mk_kernel(1M)

NAME

mk_kernel — build a bootable HP-UX kernel and/or kernel modules

SYNOPSIS

/usr/sbin/mk_kernel [-o pathname] [-s system_file] [-S] [-v]

/usr/sbin/mk_kernel -M module_name [[-M module_name]...] [-v]

DESCRIPTION

mk_kernel builds an executable file (a kernel) and associated kernel components that can be used to boot an HP-UX system. If the build succeeds, the following files are generated:

main kernel file
This is the kernel file vmunix_test, created in the build directory as described below, that contains the kernel image corresponding to the static portion of the kernel.
associated kernel component set
This is the distributed set of associated kernel files required to boot and run the generated kernel. The files in the kernel component set are associated to each other via a unique kernel ID string (KIS). The KIS associated to a given kernel can be retrieved with the kmpath command. Among other files, the files under /stand/dlkm.KIS are generated, including the loadable kernel module images, and the kernel symbol table.

The build directory is the target directory where mk_kernel places its generated files and directories. In addition to the static kernel image, files such as conf.c, conf.o, and tune.h are also placed in the build directory.

If the path used to designate the HP-UX system description file (also known as the traditional system file) is /stand/system, the build directory is /stand/build. If another path is used to designate the system description file, the build directory is the current working directory.

In addition to the system-wide information maintained in the HP-UX system description file, mk_kernel takes the following as input to generate kernels and loadable module images: a set of kernel module description files (modular), a set of master configuration files that describe the kernel components installed on the system (modular and traditional), a set of kernel archive libraries (traditional), and a set of kernel module object files (modular). Refer to config(1M) for a definition of traditionally packaged and modularly packaged modules.

If the -o option is not specified, the static kernel file remains in the build directory. The kmupdate command must be called explicitly to pre-enable the system to use this kernel and to trigger the replacement of the default kernel during the next shutdown.

If -o /stand/vmunix is specified, the target default kernel file is not overwritten. The new kernel file vmunix_test is moved to the default path as the system shuts down, and the previous version of the default file is saved as /stand/vmunix.prev. Until the system reboots, the new kernel file must be kept as vmunix_test.

If the -o option is specified with other than /stand/vmunix, the newly generated kernel file vmunix_test is renamed immediately. In case the administrator needs to later move this kernel to the system default path, the kmupdate command must be called explicitly. kmupdate pre-enables the system to use this kernel and triggers the replacement of the default kernel during the next shutdown. Manually replacing the default kernel (/stand/vmunix) or any file in its associated kernel component set (named via the kernel's KIS) can result in an unbootable kernel and must be avoided.

mk_kernel exits with no action if the environment variable SW_INITIAL_INSTALL has the value of 1. SW_INITIAL_INSTALL is exported by SD with that value only when the system is undergoing its initial software system installation.

Options

mk_kernel recognizes the following options.

-M module_name

Specify the DLKM module to configure. Dynamically loadable kernel modules are separate objects that can be independently configured into the system without requiring a reboot. No kernel image will be generated. For details see config(1M).

-o pathname

Specify the target kernel path. The newly created kernel file, vmunix_test, is moved from the build directory to the path specified by pathname, and the system is pre-enabled to use this new kernel.

If the default kernel, /stand/vmunix, is specified, the created kernel file does not immediately replace /stand/vmunix and remains as vmunix_test. The kernel file is automatically moved to /stand/vmunix during shutdown.

If the -o option is not specified, the created kernel file remains as vmunix_test, and the kmupdate command must be called explicitly to pre-enable the system to use this kernel and to trigger the replacement of the default kernel during the next shutdown. For details see kmupdate(1M).

-s system_file

Specify the HP-UX system description file. If this option is not specified, the system file /stand/system is used. For details see system(4).

-S

Specify that all kernel modules scheduled for configuration are to be statically linked into the kernel. For details see kmsystem(1M) and config(1M).

-v

Verbose mode.

RETURN VALUE

mk_kernel returns 0 upon normal completion, and 1 if an error occurred.

DIAGNOSTICS

Messages and warnings are sent to stdout. Messages from config and other commands are displayed when invoked from mk_kernel. Errors cause mk_kernel to halt immediately; warnings allow the program to continue.

EXAMPLES

mk_kernel -o /stand/vmunix

Uses the default HP-UX system description file /stand/system when building a new kernel and kernel modules. The new kernel file is placed in /stand/build/vmunix_test upon success. Additional files that comprise the kernel's component set are identified via a unique kernel ID string (KIS) defined by the newly built kernel. The system is pre-enabled to use this new kernel, and /stand/build/vmunix_test is moved automatically to /stand/vmunix during shutdown. The current default kernel is saved as /stand/vmunix.prev.

mk_kernel -s /mnt/altsys/stand/system.new

Uses the system description file /mnt/altsys/stand/system.new when building a new kernel and kernel modules. The new kernel is named vmunix_test in the current working directory. kmupdate must be called explicitly to pre-enable the system to use this kernel and to trigger the replacement of the default kernel during the next shutdown.

mk_kernel -s /stand/system -o /tmp/new_kernel

Uses the file /stand/system when building a new kernel and kernel modules. The new kernel file is placed in /tmp/new_kernel, and the system is pre-enabled to use this new kernel. If the administrator wants to use this kernel as the default kernel, the kmupdate command can be used.

WARNINGS

Do not manually copy the kernel or manually update the current kernel file with its associated kernel component set. To update the default kernel, always use the kmupdate command.

The kernel relies on several distributed files (the kernel component set) associated to the kernel via a unique kernel ID string. Missing files may result in a kernel that does not boot or is not fully enabled. These files include:

Files under /stand/dlkm.KIS
These include the dynamically loadable kernel module images and other DLKM information.
Kernel registry (KRS) files /stand/krs/KIS.*
These files store module registration information and other kernel-specific persistent information.

Never manually remove a kernel file; this will leave its associated component set orphaned. Instead, use kmupdate -d kernel_name to remove a kernel and the various distributed files that make up its associated kernel component set.

FILES

/stand/vmunix: Default kernel
/stand/dlkm.KIS: Kernel function set directory
/stand/krs/KIS.*: Kernel registry files
/stand/system: Default HP-UX system description file
/stand/build/vmunix_test: Kernel file built by mk_kernel
/stand/vmunix.prev: Saved kernel