Structure

• Kernel-level drivers are usually written in the C Programming Language. Select subroutines may be written in Assembly Language to enhance performance, but Assembly Language is less portable and more difficult to maintain than standard C code and should be used selectively.

  It is possible to implement drivers in the C++ language. For information about writing C++ drivers, see ``Writing drivers in C++''.

• C language drivers should be written using ANSI C syntax, or Kernighan and Ritchie C with ANSI style declarations and prototypes. ANSI style declarations and prototypes greatly enhance the robustness and portability of the driver code.

  Note that, for ODDI drivers that run on SCO OpenServer 5, the space.c files are compiled with an old compiler that does not understand ANSI C syntax, so the space.c files must be coded with Kernighan and Ritchie C.

  Drivers should not use Microsoft C extensions such as far and PASCAL.

• The source for each driver should follow a consistent code indentation convention that emphasizes rather than obscures the logic. Code that follows no discernible convention is difficult to read and maintain. When modifying an existing driver source file, follow the indentation style that is in place or modify the indentation style for the entire source.
  

• All drivers within a given class (such as network drivers, SDI, and so forth) perform the same functions and many are based on the same sample source code, so the potential for symbol conflict between two drivers is great. To prevent this, the following restrictions are placed on drivers:

  • All externally visible driver symbols, including global variables, structure names, and driver subroutines should be prefixed with the driver's prefix(D1). This makes them easier to identify in the kernel and greatly reduces the risk of having two entities with the same name from different drivers.

    The one exception to this rule is the DDI _load(D2) and _unload(D2) entry point routines which, beginning with DDI version 8, are called without a prefix.

    For information about adhering to this guideline in C++ drivers, see ``Driver name space issues''.
    

  • Use static variables rather than extern variables as much as possible after the driver is debugged. This applies to structures, subordinate (not entry-point) routines, and defined values.

    Note that DDI 8 drivers have less need for externally visible symbols than drivers written for earlier DDI versions and ODDI. If your DDI 8 driver is based on earlier code, look for symbols that no longer need to be global.

    For resources that should be visible for debugging but static at other times, DDI drivers can code the declaration as follows:

       STATIC int my_variable;
    

    The sys/debug.h header file includes code that will make this variable visible for debugging (when -DDEBUG is set) but static at other times.

    SCO OpenServer 5 ODDI drivers can implement similar functionality by including code such as the following at the top of the driver source code:

       #ifdef DEBUG
       #   define STATIC
       #else
       #   define STATIC static
       #endif
    

• Each SVR5 driver should use one DDI $interface version and one of any other interfaced version such as MDI or SDI. Customer drivers must never use $interface base; this is reserved for drivers developed within SCO. Customer drivers should not $interface nonconforming. See ``DDI interface versioning''.

• Use only the kernel functions documented in the Section D3 manual page sections for the $interface(s) version you are using. In future SVR5 releases, drivers that use undocumented kernel functions may not link.

  SCO OpenServer 5 does not enforce interface conformance as rigorously, but using obsolete or private functions can result in less robust driver code that is harder to port to future platforms.

  Writing specialized routines to provide the same functionality as standard kernel functions significantly reduces the possibility that the driver will work in future releases of the operating system. Source code that has private copies of function prototypes for standard functions may also have porting problems; drivers should instead use the function prototypes that are included in the system header files.

• Do not view or modify kernel structures except in the explicit ways defined in this documentation. In general, only interface-specific structures can be viewed or modified except with the defined functions.

  One exception to this is that ODDI drivers may view and modify the u.u_error and b_error structure members directly.

• Use system-derived data types such as size_t rather than data types you define yourself as much as possible, and avoid writing code that assumes that system-derived data types are a specific size. This will make it must easier to modify the driver for future changes such as the change to the 64-bit environment.

• Do not #include the inline.h header file in DDI source code. A driver that calls inline.h is exposed to platform-specific versions of DDI functions such as inb(D3) and outb(D3), and so becomes much less portable. The inline.h header file has been removed from SCO OpenServer 5.

• Use ASSERT(D3) or ASSERT(D3oddi) to check that the value of variables and structure members is correct at various stages of execution. ASSERT( ) evaluates a simple expression and, if it is not true, panics the system at that point so you can use a debugger (scodb or kdb) or the crash and crash(ADM) utility to analyze the kernel. ASSERT( ) is ignored except when the driver is compiled with the -DDEBUG flag. Note that the <sys/debug.h> header file must be #included to activate ASSERT( ).

• Hardware drivers will be easier to port and maintain if you use a layered structure: separate the higher-level protocol functionality from the low-level, machine-dependent routines. The high-level sections can usually be ported quite easily, leaving only the low-level sections to be rewritten. If you intersperse the high-level and low-level functionality, all code may need to be rewritten to run on another machine or with a different device.

• Use #define values instead of hard-coded values. In most cases, these should be defined in the header file rather than in the driver code itself, to make them accessible to user-level programs as well as the driver. Using #define values makes it easier to modify the value when necessary as well as clarifying why a certain value is being used.

• Code should be rigorous in setting, returning, and checking return values.

• Code should compile with no Error or Warning messages when compiled at the default warning level. When the compiler is set to the most verbose level, there should be few if any Warning messages.

• All code should pass lint with no errors. You may also want to download the g64lint utility from the SCO web site to check whether your driver is 64-bit clean.