Documentation

Proper documentation is essential for drivers being productized.

Each driver should be accompanied by the following information.

• Supported hardware devices, including version numbers and hardware configuration information.

• All driver-specific ioctl commands.

• Any special information required to install or administer the device, including recommendations for tuning parameters that are associated with the device.

• Text, explanation, and suggested responses to any error messages that the driver may produce. For guidelines about error messages in drivers, see ``Error handling''.

One way to provide this information is to create a Section 7 or Section HW manual page that installs with the driver software.

Drivers for devices that are configured with a ScoAdmin manager (such as network and graphics adapter cards) should include relevant information in a context-sensitive file that is installed with the ODSSI tools as part of the driver installation process. See ``Creating help files for network driver configuration'' for instructions and sample files specific to MDI drivers.

We recommend that driver writers generate a functional specification, test plan, and test report. The discipline of writing such documents often improves the quality of the code, and the information is invaluable when maintenance work is required at a later date.