Take a first stab at documenting use of MODULE_PNP_INFO

Sponsored by:	Dell EMC Isilon

share/man/man9/DRIVER_MODULE.9

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

share/man/man9/MODULE_PNP_INFO.9

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

share/man/man9/Makefile

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

share/man/man9/module.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