Guidelines for writing BTLDs

The following guidelines highlight precautions to ensure that your BTLD driver is robust enough for installation:

• Write your driver following the guidelines in ``Guidelines for all kernel drivers''. A non-BTLD drivers that violates these guidelines may corrupt the kernel; a BTLD driver that violates them may prevent successful installation of the operating system.

• BTLDs require compiled versions to be provided of any C-source files that can be installed in the Link Kit (such as Space.o and Stubs.o for Space.c and Stubs.c). This is because no mechanism is provided to compile these files at boot time -- they may only be linked.

• If you need to link a driver object module at boot-time that is different from the Driver.o to be installed into the Link Kit, you can supply a Driver.boot to achieve this. For example, a driver might need to use Driver.boot that implements a device polling mechanism if it cannot register interrupts at boot-time.

• We recommend that all drivers (including BTLDs) register interrupts dynamically. See ``Dynamic interrupt registration by BTLDs'' for more information.

• A BTLD must not require functions or data defined in another BTLD. In other words, the minimal installation kernel must be able to resolve all symbols in the BTLD.

• For forward compatibility, BLTDs must not require functions or data that are defined in any other driver, even if that driver is normally defined in the kernel. In future releases, the defining driver may not be in the minimal installation kernel.
  

• Some entry-point routines cannot be used in BTLDs because they edit kernel tables that cannot be edited at boot time. The following entry-point routines can be used in BTLDs:

  	Entry in ``funcs''
  Name	field of mdevice(F)	Comment
  xxclose	c
  xxhalt	h
  xxinit	I
  xxioctl	i
  xxkenter	E
  xxkexit	X
  xxopen	o
  xxpminit	P
  xxpoll	p
  xxprint		routine must be present for block devices
  xxprobe	R
  xxread	r
  xxstartup	s
  xxstrategy		routine must be present for block devices
  xxswtch	S
  xxwrite	w

• A BTLD must not use the extended minor device numbering scheme.

• Use consistent naming schemes to ensure that the driver name on the distribution disk matches that in the /dev/string/pkg file.

• Avoid prompts in the /install/INSTALL, preinstall, and postinstall scripts. Many users leave the installation running unattended and these prompts will stop the installation until the user returns.

• Avoid unnecessary informational messages because they will pause the installation process.

• Copyright information should be redirected to a file in the /etc/copyrights directory and not displayed during installation. The operating system will display these copyright notices when the system is booted.

• Ensure that installation scripts check for any required software that is not included in the driver package. Ideally, drivers should not have such dependencies, but if they are necessary, the scripts should check that they are there and exit gracefully if they are not. It is not necessary to verify the presence of software that is guaranteed to be present during system installation, such as the Link Kit.

• Files used to install BTLDs must not require decompressing, branding, or any alteration but must be usable directly from the BTLD disk.

• The default system configuration provides ten free slots in the switch tables and the interrupt dispatch table. The number of free slots is controlled by tunable parameters; if these have been changed or if more than ten drivers are being added as BTLDs, it may be necessary to modify the values of these tunables:

  
  EXTRA_NDEV

  number of free slots available for BTLD drivers

  
  MAX_BDEV

  maximum number of block device drivers (the size of the bdevsw table)

  
  MAX_CDEV

  maximum number of character device drivers (the size of the cdevsw table)