7 THE LCU BOOT ENABLER

The "LCU boot enabler" shall make the creation and maintenance of LCU boot-scripts easier. The main features are:

In LCU systems applying this scheme, lcuboot is always the first module that is loaded during system start-up. After that several functions are available that facilitate the loading and installation of all further modules.

These functions in principle support the automatic installation of arbitrary LCU modules, but especially of drivers and devices. All functions are intended to be used directly from the VxWorks shell in a boot-script.

The script is aborted when a fatal error condition occurs, which is signalled as a log message in the form:

<tid> (tShell): lcuboot: <message>: <faulty item>:<errno | faulty item>
<tid> (tShell): --- SCRIPT ABORTED ---

Most of the functions in lcuboot are not reentrant and should therefore only be used from LCU boot-scripts, where reentrancy is not important!

The installed version of lcuboot can be printed with lcubootVersion from the VxWorks shell.

The functions available with lcuboot are briefly described in the next sections.

7.2 Available lcuboot Functions

7.2.1 lcuboot Automatic Environment Setup

· lcubootAutoEnvInit - initializes the standard LCC shell environment variables from the LCU boot-line settings and sets the VxWorks shell-prompt. VLTROOT and optionally INTROOT must be set before calling it. This makes the explicit definition of many variables in the boot-script redundant. It also assigns search-path variables for prioritized access of binary modules (BINPATH), module-boot-scripts (BOOTPATH), and configuration files (CONFIGPATH). Functions are provided to access files based on these search-paths, see section 7.2.5.

7.2.2 lcuboot General Module Support

· lcubootAutoLoad - auto-loads a binary module and error definition files from MODROOT, INTROOT (with priority) or VLTROOT. This can be used to conditionally load a module. By default a module is not loaded again when it already exists in the LCU memory.

Do not use the VxWorks function ld to load a VLT module, since this will not handle the module's error definition files under xxxROOT/ERRORS.

· lcubootAutoExec - executes a function depending on a given condition. This can be used to conditionally/optionally install a module.

· lcubootAutoSpawn - spawns a function as a task depending on a given condition. This can be used to conditionally/optionally spawn a task.

· lcubootAutoCd - changes to the directory under INTROOT (with priority) or VLTROOT in which a file given by a relative pathname is found first.

· lcubootAutoCdBoot - dto., but specifically intended for module-boot-scripts. Only the module-name is needed, the search-path is fixed (see man-page).

· lcubootAutoProbe - tests whether any hardware is present at the given addresses. This can be used to determine the number of boards/devices that are present in the system.

7.2.3 lcuboot Driver and Device Installation

· lcubootAutoDevRegister - checks for the presence of a device and registers it for later creation and registration in LCC. Subsequent calls of lcubootAutoDrvInstall must be used to install the driver and lcubootAutoDevCreate to create the devices automatically depending on their presence.

· lcubootAutoDrvInstall - conditionally loads and installs a driver from INTROOT (with priority) or VLTROOT and prepares for subsequent calls of lcubootAutoDevCreate.

· lcubootAutoDevCreate - performs the automatic installation of a device. Note that there must be as many calls of this function as the maximum number of devices that shall be supported.

· lcubootAutoDevCheck - checks whether the number of devices installed in the system are equal to a given value. This can be used to verify that the expected number of devices are actually installed; however, it works against the idea of automatic device installation.

7.2.4 lcuboot LCC Support

· lcubootAutoLccRegisterDevs - register all devices in LCC that have been previously announced with lcubootAutoDevRegister. This function is usually called during installation of LCC.

7.2.5 lcuboot File Access Support

· lcubootFileOpen - opens a file using a given search-path. This allows for instance to access configuration files at run-time, using the environment variable CONFIGPATH as search-path.

7.3 How to create LCU Module-Boot-Scripts

As usual, there will be a main boot-script named bootScript that the LCU processes initially. From that, Module-Boot-Scripts named <module>.boot are invoked to load and initialize each module. These shall make use of the lcuboot functions, and apply the following guidelines:

· For each LCU module there must be one module-boot-script named <module>.boot that can be called from the main boot-script. It shall be installed during the make procedure of the module by specifying it under the SCRIPTS directive in the Makefile.

· For each LCU module there should be a man-page named <module>.boot(5) in the `File Formats' section that explains the contents of the module-boot-script.

· For each LCU driver module there should be a man-page named <module>(4) in the `Devices' section that explains the respective board-hardware (addresses, jumpers etc.).

See the man-pages of lcuboot(5) and bootScript(5) in the reference section 8 for details about the file and directory organization.

The following sections will present some more details about the recommended structure of module-boot-scripts, first for general LCU modules, then for drivers in particular.

7.3.1 Module-Boot-Scripts for General Module Installation

This section describes the recommended structure of standard module-boot-scripts for general modules. Module-Boot-Scripts are called from the main bootScript of the LCU when a module shall be initialized.

· The module-boot-script shall load the code of the module as well as all other modules that are needed for operation using the lcubootAutoLoad function, which will also take care of the error definition files. For user-application modules LCC can be expected to be already initialized, but driver boot-scripts should not expect that any other module they depend on has already been loaded.

lcubootAutoLoad 1,"lqs"
lcubootAutoExec 1,"lqsInit",10,"rtap"
lcubootAutoExec 1,"lqsAddEnvTbl","wte49","te49","134.171.12.184",2301
... (more) ...
lcubootAutoSpawn 1, "tLqs", 90, 0x18, 20000, "lqs", 3

acroN = lcubootAutoDevRegister("/acro0",0x1000,1,1,1)
... (more) ...
lcubootAutoDrvInstall "acro"
lcubootAutoDevCreate "/acro0",0x1000,112,1
... (more) ...
lcubootAutoSpawn acroN,"tintACRO",200,0x18,2000,"acroInt"

See the man-page of Module.boot(5) for full details and examples. It is available on-line.

7.3.2 Module-Boot-Scripts for Automatic Driver and Device Installation

This section describes the recommended structure of standard module-boot-scripts for automatic loading and installation of the hardware drivers and devices. They provide a "Plug & Play" feature, so that hardware will be automatically recognized and appropriately installed.

Driver and devices will only be installed when corresponding hardware is found in the VME system. The probing is done with a sequence of calls as follows:

<drv>N = lcubootAutoDevRegister("<devX>",<AM>,<addrX>,<args>)

<drv> - name of driver, e.g. "acro"
<devX> - name of Xth device, e.g. "/acro0"
<AM> - VMEbus address modifier code for A16/A24/A32 space
<addrX> - VMEbus address for Xth device
<args> - 3 integer arguments

See the VxWorks header "$VXROOT/h/vme.h" for all available values, but in this context only the above stated Supervisor/Data modifier codes are of interest.

For each device to be created, there must be one line as shown below. Where no hardware was found in step 1, the creation will be skipped:

The device creation usually takes VMEbus addresses as <bus-addrX>, which are different from CPU addresses. <params> are specific to each device family.

All installed devices are automatically registered afterwards in LCC with the function lcubootAutoLccRegisterDevs, which is usually called at the end of the script "lcc.boot".

The automatic installation depends totally on the usage of the VLT standard board address settings, as described in each driver's man-page in the devices volume, e.g. acro(4).

See the man-page of Driver.boot(5) for full details and examples. It is available on-line.

7.4 How to configure LCUs with lcuboot

In order to build a bootScript that is suitable for the lcuboot structure, it is recommendable to use the vccConfigLcu panel, see section 5. Hence the bootScript is a generated file and should not be edited by hand.

The userScript will still be processed as usual, its contents remains fully user-defined.

It may be necessary to configure some module-boot-scripts for your site, in particular lqs and xntp. Configuration can be done on a per-LCU basis, as well as on a per-host basis, where it applies to all LCUs booting from that host.

7.4.1 To create a boot-script suitable for lcuboot

It is assumed that all environment files have already been created as described in section 4.

All devices should be installed automatically, provided that you follow the board setups as described in the man-pages acro(4), aio(4), etc. Check with moduleShow and devs that all modules and devices are existing as expected.

These steps cover only the most general case. The userScript will still be sourced, so that it might require some adjustment.

7.4.2 To configure module-boot-scripts for your site

Some module-specific boot-scripts (those with ".boot" extension) might require some site-specific adjustments that are common to all LCUs in it. The most probable candidates for such a customization are "lqs.boot" and "xntpd.boot", where some node-names and IP-addresses must be defined. This is usually common to all LCUs, so that the configuration should be done on a per-host basis.

2. Edit this copy according to your specific needs. It will automatically have priority over the installed defaults under VLTROOT and INTROOT.

Refer to the on-line man-pages <module>.boot(5) for more information, e.g. lqs.boot(5) respectively xntpd.boot(5).

7.4.3 To configure module-boot-scripts for a specific LCU

If you have the case that one LCU needs a different configuration for a certain module than other LCUs, then do the following:

cd $VLTDATA/ENVIRONMENTS/<LCU-Env-Name>
cp $VLTDATA/config/<module>.boot .
or: cp $VLTROOT/vw/bin/<cpu>/<module>.boot .

2. Edit this copy according to your specific needs. It will automatically have priority over the installed defaults under VLTROOT and INTROOT, as well as the per-host configuration in VLTDATA/config, if present.