NAME

kldpatch —

print/modify device/quirk tables in kernel modules

SYNOPSIS

kldpatch [-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 Section 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-memory copy. Use this option when you want to make the change persistent 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 modify. 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 DESCRIPTION

kldpatch 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

WARNINGS

kldpatch 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.

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⟩.