DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

link(HW)


link, ahslink -- link boot-time loadable drivers

Description

boot(HW) invokes link to link boot-time loadable drivers (BTLDs) into the kernel. This provides access to hardware devices that are not supported by the current kernel. It is a standalone executable program, and can only be executed by boot; it cannot be executed once the kernel has loaded.

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

link is invoked by entering link as a command, or as an argument to a command, at the boot prompt.

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
If link=pkg is invoked as an argument to a different boot command, link takes the names of the packages as its parameters:
   link="pkg1 pkg2"
If link is used as a command, any link= pkg arguments are ignored.

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

The Master and System files on the BTLD floppy disk instruct the boot-linker how to configure the boot-loaded driver into the loaded kernel. Three types of conflicts with drivers already present in the kernel may occur:

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 UNIX system kernel refers to a specific driver by its unique major device number, which is used as an identifier. When boot-loading a driver, major numbers may present a problem because:

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

Most devices use interrupts. When they complete, or are ready to do some I/O, they asynchronously notify the CPU and wait for a response. Drivers for devices which use interrupts usually have an interrupt-handling procedure and priority defined in the System file (columns 6 and 7 in sdevice. Some drivers want the boot-linker to install the handler at the specified priority; these drivers have a non-``0'' type (column 5 in sdevice(F)) in the System file and no G characteristic in Master. Other drivers only want the boot-linker to check that the driver itself should be able to later install its handler at that priority; these drivers also have a non-``0'' type but include the G characteristic. When boot-linking a driver, interrupt handlers (or ``vectors'') and priorities (or IPL -- ``interrupt priority level'') can be a problem because:

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

Function dispatch tables list driver routines called on certain events (such as system startup or shutdown). Problems which may arise when adding a boot-linked driver to these tables include:

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

The linker cannot and does not detect all the errors detected by the ld(CP) linker and the idconfig and idbuild configuration tools (see idbuild(ADM)).

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

History

ahslink provided linking functionality for BTLDs in AHS (Advanced Hardware Supplement) releases. That functionality was incorporated into link.

See also

boot(HW), btld(F), btldinstall(ADM), idbuild(ADM), ld(CP), string(M)

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


© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003