KLDPATCH(8) BSD System Manager's Manual KLDPATCH(8)NAMEkldpatch — print/modify device/quirk tables in kernel modules
SYNOPSISkldpatch [-v] [-m file] [-t file | format] module_name table_name
[@offset [args ...]]
DESCRIPTION
The kldpatch utility can print or alter the content of device/quirk
tables in kernel modules. These tables are generally used to identify
devices, and possibly apply specific quirks to enable/disable certain
features.
kldpatch is especially useful to let the kernel recognise a new device
without rebooting and rebuilding/reinstalling kernel or modules, see Sec‐
tion EXAMPLES for some examples of use.
OPTIONS
The following options and arguments can be used:
-v Verbose mode, print some debugging info.
-m file
Patch the module specified as an argument instead of the in-mem‐
ory copy. Use this option when you want to make the change per‐
sistent across reboots.
-t file | format
Specify the name and structure of descriptor tables that can be
manipulated by kldpatch. The argument can be a filename, or the
description itself, as documented in Section MODULE DESCRIPTION.
module_name table_name
The module and table that we want to print/modify. Both values
are compared against the content of the description file until a
match is found. A value of ``-'' in either parameter indicates a
wildcard.
@offset
Specify the entry in the quirk table that we want to list or mod‐
ify. Values start from 0, and negative offsets can be used to
count from the end of the table, with @-1 indicating the last
element in the table, @-2 the previous one, and so on.
If @offset is not specified, then kldpatch operates in read mode
and lists the full content of the table.
args The values to be written to the table. If they are not specified,
kldpatch operates in read mode and prints the entry specified
with the @offset argument. If they are present, they are checked
against the description of the matching module/table and changes
are applied to the memory or file version of the table, as
required.
MODULE DESCRIPTIONkldpatch relies on a list describing which modules and tables (associated
to kernel symbols) it can work on, and what is the format of the records
in each table.
By default kldpatch uses an internal list, which can be overridden from
the command line using the -t option followed by either a file name, or
by immediate text.
In write mode, kldpatch checks that the arguments (module and table name,
offset, parameters formats) are compatible with the structure indicated
in the description, and also with the content of the module itself.
The file (or text) containing the module description has a simple text
format with one line per table. The `#' character is a comment delimiter,
and can appear anywhere in the text. Each valid line must contain the
following fields:
module_name symbol_name entry_format [entry_format ...]
Each entry_format describes one field in the table, and it is made of a
number and/or a character specifying the field size and format, followed
by an optional ':' and a word describing the field itself.
Supported formats are:
1 8-bit unsigned;
2 | 2l | 2b
16-bit unsigned in host, little-endian or big-endian format;
4 | 4l | 4b
32-bit unsigned in host, little-endian or big-endian format;
8 | 8l | 8b
64-bit unsigned in host, little-endian or big-endian format;
p a pointer;
s a null-terminated string;
The optional description is used as a header when listing the content of
a table.
EXAMPLE MODULE DESCRIPTION
The following is an example of a file containing module descriptions.
umass.ko umass_devdescrs 4:vendor 4:product 4:rev 2:proto 2:quirks
uscanner.ko uscanner_devs 2:vendor 2:device 4:flags # comment
if_nfe.ko nfe_devs 2:vendor 2:device s:name
if_re.ko re_devs 2:vendor 2:device 4:type s:name
EXAMPLES
Spme examples of use:
kldpatch umass.ko - @0 0x4050 0x4a5 0x0101 0x4200
tell the kernel (actually, the umass module) to use flags
"UMASS_PROTO_SCSI | UMASS_PROTO_BBB" and quirks "WRONG_CSWSIG |
NO_SYNCHRONIZE_CACHE" for a certain GSM phone that implements the
umass interface;
kldpatch uscanner.ko - @0 0x04b8 0x084a 0
let uscanner.ko recognise a newly introduced MFP scanner device.
kldpatch-m /boot/kernel/uscanner.ko uscanner.ko - @0 0x04b8 0x084a 0
as above, but patch the actual file instead of the in-memory copy of
the module, so the effects will be visible when the module is loaded
next.
kmodpatch if_re -
print all entries in module if_re.
kmodpatch umass - @-1
print the last entry in module umass.
kmodpatch uscanner.ko - @-1 0x04b8 0x0839 0
set the last entry in module uscanner.ko
WARNINGSkldpatch requires root privileges even to just read the content of the
kernel tables.
In write mode, the use of kldpatch is as dangerous as accessing /dev/kmem
in write mode, even though kldpatch does some amount of checking to make
sure that the arguments passed are reasonable. To this purpose, it is
fundamental that the table descriptions used by kldpatch match the actual
structure of the kernel tables. There is no automatic way to extract
this info.
BUGS
The algorithm used to navigate ELF files (.ko modules and the kernel)
when using the -m option makes some assumptions on the structure of the
files which should be verified at runtime.
SEE ALSOkldconfig(8), kldload(8), kldstat(8), kldunload(8)HISTORY
The kldpatch utility first appeared in FreeBSD 8.0 inspired by a similar
feature present on Linux.
AUTHORS
The kldpatch utility was designed and implemented by Luigi Rizzo
⟨luigi@FreeBSD.org⟩.
BSD January 1, 2009 BSD
