Posts Tagged ‘collaboration’

The (not so) Exciting World of Documentation

Friday, February 25th, 2011 Gary Stringham

In a survey I conducted of several firmware engineers, lack of good documentation of hardware was the number one complaint. It is because firmware engineers so heavily rely on the hardware documentation to correctly do their job. Some of the engineers said that wrong documentation is worse than no documentation because of the wasted time producing incorrect code.

It is a problem because one group (hardware engineers in this case) has to produce documentation for a different group (firmware engineers). They generally are in different physical locations, come from different engineering backgrounds, have different terminology, and have different perspectives on the end products. To overcome these differences, hardware and firmware engineers need to collaborate with each other.

Writing documentation is difficult. When I write, I understand perfectly well what I meant to say. I know and understand unwritten details and nuances that are second nature to me without realizing that my reader might not. I’m reminded of that when I have someone else review my writing and they bring up missing and incomplete sections.

While both hardware and firmware engineers should be actively involved in the collaboration, it is primarily the hardware engineers who do the majority of the work with documentation and design. When ready for review, they should give the documentation to firmware engineers for review. Firmware engineers should, in a timely fashion, review the documentation and provide hardware engineers with comments on incomplete, unclear, and incorrect sections and any issues that they might discover. Firmware review of hardware documentation should be part of the checklist for milestone completions.

Best Practice: Give hardware documentation to firmware engineers to review and respond with comments and issues.

Before firmware engineers can understand the specifics of how the block works, they need to have an overall picture of the purpose and operations of the block. If they focus too much on details, specific registers, and bits, it is hard to see what the overall operation should be. Not having a high-level description can be compared to seeing a box full of nuts, bolts, springs, levers, and other parts and not being able to recognize that it is supposed to be a toaster. But by first stepping back and looking at a high-level description of the toaster as a whole and understanding how it toasts bread, then it is easier to understand how to assemble the components to make a functional toaster.

The same concept applies to a block on the chip. Firmware engineers need to see and understand the big picture of how that block should operate, within itself and in conjunction with other parts of the system, before they can understand the detailed registers and bits.

Best Practice: Produce and have reviewed a high-level description of the block that describes its theory of operation, its function in the system, and its parts.

In addition to the high-level documentation, a detailed documentation is needed and should contain both a reference section and a tutorial section. A reference section has a list of all registers in the block, typically in address order. It gives details for each register and the bits and/or bit fields in that register. The tutorial section describes when, how, and in what order to use those registers and bits to carry out a task.

An example of reference documentations are the UNIX man pages (and Linux and other variants) which contains all commands and functions in alphabetical order, each one describing their respective options in order. On the other hand, the well-known book by Kernighan and Ritchie, “The C Programming Language,” is written in tutorial style, explaining how to do various tasks, using necessary C constructs to accomplish the tasks.

Best Practice: Provide both a reference section and a tutorial section in the detailed documentation of a block.

Until the next writing…

Early Hardware/Firmware Collaboration

Saturday, March 13th, 2010 Gary Stringham

A few years ago, I was invited to a high-level design review of a new SoC. The proposed design contained an I/O block that needed features added. I successfully convinced them to replace that block instead with an existing block that had the needed features, had seen silicon, and had a functional driver. Months later on real hardware, bringing up the driver for that block was painless.

This incident illustrates the benefits of early collaboration between hardware and firmware engineers. All too often, though, the early phases of embedded systems projects consist solely of hardware engineers working on the design of the hardware without firmware engineers involved. This practice makes it difficult to produce designs flexible and robust enough to support features that also rely on firmware. By working together, however, hardware and firmware engineers can avoid these problems.

Early collaboration of hardware and firmware engineers (both formally and informally) gets both groups talking to each other. Each group has a different perspective of their respective needs and of the embedded system. Here are some benefits you can expect:

  • Reviewing the system requirements together helps reconcile differences and produce a more comprehensive view of the requirements. This helps assure the design meets the requirements.
  • Some features can be implemented in either hardware or firmware. Working together, engineers can discuss where the line should be drawn between hardware and firmware, taking into account trade-offs such as performance, flexibility and ease of implementation.
  • Collaboration ensures the design of the hardware/firmware interface leads to a smoother integration of hardware and firmware into the embedded product as a whole.

Hardware and firmware engineers reap these and other benefits when they collaborate early.

Best Practice: Start collaboration between hardware and firmware engineers during the initial hardware high-level design phase.

Formal hardware development processes typically include checkpoints with formal reviews and signoffs by key personnel, assuring successful completion of all criteria. Firmware participation in the hardware checkpoints encourages hardware and firmware engineers to review the documentation together and jointly resolve any issues they uncover.

Best Practice: Include firmware representation in reviews and signoffs of hardware checkpoints throughout the life cycle.

Until our next collaboration…