diff options
| author | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:55:15 -0400 |
|---|---|---|
| committer | Jacob McDonnell <jacob@jacobmcdonnell.com> | 2026-04-25 19:55:15 -0400 |
| commit | 253e67c8b3a72b3a4757fdbc5845297628db0a4a (patch) | |
| tree | adf53b66087aa30dfbf8bf391a1dadb044c3bf4d /static/netbsd/man9 | |
| parent | a9157ce950dfe2fc30795d43b9d79b9d1bffc48b (diff) | |
docs: Added All NetBSD Manuals
Diffstat (limited to 'static/netbsd/man9')
117 files changed, 24829 insertions, 0 deletions
diff --git a/static/netbsd/man9/KERNEL_LOCK.9 3.html b/static/netbsd/man9/KERNEL_LOCK.9 3.html new file mode 100644 index 00000000..bdc4092c --- /dev/null +++ b/static/netbsd/man9/KERNEL_LOCK.9 3.html @@ -0,0 +1,228 @@ +<table class="head"> + <tr> + <td class="head-ltitle">KERNEL_LOCK(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">KERNEL_LOCK(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">KERNEL_LOCK</code> — + <span class="Nd">compatibility with legacy uniprocessor code</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">KERNEL_LOCK</code>(<var class="Fa" style="white-space: nowrap;">int + nlocks</var>, <var class="Fa" style="white-space: nowrap;">struct lwp + *l</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">KERNEL_UNLOCK_ONE</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">KERNEL_UNLOCK_ALL</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">int + *nlocksp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">KERNEL_UNLOCK_LAST</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">KERNEL_LOCKED_P</code>();</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">KERNEL_LOCK</code> facility serves to + gradually transition software from the kernel's legacy uniprocessor + execution model, where the kernel runs on only a single CPU and never in + parallel on multiple CPUs, to a multiprocessor system.</p> +<p class="Pp" id="New"><a class="permalink" href="#New"><b class="Sy">New code + should not use</b></a> <code class="Nm">KERNEL_LOCK</code>. + <code class="Nm">KERNEL_LOCK</code> is meant only for gradual transition of + <span class="Ux">NetBSD</span> to natively MP-safe code, which uses + <a class="Xr">mutex(9)</a> or other <a class="Xr">locking(9)</a> facilities + to synchronize between threads and interrupt handlers. Use of + <code class="Nm">KERNEL_LOCK</code> hurts system performance and + responsiveness. This man page exists only to document the legacy API in + order to make it easier to transition away from.</p> +<p class="Pp">The kernel lock, sometimes also known as ‘giant + lock’ or ‘big lock’, is a recursive exclusive spin-lock + that can be held by a CPU at any interrupt priority level and is dropped + while sleeping. This means:</p> +<dl class="Bl-tag"> + <dt>recursive</dt> + <dd>If a CPU already holds the kernel lock, it can be acquired again and + again, as long as it is released an equal number of times.</dd> + <dt>exclusive</dt> + <dd>Only one CPU at a time can hold the kernel lock.</dd> + <dt>spin-lock</dt> + <dd>When one CPU holds the kernel lock and another CPU wants to hold it, the + second CPU ‘spins’, i.e., repeatedly executes instructions + to see if the kernel lock is available yet, until the first CPU releases + it. During this time, no other threads can run on the spinning CPU. + <p class="Pp">This means holding the kernel lock for long periods of time, + such as nontrivial computation, must be avoided. Under + <code class="Dv">LOCKDEBUG</code> kernels, holding the kernel lock for + too long can lead to ‘spinout’ crashes.</p> + </dd> + <dt>held by a CPU</dt> + <dd>The kernel lock is held by a CPU, not by a process, kthread, LWP, or + interrupt handler. It may be shared by a kthread LWP and several softint + LWPs at the same time, for example, if the softints interrupted the thread + on a CPU.</dd> + <dt>any interrupt priority level</dt> + <dd>The kernel lock <i class="Em">does not</i> block interrupts; subsystems + running with the kernel lock use <a class="Xr">spl(9)</a> to synchronize + with interrupt handlers. + <p class="Pp">Interrupt handlers that are not marked MP-safe are always run + with the kernel lock. If the interrupt arrives on a CPU where the kernel + lock is already held, it is simply taken again recursively on interrupt + entry and released to its original recursion depth on interrupt + exit.</p> + </dd> + <dt>dropped while sleeping</dt> + <dd>Any time the kernel sleeps to let other threads run, for any reason + including <a class="Xr">tsleep(9)</a> or <a class="Xr">condvar(9)</a> or + even adaptive <a class="Xr">mutex(9)</a> locks, it releases the kernel + lock before going to sleep and then reacquires it afterward. + <p class="Pp">This means, for instance, that although data structures + accessed only under the kernel lock won't be changed before the sleep, + they may be changed by another thread during the sleep. For example, the + following program may crash on an assertion failure because the sleep in + <a class="Xr">mutex_enter(9)</a> can allow another CPU to run and change + the global variable <code class="Dv">x</code>:</p> + <div class="Bd Pp Li"> + <pre> KERNEL_LOCK(1, NULL); + x = 42; + mutex_enter(...); + ... + mutex_exit(...); + KASSERT(x == 42); + KERNEL_UNLOCK_ONE(NULL);</pre> + </div> + <p class="Pp">This means simply introducing calls to + <a class="Xr">mutex_enter(9)</a> and <a class="Xr">mutex_exit(9)</a> can + break kernel-locked assumptions. Subsystems need to be consistently + converted from <code class="Nm">KERNEL_LOCK</code> and + <a class="Xr">spl(9)</a> to <a class="Xr">mutex(9)</a>, + <a class="Xr">condvar(9)</a>, etc.; mixing <a class="Xr">mutex(9)</a> + and <code class="Nm">KERNEL_LOCK</code> usually doesn't work.</p> + </dd> +</dl> +<p class="Pp" id="kernel-locked">Holding the kernel lock <i class="Em">does + not</i> prevent other code from running on other CPUs at the same time. It + only prevents other + <a class="permalink" href="#kernel-locked"><i class="Em">kernel-locked</i></a> + code from running on other CPUs at the same time.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="KERNEL_LOCK"><a class="permalink" href="#KERNEL_LOCK"><code class="Fn">KERNEL_LOCK</code></a>(<var class="Fa">nlocks</var>, + <var class="Fa">l</var>)</dt> + <dd>Acquire <var class="Fa">nlocks</var> recursive levels of kernel lock. + <p class="Pp">If the kernel lock is already held by another CPU, spins until + it can be acquired by this one. If the kernel lock is already held by + this CPU, records the kernel lock recursion depth and returns + immediately.</p> + <p class="Pp" id="KERNEL_UNLOCK_ALL">Most of the time + <var class="Fa">nlocks</var> is 1, but code that deliberately releases + all of the kernel locks held by the current CPU in order to sleep and + later reacquire the same number of kernel locks will pass a value of + <var class="Fa">nlocks</var> obtained from + <a class="permalink" href="#KERNEL_UNLOCK_ALL"><code class="Fn">KERNEL_UNLOCK_ALL</code></a>().</p> + </dd> + <dt id="KERNEL_UNLOCK_ONE"><a class="permalink" href="#KERNEL_UNLOCK_ONE"><code class="Fn">KERNEL_UNLOCK_ONE</code></a>(<var class="Fa">l</var>)</dt> + <dd>Release one level of the kernel lock. Equivalent to + <a class="permalink" href="#KERNEL_UNLOCK"><code class="Fn" id="KERNEL_UNLOCK">KERNEL_UNLOCK</code></a>(<code class="Li">1</code>, + <var class="Fa">l</var>, <code class="Dv">NULL</code>);.</dd> + <dt><code class="Fn">KERNEL_UNLOCK_ALL</code>(<var class="Fa">l</var>, + <var class="Fa">nlocksp</var>)</dt> + <dd>Store the kernel lock recursion depth at <var class="Fa">nlocksp</var> and + release all recursive levels of the kernel lock. + <p class="Pp">This is often used inside logic implementing sleep, around a + call to <a class="Xr">mi_switch(9)</a>, so that the same number of + recursive kernel locks can be reacquired afterward once the thread is + reawoken:</p> + <div class="Bd Pp Li"> + <pre> int nlocks; + + KERNEL_UNLOCK_ALL(l, &nlocks); + ... mi_switch(l) ... + KERNEL_LOCK(nlocks, l);</pre> + </div> + </dd> + <dt id="KERNEL_UNLOCK_LAST"><a class="permalink" href="#KERNEL_UNLOCK_LAST"><code class="Fn">KERNEL_UNLOCK_LAST</code></a>(<var class="Fa">l</var>)</dt> + <dd>Release the kernel lock, which must be held at exactly one level. + <p class="Pp">This is normally used at the end of a non-MP-safe thread, + which was known to have started with exactly one level of the kernel + lock, and is now about to exit.</p> + </dd> + <dt id="KERNEL_LOCKED_P"><a class="permalink" href="#KERNEL_LOCKED_P"><code class="Fn">KERNEL_LOCKED_P</code></a>()</dt> + <dd>True if the kernel lock is held. + <p class="Pp">To be used only in diagnostic assertions with + <a class="Xr">KASSERT(9)</a>.</p> + </dd> +</dl> +<p class="Pp">The legacy argument <var class="Fa">l</var> must be + <code class="Dv">NULL</code> or <code class="Dv">curlwp</code>, which mean + the same thing.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp">Some <span class="Ux">NetBSD</span> kernel abstractions execute + caller-specified functions with the kernel lock held by default, for + compatibility with legacy code, but can be explicitly instructed + <a class="permalink" href="#not"><i class="Em" id="not">not</i></a> to hold + the kernel lock by passing an MP-safe flag:</p> +<ul class="Bl-bullet"> + <li><a class="Xr">callout(9)</a>, <code class="Dv">CALLOUT_MPSAFE</code></li> + <li><a class="Xr">kfilter_register(9)</a> and <a class="Xr">knote(9)</a>, + <code class="Dv">FILTEROPS_MPSAFE</code></li> + <li><a class="Xr">kthread(9)</a>, <code class="Dv">KTHREAD_MPSAFE</code></li> + <li><a class="Xr">pci_intr(9)</a>, + <code class="Dv">PCI_INTR_MPSAFE</code></li> + <li><a class="Xr">scsipi(9)</a>, + <code class="Dv">SCSIPI_ADAPT_MPSAFE</code></li> + <li><a class="Xr">softint(9)</a>, <code class="Dv">SOFTINT_MPSAFE</code></li> + <li><a class="Xr">usbdi(9)</a> pipes, <code class="Dv">USBD_MPSAFE</code></li> + <li><a class="Xr">usbdi(9)</a> tasks, + <code class="Dv">USB_TASKQ_MPSAFE</code></li> + <li><a class="Xr">vnode(9)</a>, <code class="Dv">VV_MPSAFE</code></li> + <li><a class="Xr">workqueue(9)</a>, <code class="Dv">WQ_MPSAFE</code></li> +</ul> +<p class="Pp">The following <span class="Ux">NetBSD</span> subsystems are still + kernel-locked and need re-engineering to take advantage of parallelism on + multiprocessor systems:</p> +<ul class="Bl-bullet"> + <li><a class="Xr">ata(4)</a>, <a class="Xr">atapi(4)</a>, + <a class="Xr">wd(4)</a></li> + <li><a class="Xr">video(4)</a></li> + <li><a class="Xr">autoconf(9)</a></li> + <li>most of the network stack by default, unless the option + <code class="Dv">NET_MPSAFE</code> is enabled</li> + <li id="..."><a class="permalink" href="#..."><span class="No">...</span></a></li> +</ul> +<p class="Pp">All interrupt handlers at <code class="Dv">IPL_VM</code>, or lower + (<a class="Xr">spl(9)</a>) run with the kernel lock on most ports.</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">locking(9)</a>, <a class="Xr">mutex(9)</a>, + <a class="Xr">spl(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 13, 2022</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/RELEASE_NOTES-2.9 b/static/netbsd/man9/RELEASE_NOTES-2.9 new file mode 100644 index 00000000..e30a34d6 --- /dev/null +++ b/static/netbsd/man9/RELEASE_NOTES-2.9 @@ -0,0 +1,352 @@ +The stable Postfix release is called postfix-2.9.x where 2=major +release number, 9=minor release number, x=patchlevel. The stable +release never changes except for patches that address bugs or +emergencies. Patches change the patchlevel and the release date. + +New features are developed in snapshot releases. These are called +postfix-2.10-yyyymmdd where yyyymmdd is the release date (yyyy=year, +mm=month, dd=day). Patches are never issued for snapshot releases; +instead, a new snapshot is released. + +The mail_release_date configuration parameter (format: yyyymmdd) +specifies the release date of a stable release or snapshot release. + +If you upgrade from Postfix 2.7 or earlier, read RELEASE_NOTES-2.8 +before proceeding. + +Major changes - critical +------------------------ + +[Incompat 20110321] You need to "postfix reload" after upgrade from +snapshot 20110320 or earlier. The hash_queue_names algorithm was +changed to provide better performance with long queue IDs. + +[Incompat 20110313] Use "postfix reload" after "make upgrade" on a +running Postfix system. This is needed because the protocol between +postscreen(8) and dnsblog(8) has changed. + +Major changes - library API +--------------------------- + +[Incompat 20110130] The VSTREAM error flags are now split into +separate read and write error flags. As a result of this change, +all programs that use Postfix VSTREAMs MUST be recompiled. + +Major changes - compatibility +----------------------------- + +[Incompat 20111012] For consistency with the SMTP standard, the +(client-side) smtp_line_length_limit default value was increased +from 990 characters to 999 (i.e. 1000 characters including <CR><LF>). +Specify "smtp_line_length_limit = 990" to restore historical Postfix +behavior. + +[Incompat 20111012] To simplify integration with third-party +applications, the Postfix sendmail command now always transforms +all input lines ending in <CR><LF> into UNIX format (lines ending +in <LF>). Specify "sendmail_fix_line_endings = strict" to restore +historical Postfix behavior (i.e. convert all input lines ending +in <CR><LF> only if the first line ends in <CR><LF>). + +[Incompat 20111106] To work around broken remote SMTP servers, the +Postfix SMTP client by default no longer appends the "AUTH=<>" +option to the MAIL FROM command. Specify "smtp_send_dummy_mail_auth += yes" to restore the old behavior. + +Major changes - gradual degradation +----------------------------------- + +[Incompat 20120114] Logfile-based alerting systems may need to be +updated to look for "error" messages in addition to "fatal" messages. +Specify "daemon_table_open_error_is_fatal = yes" to get the historical +behavior (immediate termination with "fatal" message). + +[Feature 20120114] Instead of terminating immediately with a "fatal" +message when a database file can't be opened, a Postfix daemon +program now logs an "error" message, and continues execution with +reduced functionality. For the sake of sanity, the number of +"errors" over the life of a process is limited to 13. + +Features that don't depend on the unavailable table will continue +to work; attempts to use features that depend on the table will +fail, and will be logged with a "warning" message. + +[Feature 20120108] Instead of terminating with a fatal error, the +LDAP, *SQL and memcache clients now handle table lookup errors in +the "domain" feature, instead of terminating with a fatal error. + +[Feature 20120102] Degrade gradually when some or all network +protocols specified with inet_protocols are unavailable, instead +of terminating with a fatal error. This eliminates build errors on +non-standard systems where opening an IPv4 socket results in an +error, and on non-standard systems where opening an IPv6 socket +results in an error. In the worst case, the master daemon will log +a message that it disables all type "inet" services. This will still +allow local submission and local delivery. + +[Feature 20111222] Instead of terminating with a fatal error, the +Postfix SMTP server now handles errors with database lookups in +mynetworks, TLS client certificate tables, debug_peer_list, +smtpd_client_event_limit_exceptions, permit_mx_backup_networks and +local_header_rewrite_clients, and reports "server local data error" +or "temporary lookup error". + +[Feature 20111229] Instead of terminating with a fatal error, the +trivial-rewrite server now handles errors with database lookups in +virtual_alias_domains, relay_domains, virtual_mailbox_domains. This +means fewer occasions where trivial-rewrite clients (such as the +SMTP server) will appear to hang. + +Major changes - long queue IDs +------------------------------ + +Postfix 2.9 introduces support for non-repeating queue IDs (also +used as queue file names). These names are encoded in a mix of upper +case, lower case and decimal digit characters. Long queue IDs are +disabled by default to avoid breaking tools that parse logfiles and +that expect queue IDs with the smaller [A-F0-9] character set. + +[Incompat 20110320] If you enable support for long queue file names, +you need to be aware that these file names are not compatible with +Postfix <= 2.8. If you must migrate back to Postfix <= 2.8, you +must first convert all long queue file names into short names, +otherwise the old Postfix version will complain. + +The conversion procedure before migration to Postfix <= 2.8 is: + + # postfix stop + # postconf enable_long_queue_ids=no + # postsuper + +Run the postsuper command repeatedly until it no longer reports +queue file name changes. + +[Feature 20110320] Support for long, non-repeating, queue IDs (queue +file names). The benefit of non-repeating names is simpler logfile +analysis, and easier queue migration (if you don't merge different +queues, there is no need to run "postsuper" to change queue file +names that don't match their message file inode number). + +Specify "enable_long_queue_ids = yes" to enable the feature. This +does not change the names of existing queue files. See postconf(5) +or postconf.5.html#enable_long_queue_ids for a detailed description +of the differences with the old short queue IDs. + +This changes new Postfix queue IDs from the short form 0FCEE9247A9 +into the longer form 3Ps0FS1Zhtz1PFjb, and changes new Message-ID +header values from YYMMDDHHMMSS.queueid@myhostname into the shorter +form queueid@myhostname. + +Major changes - memcache +------------------------ + +[Feature 20111209] memcache lookup and update support. This provides +a way to share postscreen(8) or verify(8) caches between Postfix +instances. See MEMCACHE_README and memcache_table(5) for details +and limitations. + +[Feature 20111213] Support for a persistent backup database in the +memcache client. The memcache client updates the memcache whenever +it looks up or modifies information in the persistent database. + +Major changes - postconf +------------------------ + +The postconf command was restructured - it now warns about unused +parameter name=value settings in main.cf or master.cf (likely to +be mistakes), it now understands "dynamic" parameter names such as +parameters whose name depends on the name of a master.cf entry, and +it can display main.cf and master.cf in a more user-friendly format. + +[Feature 20120117] support for legacy database parameter names +(main.cf parameter names that are generated by prepending a suffix +to the database name). + +[Feature 20111118] The "postconf -M" (display master.cf) command +now supports filtering. For example, specify "postconf -M inet" +to display only services that listen on the network. + +[Feature 20111113] postconf support to warn about unused "name=value" +entries in main.cf, and about unused "-o name=value" entries in +master.cf. This should help to eliminate common errors with mis-typed +names. + +[Feature 20111108] postconf support for parameter names that are +generated automatically from master.cf entries (delivery agents, +spawn services), and for parameter names that are defined with +main.cf smtpd_restriction_classes. + +[Feature 20111106] "postconf -M" support to print master.cf entries, +and "postconf -f" support to fold long main.cf or master.cf lines +for human readability. + +Major changes - trickle defense +------------------------------- + +[Feature 20110212] Support for per-record deadlines. These change +the behavior of Postfix timeout parameters, from a time limit per +read or write system call, to a time limit to send or receive a +complete record (an SMTP command line, SMTP response line, SMTP +message content line, or TLS protocol message). This limits the +impact from hostile peers that trickle data one byte at a time. + +The new configuration parameters and their default settings are: +smtpd_per_record_deadline (normal: no, overload: yes), +smtp_per_record_deadline (no), and lmtp_per_record_deadline (no). + +Note: when per-record deadlines are enabled, a short time limit may +cause problems with TLS over very slow network connections. The +reason is that a TLS protocol message can be up to 16 kbytes long +(with TLSv1), and that an entire TLS protocol message must be sent +or received within the per-record deadline. + +Per-record deadlines were introduced with postscreen(8) in Postfix +2.8. This program does not receive mail, and therefore it has no +problems with TLS over slow connections. + +Major changes - postscreen +-------------------------- + +[Feature 20111211] The proxymap(8) server can now be used to share +postscreen(8) or verify(8) caches between Postfix instances. Support +for proxymap-over-TCP, to share a Postfix database between hosts, +is expected to be completed in the Postfix 2.10 development cycle. + +[Feature 20111209] memcache lookup and update support. This provides +a way to share postscreen(8) or verify(8) caches between Postfix +instances. + +[Feature 20110228] postscreen(8) support to force remote SMTP clients +to implement proper MX lookup policy. By listening on both primary +and backup MX addresses, postscreen(8) can deny the temporary +whitelist status to clients that connect only to backup MX hosts, +and prevent them from talking to a Postfix SMTP server process. + +Example: when 1.2.3.4 is a local backup IP address, specify +"postscreen_whitelist_interfaces = !1.2.3.4 static:all". + +Major changes - tls +------------------- + +[Incompat 20111205] Postfix now logs the result of successful TLS +negotiation with TLS logging levels of 0. See the smtp_tls_loglevel +and smtpd_tls_loglevel descriptions in the postconf(5) manpage for +other minor differences. + +[Feature 20111205] Support for TLS public key fingerprint matching +in the Postfix SMTP client (in smtp_tls_policy_maps) and server (in +check_ccert access maps). Public key fingerprints are inherently +more specific than fingerprints over the entire certificate. + +[Feature 20111205] Revision of Postfix TLS logging. The main +difference is that Postfix now logs the result of successful TLS +negotiation with TLS logging levels of 0. See the smtp_tls_loglevel +and smtpd_tls_loglevel descriptions in the postconf(5) manpage for +other minor differences. + +Major changes - sasl authentication +----------------------------------- + +[Incompat 20111218] To support external SASL authentication, e.g., +in an NGINX proxy daemon, the Postfix SMTP server now always checks +the smtpd_sender_login_maps table, even without having +"smtpd_sasl_auth_enable = yes" in main.cf. + +[Feature 20111218] Support for external SASL authentication via the +XCLIENT command. This is used to accept SASL authentication from +an SMTP proxy such as NGINX. This support works even without having +to specify "smtpd_sasl_auth_enable = yes" in main.cf. + +[Incompat 20111106] To work around broken remote SMTP servers, the +Postfix SMTP client by default no longer appends the "AUTH=<>" +option to the MAIL FROM command. Specify "smtp_send_dummy_mail_auth += yes" to restore the old behavior. + +Major changes - large file support +---------------------------------- + +[Feature 20110219] Postfix now uses long integers for message_size_limit, +mailbox_size_limit and virtual_mailbox_limit. On LP64 systems (64-bit +long and pointer, but 32-bit integer), these limits can now exceed +2GB. + +Major changes - ipv6 +-------------------- + +[Incompat 20110918] The following changes were made in default +settings, in preparation for general availability of IPv6: + +- The default inet_protocols value is now "all" instead of "ipv4", + meaning use both IPv4 and IPv6. + + To avoid an unexpected loss of performance for sites without + global IPv6 connectivity, the commands "make upgrade" and "postfix + upgrade-configuration" now append "inet_protocols = ipv4" to + main.cf when no explicit inet_protocols setting is already present. + This workaround will be removed in a future release. + +- The default smtp_address_preference value is now "any" instead + of "ipv6", meaning choose randomly between IPv6 and IPv4. With + this the Postfix SMTP client will have more success delivering + mail to sites that have problematic IPv6 configurations. + +Major changes - address verification +------------------------------------ + +[Feature 20111211] The proxymap(8) server can now be used to share +postscreen(8) or verify(8) caches between Postfix instances. Support +for proxymap-over-TCP, to share a Postfix database between hosts, +is expected to be completed in the Postfix 2.10 development cycle. + +[Feature 20111209] memcache lookup and update support. This provides +a way to share postscreen(8) or verify(8) caches between Postfix +instances. + +[Feature 20111203] Support for time-dependent sender addresses +of address verification probes. The default address, double-bounce, +may end up on spammer blacklists. Although Postfix discards mail +for this address, such mail still uses up network bandwidth and +server resources. Specify an address_verify_sender_ttl value of +several hours or more to frustrate address harvesting. + +Major changes - session transcript notification +----------------------------------------------- + +[Incompat 20120114] By default the Postfix SMTP server no longer +reports transcripts of sessions where a client command is rejected +because a lookup table is unavailable. Postfix now implements gradual +degradation, for example, the SMTP server keeps running instead of +terminating with a fatal error. This change in error handling would +result in a very large number of "transcript of session" email +notifications when an LDAP or *SQL server goes down). + +To receive such reports, add the new "data" class to the notify_classes +parameter value. The reports will be sent to the error_notice_recipient +address as before. This class is also used by the Postfix SMTP +client to report about sessions that fail because a table is +unavailable. + +Major changes - logging +---------------------------------------- + +[Incompat 20120114] Logfile-based alerting systems may need to be +updated to look for "error" messages in addition to "fatal" messages. +Specify "daemon_table_open_error_is_fatal = yes" to get the historical +behavior (immediate termination with "fatal" message). + +[Incompat 20111214] Logfile-based analysis tools may need to be +updated. The submission and smtps examples in the sample master.cf +file were updated to make their logging easier to distinguish. + +See the source file pflogsumm_quickfix.txt for a "quick fix". + +[Incompat 20111205] Postfix now logs the result of successful TLS +negotiation with TLS logging levels of 0. See the smtp_tls_loglevel +and smtpd_tls_loglevel descriptions in the postconf(5) manpage for +other minor differences. + +[Incompat 20110219] The Postfix SMTP and QMQP servers now log +"hostname X does not resolve to address Y", when a "reverse hostname" +lookup result does not resolve to the client IP address. Until now +these servers logged "Y: hostname X verification failed" or "Y: +address not listed for hostname X" which people found confusing. diff --git a/static/netbsd/man9/RELEASE_NOTES-3.9 b/static/netbsd/man9/RELEASE_NOTES-3.9 new file mode 100644 index 00000000..6d32de25 --- /dev/null +++ b/static/netbsd/man9/RELEASE_NOTES-3.9 @@ -0,0 +1,309 @@ +This is the Postfix 3.9 stable release. + +The stable Postfix release is called postfix-3.9.x where 3=major +release number, 9=minor release number, x=patchlevel. The stable +release never changes except for patches that address bugs or +emergencies. Patches change the patchlevel and the release date. + +New features are developed in snapshot releases. These are called +postfix-3.10-yyyymmdd where yyyymmdd is the release date (yyyy=year, +mm=month, dd=day). Patches are never issued for snapshot releases; +instead, a new snapshot is released. + +The mail_release_date configuration parameter (format: yyyymmdd) +specifies the release date of a stable release or snapshot release. + +If you upgrade from Postfix 3.7 or earlier, please read RELEASE_NOTES-3.8 +before proceeding. + +Dual license +------------ + +As of Postfix 3.2.5 this software is distributed with a dual license: +in addition to the historical IBM Public License (IPL) 1.0, it is +now also distributed with the more recent Eclipse Public License +(EPL) 2.0. Recipients can choose to take the software under the +license of their choice. Those who are more comfortable with the +IPL can continue with that license. + +Topics in this document +----------------------- +- changes that are less visible +- database support +- envid support +- feature deprecation +- mime conversion +- protocol compliance +- security +- tls support + +Changes that are less visible +----------------------------- + +The documentation has been updated to address many questions +that were asked on the postfix-users mailing list. + +More unit tests to make Postfix future-proof. Wietse is now looking +into migrating unit tests to Google test, because other people are +familiar with that framework, than with a Postfix-specific one. + +Major changes - database support +-------------------------------- + +[Feature 20240208] MongoDB client support, contributed by Hamid +Maadani, based on earlier code by Stephan Ferraro. For build and +usage instructions see MONGODB_README and mongodb_table(5). + +[Feature 20240129] In the mysql: and pgsql: clients, the hard-coded +idle and retry timer settings are now configurable. Details are in +the updated mysql_table(5) and pgsql_table(5) manpages. + +[Incompat 20230903] The MySQL client no longer supports MySQL +versions < 4.0. MySQL version 4.0 was released in 2003. + +[Incompat 20230419] The MySQL client default characterset is now +configurable with the "charset" configuration file attribute. The +default is "utf8mb4", consistent with the MySQL 8.0 built-in default, +but different from earlier MySQL versions where the built-in default +was "latin1". + +Major changes - envid support +----------------------------- + +[Feature 20230901] The local(8) delivery agent exports an ENVID +environment variable with the RFC 3461 envelope ID if available. + +The pipe(8) delivery agent supports an ${envid} command-line attribute +that expands to the RFC 3461 envelope ID if available. + +Major changes - feature deprecation +----------------------------------- + +[Incompat 20240218] The new document DEPRECATION_README covers +features that have been removed and that will be removed in the +future, with suggestions how to migrate. + +The Postfix SMTP server logs a warning when "permit_mx_backup" is +used (support for restriction "permit_mx_backup" will be removed +from Postfix; instead, use "relay_domains"). File: smtpd/smtpd_check.c. + +The postconf command logs a warning when the following parameters +are specified in main.cf or master.cf: xxx_use_tls, xxx_enforce_tls +(use the corresponding xxx_security_level setting instead); +xxx_per_site (use the corresponding xxx_policy_maps setting instead); +disable_dns_lookups (use smtp_dns_support_level instead); +smtpd_tls_dh1024_param_file, smtpd_tls_eecdh_grade (do not specify, +leave at default). These warning are silenced with the "postconf +-q". + +[Incompat 20240218] The Postfix SMTP server now logs that +permit_naked_ip_address, reject_maps_rbl, and check_relay_domains +have been removed and suggests a replacement. These features have +been logging deprecation warnings since 2005 or earlier, and were +removed from Postfix documentation in 2004. + +Major changes - mime conversion +------------------------------- + +[Feature 20230901] New parameter force_mime_input_conversion (default: +no) to convert body content that claims to be 8-bit into quoted-printable, +before header_checks, body_checks, Milters, and before after-queue +content filters. This feature does not affect messages that are +sent into smtpd_proxy_filter. + +The typical use case is an MTA that applies this conversion before +signing outbound messages, so that the signatures will remain valid +when a message is later handled by an MTA that does not announce +8BITMIME support, or when a message line exceeds the SMTP length +limit. + +Major changes - protocol compliance +----------------------------------- + +[Incompat 20240206] In message headers, Postfix now formats numerical +days as two-digit days, i.e. days 1-9 have a leading zero instead +of a leading space. This change was made because the RFC 5322 date +and time specification recommends (i.e. SHOULD) that a single space +be used in each place that FWS appears. This change avoids a breaking +change in the date string length. + +Major changes - security +------------------------ + +[Incompat 20240226] The Postfix DNS client now limits the total +size of DNS lookup results to 100 records; it drops the excess +records, and logs a warning. This limit is 20x larger than the +number of server addresses that the Postfix SMTP client is willing +to consider when delivering mail, and is far below the number of +records that could cause a tail recursion crash in dns_rr_append() +as reported by Toshifumi Sakaguchi. + +This change introduces a similar limit on the number of DNS requests +that a check_*_*_access restriction can make. + +[Incompat 20240110] With "cleanup_replace_stray_cr_lf = yes" (the +default), the cleanup daemon replaces each stray <CR> or <LF> +character in message content with a space character. The replacement +happens before any other content management (header/body_checks, +Milters, etc). + +This prevents outbound SMTP smuggling, where an attacker uses Postfix +to send email containing a non-standard End-of-DATA sequence, to +exploit inbound SMTP smuggling at a vulnerable remote SMTP server. + +This also improves the remote evaluation of Postfix-added DKIM and +other signatures, as the evaluation result will not depend on how +a remote email server handles stray <CR> or <LF> characters. + +This feature applies to all email that Postfix locally or remotely +sends out. It is not allowlisted based on client identity. + +[Feature 20240118] This updates Postfix fixes for inbound SMTP smuggling +attacks. For background, see https://www.postfix.org/smtp-smuggling.html + +This will be back ported to Postfix 3.8.5, 3.7.10, 3.6.14, and 3.5.24. + +- Better compatibility: the recommended setting "smtpd_forbid_bare_newline + = normalize" requires the standard End-of-DATA sequence + <CR><LF>.<CR><LF>, but allows bare newlines from SMTP clients, + maintaining more compatibility with existing infrastructure. + +- Improved logging for rejected input (it now includes queue ID, + helo, mail, and rcpt, if available). + +- The setting "smtpd_forbid_bare_newline = reject" requires + that input lines end in <CR><LF>, requires the standard End-of-DATA + sequence <CR><LF>.<CR><LF>, and rejects a command or message that + contains a bare newline. To disconnect the client, specify + "smtpd_forbid_bare_newline_reject_code = 521". + +- The Postfix SMTP server no longer strips extra <CR> as in + <CR><LF>.<CR><CR><LF>, to silence false alarms from test tools + that send attack sequences that real mail servers cannot send. + Details at https://www.postfix.org/false-smuggling-claims.html + +- The old setting "yes" has become an alias for "normalize". + +- The old setting "no" has not changed, and allows SMTP smuggling. + +The recommended settings are now: + + # Require the standard End-of-DATA sequence <CR><LF>.<CR><LF>. + # Otherwise, allow bare <LF> and process it as if the client sent + # <CR><LF>. + # + # This maintains compatibility with many legitimate SMTP client + # applications that send a mix of standard and non-standard line + # endings, but will fail to receive email from client implementations + # that do not terminate DATA content with the standard End-of-DATA + # sequence <CR><LF>.<CR><LF>. + # + # Such clients can be allowlisted with smtpd_forbid_bare_newline_exclusions. + # The example below allowlists SMTP clients in trusted networks. + # + smtpd_forbid_bare_newline = normalize + smtpd_forbid_bare_newline_exclusions = $mynetworks + +Alternative settings: + + # Reject input lines that contain <LF> and log a "bare <LF> received" + # error. Require that input lines end in <CR><LF>, and require the + # standard End-of-DATA sequence <CR><LF>.<CR><LF>. + # + # This will reject email from SMTP clients that send any non-standard + # line endings such as web applications, netcat, or load balancer + # health checks. + # + # This will also reject email from services that use BDAT to send + # MIME text containing a bare newline (RFC 3030 Section 3 requires + # canonical MIME format for text message types, defined in RFC 2045 + # Sections 2.7 and 2.8). + # + # Such clients can be allowlisted with smtpd_forbid_bare_newline_exclusions. + # The example below allowlists SMTP clients in trusted networks. + # + smtpd_forbid_bare_newline = reject + smtpd_forbid_bare_newline_exclusions = $mynetworks + # + # Alternatively, in the case of BDAT violations, BDAT can be selectively + # disabled with smtpd_discard_ehlo_keyword_address_maps, or globally + # disabled with smtpd_discard_ehlo_keywords. + # + # smtpd_discard_ehlo_keyword_address_maps = cidr:/path/to/file + # /path/to/file: + # 10.0.0.0/24 chunking, silent-discard + # smtpd_discard_ehlo_keywords = chunking, silent-discard + +[Incompat 20230603] the Postfix SMTP server by default disconnects +remote SMTP clients that violate RFC 2920 (or 5321) command pipelining +constraints. The server replies with "554 5.5.0 Error: SMTP protocol +synchronization" and logs the unexpected remote SMTP client input. +Specify "smtpd_reject_unauth_pipelining = no" to disable. + +Major changes - tls support +--------------------------- + +[Feature 20230807] Optional Postfix TLS support to request an RFC7250 +raw public key instead of an X.509 public-key certificate. The +configuration settings for raw key public support will be ignored +when there is no raw public key support in the local TLS implementation +(i.e. Postfix with OpenSSL versions before 3.2). + +- With "smtpd_tls_enable_rpk = yes", the Postfix SMTP server will + request that a remote SMTP client sends an RFC7250 raw public key + instead of an X.509 certificate when asking for or requiring TLS + client authentication. The Postfix SMTP server will still accept + a client public-key certificate instead of a public key. + +- With "smtp_tls_enable_rpk = yes" (or "enable_rpk = yes" in an + smtp policy table) at the security levels "may", "encrypt" or + "fingerprint", the Postfix SMTP client will request that a remote + SMTP server sends an RFC7250 raw public key instead of an X.509 + certificate. The Postfix SMTP client will still accept a server + public key certificate instead of a public key. + +- At the "secure" and "verify" security level, the Postfix SMTP + client will ignore smtp_tls_enable_rpk or enable_rpk settings, + because these levels require a server certificate. + +- At the "dane" and "dane-only" security levels, the Postfix SMTP + client will ignore smtp_tls_enable_rpk or enable_rpk settings, + and will request that a remote SMTP server sends an RFC7250 raw + public key instead of an X.509 certificate when all valid TLSA + records specify only server public keys (no certificates). The + Postfix SMTP client will still accept a server public key + certificate. + +- The Postfix SMTP client and server always send a raw public key + instead of a certificate, if solicited by the remote SMTP peer + and the local TLS implementation supports raw public keys. + +- If a remote SMTP client sends a server name indication with an + SNI TLS extension, and tls_server_sni_maps is configured, the + Postfix SMTP server will extract a raw public key from the indicated + certificate. + +Caution: enabling Postfix raw key support will break authentication +based on certificate fingerprints in check_ccert_access or +smtp_tls_policy_maps, when a remote peer's TLS implementation starts +to send a raw public key instead of a certificate. The solution is +to always use public key fingerprint patterns; these will match not +only a "raw" public key, but also the public key in a certificate. + +To detect such problems before they happen, the Postfix SMTP server +will log a warning when it requests an RFC7250 raw public key instead +of an X.509 certificate, the remote peer sends a certificate instead +of a public key, and check_ccert_access has a matching fingerprint +for the certificate but not for the public key in that certificate. +There is no corresponding warning from the Postfix SMTP client. + +For instructions to generate public-key fingerprints, see the +postconf(5) man pages for smtp_tls_enable_rpk and smtpd_tls_enable_rpk. + +[Feature 20230522] Preliminary support for OpenSSL configuration +files, primarily OpenSSL 1.1.1b and later. This introduces two new +parameters "tls_config_file" and "tls_config_name", which can be +used to limit collateral damage from OS distributions that crank +up security to 11, increasing the number of plaintext email deliveries. +Details are in the postconf(5) manpage under "tls_config_file" and +"tls_config_name". diff --git a/static/netbsd/man9/accept_filter.9 3.html b/static/netbsd/man9/accept_filter.9 3.html new file mode 100644 index 00000000..d9cd0808 --- /dev/null +++ b/static/netbsd/man9/accept_filter.9 3.html @@ -0,0 +1,140 @@ +<table class="head"> + <tr> + <td class="head-ltitle">ACCEPT_FILTER(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">ACCEPT_FILTER(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">accept_filter</code>, + <code class="Nm">accept_filt_add</code>, + <code class="Nm">accept_filt_del</code>, + <code class="Nm">accept_filt_generic_mod_event</code>, + <code class="Nm">accept_filt_get</code> — <span class="Nd">filter + incoming connections</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Fd">#define ACCEPT_FILTER_MOD</code></p> +<p class="Pp"><code class="In">#include + <<a class="In">sys/param.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/kernel.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/sysctl.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/signalvar.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/socketvar.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">netinet/accept_filter.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">accept_filt_add</code>(<var class="Fa" style="white-space: nowrap;">struct + accept_filter *filt</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">accept_filt_del</code>(<var class="Fa" style="white-space: nowrap;">char + *name</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">accept_filt_generic_mod_event</code>(<var class="Fa" style="white-space: nowrap;">module_t + mod</var>, <var class="Fa" style="white-space: nowrap;">int event</var>, + <var class="Fa" style="white-space: nowrap;">void *data</var>);</p> +<p class="Pp"><var class="Ft">struct accept_filter *</var> + <br/> + <code class="Fn">accept_filt_get</code>(<var class="Fa" style="white-space: nowrap;">char + *name</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Accept filters allow an application to request that the kernel + pre-process incoming connections. This manual page describes the kernel + interface for accept filters. User applications request accept filters via + the <a class="Xr">setsockopt(2)</a> system call, passing in an + <var class="Fa">optname</var> of + <code class="Dv">SO_ACCEPTFILTER</code>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IMPLEMENTATION_NOTES"><a class="permalink" href="#IMPLEMENTATION_NOTES">IMPLEMENTATION + NOTES</a></h1> +<p class="Pp">A module that wants to be an accept filter must provide a + <var class="Vt">struct accept_filter</var> to the system:</p> +<div class="Bd Pp Li"> +<pre>struct accept_filter { + char accf_name[16]; + void (*accf_callback)(struct socket *so, void *arg, int waitflag); + void * (*accf_create)(struct socket *so, char *arg); + void (*accf_destroy)(struct socket *so); + SLIST_ENTRY(accept_filter) accf_next; /* next on the list */ +};</pre> +</div> +<p class="Pp">The module should register it with the function + <code class="Fn">accept_filt_add</code>(), passing a pointer to a + <var class="Vt">struct accept_filter</var>, allocated with + <a class="Xr">malloc(9)</a>.</p> +<p class="Pp">The accept filters currently provided with + <span class="Ux">NetBSD</span> (<a class="Xr">accf_data(9)</a> and + <a class="Xr">accf_http(9)</a>) are implemented as pseudo-devices, but an + accept filter may use any supported means of initializing and registering + itself at system startup or later, including the module framework if + supported by the running kernel.</p> +<p class="Pp">The fields of <var class="Vt">struct accept_filter</var> are as + follows:</p> +<dl class="Bl-tag"> + <dt id="accf_name"><var class="Va">accf_name</var></dt> + <dd>Name of the filter; this is how it will be accessed from userland.</dd> + <dt id="accf_callback"><var class="Va">accf_callback</var></dt> + <dd>The callback that the kernel will do once the connection is established. + It is the same as a socket upcall and will be called when the connection + is established and whenever new data arrives on the socket, unless the + callback modifies the socket's flags.</dd> + <dt id="accf_create"><var class="Va">accf_create</var></dt> + <dd>Called whenever a <a class="Xr">setsockopt(2)</a> installs the filter onto + a listening socket.</dd> + <dt id="accf_destroy"><var class="Va">accf_destroy</var></dt> + <dd>Called whenever the user removes the accept filter on the socket.</dd> +</dl> +<p class="Pp">The <code class="Fn">accept_filt_del</code>() function passed the + same string used in <var class="Va">accept_filter.accf_name</var> during + registration with <code class="Fn">accept_filt_add</code>(), the kernel will + then disallow and further userland use of the filter.</p> +<p class="Pp">The <code class="Fn">accept_filt_get</code>() function is used + internally to locate which accept filter to use via the + <a class="Xr">setsockopt(2)</a> system call.</p> +<p class="Pp">The <code class="Fn">accept_filt_generic_mod_event</code>() + function can be used by accept filters which are loadable kernel modules to + add and delete themselves.</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">setsockopt(2)</a>, <a class="Xr">accf_data(9)</a>, + <a class="Xr">accf_http(9)</a>, <a class="Xr">malloc(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The accept filter mechanism was introduced in + <span class="Ux">FreeBSD 4.0</span>. It was ported to + <span class="Ux">NetBSD</span> by Coyote Point Systems, Inc. and appeared in + <span class="Ux">NetBSD 5.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page was written by <span class="An">Alfred + Perlstein</span>, <span class="An">Sheldon Hearn</span>, and + <span class="An">Jeroen Ruigrok van der Werven</span>.</p> +<p class="Pp">The accept filter concept was pioneered by <span class="An">David + Filo</span> at Yahoo! and refined to be a loadable module system by + <span class="An">Alfred Perlstein</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 12, 2008</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/accf_data.9 3.html b/static/netbsd/man9/accf_data.9 3.html new file mode 100644 index 00000000..e8bdda78 --- /dev/null +++ b/static/netbsd/man9/accf_data.9 3.html @@ -0,0 +1,68 @@ +<table class="head"> + <tr> + <td class="head-ltitle">ACCF_DATA(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">ACCF_DATA(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">accf_data</code> — <span class="Nd">buffer + incoming connections until data arrives</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">options INET</code> + <br/> + <code class="Cd">pseudo-device accf_data</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This is a filter to be placed on a socket that will be using + <a class="permalink" href="#accept"><code class="Fn" id="accept">accept</code></a>() + to receive incoming connections.</p> +<p class="Pp" id="accept~2">It prevents the application from receiving the + connected descriptor via + <a class="permalink" href="#accept~2"><code class="Fn">accept</code></a>() + until data arrives on the connection.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">If the <code class="Nm">accf_data</code> accept filter is present + in the kernel configuration, this will enable the data accept filter on the + socket <var class="Fa">sok</var>.</p> +<div class="Bd Pp Bd-indent Li"> +<pre> struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "dataready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa));</pre> +</div> +</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">setsockopt(2)</a>, + <a class="Xr">accept_filter(9)</a>, <a class="Xr">accf_http(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The accept filter mechanism and the + <code class="Nm">accf_data</code> filter were introduced in + <span class="Ux">FreeBSD 4.0</span>. They were ported to + <span class="Ux">NetBSD</span> by Coyote Point Systems and appeared in + <span class="Ux">NetBSD 5.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page and the filter were written by + <span class="An">Alfred Perlstein</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 10, 2008</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/acct_process.9 3.html b/static/netbsd/man9/acct_process.9 3.html new file mode 100644 index 00000000..1b058cfc --- /dev/null +++ b/static/netbsd/man9/acct_process.9 3.html @@ -0,0 +1,50 @@ +<table class="head"> + <tr> + <td class="head-ltitle">ACCT_PROCESS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">ACCT_PROCESS(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">acct_process</code> — + <span class="Nd">populate and write the process accounting record</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/acct.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">acct_process</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">acct_process</code> function is called when + the process exits. If accounting is turned off, it returns immediately. If + accounting is turned on via <a class="Xr">acct(2)</a>, then the + <code class="Nm">acct_process</code> populates the accounting structure + described in <a class="Xr">acct(5)</a>, then writes the accounting record to + the file specified by <a class="Xr">acct(2)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp"><code class="Nm">acct_process</code> returns 0 on success and the + same error codes as <a class="Xr">vn_rdwr(9)</a> on failure.</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">acct(2)</a>, <a class="Xr">acct(5)</a>, + <a class="Xr">vn_rdwr(9)</a>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 5, 2024</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/autoconf.9 3.html b/static/netbsd/man9/autoconf.9 3.html new file mode 100644 index 00000000..35df3b00 --- /dev/null +++ b/static/netbsd/man9/autoconf.9 3.html @@ -0,0 +1,385 @@ +<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> diff --git a/static/netbsd/man9/bcdtobin.9 3.html b/static/netbsd/man9/bcdtobin.9 3.html new file mode 100644 index 00000000..cdb38943 --- /dev/null +++ b/static/netbsd/man9/bcdtobin.9 3.html @@ -0,0 +1,51 @@ +<table class="head"> + <tr> + <td class="head-ltitle">BCDTOBIN(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">BCDTOBIN(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">bcdtobin</code>, <code class="Nm">bintobcd</code> + — <span class="Nd">convert a single byte between (unsigned) packed + bcd and binary</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">unsigned int</var> + <br/> + <code class="Fn">bcdtobin</code>(<var class="Fa" style="white-space: nowrap;">unsigned + int bcd</var>);</p> +<p class="Pp"><var class="Ft">unsigned int</var> + <br/> + <code class="Fn">bintobcd</code>(<var class="Fa" style="white-space: nowrap;">unsigned + int bin</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#bcdtobin"><code class="Fn" id="bcdtobin">bcdtobin</code></a>() + and + <a class="permalink" href="#bintobcd"><code class="Fn" id="bintobcd">bintobcd</code></a>() + functions convert a single byte between (unsigned) packed bcd and binary + encodings.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The <code class="Fn">bcdtobin</code>() function returns the binary + value of its BCD-encoded argument, <var class="Fa">bcd</var>. The + <code class="Fn">bintobcd</code>() function returns the BCD encoding of its + binary argument, <var class="Fa">bin</var>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 11, 2006</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/bcopy.9 3.html b/static/netbsd/man9/bcopy.9 3.html new file mode 100644 index 00000000..2888fc62 --- /dev/null +++ b/static/netbsd/man9/bcopy.9 3.html @@ -0,0 +1,58 @@ +<table class="head"> + <tr> + <td class="head-ltitle">BCOPY(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">BCOPY(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">bcopy</code> — <span class="Nd">copy byte + string</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bcopy</code>(<var class="Fa" style="white-space: nowrap;">const + void *src</var>, <var class="Fa" style="white-space: nowrap;">void + *dst</var>, <var class="Fa" style="white-space: nowrap;">size_t + len</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<div class="Bf Sy">The + <a class="permalink" href="#bcopy"><code class="Fn" id="bcopy">bcopy</code></a>() + interface is obsolete. Do not add new code using it. It will soon be purged. + Use <a class="Xr">memcpy(9)</a> instead. (The <code class="Fn">bcopy</code>() + function is now a macro for <a class="Xr">memcpy(9)</a>.)</div> +<p class="Pp" id="bcopy~2">The + <a class="permalink" href="#bcopy~2"><code class="Fn">bcopy</code></a>() + function copies <var class="Fa">len</var> bytes from string + <var class="Fa">src</var> to string <var class="Fa">dst</var>.</p> +<p class="Pp" id="ovbcopy"></p> +<div class="Bf Sy">Unlike <a class="Xr">bcopy(3)</a> the two strings must not + overlap!</div> +In the traditional <span class="Ux">BSD</span> kernel, overlapping copies were + handled by the now-purged + <a class="permalink" href="#ovbcopy"><code class="Fn">ovbcopy</code></a>() + function. If you need to copy overlapping data, see + <a class="Xr">memmove(9)</a>. +<p class="Pp">If <var class="Fa">len</var> is zero, no bytes are copied.</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">bcopy(3)</a>, <a class="Xr">memcpy(9)</a>, + <a class="Xr">memmove(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 7, 2001</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/bios32_service.9 b/static/netbsd/man9/bios32_service.9 new file mode 100644 index 00000000..1c7a2772 --- /dev/null +++ b/static/netbsd/man9/bios32_service.9 @@ -0,0 +1,51 @@ +.\" $NetBSD: bios32_service.9,v 1.8 2017/02/17 22:31:08 christos Exp $ +.\" +.\" Copyright (c) 2001 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 February 17, 2017 +.Dt BIOS32_SERVICE 9 i386 +.Os +.Sh NAME +.Nm bios32_service +.Nd locate BIOS32 service +.Sh SYNOPSIS +.In i386/bios32.h +.Ft int +.Fn bios32_service "uint32_t service" "bios32_entry_t e" \ +"bios32_entry_info_t ei" +.Sh DESCRIPTION +The +.Fn bios32_service +function calls the BIOS32 to locate the specified BIOS32 service +.Fa service +and fills in the entry point information +.Fa e +and +.Fa ei . +.Sh SEE ALSO +.Xr i386/bioscall 9 diff --git a/static/netbsd/man9/bioscall.9 b/static/netbsd/man9/bioscall.9 new file mode 100644 index 00000000..28e1dfc4 --- /dev/null +++ b/static/netbsd/man9/bioscall.9 @@ -0,0 +1,131 @@ +.\" $NetBSD: bioscall.9,v 1.10 2017/07/03 21:31:01 wiz Exp $ +.\" +.\" Copyright (c) 1998 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by John Kohl. +.\" +.\" 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 May 5, 2010 +.Dt BIOSCALL 9 i386 +.Os +.Sh NAME +.Nm bioscall +.Nd call system BIOS function from real mode +.Sh SYNOPSIS +.In i386/bioscall.h +.Ft void +.Fn bioscall "int function" "struct bioscallregs *regs" +.Sh DESCRIPTION +The +.Fn bioscall +function switches the processor into real mode, calls the +.Tn BIOS +interrupt numbered +.Fa function , +and returns to protected mode. +.Pp +This function is intended to be called during the initial system +bootstrap when necessary to probe devices or pseudo-devices. +.Pp +The register values specified by +.Fa *regs +(with one exception) are installed before the +.Tn BIOS +interrupt is called. +The processor flags are handled specially. +Only the following flags are passed to the +.Tn BIOS +from the registers in +.Fa regs +(the remainder come from the processor's flags register at the time +of the call): +.Ar PSL_C , +.Ar PSL_PF , +.Ar PSL_AF , +.Ar PSL_Z , +.Ar PSL_N , +.Ar PSL_D , +.Ar PSL_V . +.Pp +The +.Va bioscallregs +structure is defined to contain structures for each register, to allow +access to 32-, 16- or 8-bit wide sections of the registers. +Definitions are provided which simplify access to the union members. +.Sh RETURN VALUES +The +.Fn bioscall +function fills in +.Fa *regs +with the processor registers as returned from the +.Tn BIOS +call. +.Sh EXAMPLES +The Advanced Power Management driver calls +.Fn bioscall +by setting up a register structure with the +.Tn APM +installation check and device types in registers +.Fa ax +and +.Fa bx , +then calls the +.Tn BIOS +to fetch the details for calling the +.Tn APM +support through a protected-mode interface. +The +.Tn BIOS +returns these details in the registers: +.Pp +.Bd -literal -offset indent +#include <i386/bioscall.h> +#include <i386/apmvar.h> +struct bioscallregs regs; + +regs.AX = APM_BIOS_FN(APM_INSTALLATION_CHECK); +regs.BX = APM_DEV_APM_BIOS; +regs.CX = regs.DX = 0; +regs.ESI = regs.EDI = regs.EFLAGS = 0; +bioscall(APM_SYSTEM_BIOS, ®s); +.Ed +.Sh CODE REFERENCES +.Pa sys/arch/i386/i386/bioscall.s , +.Pa sys/arch/i386/bioscall/biostramp.S +.Sh REFERENCES +.Xr apm 4 +.Sh HISTORY +The +.Fn bioscall +function first appeared in +.Nx 1.3 . +.Sh BUGS +Not all +.Tn BIOS +functions are safe to call through the trampoline, as they +may depend on system state which has been disturbed or used for other +purposes once the +.Nx +kernel is running. diff --git a/static/netbsd/man9/bufq.9 3.html b/static/netbsd/man9/bufq.9 3.html new file mode 100644 index 00000000..c02fc983 --- /dev/null +++ b/static/netbsd/man9/bufq.9 3.html @@ -0,0 +1,211 @@ +<table class="head"> + <tr> + <td class="head-ltitle">BUFQ(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">BUFQ(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">bufq</code>, <code class="Nm">bufq_init</code>, + <code class="Nm">bufq_register</code>, + <code class="Nm">bufq_unregister</code>, <code class="Nm">bufq_state</code>, + <code class="Nm">bufq_alloc</code>, <code class="Nm">bufq_drain</code>, + <code class="Nm">bufq_free</code>, + <code class="Nm">bufq_getstrategyname</code>, + <code class="Nm">bufq_move</code>, <code class="Nm">bufq_put</code>, + <code class="Nm">bufq_get</code>, <code class="Nm">bufq_peek</code>, + <code class="Nm">bufq_cancel</code> — <span class="Nd">device buffer + queues</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/bufq.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bufq_init</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bufq_register</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_strat *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bufq_unregister</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_strat *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bufq_alloc</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state **bufq</var>, <var class="Fa" style="white-space: nowrap;">const + char *strategy</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bufq_drain</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *bufq</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bufq_free</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *bufq</var>);</p> +<p class="Pp"><var class="Ft">const char *</var> + <br/> + <code class="Fn">bufq_getstrategyname</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *bufq</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bufq_move</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *dst</var>, <var class="Fa" style="white-space: nowrap;">struct + bufq_state *src</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bufq_put</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *bufq</var>, <var class="Fa" style="white-space: nowrap;">struct + buf *bp</var>);</p> +<p class="Pp"><var class="Ft">struct buf *</var> + <br/> + <code class="Fn">bufq_get</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *bufq</var>);</p> +<p class="Pp"><var class="Ft">struct buf *</var> + <br/> + <code class="Fn">bufq_peek</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *bufq</var>);</p> +<p class="Pp"><var class="Ft">struct buf *</var> + <br/> + <code class="Fn">bufq_cancel</code>(<var class="Fa" style="white-space: nowrap;">struct + bufq_state *bufq</var>, <var class="Fa" style="white-space: nowrap;">struct + buf *bp</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">bufq</code> subsystem is a set of operations + for the management of device buffer queues. Various strategies for ordering + of entries in the buffer queues can be provided by loadable kernel modules + (see <a class="Xr">module(9)</a>). By default, the + <code class="Dv">BUFQ_FCFS</code> and <code class="Dv">BUFQ_DISKSORT</code> + strategies are included in the kernel; see <a class="Xr">options(4)</a> for + more details.</p> +<p class="Pp" id="bufq_strat">The primary data type for using the operations is + the <i class="Em">bufq_state</i> structure, which is opaque for users. Each + buffer queue strategy module is defined by the + <a class="permalink" href="#bufq_strat"><i class="Em">bufq_strat</i></a> + structure, which is also opaque for users.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="bufq_init"><a class="permalink" href="#bufq_init"><code class="Fn">bufq_init</code></a>(<var class="Fa">void</var>)</dt> + <dd>Initialize the <code class="Nm">bufq</code> subsystem. This routine must + be called before any other <code class="Nm">bufq</code> routines.</dd> + <dt id="bufq_register"><a class="permalink" href="#bufq_register"><code class="Fn">bufq_register</code></a>(<var class="Fa">bs</var>)</dt> + <dd>Registers the specified buffer queue strategy module so it can be used in + subsequent operations.</dd> + <dt id="bufq_unregister"><a class="permalink" href="#bufq_unregister"><code class="Fn">bufq_unregister</code></a>(<var class="Fa">bs</var>)</dt> + <dd>Unregisters the specified buffer queue strategy module. The routine will + fail if any buffer queues for the specified strategy are in use (see + <code class="Fn">bufq_alloc</code>() below).</dd> + <dt><code class="Fn">bufq_alloc</code>(<var class="Fa">bufq</var>, + <var class="Fa">strategy</var>, <var class="Fa">flags</var>)</dt> + <dd>Allocate and initialize a <i class="Em">bufq_state</i> descriptor. + <p class="Pp">The argument <var class="Fa">strategy</var> specifies a buffer + queue strategy to be used for this buffer queue. The following special + values can be used:</p> + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt id="BUFQ_STRAT_ANY"><a class="permalink" href="#BUFQ_STRAT_ANY"><code class="Dv">BUFQ_STRAT_ANY</code></a></dt> + <dd>Let + <a class="permalink" href="#bufq_alloc"><code class="Fn" id="bufq_alloc">bufq_alloc</code></a>() + select a strategy.</dd> + <dt id="BUFQ_DISK_DEFAULT_STRAT"><a class="permalink" href="#BUFQ_DISK_DEFAULT_STRAT"><code class="Dv">BUFQ_DISK_DEFAULT_STRAT</code></a></dt> + <dd>Let <code class="Fn">bufq_alloc</code>() select a strategy, assuming + it will be used for a normal disk device.</dd> + </dl> + </div> + <p class="Pp">Valid bits for the <var class="Fa">flags</var> are:</p> + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt id="BUFQ_SORT_RAWBLOCK"><a class="permalink" href="#BUFQ_SORT_RAWBLOCK"><code class="Dv">BUFQ_SORT_RAWBLOCK</code></a></dt> + <dd>sort by <i class="Em">b_rawblkno</i></dd> + <dt id="BUFQ_SORT_CYLINDER"><a class="permalink" href="#BUFQ_SORT_CYLINDER"><code class="Dv">BUFQ_SORT_CYLINDER</code></a></dt> + <dd>sort by + <a class="permalink" href="#b_cylinder"><i class="Em" id="b_cylinder">b_cylinder</i></a> + and then by <i class="Em">b_rawblkno</i></dd> + <dt id="BUFQ_EXACT"><a class="permalink" href="#BUFQ_EXACT"><code class="Dv">BUFQ_EXACT</code></a></dt> + <dd>Fail if a strategy specified by <var class="Fa">strategy</var> is not + available. In that case, <var class="Fa">bufq_alloc</var> returns + <code class="Dv">ENOENT</code>. If this flag is not specified, + <a class="permalink" href="#bufq_alloc~2"><code class="Fn" id="bufq_alloc~2">bufq_alloc</code></a>() + will silently use one of available strategies.</dd> + </dl> + </div> + <p class="Pp">If a specific strategy is specified but not currently + available, the <code class="Nm">bufq</code> subsystem will attempt to + auto-load the corresponding kernel module using + <a class="Xr">module_autoload(9)</a>.</p> + </dd> + <dt id="bufq_drain"><a class="permalink" href="#bufq_drain"><code class="Fn">bufq_drain</code></a>(<var class="Fa">bufq</var>)</dt> + <dd>Drain a <i class="Em">bufq_state</i> descriptor.</dd> + <dt id="bufq_free"><a class="permalink" href="#bufq_free"><code class="Fn">bufq_free</code></a>(<var class="Fa">bufq</var>)</dt> + <dd>Destroy a <i class="Em">bufq_state</i> descriptor.</dd> + <dt id="bufq_getstrategyname"><a class="permalink" href="#bufq_getstrategyname"><code class="Fn">bufq_getstrategyname</code></a>(<var class="Fa">bufq</var>)</dt> + <dd>Get a strategy identifier of a buffer queue, the string returned will be + NUL-terminated and it always will be a valid strategy name.</dd> + <dt id="bufq_move"><a class="permalink" href="#bufq_move"><code class="Fn">bufq_move</code></a>(<var class="Fa">dst</var>, + <var class="Fa">src</var>)</dt> + <dd>Move all requests from the buffer queue <var class="Fa">src</var> to the + buffer queue <var class="Fa">dst</var>.</dd> + <dt id="bufq_put"><a class="permalink" href="#bufq_put"><code class="Fn">bufq_put</code></a>(<var class="Fa">bufq</var>, + <var class="Fa">bp</var>)</dt> + <dd>Put the buf <var class="Fa">bp</var> in the queue.</dd> + <dt id="bufq_get"><a class="permalink" href="#bufq_get"><code class="Fn">bufq_get</code></a>(<var class="Fa">bufq</var>)</dt> + <dd>Get the next buf from the queue and remove it from the queue. Returns + <code class="Dv">NULL</code> if the queue is empty.</dd> + <dt id="bufq_peek"><a class="permalink" href="#bufq_peek"><code class="Fn">bufq_peek</code></a>(<var class="Fa">bufq</var>)</dt> + <dd>Get the next buf from the queue without removal. The next buf will remain + the same until <code class="Fn">bufq_get</code>(), + <code class="Fn">bufq_put</code>(), or + <code class="Fn">bufq_drain</code>() is called. Returns + <code class="Dv">NULL</code> if the queue is empty.</dd> + <dt id="bufq_cancel"><a class="permalink" href="#bufq_cancel"><code class="Fn">bufq_cancel</code></a>(<var class="Fa">bufq</var>, + <var class="Fa">bp</var>)</dt> + <dd>Cancel the buf <var class="Fa">bp</var> issued earlier on the queue. + Returns <code class="Dv">NULL</code> if the element can not be found on + the queue or <var class="Fa">bp</var> if it has been found and removed. + This operation can be computationally expensive if there are a lot of + buffers queued.</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 actual code implementing the device buffer queues can be found + in the file <span class="Pa">sys/kern/subr_bufq.c</span>. The code + implementing specific buffer queue strategies can be found in the files + <span class="Pa">sys/kern/bufq_*.c</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp">A list of currently available buffer queue strategies is available + via the “kern.bufq.strategies” <a class="Xr">sysctl(7)</a> + variables.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">bufq</code> subsystem appeared in + <span class="Ux">NetBSD 2.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">bufq</code> subsystem was written by + <span class="An">Jürgen Hannken-Illjes</span> + ⟨hannken@NetBSD.org⟩.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 17, 2016</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/bus_space.9 3.html b/static/netbsd/man9/bus_space.9 3.html new file mode 100644 index 00000000..71ce652b --- /dev/null +++ b/static/netbsd/man9/bus_space.9 3.html @@ -0,0 +1,2110 @@ +<table class="head"> + <tr> + <td class="head-ltitle">BUS_SPACE(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">BUS_SPACE(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">bus_space</code>, + <code class="Nm">bus_space_barrier</code>, + <code class="Nm">bus_space_copy_region_1</code>, + <code class="Nm">bus_space_copy_region_2</code>, + <code class="Nm">bus_space_copy_region_4</code>, + <code class="Nm">bus_space_copy_region_8</code>, + <code class="Nm">bus_space_free</code>, + <code class="Nm">bus_space_handle_is_equal</code>, + <code class="Nm">bus_space_is_equal</code>, + <code class="Nm">bus_space_map</code>, + <code class="Nm">bus_space_mmap</code>, + <code class="Nm">bus_space_peek_1</code>, + <code class="Nm">bus_space_peek_2</code>, + <code class="Nm">bus_space_peek_4</code>, + <code class="Nm">bus_space_peek_8</code>, + <code class="Nm">bus_space_poke_1</code>, + <code class="Nm">bus_space_poke_2</code>, + <code class="Nm">bus_space_poke_4</code>, + <code class="Nm">bus_space_poke_8</code>, + <code class="Nm">bus_space_read_1</code>, + <code class="Nm">bus_space_read_2</code>, + <code class="Nm">bus_space_read_4</code>, + <code class="Nm">bus_space_read_8</code>, + <code class="Nm">bus_space_read_multi_1</code>, + <code class="Nm">bus_space_read_multi_2</code>, + <code class="Nm">bus_space_read_multi_4</code>, + <code class="Nm">bus_space_read_multi_8</code>, + <code class="Nm">bus_space_read_multi_stream_1</code>, + <code class="Nm">bus_space_read_multi_stream_2</code>, + <code class="Nm">bus_space_read_multi_stream_4</code>, + <code class="Nm">bus_space_read_multi_stream_8</code>, + <code class="Nm">bus_space_read_region_1</code>, + <code class="Nm">bus_space_read_region_2</code>, + <code class="Nm">bus_space_read_region_4</code>, + <code class="Nm">bus_space_read_region_8</code>, + <code class="Nm">bus_space_read_region_stream_1</code>, + <code class="Nm">bus_space_read_region_stream_2</code>, + <code class="Nm">bus_space_read_region_stream_4</code>, + <code class="Nm">bus_space_read_region_stream_8</code>, + <code class="Nm">bus_space_read_stream_1</code>, + <code class="Nm">bus_space_read_stream_2</code>, + <code class="Nm">bus_space_read_stream_4</code>, + <code class="Nm">bus_space_read_stream_8</code>, + <code class="Nm">bus_space_release</code>, + <code class="Nm">bus_space_reservation_addr</code>, + <code class="Nm">bus_space_reservation_init</code>, + <code class="Nm">bus_space_reservation_size</code>, + <code class="Nm">bus_space_reservation_map</code>, + <code class="Nm">bus_space_reservation_unmap</code>, + <code class="Nm">bus_space_reserve</code>, + <code class="Nm">bus_space_reserve_subregion</code>, + <code class="Nm">bus_space_set_region_1</code>, + <code class="Nm">bus_space_set_region_2</code>, + <code class="Nm">bus_space_set_region_4</code>, + <code class="Nm">bus_space_set_region_8</code>, + <code class="Nm">bus_space_subregion</code>, + <code class="Nm">bus_space_tag_create</code>, + <code class="Nm">bus_space_tag_destroy</code>, + <code class="Nm">bus_space_unmap</code>, + <code class="Nm">bus_space_vaddr</code>, + <code class="Nm">bus_space_write_1</code>, + <code class="Nm">bus_space_write_2</code>, + <code class="Nm">bus_space_write_4</code>, + <code class="Nm">bus_space_write_8</code>, + <code class="Nm">bus_space_write_multi_1</code>, + <code class="Nm">bus_space_write_multi_2</code>, + <code class="Nm">bus_space_write_multi_4</code>, + <code class="Nm">bus_space_write_multi_8</code>, + <code class="Nm">bus_space_write_multi_stream_1</code>, + <code class="Nm">bus_space_write_multi_stream_2</code>, + <code class="Nm">bus_space_write_multi_stream_4</code>, + <code class="Nm">bus_space_write_multi_stream_8</code>, + <code class="Nm">bus_space_write_region_1</code>, + <code class="Nm">bus_space_write_region_2</code>, + <code class="Nm">bus_space_write_region_4</code>, + <code class="Nm">bus_space_write_region_8</code>, + <code class="Nm">bus_space_write_region_stream_1</code>, + <code class="Nm">bus_space_write_region_stream_2</code>, + <code class="Nm">bus_space_write_region_stream_4</code>, + <code class="Nm">bus_space_write_region_stream_8</code>, + <code class="Nm">bus_space_write_stream_1</code>, + <code class="Nm">bus_space_write_stream_2</code>, + <code class="Nm">bus_space_write_stream_4</code>, + <code class="Nm">bus_space_write_stream_8</code> — + <span class="Nd">bus space manipulation functions</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/bus.h</a>></code></p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">bus_space_handle_is_equal</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle1</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle2</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">bus_space_is_equal</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space1</var>, <var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space2</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_release</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + t</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t + *bsr</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_reserve</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + t</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t bpa</var>, + <var class="Fa" style="white-space: nowrap;">bus_size_t size</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t + *bsrp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_reserve_subregion</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + t</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t + reg_start</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t + reg_end</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + size</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + alignment</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + boundary</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t + *bsrp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_reservation_init</code>(<var class="Fa" style="white-space: nowrap;">bus_space_reservation_t + *bsr</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t + addr</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + size</var>);</p> +<p class="Pp"><var class="Ft">bus_size_t</var> + <br/> + <code class="Fn">bus_space_reservation_size</code>(<var class="Fa" style="white-space: nowrap;">bus_space_reservation_t + *bsr</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_reservation_map</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + t</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_reservation_t + *bsr</var>, <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + *bshp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_reservation_unmap</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + t</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + bsh</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + size</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_map</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t + address</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + size</var>, <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + *handlep</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_unmap</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + size</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_subregion</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + size</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + *nhandlep</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_alloc</code>(<var class="Fa">bus_space_tag_t + space</var>, <var class="Fa">bus_addr_t reg_start</var>, + <var class="Fa">bus_addr_t reg_end</var>, <var class="Fa">bus_size_t + size</var>, <var class="Fa">bus_size_t alignment</var>, + <var class="Fa">bus_size_t boundary</var>, <var class="Fa">int flags</var>, + <var class="Fa">bus_addr_t *addrp</var>, <var class="Fa">bus_space_handle_t + *handlep</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_free</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + size</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">bus_space_vaddr</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>);</p> +<p class="Pp"><var class="Ft">paddr_t</var> + <br/> + <code class="Fn">bus_space_mmap</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_addr_t + addr</var>, <var class="Fa" style="white-space: nowrap;">off_t off</var>, + <var class="Fa" style="white-space: nowrap;">int prot</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_tag_create</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + obst</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + present</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + extpresent</var>, <var class="Fa" style="white-space: nowrap;">const struct + bus_space_overrides *ov</var>, + <var class="Fa" style="white-space: nowrap;">void *ctx</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_tag_t + *bstp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_tag_destroy</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + bst</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_peek_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + *datap</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_peek_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + *datap</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_peek_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + *datap</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_peek_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + *datap</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_poke_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + data</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_poke_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + data</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_poke_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + data</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">bus_space_poke_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + data</var>);</p> +<p class="Pp"><var class="Ft">uint8_t</var> + <br/> + <code class="Fn">bus_space_read_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>);</p> +<p class="Pp"><var class="Ft">uint16_t</var> + <br/> + <code class="Fn">bus_space_read_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>);</p> +<p class="Pp"><var class="Ft">uint32_t</var> + <br/> + <code class="Fn">bus_space_read_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>);</p> +<p class="Pp"><var class="Ft">uint64_t</var> + <br/> + <code class="Fn">bus_space_read_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + value</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + value</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + value</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + value</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_barrier</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + length</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_region_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_region_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_copy_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + srcoffset</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_copy_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + srcoffset</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_copy_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + srcoffset</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_copy_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + srchandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + srcoffset</var>, + <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + dsthandle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + dstoffset</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_set_region_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_set_region_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_set_region_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_set_region_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + value</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_read_multi_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_stream_1</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint8_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_stream_2</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint16_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_stream_4</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint32_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bus_space_write_multi_stream_8</code>(<var class="Fa" style="white-space: nowrap;">bus_space_tag_t + space</var>, <var class="Fa" style="white-space: nowrap;">bus_space_handle_t + handle</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + offset</var>, <var class="Fa" style="white-space: nowrap;">const uint64_t + *datap</var>, <var class="Fa" style="white-space: nowrap;">bus_size_t + count</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">bus_space</code> functions exist to allow + device drivers machine-independent access to bus memory and register areas. + All of the functions and types described in this document can be used by + including the <code class="In"><<a class="In">sys/bus.h</a>></code> + header file.</p> +<p class="Pp">Many common devices are used on multiple architectures, but are + accessed differently on each because of architectural constraints. For + instance, a device which is mapped in one system's I/O space may be mapped + in memory space on a second system. On a third system, architectural + limitations might change the way registers need to be accessed (e.g., + creating a non-linear register space). In some cases, a single driver may + need to access the same type of device in multiple ways in a single system + or architecture. The goal of the <code class="Nm">bus_space</code> functions + is to allow a single driver source file to manipulate a set of devices on + different system architectures, and to allow a single driver object file to + manipulate a set of devices on multiple bus types on a single + architecture.</p> +<p class="Pp">Not all busses have to implement all functions described in this + document, though that is encouraged if the operations are logically + supported by the bus. Unimplemented functions should cause compile-time + errors if possible.</p> +<p class="Pp">All of the interface definitions described in this document are + shown as function prototypes and discussed as if they were required to be + functions. Implementations are encouraged to implement prototyped + (type-checked) versions of these interfaces, but may implement them as + macros if appropriate. Machine-dependent types, variables, and functions + should be marked clearly in + <code class="In"><<a class="In">machine/bus_defs.h</a>></code> and in + <code class="In"><<a class="In">machine/bus_funcs.h</a>></code> to + avoid confusion with the machine-independent types and functions, and, if + possible, should be given names which make the machine-dependence clear.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CONCEPTS_AND_GUIDELINES"><a class="permalink" href="#CONCEPTS_AND_GUIDELINES">CONCEPTS + AND GUIDELINES</a></h1> +<p class="Pp">Bus spaces are described by bus space tags, which can be created + only by machine-dependent code. A given machine may have several different + types of bus space (e.g., memory space and I/O space), and thus may provide + multiple different bus space tags. Individual busses or devices on a machine + may use more than one bus space tag. For instance, ISA devices are given an + ISA memory space tag and an ISA I/O space tag. Architectures may have + several different tags which represent the same type of space, for instance + because of multiple different host bus interface chipsets.</p> +<p class="Pp">A range in bus space is described by a bus address and a bus size. + The bus address describes the start of the range in bus space. The bus size + describes the size of the range in bytes. Busses which are not byte + addressable may require use of bus space ranges with appropriately aligned + addresses and properly rounded sizes.</p> +<p class="Pp">Access to regions of bus space is facilitated by use of bus space + handles, which are usually created by mapping a specific range of a bus + space. Handles may also be created by allocating and mapping a range of bus + space, the actual location of which is picked by the implementation within + bounds specified by the caller of the allocation function.</p> +<p class="Pp">All of the bus space access functions require one bus space tag + argument, at least one handle argument, and at least one offset argument (a + bus size). The bus space tag specifies the space, each handle specifies a + region in the space, and each offset specifies the offset into the region of + the actual location(s) to be accessed. Offsets are given in bytes, though + busses may impose alignment constraints. The offset used to access data + relative to a given handle must be such that all of the data being accessed + is in the mapped region that the handle describes. Trying to access data + outside that region is an error.</p> +<p class="Pp" id="bus_space_barrier">Bus space I/O operations on mappings made + with <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> or + <code class="Dv">BUS_SPACE_MAP_CACHEABLE</code> may be reordered or combined + for performance on devices that support it, such as write-combining (a.k.a. + ‘prefetchable’) graphics framebuffers or cacheable ROM images. + The + <a class="permalink" href="#bus_space_barrier"><code class="Fn">bus_space_barrier</code></a>() + function orders reads and writes in prefetchable or cacheable mappings + relative to other reads and writes in bus spaces. Barriers are needed + <a class="permalink" href="#only"><i class="Em" id="only">only</i></a> when + prefetchable or cacheable mappings are involved:</p> +<ul class="Bl-bullet"> + <li>Bus space reads and writes on non-prefetchable, non-cacheable mappings at + a single device are totally ordered with one another.</li> + <li>Ordering of memory operations on normal memory with bus space I/O for + triggering DMA or being notified of DMA completion requires + <a class="Xr">bus_dmamap_sync(9)</a>.</li> +</ul> +<p class="Pp">People trying to write portable drivers with the + <code class="Nm">bus_space</code> functions should try to make minimal + assumptions about what the system allows. In particular, they should expect + that the system requires bus space addresses being accessed to be naturally + aligned (i.e., base address of handle added to offset is a multiple of the + access size), and that the system does alignment checking on pointers (i.e., + pointer to objects being read and written must point to properly-aligned + data).</p> +<p class="Pp">The descriptions of the <code class="Nm">bus_space</code> + functions given below all assume that they are called with proper arguments. + If called with invalid arguments or arguments that are out of range (e.g., + trying to access data outside of the region mapped when a given handle was + created), undefined behaviour results. In that case, they may cause the + system to halt, either intentionally (via panic) or unintentionally (by + causing a fatal trap or by some other means) or may cause improper operation + which is not immediately fatal. Functions which return void or which return + data read from bus space (i.e., functions which don't obviously return an + error code) do not fail. They could only fail if given invalid arguments, + and in that case their behaviour is undefined. Functions which take a count + of bytes have undefined results if the specified <var class="Fa">count</var> + is zero.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="TYPES"><a class="permalink" href="#TYPES">TYPES</a></h1> +<p class="Pp">Several types are defined in + <code class="In"><<a class="In">machine/bus_defs.h</a>></code> to + facilitate use of the <code class="Nm">bus_space</code> functions by + drivers.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt><var class="Fa">bus_addr_t</var></dt> + <dd> + <p class="Pp">The <var class="Fa">bus_addr_t</var> type is used to describe + bus addresses. It must be an unsigned integral type capable of holding + the largest bus address usable by the architecture. This type is + primarily used when mapping and unmapping bus space.</p> + <p class="Pp"></p> + </dd> + <dt><var class="Fa">bus_size_t</var></dt> + <dd> + <p class="Pp">The <var class="Fa">bus_size_t</var> type is used to describe + sizes of ranges in bus space. It must be an unsigned integral type + capable of holding the size of the largest bus address range usable on + the architecture. This type is used by virtually all of the + <code class="Nm">bus_space</code> functions, describing sizes when + mapping regions and offsets into regions when performing space access + operations.</p> + <p class="Pp"></p> + </dd> + <dt><var class="Fa">bus_space_tag_t</var></dt> + <dd> + <p class="Pp">The <var class="Fa">bus_space_tag_t</var> type is used to + describe a particular bus space on a machine. Its contents are + machine-dependent and should be considered opaque by machine-independent + code. This type is used by all <code class="Nm">bus_space</code> + functions to name the space on which they're operating.</p> + <p class="Pp"></p> + </dd> + <dt><var class="Fa">bus_space_handle_t</var></dt> + <dd> + <p class="Pp">The <var class="Fa">bus_space_handle_t</var> type is used to + describe a mapping of a range of bus space. Its contents are + machine-dependent and should be considered opaque by machine-independent + code. This type is used when performing bus space access operations.</p> + <p class="Pp"></p> + </dd> + <dt><var class="Fa">bus_space_reservation_t</var></dt> + <dd> + <p class="Pp" id="bus_space_reservation_init">The + <var class="Fa">bus_space_reservation_t</var> type is used to describe a + range of bus space. It logically consists of a + <var class="Fa">bus_addr_t</var>, the first address in the range, and a + <var class="Fa">bus_size_t</var>, the length in bytes of the range. + Machine-independent code creates and interrogates a + <var class="Fa">bus_space_reservation_t</var> using a constructor, + <a class="permalink" href="#bus_space_reservation_init"><code class="Fn">bus_space_reservation_init</code></a>(), + and accessor functions, + <a class="permalink" href="#bus_space_reservation_addr"><code class="Fn" id="bus_space_reservation_addr">bus_space_reservation_addr</code></a>() + and + <a class="permalink" href="#bus_space_reservation_size"><code class="Fn" id="bus_space_reservation_size">bus_space_reservation_size</code></a>().</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="COMPARING_BUS_SPACE_TAGS"><a class="permalink" href="#COMPARING_BUS_SPACE_TAGS">COMPARING + BUS SPACE TAGS</a></h1> +<p class="Pp">To check whether or not one <var class="Fa">bus_space_tag_t</var> + refers to the same space as another in machine-independent code, do not use + either <a class="Xr">memcmp(9)</a> or the C equals (==) operator. Use + <a class="permalink" href="#bus_space_is_equal"><code class="Fn" id="bus_space_is_equal">bus_space_is_equal</code></a>(), + instead.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MAPPING_AND_UNMAPPING_BUS_SPACE"><a class="permalink" href="#MAPPING_AND_UNMAPPING_BUS_SPACE">MAPPING + AND UNMAPPING BUS SPACE</a></h1> +<p class="Pp">Bus space must be mapped before it can be used, and should be + unmapped when it is no longer needed. The + <code class="Fn">bus_space_map</code>(), + <code class="Fn">bus_space_reservation_map</code>(), + <code class="Fn">bus_space_reservation_unmap</code>(), and + <code class="Fn">bus_space_unmap</code>() functions provide these + capabilities.</p> +<p class="Pp" id="bus_space_subregion">Some drivers need to be able to pass a + subregion of already-mapped bus space to another driver or module within a + driver. The + <a class="permalink" href="#bus_space_subregion"><code class="Fn">bus_space_subregion</code></a>() + function allows such subregions to be created.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_map"><a class="permalink" href="#bus_space_map"><code class="Fn">bus_space_map</code></a>(<var class="Fa">space</var>, + <var class="Fa">address</var>, <var class="Fa">size</var>, + <var class="Fa">flags</var>, <var class="Fa">handlep</var>)</dt> + <dd> + <p class="Pp" id="bus_space_map~2">The + <a class="permalink" href="#bus_space_map~2"><code class="Fn">bus_space_map</code></a>() + function exclusively reserves and maps the region of bus space named by + the <var class="Fa">space</var>, <var class="Fa">address</var>, and + <var class="Fa">size</var> arguments. If successful, it returns zero and + fills in the bus space handle pointed to by + <var class="Fa">handlep</var> with the handle that can be used to access + the mapped region. If unsuccessful, it will return non-zero and leave + the bus space handle pointed to by <var class="Fa">handlep</var> in an + undefined state.</p> + <p class="Pp">The <var class="Fa">flags</var> argument controls how the + space is to be mapped. Supported flags include:</p> + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt id="BUS_SPACE_MAP_CACHEABLE"><a class="permalink" href="#BUS_SPACE_MAP_CACHEABLE"><code class="Dv">BUS_SPACE_MAP_CACHEABLE</code></a></dt> + <dd>Try to map the space so that accesses can be cached by the system + cache. If this flag is not specified, the implementation should map + the space so that it will not be cached. This mapping method will only + be useful in very rare occasions. + <p class="Pp">This flag must have a value of 1 on all implementations + for backward compatibility.</p> + </dd> + <dt id="BUS_SPACE_MAP_PREFETCHABLE"><a class="permalink" href="#BUS_SPACE_MAP_PREFETCHABLE"><code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code></a></dt> + <dd>Try to map the space so that accesses can be prefetched by the system, + and writes can be buffered. This means, accesses should be side effect + free (idempotent). The + <a class="permalink" href="#bus_space_barrier~2"><code class="Fn" id="bus_space_barrier~2">bus_space_barrier</code></a>() + methods will flush the write buffer or force actual read accesses. If + this flag is not specified, the implementation should map the space so + that it will not be prefetched or delayed.</dd> + <dt id="BUS_SPACE_MAP_LINEAR"><a class="permalink" href="#BUS_SPACE_MAP_LINEAR"><code class="Dv">BUS_SPACE_MAP_LINEAR</code></a></dt> + <dd>Try to map the space so that its contents can be accessed linearly via + normal memory access methods (e.g., pointer dereferencing and + structure accesses). The <code class="Fn">bus_space_vaddr</code>() + method can be used to obtain the kernel virtual address of the mapped + range. This is useful when software wants to do direct access to a + memory device, e.g., a frame buffer. If this flag is specified and + linear mapping is not possible, the + <code class="Fn">bus_space_map</code>() call should fail. If this flag + is not specified, the system may map the space in whatever way is most + convenient. Use of this mapping method is not encouraged for normal + device access; where linear access is not essential, use of the + <a class="permalink" href="#bus_space_read/write"><code class="Fn" id="bus_space_read/write">bus_space_read/write</code></a>() + methods is strongly recommended.</dd> + </dl> + </div> + <p class="Pp">Not all combinations of flags make sense or are supported with + all spaces. For instance, + <code class="Dv">BUS_SPACE_MAP_CACHEABLE</code> may be meaningless when + used on many systems' I/O port spaces, and on some systems + <code class="Dv">BUS_SPACE_MAP_LINEAR</code> without + <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> may never work. When + the system hardware or firmware provides hints as to how spaces should + be mapped (e.g., the PCI memory mapping registers' + "prefetchable" bit), those hints should be followed for + maximum compatibility. On some systems, requesting a mapping that cannot + be satisfied (e.g., requesting a non-prefetchable mapping when the + system can only provide a prefetchable one) will cause the request to + fail.</p> + <p class="Pp">Some implementations may keep track of use of bus space for + some or all bus spaces and refuse to allow duplicate allocations. This + is encouraged for bus spaces which have no notion of slot-specific space + addressing, such as ISA and VME, and for spaces which coexist with those + spaces (e.g., EISA and PCI memory and I/O spaces co-existing with ISA + memory and I/O spaces).</p> + <p class="Pp">Mapped regions may contain areas for which there is no device + on the bus. If space in those areas is accessed, the results are + bus-dependent.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_reservation_map"><a class="permalink" href="#bus_space_reservation_map"><code class="Fn">bus_space_reservation_map</code></a>(<var class="Fa">space</var>, + <var class="Fa">bsr</var>, <var class="Fa">flags</var>, + <var class="Fa">handlep</var>)</dt> + <dd> + <p class="Pp" id="bus_space_reservation_map~2">The + <a class="permalink" href="#bus_space_reservation_map~2"><code class="Fn">bus_space_reservation_map</code></a>() + function is similar to <code class="Fn">bus_space_map</code>() but it + maps a region of bus space that was previously reserved by a call to + <code class="Fn">bus_space_reserve</code>() or + <code class="Fn">bus_space_reserve_subregion</code>(). The region is + given by the <var class="Fa">space</var> and <var class="Fa">bsr</var> + arguments. If successful, it returns zero and fills in the bus space + handle pointed to by <var class="Fa">handlep</var> with the handle that + can be used to access the mapped region. If unsuccessful, it will return + non-zero and leave the bus space handle pointed to by + <var class="Fa">handlep</var> in an undefined state.</p> + <p class="Pp" id="bus_space_reservation_map~3">A region mapped by + <a class="permalink" href="#bus_space_reservation_map~3"><code class="Fn">bus_space_reservation_map</code></a>() + may only be unmapped by a call to + <code class="Fn">bus_space_reservation_unmap</code>().</p> + <p class="Pp" id="bus_space_map~3">For more details, see the description of + <a class="permalink" href="#bus_space_map~3"><code class="Fn">bus_space_map</code></a>().</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_unmap"><a class="permalink" href="#bus_space_unmap"><code class="Fn">bus_space_unmap</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">size</var>)</dt> + <dd> + <p class="Pp" id="bus_space_unmap~2">The + <a class="permalink" href="#bus_space_unmap~2"><code class="Fn">bus_space_unmap</code></a>() + function unmaps and relinquishes a region of bus space reserved and + mapped with <code class="Fn">bus_space_map</code>(). When unmapping a + region, the <var class="Fa">size</var> specified should be the same as + the size given to <code class="Fn">bus_space_map</code>() when mapping + that region.</p> + <p class="Pp" id="bus_space_unmap~3">After + <a class="permalink" href="#bus_space_unmap~3"><code class="Fn">bus_space_unmap</code></a>() + is called on a handle, that handle is no longer valid. (If copies were + made of the handle they are no longer valid, either.)</p> + <p class="Pp" id="bus_space_unmap~4">This function will never fail. If it + would fail (e.g., because of an argument error), that indicates a + software bug which should cause a panic. In that case, + <a class="permalink" href="#bus_space_unmap~4"><code class="Fn">bus_space_unmap</code></a>() + will never return.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_reservation_unmap"><a class="permalink" href="#bus_space_reservation_unmap"><code class="Fn">bus_space_reservation_unmap</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">size</var>)</dt> + <dd> + <p class="Pp" id="bus_space_reservation_unmap~2">The + <a class="permalink" href="#bus_space_reservation_unmap~2"><code class="Fn">bus_space_reservation_unmap</code></a>() + function is similar to <code class="Fn">bus_space_unmap</code>() but it + should be called on handles mapped by + <code class="Fn">bus_space_reservation_map</code>() and only on such + handles. Unlike <code class="Fn">bus_space_unmap</code>(), + <code class="Fn">bus_space_reservation_unmap</code>() does not + relinquish exclusive use of the bus space named by + <var class="Fa">handle</var> and <var class="Fa">size</var>; that is the + job of <code class="Fn">bus_space_release</code>().</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_subregion~2"><a class="permalink" href="#bus_space_subregion~2"><code class="Fn">bus_space_subregion</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">size</var>, <var class="Fa">nhandlep</var>)</dt> + <dd> + <p class="Pp" id="bus_space_subregion~3">The + <a class="permalink" href="#bus_space_subregion~3"><code class="Fn">bus_space_subregion</code></a>() + function is a convenience function which makes a new handle to some + subregion of an already-mapped region of bus space. The subregion + described by the new handle starts at byte offset + <var class="Fa">offset</var> into the region described by + <var class="Fa">handle</var>, with the size given by + <var class="Fa">size</var>, and must be wholly contained within the + original region.</p> + <p class="Pp" id="bus_space_subregion~4">If successful, + <a class="permalink" href="#bus_space_subregion~4"><code class="Fn">bus_space_subregion</code></a>() + returns zero and fills in the bus space handle pointed to by + <var class="Fa">nhandlep</var>. If unsuccessful, it returns non-zero and + leaves the bus space handle pointed to by <var class="Fa">nhandlep</var> + in an undefined state. In either case, the handle described by + <var class="Fa">handle</var> remains valid and is unmodified.</p> + <p class="Pp" id="bus_space_subregion~5">When done with a handle created by + <a class="permalink" href="#bus_space_subregion~5"><code class="Fn">bus_space_subregion</code></a>(), + the handle should be thrown away. Under no circumstances should + <code class="Fn">bus_space_unmap</code>() be used on the handle. Doing + so may confuse any resource management being done on the space, and will + result in undefined behaviour. When + <code class="Fn">bus_space_unmap</code>() or + <code class="Fn">bus_space_free</code>() is called on a handle, all + subregions of that handle become invalid.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_vaddr"><a class="permalink" href="#bus_space_vaddr"><code class="Fn">bus_space_vaddr</code></a>(<var class="Fa">tag</var>, + <var class="Fa">handle</var>)</dt> + <dd> + <p class="Pp" id="bus_space_barrier~3">This method returns the kernel + virtual address of a mapped bus space if and only if it was mapped with + the <code class="Dv">BUS_SPACE_MAP_LINEAR</code> flag. The range can be + accessed by normal (volatile) pointer dereferences. If mapped with the + <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> flag, the + <a class="permalink" href="#bus_space_barrier~3"><code class="Fn">bus_space_barrier</code></a>() + method must be used to force a particular access order.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_mmap"><a class="permalink" href="#bus_space_mmap"><code class="Fn">bus_space_mmap</code></a>(<var class="Fa">tag</var>, + <var class="Fa">addr</var>, <var class="Fa">off</var>, + <var class="Fa">prot</var>, <var class="Fa">flags</var>)</dt> + <dd> + <p class="Pp" id="bus_space_mmap~2">This method is used to provide support + for memory mapping bus space into user applications. If an address space + is addressable via volatile pointer dereferences, + <a class="permalink" href="#bus_space_mmap~2"><code class="Fn">bus_space_mmap</code></a>() + will return the physical address (possibly encoded as a + machine-dependent cookie) of the bus space indicated by + <var class="Fa">addr</var> and <var class="Fa">off</var>. + <var class="Fa">addr</var> is the base address of the device or device + region, and <var class="Fa">off</var> is the offset into that region + that is being requested. If the request is made with + <code class="Dv">BUS_SPACE_MAP_LINEAR</code> as a flag, then a linear + region must be returned to the caller. If the region cannot be mapped + (either the address does not exist, or the constraints can not be met), + <code class="Fn">bus_space_mmap</code>() returns + <code class="Dv">-1</code> to indicate failure.</p> + <p class="Pp" id="bus_space_mmap~3">Note that it is not necessary that the + region being requested by a + <a class="permalink" href="#bus_space_mmap~3"><code class="Fn">bus_space_mmap</code></a>() + call be mapped into a <var class="Fa">bus_space_handle_t</var>.</p> + <p class="Pp" id="bus_space_mmap~4"><a class="permalink" href="#bus_space_mmap~4"><code class="Fn">bus_space_mmap</code></a>() + is called once per <code class="Dv">PAGE_SIZE</code> page in the range. + The <var class="Fa">prot</var> argument indicates the memory protection + requested by the user application for the range.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_handle_is_equal"><a class="permalink" href="#bus_space_handle_is_equal"><code class="Fn">bus_space_handle_is_equal</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle1</var>, <var class="Fa">handle2</var>)</dt> + <dd>Use <code class="Fn">bus_space_handle_is_equal</code>() to check whether + or not <var class="Fa">handle1</var> and <var class="Fa">handle2</var> + refer to regions starting at the same address in the bus space + <var class="Fa">space</var>.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="ALLOCATING_AND_FREEING_BUS_SPACE"><a class="permalink" href="#ALLOCATING_AND_FREEING_BUS_SPACE">ALLOCATING + AND FREEING BUS SPACE</a></h1> +<p class="Pp">Some devices require or allow bus space to be allocated by the + operating system for device use. When the devices no longer need the space, + the operating system should free it for use by other devices. The + <code class="Fn">bus_space_alloc</code>(), + <code class="Fn">bus_space_free</code>(), + <code class="Fn">bus_space_reserve</code>(), + <code class="Fn">bus_space_reserve_subregion</code>(), and + <code class="Fn">bus_space_release</code>() functions provide these + capabilities. The functions <code class="Fn">bus_space_reserve</code>(), + <code class="Fn">bus_space_reserve_subregion</code>(), and + <code class="Fn">bus_space_release</code>() are not yet available on all + architectures.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_alloc"><a class="permalink" href="#bus_space_alloc"><code class="Fn">bus_space_alloc</code></a>(<var class="Fa">space</var>, + <var class="Fa">reg_start</var>, <var class="Fa">reg_end</var>, + <var class="Fa">size</var>, <var class="Fa">alignment</var>, + <var class="Fa">boundary</var>, <var class="Fa">flags</var>, + <var class="Fa">addrp</var>, <var class="Fa">handlep</var>)</dt> + <dd> + <p class="Pp" id="bus_space_alloc~2">The + <a class="permalink" href="#bus_space_alloc~2"><code class="Fn">bus_space_alloc</code></a>() + function allocates and maps a region of bus space with the size given by + <var class="Fa">size</var>, corresponding to the given constraints. If + successful, it returns zero, fills in the bus address pointed to by + <var class="Fa">addrp</var> with the bus space address of the allocated + region, and fills in the bus space handle pointed to by + <var class="Fa">handlep</var> with the handle that can be used to access + that region. If unsuccessful, it returns non-zero and leaves the bus + address pointed to by <var class="Fa">addrp</var> and the bus space + handle pointed to by <var class="Fa">handlep</var> in an undefined + state.</p> + <p class="Pp" id="bus_space_alloc~3">Constraints on the allocation are given + by the <var class="Fa">reg_start</var>, <var class="Fa">reg_end</var>, + <var class="Fa">alignment</var>, and <var class="Fa">boundary</var> + parameters. The allocated region will start at or after + <var class="Fa">reg_start</var> and end before or at + <var class="Fa">reg_end</var>. The <var class="Fa">alignment</var> + constraint must be a power of two, and the allocated region will start + at an address that is an even multiple of that power of two. The + <var class="Fa">boundary</var> constraint, if non-zero, ensures that the + region is allocated so that <var class="Fa">first address in + region</var> / <var class="Fa">boundary</var> has the same value as + <var class="Fa">last address in region</var> / + <var class="Fa">boundary</var>. If the constraints cannot be met, + <a class="permalink" href="#bus_space_alloc~3"><code class="Fn">bus_space_alloc</code></a>() + will fail. It is an error to specify a set of constraints that can never + be met (for example, <var class="Fa">size</var> greater than + <var class="Fa">boundary</var>).</p> + <p class="Pp">The <var class="Fa">flags</var> parameter is the same as the + like-named parameter to <var class="Fa">bus_space_map</var>, the same + flag values should be used, and they have the same meanings.</p> + <p class="Pp" id="bus_space_alloc~4">Handles created by + <a class="permalink" href="#bus_space_alloc~4"><code class="Fn">bus_space_alloc</code></a>() + should only be freed with <code class="Fn">bus_space_free</code>(). + Trying to use <code class="Fn">bus_space_unmap</code>() on them causes + undefined behaviour. The <code class="Fn">bus_space_subregion</code>() + function can be used on handles created by + <code class="Fn">bus_space_alloc</code>().</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_reserve"><a class="permalink" href="#bus_space_reserve"><code class="Fn">bus_space_reserve</code></a>(<var class="Fa">t</var>, + <var class="Fa">bpa</var>, <var class="Fa">size</var>, + <var class="Fa">flags</var>, <var class="Fa">bsrp</var>)</dt> + <dd> + <p class="Pp" id="bus_space_reserve~2">The + <a class="permalink" href="#bus_space_reserve~2"><code class="Fn">bus_space_reserve</code></a>() + function reserves, for the caller's exclusive use, + <var class="Fa">size</var> bytes starting at the address + <var class="Fa">bpa</var> in the space referenced by + <var class="Fa">t</var>.</p> + <p class="Pp" id="bus_space_reserve~3"><a class="permalink" href="#bus_space_reserve~3"><code class="Fn">bus_space_reserve</code></a>() + does <a class="permalink" href="#not"><i class="Em" id="not">not</i></a> + map the space. The caller should use + <code class="Fn">bus_space_reservation_map</code>() to map the + reservation. <var class="Fa">flags</var> contains a hint how the caller + may map the reservation, later. Whenever possible, callers should pass + the same flags to <code class="Fn">bus_space_reserve</code>() as they + will pass to <code class="Fn">bus_space_reservation_map</code>() to map + the reservation.</p> + <p class="Pp" id="bus_space_reserve~4">On success, + <a class="permalink" href="#bus_space_reserve~4"><code class="Fn">bus_space_reserve</code></a>() + records the reservation at <var class="Fa">bsrp</var> and returns 0. On + failure, <var class="Fa">bsrp</var> is undefined, and + <code class="Fn">bus_space_reserve</code>() returns a non-zero error + code. Possible error codes include</p> + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt><code class="Er">ENOMEM</code></dt> + <dd>There was not sufficient bus space at <var class="Fa">bpa</var> to + satisfy the request.</dd> + <dt><code class="Er">EOPNOTSUPP</code></dt> + <dd><code class="Fn">bus_space_reserve</code>() is not supported on this + architecture, or <var class="Fa">flags</var> was incompatible with the + bus space represented by <var class="Fa">t</var>.</dd> + </dl> + </div> + <p class="Pp"></p> + </dd> + <dt id="bus_space_reserve_subregion"><a class="permalink" href="#bus_space_reserve_subregion"><code class="Fn">bus_space_reserve_subregion</code></a>(<var class="Fa">t</var>, + <var class="Fa">reg_start</var>, <var class="Fa">reg_end</var>, + <var class="Fa">size</var>, <var class="Fa">alignment</var>, + <var class="Fa">boundary</var>, <var class="Fa">flags</var>, + <var class="Fa">bsrp</var>)</dt> + <dd> + <p class="Pp" id="bus_space_reserve_subregion~2">The + <a class="permalink" href="#bus_space_reserve_subregion~2"><code class="Fn">bus_space_reserve_subregion</code></a>() + function reserves, for the caller's exclusive use, + <var class="Fa">size</var> bytes in the space referenced by + <var class="Fa">t</var>. The parameters <var class="Fa">reg_start</var>, + <var class="Fa">reg_end</var>, <var class="Fa">alignment</var>, + <var class="Fa">boundary</var>, and <var class="Fa">flags</var> each + work alike to the <code class="Fn">bus_space_alloc</code>() parameters + of the same names.</p> + <p class="Pp" id="bus_space_reserve_subregion~3">On success, + <a class="permalink" href="#bus_space_reserve_subregion~3"><code class="Fn">bus_space_reserve_subregion</code></a>() + records the reservation at <var class="Fa">bsrp</var> and returns 0. On + failure, <var class="Fa">bsrp</var> is undefined, and + <code class="Fn">bus_space_reserve_subregion</code>() returns a non-zero + error code. Possible error codes include</p> + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt><code class="Er">ENOMEM</code></dt> + <dd>There was not sufficient bus space at <var class="Fa">bpa</var> to + satisfy the request.</dd> + <dt><code class="Er">EOPNOTSUPP</code></dt> + <dd><code class="Fn">bus_space_reserve</code>() is not supported on this + architecture, or <var class="Fa">flags</var> was incompatible with the + bus space represented by <var class="Fa">t</var>.</dd> + </dl> + </div> + <p class="Pp"></p> + </dd> + <dt id="bus_space_release"><a class="permalink" href="#bus_space_release"><code class="Fn">bus_space_release</code></a>(<var class="Fa">t</var>, + <var class="Fa">bsr</var>)</dt> + <dd> + <p class="Pp" id="bus_space_release~2">The + <a class="permalink" href="#bus_space_release~2"><code class="Fn">bus_space_release</code></a>() + function releases the bus space <var class="Fa">bsr</var> in + <var class="Fa">t</var> that was previously reserved by + <code class="Fn">bus_space_reserve</code>() or + <code class="Fn">bus_space_reserve_subregion</code>().</p> + <p class="Pp" id="bus_space_release~3">If + <a class="permalink" href="#bus_space_release~3"><code class="Fn">bus_space_release</code></a>() + is called on a reservation that has been mapped by + <code class="Fn">bus_space_reservation_map</code>() without subsequently + being unmapped, the behavior of the system is undefined.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_free"><a class="permalink" href="#bus_space_free"><code class="Fn">bus_space_free</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">size</var>)</dt> + <dd> + <p class="Pp" id="bus_space_free~2">The + <a class="permalink" href="#bus_space_free~2"><code class="Fn">bus_space_free</code></a>() + function unmaps and frees a region of bus space mapped and allocated + with <code class="Fn">bus_space_alloc</code>(). When unmapping a region, + the <var class="Fa">size</var> specified should be the same as the size + given to <code class="Fn">bus_space_alloc</code>() when allocating the + region.</p> + <p class="Pp" id="bus_space_free~3">After + <a class="permalink" href="#bus_space_free~3"><code class="Fn">bus_space_free</code></a>() + is called on a handle, that handle is no longer valid. (If copies were + made of the handle, they are no longer valid, either.)</p> + <p class="Pp" id="bus_space_free~4">This function will never fail. If it + would fail (e.g., because of an argument error), that indicates a + software bug which should cause a panic. In that case, + <a class="permalink" href="#bus_space_free~4"><code class="Fn">bus_space_free</code></a>() + will never return.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="READING_AND_WRITING_SINGLE_DATA_ITEMS"><a class="permalink" href="#READING_AND_WRITING_SINGLE_DATA_ITEMS">READING + AND WRITING SINGLE DATA ITEMS</a></h1> +<p class="Pp">The simplest way to access bus space is to read or write a single + data item. The <code class="Fn">bus_space_read_N</code>() and + <code class="Fn">bus_space_write_N</code>() families of functions provide + the ability to read and write 1, 2, 4, and 8 byte data items on busses which + support those access sizes.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_read_1"><a class="permalink" href="#bus_space_read_1"><code class="Fn">bus_space_read_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd></dd> + <dt id="bus_space_read_2"><a class="permalink" href="#bus_space_read_2"><code class="Fn">bus_space_read_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd></dd> + <dt id="bus_space_read_4"><a class="permalink" href="#bus_space_read_4"><code class="Fn">bus_space_read_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd></dd> + <dt id="bus_space_read_8"><a class="permalink" href="#bus_space_read_8"><code class="Fn">bus_space_read_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd> + <p class="Pp" id="bus_space_read_N">The + <a class="permalink" href="#bus_space_read_N"><code class="Fn">bus_space_read_N</code></a>() + family of functions reads a 1, 2, 4, or 8 byte data item from the offset + specified by <var class="Fa">offset</var> into the region specified by + <var class="Fa">handle</var> of the bus space specified by + <var class="Fa">space</var>. The location being read must lie within the + bus space region specified by <var class="Fa">handle</var>.</p> + <p class="Pp">For portability, the starting address of the region specified + by <var class="Fa">handle</var> plus the offset should be a multiple of + the size of data item being read. On some systems, not obeying this + requirement may cause incorrect data to be read, on others it may cause + a system crash.</p> + <p class="Pp" id="bus_space_read_N~2">Read operations done by the + <a class="permalink" href="#bus_space_read_N~2"><code class="Fn">bus_space_read_N</code></a>() + functions may be executed out of order with respect to other read and + write operations if either are on prefetchable or cacheable mappings + unless order is enforced by use of the + <code class="Fn">bus_space_barrier</code>() function.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_write_1"><a class="permalink" href="#bus_space_write_1"><code class="Fn">bus_space_write_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_write_2"><a class="permalink" href="#bus_space_write_2"><code class="Fn">bus_space_write_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_write_4"><a class="permalink" href="#bus_space_write_4"><code class="Fn">bus_space_write_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_write_8"><a class="permalink" href="#bus_space_write_8"><code class="Fn">bus_space_write_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd> + <p class="Pp" id="bus_space_write_N">The + <a class="permalink" href="#bus_space_write_N"><code class="Fn">bus_space_write_N</code></a>() + family of functions writes a 1, 2, 4, or 8 byte data item to the offset + specified by <var class="Fa">offset</var> into the region specified by + <var class="Fa">handle</var> of the bus space specified by + <var class="Fa">space</var>. The location being written must lie within + the bus space region specified by <var class="Fa">handle</var>.</p> + <p class="Pp">For portability, the starting address of the region specified + by <var class="Fa">handle</var> plus the offset should be a multiple of + the size of data item being written. On some systems, not obeying this + requirement may cause incorrect data to be written, on others it may + cause a system crash.</p> + <p class="Pp" id="bus_space_write_N~2">Write operations done by the + <a class="permalink" href="#bus_space_write_N~2"><code class="Fn">bus_space_write_N</code></a>() + functions may be executed out of order with respect to other read and + write operations if either are on prefetchable or cacheable mappings + unless order is enforced by use of the + <code class="Fn">bus_space_barrier</code>() function.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="PROBING_BUS_SPACE_FOR_HARDWARE_WHICH_MAY_NOT_RESPOND"><a class="permalink" href="#PROBING_BUS_SPACE_FOR_HARDWARE_WHICH_MAY_NOT_RESPOND">PROBING + BUS SPACE FOR HARDWARE WHICH MAY NOT RESPOND</a></h1> +<p class="Pp">One problem with the + <a class="permalink" href="#bus_space_read_N~3"><code class="Fn" id="bus_space_read_N~3">bus_space_read_N</code></a>() + and <code class="Fn">bus_space_write_N</code>() family of functions is that + they provide no protection against exceptions which can occur when no + physical hardware or device responds to the read or write cycles. In such a + situation, the system typically would panic due to a kernel-mode bus error. + The <code class="Fn">bus_space_peek_N</code>() and + <code class="Fn">bus_space_poke_N</code>() family of functions provide a + mechanism to handle these exceptions gracefully without the risk of crashing + the system.</p> +<p class="Pp" id="bus_space_read_N~4">As with + <a class="permalink" href="#bus_space_read_N~4"><code class="Fn">bus_space_read_N</code></a>() + and <code class="Fn">bus_space_write_N</code>(), the peek and poke functions + provide the ability to read and write 1, 2, 4, and 8 byte data items on + busses which support those access sizes. All of the constraints specified in + the descriptions of the <code class="Fn">bus_space_read_N</code>() and + <code class="Fn">bus_space_write_N</code>() functions also apply to + <code class="Fn">bus_space_peek_N</code>() and + <code class="Fn">bus_space_poke_N</code>().</p> +<p class="Pp" id="bus_space_peek_N">The return value indicates the outcome of + the peek or poke operation. A return value of zero implies that a hardware + device is responding to the operation at the specified offset in the bus + space. A non-zero return value indicates that the kernel intercepted a + hardware exception (e.g., bus error) when the peek or poke operation was + attempted. Note that some busses are incapable of generating exceptions when + non-existent hardware is accessed. In such cases, these functions will + always return zero and the value of the data read by + <a class="permalink" href="#bus_space_peek_N"><code class="Fn">bus_space_peek_N</code></a>() + will be unspecified.</p> +<p class="Pp" id="bus_space_peek_N~2">Finally, it should be noted that at this + time the + <a class="permalink" href="#bus_space_peek_N~2"><code class="Fn">bus_space_peek_N</code></a>() + and <code class="Fn">bus_space_poke_N</code>() functions are not re-entrant + and should not, therefore, be used from within an interrupt service routine. + This constraint may be removed at some point in the future.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_peek_1"><a class="permalink" href="#bus_space_peek_1"><code class="Fn">bus_space_peek_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>)</dt> + <dd></dd> + <dt id="bus_space_peek_2"><a class="permalink" href="#bus_space_peek_2"><code class="Fn">bus_space_peek_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>)</dt> + <dd></dd> + <dt id="bus_space_peek_4"><a class="permalink" href="#bus_space_peek_4"><code class="Fn">bus_space_peek_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>)</dt> + <dd></dd> + <dt id="bus_space_peek_8"><a class="permalink" href="#bus_space_peek_8"><code class="Fn">bus_space_peek_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>)</dt> + <dd> + <p class="Pp" id="bus_space_peek_N~3">The + <a class="permalink" href="#bus_space_peek_N~3"><code class="Fn">bus_space_peek_N</code></a>() + family of functions cautiously read a 1, 2, 4, or 8 byte data item from + the offset specified by <var class="Fa">offset</var> in the region + specified by <var class="Fa">handle</var> of the bus space specified by + <var class="Fa">space</var>. The data item read is stored in the + location pointed to by <var class="Fa">datap</var>. It is permissible + for <var class="Fa">datap</var> to be NULL, in which case the data item + will be discarded after being read.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_poke_1"><a class="permalink" href="#bus_space_poke_1"><code class="Fn">bus_space_poke_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_poke_2"><a class="permalink" href="#bus_space_poke_2"><code class="Fn">bus_space_poke_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_poke_4"><a class="permalink" href="#bus_space_poke_4"><code class="Fn">bus_space_poke_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_poke_8"><a class="permalink" href="#bus_space_poke_8"><code class="Fn">bus_space_poke_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd> + <p class="Pp" id="bus_space_poke_N">The + <a class="permalink" href="#bus_space_poke_N"><code class="Fn">bus_space_poke_N</code></a>() + family of functions cautiously write a 1, 2, 4, or 8 byte data item + specified by <var class="Fa">value</var> to the offset specified by + <var class="Fa">offset</var> in the region specified by + <var class="Fa">handle</var> of the bus space specified by + <var class="Fa">space</var>.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="BARRIERS"><a class="permalink" href="#BARRIERS">BARRIERS</a></h1> +<p class="Pp">Devices that support prefetchable (also known as + ‘write-combining’) or cacheable I/O may be mapped with + <code class="Dv">BUS_SPACE_MAP_PREFETCHABLE</code> or + <code class="Dv">BUS_SPACE_MAP_CACHEABLE</code> for higher performance by + allowing bus space read and write operations to be reordered, fused, torn, + and/or cached by the system.</p> +<p class="Pp" id="bus_space_barrier~4">When a driver requires ordering, e.g. to + write to a command ring in bus space and then update the command ring + pointer, the + <a class="permalink" href="#bus_space_barrier~4"><code class="Fn">bus_space_barrier</code></a>() + function enforces it.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_barrier~5"><a class="permalink" href="#bus_space_barrier~5"><code class="Fn">bus_space_barrier</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">length</var>, <var class="Fa">flags</var>)</dt> + <dd> + <p class="Pp" id="bus_space_barrier~6">The + <a class="permalink" href="#bus_space_barrier~6"><code class="Fn">bus_space_barrier</code></a>() + function enforces ordering of bus space read and write operations for + the specified subregion (described by the <var class="Fa">offset</var> + and <var class="Fa">length</var> parameters) of the region named by + <var class="Fa">handle</var> in the space named by + <var class="Fa">space</var>.</p> + <p class="Pp">The <var class="Fa">flags</var> argument controls what types + of operations are to be ordered. Supported flags are:</p> + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt id="BUS_SPACE_BARRIER_READ"><a class="permalink" href="#BUS_SPACE_BARRIER_READ"><code class="Dv">BUS_SPACE_BARRIER_READ</code></a></dt> + <dd>Guarantee that any program-prior bus space read on + <i class="Em">any</i> bus space has returned data from the device or + memory before any program-later bus space read, bus space write, or + memory access via + <a class="permalink" href="#bus_space_vaddr~2"><code class="Fn" id="bus_space_vaddr~2">bus_space_vaddr</code></a>(), + on the specified range in the given bus space. + <p class="Pp">This functions similarly to + <a class="Xr">membar_acquire(3)</a>, but additionally orders bus + space I/O which <a class="Xr">membar_ops(3)</a> may not.</p> + </dd> + <dt id="BUS_SPACE_BARRIER_WRITE"><a class="permalink" href="#BUS_SPACE_BARRIER_WRITE"><code class="Dv">BUS_SPACE_BARRIER_WRITE</code></a></dt> + <dd>Guarantee that any program-prior bus space read, bus space write, or + memory access via + <a class="permalink" href="#bus_space_vaddr~3"><code class="Fn" id="bus_space_vaddr~3">bus_space_vaddr</code></a>(), + on the specified range in the given bus space, has completed before + any program-later bus space write on <i class="Em">any</i> bus space. + <p class="Pp">This functions similarly to + <a class="Xr">membar_release(3)</a>, but additionally orders bus + space I/O which <a class="Xr">membar_ops(3)</a> may not.</p> + </dd> + <dt id="BUS_SPACE_BARRIER_READ~2"><a class="permalink" href="#BUS_SPACE_BARRIER_READ~2"><code class="Dv">BUS_SPACE_BARRIER_READ</code></a> + | + <a class="permalink" href="#BUS_SPACE_BARRIER_WRITE~2"><code class="Dv" id="BUS_SPACE_BARRIER_WRITE~2">BUS_SPACE_BARRIER_WRITE</code></a></dt> + <dd>Guarantee that any program-prior bus space read, bus space write, or + memory access via + <a class="permalink" href="#bus_space_vaddr~4"><code class="Fn" id="bus_space_vaddr~4">bus_space_vaddr</code></a>() + on <i class="Em">any</i> bus space has completed before any + program-later bus space read, bus space write, or memory access via + <code class="Fn">bus_space_vaddr</code>() on <i class="Em">any</i> bus + space. + <p class="Pp">Note that this is independent of the specified bus space + and range.</p> + <p class="Pp">This functions similarly to + <a class="Xr">membar_sync(3)</a>, but additionally orders bus space + I/O which <a class="Xr">membar_ops(3)</a> may not. This combination + is very unusual, and often much more expensive; most drivers do not + need it.</p> + </dd> + </dl> + </div> + <p class="Pp">Example: Consider a command ring in bus space with a command + ring pointer register, and a response ring in bus space with a response + ring pointer register.</p> + <div class="Bd Pp Li"> + <pre>error = bus_space_map(sc->sc_regt, ..., 0, &sc->sc_regh); +if (error) + ... +error = bus_space_map(sc->sc_memt, ..., BUS_SPACE_MAP_PREFETCHABLE, + &sc->sc_memh); +if (error) + ...</pre> + </div> + <p class="Pp">To submit a command (assuming there is space in the ring), + first write it out and then update the pointer:</p> + <div class="Bd Pp Li"> + <pre>i = sc->sc_nextcmdslot; +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i), cmd); +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4, arg1); +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 8, arg2); +... +bus_space_write_4(sc->sc_memt, sc->sc_memh, CMDSLOT(i) + 4*n, argn); +bus_space_barrier(sc->sc_memt, sc->sc_memh, CMDSLOT(i), 4*n, + BUS_SPACE_BARRIER_WRITE); +bus_space_write_4(sc->sc_regt, sc->sc_regh, CMDPTR, i); +sc->sc_nextcmdslot = (i + n + 1) % sc->sc_ncmdslots;</pre> + </div> + <p class="Pp">To obtain a response, read the pointer first and then the ring + data:</p> + <div class="Bd Pp Li"> + <pre>ptr = bus_space_read_4(sc->sc_regt, sc->sc_regh, RESPPTR); +while ((i = sc->sc_nextrespslot) != ptr) { + bus_space_barrier(sc->sc_memt, sc->sc_memh, RESPSLOT(i), 4, + BUS_SPACE_BARRIER_READ); + status = bus_space_read_4(sc->sc_memt, sc->sc_memh, RESPSLOT(i)); + handle_response(status); + sc->sc_nextrespslot = (i + 1) % sc->sc_nrespslots; +}</pre> + </div> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="REGION_OPERATIONS"><a class="permalink" href="#REGION_OPERATIONS">REGION + OPERATIONS</a></h1> +<p class="Pp">Some devices use buffers which are mapped as regions in bus space. + Often, drivers want to copy the contents of those buffers to or from memory, + e.g., into mbufs which can be passed to higher levels of the system or from + mbufs to be output to a network. In order to allow drivers to do this as + efficiently as possible, the + <a class="permalink" href="#bus_space_read_region_N"><code class="Fn" id="bus_space_read_region_N">bus_space_read_region_N</code></a>() + and <code class="Fn">bus_space_write_region_N</code>() families of functions + are provided.</p> +<p class="Pp" id="bus_space_copy_region_N">Drivers occasionally need to copy one + region of a bus space to another, or to set all locations in a region of bus + space to contain a single value. The + <a class="permalink" href="#bus_space_copy_region_N"><code class="Fn">bus_space_copy_region_N</code></a>() + family of functions and the <code class="Fn">bus_space_set_region_N</code>() + family of functions allow drivers to perform these operations.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_read_region_1"><a class="permalink" href="#bus_space_read_region_1"><code class="Fn">bus_space_read_region_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_region_2"><a class="permalink" href="#bus_space_read_region_2"><code class="Fn">bus_space_read_region_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_region_4"><a class="permalink" href="#bus_space_read_region_4"><code class="Fn">bus_space_read_region_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_region_8"><a class="permalink" href="#bus_space_read_region_8"><code class="Fn">bus_space_read_region_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd> + <p class="Pp" id="bus_space_read_region_N~2">The + <a class="permalink" href="#bus_space_read_region_N~2"><code class="Fn">bus_space_read_region_N</code></a>() + family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte + data items from bus space starting at byte offset + <var class="Fa">offset</var> in the region specified by + <var class="Fa">handle</var> of the bus space specified by + <var class="Fa">space</var> and writes them into the array specified by + <var class="Fa">datap</var>. Each successive data item is read from an + offset 1, 2, 4, or 8 bytes after the previous data item (depending on + which function is used). All locations being read must lie within the + bus space region specified by <var class="Fa">handle</var>.</p> + <p class="Pp">For portability, the starting address of the region specified + by <var class="Fa">handle</var> plus the offset should be a multiple of + the size of data items being read and the data array pointer should be + properly aligned. On some systems, not obeying these requirements may + cause incorrect data to be read, on others it may cause a system + crash.</p> + <p class="Pp" id="bus_space_read_region_N~3">Read operations done by the + <a class="permalink" href="#bus_space_read_region_N~3"><code class="Fn">bus_space_read_region_N</code></a>() + functions may be executed in any order. They may also be executed out of + order with respect to other read and write operations if either are on + prefetchable or cacheable mappings unless order is enforced by use of + the <code class="Fn">bus_space_barrier</code>() function. There is no + way to insert barriers between reads of individual bus space locations + executed by the <code class="Fn">bus_space_read_region_N</code>() + functions.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_write_region_1"><a class="permalink" href="#bus_space_write_region_1"><code class="Fn">bus_space_write_region_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_region_2"><a class="permalink" href="#bus_space_write_region_2"><code class="Fn">bus_space_write_region_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_region_4"><a class="permalink" href="#bus_space_write_region_4"><code class="Fn">bus_space_write_region_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_region_8"><a class="permalink" href="#bus_space_write_region_8"><code class="Fn">bus_space_write_region_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd> + <p class="Pp" id="bus_space_write_region_N">The + <a class="permalink" href="#bus_space_write_region_N"><code class="Fn">bus_space_write_region_N</code></a>() + family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte + data items from the array specified by <var class="Fa">datap</var> and + writes them to bus space starting at byte offset + <var class="Fa">offset</var> in the region specified by + <var class="Fa">handle</var> of the bus space specified by + <var class="Fa">space</var>. Each successive data item is written to an + offset 1, 2, 4, or 8 bytes after the previous data item (depending on + which function is used). All locations being written must lie within the + bus space region specified by <var class="Fa">handle</var>.</p> + <p class="Pp">For portability, the starting address of the region specified + by <var class="Fa">handle</var> plus the offset should be a multiple of + the size of data items being written and the data array pointer should + be properly aligned. On some systems, not obeying these requirements may + cause incorrect data to be written, on others it may cause a system + crash.</p> + <p class="Pp" id="bus_space_write_region_N~2">Write operations done by the + <a class="permalink" href="#bus_space_write_region_N~2"><code class="Fn">bus_space_write_region_N</code></a>() + functions may be executed in any order. They may also be executed out of + order with respect to other read and write operations if either are on + prefetchable or cacheable mappings unless order is enforced by use of + the <code class="Fn">bus_space_barrier</code>() function. There is no + way to insert barriers between writes of individual bus space locations + executed by the <code class="Fn">bus_space_write_region_N</code>() + functions.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_copy_region_1"><a class="permalink" href="#bus_space_copy_region_1"><code class="Fn">bus_space_copy_region_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, + <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, + <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_copy_region_2"><a class="permalink" href="#bus_space_copy_region_2"><code class="Fn">bus_space_copy_region_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, + <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, + <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_copy_region_4"><a class="permalink" href="#bus_space_copy_region_4"><code class="Fn">bus_space_copy_region_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, + <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, + <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_copy_region_8"><a class="permalink" href="#bus_space_copy_region_8"><code class="Fn">bus_space_copy_region_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">srchandle</var>, <var class="Fa">srcoffset</var>, + <var class="Fa">dsthandle</var>, <var class="Fa">dstoffset</var>, + <var class="Fa">count</var>)</dt> + <dd> + <p class="Pp" id="bus_space_copy_region_N~2">The + <a class="permalink" href="#bus_space_copy_region_N~2"><code class="Fn">bus_space_copy_region_N</code></a>() + family of functions copies <var class="Fa">count</var> 1, 2, 4, or 8 + byte data items in bus space from the area starting at byte offset + <var class="Fa">srcoffset</var> in the region specified by + <var class="Fa">srchandle</var> of the bus space specified by + <var class="Fa">space</var> to the area starting at byte offset + <var class="Fa">dstoffset</var> in the region specified by + <var class="Fa">dsthandle</var> in the same bus space. Each successive + data item read or written has an offset 1, 2, 4, or 8 bytes after the + previous data item (depending on which function is used). All locations + being read and written must lie within the bus space region specified by + their respective handles.</p> + <p class="Pp">For portability, the starting addresses of the regions + specified by each handle plus its respective offset should be a multiple + of the size of data items being copied. On some systems, not obeying + this requirement may cause incorrect data to be copied, on others it may + cause a system crash.</p> + <p class="Pp" id="bus_space_copy_region_N~3">Read and write operations done + by the + <a class="permalink" href="#bus_space_copy_region_N~3"><code class="Fn">bus_space_copy_region_N</code></a>() + functions may be executed in any order. They may also be executed out of + order with respect to other read and write operations if either are on + prefetchable or cacheable mappings unless order is enforced by use of + the <code class="Fn">bus_space_barrier</code>() function. There is no + way to insert barriers between reads or writes of individual bus space + locations executed by the + <code class="Fn">bus_space_copy_region_N</code>() functions.</p> + <p class="Pp" id="bus_space_copy_region_N~4">Overlapping copies between + different subregions of a single region of bus space are handled + correctly by the + <a class="permalink" href="#bus_space_copy_region_N~4"><code class="Fn">bus_space_copy_region_N</code></a>() + functions.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_set_region_1"><a class="permalink" href="#bus_space_set_region_1"><code class="Fn">bus_space_set_region_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_set_region_2"><a class="permalink" href="#bus_space_set_region_2"><code class="Fn">bus_space_set_region_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_set_region_4"><a class="permalink" href="#bus_space_set_region_4"><code class="Fn">bus_space_set_region_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_set_region_8"><a class="permalink" href="#bus_space_set_region_8"><code class="Fn">bus_space_set_region_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>, <var class="Fa">count</var>)</dt> + <dd> + <p class="Pp" id="bus_space_set_region_N">The + <a class="permalink" href="#bus_space_set_region_N"><code class="Fn">bus_space_set_region_N</code></a>() + family of functions writes the given <var class="Fa">value</var> to + <var class="Fa">count</var> 1, 2, 4, or 8 byte data items in bus space + starting at byte offset <var class="Fa">offset</var> in the region + specified by <var class="Fa">handle</var> of the bus space specified by + <var class="Fa">space</var>. Each successive data item has an offset 1, + 2, 4, or 8 bytes after the previous data item (depending on which + function is used). All locations being written must lie within the bus + space region specified by <var class="Fa">handle</var>.</p> + <p class="Pp">For portability, the starting address of the region specified + by <var class="Fa">handle</var> plus the offset should be a multiple of + the size of data items being written. On some systems, not obeying this + requirement may cause incorrect data to be written, on others it may + cause a system crash.</p> + <p class="Pp" id="bus_space_set_region_N~2">Write operations done by the + <a class="permalink" href="#bus_space_set_region_N~2"><code class="Fn">bus_space_set_region_N</code></a>() + functions may be executed in any order. They may also be executed out of + order with respect to other read and write operations if either are on + prefetchable or cacheable mappings unless order is enforced by use of + the <code class="Fn">bus_space_barrier</code>() function. There is no + way to insert barriers between writes of individual bus space locations + executed by the <code class="Fn">bus_space_set_region_N</code>() + functions.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="READING_AND_WRITING_A_SINGLE_LOCATION_MULTIPLE_TIMES"><a class="permalink" href="#READING_AND_WRITING_A_SINGLE_LOCATION_MULTIPLE_TIMES">READING + AND WRITING A SINGLE LOCATION MULTIPLE TIMES</a></h1> +<p class="Pp">Some devices implement single locations in bus space which are to + be read or written multiple times to communicate data, e.g., some ethernet + devices' packet buffer FIFOs. In order to allow drivers to manipulate these + types of devices as efficiently as possible, the + <a class="permalink" href="#bus_space_read_multi_N"><code class="Fn" id="bus_space_read_multi_N">bus_space_read_multi_N</code></a>() + and <code class="Fn">bus_space_write_multi_N</code>() families of functions + are provided.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_read_multi_1"><a class="permalink" href="#bus_space_read_multi_1"><code class="Fn">bus_space_read_multi_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_multi_2"><a class="permalink" href="#bus_space_read_multi_2"><code class="Fn">bus_space_read_multi_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_multi_4"><a class="permalink" href="#bus_space_read_multi_4"><code class="Fn">bus_space_read_multi_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_multi_8"><a class="permalink" href="#bus_space_read_multi_8"><code class="Fn">bus_space_read_multi_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd> + <p class="Pp" id="bus_space_read_multi_N~2">The + <a class="permalink" href="#bus_space_read_multi_N~2"><code class="Fn">bus_space_read_multi_N</code></a>() + family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte + data items from bus space at byte offset <var class="Fa">offset</var> in + the region specified by <var class="Fa">handle</var> of the bus space + specified by <var class="Fa">space</var> and writes them into the array + specified by <var class="Fa">datap</var>. Each successive data item is + read from the same location in bus space. The location being read must + lie within the bus space region specified by + <var class="Fa">handle</var>.</p> + <p class="Pp">For portability, the starting address of the region specified + by <var class="Fa">handle</var> plus the offset should be a multiple of + the size of data items being read and the data array pointer should be + properly aligned. On some systems, not obeying these requirements may + cause incorrect data to be read, on others it may cause a system + crash.</p> + <p class="Pp" id="bus_space_read_multi_N~3">Read operations done by the + <a class="permalink" href="#bus_space_read_multi_N~3"><code class="Fn">bus_space_read_multi_N</code></a>() + functions may be executed out of order with respect to other read and + write operations if the latter are on prefetchable or cacheable mappings + unless order is enforced by use of the + <code class="Fn">bus_space_barrier</code>() function. + <code class="Fn">bus_space_read_multi_N</code>() makes no sense itself + on prefetchable or cacheable mappings.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + <p class="Pp"></p> + </dd> + <dt id="bus_space_write_multi_1"><a class="permalink" href="#bus_space_write_multi_1"><code class="Fn">bus_space_write_multi_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_multi_2"><a class="permalink" href="#bus_space_write_multi_2"><code class="Fn">bus_space_write_multi_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_multi_4"><a class="permalink" href="#bus_space_write_multi_4"><code class="Fn">bus_space_write_multi_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_multi_8"><a class="permalink" href="#bus_space_write_multi_8"><code class="Fn">bus_space_write_multi_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd> + <p class="Pp" id="bus_space_write_multi_N">The + <a class="permalink" href="#bus_space_write_multi_N"><code class="Fn">bus_space_write_multi_N</code></a>() + family of functions reads <var class="Fa">count</var> 1, 2, 4, or 8 byte + data items from the array specified by <var class="Fa">datap</var> and + writes them into bus space at byte offset <var class="Fa">offset</var> + in the region specified by <var class="Fa">handle</var> of the bus space + specified by <var class="Fa">space</var>. Each successive data item is + written to the same location in bus space. The location being written + must lie within the bus space region specified by + <var class="Fa">handle</var>.</p> + <p class="Pp">For portability, the starting address of the region specified + by <var class="Fa">handle</var> plus the offset should be a multiple of + the size of data items being written and the data array pointer should + be properly aligned. On some systems, not obeying these requirements may + cause incorrect data to be written, on others it may cause a system + crash.</p> + <p class="Pp" id="bus_space_write_multi_N~2">Write operations done by the + <a class="permalink" href="#bus_space_write_multi_N~2"><code class="Fn">bus_space_write_multi_N</code></a>() + functions may be executed out of order with respect to other read and + write operations if the latter are on prefetchable or cacheable mappings + unless order is enforced by use of the + <code class="Fn">bus_space_barrier</code>() function. + <code class="Fn">bus_space_write_multi_N</code>() makes no sense itself + on prefetchable or cacheable mappings.</p> + <p class="Pp">These functions will never fail. If they would fail (e.g., + because of an argument error), that indicates a software bug which + should cause a panic. In that case, they will never return.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="STREAM_FUNCTIONS"><a class="permalink" href="#STREAM_FUNCTIONS">STREAM + FUNCTIONS</a></h1> +<p class="Pp">Most of the <code class="Nm">bus_space</code> functions imply a + host byte-order and a bus byte-order and take care of any translation for + the caller. In some cases, however, hardware may map a FIFO or some other + memory region for which the caller may want to use multi-word, yet + untranslated access. Access to these types of memory regions should be with + the + <a class="permalink" href="#bus_space_*_stream_N"><code class="Fn" id="bus_space_*_stream_N">bus_space_*_stream_N</code></a>() + functions.</p> +<p class="Pp"></p> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_read_stream_1"><a class="permalink" href="#bus_space_read_stream_1"><code class="Fn">bus_space_read_stream_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd></dd> + <dt id="bus_space_read_stream_2"><a class="permalink" href="#bus_space_read_stream_2"><code class="Fn">bus_space_read_stream_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd></dd> + <dt id="bus_space_read_stream_4"><a class="permalink" href="#bus_space_read_stream_4"><code class="Fn">bus_space_read_stream_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd></dd> + <dt id="bus_space_read_stream_8"><a class="permalink" href="#bus_space_read_stream_8"><code class="Fn">bus_space_read_stream_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>)</dt> + <dd></dd> + <dt id="bus_space_read_multi_stream_1"><a class="permalink" href="#bus_space_read_multi_stream_1"><code class="Fn">bus_space_read_multi_stream_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_multi_stream_2"><a class="permalink" href="#bus_space_read_multi_stream_2"><code class="Fn">bus_space_read_multi_stream_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_multi_stream_4"><a class="permalink" href="#bus_space_read_multi_stream_4"><code class="Fn">bus_space_read_multi_stream_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_multi_stream_8"><a class="permalink" href="#bus_space_read_multi_stream_8"><code class="Fn">bus_space_read_multi_stream_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_region_stream_1"><a class="permalink" href="#bus_space_read_region_stream_1"><code class="Fn">bus_space_read_region_stream_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_region_stream_2"><a class="permalink" href="#bus_space_read_region_stream_2"><code class="Fn">bus_space_read_region_stream_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_region_stream_4"><a class="permalink" href="#bus_space_read_region_stream_4"><code class="Fn">bus_space_read_region_stream_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_read_region_stream_8"><a class="permalink" href="#bus_space_read_region_stream_8"><code class="Fn">bus_space_read_region_stream_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_stream_1"><a class="permalink" href="#bus_space_write_stream_1"><code class="Fn">bus_space_write_stream_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_write_stream_2"><a class="permalink" href="#bus_space_write_stream_2"><code class="Fn">bus_space_write_stream_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_write_stream_4"><a class="permalink" href="#bus_space_write_stream_4"><code class="Fn">bus_space_write_stream_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_write_stream_8"><a class="permalink" href="#bus_space_write_stream_8"><code class="Fn">bus_space_write_stream_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">value</var>)</dt> + <dd></dd> + <dt id="bus_space_write_multi_stream_1"><a class="permalink" href="#bus_space_write_multi_stream_1"><code class="Fn">bus_space_write_multi_stream_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_multi_stream_2"><a class="permalink" href="#bus_space_write_multi_stream_2"><code class="Fn">bus_space_write_multi_stream_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_multi_stream_4"><a class="permalink" href="#bus_space_write_multi_stream_4"><code class="Fn">bus_space_write_multi_stream_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_multi_stream_8"><a class="permalink" href="#bus_space_write_multi_stream_8"><code class="Fn">bus_space_write_multi_stream_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_region_stream_1"><a class="permalink" href="#bus_space_write_region_stream_1"><code class="Fn">bus_space_write_region_stream_1</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_region_stream_2"><a class="permalink" href="#bus_space_write_region_stream_2"><code class="Fn">bus_space_write_region_stream_2</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_region_stream_4"><a class="permalink" href="#bus_space_write_region_stream_4"><code class="Fn">bus_space_write_region_stream_4</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> + <dt id="bus_space_write_region_stream_8"><a class="permalink" href="#bus_space_write_region_stream_8"><code class="Fn">bus_space_write_region_stream_8</code></a>(<var class="Fa">space</var>, + <var class="Fa">handle</var>, <var class="Fa">offset</var>, + <var class="Fa">datap</var>, <var class="Fa">count</var>)</dt> + <dd></dd> +</dl> +<p class="Pp">These functions are defined just as their non-stream counterparts, + except that they provide no byte-order translation.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="IMPLEMENTING_BUS_SPACES_IN_MACHINE-INDEPENDENT_CODE"><a class="permalink" href="#IMPLEMENTING_BUS_SPACES_IN_MACHINE-INDEPENDENT_CODE">IMPLEMENTING + BUS SPACES IN MACHINE-INDEPENDENT CODE</a></h1> +<dl class="Bl-ohang Bl-compact"> + <dt id="bus_space_tag_create"><a class="permalink" href="#bus_space_tag_create"><code class="Fn">bus_space_tag_create</code></a>(<var class="Fa">obst</var>, + <var class="Fa">present</var>, <var class="Fa">extpresent</var>, + <var class="Fa">ov</var>, <var class="Fa">ctx</var>, + <var class="Fa">bstp</var>)</dt> + <dd>Create a copy of the tag <var class="Fa">obst</var> at + <var class="Fa">*bstp</var>. Except for the behavior overridden by + <var class="Fa">ov</var>, <var class="Fa">*bstp</var> inherits the + behavior of <var class="Fa">obst</var> under + <code class="Nm">bus_space</code> calls. + <p class="Pp"><var class="Fa">ov</var> contains function pointers + corresponding to <code class="Nm">bus_space</code> routines. Each + function pointer has a corresponding bit in + <var class="Fa">present</var> or <var class="Fa">extpresent</var>, and + if that bit is 1, the function pointer overrides the corresponding + <code class="Nm">bus_space</code> call for the new tag. Any combination + of these bits may be set in <var class="Fa">present</var>:</p> + <p class="Pp"></p> + <dl class="Bl-tag Bl-compact"> + <dt id="BUS_SPACE_OVERRIDE_MAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_MAP"><code class="Dv">BUS_SPACE_OVERRIDE_MAP</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_UNMAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_UNMAP"><code class="Dv">BUS_SPACE_OVERRIDE_UNMAP</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_ALLOC"><a class="permalink" href="#BUS_SPACE_OVERRIDE_ALLOC"><code class="Dv">BUS_SPACE_OVERRIDE_ALLOC</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_FREE"><a class="permalink" href="#BUS_SPACE_OVERRIDE_FREE"><code class="Dv">BUS_SPACE_OVERRIDE_FREE</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_RESERVE"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVE"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVE</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_RELEASE"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RELEASE"><code class="Dv">BUS_SPACE_OVERRIDE_RELEASE</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_RESERVATION_MAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVATION_MAP"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVATION_MAP</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_RESERVATION_UNMAP"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVATION_UNMAP"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVATION_UNMAP</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="BUS_SPACE_OVERRIDE_RESERVE_SUBREGION"><a class="permalink" href="#BUS_SPACE_OVERRIDE_RESERVE_SUBREGION"><code class="Dv">BUS_SPACE_OVERRIDE_RESERVE_SUBREGION</code></a></dt> + <dd style="width: auto;"> </dd> + </dl> + <p class="Pp" id="bus_space_tag_create~2"><a class="permalink" href="#bus_space_tag_create~2"><code class="Fn">bus_space_tag_create</code></a>() + does not copy <var class="Fa">ov</var>. After a new tag is created by + <code class="Fn">bus_space_tag_create</code>(), <var class="Fa">ov</var> + must not be destroyed until after the tag is destroyed by + <code class="Fn">bus_space_tag_destroy</code>().</p> + <p class="Pp">The first argument of every override-function is a + <var class="Vt">void *</var>, and <var class="Fa">ctx</var> is passed in + that argument.</p> + <p class="Pp">Return 0 if the call succeeds. Return + <code class="Er">EOPNOTSUPP</code> if the architecture does not support + overrides. Return <code class="Er">EINVAL</code> if + <var class="Fa">present</var> is 0, if <var class="Fa">ov</var> is + <code class="Dv">NULL</code>, or if <var class="Fa">present</var> + indicates that an override is present, but the corresponding override in + <var class="Fa">ov</var> is <code class="Dv">NULL</code>.</p> + <p class="Pp">If the call does not succeed, <var class="Fa">*bstp</var> is + undefined.</p> + </dd> + <dt id="bus_space_tag_destroy"><a class="permalink" href="#bus_space_tag_destroy"><code class="Fn">bus_space_tag_destroy</code></a>(<var class="Fa">bst</var>)</dt> + <dd>Destroy a tag, <var class="Fa">bst</var>, created by a prior call to + <code class="Fn">bus_space_tag_create</code>(). If + <var class="Fa">bst</var> was not created by + <code class="Fn">bus_space_tag_create</code>(), results are undefined. If + <var class="Fa">bst</var> was already destroyed, results are + undefined.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXPECTED_CHANGES_TO_THE_BUS_SPACE_FUNCTIONS"><a class="permalink" href="#EXPECTED_CHANGES_TO_THE_BUS_SPACE_FUNCTIONS">EXPECTED + CHANGES TO THE BUS_SPACE FUNCTIONS</a></h1> +<p class="Pp">The definition of the <code class="Nm">bus_space</code> functions + should not yet be considered finalized. There are several changes and + improvements which should be explored, including:</p> +<ul class="Bl-bullet"> + <li>Exporting the <code class="Nm">bus_space</code> functions to userland so + that applications (such as X servers) have easier, more portable access to + device space.</li> + <li>Redefining bus space tags and handles so that machine-independent bus + interface drivers (for example PCI to VME bridges) could define and + implement bus spaces without requiring machine-dependent code. If this is + done, it should be done in such a way that machine-dependent optimizations + should remain possible.</li> + <li>Converting bus spaces (such as PCI configuration space) which currently + use space-specific access methods to use the + <code class="Nm">bus_space</code> functions where that is + appropriate.</li> + <li>Redefining the way bus space is mapped and allocated, so that mapping and + allocation are done with bus specific functions which return bus space + tags. This would allow further optimization than is currently possible, + and would also ease translation of the <code class="Nm">bus_space</code> + functions into user space (since mapping in user space would look like it + just used a different bus-specific mapping function).</li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="COMPATIBILITY"><a class="permalink" href="#COMPATIBILITY">COMPATIBILITY</a></h1> +<p class="Pp">The current version of the <code class="Nm">bus_space</code> + interface specification differs slightly from the original specification + that came into wide use. A few of the function names and arguments have + changed for consistency and increased functionality. Drivers that were + written to the old, deprecated specification can be compiled by defining the + <code class="Dv">__BUS_SPACE_COMPAT_OLDDEFS</code> preprocessor symbol + before including + <code class="In"><<a class="In">sys/bus.h</a>></code>.</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">membar_ops(3)</a>, <a class="Xr">bus_dma(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">bus_space</code> functions were introduced in + a different form (memory and I/O spaces were accessed via different sets of + functions) in <span class="Ux">NetBSD 1.2</span>. The functions were merged + to work on generic “spaces” early in the + <span class="Ux">NetBSD 1.3</span> development cycle, and many drivers were + converted to use them. This document was written later during the + <span class="Ux">NetBSD 1.3</span> development cycle and the specification + was updated to fix some consistency problems and to add some missing + functionality.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">bus_space</code> interfaces were designed and + implemented by the <span class="Ux">NetBSD</span> developer community. + Primary contributors and implementors were <span class="An">Chris + Demetriou</span>, <span class="An">Jason Thorpe</span>, and + <span class="An">Charles Hannum</span>, but the rest of the + <span class="Ux">NetBSD</span> developers and the user community played a + significant role in development.</p> +<p class="Pp"><span class="An">Chris Demetriou</span> wrote this manual + page.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 12, 2022</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/clock.9 3.html b/static/netbsd/man9/clock.9 3.html new file mode 100644 index 00000000..5bf14a78 --- /dev/null +++ b/static/netbsd/man9/clock.9 3.html @@ -0,0 +1,103 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CLOCK(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CLOCK(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">days_in_month</code>, + <code class="Nm">is_leap_year</code>, <code class="Nm">days_per_year</code> + — <span class="Nd">handy time utilities</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/clock.h</a>></code></p> +<p class="Pp"><var class="Vt">#define SECS_PER_MINUTE 60</var> + <br/> + <var class="Vt">#define SECS_PER_HOUR 3600</var> + <br/> + <var class="Vt">#define SECS_PER_DAY 86400</var> + <br/> + <var class="Vt">#define DAYS_PER_COMMON_YEAR 365</var> + <br/> + <var class="Vt">#define DAYS_PER_LEAP_YEAR 366</var> + <br/> + <var class="Vt">#define SECS_PER_COMMON_YEAR (SECS_PER_DAY * + DAYS_PER_COMMON_YEAR)</var> + <br/> + <var class="Vt">#define SECS_PER_LEAP_YEAR (SECS_PER_DAY * + DAYS_PER_LEAP_YEAR)</var></p> +<p class="Pp"><var class="Ft">static inline int</var> + <br/> + <code class="Fn">days_in_month</code>(<var class="Fa" style="white-space: nowrap;">int + m</var>);</p> +<p class="Pp"><var class="Ft">static inline int</var> + <br/> + <code class="Fn">is_leap_year</code>(<var class="Fa" style="white-space: nowrap;">uint64_t + year</var>);</p> +<p class="Pp"><var class="Ft">static inline int</var> + <br/> + <code class="Fn">days_per_year</code>(<var class="Fa" style="white-space: nowrap;">uint64_t + year</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="In"><<a class="In">sys/clock.h</a>></code> + file provides handy time constants and <var class="Ft">static inline</var> + functions.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<p class="Pp">The + <a class="permalink" href="#days_in_month"><code class="Fn" id="days_in_month">days_in_month</code></a>() + function returns the number of days in the given month. + <code class="Fn">days_in_month</code>() assumes 28 days for February. If the + input value is out of the valid range (1-12) then the function returns + -1.</p> +<p class="Pp" id="is_leap_year">The + <a class="permalink" href="#is_leap_year"><code class="Fn">is_leap_year</code></a>() + and + <a class="permalink" href="#days_per_year"><code class="Fn" id="days_per_year">days_per_year</code></a>() + functions take as the input parameter a value in the Gregorian year + format.</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">bintime(9)</a>, <a class="Xr">boottime(9)</a>, + <a class="Xr">time_second(9)</a>, <a class="Xr">time_uptime(9)</a>, + <a class="Xr">todr_gettime(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="In"><<a class="In">sys/clock.h</a>></code> + header with handy utilities originated from + <code class="In"><<a class="In">dev/clock_subr.h</a>></code>, which + originated from + <code class="In"><<a class="In">arch/hp300/hp300/clock.c</a>></code>.</p> +<p class="Pp">The + <code class="In"><<a class="In">arch/hp300/hp300/clock.c</a>></code> + file first appeared in <span class="Ux">NetBSD 0.8</span> as a set of hp300 + time-converting functions. + <code class="In"><<a class="In">dev/clock_subr.h</a>></code> first + appeared in <span class="Ux">NetBSD 1.3</span> as a shared list of functions + to convert between “year/month/day/hour/minute/second” and + seconds since 1970 (“POSIX time”). The + <code class="In"><<a class="In">sys/clock.h</a>></code> file first + appeared in <span class="Ux">NetBSD 8</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Kamil Rytarowski</span></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 26, 2014</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cnmagic.9 3.html b/static/netbsd/man9/cnmagic.9 3.html new file mode 100644 index 00000000..ea61d72b --- /dev/null +++ b/static/netbsd/man9/cnmagic.9 3.html @@ -0,0 +1,164 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CNMAGIC(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CNMAGIC(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">cn_init_magic</code>, + <code class="Nm">cn_trap</code>, <code class="Nm">cn_isconsole</code>, + <code class="Nm">cn_check_magic</code>, + <code class="Nm">cn_destroy_magic</code>, + <code class="Nm">cn_set_magic</code>, <code class="Nm">cn_get_magic</code> + — <span class="Nd">console magic key sequence management</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cn_init_magic</code>(<var class="Fa" style="white-space: nowrap;">cnm_state_t + *cnms</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cn_trap</code>();</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cn_isconsole</code>(<var class="Fa" style="white-space: nowrap;">dev_t + dev</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cn_check_magic</code>(<var class="Fa" style="white-space: nowrap;">dev_t + dev</var>, <var class="Fa" style="white-space: nowrap;">int k</var>, + <var class="Fa" style="white-space: nowrap;">cnm_state_t *cnms</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cn_destroy_magic</code>(<var class="Fa" style="white-space: nowrap;">cnm_state_t + *cnms</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cn_set_magic</code>(<var class="Fa" style="white-space: nowrap;">char + *magic</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cn_get_magic</code>(<var class="Fa" style="white-space: nowrap;">char + *magic</var>, <var class="Fa" style="white-space: nowrap;">int + len</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <span class="Ux">NetBSD</span> console magic key sequence + management framework is designed to provide flexible methods to set, change, + and detect magic key sequences on console devices and break into the + debugger or ROM monitor with a minimum of interrupt latency.</p> +<p class="Pp" id="cn_init_magic">Drivers that generate console input should make + use of these routines. A different <var class="Va">cnm_state_t</var> should + be used for each separate input stream. Multiple devices that share the same + input stream, such as USB keyboards, can share the same + <var class="Va">cnm_state_t</var>. Once a <var class="Va">cnm_state_t</var> + is allocated, it should be initialized with + <a class="permalink" href="#cn_init_magic"><code class="Fn">cn_init_magic</code></a>() + so it can be used by + <a class="permalink" href="#cn_check_magic"><code class="Fn" id="cn_check_magic">cn_check_magic</code></a>(). + If a driver thinks it might be the console input device it can set the magic + sequence with <code class="Fn">cn_set_magic</code>() to any arbitrary + string. Whenever the driver receives input, it should call + <code class="Fn">cn_check_magic</code>() to process the data and determine + whether the magic sequence has been hit.</p> +<p class="Pp">The magic key sequence can be accessed through the + <var class="Va">hw.cnmagic</var> <code class="Ic">sysctl</code> variable. + This is the raw data and may be keycodes rather than processed characters, + depending on the console device.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<p class="Pp">The following functions describe the console magic interface.</p> +<dl class="Bl-tag"> + <dt id="cn_init_magic~2"><a class="permalink" href="#cn_init_magic~2"><code class="Fn">cn_init_magic</code></a>(<var class="Fa">cnm</var>)</dt> + <dd>Initialize the console magic state pointed to by <var class="Fa">cnm</var> + to a usable state.</dd> + <dt id="cn_trap"><a class="permalink" href="#cn_trap"><code class="Fn">cn_trap</code></a>()</dt> + <dd>Trap into the kernel debugger or ROM monitor. By default this routine is + defined to be + <a class="permalink" href="#console_debugger"><code class="Fn" id="console_debugger">console_debugger</code></a>() + but can be overridden in MI header files.</dd> + <dt id="cn_isconsole"><a class="permalink" href="#cn_isconsole"><code class="Fn">cn_isconsole</code></a>(<var class="Fa">dev</var>)</dt> + <dd>Determine whether a given <var class="Fa">dev</var> is the system console. + This macro tests to see if <var class="Fa">dev</var> is the same as + <var class="Va">cn_tab->cn_dev</var> but can be overridden in MI header + files.</dd> + <dt><code class="Fn">cn_check_magic</code>(<var class="Fa">dev</var>, + <var class="Fa">k</var>, <var class="Fa">cnms</var>)</dt> + <dd>All input should be passed through + <code class="Fn">cn_check_magic</code>() so the state machine remains in a + consistent state. <code class="Fn">cn_check_magic</code>() calls + <code class="Fn">cn_isconsole</code>() with <var class="Fa">dev</var> to + determine if this is the console. If that returns true then it runs the + input value <var class="Fa">k</var> through the state machine. If the + state machine completes a match of the current console magic sequence + <code class="Fn">cn_trap</code>() is called. Some input may need to be + translated to state machine values such as the serial line + <code class="Li">BREAK</code> sequence.</dd> + <dt id="cn_destroy_magic"><a class="permalink" href="#cn_destroy_magic"><code class="Fn">cn_destroy_magic</code></a>(<var class="Fa">cnms</var>)</dt> + <dd>This should be called once what <var class="Fa">cnms</var> points to is no + longer needed.</dd> + <dt><code class="Fn">cn_set_magic</code>(<var class="Fa">magic</var>)</dt> + <dd><code class="Fn">cn_set_magic</code>() encodes a + <code class="Li">nul</code> terminated arbitrary string into values that + can be used by the state machine and installs it as the global magic + sequence. The escape sequence is character value + <code class="Li">0x27</code> and can be used to encode special values: + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt>0x27</dt> + <dd>The literal value <code class="Li">0x27</code>.</dd> + <dt>0x01</dt> + <dd>Serial <code class="Li">BREAK</code> sequence.</dd> + <dt id="Nul">0x02</dt> + <dd><a class="permalink" href="#Nul"><code class="Li">Nul</code></a> + character.</dd> + </dl> + </div> + <p class="Pp">Returns <code class="Li">0</code> on success or a non-zero + error value.</p> + </dd> + <dt id="cn_get_magic"><a class="permalink" href="#cn_get_magic"><code class="Fn">cn_get_magic</code></a>(<var class="Fa">magic</var>, + <var class="Fa">len</var>)</dt> + <dd>Extract the current magic sequence from the state machine and return up to + <var class="Fa">len</var> bytes of it in the buffer pointed to by + <var class="Fa">magic</var>. It uses the same encoding accepted by + <a class="permalink" href="#cn_set_magic"><code class="Fn" id="cn_set_magic">cn_set_magic</code></a>(). + Returns <code class="Li">0</code> on success or a non-zero error + value.</dd> +</dl> +</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">ddb(4)</a>, <a class="Xr">sysctl(8)</a>, + <a class="Xr">cons(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <span class="Ux">NetBSD</span> console magic key sequence + management framework first appeared in <span class="Ux">NetBSD + 1.6</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <span class="Ux">NetBSD</span> console magic key sequence + management framework was designed and implemented by + <span class="An">Eduardo Horvath</span> ⟨eeh@NetBSD.org⟩.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 7, 2019</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cnv.9 b/static/netbsd/man9/cnv.9 new file mode 100644 index 00000000..90ca9339 --- /dev/null +++ b/static/netbsd/man9/cnv.9 @@ -0,0 +1,215 @@ +.\" $NetBSD: cnv.9,v 1.2 2018/09/08 14:02:15 christos Exp $ +.\" +.\" Copyright (c) 2016 Adam Starak <starak.adam@gmail.com> +.\" 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: head/share/man/man9/cnv.9 335343 2018-06-18 21:26:58Z oshogbo $ +.\" +.Dd June 18, 2018 +.Dt CNV 9 +.Os +.Sh NAME +.Nm cnvlist_get , +.Nm cnvlist_take , +.Nm cnvlist_free +.Nd "API for managing name/value pairs by cookie." +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/cnv.h +.Ft const char * +.Fn cnvlist_name "const void *cookie" +.Ft int +.Fn cnvlist_type "const void *cookie" +.\" +.Ft bool +.Fn cnvlist_get_bool "const void *cookie" +.Ft uint64_t +.Fn cnvlist_get_number "const void *cookie" +.Ft "const char *" +.Fn cnvlist_get_string "const void *cookie" +.Ft "const nvlist_t *" +.Fn cnvlist_get_nvlist "const void *cookie" +.Ft "const void *" +.Fn cnvlist_get_binary "const void *cookie" "size_t *sizep" +.Ft "const bool *" +.Fn cnvlist_get_bool_array "const void *cookie" "size_t *nitemsp" +.Ft "const uint64_t *" +.Fn cnvlist_get_number_array "const void *cookie" "size_t *nitemsp" +.Ft "const char * const *" +.Fn cnvlist_get_string_array "const void *cookie" "size_t *nitemsp" +.Ft "const nvlist_t * const *" +.Fn cnvlist_get_nvlist_array "const void *cookie" "size_t *nitemsp" +.Ft int +.Fn cnvlist_get_descriptor "const void *cookie" +.Ft "const int *" +.Fn cnvlist_get_descriptor_array "const void *cookie" "size_t *nitemsp" +.\" +.Ft bool +.Fn cnvlist_take_bool "void *cookie" +.Ft uint64_t +.Fn cnvlist_take_number "void *cookie" +.Ft "const char *" +.Fn cnvlist_take_string "void *cookie" +.Ft "const nvlist_t *" +.Fn cnvlist_take_nvlist "void *cookie" +.Ft "const void *" +.Fn cnvlist_take_binary "void *cookie" "size_t *sizep" +.Ft "const bool *" +.Fn cnvlist_take_bool_array "void *cookie" "size_t *nitemsp" +.Ft "const uint64_t *" +.Fn cnvlist_take_number_array "void *cookie" "size_t *nitemsp" +.Ft "const char * const *" +.Fn cnvlist_take_string_array "void *cookie" "size_t *nitemsp" +.Ft "const nvlist_t * const *" +.Fn cnvlist_take_nvlist_array "void *cookie" "size_t *nitemsp" +.Ft int +.Fn cnvlist_take_descriptor "void *cookie" +.Ft "const int *" +.Fn cnvlist_take_descriptor_array "void *cookie" "size_t *nitemsp" +.\" +.Ft void +.Fn cnvlist_free_null "void *cookie" +.Ft void +.Fn cnvlist_free_bool "void *cookie" +.Ft void +.Fn cnvlist_free_number "void *cookie" +.Ft void +.Fn cnvlist_free_string "void *cookie" +.Ft void +.Fn cnvlist_free_nvlist "void *cookie" +.Ft void +.Fn cnvlist_free_descriptor "void *cookie" +.Ft void +.Fn cnvlist_free_binary "void *cookie" +.Ft void +.Fn cnvlist_free_bool_array "void *cookie" +.Ft void +.Fn cnvlist_free_number_array "void *cookie" +.Ft void +.Fn cnvlist_free_string_array "void *cookie" +.Ft void +.Fn cnvlist_free_nvlist_array "void *cookie" +.Ft void +.Fn cnvlist_free_descriptor_array "void *cookie" +.Sh DESCRIPTION +The +.Nm libnv +library permits easy management of name/value pairs and can send and receive +them over sockets. +For more information, also see +.Xr nv 9 . +.Pp +The concept of cookies is explained in +.Fn nvlist_next , +.Fn nvlist_get_parent , +and +.Fn nvlist_get_pararr +from +.Xr nv 9 . +.Pp +The +.Fn cnvlist_name +function returns the name of an element associated with the given cookie. +.Pp +The +.Fn cnvlist_type +function returns the type of an element associated with the given cookie. +Types which can be returned are described in +.Xr nv 9 . +.Pp +The +.Nm cnvlist_get +family of functions obtains the value associated with the given cookie. +Returned strings, nvlists, descriptors, binaries, or arrays must not be modified +by the user, since they still belong to the nvlist. +The nvlist must not be in an error state. +.Pp +The +.Nm cnvlist_take +family of functions returns the value associated with the given cookie and +removes the element from the nvlist. +When the value is a string, binary, or array value, the caller is responsible +for freeing the returned memory with +.Fn free 3 . +When the value is an nvlist, the caller is responsible for destroying the +returned nvlist with +.Fn nvlist_destroy . +When the value is a descriptor, the caller is responsible for closing the +returned descriptor with the +.Fn close 2 . +.Pp +The +.Nm cnvlist_free +family of functions removes an element of the supplied cookie and frees all +resources. +If an element of the given cookie has the wrong type or does not exist, the +program +is aborted. +.Sh EXAMPLE +The following example demonstrates how to deal with cnvlist API. +.Bd -literal +int type; +void *cookie, *scookie, *bcookie; +nvlist_t *nvl; +char *name; + +nvl = nvlist_create(0); +nvlist_add_bool(nvl, "test", 1 == 2); +nvlist_add_string(nvl, "test2", "cnvlist"); +cookie = NULL; + +while (nvlist_next(nvl, &type, &cookie) != NULL) { + switch (type) { + case NV_TYPE_BOOL: + printf("test: %d\\n", cnvlist_get_bool(cookie)); + bcookie = cookie; + break; + case NV_TYPE_STRING: + printf("test2: %s\\n", cnvlist_get_string(cookie)); + scookie = cookie; + break; + } +} + +name = cnvlist_take_string(scookie); +cnvlist_free_bool(bcookie); + +printf("test2: %s\\n", name); +free(name); + +printf("nvlist_empty = %d\\n", nvlist_empty(nvl)); +nvlist_destroy(nvl); + +return (0); +.Ed +.Sh SEE ALSO +.Xr close 2 , +.Xr free 3 , +.Xr nv 9 +.Sh AUTHORS +The +.Nm cnv +API was created during the Google Summer Of Code 2016 by +.An Adam Starak . diff --git a/static/netbsd/man9/condvar.9 3.html b/static/netbsd/man9/condvar.9 3.html new file mode 100644 index 00000000..1def4ca5 --- /dev/null +++ b/static/netbsd/man9/condvar.9 3.html @@ -0,0 +1,362 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CONDVAR(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CONDVAR(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">cv</code>, <code class="Nm">condvar</code>, + <code class="Nm">cv_init</code>, <code class="Nm">cv_destroy</code>, + <code class="Nm">cv_wait</code>, <code class="Nm">cv_wait_sig</code>, + <code class="Nm">cv_timedwait</code>, + <code class="Nm">cv_timedwait_sig</code>, + <code class="Nm">cv_timedwaitbt</code>, + <code class="Nm">cv_timedwaitbt_sig</code>, + <code class="Nm">cv_signal</code>, <code class="Nm">cv_broadcast</code>, + <code class="Nm">cv_has_waiters</code> — <span class="Nd">condition + variables</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/condvar.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cv_init</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>, <var class="Fa" style="white-space: nowrap;">const char + *wmesg</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cv_destroy</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cv_wait</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>, <var class="Fa" style="white-space: nowrap;">kmutex_t + *mtx</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cv_wait_sig</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>, <var class="Fa" style="white-space: nowrap;">kmutex_t + *mtx</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cv_timedwait</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>, <var class="Fa" style="white-space: nowrap;">kmutex_t *mtx</var>, + <var class="Fa" style="white-space: nowrap;">int ticks</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cv_timedwait_sig</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>, <var class="Fa" style="white-space: nowrap;">kmutex_t *mtx</var>, + <var class="Fa" style="white-space: nowrap;">int ticks</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cv_timedwaitbt</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>, <var class="Fa" style="white-space: nowrap;">kmutex_t *mtx</var>, + <var class="Fa" style="white-space: nowrap;">struct bintime *bt</var>, + <var class="Fa" style="white-space: nowrap;">const struct bintime + *epsilon</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cv_timedwaitbt_sig</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>, <var class="Fa" style="white-space: nowrap;">kmutex_t *mtx</var>, + <var class="Fa" style="white-space: nowrap;">struct bintime *bt</var>, + <var class="Fa" style="white-space: nowrap;">const struct bintime + *epsilon</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cv_signal</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cv_broadcast</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">cv_has_waiters</code>(<var class="Fa" style="white-space: nowrap;">kcondvar_t + *cv</var>);</p> +<p class="Pp"> + <br/> + <code class="Cd">options DIAGNOSTIC</code> + <br/> + <code class="Cd">options LOCKDEBUG</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Condition variables (CVs) are used in the kernel to synchronize + access to resources that are limited (for example, memory) and to wait for + pending I/O operations to complete.</p> +<p class="Pp">The <var class="Vt">kcondvar_t</var> type provides storage for the + CV object. This should be treated as an opaque object and not examined + directly by consumers.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1> +<dl class="Bl-tag"> + <dt><code class="Cd">options DIAGNOSTIC</code></dt> + <dd> + <p class="Pp">Kernels compiled with the <code class="Dv">DIAGNOSTIC</code> + option perform basic sanity checks on CV operations.</p> + </dd> + <dt><code class="Cd">options LOCKDEBUG</code></dt> + <dd> + <p class="Pp">Kernels compiled with the <code class="Dv">LOCKDEBUG</code> + option perform potentially CPU intensive sanity checks on CV + operations.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="cv_init"><a class="permalink" href="#cv_init"><code class="Fn">cv_init</code></a>(<var class="Fa">cv</var>, + <var class="Fa">wmesg</var>)</dt> + <dd> + <p class="Pp">Initialize a CV for use. No other operations can be performed + on the CV until it has been initialized.</p> + <p class="Pp">The <var class="Fa">wmesg</var> argument specifies a string of + no more than 8 characters that describes the resource or condition + associated with the CV. The kernel does not use this argument directly + but makes it available for utilities such as <a class="Xr">ps(1)</a> to + display.</p> + </dd> + <dt id="cv_destroy"><a class="permalink" href="#cv_destroy"><code class="Fn">cv_destroy</code></a>(<var class="Fa">cv</var>)</dt> + <dd> + <p class="Pp" id="cv_broadcast">Release resources used by a CV. If there + could be waiters, they should be awoken first with + <a class="permalink" href="#cv_broadcast"><code class="Fn">cv_broadcast</code></a>(). + The CV must not be used afterwards.</p> + </dd> + <dt><code class="Fn">cv_wait</code>(<var class="Fa">cv</var>, + <var class="Fa">mtx</var>)</dt> + <dd> + <p class="Pp" id="cv_signal">Cause the current LWP to wait non-interruptably + for access to a resource, or for an I/O operation to complete. The LWP + will resume execution when awoken by another thread using + <a class="permalink" href="#cv_signal"><code class="Fn">cv_signal</code></a>() + or <code class="Fn">cv_broadcast</code>().</p> + <p class="Pp" id="cv_wait"><var class="Fa">mtx</var> specifies a kernel + mutex to be used as an interlock, and must be held by the calling LWP on + entry to + <a class="permalink" href="#cv_wait"><code class="Fn">cv_wait</code></a>(). + It will be released once the LWP has prepared to sleep, and will be + reacquired before <code class="Fn">cv_wait</code>() returns.</p> + <p class="Pp" id="cv_wait~2">A small window exists between testing for + availability of a resource and waiting for the resource with + <a class="permalink" href="#cv_wait~2"><code class="Fn">cv_wait</code></a>(), + in which the resource may become available again. The interlock is used + to guarantee that the resource will not be signalled as available until + the calling LWP has begun to wait for it.</p> + <p class="Pp">Non-interruptable waits have the potential to deadlock the + system, and so must be kept short (typically, under one second).</p> + <p class="Pp" id="cv_wait~3"><a class="permalink" href="#cv_wait~3"><code class="Fn">cv_wait</code></a>() + is typically used within a loop or restartable code sequence, because it + may awaken spuriously. The calling LWP should re-check the condition + that caused the wait. If necessary, the calling LWP may call + <code class="Fn">cv_wait</code>() again to continue waiting.</p> + </dd> + <dt><code class="Fn">cv_wait_sig</code>(<var class="Fa">cv</var>, + <var class="Fa">mtx</var>)</dt> + <dd> + <p class="Pp" id="cv_wait~4">As per + <a class="permalink" href="#cv_wait~4"><code class="Fn">cv_wait</code></a>(), + but causes the current LWP to wait interruptably. If the LWP receives a + signal, or is interrupted by another condition such as its containing + process exiting, the wait is ended early and an error code returned.</p> + <p class="Pp" id="cv_wait_sig">If + <a class="permalink" href="#cv_wait_sig"><code class="Fn">cv_wait_sig</code></a>() + returns as a result of a signal, the return value is + <code class="Er">ERESTART</code> if the signal has the + <code class="Dv">SA_RESTART</code> property. If awoken normally, the + value is zero, and <code class="Er">EINTR</code> under all other + conditions.</p> + </dd> + <dt><code class="Fn">cv_timedwait</code>(<var class="Fa">cv</var>, + <var class="Fa">mtx</var>, <var class="Fa">ticks</var>)</dt> + <dd> + <p class="Pp" id="cv_wait~5">As per + <a class="permalink" href="#cv_wait~5"><code class="Fn">cv_wait</code></a>(), + but will return early if a timeout specified by the + <var class="Fa">ticks</var> argument expires.</p> + <p class="Pp" id="cv_timedwait"><var class="Fa">ticks</var> is an + architecture and system dependent value related to the number of clock + interrupts per second. See <a class="Xr">hz(9)</a> for details. The + <a class="Xr">mstohz(9)</a> macro can be used to convert a timeout + expressed in milliseconds to one suitable for + <a class="permalink" href="#cv_timedwait"><code class="Fn">cv_timedwait</code></a>(). + If the <var class="Fa">ticks</var> argument is zero, + <code class="Fn">cv_timedwait</code>() behaves exactly like + <code class="Fn">cv_wait</code>().</p> + <p class="Pp">If the timeout expires before the LWP is awoken, the return + value is <code class="Er">EWOULDBLOCK</code>. If awoken normally, the + return value is zero.</p> + </dd> + <dt id="cv_timedwait_sig"><a class="permalink" href="#cv_timedwait_sig"><code class="Fn">cv_timedwait_sig</code></a>(<var class="Fa">cv</var>, + <var class="Fa">mtx</var>, <var class="Fa">ticks</var>)</dt> + <dd> + <p class="Pp" id="cv_wait_sig~2">As per + <a class="permalink" href="#cv_wait_sig~2"><code class="Fn">cv_wait_sig</code></a>(), + but also accepts a timeout value and will return + <code class="Er">EWOULDBLOCK</code> if the timeout expires.</p> + </dd> + <dt><code class="Fn">cv_timedwaitbt</code>(<var class="Fa">cv</var>, + <var class="Fa">mtx</var>, <var class="Fa">bt</var>, + <var class="Fa">epsilon</var>)</dt> + <dd style="width: auto;"> </dd> + <dt><code class="Fn">cv_timedwaitbt_sig</code>(<var class="Fa">cv</var>, + <var class="Fa">mtx</var>, <var class="Fa">bt</var>, + <var class="Fa">epsilon</var>)</dt> + <dd> + <p class="Pp" id="cv_wait~6">As per + <a class="permalink" href="#cv_wait~6"><code class="Fn">cv_wait</code></a>() + and <code class="Fn">cv_wait_sig</code>(), but will return early if the + duration <var class="Fa">bt</var> has elapsed, immediately if + <var class="Fa">bt</var> is zero. On return, + <code class="Fn">cv_timedwaitbt</code>() and + <code class="Fn">cv_timedwaitbt_sig</code>() subtract the time elapsed + from <var class="Fa">bt</var> in place, or set it to zero if there is no + time remaining.</p> + <p class="Pp" id="cv_timedwaitbt">Note that + <a class="permalink" href="#cv_timedwaitbt"><code class="Fn">cv_timedwaitbt</code></a>() + and + <a class="permalink" href="#cv_timedwaitbt_sig"><code class="Fn" id="cv_timedwaitbt_sig">cv_timedwaitbt_sig</code></a>() + may return zero indicating success, rather than + <code class="Er">EWOULDBLOCK</code>, even if they set the timeout to + zero; this means that the caller must re-check the condition in order to + avoid potentially losing a <code class="Fn">cv_signal</code>(), but the + <a class="permalink" href="#next"><i class="Em" id="next">next</i></a> + wait will time out immediately.</p> + <p class="Pp">The hint <var class="Fa">epsilon</var>, which can be + <code class="Dv">DEFAULT_TIMEOUT_EPSILON</code> if in doubt, requests + that the wakeup not be delayed more than <var class="Fa">bt</var> + <code class="Li">+</code> <var class="Fa">epsilon</var>, so that the + system can coalesce multiple wakeups within their respective epsilons + into a single high-resolution clock interrupt or choose to use cheaper + low-resolution clock interrupts instead.</p> + <p class="Pp">However, the system is still limited by its best clock + interrupt resolution and by scheduling competition, which may delay the + wakeup by more than <var class="Fa">bt</var> <code class="Li">+</code> + <var class="Fa">epsilon</var>.</p> + </dd> + <dt id="cv_signal~2"><a class="permalink" href="#cv_signal~2"><code class="Fn">cv_signal</code></a>(<var class="Fa">cv</var>)</dt> + <dd> + <p class="Pp">Awaken one LWP waiting on the specified condition variable. + Where there are waiters sleeping non-interruptaby, more than one LWP may + be awoken. This can be used to avoid a "thundering herd" + problem, where a large number of LWPs are awoken following an event, but + only one LWP can process the event.</p> + <p class="Pp" id="cv_signal~3">The mutex passed to the wait function + (<var class="Fa">mtx</var>) should be held or have been released + immediately before + <a class="permalink" href="#cv_signal~3"><code class="Fn">cv_signal</code></a>() + is called.</p> + <p class="Pp" id="cv_signal~4">(Note that + <a class="permalink" href="#cv_signal~4"><code class="Fn">cv_signal</code></a>() + is erroneously named in that it does not send a signal in the + traditional sense to LWPs waiting on a CV.)</p> + </dd> + <dt><code class="Fn">cv_broadcast</code>(<var class="Fa">cv</var>)</dt> + <dd> + <p class="Pp">Awaken all LWPs waiting on the specified condition + variable.</p> + <p class="Pp" id="cv_signal~5">As with + <a class="permalink" href="#cv_signal~5"><code class="Fn">cv_signal</code></a>(), + the mutex passed to the wait function (<var class="Fa">mtx</var>) should + be held or have been released immediately before + <code class="Fn">cv_broadcast</code>() is called.</p> + </dd> + <dt><code class="Fn">cv_has_waiters</code>(<var class="Fa">cv</var>)</dt> + <dd> + <p class="Pp">Return <code class="Dv">true</code> if one or more LWPs are + waiting on the specified condition variable.</p> + <p class="Pp" id="cv_has_waiters"><a class="permalink" href="#cv_has_waiters"><code class="Fn">cv_has_waiters</code></a>() + cannot test reliably for interruptable waits. It should only be used to + test for non-interruptable waits made using + <code class="Fn">cv_wait</code>().</p> + <p class="Pp" id="cv_has_waiters~2"><a class="permalink" href="#cv_has_waiters~2"><code class="Fn">cv_has_waiters</code></a>() + should only be used when making diagnostic assertions, and must be + called while holding the interlocking mutex passed to + <code class="Fn">cv_wait</code>().</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">Consuming a resource:</p> +<div class="Bd Pp Li"> +<pre> /* + * Lock the resource. Its mutex will also serve as the + * interlock. + */ + mutex_enter(&res->mutex); + + /* + * Wait for the resource to become available. Timeout after + * five seconds. If the resource is not available within the + * allotted time, return an error. + */ + struct bintime timeout = { .sec = 5, .frac = 0 }; + while (res->state == BUSY) { + error = cv_timedwaitbt(&res->condvar, + &res->mutex, &timeout, DEFAULT_TIMEOUT_EPSILON); + if (error) { + KASSERT(error == EWOULDBLOCK); + mutex_exit(&res->mutex); + return ETIMEDOUT; + } + } + + /* + * It's now available to us. Take ownership of the + * resource, and consume it. + */ + res->state = BUSY; + mutex_exit(&res->mutex); + consume(res);</pre> +</div> +<p class="Pp">Releasing a resource for the next consumer to use:</p> +<div class="Bd Pp Li"> +<pre> mutex_enter(&res->mutex); + res->state = IDLE; + cv_signal(&res->condvar); + mutex_exit(&res->mutex);</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The core of the CV implementation is in + <span class="Pa">sys/kern/kern_condvar.c</span>.</p> +<p class="Pp">The header file <span class="Pa">sys/sys/condvar.h</span> + describes the public interface.</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">sigaction(2)</a>, <a class="Xr">membar_ops(3)</a>, + <a class="Xr">errno(9)</a>, <a class="Xr">mstohz(9)</a>, + <a class="Xr">mutex(9)</a>, <a class="Xr">rwlock(9)</a></p> +<p class="Pp"></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Jim Mauro</span> and + <span class="RsA">Richard McDougall</span>, <span class="RsT">Solaris + Internals: Core Kernel Architecture</span>, <i class="RsI">Prentice + Hall</i>, <span class="RsD">2001</span>, <span class="RsO">ISBN + 0-13-022496-0</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The CV primitives first appeared in <span class="Ux">NetBSD + 5.0</span>. The <code class="Fn">cv_timedwaitbt</code>() and + <code class="Fn">cv_timedwaitbt_sig</code>() primitives first appeared in + <span class="Ux">NetBSD 9.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 7, 2023</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cons.9 3.html b/static/netbsd/man9/cons.9 3.html new file mode 100644 index 00000000..2983cb8d --- /dev/null +++ b/static/netbsd/man9/cons.9 3.html @@ -0,0 +1,137 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CONS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CONS(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">cnbell</code>, <code class="Nm">cnflush</code>, + <code class="Nm">cngetc</code>, <code class="Nm">cngetsn</code>, + <code class="Nm">cnhalt</code>, <code class="Nm">cnpollc</code>, + <code class="Nm">cnputc</code> — <span class="Nd">console access + interface</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">dev/cons.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cnbell</code>(<var class="Fa" style="white-space: nowrap;">u_int + pitch</var>, <var class="Fa" style="white-space: nowrap;">u_int + period</var>, <var class="Fa" style="white-space: nowrap;">u_int + volume</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cnflush</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cngetc</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cngetsn</code>(<var class="Fa" style="white-space: nowrap;">char + *cp</var>, <var class="Fa" style="white-space: nowrap;">int size</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cnhalt</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cnpollc</code>(<var class="Fa" style="white-space: nowrap;">int + on</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cnputc</code>(<var class="Fa" style="white-space: nowrap;">int + c</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">These functions operate over the current console device. The + console must be initialized before these functions can be used.</p> +<p class="Pp" id="cngetc">Console input polling functions + <a class="permalink" href="#cngetc"><code class="Fn">cngetc</code></a>(), + <a class="permalink" href="#cngetsn"><code class="Fn" id="cngetsn">cngetsn</code></a>() + and + <a class="permalink" href="#cnpollc"><code class="Fn" id="cnpollc">cnpollc</code></a>() + are only to be used during initial system boot, e.g., when asking for root + and dump device or to get necessary user input within mountroothooks. Once + the system boots, user input is read via standard <a class="Xr">tty(4)</a> + facilities.</p> +<p class="Pp">The following is a brief description of each function:</p> +<dl class="Bl-tag"> + <dt id="cnbell"><a class="permalink" href="#cnbell"><code class="Fn">cnbell</code></a>()</dt> + <dd>Ring a bell at appropriate <var class="Fa">pitch</var>, for duration of + <var class="Fa">period</var> milliseconds at given + <var class="Fa">volume</var>. Note that the <var class="Fa">volume</var> + value is ignored commonly.</dd> + <dt id="cnflush"><a class="permalink" href="#cnflush"><code class="Fn">cnflush</code></a>()</dt> + <dd>Waits for all pending output to finish.</dd> + <dt id="must"><code class="Fn">cngetc</code>()</dt> + <dd>Poll (busy wait) for an input and return the input key. Returns 0 if there + is no console input device. <code class="Fn">cnpollc</code>() + <a class="permalink" href="#must"><i class="Em">must</i></a> be called + before <code class="Fn">cngetc</code>() could be used. + <code class="Fn">cngetc</code>() should be used during kernel startup + only.</dd> + <dt id="not"><code class="Fn">cngetsn</code>()</dt> + <dd>Read one line of user input, stop reading once the newline key is input. + Input is echoed back. This uses <code class="Fn">cnpollc</code>() and + <code class="Fn">cngetc</code>(). Number of read characters is + <var class="Fa">size</var> at maximum, user is notified by console bell + when the end of input buffer is reached. <Backspace> key works as + expected. <@> or <CTRL>-u make + <code class="Fn">cngetsn</code>() discard input read so far, print newline + and wait for next input. <code class="Fn">cngetsn</code>() returns number + of characters actually read, excluding the final newline. + <var class="Fa">cp</var> is + <a class="permalink" href="#not"><i class="Em">not</i></a> zero-ended + before return. <code class="Fn">cngetsn</code>() should be used during + kernel startup only.</dd> + <dt id="cnhalt"><a class="permalink" href="#cnhalt"><code class="Fn">cnhalt</code></a>()</dt> + <dd>Terminates the console device (i.e. cleanly shuts down the console + hardware.)</dd> + <dt><code class="Fn">cnpollc</code>()</dt> + <dd>Switch the console driver to polling mode if <var class="Fa">on</var> is + nonzero, or back to interrupt driven mode if <var class="Fa">on</var> is + zero. <code class="Fn">cnpollc</code>() should be used during kernel + startup only.</dd> + <dt id="cnputc"><a class="permalink" href="#cnputc"><code class="Fn">cnputc</code></a>()</dt> + <dd>Console kernel output character routine. Commonly, kernel code uses + <a class="Xr">printf(9)</a> rather than using this low-level + interface.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">This waits until a <Enter> key is pressed:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>int c; + +cnpollc(1); +for(;;) { + c = cngetc(); + if ((c == '\r' || (c == '\n')) { + printf("\n"); + break; + } +} +cnpollc(0);</pre> +</div> +</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">pckbd(4)</a>, <a class="Xr">pcppi(4)</a>, + <a class="Xr">tty(4)</a>, <a class="Xr">wscons(4)</a>, + <a class="Xr">wskbd(4)</a>, <a class="Xr">printf(9)</a>, + <a class="Xr">spl(9)</a>, <a class="Xr">wscons(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">June 8, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cprng.9 3.html b/static/netbsd/man9/cprng.9 3.html new file mode 100644 index 00000000..4949c78c --- /dev/null +++ b/static/netbsd/man9/cprng.9 3.html @@ -0,0 +1,218 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CPRNG(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CPRNG(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">cprng</code>, + <code class="Nm">cprng_strong_create</code>, + <code class="Nm">cprng_strong_destroy</code>, + <code class="Nm">cprng_strong</code>, + <code class="Nm">cprng_strong32</code>, + <code class="Nm">cprng_strong64</code>, <code class="Nm">cprng_fast</code>, + <code class="Nm">cprng_fast32</code>, <code class="Nm">cprng_fast64</code> + — <span class="Nd">cryptographic pseudorandom number + generators</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/cprng.h</a>></code></p> +<p class="Pp"><var class="Ft">cprng_strong_t *</var> + <br/> + <code class="Fn">cprng_strong_create</code>(<var class="Fa" style="white-space: nowrap;">const + char *name</var>, <var class="Fa" style="white-space: nowrap;">int + ipl</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cprng_strong_destroy</code>(<var class="Fa" style="white-space: nowrap;">cprng_strong_t + *cprng</var>);</p> +<p class="Pp"><var class="Ft">size_t</var> + <br/> + <code class="Fn">cprng_strong</code>(<var class="Fa" style="white-space: nowrap;">cprng_strong_t + *cprng</var>, <var class="Fa" style="white-space: nowrap;">void *buf</var>, + <var class="Fa" style="white-space: nowrap;">size_t len</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> +<p class="Pp"><var class="Ft">uint32_t</var> + <br/> + <code class="Fn">cprng_strong32</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">uint64_t</var> + <br/> + <code class="Fn">cprng_strong64</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">size_t</var> + <br/> + <code class="Fn">cprng_fast</code>(<var class="Fa" style="white-space: nowrap;">void + *buf</var>, <var class="Fa" style="white-space: nowrap;">size_t + len</var>);</p> +<p class="Pp"><var class="Ft">uint32_t</var> + <br/> + <code class="Fn">cprng_fast32</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">uint64_t</var> + <br/> + <code class="Fn">cprng_fast64</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<div class="Bd Pp Li"> +<pre>#define CPRNG_MAX_LEN 524288</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">cprng</code> family of functions provide + cryptographic pseudorandom number generators automatically seeded from the + kernel entropy pool. All applications in the kernel requiring random data or + random choices should use the <code class="Nm">cprng_strong</code> family of + functions, unless performance constraints demand otherwise.</p> +<p class="Pp">The <code class="Nm">cprng_fast</code> family of functions may be + used in applications that can tolerate exposure of past random data, such as + initialization vectors or transaction ids that are sent over the internet + anyway, if the applications require higher throughput or lower per-request + latency than the <code class="Nm">cprng_strong</code> family of functions + provide. If in doubt, choose <code class="Nm">cprng_strong</code>.</p> +<p class="Pp" id="cprng_strong_create">A single instance of the fast generator + serves the entire kernel. A well-known instance of the strong generator, + <code class="Dv">kern_cprng</code>, may be used by any in-kernel caller, but + separately seeded instances of the strong generator can also be created by + calling + <a class="permalink" href="#cprng_strong_create"><code class="Fn">cprng_strong_create</code></a>().</p> +<p class="Pp" id="cprng_strong_create~2">The <code class="Nm">cprng</code> + functions may be used in soft interrupt context, except for + <a class="permalink" href="#cprng_strong_create~2"><code class="Fn">cprng_strong_create</code></a>() + and <code class="Fn">cprng_strong_destroy</code>() which are allowed only at + <code class="Dv">IPL_NONE</code> in thread context; see + <a class="Xr">spl(9)</a>.</p> +<p class="Pp">The <code class="Nm">cprng</code> functions replace the legacy + <a class="Xr">arc4random(9)</a> and <a class="Xr">rnd_extract_data(9)</a> + functions.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="cprng_strong_create~3"><a class="permalink" href="#cprng_strong_create~3"><code class="Fn">cprng_strong_create</code></a>(<var class="Fa">name</var>, + <var class="Fa">ipl</var>, <var class="Fa">flags</var>)</dt> + <dd>Create an instance of the cprng_strong generator. This generator currently + implements the NIST SP 800-90A Hash_DRBG with SHA-256 as the hash + function. + <p class="Pp">The <var class="Fa">name</var> argument is used to + “personalize” the Hash_DRBG according to the standard, so + that its initial state will depend both on seed material from the + entropy pool and also on the personalization string (name).</p> + <p class="Pp">The <var class="Fa">ipl</var> argument specifies the interrupt + priority level for the mutex which will serialize access to the new + instance of the generator (see <a class="Xr">spl(9)</a>), and must be no + higher than <code class="Dv">IPL_SOFTSERIAL</code>.</p> + <p class="Pp">The <var class="Fa">flags</var> argument must be zero.</p> + <p class="Pp">Creation will succeed even if full entropy for the generator + is not available. In this case, the first request to read from the + generator may cause reseeding.</p> + <p class="Pp" id="cprng_strong_create~4"><a class="permalink" href="#cprng_strong_create~4"><code class="Fn">cprng_strong_create</code></a>() + may sleep to allocate memory.</p> + </dd> + <dt><code class="Fn">cprng_strong_destroy</code>(<var class="Fa">cprng</var>)</dt> + <dd>Destroy <var class="Fa">cprng</var>. + <p class="Pp" id="cprng_strong_destroy"><a class="permalink" href="#cprng_strong_destroy"><code class="Fn">cprng_strong_destroy</code></a>() + may sleep.</p> + </dd> + <dt id="cprng_strong"><a class="permalink" href="#cprng_strong"><code class="Fn">cprng_strong</code></a>(<var class="Fa">cprng</var>, + <var class="Fa">buf</var>, <var class="Fa">len</var>, + <var class="Fa">flags</var>)</dt> + <dd>Fill memory location <var class="Fa">buf</var> with up to + <var class="Fa">len</var> bytes from the generator + <var class="Fa">cprng</var>, and return the number of bytes. + <var class="Fa">len</var> must be at most + <code class="Dv">CPRNG_MAX_LEN</code>. <var class="Fa">flags</var> must be + zero.</dd> + <dt><code class="Fn">cprng_strong32</code>()</dt> + <dd>Generate 32 bits using the <code class="Dv">kern_cprng</code> strong + generator. + <p class="Pp" id="cprng_strong32"><a class="permalink" href="#cprng_strong32"><code class="Fn">cprng_strong32</code></a>() + does not sleep.</p> + </dd> + <dt><code class="Fn">cprng_strong64</code>()</dt> + <dd>Generate 64 bits using the <code class="Dv">kern_cprng</code> strong + generator. + <p class="Pp" id="cprng_strong64"><a class="permalink" href="#cprng_strong64"><code class="Fn">cprng_strong64</code></a>() + does not sleep.</p> + </dd> + <dt><code class="Fn">cprng_fast</code>(<var class="Fa">buf</var>, + <var class="Fa">len</var>)</dt> + <dd>Fill memory location <var class="Fa">buf</var> with + <var class="Fa">len</var> bytes from the fast generator. + <p class="Pp" id="cprng_fast"><a class="permalink" href="#cprng_fast"><code class="Fn">cprng_fast</code></a>() + does not sleep.</p> + </dd> + <dt><code class="Fn">cprng_fast32</code>()</dt> + <dd>Generate 32 bits using the fast generator. + <p class="Pp" id="cprng_fast32"><a class="permalink" href="#cprng_fast32"><code class="Fn">cprng_fast32</code></a>() + does not sleep.</p> + </dd> + <dt><code class="Fn">cprng_fast64</code>()</dt> + <dd>Generate 64 bits using the fast generator. + <p class="Pp" id="cprng_fast64"><a class="permalink" href="#cprng_fast64"><code class="Fn">cprng_fast64</code></a>() + does not sleep.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SECURITY_MODEL"><a class="permalink" href="#SECURITY_MODEL">SECURITY + MODEL</a></h1> +<p class="Pp">The <code class="Nm">cprng</code> family of functions provide the + following security properties:</p> +<ul class="Bl-bullet Bd-indent"> + <li>An attacker who has seen some outputs of any of the + <code class="Nm">cprng</code> functions cannot predict past or future + unseen outputs.</li> + <li>An attacker who has compromised kernel memory cannot predict past outputs + of the <code class="Nm">cprng_strong</code> functions. However, such an + attacker may be able to predict past outputs of the + <code class="Nm">cprng_fast</code> functions.</li> +</ul> +<p class="Pp">The second property is sometimes called “backtracking + resistance”, “forward secrecy”, or “key + erasure” in the cryptography literature. The + <code class="Nm">cprng_strong</code> functions provide backtracking + resistance; the <code class="Nm">cprng_fast</code> functions do not.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">cprng_strong</code> functions are implemented + in <span class="Pa">sys/kern/subr_cprng.c</span>, and use the NIST SP + 800-90A Hash_DRBG implementation in + <span class="Pa">sys/crypto/nist_hash_drbg</span>. The + <code class="Nm">cprng_fast</code> functions are implemented in + <span class="Pa">sys/crypto/cprng_fast/cprng_fast.c</span>, and use the + ChaCha8 stream cipher.</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">condvar(9)</a>, <a class="Xr">rnd(9)</a>, + <a class="Xr">spl(9)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Elaine Barker</span> and + <span class="RsA">John Kelsey</span>, <span class="RsT">Recommendation for + Random Number Generation Using Deterministic Random Bit Generators + (Revised)</span>, <i class="RsI">National Institute of Standards and + Technology</i>, <span class="RsD">2011</span>, <span class="RsO">NIST + Special Publication 800-90A, Rev 1</span>.</cite></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Daniel J. Bernstein</span>, + <span class="RsT">ChaCha, a variant of Salsa20</span>, + <a class="RsU" href="http://cr.yp.to/papers.html#chacha">http://cr.yp.to/papers.html#chacha</a>, + <span class="RsD">2008-01-28</span>, <span class="RsO">Document ID: + 4027b5256e17b9796842e6d0f68b0b5e</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The cprng family of functions first appeared in + <span class="Ux">NetBSD 6.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 16, 2020</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cpu_configure.9 3.html b/static/netbsd/man9/cpu_configure.9 3.html new file mode 100644 index 00000000..2a67aa1b --- /dev/null +++ b/static/netbsd/man9/cpu_configure.9 3.html @@ -0,0 +1,54 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CPU_CONFIGURE(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CPU_CONFIGURE(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">cpu_configure</code> — + <span class="Nd">machine-dependent device autoconfiguration</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cpu_configure</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The machine-dependent + <a class="permalink" href="#cpu_configure"><code class="Fn" id="cpu_configure">cpu_configure</code></a>() + is called during system bootstrap to perform the machine-dependent portion + of device autoconfiguration. It sets the configuration machinery in motion + by finding the root bus (“mainbus”). When this function + returns, interrupts must be enabled.</p> +<p class="Pp" id="cpu_configure~2">The following tasks are performed by + <a class="permalink" href="#cpu_configure~2"><code class="Fn">cpu_configure</code></a>():</p> +<ul class="Bl-bullet Bd-indent"> + <li>initialize soft interrupts (see <a class="Xr">softint(9)</a>);</li> + <li>initialize CPU interrupts and SPLs (see <a class="Xr">spl(9)</a>);</li> + <li id="config_rootfound">call + <a class="permalink" href="#config_rootfound"><code class="Fn">config_rootfound</code></a>() + for “mainbus”; and</li> + <li>complete any initialization deferred from + <a class="Xr">cpu_startup(9)</a>.</li> +</ul> +</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">autoconf(9)</a>, + <a class="Xr">cpu_startup(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 13, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cpu_dumpconf.9 3.html b/static/netbsd/man9/cpu_dumpconf.9 3.html new file mode 100644 index 00000000..d7fabb54 --- /dev/null +++ b/static/netbsd/man9/cpu_dumpconf.9 3.html @@ -0,0 +1,69 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CPU_DUMPCONF(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CPU_DUMPCONF(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">cpu_dumpconf</code>, + <code class="Nm">cpu_dump</code>, <code class="Nm">cpu_dumpsize</code>, + <code class="Nm">dumpsys</code> — <span class="Nd">machine-dependent + kernel core dumps</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/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cpu_dumpconf</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cpu_dump</code>(<var class="Fa" style="white-space: nowrap;">int + (*dump)(dev_t, daddr_t, void *, size_t)</var>, + <var class="Fa" style="white-space: nowrap;">daddr_t *blknop</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cpu_dumpsize</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dumpsys</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><a class="permalink" href="#cpu_dumpconf"><code class="Fn" id="cpu_dumpconf">cpu_dumpconf</code></a>() + is the machine-dependent interface invoked during system bootstrap to + determine the dump device and initialize machine-dependent kernel core dump + state. Internally, <code class="Fn">cpu_dumpconf</code>() will invoke + <code class="Fn">cpu_dumpsize</code>() to calculate the size of + machine-dependent kernel core dump headers.</p> +<p class="Pp" id="dumpsys"><a class="permalink" href="#dumpsys"><code class="Fn">dumpsys</code></a>() + is invoked by + <a class="permalink" href="#cpu_reboot"><code class="Fn" id="cpu_reboot">cpu_reboot</code></a>() + to dump kernel physical memory onto the dump device. + <code class="Fn">dumpsys</code>() invokes <code class="Fn">cpu_dump</code>() + to write the machine-dependent header to the dump device at block number + <var class="Fa">*blknop</var> using the dump device's PIO dump routine + specified by the <var class="Fa">dump</var> argument.</p> +<p class="Pp" id="cpu_dumpsize"><a class="permalink" href="#cpu_dumpsize"><code class="Fn">cpu_dumpsize</code></a>(), + <a class="permalink" href="#cpu_dump"><code class="Fn" id="cpu_dump">cpu_dump</code></a>(), + and <code class="Fn">dumpsys</code>() are parts of the machine-dependent + interface, however they are not exported to machine-independent code.</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">cpu_reboot(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 24, 2002</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cpu_need_resched.9 3.html b/static/netbsd/man9/cpu_need_resched.9 3.html new file mode 100644 index 00000000..4db08d3c --- /dev/null +++ b/static/netbsd/man9/cpu_need_resched.9 3.html @@ -0,0 +1,80 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CPU_NEED_RESCHED(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CPU_NEED_RESCHED(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">cpu_need_resched</code> — + <span class="Nd">context switch notification</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/cpu.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cpu_need_resched</code>(<var class="Fa" style="white-space: nowrap;">struct + cpu_info *ci</var>, <var class="Fa" style="white-space: nowrap;">struct lwp + *l</var>, <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#cpu_need_resched"><code class="Fn" id="cpu_need_resched">cpu_need_resched</code></a>() + function is the machine-independent interface for the scheduler to notify + machine-dependent code that a context switch from the current LWP + <var class="Fa">l</var>, on the cpu <var class="Fa">ci</var>, is required. + This event may occur if a higher priority LWP appears on the run queue or if + the current LWP has exceeded its time slice. <var class="Fa">l</var> is the + last LWP observed running on the CPU. It may no longer be running, as + <code class="Fn">cpu_need_resched</code>() can be called without holding + scheduler locks.</p> +<p class="Pp">If the <code class="Dv">RESCHED_KPREEMPT</code> flag is specified + in <var class="Fa">flags</var> and <code class="Dv">__HAVE_PREEMPTION</code> + C pre-processor macro is defined in + <code class="In"><<a class="In">machine/intr.h</a>></code>, + machine-dependent code should make a context switch happen as soon as + possible even if the CPU is running in kernel mode. If the + <code class="Dv">RESCHED_KPREEMPT</code> flag is not specified, then + <code class="Dv">RESCHED_UPREEMPT</code> is specified instead.</p> +<p class="Pp">If the <code class="Dv">RESCHED_IDLE</code> flag is specified in + <var class="Fa">flags</var>, the last thread observed running on the CPU was + the idle LWP.</p> +<p class="Pp" id="cpu_need_resched~2">If <code class="Dv">RESCHED_REMOTE</code> + flag is specified in <var class="Fa">flags</var>, the request is not for the + current CPU. The opposite also holds true. If <var class="Fa">ci</var> is + not the current processor, + <a class="permalink" href="#cpu_need_resched~2"><code class="Fn">cpu_need_resched</code></a>() + typically issues an inter processor call to the processor to make it notice + the need of a context switch as soon as possible.</p> +<p class="Pp" id="cpu_need_resched~3"><a class="permalink" href="#cpu_need_resched~3"><code class="Fn">cpu_need_resched</code></a>() + is always called with kernel preemption disabled.</p> +<p class="Pp" id="cpu_need_resched~4">Typically, the + <a class="permalink" href="#cpu_need_resched~4"><code class="Fn">cpu_need_resched</code></a>() + function will perform the following operations:</p> +<ul class="Bl-bullet Bd-indent"> + <li>Set a per-processor flag which is checked by <a class="Xr">userret(9)</a> + when returning to user-mode execution.</li> + <li>Post an asynchronous software trap (AST).</li> + <li id="userret">Send an inter processor interrupt to wake up + <a class="Xr">cpu_idle(9)</a> and/or force an user process across the + user/kernel boundary, thus making a trip through + <a class="permalink" href="#userret"><code class="Fn">userret</code></a>().</li> +</ul> +</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">sched_4bsd(9)</a>, <a class="Xr">userret(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 17, 2019</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/cpu_rootconf.9 3.html b/static/netbsd/man9/cpu_rootconf.9 3.html new file mode 100644 index 00000000..fe371383 --- /dev/null +++ b/static/netbsd/man9/cpu_rootconf.9 3.html @@ -0,0 +1,98 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CPU_ROOTCONF(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CPU_ROOTCONF(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">cpu_rootconf</code>, + <code class="Nm">rootconf</code>, <code class="Nm">setroot</code> — + <span class="Nd">root file system setup</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/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cpu_rootconf</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">rootconf</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">setroot</code>(<var class="Fa" style="white-space: nowrap;">device_t + bootdv</var>, <var class="Fa" style="white-space: nowrap;">int + bootpartition</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#cpu_rootconf"><code class="Fn" id="cpu_rootconf">cpu_rootconf</code></a>() + is a machine-dependent interface invoked during system bootstrap to + determine the root file system device and initialize machine-dependent file + system state. <code class="Fn">cpu_rootconf</code>() provides the global + variables <var class="Fa">booted_device</var>, + <var class="Fa">booted_partition</var>, + <var class="Fa">booted_startblk</var>, <var class="Fa">booted_nblks</var>, + and <var class="Fa">bootspec</var>. <var class="Fa">cpu_rootconf</var> + invokes the machine-independent function <var class="Fa">rootconf</var> + which calls the function <var class="Fa">setroot</var> to record the root + device and the root partition information for use in machine-independent + code.</p> +<p class="Pp"><var class="Fa">rootconf</var> may adjust the global variables and + determines the parameters for setroot. This is for example used to translate + a device and partition number provided by the bootloader into a disk wedge + device covering the same partition.</p> +<p class="Pp">If the bootloader already identified a disk wedge, it passes a + non-zero value for <var class="Fa">booted_nblks</var>, then + <var class="Fa">booted_startblk</var> and <var class="Fa">booted_nblks</var> + specify a disk wedge as the boot device.</p> +<p class="Pp"><var class="Fa">setroot</var> evaluates several sources to + identify the root device in the following order until a valid device is + selected:</p> +<ol class="Bl-enum"> + <li>The kernel configuration variable <var class="Fa">rootspec</var> which is + set by <a class="Xr">config(1)</a>. The value is the name and unit of the + root device, e.g., "sd0" (disk) or "dk0" (wedge) or + "le0" (network) or the prefix "wedge:" followed by the + name of the disk wedge. For disk devices the partition passed as argument + to <var class="Fa">setroot</var> is used.</li> + <li>The variable <var class="Fa">bootspec</var> following the same + syntax.</li> + <li>The result of an interactive query of the root device if + <var class="Fa">boothowto</var> has set the flag + <code class="Dv">RB_ASKNAME</code>. The input uses the same syntax as the + previous sources. Here also the kernel dump device is queried.</li> + <li>The boot device and partition passed as arguments.</li> +</ol> +<p class="Pp">If a root device cannot be selected, <var class="Fa">setroot</var> + sets the <code class="Dv">RB_ASKNAME</code> flag and loops.</p> +<p class="Pp">Otherwise the kernel dump device is identified in a similar manner + from</p> +<ol class="Bl-enum"> + <li>The result of a previous interactive query. See above.</li> + <li>The kernel configuration variable <var class="Fa">dumpspec</var>, if + set.</li> + <li>The second partition of the root device, if it is a regular disk.</li> + <li>The first disk wedge device of type DKW_PTYPE_SWAP.</li> +</ol> +</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">dk(4)</a>, + <a class="Xr">boot(8)</a>, <a class="Xr">boothowto(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 11, 2014</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/csf.9 3.html b/static/netbsd/man9/csf.9 3.html new file mode 100644 index 00000000..4702e2dc --- /dev/null +++ b/static/netbsd/man9/csf.9 3.html @@ -0,0 +1,295 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CSF(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CSF(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">CSF</code> — <span class="Nd">The + <span class="Ux">NetBSD</span> common scheduler 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/sched.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_rqinit</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_setup</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_cpuattach</code>(<var class="Fa" style="white-space: nowrap;">struct + cpu_info *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_tick</code>(<var class="Fa" style="white-space: nowrap;">struct + cpu_info *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_schedclock</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">sched_curcpu_runnable_p</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">lwp_t *</var> + <br/> + <code class="Fn">sched_nextlwp</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_enqueue</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>, <var class="Fa" style="white-space: nowrap;">bool</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_dequeue</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_nice</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_proc_fork</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *</var>, <var class="Fa" style="white-space: nowrap;">struct proc + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_proc_exit</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *</var>, <var class="Fa" style="white-space: nowrap;">struct proc + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_lwp_fork</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_lwp_exit</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_setrunnable</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_print_runqueue</code>(<var class="Fa" style="white-space: nowrap;">void + (*pr)(const char *, ...)</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_pstats_hook</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *</var>, <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_pstats</code>(<var class="Fa" style="white-space: nowrap;">void + *arg</var>);</p> +<p class="Pp"><var class="Ft">pri_t</var> + <br/> + <code class="Fn">sched_kpri</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">resched_cpu</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">setrunnable</code>();</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">schedclock</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_init</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">CSF</code> provides a modular and self-contained + interface for implementing different thread scheduling algorithms. The + different schedulers can be selected at compile-time. Currently, the + schedulers available are <a class="Xr">sched_4bsd(9)</a>, the traditional + 4.4BSD thread scheduler, and <a class="Xr">sched_m2(9)</a> which implements + a SVR4/Solaris like approach.</p> +<p class="Pp">The interface is divided into two parts: A set of functions each + scheduler needs to implement and common functions used by all + schedulers.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="Scheduler-specific_functions"><a class="permalink" href="#Scheduler-specific_functions">Scheduler-specific + functions</a></h1> +<p class="Pp">The following functions have to be implemented by the individual + scheduler.</p> +<section class="Ss"> +<h2 class="Ss" id="Scheduler_initialization"><a class="permalink" href="#Scheduler_initialization">Scheduler + initialization</a></h2> +<dl class="Bl-tag"> + <dt id="sched_cpuattach"><var class="Ft">void</var> + <a class="permalink" href="#sched_cpuattach"><code class="Fn">sched_cpuattach</code></a>(<var class="Fa">struct + cpu_info *</var>)</dt> + <dd>Per-CPU scheduler initialization routine.</dd> + <dt id="sched_rqinit"><var class="Ft">void</var> + <a class="permalink" href="#sched_rqinit"><code class="Fn">sched_rqinit</code></a>(<var class="Fa">void</var>)</dt> + <dd>Initialize the scheduler's runqueue data structures.</dd> + <dt id="sched_setup"><var class="Ft">void</var> + <a class="permalink" href="#sched_setup"><code class="Fn">sched_setup</code></a>(<var class="Fa">void</var>)</dt> + <dd>Setup initial scheduling parameters and kick off timeout driven + events.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Runqueue_handling"><a class="permalink" href="#Runqueue_handling">Runqueue + handling</a></h2> +<p class="Pp">Runqueue handling is completely internal to the scheduler. Other + parts of the kernel should access runqueues only through the following + functions:</p> +<dl class="Bl-tag"> + <dt id="sched_enqueue"><var class="Ft">void</var> + <a class="permalink" href="#sched_enqueue"><code class="Fn">sched_enqueue</code></a>(<var class="Fa">lwp_t + *</var>, <var class="Fa">bool</var>)</dt> + <dd>Place an LWP within the scheduler's runqueue structures.</dd> + <dt id="sched_dequeue"><var class="Ft">void</var> + <a class="permalink" href="#sched_dequeue"><code class="Fn">sched_dequeue</code></a>(<var class="Fa">lwp_t + *</var>)</dt> + <dd>Remove an LWP from the scheduler's runqueue structures.</dd> + <dt id="sched_nextlwp"><var class="Ft">lwp_t *</var> + <a class="permalink" href="#sched_nextlwp"><code class="Fn">sched_nextlwp</code></a>(<var class="Fa">void</var>)</dt> + <dd>Return the LWP that should run the CPU next.</dd> + <dt id="sched_curcpu_runnable_p"><var class="Ft">bool</var> + <a class="permalink" href="#sched_curcpu_runnable_p"><code class="Fn">sched_curcpu_runnable_p</code></a>(<var class="Fa">void</var>)</dt> + <dd>Indicate if there is a runnable LWP for the current CPU.</dd> + <dt id="sched_print_runqueue"><var class="Ft">void</var> + <a class="permalink" href="#sched_print_runqueue"><code class="Fn">sched_print_runqueue</code></a>(<var class="Fa">void + (*pr)(const char *, ...)</var>)</dt> + <dd>Print runqueues in DDB.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Core_scheduler_functions"><a class="permalink" href="#Core_scheduler_functions">Core + scheduler functions</a></h2> +<dl class="Bl-tag"> + <dt id="sched_tick"><var class="Ft">void</var> + <a class="permalink" href="#sched_tick"><code class="Fn">sched_tick</code></a>(<var class="Fa">struct + cpu_info *</var>)</dt> + <dd>Periodically called from <a class="Xr">hardclock(9)</a>. Determines if a + reschedule is necessary, if the running LWP has used up its quantum.</dd> + <dt id="sched_schedclock"><var class="Ft">void</var> + <a class="permalink" href="#sched_schedclock"><code class="Fn">sched_schedclock</code></a>(<var class="Fa">lwp_t + *</var>)</dt> + <dd>Periodically called from + <a class="permalink" href="#schedclock"><code class="Fn" id="schedclock">schedclock</code></a>() + in order to handle priority adjustment.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Priority_adjustment"><a class="permalink" href="#Priority_adjustment">Priority + adjustment</a></h2> +<dl class="Bl-tag"> + <dt id="sched_nice"><var class="Ft">void</var> + <a class="permalink" href="#sched_nice"><code class="Fn">sched_nice</code></a>(<var class="Fa">struct + proc *</var>, <var class="Fa">int</var>)</dt> + <dd>Recalculate the process priority according to its nice value.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="General_helper_functions"><a class="permalink" href="#General_helper_functions">General + helper functions</a></h2> +<dl class="Bl-tag"> + <dt id="sched_proc_fork"><var class="Ft">void</var> + <a class="permalink" href="#sched_proc_fork"><code class="Fn">sched_proc_fork</code></a>(<var class="Fa">struct + proc *</var>, <var class="Fa">struct proc *</var>)</dt> + <dd>Inherit the scheduling history of the parent process after + <a class="permalink" href="#fork"><code class="Fn" id="fork">fork</code></a>().</dd> + <dt id="sched_proc_exit"><var class="Ft">void</var> + <a class="permalink" href="#sched_proc_exit"><code class="Fn">sched_proc_exit</code></a>(<var class="Fa">struct + proc *</var>, <var class="Fa">struct proc *</var>)</dt> + <dd>Charge back a processes parent for its resource usage.</dd> + <dt id="sched_lwp_fork"><var class="Ft">void</var> + <a class="permalink" href="#sched_lwp_fork"><code class="Fn">sched_lwp_fork</code></a>(<var class="Fa">lwp_t + *</var>)</dt> + <dd>LWP-specific version of the above</dd> + <dt id="sched_lwp_exit"><var class="Ft">void</var> + <a class="permalink" href="#sched_lwp_exit"><code class="Fn">sched_lwp_exit</code></a>(<var class="Fa">lwp_t + *</var>)</dt> + <dd>LWP-specific version of the above</dd> + <dt id="sched_setrunnable"><var class="Ft">void</var> + <a class="permalink" href="#sched_setrunnable"><code class="Fn">sched_setrunnable</code></a>(<var class="Fa">lwp_t + *</var>)</dt> + <dd>Scheduler-specific actions for + <a class="permalink" href="#setrunnable"><code class="Fn" id="setrunnable">setrunnable</code></a>().</dd> + <dt id="sched_pstats_hook"><var class="Ft">void</var> + <a class="permalink" href="#sched_pstats_hook"><code class="Fn">sched_pstats_hook</code></a>(<var class="Fa">struct + proc *</var>, <var class="Fa">int</var>)</dt> + <dd>Scheduler-specific actions for + <a class="permalink" href="#sched_pstats"><code class="Fn" id="sched_pstats">sched_pstats</code></a>().</dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="Common_scheduler_functions"><a class="permalink" href="#Common_scheduler_functions">Common + scheduler functions</a></h1> +<dl class="Bl-tag"> + <dt id="sched_kpri"><var class="Ft">pri_t</var> + <a class="permalink" href="#sched_kpri"><code class="Fn">sched_kpri</code></a>(<var class="Fa">lwp_t + *</var>)</dt> + <dd>Scale a priority level to a kernel priority level, usually for an LWP that + is about to sleep.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">sched_pstats</code>(<var class="Fa">void *</var>)</dt> + <dd>Update process statistics and check CPU resource allocation.</dd> + <dt id="resched_cpu"><var class="Ft">inline void</var> + <a class="permalink" href="#resched_cpu"><code class="Fn">resched_cpu</code></a>(<var class="Fa">lwp_t + *</var>)</dt> + <dd>Arrange for a reschedule.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">setrunnable</code>(<var class="Fa">lwp_t *</var>)</dt> + <dd>Change process state to be runnable, placing it on a runqueue if it is in + memory, awakening the swapper otherwise.</dd> + <dt id="statclock"><var class="Ft">void</var> + <code class="Fn">schedclock</code>(<var class="Fa">lwp_t *</var>)</dt> + <dd>Scheduler clock. Periodically called from + <a class="permalink" href="#statclock"><code class="Fn">statclock</code></a>().</dd> + <dt id="sched_init"><var class="Ft">void</var> + <a class="permalink" href="#sched_init"><code class="Fn">sched_init</code></a>(<var class="Fa">void</var>)</dt> + <dd>Initialize callout for <code class="Fn">sched_pstats</code>() and call + <code class="Fn">sched_setup</code>() to initialize any other + scheduler-specific data.</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 <code class="Nm">CSF</code> programming interface is defined + within the file <span class="Pa">sys/sys/sched.h</span>.</p> +<p class="Pp">Functions common to all scheduler implementations are in + <span class="Pa">sys/kern/kern_synch.c</span>.</p> +<p class="Pp">The traditional 4.4BSD scheduler is implemented in + <span class="Pa">sys/kern/sched_4bsd.c</span>.</p> +<p class="Pp">The M2 scheduler is implemented in + <span class="Pa">sys/kern/sched_m2.c</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">mi_switch(9)</a>, <a class="Xr">preempt(9)</a>, + <a class="Xr">sched_4bsd(9)</a>, <a class="Xr">sched_m2(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">CSF</code> appeared in + <span class="Ux">NetBSD 5.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">CSF</code> was written by + <span class="An">Daniel Sieger</span> + ⟨dsieger@NetBSD.org⟩.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 27, 2014</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/curproc.9 3.html b/static/netbsd/man9/curproc.9 3.html new file mode 100644 index 00000000..17d4ed8c --- /dev/null +++ b/static/netbsd/man9/curproc.9 3.html @@ -0,0 +1,100 @@ +<table class="head"> + <tr> + <td class="head-ltitle">CURPROC(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">CURPROC(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">curcpu</code>, <code class="Nm">curlwp</code>, + <code class="Nm">curproc</code> — <span class="Nd">current processor, + thread, and process</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/proc.h</a>></code></p> +<p class="Pp"><var class="Ft">struct cpu_info *</var> + <br/> + <code class="Fn">curcpu</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Vt">struct proc *curproc</var>; + <br/> + <var class="Vt">struct lwp *curlwp</var>;</p> +<p class="Pp"><code class="In">#include + <<a class="In">sys/cpu.h</a>></code></p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">curcpu_stable</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The following retrieve the current CPU, process, and thread + (lightweight process, or LWP), respectively:</p> +<dl class="Bl-tag"> + <dt id="curcpu"><a class="permalink" href="#curcpu"><code class="Fn">curcpu</code></a>()</dt> + <dd>Returns a pointer to the <var class="Vt">struct cpu_info</var> structure + representing the CPU that the code calling it is running on. + <p class="Pp" id="curcpu~2">The value of + <a class="permalink" href="#curcpu~2"><code class="Fn">curcpu</code></a>() + is unstable and may be stale as soon as it is read unless the caller + prevents preemption by raising the IPL (<a class="Xr">spl(9)</a>, + <a class="Xr">mutex(9)</a>), by disabling preemption + (<a class="Xr">kpreempt_disable(9)</a>), or by binding the thread to its + CPU (<a class="Xr">curlwp_bind(9)</a>).</p> + <p class="Pp" id="curcpu_stable">The function + <a class="permalink" href="#curcpu_stable"><code class="Fn">curcpu_stable</code></a>() + can be used in assertions (<a class="Xr">KASSERT(9)</a>) to verify that + <code class="Fn">curcpu</code>() is stable in the current context. + <code class="Fn">curcpu_stable</code>() MUST NOT be used to make dynamic + decisions about whether to query <code class="Fn">curcpu</code>().</p> + </dd> + <dt id="curproc"><a class="permalink" href="#curproc"><code class="Dv">curproc</code></a></dt> + <dd>Yields a pointer to the <var class="Vt">struct proc</var> structure + representing the currently running process. + <p class="Pp">The value of <code class="Dv">curproc</code> is stable and + does not change during execution except in machine-dependent logic to + perform context switches, so it works like a global constant, not like a + stateful procedure.</p> + </dd> + <dt id="curlwp"><a class="permalink" href="#curlwp"><code class="Dv">curlwp</code></a></dt> + <dd>Yields a pointer to the <var class="Vt">struct lwp</var> structure + representing the currently running thread. + <p class="Pp">The value of <code class="Dv">curlwp</code> is stable and does + not change during execution except in machine-dependent logic to perform + context switches, so it works like a global constant, not like a + stateful procedure.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SOURCE_REFERENCES"><a class="permalink" href="#SOURCE_REFERENCES">SOURCE + REFERENCES</a></h1> +<p class="Pp">The + <a class="permalink" href="#curcpu~3"><code class="Fn" id="curcpu~3">curcpu</code></a>() + macro is defined in the machine-independent + <span class="Pa">machine/cpu.h</span>.</p> +<p class="Pp">The <code class="Dv">curproc</code> macro is defined in + <span class="Pa">sys/lwp.h</span>.</p> +<p class="Pp">The <code class="Dv">curlwp</code> macro has a machine-independent + definition in <span class="Pa">sys/lwp.h</span>, but it may be overridden by + <span class="Pa">machine/cpu.h</span>, and must be overridden on + architectures supporting multiprocessing and kernel preemption.</p> +<p class="Pp" id="curcpu_stable~2">The + <a class="permalink" href="#curcpu_stable~2"><code class="Fn">curcpu_stable</code></a>() + function is defined in <span class="Pa">kern/subr_cpu.c</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">cpu_number(9)</a>, + <a class="Xr">proc_find(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 8, 2023</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/ddc.9 3.html b/static/netbsd/man9/ddc.9 3.html new file mode 100644 index 00000000..18a348e1 --- /dev/null +++ b/static/netbsd/man9/ddc.9 3.html @@ -0,0 +1,96 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DDC(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">DDC(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">ddc</code> — <span class="Nd">VESA Display + Data Channel V2</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">dev/i2c/ddcvar.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">ddc_read_edid</code>(<var class="Fa">i2c_tag_t tag</var>, + <var class="Fa">uint8_t *dest</var>, <var class="Fa">size_t len</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#ddc_read_edid"><code class="Fn" id="ddc_read_edid">ddc_read_edid</code></a>() + reads a VESA Extended Display Identification Data block (EDID) via VESA + Display Data Channel (DDCv2). DDCv2 is a protocol for data exchange between + display devices (such as monitors and flat panels) and host machines using + an I2C bus.</p> +<p class="Pp">The <var class="Fa">tag</var> argument is a machine-dependent tag + used to specify the I2C bus on which the DDCv2 device is located. The + <var class="Fa">dest</var> argument is a pointer to a buffer where the EDID + data will be stored. The <var class="Fa">len</var> argument is the amount of + data to read into the buffer. (The buffer must be large enough.) Typically, + this value will be 128, which is the size of a normal EDID data block.</p> +<p class="Pp" id="edid_parse">Normally the EDID data block will be + post-processed with the + <a class="permalink" href="#edid_parse"><code class="Fn">edid_parse</code></a>() + function.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The <code class="Fn">ddc_read_edid</code>() function returns zero + on success, and non-zero otherwise.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1> +<p class="Pp">The <code class="Fn">ddc_read_edid</code>() function is part of + the <a class="Xr">ddc(4)</a> driver, and is only included in the kernel if + that driver is also included.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following code uses <code class="Fn">ddc_read_edid</code>() to + retrieve and print information about a monitor:</p> +<p class="Pp"></p> +<div class="Bd Li"> +<pre> struct edid_info info; + i2c_tag_t tag; + char buffer[128]; + + ... + /* initialize i2c tag... */ + ... + if ((ddc_read_edid(tag, buffer, 128) == 0) && + (edid_parse(buffer, &info) == 0)) + edid_print(info); + ...</pre> +</div> +<p class="Pp">Note that this must be called before the PCI bus is attached + during autoconfiguration.</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">ddc(4)</a>, <a class="Xr">edid(9)</a>, + <a class="Xr">iic(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">DDCv2 support was added in <span class="Ux">NetBSD 4.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Garrett D'Amore</span> + <<a class="Mt" href="mailto:gdamore@NetBSD.org">gdamore@NetBSD.org</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 11, 2006</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/delay.9 3.html b/static/netbsd/man9/delay.9 3.html new file mode 100644 index 00000000..8c4089bf --- /dev/null +++ b/static/netbsd/man9/delay.9 3.html @@ -0,0 +1,51 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DELAY(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">DELAY(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">delay</code>, <code class="Nm">DELAY</code> + — <span class="Nd">microsecond delay</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></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">delay</code>(<var class="Fa" style="white-space: nowrap;">unsigned + int us</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">DELAY</code>(<var class="Fa" style="white-space: nowrap;">unsigned + int us</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Wait approximately <var class="Fa">us</var> microseconds.</p> +<p class="Pp" id="DELAY">The delay is implemented as a machine loop, preventing + events other than interrupt handlers for unmasked interrupts to run. + <a class="permalink" href="#DELAY"><code class="Fn">DELAY</code></a>() is + reentrant (doesn't modify any global kernel or machine state) and is safe to + use in interrupt or process context.</p> +<p class="Pp">For long delays, condition variables should be considered, however + they can only be used from process context and their resolution is limited + by the system clock frequency.</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">condvar(9)</a>, <a class="Xr">hz(9)</a>, + <a class="Xr">kpause(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 20, 2011</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/dksubr.9 3.html b/static/netbsd/man9/dksubr.9 3.html new file mode 100644 index 00000000..631fd210 --- /dev/null +++ b/static/netbsd/man9/dksubr.9 3.html @@ -0,0 +1,300 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DKSUBR(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">DKSUBR(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">dk_softc</code>, <code class="Nm">dk_init</code>, + <code class="Nm">dk_attach</code>, <code class="Nm">dk_detach</code>, + <code class="Nm">dk_open</code>, <code class="Nm">dk_close</code>, + <code class="Nm">dk_size</code>, <code class="Nm">dk_dump</code>, + <code class="Nm">dk_ioctl</code>, <code class="Nm">dk_strategy</code>, + <code class="Nm">dk_strategy_defer</code>, + <code class="Nm">dk_strategy_pending</code>, + <code class="Nm">dk_start</code>, <code class="Nm">dk_done</code>, + <code class="Nm">dk_drain</code>, <code class="Nm">dk_discard</code>, + <code class="Nm">dk_getdefaultlabel</code>, + <code class="Nm">dk_getdisklabel</code> — <span class="Nd">disk + driver subroutines</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/bufq.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/disk.h</a>></code> + <br/> + <code class="In">#include <<a class="In">dev/dkvar.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_init</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, + <var class="Fa" style="white-space: nowrap;">device_t</var>, + <var class="Fa" style="white-space: nowrap;">int dtype</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_attach</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_detach</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_open</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">dev_t</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">int fmt</var>, + <var class="Fa" style="white-space: nowrap;">struct lwp *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_close</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">dev_t</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">int fmt</var>, + <var class="Fa" style="white-space: nowrap;">struct lwp *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_discard</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">dev_t</var>, + <var class="Fa" style="white-space: nowrap;">off_t pos</var>, + <var class="Fa" style="white-space: nowrap;">off_t len</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_size</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, + <var class="Fa" style="white-space: nowrap;">dev_t</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_dump</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">dev_t</var>, + <var class="Fa" style="white-space: nowrap;">daddr_t blkno</var>, + <var class="Fa" style="white-space: nowrap;">void *vav</var>, + <var class="Fa" style="white-space: nowrap;">size_t size</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_ioctl</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">dev_t</var>, + <var class="Fa" style="white-space: nowrap;">u_long cmd</var>, + <var class="Fa" style="white-space: nowrap;">void *data</var>, + <var class="Fa" style="white-space: nowrap;">int flag</var>, + <var class="Fa" style="white-space: nowrap;">struct lwp *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_strategy</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_strategy_defer</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_strategy_pending</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_start</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_done</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">dk_drain</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_getdefaultlabel</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, <var class="Fa" style="white-space: nowrap;">struct + disklabel *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dk_getdisklabel</code>(<var class="Fa" style="white-space: nowrap;">struct + dk_softc *</var>, + <var class="Fa" style="white-space: nowrap;">dev_t</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The disk driver subroutines provide common functionality for all + disk drivers to reduce the amount of replicated code. For many disk drivers, + their corresponding entry points can be made mostly stubs.</p> +<p class="Pp">The subroutines encapsulate data structures found in a driver's + softc into</p> +<div class="Bd Pp Li"> +<pre>struct dk_softc { + device_t sc_dev; + struct disk sc_dkdev; + struct bufq_state sc_bufq; + krndsource_t sc_rnd_source; +... +}</pre> +</div> +The <code class="Nm">dk_softc</code> structure therefore replaces the + <code class="Nm">device_t</code> member of the driver's softc struct. +<p class="Pp">The following is a brief description of each function in the + framework:</p> +<dl class="Bl-tag"> + <dt id="dk_init"><a class="permalink" href="#dk_init"><code class="Fn">dk_init</code></a>()</dt> + <dd>Initialize the dk_softc structure.</dd> + <dt id="dk_attach"><a class="permalink" href="#dk_attach"><code class="Fn">dk_attach</code></a>()</dt> + <dd>Attach framework after driver has attached the <a class="Xr">disk(9)</a> + subsystem, created a <a class="Xr">bufq(9)</a> and is ready to handle + I/O.</dd> + <dt id="dk_detach"><a class="permalink" href="#dk_detach"><code class="Fn">dk_detach</code></a>()</dt> + <dd>Undo dk_attach.</dd> + <dt id="dk_open"><a class="permalink" href="#dk_open"><code class="Fn">dk_open</code></a>()</dt> + <dd>Handles open steps for the <a class="Xr">disk(9)</a> framework, acquires + the disklabel and validates open parameters. The driver may provide the + <code class="Nm">d_firstopen</code> callback to handle initialization + steps.</dd> + <dt id="dk_close"><a class="permalink" href="#dk_close"><code class="Fn">dk_close</code></a>()</dt> + <dd>Handles close steps for the <a class="Xr">disk(9)</a> framework. The + driver may provide the <code class="Nm">d_lastclose</code> callback to + handle finalization steps. <code class="Nm">dk_open</code> and + <code class="Nm">dk_close</code> are serialized by the openlock + mutex.</dd> + <dt id="dk_discard"><a class="permalink" href="#dk_discard"><code class="Fn">dk_discard</code></a>()</dt> + <dd>Validates parameters, computes raw block numbers and passes these to the + <code class="Nm">d_discard</code> callback.</dd> + <dt id="dk_size"><a class="permalink" href="#dk_size"><code class="Fn">dk_size</code></a>()</dt> + <dd>Returns dump size information from the <a class="Xr">disklabel(9)</a> and + opens and closes the driver when necessary.</dd> + <dt id="dk_dump"><a class="permalink" href="#dk_dump"><code class="Fn">dk_dump</code></a>()</dt> + <dd>Validates parameters, computes raw block numbers and iterates over the + <code class="Nm">d_dumpblocks</code> callback in appropriate chunks + determined by the <code class="Nm">d_iosize</code> callback.</dd> + <dt id="dk_ioctl"><a class="permalink" href="#dk_ioctl"><code class="Fn">dk_ioctl</code></a>()</dt> + <dd>Handles the ioctls <code class="Dv">DIOCKLABEL</code>, + <code class="Dv">DIOCWLABEL</code>, <code class="Dv">DIOCGDEFLABEL</code>, + <code class="Dv">DIOCGSTRATEGY</code>, and + <code class="Dv">DIOCSSTRATEGY</code> and passes other disk ioctls through + the <a class="Xr">disk(9)</a> framework. Returns + <code class="Nm">ENOTTY</code> when an ioctl isn't implemented. This + routine is run as a fallback to handle commands that are not specific to + the driver.</dd> + <dt id="dk_strategy"><a class="permalink" href="#dk_strategy"><code class="Fn">dk_strategy</code></a>()</dt> + <dd>Validates parameters, computes raw block numbers, queues a buffer for I/O + and triggers queue processing by calling + <code class="Nm">dk_start</code>.</dd> + <dt id="dk_strategy_defer"><a class="permalink" href="#dk_strategy_defer"><code class="Fn">dk_strategy_defer</code></a>()</dt> + <dd>Alternative to <code class="Nm">dk_strategy</code> that only queues the + buffer. Drivers that implement a separate I/O thread can use + <code class="Nm">dk_strategy_defer</code> within their own strategy + routine and signal the thread through a private interface.</dd> + <dt id="dk_strategy_pending"><a class="permalink" href="#dk_strategy_pending"><code class="Fn">dk_strategy_pending</code></a>()</dt> + <dd>This function is called by an I/O thread to determine if work has been + queued by <code class="Nm">dk_strategy_defer</code>. The driver must then + call <code class="Nm">dk_start</code> to trigger queue processing.</dd> + <dt id="dk_start"><a class="permalink" href="#dk_start"><code class="Fn">dk_start</code></a>()</dt> + <dd>If <var class="Ar">bp !=</var> <code class="Dv">NULL</code> put it into + the queue. Run the <code class="Nm">d_diskstart</code> callback for every + buffer until the queue is empty or the callback returns + <code class="Nm">EAGAIN</code>. In the latter case, the buffer is saved + and issued on the next queue run. This also calls + <code class="Nm">disk_busy</code> accordingly to handle I/O metrics.</dd> + <dt id="dk_done"><a class="permalink" href="#dk_done"><code class="Fn">dk_done</code></a>()</dt> + <dd>Called by the driver when an I/O operation completed. + <code class="Nm">dk_done</code> logs errors, calls + <code class="Nm">disk_unbusy</code> to handle I/O metrics and collects + entropy for the <a class="Xr">cprng(9)</a>.</dd> + <dt id="dk_drain"><a class="permalink" href="#dk_drain"><code class="Fn">dk_drain</code></a>()</dt> + <dd>Aborts all queued I/O. This function must be called instead of + <a class="permalink" href="#bufq_drain"><code class="Fn" id="bufq_drain">bufq_drain</code></a>() + to cooperate with <code class="Nm">dk_start</code>.</dd> + <dt id="dk_getdefaultlabel"><a class="permalink" href="#dk_getdefaultlabel"><code class="Fn">dk_getdefaultlabel</code></a>()</dt> + <dd>Compute a common default disklabel for all disk drivers. Some drivers + provide device specific information or assign specific disk formats to + partitions. Such drivers may implement the <code class="Nm">d_label</code> + callback that is called by <code class="Nm">dk_getdefaultlabel</code> + after initializing the label with common values.</dd> + <dt id="dk_getdisklabel"><a class="permalink" href="#dk_getdisklabel"><code class="Fn">dk_getdisklabel</code></a>()</dt> + <dd>Read disklabel with machine dependent low-level function + <code class="Nm">readdisklabel</code> and do sanity checks.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="DRIVER_INTERFACE"><a class="permalink" href="#DRIVER_INTERFACE">DRIVER + INTERFACE</a></h1> +<p class="Pp">The driver needs to provide a common set of entry points that are + used by the disk driver subroutines and the <a class="Xr">disk(9)</a> + framework.</p> +<div class="Bd Pp Li"> +<pre>struct dkdriver { + void (*d_strategy)(struct buf *); + void (*d_minphys)(struct buf *); + int (*d_open)(dev_t, int, int, struct lwp *); + int (*d_close)(dev_t, int, int, struct lwp *); + int (*d_diskstart)(device_t, struct buf *); + void (*d_iosize)(device_t, int *); + int (*d_dumpblocks)(device_t, void *, daddr_t, int); + int (*d_lastclose)(device_t); + int (*d_discard)(device_t, off_t, off_t); + int (*d_firstopen)(device_t, dev_t, int, int); + void (*d_label)(device_t, struct disklabel *); +};</pre> +</div> +<dl class="Bl-tag"> + <dt id="d_strategy"><a class="permalink" href="#d_strategy"><code class="Fn">d_strategy</code></a>()</dt> + <dd>The driver strategy routine queues a single buffer for I/O and starts + queue processing as appropriate.</dd> + <dt id="d_minphys"><a class="permalink" href="#d_minphys"><code class="Fn">d_minphys</code></a>()</dt> + <dd>The driver minphys routine limits the buffer + <code class="Nm">b_bcount</code> to the maximum size for an I/O transfer + supported by the driver and hardware. It also calls + <code class="Nm">minphys</code> to apply the platform limit.</dd> + <dt id="d_open"><a class="permalink" href="#d_open"><code class="Fn">d_open</code></a>()</dt> + <dd>The driver open routine.</dd> + <dt id="d_close"><a class="permalink" href="#d_close"><code class="Fn">d_close</code></a>()</dt> + <dd>The driver close routine.</dd> + <dt id="d_diskstart"><a class="permalink" href="#d_diskstart"><code class="Fn">d_diskstart</code></a>()</dt> + <dd>Issues a single I/O request, called by + <code class="Nm">dk_start</code>.</dd> + <dt id="d_iosize"><a class="permalink" href="#d_iosize"><code class="Fn">d_iosize</code></a>()</dt> + <dd>Truncate I/O size to the driver limit. This is similar to + <code class="Nm">minphys</code> but operates on an integer value instead + of a buffer.</dd> + <dt id="d_dumpblocks"><a class="permalink" href="#d_dumpblocks"><code class="Fn">d_dumpblocks</code></a>()</dt> + <dd>Issue a single I/O requests, called by + <code class="Nm">dk_dump</code>.</dd> + <dt id="d_lastclose"><a class="permalink" href="#d_lastclose"><code class="Fn">d_lastclose</code></a>()</dt> + <dd>Private cleanup after last user is finished. Often used to flush write + caches.</dd> + <dt id="d_discard"><a class="permalink" href="#d_discard"><code class="Fn">d_discard</code></a>()</dt> + <dd>Issue a single I/O request to invalidate a disk region.</dd> + <dt id="d_firstopen"><a class="permalink" href="#d_firstopen"><code class="Fn">d_firstopen</code></a>()</dt> + <dd>Private initialization when first user opens the driver.</dd> +</dl> +</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">cgd(4)</a>, <a class="Xr">ld(4)</a>, + <a class="Xr">cprng(9)</a>, <a class="Xr">disk(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">The <span class="Ux">NetBSD</span> common disk driver subroutines + appeared in <span class="Ux">NetBSD 2.0</span> as a base for the + cryptographic disk driver and was extended to handle disk wedges in + <span class="Ux">NetBSD 4.0</span>. Most functionality provided by + <a class="Xr">ld(4)</a> was included and extended in <span class="Ux">NetBSD + 8.0</span> to support other disk drivers. The callback interface used by the + <a class="Xr">disk(9)</a> framework has been merged as well.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">November 28, 2016</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/dnv.9 b/static/netbsd/man9/dnv.9 new file mode 100644 index 00000000..95c54eb0 --- /dev/null +++ b/static/netbsd/man9/dnv.9 @@ -0,0 +1,117 @@ +.\" $NetBSD: dnv.9,v 1.2 2018/09/08 14:02:15 christos Exp $ +.\" +.\" Copyright (c) 2016 Adam Starak <starak.adam@gmail.com> +.\" 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: head/share/man/man9/dnv.9 315801 2017-03-23 05:54:07Z ngie $ +.\" +.Dd July 26, 2016 +.Dt DNV 9 +.Os +.Sh NAME +.Nm dnvlist_get , +.Nm dnvlist_take +.Nd "API for getting name/value pairs. Nonexistent pairs do not raise an error." +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/dnv.h +.Ft bool +.Fn dnvlist_get_bool "const nvlist_t *nvl" "const char *name" "bool defval" +.Ft uint64_t +.Fn dnvlist_get_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" +.Ft char * +.Fn dnvlist_get_string "const nvlist_t *nvl" "const char *name" "const char *defval" +.Ft nvlist_t * +.Fn dnvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" +.Ft int +.Fn dnvlist_get_descriptor "const nvlist_t *nvl" "const char *name" "int defval" +.Ft void * +.Fn dnvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" +.Ft bool +.Fn dnvlist_take_bool "const nvlist_t *nvl" "const char *name" "bool defval" +.Ft uint64_t +.Fn dnvlist_take_number "const nvlist_t *nvl" "const char *name" "uint64_t defval" +.Ft char * +.Fn dnvlist_take_string "const nvlist_t *nvl" "const char *name" "const char *defval" +.Ft nvlist_t * +.Fn dnvlist_take_nvlist "const nvlist_t *nvl" "const char *name" "nvlist_t *defval" +.Ft int +.Fn dnvlist_take_descriptor "const nvlist_t *nvl" "const char *name" "int defval" +.Ft void * +.Fn dnvlist_take_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" "void *defval" "size_t defsize" +.Sh DESCRIPTION +The +.Nm libnv +library permits easy management of name/value pairs and can send and receive +them over sockets. +For more information, also see +.Xr nv 9 . +.Pp +The +.Nm dnvlist_get +family of functions returns the value associated with the specified name. +If an element of the specified name does not exist, the function returns the +value provided in +.Fa defval . +Returned strings, nvlists, descriptors, binaries, or arrays must not be modified +by the user. +They still belong to the nvlist. +If the nvlist is in an error state, attempts to use any of these functions will +cause the program to abort. +.Pp +The +.Nm dnvlist_take +family of functions returns the value associated with the specified name and +removes the element from the nvlist. +If an element of the supplied name does not exist, the value provided in +.Nm defval +is returned. +When the value is a string, binary, or array value, the caller is +responsible for freeing returned memory with +.Fn free 3 . +When the value is an nvlist, the caller is responsible for destroying the +returned nvlist with +.Fn nvlist_destroy . +When the value is a descriptor, the caller is responsible for closing the +returned descriptor with +.Fn close 2 . +.Sh SEE ALSO +.Xr close 2 , +.Xr free 3 , +.Xr nv 9 +.Sh HISTORY +The +.Nm dnv +API appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm dnv +API was implemented by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. +This manual page was written by +.An Adam Starak Aq Mt starak.adam@gmail.com diff --git a/static/netbsd/man9/dopowerhooks.9 3.html b/static/netbsd/man9/dopowerhooks.9 3.html new file mode 100644 index 00000000..30034aef --- /dev/null +++ b/static/netbsd/man9/dopowerhooks.9 3.html @@ -0,0 +1,51 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DOPOWERHOOKS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">DOPOWERHOOKS(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">dopowerhooks</code> — <span class="Nd">run + all power hooks</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">dopowerhooks</code>(<var class="Fa" style="white-space: nowrap;">int + why</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><a class="permalink" href="#The"><i class="Em" id="The">The</i></a> + <code class="Nm">dopowerhooks</code> + <a class="permalink" href="#routine"><i class="Em" id="routine">routine is + deprecated.</i></a> + <a class="permalink" href="#Use"><i class="Em" id="Use">Use</i></a> + <a class="Xr">pmf_system_suspend(9)</a> + <a class="permalink" href="#instead."><i class="Em" id="instead.">instead.</i></a></p> +<p class="Pp" id="dopowerhooks">The + <a class="permalink" href="#dopowerhooks"><code class="Fn">dopowerhooks</code></a>() + function invokes all power hooks established using the + <a class="Xr">powerhook_establish(9)</a> function. When power is + disappearing the power hooks are called in reverse order, i.e., the power + hook established last will be called first. When power is restored they are + called normal order.</p> +<p class="Pp">This function is called from the <a class="Xr">apm(4)</a> driver + when a power change is detected.</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">powerhook_establish(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 11, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/doshutdownhooks.9 3.html b/static/netbsd/man9/doshutdownhooks.9 3.html new file mode 100644 index 00000000..4e531af1 --- /dev/null +++ b/static/netbsd/man9/doshutdownhooks.9 3.html @@ -0,0 +1,53 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DOSHUTDOWNHOOKS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">DOSHUTDOWNHOOKS(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">doshutdownhooks</code> — + <span class="Nd">run all shutdown hooks</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">doshutdownhooks</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><a class="permalink" href="#The"><i class="Em" id="The">The</i></a> + <code class="Nm">doshutdownhooks</code> + <a class="permalink" href="#routine"><i class="Em" id="routine">routine is + deprecated.</i></a> + <a class="permalink" href="#Use"><i class="Em" id="Use">Use</i></a> + <a class="Xr">pmf_system_shutdown(9)</a> + <a class="permalink" href="#instead."><i class="Em" id="instead.">instead.</i></a></p> +<p class="Pp" id="doshutdownhooks">The + <a class="permalink" href="#doshutdownhooks"><code class="Fn">doshutdownhooks</code></a>() + function invokes all shutdown hooks established using the + <a class="Xr">shutdownhook_establish(9)</a> function. Shutdown hooks are + called in reverse order, i.e., the shutdown hook established last will be + called first.</p> +<p class="Pp" id="cpu_reboot">This function is called from + <a class="permalink" href="#cpu_reboot"><code class="Fn">cpu_reboot</code></a>() + with interrupts turned off. It is called immediately before the system is + halted or rebooted, after file systems have been unmounted, after the clock + has been updated, and after a system dump has been done (if necessary).</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">cpu_reboot(9)</a>, + <a class="Xr">shutdownhook_establish(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 11, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/driver.9 3.html b/static/netbsd/man9/driver.9 3.html new file mode 100644 index 00000000..e33ab52e --- /dev/null +++ b/static/netbsd/man9/driver.9 3.html @@ -0,0 +1,249 @@ +<table class="head"> + <tr> + <td class="head-ltitle">DRIVER(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">DRIVER(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">driver</code> — + <span class="Nd">description of a device driver</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">static int</var> + <br/> + <code class="Fn">foo_match</code>(<var class="Fa" style="white-space: nowrap;">device_t + parent</var>, <var class="Fa" style="white-space: nowrap;">cfdata_t + match</var>, <var class="Fa" style="white-space: nowrap;">void + *aux</var>);</p> +<p class="Pp"><var class="Ft">static void</var> + <br/> + <code class="Fn">foo_attach</code>(<var class="Fa" style="white-space: nowrap;">device_t + parent</var>, <var class="Fa" style="white-space: nowrap;">device_t + self</var>, <var class="Fa" style="white-space: nowrap;">void + *aux</var>);</p> +<p class="Pp"><var class="Ft">static int</var> + <br/> + <code class="Fn">foo_detach</code>(<var class="Fa" style="white-space: nowrap;">device_t + self</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">static int</var> + <br/> + <code class="Fn">foo_activate</code>(<var class="Fa" style="white-space: nowrap;">device_t + self</var>, <var class="Fa" style="white-space: nowrap;">enum devact + act</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This page briefly describes the basic + <span class="Ux">NetBSD</span> autoconfiguration interface used by device + drivers. For a detailed overview of the autoconfiguration framework see + <a class="Xr">autoconf(9)</a>.</p> +<p class="Pp">Each device driver must present to the system a standard + autoconfiguration interface. This interface is provided by the + <var class="Vt">cfattach</var> structure. The interface to the driver is + constant and is defined statically inside the driver. For example, the + interface to driver ‘<code class="Li">foo</code>’ is defined + with:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>CFATTACH_DECL_NEW(foo, /* driver name */ + sizeof(struct foo_softc), /* size of instance data */ + foo_match, /* match/probe function */ + foo_attach, /* attach function */ + foo_detach, /* detach function */ + foo_activate); /* activate function */</pre> +</div> +<p class="Pp">For each device instance controlled by the driver, the + autoconfiguration framework allocates a block of memory to record + device-instance-specific driver variables. The size of this memory block is + specified by the second argument in the + <code class="Dv">CFATTACH_DECL</code> family of macros. The memory block is + referred to as the driver's <var class="Vt">softc</var> structure. The + <var class="Vt">softc</var> structure is only accessed within the driver, so + its definition is local to the driver. Nevertheless, the + <var class="Vt">softc</var> structure should adopt the standard + <span class="Ux">NetBSD</span> configuration and naming conventions. For + example, the <var class="Vt">softc</var> structure for driver + ‘<code class="Li">foo</code>’ is defined with:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct foo_softc { + device_t sc_dev; /* generic device info */ + /* device-specific state */ +};</pre> +</div> +<p class="Pp">If a driver has character device interfaces accessed from + userland, the driver must define the <var class="Vt">cdevsw</var> structure. + The structure is constant and is defined inside the driver. For example, the + <var class="Vt">cdevsw</var> structure for driver + ‘<code class="Li">foo</code>’ can be defined with:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>const struct cdevsw foo_cdevsw { + .d_open = fooopen, + .d_close = nullclose, + .d_read = fooread, + .d_write = nowrite, + .d_ioctl = fooioctl, + .d_stop = nostop, + .d_tty = notty, + .d_poll = foopoll, + .d_mmap = nommap, + .d_kqfilter = nokqfilter, + .d_discard = nodiscard, + .d_flag = D_OTHER | D_MPSAFE, +};</pre> +</div> +<p class="Pp">The structure variable must be named + <var class="Va">foo_cdevsw</var> by appending the letters + ‘<code class="Li">_cdevsw</code>’ to the driver's base name. + This convention is mandated by the autoconfiguration framework.</p> +<p class="Pp">If the driver ‘<code class="Li">foo</code>’ has also + block device interfaces, the driver must define the + <var class="Vt">bdevsw</var> structure. The structure is constant and is + defined inside the driver. For example, the <var class="Vt">bdevsw</var> + structure for driver ‘<code class="Li">foo</code>’ is defined + with:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>const struct bdevsw foo_bdevsw { + .d_open = fooopen, + .d_close = fooclose, + .d_strategy = foostrategy, + .d_ioctl = fooioctl, + .d_dump = nodump, + .d_psize = nosize, + .d_flag = D_DISK | D_MPSAFE, +};</pre> +</div> +<p class="Pp">The structure variable must be named + <var class="Va">foo_bdevsw</var> by appending the letters + ‘<code class="Li">_bdevsw</code>’ to the driver's base name. + This convention is mandated by the autoconfiguration framework.</p> +<p class="Pp" id="foo_probe">During system bootstrap, the autoconfiguration + framework searches the system for devices. For each device driver, its match + function is called (via its <var class="Vt">cfattach</var> structure) to + match the driver with a device instance. The match function is called with + three arguments. This first argument <var class="Fa">parent</var> is a + pointer to the driver's parent device structure. The second argument + <var class="Fa">match</var> is a pointer to a data structure describing the + autoconfiguration framework's understanding of the driver. Both the + <var class="Fa">parent</var> and <var class="Fa">match</var> arguments are + ignored by most drivers. The third argument <var class="Fa">aux</var> + contains a pointer to a structure describing a potential device-instance. It + is passed to the driver from the parent. The match function would type-cast + the <var class="Fa">aux</var> argument to its appropriate attachment + structure and use its contents to determine whether it supports the device. + Depending on the device hardware, the contents of the attachment structure + may contain “locators” to locate the device instance so that + the driver can probe it for its identity. If the probe process identifies + additional device properties, it may modify the members of the attachment + structure. For these devices, the <span class="Ux">NetBSD</span> convention + is to call the match routine + <a class="permalink" href="#foo_probe"><code class="Fn">foo_probe</code></a>() + instead of + <a class="permalink" href="#foo_match"><code class="Fn" id="foo_match">foo_match</code></a>() + to make this distinction clear. Either way, the 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. Generally, only a + single driver exists for a device, so the match function returns 1 for a + positive match.</p> +<p class="Pp" id="device_private">The autoconfiguration framework will call the + attach function (via its <var class="Vt">cfattach</var> structure) of the + driver which returns the highest value from its match function. The attach + function is called with three arguments. The attach function performs the + necessary process to initialise the device for operation. The first argument + <var class="Fa">parent</var> is a pointer to the driver's parent device + structure. The second argument <var class="Fa">self</var> is a pointer to + the driver's device structure. The device's <var class="Vt">softc</var> + structure can be obtained from it using the + <a class="permalink" href="#device_private"><code class="Fn">device_private</code></a>() + function (see <a class="Xr">disk(9)</a>). The third argument + <var class="Fa">aux</var> is a pointer to the attachment structure. The + <var class="Fa">parent</var> and <var class="Fa">aux</var> arguments are the + same as passed to the match function.</p> +<p class="Pp" id="config_interrupts">The driver's attach function is called + before system interrupts are enabled. If interrupts are required during + initialisation, then the attach function should make use of + <a class="permalink" href="#config_interrupts"><code class="Fn">config_interrupts</code></a>() + (see <a class="Xr">autoconf(9)</a>).</p> +<p class="Pp">Some devices can be removed from the system without requiring a + system reboot. The autoconfiguration framework calls the driver's detach + function (via its <var class="Vt">cfattach</var> structure) during device + detachment. If the device does not support detachment, then the driver does + not have to provide a detach function. The detach function is used to + relinquish resources allocated to the driver which are no longer needed. The + first argument <var class="Fa">self</var> is a pointer to the driver's + device structure. It is the same structure as passed to the attach function. + The second argument <var class="Fa">flags</var> contains detachment flags. + Valid values are <code class="Dv">DETACH_FORCE</code> (force detachment; + hardware gone) and <code class="Dv">DETACH_QUIET</code> (do not print a + notice).</p> +<p class="Pp">The activate function is used by some buses to notify drivers from + interrupt context when detachment is imminent, with + <var class="Fa">act</var> set to <code class="Dv">DVACT_DEACTIVATE</code>. + Currently only <a class="Xr">pcmcia(9)</a> and <a class="Xr">cardbus(9)</a> + use this. If the action is not supported the activate function should return + <code class="Er">EOPNOTSUPP</code>.</p> +<p class="Pp">Most drivers will want to make use of interrupt facilities. + Interrupt locators provided through the attachment structure should be used + to establish interrupts within the system. Generally, an interrupt interface + is provided by the parent. The interface will require a handler and a + driver-specific argument to be specified. This argument is usually a pointer + to the device-instance-specific softc structure. When a hardware interrupt + for the device occurs the handler is called with the argument. Interrupt + handlers should return 0 for “interrupt not for me”, 1 for + “I took care of it”, or -1 for “I guess it was mine, + but I wasn't expecting it”.</p> +<p class="Pp">For a driver to be compiled into the kernel, + <a class="Xr">config(1)</a> must be aware of its existence. This is done by + including an entry in files.<bus> in the directory containing the + driver. For example, the driver <var class="Ar">foo</var> attaching to bus + <var class="Ar">bar</var> with dependency on kernel module + <var class="Ar">baz</var> has the entry:</p> +<div class="Bd Pp Bd-indent Li"> +<pre><code class="Cd">device</code> <var class="Ar">foo</var><code class="Cd">:</code> <var class="Ar">baz</var> +<code class="Cd">attach</code> <var class="Ar">foo</var> <code class="Cm">at</code> <var class="Ar">bar</var> +<code class="Cd">file</code> <span class="Pa">dev/</span><var class="Ar">bar</var><span class="Pa">/</span><var class="Ar">foo</var><span class="Pa">.c</span> <var class="Ar">foo</var></pre> +</div> +<p class="Pp">An entry can now be added to the machine description file:</p> +<div class="Bd Pp Bd-indent"><var class="Ar">foo</var><code class="Cm">*</code> + <code class="Cm">at</code> + <var class="Ar">bar</var><code class="Cm">?</code></div> +<p class="Pp">For device interfaces of a driver to be compiled into the kernel, + <a class="Xr">config(1)</a> must be aware of its existence. This is done by + including an entry in + <span class="Pa">majors.</span>⟨<var class="Ar">arch</var>⟩. + For example, the driver <var class="Ar">foo</var> with character device + interfaces, a character major device number <var class="Ar">cmaj</var>, + block device interfaces, a block device major number + <var class="Ar">bmaj</var> and dependency on kernel module + <var class="Ar">baz</var> has the entry:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">device-major</code> + <var class="Ar">foo</var> <code class="Cm">char</code> + <var class="Ar">cmaj</var> <code class="Cm">block</code> + <var class="Ar">bmaj</var> <var class="Ar">baz</var></div> +<p class="Pp">For a detailed description of the machine description file and the + “device definition” language see + <a class="Xr">config(9)</a>.</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">autoconf(9)</a>, + <a class="Xr">config(9)</a>, <a class="Xr">devsw(9)</a>, + <a class="Xr">pmf(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 30, 2017</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/errno.9 3.html b/static/netbsd/man9/errno.9 3.html new file mode 100644 index 00000000..3942db0e --- /dev/null +++ b/static/netbsd/man9/errno.9 3.html @@ -0,0 +1,101 @@ +<table class="head"> + <tr> + <td class="head-ltitle">ERRNO(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">ERRNO(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">errno</code> — <span class="Nd">kernel + internal error numbers</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/errno.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This section provides an overview of the error numbers used + internally by the kernel and indicate neither success nor failure. These + error numbers are not returned to userland code.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">Kernel functions that indicate success or failure by means of + either 0 or an <a class="Xr">errno(2)</a> value sometimes have a need to + indicate that “special” handling is required at an upper layer + or, in the case of <a class="Xr">ioctl(2)</a> processing, that + “nothing was wrong but the request was not handled”. To handle + these cases, some negative <a class="Xr">errno(2)</a> values are defined + which are handled by the kernel before returning a different + <a class="Xr">errno(2)</a> value to userland or simply zero.</p> +<p class="Pp" id="not">The following is a list of the defined names and their + meanings as given in + <code class="In"><<a class="In">errno.h</a>></code>. It is important + to note that the value -1 is + <a class="permalink" href="#not"><i class="Em">not</i></a> used, since it is + commonly used to indicate generic failure and leaves it up to the caller to + determine the action to take.</p> +<dl class="Bl-hang"> + <dt id="Modify"><code class="Er">-2 EJUSTRETURN</code> + <a class="permalink" href="#Modify"><i class="Em">Modify regs, just + return</i></a>.</dt> + <dd>No more work is required and the function should just return.</dd> + <dt id="Restart"><code class="Er">-3 ERESTART</code> + <a class="permalink" href="#Restart"><i class="Em">Restart + syscall</i></a>.</dt> + <dd>The system call should be restarted. This typically means that the machine + dependent system call trap code will reposition the process's instruction + pointer or program counter to re-execute the current system call with no + other work required.</dd> + <dt id="Operation"><code class="Er">-4 EPASSTHROUGH</code> + <a class="permalink" href="#Operation"><i class="Em">Operation not handled + by this layer</i></a>.</dt> + <dd>The operation was not handled and should be passed through to another + layer. This often occurs when processing <a class="Xr">ioctl(2)</a> + requests since lower layer processing may not handle something that + subsequent code at a higher level will.</dd> + <dt id="Duplicate"><code class="Er">-5 EDUPFD</code> + <a class="permalink" href="#Duplicate"><i class="Em">Duplicate file + descriptor.</i></a></dt> + <dd>This error is returned from the device open routine indicating that the + <var class="Ar">l_dupfd</var> field contains the file descriptor + information to be returned to the caller, instead of the file descriptor + that has been opened already. This error is used by cloning device + multiplexors. Cloning device multiplexors open a new file descriptor and + associate that file descriptor with the appropriate cloned device. They + set <var class="Ar">l_dupfd</var> to that new file descriptor and return + <code class="Er">EDUPFD</code>. <a class="Xr">vn_open(9)</a> takes the + file descriptor pointed to by <var class="Ar">l_dupfd</var> and arranges + for it to be copied to the file descriptor that the open call will + return.</dd> + <dt id="Move"><code class="Er">-6 EMOVEFD</code> + <a class="permalink" href="#Move"><i class="Em">Move file + descriptor.</i></a></dt> + <dd>This error is similar to <code class="Er">EDUPFD</code> except that the + file descriptor in <var class="Ar">l_dupfd</var> is closed after it has + been copied.</dd> +</dl> +</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">errno(2)</a>, <a class="Xr">ioctl(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">An <code class="Nm">errno</code> manual page appeared in + <span class="Ux">Version 6 AT&T UNIX</span>. This + <code class="Nm">errno</code> manual page appeared in + <span class="Ux">NetBSD 3.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 3, 2004</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/evcnt.9 3.html b/static/netbsd/man9/evcnt.9 3.html new file mode 100644 index 00000000..5fbf24af --- /dev/null +++ b/static/netbsd/man9/evcnt.9 3.html @@ -0,0 +1,257 @@ +<table class="head"> + <tr> + <td class="head-ltitle">EVCNT(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">EVCNT(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">evcnt</code>, + <code class="Nm">evcnt_attach_dynamic</code>, + <code class="Nm">evcnt_attach_static</code>, + <code class="Nm">evcnt_detach</code> — <span class="Nd">generic event + counter 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/evcnt.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">evcnt_attach_dynamic</code>(<var class="Fa" style="white-space: nowrap;">struct + evcnt *ev</var>, <var class="Fa" style="white-space: nowrap;">int + type</var>, <var class="Fa" style="white-space: nowrap;">const struct evcnt + *parent</var>, <var class="Fa" style="white-space: nowrap;">const char + *group</var>, <var class="Fa" style="white-space: nowrap;">const char + *name</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">evcnt_attach_static</code>(<var class="Fa" style="white-space: nowrap;">struct + evcnt *ev</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">evcnt_detach</code>(<var class="Fa" style="white-space: nowrap;">struct + evcnt *ev</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <span class="Ux">NetBSD</span> generic event counter framework + is designed to provide a flexible and hierarchical event counting facility, + which is useful for tracking system events (including device + interrupts).</p> +<p class="Pp" id="evcnt">The fundamental component of this framework is the + <a class="permalink" href="#evcnt"><i class="Em">evcnt</i></a> structure. + Its user-accessible fields are:</p> +<div class="Bd Pp Li"> +<pre>struct evcnt { + uint64_t ev_count; /* how many have occurred */ + TAILQ_ENTRY(evcnt) ev_list; /* entry on list of all counters */ + unsigned char ev_type; /* counter type; see below */ + unsigned char ev_grouplen; /* 'group' len, excluding NUL */ + unsigned char ev_namelen; /* 'name' len, excluding NUL */ + const struct evcnt *ev_parent; /* parent, for hierarchical ctrs */ + const char *ev_group; /* name of group */ + const char *ev_name; /* name of specific event */ +};</pre> +</div> +<p class="Pp">The system maintains a global linked list of all active event + counters. This list, called <code class="Nm">allevents</code>, may grow or + shrink over time as event counters are dynamically added to and removed from + the system.</p> +<p class="Pp">Each event counter is marked (in the <var class="Fa">ev_type</var> + field) with the type of event being counted. The following types are + currently defined:</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt id="EVCNT_TYPE_MISC"><a class="permalink" href="#EVCNT_TYPE_MISC"><code class="Ev">EVCNT_TYPE_MISC</code></a></dt> + <dd>Miscellaneous; doesn't fit into one of the other types.</dd> + <dt id="EVCNT_TYPE_INTR"><a class="permalink" href="#EVCNT_TYPE_INTR"><code class="Ev">EVCNT_TYPE_INTR</code></a></dt> + <dd>Interrupt counter, reported by <code class="Ic">vmstat -i</code>.</dd> + <dt id="EVCNT_TYPE_TRAP"><a class="permalink" href="#EVCNT_TYPE_TRAP"><code class="Ev">EVCNT_TYPE_TRAP</code></a></dt> + <dd>Processor trap style events.</dd> +</dl> +</div> +<p class="Pp">Each event counter also has a group name + (<var class="Fa">ev_group</var>) and an event name + (<var class="Fa">ev_name</var>) which are used to identify the counter. The + group name may be shared by a set of counters. For example, device interrupt + counters would use the name of the device whose interrupts are being counted + as the group name. The counter name is meant to distinguish the counter from + others in its group (and need not be unique across groups). Both names + should be understandable by users, since they are printed by commands like + <a class="Xr">vmstat(1)</a>. The constant + <code class="Dv">EVCNT_STRING_MAX</code> is defined to be the maximum group + or event name length in bytes (including the trailing + <code class="Dv">NUL</code>). In the current implementation it is 256.</p> +<p class="Pp">To support hierarchical tracking of events, each event counter can + name a “parent” event counter. For instance, interrupt + dispatch code could have an event counter per interrupt line, and devices + could each have counters for the number of interrupts that they were + responsible for causing. In that case, the counter for a device on a given + interrupt line would have the line's counter as its parent. The value + <code class="Dv">NULL</code> is used to indicate that a counter has no + parent. A counter's parent must be attached before the counter is attached, + and detached after the counter is detached.</p> +<p class="Pp" id="EVCNT_INITIALIZER">The + <a class="permalink" href="#EVCNT_INITIALIZER"><code class="Fn">EVCNT_INITIALIZER</code></a>() + macro can be used to provide a static initializer for an event counter + structure. It is invoked as + <code class="Fn">EVCNT_INITIALIZER</code>(<var class="Fa">type</var>, + <var class="Fa">parent</var>, <var class="Fa">group</var>, + <var class="Fa">name</var>), and its arguments will be placed into the + corresponding fields of the event counter structure it is initializing. The + <var class="Fa">group</var> and <var class="Fa">name</var> arguments must be + constant strings.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<p class="Pp">The following is a brief description of each function in the + framework:</p> +<dl class="Bl-tag"> + <dt id="evcnt_attach_dynamic"><a class="permalink" href="#evcnt_attach_dynamic"><code class="Fn">evcnt_attach_dynamic</code></a>(<var class="Fa">ev</var>, + <var class="Fa">type</var>, <var class="Fa">parent</var>, + <var class="Fa">group</var>, <var class="Fa">name</var>)</dt> + <dd>Attach the event counter structure pointed to by <var class="Fa">ev</var> + to the system event list. The event counter is cleared and its fields + initialized using the arguments to the function call. The contents of the + remaining elements in the structure (e.g., the name lengths) are + calculated, and the counter is added to the system event list. + <p class="Pp">The strings specified as the group and counter names must + persist (with the same value) throughout the life of the event counter; + they are referenced by, not copied into, the counter.</p> + </dd> + <dt id="evcnt_attach_static"><a class="permalink" href="#evcnt_attach_static"><code class="Fn">evcnt_attach_static</code></a>(<var class="Fa">ev</var>)</dt> + <dd>Attach the statically-initialized event counter structure pointed to by + <var class="Fa">ev</var> to the system event list. The event counter is + assumed to be statically initialized using the + <code class="Fn">EVCNT_INITIALIZER</code>() macro. This function simply + calculates structure elements' values as appropriate (e.g., the string + lengths), and adds the counter to the system event list.</dd> + <dt id="evcnt_detach"><a class="permalink" href="#evcnt_detach"><code class="Fn">evcnt_detach</code></a>(<var class="Fa">ev</var>)</dt> + <dd>Detach the event counter structure pointed to by <var class="Fa">ev</var> + from the system event list.</dd> +</dl> +<p class="Pp">Note that no method is provided to increment the value of an event + counter. Code incrementing an event counter should do so by directly + accessing its <var class="Fa">ev_count</var> field in a manner that is known + to be safe. For instance, additions to a device's event counters in the + interrupt handler for that device will often be safe without additional + protection (because interrupt handler entries for a given device have to be + serialized). However, for other uses of event counters, additional locking + or use of machine-dependent atomic operation may be appropriate. (The + overhead of using a mechanism that is guaranteed to be safe to increment + every counter, regardless of actual need for such a mechanism where the + counter is being incremented, would be too great. On some systems, it might + involve a global lock and several function calls.)</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">This section includes a description on basic use of the framework + and example usage of its functions.</p> +<p class="Pp">Device drivers can use the + <code class="Fn">evcnt_attach_dynamic</code>() and + <code class="Fn">evcnt_detach</code>() functions to manage device-specific + event counters. Statically configured system modules can use + <code class="Fn">evcnt_attach_static</code>() to configure global event + counters. Similarly, loadable modules can use + <code class="Fn">evcnt_attach_static</code>() to configure their global + event counters, <code class="Fn">evcnt_attach_dynamic</code>() to attach + device-specific event counters, and <code class="Fn">evcnt_detach</code>() + to detach all counters when being unloaded.</p> +<p class="Pp">Device drivers that wish to use the generic event counter + framework should place event counter structures in their + “softc” structures. For example, to keep track of the number + of interrupts for a given device (broken down further into “device + readable” and “device writable” interrupts) a device + driver might use:</p> +<div class="Bd Pp Li"> +<pre>struct foo_softc { + [ . . . ] + struct evcnt sc_ev_intr; /* interrupt count */ + struct evcnt sc_ev_intr_rd; /* 'readable' interrupt count */ + struct evcnt sc_ev_intr_wr; /* 'writable' interrupt count */ + [ . . . ] +};</pre> +</div> +<p class="Pp">In the device attach function, those counters would be registered + with the system using the <code class="Fn">evcnt_attach_dynamic</code>() + function, using code like:</p> +<div class="Bd Pp Li"> +<pre>void +fooattach(device_t parent, device_t self, void *aux) +{ + struct foo_softc *sc = device_private(self); + + [ . . . ] + + /* Initialize and attach event counters. */ + evcnt_attach_dynamic(&sc->sc_ev, EVCNT_TYPE_INTR, + NULL, device_xname(self), "intr"); + evcnt_attach_dynamic(&sc->sc_ev_rd, EVCNT_TYPE_INTR, + &sc->sc_ev, device_xname(self), "intr rd"); + evcnt_attach_dynamic(&sc->sc_ev_wr, EVCNT_TYPE_INTR, + &sc->sc_ev, device_xname(self), "intr wr"); + + [ . . . ] +}</pre> +</div> +<p class="Pp">If the device can be detached from the system, its detach function + should invoke <code class="Fn">evcnt_detach</code>() on each attached + counter (making sure to detach any “parent” counters only + after detaching all children).</p> +<p class="Pp">Code like the following might be used to initialize a static event + counter (in this example, one used to track CPU alignment traps):</p> +<div class="Bd Pp Li"> +<pre> struct evcnt aligntrap_ev = EVCNT_INITIALIZER(EVCNT_TYPE_MISC, + NULL, "cpu", "aligntrap")</pre> +</div> +<p class="Pp">To attach this event counter, code like the following could be + used:</p> +<div class="Bd Pp Li"> +<pre> evcnt_attach_static(&aligntrap_ev);</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The event counter framework itself is implemented within the file + <span class="Pa">sys/kern/subr_evcnt.c</span>. Data structures and function + prototypes for the framework are located in + <span class="Pa">sys/sys/device.h</span>.</p> +<p class="Pp">Event counters are used throughout the system.</p> +<p class="Pp">The <a class="Xr">vmstat(1)</a> source file + <span class="Pa">usr.bin/vmstat/vmstat.c</span> shows an example of how to + access event counters from user programs.</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">vmstat(1)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">A set of interrupt counter interfaces with similar names to the + interfaces in the <span class="Ux">NetBSD</span> generic event counter + framework appeared as part of the new autoconfiguration system in + <span class="Ux">4.4BSD</span>. Those interfaces were never widely adopted + in <span class="Ux">NetBSD</span> because of limitations in their + applicability. (Their use was limited to non-hierarchical, dynamically + attached device interrupt counters.) The <span class="Ux">NetBSD</span> + generic event counter framework first appeared in <span class="Ux">NetBSD + 1.5</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <span class="Ux">NetBSD</span> generic event counter framework + was designed and implemented by <span class="An">Chris Demetriou</span> + ⟨cgd@NetBSD.org⟩.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 14, 2011</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/example.9 b/static/netbsd/man9/example.9 new file mode 100644 index 00000000..02db18cb --- /dev/null +++ b/static/netbsd/man9/example.9 @@ -0,0 +1,13 @@ +# $NetBSD: example.9,v 1.1.1.1 2012/03/23 21:20:15 christos Exp $ +# +# drop all packets without IP security options +# +block in all +pass in all with opt sec +# +# only allow packets in and out on le1 which are top secret +# +block out on le1 all +pass out on le1 all with opt sec-class topsecret +block in on le1 all +pass in on le1 all with opt sec-class topsecret diff --git a/static/netbsd/man9/fileassoc.9 3.html b/static/netbsd/man9/fileassoc.9 3.html new file mode 100644 index 00000000..d4c28048 --- /dev/null +++ b/static/netbsd/man9/fileassoc.9 3.html @@ -0,0 +1,338 @@ +<table class="head"> + <tr> + <td class="head-ltitle">FILEASSOC(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">FILEASSOC(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">fileassoc</code> — + <span class="Nd">in-kernel, file system independent, file meta-data + association</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/fileassoc.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_register</code>(<var class="Fa" style="white-space: nowrap;">const + char *name</var>, + <var class="Fa" style="white-space: nowrap;">fileassoc_cleanup_cb_t + cleanup_cb</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t + *result</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_deregister</code>(<var class="Fa" style="white-space: nowrap;">fileassoc_t + id</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">fileassoc_lookup</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t + id</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_table_delete</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_table_clear</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t + id</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_table_run</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t + id</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_cb_t + cb</var>, <var class="Fa" style="white-space: nowrap;">void + *cookie</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_file_delete</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_add</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t + id</var>, <var class="Fa" style="white-space: nowrap;">void + *data</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fileassoc_clear</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">fileassoc_t + id</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">fileassoc</code> KPI allows association of + meta-data with files independent of file system support for such elaborate + meta-data.</p> +<p class="Pp">When plugging a new fileassoc to the system, a developer can + specify private data to be associated with every file, as well as + (potentially different) private data to be associated with every file system + mount.</p> +<p class="Pp">For example, a developer might choose to associate a custom ACL + with every file, and a count of total files with ACLs with the mount.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="KERNEL_PROGRAMMING_INTERFACE"><a class="permalink" href="#KERNEL_PROGRAMMING_INTERFACE">KERNEL + PROGRAMMING INTERFACE</a></h1> +<p class="Pp">Designed with simplicity in mind, the + <code class="Nm">fileassoc</code> KPI usually accepts four different types + of parameters to the most commonly used routines:</p> +<dl class="Bl-tag"> + <dt><var class="Ft">struct mount *</var> <var class="Ar">mp</var></dt> + <dd>Describing a mount on which to take action.</dd> + <dt><var class="Ft">struct vnode *</var> <var class="Ar">vp</var></dt> + <dd>Describing a file on which to take action.</dd> + <dt id="fileassoc_register"><var class="Ft">fileassoc_t</var> + <var class="Ar">id</var></dt> + <dd>Describing an id, as returned from a successful call to + <a class="permalink" href="#fileassoc_register"><code class="Fn">fileassoc_register</code></a>().</dd> + <dt><var class="Ft">void *</var> <var class="Ar">data</var></dt> + <dd>Describing a custom private data block, attached to either a file or a + mount.</dd> +</dl> +<p class="Pp">Before using the <code class="Nm">fileassoc</code> KPI it is + important to keep in mind that the interface provides memory management only + for <code class="Nm">fileassoc</code> internal memory. Any additional memory + stored in the tables (such as private data structures used by custom + fileassocs) should be allocated and freed by the developer.</p> +<p class="Pp" id="fileassoc_register~2"><code class="Nm">fileassoc</code> + provides the ability to specify a “cleanup” routine to + <a class="permalink" href="#fileassoc_register~2"><code class="Fn">fileassoc_register</code></a>() + (see below) to be called whenever an entry for a file or a mount is + deleted.</p> +<section class="Ss"> +<h2 class="Ss" id="REGISTRATION_AND_DEREGISTRATION_ROUTINES"><a class="permalink" href="#REGISTRATION_AND_DEREGISTRATION_ROUTINES">REGISTRATION + AND DEREGISTRATION ROUTINES</a></h2> +<p class="Pp">These routines allow a developer to allocate a + <code class="Nm">fileassoc</code> slot to be used for private data.</p> +<dl class="Bl-tag"> + <dt><code class="Fn">fileassoc_register</code>(<var class="Fa">name</var>, + <var class="Fa">cleanup_cb</var>, <var class="Fa">result</var>)</dt> + <dd>Registers a new fileassoc as <var class="Ar">name</var>, and returns a + <var class="Ft">fileassoc_t</var> via <var class="Fa">result</var> to be + used as identifier in subsequent calls to the + <code class="Nm">fileassoc</code> subsystem. + <p class="Pp" id="fileassoc_register~3"><a class="permalink" href="#fileassoc_register~3"><code class="Fn">fileassoc_register</code></a>() + returns zero on success. Otherwise, an error number will be + returned.</p> + <p class="Pp">If <var class="Ar">cleanup_cb</var> is not + <code class="Dv">NULL</code>, it will be called during delete/clear + operations (see routines below) with indication whether the passed data + is file- or mount-specific.</p> + <p class="Pp"><var class="Ar">cleanup_cb</var> should be a function + receiving a <var class="Ft">void *</var> and returning + <var class="Ft">void</var>. See the + <a class="Sx" href="#EXAMPLES">EXAMPLES</a> section for + illustration.</p> + </dd> + <dt id="fileassoc_deregister"><a class="permalink" href="#fileassoc_deregister"><code class="Fn">fileassoc_deregister</code></a>(<var class="Fa">id</var>)</dt> + <dd>Deregisters a <code class="Nm">fileassoc</code> whose id is + <var class="Ar">id</var>. + <p class="Pp" id="fileassoc_deregister~2">Note that calling + <a class="permalink" href="#fileassoc_deregister~2"><code class="Fn">fileassoc_deregister</code></a>() + only frees the associated slot in the <code class="Nm">fileassoc</code> + subsystem. It is up to the developer to take care of garbage + collection.</p> + </dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="LOOKUP_ROUTINES"><a class="permalink" href="#LOOKUP_ROUTINES">LOOKUP + ROUTINES</a></h2> +<p class="Pp">These routines allow lookup of <code class="Nm">fileassoc</code> + mounts, files, and private data attached to them.</p> +<dl class="Bl-tag"> + <dt id="fileassoc_lookup"><a class="permalink" href="#fileassoc_lookup"><code class="Fn">fileassoc_lookup</code></a>(<var class="Fa">vp</var>, + <var class="Fa">id</var>)</dt> + <dd>Returns the private data for the file/id combination or + <code class="Dv">NULL</code> if not found.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="MOUNT-WIDE_ROUTINES"><a class="permalink" href="#MOUNT-WIDE_ROUTINES">MOUNT-WIDE + ROUTINES</a></h2> +<dl class="Bl-tag"> + <dt id="fileassoc_table_delete"><a class="permalink" href="#fileassoc_table_delete"><code class="Fn">fileassoc_table_delete</code></a>(<var class="Fa">mp</var>)</dt> + <dd>Deletes a fileassoc table for <var class="Ar">mp</var>.</dd> + <dt id="fileassoc_table_clear"><a class="permalink" href="#fileassoc_table_clear"><code class="Fn">fileassoc_table_clear</code></a>(<var class="Fa">mp</var>, + <var class="Fa">id</var>)</dt> + <dd>Clear all table entries for <var class="Ar">fileassoc</var> from + <var class="Ar">mp</var>. + <p class="Pp">If specified, the fileassoc's “cleanup routine” + will be called with a pointer to the private data structure.</p> + </dd> + <dt id="fileassoc_table_run"><a class="permalink" href="#fileassoc_table_run"><code class="Fn">fileassoc_table_run</code></a>(<var class="Fa">mp</var>, + <var class="Fa">id</var>, <var class="Fa">cb</var>, + <var class="Fa">cookie</var>)</dt> + <dd>For each entry for <var class="Ar">id</var>, call <var class="Ar">cb</var> + with the entry being the first argument, and <var class="Ar">cookie</var> + being the second argument. + <p class="Pp"><var class="Ar">cb</var> is a function returning + <var class="Ft">void</var> and receiving two <var class="Ft">void + *</var> parameters.</p> + </dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="FILE-SPECIFIC_ROUTINES"><a class="permalink" href="#FILE-SPECIFIC_ROUTINES">FILE-SPECIFIC + ROUTINES</a></h2> +<dl class="Bl-tag"> + <dt id="fileassoc_file_delete"><a class="permalink" href="#fileassoc_file_delete"><code class="Fn">fileassoc_file_delete</code></a>(<var class="Fa">vp</var>)</dt> + <dd>Delete the fileassoc entries for <var class="Ar">vp</var>. + <p class="Pp">If specified, the “cleanup routines” of all + fileassoc types added will be called with a pointer to the corresponding + private data structure and indication of + <code class="Dv">FILEASSOC_CLEANUP_FILE</code>.</p> + </dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="FILEASSOC-SPECIFIC_ROUTINES"><a class="permalink" href="#FILEASSOC-SPECIFIC_ROUTINES">FILEASSOC-SPECIFIC + ROUTINES</a></h2> +<dl class="Bl-tag"> + <dt id="fileassoc_add"><a class="permalink" href="#fileassoc_add"><code class="Fn">fileassoc_add</code></a>(<var class="Fa">vp</var>, + <var class="Fa">id</var>, <var class="Fa">data</var>)</dt> + <dd>Add private data in <var class="Ar">data</var> for + <var class="Ar">vp</var>, for the fileassoc specified by + <var class="Ar">id</var>. + <p class="Pp">If a table for the mount-point <var class="Ar">vp</var> is on + doesn't exist, one will be created automatically. + <code class="Nm">fileassoc</code> manages internally the optimal table + sizes as tables are modified.</p> + </dd> + <dt id="fileassoc_clear"><a class="permalink" href="#fileassoc_clear"><code class="Fn">fileassoc_clear</code></a>(<var class="Fa">vp</var>, + <var class="Fa">id</var>)</dt> + <dd>Clear the private data for <var class="Ar">vp</var>, for the fileassoc + specified by <var class="Ar">id</var>. + <p class="Pp">If specified, the fileassoc's “cleanup routine” + will be called with a pointer to the private data structure and + indication of <code class="Dv">FILEASSOC_CLEANUP_FILE</code>.</p> + </dd> +</dl> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following code examples should give you a clue on using + <code class="Nm">fileassoc</code> for your purposes.</p> +<p class="Pp">First, we'll begin with registering a new id. We need to do that + to save a slot for private data storage with each mount and/or file:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>fileassoc_t myhook_id; +int error; + +error = fileassoc_register("my_hook", myhook_cleanup, &myhook_id); +if (error != 0) + ...handle error...</pre> +</div> +<p class="Pp">In the above example we pass a + <code class="Fn">myhook_cleanup</code>() routine. It could look something + like this:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>void +myhook_cleanup(void *data) +{ + + printf("Myhook: Removing entry for file.\n"); + ...handle file entry removal... + free(data, M_TEMP); +}</pre> +</div> +<p class="Pp">Another useful thing would be to add our private data to a file. + For example, let's assume we keep a custom ACL with each file:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>int +myhook_acl_add(struct vnode *vp, struct myhook_acl *acl) +{ + int error; + + error = fileassoc_add(vp, myhook_id, acl); + if (error) { + printf("Myhook: Could not add ACL.\n"); + ...handle error... + } + + printf("Myhook: Added ACL.\n"); + + return (0); +}</pre> +</div> +<p class="Pp">Adding an entry will override any entry that previously + exists.</p> +<p class="Pp">Whatever your plug is, eventually you'll want to access the + private data you store with each file. To do that you can use the + following:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>int +myhook_acl_access(struct vnode *vp, int access_flags) +{ + struct myhook_acl *acl; + + acl = fileassoc_lookup(vp, myhook_id); + if (acl == NULL) + return (0); + + error = myhook_acl_eval(acl, access_flags); + if (error) { + printf("Myhook: Denying access based on ACL decision.\n"); + return (error); + } + + return (0); +}</pre> +</div> +<p class="Pp">And, in some cases, it may be desired to remove private data + associated with an file:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>int error; + +error = fileassoc_clear(vp, myhook_id); +if (error) { + printf("Myhook: Error occurred during fileassoc removal.\n"); + ...handle error... +}</pre> +</div> +<p class="Pp">As mentioned previously, the call to + <code class="Fn">fileassoc_clear</code>() will result in a call to the + “cleanup routine” specified in the initial call to + <code class="Fn">fileassoc_register</code>().</p> +<p class="Pp">The above should be enough to get you started.</p> +<p class="Pp">For example usage of <code class="Nm">fileassoc</code>, see the + Veriexec code.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">fileassoc</code> is implemented within + <span class="Pa">src/sys/kern/kern_fileassoc.c</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">veriexec(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">fileassoc</code> KPI first appeared in + <span class="Ux">NetBSD 4.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Elad Efrat</span> + <<a class="Mt" href="mailto:elad@NetBSD.org">elad@NetBSD.org</a>> + <br/> + <span class="An">Brett Lymn</span> + <<a class="Mt" href="mailto:blymn@NetBSD.org">blymn@NetBSD.org</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 1, 2016</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/firmload.9 3.html b/static/netbsd/man9/firmload.9 3.html new file mode 100644 index 00000000..b402b742 --- /dev/null +++ b/static/netbsd/man9/firmload.9 3.html @@ -0,0 +1,151 @@ +<table class="head"> + <tr> + <td class="head-ltitle">FIRMLOAD(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">FIRMLOAD(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">firmload</code> — + <span class="Nd">Firmware loader API for device drivers</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">dev/firmload.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">firmware_open</code>(<var class="Fa" style="white-space: nowrap;">const + char *drvname</var>, <var class="Fa" style="white-space: nowrap;">const char + *imgname</var>, + <var class="Fa" style="white-space: nowrap;">firmware_handle_t + *fhp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">firmware_close</code>(<var class="Fa" style="white-space: nowrap;">firmware_handle_t + fh</var>);</p> +<p class="Pp"><var class="Ft">off_t</var> + <br/> + <code class="Fn">firmware_get_size</code>(<var class="Fa" style="white-space: nowrap;">firmware_handle_t + fh</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">firmware_read</code>(<var class="Fa" style="white-space: nowrap;">firmware_handle_t + fh</var>, <var class="Fa" style="white-space: nowrap;">off_t offset</var>, + <var class="Fa" style="white-space: nowrap;">void *buf</var>, + <var class="Fa" style="white-space: nowrap;">size_t size</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">firmware_malloc</code>(<var class="Fa" style="white-space: nowrap;">size_t + size</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">firmware_free</code>(<var class="Fa" style="white-space: nowrap;">void + *buf</var>, <var class="Fa" style="white-space: nowrap;">size_t + size</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">firmload</code> provides a simple and convenient + API for device drivers to load firmware images from files residing in the + file system that are necessary for the devices that they control. Firmware + images reside in sub-directories, one for each driver, of a series of + colon-separated path prefixes specified by the sysctl variable + <code class="Dv">hw.firmware.path</code>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<p class="Pp">The following functions are provided by the + <code class="Nm">firmload</code> API:</p> +<dl class="Bl-tag"> + <dt id="firmware_open"><a class="permalink" href="#firmware_open"><code class="Fn">firmware_open</code></a>(<var class="Fa">drvname</var>, + <var class="Fa">imgname</var>, <var class="Fa">fhp</var>)</dt> + <dd> + <p class="Pp" id="firmware_open~2">Open the firmware image + <var class="Fa">imgname</var> for the driver + <var class="Fa">drvname</var>. The path to the firmware image file is + constructed by appending the string “/drvname/imgname” to + each configured path prefix until opening the firmware image file + succeeds. Upon success, + <a class="permalink" href="#firmware_open~2"><code class="Fn">firmware_open</code></a>() + returns 0 and stores a firmware image handle in the location pointed to + by <var class="Fa">fhp</var>. Otherwise, an error code is returned to + indicate the reason for failure.</p> + </dd> + <dt id="firmware_close"><a class="permalink" href="#firmware_close"><code class="Fn">firmware_close</code></a>(<var class="Fa">fh</var>)</dt> + <dd> + <p class="Pp">Close the firmware image file associated with the firmware + handle <var class="Fa">fh</var>. Returns 0 upon success or an error code + to indicate the reason for failure.</p> + </dd> + <dt id="firmware_get_size"><a class="permalink" href="#firmware_get_size"><code class="Fn">firmware_get_size</code></a>(<var class="Fa">fh</var>)</dt> + <dd> + <p class="Pp">Returns the size of the image file associated with the + firmware handle <var class="Fa">fh</var>.</p> + </dd> + <dt id="firmware_read"><a class="permalink" href="#firmware_read"><code class="Fn">firmware_read</code></a>(<var class="Fa">fh</var>, + <var class="Fa">offset</var>, <var class="Fa">buf</var>, + <var class="Fa">size</var>)</dt> + <dd> + <p class="Pp">Reads from the image file associated with the firmware handle + <var class="Fa">fh</var> beginning at offset + <var class="Fa">offset</var> for length <var class="Fa">size</var>. The + firmware image data is placed into the buffer specified by + <var class="Fa">buf</var>. Returns 0 upon success or an error code to + indicate the reason for failure.</p> + </dd> + <dt id="firmware_malloc"><a class="permalink" href="#firmware_malloc"><code class="Fn">firmware_malloc</code></a>(<var class="Fa">size</var>)</dt> + <dd> + <p class="Pp" id="firmware_malloc~2">Allocates a region of wired kernel + memory of size <var class="Fa">size</var>. Note: + <a class="permalink" href="#firmware_malloc~2"><code class="Fn">firmware_malloc</code></a>() + may block.</p> + </dd> + <dt id="firmware_free"><a class="permalink" href="#firmware_free"><code class="Fn">firmware_free</code></a>(<var class="Fa">buf</var>, + <var class="Fa">size</var>)</dt> + <dd> + <p class="Pp" id="firmware_malloc~3">Frees a region of memory previously + allocated by + <a class="permalink" href="#firmware_malloc~3"><code class="Fn">firmware_malloc</code></a>().</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<p class="Pp">Default search path for firmware</p> +<dl class="Bl-tag Bl-compact"> + <dt><span class="Pa">/libdata/firmware</span></dt> + <dd style="width: auto;"> </dd> + <dt><span class="Pa">/usr/libdata/firmware</span></dt> + <dd style="width: auto;"> </dd> + <dt><span class="Pa">/usr/pkg/libdata/firmware</span></dt> + <dd style="width: auto;"> </dd> + <dt><span class="Pa">/usr/pkg/libdata</span></dt> + <dd style="width: auto;"> </dd> +</dl> +</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">autoconf(9)</a>, <a class="Xr">malloc(9)</a>, + <a class="Xr">vnsubr(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">firmload</code> framework first appeared in + <span class="Ux">NetBSD 4.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Jason Thorpe</span> + <<a class="Mt" href="mailto:thorpej@NetBSD.org">thorpej@NetBSD.org</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 16, 2018</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/flash.9 3.html b/static/netbsd/man9/flash.9 3.html new file mode 100644 index 00000000..721e2898 --- /dev/null +++ b/static/netbsd/man9/flash.9 3.html @@ -0,0 +1,75 @@ +<table class="head"> + <tr> + <td class="head-ltitle">FLASH(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">FLASH(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">flash</code> — <span class="Nd">subsystem + for flash-like memory devices</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">dev/flash/flash.h</a>></code></p> +<p class="Pp"><var class="Ft">device_t</var> + <br/> + <code class="Fn">flash_attach_mi</code>(<var class="Fa" style="white-space: nowrap;">const + struct flash_interface *fl</var>, + <var class="Fa" style="white-space: nowrap;">device_t dev</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Flash-like devices can register themselves to the + <code class="Nm">flash</code> layer with the + <var class="Fa">flash_hw_if</var> structure. This structure has function + pointers and other fields.</p> +<p class="Pp" id="flash_attach_mi">The attachment can be done by calling + <a class="permalink" href="#flash_attach_mi"><code class="Fn">flash_attach_mi</code></a>() + with this structure and the device's <var class="Vt">device_t</var> as an + argument. Return value is the flash layer device. The + <var class="Fa">flash_interface</var> structure is shown below.</p> +<div class="Bd Pp Li"> +<pre>struct flash_interface { + int (*erase) (device_t, struct flash_erase_instruction *); + int (*read) (device_t, off_t, size_t, size_t *, uint8_t *); + int (*write) (device_t, off_t, size_t, size_t *, const uint8_t *); + int (*block_markbad)(device_t, uint64_t); + int (*block_isbad)(device_t, uint64_t); + int (*sync) (device_t); + + int (*submit)(device_t, struct buf *); + + /* storage for partition info */ + struct flash_partition partition; + + /* total size of mtd */ + flash_addr_t size; + uint32_t page_size; + uint32_t erasesize; + uint32_t writesize; + uint32_t minor; + uint8_t type; +};</pre> +</div> +</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">flash(4)</a>, <a class="Xr">nand(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Adam Hoka</span> + <<a class="Mt" href="mailto:ahoka@NetBSD.org">ahoka@NetBSD.org</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 31, 2011</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/fstrans.9 3.html b/static/netbsd/man9/fstrans.9 3.html new file mode 100644 index 00000000..9de74e53 --- /dev/null +++ b/static/netbsd/man9/fstrans.9 3.html @@ -0,0 +1,307 @@ +<table class="head"> + <tr> + <td class="head-ltitle">FSTRANS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">FSTRANS(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">fstrans</code>, + <code class="Nm">fstrans_setstate</code>, + <code class="Nm">fstrans_getstate</code>, + <code class="Nm">fstrans_start</code>, + <code class="Nm">fstrans_start_nowait</code>, + <code class="Nm">fstrans_start_lazy</code>, + <code class="Nm">fstrans_done</code>, + <code class="Nm">fstrans_is_owner</code>, + <code class="Nm">fscow_establish</code>, + <code class="Nm">fscow_disestablish</code>, + <code class="Nm">fscow_run</code> — <span class="Nd">file system + suspension helper subsystem</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/mount.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/fstrans.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">fstrans_start</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fstrans_start_nowait</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">fstrans_start_lazy</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">fstrans_done</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fstrans_setstate</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">enum + fstrans_state new_state</var>);</p> +<p class="Pp"><var class="Ft">enum fstrans_state</var> + <br/> + <code class="Fn">fstrans_getstate</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fstrans_is_owner</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fscow_establish</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">int + (*func)(void *, struct buf *, bool)</var>, + <var class="Fa" style="white-space: nowrap;">void *cookie</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fscow_disestablish</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">int + (*func)(void *, struct buf *, bool)</var>, + <var class="Fa" style="white-space: nowrap;">void *cookie</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">fscow_run</code>(<var class="Fa" style="white-space: nowrap;">struct + buf *bp</var>, <var class="Fa" style="white-space: nowrap;">bool + data_valid</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">fstrans</code> subsystem assists file system + suspension and copy-on-write snapshots.</p> +<p class="Pp" id="fstrans_start">The file system's normal operations, such as + its <a class="Xr">vnodeops(9)</a>, must be bracketed by + <a class="permalink" href="#fstrans_start"><code class="Fn">fstrans_start</code></a>() + and <code class="Fn">fstrans_done</code>() in a + <a class="permalink" href="#shared"><i class="Em" id="shared">shared</i></a> + transaction, which is blocked by suspending the file system and while it is + suspended.</p> +<p class="Pp" id="fstrans_start_lazy">Operations needed while suspending the + file system must be bracketed by + <a class="permalink" href="#fstrans_start_lazy"><code class="Fn">fstrans_start_lazy</code></a>() + and <code class="Fn">fstrans_done</code>() in a + <a class="permalink" href="#lazy"><i class="Em" id="lazy">lazy</i></a> + transaction, which is allowed while suspending the file system, but blocked + while the file system is suspended.</p> +<p class="Pp" id="fstrans_start~2">Transactions are per-thread and nestable: if + a thread is already in a transaction, it can enter another transaction + without blocking. Each + <a class="permalink" href="#fstrans_start~2"><code class="Fn">fstrans_start</code></a>() + must be paired with <code class="Fn">fstrans_done</code>(). Transactions for + multiple distinct mount points may not be nested.</p> +<p class="Pp" id="fstrans_setstate">The file system's + <a class="Xr">VFS_SUSPENDCTL(9)</a> method can use + <a class="permalink" href="#fstrans_setstate"><code class="Fn">fstrans_setstate</code></a>() + to:</p> +<ul class="Bl-dash"> + <li>enter the <code class="Dv">FSTRANS_SUSPENDING</code> state to suspend all + normal operations but allow lazy transactions,</li> + <li>enter the <code class="Dv">FSTRANS_SUSPENDED</code> state to suspend all + operations, and</li> + <li>restore to the <code class="Dv">FSTRANS_NORMAL</code> state to resume all + operations.</li> +</ul> +<p class="Pp" id="fscow_establish">A file system supporting + <code class="Nm">fstrans</code> may establish a copy-on-write callback with + <a class="permalink" href="#fscow_establish"><code class="Fn">fscow_establish</code></a>(). + The copy-on-write callback will be called every time a buffer is written to + a block device with + <a class="permalink" href="#VOP_STRATEGY"><code class="Fn" id="VOP_STRATEGY">VOP_STRATEGY</code></a>() + and every time a buffer is read into the <a class="Xr">buffercache(9)</a> + with <code class="Dv">B_MODIFY</code> set indicating the caller's intent to + modify it. Anyone modifying a buffer may additionally use + <code class="Fn">fscow_run</code>() to explicitly invoke the established + callback. The copy-on-write callback must be disestablished with + <code class="Fn">fscow_disestablish</code>() when the file system is done + with it.</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">fstrans_start</code>(<var class="Fa">mp</var>)</dt> + <dd>Enter a transaction on the file system <var class="Fa">mp</var> in the + current thread. If the file system is in a state that blocks such + transactions, wait until it changes state to one that does not. + <p class="Pp">If the file system is suspended, wait until it is resumed.</p> + <p class="Pp" id="fstrans_start~3">However, if the current thread is already + in a transaction on <var class="Fa">mp</var>, + <a class="permalink" href="#fstrans_start~3"><code class="Fn">fstrans_start</code></a>() + will enter a nested transaction and return immediately without + waiting.</p> + <p class="Pp">May sleep.</p> + </dd> + <dt id="fstrans_start_nowait"><a class="permalink" href="#fstrans_start_nowait"><code class="Fn">fstrans_start_nowait</code></a>(<var class="Fa">mp</var>)</dt> + <dd>Like <code class="Fn">fstrans_start</code>(), but return + <code class="Er">EBUSY</code> immediately if transactions are blocked in + its current state. + <p class="Pp">May sleep nevertheless on internal locks.</p> + </dd> + <dt id="fstrans_start_lazy~2"><a class="permalink" href="#fstrans_start_lazy~2"><code class="Fn">fstrans_start_lazy</code></a>(<var class="Fa">mp</var>)</dt> + <dd>Like <code class="Fn">fstrans_start</code>(), but will not block while + suspending. + <p class="Pp">May sleep.</p> + </dd> + <dt id="fstrans_done"><a class="permalink" href="#fstrans_done"><code class="Fn">fstrans_done</code></a>(<var class="Fa">mp</var>)</dt> + <dd>End the current transaction on <var class="Fa">mp</var>.</dd> + <dt><code class="Fn">fstrans_getstate</code>(<var class="Fa">mp</var>)</dt> + <dd>Return the current state of the file system <var class="Fa">mp</var>. + <p class="Pp">Must be called within a transaction for the answer to be + stable.</p> + </dd> + <dt id="fstrans_setstate~2"><a class="permalink" href="#fstrans_setstate~2"><code class="Fn">fstrans_setstate</code></a>(<var class="Fa">mp</var>, + <var class="Fa">new_state</var>)</dt> + <dd>Change the state of the file system <var class="Fa">mp</var> to + <var class="Fa">new_state</var>, and wait for all transactions not allowed + in <var class="Fa">new_state</var> to complete. + <dl class="Bl-tag"> + <dt id="FSTRANS_NORMAL"><a class="permalink" href="#FSTRANS_NORMAL"><code class="Dv">FSTRANS_NORMAL</code></a></dt> + <dd>Allow all transactions.</dd> + <dt id="FSTRANS_SUSPENDING"><a class="permalink" href="#FSTRANS_SUSPENDING"><code class="Dv">FSTRANS_SUSPENDING</code></a></dt> + <dd>Block <code class="Dv">FSTRANS_SHARED</code> transactions but allow + <code class="Dv">FSTRANS_LAZY</code> transactions.</dd> + <dt id="FSTRANS_SUSPENDED"><a class="permalink" href="#FSTRANS_SUSPENDED"><code class="Dv">FSTRANS_SUSPENDED</code></a></dt> + <dd>Block all transactions.</dd> + </dl> + <p class="Pp" id="fstrans_getstate">A thread that changes a file system to a + state other than <code class="Dv">FSTRANS_NORMAL</code> enters a + transaction for the purposes of + <a class="permalink" href="#fstrans_getstate"><code class="Fn">fstrans_getstate</code></a>() + until it changes state back to + <code class="Dv">FSTRANS_NORMAL</code>.</p> + <p class="Pp" id="fstrans_is_owner">Additionally, a thread that changes a + file system to a state other than <code class="Dv">FSTRANS_NORMAL</code> + acquires an exclusive lock on the file system state, so that + <a class="permalink" href="#fstrans_is_owner"><code class="Fn">fstrans_is_owner</code></a>() + will return true in that thread, and no other thread can change the file + system's state until the owner restores it to + <code class="Dv">FSTRANS_NORMAL</code>.</p> + <p class="Pp" id="fstrans_setstate~3">May sleep, and may be interrupted by a + signal. On success, return zero. On failure, restore the file system to + the <code class="Dv">FSTRANS_NORMAL</code> state and return an error + code. + <a class="permalink" href="#fstrans_setstate~3"><code class="Fn">fstrans_setstate</code></a>() + never fails if <var class="Fa">new_state</var> is + <code class="Dv">FSTRANS_NORMAL</code>.</p> + </dd> + <dt><code class="Fn">fstrans_is_owner</code>(<var class="Fa">mp</var>)</dt> + <dd>Return <code class="Dv">true</code> if the current thread is currently + suspending the file system <var class="Fa">mp</var>.</dd> + <dt><code class="Fn">fscow_establish</code>(<var class="Fa">mp</var>, + <var class="Fa">func</var>, <var class="Fa">cookie</var>)</dt> + <dd>Establish a copy-on-write callback for the file system + <var class="Fa">mp</var>. The function <var class="Fa">func</var> will be + called for every buffer <var class="Fa">bp</var> written through this file + system as + <div class="Bd + Bd-indent"><code class="Li"><var class="Fa">func</var>(<var class="Fa">cookie</var>, + <var class="Fa">bp</var>, <var class="Fa">data_valid</var></code></div> + ) where <var class="Fa">data_valid</var> is true if and only if the buffer + <var class="Fa">bp</var> has not yet been modified. + <p class="Pp">May sleep.</p> + </dd> + <dt id="fscow_disestablish"><a class="permalink" href="#fscow_disestablish"><code class="Fn">fscow_disestablish</code></a>(<var class="Fa">mp</var>, + <var class="Fa">func</var>, <var class="Fa">cookie</var>)</dt> + <dd>Disestablish a copy-on-write callback established with + <code class="Fn">fscow_establish</code>(). + <p class="Pp">May sleep.</p> + </dd> + <dt id="fscow_run"><a class="permalink" href="#fscow_run"><code class="Fn">fscow_run</code></a>(<var class="Fa">bp</var>, + <var class="Fa">data_valid</var>)</dt> + <dd>Run all copy-on-write callbacks established for the file system this + buffer belongs to, if they have not already been run for this buffer. If + <var class="Fa">data_valid</var> is <code class="Dv">true</code> the + buffer data has not yet been modified. + <p class="Pp">May sleep.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following is an example of a file system suspend + operation.</p> +<div class="Bd Pp Li"> +<pre>int +xxx_suspendctl(struct mount *mp, int cmd) +{ + int error; + + switch (cmd) { + case SUSPEND_SUSPEND: + error = fstrans_setstate(mp, FSTRANS_SUSPENDING); + if (error) + return error; + return fstrans_setstate(mp, FSTRANS_SUSPENDED); + + case SUSPEND_RESUME: + return fstrans_setstate(mp, FSTRANS_NORMAL); + + default: + return EINVAL; + } +}</pre> +</div> +<p class="Pp">This is an example of a file system operation.</p> +<div class="Bd Pp Li"> +<pre>int +xxx_create(void *v) +{ + struct vop_create_args *ap = v; + struct mount *mp = ap->a_dvp->v_mount; + int error; + + fstrans_start(mp); + + /* Actually create the node. */ + + fstrans_done(mp); + + return 0; +}</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">fstrans</code> subsystem is implemented in + the file <span class="Pa">sys/kern/vfs_trans.c</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">vfs_resume(9)</a>, + <a class="Xr">vfs_suspend(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">fstrans</code> subsystem appeared in + <span class="Ux">NetBSD 5.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">fstrans</code> subsystem was written by + <span class="An">Jürgen Hannken-Illjes</span> + ⟨hannken@NetBSD.org⟩.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp"><code class="Nm">fstrans</code> is useful only for temporary + suspension — it does not help to permanently block file system + operations for unmounting, because <code class="Fn">fstrans_start</code>() + cannot fail.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 4, 2018</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/genfs.9 3.html b/static/netbsd/man9/genfs.9 3.html new file mode 100644 index 00000000..599f3fb9 --- /dev/null +++ b/static/netbsd/man9/genfs.9 3.html @@ -0,0 +1,137 @@ +<table class="head"> + <tr> + <td class="head-ltitle">GENFS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">GENFS(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">genfs</code> — <span class="Nd">genfs + routines</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">miscfs/genfs/genfs.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">genfs_can_chflags</code>(<var class="Fa" style="white-space: nowrap;">vnode_t + *vp</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t</var>, + <var class="Fa" style="white-space: nowrap;">cred"</var>, + <var class="Fa" style="white-space: nowrap;">uid_t owner_uid</var>, + <var class="Fa" style="white-space: nowrap;">bool + changing_sysflags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">genfs_can_chmod</code>(<var class="Fa" style="white-space: nowrap;">vnode_t + *vp</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">uid_t + cur_uid</var>, <var class="Fa" style="white-space: nowrap;">gid_t + cur_gid</var>, <var class="Fa" style="white-space: nowrap;">mode_t + new_mode</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">genfs_can_chown</code>(<var class="Fa" style="white-space: nowrap;">vnode_t + *vp</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">uid_t + cur_uid</var>, <var class="Fa" style="white-space: nowrap;">gid_t + cur_gid</var>, <var class="Fa" style="white-space: nowrap;">uid_t + new_uid</var>, <var class="Fa" style="white-space: nowrap;">gid_t + new_gid</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">genfs_can_chtimes</code>(<var class="Fa" style="white-space: nowrap;">vnode_t + *vp</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">uid_t + owner_uid</var>, <var class="Fa" style="white-space: nowrap;">u_int + vaflags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">genfs_can_extattr</code>(<var class="Fa" style="white-space: nowrap;">vnode_t + *vp</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">accmode_t + accmode</var>, <var class="Fa" style="white-space: nowrap;">int + attrnamespace</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">genfs_can_sticky</code>(<var class="Fa" style="white-space: nowrap;">vnode_t + *vp</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">uid_t + dir_uid</var>, <var class="Fa" style="white-space: nowrap;">uid_t + file_uid</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The functions documented here are general routines for internal + use in file systems to implement common policies for performing various + operations. The developer must understand that these routines implement no + system-wide policies and only take into account the object being accessed + and the nominal values of the credentials accessing it.</p> +<p class="Pp">In other words, these functions are not meant to be called + directly. They are intended to be used in <a class="Xr">kauth(9)</a> vnode + scope authorization calls, for providing the fall-back file system + decision.</p> +<p class="Pp">As a rule of thumb, code that looks like this is wrong:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>error = genfs_can_foo(...); /* WRONG */</pre> +</div> +<p class="Pp">While code that looks like this is right:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>error = kauth_authorize_vnode(..., genfs_can_foo(...));</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="genfs_can_chflags"><a class="permalink" href="#genfs_can_chflags"><code class="Fn">genfs_can_chflags</code></a>(<var class="Fa">vnode_t + *vp</var>, <var class="Fa">kauth_cred_t cred</var>)</dt> + <dd>"uid_t owner_uid" "bool changing_sysflags" Implements + <a class="Xr">chflags(2)</a> policy.</dd> + <dt id="genfs_can_chmod"><a class="permalink" href="#genfs_can_chmod"><code class="Fn">genfs_can_chmod</code></a>(<var class="Fa">vnode_t + *vp</var>, <var class="Fa">kauth_cred_t cred</var>, <var class="Fa">uid_t + cur_uid</var>, <var class="Fa">gid_t cur_gid</var>, <var class="Fa">mode_t + new_mode</var>)</dt> + <dd>Implements <a class="Xr">chmod(2)</a> policy.</dd> + <dt id="genfs_can_chown"><a class="permalink" href="#genfs_can_chown"><code class="Fn">genfs_can_chown</code></a>(<var class="Fa">vnode_t + *vp</var>, <var class="Fa">kauth_cred_t cred</var>, <var class="Fa">uid_t + cur_uid</var>, <var class="Fa">gid_t cur_gid</var>, <var class="Fa">uid_t + new_uid</var>, <var class="Fa">gid_t new_gid</var>)</dt> + <dd>Implements <a class="Xr">chown(2)</a> policy.</dd> + <dt id="genfs_can_chtimes"><a class="permalink" href="#genfs_can_chtimes"><code class="Fn">genfs_can_chtimes</code></a>(<var class="Fa">vnode_t + *vp</var>, <var class="Fa">kauth_cred_t cred</var>, <var class="Fa">uid_t + owner_uid</var>, <var class="Fa">u_int vaflags</var>)</dt> + <dd>Implements <a class="Xr">utimes(2)</a> policy.</dd> + <dt id="genfs_can_extattr"><a class="permalink" href="#genfs_can_extattr"><code class="Fn">genfs_can_extattr</code></a>(<var class="Fa">vnode_t + *vp</var>, <var class="Fa">kauth_cred_t cred</var>, + <var class="Fa">accmode_t accmode</var>, <var class="Fa">int + attrnamespace</var>)</dt> + <dd>Implements extended attributes access policy.</dd> + <dt id="genfs_can_sticky"><a class="permalink" href="#genfs_can_sticky"><code class="Fn">genfs_can_sticky</code></a>(<var class="Fa">vnode_t + *vp</var>, <var class="Fa">kauth_cred_t cred</var>, <var class="Fa">uid_t + dir_uid</var>, <var class="Fa">uid_t file_uid</var>)</dt> + <dd>Implements rename and delete policy from sticky directories.</dd> +</dl> +</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">genfs_can_access(9)</a>, + <a class="Xr">genfs_can_access_acl_nfs4(9)</a>, + <a class="Xr">genfs_can_access_acl_posix1e(9)</a>, + <a class="Xr">genfs_rename(9)</a>, <a class="Xr">kauth(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Elad Efrat</span> + <<a class="Mt" href="mailto:elad@NetBSD.org">elad@NetBSD.org</a>> + wrote this manual page.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 17, 2022</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/genfs_can_access.9 3.html b/static/netbsd/man9/genfs_can_access.9 3.html new file mode 100644 index 00000000..1671198e --- /dev/null +++ b/static/netbsd/man9/genfs_can_access.9 3.html @@ -0,0 +1,100 @@ +<table class="head"> + <tr> + <td class="head-ltitle">GENFS_CAN_ACCESS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">GENFS_CAN_ACCESS(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">genfs_can_access</code> — + <span class="Nd">generate an access control decision using vnode + parameters</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">miscfs/genfs/genfs.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">genfs_can_access</code>(<var class="Fa">vnode_t *vp</var>, + <var class="Fa">kauth_cred_t cred</var>, <var class="Fa">uid_t + file_uid</var>, <var class="Fa">gid_t file_gid</var>, <var class="Fa">mode_t + file_mode</var>, <var class="Fa">struct acl *acl</var>, + <var class="Fa">accmode_t accmode</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This call implements the logic for the + <span class="Ux">UNIX</span> discretionary file security model common to + many file systems in <span class="Ux">FreeBSD</span>. It accepts the vnode + <var class="Fa">vp</var>, requesting credential <var class="Fa">cred</var>, + permissions via owning UID <var class="Fa">file_uid</var>, owning GID + <var class="Fa">file_gid</var>, file permissions + <var class="Fa">file_mode</var>, access ACL for the file + <var class="Fa">acl</var>, desired access mode + <var class="Fa">accmode</var>,</p> +<p class="Pp" id="vaccess">This call is intended to support implementations of + <a class="Xr">VOP_ACCESS(9)</a>, which will use their own access methods to + retrieve the vnode properties, and then invoke + <a class="permalink" href="#vaccess"><code class="Fn">vaccess</code></a>() + in order to perform the actual check. Implementations of + <a class="Xr">VOP_ACCESS(9)</a> may choose to implement additional security + mechanisms whose results will be composed with the return value.</p> +<p class="Pp" id="genfs_can_access">The algorithm used by + <a class="permalink" href="#genfs_can_access"><code class="Fn">genfs_can_access</code></a>() + selects a component of the file permission bits based on comparing the + passed credential, file owner, and file group. If the credential's effective + UID matches the file owner, then the owner component of the permission bits + is selected. If the UID does not match, then the credential's effective GID, + followed by additional groups, are compared with the file group—if + there is a match, then the group component of the permission bits is + selected. If neither the credential UID or GIDs match the passed file owner + and group, then the other component of the permission bits is selected.</p> +<p class="Pp">Once appropriate protections are selected for the current + credential, the requested access mode, in combination with the vnode type, + will be compared with the discretionary rights available for the credential. + If the rights granted by discretionary protections are insufficient, then + super-user privilege, if available for the credential, will also be + considered.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp"><code class="Fn">genfs_can_access</code>() will return 0 on + success, or a non-zero error value on failure.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1> +<dl class="Bl-tag"> + <dt id="EACCES">[<a class="permalink" href="#EACCES"><code class="Er">EACCES</code></a>]</dt> + <dd>Permission denied. An attempt was made to access a file in a way forbidden + by its file access permissions.</dd> + <dt id="EPERM">[<a class="permalink" href="#EPERM"><code class="Er">EPERM</code></a>]</dt> + <dd>Operation not permitted. An attempt was made to perform an operation + limited to processes with appropriate privileges or to the owner of a file + or other resource.</dd> +</dl> +</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">genfs(9)</a>, + <a class="Xr">genfs_can_access_acl_nfs4(9)</a>, + <a class="Xr">genfs_can_access_acl_posix1e(9)</a>, + <a class="Xr">vnode(9)</a>, <a class="Xr">VOP_ACCESS(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page and the current implementation of + <code class="Fn">vaccess</code>() were written by <span class="An">Robert + Watson</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 17, 2022</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/hardclock.9 3.html b/static/netbsd/man9/hardclock.9 3.html new file mode 100644 index 00000000..c0c53cc3 --- /dev/null +++ b/static/netbsd/man9/hardclock.9 3.html @@ -0,0 +1,59 @@ +<table class="head"> + <tr> + <td class="head-ltitle">HARDCLOCK(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">HARDCLOCK(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">hardclock</code> — + <span class="Nd">real-time timer</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">hardclock</code>(<var class="Fa" style="white-space: nowrap;">struct + clockframe *frame</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#hardclock"><code class="Fn" id="hardclock">hardclock</code></a>() + function is called <a class="Xr">hz(9)</a> times per second. It implements + the real-time system clock. The argument <var class="Va">frame</var> is an + opaque, machine-dependent structure that encapsulates the previous machine + state.</p> +<p class="Pp" id="hardclock~2">The + <a class="permalink" href="#hardclock~2"><code class="Fn">hardclock</code></a>() + performs different tasks such as:</p> +<ul class="Bl-bullet Bd-indent"> + <li>Run the current process's virtual and profile time (decrease the + corresponding timers, if they are activated, and generate + <code class="Li">SIGVTALRM</code> or <code class="Li">SIGPROF</code>, + respectively).</li> + <li>Increment the time-of-day, taking care of any <a class="Xr">ntpd(8)</a> or + <a class="Xr">adjtime(2)</a> induced changes and leap seconds, as well as + any necessary compensations to keep in sync with PPS signals or external + clocks, if support for this is in the kernel (see + <a class="Xr">options(4)</a>).</li> + <li>Schedule softclock interrupts if any callouts should be triggered (see + <a class="Xr">callout(9)</a>).</li> +</ul> +</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">adjtime(2)</a>, <a class="Xr">ntp_adjtime(2)</a>, + <a class="Xr">signal(7)</a>, <a class="Xr">ntpd(8)</a>, + <a class="Xr">callout(9)</a>, <a class="Xr">hz(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 25, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/heartbeat.9 3.html b/static/netbsd/man9/heartbeat.9 3.html new file mode 100644 index 00000000..4a279c6a --- /dev/null +++ b/static/netbsd/man9/heartbeat.9 3.html @@ -0,0 +1,131 @@ +<table class="head"> + <tr> + <td class="head-ltitle">HEARTBEAT(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">HEARTBEAT(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">heartbeat</code> — + <span class="Nd">periodic checks to ensure CPUs are making + progress</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">options HEARTBEAT</code> + <br/> + <code class="Cd">options HEARTBEAT_MAX_PERIOD_DEFAULT=15</code></p> +<p class="Pp"> + <br/> + <code class="In">#include <<a class="In">sys/heartbeat.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">heartbeat_start</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">heartbeat</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">heartbeat_suspend</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">heartbeat_resume</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><code class="Fd">#ifdef DDB</code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">heartbeat_dump</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><code class="Fd">#endif</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">heartbeat</code> subsystem verifies that soft + interrupts (<a class="Xr">softint(9)</a>) and the system + <a class="Xr">timecounter(9)</a> are making progress over time, and panics + if they appear stuck.</p> +<p class="Pp">The number of seconds before <code class="Nm">heartbeat</code> + panics without progress is controlled by the sysctl knob + <code class="Li">kern.heartbeat.max_period</code>, which defaults to 15. If + set to zero, heartbeat checks are disabled.</p> +<p class="Pp" id="heartbeat">The periodic hardware timer interrupt handler calls + <a class="permalink" href="#heartbeat"><code class="Fn">heartbeat</code></a>() + every tick on each CPU. Once per second (i.e., every <a class="Xr">hz(9)</a> + ticks), <code class="Fn">heartbeat</code>() schedules a soft interrupt at + priority <code class="Dv">SOFTINT_CLOCK</code> to advance the current CPU's + view of <a class="Xr">time_uptime(9)</a>.</p> +<p class="Pp" id="heartbeat~2"><a class="permalink" href="#heartbeat~2"><code class="Fn">heartbeat</code></a>() + checks whether <a class="Xr">time_uptime(9)</a> has changed, to see if + either the <a class="Xr">timecounter(9)</a> or soft interrupts on the + current CPU are stuck. If it hasn't advanced within + <code class="Li">kern.heartbeat.max_period</code> seconds worth of ticks, or + if it has updated and the current CPU's view of it hasn't been updated by + more than <code class="Li">kern.heartbeat.max_period</code> seconds, then + <code class="Fn">heartbeat</code>() panics.</p> +<p class="Pp" id="heartbeat~3"><a class="permalink" href="#heartbeat~3"><code class="Fn">heartbeat</code></a>() + also checks whether the next online CPU has advanced its view of + <a class="Xr">time_uptime(9)</a>, to see if soft interrupts (including + <a class="Xr">callout(9)</a>) on that CPU are stuck. If it hasn't updated + within <code class="Li">kern.heartbeat.max_period</code> seconds, + <code class="Fn">heartbeat</code>() sends an <a class="Xr">ipi(9)</a> to + panic on that CPU. If that CPU has not acknowledged the + <a class="Xr">ipi(9)</a> within one second, + <code class="Fn">heartbeat</code>() panics on the current CPU instead.</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">heartbeat</code>()</dt> + <dd>Check for timecounter and soft interrupt progress on this CPU and on + another CPU, and schedule a soft interrupt to advance this CPU's view of + timecounter progress. + <p class="Pp">Called by <a class="Xr">hardclock(9)</a> periodically.</p> + </dd> + <dt id="heartbeat_dump"><a class="permalink" href="#heartbeat_dump"><code class="Fn">heartbeat_dump</code></a>()</dt> + <dd>Print each CPU's heartbeat counter, uptime cache, and uptime cache + timestamp (in units of heartbeats) to the console. + <p class="Pp">Can be invoked from <a class="Xr">ddb(9)</a> by + ‘<code class="Li">call heartbeat_dump</code>’.</p> + </dd> + <dt id="heartbeat_resume"><a class="permalink" href="#heartbeat_resume"><code class="Fn">heartbeat_resume</code></a>()</dt> + <dd>Resume heartbeat monitoring of the current CPU. + <p class="Pp">Called after a CPU has started running but before it has been + marked online.</p> + </dd> + <dt id="heartbeat_start"><a class="permalink" href="#heartbeat_start"><code class="Fn">heartbeat_start</code></a>()</dt> + <dd>Start monitoring heartbeats systemwide. + <p class="Pp" id="main">Called by + <a class="permalink" href="#main"><code class="Fn">main</code></a>() in + <span class="Pa">sys/kern/init_main.c</span> as soon as soft interrupts + can be established.</p> + </dd> + <dt id="heartbeat_suspend"><a class="permalink" href="#heartbeat_suspend"><code class="Fn">heartbeat_suspend</code></a>()</dt> + <dd>Suspend heartbeat monitoring of the current CPU. + <p class="Pp">Called after the current CPU has been marked offline but + before it has stopped running.</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 <code class="Nm">heartbeat</code> subsystem is implemented in + <span class="Pa">sys/kern/kern_heartbeat.c</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">swwdog(4)</a>, <a class="Xr">wdogctl(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">heartbeat</code> subsystem first appeared in + <span class="Ux">NetBSD 11.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 6, 2023</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/hz.9 3.html b/static/netbsd/man9/hz.9 3.html new file mode 100644 index 00000000..39a5112c --- /dev/null +++ b/static/netbsd/man9/hz.9 3.html @@ -0,0 +1,79 @@ +<table class="head"> + <tr> + <td class="head-ltitle">HZ(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">HZ(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">hz</code>, <code class="Nm">tick</code>, + <code class="Nm">tickadj</code>, <code class="Nm">stathz</code>, + <code class="Nm">profhz</code> — <span class="Nd">system time + model</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/kernel.h</a>></code></p> +<p class="Pp"> + <br/> + <var class="Vt">extern int hz;</var> + <br/> + <var class="Vt">extern int tick;</var> + <br/> + <var class="Vt">extern int tickadj;</var> + <br/> + <var class="Vt">extern int stathz;</var> + <br/> + <var class="Vt">extern int profhz;</var></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The essential clock handling routines in + <span class="Ux">NetBSD</span> are written to operate with two timers that + run independently of each other. The main clock, running + <var class="Va">hz</var> times per second, is used to keep track of real + time.</p> +<p class="Pp">In another words, <var class="Va">hz</var> specifies the number of + times the <a class="Xr">hardclock(9)</a> timer ticks per second. Normally + <a class="Xr">hardclock(9)</a> increments time by <var class="Va">tick</var> + each time it is called. If the system clock has drifted, + <a class="Xr">adjtime(2)</a> may be used to skew this increment based on the + rate of <var class="Va">tickadj</var>.</p> +<p class="Pp">The second timer is used to gather timing statistics. It also + handles kernel and user profiling. If the second timer is programmable, it + is randomized to avoid aliasing between the two clocks. The mean frequency + of the second timer is <var class="Va">stathz</var>. If a separate clock is + not available, <var class="Va">stathz</var> is set to + <var class="Va">hz</var>.</p> +<p class="Pp">If profiling is enabled, the clock normally used to drive + <var class="Va">stathz</var> may be run at a higher rate + <var class="Va">profhz</var>, which is required to be a multiple of + <var class="Va">stathz</var>. This will give higher resolution profiling + information.</p> +<p class="Pp" id="struct">These system variables are also available as + <a class="permalink" href="#struct"><i class="Em">struct clockinfo</i></a> + from <a class="Xr">sysctl(3)</a> and + <a class="permalink" href="#kern.clockrate"><b class="Sy" id="kern.clockrate">kern.clockrate</b></a> + from <a class="Xr">sysctl(8)</a>. The <var class="Va">hz</var> is + hardware-dependent; it can be overridden (if the machine dependent code + supports this) by defining <code class="Dv">HZ</code> in the kernel + configuration file (see <a class="Xr">options(4)</a>). Only override the + default value if you really know what you are doing.</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">adjtime(2)</a>, <a class="Xr">callout(9)</a>, + <a class="Xr">hardclock(9)</a>, <a class="Xr">microtime(9)</a>, + <a class="Xr">time_second(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 25, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/ieee80211_proto.9 3.html b/static/netbsd/man9/ieee80211_proto.9 3.html new file mode 100644 index 00000000..82e9d6e8 --- /dev/null +++ b/static/netbsd/man9/ieee80211_proto.9 3.html @@ -0,0 +1,80 @@ +<table class="head"> + <tr> + <td class="head-ltitle">IEEE80211_PROTO(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">IEEE80211_PROTO(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">ieee80211_proto_attach</code>, + <code class="Nm">ieee80211_proto_detach</code>, + <code class="Nm">ieee80211_print_essid</code>, + <code class="Nm">ieee80211_dump_pkt</code>, + <code class="Nm">ieee80211_fix_rate</code>, + <code class="Nm">ieee80211_proto</code> — <span class="Nd">software + 802.11 stack protocol helper functions</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">net80211/ieee80211_var.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">net80211/ieee80211_proto.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">ieee80211_proto_attach</code>(<var class="Fa" style="white-space: nowrap;">struct + ieee80211com *ic</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">ieee80211_proto_detach</code>(<var class="Fa" style="white-space: nowrap;">struct + ieee80211com *ic</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">ieee80211_print_essid</code>(<var class="Fa" style="white-space: nowrap;">u_int8_t + *essid</var>, <var class="Fa" style="white-space: nowrap;">int + len</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">ieee80211_dump_pkt</code>(<var class="Fa" style="white-space: nowrap;">u_int8_t + *buf</var>, <var class="Fa" style="white-space: nowrap;">int len</var>, + <var class="Fa" style="white-space: nowrap;">int rate</var>, + <var class="Fa" style="white-space: nowrap;">int rssi</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">ieee80211_fix_rate</code>(<var class="Fa">struct + ieee80211_node *ni</var>, <var class="Fa">int flags</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">These functions are helper functions used throughout the software + 802.11 protocol stack.</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">ieee80211(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ieee80211</code> series of functions first + appeared in <span class="Ux">NetBSD 1.5</span>, and were later ported to + <span class="Ux">FreeBSD 4.6</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This man page was written by <span class="An">Bruce M. + Simpson</span> + <<a class="Mt" href="mailto:bms@FreeBSD.org">bms@FreeBSD.org</a>> and + <span class="An">Darron Broad</span> + <<a class="Mt" href="mailto:darron@kewl.org">darron@kewl.org</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 12, 2006</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/ieee80211_radiotap.9 3.html b/static/netbsd/man9/ieee80211_radiotap.9 3.html new file mode 100644 index 00000000..06b0d5ce --- /dev/null +++ b/static/netbsd/man9/ieee80211_radiotap.9 3.html @@ -0,0 +1,233 @@ +<table class="head"> + <tr> + <td class="head-ltitle">IEEE80211_RADIOTAP(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">IEEE80211_RADIOTAP(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">ieee80211_radiotap</code> — + <span class="Nd">software 802.11 stack packet capture definitions</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">net80211/ieee80211_var.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">net80211/ieee80211_ioctl.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">net80211/ieee80211_radiotap.h</a>></code> + <br/> + <code class="In">#include <<a class="In">net/bpf.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">ieee80211_radiotap</code> definitions provide + a device-independent <a class="Xr">bpf(4)</a> attachment for the capture of + information about 802.11 traffic which is not part of the 802.11 frame + structure.</p> +<p class="Pp">Radiotap was designed to balance the desire for a capture format + that conserved CPU and memory bandwidth on embedded systems, with the desire + for a hardware-independent, extensible format that would support the diverse + capabilities of virtually all 802.11 radios.</p> +<p class="Pp">These considerations led radiotap to settle on a format consisting + of a standard preamble followed by an extensible bitmap indicating the + presence of optional capture fields.</p> +<p class="Pp">The capture fields were packed into the header as compactly as + possible, modulo the requirements that they had to be packed swiftly, with + their natural alignment, in the same order as the bits indicating their + presence.</p> +<p class="Pp">This typically includes information such as signal quality and + timestamps. This information may be used by a variety of user agents, + including <a class="Xr">tcpdump(8)</a>. It is requested by using the + <a class="Xr">bpf(4)</a> data-link type + <code class="Dv">DLT_IEEE_80211_RADIO</code>.</p> +<p class="Pp">Each frame using this attachment has the following header + prepended to it:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct ieee80211_radiotap_header { + u_int8_t it_version; /* set to 0 */ + u_int8_t it_pad; + u_int16_t it_len; /* entire length */ + u_int32_t it_present; /* fields present */ +} __attribute__((__packed__));</pre> +</div> +<p class="Pp">A device driver implementing <var class="Vt">radiotap</var> + typically defines a structure embedding an instance of + <var class="Vt">struct ieee80211_radiotap_header</var> at the beginning, + with subsequent fields naturally aligned, and in the appropriate order. + Also, a driver defines a macro to set the bits of the + <var class="Va">it_present</var> bitmap to indicate which fields exist and + are filled in by the driver.</p> +<p class="Pp">Radiotap capture fields are in little-endian byte order.</p> +<p class="Pp" id="must">Radiotap capture fields + <a class="permalink" href="#must"><i class="Em">must be naturally + aligned</i></a>. That is, 16-, 32-, and 64-bit fields must begin on 16-, + 32-, and 64-bit boundaries, respectively. In this way, drivers can avoid + unaligned accesses to radiotap capture fields. radiotap-compliant drivers + must insert padding before a capture field to ensure its natural alignment. + radiotap-compliant packet dissectors, such as <a class="Xr">tcpdump(8)</a>, + expect the padding.</p> +<p class="Pp">Developers beware: all compilers may not pack structs alike. If a + driver developer constructs their radiotap header with a packed structure, + in order to ensure natural alignment, then it is important that they insert + padding bytes by themselves.</p> +<p class="Pp" id="bpfattach2">Radiotap headers are copied to the userland via a + separate bpf attachment. It is necessary for the driver to create this + attachment after calling <a class="Xr">ieee80211_ifattach(9)</a> by calling + <a class="permalink" href="#bpfattach2"><code class="Fn">bpfattach2</code></a>() + with the data-link type set to + <code class="Dv">DLT_IEEE802_11_RADIO</code>.</p> +<p class="Pp" id="bpf_mtap2">When the information is available, usually + immediately before a link-layer transmission or after a receive, the driver + copies it to the bpf layer using the + <a class="permalink" href="#bpf_mtap2"><code class="Fn">bpf_mtap2</code></a>() + function.</p> +<p class="Pp">The following extension fields are defined for + <var class="Vt">radiotap</var>, in the order in which they should appear in + the buffer copied to userland:</p> +<dl class="Bl-tag"> + <dt id="IEEE80211_RADIOTAP_TSFT"><a class="permalink" href="#IEEE80211_RADIOTAP_TSFT"><code class="Dv">IEEE80211_RADIOTAP_TSFT</code></a></dt> + <dd>This field contains the unsigned 64-bit value, in microseconds, of the + MAC's 802.11 Time Synchronization Function timer, when the first bit of + the MPDU arrived at the MAC. This field should be present for received + frames only.</dd> + <dt id="IEEE80211_RADIOTAP_FLAGS"><a class="permalink" href="#IEEE80211_RADIOTAP_FLAGS"><code class="Dv">IEEE80211_RADIOTAP_FLAGS</code></a></dt> + <dd>This field contains a single unsigned 8-bit value, containing a bitmap of + flags specifying properties of the frame being transmitted or + received.</dd> + <dt id="IEEE80211_RADIOTAP_RATE"><a class="permalink" href="#IEEE80211_RADIOTAP_RATE"><code class="Dv">IEEE80211_RADIOTAP_RATE</code></a></dt> + <dd>This field contains a single unsigned 8-bit value, which is the data rate + in use in units of 500Kbps.</dd> + <dt id="IEEE80211_RADIOTAP_CHANNEL"><a class="permalink" href="#IEEE80211_RADIOTAP_CHANNEL"><code class="Dv">IEEE80211_RADIOTAP_CHANNEL</code></a></dt> + <dd>This field contains two unsigned 16-bit values. The first value is the + frequency upon which this PDU was transmitted or received. The second + value is a bitmap containing flags which specify properties of the channel + in use. These are documented within the header file, + <code class="In"><<a class="In">net80211/ieee80211_radiotap.h</a>></code>.</dd> + <dt id="IEEE80211_RADIOTAP_FHSS"><a class="permalink" href="#IEEE80211_RADIOTAP_FHSS"><code class="Dv">IEEE80211_RADIOTAP_FHSS</code></a></dt> + <dd>This field contains two 8-bit values. This field should be present for + frequency-hopping radios only. The first byte is the hop set. The second + byte is the pattern in use.</dd> + <dt id="IEEE80211_RADIOTAP_DBM_ANTSIGNAL"><a class="permalink" href="#IEEE80211_RADIOTAP_DBM_ANTSIGNAL"><code class="Dv">IEEE80211_RADIOTAP_DBM_ANTSIGNAL</code></a></dt> + <dd>This field contains a single signed 8-bit value, which indicates the RF + signal power at the antenna, in decibels difference from 1mW.</dd> + <dt id="IEEE80211_RADIOTAP_DBM_ANTNOISE"><a class="permalink" href="#IEEE80211_RADIOTAP_DBM_ANTNOISE"><code class="Dv">IEEE80211_RADIOTAP_DBM_ANTNOISE</code></a></dt> + <dd>This field contains a single signed 8-bit value, which indicates the RF + noise power at the antenna, in decibels difference from 1mW.</dd> + <dt id="IEEE80211_RADIOTAP_LOCK_QUALITY"><a class="permalink" href="#IEEE80211_RADIOTAP_LOCK_QUALITY"><code class="Dv">IEEE80211_RADIOTAP_LOCK_QUALITY</code></a></dt> + <dd>This field contains a single unsigned 16-bit value, indicating the quality + of the Barker Code lock. No unit is specified for this field. There does + not appear to be a standard way of measuring this at this time; this + quantity is often referred to as “Signal Quality” in some + datasheets.</dd> + <dt id="IEEE80211_RADIOTAP_TX_ATTENUATION"><a class="permalink" href="#IEEE80211_RADIOTAP_TX_ATTENUATION"><code class="Dv">IEEE80211_RADIOTAP_TX_ATTENUATION</code></a></dt> + <dd>This field contains a single unsigned 16-bit value, expressing transmit + power as unitless distance from maximum power set at factory calibration. + 0 indicates maximum transmit power. Monotonically nondecreasing with lower + power levels.</dd> + <dt id="IEEE80211_RADIOTAP_DB_TX_ATTENUATION"><a class="permalink" href="#IEEE80211_RADIOTAP_DB_TX_ATTENUATION"><code class="Dv">IEEE80211_RADIOTAP_DB_TX_ATTENUATION</code></a></dt> + <dd>This field contains a single unsigned 16-bit value, expressing transmit + power as decibel distance from maximum power set at factory calibration. 0 + indicates maximum transmit power. Monotonically nondecreasing with lower + power levels.</dd> + <dt id="IEEE80211_RADIOTAP_DBM_TX_POWER"><a class="permalink" href="#IEEE80211_RADIOTAP_DBM_TX_POWER"><code class="Dv">IEEE80211_RADIOTAP_DBM_TX_POWER</code></a></dt> + <dd>Transmit power expressed as decibels from a 1mW reference. This field is a + single signed 8-bit value. This is the absolute power level measured at + the antenna port.</dd> + <dt id="IEEE80211_RADIOTAP_ANTENNA"><a class="permalink" href="#IEEE80211_RADIOTAP_ANTENNA"><code class="Dv">IEEE80211_RADIOTAP_ANTENNA</code></a></dt> + <dd>For radios which support antenna diversity, this field contains a single + unsigned 8-bit value specifying which antenna is being used to transmit or + receive this frame. The first antenna is antenna 0.</dd> + <dt id="IEEE80211_RADIOTAP_DB_ANTSIGNAL"><a class="permalink" href="#IEEE80211_RADIOTAP_DB_ANTSIGNAL"><code class="Dv">IEEE80211_RADIOTAP_DB_ANTSIGNAL</code></a></dt> + <dd>This field contains a single unsigned 8-bit value, which indicates the RF + signal power at the antenna, in decibels difference from an arbitrary, + fixed reference.</dd> + <dt id="IEEE80211_RADIOTAP_DB_ANTNOISE"><a class="permalink" href="#IEEE80211_RADIOTAP_DB_ANTNOISE"><code class="Dv">IEEE80211_RADIOTAP_DB_ANTNOISE</code></a></dt> + <dd>This field contains a single unsigned 8-bit value, which indicates the RF + noise power at the antenna, in decibels difference from an arbitrary, + fixed reference.</dd> + <dt id="IEEE80211_RADIOTAP_RX_FLAGS"><a class="permalink" href="#IEEE80211_RADIOTAP_RX_FLAGS"><code class="Dv">IEEE80211_RADIOTAP_RX_FLAGS</code></a></dt> + <dd>An unsigned 16-bit bitmap indicating properties of received frames.</dd> + <dt id="IEEE80211_RADIOTAP_TX_FLAGS"><a class="permalink" href="#IEEE80211_RADIOTAP_TX_FLAGS"><code class="Dv">IEEE80211_RADIOTAP_TX_FLAGS</code></a></dt> + <dd>An unsigned 16-bit bitmap indicating properties of transmitted + frames.</dd> + <dt id="IEEE80211_RADIOTAP_RTS_RETRIES"><a class="permalink" href="#IEEE80211_RADIOTAP_RTS_RETRIES"><code class="Dv">IEEE80211_RADIOTAP_RTS_RETRIES + u_int8_t data</code></a></dt> + <dd>Unsigned 8-bit value indicating how many times the NIC retransmitted the + Request to Send (RTS) in an RTS/CTS handshake before receiving an 802.11 + Clear to Send (CTS).</dd> + <dt id="IEEE80211_RADIOTAP_DATA_RETRIES"><a class="permalink" href="#IEEE80211_RADIOTAP_DATA_RETRIES"><code class="Dv">IEEE80211_RADIOTAP_DATA_RETRIES</code></a></dt> + <dd>Unsigned 8-bit value indicating how many times the NIC retransmitted a + unicast data packet before receiving an 802.11 Acknowledgement.</dd> + <dt id="IEEE80211_RADIOTAP_EXT"><a class="permalink" href="#IEEE80211_RADIOTAP_EXT"><code class="Dv">IEEE80211_RADIOTAP_EXT</code></a></dt> + <dd>This bit is reserved for any future extensions to the + <var class="Vt">radiotap</var> structure. A driver sets + <code class="Dv">IEEE80211_RADIOTAP_EXT</code> to extend the it_present + bitmap by another 32 bits. The bitmap can be extended by multiples of 32 + bits to 96, 128, 160 bits or longer, by setting + <code class="Dv">IEEE80211_RADIOTAP_EXT</code> in the extensions. The + bitmap ends at the first extension field where + <code class="Dv">IEEE80211_RADIOTAP_EXT</code> is not set.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">Radiotap header for the Cisco Aironet driver:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct an_rx_radiotap_header { + struct ieee80211_radiotap_header ar_ihdr; + u_int8_t ar_flags; + u_int8_t ar_rate; + u_int16_t ar_chan_freq; + u_int16_t ar_chan_flags; + u_int8_t ar_antsignal; + u_int8_t ar_antnoise; +} __attribute__((__packed__));</pre> +</div> +<p class="Pp">Bitmap indicating which fields are present in the above + structure:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>#define AN_RX_RADIOTAP_PRESENT \ + ((1 >> IEEE80211_RADIOTAP_FLAGS) | \ + (1 >> IEEE80211_RADIOTAP_RATE) | \ + (1 >> IEEE80211_RADIOTAP_CHANNEL) | \ + (1 >> IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \ + (1 >> IEEE80211_RADIOTAP_DBM_ANTNOISE))</pre> +</div> +</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">bpf(4)</a>, <a class="Xr">ieee80211(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">ieee80211_radiotap</code> definitions first + appeared in <span class="Ux">NetBSD 1.5</span>, and were later ported to + <span class="Ux">FreeBSD 4.6</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">ieee80211_radiotap</code> interface was + designed and implemented by <span class="An">David Young</span> + <<a class="Mt" href="mailto:dyoung@pobox.com">dyoung@pobox.com</a>>. + <span class="An">David Young</span> is the maintainer of the radiotap + capture format. Contact him to add new capture fields.</p> +<p class="Pp">This manual page was written by <span class="An">Bruce M. + Simpson</span> + <<a class="Mt" href="mailto:bms@FreeBSD.org">bms@FreeBSD.org</a>> and + <span class="An">Darron Broad</span> + <<a class="Mt" href="mailto:darron@kewl.org">darron@kewl.org</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 12, 2006</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/imax.9 3.html b/static/netbsd/man9/imax.9 3.html new file mode 100644 index 00000000..9848ab9b --- /dev/null +++ b/static/netbsd/man9/imax.9 3.html @@ -0,0 +1,83 @@ +<table class="head"> + <tr> + <td class="head-ltitle">IMAX(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">IMAX(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">imax</code>, <code class="Nm">imin</code>, + <code class="Nm">lmax</code>, <code class="Nm">lmin</code>, + <code class="Nm">uimax</code>, <code class="Nm">uimin</code>, + <code class="Nm">ulmax</code>, <code class="Nm">ulmin</code> — + <span class="Nd">compare integers</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">imax</code>(<var class="Fa" style="white-space: nowrap;">int + a</var>, <var class="Fa" style="white-space: nowrap;">int b</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">imin</code>(<var class="Fa" style="white-space: nowrap;">int + a</var>, <var class="Fa" style="white-space: nowrap;">int b</var>);</p> +<p class="Pp"><var class="Ft">long</var> + <br/> + <code class="Fn">lmax</code>(<var class="Fa" style="white-space: nowrap;">long + a</var>, <var class="Fa" style="white-space: nowrap;">long b</var>);</p> +<p class="Pp"><var class="Ft">long</var> + <br/> + <code class="Fn">lmin</code>(<var class="Fa" style="white-space: nowrap;">long + a</var>, <var class="Fa" style="white-space: nowrap;">long b</var>);</p> +<p class="Pp"><var class="Ft">u_int</var> + <br/> + <code class="Fn">uimax</code>(<var class="Fa" style="white-space: nowrap;">u_int + a</var>, <var class="Fa" style="white-space: nowrap;">u_int b</var>);</p> +<p class="Pp"><var class="Ft">u_int</var> + <br/> + <code class="Fn">uimin</code>(<var class="Fa" style="white-space: nowrap;">u_int + a</var>, <var class="Fa" style="white-space: nowrap;">u_int b</var>);</p> +<p class="Pp"><var class="Ft">u_long</var> + <br/> + <code class="Fn">ulmax</code>(<var class="Fa" style="white-space: nowrap;">u_long + a</var>, <var class="Fa" style="white-space: nowrap;">u_long b</var>);</p> +<p class="Pp"><var class="Ft">u_long</var> + <br/> + <code class="Fn">ulmin</code>(<var class="Fa" style="white-space: nowrap;">u_long + a</var>, <var class="Fa" style="white-space: nowrap;">u_long b</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#imin"><code class="Fn" id="imin">imin</code></a>(), + <a class="permalink" href="#lmin"><code class="Fn" id="lmin">lmin</code></a>(), + <a class="permalink" href="#uimin"><code class="Fn" id="uimin">uimin</code></a>(), + and + <a class="permalink" href="#ulmin"><code class="Fn" id="ulmin">ulmin</code></a>() + functions return whichever argument is algebraically smaller, differing only + in their argument and return types: these functions operate on, + respectively, natural size, long, unsigned and unsigned long integers.</p> +<p class="Pp" id="imax">The + <a class="permalink" href="#imax"><code class="Fn">imax</code></a>(), + <a class="permalink" href="#lmax"><code class="Fn" id="lmax">lmax</code></a>(), + <a class="permalink" href="#uimax"><code class="Fn" id="uimax">uimax</code></a>(), + and + <a class="permalink" href="#ulmax"><code class="Fn" id="ulmax">ulmax</code></a>() + functions are identical except that they return the algebraically larger + argument between <var class="Ar">a</var> and <var class="Ar">b</var>.</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">ilog2(3)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 10, 2024</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/inittodr.9 3.html b/static/netbsd/man9/inittodr.9 3.html new file mode 100644 index 00000000..b8f919ad --- /dev/null +++ b/static/netbsd/man9/inittodr.9 3.html @@ -0,0 +1,74 @@ +<table class="head"> + <tr> + <td class="head-ltitle">INITTODR(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">INITTODR(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">inittodr</code> — + <span class="Nd">initialize system time</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">inittodr</code>(<var class="Fa" style="white-space: nowrap;">time_t + base</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#inittodr"><code class="Fn" id="inittodr">inittodr</code></a>() + function determines the time and sets the system clock. It tries to pick the + correct time using a set of heuristics that examine the system's + battery-backed clock and the time reported by the file system, as given in + <var class="Fa">base</var>. Those heuristics include:</p> +<ul class="Bl-bullet"> + <li>If the battery-backed clock has a valid time, and is not significantly + behind the time provided by <var class="Fa">base</var>, it is used.</li> + <li>If the battery-backed clock does not have a valid time, or is + significantly behind the time provided in <var class="Fa">base</var>, and + the time provided in <var class="Fa">base</var> is within reason, + <var class="Fa">base</var> is used as the current time.</li> + <li>If the battery-backed clock appears invalid, and + <var class="Fa">base</var> appears non-sensical or was not provided (was + given as zero), an arbitrary base (typically some time within the same + year that the kernel was last updated) will be used.</li> +</ul> +<p class="Pp">Once a system time has been determined, it is stored in the + <var class="Va">time</var> variable.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">The <code class="Fn">inittodr</code>() function prints diagnostic + messages if it has trouble figuring out the system time. Conditions that can + cause diagnostic messages to be printed include:</p> +<ul class="Bl-bullet"> + <li>There is no battery-backed clock present on the system.</li> + <li>The battery-backed clock's time appears nonsensical.</li> + <li>The <var class="Fa">base</var> time appears nonsensical.</li> + <li>The <var class="Fa">base</var> time and the battery-backed clock's time + differ by a large amount.</li> +</ul> +</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">clock_ymdhms_to_secs(9)</a>, + <a class="Xr">resettodr(9)</a>, <a class="Xr">time_second(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Some systems use heuristics for picking the correct time that are + slightly different.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 6, 2006</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/interrupt_distribute.9 3.html b/static/netbsd/man9/interrupt_distribute.9 3.html new file mode 100644 index 00000000..7cf9b23e --- /dev/null +++ b/static/netbsd/man9/interrupt_distribute.9 3.html @@ -0,0 +1,44 @@ +<table class="head"> + <tr> + <td class="head-ltitle">INTERRUPT_DISTRIBUTE(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">INTERRUPT_DISTRIBUTE(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">interrupt_distribute</code> — + <span class="Nd">assign an interrupt to a CPU</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/interrupt.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">interrupt_distribute</code>(<var class="Fa" style="white-space: nowrap;">void + *ich</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *newset</var>, <var class="Fa" style="white-space: nowrap;">kcpuset_t + *oldset</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">interrupt_distribute</code> function exists + to assign an interrupt to a CPU.</p> +<p class="Pp" id="pci_intr_establish">If a driver (or the other kernel + component) wishes to assign an interrupt to a CPU, it should pass an + interrupt handler such as the return value of + <a class="permalink" href="#pci_intr_establish"><code class="Fn">pci_intr_establish</code></a>() + as <var class="Fa">ich</var> argument, and it should pass the kcpuset to + which it should be assigned as <var class="Fa">newset</var>. To get the + previous value, pass a non-<code class="Dv">NULL</code> value to + <var class="Ft">oldset</var>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 17, 2015</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/intro.9 3.html b/static/netbsd/man9/intro.9 3.html new file mode 100644 index 00000000..e02756d7 --- /dev/null +++ b/static/netbsd/man9/intro.9 3.html @@ -0,0 +1,347 @@ +<table class="head"> + <tr> + <td class="head-ltitle">INTRO(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">INTRO(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">intro</code> — + <span class="Nd">introduction to kernel internals</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This section contains information related to the internal + operation of the system kernel. It describes function interfaces and + variables of use to the systems and device driver programmer.</p> +<p class="Pp">In addition to the normal man page format, the kernel pages + include an additional section:</p> +<dl class="Bl-tag"> + <dt>CODE REFERENCES</dt> + <dd>Contains the pathname(s) of the source file(s) which contain the + definition and/or source code of the variables or functions being + documented. Any paths are relative to the top level of the source tree + (traditionally <span class="Pa">/usr/src</span>).</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="MEMORY_MANAGEMENT"><a class="permalink" href="#MEMORY_MANAGEMENT">MEMORY + MANAGEMENT</a></h1> +<p class="Pp">Introduction to kernel memory allocators. See + <a class="Xr">memoryallocators(9)</a>.</p> +<p class="Pp">Machine-dependent portion of the virtual memory system. See + <a class="Xr">pmap(9)</a>.</p> +<p class="Pp">Virtual memory system external interface. See + <a class="Xr">uvm(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="I/O_SUBSYSTEM"><a class="permalink" href="#I/O_SUBSYSTEM">I/O + SUBSYSTEM</a></h1> +<p class="Pp">Buffer cache interfaces. See <a class="Xr">buffercache(9)</a>.</p> +<p class="Pp">Device buffer queues. See <a class="Xr">bufq(9)</a>.</p> +<p class="Pp">Initiate I/O on raw devices. See <a class="Xr">physio(9)</a>.</p> +<p class="Pp">I/O descriptor allocation interface. See + <a class="Xr">getiobuf(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="PROCESS_CONTROL"><a class="permalink" href="#PROCESS_CONTROL">PROCESS + CONTROL</a></h1> +<p class="Pp">Idle CPU while waiting for work. See + <a class="Xr">cpu_idle(9)</a>.</p> +<p class="Pp">Finish a fork operation. See + <a class="Xr">cpu_lwp_fork(9)</a>.</p> +<p class="Pp">Switch to another light weight process. See + <a class="Xr">mi_switch(9)</a>.</p> +<p class="Pp">Current process and processor. See + <a class="Xr">curproc(9)</a>.</p> +<p class="Pp">Set process uid and gid. See + <a class="Xr">do_setresuid(9)</a>.</p> +<p class="Pp">New processes and kernel threads. See <a class="Xr">fork1(9)</a>, + <a class="Xr">kthread(9)</a>.</p> +<p class="Pp">Context switch notification. See + <a class="Xr">cpu_need_resched(9)</a>.</p> +<p class="Pp">Common scheduler framework. See <a class="Xr">csf(9)</a>.</p> +<p class="Pp">Software signal facilities. See <a class="Xr">signal(9)</a>.</p> +<p class="Pp">Suspend the scheduler. See <a class="Xr">suspendsched(9)</a>.</p> +<p class="Pp">Return path to user-mode execution. See + <a class="Xr">userret(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILE_SYSTEM"><a class="permalink" href="#FILE_SYSTEM">FILE + SYSTEM</a></h1> +<p class="Pp">High-level file operations. See + <a class="Xr">dofileread(9)</a>.</p> +<p class="Pp">Convert an extended attribute namespace identifier to a string and + vice versa. See <a class="Xr">extattr(9)</a>.</p> +<p class="Pp">Operations on file entries. See <a class="Xr">file(9)</a>.</p> +<p class="Pp">In-kernel, file system independent, file-meta data association. + See <a class="Xr">fileassoc(9)</a>.</p> +<p class="Pp">File descriptor tables and operations. See + <a class="Xr">filedesc(9)</a>.</p> +<p class="Pp">File descriptor owner handling functions. See + <a class="Xr">fsetown(9)</a>.</p> +<p class="Pp">File system suspension helper subsystem. See + <a class="Xr">fstrans(9)</a>.</p> +<p class="Pp">Pathname lookup, cache and management. See + <a class="Xr">namei(9)</a>, <a class="Xr">namecache(9)</a>.</p> +<p class="Pp">Kernel interface to file systems. See + <a class="Xr">vfs(9)</a>.</p> +<p class="Pp">Kernel representation of a file or directory and vnode attributes. + See <a class="Xr">vnode(9)</a>, <a class="Xr">vattr(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="NETWORKING"><a class="permalink" href="#NETWORKING">NETWORKING</a></h1> +<p class="Pp">Kernel interfaces for manipulating output queues on network + interfaces. See <a class="Xr">altq(9)</a>.</p> +<p class="Pp">Externally visible ARP functions. See + <a class="Xr">arp(9)</a>.</p> +<p class="Pp">Ethernet and FDDI driver support functions and macros. See + <a class="Xr">ethersubr(9)</a>.</p> +<p class="Pp">Core 802.11 network stack functions and rate adaptation based on + received signal strength. See <a class="Xr">ieee80211(9)</a>, + <a class="Xr">rssadapt(9)</a>.</p> +<p class="Pp">Compute Internet checksum. See <a class="Xr">in_cksum(9)</a>.</p> +<p class="Pp">Look up the IPv4 source address best matching an IPv4 destination. + See <a class="Xr">in_getifa(9)</a>.</p> +<p class="Pp">Functions and macros for managing memory used by networking code. + See <a class="Xr">mbuf(9)</a>.</p> +<p class="Pp">Packet filter interface. See <a class="Xr">pfil(9)</a>.</p> +<p class="Pp">Route callout functions. See <a class="Xr">rt_timer(9)</a>.</p> +<p class="Pp">TCP congestion control API. See + <a class="Xr">tcp_congctl(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="LOCKING_AND_INTERRUPT_CONTROL"><a class="permalink" href="#LOCKING_AND_INTERRUPT_CONTROL">LOCKING + AND INTERRUPT CONTROL</a></h1> +<p class="Pp">See <a class="Xr">locking(9)</a> for an overview.</p> +<p class="Pp">Condition variables. See <a class="Xr">condvar(9)</a>.</p> +<p class="Pp">Kernel lock functions. See <a class="Xr">lock(9)</a>.</p> +<p class="Pp">Memory barriers. See <a class="Xr">membar_ops(3)</a>.</p> +<p class="Pp">Mutual exclusion primitives. See <a class="Xr">mutex(9)</a>.</p> +<p class="Pp">Restartable atomic sequences. See <a class="Xr">ras(9)</a>.</p> +<p class="Pp">Reader / writer lock primitives. See + <a class="Xr">rwlock(9)</a>.</p> +<p class="Pp">Machine-independent software interrupt framework. See + <a class="Xr">softint(9)</a>.</p> +<p class="Pp">Functions to modify system interrupt priority level. See + <a class="Xr">spl(9)</a>.</p> +<p class="Pp">Functions to raise the system priority level. See + <a class="Xr">splraiseipl(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SECURITY"><a class="permalink" href="#SECURITY">SECURITY</a></h1> +<p class="Pp">Kernel authorization framework. See + <a class="Xr">kauth(9)</a>.</p> +<p class="Pp">API for cryptographic services in the kernel. See + <a class="Xr">opencrypto(9)</a>.</p> +<p class="Pp">Security model development guidelines. See + <a class="Xr">secmodel(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYSTEM_TIME_CONTROL"><a class="permalink" href="#SYSTEM_TIME_CONTROL">SYSTEM + TIME CONTROL</a></h1> +<p class="Pp">Execute a function after a specified length of time. See + <a class="Xr">callout(9)</a>.</p> +<p class="Pp">Microsecond delay. See <a class="Xr">delay(9)</a>.</p> +<p class="Pp">Real-time timer. See <a class="Xr">hardclock(9)</a>.</p> +<p class="Pp">System clock frequency. See <a class="Xr">hz(9)</a>.</p> +<p class="Pp">Initialization of system time and time-of-day clock support. See + <a class="Xr">inittodr(9)</a>, <a class="Xr">todr(9)</a>.</p> +<p class="Pp">Check that a timeval value is valid, and correct. See + <a class="Xr">itimerfix(9)</a>.</p> +<p class="Pp">System time variables. See <a class="Xr">timecounter(9)</a>.</p> +<p class="Pp">Realtime system clock. See <a class="Xr">microtime(9)</a>.</p> +<p class="Pp">Get the time elapsed since boot. See + <a class="Xr">microuptime(9)</a>.</p> +<p class="Pp">Convert milliseconds to system clock ticks. See + <a class="Xr">mstohz(9)</a>.</p> +<p class="Pp">Function to help implement rate-limited actions. See + <a class="Xr">ppsratecheck(9)</a>.</p> +<p class="Pp">Function to help implement rate-limited actions. See + <a class="Xr">ratecheck(9)</a>.</p> +<p class="Pp">Set battery-backed clock from system time. See + <a class="Xr">resettodr(9)</a>.</p> +<p class="Pp">System time variables. See <a class="Xr">time_second(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="KERNEL_AND_USER_SPACE_DATA_COPY_FUNCTIONS"><a class="permalink" href="#KERNEL_AND_USER_SPACE_DATA_COPY_FUNCTIONS">KERNEL + AND USER SPACE DATA COPY FUNCTIONS</a></h1> +<p class="Pp">Kernel space to/from user space copy functions. See + <a class="Xr">copy(9)</a>.</p> +<p class="Pp">Store data to user-space. See <a class="Xr">ustore(9)</a>.</p> +<p class="Pp">Fetch data from user-space. See <a class="Xr">ufetch(9)</a>.</p> +<p class="Pp">Move data described by a struct uio. See + <a class="Xr">uiomove(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MACHINE_DEPENDENT_KERNEL_FUNCTIONS"><a class="permalink" href="#MACHINE_DEPENDENT_KERNEL_FUNCTIONS">MACHINE + DEPENDENT KERNEL FUNCTIONS</a></h1> +<p class="Pp">Machine-dependent clock setup interface. See + <a class="Xr">cpu_initclocks(9)</a>.</p> +<p class="Pp">Machine-dependent process core dump interface. See + <a class="Xr">cpu_coredump(9)</a>.</p> +<p class="Pp">Machine-dependent kernel core dumps. See + <a class="Xr">cpu_dumpconf(9)</a>.</p> +<p class="Pp">Unique CPU identification number See + <a class="Xr">cpu_number(9)</a>.</p> +<p class="Pp">Halt or reboot the system See <a class="Xr">cpu_reboot(9)</a>.</p> +<p class="Pp">Machine-dependent root file system setup See + <a class="Xr">cpu_rootconf(9)</a>.</p> +<p class="Pp">Machine-dependent CPU startup See + <a class="Xr">cpu_startup(9)</a>.</p> +<p class="Pp">Disk label management routines. See + <a class="Xr">disklabel(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DEVICE_CONFIGURATION"><a class="permalink" href="#DEVICE_CONFIGURATION">DEVICE + CONFIGURATION</a></h1> +<p class="Pp">Autoconfiguration frame-work. See + <a class="Xr">autoconf(9)</a>.</p> +<p class="Pp">Description of a device driver. See + <a class="Xr">driver(9)</a>.</p> +<p class="Pp">The autoconfiguration framework ``device definition'' language. + See <a class="Xr">config(9)</a>.</p> +<p class="Pp">Machine-dependent device autoconfiguration. See + <a class="Xr">cpu_configure(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MI_DEVICE_DRIVER_API"><a class="permalink" href="#MI_DEVICE_DRIVER_API">MI + DEVICE DRIVER API</a></h1> +<p class="Pp">Bus and Machine Independent DMA Mapping Interface. See + <a class="Xr">bus_dma(9)</a>.</p> +<p class="Pp">Bus space manipulation functions. See + <a class="Xr">bus_space(9)</a>.</p> +<p class="Pp">Generic disk framework. See <a class="Xr">disk(9)</a>.</p> +<p class="Pp">Hardware-assisted data mover interface. See + <a class="Xr">dmover(9)</a>. Generic event counter framework. See + <a class="Xr">evcnt(9)</a>.</p> +<p class="Pp">Firmware loader API for device drivers. See + <a class="Xr">firmload(9)</a>.</p> +<p class="Pp">How to implement a new ioctl call to access device drivers. See + <a class="Xr">ioctl(9)</a>.</p> +<p class="Pp">Extensible line discipline framework. See + <a class="Xr">linedisc(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CONSOLE_DEVICES"><a class="permalink" href="#CONSOLE_DEVICES">CONSOLE + DEVICES</a></h1> +<p class="Pp">Console magic key sequence management. See + <a class="Xr">cnmagic(9)</a>.</p> +<p class="Pp">Console access interface. See <a class="Xr">cons(9)</a>.</p> +<p class="Pp">Raster display operations. See <a class="Xr">rasops(9)</a>.</p> +<p class="Pp">Generic virtual console framework. See + <a class="Xr">vcons(9)</a>.</p> +<p class="Pp">Machine-independent console support. See + <a class="Xr">wscons(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DEVICE_SPECIFIC_IMPLEMENTATION"><a class="permalink" href="#DEVICE_SPECIFIC_IMPLEMENTATION">DEVICE + SPECIFIC IMPLEMENTATION</a></h1> +<p class="Pp">Interface between low and high level audio drivers. See + <a class="Xr">audio(9)</a>.</p> +<p class="Pp">Bluetooth Device/Protocol API. See + <a class="Xr">bluetooth(9)</a>.</p> +<p class="Pp">Support for CardBus PC-Card devices. See + <a class="Xr">cardbus(9)</a>.</p> +<p class="Pp">VESA Display Data Channel V2. See <a class="Xr">ddc(9)</a>.</p> +<p class="Pp">VESA Extended Display Identification Data. See + <a class="Xr">edid(9)</a>.</p> +<p class="Pp">Inter IC (I2C) bus. See <a class="Xr">iic(9)</a>.</p> +<p class="Pp">Baseboard I/O control ASIC for DEC TURBOchannel systems. See + <a class="Xr">ioasic(9)</a>.</p> +<p class="Pp">Industry-standard Architecture. See <a class="Xr">isa(9)</a>.</p> +<p class="Pp">Introduction to ISA Plug-and-Play support. See + <a class="Xr">isapnp(9)</a>.</p> +<p class="Pp">MicroChannel Architecture bus. See <a class="Xr">mca(9)</a>.</p> +<p class="Pp">PPBUS microseqencer developer's guide. See + <a class="Xr">microseq(9)</a>.</p> +<p class="Pp">Peripheral Component Interconnect. See + <a class="Xr">pci(9)</a>.</p> +<p class="Pp">Perform PCI bus configuration. See + <a class="Xr">pci_configure_bus(9)</a>.</p> +<p class="Pp">PCI bus interrupt manipulation functions. See + <a class="Xr">pci_intr(9)</a>.</p> +<p class="Pp">PC keyboard port interface. See <a class="Xr">pckbport(9)</a>.</p> +<p class="Pp">Support for PCMCIA PC-Card devices. See + <a class="Xr">pcmcia(9)</a>.</p> +<p class="Pp">Interface between low and high level radio drivers. See + <a class="Xr">radio(9)</a>.</p> +<p class="Pp">Functions to make a device available for entropy collection. See + <a class="Xr">rnd(9)</a>.</p> +<p class="Pp">SCSI/ATAPI middle-layer interface. See + <a class="Xr">scsipi(9)</a>.</p> +<p class="Pp">TURBOchannel bus. See <a class="Xr">tc(9)</a>.</p> +<p class="Pp">USB tty support. See <a class="Xr">ucom(9)</a>.</p> +<p class="Pp">USB device drivers interface. See <a class="Xr">usbdi(9)</a>.</p> +<p class="Pp">Versa Module Euroboard bus. See <a class="Xr">vme(9)</a>.</p> +<p class="Pp">Machine-independent IDE/ATAPI driver. See + <a class="Xr">wdc(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="KERNEL_EVENT"><a class="permalink" href="#KERNEL_EVENT">KERNEL + EVENT</a></h1> +<p class="Pp">Functions to add or remove kernel event filters. See + <a class="Xr">kfilter_register(9)</a>.</p> +<p class="Pp">Functions to raise kernel event. See + <a class="Xr">knote(9)</a>.</p> +<p class="Pp">Record and wakeup select requests. See + <a class="Xr">selrecord(9)</a>.</p> +<p class="Pp">Simple do-it-in-thread-context framework. See + <a class="Xr">workqueue(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="KERNEL_HELPER_FUNCTIONS"><a class="permalink" href="#KERNEL_HELPER_FUNCTIONS">KERNEL + HELPER FUNCTIONS</a></h1> +<p class="Pp">Kernel expression verification macros. See + <a class="Xr">KASSERT(9)</a>.</p> +<p class="Pp">Convert a single byte between (unsigned) packed bcd and binary. + See <a class="Xr">bcdtobin(9)</a>.</p> +<p class="Pp">Bitmask output conversion. See <a class="Xr">snprintb(3)</a>.</p> +<p class="Pp">General purpose extent manager. See + <a class="Xr">extent(9)</a>.</p> +<p class="Pp">Compare integers. See <a class="Xr">imax(9)</a>.</p> +<p class="Pp">Kernel formatted output conversion. See + <a class="Xr">kprintf(9)</a>.</p> +<p class="Pp">Data comparing, moving, copying, setting and cleaning. See + <a class="Xr">memcmp(9)</a>, <a class="Xr">memmove(9)</a>, + <a class="Xr">memcpy(9)</a>, <a class="Xr">memset(9)</a>, + <a class="Xr">bcmp(9)</a>, <a class="Xr">bcopy(9)</a>, + <a class="Xr">bzero(9)</a>, <a class="Xr">kcopy(9)</a>.</p> +<p class="Pp">Log a message from the kernel through the /dev/klog device. See + <a class="Xr">log(9)</a>.</p> +<p class="Pp">Bring down system on fatal error. See + <a class="Xr">panic(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MISC"><a class="permalink" href="#MISC">MISC</a></h1> +<p class="Pp">Power management and inter-driver messaging. See + <a class="Xr">pmf(9)</a>.</p> +<p class="Pp">Run all shutdown hooks. See + <a class="Xr">pmf_system_shutdown(9)</a>.</p> +<p class="Pp">Kernel internal error numbers. See <a class="Xr">errno(9)</a>.</p> +<p class="Pp">Kernel hash functions, hash table construction and destruction. + See <a class="Xr">hash(9)</a>, <a class="Xr">hashinit(9)</a>.</p> +<p class="Pp">Format a number into a human readable form. See + <a class="Xr">humanize_number(9)</a>.</p> +<p class="Pp">Options string management. See <a class="Xr">optstr(9)</a>.</p> +<p class="Pp">Performs pattern matching on strings. See + <a class="Xr">pmatch(9)</a>.</p> +<p class="Pp">Add or remove a shutdown hook. See <a class="Xr">pmf(9)</a>.</p> +<p class="Pp">Non-local jumps. See <a class="Xr">setjmp(9)</a>.</p> +<p class="Pp">System variable control interfaces. See + <a class="Xr">sysctl(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <span class="Ux">NetBSD</span> kernel internals section first + appeared in <span class="Ux">NetBSD 1.2</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 14, 2018</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/ioctl.9 3.html b/static/netbsd/man9/ioctl.9 3.html new file mode 100644 index 00000000..db973c99 --- /dev/null +++ b/static/netbsd/man9/ioctl.9 3.html @@ -0,0 +1,289 @@ +<table class="head"> + <tr> + <td class="head-ltitle">IOCTL(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">IOCTL(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">ioctl</code> — <span class="Nd">how to + implement a new ioctl call to access device drivers</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/ioctl.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/ioccom.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">ioctl</code>(<var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">unsigned long</var>, + <var class="Fa" style="white-space: nowrap;">...</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">ioctl</code> are internally defined as</p> +<dl class="Bl-tag"> + <dt>#define FOOIOCTL fun(t,n,pt)</dt> + <dd style="width: auto;"> </dd> +</dl> +<p class="Pp">where the different variables and functions are:</p> +<dl class="Bl-tag"> + <dt id="FOOIOCTL"><a class="permalink" href="#FOOIOCTL"><code class="Cm">FOOIOCTL</code></a></dt> + <dd>the name which will later be given in the <a class="Xr">ioctl(2)</a> + system call as second argument, e.g., + <div class="Bd Bd-indent"><code class="Li">ioctl(s, FOOIOCTL, + ...)</code></div> + .</dd> + <dt id="fun"><a class="permalink" href="#fun"><code class="Fn">fun</code></a>()</dt> + <dd>a macro which can be one of + <dl class="Bl-tag"> + <dt>_IO</dt> + <dd>the call is a simple message to the kernel by itself. It does not copy + anything into the kernel, nor does it want anything back.</dd> + <dt>_IOR</dt> + <dd>the call only reads parameters from the kernel and does not pass any + to it</dd> + <dt>_IOW</dt> + <dd>the call only writes parameters to the kernel, but does not want + anything back</dd> + <dt>_IOWR</dt> + <dd>the call writes data to the kernel and wants information back.</dd> + </dl> + </dd> + <dt><var class="Ar">t</var></dt> + <dd>This integer describes to which subsystem the ioctl applies. + <var class="Ar">t</var> can be one of + <dl class="Bl-tag Bl-compact"> + <dt>'1'</dt> + <dd>pulse-per-second interface</dd> + <dt>'a'</dt> + <dd>ISO networking</dd> + <dt>'A'</dt> + <dd>ac devices (hp300)</dd> + <dt>'A'</dt> + <dd>Advanced Power Management (hpcmips, i386, sparc), see + <a class="Xr">apm(4)</a></dd> + <dt>'A'</dt> + <dd>ADB devices (mac68k, macppc)</dd> + <dt>'A'</dt> + <dd><a class="Xr">audio(4)</a></dd> + <dt>'b'</dt> + <dd>Bluetooth HCI sockets, see <a class="Xr">bluetooth(4)</a></dd> + <dt>'b'</dt> + <dd>Bluetooth Hub Control, see <a class="Xr">bthub(4)</a></dd> + <dt>'b'</dt> + <dd>Bluetooth SCO audio driver, see <a class="Xr">btsco(4)</a></dd> + <dt>'B'</dt> + <dd>bell device (x68k)</dd> + <dt>'B'</dt> + <dd><a class="Xr">bpf(4)</a></dd> + <dt>'c'</dt> + <dd>coda</dd> + <dt>'c'</dt> + <dd><a class="Xr">cd(4)</a></dd> + <dt>'c'</dt> + <dd><a class="Xr">ch(4)</a></dd> + <dt>'C'</dt> + <dd>clock devices (amiga, atari, hp300, x68k)</dd> + <dt>'d'</dt> + <dd>the disk subsystem</dd> + <dt>'E'</dt> + <dd><a class="Xr">envsys(4)</a></dd> + <dt>'f'</dt> + <dd>files</dd> + <dt>'F'</dt> + <dd>Sun-compatible framebuffers</dd> + <dt>'F'</dt> + <dd><a class="Xr">ccd(4)</a> and <a class="Xr">vnd(4)</a></dd> + <dt>'g'</dt> + <dd>qdss framebuffers</dd> + <dt>'G'</dt> + <dd>grf devices (amiga, atari, hp300, mac68k, x68k)</dd> + <dt>'h'</dt> + <dd>HIL devices (hp300)</dd> + <dt>'H'</dt> + <dd>HIL devices (hp300)</dd> + <dt>'H'</dt> + <dd>HPc framebuffers</dd> + <dt>'i'</dt> + <dd>a (pseudo) interface</dd> + <dt>'I'</dt> + <dd><a class="Xr">ite(4)</a> (mac68k)</dd> + <dt>'J'</dt> + <dd>ISA joystick interface</dd> + <dt>'k'</dt> + <dd>Sun-compatible (and other) keyboards</dd> + <dt>'l'</dt> + <dd>leo devices (atari)</dd> + <dt>'m'</dt> + <dd><a class="Xr">mtio(4)</a></dd> + <dt>'M'</dt> + <dd>mouse devices (atari)</dd> + <dt>'M'</dt> + <dd><a class="Xr">mlx(4)</a></dd> + <dt>'n'</dt> + <dd>virtual console device (arm32)</dd> + <dt>'n'</dt> + <dd>SMB networking</dd> + <dt>'O'</dt> + <dd>OpenPROM and OpenFirmware</dd> + <dt>'p'</dt> + <dd>power control (x68k)</dd> + <dt>'P'</dt> + <dd>parallel port (amiga, x68k)</dd> + <dt>'P'</dt> + <dd>profiling (arm32)</dd> + <dt>'P'</dt> + <dd>printer/plotter interface (hp300)</dd> + <dt>'P'</dt> + <dd>pci(4)</dd> + <dt>'P'</dt> + <dd>compat/ossaudio and soundcard.h</dd> + <dt>'P'</dt> + <dd><a class="Xr">sparc/magma(4)</a> bpp (sparc)</dd> + <dt>'q'</dt> + <dd><a class="Xr">altq(9)</a></dd> + <dt>'q'</dt> + <dd>pmax graphics devices</dd> + <dt>'Q'</dt> + <dd><a class="Xr">altq(9)</a></dd> + <dt>'Q'</dt> + <dd>raw SCSI commands</dd> + <dt>'r'</dt> + <dd>the routing subsystem</dd> + <dt>'r'</dt> + <dd><a class="Xr">md(4)</a></dd> + <dt>'R'</dt> + <dd><a class="Xr">rnd(4)</a></dd> + <dt>'s'</dt> + <dd>the socket layer</dd> + <dt>'S'</dt> + <dd>SCSI disks (arc, hp300, pmax)</dd> + <dt>'S'</dt> + <dd>watchdog devices (sh3)</dd> + <dt>'S'</dt> + <dd>ISA speaker devices</dd> + <dt>'S'</dt> + <dd>stic devices</dd> + <dt>'S'</dt> + <dd>scanners</dd> + <dt>'t'</dt> + <dd>the tty layer</dd> + <dt>'u'</dt> + <dd>user defined ???</dd> + <dt>'U'</dt> + <dd>scsibus (see <a class="Xr">scsi(4)</a>)</dd> + <dt>'v'</dt> + <dd>Sun-compatible “firm events”</dd> + <dt>'V'</dt> + <dd>view device (amiga, atari)</dd> + <dt>'V'</dt> + <dd>sram device (x68k)</dd> + <dt>'w'</dt> + <dd>watchdog devices</dd> + <dt>'W'</dt> + <dd>wt devices</dd> + <dt>'W'</dt> + <dd>wscons devices</dd> + <dt>'x'</dt> + <dd>bt8xx devices</dd> + <dt>'Z'</dt> + <dd>ite devices (amiga, atari, x68k)</dd> + <dt>'Z'</dt> + <dd>passthrough ioctls</dd> + </dl> + </dd> + <dt><var class="Ar">n</var></dt> + <dd>This numbers the ioctl within the group. There may be only one + <var class="Ar">n</var> for a given <var class="Ar">t</var>. This is an + unsigned 8 bit number.</dd> + <dt><var class="Ar">pt</var></dt> + <dd>This specifies the type of the passed parameter. This one gets internally + transformed to the size of the parameter, so for example, if you want to + pass a structure, then you have to specify that structure and not a + pointer to it or sizeof(struct foo)</dd> +</dl> +<p class="Pp">In order for the new ioctl to be known to the system it is + installed in either ⟨<span class="Pa">sys/ioctl.h</span>⟩ or + one of the files that are reached from + ⟨<span class="Pa">sys/ioctl.h</span>⟩.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">All <code class="Fn">ioctl</code>() routines should return either + 0 or a defined error code. The use of magic numbers such as -1, to indicate + that a given ioctl code was not handled is strongly discouraged. The value + -1 coincides with the historic value for <code class="Cm">ERESTART</code> + which was shown to produce user space code that never returned from a call + to <a class="Xr">ioctl(2)</a>.</p> +<p class="Pp">For ioctl codes that are not handled by a given routine, the + pseudo error value <code class="Cm">EPASSTHROUGH</code> is provided. + <code class="Cm">EPASSTHROUGH</code> indicates that no error occurred during + processing (it did not fail), but neither was anything processed (it did not + succeed). This supersedes the use of either <code class="Cm">ENOTTY</code> + (which is an explicit failure) or -1 (which has no contextual meaning) as a + return value. <code class="Cm">ENOTTY</code> will get passed directly back + to user space and bypass any further processing by other ioctl layers. Only + code that wishes to suppress possible further processing of an ioctl code + (e.g., the tty line discipline code) should return + <code class="Cm">ENOTTY</code>. All other code should return + <code class="Cm">EPASSTHROUGH</code>, even if it knows that no other layers + will be called upon.</p> +<p class="Pp">If the value <code class="Cm">EPASSTHROUGH</code> is returned to + <code class="Fn">sys_ioctl</code>(), then it will there be changed to + <code class="Cm">ENOTTY</code> to be returned to user space, thereby + providing the proper error notification to the application.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<div class="Bd Bd-indent Li"> +<pre>#define FOOIOCTL _IOWR('i', 23, int) + +int a = 3; +error = ioctl(s, FOOIOCTL, &a);</pre> +</div> +<p class="Pp">Within the + <code class="Fn">ioctl</code>()<span class="No">-routine</span> of the + driver, it can be then accessed like</p> +<div class="Bd Pp Bd-indent Li"> +<pre>driver_ioctl(..., u_long cmd, void *data) +{ + ... + switch (cmd) { + + case FOOIOCTL: + int *a = (int *)data; + printf(" Value passed: %d\n", *a); + break; + } +}</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp">Note that if you for example try to read information from an + ethernet driver where the name of the card is included in the third argument + (e.g., ioctl(s, READFROMETH, struct ifreq *)), then you have to use the + <a class="permalink" href="#_IOWR"><code class="Fn" id="_IOWR">_IOWR</code></a>() + form not the + <a class="permalink" href="#_IOR"><code class="Fn" id="_IOR">_IOR</code></a>(), + as passing the name of the card to the kernel already consists of writing + data.</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">ioctl(2)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 7, 2022</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/isr_add.9 b/static/netbsd/man9/isr_add.9 new file mode 100644 index 00000000..d834441d --- /dev/null +++ b/static/netbsd/man9/isr_add.9 @@ -0,0 +1,124 @@ +.\" $NetBSD: isr_add.9,v 1.10 2019/12/27 09:41:48 msaitoh Exp $ +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jeremy Cooper. +.\" +.\" 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 May 21, 1997 +.Dt ISR_ADD 9 sun3 +.Os +.Sh NAME +.Nm isr_add , +.Nm isr_add_autovect , +.Nm isr_add_vectored , +.Nm isr_add_custom +.Nd establish interrupt handler +.Sh SYNOPSIS +.In sun3/autoconf.h +.Bd -literal +typedef int (*isr_func_t)(void *); +.Ed +.Ft void +.Fn isr_add_autovect "isr_func_t fun" "void *arg" "int level" +.Ft void +.Fn isr_add_vectored "isr_func_t fun" "void *arg" "int pri" "int vec" +.Ft void +.Fn isr_add_custom "int level" "void *fun" +.Sh DESCRIPTION +The +.Nm +functions establish interrupt handlers into the system interrupt dispatch table +and are typically called from device drivers during the autoconfiguration +process. +.Pp +There are two types of interrupts in the Motorola 68000 architecture, +which differ in the way that an interrupt request is mapped to a dispatch +function within the interrupt vector table. +.Pp +When the CPU detects an asserted signal on one of its interrupt request lines, +it suspends normal instruction execution and begins an interrupt acknowledge +cycle on the system bus. +During this cycle the interrupting device directs how the CPU is to dispatch +its interrupt request. +.Pp +If the interrupting device is integrated tightly with the system bus, +it provides an 8-bit interrupt vector number to the CPU and a +.Sy vectored +interrupt occurs. +This vector number points to a vector entry within the interrupt +vector table to which instruction execution is immediately transferred. +.Pp +If the interrupting device cannot provide a vector number, +it asserts a specialized bus line and an +.Sy autovectored +interrupt occurs. +The vector number to use is determined by adding the interrupt priority +.Pq 0\(en6 +to an autovector base +.Pq typically Li 18 hexadecimal . +.Pp +.Bl -tag -width isr_add_autovec +.It Fn isr_add_autovect +Adds the function +.Fa fun +to the list of interrupt handlers to be called during an autovectored interrupt +of priority +.Fa level . +The pointer +.Fa arg +is passed to the function as its first argument. +.It Fn isr_add_vectored +Adds the function +.Fa fun +to the list of interrupt handlers to be called during a vectored interrupts of +priority +.Fa pri +at dispatch vector number +.Fa vec . +The pointer +.Fa arg +is passed to the function as its first argument. +.It Fn isr_add_custom +Establish function +.Fa fun +as the interrupt handler for vector +.Fa level . +The autovector base number is automatically added to +.Fa level . +.Pp +.Fa fun +is called directly as the dispatch handler and must handle all of the specifics +of saving the processor state and returning from a processor exception. +These requirements generally dictate that +.Fa fun +be written in assembler. +.El +.Sh CODE REFERENCES +.Pa sys/arch/sun3/sun3/isr.c +.Sh REFERENCES +MC68030 User's Manual, Third edition, MC68030UM/AD Rev 2, Motorola Inc. +.Sh BUGS +There is no way to remove a handler once it has been added. diff --git a/static/netbsd/man9/kcopy.9 3.html b/static/netbsd/man9/kcopy.9 3.html new file mode 100644 index 00000000..21723f5f --- /dev/null +++ b/static/netbsd/man9/kcopy.9 3.html @@ -0,0 +1,54 @@ +<table class="head"> + <tr> + <td class="head-ltitle">KCOPY(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">KCOPY(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">kcopy</code> — <span class="Nd">copy data + with abort on page fault</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">kcopy</code>(<var class="Fa" style="white-space: nowrap;">const + void *src</var>, <var class="Fa" style="white-space: nowrap;">void + *dst</var>, <var class="Fa" style="white-space: nowrap;">size_t + len</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><a class="permalink" href="#kcopy"><code class="Fn" id="kcopy">kcopy</code></a>() + copies <var class="Fa">len</var> bytes from <var class="Fa">src</var> to + <var class="Fa">dst</var>, aborting if a fatal page fault is + encountered.</p> +<p class="Pp" id="kcopy~2"><a class="permalink" href="#kcopy~2"><code class="Fn">kcopy</code></a>() + must save and restore the old fault handler since it is called by + <a class="Xr">uiomove(9)</a>, which may be in the path of servicing a + non-fatal page fault.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp"><code class="Fn">kcopy</code>() returns 0 on success and an error + number on failure.</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">errno(2)</a>, <a class="Xr">memcpy(9)</a>, + <a class="Xr">uiomove(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 6, 2017</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/kcpuset.9 3.html b/static/netbsd/man9/kcpuset.9 3.html new file mode 100644 index 00000000..cbd8d284 --- /dev/null +++ b/static/netbsd/man9/kcpuset.9 3.html @@ -0,0 +1,339 @@ +<table class="head"> + <tr> + <td class="head-ltitle">KCPUSET(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">KCPUSET(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">kcpuset</code>, + <code class="Nm">kcpuset_create</code>, + <code class="Nm">kcpuset_destroy</code>, + <code class="Nm">kcpuset_clone</code>, <code class="Nm">kcpuset_copy</code>, + <code class="Nm">kcpuset_use</code>, <code class="Nm">kcpuset_unuse</code>, + <code class="Nm">kcpuset_copyin</code>, + <code class="Nm">kcpuset_copyout</code>, + <code class="Nm">kcpuset_zero</code>, <code class="Nm">kcpuset_fill</code>, + <code class="Nm">kcpuset_set</code>, <code class="Nm">kcpuset_clear</code>, + <code class="Nm">kcpuset_isset</code>, + <code class="Nm">kcpuset_isotherset</code>, + <code class="Nm">kcpuset_iszero</code>, + <code class="Nm">kcpuset_match</code>, + <code class="Nm">kcpuset_intersect</code>, + <code class="Nm">kcpuset_merge</code>, + <code class="Nm">kcpuset_remove</code>, <code class="Nm">kcpuset_ffs</code>, + <code class="Nm">kcpuset_ffs_intersecting</code>, + <code class="Nm">kcpuset_countset</code>, + <code class="Nm">kcpuset_atomic_set</code>, + <code class="Nm">kcpuset_atomic_clear</code>, + <code class="Nm">kcpuset_atomicly_intersect</code>, + <code class="Nm">kcpuset_atomicly_merge</code>, + <code class="Nm">kcpuset_atomicly_remove</code>, + <code class="Nm">kcpuset_export_32</code> — <span class="Nd">dynamic + kernel CPU sets</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/kcpuset.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_create</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + **retkcp</var>, <var class="Fa" style="white-space: nowrap;">bool + zero</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_destroy</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_clone</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + **retkcp</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *skcp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_copy</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *dkcp</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *skcp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_use</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_unuse</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>, <var class="Fa" style="white-space: nowrap;">kcpuset_t + **lst</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">kcpuset_copyin</code>(<var class="Fa" style="white-space: nowrap;">const + cpuset_t *ucp</var>, <var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>, <var class="Fa" style="white-space: nowrap;">size_t + len</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">kcpuset_copyout</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>, <var class="Fa" style="white-space: nowrap;">cpuset_t + *ucp</var>, <var class="Fa" style="white-space: nowrap;">size_t + len</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_zero</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_fill</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_set</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>, <var class="Fa" style="white-space: nowrap;">cpuid_t + cpu</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_clear</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>, <var class="Fa" style="white-space: nowrap;">cpuid_t + cpu</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">kcpuset_isset</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t * kcp</var>, <var class="Fa" style="white-space: nowrap;">cpuid_t + cpu</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">kcpuset_isotherset</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t * kcp</var>, <var class="Fa" style="white-space: nowrap;">cpuid_t + cpu</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">kcpuset_iszero</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">kcpuset_intersecting_p</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp2</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">kcpuset_match</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp2</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_intersect</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *kcp2</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_merge</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *kcp2</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_remove</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *kcp2</var>);</p> +<p class="Pp"><var class="Ft">cpuid_t</var> + <br/> + <code class="Fn">kcpuset_ffs</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp</var>);</p> +<p class="Pp"><var class="Ft">cpuid_t</var> + <br/> + <code class="Fn">kcpuset_ffs_intersecting</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp2</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">kcpuset_countset</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_atomic_set</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>, <var class="Fa" style="white-space: nowrap;">cpuid_t + cpu</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_atomic_clear</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp</var>, <var class="Fa" style="white-space: nowrap;">cpuid_t + cpu</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_atomicly_intersect</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *kcp2</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_atomicly_merge</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *kcp2</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_atomicly_remove</code>(<var class="Fa" style="white-space: nowrap;">kcpuset_t + *kcp1</var>, <var class="Fa" style="white-space: nowrap;">const kcpuset_t + *kcp2</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kcpuset_export_u32</code>(<var class="Fa" style="white-space: nowrap;">const + kcpuset_t *kcp</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + *bitfield</var>, <var class="Fa" style="white-space: nowrap;">size_t + len</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The machine-independent <code class="Nm">kcpuset</code> subsystem + provides support for dynamic processor sets. Conceptually + <code class="Nm">kcpuset</code> can be understood to be the kernel + equivalent of the user space <a class="Xr">cpuset(3)</a> interface.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="kcpuset_create"><a class="permalink" href="#kcpuset_create"><code class="Fn">kcpuset_create</code></a>(<var class="Fa">retkcp</var>, + <var class="Fa">zero</var>)</dt> + <dd>The <code class="Fn">kcpuset_create</code>() function creates a dynamic + CPU set and stores the result to <var class="Fa">retkcp</var>. If the + boolean <var class="Fa">zero</var> is not false, the allocated set is also + initialized to zero.</dd> + <dt id="kcpuset_destroy"><a class="permalink" href="#kcpuset_destroy"><code class="Fn">kcpuset_destroy</code></a>(<var class="Fa">kcp</var>)</dt> + <dd>Destroys the CPU set <var class="Fa">kcp</var> and schedules any linked + CPU sets for deferred destruction.</dd> + <dt id="kcpuset_copy"><a class="permalink" href="#kcpuset_copy"><code class="Fn">kcpuset_copy</code></a>(<var class="Fa">dkcp</var>, + <var class="Fa">skcp</var>)</dt> + <dd>Copies the CPU set pointed by <var class="Fa">skcp</var> to + <var class="Fa">dkcp</var>.</dd> + <dt id="kcpuset_clone"><a class="permalink" href="#kcpuset_clone"><code class="Fn">kcpuset_clone</code></a>(<var class="Fa">retkcp</var>, + <var class="Fa">skcp</var>)</dt> + <dd>Creates a dynamic CPU set and stores the result to + <var class="Fa">retkcp</var> and copies the CPU set pointed by + <var class="Fa">skcp</var> to the new CPU set.</dd> + <dt id="kcpuset_use"><a class="permalink" href="#kcpuset_use"><code class="Fn">kcpuset_use</code></a>(<var class="Fa">kcp</var>)</dt> + <dd>Marks <var class="Fa">kcp</var> as being in use by increasing the + reference count of the object. Note that initially + <code class="Fn">kcpuset_create</code>() sets the reference count to + 1.</dd> + <dt id="kcpuset_unuse"><a class="permalink" href="#kcpuset_unuse"><code class="Fn">kcpuset_unuse</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">lst</var>)</dt> + <dd>Decreases the internal reference count of <var class="Fa">kcp</var>, and + on the last reference (when the count reaches zero), destroys + <var class="Fa">kcp</var>. If <var class="Fa">lst</var> is not + <code class="Dv">NULL</code>, then instead of destroying, + <var class="Fa">kcp</var> will be added to the <var class="Fa">lst</var> + list for a deferred destruction.</dd> + <dt id="kcpuset_copyin"><a class="permalink" href="#kcpuset_copyin"><code class="Fn">kcpuset_copyin</code></a>(<var class="Fa">ucp</var>, + <var class="Fa">kcp</var>, <var class="Fa">len</var>)</dt> + <dd>Copies the <var class="Fa">len</var> bytes long user-space CPU set + <var class="Fa">ucp</var> to the kernel CPU set + <var class="Fa">kcp</var>.</dd> + <dt id="kcpuset_copyout"><a class="permalink" href="#kcpuset_copyout"><code class="Fn">kcpuset_copyout</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">ucp</var>, <var class="Fa">len</var>)</dt> + <dd>Copies the kernel CPU set <var class="Fa">kcp</var> to the user-space CPU + set <var class="Fa">ucp</var>.</dd> + <dt id="kcpuset_zero"><a class="permalink" href="#kcpuset_zero"><code class="Fn">kcpuset_zero</code></a>(<var class="Fa">kcp</var>)</dt> + <dd>Clears the set <var class="Fa">kcp</var>.</dd> + <dt id="kcpuset_fill"><a class="permalink" href="#kcpuset_fill"><code class="Fn">kcpuset_fill</code></a>(<var class="Fa">kcp</var>)</dt> + <dd>Fills the whole set <var class="Fa">kcp</var> with ones.</dd> + <dt id="kcpuset_set"><a class="permalink" href="#kcpuset_set"><code class="Fn">kcpuset_set</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">cpu</var>)</dt> + <dd>Adds <var class="Fa">cpu</var> to the set <var class="Fa">kcp</var>.</dd> + <dt id="kcpuset_clear"><a class="permalink" href="#kcpuset_clear"><code class="Fn">kcpuset_clear</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">cpu</var>)</dt> + <dd>Removes <var class="Fa">cpu</var> from the set + <var class="Fa">kcp</var>.</dd> + <dt id="kcpuset_isset"><a class="permalink" href="#kcpuset_isset"><code class="Fn">kcpuset_isset</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">cpu</var>)</dt> + <dd>Returns true if <var class="Fa">cpu</var> is part of the CPU set + <var class="Fa">kcp</var>.</dd> + <dt id="kcpuset_isotherset"><a class="permalink" href="#kcpuset_isotherset"><code class="Fn">kcpuset_isotherset</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">cpu</var>)</dt> + <dd>Returns true if there any CPUs other than <var class="Fa">cpu</var> in the + CPU set <var class="Fa">kcp</var>.</dd> + <dt id="kcpuset_iszero"><a class="permalink" href="#kcpuset_iszero"><code class="Fn">kcpuset_iszero</code></a>(<var class="Fa">kcp</var>)</dt> + <dd>Returns true if the set <var class="Fa">kcp</var> is empty.</dd> + <dt id="kcpuset_match"><a class="permalink" href="#kcpuset_match"><code class="Fn">kcpuset_match</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>Compares the sets <var class="Fa">kcp1</var> and + <var class="Fa">kcp2</var>, returning true if these are identical.</dd> + <dt id="kcpuset_intersect"><a class="permalink" href="#kcpuset_intersect"><code class="Fn">kcpuset_intersect</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>Removes any CPU not set in <var class="Fa">kcp2</var> from the set + <var class="Fa">kcp1</var>.</dd> + <dt id="kcpuset_merge"><a class="permalink" href="#kcpuset_merge"><code class="Fn">kcpuset_merge</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>Merges the set <var class="Fa">kcp2</var> to the set + <var class="Fa">kcp1</var>.</dd> + <dt id="kcpuset_remove"><a class="permalink" href="#kcpuset_remove"><code class="Fn">kcpuset_remove</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>Removes any CPU present in <var class="Fa">kcp2</var> from the set + <var class="Fa">kcp1</var>.</dd> + <dt id="kcpuset_ffs"><a class="permalink" href="#kcpuset_ffs"><code class="Fn">kcpuset_ffs</code></a>(<var class="Fa">kcp</var>)</dt> + <dd>Returns the lowest numbered <var class="Ft">cpu</var> present in + <var class="Fa">kcp</var> plus 1. If <var class="Fa">kcp</var> is empty, a + value of 0 is returned. <var class="Fa">kcp</var></dd> + <dt id="kcpuset_ffs_intersecting"><a class="permalink" href="#kcpuset_ffs_intersecting"><code class="Fn">kcpuset_ffs_intersecting</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>Returns the lowest numbered <var class="Ft">cpu</var> present in the + intersection of <var class="Fa">kcp1</var> and <var class="Fa">kcp2</var> + plus 1. If the intersection is empty, a value of 0 is returned.</dd> + <dt id="kcpuset_countset"><a class="permalink" href="#kcpuset_countset"><code class="Fn">kcpuset_countset</code></a>(<var class="Fa">kcp</var>)</dt> + <dd>Counts how many CPUs are in the set <var class="Fa">kcp</var>.</dd> + <dt id="kcpuset_atomic_set"><a class="permalink" href="#kcpuset_atomic_set"><code class="Fn">kcpuset_atomic_set</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">cpu</var>)</dt> + <dd>The <code class="Fn">kcpuset_atomic_set</code>() function operates as + <code class="Fn">kcpuset_set</code>(), but the operation is atomic; see + <a class="Xr">atomic_ops(3)</a> for more details.</dd> + <dt id="kcpuset_atomic_clear"><a class="permalink" href="#kcpuset_atomic_clear"><code class="Fn">kcpuset_atomic_clear</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">cpu</var>)</dt> + <dd>Removes <var class="Fa">cpu</var> from the CPU set + <var class="Fa">kcp</var> atomically.</dd> + <dt id="kcpuset_atomicly_intersect"><a class="permalink" href="#kcpuset_atomicly_intersect"><code class="Fn">kcpuset_atomicly_intersect</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>The <code class="Fn">kcpuset_atomicly_intersect</code>() function operates + as <code class="Fn">kcpuset_intersect</code>(), but the operation is + performed using atomic operations; see <a class="Xr">atomic_ops(3)</a> for + more details.</dd> + <dt id="kcpuset_atomicly_merge"><a class="permalink" href="#kcpuset_atomicly_merge"><code class="Fn">kcpuset_atomicly_merge</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>The <code class="Fn">kcpuset_atomicly_merge</code>() function operates as + <code class="Fn">kcpuset_merge</code>(), but the operation is performed + using atomic operations; see <a class="Xr">atomic_ops(3)</a> for more + details.</dd> + <dt id="kcpuset_atomicly_remove"><a class="permalink" href="#kcpuset_atomicly_remove"><code class="Fn">kcpuset_atomicly_remove</code></a>(<var class="Fa">kcp1</var>, + <var class="Fa">kcp2</var>)</dt> + <dd>The <code class="Fn">kcpuset_atomicly_remove</code>() function operates as + <code class="Fn">kcpuset_remove</code>(), but the operation is performed + using atomic operations; see <a class="Xr">atomic_ops(3)</a> for more + details.</dd> + <dt id="kcpuset_export_u32"><a class="permalink" href="#kcpuset_export_u32"><code class="Fn">kcpuset_export_u32</code></a>(<var class="Fa">kcp</var>, + <var class="Fa">bitfield</var>, <var class="Fa">len</var>)</dt> + <dd>Exports the CPU set <var class="Fa">kcp</var> into a format of 32-bit + integer array, specified by <var class="Fa">bitfield</var> and length in + bytes by <var class="Fa">len</var>. An integers is in the host byte-order + and represents a bit field. The first bit at index zero represents CPU + number 0, and so on.</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 <code class="Nm">kcpuset</code> subsystem is implemented + within <span class="Pa">sys/kern/subr_kcpuset.c</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">cpuset(3)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">kcpuset</code> subsystem first appeared in + <span class="Ux">NetBSD 6.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 17, 2013</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/kmem.9 3.html b/static/netbsd/man9/kmem.9 3.html new file mode 100644 index 00000000..1acd9611 --- /dev/null +++ b/static/netbsd/man9/kmem.9 3.html @@ -0,0 +1,297 @@ +<table class="head"> + <tr> + <td class="head-ltitle">KMEM(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">KMEM(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">kmem</code> — <span class="Nd">kernel + wired memory allocator</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/kmem.h</a>></code></p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">kmem_alloc</code>(<var class="Fa" style="white-space: nowrap;">size_t + size</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">kmem_zalloc</code>(<var class="Fa" style="white-space: nowrap;">size_t + size</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kmem_free</code>(<var class="Fa" style="white-space: nowrap;">void + *p</var>, <var class="Fa" style="white-space: nowrap;">size_t + size</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">kmem_intr_alloc</code>(<var class="Fa" style="white-space: nowrap;">size_t + size</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">kmem_intr_zalloc</code>(<var class="Fa" style="white-space: nowrap;">size_t + size</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kmem_intr_free</code>(<var class="Fa" style="white-space: nowrap;">void + *p</var>, <var class="Fa" style="white-space: nowrap;">size_t + size</var>);</p> +<p class="Pp"><var class="Ft">char *</var> + <br/> + <code class="Fn">kmem_asprintf</code>(<var class="Fa" style="white-space: nowrap;">const + char *fmt</var>, + <var class="Fa" style="white-space: nowrap;">...</var>);</p> +<p class="Pp"><var class="Ft">char *</var> + <br/> + <code class="Fn">kmem_strdupsize</code>(<var class="Fa" style="white-space: nowrap;">const + char *str</var>, <var class="Fa" style="white-space: nowrap;">size_t + *size</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">char *</var> + <br/> + <code class="Fn">kmem_strdup</code>(<var class="Fa" style="white-space: nowrap;">const + char *str</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">char *</var> + <br/> + <code class="Fn">kmem_strndup</code>(<var class="Fa" style="white-space: nowrap;">const + char *str</var>, <var class="Fa" style="white-space: nowrap;">size_t + manxlen</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kmem_strfree</code>(<var class="Fa" style="white-space: nowrap;">char + *str</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">kmem_tmpbuf_alloc</code>(<var class="Fa" style="white-space: nowrap;">size_t + size</var>, <var class="Fa" style="white-space: nowrap;">void + *stackbuf</var>, <var class="Fa" style="white-space: nowrap;">size_t + stackbufsize</var>, <var class="Fa" style="white-space: nowrap;">km_flag_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kmem_tmpbuf_free</code>(<var class="Fa" style="white-space: nowrap;">void + *p</var>, <var class="Fa" style="white-space: nowrap;">size_t size</var>, + <var class="Fa" style="white-space: nowrap;">void *stackbuf</var>);</p> +<p class="Pp"> + <br/> + <code class="Cd">options KMEM_SIZE</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><a class="permalink" href="#kmem_alloc"><code class="Fn" id="kmem_alloc">kmem_alloc</code></a>() + allocates kernel wired memory. It takes the following arguments.</p> +<dl class="Bl-tag"> + <dt><var class="Fa">size</var></dt> + <dd>Specify the size of allocation in bytes.</dd> + <dt><var class="Fa">kmflags</var></dt> + <dd>Either of the following: + <dl class="Bl-tag"> + <dt id="KM_SLEEP"><a class="permalink" href="#KM_SLEEP"><code class="Dv">KM_SLEEP</code></a></dt> + <dd>If the allocation cannot be satisfied immediately, sleep until enough + memory is available. If <code class="Dv">KM_SLEEP</code> is specified, + then the allocation cannot fail.</dd> + <dt id="KM_NOSLEEP"><a class="permalink" href="#KM_NOSLEEP"><code class="Dv">KM_NOSLEEP</code></a></dt> + <dd>Don't sleep. Immediately return <code class="Dv">NULL</code> if there + is not enough memory available. It should only be used when failure to + allocate will not have harmful, user-visible effects. + <p class="Pp"></p> + <div class="Bf Sy">Use of <code class="Dv">KM_NOSLEEP</code> is strongly + discouraged as it can create transient, hard to debug failures that + occur when the system is under memory pressure.</div> + <p class="Pp">In situations where it is not possible to sleep, for + example because locks are held by the caller, the code path should + be restructured to allow the allocation to be made in another + place.</p> + </dd> + </dl> + </dd> +</dl> +<p class="Pp">The contents of allocated memory are uninitialized.</p> +<p class="Pp">Unlike Solaris, kmem_alloc(0, flags) is illegal.</p> +<p class="Pp" id="kmem_zalloc"><a class="permalink" href="#kmem_zalloc"><code class="Fn">kmem_zalloc</code></a>() + is the equivalent of <code class="Fn">kmem_alloc</code>(), except that it + initializes the memory to zero.</p> +<p class="Pp" id="kmem_asprintf"><a class="permalink" href="#kmem_asprintf"><code class="Fn">kmem_asprintf</code></a>() + functions as the well known + <a class="permalink" href="#asprintf"><code class="Fn" id="asprintf">asprintf</code></a>() + function, but allocates memory using <code class="Fn">kmem_alloc</code>(). + This routine can sleep during allocation. The size of the allocated area is + the length of the returned character string, plus one (for the NUL + terminator). This must be taken into consideration when freeing the returned + area with <code class="Fn">kmem_free</code>().</p> +<p class="Pp" id="kmem_free"><a class="permalink" href="#kmem_free"><code class="Fn">kmem_free</code></a>() + frees kernel wired memory allocated by <code class="Fn">kmem_alloc</code>() + or <code class="Fn">kmem_zalloc</code>() so that it can be used for other + purposes. It takes the following arguments.</p> +<dl class="Bl-tag"> + <dt><var class="Fa">p</var></dt> + <dd>The pointer to the memory being freed. It must be the one returned by + <code class="Fn">kmem_alloc</code>() or + <code class="Fn">kmem_zalloc</code>().</dd> + <dt><var class="Fa">size</var></dt> + <dd>The size of the memory being freed, in bytes. It must be the same as the + <var class="Fa">size</var> argument used for + <code class="Fn">kmem_alloc</code>() or + <code class="Fn">kmem_zalloc</code>() when the memory was allocated.</dd> +</dl> +<p class="Pp">Freeing <code class="Dv">NULL</code> is illegal.</p> +<p class="Pp" id="kmem_intr_alloc"><a class="permalink" href="#kmem_intr_alloc"><code class="Fn">kmem_intr_alloc</code></a>(), + <a class="permalink" href="#kmem_intr_zalloc"><code class="Fn" id="kmem_intr_zalloc">kmem_intr_zalloc</code></a>() + and + <a class="permalink" href="#kmem_intr_free"><code class="Fn" id="kmem_intr_free">kmem_intr_free</code></a>() + are the equivalents of the above kmem routines which can be called from the + interrupt context. These routines are for the special cases. Normally, + <a class="Xr">pool_cache(9)</a> should be used for memory allocation from + interrupt context.</p> +<p class="Pp" id="kmem_strdupsize">The + <a class="permalink" href="#kmem_strdupsize"><code class="Fn">kmem_strdupsize</code></a>() + function is a utility function that can be used to copy the string in the + <var class="Fa">str</var> argument to a new buffer allocated using + <code class="Fn">kmem_alloc</code>() and optionally return the size of the + allocation (the length of the string plus the trailing + <code class="Dv">NUL</code>) in the <var class="Fa">size</var> argument if + that is not <code class="Dv">NULL</code>.</p> +<p class="Pp" id="kmem_strdup">The + <a class="permalink" href="#kmem_strdup"><code class="Fn">kmem_strdup</code></a>() + function is a simplified version of + <code class="Fn">kmem_strdupsize</code>() that does not return the size of + the allocation.</p> +<p class="Pp" id="kmem_strndup">The + <a class="permalink" href="#kmem_strndup"><code class="Fn">kmem_strndup</code></a>() + function is variation of <code class="Fn">kmem_strdup</code>() that copies + at most <var class="Fa">maxlen</var> characters from the string + <var class="Fa">str</var> always NUL terminating the copied string.</p> +<p class="Pp" id="kmem_strfree">The + <a class="permalink" href="#kmem_strfree"><code class="Fn">kmem_strfree</code></a>() + function can be used to free a <code class="Dv">NUL</code> terminated string + computing the length of the string using <a class="Xr">strlen(3)</a> and + adding one for the <code class="Dv">NUL</code> and then using + <code class="Fn">kmem_free</code>().</p> +<p class="Pp" id="kmem_tmpbuf_alloc">The + <a class="permalink" href="#kmem_tmpbuf_alloc"><code class="Fn">kmem_tmpbuf_alloc</code></a>() + function is a utility function for allocating memory for temporary use, + where allocation on the stack is desirable, but only up to a certain size. + If the requested size fits within the specified stack buffer, the stack + buffer is returned. Otherwise, memory is allocated with + <code class="Fn">kmem_alloc</code>(). The + <a class="permalink" href="#kmem_tmpbuf_free"><code class="Fn" id="kmem_tmpbuf_free">kmem_tmpbuf_free</code></a>() + function compares the result of a previous call to + <code class="Fn">kmem_tmpbuf_alloc</code>() and frees the memory using + <code class="Fn">kmem_free</code>() if it is not the specified stack + buffer.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp">Making <code class="Dv">KM_SLEEP</code> allocations while holding + mutexes or reader/writer locks is discouraged, as the caller can sleep for + an unbounded amount of time in order to satisfy the allocation. This can in + turn block other threads that wish to acquire locks held by the caller. It + should be noted that <code class="Fn">kmem_free</code>() may also block.</p> +<p class="Pp">For some locks this is permissible or even unavoidable. For + others, particularly locks that may be taken from soft interrupt context, it + is a serious problem. As a general rule it is better not to allow this type + of situation to develop. One way to circumvent the problem is to make + allocations speculative and part of a retryable sequence. For example:</p> +<div class="Bd Pp Li"> +<pre> retry: + /* speculative unlocked check */ + if (need to allocate) { + new_item = kmem_alloc(sizeof(*new_item), KM_SLEEP); + } else { + new_item = NULL; + } + mutex_enter(lock); + /* check while holding lock for true status */ + if (need to allocate) { + if (new_item == NULL) { + mutex_exit(lock); + goto retry; + } + consume(new_item); + new_item = NULL; + } + mutex_exit(lock); + if (new_item != NULL) { + /* did not use it after all */ + kmem_free(new_item, sizeof(*new_item)); + }</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1> +<section class="Ss"> +<h2 class="Ss" id="KMEM_SIZE"><a class="permalink" href="#KMEM_SIZE">KMEM_SIZE</a></h2> +<p class="Pp">Kernels compiled with the <code class="Dv">KMEM_SIZE</code> option + ensure the size given in + <a class="permalink" href="#kmem_free~2"><code class="Fn" id="kmem_free~2">kmem_free</code></a>() + matches the actual allocated size. On <code class="Fn">kmem_alloc</code>(), + the kernel will allocate an additional contiguous kmem page of eight bytes + in the buffer, will register the allocated size in the first kmem page of + that buffer, and will return a pointer to the second kmem page in that same + buffer. When freeing, the kernel reads the first page, and compares the size + registered with the one given in <code class="Fn">kmem_free</code>(). Any + mismatch triggers a panic.</p> +<p class="Pp"><code class="Dv">KMEM_SIZE</code> is enabled by default on + <code class="Dv">DIAGNOSTIC</code>.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">On success, <code class="Fn">kmem_alloc</code>(), + <code class="Fn">kmem_asprintf</code>(), + <code class="Fn">kmem_intr_alloc</code>(), + <code class="Fn">kmem_intr_zalloc</code>(), + <code class="Fn">kmem_strdupsize</code>(), and + <code class="Fn">kmem_zalloc</code>() return a pointer to allocated memory. + Otherwise, <code class="Dv">NULL</code> is returned.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">kmem</code> subsystem is implemented within + the file <span class="Pa">sys/kern/subr_kmem.c</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">intro(9)</a>, <a class="Xr">memoryallocators(9)</a>, + <a class="Xr">percpu(9)</a>, <a class="Xr">pool_cache(9)</a>, + <a class="Xr">uvm_km(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">The <code class="Fn">kmem_alloc</code>(), + <code class="Fn">kmem_asprintf</code>(), + <code class="Fn">kmem_free</code>(), + <code class="Fn">kmem_strdupsize</code>(), + <code class="Fn">kmem_strfree</code>(), and + <code class="Fn">kmem_zalloc</code>() functions cannot be used from + interrupt context, from a soft interrupt, or from a callout. Use + <a class="Xr">pool_cache(9)</a> in these situations.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SECURITY_CONSIDERATIONS"><a class="permalink" href="#SECURITY_CONSIDERATIONS">SECURITY + CONSIDERATIONS</a></h1> +<p class="Pp">As the memory allocated by <code class="Fn">kmem_alloc</code>() is + uninitialized, it can contain security-sensitive data left by its previous + user. It is the caller's responsibility not to expose it to the world.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 24, 2021</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/localcount.9 3.html b/static/netbsd/man9/localcount.9 3.html new file mode 100644 index 00000000..d71eac71 --- /dev/null +++ b/static/netbsd/man9/localcount.9 3.html @@ -0,0 +1,170 @@ +<table class="head"> + <tr> + <td class="head-ltitle">LOCALCOUNT(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">LOCALCOUNT(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">localcount</code>, + <code class="Nm">localcount_init</code>, + <code class="Nm">localcount_fini</code>, + <code class="Nm">localcount_acquire</code>, + <code class="Nm">localcount_release</code>, + <code class="Nm">localcount_drain</code> — + <span class="Nd">reference-count primitives</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/localcount.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">localcount_init</code>(<var class="Fa" style="white-space: nowrap;">struct + localcount *lc</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">localcount_fini</code>(<var class="Fa" style="white-space: nowrap;">struct + localcount *lc</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">localcount_acquire</code>(<var class="Fa" style="white-space: nowrap;">struct + localcount *lc</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">localcount_release</code>(<var class="Fa" style="white-space: nowrap;">struct + localcount *lc</var>, <var class="Fa" style="white-space: nowrap;">struct + kcondvar *cv</var>, <var class="Fa" style="white-space: nowrap;">struct + kmutex *mtx</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">localcount_drain</code>(<var class="Fa" style="white-space: nowrap;">struct + localcount *lc</var>, <var class="Fa" style="white-space: nowrap;">struct + kcondvar *cv</var>, <var class="Fa" style="white-space: nowrap;">struct + kmutex *mtx</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Localcounts are used in the kernel to implement a medium-weight + reference counting mechanism. During normal operations, localcounts do not + need the interprocessor synchronization associated with + <a class="Xr">atomic_ops(3)</a> atomic memory operations, and (unlike + <a class="Xr">psref(9)</a>) <code class="Nm">localcount</code> references + can be held across sleeps and can migrate between CPUs. Draining a + <code class="Nm">localcount</code> requires more expensive interprocessor + synchronization than <a class="Xr">atomic_ops(3)</a> (similar to + <a class="Xr">psref(9)</a>). And <code class="Nm">localcount</code> + references require eight bytes of memory per object per-CPU, significantly + more than <a class="Xr">atomic_ops(3)</a> and almost always more than + <a class="Xr">psref(9)</a>.</p> +<p class="Pp">As a rough heuristic, <code class="Nm">localcount</code> should be + used for classes of objects of which there are perhaps a few dozen instances + (such as <a class="Xr">autoconf(9)</a> devices) but not thousands of + instances (such as network flows) and on which there may be a mixture of + long-term I/O waits, such as xyzread for a device xyz(4), and short-term + fast operations, such as + <code class="Dv">xyzioctl(IOC_READ_A_CPU_REG)</code>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="localcount_init"><a class="permalink" href="#localcount_init"><code class="Fn">localcount_init</code></a>(<var class="Fa">lc</var>)</dt> + <dd>Dynamically initialize localcount <var class="Ar">lc</var> for use. + <p class="Pp">No other operations can be performed on a localcount until it + has been initialized.</p> + </dd> + <dt id="localcount_fini"><a class="permalink" href="#localcount_fini"><code class="Fn">localcount_fini</code></a>(<var class="Fa">lc</var>)</dt> + <dd>Release resources used by localcount <var class="Ar">lc</var>. The caller + must have already called <code class="Fn">localcount_drain</code>(). The + localcount may not be used after <code class="Fn">localcount_fini</code>() + has been called until it has been re-initialized by + <code class="Fn">localcount_init</code>().</dd> + <dt><code class="Fn">localcount_acquire</code>(<var class="Fa">lc</var>)</dt> + <dd>Acquire a reference to the localcount <var class="Ar">lc</var>. + <p class="Pp" id="localcount_acquire">The caller must ensure by some other + mechanism that the localcount will not be destroyed before the call to + <a class="permalink" href="#localcount_acquire"><code class="Fn">localcount_acquire</code></a>(); + typically this will be via a <a class="Xr">pserialize(9)</a> read + section.</p> + </dd> + <dt id="localcount_release"><a class="permalink" href="#localcount_release"><code class="Fn">localcount_release</code></a>(<var class="Fa">lc</var>, + <var class="Fa">cv</var>, <var class="Fa">mtx</var>)</dt> + <dd>Release a reference to the localcount <var class="Ar">lc</var>. If the + localcount is currently being drained, the mutex <var class="Ar">mtx</var> + will be used to synchronize updates to the global reference count (i.e., + the total across all CPUs). If the reference count goes to zero, + <code class="Fn">localcount_release</code>() will broadcast availability + of the condvar <var class="Ar">cv</var>.</dd> + <dt><code class="Fn">localcount_drain</code>(<var class="Fa">lc</var>, + <var class="Fa">cv</var>, <var class="Fa">mtx</var>)</dt> + <dd>Wait for all references to the localcount <var class="Ar">lc</var> to be + released. The caller must hold the mutex <var class="Ar">mtx</var>; the + mutex will be released during inter-CPU cross-calls (see + <a class="Xr">xcall(9)</a>) and while waiting on the condvar + <var class="Ar">cv</var>. The same <var class="Ar">cv</var> and + <var class="Ar">mtx</var> must be used with + <code class="Fn">localcount_release</code>(). + <p class="Pp" id="localcount_acquire~2">The caller must guarantee that no + new references can be acquired with + <a class="permalink" href="#localcount_acquire~2"><code class="Fn">localcount_acquire</code></a>() + before calling <code class="Fn">localcount_drain</code>(). For example, + any object that may be found in a list and acquired must be removed from + the list before calling <code class="Fn">localcount_drain</code>(); + removal from the list would typically be protected by calling + <a class="Xr">pserialize_perform(9)</a> to wait for any + <a class="Xr">pserialize(9)</a> readers to complete.</p> + <p class="Pp" id="localcount_drain">Once the localcount object + <var class="Ar">lc</var> is passed to + <a class="permalink" href="#localcount_drain"><code class="Fn">localcount_drain</code></a>(), + it must be passed to <code class="Fn">localcount_fini</code>() before + any other re-use.</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 core of the localcount implementation is located in + <span class="Pa">sys/kern/subr_localcount.c</span>.</p> +<p class="Pp">The header file <span class="Pa">sys/sys/localcount.h</span> + describes the public interface, and interfaces that machine-dependent code + must provide to support localcounts.</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">atomic_ops(3)</a>, <a class="Xr">condvar(9)</a>, + <a class="Xr">mutex(9)</a>, <a class="Xr">psref(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The localcount primitives first appeared in + <span class="Ux">NetBSD 8.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><code class="Nm">localcount</code> was designed by + <span class="An">Taylor R. Campbell</span>, who also provided a draft + implementation. The implementation was completed, tested, and integrated by + <span class="An">Paul Goyette</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">The <code class="Nm">localcount</code> facility does not provide + any way to examine the reference count without actually waiting for the + count to reach zero.</p> +<p class="Pp">Waiting for a <code class="Nm">localcount</code> reference count + to drain (reach zero) is a one-shot operation. Once the + <code class="Nm">localcount</code> has been drained, no further operations + are allowed until the <code class="Nm">localcount</code> has been + re-initialized.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 25, 2019</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/lock.9 3.html b/static/netbsd/man9/lock.9 3.html new file mode 100644 index 00000000..304547b0 --- /dev/null +++ b/static/netbsd/man9/lock.9 3.html @@ -0,0 +1,49 @@ +<table class="head"> + <tr> + <td class="head-ltitle">LOCK(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">LOCK(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">lock</code>, + <code class="Nm">simple_lock_init</code>, + <code class="Nm">simple_lock</code>, + <code class="Nm">simple_lock_try</code>, + <code class="Nm">simple_unlock</code>, + <code class="Nm">simple_lock_freecheck</code>, + <code class="Nm">simple_lock_dump</code>, <code class="Nm">lockinit</code>, + <code class="Nm">lockmgr</code>, <code class="Nm">lockstatus</code>, + <code class="Nm">lockmgr_printinfo</code>, + <code class="Nm">spinlockinit</code>, <code class="Nm">spinlockmgr</code> + — <span class="Nd">kernel lock functions</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">These interfaces have been obsoleted and removed from the + system.</p> +<p class="Pp">Please see the <a class="Xr">condvar(9)</a>, + <a class="Xr">mutex(9)</a>, and <a class="Xr">rwlock(9)</a> manual pages for + information on kernel synchronisation primitives.</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">condvar(9)</a>, <a class="Xr">mutex(9)</a>, + <a class="Xr">rwlock(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The kernel locking API first appeared in + <span class="Ux">4.4BSD</span>-lite2, and was replaced in + <span class="Ux">NetBSD 5.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 30, 2008</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/locking.9 3.html b/static/netbsd/man9/locking.9 3.html new file mode 100644 index 00000000..9704a7c1 --- /dev/null +++ b/static/netbsd/man9/locking.9 3.html @@ -0,0 +1,333 @@ +<table class="head"> + <tr> + <td class="head-ltitle">LOCKING(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">LOCKING(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">locking</code> — + <span class="Nd">introduction to kernel synchronization and interrupt + control</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <span class="Ux">NetBSD</span> kernel provides several + synchronization and interrupt control primitives. This man page aims to give + an overview of these interfaces and their proper application. Also included + are basic kernel thread control primitives and a rough overview of the + <span class="Ux">NetBSD</span> kernel design.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="KERNEL_OVERVIEW"><a class="permalink" href="#KERNEL_OVERVIEW">KERNEL + OVERVIEW</a></h1> +<p class="Pp">The aim of synchronization, threads and interrupt control in the + kernel is:</p> +<ul class="Bl-bullet Bd-indent"> + <li>To control concurrent access to shared resources (critical sections).</li> + <li>Spawn tasks from an interrupt in the thread context.</li> + <li>Mask interrupts from threads.</li> + <li>Scale on multiple CPU system.</li> +</ul> +<p class="Pp">There are three types of contexts in the + <span class="Ux">NetBSD</span> kernel:</p> +<ul class="Bl-bullet Bd-indent"> + <li id="Thread"><a class="permalink" href="#Thread"><i class="Em">Thread + context</i></a> - running processes (represented by + <code class="Dv">struct proc</code>) and light-weight processes + (represented by <code class="Dv">struct lwp</code>, also known as kernel + threads). Code in this context can sleep, block resources and own + address-space.</li> + <li id="Software"><a class="permalink" href="#Software"><i class="Em">Software + interrupt context</i></a> - limited by thread context. Code in this + context must be processed shortly. These interrupts don't own any address + space context. Software interrupts are a way of deferring hardware + interrupts to do more expensive processing at a lower interrupt + priority.</li> + <li id="Hard"><a class="permalink" href="#Hard"><i class="Em">Hard interrupt + context</i></a> - Code in this context must be processed as quickly as + possible. It is forbidden for a piece of code to sleep or access + long-awaited resources here.</li> +</ul> +<p class="Pp">The main differences between processes and kernel threads are:</p> +<ul class="Bl-bullet Bd-indent"> + <li>A single process can own multiple kernel threads (LWPs).</li> + <li>A process owns address space context to map userland address space.</li> + <li>Processes are designed for userland executables and kernel threads for + in-kernel tasks. The only process running in the kernel-space is + <code class="Dv">proc0</code> (called swapper).</li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="INTERFACES"><a class="permalink" href="#INTERFACES">INTERFACES</a></h1> +<section class="Ss"> +<h2 class="Ss" id="Atomic_memory_operations"><a class="permalink" href="#Atomic_memory_operations">Atomic + memory operations</a></h2> +<p class="Pp">The <code class="Nm">atomic_ops</code> family of functions provide + atomic memory operations. There are 7 classes of atomic memory operations + available: addition, logical “and”, compare-and-swap, + decrement, increment, logical “or”, swap.</p> +<p class="Pp">See <a class="Xr">atomic_ops(3)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Condition_variables"><a class="permalink" href="#Condition_variables">Condition + variables</a></h2> +<p class="Pp">Condition variables (CVs) are used in the kernel to synchronize + access to resources that are limited (for example, memory) and to wait for + pending I/O operations to complete.</p> +<p class="Pp">See <a class="Xr">condvar(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Memory_access_barrier_operations"><a class="permalink" href="#Memory_access_barrier_operations">Memory + access barrier operations</a></h2> +<p class="Pp">The <code class="Nm">membar_ops</code> family of functions provide + memory access barrier operations necessary for synchronization in + multiprocessor execution environments that have relaxed load and store + order.</p> +<p class="Pp">See <a class="Xr">membar_ops(3)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Memory_barriers"><a class="permalink" href="#Memory_barriers">Memory + barriers</a></h2> +<p class="Pp">The memory barriers can be used to control the order in which + memory accesses occur, and thus the order in which those accesses become + visible to other processors. They can be used to implement + “lockless” access to data structures where the necessary + barrier conditions are well understood.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Mutual_exclusion_primitives"><a class="permalink" href="#Mutual_exclusion_primitives">Mutual + exclusion primitives</a></h2> +<p class="Pp">Thread-base adaptive mutexes. These are lightweight, exclusive + locks that use threads as the focus of synchronization activity. Adaptive + mutexes typically behave like spinlocks, but under specific conditions an + attempt to acquire an already held adaptive mutex may cause the acquiring + thread to sleep. Sleep activity occurs rarely. Busy-waiting is typically + more efficient because mutex hold times are most often short. In contrast to + pure spinlocks, a thread holding an adaptive mutex may be pre-empted in the + kernel, which can allow for reduced latency where soft real-time application + are in use on the system.</p> +<p class="Pp">See <a class="Xr">mutex(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Restartable_atomic_sequences"><a class="permalink" href="#Restartable_atomic_sequences">Restartable + atomic sequences</a></h2> +<p class="Pp">Restartable atomic sequences are user code only sequences which + are guaranteed to execute without preemption. This property is assured by + checking the set of restartable atomic sequences registered for a process + during <a class="Xr">cpu_switchto(9)</a>. If a process is found to have been + preempted during a restartable sequence, then its execution is rolled-back + to the start of the sequence by resetting its program counter which is saved + in its process control block (PCB).</p> +<p class="Pp">See <a class="Xr">ras(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Reader_/_writer_lock_primitives"><a class="permalink" href="#Reader_/_writer_lock_primitives">Reader + / writer lock primitives</a></h2> +<p class="Pp">Reader / writer locks (RW locks) are used in the kernel to + synchronize access to an object among LWPs (lightweight processes) and soft + interrupt handlers. In addition to the capabilities provided by mutexes, RW + locks distinguish between read (shared) and write (exclusive) access.</p> +<p class="Pp">See <a class="Xr">rwlock(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Functions_to_modify_system_interrupt_priority_level"><a class="permalink" href="#Functions_to_modify_system_interrupt_priority_level">Functions + to modify system interrupt priority level</a></h2> +<p class="Pp">These functions raise and lower the interrupt priority level. They + are used by kernel code to block interrupts in critical sections, in order + to protect data structures.</p> +<p class="Pp">See <a class="Xr">spl(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Machine-independent_software_interrupt_framework"><a class="permalink" href="#Machine-independent_software_interrupt_framework">Machine-independent + software interrupt framework</a></h2> +<p class="Pp">The software interrupt framework is designed to provide a generic + software interrupt mechanism which can be used any time a low-priority + callback is required. It allows dynamic registration of software interrupts + for loadable drivers, protocol stacks, software interrupt prioritization, + software interrupt fair queuing and allows machine-dependent optimizations + to reduce cost.</p> +<p class="Pp">See <a class="Xr">softint(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Functions_to_raise_the_system_priority_level"><a class="permalink" href="#Functions_to_raise_the_system_priority_level">Functions + to raise the system priority level</a></h2> +<p class="Pp">The <code class="Nm">splraiseipl</code> function raises the system + priority level to the level specified by <code class="Dv">icookie</code>, + which should be a value returned by <a class="Xr">makeiplcookie(9)</a>. In + general, device drivers should not make use of this interface. To ensure + correct synchronization, device drivers should use the + <a class="Xr">condvar(9)</a>, <a class="Xr">mutex(9)</a>, and + <a class="Xr">rwlock(9)</a> interfaces.</p> +<p class="Pp">See <a class="Xr">splraiseipl(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Passive_serialization_mechanism"><a class="permalink" href="#Passive_serialization_mechanism">Passive + serialization mechanism</a></h2> +<p class="Pp">Passive serialization is a reader / writer synchronization + mechanism designed for lock-less read operations. The read operations may + happen from software interrupt at <code class="Dv">IPL_SOFTCLOCK</code>.</p> +<p class="Pp">See <a class="Xr">pserialize(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Passive_reference_mechanism"><a class="permalink" href="#Passive_reference_mechanism">Passive + reference mechanism</a></h2> +<p class="Pp">Passive references allow CPUs to cheaply acquire and release + passive references to a resource, which guarantee the resource will not be + destroyed until the reference is released. Acquiring and releasing passive + references requires no interprocessor synchronization, except when the + resource is pending destruction.</p> +<p class="Pp">See <a class="Xr">psref(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Localcount_mechanism"><a class="permalink" href="#Localcount_mechanism">Localcount + mechanism</a></h2> +<p class="Pp">Localcounts are used in the kernel to implement a medium-weight + reference counting mechanism. During normal operations, localcounts do not + need the interprocessor synchronization associated with + <a class="Xr">atomic_ops(3)</a> atomic memory operations, and (unlike + <a class="Xr">psref(9)</a>) localcount references can be held across sleeps + and can migrate between CPUs. Draining a localcount requires more expensive + interprocessor synchronization than <a class="Xr">atomic_ops(3)</a> (similar + to <a class="Xr">psref(9)</a>). And localcount references require eight + bytes of memory per object per-CPU, significantly more than + <a class="Xr">atomic_ops(3)</a> and almost always more than + <a class="Xr">psref(9)</a>.</p> +<p class="Pp">See <a class="Xr">localcount(9)</a>.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Simple_do-it-in-thread-context_framework"><a class="permalink" href="#Simple_do-it-in-thread-context_framework">Simple + do-it-in-thread-context framework</a></h2> +<p class="Pp">The workqueue utility routines are provided to defer work which is + needed to be processed in a thread context.</p> +<p class="Pp">See <a class="Xr">workqueue(9)</a>.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="USAGE"><a class="permalink" href="#USAGE">USAGE</a></h1> +<p class="Pp">The following table describes in which contexts the use of the + <span class="Ux">NetBSD</span> kernel interfaces are valid. Synchronization + primitives which are available in more than one context can be used to + protect shared resources between the contexts they overlap.</p> +<table class="Bl-column Bd-indent"> + <tr id="interface"> + <td><a class="permalink" href="#interface"><b class="Sy">interface</b></a></td> + <td><a class="permalink" href="#thread"><b class="Sy" id="thread">thread</b></a></td> + <td><a class="permalink" href="#softirq"><b class="Sy" id="softirq">softirq</b></a></td> + <td><a class="permalink" href="#hardirq"><b class="Sy" id="hardirq">hardirq</b></a></td> + </tr> + <tr> + <td><a class="Xr">atomic_ops(3)</a></td> + <td>yes</td> + <td>yes</td> + <td>yes</td> + </tr> + <tr> + <td><a class="Xr">condvar(9)</a></td> + <td>yes</td> + <td>partly</td> + <td>no</td> + </tr> + <tr> + <td><a class="Xr">membar_ops(3)</a></td> + <td>yes</td> + <td>yes</td> + <td>yes</td> + </tr> + <tr> + <td><a class="Xr">mutex(9)</a></td> + <td>yes</td> + <td>depends</td> + <td>depends</td> + </tr> + <tr> + <td><a class="Xr">rwlock(9)</a></td> + <td>yes</td> + <td>yes</td> + <td>no</td> + </tr> + <tr> + <td><a class="Xr">softint(9)</a></td> + <td>yes</td> + <td>yes</td> + <td>yes</td> + </tr> + <tr> + <td><a class="Xr">spl(9)</a></td> + <td>yes</td> + <td>no</td> + <td>no</td> + </tr> + <tr> + <td><a class="Xr">splraiseipl(9)</a></td> + <td>yes</td> + <td>no</td> + <td>no</td> + </tr> + <tr> + <td><a class="Xr">pserialize(9)</a></td> + <td>yes</td> + <td>yes</td> + <td>no</td> + </tr> + <tr> + <td><a class="Xr">psref(9)</a></td> + <td>yes</td> + <td>yes</td> + <td>no</td> + </tr> + <tr> + <td><a class="Xr">localcount(9)</a></td> + <td>yes</td> + <td>yes</td> + <td>no</td> + </tr> + <tr> + <td><a class="Xr">workqueue(9)</a></td> + <td>yes</td> + <td>yes</td> + <td>yes</td> + </tr> +</table> +</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">atomic_ops(3)</a>, <a class="Xr">membar_ops(3)</a>, + <a class="Xr">condvar(9)</a>, <a class="Xr">mutex(9)</a>, + <a class="Xr">ras(9)</a>, <a class="Xr">rwlock(9)</a>, + <a class="Xr">softint(9)</a>, <a class="Xr">spl(9)</a>, + <a class="Xr">splraiseipl(9)</a>, <a class="Xr">workqueue(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">Initial SMP support was introduced in <span class="Ux">NetBSD + 2.0</span> and was designed with a giant kernel lock. Through + <span class="Ux">NetBSD 4.0</span>, the kernel used spinlocks and a per-CPU + interrupt priority level (the <a class="Xr">spl(9)</a> system). These + mechanisms did not lend themselves well to a multiprocessor environment + supporting kernel preemption. The use of thread based (lock) synchronization + was limited and the available synchronization primitive (lockmgr) was + inefficient and slow to execute. <span class="Ux">NetBSD 5.0</span> + introduced massive performance improvements on multicore hardware by Andrew + Doran. This work was sponsored by The <span class="Ux">NetBSD</span> + Foundation.</p> +<p class="Pp">A <code class="Nm">locking</code> manual first appeared in + <span class="Ux">NetBSD 8.0</span> and was inspired by the corresponding + <code class="Nm">locking</code> manuals in <span class="Ux">FreeBSD</span> + and <span class="Ux">DragonFly</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Kamil Rytarowski</span> + <<a class="Mt" href="mailto:kamil@NetBSD.org">kamil@NetBSD.org</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 23, 2017</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/ltsleep.9 3.html b/static/netbsd/man9/ltsleep.9 3.html new file mode 100644 index 00000000..852103ea --- /dev/null +++ b/static/netbsd/man9/ltsleep.9 3.html @@ -0,0 +1,203 @@ +<table class="head"> + <tr> + <td class="head-ltitle">LTSLEEP(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">LTSLEEP(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">ltsleep</code>, <code class="Nm">mtsleep</code>, + <code class="Nm">tsleep</code>, <code class="Nm">wakeup</code> — + <span class="Nd">process context sleep and wakeup</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/proc.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">mtsleep</code>(<var class="Fa" style="white-space: nowrap;">wchan_t + ident</var>, <var class="Fa" style="white-space: nowrap;">pri_t + priority</var>, <var class="Fa" style="white-space: nowrap;">const char + *wmesg</var>, <var class="Fa" style="white-space: nowrap;">int timo</var>, + <var class="Fa" style="white-space: nowrap;">kmutex_t *mtx</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">tsleep</code>(<var class="Fa" style="white-space: nowrap;">wchan_t + ident</var>, <var class="Fa" style="white-space: nowrap;">pri_t + priority</var>, <var class="Fa" style="white-space: nowrap;">const char + *wmesg</var>, <var class="Fa" style="white-space: nowrap;">int + timo</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wakeup</code>(<var class="Fa" style="white-space: nowrap;">wchan_t + ident</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><i class="Em">The interfaces described in this manual page are + obsolete</i> <i class="Em">and will be removed from a future version of the + system.</i></p> +<p class="Pp" id="ltsleep"><i class="Em">The</i> + <a class="permalink" href="#ltsleep"><code class="Fn">ltsleep</code></a>() + <a class="permalink" href="#interface"><i class="Em" id="interface">interface + has been obsoleted and removed from the system.</i></a></p> +<p class="Pp" id="Please"><a class="permalink" href="#Please"><i class="Em">Please + see the</i></a> <a class="Xr">condvar(9)</a>, <a class="Xr">mutex(9)</a>, + <i class="Em">and</i> <a class="Xr">rwlock(9)</a> + <a class="permalink" href="#manual"><i class="Em" id="manual">manual pages + for information on kernel synchronisation primitives.</i></a></p> +<p class="Pp" id="tsleep">These functions implement voluntary context switching. + <a class="permalink" href="#tsleep"><code class="Fn">tsleep</code></a>() and + <code class="Fn">mtsleep</code>() are used throughout the kernel whenever + processing in the current context can not continue for any of the following + reasons:</p> +<ul class="Bl-bullet Bd-indent"> + <li>The current process needs to await the results of a pending I/O + operation.</li> + <li>The current process needs resources (e.g., memory) which are temporarily + unavailable.</li> +</ul> +<p class="Pp" id="wakeup">The function + <a class="permalink" href="#wakeup"><code class="Fn">wakeup</code></a>() is + used to notify sleeping processes of possible changes to the condition that + caused them to go to sleep. Typically, an awakened process will — + after it has acquired a context again — retry the action that blocked + its operation to see if the “blocking” condition has + cleared.</p> +<p class="Pp" id="tsleep~2">The + <a class="permalink" href="#tsleep~2"><code class="Fn">tsleep</code></a>() + and <code class="Fn">mtsleep</code>() functions take the following + arguments:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">ident</var></dt> + <dd>An identifier of the “wait channel” representing the + resource for which the current process needs to wait. This typically is + the virtual address of some kernel data-structure related to the resource + for which the process is contending. The same identifier must be used in a + call to <code class="Fn">wakeup</code>() to get the process going again. + <var class="Fa">ident</var> should not be + <code class="Dv">NULL</code>.</dd> + <dt><var class="Fa">priority</var></dt> + <dd>The process priority to be used when the process is awakened and put on + the queue of runnable processes. This mechanism is used to optimize + “throughput” of processes executing in kernel mode. If the + flag <code class="Dv">PCATCH</code> is OR'ed into + <var class="Fa">priority</var> the process checks for posted signals + before and after sleeping.</dd> + <dt><var class="Fa">wmesg</var></dt> + <dd>A pointer to a character string indicating the reason a process is + sleeping. The kernel does not use the string, but makes it available + (through the process structure field <code class="Li">p_wmesg</code>) for + user level utilities such as <a class="Xr">ps(1)</a>.</dd> + <dt><var class="Fa">timo</var></dt> + <dd>If non-zero, the process will sleep for at most + <code class="Li">timo/hz</code> seconds. If this amount of time elapses + and no <code class="Fn">wakeup</code>(<var class="Fa">ident</var>) has + occurred, and no signal (if <code class="Dv">PCATCH</code> + <span class="No">was set</span>) was posted, + <code class="Fn">tsleep</code>() will return + <code class="Er">EWOULDBLOCK</code>.</dd> +</dl> +<p class="Pp" id="mtsleep">The + <a class="permalink" href="#mtsleep"><code class="Fn">mtsleep</code></a>() + function takes an additional argument and flag:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">mtx</var></dt> + <dd>A <a class="Xr">mutex(9)</a> representing the lock protecting the + data-structures. On entry <code class="Fn">mtsleep</code>() will release + the lock and re-acquire the lock on return.</dd> + <dt><var class="Fa">priority</var></dt> + <dd>If the flag <code class="Dv">PNORELOCK</code> is OR'ed into + <var class="Fa">priority</var> then <code class="Fn">mtsleep</code>() will + not re-acquire the lock.</dd> +</dl> +<p class="Pp" id="wakeup~2">The + <a class="permalink" href="#wakeup~2"><code class="Fn">wakeup</code></a>() + function will mark all processes which are currently sleeping on the + identifier <var class="Fa">ident</var> as runnable. Eventually, each of the + processes will resume execution in the kernel context, causing a return from + <code class="Fn">tsleep</code>() or <code class="Fn">mtsleep</code>(). Note + that processes returning from sleep should always re-evaluate the conditions + that blocked them, since a call to <code class="Fn">wakeup</code>() merely + signals a + <a class="permalink" href="#possible"><i class="Em" id="possible">possible</i></a> + change to the blocking conditions.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp"><code class="Fn">tsleep</code>() and + <code class="Fn">mtsleep</code>() return 0 if they return as a result of a + <code class="Fn">wakeup</code>(). If a <code class="Fn">tsleep</code>() and + <code class="Fn">mtsleep</code>() return as a result of a signal, the return + value is <code class="Er">ERESTART</code> if the signal has the + <code class="Dv">SA_RESTART</code> property (see + <a class="Xr">sigaction(2)</a>), and <code class="Er">EINTR</code> + otherwise. If <code class="Fn">tsleep</code>() and + <code class="Fn">mtsleep</code>() return because of a timeout, the return + value is <code class="Er">EWOULDBLOCK</code>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MIGRATING_TO_CONDVAR"><a class="permalink" href="#MIGRATING_TO_CONDVAR">MIGRATING + TO CONDVAR</a></h1> +<p class="Pp">Note the conversion from tsleep/wakeup into + <a class="Xr">condvar(9)</a> should not be done mechanically i.e. + “blindly”. Code logic should be understood before changing, + and it may also need to be revisited for the change. Please also read the + <a class="Xr">condvar(9)</a> man page.</p> +<p class="Pp" id="tsleep~3">The + <a class="permalink" href="#tsleep~3"><code class="Fn">tsleep</code></a>() + and <code class="Fn">mtsleep</code>(), and <code class="Fn">wakeup</code>() + pairs should generally be replaced by <a class="Xr">cv_wait(9)</a> / + <a class="Xr">cv_wait_sig(9)</a> / <a class="Xr">cv_timedwait(9)</a> / + <a class="Xr">cv_timedwait_sig(9)</a> and <a class="Xr">cv_signal(9)</a> / + <a class="Xr">cv_broadcast(9)</a> pairs. The + <a class="permalink" href="#cv_wait*"><code class="Fn" id="cv_wait*">cv_wait*</code></a>() + variant to use can be determined from looking at the corresponding + <code class="Fn">tsleep</code>() usage.</p> +<p class="Pp">There are two arguments of interest: <var class="Ar">timo</var> + and <var class="Ar">priority</var>. The <var class="Ar">priority</var> value + may have OR'ed the flag <code class="Dv">PCATCH</code>.</p> +<p class="Pp">The <code class="Dv">PCATCH</code> flag means that the blocking + thread should be awoken on signal, and the sleep call should be replaced + with <a class="Xr">cv_wait_sig(9)</a>.</p> +<p class="Pp">The <var class="Ar">timo</var> value, if it is not zero, indicates + how long to sleep, and the sleep call should be replaced with + <a class="Xr">cv_timedwait(9)</a>.</p> +<p class="Pp">If both the <code class="Dv">PCATCH</code> flag and a non-zero + <var class="Ar">timo</var> value are specified, then + <a class="Xr">cv_timedwait_sig(9)</a> should be used.</p> +<p class="Pp" id="cv_wait">A <a class="Xr">mutex(9)</a> (interlock) must be held + across + <a class="permalink" href="#cv_wait"><code class="Fn">cv_wait</code></a>() + and + <a class="permalink" href="#cv_broadcast"><code class="Fn" id="cv_broadcast">cv_broadcast</code></a>() + calls, in order to protect state. Most old code will require the addition of + locking, whereas some will require amending to remove + <code class="Dv">PNORELOCK</code>.</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">sigaction(2)</a>, <a class="Xr">condvar(9)</a>, + <a class="Xr">hz(9)</a>, <a class="Xr">kpause(9)</a>, + <a class="Xr">mutex(9)</a>, <a class="Xr">rwlock(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The sleep/wakeup process synchronization mechanism is very old. It + appeared in a very early version of Unix. <code class="Fn">tsleep</code>() + appeared in <span class="Ux">4.4BSD</span>. + <code class="Fn">ltsleep</code>() appeared in <span class="Ux">NetBSD + 1.5</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 7, 2024</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/man9.x86/rdmsr.9 3.html b/static/netbsd/man9/man9.x86/rdmsr.9 3.html new file mode 100644 index 00000000..e964d37b --- /dev/null +++ b/static/netbsd/man9/man9.x86/rdmsr.9 3.html @@ -0,0 +1,87 @@ +<table class="head"> + <tr> + <td class="head-ltitle">RDMSR(9)</td> + <td class="head-vol">Kernel Developer's Manual (x86)</td> + <td class="head-rtitle">RDMSR(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">msr</code>, <code class="Nm">rdmsr</code>, + <code class="Nm">rdmsr_safe</code>, <code class="Nm">wrmsr</code> — + <span class="Nd">functions for x86 MSRs</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">x86/cpufunc.h</a>></code></p> +<p class="Pp"><var class="Ft">uint64_t</var> + <br/> + <code class="Fn">rdmsr</code>(<var class="Fa" style="white-space: nowrap;">u_int + msr</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">rdmsr_safe</code>(<var class="Fa" style="white-space: nowrap;">u_int + msr</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + *valp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wrmsr</code>(<var class="Fa" style="white-space: nowrap;">u_int + msr</var>, <var class="Fa" style="white-space: nowrap;">uint64_t + val</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Dv">RDMSR</code> instruction reads from a x86 + model-specific register (<code class="Dv">MSR</code>). Conversely, the + <code class="Dv">WRMSR</code> instruction is used to write to a + <code class="Dv">MSR</code>. In <span class="Ux">NetBSD</span> the + <a class="permalink" href="#rdmsr"><code class="Fn" id="rdmsr">rdmsr</code></a>(), + <code class="Fn">rdmsr_safe</code>(), and + <a class="permalink" href="#wrmsr"><code class="Fn" id="wrmsr">wrmsr</code></a>() + functions are used to access <code class="Dv">MSRs</code>. The header + <code class="In"><<a class="In">x86/specialreg.h</a>></code> includes + definitions for some of the commonly used MSRs, that is, control registers + that are present in some x86 processor models but unavailable in others.</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">rdmsr</code>(<var class="Fa">msr</var>)</dt> + <dd>Returns the value read from <var class="Fa">msr</var>.</dd> + <dt><code class="Fn">rdmsr_safe</code>(<var class="Fa">msr</var>, + <var class="Fa">valp</var>)</dt> + <dd>The <code class="Fn">rdmsr_safe</code>() function is a safer variant of + <code class="Fn">rdmsr</code>(). Upon successful completion, the function + returns zero and the value read from the register + <var class="Fa">msr</var> is returned in <var class="Fa">valp</var>. If a + fault occurs while accessing <var class="Fa">msr</var>, + <code class="Fn">rdmsr_safe</code>() returns + <code class="Dv">EFAULT</code>.</dd> + <dt><code class="Fn">wrmsr</code>(<var class="Fa">msr</var>, + <var class="Fa">val</var>)</dt> + <dd>The <code class="Fn">wrmsr</code>() function writes + <var class="Fa">val</var> to the register <var class="Fa">msr</var>.</dd> +</dl> +<p class="Pp" id="rdmsr_safe">Note that even though + <a class="permalink" href="#rdmsr_safe"><code class="Fn">rdmsr_safe</code></a>() + provides support for reading <code class="Dv">MSRs</code> in a safe manner, + it is still a good practice to always verify that the given model-specific + register is present by using the <code class="Dv">CPUID</code> instruction, + available in <span class="Ux">NetBSD</span> via + <a class="permalink" href="#x86_cpuid"><code class="Fn" id="x86_cpuid">x86_cpuid</code></a>().</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">rdtsc(9)</a>, + <a class="Xr">x86/x86_msr_xcall(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 17, 2017</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/man9.x86/tsc.9 3.html b/static/netbsd/man9/man9.x86/tsc.9 3.html new file mode 100644 index 00000000..cf839df4 --- /dev/null +++ b/static/netbsd/man9/man9.x86/tsc.9 3.html @@ -0,0 +1,102 @@ +<table class="head"> + <tr> + <td class="head-ltitle">TSC(9)</td> + <td class="head-vol">Kernel Developer's Manual (x86)</td> + <td class="head-rtitle">TSC(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">tsc</code> — <span class="Nd">Time Stamp + Counter</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">x86/x86/tsc.h</a>></code></p> +<p class="Pp"><var class="Ft">uint64_t</var> + <br/> + <code class="Fn">rdtsc</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tsc_tc_init</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tsc_sync_ap</code>(<var class="Fa" style="white-space: nowrap;">struct + cpu_info *ci</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tsc_sync_bp</code>(<var class="Fa" style="white-space: nowrap;">struct + cpu_info *ci</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tsc_sync_drift</code>(<var class="Fa" style="white-space: nowrap;">int64_t + drift</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The time stamp counter (TSC) is a hardware counter found in all + contemporary x86 processors. The counter is implemented as a 64-bit + model-specific register (MSR) that is incremented at every clock cycle. The + RDTSC (“read time stamp counter”) register has been present + since the original Pentium.</p> +<p class="Pp">Already because of the access method, TSC provides a low-overhead + and high-resolution way to obtain CPU timing information. This traditional + premise was violated when such factors as system sleep states, CPU + “hotplugging”, “hibernation”, and CPU frequency + scaling were introduced to the x86 lineage. This was however mainly a short + abruption: in many new x86 CPUs the time stamp counter is again invariant + with respect to the stability of the clock frequency. Care should be however + taken in implementations that rely on this assumption.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="rdtsc"><a class="permalink" href="#rdtsc"><code class="Fn">rdtsc</code></a>(<var class="Fa"></var>)</dt> + <dd>The <code class="Fn">rdtsc</code>() function returns the value read from + <code class="Dv">RDTSC</code>.</dd> + <dt id="tsc_tc_init"><a class="permalink" href="#tsc_tc_init"><code class="Fn">tsc_tc_init</code></a>(<var class="Fa"></var>)</dt> + <dd>The <code class="Fn">tsc_tc_init</code>() function initializes the TSC as + a <a class="Xr">timecounter(9)</a>. The function is called early in the + boot process when the processors attach.</dd> + <dt><code class="Fn">tsc_sync_bp</code>(<var class="Fa">ci</var>)</dt> + <dd>The <code class="Fn">tsc_sync_bp</code>() function synchronizes the + counter for the boot processor (BP). The supplied <var class="Fa">ci</var> + must refer to the BP itself. The <code class="Nm">tsc</code> interface + takes internally care of such issues as out-of-order execution, where + instructions are not necessarily performed in the order of execution, + possibly causing a misleading cycle count.</dd> + <dt><code class="Fn">tsc_sync_ap</code>(<var class="Fa">ci</var>)</dt> + <dd>The <code class="Fn">tsc_sync_ap</code>() function synchronize the counter + for the application processor <var class="Fa">ci</var>. Interrupts must be + off at machine-level when the function is called. + <p class="Pp" id="tsc_sync_ap">It is necessary to call both + <a class="permalink" href="#tsc_sync_ap"><code class="Fn">tsc_sync_ap</code></a>() + and + <a class="permalink" href="#tsc_sync_bp"><code class="Fn" id="tsc_sync_bp">tsc_sync_bp</code></a>() + during the boot, but additional synchronization may be required also + during runtime. As an example, the TSC needs to be synchronized for all + processors when the system resumes from an <a class="Xr">acpi(4)</a> + sleep state.</p> + </dd> + <dt id="tsc_sync_drift"><a class="permalink" href="#tsc_sync_drift"><code class="Fn">tsc_sync_drift</code></a>(<var class="Fa">drift</var>)</dt> + <dd>Finally, the <code class="Fn">tsc_sync_drift</code>() function records + <var class="Fa">drift</var>, measured in clock cycles. This is called when + the APs attach.</dd> +</dl> +</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">gettimeofday(2)</a>, <a class="Xr">hpet(4)</a>, + <a class="Xr">hz(9)</a>, <a class="Xr">timecounter(9)</a>, + <a class="Xr">x86/rdmsr(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 17, 2017</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/memcmp.9 3.html b/static/netbsd/man9/memcmp.9 3.html new file mode 100644 index 00000000..0d809b4b --- /dev/null +++ b/static/netbsd/man9/memcmp.9 3.html @@ -0,0 +1,55 @@ +<table class="head"> + <tr> + <td class="head-ltitle">MEMCMP(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">MEMCMP(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">memcmp</code> — <span class="Nd">compare + byte string</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">memcmp</code>(<var class="Fa" style="white-space: nowrap;">const + void *b1</var>, <var class="Fa" style="white-space: nowrap;">const void + *b2</var>, <var class="Fa" style="white-space: nowrap;">size_t + len</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#memcmp"><code class="Fn" id="memcmp">memcmp</code></a>() + function compares byte string <var class="Fa">b1</var> against byte string + <var class="Fa">b2</var>. Both strings are assumed to be + <var class="Fa">len</var> bytes long.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The <code class="Fn">memcmp</code>() function returns zero if the + two strings are identical, otherwise returns the difference between the + first two differing bytes (treated as unsigned char values, so that + ‘<code class="Li">\200</code>’ is greater than + ‘<code class="Li">\0</code>’, for example). Zero-length + strings are always identical.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1> +<p class="Pp">The <code class="Fn">memcmp</code>() function conforms to + <span class="St">ANSI X3.159-1989 + (“ANSI C89”)</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 7, 2001</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/memset.9 3.html b/static/netbsd/man9/memset.9 3.html new file mode 100644 index 00000000..43b06ae0 --- /dev/null +++ b/static/netbsd/man9/memset.9 3.html @@ -0,0 +1,50 @@ +<table class="head"> + <tr> + <td class="head-ltitle">MEMSET(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">MEMSET(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">memset</code> — <span class="Nd">write a + byte to byte string</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">memset</code>(<var class="Fa" style="white-space: nowrap;">void + *b</var>, <var class="Fa" style="white-space: nowrap;">int c</var>, + <var class="Fa" style="white-space: nowrap;">size_t len</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#memset"><code class="Fn" id="memset">memset</code></a>() + function writes <var class="Fa">len</var> bytes of value + <var class="Fa">c</var> (converted to an unsigned char) to the string + <var class="Fa">b</var>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The <code class="Fn">memset</code>() function returns the original + value of <var class="Fa">b</var>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1> +<p class="Pp">The <code class="Fn">memset</code>() function conforms to + <span class="St">ANSI X3.159-1989 + (“ANSI C89”)</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 7, 2001</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/microseq.9 3.html b/static/netbsd/man9/microseq.9 3.html new file mode 100644 index 00000000..88fba6fd --- /dev/null +++ b/static/netbsd/man9/microseq.9 3.html @@ -0,0 +1,531 @@ +<table class="head"> + <tr> + <td class="head-ltitle">MICROSEQ(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">MICROSEQ(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">microseq</code> — <span class="Nd">ppbus + microseqencer developer's guide</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/types.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">dev/ppbus/ppbus_conf.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">dev/ppbus/ppbus_msq.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">See <a class="Xr">ppbus(4)</a> for <code class="Nm">ppbus</code> + description and general info about the microsequencer.</p> +<p class="Pp">The purpose of this document is to encourage developers to use the + microsequencer mechanism in order to have:</p> +<ol class="Bl-enum Bd-indent"> + <li>a uniform programming model</li> + <li>efficient code</li> +</ol> +<p class="Pp">Before using microsequences, you are encouraged to look at the + <a class="Xr">atppc(4)</a> microsequencer implementation and an example of + how using it in <a class="Xr">vpo(4)</a>.</p> +<section class="Ss"> +<h2 class="Ss" id="PPBUS_register_model"><a class="permalink" href="#PPBUS_register_model">PPBUS + register model</a></h2> +</section> +<section class="Ss"> +<h2 class="Ss" id="Background"><a class="permalink" href="#Background">Background</a></h2> +<p class="Pp">The parallel port model chosen for <a class="Xr">ppbus(4)</a> is + the PC parallel port model. Thus, any register described later has the same + semantic than its counterpart in a PC parallel port. For more info about + ISA/ECP programming, get the Microsoft standard referenced “Extended + Capabilities Port Protocol and ISA interface Standard”. Registers + described later are standard parallel port registers.</p> +<p class="Pp">Mask macros are defined in the standard <a class="Xr">ppbus(4)</a> + include files for each valid bit of parallel port registers.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Data_register"><a class="permalink" href="#Data_register">Data + register</a></h2> +<p class="Pp">In compatible or nibble mode, writing to this register will drive + data to the parallel port data lines. In any other mode, drivers may be + tri-stated by setting the direction bit (PCD) in the control register. Reads + to this register return the value on the data lines.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Device_status_register"><a class="permalink" href="#Device_status_register">Device + status register</a></h2> +<p class="Pp">This read-only register reflects the inputs on the parallel port + interface.</p> +<p class="Pp"></p> +<table class="Bl-column Bl-compact"> + <tr id="Bit"> + <td><a class="permalink" href="#Bit"><i class="Em">Bit</i></a></td> + <td><a class="permalink" href="#Name"><i class="Em" id="Name">Name</i></a></td> + <td><a class="permalink" href="#Description"><i class="Em" id="Description">Description</i></a></td> + </tr> + <tr> + <td>7</td> + <td>nBUSY</td> + <td>inverted version of parallel port Busy signal</td> + </tr> + <tr> + <td>6</td> + <td>nACK</td> + <td>version of parallel port nAck signal</td> + </tr> + <tr> + <td>5</td> + <td>PERROR</td> + <td>version of parallel port PERROR signal</td> + </tr> + <tr> + <td>4</td> + <td>SELECT</td> + <td>version of parallel port Select signal</td> + </tr> + <tr> + <td>3</td> + <td>nFAULT</td> + <td>version of parallel port nFault signal</td> + </tr> +</table> +<p class="Pp">Others are reserved and return undefined result when read.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="Device_control_register"><a class="permalink" href="#Device_control_register">Device + control register</a></h2> +<p class="Pp">This register directly controls several output signals as well as + enabling some functions.</p> +<p class="Pp"></p> +<table class="Bl-column Bl-compact"> + <tr id="Bit~2"> + <td><a class="permalink" href="#Bit~2"><i class="Em">Bit</i></a></td> + <td><a class="permalink" href="#Name~2"><i class="Em" id="Name~2">Name</i></a></td> + <td><a class="permalink" href="#Description~2"><i class="Em" id="Description~2">Description</i></a></td> + </tr> + <tr> + <td>5</td> + <td>PCD</td> + <td>direction bit in extended modes</td> + </tr> + <tr> + <td>4</td> + <td>IRQENABLE</td> + <td>1 enables an interrupt on the rising edge of nAck</td> + </tr> + <tr> + <td>3</td> + <td>SELECTIN</td> + <td>inverted and driven as parallel port nSelectin signal</td> + </tr> + <tr> + <td>2</td> + <td>nINIT</td> + <td>driven as parallel port nInit signal</td> + </tr> + <tr> + <td>1</td> + <td>AUTOFEED</td> + <td>inverted and driven as parallel port nAutoFd signal</td> + </tr> + <tr> + <td>0</td> + <td>STROBE</td> + <td>inverted and driven as parallel port nStrobe signal</td> + </tr> +</table> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="MICROINSTRUCTIONS"><a class="permalink" href="#MICROINSTRUCTIONS">MICROINSTRUCTIONS</a></h1> +<section class="Ss"> +<h2 class="Ss" id="Description~3"><a class="permalink" href="#Description~3">Description</a></h2> +<p class="Pp"><a class="permalink" href="#Microinstructions"><i class="Em" id="Microinstructions">Microinstructions</i></a> + are either parallel port accesses, program iterations, submicrosequence or C + calls. The parallel port must be considered as the logical model described + in <a class="Xr">ppbus(4)</a>.</p> +<p class="Pp">Available microinstructions are:</p> +<div class="Bd Pp Li"> +<pre>#define MS_OP_GET 0 /* get <ptr>, <len> */ +#define MS_OP_PUT 1 /* put <ptr>, <len> */ +#define MS_OP_RFETCH 2 /* rfetch <reg>, <mask>, <ptr> */ +#define MS_OP_RSET 3 /* rset <reg>, <mask>, <mask> */ +#define MS_OP_RASSERT 4 /* rassert <reg>, <mask> */ +#define MS_OP_DELAY 5 /* delay <val> */ +#define MS_OP_SET 6 /* set <val> */ +#define MS_OP_DBRA 7 /* dbra <offset> */ +#define MS_OP_BRSET 8 /* brset <mask>, <offset> */ +#define MS_OP_BRCLEAR 9 /* brclear <mask>, <offset> */ +#define MS_OP_RET 10 /* ret <retcode> */ +#define MS_OP_C_CALL 11 /* c_call <function>, <parameter> */ +#define MS_OP_PTR 12 /* ptr <pointer> */ +#define MS_OP_ADELAY 13 /* adelay <val> */ +#define MS_OP_BRSTAT 14 /* brstat <mask>, <mask>, <offset> */ +#define MS_OP_SUBRET 15 /* subret <code> */ +#define MS_OP_CALL 16 /* call <microsequence> */ +#define MS_OP_RASSERT_P 17 /* rassert_p <iter>, <reg> */ +#define MS_OP_RFETCH_P 18 /* rfetch_p <iter>, <reg>, <mask> */ +#define MS_OP_TRIG 19 /* trigger <reg>, <len>, <array> */</pre> +</div> +</section> +<section class="Ss"> +<h2 class="Ss" id="Execution_context"><a class="permalink" href="#Execution_context">Execution + context</a></h2> +<p class="Pp">The + <a class="permalink" href="#execution"><i class="Em" id="execution">execution + context</i></a> of microinstructions is:</p> +<ul class="Bl-bullet Bd-indent"> + <li id="program">the + <a class="permalink" href="#program"><i class="Em">program counter</i></a> + which points to the next microinstruction to execute either in the main + microsequence or in a subcall</li> + <li id="ptr">the current value of + <a class="permalink" href="#ptr"><i class="Em">ptr</i></a> which points to + the next char to send/receive</li> + <li id="branch">the current value of the internal + <a class="permalink" href="#branch"><i class="Em">branch + register</i></a></li> +</ul> +<p class="Pp">This data is modified by some of the microinstructions, not + all.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_GET_and_MS_OP_PUT"><a class="permalink" href="#MS_OP_GET_and_MS_OP_PUT">MS_OP_GET + and MS_OP_PUT</a></h2> +<p class="Pp">are microinstructions used to do either predefined standard + IEEE1284-1994 transfers or programmed non-standard I/O.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_RFETCH_-_Register_FETCH"><a class="permalink" href="#MS_OP_RFETCH_-_Register_FETCH">MS_OP_RFETCH + - Register FETCH</a></h2> +<p class="Pp">is used to retrieve the current value of a parallel port register, + apply a mask and save it in a buffer.</p> +<p class="Pp">Parameters:</p> +<ol class="Bl-enum Bd-indent"> + <li>register</li> + <li>character mask</li> + <li>pointer to the buffer</li> +</ol> +<p class="Pp">Predefined macro: MS_RFETCH(reg,mask,ptr)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_RSET_-_Register_SET"><a class="permalink" href="#MS_OP_RSET_-_Register_SET">MS_OP_RSET + - Register SET</a></h2> +<p class="Pp">is used to assert/clear some bits of a particular parallel port + register, two masks are applied.</p> +<p class="Pp">Parameters:</p> +<ol class="Bl-enum Bd-indent"> + <li>register</li> + <li>mask of bits to assert</li> + <li>mask of bits to clear</li> +</ol> +<p class="Pp">Predefined macro: MS_RSET(reg,assert,clear)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_RASSERT_-_Register_ASSERT"><a class="permalink" href="#MS_OP_RASSERT_-_Register_ASSERT">MS_OP_RASSERT + - Register ASSERT</a></h2> +<p class="Pp">is used to assert all bits of a particular parallel port + register.</p> +<p class="Pp">Parameters:</p> +<ol class="Bl-enum Bd-indent"> + <li>register</li> + <li>byte to assert</li> +</ol> +<p class="Pp">Predefined macro: MS_RASSERT(reg,byte)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_DELAY_-_microsecond_DELAY"><a class="permalink" href="#MS_OP_DELAY_-_microsecond_DELAY">MS_OP_DELAY + - microsecond DELAY</a></h2> +<p class="Pp">is used to delay the execution of the microsequence.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>delay in microseconds</li> +</ol> +<p class="Pp">Predefined macro: MS_DELAY(delay)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_SET_-_SET_internal_branch_register"><a class="permalink" href="#MS_OP_SET_-_SET_internal_branch_register">MS_OP_SET + - SET internal branch register</a></h2> +<p class="Pp">is used to set the value of the internal branch register.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>integer value</li> +</ol> +<p class="Pp">Predefined macro: MS_SET(accum)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_DBRA_-_"><a class="permalink" href="#MS_OP_DBRA_-_">MS_OP_DBRA + - Do BRAnch</a></h2> +<p class="Pp">is used to branch if internal branch register decremented by one + result value is positive.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>integer offset in the current executed (sub)microsequence. Offset is added + to the index of the next microinstruction to execute.</li> +</ol> +<p class="Pp">Predefined macro: MS_DBRA(offset)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_BRSET_-_BRanch_on_SET"><a class="permalink" href="#MS_OP_BRSET_-_BRanch_on_SET">MS_OP_BRSET + - BRanch on SET</a></h2> +<p class="Pp">is used to branch if some of the status register bits of the + parallel port are set.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>bits of the status register</li> + <li>integer offset in the current executed (sub)microsequence. Offset is added + to the index of the next microinstruction to execute.</li> +</ol> +<p class="Pp">Predefined macro: MS_BRSET(mask,offset)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_BRCLEAR_-_BRanch_on_CLEAR"><a class="permalink" href="#MS_OP_BRCLEAR_-_BRanch_on_CLEAR">MS_OP_BRCLEAR + - BRanch on CLEAR</a></h2> +<p class="Pp">is used to branch if some of the status register bits of the + parallel port are cleared.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>bits of the status register</li> + <li>integer offset in the current executed (sub)microsequence. Offset is added + to the index of the next microinstruction to execute.</li> +</ol> +<p class="Pp">Predefined macro: MS_BRCLEAR(mask,offset)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_RET_-_RETurn"><a class="permalink" href="#MS_OP_RET_-_RETurn">MS_OP_RET + - RETurn</a></h2> +<p class="Pp">is used to return from a microsequence. This instruction is + mandatory. This is the only way for the microsequencer to detect the end of + the microsequence. The return code is returned in the integer pointed by the + (int *) parameter of the ppb_MS_microseq().</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>integer return code</li> +</ol> +<p class="Pp">Predefined macro: MS_RET(code)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_C_CALL_-_C_function_CALL"><a class="permalink" href="#MS_OP_C_CALL_-_C_function_CALL">MS_OP_C_CALL + - C function CALL</a></h2> +<p class="Pp">is used to call C functions from microsequence execution. This may + be useful when a non-standard I/O is performed to retrieve a data character + from the parallel port.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>the C function to call</li> + <li>the parameter to pass to the function call</li> +</ol> +<p class="Pp">The C function shall be declared as a <var class="Ft">int(*)(void + *p, char *ptr)</var>. The ptr parameter is the current position in the + buffer currently scanned.</p> +<p class="Pp">Predefined macro: MS_C_CALL(func,param)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_PTR_-_initialize_internal_PTR"><a class="permalink" href="#MS_OP_PTR_-_initialize_internal_PTR">MS_OP_PTR + - initialize internal PTR</a></h2> +<p class="Pp">is used to initialize the internal pointer to the currently + scanned buffer. This pointer is passed to any C call (see above).</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li id="xxx_P">pointer to the buffer that shall be accessed by + <a class="permalink" href="#xxx_P"><code class="Fn">xxx_P</code></a>() + microsequence calls. Note that this pointer is automatically incremented + during <code class="Fn">xxx_P</code>() calls.</li> +</ol> +<p class="Pp">Predefined macro: MS_PTR(ptr)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_ADELAY_-_do_an_Asynchronous_DELAY"><a class="permalink" href="#MS_OP_ADELAY_-_do_an_Asynchronous_DELAY">MS_OP_ADELAY + - do an Asynchronous DELAY</a></h2> +<p class="Pp">is used to make a <a class="Xr">cv_timedwait(9)</a> during + microsequence execution.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>delay in ms</li> +</ol> +<p class="Pp">Predefined macro: MS_ADELAY(delay)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_BRSTAT_-_BRanch_on_STATe"><a class="permalink" href="#MS_OP_BRSTAT_-_BRanch_on_STATe">MS_OP_BRSTAT + - BRanch on STATe</a></h2> +<p class="Pp">is used to branch on status register state condition.</p> +<p class="Pp">Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>mask of asserted bits. Bits that shall be asserted in the status register + are set in the mask</li> + <li>mask of cleared bits. Bits that shall be cleared in the status register + are set in the mask</li> + <li>integer offset in the current executed (sub)microsequence. Offset is added + to the index of the next microinstruction to execute.</li> +</ol> +<p class="Pp">Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_SUBRET_-_SUBmicrosequence_RETurn"><a class="permalink" href="#MS_OP_SUBRET_-_SUBmicrosequence_RETurn">MS_OP_SUBRET + - SUBmicrosequence RETurn</a></h2> +<p class="Pp">is used to return from the submicrosequence call. This action is + mandatory before a RET call. Some microinstructions (PUT, GET) may not be + callable within a submicrosequence.</p> +<p class="Pp">No parameter.</p> +<p class="Pp">Predefined macro: MS_SUBRET()</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_CALL_-_submicrosequence_CALL"><a class="permalink" href="#MS_OP_CALL_-_submicrosequence_CALL">MS_OP_CALL + - submicrosequence CALL</a></h2> +<p class="Pp">is used to call a submicrosequence. A submicrosequence is a + microsequence with a SUBRET call. Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>the submicrosequence to execute</li> +</ol> +<p class="Pp">Predefined macro: MS_CALL(microseq)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_RASSERT_P_-_Register_ASSERT_from_internal_PTR"><a class="permalink" href="#MS_OP_RASSERT_P_-_Register_ASSERT_from_internal_PTR">MS_OP_RASSERT_P + - Register ASSERT from internal PTR</a></h2> +<p class="Pp">is used to assert a register with data currently pointed by the + internal PTR pointer. Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>amount of data to write to the register</li> + <li>register</li> +</ol> +<p class="Pp">Predefined macro: MS_RASSERT_P(iter,reg)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_RFETCH_P_-_Register_FETCH_to_internal_PTR"><a class="permalink" href="#MS_OP_RFETCH_P_-_Register_FETCH_to_internal_PTR">MS_OP_RFETCH_P + - Register FETCH to internal PTR</a></h2> +<p class="Pp">is used to fetch data from a register. Data is stored in the + buffer currently pointed by the internal PTR pointer. Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>amount of data to read from the register</li> + <li>register</li> + <li>mask applied to fetched data</li> +</ol> +<p class="Pp">Predefined macro: MS_RFETCH_P(iter,reg,mask)</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="MS_OP_TRIG_-_TRIG_register"><a class="permalink" href="#MS_OP_TRIG_-_TRIG_register">MS_OP_TRIG + - TRIG register</a></h2> +<p class="Pp">is used to trigger the parallel port. This microinstruction is + intended to provide a very efficient control of the parallel port. + Triggering a register is writing data, wait a while, write data, wait a + while... This allows to write magic sequences to the port. Parameter:</p> +<ol class="Bl-enum Bd-indent"> + <li>amount of data to read from the register</li> + <li>register</li> + <li>size of the array</li> + <li>array of unsigned chars. Each couple of u_chars define the data to write + to the register and the delay in us to wait. The delay is limited to 255 + us to simplify and reduce the size of the array.</li> +</ol> +<p class="Pp">Predefined macro: MS_TRIG(reg,len,array)</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="MICROSEQUENCES"><a class="permalink" href="#MICROSEQUENCES">MICROSEQUENCES</a></h1> +<section class="Ss"> +<h2 class="Ss" id="C_structures"><a class="permalink" href="#C_structures">C + structures</a></h2> +<div class="Bd Li"> +<pre>union ppb_insarg { + int i; + char c; + void *p; + int (* f)(void *, char *); +}; + +struct ppb_microseq { + int opcode; /* microins. opcode */ + union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */ +};</pre> +</div> +</section> +<section class="Ss"> +<h2 class="Ss" id="Using_microsequences"><a class="permalink" href="#Using_microsequences">Using + microsequences</a></h2> +<p class="Pp">To instantiate a microsequence, just declare an array of + ppb_microseq structures and initialize it as needed. You may either use + predefined macros or code directly your microinstructions according to the + ppb_microseq definition. For example,</p> +<div class="Bd Pp Li"> +<pre> struct ppb_microseq select_microseq[] = { + + /* parameter list + */ + #define SELECT_TARGET MS_PARAM(0, 1, MS_TYP_INT) + #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT) + + /* send the select command to the drive */ + MS_DASS(MS_UNKNOWN), + MS_CASS(H_nAUTO | H_nSELIN | H_INIT | H_STROBE), + MS_CASS( H_AUTO | H_nSELIN | H_INIT | H_STROBE), + MS_DASS(MS_UNKNOWN), + MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE), + + /* now, wait until the drive is ready */ + MS_SET(VP0_SELTMO), +/* loop: */ MS_BRSET(H_ACK, 2 /* ready */), + MS_DBRA(-2 /* loop */), +/* error: */ MS_RET(1), +/* ready: */ MS_RET(0) + };</pre> +</div> +<p class="Pp" id="ppb_MS_init_msq">Here, some parameters are undefined and must + be filled before executing the microsequence. In order to initialize each + microsequence, one should use the + <a class="permalink" href="#ppb_MS_init_msq"><code class="Fn">ppb_MS_init_msq</code></a>() + function like this:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>ppb_MS_init_msq(select_microseq, 2, + SELECT_TARGET, 1 << target, + SELECT_INITIATOR, 1 << initiator);</pre> +</div> +<p class="Pp">and then execute the microsequence.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="The_microsequencer"><a class="permalink" href="#The_microsequencer">The + microsequencer</a></h2> +<p class="Pp">The microsequencer is executed either at ppbus or adapter level + (see <a class="Xr">ppbus(4)</a> for info about ppbus system layers). Most of + the microsequencer is executed at <a class="Xr">atppc(4)</a> level to avoid + <a class="Xr">ppbus(4)</a> to adapter function call overhead. But some + actions like deciding whereas the transfer is IEEE1284-1994 compliant are + executed at <a class="Xr">ppbus(4)</a> layer.</p> +</section> +</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">atppc(4)</a>, <a class="Xr">ppbus(4)</a>, + <a class="Xr">vpo(4)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">microseq</code> manual page first appeared in + <span class="Ux">FreeBSD 3.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page is based on the <span class="Ux">FreeBSD</span> + <code class="Nm">microseq</code> manual page and was update for the + <span class="Ux">NetBSD</span> port by <span class="An">Gary + Thorpe</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Only one level of submicrosequences is allowed.</p> +<p class="Pp">When triggering the port, maximum delay allowed is 255 us.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 29, 2003</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/microtime.9 3.html b/static/netbsd/man9/microtime.9 3.html new file mode 100644 index 00000000..0966aa13 --- /dev/null +++ b/static/netbsd/man9/microtime.9 3.html @@ -0,0 +1,121 @@ +<table class="head"> + <tr> + <td class="head-ltitle">MICROTIME(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">MICROTIME(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">bintime</code>, + <code class="Nm">getbintime</code>, <code class="Nm">microtime</code>, + <code class="Nm">getmicrotime</code>, <code class="Nm">nanotime</code>, + <code class="Nm">getnanotime</code> — <span class="Nd">get the + current time</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/time.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">bintime</code>(<var class="Fa">struct bintime *bt</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">getbintime</code>(<var class="Fa">struct bintime + *bt</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">microtime</code>(<var class="Fa">struct timeval + *tv</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">getmicrotime</code>(<var class="Fa">struct timeval + *tv</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">nanotime</code>(<var class="Fa">struct timespec + *tsp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">getnanotime</code>(<var class="Fa">struct timespec + *tsp</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#bintime"><code class="Fn" id="bintime">bintime</code></a>() + and <code class="Fn">getbintime</code>() functions store the system time as + a <var class="Vt">struct bintime</var> at the addresses specified by + <var class="Fa">bt</var>. The <code class="Fn">microtime</code>() and + <code class="Fn">getmicrotime</code>() functions perform the same utility, + but record the time as a <var class="Vt">struct timeval</var> instead. + Similarly the <code class="Fn">nanotime</code>() and + <code class="Fn">getnanotime</code>() functions store the time as a + <var class="Vt">struct timespec</var>. The structures are described in + <a class="Xr">timeval(3)</a>.</p> +<p class="Pp" id="bintime~2">The + <a class="permalink" href="#bintime~2"><code class="Fn">bintime</code></a>(), + <code class="Fn">microtime</code>(), and + <a class="permalink" href="#nanotime"><code class="Fn" id="nanotime">nanotime</code></a>() + functions always query the timecounter to return the current time as + precisely as possible. Whereas <code class="Fn">getbintime</code>(), + <code class="Fn">getmicrotime</code>(), and + <code class="Fn">getnanotime</code>() functions are abstractions which + return a less precise, but faster to obtain, time.</p> +<p class="Pp" id="getbintime">The intent of the + <a class="permalink" href="#getbintime"><code class="Fn">getbintime</code></a>(), + <a class="permalink" href="#getmicrotime"><code class="Fn" id="getmicrotime">getmicrotime</code></a>(), + and + <a class="permalink" href="#getnanotime"><code class="Fn" id="getnanotime">getnanotime</code></a>() + functions is to enforce the user's preference for timer accuracy versus + execution time. They should be used where a precision of + 1/<i class="Em">HZ</i> (e.g., 10 msec on a 100<i class="Em">HZ</i> machine, + see <a class="Xr">hz(9)</a>) is acceptable or where performance is + priority.</p> +<p class="Pp">The system realtime clock is guaranteed to be monotonically + increasing at all times. As such, all calls to these functions are + guaranteed to return a system time greater than or equal to the system time + returned in any previous calls. Comparable functions exist to retrieve the + time elapsed since boot; see <a class="Xr">microuptime(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The implementation of the + <a class="permalink" href="#microtime"><code class="Fn" id="microtime">microtime</code></a>() + family of functions is in <span class="Pa">sys/kern/kern_tc.c</span> as a + part of the <a class="Xr">timecounter(9)</a> framework.</p> +<p class="Pp">The implementation of the time counter sources used by the + <a class="Xr">timecounter(9)</a> is machine dependent, hence its location in + the source code tree varies from architecture to architecture.</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">settimeofday(2)</a>, + <a class="Xr">bintime_add(9)</a>, <a class="Xr">inittodr(9)</a>, + <a class="Xr">time_second(9)</a>, <a class="Xr">tvtohz(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page was written by <span class="An">Jeremy + Cooper</span> and + <br/> + <span class="An">Kelly Yancey</span> + <<a class="Mt" href="mailto:kbyanc@posi.net">kbyanc@posi.net</a>>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">Despite the guarantee that the system realtime clock will always + be monotonically increasing, it is always possible for the system clock to + be manually reset by the system administrator to any date.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 13, 2013</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/module.9 3.html b/static/netbsd/man9/module.9 3.html new file mode 100644 index 00000000..f8cf2512 --- /dev/null +++ b/static/netbsd/man9/module.9 3.html @@ -0,0 +1,539 @@ +<table class="head"> + <tr> + <td class="head-ltitle">MODULE(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">MODULE(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">module</code>, + <code class="Nm">module_load</code>, + <code class="Nm">module_autoload</code>, + <code class="Nm">module_unload</code>, + <code class="Nm">module_init_class</code>, + <code class="Nm">module_hold</code>, <code class="Nm">module_rele</code>, + <code class="Nm">module_find_section</code>, + <code class="Nm">module_kernel</code>, <code class="Nm">module_name</code>, + <code class="Nm">module_source</code>, + <code class="Nm">module_register_callbacks</code>, + <code class="Nm">module_unregister_callbacks</code>, + <code class="Nm">module_specific_key_create</code>, + <code class="Nm">module_specific_key_delete</code>, + <code class="Nm">module_getspecific</code>, + <code class="Nm">module_setspecific</code> — <span class="Nd">kernel + module loader</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/module.h</a>></code></p> +<p class="Pp"><code class="Fn">MODULE</code>(<var class="Fa" style="white-space: nowrap;">class</var>, + <var class="Fa" style="white-space: nowrap;">name</var>, + <var class="Fa" style="white-space: nowrap;">required</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">module_load</code>(<var class="Fa" style="white-space: nowrap;">const + char *name</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>, <var class="Fa" style="white-space: nowrap;">prop_dictionary_t + props</var>, <var class="Fa" style="white-space: nowrap;">modclass_t + class</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">module_autoload</code>(<var class="Fa" style="white-space: nowrap;">const + char *name</var>, <var class="Fa" style="white-space: nowrap;">modclass_t + class</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">module_unload</code>(<var class="Fa" style="white-space: nowrap;">const + char *name</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_init_class</code>(<var class="Fa" style="white-space: nowrap;">modclass_t + class</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_hold</code>(<var class="Fa" style="white-space: nowrap;">module_t + *module</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_rele</code>(<var class="Fa" style="white-space: nowrap;">module_t + *module</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">module_find_section</code>(<var class="Fa" style="white-space: nowrap;">const + char *</var>, <var class="Fa" style="white-space: nowrap;">void **</var>, + <var class="Fa" style="white-space: nowrap;">size_t *</var>);</p> +<p class="Pp"><var class="Ft">module_t *</var> + <br/> + <code class="Fn">module_kernel</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">const char *</var> + <br/> + <code class="Fn">module_name</code>(<var class="Fa" style="white-space: nowrap;">struct + module *module</var>);</p> +<p class="Pp"><var class="Ft">modsrc_t</var> + <br/> + <code class="Fn">module_source</code>(<var class="Fa" style="white-space: nowrap;">struct + module *module</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_init</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_start_unload_thread</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_builtin_require_force</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_load_vfs_init</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">module_register_callbacks</code>(<var class="Fa" style="white-space: nowrap;">void + (*)(struct module *)</var>, + <var class="Fa" style="white-space: nowrap;">void (*unload)(struct module + *)</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_unregister_callbacks</code>(<var class="Fa" style="white-space: nowrap;">void + *</var>);</p> +<p class="Pp"><var class="Ft">specificdata_key_t</var> + <br/> + <code class="Fn">module_specific_key_create</code>(<var class="Fa" style="white-space: nowrap;">specificdata_key_t + *keyp</var>, + <var class="Fa" style="white-space: nowrap;">specificdata_dtor_t + dtor</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">module_specific_key_delete</code>(<var class="Fa" style="white-space: nowrap;">specificdata_key_t + key</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">module_getspecific</code>(<var class="Fa" style="white-space: nowrap;">module_t + *mod</var>, <var class="Fa" style="white-space: nowrap;">specificdata_key_t + key</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">module_setspecific</code>(<var class="Fa" style="white-space: nowrap;">module_t + *mod</var>, <var class="Fa" style="white-space: nowrap;">specificdata_key_t + key</var>, <var class="Fa" style="white-space: nowrap;">void + *data</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Modules are sections of code that can be independently linked and + selectively loaded into or unloaded from a running kernel. This provides a + mechanism to update the module without having to relink the kernel and + reboot. Modules can be loaded from within the kernel image, provided by the + boot loader, or loaded from the file system.</p> +<p class="Pp">The <code class="Nm">module</code> subsystem includes two data + types:</p> +<ol class="Bl-enum Bd-indent"> + <li>The <var class="Vt">module_t</var> type provides storage to describe a + module.</li> + <li>The <var class="Vt">modinfo_t</var> type resides within + <var class="Vt">module_t</var> and contains module header info.</li> +</ol> +<p class="Pp">The module subsystem is protected by the global + <var class="Va">kernconfig_mutex</var>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="MODULE"><a class="permalink" href="#MODULE"><code class="Fn">MODULE</code></a>(<var class="Fa">class</var>, + <var class="Fa">name</var>, <var class="Fa">required</var>)</dt> + <dd>The <code class="Fn">MODULE</code>() macro creates and initializes a + <var class="Vt">modinfo_t</var> structure. The <var class="Fa">class</var> + argument identifies the class of module, and must be one of the following + (note that <code class="Dv">MODULE_CLASS_ANY</code> should not be used + here): + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt id="MODULE_CLASS_VFS"><a class="permalink" href="#MODULE_CLASS_VFS"><code class="Dv">MODULE_CLASS_VFS</code></a></dt> + <dd>The module provide a virtual file system - see + <a class="Xr">vfs(9)</a></dd> + <dt id="MODULE_CLASS_DRIVER"><a class="permalink" href="#MODULE_CLASS_DRIVER"><code class="Dv">MODULE_CLASS_DRIVER</code></a></dt> + <dd>The module is a device driver - see <a class="Xr">driver(9)</a></dd> + <dt id="MODULE_CLASS_EXEC"><a class="permalink" href="#MODULE_CLASS_EXEC"><code class="Dv">MODULE_CLASS_EXEC</code></a></dt> + <dd>The module provides an alternate execution environment - see the + various <code class="Dv">COMPAT_xxx</code> options in + <a class="Xr">options(4)</a></dd> + <dt id="MODULE_CLASS_SECMODEL"><a class="permalink" href="#MODULE_CLASS_SECMODEL"><code class="Dv">MODULE_CLASS_SECMODEL</code></a></dt> + <dd>The module provides a security model - see + <a class="Xr">secmodel(9)</a></dd> + <dt id="MODULE_CLASS_BUFQ"><a class="permalink" href="#MODULE_CLASS_BUFQ"><code class="Dv">MODULE_CLASS_BUFQ</code></a></dt> + <dd>The module provides a buffer queue strategy - see + <a class="Xr">bufq(9)</a></dd> + <dt id="MODULE_CLASS_MISC"><a class="permalink" href="#MODULE_CLASS_MISC"><code class="Dv">MODULE_CLASS_MISC</code></a></dt> + <dd>The module provides miscellaneous kernel services</dd> + </dl> + </div> + <p class="Pp">The <var class="Fa">name</var> argument provides the name of + the module. Loaded modules, including those that are built-in to the + kernel, must all have unique names.</p> + <p class="Pp">The <var class="Fa">required</var> argument is a quoted string + containing a comma-separated list of module names that are required by + this module. The list must not contain any white-space. When a module is + loaded, all of its required modules are auto-loaded and initialized + before the module itself is loaded. Loading of required modules is a + recursive operation.</p> + <p class="Pp">If there are no required modules, this argument should be + specified as <code class="Dv">NULL</code>.</p> + <p class="Pp" id="MODULE~2">In addition to the explicit arguments, the + <a class="permalink" href="#MODULE~2"><code class="Fn">MODULE</code></a>() + macro creates a reference to the module's + <code class="Fn">modcmd</code>() function. This function is defined + as:</p> + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt id="xxx_modcmd"><var class="Ft">int</var></dt> + <dd><a class="permalink" href="#xxx_modcmd"><code class="Fn">xxx_modcmd</code></a>(<var class="Fa">modcmd_t + cmd</var>, <var class="Fa">void *data</var>)</dd> + </dl> + </div> + <p class="Pp">(where xxx is the name of the module, from the + <code class="Dv">MODULE</code> macro).</p> + <p class="Pp">The <var class="Fa">cmd</var> argument requests one of the + following operations:</p> + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt id="MODULE_CMD_INIT"><a class="permalink" href="#MODULE_CMD_INIT"><code class="Dv">MODULE_CMD_INIT</code></a></dt> + <dd>Perform module-specific initialization when the module is loaded.</dd> + <dt id="MODULE_CMD_FINI"><a class="permalink" href="#MODULE_CMD_FINI"><code class="Dv">MODULE_CMD_FINI</code></a></dt> + <dd>Perform module-specific clean-up before the module is unloaded.</dd> + <dt id="MODULE_CMD_AUTOUNLOAD"><a class="permalink" href="#MODULE_CMD_AUTOUNLOAD"><code class="Dv">MODULE_CMD_AUTOUNLOAD</code></a></dt> + <dd>Notify the module that it is about to be unloaded.</dd> + <dt id="MODULE_CMD_STAT"><a class="permalink" href="#MODULE_CMD_STAT"><code class="Dv">MODULE_CMD_STAT</code></a></dt> + <dd>Request the module to provide status information (not currently + implemented).</dd> + </dl> + </div> + <p class="Pp" id="modcmd">All modules' + <a class="permalink" href="#modcmd"><code class="Fn">modcmd</code></a>() + functions must implement the <code class="Dv">MODULE_CMD_INIT</code> and + <code class="Dv">MODULE_CMD_FINI</code> commands. The other commands are + optional, and should return <code class="Er">ENOTTY</code> if not + implemented.</p> + <p class="Pp">For the <code class="Dv">MODULE_CMD_INIT</code> command, the + <var class="Fa">data</var> argument is used to pass a pointer to the + module's <a class="Xr">prop_dictionary(3)</a>. For the + <code class="Dv">MODULE_CMD_STAT</code> command, the + <var class="Fa">data</var> argument points to a buffer where the status + information should be placed.</p> + <p class="Pp">The __link_set mechanism is used to enable the + <code class="Nm">module</code> subsystem to locate the + <var class="Vt">modinfo_t</var> structure.</p> + </dd> + <dt id="module_load"><a class="permalink" href="#module_load"><code class="Fn">module_load</code></a>(<var class="Fa">name</var>, + <var class="Fa">flags</var>, <var class="Fa">props</var>, + <var class="Fa">class</var>)</dt> + <dd>Load a module, link it into the running kernel, and call the module's + <code class="Fn">modcmd</code>() routine with a <var class="Fa">cmd</var> + argument of <code class="Dv">MODULE_CMD_INIT</code>. If the specified + module requires other modules, they are loaded first; if any required + module cannot be loaded or if any of their + <code class="Fn">modcmd</code>() control routines returns a non-zero + status, loading of this module and the specific required module will fail. + The required modules are marked for automatic unloading. Thus, if the + loading of the module failed, the required modules will be automatically + unloaded after a short delay. + <p class="Pp" id="module_unload">The loader will look first for a built-in + module with the specified <var class="Fa">name</var> that has not been + disabled (see + <a class="permalink" href="#module_unload"><code class="Fn">module_unload</code></a>() + below). If a built-in module with that <var class="Fa">name</var> is not + found, the list of modules prepared by the boot loader is searched. If + the named module is still not found, an attempt is made to locate the + module within the file system, provided it has been mounted by the + initialization code.</p> + <p class="Pp">The <var class="Fa">flags</var> argument can include:</p> + <div class="Bd-indent"> + <dl class="Bl-tag"> + <dt id="MODCTL_NO_PROP"><a class="permalink" href="#MODCTL_NO_PROP"><code class="Dv">MODCTL_NO_PROP</code></a></dt> + <dd>When loading a module from the file system, do not attempt to locate a + corresponding prop_dictionary file.</dd> + <dt id="MODCTL_LOAD_FORCE"><a class="permalink" href="#MODCTL_LOAD_FORCE"><code class="Dv">MODCTL_LOAD_FORCE</code></a></dt> + <dd>Force loading of disabled built-in modules and modules built for a + different version of the operating system.</dd> + </dl> + </div> + <p class="Pp" id="modcmd~2">The <var class="Fa">props</var> argument points + to an externalized property list which is passed to the module's + <a class="permalink" href="#modcmd~2"><code class="Fn">modcmd</code></a>() + routine. If a module is being loaded from the file system, and the + <code class="Dv">MODCTL_NO_PROP</code> flag is not set, the system + searches for a file with the same name as the module file, but with the + suffix “<span class="Pa">.plist</span>”. If this file is + found, the prop_dictionary it contains is loaded and merged with the + prop_dictionary from the <var class="Fa">props</var> argument.</p> + <p class="Pp">The <var class="Fa">class</var> argument can be any of:</p> + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt id="MODULE_CLASS_ANY"><a class="permalink" href="#MODULE_CLASS_ANY"><code class="Dv">MODULE_CLASS_ANY</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="MODULE_CLASS_DRIVER~2"><a class="permalink" href="#MODULE_CLASS_DRIVER~2"><code class="Dv">MODULE_CLASS_DRIVER</code></a></dt> + <dd>Device driver</dd> + <dt id="MODULE_CLASS_EXEC~2"><a class="permalink" href="#MODULE_CLASS_EXEC~2"><code class="Dv">MODULE_CLASS_EXEC</code></a></dt> + <dd>Executable image handler</dd> + <dt id="MODULE_CLASS_MISC~2"><a class="permalink" href="#MODULE_CLASS_MISC~2"><code class="Dv">MODULE_CLASS_MISC</code></a></dt> + <dd>Miscellaneous module</dd> + <dt id="MODULE_CLASS_SECMODEL~2"><a class="permalink" href="#MODULE_CLASS_SECMODEL~2"><code class="Dv">MODULE_CLASS_SECMODEL</code></a></dt> + <dd>Security model (see <a class="Xr">secmodel(9)</a> for more + details)</dd> + <dt id="MODULE_CLASS_VFS~2"><a class="permalink" href="#MODULE_CLASS_VFS~2"><code class="Dv">MODULE_CLASS_VFS</code></a></dt> + <dd>Virtual file system</dd> + </dl> + </div> + <p class="Pp" id="secmodel_register">If the class is not + <code class="Dv">MODULE_CLASS_ANY</code>, the class of the module being + loaded must match the requested <var class="Fa">class</var>. Except when + verifying a module's class when it is being loaded, module classes other + than <code class="Dv">MODULE_CLASS_SECMODEL</code> are transparent to + the module subsystem. They are provided only for the benefit of the + subsystem's clients. Modules with class + <code class="Dv">MODULE_CLASS_SECMODEL</code> are automatically + registered with + <a class="permalink" href="#secmodel_register"><code class="Fn">secmodel_register</code></a>() + after being successfully loaded, and automatically deregistered with + <a class="permalink" href="#secmodel_deregister"><code class="Fn" id="secmodel_deregister">secmodel_deregister</code></a>() + when being unloaded.</p> + <p class="Pp" id="module_load~2">The + <a class="permalink" href="#module_load~2"><code class="Fn">module_load</code></a>() + routine is primarily intended as the implementation of the + <code class="Dv">MODCTL_LOAD</code> option of the + <a class="Xr">modctl(2)</a> system call.</p> + </dd> + <dt><code class="Fn">module_autoload</code>(<var class="Fa">name</var>, + <var class="Fa">class</var>)</dt> + <dd>Auto-load a module, making it available for automatic unloading. The + <var class="Fa">name</var> and <var class="Fa">class</var> arguments are + the same as for the <code class="Fn">module_load</code>() routine. + <p class="Pp" id="module_autoload">The module subsystem uses a kernel thread + to attempt to automatically unload modules a short time (currently, 10 + seconds) after being loaded by + <a class="permalink" href="#module_autoload"><code class="Fn">module_autoload</code></a>(). + Before the module is unloaded by this thread, its + <code class="Fn">modcmd</code>() is called with the + <var class="Fa">cmd</var> argument specified as + <code class="Dv">MODULE_CMD_AUTOUNLOAD</code>. A module can prevent + itself from being unloaded by returning a non-zero value. Exception: If + <code class="Li">kern.module.autounload_unsafe</code> is set, a module + that returns <code class="Er">ENOTTY</code>, meaning it does not + understand the command, may still be autounloaded.</p> + <p class="Pp" id="module_autoload~2">The + <a class="permalink" href="#module_autoload~2"><code class="Fn">module_autoload</code></a>() + function is intended for use by kernel components to locate and load + optional system components. The function is also used to load modules + that are required by other modules.</p> + <p class="Pp" id="modcmd~3">The directory from which the module is loaded + will be searched for a file with the same name as the module file, but + with the suffix “<span class="Pa">.plist</span>”. If this + file is found, the prop_dictionary it contains will be loaded and passed + to the module's + <a class="permalink" href="#modcmd~3"><code class="Fn">modcmd</code></a>() + routine. If this prop_dictionary contains a + “<span class="Pa">noautoload</span>” property which is set + to “<span class="Pa">true</span>” then the system will + refuse to load the module.</p> + </dd> + <dt><code class="Fn">module_unload</code>(<var class="Fa">name</var>)</dt> + <dd>Unload a module. If the module's reference count is non-zero, the function + returns <code class="Er">EBUSY</code>. Otherwise, the module's + <code class="Fn">modcmd</code>() routine is called with a + <var class="Fa">cmd</var> argument of + <code class="Dv">MODULE_CMD_FINI</code>. If the + <code class="Fn">modcmd</code>() routine returns with an error, then the + error is returned to the caller otherwise the module is unloaded. + <p class="Pp" id="module_unload~2">The reference counts of all modules that + were required by this module are decremented, but the required modules + are not unloaded by the call to + <a class="permalink" href="#module_unload~2"><code class="Fn">module_unload</code></a>(). + Instead, the required modules may be unloaded by subsequent calls to + <code class="Fn">module_unload</code>().</p> + <p class="Pp" id="module_load~3">Unloading a built-in module causes the + module to be marked as disabled. This prevents the module from being + re-loaded, except by the + <a class="permalink" href="#module_load~3"><code class="Fn">module_load</code></a>() + function with the <var class="Fa">flags</var> argument set to + <code class="Dv">MODULE_FORCE_LOAD</code>.</p> + <p class="Pp" id="module_unload~3">The + <a class="permalink" href="#module_unload~3"><code class="Fn">module_unload</code></a>() + function may be called by the <a class="Xr">modctl(2)</a> system call, + by the module subsystem's internal auto-unload thread, or by other + kernel facilities. Generally, other kernel facilities should not be + calling this function.</p> + </dd> + <dt id="module_init_class"><a class="permalink" href="#module_init_class"><code class="Fn">module_init_class</code></a>(<var class="Fa">class</var>)</dt> + <dd>Load and initialize all available modules of the specified + <var class="Fa">class</var>. Any built-in modules that have not been + disabled, and any modules provided by the boot loader are loaded.</dd> + <dt id="module_hold"><a class="permalink" href="#module_hold"><code class="Fn">module_hold</code></a>(<var class="Fa">module</var>)</dt> + <dd>Increment the reference count of a module. A module cannot be unloaded if + its reference count is non-zero.</dd> + <dt id="module_rele"><a class="permalink" href="#module_rele"><code class="Fn">module_rele</code></a>(<var class="Fa">module</var>)</dt> + <dd>Decrement the reference count of a module.</dd> + <dt id="module_find_section"><a class="permalink" href="#module_find_section"><code class="Fn">module_find_section</code></a>(<var class="Fa">name</var>, + <var class="Fa">addr</var>, <var class="Fa">size</var>)</dt> + <dd>Find the start address and size of linker section + <var class="Ar">name</var> within a module. The miniroot module uses this + routine to find the address and size of the embedded file system image. + This routine can only examine the linker data for the module that is + currently being initialized; it cannot examine data for any other + module.</dd> + <dt id="module_kernel"><a class="permalink" href="#module_kernel"><code class="Fn">module_kernel</code></a>(<var class="Fa">void</var>)</dt> + <dd>Returns a pointer to a <var class="Ft">module_t</var> structure describing + the kernel module.</dd> + <dt id="module_name"><a class="permalink" href="#module_name"><code class="Fn">module_name</code></a>(<var class="Fa">module</var>)</dt> + <dd>Returns a pointer to the module's name.</dd> + <dt id="module_source"><a class="permalink" href="#module_source"><code class="Fn">module_source</code></a>(<var class="Fa">module</var>)</dt> + <dd>Returns the source of the module, one of + <code class="Dv">MODULE_SOURCE_KERNEL</code>, + <code class="Dv">MODULE_SOURCE_BOOT</code>, or + <code class="Dv">MODULE_SOURCE_FILESYS</code>.</dd> + <dt id="module_init"><a class="permalink" href="#module_init"><code class="Fn">module_init</code></a>(<var class="Fa">void</var>)</dt> + <dd>Initialize the module subsystem. Creates and initializes various data + structures, locates all built-in modules, and establishes the sub-system's + <a class="Xr">sysctl(8)</a> tree. <code class="Fn">module_init</code>() is + called early in system initialization to facilitate use of security model + modules.</dd> + <dt id="module_start_unload_thread"><a class="permalink" href="#module_start_unload_thread"><code class="Fn">module_start_unload_thread</code></a>(<var class="Fa">void</var>)</dt> + <dd>Create the thread that attempts to automatically unload modules that were + loaded via the <code class="Fn">module_autoload</code>() routine. The + function is called only once, after the scheduler and timer functions are + initialized.</dd> + <dt id="module_builtin_require_force"><a class="permalink" href="#module_builtin_require_force"><code class="Fn">module_builtin_require_force</code></a>(<var class="Fa">void</var>)</dt> + <dd>Mark as "disabled" any built-in modules that have not been + successfully initialized. Modules marked "disabled" can only be + loaded if the <code class="Dv">MODCTL_LOAD_FORCE</code> is specified. + <code class="Fn">module_builtin_require_force</code>() is called near the + end of system initialization, after the <a class="Xr">init(8)</a> process + is created.</dd> + <dt id="module_load_vfs_init"><a class="permalink" href="#module_load_vfs_init"><code class="Fn">module_load_vfs_init</code></a>(<var class="Fa">void</var>)</dt> + <dd>The module subsystem is initialized early, long before any file systems + are available. After the root file system is mounted, + <code class="Fn">module_load_vfs_init</code>(<var class="Fa">void</var>) + is used to enable loading modules from the file system. Until this routine + is called, modules can only be loaded if they were built-in to the kernel + image or provided by the boot loader.</dd> + <dt id="module_register_callbacks"><a class="permalink" href="#module_register_callbacks"><code class="Fn">module_register_callbacks</code></a>(<var class="Fa">void + (*load)(struct module *)</var>, <var class="Fa">void (*unload)(struct module + *)</var>)</dt> + <dd>Register a new set of callbacks. The <var class="Fa">load</var> callback + is invoked after any module (including this module) is successfully + loaded; the <var class="Fa">unload</var> callback is invoked before any + module is unloaded. Each load or unload event can result in multiple + invocations of the callback routines. An opaque cookie is returned which + can be passed to + <a class="permalink" href="#module_unregister_callbacks"><code class="Fn" id="module_unregister_callbacks">module_unregister_callbacks</code></a>().</dd> + <dt><code class="Fn">module_unregister_callbacks</code>(<var class="Fa">void + *opaque</var>)</dt> + <dd>Unregister a set of callback routines previously registered with + <code class="Fn">module_register_callbacks</code>(). The + <var class="Fa">opaque</var> argument should be the return value from the + previous <code class="Fn">module_register_callbacks</code>() call.</dd> + <dt id="module_specific_key_create"><a class="permalink" href="#module_specific_key_create"><code class="Fn">module_specific_key_create</code></a>(<var class="Fa">specificdata_key_t + *keyp</var>, <var class="Fa">specificdata_dtor_t dtor</var>)</dt> + <dd>Creates a new specificdata_key for use within the + <code class="Nm">module</code> domain. The key identifier is returned in + <var class="Fa">keyp</var>.</dd> + <dt id="module_specific_key_delete"><a class="permalink" href="#module_specific_key_delete"><code class="Fn">module_specific_key_delete</code></a>(<var class="Fa">specificdata_key_t + key</var>)</dt> + <dd>Deletes the specified specificdata_key <var class="Fa">key</var> from the + <code class="Nm">module</code> domain.</dd> + <dt id="module_getspecific"><a class="permalink" href="#module_getspecific"><code class="Fn">module_getspecific</code></a>(<var class="Fa">module_t + *mod</var>, <var class="Fa">specificdata_key_t key</var>)</dt> + <dd>Retrieves the value associated with <var class="Fa">key</var> from module + <var class="Fa">mod</var>.</dd> + <dt id="module_setspecific"><a class="permalink" href="#module_setspecific"><code class="Fn">module_setspecific</code></a>(<var class="Fa">module_t + *mod</var>, <var class="Fa">specificdata_key_t key</var>, + <var class="Fa">void *data</var>)</dt> + <dd>Stores <var class="Fa">data</var> as the value associated with + <var class="Fa">key</var> for module <var class="Fa">mod</var>.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="PROGRAMMING_CONSIDERATIONS"><a class="permalink" href="#PROGRAMMING_CONSIDERATIONS">PROGRAMMING + CONSIDERATIONS</a></h1> +<p class="Pp">The module subsystem is designed to be called recursively, but + only within a single LWP. This permits one module's + <code class="Fn">modcmd</code>() routine to load or unload other + modules.</p> +<p class="Pp">Additional considerations:</p> +<ul class="Bl-bullet Bd-indent"> + <li id="modcmd~4">A module is not permitted to load or unload itself. Attempts + to load or unload a module from within its own + <a class="permalink" href="#modcmd~4"><code class="Fn">modcmd</code></a>() + routine will fail with <code class="Er">EEXIST</code> or + <code class="Er">EBUSY</code>, respectively.</li> + <li>Although a module can be loaded by using either + <code class="Fn">module_load</code>() or + <code class="Fn">module_autoload</code>(), it is not possible for the + module's <code class="Fn">modcmd</code>() routine to distinguish between + the two methods. Any module which needs to ensure that it does not get + auto-unloaded must either handle the + <code class="Dv">MODULE_CMD_AUTOUNLOAD</code> command in its + <code class="Fn">modcmd</code>() routine, or use + <code class="Fn">module_hold</code>() to increment its reference count. + Note however that modules loaded manually with + <a class="Xr">modload(8)</a> are never auto-unloaded.</li> +</ul> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">A set of example modules is available in the + <span class="Pa">src/sys/modules/examples</span> directory hierarchy.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The core of the kernel module implementation is in + <span class="Pa">sys/kern/kern_module.c</span> and + <span class="Pa">sys/kern/kern_module_vfs.c</span>.</p> +<p class="Pp">The routines for linking the module are in + <span class="Pa">sys/kern/subr_kobj.c</span>.</p> +<p class="Pp">The routines for reading a module from the file system are in + <span class="Pa">sys/kern/subr_kobj_vfs.c</span>.</p> +<p class="Pp">The header file + <code class="In"><<a class="In">sys/sys/module.h</a>></code> describes + the public interface.</p> +<p class="Pp" id="kobj_machdep">In addition, each architecture is expected to + provide + <a class="permalink" href="#kobj_machdep"><code class="Fn">kobj_machdep</code></a>(), + <a class="permalink" href="#kobj_reloc"><code class="Fn" id="kobj_reloc">kobj_reloc</code></a>(), + and + <a class="permalink" href="#module_init_md"><code class="Fn" id="module_init_md">module_init_md</code></a>(). + <code class="Fn">kobj_machdep</code>() is for any machine dependent actions, + such as flushing caches, that are needed when a module is loaded or + unloaded. <code class="Fn">kobj_reloc</code>() deals with resolution of + relocatable symbols. <code class="Fn">module_init_md</code>() is for finding + modules passed in by the boot loader.</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">modctl(2)</a>, <a class="Xr">module(7)</a>, + <a class="Xr">specificdata(9)</a>, <a class="Xr">intro(9lua)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The kernel module subsystem first appeared in + <span class="Ux">NetBSD 5.0</span>. It replaces the “LKM” + subsystem from earlier releases.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">module</code> system was written by + <span class="An">Andrew Doran</span> + <<a class="Mt" href="mailto:ad@NetBSD.org">ad@NetBSD.org</a>>. This + manual page was written by <span class="An">Paul Goyette</span> + <<a class="Mt" href="mailto:pgoyette@NetBSD.org">pgoyette@NetBSD.org</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 21, 2021</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/namecache.9 3.html b/static/netbsd/man9/namecache.9 3.html new file mode 100644 index 00000000..39271d56 --- /dev/null +++ b/static/netbsd/man9/namecache.9 3.html @@ -0,0 +1,223 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NAMECACHE(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">NAMECACHE(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">namecache</code>, + <code class="Nm">cache_lookup</code>, + <code class="Nm">cache_revlookup</code>, + <code class="Nm">cache_enter</code>, <code class="Nm">cache_purge</code>, + <code class="Nm">cache_purgevfs</code>, + <code class="Nm">namecache_print</code> — <span class="Nd">name + lookup cache</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/namei.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/proc.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/uio.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/vnode.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cache_lookup</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">const char + *name</var>, <var class="Fa" style="white-space: nowrap;">size_t + namelen</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + nameiop</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + nameiflags</var>, <var class="Fa" style="white-space: nowrap;">int + *iswhiteout</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">cache_revlookup</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *dvp</var>, <var class="Fa" style="white-space: nowrap;">char **bpp</var>, + <var class="Fa" style="white-space: nowrap;">char *bufp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cache_enter</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *vp</var>, <var class="Fa" style="white-space: nowrap;">const char + *name</var>, <var class="Fa" style="white-space: nowrap;">size_t + namelen</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + nameiflags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cache_purge</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">cache_purgevfs</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">namecache_print</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">void + (*func)(const char *, ...)</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The name lookup cache is the mechanism to allow the file system + type dependent algorithms to quickly resolve a file's vnode from its + pathname. The name lookup cache is generally accessed through the + higher-level <a class="Xr">namei(9)</a> interface.</p> +<p class="Pp">The name of the file is used to look up an entry associated with + the file in the name lookup cache. If no entry is found, one is created for + it. If an entry is found, the information obtained from the cache lookup + contains information about the file which is useful to the file system type + dependent functions.</p> +<p class="Pp">The name lookup cache is managed by a least recently used (LRU) + algorithm so frequently used names will hang around. The cache itself is a + hash table called <var class="Va">nchashtbl</var>, containing + <i class="Em">namecache</i> entries that are allocated dynamically from a + kernel memory pool. Each entry has the following structure:</p> +<div class="Bd Pp Li"> +<pre>#define NCHNAMLEN 31 /* maximum name segment length */ +struct namecache { + LIST_ENTRY(namecache) nc_hash; /* hash chain */ + TAILQ_ENTRY(namecache) nc_lru; /* LRU chain */ + LIST_ENTRY(namecache) nc_vhash; /* directory hash chain */ + LIST_ENTRY(namecache) nc_dvlist; + struct vnode *nc_dvp; /* vnode of parent of name */ + LIST_ENTRY(namecache) nc_vlist; + struct vnode *nc_vp; /* vnode the name refers to */ + int nc_flags; /* copy of componentname's ISWHITEOUT */ + char nc_nlen; /* length of name */ + char nc_name[NCHNAMLEN]; /* segment name */ +};</pre> +</div> +<p class="Pp">For simplicity (and economy of storage), names longer than a + maximum length of NCHNAMLEN are not cached; they occur infrequently in any + case, and are almost never of interest.</p> +<p class="Pp" id="ncvhashtbl">Each <i class="Em">namecache</i> entry can appear + on two hash chains in addition to <var class="Va">nchashtbl</var>: + <a class="permalink" href="#ncvhashtbl"><i class="Em">ncvhashtbl</i></a> + (the name cache directory hash chain), and + <a class="permalink" href="#nclruhead"><i class="Em" id="nclruhead">nclruhead</i></a> + (the name cache LRU chain). The hash chains are indexed by a hash value + obtained from the file's name and the address of its parent directory + vnode.</p> +<p class="Pp" id="componentname">Functions which access to the name cache pass + arguments in the partially initialised + <a class="permalink" href="#componentname"><i class="Em">componentname</i></a> + structure. See <a class="Xr">vnodeops(9)</a> for details on this + structure.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="cache_lookup"><a class="permalink" href="#cache_lookup"><code class="Fn">cache_lookup</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">name</var>, <var class="Fa">namelen</var>, + <var class="Fa">nameiop</var>, <var class="Fa">nameiflags</var>, + <var class="Fa">iswhiteout</var>, <var class="Fa">vpp</var>)</dt> + <dd>Look for a name in the cache. <code class="Fn">cache_lookup</code>() is + called with <var class="Fa">dvp</var> pointing to the vnode of the + directory to search. The <var class="Fa">name</var> and + <var class="Fa">namelen</var> arguments specify the name to look for. The + <var class="Fa">nameiop</var> and <var class="Fa">nameiflags</var> should + be taken from the <var class="Fa">cn_nameiop</var> and + <var class="Fa">cn_flags</var> fields of struct componentname. + <p class="Pp" id="no">The lookup can produce either a cache miss or a cache + hit, and a cache hit can either be a positive hit, where the name looked + up refers to some existing object, or a negative hit, where the name + looked up is known to refer to + <a class="permalink" href="#no"><i class="Em">no</i></a> existing + object. (The lookup cannot fail, in the sense of generating an error + condition that requires aborting the operation in progress.)</p> + <p class="Pp" id="cache_lookup~2">On a cache miss, + <a class="permalink" href="#cache_lookup~2"><code class="Fn">cache_lookup</code></a>() + returns zero (false). On a positive hit, the unlocked vnode for the + object found is stored in <var class="Fa">vpp</var>, and a nonzero + (true) value is returned. On a negative hit, <var class="Fa">vpp</var> + is set to contain a null pointer and a nonzero value is returned. + Usually a negative hit will prompt the caller to fail with + <code class="Er">ENOENT</code>.</p> + <p class="Pp" id="cache_lookup~3">The <var class="Fa">iswhiteout</var> + argument is a pointer to an integer result that will be set to nonzero + if the entry represents a whiteout, and zero if it does not. This + pointer may be <code class="Dv">NULL</code> if the caller does not + support whiteouts. According to the current scheme for handling + whiteouts, if + <a class="permalink" href="#cache_lookup~3"><code class="Fn">cache_lookup</code></a>() + sets <var class="Fa">iswhiteout</var> the caller should add + <code class="Dv">ISWHITEOUT</code> to the <var class="Fa">cn_flags</var> + field of its struct componentname.</p> + </dd> + <dt id="cache_revlookup"><a class="permalink" href="#cache_revlookup"><code class="Fn">cache_revlookup</code></a>(<var class="Fa">vp</var>, + <var class="Fa">dvp</var>, <var class="Fa">bpp</var>, + <var class="Fa">bufp</var>)</dt> + <dd>Scan cache looking for name of directory entry pointing at + <var class="Fa">vp</var> and fill in <var class="Fa">dvpp</var>. If + <var class="Fa">bufp</var> is non-<code class="Dv">NULL</code>, also place + the name in the buffer which starts at <var class="Fa">bufp</var>, + immediately before <var class="Fa">bpp</var>, and move bpp backwards to + point at the start of it. If the lookup succeeds, the vnode is referenced. + Returns 0 on success, -1 on cache miss, positive errno on failure.</dd> + <dt id="cache_enter"><a class="permalink" href="#cache_enter"><code class="Fn">cache_enter</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vp</var>, <var class="Fa">name</var>, + <var class="Fa">namelen</var>, <var class="Fa">nameiflags</var>)</dt> + <dd>Add an entry to the cache. The <var class="Fa">name</var> and + <var class="Fa">namelen</var> arguments specify the name to add to the + cache. The <var class="Fa">dvp</var> argument specifies the directory the + name appears in. The <var class="Fa">vp</var> argument specifies the + object to enter in the cache. The <var class="Fa">nameiflags</var> + argument should come from the <var class="Fa">cn_flags</var> member of + struct componentname. + <p class="Pp">If <var class="Fa">vp</var> is <code class="Dv">NULL</code>, a + negative cache entry is created, specifying that the entry does not + exist in the file system.</p> + </dd> + <dt id="cache_purge"><a class="permalink" href="#cache_purge"><code class="Fn">cache_purge</code></a>(<var class="Fa">vp</var>)</dt> + <dd>Flush the cache of a particular vnode <var class="Fa">vp</var>. + <code class="Fn">cache_purge</code>() is called when a vnode is renamed to + hide entries that would now be invalid.</dd> + <dt id="cache_purgevfs"><a class="permalink" href="#cache_purgevfs"><code class="Fn">cache_purgevfs</code></a>(<var class="Fa">mp</var>)</dt> + <dd>Flush cache of a whole file system <var class="Fa">mp</var>. + <code class="Fn">cache_purgevfs</code>() is called when file system is + unmounted to remove entries that would now be invalid.</dd> + <dt id="namecache_print"><a class="permalink" href="#namecache_print"><code class="Fn">namecache_print</code></a>(<var class="Fa">vp</var>, + <var class="Fa">func</var>)</dt> + <dd>Print all entries of the name cache. <var class="Fa">func</var> is the + <a class="Xr">printf(9)</a> format. + <code class="Fn">namecache_print</code>() is only defined if the kernel + option DDB is compiled into the kernel.</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 name lookup cache is implemented within the file + <span class="Pa">sys/kern/vfs_cache.c</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">intro(9)</a>, <a class="Xr">namei(9)</a>, + <a class="Xr">vfs(9)</a>, <a class="Xr">vnode(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The name lookup cache first appeared in + <span class="Ux">4.2BSD</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The original name lookup cache was written by + <span class="An">Robert Elz</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 7, 2014</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/nmi.9 b/static/netbsd/man9/nmi.9 new file mode 100644 index 00000000..708dba39 --- /dev/null +++ b/static/netbsd/man9/nmi.9 @@ -0,0 +1,135 @@ +.\" $NetBSD: nmi.9,v 1.5 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young. +.\" +.\" 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 March 17, 2011 +.Dt NMI 9 x86 +.Os +.Sh NAME +.Nm nmi , +.Nm nmi_establish , +.Nm nmi_disestablish , +.Nd NMI +.Sh SYNOPSIS +.In x86/nmi.h +.Ft nmi_handler_t * +.Fn nmi_establish "int (*func)(const struct trapframe *, void *)" "void *arg" +.Ft void +.Fn nmi_disestablish "nmi_handler_t *handle" +.Sh DESCRIPTION +The +.Nm +interface lets the kernel establish handlers for x86 Non-Maskable +Interrupts (NMIs). +An NMI signals to the processor an exception on a processor, memory +controller, or I/O bus that is irrecoverable or else needs attention +at a high priority. +A +.Dq "debug switch" +or a performance/watchdog timer may also trigger an NMI. +.Pp +An NMI handler will run to completion on the same processor where +it began without being preempted by any thread or interrupt except +for another NMI. +An NMI handler must prepare for re-entry. +An NMI handler may run simultaneously on more than one CPU. +.Pp +Synchronizing access to a shared data structure from +an NMI handler is a different challenge than synchronizing access +from hardware/software interrupt routines or from kernel threads. +An NMI handler may not perform any operation that may sleep, acquire +a mutex, or schedule a software interrupt. +An NMI handler may use +.Xr atomic_ops 3 . +An NMI handler may reference per-CPU storage +.Po +.Xr percpu 9 +.Pc . +.Pp +An NMI handler may not write to the kernel message buffer. +.Sh FUNCTIONS +.Bl -tag -width compact +.It Fn nmi_establish "func" "arg" +Call this in thread context to establish a handler for non-maskable +interrupts. +Establish +.Fa func +as one of the handler functions to call when an NMI occurs. +Where +.Fa tf +is a +.Vt struct trapframe +representation of the processor context where the NMI was received, +and +.Fa arg +is the argument to +.Fn nmi_establish , +the kernel will call +.Fo (*func) +.Fa tf +.Fa arg +.Fc +every time an NMI occurs until the handler is removed with +.Fn nmi_disestablish . +.Fa func +should return non-zero if it handled a condition that causes +NMI, or zero if it did not. +If, for a given NMI, all handlers return zero, the system will +panic or enter the kernel debugger, +.Xr ddb 4 . +.Fn nmi_establish +returns +.Dv NULL +on failure, and a handle for the NMI handler on success. +.It Fn nmi_disestablish "handle" +Call this in thread context to stop the kernel from calling an NMI +handler. +Indicate the handler to disestablish with the +.Fa handle +returned by +.Fn nmi_establish . +.El +.Sh CODE REFERENCES +The +.Nm +interface is implemented within the file +.Pa sys/arch/x86/x86/nmi.c . +.\" .Sh EXAMPLES +.Sh SEE ALSO +.Xr atomic_ops 3 , +.Xr ddb 4 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An YAMAMOTO Takashi Aq Mt yamt@NetBSD.org +.\" .Sh CAVEATS +.\" .Sh BUGS +.\" .Sh SECURITY CONSIDERATIONS diff --git a/static/netbsd/man9/nullop.9 3.html b/static/netbsd/man9/nullop.9 3.html new file mode 100644 index 00000000..26154789 --- /dev/null +++ b/static/netbsd/man9/nullop.9 3.html @@ -0,0 +1,80 @@ +<table class="head"> + <tr> + <td class="head-ltitle">NULLOP(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">NULLOP(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">nullop</code> — <span class="Nd">dummy + functions</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">nullop</code>(<var class="Fa" style="white-space: nowrap;">void + *v</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">voidop</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">enodev</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">enxio</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">enoioctl</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">enosys</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">eopnotsupp</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#nullop"><code class="Fn" id="nullop">nullop</code></a>() + function provides a generic “null operation”. It always + returns the value 0. The + <a class="permalink" href="#voidop"><code class="Fn" id="voidop">voidop</code></a>() + function takes no arguments and does nothing.</p> +<p class="Pp" id="enodev">The + <a class="permalink" href="#enodev"><code class="Fn">enodev</code></a>(), + <a class="permalink" href="#enxio"><code class="Fn" id="enxio">enxio</code></a>(), + <a class="permalink" href="#enoioctl"><code class="Fn" id="enoioctl">enoioctl</code></a>(), + <a class="permalink" href="#enosys"><code class="Fn" id="enosys">enosys</code></a>(), + and + <a class="permalink" href="#eopnotsupp"><code class="Fn" id="eopnotsupp">eopnotsupp</code></a>() + functions always fail, returning <code class="Er">ENODEV</code>, + <code class="Er">ENXIO</code>, <code class="Er">ENOTTY</code>, + <code class="Er">ENOSYS</code>, and <code class="Er">EOPNOTSUPP</code>, + respectively.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following example demonstrates a case where + <code class="Fn">nullop</code>() may be useful:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>uint64_t xc; + +... + +xc = xc_broadcast(0, (xcfunc_t)nullop, NULL, NULL); +xc_wait(xc);</pre> +</div> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 25, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/nv.9 b/static/netbsd/man9/nv.9 new file mode 100644 index 00000000..52695caa --- /dev/null +++ b/static/netbsd/man9/nv.9 @@ -0,0 +1,969 @@ +.\" $NetBSD: nv.9,v 1.2 2018/09/08 14:02:15 christos Exp $ +.\" +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" Copyright (c) 2013-2015 Mariusz Zaborski <oshogbo@FreeBSD.org> +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" the FreeBSD Foundation. +.\" +.\" 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: head/share/man/man9/nv.9 335348 2018-06-18 23:00:15Z oshogbo $ +.\" +.Dd June 19, 2018 +.Dt NV 9 +.Os +.Sh NAME +.Nm nvlist_create , +.Nm nvlist_destroy , +.Nm nvlist_error , +.Nm nvlist_set_error , +.Nm nvlist_empty , +.Nm nvlist_flags , +.Nm nvlist_exists , +.Nm nvlist_free , +.Nm nvlist_clone , +.Nm nvlist_dump , +.Nm nvlist_fdump , +.Nm nvlist_size , +.Nm nvlist_pack , +.Nm nvlist_unpack , +.Nm nvlist_send , +.Nm nvlist_recv , +.Nm nvlist_xfer , +.Nm nvlist_in_array , +.Nm nvlist_next , +.Nm nvlist_add , +.Nm nvlist_move , +.Nm nvlist_get , +.Nm nvlist_take , +.Nm nvlist_append +.Nd "library for name/value pairs" +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/nv.h +.Ft "nvlist_t *" +.Fn nvlist_create "int flags" +.Ft void +.Fn nvlist_destroy "nvlist_t *nvl" +.Ft int +.Fn nvlist_error "const nvlist_t *nvl" +.Ft void +.Fn nvlist_set_error "nvlist_t *nvl" "int error" +.Ft bool +.Fn nvlist_empty "const nvlist_t *nvl" +.Ft int +.Fn nvlist_flags "const nvlist_t *nvl" +.Ft bool +.Fn nvlist_in_array "const nvlist_t *nvl" +.\" +.Ft "nvlist_t *" +.Fn nvlist_clone "const nvlist_t *nvl" +.\" +.Ft void +.Fn nvlist_dump "const nvlist_t *nvl" "int fd" +.Ft void +.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp" +.\" +.Ft size_t +.Fn nvlist_size "const nvlist_t *nvl" +.Ft "void *" +.Fn nvlist_pack "const nvlist_t *nvl" "size_t *sizep" +.Ft "nvlist_t *" +.Fn nvlist_unpack "const void *buf" "size_t size" "int flags" +.\" +.Ft int +.Fn nvlist_send "int sock" "const nvlist_t *nvl" +.Ft "nvlist_t *" +.Fn nvlist_recv "int sock" "int flags" +.Ft "nvlist_t *" +.Fn nvlist_xfer "int sock" "nvlist_t *nvl" "int flags" +.\" +.Ft "const char *" +.Fn nvlist_next "const nvlist_t *nvl" "int *typep" "void **cookiep" +.\" +.Ft bool +.Fn nvlist_exists "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_type "const nvlist_t *nvl" "const char *name" "int type" +.Ft bool +.Fn nvlist_exists_null "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_bool "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_number "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name" +.\" +.Ft void +.Fn nvlist_add_null "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value" +.Ft void +.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value" +.Ft void +.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value" +.Ft void +.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..." +.Ft void +.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap" +.Ft void +.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value" +.Ft void +.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value" +.Ft void +.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size" +.Ft void +.Fn nvlist_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems" +.\" +.Ft void +.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value" +.Ft void +.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value" +.Ft void +.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value" +.Ft void +.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size" +.Ft void +.Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems" +.\" +.Ft bool +.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name" +.Ft uint64_t +.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" +.Ft "const char *" +.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" +.Ft "const nvlist_t *" +.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" +.Ft int +.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name" +.Ft "const void *" +.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" +.Ft "const bool *" +.Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const uint64_t *" +.Fn nvlist_get_number_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const char * const *" +.Fn nvlist_get_string_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const nvlist_t * const *" +.Fn nvlist_get_nvlist_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const int *" +.Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const nvlist_t *" +.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep" +.Ft "const nvlist_t *" +.Fn nvlist_get_array_next "const nvlist_t *nvl" +.Ft "const nvlist_t *" +.Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep" +.\" +.Ft bool +.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name" +.Ft uint64_t +.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" +.Ft "char *" +.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" +.Ft "nvlist_t *" +.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" +.Ft int +.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" +.Ft "void *" +.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep" +.Ft "bool *" +.Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "uint64_t **" +.Fn nvlist_take_number_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "char **" +.Fn nvlist_take_string_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "nvlist_t **" +.Fn nvlist_take_nvlist_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "int *" +.Fn nvlist_take_descriptor_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.\" +.Ft void +.Fn nvlist_append_bool_array "nvlist_t *nvl" "const char *name" "const bool value" +.Ft void +.Fn nvlist_append_number_array "nvlist_t *nvl" "const char *name" "const uint64_t value" +.Ft void +.Fn nvlist_append_string_array "nvlist_t *nvl" "const char *name" "const char * const value" +.Ft void +.Fn nvlist_append_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const value" +.Ft void +.Fn nvlist_append_descriptor_array "nvlist_t *nvl" "const char *name" "int value" +.\" +.Ft void +.Fn nvlist_free "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type" +.\" +.Ft void +.Fn nvlist_free_null "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_bool "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_number "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_string "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name" +.Sh DESCRIPTION +The +.Nm libnv +library allows to easily manage name value pairs as well as send and receive +them over sockets. +A group (list) of name value pairs is called an +.Nm nvlist . +The API supports the following data types: +.Bl -ohang -offset indent +.It Sy null ( NV_TYPE_NULL ) +There is no data associated with the name. +.It Sy bool ( NV_TYPE_BOOL ) +The value can be either +.Dv true +or +.Dv false . +.It Sy number ( NV_TYPE_NUMBER ) +The value is a number stored as +.Vt uint64_t . +.It Sy string ( NV_TYPE_STRING ) +The value is a C string. +.It Sy nvlist ( NV_TYPE_NVLIST ) +The value is a nested nvlist. +.It Sy descriptor ( NV_TYPE_DESCRIPTOR ) +The value is a file descriptor. +Note that file descriptors can be sent only over +.Xr unix 4 +domain sockets. +.It Sy binary ( NV_TYPE_BINARY ) +The value is a binary buffer. +.It Sy bool array ( NV_TYPE_BOOL_ARRAY ) +The value is an array of boolean values. +.It Sy number array ( NV_TYPE_NUMBER_ARRAY ) +The value is an array of numbers, each stored as +.Vt uint64_t . +.It Sy string array ( NV_TYPE_STRING_ARRAY ) +The value is an array of C strings. +.It Sy nvlist array ( NV_TYPE_NVLIST_ARRAY ) +The value is an array of nvlists. +When an nvlist is added to an array, it becomes part of the primary nvlist. +Traversing these arrays can be done using the +.Fn nvlist_get_array_next +and +.Fn nvlist_get_pararr +functions. +.It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY ) +The value is an array of files descriptors. +.El +.Pp +The +.Fn nvlist_create +function allocates memory and initializes an nvlist. +.Pp +The following flag can be provided: +.Pp +.Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent +.It Dv NV_FLAG_IGNORE_CASE +Perform case-insensitive lookups of provided names. +.It Dv NV_FLAG_NO_UNIQUE +Names in the nvlist do not have to be unique. +.El +.Pp +The +.Fn nvlist_destroy +function destroys the given nvlist. +Function does nothing if +.Dv NULL +nvlist is provided. +Function never modifies the +.Va errno +global variable. +.Pp +The +.Fn nvlist_error +function returns any error value that the nvlist accumulated. +If the given nvlist is +.Dv NULL +the +.Er ENOMEM +error will be returned. +.Pp +The +.Fn nvlist_set_error +function sets an nvlist to be in the error state. +Subsequent calls to +.Fn nvlist_error +will return the given error value. +This function cannot be used to clear the error state from an nvlist. +This function does nothing if the nvlist is already in the error state. +.Pp +The +.Fn nvlist_empty +function returns +.Dv true +if the given nvlist is empty and +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_flags +function returns flags used to create the nvlist with the +.Fn nvlist_create +function. +.Pp +The +.Fn nvlist_in_array +function returns +.Dv true +if +.Fa nvl +is part of an array that is a member of another nvlist. +.Pp +The +.Fn nvlist_clone +functions clones the given nvlist. +The clone shares no resources with its origin. +This also means that all file descriptors that are part of the nvlist will be +duplicated with the +.Xr dup 2 +system call before placing them in the clone. +.Pp +The +.Fn nvlist_dump +dumps nvlist content for debugging purposes to the given file descriptor +.Fa fd . +.Pp +The +.Fn nvlist_fdump +dumps nvlist content for debugging purposes to the given file stream +.Fa fp . +.Pp +The +.Fn nvlist_size +function returns the size of the given nvlist after converting it to binary +buffer with the +.Fn nvlist_pack +function. +.Pp +The +.Fn nvlist_pack +function converts the given nvlist to a binary buffer. +The function allocates memory for the buffer, which should be freed with the +.Xr free 3 +function. +If the +.Fa sizep +argument is not +.Dv NULL , +the size of the buffer will be stored there. +The function returns +.Dv NULL +in case of an error (allocation failure). +If the nvlist contains any file descriptors +.Dv NULL +will be returned. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_unpack +function converts the given buffer to the nvlist. +The +.Fa flags +argument defines what type of the top level nvlist is expected to be. +Flags are set up using the +.Fn nvlist_create +function. +If the nvlist flags do not match the flags passed to +.Fn nvlist_unpack , +the nvlist will not be returned. +Every nested nvlist list should be checked using +.Fn nvlist_flags +function. +The function returns +.Dv NULL +in case of an error. +.Pp +The +.Fn nvlist_send +function sends the given nvlist over the socket given by the +.Fa sock +argument. +Note that nvlist that contains file descriptors can only be send over +.Xr unix 4 +domain sockets. +.Pp +The +.Fn nvlist_recv +function receives nvlist over the socket given by the +.Fa sock +argument. +The +.Fa flags +argument defines what type of the top level nvlist is expected to be. +Flags are set up using the +.Fn nvlist_create +function. +If the nvlist flags do not match the flags passed to +.Fn nvlist_recv , +the nvlist will not be returned. +Every nested nvlist list should be checked using +.Fn nvlist_flags +function. +.Pp +The +.Fn nvlist_xfer +function sends the given nvlist over the socket given by the +.Fa sock +argument and receives nvlist over the same socket. +The +.Fa flags +argument defines what type of the top level nvlist is expected to be. +Flags are set up using the +.Fn nvlist_create +function. +If the nvlist flags do not match the flags passed to +.Fn nvlist_xfer , +the nvlist will not be returned. +Every nested nvlist list should be checked using +.Fn nvlist_flags +function. +The given nvlist is always destroyed. +.Pp +The +.Fn nvlist_next +function iterates over the given nvlist returning names and types of subsequent +elements. +The +.Fa cookiep +argument allows the function to figure out which element should be returned +next. +The +.Va *cookiep +should be set to +.Dv NULL +for the first call and should not be changed later. +Returning +.Dv NULL +means there are no more elements on the nvlist. +The +.Fa typep +argument can be NULL. +Elements may not be removed from the nvlist while traversing it. +The nvlist must not be in error state. +Note that +.Fn nvlist_next +will handle +.Va cookiep +being set to +.Dv NULL . +In this case first element is returned or +.Dv NULL +if nvlist is empty. +This behavior simplifies removing the first element from the list. +.Pp +The +.Fn nvlist_exists +function returns +.Dv true +if element of the given name exists (besides of its type) or +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_exists_type +function returns +.Dv true +if element of the given name and the given type exists or +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_exists_null , +.Fn nvlist_exists_bool , +.Fn nvlist_exists_number , +.Fn nvlist_exists_string , +.Fn nvlist_exists_nvlist , +.Fn nvlist_exists_descriptor , +.Fn nvlist_exists_binary , +.Fn nvlist_exists_bool_array , +.Fn nvlist_exists_number_array , +.Fn nvlist_exists_string_array , +.Fn nvlist_exists_nvlist_array , +.Fn nvlist_exists_descriptor_array +functions return +.Dv true +if element of the given name and the given type determined by the function name +exists or +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_add_null , +.Fn nvlist_add_bool , +.Fn nvlist_add_number , +.Fn nvlist_add_string , +.Fn nvlist_add_stringf , +.Fn nvlist_add_stringv , +.Fn nvlist_add_nvlist , +.Fn nvlist_add_descriptor , +.Fn nvlist_add_binary , +.Fn nvlist_add_bool_array , +.Fn nvlist_add_number_array , +.Fn nvlist_add_string_array , +.Fn nvlist_add_nvlist_array , +.Fn nvlist_add_descriptor_array +functions add element to the given nvlist. +When adding string or binary buffer the functions will allocate memory +and copy the data over. +When adding nvlist, the nvlist will be cloned and clone will be added. +When adding descriptor, the descriptor will be duplicated using the +.Xr dup 2 +system call and the new descriptor will be added. +The array functions will fail if there are any +.Dv NULL +elements in the array, or if the array pointer is +.Dv NULL . +If an error occurs while adding new element, internal error is set which can be +examined using the +.Fn nvlist_error +function. +.Pp +The +.Fn nvlist_move_string , +.Fn nvlist_move_nvlist , +.Fn nvlist_move_descriptor , +.Fn nvlist_move_binary , +.Fn nvlist_move_bool_array , +.Fn nvlist_move_number_array , +.Fn nvlist_move_string_array , +.Fn nvlist_move_nvlist_array , +.Fn nvlist_move_descriptor_array +functions add new element to the given nvlist, but unlike +.Fn nvlist_add_<type> +functions they will consume the given resource. +In the case of strings, descriptors, or nvlists every elements must be +unique, or it could cause a double free. +The array functions will fail if there are any +.Dv NULL +elements, or if the array pointer is +.Dv NULL . +If an error occurs while adding new element, the resource is destroyed and +internal error is set which can be examined using the +.Fn nvlist_error +function. +.Pp +The +.Fn nvlist_get_bool , +.Fn nvlist_get_number , +.Fn nvlist_get_string , +.Fn nvlist_get_nvlist , +.Fn nvlist_get_descriptor , +.Fn nvlist_get_binary , +.Fn nvlist_get_bool_array , +.Fn nvlist_get_number_array , +.Fn nvlist_get_string_array , +.Fn nvlist_get_nvlist_array , +.Fn nvlist_get_descriptor_array +functions return the value that corresponds to the given key name. +In the case of strings, nvlists, descriptors, binary, or arrays, the returned +resource should not be modified - they still belong to the nvlist. +If an element of the given name does not exist, the program will be aborted. +To avoid this, the caller should check for the existence of the name before +trying to obtain the value, or use the +.Xr dnvlist 3 +extension, which can provide a default value in the case of a missing element. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_get_parent +function returns the parent nvlist of the nested nvlist. +.Pp +The +.Fn nvlist_get_array_next +function returns the next element from the array or +.Dv NULL +if the nvlist is not in array or it is the last element. +Note that +.Fn nvlist_get_array_next +only works if you added the nvlist array using the +.Fn nvlist_move_nvlist_array +or +.Fn nvlist_add_nvlist_array +functions. +.Pp +The +.Fn nvlist_get_pararr +function returns the next element in the array, or if not available +the parent of the nested nvlist. +.Pp +The +.Fn nvlist_take_bool , +.Fn nvlist_take_number , +.Fn nvlist_take_string , +.Fn nvlist_take_nvlist , +.Fn nvlist_take_descriptor , +.Fn nvlist_take_binary , +.Fn nvlist_take_bool_array , +.Fn nvlist_take_number_array , +.Fn nvlist_take_string_array , +.Fn nvlist_take_nvlist_array , +.Fn nvlist_take_descriptor_array +functions return value associated with the given name and remove the element +from the nvlist. +In case of string and binary values, the caller is responsible for free returned +memory using the +.Xr free 3 +function. +In case of nvlist, the caller is responsible for destroying returned nvlist +using the +.Fn nvlist_destroy +function. +In case of descriptor, the caller is responsible for closing returned descriptor +using the +.Fn close 2 +system call. +If an element of the given name does not exist, the program will be aborted. +To avoid that the caller should check for the existence of the given name +before trying to obtain the value, or use the +.Xr dnvlist 3 +extension, which can provide a default value in the case of a missing element. +In the case of an array of strings or binary values, the caller is responsible +for freeing every element of the array using the +.Xr free 3 +function. +In the case of an array of nvlists, the caller is responsible for destroying +every element of array using the +.Fn nvlist_destroy +function. +In the case of descriptors, the caller is responsible for closing every +element of array using the +.Fn close 2 +system call. +In every case involving an array, the caller must also free the pointer to +the array using the +.Xr free 3 +function. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_append_bool_array , +.Fn nvlist_append_number_array , +.Fn nvlist_append_string_array , +.Fn nvlist_append_nvlist_array , +.Fn nvlist_append_descriptor_array +functions append an element to the existing array using the same semantics +as the add functions (i.e. the element will be copied when applicable). +If the array for a given key does not exist, then it will be created +as if using the +.Fn nvlist_add_<type>_array +function. +The internal error is set on append failure. +.Pp +The +.Fn nvlist_free +function removes element of the given name from the nvlist (besides of its type) +and frees all resources associated with it. +If element of the given name does not exist, the program will be aborted. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_free_type +function removes element of the given name and the given type from the nvlist +and frees all resources associated with it. +If element of the given name and the given type does not exist, the program +will be aborted. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_free_null , +.Fn nvlist_free_bool , +.Fn nvlist_free_number , +.Fn nvlist_free_string , +.Fn nvlist_free_nvlist , +.Fn nvlist_free_descriptor , +.Fn nvlist_free_binary , +.Fn nvlist_free_bool_array , +.Fn nvlist_free_number_array , +.Fn nvlist_free_string_array , +.Fn nvlist_free_nvlist_array , +.Fn nvlist_free_descriptor_array +functions remove element of the given name and the given type determined by the +function name from the nvlist and free all resources associated with it. +If element of the given name and the given type does not exist, the program +will be aborted. +The nvlist must not be in error state. +.Sh NOTES +The +.Fn nvlist_pack +and +.Fn nvlist_unpack +functions handle the byte-order conversions, so the binary buffer can be +packed/unpacked by the hosts with the different endianness. +.Sh EXAMPLES +The following example demonstrates how to prepare an nvlist and send it over +.Xr unix 4 +domain socket. +.Bd -literal +nvlist_t *nvl; +int fd; + +fd = open("/tmp/foo", O_RDONLY); +if (fd < 0) + err(1, "open(\\"/tmp/foo\\") failed"); + +nvl = nvlist_create(0); +/* + * There is no need to check if nvlist_create() succeeded, + * as the nvlist_add_<type>() functions can cope. + * If it failed, nvlist_send() will fail. + */ +nvlist_add_string(nvl, "filename", "/tmp/foo"); +nvlist_add_number(nvl, "flags", O_RDONLY); +/* + * We just want to send the descriptor, so we can give it + * for the nvlist to consume (that's why we use nvlist_move + * not nvlist_add). + */ +nvlist_move_descriptor(nvl, "fd", fd); +if (nvlist_send(sock, nvl) < 0) { + nvlist_destroy(nvl); + err(1, "nvlist_send() failed"); +} +nvlist_destroy(nvl); +.Ed +.Pp +Receiving nvlist and getting data: +.Bd -literal +nvlist_t *nvl; +const char *command; +char *filename; +int fd; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +/* For command we take pointer to nvlist's buffer. */ +command = nvlist_get_string(nvl, "command"); +/* + * For filename we remove it from the nvlist and take + * ownership of the buffer. + */ +filename = nvlist_take_string(nvl, "filename"); +/* The same for the descriptor. */ +fd = nvlist_take_descriptor(nvl, "fd"); + +printf("command=%s filename=%s fd=%d\n", command, filename, fd); + +nvlist_destroy(nvl); +free(filename); +close(fd); +/* command was freed by nvlist_destroy() */ +.Ed +.Pp +Iterating over nvlist: +.Bd -literal +nvlist_t *nvl; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +cookie = NULL; +while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + printf("%s=", name); + switch (type) { + case NV_TYPE_NUMBER: + printf("%ju", (uintmax_t)nvlist_get_number(nvl, name)); + break; + case NV_TYPE_STRING: + printf("%s", nvlist_get_string(nvl, name)); + break; + default: + printf("N/A"); + break; + } + printf("\\n"); +} +.Ed +.Pp +Iterating over every nested nvlist: +.Bd -literal +nvlist_t *nvl; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +cookie = NULL; +do { + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, name); + cookie = NULL; + } + } +} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL); +.Ed +.Pp +Iterating over every nested nvlist and every nvlist element: +.Bd -literal +nvlist_t *nvl; +const nvlist_t * const *array; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == null) + err(1, "nvlist_recv() failed"); + +cookie = null; +do { + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, name); + cookie = NULL; + } else if (type == NV_TYPE_NVLIST_ARRAY) { + nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0]; + cookie = NULL; + } + } +} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL); +.Ed +.Pp +Or alternatively: +.Bd -literal +nvlist_t *nvl, *tmp; +const nvlist_t * const *array; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == null) + err(1, "nvlist_recv() failed"); + +cooke = NULL; +tmp = nvl; +do { + do { + nvl = tmp; + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, + name); + cookie = NULL; + } else if (type == NV_TYPE_NVLIST_ARRAY) { + nvl = nvlist_get_nvlist_array(nvl, name, + NULL)[0]; + cookie = NULL; + } + } + cookie = NULL; + } while ((tmp = nvlist_get_array_next(nvl)) != NULL); +} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL); +.Ed +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr open 2 , +.Xr err 3 , +.Xr free 3 , +.Xr printf 3 , +.Xr unix 4 +.Sh HISTORY +The +.Nm libnv +library appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm libnv +library was implemented by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. diff --git a/static/netbsd/man9/optstr.9 3.html b/static/netbsd/man9/optstr.9 3.html new file mode 100644 index 00000000..c46e0389 --- /dev/null +++ b/static/netbsd/man9/optstr.9 3.html @@ -0,0 +1,128 @@ +<table class="head"> + <tr> + <td class="head-ltitle">OPTSTR(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">OPTSTR(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">optstr_get</code>, + <code class="Nm">optstr_get_string</code>, + <code class="Nm">optstr_get_number</code>, + <code class="Nm">optstr_get_number_binary</code>, + <code class="Nm">optstr_get_number_hex</code>, + <code class="Nm">optstr_get_macaddr</code> — <span class="Nd">Options + string management</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/optstr.h</a>></code></p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">optstr_get</code>(<var class="Fa">const char *optstr</var>, + <var class="Fa">const char *key</var>, <var class="Fa">char *buf</var>, + <var class="Fa">size_t bufsize</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">optstr_get_string</code>(<var class="Fa">const char + *optstr</var>, <var class="Fa">const char *key</var>, <var class="Fa">char + **result</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">optstr_get_number</code>(<var class="Fa">const char + *optstr</var>, <var class="Fa">const char *key</var>, + <var class="Fa">unsigned long *result</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">optstr_get_number_binary</code>(<var class="Fa">const char + *optstr</var>, <var class="Fa">const char *key</var>, + <var class="Fa">unsigned long *result</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">optstr_get_number_hex</code>(<var class="Fa">const char + *optstr</var>, <var class="Fa">const char *key</var>, + <var class="Fa">unsigned long *result</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">optstr_get_macaddr</code>(<var class="Fa">const char + *optstr</var>, <var class="Fa">const char *key</var>, + <var class="Fa">uint8_t result[ETHER_ADDR_LEN]</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">An options string is a list of key/value pairs represented in + textual form. Each pair is expressed as + <var class="Ar">key</var><code class="Li">=</code><var class="Ar">value</var> + and is separated from other pairs by one or more spaces. For example:</p> +<p class="Pp"></p> +<div class="Bd Bd-indent"><code class="Li">key1=value1 key2=value2 + key3=value3</code></div> +<p class="Pp">Options strings are used to pass information between userland + programs and the kernel in a binary-agnostic way. This makes them endianness + and ABI independent.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<p class="Pp">The following functions are provided to manage options + strings:</p> +<dl class="Bl-tag"> + <dt id="optstr_get"><a class="permalink" href="#optstr_get"><code class="Fn">optstr_get</code></a>(<var class="Fa">optstr</var>, + <var class="Fa">key</var>, <var class="Fa">buf</var>, + <var class="Fa">bufsize</var>)</dt> + <dd>Scans the <var class="Fa">optstr</var> options string looking for the key + <var class="Fa">key</var> and stores its value in the buffer pointed to by + <var class="Fa">buf</var> copying a maximum of + <var class="Fa">bufsize</var> bytes. Returns + ‘<code class="Li">true</code>’ if the key was found or + ‘<code class="Li">false</code>’ otherwise, in which case + <var class="Fa">buf</var> is left unmodified.</dd> +</dl> +<p class="Pp">The <code class="Li">optstr_get_</code><var class="Ar">item</var> + family of functions provide the ability to scan for the key, and return the + value converted to an appropriate type.</p> +<p class="Pp"></p> +<dl class="Bl-tag Bl-compact"> + <dt id="optstr_get_string"><a class="permalink" href="#optstr_get_string"><code class="Fn">optstr_get_string</code></a>(<var class="Fa">optstr</var>, + <var class="Fa">key</var>, <var class="Fa">result</var>)</dt> + <dd style="width: auto;"> </dd> + <dt id="optstr_get_number"><a class="permalink" href="#optstr_get_number"><code class="Fn">optstr_get_number</code></a>(<var class="Fa">optstr</var>, + <var class="Fa">key</var>, <var class="Fa">result</var>)</dt> + <dd style="width: auto;"> </dd> + <dt id="optstr_get_number_binary"><a class="permalink" href="#optstr_get_number_binary"><code class="Fn">optstr_get_number_binary</code></a>(<var class="Fa">optstr</var>, + <var class="Fa">key</var>, <var class="Fa">result</var>)</dt> + <dd style="width: auto;"> </dd> + <dt id="optstr_get_number_hex"><a class="permalink" href="#optstr_get_number_hex"><code class="Fn">optstr_get_number_hex</code></a>(<var class="Fa">optstr</var>, + <var class="Fa">key</var>, <var class="Fa">result</var>)</dt> + <dd style="width: auto;"> </dd> + <dt id="optstr_get_macaddr"><a class="permalink" href="#optstr_get_macaddr"><code class="Fn">optstr_get_macaddr</code></a>(<var class="Fa">optstr</var>, + <var class="Fa">key</var>, <var class="Fa">result</var>)</dt> + <dd>These functions scan the <var class="Fa">optstr</var> options string + looking for the key <var class="Fa">key</var> and returns the key value + converted as per the function name in <var class="Fa">result</var>. All + functions return ‘<code class="Li">true</code>’ if the key + was found or ‘<code class="Li">false</code>’ otherwise, in + which case <var class="Fa">result</var> is left unmodified.</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 options string management functions are implemented within the + files <span class="Pa">sys/kern/subr_optstr.c</span> and + <span class="Pa">sys/sys/optstr.h</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">Options strings appeared in <span class="Ux">NetBSD + 4.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 20, 2023</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/p.9 b/static/netbsd/man9/p.9 new file mode 100644 index 00000000..3cf20b67 --- /dev/null +++ b/static/netbsd/man9/p.9 @@ -0,0 +1 @@ +$1 >= "S" diff --git a/static/netbsd/man9/panic.9 3.html b/static/netbsd/man9/panic.9 3.html new file mode 100644 index 00000000..27a73f6c --- /dev/null +++ b/static/netbsd/man9/panic.9 3.html @@ -0,0 +1,91 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PANIC(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PANIC(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">panic</code> — <span class="Nd">bring down + system on fatal error</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/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">vpanic</code>(<var class="Fa" style="white-space: nowrap;">const + char *fmt</var>, <var class="Fa" style="white-space: nowrap;">va_list + ap</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">panic</code>(<var class="Fa" style="white-space: nowrap;">const + char *fmt</var>, + <var class="Fa" style="white-space: nowrap;">...</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#panic"><code class="Fn" id="panic">panic</code></a>() + and + <a class="permalink" href="#vpanic"><code class="Fn" id="vpanic">vpanic</code></a>() + functions terminate the <span class="Ux">NetBSD</span> system. The message + <var class="Fa">fmt</var> is a <a class="Xr">printf(3)</a> style format + string which is printed to the console and saved in the variable + <var class="Va">panicstr</var> for later retrieval via core dump inspection. + A newline character is added at the end automatically, and is thus not + needed in the format string.</p> +<p class="Pp" id="panic~2">If a kernel debugger is installed, control is passed + to it after the message is printed. If the kernel debugger is + <a class="Xr">ddb(4)</a>, control may be passed to it, depending on the + value of <i class="Em">ddb.onpanic</i>. See <a class="Xr">options(4)</a> for + more details on setting <i class="Em">ddb.onpanic</i>. If control is not + passed through to <a class="Xr">ddb(4)</a>, a + <a class="Xr">ddb(4)</a>-specific function is used to print the kernel stack + trace, and then control returns to + <a class="permalink" href="#panic~2"><code class="Fn">panic</code></a>().</p> +<p class="Pp" id="panic~3">If control remains in + <a class="permalink" href="#panic~3"><code class="Fn">panic</code></a>(), an + attempt is made to save an image of system memory on the configured dump + device.</p> +<p class="Pp" id="panic~4">If during the process of handling the panic, + <a class="permalink" href="#panic~4"><code class="Fn">panic</code></a>() is + called again (from the filesystem synchronization routines, for example), + the system is rebooted immediately without synchronizing any + filesystems.</p> +<p class="Pp" id="panic~5"><a class="permalink" href="#panic~5"><code class="Fn">panic</code></a>() + is meant to be used in situations where something unexpected has happened + and it is difficult to recover the system to a stable state, or in + situations where proceeding might make things worse, leading to data + corruption and/or loss. It is not meant to be used in scenarios where the + system could easily ignore and/or isolate the condition/subsystem and + proceed.</p> +<p class="Pp" id="panic~6">In general developers should try to reduce the number + of <a class="permalink" href="#panic~6"><code class="Fn">panic</code></a>() + calls in the kernel to improve stability.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The <code class="Fn">panic</code>() function never returns.</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">printf(3)</a>, <a class="Xr">sysctl(3)</a>, + <a class="Xr">ddb(4)</a>, <a class="Xr">options(4)</a>, + <a class="Xr">savecore(8)</a>, <a class="Xr">swapctl(8)</a>, + <a class="Xr">sysctl(8)</a>, <a class="Xr">printf(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 4, 2019</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pci_configure_bus.9 3.html b/static/netbsd/man9/pci_configure_bus.9 3.html new file mode 100644 index 00000000..de32dcfc --- /dev/null +++ b/static/netbsd/man9/pci_configure_bus.9 3.html @@ -0,0 +1,256 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PCI_CONFIGURE_BUS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PCI_CONFIGURE_BUS(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">pci_configure_bus</code>, + <code class="Nm">pci_conf_hook</code>, + <code class="Nm">pci_conf_interrupt</code>, + <code class="Nm">pciconf_resource_init</code>, + <code class="Nm">pciconf_resource_add</code>, + <code class="Nm">pciconf_resource_fini</code> — + <span class="Nd">perform PCI bus configuration</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">dev/pci/pciconf.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_configure_bus</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">struct + pciconf_resources *res</var>, + <var class="Fa" style="white-space: nowrap;">int firstbus</var>, + <var class="Fa" style="white-space: nowrap;">int cacheline_size</var>);</p> +<p class="Pp"><var class="Ft">struct pciconf_resources *</var> + <br/> + <code class="Fn">pciconf_resource_init</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pciconf_resource_add</code>(<var class="Fa" style="white-space: nowrap;">struct + pciconf_resources *res</var>, + <var class="Fa" style="white-space: nowrap;">int type</var>, + <var class="Fa" style="white-space: nowrap;">bus_addr_t addr</var>, + <var class="Fa" style="white-space: nowrap;">bus_size_t size</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pciconf_resource_fini</code>(<var class="Fa" style="white-space: nowrap;">struct + pciconf_resources *res</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#pci_configure_bus"><code class="Fn" id="pci_configure_bus">pci_configure_bus</code></a>() + function configures a PCI bus for use. This involves:</p> +<ul class="Bl-bullet"> + <li>Defining bus numbers for all busses on the system,</li> + <li>Setting the Base Address Registers for all devices,</li> + <li>Setting up the interrupt line register for all devices,</li> + <li>Configuring bus latency timers for all devices, and</li> + <li>Configuring cacheline sizes for all devices.</li> +</ul> +<p class="Pp" id="pci_configure_bus~2">In traditional PCs and Alpha systems, the + BIOS or firmware takes care of this task, but that is not the case for all + systems. + <a class="permalink" href="#pci_configure_bus~2"><code class="Fn">pci_configure_bus</code></a>() + should be called prior to the autoconfiguration of the bus.</p> +<p class="Pp" id="pci_make_tag">The <var class="Fa">pc</var> argument is a + machine-dependent tag used to specify the PCI chipset to the system. This + should be the same value used with + <a class="permalink" href="#pci_make_tag"><code class="Fn">pci_make_tag</code></a>(). + The <var class="Fa">res</var> argument is a container for PCI bus resources + that will be used to configure the bus. The <var class="Fa">firstbus</var> + argument indicates the number of the first bus to be configured. The + <var class="Fa">cacheline_size</var> argument is used to configure the PCI + Cache Line Size Register; it should be the size, in bytes, of the largest + D-cache line on the system.</p> +<p class="Pp" id="pci_configure_bus~3">An implementation may choose to not have + full configuration performed by + <a class="permalink" href="#pci_configure_bus~3"><code class="Fn">pci_configure_bus</code></a>() + on certain PCI devices, such as PCI host bridges or PCI bus analyzers which + are instantiated as devices on the bus. In order for this to take place, the + header + <code class="In"><<a class="In">machine/pci_machdep.h</a>></code> must + define the <code class="Dv">__HAVE_PCI_CONF_HOOK</code> symbol (without a + value), and a machine-dependent function + <code class="Fn">pci_conf_hook</code>() (declared in the same header) must + be defined. The prototype for this function is:</p> +<p class="Pp" id="pci_conf_hook"><var class="Ft">int</var> + <a class="permalink" href="#pci_conf_hook"><code class="Fn">pci_conf_hook</code></a>(<var class="Fa">pci_chipset_tag_t + pc</var>, <var class="Fa">int bus</var>, <var class="Fa">int device</var>, + <var class="Fa">int function</var>, <var class="Fa">pcireg_t id</var>);</p> +<p class="Pp" id="pci_conf_hook~2">In this function, <var class="Fa">bus</var>, + <var class="Fa">device</var>, and <var class="Fa">function</var> uniquely + identify the item being configured; in addition to this, the value of the + device's PCI identification register is passed in <var class="Fa">id</var>. + For each device + <a class="permalink" href="#pci_conf_hook~2"><code class="Fn">pci_conf_hook</code></a>() + can then decide upon the amount of configuration to be performed by + returning a bitwise inclusive-or of the following flags:</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt id="PCI_CONF_MAP_IO"><a class="permalink" href="#PCI_CONF_MAP_IO"><code class="Dv">PCI_CONF_MAP_IO</code></a></dt> + <dd>Configure Base Address Registers that map I/O space</dd> + <dt id="PCI_CONF_MAP_MEM"><a class="permalink" href="#PCI_CONF_MAP_MEM"><code class="Dv">PCI_CONF_MAP_MEM</code></a></dt> + <dd>Configure Base Address Registers that map memory space</dd> + <dt id="PCI_CONF_MAP_ROM"><a class="permalink" href="#PCI_CONF_MAP_ROM"><code class="Dv">PCI_CONF_MAP_ROM</code></a></dt> + <dd>Configure Expansion ROM Base Address register</dd> + <dt id="PCI_CONF_ENABLE_IO"><a class="permalink" href="#PCI_CONF_ENABLE_IO"><code class="Dv">PCI_CONF_ENABLE_IO</code></a></dt> + <dd>Enable I/O space accesses</dd> + <dt id="PCI_CONF_ENABLE_MEM"><a class="permalink" href="#PCI_CONF_ENABLE_MEM"><code class="Dv">PCI_CONF_ENABLE_MEM</code></a></dt> + <dd>Enable memory space accesses</dd> + <dt id="PCI_CONF_ENABLE_BM"><a class="permalink" href="#PCI_CONF_ENABLE_BM"><code class="Dv">PCI_CONF_ENABLE_BM</code></a></dt> + <dd>Enable bus mastering</dd> +</dl> +</div> +<p class="Pp">In addition, <code class="Dv">PCI_CONF_ALL</code> specifies all of + the above.</p> +<p class="Pp" id="pci_configure_bus~4">One of the functions of + <a class="permalink" href="#pci_configure_bus~4"><code class="Fn">pci_configure_bus</code></a>() + is to configure interrupt “line” information. This must be + done on a machine-dependent basis, so a machine-dependent function + <code class="Fn">pci_conf_interrupt</code>() must be defined. The prototype + for this function is</p> +<p class="Pp" id="pci_conf_interrupt"><var class="Ft">void</var> + <a class="permalink" href="#pci_conf_interrupt"><code class="Fn">pci_conf_interrupt</code></a>(<var class="Fa">pci_chipset_tag_t + pc</var>, <var class="Fa">int bus</var>, <var class="Fa">int device</var>, + <var class="Fa">int pin</var>, <var class="Fa">int swiz</var>, + <var class="Fa">int *iline</var>)</p> +<p class="Pp">In this function, <var class="Fa">bus</var>, + <var class="Fa">device</var>, and <var class="Fa">pin</var>, uniquely + identify the item being configured. The <var class="Fa">swiz</var> argument + is a “swizzle”, a sum of the device numbers of the primary + interface of the bridges between the host bridge and the current device. The + function is responsible for setting the value of + <var class="Fa">iline</var>. See chapter 9 of the “PCI-to-PCI Bridge + Architecture Specification” for more information on swizzling (also + known as interrupt routing).</p> +<p class="Pp" id="pciconf_resource_init">The resources used to configure the PCI + bus are encapsulated into a resource container. The + <a class="permalink" href="#pciconf_resource_init"><code class="Fn">pciconf_resource_init</code></a>() + function allocates and initializes one of these containers, and the + <a class="permalink" href="#pciconf_resource_add"><code class="Fn" id="pciconf_resource_add">pciconf_resource_add</code></a>() + function adds resources to the container, specifying the type, start + address, and size of the resource being added. The following resource types + are supported:</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt id="PCICONF_RESOURCE_IO"><a class="permalink" href="#PCICONF_RESOURCE_IO"><code class="Dv">PCICONF_RESOURCE_IO</code></a></dt> + <dd>An address region used for PCI I/O accesses.</dd> + <dt id="PCICONF_RESOURCE_MEM"><a class="permalink" href="#PCICONF_RESOURCE_MEM"><code class="Dv">PCICONF_RESOURCE_MEM</code></a></dt> + <dd>An address region used for PCI memory accesses where reads may have side + effects.</dd> + <dt id="PCICONF_RESOURCE_PREFETCHABLE_MEM"><a class="permalink" href="#PCICONF_RESOURCE_PREFETCHABLE_MEM"><code class="Dv">PCICONF_RESOURCE_PREFETCHABLE_MEM</code></a></dt> + <dd>An address region used for PCI memory accesses where reads do not have + side effects (e.g. ROMs, frame buffers, other memory-like regions that are + marked as prefetchable in their BAR).</dd> +</dl> +</div> +<p class="Pp">If an implementation does not distinguish between prefetchable and + non-prefetchable memory, then adding a + <code class="Dv">PCICONF_RESOURCE_PREFETCHABLE_MEM</code> resource is not + required; <code class="Dv">PCICONF_RESOURCE_MEM</code> resources will be + used for ROMs and BARs that are marked as prefetchable.</p> +<p class="Pp" id="pciconf_resource_fini">Once the bus has been successfully + configured, the resource container should be disposed of by calling + <a class="permalink" href="#pciconf_resource_fini"><code class="Fn">pciconf_resource_fini</code></a>().</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">If successful <code class="Fn">pci_configure_bus</code>() returns + 0. A non-zero return value means that the bus was not completely configured + for some reason. A description of the failure will be displayed on the + console.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ENVIRONMENT"><a class="permalink" href="#ENVIRONMENT">ENVIRONMENT</a></h1> +<p class="Pp">The <code class="Fn">pci_configure_bus</code>() function is only + included in the kernel if the kernel is compiled with the + <code class="Dv">PCI_NETBSD_CONFIGURE</code> option enabled.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The <code class="Fn">pci_conf_hook</code>() function in evbppc's + walnut implementation looks like:</p> +<p class="Pp"></p> +<div class="Bd Li"> +<pre>int +pci_conf_hook(pci_chipset_tag_t pc, int bus, int dev, int func, + pcireg_t id) +{ + + if ((PCI_VENDOR(id) == PCI_VENDOR_IBM && + PCI_PRODUCT(id) == PCI_PRODUCT_IBM_405GP) || + (PCI_VENDOR(id) == PCI_VENDOR_INTEL && + PCI_PRODUCT(id) == PCI_PRODUCT_INTEL_80960_RP)) { + /* Don't configure the bridge and PCI probe. */ + return 0; + } + return (PCI_CONF_ALL & ~PCI_CONF_MAP_ROM); +}</pre> +</div> +<p class="Pp">The <code class="Fn">pci_conf_interrupt</code>() function in the + sandpoint implementation looks like:</p> +<p class="Pp"></p> +<div class="Bd Li"> +<pre>void +pci_conf_interrupt(pci_chipset_tag_t pc, int bus, int dev, int pin, + int swiz, int *iline) +{ + if (bus == 0) { + *iline = dev; + } else { + *iline = 13 + ((swiz + dev + 3) & 3); + } +}</pre> +</div> +<p class="Pp">This configuration example is taken from the bebox port.</p> +<p class="Pp"></p> +<div class="Bd Li"> +<pre>#define PCI_IO_START 0x00008000 +#define PCI_IO_END 0x0000ffff +#define PCI_IO_SIZE ((PCI_IO_END - PCI_IO_START) + 1) + +#define PCI_MEM_START 0x00000000 +#define PCI_MEM_END 0x0fffffff +#define PCI_MEM_SIZE ((PCI_MEM_END - PCI_MEM_START) + 1) + ... + struct pciconf_resources *pcires; + ... + pcires = pciconf_resource_init(); + pciconf_resource_add(pcires, PCICONF_RESOURCE_IO, + PCI_IO_START, PCI_IO_SIZE); + pciconf_resource_add(pcires, PCICONF_RESOURCE_MEM, + PCI_MEM_START, PCI_MEM_SIZE); + ... + pci_configure_bus(pc, pcires, 0, CACHELINESIZE); + ... + pciconf_resource_fini(pcires); + ...</pre> +</div> +<p class="Pp">Note that this must be called before the PCI bus is attached + during autoconfiguration.</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">pci(4)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp"><code class="Fn">pci_configure_bus</code>() was added in + <span class="Ux">NetBSD 1.6</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 7, 2020</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pci_intr.9 3.html b/static/netbsd/man9/pci_intr.9 3.html new file mode 100644 index 00000000..b80bb699 --- /dev/null +++ b/static/netbsd/man9/pci_intr.9 3.html @@ -0,0 +1,184 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PCI_INTR(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PCI_INTR(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">pci_intr</code>, + <code class="Nm">pci_intr_map</code>, + <code class="Nm">pci_intr_string</code>, + <code class="Nm">pci_intr_evcnt</code>, + <code class="Nm">pci_intr_establish</code>, + <code class="Nm">pci_intr_establish_xname</code>, + <code class="Nm">pci_intr_disestablish</code>, + <code class="Nm">pci_intr_setattr</code> — <span class="Nd">PCI bus + interrupt manipulation functions</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">dev/pci/pcivar.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_intr_map</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + *ih</var>);</p> +<p class="Pp"><var class="Ft">const char *</var> + <br/> + <code class="Fn">pci_intr_string</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + ih</var>, <var class="Fa" style="white-space: nowrap;">char *buf</var>, + <var class="Fa" style="white-space: nowrap;">size_t len</var>);</p> +<p class="Pp"><var class="Ft">const struct evcnt *</var> + <br/> + <code class="Fn">pci_intr_evcnt</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + ih</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">pci_intr_establish</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + ih</var>, <var class="Fa" style="white-space: nowrap;">int ipl</var>, + <var class="Fa" style="white-space: nowrap;">int (*intrhand)(void *)</var>, + <var class="Fa" style="white-space: nowrap;">void *intrarg</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">pci_intr_establish_xname</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + ih</var>, <var class="Fa" style="white-space: nowrap;">int ipl</var>, + <var class="Fa" style="white-space: nowrap;">int (*intrhand)(void *)</var>, + <var class="Fa" style="white-space: nowrap;">void *intrarg</var>, + <var class="Fa" style="white-space: nowrap;">const char *xname</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pci_intr_disestablish</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">void *ih</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_intr_setattr</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + *ih</var>, <var class="Fa" style="white-space: nowrap;">int attr</var>, + <var class="Fa" style="white-space: nowrap;">uint64_t data</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">pci_intr</code> functions exist to allow + device drivers machine-independent access to PCI bus interrupts. The + functions described in this page are typically declared in a port's + <code class="In"><<a class="In">machine/pci_machdep.h</a>></code> + header file; however, drivers should generally include + <code class="In"><<a class="In">dev/pci/pcivar.h</a>></code> to get + other PCI-specific declarations as well.</p> +<p class="Pp" id="attach">Each driver has an + <a class="permalink" href="#attach"><code class="Fn">attach</code></a>() + function which has a bus-specific <var class="Ft">attach_args</var> + structure. Each driver for a PCI device is passed a pointer to an object of + type <var class="Ft">struct pci_attach_args</var> which contains, among + other things, information about the location of the device in the PCI bus + topology sufficient to allow interrupts from the device to be handled.</p> +<p class="Pp" id="pci_intr_map">If a driver wishes to establish an interrupt + handler for the device, it should pass the <var class="Ft">struct + pci_attach_args *</var> to the + <a class="permalink" href="#pci_intr_map"><code class="Fn">pci_intr_map</code></a>() + function, which returns zero on success, and nonzero on failure. The + function sets the <var class="Ft">pci_intr_handle_t</var> pointed at by its + second argument to a machine-dependent value which identifies a particular + interrupt source.</p> +<p class="Pp" id="pci_intr_string">If the driver wishes to refer to the + interrupt source in an attach or error message, it should use the value + returned by + <a class="permalink" href="#pci_intr_string"><code class="Fn">pci_intr_string</code></a>(). + The buffer passed to <code class="Fn">pci_intr_string</code>() should be at + least <code class="Dv">PCI_INTRSTR_LEN</code> bytes.</p> +<p class="Pp" id="pci_intr_establish">Subsequently, when the driver is prepared + to receive interrupts, it should call + <a class="permalink" href="#pci_intr_establish"><code class="Fn">pci_intr_establish</code></a>() + to actually establish the handler; when the device interrupts, + <var class="Fa">intrhand</var> will be called with a single argument + <var class="Fa">intrarg</var>, and will run at the interrupt priority level + <var class="Fa">ipl</var>.</p> +<p class="Pp" id="pci_intr_establish~2">The return value of + <a class="permalink" href="#pci_intr_establish~2"><code class="Fn">pci_intr_establish</code></a>() + may be saved and passed to + <a class="permalink" href="#pci_intr_disestablish"><code class="Fn" id="pci_intr_disestablish">pci_intr_disestablish</code></a>() + to disable the interrupt handler when the driver is no longer interested in + interrupts from the device.</p> +<p class="Pp" id="pci_intr_establish_xname"><a class="permalink" href="#pci_intr_establish_xname"><code class="Fn">pci_intr_establish_xname</code></a>() + is almost the same as <code class="Fn">pci_intr_establish</code>(). The + difference is only <var class="Fa">xname</var> which is used by + <a class="Xr">intrctl(8)</a> to show the device name(s) of the interrupt + id.</p> +<p class="Pp" id="pci_intr_setattr">The + <a class="permalink" href="#pci_intr_setattr"><code class="Fn">pci_intr_setattr</code></a>() + function sets an attribute <var class="Fa">attr</var> of the interrupt + handler to <var class="Fa">data</var>. Currently, only the following + attribute is supported:</p> +<dl class="Bl-tag"> + <dt id="PCI_INTR_MPSAFE"><a class="permalink" href="#PCI_INTR_MPSAFE"><code class="Dv">PCI_INTR_MPSAFE</code></a></dt> + <dd>If this attribute is set to <code class="Dv">true</code>, it specifies + that the interrupt handler is multiprocessor safe and works its own + locking; otherwise the kernel lock will be held for the call to the + interrupt handler. The default is <code class="Dv">false</code>.</dd> +</dl> +<p class="Pp" id="pci_intr_setattr~2">The + <a class="permalink" href="#pci_intr_setattr~2"><code class="Fn">pci_intr_setattr</code></a>() + function returns zero on success, and nonzero on failure.</p> +<p class="Pp" id="pci_intr_evcnt">The + <a class="permalink" href="#pci_intr_evcnt"><code class="Fn">pci_intr_evcnt</code></a>() + function should return an evcnt structure pointer or + <code class="Dv">NULL</code> if there is no evcnt associated with this + interrupt. See <a class="Xr">evcnt(9)</a> for more details.</p> +<section class="Ss"> +<h2 class="Ss" id="PORTING"><a class="permalink" href="#PORTING">PORTING</a></h2> +<p class="Pp">A port's implementation of <code class="Fn">pci_intr_map</code>() + may use the following members of <var class="Ft">struct + pci_attach_args</var> to determine how the device's interrupts are + routed.</p> +<div class="Bd Pp Li"> +<pre> pci_chipset_tag_t pa_pc; + pcitag_t pa_tag; + pcitag_t pa_intrtag; /* intr. appears to come from here */ + pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */ + pci_intr_line_t pa_intrline; /* intr. routing information */ + pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */</pre> +</div> +<p class="Pp">PCI-PCI bridges swizzle (permute) interrupt wiring. Depending on + implementation details, it may be more convenient to use either original or + the swizzled interrupt parameters. The original device tag and interrupt pin + can be found in <var class="Ft">pa_tag</var> and + <var class="Ft">pa_rawintrpin</var> respectively, while the swizzled tag and + pin can be found in <var class="Ft">pa_intrtag</var> and + <var class="Ft">pa_intrpin</var>.</p> +<p class="Pp">When a device is attached to a primary bus, both pairs of fields + contain the same values. When a device is found behind one or more pci-pci + bridges, <var class="Ft">pa_intrpin</var> contains the + “swizzled” interrupt pin number, while + <var class="Ft">pa_rawintrpin</var> contains the original interrupt pin; + <var class="Ft">pa_tag</var> contains the PCI tag of the device itself, and + <var class="Ft">pa_intrtag</var> contains the PCI tag of the uppermost + bridge device.</p> +</section> +</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">evcnt(9)</a>, <a class="Xr">pci(9)</a>, + <a class="Xr">pci_msi(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp"><code class="Fn">pci_intr_establish_xname</code>() was added in + <span class="Ux">NetBSD 8.0</span> as part of MSI/MSI-X support.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 20, 2018</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pci_msi.9 3.html b/static/netbsd/man9/pci_msi.9 3.html new file mode 100644 index 00000000..1c2d0d0e --- /dev/null +++ b/static/netbsd/man9/pci_msi.9 3.html @@ -0,0 +1,296 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PCI_MSI(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PCI_MSI(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">pci_msi</code>, <code class="Nm">pci_msix</code>, + <code class="Nm">pci_msi_count</code>, + <code class="Nm">pci_msi_alloc</code>, + <code class="Nm">pci_msi_alloc_exact</code>, + <code class="Nm">pci_msix_count</code>, + <code class="Nm">pci_msix_alloc</code>, + <code class="Nm">pci_msix_alloc_exact</code>, + <code class="Nm">pci_msix_alloc_map</code>, + <code class="Nm">pci_intx_alloc</code>, + <code class="Nm">pci_intr_alloc</code>, + <code class="Nm">pci_intr_release</code>, + <code class="Nm">pci_intr_type</code> — <span class="Nd">PCI MSI{,-X} + manipulation functions</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_msi_count</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pcitag_t + tag</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_msi_alloc</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, + <var class="Fa" style="white-space: nowrap;">int *count</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_msi_alloc_exact</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, + <var class="Fa" style="white-space: nowrap;">int count</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_msix_count</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pcitag_t + tag</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_msix_alloc</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, + <var class="Fa" style="white-space: nowrap;">int *count</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_msix_alloc_exact</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, + <var class="Fa" style="white-space: nowrap;">int count</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_msix_alloc_map</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihps</var>, + <var class="Fa" style="white-space: nowrap;">u_int *table_indexes</var>, + <var class="Fa" style="white-space: nowrap;">int count</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_intx_alloc</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + **ihp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pci_intr_alloc</code>(<var class="Fa" style="white-space: nowrap;">const + struct pci_attach_args *pa</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t **ihp</var>, + <var class="Fa" style="white-space: nowrap;">int *counts</var>, + <var class="Fa" style="white-space: nowrap;">pci_intr_type_t + max_type</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pci_intr_release</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + *pih</var>, <var class="Fa" style="white-space: nowrap;">int + count</var>);</p> +<p class="Pp"><var class="Ft">pci_intr_type_t</var> + <br/> + <code class="Fn">pci_intr_type</code>(<var class="Fa" style="white-space: nowrap;">pci_chipset_tag_t + pc</var>, <var class="Fa" style="white-space: nowrap;">pci_intr_handle_t + ih</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">pci_msi</code> functions exist to allow + device drivers to use MSI/MSI-X. When the system uses MSI/MSI-X, it must + define the <code class="Dv">__HAVE_PCI_MSI_MSIX</code> build option.</p> +<p class="Pp" id="attach">Each driver has an + <a class="permalink" href="#attach"><code class="Fn">attach</code></a>() + function which has a bus-specific <var class="Ft">attach_args</var> + structure. Each driver for a PCI device is passed a pointer to an object of + type <var class="Ft">struct pci_attach_args</var> which contains, among + other things, information about the location of the device in the PCI bus + topology sufficient to allow interrupts from the device to be handled.</p> +<p class="Pp" id="pci_msi_count"><a class="permalink" href="#pci_msi_count"><code class="Fn">pci_msi_count</code></a>() + returns the max number of the device's MSI. If the device can not use MSI, + <code class="Fn">pci_msi_count</code>() returns zero. + <a class="permalink" href="#pci_msix_count"><code class="Fn" id="pci_msix_count">pci_msix_count</code></a>() + works in the same manner for MSI-X.</p> +<p class="Pp" id="pci_msi_alloc">If a driver wishes to establish an MSI handler + for the device, it should pass the <var class="Ft">struct pci_attach_args + *</var> and <var class="Fa">count</var> + <a class="permalink" href="#pci_msi_alloc"><code class="Fn">pci_msi_alloc</code></a>() + or + <a class="permalink" href="#pci_msi_alloc_exact"><code class="Fn" id="pci_msi_alloc_exact">pci_msi_alloc_exact</code></a>() + functions, which return zero on success, and nonzero on failure. When the + functions are successful, they return the pointer to the allocated handle + array in <var class="Ft">pihs</var> whose size is + <var class="Ft">count</var> or less. The difference between + <code class="Fn">pci_msi_alloc</code>() and + <code class="Fn">pci_msi_alloc_exact</code>() is whether + <var class="Fa">count</var> can be decremented or not. + <code class="Fn">pci_msi_alloc</code>() can decrement + <var class="Fa">count</var>, and which is similar to + <span class="Ux">FreeBSD</span>'s + <a class="permalink" href="#pci_alloc_msi"><code class="Fn" id="pci_alloc_msi">pci_alloc_msi</code></a>(). + In contrast, <code class="Fn">pci_msi_alloc_exact</code>() can not decrement + <var class="Ft">count</var>.</p> +<p class="Pp" id="pci_intr_string">If the driver wishes to refer to the MSI + source in an attach or error message, it should use the value returned by + <a class="permalink" href="#pci_intr_string"><code class="Fn">pci_intr_string</code></a>() + the same as INTx. The buffer passed to + <code class="Fn">pci_intr_string</code>() should be at least + <code class="Dv">PCI_INTRSTR_LEN</code> bytes long.</p> +<p class="Pp" id="pci_intr_establish">Subsequently, when the driver is prepared + to receive MSIs, it should call + <a class="permalink" href="#pci_intr_establish"><code class="Fn">pci_intr_establish</code></a>() + the same as INTx to actually establish the handler; when the device + interrupts, <var class="Fa">intrhand</var> will be called with a single + argument <var class="Fa">intrarg</var>, and will run at the interrupt + priority level <var class="Fa">ipl</var>.</p> +<p class="Pp" id="pci_intr_establish~2">The return value of + <a class="permalink" href="#pci_intr_establish~2"><code class="Fn">pci_intr_establish</code></a>() + may be saved and passed to + <a class="permalink" href="#pci_intr_disestablish"><code class="Fn" id="pci_intr_disestablish">pci_intr_disestablish</code></a>() + to disable the interrupt handler the same as INTx when the driver is no + longer interested in MSIs from the device. After that, the driver should + also call <code class="Fn">pci_intr_release</code>() to free resources about + MSI as well as INTx and MSI-X. If <var class="Fa">pih</var> is NULL, + <code class="Fn">pci_intr_release</code>() does nothing.</p> +<p class="Pp" id="pci_msix_alloc_map">If a driver wishes to establish an MSI-X + handler for the device, it is almost the same as MSI. The only differences + is + <a class="permalink" href="#pci_msix_alloc_map"><code class="Fn">pci_msix_alloc_map</code></a>(). + This function can assign separate handlers for each MSI-X table entry. I.e., + if the driver wants to assign the handlers in the following way:</p> +<div class="Bd Pp Li"> +<pre> msix_handler0 => MSI-X table index: 4 + msix_handler1 => MSI-X table index: 5 + msix_handler2 => MSI-X table index: 0</pre> +</div> +the driver should set <var class="Fa">table_indexes</var> this way: +<div class="Bd Pp Li"> +<pre> table_indexes[0] = 4; + table_indexes[1] = 5; + table_indexes[2] = 0;</pre> +</div> +<p class="Pp" id="pci_intx_alloc">If the driver wants to fall back to INTx, the + driver should use + <a class="permalink" href="#pci_intx_alloc"><code class="Fn">pci_intx_alloc</code></a>() + and + <a class="permalink" href="#pci_intr_release"><code class="Fn" id="pci_intr_release">pci_intr_release</code></a>() + instead of + <a class="permalink" href="#pci_intr_map"><code class="Fn" id="pci_intr_map">pci_intr_map</code></a>() + to resolve contradiction of the interrupt handler ownership. I.e., + <code class="Fn">pci_intr_map</code>() does not have the ownership (the + function just calculates value), in contrast, + <code class="Fn">pci_msi_alloc</code>() and + <a class="permalink" href="#pci_msix_alloc"><code class="Fn" id="pci_msix_alloc">pci_msix_alloc</code></a>() + have (the functions allocate memory for interrupt handlers).</p> +<p class="Pp" id="pci_intr_alloc"><a class="permalink" href="#pci_intr_alloc"><code class="Fn">pci_intr_alloc</code></a>() + is wrapper function which select and automatically fallback allocation + functions according to the argument <var class="Fa">counts</var>. The + elements of <var class="Fa">counts</var> array means each required interrupt + count for INTx, MSI, and MSI-X. The index count of + <var class="Fa">counts</var> must be + <code class="Dv">PCI_INTR_TYPE_SIZE</code>. <var class="Fa">max_type</var> + must be <code class="Dv">PCI_INTR_TYPE_MSIX</code>, + <code class="Dv">PCI_INTR_TYPE_MSI</code>, or + <code class="Dv">PCI_INTR_TYPE_INTX</code>. The parameter does not mean + array index counts of <var class="Fa">counts</var>. The parameter means the + interrupt type which <code class="Fn">pci_intr_alloc</code>() tries to + allocate first. I.e., if the driver wants to allocate interrupts in the + following way:</p> +<div class="Bd Pp Li"> +<pre> 5 MSI-X + 1 MSI (if MSI-X allocation failed) + INTx (if MSI allocation failed either)</pre> +</div> +the driver should call <code class="Fn">pci_intr_alloc</code>() in the following + way: +<div class="Bd Pp Li"> +<pre> int counts[PCI_INTR_TYPE_SIZE]; + counts[PCI_INTR_TYPE_MSIX] = 5; + counts[PCI_INTR_TYPE_MSI] = 1; + counts[PCI_INTR_TYPE_INTX] = 1; + error = pci_intr_alloc(pa, ihps, counts, + PCI_INTR_TYPE_MSIX);</pre> +</div> +If the driver wants to allocate interrupts in the following way: +<div class="Bd Pp Li"> +<pre> hardware max number MSI-X + 1 MSI (if MSI-X allocation failed)</pre> +</div> +that is, the driver does not use INTx, the driver should call + <code class="Fn">pci_intr_alloc</code>() in the following way: +<div class="Bd Pp Li"> +<pre> int counts[PCI_INTR_TYPE_SIZE]; + counts[PCI_INTR_TYPE_MSIX] = -1; /* -1 means max */ + counts[PCI_INTR_TYPE_MSI] = 1; + counts[PCI_INTR_TYPE_INTX] = 0; /* 0 means not use */ + error = pci_intr_alloc(pa, ihps, counts, + PCI_INTR_TYPE_MSIX);</pre> +</div> +If the driver wants to allocate interrupts in the following way: +<div class="Bd Pp Li"> +<pre> 3 MSI + INTx (if MSI allocation failed)</pre> +</div> +that is, the driver does not use MSI-X, the driver should call + <code class="Fn">pci_intr_alloc</code>() in the following way: +<div class="Bd Pp Li"> +<pre> int counts[PCI_INTR_TYPE_SIZE]; + counts[PCI_INTR_TYPE_MSIX] = 0; /* 0 means not use */ + counts[PCI_INTR_TYPE_MSI] = 3; + counts[PCI_INTR_TYPE_INTX] = 1; + error = pci_intr_alloc(pa, ihps, counts, + PCI_INTR_TYPE_MSI);</pre> +</div> +If the driver wants to allocate interrupts in the following way: +<div class="Bd Pp Li"> +<pre> 1 MSI-X + 1 MSI + INTx (if MSI/MSI-X allocation failed)</pre> +</div> +that is, general usage, the driver should call simply + <code class="Fn">pci_intr_alloc</code>() in the following way: +<div class="Bd Pp Li"> +<pre> error = pci_intr_alloc(pa, ihps, NULL, 0);</pre> +</div> +<var class="Fa">max_type</var> is ignored in this case. + <code class="Fn">pci_intr_alloc</code>() returns zero on any allocation + function success, and non-zero on all allocation function failures. On + success, <var class="Fa">counts</var> is overwritten by a really allocated + count. I.e., if 5 MSI-X is allocated, <var class="Fa">counts</var> is +<div class="Bd Pp Li"> +<pre> counts[PCI_INTR_TYPE_MSIX] == 5 + counts[PCI_INTR_TYPE_MSI] == 0 + counts[PCI_INTR_TYPE_INTX] == 0</pre> +</div> +on return. +<p class="Pp" id="pci_intr_type"><a class="permalink" href="#pci_intr_type"><code class="Fn">pci_intr_type</code></a>() + returns the interrupt type of <var class="Fa">ih</var>. The return value is + <code class="Dv">PCI_INTR_TYPE_MSIX</code> for MSI-X, + <code class="Dv">PCI_INTR_TYPE_MSI</code> for MSI, and + <code class="Dv">PCI_INTR_TYPE_INTX</code> for others.</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">pci_intr(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp"><code class="Nm">pci_msi</code> support first appeared in + <span class="Ux">NetBSD 8.0</span>. Support is present on + <a class="permalink" href="#i386"><i class="Em" id="i386">i386</i></a>, + <a class="permalink" href="#amd64"><i class="Em" id="amd64">amd64</i></a> + and + <a class="permalink" href="#aarch64"><i class="Em" id="aarch64">aarch64</i></a> + architectures.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">pci_msi</code> interfaces were designed and + implemented by <span class="An">Kengo Nakahara</span> + <<a class="Mt" href="mailto:knakahara@NetBSD.org">knakahara@NetBSD.org</a>>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 12, 2021</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pckbport.9 3.html b/static/netbsd/man9/pckbport.9 3.html new file mode 100644 index 00000000..d1920d32 --- /dev/null +++ b/static/netbsd/man9/pckbport.9 3.html @@ -0,0 +1,319 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PCKBPORT(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PCKBPORT(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">pckbport</code>, + <code class="Nm">pckbport_attach</code>, + <code class="Nm">pckbport_attach_slot</code>, + <code class="Nm">pckbport_cnattach</code>, + <code class="Nm">pckbportintr</code>, + <code class="Nm">pckbport_set_inputhandler</code>, + <code class="Nm">pckbport_flush</code>, + <code class="Nm">pckbport_poll_cmd</code>, + <code class="Nm">pckbport_enqueue_cmd</code>, + <code class="Nm">pckbport_poll_data</code>, + <code class="Nm">pckbport_set_poll</code>, + <code class="Nm">pckbport_xt_translation</code>, + <code class="Nm">pckbport_slot_enable</code> — <span class="Nd">PC + keyboard port interface</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">dev/pckbport/pckbportvar.h</a>></code></p> +<p class="Pp"><var class="Ft">pckbport_tag_t</var> + <br/> + <code class="Fn">pckbport_attach</code>(<var class="Fa" style="white-space: nowrap;">void + *</var>, <var class="Fa" style="white-space: nowrap;">struct + pckbport_accessops const *</var>);</p> +<p class="Pp"><var class="Ft">struct device *</var> + <br/> + <code class="Fn">pckbport_attach_slot</code>(<var class="Fa" style="white-space: nowrap;">struct + device *</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pckbport_cnattach</code>(<var class="Fa" style="white-space: nowrap;">void + *</var>, <var class="Fa" style="white-space: nowrap;">struct + pckbport_accessops const *</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pckbportintr</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pckbport_set_inputhandler</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_inputfcn</var>, + <var class="Fa" style="white-space: nowrap;">void *</var>, + <var class="Fa" style="white-space: nowrap;">char *</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pckbport_flush</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pckbport_poll_cmd</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>, + <var class="Fa" style="white-space: nowrap;">u_char *</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">u_char *</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pckbport_enqueue_cmd</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>, + <var class="Fa" style="white-space: nowrap;">u_char *</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">int</var>, + <var class="Fa" style="white-space: nowrap;">u_char *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pckbport_poll_data</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pckbport_set_poll</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pckbport_xt_translation</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pckbport_slot_enable</code>(<var class="Fa" style="white-space: nowrap;">pckbport_tag_t</var>, + <var class="Fa" style="white-space: nowrap;">pckbport_slot_t</var>, + <var class="Fa" style="white-space: nowrap;">int</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The machine-independent <code class="Nm">pckbport</code> subsystem + provides an interface layer corresponding to the serial keyboard and mouse + interface used on the IBM PS/2 and many other machines. It interfaces a + controller driver such as <a class="Xr">pckbc(4)</a> to device drivers such + as <a class="Xr">pckbd(4)</a> and <a class="Xr">pms(4)</a>.</p> +<p class="Pp">A single controller can have up to two ports (known as + “slots”), and these are identified by values of type + <var class="Fa">pckbport_slot_t</var>. The values + <code class="Dv">PCKBPORT_KBD_SLOT</code> and + <code class="Dv">PCKBPORT_AUX_SLOT</code> should be used for keyboard and + mouse ports respectively. Each controller is identified by an opaque value + of type <var class="Fa">pckbport_tag_t</var>.</p> +<section class="Ss"> +<h2 class="Ss" id="Controller_interface"><a class="permalink" href="#Controller_interface">Controller + interface</a></h2> +<p class="Pp">A PC keyboard controller registers itself by calling + <a class="permalink" href="#pckbport_attach"><code class="Fn" id="pckbport_attach">pckbport_attach</code></a>(<var class="Fa">cookie</var>, + <var class="Fa">ops</var>), with <var class="Fa">ops</var> being a pointer + to a <var class="Fa">struct pckbport_accessops</var> containing pointers to + functions for driving the controller, which will all be called with + <var class="Fa">cookie</var> as their first argument. + <code class="Fn">pckbport_attach</code>() returns the + <var class="Fa">pckbport_tag_t</var> assigned to the controller. The + controller is then expected to call + <a class="permalink" href="#pckbport_attach_slot"><code class="Fn" id="pckbport_attach_slot">pckbport_attach_slot</code></a>() + for each slot with which it is equipped, passing the <var class="Fa">struct + device *</var> corresponding to the controller. This function returns a + pointer to the child device attached to the slot, or + <code class="Dv">NULL</code> if no such device was attached.</p> +<p class="Pp" id="pckbport_attach~2">The elements of <var class="Fa">struct + pckbport_accessops</var> each take as their first two arguments the + <var class="Fa">cookie</var> passed to + <a class="permalink" href="#pckbport_attach~2"><code class="Fn">pckbport_attach</code></a>() + and the slot in question. The elements are:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">int</var> + <code class="Fn">(*t_xt_translation)</code>(<var class="Fa">void + *cookie</var>, <var class="Fa">pckbport_slot_t slot</var>, + <var class="Fa">int on</var>)</dt> + <dd>If <var class="Fa">on</var> is non-zero, enable, otherwise disable, + AT-to-XT keycode translation on the slot specified. Returns 1 on success, + 0 on failure (or if the controller does not support such + translation).</dd> + <dt><var class="Fa">int</var> + <code class="Fn">(*t_send_devcmd)</code>(<var class="Fa">void *cookie</var>, + <var class="Fa">pckbport_slot_t slot</var>, <var class="Fa">u_char + byte</var>)</dt> + <dd>Send a single <var class="Fa">byte</var> to the device without waiting for + completion. Returns 1 on success, 0 on failure.</dd> + <dt><var class="Fa">int</var> + <code class="Fn">(*t_poll_data1)</code>(<var class="Fa">void *cookie</var>, + <var class="Fa">pckbport_slot_t slot</var>)</dt> + <dd>Wait for and return one byte of data from the device, without using + interrupts. This function will only be called after + <code class="Fn">(*t_set_poll)</code>() has been used to put the slot in + polling mode. If no data are forthcoming from the device after about + 100ms, return -1.</dd> + <dt><var class="Fa">void</var> + <code class="Fn">(*t_slot_enable)</code>(<var class="Fa">void *cookie</var>, + <var class="Fa">pckbport_slot_t slot</var>, <var class="Fa">int + on</var>)</dt> + <dd>If <var class="Fa">on</var> is non-zero, enable, otherwise disable, the + slot. If a slot is disabled, it can be powered down, and is not expected + to generate any interrupts. When first attached, ports should be + disabled.</dd> + <dt><var class="Fa">void</var> + <code class="Fn">(*t_intr_establish)</code>(<var class="Fa">void + *cookie</var>, <var class="Fa">pckbport_slot_t slot</var>)</dt> + <dd>Set up an interrupt handler for the slot. Called when a device gets + attached to it.</dd> + <dt id="pckbportintr"><var class="Fa">void</var> + <code class="Fn">(*t_set_poll)</code>(<var class="Fa">void *cookie</var>, + <var class="Fa">pckbport_slot_t slot</var>, <var class="Fa">int + on</var>)</dt> + <dd>If <var class="Fa">on</var> is non-zero, enable, otherwise disable, + polling mode on the slot. In polling mode, data received from the device + are provided to <code class="Fn">(*t_poll_data1)</code>() and not passed + to + <a class="permalink" href="#pckbportintr"><code class="Fn">pckbportintr</code></a>(), + whether or not interrupts are enabled. In non-polling mode, data from the + device are expected to cause interrupts. The controller interrupt handler + should call + <code class="Fn">pckbportintr</code>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>, <var class="Fa">byte</var>) once for each + <var class="Va">byte</var> received from the device. When first attached, + a port should be in non-polling mode.</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Device_interface"><a class="permalink" href="#Device_interface">Device + interface</a></h2> +<p class="Pp">Devices that attach to <code class="Nm">pckbport</code> + controllers do so using the normal <a class="Xr">autoconf(9)</a> mechanism. + Their <code class="Fn">(*ca_match)</code>() and + <code class="Fn">(*ca_attach)</code>() functions get passed a + <var class="Fa">struct pckbport_attach_args</var> which contains the + controller and slot number where the device was found. Device drivers can + use the following functions to communicate with the controller. Each takes + <var class="Fa">tag</var> and <var class="Fa">slot</var> arguments to + specify the slot to be acted on.</p> +<dl class="Bl-tag"> + <dt id="pckbport_set_inputhandler"><a class="permalink" href="#pckbport_set_inputhandler"><code class="Fn">pckbport_set_inputhandler</code></a>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>, <var class="Fa">fn</var>, + <var class="Fa">arg</var>, <var class="Fa">name</var>)</dt> + <dd>Arrange for <var class="Fa">fn</var> to be called with argument + <var class="Fa">arg</var> whenever an unsolicited byte is received from + the slot. The function will be called at + <a class="permalink" href="#spltty"><code class="Fn" id="spltty">spltty</code></a>().</dd> + <dt id="pckbport_flush"><a class="permalink" href="#pckbport_flush"><code class="Fn">pckbport_flush</code></a>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>)</dt> + <dd>Ensure that there is no pending input from the slot.</dd> + <dt id="pckbport_poll_cmd"><a class="permalink" href="#pckbport_poll_cmd"><code class="Fn">pckbport_poll_cmd</code></a>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>, <var class="Fa">cmd</var>, + <var class="Fa">len</var>, <var class="Fa">responselen</var>, + <var class="Fa">respbuf</var>, <var class="Fa">slow</var>)</dt> + <dd>Issue a complete device command, <var class="Fa">cmd</var>, + <var class="Fa">len</var> bytes long, expecting a response + <var class="Fa">responselen</var> bytes long, which will be placed in + <var class="Fa">respbuf</var>. If <var class="Fa">slow</var> is true, the + command is expected to take over a second to execute. + <code class="Fn">pckbport_poll_cmd</code>() handles getting an + acknowledgement from the device and retrying the command if necessary. + Returns 0 on success, and an error value on failure. This function should + only be called during autoconfiguration or when the slot has been placed + into polling mode by + <a class="permalink" href="#pckbport_set_poll"><code class="Fn" id="pckbport_set_poll">pckbport_set_poll</code></a>().</dd> + <dt id="pckbport_enqueue_cmd"><a class="permalink" href="#pckbport_enqueue_cmd"><code class="Fn">pckbport_enqueue_cmd</code></a>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>, <var class="Fa">cmd</var>, + <var class="Fa">len</var>, <var class="Fa">responselen</var>, + <var class="Fa">sync</var>, <var class="Fa">respbuf</var>)</dt> + <dd>Issue a complete device command, <var class="Fa">cmd</var>, + <var class="Fa">len</var> bytes long, expecting a response + <var class="Fa">responselen</var> bytes long, which will be places in + <var class="Fa">respbuf</var>. If <var class="Fa">sync</var> is true, + <code class="Fn">pckbport_enqueue_cmd</code>() waits for the command to + complete before returning, otherwise it returns immediately. It is not + safe to set <var class="Fa">sync</var> when calling from an interrupt + context. The <code class="Nm">pckbport</code> layer handles getting an + acknowledgement from the device and retrying the command if necessary. + Returns 0 on success, and an error value on failure.</dd> + <dt id="pckbport_poll_data"><a class="permalink" href="#pckbport_poll_data"><code class="Fn">pckbport_poll_data</code></a>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>)</dt> + <dd>Low-level command to poll for a single byte of data from the device, but + ignoring bytes that are part of the response to a command issued through + <a class="permalink" href="#pckbport_enqueue_command"><code class="Fn" id="pckbport_enqueue_command">pckbport_enqueue_command</code></a>().</dd> + <dt><code class="Fn">pckbport_set_poll</code>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>, <var class="Fa">on</var>)</dt> + <dd>If <var class="Fa">on</var> is true, enable polling on the slot, otherwise + disable it. In polling mode, <code class="Fn">pckbport_poll_cmd</code>() + can be used to issue commands and + <code class="Fn">pckbport_poll_data</code>() to read unsolicited data, + without enabling interrupts. In non-polling mode, commands should be + issued using <code class="Fn">pckbport_enqueue_cmd</code>(), unsolicited + data are handled by the input function, and disabling interrupts will + suspend <code class="Nm">pckbport</code> operation.</dd> + <dt id="pckbport_xt_translation"><a class="permalink" href="#pckbport_xt_translation"><code class="Fn">pckbport_xt_translation</code></a>(<var class="Fa">tag</var>, + <var class="Fa">slot</var>, <var class="Fa">on</var>)</dt> + <dd>Passthrough of <code class="Fn">(*t_xt_translation)</code>() (see + above).</dd> + <dt id="pckbport_slot"><a class="permalink" href="#pckbport_slot"><code class="Fn">pckbport_slot</code></a>(<var class="Fa">enable</var>, + <var class="Fa">tag</var>, <var class="Fa">slot</var>, + <var class="Fa">on</var>)</dt> + <dd>Passthrough of <code class="Fn">(*t_slot_enable)</code>() (see + above).</dd> +</dl> +</section> +<section class="Ss"> +<h2 class="Ss" id="Console_interface"><a class="permalink" href="#Console_interface">Console + interface</a></h2> +<p class="Pp">On systems that can attach consoles through + <code class="Nm">pckbport</code>, the controller's console attachment + function (called very early in autoconfiguration) calls + <a class="permalink" href="#pckbport_cnattach"><code class="Fn" id="pckbport_cnattach">pckbport_cnattach</code></a>(<var class="Fa">cookie</var>, + <var class="Fa">ops</var>, <var class="Fa">slot</var>). The first two + arguments are the same as for <code class="Fn">pckbport_attach</code>(), + while the third indicates which slot the console keyboard is attached to. + <code class="Fn">pckbport_cnattach</code>() either calls + <a class="permalink" href="#pckbd_cnattach"><code class="Fn" id="pckbd_cnattach">pckbd_cnattach</code></a>(), + if it is available, or + <a class="permalink" href="#pckbport_machdep_cnattach"><code class="Fn" id="pckbport_machdep_cnattach">pckbport_machdep_cnattach</code></a>(). + The latter allows machine-dependent keyboard drivers to attach themselves, + but it is only called if a device with the + ‘<code class="Li">pckbport_machdep_cnattach</code>’ attribute + is configured into the system. <code class="Fn">pckbport_cnattach</code>() + returns 0 on success and an error value on failure. + <code class="Fn">pckbport_machdep_cnattach</code>() is expected to do the + same.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">pckbport</code> code, and the + <a class="Xr">pckbd(4)</a> and <a class="Xr">pms(4)</a> device drivers are + in <span class="Pa">sys/dev/pckbport</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">pckbc(4)</a>, <a class="Xr">pckbd(4)</a>, + <a class="Xr">pms(4)</a>, <a class="Xr">autoconf(9)</a>, + <a class="Xr">spl(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">pckbport</code> system appeared in + <span class="Ux">NetBSD 2.0</span>. Before that, <a class="Xr">pckbd(4)</a> + and <a class="Xr">pms(4)</a> attached directly to <a class="Xr">pckbc(4)</a> + without any sensible way of using a different controller.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 5, 2004</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pcq.9 3.html b/static/netbsd/man9/pcq.9 3.html new file mode 100644 index 00000000..0dc43915 --- /dev/null +++ b/static/netbsd/man9/pcq.9 3.html @@ -0,0 +1,162 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PCQ(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PCQ(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">pcq</code> — + <span class="Nd">producer/consumer queue</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/pcq.h</a>></code></p> +<p class="Pp"><var class="Ft">pcq_t *</var> + <br/> + <code class="Fn">pcq_create</code>(<var class="Fa" style="white-space: nowrap;">size_t + maxlen</var>, <var class="Fa" style="white-space: nowrap;">km_flags_t + kmflags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pcq_destroy</code>(<var class="Fa" style="white-space: nowrap;">pcq_t + *pcq</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">pcq_get</code>(<var class="Fa" style="white-space: nowrap;">pcq_t + *pcq</var>);</p> +<p class="Pp"><var class="Ft">size_t</var> + <br/> + <code class="Fn">pcq_maxitems</code>(<var class="Fa" style="white-space: nowrap;">pcq_t + *pcq</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">pcq_peek</code>(<var class="Fa" style="white-space: nowrap;">pcq_t + *pcq</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pcq_put</code>(<var class="Fa" style="white-space: nowrap;">pcq_t + *pcq</var>, <var class="Fa" style="white-space: nowrap;">void + *item</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The machine-independent <code class="Nm">pcq</code> interface + provides lockless producer/consumer queues. A queue + (<var class="Vt">pcq_t</var>) allows multiple writers (producers), but only + a single reader (consumer). The consumer is expected to be protected by a + lock that covers the structure that the <var class="Vt">pcq_t</var> is + embedded into (e.g., socket lock, ifnet hwlock). These queues operate in a + first-in, first-out (FIFO) manner. The act of inserting or removing an item + from a <var class="Vt">pcq_t</var> does not modify the item in any way. + <code class="Nm">pcq</code> does not prevent an item from being inserted + multiple times into a single <var class="Vt">pcq_t</var>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="pcq_create"><a class="permalink" href="#pcq_create"><code class="Fn">pcq_create</code></a>(<var class="Fa">maxlen</var>, + <var class="Fa">kmflags</var>)</dt> + <dd>Create a queue that can store at most <var class="Fa">maxlen</var> items + at one time. <var class="Fa">kmflags</var> should be either + <code class="Dv">KM_SLEEP</code>, if <code class="Fn">pcq_create</code>() + is allowed to sleep until resources are available, or + <code class="Dv">KM_NOSLEEP</code> if it should return + <code class="Dv">NULL</code> immediately, if resources are + unavailable.</dd> + <dt id="pcq_destroy"><a class="permalink" href="#pcq_destroy"><code class="Fn">pcq_destroy</code></a>(<var class="Fa">pcq</var>)</dt> + <dd>Free the resources held by <var class="Fa">pcq</var>.</dd> + <dt><code class="Fn">pcq_get</code>(<var class="Fa">pcq</var>)</dt> + <dd>Remove the next item to be consumed from the queue and return it. If the + queue is empty, return <code class="Dv">NULL</code>. The caller must + prevent concurrent gets from occurring.</dd> + <dt id="pcq_maxitems"><a class="permalink" href="#pcq_maxitems"><code class="Fn">pcq_maxitems</code></a>(<var class="Fa">pcq</var>)</dt> + <dd>Return the maximum number of items that the queue can store at any one + time.</dd> + <dt><code class="Fn">pcq_peek</code>(<var class="Fa">pcq</var>)</dt> + <dd>Return the next item to be consumed from the queue but do not remove it + from the queue. If the queue is empty, return + <code class="Dv">NULL</code>.</dd> + <dt><code class="Fn">pcq_put</code>(<var class="Fa">pcq</var>, + <var class="Fa">item</var>)</dt> + <dd>Place an item at the end of the queue. If there is no room in the queue + for the item, return <code class="Dv">false</code>; otherwise, return + <code class="Dv">true</code>. The item must not have the value of + <code class="Dv">NULL</code>.</dd> +</dl> +<section class="Ss"> +<h2 class="Ss" id="Memory_ordering"><a class="permalink" href="#Memory_ordering">Memory + ordering</a></h2> +<p class="Pp">Any memory operations sequenced before + <code class="Fn">pcq_put</code>() of an item in one thread happen before all + memory operations with data dependencies on the item returned by + <code class="Fn">pcq_get</code>() or <code class="Fn">pcq_peek</code>() in + another thread. For example:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>int mumble; + +/* producer */ +mumble = 42; // A +foo->x = 123; // B +refcnt = foo->refcnt; // C +pcq_put(pcq, foo); +KASSERT(refcnt == 0); + +/* consumer */ +foo = pcq_get(pcq); +if (foo == NULL) + return; +atomic_inc_uint(&foo->refcnt); // D +x = foo->x; // E +if (x == 123) + KASSERT(mumble == 42); // F</pre> +</div> +<p class="Pp" id="pcq_get">In this example, memory operations B and C + happen-before D and E. However, no ordering is guaranteed for A or F + relative to any other memory operations, because the memory location of + <var class="Fa">mumble</var> is independent of the pointer + <var class="Fa">foo</var> returned by + <a class="permalink" href="#pcq_get"><code class="Fn">pcq_get</code></a>().</p> +<p class="Pp" id="pcq_get~2">If you must guarantee A happens before F, then on + the consumer side, after + <a class="permalink" href="#pcq_get~2"><code class="Fn">pcq_get</code></a>() + or + <a class="permalink" href="#pcq_peek"><code class="Fn" id="pcq_peek">pcq_peek</code></a>(), + you can call + <a class="permalink" href="#membar_acquire"><code class="Fn" id="membar_acquire">membar_acquire</code></a>() + to turn it into an acquire operation instead of a consume operation; + <a class="permalink" href="#pcq_put"><code class="Fn" id="pcq_put">pcq_put</code></a>() + serves as the matching release operation. (This is a little dicey. Perhaps + there should be separate + <a class="permalink" href="#pcq_peek_acq"><code class="Fn" id="pcq_peek_acq">pcq_peek_acq</code></a>() + and + <a class="permalink" href="#pcq_get_acq"><code class="Fn" id="pcq_get_acq">pcq_get_acq</code></a>() + operations if this semantics is necessary.)</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">pcq</code> interface is implemented within + the file <span class="Pa">sys/kern/subr_pcq.c</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">atomic_ops(3)</a>, <a class="Xr">queue(3)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">pcq</code> interface first appeared in + <span class="Ux">NetBSD 6.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 22, 2012</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pfil.9 3.html b/static/netbsd/man9/pfil.9 3.html new file mode 100644 index 00000000..f140ca0d --- /dev/null +++ b/static/netbsd/man9/pfil.9 3.html @@ -0,0 +1,246 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PFIL(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PFIL(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">pfil</code>, + <code class="Nm">pfil_head_create</code>, + <code class="Nm">pfil_head_destroy</code>, + <code class="Nm">pfil_head_get</code>, + <code class="Nm">pfil_hook_get</code>, + <code class="Nm">pfil_add_hook</code>, + <code class="Nm">pfil_remove_hook</code>, + <code class="Nm">pfil_run_hooks</code>, + <code class="Nm">pfil_add_ihook</code>, + <code class="Nm">pfil_remove_ihook</code>, + <code class="Nm">pfil_run_addrhooks</code>, + <code class="Nm">pfil_run_ifhooks</code> — <span class="Nd">packet + filter interface</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/mbuf.h</a>></code> + <br/> + <code class="In">#include <<a class="In">net/if.h</a>></code> + <br/> + <code class="In">#include <<a class="In">net/pfil.h</a>></code></p> +<p class="Pp"><var class="Ft">pfil_head_t *</var> + <br/> + <code class="Fn">pfil_head_create</code>(<var class="Fa" style="white-space: nowrap;">int + type</var>, <var class="Fa" style="white-space: nowrap;">void + *key</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pfil_head_destroy</code>(<var class="Fa" style="white-space: nowrap;">pfil_head_t + *ph</var>);</p> +<p class="Pp"><var class="Ft">pfil_head_t *</var> + <br/> + <code class="Fn">pfil_head_get</code>(<var class="Fa" style="white-space: nowrap;">int + type</var>, <var class="Fa" style="white-space: nowrap;">void + *key</var>);</p> +<p class="Pp"><var class="Ft">struct packet_filter_hook *</var> + <br/> + <code class="Fn">pfil_hook_get</code>(<var class="Fa" style="white-space: nowrap;">int + dir</var>, <var class="Fa" style="white-space: nowrap;">pfil_head_t + *ph</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pfil_add_hook</code>(<var class="Fa" style="white-space: nowrap;">pfil_func_t + func</var>, <var class="Fa" style="white-space: nowrap;">void *arg</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">pfil_head_t *ph</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pfil_remove_hook</code>(<var class="Fa" style="white-space: nowrap;">pfil_func_t + func</var>, <var class="Fa" style="white-space: nowrap;">void *arg</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">pfil_head_t *ph</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">(*func)</code>(<var class="Fa" style="white-space: nowrap;">void + *arg</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf + **mp</var>, <var class="Fa" style="white-space: nowrap;">struct ifnet + *</var>, <var class="Fa" style="white-space: nowrap;">int dir</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pfil_run_hooks</code>(<var class="Fa" style="white-space: nowrap;">pfil_head_t + *ph</var>, <var class="Fa" style="white-space: nowrap;">struct mbuf + **mp</var>, <var class="Fa" style="white-space: nowrap;">struct ifnet + *ifp</var>, <var class="Fa" style="white-space: nowrap;">int dir</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pfil_add_ihook</code>(<var class="Fa" style="white-space: nowrap;">pfil_ifunc_t + ifunc</var>, <var class="Fa" style="white-space: nowrap;">void *arg</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">pfil_head_t *ph</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pfil_remove_ihook</code>(<var class="Fa" style="white-space: nowrap;">pfil_ifunc_t + ifunc</var>, <var class="Fa" style="white-space: nowrap;">void *arg</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">pfil_head_t *ph</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">(*ifunc)</code>(<var class="Fa" style="white-space: nowrap;">void + *arg</var>, <var class="Fa" style="white-space: nowrap;">unsigned long + cmd</var>, <var class="Fa" style="white-space: nowrap;">void + *ptr</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pfil_run_addrhooks</code>(<var class="Fa" style="white-space: nowrap;">pfil_head_t + *ph</var>, <var class="Fa" style="white-space: nowrap;">unsigned long</var>, + <var class="Fa" style="white-space: nowrap;">struct ifaddr *ifa</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pfil_run_ifhooks</code>(<var class="Fa" style="white-space: nowrap;">pfil_head_t + *ph</var>, <var class="Fa" style="white-space: nowrap;">unsigned long</var>, + <var class="Fa" style="white-space: nowrap;">struct ifnet *ifp</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">pfil</code> framework allows for a specified + function to be invoked for every incoming or outgoing packet for a + particular network I/O stream. These hooks may be used to implement a + firewall or perform packet transformations.</p> +<p class="Pp" id="pfil_head_create">Packet filtering points are created with + <a class="permalink" href="#pfil_head_create"><code class="Fn">pfil_head_create</code></a>(). + Filtering points are identified by a data link (<var class="Vt">int</var>) + <var class="Fa">type</var> and a (<var class="Vt">void *</var>) + <var class="Fa">key</var>. If a packet filtering point already exists for + that data link <var class="Fa">type</var> and <var class="Fa">key</var> then + the <code class="Fn">pfil_head_create</code>() function returns + <code class="Dv">NULL</code>. Packet filters use the + <a class="permalink" href="#pfil_head_get"><code class="Fn" id="pfil_head_get">pfil_head_get</code></a>() + function specifying the data link <var class="Fa">type</var> and the + <var class="Fa">key</var> to look up the filtering point with which they + register themselves. The <var class="Fa">key</var> is unique to the + filtering point. The data link <var class="Fa">type</var> is a + <a class="Xr">bpf(4)</a> + <code class="Dv">DLT_</code><var class="Ar">type</var> constant indicating + what kind of header is present on the packet at the filtering point. + Filtering points may be destroyed with the + <a class="permalink" href="#pfil_head_destroy"><code class="Fn" id="pfil_head_destroy">pfil_head_destroy</code></a>() + function.</p> +<p class="Pp" id="pfil_add_hook">Packet filters register/unregister themselves + with a filtering point with the + <a class="permalink" href="#pfil_add_hook"><code class="Fn">pfil_add_hook</code></a>() + and + <a class="permalink" href="#pfil_remove_hook"><code class="Fn" id="pfil_remove_hook">pfil_remove_hook</code></a>() + functions, respectively. The head is looked up using the + <a class="permalink" href="#pfil_head_get~2"><code class="Fn" id="pfil_head_get~2">pfil_head_get</code></a>() + function, which takes the data link <var class="Fa">type</var> and the + <var class="Fa">key</var> that the packet filter expects. Filters may + provide an argument to be passed to the filter when invoked on a packet.</p> +<p class="Pp">When a filter is invoked, the packet appears just as if it + “came off the wire”. That is, all protocol fields are in + network byte order. The filter is called with its specified argument, the + pointer to the pointer to the mbuf containing the packet, the pointer to the + network interface that the packet is traversing, and the direction (either + <code class="Dv">PFIL_IN</code> or <code class="Dv">PFIL_OUT</code>, see + also below) that the packet is traveling. The filter may change which mbuf + the <var class="Vt">mbuf **</var> argument references. The filter returns an + errno if the packet processing is to stop, or 0 if the processing is to + continue. If the packet processing is to stop, it is the responsibility of + the filter to free the packet.</p> +<p class="Pp" id="pfil_add_hook~2">The <var class="Fa">flags</var> parameter, + used in the + <a class="permalink" href="#pfil_add_hook~2"><code class="Fn">pfil_add_hook</code></a>() + and + <a class="permalink" href="#pfil_remove_hook~2"><code class="Fn" id="pfil_remove_hook~2">pfil_remove_hook</code></a>() + functions, indicates when the filter should be called. The flags are:</p> +<p class="Pp"></p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt id="PFIL_IN"><a class="permalink" href="#PFIL_IN"><code class="Dv">PFIL_IN</code></a></dt> + <dd>call me on incoming packets</dd> + <dt id="PFIL_OUT"><a class="permalink" href="#PFIL_OUT"><code class="Dv">PFIL_OUT</code></a></dt> + <dd>call me on outgoing packets</dd> + <dt id="PFIL_ALL"><a class="permalink" href="#PFIL_ALL"><code class="Dv">PFIL_ALL</code></a></dt> + <dd>call me on all of the above</dd> +</dl> +</div> +<p class="Pp" id="pfil_add_ihook">By the same token, event handlers + register/unregister themselves with the + <a class="permalink" href="#pfil_add_ihook"><code class="Fn">pfil_add_ihook</code></a>() + and + <a class="permalink" href="#pfil_remove_ihook"><code class="Fn" id="pfil_remove_ihook">pfil_remove_ihook</code></a>() + functions, respectively. The event handler is called with its specified + argument, the event id (either <code class="Dv">PFIL_IFNET_ATTACH</code> or + <code class="Dv">PFIL_IFNET_DETACH</code>, see also below) or ioctl number, + and the pointer to the network interface or the pointer to the ifaddr.</p> +<p class="Pp" id="pfil_add_ihook~2">The <var class="Fa">flags</var> parameter, + used in the + <a class="permalink" href="#pfil_add_ihook~2"><code class="Fn">pfil_add_ihook</code></a>() + and + <a class="permalink" href="#pfil_remove_ihook~2"><code class="Fn" id="pfil_remove_ihook~2">pfil_remove_ihook</code></a>() + functions, indicates when the filter should be called. The flags are:</p> +<p class="Pp"></p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt id="PFIL_IFADDR"><a class="permalink" href="#PFIL_IFADDR"><code class="Dv">PFIL_IFADDR</code></a></dt> + <dd>call me on interface reconfig (<var class="Fa">cmd</var> is ioctl #)</dd> + <dt id="PFIL_IFNET"><a class="permalink" href="#PFIL_IFNET"><code class="Dv">PFIL_IFNET</code></a></dt> + <dd>call me on interface attach/detach (<var class="Fa">cmd</var> is either + <code class="Dv">PFIL_IFNET_ATTACH</code> or + <code class="Dv">PFIL_IFNET_DETACH</code>)</dd> +</dl> +</div> +</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">bpf(4)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">pfil</code> interface first appeared in + <span class="Ux">NetBSD 1.3</span>. The <code class="Nm">pfil</code> input + and output lists were originally implemented as + <code class="In"><<a class="In">sys/queue.h</a>></code> + <code class="Dv">LIST</code> structures; however this was changed in + <span class="Ux">NetBSD 1.4</span> to <code class="Dv">TAILQ</code> + structures. This change was to allow the input and output filters to be + processed in reverse order, to allow the same path to be taken, in or out of + the kernel.</p> +<p class="Pp">The <code class="Nm">pfil</code> interface was changed in 1.4T to + accept a 3rd parameter to both <code class="Fn">pfil_add_hook</code>() and + <code class="Fn">pfil_remove_hook</code>(), introducing the capability of + per-protocol filtering. This was done primarily in order to support + filtering of IPv6.</p> +<p class="Pp">In 1.5K, the <code class="Nm">pfil</code> framework was changed to + work with an arbitrary number of filtering points, as well as be less + IP-centric.</p> +<p class="Pp"><code class="Fn">pfil_add_ihook</code>() and + <code class="Fn">pfil_remove_ihook</code>() were added in + <span class="Ux">NetBSD 8.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">pfil</code> interface was designed and + implemented by <span class="An">Matthew R. Green</span>, with help from + <span class="An">Darren Reed</span>, <span class="An">Jason R. + Thorpe</span>, and <span class="An">Charles M. Hannum</span>. + <span class="An">Darren Reed</span> added support for IPv6 in addition to + IPv4. <span class="An">Jason R. Thorpe</span> added support for multiple + hooks and other clean up.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">The current <code class="Nm">pfil</code> implementation will need + changes to suit a threaded kernel model.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 15, 2022</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/physio.9 3.html b/static/netbsd/man9/physio.9 3.html new file mode 100644 index 00000000..6f566d57 --- /dev/null +++ b/static/netbsd/man9/physio.9 3.html @@ -0,0 +1,93 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PHYSIO(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PHYSIO(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">physio</code> — <span class="Nd">initiate + I/O on raw devices</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">physio</code>(<var class="Fa">void (*strategy)(buf_t + *)</var>, <var class="Fa">buf_t *bp</var>, <var class="Fa">dev_t dev</var>, + <var class="Fa">int flags</var>, <var class="Fa">void (*minphys)(buf_t + *)</var>, <var class="Fa">struct uio *uio</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#physio"><code class="Fn" id="physio">physio</code></a>() + is a helper function typically called from character device read and write + routines to start I/O on a user process buffer. It calls back on the + provided <var class="Fa">strategy</var> routine one or more times to + complete the transfer described by <var class="Fa">uio</var>. The maximum + amount of data to transfer with each call to <var class="Fa">strategy</var> + is determined by the <var class="Fa">minphys</var> routine.</p> +<p class="Pp" id="physio~2">Since <var class="Fa">uio</var> normally describes + user space addresses, + <a class="permalink" href="#physio~2"><code class="Fn">physio</code></a>() + needs to lock the appropriate data area into memory before each transaction + with <var class="Fa">strategy</var> (see <a class="Xr">uvm_vslock(9)</a> and + <a class="Xr">uvm_vsunlock(9)</a>). The <code class="Fn">physio</code>() + function always awaits the completion of the entire requested transfer + before returning, unless an error condition is detected earlier. In all + cases, the buffer passed in <var class="Fa">bp</var> is locked (marked as + “busy”) for the duration of the entire transfer.</p> +<p class="Pp">A break-down of the arguments follows:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">strategy</var></dt> + <dd>The device strategy routine to call for each chunk of data to initiate + device I/O.</dd> + <dt><var class="Fa">bp</var></dt> + <dd>The buffer to use with the strategy routine. The buffer flags will have + <code class="Dv">B_BUSY</code>, <code class="Dv">B_PHYS</code>, and + <code class="Dv">B_RAW</code> set when passed to the strategy routine. If + <code class="Dv">NULL</code>, a buffer is allocated from a system + pool.</dd> + <dt><var class="Fa">dev</var></dt> + <dd>The device number identifying the device to interact with.</dd> + <dt><var class="Fa">flags</var></dt> + <dd>Direction of transfer; the only valid settings are + <code class="Dv">B_READ</code> or <code class="Dv">B_WRITE</code>.</dd> + <dt><var class="Fa">minphys</var></dt> + <dd>A device specific routine called to determine the maximum transfer size + that the device's strategy routine can handle.</dd> + <dt><var class="Fa">uio</var></dt> + <dd>The description of the entire transfer as requested by the user process. + Currently, the results of passing a <var class="Fa">uio</var> structure + with the ‘uio_segflg’ set to anything other than + <code class="Dv">UIO_USERSPACE</code>, are undefined.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">If successful <code class="Fn">physio</code>() returns 0. + <code class="Er">EFAULT</code> is returned if the address range described by + <var class="Fa">uio</var> is not accessible by the requesting process. + <code class="Fn">physio</code>() will return any error resulting from calls + to the device strategy routine, by examining the + <code class="Dv">B_ERROR</code> buffer flag and the ‘b_error’ + field. Note that the actual transfer size may be less than requested by + <var class="Fa">uio</var> if the device signals an “end of + file” condition.</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">read(2)</a>, <a class="Xr">write(2)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 12, 2019</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pmatch.9 3.html b/static/netbsd/man9/pmatch.9 3.html new file mode 100644 index 00000000..54a90803 --- /dev/null +++ b/static/netbsd/man9/pmatch.9 3.html @@ -0,0 +1,59 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PMATCH(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PMATCH(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">pmatch</code> — <span class="Nd">performs + pattern matching on strings</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pmatch</code>(<var class="Fa" style="white-space: nowrap;">const + char *string</var>, <var class="Fa" style="white-space: nowrap;">const char + *pattern</var>, <var class="Fa" style="white-space: nowrap;">const char + **estr</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Extract substring matching <var class="Fa">pattern</var> from + <var class="Fa">string</var>. If not <code class="Dv">NULL</code>, + <var class="Fa">estr</var> points to the end of the longest exact or + substring match.</p> +<p class="Pp" id="pmatch"><a class="permalink" href="#pmatch"><code class="Fn">pmatch</code></a>() + uses the following metacharacters:</p> +<dl class="Bl-tag"> + <dt id="?"><a class="permalink" href="#?"><code class="Li">?</code></a></dt> + <dd>match any single character.</dd> + <dt id="*"><a class="permalink" href="#*"><code class="Li">*</code></a></dt> + <dd>match any character 0 or more times.</dd> + <dt id="_"><a class="permalink" href="#_"><code class="Li">[</code></a></dt> + <dd>define a range of characters that will match. The range is defined by 2 + characters separated by a ‘<code class="Li">-</code>’. The + range definition has to end with a + ‘<code class="Li">]</code>’. A + ‘<code class="Li">^</code>’ following the + ‘<code class="Li">[</code>’ will negate the range.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp"><code class="Fn">pmatch</code>() will return 2 for an exact match, + 1 for a substring match, 0 for no match and -1 if an error occurs.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 12, 2003</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pmf.9 3.html b/static/netbsd/man9/pmf.9 3.html new file mode 100644 index 00000000..d9e091dd --- /dev/null +++ b/static/netbsd/man9/pmf.9 3.html @@ -0,0 +1,320 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PMF(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PMF(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">PMF</code>, + <code class="Nm">pmf_device_register</code>, + <code class="Nm">pmf_device_register1</code>, + <code class="Nm">pmf_device_deregister</code>, + <code class="Nm">pmf_device_suspend</code>, + <code class="Nm">pmf_device_resume</code>, + <code class="Nm">pmf_device_recursive_suspend</code>, + <code class="Nm">pmf_device_recursive_resume</code>, + <code class="Nm">pmf_device_resume_subtree</code>, + <code class="Nm">pmf_class_network_register</code>, + <code class="Nm">pmf_class_input_register</code>, + <code class="Nm">pmf_class_display_register</code>, + <code class="Nm">pmf_system_suspend</code>, + <code class="Nm">pmf_system_resume</code>, + <code class="Nm">pmf_system_shutdown</code>, + <code class="Nm">pmf_event_register</code>, + <code class="Nm">pmf_event_deregister</code>, + <code class="Nm">pmf_event_inject</code>, + <code class="Nm">pmf_set_platform</code>, + <code class="Nm">pmf_get_platform</code> — <span class="Nd">power + management and inter-driver messaging 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/device.h</a>></code></p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_device_register</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">bool + (*suspend)(device_t dev, const pmf_qual_t *qual)</var>, + <var class="Fa" style="white-space: nowrap;">bool (*resume)(device_t dev, + const pmf_qual_t *qual)</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_device_register1</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">bool + (*suspend)(device_t dev, const pmf_qual_t *qual)</var>, + <var class="Fa" style="white-space: nowrap;">bool (*resume)(device_t dev, + const pmf_qual_t *qual)</var>, + <var class="Fa" style="white-space: nowrap;">bool (*shutdown)(device_t dev, + int how)</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pmf_device_deregister</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_device_suspend</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">const pmf_qual_t + *qual</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_device_resume</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">const pmf_qual_t + *qual</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_device_recursive_suspend</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">const pmf_qual_t + *qual</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_device_recursive_resume</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">const pmf_qual_t + *qual</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_device_subtree_resume</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">const pmf_qual_t + *qual</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pmf_class_network_register</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">struct ifnet + *ifp</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_class_input_register</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_class_display_register</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_system_suspend</code>(<var class="Fa" style="white-space: nowrap;">const + pmf_qual_t *qual</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_system_resume</code>(<var class="Fa" style="white-space: nowrap;">const + pmf_qual_t *qual</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pmf_system_shutdown</code>(<var class="Fa" style="white-space: nowrap;">int</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_event_register</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">pmf_generic_event_t + ev</var>, <var class="Fa" style="white-space: nowrap;">void + (*handler)(device_t dev)</var>, + <var class="Fa" style="white-space: nowrap;">bool global</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pmf_event_deregister</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">pmf_generic_event_t + ev</var>, <var class="Fa" style="white-space: nowrap;">void + (*handler)(device_t dev)</var>, + <var class="Fa" style="white-space: nowrap;">bool global</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_event_inject</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">pmf_generic_event_t + ev</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">pmf_set_platform</code>(<var class="Fa" style="white-space: nowrap;">const + char *key</var>, <var class="Fa" style="white-space: nowrap;">const char + *value</var>);</p> +<p class="Pp"><var class="Ft">const char *</var> + <br/> + <code class="Fn">pmf_get_platform</code>(<var class="Fa" style="white-space: nowrap;">const + char *key</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The machine-independent <code class="Nm">PMF</code> framework + provides power management and inter-driver messaging support for device + drivers.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DATA_TYPES"><a class="permalink" href="#DATA_TYPES">DATA + TYPES</a></h1> +<p class="Pp">Drivers for devices implementing <code class="Nm">PMF</code> may + make use of the following data type:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">pmf_qual_t</var></dt> + <dd>An opaque aggregate of qualifications on a <code class="Nm">PMF</code> + suspend or resume call.</dd> + <dt><var class="Fa">pmf_generic_event_t</var></dt> + <dd>A device driver can register as a listener for specific events, or inject + events into the message queue. The following message types are defined: + <ul class="Bl-item Bd-indent Bl-compact"> + <li id="PMFE_DISPLAY_ON"><a class="permalink" href="#PMFE_DISPLAY_ON"><code class="Dv">PMFE_DISPLAY_ON</code></a></li> + <li id="PMFE_DISPLAY_REDUCED"><a class="permalink" href="#PMFE_DISPLAY_REDUCED"><code class="Dv">PMFE_DISPLAY_REDUCED</code></a></li> + <li id="PMFE_DISPLAY_STANDBY"><a class="permalink" href="#PMFE_DISPLAY_STANDBY"><code class="Dv">PMFE_DISPLAY_STANDBY</code></a></li> + <li id="PMFE_DISPLAY_SUSPEND"><a class="permalink" href="#PMFE_DISPLAY_SUSPEND"><code class="Dv">PMFE_DISPLAY_SUSPEND</code></a></li> + <li id="PMFE_DISPLAY_OFF"><a class="permalink" href="#PMFE_DISPLAY_OFF"><code class="Dv">PMFE_DISPLAY_OFF</code></a></li> + <li id="PMFE_DISPLAY_BRIGHTNESS_UP"><a class="permalink" href="#PMFE_DISPLAY_BRIGHTNESS_UP"><code class="Dv">PMFE_DISPLAY_BRIGHTNESS_UP</code></a></li> + <li id="PMFE_DISPLAY_BRIGHTNESS_DOWN"><a class="permalink" href="#PMFE_DISPLAY_BRIGHTNESS_DOWN"><code class="Dv">PMFE_DISPLAY_BRIGHTNESS_DOWN</code></a></li> + <li id="PMFE_AUDIO_VOLUME_UP"><a class="permalink" href="#PMFE_AUDIO_VOLUME_UP"><code class="Dv">PMFE_AUDIO_VOLUME_UP</code></a></li> + <li id="PMFE_AUDIO_VOLUME_DOWN"><a class="permalink" href="#PMFE_AUDIO_VOLUME_DOWN"><code class="Dv">PMFE_AUDIO_VOLUME_DOWN</code></a></li> + <li id="PMFE_AUDIO_VOLUME_TOGGLE"><a class="permalink" href="#PMFE_AUDIO_VOLUME_TOGGLE"><code class="Dv">PMFE_AUDIO_VOLUME_TOGGLE</code></a></li> + <li id="PMFE_CHASSIS_LID_CLOSE"><a class="permalink" href="#PMFE_CHASSIS_LID_CLOSE"><code class="Dv">PMFE_CHASSIS_LID_CLOSE</code></a></li> + <li id="PMFE_CHASSIS_LID_OPEN"><a class="permalink" href="#PMFE_CHASSIS_LID_OPEN"><code class="Dv">PMFE_CHASSIS_LID_OPEN</code></a></li> + </ul> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="pmf_device_register"><a class="permalink" href="#pmf_device_register"><code class="Fn">pmf_device_register</code></a>(<var class="Fa">dev</var>, + <var class="Fa">suspend</var>, <var class="Fa">resume</var>)</dt> + <dd>Register a device with the power management framework. The + <var class="Fa">suspend</var> and <var class="Fa">resume</var> functions + are passed <var class="Fa">dev</var> and a + <var class="Fa">pmf_qual_t</var>, and will be called when the system state + changes; they should return <code class="Dv">true</code> on success and + <code class="Dv">false</code> on failure. If either + <var class="Fa">suspend</var> or <var class="Fa">resume</var> is + <code class="Dv">NULL</code> then it is assumed that device state does not + need to be captured and resumed on a power transition. Bus and class-level + power management will still be performed. + <p class="Pp" id="pmf_device_register~2"><a class="permalink" href="#pmf_device_register~2"><code class="Fn">pmf_device_register</code></a>() + always returns true. Callers should ignore the return value.</p> + </dd> + <dt id="pmf_system_shutdown"><code class="Fn">pmf_device_register1</code>(<var class="Fa">dev</var>, + <var class="Fa">suspend</var>, <var class="Fa">resume</var>, + <var class="Fa">shutdown</var>)</dt> + <dd>Like <code class="Fn">pmf_device_register</code>(), but additionally + registers a shutdown handler. During system shutdown, + <a class="permalink" href="#pmf_system_shutdown"><code class="Fn">pmf_system_shutdown</code></a>() + calls <var class="Fa">shutdown</var> on <var class="Fa">dev</var> with the + <a class="Xr">reboot(2)</a> “howto” in the second argument. + <var class="Fa">shutdown</var> should return <code class="Dv">true</code> + on success and <code class="Dv">false</code> on failure. + <p class="Pp" id="pmf_device_register1"><a class="permalink" href="#pmf_device_register1"><code class="Fn">pmf_device_register1</code></a>() + always returns true. Callers should ignore the return value.</p> + </dd> + <dt id="pmf_device_deregister"><a class="permalink" href="#pmf_device_deregister"><code class="Fn">pmf_device_deregister</code></a>(<var class="Fa">dev</var>)</dt> + <dd>Deregister a device with the power management framework.</dd> + <dt id="pmf_device_suspend"><a class="permalink" href="#pmf_device_suspend"><code class="Fn">pmf_device_suspend</code></a>(<var class="Fa">dev</var>, + <var class="Fa">qual</var>)</dt> + <dd>Suspend a device by first calling the class suspend handler, followed by + the driver suspend handler, and finally the bus suspend handler.</dd> + <dt id="pmf_device_resume"><a class="permalink" href="#pmf_device_resume"><code class="Fn">pmf_device_resume</code></a>(<var class="Fa">dev</var>, + <var class="Fa">qual</var>)</dt> + <dd>Resume a device by first calling the bus resume handler, followed by the + driver resume handler, and finally the class resume handler.</dd> + <dt id="pmf_device_recursive_suspend"><a class="permalink" href="#pmf_device_recursive_suspend"><code class="Fn">pmf_device_recursive_suspend</code></a>(<var class="Fa">dev</var>, + <var class="Fa">qual</var>)</dt> + <dd>As <code class="Fn">pmf_device_suspend</code>(), but ensures that all + child devices of <var class="Fa">dev</var> are suspended.</dd> + <dt id="pmf_device_recursive_resume"><a class="permalink" href="#pmf_device_recursive_resume"><code class="Fn">pmf_device_recursive_resume</code></a>(<var class="Fa">dev</var>, + <var class="Fa">qual</var>)</dt> + <dd>As <code class="Fn">pmf_device_resume</code>(), but ensures that all + parent devices of <var class="Fa">dev</var> are resumed.</dd> + <dt id="pmf_device_subtree_resume"><a class="permalink" href="#pmf_device_subtree_resume"><code class="Fn">pmf_device_subtree_resume</code></a>(<var class="Fa">dev</var>, + <var class="Fa">qual</var>)</dt> + <dd>As <code class="Fn">pmf_device_resume</code>(), but ensures that all child + devices of <var class="Fa">dev</var> are resumed.</dd> + <dt id="pmf_class_network_register"><a class="permalink" href="#pmf_class_network_register"><code class="Fn">pmf_class_network_register</code></a>(<var class="Fa">dev</var>, + <var class="Fa">ifp</var>)</dt> + <dd>Register a device with the power management framework as a network-class + device.</dd> + <dt id="pmf_class_input_register"><a class="permalink" href="#pmf_class_input_register"><code class="Fn">pmf_class_input_register</code></a>(<var class="Fa">dev</var>)</dt> + <dd>Register a device with the power management framework as an input-class + device.</dd> + <dt id="pmf_class_display_register"><a class="permalink" href="#pmf_class_display_register"><code class="Fn">pmf_class_display_register</code></a>(<var class="Fa">dev</var>)</dt> + <dd>Register a device with the power management framework as a display-class + device.</dd> + <dt id="pmf_system_suspend"><a class="permalink" href="#pmf_system_suspend"><code class="Fn">pmf_system_suspend</code></a>(<var class="Fa">qual</var>)</dt> + <dd>Suspend all attached devices. Devices are suspended by traversing the + autoconfiguration tree beginning with the leaf nodes. This function will + fail if any attached drivers do not support the power management + framework.</dd> + <dt id="pmf_system_resume"><a class="permalink" href="#pmf_system_resume"><code class="Fn">pmf_system_resume</code></a>(<var class="Fa">qual</var>)</dt> + <dd>Resume all attached devices. Devices are resumed by traversing the + autoconfiguration tree beginning with devices that do not have a parent. + This function will fail if any attached drivers do not support the power + management framework.</dd> + <dt><code class="Fn">pmf_system_shutdown</code>(<var class="Fa">int</var>)</dt> + <dd>Shutdown all attached devices. Devices are shut down by traversing the + autoconfiguration tree beginning with the leaf nodes. The integer argument + is passed to the driver shutdown functions. It should contain the + <a class="Xr">reboot(2)</a> “howto” argument. This function + ignores the presence of attached drivers that do not support the power + management framework.</dd> + <dt id="pmf_event_register"><a class="permalink" href="#pmf_event_register"><code class="Fn">pmf_event_register</code></a>(<var class="Fa">dev</var>, + <var class="Fa">ev</var>, <var class="Fa">handler</var>, + <var class="Fa">global</var>)</dt> + <dd>Register the callback <var class="Fa">handler</var> to be called whenever + an <var class="Fa">ev</var> event is triggered. If + <var class="Fa">global</var> is <code class="Dv">true</code>, + <var class="Fa">handler</var> accepts anonymous events from + <a class="permalink" href="#pmf_event_inject"><code class="Fn" id="pmf_event_inject">pmf_event_inject</code></a>().</dd> + <dt id="pmf_event_deregister"><a class="permalink" href="#pmf_event_deregister"><code class="Fn">pmf_event_deregister</code></a>(<var class="Fa">dev</var>, + <var class="Fa">ev</var>, <var class="Fa">handler</var>, + <var class="Fa">global</var>)</dt> + <dd>Deregister the callback previously registered with + <code class="Fn">pmf_event_register</code>().</dd> + <dt><code class="Fn">pmf_event_inject</code>(<var class="Fa">dev</var>, + <var class="Fa">ev</var>)</dt> + <dd>Inject an inter-driver message into the message queue. If + <var class="Fa">dev</var> is <code class="Dv">NULL</code>, the event is + considered to be anonymous and one or more drivers may handle this event, + otherwise the event is delivered directly to the callback registered by + <var class="Fa">dev</var>.</dd> + <dt id="pmf_set_platform"><a class="permalink" href="#pmf_set_platform"><code class="Fn">pmf_set_platform</code></a>(<var class="Fa">key</var>, + <var class="Fa">value</var>)</dt> + <dd>Insert a name-value pair into the platform information database.</dd> + <dt id="pmf_get_platform"><a class="permalink" href="#pmf_get_platform"><code class="Fn">pmf_get_platform</code></a>(<var class="Fa">key</var>)</dt> + <dd>Retrieve the value for <var class="Fa">key</var> from the platform + information database. Returns <code class="Dv">NULL</code> if the key is + not present.</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 power management framework is implemented within the files + <span class="Pa">sys/sys/pmf.h</span>, + <span class="Pa">sys/sys/device.h</span>, + <span class="Pa">sys/kern/kern_pmf.c</span>, and + <span class="Pa">sys/kern/subr_autoconf.c</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">autoconf(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">The <code class="Nm">PMF</code> framework appeared in + <span class="Ux">NetBSD 5.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Jared D. McNeill</span> + <<a class="Mt" href="mailto:jmcneill@NetBSD.org">jmcneill@NetBSD.org</a>> + <br/> + <span class="An">Joerg Sonnenberger</span> + <<a class="Mt" href="mailto:joerg@NetBSD.org">joerg@NetBSD.org</a>></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp"><code class="Fn">pmf_device_register</code>() and + <code class="Fn">pmf_device_register1</code>() never fail and should return + void, but until all callers are updated to ignore the return value, they + must continue to return bool: + <a class="Lk" href="https://gnats.NetBSD.org/57575">PR kern/57575</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 9, 2024</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/proc_find.9 3.html b/static/netbsd/man9/proc_find.9 3.html new file mode 100644 index 00000000..7f11e854 --- /dev/null +++ b/static/netbsd/man9/proc_find.9 3.html @@ -0,0 +1,59 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PROC_FIND(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PROC_FIND(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">proc_find</code>, + <code class="Nm">pgrp_find</code> — <span class="Nd">find process or + process group</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/proc.h</a>></code></p> +<p class="Pp"><var class="Ft">struct proc *</var> + <br/> + <code class="Fn">proc_find</code>(<var class="Fa" style="white-space: nowrap;">pid_t + pid</var>);</p> +<p class="Pp"><var class="Ft">struct pgrp *</var> + <br/> + <code class="Fn">pgrp_find</code>(<var class="Fa" style="white-space: nowrap;">pid_t + pgid</var>);</p> +<p class="Pp"><var class="Va">extern kmutex_t *proc_lock;</var></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#proc_find"><code class="Fn" id="proc_find">proc_find</code></a>() + and + <a class="permalink" href="#pgrp_find"><code class="Fn" id="pgrp_find">pgrp_find</code></a>() + functions retrieve process and process group structures from process ID + <var class="Fa">pid</var> and process group ID <var class="Fa">pgid</var>. + Both functions must be called by holding a <a class="Xr">mutex(9)</a> on + <var class="Va">proc_lock</var>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">Upon successful completion, the described functions return a + pointer to either <i class="Em">struct proc</i> or <i class="Em">struct + pgrp</i>. Otherwise, if the requested ID was not found, + <code class="Dv">NULL</code> is returned.</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">curproc(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 1, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/prop_copyin_ioctl.9 b/static/netbsd/man9/prop_copyin_ioctl.9 new file mode 100644 index 00000000..60e56940 --- /dev/null +++ b/static/netbsd/man9/prop_copyin_ioctl.9 @@ -0,0 +1,222 @@ +.\" $NetBSD: prop_copyin_ioctl.9,v 1.16 2025/04/23 02:58:52 thorpej Exp $ +.\" +.\" Copyright (c) 2006, 2009, 2025 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe. +.\" +.\" 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 April 20, 2025 +.Dt PROP_COPYIN_IOCTL 9 +.Os +.Sh NAME +.Nm prop_object_copyin , +.Nm prop_object_copyin_size , +.Nm prop_object_copyin_ioctl , +.Nm prop_object_copyin_ioctl_size , +.Nm prop_object_copyout , +.Nm prop_object_copyout_ioctl +.Nd Copy property lists to and from kernel space +.Sh SYNOPSIS +.In prop/proplib.h +.Ft int +.Fn prop_object_copyin "const struct plistref *pref" \ + "prop_object_t *arrayp" +.Ft int +.Fn prop_object_copyin_size "const struct plistref *pref" \ + "prop_object_t *arrayp" "size_t lim" +.Ft int +.Fn prop_object_copyin_ioctl "const struct plistref *pref" \ + "const u_long cmd" "prop_object_t *arrayp" +.Ft int +.Fn prop_object_copyin_ioctl_size "const struct plistref *pref" \ + "const u_long cmd" "prop_object_t *arrayp" "size_t lim" +.Ft int +.Fn prop_object_copyout "struct plistref *pref" \ + "prop_object_t array" +.Ft int +.Fn prop_object_copyout_ioctl "struct plistref *pref" \ + "const u_long cmd" "prop_object_t array" +.Sh DESCRIPTION +The +.Nm prop_object_copyin_ioctl , +.Nm prop_object_copyin_ioctl_size , +and +.Nm prop_object_copyout_ioctl +functions implement the kernel side of a protocol for copying property lists +to and from the kernel using +.Xr ioctl 2 . +The functions +.Nm prop_object_copyin , +.Nm prop_object_copyin_size , +and +.Nm prop_object_copyout +implement the kernel side of a protocol for copying property lists to the +kernel as arguments of normal system calls. +.Pp +A kernel routine receiving or returning a property list will be passed a +pointer to a +.Vt struct plistref . +This structure encapsulates the reference to the property list in externalized +form. +.Pp +The functions +.Nm prop_object_copyin_size +and +.Nm prop_object_copyin_ioctl_size +take an explicit size limit argument +.Ar lim +while +.Nm prop_object_copyin +and +.Nm prop_object_copyin_ioctl +have an implicit size limit of 128KB. +Attempts to transfer objects larger than the limit result in an +.Er E2BIG +return value. +.Pp +The functions +.Fn prop_array_copyin , +.Fn prop_array_copyin_size , +.Fn prop_array_copyin_ioctl , +.Fn prop_array_copyin_ioctl_size , +.Fn prop_dictionary_copyin , +.Fn prop_dictionary_copyin_size , +.Fn prop_dictionary_copyin_ioctl , +and +.Fn prop_dictionary_copyin_ioctl_size +are provided as wrappers around the corresponding generic object +functions. +They are provided for backwards compatibility and will fail if the +object copied in is not of the specified type, preserving the previous +behavior. +.Pp +The functions +.Fn prop_array_copyout , +.Fn prop_array_copyout_ioctl , +.Fn prop_dictionary_copyout , +and +.Fn prop_dictionary_copyout_ioctl +are also provided as backwards compatibility wrappers around the +corresponding generic object functions, but impose no object type +constraints. +.Sh RETURN VALUES +If successful, functions return zero. +Otherwise, an error number will be returned to indicate the error. +.Sh EXAMPLES +The following +.Pq simplified +example demonstrates using +.Fn prop_object_copyin_ioctl +and +.Fn prop_object_copyout_ioctl +in an ioctl routine: +.Bd -literal +extern prop_dictionary_t fooprops; + +int +fooioctl(dev_t dev, u_long cmd, caddr_t data, int flag, struct lwp *l) +{ + prop_dictionary_t dict, odict; + int error; + + switch (cmd) { + case FOOSETPROPS: { + const struct plistref *pref = (const struct plistref *) data; + error = prop_object_copyin_ioctl(pref, cmd, + (prop_object_t *)\*[Am]dict); + if (error) + return (error); + odict = fooprops; + fooprops = dict; + prop_object_release(odict); + break; + } + + case FOOGETPROPS: { + struct plistref *pref = (struct plistref *) data; + error = prop_object_copyout_ioctl(pref, cmd, fooprops); + break; + } + + default: + return (EPASSTHROUGH); + } + return (error); +} +.Ed +.Pp +The following +.Pq simplified +example demonstrates using +.Fn prop_object_copyin +in a routine: +.Bd -literal +int +foocopyin(const struct plistref *pref)) +{ + prop_array_t array; + int error; + + error = prop_object_copyin(pref, (prop_object_t *)\*[Am]array); + if (error) + return (error); + ... +} +.Ed +.Sh ERRORS +.Fn prop_object_copyin_ioctl +will fail if: +.Bl -tag -width Er +.It Bq Er E2BIG +The object being copied is larger than an arbitrarily established limit +(currently set to 128Kbytes). +.It Bq Er EFAULT +Bad address +.It Bq Er EIO +Input/output error +.It Bq Er ENOMEM +Cannot allocate memory +.El +.Pp +.Fn prop_object_copyout_ioctl +will fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +Bad address +.It Bq Er ENOMEM +Cannot allocate memory +.El +.Sh SEE ALSO +.Xr prop_array 3 , +.Xr prop_dictionary 3 , +.Xr prop_object 3 , +.Xr prop_send_ioctl 3 , +.Xr prop_send_syscall 3 , +.Xr proplib 3 +.Sh HISTORY +The +.Nm proplib +property container object library first appeared in +.Nx 4.0 . diff --git a/static/netbsd/man9/pserialize.9 3.html b/static/netbsd/man9/pserialize.9 3.html new file mode 100644 index 00000000..151a711b --- /dev/null +++ b/static/netbsd/man9/pserialize.9 3.html @@ -0,0 +1,185 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PSERIALIZE(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PSERIALIZE(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">pserialize</code> — + <span class="Nd">passive serialization mechanism</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/pserialize.h</a>></code></p> +<p class="Pp"><var class="Ft">pserialize_t</var> + <br/> + <code class="Fn">pserialize_create</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pserialize_destroy</code>(<var class="Fa" style="white-space: nowrap;">pserialize_t + psz</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">pserialize_read_enter</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pserialize_read_exit</code>(<var class="Fa" style="white-space: nowrap;">int + s</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pserialize_perform</code>(<var class="Fa" style="white-space: nowrap;">pserialize_t + psz</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Passive serialization is a reader / writer synchronisation + mechanism designed for lock-less read operations. The read operations may + happen from software interrupt at <code class="Dv">IPL_SOFTCLOCK</code>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="pserialize_create"><a class="permalink" href="#pserialize_create"><code class="Fn">pserialize_create</code></a>()</dt> + <dd>Allocate a new synchronisation object.</dd> + <dt id="pserialize_destroy"><a class="permalink" href="#pserialize_destroy"><code class="Fn">pserialize_destroy</code></a>()</dt> + <dd>Destroy the synchronisation object. No synchronisation activity should + happen at this point.</dd> + <dt id="pserialize_read_enter"><a class="permalink" href="#pserialize_read_enter"><code class="Fn">pserialize_read_enter</code></a>()</dt> + <dd>Enter the critical path of the reader side. Returns an IPL value, which + must be passed to <a class="Xr">pserialize_read_exit(9)</a>. Protected + code path is not allowed to block.</dd> + <dt id="pserialize_read_exit"><a class="permalink" href="#pserialize_read_exit"><code class="Fn">pserialize_read_exit</code></a>()</dt> + <dd>Exit the critical path of the reader side. Takes the IPL value returned by + <a class="Xr">pserialize_read_enter(9)</a>.</dd> + <dt id="pserialize_perform"><a class="permalink" href="#pserialize_perform"><code class="Fn">pserialize_perform</code></a>()</dt> + <dd>Perform the passive serialization on the writer side. Passing of this + function ensures that no readers are in action. Writers are typically + additionally serialized with a separate mechanism, e.g. + <a class="Xr">mutex(9)</a>, to remove objects used by readers from a + published list. Operation blocks and it may only be performed from thread + context.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">Given a global database of frotz records:</p> +<div class="Bd Pp Li"> +<pre> struct frotz { + ... + struct frotz *f_next; + }; + + static struct { + kmutex_t lock; + pserialize_t psz; + struct frotz *first; + } frobbotzim __cacheline_aligned;</pre> +</div> +<p class="Pp">Create a frotz and publish it, as a writer:</p> +<div class="Bd Pp Li"> +<pre> struct frotz *f = pool_get(&frotz_pool, PR_WAITOK); + + /* Initialize f. */ + ... + + mutex_enter(&frobbotzim.lock); + f->f_next = frobbotzim.first; + /* + * Publish the contents of f->f_next before we publish the + * pointer to f in frobbotzim.first. + */ + atomic_store_release(&frobbotzim.first, f); + mutex_exit(&frobbotzim.lock);</pre> +</div> +<p class="Pp">Find a frotz, as a reader:</p> +<div class="Bd Pp Li"> +<pre> struct frotz *f; + int error = ENOENT; + int s; + + s = pserialize_read_enter(); + /* Fetch frobbotzim.first before we fetch anything it point to. */ + for (f = atomic_load_consume(&frobbotzim.first); + f != NULL; + f = f->f_next) { + if (f->f_... == key) { + /* + * Grab whatever part of the frotz we need. + * Note that we can't use the frotz after + * pserialize_read_exit, without a stronger + * kind of reference, say a reference count + * managed by atomic_ops(3). + */ + *resultp = f->f_...; + error = 0; + break; + } + } + pserialize_read_exit(s); + + return error;</pre> +</div> +<p class="Pp">Remove a frotz, as a writer, and free it once there are no more + readers:</p> +<div class="Bd Pp Li"> +<pre> struct frotz **fp, *f; + + mutex_enter(&frobbotzim.lock); + for (fp = &frobbotzim.first; (f = *fp) != NULL; fp = &f->f_next) { + if (f->f_... == key) { + /* + * Unhook it from the list. Readers may still + * be traversing the list at this point, so + * the next pointer must remain valid and + * memory must remain allocated. + */ + *fp = f->f_next; + break; + } + } + mutex_exit(&frobbotzim.lock); + + /* + * Wait for all existing readers to complete. New readers will + * not see f because the list no longer points to it. + */ + pserialize_perform(frobbotzim.psz); + + /* Now nobody else can be touching f, so it is safe to free. */ + if (f != NULL) + pool_put(&frotz_pool, f);</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">pserialize</code> is implemented within the + file <span class="Pa">sys/kern/subr_pserialize.c</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">membar_ops(3)</a>, <a class="Xr">condvar(9)</a>, + <a class="Xr">mutex(9)</a>, <a class="Xr">rwlock(9)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Hennessy, et al.</span>, + <span class="RsT">Passive serialization in a multitasking + environment</span>, <i class="RsI">US Patent and Trademark Office</i>, + <span class="RsN">US Patent 4809168</span>, <span class="RsD">February 28, + 1989</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">Passive serialization mechanism first appeared in + <span class="Ux">NetBSD 6.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 26, 2016</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/pslist.9 3.html b/static/netbsd/man9/pslist.9 3.html new file mode 100644 index 00000000..9aa95f84 --- /dev/null +++ b/static/netbsd/man9/pslist.9 3.html @@ -0,0 +1,386 @@ +<table class="head"> + <tr> + <td class="head-ltitle">PSLIST(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">PSLIST(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">pslist</code> — + <span class="Nd">pserialize-safe linked lists</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/pslist.h</a>></code></p> +<p class="Pp"><var class="Vt">struct pslist_head head <span class="No">=</span> + <code class="Dv">PSLIST_INITIALIZER</code></var>; + <br/> + <var class="Vt">struct pslist_entry entry <span class="No">=</span> + <code class="Dv">PSLIST_ENTRY_INITIALIZER</code></var>;</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_INIT</code>(<var class="Fa" style="white-space: nowrap;">struct + pslist_head *head</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_DESTROY</code>(<var class="Fa" style="white-space: nowrap;">struct + pslist_head *head</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_ENTRY_INIT</code>(<var class="Fa" style="white-space: nowrap;">TYPE + *element</var>, <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY + NAME</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_ENTRY_DESTROY</code>(<var class="Fa" style="white-space: nowrap;">TYPE + *element</var>, <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY + NAME</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_WRITER_INSERT_HEAD</code>(<var class="Fa" style="white-space: nowrap;">struct + pslist_head *head</var>, <var class="Fa" style="white-space: nowrap;">TYPE + *new</var>, <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY + NAME</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_WRITER_INSERT_BEFORE</code>(<var class="Fa" style="white-space: nowrap;">TYPE + *element</var>, <var class="Fa" style="white-space: nowrap;">TYPE + *new</var>, <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY + NAME</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_WRITER_INSERT_AFTER</code>(<var class="Fa" style="white-space: nowrap;">TYPE + *element</var>, <var class="Fa" style="white-space: nowrap;">TYPE + *new</var>, <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY + NAME</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">PSLIST_WRITER_REMOVE</code>(<var class="Fa" style="white-space: nowrap;">TYPE + *element</var>, <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY + NAME</var>);</p> +<p class="Pp"><var class="Ft">TYPE *</var> + <br/> + <code class="Fn">PSLIST_WRITER_FIRST</code>(<var class="Fa" style="white-space: nowrap;">const + struct pslist *head</var>, + <var class="Fa" style="white-space: nowrap;">TYPE</var>, + <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY NAME</var>);</p> +<p class="Pp"><var class="Ft">TYPE *</var> + <br/> + <code class="Fn">PSLIST_WRITER_NEXT</code>(<var class="Fa" style="white-space: nowrap;">const + TYPE *element</var>, + <var class="Fa" style="white-space: nowrap;">TYPE</var>, + <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY NAME</var>);</p> +<p class="Pp"><code class="Fn">PSLIST_WRITER_FOREACH</code>(<var class="Fa" style="white-space: nowrap;">const + TYPE *element</var>, <var class="Fa" style="white-space: nowrap;">const + struct pslist_head *head</var>, + <var class="Fa" style="white-space: nowrap;">TYPE</var>, + <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY NAME</var>);</p> +<p class="Pp"><var class="Ft">TYPE *</var> + <br/> + <code class="Fn">PSLIST_READER_FIRST</code>(<var class="Fa" style="white-space: nowrap;">const + struct pslist *head</var>, + <var class="Fa" style="white-space: nowrap;">TYPE</var>, + <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY NAME</var>);</p> +<p class="Pp"><var class="Ft">TYPE *</var> + <br/> + <code class="Fn">PSLIST_READER_NEXT</code>(<var class="Fa" style="white-space: nowrap;">const + TYPE *element</var>, + <var class="Fa" style="white-space: nowrap;">TYPE</var>, + <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY NAME</var>);</p> +<p class="Pp"><code class="Fn">PSLIST_READER_FOREACH</code>(<var class="Fa" style="white-space: nowrap;">const + TYPE *element</var>, <var class="Fa" style="white-space: nowrap;">const + struct pslist_head *head</var>, + <var class="Fa" style="white-space: nowrap;">TYPE</var>, + <var class="Fa" style="white-space: nowrap;">PSLIST_ENTRY NAME</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">pslist</code> data structure is a linked list + like <code class="Nm">list</code> in <a class="Xr">queue(3)</a>. It is + augmented with memory barriers so that any number of readers can safely run + in parallel with at most one writer, without needing any interprocessor + synchronization such as locks or atomics on the reader side.</p> +<p class="Pp" id="PSLIST_INIT">The head of a linked list is represented by a + <var class="Vt">struct pslist_head</var> object allocated by the caller, + e.g. by embedding it in another struct, which should be otherwise treated as + opaque. A linked list head must be initialized with + <code class="Dv">PSLIST_INITIALIZER</code> or + <a class="permalink" href="#PSLIST_INIT"><code class="Fn">PSLIST_INIT</code></a>() + before it may be used. When initialized, a list head represents an empty + list. A list should be empty and destroyed with + <a class="permalink" href="#PSLIST_DESTROY"><code class="Fn" id="PSLIST_DESTROY">PSLIST_DESTROY</code></a>() + before the <var class="Vt">struct pslist_head</var> object's memory is + reused.</p> +<p class="Pp" id="element">Each entry in a linked list is represented by a + <var class="Vt">struct pslist_entry</var> object, also opaque, and embedded + as a member in a caller-allocated structure called an + <a class="permalink" href="#element"><i class="Em">element</i></a>. A + <var class="Vt">struct pslist_entry</var> object must be initialized with + <code class="Dv">PSLIST_ENTRY_INITIALIZER</code> or + <a class="permalink" href="#PSLIST_ENTRY_INIT"><code class="Fn" id="PSLIST_ENTRY_INIT">PSLIST_ENTRY_INIT</code></a>() + before it may be used.</p> +<p class="Pp" id="PSLIST_ENTRY_DESTROY">When initialized, a list entry is + unassociated. Inserting an entry associates it with a particular list. + Removing it partially disassociates it from that list and prevents new + readers from finding it in the list, but allows extant parallel readers to + continue reading the next entry. The caller must then wait, e.g. with + <a class="Xr">pserialize_perform(9)</a>, for all extant parallel readers to + finish, before destroying the list entry with + <a class="permalink" href="#PSLIST_ENTRY_DESTROY"><code class="Fn">PSLIST_ENTRY_DESTROY</code></a>() + and then freeing or reusing its memory.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXCLUSIVE_OPERATIONS"><a class="permalink" href="#EXCLUSIVE_OPERATIONS">EXCLUSIVE + OPERATIONS</a></h1> +<p class="Pp">The following operations may be performed on list heads and + entries when the caller has exclusive access to them — no parallel + writers or readers may have access to the same objects.</p> +<dl class="Bl-tag"> + <dt id="PSLIST_INITIALIZER"><a class="permalink" href="#PSLIST_INITIALIZER"><code class="Dv">PSLIST_INITIALIZER</code></a></dt> + <dd>Constant initializer for a <var class="Vt">struct pslist_head</var> + object.</dd> + <dt><code class="Fn">PSLIST_INIT</code>(<var class="Fa">head</var>)</dt> + <dd>Initialize the list headed by <var class="Fa">head</var> to be empty.</dd> + <dt><code class="Fn">PSLIST_DESTROY</code>(<var class="Fa">head</var>)</dt> + <dd>Destroy the list headed by <var class="Fa">head</var>, which must be + empty. + <p class="Pp">This has an effect only with the + <code class="Dv">DIAGNOSTIC</code> option, so it is not strictly + necessary, but it can help to detect bugs early; see + <a class="Xr">KASSERT(9)</a>.</p> + </dd> + <dt id="PSLIST_ENTRY_INITIALIZER"><a class="permalink" href="#PSLIST_ENTRY_INITIALIZER"><code class="Dv">PSLIST_ENTRY_INITIALIZER</code></a></dt> + <dd>Constant initializer for an unassociated <var class="Vt">struct + pslist_entry</var> object.</dd> + <dt id="PSLIST_ENTRY_INIT~2"><a class="permalink" href="#PSLIST_ENTRY_INIT~2"><code class="Fn">PSLIST_ENTRY_INIT</code></a>(<var class="Fa">element</var>, + <var class="Fa">NAME</var>)</dt> + <dd>Initialize the <var class="Vt">struct pslist_entry</var> object + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var>.</dd> + <dt><code class="Fn">PSLIST_ENTRY_DESTROY</code>(<var class="Fa">element</var>, + <var class="Fa">NAME</var>)</dt> + <dd>Destroy the <var class="Vt">struct pslist_entry</var> object + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var>. + Either <var class="Fa">element</var> must never have been inserted into a + list, or it must have been inserted and removed, and the caller must have + waited for all parallel readers to finish reading it first.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="WRITER_OPERATIONS"><a class="permalink" href="#WRITER_OPERATIONS">WRITER + OPERATIONS</a></h1> +<p class="Pp">The following operations may be performed on list heads and + entries when the caller has exclusive + <a class="permalink" href="#write"><i class="Em" id="write">write</i></a> + access to them — parallel readers for the same objects are allowed, + but no parallel writers.</p> +<dl class="Bl-tag"> + <dt id="PSLIST_WRITER_INSERT_HEAD"><a class="permalink" href="#PSLIST_WRITER_INSERT_HEAD"><code class="Fn">PSLIST_WRITER_INSERT_HEAD</code></a>(<var class="Fa">head</var>, + <var class="Fa">element</var>, <var class="Fa">NAME</var>)</dt> + <dd>Insert the element <var class="Fa">element</var> at the beginning of the + list headed by <var class="Fa">head</var>, before any existing elements in + the list. + <p class="Pp">The object + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var> + must be a <var class="Vt">struct pslist_entry</var> object which has + been initialized but not inserted.</p> + </dd> + <dt id="PSLIST_WRITER_INSERT_BEFORE"><a class="permalink" href="#PSLIST_WRITER_INSERT_BEFORE"><code class="Fn">PSLIST_WRITER_INSERT_BEFORE</code></a>(<var class="Fa">element</var>, + <var class="Fa">new</var>, <var class="Fa">NAME</var>)</dt> + <dd>Insert the element <var class="Fa">new</var> into a list before the + element <var class="Fa">element</var>. + <p class="Pp">The object + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var> + must be a <var class="Vt">struct pslist_entry</var> object which has + been inserted into a list. The object + <var class="Fa">new</var><code class="Li">-></code><var class="Fa">NAME</var> + must be a <var class="Vt">struct pslist_entry</var></p> + </dd> + <dt id="PSLIST_WRITER_INSERT_AFTER"><a class="permalink" href="#PSLIST_WRITER_INSERT_AFTER"><code class="Fn">PSLIST_WRITER_INSERT_AFTER</code></a>(<var class="Fa">element</var>, + <var class="Fa">new</var>, <var class="Fa">NAME</var>)</dt> + <dd>Insert the element <var class="Fa">new</var> into a list after the element + <var class="Fa">element</var>. + <p class="Pp">The object + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var> + must be a <var class="Vt">struct pslist_entry</var> object which has + been inserted into a list. The object + <var class="Fa">new</var><code class="Li">-></code><var class="Fa">NAME</var> + must be a <var class="Vt">struct pslist_entry</var></p> + </dd> + <dt id="PSLIST_WRITER_REMOVE"><a class="permalink" href="#PSLIST_WRITER_REMOVE"><code class="Fn">PSLIST_WRITER_REMOVE</code></a>(<var class="Fa">element</var>, + <var class="Fa">NAME</var>)</dt> + <dd>Remove the element <var class="Fa">element</var> from the list into which + it has been inserted. + <p class="Pp">The object + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var> + must be a <var class="Vt">struct pslist_entry</var> object which has + been inserted into a list.</p> + </dd> + <dt id="PSLIST_WRITER_FIRST"><a class="permalink" href="#PSLIST_WRITER_FIRST"><code class="Fn">PSLIST_WRITER_FIRST</code></a>(<var class="Fa">head</var>, + <var class="Fa">type</var>, <var class="Fa">NAME</var>)</dt> + <dd>Return a pointer to the first element <var class="Fa">o</var> of type + <var class="Fa">type</var> with a <var class="Vt">struct + pslist_entry</var> member + <var class="Fa">o</var><code class="Li">-></code><var class="Fa">NAME</var>, + or <code class="Dv">NULL</code> if the list is empty.</dd> + <dt id="PSLIST_WRITER_NEXT"><a class="permalink" href="#PSLIST_WRITER_NEXT"><code class="Fn">PSLIST_WRITER_NEXT</code></a>(<var class="Fa">element</var>, + <var class="Fa">type</var>, <var class="Fa">NAME</var>)</dt> + <dd>Return a pointer to the next element <var class="Fa">o</var> of type + <var class="Fa">type</var> with a <var class="Vt">struct + pslist_entry</var> member + <var class="Fa">o</var><code class="Li">-></code><var class="Fa">NAME</var> + after <var class="Fa">element</var> in a list, or + <code class="Dv">NULL</code> if there are no elements after + <var class="Fa">element</var>.</dd> + <dt id="PSLIST_WRITER_FOREACH"><a class="permalink" href="#PSLIST_WRITER_FOREACH"><code class="Fn">PSLIST_WRITER_FOREACH</code></a>(<var class="Fa">element</var>, + <var class="Fa">head</var>, <var class="Fa">type</var>, + <var class="Fa">NAME</var>)</dt> + <dd>Loop header for iterating over each element <var class="Fa">element</var> + of type <var class="Fa">type</var> with <var class="Vt">struct + pslist_entry</var> member + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var> + starting at the list head <var class="Fa">head</var>. + <p class="Pp">The caller must not modify the list while iterating over + it.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="READER_OPERATIONS"><a class="permalink" href="#READER_OPERATIONS">READER + OPERATIONS</a></h1> +<p class="Pp">The following operations may be performed on list heads and + entries when the caller is in a passively serialized read section — + see <a class="Xr">pserialize(9)</a>.</p> +<dl class="Bl-tag"> + <dt id="PSLIST_READER_FIRST"><a class="permalink" href="#PSLIST_READER_FIRST"><code class="Fn">PSLIST_READER_FIRST</code></a>(<var class="Fa">head</var>, + <var class="Fa">type</var>, <var class="Fa">NAME</var>)</dt> + <dd>Return a pointer to the first element <var class="Fa">o</var> of type + <var class="Fa">type</var> with a <var class="Vt">struct + pslist_entry</var> member + <var class="Fa">o</var><code class="Li">-></code><var class="Fa">NAME</var>, + or <code class="Dv">NULL</code> if the list is empty.</dd> + <dt id="PSLIST_READER_NEXT"><a class="permalink" href="#PSLIST_READER_NEXT"><code class="Fn">PSLIST_READER_NEXT</code></a>(<var class="Fa">element</var>, + <var class="Fa">type</var>, <var class="Fa">NAME</var>)</dt> + <dd>Return a pointer to the next element <var class="Fa">o</var> of type + <var class="Fa">type</var> with a <var class="Vt">struct + pslist_entry</var> member + <var class="Fa">o</var><code class="Li">-></code><var class="Fa">NAME</var> + after <var class="Fa">element</var> in a list, or + <code class="Dv">NULL</code> if there are no elements after + <var class="Fa">element</var>.</dd> + <dt id="PSLIST_READER_FOREACH"><a class="permalink" href="#PSLIST_READER_FOREACH"><code class="Fn">PSLIST_READER_FOREACH</code></a>(<var class="Fa">element</var>, + <var class="Fa">head</var>, <var class="Fa">type</var>, + <var class="Fa">NAME</var>)</dt> + <dd>Loop header for iterating over each element <var class="Fa">element</var> + of type <var class="Fa">type</var> with <var class="Vt">struct + pslist_entry</var> member + <var class="Fa">element</var><code class="Li">-></code><var class="Fa">NAME</var> + starting at the list head <var class="Fa">head</var>.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">Example frotz structure and global state:</p> +<div class="Bd Pp Li"> +<pre> struct frotz { + uint64_t f_key; + uint64_t f_datum; + struct pslist_entry f_entry; + }; + + static struct { + kmutex_t lock; + pserialize_t psz; + struct pslist_head list; + struct pool pool; + } frobnitzem __cacheline_aligned;</pre> +</div> +<p class="Pp">Initialize the global state:</p> +<div class="Bd Pp Li"> +<pre> mutex_init(&frobnitzem.lock, MUTEX_DEFAULT, IPL_NONE); + frobnitzem.psz = pserialize_create(); + PSLIST_INIT(&frobnitzem.list); + pool_init(&frobnitzem.pool, sizeof(struct frotz), ...);</pre> +</div> +<p class="Pp">Create and publish a frotz:</p> +<div class="Bd Pp Li"> +<pre> uint64_t key = ...; + uint64_t datum = ...; + + struct frotz *f = pool_get(&frobnitzem.pool, PR_WAITOK); + + /* Initialize f. */ + f->f_key = key; + f->f_datum = datum; + PSLIST_ENTRY_INIT(f, f_entry); + + /* Publish it. */ + mutex_enter(&frobnitzem.lock); + PSLIST_WRITER_INSERT_HEAD(&frobnitzem.list, f, f_entry); + mutex_exit(&frobnitzem.lock);</pre> +</div> +<p class="Pp">Look up a frotz and return its associated datum:</p> +<div class="Bd Pp Li"> +<pre> uint64_t key = ...; + struct frotz *f; + int error = ENOENT; + int s; + + s = pserialize_read_enter(); + PSLIST_READER_FOREACH(f, &frobnitzem.list, struct frotz, f_entry) { + if (f->f_key == key) { + *datump = f->f_datum; + error = 0; + break; + } + } + pserialize_read_exit(s); + return error;</pre> +</div> +<p class="Pp">Remove a frotz and wait for readers to finish using it before + reusing the memory allocated for it:</p> +<div class="Bd Pp Li"> +<pre> struct frotz *f = ...; + + mutex_enter(&frobnitzem.lock); + PSLIST_WRITER_REMOVE(f, f_entry); + mutex_exit(&frobnitzem.lock); + + pserialize_perform(&frobnitzem.psz); + + PSLIST_ENTRY_DESTROY(f, f_entry); + pool_put(&frobnitzem.pool, f);</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <code class="Nm">pslist</code> data structure is implemented + by static inlines and macros in + <span class="Pa">sys/sys/pslist.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">queue(3)</a>, <a class="Xr">pserialize(9)</a>, + <a class="Xr">psref(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">pslist</code> data structure first appeared + in <span class="Ux">NetBSD 8.0</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Taylor R Campbell</span> + <<a class="Mt" href="mailto:riastradh@NetBSD.org">riastradh@NetBSD.org</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 7, 2016</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/ras.9 3.html b/static/netbsd/man9/ras.9 3.html new file mode 100644 index 00000000..defc6050 --- /dev/null +++ b/static/netbsd/man9/ras.9 3.html @@ -0,0 +1,121 @@ +<table class="head"> + <tr> + <td class="head-ltitle">RAS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">RAS(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">ras_lookup</code>, + <code class="Nm">ras_fork</code>, <code class="Nm">ras_purgeall</code> + — <span class="Nd">restartable atomic sequences</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/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/proc.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/ras.h</a>></code></p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">ras_lookup</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>, <var class="Fa" style="white-space: nowrap;">void + *addr</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">ras_fork</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p1</var>, <var class="Fa" style="white-space: nowrap;">struct proc + *p2</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">ras_purgeall</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Restartable atomic sequences are user code sequences which are + guaranteed to execute without preemption. This property is assured by + checking the set of restartable atomic sequences registered for a process + during <a class="Xr">cpu_switchto(9)</a>. If a process is found to have been + preempted during a restartable sequence, then its execution is rolled-back + to the start of the sequence by resetting its program counter saved in its + process control block (PCB).</p> +<p class="Pp">The RAS functionality is provided by a combination of the + machine-independent routines discussed in this page and a machine-dependent + component in <a class="Xr">cpu_switchto(9)</a>. A port which supports + restartable atomic sequences will define <code class="Dv">__HAVE_RAS</code> + in <code class="In"><<a class="In">machine/types.h</a>></code> for + machine-independent code to conditionally provide RAS support.</p> +<p class="Pp">A complicated side-effect of restartable atomic sequences is their + interaction with the machine-dependent <a class="Xr">ptrace(2)</a> support. + Specifically, single-step traps and/or the emulation of single-stepping must + carefully consider the effect on restartable atomic sequences. A general + solution is to ignore these traps or disable them within restartable atomic + sequences.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<p class="Pp">The functions which operate on restartable atomic sequences + are:</p> +<dl class="Bl-tag"> + <dt id="ras_lookup"><a class="permalink" href="#ras_lookup"><code class="Fn">ras_lookup</code></a>(<var class="Fa">p</var>, + <var class="Fa">addr</var>)</dt> + <dd>This function searches the registered restartable atomic sequences for + process <var class="Fa">p</var> which contain the user address + <var class="Fa">addr</var>. If the address <var class="Fa">addr</var> is + found within a RAS, then the restart address of the RAS is returned, + otherwise -1 is returned.</dd> + <dt id="ras_fork"><a class="permalink" href="#ras_fork"><code class="Fn">ras_fork</code></a>(<var class="Fa">p1</var>, + <var class="Fa">p2</var>)</dt> + <dd>This function is used to copy all registered restartable atomic sequences + for process <var class="Fa">p1</var> to process <var class="Fa">p2</var>. + It is primarily called from <a class="Xr">fork1(9)</a> when the sequences + are inherited from the parent by the child.</dd> + <dt id="ras_purgeall"><a class="permalink" href="#ras_purgeall"><code class="Fn">ras_purgeall</code></a>(<var class="Fa">p</var>)</dt> + <dd>This function is used to remove all registered restartable atomic + sequences for process <var class="Fa">p</var>. It is primarily used to + remove all registered restartable atomic sequences for a process during + <a class="Xr">exec(3)</a> and by <a class="Xr">rasctl(2)</a>.</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 RAS framework itself is implemented within the file + <span class="Pa">sys/kern/kern_ras.c</span>. Data structures and function + prototypes for the framework are located in + <code class="In"><<a class="In">sys/ras.h</a>></code>. + Machine-dependent portions are implemented within + <a class="Xr">cpu_switchto(9)</a> in the machine-dependent file + <span class="Pa">sys/arch/<arch>/<arch>/locore.S</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">rasctl(2)</a>, <a class="Xr">cpu_switchto(9)</a>, + <a class="Xr">fork1(9)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Gregory McGarry</span>, + <span class="RsT">An Implementation of User-level Restartable Atomic + Sequences on the NetBSD Operating System</span>, <i class="RsB">Proceedings + of the FREENIX Track: 2003 USENIX Annual Technical Conference</i>, + <i class="RsI">USENIX Association</i>, + <a class="RsU" href="http://www.usenix.org/publications/library/proceedings/usenix03/tech/freenix03/full_papers/mcgarry/mcgarry.pdf">http://www.usenix.org/publications/library/proceedings/usenix03/tech/freenix03/full_papers/mcgarry/mcgarry.pdf</a>, + <span class="RsP">311-322</span>, <span class="RsD">June 9-14, + 2003</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The RAS functionality first appeared in <span class="Ux">NetBSD + 2.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 17, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/rdmsr.9 b/static/netbsd/man9/rdmsr.9 new file mode 100644 index 00000000..ab95e482 --- /dev/null +++ b/static/netbsd/man9/rdmsr.9 @@ -0,0 +1,119 @@ +.\" $NetBSD: rdmsr.9,v 1.4 2017/02/17 22:31:08 christos Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 February 17, 2017 +.Dt RDMSR 9 x86 +.Os +.Sh NAME +.Nm msr , +.Nm rdmsr , +.Nm rdmsr_safe , +.Nm wrmsr +.Nd functions for x86 MSRs +.Sh SYNOPSIS +.In x86/cpufunc.h +.Ft uint64_t +.Fn rdmsr "u_int msr" +.\" .Ft uint64_t +.\" .Fn rdmsr_locked "u_int msr" +.Ft int +.Fn rdmsr_safe "u_int msr" "uint64_t *valp" +.Ft void +.Fn wrmsr "u_int msr" "uint64_t val" +.\" .Ft void +.\" .Fn wrmsr_locked "u_int msr" "u_int" "uint64_t val" +.Sh DESCRIPTION +The +.Dv RDMSR +instruction reads from a x86 model-specific register +.Pq Dv MSR . +Conversely, the +.Dv WRMSR +instruction is used to write to a +.Dv MSR . +In +.Nx +the +.Fn rdmsr , +.Fn rdmsr_safe , +and +.Fn wrmsr +functions are used to access +.Dv MSRs . +The header +.In x86/specialreg.h +includes definitions for some of the commonly used MSRs, +that is, control registers that are present +in some x86 processor models but unavailable in others. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn rdmsr "msr" +Returns the value read from +.Fa msr . +.\" .It Fn rdmsr_locked "msr" +.It Fn rdmsr_safe "msr" "valp" +The +.Fn rdmsr_safe +function is a safer variant of +.Fn rdmsr . +Upon successful completion, +the function returns zero and the value read from the register +.Fa msr +is returned in +.Fa valp . +If a fault occurs while accessing +.Fa msr , +.Fn rdmsr_safe +returns +.Dv EFAULT . +.It Fn wrmsr "msr" "val" +The +.Fn wrmsr +function writes +.Fa val +to the register +.Fa msr . +.\" .It Fn wrmsr_locked "msr" "xxx" "val" +.El +.Pp +Note that even though +.Fn rdmsr_safe +provides support for reading +.Dv MSRs +in a safe manner, it is still a good practice +to always verify that the given model-specific register +is present by using the +.Dv CPUID +instruction, available in +.Nx +via +.Fn x86_cpuid . +.Sh SEE ALSO +.Xr rdtsc 9 , +.Xr x86/x86_msr_xcall 9 diff --git a/static/netbsd/man9/return_address.9 b/static/netbsd/man9/return_address.9 new file mode 100644 index 00000000..36e4ccdb --- /dev/null +++ b/static/netbsd/man9/return_address.9 @@ -0,0 +1,91 @@ +.\" $NetBSD: return_address.9,v 1.7 2014/03/18 18:20:40 riastradh Exp $ +.\" +.\" Copyright (c) 2009 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by David Young. +.\" +.\" 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 May 5, 2010 +.Dt RETURN_ADDRESS 9 i386 +.Os +.Sh NAME +.Nm return_address +.Nd return address from call stack +.Sh SYNOPSIS +.In i386/return.h +.Ft void * +.Fn return_address "unsigned int level" +.Sh DESCRIPTION +The +.Fn return_address +function evaluates to the first return address on the call stack +if +.Fa level +equals 0, or else +to the return address for the stack frame +.Fa level +frames down. +.Pp +This function is intended to be called by diagnostic code to record +the call stack. +.Pp +A special fault handler stops +.Fn return_address +from crashing the kernel by examining a non-existent or corrupt stack +frame. +.Pp +Kernel compilation options affect both the ability of +.Fn return_address +to locate return addresses on the stack, and the programmer's +ability to interpret the addresses. +The compiler may optimize away the stack frame pointers that +.Fn return_address +depends on. +.Pp +To use +.Fn return_address +effecively, try a kernel configuration option such as +.Bd -literal +makeoptions DEBUG="-g -fno-omit-frame-pointer \e + -fno-optimize-sibling-calls -O0" +.Ed +.Sh RETURN VALUES +The +.Fn return_address +function returns the requested return address, or +.Dv NULL +if it cannot dissect the call stack. +.Sh CODE REFERENCES +.Pa sys/arch/i386/i386/copy.S , +.Pa sys/arch/i386/include/return.h +.Sh REFERENCES +.Xr config 5 +.Sh HISTORY +The +.Fn return_address +function first appeared in +.Nx 6.0 . +.Sh AUTHORS +.An "David Young" Aq Mt dyoung@NetBSD.org diff --git a/static/netbsd/man9/roundup.9 3.html b/static/netbsd/man9/roundup.9 3.html new file mode 100644 index 00000000..a0cfeb99 --- /dev/null +++ b/static/netbsd/man9/roundup.9 3.html @@ -0,0 +1,100 @@ +<table class="head"> + <tr> + <td class="head-ltitle">ROUNDUP(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">ROUNDUP(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">roundup</code> — <span class="Nd">macros + for counting and rounding</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></p> +<p class="Pp"><var class="Ft">size</var> + <br/> + <code class="Fn">howmany</code>(<var class="Fa" style="white-space: nowrap;">x</var>, + <var class="Fa" style="white-space: nowrap;">size</var>);</p> +<p class="Pp"><var class="Ft">size</var> + <br/> + <code class="Fn">roundup</code>(<var class="Fa" style="white-space: nowrap;">x</var>, + <var class="Fa" style="white-space: nowrap;">size</var>);</p> +<p class="Pp"><var class="Ft">size</var> + <br/> + <code class="Fn">rounddown</code>(<var class="Fa" style="white-space: nowrap;">x</var>, + <var class="Fa" style="white-space: nowrap;">size</var>);</p> +<p class="Pp"><var class="Ft">size</var> + <br/> + <code class="Fn">roundup2</code>(<var class="Fa" style="white-space: nowrap;">x</var>, + <var class="Fa" style="white-space: nowrap;">size</var>);</p> +<p class="Pp"><var class="Ft">size</var> + <br/> + <code class="Fn">rounddown2</code>(<var class="Fa" style="white-space: nowrap;">x</var>, + <var class="Fa" style="white-space: nowrap;">size</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">powerof2</code>(<var class="Fa" style="white-space: nowrap;">x</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#roundup"><code class="Fn" id="roundup">roundup</code></a>() + and + <a class="permalink" href="#rounddown"><code class="Fn" id="rounddown">rounddown</code></a>() + macros return an integer from rounding <var class="Fa">x</var> up and down, + respectively, to the next <var class="Fa">size</var>. The + <a class="permalink" href="#howmany"><code class="Fn" id="howmany">howmany</code></a>() + macro in turn reveals how many times <var class="Fa">size</var> fits into + <var class="Fa">x</var>, rounding the residual up.</p> +<p class="Pp" id="roundup2">The + <a class="permalink" href="#roundup2"><code class="Fn">roundup2</code></a>() + and + <a class="permalink" href="#rounddown2"><code class="Fn" id="rounddown2">rounddown2</code></a>() + macros also round up and down, respectively, but with the assumption that + <var class="Fa">size</var> is a power of two. If <var class="Fa">x</var> is + indeed a power of two, + <a class="permalink" href="#powerof2"><code class="Fn" id="powerof2">powerof2</code></a>() + return 1.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The return value is an integer from the respective operation. If + <var class="Fa">x</var> is 0, all macros except + <code class="Fn">powerof2</code>() return 0. The behavior is undefined if + <var class="Fa">size</var> is 0.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following example rounds the variable <var class="Va">rx</var> + to a 32-bit boundary:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>uint16_t rx; + +... + +rx = roundup2(rx, sizeof(uint32_t));</pre> +</div> +</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">ilog2(3)</a>, <a class="Xr">param(3)</a>, + <a class="Xr">imax(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1> +<p class="Pp">All described macros make no assumptions about the type of the + parameters. These are implicitly assumed to be unsigned integers.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 2, 2019</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/rwlock.9 3.html b/static/netbsd/man9/rwlock.9 3.html new file mode 100644 index 00000000..239ed9ad --- /dev/null +++ b/static/netbsd/man9/rwlock.9 3.html @@ -0,0 +1,256 @@ +<table class="head"> + <tr> + <td class="head-ltitle">RWLOCK(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">RWLOCK(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">rw</code>, <code class="Nm">rw_init</code>, + <code class="Nm">rw_destroy</code>, <code class="Nm">rw_enter</code>, + <code class="Nm">rw_exit</code>, <code class="Nm">rw_tryenter</code>, + <code class="Nm">rw_tryupgrade</code>, <code class="Nm">rw_downgrade</code>, + <code class="Nm">rw_read_held</code>, <code class="Nm">rw_write_held</code>, + <code class="Nm">rw_lock_held</code>, <code class="Nm">rw_lock_op</code> + — <span class="Nd">reader / writer lock primitives</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/rwlock.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">rw_init</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">rw_destroy</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">rw_enter</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>, <var class="Fa" style="white-space: nowrap;">const krw_t + op</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">rw_exit</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">rw_tryenter</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>, <var class="Fa" style="white-space: nowrap;">const krw_t + op</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">rw_tryupgrade</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">rw_downgrade</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">rw_read_held</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">rw_write_held</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">rw_lock_held</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"><var class="Ft">krw_t</var> + <br/> + <code class="Fn">rw_lock_op</code>(<var class="Fa" style="white-space: nowrap;">krwlock_t + *rw</var>);</p> +<p class="Pp"> + <br/> + <code class="Cd">options DIAGNOSTIC</code> + <br/> + <code class="Cd">options LOCKDEBUG</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Reader / writer locks (RW locks) are used in the kernel to + synchronize access to an object among LWPs (lightweight processes) and soft + interrupt handlers.</p> +<p class="Pp">In addition to the capabilities provided by mutexes, RW locks + distinguish between read (shared) and write (exclusive) access.</p> +<p class="Pp">RW locks are in one of three distinct states at any given + time:</p> +<dl class="Bl-tag"> + <dt id="Unlocked"><a class="permalink" href="#Unlocked"><code class="Dv">Unlocked</code></a></dt> + <dd>The lock is not held.</dd> + <dt id="Read"><a class="permalink" href="#Read"><code class="Dv">Read + locked</code></a></dt> + <dd>The lock holders intend to read the protected object. Multiple callers may + hold a RW lock with “read intent” simultaneously.</dd> + <dt id="Write"><a class="permalink" href="#Write"><code class="Dv">Write + locked</code></a></dt> + <dd>The lock holder intends to update the protected object. Only one caller + may hold a RW lock with “write intent”.</dd> +</dl> +<p class="Pp">The <var class="Vt">krwlock_t</var> type provides storage for the + RW lock object. This should be treated as an opaque object and not examined + directly by consumers.</p> +<p class="Pp">Note that these interfaces must not be used from a hardware + interrupt handler.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="OPTIONS_AND_MACROS"><a class="permalink" href="#OPTIONS_AND_MACROS">OPTIONS + AND MACROS</a></h1> +<dl class="Bl-tag"> + <dt><code class="Cd">options DIAGNOSTIC</code></dt> + <dd> + <p class="Pp">Kernels compiled with the <code class="Dv">DIAGNOSTIC</code> + option perform basic sanity checks on RW lock operations.</p> + </dd> + <dt><code class="Cd">options LOCKDEBUG</code></dt> + <dd> + <p class="Pp">Kernels compiled with the <code class="Dv">LOCKDEBUG</code> + option perform potentially CPU intensive sanity checks on RW lock + operations.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="rw_init"><a class="permalink" href="#rw_init"><code class="Fn">rw_init</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Initialize a lock for use. No other operations can be + performed on the lock until it has been initialized.</p> + </dd> + <dt id="rw_destroy"><a class="permalink" href="#rw_destroy"><code class="Fn">rw_destroy</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Release resources used by a lock. The lock may not be used + after it has been destroyed.</p> + </dd> + <dt id="rw_enter"><a class="permalink" href="#rw_enter"><code class="Fn">rw_enter</code></a>(<var class="Fa">rw</var>, + <var class="Fa">op</var>)</dt> + <dd> + <p class="Pp">If <code class="Dv">RW_READER</code> is specified as the + argument to <var class="Fa">op</var>, acquire a read lock. The caller + may block and will not return until the hold is acquired. Callers must + not recursively acquire read locks.</p> + <p class="Pp">If <code class="Dv">RW_WRITER</code> is specified, acquire a + write lock. If the lock is already held, the caller will block and not + return until the hold is acquired.</p> + <p class="Pp">RW locks and other types of locks must always be acquired in a + consistent order with respect to each other. Otherwise, the potential + for system deadlock exists.</p> + </dd> + <dt id="rw_exit"><a class="permalink" href="#rw_exit"><code class="Fn">rw_exit</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Release a lock. The lock must have been previously acquired by + the caller.</p> + </dd> + <dt id="rw_tryenter"><a class="permalink" href="#rw_tryenter"><code class="Fn">rw_tryenter</code></a>(<var class="Fa">rw</var>, + <var class="Fa">op</var>)</dt> + <dd> + <p class="Pp">Try to acquire a lock, but do not block if the lock is already + held. If the lock is acquired successfully, return non-zero. Otherwise, + return zero.</p> + <p class="Pp">Valid arguments to <var class="Fa">op</var> are + <code class="Dv">RW_READER</code> or + <code class="Dv">RW_WRITER</code>.</p> + </dd> + <dt id="rw_tryupgrade"><a class="permalink" href="#rw_tryupgrade"><code class="Fn">rw_tryupgrade</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Try to upgrade a lock from one read hold to a write hold. If + the lock is upgraded successfully, returns non-zero. Otherwise, returns + zero.</p> + </dd> + <dt id="rw_downgrade"><a class="permalink" href="#rw_downgrade"><code class="Fn">rw_downgrade</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Downgrade a lock from a write hold to a read hold.</p> + </dd> + <dt id="rw_write_held"><a class="permalink" href="#rw_write_held"><code class="Fn">rw_write_held</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Return non-zero if write lock is held by current lwp. + Otherwise, return zero.</p> + </dd> + <dt id="rw_read_held"><a class="permalink" href="#rw_read_held"><code class="Fn">rw_read_held</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Returns non-zero if read lock is held by any lwp. Otherwise, + return zero.</p> + </dd> + <dt id="rw_lock_held"><a class="permalink" href="#rw_lock_held"><code class="Fn">rw_lock_held</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">Returns non-zero if either read or write lock is held by any + lwp. Otherwise, return zero.</p> + <p class="Pp" id="rw_write_held~2"><a class="permalink" href="#rw_write_held~2"><code class="Fn">rw_write_held</code></a>(), + <code class="Fn">rw_read_held</code>(), and + <code class="Fn">rw_lock_held</code>() should not generally be used to + make locking decisions at run time: they are provided for diagnostic + purposes, for example making assertions.</p> + <p class="Pp" id="rw_write_held~3">Negative assertions (lock not held) + should not be made due to atomicity issues, excepting + <a class="permalink" href="#rw_write_held~3"><code class="Fn">rw_write_held</code></a>(), + which can safely be used to assert that a write lock is NOT held by the + current LWP.</p> + </dd> + <dt id="rw_lock_op"><a class="permalink" href="#rw_lock_op"><code class="Fn">rw_lock_op</code></a>(<var class="Fa">rw</var>)</dt> + <dd> + <p class="Pp">For a lock that is known to be held by the calling LWP, return + either <code class="Dv">RW_READER</code> or + <code class="Dv">RW_WRITER</code> to denote the type of hold. This is + useful when dropping and later re-acquiring a lock, if the type of hold + is not already known.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="PERFORMANCE_CONSIDERATIONS"><a class="permalink" href="#PERFORMANCE_CONSIDERATIONS">PERFORMANCE + CONSIDERATIONS</a></h1> +<p class="Pp">RW locks are subject to high cache contention on multiprocessor + systems, and scale poorly when the write:read ratio is not strongly in + favour of readers. Ideally, RW locks should only be used in settings when + the following three conditions are met:</p> +<ul class="Bl-bullet"> + <li>The data object(s) protected by the RW lock are read much more frequently + than written.</li> + <li>The read-side hold time for the RW lock is long (in the order of thousands + of processor clock cycles).</li> + <li>Strong synchronization semantics are required: there is no scope for + lockless, lazy or optimistic synchronization.</li> +</ul> +<p class="Pp">Generally speaking, it is better to organise code paths and/or + data flows such that fewer and weaker synchronization points are required to + ensure correct operation.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The core of the RW lock implementation is in + <span class="Pa">sys/kern/kern_rwlock.c</span>.</p> +<p class="Pp">The header file <span class="Pa">sys/sys/rwlock.h</span> describes + the public interface, and interfaces that machine-dependent code must + provide to support RW locks.</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">membar_ops(3)</a>, <a class="Xr">lockstat(8)</a>, + <a class="Xr">condvar(9)</a>, <a class="Xr">mutex(9)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Jim Mauro</span> and + <span class="RsA">Richard McDougall</span>, <span class="RsT">Solaris + Internals: Core Kernel Architecture</span>, <i class="RsI">Prentice + Hall</i>, <span class="RsD">2001</span>, <span class="RsO">ISBN + 0-13-022496-0</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The RW lock primitives first appeared in <span class="Ux">NetBSD + 5.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">February 22, 2020</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/scanc.9 3.html b/static/netbsd/man9/scanc.9 3.html new file mode 100644 index 00000000..89cfb775 --- /dev/null +++ b/static/netbsd/man9/scanc.9 3.html @@ -0,0 +1,55 @@ +<table class="head"> + <tr> + <td class="head-ltitle">SCANC(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">SCANC(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">scanc</code> — <span class="Nd">use byte + string as lookup table index</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">lib/libkern/libkern.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">scanc</code>(<var class="Fa" style="white-space: nowrap;">u_int + size</var>, <var class="Fa" style="white-space: nowrap;">const u_char + *cp</var>, <var class="Fa" style="white-space: nowrap;">const u_char + table[]</var>, <var class="Fa" style="white-space: nowrap;">int + mask</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The + <a class="permalink" href="#scanc"><code class="Fn" id="scanc">scanc</code></a>() + function scans the byte string <var class="Fa">cp</var>, whose length is + <var class="Fa">size</var>. A character in the string is used as an index in + the 256-byte <var class="Fa">table</var>. If a bitwise-AND of the byte from + the table and <var class="Fa">mask</var> isn't zero or the string is + exhausted, the scan stops.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">The <code class="Fn">scanc</code>() function returns the length of + the rest of the string, including the character which made the scan stop. If + the <code class="Fn">scanc</code>() function exhausted the string, it + returns 0.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Fn">scanc</code>() function emulates a VAX + instruction with the same name.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 24, 2013</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/sched_4bsd.9 3.html b/static/netbsd/man9/sched_4bsd.9 3.html new file mode 100644 index 00000000..d08d4b85 --- /dev/null +++ b/static/netbsd/man9/sched_4bsd.9 3.html @@ -0,0 +1,103 @@ +<table class="head"> + <tr> + <td class="head-ltitle">SCHED_4BSD(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">SCHED_4BSD(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">sched_4bsd</code> — <span class="Nd">The + 4.4BSD thread scheduler</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/sched.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">resetpriority</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *l</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_tick</code>(<var class="Fa" style="white-space: nowrap;">struct + cpu_info *ci</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_schedclock</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *l</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_pstats_hook</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>, <var class="Fa" style="white-space: nowrap;">int + minslp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sched_setrunnable</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *l</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">updatepri</code>(<var class="Fa" style="white-space: nowrap;">lwp_t + *l</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The traditional <span class="Ux">4.4BSD</span> scheduler employs a + “multilevel feedback queues” algorithm, favouring interactive, + short-running threads to CPU-bound ones.</p> +<p class="Pp" id="resetpriority"><a class="permalink" href="#resetpriority"><code class="Fn">resetpriority</code></a>() + recomputes the priority of a thread running in user mode. If the resulting + priority is higher than that of the current thread, a reschedule is + arranged.</p> +<p class="Pp" id="sched_tick"><a class="permalink" href="#sched_tick"><code class="Fn">sched_tick</code></a>() + gets called from <a class="Xr">hardclock(9)</a> every 100ms to force a + switch between equal priority threads.</p> +<p class="Pp" id="sched_schedclock">The priority of the current thread is + adjusted through + <a class="permalink" href="#sched_schedclock"><code class="Fn">sched_schedclock</code></a>(). + The priority of a thread gets worse as it accumulates CPU time.</p> +<p class="Pp" id="sched_pstats_hook"><a class="permalink" href="#sched_pstats_hook"><code class="Fn">sched_pstats_hook</code></a>() + gets called from + <a class="permalink" href="#sched_pstats"><code class="Fn" id="sched_pstats">sched_pstats</code></a>() + every Hz ticks in order to recompute the priorities of all threads.</p> +<p class="Pp" id="sched_setrunnable"><a class="permalink" href="#sched_setrunnable"><code class="Fn">sched_setrunnable</code></a>() + checks if an LWP has slept for more than one second. If so, its priority is + updated by + <a class="permalink" href="#updatepri"><code class="Fn" id="updatepri">updatepri</code></a>().</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">To determine the scheduler currently in use</p> +<div class="Bd Pp Bd-indent Li"> +<pre>$ sysctl kern.sched.name +kern.sched.name = 4.4BSD</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The <span class="Ux">4.4BSD</span> scheduler subsystem is + implemented within the file + <span class="Pa">sys/kern/sched_4bsd.c</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">csf(9)</a>, <a class="Xr">hardclock(9)</a>, + <a class="Xr">mi_switch(9)</a>, <a class="Xr">sched_m2(9)</a>, + <a class="Xr">userret(9)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Marshall Kirk McKusick</span>, + <span class="RsA">Keith Bostic</span>, <span class="RsA">Michael J. + Karels</span>, and <span class="RsA">John S. Quarterman</span>, + <i class="RsB">The Design and Implementation of the 4.4BSD Operating + System</i>, <i class="RsI">Addison Wesley</i>, + <span class="RsD">1996</span>.</cite></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 9, 2019</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/secmodel_extensions.9 3.html b/static/netbsd/man9/secmodel_extensions.9 3.html new file mode 100644 index 00000000..e5aa5184 --- /dev/null +++ b/static/netbsd/man9/secmodel_extensions.9 3.html @@ -0,0 +1,103 @@ +<table class="head"> + <tr> + <td class="head-ltitle">SECMODEL_EXTENSIONS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">SECMODEL_EXTENSIONS(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">secmodel_extensions</code> — + <span class="Nd">extensions security model</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">secmodel_extensions</code> implements extensions + to the traditional security model based on the original + <span class="Ux">4.4BSD</span>. They can be used to grant additional + privileges to ordinary users, or enable specific security measures like + curtain mode.</p> +<p class="Pp">The extensions are described below.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="Curtain_mode"><a class="permalink" href="#Curtain_mode">Curtain + mode</a></h1> +<p class="Pp">When enabled, all returned objects will be filtered according to + the user-id requesting information about them, preventing users from + accessing objects they do not own.</p> +<p class="Pp">It affects the output of many commands, including + <a class="Xr">fstat(1)</a>, <a class="Xr">netstat(1)</a>, + <a class="Xr">ps(1)</a>, <a class="Xr">sockstat(1)</a>, and + <a class="Xr">w(1)</a>.</p> +<p class="Pp">This extension is enabled by setting + <span class="Pa">security.models.extensions.curtain</span> or + <span class="Pa">security.curtain</span> <a class="Xr">sysctl(7)</a> to a + non-zero value.</p> +<p class="Pp">It can be enabled at any time, but cannot be disabled anymore when + the <i class="Em">securelevel</i> of the system is above 0.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="Non-superuser_mounts"><a class="permalink" href="#Non-superuser_mounts">Non-superuser + mounts</a></h1> +<p class="Pp">When enabled, it allows file-systems to be mounted by an ordinary + user who owns the point <var class="Ar">node</var> and has at least read + access to the <var class="Ar">special</var> device + <a class="Xr">mount(8)</a> arguments. Note that the + <code class="Cm">nosuid</code> and <code class="Cm">nodev</code> flags must + be given for non-superuser mounts.</p> +<p class="Pp">This extension is enabled by setting + <span class="Pa">security.models.extensions.usermount</span> or + <span class="Pa">vfs.generic.usermount</span> <a class="Xr">sysctl(7)</a> to + a non-zero value.</p> +<p class="Pp">It can be disabled at any time, but cannot be enabled anymore when + the <i class="Em">securelevel</i> of the system is above 0.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="Non-superuser_control_of_CPU_sets"><a class="permalink" href="#Non-superuser_control_of_CPU_sets">Non-superuser + control of CPU sets</a></h1> +<p class="Pp">When enabled, an ordinary user is allowed to control the CPU + <a class="Xr">affinity(3)</a> of the processes and threads they own.</p> +<p class="Pp">This extension is enabled by setting + <span class="Pa">security.models.extensions.user_set_cpu_affinity</span> + <a class="Xr">sysctl(7)</a> to a non-zero value.</p> +<p class="Pp">It can be disabled at any time, but cannot be enabled anymore when + the <i class="Em">securelevel</i> of the system is above 0.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="Hardlink_restrictions"><a class="permalink" href="#Hardlink_restrictions">Hardlink + restrictions</a></h1> +<p class="Pp">Prevent hardlinks to files that the user does not own or has group + access to.</p> +<p class="Pp">To enable user ownership checks, set the + <a class="Xr">sysctl(7)</a> variable + <span class="Pa">security.models.extensions.hardlink_check_uid</span> to a + non-zero value.</p> +<p class="Pp">To enable group membership checks, set the + <a class="Xr">sysctl(7)</a> variable + <span class="Pa">security.models.extensions.hardlink_check_gid</span> to a + non-zero value.</p> +<p class="Pp">These variables can be enabled anytime, but cannot be disabled + anymore when the <i class="Em">securelevel</i> of the system is above 0.</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">affinity(3)</a>, <a class="Xr">sched(3)</a>, + <a class="Xr">sysctl(7)</a>, <a class="Xr">kauth(9)</a>, + <a class="Xr">secmodel(9)</a>, <a class="Xr">secmodel_bsd44(9)</a>, + <a class="Xr">secmodel_securelevel(9)</a>, + <a class="Xr">secmodel_suser(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Elad Efrat</span> + <<a class="Mt" href="mailto:elad@NetBSD.org">elad@NetBSD.org</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 27, 2022</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/signal.9 3.html b/static/netbsd/man9/signal.9 3.html new file mode 100644 index 00000000..6cfaf949 --- /dev/null +++ b/static/netbsd/man9/signal.9 3.html @@ -0,0 +1,482 @@ +<table class="head"> + <tr> + <td class="head-ltitle">SIGNAL(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">SIGNAL(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">signal</code>, <code class="Nm">siginit</code>, + <code class="Nm">sigactsinit</code>, <code class="Nm">sigactsunshare</code>, + <code class="Nm">sigactsfree</code>, <code class="Nm">execsigs</code>, + <code class="Nm">sigaction1</code>, <code class="Nm">sigprocmask1</code>, + <code class="Nm">sigpending1</code>, <code class="Nm">sigsuspend1</code>, + <code class="Nm">sigaltstack1</code>, <code class="Nm">pgsignal</code>, + <code class="Nm">kpgsignal</code>, <code class="Nm">psignal</code>, + <code class="Nm">kpsignal</code>, <code class="Nm">issignal</code>, + <code class="Nm">postsig</code>, <code class="Nm">killproc</code>, + <code class="Nm">sigexit</code>, <code class="Nm">trapsignal</code>, + <code class="Nm">sendsig</code>, <code class="Nm">sigcode</code>, + <code class="Nm">sigtramp</code> — <span class="Nd">software signal + facilities</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/signal.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/signalvar.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">siginit</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sigactsinit</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *pp</var>, <var class="Fa" style="white-space: nowrap;">int + share</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sigactsunshare</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sigactsfree</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">execsigs</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sigaction1</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">int signum</var>, + <var class="Fa" style="white-space: nowrap;">const struct sigaction + *nsa</var>, <var class="Fa" style="white-space: nowrap;">struct sigaction + *osa</var>, <var class="Fa" style="white-space: nowrap;">void *tramp</var>, + <var class="Fa" style="white-space: nowrap;">int vers</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sigprocmask1</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">int how</var>, + <var class="Fa" style="white-space: nowrap;">const sigset_t *nss</var>, + <var class="Fa" style="white-space: nowrap;">sigset_t *oss</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sigpending1</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">sigset_t + *ss</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sigsuspend1</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">const sigset_t + *ss</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sigaltstack1</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">const struct + sigaltstack *nss</var>, <var class="Fa" style="white-space: nowrap;">struct + sigaltstack *oss</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">pgsignal</code>(<var class="Fa" style="white-space: nowrap;">struct + pgrp *pgrp</var>, <var class="Fa" style="white-space: nowrap;">int + signum</var>, <var class="Fa" style="white-space: nowrap;">int + checkctty</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kpgsignal</code>(<var class="Fa" style="white-space: nowrap;">struct + pgrp *pgrp</var>, <var class="Fa" style="white-space: nowrap;">ksiginfo_t + *ks</var>, <var class="Fa" style="white-space: nowrap;">void *data</var>, + <var class="Fa" style="white-space: nowrap;">int checkctty</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">psignal</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>, <var class="Fa" style="white-space: nowrap;">int + signum</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">kpsignal</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>, <var class="Fa" style="white-space: nowrap;">ksiginfo_t + *ks</var>, <var class="Fa" style="white-space: nowrap;">void + *data</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">issignal</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">postsig</code>(<var class="Fa" style="white-space: nowrap;">int + signum</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">killproc</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p</var>, <var class="Fa" style="white-space: nowrap;">const char + *why</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sigexit</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">int + signum</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">trapsignal</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">const ksiginfo_t + *ks</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sendsig</code>(<var class="Fa" style="white-space: nowrap;">const + ksiginfo_t *ks</var>, <var class="Fa" style="white-space: nowrap;">const + sigset_t *mask</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The system defines a set of signals that may be delivered to a + process. These functions implement the kernel portion of the signal + facility.</p> +<p class="Pp">Signal numbers used throughout the kernel signal facilities should + always be within the range of [1-NSIG].</p> +<p class="Pp">Most of the kernel's signal infrastructure is implemented in + machine-independent code. Machine-dependent code provides support for + invoking a process's signal handler, restoring context when the signal + handler returns, generating signals when hardware traps occur, triggering + the delivery of signals when a process is about to return from the kernel to + userspace.</p> +<p class="Pp">The signal state for a process is contained in + <var class="Fa">struct sigctx</var>. This includes the list of signals with + delivery pending, information about the signal handler stack, the signal + mask, and the address of the signal trampoline.</p> +<p class="Pp">The registered signal handlers for a process are recorded in + <var class="Fa">struct sigacts</var>. This structure may be shared by + multiple processes.</p> +<p class="Pp">The kernel's signal facilities are implemented by the following + functions:</p> +<dl class="Bl-tag"> + <dt id="siginit"><a class="permalink" href="#siginit"><code class="Fn">siginit</code></a>(<var class="Fa">p</var>)</dt> + <dd> + <p class="Pp">This function initializes the signal state of + <var class="Va">proc0</var> to the system default. This signal state is + then inherited by <a class="Xr">init(8)</a> when it is started by the + kernel.</p> + </dd> + <dt id="sigactsinit"><a class="permalink" href="#sigactsinit"><code class="Fn">sigactsinit</code></a>(<var class="Fa">pp</var>, + <var class="Fa">share</var>)</dt> + <dd> + <p class="Pp">This function creates an initial <var class="Fa">struct + sigacts</var> for the process <var class="Fa">pp</var>. If the + <var class="Fa">share</var> argument is non-zero, then + <var class="Fa">pp</var> shares the <var class="Fa">struct sigacts</var> + by holding a reference. Otherwise, <var class="Fa">pp</var> receives a + new <var class="Fa">struct sigacts</var> which is copied from the + parent.</p> + </dd> + <dt id="sigactsunshare"><a class="permalink" href="#sigactsunshare"><code class="Fn">sigactsunshare</code></a>(<var class="Fa">p</var>)</dt> + <dd> + <p class="Pp">This function causes the process <var class="Fa">p</var> to no + longer share its <var class="Fa">struct sigacts</var> The current state + of the signal actions is maintained in the new copy.</p> + </dd> + <dt id="sigactsfree"><a class="permalink" href="#sigactsfree"><code class="Fn">sigactsfree</code></a>(<var class="Fa">p</var>)</dt> + <dd> + <p class="Pp">This function decrements the reference count on the + <var class="Fa">struct sigacts</var> of process <var class="Fa">p</var>. + If the reference count reaches zero, the <var class="Fa">struct + sigacts</var> is freed.</p> + </dd> + <dt id="execsigs"><a class="permalink" href="#execsigs"><code class="Fn">execsigs</code></a>(<var class="Fa">p</var>)</dt> + <dd> + <p class="Pp">This function is used to reset the signal state of the process + <var class="Fa">p</var> to the system defaults when the process execs a + new program image.</p> + </dd> + <dt id="sigaction1"><a class="permalink" href="#sigaction1"><code class="Fn">sigaction1</code></a>(<var class="Fa">l</var>, + <var class="Fa">signum</var>, <var class="Fa">nsa</var>, + <var class="Fa">osa</var>, <var class="Fa">tramp</var>, + <var class="Fa">vers</var>)</dt> + <dd> + <p class="Pp" id="sendsig">This function implements the + <a class="Xr">sigaction(2)</a> system call. The + <var class="Fa">tramp</var> and <var class="Fa">vers</var> arguments + provide support for userspace signal trampolines. Trampoline version 0 + is reserved for the legacy kernel-provided signal trampoline; + <var class="Fa">tramp</var> must be <code class="Dv">NULL</code> in this + case. Otherwise, <var class="Fa">vers</var> specifies the ABI of the + trampoline specified by <var class="Fa">tramp</var>. The signal + trampoline ABI is machine-dependent, and must be coordinated with the + <a class="permalink" href="#sendsig"><code class="Fn">sendsig</code></a>() + function.</p> + </dd> + <dt id="sigprocmask1"><a class="permalink" href="#sigprocmask1"><code class="Fn">sigprocmask1</code></a>(<var class="Fa">l</var>, + <var class="Fa">how</var>, <var class="Fa">nss</var>, + <var class="Fa">oss</var>)</dt> + <dd> + <p class="Pp">This function implements the <a class="Xr">sigprocmask(2)</a> + system call.</p> + </dd> + <dt id="sigpending1"><a class="permalink" href="#sigpending1"><code class="Fn">sigpending1</code></a>(<var class="Fa">l</var>, + <var class="Fa">ss</var>)</dt> + <dd> + <p class="Pp">This function implements the <a class="Xr">sigpending(2)</a> + system call.</p> + </dd> + <dt id="sigsuspend1"><a class="permalink" href="#sigsuspend1"><code class="Fn">sigsuspend1</code></a>(<var class="Fa">l</var>, + <var class="Fa">ss</var>)</dt> + <dd> + <p class="Pp">This function implements the <a class="Xr">sigsuspend(2)</a> + system call.</p> + </dd> + <dt id="sigaltstack1"><a class="permalink" href="#sigaltstack1"><code class="Fn">sigaltstack1</code></a>(<var class="Fa">l</var>, + <var class="Fa">nss</var>, <var class="Fa">oss</var>)</dt> + <dd> + <p class="Pp">This function implements the <a class="Xr">sigaltstack(2)</a> + system call.</p> + </dd> + <dt id="pgsignal"><a class="permalink" href="#pgsignal"><code class="Fn">pgsignal</code></a>(<var class="Fa">pgrp</var>, + <var class="Fa">signum</var>, <var class="Fa">checkctty</var>)</dt> + <dd> + <p class="Pp" id="kpgsignal">This is a wrapper function for + <a class="permalink" href="#kpgsignal"><code class="Fn">kpgsignal</code></a>() + which is described below.</p> + </dd> + <dt><code class="Fn">kpgsignal</code>(<var class="Fa">pgrp</var>, + <var class="Fa">ks</var>, <var class="Fa">data</var>, + <var class="Fa">checkctty</var>)</dt> + <dd> + <p class="Pp" id="kpsignal">Schedule the signal + <var class="Fa">ks->ksi_signo</var> to be delivered to all members of + the process group <var class="Fa">pgrp</var>. If + <var class="Fa">checkctty</var> is non-zero, the signal is only sent to + processes which have a controlling terminal. The + <var class="Fa">data</var> argument and the complete signal scheduling + semantics are described in the + <a class="permalink" href="#kpsignal"><code class="Fn">kpsignal</code></a>() + function below.</p> + </dd> + <dt id="trapsignal"><a class="permalink" href="#trapsignal"><code class="Fn">trapsignal</code></a>(<var class="Fa">l</var>, + <var class="Fa">ks</var>)</dt> + <dd> + <p class="Pp">Sends the signal <var class="Fa">ks->ksi_signo</var> caused + by a hardware trap to the current process.</p> + </dd> + <dt id="psignal"><a class="permalink" href="#psignal"><code class="Fn">psignal</code></a>(<var class="Fa">p</var>, + <var class="Fa">signum</var>)</dt> + <dd> + <p class="Pp" id="kpsignal~2">This is a wrapper function for + <a class="permalink" href="#kpsignal~2"><code class="Fn">kpsignal</code></a>() + which is described below.</p> + </dd> + <dt><code class="Fn">kpsignal</code>(<var class="Fa">p</var>, + <var class="Fa">ks</var>, <var class="Fa">data</var>)</dt> + <dd> + <p class="Pp">Schedule the signal <var class="Fa">ks->ksi_signo</var> to + be delivered to the process <var class="Fa">p</var>. The + <var class="Fa">data</var> argument, if not + <code class="Dv">NULL</code>, points to the file descriptor data that + caused the signal to be generated in the <code class="Li">SIGIO</code> + case.</p> + <p class="Pp" id="issignal">With a few exceptions noted below, the target + process signal disposition is updated and is marked as runnable, so + further handling of the signal is done in the context of the target + process after a context switch; see + <a class="permalink" href="#issignal"><code class="Fn">issignal</code></a>() + below. Note that <code class="Fn">kpsignal</code>() does not by itself + cause a context switch to happen.</p> + <p class="Pp">The target process is not marked as runnable in the following + cases:</p> + <ul class="Bl-bullet Bd-indent"> + <li>The target process is sleeping uninterruptibly. The signal will be + noticed when the process returns from the system call or trap.</li> + <li>The target process is currently ignoring the signal.</li> + <li>If a stop signal is sent to a sleeping process that takes the default + action (see <a class="Xr">sigaction(2)</a>), the process is stopped + without awakening it.</li> + <li>SIGCONT restarts a stopped process (or puts them back to sleep) + regardless of the signal action (e.g., blocked or ignored).</li> + </ul> + <p class="Pp" id="kpsignal~3">If the target process is being traced, + <a class="permalink" href="#kpsignal~3"><code class="Fn">kpsignal</code></a>() + behaves as if the target process were taking the default action for + <var class="Fa">signum</var>. This allows the tracing process to be + notified of the signal.</p> + </dd> + <dt><code class="Fn">issignal</code>(<var class="Fa">l</var>)</dt> + <dd> + <p class="Pp">This function determines which signal, if any, is to be posted + to the current process. A signal is to be posted if:</p> + <ul class="Bl-bullet Bd-indent"> + <li>The signal has a handler provided by the program image.</li> + <li>The signal should cause the process to dump core and/or + terminate.</li> + <li>The signal should interrupt the current system call.</li> + </ul> + <p class="Pp" id="issignal~2">Signals which cause the process to be stopped + are handled within + <a class="permalink" href="#issignal~2"><code class="Fn">issignal</code></a>() + directly.</p> + <p class="Pp" id="issignal~3"><a class="permalink" href="#issignal~3"><code class="Fn">issignal</code></a>() + should be called by machine-dependent code when returning to userspace + from a system call or other trap or interrupt by using the following + code:</p> + <div class="Bd Pp Bd-indent Li"> + <pre>while (signum = CURSIG(curproc)) + postsig(signum);</pre> + </div> + </dd> + <dt id="postsig"><a class="permalink" href="#postsig"><code class="Fn">postsig</code></a>(<var class="Fa">signum</var>)</dt> + <dd> + <p class="Pp" id="postsig~2">The + <a class="permalink" href="#postsig~2"><code class="Fn">postsig</code></a>() + function is used to invoke the action for the signal + <var class="Fa">signum</var> in the current process. If the default + action of a signal is to terminate the process, and the signal does not + have a registered handler, the process exits using + <code class="Fn">sigexit</code>(), dumping a core image if + necessary.</p> + </dd> + <dt id="killproc"><a class="permalink" href="#killproc"><code class="Fn">killproc</code></a>(<var class="Fa">p</var>, + <var class="Fa">why</var>)</dt> + <dd> + <p class="Pp">This function sends a SIGKILL signal to the specified process. + The message provided by <var class="Fa">why</var> is sent to the system + log and is also displayed on the process's controlling terminal.</p> + </dd> + <dt id="sigexit"><a class="permalink" href="#sigexit"><code class="Fn">sigexit</code></a>(<var class="Fa">l</var>, + <var class="Fa">signum</var>)</dt> + <dd> + <p class="Pp">This function forces the current process to exit with the + signal <var class="Fa">signum</var>, generating a core file if + appropriate. No checks are made for masked or caught signals; the + process always exits.</p> + </dd> + <dt id="sendsig~2"><a class="permalink" href="#sendsig~2"><code class="Fn">sendsig</code></a>(<var class="Fa">ks</var>, + <var class="Fa">mask</var>)</dt> + <dd> + <p class="Pp" id="sendsig~3">This function is provided by machine-dependent + code, and is used to invoke a signal handler for the current process. + <a class="permalink" href="#sendsig~3"><code class="Fn">sendsig</code></a>() + must prepare the registers and stack of the current process to invoke + the signal handler stored in the process's <var class="Fa">struct + sigacts</var>. This may include switching to an alternate signal stack + specified by the process. The previous register, stack, and signal state + are stored in a <var class="Fa">ucontext_t</var>, which is then copied + out to the user's stack.</p> + <p class="Pp">The registers and stack must be set up to invoke the signal + handler as follows:</p> + <div class="Bd Pp Bd-indent Li"> + <pre>(*handler)(int signum, siginfo_t *info, void *ctx)</pre> + </div> + <p class="Pp">where <var class="Fa">signum</var> is the signal number, + <var class="Fa">info</var> contains additional signal specific + information when <code class="Li">SA_SIGINFO</code> is specified when + setting up the signal handler. <var class="Fa">ctx</var> is the pointer + to <var class="Fa">ucontext_t</var> on the user's stack. The registers + and stack must also arrange for the signal handler to return to the + signal trampoline. The trampoline is then used to return to the code + which was executing when the signal was delivered using the + <a class="Xr">setcontext(2)</a> system call.</p> + <p class="Pp" id="sendsig~4">For performance reasons, it is recommended that + <a class="permalink" href="#sendsig~4"><code class="Fn">sendsig</code></a>() + arrange for the signal handler to be invoked directly on architectures + where it is convenient to do so. In this case, the trampoline is used + only for the signal return path. If it is not feasible to directly + invoke the signal handler, the trampoline is also used to invoke the + handler, performing any final set up that was not possible for + <code class="Fn">sendsig</code>() to perform.</p> + <p class="Pp" id="sendsig~5"><a class="permalink" href="#sendsig~5"><code class="Fn">sendsig</code></a>() + must invoke the signal trampoline with the correct ABI. The ABI of the + signal trampoline is specified on a per-signal basis in the + <a class="permalink" href="#sigacts"><code class="Fn" id="sigacts">sigacts</code></a>() + structure for the process. Trampoline version 0 is reserved for the + legacy kernel-provided, on-stack signal trampoline. All other trampoline + versions indicate a specific trampoline ABI. This ABI is coordinated + with machine-dependent code in the system C library.</p> + </dd> +</dl> +<section class="Ss"> +<h2 class="Ss" id="SIGNAL_TRAMPOLINE"><a class="permalink" href="#SIGNAL_TRAMPOLINE">SIGNAL + TRAMPOLINE</a></h2> +<p class="Pp">The signal trampoline is a special piece of code which provides + support for invoking the signal handlers for a process. The trampoline is + used to return from the signal handler back to the code which was executing + when the signal was delivered, and is also used to invoke the handler itself + on architectures where it is not feasible to have the kernel invoke the + handler directly.</p> +<p class="Pp">In traditional <span class="Ux">UNIX</span> systems, the signal + trampoline, also referred to as the “sigcode”, is provided by + the kernel and copied to the top of the user's stack when a new process is + created or a new program image is exec'd. Starting in + <span class="Ux">NetBSD 2.0</span>, the signal trampoline is provided by the + system C library. This allows for more flexibility when the signal facility + is extended, makes dealing with signals easier in debuggers, such as + <a class="Xr">gdb(1)</a>, and may also enhance system security by allowing + the kernel to disallow execution of code on the stack.</p> +<p class="Pp">The signal trampoline is specified on a per-signal basis. The + correct trampoline is selected automatically by the C library when a signal + handler is registered by a process.</p> +<p class="Pp">Signal trampolines have a special naming convention which enables + debuggers to determine the characteristics of the signal handler and its + arguments. Trampoline functions are named like so:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>__sigtramp_<flavor>_<version></pre> +</div> +<p class="Pp">where:</p> +<dl class="Bl-tag"> + <dt>⟨flavor⟩</dt> + <dd>The flavor of the signal handler. The following flavors are valid: + <dl class="Bl-tag"> + <dt>sigcontext</dt> + <dd>Specifies a traditional BSD-style (deprecated) signal handler with the + following signature: + <div class="Bd Pp Li"> + <pre>void (*handler)(int signum, + int code, + struct sigcontext *scp);</pre> + </div> + </dd> + <dt>siginfo</dt> + <dd>Specifies a POSIX-style signal handler with the following signature: + <div class="Bd Pp Li"> + <pre>void (*handler)(int signum, + siginfo_t *si, + void *uc);</pre> + </div> + <p class="Pp">Note: sigcontext style signal handlers are deprecated, and + retained only for compatibility with older binaries.</p> + </dd> + </dl> + </dd> + <dt id="sendsig~6">⟨version⟩</dt> + <dd>Specifies the ABI version of the signal trampoline. The trampoline ABI is + coordinated with the machine-dependent kernel + <a class="permalink" href="#sendsig~6"><code class="Fn">sendsig</code></a>() + function. The trampoline version needs to be unique even across different + trampoline flavors, in order to simplify trampoline selection in the + kernel.</dd> +</dl> +<p class="Pp">The following is an example if a signal trampoline name which + indicates that the trampoline is used for traditional BSD-style signal + handlers and implements version 1 of the signal trampoline ABI:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>__sigtramp_sigcontext_1</pre> +</div> +<p class="Pp">The current signal trampoline is:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>__sigtramp_siginfo_2</pre> +</div> +</section> +</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">sigaction(2)</a>, <a class="Xr">signal(7)</a>, + <a class="Xr">condvar(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">April 29, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/sockopt.9 3.html b/static/netbsd/man9/sockopt.9 3.html new file mode 100644 index 00000000..75fa4080 --- /dev/null +++ b/static/netbsd/man9/sockopt.9 3.html @@ -0,0 +1,157 @@ +<table class="head"> + <tr> + <td class="head-ltitle">SOCKOPT(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">SOCKOPT(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">sockopt_init</code>, + <code class="Nm">sockopt_destroy</code>, + <code class="Nm">sockopt_get</code>, <code class="Nm">sockopt_getint</code>, + <code class="Nm">sockopt_set</code>, <code class="Nm">sockopt_setint</code> + — <span class="Nd">socket options handling</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/socketvar.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sockopt_init</code>(<var class="Fa" style="white-space: nowrap;">struct + sockopt *sopt</var>, <var class="Fa" style="white-space: nowrap;">int + level</var>, <var class="Fa" style="white-space: nowrap;">int name</var>, + <var class="Fa" style="white-space: nowrap;">size_t size</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">sockopt_destroy</code>(<var class="Fa" style="white-space: nowrap;">struct + sockopt *sopt</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sockopt_get</code>(<var class="Fa" style="white-space: nowrap;">struct + sockopt *sopt</var>, <var class="Fa" style="white-space: nowrap;">void + *value</var>, <var class="Fa" style="white-space: nowrap;">size_t + size</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sockopt_getint</code>(<var class="Fa" style="white-space: nowrap;">struct + sockopt *sopt</var>, <var class="Fa" style="white-space: nowrap;">int + *value</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sockopt_set</code>(<var class="Fa" style="white-space: nowrap;">struct + sockopt *sopt</var>, <var class="Fa" style="white-space: nowrap;">const void + *value</var>, <var class="Fa" style="white-space: nowrap;">size_t + size</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sockopt_setint</code>(<var class="Fa" style="white-space: nowrap;">struct + sockopt *sopt</var>, <var class="Fa" style="white-space: nowrap;">int + value</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <var class="Ft">sockopt</var> structure is used to pass a + socket option and associated value:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>struct sockopt { + int sopt_level; /* option level */ + int sopt_name; /* option name */ + size_t sopt_size; /* data length */ + size_t sopt_retsize; /* returned data length */ + void * sopt_data; /* data pointer */ + uint8_t sopt_buf[sizeof(int)]; /* internal storage */ +};</pre> +</div> +<p class="Pp">The internal storage is used for the common case of values up to + integer size so that memory allocation is not required and sopt_data will + point to this in that case.</p> +<p class="Pp">Rather than provide accessor functions, the + <var class="Ft">sockopt</var> structure is public and the contents are + expected to be internally consistent, but the normal practice would be to + use the appropriate methods for storage and retrieval of values where a + known datatype is expected, as the size will be verified.</p> +<p class="Pp">Note: a sockopt structure may only be used for a single + level/name/size combination. If the structure is to be re-used, it must be + destroyed and re-initialized with the new values.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="OPTIONS"><a class="permalink" href="#OPTIONS">OPTIONS</a></h1> +<dl class="Bl-tag"> + <dt><code class="Cd">options DIAGNOSTIC</code></dt> + <dd>Kernels compiled with the <code class="Dv">DIAGNOSTIC</code> option will + perform basic sanity checks on socket options operations.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="sockopt_init"><a class="permalink" href="#sockopt_init"><code class="Fn">sockopt_init</code></a>(<var class="Fa">sopt</var>, + <var class="Fa">level</var>, <var class="Fa">name</var>, + <var class="Fa">size</var>)</dt> + <dd>Initialise sockopt storage. If <var class="Ar">size</var> is given, + <code class="Fn">sockopt_init</code>() will arrange for sopt_data to point + to a buffer of <var class="Ar">size</var> bytes for the sockopt value. + Where memory needs to be allocated to satisfy this, + <code class="Fn">sockopt_init</code>() may sleep.</dd> + <dt id="sockopt_destroy"><a class="permalink" href="#sockopt_destroy"><code class="Fn">sockopt_destroy</code></a>(<var class="Fa">sopt</var>)</dt> + <dd>Destroy sockopt storage, releasing any allocated memory.</dd> + <dt id="sockopt_get"><a class="permalink" href="#sockopt_get"><code class="Fn">sockopt_get</code></a>(<var class="Fa">sopt</var>, + <var class="Fa">value</var>, <var class="Fa">size</var>)</dt> + <dd>Copy out sockopt value. Will return <code class="Er">EINVAL</code> if an + incorrect data size is given.</dd> + <dt id="sockopt_getint"><a class="permalink" href="#sockopt_getint"><code class="Fn">sockopt_getint</code></a>(<var class="Fa">sopt</var>, + <var class="Fa">value</var>)</dt> + <dd>Common case of get sockopt integer value. Will return + <code class="Er">EINVAL</code> if sockopt does not contain an integer + sized value.</dd> + <dt><code class="Fn">sockopt_set</code>(<var class="Fa">sopt</var>, + <var class="Fa">value</var>, <var class="Fa">size</var>)</dt> + <dd>Copy in sockopt value. The sockopt structure must contain a data field of + <var class="Ar">size</var> bytes or be previously unset, in which case a + data buffer may be allocated using <a class="Xr">kmem_alloc(9)</a> with + the <code class="Dv">KM_NOSLEEP</code> flag which may cause + <code class="Fn">sockopt_set</code>() to return + <code class="Er">ENOMEM</code>. + <p class="Pp" id="sockopt_set">Note: If you need to use + <a class="permalink" href="#sockopt_set"><code class="Fn">sockopt_set</code></a>() + in a context where memory allocation may be required and you do not wish + to contemplate failure, the sockopt structure can be initialised in a + more suitable context using <code class="Fn">sockopt_init</code>() which + will not fail.</p> + </dd> + <dt id="sockopt_setint"><a class="permalink" href="#sockopt_setint"><code class="Fn">sockopt_setint</code></a>(<var class="Fa">sopt</var>, + <var class="Fa">value</var>)</dt> + <dd>Common case of set sockopt integer value. The sockopt structure must + contain an int sized data field or be previously unset, in which case the + data pointer will be set to the internal storage.</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 function prototypes and sockopt structure are defined in the + <span class="Pa">sys/sys/socketvar.h</span> header file, and the socket + options implementation is in + <span class="Pa">sys/kern/uipc_socket.c</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">errno(2)</a>, <a class="Xr">kmem(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The socket options KPI was inspired by a similar KPI in + <span class="Ux">FreeBSD</span> and first appeared in + <span class="Ux">NetBSD 5.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 3, 2018</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/splraise.9 b/static/netbsd/man9/splraise.9 new file mode 100644 index 00000000..800666ac --- /dev/null +++ b/static/netbsd/man9/splraise.9 @@ -0,0 +1,85 @@ +.\" $NetBSD: splraise.9,v 1.1 2010/02/06 22:32:08 dyoung Exp $ +.\" +.\" Copyright (c) 2010 David Young. 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. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 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 February 5, 2010 +.Dt SPLRAISE 9 +.Os +.Sh NAME +.Nm spllower , +.Nm splraise +.Nd modify system interrupt priority level +.Sh SYNOPSIS +.In machine/intr.h +.Ft void +.Fn spllower "int s" +.Ft int +.Fn splraise "int s" +.Sh DESCRIPTION +These functions raise and lower the interrupt priority level +on i386. +They are used by machine-dependent kernel code to implement +the machine-independent +.Xr spl 9 +interface. +.Pp +In a multi-CPU system, these functions change the interrupt +priority level on the local CPU only. +In general, device drivers should not make use of these functions. +.Pp +The +.Fn spllower +function sets the system priority level to the one encoded in +.Fa s , +if +.Fa s +is lower than the current level. +Otherwise, it does not change the level. +Use +.Fn splx +instead +of +.Fn spllower , +except in extraordinary circumstances. +.Pp +The +.Fn splraise +function sets the system priority level to the one encoded in +.Fa s , +if +.Fa s +is greater than the current level, and returns the previous level. +Otherwise, it does not change the level, and it returns the current level. +Except in extraordinary circumstances, +do not use +.Fn splraise . +Use one of the priority-raising functions defined in +.Xr spl 9 , +instead. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr spl 9 diff --git a/static/netbsd/man9/strlist.9 3.html b/static/netbsd/man9/strlist.9 3.html new file mode 100644 index 00000000..8b78bd4c --- /dev/null +++ b/static/netbsd/man9/strlist.9 3.html @@ -0,0 +1,212 @@ +<table class="head"> + <tr> + <td class="head-ltitle">OFSL(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">OFSL(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">strlist</code>, + <code class="Nm">strlist_next</code>, <code class="Nm">strlist_count</code>, + <code class="Nm">strlist_string</code>, + <code class="Nm">strlist_match</code>, + <code class="Nm">strlist_index</code>, + <code class="Nm">strlist_append</code> — <span class="Nd">functions + to interact with OpenFirmware-style string lists</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/systm.h</a>></code></p> +<p class="Pp"><var class="Ft">const char *</var> + <br/> + <code class="Fn">strlist_next</code>(<var class="Fa" style="white-space: nowrap;">const + char *sl</var>, <var class="Fa" style="white-space: nowrap;">size_t + slsize</var>, <var class="Fa" style="white-space: nowrap;">size_t + *cursorp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">strlist_count</code>(<var class="Fa" style="white-space: nowrap;">const + char *sl</var>, <var class="Fa" style="white-space: nowrap;">size_t + slsize</var>);</p> +<p class="Pp"><var class="Ft">const char *</var> + <br/> + <code class="Fn">strlist_string</code>(<var class="Fa" style="white-space: nowrap;">const + char *sl</var>, <var class="Fa" style="white-space: nowrap;">size_t + slsize</var>, <var class="Fa" style="white-space: nowrap;">unsigned int + index</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">strlist_match</code>(<var class="Fa" style="white-space: nowrap;">const + char *sl</var>, <var class="Fa" style="white-space: nowrap;">size_t + slsize</var>, <var class="Fa" style="white-space: nowrap;">const char + *str</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">strlist_pmatch</code>(<var class="Fa" style="white-space: nowrap;">const + char *sl</var>, <var class="Fa" style="white-space: nowrap;">size_t + slsize</var>, <var class="Fa" style="white-space: nowrap;">const char + *pattern</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">strlist_index</code>(<var class="Fa" style="white-space: nowrap;">const + char *sl</var>, <var class="Fa" style="white-space: nowrap;">size_t + slsize</var>, <var class="Fa" style="white-space: nowrap;">const char + *str</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">strlist_append</code>(<var class="Fa" style="white-space: nowrap;">char + **slp</var>, <var class="Fa" style="white-space: nowrap;">size_t + *slsizep</var>, <var class="Fa" style="white-space: nowrap;">const char + *str</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">strlist</code> functions provide a simple way + to interact with OpenFirmware (IEEE 1275) string lists.</p> +<p class="Pp">An OpenFirmware string list is simply a buffer containing one or + more NUL-terminated strings concatenated together. For example, a string + list containing the strings “foo”, “bar”, and + “baz” would be represented in memory as:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>foo\0bar\0baz\0</pre> +</div> +<p class="Pp">The following functions are available:</p> +<dl class="Bl-tag"> + <dt id="strlist_next"><a class="permalink" href="#strlist_next"><code class="Fn">strlist_next</code></a>(<var class="Fa">const + char *sl</var>, <var class="Fa">size_t slsize</var>, <var class="Fa">size_t + *cursorp</var>)</dt> + <dd>This function provides a way to enumerate the strings in a string list. To + enumerate a string list, initialize <var class="Fa">cursor</var> to 0 and + pass it by reference to <code class="Fn">strlist_next</code>(). Each call + to <code class="Fn">strlist_next</code>() returns the current string and + advances the cursor to the next string in the list. If all strings in the + list have been enumerated, <code class="Fn">strlist_next</code>() will + return <code class="Dv">NULL</code>.</dd> + <dt id="strlist_count"><a class="permalink" href="#strlist_count"><code class="Fn">strlist_count</code></a>(<var class="Fa">const + char *sl</var>, <var class="Fa">size_t slsize</var>)</dt> + <dd>Returns the number of strings in the string list.</dd> + <dt id="strlist_string"><a class="permalink" href="#strlist_string"><code class="Fn">strlist_string</code></a>(<var class="Fa">const + char *sl</var>, <var class="Fa">size_t slsize</var>, + <var class="Fa">unsigned int index</var>)</dt> + <dd>Returns a pointer to the string in the string list at the specified index + or <code class="Dv">NULL</code> if the index is out of range.</dd> + <dt id="strlist_match"><a class="permalink" href="#strlist_match"><code class="Fn">strlist_match</code></a>(<var class="Fa">const + char *sl</var>, <var class="Fa">size_t slsize</var>, <var class="Fa">const + char *str</var>)</dt> + <dd>Returns a weighted match value if the specified string appears in the + string list. The value returned is the number of strings in the string + list minus the index of the matched string. For example, if a string list + contains the strings “foo”, “bar”, and + “baz”, a match against “foo” returns 3 and a + match against “baz” returns 1. If the string does not appear + in the string list, 0 is returned.</dd> + <dt id="strlist_pmatch"><a class="permalink" href="#strlist_pmatch"><code class="Fn">strlist_pmatch</code></a>(<var class="Fa">const + char *sl</var>, <var class="Fa">size_t slsize</var>, <var class="Fa">const + char *pattern</var>)</dt> + <dd>Like <code class="Fn">strlist_match</code>(), but uses + <a class="permalink" href="#pmatch"><code class="Fn" id="pmatch">pmatch</code></a>() + to compare strings, allowing for wildcard characters to be specified in + <var class="Fa">pattern</var>.</dd> + <dt id="strlist_index"><a class="permalink" href="#strlist_index"><code class="Fn">strlist_index</code></a>(<var class="Fa">const + char *sl</var>, <var class="Fa">size_t slsize</var>, <var class="Fa">const + char *str</var>)</dt> + <dd>Returns the index of the specified string if it appears in the string + list, or -1 if the string does not appear in the string list.</dd> + <dt id="strlist_append"><a class="permalink" href="#strlist_append"><code class="Fn">strlist_append</code></a>(<var class="Fa">char + **slp</var>, <var class="Fa">size_t *slsizep</var>, <var class="Fa">const + char *str</var>)</dt> + <dd>Appends a copy of the specified string to the stringlist. Begin by + initializing <var class="Fa">sl</var> to <code class="Dv">NULL</code> and + <var class="Fa">slsize</var> to 0. Pass these by reference to + <code class="Fn">strlist_append</code>(). New memory for the string list + will be allocated as needed. The resulting string list can be freed with + <a class="permalink" href="#kmem_free"><code class="Fn" id="kmem_free">kmem_free</code></a>(). + Returns <code class="Dv">true</code> if the string was successfully + appended to the string list or <code class="Dv">false</code> if memory + allocation fails.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> +<p class="Pp">The following shows an example of string list enumeration using + <code class="Fn">strlist_next</code>():</p> +<div class="Bd Pp Li"> +<pre>void +print_stringlist(const char *sl, size_t slsize) +{ + const char *cp; + size_t cursor; + + printf("There are %u strings in the string list:\n", + strlist_count(sl, slsize)); + for (cursor = 0; + (cp = strlist_next(sl, slsize, &cursor) != NULL; ) { + printf("\t%s\n", cp); + } +}</pre> +</div> +<p class="Pp">The following example shows a simple way to use + <code class="Fn">strlist_match</code>():</p> +<div class="Bd Pp Li"> +<pre>bool +is_compatible(int phandle, const char *compat_str) +{ + char buf[128]; + int proplen; + + proplen = OF_getprop(phandle, "compatible", buf, sizeof(buf)); + return strlist_match(buf, proplen, compat_str) != 0; +}</pre> +</div> +<p class="Pp">The following example shows a use of + <code class="Fn">strlist_pmatch</code>():</p> +<div class="Bd Pp Li"> +<pre>bool +is_pc_printer_port(const char *pnp_id_list, size_t list_size) +{ + return strlist_pmatch(pnp_id_list, list_size, "PNP04??") != 0; +}</pre> +</div> +<p class="Pp">The following example converts an array of strings to a string + list using <code class="Fn">strlist_append</code>():</p> +<div class="Bd Pp Li"> +<pre>char * +string_array_to_string_list(const char **array, int count, + size_t *slsizep) +{ + char *sl; + size_t slsize; + int i; + + for (i = 0, sl = NULL, slsize = 0; i < count; i++) { + if (!strlist_append(&sl, &slsize, array[i])) { + kmem_free(sl, slsize); + return NULL; + } + } + + *slsizep = slsize; + return sl; +}</pre> +</div> +</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">kmem(9)</a>, <a class="Xr">pmatch(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The <code class="Nm">strlist</code> functions first appeared in + <span class="Ux">NetBSD 10.0</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 20, 2021</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/tc.9 3.html b/static/netbsd/man9/tc.9 3.html new file mode 100644 index 00000000..ebfdfeed --- /dev/null +++ b/static/netbsd/man9/tc.9 3.html @@ -0,0 +1,185 @@ +<table class="head"> + <tr> + <td class="head-ltitle">TC(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">TC(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">TC</code>, + <code class="Nm">tc_intr_establish</code>, + <code class="Nm">tc_intr_disestablish</code>, + <code class="Nm">tc_intr_evcnt</code>. <code class="Nm">tc_mb</code>, + <code class="Nm">tc_wmb</code>, <code class="Nm">tc_syncbus</code>, + <code class="Nm">tc_badaddr</code>, + <code class="Nm">TC_DENSE_TO_SPARSE</code>, + <code class="Nm">TC_PHYS_TO_UNCACHED</code> — + <span class="Nd">TURBOchannel bus</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/bus.h</a>></code> + <br/> + <code class="In">#include <<a class="In">dev/tc/tcvar.h</a>></code> + <br/> + <code class="In">#include <<a class="In">dev/tc/tcdevs.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tc_intr_establish</code>(<var class="Fa" style="white-space: nowrap;">struct + device *dev</var>, <var class="Fa" style="white-space: nowrap;">void + *cookie</var>, <var class="Fa" style="white-space: nowrap;">int level</var>, + <var class="Fa" style="white-space: nowrap;">int (*handler)(void *)</var>, + <var class="Fa" style="white-space: nowrap;">void *arg</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tc_intr_disestablish</code>(<var class="Fa" style="white-space: nowrap;">struct + device *dev</var>, <var class="Fa" style="white-space: nowrap;">void + *cookie</var>);</p> +<p class="Pp"><var class="Ft">const struct evcnt *</var> + <br/> + <code class="Fn">tc_intr_evcnt</code>(<var class="Fa" style="white-space: nowrap;">struct + device *dev</var>, <var class="Fa" style="white-space: nowrap;">void + *cookie</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tc_mb</code>(<var class="Fa" style="white-space: nowrap;"></var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tc_wmb</code>(<var class="Fa" style="white-space: nowrap;"></var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">tc_syncbus</code>(<var class="Fa" style="white-space: nowrap;"></var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">tc_badaddr</code>(<var class="Fa" style="white-space: nowrap;">tc_addr_t + tcaddr</var>);</p> +<p class="Pp"><var class="Ft">tc_addr_t</var> + <br/> + <code class="Fn">TC_DENSE_TO_SPARSE</code>(<var class="Fa" style="white-space: nowrap;">tc_addr_t + addr</var>);</p> +<p class="Pp"><var class="Ft">tc_addr_t</var> + <br/> + <code class="Fn">TC_PHYS_TO_UNCACHED</code>(<var class="Fa" style="white-space: nowrap;">tc_addr_t + addr</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">TC</code> device provides support for the DEC + TURBOchannel bus found on all DEC TURBOchannel machines with MIPS + (DECstation 5000 series, excluding the 5000/200) and Alpha (3000-series) + systems. TURBOchannel is a 32-bit wide synchronous DMA-capable bus, running + at 25 MHz on higher-end machines and at 12.5 MHz on lower-end machines.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DATA_TYPES"><a class="permalink" href="#DATA_TYPES">DATA + TYPES</a></h1> +<p class="Pp">Drivers for devices attached to the TURBOchannel bus will make use + of the following data types:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">struct tc_attach_args</var></dt> + <dd>A structure use to inform the driver of TURBOchannel bus properties. It + contains the following members: + <div class="Bd Pp Li"> + <pre> bus_space_tag_t ta_memt; + bus_dma_tag_t ta_dmat; + char ta_modname[TC_ROM_LLEN+1]; + u_int ta_slot; + tc_offset_t ta_offset; + tc_addr_t ta_addr; + void *ta_cookie; + u_int ta_busspeed;</pre> + </div> + <p class="Pp" id="ta_busspeed">The + <a class="permalink" href="#ta_busspeed"><i class="Em">ta_busspeed</i></a> + member specifies the TURBOchannel bus speed and is useful for + time-related functions. Values values are + <a class="permalink" href="#TC_SPEED_12_5_MHZ"><i class="Em" id="TC_SPEED_12_5_MHZ">TC_SPEED_12_5_MHZ</i></a> + for the 12.5 MHz bus and + <a class="permalink" href="#TC_SPEED_25_MHZ"><i class="Em" id="TC_SPEED_25_MHZ">TC_SPEED_25_MHZ</i></a> + for the 50 MHz bus.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="tc_intr_establish"><a class="permalink" href="#tc_intr_establish"><code class="Fn">tc_intr_establish</code></a>(<var class="Fa">dev</var>, + <var class="Fa">cookie</var>, <var class="Fa">level</var>, + <var class="Fa">handler</var>, <var class="Fa">arg</var>)</dt> + <dd>Establish an interrupt handler with device <var class="Fa">dev</var> for + the interrupt described completely by <var class="Fa">cookie</var>, the + value passed to the driver in the + <a class="permalink" href="#ta_cookie"><i class="Em" id="ta_cookie">ta_cookie</i></a> + member of the <i class="Em">tc_attach_args</i> structure. The priority of + the interrupt is specified by <var class="Fa">level</var>. When the + interrupt occurs the function <var class="Fa">handler</var> is called with + argument <var class="Fa">arg</var>.</dd> + <dt id="tc_intr_disestablish"><a class="permalink" href="#tc_intr_disestablish"><code class="Fn">tc_intr_disestablish</code></a>(<var class="Fa">dev</var>, + <var class="Fa">cookie</var>)</dt> + <dd>Dis-establish the interrupt handler with device <var class="Fa">dev</var> + for the interrupt described completely <var class="Fa">cookie</var>.</dd> + <dt id="tc_intr_evcnt"><a class="permalink" href="#tc_intr_evcnt"><code class="Fn">tc_intr_evcnt</code></a>(<var class="Fa">dev</var>, + <var class="Fa">cookie</var>)</dt> + <dd>Do interrupt event counting with device <var class="Fa">dev</var> for the + event described completely by <var class="Fa">cookie</var>.</dd> + <dt id="tc_mb"><a class="permalink" href="#tc_mb"><code class="Fn">tc_mb</code></a>(<var class="Fa"></var>)</dt> + <dd>A read/write memory barrier. Any CPU-to-memory reads/writes before the + barrier must complete before any CPU-to-memory reads/writes after it.</dd> + <dt id="tc_wmb"><a class="permalink" href="#tc_wmb"><code class="Fn">tc_wmb</code></a>(<var class="Fa"></var>)</dt> + <dd>A write memory barrier. Any CPU-to-memory writes before the barrier must + complete before any CPU-to-memory writes after it.</dd> + <dt id="tc_syncbus"><a class="permalink" href="#tc_syncbus"><code class="Fn">tc_syncbus</code></a>(<var class="Fa"></var>)</dt> + <dd>Synchronise writes on the TURBOchannel bus by ensuring CPU writes are + propagated across the TURBOchannel bus.</dd> + <dt id="tc_badaddr"><a class="permalink" href="#tc_badaddr"><code class="Fn">tc_badaddr</code></a>(<var class="Fa">tcaddr</var>)</dt> + <dd>Returns non-zero if the given address <var class="Fa">tcaddr</var> is + invalid.</dd> + <dt id="TC_DENSE_TO_SPARSE"><a class="permalink" href="#TC_DENSE_TO_SPARSE"><code class="Fn">TC_DENSE_TO_SPARSE</code></a>(<var class="Fa">addr</var>)</dt> + <dd>Convert the given physical address <var class="Fa">addr</var> in + TURBOchannel dense space to the corresponding address in TURBOchannel + sparse space.</dd> + <dt id="TC_PHYS_TO_UNCACHED"><a class="permalink" href="#TC_PHYS_TO_UNCACHED"><code class="Fn">TC_PHYS_TO_UNCACHED</code></a>(<var class="Fa">addr</var>)</dt> + <dd>Convert the given system memory physical address + <var class="Fa">addr</var> to the physical address of the corresponding + region that is not cached.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTOCONFIGURATION"><a class="permalink" href="#AUTOCONFIGURATION">AUTOCONFIGURATION</a></h1> +<p class="Pp">The TURBOchannel bus is a direct-connection bus. During + autoconfiguration, the parent specifies the name of the found TURBOchannel + module into the <var class="Fa">ta_modname</var> member of the + <i class="Em">tc_attach_args</i> structure. Drivers should match on this + name.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DMA_SUPPORT"><a class="permalink" href="#DMA_SUPPORT">DMA + SUPPORT</a></h1> +<p class="Pp">The TURBOchannel bus supports 32-bit, bidirectional DMA transfers. + Support is provided by the standard <a class="Xr">bus_dma(9)</a> + interface.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The TURBOchannel subsystem itself is implemented within the file + <span class="Pa">sys/dev/tc/tc_subr.c</span>. Machine-dependent portions can + be found in <span class="Pa">sys/arch/<arch>/tc/tcbus.c</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">tc(4)</a>, <a class="Xr">autoconf(9)</a>, + <a class="Xr">bus_dma(9)</a>, <a class="Xr">bus_space(9)</a>, + <a class="Xr">driver(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 7, 2001</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/tcp_congctl.9 3.html b/static/netbsd/man9/tcp_congctl.9 3.html new file mode 100644 index 00000000..5342e324 --- /dev/null +++ b/static/netbsd/man9/tcp_congctl.9 3.html @@ -0,0 +1,87 @@ +<table class="head"> + <tr> + <td class="head-ltitle">TCP_CONGCTL(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">TCP_CONGCTL(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">tcp_congctl</code> — <span class="Nd">TCP + congestion control API</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">netinet/tcp_congctl.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">tcp_congctl_register</code>(<var class="Fa" style="white-space: nowrap;">const + char *</var>, <var class="Fa" style="white-space: nowrap;">struct + tcp_congctl *</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">tcp_congctl_unregister</code>(<var class="Fa" style="white-space: nowrap;">const + char *</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">tcp_congctrl</code> API is used to add or + remove TCP congestion control algorithms on-the-fly and to modularize them. + It includes basically two functions:</p> +<dl class="Bl-tag"> + <dt id="tcp_congctl_register"><a class="permalink" href="#tcp_congctl_register"><code class="Fn">tcp_congctl_register</code></a>(<var class="Fa">const + char *</var>, <var class="Fa">struct tcp_congctl *</var>)</dt> + <dd>Registers a new congestion control algorithm. The <var class="Fa">struct + tcp_congctl</var> argument must contain a list of callbacks like the + following: + <div class="Bd Pp Bd-indent Li"> + <pre>struct tcp_congctl { + int (*fast_retransmit)(struct tcpcb *, + struct tcphdr *); + void (*slow_retransmit)(struct tcpcb *); + void (*fast_retransmit_newack)(struct tcpcb *, + struct tcphdr *); + void (*newack)(struct tcpcb *, + struct tcphdr *); + void (*cong_exp)(struct tcpcb *); +};</pre> + </div> + </dd> + <dt id="tcp_congctl_unregister"><a class="permalink" href="#tcp_congctl_unregister"><code class="Fn">tcp_congctl_unregister</code></a>(<var class="Fa">const + char *</var>)</dt> + <dd>If found, unregister the selected TCP congestion control algorithm.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp"><code class="Fn">tcp_congctl_register</code>() and + <code class="Fn">tcp_congctl_unregister</code>() both return + <code class="Dv">0</code> when there is no error. If the name is already + registered, <code class="Fn">tcp_congctl_register</code>() will return + <code class="Er">EEXIST</code>. + <code class="Fn">tcp_congctl_unregister</code>() can return + <code class="Er">ENOENT</code> if there is no congestion control algorithm + by that name and can return <code class="Er">EBUSY</code> if the matched + algorithm is being used by userspace applications.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<p class="Pp">Implementation is in + <span class="Pa">sys/netinet/tcp_congctl.c</span> and the interface is in + <span class="Pa">sys/netinet/tcp_congctl.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">tcp(4)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">October 15, 2006</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/test_packets.9 b/static/netbsd/man9/test_packets.9 new file mode 100644 index 00000000..72dbac05 --- /dev/null +++ b/static/netbsd/man9/test_packets.9 @@ -0,0 +1,23 @@ +; Test that RRSIG(SOA) is matched with the SOA record. +; Test that FORMERR no longer happens. +; This is output from the PowerDNS online signer. +; +;-- next packet -- +E2C084000001000000040 +0010E686F74656C6C73616E746961676F02736500000F0001C00C0006000100000E10002C036E733 +30662696E65726FC01B087265676973747279C0334EDFD75C0000A8C000000E1000093A8000000E1 +02075616D326963717673707635356136746A306C6C32336B71376E766D666E6136C00C003200010 +0001C2000240100000101AB14D7425114B28CE784C3A3D9B8FC5D920A8D7B5570000762000000000 +290C00C002E000100001C2000A50006080200001C204EE938804ED6C38085F80E686F74656C6C736 +16E746961676F02736500442DF70F92FCFDF5F5D3560194FCDE01B91CE6AC00910CDDA550F985C84 +F4FA1FD8DFD +957F4382C276FD26E5A +3C10C494DCB6D0132F930595A0901D4E0616679EA426F7D45A683CA7236F8532C1E3B3B82EF6B0C0 +2E43999F8B8FF0B001968E10AFAEFA7774FC003ED0E43DDEA776596AFD91DADECA5AD505107F97AC +467264EC05B002E000100001C2000A50032080300001C204EE938804ED6C38085F80E686F74656C6 +C73616E746961676F027365000D4700DE3055046F2CC0529307903D40FEFC7ECFF29BB5B6B7427EB +11B06669605B1ADFC070DAF801FB3EB59446F6C7BE5D4BC7C725BFEF2F5F416BCC8A090692F5CE76 +85923DD102677C9224E69FF10167EF8C0EC18070E986E9F0266C7CBB3270A9CD6C562157EC1074B6 +F48553DD58BBE +12A63202C9A1DB7DA5F8560849580000295800000080000000 + diff --git a/static/netbsd/man9/test_signatures.9 b/static/netbsd/man9/test_signatures.9 new file mode 100644 index 00000000..7f4b350e --- /dev/null +++ b/static/netbsd/man9/test_signatures.9 @@ -0,0 +1,21 @@ +; Signature test file + +; first entry is a DNSKEY answer, with the DNSKEY rrset used for verification. +; later entries are verified with it. + +ENTRY_BEGIN +SECTION QUESTION +nsec.0skar.cz. IN DNSKEY +SECTION ANSWER +nsec.0skar.cz. 297 IN DNSKEY 257 3 10 AwEAAcfJERXDHOSg4JsxSO8WmFdi/PPbtgB6N6xDyyaDqRzr9QCL4LXH yLYjGmriFn7xhVDQTyQQp/nox5RK8YeAFHoiglQuwQVs2TyZTAZskTRj K4NL3+TuMxtCMObzHkAxa0rYvAV5RBh5tdLHUHJLe33xrFNcVidkHMAP F+kjY/9UNi1at2LTohE8VQD0mcv3Gvm79heIjq8Xt3SuqPpk7eQm1r8m 7cIsuojbCum964/H93LeyafExa1eEMhZIIiSG+ik2jDhdeybmMyeoKsO jIL/9N/Yd6u60VkWvUMennyv9rKQTOY84yg2T9yAVjusepggcxMpCVX5 HdWxakruR80= +ENTRY_END + +; entry to test ; note timestamp in 2080. +ENTRY_BEGIN +SECTION QUESTION +nsec.0skar.cz. IN DNSKEY +SECTION ANSWER +nsec.0skar.cz. 297 IN DNSKEY 257 3 10 AwEAAcfJERXDHOSg4JsxSO8WmFdi/PPbtgB6N6xDyyaDqRzr9QCL4LXH yLYjGmriFn7xhVDQTyQQp/nox5RK8YeAFHoiglQuwQVs2TyZTAZskTRj K4NL3+TuMxtCMObzHkAxa0rYvAV5RBh5tdLHUHJLe33xrFNcVidkHMAP F+kjY/9UNi1at2LTohE8VQD0mcv3Gvm79heIjq8Xt3SuqPpk7eQm1r8m 7cIsuojbCum964/H93LeyafExa1eEMhZIIiSG+ik2jDhdeybmMyeoKsO jIL/9N/Yd6u60VkWvUMennyv9rKQTOY84yg2T9yAVjusepggcxMpCVX5 HdWxakruR80= +nsec.0skar.cz. 297 IN RRSIG DNSKEY 10 3 300 20800101000000 20140130121330 28887 nsec.0skar.cz. Ef6Jmf/d9BR0VcRakUD8dEjrMmbAF6qqYRBllLOvibFvpgdEJ7egCO9t d8jliD2VRXhqej2lqECNOvARJ+YyYekpniueiYZsBjleU2kJAyFAS2q3 7aBIii1WdM3h+noayDnjiuhEO3GLxxHWc3kyd2yDesPddiFl09fx+rcz 9BwXaS9A/vdWv+92R1j4nijVI5jxZgkQ4lnD0ZtAVRdBRO7qDRpkRHDM pnaSq51B/9XCZEv2CW8UQ5dGd9D20a3uA2lAKHLgj2/Rcuar4o2Y4ERa ms9pyDCQDhGaveZQdx01EXX0ehe5qIKOKk7iFP95TbWPMRyk1bfKTUoT Rq5rhQ== +ENTRY_END + diff --git a/static/netbsd/man9/tsc.9 b/static/netbsd/man9/tsc.9 new file mode 100644 index 00000000..31d255dc --- /dev/null +++ b/static/netbsd/man9/tsc.9 @@ -0,0 +1,152 @@ +.\" $NetBSD: tsc.9,v 1.8 2017/02/19 11:54:59 wiz Exp $ +.\" +.\" Copyright (c) 2011 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 February 17, 2017 +.Dt TSC 9 x86 +.Os +.Sh NAME +.Nm tsc +.Nd Time Stamp Counter +.Sh SYNOPSIS +.In x86/x86/tsc.h +.Ft uint64_t +.Fn rdtsc "void" +.Ft void +.Fn tsc_tc_init "void" +.Ft void +.Fn tsc_sync_ap "struct cpu_info *ci" +.Ft void +.Fn tsc_sync_bp "struct cpu_info *ci" +.Ft void +.Fn tsc_sync_drift "int64_t drift" +.Sh DESCRIPTION +The time stamp counter +.Pq Tn TSC +is a hardware counter found in all contemporary x86 processors. +The counter is implemented as a 64-bit model-specific register +.Pq Tn MSR +that is incremented at every clock cycle. +The +.Tn RDTSC +.Pq Dq read time stamp counter +register has been present since the original Pentium. +.Pp +Already because of the access method, +.Tn TSC +provides a low-overhead and high-resolution +way to obtain +.Tn CPU +timing information. +This traditional premise was violated when such factors as +system sleep states, +.Tn CPU +.Dq hotplugging , +.Dq hibernation , +and +.Tn CPU +frequency scaling +were introduced to the x86 lineage. +This was however mainly a short abruption: +in many new x86 +.Tn CPUs +the time stamp counter is again invariant with +respect to the stability of the clock frequency. +Care should be however taken in implementations that rely on this assumption. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn rdtsc "" +The +.Fn rdtsc +function returns the value read from +.Dv RDTSC . +.It Fn tsc_tc_init "" +The +.Fn tsc_tc_init +function initializes the +.Tn TSC +as a +.Xr timecounter 9 . +The function is called early in the boot process when the processors attach. +.It Fn tsc_sync_bp "ci" +The +.Fn tsc_sync_bp +function synchronizes the counter for the boot processor +.Pq Tn BP . +The supplied +.Fa ci +must refer to the +.Tn BP +itself. +The +.Nm +interface takes internally care of such issues as out-of-order execution, +where instructions are not necessarily performed in the order of execution, +possibly causing a misleading cycle count. +.It Fn tsc_sync_ap "ci" +The +.Fn tsc_sync_ap +function synchronize the counter for the application processor +.Fa ci . +Interrupts must be off at machine-level when the function is called. +.Pp +It is necessary to call both +.Fn tsc_sync_ap +and +.Fn tsc_sync_bp +during the boot, but additional synchronization +may be required also during runtime. +As an example, the +.Tn TSC +needs to be synchronized for all processors when the system resumes from an +.Xr acpi 4 +sleep state. +.It Fn tsc_sync_drift "drift" +Finally, the +.Fn tsc_sync_drift +function records +.Fa drift , +measured in clock cycles. +This is called when the +.Tn APs +attach. +.El +.\" +.\" Some references that are not worth adding to the actual page: +.\" +.\" http://lwn.net/Articles/209101/ +.\" http://lwn.net/Articles/388188/ +.\" http://lkml.org/lkml/2005/11/4/173 +.\" http://www.ccsl.carleton.ca/~jamuir/rdtscpm1.pdf +.\" +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr hpet 4 , +.Xr hz 9 , +.Xr timecounter 9 , +.Xr x86/rdmsr 9 diff --git a/static/netbsd/man9/ucom.9 3.html b/static/netbsd/man9/ucom.9 3.html new file mode 100644 index 00000000..774d39d3 --- /dev/null +++ b/static/netbsd/man9/ucom.9 3.html @@ -0,0 +1,204 @@ +<table class="head"> + <tr> + <td class="head-ltitle">UCOM(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">UCOM(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">ucom</code> — <span class="Nd">interface + for USB tty like devices</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">ucom</code> driver is a (relatively) easy way + to make a USB device look like a <a class="Xr">tty(4)</a>. It basically + takes two bulk pipes, input and output, and makes a tty out of them. This is + useful for a number of device types, e.g., serial ports (see + <a class="Xr">uftdi(4)</a>), modems (see <a class="Xr">umodem(4)</a>), and + devices that traditionally look like a tty (see + <a class="Xr">uvisor(4)</a>).</p> +<p class="Pp">Communication between the real driver and the + <code class="Nm">ucom</code> driver is via the attachment arguments (when + attached) and via the <var class="Va">ucom_methods</var> struct</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ATTACHMENT"><a class="permalink" href="#ATTACHMENT">ATTACHMENT</a></h1> +<div class="Bd Li"> +<pre>struct ucom_attach_args { + int ucaa_portno; + int ucaa_bulkin; + int ucaa_bulkout; + u_int ucaa_ibufsize; + u_int ucaa_ibufsizepad; + u_int ucaa_obufsize; + u_int ucaa_opkthdrlen; + const char *ucaa_info; + struct usbd_device *ucaa_device; + struct usbd_interface *ucaa_iface; + const struct ucom_methods *ucaa_methods; + void *ucaa_arg; +};</pre> +</div> +<dl class="Bl-tag"> + <dt id="int"><a class="permalink" href="#int"><code class="Dv">int + ucaa_portno</code></a></dt> + <dd>identifies the port if the devices should have more than one + <code class="Nm">ucom</code> attached. Use the value + <code class="Dv">UCOM_UNK_PORTNO</code> if there is only one port.</dd> + <dt id="int~2"><a class="permalink" href="#int~2"><code class="Dv">int + ucaa_bulkin</code></a></dt> + <dd>the number of the bulk input pipe.</dd> + <dt id="int~3"><a class="permalink" href="#int~3"><code class="Dv">int + ucaa_bulkout</code></a></dt> + <dd>the number of the bulk output pipe.</dd> + <dt id="u_int"><a class="permalink" href="#u_int"><code class="Dv">u_int + ucaa_ibufsize</code></a></dt> + <dd>the size of the read requests on the bulk in pipe.</dd> + <dt id="u_int~2"><a class="permalink" href="#u_int~2"><code class="Dv">u_int + ucaa_ibufsizepad</code></a></dt> + <dd>the size of the input buffer. This is usually the same as + <code class="Dv">ibufsize</code>.</dd> + <dt id="u_int~3"><a class="permalink" href="#u_int~3"><code class="Dv">u_int + ucaa_obufsize</code></a></dt> + <dd>the size of the write requests on the bulk out pipe.</dd> + <dt id="u_int~4"><a class="permalink" href="#u_int~4"><code class="Dv">u_int + ucaa_obufsizepad</code></a></dt> + <dd>the size of the output buffer. This is usually the same as + <code class="Dv">ucaa_obufsize</code>.</dd> + <dt id="struct"><a class="permalink" href="#struct"><code class="Dv">struct + usbd_device *ucaa_device</code></a></dt> + <dd>a handle to the device.</dd> + <dt>struct usbd_interface *ucaa_iface</dt> + <dd>a handle to the interface that should be used.</dd> + <dt>struct ucom_methods *ucaa_methods</dt> + <dd>a pointer to the methods that the <code class="Nm">ucom</code> driver + should use for further communication with the driver.</dd> + <dt>void *ucaa_arg</dt> + <dd>the value that should be passed as first argument to each method.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="METHODS"><a class="permalink" href="#METHODS">METHODS</a></h1> +<p class="Pp">The <code class="Dv">ucom_methods</code> struct contains a number + of function pointers used by the <code class="Nm">ucom</code> driver at + various stages. If the device is not interested in being called at a + particular point it should just use a <code class="Dv">NULL</code> pointer + and the <code class="Nm">ucom</code> driver will use a sensible default.</p> +<div class="Bd Pp Li"> +<pre>struct ucom_methods { + void (*ucom_get_status)(void *sc, int portno, + u_char *lsr, u_char *msr); + void (*ucom_set)(void *sc, int portno, int reg, int onoff); +#define UCOM_SET_DTR 1 +#define UCOM_SET_RTS 2 +#define UCOM_SET_BREAK 3 + int (*ucom_param)(void *sc, int portno, struct termios *); + int (*ucom_ioctl)(void *sc, int portno, u_long cmd, + void *data, int flag, proc_t *p); + int (*ucom_open)(void *sc, int portno); + void (*ucom_close)(void *sc, int portno); + void (*ucom_read)(void *sc, int portno, u_char **ptr, + uint32_t *count); + void (*ucom_write)(void *sc, int portno, u_char *to, + u_char *from, uint32_t *count); +};</pre> +</div> +<dl class="Bl-tag"> + <dt><var class="Ft">void</var> + <code class="Fn">(*ucom_get_status)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>, <var class="Fa">u_char *lsr</var>, + <var class="Fa">u_char *msr</var>)</dt> + <dd>get the status of port <var class="Fa">portno</var>. The status consists + of the line status, <var class="Fa">lsr</var>, and the modem status + <var class="Fa">msr</var>. The contents of these two bytes is exactly as + for a 16550 UART.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*ucom_set)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>, <var class="Fa">int reg</var>, + <var class="Fa">int onoff</var>)</dt> + <dd>Set (or unset) a particular feature of a port.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*ucom_param)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>, <var class="Fa">struct termios + *t</var>)</dt> + <dd>Set the speed, number of data bit, stop bits, and parity of a port + according to the <a class="Xr">termios(4)</a> struct.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*ucom_ioctl)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>, <var class="Fa">u_long cmd</var>, + <var class="Fa">void *data</var>, <var class="Fa">int flag</var>, + <var class="Fa">proc_t *p</var>)</dt> + <dd>implements any non-standard <a class="Xr">ioctl(2)</a> that a device + needs.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*ucom_open)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>)</dt> + <dd>called just before the <code class="Nm">ucom</code> driver opens the bulk + pipes for the port.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*ucom_close)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>)</dt> + <dd>called just after the <code class="Nm">ucom</code> driver closes the bulk + pipes for the port.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*ucom_read)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>, <var class="Fa">u_char **ptr</var>, + <var class="Fa">uint32_t *count</var>)</dt> + <dd>if the data delivered on the bulk pipe is not just the raw input + characters this routine needs to increment <var class="Fa">ptr</var> by as + many characters to skip from the start of the raw input and decrement + <var class="Fa">count</var> by as many characters to truncate from the end + of the raw input.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*ucom_write)</code>(<var class="Fa">void *sc</var>, + <var class="Fa">int portno</var>, <var class="Fa">u_char *dst</var>, + <var class="Fa">u_char *src</var>, <var class="Fa">uint32_t + *count</var>)</dt> + <dd>if the data written to the bulk pipe is not just the raw characters then + this routine needs to copy <var class="Fa">count</var> raw characters from + <var class="Fa">src</var> into the buffer at <var class="Fa">dst</var> and + do the appropriate padding. The <var class="Fa">count</var> should be + updated to the new size. The buffer at <var class="Fa">src</var> is at + most <var class="Va">ibufsize</var> bytes and the buffer at + <var class="Fa">dst</var> is <var class="Va">ibufsizepad</var> bytes.</dd> +</dl> +<p class="Pp">Apart from these methods there is a function</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt id="void"><var class="Ft">void</var> + <a class="permalink" href="#void"><code class="Fn">ucom_status_change</code></a>(<var class="Fa">struct + ucom_softc *</var>)</dt> + <dd style="width: auto;"> </dd> +</dl> +</div> +<p class="Pp">which should be called by the driver whenever it notices a status + change.</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">tty(4)</a>, <a class="Xr">u3g(4)</a>, + <a class="Xr">uark(4)</a>, <a class="Xr">ubsa(4)</a>, + <a class="Xr">uchcom(4)</a>, <a class="Xr">uftdi(4)</a>, + <a class="Xr">ugensa(4)</a>, <a class="Xr">uhmodem(4)</a>, + <a class="Xr">uipaq(4)</a>, <a class="Xr">ukyopon(4)</a>, + <a class="Xr">umct(4)</a>, <a class="Xr">umodem(4)</a>, + <a class="Xr">uplcom(4)</a>, <a class="Xr">usb(4)</a>, + <a class="Xr">uslsa(4)</a>, <a class="Xr">uvisor(4)</a>, + <a class="Xr">uvscom(4)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">This <code class="Nm">ucom</code> interface first appeared in + <span class="Ux">NetBSD 1.5</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 12, 2016</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/usbd_status.9 3.html b/static/netbsd/man9/usbd_status.9 3.html new file mode 100644 index 00000000..9b3cad01 --- /dev/null +++ b/static/netbsd/man9/usbd_status.9 3.html @@ -0,0 +1,97 @@ +<table class="head"> + <tr> + <td class="head-ltitle">USBD_STATUS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">USBD_STATUS(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">usbd_status</code> — <span class="Nd">USB + device drivers interface return status values</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">dev/usb/usbdi.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">This documents the full list of return values used by the generic + USB code. Interface-specific definitions will be given with interface.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp">Return values are split into two main groups: expected values and + error values.</p> +<p class="Pp">There are only two expected values:</p> +<dl class="Bl-tag"> + <dt id="USBD_NORMAL_COMPLETION"><a class="permalink" href="#USBD_NORMAL_COMPLETION"><code class="Dv">USBD_NORMAL_COMPLETION</code></a></dt> + <dd>The operation completed successfully.</dd> + <dt id="USBD_IN_PROGRESS"><a class="permalink" href="#USBD_IN_PROGRESS"><code class="Dv">USBD_IN_PROGRESS</code></a></dt> + <dd>The operation was successfully submitted, usually part of an asynchronous + operation.</dd> +</dl> +<p class="Pp">These are the error values:</p> +<dl class="Bl-tag"> + <dt id="USBD_PENDING_REQUESTS"><a class="permalink" href="#USBD_PENDING_REQUESTS"><code class="Dv">USBD_PENDING_REQUESTS</code></a></dt> + <dd>The requested operation could not be completed due to pending requests, + usually from a pipe close operation.</dd> + <dt id="USBD_NOT_STARTED"><a class="permalink" href="#USBD_NOT_STARTED"><code class="Dv">USBD_NOT_STARTED</code></a></dt> + <dd>The initial status of a USB transfer. See <a class="Xr">usbdi(9)</a> for + more details about USB transfers.</dd> + <dt id="USBD_INVAL"><a class="permalink" href="#USBD_INVAL"><code class="Dv">USBD_INVAL</code></a></dt> + <dd>Invalid arguments were supplied for the requested operation.</dd> + <dt id="USBD_NOMEM"><a class="permalink" href="#USBD_NOMEM"><code class="Dv">USBD_NOMEM</code></a></dt> + <dd>No memory could be allocated.</dd> + <dt id="USBD_CANCELLED"><a class="permalink" href="#USBD_CANCELLED"><code class="Dv">USBD_CANCELLED</code></a></dt> + <dd>The USB transfer has been cancelled, and not completed.</dd> + <dt id="USBD_BAD_ADDRESS"><a class="permalink" href="#USBD_BAD_ADDRESS"><code class="Dv">USBD_BAD_ADDRESS</code></a></dt> + <dd>The requested USB pipe could not be found. See <a class="Xr">usbdi(9)</a> + for more details about USB pipes.</dd> + <dt id="USBD_IN_USE"><a class="permalink" href="#USBD_IN_USE"><code class="Dv">USBD_IN_USE</code></a></dt> + <dd>The requested operation could not be performed due to the device having + active connections, such as USB audio device currently playing.</dd> + <dt id="USBD_NO_ADDR"><a class="permalink" href="#USBD_NO_ADDR"><code class="Dv">USBD_NO_ADDR</code></a></dt> + <dd>USB bus has reached its maximum limit of devices.</dd> + <dt id="USBD_SET_ADDR_FAILED"><a class="permalink" href="#USBD_SET_ADDR_FAILED"><code class="Dv">USBD_SET_ADDR_FAILED</code></a></dt> + <dd>Call to <code class="Fn">usbd_set_address</code>() failed during new USB + device discovery.</dd> + <dt id="USBD_NO_POWER"><a class="permalink" href="#USBD_NO_POWER"><code class="Dv">USBD_NO_POWER</code></a></dt> + <dd>New device has requested more power than is available.</dd> + <dt id="USBD_TOO_DEEP"><a class="permalink" href="#USBD_TOO_DEEP"><code class="Dv">USBD_TOO_DEEP</code></a></dt> + <dd>New USB Hub too deep from the root.</dd> + <dt id="USBD_IOERROR"><a class="permalink" href="#USBD_IOERROR"><code class="Dv">USBD_IOERROR</code></a></dt> + <dd>Non-specific error happened during IO.</dd> + <dt id="USBD_NOT_CONFIGURED"><a class="permalink" href="#USBD_NOT_CONFIGURED"><code class="Dv">USBD_NOT_CONFIGURED</code></a></dt> + <dd>USB device is not configured; it has no configuration descriptor.</dd> + <dt id="USBD_TIMEOUT"><a class="permalink" href="#USBD_TIMEOUT"><code class="Dv">USBD_TIMEOUT</code></a></dt> + <dd>Operation timed out.</dd> + <dt id="USBD_SHORT_XFER"><a class="permalink" href="#USBD_SHORT_XFER"><code class="Dv">USBD_SHORT_XFER</code></a></dt> + <dd>USB transfer succeeded but not all requested data was returned.</dd> + <dt id="USBD_STALLED"><a class="permalink" href="#USBD_STALLED"><code class="Dv">USBD_STALLED</code></a></dt> + <dd>USB controller has stalled (controller specific.)</dd> + <dt id="USBD_INTERRUPTED"><a class="permalink" href="#USBD_INTERRUPTED"><code class="Dv">USBD_INTERRUPTED</code></a></dt> + <dd>Process was interrupted by external means (such as a signal) while waiting + for a transfer to complete.</dd> +</dl> +</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">usb(4)</a>, <a class="Xr">usbdi(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">This <code class="Nm">usbd_status</code> interface first appeared + in <span class="Ux">NetBSD 1.4</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 12, 2012</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/usbnet.9 3.html b/static/netbsd/man9/usbnet.9 3.html new file mode 100644 index 00000000..39a68489 --- /dev/null +++ b/static/netbsd/man9/usbnet.9 3.html @@ -0,0 +1,669 @@ +<table class="head"> + <tr> + <td class="head-ltitle">USBNET(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">USBNET(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">usbnet</code> — <span class="Nd">common + USB Ethernet driver 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">dev/usb/usbnet.h</a>></code></p> +<section class="Ss"> +<h2 class="Ss" id="Functions_offered_by_usbnet.h"><a class="permalink" href="#Functions_offered_by_usbnet.h">Functions + offered by usbnet.h</a></h2> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">usbnet_set_link</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>, <var class="Fa" style="white-space: nowrap;">bool + link</var>);</p> +<p class="Pp"><var class="Ft">struct ifnet *</var> + <br/> + <code class="Fn">usbnet_ifp</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">struct ethercom *</var> + <br/> + <code class="Fn">usbnet_ec</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">struct mii_data *</var> + <br/> + <code class="Fn">usbnet_mii</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">krndsource_t *</var> + <br/> + <code class="Fn">usbnet_rndsrc</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">void *</var> + <br/> + <code class="Fn">usbnet_softc</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">usbnet_havelink</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">usbnet_ispromisc</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">usbnet_isdying</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">usbnet_enqueue</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + *buf</var>, <var class="Fa" style="white-space: nowrap;">size_t + buflen</var>, <var class="Fa" style="white-space: nowrap;">int + csum_flags</var>, <var class="Fa" style="white-space: nowrap;">uint32_t + csum_data</var>, <var class="Fa" style="white-space: nowrap;">int + mbuf_flags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">usbnet_input</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>, <var class="Fa" style="white-space: nowrap;">uint8_t + *buf</var>, <var class="Fa" style="white-space: nowrap;">size_t + buflen</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">usbnet_attach</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">usbnet_attach_ifp</code>(<var class="Fa" style="white-space: nowrap;">struct + usbnet *un</var>, <var class="Fa" style="white-space: nowrap;">unsigned + if_flags</var>, <var class="Fa" style="white-space: nowrap;">unsigned + if_extflags</var>, <var class="Fa" style="white-space: nowrap;">const struct + usbnet_mii *unm</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">usbnet_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">usbnet_activate</code>(<var class="Fa" style="white-space: nowrap;">device_t + dev</var>, <var class="Fa" style="white-space: nowrap;">devact_t + act</var>);</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">usbnet</code> framework provides methods + usable for USB Ethernet drivers. The framework has support for these + features:</p> +<ul class="Bl-bullet Bd-indent"> + <li>Partial autoconf handling</li> + <li>USB endpoint pipe handling</li> + <li>Rx and Tx chain handling</li> + <li>Generic handlers or support for several struct ifnet callbacks</li> + <li>Network stack locking protocol</li> + <li>Interrupt handling</li> +</ul> +<p class="Pp"><code class="Nm">usbnet</code> provides many or all of the + traditional “softc” members inside <var class="Va">struct + usbnet</var>, which can be used directly as the device softc structure if no + additional storage is required. A structure exists for receive and transmit + chain management, <var class="Va">struct usbnet_chain</var>, that tracks the + metadata for each transfer descriptor available, minimum of one each for Rx + and Tx slots, and will be passed to the Rx and Tx callbacks.</p> +<p class="Pp">There is a <var class="Va">struct usbnet_ops</var> structure that + provides a number of optional and required callbacks that will be described + below.</p> +<p class="Pp" id="usbnet_attach">For autoconfiguration the device attach routine + is expected to ensure that this device's <var class="Va">struct usbnet</var> + is the first member of the device softc, if it can not be used directly as + the device softc, as well as set up the necessary structure members, find + end-points, find the Ethernet address if relevant, call + <a class="permalink" href="#usbnet_attach"><code class="Fn">usbnet_attach</code></a>(), + set up interface, Ethernet, and MII capabilities, and finally call + <code class="Fn">usbnet_attach_ifp</code>(). The device detach routine + should free any resources allocated by attach and then call + <code class="Fn">usbnet_detach</code>(), possibly directly using + <code class="Fn">usbnet_detach</code>() as most consumers have no additional + resources not owned and released by the <code class="Nm">usbnet</code> + framework itself. The device activate function should be set to + <code class="Fn">usbnet_activate</code>().</p> +<p class="Pp">When bringing an interface up from <a class="Xr">if_init(9)</a>, + which happens under <a class="Xr">IFNET_LOCK(9)</a>, + <code class="Nm">usbnet</code> will:</p> +<ol class="Bl-enum"> + <li>call “uno_init” to initialize the hardware for sending and + receiving packets,</li> + <li>open the USB pipes,</li> + <li>allocate Rx and Tx buffers for transfers,</li> + <li>call “uno_mcast” to initially program the hardware multicast + filter, and finally</li> + <li>start the Rx transfers so packets can be received.</li> +</ol> +<p class="Pp">See the <a class="Sx" href="#RECEIVE_AND_SEND">RECEIVE AND + SEND</a> section for details on using the chains.</p> +<p class="Pp">When bringing an interface down from <a class="Xr">if_stop(9)</a>, + which happens under <a class="Xr">IFNET_LOCK(9)</a>, + <code class="Nm">usbnet</code> will:</p> +<ol class="Bl-enum"> + <li>abort the USB pipes,</li> + <li>call “uno_stop” to stop the hardware from receiving packets + (unless the device is detaching),</li> + <li>free Rx and Tx buffers for transfers, and</li> + <li>close the USB pipes.</li> +</ol> +<p class="Pp">For interface ioctl, most of the handling is in the framework. + While the interface is running, the optional “uno_mcast” + callback is invoked after handling the <code class="Dv">SIOCADDMULTI</code> + and <code class="Dv">SIOCDELMULTI</code> ioctl commands to update the + hardware's multicast filter from the <a class="Xr">ethersubr(9)</a> lists. + The optional “uno_ioctl” callback, which is invoked under + <a class="Xr">IFNET_LOCK(9)</a>, can be used to program special settings + like offload handling.</p> +<p class="Pp" id="ether_ioctl">If ioctl handling requires capturing + device-specific ioctls then the “uno_override_ioctl” callback + may be used instead to replace the framework's ioctl handler completely + (i.e., the replacement should call any generic ioctl handlers such as + <a class="permalink" href="#ether_ioctl"><code class="Fn">ether_ioctl</code></a>() + as required). For sending packets, the “uno_tx_prepare” + callback must be used to convert an mbuf into a chain buffer ready for + transmission.</p> +<p class="Pp">For devices requiring MII handling there are callbacks for reading + and writing registers, and for status change events. Access to all the MII + functions is serialized by <code class="Nm">usbnet</code>.</p> +<p class="Pp" id="usbnet_enqueue">As receive must handle the case of multiple + packets in one buffer, the support is split between the driver and the + framework. A “uno_rx_loop” callback must be provided that + loops over the incoming packet data found in a chain, performs necessary + checking, and passes the network frame up the stack via either + <a class="permalink" href="#usbnet_enqueue"><code class="Fn">usbnet_enqueue</code></a>() + or + <a class="permalink" href="#usbnet_input"><code class="Fn" id="usbnet_input">usbnet_input</code></a>(). + Typically Ethernet devices prefer + <code class="Fn">usbnet_enqueue</code>().</p> +<p class="Pp">General accessor functions for <var class="Fa">struct + usbnet</var>:</p> +<dl class="Bl-tag"> + <dt id="usbnet_set_link"><a class="permalink" href="#usbnet_set_link"><code class="Fn">usbnet_set_link</code></a>(<var class="Fa">un</var>, + <var class="Fa">link</var>)</dt> + <dd>Set the link status for this <var class="Fa">un</var> to + <var class="Fa">link</var>.</dd> + <dt id="usbnet_ifp"><a class="permalink" href="#usbnet_ifp"><code class="Fn">usbnet_ifp</code></a>(<var class="Fa">un</var>)</dt> + <dd>Returns pointer to this <var class="Fa">un</var>'s <var class="Va">struct + ifnet</var>.</dd> + <dt id="usbnet_ec"><a class="permalink" href="#usbnet_ec"><code class="Fn">usbnet_ec</code></a>(<var class="Fa">un</var>)</dt> + <dd>Returns pointer to this <var class="Fa">un</var>'s <var class="Va">struct + ethercom</var>.</dd> + <dt id="usbnet_mii"><a class="permalink" href="#usbnet_mii"><code class="Fn">usbnet_mii</code></a>(<var class="Fa">un</var>)</dt> + <dd>Returns pointer to this <var class="Fa">un</var>'s <var class="Va">struct + mii_data</var>.</dd> + <dt id="usbnet_rndsrc"><a class="permalink" href="#usbnet_rndsrc"><code class="Fn">usbnet_rndsrc</code></a>(<var class="Fa">un</var>)</dt> + <dd>Returns pointer to this <var class="Fa">un</var>'s + <var class="Va">krndsource_t</var>.</dd> + <dt id="usbnet_softc"><a class="permalink" href="#usbnet_softc"><code class="Fn">usbnet_softc</code></a>(<var class="Fa">un</var>)</dt> + <dd>Returns pointer to this <var class="Fa">un</var>'s device softc.</dd> + <dt id="usbnet_havelink"><a class="permalink" href="#usbnet_havelink"><code class="Fn">usbnet_havelink</code></a>(<var class="Fa">un</var>)</dt> + <dd>Returns true if link is active.</dd> + <dt id="usbnet_ispromisc"><a class="permalink" href="#usbnet_ispromisc"><code class="Fn">usbnet_ispromisc</code></a>(<var class="Fa">un</var>)</dt> + <dd>True if <code class="Dv">IFF_PROMISC</code> is enabled, false if not. + <p class="Pp">May be used only in “uno_init” and + “uno_mcast”.</p> + <p class="Pp">Drivers must use this in “uno_mcast” instead of + reading <code class="Li">ifp->if_flags</code>.</p> + </dd> + <dt id="usbnet_isdying"><a class="permalink" href="#usbnet_isdying"><code class="Fn">usbnet_isdying</code></a>(<var class="Fa">un</var>)</dt> + <dd>Returns true if device is dying (has been pulled or deactivated, pending + detach). This should be used only to abort timeout loops early.</dd> +</dl> +<p class="Pp">Buffer enqueue handling for <var class="Fa">struct + usbnet</var>:</p> +<dl class="Bl-tag"> + <dt id="usbnet_enqueue~2"><a class="permalink" href="#usbnet_enqueue~2"><code class="Fn">usbnet_enqueue</code></a>(<var class="Fa">un</var>, + <var class="Fa">buf</var>, <var class="Fa">buflen</var>, + <var class="Fa">csum_flags</var>, <var class="Fa">csum_data</var>, + <var class="Fa">mbuf_flags</var>)</dt> + <dd>Enqueue buffer <var class="Fa">buf</var> for length + <var class="Fa">buflen</var> with higher layers, using the provided + <var class="Fa">csum_flags</var>, and <var class="Fa">csum_data</var>, + which are written directly to the mbuf packet header, and + <var class="Fa">mbuf_flags</var>, which is or-ed into the mbuf flags for + the created mbuf.</dd> + <dt id="usbnet_input~2"><a class="permalink" href="#usbnet_input~2"><code class="Fn">usbnet_input</code></a>(<var class="Fa">un</var>, + <var class="Fa">buf</var>, <var class="Fa">buflen</var>)</dt> + <dd>Enqueue buffer <var class="Fa">buf</var> for length + <var class="Fa">buflen</var> with higher layers.</dd> +</dl> +<p class="Pp">Autoconfiguration handling for <var class="Fa">struct + usbnet</var>. See the + <a class="Sx" href="#AUTOCONFIGURATION">AUTOCONFIGURATION</a> section for + more details about these functions.</p> +<dl class="Bl-tag"> + <dt id="usbnet_attach~2"><a class="permalink" href="#usbnet_attach~2"><code class="Fn">usbnet_attach</code></a>(<var class="Fa">un</var>)</dt> + <dd>Initial stage attach of a USB network device. Performs internal + initialization and memory allocation only — nothing is published + yet.</dd> + <dt><code class="Fn">usbnet_attach_ifp</code>(<var class="Fa">un</var>, + <var class="Fa">if_flags</var>, <var class="Fa">if_extflags</var>, + <var class="Fa">unm</var>)</dt> + <dd>Final stage attach of a USB network device. Publishes the network + interface to the rest of the system. + <p class="Pp" id="mii_attach">If the passed in <var class="Fa">unm</var> is + non-<code class="Dv">NULL</code> then an MII interface will be created + using the values provided in the <var class="Fa">struct usbnet_mii</var> + structure, which has these members passed to + <a class="permalink" href="#mii_attach"><code class="Fn">mii_attach</code></a>():</p> + <dl class="Bl-tag"> + <dt>un_mii_flags</dt> + <dd>Flags.</dd> + <dt>un_mii_capmask</dt> + <dd>Capability mask.</dd> + <dt>un_mii_phyloc</dt> + <dd>PHY location.</dd> + <dt>un_mii_offset</dt> + <dd>PHY offset.</dd> + </dl> + <p class="Pp" id="USBNET_MII_DECL_DEFAULT">A default + <var class="Fa">unm</var> can be set using the + <a class="permalink" href="#USBNET_MII_DECL_DEFAULT"><code class="Fn">USBNET_MII_DECL_DEFAULT</code></a>() + macro. The <var class="Fa">if_flags</var> and + <var class="Fa">if_extflags</var> will be or-ed into the interface flags + and extflags.</p> + </dd> + <dt><code class="Fn">usbnet_detach</code>(<var class="Fa">dev</var>, + <var class="Fa">flags</var>)</dt> + <dd>Device detach. Stops all activity and frees memory. Usable as + <a class="Xr">driver(9)</a> detach method.</dd> + <dt><code class="Fn">usbnet_activate</code>(<var class="Fa">dev</var>, + <var class="Fa">act</var>)</dt> + <dd>Device activate (deactivate) method. Usable as <a class="Xr">driver(9)</a> + activate method.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTOCONFIGURATION"><a class="permalink" href="#AUTOCONFIGURATION">AUTOCONFIGURATION</a></h1> +<p class="Pp">The framework expects the usbnet structure to have these members + filled in with valid values or functions:</p> +<dl class="Bl-tag"> + <dt>un_sc</dt> + <dd>Real softc allocated by autoconf and provided to attach, should be set to + the usbnet structure if no device-specific softc is needed.</dd> + <dt>un_dev</dt> + <dd>device_t saved in attach, used for messages mostly.</dd> + <dt id="usbd_device2interface_handle">un_iface</dt> + <dd>The USB iface handle for data interactions, see + <a class="permalink" href="#usbd_device2interface_handle"><code class="Fn">usbd_device2interface_handle</code></a>() + for more details.</dd> + <dt>un_udev</dt> + <dd>The struct usbd_device for this device, provided as the usb_attach_arg's + <var class="Va">uaa_device</var> member.</dd> + <dt>un_ops</dt> + <dd>Points to a <var class="Va">struct usbnet_ops</var> structure which + contains these members: + <dl class="Bl-tag"> + <dt><var class="Ft">void</var> + <code class="Fn">(*uno_stop)</code>(<var class="Fa">struct ifnet + *ifp</var>, <var class="Fa">int disable</var>)</dt> + <dd>Stop hardware activity (optional). Called under + <a class="Xr">IFNET_LOCK(9)</a> when bringing the interface down, but + skipped when the device is detaching.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*uno_ioctl)</code>(<var class="Fa">struct ifnet + *ifp</var>, <var class="Fa">u_long cmd</var>, <var class="Fa">void + *data</var>)</dt> + <dd>Handle driver-specific ioctls (optional). Called under + <a class="Xr">IFNET_LOCK(9)</a>.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*uno_mcast)</code>(<var class="Fa">struct ifnet + *</var>)</dt> + <dd>Program hardware multicast filters from <a class="Xr">ethersubr(9)</a> + lists (optional). Called between, and not during, + “uno_init” and “uno_stop”.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*uno_override_ioctl)</code>(<var class="Fa">struct + ifnet *ifp</var>, <var class="Fa">u_long cmd</var>, <var class="Fa">void + *data</var>)</dt> + <dd>Handle all ioctls, including standard ethernet ioctls normally handled + internally by <code class="Nm">usbnet</code> (optional). May or may + not be called under <a class="Xr">IFNET_LOCK(9)</a>.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*uno_init)</code>(<var class="Fa">struct ifnet + *ifp</var>)</dt> + <dd>Initialize hardware activity (optional). Called under + <a class="Xr">IFNET_LOCK(9)</a> when bringing the interface up.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*uno_read_reg)</code>(<var class="Fa">struct usbnet + *un</var>, <var class="Fa">int phy</var>, <var class="Fa">int reg</var>, + <var class="Fa">uint16_t *val</var>)</dt> + <dd>Read MII register. Required with MII. Serialized with other MII + functions, and only called after “uno_init” and before + “uno_stop”.</dd> + <dt><var class="Ft">int</var> + <code class="Fn">(*uno_write_reg)</code>(<var class="Fa">struct usbnet + *un</var>, <var class="Fa">int phy</var>, <var class="Fa">int reg</var>, + <var class="Fa">uint16_t val</var>)</dt> + <dd>Write MII register. Required with MII. Serialized with other MII + functions, and only called after “uno_init” and before + “uno_stop”.</dd> + <dt><var class="Ft">usbd_status</var> + <code class="Fn">(*uno_statchg)</code>(<var class="Fa">struct ifnet + *ifp</var>)</dt> + <dd>Handle MII status change. Required with MII. Serialized with other MII + functions, and only called after “uno_init” and before + “uno_stop”.</dd> + <dt><var class="Ft">unsigned</var> + <code class="Fn">(*uno_tx_prepare)</code>(<var class="Fa">struct usbnet + *un</var>, <var class="Fa">struct mbuf *m</var>, <var class="Fa">struct + usbnet_chain *c</var>)</dt> + <dd>Prepare an mbuf for transmit. Required. Called sequentially between, + and not during, “uno_init” and + “uno_stop”.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*uno_rx_loop)</code>(<var class="Fa">struct usbnet + *un</var>, <var class="Fa">struct usbnet_chain *c</var>, + <var class="Fa">uint32_t total_len</var>)</dt> + <dd>Prepare one or more chain for enqueue. Required. Called sequentially + between, and not during, “uno_init” and + “uno_stop”.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*uno_intr)</code>(<var class="Fa">struct usbnet + *un</var>, <var class="Fa">usbd_status status</var>)</dt> + <dd>Process periodic interrupt (optional). Called sequentially between, + and not during, “uno_init” and + “uno_stop”.</dd> + <dt><var class="Ft">void</var> + <code class="Fn">(*uno_tick)</code>(<var class="Fa">struct usbnet + *un</var>)</dt> + <dd>Called every second with USB task thread context (optional). Called + sequentially between, and not during, “uno_init” and + “uno_stop”.</dd> + </dl> + </dd> + <dt>un_intr</dt> + <dd>Points to a <var class="Va">struct usbnet_intr</var> structure which + should have these members set: + <dl class="Bl-tag"> + <dt>uni_buf</dt> + <dd>If non-<code class="Dv">NULL</code>, points to a buffer passed to + <code class="Fn">usbd_open_pipe_intr</code>() in the device init + callback, along with the size and interval.</dd> + <dt>uni_bufsz</dt> + <dd>Size of interrupt pipe buffer.</dd> + <dt>uni_interval</dt> + <dd>Frequency of the interrupt in milliseconds.</dd> + </dl> + </dd> + <dt>un_ed</dt> + <dd>Array of endpoint descriptors. There indexes are provided: + <code class="Dv">USBNET_ENDPT_RX</code>, + <code class="Dv">USBNET_ENDPT_TX</code>, and + <code class="Dv">USBNET_ENDPT_INTR</code>. The Rx and Tx endpoints are + required.</dd> + <dt>un_phyno</dt> + <dd>MII phy number. Not used by <code class="Nm">usbnet</code>.</dd> + <dt>un_eaddr</dt> + <dd>6 bytes of Ethernet address that must be provided before calling + <code class="Fn">usbnet_attach_ifp</code>() if the device has + Ethernet.</dd> + <dt>un_flags</dt> + <dd>Device owned flags word. The <code class="Nm">usbnet</code> framework will + not touch this value.</dd> + <dt id="usbd_setup_xfer">un_rx_xfer_flags</dt> + <dd>Passed to + <a class="permalink" href="#usbd_setup_xfer"><code class="Fn">usbd_setup_xfer</code></a>() + for receiving packets.</dd> + <dt>un_tx_xfer_flags</dt> + <dd>Passed to <code class="Fn">usbd_setup_xfer</code>() for sending + packets.</dd> + <dt>un_rx_list_cnt</dt> + <dd>Number of chain elements to allocate for Rx.</dd> + <dt>un_tx_list_cnt</dt> + <dd>Number of chain elements to allocate for Tx.</dd> + <dt>un_rx_bufsz</dt> + <dd>Rx buffer size.</dd> + <dt>un_tx_bufsz</dt> + <dd>Tx buffer size.</dd> +</dl> +<p class="Pp" id="usbnet_detach">The device detach and activate callbacks can + typically be set to + <a class="permalink" href="#usbnet_detach"><code class="Fn">usbnet_detach</code></a>() + and + <a class="permalink" href="#usbnet_activate"><code class="Fn" id="usbnet_activate">usbnet_activate</code></a>() + unless device-specific handling is required, in which case, they can be + called before or after such handling.</p> +<p class="Pp" id="usbnet_attach_ifp">The capabilities described in both + <var class="Va">struct ifp</var> and <var class="Va">struct ethercom</var> + must be set before calling + <a class="permalink" href="#usbnet_attach_ifp"><code class="Fn">usbnet_attach_ifp</code></a>().</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RECEIVE_AND_SEND"><a class="permalink" href="#RECEIVE_AND_SEND">RECEIVE + AND SEND</a></h1> +<p class="Pp">Receive and send routines are structured around the + <var class="Va">usbnet_cdata</var> and <var class="Va">usbnet_chain</var> + structures, the <code class="Dv">un_ed</code>, + <code class="Dv">un_rx_xfer_flags</code>, and + <code class="Dv">un_tx_xfer_flags</code> members, and the + <code class="Fn">uno_init</code>(), + <code class="Fn">uno_tx_prepare</code>(), + <code class="Fn">uno_rx_loop</code>(), and + <code class="Fn">uno_stop</code>() callbacks of + <var class="Va">usbnet_ops</var>.</p> +<p class="Pp">Typically, the device attach routine will fill in members of the + <var class="Va">usbnet</var> structure, as listed in + <a class="Sx" href="#AUTOCONFIGURATION">AUTOCONFIGURATION</a>. The + <code class="Dv">un_ed</code> array should have the + <code class="Dv">USBNET_ENDPT_RX</code> and + <code class="Dv">USBNET_ENDPT_TX</code> array entries filled in, and + optionally the <code class="Dv">USBNET_ENDPT_INTR</code> entry filled in if + applicable.</p> +<p class="Pp" id="uno_init">The + <a class="permalink" href="#uno_init"><code class="Fn">uno_init</code></a>() + callback enables the hardware, and if necessary reprograms the hardware + multicast filter, before the framework initiates USB Tx/Rx transfers. All + USB transfer setup is handled by the framework. The driver callbacks merely + copy data in or out of a chain entry using what is typically a + device-specific method.</p> +<p class="Pp" id="uno_rx_loop">The + <a class="permalink" href="#uno_rx_loop"><code class="Fn">uno_rx_loop</code></a>() + callback, called sequentially, converts the provided + <var class="Va">usbnet_chain</var> data and length into a series (one or + more) of packets that are enqueued with the higher layers using either + <code class="Fn">usbnet_enqueue</code>() (for most devices) or + <code class="Fn">usbnet_input</code>() for devices that use + <a class="permalink" href="#if_input"><code class="Fn" id="if_input">if_input</code></a>(). + (This currently relies upon the <var class="Va">struct ifnet</var> having + the “_if_input” member set as well, which is true for current + consumers.)</p> +<p class="Pp" id="uno_tx_prepare">The + <a class="permalink" href="#uno_tx_prepare"><code class="Fn">uno_tx_prepare</code></a>() + callback must convert the provided <var class="Va">struct mbuf</var> into + the provided <var class="Va">struct usbnet_chain</var> performing any + device-specific padding, checksum, header or other. Note that this callback + must check that it is not attempting to copy more than the chain buffer + size, as set in the <var class="Va">usbnet</var> “un_tx_bufsz” + member. This callback is only called once per packet, sequentially.</p> +<p class="Pp">The <var class="Fa">struct usbnet_chain</var> structure which + contains a “unc_buf” member which has the chain buffer + allocated where data should be copied to or from for receive or transmit + operations. It also contains pointers back to the owning + <var class="Fa">struct usbnet</var>, and the <var class="Va">struct + usbd_xfer</var> associated with this transfer.</p> +<p class="Pp" id="uno_stop">After aborting all USB Tx/Rx transfers when bringing + an interface down, the framework calls the optional + <a class="permalink" href="#uno_stop"><code class="Fn">uno_stop</code></a>() + callback to disable the hardware.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MII"><a class="permalink" href="#MII">MII</a></h1> +<p class="Pp">For devices that have MII support these callbacks in + <var class="Fa">struct usbnet_ops</var> must be provided:</p> +<dl class="Bl-tag"> + <dt>uno_read_reg</dt> + <dd>Read an MII register for a particular PHY. Returns standard + <a class="Xr">errno(2)</a>. Must initialize the result even on + failure.</dd> + <dt>uno_write_reg</dt> + <dd>Write an MII register for a particular PHY. Returns standard + <a class="Xr">errno(2)</a>.</dd> + <dt>uno_statchg</dt> + <dd>Handle a status change event for this interface.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="INTERRUPT_PIPE"><a class="permalink" href="#INTERRUPT_PIPE">INTERRUPT + PIPE</a></h1> +<p class="Pp">The interrupt-specific callback, “uno_intr”, is an + optional callback that can be called periodically, registered by + <code class="Nm">usbnet</code> using the + <code class="Fn">usbd_open_pipe_intr</code>() function (instead of the + <a class="permalink" href="#usbd_open_pipe"><code class="Fn" id="usbd_open_pipe">usbd_open_pipe</code></a>() + function). The <code class="Nm">usbnet</code> framework provides most of the + interrupt handling and the callback simply inspects the returned buffer as + necessary. To enable this callback point the <var class="Va">struct + usbnet</var> member “un_intr” to a <var class="Va">struct + usbnet_intr</var> structure with these members set:</p> +<dl class="Bl-tag"> + <dt>uni_buf</dt> + <dd>Data buffer for interrupt status replies.</dd> + <dt>uni_bufsz</dt> + <dd>Size of the above buffer.</dd> + <dt>uni_interval</dt> + <dd>Interval in millieconds.</dd> +</dl> +<p class="Pp" id="usbd_open_pipe_intr">These values will be passed to + <a class="permalink" href="#usbd_open_pipe_intr"><code class="Fn">usbd_open_pipe_intr</code></a>().</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CONVERTING_OLD-STYLE_DRIVERS"><a class="permalink" href="#CONVERTING_OLD-STYLE_DRIVERS">CONVERTING + OLD-STYLE DRIVERS</a></h1> +<p class="Pp">The porting of an older driver to the + <code class="Nm">usbnet</code> framework is largely an effort in deleting + code. The process involves making these changes:</p> +<dl class="Bl-tag"> + <dt>Headers</dt> + <dd>Many headers are included in <span class="Pa">usbnet.h</span> and can be + removed from the driver, as well as headers no longer used, such as + <span class="Pa">callout.h</span> and <span class="Pa">rndsource.h</span>, + etc.</dd> + <dt>Device softc</dt> + <dd>The majority of the driver's existing “softc” structure can + likely be replaced with usage of <var class="Va">struct usbnet</var> and + its related functionality. This includes at least the device_t pointer, + Ethernet address, the ethercom and mii_data structures, end point + descriptors, usbd device, interface, and task and callout structures (both + these probably go away entirely) and all the associated watchdog handling, + timevals, list size, buffer size and xfer flags for both Rx, and Tx, and + interrupt notices, interface flags, device link, PHY number, chain data, + locks including Rx, Tx, and MII. There is a driver-only + “un_flags” in the <var class="Va">usbnet</var> structure + available for drivers to use. + <p class="Pp" id="usbd_do_request">Many drivers can use the + <var class="Va">usbnet</var> structure as the device private storage + passed to <code class="Dv">CFATTACH_DECL_NEW</code>. Many internal + functions to the driver may look better if switched to operate on the + device's <var class="Va">usbnet</var> as, for example, the + <var class="Va">usbd_device</var> value is now available (and must be + set by the driver) in the <var class="Va">usbnet</var>, which may be + needed for any call to + <a class="permalink" href="#usbd_do_request"><code class="Fn">usbd_do_request</code></a>(). + The standard endpoint values must be stored in the + <code class="Nm">usbnet</code> “un_ed[]” array.</p> + <p class="Pp">As <code class="Nm">usbnet</code> manages xfer chains all code + related to the opening, closing, aborting and transferring of data on + pipes is performed by the framework based upon the buffer size and more + provided in <var class="Va">subnet</var>, so all code related to them + should be deleted.</p> + </dd> + <dt id="usbnet_attach_ifp~2">Interface setup</dt> + <dd>The vast majority of interface-specific code should be deleted. For + device-specific interface values, the <var class="Va">ifnet</var> flags + and exflags can be set, as well as the <var class="Va">ethercom</var> + “ec_capabilities” member, before calling + <a class="permalink" href="#usbnet_attach_ifp~2"><code class="Fn">usbnet_attach_ifp</code></a>(). + All calls to + <a class="permalink" href="#ifmedia_init"><code class="Fn" id="ifmedia_init">ifmedia_init</code></a>(), + <code class="Fn">mii_attach</code>(), + <a class="permalink" href="#ifmedia_add"><code class="Fn" id="ifmedia_add">ifmedia_add</code></a>(), + <a class="permalink" href="#ifmedia_set"><code class="Fn" id="ifmedia_set">ifmedia_set</code></a>(), + <a class="permalink" href="#if_attach"><code class="Fn" id="if_attach">if_attach</code></a>(), + <a class="permalink" href="#ether_ifattach"><code class="Fn" id="ether_ifattach">ether_ifattach</code></a>(), + <a class="permalink" href="#rnd_attach_source"><code class="Fn" id="rnd_attach_source">rnd_attach_source</code></a>(), + and + <a class="permalink" href="#usbd_add_drv_event"><code class="Fn" id="usbd_add_drv_event">usbd_add_drv_event</code></a>() + should be eliminated. The device “ioctl” routine can use the + default handling with a callback for additional device-specific + programming (multicast filters, etc.), which can be empty, or, the + override ioctl can be used for heavier requirements. The device + “stop” routine is replaced with a simple call that turns off + the device-specific transmitter and receiver if necessary, as the + framework handles pipes and transfers and buffers.</dd> + <dt>MII handling</dt> + <dd>For devices with MII support the three normal callbacks (read, write, and + status change) must be converted to <var class="Va">usbnet</var>. Local + “link” variables need to be replaced with accesses to + <code class="Fn">usbnet_set_link</code>() and + <code class="Fn">usbnet_havelink</code>(). Other ifmedia callbacks that + were passed to <code class="Fn">ifmedia_init</code>() should be deleted + and any work moved into “uno_statchg”.</dd> + <dt id="usbnet_init_rx_tx">Receive and Transmit</dt> + <dd>The <code class="Nm">usbnet</code> framework handles the majority of + handling of both network directions. The interface init routine should + keep all of the device-specific setup but replace all pipe management with + a call to + <a class="permalink" href="#usbnet_init_rx_tx"><code class="Fn">usbnet_init_rx_tx</code></a>(). + The typical receive handling will normally be replaced with a receive loop + function that can accept one or more packets, “uno_rx_loop”, + which can use either <code class="Fn">usbnet_enqueue</code>() or + <code class="Fn">usbnet_input</code>() to pass the packets up to higher + layers. The typical interface “if_start” function and any + additional functions used will normally be replaced with a relatively + simple “uno_tx_prepare” function that simply converts an + <var class="Va">mbuf</var> into a <var class="Va">usbnet_chain</var> + useful for this device that will be passed onto + <a class="permalink" href="#usbd_transfer"><code class="Fn" id="usbd_transfer">usbd_transfer</code></a>(). + The framework's handling of the Tx interrupt is all internal.</dd> + <dt>Interrupt pipe handling</dt> + <dd>For devices requiring special handling of the interrupt pipe (i.e., they + use the <code class="Fn">usbd_open_pipe_intr</code>() method), most of the + interrupt handler should be deleted, leaving only code that inspects the + result of the interrupt transfer.</dd> + <dt>Common errors</dt> + <dd>It's common to forget to set link active on devices with MII. Be sure to + call <code class="Fn">usbnet_set_link</code>() during any status change + event. + <p class="Pp">Many locking issues are hidden without + <code class="Dv">LOCKDEBUG</code>, including hard-hangs. It's highly + recommended to develop with <code class="Dv">LOCKDEBUG</code>.</p> + <p class="Pp">The <var class="Va">usbnet</var> “un_ed” array + is unsigned and should use “0” as the no-endpoint + value.</p> + </dd> +</dl> +</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">usb(4)</a>, <a class="Xr">driver(9)</a>, + <a class="Xr">usbd_status(9)</a>, <a class="Xr">usbdi(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">This <code class="Nm">usbnet</code> interface first appeared in + <span class="Ux">NetBSD 9.0</span>. Portions of the original design are + based upon ideas from <span class="An">Nick Hudson</span> + <<a class="Mt" href="mailto:skrll@NetBSD.org">skrll@NetBSD.org</a>>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Matthew R. Green</span> + <<a class="Mt" href="mailto:mrg@eterna23.net">mrg@eterna23.net</a>></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 15, 2020</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/uvm.9 3.html b/static/netbsd/man9/uvm.9 3.html new file mode 100644 index 00000000..19108045 --- /dev/null +++ b/static/netbsd/man9/uvm.9 3.html @@ -0,0 +1,580 @@ +<table class="head"> + <tr> + <td class="head-ltitle">UVM(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">UVM(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">uvm</code> — <span class="Nd">virtual + memory system external interface</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">uvm/uvm.h</a>></code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The UVM virtual memory system manages access to the computer's + memory resources. User processes and the kernel access these resources + through UVM's external interface. UVM's external interface includes + functions that:</p> +<p class="Pp"></p> +<ul class="Bl-dash Bl-compact"> + <li>initialize UVM sub-systems</li> + <li>manage virtual address spaces</li> + <li>resolve page faults</li> + <li>memory map files and devices</li> + <li>perform uio-based I/O to virtual memory</li> + <li>allocate and free kernel virtual memory</li> + <li>allocate and free physical memory</li> +</ul> +<p class="Pp">In addition to exporting these services, UVM has two kernel-level + processes: pagedaemon and swapper. The pagedaemon process sleeps until + physical memory becomes scarce. When that happens, pagedaemon is awoken. It + scans physical memory, paging out and freeing memory that has not been + recently used. The swapper process swaps in runnable processes that are + currently swapped out, if there is room.</p> +<p class="Pp">There are also several miscellaneous functions.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="INITIALIZATION"><a class="permalink" href="#INITIALIZATION">INITIALIZATION</a></h1> +<dl class="Bl-ohang"> + <dt id="uvm_init"><var class="Ft">void</var></dt> + <dd><a class="permalink" href="#uvm_init"><code class="Fn">uvm_init</code></a>(<var class="Fa">void</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_init_limits</code>(<var class="Fa">struct lwp + *l</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_setpagesize</code>(<var class="Fa">void</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_swap_init</code>(<var class="Fa">void</var>);</dd> +</dl> +<p class="Pp" id="uvm_init~2"><a class="permalink" href="#uvm_init~2"><code class="Fn">uvm_init</code></a>() + sets up the UVM system at system boot time, after the console has been + setup. It initializes global state, the page, map, kernel virtual memory + state, machine-dependent physical map, kernel memory allocator, pager and + anonymous memory sub-systems, and then enables paging of kernel objects.</p> +<p class="Pp" id="uvm_init_limits"><a class="permalink" href="#uvm_init_limits"><code class="Fn">uvm_init_limits</code></a>() + initializes process limits for the named process. This is for use by the + system startup for process zero, before any other processes are created.</p> +<p class="Pp" id="uvm_md_init"><a class="permalink" href="#uvm_md_init"><code class="Fn">uvm_md_init</code></a>() + does early boot initialization. This currently includes: + <a class="permalink" href="#uvm_setpagesize"><code class="Fn" id="uvm_setpagesize">uvm_setpagesize</code></a>() + which initializes the uvmexp members pagesize (if not already done by + machine-dependent code), pageshift and pagemask. + <a class="permalink" href="#uvm_physseg_init"><code class="Fn" id="uvm_physseg_init">uvm_physseg_init</code></a>() + which initialises the <a class="Xr">uvm_hotplug(9)</a> subsystem. It should + be called by machine-dependent code early in the + <a class="permalink" href="#pmap_init"><code class="Fn" id="pmap_init">pmap_init</code></a>() + call (see <a class="Xr">pmap(9)</a>).</p> +<p class="Pp" id="uvm_swap_init"><a class="permalink" href="#uvm_swap_init"><code class="Fn">uvm_swap_init</code></a>() + initializes the swap sub-system.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="VIRTUAL_ADDRESS_SPACE_MANAGEMENT"><a class="permalink" href="#VIRTUAL_ADDRESS_SPACE_MANAGEMENT">VIRTUAL + ADDRESS SPACE MANAGEMENT</a></h1> +<p class="Pp">See <a class="Xr">uvm_map(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="PAGE_FAULT_HANDLING"><a class="permalink" href="#PAGE_FAULT_HANDLING">PAGE + FAULT HANDLING</a></h1> +<dl class="Bl-ohang"> + <dt><var class="Ft">int</var></dt> + <dd><code class="Fn">uvm_fault</code>(<var class="Fa">struct vm_map + *orig_map</var>, <var class="Fa">vaddr_t vaddr</var>, + <var class="Fa">vm_prot_t access_type</var>);</dd> +</dl> +<p class="Pp" id="uvm_fault"><a class="permalink" href="#uvm_fault"><code class="Fn">uvm_fault</code></a>() + is the main entry point for faults. It takes <var class="Fa">orig_map</var> + as the map the fault originated in, a <var class="Fa">vaddr</var> offset + into the map the fault occurred, and <var class="Fa">access_type</var> + describing the type of access requested. <code class="Fn">uvm_fault</code>() + returns a standard UVM return value.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MEMORY_MAPPING_FILES_AND_DEVICES"><a class="permalink" href="#MEMORY_MAPPING_FILES_AND_DEVICES">MEMORY + MAPPING FILES AND DEVICES</a></h1> +<p class="Pp">See <a class="Xr">ubc(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="VIRTUAL_MEMORY_I/O"><a class="permalink" href="#VIRTUAL_MEMORY_I/O">VIRTUAL + MEMORY I/O</a></h1> +<dl class="Bl-ohang"> + <dt><var class="Ft">int</var></dt> + <dd><code class="Fn">uvm_io</code>(<var class="Fa">struct vm_map *map</var>, + <var class="Fa">struct uio *uio</var>);</dd> +</dl> +<p class="Pp" id="uvm_io"><a class="permalink" href="#uvm_io"><code class="Fn">uvm_io</code></a>() + performs the I/O described in <var class="Fa">uio</var> on the memory + described in <var class="Fa">map</var>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ALLOCATION_OF_KERNEL_MEMORY"><a class="permalink" href="#ALLOCATION_OF_KERNEL_MEMORY">ALLOCATION + OF KERNEL MEMORY</a></h1> +<p class="Pp">See <a class="Xr">uvm_km(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ALLOCATION_OF_PHYSICAL_MEMORY"><a class="permalink" href="#ALLOCATION_OF_PHYSICAL_MEMORY">ALLOCATION + OF PHYSICAL MEMORY</a></h1> +<dl class="Bl-ohang"> + <dt><var class="Ft">struct vm_page *</var></dt> + <dd><code class="Fn">uvm_pagealloc</code>(<var class="Fa">struct uvm_object + *uobj</var>, <var class="Fa">voff_t off</var>, <var class="Fa">struct + vm_anon *anon</var>, <var class="Fa">int flags</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_pagerealloc</code>(<var class="Fa">struct vm_page + *pg</var>, <var class="Fa">struct uvm_object *newobj</var>, + <var class="Fa">voff_t newoff</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_pagefree</code>(<var class="Fa">struct vm_page + *pg</var>);</dd> + <dt><var class="Ft">int</var></dt> + <dd><code class="Fn">uvm_pglistalloc</code>(<var class="Fa">psize_t + size</var>, <var class="Fa">paddr_t low</var>, <var class="Fa">paddr_t + high</var>, <var class="Fa">paddr_t alignment</var>, + <var class="Fa">paddr_t boundary</var>, <var class="Fa">struct pglist + *rlist</var>, <var class="Fa">int nsegs</var>, <var class="Fa">int + waitok</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_pglistfree</code>(<var class="Fa">struct pglist + *list</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_page_physload</code>(<var class="Fa">paddr_t + start</var>, <var class="Fa">paddr_t end</var>, <var class="Fa">paddr_t + avail_start</var>, <var class="Fa">paddr_t avail_end</var>, + <var class="Fa">int free_list</var>);</dd> +</dl> +<p class="Pp" id="uvm_pagealloc"><a class="permalink" href="#uvm_pagealloc"><code class="Fn">uvm_pagealloc</code></a>() + allocates a page of memory at virtual address <var class="Fa">off</var> in + either the object <var class="Fa">uobj</var> or the anonymous memory + <var class="Fa">anon</var>, which must be locked by the caller. Only one of + <var class="Fa">uobj</var> and <var class="Fa">anon</var> can be non + <code class="Dv">NULL</code>. Returns <code class="Dv">NULL</code> when no + page can be found. The flags can be any of</p> +<div class="Bd Pp Li"> +<pre>#define UVM_PGA_USERESERVE 0x0001 /* ok to use reserve pages */ +#define UVM_PGA_ZERO 0x0002 /* returned page must be zero'd */</pre> +</div> +<p class="Pp"><code class="Dv">UVM_PGA_USERESERVE</code> means to allocate a + page even if that will result in the number of free pages being lower than + <code class="Dv">uvmexp.reserve_pagedaemon</code> (if the current thread is + the pagedaemon) or <code class="Dv">uvmexp.reserve_kernel</code> (if the + current thread is not the pagedaemon). <code class="Dv">UVM_PGA_ZERO</code> + causes the returned page to be filled with zeroes, either by allocating it + from a pool of pre-zeroed pages or by zeroing it in-line as necessary.</p> +<p class="Pp" id="uvm_pagerealloc"><a class="permalink" href="#uvm_pagerealloc"><code class="Fn">uvm_pagerealloc</code></a>() + reallocates page <var class="Fa">pg</var> to a new object + <var class="Fa">newobj</var>, at a new offset + <var class="Fa">newoff</var>.</p> +<p class="Pp" id="uvm_pagefree"><a class="permalink" href="#uvm_pagefree"><code class="Fn">uvm_pagefree</code></a>() + frees the physical page <var class="Fa">pg</var>. If the content of the page + is known to be zero-filled, caller should set + <code class="Dv">PG_ZERO</code> in pg->flags so that the page allocator + will use the page to serve future <code class="Dv">UVM_PGA_ZERO</code> + requests efficiently.</p> +<p class="Pp" id="uvm_pglistalloc"><a class="permalink" href="#uvm_pglistalloc"><code class="Fn">uvm_pglistalloc</code></a>() + allocates a list of pages for size <var class="Fa">size</var> byte under + various constraints. <var class="Fa">low</var> and + <var class="Fa">high</var> describe the lowest and highest addresses + acceptable for the list. If <var class="Fa">alignment</var> is non-zero, it + describes the required alignment of the list, in power-of-two notation. If + <var class="Fa">boundary</var> is non-zero, no segment of the list may cross + this power-of-two boundary, relative to zero. <var class="Fa">nsegs</var> is + the maximum number of physically contiguous segments. If + <var class="Fa">waitok</var> is non-zero, the function may sleep until + enough memory is available. (It also may give up in some situations, so a + non-zero <var class="Fa">waitok</var> does not imply that + <code class="Fn">uvm_pglistalloc</code>() cannot return an error.) The + allocated memory is returned in the <var class="Fa">rlist</var> list; the + caller has to provide storage only, the list is initialized by + <code class="Fn">uvm_pglistalloc</code>().</p> +<p class="Pp" id="uvm_pglistfree"><a class="permalink" href="#uvm_pglistfree"><code class="Fn">uvm_pglistfree</code></a>() + frees the list of pages pointed to by <var class="Fa">list</var>. If the + content of the page is known to be zero-filled, caller should set + <code class="Dv">PG_ZERO</code> in pg->flags so that the page allocator + will use the page to serve future <code class="Dv">UVM_PGA_ZERO</code> + requests efficiently.</p> +<p class="Pp" id="uvm_page_physload"><a class="permalink" href="#uvm_page_physload"><code class="Fn">uvm_page_physload</code></a>() + loads physical memory segments into VM space on the specified + <var class="Fa">free_list</var>. It must be called at system boot time to + set up physical memory management pages. The arguments describe the + <var class="Fa">start</var> and <var class="Fa">end</var> of the physical + addresses of the segment, and the available start and end addresses of pages + not already in use. If a system has memory banks of different speeds the + slower memory should be given a higher <var class="Fa">free_list</var> + value.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="PROCESSES"><a class="permalink" href="#PROCESSES">PROCESSES</a></h1> +<dl class="Bl-ohang"> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_pageout</code>(<var class="Fa">void</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_scheduler</code>(<var class="Fa">void</var>);</dd> +</dl> +<p class="Pp" id="uvm_pageout"><a class="permalink" href="#uvm_pageout"><code class="Fn">uvm_pageout</code></a>() + is the main loop for the page daemon.</p> +<p class="Pp" id="uvm_scheduler"><a class="permalink" href="#uvm_scheduler"><code class="Fn">uvm_scheduler</code></a>() + is the process zero main loop, which is to be called after the system has + finished starting other processes. It handles the swapping in of runnable, + swapped out processes in priority order.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="PAGE_LOAN"><a class="permalink" href="#PAGE_LOAN">PAGE + LOAN</a></h1> +<dl class="Bl-ohang"> + <dt><var class="Ft">int</var></dt> + <dd><code class="Fn">uvm_loan</code>(<var class="Fa">struct vm_map *map</var>, + <var class="Fa">vaddr_t start</var>, <var class="Fa">vsize_t len</var>, + <var class="Fa">void *v</var>, <var class="Fa">int flags</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_unloan</code>(<var class="Fa">void *v</var>, + <var class="Fa">int npages</var>, <var class="Fa">int flags</var>);</dd> +</dl> +<p class="Pp" id="uvm_loan"><a class="permalink" href="#uvm_loan"><code class="Fn">uvm_loan</code></a>() + loans pages in a map out to anons or to the kernel. + <var class="Fa">map</var> should be unlocked, <var class="Fa">start</var> + and <var class="Fa">len</var> should be multiples of + <code class="Dv">PAGE_SIZE</code>. Argument <var class="Fa">flags</var> + should be one of</p> +<div class="Bd Pp Li"> +<pre>#define UVM_LOAN_TOANON 0x01 /* loan to anons */ +#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */</pre> +</div> +<p class="Pp" id="uvm_loan~2"><var class="Fa">v</var> should be pointer to array + of pointers to <code class="Li">struct anon</code> or + <code class="Li">struct vm_page</code>, as appropriate. The caller has to + allocate memory for the array and ensure it's big enough to hold + <var class="Fa">len / PAGE_SIZE</var> pointers. Returns 0 for success, or + appropriate error number otherwise. Note that wired pages can't be loaned + out and + <a class="permalink" href="#uvm_loan~2"><code class="Fn">uvm_loan</code></a>() + will fail in that case.</p> +<p class="Pp" id="uvm_unloan"><a class="permalink" href="#uvm_unloan"><code class="Fn">uvm_unloan</code></a>() + kills loans on pages or anons. The <var class="Fa">v</var> must point to the + array of pointers initialized by previous call to + <code class="Fn">uvm_loan</code>(). <var class="Fa">npages</var> should + match number of pages allocated for loan, this also matches number of items + in the array. Argument <var class="Fa">flags</var> should be one of</p> +<div class="Bd Pp Li"> +<pre>#define UVM_LOAN_TOANON 0x01 /* loan to anons */ +#define UVM_LOAN_TOPAGE 0x02 /* loan to kernel */</pre> +</div> +<p class="Pp" id="uvm_loan~3">and should match what was used for previous call + to + <a class="permalink" href="#uvm_loan~3"><code class="Fn">uvm_loan</code></a>().</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MISCELLANEOUS_FUNCTIONS"><a class="permalink" href="#MISCELLANEOUS_FUNCTIONS">MISCELLANEOUS + FUNCTIONS</a></h1> +<dl class="Bl-ohang"> + <dt><var class="Ft">struct uvm_object *</var></dt> + <dd><code class="Fn">uao_create</code>(<var class="Fa">vsize_t size</var>, + <var class="Fa">int flags</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uao_detach</code>(<var class="Fa">struct uvm_object + *uobj</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uao_reference</code>(<var class="Fa">struct uvm_object + *uobj</var>);</dd> + <dt><var class="Ft">bool</var></dt> + <dd><code class="Fn">uvm_chgkprot</code>(<var class="Fa">void *addr</var>, + <var class="Fa">size_t len</var>, <var class="Fa">int rw</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_kernacc</code>(<var class="Fa">void *addr</var>, + <var class="Fa">size_t len</var>, <var class="Fa">int rw</var>);</dd> + <dt><var class="Ft">int</var></dt> + <dd><code class="Fn">uvm_vslock</code>(<var class="Fa">struct vmspace + *vs</var>, <var class="Fa">void *addr</var>, <var class="Fa">size_t + len</var>, <var class="Fa">vm_prot_t prot</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_vsunlock</code>(<var class="Fa">struct vmspace + *vs</var>, <var class="Fa">void *addr</var>, <var class="Fa">size_t + len</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_meter</code>(<var class="Fa">void</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_proc_fork</code>(<var class="Fa">struct proc + *p1</var>, <var class="Fa">struct proc *p2</var>, <var class="Fa">bool + shared</var>);</dd> + <dt><var class="Ft">int</var></dt> + <dd><code class="Fn">uvm_grow</code>(<var class="Fa">struct proc *p</var>, + <var class="Fa">vaddr_t sp</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvn_findpages</code>(<var class="Fa">struct uvm_object + *uobj</var>, <var class="Fa">voff_t offset</var>, <var class="Fa">int + *npagesp</var>, <var class="Fa">struct vm_page **pps</var>, + <var class="Fa">int flags</var>);</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_vnp_setsize</code>(<var class="Fa">struct vnode + *vp</var>, <var class="Fa">voff_t newsize</var>);</dd> +</dl> +<p class="Pp" id="uao_create">The + <a class="permalink" href="#uao_create"><code class="Fn">uao_create</code></a>(), + <a class="permalink" href="#uao_detach"><code class="Fn" id="uao_detach">uao_detach</code></a>(), + and <code class="Fn">uao_reference</code>() functions operate on anonymous + memory objects, such as those used to support System V shared memory. + <code class="Fn">uao_create</code>() returns an object of size + <var class="Fa">size</var> with flags:</p> +<div class="Bd Pp Li"> +<pre>#define UAO_FLAG_KERNOBJ 0x1 /* create kernel object */ +#define UAO_FLAG_KERNSWAP 0x2 /* enable kernel swap */</pre> +</div> +<p class="Pp" id="uao_reference">which can only be used once each at system boot + time. + <a class="permalink" href="#uao_reference"><code class="Fn">uao_reference</code></a>() + creates an additional reference to the named anonymous memory object. + <a class="permalink" href="#uao_detach~2"><code class="Fn" id="uao_detach~2">uao_detach</code></a>() + removes a reference from the named anonymous memory object, destroying it if + removing the last reference.</p> +<p class="Pp" id="uvm_chgkprot"><a class="permalink" href="#uvm_chgkprot"><code class="Fn">uvm_chgkprot</code></a>() + changes the protection of kernel memory from <var class="Fa">addr</var> to + <var class="Fa">addr + len</var> to the value of <var class="Fa">rw</var>. + This is primarily useful for debuggers, for setting breakpoints. This + function is only available with options <code class="Dv">KGDB</code>.</p> +<p class="Pp" id="uvm_kernacc"><a class="permalink" href="#uvm_kernacc"><code class="Fn">uvm_kernacc</code></a>() + checks the access at address <var class="Fa">addr</var> to + <var class="Fa">addr + len</var> for <var class="Fa">rw</var> access in the + kernel address space.</p> +<p class="Pp" id="uvm_vslock"><a class="permalink" href="#uvm_vslock"><code class="Fn">uvm_vslock</code></a>() + and + <a class="permalink" href="#uvm_vsunlock"><code class="Fn" id="uvm_vsunlock">uvm_vsunlock</code></a>() + control the wiring and unwiring of pages for process <var class="Fa">p</var> + from <var class="Fa">addr</var> to <var class="Fa">addr + len</var>. These + functions are normally used to wire memory for I/O.</p> +<p class="Pp" id="uvm_meter"><a class="permalink" href="#uvm_meter"><code class="Fn">uvm_meter</code></a>() + calculates the load average.</p> +<p class="Pp" id="uvm_proc_fork"><a class="permalink" href="#uvm_proc_fork"><code class="Fn">uvm_proc_fork</code></a>() + forks a virtual address space for process' (old) <var class="Fa">p1</var> + and (new) <var class="Fa">p2</var>. If the <var class="Fa">shared</var> + argument is non zero, p1 shares its address space with p2, otherwise a new + address space is created. This function currently has no return value, and + thus cannot fail. In the future, this function will be changed to allow it + to fail in low memory conditions.</p> +<p class="Pp" id="uvm_grow"><a class="permalink" href="#uvm_grow"><code class="Fn">uvm_grow</code></a>() + increases the stack segment of process <var class="Fa">p</var> to include + <var class="Fa">sp</var>.</p> +<p class="Pp" id="uvn_findpages"><a class="permalink" href="#uvn_findpages"><code class="Fn">uvn_findpages</code></a>() + looks up or creates pages in <var class="Fa">uobj</var> at offset + <var class="Fa">offset</var>, marks them busy and returns them in the + <var class="Fa">pps</var> array. Currently <var class="Fa">uobj</var> must + be a vnode object. The number of pages requested is pointed to by + <var class="Fa">npagesp</var>, and this value is updated with the actual + number of pages returned. The flags can be any bitwise inclusive-or of:</p> +<p class="Pp"></p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt id="UFP_ALL"><a class="permalink" href="#UFP_ALL"><code class="Dv">UFP_ALL</code></a></dt> + <dd>Zero pseudo-flag meaning return all pages.</dd> + <dt id="UFP_NOWAIT"><a class="permalink" href="#UFP_NOWAIT"><code class="Dv">UFP_NOWAIT</code></a></dt> + <dd>Don't sleep — yield <code class="Dv">NULL</code> for busy pages or + for uncached pages for which allocation would sleep.</dd> + <dt id="UFP_NOALLOC"><a class="permalink" href="#UFP_NOALLOC"><code class="Dv">UFP_NOALLOC</code></a></dt> + <dd>Don't allocate — yield <code class="Dv">NULL</code> for uncached + pages.</dd> + <dt id="UFP_NOCACHE"><a class="permalink" href="#UFP_NOCACHE"><code class="Dv">UFP_NOCACHE</code></a></dt> + <dd>Don't use cached pages — yield <code class="Dv">NULL</code> + instead.</dd> + <dt id="UFP_NORDONLY"><a class="permalink" href="#UFP_NORDONLY"><code class="Dv">UFP_NORDONLY</code></a></dt> + <dd>Don't yield read-only pages — yield <code class="Dv">NULL</code> + for pages marked <code class="Dv">PG_READONLY</code>.</dd> + <dt id="UFP_DIRTYONLY"><a class="permalink" href="#UFP_DIRTYONLY"><code class="Dv">UFP_DIRTYONLY</code></a></dt> + <dd>Don't yield clean pages — stop early at the first clean one. As a + side effect, mark yielded dirty pages clean. Caller must write them to + permanent storage before unbusying.</dd> + <dt id="UFP_BACKWARD"><a class="permalink" href="#UFP_BACKWARD"><code class="Dv">UFP_BACKWARD</code></a></dt> + <dd>Traverse pages in reverse order. If + <a class="permalink" href="#uvn_findpages~2"><code class="Fn" id="uvn_findpages~2">uvn_findpages</code></a>() + returns early, it will have filled + <code class="Li">*</code><var class="Fa">npagesp</var> entries at the end + of <var class="Fa">pps</var> rather than the beginning.</dd> +</dl> +</div> +<p class="Pp" id="uvm_vnp_setsize"><a class="permalink" href="#uvm_vnp_setsize"><code class="Fn">uvm_vnp_setsize</code></a>() + sets the size of vnode <var class="Fa">vp</var> to + <var class="Fa">newsize</var>. Caller must hold a reference to the vnode. If + the vnode shrinks, pages no longer used are discarded.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="MISCELLANEOUS_MACROS"><a class="permalink" href="#MISCELLANEOUS_MACROS">MISCELLANEOUS + MACROS</a></h1> +<dl class="Bl-ohang"> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">atop</code>(<var class="Fa">paddr_t pa</var>);</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">ptoa</code>(<var class="Fa">paddr_t pn</var>);</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">round_page</code>(<var class="Fa">address</var>);</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">trunc_page</code>(<var class="Fa">address</var>);</dd> +</dl> +<p class="Pp" id="atop">The + <a class="permalink" href="#atop"><code class="Fn">atop</code></a>() macro + converts a physical address <var class="Fa">pa</var> into a page number. The + <a class="permalink" href="#ptoa"><code class="Fn" id="ptoa">ptoa</code></a>() + macro does the opposite by converting a page number <var class="Fa">pn</var> + into a physical address.</p> +<p class="Pp" id="round_page"><a class="permalink" href="#round_page"><code class="Fn">round_page</code></a>() + and + <a class="permalink" href="#trunc_page"><code class="Fn" id="trunc_page">trunc_page</code></a>() + macros return a page address boundary from rounding + <var class="Fa">address</var> up and down, respectively, to the nearest page + boundary. These macros work for either addresses or byte counts.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYSCTL"><a class="permalink" href="#SYSCTL">SYSCTL</a></h1> +<p class="Pp">UVM provides support for the <code class="Dv">CTL_VM</code> domain + of the <a class="Xr">sysctl(3)</a> hierarchy. It handles the + <code class="Dv">VM_LOADAVG</code>, <code class="Dv">VM_METER</code>, + <code class="Dv">VM_UVMEXP</code>, and <code class="Dv">VM_UVMEXP2</code> + nodes, which return the current load averages, calculates current VM totals, + returns the uvmexp structure, and a kernel version independent view of the + uvmexp structure, respectively. It also exports a number of tunables that + control how much VM space is allowed to be consumed by various tasks. The + load averages are typically accessed from userland using the + <a class="Xr">getloadavg(3)</a> function. The uvmexp structure has all + global state of the UVM system, and has the following members:</p> +<div class="Bd Pp Li"> +<pre>/* vm_page constants */ +int pagesize; /* size of a page (PAGE_SIZE): must be power of 2 */ +int pagemask; /* page mask */ +int pageshift; /* page shift */ + +/* vm_page counters */ +int npages; /* number of pages we manage */ +int free; /* number of free pages */ +int paging; /* number of pages in the process of being paged out */ +int wired; /* number of wired pages */ +int reserve_pagedaemon; /* number of pages reserved for pagedaemon */ +int reserve_kernel; /* number of pages reserved for kernel */ + +/* pageout params */ +int freemin; /* min number of free pages */ +int freetarg; /* target number of free pages */ +int inactarg; /* target number of inactive pages */ +int wiredmax; /* max number of wired pages */ + +/* swap */ +int nswapdev; /* number of configured swap devices in system */ +int swpages; /* number of PAGE_SIZE'ed swap pages */ +int swpginuse; /* number of swap pages in use */ +int nswget; /* number of times fault calls uvm_swap_get() */ +int nanon; /* number total of anon's in system */ +int nfreeanon; /* number of free anon's */ + +/* stat counters */ +int faults; /* page fault count */ +int traps; /* trap count */ +int intrs; /* interrupt count */ +int swtch; /* context switch count */ +int softs; /* software interrupt count */ +int syscalls; /* system calls */ +int pageins; /* pagein operation count */ + /* pageouts are in pdpageouts below */ +int pgswapin; /* pages swapped in */ +int pgswapout; /* pages swapped out */ +int forks; /* forks */ +int forks_ppwait; /* forks where parent waits */ +int forks_sharevm; /* forks where vmspace is shared */ + +/* fault subcounters */ +int fltnoram; /* number of times fault was out of ram */ +int fltnoanon; /* number of times fault was out of anons */ +int fltpgwait; /* number of times fault had to wait on a page */ +int fltpgrele; /* number of times fault found a released page */ +int fltrelck; /* number of times fault relock called */ +int fltrelckok; /* number of times fault relock is a success */ +int fltanget; /* number of times fault gets anon page */ +int fltanretry; /* number of times fault retrys an anon get */ +int fltamcopy; /* number of times fault clears "needs copy" */ +int fltnamap; /* number of times fault maps a neighbor anon page */ +int fltnomap; /* number of times fault maps a neighbor obj page */ +int fltlget; /* number of times fault does a locked pgo_get */ +int fltget; /* number of times fault does an unlocked get */ +int flt_anon; /* number of times fault anon (case 1a) */ +int flt_acow; /* number of times fault anon cow (case 1b) */ +int flt_obj; /* number of times fault is on object page (2a) */ +int flt_prcopy; /* number of times fault promotes with copy (2b) */ +int flt_przero; /* number of times fault promotes with zerofill (2b) */ + +/* daemon counters */ +int pdwoke; /* number of times daemon woke up */ +int pdrevs; /* number of times daemon rev'd clock hand */ +int pdfreed; /* number of pages daemon freed since boot */ +int pdscans; /* number of pages daemon scanned since boot */ +int pdanscan; /* number of anonymous pages scanned by daemon */ +int pdobscan; /* number of object pages scanned by daemon */ +int pdreact; /* number of pages daemon reactivated since boot */ +int pdbusy; /* number of times daemon found a busy page */ +int pdpageouts; /* number of times daemon started a pageout */ +int pddeact; /* number of pages daemon deactivates */</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp"><code class="Fn">uvm_chgkprot</code>() is only available if the + kernel has been compiled with options <code class="Dv">KGDB</code>.</p> +<p class="Pp">All structure and types whose names begin with “vm_” + will be renamed to “uvm_”.</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">swapctl(2)</a>, <a class="Xr">getloadavg(3)</a>, + <a class="Xr">kvm(3)</a>, <a class="Xr">sysctl(3)</a>, + <a class="Xr">ddb(4)</a>, <a class="Xr">options(4)</a>, + <a class="Xr">memoryallocators(9)</a>, <a class="Xr">pmap(9)</a>, + <a class="Xr">ubc(9)</a>, <a class="Xr">uvm_km(9)</a>, + <a class="Xr">uvm_map(9)</a></p> +<p class="Pp"><cite class="Rs"><span class="RsA">Charles D. Cranor</span> and + <span class="RsA">Gurudatta M. Parulkar</span>, <span class="RsT">The UVM + Virtual Memory System</span>, <i class="RsB">Proceedings of the USENIX + Annual Technical Conference</i>, <i class="RsI">USENIX Association</i>, + <a class="RsU" href="http://www.usenix.org/event/usenix99/full_papers/cranor/cranor.pdf">http://www.usenix.org/event/usenix99/full_papers/cranor/cranor.pdf</a>, + <span class="RsP">117-130</span>, <span class="RsD">June 6-11, + 1999</span>.</cite></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">UVM is a new VM system developed at Washington University in St. + Louis (Missouri). UVM's roots lie partly in the Mach-based + <span class="Ux">4.4BSD</span> VM system, the + <span class="Ux">FreeBSD</span> VM system, and the SunOS 4 VM system. UVM's + basic structure is based on the <span class="Ux">4.4BSD</span> VM system. + UVM's new anonymous memory system is based on the anonymous memory system + found in the SunOS 4 VM (as described in papers published by Sun + Microsystems, Inc.). UVM also includes a number of features new to + <span class="Ux">BSD</span> including page loanout, map entry passing, + simplified copy-on-write, and clustered anonymous memory pageout. UVM is + also further documented in an August 1998 dissertation by Charles D. + Cranor.</p> +<p class="Pp">UVM appeared in <span class="Ux">NetBSD 1.4</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Charles D. Cranor</span> + <<a class="Mt" href="mailto:chuck@ccrc.wustl.edu">chuck@ccrc.wustl.edu</a>> + designed and implemented UVM.</p> +<p class="Pp"><span class="An">Matthew Green</span> + <<a class="Mt" href="mailto:mrg@eterna23.net">mrg@eterna23.net</a>> + wrote the swap-space management code and handled the logistical issues + involved with merging UVM into the <span class="Ux">NetBSD</span> source + tree.</p> +<p class="Pp"><span class="An">Chuck Silvers</span> + <<a class="Mt" href="mailto:chuq@chuq.com">chuq@chuq.com</a>> + implemented the aobj pager, thus allowing UVM to support System V shared + memory and process swapping.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 23, 2015</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/uvm_hotplug.9 3.html b/static/netbsd/man9/uvm_hotplug.9 3.html new file mode 100644 index 00000000..d42fe4b1 --- /dev/null +++ b/static/netbsd/man9/uvm_hotplug.9 3.html @@ -0,0 +1,443 @@ +<table class="head"> + <tr> + <td class="head-ltitle">UVM_HOTPLUG(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">UVM_HOTPLUG(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">uvm_physseg_init</code>, + <code class="Nm">uvm_physseg_valid_p</code>, + <code class="Nm">uvm_physseg_get_start</code>, + <code class="Nm">uvm_physseg_get_end</code>, + <code class="Nm">uvm_physseg_get_avail_start</code>, + <code class="Nm">uvm_physseg_get_avail_end</code>, + <code class="Nm">uvm_physseg_get_pg</code>, + <code class="Nm">uvm_physseg_get_pmseg</code>, + <code class="Nm">uvm_physseg_get_free_list</code>, + <code class="Nm">uvm_physseg_get_start_hint</code>, + <code class="Nm">uvm_physseg_set_start_hint</code>, + <code class="Nm">uvm_physseg_get_next</code>, + <code class="Nm">uvm_physseg_get_prev</code>, + <code class="Nm">uvm_physseg_get_first</code>, + <code class="Nm">uvm_physseg_get_last</code>, + <code class="Nm">uvm_physseg_get_highest_frame</code>, + <code class="Nm">uvm_physseg_find</code>, + <code class="Nm">uvm_page_physload</code>, + <code class="Nm">uvm_page_physunload</code>, + <code class="Nm">uvm_page_physunload_force</code>, + <code class="Nm">uvm_physseg_plug</code>, + <code class="Nm">uvm_physseg_unplug</code>, + <code class="Nm">uvm_physseg_set_avail_start</code>, + <code class="Nm">uvm_physseg_set_avail_end</code> — + <span class="Nd">memory hotplug manager</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">uvm/uvm_physseg.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">uvm_physseg_init</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">uvm_physseg_t</var> + <br/> + <code class="Fn">uvm_page_physload</code>(<var class="Fa" style="white-space: nowrap;">paddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">paddr_t end</var>, + <var class="Fa" style="white-space: nowrap;">paddr_t avail_start</var>, + <var class="Fa" style="white-space: nowrap;">paddr_t avail_end</var>, + <var class="Fa" style="white-space: nowrap;">int free_list</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">uvm_page_physunload</code>(<var class="Fa" style="white-space: nowrap;">uvm_physseg_t + upm</var>, <var class="Fa" style="white-space: nowrap;">int free_list</var>, + <var class="Fa" style="white-space: nowrap;">paddr_t *paddrp</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">uvm_page_physunload_force</code>(<var class="Fa" style="white-space: nowrap;">uvm_physseg_t + upm</var>, <var class="Fa" style="white-space: nowrap;">int free_list</var>, + <var class="Fa" style="white-space: nowrap;">paddr_t *paddrp</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">uvm_physseg_plug</code>(<var class="Fa" style="white-space: nowrap;">paddr_t + pfn</var>, <var class="Fa" style="white-space: nowrap;">size_t npages</var>, + <var class="Fa" style="white-space: nowrap;">uvm_physseg_t *upmp</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">uvm_physseg_unplug</code>(<var class="Fa" style="white-space: nowrap;">paddr_t + pfn</var>, <var class="Fa" style="white-space: nowrap;">size_t + npages</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">These utility routines provide the ability to tell + <a class="Xr">uvm(9)</a> about system memory segments. When the kernel is + compiled with <code class="Cd">'options UVM_HOTPLUG'</code>, memory segments + are handled in a dynamic data structure (<a class="Xr">rbtree(3)</a>) + compared to a static array when not. This enables kernel code to add or + remove information about memory segments at any point after boot - thus + "hotplug".</p> +<p class="Pp" id="uvm_page_physload"><a class="permalink" href="#uvm_page_physload"><code class="Fn">uvm_page_physload</code></a>(), + <code class="Fn">uvm_page_physunload</code>(), and + <code class="Fn">uvm_page_physunload_force</code>() are legacy interfaces + which may be removed in the future. They must never be used after + <a class="Xr">uvm_init(9)</a>.</p> +<p class="Pp" id="WARNING"><a class="permalink" href="#WARNING"><b class="Sy">WARNING</b></a>: + This is an experimental feature and should not be used in production + environments. Furthermore, attempting to "hotplug" without + <code class="Cd">'options UVM_HOTPLUG'</code> after boot will almost + certainly end in a <a class="Xr">panic(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="USAGE"><a class="permalink" href="#USAGE">USAGE</a></h1> +<section class="Ss"> +<h2 class="Ss" id="INITIALIZING_HOTPLUG"><a class="permalink" href="#INITIALIZING_HOTPLUG">INITIALIZING + HOTPLUG</a></h2> +<p class="Pp">The function + <a class="permalink" href="#uvm_physseg_init"><code class="Fn" id="uvm_physseg_init">uvm_physseg_init</code></a>() + initializes the hotplug subsystem. This is expected to happen exactly once, + at boot time, and from MD code.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="PLUGGING_IN_MEMORY"><a class="permalink" href="#PLUGGING_IN_MEMORY">PLUGGING + IN MEMORY</a></h2> +<p class="Pp"><code class="Fn">uvm_page_physload</code>() registers + <a class="Xr">uvm(9)</a> with a memory segment span, and on a specified + <var class="Fa">free_list</var>. It must be called at system boot time as + part of setting up memory management. The arguments describe the start and + end of the physical addresses of the segment, and the available start and + end addresses of pages not already in use. If a system has memory banks of + different speeds the slower memory should be given a higher + <var class="Fa">free_list</var> value.</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt><var class="Fa">start</var></dt> + <dd>Starting page frame number of the physical memory segments.</dd> + <dt><var class="Fa">end</var></dt> + <dd>Ending page frame number of the physical memory segments.</dd> + <dt><var class="Fa">avail_start</var></dt> + <dd>Available starting page frame number of the physical memory segments.</dd> + <dt><var class="Fa">avail_end</var></dt> + <dd>Available ending page frame number of the physical memory segments.</dd> + <dt><var class="Fa">free_list</var></dt> + <dd>The free list types are defined in the Machine Dependent code.</dd> +</dl> +</div> +<p class="Pp">This function returns a valid + <code class="Dv">uvm_physseg_t</code> handle when a successful plug occurs, + else it will return <code class="Dv">UVM_PHYSSEG_TYPE_INVALID</code> when + the plug fails.</p> +<p class="Pp" id="uvm_physseg_plug"><a class="permalink" href="#uvm_physseg_plug"><code class="Fn">uvm_physseg_plug</code></a>() + registers <a class="Xr">uvm(9)</a> with a memory segment span. It can also + be called to initiate a hotplug and register a newly "hotplugged" + physical memory range into the VM. Unlike + <code class="Fn">uvm_page_physload</code>() this function can, if + <code class="Cd">'options UVM_HOTPLUG'</code> is enabled at compile time, be + used after <a class="Xr">uvm_init(9)</a>. The arguments describe the start + page frame, the number of pages to plug starting from the start page frame + and an optional return variable, which points to a valid + <var class="Fa">uvm_physseg_t</var> handle when a successful plug + occurs.</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt><var class="Fa">pfn</var></dt> + <dd>Starting page frame number of the physical memory segment.</dd> + <dt><var class="Fa">npages</var></dt> + <dd>Total number of pages from the starting page frame number to plug in.</dd> + <dt><var class="Fa">upmp</var></dt> + <dd>If upmp is not <code class="Dv">NULL</code>, then on a successful plug, a + valid pointer to the uvm_physseg_t handle for the segment which was + plugged is returned.</dd> +</dl> +</div> +<p class="Pp">This function returns <var class="Fa">true</var> when a successful + plug occurs, <var class="Fa">false</var> otherwise.</p> +</section> +<section class="Ss"> +<h2 class="Ss" id="UNPLUGGING_MEMORY"><a class="permalink" href="#UNPLUGGING_MEMORY">UNPLUGGING + MEMORY</a></h2> +<p class="Pp">The functions + <a class="permalink" href="#uvm_page_physunload"><code class="Fn" id="uvm_page_physunload">uvm_page_physunload</code></a>(), + <code class="Fn">uvm_page_physunload_force</code>(), and + <code class="Fn">uvm_physseg_unplug</code>() make <a class="Xr">uvm(9)</a> + forget about previously registered memory segments or portions of such.</p> +<p class="Pp" id="uvm_page_physunload~2"><a class="permalink" href="#uvm_page_physunload~2"><code class="Fn">uvm_page_physunload</code></a>() + unloads pages from a segment (from the front or from the back) depending on + its availability. When the last page is removed, the segment handle is + invalidated and supporting metadata is freed.</p> +<p class="Pp" id="uvm_page_physunload~3">Note: This function can only be used + during boot time. Pages, once unloaded, are unregistered from uvm and are + therefore assumed to be managed by the code which called + <a class="permalink" href="#uvm_page_physunload~3"><code class="Fn">uvm_page_physunload</code></a>(<var class="Fa">9</var>) + (usually boot time MD code, for boottime memory "allocation").</p> +<p class="Pp">The arguments are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt><var class="Fa">upm</var></dt> + <dd>The handle identifying segment from which we are trying to unload + memory.</dd> + <dt><var class="Fa">free_list</var></dt> + <dd>The free list types are defined in the Machine Dependent code.</dd> + <dt><var class="Fa">paddrp</var></dt> + <dd>The pointer to the physical address that was unloaded.</dd> +</dl> +</div> +<p class="Pp">If the unload was successful, <var class="Fa">true</var> is + returned, <var class="Fa">false</var> otherwise.</p> +<p class="Pp" id="uvm_page_physunload_force"><a class="permalink" href="#uvm_page_physunload_force"><code class="Fn">uvm_page_physunload_force</code></a>() + unconditionally unloads pages from a segment. When the last page is removed, + the segment handle is invalidated and supporting metadata is freed.</p> +<p class="Pp" id="uvm_page_physunload_force~2">Note: This function can only be + used during boot time. Pages, once unloaded, are unregistered from uvm and + are therefore assumed to be managed by the code which called + <a class="permalink" href="#uvm_page_physunload_force~2"><code class="Fn">uvm_page_physunload_force</code></a>(<var class="Fa">9</var>) + (usually boot time MD code, for boottime memory "allocation").</p> +<p class="Pp">The arguments are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt><var class="Fa">upm</var></dt> + <dd>The handle identifying segment from which we are trying to unload + memory.</dd> + <dt><var class="Fa">free_list</var></dt> + <dd>The free list types are defined in the Machine Dependent code.</dd> + <dt><var class="Fa">paddrp</var></dt> + <dd>The pointer to the physical address that was unloaded.</dd> +</dl> +</div> +<p class="Pp">If the unload was successful <var class="Fa">true</var> is + returned, <var class="Fa">false</var> otherwise.</p> +<p class="Pp" id="uvm_physseg_unplug"><a class="permalink" href="#uvm_physseg_unplug"><code class="Fn">uvm_physseg_unplug</code></a>() + can be called to unplug an existing physical memory segment. Unlike + <code class="Fn">uvm_page_physunload</code>() and + <code class="Fn">uvm_page_physunload_force</code>(), it can be called after + <a class="Xr">uvm_init(9)</a>, if <code class="Cd">'options + UVM_HOTPLUG'</code> is enabled at compile time. + <a class="permalink" href="#uvm_hotplug"><code class="Fn" id="uvm_hotplug">uvm_hotplug</code></a>(<var class="Fa">9</var>) + makes no effort to manage the state of the underlying physical memory. It is + up to the caller to ensure that it is not in use, either by + <a class="Xr">uvm(9)</a>, or by any other sub-system. Further, any hardware + quiescing that may be required is the responsibility of MD code. The + arguments describe the start page frame and the number of pages to unplug. + The arguments are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt><var class="Fa">pfn</var></dt> + <dd>Starting page frame number of the physical memory segment.</dd> + <dt><var class="Fa">npages</var></dt> + <dd>Total number of pages from the starting page frame number to unplug.</dd> +</dl> +</div> +<p class="Pp">Returns <var class="Fa">true</var> or <var class="Fa">false</var> + depending on success or failure respectively.</p> +</section> +</section> +<section class="Sh"> +<h1 class="Sh" id="UTILITY_FUNCTIONS"><a class="permalink" href="#UTILITY_FUNCTIONS">UTILITY + FUNCTIONS</a></h1> +<dl class="Bl-ohang"> + <dt id="uvm_physseg_valid_p"><var class="Ft">bool</var></dt> + <dd><a class="permalink" href="#uvm_physseg_valid_p"><code class="Fn">uvm_physseg_valid_p</code></a>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_start</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_end</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_avail_start</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_avail_end</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">struct vm_page *</var></dt> + <dd><code class="Fn">uvm_physseg_get_pg</code>(<var class="Fa">uvm_physseg_t + upm</var>, <var class="Fa">paddr_t index</var>)</dd> + <dt id="uvm_physseg_get_pmesg"><var class="Ft">struct pmap_physseg + *</var></dt> + <dd><a class="permalink" href="#uvm_physseg_get_pmesg"><code class="Fn">uvm_physseg_get_pmesg</code></a>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">int</var></dt> + <dd><code class="Fn">uvm_physseg_get_free_list</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">u_int</var></dt> + <dd><code class="Fn">uvm_physseg_get_start_hint</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">bool</var></dt> + <dd><code class="Fn">uvm_physseg_set_start_hint</code>(<var class="Fa">uvm_physseg_t + upm</var>, <var class="Fa">u_int start_hint</var>)</dd> + <dt><var class="Ft">uvm_physseg_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_next</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">uvm_physseg_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_prev</code>(<var class="Fa">uvm_physseg_t + upm</var>)</dd> + <dt><var class="Ft">uvm_physseg_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_first</code>(<var class="Fa">void</var>)</dd> + <dt><var class="Ft">uvm_physseg_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_last</code>(<var class="Fa">void</var>)</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">uvm_physseg_get_highest_frame</code>(<var class="Fa">void</var>)</dd> + <dt><var class="Ft">paddr_t</var></dt> + <dd><code class="Fn">uvm_physseg_find</code>(<var class="Fa">paddr + pframe</var>, <var class="Fa">psize_t *offsetp</var>)</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_physseg_set_avail_start</code>(<var class="Fa">uvm_physseg_t + upm</var>, <var class="Fa">paddr_t avail_start</var>)</dd> + <dt><var class="Ft">void</var></dt> + <dd><code class="Fn">uvm_physseg_set_avail_end</code>(<var class="Fa">uvm_physseg_t + upm</var>, <var class="Fa">paddr_t avail_end</var>)</dd> +</dl> +<p class="Pp" id="uvm_physseg_valid_p~2"><a class="permalink" href="#uvm_physseg_valid_p~2"><code class="Fn">uvm_physseg_valid_p</code></a>() + validates a handle that is passed in, returns <var class="Fa">true</var> if + the given handle is valid, <var class="Fa">false</var> otherwise.</p> +<p class="Pp" id="uvm_physseg_get_start"><a class="permalink" href="#uvm_physseg_get_start"><code class="Fn">uvm_physseg_get_start</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in, it + returns the starting physical address of the segment. The returned value is + of type <var class="Ft">paddr_t</var>. In case the handle is invalid the + returned value will match (<var class="Ft">paddr_t</var>) -1.</p> +<p class="Pp" id="uvm_physseg_get_end"><a class="permalink" href="#uvm_physseg_get_end"><code class="Fn">uvm_physseg_get_end</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in, it + returns the ending physical address of the segment. The returned value is of + type <var class="Ft">paddr_t</var>. In case the handle is invalid the + returned value will match (<var class="Ft">paddr_t</var>) -1.</p> +<p class="Pp" id="uvm_physseg_get_avail_start"><a class="permalink" href="#uvm_physseg_get_avail_start"><code class="Fn">uvm_physseg_get_avail_start</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in, it + returns the available starting physical address of the segment. The returned + value is of type <var class="Ft">paddr_t</var>. In case the handle is + invalid the returned value will match (<var class="Ft">paddr_t</var>) + -1.</p> +<p class="Pp" id="uvm_physseg_get_avail_end"><a class="permalink" href="#uvm_physseg_get_avail_end"><code class="Fn">uvm_physseg_get_avail_end</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in, it + returns the available ending physical address of the segment. The returned + value is of type <var class="Ft">paddr_t</var>. In case the handle is + invalid the returned value will match (<var class="Ft">paddr_t</var>) + -1.</p> +<p class="Pp" id="uvm_physseg_get_pg"><a class="permalink" href="#uvm_physseg_get_pg"><code class="Fn">uvm_physseg_get_pg</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle along with an index + value is passed in, it returns the <var class="Fa">struct vm_page *</var> + object contained in that location.</p> +<p class="Pp" id="uvm_physseg_get_pmseg"><a class="permalink" href="#uvm_physseg_get_pmseg"><code class="Fn">uvm_physseg_get_pmseg</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in, it + returns the <var class="Fa">struct pmap_physseg *</var> object contained in + the handle.</p> +<p class="Pp" id="uvm_physseg_get_free_list"><a class="permalink" href="#uvm_physseg_get_free_list"><code class="Fn">uvm_physseg_get_free_list</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in, it + returns the <var class="Fa">free_list</var> type for which the current + segment is associated with. The returned value is of type + <var class="Fa">int</var>.</p> +<p class="Pp" id="uvm_physseg_get_start_hint"><a class="permalink" href="#uvm_physseg_get_start_hint"><code class="Fn">uvm_physseg_get_start_hint</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in, it + returns the <var class="Fa">start_hint</var> type for the current segment. + The returned value is of type <var class="Fa">u_int</var>.</p> +<p class="Pp" id="uvm_physseg_set_start_hint"><a class="permalink" href="#uvm_physseg_set_start_hint"><code class="Fn">uvm_physseg_set_start_hint</code></a>() + if a valid handle along with the <var class="Fa">start_hint</var> is passed + in, the value is set in the segment. And a <var class="Fa">true</var> is + returned to indicate a successful value setting. In case the handle is + invalid a <var class="Fa">false</var> is returned.</p> +<p class="Pp" id="uvm_physseg_get_next"><a class="permalink" href="#uvm_physseg_get_next"><code class="Fn">uvm_physseg_get_next</code></a>() + if a valid handle is passed in, it returns the next valid + <var class="Fa">uvm_physseg_t</var> handle in the sequence. However if the + handle passed is the last segment in the sequence the function returns + <var class="Fa">UVM_PHYSSEG_TYPE_INVALID_OVERFLOW</var>. Passing an invalid + handle is not fatal, and returns + <var class="Fa">UVM_PHYSSEG_TYPE_INVALID</var>.</p> +<p class="Pp" id="uvm_physseg_get_prev"><a class="permalink" href="#uvm_physseg_get_prev"><code class="Fn">uvm_physseg_get_prev</code></a>() + if a valid handle is passed in, it returns the previous validh + <var class="Fa">uvm_physseg_t</var> handle in the sequence. However if the + handle passed is the first segment in the sequence the function returns + <var class="Fa">UVM_PHYSSEG_TYPE_INVALID_EMPTY</var>. Passing an invalid + handle is not fatal, and returns + <var class="Fa">UVM_PHYSSEG_TYPE_INVALID</var>.</p> +<p class="Pp" id="uvm_physseg_get_first"><a class="permalink" href="#uvm_physseg_get_first"><code class="Fn">uvm_physseg_get_first</code></a>() + returns the first valid <var class="Fa">uvm_physseg_t</var> handle in the + sequence. However if there are no valid handles in the sequence yet, the + function returns <var class="Fa">UVM_PHYSSEG_TYPE_INVALID_EMPTY</var>.</p> +<p class="Pp" id="uvm_physseg_get_last"><a class="permalink" href="#uvm_physseg_get_last"><code class="Fn">uvm_physseg_get_last</code></a>() + returns the last valid <var class="Fa">uvm_physseg_t</var> handle in the + sequence. However if there are no valid handles in the sequence yet, the + function returns <var class="Fa">UVM_PHYSSEG_TYPE_INVALID_EMPTY</var>.</p> +<p class="Pp" id="uvm_physseg_get_highest_frame"><a class="permalink" href="#uvm_physseg_get_highest_frame"><code class="Fn">uvm_physseg_get_highest_frame</code></a>() + returns the frame number of the highest registered physical page frame which + is of type <var class="Ft">paddr_t</var>. XXX: Searching on empty sequences + are not yet processed in the function.</p> +<p class="Pp" id="uvm_physseg_find"><a class="permalink" href="#uvm_physseg_find"><code class="Fn">uvm_physseg_find</code></a>() + searches for a given segment containing the page frame + (<var class="Ft">paddr_t</var>) passed in. If a segment that falls between + starting and ending addresses is found, the corresponding + <var class="Fa">uvm_physseg_t</var> handle is returned else a + <var class="Fa">UVM_PHYSSEG_TYPE_INVALID</var> is returned. The second + parameter, if not set to <code class="Dv">NULL</code>, the offset value of + the page frame passed in with respect to the starting address is set to the + appropriate <var class="Fa">psize_t</var> value if the search was successful + in finding the segment.</p> +<p class="Pp" id="uvm_physseg_set_avail_start"><a class="permalink" href="#uvm_physseg_set_avail_start"><code class="Fn">uvm_physseg_set_avail_start</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in along + with the available starting physical address of the segment of type + <var class="Ft">paddr_t</var>, the value is set in the segment.</p> +<p class="Pp" id="uvm_physseg_set_avail_end"><a class="permalink" href="#uvm_physseg_set_avail_end"><code class="Fn">uvm_physseg_set_avail_end</code></a>() + if a valid <var class="Fa">uvm_physseg_t</var> handle is passed in along + with the available ending physical address of the segment of type + <var class="Ft">paddr_t</var>, the value is set in the segment.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="NOTES"><a class="permalink" href="#NOTES">NOTES</a></h1> +<p class="Pp"><code class="Fn">uvm_physseg_plug</code>() and + <code class="Fn">uvm_physseg_unplug</code>() must never be used after + <a class="Xr">uvm_init(9)</a> in a kernel build where + <code class="Cd">'options UVM_HOTPLUG'</code> is not enabled.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DIAGNOSTICS"><a class="permalink" href="#DIAGNOSTICS">DIAGNOSTICS</a></h1> +<p class="Pp">Tests for <code class="Nm">uvm_physseg_init</code> are in + <span class="Pa">tests/sys/uvm</span>.</p> +<p class="Pp">Unit / functional tests are in + <span class="Pa">tests/sys/uvm/t_uvm_physseg.c</span>. These tests focus on + the expected working of the <code class="Nm">uvm_physseg_init</code> API and + its utility functions.</p> +<p class="Pp">Load tests can be found in + <span class="Pa">tests/sys/uvm/t_uvm_physseg_load.c</span>. These tests + focus on stressing the <code class="Nm">uvm_physseg_init</code> + implementation in order to make performance comparisons between kernel + builds with and without <code class="Cd">'options UVM_HOTPLUG'</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The uvm hotplug feature is implemented in the file + <span class="Pa">sys/uvm/uvm_physseg.c</span>. The uvm hotplug API is + exported via <span class="Pa">sys/uvm/uvm_physseg.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">extent(9)</a>, <a class="Xr">free(9)</a>, + <a class="Xr">malloc(9)</a>, <a class="Xr">memoryallocators(9)</a>, + <a class="Xr">uvm(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">This API emerged out of the need to insert new pages at runtime in + the Xen <a class="Xr">x86/balloon(4)</a> driver.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Cherry G. Mathew</span> + <<a class="Mt" href="mailto:cherry@NetBSD.org">cherry@NetBSD.org</a>> + designed and integrated the API.</p> +<p class="Pp"><span class="An">Santhosh N. Raju</span> + <<a class="Mt" href="mailto:santhosh.raju@gmail.com">santhosh.raju@gmail.com</a>> + implemented the dynamic segment handling code and all tests for this + API.</p> +<p class="Pp"><span class="An">Nick Hudson</span> + <<a class="Mt" href="mailto:skrll@NetBSD.org">skrll@NetBSD.org</a>> + contributed bugfixes and testing on a wide range of hardware ports.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 17, 2020</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/uvm_map.9 3.html b/static/netbsd/man9/uvm_map.9 3.html new file mode 100644 index 00000000..d50fc351 --- /dev/null +++ b/static/netbsd/man9/uvm_map.9 3.html @@ -0,0 +1,318 @@ +<table class="head"> + <tr> + <td class="head-ltitle">UVM_MAP(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">UVM_MAP(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">uvm_map</code> — <span class="Nd">virtual + address space management interface</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">uvm/uvm.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">uvm_map</code>(<var class="Fa" style="white-space: nowrap;">struct + vm_map *map</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + *startp</var>, <var class="Fa" style="white-space: nowrap;">vsize_t + size</var>, <var class="Fa" style="white-space: nowrap;">struct uvm_object + *uobj</var>, <var class="Fa" style="white-space: nowrap;">voff_t + uoffset</var>, <var class="Fa" style="white-space: nowrap;">vsize_t + align</var>, <var class="Fa" style="white-space: nowrap;">uvm_flag_t + flags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">uvm_unmap</code>(<var class="Fa" style="white-space: nowrap;">struct + vm_map *map</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + end</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">uvm_map_pageable</code>(<var class="Fa" style="white-space: nowrap;">struct + vm_map *map</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t end</var>, + <var class="Fa" style="white-space: nowrap;">bool new_pageable</var>, + <var class="Fa" style="white-space: nowrap;">int lockflags</var>);</p> +<p class="Pp"><var class="Ft">bool</var> + <br/> + <code class="Fn">uvm_map_checkprot</code>(<var class="Fa" style="white-space: nowrap;">struct + vm_map *map</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t end</var>, + <var class="Fa" style="white-space: nowrap;">vm_prot_t + protection</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">uvm_map_protect</code>(<var class="Fa" style="white-space: nowrap;">struct + vm_map *map</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t end</var>, + <var class="Fa" style="white-space: nowrap;">vm_prot_t new_prot</var>, + <var class="Fa" style="white-space: nowrap;">bool set_max</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">uvm_map_protect_user</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t end</var>, + <var class="Fa" style="white-space: nowrap;">vm_prot_t new_prot</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">uvm_deallocate</code>(<var class="Fa" style="white-space: nowrap;">struct + vm_map *map</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">vsize_t + size</var>);</p> +<p class="Pp"><var class="Ft">struct vmspace *</var> + <br/> + <code class="Fn">uvmspace_alloc</code>(<var class="Fa" style="white-space: nowrap;">vaddr_t + min</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + max</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">uvmspace_exec</code>(<var class="Fa" style="white-space: nowrap;">struct + lwp *l</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + start</var>, <var class="Fa" style="white-space: nowrap;">vaddr_t + end</var>);</p> +<p class="Pp"><var class="Ft">struct vmspace *</var> + <br/> + <code class="Fn">uvmspace_fork</code>(<var class="Fa" style="white-space: nowrap;">struct + vmspace *vm</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">uvmspace_free</code>(<var class="Fa" style="white-space: nowrap;">struct + vmspace *vm</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">uvmspace_share</code>(<var class="Fa" style="white-space: nowrap;">struct + proc *p1</var>, <var class="Fa" style="white-space: nowrap;">struct proc + *p2</var>);</p> +<p class="Pp"><var class="Ft">vaddr_t</var> + <br/> + <code class="Fn">uvm_uarea_alloc</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">uvm_uarea_free</code>(<var class="Fa" style="white-space: nowrap;">vaddr_t + uaddr</var>);</p> +<p class="Pp"><var class="Ft">vaddr_t</var> + <br/> + <code class="Fn">uvm_uarea_system_alloc</code>(<var class="Fa" style="white-space: nowrap;">void</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">uvm_uarea_system_free</code>(<var class="Fa" style="white-space: nowrap;">vaddr_t + uaddr</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The UVM facility for virtual address space management.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<p class="Pp"><a class="permalink" href="#uvm_map"><code class="Fn" id="uvm_map">uvm_map</code></a>() + establishes a valid mapping in map <var class="Fa">map</var>, which must be + unlocked. The new mapping has size <var class="Fa">size</var>, which must be + a multiple of <code class="Dv">PAGE_SIZE</code>.</p> +<p class="Pp">The <var class="Fa">uobj</var> and <var class="Fa">uoffset</var> + arguments can have four meanings:</p> +<ul class="Bl-bullet Bd-indent Bl-compact"> + <li id="uvm_map~2">When <var class="Fa">uobj</var> is + <code class="Dv">NULL</code> and <var class="Fa">uoffset</var> is + <code class="Dv">UVM_UNKNOWN_OFFSET</code>, + <a class="permalink" href="#uvm_map~2"><code class="Fn">uvm_map</code></a>() + does not use the machine-dependent <code class="Dv">PMAP_PREFER</code> + function.</li> + <li>When <var class="Fa">uobj</var> is <code class="Dv">NULL</code> and + <var class="Fa">uoffset</var> is any other value, it is used as the hint + to <code class="Dv">PMAP_PREFER</code>.</li> + <li>When <var class="Fa">uobj</var> is not <code class="Dv">NULL</code> and + <var class="Fa">uoffset</var> is + <code class="Dv">UVM_UNKNOWN_OFFSET</code>, + <code class="Fn">uvm_map</code>() finds the offset based upon the virtual + address, passed as <var class="Fa">startp</var>.</li> + <li>When <var class="Fa">uobj</var> is not <code class="Dv">NULL</code> and + <var class="Fa">uoffset</var> is any other value, then a regular mapping + is performed at this offset. The start address of the map will be returned + in <var class="Fa">startp</var>.</li> +</ul> +If <var class="Fa">uobj</var> is supplied, then + <code class="Fn">uvm_map</code>() + <a class="permalink" href="#consumes"><i class="Em" id="consumes">consumes</i></a> + the caller's reference to <var class="Fa">uobj</var> on success; + <code class="Fn">uvm_unmap</code>() will release it when removing this + mapping. On failure, <code class="Fn">uvm_map</code>() leaves the reference + count of <var class="Fa">uobj</var> unmodified. +<p class="Pp"><var class="Fa">align</var> specifies alignment of mapping unless + <code class="Dv">UVM_FLAG_FIXED</code> is specified in + <var class="Fa">flags</var>. <var class="Fa">align</var> must be a power of + 2.</p> +<p class="Pp" id="uvm_map~3"><var class="Fa">flags</var> passed to + <a class="permalink" href="#uvm_map~3"><code class="Fn">uvm_map</code></a>() + are typically created using the + <a class="permalink" href="#UVM_MAPFLAG"><code class="Fn" id="UVM_MAPFLAG">UVM_MAPFLAG</code></a>(<var class="Fa">vm_prot_t + prot</var>, <var class="Fa">vm_prot_t maxprot</var>, + <var class="Fa">vm_inherit_t inh</var>, <var class="Fa">int advice</var>, + <var class="Fa">int flags</var>) macro, which uses the following values.</p> +<p class="Pp">The values that <var class="Fa">prot</var> and + <var class="Fa">maxprot</var> can take are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>UVM_PROT_NONE</dt> + <dd>No protection bits.</dd> + <dt>UVM_PROT_R</dt> + <dd>Read.</dd> + <dt>UVM_PROT_W</dt> + <dd>Write.</dd> + <dt>UVM_PROT_X</dt> + <dd>Exec.</dd> + <dt>UVM_PROT_MASK</dt> + <dd>Mask to extraction the protection bits.</dd> +</dl> +</div> +Additionally, the following constants for ORed values are available: + <code class="Dv">UVM_PROT_RW</code>, <code class="Dv">UVM_PROT_RX</code>, + <code class="Dv">UVM_PROT_WX</code> and <code class="Dv">UVM_PROT_RWX</code>. +<p class="Pp">The values that <var class="Fa">inh</var> can take are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>UVM_INH_SHARE</dt> + <dd>Share the map.</dd> + <dt>UVM_INH_COPY</dt> + <dd>Copy the map.</dd> + <dt>UVM_INH_NONE</dt> + <dd>No inheritance.</dd> + <dt>UVM_INH_MASK</dt> + <dd>Mask to extract inherit flags.</dd> +</dl> +</div> +<p class="Pp">The values that <var class="Fa">advice</var> can take are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>UVM_ADV_NORMAL</dt> + <dd>"Normal" use.</dd> + <dt>UVM_ADV_RANDOM</dt> + <dd>"Random" access likelihood.</dd> + <dt>UVM_ADV_SEQUENTIAL</dt> + <dd>"Sequential" access likelihood.</dd> + <dt>UVM_ADV_MASK</dt> + <dd>Mask to extract the advice flags.</dd> +</dl> +</div> +<p class="Pp">The values that <var class="Fa">flags</var> can take are:</p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>UVM_FLAG_FIXED</dt> + <dd>Attempt to map on the address specified by <var class="Fa">startp</var>. + Otherwise, it is used just as a hint.</dd> + <dt>UVM_FLAG_OVERLAY</dt> + <dd>Establish overlay.</dd> + <dt>UVM_FLAG_NOMERGE</dt> + <dd>Do not merge map entries, if such merge is possible.</dd> + <dt>UVM_FLAG_COPYONW</dt> + <dd>Use copy-on-write i.e. do not fault in the pages immediately.</dd> + <dt>UVM_FLAG_AMAPPAD</dt> + <dd>Used for BSS: allocate larger amap, if extending is likely.</dd> + <dt>UVM_FLAG_TRYLOCK</dt> + <dd>Fail if cannot acquire the lock immediately.</dd> + <dt>UVM_FLAG_NOWAIT</dt> + <dd>Not allowed to sleep. Fail, in such case.</dd> + <dt>UVM_FLAG_QUANTUM</dt> + <dd>Indicates that map entry cannot be split once mapped.</dd> + <dt>UVM_FLAG_WAITVA</dt> + <dd>Sleep until VA space is available, if it is not.</dd> + <dt id="uvm_unmap">UVM_FLAG_VAONLY</dt> + <dd>Unmap only VA space. Used by + <a class="permalink" href="#uvm_unmap"><code class="Fn">uvm_unmap</code></a>().</dd> + <dt>UVM_FLAG_UNMAP</dt> + <dd>Any existing entries in the range for this mapping should be unmapped as + part of creating the new mapping. Use of this flag without also specifying + <code class="Dv">UVM_FLAG_FIXED</code> is a bug.</dd> +</dl> +</div> +<p class="Pp" id="uvm_map~4">The <code class="Dv">UVM_MAPFLAG</code> macro + arguments can be combined with an or operator. There are several special + purpose macros for checking protection combinations, e.g., the + <code class="Dv">UVM_PROT_WX</code>. There are also some additional macros + to extract bits from the flags. The <code class="Dv">UVM_PROTECTION</code>, + <code class="Dv">UVM_INHERIT</code>, + <code class="Dv">UVM_MAXPROTECTION</code> and + <code class="Dv">UVM_ADVICE</code> macros return the protection, + inheritance, maximum protection, and advice, respectively. + <a class="permalink" href="#uvm_map~4"><code class="Fn">uvm_map</code></a>() + returns zero on success or error number otherwise.</p> +<p class="Pp" id="uvm_unmap~2"><a class="permalink" href="#uvm_unmap~2"><code class="Fn">uvm_unmap</code></a>() + removes a valid mapping, from <var class="Fa">start</var> to + <var class="Fa">end</var>, in map <var class="Fa">map</var>, which must be + unlocked.</p> +<p class="Pp" id="uvm_map_pageable"><a class="permalink" href="#uvm_map_pageable"><code class="Fn">uvm_map_pageable</code></a>() + changes the pageability of the pages in the range from + <var class="Fa">start</var> to <var class="Fa">end</var> in map + <var class="Fa">map</var> to <var class="Fa">new_pageable</var>. + <code class="Fn">uvm_map_pageable</code>() returns zero on success or error + number otherwise.</p> +<p class="Pp" id="uvm_map_checkprot"><a class="permalink" href="#uvm_map_checkprot"><code class="Fn">uvm_map_checkprot</code></a>() + checks the protection of the range from <var class="Fa">start</var> to + <var class="Fa">end</var> in map <var class="Fa">map</var> against + <var class="Fa">protection</var>. This returns either + <code class="Dv">true</code> or <code class="Dv">false</code>.</p> +<p class="Pp" id="uvm_map_protect"><a class="permalink" href="#uvm_map_protect"><code class="Fn">uvm_map_protect</code></a>() + changes the protection <var class="Fa">start</var> to + <var class="Fa">end</var> in map <var class="Fa">map</var> to + <var class="Fa">new_prot</var>, also setting the maximum protection to the + region to <var class="Fa">new_prot</var> if <var class="Fa">set_max</var> is + true. This function returns a standard UVM return value.</p> +<p class="Pp" id="uvm_map_protect_user"><a class="permalink" href="#uvm_map_protect_user"><code class="Fn">uvm_map_protect_user</code></a>() + verifies that the new permissions honor PAX restrictions if applicable and + forwards to <code class="Fn">uvm_map_protect</code>() on passing.</p> +<p class="Pp" id="uvm_deallocate"><a class="permalink" href="#uvm_deallocate"><code class="Fn">uvm_deallocate</code></a>() + deallocates kernel memory in map <var class="Fa">map</var> from address + <var class="Fa">start</var> to <var class="Fa">start + size</var>.</p> +<p class="Pp" id="uvmspace_alloc"><a class="permalink" href="#uvmspace_alloc"><code class="Fn">uvmspace_alloc</code></a>() + allocates and returns a new address space, with ranges from + <var class="Fa">min</var> to <var class="Fa">max</var>.</p> +<p class="Pp" id="uvmspace_exec"><a class="permalink" href="#uvmspace_exec"><code class="Fn">uvmspace_exec</code></a>() + either reuses the address space of thread <var class="Fa">l</var> (its + process) if there are no other references to it, or creates a new one with + <code class="Fn">uvmspace_alloc</code>(). The range of valid addresses in + the address space is reset to <var class="Fa">start</var> through + <var class="Fa">end</var>.</p> +<p class="Pp" id="uvmspace_fork"><a class="permalink" href="#uvmspace_fork"><code class="Fn">uvmspace_fork</code></a>() + creates and returns a new address space based upon the + <var class="Fa">vm</var> address space, typically used when allocating an + address space for a child process.</p> +<p class="Pp" id="uvmspace_free"><a class="permalink" href="#uvmspace_free"><code class="Fn">uvmspace_free</code></a>() + lowers the reference count on the address space <var class="Fa">vm</var>, + freeing the data structures if there are no other references.</p> +<p class="Pp" id="uvmspace_share"><a class="permalink" href="#uvmspace_share"><code class="Fn">uvmspace_share</code></a>() + causes process <span class="Pa">p2</span> to share the address space of + <var class="Fa">p1</var>.</p> +<p class="Pp" id="uvm_uarea_alloc"><a class="permalink" href="#uvm_uarea_alloc"><code class="Fn">uvm_uarea_alloc</code></a>() + allocates memory for a u-area (i.e. kernel stack, PCB, etc) and returns the + address.</p> +<p class="Pp" id="uvm_uarea_free"><a class="permalink" href="#uvm_uarea_free"><code class="Fn">uvm_uarea_free</code></a>() + frees a u-area allocated with <code class="Fn">uvm_uarea_alloc</code>().</p> +<p class="Pp" id="uvm_uarea_system_alloc"><a class="permalink" href="#uvm_uarea_system_alloc"><code class="Fn">uvm_uarea_system_alloc</code></a>() + and + <a class="permalink" href="#uvm_uarea_system_free"><code class="Fn" id="uvm_uarea_system_free">uvm_uarea_system_free</code></a>() + are optimized routines, which are used for kernel threads.</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">pmap(9)</a>, <a class="Xr">uvm(9)</a>, + <a class="Xr">uvm_km(9)</a>, <a class="Xr">vmem(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">UVM and <code class="Nm">uvm_map</code> first appeared in + <span class="Ux">NetBSD 1.4</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">May 20, 2017</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/vattr.9 3.html b/static/netbsd/man9/vattr.9 3.html new file mode 100644 index 00000000..3b467fc3 --- /dev/null +++ b/static/netbsd/man9/vattr.9 3.html @@ -0,0 +1,98 @@ +<table class="head"> + <tr> + <td class="head-ltitle">VATTR(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">VATTR(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">vattr</code>, <code class="Nm">vattr_null</code> + — <span class="Nd">vnode attributes</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/vnode.h</a>></code></p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">vattr_null</code>(<var class="Fa" style="white-space: nowrap;">struct + vattr *vap</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">Vnode attributes describe attributes of a file or directory + including file permissions, owner, group, size, access time and modification + time.</p> +<p class="Pp">A vnode attribute has the following structure:</p> +<div class="Bd Pp Li"> +<pre>struct vattr { + enum vtype va_type; /* vnode type (for create) */ + mode_t va_mode; /* files access mode and type */ + nlink_t va_nlink; /* number of references to file */ + uid_t va_uid; /* owner user id */ + gid_t va_gid; /* owner group id */ + dev_t va_fsid; /* file system id (dev for now) */ + ino_t va_fileid; /* file id */ + u_quad_t va_size; /* file size in bytes */ + long va_blocksize; /* blocksize preferred for i/o */ + struct timespec va_atime; /* time of last access */ + struct timespec va_mtime; /* time of last modification */ + struct timespec va_ctime; /* time file changed */ + struct timespec va_birthtime; /* time file created */ + u_long va_gen; /* generation number of file */ + u_long va_flags; /* flags defined for file */ + dev_t va_rdev; /* device the special file represents */ + u_quad_t va_bytes; /* bytes of disk space held by file */ + u_quad_t va_filerev; /* file modification number */ + u_int va_vaflags; /* operations flags, see below */ + long va_spare; /* remain quad aligned */ +};</pre> +</div> +<p class="Pp" id="va_flags">A field value of VNOVAL represents a field whose + value is unavailable or which is not to be changed. Valid flag values for + <a class="permalink" href="#va_flags"><i class="Em">va_flags</i></a> + are:</p> +<p class="Pp"></p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>VA_UTIMES_NULL</dt> + <dd>utimes argument was NULL</dd> + <dt>VA_EXCLUSIVE</dt> + <dd>exclusive create request</dd> +</dl> +</div> +<p class="Pp">Vnode attributes for a file are set by the vnode operation + <a class="Xr">VOP_SETATTR(9)</a>. Vnode attributes for a file are retrieved + by the vnode operation <a class="Xr">VOP_GETATTR(9)</a>. For more + information on vnode operations see <a class="Xr">vnodeops(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="vattr_null"><a class="permalink" href="#vattr_null"><code class="Fn">vattr_null</code></a>(<var class="Fa">vap</var>)</dt> + <dd>Set vnode attributes in <var class="Fa">vap</var> to VNOVAL.</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"><code class="Fn">vattr_null</code>() is implemented in + <span class="Pa">sys/kern/vfs_subr.c</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">intro(9)</a>, <a class="Xr">vfs(9)</a>, + <a class="Xr">vnode(9)</a>, <a class="Xr">vnodeops(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 8, 2010</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/vfs.9 3.html b/static/netbsd/man9/vfs.9 3.html new file mode 100644 index 00000000..f5ce15c7 --- /dev/null +++ b/static/netbsd/man9/vfs.9 3.html @@ -0,0 +1,37 @@ +<table class="head"> + <tr> + <td class="head-ltitle">VFS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">VFS(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">vfs</code> — <span class="Nd">kernel + interface to file systems</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The virtual file system, <code class="Nm">vfs</code>, is the + kernel interface to file systems. The interface specifies the calls for the + kernel to access file systems. It also specifies the core functionality that + a file system must provide to the kernel.</p> +<p class="Pp" id="vnode">The focus of <code class="Nm">vfs</code> activity is + the <a class="permalink" href="#vnode"><i class="Em">vnode</i></a> and is + discussed in <a class="Xr">vnode(9)</a>. File system operations such as + mounting and syncing are discussed in <a class="Xr">vfsops(9)</a>.</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">intro(9)</a>, <a class="Xr">vfsops(9)</a>, + <a class="Xr">vnode(9)</a>, <a class="Xr">vnodeops(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">September 22, 2001</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/vfsops.9 3.html b/static/netbsd/man9/vfsops.9 3.html new file mode 100644 index 00000000..0466fe6d --- /dev/null +++ b/static/netbsd/man9/vfsops.9 3.html @@ -0,0 +1,461 @@ +<table class="head"> + <tr> + <td class="head-ltitle">VFSOPS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">VFSOPS(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">vfsops</code>, <code class="Nm">VFS_MOUNT</code>, + <code class="Nm">VFS_START</code>, <code class="Nm">VFS_UNMOUNT</code>, + <code class="Nm">VFS_ROOT</code>, <code class="Nm">VFS_QUOTACTL</code>, + <code class="Nm">VFS_STATVFS</code>, <code class="Nm">VFS_SYNC</code>, + <code class="Nm">VFS_VGET</code>, <code class="Nm">VFS_LOADVNODE</code>, + <code class="Nm">VFS_NEWVNODE</code>, <code class="Nm">VFS_FHTOVP</code>, + <code class="Nm">VFS_VPTOFH</code>, <code class="Nm">VFS_SNAPSHOT</code>, + <code class="Nm">VFS_SUSPENDCTL</code> — <span class="Nd">kernel file + system interface</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/mount.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/vnode.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_MOUNT</code>(<var class="Fa">struct mount *mp</var>, + <var class="Fa">const char *path</var>, <var class="Fa">void *data</var>, + <var class="Fa">size_t *dlen</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_START</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_UNMOUNT</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">int + mntflags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_ROOT</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">int + lktype</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_QUOTACTL</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">struct + quotactl_args *args</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_STATVFS</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">struct statvfs + *sbp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_SYNC</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">int + waitfor</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_VGET</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">ino_t + ino</var>, <var class="Fa" style="white-space: nowrap;">int lktype</var>, + <var class="Fa" style="white-space: nowrap;">struct vnode **vpp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_LOADVNODE</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *vp</var>, <var class="Fa" style="white-space: nowrap;">const void + *key</var>, <var class="Fa" style="white-space: nowrap;">size_t + key_len</var>, <var class="Fa" style="white-space: nowrap;">const void + **new_key</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_NEWVNODE</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *vp</var>, <var class="Fa" style="white-space: nowrap;">struct vattr + *vap</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">void *extra</var>, + <var class="Fa" style="white-space: nowrap;">size_t *key_len</var>, + <var class="Fa" style="white-space: nowrap;">const void + **new_key</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_FHTOVP</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">struct fid + *fhp</var>, <var class="Fa" style="white-space: nowrap;">int lktype</var>, + <var class="Fa" style="white-space: nowrap;">struct vnode **vpp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_VPTOFH</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct fid + *fhp</var>, <var class="Fa" style="white-space: nowrap;">size_t + *fh_size</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_SNAPSHOT</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *vp</var>, <var class="Fa" style="white-space: nowrap;">struct timespec + *ts</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VFS_SUSPENDCTL</code>(<var class="Fa" style="white-space: nowrap;">struct + mount *mp</var>, <var class="Fa" style="white-space: nowrap;">int + cmd</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">In a similar fashion to the <a class="Xr">vnode(9)</a> interface, + all operations that are done on a file system are conducted through a single + interface that allows the system to carry out operations on a file system + without knowing its construction or type.</p> +<p class="Pp">All supported file systems in the kernel have an entry in the + <var class="Va">vfs_list_initial</var> table. This table is generated by + <a class="Xr">config(1)</a> and is a + <code class="Dv">NULL</code><span class="No">-terminated</span> list of + <var class="Vt">vfsops</var> structures. The vfsops structure describes the + operations that can be done to a specific file system type. The following + table lists the elements of the vfsops vector, the corresponding invocation + macro, and a description of the element.</p> +<p class="Pp"></p> +<table class="Bl-column Bl-compact"> + <tr id="Vector"> + <td><a class="permalink" href="#Vector"><b class="Sy">Vector + element</b></a></td> + <td><a class="permalink" href="#Macro"><b class="Sy" id="Macro">Macro</b></a></td> + <td><a class="permalink" href="#Description"><b class="Sy" id="Description">Description</b></a></td> + </tr> + <tr id="VFS_MOUNT"> + <td>int (*vfs_mount)()</td> + <td><a class="permalink" href="#VFS_MOUNT"><code class="Dv">VFS_MOUNT</code></a></td> + <td>Mount a file system</td> + </tr> + <tr id="VFS_START"> + <td>int (*vfs_start)()</td> + <td><a class="permalink" href="#VFS_START"><code class="Dv">VFS_START</code></a></td> + <td>Make operational</td> + </tr> + <tr id="VFS_UNMOUNT"> + <td>int (*vfs_unmount)()</td> + <td><a class="permalink" href="#VFS_UNMOUNT"><code class="Dv">VFS_UNMOUNT</code></a></td> + <td>Unmount a file system</td> + </tr> + <tr id="VFS_ROOT"> + <td>int (*vfs_root)()</td> + <td><a class="permalink" href="#VFS_ROOT"><code class="Dv">VFS_ROOT</code></a></td> + <td>Get the file system root vnode</td> + </tr> + <tr id="VFS_QUOTACTL"> + <td>int (*vfs_quotactl)()</td> + <td><a class="permalink" href="#VFS_QUOTACTL"><code class="Dv">VFS_QUOTACTL</code></a></td> + <td>Query/modify space quotas</td> + </tr> + <tr id="VFS_STATVFS"> + <td>int (*vfs_statvfs)()</td> + <td><a class="permalink" href="#VFS_STATVFS"><code class="Dv">VFS_STATVFS</code></a></td> + <td>Get file system statistics</td> + </tr> + <tr id="VFS_SYNC"> + <td>int (*vfs_sync)()</td> + <td><a class="permalink" href="#VFS_SYNC"><code class="Dv">VFS_SYNC</code></a></td> + <td>Flush file system buffers</td> + </tr> + <tr id="VFS_VGET"> + <td>int (*vfs_vget)()</td> + <td><a class="permalink" href="#VFS_VGET"><code class="Dv">VFS_VGET</code></a></td> + <td>Get vnode from file id</td> + </tr> + <tr id="VFS_LOADVNODE"> + <td>int (*vfs_loadvnode)()</td> + <td><a class="permalink" href="#VFS_LOADVNODE"><code class="Dv">VFS_LOADVNODE</code></a></td> + <td>Initialize vnode with file</td> + </tr> + <tr id="VFS_NEWVNODE"> + <td>int (*vfs_newvnode)()</td> + <td><a class="permalink" href="#VFS_NEWVNODE"><code class="Dv">VFS_NEWVNODE</code></a></td> + <td>Initialize vnode with new file</td> + </tr> + <tr id="VFS_FHTOVP"> + <td>int (*vfs_fhtovp)()</td> + <td><a class="permalink" href="#VFS_FHTOVP"><code class="Dv">VFS_FHTOVP</code></a></td> + <td>NFS file handle to vnode lookup</td> + </tr> + <tr id="VFS_VPTOFH"> + <td>int (*vfs_vptofh)()</td> + <td><a class="permalink" href="#VFS_VPTOFH"><code class="Dv">VFS_VPTOFH</code></a></td> + <td>Vnode to NFS file handle lookup</td> + </tr> + <tr> + <td>void (*vfs_init)()</td> + <td>-</td> + <td>Initialize file system</td> + </tr> + <tr> + <td>void (*vfs_reinit)()</td> + <td>-</td> + <td>Reinitialize file system</td> + </tr> + <tr> + <td>void (*vfs_done)()</td> + <td>-</td> + <td>Cleanup unmounted file system</td> + </tr> + <tr> + <td>int (*vfs_mountroot)()</td> + <td>-</td> + <td>Mount the root file system</td> + </tr> + <tr id="VFS_SNAPSHOT"> + <td>int (*vfs_snapshot)()</td> + <td><a class="permalink" href="#VFS_SNAPSHOT"><code class="Dv">VFS_SNAPSHOT</code></a></td> + <td>Take a snapshot</td> + </tr> + <tr id="VFS_SUSPENDCTL"> + <td>int (*vfs_suspendctl)()</td> + <td><a class="permalink" href="#VFS_SUSPENDCTL"><code class="Dv">VFS_SUSPENDCTL</code></a></td> + <td>Suspend or resume</td> + </tr> +</table> +<p class="Pp">Some additional non-function members of the vfsops structure are + the file system name <var class="Fa">vfs_name</var> and a reference count + <var class="Fa">vfs_refcount</var>. It is not mandatory for a file system + type to support a particular operation, but it must assign each member + function pointer to a suitable function to do the minimum required of it. In + most cases, such functions either do nothing or return an error value to the + effect that it is not supported. <var class="Fa">vfs_reinit</var>, + <var class="Fa">vfs_mountroot</var>, <var class="Fa">vfs_fhtovp</var>, and + <var class="Fa">vfs_vptofh</var> may be <code class="Dv">NULL</code>.</p> +<p class="Pp">At system boot, each file system with an entry in + <var class="Va">vfs_list_initial</var> is established and initialized. Each + initialized file system is recorded by the kernel in the list + <var class="Va">vfs_list</var> and the file system specific initialization + function <var class="Fa">vfs_init</var> in its vfsops vector is invoked. + When the file system is no longer needed <var class="Fa">vfs_done</var> is + invoked to run file system specific cleanups and the file system is removed + from the kernel list.</p> +<p class="Pp">At system boot, the root file system is mounted by invoking the + file system type specific <var class="Fa">vfs_mountroot</var> function in + the vfsops vector. All file systems that can be mounted as a root file + system must define this function. It is responsible for initializing to list + of mount structures for all future mounted file systems.</p> +<p class="Pp">Kernel state which affects a specific file system type can be + queried and modified using the <a class="Xr">sysctl(8)</a> interface.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="VFS_MOUNT~2"><a class="permalink" href="#VFS_MOUNT~2"><code class="Fn">VFS_MOUNT</code></a>(<var class="Fa">mp</var>, + <var class="Fa">path</var>, <var class="Fa">data</var>, + <var class="Fa">dlen</var>)</dt> + <dd>Mount a file system specified by the mount structure + <var class="Fa">mp</var> on the mount point described by + <var class="Fa">path</var>. The argument <var class="Fa">data</var> + contains file system type specific data, while the argument + <var class="Fa">dlen</var> points to a location specifying the length of + the data. + <p class="Pp" id="VFS_MOUNT~3"><a class="permalink" href="#VFS_MOUNT~3"><code class="Fn">VFS_MOUNT</code></a>() + initializes the mount structure for the mounted file system. This + structure records mount-specific information for the file system and + records the list of vnodes associated with the file system. This + function is invoked both to mount new file systems and to change the + attributes of an existing file system. If the flag + <code class="Dv">MNT_UPDATE</code> is set in + <var class="Va">mp->mnt_flag</var>, the file system should update its + state. This can be used, for instance, to convert a read-only file + system to read-write. The current attributes for a mounted file system + can be fetched by specifying <code class="Dv">MNT_GETARGS</code>. If + neither <code class="Dv">MNT_UPDATE</code> or + <code class="Dv">MNT_GETARGS</code> are specified, a new file system + will attempted to be mounted.</p> + </dd> + <dt><code class="Fn">VFS_START</code>(<var class="Fa">mp</var>, + <var class="Fa">flags</var>)</dt> + <dd>Make the file system specified by the mount structure + <var class="Fa">mp</var> operational. The argument + <var class="Fa">flags</var> is a set of flags for controlling the + operation of <code class="Fn">VFS_START</code>(). This function is invoked + after <code class="Fn">VFS_MOUNT</code>() and before the first access to + the file system.</dd> + <dt><code class="Fn">VFS_UNMOUNT</code>(<var class="Fa">mp</var>, + <var class="Fa">mntflags</var>)</dt> + <dd>Unmount a file system specified by the mount structure + <var class="Fa">mp</var>. <code class="Fn">VFS_UNMOUNT</code>() performs + any file system type specific operations required before the file system + is unmounted, such are flushing buffers. If + <code class="Dv">MNT_FORCE</code> is specified in the flags + <var class="Fa">mntflags</var> then open files are forcibly closed. The + function also deallocates space associated with data structure that were + allocated for the file system when it was mounted.</dd> + <dt><code class="Fn">VFS_ROOT</code>(<var class="Fa">mp</var>, + <var class="Fa">lktype</var>, <var class="Fa">vpp</var>)</dt> + <dd>Get the root vnode of the file system specified by the mount structure + <var class="Fa">mp</var>. The vnode is returned in the address given by + <var class="Fa">vpp</var>, with lock type <var class="Fa">lktype</var>. + <var class="Fa">lktype</var> can be <code class="Dv">LK_NONE</code>, or + <code class="Dv">LK_SHARED</code>, or + <code class="Dv">LK_EXCLUSIVE</code>. This function is used by the + pathname translation algorithms when a vnode that has been covered by a + mounted file system is encountered. While resolving the pathname, the + pathname translation algorithm will have to go through the directory tree + in the file system associated with that mount point and therefore requires + the root vnode of the file system.</dd> + <dt><code class="Fn">VFS_QUOTACTL</code>(<var class="Fa">mp</var>, + <var class="Fa">args</var>)</dt> + <dd>Query/modify user space quotas for the file system specified by the mount + structure <var class="Fa">mp</var>. The argument structure provides the + operation ID and arguments to perform. This is the same interface as + documented in <a class="Xr">__quotactl(2)</a> except that the file system + argument has been resolved. All <a class="Xr">copyin(9)</a> and + <a class="Xr">copyout(9)</a> processing is handled by code above the file + system.</dd> + <dt><code class="Fn">VFS_STATVFS</code>(<var class="Fa">mp</var>, + <var class="Fa">sbp</var>)</dt> + <dd>Get file system statistics for the file system specified by the mount + structure <var class="Fa">mp</var>. A statvfs structure filled with the + statistics is returned in <var class="Fa">sbp</var>. + <code class="Fn">VFS_STATVFS</code>() is the file system type specific + implementation of the <a class="Xr">statvfs(2)</a> and + <a class="Xr">fstatvfs(2)</a> system calls.</dd> + <dt><code class="Fn">VFS_SYNC</code>(<var class="Fa">mp</var>, + <var class="Fa">waitfor</var>, <var class="Fa">cred</var>)</dt> + <dd>Flush file system I/O buffers for the file system specified by the mount + structure <var class="Fa">mp</var>. The <var class="Fa">waitfor</var> + argument indicates whether a partial flush or complete flush should be + performed. The argument <var class="Fa">cred</var> specifies the calling + credentials. <code class="Fn">VFS_SYNC</code>() does not provide any + return value since the operation can never fail.</dd> + <dt><code class="Fn">VFS_VGET</code>(<var class="Fa">mp</var>, + <var class="Fa">ino</var>, <var class="Fa">lktype</var>, + <var class="Fa">vpp</var>)</dt> + <dd>Get vnode for a file system type specific file id + <var class="Fa">ino</var> for the file system specified by the mount + structure <var class="Fa">mp</var>, with lock type + <var class="Fa">lktype</var>. <var class="Fa">lktype</var> can be + <code class="Dv">LK_NONE</code>, or <code class="Dv">LK_SHARED</code>, or + <code class="Dv">LK_EXCLUSIVE</code>. The vnode is returned in the address + specified <var class="Fa">vpp</var>. The function is optional for file + systems which have a unique id number for every file in the file system. + It is used internally by the UFS file system and also by the NFSv3 server + to implement the READDIRPLUS NFS call. If the file system does not support + this function, it should return <code class="Er">EOPNOTSUPP</code>.</dd> + <dt><code class="Fn">VFS_LOADVNODE</code>(<var class="Fa">mp</var>, + <var class="Fa">vp</var>, <var class="Fa">key</var>, + <var class="Fa">key_len</var>, <var class="Fa">new_key</var>)</dt> + <dd>Initialise the vnode <var class="Fa">vp</var> with the file identified by + the arguments <var class="Fa">key</var> and <var class="Fa">key_len</var> + for the file system specified by the mount structure + <var class="Fa">mp</var>. + <p class="Pp">The new key is returned in the address specified by + <var class="Fa">new_key</var>.</p> + <p class="Pp">Caller of this function assures no other thread will try to + load this file.</p> + </dd> + <dt id="VFS_NEWVNODE~2"><a class="permalink" href="#VFS_NEWVNODE~2"><code class="Fn">VFS_NEWVNODE</code></a>(<var class="Fa">mp</var>, + <var class="Fa">dvp</var>, <var class="Fa">vp</var>, + <var class="Fa">vap</var>, <var class="Fa">cred</var>, + <var class="Fa">extra</var>, <var class="Fa">key_len</var>, + <var class="Fa">new_key</var>)</dt> + <dd>Initialise the vnode <var class="Fa">vp</var> with a new file for the file + system specified by the mount structure <var class="Fa">mp</var>. + <p class="Pp">The argument <var class="Fa">dvp</var> points to the directory + to create the file in.</p> + <p class="Pp">The argument <var class="Fa">vap</var> points to the + attributes for the file to create.</p> + <p class="Pp">The argument <var class="Fa">cred</var> holds the credentials + for the file to create.</p> + <p class="Pp">The argument <var class="Fa">extra</var> allows the caller to + pass more information about the file to create.</p> + <p class="Pp">The key for the file is returned in the addresses specified by + <var class="Fa">key_len</var> and <var class="Fa">new_key</var>.</p> + </dd> + <dt id="VFS_FHTOVP~2"><a class="permalink" href="#VFS_FHTOVP~2"><code class="Fn">VFS_FHTOVP</code></a>(<var class="Fa">mp</var>, + <var class="Fa">fhp</var>, <var class="Fa">lktype</var>, + <var class="Fa">vpp</var>)</dt> + <dd>Get the vnode for the file handle <var class="Fa">fhp</var> in the file + system specified by the mount structure <var class="Fa">mp</var>, with + lock type <var class="Fa">lktype</var>. <var class="Fa">lktype</var> can + be <code class="Dv">LK_NONE</code>, or <code class="Dv">LK_SHARED</code>, + or <code class="Dv">LK_EXCLUSIVE</code>. The locked vnode is returned in + <var class="Fa">vpp</var>. + <p class="Pp" id="VFS_FHTOVP~3">When exporting, the call to + <a class="permalink" href="#VFS_FHTOVP~3"><code class="Fn">VFS_FHTOVP</code></a>() + should follow a call to + <a class="permalink" href="#netexport_check"><code class="Fn" id="netexport_check">netexport_check</code></a>(), + which checks if the file is accessible to the client.</p> + <p class="Pp">If file handles are not supported by the file system, this + function must return <code class="Er">EOPNOTSUPP</code>.</p> + </dd> + <dt id="VFS_VPTOFH~2"><a class="permalink" href="#VFS_VPTOFH~2"><code class="Fn">VFS_VPTOFH</code></a>(<var class="Fa">vp</var>, + <var class="Fa">fhp</var>, <var class="Fa">fh_size</var>)</dt> + <dd>Get a file handle for the vnode specified by <var class="Fa">vp</var>. The + file handle is returned in <var class="Fa">fhp</var>. The contents of the + file handle are defined by the file system and are not examined by any + other subsystems. It should contain enough information to uniquely + identify a file within the file system as well as noticing when a file has + been removed and the file system resources have been recycled for a new + file. + <p class="Pp">The parameter <var class="Fa">fh_size</var> points to the + container size for the file handle. This parameter should be updated to + the size of the finished file handle. Note that it is legal to call this + function with <var class="Fa">fhp</var> set to + <code class="Dv">NULL</code> in case <var class="Fa">fh_size</var> is + zero. In case <var class="Fa">fh_size</var> indicates a storage space + too small, the storage space required for the file handle corresponding + to <var class="Fa">vp</var> should be filled in and + <code class="Er">E2BIG</code> should be returned.</p> + <p class="Pp">If file handles are not supported by the file system, this + function must return <code class="Er">EOPNOTSUPP</code>.</p> + </dd> + <dt id="VFS_SNAPSHOT~2"><a class="permalink" href="#VFS_SNAPSHOT~2"><code class="Fn">VFS_SNAPSHOT</code></a>(<var class="Fa">mp</var>, + <var class="Fa">vp</var>, <var class="Fa">ts</var>)</dt> + <dd>Take a snapshot of the file system specified by the mount structure + <var class="Fa">mp</var> and make it accessible through the locked vnode + <var class="Fa">vp</var>. If <var class="Fa">ts</var> is not + <code class="Dv">NULL</code> it will receive the time this snapshot was + taken. If the file system does not support this function, it should return + <code class="Er">EOPNOTSUPP</code>.</dd> + <dt><code class="Fn">VFS_SUSPENDCTL</code>(<var class="Fa">mp</var>, + <var class="Fa">cmd</var>)</dt> + <dd>Suspend or resume all operations on this file system. + <var class="Fa">cmd</var> is either + <code class="Dv">SUSPEND_SUSPEND</code> to suspend or + <code class="Dv">SUSPEND_RESUME</code> to resume operations. If the file + system does not support this function, it should return + <code class="Er">EOPNOTSUPP</code>.</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 vfs operations are implemented within the files + <span class="Pa">sys/kern/vfs_subr.c</span> and + <span class="Pa">sys/kern/vfs_init.c</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">intro(9)</a>, <a class="Xr">namei(9)</a>, + <a class="Xr">vfs(9)</a>, <a class="Xr">vfssubr(9)</a>, + <a class="Xr">vnode(9)</a>, <a class="Xr">vnodeops(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The vfs operations vector, its functions and the corresponding + macros appeared in <span class="Ux">4.3BSD</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">August 7, 2020</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/video.9 3.html b/static/netbsd/man9/video.9 3.html new file mode 100644 index 00000000..8177e9c8 --- /dev/null +++ b/static/netbsd/man9/video.9 3.html @@ -0,0 +1,182 @@ +<table class="head"> + <tr> + <td class="head-ltitle">VIDEO(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">VIDEO(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">video</code> — <span class="Nd">interface + between low and high level video drivers</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">dev/video_if.h</a>></code></p> +<p class="Pp"><var class="Ft">device_t</var> + <br/> + <code class="Fn">video_attach_mi</code>(<var class="Fa" style="white-space: nowrap;">const + struct video_hw_if *hw_if</var>, + <var class="Fa" style="white-space: nowrap;">device_t hw_dev</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">video_submit_payload</code>(<var class="Fa" style="white-space: nowrap;">device_t + vl_dev</var>, <var class="Fa" style="white-space: nowrap;">const struct + video_payload *payload</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The video device driver is divided into a high level, machine + independent layer, and a low level hardware dependent layer. The interface + between these is the <var class="Fa">video_hw_if</var> structure function + pointers called by the video layer, and video layer functions called by the + hardware driver.</p> +<p class="Pp">The high level video driver attaches to the low level driver when + the latter calls <var class="Fa">video_attach_mi</var>. The + <var class="Fa">video_hw_if</var> struct is as shown below. + <var class="Fa">dev</var> is the device struct for the hardware device. + Return value is the video layer device.</p> +<div class="Bd Pp Li"> +<pre>struct video_hw_if { + int (*open)(void *, int); /* open hardware */ + void (*close)(void *); /* close hardware */ + + const char * (*get_devname)(void *); + + int (*enum_format)(void *, uint32_t, struct video_format *); + int (*get_format)(void *, struct video_format *); + int (*set_format)(void *, struct video_format *); + int (*try_format)(void *, struct video_format *); + + int (*start_transfer)(void *); + int (*stop_transfer)(void *); + + int (*control_iter_init)(void *, struct video_control_iter *); + int (*control_iter_next)(void *, struct video_control_iter *); + int (*get_control_desc_group)(void *, + struct video_control_desc_group *); + int (*get_control_group)(void *, struct video_control_group *); + int (*set_control_group)(void *, const struct video_control_group *); +};</pre> +</div> +<p class="Pp">The upper layer of the video driver allocates buffers for video + samples. The hardware driver submits data to the video layer with + <var class="Fa">video_submit_payload</var>. <var class="Fa">vl_dev</var> is + the video layer device returned by + <var class="Fa">video_attach_mi</var>.</p> +<div class="Bd Pp Li"> +<pre>struct video_payload { + const uint8_t *data; + size_t size; + int frameno; + bool end_of_frame; +};</pre> +</div> +<dl class="Bl-tag"> + <dt><var class="Fa">data</var></dt> + <dd>Pointer to the video data for this payload. This may only be a portion of + the data in one video sample or frame.</dd> + <dt><var class="Fa">size</var></dt> + <dd>Size in bytes of the video data in this payload</dd> + <dt><var class="Fa">frameno</var></dt> + <dd>Frame number to which this payload belongs. The hardware driver must + toggle the frame number between 0 and 1 so the video layer can detect + sample or frame boundaries.</dd> + <dt><var class="Fa">end_of_frame</var></dt> + <dd>Optional end of frame marker. If the hardware layer sets this, the video + layer can immediately pass the completed sample or frame to userspace + rather than waiting for the next payload to toggle + <var class="Fa">frameno</var>.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="HARDWARE-LAYER_FUNCTIONS"><a class="permalink" href="#HARDWARE-LAYER_FUNCTIONS">HARDWARE-LAYER + FUNCTIONS</a></h1> +<p class="Pp">The fields of <var class="Va">video_hw_if</var> are described in + some more detail below. Some fields are optional and can be set to + <code class="Dv">NULL</code> if not needed.</p> +<dl class="Bl-tag"> + <dt id="int"><a class="permalink" href="#int"><code class="Dv">int open(void + *hdl, int flags)</code></a></dt> + <dd>optional, is called when the video device is opened. It should initialize + the hardware for I/O. Every successful call to <var class="Va">open</var> + is matched by a call to <var class="Va">close</var>. Return 0 on success, + otherwise an error code.</dd> + <dt id="void"><a class="permalink" href="#void"><code class="Dv">void + close(void *hdl)</code></a></dt> + <dd>optional, is called when the audio device is closed.</dd> + <dt id="const"><a class="permalink" href="#const"><code class="Dv">const char + * get_devname(void *hdl)</code></a></dt> + <dd>mandatory, returns a NUL-terminated string naming the device, e.g. a + vendor and product model name.</dd> + <dt id="int~2"><a class="permalink" href="#int~2"><code class="Dv">int + enum_format(void *hdl, uint32_t index, struct video_format + *format);</code></a></dt> + <dd>mandatory, called with an <var class="Va">index</var> from 0 to + <var class="Va">max_index - 1</var>. Fills <var class="Va">format</var> + with the format description at that index. Returns 0 on success, otherwise + an error code.</dd> + <dt id="int~3"><a class="permalink" href="#int~3"><code class="Dv">int + get_format(void *hdl, struct video_format *format)</code></a></dt> + <dd>mandatory, fills <var class="Va">format</var> with the current video + format. There should be a default format so this function works before and + streaming has begun. Returns 0 on success, otherwise an error code.</dd> + <dt id="int~4"><a class="permalink" href="#int~4"><code class="Dv">int + set_format(void *hdl, struct video_format *format)</code></a></dt> + <dd>mandatory, sets the format of the video stream based on + <var class="Va">format</var>. Fills <var class="Va">format</var> with the + actual format used which may not be the same as requested. Returns 0 on + success, otherwise an error code.</dd> + <dt id="int~5"><a class="permalink" href="#int~5"><code class="Dv">int + try_format(void *hdl, struct video_format *format)</code></a></dt> + <dd>optional, like <var class="Va">set_format</var> but does not actually + change the stream format, just checks what is available. Returns 0 on + success, otherwise an error code.</dd> + <dt id="int~6"><a class="permalink" href="#int~6"><code class="Dv">int + start_transfer(void *hdl)</code></a></dt> + <dd>mandatory, starts the capture of video frames. Incoming video data must be + submitted to the video layer with repeated calls to + <a class="permalink" href="#video_submit_payload"><code class="Fn" id="video_submit_payload">video_submit_payload</code></a>().</dd> + <dt id="int~7"><a class="permalink" href="#int~7"><code class="Dv">int + stop_transfer(void *hdl)</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="int~8"><a class="permalink" href="#int~8"><code class="Dv">int + control_iter_init(void *hdl, struct video_control_iter *)</code></a></dt> + <dd>Does nothing at this time.</dd> + <dt id="int~9"><a class="permalink" href="#int~9"><code class="Dv">int + control_iter_next(void *hdl, struct video_control_iter *)</code></a></dt> + <dd>Does nothing at this time.</dd> + <dt id="int~10"><a class="permalink" href="#int~10"><code class="Dv">int + get_control_group(void *hdl, struct video_control_group *)</code></a></dt> + <dd style="width: auto;"> </dd> + <dt id="int~11"><a class="permalink" href="#int~11"><code class="Dv">int + set_control_group(void *hdl, struct video_control_group *)</code></a></dt> + <dd style="width: auto;"> </dd> +</dl> +</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">video(4)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Patrick Mahoney</span> + <<a class="Mt" href="mailto:pat@polycrystal.org">pat@polycrystal.org</a>></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Incomplete. Only supports a single video capture stream. Does not + support output streams. Format handling may change in the future. Control + handling may change. Current design requires copying all incoming video + data.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">July 24, 2008</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/vnodeops.9 3.html b/static/netbsd/man9/vnodeops.9 3.html new file mode 100644 index 00000000..17e8c6f5 --- /dev/null +++ b/static/netbsd/man9/vnodeops.9 3.html @@ -0,0 +1,1441 @@ +<table class="head"> + <tr> + <td class="head-ltitle">VNODEOPS(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">VNODEOPS(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">vnodeops</code>, + <code class="Nm">VOP_LOOKUP</code>, <code class="Nm">VOP_CREATE</code>, + <code class="Nm">VOP_MKNOD</code>, <code class="Nm">VOP_OPEN</code>, + <code class="Nm">VOP_CLOSE</code>, <code class="Nm">VOP_ACCESS</code>, + <code class="Nm">VOP_GETATTR</code>, <code class="Nm">VOP_SETATTR</code>, + <code class="Nm">VOP_READ</code>, <code class="Nm">VOP_WRITE</code>, + <code class="Nm">VOP_FALLOCATE</code>, <code class="Nm">VOP_FDISCARD</code>, + <code class="Nm">VOP_IOCTL</code>, <code class="Nm">VOP_FCNTL</code>, + <code class="Nm">VOP_POLL</code>, <code class="Nm">VOP_KQFILTER</code>, + <code class="Nm">VOP_REVOKE</code>, <code class="Nm">VOP_MMAP</code>, + <code class="Nm">VOP_FSYNC</code>, <code class="Nm">VOP_SEEK</code>, + <code class="Nm">VOP_REMOVE</code>, <code class="Nm">VOP_LINK</code>, + <code class="Nm">VOP_RENAME</code>, <code class="Nm">VOP_MKDIR</code>, + <code class="Nm">VOP_RMDIR</code>, <code class="Nm">VOP_SYMLINK</code>, + <code class="Nm">VOP_READDIR</code>, <code class="Nm">VOP_READLINK</code>, + <code class="Nm">VOP_ABORTOP</code>, <code class="Nm">VOP_INACTIVE</code>, + <code class="Nm">VOP_RECLAIM</code>, <code class="Nm">VOP_LOCK</code>, + <code class="Nm">VOP_UNLOCK</code>, <code class="Nm">VOP_ISLOCKED</code>, + <code class="Nm">VOP_BMAP</code>, <code class="Nm">VOP_PRINT</code>, + <code class="Nm">VOP_PATHCONF</code>, <code class="Nm">VOP_ADVLOCK</code>, + <code class="Nm">VOP_WHITEOUT</code>, <code class="Nm">VOP_GETPAGES</code>, + <code class="Nm">VOP_PUTPAGES</code>, <code class="Nm">VOP_STRATEGY</code>, + <code class="Nm">VOP_BWRITE</code>, <code class="Nm">VOP_GETEXTATTR</code>, + <code class="Nm">VOP_SETEXTATTR</code>, + <code class="Nm">VOP_LISTEXTATTR</code>, + <code class="Nm">VOP_DELETEEXTATTR</code> — <span class="Nd">vnode + operations</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/buf.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/dirent.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/vnode.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/mount.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/namei.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/unistd.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/fcntl.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/lockf.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/extattr.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_LOOKUP</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *cnp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_CREATE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *cnp</var>, + <var class="Fa" style="white-space: nowrap;">struct vattr *vap</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_MKNOD</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *cnp</var>, + <var class="Fa" style="white-space: nowrap;">struct vattr *vap</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_OPEN</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + mode</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_CLOSE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + fflag</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_ACCESS</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + mode</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_GETATTR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct vattr + *vap</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_SETATTR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct vattr + *vap</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_READ</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct uio + *uio</var>, <var class="Fa" style="white-space: nowrap;">int ioflag</var>, + <var class="Fa" style="white-space: nowrap;">kauth_cred_t cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_WRITE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct uio + *uio</var>, <var class="Fa" style="white-space: nowrap;">int ioflag</var>, + <var class="Fa" style="white-space: nowrap;">kauth_cred_t cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_FALLOCATE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">off_t + pos</var>, <var class="Fa" style="white-space: nowrap;">off_t + len</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_FDISCARD</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">off_t + pos</var>, <var class="Fa" style="white-space: nowrap;">off_t + len</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_IOCTL</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">u_long + command</var>, <var class="Fa" style="white-space: nowrap;">void + *data</var>, <var class="Fa" style="white-space: nowrap;">int fflag</var>, + <var class="Fa" style="white-space: nowrap;">kauth_cred_t cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_FCNTL</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">u_int + command</var>, <var class="Fa" style="white-space: nowrap;">void + *data</var>, <var class="Fa" style="white-space: nowrap;">int fflag</var>, + <var class="Fa" style="white-space: nowrap;">kauth_cred_t cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_POLL</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + events</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_KQFILTER</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct knote + *kn</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_REVOKE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_MMAP</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">vm_prot_t + prot</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_FSYNC</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">int flags</var>, + <var class="Fa" style="white-space: nowrap;">off_t offlo</var>, + <var class="Fa" style="white-space: nowrap;">off_t offhi</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_SEEK</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">off_t + oldoff</var>, <var class="Fa" style="white-space: nowrap;">off_t + newoff</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_REMOVE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *vp</var>, <var class="Fa" style="white-space: nowrap;">struct componentname + *cnp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_LINK</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *vp</var>, <var class="Fa" style="white-space: nowrap;">struct componentname + *cnp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_RENAME</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *fdvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *fvp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *fcnp</var>, + <var class="Fa" style="white-space: nowrap;">struct vnode *tdvp</var>, + <var class="Fa" style="white-space: nowrap;">struct vnode *tvp</var>, + <var class="Fa" style="white-space: nowrap;">struct componentname + *tcnp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_MKDIR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *cnp</var>, + <var class="Fa" style="white-space: nowrap;">struct vattr *vap</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_RMDIR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *vp</var>, <var class="Fa" style="white-space: nowrap;">struct componentname + *cnp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_SYMLINK</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *cnp</var>, + <var class="Fa" style="white-space: nowrap;">struct vattr *vap</var>, + <var class="Fa" style="white-space: nowrap;">char *target</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_READDIR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct uio + *uio</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>, <var class="Fa" style="white-space: nowrap;">int *eofflag</var>, + <var class="Fa" style="white-space: nowrap;">off_t **cookies</var>, + <var class="Fa" style="white-space: nowrap;">int *ncookies</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_READLINK</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct uio + *uio</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_ABORTOP</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *cnp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_INACTIVE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_RECLAIM</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_LOCK</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_UNLOCK</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_ISLOCKED</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_BMAP</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">daddr_t + bn</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + **vpp</var>, <var class="Fa" style="white-space: nowrap;">daddr_t + *bnp</var>, <var class="Fa" style="white-space: nowrap;">int + *runp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_PRINT</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_PATHCONF</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + name</var>, <var class="Fa" style="white-space: nowrap;">register_t + *retval</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_ADVLOCK</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">void + *id</var>, <var class="Fa" style="white-space: nowrap;">int op</var>, + <var class="Fa" style="white-space: nowrap;">struct flock *fl</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_WHITEOUT</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *dvp</var>, <var class="Fa" style="white-space: nowrap;">struct + componentname *cnp</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_GETPAGES</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">voff_t + offset</var>, <var class="Fa" style="white-space: nowrap;">struct vm_page + **m</var>, <var class="Fa" style="white-space: nowrap;">int *count</var>, + <var class="Fa" style="white-space: nowrap;">int centeridx</var>, + <var class="Fa" style="white-space: nowrap;">vm_prot_t access_type</var>, + <var class="Fa" style="white-space: nowrap;">int advice</var>, + <var class="Fa" style="white-space: nowrap;">int flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_PUTPAGES</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">voff_t + offlo</var>, <var class="Fa" style="white-space: nowrap;">voff_t + offhi</var>, <var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_STRATEGY</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *bp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_BWRITE</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *bp</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_GETEXTATTR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + attrnamespace</var>, <var class="Fa" style="white-space: nowrap;">const char + *name</var>, <var class="Fa" style="white-space: nowrap;">struct uio + *uio</var>, <var class="Fa" style="white-space: nowrap;">size_t *size</var>, + <var class="Fa" style="white-space: nowrap;">kauth_cred_t cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_SETEXTATTR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + attrnamespace</var>, <var class="Fa" style="white-space: nowrap;">const char + *name</var>, <var class="Fa" style="white-space: nowrap;">struct uio + *uio</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_LISTEXTATTR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + attrnamespace</var>, <var class="Fa" style="white-space: nowrap;">struct uio + *uio</var>, <var class="Fa" style="white-space: nowrap;">size_t *size</var>, + <var class="Fa" style="white-space: nowrap;">kauth_cred_t cred</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">VOP_DELETEEXTATTR</code>(<var class="Fa" style="white-space: nowrap;">struct + vnode *vp</var>, <var class="Fa" style="white-space: nowrap;">int + attrnamespace</var>, <var class="Fa" style="white-space: nowrap;">const char + *name</var>, <var class="Fa" style="white-space: nowrap;">kauth_cred_t + cred</var>);</p> +<p class="Pp">Not all header files are required for each function.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The vnode operations vector describes what operations can be done + to the file associated with the vnode. The system maintains one vnode + operations vector for each file system type configured into the kernel. The + vnode operations vector contains a pointer to a function for each operation + supported by the file system. Many of the functions described in the vnode + operations vector are closely related to their corresponding system calls. + In most cases, they are called as a result of the system call associated + with the operation being invoked.</p> +<p class="Pp">Functions in the vnode operations vector are invoked using + specialized macros. The following table gives a summary of the + operations.</p> +<p class="Pp"></p> +<table class="Bl-column Bl-compact"> + <tr id="Macro"> + <td><a class="permalink" href="#Macro"><b class="Sy">Macro</b></a></td> + <td><a class="permalink" href="#Description"><b class="Sy" id="Description">Description</b></a></td> + </tr> + <tr> + <td>VOP_LOOKUP</td> + <td>Lookup file name in name cache</td> + </tr> + <tr> + <td>VOP_CREATE</td> + <td>Create a new file</td> + </tr> + <tr> + <td>VOP_MKNOD</td> + <td>Make a new device</td> + </tr> + <tr> + <td>VOP_OPEN</td> + <td>Open a file</td> + </tr> + <tr> + <td>VOP_CLOSE</td> + <td>Close a file</td> + </tr> + <tr> + <td>VOP_ACCESS</td> + <td>Determine file accessibility</td> + </tr> + <tr> + <td>VOP_GETATTR</td> + <td>Get file attributes</td> + </tr> + <tr> + <td>VOP_SETATTR</td> + <td>Set file attributes</td> + </tr> + <tr> + <td>VOP_READ</td> + <td>Read from a file</td> + </tr> + <tr> + <td>VOP_WRITE</td> + <td>Write to a file</td> + </tr> + <tr> + <td>VOP_FALLOCATE</td> + <td>Allocate backing for a file</td> + </tr> + <tr> + <td>VOP_FDISCARD</td> + <td>Discard backing for a file</td> + </tr> + <tr> + <td>VOP_IOCTL</td> + <td>Perform device-specific I/O</td> + </tr> + <tr> + <td>VOP_FCNTL</td> + <td>Perform file control</td> + </tr> + <tr> + <td>VOP_POLL</td> + <td>Test if poll event has occurred</td> + </tr> + <tr> + <td>VOP_KQFILTER</td> + <td>Register a knote</td> + </tr> + <tr> + <td>VOP_REVOKE</td> + <td>Eliminate vnode activity</td> + </tr> + <tr> + <td>VOP_MMAP</td> + <td>Map file into user address space</td> + </tr> + <tr> + <td>VOP_FSYNC</td> + <td>Flush pending data to disk</td> + </tr> + <tr> + <td>VOP_SEEK</td> + <td>Test if file is seekable</td> + </tr> + <tr> + <td>VOP_REMOVE</td> + <td>Remove a file</td> + </tr> + <tr> + <td>VOP_LINK</td> + <td>Link a file</td> + </tr> + <tr> + <td>VOP_RENAME</td> + <td>Rename a file</td> + </tr> + <tr> + <td>VOP_MKDIR</td> + <td>Make a new directory</td> + </tr> + <tr> + <td>VOP_RMDIR</td> + <td>Remove a directory</td> + </tr> + <tr> + <td>VOP_SYMLINK</td> + <td>Create a symbolic link</td> + </tr> + <tr> + <td>VOP_READDIR</td> + <td>Read directory entry</td> + </tr> + <tr> + <td>VOP_READLINK</td> + <td>Read contents of a symlink</td> + </tr> + <tr> + <td>VOP_ABORTOP</td> + <td>Abort pending operation</td> + </tr> + <tr> + <td>VOP_INACTIVE</td> + <td>Release the inactive vnode</td> + </tr> + <tr> + <td>VOP_RECLAIM</td> + <td>Reclaim vnode for another file</td> + </tr> + <tr> + <td>VOP_LOCK</td> + <td>Sleep until vnode lock is free</td> + </tr> + <tr> + <td>VOP_UNLOCK</td> + <td>Wake up process sleeping on lock</td> + </tr> + <tr> + <td>VOP_ISLOCKED</td> + <td>Test if vnode is locked</td> + </tr> + <tr> + <td>VOP_BMAP</td> + <td>Logical block number conversion</td> + </tr> + <tr> + <td>VOP_PRINT</td> + <td>Print debugging information</td> + </tr> + <tr> + <td>VOP_PATHCONF</td> + <td>Return POSIX pathconf data</td> + </tr> + <tr> + <td>VOP_ADVLOCK</td> + <td>Advisory record locking</td> + </tr> + <tr> + <td>VOP_WHITEOUT</td> + <td>Whiteout vnode</td> + </tr> + <tr> + <td>VOP_GETPAGES</td> + <td>Read VM pages from file</td> + </tr> + <tr> + <td>VOP_PUTPAGES</td> + <td>Write VM pages to file</td> + </tr> + <tr> + <td>VOP_STRATEGY</td> + <td>Read/write a file system buffer</td> + </tr> + <tr> + <td>VOP_BWRITE</td> + <td>Write a file system buffer</td> + </tr> + <tr> + <td>VOP_GETEXTATTR</td> + <td>Get extended attribute</td> + </tr> + <tr> + <td>VOP_SETEXTATTR</td> + <td>Set extended attribute</td> + </tr> + <tr> + <td>VOP_LISTEXTATTR</td> + <td>List extended attributes</td> + </tr> + <tr> + <td>VOP_DELETEEXTATTR</td> + <td>Remove extended attribute</td> + </tr> +</table> +<p class="Pp">The implementation details of the vnode operations vector are not + quite what is described here.</p> +<p class="Pp">If the file system type does not support a specific operation, it + must nevertheless assign an appropriate stub in the vnode operations vector + to do the minimum required of it. In most cases, such functions either do + nothing or return an error value to the effect that it is not supported.</p> +<p class="Pp">Many of the functions in the vnode operations vector take a + componentname structure. It is used to encapsulate many parameters into a + single function argument. It has the following structure:</p> +<div class="Bd Pp Li"> +<pre>struct componentname { + /* + * Arguments to lookup. + */ + uint32_t cn_nameiop; /* namei operation */ + uint32_t cn_flags; /* flags to namei */ + kauth_cred_t cn_cred; /* credentials */ + /* + * Shared between lookup and commit routines. + */ + const char *cn_nameptr; /* pointer to looked up name */ + size_t cn_namelen; /* length of looked up component */ + size_t cn_consume; /* chars to consume in lookup() */ +};</pre> +</div> +<p class="Pp" id="VOP_LOOKUP">The top half of the structure is used exclusively + for the pathname lookups using + <a class="permalink" href="#VOP_LOOKUP"><code class="Fn">VOP_LOOKUP</code></a>() + and is initialized by the caller. The semantics of the lookup are affected + by the lookup operation specified in + <a class="permalink" href="#cn_nameiop"><i class="Em" id="cn_nameiop">cn_nameiop</i></a> + and the flags specified in + <a class="permalink" href="#cn_flags"><i class="Em" id="cn_flags">cn_flags</i></a>. + Valid operations are:</p> +<p class="Pp"></p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>LOOKUP</dt> + <dd>perform name lookup only</dd> + <dt>CREATE</dt> + <dd>set up for file creation</dd> + <dt>DELETE</dt> + <dd>set up for file deletion</dd> + <dt>RENAME</dt> + <dd>set up for file renaming</dd> + <dt>OPMASK</dt> + <dd>mask for operation</dd> +</dl> +</div> +<p class="Pp" id="cn-_cn_flags">Valid values for + <a class="permalink" href="#cn-_cn_flags"><i class="Em">cn->cn_flags</i></a> + are:</p> +<p class="Pp"></p> +<div class="Bd-indent"> +<dl class="Bl-tag Bl-compact"> + <dt>LOCKLEAF</dt> + <dd>lock inode on return</dd> + <dt>LOCKPARENT</dt> + <dd>want parent vnode returned locked</dd> + <dt>NOCACHE</dt> + <dd>name must not be left in name cache (see + <a class="Xr">namecache(9)</a>)</dd> + <dt>FOLLOW</dt> + <dd>follow symbolic links</dd> + <dt>NOFOLLOW</dt> + <dd>do not follow symbolic links (pseudo)</dd> + <dt>MODMASK</dt> + <dd>mask of operational modifiers</dd> +</dl> +</div> +<p class="Pp">No vnode operations may be called from interrupt context. Most + operations also require the vnode to be locked on entry. To prevent + deadlocks, when acquiring locks on multiple vnodes, the lock of parent + directory must be acquired before the lock on the child directory.</p> +<p class="Pp">Vnode operations for a file system type generally should not be + called directly from the kernel, but accessed indirectly through the + high-level convenience functions discussed in + <a class="Xr">vnsubr(9)</a>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="VOP_LOOKUP~2"><a class="permalink" href="#VOP_LOOKUP~2"><code class="Fn">VOP_LOOKUP</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vpp</var>, <var class="Fa">cnp</var>)</dt> + <dd>Lookup a single pathname component in a given directory. The argument + <var class="Fa">dvp</var> is the locked vnode of the directory to search + and <var class="Fa">cnp</var> is the pathname component to be searched + for. If the pathname component is found, the address of the resulting + unlocked vnode is returned in <var class="Fa">vpp</var>. The operation + specified in + <a class="permalink" href="#cnp-_cn_nameiop"><i class="Em" id="cnp-_cn_nameiop">cnp->cn_nameiop</i></a> + indicates <code class="Fn">VOP_LOOKUP</code>() the reason for requesting + the lookup and uses it to cache file system type specific information in + the vnode for subsequent operations. + <p class="Pp" id="VOP_LOOKUP~3">There are three types of lookups: + ".", ".." (ISDOTDOT), and regular. If the pathname + component being searched for is ".", then + <var class="Fa">dvp</var> has an extra reference added to it and it is + returned in <var class="Fa">*vpp</var>. For other pathname components, + <a class="permalink" href="#VOP_LOOKUP~3"><code class="Fn">VOP_LOOKUP</code></a>() + checks the accessibility of the directory and searches the name cache + for the pathname component. See <a class="Xr">namecache(9)</a>. If the + pathname is not found in the name cache, the directory is searched for + the pathname. The resulting unlocked vnode is returned in + <var class="Fa">vpp</var>. <var class="Fa">dvp</var> is always returned + locked.</p> + <p class="Pp">On failure <var class="Fa">*vpp</var> is + <code class="Dv">NULL</code>, and <var class="Fa">*dvp</var> is left + locked. If the operation is successful <var class="Fa">*vpp</var> is + unlocked and zero is returned. Typically, if <var class="Fa">*vpp</var> + and <var class="Fa">dvp</var> are the same vnode the caller will need to + release twice (decrement the reference count) and unlock once.</p> + </dd> + <dt id="VOP_CREATE"><a class="permalink" href="#VOP_CREATE"><code class="Fn">VOP_CREATE</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vpp</var>, <var class="Fa">cnp</var>, + <var class="Fa">vap</var>)</dt> + <dd>Create a new file in a given directory. The argument + <var class="Fa">dvp</var> is the locked vnode of the directory to create + the new file in and <var class="Fa">cnp</var> is the pathname component of + the new file. The argument <var class="Fa">vap</var> specifies the + attributes that the new file should be created with. If the file is + successfully created, the address of the resulting unlocked vnode is + returned in <var class="Fa">vpp</var> and zero is returned. + <p class="Pp" id="VOP_LOOKUP~4">This function is called after + <a class="permalink" href="#VOP_LOOKUP~4"><code class="Fn">VOP_LOOKUP</code></a>() + when a file is being created. Normally, + <code class="Fn">VOP_LOOKUP</code>() will have set the SAVENAME flag in + <i class="Em">cnp->cn_flags</i> to keep the memory pointed to by + <i class="Em">cnp->cn_pnbuf</i> valid. If an error is detected when + creating the file, this memory is released. If the file is created + successfully it will be released unless the SAVESTART flags in specified + in <i class="Em">cnp->cn_flags</i>.</p> + </dd> + <dt id="VOP_MKNOD"><a class="permalink" href="#VOP_MKNOD"><code class="Fn">VOP_MKNOD</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vpp</var>, <var class="Fa">cnp</var>, + <var class="Fa">vap</var>)</dt> + <dd>Make a new device-special file in a given directory. The argument + <var class="Fa">dvp</var> is the locked vnode of the directory to create + the new device-special file in and <var class="Fa">cnp</var> is the + pathname component of the new device-special file. The argument + <var class="Fa">vap</var> specifies the attributes that the new + device-special file should be created with. If the file is successfully + created, the address of the resulting unlocked vnode is returned in + <var class="Fa">vpp</var> and zero is returned. + <p class="Pp" id="VOP_LOOKUP~5">This function is called after + <a class="permalink" href="#VOP_LOOKUP~5"><code class="Fn">VOP_LOOKUP</code></a>() + when a device-special file is being created. Normally, + <code class="Fn">VOP_LOOKUP</code>() will have set the SAVENAME flag in + <i class="Em">cnp->cn_flags</i> to keep the memory pointed to by + <i class="Em">cnp->cn_pnbuf</i> valid. If an error is detected when + creating the device-special file, this memory is released. If the + device-special file is created successfully it will be released unless + the SAVESTART flags in specified in + <i class="Em">cnp->cn_flags</i>.</p> + </dd> + <dt><code class="Fn">VOP_OPEN</code>(<var class="Fa">vp</var>, + <var class="Fa">mode</var>, <var class="Fa">cred</var>)</dt> + <dd>Open a file. The argument <var class="Fa">vp</var> is the vnode of the + file to open and <var class="Fa">mode</var> specifies the access mode + required by the calling process. The calling credentials are specified by + <var class="Fa">cred</var>. The access mode is a set of flags, including + FREAD, FWRITE, O_NONBLOCK, O_APPEND, etc. + <code class="Fn">VOP_OPEN</code>() must be called before a file can be + accessed by a thread. The vnode reference count is incremented. + <p class="Pp" id="VOP_OPEN"><a class="permalink" href="#VOP_OPEN"><code class="Fn">VOP_OPEN</code></a>() + expects the vnode <var class="Fa">vp</var> to be locked on entry and + will leave it locked on return. If the operation is successful zero is + returned, otherwise an appropriate error code is returned.</p> + </dd> + <dt id="VOP_CLOSE"><a class="permalink" href="#VOP_CLOSE"><code class="Fn">VOP_CLOSE</code></a>(<var class="Fa">vp</var>, + <var class="Fa">fflag</var>, <var class="Fa">cred</var>)</dt> + <dd>Close a file. The argument <var class="Fa">vp</var> is the vnode of the + file to close and <var class="Fa">fflag</var> specifies the access mode by + the calling process. The possible flags are <code class="Dv">FREAD</code>, + <code class="Dv">FWRITE</code> and <code class="Dv">FNONBLOCK</code>. The + calling credentials are specified by <var class="Fa">cred</var>. + <code class="Fn">VOP_CLOSE</code>() frees resources allocated by + <code class="Fn">VOP_OPEN</code>(). + <p class="Pp">The vnode <var class="Fa">vp</var> will be locked on entry and + should remain locked on return.</p> + </dd> + <dt id="VOP_ACCESS"><a class="permalink" href="#VOP_ACCESS"><code class="Fn">VOP_ACCESS</code></a>(<var class="Fa">vp</var>, + <var class="Fa">mode</var>, <var class="Fa">cred</var>)</dt> + <dd>Determine the accessibility (permissions) of the file against the + specified credentials. The argument <var class="Fa">vp</var> is the vnode + of the file to check, <var class="Fa">mode</var> is the type of access + required and <var class="Fa">cred</var> contains the user credentials to + check. The argument <var class="Fa">mode</var> is a mask which can contain + VREAD, VWRITE or VEXEC. If the file is accessible in the specified way, + zero is returned, otherwise an appropriate error code is returned. + <p class="Pp">The vnode <var class="Fa">vp</var> will be locked on entry and + should remain locked on return.</p> + </dd> + <dt id="VOP_GETATTR"><a class="permalink" href="#VOP_GETATTR"><code class="Fn">VOP_GETATTR</code></a>(<var class="Fa">vp</var>, + <var class="Fa">vap</var>, <var class="Fa">cred</var>)</dt> + <dd>Get specific vnode attributes on a file. The argument + <var class="Fa">vp</var> is the vnode of the file to get the attributes + for. The argument <var class="Fa">cred</var> specifies the calling + credentials. <code class="Fn">VOP_GETATTR</code>() uses the file system + type specific data object <i class="Em">vp->v_data</i> to reference the + underlying file attributes. The attributes are returned in + <var class="Fa">vap</var>. Attributes which are not available are set to + the value VNOVAL. + <p class="Pp" id="VOP_GETATTR~2">For more information on vnode attributes + see <a class="Xr">vattr(9)</a>. Historically it was considered + acceptable to call + <a class="permalink" href="#VOP_GETATTR~2"><code class="Fn">VOP_GETATTR</code></a>() + without first locking the vnode. This usage is deprecated.</p> + <p class="Pp">The vnode <var class="Fa">vp</var> will be locked on entry and + should remain locked on return.</p> + </dd> + <dt id="VOP_SETATTR"><a class="permalink" href="#VOP_SETATTR"><code class="Fn">VOP_SETATTR</code></a>(<var class="Fa">vp</var>, + <var class="Fa">vap</var>, <var class="Fa">cred</var>)</dt> + <dd>Set specific vnode attributes on a file. The argument + <var class="Fa">vp</var> is the locked vnode of the file to set the + attributes for. The argument <var class="Fa">cred</var> specifies the + calling credentials. <code class="Fn">VOP_SETATTR</code>() uses the file + system type specific data object <i class="Em">vp->v_data</i> to + reference the underlying file attributes. The new attributes are defined + in <var class="Fa">vap</var>. Attributes which are not being modified by + <code class="Fn">VOP_SETATTR</code>() should be set to the value VNOVAL. + If the operation is successful zero is returned, otherwise an appropriate + error is returned. + <p class="Pp">For more information on vnode attributes see + <a class="Xr">vattr(9)</a>.</p> + </dd> + <dt id="VOP_READ"><a class="permalink" href="#VOP_READ"><code class="Fn">VOP_READ</code></a>(<var class="Fa">vp</var>, + <var class="Fa">uio</var>, <var class="Fa">ioflag</var>, + <var class="Fa">cred</var>)</dt> + <dd>Read the contents of a file. The argument <var class="Fa">vp</var> is the + vnode of the file to read from, <var class="Fa">uio</var> is the location + to read the data into, <var class="Fa">ioflag</var> is a set of flags and + <var class="Fa">cred</var> are the credentials of the calling process. + <p class="Pp">The <var class="Fa">ioflag</var> argument is used to give + directives and hints to the file system. When attempting a read, the + high 16 bits are used to provide a read-ahead hint (in unit of file + system blocks) that the file system should attempt. The low 16 bits are + a bit mask which can contain the following flags:</p> + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt>IO_UNIT</dt> + <dd>do I/O as atomic unit</dd> + <dt>IO_APPEND</dt> + <dd>append write to end</dd> + <dt>IO_SYNC</dt> + <dd>sync I/O file integrity completion</dd> + <dt>IO_NODELOCKED</dt> + <dd>underlying node already locked</dd> + <dt>IO_NDELAY</dt> + <dd>FNDELAY flag set in file table</dd> + <dt>IO_DSYNC</dt> + <dd>sync I/O data integrity completion</dd> + <dt>IO_ALTSEMANTICS</dt> + <dd>use alternate I/O semantics</dd> + <dt>IO_NORMAL</dt> + <dd>operate on regular data</dd> + <dt>IO_EXT</dt> + <dd>operate on extended attributes</dd> + <dt>IO_DIRECT</dt> + <dd>do not buffer data in the kernel</dd> + </dl> + </div> + <p class="Pp">Zero is returned on success, otherwise an error is returned. + The vnode should be locked on entry and remains locked on exit.</p> + </dd> + <dt id="VOP_WRITE"><a class="permalink" href="#VOP_WRITE"><code class="Fn">VOP_WRITE</code></a>(<var class="Fa">vp</var>, + <var class="Fa">uio</var>, <var class="Fa">ioflag</var>, + <var class="Fa">cred</var>)</dt> + <dd>Write to a file. The argument <var class="Fa">vp</var> is the vnode of the + file to write to, <var class="Fa">uio</var> is the location of the data to + write, <var class="Fa">ioflag</var> is a set of flags and + <var class="Fa">cred</var> are the credentials of the calling process. + <p class="Pp" id="VOP_READ~2">The <var class="Fa">ioflag</var> argument is + used to give directives and hints to the file system. The low 16 bits + are a bit mask which can contain the same flags as + <a class="permalink" href="#VOP_READ~2"><code class="Fn">VOP_READ</code></a>().</p> + <p class="Pp">Zero is returned on success, otherwise an error is returned. + The vnode should be locked on entry and remains locked on exit.</p> + </dd> + <dt id="VOP_FALLOCATE"><a class="permalink" href="#VOP_FALLOCATE"><code class="Fn">VOP_FALLOCATE</code></a>(<var class="Fa">vp</var>, + <var class="Fa">pos</var>, <var class="Fa">len</var>)</dt> + <dd>Allocate backing store. The argument <var class="Fa">vp</var> is the vnode + for the file. The <var class="Fa">pos</var> and <var class="Fa">len</var> + arguments (specified in bytes) name an extent within the file. The blocks + underlying this range, rounding up at the top and down at the bottom if + needed, are checked; if no physical storage is allocated, a physical block + is allocated and zeroed. This operation removes “holes” from + files.</dd> + <dt id="VOP_FDISCARD"><a class="permalink" href="#VOP_FDISCARD"><code class="Fn">VOP_FDISCARD</code></a>(<var class="Fa">vp</var>, + <var class="Fa">pos</var>, <var class="Fa">len</var>)</dt> + <dd>Discard backing store. The argument <var class="Fa">vp</var> is the vnode + for the file. The <var class="Fa">pos</var> and <var class="Fa">len</var> + arguments (specified in bytes) name an extent within the file. The blocks + underlying this range, rounding down at the top and up at the bottom if + needed, are checked. If any physical storage is used, it is deallocated. + This operation creates “holes” in files. Discarded blocks of + regular files read back afterwards as zeroes. On devices, the underlying + discard-block operation if any (e.g. ATA TRIM) is issued. The device + handles this as it sees fit. In particular it is + <a class="permalink" href="#not"><i class="Em" id="not">not</i></a> + guaranteed that discarded blocks on devices will be zeroed; reading a + discarded block might produce zeros, or ones, or the previously existing + data, or some other data, or trash.</dd> + <dt><code class="Fn">VOP_IOCTL</code>(<var class="Fa">vp</var>, + <var class="Fa">command</var>, <var class="Fa">data</var>, + <var class="Fa">fflag</var>, <var class="Fa">cred</var>)</dt> + <dd>Perform device-specific I/O. The argument <var class="Fa">vp</var> is the + vnode of the file, normally representing a device. The argument + <var class="Fa">command</var> specifies the device-specific operation to + perform and <var class="Fa">cnp</var> provides extra data for the + specified operation. The argument <var class="Fa">fflags</var> is a set of + flags. The argument <var class="Fa">cred</var> is the caller's + credentials. If the operation is successful, zero is returned, otherwise + an appropriate error code is returned. + <p class="Pp" id="VOP_IOCTL">Most file systems do not supply a function for + <a class="permalink" href="#VOP_IOCTL"><code class="Fn">VOP_IOCTL</code></a>(). + This function implements the <a class="Xr">ioctl(2)</a> system call.</p> + </dd> + <dt id="VOP_FCNTL"><a class="permalink" href="#VOP_FCNTL"><code class="Fn">VOP_FCNTL</code></a>(<var class="Fa">vp</var>, + <var class="Fa">command</var>, <var class="Fa">data</var>, + <var class="Fa">fflag</var>, <var class="Fa">cred</var>)</dt> + <dd>Perform file control. The argument <var class="Fa">vp</var> is the locked + vnode of the file. The argument <var class="Fa">command</var> specifies + the operation to perform and <var class="Fa">cnp</var> provides extra data + for the specified operation. The argument <var class="Fa">fflags</var> is + a set of flags. The argument <var class="Fa">cred</var> is the caller's + credentials. If the operation is successful, zero is returned, otherwise + an appropriate error code is returned.</dd> + <dt id="VOP_POLL"><a class="permalink" href="#VOP_POLL"><code class="Fn">VOP_POLL</code></a>(<var class="Fa">vp</var>, + <var class="Fa">events</var>)</dt> + <dd>Test if a poll event has occurred. The argument <var class="Fa">vp</var> + is the vnode of the file to poll. It returns any events of interest as + specified by <var class="Fa">events</var> that may have occurred for the + file. The argument <var class="Fa">events</var> is a set of flags as + specified by <a class="Xr">poll(2)</a>. + <p class="Pp">The vnode <var class="Fa">vp</var> remains unlocked throughout + the whole operation.</p> + </dd> + <dt id="VOP_KQFILTER"><a class="permalink" href="#VOP_KQFILTER"><code class="Fn">VOP_KQFILTER</code></a>(<var class="Fa">vp</var>, + <var class="Fa">kn</var>)</dt> + <dd>Register a knote <var class="Fa">kn</var> with the vnode + <var class="Fa">vn</var>. If the operation is successful zero is returned, + otherwise an appropriate error code is returned. + <p class="Pp">The vnode <var class="Fa">vp</var> remains unlocked throughout + the whole operation.</p> + </dd> + <dt id="VOP_REVOKE"><a class="permalink" href="#VOP_REVOKE"><code class="Fn">VOP_REVOKE</code></a>(<var class="Fa">vp</var>, + <var class="Fa">flags</var>)</dt> + <dd>Eliminate all activity associated with the vnode <var class="Fa">vp</var>. + The argument <var class="Fa">flags</var> is a set of flags. If REVOKEALL + is set in <var class="Fa">flags</var> all vnodes aliased to the vnode + <var class="Fa">vp</var> are also eliminated. If the operation is + successful zero is returned, otherwise an appropriate error is returned. + <p class="Pp">The vnode <var class="Fa">vp</var> remains unlocked throughout + the whole operation.</p> + </dd> + <dt id="VOP_MMAP"><a class="permalink" href="#VOP_MMAP"><code class="Fn">VOP_MMAP</code></a>(<var class="Fa">vp</var>, + <var class="Fa">prot</var>, <var class="Fa">cred</var>)</dt> + <dd>Inform file system that <var class="Fa">vp</var> is in the process of + being memory mapped. The argument <var class="Fa">prot</var> specifies the + vm access protection the vnode is going to be mapped with. The argument + <var class="Fa">cred</var> is the caller's credentials. If the file system + allows the memory mapping, zero is returned, otherwise an appropriate + error code is returned. + <p class="Pp" id="VOP_MMAP~2">Most file systems do not supply a function for + <a class="permalink" href="#VOP_MMAP~2"><code class="Fn">VOP_MMAP</code></a>() + and use + <a class="permalink" href="#genfs_mmap"><code class="Fn" id="genfs_mmap">genfs_mmap</code></a>() + to default for success. Only file systems which do not integrate with + the page cache at all typically want to disallow memory mapping.</p> + </dd> + <dt id="VOP_FSYNC"><a class="permalink" href="#VOP_FSYNC"><code class="Fn">VOP_FSYNC</code></a>(<var class="Fa">vp</var>, + <var class="Fa">cred</var>, <var class="Fa">flags</var>, + <var class="Fa">offlo</var>, <var class="Fa">offhi</var>)</dt> + <dd>Flush pending data buffers for a file to disk. The argument + <var class="Fa">vp</var> is the locked vnode of the file for flush. The + argument <var class="Fa">cred</var> is the caller's credentials. The + argument <var class="Fa">flags</var> is a set of flags. If FSYNC_WAIT is + specified in <var class="Fa">flags</var>, the function should wait for I/O + to complete before returning. The argument <var class="Fa">offlo</var> and + <var class="Fa">offhi</var> specify the range of file to flush. If the + operation is successful zero is returned, otherwise an appropriate error + code is returned. + <p class="Pp">This function implements the <a class="Xr">sync(2)</a> and + <a class="Xr">fsync(2)</a> system calls.</p> + </dd> + <dt id="VOP_SEEK"><a class="permalink" href="#VOP_SEEK"><code class="Fn">VOP_SEEK</code></a>(<var class="Fa">vp</var>, + <var class="Fa">oldoff</var>, <var class="Fa">newoff</var>, + <var class="Fa">cred</var>)</dt> + <dd>Test if the file is seekable for the specified offset + <var class="Fa">newoff</var>. The argument <var class="Fa">vp</var> is the + locked vnode of the file to test. For most file systems this function + simply tests if <var class="Fa">newoff</var> is valid. If the specified + <var class="Fa">newoff</var> is less than zero, the function returns error + code EINVAL.</dd> + <dt id="VOP_REMOVE"><a class="permalink" href="#VOP_REMOVE"><code class="Fn">VOP_REMOVE</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vp</var>, <var class="Fa">cnp</var>)</dt> + <dd>Remove a file. The argument <var class="Fa">dvp</var> is the locked vnode + of the directory to remove the file from and <var class="Fa">vp</var> is + the locked vnode of the file to remove. The argument + <var class="Fa">cnp</var> is the pathname component about the file to + remove. If the operation is successful zero is returned, otherwise an + appropriate error code is returned. Both <var class="Fa">dvp</var> and + <var class="Fa">vp</var> are locked on entry and are to be unlocked before + returning.</dd> + <dt id="VOP_LINK"><a class="permalink" href="#VOP_LINK"><code class="Fn">VOP_LINK</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vp</var>, <var class="Fa">cnp</var>)</dt> + <dd>Link to a file. The argument <var class="Fa">dvp</var> is the locked node + of the directory to create the new link and <var class="Fa">vp</var> is + the vnode of the file to be linked. The argument <var class="Fa">cnp</var> + is the pathname component of the new link. If the operation is successful + zero is returned, otherwise an error code is returned. The directory vnode + <var class="Fa">dvp</var> should be locked on entry and will be released + and unlocked on return. The vnode <var class="Fa">vp</var> should not be + locked on entry and will remain unlocked on return.</dd> + <dt><code class="Fn">VOP_RENAME</code>(<var class="Fa">fdvp</var>, + <var class="Fa">fvp</var>, <var class="Fa">fcnp</var>, + <var class="Fa">tdvp</var>, <var class="Fa">tvp</var>, + <var class="Fa">tcnp</var>)</dt> + <dd>Rename a file. The argument <var class="Fa">fdvp</var> is the vnode of the + old parent directory containing in the file to be renamed and + <var class="Fa">fvp</var> is the vnode of the file to be renamed. The + argument <var class="Fa">fcnp</var> is the pathname component about the + file to be renamed. The argument <var class="Fa">tdvp</var> is the vnode + of the new directory of the target file and <var class="Fa">tvp</var> is + the vnode of the target file (if it exists). The argument + <var class="Fa">tcnp</var> is the pathname component about the file's new + name. If the operation is successful zero is returned, otherwise an error + code is returned. + <p class="Pp" id="VOP_RENAME">The caller must hold the target file system's + rename lock. The source directory and file vnodes should be unlocked and + their reference counts should be incremented before entry. The target + directory and file vnodes should both be locked on entry. + <a class="permalink" href="#VOP_RENAME"><code class="Fn">VOP_RENAME</code></a>() + updates the reference counts prior to returning.</p> + <p class="Pp" id="VOP_RENAME~2">Because of the complexity and nastiness of + the interface, please do not write new code that calls + <a class="permalink" href="#VOP_RENAME~2"><code class="Fn">VOP_RENAME</code></a>() + directly until such time as ongoing cleanup work reaches a point where + the interface has been rendered halfway sane.</p> + </dd> + <dt id="VOP_MKDIR"><a class="permalink" href="#VOP_MKDIR"><code class="Fn">VOP_MKDIR</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vpp</var>, <var class="Fa">cnp</var>, + <var class="Fa">vap</var>)</dt> + <dd>Make a new directory in a given directory. The argument + <var class="Fa">dvp</var> is the locked vnode of the directory to create + the new directory in and <var class="Fa">cnp</var> is the pathname + component of the new directory. The argument <var class="Fa">vap</var> + specifies the attributes that the new directory should be created with. If + the file is successfully created, the address of the resulting unlocked + vnode is returned in <var class="Fa">vpp</var> and zero is returned. + <p class="Pp" id="VOP_LOOKUP~6">This function is called after + <a class="permalink" href="#VOP_LOOKUP~6"><code class="Fn">VOP_LOOKUP</code></a>() + when a directory is being created. Normally, + <code class="Fn">VOP_LOOKUP</code>() will have set the SAVENAME flag in + <i class="Em">cnp->cn_flags</i> to keep the memory pointed to by + <i class="Em">cnp->cn_pnbuf</i> valid. If an error is detected when + creating the directory, this memory is released. If the directory is + created successfully it will be released unless the SAVESTART flags in + specified in <i class="Em">cnp->cn_flags</i>.</p> + </dd> + <dt id="VOP_RMDIR"><a class="permalink" href="#VOP_RMDIR"><code class="Fn">VOP_RMDIR</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vp</var>, <var class="Fa">cnp</var>)</dt> + <dd>Remove a directory in a given directory. The argument + <var class="Fa">dvp</var> is the locked vnode of the directory to remove + the directory from and <var class="Fa">vp</var> is the locked vnode of the + directory to remove. The argument <var class="Fa">cnp</var> is the + pathname component of the directory. Zero is returned on success, + otherwise an error code is returned. Both <var class="Fa">dvp</var> and + <var class="Fa">vp</var> should be locked on entry and will be released + and unlocked on return.</dd> + <dt id="VOP_SYMLINK"><a class="permalink" href="#VOP_SYMLINK"><code class="Fn">VOP_SYMLINK</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">vpp</var>, <var class="Fa">cnp</var>, + <var class="Fa">vap</var>, <var class="Fa">target</var>)</dt> + <dd>Create a symbolic link in a given directory. The argument + <var class="Fa">dvp</var> is the locked vnode of the directory to create + the symbolic link in and <var class="Fa">cnp</var> is the pathname + component of the symbolic link. The argument <var class="Fa">vap</var> + specifies the attributes that the symbolic link should be created with and + <var class="Fa">target</var> specifies the pathname of the target of the + symbolic link. If the symbolic link is successfully created, the address + of the resulting unlocked vnode is returned in <var class="Fa">vpp</var> + and zero is returned. + <p class="Pp" id="VOP_LOOKUP~7">This function is called after + <a class="permalink" href="#VOP_LOOKUP~7"><code class="Fn">VOP_LOOKUP</code></a>() + when a symbolic link is being created. Normally, + <code class="Fn">VOP_LOOKUP</code>() will have set the SAVENAME flag in + <i class="Em">cnp->cn_flags</i> to keep the memory pointed to by + <i class="Em">cnp->cn_pnbuf</i> valid. If an error is detected when + creating the symbolic link, this memory is released. If the symbolic + link is created successfully it will be released unless the SAVESTART + flags in specified in <i class="Em">cnp->cn_flags</i>.</p> + </dd> + <dt><code class="Fn">VOP_READDIR</code>(<var class="Fa">vp</var>, + <var class="Fa">uio</var>, <var class="Fa">cred</var>, + <var class="Fa">eofflag</var>, <var class="Fa">cookies</var>, + <var class="Fa">ncookies</var>)</dt> + <dd>Read directory entry. The argument <var class="Fa">vp</var> is the vnode + of the directory to read the contents of and <var class="Fa">uio</var> is + the destination location to read the contents into. The argument + <var class="Fa">cred</var> is the caller's credentials. The argument + <var class="Fa">eofflag</var> is the pointer to a flag which is set by + <code class="Fn">VOP_READDIR</code>() to indicate an end-of-file + condition. If <var class="Fa">eofflag</var> is + <code class="Dv">NULL</code>, the end-of-file condition is not returned. + The arguments <var class="Fa">cookies</var> and + <var class="Fa">ncookies</var> specify the addresses for the list and + number of directory seek cookies generated for NFS. Both + <var class="Fa">cookies</var> and <var class="Fa">ncookies</var> should be + <code class="Dv">NULL</code> if they aren't required to be returned by + <code class="Fn">VOP_READDIR</code>(). The directory contents are read + into struct dirent structures and <var class="Fa">uio->uio_offset</var> + is set to the offset of the next unread directory entry. This offset may + be used in a following invocation to continue a sequential read of the + directory contents. If the operation is successful zero is returned, + otherwise an appropriate error code is returned. + <p class="Pp">The directory should be locked on entry and will remain locked + on return.</p> + <p class="Pp">In case <var class="Fa">ncookies</var> and + <var class="Fa">cookies</var> are supplied, one cookie should be + returned per directory entry. The value of the cookie for each directory + entry should be the offset within the directory where the on-disk + version of the following directory entry starts. That is, for each + directory entry <var class="Fa">i</var>, the corresponding cookie should + refer to the offset of directory entry <var class="Fa">i + 1</var>.</p> + <p class="Pp" id="VOP_READDIR">Note that the <var class="Fa">cookies</var> + array must be allocated by the callee using the M_TEMP malloc type as + callers of + <a class="permalink" href="#VOP_READDIR"><code class="Fn">VOP_READDIR</code></a>() + must be able to free the allocation.</p> + </dd> + <dt id="VOP_READLINK"><a class="permalink" href="#VOP_READLINK"><code class="Fn">VOP_READLINK</code></a>(<var class="Fa">vp</var>, + <var class="Fa">uio</var>, <var class="Fa">cred</var>)</dt> + <dd>Read the contents of a symbolic link. The argument + <var class="Fa">vp</var> is the locked vnode of the symlink and + <var class="Fa">uio</var> is the destination location to read the contents + into. The argument <var class="Fa">cred</var> is the credentials of the + caller. If the operation is successful zero is returned, otherwise an + error code is returned. + <p class="Pp">The vnode should be locked on entry and will remain locked on + return.</p> + </dd> + <dt id="VOP_ABORTOP"><a class="permalink" href="#VOP_ABORTOP"><code class="Fn">VOP_ABORTOP</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">cnp</var>)</dt> + <dd>Abort pending operation on vnode <var class="Fa">dvp</var> and free + resources allocated in <var class="Fa">cnp</var>. + <p class="Pp" id="genfs_abortop">This operation is rarely implemented in + file systems and + <a class="permalink" href="#genfs_abortop"><code class="Fn">genfs_abortop</code></a>() + is typically used instead.</p> + </dd> + <dt id="VOP_INACTIVE"><a class="permalink" href="#VOP_INACTIVE"><code class="Fn">VOP_INACTIVE</code></a>(<var class="Fa">vp</var>)</dt> + <dd>Release the inactive vnode. <code class="Fn">VOP_INACTIVE</code>() is + called when the kernel is no longer using the vnode. This may be because + the reference count reaches zero or it may be that the file system is + being forcibly unmounted while there are open files. It can be used to + reclaim space for open but deleted files. The argument + <var class="Fa">vp</var> is the locked vnode to be released. If the + operation is successful zero is returned, otherwise an appropriate error + code is returned. The vnode <var class="Fa">vp</var> must be locked on + entry, and will remain locked on return.</dd> + <dt id="VOP_RECLAIM"><a class="permalink" href="#VOP_RECLAIM"><code class="Fn">VOP_RECLAIM</code></a>(<var class="Fa">vp</var>)</dt> + <dd>Reclaim the vnode for another file system. + <code class="Fn">VOP_RECLAIM</code>() is called when a vnode is being + reused for a different file system. Any file system specific resources + associated with the vnode should be freed. The argument + <var class="Fa">vp</var> is the vnode to be reclaimed. If the operation is + successful zero is returned, otherwise an appropriate error code is + returned. The vnode <var class="Fa">vp</var> should be locked on entry, + and will be returned unlocked.</dd> + <dt id="VOP_LOCK"><a class="permalink" href="#VOP_LOCK"><code class="Fn">VOP_LOCK</code></a>(<var class="Fa">vp</var>, + <var class="Fa">flags</var>)</dt> + <dd>Sleep until vnode lock is free. The argument <var class="Fa">vp</var> is + the vnode of the file to be locked. The argument + <var class="Fa">flags</var> is <code class="Dv">LK_EXCLUSIVE</code> to + take the lock exclusively or <code class="Dv">LK_SHARED</code> to take a + shared lock. If <var class="Fa">flags</var> contains + <code class="Dv">LK_NOWAIT</code> and the lock is busy, the operation will + return immediately with an error code. If <var class="Fa">flags</var> + contains <code class="Dv">LK_RETRY</code> this is a hint the caller wants + the lock on dead vnodes too. If the operation is successful zero is + returned, otherwise an appropriate error code is returned. + <code class="Fn">VOP_LOCK</code>() is used to serialize access to the file + system such as to prevent two writes to the same file from happening at + the same time. Kernel code should use <a class="Xr">vn_lock(9)</a> to lock + a vnode rather than calling <code class="Fn">VOP_LOCK</code>() + directly.</dd> + <dt id="VOP_UNLOCK"><a class="permalink" href="#VOP_UNLOCK"><code class="Fn">VOP_UNLOCK</code></a>(<var class="Fa">vp</var>)</dt> + <dd>Wake up process sleeping on lock. The argument <var class="Fa">vp</var> is + the vnode of the file to be unlocked. If the operation is successful zero + is returned, otherwise an appropriate error code is returned. + <code class="Fn">VOP_UNLOCK</code>() is used to serialize access to the + file system such as to prevent two writes to the same file from happening + at the same time.</dd> + <dt id="VOP_ISLOCKED"><a class="permalink" href="#VOP_ISLOCKED"><code class="Fn">VOP_ISLOCKED</code></a>(<var class="Fa">vp</var>)</dt> + <dd>Test if the vnode <var class="Fa">vp</var> is locked. Possible return + values are <code class="Dv">LK_EXCLUSIVE</code>, + <code class="Dv">LK_SHARED</code> or 0 for lock held exclusively by the + calling thread, shared lock held by anyone or unlocked, respectively. + <p class="Pp">This function must never be used to make locking decisions at + run time: it is provided only for diagnostic purposes.</p> + </dd> + <dt id="VOP_BMAP"><a class="permalink" href="#VOP_BMAP"><code class="Fn">VOP_BMAP</code></a>(<var class="Fa">vp</var>, + <var class="Fa">bn</var>, <var class="Fa">vpp</var>, + <var class="Fa">bnp</var>, <var class="Fa">runp</var>)</dt> + <dd>Convert the logical block number <var class="Fa">bn</var> of a file + specified by vnode <var class="Fa">vp</var> to its physical block number + on the disk. The physical block is returned in <var class="Fa">bnp</var>. + In case the logical block is not allocated, -1 is used. + <p class="Pp">If <var class="Fa">vpp</var> is not + <code class="Dv">NULL</code>, the vnode of the device vnode for the file + system is returned in the address specified by + <var class="Fa">vpp</var>. If <var class="Fa">runp</var> is not + <code class="Dv">NULL</code>, the number of contiguous blocks starting + from the next block after the queried block will be returned in + <var class="Fa">runp</var>.</p> + </dd> + <dt id="VOP_PRINT"><a class="permalink" href="#VOP_PRINT"><code class="Fn">VOP_PRINT</code></a>(<var class="Fa">vp</var>)</dt> + <dd>Print debugging information. The argument <var class="Fa">vp</var> is the + vnode to print. If the operation is successful zero is returned, otherwise + an appropriate error code is returned.</dd> + <dt id="VOP_PATHCONF"><a class="permalink" href="#VOP_PATHCONF"><code class="Fn">VOP_PATHCONF</code></a>(<var class="Fa">vp</var>, + <var class="Fa">name</var>, <var class="Fa">retval</var>)</dt> + <dd>Implement POSIX <a class="Xr">pathconf(2)</a> and + <a class="Xr">fpathconf(2)</a> support. The argument + <var class="Fa">vp</var> is the locked vnode to get information about. The + argument <var class="Fa">name</var> specified the type of information to + return. The information is returned in the address specified by + <var class="Fa">retval</var>. Valid values for <var class="Fa">name</var> + are: + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt>_PC_LINK_MAX</dt> + <dd>return the maximum number of links to a file</dd> + <dt>_PC_NAME_MAX</dt> + <dd>return the maximum number of bytes in a file name</dd> + <dt>_PC_PATH_MAX</dt> + <dd>return the maximum number of bytes in a pathname</dd> + <dt>_PC_PIPE_BUF</dt> + <dd>return the maximum number of bytes which will be written atomically to + a pipe</dd> + <dt>_PC_CHOWN_RESTRICTED</dt> + <dd>return 1 if appropriate privileges are required for the + <a class="Xr">chown(2)</a> system call, otherwise zero</dd> + <dt>_PC_NO_TRUNC</dt> + <dd>return 0 if file names longer than {<code class="Dv">NAME_MAX</code>} + are silently truncated</dd> + </dl> + </div> + <p class="Pp">If <var class="Fa">name</var> is recognized, + <var class="Fa">*retval</var> is set to the specified value and zero is + returned, otherwise an appropriate error is returned.</p> + </dd> + <dt id="VOP_ADVLOCK"><a class="permalink" href="#VOP_ADVLOCK"><code class="Fn">VOP_ADVLOCK</code></a>(<var class="Fa">vp</var>, + <var class="Fa">id</var>, <var class="Fa">op</var>, + <var class="Fa">fl</var>, <var class="Fa">flags</var>)</dt> + <dd>Manipulate Advisory record locks on a vnode. The argument + <var class="Fa">vp</var> is the vnode on which locks are manipulated. The + argument <var class="Fa">id</var> is the id token which is changing the + lock and <var class="Fa">op</var> is the <a class="Xr">fcntl(2)</a> + operation to perform. Valid values are: + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt>F_SETLK</dt> + <dd>set lock</dd> + <dt>F_GETLK</dt> + <dd>get the first conflicted lock</dd> + <dt>F_UNLCK</dt> + <dd>clear lock</dd> + </dl> + </div> + <p class="Pp" id="VOP_ADVLOCK~2">The argument <var class="Fa">fl</var> is a + description of the lock. In the case of + <code class="Dv">SEEK_CUR</code>, The caller should add the current file + offset to fl->l_start beforehand. + <a class="permalink" href="#VOP_ADVLOCK~2"><code class="Fn">VOP_ADVLOCK</code></a>() + treats <code class="Dv">SEEK_CUR</code> as + <code class="Dv">SEEK_SET</code>.</p> + <p class="Pp">The argument <var class="Fa">flags</var> is the set of flags. + Valid values are:</p> + <p class="Pp"></p> + <div class="Bd-indent"> + <dl class="Bl-tag Bl-compact"> + <dt>F_WAIT</dt> + <dd>wait until lock is granted</dd> + <dt>F_FLOCK</dt> + <dd>use <a class="Xr">flock(2)</a> semantics for lock</dd> + <dt>F_POSIX</dt> + <dd>use POSIX semantics for lock</dd> + </dl> + </div> + <p class="Pp">If the operation is successful zero is returned, otherwise an + appropriate error is returned.</p> + </dd> + <dt id="VOP_WHITEOUT"><a class="permalink" href="#VOP_WHITEOUT"><code class="Fn">VOP_WHITEOUT</code></a>(<var class="Fa">dvp</var>, + <var class="Fa">cnp</var>, <var class="Fa">flags</var>)</dt> + <dd>Whiteout pathname component in directory with vnode + <var class="Fa">dvp</var>. The argument <var class="Fa">cnp</var> + specifies the pathname component to whiteout. + <p class="Pp">The vnode <var class="Fa">dvp</var> should be locked on entry + and will remain locked on return.</p> + </dd> + <dt id="VOP_GETPAGES"><a class="permalink" href="#VOP_GETPAGES"><code class="Fn">VOP_GETPAGES</code></a>(<var class="Fa">vp</var>, + <var class="Fa">offset</var>, <var class="Fa">m</var>, + <var class="Fa">count</var>, <var class="Fa">centeridx</var>, + <var class="Fa">access_type</var>, <var class="Fa">advice</var>, + <var class="Fa">flags</var>)</dt> + <dd>Read VM pages from file. The argument <var class="Fa">vp</var> is the + locked vnode to read the VM pages from. The argument + <var class="Fa">offset</var> is offset in the file to start accessing and + <var class="Fa">m</var> is an array of VM pages. The argument + <var class="Fa">count</var> points a variable that specifies the number of + pages to read. If the operation is successful zero is returned, otherwise + an appropriate error code is returned. If PGO_LOCKED is specified in + <a class="permalink" href="#flags"><i class="Em" id="flags">flags</i></a>, + <code class="Fn">VOP_GETPAGES</code>() might return less pages than + requested. In that case, the variable pointed to by + <a class="permalink" href="#count"><i class="Em" id="count">count</i></a> + will be updated. + <p class="Pp">This function is primarily used by the page-fault handing + mechanism.</p> + </dd> + <dt id="VOP_PUTPAGES"><a class="permalink" href="#VOP_PUTPAGES"><code class="Fn">VOP_PUTPAGES</code></a>(<var class="Fa">vp</var>, + <var class="Fa">offlo</var>, <var class="Fa">offhi</var>, + <var class="Fa">flags</var>)</dt> + <dd>Write modified (dirty) VM pages to file. The argument + <var class="Fa">vp</var> is the vnode to write the VM pages to. The + vnode's vm object lock (<var class="Va">v_uobj.vmobjlock</var>) must be + held by the caller and will be released upon return. The arguments + <var class="Fa">offlo</var> and <var class="Fa">offhi</var> specify the + range of VM pages to write. In case <var class="Fa">offhi</var> is given + as 0, all pages at and after the start offset <var class="Fa">offlo</var> + belonging the vnode <var class="Fa">vp</var> will be written. The argument + <var class="Fa">flags</var> controls the behavior of the routine and takes + the vm pager's flags (<code class="Dv">PGO_ -prefixed</code>). If the + operation is successful zero is returned, otherwise an appropriate error + code is returned. + <p class="Pp" id="genfs_putpages">The function is primarily used by the + pageout handling mechanism and is commonly implemented indirectly by + <a class="permalink" href="#genfs_putpages"><code class="Fn">genfs_putpages</code></a>() + with the help of + <a class="permalink" href="#VOP_STRATEGY"><code class="Fn" id="VOP_STRATEGY">VOP_STRATEGY</code></a>() + and <code class="Fn">VOP_BMAP</code>().</p> + </dd> + <dt id="bp-_b_flags"><code class="Fn">VOP_STRATEGY</code>(<var class="Fa">vp</var>, + <var class="Fa">bp</var>)</dt> + <dd>Read/write a file system buffer. The argument <var class="Fa">vp</var> is + the vnode to read/write to. The argument <var class="Fa">bp</var> is the + buffer to be read or written. <code class="Fn">VOP_STRATEGY</code>() will + either read or write data to the file depending on the value of + <a class="permalink" href="#bp-_b_flags"><i class="Em">bp->b_flags</i></a>. + If the operation is successful zero is returned, otherwise an appropriate + error code is returned.</dd> + <dt id="VOP_BWRITE"><a class="permalink" href="#VOP_BWRITE"><code class="Fn">VOP_BWRITE</code></a>(<var class="Fa">vp</var>, + <var class="Fa">bp</var>)</dt> + <dd>Write a file system buffer. The argument <var class="Fa">vp</var> is the + vnode to write to. The argument <var class="Fa">bp</var> specifies the + buffer to be written. If the operation is successful zero is returned, + otherwise an appropriate error code is returned.</dd> + <dt id="VOP_GETEXTATTR"><a class="permalink" href="#VOP_GETEXTATTR"><code class="Fn">VOP_GETEXTATTR</code></a>(<var class="Fa">vp</var>, + <var class="Fa">attrnamespace</var>, <var class="Fa">name</var>, + <var class="Fa">uio</var>, <var class="Fa">size</var>, + <var class="Fa">cred</var>)</dt> + <dd>Get an extended attribute. The argument <var class="Fa">vp</var> is the + locked vnode of the file or directory from which to retrieve the + attribute. The argument <var class="Fa">attrnamespace</var> specifies the + extended attribute namespace. The argument <var class="Fa">name</var> is a + nul-terminated character string naming the attribute to retrieve. The + argument <var class="Fa">uio</var>, if not <code class="Dv">NULL</code>, + specifies where the extended attribute value is to be written. The + argument <var class="Fa">size</var>, if not <code class="Dv">NULL</code>, + will contain the number of bytes required to read all of the attribute + data upon return. In most cases, <var class="Fa">uio</var> will be + <code class="Dv">NULL</code> when <var class="Fa">size</var> is not, and + vice versa. The argument <var class="Fa">cred</var> specifies the user + credentials to use when authorizing the request.</dd> + <dt id="VOP_SETEXTATTR"><a class="permalink" href="#VOP_SETEXTATTR"><code class="Fn">VOP_SETEXTATTR</code></a>(<var class="Fa">vp</var>, + <var class="Fa">attrnamespace</var>, <var class="Fa">name</var>, + <var class="Fa">uio</var>, <var class="Fa">cred</var>)</dt> + <dd>Set an extended attribute. The argument <var class="Fa">vp</var> is the + locked vnode of the file or directory to which to store the attribute. The + argument <var class="Fa">namespace</var> specifies the extended attribute + namespace. The argument <var class="Fa">name</var> is a nul-terminated + character string naming the attribute to store. The argument + <var class="Fa">uio</var> specifies the source of the extended attribute + data. The argument <var class="Fa">cred</var> specifies the user + credentials to use when authorizing the request.</dd> + <dt id="VOP_LISTEXTATTR"><a class="permalink" href="#VOP_LISTEXTATTR"><code class="Fn">VOP_LISTEXTATTR</code></a>(<var class="Fa">vp</var>, + <var class="Fa">attrnamespace</var>, <var class="Fa">uio</var>, + <var class="Fa">size</var>, <var class="Fa">cred</var>)</dt> + <dd>Retrieve the list of extended attributes. The argument + <var class="Fa">vp</var> is the locked vnode of the file or directory + whose attributes are to be listed. The argument + <var class="Fa">attrnamespace</var> specifies the extended attribute + namespace. The argument <var class="Fa">uio</var>, if not + <code class="Dv">NULL</code>, specifies where the extended attribute list + is to be written. The argument <var class="Fa">size</var>, if not + <code class="Dv">NULL</code>, will contain the number of bytes required to + read all of the attribute names upon return. In most cases, + <var class="Fa">uio</var> will be <code class="Dv">NULL</code> when + <var class="Fa">size</var> is not, and vice versa. The argument + <var class="Fa">cred</var> specifies the user credentials to use when + authorizing the request.</dd> + <dt id="VOP_DELETEEXTATTR"><a class="permalink" href="#VOP_DELETEEXTATTR"><code class="Fn">VOP_DELETEEXTATTR</code></a>(<var class="Fa">vp</var>, + <var class="Fa">attrnamespace</var>, <var class="Fa">name</var>, + <var class="Fa">cred</var>)</dt> + <dd>Remove attribute <var class="Fa">name</var> from file associated with + <var class="Fa">vp</var>. The argument <var class="Fa">attrnamespace</var> + specifies the extended attribute namespace. If full removal is not + supported, the file system should return + <code class="Er">EOPNOTSUPP</code> to allow the caller to zero out the + value with <code class="Fn">VOP_SETEXTATTR</code>(). + <p class="Pp">The vnode <var class="Fa">vp</var> should be locked on entry + and will remain locked on return.</p> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1> +<p class="Pp"><span class="Pa">src/sys/kern/vnode_if.src</span> contains the + list of vnode functions, their definitions and an exact locking + protocol.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1> +<dl class="Bl-tag"> + <dt id="EACCES">[<a class="permalink" href="#EACCES"><code class="Er">EACCES</code></a>]</dt> + <dd>Access for the specified operation is denied.</dd> + <dt id="EDQUOT">[<a class="permalink" href="#EDQUOT"><code class="Er">EDQUOT</code></a>]</dt> + <dd>Quota exceeded.</dd> + <dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt> + <dd>attempt to read from an illegal offset in the directory; unrecognized + input</dd> + <dt id="EIO">[<a class="permalink" href="#EIO"><code class="Er">EIO</code></a>]</dt> + <dd>a read error occurred while reading the directory or reading the contents + of a symbolic link</dd> + <dt id="EJUSTRETURN">[<a class="permalink" href="#EJUSTRETURN"><code class="Er">EJUSTRETURN</code></a>]</dt> + <dd>A CREATE or RENAME operation would be successful.</dd> + <dt id="ENOATTR">[<a class="permalink" href="#ENOATTR"><code class="Er">ENOATTR</code></a>]</dt> + <dd>The requested attribute is not defined for this vnode.</dd> + <dt id="ENOENT">[<a class="permalink" href="#ENOENT"><code class="Er">ENOENT</code></a>]</dt> + <dd>The component was not found in the directory.</dd> + <dt id="ENOSPC">[<a class="permalink" href="#ENOSPC"><code class="Er">ENOSPC</code></a>]</dt> + <dd>The file system is full.</dd> + <dt id="ENOTDIR">[<a class="permalink" href="#ENOTDIR"><code class="Er">ENOTDIR</code></a>]</dt> + <dd>The vnode does not represent a directory.</dd> + <dt id="ENOTEMPTY">[<a class="permalink" href="#ENOTEMPTY"><code class="Er">ENOTEMPTY</code></a>]</dt> + <dd>attempt to remove a directory which is not empty</dd> + <dt id="EPERM">[<a class="permalink" href="#EPERM"><code class="Er">EPERM</code></a>]</dt> + <dd>an attempt was made to change an immutable file</dd> + <dt id="EROFS">[<a class="permalink" href="#EROFS"><code class="Er">EROFS</code></a>]</dt> + <dd>the file system is read-only</dd> +</dl> +</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">extattr(9)</a>, <a class="Xr">intro(9)</a>, + <a class="Xr">namei(9)</a>, <a class="Xr">vattr(9)</a>, + <a class="Xr">vfs(9)</a>, <a class="Xr">vfsops(9)</a>, + <a class="Xr">vnode(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">The vnode operations vector, its functions and the corresponding + macros appeared in <span class="Ux">4.3BSD</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">June 15, 2023</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/wapbl.9 3.html b/static/netbsd/man9/wapbl.9 3.html new file mode 100644 index 00000000..241ea757 --- /dev/null +++ b/static/netbsd/man9/wapbl.9 3.html @@ -0,0 +1,424 @@ +<table class="head"> + <tr> + <td class="head-ltitle">WAPBL(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">WAPBL(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">WAPBL</code>, + <code class="Nm">wapbl_start</code>, <code class="Nm">wapbl_stop</code>, + <code class="Nm">wapbl_begin</code>, <code class="Nm">wapbl_end</code>, + <code class="Nm">wapbl_flush</code>, <code class="Nm">wapbl_discard</code>, + <code class="Nm">wapbl_add_buf</code>, + <code class="Nm">wapbl_remove_buf</code>, + <code class="Nm">wapbl_resize_buf</code>, + <code class="Nm">wapbl_register_inode</code>, + <code class="Nm">wapbl_unregister_inode</code>, + <code class="Nm">wapbl_register_deallocation</code>, + <code class="Nm">wapbl_jlock_assert</code>, + <code class="Nm">wapbl_junlock_assert</code> — + <span class="Nd">write-ahead physical block logging for file + systems</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/wapbl.h</a>></code></p> +<p class="Pp"><var class="Vt">typedef void (*wapbl_flush_fn_t)(struct mount *, + daddr_t *, int *, int)</var>;</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">wapbl_start</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl **wlp</var>, <var class="Fa" style="white-space: nowrap;">struct mount + *mp</var>, <var class="Fa" style="white-space: nowrap;">struct vnode + *devvp</var>, <var class="Fa" style="white-space: nowrap;">daddr_t + off</var>, <var class="Fa" style="white-space: nowrap;">size_t count</var>, + <var class="Fa" style="white-space: nowrap;">size_t blksize</var>, + <var class="Fa" style="white-space: nowrap;">struct wapbl_replay *wr</var>, + <var class="Fa" style="white-space: nowrap;">wapbl_flush_fn_t flushfn</var>, + <var class="Fa" style="white-space: nowrap;">wapbl_flush_fn_t + flushabortfn</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">wapbl_stop</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">int + force</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">wapbl_begin</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">const char + *file</var>, <var class="Fa" style="white-space: nowrap;">int + line</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_end</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">wapbl_flush</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">int + wait</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_discard</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_add_buf</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *bp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_remove_buf</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *bp</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_resize_buf</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">struct buf + *bp</var>, <var class="Fa" style="white-space: nowrap;">long oldsz</var>, + <var class="Fa" style="white-space: nowrap;">long oldcnt</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_register_inode</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">ino_t + ino</var>, <var class="Fa" style="white-space: nowrap;">mode_t + mode</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_unregister_inode</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">ino_t + ino</var>, <var class="Fa" style="white-space: nowrap;">mode_t + mode</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_register_deallocation</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>, <var class="Fa" style="white-space: nowrap;">daddr_t + blk</var>, <var class="Fa" style="white-space: nowrap;">int len</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_jlock_assert</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">wapbl_junlock_assert</code>(<var class="Fa" style="white-space: nowrap;">struct + wapbl *wl</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp"><code class="Nm">WAPBL</code>, or + <a class="permalink" href="#write-ahead"><i class="Em" id="write-ahead">write-ahead + physical block logging</i></a>, is an abstraction for file systems to write + physical blocks in the <a class="Xr">buffercache(9)</a> to a bounded-size + log first before their real destinations on disk. The name means:</p> +<div class="Bd-indent"> +<dl class="Bl-tag"> + <dt>logging</dt> + <dd>batches of writes are issued atomically via a log</dd> + <dt>physical block</dt> + <dd>only physical blocks, not logical file system operations, are stored in + the log</dd> + <dt>write-ahead</dt> + <dd>before writing a block to disk, its new content, rather than its old + content for roll-back, is recorded in the log</dd> +</dl> +</div> +<p class="Pp" id="transactions">When a file system using + <code class="Nm">WAPBL</code> issues writes (as in + <a class="Xr">bwrite(9)</a> or <a class="Xr">bdwrite(9)</a>), they are + grouped in batches called + <a class="permalink" href="#transactions"><i class="Em">transactions</i></a> + in memory, which are serialized to be consistent with program order before + <code class="Nm">WAPBL</code> submits them to disk atomically.</p> +<p class="Pp">Thus, within a transaction, after one write, another write need + not wait for disk I/O, and if the system is interrupted, e.g. by a crash or + by power failure, either both writes will appear on disk, or neither + will.</p> +<p class="Pp" id="log">When a transaction is full, it is written to a circular + buffer on disk called the + <a class="permalink" href="#log"><i class="Em">log</i></a>. When the + transaction has been written to disk, every write in the transaction is + submitted to disk asynchronously. Finally, the file system may issue new + writes via <code class="Nm">WAPBL</code> once enough writes submitted to + disk have completed.</p> +<p class="Pp">After interruption, such as a crash or power failure, some writes + issued by the file system may not have completed. However, the log is + written consistently with program order and before file system writes are + submitted to disk. Hence a consistent program-order view of the file system + can be attained by resubmitting the writes that were successfully stored in + the log using <a class="Xr">wapbl_replay(9)</a>. This may not be the same + state just before interruption — writes in transactions that did not + reach the disk will be excluded.</p> +<p class="Pp" id="wapbl_start">For a file system to use + <code class="Nm">WAPBL</code>, its <a class="Xr">VFS_MOUNT(9)</a> method + should first replay any journal on disk using + <a class="Xr">wapbl_replay(9)</a>, and then, if the mount is read/write, + initialize <code class="Nm">WAPBL</code> for the mount by calling + <a class="permalink" href="#wapbl_start"><code class="Fn">wapbl_start</code></a>(). + The <a class="Xr">VFS_UNMOUNT(9)</a> method should call + <a class="permalink" href="#wapbl_stop"><code class="Fn" id="wapbl_stop">wapbl_stop</code></a>().</p> +<p class="Pp" id="wapbl_begin">Before issuing any + <a class="Xr">buffercache(9)</a> writes, the file system must acquire a + shared lock on the current <code class="Nm">WAPBL</code> transaction with + <a class="permalink" href="#wapbl_begin"><code class="Fn">wapbl_begin</code></a>(), + which may sleep until there is room in the transaction for new writes. After + issuing the writes, the file system must release its shared lock on the + transaction with <code class="Fn">wapbl_end</code>(). Either all writes + issued between <code class="Fn">wapbl_begin</code>() and + <code class="Fn">wapbl_end</code>() will complete, or none of them will.</p> +<p class="Pp" id="exclusive">File systems may also witness an + <a class="permalink" href="#exclusive"><i class="Em">exclusive</i></a> lock + on the current transaction when <code class="Nm">WAPBL</code> is flushing + the transaction to disk, or aborting a flush, and invokes a file system's + callback. File systems can assert that the transaction is locked with + <a class="permalink" href="#wapbl_jlock_assert"><code class="Fn" id="wapbl_jlock_assert">wapbl_jlock_assert</code></a>(), + or not + <a class="permalink" href="#exclusively"><i class="Em" id="exclusively">exclusively</i></a> + locked, with <code class="Fn">wapbl_junlock_assert</code>().</p> +<p class="Pp" id="wapbl_register_inode">If a file system requires multiple + transactions to initialize an inode, and needs to destroy partially + initialized inodes during replay, it can register them by + <var class="Vt">ino_t</var> inode number before initialization with + <a class="permalink" href="#wapbl_register_inode"><code class="Fn">wapbl_register_inode</code></a>() + and unregister them with + <a class="permalink" href="#wapbl_unregister_inode"><code class="Fn" id="wapbl_unregister_inode">wapbl_unregister_inode</code></a>() + once initialization is complete. <code class="Nm">WAPBL</code> does not + actually concern itself whether the objects identified by + <var class="Vt">ino_t</var> values are ‘inodes’ or + ‘quaggas’ or anything else — file systems may use this + to list any objects keyed by <var class="Vt">ino_t</var> value in the + log.</p> +<p class="Pp">When a file system frees resources on disk and issues writes to + reflect the fact, it cannot then reuse the resources until the writes have + reached the disk. However, as far as the <a class="Xr">buffercache(9)</a> is + concerned, as soon as the file system issues the writes, they will appear to + have been written. So the file system must not attempt to reuse the resource + until the current <code class="Nm">WAPBL</code> transaction has been flushed + to disk.</p> +<p class="Pp" id="wapbl_register_deallocation">The file system can defer freeing + a resource by calling + <a class="permalink" href="#wapbl_register_deallocation"><code class="Fn">wapbl_register_deallocation</code></a>() + to record the disk address of the resource and length in bytes of the + resource. Then, when <code class="Nm">WAPBL</code> next flushes the + transaction to disk, it will pass an array of the disk addresses and lengths + in bytes to a file-system-supplied callback. (Again, + <code class="Nm">WAPBL</code> does not care whether the ‘disk + address’ or ‘length in bytes’ is actually that; it will + pass along <var class="Vt">daddr_t</var> and <var class="Vt">int</var> + values.)</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">wapbl_start</code>(<var class="Fa">wlp</var>, + <var class="Fa">mp</var>, <var class="Fa">devvp</var>, + <var class="Fa">off</var>, <var class="Fa">count</var>, + <var class="Fa">blksize</var>, <var class="Fa">wr</var>, + <var class="Fa">flushfn</var>, <var class="Fa">flushabortfn</var>)</dt> + <dd>Start using <code class="Nm">WAPBL</code> for the file system mounted at + <var class="Fa">mp</var>, storing a log of <var class="Fa">count</var> + disk sectors at disk address <var class="Fa">off</var> on the block device + <var class="Fa">devvp</var> writing blocks in units of + <var class="Fa">blksize</var> bytes. On success, stores an opaque + <var class="Vt">struct wapbl *</var> cookie in + <code class="Li">*</code><var class="Fa">wlp</var> for use with the other + <code class="Nm">WAPBL</code> routines and returns zero. On failure, + returns an error number. + <p class="Pp" id="wapbl_start~2">If the file system had replayed the log + with <a class="Xr">wapbl_replay(9)</a>, then <var class="Fa">wr</var> + must be the <var class="Vt">struct wapbl_replay *</var> cookie used to + replay it, and + <a class="permalink" href="#wapbl_start~2"><code class="Fn">wapbl_start</code></a>() + will register any inodes that were in the log as if with + <code class="Fn">wapbl_register_inode</code>(); otherwise + <var class="Fa">wr</var> must be <code class="Dv">NULL</code>.</p> + <p class="Pp" id="wapbl_start~3"><var class="Fa">flushfn</var> is a callback + that <code class="Nm">WAPBL</code> will invoke as + <var class="Fa">flushfn</var> (<var class="Fa">mp</var>, + <var class="Fa">deallocblks</var>, <var class="Fa">dealloclens</var>, + <var class="Fa">dealloccnt</var>) just before it flushes a transaction + to disk, with the an exclusive lock held on the transaction, where + <var class="Fa">mp</var> is the mount point passed to + <a class="permalink" href="#wapbl_start~3"><code class="Fn">wapbl_start</code></a>(), + <var class="Fa">deallocblks</var> is an array of + <var class="Fa">dealloccnt</var> disk addresses, and + <var class="Fa">dealloclens</var> is an array of + <var class="Fa">dealloccnt</var> lengths, corresponding to the addresses + and lengths the file system passed to + <code class="Fn">wapbl_register_deallocation</code>(). If flushing the + transaction to disk fails, <code class="Nm">WAPBL</code> will call + <var class="Fa">flushabortfn</var> with the same arguments to undo any + effects that <var class="Fa">flushfn</var> had.</p> + </dd> + <dt><code class="Fn">wapbl_stop</code>(<var class="Fa">wl</var>, + <var class="Fa">force</var>)</dt> + <dd>Flush the current transaction to disk and stop using + <code class="Nm">WAPBL</code>. If flushing the transaction fails and + <var class="Fa">force</var> is zero, return error. If flushing the + transaction fails and <var class="Fa">force</var> is nonzero, discard the + transaction, permanently losing any writes in it. If flushing the + transaction is successful or if <var class="Fa">force</var> is nonzero, + free memory associated with <var class="Fa">wl</var> and return zero.</dd> + <dt><code class="Fn">wapbl_begin</code>(<var class="Fa">wl</var>, + <var class="Fa">file</var>, <var class="Fa">line</var>)</dt> + <dd>Wait for space in the current transaction for new writes, flushing it if + necessary, and acquire a shared lock on it. + <p class="Pp">The lock is not exclusive: other threads may acquire shared + locks on the transaction too. The lock is not recursive: a thread may + not acquire it again without calling <var class="Fa">wapbl_end</var> + first.</p> + <p class="Pp">May sleep.</p> + <p class="Pp"><var class="Fa">file</var> and <var class="Fa">line</var> are + the file name and line number of the caller for debugging purposes.</p> + </dd> + <dt id="wapbl_end"><a class="permalink" href="#wapbl_end"><code class="Fn">wapbl_end</code></a>(<var class="Fa">wl</var>)</dt> + <dd>Release a shared lock on the transaction acquired with + <code class="Fn">wapbl_begin</code>().</dd> + <dt id="wapbl_flush"><a class="permalink" href="#wapbl_flush"><code class="Fn">wapbl_flush</code></a>(<var class="Fa">wl</var>, + <var class="Fa">wait</var>)</dt> + <dd>Flush the current transaction to disk. If <var class="Fa">wait</var> is + nonzero, wait for all writes in the current transaction to complete. + <p class="Pp">The current transaction must not be locked.</p> + </dd> + <dt id="wapbl_discard"><a class="permalink" href="#wapbl_discard"><code class="Fn">wapbl_discard</code></a>(<var class="Fa">wl</var>)</dt> + <dd>Discard the current transaction, permanently losing any writes in it. + <p class="Pp">The current transaction must not be locked.</p> + </dd> + <dt id="wapbl_add_buf"><a class="permalink" href="#wapbl_add_buf"><code class="Fn">wapbl_add_buf</code></a>(<var class="Fa">wl</var>, + <var class="Fa">bp</var>)</dt> + <dd>Add the buffer <var class="Fa">bp</var> to the current transaction, which + must be locked, because someone has asked to write it. + <p class="Pp">This is meant to be called from within + <a class="Xr">buffercache(9)</a>, not by file systems directly.</p> + </dd> + <dt id="wapbl_remove_buf"><a class="permalink" href="#wapbl_remove_buf"><code class="Fn">wapbl_remove_buf</code></a>(<var class="Fa">wl</var>, + <var class="Fa">bp</var>)</dt> + <dd>Remove the buffer <var class="Fa">bp</var>, which must have been added + using <var class="Fa">wapbl_add_buf</var>, from the current transaction, + which must be locked, because it has been invalidated (or XXX ???). + <p class="Pp">This is meant to be called from within + <a class="Xr">buffercache(9)</a>, not by file systems directly.</p> + </dd> + <dt id="wapbl_resize_buf"><a class="permalink" href="#wapbl_resize_buf"><code class="Fn">wapbl_resize_buf</code></a>(<var class="Fa">wl</var>, + <var class="Fa">bp</var>, <var class="Fa">oldsz</var>, + <var class="Fa">oldcnt</var>)</dt> + <dd>Note that the buffer <var class="Fa">bp</var>, which must have been added + using <var class="Fa">wapbl_add_buf</var>, has changed size, where + <var class="Fa">oldsz</var> is the previous allocated size in bytes and + <var class="Fa">oldcnt</var> is the previous number of valid bytes in + <var class="Fa">bp</var>. + <p class="Pp">This is meant to be called from within + <a class="Xr">buffercache(9)</a>, not by file systems directly.</p> + </dd> + <dt id="wapbl_register_inode~2"><a class="permalink" href="#wapbl_register_inode~2"><code class="Fn">wapbl_register_inode</code></a>(<var class="Fa">wl</var>, + <var class="Fa">ino</var>, <var class="Fa">mode</var>)</dt> + <dd>Register <var class="Fa">ino</var> with the mode + <var class="Fa">mode</var> as commencing initialization.</dd> + <dt id="wapbl_unregister_inode~2"><a class="permalink" href="#wapbl_unregister_inode~2"><code class="Fn">wapbl_unregister_inode</code></a>(<var class="Fa">wl</var>, + <var class="Fa">ino</var>, <var class="Fa">mode</var>)</dt> + <dd>Unregister <var class="Fa">ino</var>, which must have previously been + registered with <var class="Fa">wapbl_register_inode</var> using the same + <var class="Fa">mode</var>, now that its initialization has + completed.</dd> + <dt><code class="Fn">wapbl_register_deallocation</code>(<var class="Fa">wl</var>, + <var class="Fa">blk</var>, <var class="Fa">len</var>)</dt> + <dd>Register <var class="Fa">len</var> bytes at the disk address + <var class="Fa">blk</var> as ready for deallocation, so that they will be + passed to the <var class="Fa">flushfn</var> that was given to + <code class="Fn">wapbl_start</code>().</dd> + <dt><code class="Fn">wapbl_jlock_assert</code>(<var class="Fa">wl</var>)</dt> + <dd>Assert that the current transaction is locked. + <p class="Pp" id="any">Note that it might not be locked by the current + thread: this assertion passes if + <a class="permalink" href="#any"><i class="Em">any</i></a> thread has it + locked.</p> + </dd> + <dt id="wapbl_junlock_assert"><a class="permalink" href="#wapbl_junlock_assert"><code class="Fn">wapbl_junlock_assert</code></a>(<var class="Fa">wl</var>)</dt> + <dd>Assert that the current transaction is not exclusively locked by the + current thread. + <p class="Pp" id="wapbl_start~4">Users of <code class="Nm">WAPBL</code> + observe exclusive locks only in the <var class="Fa">flushfn</var> and + <var class="Fa">flushabortfn</var> callbacks to + <a class="permalink" href="#wapbl_start~4"><code class="Fn">wapbl_start</code></a>(). + Outside of such contexts, the transaction is never exclusively locked, + even between <code class="Fn">wapbl_begin</code>() and + <code class="Fn">wapbl_end</code>().</p> + <p class="Pp" id="wapbl_begin~2">There is no way to assert that the current + transaction is not locked at all — i.e., that the caller may + acquire a shared lock on the transaction with + <a class="permalink" href="#wapbl_begin~2"><code class="Fn">wapbl_begin</code></a>() + without danger of deadlock.</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 <code class="Nm">WAPBL</code> subsystem is implemented in + <span class="Pa">sys/kern/vfs_wapbl.c</span>, with hooks in + <span class="Pa">sys/kern/vfs_bio.c</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">buffercache(9)</a>, <a class="Xr">vfsops(9)</a>, + <a class="Xr">wapbl_replay(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp"><code class="Nm">WAPBL</code> works only for file system metadata + managed via the <a class="Xr">buffercache(9)</a>, and provides no way to log + writes via the page cache, as in <a class="Xr">VOP_GETPAGES(9)</a>, + <a class="Xr">VOP_PUTPAGES(9)</a>, and <a class="Xr">ubc_uiomove(9)</a>, + which is normally used for file data.</p> +<p class="Pp">Not only is <code class="Nm">WAPBL</code> unable to log writes via + the page cache, it is also unable to defer <a class="Xr">buffercache(9)</a> + writes until cached pages have been written. This manifests as the + well-known garbage-data-appended-after-crash bug in FFS: when appending to a + file, the pages containing new data may not reach the disk before the inode + update reporting its new size. After a crash, the inode update will be on + disk, but the new data will not be — instead, whatever garbage data + in the free space will appear to have been appended to the file. + <code class="Nm">WAPBL</code> exacerbates the problem by increasing the + throughput of metadata writes, because it can issue many metadata writes + asynchronously that FFS without <code class="Nm">WAPBL</code> would need to + issue synchronously in order for <a class="Xr">fsck(8)</a> to work.</p> +<p class="Pp">The criteria for when the transaction must be flushed to disk + before <code class="Fn">wapbl_begin</code>() returns are heuristic, i.e. + wrong. There is no way for a file system to communicate to + <code class="Fn">wapbl_begin</code>() how many buffers, inodes, and + deallocations it will issue via <code class="Nm">WAPBL</code> in the + transaction.</p> +<p class="Pp"><code class="Nm">WAPBL</code> mainly supports write-ahead, and has + only limited support for rolling back operations, in the form of + <code class="Fn">wapbl_register_inode</code>() and + <code class="Fn">wapbl_unregister_inode</code>(). Consequently, for example, + large writes appending to a file, which requires multiple disk block + allocations and an inode update, must occur in a single transaction — + there is no way to roll back the disk block allocations if the write fails + in the middle, e.g. because of a fault in the middle of the user buffer.</p> +<p class="Pp"><code class="Fn">wapbl_jlock_assert</code>() does not guarantee + that the current thread has the current transaction locked. + <code class="Fn">wapbl_junlock_assert</code>() does not guarantee that the + current thread does not have the current transaction locked at all.</p> +<p class="Pp">There is only one <code class="Nm">WAPBL</code> transaction for + each file system at any given time, and only one + <code class="Nm">WAPBL</code> log on disk. Consequently, all writes are + serialized. Extending <code class="Nm">WAPBL</code> to support multiple logs + per file system, partitioned according to an appropriate scheme, is left as + an exercise for the reader.</p> +<p class="Pp">There is no reason for <code class="Nm">WAPBL</code> to require + its own hooks in <a class="Xr">buffercache(9)</a>.</p> +<p class="Pp">The on-disk format used by <code class="Nm">WAPBL</code> is + undocumented.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 26, 2015</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/wsbell.9 3.html b/static/netbsd/man9/wsbell.9 3.html new file mode 100644 index 00000000..05dad7f0 --- /dev/null +++ b/static/netbsd/man9/wsbell.9 3.html @@ -0,0 +1,103 @@ +<table class="head"> + <tr> + <td class="head-ltitle">WSBELL(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">WSBELL(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">wsbell</code>, + <code class="Nm">wsbelldevprint</code> — <span class="Nd">wscons + system bell support</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">dev/wscons/wsconsio.h</a>></code> + <br/> + <code class="In">#include + <<a class="In">dev/wscons/wsbellvar.h</a>></code></p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">wsbelldevprint</code>(<var class="Fa" style="white-space: nowrap;">void + *aux</var>, <var class="Fa" style="white-space: nowrap;">const char + *pnp</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">wsbell</code> module is a component of the + <a class="Xr">wscons(9)</a> framework, providing keyboard-independent bell + support. All of the support is provided by the <a class="Xr">wsbell(4)</a> + device driver, which must be a child of the hardware device driver. The only + hardware device drivers that can provide a <code class="Nm">wsbell</code> + facility are <a class="Xr">speaker(4)</a> devices.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DATA_TYPES"><a class="permalink" href="#DATA_TYPES">DATA + TYPES</a></h1> +<p class="Pp">Speaker drivers providing support for wscons bell devices will + make use of the following data types:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">struct wsbelldev_attach_args</var></dt> + <dd>A structure used to attach the <a class="Xr">wsbell(4)</a> child device. + It has the following members: + <div class="Bd Pp Li"> + <pre> void *accesscookie;</pre> + </div> + </dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="FUNCTIONS"><a class="permalink" href="#FUNCTIONS">FUNCTIONS</a></h1> +<dl class="Bl-tag"> + <dt id="wsbelldevprint"><a class="permalink" href="#wsbelldevprint"><code class="Fn">wsbelldevprint</code></a>(<var class="Fa">aux</var>, + <var class="Fa">pnp</var>)</dt> + <dd>The default wsbell printing routine used by + <a class="permalink" href="#config_found"><code class="Fn" id="config_found">config_found</code></a>(). + (see <a class="Xr">autoconf(9)</a>).</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTOCONFIGURATION"><a class="permalink" href="#AUTOCONFIGURATION">AUTOCONFIGURATION</a></h1> +<p class="Pp">Speaker drivers which want to use the wsbell module must be a + parent to the <a class="Xr">wsbell(4)</a> device and provide an attachment + interface. To attach the <a class="Xr">wsbell(4)</a> device, the speaker + driver must allocate and populate a + <var class="Fa">wsbelldev_attach_args</var> structure with a pointer to the + parent's device structure as an access cookie and call + <code class="Fn">config_found</code>() to perform the attach (see + <a class="Xr">autoconf(9)</a>).</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="OPERATION"><a class="permalink" href="#OPERATION">OPERATION</a></h1> +<p class="Pp">When a bell event is received on a <a class="Xr">wsdisplay(4)</a> + device the system bell is sounded.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="CODE_REFERENCES"><a class="permalink" href="#CODE_REFERENCES">CODE + REFERENCES</a></h1> +<p class="Pp">The wscons subsystem is implemented within the directory + <span class="Pa">sys/dev/wscons</span>. The <code class="Nm">wsbell</code> + module itself is implement within the file + <span class="Pa">sys/dev/wscons/wsbell.c</span>. <a class="Xr">ioctl(2)</a> + operations are listed in + <span class="Pa">sys/dev/wscons/wsconsio.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">ioctl(2)</a>, <a class="Xr">wsbell(4)</a>, + <a class="Xr">wscons(4)</a>, <a class="Xr">wskbd(4)</a>, + <a class="Xr">autoconf(9)</a>, <a class="Xr">driver(9)</a>, + <a class="Xr">intro(9)</a>, <a class="Xr">wscons(9)</a>, + <a class="Xr">wsdisplay(9)</a>, <a class="Xr">wskbd(9)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">June 30, 2017</td> + <td class="foot-os">NetBSD 10.1</td> + </tr> +</table> diff --git a/static/netbsd/man9/x86_msr_xcall.9 b/static/netbsd/man9/x86_msr_xcall.9 new file mode 100644 index 00000000..34b9c103 --- /dev/null +++ b/static/netbsd/man9/x86_msr_xcall.9 @@ -0,0 +1,98 @@ +.\" $NetBSD: x86_msr_xcall.9,v 1.5 2017/02/17 22:31:08 christos Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jukka Ruohonen. +.\" +.\" 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 February 17, 2017 +.Dt X86_MSR_XCALL 9 x86 +.Os +.Sh NAME +.Nm x86_msr_xcall +.Nd MSR specific cross-call +.Sh SYNOPSIS +.In x86/cpu_msr.h +.Ft void +.Fn x86_msr_xcall "void *arg1" "void *arg1" +.Sh DESCRIPTION +The +.Fn x86_msr_xcall +function provides a x86-specific IPI handler suitable for use with the +.Xr xcall 9 +interface. +It can be used to ensure that a given +.Tn MSR +call is executed on all processors. +The prototype follows the +.Ft xcfunc_t +function pointer type and the opaque +.Fa arg1 +pointer is casted to the following structure: +.Bd -literal -offset indent +struct msr_rw_info { + int msr_read; + int msr_type; + uint64_t msr_value; + uint64_t msr_mask; +}; +.Ed +.Pp +This structure must be filled prior to the call. +Two fields are compulsory: +.Fa msr_type +is used as the address of the +.Tn MSR +and +.Fa msr_value +is the value to be written. +If +.Fa msr_read +is not zero, +.Fn x86_msr_xcall +will first read from +.Fa msr_type +and then clear the mask specified in +.Fa msr_mask +before the write operation. +.Sh EXAMPLES +The following example writes a value zero to the +.Tn MSR_THERM_CONTROL +model-specific register on all processors in the system: +.Bd -literal -offset indent +struct msr_rw_info msr; +uint64_t xc; + +msr.msr_value = 0; +msr.msr_read = true; +msr.msr_type = MSR_THERM_CONTROL; +msr.msr_mask = 0x1e; + +xc = xc_broadcast(0, (xcfunc_t)x86_msr_xcall, &msr, NULL); +xc_wait(xc); +.Ed +.Sh SEE ALSO +.Xr x86/rdmsr 9 , +.Xr xcall 9 |