feat: Added NetBSD man pages

1 files changed, 507 insertions, 0 deletions

diff --git a/static/netbsd/man9/autoconf.9 b/static/netbsd/man9/autoconf.9
new file mode 100644
index 00000000..735c5711
--- /dev/null
+++ b/static/netbsd/man9/autoconf.9
@@ -0,0 +1,507 @@
+.\"     $NetBSD: autoconf.9,v 1.35 2021/08/08 16:12:10 andvar Exp $
+.\"
+.\" Copyright (c) 2001, 2002, 2021 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Gregory McGarry.
+.\"
+.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
+.\"
+.Dd August 7, 2021
+.Dt AUTOCONF 9
+.Os
+.Sh NAME
+.Nm autoconf ,
+.Nm config_search ,
+.Nm config_found ,
+.Nm config_match ,
+.Nm config_attach ,
+.Nm config_attach_pseudo ,
+.Nm config_detach ,
+.Nm config_detach_children ,
+.Nm config_deactivate ,
+.Nm config_defer ,
+.Nm config_interrupts ,
+.Nm config_mountroot ,
+.Nm config_pending_incr ,
+.Nm config_pending_decr ,
+.Nm config_finalize_register
+.Nd autoconfiguration framework
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/device.h
+.In sys/errno.h
+.Ft cfdata_t
+.Fn config_search "device_t parent" "void *aux" "const struct cfargs *"
+.Ft device_t
+.Fn config_found "device_t parent" "void *aux" "cfprint_t print" \
+"const struct cfargs *"
+.Ft int
+.Fn config_match "device_t parent" "cfdata_t cf" "void *aux"
+.Ft int
+.Fn config_probe "device_t parent" "cfdata_t cf" "void *aux"
+.Ft device_t
+.Fn config_attach "device_t parent" "cfdata_t cf" "void *aux" \
+"cfprint_t print" "const struct cfargs *"
+.Ft device_t
+.Fn config_attach_pseudo "cfdata_t cf"
+.Ft int
+.Fn config_detach "device_t dev" "int flags"
+.Ft int
+.Fn config_detach_children "device_t dev" "int flags"
+.Ft int
+.Fn config_deactivate "device_t dev"
+.Ft int
+.Fn config_defer "device_t dev" "void (*func)(device_t)"
+.Ft void
+.Fn config_interrupts "device_t dev" "void (*func)(device_t)"
+.Ft void
+.Fn config_mountroot "device_t dev" "void (*func)(device_t)"
+.Ft void
+.Fn config_pending_incr
+.Ft void
+.Fn config_pending_decr
+.Ft int
+.Fn config_finalize_register "device_t dev" "int (*func)(device_t)"
+.Sh DESCRIPTION
+Autoconfiguration is the process of matching hardware devices with an
+appropriate device driver.
+In its most basic form, autoconfiguration consists of the recursive process
+of finding and attaching all devices on a bus, including other busses.
+.Pp
+The autoconfiguration framework supports
+.Em direct configuration
+where the bus driver can determine the devices present.
+The autoconfiguration framework also supports
+.Em indirect configuration
+where the drivers must probe the bus looking for the presence of a device.
+Direct configuration is preferred since it can find hardware
+regardless of the presence of proper drivers.
+.Pp
+The autoconfiguration process occurs at system bootstrap and is driven
+by a table generated from a
+.Do
+machine description
+.Dc
+file by
+.Xr config 1 .
+For a description of the
+.Xr config 1
+.Do
+device definition
+.Dc
+language, see
+.Xr config 9 .
+.Pp
+Each device must have a name consisting of an alphanumeric string that
+ends with a unit number.
+The unit number identifies an instance of the driver.
+Device data structures are allocated dynamically during
+autoconfiguration, giving a unique address for each instance.
+.Pp
+Several of the autoconfiguration functions take a strongly-typed variadic
+list of arguments to pass information from driver autoconfiguration
+functions to the kernel's autoconfiguration system.
+This list is constructed using the
+.Fn CFARGS
+macro, like this example:
+.Bd -literal -offset indent
+config_search(self, NULL,
+    CFARGS(.search = mainbus_search,
+           .iattr = "mainbus"));
+.Ed
+.Pp
+Each tag is followed by a tag-specific value.
+.Bl -tag -offset indent -width ".Fa devhandle"
+.It Fa submatch
+A pointer to a
+.Sq submatch
+function used in
+.Em direct
+configuration.
+.\"
+.It Fa search
+A pointer to a
+.Sq search
+function used in
+.Em indirect
+configuration.
+.\"
+.It Fa iattr
+A pointer to a constant
+.Tn C
+string
+.Pq Vt "const char *"
+specifying an interface attribute.
+If a parent device carries only a single interface attribute, then this
+argument may be omitted.
+If an interface attribute is specified that the parent device does not
+carry, or no interface attribute is specified and the parent device carries
+more than one, behavior is undefined.
+On kernels built with the
+.Dv DIAGNOSTIC
+option, this may result in an assertion panic.
+.\"
+.It Fa locators
+A pointer to a constant array of integers
+.Pq Vt "const int *"
+containing interface attribute-specific locators.
+.\"
+.It Fa devhandle
+A
+.Vt devhandle_t
+(passed by value) corresponding to the device being attached.
+.El
+.Pp
+If no arguments are to be passed, the special value
+.Dv CFARGS_NONE
+may be used in place of the
+.Fn CFARGS
+macro.
+.Sh FUNCTIONS
+.Bl -tag -width ".Fn config"
+.\"
+.\"
+.It Fn config_search "parent" "aux" "cfargs"
+Cfargs consumed:
+.Fa search ,
+.Fa iattr ,
+.Fa locators .
+.\"
+.Pp
+Performs indirect configuration of physical devices.
+.Fn config_search
+iterates over all potential children, calling the given
+search function
+If no search function is specified,
+.fn config_search
+applies the potential child's match function instead.
+The argument
+.Fa parent
+is the pointer to the parent's device structure.
+If an interface attribute is specified, only potential children eligible to
+attach to that interface attribute will be consulted.
+If specified,
+the locators argument lists the locator values for the device and are passed
+to the search function.
+The given
+.Fa aux
+argument describes the device that has been found and is simply passed
+on through the search function to the child.
+.Fn config_search
+returns a pointer to the configuration data that indicates the best-matched
+child or
+.Dv NULL
+otherwise.
+.Pp
+The role of the search function is to call
+.Fn config_probe
+for each potential child and call
+.Fn config_attach
+for any positive matches.
+If no search function is specified,
+then the parent should record the return value from
+.Fn config_search
+and call
+.Fn config_attach
+itself.
+.Pp
+Note that this function is designed so that it can be used to apply an
+arbitrary function to all potential children.
+In this case callers may choose to ignore the return value.
+.\"
+.\"
+.It Fn config_found "parent" "aux" "print" "cfargs"
+Cfargs consumed:
+.Fa submatch ,
+.Fa iattr ,
+.Fa locators ,
+.Fa devhandle .
+.\"
+.Pp
+Performs direct configuration on a physical device.
+.Fn config_found
+is called by the parent and in turn calls the specified submatch function
+as determined by the configuration table.
+The submatch function compares user-specified locators from the
+machine description file against those specifying a found device,
+calling
+.Fn config_match
+if they match
+.Pq including wildcard matching .
+If a submatch function is not specified, then driver match functions are
+called directly.
+The argument
+.Fa parent
+is the pointer to the parent's device structure.
+If an interface attribute is specified, only potential children eligible to
+attach to that interface attribute will be consulted.
+If specified, the locators argument lists the locator values for the found
+device and may be used by the submatch function and will be recorded in the
+device structure of the child device.
+The given
+.Fa aux
+argument describes the device that has been found.
+.Fn config_found
+internally uses
+.Fn config_search .
+The
+.Vt softc
+structure for the matched device will be allocated, and the
+appropriate driver attach function will be called.
+If the device is matched, the system prints the name of the child and
+parent devices, and then calls the
+.Fa print
+function to produce additional information if desired.
+If no driver takes a match, the same
+.Fa print
+function is called to complain.
+The print function is called with the
+.Fa aux
+argument and, if the matches failed, the full name (including unit
+number) of the parent device, otherwise
+.Dv NULL .
+The
+.Fa print
+function must return an integer value.
+.Pp
+Two special strings,
+.Do
+not configured
+.Dc
+and
+.Do
+unsupported
+.Dc
+will be appended automatically to non-driver reports if the return
+value is
+.Dv UNCONF
+or
+.Dv UNSUPP
+respectively; otherwise the function should
+return the value
+.Dv QUIET .
+If a device handle is specified, that handle will be associated with
+the resulting child device structure if a driver matches.
+.Pp
+.Fn config_found
+returns a pointer to the attached device's
+.Vt device
+structure if the device is attached,
+.Dv NULL
+otherwise.
+Most callers can ignore this value, since the system will already have
+printed a diagnostic.
+.\"
+.\"
+.It Fn config_match "parent" "cf" "aux"
+.\"
+Match a device
+.Pq direct configuration .
+Invokes the driver's match function according to the configuration table.
+The
+.Fn config_match
+function returns a nonzero integer indicating the confidence of
+supporting this device and a value of 0 if the driver doesn't support
+the device.
+.\"
+.\"
+.It Fn config_probe "parent" "cf" "aux"
+.\"
+Probe for a device
+.Pq indirect configuration .
+Invokes the driver's match function according to the configuration table.
+The
+.Fn config_probe
+function returns a nonzero integer to indicate a successful probe
+and a value of 0 otherwise.
+Unlike
+.Fn config_match ,
+the return value of
+.Fn config_probe
+is not intended to reflect a confidence value.
+.\"
+.\"
+.It Fn config_attach "parent" "cf" "aux" "print" "cfargs"
+Cfargs consumed:
+.Fa locators ,
+.Fa devhandle .
+.\"
+.Pp
+Attach a found device.
+Allocates the memory for the
+.Vt softc
+structure and calls the drivers attach function according to the
+configuration table.
+If successful,
+.Fn config_attach
+returns a pointer to the
+.Vt device
+structure.
+If unsuccessful, it returns
+.Dv NULL .
+.\"
+.\"
+.It Fn config_attach_pseudo "cf"
+.\"
+Create an instance of a pseudo-device driver.
+.Xr config 5
+syntax allows the creation of pseudo-devices from which regular
+.Ft device_t
+instances can be created.
+Such objects are similar to the devices that attach at the root of the device
+tree.
+.Pp
+The caller is expected to allocate and fill the
+.Ft cfdata_t
+object and pass it to
+.Fn config_attach_pseudo .
+The content of that object is similar to what is returned by
+.Fn config_search
+for regular devices.
+.\"
+.\"
+.It Fn config_detach "dev" "flags"
+.\"
+Called by the parent to detach the child device.
+The second argument
+.Fa flags
+contains detachment flags.
+Valid values are
+.Dv DETACH_FORCE
+(force detachment, e.g., because of hardware removal)
+and
+.Dv DETACH_QUIET
+(do not print a notice).
+.Fn config_detach
+returns zero if successful and an error code otherwise.
+.Fn config_detach
+is always called from a thread context, allowing condition variables
+to be used while the device detaches itself.
+.\"
+.\"
+.It Fn config_detach_children "dev" "flags"
+.\"
+Iterate through all attached devices, calling
+.Fn config_detach
+for each child of
+.Fa dev ,
+passing
+.Fa flags .
+If detaching any child results in an error, the iteration will halt
+and any remaining devices will not be detached.
+.Fn config_detach_children
+returns zero if successful and an error code otherwise.
+.\"
+.\"
+.It Fn config_deactivate "dev"
+.\"
+Called by the parent to deactivate the child device
+.Fa dev .
+.Fn config_deactivate
+is called from interrupt context to immediately relinquish resources
+and notify dependent kernel subsystems that the device is about to be
+detached.
+At some later point
+.Fn config_detach
+will be called to finalise the removal of the device.
+.\"
+.\"
+.It Fn config_defer "dev" "func"
+.\"
+Called by the child to defer the remainder of its configuration until
+all its parent's devices have been attached.
+At this point, the function
+.Fa func
+is called with the argument
+.Fa dev .
+.\"
+.\"
+.It Fn config_interrupts "dev" "func"
+.\"
+Called by the child to defer the remainder of its configuration until
+interrupts are enabled.
+At this point, the function
+.Fa func
+is called with the argument
+.Fa dev .
+.\"
+.\"
+.It Fn config_mountroot "dev" "func"
+.\"
+Called by the child to defer the remainder of its configuration until
+the root file system is mounted.
+At this point, the function
+.Fa func
+is called with the argument
+.Fa dev .
+This is used for devices that need to load firmware image from
+a mounted file system.
+.\"
+.\"
+.It Fn config_pending_incr
+.\"
+Increment the
+.Va config_pending
+semaphore.
+It is used to account for deferred configurations before
+mounting the root file system.
+.\"
+.\"
+.It Fn config_pending_decr
+.\"
+Decrement the
+.Va config_pending
+semaphore.
+It is used to account for deferred configurations before
+mounting the root file system.
+.\"
+.\"
+.It Fn config_finalize_register "dev" "func"
+.\"
+.\"
+Register a function to be called after all real devices have been found.
+.Pp
+Registered functions are all executed until all of them return 0.
+The callbacks should return 0 to indicate they do not require to be called
+another time, but they should be aware that they still might be in case one of
+them returns 1.
+.El
+.Sh CODE REFERENCES
+The autoconfiguration framework itself is implemented within the file
+.Pa sys/kern/subr_autoconf.c .
+Data structures and function prototypes for the framework are located in
+.Pa sys/sys/device.h .
+.Sh SEE ALSO
+.Xr config 1 ,
+.Xr config 5 ,
+.Xr condvar 9 ,
+.Xr config 9 ,
+.Xr driver 9
+.Sh HISTORY
+Autoconfiguration first appeared in
+.Bx 4.1 .
+The autoconfiguration framework was completely revised in
+.Bx 4.4 .
+The detach and deactivate interfaces appeared in
+.Nx 1.5 .