config(1M)

NAME

config — configure and build an HP-UX system

SYNOPSIS

/usr/sbin/config [-c c_file] [-l m_file] [-m master] [-r path] [-s|-u] [-S] [-t] system_file

/usr/sbin/config -M module_name [[-M module_name]...] [-m master] [-u]

DESCRIPTION

config is used to configure the following parts of the operating system:

device drivers
swap and dump devices
tunable system parameters
kernel modules

config supports the following configurations:

whole kernel configuration (first form)
Both the static kernel (vmunix) and dynamically loadable modules are generated, and a system reboot is necessary.
dynamically loadable module configuration (second form)
Specified loadable modules are dynamically generated and registered with the current system. The newly configured services are available immediately, without requiring a system reboot.

Kernel modules can either be static modules or dynamically loadable modules.

The first form is used to configure the entire kernel; that is, the static kernel and all kernel modules. This type of configuration is called a whole kernel configuration. The second form is used to configure only the dynamically loadable modules.

Static modules are maintained in individual object files which are included or excluded from the static kernel (vmunix) based on whether the features they support are required in the system. Such modules are non-loadable and remain linked into the kernel.

Dynamically loadable modules are also maintained in individual object files but they are not statically linked into the kernel. Loadable modules can be configured to be included or excluded from the kernel dynamically, without having to relink the entire kernel or reboot the system. The loadable image generated during the configuration of such modules may be auto-loaded or unloaded by the kernel or demand-loaded or unloaded by the system administrator.

See the Managing Systems and Workgroups for information on how to include or remove a subsystem, file system, or kernel module, and how to boot the system.

Whole Kernel Configuration (First Form)

To configure a whole kernel, config reads the user-provided description of an HP-UX system (system_file), the system description files for kernel modules, and the master kernel configuration table information.

Note that the system file and system description files for kernel modules should only be modified by using the kmsystem or kmtune system administration commands.

For all kernel modules to be configured, config checks the interface functions or symbols used by the modules. If modules rely on symbols not covered by the $INTERFACE section of its master file, configuration fails. Otherwise, config generates the following output files and directories:

C program source files (conf.c and space.h) that define the configuration tables for various parts of the system. Unless kernel modules are configured, these files will not be generated.
C program header file (tune.h) that defines tunable parameters of the system required by kernel and kernel modules.
C program source files (mod_conf.c) that are required by kernel modules. If a space.h header file is provided with a module, it is included by the source file.
a makefile (config.mk) to compile the C program produced and relink the newly configured system with statically linked kernel module object file (vmunix_test), and to generate kernel symbol table (symtab).
another makefile (config.mod) to generate all dynamically loadable modules to be configured.
a directory (dlkm.vmunix_test) to store the generated dynamically loadable modules, kernel symbol table, and module registry file associated with the kernel being built (vmunix_test). This directory here after will be referred to as the kernel function set directory. The files in this directory will be referred to as the kernel function set files.

Many header files are needed to compile conf.c. Also, archive library files containing the kernel objects are needed to link the kernel. These files are supplied with the system and are contained in the directories found under /usr/conf.

config.mod and the module registry file are not generated if there are no dynamically loadable modules being configured.

config executes the make command to compile conf.c, to link the kernel with the appropriate kernel libraries and statically linked modules, and to generate the kernel symbol table. It also executes the make command with config.mod to compile dynamically loadable modules.

The make command create several files in a working directory whose location depends on the name of the system file. If system_file is /stand/system, the working directory is /stand/build; otherwise the working directory is the current directory. With successful completion of the make command, the following files are generated:

kernel file
The kernel file vmunix_test is generated in the working directory.
kernel function set directory
The kernel function set directory (dlkm.vmunix_test) is created in the working directory.
kernel symbol table
The kernel symbol table symtab is generated in the kernel function set directory.
dynamically loadable modules
Dynamically loadable modules are generated under a subdirectory (mod.d) of the kernel function set directory.

If the -u option is specified, the newly generated kernel file and its kernel function set directory are automatically copied to their default locations, /stand/vmunix and /stand/dlkm, respectively, on system shutdown or restart. The previous kernel file and its kernel function set directory will be saved as /stand/vmunix.prev and /stand/dlkm.vmunix.prev, respectively.

Options for Whole Kernel Configuration

When configuring a whole kernel, the config command recognizes the following arguments:

-c c_file: Specify the name of the C program source file produced by config. The default file name is conf.c.
-l m_file: Specify the name of the makefile which is generated by config. This is the makefile which will be used by config to compile the C program source file and make the new kernel. The default file name is config.mk.
-m master: Specify the name of the master kernel configuration information file or directory that config should use in creating source files and makefiles. If master is a directory, config reads all files in that directory to create its data structures. If master is a file, only that file is read for creating data structures for config. By default, config reads the files in the directory /usr/conf/master.d. /usr/conf/master.d is supplied as part of the HP-UX operating system and should not be modified by anyone who does not fully understand its structure and purpose.
-r path: Search the directory path for the libraries and header files needed for making the kernel. By default, config uses the directory /usr/conf.
-S: Statically link all kernel modules into the kernel file. This option only takes effect if kernel modules are configured as loadable.
-s: Stop after generating source files and makefiles. make is not executed and no kernel (vmunix_test) or kernel modules are created. The -s option cannot be used with the -u option.
-t: Give a short table of major device numbers for the character and block devices, the card drivers, the streams drivers and modules that require link routines, the streams devices and the streams modules named in system_file. These tables may be useful when creating special device files.
-u: Invoke kmupdate after successfully configuring the new kernel environment. The -u option cannot be used together with the -s option.
system_file: The file containing configuration information for the user's system. The default system file is /stand/system and when this file is used as input to config, the resulting output is placed in the directory /stand/build. If a file other than /stand/system is used for system_file, config places its output files in the current directory. The system file is divided into two parts: the first part (mandatory) contains driver specifications; the second part (optional) contains system-dependent information.

Constructing an HP-UX System File

The first part of system_file is used to configure:

device drivers
pseudo-drivers
subsystems

Each line has the following format:

devname: where devname is the driver or subsystem name as it appears in the alias tables, driver install tables or the device tables in the files in the directory, /usr/conf/master.d. For example, scsi selects the driver for SCSI disk drives, scsitape selects the driver for SCSI tape drives, and nfs selects the NFS subsystem. Together, the files in /usr/conf/master.d contain a complete list of configurable devices, cards, subsystems, and pseudo-drivers.

The optional second part of system_file is used to:

define the swap device
define the dump device(s)
provide a mapping of a driver to a hardware path
define status and values of selected system parameters.

Lines are constructed as indicated below for each category.

(1) Swap device specification

No more than one swap specification is allowed. If a swap specification is not given, the system will be configured to swap on the root device at the end of the filesystem.

swap hw_path offset [blocks]

Configure the swap device location and its size as specified. Arguments are interpreted as follows:

hw_path: The hardware path representing the device to configure as the swap device or the string default may be used to indicate using the root device.
offset: The swap area location. Boundaries are located at 1K-byte intervals. A negative value specifies that a file system is expected on the device. At boot-up, the super block is read to determine the exact size of the file system, and this value is put in offset. If the swap device is auto-configured, this is the mechanism used. If the super block is invalid, the entry will be skipped so that a corrupted super block will not later cause the entire file system to be corrupted by configuring the swap area on top of it. A positive or zero value for offset specifies the minimum area that must be reserved. Zero means to reserve no area at the head of the device. A zero value implies that there is no file system on the device.
blocks: The number (in decimal) of 1K-byte disk blocks in the swap area. For this swap device specification, only the blocks parameter is optional. Zero is the default for auto-configuration. If blocks is zero, the entire remainder of the device is automatically configured in as swap area. If blocks is non-zero, its absolute value is treated as an upper bound for the size of the swap area. Then, if the swap area size has actually been cut back, the sign of blocks determines whether blocks remains as is, resulting in the swap area being adjacent to the reserved area, or whether blocks is bumped by the size of the unused area, resulting in the swap area being adjacent to the tail of the device.

swap hw_path options

Configure the swap device at the location specified using the options specified. The hw_path argument is interpreted as it is in the previous example.

The options field is used to specify a section. It is only offered for backwards compatibility purposes. For example, s3 would put the swap area on section 3.

swap lvol

Configure swap on a logical volume.

swap none

Configure the kernel with no swap device.

(2) Dump device(s) specification

One or more dump specifications are allowed. If a dump specification is not given, then the primary swap area will be used.

dump hw_path [options]

Configure the dump device location and its size as specified. Arguments are interpreted as follows:

hw_path: The hardware path representing the device to configure as a dump device or the string default may be used to indicate using the primary swap area.
options: This field is used to specify a section. It is only offered for backwards compatibility purposes. For example s3 would put the dump area at section 3.

dump lvol

Configure dump on a logical volume.

dump none

Configure the kernel with no dump device.

(3) Device driver to hardware path

One or more driver to hardware path specifications is allowed. If a driver statement is provided, the specified software module is forced into the kernel I/O system at the given hardware path. This can be used to make the system recognize a device that could not be recognized automatically.

driver hw_path driver_name

Bind the driver into the kernel I/O system at the given hardware path. Arguments are interpreted as follows:

hw_path: The hardware path representing the device to bind the software with.
driver_name: The name of the software module to bind into the kernel at the specified hardware path.

(4) System parameters

These parameters should not be modified without a full understanding of the ramifications of doing so (see the Managing Systems and Workgroups manual).

Each line contains two fields. The first field can contain up to 20 characters; the second field up to 60 characters. Each line is independent, optional, and written in the following format:

 parameter_name      number or formula 

Interprocess communication consists of messages (mesg), semaphores (sema) and shared memory (shmem) features. If mesg, sema, and/or shmem are specified as 0, the kernel code for these features is not included. If they are specified as 1, the kernel code is included; this is the default. The features can be specified independent of each other. If the code is included, the parameters listed below can be modified:

                      

mesg        1 msgmap      number or formula  msgmax      number or formula  msgmnb      number or formula  msgmni      number or formula  msgseg      number or formula  msgssz      number or formula  msgtql      number or formula  sema        1 semaem      number or formula  semmap      number or formula  semmni      number or formula  semmns      number or formula  semmnu      number or formula  semume      number or formula  semvmx      number or formula  shmem       1 shmall      number or formula  smbrk       number or formula  shmmax      number or formula  shmmin      number or formula  shmmni      number or formula  shmseg      number or formula 

Dynamically Loadable Module Configuration (Second Form)

To configure loadable kernel modules, config builds components for the module specified by the -M option. If the -M option is specified in conjunction with the -u option, then config builds the loadable module and call upon kmupdate to update the loadable image of that module in memory. Updating the loadable image implies replacing the existing loadable image with the newly created loadable image, re-registering the module with the new information, if required, and performing any type-specific initialization; e.g. recreating the special device file, if needed.

When configuring loadable modules, config reads the running kernel's system description file, system description files for kernel modules, and the master kernel configuration information table.

Note that system description files for kernel modules should only be modified by using kmsystemor kmtune system administration commands.

To configure loadable modules, config checks the interface functions or symbols used by the modules. If the modules rely on symbols not covered by the $INTERFACE section of its master file, configuration fails. config then generates the following output files:

C program header file (tune.h) that defines tunable parameters of the system.
C program source file (mod_conf.c) that is required by each kernel module.
makefile (config.mod) to generate specified dynamically loadable modules.
module registry entry to register the specified modules.

After the above files have been generated, config executes the make command with config.mod to generate dynamically loadable module.

With a successful make, the object files of dynamically loadable modules are generated and placed under the kernel function set directory.

If the -u option is specified, kmupdate is executed by config.

All kernel module related files are needed to configure the module. See kminstall(1M) for details on kernel module files.

Options for Loadable Module Configuration

When configuring a loadable module, config recognizes the following options:

-M module_name

Configure the specified loadable module only. A kernel file is not generated in this case. If successful, the loadable image of the module is generated.

If the specified module is a stub module (see master(4)), config prints a message and fails. An entire kernel build is required to configure stub modules.

-m master

Specify the name of the master kernel configuration information file or directory that config should use in creating source files and makefiles. If master is a directory, config reads all files in that directory to create its data structures. If master is a file, only that file is read for creating data structures for config. By default, config reads the files in the directory /usr/conf/master.d. /usr/conf/master.d is supplied as part of the HP-UX operating system and should not be modified by anyone who does not fully understand its structure and purpose.

-u

Invoking kmupdate to update the module.

Kernel Module System Description File

Kernel module description files are placed under /stand/system.d. A system file for a module is named after the module name and is unique.

Each file consists of three mandatory and one optional sections.

$VERSION:

The line starting with $VERSION indicates the version number for the file format. Version is defined as a decimal number and starts from one.

Format is:

$VERSION version_number

Example:

$VERSION 1 

$CONFIGURE:

The line starting with $CONFIGURE indicates whether the module needs to be configured. If the second field is either Y or y, the module will be configured on the next build. If the field is either N or n, the module will not be configured on the build.

Format is:

$CONFIGURE 
{Y|y|N
|n}

Example:

$CONFIGURE Y

$LOADABLE:

The line starting with $LOADABLE indicates how the module will be configured. If the second field is either Y or y, the module will be configured as a dynamically loadable module.

If the field is either N or n, the module will be statically linked into the kernel.

If the master file for the module does not have a $LOADABLE section, then the system file should not have one either.

Format is:

$LOADABLE 
{Y|y|N
|n}

Example:

$LOADABLE Y

$TUNABLE (Optional system parameter section)

The section between the lines starting with $TUNABLE, and with $$$ indicates tunable parameters of the module.

The above mentioned keywords e.g. $VERSION, $CONFIGURE must start at the beginning of the line without white space or tabs. Field separators can be single white spaces, tabs, or a combination of both.

Lines starting with an asterisk (*) are comment lines

RETURN VALUE

config returns 0 upon successful completion. If an error occurs, a non-zero value is returned.

DIAGNOSTICS

All error messages and warning messages of config are sent to stderr. Status report messages are sent to stdout. These messages are self explanatory. Some messages are generated by make or commands called from the makefiles.

FILES

/usr/conf/master.d/*: Default input master configuration tables
/usr/conf/interface.d/*: Interface files
/usr/conf/gen/config.sys: Contains skeleton makefile
/usr/conf/gen/config.lm: Contains skeleton makefile for kernel modules
/stand/system: Default system file
/stand/system.d/*: Default kernel module description files
/stand/build/conf.c: Default output configuration table
/stand/build/tune.h: Default output system parameter table
/stand/build/config.mk: Default output make(1) script
/stand/build/config.mod: Default kernel module make(1) script
/stand/build/vmunix_test: Default kernel made by config
/stand/build/dlkm.vmunix_test/symtab: Default kernel symbol table
/stand/build/dlkm.vmunix_test/mod.d/*: Default kernel module loadable image
/stand/build/dlkm.vmunix_test/mod_register: Default module registry file

config(1M)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

DESCRIPTION

Whole Kernel Configuration (First Form)

Options for Whole Kernel Configuration

Constructing an HP-UX System File

Dynamically Loadable Module Configuration (Second Form)

Options for Loadable Module Configuration

Kernel Module System Description File

RETURN VALUE

DIAGNOSTICS

FILES

SEE ALSO