Take a first stab at documenting use of MODULE_PNP_INFO
Sponsored by: Dell EMC Isilon
This commit is contained in:
Conrad Meyer
parent
e8a81142ab
commit
4777ab9764
@ -28,7 +28,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd January 15, 2017
|
||||
.Dd February 12, 2018
|
||||
.Dt DRIVER_MODULE 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -144,6 +144,7 @@ for a specific pass level.
|
||||
.Xr device 9 ,
|
||||
.Xr driver 9 ,
|
||||
.Xr module 9 ,
|
||||
.Xr MODULE_PNP_INFO 9 ,
|
||||
.Xr SYSINIT 9
|
||||
.Sh AUTHORS
|
||||
This manual page was written by
|
||||
|
||||
179
share/man/man9/MODULE_PNP_INFO.9
Normal file
179
share/man/man9/MODULE_PNP_INFO.9
Normal file
@ -0,0 +1,179 @@
|
||||
.\" Copyright (c) 2018 Conrad Meyer <cem@FreeBSD.org>
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd February 12, 2018
|
||||
.Dt MODULE_PNP_INFO 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm MODULE_PNP_INFO
|
||||
.Nd register plug and play information for device matching
|
||||
.\"
|
||||
.Sh SYNOPSIS
|
||||
.In sys/module.h
|
||||
.Fo MODULE_PNP_INFO
|
||||
.Fa "const char *descriptor_string"
|
||||
.Fa "bus"
|
||||
.Fa "module"
|
||||
.Fa "void *table"
|
||||
.Fa "size_t entry_len"
|
||||
.Fa "size_t num_entries"
|
||||
.Fc
|
||||
.\"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn MODULE_PNP_INFO
|
||||
macro registers a
|
||||
.Fa table
|
||||
of device-identifying data for use by
|
||||
.Xr devmatch 8 .
|
||||
.Pp
|
||||
The macro takes a
|
||||
.Fa descriptor_string
|
||||
that describes the memory layout of table entries.
|
||||
The string is a series of members separated by semi-colons.
|
||||
Members are identified by a type and a name.
|
||||
They are encoded in the descriptor string by concatenating the type with a
|
||||
colon, followed by the name.
|
||||
(The special type
|
||||
.Vt W32
|
||||
represents two members.
|
||||
The first name is encoded like any other type.
|
||||
The second name is encoded by appending a forward slash and the second
|
||||
name after the first.)
|
||||
.Pp
|
||||
Types are one of the following:
|
||||
.Bl -tag -width U16
|
||||
.It Dq Vt U8
|
||||
.Vt uint8_t
|
||||
element.
|
||||
.It Dq Vt V8
|
||||
Same as
|
||||
.Vt U8 ,
|
||||
except that the sentinel value 0xFF matches any.
|
||||
.It Dq Vt G16
|
||||
.Vt uint16_t
|
||||
element; any value greater than or equal matches.
|
||||
.It Dq Vt L16
|
||||
.Vt uint16_t
|
||||
element; any value less than or equal matches.
|
||||
.It Dq Vt M16
|
||||
.Vt uint16_t
|
||||
element; mask of which of the following fields to use.
|
||||
.It Dq Vt U16
|
||||
.Vt uint16_t
|
||||
element.
|
||||
.It Dq Vt V16
|
||||
Same as
|
||||
.Vt U16 ,
|
||||
except that the sentinel value 0xFFFF matches any.
|
||||
.It Dq Vt U32
|
||||
.Vt uint32_t
|
||||
element.
|
||||
.It Dq Vt V32
|
||||
Same as
|
||||
.Vt U32 ,
|
||||
except that the sentinel value 0xFFFFFFFF matches any.
|
||||
.It Dq Vt W32
|
||||
Two
|
||||
.Vt uint16_t
|
||||
values; the first named member is in the least significant word and the second
|
||||
named member is in the most significant word.
|
||||
.It Dq Vt Z
|
||||
A pointer to a string to match exactly.
|
||||
.It Dq Vt D
|
||||
A pointer to a human readable description for the device.
|
||||
.It Dq Vt P
|
||||
A pointer that should be ignored.
|
||||
.It Dq Vt E
|
||||
EISA PNP Identifier.
|
||||
.El
|
||||
.Pp
|
||||
The pseudo-name
|
||||
.Dq #
|
||||
is reserved for fields that should be ignored.
|
||||
Any member that does not match the parent device's pnpinfo output must be
|
||||
ignored.
|
||||
.Pp
|
||||
The
|
||||
.Fa bus
|
||||
parameter is an unquoted word naming the parent bus of the driver.
|
||||
For example,
|
||||
.Dq pci .
|
||||
.Pp
|
||||
The
|
||||
.Fa module
|
||||
parameter is also an unquoted word.
|
||||
It must be unique to the driver.
|
||||
Usually the driver's name is used.
|
||||
.Pp
|
||||
The
|
||||
.Fa table
|
||||
parameter points to the device matching data with entries matching the
|
||||
.Fa descriptor_string .
|
||||
.Pp
|
||||
The
|
||||
.Fa entry_len
|
||||
parameter is the size of each table entry, i.e.,
|
||||
.Ql sizeof(table[0]) .
|
||||
.Pp
|
||||
The
|
||||
.Fa num_entries
|
||||
parameter is the number of entries in the table, i.e.,
|
||||
.Ql nitems(table) .
|
||||
Note that only valid entries should be included.
|
||||
If the table contains trailing zero or bogus values, they should not be
|
||||
included in
|
||||
.Fa num_entries .
|
||||
.\"
|
||||
.Sh EXAMPLES
|
||||
.Bd -literal -offset indent -compact
|
||||
#include <sys/param.h>
|
||||
#include <sys/module.h>
|
||||
static struct my_pciids {
|
||||
uint32_t devid;
|
||||
const char *desc;
|
||||
} my_ids[] = {
|
||||
{ 0x12345678, "Foo bar" },
|
||||
{ 0x9abcdef0, "Baz fizz" },
|
||||
};
|
||||
MODULE_PNP_INFO("W32:vendor/device", pci, my_driver, my_ids, sizeof(my_ids[0]),
|
||||
nitems(my_ids));
|
||||
.Ed
|
||||
.\"
|
||||
.Sh SEE ALSO
|
||||
.Xr module 9 ,
|
||||
.Xr DRIVER_MODULE 9 ,
|
||||
.Xr devmatch 8
|
||||
.Sh HISTORY
|
||||
The macro
|
||||
.Nm
|
||||
appeared in
|
||||
.Fx 12.0 .
|
||||
.Sh AUTHORS
|
||||
The PNP framework and
|
||||
.Xr devmatch 8
|
||||
utility were written by
|
||||
.An Warner Losh Aq Mt imp@FreeBSD.org .
|
||||
@ -199,6 +199,7 @@ MAN= accept_filter.9 \
|
||||
mod_cc.9 \
|
||||
module.9 \
|
||||
MODULE_DEPEND.9 \
|
||||
MODULE_PNP_INFO.9 \
|
||||
MODULE_VERSION.9 \
|
||||
mtx_pool.9 \
|
||||
mutex.9 \
|
||||
|
||||
@ -28,7 +28,7 @@
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd July 19, 2007
|
||||
.Dd February 12, 2018
|
||||
.Dt MODULE 9
|
||||
.Os
|
||||
.Sh NAME
|
||||
@ -112,6 +112,7 @@ DECLARE_MODULE(foo, mod_data, SI_SUB_EXEC, SI_ORDER_ANY);
|
||||
.Xr DEV_MODULE 9 ,
|
||||
.Xr DRIVER_MODULE 9 ,
|
||||
.Xr MODULE_DEPEND 9 ,
|
||||
.Xr MODULE_PNP_INFO 9 ,
|
||||
.Xr MODULE_VERSION 9 ,
|
||||
.Xr SYSCALL_MODULE 9
|
||||
.Pp
|
||||
|
||||
Loading…
Reference in New Issue
Block a user