irix-657m-src/eoe/man/man4/mload.4

.nr X
.if \nX=0 .ds x} mload 4
.TH \*(x}
.SH NAME
mload \- dynamically loadable kernel modules
.SH DESCRIPTION
IRIX supports dynamic loading and unloading
of modules into a running kernel.
Kernel modules
can be registered and then loaded automatically
by the kernel when the corresponding device is
opened, or they can be loaded manually.
Similarly,
dynamically loaded modules can be unloaded automatically
or manually if the module includes an \f3unload\f1 entry point.
A loadable kernel module can be a character, block or streams
device driver, a streams module, a library module or the \f2idbg.o\f1
module.
.SS Module Configuration
Each loadable module should contain the string:
.Ex
\f4char *\f1\f2prefix\f1\f4mversion = M_VERSION;\f1
.Ee
M_VERSION is defined in the \f2mload.h\fP header file, which should
be included by the loadable module.
.PP
A number of \f2cc\fP flags must be defined correctly when compiling
loadable modules for Irix.  To ensure that you get the correct flags,
use the sample makefile in /var/sysgen/Makefile.kernloadio from the
eoe.hdr.lib subsystem.  Instructions for using the makefile are at the
beginning of the Makefile.kernloadio file.
.sp .8v
A loadable module must not be dependent on any loadable module, other
than a library module.  In order to load a module comprised of multiple
object files, the object files should be linked together into a single
object file, using the following \f2ld\fP options:  \f3\-G0 \-r \-d\fP
.SS Loading a Dynamically Loadable Kernel Module
Either \f2lboot\fP or the \f2ml\fP command can be used to
load, register, unload, unregister, and list loadable kernel
modules.
The \f2lboot\f1 command parses module type, prefix and
major number information from the module's master file found
in the \f2/var/sysgen/master.d\f1 directory.
The loadable
object file is expected to be found in the \f2/var/sysgen/boot\f1
directory.
The \f2ml\f1 command also provides a means of loading,
registering and unloading loadable modules, without the need
for creating a master file or reconfiguring the kernel.
.TP
Load\ \ \ \&
When a module is loaded, the object file's header is read;
memory is allocated for the module's text, data and bss;
the module's text and data are read;
the module's text and data are relocated and
unresolved references into the kernel are resolved;
a symbol table is created for the module;
the module is added to the appropriate kernel switch table;
and the module's init routine is called.
.IP
A module is loaded using the following \f2ml\fP command:
.sp .8v
.RS
.nf
	\f4ml ld \f1[\f4-v\f1] \f4-\f1[\f4cbBfmi\f1] \f2module.o\f1 \f4-p\f1 \c
\f2prefix\f1 [\f4-s\f1 \f2major major\f1 ...]
	[\f4-a\f1 \f2modname\f1]
.fi
.RE
.IP
If a module is loaded successfully, an id number is
returned which can be used to unload the module.
.IP
A module can also be loaded using \f2lboot\fP:
.sp .8v
.RS
	\f4lboot -L\f1 \f2master\f1
.RE
.TP
Register
The register command is used to register a module for
loading when its corresponding device is opened.
When a
module is registered, a stub routine is entered into the
appropriate kernel switch table.
When the corresponding
device is opened, the module is actually loaded.
.IP
A module is registered using the following \f2ml\fP command:
.sp .8v
.RS
.nf
	\f4ml reg\f1 [\f4-v\f1] \f4-\f1[\f4cbBfmi\f1] \f2module.o\f1 \f4-p\f1 \c
\f2prefix\f1 [\f4-s\f1 \f2major major\f1 ...]
	[\f4-a\f1 \f2modname\f1] [\f4-t\f1 \f2autounload_delay\f1]
.fi
.RE
.IP
If a module is registered successfully, an id number is
returned which can be used to unregister the module.
.IP
A module can also be registered using \f2lboot\fP:
.sp .8v
.RS
	\f4lboot -R\f1 \f2master\f1
.RE
.TP
Unload
A module can be unloaded only if it provides an \f3unload\f1
entry point.
A module is unloaded using:
.sp .8v
.RS
	\f4ml unld\f1 \f2id\f1 [\f2id id\f1 ...]
.RE
.IP
or
.sp .8v
.RS
	\f4lboot -U\f1 \f2id\f1 [\f2id id\f1 ...]
.RE
.TP
Unregister
A module can be unregistered using:
.sp .8v
.RS
	\f4ml unreg\f1 \f2id\f1 [\f2id id\f1 ...]
.RE
.IP
or
.sp .8v
.RS
	\f4lboot -W\f1 \f2id\f1 [\f2id id\f1 ...]
.RE
.TP
List\ \ \ \&
All loaded and/or registered modules can be listed using:
.sp .8v
.RS
	\f4ml list\f1 [\f4-rlb\f1]
.RE
.IP
or
.sp .8v
.RS
	\f4lboot -V\f1
.RE
.SS Master File Configuration
If a dynamically loadable module
has an associated master file, the
master file should include a \f3d\fP in Field 1.
The \f3d\fP flag indicates to \f2lboot\fP that the module is
a dynamically loadable kernel module.
If the \f3d\fP flag
is present \f2lboot\fP will parse the module's master file,
but will not fill in the entry in the corresponding kernel
switch table for the module.
All global data defined in
the master file will be included in the generated \f2master.c\f1 file.
The kernel should be configured with
master files that contain the \f3d\fP option for each module
that will be a dynamically loadable module, if \f2lboot\f1 will be
used to load, register, unload, unregister or autoregister
the module.
If the \f2ml\f1(1M) command will be used, then it is not
necessary to create a master file for the module.
.SS Auto Registration
Loadable modules can be registered by \f2lboot\f1 automatically at
system startup when autoconfig is run.
In order for a module to
be auto-registered, its master file should contain an \f3R\f1 in
Field 1, in addition to \f3d\f1, which indicates that the module is
loadable.
When \f2lboot\f1 runs at system startup, it registers each module
that contains an \f3R\f1 in its master file.
Modules which specify
a particular major number are registered before modules which pick
a major number dynamically.
If an rc2 script is added, which
registers or loads dynamically loadable modules, it should be run
after the autoconfig rc2 script is run.
.PP
For more detailed information, see the \f2lboot\fP(1M), \f2ml\fP(1M),
and \f2master\fP(4) reference pages.
.SS Auto Unload
All registered modules that include an \f3unload\f1 routine are automatically
unloaded after last close, unless they have been configured not to.
Modules are unloaded five minutes after last close by default.
The default
auto-unload delay can be changed by using \f2systune\f1 to change the
\f2module_unld_delay\f1 variable.
For more information about systune,
see the \f2systune\fP(1M) reference page.
A particular module can be
configured with a specific auto-unload delay by using the \f2ml\f1
command.
A module can be configured to not be auto-unloaded by either
placing an \f3N\f1 in the flags field of its \f2master.d\f1 file, if it is
registered using \f2lboot\f1, or by using \f2ml\f1 to register the module and
using the \f3\-t\f1 option.
.SS Kernel Configuration
A kernel which supports loadable modules, should be configured
so that the kernel switch tables generated by \f2lboot\fP(1M)
contain "extra" entries for the loadable modules.
Extra entries
are generated by \f2lboot\fP based on the values of the following
kernel tuneable parameters:
.PP
.RS
.PD 0
.TP 12
* name                  default         minimum   maximum
.TP
\f3bdevsw_extra\fP            21              1         254
.TP
\f3cdevsw_extra\fP            23              3         254
.TP
\f3fmodsw_extra\fP            20              0
.TP
\f3vfssw_extra\fP              5              0
.RE
.PD
.PP
These tuneable parameters are found in the kernel
\f2/var/sysgen/mtune/kernel\f1 file and are set to the
defaults listed above.
For more information about
changing tuneable parameters, see the \f2mtune\fP(4)
and \f2systune\fP(1M) reference pages.
.SS Module Entry Points
Loadable device drivers should conform to the SVR4 DDI/DKI
standard.
In addition to the entry points specified by the
DDI/DKI standard, if a loadable module is to be unloaded, the
module needs to contain an \f3unload\f1 entry point:
.PP
.RS
	\f4int\f1 \f2prefix\f1\f4unload (void)\f1
.RE
.PP
An \f3unload\f1 routine should be treated as an interrupt
routine and should not call any routines that would cause it
to sleep, such as: \f3biowait\f1(), \f3sleep\f1(), \f3psema\f1()
or \f3delay\f1().
.PP
An \f3unload\f1 routine should free any resources allocated by the
driver, including freeing interrupt vectors and allocated
memory and return 0.
.SS Module Initialization
After a module is loaded, linked into the kernel and sanity
checking is done, the modules' initialization routines,
\f2prefix\f1\f3init\f1(), \f2prefix\f1\f3edtinit\f1() and
\f2prefix\f1\f3start\f1()
are called, if they exist.
For more information on these
routines, refer to the SVR4 DDI/DKI Reference Manual and the \f2IRIX
Device Driver Programmer's Guide\f1.
.SS Edt Type Drivers
For drivers that have an edtinit entry point, which get passed
a pointer to an edt structure, \f2lboot\f1 must be used to load the
driver.
A vector line should be added to the system file for the
driver, as it would for any driver.
When the module is loaded,
using \f2lboot\f1, \f2lboot\f1 parses the vector line from the system file
to create an edt structure which is passed through the kernel
and to the driver's edtinit routine.
For more information, see
the \f2system\fP(4) reference page.
.SS Library Modules
A library module is a loadable module which contains a
collection of functions and data that other loaded modules can
link against.
A library module can be loaded using the following
\f2ml\f1 command:
.Ex
\f4ml ld\f1 [\f4-v\f1] \f4-l\f1 \f2library.o\f1
.Ee
A library module must be loaded before other modules that
link against it are loaded.
Library modules can not be unloaded,
registered or unregistered.
Only regular object files
are supported as loadable library modules.
.SS The idbg.o Module
The \f2idbg.o\f1 module can be dynamically loaded into a running
kernel, so that the kernel print utility, \f2idbg\fP(1M), can be
used without reconfiguring and rebooting a new kernel.
The
\f2idbg.o\f1 module can be dynamically loaded using the \f2ml\f1 command:
.Ex
\f4ml ld -i /var/sysgen/boot/idbg.o -p idbg\f1
.Ee
The \f2idbg.o\f1 module can also be unloaded.
.PP
Other idbg modules, such as \f2xfsidbg.o\f1, \f2xlvidbg.o\f1, \f2mloadidbg.o\f1,
and so on, can be loaded after \f2idbg.o\f1 is loaded.
For example:
.Ex
\f4ml ld -i /var/sysgen/boot/xfsidbg.o -p xfsidbg.o\f1
.Ee
For more information, see the \f2idbg\fP(1M) reference page.
.SS Loadable Modules and Hardware Inventory
Many device drivers add to the hardware inventory in their init or
edtinit routines.
If a driver is a dynamically loadable driver and
is auto-registered, it will not show up in the hardware inventory
until the driver has been loaded on the first open of the corresponding
device.
If a clean install or a diskless install is done, a \f2/dev\f1 entry
will not get created by \f2MAKEDEV\f1 for such a driver since it doesn't
appear in the hardware inventory.
If such a situation arises, the \f3D\f1
\f2master.d\f1 flag can be used to indicate that the driver should be loaded,
then unloaded by \f2autoconfig\f1.
If the \f3R\f1 \f2master.d\f1 flag, which
indicates that the driver should be auto-registered, is also used, then
the driver will be auto-registered as usual.
A startup script can then
be added that will run \f2MAKEDEV\f1 after \f2autoconfig\f1, if necessary.
For an example, see the \f2/etc/init.d/chkdev\f1 startup script.
.SS Kernel Runtime Symbol Table
A runtime symbol table which contains kernel routines and
global data that modules can link against is created from the
ELF symbol information in the kernel that was booted.
The runtime
symbol table is created automatically by the kernel from the
file indicated by the \f3kernname\f1 environment variable, which
is set by sash to the name of the file that was booted.
.PP
The symbol table is loaded with a default auto-unload
timeout of five minutes, after which the symbol table is automatically
unloaded.
The symbol table is automatically reloaded when needed to
resolve symbols (for example
when a new or registered module is loaded).
.PP
The kernel runtime symbol table can also be loaded manually, using
the \f2ml\f1 command:
.Ex
\f4ml ld -r /unix\f1
.Ee
Or unloaded manually:
.Ex
\f4ml unld\f1 \f2id\f1
.Ee
Note that only one kernel runtime symbol table can exist at one time.
.PP
Auto-loading and unloading of the kernel runtime symbol table can
be disabled using the \f3mload_auto_rtsyms\f1 systune variable.
For more
information about tuneable variables, see the \f2systune\f1(1M) reference
page.
.SS Debugging Loadable Modules
\f2symmon\f1(1M) supports debugging of loadable modules.
\f2symmon\f1
commands that do a symbol table lookup, such as: brk,
lkup, lkaddr, hx and nm, also search the symbol
tables created for loadable modules.
The \f2msyms\f1
command can also be used to list the symbols for a
particular loaded module:
.Ex
\f4msyms\f1 \f2id\f1
.Ee
The \f2mlist\f1 command can be used to list all of the
modules that are currently loaded and/or registered.
.PP
For more information, see the \f2symmon\fP(1M) reference page.
.SS Load/Register Failures
If a registered module fails to load, it is suggested that the
module be unregistered and then loaded using \f3ml ld\f1 or \f3lboot \-L\f1,
in order to get a more detailed error message about the failure.
All of the error codes, including a description of each, are listed in
the \f2mload.h\f1 header file, found in the \f2/usr/include/sys\f1
directory.
.PP
The kernel will fail to load or register a module for any of the
following reasons:
.TP
1.
If autoconfig is not run at system startup, none of the dynamically
loadable modules will be registered or loaded.
.TP
2.
If autoconfig fails for some reason, before it has processed the
dynamically loadable module \f2master.d\f1 files, the modules will not be
registered or loaded.
.TP
3.
The major number specified either in the master file, or by
the ml command, is already in use.
.TP
4.
The object file is not compiled with the correct options, such
as \f3\-G0\f1 and \f3\-jalr\f1.
.TP
5.
The module is an "old style" driver, with either xxxdevflag set to
D_OLD, or no xxxdevflag exists in the driver.
.TP
6.
A corrupted object file could cause "invalid JMPADDR" errors.
.TP
7.
Not all of the module's symbols were resolved by the kernel.
.TP
8.
The device switch table is full and has no more room to add a
loadable driver.
.TP
9.
Required entry points for the particular type of module are not
found in the object file, such as xxxopen for a character device
driver.
.TP
10.
All major numbers are in use.
.TP
11.
An old sash is used to boot the kernel, which does not set the
\f3kernname\f1 environment variable, which indicates the on-disk kernel
image to load the runtime symbol table from (for example, \f2/unix\f1).
This will
cause all loadable modules to fail to load or be registered.
To
find out what the \f3kernname\f1 environment variable is set to,
use the \f2nvram\f1(1M) command:
.sp .8v
.RS
	\f4nvram kernname\f1
.RE
.TP
12.
The runtime symbol table can not be loaded from the file
indicated by the \f3kernname\f1 environment variable, because the
file does not exist, the file is not the same as the running kernel
or the kernel was bootp'ed from another machine.
.SH EXAMPLE 1
The following example lists the steps necessary to build
a kernel and load a character device driver, called dlkm,
using the \f2lboot\fP command:
.TP
1.
Add \f3d\f1 to the dlkm master file:
.sp .8v
.RS
.nf
	\f7*FLAG   PREFIX  SOFT    #DEV    DEPENDENCIES
	cd       dlkm     38      2\f1
.fi
.RE
.TP
2.
Make sure that the cdevsw_extra kernel tuneable
parameter allows for extra entries in the cdevsw table,
the default setting in \f2/var/sysgen/mtune/kernel\f1 is:
.sp .8v
.RS
	cdevsw_extra            23              3         254
.RE
.IP
The \f2systune\fP(1M) command also lists the current values of
all of the tuneable parameters.
If the kernel is not
configured to allow extra entries in the cdevsw table,
use the \f2systune\fP command to change the cdevsw_extra parameter:
.sp .8v
.RS
.nf
	> \f4systune -i\f7
	systune-> \f4cdevsw_extra 3\f7
	systune-> \f4quit\f7
	>
.fi
.RE
.TP
3.
Build a new kernel and boot the target system with the
new kernel.
.TP
4.
Compile the \f2dlkm.c\f1 driver.  It should be noted that
linking either 64bit or 32bit objects the "-non_shared"
flag is not needed.
.IP
For 32-bit modules:
.sp .8v
.RS
	\f4cc -non_shared -elf -G0 -r -d -jalr -c dlkm.c\f1
.RE
.IP
For 64-bit modules:
.sp .8v
.RS
	\f4cc -non_shared -elf -G 0 -jalr -c dlkm.c\f1
.RE
.TP
5.
Copy \f2dlkm.o\f1 to \f2/var/sysgen/boot\f1.
.TP
6.
Load the driver into the kernel:
.sp .8v
.RS
	\f4lboot -L dlkm\f1
.RE
.TP
7.
List the currently loaded modules to verify that the module
was loaded:
.sp .8v
.RS
	\f4lboot -V\f1
.RE
.SH EXAMPLE 2
The following example lists the steps necessary to load a
character device driver, called dlkm, using the \f2ml\fP command:
.TP
1.
Follow step 2 from example 1.
.TP
2.
Follow step 4 from example 1.
.TP
3.
Load the driver into the kernel:
.sp .8v
.RS
	\f4ml ld -c dlkm.o -p dlkm -s 38\f1
.RE
.IP
If a major number is not specified, the first free major
number in the MAJOR table is used.
If the load was successful,
an id number is returned, which can be used to unload the driver.
.TP
4.
List the currently loaded modules to verify that the module
was loaded:
.sp .8v
.RS
	\f4ml list\f1
.RE
.SH CAVEATS
.TP
1.
Loadable modules must not have any dependencies
on loadable modules, other than library modules.
When a
module is loaded, it is linked against the kernel symbol
table and any loaded library modules' symbol tables, but
it is not linked against other modules' symbol tables.
.TP
2.
Only character, block and streams device drivers, streams
modules and library modules are supported as loadable modules
at this time.
.TP
3.
Old style drivers (devflag set to D_OLD) are not loadable.
.TP
4.
Kernel profiling does not support loadable modules.
.TP
5.
Memory allocated may be in either K0SEG or in K2SEG.
If the
module is loaded into K2SEG static buffers are not necessarily in
physically contiguous memory.
Also, depending on machine configuration,
K2SEG addresses may map to high physical memory addresses, in which
case, PHYS_TO_K0 and PHYS_TO_K1 macros will not work.
.SH SEE ALSO
cc(1),
lboot(1M),
ld(1),
ml(1M),
symmon(1M),
systune(1M),
master(4),
mtune(4).
.PP
\f2IRIX Device Driver Programmer's Guide\f1