Managing Dynamically Loadable Kernel Modules

The Dynamically Loadable Kernel Modules Infrastructure is an HP-UX operating system feature that allows “DLKM-Enabled” kernel modules to be dynamically loaded into, or unloaded from, the HP-UX kernel without having to re-link the entire kernel or reboot the system.

Previously, to install and use a new driver, you had to edit the system file, run the config or mk_kernel commands to create a new kernel, shut down the system, and then bring the system back up.

The DLKM feature not only provides the infrastructure to load kernel modules into a running system, but it also allows you the option of statically linking a kernel module when rebuilding the kernel. This is accomplished by changing the value of one of the DLKM module's configuration attributes.

The DLKM infrastructure specifies that:

	NOTE: See the master(4) manual page for descriptions of the traditional and modular master files, and the system(4) manual page for a description of the traditional and modular system files. See kmsystem(1M) and kmtune(1M) for descriptions of how to set and get a module's configurable attributes.

Kernel modules written as traditional modules are still supported in HP-UX. Driver developers are encouraged to re-package their static modules according to the module packaging architecture introduced with DLKM modules, as traditional packaging support may be obsoleted in a future release.

The DLKM feature currently supports the following types of kernel modules:

DLKM modules provide many advantages relative to static modules, including:

When a module is dynamically loaded, its object file is read from disk and loaded into newly allocated kernel memory. Once in memory, the module's symbols are relocated and any external references are resolved. Special code in the module is then executed to perform any required module-specific setup. Then the code specific to the module's type, if any, is executed, making the newly loaded module accessible to the rest of the kernel.

A module can be loaded in the following ways:

When the functionality provided by a module is no longer needed the module can be unloaded, thus freeing its resources for other uses.

Through the use of configurable module attributes, system administrators can control the various functions of a DLKM module, including whether it is dynamically loaded or statically configured.

The section “Developing Dynamically Loadable Kernel Modules”, describes the required and optional component files and the keywords and attributes which are configurable. It also presents a brief description of STREAMS and Miscellaneous modules.

The section “DLKM Procedures ”, presents detailed instructions on how to modify the configurable module attributes, and how to manage DLKM modules using the kernel configuration tool set.

Since the introduction of DLKM to HP-UX, the installed kernel configuration information is used to configure a whole kernel, or a specific module, and is distributed among several files. The number and location of the files used to configure a kernel depends on which modules are installed on the system. Furthermore, the format of such information is subject to change. Using the kmsystem(1M) and kmtune(1M) commands to modify the planned configuration prior to a whole kernel configuration or a module configuration will avoid corruption of the configuration files, and will ensure that the correct files are updated.

	CAUTION: Avoid editing the system files; doing so is not forward-compatible and increases the chance of introducing configuration errors.

In addition, a configured, bootable kernel is no longer composed of a single file. Each new kernel configured with the config(1M) or mk_kernel(1M) command is composed of several files, including the main kernel file, the loadable images for DLKMs, a symbol table file, and a kernel-specific KRS file. All component files of the kernel are essential for the kernel to boot and run properly. The kmupdate(1M) command understands the organization of these files and prepares a directory structure accessible to the boot loader that allows a newly generated kernel to boot and run properly.

A whole kernel configuration must be followed by a kernel update step initiated via the kmupdate(1M) command (or config -u) in order to be able to successfully boot the new kernel.

Because of these effects, it is best to configure any type of kernel module using the tools described in this section.

	CAUTION: Avoid copying or moving kernel files; doing so may result in corrupting the running kernel, or any other configured kernel on the system.

See kmsystem(1M), kmtune(1M), mk_kernel(1M), config(1M), and kmupdate(1M) for more information.

These procedures:

Preparing a Loadable Module for Dynamic Loading Into the HP-UX Kernel. You can use the kmsystem command to prepare a DLKM module to be either dynamically configured or statically configured.

The kmsystem command sets the planned configuration, planned linkage, and planned loading phase of a module.

The -c value option specifies whether the module will, or will not, be configured at the next kernel or module build. If value is y, it will be configured, if value is n it will not be configured. The -l value option specifies whether the module will be dynamically, or statically, linked at the next kernel or module build. If value is y, it will be dynamically loadable. If value is n it will be statically linked.

The -b value option specifies the phase during which the module will be loaded, assuming it has been configured and registered with the kernel. The value argument can be one of the following:

The planned loading phase will become the configured loading phase once a module is configured and registered with the kernel.

	NOTE: If the module does not support dynamic linkage, an attempt to set the planned linkage as dynamic (kmsystem -l y), and/or an attempt to set the planned loading phase (kmsystem -b phase) will result in an error.

To prepare a loadable module to be dynamically loaded into the kernel, execute this command:

   /usr/sbin/kmsystem -c y -l y -b phase module_name

	NOTE: A module's system description file, as well as the HP-UX system file, must only be modified using the kmsystem or kmtune commands. It is important to follow this practice because the format of planned attributes and their location in the system will change in future releases and if you manually modify the system files as they are currently designed, your modifications will not be forward compatible.

Configuring a Loadable Module for Dynamic Loading. Use the config command to configure a loadable module (a DLKM module) into the system as a dynamically configured module. For a DLKM module configuration, config proceeds as follows:

To configure a loadable module for dynamic loading and register it with the running kernel, execute this config command:

   /usr/sbin/config -M module_name -u

This results in the generation of a loadable image. The -u option forces config to call the kmupdate command, which causes the system to move the newly generated image into place and register it with the running kernel.Upon completing this configuration procedure, the DLKM is ready to load on any of its Supported Loading Phases. If the module specifies runtime (RUN) as a supported loading phase, the module is ready to load immediately; you do not have to wait for a reboot.

Loading a Dynamically Configured Loadable Module Into the HP-UX Kernel. To load a dynamically configured loadable module, use the -L option of the kmadmin command. The load operation initiated by the kmadmin -L command performs all tasks associated with link editing the module to the running kernel and making the module accessible to the system.

	NOTE: All dynamically loadable modules need to be registered before they can be demand or autoloaded into the running kernel. The kmupdate command carries out this task.

Specifically, the load operation performs the following tasks:

To load a dynamically configured loadable module into the running kernel, execute the following kmadmin command:

   /usr/sbin/kmadmin -L module_name

When the loading completes, an identifier (ID) number prints on the standard output to identify the module that was loaded.

Changing the Configured Loading Phase of a Currently Registered Module. Once a module has been registered with the currently running kernel, the configured loading phase can be changed using the following command syntax:

For example, the following command schedules a registered module named hello to be loaded at every system reboot, at the end of the boot sequence (at init time); /usr/sbin/kmadmim -b i hello

For more information, see “Preparing a Loadable Module for Dynamic Loading Into the HP-UX Kernel”.

These procedures:

Preparing a Loadable Module for Static Linking. You can use the kmsystem command to prepare a DLKM module for configuration as statically configured.

Use the kmsystem command to set the planned configuration of a module.

To prepare a DLKM module for static linking to the HP-UX kernel, execute this kmsystem command:

   /usr/sbin/kmsystem -c y -l n module_name

	NOTE: A module's system description file, as well as the HP-UX system file, must only be modified using the kmsystem or kmtune commands. It is important to follow this practice because the format of planned attributes and their location in the system will change in future releases and if you manually modify the system files as they are currently designed, your modifications will not be forward compatible.

Whole HP-UX Kernel Configuration to Include a Statically Configured Loadable Module. When configuring a DLKM module into the system as statically configured, config builds an entire kernel, that is, configures the static kernel and all kernel modules. For a whole kernel configuration, config proceeds as follows:

	WARNING! Manually copying or moving kernel files is not a supported practice, and may result in corrupting the running kernel or other kernels on the system. See kmupdate(1M) for the supported interfaces to update and remove kernels.

	NOTE: A whole kernel configuration generates several files that will make up the kernel component set for the new kernel. After a whole kernel configuration, a kernel update (see next section) and a system shutdown and restart are required to be able to make the newly configured kernel the active kernel. The kernel update step, initiated with the kmupdate command or config -u, is now a required step to be able to successfully boot a newly configured kernel.

To configure the HP-UX kernel to include a statically configured loadable module and update the system with the new kernel, execute this config command:

   /usr/sbin/config -u /stand/system

config builds a new kernel. The -u option forces config to call the kmupdate command to schedule the update of the kernel image, a required step in the process of successfully booting a newly configured kernel.

After the system reboots, your DLKM module will be available as statically configured in the new running kernel.

Updating the Kernel. For a DLKM module configured as statically linked, use the kmupdate command to schedule the update of the system with the newly configured kernel.

Each new kernel configured with the config(1M) command is composed of several distributed files, which are all required for a kernel to boot and run properly. The main kernel file is associated with its component files by way of a Kernel ID String (KIS) in the main kernel image. For any kernel, all the files required by the boot loader need to be accessible from the /stand/boot.KIS directory, where KIS uniquely identifies the kernel being booted.

The kmupdate(1M) command does the following:

Call kmupdate after first calling config. If you include the -u option in the config invocation, there is no need to invoke kmupdate. The config -u command automatically invokes kmupdate.

To update the kernel, execute the following kmupdate command:

   /usr/sbin/kmupdate /stand/build/vmunix_test

Loading the Kernel. For a DLKM module configured as statically linked, use the -r option of the shutdown(1M) command to load the newly generated kernel by shutting down and rebooting the system. Executing the shutdown -r command terminates all currently running processes and reboots the system, which causes the new kernel configuration to take effect. At that time, all statically linked, dynamically configured modules associated with the new kernel are accessible to the system.

To load the new kernel, move to the / directory, and execute the following shutdown command:

      cd /
      /usr/sbin/shutdown -r