diff --git a/share/man/man3/pthread_set_name_np.3 b/share/man/man3/pthread_set_name_np.3 index 5fb627a5a182..5423ef898f58 100644 --- a/share/man/man3/pthread_set_name_np.3 +++ b/share/man/man3/pthread_set_name_np.3 @@ -1,109 +1,109 @@ .\" Copyright (c) 2003 Alexey Zelkin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 12, 2021 .Dt PTHREAD_SET_NAME_NP 3 .Os .Sh NAME .Nm pthread_get_name_np , .Nm pthread_getname_np , -.Nm pthread_set_name_np +.Nm pthread_set_name_np , .Nm pthread_setname_np .Nd set and retrieve the thread name .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS .In pthread_np.h .Ft void .Fn pthread_get_name_np "pthread_t thread" "char *name" "size_t len" .Ft int .Fn pthread_getname_np "pthread_t thread" "char *name" "size_t len" .Ft void .Fn pthread_set_name_np "pthread_t thread" "const char *name" .Ft int .Fn pthread_setname_np "pthread_t thread" "const char *name" .Sh DESCRIPTION The .Fn pthread_set_name_np and .Fn pthread_setname_np functions apply a copy of the given .Fa name to the given .Fa thread . .Pp The .Fn pthread_get_name_np and .Fn pthread_getname_np functions retrieve the .Fa name associated with .Fa thread . If .Fn pthread_set_name_np was not previously called for .Fa thread , the buffer pointed to by .Fa name will be empty. .Sh ERRORS The .Nm pthread_getname_np and .Nm pthread_setname_np will fail if .Bl -tag -width Er .It Bq Er ESRCH No thread could be found in the current process corresponding to that specified by the given thread ID .Fa thread . .El .Pp Because of the debugging nature of .Nm pthread_get_name_np and .Nm pthread_set_name_np functions, all errors that may appear inside are silently ignored. .Sh SEE ALSO -.Xr pthread_np 3 , -.Xr thr_set_name 2 +.Xr thr_set_name 2 , +.Xr pthread_np 3 .Sh STANDARDS .Fn pthread_set_name_np and .Fn pthread_get_name_np are non-standard extensions. .Fn pthread_setname_np and .Fn pthread_getname_np are also non-standard, but are implemented by larger number of operating systems so they are in fact more portable. .Sh AUTHORS This manual page was written by .An Alexey Zelkin Aq Mt phantom@FreeBSD.org and .An Yuri Pankov Aq Mt yuripv@yuripv.net . diff --git a/share/man/man3/pthread_testcancel.3 b/share/man/man3/pthread_testcancel.3 index 5d0efcb2d635..9ba1403dffdc 100644 --- a/share/man/man3/pthread_testcancel.3 +++ b/share/man/man3/pthread_testcancel.3 @@ -1,259 +1,258 @@ .\" $FreeBSD$ .Dd March 18, 2017 .Dt PTHREAD_TESTCANCEL 3 .Os .Sh NAME .Nm pthread_setcancelstate , .Nm pthread_setcanceltype , .Nm pthread_testcancel .Nd set cancelability state .Sh LIBRARY .Lb libpthread .Sh SYNOPSIS .In pthread.h .Ft int .Fn pthread_setcancelstate "int state" "int *oldstate" .Ft int .Fn pthread_setcanceltype "int type" "int *oldtype" .Ft void .Fn pthread_testcancel "void" .Sh DESCRIPTION The .Fn pthread_setcancelstate function atomically both sets the calling thread's cancelability state to the indicated .Fa state and, if .Fa oldstate is not .Dv NULL , returns the previous cancelability state at the location referenced by .Fa oldstate . Legal values for .Fa state are .Dv PTHREAD_CANCEL_ENABLE and .Dv PTHREAD_CANCEL_DISABLE . .Pp The .Fn pthread_setcanceltype function atomically both sets the calling thread's cancelability type to the indicated .Fa type and, if .Fa oldtype is not .Dv NULL , returns the previous cancelability type at the location referenced by .Fa oldtype . Legal values for .Fa type are .Dv PTHREAD_CANCEL_DEFERRED and .Dv PTHREAD_CANCEL_ASYNCHRONOUS . .Pp The cancelability state and type of any newly created threads, including the thread in which .Fn main was first invoked, are .Dv PTHREAD_CANCEL_ENABLE and .Dv PTHREAD_CANCEL_DEFERRED respectively. .Pp The .Fn pthread_testcancel function creates a cancellation point in the calling thread. The .Fn pthread_testcancel function has no effect if cancelability is disabled. -.Pp .Ss Cancelability States The cancelability state of a thread determines the action taken upon receipt of a cancellation request. The thread may control cancellation in a number of ways. .Pp Each thread maintains its own .Dq cancelability state which may be encoded in two bits: .Bl -hang .It Em Cancelability Enable When cancelability is .Dv PTHREAD_CANCEL_DISABLE , cancellation requests against the target thread are held pending. .It Em Cancelability Type When cancelability is enabled and the cancelability type is .Dv PTHREAD_CANCEL_ASYNCHRONOUS , new or pending cancellation requests may be acted upon at any time. When cancelability is enabled and the cancelability type is .Dv PTHREAD_CANCEL_DEFERRED , cancellation requests are held pending until a cancellation point (see below) is reached. If cancelability is disabled, the setting of the cancelability type has no immediate effect as all cancellation requests are held pending; however, once cancelability is enabled again the new type will be in effect. .El .Ss Cancellation Points Cancellation points will occur when a thread is executing the following functions: .Bl -tag -width "Fn pthread_cond_timedwait" -compact .It Fn accept .It Fn accept4 .It Fn aio_suspend .It Fn connect .It Fn clock_nanosleep .It Fn close .It Fn creat .It Fn fcntl The .Fn fcntl function is a cancellation point if .Fa cmd is .Dv F_SETLKW . .It Fn fdatasync .It Fn fsync .It Fn kevent The .Fn kevent function is a cancellation point if it is potentially blocking, such as when the .Fa nevents argument is non-zero. .It Fn mq_receive .It Fn mq_send .It Fn mq_timedreceive .It Fn mq_timedsend .It Fn msync .It Fn nanosleep .It Fn open .It Fn openat .It Fn pause .It Fn poll .It Fn ppoll .It Fn pselect .It Fn pthread_cond_timedwait .It Fn pthread_cond_wait .It Fn pthread_join .It Fn pthread_testcancel .It Fn read .It Fn readv .It Fn recv .It Fn recvfrom .It Fn recvmsg .It Fn select .It Fn sem_timedwait .It Fn sem_clockwait_np .It Fn sem_wait .It Fn send .It Fn sendmsg .It Fn sendto .It Fn sigsuspend .It Fn sigtimedwait .It Fn sigwaitinfo .It Fn sigwait .It Fn sleep .It Fn system .It Fn tcdrain .It Fn usleep .It Fn wait .It Fn wait3 .It Fn wait4 .It Fn wait6 .It Fn waitid .It Fn waitpid .It Fn write .It Fn writev .El .Sh NOTES The .Fn pthread_setcancelstate and .Fn pthread_setcanceltype functions are used to control the points at which a thread may be asynchronously canceled. For cancellation control to be usable in modular fashion, some rules must be followed. .Pp For purposes of this discussion, consider an object to be a generalization of a procedure. It is a set of procedures and global variables written as a unit and called by clients not known by the object. Objects may depend on other objects. .Pp First, cancelability should only be disabled on entry to an object, never explicitly enabled. On exit from an object, the cancelability state should always be restored to its value on entry to the object. .Pp This follows from a modularity argument: if the client of an object (or the client of an object that uses that object) has disabled cancelability, it is because the client does not want to have to worry about how to clean up if the thread is canceled while executing some sequence of actions. If an object is called in such a state and it enables cancelability and a cancellation request is pending for that thread, then the thread will be canceled, contrary to the wish of the client that disabled. .Pp Second, the cancelability type may be explicitly set to either .Em deferred or .Em asynchronous upon entry to an object. But as with the cancelability state, on exit from an object that cancelability type should always be restored to its value on entry to the object. .Pp Finally, only functions that are cancel-safe may be called from a thread that is asynchronously cancelable. .Sh RETURN VALUES If successful, the .Fn pthread_setcancelstate and .Fn pthread_setcanceltype functions will return zero. Otherwise, an error number shall be returned to indicate the error. .Sh ERRORS The function .Fn pthread_setcancelstate may fail with: .Bl -tag -width Er .It Bq Er EINVAL The specified state is not .Dv PTHREAD_CANCEL_ENABLE or .Dv PTHREAD_CANCEL_DISABLE . .El .Pp The function .Fn pthread_setcanceltype may fail with: .Bl -tag -width Er .It Bq Er EINVAL The specified state is not .Dv PTHREAD_CANCEL_DEFERRED or .Dv PTHREAD_CANCEL_ASYNCHRONOUS . .El .Sh SEE ALSO .Xr pthread_cancel 3 .Sh STANDARDS The .Fn pthread_testcancel function conforms to .St -p1003.1-96 . The standard allows implementations to make many more functions cancellation points. .Sh AUTHORS This manual page was written by .An David Leonard Aq Mt d@openbsd.org for the .Ox implementation of .Xr pthread_cancel 3 . diff --git a/share/man/man9/OF_child.9 b/share/man/man9/OF_child.9 index 03036197f5ab..8227401f5f14 100644 --- a/share/man/man9/OF_child.9 +++ b/share/man/man9/OF_child.9 @@ -1,76 +1,75 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2018 .Dt OF_CHILD 9 .Os .Sh NAME .Nm OF_child , .Nm OF_parent , .Nm OF_peer .Nd navigate device tree .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft phandle_t .Fn OF_child "phandle_t node" .Ft phandle_t .Fn OF_parent "phandle_t node" .Ft phandle_t .Fn OF_peer "phandle_t node" .Sh DESCRIPTION -.Pp .Fn OF_child returns the phandle value of the first child of the .Fa node . Zero is returned if there are no child nodes. .Pp .Fn OF_parent returns the phandle for the parent of the .Fa node . Zero is returned if .Fa node is the root node. .Pp .Fn OF_peer returns the phandle value of the next sibling of the .Fa node . Zero is returned if there is no sibling node. .Sh EXAMPLES .Bd -literal phandle_t node, child; ... for (child = OF_child(node); child != 0; child = OF_peer(child) { ... } .Ed .Sh SEE ALSO .Xr OF_finddevice 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/share/man/man9/OF_device_from_xref.9 b/share/man/man9/OF_device_from_xref.9 index f6a483f9fd5c..c8c206afe777 100644 --- a/share/man/man9/OF_device_from_xref.9 +++ b/share/man/man9/OF_device_from_xref.9 @@ -1,91 +1,90 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2018 .Dt OF_DEVICE_FROM_XREF 9 .Os .Sh NAME .Nm OF_device_from_xref , .Nm OF_xref_from_device , .Nm OF_device_register_xref .Nd "manage mappings between xrefs and devices" .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft int .Fn OF_device_register_xref "phandle_t xref" "device_t dev" .Ft device_t .Fn OF_device_from_xref "phandle_t xref" .Ft phandle_t .Fn OF_xref_from_device "device_t dev" .Sh DESCRIPTION -.Pp When a device tree node references another node, the driver may need to get a device_t instance associated with the referenced node. For instance, an Ethernet driver accessing a PHY device. To make this possible, the kernel maintains a table that maps effective handles to device_t instances. .Pp .Fn OF_device_register_xref adds a map entry from the effective phandle .Fa xref to device .Fa dev . If a mapping entry for .Fa xref already exists, it is replaced with the new one. The function always returns 0. .Pp .Fn OF_device_from_xref returns a device_t instance associated with the effective phandle .Fa xref . If no such mapping exists, the function returns NULL. .Pp .Fn OF_xref_from_device returns the effective phandle associated with the device .Fa dev . If no such mapping exists, the function returns 0. .Sh EXAMPLES .Bd -literal static int acmephy_attach(device_t dev) { phandle_t node; /* PHY node is referenced from eth device, register it */ node = ofw_bus_get_node(dev); OF_device_register_xref(OF_xref_from_node(node), dev); return (0); } .Ed .Sh SEE ALSO .Xr OF_node_to_xref 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/share/man/man9/OF_finddevice.9 b/share/man/man9/OF_finddevice.9 index 30341e779bf2..d524a182f01c 100644 --- a/share/man/man9/OF_finddevice.9 +++ b/share/man/man9/OF_finddevice.9 @@ -1,73 +1,73 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2018 .Dt OF_FINDDEVICE 9 .Os .Sh NAME .Nm OF_finddevice .Nd find node in device tree .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft phandle_t .Fn OF_finddevice "const char *path" .Sh DESCRIPTION .Fn OF_finddevice returns the phandle for the node specified by the .Fa path . Returns -1 if the path cannot be found in the tree. .Sh EXAMPLES .Bd -literal phandle_t root, i2c; root = OF_finddevice("/"); i2c = OF_finddevice("/soc/axi/i2c@a0e0000"); if (i2c != -1) { ... } .Ed .Sh SEE ALSO -.Xr OF_child 9 -.Xr OF_parent 9 +.Xr OF_child 9 , +.Xr OF_parent 9 , .Xr OF_peer 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . .Sh CAVEATS The return value should only be checked with equality operators (equal to, not equal to) and not relational comparison (less than, greater than ). There is a discrepancy between IEEE 1275 standard and .Fx Ns 's internal representation of a phandle: IEEE 1275 requires the return value of this function to be -1 if the path is not found. But phandle_t is an unsigned type, so it cannot be relationally compared with -1 or 0, this comparison is always true or always false. diff --git a/share/man/man9/OF_getprop.9 b/share/man/man9/OF_getprop.9 index 9ad996f4395b..5d0607a0a3bf 100644 --- a/share/man/man9/OF_getprop.9 +++ b/share/man/man9/OF_getprop.9 @@ -1,353 +1,352 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 23, 2018 .Dt OF_GETPROP 9 .Os .Sh NAME .Nm OF_getprop , .Nm OF_getproplen , .Nm OF_getencprop , .Nm OF_hasprop , .Nm OF_searchprop , .Nm OF_searchencprop , .Nm OF_getprop_alloc , .Nm OF_getencprop_alloc , .Nm OF_getprop_alloc_multi , .Nm OF_getencprop_alloc_multi , .Nm OF_prop_free , .Nm OF_nextprop , .Nm OF_setprop .Nd access properties of device tree node .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft ssize_t .Fn OF_getproplen "phandle_t node" "const char *propname" .Ft ssize_t .Fn OF_getprop "phandle_t node" "const char *propname" \ "void *buf" "size_t len" .Ft ssize_t .Fn OF_getencprop "phandle_t node" "const char *prop" \ "pcell_t *buf" "size_t len" .Ft int .Fn OF_hasprop "phandle_t node" "const char *propname" .Ft ssize_t .Fn OF_searchprop "phandle_t node" "const char *propname" \ "void *buf" "size_t len" .Ft ssize_t .Fn OF_searchencprop "phandle_t node" "const char *propname" \ "pcell_t *buf" "size_t len" .Ft ssize_t .Fn OF_getprop_alloc "phandle_t node" "const char *propname" \ "void **buf" .Ft ssize_t .Fn OF_getencprop_alloc "phandle_t node" "const char *propname" \ "pcell_t **buf" .Ft ssize_t .Fn OF_getprop_alloc_multi "phandle_t node" "const char *propname" \ "int elsz" "void **buf" .Ft ssize_t .Fn OF_getencprop_alloc_multi "phandle_t node" "const char *propname" \ "int elsz" "pcell_t **buf" .Ft void .Fn OF_prop_free "void *buf" .Ft int .Fn OF_nextprop "phandle_t node" "const char *propname" \ "char *buf" "size_t len" .Ft int .Fn OF_setprop "phandle_t node" "const char *propname" \ "const void *buf" "size_t len" .Sh DESCRIPTION -.Pp Device nodes can have associated properties. Properties consist of a name and a value. A name is a human-readable string from 1 to 31 characters long. A value is an array of zero or more bytes that encode certain information. The meaning of that bytes depends on how drivers interpret them. Properties can encode byte arrays, text strings, unsigned 32-bit values or any combination of these types. .Pp Property with a zero-length value usually represents boolean information. If the property is present, it signifies true, otherwise false. .Pp A byte array is encoded as a sequence of bytes and represents values like MAC addresses. .Pp A text string is a sequence of n printable characters. It is encoded as a byte array of length n + 1 bytes with characters represented as bytes plus a terminating null character. .Pp Unsigned 32-bit values, also sometimes called cells, are encoded as a sequence of 4 bytes in big-endian order. .Pp .Fn OF_getproplen returns either the length of the value associated with the property .Fa propname in the node identified by .Fa node , or 0 if the property exists but has no associated value. If .Fa propname does not exist, -1 is returned. .Pp .Fn OF_getprop copies a maximum of .Fa len bytes from the value associated with the property .Fa propname of the device node .Fa node into the memory specified by .Fa buf . Returns the actual size of the value or -1 if the property does not exist. .Pp .Fn OF_getencprop copies a maximum of .Fa len bytes into memory specified by .Fa buf , then converts cell values from big-endian to host byte order. Returns the actual size of the value in bytes, or -1 if the property does not exist. .Fa len must be a multiple of 4. .Pp .Fn OF_hasprop returns 1 if the device node .Fa node has a property specified by .Fa propname , and zero if the property does not exist. .Pp .Fn OF_searchprop recursively looks for the property specified by .Fa propname starting with the device node .Fa node followed by the parent node and up to the root node. If the property is found, the function copies a maximum of .Fa len bytes of the value associated with the property into the memory specified by .Fa buf . Returns the actual size in bytes of the value, or -1 if the property does not exist. .Pp .Fn OF_searchencprop recursively looks for the property specified by .Fa propname starting with the device node .Fa node followed by the parent node and up to the root node. If the property is found, the function copies a maximum of .Fa len bytes of the value associated with the property into the memory specified by .Fa buf , then converts cell values from big-endian to host byte order. Returns the actual size in bytes of the value, or -1 if the property does not exist. .Pp .Fn OF_getprop_alloc allocates memory large enough to hold the value associated with the property .Fa propname of the device node .Fa node and copies the value into the newly allocated memory region. Returns the actual size of the value and stores the address of the allocated memory in .Fa *buf . If the property has a zero-sized value .Fa *buf is set NULL. Returns -1 if the property does not exist or memory allocation failed. Allocated memory should be released when no longer required by calling .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_getencprop_alloc allocates enough memory to hold the value associated with the property .Fa propname of the device node .Fa node , copies the value into the newly allocated memory region, and then converts cell values from big-endian to host byte order. The actual size of the value is returned and the address of allocated memory is stored in .Fa *buf . If the property has zero-length value, .Fa *buf is set to NULL. Returns -1 if the property does not exist or memory allocation failed or the size of the value is not divisible by a cell size (4 bytes). Allocated memory should be released when no longer required by calling .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_getprop_alloc_multi allocates memory large enough to hold the value associated with the property .Fa propname of the device node .Fa node and copies the value into the newly allocated memory region. The value is expected to be an array of zero or more elements .Fa elsz bytes long. Returns the number of elements in the value and stores the address of the allocated memory in .Fa *buf . If the property has a zero-sized value .Fa *buf is set NULL. Returns -1 if the property does not exist or memory allocation failed or the size of the value is not divisible by .Fa elsz . Allocated memory should be released when no longer required by calling .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_getencprop_alloc_multi allocates memory large enough to hold the value associated with the property .Fa propname of the device node .Fa node and copies the value into the newly allocated memory region, and then converts cell values from big-endian to host byte order. The value is expected to be an array of zero or more elements .Fa elsz bytes long. Returns the number of elements in the value and stores the address of the allocated memory in .Fa *buf . If the property has a zero-sized value .Fa *buf is set NULL. Returns -1 if the property does not exist or memory allocation failed or the size of the value is not divisible by .Fa elsz . Allocated memory should be released when no longer required by calling .Fn OF_prop_free . The function might sleep when allocating memory. .Pp .Fn OF_prop_free releases memory at .Fa buf that was allocated by .Fn OF_getprop_alloc , .Fn OF_getencprop_alloc , .Fn OF_getprop_alloc_multi , .Fn OF_getencprop_alloc_multi . .Pp .Fn OF_nextprop copies a maximum of .Fa size bytes of the name of the property following the .Fa propname property into .Fa buf . If .Fa propname is NULL, the function copies the name of the first property of the device node .Fa node . .Fn OF_nextprop returns -1 if .Fa propname is invalid or there is an internal error, 0 if there are no more properties after .Fa propname , or 1 otherwise. .Pp .Fn OF_setprop sets the value of the property .Fa propname in the device node .Fa node to the value beginning at the address specified by .Fa buf and running for .Fa len bytes. If the property does not exist, the function tries to create it. .Fn OF_setprop returns the actual size of the new value, or -1 if the property value cannot be changed or the new property cannot be created. .Sh EXAMPLES .Bd -literal phandle_t node; phandle_t hdmixref, hdminode; device_t hdmi; uint8_t mac[6]; char *model; /* * Get a byte array property */ if (OF_getprop(node, "eth,hwaddr", mac, sizeof(mac)) != sizeof(mac)) return; /* * Get internal node reference and device associated with it */ if (OF_getencprop(node, "hdmi", &hdmixref) <= 0) return; hdmi = OF_device_from_xref(hdmixref); /* * Get string value of model property of HDMI framer node */ hdminode = OF_node_from_xref(hdmixref); if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0) return; .Ed .Sh SEE ALSO -.Xr OF_device_from_xref 9 +.Xr OF_device_from_xref 9 , .Xr OF_node_from_xref 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/share/man/man9/OF_node_from_xref.9 b/share/man/man9/OF_node_from_xref.9 index fd4fae8c5375..41b683fac928 100644 --- a/share/man/man9/OF_node_from_xref.9 +++ b/share/man/man9/OF_node_from_xref.9 @@ -1,100 +1,99 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2018 .Dt OF_NODE_FROM_XREF 9 .Os .Sh NAME .Nm OF_node_from_xref , .Nm OF_xref_from_node .Nd convert between kernel phandle and effective phandle .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft phandle_t .Fn OF_node_from_xref "phandle_t xref" .Ft phandle_t .Fn OF_xref_from_node "phandle_t node" .Sh DESCRIPTION -.Pp Some OpenFirmware implementations (FDT, IBM) have a concept of effective phandle or xrefs. They are used to cross-reference device tree nodes. For instance, a framebuffer controller may refer to a GPIO controller and pin that controls the backlight. In this example, the GPIO node would have a cell (32-bit integer) property with a reserved name like "phandle" or "linux,phandle" whose value uniquely identifies the node. The actual name depends on the implementation. The framebuffer node would have a property with the name described by device bindings (device-specific set of properties). It can be a cell property or a combined property with one part of it being a cell. The value of the framebuffer node's property would be the same as the value of the GPIO "phandle" property so it can be said that the framebuffer node refers to the GPIO node. The kernel uses internal logic to assign unique identifiers to the device tree nodes, and these values do not match the values of "phandle" properties. .Fn OF_node_from_xref and .Fn OF_xref_from_node are used to perform conversion between these two kinds of node identifiers. .Pp .Fn OF_node_from_xref returns the kernel phandle for the effective phandle .Fa xref . If one cannot be found or the OpenFirmware implementation does not support effective phandles, the function returns the input value. .Pp .Fn OF_xref_from_xref returns the effective phandle for the kernel phandle .Fa xref . If one cannot be found or the OpenFirmware implementation does not support effective phandles, the function returns the input value. .Sh EXAMPLES .Bd -literal phandle_t panelnode, panelxref; char *model; if (OF_getencprop(node, "lcd-panel", &panelxref) <= 0) return; panelnode = OF_node_from_xref(panelxref); if (OF_getprop_alloc(hdminode, "model", (void **)&model) <= 0) return; .Ed .Sh SEE ALSO -.Xr OF_device_from_xref 9 +.Xr OF_device_from_xref 9 , .Xr OF_device_register_xref 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/share/man/man9/OF_package_to_path.9 b/share/man/man9/OF_package_to_path.9 index 6726ccde9cf5..93ff504bfaae 100644 --- a/share/man/man9/OF_package_to_path.9 +++ b/share/man/man9/OF_package_to_path.9 @@ -1,54 +1,53 @@ .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 9, 2018 .Dt OF_PACKAGE_TO_PATH 9 .Os .Sh NAME .Nm OF_package_to_path .Nd get fully qualified path to a device tree node .Sh SYNOPSIS .In dev/ofw/ofw_bus.h .In dev/ofw/ofw_bus_subr.h .Ft ssize_t .Fn OF_package_to_path "phandle_t node" "char *buf" "size_t len" .Sh DESCRIPTION -.Pp .Fn OF_package_to_path copies at most .Fa len bytes of the fully qualified path to the device tree node .Fa node into the memory specified by .Fa buf . The function returns the number of bytes copied or -1 in case of the error. .Sh SEE ALSO .Xr OF_finddevice 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Oleksandr Tymoshenko Aq Mt gonzo@FreeBSD.org . diff --git a/share/man/man9/atomic.9 b/share/man/man9/atomic.9 index e95bfbdbf4e8..7513d569c2f1 100644 --- a/share/man/man9/atomic.9 +++ b/share/man/man9/atomic.9 @@ -1,618 +1,618 @@ .\" Copyright (c) 2000-2001 John H. Baldwin .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 16, 2023 .Dt ATOMIC 9 .Os .Sh NAME .Nm atomic_add , .Nm atomic_clear , .Nm atomic_cmpset , .Nm atomic_fcmpset , .Nm atomic_fetchadd , .Nm atomic_interrupt_fence , .Nm atomic_load , .Nm atomic_readandclear , .Nm atomic_set , .Nm atomic_subtract , .Nm atomic_store , .Nm atomic_thread_fence .Nd atomic operations .Sh SYNOPSIS .In machine/atomic.h .Ft void .Fn atomic_add_[acq_|rel_] "volatile *p" " v" .Ft void .Fn atomic_clear_[acq_|rel_] "volatile *p" " v" .Ft int .Fo atomic_cmpset_[acq_|rel_] .Fa "volatile *dst" .Fa " old" .Fa " new" .Fc .Ft int .Fo atomic_fcmpset_[acq_|rel_] .Fa "volatile *dst" .Fa " *old" .Fa " new" .Fc .Ft .Fn atomic_fetchadd_ "volatile *p" " v" .Ft void .Fn atomic_interrupt_fence "void" .Ft .Fn atomic_load_[acq_] "volatile *p" .Ft .Fn atomic_readandclear_ "volatile *p" .Ft void .Fn atomic_set_[acq_|rel_] "volatile *p" " v" .Ft void .Fn atomic_subtract_[acq_|rel_] "volatile *p" " v" .Ft void .Fn atomic_store_[rel_] "volatile *p" " v" .Ft .Fn atomic_swap_ "volatile *p" " v" .Ft int .Fn atomic_testandclear_ "volatile *p" "u_int v" .Ft int .Fn atomic_testandset_ "volatile *p" "u_int v" .Ft void .Fn atomic_thread_fence_[acq|acq_rel|rel|seq_cst] "void" .Sh DESCRIPTION Atomic operations are commonly used to implement reference counts and as building blocks for synchronization primitives, such as mutexes. .Pp All of these operations are performed .Em atomically across multiple threads and in the presence of interrupts, meaning that they are performed in an indivisible manner from the perspective of concurrently running threads and interrupt handlers. .Pp On all architectures supported by .Fx , ordinary loads and stores of integers in cache-coherent memory are inherently atomic if the integer is naturally aligned and its size does not exceed the processor's word size. However, such loads and stores may be elided from the program by the compiler, whereas atomic operations are always performed. .Pp When atomic operations are performed on cache-coherent memory, all operations on the same location are totally ordered. .Pp When an atomic load is performed on a location in cache-coherent memory, it reads the entire value that was defined by the last atomic store to each byte of the location. An atomic load will never return a value out of thin air. When an atomic store is performed on a location, no other thread or interrupt handler will observe a .Em torn write , or partial modification of the location. .Pp Except as noted below, the semantics of these operations are almost identical to the semantics of similarly named C11 atomic operations. .Ss Types Most atomic operations act upon a specific .Fa type . That type is indicated in the function name. In contrast to C11 atomic operations, .Fx Ns 's atomic operations are performed on ordinary integer types. The available types are: .Pp .Bl -tag -offset indent -width short -compact .It Li int unsigned integer .It Li long unsigned long integer .It Li ptr unsigned integer the size of a pointer .It Li 32 unsigned 32-bit integer .It Li 64 unsigned 64-bit integer .El .Pp For example, the function to atomically add two integers is called .Fn atomic_add_int . .Pp Certain architectures also provide operations for types smaller than .Dq Li int . .Pp .Bl -tag -offset indent -width short -compact .It Li char unsigned character .It Li short unsigned short integer .It Li 8 unsigned 8-bit integer .It Li 16 unsigned 16-bit integer .El .Pp These types must not be used in machine-independent code. .Ss Acquire and Release Operations By default, a thread's accesses to different memory locations might not be performed in .Em program order , that is, the order in which the accesses appear in the source code. To optimize the program's execution, both the compiler and processor might reorder the thread's accesses. However, both ensure that their reordering of the accesses is not visible to the thread. Otherwise, the traditional memory model that is expected by single-threaded programs would be violated. Nonetheless, other threads in a multithreaded program, such as the .Fx kernel, might observe the reordering. Moreover, in some cases, such as the implementation of synchronization between threads, arbitrary reordering might result in the incorrect execution of the program. To constrain the reordering that both the compiler and processor might perform on a thread's accesses, a programmer can use atomic operations with .Em acquire and .Em release semantics. .Pp Atomic operations on memory have up to three variants. The first, or .Em relaxed variant, performs the operation without imposing any ordering constraints on accesses to other memory locations. This variant is the default. The second variant has acquire semantics, and the third variant has release semantics. .Pp When an atomic operation has acquire semantics, the operation must have completed before any subsequent load or store (by program order) is performed. Conversely, acquire semantics do not require that prior loads or stores have completed before the atomic operation is performed. An atomic operation can only have acquire semantics if it performs a load from memory. To denote acquire semantics, the suffix .Dq Li _acq is inserted into the function name immediately prior to the .Dq Li _ Ns Aq Fa type suffix. For example, to subtract two integers ensuring that the subtraction is completed before any subsequent loads and stores are performed, use .Fn atomic_subtract_acq_int . .Pp When an atomic operation has release semantics, all prior loads or stores (by program order) must have completed before the operation is performed. Conversely, release semantics do not require that the atomic operation must have completed before any subsequent load or store is performed. An atomic operation can only have release semantics if it performs a store to memory. To denote release semantics, the suffix .Dq Li _rel is inserted into the function name immediately prior to the .Dq Li _ Ns Aq Fa type suffix. For example, to add two long integers ensuring that all prior loads and stores are completed before the addition is performed, use .Fn atomic_add_rel_long . .Pp When a release operation by one thread .Em synchronizes with an acquire operation by another thread, usually meaning that the acquire operation reads the value written by the release operation, then the effects of all prior stores by the releasing thread must become visible to subsequent loads by the acquiring thread. Moreover, the effects of all stores (by other threads) that were visible to the releasing thread must also become visible to the acquiring thread. These rules only apply to the synchronizing threads. Other threads might observe these stores in a different order. .Pp In effect, atomic operations with acquire and release semantics establish one-way barriers to reordering that enable the implementations of synchronization primitives to express their ordering requirements without also imposing unnecessary ordering. For example, for a critical section guarded by a mutex, an acquire operation when the mutex is locked and a release operation when the mutex is unlocked will prevent any loads or stores from moving outside of the critical section. However, they will not prevent the compiler or processor from moving loads or stores into the critical section, which does not violate the semantics of a mutex. .Ss Thread Fence Operations Alternatively, a programmer can use atomic thread fence operations to constrain the reordering of accesses. In contrast to other atomic operations, fences do not, themselves, access memory. .Pp When a fence has acquire semantics, all prior loads (by program order) must have completed before any subsequent load or store is performed. Thus, an acquire fence is a two-way barrier for load operations. To denote acquire semantics, the suffix .Dq Li _acq is appended to the function name, for example, .Fn atomic_thread_fence_acq . .Pp When a fence has release semantics, all prior loads or stores (by program order) must have completed before any subsequent store operation is performed. Thus, a release fence is a two-way barrier for store operations. To denote release semantics, the suffix .Dq Li _rel is appended to the function name, for example, .Fn atomic_thread_fence_rel . .Pp Although .Fn atomic_thread_fence_acq_rel implements both acquire and release semantics, it is not a full barrier. For example, a store prior to the fence (in program order) may be completed after a load subsequent to the fence. In contrast, .Fn atomic_thread_fence_seq_cst implements a full barrier. Neither loads nor stores may cross this barrier in either direction. .Pp In C11, a release fence by one thread synchronizes with an acquire fence by another thread when an atomic load that is prior to the acquire fence (by program order) reads the value written by an atomic store that is subsequent to the release fence. In constrast, in .Fx , because of the atomicity of ordinary, naturally aligned loads and stores, fences can also be synchronized by ordinary loads and stores. This simplifies the implementation and use of some synchronization primitives in .Fx . .Pp Since neither a compiler nor a processor can foresee which (atomic) load will read the value written by an (atomic) store, the ordering constraints imposed by fences must be more restrictive than acquire loads and release stores. Essentially, this is why fences are two-way barriers. .Pp Although fences impose more restrictive ordering than acquire loads and release stores, by separating access from ordering, they can sometimes facilitate more efficient implementations of synchronization primitives. For example, they can be used to avoid executing a memory barrier until a memory access shows that some condition is satisfied. .Ss Interrupt Fence Operations The -.Fn atomic_interrupt_fence() +.Fn atomic_interrupt_fence function establishes ordering between its call location and any interrupt handler executing on the same CPU. It is modeled after the similar C11 function -.Fn atomic_signal_fence() , +.Fn atomic_signal_fence , and adapted for the kernel environment. .Ss Multiple Processors In multiprocessor systems, the atomicity of the atomic operations on memory depends on support for cache coherence in the underlying architecture. In general, cache coherence on the default memory type, .Dv VM_MEMATTR_DEFAULT , is guaranteed by all architectures that are supported by .Fx . For example, cache coherence is guaranteed on write-back memory by the .Tn amd64 and .Tn i386 architectures. However, on some architectures, cache coherence might not be enabled on all memory types. To determine if cache coherence is enabled for a non-default memory type, consult the architecture's documentation. .Ss Semantics This section describes the semantics of each operation using a C like notation. .Bl -hang .It Fn atomic_add p v .Bd -literal -compact *p += v; .Ed .It Fn atomic_clear p v .Bd -literal -compact *p &= ~v; .Ed .It Fn atomic_cmpset dst old new .Bd -literal -compact if (*dst == old) { *dst = new; return (1); } else return (0); .Ed .El .Pp Some architectures do not implement the .Fn atomic_cmpset functions for the types .Dq Li char , .Dq Li short , .Dq Li 8 , and .Dq Li 16 . .Bl -hang .It Fn atomic_fcmpset dst *old new .El .Pp On architectures implementing .Em Compare And Swap operation in hardware, the functionality can be described as .Bd -literal -offset indent -compact if (*dst == *old) { *dst = new; return (1); } else { *old = *dst; return (0); } .Ed On architectures which provide .Em Load Linked/Store Conditional primitive, the write to .Dv *dst might also fail for several reasons, most important of which is a parallel write to .Dv *dst cache line by other CPU. In this case .Fn atomic_fcmpset function also returns .Dv false , despite .Dl *old == *dst . .Pp Some architectures do not implement the .Fn atomic_fcmpset functions for the types .Dq Li char , .Dq Li short , .Dq Li 8 , and .Dq Li 16 . .Bl -hang .It Fn atomic_fetchadd p v .Bd -literal -compact tmp = *p; *p += v; return (tmp); .Ed .El .Pp The .Fn atomic_fetchadd functions are only implemented for the types .Dq Li int , .Dq Li long and .Dq Li 32 and do not have any variants with memory barriers at this time. .Bl -hang .It Fn atomic_load p .Bd -literal -compact return (*p); .Ed .It Fn atomic_readandclear p .Bd -literal -compact tmp = *p; *p = 0; return (tmp); .Ed .El .Pp The .Fn atomic_readandclear functions are not implemented for the types .Dq Li char , .Dq Li short , .Dq Li ptr , .Dq Li 8 , and .Dq Li 16 and do not have any variants with memory barriers at this time. .Bl -hang .It Fn atomic_set p v .Bd -literal -compact *p |= v; .Ed .It Fn atomic_subtract p v .Bd -literal -compact *p -= v; .Ed .It Fn atomic_store p v .Bd -literal -compact *p = v; .Ed .It Fn atomic_swap p v .Bd -literal -compact tmp = *p; *p = v; return (tmp); .Ed .El .Pp The .Fn atomic_swap functions are not implemented for the types .Dq Li char , .Dq Li short , .Dq Li ptr , .Dq Li 8 , and .Dq Li 16 and do not have any variants with memory barriers at this time. .Bl -hang .It Fn atomic_testandclear p v .Bd -literal -compact bit = 1 << (v % (sizeof(*p) * NBBY)); tmp = (*p & bit) != 0; *p &= ~bit; return (tmp); .Ed .El .Bl -hang .It Fn atomic_testandset p v .Bd -literal -compact bit = 1 << (v % (sizeof(*p) * NBBY)); tmp = (*p & bit) != 0; *p |= bit; return (tmp); .Ed .El .Pp The .Fn atomic_testandset and .Fn atomic_testandclear functions are only implemented for the types .Dq Li int , .Dq Li long and .Dq Li 32 and do not have any variants with memory barriers at this time. .Pp The type .Dq Li 64 is currently not implemented for some of the atomic operations on the .Tn arm , .Tn i386 , and .Tn powerpc architectures. .Sh RETURN VALUES The .Fn atomic_cmpset function returns the result of the compare operation. The .Fn atomic_fcmpset function returns .Dv true if the operation succeeded. Otherwise it returns .Dv false and sets .Va *old to the found value. The .Fn atomic_fetchadd , .Fn atomic_load , .Fn atomic_readandclear , and .Fn atomic_swap functions return the value at the specified address. The .Fn atomic_testandset and .Fn atomic_testandclear function returns the result of the test operation. .Sh EXAMPLES This example uses the .Fn atomic_cmpset_acq_ptr and .Fn atomic_set_ptr functions to obtain a sleep mutex and handle recursion. Since the .Va mtx_lock member of a .Vt "struct mtx" is a pointer, the .Dq Li ptr type is used. .Bd -literal /* Try to obtain mtx_lock once. */ #define _obtain_lock(mp, tid) \\ atomic_cmpset_acq_ptr(&(mp)->mtx_lock, MTX_UNOWNED, (tid)) /* Get a sleep lock, deal with recursion inline. */ #define _get_sleep_lock(mp, tid, opts, file, line) do { \\ uintptr_t _tid = (uintptr_t)(tid); \\ \\ if (!_obtain_lock(mp, tid)) { \\ if (((mp)->mtx_lock & MTX_FLAGMASK) != _tid) \\ _mtx_lock_sleep((mp), _tid, (opts), (file), (line));\\ else { \\ atomic_set_ptr(&(mp)->mtx_lock, MTX_RECURSE); \\ (mp)->mtx_recurse++; \\ } \\ } \\ } while (0) .Ed .Sh HISTORY The .Fn atomic_add , .Fn atomic_clear , .Fn atomic_set , and .Fn atomic_subtract operations were introduced in .Fx 3.0 . Initially, these operations were defined on the types .Dq Li char , .Dq Li short , .Dq Li int , and .Dq Li long . .Pp The .Fn atomic_cmpset , .Fn atomic_load_acq , .Fn atomic_readandclear , and .Fn atomic_store_rel operations were added in .Fx 5.0 . Simultaneously, the acquire and release variants were introduced, and support was added for operation on the types .Dq Li 8 , .Dq Li 16 , .Dq Li 32 , .Dq Li 64 , and .Dq Li ptr . .Pp The .Fn atomic_fetchadd operation was added in .Fx 6.0 . .Pp The .Fn atomic_swap and .Fn atomic_testandset operations were added in .Fx 10.0 . .Pp The .Fn atomic_testandclear and .Fn atomic_thread_fence operations were added in .Fx 11.0 . .Pp The relaxed variants of .Fn atomic_load and .Fn atomic_store were added in .Fx 12.0 . .Pp The .Fn atomic_interrupt_fence operation was added in .Fx 13.0 . diff --git a/share/man/man9/backlight.9 b/share/man/man9/backlight.9 index 5151ab1e91da..322946a76877 100644 --- a/share/man/man9/backlight.9 +++ b/share/man/man9/backlight.9 @@ -1,77 +1,77 @@ .\" Copyright (c) 2020 Emmanuel Vadot .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 2, 2020 .Dt BACKLIGHT 9 .Os .Sh NAME .Nm backlight , .Nm backlight_register , .Nm backlight_destroy , .Nm BACKLIGHT_GET_STATUS , -.Nm BACKLIGHT_SET_STATUS , +.Nm BACKLIGHT_SET_STATUS .Nd BACKLIGHT methods .Sh SYNOPSIS .Cd "device backlight" .In "backlight_if.h" .In "sys/sys/backlight.h" .Ft int .Fn BACKLIGHT_GET_STATUS "device_t bus" "struct backlight_props *props" .Ft int .Fn BACKLIGHT_SET_STATUS "device_t bus" "struct backlight_props *props" .Ft struct cdev * .Fn backlight_register "const char *name" "device_t dev" .Ft int .Fn backlight_destroy "struct cdev *cdev" .Sh DESCRIPTION The backlight driver provides a generic way for handling a panel backlight. .Pp Drivers for backlight system register themselves globally using the .Fn backlight_register function. They must define two methods, .Fn BACKLIGHT_GET_STATUS which is used to query the current brightness level and .Fn BACKLIGHT_SET_STATUS which is used to update it. .Sh INTERFACE .Bl -tag -width indent .It Fn BACKLIGHT_GET_STATUS "device_t bus" "struct backlight_props *props" Driver fills the current brightless level and the optional supported levels. .It Fn BACKLIGHT_SET_STATUS "device_t bus" "struct backlight_props *props" Driver update the backlight level based on the brightness member of the props struct. .El .Sh FILES .Bl -tag -width "/dev/backlight/*" .It Pa /dev/backlight/* .Sh HISTORY The .Nm backlight interface first appear in .Fx 13.0 . The .Nm backlight driver and manual page was written by .An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/share/man/man9/crypto_buffer.9 b/share/man/man9/crypto_buffer.9 index 064c6fbc12e3..7f3839970dfa 100644 --- a/share/man/man9/crypto_buffer.9 +++ b/share/man/man9/crypto_buffer.9 @@ -1,362 +1,362 @@ .\" Copyright (c) 2020, Chelsio Inc .\" .\" 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. Neither the name of the Chelsio Inc nor the names of its .\" contributors may be used to endorse or promote products derived from .\" this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" -.Dd Feburary 11, 2022 +.Dd February 11, 2022 .Dt CRYPTO_BUFFER 9 .Os .Sh NAME .Nm crypto_buffer .Nd symmetric cryptographic request buffers .Sh SYNOPSIS .In opencrypto/cryptodev.h .Ft int .Fo crypto_apply .Fa "struct cryptop *crp" .Fa "int off" .Fa "int len" .Fa "int (*f)(void *, void *, u_int)" .Fa "void *arg" .Fc .Ft int .Fo crypto_apply_buf .Fa "struct crypto_buffer *cb" .Fa "int off" .Fa "int len" .Fa "int (*f)(void *, void *, u_int)" .Fa "void *arg" .Fc .Ft void * .Fo crypto_buffer_contiguous_subsegment .Fa "struct crypto_buffer *cb" .Fa "size_t skip" .Fa "size_t len" .Fc .Ft size_t .Fn crypto_buffer_len "struct crypto_buffer *cb" .Ft void * .Fo crypto_contiguous_subsegment .Fa "struct cryptop *crp" .Fa "size_t skip" .Fa "size_t len" .Fc .Ft void .Fo crypto_cursor_init .Fa "struct crypto_buffer_cursor *cc" .Fa "const struct crypto_buffer *cb" .Fc .Ft void .Fn crypto_cursor_advance "struct crypto_buffer_cursor *cc" "size_t amount" .Ft void .Fo crypto_cursor_copyback .Fa "struct crypto_buffer_cursor *cc" .Fa "int size" .Fa "const void *src" .Fc .Ft void .Fo crypto_cursor_copydata .Fa "struct crypto_buffer_cursor *cc" .Fa "int size" .Fa "void *dst" .Fc .Ft void .Fo crypto_cursor_copydata_noadv .Fa "struct crypto_buffer_cursor *cc" .Fa "int size" .Fa "void *dst" .Fc .Ft void * .Fn crypto_cursor_segment "struct crypto_buffer_cursor *cc" "size_t *len" .Ft void * .Fn crypto_cursor_segbase "struct crypto_buffer_cursor *cc" .Ft size_t .Fn crypto_cursor_seglen "struct crypto_buffer_cursor *cc" .Ft void .Fo crypto_cursor_copy .Fa "const struct crypto_buffer_cursor *fromc" .Fa "struct crypto_buffer_cursor *toc" .Fc .Ft bool .Fn CRYPTO_HAS_OUTPUT_BUFFER "struct cryptop *crp" .Sh DESCRIPTION Symmetric cryptographic requests use data buffers to describe the data to be modified. Requests can either specify a single data buffer whose contents are modified in place, or requests may specify separate data buffers for input and output. .Vt struct crypto_buffer provides an abstraction that permits cryptographic requests to operate on different types of buffers. .Vt struct crypto_cursor allows cryptographic drivers to iterate over a data buffer. .Pp .Fn CRYPTO_HAS_OUTPUT_BUFFER returns true if .Fa crp uses separate buffers for input and output and false if .Fa crp uses a single buffer. .Pp .Fn crypto_buffer_len returns the length of data buffer .Fa cb in bytes. .Pp .Fn crypto_apply_buf invokes a caller-supplied function to a region of the data buffer .Fa cb . The function .Fa f is called one or more times. For each invocation, the first argument to .Fa f is the value of .Fa arg passed to .Fn crypto_apply_buf . The second and third arguments to .Fa f are a pointer and length to a segment of the buffer mapped into the kernel. The function is called enough times to cover the .Fa len bytes of the data buffer which starts at an offset .Fa off . If any invocation of .Fa f returns a non-zero value, .Fn crypto_apply_buf immediately returns that value without invoking .Fa f on any remaining segments of the region, otherwise .Fn crypto_apply_buf returns the value from the final call to .Fa f . .Fn crypto_apply invokes the callback .Fa f on a region of the input data buffer for .Fa crp . .Pp .Fn crypto_buffer_contiguous_subsegment attempts to locate a single, virtually-contiguous segment of the data buffer .Fa cb . The segment must be .Fa len bytes long and start at an offset of .Fa skip bytes. If a segment is found, a pointer to the start of the segment is returned. Otherwise, .Dv NULL is returned. .Fn crypto_contiguous_subsegment attempts to locate a single, virtually-contiguous segment in the input data buffer for .Fa crp . .Ss Data Buffers Data buffers are described by an instance of .Vt struct crypto buffer . The .Fa cb_type member contains the type of the data buffer. The following types are supported: .Bl -tag -width " CRYPTO_BUF_CONTIG" .It Dv CRYPTO_BUF_NONE An invalid buffer. Used to mark the output buffer when a crypto request uses a single data buffer. .It Dv CRYPTO_BUF_CONTIG An array of bytes mapped into the kernel's address space. .It Dv CRYPTO_BUF_UIO A scatter/gather list of kernel buffers as described in .Xr uio 9 . .It Dv CRYPTO_BUF_MBUF A chain of network memory buffers as described in .Xr mbuf 9 . .It Dv CRYPTO_BUF_SINGLE_MBUF A single network memory buffer as described in .Xr mbuf 9 . .It Dv CRYPTO_BUF_VMPAGE A scatter/gather list of .Vt vm_page_t structures describing pages in the kernel's address space. This buffer type is only available if .Dv CRYPTO_HAS_VMPAGE is true. .El .Pp The structure also contains the following type-specific fields: .Bl -tag -width " cb_vm_page_offset" .It Fa cb_buf A pointer to the start of a .Dv CRYPTO_BUF_CONTIG data buffer. .It Fa cb_buf_len The length of a .Dv CRYPTO_BUF_CONTIG data buffer .It Fa cb_mbuf A pointer to a .Vt struct mbuf for .Dv CRYPTO_BUF_MBUF and .Dv CRYPTO_BUF_SINGLE_MBUF . .It Fa cb_uio A pointer to a .Vt struct uio for .Dv CRYPTO_BUF_UIO . .It Fa cb_vm_page A pointer to an array of .Vt struct vm_page for .Dv CRYPTO_BUF_VMPAGE . .It Fa cb_vm_page_len The total amount of data included in the .Fa cb_vm_page array, in bytes. .It Fa cb_vm_page_offset Offset in bytes in the first page of .Fa cb_vm_page where valid data begins. .El .Ss Cursors Cursors provide a mechanism for iterating over a data buffer. They are primarily intended for use in software drivers which access data buffers via virtual addresses. .Pp .Fn crypto_cursor_init initializes the cursor .Fa cc to reference the start of the data buffer .Fa cb . .Pp .Fn crypto_cursor_advance advances the cursor .Fa amount bytes forward in the data buffer. .Pp .Fn crypto_cursor_copyback copies .Fa size bytes from the local buffer pointed to by .Fa src into the data buffer associated with .Fa cc . The bytes are written to the current position of .Fa cc , and the cursor is then advanced by .Fa size bytes. .Pp .Fn crypto_cursor_copydata copies .Fa size bytes out of the data buffer associated with .Fa cc into a local buffer pointed to by .Fa dst . The bytes are read from the current position of .Fa cc , and the cursor is then advanced by .Fa size bytes. .Pp .Fn crypto_cursor_copydata_noadv is similar to .Fn crypto_cursor_copydata except that it does not change the current position of .Fa cc . .Pp .Fn crypto_cursor_segment returns the start of the virtually-contiguous segment at the current position of .Fa cc . The length of the segment is stored in .Fa len . .Pp .Fn crypto_cursor_segbase and .Fn crypto_cursor_seglen return the start and length, respectively, of the virtually-contiguous segment at the current position of .Fa cc . .Sh RETURN VALUES .Fn crypto_apply and .Fn crypto_apply_buf return the return value from the caller-supplied callback function. .Pp .Fn crypto_buffer_contiguous_subsegment , .Fn crypto_contiguous_subsegment , .Fn crypto_cursor_segbase , and .Fn crypto_cursor_segment return a pointer to a contiguous segment or .Dv NULL . .Pp .Fn crypto_buffer_len returns the length of a buffer in bytes. .Pp .Fn crypto_cursor_seglen returns the length in bytes of a contiguous segment. .Pp .Fn crypto_cursor_copy makes a deep copy of the cursor .Fa fromc . The two copies do not share any state and can thus be used independently. .Pp .Fn CRYPTO_HAS_OUTPUT_BUFFER returns true if the request uses a separate output buffer. .Sh SEE ALSO .Xr ipsec 4 , .Xr crypto 7 , .Xr bus_dma 9 , .Xr crypto 9 , .Xr crypto_driver 9 , .Xr crypto_request 9 , .Xr crypto_session 9 , .Xr mbuf 9 , .Xr uio 9 .Sh HISTORY The .Nm functions first appeared in .Fx 13 . .Sh AUTHORS The .Nm functions and this manual page were written by .An John Baldwin Aq Mt jhb@FreeBSD.org . diff --git a/share/man/man9/crypto_driver.9 b/share/man/man9/crypto_driver.9 index 930cc0d8bde4..a6ab8fa92429 100644 --- a/share/man/man9/crypto_driver.9 +++ b/share/man/man9/crypto_driver.9 @@ -1,343 +1,342 @@ .\" Copyright (c) 2020, Chelsio Inc .\" .\" 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. Neither the name of the Chelsio Inc nor the names of its .\" contributors may be used to endorse or promote products derived from .\" this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd June 9, 2020 .Dt CRYPTO_DRIVER 9 .Os .Sh NAME .Nm crypto_driver .Nd interface for symmetric cryptographic drivers .Sh SYNOPSIS .In opencrypto/cryptodev.h .Ft void .Fn crypto_copyback "struct cryptop *crp" "int off" "int size" "const void *src" .Ft void .Fn crypto_copydata "struct cryptop *crp" "int off" "int size" "void *dst" .Ft void .Fn crypto_done "struct cryptop *crp" .Ft int32_t .Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags" .Ft void * .Fn crypto_get_driver_session "crypto_session_t crypto_session" .Ft void .Fn crypto_read_iv "struct cryptop *crp" "void *iv" .Ft int .Fn crypto_unblock "uint32_t driverid" "int what" .Ft int .Fn crypto_unregister_all "uint32_t driverid" .Ft int .Fn CRYPTODEV_FREESESSION "device_t dev" "crypto_session_t crypto_session" .Ft int .Fo CRYPTODEV_NEWSESSION .Fa "device_t dev" .Fa "crypto_session_t crypto_session" .Fa "const struct crypto_session_params *csp" .Fc .Ft int .Fo CRYPTODEV_PROBESESSION .Fa "device_t dev" .Fa "const struct crypto_session_params *csp" .Fc .Ft int .Fn CRYPTODEV_PROCESS "device_t dev" "struct cryptop *crp" "int flags" .Ft void .Fo hmac_init_ipad .Fa "struct auth_hash *axf" .Fa "const char *key" .Fa "int klen" .Fa "void *auth_ctx" .Fc .Ft void .Fo hmac_init_opad .Fa "struct auth_hash *axf" .Fa "const char *key" .Fa "int klen" .Fa "void *auth_ctx" .Fc .Sh DESCRIPTION Symmetric cryptographic drivers process cryptographic requests submitted to sessions associated with the driver. .Pp Cryptographic drivers call .Fn crypto_get_driverid to register with the cryptographic framework. .Fa dev is the device used to service requests. The .Fn CRYPTODEV methods are defined in the method table for the device driver attached to .Fa dev . .Fa session_size specifies the size of a driver-specific per-session structure allocated by the cryptographic framework. .Fa flags is a bitmask of properties about the driver. Exactly one of .Dv CRYPTOCAP_F_SOFTWARE or .Dv CRYPTOCAP_F_HARDWARE must be specified. .Dv CRYPTOCAP_F_SOFTWARE should be used for drivers which process requests using host CPUs. .Dv CRYPTOCAP_F_HARDWARE should be used for drivers which process requests on separate co-processors. .Dv CRYPTOCAP_F_SYNC should be set for drivers which process requests synchronously in .Fn CRYPTODEV_PROCESS . .Dv CRYPTOCAP_F_ACCEL_SOFTWARE should be set for software drivers which use accelerated CPU instructions. .Fn crypto_get_driverid returns an opaque driver id. .Pp .Fn crypto_unregister_all unregisters a driver from the cryptographic framework. If there are any pending operations or open sessions, this function will sleep. .Fa driverid is the value returned by an earlier call to .Fn crypto_get_driverid . .Pp When a new session is created by .Fn crypto_newsession , .Fn CRYPTODEV_PROBESESSION is invoked by the cryptographic framework on each active driver to determine the best driver to use for the session. This method should inspect the session parameters in .Fa csp . If a driver does not support requests described by .Fa csp , this method should return an error value. If the driver does support requests described by .Fa csp , it should return a negative value. The framework prefers drivers with the largest negative value, similar to .Xr DEVICE_PROBE 9 . The following values are defined for non-error return values from this method: .Bl -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE" .It Dv CRYPTODEV_PROBE_HARDWARE The driver processes requests via a co-processor. .It Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE The driver processes requests on the host CPU using optimized instructions such as AES-NI. .It Dv CRYPTODEV_PROBE_SOFTWARE The driver processes requests on the host CPU. .El .Pp This method should not sleep. .Pp Once the framework has chosen a driver for a session, the framework invokes the .Fn CRYPTODEV_NEWSESSION method to initialize driver-specific session state. Prior to calling this method, the framework allocates a per-session driver-specific data structure. This structure is initialized with zeroes, and its size is set by the .Fa session_size passed to .Fn crypto_get_driverid . This method can retrieve a pointer to this data structure by passing .Fa crypto_session to .Fn crypto_get_driver_session . Session parameters are described in .Fa csp . .Pp This method should not sleep. .Pp .Fn CRYPTODEV_FREESESSION is invoked to release any driver-specific state when a session is destroyed. The per-session driver-specific data structure is explicitly zeroed and freed by the framework after this method returns. If a driver requires no additional tear-down steps, it can leave this method undefined. .Pp This method should not sleep. .Pp .Fn CRYPTODEV_PROCESS is invoked for each request submitted to an active session. This method can either complete a request synchronously or schedule it to be completed asynchronously, but it must not sleep. .Pp If this method is not able to complete a request due to insufficient resources such as a full command queue, it can defer the request by returning .Dv ERESTART . The request will be queued by the framework and retried once the driver releases pending requests via .Fn crypto_unblock . Any requests submitted to sessions belonging to the driver will also be queued until .Fn crypto_unblock is called. .Pp If a driver encounters errors while processing a request, it should report them via the .Fa crp_etype field of .Fa crp rather than returning an error directly. .Pp .Fa flags may be set to .Dv CRYPTO_HINT_MORE if there are additional requests queued for this driver. The driver can use this as a hint to batch completion interrupts. Note that these additional requests may be from different sessions. .Pp .Fn crypto_get_driver_session returns a pointer to the driver-specific per-session data structure for the session .Fa crypto_session . This function can be used in the .Fn CRYPTODEV_NEWSESSION , .Fn CRYPTODEV_PROCESS , and .Fn CRYPTODEV_FREESESSION callbacks. .Pp .Fn crypto_copydata copies .Fa size bytes out of the input buffer for .Fa crp into a local buffer pointed to by .Fa dst . The bytes are read starting at an offset of .Fa off bytes in the request's input buffer. .Pp .Fn crypto_copyback copies .Fa size bytes from the local buffer pointed to by .Fa src into the output buffer for .Fa crp . The bytes are written starting at an offset of .Fa off bytes in the request's output buffer. .Pp .Fn crypto_read_iv copies the IV or nonce for .Fa crp into the local buffer pointed to by .Fa iv . .Pp A driver calls .Fn crypto_done to mark the request .Fa crp as completed. Any errors should be set in .Fa crp_etype prior to calling this function. .Pp If a driver defers a request by returning .Dv ERESTART from .Dv CRYPTO_PROCESS , the framework will queue all requests for the driver until the driver calls .Fn crypto_unblock to indicate that the temporary resource shortage has been relieved. For example, if a driver returns .Dv ERESTART due to a full command ring, it would invoke .Fn crypto_unblock from a command completion interrupt that makes a command ring entry available. .Fa driverid is the value returned by .Fn crypto_get_driverid . .Fa what indicates which types of requests the driver is able to handle again: .Bl -tag -width "CRYPTO_ASYMQ" .It Dv CRYPTO_SYMQ indicates that the driver is able to handle symmetric requests passed to .Fn CRYPTODEV_PROCESS . .It Dv CRYPTO_ASYMQ indicates that the driver is able to handle asymmetric requests passed to .Fn CRYPTODEV_KPROCESS . .El .Pp -.Pp .Fn hmac_init_ipad prepares an authentication context to generate the inner hash of an HMAC. .Fa axf is a software implementation of an authentication algorithm such as the value returned by .Fn crypto_auth_hash . .Fa key is a pointer to a HMAC key of .Fa klen bytes. .Fa auth_ctx points to a valid authentication context for the desired algorithm. The function initializes the context with the supplied key. .Pp .Fn hmac_init_opad is similar to .Fn hmac_init_ipad except that it prepares an authentication context to generate the outer hash of an HMAC. .Sh RETURN VALUES .Fn crypto_apply returns the return value from the caller-supplied callback function. .Pp .Fn crypto_contiguous_subsegment returns a pointer to a contiguous segment or .Dv NULL . .Pp .Fn crypto_get_driverid returns a driver identifier on success or -1 on error. .Pp .Fn crypto_unblock , .Fn crypto_unregister_all , .Fn CRYPTODEV_FREESESSION , .Fn CRYPTODEV_NEWSESSION , and .Fn CRYPTODEV_PROCESS return zero on success or an error on failure. .Pp .Fn CRYPTODEV_PROBESESSION returns a negative value on success or an error on failure. .Sh SEE ALSO .Xr crypto 7 , .Xr crypto 9 , .Xr crypto_buffer 9 , .Xr crypto_request 9 , .Xr crypto_session 9 diff --git a/share/man/man9/crypto_request.9 b/share/man/man9/crypto_request.9 index 18012adc4322..a28cd33c2956 100644 --- a/share/man/man9/crypto_request.9 +++ b/share/man/man9/crypto_request.9 @@ -1,548 +1,547 @@ .\" Copyright (c) 2020, Chelsio Inc .\" .\" 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. Neither the name of the Chelsio Inc nor the names of its .\" contributors may be used to endorse or promote products derived from .\" this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd January 4, 2022 .Dt CRYPTO_REQUEST 9 .Os .Sh NAME .Nm crypto_request .Nd symmetric cryptographic operations .Sh SYNOPSIS .In opencrypto/cryptodev.h .Ft "struct cryptop *" .Fn crypto_clonereq "crypto_session_t cses" "struct cryptop *crp" "int how" .Ft int .Fn crypto_dispatch "struct cryptop *crp" .Ft void .Fn crypto_destroyreq "struct cryptop *crp" .Ft void .Fn crypto_freereq "struct cryptop *crp" .Ft "struct cryptop *" .Fn crypto_getreq "crypto_session_t cses" "int how" .Ft void .Fn crypto_initreq "crypto_session_t cses" "int how" .Ft void .Fn crypto_use_buf "struct cryptop *crp" "void *buf" "int len" .Ft void .Fn crypto_use_mbuf "struct cryptop *crp" "struct mbuf *m" .Ft void .Fn crypto_use_uio "struct cryptop *crp" "struct uio *uio" .Ft void .Fn crypto_use_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset" .Ft void .Fn crypto_use_output_buf "struct cryptop *crp" "void *buf" "int len" .Ft void .Fn crypto_use_output_mbuf "struct cryptop *crp" "struct mbuf *m" .Ft void .Fn crypto_use_output_uio "struct cryptop *crp" "struct uio *uio" .Ft void .Fn crypto_use_output_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset" .Sh DESCRIPTION Each symmetric cryptographic operation in the kernel is described by an instance of .Vt struct cryptop and is associated with an active session. .Pp Requests can either be allocated dynamically or use caller-supplied storage. Dynamically allocated requests should be allocated by either .Fn crypto_getreq or .Fn crypto_clonereq , and freed by .Fn crypto_freereq once the request has completed. Requests using caller-supplied storage should be initialized by .Fn crypto_initreq at the start of each operation and destroyed by .Fn crypto_destroyreq once the request has completed. .Pp For .Fn crypto_clonereq , .Fn crypto_getreq , and .Fn crypto_initreq , .Fa cses is a reference to an active session. For .Fn crypto_clonereq and .Fn crypto_getreq , .Fa how is passed to .Xr malloc 9 and should be set to either .Dv M_NOWAIT or .Dv M_WAITOK . .Pp .Fn crypto_clonereq allocates a new request that inherits request inputs such as request buffers from the original .Fa crp request. However, the new request is associated with the .Fa cses session rather than inheriting the session from .Fa crp . .Fa crp must not be a completed request. .Pp Once a request has been initialized, the caller should set fields in the structure to describe request-specific parameters. Unused fields should be left as-is. .Pp .Fn crypto_dispatch passes a crypto request to the driver attached to the request's session. If there are errors in the request's fields, this function may return an error to the caller. If errors are encountered while servicing the request, they will instead be reported to the request's callback function .Pq Fa crp_callback via .Fa crp_etype . .Pp Note that a request's callback function may be invoked before .Fn crypto_dispatch returns. .Pp Once a request has signaled completion by invoking its callback function, it should be freed via .Fn crypto_destroyreq or .Fn crypto_freereq . .Pp Cryptographic operations include several fields to describe the request. .Ss Request Buffers Requests can either specify a single data buffer that is modified in place .Po .Fa crp_buf .Pc or separate input .Po .Fa crp_buf .Pc and output .Po .Fa crp_obuf .Pc buffers. Note that separate input and output buffers are not supported for compression mode requests. .Pp All requests must have a valid .Fa crp_buf initialized by one of the following functions: .Bl -tag -width "Fn crypto_use_vmpage" .It Fn crypto_use_buf Uses an array of .Fa len bytes pointed to by .Fa buf as the data buffer. .It Fn crypto_use_mbuf Uses the network memory buffer .Fa m as the data buffer. .It Fn crypto_use_uio Uses the scatter/gather list .Fa uio as the data buffer. .It Fn crypto_use_vmpage Uses the array of .Vt vm_page_t structures as the data buffer. .El .Pp One of the following functions should be used to initialize .Fa crp_obuf for requests that use separate input and output buffers: .Bl -tag -width "Fn crypto_use_output_vmpage" .It Fn crypto_use_output_buf Uses an array of .Fa len bytes pointed to by .Fa buf as the output buffer. .It Fn crypto_use_output_mbuf Uses the network memory buffer .Fa m as the output buffer. .It Fn crypto_use_output_uio Uses the scatter/gather list .Fa uio as the output buffer. .It Fn crypto_use_output_vmpage Uses the array of .Vt vm_page_t structures as the output buffer. .El .Ss Request Regions Each request describes one or more regions in the data buffers. Each region is described by an offset relative to the start of a data buffer and a length. The length of some regions is the same for all requests belonging to a session. Those lengths are set in the session parameters of the associated session. All requests must define a payload region. Other regions are only required for specific session modes. .Pp For requests with separate input and output data buffers, the AAD, IV, and payload regions are always defined as regions in the input buffer, and a separate payload output region is defined to hold the output of encryption or decryption in the output buffer. The digest region describes a region in the input data buffer for requests that verify an existing digest. For requests that compute a digest, the digest region describes a region in the output data buffer. Note that the only data written to the output buffer is the encryption or decryption result and any computed digest. AAD and IV regions are not copied from the input buffer into the output buffer but are only used as inputs. .Pp The following regions are defined: .Bl -column "Payload Output" "Input/Output" .It Sy Region Ta Sy Buffer Ta Sy Description .It AAD Ta Input Ta Embedded Additional Authenticated Data .It IV Ta Input Ta Embedded IV or nonce .It Payload Ta Input Ta Data to encrypt, decrypt, compress, or decompress .It Payload Output Ta Output Ta Encrypted or decrypted data .It Digest Ta Input/Output Ta Authentication digest, hash, or tag .El .Bl -column "Payload Output" ".Fa crp_payload_output_start" .It Sy Region Ta Sy Start Ta Sy Length .It AAD Ta Fa crp_aad_start Ta Fa crp_aad_length .It IV Ta Fa crp_iv_start Ta Fa csp_ivlen .It Payload Ta Fa crp_payload_start Ta Fa crp_payload_length .It Payload Output Ta Fa crp_payload_output_start Ta Fa crp_payload_length .It Digest Ta Fa crp_digest_start Ta Fa csp_auth_mlen .El .Pp Requests are permitted to operate on only a subset of the data buffer. For example, requests from IPsec operate on network packets that include headers not used as either additional authentication data (AAD) or payload data. .Ss Request Operations All requests must specify the type of operation to perform in .Fa crp_op . Available operations depend on the session's mode. .Pp Compression requests support the following operations: .Bl -tag -width CRYPTO_OP_DECOMPRESS .It Dv CRYPTO_OP_COMPRESS Compress the data in the payload region of the data buffer. .It Dv CRYPTO_OP_DECOMPRESS Decompress the data in the payload region of the data buffer. .El .Pp Cipher requests support the following operations: .Bl -tag -width CRYPTO_OP_DECRYPT .It Dv CRYPTO_OP_ENCRYPT Encrypt the data in the payload region of the data buffer. .It Dv CRYPTO_OP_DECRYPT Decrypt the data in the payload region of the data buffer. .El .Pp Digest requests support the following operations: .Bl -tag -width CRYPTO_OP_COMPUTE_DIGEST .It Dv CRYPTO_OP_COMPUTE_DIGEST Calculate a digest over the payload region of the data buffer and store the result in the digest region. .It Dv CRYPTO_OP_VERIFY_DIGEST Calculate a digest over the payload region of the data buffer. Compare the calculated digest to the existing digest from the digest region. If the digests match, complete the request successfully. If the digests do not match, fail the request with .Er EBADMSG . .El .Pp AEAD and Encrypt-then-Authenticate requests support the following operations: .Bl -tag -width CRYPTO_OP .It Dv CRYPTO_OP_ENCRYPT | Dv CRYPTO_OP_COMPUTE_DIGEST Encrypt the data in the payload region of the data buffer. Calculate a digest over the AAD and payload regions and store the result in the data buffer. .It Dv CRYPTO_OP_DECRYPT | Dv CRYPTO_OP_VERIFY_DIGEST Calculate a digest over the AAD and payload regions of the data buffer. Compare the calculated digest to the existing digest from the digest region. If the digests match, decrypt the payload region. If the digests do not match, fail the request with .Er EBADMSG . .El .Ss Request AAD AEAD and Encrypt-then-Authenticate requests may optionally include Additional Authenticated Data. AAD may either be supplied in the AAD region of the input buffer or as a single buffer pointed to by .Fa crp_aad . In either case, .Fa crp_aad_length always indicates the amount of AAD in bytes. .Ss Request ESN IPsec requests may optionally include Extended Sequence Numbers (ESN). ESN may either be supplied in .Fa crp_esn or as part of the AAD pointed to by .Fa crp_aad . .Pp If the ESN is stored in .Fa crp_esn , .Dv CSP_F_ESN should be set in .Fa csp_flags . This use case is dedicated for encrypt and authenticate mode, since the high-order 32 bits of the sequence number are appended after the Next Header (RFC 4303). .Pp AEAD modes supply the ESN in a separate AAD buffer (see e.g. RFC 4106, Chapter 5 AAD Construction). .Ss Request IV and/or Nonce Some cryptographic operations require an IV or nonce as an input. An IV may be stored either in the IV region of the data buffer or in .Fa crp_iv . By default, the IV is assumed to be stored in the IV region. If the IV is stored in .Fa crp_iv , .Dv CRYPTO_F_IV_SEPARATE should be set in .Fa crp_flags and .Fa crp_iv_start should be left as zero. .Pp Requests that store part, but not all, of the IV in the data buffer should store the partial IV in the data buffer and pass the full IV separately in .Fa crp_iv . .Ss Request and Callback Scheduling The crypto framework provides multiple methods of scheduling the dispatch of requests to drivers along with the processing of driver callbacks. Requests use flags in .Fa crp_flags to select the desired scheduling methods. .Pp .Fn crypto_dispatch can pass the request to the session's driver via three different methods: .Bl -enum .It The request is queued to a taskqueue backed by a pool of worker threads. By default the pool is sized to provide one thread for each CPU. Worker threads dequeue requests and pass them to the driver asynchronously. .It The request is passed to the driver synchronously in the context of the thread invoking .Fn crypto_dispatch . .It The request is queued to a queue of pending requests. A single worker thread dequeues requests and passes them to the driver asynchronously. .El .Pp To select the first method (taskqueue backed by multiple threads), requests should set .Dv CRYPTO_F_ASYNC . To always use the third method (queue to single worker thread), requests should set .Dv CRYPTO_F_BATCH . If both flags are set, .Dv CRYPTO_F_ASYNC takes precedence. If neither flag is set, .Fn crypto_dispatch will first attempt the second method (invoke driver synchronously). If the driver is blocked, the request will be queued using the third method. One caveat is that the first method is only used for requests using software drivers which use host CPUs to process requests. Requests whose session is associated with a hardware driver will ignore .Dv CRYPTO_F_ASYNC and only use .Dv CRYPTO_F_BATCH to determine how requests should be scheduled. .Pp In addition to bypassing synchronous dispatch in .Fn crypto_dispatch , .Dv CRYPTO_F_BATCH requests additional changes aimed at optimizing batches of requests to the same driver. When the worker thread processes a request with .Dv CRYPTO_F_BATCH , it will search the pending request queue for any other requests for the same driver, including requests from different sessions. If any other requests are present, .Dv CRYPTO_HINT_MORE is passed to the driver's process method. Drivers may use this to batch completion interrupts. .Pp Callback function scheduling is simpler than request scheduling. Callbacks can either be invoked synchronously from .Fn crypto_done , or they can be queued to a pool of worker threads. This pool of worker threads is also sized to provide one worker thread for each CPU by default. Note that a callback function invoked synchronously from .Fn crypto_done must follow the same restrictions placed on threaded interrupt handlers. .Pp By default, callbacks are invoked asynchronously by a worker thread. If .Dv CRYPTO_F_CBIMM is set, the callback is always invoked synchronously from .Fn crypto_done . If .Dv CRYPTO_F_CBIFSYNC is set, the callback is invoked synchronously if the request was processed by a software driver or asynchronously if the request was processed by a hardware driver. .Pp If a request was scheduled to the taskqueue via .Dv CRYPTO_F_ASYNC , callbacks are always invoked asynchronously ignoring .Dv CRYPTO_F_CBIMM and .Dv CRYPTO_F_CBIFSYNC . In this case, .Dv CRYPTO_F_ASYNC_KEEPORDER may be set to ensure that callbacks for requests on a given session are invoked in the same order that requests were queued to the session via .Fn crypto_dispatch . This flag is used by IPsec to ensure that decrypted network packets are passed up the network stack in roughly the same order they were received. -.Pp .Ss Other Request Fields In addition to the fields and flags enumerated above, .Vt struct cryptop includes the following: .Bl -tag -width crp_payload_length .It Fa crp_session A reference to the active session. This is set when the request is created by .Fn crypto_getreq and should not be modified. Drivers can use this to fetch driver-specific session state or session parameters. .It Fa crp_etype Error status. Either zero on success, or an error if a request fails. Set by drivers prior to completing a request via .Fn crypto_done . .It Fa crp_flags A bitmask of flags. The following flags are available in addition to flags discussed previously: .Bl -tag -width CRYPTO_F_DONE .It Dv CRYPTO_F_DONE Set by .Fa crypto_done before calling .Fa crp_callback . This flag is not very useful and will likely be removed in the future. It can only be safely checked from the callback routine at which point it is always set. .El .It Fa crp_cipher_key Pointer to a request-specific encryption key. If this value is not set, the request uses the session encryption key. .It Fa crp_auth_key Pointer to a request-specific authentication key. If this value is not set, the request uses the session authentication key. .It Fa crp_opaque An opaque pointer. This pointer permits users of the cryptographic framework to store information about a request to be used in the callback. .It Fa crp_callback Callback function. This must point to a callback function of type .Vt void (*)(struct cryptop *) . The callback function should inspect .Fa crp_etype to determine the status of the completed operation. It should also arrange for the request to be freed via .Fn crypto_freereq . .It Fa crp_olen Used with compression and decompression requests to describe the updated length of the payload region in the data buffer. .Pp If a compression request increases the size of the payload, then the data buffer is unmodified, the request completes successfully, and .Fa crp_olen is set to the size the compressed data would have used. Callers can compare this to the payload region length to determine if the compressed data was discarded. .El .Sh RETURN VALUES .Fn crypto_dispatch returns an error if the request contained invalid fields, or zero if the request was valid. .Fn crypto_getreq returns a pointer to a new request structure on success, or .Dv NULL on failure. .Dv NULL can only be returned if .Dv M_NOWAIT was passed in .Fa how . .Sh SEE ALSO .Xr ipsec 4 , .Xr crypto 7 , .Xr crypto 9 , .Xr crypto_session 9 , -.Xr mbuf 9 +.Xr mbuf 9 , .Xr uio 9 .Sh BUGS Not all drivers properly handle mixing session and per-request keys within a single session. Consumers should either use a single key for a session specified in the session parameters or always use per-request keys. diff --git a/share/man/man9/dev_refthread.9 b/share/man/man9/dev_refthread.9 index 74e8d69d150c..c6aa7d955230 100644 --- a/share/man/man9/dev_refthread.9 +++ b/share/man/man9/dev_refthread.9 @@ -1,153 +1,153 @@ .\" Copyright (c) 2018 Conrad Meyer .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 29, 2018 .Dt DEV_REFTHREAD 9 .Os .Sh NAME .Nm dev_refthread , .Nm devvn_refthread , .Nm dev_relthread .Nd safely access device methods .Sh SYNOPSIS .In sys/param.h .In sys/conf.h .Ft "struct cdevsw *" .Fn dev_refthread "struct cdev *dev" "int *ref" .Ft "struct cdevsw *" .Fn devvn_refthread "struct vnode *vp" "struct cdev **devp" "int *ref" .Ft void .Fn dev_relthread "struct cdev *dev" "int ref" .Sh DESCRIPTION The .Fn dev_refthread (or .Fn devvn_refthread ) and .Fn dev_relthread routines provide a safe way to access .Xr devfs 5 devices that may be concurrently destroyed by .Fn destroy_dev (e.g., removable media). .Pp If successful, .Fn dev_refthread and .Fn devvn_refthread acquire a "thread reference" to the associated .Vt "struct cdev" and return a non-NULL pointer to the cdev's .Vt "struct cdevsw" method table. For the duration of that reference, the cdev's associated private data and method table object are valid. Destruction of the cdev sleeps until the thread reference is released. .Pp A reference cannot prevent media removal. It is an implementation detail of individual drivers how method calls from callers with .Fn dev_refthread references are handled when the device is pending destruction. A common behavior for disk devices is to return the .Er ENXIO status, but that is not required by this KPI. .Pp The .Fn devvn_refthread variant of .Fn dev_refthread extracts the .Vt "struct cdev" pointer out of the .Dv VCHR .Xr vnode 9 automatically before performing the same actions as .Fn dev_refthread . Additionally, a pointer to the .Vt "struct cdev" is returned to the caller via .Fa "*devp" . .Fn devvn_refthread correctly handles possible parallel reclamation of the vnode. .Pp .Fn dev_relthread is used to release a reference to a .Vt "struct cdev" . .Fn dev_relthread .Sy must only be invoked when the associated invocation of .Fn dev_refthread or .Fn devvn_refthread returned a non-NULL .Vt "struct cdevsw *" . .Sh CONTEXT .Vt struct cdev objects have two reference counts, .Va si_refcount and .Va si_threadcount . The .Fn dev_refthread , .Fn devvn_refthread , and .Fn dev_relthread functions manipulate the .Va si_threadcount . The .Va si_threadcount reference guarantees the liveness of the .Vt struct cdev object. The other .Va si_refcount reference provides only the weaker guarantee that the memory backing the .Vt struct cdev has not been freed. .Sh RETURN VALUES If .Fn dev_refthread or .Fn devvn_refthread are unsuccessful, they return .Dv NULL . .Bf Em If these routines are unsuccessful, they do not increment the .Vt "struct cdev" .Va si_threadcount and do not initialize the value pointed to by the .Fa "*ref" parameter in any way. .Ef .Sh SEE ALSO -.Xr destroy_dev 9 , -.Xr devfs 5 +.Xr devfs 5 , +.Xr destroy_dev 9 .Sh CAVEATS Do not invoke .Fn dev_relthread unless the matching refthread routine succeeded! diff --git a/share/man/man9/drbr.9 b/share/man/man9/drbr.9 index eebc3a7df157..9c641cd0e841 100644 --- a/share/man/man9/drbr.9 +++ b/share/man/man9/drbr.9 @@ -1,140 +1,140 @@ .\" Copyright (c) 2009 Bitgravity Inc .\" Written by: Kip Macy .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 27, 2012 .Dt DRBR 9 .Os .Sh NAME .Nm drbr , .Nm drbr_free , .Nm drbr_enqueue , .Nm drbr_dequeue , .Nm drbr_dequeue_cond , .Nm drbr_flush , .Nm drbr_empty , -.Nm drbr_inuse , +.Nm drbr_inuse .Nd network driver interface to buf_ring .Sh SYNOPSIS .In sys/param.h .In net/if.h .In net/if_var.h .Ft void .Fn drbr_free "struct buf_ring *br" "struct malloc_type *type" .Ft int .Fn drbr_enqueue "struct ifnet *ifp" "struct buf_ring *br" "struct mbuf *m" .Ft struct mbuf * .Fn drbr_dequeue "struct ifnet *ifp" "struct buf_ring *br" .Ft struct mbuf * .Fn drbr_dequeue_cond "struct ifnet *ifp" "struct buf_ring *br" "int (*func) (struct mbuf *, void *)" "void *arg" .Ft void .Fn drbr_flush "struct ifnet *ifp" "struct buf_ring *br" .Ft int .Fn drbr_empty "struct ifnet *ifp" "struct buf_ring *br" .Ft int .Fn drbr_inuse "struct ifnet *ifp" "struct buf_ring *br" .Sh DESCRIPTION The .Nm functions provide an API to network drivers for using .Xr buf_ring 9 for enqueueing and dequeueing packets. This is meant as a replacement for the IFQ interface for packet queuing. It allows a packet to be enqueued with a single atomic and packet dequeue to be done without any per-packet atomics as it is protected by the driver's tx queue lock. If .Dv INVARIANTS is enabled, .Fn drbr_dequeue will assert that the tx queue lock is held when it is called. .Pp The .Fn drbr_free function frees all the enqueued mbufs and then frees the buf_ring. .Pp The .Fn drbr_enqueue function is used to enqueue an mbuf to a buf_ring, falling back to the ifnet's IFQ if .Xr ALTQ 4 is enabled. .Pp The .Fn drbr_dequeue function is used to dequeue an mbuf from a buf_ring or, if .Xr ALTQ 4 is enabled, from the ifnet's IFQ. .Pp The .Fn drbr_dequeue_cond function is used to conditionally dequeue an mbuf from a buf_ring based on whether .Fa func returns .Dv TRUE or .Dv FALSE . .Pp The .Fn drbr_flush function frees all mbufs enqueued in the buf_ring and the ifnet's IFQ. .Pp The .Fn drbr_empty function returns .Dv TRUE if there are no mbufs enqueued, .Dv FALSE otherwise. .Pp The .Fn drbr_inuse function returns the number of mbufs enqueued. Note to users that this is intrinsically racy as there is no guarantee that there will not be more mbufs when .Fn drbr_dequeue is actually called. Provided the tx queue lock is held there will not be less. .Sh RETURN VALUES The .Fn drbr_enqueue function returns .Er ENOBUFS if there are no slots available in the buf_ring and .Dv 0 on success. .Pp The .Fn drbr_dequeue and .Fn drbr_dequeue_cond functions return an mbuf on success and .Dv NULL if the buf_ring is empty. .Sh HISTORY These functions were introduced in .Fx 8.0 . diff --git a/share/man/man9/epoch.9 b/share/man/man9/epoch.9 index e81b715f872a..1f191211b041 100644 --- a/share/man/man9/epoch.9 +++ b/share/man/man9/epoch.9 @@ -1,296 +1,296 @@ .\" .\" Copyright (C) 2018 Matthew Macy . .\" .\" 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(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), 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 COPYRIGHT HOLDER(S) ``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 COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 30, 2020 .Dt EPOCH 9 .Os .Sh NAME .Nm epoch , .Nm epoch_context , .Nm epoch_alloc , .Nm epoch_free , .Nm epoch_enter , .Nm epoch_exit , .Nm epoch_wait , .Nm epoch_enter_preempt , .Nm epoch_exit_preempt , .Nm epoch_wait_preempt , .Nm epoch_call , .Nm epoch_drain_callbacks , .Nm in_epoch , -.Nm in_epoch_verbose , +.Nm in_epoch_verbose .Nd kernel epoch based reclamation .Sh SYNOPSIS .In sys/param.h .In sys/proc.h .In sys/epoch.h .\" Types .Bd -literal struct epoch; /* Opaque */ .Ed .Vt typedef "struct epoch *epoch_t" ; .Bd -literal struct epoch_context { void *data[2]; }; .Ed .Vt typedef "struct epoch_context *epoch_context_t" ; .Vt typedef "void epoch_callback_t(epoch_context_t)" ; .Bd -literal struct epoch_tracker; /* Opaque */ .Ed .Vt typedef "struct epoch_tracker *epoch_tracker_t" ; .\" Declarations .Ft epoch_t .Fn epoch_alloc "const char *name" "int flags" .Ft void .Fn epoch_free "epoch_t epoch" .Ft void .Fn epoch_enter "epoch_t epoch" .Ft void .Fn epoch_exit "epoch_t epoch" .Ft void .Fn epoch_wait "epoch_t epoch" .Ft void .Fn epoch_enter_preempt "epoch_t epoch" "epoch_tracker_t et" .Ft void .Fn epoch_exit_preempt "epoch_t epoch" "epoch_tracker_t et" .Ft void .Fn epoch_wait_preempt "epoch_t epoch" .Ft void .Fn epoch_call "epoch_t epoch" "epoch_callback_t callback" "epoch_context_t ctx" .Ft void .Fn epoch_drain_callbacks "epoch_t epoch" .Ft int .Fn in_epoch "epoch_t epoch" .Ft int .Fn in_epoch_verbose "epoch_t epoch" "int dump_onfail" .Sh DESCRIPTION Epochs are used to guarantee liveness and immutability of data by deferring reclamation and mutation until a grace period has elapsed. Epochs do not have any lock ordering issues. Entering and leaving an epoch section will never block. .Pp Epochs are allocated with .Fn epoch_alloc . The .Fa name argument is used for debugging convenience when the .Cd EPOCH_TRACE kernel option is configured. By default, epochs do not allow preemption during sections. By default mutexes cannot be held across .Fn epoch_wait_preempt . The .Fa flags specified are formed by .Em OR Ns 'ing the following values: .Bl -tag -offset indent -width Ds .It Dv EPOCH_LOCKED Permit holding mutexes across .Fn epoch_wait_preempt (requires .Dv EPOCH_PREEMPT ) . When doing this one must be cautious of creating a situation where a deadlock is possible. .It Dv EPOCH_PREEMPT The .Vt epoch will allow preemption during sections. Only non-sleepable locks may be acquired during a preemptible epoch. The functions .Fn epoch_enter_preempt , .Fn epoch_exit_preempt , and .Fn epoch_wait_preempt must be used in place of .Fn epoch_enter , .Fn epoch_exit , and .Fn epoch_wait , respectively. .El .Pp .Vt epoch Ns s are freed with .Fn epoch_free . .Pp Threads indicate the start of an epoch critical section by calling .Fn epoch_enter (or .Fn epoch_enter_preempt for preemptible epochs). Threads call .Fn epoch_exit (or .Fn epoch_exit_preempt for preemptible epochs) to indicate the end of a critical section. .Vt struct epoch_tracker Ns s are stack objects whose pointers are passed to .Fn epoch_enter_preempt and .Fn epoch_exit_preempt (much like .Vt struct rm_priotracker ) . .Pp Threads can defer work until a grace period has expired since any thread has entered the epoch either synchronously or asynchronously. .Fn epoch_call defers work asynchronously by invoking the provided .Fa callback at a later time. .Fn epoch_wait (or .Fn epoch_wait_preempt ) blocks the current thread until the grace period has expired and the work can be done safely. .Pp Default, non-preemptible epoch wait .Fn ( epoch_wait ) is guaranteed to have much shorter completion times relative to preemptible epoch wait .Fn ( epoch_wait_preempt ) . (In the default type, none of the threads in an epoch section will be preempted before completing its section.) .Pp INVARIANTS can assert that a thread is in an epoch by using .Fn in_epoch . .Fn in_epoch "epoch" is equivalent to invoking .Fn in_epoch_verbose "epoch" "0" . If .Cd EPOCH_TRACE is enabled, .Fn in_epoch_verbose "epoch" "1" provides additional verbose debugging information. .Pp The epoch API currently does not support sleeping in epoch_preempt sections. A caller should never call .Fn epoch_wait in the middle of an epoch section for the same epoch as this will lead to a deadlock. .Pp The .Fn epoch_drain_callbacks function is used to drain all pending callbacks which have been invoked by prior .Fn epoch_call function calls on the same epoch. This function is useful when there are shared memory structure(s) referred to by the epoch callback(s) which are not refcounted and are rarely freed. The typical place for calling this function is right before freeing or invalidating the shared resource(s) used by the epoch callback(s). This function can sleep and is not optimized for performance. .Sh RETURN VALUES .Fn in_epoch curepoch will return 1 if curthread is in curepoch, 0 otherwise. .Sh EXAMPLES Async free example: Thread 1: .Bd -literal int in_pcbladdr(struct inpcb *inp, struct in_addr *faddr, struct in_laddr *laddr, struct ucred *cred) { /* ... */ epoch_enter(net_epoch); CK_STAILQ_FOREACH(ifa, &ifp->if_addrhead, ifa_link) { sa = ifa->ifa_addr; if (sa->sa_family != AF_INET) continue; sin = (struct sockaddr_in *)sa; if (prison_check_ip4(cred, &sin->sin_addr) == 0) { ia = (struct in_ifaddr *)ifa; break; } } epoch_exit(net_epoch); /* ... */ } .Ed Thread 2: .Bd -literal void ifa_free(struct ifaddr *ifa) { if (refcount_release(&ifa->ifa_refcnt)) epoch_call(net_epoch, ifa_destroy, &ifa->ifa_epoch_ctx); } void if_purgeaddrs(struct ifnet *ifp) { /* .... * IF_ADDR_WLOCK(ifp); CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link); IF_ADDR_WUNLOCK(ifp); ifa_free(ifa); } .Ed .Pp Thread 1 traverses the ifaddr list in an epoch. Thread 2 unlinks with the corresponding epoch safe macro, marks as logically free, and then defers deletion. More general mutation or a synchronous free would have to follow a call to .Fn epoch_wait . .Sh NOTES The .Nm kernel programming interface is under development and is subject to change. .Sh SEE ALSO .Xr locking 9 , .Xr mtx_pool 9 , .Xr mutex 9 , .Xr rwlock 9 , .Xr sema 9 , .Xr sleep 9 , .Xr sx 9 , .Xr timeout 9 .Sh HISTORY The .Nm framework first appeared in .Fx 11.0 . .Sh CAVEATS One must be cautious when using .Fn epoch_wait_preempt . Threads are pinned during epoch sections, so if a thread in a section is then preempted by a higher priority compute bound thread on that CPU, it can be prevented from leaving the section indefinitely. .Pp Epochs are not a straight replacement for read locks. Callers must use safe list and tailq traversal routines in an epoch (see ck_queue). When modifying a list referenced from an epoch section safe removal routines must be used and the caller can no longer modify a list entry in place. An item to be modified must be handled with copy on write and frees must be deferred until after a grace period has elapsed. diff --git a/share/man/man9/fdt_pinctrl.9 b/share/man/man9/fdt_pinctrl.9 index f4cb92368136..8f1f24a07a52 100644 --- a/share/man/man9/fdt_pinctrl.9 +++ b/share/man/man9/fdt_pinctrl.9 @@ -1,191 +1,191 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2018 Oleksandr Tymoshenko .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd June 23, 2018 .Dt fdt_pinctrl 9 .Os .Sh NAME .Nm fdt_pinctrl .Nd helper functions for FDT pinmux controller drivers .Sh SYNOPSIS .In dev/fdt/fdt_pinctrl.h .Ft int .Fn fdt_pinctrl_configure "device_t client" "u_int index" .Ft int .Fn fdt_pinctrl_configure_by_name "device_t client" "const char * name" .Ft int .Fn fdt_pinctrl_register "device_t pinctrl" "const char *pinprop" .Ft int .Fn fdt_pinctrl_configure_tree "device_t pinctrl" .Sh DESCRIPTION .Xr fdt_pinctrl 4 provides an API for manipulating I/O pin configurations on pinmux controllers and pinmux clients. On the controller side, the standard newbus probe and attach methods are implemented. As part of handling attach, it calls the .Fn fdt_pinctrl_register function to register itself as a pinmux controller. Then .Fn fdt_pinctrl_configure_tree is used to walk the device tree and configure pins specified by the pinctrl-0 property for all active devices. The driver also implements the .Fn fdt_pinctrl_configure method, which allows client devices to change their pin configurations after startup. If a client device requires a pin configuration change at some point of its lifecycle, it uses the .Fn fdt_pinctrl_configure or .Fn fdt_pinctrl_configure_by_name functions. .Pp .Fn fdt_pinctrl_configure is used by client device .Fa client to request a pin configuration described by the pinctrl-N property with index .Fa index . .Pp .Fn fdt_pinctrl_configure_by_name is used by client device .Fa client to request the pin configuration with name .Fa name . .Pp .Fn fdt_pinctrl_register registers a pinctrl driver so that it can be used by other devices which call .Fn fdt_pinctrl_configure or .Fn fdt_pinctrl_configure_by_name . It also registers each child node of the pinctrl driver's node which contains a property with the name given in .Fa pinprop . If .Fa pinprop is .Dv NULL , every descendant node is registered. It is possible for the driver to register itself as a pinmux controller for more than one pin property type by calling .Fn fdt_pinctrl_register multiple types. .Pp .Fn fdt_pinctrl_configure_tree walks through enabled devices in the device tree. If the pinctrl-0 property contains references to child nodes of the specified pinctrl device, their pins are configured. .Sh EXAMPLES .Bd -literal static int foo_configure_pins(device_t dev, phandle_t cfgxref) { phandle_t cfgnode; uint32_t *pins, *functions; int npins, nfunctions; cfgnode = OF_node_from_xref(cfgxref); pins = NULL; npins = OF_getencprop_alloc_multi(cfgnode, "foo,pins", sizeof(*pins), (void **)&pins); functions = NULL; nfunctions = OF_getencprop_alloc_multi(cfgnode, "foo,functions", sizeof(*functions), (void **)&functions); ... } static int foo_is_gpio(device_t dev, device_t gpiodev, bool *is_gpio) { return (foo_is_pin_func_gpio(is_gpio)); } static int foo_set_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t flags) { int rv; rv = foo_is_pin_func_gpio(is_gpio); if (rv != 0) return (rv); foo_set_flags(pin, flags); return (0); } static int foo_get_flags(device_t dev, device_t gpiodev, uint32_t pin, uint32_t *flags) { int rv; rv = foo_is_pin_func_gpio(is_gpio); if (rv != 0) return (rv); foo_get_flags(pin, flags); return (0); } static int foo_attach(device_t dev) { ... fdt_pinctrl_register(dev, "foo,pins"); /* * It is possible to register more than one pinprop handler */ fdt_pinctrl_register(dev, "bar,pins"); fdt_pinctrl_configure_tree(dev); return (0); } static device_method_t foo_methods[] = { ... /* fdt_pinctrl interface */ DEVMETHOD(fdt_pinctrl_configure, foo_configure_pins), DEVMETHOD(fdt_pinctrl_is_gpio, foo_is_gpio), DEVMETHOD(fdt_pinctrl_set_flags, foo_set_flags), DEVMETHOD(fdt_pinctrl_get_flags, foo_get_flags), /* Terminate method list */ DEVMETHOD_END }; DRIVER_MODULE(foo, simplebus, foo_driver, foo_devclass, NULL, NULL); .Ed .Sh SEE ALSO -.Xr fdt_pinctrl 4 , +.Xr fdt_pinctrl 4 .Sh AUTHORS This manual page was written by .An Oleksandr Tymoshenko . diff --git a/share/man/man9/iflibdi.9 b/share/man/man9/iflibdi.9 index c37832ede6af..0d40333dd528 100644 --- a/share/man/man9/iflibdi.9 +++ b/share/man/man9/iflibdi.9 @@ -1,238 +1,237 @@ .\" $FreeBSD$ .Dd May 21, 2019 .Dt IFLIBDI 9 .Os .Sh NAME .Nm iflibdi .Nd Device Independent Configuration Functions .Sh SYNOPSIS .In "ifdi_if.h" .Ss "Device Independent Functions" .Ft int .Fo iflib_device_attach .Fa "device_t dev" .Fc .Ft int .Fo iflib_device_detach .Fa "device_t dev" .Fc .Ft int .Fo iflib_device_suspend .Fa "device_t dev" .Fc .Ft int .Fo iflib_device_resume .Fa "device_t dev" .Fc .Ft int .Fo iflib_device_register .Fa "device_t dev" .Fa "void *softc" .Fa "if_shared_ctx_t sctx" .Fa "if_ctx_t *ctxp" .Fc .Ft int .Fo iflib_device_deregister .Fa "if_ctx_t ctx" .Fc .Ft int .Fo iflib_irq_alloc .Fa "if_ctx_t ctx" .Fa "if_irq_t irq_info" .Fa "int rid" .Fa "driver_filter_t filter" .Fa "void *filter_arg" .Fa "driver_intr_t handler" .Fa "void *arg" .Fa "char *name" .Fc .Ft int .Fo iflib_irq_alloc_generic .Fa "if_ctx_t ctx" .Fa "if_irq_t irq" .Fa "int rid" .Fa "intr_type_t type" .Fa "driver_filter_t *filter" .Fa "void *filter_arg" .Fa "int qid" .Fa "char *name" .Fc .Ft void .Fo iflib_led_create .Fa "if_ctx_t ctx" .Fc .Ft void .Fo iflib_tx_intr_deferred .Fa "if_ctx_t ctx" .Fa "int txqid" .Fc .Ft void .Fo iflib_rx_intr_deferred .Fa "if_ctx_t ctx" .Fa "int rxqid" .Fc .Ft void .Fo iflib_link_intr_deferred .Fa "if_ctx_t ctx" .Fc .Ft void .Fo iflib_link_state_change .Fa "if_ctx_t ctx" .Fa "int linkstate" .Fc .Ft void .Fo iflib_add_int_delay_sysctl .Fa "if_ctx_t ctx" .Fa "const char *" .Fa "const char *" .Fa "if_int_delay_info_t" .Fa "int" .Fa "int" .Fc .Ss "Global Variables" .Vt extern struct if_txrx .Sh DATA STRUCTURES The \fIif_ctx_t\fP Structure is the device independent data structure that contains statistics and identifying information used to transmit and receive data packets. The interface is associated with an array of queues assigned sequentially. Each queue has its own transmit (iflib_txq_t) and receive (iflib_rxq_t) queue. The transmit queue is used to hold packets while the interface is in the process of sending another. The receive queue is used to receive packets that are awaiting processing. -.Pp .Ss The if_ctx_t Structure The fields of .Vt "struct if_ctx_t" are as follows: .Bl -tag -width ".Va if_capabilities" -offset indent .It Va if_softc .Pq Vt "void" A pointer to the driver's private state block. .It Va ifc_dev .Pq Vt "device_t" The underlying device structure. .It Va ifc_ip .Pq Vt "if_t" A link back to the interface structure .It Va ifc_cpus .Pq Vt "cpuset_t" .It Va ifc_mutex .Pq Vt "struct mtx" Mutex lock used to maintain data integrity .It Va ifc_mtx_name .Pq Vt "char *" The name of the mutex .It Va ifc_txqs .Pq Vt "iflib_txq_t" Device independent transmit queue maintained internally by iflib .It Va ifc_rxqs .Pq Vt "iflib_rxq_t" Device independent receive queue maintained internally by iflib .It Va ifc_qsets .Pq Vt "iflib_qset_t" Output queue that contains a single transmit (ifc_txq_t) and receive (ifc_rxq_t) queue .It Va ifc_if_flags .Pq Vt "uint32_t" Flags describing the operational parameter of the interface .It Va ifc_in_detach .Pq Vt "int" .It Va ifc_link_state .Pq Vt "int" Describes the current link state of the Ethernet interface. Its possible values are either active or inactive. .It Va ifc_link_irq .Pq Vt "int" .It Va ifc_vlan_attach_event .Pq Vt "eventhandler_tag" .It Va ifc_vlan_detach_event .Pq Vt "eventhandler_tag" .It Va ifc_pause_frames .Pq Vt "int" .It Va ifc_watchdog_events .Pq Vt "int" .It Va ifc_mac .Pq Vt "uint8_t" .It Va ifc_msix_mem .Pq Vt "struct resource *" .It Va ifc_legacy_irq .Pq Vt "struct if_irq" .It Va ifc_admin_task .Pq Vt "struct grouptask" Taskqueue task scheduled for link state change events of the interface .It Va ifc_filter_info .Pq Vt "struct iflib_filter_info" Statistics and information relating to the interface device filter .It Va ifc_media .Pq Vt "struct ifmedia" .It Va ifc_txrx .Pq Vt "struct if_txrx" .El .Sh FUNCTIONS The above named functions are found exclusively in iflib. They are independent of the underlying hardware type or configuration. .Ss Device Independent Functions .Bl -ohang -offset indent .It Fn iflib_device_attach Function initiates a device registration with the iflib framework. It calls the iflib_register function, which is responsible for allocating and initializing the \fIif_ctx_t\fP structure. .It Fn iflib_device_detach Shutdown and detach the device. Unregister vlan events, drain any dependent tasks, and release irq, pci, and msix memory. .It Fn iflib_device_suspend Suspend a device by calling the device dependent suspend function and bus_generic_suspend. .It Fn iflib_device_resume Resume a device by calling the device dependent resume function, the iflib_init_locked function, and bus_generic_resume. .It Fn iflib_device_register Register a device with the iflib framework. Allocate and initialize the \fIif_ctx_t\fP structure. Setup and initialize the MSI or MSI/X interrupt queues if necessary. Allocate memory for queues and qset structure setup. .It Fn iflib_irq_alloc Allocate an interrupt resource for a given rid value with an associated filter and handler function. .It Fn iflib_irq_alloc_generic Performs the same function as iflib_device_irq_alloc along with the additional functionality of adding a taskgroup. The data fields and callback function are determined by the type of interrupt, such as .Dv IFLIB_INTR_TX , .Dv IFLIB_INTR_RX , and .Dv IFLIB_INTR_ADMIN . .It Fn iflib_led_create Calls led_create to initialize the ctx->ifc_led_dev field .It Fn iflib_tx_intr_deferred Calls GROUPTASK_ENQUEUE to enqueue the transfer queues ift_task. .It Fn iflib_rx_intr_deferred Calls GROUPTASK_ENQUEUE to enqueue the receive queues ifr_task. .It Fn iflib_link_intr_deferred Calls GROUPTASK_ENQUEUE to enqueue the link task .It Fn iflib_link_state_change Change the interface link status to either .Dv LINK_STATE_UP or .Dv LINK_STATE_DOWN as specified by the second argument to the function. .Pp .Em Interface Link States The following link states are currently defined: .It Dv LINK_STATE_UP The link is up. .It Dv LINK_STATE_DOWN The link is down. .It Fn iflib_add_int_delay_sysctl Modifies settings to user defined values for a given set of variables. .El .Sh SEE ALSO .Xr iflibdd 9 , .Xr iflibtxrx 9 .Sh AUTHORS This manual page was written by .An Nicole Graziano diff --git a/share/man/man9/iflibtxrx.9 b/share/man/man9/iflibtxrx.9 index f99a91b05838..adb44def1d3f 100644 --- a/share/man/man9/iflibtxrx.9 +++ b/share/man/man9/iflibtxrx.9 @@ -1,241 +1,240 @@ .\" $FreeBSD$ .Dd December 17, 2020 .Dt IFLIBTXTX 9 .Os .Sh NAME .Nm iflibtxrx .Nd Device Dependent Transmit and Receive Functions .Sh SYNOPSIS .In "ifdi_if.h" .Ss "Interface Manipulation Functions" .Ft int .Fo isc_txd_encap .Fa "void *sc" .Fa "if_pkt_info_t pi" .Fc .Ft void .Fo isc_txd_flush .Fa "void *sc" .Fa "uint16_t qid" .Fa "uint32_t _pidx_or_credits_" .Fc .Ft int .Fo isc_txd_credits_update .Fa "void *sc" .Fa "uint16_t qid" .Fa "bool clear" .Fc .Ft int .Fo isc_rxd_available .Fa "void *sc" .Fa "uint16_t qsid" .Fa "uint32_t cidx" .Fc .Ft void .Fo isc_rxd_refill .Fa "void *sc" .Fa "uint16_t qsid" .Fa "uint8_t flid" .Fa "uint32_t pidx" .Fa "uint64_t *paddrs" .Fa "caddr_t *vaddrs" .Fa "uint16_t count" .Fc .Ft void .Fo isc_rxd_flush .Fa "void *sc" .Fa "uint16_t qsid" .Fa "uint8_t flid" .Fa "uint32_t pidx" .Fc .Ft int .Fo isc_rxd_pkt_get .Fa "void *sc" .Fa "if_rxd_info_t ri" .Fc .Ss "Global Variables" .Vt extern struct if_txrx .Sh DATA STRUCTURES The device dependent mechanisms for handling packet transmit and receive are primarily defined by the functions named above. The if_pkt_info data structure contains statistics and identifying info necessary for packet transmission. While the data structure for packet receipt is the if_rxd_info structure. -.Pp .Ss The if_pkt_info Structure The fields of .Vt "struct if_pkt_info" are as follows: .Bl -tag -width ".Va if_capabilities" -offset indent .It Va ipi_len .Pq Vt "uint32_t" Denotes the size of packet to be sent on the transmit queue. .It Va ipi_segs .Pq Vt "bus_dma_segment_t *" A pointer to the bus_dma_segment of the device independent transfer queue defined in iflib. .It Va ipi_qsidx Unique index value assigned sequentially to each transmit queue. Used to reference the currently transmitting queue. .It Va ipi_nsegs .Pq Vt "uint16_t" Number of descriptors to be read into the device dependent transfer descriptors. .It Va ipi_ndescs .Pq Vt "uint16_t" Number of descriptors in use. Calculated by subtracting the old pidx value from the new pidx value. .It Va ipi_flags .Pq Vt "uint16_t" Flags defined on a per packet basis. .It Va ipi_pidx .Pq Vt "uint32_t" Value of first pidx sent to the isc_encap function for encapsulation and subsequent transmission. .It Va ipi_new_pidx .Pq Vt "uint32_t" Value set after the termination of the isc_encap function. This value will become the first pidx sent to the isc-encap the next time that the function is called. .It Va \fBThe Following Fields Are Used For Offload Handling\fP .It Va ipi_csum_flags .Pq Vt "uint64_t" Flags describing the checksum values, used on a per packet basis. .It Va ipi_tso_segsz .Pq Vt "uint16_t" Size of the TSO Segment Size. .It Va ipi_mflags .Pq Vt "uint16_t" Flags describing the operational parameters of the mbuf. .It Va ipi_vtag .Pq Vt "uint16_t" Contains the VLAN information in the Ethernet Frame. .It Va ipi_etype .Pq Vt "uint16_t" Type of ethernet header protocol as contained by the struct ether_vlan_header. .It Va ipi_ehrdlen .Pq Vt "uint8_t" Length of the Ethernet Header. .It Va ipi_ip_hlen .Pq Vt "uint8_t" Length of the TCP Header .It Va ipi_tcp_hlen .Pq Vt "uint8_t" Length of the TCP Header. .It Va ipi_tcp_hflags .Pq Vt "uint8_t" Flags describing the operational parameters of the TCP Header. .It Va ipi_ipproto .Pq Vt "uint8_t" Specifies the type of IP Protocol in use. Example TCP, UDP, or SCTP. .El .Ss The if_rxd_info Structure The fields of .Vt "struct if_rxd_info" are as follows: .Bl -tag -width ".Va if_capabilities" -offset indent .It Va iri_qsidx .Pq Vt "uint16_t" Unique index value assigned sequentially to each receive queue. Used to reference the currently receiving queue. .It Va iri_vtag .Pq Vt "uint16_t" Contains the VLAN information in the Ethernet Frame. .It Va iri_len .Pq Vt "uint16_t" Denotes the size of a received packet. .It Va iri_next_offset .Pq Vt "uint16_t" Denotes the offset value for the next packet to be receive. A Null value signifies the end of packet. .It Va iri_cidx .Pq Vt "uint32_t" Denotes the index value of the packet currently being processed in the consumer queue. .It Va iri_flowid .Pq Vt "uint32_t" Value of the RSS hash for the packet. .It Va iri_flags .Pq Vt "uint" Flags describing the operational parameters of the mbuf contained in the receive packet. .It Va iri_csum_flags .Pq Vt "uint32_t" Flags describing the checksum value contained in the receive packet. .It Va iri_csum_data .Pq Vt "uint32_t" Checksum data contained in the .Xr mbuf 9 packet header. .It Va iri_m .Pq Vt "struct mbuf *" A mbuf for drivers that manage their own receive queues. .It Va iri_ifp .Pq Vt "struct ifnet *" A link back to the interface structure. Utilized by drivers that have multiple interface per softc. .It Va iri_rsstype .Pq Vt "uint8_t" The value of the RSS hash type. .It Va iri_pad .Pq Vt "uint8_t" The length of any padding contained by the received data. .It Va iri_qidx .Pq Vt "uint8_t" Represents the type of queue event. If value >= 0 then it is the freelist id otherwise it is a completion queue event. .El .Sh FUNCTIONS All function calls are associated exclusively with either packet transmission or receipt. The void *sc passed as the first argument to all of the following functions represents the driver's softc. .Ss Transmit Packet Functions .Bl -ohang -offset indent .It Fn isc_txd_encap Transmit function that sends a packet on an interface. The if_pkt_info data structure contains data information fields describing the packet. This function returns 0 if successful, otherwise an error value is returned. .It Fn isc_txd_flush Flush function is called immediately after the isc_txd_encap function transmits a packet. It updates the hardware producer index or increments the descriptors used to pidx_or_credits in the queue designated by the qid number. This is often referred to as poking the doorbell register. .It Fn isc_txd_credits_update Credit function advances the buffer ring and calculates the credits (descriptors) processed. Until the I/O is complete it cleans the range in case of multisegments and updates the count of processed packets. The function returns the number of processed credits. .El .Ss Receive Packet Functions .Bl -ohang -offset indent .It Fn isc_rxd_available Function calculates the remaining number of descriptors from a position given by idx. The function returns this value. .It Fn isc_rxd_refill Starting with the physical address paddrs, the function reads a packet into the rx_ring until a value designated by count is reached. vaddrs is typically not needed and is provided for devices that place their own metadata in the packet header. .It Fn isc_rxd_flush Flush function updates the producer pointer on the free list flid in queue set number qid to pidx to reflect the presence of new buffers. .It Fn isc_rxd_pkt_get Process a single software descriptor. rxr->rx_base[i] contains a descriptor that describes a received packet. Hardware specific information about the buffer referred to by ri is returned in the data structure if_rxd_info .El .Sh SEE ALSO .Xr iflibdd 9 , .Xr iflibdi 9 , .Xr mbuf 9 .Sh AUTHORS This manual page was written by .An Nicole Graziano diff --git a/share/man/man9/ifnet.9 b/share/man/man9/ifnet.9 index 90a95106b1d5..d604a2092e19 100644 --- a/share/man/man9/ifnet.9 +++ b/share/man/man9/ifnet.9 @@ -1,1546 +1,1545 @@ .\" -*- Nroff -*- .\" Copyright 1996, 1997 Massachusetts Institute of Technology .\" .\" Permission to use, copy, modify, and distribute this software and .\" its documentation for any purpose and without fee is hereby .\" granted, provided that both the above copyright notice and this .\" permission notice appear in all copies, that both the above .\" copyright notice and this permission notice appear in all .\" supporting documentation, and that the name of M.I.T. not be used .\" in advertising or publicity pertaining to distribution of the .\" software without specific, written prior permission. M.I.T. makes .\" no representations about the suitability of this software for any .\" purpose. It is provided "as is" without express or implied .\" warranty. .\" .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 28, 2020 .Dt IFNET 9 .Os .Sh NAME .Nm ifnet , .Nm ifaddr , .Nm ifqueue , .Nm if_data .Nd kernel interfaces for manipulating network interfaces .Sh SYNOPSIS .In sys/param.h .In sys/time.h .In sys/socket.h .In net/if.h .In net/if_var.h .In net/if_types.h .\" .Ss "Interface Manipulation Functions" .Ft "struct ifnet *" .Fn if_alloc "u_char type" .Ft "struct ifnet *" .Fn if_alloc_dev "u_char type" "device_t dev" .Ft "struct ifnet *" .Fn if_alloc_domain "u_char type" "int numa_domain" .Ft void .Fn if_attach "struct ifnet *ifp" .Ft void .Fn if_detach "struct ifnet *ifp" .Ft void .Fn if_free "struct ifnet *ifp" .Ft void .Fn if_free_type "struct ifnet *ifp" "u_char type" .Ft void .Fn if_down "struct ifnet *ifp" .Ft int .Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" .Ft int .Fn ifpromisc "struct ifnet *ifp" "int pswitch" .Ft int .Fn if_allmulti "struct ifnet *ifp" "int amswitch" .Ft "struct ifnet *" .Fn ifunit "const char *name" .Ft "struct ifnet *" .Fn ifunit_ref "const char *name" .Ft void .Fn if_up "struct ifnet *ifp" .\" .Ss "Interface Address Functions" .Ft "struct ifaddr *" .Fn ifaddr_byindex "u_short idx" .Ft "struct ifaddr *" .Fn ifa_ifwithaddr "struct sockaddr *addr" .Ft "struct ifaddr *" .Fn ifa_ifwithdstaddr "struct sockaddr *addr" "int fib" .Ft "struct ifaddr *" .Fn ifa_ifwithnet "struct sockaddr *addr" "int ignore_ptp" "int fib" .Ft "struct ifaddr *" .Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" .Ft void .Fn ifa_ref "struct ifaddr *ifa" .Ft void .Fn ifa_free "struct ifaddr *ifa" .\" .Ss "Interface Multicast Address Functions" .Ft int .Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" .Ft int .Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" .Ft "struct ifmultiaddr *" .Fn if_findmulti "struct ifnet *ifp" "struct sockaddr *sa" .Ss "Output queue macros" .Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" .\" .Ss "struct ifnet Member Functions" .Ft void .Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m" .Ft int .Fo \*(lp*if_output\*(rp .Fa "struct ifnet *ifp" "struct mbuf *m" .Fa "const struct sockaddr *dst" "struct route *ro" .Fc .Ft void .Fn \*(lp*if_start\*(rp "struct ifnet *ifp" .Ft int .Fn \*(lp*if_transmit\*(rp "struct ifnet *ifp" "struct mbuf *m" .Ft void .Fn \*(lp*if_qflush\*(rp "struct ifnet *ifp" .Ft int .Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "u_long cmd" "caddr_t data" .Ft void .Fn \*(lp*if_init\*(rp "void *if_softc" .Ft int .Fo \*(lp*if_resolvemulti\*(rp .Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" .Fc .Ss "struct ifaddr member function" .Ft void .Fo \*(lp*ifa_rtrequest\*(rp .Fa "int cmd" "struct rtentry *rt" "struct rt_addrinfo *info" .Fc .\" .Ss "Global Variables" .Vt extern struct ifnethead ifnet ; .\" extern struct ifindex_entry *ifindex_table ; .Vt extern int if_index ; .Vt extern int ifqmaxlen ; .Sh DATA STRUCTURES The kernel mechanisms for handling network interfaces reside primarily in the .Vt ifnet , if_data , ifaddr , and .Vt ifmultiaddr structures in .In net/if.h and .In net/if_var.h and the functions named above and defined in .Pa /sys/net/if.c . Those interfaces which are intended to be used by user programs are defined in .In net/if.h ; these include the interface flags, the .Vt if_data structure, and the structures defining the appearance of interface-related messages on the .Xr route 4 routing socket and in .Xr sysctl 3 . The header file .In net/if_var.h defines the kernel-internal interfaces, including the .Vt ifnet , ifaddr , and .Vt ifmultiaddr structures and the functions which manipulate them. (A few user programs will need .In net/if_var.h because it is the prerequisite of some other header file like .In netinet/if_ether.h . Most references to those two files in particular can be replaced by .In net/ethernet.h . ) .Pp The system keeps a linked list of interfaces using the .Li TAILQ macros defined in .Xr queue 3 ; this list is headed by a .Vt "struct ifnethead" called .Va ifnet . The elements of this list are of type .Vt "struct ifnet" , and most kernel routines which manipulate interface as such accept or return pointers to these structures. Each interface structure contains an .Vt if_data structure used for statistics and information. Each interface also has a .Li TAILQ of interface addresses, described by .Vt ifaddr structures. An .Dv AF_LINK address (see .Xr link_addr 3 ) describing the link layer implemented by the interface (if any) is accessed by the .Fn ifaddr_byindex function or .Va if_addr structure. (Some trivial interfaces do not provide any link layer addresses; this structure, while still present, serves only to identify the interface name and index.) .Pp Finally, those interfaces supporting reception of multicast datagrams have a .Li TAILQ of multicast group memberships, described by .Vt ifmultiaddr structures. These memberships are reference-counted. .Pp Interfaces are also associated with an output queue, defined as a .Vt "struct ifqueue" ; this structure is used to hold packets while the interface is in the process of sending another. -.Pp .Ss The ifnet Structure The fields of .Vt "struct ifnet" are as follows: .Bl -tag -width ".Va if_capabilities" -offset indent .It Va if_softc .Pq Vt "void *" A pointer to the driver's private state block. (Initialized by driver.) .It Va if_l2com .Pq Vt "void *" A pointer to the common data for the interface's layer 2 protocol. (Initialized by .Fn if_alloc . ) .It Va if_vnet .Pq Vt "struct vnet *" A pointer to the virtual network stack instance. (Initialized by .Fn if_attach . ) .It Va if_home_vnet .Pq Vt "struct vnet *" A pointer to the parent virtual network stack, where this .Vt "struct ifnet" originates from. (Initialized by .Fn if_attach . ) .It Va if_link .Pq Fn TAILQ_ENTRY ifnet .Xr queue 3 macro glue. .It Va if_xname .Pq Vt "char *" The name of the interface, (e.g., .Dq Li fxp0 or .Dq Li lo0 ) . (Initialized by driver (usually via .Fn if_initname ) . ) .It Va if_dname .Pq Vt "const char *" The name of the driver. (Initialized by driver (usually via .Fn if_initname ) . ) .It Va if_dunit .Pq Vt int A unique number assigned to each interface managed by a particular driver. Drivers may choose to set this to .Dv IF_DUNIT_NONE if a unit number is not associated with the device. (Initialized by driver (usually via .Fn if_initname ) . ) .It Va if_refcount .Pq Vt u_int The reference count. (Initialized by .Fn if_alloc . ) .It Va if_addrhead .Pq Vt "struct ifaddrhead" The head of the .Xr queue 3 .Li TAILQ containing the list of addresses assigned to this interface. .It Va if_pcount .Pq Vt int A count of promiscuous listeners on this interface, used to reference-count the .Dv IFF_PROMISC flag. .It Va if_carp .Pq Vt "struct carp_if *" A pointer to the CARP interface structure, .Xr carp 4 . (Initialized by the driver-specific .Fn if_ioctl routine.) .It Va if_bpf .Pq Vt "struct bpf_if *" Opaque per-interface data for the packet filter, .Xr bpf 4 . (Initialized by .Fn bpf_attach . ) .It Va if_index .Pq Vt u_short A unique number assigned to each interface in sequence as it is attached. This number can be used in a .Vt "struct sockaddr_dl" to refer to a particular interface by index (see .Xr link_addr 3 ) . (Initialized by .Fn if_alloc . ) .It Va if_vlantrunk .Pq Vt struct ifvlantrunk * A pointer to 802.1Q trunk structure, .Xr vlan 4 . (Initialized by the driver-specific .Fn if_ioctl routine.) .It Va if_flags .Pq Vt int Flags describing operational parameters of this interface (see below). (Manipulated by generic code.) .It Va if_drv_flags .Pq Vt int Flags describing operational status of this interface (see below). (Manipulated by driver.) .It Va if_capabilities .Pq Vt int Flags describing the capabilities the interface supports (see below). .It Va if_capenable .Pq Vt int Flags describing the enabled capabilities of the interface (see below). .It Va if_linkmib .Pq Vt "void *" A pointer to an interface-specific MIB structure exported by .Xr ifmib 4 . (Initialized by driver.) .It Va if_linkmiblen .Pq Vt size_t The size of said structure. (Initialized by driver.) .It Va if_data .Pq Vt "struct if_data" More statistics and information; see .Sx "The if_data structure" , below. (Initialized by driver, manipulated by both driver and generic code.) .It Va if_multiaddrs .Pq Vt struct ifmultihead The head of the .Xr queue 3 .Li TAILQ containing the list of multicast addresses assigned to this interface. .It Va if_amcount .Pq Vt int A number of multicast requests on this interface, used to reference-count the .Dv IFF_ALLMULTI flag. .It Va if_addr .Pq Vt "struct ifaddr *" A pointer to the link-level interface address. (Initialized by .Fn if_alloc . ) .\" .It Va if_llsoftc .\" .Pq Vt "void *" .\" The purpose of the field is unclear. .It Va if_snd .Pq Vt "struct ifaltq" The output queue. (Manipulated by driver.) .It Va if_broadcastaddr .Pq Vt "const u_int8_t *" A link-level broadcast bytestring for protocols with variable address length. .It Va if_bridge .Pq Vt "void *" A pointer to the bridge interface structure, .Xr if_bridge 4 . (Initialized by the driver-specific .Fn if_ioctl routine.) .It Va if_label .Pq Vt "struct label *" A pointer to the MAC Framework label structure, .Xr mac 4 . (Initialized by .Fn if_alloc . ) .It Va if_afdata .Pq Vt "void *" An address family dependent data region. .It Va if_afdata_initialized .Pq Vt int Used to track the current state of address family initialization. .It Va if_afdata_lock .Pq Vt "struct rwlock" An .Xr rwlock 9 lock used to protect .Va if_afdata internals. .It Va if_linktask .Pq Vt "struct task" A .Xr taskqueue 9 task scheduled for link state change events of the interface. .It Va if_addr_lock .Pq Vt "struct rwlock" An .Xr rwlock 9 lock used to protect interface-related address lists. .It Va if_clones .Pq Fn LIST_ENTRY ifnet .Xr queue 3 macro glue for the list of clonable network interfaces. .It Va if_groups .Pq Fn TAILQ_HEAD "" "ifg_list" The head of the .Xr queue 3 .Li TAILQ containing the list of groups per interface. .It Va if_pf_kif .Pq Vt "void *" A pointer to the structure used for interface abstraction by .Xr pf 4 . .It Va if_lagg .Pq Vt "void *" A pointer to the .Xr lagg 4 interface structure. .It Va if_alloctype .Pq Vt u_char The type of the interface as it was at the time of its allocation. It is used to cache the type passed to .Fn if_alloc , but unlike .Va if_type , it would not be changed by drivers. .It Va if_numa_domain .Pq Vt uint8_t The NUMA domain of the hardware device associated with the interface. This is filled in with a wildcard value unless the kernel is NUMA aware, the system is a NUMA system, and the ifnet is allocated using .Fn if_alloc_dev or .Fn if_alloc_domain . .El .Pp References to .Vt ifnet structures are gained by calling the .Fn if_ref function and released by calling the .Fn if_rele function. They are used to allow kernel code walking global interface lists to release the .Vt ifnet lock yet keep the .Vt ifnet structure stable. .Pp There are in addition a number of function pointers which the driver must initialize to complete its interface with the generic interface layer: .Bl -ohang -offset indent .It Fn if_input Pass a packet to an appropriate upper layer as determined from the link-layer header of the packet. This routine is to be called from an interrupt handler or used to emulate reception of a packet on this interface. A single function implementing .Fn if_input can be shared among multiple drivers utilizing the same link-layer framing, e.g., Ethernet. .It Fn if_output Output a packet on interface .Fa ifp , or queue it on the output queue if the interface is already active. .It Fn if_transmit Transmit a packet on an interface or queue it if the interface is in use. This function will return .Dv ENOBUFS if the devices software and hardware queues are both full. This function must be installed after .Fn if_attach to override the default implementation. This function is exposed in order to allow drivers to manage their own queues and to reduce the latency caused by a frequently gratuitous enqueue / dequeue pair to ifq. The suggested internal software queuing mechanism is buf_ring. .It Fn if_qflush Free mbufs in internally managed queues when the interface is marked down. This function must be installed after .Fn if_attach to override the default implementation. This function is exposed in order to allow drivers to manage their own queues and to reduce the latency caused by a frequently gratuitous enqueue / dequeue pair to ifq. The suggested internal software queuing mechanism is buf_ring. .It Fn if_start Start queued output on an interface. This function is exposed in order to provide for some interface classes to share a .Fn if_output among all drivers. .Fn if_start may only be called when the .Dv IFF_DRV_OACTIVE flag is not set. (Thus, .Dv IFF_DRV_OACTIVE does not literally mean that output is active, but rather that the device's internal output queue is full.) Please note that this function will soon be deprecated. .It Fn if_ioctl Process interface-related .Xr ioctl 2 requests (defined in .In sys/sockio.h ) . Preliminary processing is done by the generic routine .Fn ifioctl to check for appropriate privileges, locate the interface being manipulated, and perform certain generic operations like twiddling flags and flushing queues. See the description of .Fn ifioctl below for more information. .It Fn if_init Initialize and bring up the hardware, e.g., reset the chip and enable the receiver unit. Should mark the interface running, but not active .Dv ( IFF_DRV_RUNNING , ~IIF_DRV_OACTIVE ) . .It Fn if_resolvemulti Check the requested multicast group membership, .Fa addr , for validity, and if necessary compute a link-layer group which corresponds to that address which is returned in .Fa *retsa . Returns zero on success, or an error code on failure. .El .Ss "Interface Flags" Interface flags are used for a number of different purposes. Some flags simply indicate information about the type of interface and its capabilities; others are dynamically manipulated to reflect the current state of the interface. Flags of the former kind are marked .Aq S in this table; the latter are marked .Aq D . Flags which begin with .Dq IFF_DRV_ are stored in .Va if_drv_flags ; all other flags are stored in .Va if_flags . .Pp The macro .Dv IFF_CANTCHANGE defines the bits which cannot be set by a user program using the .Dv SIOCSIFFLAGS command to .Xr ioctl 2 ; these are indicated by an asterisk .Pq Ql * in the following listing. .Pp .Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact .It Dv IFF_UP .Aq D The interface has been configured up by the user-level code. .It Dv IFF_BROADCAST .Aq S* The interface supports broadcast. .It Dv IFF_DEBUG .Aq D Used to enable/disable driver debugging code. .It Dv IFF_LOOPBACK .Aq S The interface is a loopback device. .It Dv IFF_POINTOPOINT .Aq S* The interface is point-to-point; .Dq broadcast address is actually the address of the other end. .It Dv IFF_DRV_RUNNING .Aq D* The interface has been configured and dynamic resources were successfully allocated. Probably only useful internal to the interface. .It Dv IFF_NOARP .Aq D Disable network address resolution on this interface. .It Dv IFF_PROMISC .Aq D* This interface is in promiscuous mode. .It Dv IFF_PPROMISC .Aq D This interface is in the permanently promiscuous mode (implies .Dv IFF_PROMISC ) . .It Dv IFF_ALLMULTI .Aq D* This interface is in all-multicasts mode (used by multicast routers). .It Dv IFF_DRV_OACTIVE .Aq D* The interface's hardware output queue (if any) is full; output packets are to be queued. .It Dv IFF_SIMPLEX .Aq S* The interface cannot hear its own transmissions. .It Dv IFF_LINK0 .It Dv IFF_LINK1 .It Dv IFF_LINK2 .Aq D Control flags for the link layer. (Currently abused to select among multiple physical layers on some devices.) .It Dv IFF_MULTICAST .Aq S* This interface supports multicast. .It Dv IFF_CANTCONFIG .Aq S* The interface is not configurable in a meaningful way. Primarily useful for .Dv IFT_USB interfaces registered at the interface list. .It Dv IFF_MONITOR .Aq D This interface blocks transmission of packets and discards incoming packets after BPF processing. Used to monitor network traffic but not interact with the network in question. .It Dv IFF_STATICARP .Aq D Used to enable/disable ARP requests on this interface. .It Dv IFF_DYING .Aq D* Set when the .Vt ifnet structure of this interface is being released and still has .Va if_refcount references. .It Dv IFF_RENAMING .Aq D Set when this interface is being renamed. .El .Ss "Interface Capabilities Flags" Interface capabilities are specialized features an interface may or may not support. These capabilities are very hardware-specific and allow, when enabled, to offload specific network processing to the interface or to offer a particular feature for use by other kernel parts. .Pp It should be stressed that a capability can be completely uncontrolled (i.e., stay always enabled with no way to disable it) or allow limited control over itself (e.g., depend on another capability's state.) Such peculiarities are determined solely by the hardware and driver of a particular interface. Only the driver possesses the knowledge on whether and how the interface capabilities can be controlled. Consequently, capabilities flags in .Va if_capenable should never be modified directly by kernel code other than the interface driver. The command .Dv SIOCSIFCAP to .Fn ifioctl is the dedicated means to attempt altering .Va if_capenable on an interface. Userland code shall use .Xr ioctl 2 . .Pp The following capabilities are currently supported by the system: .Bl -tag -width ".Dv IFCAP_VLAN_HWTAGGING" -offset indent .It Dv IFCAP_RXCSUM This interface can do checksum validation on receiving data. Some interfaces do not have sufficient buffer storage to store frames above a certain MTU-size completely. The driver for the interface might disable hardware checksum validation if the MTU is set above the hardcoded limit. .It Dv IFCAP_TXCSUM This interface can do checksum calculation on transmitting data. .It Dv IFCAP_HWCSUM A shorthand for .Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . .It Dv IFCAP_NETCONS This interface can be a network console. .It Dv IFCAP_VLAN_MTU The .Xr vlan 4 driver can operate over this interface in software tagging mode without having to decrease MTU on .Xr vlan 4 interfaces below 1500 bytes. This implies the ability of this interface to cope with frames somewhat longer than permitted by the Ethernet specification. .It Dv IFCAP_VLAN_HWTAGGING This interface can do VLAN tagging on output and demultiplex frames by their VLAN tag on input. .It Dv IFCAP_JUMBO_MTU This Ethernet interface can transmit and receive frames up to 9000 bytes long. .It Dv IFCAP_POLLING This interface supports .Xr polling 4 . See below for details. .It Dv IFCAP_VLAN_HWCSUM This interface can do checksum calculation on both transmitting and receiving data on .Xr vlan 4 interfaces (implies .Dv IFCAP_HWCSUM ) . .It Dv IFCAP_TSO4 This Ethernet interface supports TCP4 Segmentation offloading. .It Dv IFCAP_TSO6 This Ethernet interface supports TCP6 Segmentation offloading. .It Dv IFCAP_TSO A shorthand for .Pq Dv IFCAP_TSO4 | IFCAP_TSO6 . .It Dv IFCAP_TOE4 This Ethernet interface supports TCP offloading. .It Dv IFCAP_TOE6 This Ethernet interface supports TCP6 offloading. .It Dv IFCAP_TOE A shorthand for .Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . .It Dv IFCAP_WOL_UCAST This Ethernet interface supports waking up on any Unicast packet. .It Dv IFCAP_WOL_MCAST This Ethernet interface supports waking up on any Multicast packet. .It Dv IFCAP_WOL_MAGIC This Ethernet interface supports waking up on any Magic packet such as those sent by .Xr wake 8 . .It Dv IFCAP_WOL A shorthand for .Pq Dv IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC . .It Dv IFCAP_TOE4 This Ethernet interface supports TCP4 Offload Engine. .It Dv IFCAP_TOE6 This Ethernet interface supports TCP6 Offload Engine. .It Dv IFCAP_TOE A shorthand for .Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . .It Dv IFCAP_VLAN_HWFILTER This interface supports frame filtering in hardware on .Xr vlan 4 interfaces. .It Dv IFCAP_VLAN_HWTSO This interface supports TCP Segmentation offloading on .Xr vlan 4 interfaces (implies .Dv IFCAP_TSO ) . .It Dv IFCAP_LINKSTATE This Ethernet interface supports dynamic link state changes. .It Dv IFCAP_NETMAP This Ethernet interface supports .Xr netmap 4 . .El .Pp The ability of advanced network interfaces to offload certain computational tasks from the host CPU to the board is limited mostly to TCP/IP. Therefore a separate field associated with an interface (see .Va ifnet.if_data.ifi_hwassist below) keeps a detailed description of its enabled capabilities specific to TCP/IP processing. The TCP/IP module consults the field to see which tasks can be done on an .Em outgoing packet by the interface. The flags defined for that field are a superset of those for .Va mbuf.m_pkthdr.csum_flags , namely: .Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent .It Dv CSUM_IP The interface will compute IP checksums. .It Dv CSUM_TCP The interface will compute TCP checksums. .It Dv CSUM_UDP The interface will compute UDP checksums. .El .Pp An interface notifies the TCP/IP module about the tasks the former has performed on an .Em incoming packet by setting the corresponding flags in the field .Va mbuf.m_pkthdr.csum_flags of the .Vt mbuf chain containing the packet. See .Xr mbuf 9 for details. .Pp The capability of a network interface to operate in .Xr polling 4 mode involves several flags in different global variables and per-interface fields. The capability flag .Dv IFCAP_POLLING set in interface's .Va if_capabilities indicates support for .Xr polling 4 on the particular interface. If set in .Va if_capabilities , the same flag can be marked or cleared in the interface's .Va if_capenable within .Fn ifioctl , thus initiating switch of the interface to .Xr polling 4 mode or interrupt mode, respectively. The actual mode change is managed by the driver-specific .Fn if_ioctl routine. The .Xr polling 4 handler returns the number of packets processed. .Ss The if_data Structure The .Vt if_data structure contains statistics and identifying information used by management programs, and which is exported to user programs by way of the .Xr ifmib 4 branch of the .Xr sysctl 3 MIB. The following elements of the .Vt if_data structure are initialized by the interface and are not expected to change significantly over the course of normal operation: .Bl -tag -width ".Va ifi_lastchange" -offset indent .It Va ifi_type .Pq Vt u_char The type of the interface, as defined in .In net/if_types.h and described below in the .Sx "Interface Types" section. .It Va ifi_physical .Pq Vt u_char Intended to represent a selection of physical layers on devices which support more than one; never implemented. .It Va ifi_addrlen .Pq Vt u_char Length of a link-layer address on this device, or zero if there are none. Used to initialized the address length field in .Vt sockaddr_dl structures referring to this interface. .It Va ifi_hdrlen .Pq Vt u_char Maximum length of any link-layer header which might be prepended by the driver to a packet before transmission. The generic code computes the maximum over all interfaces and uses that value to influence the placement of data in .Vt mbuf Ns s to attempt to ensure that there is always sufficient space to prepend a link-layer header without allocating an additional .Vt mbuf . .It Va ifi_datalen .Pq Vt u_char Length of the .Vt if_data structure. Allows some stabilization of the routing socket ABI in the face of increases in the length of .Vt struct ifdata . .It Va ifi_mtu .Pq Vt u_long The maximum transmission unit of the medium, exclusive of any link-layer overhead. .It Va ifi_metric .Pq Vt u_long A dimensionless metric interpreted by a user-mode routing process. .It Va ifi_baudrate .Pq Vt u_long The line rate of the interface, in bits per second. .It Va ifi_hwassist .Pq Vt u_long A detailed interpretation of the capabilities to offload computational tasks for .Em outgoing packets. The interface driver must keep this field in accord with the current value of .Va if_capenable . .It Va ifi_epoch .Pq Vt time_t The system uptime when interface was attached or the statistics below were reset. This is intended to be used to set the SNMP variable .Va ifCounterDiscontinuityTime . It may also be used to determine if two successive queries for an interface of the same index have returned results for the same interface. .El .Pp The structure additionally contains generic statistics applicable to a variety of different interface types (except as noted, all members are of type .Vt u_long ) : .Bl -tag -width ".Va ifi_lastchange" -offset indent .It Va ifi_link_state .Pq Vt u_char The current link state of Ethernet interfaces. See the .Sx Interface Link States section for possible values. .It Va ifi_ipackets Number of packets received. .It Va ifi_ierrors Number of receive errors detected (e.g., FCS errors, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB. .It Va ifi_opackets Number of packets transmitted. .It Va ifi_oerrors Number of output errors detected (e.g., late collisions, DMA overruns, etc.). More detailed breakdowns can often be had by way of a link-specific MIB. .It Va ifi_collisions Total number of collisions detected on output for CSMA interfaces. (This member is sometimes [ab]used by other types of interfaces for other output error counts.) .It Va ifi_ibytes Total traffic received, in bytes. .It Va ifi_obytes Total traffic transmitted, in bytes. .It Va ifi_imcasts Number of packets received which were sent by link-layer multicast. .It Va ifi_omcasts Number of packets sent by link-layer multicast. .It Va ifi_iqdrops Number of packets dropped on input. Rarely implemented. .It Va ifi_oqdrops Number of packets dropped on output. .It Va ifi_noproto Number of packets received for unknown network-layer protocol. .It Va ifi_lastchange .Pq Vt "struct timeval" The time of the last administrative change to the interface (as required for .Tn SNMP ) . .El .Ss Interface Types The header file .In net/if_types.h defines symbolic constants for a number of different types of interfaces. The most common are: .Pp .Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact .It Dv IFT_OTHER none of the following .It Dv IFT_ETHER Ethernet .It Dv IFT_ISO88023 ISO 8802-3 CSMA/CD .It Dv IFT_ISO88024 ISO 8802-4 Token Bus .It Dv IFT_ISO88025 ISO 8802-5 Token Ring .It Dv IFT_ISO88026 ISO 8802-6 DQDB MAN .It Dv IFT_FDDI FDDI .It Dv IFT_PPP Internet Point-to-Point Protocol .Pq Xr ppp 8 .It Dv IFT_LOOP The loopback .Pq Xr lo 4 interface .It Dv IFT_SLIP Serial Line IP .It Dv IFT_PARA Parallel-port IP .Pq Dq Tn PLIP .It Dv IFT_ATM Asynchronous Transfer Mode .It Dv IFT_USB USB Interface .El .Ss Interface Link States The following link states are currently defined: .Pp .Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact .It Dv LINK_STATE_UNKNOWN The link is in an invalid or unknown state. .It Dv LINK_STATE_DOWN The link is down. .It Dv LINK_STATE_UP The link is up. .El .Ss The ifaddr Structure Every interface is associated with a list (or, rather, a .Li TAILQ ) of addresses, rooted at the interface structure's .Va if_addrhead member. The first element in this list is always an .Dv AF_LINK address representing the interface itself; multi-access network drivers should complete this structure by filling in their link-layer addresses after calling .Fn if_attach . Other members of the structure represent network-layer addresses which have been configured by means of the .Dv SIOCAIFADDR command to .Xr ioctl 2 , called on a socket of the appropriate protocol family. The elements of this list consist of .Vt ifaddr structures. Most protocols will declare their own protocol-specific interface address structures, but all begin with a .Vt "struct ifaddr" which provides the most-commonly-needed functionality across all protocols. Interface addresses are reference-counted. .Pp The members of .Vt "struct ifaddr" are as follows: .Bl -tag -width ".Va ifa_rtrequest" -offset indent .It Va ifa_addr .Pq Vt "struct sockaddr *" The local address of the interface. .It Va ifa_dstaddr .Pq Vt "struct sockaddr *" The remote address of point-to-point interfaces, and the broadcast address of broadcast interfaces. .Va ( ifa_broadaddr is a macro for .Va ifa_dstaddr . ) .It Va ifa_netmask .Pq Vt "struct sockaddr *" The network mask for multi-access interfaces, and the confusion generator for point-to-point interfaces. .It Va ifa_ifp .Pq Vt "struct ifnet *" A link back to the interface structure. .It Va ifa_link .Pq Fn TAILQ_ENTRY ifaddr .Xr queue 3 glue for list of addresses on each interface. .It Va ifa_rtrequest See below. .It Va ifa_flags .Pq Vt u_short Some of the flags which would be used for a route representing this address in the route table. .It Va ifa_refcnt .Pq Vt short The reference count. .El .Pp References to .Vt ifaddr structures are gained by calling the .Fn ifa_ref function and released by calling the .Fn ifa_free function. .Pp .Fn ifa_rtrequest is a pointer to a function which receives callouts from the routing code .Pq Fn rtrequest to perform link-layer-specific actions upon requests to add, or delete routes. The .Fa cmd argument indicates the request in question: .Dv RTM_ADD , or .Dv RTM_DELETE . The .Fa rt argument is the route in question; the .Fa info argument contains the specific destination being manipulated. .Sh FUNCTIONS The functions provided by the generic interface code can be divided into two groups: those which manipulate interfaces, and those which manipulate interface addresses. In addition to these functions, there may also be link-layer support routines which are used by a number of drivers implementing a specific link layer over different hardware; see the documentation for that link layer for more details. .Ss The ifmultiaddr Structure Every multicast-capable interface is associated with a list of multicast group memberships, which indicate at a low level which link-layer multicast addresses (if any) should be accepted, and at a high level, in which network-layer multicast groups a user process has expressed interest. .Pp The elements of the structure are as follows: .Bl -tag -width ".Va ifma_refcount" -offset indent .It Va ifma_link .Pq Fn LIST_ENTRY ifmultiaddr .Xr queue 3 macro glue. .It Va ifma_addr .Pq Vt "struct sockaddr *" A pointer to the address which this record represents. The memberships for various address families are stored in arbitrary order. .It Va ifma_lladdr .Pq Vt "struct sockaddr *" A pointer to the link-layer multicast address, if any, to which the network-layer multicast address in .Va ifma_addr is mapped, else a null pointer. If this element is non-nil, this membership also holds an invisible reference to another membership for that link-layer address. .It Va ifma_refcount .Pq Vt u_int A reference count of requests for this particular membership. .El .Ss Interface Manipulation Functions .Bl -ohang -offset indent .It Fn if_alloc Allocate and initialize .Vt "struct ifnet" . Initialization includes the allocation of an interface index and may include the allocation of a .Fa type specific structure in .Va if_l2com . .It Fn if_alloc_dev Allocate and initialize .Vt "struct ifnet" as .Fn if_alloc does, with the addition that the ifnet can be tagged with the appropriate NUMA domain derived from the .Fa dev argument passed by the caller. .It Fn if_alloc_domain Allocate and initialize .Vt "struct ifnet" as .Fn if_alloc does, with the addition that the ifnet will be tagged with the NUMA domain via the .Fa numa_domain argument passed by the caller. .It Fn if_attach Link the specified interface .Fa ifp into the list of network interfaces. Also initialize the list of addresses on that interface, and create a link-layer .Vt ifaddr structure to be the first element in that list. (A pointer to this address structure is saved in the .Vt ifnet structure and is accessed by the .Fn ifaddr_byindex function.) The .Fa ifp must have been allocated by .Fn if_alloc , .Fn if_alloc_dev or .Fn if_alloc_domain . .It Fn if_detach Shut down and unlink the specified .Fa ifp from the interface list. .It Fn if_free Free the given .Fa ifp back to the system. The interface must have been previously detached if it was ever attached. .It Fn if_free_type Identical to .Fn if_free except that the given .Fa type is used to free .Va if_l2com instead of the type in .Va if_type . This is intended for use with drivers that change their interface type. .It Fn if_down Mark the interface .Fa ifp as down (i.e., .Dv IFF_UP is not set), flush its output queue, notify protocols of the transition, and generate a message from the .Xr route 4 routing socket. .It Fn if_up Mark the interface .Fa ifp as up, notify protocols of the transition, and generate a message from the .Xr route 4 routing socket. .It Fn ifpromisc Add or remove a promiscuous reference to .Fa ifp . If .Fa pswitch is true, add a reference; if it is false, remove a reference. On reference count transitions from zero to one and one to zero, set the .Dv IFF_PROMISC flag appropriately and call .Fn if_ioctl to set up the interface in the desired mode. .It Fn if_allmulti As .Fn ifpromisc , but for the all-multicasts .Pq Dv IFF_ALLMULTI flag instead of the promiscuous flag. .It Fn ifunit Return an .Vt ifnet pointer for the interface named .Fa name . .It Fn ifunit_ref Return a reference-counted (via .Fn ifa_ref ) .Vt ifnet pointer for the interface named .Fa name . This is the preferred function over .Fn ifunit . The caller is responsible for releasing the reference with .Fn if_rele when it is finished with the ifnet. .It Fn ifioctl Process the ioctl request .Fa cmd , issued on socket .Fa so by thread .Fa td , with data parameter .Fa data . This is the main routine for handling all interface configuration requests from user mode. It is ordinarily only called from the socket-layer .Xr ioctl 2 handler, and only for commands with class .Sq Li i . Any unrecognized commands will be passed down to socket .Fa so Ns 's protocol for further interpretation. The following commands are handled by .Fn ifioctl : .Pp .Bl -tag -width ".Dv SIOCGIFNETMASK" -offset indent -compact .It Dv SIOCGIFCONF Get interface configuration. (No call-down to driver.) .Pp .It Dv SIOCSIFNAME Set the interface name. .Dv RTM_IFANNOUNCE departure and arrival messages are sent so that routing code that relies on the interface name will update its interface list. Caller must have appropriate privilege. (No call-down to driver.) .It Dv SIOCGIFCAP .It Dv SIOCGIFDATA .It Dv SIOCGIFFIB .It Dv SIOCGIFFLAGS .It Dv SIOCGIFMETRIC .It Dv SIOCGIFMTU .It Dv SIOCGIFPHYS Get interface capabilities, data, FIB, flags, metric, MTU, medium selection. (No call-down to driver.) .Pp .It Dv SIOCSIFCAP Enable or disable interface capabilities. Caller must have appropriate privilege. Before a call to the driver-specific .Fn if_ioctl routine, the requested mask for enabled capabilities is checked against the mask of capabilities supported by the interface, .Va if_capabilities . Requesting to enable an unsupported capability is invalid. The rest is supposed to be done by the driver, which includes updating .Va if_capenable and .Va if_data.ifi_hwassist appropriately. .Pp .It Dv SIOCSIFFIB Sets interface FIB. Caller must have appropriate privilege. FIB values start at 0 and values greater or equals than .Va net.fibs are considered invalid. .It Dv SIOCSIFFLAGS Change interface flags. Caller must have appropriate privilege. If a change to the .Dv IFF_UP flag is requested, .Fn if_up or .Fn if_down is called as appropriate. Flags listed in .Dv IFF_CANTCHANGE are masked off, and the field .Va if_flags in the interface structure is updated. Finally, the driver .Fn if_ioctl routine is called to perform any setup requested. .Pp .It Dv SIOCSIFMETRIC .It Dv SIOCSIFPHYS Change interface metric or medium. Caller must have appropriate privilege. .Pp .It Dv SIOCSIFMTU Change interface MTU. Caller must have appropriate privilege. MTU values less than 72 or greater than 65535 are considered invalid. The driver .Fn if_ioctl routine is called to implement the change; it is responsible for any additional sanity checking and for actually modifying the MTU in the interface structure. .Pp .It Dv SIOCADDMULTI .It Dv SIOCDELMULTI Add or delete permanent multicast group memberships on the interface. Caller must have appropriate privilege. The .Fn if_addmulti or .Fn if_delmulti function is called to perform the operation; qq.v. .Pp .It Dv SIOCAIFADDR .It Dv SIOCDIFADDR The socket's protocol control routine is called to implement the requested action. .El .El .Ss "Interface Address Functions" Several functions exist to look up an interface address structure given an address. .Fn ifa_ifwithaddr returns an interface address with either a local address or a broadcast address precisely matching the parameter .Fa addr . .Fn ifa_ifwithdstaddr returns an interface address for a point-to-point interface whose remote .Pq Dq destination address is .Fa addr and a fib is .Fa fib . If .Fa fib is .Dv RT_ALL_FIBS , then the first interface address matching .Fa addr will be returned. .Pp .Fn ifa_ifwithnet returns the most specific interface address which matches the specified address, .Fa addr , subject to its configured netmask, or a point-to-point interface address whose remote address is .Fa addr if one is found. If .Fa ignore_ptp is true, skip point-to-point interface addresses. The .Fa fib parameter is handled the same way as by .Fn ifa_ifwithdstaddr . .Pp .Fn ifaof_ifpforaddr returns the most specific address configured on interface .Fa ifp which matches address .Fa addr , subject to its configured netmask. If the interface is point-to-point, only an interface address whose remote address is precisely .Fa addr will be returned. .Pp .Fn ifaddr_byindex returns the link-level address of the interface with the given index .Fa idx . .Pp All of these functions return a null pointer if no such address can be found. .Ss "Interface Multicast Address Functions" The .Fn if_addmulti , .Fn if_delmulti , and .Fn if_findmulti functions provide support for requesting and relinquishing multicast group memberships, and for querying an interface's membership list, respectively. The .Fn if_addmulti function takes a pointer to an interface, .Fa ifp , and a generic address, .Fa sa . It also takes a pointer to a .Vt "struct ifmultiaddr *" which is filled in on successful return with the address of the group membership control block. The .Fn if_addmulti function performs the following four-step process: .Bl -enum -offset indent .It Call the interface's .Fn if_resolvemulti entry point to determine the link-layer address, if any, corresponding to this membership request, and also to give the link layer an opportunity to veto this membership request should it so desire. .It Check the interface's group membership list for a pre-existing membership for this group. If one is not found, allocate a new one; if one is, increment its reference count. .It If the .Fn if_resolvemulti routine returned a link-layer address corresponding to the group, repeat the previous step for that address as well. .It If the interface's multicast address filter needs to be changed because a new membership was added, call the interface's .Fn if_ioctl routine (with a .Fa cmd argument of .Dv SIOCADDMULTI ) to request that it do so. .El .Pp The .Fn if_delmulti function, given an interface .Fa ifp and an address, .Fa sa , reverses this process. Both functions return zero on success, or a standard error number on failure. .Pp The .Fn if_findmulti function examines the membership list of interface .Fa ifp for an address matching .Fa sa , and returns a pointer to that .Vt "struct ifmultiaddr" if one is found, else it returns a null pointer. .Sh SEE ALSO .Xr ioctl 2 , .Xr link_addr 3 , .Xr queue 3 , .Xr sysctl 3 , .Xr bpf 4 , .Xr ifmib 4 , .Xr lo 4 , .Xr netintro 4 , .Xr polling 4 , .Xr config 8 , .Xr ppp 8 , .Xr mbuf 9 , .Xr rtentry 9 .Rs .%A Gary R. Wright .%A W. Richard Stevens .%B TCP/IP Illustrated .%V Vol. 2 .%O Addison-Wesley, ISBN 0-201-63354-X .Re .Sh AUTHORS This manual page was written by .An Garrett A. Wollman . diff --git a/share/man/man9/kern_reboot.9 b/share/man/man9/kern_reboot.9 index 587d4ab114db..fe8ccd7390c3 100644 --- a/share/man/man9/kern_reboot.9 +++ b/share/man/man9/kern_reboot.9 @@ -1,110 +1,110 @@ .\" $NetBSD: boot.9,v 1.2 1996/09/24 07:01:26 ghudson Exp $ .\" .\" Copyright (c) 1997 .\" Mike Pritchard. All rights reserved. .\" .\" Copyright (c) 1994 Christopher G. Demetriou .\" 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. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Christopher G. Demetriou .\" for the NetBSD Project. .\" 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. .\" .\" $FreeBSD$ .\" -.Dd Sept 23, 2021 +.Dd September 23, 2021 .Dt KERN_REBOOT 9 .Os .Sh NAME .Nm kern_reboot .Nd halt or reboot the system .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .In sys/reboot.h .Ft void .Fn kern_reboot "int howto" .In sys/eventhandler.h .Fn EVENTHANDLER_REGISTER "shutdown_pre_sync" "shutdown_fn" "private" "priority" .Fn EVENTHANDLER_REGISTER "shutdown_post_sync" "shutdown_fn" "private" "priority" .Fn EVENTHANDLER_REGISTER "shutdown_final" "shutdown_fn" "private" "priority" .Sh DESCRIPTION The .Fn kern_reboot function handles final system shutdown, and either halts or reboots the system. The exact action to be taken is determined by the flags passed in .Fa howto and by whether or not the system has finished autoconfiguration. .Pp If the system has finished autoconfiguration, .Fn kern_reboot does the following: .Bl -enum -offset indent .It If this is the first invocation of .Fn kern_reboot and the .Dv RB_NOSYNC flag is not set in .Fa howto , syncs and unmounts the system disks by calling .Xr vfs_unmountall 9 . .It Disables interrupts. .It If rebooting after a crash (i.e., if .Dv RB_DUMP is set in .Fa howto , but .Dv RB_HALT is not), saves a system crash dump. .It Runs any shutdown hooks previously registered. .It Prints a message indicating that the system is about to be halted or rebooted. .It If .Dv RB_HALT is set in .Fa howto , halts the system. Otherwise, reboots the system. .El .Pp If the system has not finished autoconfiguration, .Fn kern_reboot runs any shutdown hooks previously registered, prints a message, and halts the system. .Sh RETURN VALUES The .Fn kern_reboot function does not return. .Sh SEE ALSO -.Xr reboot 2 -.Xr EVENTHANDLER 9 +.Xr reboot 2 , +.Xr EVENTHANDLER 9 , .Xr vfs_unmountall 9 diff --git a/share/man/man9/namei.9 b/share/man/man9/namei.9 index b51b9c48a48a..f98646725fb3 100644 --- a/share/man/man9/namei.9 +++ b/share/man/man9/namei.9 @@ -1,368 +1,368 @@ .\" .\" Copyright (c) 1998, 1999 Eivind Eklund .\" Copyright (c) 2003 Hiten M. Pandya .\" Copyright (c) 2005 Robert N. M. Watson .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS 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. .\" .\" .\" If you integrate this manpage in another OS, I'd appreciate a note .\" - eivind@FreeBSD.org .\" .\" $FreeBSD$ .\" .Dd May 23, 2015 .Dt NAMEI 9 .Os .Sh NAME .Nm namei , .Nm NDINIT , -.Nm NDFREE , +.Nm NDFREE .Nd pathname translation and lookup operations .Sh SYNOPSIS .In sys/param.h .In sys/fcntl.h .In sys/namei.h .Ft int .Fn namei "struct nameidata *ndp" .Ft void .Fo NDINIT .Fa "struct nameidata *ndp" "u_long op" "u_long flags" .Fa "enum uio_seg segflg" "const char *namep" "struct thread *td" .Fc .Ft void .Fn NDFREE "struct nameidata *ndp" "const uint flags" .Sh DESCRIPTION The .Nm facility allows the client to perform pathname translation and lookup operations. The .Nm functions will increment the reference count for the vnode in question. The reference count has to be decremented after use of the vnode, by using either .Xr vrele 9 or .Xr vput 9 , depending on whether the .Dv LOCKLEAF flag was specified or not. .Pp The .Fn NDINIT function is used to initialize .Nm components. It takes the following arguments: .Bl -tag -width ".Fa segflg" .It Fa ndp The .Vt "struct nameidata" to initialize. .It Fa op The operation which .Fn namei will perform. The following operations are valid: .Dv LOOKUP , CREATE , DELETE , and .Dv RENAME . The latter three are just setup for those effects; just calling .Fn namei will not result in .Fn VOP_RENAME being called. .It Fa flags Operation flags. Several of these can be effective at the same time. .It Fa segflg UIO segment indicator. This indicates if the name of the object is in userspace .Pq Dv UIO_USERSPACE or in the kernel address space .Pq Dv UIO_SYSSPACE . .It Fa namep Pointer to the component's pathname buffer (the file or directory name that will be looked up). .It Fa td The thread context to use for .Nm operations and locks. .El .Sh NAMEI OPERATION FLAGS The .Fn namei function takes the following set of .Dq "operation flags" that influence its operation: .Bl -tag -width ".Dv WANTPARENT" .It Dv LOCKLEAF Lock vnode on return with .Dv LK_EXCLUSIVE unless .Dv LOCKSHARED is also set. The .Xr VOP_UNLOCK 9 should be used to release the lock (or .Xr vput 9 which is equivalent to calling .Xr VOP_UNLOCK 9 followed by .Xr vrele 9 , all in one). .It Dv LOCKPARENT This flag lets the .Fn namei function return the parent (directory) vnode, .Va ni_dvp in locked state, unless it is identical to .Va ni_vp , in which case .Va ni_dvp is not locked per se (but may be locked due to .Dv LOCKLEAF ) . If a lock is enforced, it should be released using .Xr vput 9 or .Xr VOP_UNLOCK 9 and .Xr vrele 9 . .It Dv LOCKSHARED Lock vnode on return with .Dv LK_SHARED . The .Xr VOP_UNLOCK 9 should be used to release the lock (or .Xr vput 9 which is equivalent to calling .Xr VOP_UNLOCK 9 followed by .Xr vrele 9 , all in one). .It Dv WANTPARENT This flag allows the .Fn namei function to return the parent (directory) vnode in an unlocked state. The parent vnode must be released separately by using .Xr vrele 9 . .It Dv NOCACHE Avoid .Fn namei creating this entry in the namecache if it is not already present. Normally, .Fn namei will add entries to the name cache if they are not already there. .It Dv FOLLOW With this flag, .Fn namei will follow the symbolic link if the last part of the path supplied is a symbolic link (i.e., it will return a vnode for whatever the link points at, instead for the link itself). .It Dv NOFOLLOW Do not follow symbolic links (pseudo). This flag is not looked for by the actual code, which looks for .Dv FOLLOW . .Dv NOFOLLOW is used to indicate to the source code reader that symlinks are intentionally not followed. .It Dv SAVENAME Do not free the pathname buffer at the end of the .Fn namei invocation; instead, free it later in .Fn NDFREE so that the caller may access the pathname buffer. See below for details. .It Dv SAVESTART Retain an additional reference to the parent directory; do not free the pathname buffer. See below for details. .El .Sh ALLOCATED ELEMENTS The .Vt nameidata structure is composed of the following fields: .Bl -tag -width ".Va ni_cnd.cn_pnbuf" .It Va ni_startdir In the normal case, this is either the current directory or the root. It is the current directory if the name passed in does not start with .Ql / and we have not gone through any symlinks with an absolute path, and the root otherwise. .Pp In this case, it is only used by .Fn lookup , and should not be considered valid after a call to .Fn namei . If .Dv SAVESTART is set, this is set to the same as .Va ni_dvp , with an extra .Xr vref 9 . To block .Fn NDFREE from releasing .Va ni_startdir , the .Dv NDF_NO_STARTDIR_RELE can be set. .It Va ni_dvp Vnode pointer to directory of the object on which lookup is performed. This is available on successful return if .Dv LOCKPARENT or .Dv WANTPARENT is set. It is locked if .Dv LOCKPARENT is set. Freeing this in .Fn NDFREE can be inhibited by .Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT , or .Dv NDF_NO_DVP_UNLOCK (with the obvious effects). .It Va ni_vp Vnode pointer to the resulting object, .Dv NULL otherwise. The .Va v_usecount field of this vnode is incremented. If .Dv LOCKLEAF is set, it is also locked. .Pp Freeing this in .Fn NDFREE can be inhibited by .Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT , or .Dv NDF_NO_VP_UNLOCK (with the obvious effects). .It Va ni_cnd.cn_pnbuf The pathname buffer contains the location of the file or directory that will be used by the .Nm operations. It is managed by the .Xr uma 9 zone allocation interface. If the .Dv SAVESTART or .Dv SAVENAME flag is set, then the pathname buffer is available after calling the .Fn namei function. .Pp To only deallocate resources used by the pathname buffer, .Va ni_cnd.cn_pnbuf , then .Dv NDF_ONLY_PNBUF flag can be passed to the .Fn NDFREE function. To keep the pathname buffer intact, the .Dv NDF_NO_FREE_PNBUF flag can be passed to the .Fn NDFREE function. .El .Sh RETURN VALUES If successful, .Fn namei will return 0, otherwise it will return an error. .Sh FILES .Bl -tag -width Pa .It Pa src/sys/kern/vfs_lookup.c .El .Sh ERRORS Errors which .Fn namei may return: .Bl -tag -width Er .It Bq Er ENOTDIR A component of the specified pathname is not a directory when a directory is expected. .It Bq Er ENAMETOOLONG A component of a pathname exceeded 255 characters, or an entire pathname exceeded 1023 characters. .It Bq Er ENOENT A component of the specified pathname does not exist, or the pathname is an empty string. .It Bq Er EACCES An attempt is made to access a file in a way forbidden by its file access permissions. .It Bq Er ELOOP Too many symbolic links were encountered in translating the pathname. .It Bq Er EISDIR An attempt is made to open a directory with write mode specified. .It Bq Er EINVAL The last component of the pathname specified for a .Dv DELETE or .Dv RENAME operation is .Ql \&. . .It Bq Er EROFS An attempt is made to modify a file or directory on a read-only file system. .El .Sh SEE ALSO .Xr uio 9 , .Xr uma 9 , .Xr VFS 9 , .Xr vnode 9 , .Xr vput 9 , .Xr vref 9 .Sh AUTHORS .An -nosplit This manual page was written by .An Eivind Eklund Aq Mt eivind@FreeBSD.org and later significantly revised by .An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . .Sh BUGS The .Dv LOCKPARENT flag does not always result in the parent vnode being locked. This results in complications when the .Dv LOCKPARENT is used. In order to solve this for the cases where both .Dv LOCKPARENT and .Dv LOCKLEAF are used, it is necessary to resort to recursive locking. diff --git a/share/man/man9/nvmem.9 b/share/man/man9/nvmem.9 index 281bb93ba80b..5325700639e0 100644 --- a/share/man/man9/nvmem.9 +++ b/share/man/man9/nvmem.9 @@ -1,157 +1,157 @@ .\" Copyright (c) 2018 Emmanuel Vadot .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd July 24, 2018 .Dt nvmem 9 .Os .Sh NAME -.Nm nvmem +.Nm nvmem , .Nm nvmem_get_cell_len , .Nm nvmem_read_cell_by_name , .Nm nvmem_read_cell_by_idx , .Nm nvmem_write_cell_by_name , -.Nm nvmem_write_cell_by_idx , +.Nm nvmem_write_cell_by_idx .Sh SYNOPSIS .Cd "options EXT_RESOURCES" .Cd "options FDT" .Cd "device nvmem" .In sys/extres/nvmem/nvmem.h .Ft int .Fn nvmem_get_cell_len "phandle_t node" "const char *name" .Ft int .Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" .Ft int .Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" .Ft int .Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" .Ft int .Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" .Sh DESCRIPTION On some embedded boards, the manufacturer stored some data on a NVMEM (Non-Volatile Memory), this is generally stored in some eeprom or fuses. .Pp The .Nm API consist of helpers functions for consumer and device methods for providers. .Sh FUNCTIONS .Bl -tag -width indent .It Fn nvmem_get_cell_len "phandle_t node" "const char *name" Get the size of the cell base on the reg property on the node. Return the size or ENOENT if the cell name wasn't found .It Fn nvmem_read_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" Get the cell content based on the name. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .It Fn nvmem_read_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" Get the cell content based on the id. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .It Fn nvmem_write_cell_by_name "phandle_t node" "const char *name" "void *cell" "size_t buflen" Write the cell content based on the name. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .It Fn nvmem_write_cell_by_idx "phandle_t node" "int idx" "void *cell" "size_t buflen" Write the cell content based on the id. Return 0 on sucess or ENOENT if the cell doesn't exists, ENXIO if no provider device was found, EINVAL if the size isn't correct. .El .Sh DEVICE METHODS .Bl -tag -width indent .It Fn nvmem_read "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" Provider device method to read a cell content. .It Fn nvmem_write "device_t dev" "uint32_t offset" "uint32_t size" "uint8_t *buffer" Provider device method to write a cell content. .El .Sh EXAMPLES Consider this DTS .Bd -literal /* Provider */ eeprom: eeprom@20000 { board_id: id@0 { reg = <0x0 0x4>; }; }; /* Consumer */ device@30000 { ... nvmem-cells = <&board_id> nvmem-cell-names = "boardid"; }; .Ed .Pp The device driver for eeprom@20000 needs to expose itself as a provider .Bd -literal #include "nvmem_if.h" int foo_nvmem_read(device_t dev, uint32_t offset, uint32_t size, uint8_t *buffer) { /* Read the data */ } int foo_attach(device_t dev) { phandle_t node; node = ofw_bus_get_node(dev); ... /* Registering the device so the consumers can find us */ OF_device_register_xref(OF_xref_from_node(node), dev); ... } static device_method_t foo_methods[] = { ... /* nvmem interface */ DEVMETHOD(nvmem_read, foo_nvmem_read), /* Terminate method list */ DEVMETHOD_END }; .Ed .Pp The consumer device driver for device@30000 can now read the nvmem data .Bd -literal int bar_attach(device_t dev) { phandle_t node; uint32_t boardid; ... node = ofw_bus_get_node(dev); nvmem_read_cell_by_name(node, "boardid", (void *)&boardid, sizeof(boardid)); ... } .Ed .Sh HISTORY The nvmem related function first appear in .Fx 12.0 . The nvmem interface and manual page was written by .An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/share/man/man9/ofw_graph.9 b/share/man/man9/ofw_graph.9 index 0c121f7a05b2..becb5caffc1f 100644 --- a/share/man/man9/ofw_graph.9 +++ b/share/man/man9/ofw_graph.9 @@ -1,108 +1,106 @@ .\" Copyright (c) 2019 Emmanuel Vadot .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 10, 2019 .Dt ofw_graph 9 .Os .Sh NAME .Nm ofw_graph , .Nm ofw_graph_get_port_by_idx , .Nm ofw_graph_port_get_num_endpoints , .Nm ofw_graph_get_endpoint_by_idx , .Nm ofw_graph_get_remote_endpoint , .Nm ofw_graph_get_remote_parent , -.Nm ofw_graph_get_device_by_port_ep , +.Nm ofw_graph_get_device_by_port_ep .Nd Helpers for the graph bindings .Sh SYNOPSIS .In dev/ofw/openfirm.h .In dev/ofw/ofw_graph.h .Ft phandle_t .Fn ofw_graph_get_port_by_idx "phandle_t node" "uint32_t idx" .Ft size_t .Fn ofw_graph_port_get_num_endpoints "phandle_t port" .Ft phandle_t .Fn ofw_graph_get_endpoint_by_idx "phandle_t port" "uint32_t idx" .Ft phandle_t .Fn ofw_graph_get_remote_endpoint "phandle_t endpoint" .Ft phandle_t .Fn ofw_graph_get_remote_parent "phandle_t remote" .Ft device_t .Fn ofw_graph_get_device_by_port_ep "phandle_t node" "uint32_t port_id" "uin32_t ep_id" .Sh DESCRIPTION -.Pp The ofw_graph functions are helpers to parse the DTS graph bindings .Pp .Fn ofw_graph_get_port_by_idx return the port with id .Fa idx . It will first check node named .Fa port@idx and then fallback on checking the .Fa ports child for a child node matching the id. If no ports matching .Fa idx is found the function return 0. .Pp .Fn ofw_graph_port_get_num_endpoints returns the number of endpoints a port node have. .Pp .Fn ofw_graph_get_endpoint_by_idx return the endpoint with id .Fa idx . It will first check if there is a single child named .Fa endpoint and returns it if there is. If there is multiple endpoints it will check the .Fa reg property and returns the correct .Fa phandle_t or 0 if none match. .Pp .Fn ofw_graph_get_remote_endpoint returns the .Fa remote-endpoint property if it exists or 0. .Pp .Fn ofw_graph_get_remote_parent returns the device node corresponding to the .Fa remote-endpoint phandle or 0 if none. .Fn ofw_graph_get_device_by_port_ep returns the device associated with the port and endpoint or .Fa NULL if none. The device driver should have called .Fn OF_device_register_xref before. -.Fn .Sh HISTORY The .Nm ofw_graph functions first appeared in .Fx 13.0 . The .Nm ofw_graph functions and manual page were written by .An Emmanuel Vadot Aq Mt manu@FreeBSD.org . diff --git a/share/man/man9/owll.9 b/share/man/man9/owll.9 index 715dd96c1e8c..a8b623a73a50 100644 --- a/share/man/man9/owll.9 +++ b/share/man/man9/owll.9 @@ -1,92 +1,92 @@ .\" .\" Copyright (c) 2015 M. Warner Losh .\" .\" 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. 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 AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 22, 2016 .Dt OWLL 9 .Os .Sh NAME -.Nm owll +.Nm owll , .Nm OWLL_WRITE_ONE , .Nm OWLL_WRITE_ZERO , .Nm OWLL_READ_DATA , .Nm OWLL_REASET_AND_PRESENCE .Nd Dallas Semiconductor 1-Wire Link Layer Interface .Sh SYNOPSIS .Ft int .Fn OWLL_WRITE_ONE "device_t lldev" "struct ow_timing *timing" .Ft int .Fn OWLL_WRITE_ZERO "device_t lldev" "struct ow_timing *timing" .Ft int .Fn OWLL_READ_DATA "device_t lldev" "struct ow_timing *timing" "int *bit" .Ft int .Fn OWLL_RESET_AND_PRESENCE "device_t lldev" "struct ow_timing *timing" "int *bit" .Sh DESCRIPTION The .Nm interface provides access to the link layer of the Dallas Semiconductor 1-Wire from upper layers of the protocol. .Pp .Fn OWLL_WRITE_ONE and .Fn OWLL_WRITE_ZERO writes a one bit or a zero bit respectively on the 1-Wire bus. .Pp .Fn OWLL_READ_DATA reads one bit from the 1-Wire bus. This is often referred to as a .Dq Read Time Slot in the 1-Wire device data sheets. .Pp The .Fn OWLL_RESET_AND_PRESENCE function starts a reset sequence and detects if any device(s) are present on the bus. This is the beginning of all 1-Wire transactions. .Sh NOTES This interface is intended to be used only by the .Xr ow 4 device to talk to the low-level bus. By convention, the device that implements this interface is called .Xr owc 4 . Only devices that implement .Xr own 9 should call these interfaces. .Sh SEE ALSO .Xr ow 4 , .Xr owc 4 , .Xr own 9 .Sh LEGAL .Tn 1-Wire is a registered trademark of Maxim Integrated Products, Inc. .Sh HISTORY The .Nm driver first appeared in .Fx 11.0 . .Sh AUTHORS The .Nm device driver and this manual page were written by .An Warner Losh . diff --git a/share/man/man9/pmap_zero_page.9 b/share/man/man9/pmap_zero_page.9 index f02b3a59bbba..52e76520ec40 100644 --- a/share/man/man9/pmap_zero_page.9 +++ b/share/man/man9/pmap_zero_page.9 @@ -1,60 +1,60 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 30, 2016 .Dt PMAP_ZERO 9 .Os .Sh NAME .Nm pmap_zero_page , -.Nm pmap_zero_area , +.Nm pmap_zero_area .Nd zero-fill a page using machine-dependent optimizations .Sh SYNOPSIS .In sys/param.h .In vm/vm.h .In vm/pmap.h .Ft void .Fn pmap_zero_page "vm_page_t m" .Ft void .Fn pmap_zero_page_area "vm_page_t m" "int off" "int size" .Sh DESCRIPTION The .Fn pmap_zero_page function zero-fills an entire page using machine-dependent optimizations. The .Fn pmap_zero_page_area function is used to zero-fill an area of a page. The range specified must not cross a page boundary; it must be contained entirely within a single page. .Sh IMPLEMENTATION NOTES This function is required to be implemented for each architecture supported by .Fx . .Sh SEE ALSO .Xr bzero 3 , .Xr pmap 9 .Sh AUTHORS This manual page was written by .An Bruce M Simpson Aq Mt bms@spc.org . diff --git a/share/man/man9/printf.9 b/share/man/man9/printf.9 index 1a3640871bd1..4d3a6fb8b2a5 100644 --- a/share/man/man9/printf.9 +++ b/share/man/man9/printf.9 @@ -1,187 +1,187 @@ .\" .\" Copyright (c) 2001 Andrew R. Reiter .\" Copyright (c) 2004 Joerg Wunsch .\" 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 ``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. .\" .\" $FreeBSD$ .\" .Dd May 9, 2020 .Dt PRINTF 9 .Os .Sh NAME .Nm printf , .Nm uprintf , .Nm tprintf , .Nm log .Nd formatted output conversion .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .Ft int .Fn printf "const char *fmt" ... .Ft void .Fn tprintf "struct proc *p" "int pri" "const char *fmt" ... .Ft int .Fn uprintf "const char *fmt" ... .Ft int .Fn vprintf "const char *fmt" "va_list ap" .In sys/syslog.h .Ft void .Fn log "int pri" "const char *fmt" ... .Ft void .Fn vlog "int pri" "const char *fmt" "va_list ap" .Sh DESCRIPTION The -.Xr printf 9 +.Nm family of functions are similar to the .Xr printf 3 family of functions. The different functions each use a different output stream. The .Fn uprintf function outputs to the current process' controlling tty, while .Fn printf writes to the console as well as to the logging facility. The .Fn tprintf function outputs to the tty associated with the process .Fa p and the logging facility if .Fa pri is not \-1. The .Fn log function sends the message to the kernel logging facility, using the log level as indicated by .Fa pri , and to the console if no process is yet reading the log. .Pp Each of these related functions use the .Fa fmt parameter in the same manner as .Xr printf 3 . However, -.Xr printf 9 +.Nm adds two other conversion specifiers and omits one. .Pp The .Cm \&%b identifier expects two arguments: an .Vt int and a .Vt "char *" . These are used as a register value and a print mask for decoding bitmasks. The print mask is made up of two parts: the base and the arguments. The base value is the output base expressed as an integer value; for example, \e10 gives octal and \e20 gives hexadecimal. The arguments are made up of a sequence of bit identifiers. Each bit identifier begins with an integer value which is the number of the bit (starting from 1) this identifier describes. The rest of the identifier is a string of characters containing the name of the bit. The string is terminated by either the bit number at the start of the next bit identifier or .Dv NUL for the last bit identifier. .Pp The .Cm \&%D identifier is meant to assist in hexdumps. It requires two arguments: a .Vt "u_char *" pointer and a .Vt "char *" string. The memory pointed to by the pointer is output in hexadecimal one byte at a time. The string is used as a delimiter between individual bytes. If present, a width directive will specify the number of bytes to display. By default, 16 bytes of data are output. .Pp The .Cm \&%n conversion specifier is not supported. .Pp The .Fn log function uses .Xr syslog 3 level values .Dv LOG_DEBUG through .Dv LOG_EMERG for its .Fa pri parameter (mistakenly called .Sq priority here). Alternatively, if a .Fa pri of \-1 is given, the message will be appended to the last log message started by a previous call to .Fn log . As these messages are generated by the kernel itself, the facility will always be .Dv LOG_KERN . .Sh RETURN VALUES The .Fn printf and the .Fn uprintf functions return the number of characters displayed. .Sh EXAMPLES This example demonstrates the use of the .Cm \&%b and .Cm \&%D conversion specifiers. The function .Bd -literal -offset indent void printf_test(void) { printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE"); printf("out: %4D\en", "AAAA", ":"); } .Ed .Pp will produce the following output: .Bd -literal -offset indent reg=3 out: 41:41:41:41 .Ed .Pp The call .Bd -literal -offset indent log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); .Ed .Pp will add the appropriate debug message at priority .Dq Li kern.debug to the system log. .Sh SEE ALSO .Xr printf 3 , .Xr syslog 3 diff --git a/share/man/man9/prng.9 b/share/man/man9/prng.9 index 63132c28c198..20cfcf910442 100644 --- a/share/man/man9/prng.9 +++ b/share/man/man9/prng.9 @@ -1,99 +1,98 @@ .\"- .\" Copyright 2020 Conrad Meyer . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 5, 2020 .Dt PRNG 9 .Os .Sh NAME .Nm prng .Nd "Kernel pseudo-random number generators" .Sh SYNOPSIS .In sys/prng.h .Ft uint32_t .Fn prng32 void .Ft uint32_t .Fn prng32_bounded "uint32_t bound" .Ft uint64_t .Fn prng64 void .Ft uint64_t .Fn prng64_bounded "uint64_t bound" .Sh DESCRIPTION .Ss GENERIC PRNG ROUTINES .Nm is a family of fast, .Em non-cryptographic pseudo-random number generators. Unlike .Xr random 9 , .Fn prng32 , .Fn prng32_bounded , .Fn prng64 , and .Fn prng64_bounded avoid shared global state, removing unnecessary contention on SMP systems. The routines are not explicitly tied to any specific implementation, and may produce different specific sequences on different hosts, reboots, or versions of .Fx . Different CPUs in SMP systems are guaranteed to produce different sequences of integers. .Pp For .Em cryptographically secure random numbers generated by the .Xr random 4 kernel cryptographically secure random number generator subsystem, see .Xr arc4random 9 . -.Pp .Bl -tag -width indent .It Fn prng32 Generate a 32-bit integer uniformly distributed in [0, 2^32-1]. .It Fn prng32_bounded bound Generate an integer uniformly in the range [0, bound-1]. .It Fn prng64 Generate a 64-bit integer uniformly distributed in [0, 2^64-1]. .It Fn prng64_bounded bound Generate an integer uniformly in the range [0, bound-1]. .El .Pp These routines are not reentrant; they are not safe to use in interrupt handlers ("interrupt filters" in .Xr bus_setup_intr 9 terminology). They are safe to use in all other kernel contexts, including interrupt threads ("ithreads"). .Ss REPRODUCIBLE PRNG APIS In addition to these per-CPU helpers, the .In sys/prng.h header also exposes the entire API of the PCG family of PRNGs as inline functions. The PCG-C API is described in full at .Lk https://www.pcg-random.org/using-pcg-c.html . .Sh HISTORY .Nm was introduced in .Fx 13 . diff --git a/share/man/man9/sglist.9 b/share/man/man9/sglist.9 index 408d23573489..ec452194527b 100644 --- a/share/man/man9/sglist.9 +++ b/share/man/man9/sglist.9 @@ -1,614 +1,614 @@ .\" .\" Copyright (c) 2009 Hudson River Trading LLC .\" Written by: John H. Baldwin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 25, 2021 .Dt SGLIST 9 .Os .Sh NAME .Nm sglist , .Nm sglist_alloc , .Nm sglist_append , .Nm sglist_append_bio , .Nm sglist_append_mbuf , -.Nm sglist_append_mbuf_epg, +.Nm sglist_append_mbuf_epg , .Nm sglist_append_phys , .Nm sglist_append_sglist , .Nm sglist_append_single_mbuf , .Nm sglist_append_uio , .Nm sglist_append_user , .Nm sglist_append_vmpages , .Nm sglist_build , .Nm sglist_clone , .Nm sglist_consume_uio , .Nm sglist_count , .Nm sglist_count_mbuf_epg , .Nm sglist_count_vmpages , .Nm sglist_free , .Nm sglist_hold , .Nm sglist_init , .Nm sglist_join , .Nm sglist_length , .Nm sglist_reset , .Nm sglist_slice , .Nm sglist_split .Nd manage a scatter/gather list of physical memory addresses .Sh SYNOPSIS .In sys/types.h .In sys/sglist.h .Ft struct sglist * .Fn sglist_alloc "int nsegs" "int mflags" .Ft int .Fn sglist_append "struct sglist *sg" "void *buf" "size_t len" .Ft int .Fn sglist_append_bio "struct sglist *sg" "struct bio *bp" .Ft int .Fn sglist_append_mbuf_epg "struct sglist *sg" "struct mbuf *m" "size_t offset" "size_t len" .Ft int .Fn sglist_append_mbuf "struct sglist *sg" "struct mbuf *m" .Ft int .Fn sglist_append_phys "struct sglist *sg" "vm_paddr_t paddr" "size_t len" .Ft int .Fn sglist_append_sglist "struct sglist *sg" "struct sglist *source" "size_t offset" "size_t len" .Ft int .Fn sglist_append_single_mbuf "struct sglist *sg" "struct mbuf *m" .Ft int .Fn sglist_append_uio "struct sglist *sg" "struct uio *uio" .Ft int .Fn sglist_append_user "struct sglist *sg" "void *buf" "size_t len" "struct thread *td" .Ft int .Fn sglist_append_vmpages "struct sglist *sg" "vm_page_t *m" "size_t pgoff" "size_t len" .Ft struct sglist * .Fn sglist_build "void *buf" "size_t len" "int mflags" .Ft struct sglist * .Fn sglist_clone "struct sglist *sg" "int mflags" .Ft int .Fn sglist_consume_uio "struct sglist *sg" "struct uio *uio" "size_t resid" .Ft int .Fn sglist_count "void *buf" "size_t len" .Ft int .Fn sglist_count_mbuf_epg "struct mbuf *m" "size_t offset" "size_t len" .Ft int .Fn sglist_count_vmpages "vm_page_t *m" "size_t pgoff" "size_t len" .Ft void .Fn sglist_free "struct sglist *sg" .Ft struct sglist * .Fn sglist_hold "struct sglist *sg" .Ft void .Fn sglist_init "struct sglist *sg" "int maxsegs" "struct sglist_seg *segs" .Ft int .Fn sglist_join "struct sglist *first" "struct sglist *second" .Ft size_t .Fn sglist_length "struct sglist *sg" .Ft void .Fn sglist_reset "struct sglist *sg" .Ft int .Fn sglist_slice "struct sglist *original" "struct sglist **slice" "size_t offset" "size_t length" "int mflags" .Ft int .Fn sglist_split "struct sglist *original" "struct sglist **head" "size_t length" "int mflags" .Sh DESCRIPTION The .Nm API manages physical address ranges. Each list contains one or more elements. Each element contains a starting physical address and a length. Scatter/gather lists are read-only while they are shared. If one wishes to alter an existing scatter/gather list and does not hold the sole reference to the list, then one should create a new list instead of modifying the existing list. .Pp Each scatter/gather list object contains a reference count. New lists are created with a single reference. New references are obtained by calling .Nm sglist_hold and are released by calling .Nm sglist_free . .Ss Allocating and Initializing Lists Each .Nm object consists of a header structure and a variable-length array of scatter/gather list elements. The .Nm sglist_alloc function allocates a new list that contains a header and .Fa nsegs scatter/gather list elements. The .Fa mflags argument can be set to either .Dv M_NOWAIT or .Dv M_WAITOK . .Pp The .Nm sglist_count function returns the number of scatter/gather list elements needed to describe the physical address ranges mapped by a single kernel virtual address range. The kernel virtual address range starts at .Fa buf and is .Fa len bytes long. .Pp The .Nm sglist_count_mbuf_epg function returns the number of scatter/gather list elements needed to describe the external multipage mbuf buffer .Fa m . The ranges start at an offset of .Fa offset relative to the start of the buffer and is .Fa len bytes long. .Pp The .Nm sglist_count_vmpages function returns the number of scatter/gather list elements needed to describe the physical address ranges of a buffer backed by an array of virtual memory pages .Fa m . The buffer starts at an offset of .Fa pgoff bytes relative to the first page and is .Fa len bytes long. .Pp The .Nm sglist_build function allocates a new scatter/gather list object that describes the physical address ranges mapped by a single kernel virtual address range. The kernel virtual address range starts at .Fa buf and is .Fa len bytes long. The .Fa mflags argument can be set to either .Dv M_NOWAIT or .Dv M_WAITOK . .Pp The .Nm sglist_clone function returns a copy of an existing scatter/gather list object .Fa sg . The .Fa mflags argument can be set to either .Dv M_NOWAIT or .Dv M_WAITOK . This can be used to obtain a private copy of a scatter/gather list before modifying it. .Pp The .Nm sglist_init function initializes a scatter/gather list header. The header is pointed to by .Fa sg and is initialized to manage an array of .Fa maxsegs scatter/gather list elements pointed to by .Fa segs . This can be used to initialize a scatter/gather list header whose storage is not provided by .Nm sglist_alloc . In that case, the caller should not call .Nm sglist_free to release its own reference and is responsible for ensuring all other references to the list are dropped before it releases the storage for .Fa sg and .Fa segs . .Ss Constructing Scatter/Gather Lists The .Nm API provides several routines for building a scatter/gather list to describe one or more objects. Specifically, the .Nm sglist_append family of routines can be used to append the physical address ranges described by an object to the end of a scatter/gather list. All of these routines return 0 on success or an error on failure. If a request to append an address range to a scatter/gather list fails, the scatter/gather list will remain unchanged. .Pp The .Nm sglist_append function appends the physical address ranges described by a single kernel virtual address range to the scatter/gather list .Fa sg . The kernel virtual address range starts at .Fa buf and is .Fa len bytes long. .Pp The .Nm sglist_append_bio function appends the physical address ranges described by a single bio .Fa bp to the scatter/gather list .Fa sg . .Pp The .Nm sglist_append_mbuf_epg function appends the physical address ranges described by the external multipage .Xr mbuf 9 buffer .Fa ext_pgs to the scatter/gather list .Fa sg . The physical address ranges start at offset .Fa offset within .Fa ext_pgs and continue for .Fa len bytes. Note that unlike .Nm sglist_append_mbuf , .Nm sglist_append_mbuf_epg only adds ranges for a single mbuf, not an entire mbuf chain. .Pp The .Nm sglist_append_mbuf function appends the physical address ranges described by an entire mbuf chain .Fa m to the scatter/gather list .Fa sg . .Pp The .Nm sglist_append_mbuf function appends the physical address ranges described by a single mbuf .Fa m to the scatter/gather list .Fa sg . .Pp The .Nm sglist_append_phys function appends a single physical address range to the scatter/gather list .Fa sg . The physical address range starts at .Fa paddr and is .Fa len bytes long. .Pp The .Nm sglist_append_sglist function appends physical address ranges described by the scatter/gather list .Fa source to the scatter/gather list .Fa sg . The physical address ranges start at offset .Fa offset within .Fa source and continue for .Fa len bytes. .Pp The .Nm sglist_append_uio function appends the physical address ranges described by a .Xr uio 9 object to the scatter/gather list .Fa sg . Note that it is the caller's responsibility to ensure that the pages backing the I/O request are wired for the lifetime of .Fa sg . Note also that this routine does not modify .Fa uio . .Pp The .Nm sglist_append_user function appends the physical address ranges described by a single user virtual address range to the scatter/gather list .Fa sg . The user virtual address range is relative to the address space of the thread .Fa td . It starts at .Fa buf and is .Fa len bytes long. Note that it is the caller's responsibility to ensure that the pages backing the user buffer are wired for the lifetime of .Fa sg . .Pp The .Nm sglist_append_vmpages function appends the physical address ranges of a buffer backed by an array of virtual memory pages .Fa m . The buffer starts at an offset of .Fa pgoff bytes relative to the first page and is .Fa len bytes long. .Pp The .Nm sglist_consume_uio function is a variation of .Nm sglist_append_uio . As with .Nm sglist_append_uio , it appends the physical address ranges described by .Fa uio to the scatter/gather list .Fa sg . Unlike .Nm sglist_append_uio , however, .Nm sglist_consume_uio modifies the I/O request to indicate that the appended address ranges have been processed similar to calling .Xr uiomove 9 . This routine will only append ranges that describe up to .Fa resid total bytes in length. If the available segments in the scatter/gather list are exhausted before .Fa resid bytes are processed, then the .Fa uio structure will be updated to reflect the actual number of bytes processed, and .Nm sglist_consume_io will return zero to indicate success. In effect, this function will perform partial reads or writes. The caller can compare the .Fa uio_resid member of .Fa uio before and after calling .Nm sglist_consume_uio to determine the actual number of bytes processed. .Ss Manipulating Scatter/Gather Lists The .Nm sglist_join function appends physical address ranges from the scatter/gather list .Fa second onto .Fa first and then resets .Fa second to an empty list. It returns zero on success or an error on failure. .Pp The .Nm sglist_split function splits an existing scatter/gather list into two lists. The first .Fa length bytes described by the list .Fa original are moved to a new list .Fa *head . If .Fa original describes a total address range that is smaller than .Fa length bytes, then all of the address ranges will be moved to the new list at .Fa *head and .Fa original will be an empty list. The caller may supply an existing scatter/gather list in .Fa *head . If so, the list must be empty. Otherwise, the caller may set .Fa *head to .Dv NULL in which case a new scatter/gather list will be allocated. In that case, .Fa mflags may be set to either .Dv M_NOWAIT or .Dv M_WAITOK . Note that since the .Fa original list is modified by this call, it must be a private list with no other references. The .Nm sglist_split function returns zero on success or an error on failure. .Pp The .Nm sglist_slice function generates a new scatter/gather list from a sub-range of an existing scatter/gather list .Fa original . The sub-range to extract is specified by the .Fa offset and .Fa length parameters. The new scatter/gather list is stored in .Fa *slice . As with .Fa head for .Nm sglist_join , the caller may either provide an empty scatter/gather list, or it may set .Fa *slice to .Dv NULL in which case .Nm sglist_slice will allocate a new list subject to .Fa mflags . Unlike .Nm sglist_split , .Nm sglist_slice does not modify .Fa original and does not require it to be a private list. The .Nm sglist_split function returns zero on success or an error on failure. .Ss Miscellaneous Routines The .Nm sglist_reset function clears the scatter/gather list .Fa sg so that it no longer maps any address ranges. This can allow reuse of a single scatter/gather list object for multiple requests. .Pp The .Nm sglist_length function returns the total length of the physical address ranges described by the scatter/gather list .Fa sg . .Sh RETURN VALUES The .Nm sglist_alloc , .Nm sglist_build , and .Nm sglist_clone functions return a new scatter/gather list on success or .Dv NULL on failure. .Pp The .Nm sglist_append family of functions and the .Nm sglist_consume_uio , .Nm sglist_join , .Nm sglist_slice , and .Nm sglist_split functions return zero on success or an error on failure. .Pp The .Nm sglist_count family of functions return a count of scatter/gather list elements. .Pp The .Nm sglist_length function returns a count of address space described by a scatter/gather list in bytes. .Sh ERRORS The .Nm sglist_append functions return the following errors on failure: .Bl -tag -width Er .It Bq Er EINVAL The scatter/gather list has zero segments. .It Bq Er EFBIG There are not enough available segments in the scatter/gather list to append the specified physical address ranges. .El .Pp The .Nm sglist_consume_uio function returns the following error on failure: .Bl -tag -width Er .It Bq Er EINVAL The scatter/gather list has zero segments. .El .Pp The .Nm sglist_join function returns the following error on failure: .Bl -tag -width Er .It Bq Er EFBIG There are not enough available segments in the scatter/gather list .Fa first to append the physical address ranges from .Fa second . .El .Pp The .Nm sglist_slice function returns the following errors on failure: .Bl -tag -width Er .It Bq Er EINVAL The .Fa original scatter/gather list does not describe enough address space to cover the requested sub-range. .It Bq Er EINVAL The caller-supplied scatter/gather list in .Fa *slice is not empty. .It Bq Er ENOMEM An attempt to allocate a new scatter/gather list with .Dv M_NOWAIT set in .Fa mflags failed. .It Bq Er EFBIG There are not enough available segments in the caller-supplied scatter/gather list in .Fa *slice to describe the requested physical address ranges. .El .Pp The .Nm sglist_split function returns the following errors on failure: .Bl -tag -width Er .It Bq Er EDOOFUS The .Fa original scatter/gather list has more than one reference. .It Bq Er EINVAL The caller-supplied scatter/gather list in .Fa *head is not empty. .It Bq Er ENOMEM An attempt to allocate a new scatter/gather list with .Dv M_NOWAIT set in .Fa mflags failed. .It Bq Er EFBIG There are not enough available segments in the caller-supplied scatter/gather list in .Fa *head to describe the requested physical address ranges. .El .Sh SEE ALSO .Xr g_bio 9 , .Xr malloc 9 , .Xr mbuf 9 , .Xr uio 9 .Sh HISTORY This API was first introduced in .Fx 8.0 . diff --git a/share/man/man9/vrele.9 b/share/man/man9/vrele.9 index 1eae4426e7ef..a0d6a1e3f0ac 100644 --- a/share/man/man9/vrele.9 +++ b/share/man/man9/vrele.9 @@ -1,103 +1,103 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 1996 Doug Rabson .\" Copyright (c) 2010 Konstantin Belousov .\" .\" All rights reserved. .\" .\" This program is free software. .\" .\" 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 DEVELOPERS ``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 DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 24, 2016 .Dt VRELE 9 .Os .Sh NAME .Nm vput , .Nm vrele , .Nm vunref .Nd decrement the use count for a vnode .Sh SYNOPSIS .In sys/param.h .In sys/vnode.h .Ft void .Fn vput "struct vnode *vp" .Ft void .Fn vrele "struct vnode *vp" .Ft void .Fn vunref "struct vnode *vp" .Sh DESCRIPTION Decrement the .Va v_usecount field of a vnode. .Bl -tag -width 2n .It Fa vp the vnode to decrement .El .Pp The .Fn vrele function takes an unlocked vnode and returns with the vnode unlocked. .Pp The .Fn vput function should be given a locked vnode as argument, the vnode is unlocked after the function returned. The .Fn vput is operationally equivalent to calling .Xr VOP_UNLOCK 9 followed by -.Xr vrele 9 , +.Fn vrele , with less overhead. .Pp The .Fn vunref function takes a locked vnode as argument, and returns with the vnode locked. .Pp Any code in the system which signified its use of a vnode by usecount should call one of the listed function to decrement use counter. If the .Va v_usecount field of the non-doomed vnode reaches zero, then it will be inactivated and placed on the free list. .Pp The .Fn vrele function may lock the vnode. All three functions may sleep. .Pp The hold count for the vnode is always greater or equal to the usecount. Non-forced unmount fails when mount point owns a vnode that has non-zero usecount, see .Xr vflush 9 . .Sh SEE ALSO .Xr vget 9 , .Xr vnode 9 , .Xr vref 9 , .Xr vrefcnt 9 .Sh AUTHORS This manual page was written by .An Doug Rabson and .An Konstantin Belousov .