This section defines the contents of the Driver Software Package (DSP), and Appendix E contains an example package. Each DSP must have two
"names." One is the "external name" that the user will see when the pack-age is installed. The second is an "internal name" that the kernel uses to identify the device. More information is provided about these names below and in the section "Driver Development Procedures. "
The DSP is to be delivered on an installation floppy diskette, as described in Chapter 2 of this Guide. There you will find general descriptions of the files and information on ordering and contents. The driver writer must prepare a DSP consisting of the files (termed modules) described in the fol-lowing sections.
Driver.o (required)
This is the driver object module that is to be configured into the kernel.
This object module must be compiled using the native C Programming
Language Utilities (CPLU) delivered in the C Software Development Set of the UNIX System V /386 Software Development Set. The section "Device Driver Development Methodology" provides procedures for coding, compiling, and debugging the driver object module.
Master (required)
This module contains a one-line description of the device being installed.
This module will be added to the ID mdevice file. The syntax of this line appears in the mdevice(4) manual page in Appendix A of this document and in the Programmer's Reference Manual.
Fields 6 and 7 of the Master entry should be set to zero. These are the driver's character and block and character major device numbers. These values are set by ID when the Master entry is added to the kernel configura-tion.
System (required)
When a DSP is installed, this module is added to the files which will be included in the kernel the next time the system is rebuilt. During reconfigura-tion, the System modules for each device are concatenated together to form the ID file sdevice. The syntax of this line appears in the sdevice(4) manual
3·54 ISDG
page in Appendix A of this document and in the Programmer's Reference Manual.
Space.c (optional)
The file /usr/inc1ude/sys/space.h traditionally contains data structure declarations required by the kernel and device drivers. The amount of storage allocated for each driver data structure is dependent on the number of sub-devices configured for a particular device. For UNIX System V /386, each driver can have its own Space.c file containing configuration dependent-data structures.
As an alternative to providing Space.c, the driver writer could preallocate data in the driver, eliminating the need for this file. This is useful when
• the amount of storage required by the driver is static
• the difference in storage between the minimum and maximum number of subdevices that can be configured for that device is small
Node (optional)
This file is used to generate the device's "special files" in the / dev direc-tory on the next reboot after the system has been reconfigured. Node con-tains one line for each node that is to be inserted in /dev. The fields can be separated by spaces. The syntax of this line is as follows:
Field 1: OSP internal name
Field 2: name of node to be inserted
Field 3: 'b' or 'c' (block or character device) Field 4: m:iIx>r device :number
example
OSP-internal-name nodeO c 0 OSP-internal-name node 1 c 1
See the idmknod(lM) manual page in Appendix A of this document and in the User's/System Administrator's Reference Manual.
DEVICE DRIVERS 3·55
Init (optional)
Some drivers require entries in /etc/inittab to make them operational.
An inittab entry is of the following form (see inittab(4) in the Programmer's Reference Manual):
id:rstate:actian:process
Each line of the init module must be of the format action:process, or rstate:action:process. The id and rstate field will be generated by ID (if your entry has an rstate field it will be used; otherwise, "2" will be used). The new inittab entries will be added to /etc/inittab on the next reboot after the system has been reconfigured. For more information on the init module for-mat, see the idmkinit(lM) manual page in Appendix A of this document and in the User'sjSystem Administrator's Reference Manual.
Rc (optional)
This module is an initialization file that is executed when the system is booted. The new Rc file will be placed in the directory /etc/idrc.d on the next reboot after the system has been reconfigured and will be invoked on every system reboot thereafter upon entering init level 2 (see the init(lM) manual page in the User'sjSystem Administrator's Reference Manual). When creating this module the file permissions must allow execution by root.
Shutdown (optional)
This file is executed when the system is shut down. The new shutdown file will be placed in the directory /etc/idsd.d on the next reboot after the system has been reconfigured and will be invoked on every system shutdown thereafter upon entering init state O. When creating this module the file per-missions must allow execution by root.
Name (required)
This module contains the "external DSP name," which is the name displayed by the displaypkg command. The package name should be fairly specific to reduce the chance of conflicting with other packages.
3·56 ISDG
If the DSP contains just a device driver, then the name Device~ame
Driver might be a good choice. If, however, the driver is part of a package that includes a driver, communication protocols, and user commands to access a network, for example, then perhaps the word "driver" shouldn't even be used. Something like Net-name Communications Package may be more appropriate.
The internal name should be derived from the external name for naming jdev entries and for use by the Install script.
The internal name must be the same as the name appearing in field one of the Master module. The internal name must uniquely identify the driver and be eight characters or less. As an example, the Phone Manager Device Driver might have an internal name of phone. See the section "Driver Development Procedures" for elaboration of the internal name.
Files ,required)
The DSP may contain commands, programs, or data files in addition to the ones listed as ID modules directly. It is the responsibility of the Install module to install or make use of these files. The Files module must contain a full path name of where these additional files are to be installed.
Install ,required) This module
• Installs all of the files that are listed in the module Files. It does not install any of the ID modules.
• Invokes the ID command idinstall with the -a option and passes it one argument, the internal DSP name. This will move the contents of the DSP to the proper directories.
• Invokes the ID command idbuild.
Remove ,required) This module
• Removes any commands, programs, or data files installed by the install module.
DEVICE DRIVERS 3·57
• Calls the idinstall command with the -d option and passes it one argument, the internal DSP name. This will remove the DSP modules.
• Invokes the ID command idbuild.
Size (required)
The contents of the Size file should be the number of blocks required to install the DSP. A block is defined as 512 bytes. This file is to be used by the installpkg program to determine if enough free disk space is available to add the driver package. At installation time, if insufficient disk space exists to install the package, the user will be alerted and the installation aborted. In addition to the space required to store the user commands and files the pack-age is to install, a large amount of temporary space is required to reconfigure the kernel. The space required in the root (" I") file system can be roughly calculated as the size of the current UNIX Operating System kernel image (funix) plus 400 blocks. If the system has a lusr file system, approximately 400 blocks should be specified. An example of a Size file is as follows (assuming a typical lunix is 1000 blocks):
ROaI'=1400 USR=400.
Mfsys (optional) and Sfsys (optional)
These files are new to UNIX System V 1386 Release 3.2 and specify the addition of file system types to the UNIX Operating System kernel. Addi-tional information can be obtained from the mfsys(4) and sfsys(4) manual pages in Appendix A of this document and in the Programmer's Reference Manual.
Summary of Modules
Table 1 lists the modules that may appear in a DSP. The only restriction on ordering the files is that the Size file must be on the first floppy diskette of the DSP. See the section "Special Installation Files" in Chapter 2 for more information on installation packaging.
3-58 ISDG
Module
Disk space requirements to install DSP DSP name
Installation script Remove script
Target paths for commands/data files Driver object file
Master file entry System file entry
Driver space allocation file Special file entries in jdev jetc/inittab entries
Executed when entering init-Ievel 2 Executed when entering init-Ievel 0 File system type master data File system type system data
Table 1. Components of Driver Software Package