Device Driver Conventions

There are several conventions one should be aware of when writing device drivers, pertaining to:

• Driver Names

• Driver Information

• Message Logging

• Use of ASSERT Macro

Driver Names

Driver names in the Driver Framework must follow the following conventions, in this order:

1. driver vendor name

2. bottom interface used by driver

3. chip supported by driver

4. top interface used by driver

For example:

sun:bus-ns16550-uart
sun:pci-cheerio-ether

where "sun" is the vendor name, "bus" and "pci" are the bottom interfaces used, "ns16550" and "cheerio" are the chips supported, and "uart" and "ether" are the top interfaces.

In the case of a driver providing several top interfaces, these interfaces are specified within parentheses, separated by commas:

sun:bus-mc146818-(rtc, timer)

Driver Information

Driver information is stored in the driver registry record, using the drv_info field. This info string must be built after the driver description and source management version information of the driver module.

For example:

NS16x50 UART driver [#ident \"@(#)ns16550.c 1.16 99/02/16 SMI\"]

Message Logging

Because messages are processed through the ChorusOS operating system, drivers must never use sysLog or printf directly to display messages. The ChorusOS operating system provides the following macros to handle message logging:

DKI_MSG((format, ...))

typically does: printf

DKI_WARN((format, ...))

typically does: printf + syslog

DKI_PANIC((format, ...))

typically does: printf + syslog + callDebug

DKI_ERR((format, ... ))

typically does: printff + syslog

Moreover, message format conventions are as follows:

DKI_MSG

"<name>: <message>"

DKI_WARN

"<name>: warning -- <message>"

DKI_ERR

"<name>: error -- <message>"

DKI_PANIC

"<name>: panic -- <message>"

where <name> is either:

• the name of the driver (if the message is not related to a particular instance of the driver)

• the path of the device in the device tree (if the message is related to a driver instance)

  ---

  Note -

  The dtreePathLeng() and dtreePathGet() calls can be used to get the device tree path for a particular instance.

  ---

Use of ASSERT Macro

ASSERT is a macro (fully defined in util/macro.h) which should only be used in situations which should not logically be possible in the construction of the software.

Situations such as critical resource allocation failures should be handled with the DKI_ERR macro instead.

ASSERT is enabled at compile time only, with

#define DEBUG