link(HW)

Description

Note that the linker must reside on the same device as boot.

For example, link may be invoked from boot using the syntax:

link="pkg1 pkg2"

where pkg1 ... pkgn are the names of packages to be linked into the loaded UNIX system kernel.

Boot-time loading of device drivers

Boot-time loadable drivers (BTLDs) are distributed in ``packages'' (that are normally provided on floppy disk).

If link is invoked as a command at the boot prompt, it prompts for the names of the packages to boot-load:

   What packages do you need linked into the system,
   or q to quit?: pkg1 pkg2

   link="pkg1 pkg2"

After the UNIX system kernel is loaded, each package pkg specified as an argument to link is prompted for. The appropriate floppy disk should be inserted into the drive. If the package name (pkg) does not include a device, link uses the default device defined by the bltd (or btlddev) argument to search for the package. The default device is usually the same device that boot was loaded from.

The package floppy disk should contain the files described in btld(F).

For each driver listed in /pkg/install/btld the same process is repeated. An error in a preceding step aborts the link and subsequent steps are not performed:

1. The driver's Master, System and Bootload files (if any) are read.

2. The appropriate object modules (as defined in Bootload) are loaded; the default is Driver.o and Space.o.

3. Any tune-able parameters (defined in Bootload) are prompted for.

4. The function dispatch tables defined in Master, and any tuneed or patched symbols are adjusted. If any conflicts occur (for example, if the interrupt vector that the boot-loaded driver wants to use is already occupied by another driver), boot explains the problem, lists the possible resolutions, and prompts for what to do about the conflict. Please see ``Resolving BTLD conflicts'' for details.

5. Unresolved references in the object modules are resolved.

The boot-linker queues the changes to the UNIX system kernel (step 4), so if there is a problem in resolving references (step 5) the linking can be aborted without forcing a reboot: the loaded kernel has not been changed. The queued changes to the kernel are not applied until the relinking (step 5) has completed successfully.

If every driver in the package was successfully linked by the boot-linker, the first line of the file /pkg/install/btld is appended to the list of link's arguments, and the name of the package is added to the ``package string'' passed to the UNIX system kernel. The package string can be read from the special file /dev/string/pkg.

Hardware usually has jumpers, switches, or a DOS (or standalone) setup program to configure the board. When boot-loading the drivers for such boards, the tune directive in the Bootload file (see the btld(F) manual page) causes boot to prompt for the settings of these jumpers or switches. The information boot may prompt for includes:

vector

The interrupt vector or IRQ used by the hardware.

DMAchan

The channel used by the hardware to directly access memory.

SIOA

Base or start I/O register address of the board.

EIOA

Ending (or extra) I/O register address of the board.

SCMA

Start or base bus, controller, or dual-ported memory address used by the board.

ECMA

Ending bus, controller, or dual-ported memory address used by the board.

units

Number or size of the peripherals attached to the board.

The manufacturer's instructions should say how to set the jumpers or switches, and what to reply in response to any prompts.

Resolving BTLD conflicts

• Another driver is already using the major device number the boot-loaded driver wants to use. See ``Resolving major device number conflicts'' for more information.

• Another driver already occupies the interrupt vector the boot-loaded driver wants to occupy. See ``Resolving interrupt vector conflicts'' for more information.

• A function dispatch table is full and so the appropriate boot-loaded driver's function cannot be added to the table. See ``Resolving function dispatch table conflicts'' for more information.

When a conflict is detected, boot explains the problem and offers several possible ways of dealing with the issue. If there is a comparatively safe alternative, that is the default resolution.

There are several answers which may always be entered:

q

Quit: the boot-linking of this driver is stopped; the kernel has not been changed.

RETURN

Use the default answer (if any).

M

List the major device numbers and associated drivers.

I[ vecno ]

Display interrupt vector vecno (0-255).

Tfuncs

Print the function dispatch table funcs; some of the dispatch tables include io_init, io_start, and io_halt.

Resolving major device number conflicts

• The Master file specifies a major number which is already in use.

• The Master file does not specify a particular major number, but there are no available (free) major numbers.

• The driver is both a block and character device, but the block and character major numbers specified in the Master file differ.

• The major number specified in the Master file is out-of-range.

• Another driver has the same internal name (column 1 mdevice(F)). This should never happen unless you are boot-linking a driver to a kernel which already contains that driver; doing so (called ``driver replacement'') is unreliable.

The possible resolutions include:

a

Add the driver using an available (free) major number.

number

Use major number; if that major is in use, boot prompts again to confirm the choice.

r

Replace the ``other'' driver (which has either the same internal name or is using the desired major number). This is inherently unreliable, not supported, and is never recommended.

Major device number conflicts are unlikely to occur. Should one occur, boot's default (if possible) is a -- add the driver using an available major number. The initial system installation procedure does not rely on boot-loaded drivers using any specific majors, even if the Master file gave a specific value. (However, there may be conflicts later when the driver is added to the kernel using the Link Kit.)

Resolving interrupt vector conflicts

• There is another handler of the same name at this vector. This should never happen unless you are boot-linking a driver to a kernel which already contains that driver; such driver replacement is unreliable.

• The boot-loaded driver wants exclusive use of the vector, but the vector is already in use. (The driver's type is 1 or 2.)

• The boot-loaded driver is willing to share use of the vector, but the vector is in use by another driver that wants exclusive use. (The driver's type is 3 or more, but the vector is occupied by a type 1 or 2 handler.)

• The vector is full and cannot be shared with any more handlers.

• The vector is in use and sharable but the priority (IPL) is wrong.

The possible resolutions depend on whether or not the boot-linker should actually configure the handler or just check the configuration. If the boot-linker is only checking the configuration (the driver has the G characteristic), the possible answers include:

d

Delete all handlers from the vector. The corresponding devices probably cannot be used, or the system may not function properly.

number

Delete a specific handler from the vector. That device probably cannot be used or the system may not function properly. A ? lists the handlers using the vector.

s

Convert an unsharable vector into one which can be shared. This may result in a handler sharing a vector despite not being designed to do so; the system may not function properly.

If the boot-linker should configure the handler into the system, the possible answers include:

number

Which handler already installed in the vector should be replaced by the boot-loaded driver's handler. The device controlled by the replaced driver probably cannot be used and the system may not function properly.

a

Add the boot-linked driver's handler to the vector. The system should work unless the vector was unsharable (and hence had to be converted to a sharable vector); if such a conversion is done, the system may not function properly.

r

Replace the entire list of handlers sharing this vector with the boot-linked driver's handler. Probably none of the replaced devices can be used or the system may not function properly.

An additional resolution is always possible:

n

Do nothing. The boot-loaded device probably cannot be used, or the system may not function properly.

If a vector is already in-use, the interrupt priority level (IPL) may need to be adjusted:

l

The boot-loaded driver's IPL is less than that of the vector; lower the vector's IPL to that of the driver.

r

The boot-loaded driver's IPL is greater than that of the vector; raise the vector's IPL to that of the driver.

c

Keep the vector's current IPL ignoring the driver's setting.

number

Set the vector's IPL to number (1 - 7 inclusive).

Since the system will probably malfunction if the driver's interrupts occur with a higher priority that the driver was designed for, r (raise) is never recommended. Whichever of l (lower) or c (current) that results in the least IPL (lowest priority) is always recommended.

Interrupt vector and priority conflicts are the most common problems encountered when boot-linking a driver to a kernel. The best resolution is to use the following procedure:

1. Shut down the machine.

2. Change the IRQ (interrupt vector) setting on the board using the jumpers, switches, or software setup as per the manufacturer's instructions.

3. Try the boot-link again.

Hardware which has jumper or switch selectable configuration parameters is preferable to ``hard-wired'' (fixed) equipment. The boot-loadable drivers for jumper or switch selectable boards should use the tune directive in the Bootload file to prompt for the settings of the switches or jumpers. The new values should be entered in response to the prompts, as per the manufacturer's instructions.

If the hardware does not have a switch-, software- or jumper-selectable IRQ, or the boot-linker fails to prompt for values, there is no ideal resolution. If possible, boot's default action is either s (convert an unsharable vector into a sharable one) or a (add the handler to the vector, converting the vector if necessary). Either may result in an uninstallable system.

Resolving function dispatch table conflicts

• The dispatch table is full.

• There already is another routine of the same name in the table. This should never happen unless you are boot-linking a driver to a kernel which already contains that driver; such driver replacement is unreliable.

The possible resolutions include:

number

Replace a routine already in the dispatch table with the boot-linked driver's routine.

a

Add the driver's routine to the table.

n

Do nothing; the driver's routine is not added. The boot-linked device may not work.

Dispatch table conflicts are unlikely to occur. Should one happen, boot's default (if possible) is to add the driver's routine (a).

Limitations

It is possible to boot-link a driver into the kernel that could not otherwise exist there. This may result in unpredictable behavior.

History

See also

Information about developing device drivers is available at the Consolidated Hardware Development (HDK) Web Page (http://www.sco.com/developers/hdk)