DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

btld(F)


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 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 ; these include XENIX, S51K, and AFS but exclude HTFS(TM) and DTFS(TM) -- 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.

/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 disk 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 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/...).

/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 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.

/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 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 software 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 to adjust the ownership and permissions of the installed files.

/pkg/install/bootstring

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=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 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 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
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 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

.../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 interrupt 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 number 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 the mdevice(F) file.

*
Most architectures only use the first 16 or so interrupt vectors. Interrupt vector 0 is always reserved for the system's clock. The tuned vector overrides column 6 of the sdevice file, 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 specified 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 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.

.../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 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 when run from idbuild.

.../xnamex/Rc

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.

.../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.

Limitations

Lines in the btld, bootstring, Bootload, Master, and System files should be less then 60 characters in length.

The following mdevice characteristics are silently ignored:


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(F) characteristics always cause the boot-linking to fail:

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 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.

See also

basename(C), boot(HW), btldinstall(ADM), configure(ADM), displaypkg(ADM), filesys(F), fixperm(ADM), hd(HW), idbuild(ADM), idinstall(ADM), idmkinit(ADM), idmknod(ADM), idtune(ADM), init(M), installpkg(ADM), ld(CP), link(HW), mdevice(F), mkdev(ADM), mtune(F), sdevice(F), sh(C), string(M), stune(F)
© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003