|
|
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 ;
these include XENIX, S51K, and AFS but exclude
HTFS
and DTFS -- see
filesys(F).
Each package 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.
This file must exist and be an executable Bourne shell (sh(C)) script. It is run by installpkg with three arguments:
There can only be one INSTALL script per disk. It typically invokes btldinstall :
exec /etc/btldinstall "$2"btldinstall asks which packages on this disk are to be installed, and then adds the appropriate drivers from the requested packages to the system's Link Kit (/etc/conf/...).
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 the mdevice(F) file. 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.
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.
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 list the contents of this file.
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.
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 software packages.
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 to adjust the ownership and permissions of the installed files.
If this file exists, the first non-empty line not starting with
an asterisk (
) or hash (#) is appended to the bootstring
passed by boot to the booted UNIX kernel.
For example, bootstring might contain:
hd=xnamexto specify that boot-linked driver xnamex (part of this package) is the primary hard disk.
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 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.
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.
File containing the mdevic file 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(F) file by idinstall 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 |
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 | MAX_BDEV | At least this many block device entries |
| c | MAX_CDEV | At least this many character device entries |
| I P s p h E X S | EXTRA_NDEV | Extra unoccupied entries available for boot to fill |
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 interrupt dispatch tables accordingly.
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 number sign (#) are ignored.
The keywords include:
files Driver.o Space.oThe filenames are relative to the .../xnamex directory.
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 |
As an example, the directive:
tune SIOA xx_iobase 2 SCMA xx_ramloc 4would 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 specified in the appropriate mdevice (Master) or sdevice (System) column. The C code initialized values are not used and are always overwritten.
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.
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.
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 capitalization) 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.
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.
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.
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 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.
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 when run from idbuild.
Bourne shell script run by /etc/rc2 when entering init state 2 (multiuser 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.
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.
The following mdevice characteristics are silently 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 tunable parameters 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 configuration during system installation.
Whenever possible, a driver's interrupt handling routine should be willing to share the vector; that is, the driver should be type 3 (column 5 of an sdevice(F) entry. 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 disk.
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 the (K) manual pages section
or if that driver expects to have an entry installed in any table not
listed above.