BSP Developer's Guide

VxWorks 5.5
BSP Developer’s Guide
Documentation and Standards
Describe the entire chip with all of its features and operating modes. Code
maintainers need to determine the basis of the chip without resorting to a complete
library search. Most manufacturers now have their data sheets on the World Wide
Web. This makes finding data sheets easier, but a good one paragraph summary of
the chip can save a lot of time spent searching and reading.
Describe the driver modes and limitations. The module description should be an
introduction to both the chip and the driver.
Follow the Wind River coding standard. This enhances readability and eases
maintenance. Have a technical writer review the documentation for clarity and
grammar.
Do a formal code review to check for adherence to the coding standards. There is
no better way to insure quality and readability than to have someone else look at
your code.
Concentrate on documenting how the device and the driver work together. In
addition to missing documentation, there is the problem of useless documentation.
It is not unusual to see documentation that is trivial and redundant. A typical
example would be:
x = 0; /* clear x */
fooReset (&myFoo); /* reset myFoo */
These are not unusual examples. Assembly level programmers are used to
documenting each line of code. In the C era, programmers tend to write comments
preceding the code. The line by line comment model tends to have more useless
documentation. Programmers are warned to avoid the problems with line by line
running comments.
Another point to consider is that the documentation that goes into the generated
man pages is usually more important than comments in the body of the code. This
is information for the user. It must be accurate and clear. Done right, the reader will
understand what the code intends to accomplish. It becomes much easier to spot
problems in code when you understand its goals clearly.
Documentation should tell the engineer how to integrate the driver into the overall
BSP package. All special external routines should be documented. Instructions on
initializing the driver should be included. Actual examples of BSP integration code
would be very helpful.
96