Making hardware specifications 'firmware friendly'

Consideration is given to optimizing the usefulness of a document targeted for electronic distribution as well as for specifications distributed as paper documents.

Document Organization
First, the specification should be organized in a logical manner. Hardware engineers, for the past two decades, have been trained to develop their designs in a top-down manner -- in other words, they determine the general operation of an IC before developing detailed designs of its parts. As each level of this design hierarchy is developed, the descriptions of the parts are then used to develop each part in a similar manner. Firmware engineers, in order to be efficient in their design, need this same top-down understanding of the IC in order to develop code that controls all parts of the system in an efficient, coordinated manner.

Specifications should be written in a hierarchal, top-down manner. First describe what the chip does, then describe how each major block contributes to this o peration. Next describe each major block in terms of its own logic blocks. Logic blocks should be divided and subdivided in the specification to the point where the registers unique to a single logic block can be treated together as a unit, but where no register directly affects an outside block of logic. (Note that this also implies a design practice where two distinct logic blocks do not share registers.)

The descriptive text in the specification should call out registers and register bit-fields as needed, but need not necessarily provide an exhaustive list of registers and bit fields. Bit field references should always indicate the register containing that bit field in the text. This can be done by simply adding the register name in the text or by adding a cross-reference. This is necessary because there is generally no reference list, table, or index of bit fields. Thus, chasing down an individual bit field name in a paper document can be an hours-long, tedious task.

Detailed register desc riptions are a major reference tool for firmware developers. These should exist in a document section that is distinct from the functional circuit descriptions. Every register in the IC should be assigned a single-word acronym in the specification. This should be used throughout the document instead of longer, more descriptive names. This greatly increases the usability of the document to firmware engineers, who use the acronym to reference the register in their software.

Memory and register maps should supply a relative address location, a name, and the acronym for each register and memory block in the IC. For a more useful document, two lists can be supplied. The traditional memory map lists all elements in numerical order by address. The second list is in alphabetical order by acronym. This allows the user to find the memory mapped element by acronym to learn the address of the element. Both of these lists are more useful if they contain cross-references to the section in the specification where the register (or other memory mapped element) is described in detail.

Experienced firmware engineers soon become experts at custom-tab indexing. By the time a firmware development project is completed the hardware specification is loaded with sticky-notes and tape-flags indicating where a vital piece of information is located. This is the result of cumulative days of time spent searching the document for an explanation of an item referenced in some part of the specification.

Using the cross-referencing and indexing tools of today's documentation tools can render this tedious research unnecessary. Anyone who has used a well-designed GNU "info" document can attest to the usefulness of cross-references. If the document is to be distributed or used in an electronic format, the cross-references and index entries should be hot-links.

Divide and sub-divide the circuit description text along the lines of the hardware architecture with headers that are displayed in the Table of Contents. All major s ections should begin on the odd-numbered (right-hand side) pages; chapters or major subsections should begin on a new page.

If any tables or figures are used, supply tables of tables and figures. These can be a single table or (better for large documents) a listing for tables and a separate listing for figures. Separate listings for certain kinds of often-used tables may increase the efficiency of the document even further.

Document Contents
Every logic block description, whether at the chip level or the lowest sublevel in the design hierarchy, should answer the following descriptions:

• What does it do?
• How do I make it do that?
• What errors or exceptions can occur?
• How do I handle each error and exception?
• What is the reset state?

You can even use a form of these questions as headers for subsections of the logic block description. Note that descriptions of higher level blocks should answer these questions at the same level of detail as the block descrip tion. For example, a high level logic description should explain "How do I make it do that?" in terms of the lower level logic blocks:

How to Cause BigBlockOne to do Something Neat:


First program Block A to generate XYZ data based upon the inputs from blocks B and C. Block B should then be set up to handle the inputs from Blocks C, D and inputs In1 -- In8. Blocks C should then be configured to ...

Errors and Exceptions Originating from BigBlockOne:


The descriptions of lower level blocks will be in terms of their own lower level blocks until the register level description is reached:

How to Cause BlockA to do Something Really Neat:


Program registers R1 and R2 to control the reactions to inputs from Block B. Register R3 should be set to control inputs from Block C...

Errors and Exceptions Originating from BlockA:


The BigBadError exception can occur if the data from Block B is wrong. When this error occurs register R4 should b e read to determine the source of the problem. Refer to the R4 register description for information on how to handle each source.

All experienced firmware engineers have stories of a neat part that was an excellent design except that, whenever a certain exception condition occurred, the only way to recover was to reset the part. An added benefit of this documentation effort is that the hardware designers will have considered these possible exceptions and exception handling issues prior to their design. This may reduce the need for respins of the part due to a critical exception handling problem that was overlooked during hardware design.

Each register description should include a picture of the register with all bit-fields clearly delineated. The picture should also indicate the "endianness" of the register. This picture is more important than listing the bit positions in the text description of each bit field. The register pictures are reference material and the effects of anything that improves the efficiency of researching the registers will be multiplied due to number of times this part of the document is used.

Figure 1 -- Register picture with bitfields

Figure 2 -- Table of content entries for register descriptions

Document Formatting

The formatting of the specification document can be as important as the contents when considered with respect to its use as a learning tool and as a reference. Any formatting technique that increases the efficiency of searching the document should be considered -- the "look and feel" should be of only secondary importance to this concern.

Use mirror margins to allow extra space on the inside margin of paper documents. This makes the document easier to use whether delivered bound or loose -- the user is going to bind the document anyway, and holes in the paper that obfuscate text are irritating at best and can be disastrous.

The headers and footers should contain the following information:

• Title of current section of the text should be on the outside corner of the page. This brings up the question of "What title?" If a 400 page document is divided into 3 major sections which are further divided into chapters and subsections, the chapter titles in the header may be worth more than the major section titles. It may be useful to list both a major section and a chapter header.
• Current page number should be on the outside corner also. For example, if the title is in the header the page number should be in the footer and vise versa. This should be an absolute page number. A relative page number (relative to the start of the current section) may also be included elsewhere if desired, but the absolute page number is the number that will correspond to the page number in the electronic document. Even if only paper versions of the document are distributed there is a good chance tha t the manufacturer's support personnel are using an electronic version.
• The revision number for the document. Whenever a customer calls the manufacturer for support, one of the first actions of the support person will be to obtain the document revision number; make this easy to find and to understand.

Use a picture whenever possible to explain a concept or describe a function or feature. Good pictures are the best possible reference tool; they are easy to find in the document, hopefully easy to read, and easy to remember.

Use charts, tables, and lists instead of general text to call out facts whenever possible. Like pictures, these are easier to find, more efficient to reference later, and easier to remember than general text. All pictures charts, lists, and tables should be accompanied by a caption and should appear in some sort of table of contents list.

Use a font that clearly differentiates between the characters one, small 'L', and capital 'i'. The font of choice should also differentiate between small and capital 'o' and a zero. It is also useful to avoid names of circuit elements that place these characters next to each other in a word.

A list of the more common fonts with examples of the problem characters is given in Figure 3.

Figure 3 -- Font comparisons

It is also important to choose an easy-to-read font. The easier it is to read a font, the less fatigue will be suffered by the reader. It may be useful or necessary to use multiple fonts in the document. Use one easy-to-read font for general text and a different font the delineates the various similar characters where necessary -- such as when describing bit field values or I/O logic levels.

Use a two-column format for text. This is easier to read and reference by the user. This is also a more efficient use of paper, leaving less empty line space at the end of paragraphs. This also helps present figures and tables as easier to find due to the need for these to cross column boundaries.

Sources

• Hardware Design Guidelines of the Fort Collins Product Development department of LSI Logic Corporation, Fort Collins, CO.
• "The Embedded Muse", an email newsletter distributed by Jack Ganssle (jack@ganssle.com).
• GNU products are distributed by the Free Software Foundation of Cambridge, MA.

David Fechser is a staff engineer working for the Systems Verification group of the Storage Products Division at LSI Logic Corp. in Fort Collins, Colorado.