mdevice(F) 19 June 1992 mdevice(F) Name mdevice - device driver module description file Description /etc/conf/cf.d/mdevice is a one-line description of each device driver and configurable software module in the system (except for file system types, see mfsys(FP)). Each line in mdevice represents the Master file component from a Driver Software Package (DSP) which is either delivered with the base system or installed later via idinstall(ADM). Each line contains several fields separated by spaces or tabs; these are described below. Each field must be supplied with a value or a ``-'' (dash). 1. Device name: This field is the internal name of the device or module, and may be up to 8 characters long. The first character of the name must be an alphabetic character; the others may be letters, digits, or underscores. 2. Function list: This field is a string of characters that identify driver functions that are present. Using one of the characters below requires the driver to have an entry point (function) of the type indicated. When the kernel is relinked an entry is made in the kernel switch tables for each function in the list. If no functions in the following list are supplied, the field should contain a dash. Most drivers use some or all of the following functions: I init function. Called by the system during the system boot sequence to initialize the driver or module for use. Interupts are not enabled when this function is called. o open function. Called whenever a device node associated with this driver is opened. c close function. Called whenever the last open connection to a device node associated with this driver is closed. i ioctl function. I/O control function called to issue control commands to the driver. Used by character devices only. r read function. Called to read data from a device controlled by this driver. Used by character devices only. w write function. Called to write data to a device controlled by this driver. Used by character devices only. The remaining functions in this list are likely to be used only by drivers with special requirements: h halt function. Called during system shutdown. This might be provided if, for instance, the driver needs to reset hardware in preparation for a warm boot. p poll function. Called once every system clock-tick. This might be required (for instance) for a device which loses interrupts and needs to be re-primed periodically. E kenter function. Called by the system whenever kernel mode is entered. Provided for drivers which have specific actions to carry out whenever this happens. X kexit function. Called on exit from kernel mode to user mode. Provided for drivers which have specific actions to carry out when this happens. e exec function. Called when a process with an open (or previ- ously open) connection to this device, using this driver, issues an exec(S) system call. Provided for devices which must perform specific actions when this situation arises. s start function. Secondary initialization function called by the system late in the system boot sequence. Provided for drivers which have initialization functions which must be deferred until after system interrupts have been enabled. P pminit function. Pre-main initialization function called by the system very early in the system initialization process. Pro- vided for drivers which need to be initialized early. Normally this function is used by a kernel debugger so that it is avail- able to the user as early as possible. x exit function. Called when a process with a previously open connection to this device exits. Provided for devices which must perform specific actions when this situation arises. S swtch function. Called by the system whenever a process context switch occurs. This is provided for drivers which have specific actions to carry out whenever a context switch occurs. Note that if the device is a 'block' type device (see field 3 below), a strategy routine and a print routine are mandatory. 3. Characteristics of driver: This field contains a set of characters that indicate the characteristics of the driver. If none of the characters below apply, the field should contain a dash. The legal characters for this field are: a The driver is installed automatically. b The device is a 'block' device. c The device is a 'character' device. d The device can accept 32-bit addresses for DMA transfer, but cannot directly access addresses above 16Mb (see ``x'' below). h The device is an SCSI host adapter. i The device driver is installable. n The driver is not installable. o This device may have only one sdevice(F) entry. p The device is an SCSI peripheral. r This device is required in all configurations of the kernel. This option is intended for drivers delivered with the base system only. Device nodes (special files in the /dev direc- tory), once made for this device, are never removed. See idmknod(ADM). s Suppress device count field. t The device is a ttym and has a tty table. x The device can perform DMA to addresses above 16Mb without the need for memory windowing support from dedicated hardware and the kernel. This is only valid if the ``d'' characteristic is also set. C The device is a scatter/gather device which performs cluster I/O requests. (Block devices only.) D This option indicates that the device driver can share its DMA channel. G The interrupt handler specified in the sdevice(F) entry is not installed, but is checked for conflicts with other devices. This is used when you wish to associate a device with a specif- ic device group. H This device driver controls hardware. This option distin- guishes drivers that support hardware from those that are entirely software (pseudo-devices). I Ignore pack.d directory. This option prevents the system from looking for driver components when relinking the kernel. This option is used when the functions associated with this driver name are actually included in another driver. M This driver defines a range of extended minor device numbers for a driver already defined in a preceding entry. This also causes the Minumum and Maximum fields to be interpreted dif- ferently. (See fields 7 and 8 below.) N No Driver.o or space.c file. O This option indicates that the IOA range (sdevice(F) columns 7 and 8) of this device may overlap that of another device, which must also have the 'O' characteristic. S This device driver is a STREAMS module. Z This driver may have multiple entries in the mdevice file, with different major numbers. 4. Handler prefix: This field contains a character string which is used as a prefix for all the externally-known handler routines asso- ciated with this driver. The string may be up to 4 characters long. 5. Block major number: This field should be set to zero in a DSP Master file. If the device is a 'block' type device, a value will be assigned by idinstall during installation. 6. Character major number: This field should be set to zero in a DSP Master file. If the device is a 'character' type device (or 'STREAMS' type), a value will be assigned by idinstall during in- stallation. 7. Minimum units: This field is an integer specifying the minimum num- ber of these devices that can be specified in the sdevice(F) file. If ``M'' appears in the characteristics field, this is the base major number of the driver to which the extended minor numbers apply (i.e. BASE major). 8. Maximum units: This field specifies the maximum number of these de- vices that may be specified in the sdevice(F) file. It contains an integer. If ``M'' appears in the characteristics field, this is the offset at which the range of the extended minor numbers begin (i.e. OFFSET). Must be a multiple of 256. 9. DMA channel: This field contains an integer that specifies the DMA channel to be used by this device. If the device does not use DMA, place a ``-1'' in this field. Note that more than one device can share a DMA channel provided that each sharing device has the ``D'' characteristic set. Specifying STREAMS modules and device STREAMS modules and devices are treated in a slightly different way from other drivers in all UNIX systems, and their configuration reflects this difference. To specify a STREAMS device driver, its mdevice entry should contain both an ``S'' and a ``c'' in the ``characteristics'' field (see field 3. above). This indicates that it is a STREAMS device and that it requires an entry in the UNIX kernel's cdevsw table, where STREAMS de- vices are normally configured into the system. A STREAMS module that is not a device driver, such as a line discipline module, requires an ``S'' in the ``characteristics'' field of its mdevice file entry, but should not include a ``c'', as a device driver does. See also configure(ADM), idbuild(ADM), idinstall(ADM), mfsys(FP), sdevice(F) Device Driver Writer's Guide