|-v||Verbose mode, print some debugging info.|
|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.|
|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.|
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.
The values to be written to the table. If they are not specified,
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.
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.
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
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
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.
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.
The kldpatch utility first appeared in
.Fx 8.0 inspired by a similar feature present on Linux.
.An -nosplit The kldpatch utility was designed and implemented by
.An Luigi Rizzo Aq luigi@FreeBSD.org .