diff --git a/lib/libdevctl/devctl.3 b/lib/libdevctl/devctl.3 index a6823a0b3c6a..c8a4704825c2 100644 --- a/lib/libdevctl/devctl.3 +++ b/lib/libdevctl/devctl.3 @@ -1,450 +1,450 @@ .\" .\" Copyright (c) 2014 John 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 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. .\" .Dd April 4, 2019 .Dt DEVCTL 3 .Os .Sh NAME .Nm devctl , .Nm devctl_attach , .Nm devctl_clear_driver , .Nm devctl_delete , .Nm devctl_detach , .Nm devctl_disable , .Nm devctl_enable , .Nm devctl_freeze , .Nm devctl_getpath , .Nm devctl_rescan , .Nm devctl_reset , .Nm devctl_resume , .Nm devctl_set_driver , .Nm devctl_suspend , .Nm devctl_thaw .Nd device control library .Sh LIBRARY .Lb libdevctl .Sh SYNOPSIS .In devctl.h .Ft int .Fn devctl_attach "const char *device" .Ft int .Fn devctl_clear_driver "const char *device" "bool force" .Ft int .Fn devctl_delete "const char *device" "bool force" .Ft int .Fn devctl_detach "const char *device" "bool force" .Ft int .Fn devctl_disable "const char *device" "bool force_detach" .Ft int .Fn devctl_enable "const char *device" .Ft int .Fn devctl_freeze "void" .Ft int .Fn devctl_getpath "const char *device" "const char *locator" "char **buffer" .Ft int .Fn devctl_rescan "const char *device" .Ft int .Fn devctl_reset "const char *device" "bool detach" .Ft int .Fn devctl_resume "const char *device" .Ft int .Fn devctl_set_driver "const char *device" "const char *driver" "bool force" .Ft int .Fn devctl_suspend "const char *device" .Ft int .Fn devctl_thaw "void" .Sh DESCRIPTION The .Nm library adjusts the state of devices in the kernel's internal device hierarchy. Each control operation accepts a .Fa device argument that identifies the device to adjust. The .Fa device may be specified as either the name of an existing device or as a bus-specific address. The following bus-specific address formats are currently supported: .Bl -tag -offset indent .It Sy pci Ns Fa domain Ns : Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function A PCI device with the specified .Fa domain , .Fa bus , .Fa slot , and .Fa function . .It Sy pci Ns Fa bus Ns : Ns Fa slot Ns : Ns Fa function A PCI device in domain zero with the specified .Fa bus , .Fa slot , and .Fa function . .It Fa handle A device with an ACPI handle of .Fa handle . The handle must be specified as an absolute path and must begin with a .Dq \e . .El .Pp The .Fn devctl_attach function probes a device and attaches a suitable device driver if one is found. .Pp The .Fn devctl_detach function detaches a device from its current device driver. The device is left detached until either a new driver for its parent bus is loaded or the device is explicitly probed via .Fn devctl_attach . If .Fa force is true, the current device driver will be detached even if the device is busy. .Pp The .Fn devctl_delete function deletes a device from the device tree. No If .Fa force is true, the device is deleted even if the device is physically present. .Pp The .Fn devctl_disable function disables a device. If the device is currently attached to a device driver, the device driver will be detached from the device, but the device will retain its current name. If .Fa force_detach is true, the current device driver will be detached even if the device is busy. The device will remain disabled and detached until it is explicitly enabled via .Fn devctl_enable . .Pp The .Fn devctl_enable function re-enables a disabled device. The device will probe and attach if a suitable device driver is found. .Pp The .Fn devctl_suspend function suspends a device. This may include placing the device in a reduced power state, but any device driver currently attached to the device will remain attached. .Pp The .Fn devctl_resume function resumes a suspended device to a fully working state. .Pp The .Fn devctl_set_driver function attaches a device driver named .Fa driver to a device. If the device is already attached and .Fa force is false, the request will fail. If the device is already attached and .Fa force is true, the device will be detached from its current device driver before it is attached to the new device driver. .Pp The .Fn devctl_clear_driver function resets a device so that it can be attached to any valid device driver rather than only drivers with a previously specified name. This function is used to undo a previous call to .Fn devctl_set_driver . If the device is already attached and .Fa force is false, the request will fail. If the device is already attached and .Fa force is true, the device will be detached from its current device driver. After the device's name is reset, it is reprobed and attached to a suitable device driver if one is found. .Pp The .Fn devctl_rescan function rescans a bus device checking for devices that have been added or removed. .Pp The .Fn devctl_getpath retrieves the path to the .Fa device from the kernel using the .Fa locator method to construct the path. The .Fa buffer pointer is updated with an allocated buffer that must be freed with -.Xr free . +.Xr free 3 . .Pp The .Fn devctl_freeze function freezes probe and attach processing initiated in response to drivers being loaded. .Pp The .Fn devctl_thaw function resumes (thaws the freeze) probe and attach processing initiated in response to drivers being loaded. .Pp The .Fn devctl_reset function resets the specified device using bus-specific reset method. The .Fa detach argument, if true, specifies that the device driver is detached before the reset, and re-attached afterwards. If false, the device is suspended before the reset, and resumed after. .Sh RETURN VALUES .Rv -std devctl_attach devctl_clear_driver devctl_delete devctl_detach \ devctl_disable devctl_enable devctl_suspend devctl_rescan devctl_resume \ devctl_set_driver .Sh ERRORS In addition to specific errors noted below, all of the .Nm functions may fail for any of the errors described in .Xr open 2 as well as: .Bl -tag -width Er .It Bq Er EINVAL The device name is too long. .It Bq Er ENOENT No existing device matches the specified name or location. .It Bq Er EPERM The current process is not permitted to adjust the state of .Fa device . .El .Pp The .Fn devctl_attach function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The device is already attached. .It Bq Er ENOMEM An internal memory allocation request failed. .It Bq Er ENXIO The device is disabled. .It Bq Er ENXIO No suitable driver for the device could be found, or the driver failed to attach. .El .Pp The .Fn devctl_detach function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The current device driver for .Fa device is busy and cannot detach at this time. Note that some drivers may return this even if .Fa force is true. .It Bq Er ENXIO The device is not attached to a driver. .It Bq Er ENXIO The current device driver for .Fa device does not support detaching. .El .Pp The .Fn devctl_enable function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The device is already enabled. .It Bq Er ENOMEM An internal memory allocation request failed. .It Bq Er ENXIO No suitable driver for the device could be found, or the driver failed to attach. .El .Pp The .Fn devctl_disable function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The current device driver for .Fa device is busy and cannot detach at this time. Note that some drivers may return this even if .Fa force_detach is true. .It Bq Er ENXIO The device is already disabled. .It Bq Er ENXIO The current device driver for .Fa device does not support detaching. .El .Pp The .Fn devctl_suspend function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The device is already suspended. .It Bq Er EINVAL The device to be suspended is the root bus device. .El .Pp The .Fn devctl_resume function may fail if: .Bl -tag -width Er .It Bq Er EINVAL The device is not suspended. .It Bq Er EINVAL The device to be resumed is the root bus device. .El .Pp The .Fn devctl_set_driver function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The device is currently attached to a device driver and .Fa force is false. .It Bq Er EBUSY The current device driver for .Fa device is busy and cannot detach at this time. .It Bq Er EFAULT The .Fa driver argument points outside the process' allocated address space. .It Bq Er ENOENT No device driver with the requested name exists. .It Bq Er ENOMEM An internal memory allocation request failed. .It Bq Er ENXIO The device is disabled. .It Bq Er ENXIO The new device driver failed to attach. .El .Pp The .Fn devctl_clear_driver function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The device is currently attached to a device driver and .Fa force is false. .It Bq Er EBUSY The current device driver for .Fa device is busy and cannot detach at this time. .It Bq Er EINVAL The device is not configured for a specific device driver name. .It Bq Er ENXIO The device driver chosen after reprobing failed to attach. .El .Pp The .Fn devctl_rescan function may fail if: .Bl -tag -width Er .It Bq Er ENXIO The device is not attached to a driver. .It Bq Er ENXIO The bus driver does not support rescanning. .El .Pp The .Fn devctl_delete function may fail if: .Bl -tag -width Er .It Bq Er EBUSY The device is physically present and .Fa force is false. .It Bq Er EINVAL .Fa dev is the root device of the device tree. .El .Pp The .Fn devctl_reset function may fail if: .Bl -tag -width Er .It Bq Er ENXIO The bus does not implement the reset method. .It Bq Er ETIMEDOUT The device failed to respond after the reset in the time limits specific to the bus. .El The .Fn devctl_reset function may also return errors caused by the attach, detach, suspend, and resume methods of the device driver. .Sh SEE ALSO .Xr devinfo 3 , .Xr devstat 3 , .Xr devctl 8 .Sh HISTORY The .Nm library first appeared in .Fx 10.3 . .Sh BUGS If a device is suspended individually via .Fn devctl_suspend and the entire machine is subsequently suspended, the device will be resumed when the machine resumes. .Pp Similarly, if the device is suspended, and .Fn devctl_reset is called on the device with .Fa detach set to .Va false , the device is resumed by the .Fn devctl_reset call. Or, if the driver for the device is detached manually, and .Fn devctl_reset is called on the device with .Fa detach set to .Va true , device reset re-attaches the driver. diff --git a/lib/libthr/libthr.3 b/lib/libthr/libthr.3 index 6d33f4c378ce..35a7467eec14 100644 --- a/lib/libthr/libthr.3 +++ b/lib/libthr/libthr.3 @@ -1,362 +1,362 @@ .\" Copyright (c) 2005 Robert N. M. Watson .\" Copyright (c) 2014,2015,2021 The FreeBSD Foundation, Inc. .\" All rights reserved. .\" .\" Part of this documentation was written by .\" Konstantin Belousov under sponsorship .\" from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS 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 AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd October 1, 2021 .Dt LIBTHR 3 .Os .Sh NAME .Nm libthr .Nd "1:1 POSIX threads library" .Sh LIBRARY .Lb libthr .Sh SYNOPSIS .In pthread.h .Sh DESCRIPTION The .Nm library provides a 1:1 implementation of the .Xr pthread 3 library interfaces for application threading. It has been optimized for use by applications expecting system scope thread semantics. .Pp The library is tightly integrated with the run-time link editor .Xr ld-elf.so.1 1 and .Lb libc ; all three components must be built from the same source tree. Mixing .Li libc and .Nm libraries from different versions of .Fx is not supported. The run-time linker .Xr ld-elf.so.1 1 has some code to ensure backward-compatibility with older versions of .Nm . .Pp The man page documents the quirks and tunables of the .Nm . When linking with .Li -lpthread , the run-time dependency .Li libthr.so.3 is recorded in the produced object. .Sh MUTEX ACQUISITION A locked mutex (see .Xr pthread_mutex_lock 3 ) is represented by a volatile variable of type .Dv lwpid_t , which records the global system identifier of the thread owning the lock. .Nm performs a contested mutex acquisition in three stages, each of which is more resource-consuming than the previous. The first two stages are only applied for a mutex of .Dv PTHREAD_MUTEX_ADAPTIVE_NP type and .Dv PTHREAD_PRIO_NONE protocol (see .Xr pthread_mutexattr 3 ) . .Pp First, on SMP systems, a spin loop is performed, where the library attempts to acquire the lock by .Xr atomic 9 operations. The loop count is controlled by the .Ev LIBPTHREAD_SPINLOOPS environment variable, with a default value of 2000. .Pp If the spin loop was unable to acquire the mutex, a yield loop is executed, performing the same .Xr atomic 9 acquisition attempts as the spin loop, but each attempt is followed by a yield of the CPU time of the thread using the .Xr sched_yield 2 syscall. By default, the yield loop is not executed. This is controlled by the .Ev LIBPTHREAD_YIELDLOOPS environment variable. .Pp If both the spin and yield loops failed to acquire the lock, the thread is taken off the CPU and put to sleep in the kernel with the .Xr _umtx_op 2 syscall. The kernel wakes up a thread and hands the ownership of the lock to the woken thread when the lock becomes available. .Sh THREAD STACKS Each thread is provided with a private user-mode stack area used by the C runtime. The size of the main (initial) thread stack is set by the kernel, and is controlled by the .Dv RLIMIT_STACK process resource limit (see .Xr getrlimit 2 ) . .Pp By default, the main thread's stack size is equal to the value of .Dv RLIMIT_STACK for the process. If the .Ev LIBPTHREAD_SPLITSTACK_MAIN environment variable is present in the process environment (its value does not matter), the main thread's stack is reduced to 4MB on 64bit architectures, and to 2MB on 32bit architectures, when the threading library is initialized. The rest of the address space area which has been reserved by the kernel for the initial process stack is used for non-initial thread stacks in this case. The presence of the .Ev LIBPTHREAD_BIGSTACK_MAIN environment variable overrides .Ev LIBPTHREAD_SPLITSTACK_MAIN ; it is kept for backward-compatibility. .Pp The size of stacks for threads created by the process at run-time with the .Xr pthread_create 3 call is controlled by thread attributes: see .Xr pthread_attr 3 , in particular, the .Xr pthread_attr_setstacksize 3 , .Xr pthread_attr_setguardsize 3 and .Xr pthread_attr_setstackaddr 3 functions. If no attributes for the thread stack size are specified, the default non-initial thread stack size is 2MB for 64bit architectures, and 1MB for 32bit architectures. .Sh RUN-TIME SETTINGS The following environment variables are recognized by .Nm and adjust the operation of the library at run-time: .Bl -tag -width "Ev LIBPTHREAD_SPLITSTACK_MAIN" .It Ev LIBPTHREAD_BIGSTACK_MAIN Disables the reduction of the initial thread stack enabled by .Ev LIBPTHREAD_SPLITSTACK_MAIN . .It Ev LIBPTHREAD_SPLITSTACK_MAIN Causes a reduction of the initial thread stack, as described in the section .Sx THREAD STACKS . This was the default behaviour of .Nm before .Fx 11.0 . .It Ev LIBPTHREAD_SPINLOOPS The integer value of the variable overrides the default count of iterations in the .Li spin loop of the mutex acquisition. The default count is 2000, set by the .Dv MUTEX_ADAPTIVE_SPINS constant in the .Nm sources. .It Ev LIBPTHREAD_YIELDLOOPS A non-zero integer value enables the yield loop in the process of the mutex acquisition. The value is the count of loop operations. .It Ev LIBPTHREAD_QUEUE_FIFO The integer value of the variable specifies how often blocked threads are inserted at the head of the sleep queue, instead of its tail. Bigger values reduce the frequency of the FIFO discipline. The value must be between 0 and 255. .It Dv LIBPTHREAD_UMTX_MIN_TIMEOUT The minimal amount of time, in nanoseconds, the thread is required to sleep for pthread operations specifying a timeout. If the operation requests a timeout less than the value provided, it is silently increased to the value. The value of zero means no minimum (default). .Pp .El The following .Dv sysctl MIBs affect the operation of the library: .Bl -tag -width "Dv debug.umtx.robust_faults_verbose" .It Dv kern.ipc.umtx_vnode_persistent By default, a shared lock backed by a mapped file in memory is automatically destroyed on the last unmap of the corresponding file's page, which is allowed by POSIX. Setting the sysctl to 1 makes such a shared lock object persist until the vnode is recycled by the Virtual File System. Note that in case file is not opened and not mapped, the kernel might recycle it at any moment, making this sysctl less useful than it sounds. .It Dv kern.ipc.umtx_max_robust The maximal number of robust mutexes allowed for one thread. The kernel will not unlock more mutexes than specified, see -.Xr _umtx_op +.Xr _umtx_op 2 for more details. The default value is large enough for most useful applications. .It Dv debug.umtx.robust_faults_verbose A non zero value makes kernel emit some diagnostic when the robust mutexes unlock was prematurely aborted after detecting some inconsistency, as a measure to prevent memory corruption. .El .Pp The .Dv RLIMIT_UMTXP limit (see .Xr getrlimit 2 ) defines how many shared locks a given user may create simultaneously. .Sh INTERACTION WITH RUN-TIME LINKER On load, .Nm installs interposing handlers into the hooks exported by .Li libc . The interposers provide real locking implementation instead of the stubs for single-threaded processes in .Li libc , cancellation support and some modifications to the signal operations. .Pp .Nm cannot be unloaded; the .Xr dlclose 3 function does not perform any action when called with a handle for .Nm . One of the reasons is that the internal interposing of .Li libc functions cannot be undone. .Sh SIGNALS The implementation interposes the user-installed .Xr signal 3 handlers. This interposing is done to postpone signal delivery to threads which entered (libthr-internal) critical sections, where the calling of the user-provided signal handler is unsafe. An example of such a situation is owning the internal library lock. When a signal is delivered while the signal handler cannot be safely called, the call is postponed and performed until after the exit from the critical section. This should be taken into account when interpreting .Xr ktrace 1 logs. .Sh PROCESS-SHARED SYNCHRONIZATION OBJECTS In the .Li libthr implementation, user-visible types for all synchronization objects (e.g. pthread_mutex_t) are pointers to internal structures, allocated either by the corresponding .Fn pthread__init method call, or implicitly on first use when a static initializer was specified. The initial implementation of process-private locking object used this model with internal allocation, and the addition of process-shared objects was done in a way that did not break the application binary interface. .Pp For process-private objects, the internal structure is allocated using either .Xr malloc 3 or, for .Xr pthread_mutex_init 3 , an internal memory allocator implemented in .Nm . The internal allocator for mutexes is used to avoid bootstrap issues with many .Xr malloc 3 implementations which need working mutexes to function. The same allocator is used for thread-specific data, see .Xr pthread_setspecific 3 , for the same reason. .Pp For process-shared objects, the internal structure is created by first allocating a shared memory segment using .Xr _umtx_op 2 operation .Dv UMTX_OP_SHM , and then mapping it into process address space with .Xr mmap 2 with the .Dv MAP_SHARED flag. The POSIX standard requires that: .Bd -literal only the process-shared synchronization object itself can be used for performing synchronization. It need not be referenced at the address used to initialize it (that is, another mapping of the same object can be used). .Ed .Pp With the .Fx implementation, process-shared objects require initialization in each process that use them. In particular, if you map the shared memory containing the user portion of a process-shared object already initialized in different process, locking functions do not work on it. .Pp Another broken case is a forked child creating the object in memory shared with the parent, which cannot be used from parent. Note that processes should not use non-async-signal safe functions after .Xr fork 2 anyway. .Sh SEE ALSO .Xr ktrace 1 , .Xr ld-elf.so.1 1 , .Xr _umtx_op 2 , .Xr errno 2 , .Xr getrlimit 2 , .Xr thr_exit 2 , .Xr thr_kill 2 , .Xr thr_kill2 2 , .Xr thr_new 2 , .Xr thr_self 2 , .Xr thr_set_name 2 , .Xr dlclose 3 , .Xr dlopen 3 , .Xr getenv 3 , .Xr pthread_attr 3 , .Xr pthread_attr_setstacksize 3 , .Xr pthread_create 3 , .Xr signal 3 , .Xr atomic 9 .Sh HISTORY The .Nm library first appeared in .Fx 5.2 . .Sh AUTHORS .An -nosplit The .Nm library was originally created by .An Jeff Roberson Aq Mt jeff@FreeBSD.org , and enhanced by .An Jonathan Mini Aq Mt mini@FreeBSD.org and .An Mike Makonnen Aq Mt mtm@FreeBSD.org . It has been substantially rewritten and optimized by .An David Xu Aq Mt davidxu@FreeBSD.org . diff --git a/share/man/man4/disk.4 b/share/man/man4/disk.4 index 6451ff0e7370..dfe0059263ee 100644 --- a/share/man/man4/disk.4 +++ b/share/man/man4/disk.4 @@ -1,208 +1,208 @@ .\" Copyright (c) 2020 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. 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. .\" .Dd November 20, 2020 .Dt disk 4 .Os .Sh NAME .Nm disk .Nd common disk interfaces .Sh SYNOPSIS .Cd device cd .Sh DESCRIPTION Common block device IOCTLs .Pp All the block devices in the system should support these disk .Xr ioctl 2 commands defined here. Much of this information is also available via the .Xr geom 2 attributes. .Sh IOCTLS The following .Xr ioctl 2 calls apply to disk drives, and are defined in the .In sys/disk.h header file. .Bl -tag -width DIOCGPROVIDERNAME .It Dv DIOCGSECTORSIZE .Pq Li "u_int" Get the sector or block size of the device in bytes. The sector size is the smallest unit of data which can be transferred from this device. This is usually a power of 2 but it might not be (e.g. CDROM audio). Operations to block devices such as .Xr lseek 2 , .Xr read 2 , and -.Xr write +.Xr write 2 may only be performed at file offsets that are integral multiple of this size. .It Dv DIOCGMEDIASIZE .Pq Li "off_t" Get the size of the entire device in bytes. This should be a multiple of the sector size. .It Dv DIOCGFWSECTORS .Pq Li "u_int" Return the firmware's notion of number of sectors per track. This value is mostly used for compatibility with various ill designed disk label formats. Use this value only when absolutely required. Its interpretation and use is largely obsolete. .It Dv DIOCGFWHEADS .Pq Li "u_int" Return the firmware's notion of number of heads per cylinder. This value is mostly used for compatibility with various ill designed disk label formats. Use this value only when absolutely required. Its interpretation and use is largely obsolete. .It Dv DIOCGFLUSH Flush write cache of the device. .It Dv DIOCGDELETE .Pq Li "off_t[2]" Mark data on the device as unused. The first element is the offset to start deleting. The second element is the length to delete. Providers may use this information to free storage or instruct storage devices the contents can be discarded. .It Dv DIOCGIDENT .Pq Li "char[DISK_IDENT_SIZE]" Get the ident for this provider. Ident is a unique and fixed identifier for this provider. Ident's properties are as follow: .Bl -bullet .It preserved between reboots, .It preserved across a provider being detached/attached, .It provider's name can change - ident can't, .It ident value should not be based on on-disk metadata; in other words, copying whole data from one disk to another should not yield the same ident for the other disk, .It there can be more than one provider with the same ident, but only if they point at exactly the same physical storage, this is the case for multipathing for example, .It GEOM classes that consume a single provider and provide single provider, like .Xr geli 8 , and .Xr gbde 8 , the identifier should be formed by attaching that provider's class name to the ident of the underlying provider, .It ident is an NUL-terminated ASCII string (is printable), .It ident is optional and applications can't relay on its presence. .El .It Dv DIOCGPROVIDERNAME .Pq Li "char[MAXPATHLEN]" Store the provider name for the device in a buffer. The buffer must be at least MAXPATHLEN bytes long. .It Dv DIOCGSTRIPESIZE .Pq Li "off_t" Get the size of the device's optimal access block in bytes. This should be a multiple of the sector size. .It Dv DIOCGSTRIPEOFFSET .Pq Li "off_t" Get the offset of the first device's optimal access block in bytes. This should be a multiple of the sector size. .It Dv DIOCGPHYSPATH .Pq Li "char[MAXPATHLEN]" Get a string defining the physical path for a given provider. This has similar rules to ident, but is intended to uniquely identify the physical location of the device, not the current occupant of that location. The buffer must be at least MAXPATHLEN bytes long. .It Dv DIOCGATTR .Pq Li "struct diocgattr_arg" .Bd -literal -offset indent struct diocgattr_arg { char name[64]; int len; union { char str[DISK_IDENT_SIZE]; off_t off; int i; uint16_t u16; } value; }; .Ed Get a geom attribute from the provider. Format of the returned data is specific to the attribute. .It Dv DIOCZONECMD .Pq Li "struct disk_zone_arg" Send disk zone commands. .It Dv DIOCSKERNELDUMP .Pq Li "struct diocskerneldump_arg" Enable/Disable the device for kernel core dumps. .It Dv DIOCGKERNELDUMP .Pq Li "struct diocskerneldump_arg" Get current kernel netdump configuration details for a given index. .Bd -literal -offset indent /* * Sentinel values for kda_index. * * If kda_index is KDA_REMOVE_ALL, all dump configurations are cleared. * * If kda_index is KDA_REMOVE_DEV, all dump configurations for the specified * device are cleared. * * If kda_index is KDA_REMOVE, only the specified dump configuration for the * given device is removed from the list of fallback dump configurations. * * If kda_index is KDA_APPEND, the dump configuration is added after all * existing dump configurations. * * Otherwise, the new configuration is inserted into the fallback dump list at * index 'kda_index'. */ #define KDA_REMOVE UINT8_MAX #define KDA_REMOVE_ALL (UINT8_MAX - 1) #define KDA_REMOVE_DEV (UINT8_MAX - 2) #define KDA_APPEND (UINT8_MAX - 3) struct diocskerneldump_arg { uint8_t kda_index; uint8_t kda_compression; uint8_t kda_encryption; uint8_t kda_key[KERNELDUMP_KEY_MAX_SIZE]; uint32_t kda_encryptedkeysize; uint8_t *kda_encryptedkey; char kda_iface[IFNAMSIZ]; union kd_ip kda_server; union kd_ip kda_client; union kd_ip kda_gateway; uint8_t kda_af; }; .Ed .El .Sh HISTORY The manual page was written by .An M Warner Losh Aq Mt imp@FreeBSD.org from text largely derived from .In sys/disk.h . diff --git a/share/man/man4/ng_iface.4 b/share/man/man4/ng_iface.4 index 0579028b4c74..e2dee22b67b9 100644 --- a/share/man/man4/ng_iface.4 +++ b/share/man/man4/ng_iface.4 @@ -1,164 +1,164 @@ .\" Copyright (c) 1996-1999 Whistle Communications, Inc. .\" All rights reserved. .\" .\" Subject to the following obligations and disclaimer of warranty, use and .\" redistribution of this software, in source or object code forms, with or .\" without modifications are expressly permitted by Whistle Communications; .\" provided, however, that: .\" 1. Any and all reproductions of the source or object code must include the .\" copyright notice above and the following disclaimer of warranties; and .\" 2. No rights are granted, in any manner or form, to use Whistle .\" Communications, Inc. trademarks, including the mark "WHISTLE .\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as .\" such appears in the above copyright notice or in the software. .\" .\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, .\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. .\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY .\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS .\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. .\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES .\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING .\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER 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 WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY .\" OF SUCH DAMAGE. .\" .\" Author: Archie Cobbs .\" $Whistle: ng_iface.8,v 1.5 1999/01/25 23:46:26 archie Exp $ .\" .Dd July 31, 2020 .Dt NG_IFACE 4 .Os .Sh NAME .Nm ng_iface .Nd interface netgraph node type .Sh SYNOPSIS .In netgraph/ng_iface.h .Sh DESCRIPTION An .Nm iface node is both a netgraph node and a system networking interface. When an .Nm iface node is created, a new interface appears which is accessible via .Xr ifconfig 8 . .Nm Iface node interfaces are named .Dv ng0 , .Dv ng1 , etc. When a node is shutdown, the corresponding interface is removed and the interface name becomes available for reuse by future .Nm iface nodes; new nodes always take the first unused interface. The node itself is assigned the same name as its interface, unless the name already exists, in which case the node remains unnamed. .Pp An .Nm iface node has a single hook corresponding to each supported protocol. Packets transmitted via the interface flow out the corresponding protocol-specific hook. Similarly, packets received on a hook appear on the interface as packets received into the corresponding protocol stack. The currently supported protocols are IP and IPv6. .Pp An .Nm iface node can be configured as a point-to-point interface or a broadcast interface. The configuration can only be changed when the interface is down. The default mode is point-to-point. .Pp .Nm Iface nodes support the Berkeley Packet Filter (BPF). .Sh HOOKS This node type supports the following hooks: .Bl -tag -width ".Va inet6" .It Va inet Transmission and reception of IP packets. .It Va inet6 Transmission and reception of IPv6 packets. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_IFACE_GET_IFNAME Pq Ic getifname Returns the name of the associated interface as a .Dv NUL Ns -terminated .Tn ASCII string. Normally this is the same as the name of the node. .It Dv NGM_IFACE_GET_IFINDEX Pq Ic getifindex Returns the global index of the associated interface as a 32 bit integer. .It Dv NGM_IFACE_POINT2POINT Pq Ic point2point Set the interface to point-to-point mode. The interface must not currently be up. .It Dv NGM_IFACE_BROADCAST Pq Ic broadcast Set the interface to broadcast mode. The interface must not currently be up. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message. The associated interface is removed and becomes available for use by future .Nm iface nodes. .Pp Unlike most other node types, an .Nm iface node does .Em not go away when all hooks have been disconnected; rather, and explicit .Dv NGM_SHUTDOWN control message is required. .Sh ALTQ Support The .Nm interface supports ALTQ bandwidth management feature. However, .Nm is a special case, since it is not a physical interface with limited bandwidth. One should not turn ALTQ on .Nm if the latter corresponds to some tunneled connection, e.g.\& PPPoE or PPTP. In this case, ALTQ should be configured on the interface that is used to transmit the encapsulated packets. In case when your graph ends up with some kind of serial line, either synchronous or modem, the .Nm is the right place to turn ALTQ on. .Sh Nesting .Nm supports nesting, a configuration when traffic of one .Nm interface flows through the other. The default maximum allowed nesting level is 2. It can be changed at runtime setting .Xr sysctl 8 variable .Va net.graph.iface.max_nesting to the desired level of nesting. .Sh SEE ALSO .Xr altq 4 , .Xr bpf 4 , .Xr netgraph 4 , .Xr ng_cisco 4 , .Xr ifconfig 8 , -.Xr ngctl 8 -.Xr sysctl +.Xr ngctl 8 , +.Xr sysctl 8 .Sh HISTORY The .Nm iface node type was implemented in .Fx 4.0 . .Sh AUTHORS .An Archie Cobbs Aq Mt archie@FreeBSD.org diff --git a/share/man/man4/ng_nat.4 b/share/man/man4/ng_nat.4 index 53cd841a7392..bf9ec4052733 100644 --- a/share/man/man4/ng_nat.4 +++ b/share/man/man4/ng_nat.4 @@ -1,407 +1,407 @@ .\" Copyright (c) 2005 Gleb Smirnoff .\" 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. .\" .Dd January 24, 2021 .Dt NG_NAT 4 .Os .Sh NAME .Nm ng_nat .Nd "NAT netgraph node type" .Sh SYNOPSIS .In netgraph/ng_nat.h .Sh DESCRIPTION An .Nm node performs network address translation (NAT) of IPv4 packets passing through it. A .Nm nat node uses .Xr libalias 3 engine for packet aliasing. .Sh HOOKS This node type has two hooks: .Bl -tag -width ".Va out" .It Va out Packets received on this hook are considered outgoing and will be masqueraded to a configured address. .It Va in Packets coming on this hook are considered incoming and will be dealiased. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_NAT_SET_IPADDR Pq Ic setaliasaddr Configure aliasing address for a node. After both hooks have been connected and aliasing address was configured, a node is ready for aliasing operation. .It Dv NGM_NAT_SET_MODE Pq Ic setmode Set node's operation mode using supplied .Vt "struct ng_nat_mode" . .Bd -literal struct ng_nat_mode { uint32_t flags; uint32_t mask; }; /* Supported flags: */ #define NG_NAT_LOG 0x01 #define NG_NAT_DENY_INCOMING 0x02 #define NG_NAT_SAME_PORTS 0x04 #define NG_NAT_UNREGISTERED_ONLY 0x10 #define NG_NAT_RESET_ON_ADDR_CHANGE 0x20 #define NG_NAT_PROXY_ONLY 0x40 #define NG_NAT_REVERSE 0x80 #define NG_NAT_UNREGISTERED_CGN 0x100 .Ed .Pp The corresponding libalias flags can be found by replacing the .Vt "NG_NAT" prefix with .Vt "PKT_ALIAS" . .It Dv NGM_NAT_SET_TARGET Pq Ic settarget Configure target address for a node. When an incoming packet not associated with any pre-existing aliasing link arrives at the host machine, it will be sent to the specified address. .It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport Redirect incoming connections arriving to given port(s) to another host and port(s). The following .Vt "struct ng_nat_redirect_port" must be supplied as argument. .Bd -literal #define NG_NAT_DESC_LENGTH 64 struct ng_nat_redirect_port { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Redirection is assigned an unique ID which is returned as response to this message, and information about redirection added to list of static redirects which later can be retrieved by .Dv NGM_NAT_LIST_REDIRECTS message. .It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr Redirect traffic for public IP address to a machine on the local network. This function is known as .Em static NAT . The following .Vt "struct ng_nat_redirect_addr" must be supplied as argument. .Bd -literal struct ng_nat_redirect_addr { struct in_addr local_addr; struct in_addr alias_addr; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Unique ID for this redirection is returned as response to this message. .It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto Redirect incoming IP packets of protocol .Va proto (see .Xr protocols 5 ) to a machine on the local network. The following .Vt "struct ng_nat_redirect_proto" must be supplied as argument. .Bd -literal struct ng_nat_redirect_proto { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Unique ID for this redirection is returned as response to this message. .It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic Mark redirection with specified ID as dynamic, i.e., it will serve for exactly one next connection and then will be automatically deleted from internal links table. Only fully specified links can be made dynamic. The redirection with this ID is also immediately deleted from user-visible list of static redirects (available through .Dv NGM_NAT_LIST_REDIRECTS message). .It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete Delete redirection with specified ID (currently active connections are not affected). .It Dv NGM_NAT_ADD_SERVER Pq Ic addserver Add another server to a pool. This is used to transparently offload network load on a single server and distribute the load across a pool of servers, also known as .Em LSNAT (RFC 2391). The following .Vt "struct ng_nat_add_server" must be supplied as argument. .Bd -literal struct ng_nat_add_server { uint32_t id; struct in_addr addr; uint16_t port; }; .Ed .Pp First, the redirection is set up by .Dv NGM_NAT_REDIRECT_PORT or .Dv NGM_NAT_REDIRECT_ADDR . Then, ID of that redirection is used in multiple .Dv NGM_NAT_ADD_SERVER messages to add necessary number of servers. For redirections created by .Dv NGM_NAT_REDIRECT_ADDR , the .Va port is ignored and could have any value. Original redirection's parameters .Va local_addr and .Va local_port are also ignored after .Dv NGM_NAT_ADD_SERVER was used (they are effectively replaced by server pool). .It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects Return list of configured static redirects as .Vt "struct ng_nat_list_redirects" . .Bd -literal struct ng_nat_listrdrs_entry { uint32_t id; /* Anything except zero */ struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint16_t proto; /* Valid proto or NG_NAT_REDIRPROTO_ADDR */ uint16_t lsnat; /* LSNAT servers count */ char description[NG_NAT_DESC_LENGTH]; }; struct ng_nat_list_redirects { uint32_t total_count; struct ng_nat_listrdrs_entry redirects[]; }; #define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3) .Ed .Pp Entries of the .Va redirects array returned in the unified format for all redirect types. Ports are meaningful only if protocol is either TCP or UDP and .Em static NAT redirection (created by .Dv NGM_NAT_REDIRECT_ADDR ) is indicated by .Va proto set to .Dv NG_NAT_REDIRPROTO_ADDR . If .Va lsnat servers counter is greater than zero, then .Va local_addr and .Va local_port are also meaningless. .It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule Specify a transparent proxying rule (string must be supplied as argument). See .Xr libalias 3 for details. .It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo Return internal statistics of .Xr libalias 3 instance as .Vt "struct ng_nat_libalias_info" . .Bd -literal struct ng_nat_libalias_info { uint32_t icmpLinkCount; uint32_t udpLinkCount; uint32_t tcpLinkCount; uint32_t sctpLinkCount; uint32_t pptpLinkCount; uint32_t protoLinkCount; uint32_t fragmentIdLinkCount; uint32_t fragmentPtrLinkCount; uint32_t sockCount; }; .Ed In case of .Nm failed to retrieve a certain counter from its -.Xr libalias +.Xr libalias 3 instance, the corresponding field is returned as .Va UINT32_MAX . .It Dv NGM_NAT_SET_DLT Pq Ic setdlt Sets the data link type on the .Va in and .Va out hooks. Currently, supported types are .Cm DLT_RAW (raw IP datagrams , no offset applied, the default) and .Cm DLT_EN10MB (Ethernet). DLT_ definitions can be found in .In net/bpf.h . If you want to work on the .Xr ipfw 8 level you must use no additional offset by specifying .Cm DLT_RAW . If, however, you attach .Nm to a network interface directly and .Cm EN10MB is specified, then the extra offset will be applied to take into account link-level header. In this mode the .Nm would also inspect appropriate type field in the Ethernet header and pass-through any datagrams that are not IP packets. .It Dv NGM_NAT_GET_DLT Pq Ic getdlt This control message returns the current data link type of the .Va in and .Va out hooks. .El .Pp In all redirection messages .Va local_addr and .Va local_port mean address and port of target machine in the internal network, respectively. If .Va alias_addr is zero, then default aliasing address (set by .Dv NGM_NAT_SET_IPADDR ) is used. Connections can also be restricted to be accepted only from specific external machines by using non-zero .Va remote_addr and/or .Va remote_port . Each redirection assigned an ID which can be later used for redirection manipulation on individual basis (e.g., removal). This ID guaranteed to be unique until the node shuts down (it will not be reused after deletion), and is returned to user after making each new redirection or can be found in the stored list of all redirections. The .Va description passed to and from node unchanged, together with ID providing a way for several entities to concurrently manipulate redirections in automated way. .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when both hooks are disconnected. .Sh EXAMPLES In the following example, the packets are injected into a .Nm nat node using the .Xr ng_ipfw 4 node. .Bd -literal -offset indent # Create NAT node ngctl mkpeer ipfw: nat 60 out ngctl name ipfw:60 nat ngctl connect ipfw: nat: 61 in ngctl msg nat: setaliasaddr x.y.35.8 # Divert traffic into NAT node ipfw add 300 netgraph 61 all from any to any in via fxp0 ipfw add 400 netgraph 60 all from any to any out via fxp0 # Let packets continue with after being (de)aliased sysctl net.inet.ip.fw.one_pass=0 .Ed .Pp The .Nm node can be inserted right after the .Xr ng_iface 4 node in the graph. In the following example, we perform masquerading on a serial line with HDLC encapsulation. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer cp0: cisco rawdata downstream name cp0:rawdata hdlc mkpeer hdlc: nat inet in name hdlc:inet nat mkpeer nat: iface out inet msg nat: setaliasaddr x.y.8.35 SEQ ifconfig ng0 x.y.8.35 x.y.8.1 .Ed .Pp The .Nm node can also be attached directly to the physical interface via .Xr ng_ether 4 node in the graph. In the following example, we perform masquerading on a Ethernet interface connected to a public network. .Bd -literal -offset indent ifconfig igb0 inet x.y.8.35 netmask 0xfffff000 route add default x.y.0.1 /usr/sbin/ngctl -f- <<-SEQ mkpeer igb0: nat lower in name igb0:lower igb0_NAT connect igb0: igb0_NAT: upper out msg igb0_NAT: setdlt 1 msg igb0_NAT: setaliasaddr x.y.8.35 SEQ .Ed .Sh SEE ALSO .Xr libalias 3 , .Xr ng_ipfw 4 , .Xr natd 8 , .Xr ng_ether 8 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 6.0 . .Sh AUTHORS .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org diff --git a/share/man/man4/qat.4 b/share/man/man4/qat.4 index b0fa0b0cbc92..03d1e6e956e7 100644 --- a/share/man/man4/qat.4 +++ b/share/man/man4/qat.4 @@ -1,185 +1,185 @@ .\" SPDX-License-Identifier: BSD-3-Clause .\" Copyright(c) 2007-2022 Intel Corporation .Dd May 4, 2023 .Dt QAT 4 .Os .Sh NAME .Nm qat .Nd Intel (R) QuickAssist Technology (QAT) driver .Sh SYNOPSIS To load the driver call: .Pp .Bl -item -compact .It kldload qat .El .Pp In order to load the driver on boot add these lines to .Xr loader.conf 5 selecting firmware(s) suitable for installed device(s) .Pp .Bl -item -compact .It qat_200xx_fw_load="YES" .It qat_c3xxx_fw_load="YES" .It qat_c4xxx_fw_load="YES" .It qat_c62x_fw_load="YES" .It qat_dh895xcc_fw_load="YES" .It qat_4xxx_fw_load="YES" .It qat_load="YES" .El .Sh DESCRIPTION The .Nm driver supports cryptography and compression acceleration of the Intel (R) QuickAssist Technology (QAT) devices. .Pp The .Nm driver is intended for platforms that contain: .Bl -bullet -compact .It Intel (R) C62x Chipset .It Intel (R) Atom C3000 processor product family .It Intel (R) QuickAssist Adapter 8960/Intel (R) QuickAssist Adapter 8970 (formerly known as "Lewis Hill") .It Intel (R) Communications Chipset 8925 to 8955 Series .It Intel (R) Atom P5300 processor product family .It Intel (R) QAT 4xxx Series .El .Pp The .Nm driver supports cryptography and compression acceleration. A complete API for offloading these operations is exposed in the kernel and may be used by any other entity directly. For details of usage and supported operations and algorithms refer to the following documentation available from Intel Download Center .Lk https://downloadcenter.intel.com : .Bl -bullet -compact .It .Rs .%A Intel (R) .%T QuickAssist Technology API Programmer's Guide .Re .It .Rs .%A Intel (R) .%T QuickAssist Technology Cryptographic API Reference Manual .Re .It .Rs .%A Intel (R) .%T QuickAssist Technology Data Compression API Reference Manual .Re .It .Rs .%A Intel (R) .%T QuickAssist Technology Performance Optimization Guide .Re .El .Pp In addition to exposing complete kernel API for offloading cryptography and compression operations, the .Nm driver also integrates with .Xr crypto 4 , allowing offloading supported cryptography operations to Intel (R) QuickAssist Technology (QAT) devices. For details of usage and supported operations and algorithms refer to the documentation mentioned above and .Sx SEE ALSO section. .Sh SYSCTL_VARIABLES Following variables may be used to reconfigure the QAT device.\& For configuration persistence those variables may be set before loading the driver, either via .Xr kenv 1 or -.Xr loader.conf(5). +.Xr loader.conf 5 . The device specific configuration options are prefixed with .Va dev.qat.X\&. where X is the device number. The specific device needs to be in "down" state before changing the configuration. .Bl -tag -width indent .It Va state Show current state of the device. Override the device state. Possible values: "down", "up". NOTE: If the symmetric services are used for device the qat_ocf driver needs to be disabled prior the device reconfiguration. Following variable may be used to enable/disable the QAT cryptographic framework connectivity .Va dev.qat_ocf.0.enable\&. Enabled by default. .It Va cfg_services Override the device services enabled: symmetric, asymmetric, data compression. Possible values: "sym", "asym", "dc", "sym;dc", "asym;dc", "sym;asym". Default services configured are "sym;asym" for even and "dc" for odd devices. .It Va cfg_mode Override the device mode configuration for kernel space and user space instances. Possible values: "ks", "us", "ks;us". Default value "ks;us". .It Va num_user_processes Override the number of uio user space processes that can connect to the QAT device. Default: 2 .El .Pp The following .Xr sysctl 8 variables are read-only: .Bl -tag -width indent .It Va frequency QAT device frequency value. .It Va mmp_version QAT MMP Library revision number. .It Va hw_version QAT hardware revision number. .It Va fw_version QAT firmware revision number. .It Va dev_cfg Summary of device specific configuration. .It Va heartbeat QAT device heartbeat status. Value '1' indicates that the device is operational. '0' value means that the device is not responsive. Device requires restart. .It Va heartbeat_failed Number of QAT heartbeat failures received. .It Va heartbeat_sent Number of QAT heartbeat requests sent. .El .Sh COMPATIBILITY The .Nm driver replaced previous implementation introduced in .Fx 13.0 . Current version, in addition to .Xr crypto 4 integration, supports also data compression and exposes a complete API for offloading data compression and cryptography operations. .Sh SEE ALSO .Xr crypto 4 , .Xr ipsec 4 , .Xr pci 4 , .Xr crypto 7 , .Xr crypto 9 .Sh HISTORY This .Nm driver was introduced in .Fx 14.0 . .Fx 13.0 included a different version of .Nm driver. .Sh AUTHORS The .Nm driver was written by .An Intel (R) Corporation . diff --git a/share/man/man4/watchdog.4 b/share/man/man4/watchdog.4 index f711d4d176d1..7663d4831464 100644 --- a/share/man/man4/watchdog.4 +++ b/share/man/man4/watchdog.4 @@ -1,204 +1,204 @@ .\" Copyright (c) 2004 Poul-Henning Kamp .\" Copyright (c) 2003, 2004 Sean M. Kelly .\" 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 REGENTS 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 REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd January 2, 2018 .Dt WATCHDOG 4 .Os .Sh NAME .Nm watchdog .Nd "hardware and software watchdog" .Sh SYNOPSIS .In sys/watchdog.h .Sh DESCRIPTION The .Nm facility is used for controlling hardware and software watchdogs. .Pp The device .Pa /dev/fido supports several optional .Xr ioctl 2 calls for configuration, and responds to a single operational -.Xr ioctl +.Xr ioctl 2 call, .Dv WDIOCPATPAT . It takes a single argument which represents a timeout value specified as a power of two nanoseconds, or-ed with a flag selecting active or passive control of the watchdog. .Pp .Dv WD_ACTIVE indicates that the .Nm will be kept from timing out from userland, for instance by the .Xr watchdogd 8 daemon. .Dv WD_PASSIVE indicates that the .Nm will be kept from timing out from the kernel. .Pp The .Dv WDIOCPATPAT .Xr ioctl 2 call will return success if just one of the available .Xr watchdog 9 implementations supports setting the timeout to the specified timeout. This means that at least one watchdog is armed. By default, this will be a hardware watchdog if one is present, but if no hardware watchdog is able to process the request, a default software watchdog is enabled. If the call fails, for instance if none of .Xr watchdog 9 implementations support the timeout length, all watchdogs are disabled and must be explicitly re-enabled. .Pp To disable the watchdogs pass .Dv WD_TO_NEVER . If disarming the watchdog(s) failed an error is returned. The watchdog might still be armed! .Pp The optional configuration -.Xr ioctl +.Xr ioctl 2 commands are listed here, along with the type of the parameter used. Examples of their use can be found in .Xr watchdogd 8 . .Bl -tag -width "WDIOC_SETSOFTTIMEOUTACT int " .It Dv WDIOC_SETTIMEOUT Fa int set/reset the timer .It Dv WDIOC_GETTIMEOUT Fa int get total timeout .It Dv WDIOC_GETTIMELEFT Fa int get time left .It Dv WDIOC_GETPRETIMEOUT Fa int get the pre-timeout .It Dv WDIOC_SETPRETIMEOUT Fa int set the pre-timeout .It Dv WDIOC_SETPRETIMEOUTACT Fa int Set the action when a pre-timeout occurs (see .Li WD_SOFT_* below). .It Dv WDIOC_SETSOFT Fa int Use an internal software watchdog instead of hardware. There is also an external software watchdog, which is used by default if no hardware watchdog was attached. .It Dv WDIOC_SETSOFTTIMEOUTACT Fa int Set the action whan a soft timeout occurs. .El .Pp The actions that may be specified for the pre-timeout or the internal software watchdog are listed here. Multiple actions can be specified by ORing values together. .Bl -tag -width WD_SOFT_PRINT .It Dv WD_SOFT_PANIC panic .It Dv WD_SOFT_DDB enter debugger .It Dv WD_SOFT_LOG log(9) .It Dv WD_SOFT_PRINT printf(9) .El .Sh RETURN VALUES The .Dv WDIOCPATPAT -.Xr ioctl +.Xr ioctl 2 returns zero on success and non-zero on failure. .Bl -tag -width Er .It Bq Er EOPNOTSUPP No watchdog present in the kernel or none of the watchdogs supports the requested timeout value (timeout value other than 0). .It Bq Er EOPNOTSUPP Watchdog could not be disabled (timeout value of 0). .It Bq Er EINVAL Invalid flag combination passed. .El .Pp The configuration -.Xr ioctl +.Xr ioctl 2 operations return zero on success and non-zero on failure. .Sh EXAMPLES .Bd -literal -offset indent #include #include #define WDPATH "/dev/" _PATH_WATCHDOG int wdfd = -1; static void wd_init(void) { wdfd = open(WDPATH, O_RDWR); if (wdfd == -1) err(1, WDPATH); } static void wd_reset(u_int timeout) { if (ioctl(wdfd, WDIOCPATPAT, &timeout) == -1) err(1, "WDIOCPATPAT"); } /* in main() */ wd_init(); wd_reset(WD_ACTIVE|WD_TO_8SEC); /* potential freeze point */ wd_reset(WD_TO_NEVER); .Ed .Pp Enables a watchdog to recover from a potentially freezing piece of code. .Pp .Dl "options SW_WATCHDOG" .Pp in your kernel config forces a software watchdog in the kernel to be configured even if a hardware watchdog is configured, dropping to KDB or panicking when firing, depending on the KDB and KDB_UNATTENDED kernel configuration options. .Sh SEE ALSO .Xr watchdogd 8 , .Xr watchdog 9 .Sh HISTORY The .Nm code first appeared in .Fx 5.1 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . The software watchdog code and this manual page were written by .An Sean Kelly Aq Mt smkelly@FreeBSD.org . Some contributions were made by .An Jeff Roberson Aq Mt jeff@FreeBSD.org . .Sh BUGS The .Dv WD_PASSIVE option has not yet been implemented. diff --git a/share/man/man9/VOP_ADVISE.9 b/share/man/man9/VOP_ADVISE.9 index 3decc0c2eac8..c6e8791615ce 100644 --- a/share/man/man9/VOP_ADVISE.9 +++ b/share/man/man9/VOP_ADVISE.9 @@ -1,89 +1,89 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2013 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. .\" .Dd September 26, 2015 .Dt VOP_ADVISE 9 .Os .Sh NAME .Nm VOP_ADVISE .Nd apply advice about use of file data .Sh SYNOPSIS .In sys/param.h .In sys/vnode.h .Ft int .Fn VOP_ADVISE "struct vnode *vp" "off_t start" "off_t end" "int advice" .Sh DESCRIPTION This call applies advice for a range of a file's data. It is used to implement the -.Xr posix_fadvise +.Xr posix_fadvise 2 system call. .Pp Its arguments are: .Bl -tag -width offset .It Fa vp The vnode of the file. .It Fa start The start of the range of file data. .It Fa end The end of the range of file data. A value of .Dv OFF_MAX indicates that the advice is to be applied up to the end of the file. .It Fa advice The type of operation to apply to the file data. Possible values are: .Bl -tag -width POSIX_FADV_WILLNEED .It Dv POSIX_FADV_WILLNEED Initiate an asynchronous read of the file data if it is not already resident. .It Dv POSIX_FADV_DONTNEED Decrease the in-memory priority of clean file data or discard clean file data. .El .El .Pp If the .Fa start and .Fa end offsets are both zero, then the operation should be applied to the entire file. Note that this call is advisory only and may perform the requested operation on a subset of the requested range .Pq including not performing it at all and still return success. .Sh LOCKS The file should be unlocked on entry. .Sh RETURN VALUES Zero is returned if the call is successful, otherwise an appropriate error code is returned. .Sh ERRORS .Bl -tag -width Er .It Bq Er EINVAL An invalid value was given for .Fa advice . .El .Sh SEE ALSO .Xr vnode 9 diff --git a/share/man/man9/VOP_ALLOCATE.9 b/share/man/man9/VOP_ALLOCATE.9 index fce2ea183273..4fcbe773f236 100644 --- a/share/man/man9/VOP_ALLOCATE.9 +++ b/share/man/man9/VOP_ALLOCATE.9 @@ -1,92 +1,92 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2013 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. .\" .Dd November 8, 2021 .Dt VOP_ALLOCATE 9 .Os .Sh NAME .Nm VOP_ALLOCATE .Nd allocate storage for a file .Sh SYNOPSIS .In sys/param.h .In sys/vnode.h .Ft int .Fo VOP_ALLOCATE .Fa "struct vnode *vp" .Fa "off_t *offset" .Fa "off_t *len" .Fa "int ioflag" .Fa "struct ucred *cred" .Fc .Sh DESCRIPTION This call allocates storage for a range of offsets in a file. It is used to implement the -.Xr posix_fallocate +.Xr posix_fallocate 2 system call. .Pp Its arguments are: .Bl -tag -width offset .It Fa vp The vnode of the file. .It Fa offset The start of the range to allocate storage for in the file. .It Fa len The length of the range to allocate storage for in the file. .It Fa ioflag Directives and hints to be given to the file system. .It Fa cred The credentials of the caller. .El .Pp The .Fa offset and .Fa len arguments are updated to reflect the portion of the range that still needs to be allocated on return. A partial allocation is considered a successful operation. The file's contents are not changed. .Sh LOCKS The file should be exclusively locked on entry and will still be locked on exit. .Sh RETURN VALUES Zero is returned if the call is successful, otherwise an appropriate error code is returned. .Sh ERRORS .Bl -tag -width Er .It Bq Er EFBIG An attempt was made to write a file that exceeds the process's file size limit or the maximum file size. .It Bq Er ENOSPC The file system is full. .It Bq Er EPERM An append-only flag is set on the file, but the caller is attempting to write before the current end of file. .El .Sh SEE ALSO .Xr vnode 9 , .Xr VOP_READ 9 , .Xr VOP_WRITE 9 diff --git a/share/man/man9/osd.9 b/share/man/man9/osd.9 index 82f279ef17f4..95547f5211c2 100644 --- a/share/man/man9/osd.9 +++ b/share/man/man9/osd.9 @@ -1,448 +1,448 @@ .\" .\" Copyright (c) 2010 Lawrence Stewart .\" 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, .\" without modification, immediately at the beginning of the file. .\" 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. .\" .Dd April 26, 2016 .Dt OSD 9 .Os .Sh NAME .Nm osd , .Nm osd_register , .Nm osd_deregister , .Nm osd_set , .Nm osd_reserve , .Nm osd_set_reserved , .Nm osd_free_reserved , .Nm osd_get , .Nm osd_del , .Nm osd_call , .Nm osd_exit .Nd Object Specific Data .Sh SYNOPSIS .In sys/osd.h .Ft typedef void .Fn "\*(lp*osd_destructor_t\*(rp" "void *value" .Ft typedef int .Fn "\*(lp*osd_method_t\*(rp" "void *obj" "void *data" .Ft int .Fo osd_register .Fa "u_int type" .Fa "osd_destructor_t destructor" .Fa "osd_method_t *methods" .Fc .Ft void .Fo osd_deregister .Fa "u_int type" .Fa "u_int slot" .Fc .Ft int .Fo osd_set .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fa "void *value" .Fc .Ft void ** .Fo osd_reserve .Fa "u_int slot" .Fc .Ft int .Fo osd_set_reserved .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fa "void **rsv" .Fa "void *value" .Fc .Ft void .Fo osd_free_reserved .Fa "void **rsv" .Fc .Ft void * .Fo osd_get .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fc .Ft void .Fo osd_del .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fc .Ft int .Fo osd_call .Fa "u_int type" .Fa "u_int method" .Fa "void *obj" .Fa "void *data" .Fc .Ft void .Fo osd_exit .Fa "u_int type" .Fa "struct osd *osd" .Fc .Sh DESCRIPTION The .Nm framework provides a mechanism to dynamically associate arbitrary data at run-time with any kernel data structure which has been suitably modified for use with .Nm . The one-off modification required involves embedding a .Vt "struct osd" inside the kernel data structure. .Pp An additional benefit is that after the initial change to a structure is made, all subsequent use of .Nm with the structure involves no changes to the structure's layout. By extension, if the data structure is part of the ABI, .Nm provides a way of extending the structure in an ABI preserving manner. .Pp The details of the embedded .Vt "struct osd" are not relevant to consumers of the .Nm framework and should not be manipulated directly. .Pp Data associated with a structure is referenced by the .Nm framework using a type/slot identifier pair. Types are statically defined in .In sys/osd.h and provide a high-level grouping for slots to be registered under. Slot identifiers are dynamically assigned by the framework when a data type is registered using .Fn osd_register and remains valid until a corresponding call to .Fn osd_deregister . .Ss Functions The .Fn osd_register function registers a type/slot identifier pair with the .Nm framework for use with a new data type. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier should be allocated under. The .Fa destructor argument specifies an optional osd_destructor_t function pointer that will be called for objects of the type being registered which are later destroyed by the .Fn osd_del function. NULL may be passed if no destructor is required. The .Fa methods argument specifies an optional array of osd_method_t function pointers which can be later invoked by the .Fn osd_call function. NULL may be passed if no methods are required. The .Fa methods argument is currently only useful with the OSD_JAIL type identifier. .Pp The .Fn osd_deregister function deregisters a previously registered type/slot identifier pair. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa slot argument specifies the slot identifier which is being deregistered and should be the value that was returned by .Fn osd_register when the data type was registered. .Pp The .Fn osd_set function associates a data object pointer with a kernel data structure's .Vt struct osd member. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd which will have the .Fa value pointer associated with it. The .Fa slot argument specifies the slot identifier to assign the .Fa value pointer to. The .Fa value argument points to a data object to associate with .Fa osd . .Pp The .Fn osd_set_reserved function does the same as .Fn osd_set , but with an extra argument .Fa rsv that is internal-use memory previously allocated via .Fn osd_reserve . .Pp The .Fn osd_get function returns the data pointer associated with a kernel data structure's .Vt struct osd member from the specified type/slot identifier pair. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to retrieve the data pointer from. The .Fa slot argument specifies the slot identifier to retrieve the data pointer from. .Pp The .Fn osd_del function removes the data pointer associated with a kernel data structure's .Vt struct osd member from the specified type/slot identifier pair. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to remove the data pointer from. The .Fa slot argument specifies the slot identifier to remove the data pointer from. If an osd_destructor_t function pointer was specified at registration time, the destructor function will be called and passed the data pointer for the type/slot identifier pair which is being deleted. .Pp The .Fn osd_call function calls the specified osd_method_t function pointer for all currently registered slots of a given type on the specified .Fa obj and .Fa data pointers. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h to call the method for. The .Fa method argument specifies the index into the osd_method_t array that was passed to .Fn osd_register . The .Fa obj and .Fa data arguments are passed to the method function pointer of each slot. .Pp The .Fn osd_exit function removes all data object pointers from all currently registered slots for a given type for the specified kernel data structure's .Vt struct osd member. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h to remove data pointers from. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to remove all data object pointers for all currently registered slots from. .Sh IMPLEMENTATION NOTES .Nm uses a two dimensional matrix (array of arrays) as the data structure to manage the external data associated with a kernel data structure's .Vt struct osd member. The type identifier is used as the index into the outer array, and the slot identifier is used as the index into the inner array. To set or retrieve a data pointer for a given type/slot identifier pair, .Fn osd_set and .Fn osd_get perform the equivalent of array[type][slot], which is both constant time and fast. .Pp If .Fn osd_set is called on a .Vt struct osd for the first time, the array for storing data pointers is dynamically allocated using .Xr malloc 9 with M_NOWAIT to a size appropriate for the slot identifier being set. If a subsequent call to .Fn osd_set attempts to set a slot identifier which is numerically larger than the slot used in the previous .Fn osd_set call, .Xr realloc 9 is used to grow the array to the appropriate size such that the slot identifier can be used. To maximise the efficiency of any code which calls .Fn osd_set sequentially on a number of different slot identifiers (e.g., during an initialisation phase) one should loop through the slot identifiers in descending order from highest to lowest. This will result in only a single .Xr malloc 9 call to create an array of the largest slot size and all subsequent calls to .Fn osd_set will proceed without any .Xr realloc 9 calls. .Pp It is possible for .Fn osd_set to fail to allocate this array. To ensure that such allocation succeeds, .Fn osd_reserve may be called (in a non-blocking context), and it will pre-allocate the memory via .Xr malloc 9 with M_WAITOK. Then this pre-allocated memory is passed to .Fn osd_set_reserved , which will use it if necessary or otherwise discard it. The memory may also be explicitly discarded by calling .Fn osd_free_reserved . As this method always allocates memory whether or not it is ultimately needed, it should be used only rarely, such as in the unlikely event that .Fn osd_set fails. .Pp The .Nm API is geared towards slot identifiers storing pointers to the same underlying data structure type for a given .Nm type identifier. This is not a requirement, and .Xr khelp 9 for example stores completely different data types in slots under the OSD_KHELP type identifier. .Ss Locking .Nm internally uses a mix of .Xr mutex 9 , .Xr rmlock 9 and .Xr sx 9 locks to protect its internal data structures and state. .Pp Responsibility for synchronising access to a kernel data structure's .Vt struct osd member is left to the subsystem that uses the data structure and calls the .Nm API. .Pp .Fn osd_get only acquires an -.Xr rmlock +.Xr rmlock 9 in read mode, therefore making it safe to use in the majority of contexts within the kernel including most fast paths. .Sh RETURN VALUES .Fn osd_register returns the slot identifier for the newly registered data type. .Pp .Fn osd_set and .Fn osd_set_reserved return zero on success or ENOMEM if the specified type/slot identifier pair triggered an internal .Xr realloc 9 which failed .Ns ( .Fn osd_set_reserved will always succeed when .Fa rsv is non-NULL). .Pp .Fn osd_get returns the data pointer for the specified type/slot identifier pair, or NULL if the slot has not been initialised yet. .Pp .Fn osd_reserve returns a pointer suitable for passing to .Fn osd_set_reserved or .Fn osd_free_reserved . .Pp .Fn osd_call returns zero if no method is run or the method for each slot runs successfully. If a method for a slot returns non-zero, .Fn osd_call terminates prematurely and returns the method's error to the caller. .Sh SEE ALSO .Xr khelp 9 .Sh HISTORY The Object Specific Data (OSD) facility first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . .Pp This manual page was written by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org .