Take a first stab at documenting use of MODULE_PNP_INFO
Sponsored by: Dell EMC Isilon
This commit is contained in:
parent
e8a81142ab
commit
4777ab9764
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=329185
@ -28,7 +28,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd January 15, 2017
|
.Dd February 12, 2018
|
||||||
.Dt DRIVER_MODULE 9
|
.Dt DRIVER_MODULE 9
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -144,6 +144,7 @@ for a specific pass level.
|
|||||||
.Xr device 9 ,
|
.Xr device 9 ,
|
||||||
.Xr driver 9 ,
|
.Xr driver 9 ,
|
||||||
.Xr module 9 ,
|
.Xr module 9 ,
|
||||||
|
.Xr MODULE_PNP_INFO 9 ,
|
||||||
.Xr SYSINIT 9
|
.Xr SYSINIT 9
|
||||||
.Sh AUTHORS
|
.Sh AUTHORS
|
||||||
This manual page was written by
|
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 \
|
mod_cc.9 \
|
||||||
module.9 \
|
module.9 \
|
||||||
MODULE_DEPEND.9 \
|
MODULE_DEPEND.9 \
|
||||||
|
MODULE_PNP_INFO.9 \
|
||||||
MODULE_VERSION.9 \
|
MODULE_VERSION.9 \
|
||||||
mtx_pool.9 \
|
mtx_pool.9 \
|
||||||
mutex.9 \
|
mutex.9 \
|
||||||
|
@ -28,7 +28,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd July 19, 2007
|
.Dd February 12, 2018
|
||||||
.Dt MODULE 9
|
.Dt MODULE 9
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -112,6 +112,7 @@ DECLARE_MODULE(foo, mod_data, SI_SUB_EXEC, SI_ORDER_ANY);
|
|||||||
.Xr DEV_MODULE 9 ,
|
.Xr DEV_MODULE 9 ,
|
||||||
.Xr DRIVER_MODULE 9 ,
|
.Xr DRIVER_MODULE 9 ,
|
||||||
.Xr MODULE_DEPEND 9 ,
|
.Xr MODULE_DEPEND 9 ,
|
||||||
|
.Xr MODULE_PNP_INFO 9 ,
|
||||||
.Xr MODULE_VERSION 9 ,
|
.Xr MODULE_VERSION 9 ,
|
||||||
.Xr SYSCALL_MODULE 9
|
.Xr SYSCALL_MODULE 9
|
||||||
.Pp
|
.Pp
|
||||||
|
Loading…
Reference in New Issue
Block a user