btld(F) 06 January 1993 btld(F) Name btld - contents of a boot time loadable device driver disk Disk contents /install/INSTALL /pkg/install/btld [ /pkg/install/drivers ] [ /pkg/install/pkg.name ] [ /pkg/install/copyright ] [ /pkg/install/preinstall ] [ /pkg/install/postinstall ] [ /pkg/install/bootstring ] [ /pkg/new/... ] [ .../xnamex/Master ] [ .../xnamex/System ] [ .../xnamex/Bootload ] files filename ... tune field symbol size ... patch symbol size value ... [ .../xnamex/Driver.o ] [ .../xnamex/Space.o ] [ .../xnamex/Space.c ] [ .../xnamex/Stubs.c ] [ .../xnamex/Node ] [ .../xnamex/Inittab ] [ .../xnamex/Rc ] [ .../xnamex/Shutdown ] Description boot(HW) can link-edit additional device drivers into the UNIX kernel being booted. These modules are known generically as ``Boot Time Loadable Drivers'' or BTLDs. The link-edited modules must be arranged, usually on a floppy disk, in a series of ``packages''. Each package (pkg) contains one or more drivers. There can be more than one package on a disk, but each package must be fully contained on one disk. Each disk must be a mountable filesystem of a type recognized by both boot and installpkg(ADM); these include XENIX, S51K, and AFS. Each pack- age has its own directory hierarchy /pkg in this filesystem. Optional and required files on a BTLD disk are described below. Note that optional files are indicated with [square brackets] in the preceding ``Disk contents'' section. /install/INSTALL This file must exist and be an executable Bourne shell (sh(C)) script. It is run by installpkg with three arguments: device the name of block special floppy diskette device (for example, /dev/fd096ds15) rootdir the floppy filesystem's root directory prompt a string describing device (useful when prompting) There can only be one INSTALL script per diskette. It typically just invokes btldinstall(ADM): exec /etc/btldinstall "$2" btldinstall asks which packages on this diskette are to be installed, and then adds the appropriate drivers from the requested packages to the system's Link Kit (/etc/conf/...). /pkg/install/btld If this file exists, then both boot and btldinstall assume /pkg is a boot-time-loadable package hierarchy. This file contains, one per line, the pathnames of the directories containing each driver which boot is to link-edit into the kernel. If this file does not exist, both boot and btldinstall will ignore the entire /pkg hierarchy. Each driver must have its own directory. The basename(C) of each such directory must be the same as the ``internal name'' (xnamex) of the driver as defined by column 1 of mdevice(F). Conventionally, each driver's directory is named /pkg/driver/xnamex, and that is what is specified in the btld file. However, any pathname ending in the driver's internal name xnamex is acceptable. /pkg/install/drivers If this file exists, then it contains, one per line, the pathnames of the directories containing each driver which btldinstall is to add to the system's Link Kit. The basename of each listed directory must be the same as the internal name of the driver. The directories listed in this file do not have to be the same as those listed in /pkg/install/btld. If this file is missing, btldinstall does not install any drivers from this package into the Link Kit. /pkg/install/pkg.name An optional one-line description of this package. This file, if it exists, will be installed by btldinstall as /usr/options/pkg.name. Both btldinstall and displaypkg(ADM) list the contents of this file. /pkg/install/copyright An optional Bourne shell script run by btldinstall to print out copyright and licensing information for this package. If this script exists, it must have execute permission. /pkg/install/preinstall An optional Bourne shell script run by btldinstall prior to installing the drivers listed in /pkg/install/drivers. This script might be used to check the system version, or to check for the presence of optional soft- ware packages. /pkg/install/postinstall An optional Bourne shell script run by btldinstall after installing both the drivers listed in /pkg/install/drivers and the /pkg/new hierarchy. Typically, this script runs fixperm(ADM) to adjust the ownership and per- missions of the installed files. /pkg/install/bootstring If this file exists, the first non-empty line not starting with an aster- isk (*) or hash (#) is appended to the bootstring passed by boot to the booted UNIX kernel. For example, bootstring might contain: hd=xnamex to specify that boot-linked driver xnamex (part of this package) is the primary hard disk. /pkg/new/... An optional hierarchy installed by btldinstall as if new were /. The owners, permissions, and contents of all files and directories in this hierarchy are copied. This is typically used to install a mkdev(ADM) script in /usr/lib/mkdev, a fixperm-list in /etc/perms, plus other assorted commands and data files specific to this package as required. However, drivers should not be added to the Link Kit (/etc/conf/...) in this manner. .../xnamex Directory containing the files specific to the driver whose internal name is xnamex. Conventionally, this directory is /pkg/driver/xnamex, but the /pkg/install/btld and /pkg/install/drivers files may specify otherwise. This directory should not be in the /pkg/new hierarchy. .../xnamex/Master File containing the mdevice(F) entries for driver xnamex. If this ``driver'' is listed in /pkg/install/drivers, then this file must exist. The lines dealing with driver xnamex will be extracted and added to the system's mdevice file by idinstall(ADM) when run by btldinstall. If this ``driver'' is listed in /pkg/install/btld and really is a device driver (that is, if it must have entries added to the various kernel dispatch tables such as bdevsw), then this file should exist. For the first xnamex entry only, the boot link-editor adds appropriate entries to the indicated dispatch tables. Only some characteristics (mdevice column 3) and function tables (mdevice column 2) are recognized: _________________________________________________________________________ Characteristic Description _________________________________________________________________________ b Block device driver c Character device driver S STREAMS device driver G Check but do not install the interrupt handler t The device is a tty (character devices only) C Scatter/gather (block devices only) _________________________________________________________________________ Function Description _________________________________________________________________________ o open routine (device drivers only) c close routine (device drivers only) r read routine (character devices only) w write routine (character devices only) i ioctl routine (character devices only) I init routine P pminit routine s start routine p poll routine h halt routine E kenter routine X kexit routine S swtch routine Block devices are assumed to always have open, close, strategy, and print routines. When the kernel is built, extra space is left in the appropriate tables by idconfig according to the mtune(F) parameters: _________________________________________________________________________ Function or Characteristic Parameter Description _________________________________________________________________________ b MAXBDEV At least this many block device entries c MAXCDEV At least this many character device entries I P s p h E X S EXTRANDEV Extra unoccupied entries available for boot to fill .../xnamex/System An sdevice(F) file for driver xnamex. If this ``driver'' is listed in /pkg/install/drivers, then this file must exist. It will be installed as /etc/conf/sdevice.d/xnamex by idinstall. If this ``driver'' is listed in /pkg/install/btld and uses interrupts (or tunable parameters), then this file should exist. For the first entry only (which must be for xnamex), the boot link-editor adjusts the inter- rupt dispatch tables accordingly. .../xnamex/Bootload Optional file used by boot to guide the link-editing. This file, if it exists, contains a series of directives. Each directive is one of the following keywords on a line, followed by additional lines specific to that keyword. Empty lines and lines beginning with asterisk (*) or num- ber sign (#) are ignored. The keywords include: files Subsequent lines list the names of COFF object modules boot is to link-edit into the UNIX System kernel. The default is: files Driver.o Space.o The filenames are relative to the .../xnamex directory. tune Subsequent lines list the sdevice(F) field for which the user is prompted, and the name and size of the initialized data (not BSS or text) symbol whose value is to be patched to be the user's answer: field symbol size Only 2 and 4 byte sizes are understood. The known field names include: _______________________________________________________________ mdevice/sdevice Legal range Field column (inclusive) Description _______________________________________________________________ units sdevice 3 + Number of peri- decimal pherals connected to controller vector sdevice 6 1-255 Interrupt vector decimal number * DMAchan mdevice 9 0-32767 DMA channel decimal SIOA sdevice 7 1-0x3FF Start I/O Address hexadecimal EIOA sdevice 8 SIOA-0x3FF End I/O Address hexadecimal SCMA sdevice 9 0xA0000-0xFBFFF Start Controller hexadecimal Memory Address ECMA sdevice 10 SCMA-0xFBFFF End Controller hexadecimal Memory Address + The minimum and maximum number of units are specified by columns 7 and 8 (respectively) of mdevice(F.) * Most architectures only use the first 16 or so interrupt vec- tors. Interrupt vector 0 is always reserved for the system's clock. The tuned vector overrides sdevice(F) column 6, and so is used by boot. As an example, the directive: tune SIOA xx_iobase 2 SCMA xx_ramloc 4 would cause the user to be prompted for the starting I/O address (SIOA) and starting controller memory address (SCMA). The answers supplied would be used to patch the initialized data: short xx_iobase = 0x302; long xx_ramloc = 0xC8000; The default answers (provided they are in range) are those speci- fied in the appropriate mdevice (Master) or sdevice (System) column. The C-code initialized values are not used and are always overwritten. patch Subsequent lines of the form: symbol size value cause the first size bytes of the kernel's definition of symbol to be set to value. Only 2 and 4 byte sizes are understood; value is a (optionally signed ``-'' or ``+'') hexadecimal (0x), octal (0), or decimal integer. Only initialized data -- not BSS or text -- should be patched. .../xnamex/Driver.o The driver's relocatable COFF object module. If this driver is listed in /pkg/install/drivers, (that is, if it is installed by btldinstall into the Link Kit), then this file must exist. It is installed in the Link Kit as /etc/conf/pack.d/xnamex/Driver.o by idinstall. If this driver is listed in /pkg/install/btld, and there is not a files directive in the Bootload file (to specify otherwise), then this file should exist. .../xnamex/Space.o An additional, configuration-dependent, relocatable COFF object module. If this driver is listed in /pkg/install/drivers (that is, if it is installed by btldinstall into the Link Kit), then this is installed in the Link Kit as /etc/conf/pack.d/xnamex/space.o (note the change in capi- talization) by idinstall. If this driver is listed in /pkg/install/btld and there is not a files directive in the Bootload file (to specify otherwise), then this file should exist. .../xnamex/Space.c C source to Space.o. If this driver is listed in /pkg/install/drivers and this file exists, then it is installed in the Link Kit as /etc/conf/pack.d/xnamex/space.c (note the change in capitalization) by idinstall. This file is compiled and linked into the kernel along with any Driver.o whenever this driver is configured into the kernel being built. .../xnamex/Stubs.c If this C source exists, it is installed in the Link Kit as /etc/conf/pack.d/xnamex/stubs.c (note the change in capitalization) by idinstall. This file is compiled and linked into the kernel whenever this driver is not configured into the kernel being built. .../xnamex/Node Description of the /dev special files associated with this driver. If this driver is listed in /pkg/install/drivers and this file exists, it is installed in the Link Kit as /etc/conf/node.d/xnamex by idinstall, and used by idmknod(ADM) when run from idbuild. The UNIX system installation also uses the Node file to determine which /dev special files must exist: if package pkg is listed in the packages string (/dev/string/cfg) then for each driver listed in /pkg/install/btld that has a Node file, the indicated /dev special files are created. .../xnamex/Inittab Lines to add to /etc/inittab to run various system startup and shutdown commands associated with this driver. If this driver is listed in /pkg/install/drivers and this file exists, it is installed in the Link Kit as /etc/conf/init.d/xnamex by idinstall, and used by idmkinit(ADM) when run from idbuild. .../xnamex/Rc Bourne shell script run by /etc/rc2 when entering init(M) state 2 (multi- user operation). If this driver is listed in /pkg/install/drivers and this file exists, it is installed in the Link Kit as /etc/conf/rc.d/xnamex by idinstall, and used by idmkinit when run from idbuild. .../xnamex/Shutdown Bourne shell script run by /etc/rc0 when entering init state 0 (system shutdown). If this driver is listed in /pkg/install/drivers and this file exists, it is installed in the Link Kit as /etc/conf/sd.d/xnamex by idinstall, and used by idmkinit when run from idbuild. See also basename(C), boot(HW), btldinstall(ADM), configure(ADM), displaypkg(ADM), fixperm(ADM), hd(HW), idbuild(ADM), idinstall(ADM), idmkinit(ADM), idmknod(ADM), idtune(ADM), init(M), installpkg(ADM), ld(CP), mdevice(F), mkdev(ADM), mtune(F), sdevice(F), sh(C), string(M), and stune(F). Device Driver Writer's Guide Notes Lines in the btld, bootstring, Bootload, Master, and System files should be less then 60 characters in length. The following mdevice(F) characteristics are silently ignored: _________________________________________________________________________ Characteristic Description _________________________________________________________________________ i Driver can be installed (assumed) o Only one sdevice(F) entry (boot(HW) only processes the first entry) H Driver controls hardware (not relevant) Other mdevice characteristics always cause the boot-linking to fail: _________________________________________________________________________ Characteristic Description _________________________________________________________________________ a Driver is automatically installed n Driver is not installable I Ignore driver's pack.d directory N No Driver.o or Space.c files Unrecognized characteristics and function tables cause a warning but are then ignored. If the hardware controlled by the boot-linked driver has jumpers or switches for setting parameters such as the IRQ (interrupt vector), base I/O address, or memory address, these should be specified as tuneable pa- rameters in the Bootload file. Users can then configure the hardware for their machine and add the required driver to the kernel so that it will use that configuration. This avoids the requirement for a specific con- figuration during system installation. Whenever possible, a driver's interrupt handling routine should be wil- ling to share the vector; that is, the driver should be type 3 (column 5 of sdevice(F)). Doing so increases the probability that boot will be able to configure the driver into the kernel successfully. Sharable interrupt handlers typically determine if a particular device caused an interrupt, and if not, they take no action. They must not lower the software priority level, although they may raise it temporarily. They should also avoid using unnecessary spin loops as this can cause timing problems for other drivers trying to share the vector. STREAMS modules, filesystems, event drivers, line disciplines and so forth cannot be boot-linked. Some versions of boot have facilities for linking some kernel debuggers; this is not supported and may change. boot cannot check for I/O or Controller Memory Address conflicts with other devices. Not all interrupt vector or device major number conflicts can be resolved; boot presents the possible resolutions and suggests the one most likely to work (if any are liable to work). The -p option to idbuild can be used to build space.o from space.c and thus obtain a Space.o (and Space.c) when making a BTLD diskette. Some relocatable COFF object modules that idbuild can add to a kernel either cannot be added by boot, or are added in a slightly different manner. Such modules include those with multiple mdevice or sdevice entries, those with entries in function tables not patched by boot, or those with references to functions or data defined in other drivers. In general, it is inadvisable to boot-link a driver if that driver calls any external routine not defined in section K of the Device Driver Writer's Guide or if that driver expects to have an entry installed in any table not listed above.