diff options
Diffstat (limited to 'static/netbsd/man9/autoconf.9 3.html')
| -rw-r--r-- | static/netbsd/man9/autoconf.9 3.html | 385 |
1 files changed, 0 insertions, 385 deletions
diff --git a/static/netbsd/man9/autoconf.9 3.html b/static/netbsd/man9/autoconf.9 3.html deleted file mode 100644 index 35df3b00..00000000 --- a/static/netbsd/man9/autoconf.9 3.html +++ /dev/null @@ -1,385 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">AUTOCONF(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">AUTOCONF(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">autoconf</code>, - <code class="Nm">config_search</code>, <code class="Nm">config_found</code>, - <code class="Nm">config_match</code>, <code class="Nm">config_attach</code>, - <code class="Nm">config_attach_pseudo</code>, - <code class="Nm">config_detach</code>, - <code class="Nm">config_detach_children</code>, - <code class="Nm">config_deactivate</code>, - <code class="Nm">config_defer</code>, - <code class="Nm">config_interrupts</code>, - <code class="Nm">config_mountroot</code>, - <code class="Nm">config_pending_incr</code>, - <code class="Nm">config_pending_decr</code>, - <code class="Nm">config_finalize_register</code> — - <span class="Nd">autoconfiguration framework</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">sys/param.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/device.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/errno.h</a>></code></p> -<p class="Pp"><var class="Ft">cfdata_t</var> - <br/> - <code class="Fn">config_search</code>(<var class="Fa" style="white-space: nowrap;">device_t - parent</var>, <var class="Fa" style="white-space: nowrap;">void *aux</var>, - <var class="Fa" style="white-space: nowrap;">const struct cfargs - *</var>);</p> -<p class="Pp"><var class="Ft">device_t</var> - <br/> - <code class="Fn">config_found</code>(<var class="Fa" style="white-space: nowrap;">device_t - parent</var>, <var class="Fa" style="white-space: nowrap;">void *aux</var>, - <var class="Fa" style="white-space: nowrap;">cfprint_t print</var>, - <var class="Fa" style="white-space: nowrap;">const struct cfargs - *</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">config_match</code>(<var class="Fa" style="white-space: nowrap;">device_t - parent</var>, <var class="Fa" style="white-space: nowrap;">cfdata_t - cf</var>, <var class="Fa" style="white-space: nowrap;">void *aux</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">config_probe</code>(<var class="Fa" style="white-space: nowrap;">device_t - parent</var>, <var class="Fa" style="white-space: nowrap;">cfdata_t - cf</var>, <var class="Fa" style="white-space: nowrap;">void *aux</var>);</p> -<p class="Pp"><var class="Ft">device_t</var> - <br/> - <code class="Fn">config_attach</code>(<var class="Fa" style="white-space: nowrap;">device_t - parent</var>, <var class="Fa" style="white-space: nowrap;">cfdata_t - cf</var>, <var class="Fa" style="white-space: nowrap;">void *aux</var>, - <var class="Fa" style="white-space: nowrap;">cfprint_t print</var>, - <var class="Fa" style="white-space: nowrap;">const struct cfargs - *</var>);</p> -<p class="Pp"><var class="Ft">device_t</var> - <br/> - <code class="Fn">config_attach_pseudo</code>(<var class="Fa" style="white-space: nowrap;">cfdata_t - cf</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">config_detach</code>(<var class="Fa" style="white-space: nowrap;">device_t - dev</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">config_detach_children</code>(<var class="Fa" style="white-space: nowrap;">device_t - dev</var>, <var class="Fa" style="white-space: nowrap;">int - flags</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">config_deactivate</code>(<var class="Fa" style="white-space: nowrap;">device_t - dev</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">config_defer</code>(<var class="Fa" style="white-space: nowrap;">device_t - dev</var>, <var class="Fa" style="white-space: nowrap;">void - (*func)(device_t)</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">config_interrupts</code>(<var class="Fa" style="white-space: nowrap;">device_t - dev</var>, <var class="Fa" style="white-space: nowrap;">void - (*func)(device_t)</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">config_mountroot</code>(<var class="Fa" style="white-space: nowrap;">device_t - dev</var>, <var class="Fa" style="white-space: nowrap;">void - (*func)(device_t)</var>);</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">config_pending_incr</code>();</p> -<p class="Pp"><var class="Ft">void</var> - <br/> - <code class="Fn">config_pending_decr</code>();</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">config_finalize_register</code>(<var class="Fa" style="white-space: nowrap;">device_t - dev</var>, <var class="Fa" style="white-space: nowrap;">int - (*func)(device_t)</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">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.</p> -<p class="Pp">The autoconfiguration framework supports <i class="Em">direct - configuration</i> where the bus driver can determine the devices present. - The autoconfiguration framework also supports <i class="Em">indirect - configuration</i> 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.</p> -<p class="Pp">The autoconfiguration process occurs at system bootstrap and is - driven by a table generated from a “machine description” file - by <a class="Xr">config(1)</a>. For a description of the - <a class="Xr">config(1)</a> “device definition” language, see - <a class="Xr">config(9)</a>.</p> -<p class="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.</p> -<p class="Pp" id="CFARGS">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 - <a class="permalink" href="#CFARGS"><code class="Fn">CFARGS</code></a>() - macro, like this example:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>config_search(self, NULL, - CFARGS(.search = mainbus_search, - .iattr = "mainbus"));</pre> -</div> -<p class="Pp">Each tag is followed by a tag-specific value.</p> -<div class="Bd-indent"> -<dl class="Bl-tag"> - <dt><var class="Fa">submatch</var></dt> - <dd>A pointer to a ‘submatch’ function used in - <i class="Em">direct</i> configuration.</dd> - <dt><var class="Fa">search</var></dt> - <dd>A pointer to a ‘search’ function used in - <i class="Em">indirect</i> configuration.</dd> - <dt><var class="Fa">iattr</var></dt> - <dd>A pointer to a constant C string (<var class="Vt">const char *</var>) - 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 - <code class="Dv">DIAGNOSTIC</code> option, this may result in an assertion - panic.</dd> - <dt><var class="Fa">locators</var></dt> - <dd>A pointer to a constant array of integers (<var class="Vt">const int - *</var>) containing interface attribute-specific locators.</dd> - <dt><var class="Fa">devhandle</var></dt> - <dd>A <var class="Vt">devhandle_t</var> (passed by value) corresponding to the - device being attached.</dd> -</dl> -</div> -<p class="Pp" id="CFARGS~2">If no arguments are to be passed, the special value - <code class="Dv">CFARGS_NONE</code> may be used in place of the - <a class="permalink" href="#CFARGS~2"><code class="Fn">CFARGS</code></a>() - macro.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> -<dl class="Bl-tag"> - <dt><code class="Fn">config_search</code>(<var class="Fa">parent</var>, - <var class="Fa">aux</var>, <var class="Fa">cfargs</var>)</dt> - <dd>Cfargs consumed: <var class="Fa">search</var>, - <var class="Fa">iattr</var>, <var class="Fa">locators</var>. - <p class="Pp" id="config_search">Performs indirect configuration of physical - devices. - <a class="permalink" href="#config_search"><code class="Fn">config_search</code></a>() - iterates over all potential children, calling the given search function - If no search function is specified, applies the potential child's match - function instead. The argument <var class="Fa">parent</var> 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 <var class="Fa">aux</var> argument describes the device that - has been found and is simply passed on through the search function to - the child. <code class="Fn">config_search</code>() returns a pointer to - the configuration data that indicates the best-matched child or - <code class="Dv">NULL</code> otherwise.</p> - <p class="Pp" id="config_probe">The role of the search function is to call - <a class="permalink" href="#config_probe"><code class="Fn">config_probe</code></a>() - for each potential child and call - <code class="Fn">config_attach</code>() for any positive matches. If no - search function is specified, then the parent should record the return - value from <code class="Fn">config_search</code>() and call - <code class="Fn">config_attach</code>() itself.</p> - <p class="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.</p> - </dd> - <dt id="config_found"><a class="permalink" href="#config_found"><code class="Fn">config_found</code></a>(<var class="Fa">parent</var>, - <var class="Fa">aux</var>, <var class="Fa">print</var>, - <var class="Fa">cfargs</var>)</dt> - <dd>Cfargs consumed: <var class="Fa">submatch</var>, - <var class="Fa">iattr</var>, <var class="Fa">locators</var>, - <var class="Fa">devhandle</var>. - <p class="Pp" id="config_found~2">Performs direct configuration on a - physical device. - <a class="permalink" href="#config_found~2"><code class="Fn">config_found</code></a>() - 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 - <a class="permalink" href="#config_match"><code class="Fn" id="config_match">config_match</code></a>() - if they match (including wildcard matching). If a submatch function is - not specified, then driver match functions are called directly. The - argument <var class="Fa">parent</var> 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 - <var class="Fa">aux</var> argument describes the device that has been - found. <code class="Fn">config_found</code>() internally uses - <code class="Fn">config_search</code>(). The <var class="Vt">softc</var> - 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 <var class="Fa">print</var> function to produce additional - information if desired. If no driver takes a match, the same - <var class="Fa">print</var> function is called to complain. The print - function is called with the <var class="Fa">aux</var> argument and, if - the matches failed, the full name (including unit number) of the parent - device, otherwise <code class="Dv">NULL</code>. The - <var class="Fa">print</var> function must return an integer value.</p> - <p class="Pp">Two special strings, “not configured” and - “unsupported” will be appended automatically to non-driver - reports if the return value is <code class="Dv">UNCONF</code> or - <code class="Dv">UNSUPP</code> respectively; otherwise the function - should return the value <code class="Dv">QUIET</code>. If a device - handle is specified, that handle will be associated with the resulting - child device structure if a driver matches.</p> - <p class="Pp" id="config_found~3"><a class="permalink" href="#config_found~3"><code class="Fn">config_found</code></a>() - returns a pointer to the attached device's <var class="Vt">device</var> - structure if the device is attached, <code class="Dv">NULL</code> - otherwise. Most callers can ignore this value, since the system will - already have printed a diagnostic.</p> - </dd> - <dt id="config_match~2"><a class="permalink" href="#config_match~2"><code class="Fn">config_match</code></a>(<var class="Fa">parent</var>, - <var class="Fa">cf</var>, <var class="Fa">aux</var>)</dt> - <dd>Match a device (direct configuration). Invokes the driver's match function - according to the configuration table. The - <code class="Fn">config_match</code>() 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.</dd> - <dt><code class="Fn">config_probe</code>(<var class="Fa">parent</var>, - <var class="Fa">cf</var>, <var class="Fa">aux</var>)</dt> - <dd>Probe for a device (indirect configuration). Invokes the driver's match - function according to the configuration table. The - <code class="Fn">config_probe</code>() function returns a nonzero integer - to indicate a successful probe and a value of 0 otherwise. Unlike - <code class="Fn">config_match</code>(), the return value of - <code class="Fn">config_probe</code>() is not intended to reflect a - confidence value.</dd> - <dt><code class="Fn">config_attach</code>(<var class="Fa">parent</var>, - <var class="Fa">cf</var>, <var class="Fa">aux</var>, - <var class="Fa">print</var>, <var class="Fa">cfargs</var>)</dt> - <dd>Cfargs consumed: <var class="Fa">locators</var>, - <var class="Fa">devhandle</var>. - <p class="Pp" id="config_attach">Attach a found device. Allocates the memory - for the <var class="Vt">softc</var> structure and calls the drivers - attach function according to the configuration table. If successful, - <a class="permalink" href="#config_attach"><code class="Fn">config_attach</code></a>() - returns a pointer to the <var class="Vt">device</var> structure. If - unsuccessful, it returns <code class="Dv">NULL</code>.</p> - </dd> - <dt><code class="Fn">config_attach_pseudo</code>(<var class="Fa">cf</var>)</dt> - <dd>Create an instance of a pseudo-device driver. <a class="Xr">config(5)</a> - syntax allows the creation of pseudo-devices from which regular - <var class="Ft">device_t</var> instances can be created. Such objects are - similar to the devices that attach at the root of the device tree. - <p class="Pp" id="config_attach_pseudo">The caller is expected to allocate - and fill the <var class="Ft">cfdata_t</var> object and pass it to - <a class="permalink" href="#config_attach_pseudo"><code class="Fn">config_attach_pseudo</code></a>(). - The content of that object is similar to what is returned by - <code class="Fn">config_search</code>() for regular devices.</p> - </dd> - <dt id="config_detach"><a class="permalink" href="#config_detach"><code class="Fn">config_detach</code></a>(<var class="Fa">dev</var>, - <var class="Fa">flags</var>)</dt> - <dd>Called by the parent to detach the child device. The second argument - <var class="Fa">flags</var> contains detachment flags. Valid values are - <code class="Dv">DETACH_FORCE</code> (force detachment, e.g., because of - hardware removal) and <code class="Dv">DETACH_QUIET</code> (do not print a - notice). <code class="Fn">config_detach</code>() returns zero if - successful and an error code otherwise. - <code class="Fn">config_detach</code>() is always called from a thread - context, allowing condition variables to be used while the device detaches - itself.</dd> - <dt id="config_detach_children"><a class="permalink" href="#config_detach_children"><code class="Fn">config_detach_children</code></a>(<var class="Fa">dev</var>, - <var class="Fa">flags</var>)</dt> - <dd>Iterate through all attached devices, calling - <code class="Fn">config_detach</code>() for each child of - <var class="Fa">dev</var>, passing <var class="Fa">flags</var>. If - detaching any child results in an error, the iteration will halt and any - remaining devices will not be detached. - <code class="Fn">config_detach_children</code>() returns zero if - successful and an error code otherwise.</dd> - <dt id="config_deactivate"><a class="permalink" href="#config_deactivate"><code class="Fn">config_deactivate</code></a>(<var class="Fa">dev</var>)</dt> - <dd>Called by the parent to deactivate the child device - <var class="Fa">dev</var>. <code class="Fn">config_deactivate</code>() 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 <code class="Fn">config_detach</code>() will - be called to finalise the removal of the device.</dd> - <dt id="config_defer"><a class="permalink" href="#config_defer"><code class="Fn">config_defer</code></a>(<var class="Fa">dev</var>, - <var class="Fa">func</var>)</dt> - <dd>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 - <var class="Fa">func</var> is called with the argument - <var class="Fa">dev</var>.</dd> - <dt id="config_interrupts"><a class="permalink" href="#config_interrupts"><code class="Fn">config_interrupts</code></a>(<var class="Fa">dev</var>, - <var class="Fa">func</var>)</dt> - <dd>Called by the child to defer the remainder of its configuration until - interrupts are enabled. At this point, the function - <var class="Fa">func</var> is called with the argument - <var class="Fa">dev</var>.</dd> - <dt id="config_mountroot"><a class="permalink" href="#config_mountroot"><code class="Fn">config_mountroot</code></a>(<var class="Fa">dev</var>, - <var class="Fa">func</var>)</dt> - <dd>Called by the child to defer the remainder of its configuration until the - root file system is mounted. At this point, the function - <var class="Fa">func</var> is called with the argument - <var class="Fa">dev</var>. This is used for devices that need to load - firmware image from a mounted file system.</dd> - <dt id="config_pending_incr"><a class="permalink" href="#config_pending_incr"><code class="Fn">config_pending_incr</code></a>()</dt> - <dd>Increment the <var class="Va">config_pending</var> semaphore. It is used - to account for deferred configurations before mounting the root file - system.</dd> - <dt id="config_pending_decr"><a class="permalink" href="#config_pending_decr"><code class="Fn">config_pending_decr</code></a>()</dt> - <dd>Decrement the <var class="Va">config_pending</var> semaphore. It is used - to account for deferred configurations before mounting the root file - system.</dd> - <dt id="config_finalize_register"><a class="permalink" href="#config_finalize_register"><code class="Fn">config_finalize_register</code></a>(<var class="Fa">dev</var>, - <var class="Fa">func</var>)</dt> - <dd>Register a function to be called after all real devices have been found. - <p class="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.</p> - </dd> -</dl> -</section> -<section class="Sh"> -<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE - REFERENCES</a></h1> -<p class="Pp">The autoconfiguration framework itself is implemented within the - file <span class="Pa">sys/kern/subr_autoconf.c</span>. Data structures and - function prototypes for the framework are located in - <span class="Pa">sys/sys/device.h</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">config(1)</a>, <a class="Xr">config(5)</a>, - <a class="Xr">condvar(9)</a>, <a class="Xr">config(9)</a>, - <a class="Xr">driver(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">Autoconfiguration first appeared in - <span class="Ux">4.1BSD</span>. The autoconfiguration framework was - completely revised in <span class="Ux">4.4BSD</span>. The detach and - deactivate interfaces appeared in <span class="Ux">NetBSD 1.5</span>.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">August 7, 2021</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |