From owner-svn-src-all@freebsd.org Mon Feb 12 22:42:08 2018 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 0F92BF00079; Mon, 12 Feb 2018 22:42:08 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 7E5CC72B7D; Mon, 12 Feb 2018 22:42:07 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 794CF183C6; Mon, 12 Feb 2018 22:42:07 +0000 (UTC) (envelope-from cem@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id w1CMg7JM030833; Mon, 12 Feb 2018 22:42:07 GMT (envelope-from cem@FreeBSD.org) Received: (from cem@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id w1CMg7lo030828; Mon, 12 Feb 2018 22:42:07 GMT (envelope-from cem@FreeBSD.org) Message-Id: <201802122242.w1CMg7lo030828@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: cem set sender to cem@FreeBSD.org using -f From: Conrad Meyer Date: Mon, 12 Feb 2018 22:42:07 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r329185 - head/share/man/man9 X-SVN-Group: head X-SVN-Commit-Author: cem X-SVN-Commit-Paths: head/share/man/man9 X-SVN-Commit-Revision: 329185 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.25 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 12 Feb 2018 22:42:08 -0000 Author: cem Date: Mon Feb 12 22:42:06 2018 New Revision: 329185 URL: https://svnweb.freebsd.org/changeset/base/329185 Log: Take a first stab at documenting use of MODULE_PNP_INFO Sponsored by: Dell EMC Isilon Added: head/share/man/man9/MODULE_PNP_INFO.9 (contents, props changed) Modified: head/share/man/man9/DRIVER_MODULE.9 head/share/man/man9/Makefile head/share/man/man9/module.9 Modified: head/share/man/man9/DRIVER_MODULE.9 ============================================================================== --- head/share/man/man9/DRIVER_MODULE.9 Mon Feb 12 22:21:11 2018 (r329184) +++ head/share/man/man9/DRIVER_MODULE.9 Mon Feb 12 22:42:06 2018 (r329185) @@ -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 Added: head/share/man/man9/MODULE_PNP_INFO.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/MODULE_PNP_INFO.9 Mon Feb 12 22:42:06 2018 (r329185) @@ -0,0 +1,179 @@ +.\" Copyright (c) 2018 Conrad Meyer +.\" 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 +#include +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 . Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Mon Feb 12 22:21:11 2018 (r329184) +++ head/share/man/man9/Makefile Mon Feb 12 22:42:06 2018 (r329185) @@ -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 \ Modified: head/share/man/man9/module.9 ============================================================================== --- head/share/man/man9/module.9 Mon Feb 12 22:21:11 2018 (r329184) +++ head/share/man/man9/module.9 Mon Feb 12 22:42:06 2018 (r329185) @@ -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_AN .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