Wed Mar 14 02:47:42 2018 UTC ()
Update to describe module aliases.


(pgoyette)
diff -r1.42.2.3 -r1.42.2.4 src/share/man/man9/module.9
cvs diff -r1.42.2.3 -r1.42.2.4 src/share/man/man9/module.9 (expand / switch to unified diff)

--- src/share/man/man9/module.9 2018/03/11 00:44:32 1.42.2.3
+++ src/share/man/man9/module.9 2018/03/14 02:47:41 1.42.2.4
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: module.9,v 1.42.2.3 2018/03/11 00:44:32 pgoyette Exp $ 1.\" $NetBSD: module.9,v 1.42.2.4 2018/03/14 02:47:41 pgoyette Exp $
2.\" 2.\"
3.\" Copyright (c) 2010 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2010 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Andrew Doran. 7.\" by Andrew Doran.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -17,42 +17,43 @@ @@ -17,42 +17,43 @@
17.\" 17.\"
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd December 16, 2017 30.Dd March 14, 2018
31.Dt MODULE 9 31.Dt MODULE 9
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm module , 34.Nm module ,
35.Nm module_load , 35.Nm module_load ,
36.Nm module_autoload , 36.Nm module_autoload ,
37.Nm module_unload , 37.Nm module_unload ,
38.Nm module_init_class , 38.Nm module_init_class ,
39.Nm module_hold , 39.Nm module_hold ,
40.Nm module_rele , 40.Nm module_rele ,
41.Nm module_find_section 41.Nm module_find_section
42.Nd kernel module loader 42.Nd kernel module loader
43.Sh SYNOPSIS 43.Sh SYNOPSIS
44.In sys/module.h 44.In sys/module.h
45.Fn MODULE "class" "name" "required" 45.Fn MODULE "class" "name" "required"
 46.Fn MODULE_WITH_ALIAS "class" "name" "required" "aliases"
46.Ft int 47.Ft int
47.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" \ 48.Fn module_load "const char *name" "int flags" "prop_dictionary_t props" \
48"modclass_t class" 49"modclass_t class"
49.Ft int 50.Ft int
50.Fn module_autoload "const char *name" "modclass_t class" 51.Fn module_autoload "const char *name" "modclass_t class"
51.Ft int 52.Ft int
52.Fn module_unload "const char *name" 53.Fn module_unload "const char *name"
53.Ft void 54.Ft void
54.Fn module_init_class "modclass_t class" 55.Fn module_init_class "modclass_t class"
55.Ft int 56.Ft int
56.Fn module_hold "const char *name" 57.Fn module_hold "const char *name"
57.Ft void 58.Ft void
58.Fn module_rele "const char *" 59.Fn module_rele "const char *"
@@ -85,29 +86,32 @@ type provides storage to describe a modu @@ -85,29 +86,32 @@ type provides storage to describe a modu
85.It 86.It
86The 87The
87.Vt modinfo_t 88.Vt modinfo_t
88type resides within 89type resides within
89.Vt module_t 90.Vt module_t
90and contains module header info. 91and contains module header info.
91.El 92.El
92.Pp 93.Pp
93The module subsystem is protected by the global 94The module subsystem is protected by the global
94.Va kernconfig_mutex . 95.Va kernconfig_mutex .
95.Sh FUNCTIONS 96.Sh FUNCTIONS
96.Bl -tag -width abcd 97.Bl -tag -width abcd
97.It Fn MODULE "class" "name" "required" 98.It Fn MODULE "class" "name" "required"
 99.It Fn MODULE_WITH_ALIASES "class" "name" "required" "aliases"
98The 100The
99.Fn MODULE 101.Fn MODULE
100macro creates and initializes a 102and
 103.Fn MODULE_WITH_ALIASES
 104macros create and initialize a
101.Vt modinfo_t 105.Vt modinfo_t
102structure. 106structure.
103The 107The
104.Fa class 108.Fa class
105argument identifies the class of module, and must be one of the following: 109argument identifies the class of module, and must be one of the following:
106.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent 110.Bl -tag -width MODULE_CLASS_SECMODEL -offset indent
107.It Dv MODULE_CLASS_VFS 111.It Dv MODULE_CLASS_VFS
108The module provide a virtual file system - see 112The module provide a virtual file system - see
109.Xr vfs 9 113.Xr vfs 9
110.It Dv MODULE_CLASS_DRIVER 114.It Dv MODULE_CLASS_DRIVER
111The module is a device driver - see 115The module is a device driver - see
112.Xr driver 9 116.Xr driver 9
113.It Dv MODULE_CLASS_EXEC 117.It Dv MODULE_CLASS_EXEC
@@ -130,27 +134,50 @@ The @@ -130,27 +134,50 @@ The
130argument provides the name of the module. 134argument provides the name of the module.
131Loaded modules, including those that are built-in to the kernel, must all 135Loaded modules, including those that are built-in to the kernel, must all
132have unique names. 136have unique names.
133.Pp 137.Pp
134The 138The
135.Fa required 139.Fa required
136argument is a quoted string containing a comma-separated list of module 140argument is a quoted string containing a comma-separated list of module
137names that are required by this module. 141names that are required by this module.
138The list must not contain any white-space. 142The list must not contain any white-space.
139When a module is loaded, all of its required modules are auto-loaded and 143When a module is loaded, all of its required modules are auto-loaded and
140initialized before the module itself is loaded. 144initialized before the module itself is loaded.
141Loading of required modules is a recursive operation. 145Loading of required modules is a recursive operation.
142.Pp 146.Pp
143If there are no required modules, this argument should be specified as 147The
 148.Fa aliases
 149argument is a pointer to a NULL-terminated constant array of constant
 150strings.
 151Each string in the array is an alternate name (i.e., an alias) of the
 152module.
 153Module names and aliases must all be unique; a module cannot be loaded
 154if its name or any of its aliases matches the name or an alias of any
 155already-loaded module.
 156(Module names are displayed by the
 157.Xr modstat 8
 158utility, with an
 159.Dv A
 160in the flags column.)
 161.Pp
 162For example,
 163.Bd -literal
 164 const char * const my_pets[] = { "dog", "cat", "bird", NULL };
 165
 166 MODULE_WITH_ALIASES(MODULE_CLASS_MISC, pets, NULL, &my_pets);
 167.Ed
 168.Pp
 169If there are no required modules or aliases, these argument should be
 170specified as
144.Dv NULL . 171.Dv NULL .
145.Pp 172.Pp
146In addition to the explicit arguments, the 173In addition to the explicit arguments, the
147.Fn MODULE 174.Fn MODULE
148macro creates a reference to the module's 175macro creates a reference to the module's
149.Fn modcmd 176.Fn modcmd
150function. 177function.
151This function is defined as: 178This function is defined as:
152.Bl -tag -width modcmd -offset indent 179.Bl -tag -width modcmd -offset indent
153.It Ft int 180.It Ft int
154.Fn xxx_modcmd "modcmd_t cmd" "void *data" 181.Fn xxx_modcmd "modcmd_t cmd" "void *data"
155.El 182.El
156.Pp 183.Pp