Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
KLDPATCH(8)		  BSD System Manager's Manual		   KLDPATCH(8)

     kldpatch -- print/modify device/quirk tables in kernel modules

     kldpatch [-v] [-m file] [-t file |	format]	module_name table_name
	      [@offset [args ...]]

     The kldpatch utility can print or alter the content of device/quirk ta-
     bles in kernel modules. These tables are generally	used to	identify de-
     vices, and	possibly apply specific	quirks to enable/disable certain fea-

     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.

     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

	     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 el-
	     ement 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	re-

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

     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.

     kldconfig(8), kldload(8), kldstat(8), kldunload(8)

     The kldpatch utility first	appeared in FreeBSD 8.0	inspired by a similar
     feature present on	Linux.

     The kldpatch utility was designed and implemented by Luigi	Rizzo

BSD				January	1, 2009				   BSD


Want to link to this manual page? Use this URL:

home | help