Index: head/share/man/man9/bpf.9 =================================================================== --- head/share/man/man9/bpf.9 (revision 301589) +++ head/share/man/man9/bpf.9 (revision 301590) @@ -1,301 +1,301 @@ .\" Copyright (c) 2004 FreeBSD Inc. .\" 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 [your name] 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 11, 2012 .Dt BPF 9 .Os .\" .Sh NAME .Nm bpf .Nd "Berkeley Packet Filter" .\" .Sh SYNOPSIS .In net/bpf.h .\" .Ft void .Fn bpfattach "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" .Ft void .Fo bpfattach2 .Fa "struct ifnet *ifp" "u_int dlt" "u_int hdrlen" "struct bpf_if **driverp" .Fc .Ft void .Fn bpfdetach "struct ifnet *ifp" .Ft void .Fn bpf_tap "struct ifnet *ifp" "u_char *pkt" "u_int *pktlen" .Ft void .Fn bpf_mtap "struct ifnet *ifp" "struct mbuf *m" .Ft void .Fn bpf_mtap2 "struct bpf_if *bp" "void *data" "u_int dlen" "struct mbuf *m" .Ft u_int .Fo bpf_filter .Fa "const struct bpf_insn *pc " "u_char *pkt" "u_int wirelen" "u_int buflen" .Fc .Ft int .Fn bpf_validate "const struct bpf_insn *fcode" "int flen" .\" .Sh DESCRIPTION The Berkeley Packet Filter provides a raw interface, that is protocol independent, to data link layers. It allows all packets on the network, even those destined for other hosts, to be passed from a network interface to user programs. Each program may specify a filter, in the form of a .Nm filter machine program. The .Xr bpf 4 manual page describes the interface used by user programs. This manual page describes the functions used by interfaces to pass packets to .Nm and the functions for testing and running .Nm filter machine programs. .Pp The .Fn bpfattach function attaches a network interface to .Nm . The .Fa ifp argument is a pointer to the structure that defines the interface to be attached to an interface. The .Fa dlt argument is the data link-layer type: .Dv DLT_NULL (no link-layer encapsulation), .Dv DLT_EN10MB (Ethernet), .Dv DLT_IEEE802_11 (802.11 wireless networks), etc. The rest of the link layer types can be found in .In net/bpf.h . The .Fa hdrlen argument is the fixed size of the link header; variable length headers are not yet supported. The .Nm system will hold a pointer to .Fa ifp->if_bpf . This variable will set to a .Pf non- Dv NULL value when .Nm requires packets from this interface to be tapped using the functions below. .Pp The .Fn bpfattach2 function allows multiple .Nm instances to be attached to a single interface, by registering an explicit .Fa if_bpf rather than using .Fa ifp->if_bpf . It is then possible to run .Xr tcpdump 1 on the interface for any data link-layer types attached. .Pp The .Fn bpfdetach function detaches a .Nm instance from an interface, specified by .Fa ifp . The .Fn bpfdetach function should be called once for each .Nm instance attached. .Pp The .Fn bpf_tap function is used by an interface to pass the packet to .Nm . The packet data (including link-header), pointed to by .Fa pkt , is of length .Fa pktlen , which must be a contiguous buffer. The .Fa ifp argument is a pointer to the structure that defines the interface to be tapped. The packet is parsed by each processes filter, and if accepted, it is buffered for the process to read. .Pp The .Fn bpf_mtap function is like .Fn bpf_tap except that it is used to tap packets that are in an .Vt mbuf chain, .Fa m . The .Fa ifp argument is a pointer to the structure that defines the interface to be tapped. Like .Fn bpf_tap , .Fn bpf_mtap requires a link-header for whatever data link layer type is specified. Note that .Nm only reads from the .Vt mbuf chain, it does not free it or keep a pointer to it. This means that an .Vt mbuf containing the link-header can be prepended to the chain if necessary. A cleaner interface to achieve this is provided by .Fn bpf_mtap2 . .Pp The .Fn bpf_mtap2 function allows the user to pass a link-header .Fa data , of length .Fa dlen , independent of the .Vt mbuf .Fa m , containing the packet. This simplifies the passing of some link-headers. .Pp The .Fn bpf_filter function executes the filter program starting at .Fa pc on the packet .Fa pkt . The .Fa wirelen argument is the length of the original packet and .Fa buflen is the amount of data present. The .Fa buflen value of 0 is special; it indicates that the .Fa pkt is actually a pointer to an mbuf chain .Pq Vt "struct mbuf *" . .Pp The .Fn bpf_validate function checks that the filter code .Fa fcode , of length .Fa flen , is valid. .\" .Sh RETURN VALUES The .Fn bpf_filter function returns \-1 (cast to an unsigned integer) if there is no filter. Otherwise, it returns the result of the filter program. .Pp The .Fn bpf_validate function returns 0 when the program is not a valid filter program. .\" .Sh EVENT HANDLERS .Nm invokes .Fa bpf_track .Xr EVENTHANDLER 9 event each time listener attaches to or detaches from an interface. Pointer to .Pq Vt "struct ifnet *" is passed as the first argument, interface .Fa dlt -follows. Last argument indicates listener is attached (1) or -detached (0). +follows. +Last argument indicates listener is attached (1) or detached (0). Note that handler is invoked with .Nm global lock held, which implies restriction on sleeping and calling .Nm subsystem inside .Xr EVENTHANDLER 9 dispatcher. Note that handler is not called for write-only listeners. .\" .Sh SEE ALSO .Xr tcpdump 1 , .Xr bpf 4 , .Xr EVENTHANDLER 9 .\" .Sh HISTORY The Enet packet filter was created in 1980 by Mike Accetta and Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at Stanford, ported the code to .Bx and continued its development from 1983 on. Since then, it has evolved into the Ultrix Packet Filter at .Tn DEC , a .Tn STREAMS .Tn NIT module under .Tn SunOS 4.1, and .Tn BPF . .\" .Sh AUTHORS .An -nosplit .An Steven McCanne , of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. Much of the design is due to .An Van Jacobson . This manpage was written by .An Orla McGann . Index: head/share/man/man9/firmware.9 =================================================================== --- head/share/man/man9/firmware.9 (revision 301589) +++ head/share/man/man9/firmware.9 (revision 301590) @@ -1,272 +1,275 @@ .\" Copyright (c) 2006 Max Laier .\" 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 August 2, 2008 .Dt FIRMWARE 9 .Os .Sh NAME .Nm firmware_register , .Nm firmware_unregister , .Nm firmware_get , .Nm firmware_put .Nd firmware image loading and management .Sh SYNOPSIS .In sys/param.h .In sys/systm.h .In sys/linker.h .In sys/firmware.h .Bd -literal struct firmware { const char *name; /* system-wide name */ const void *data; /* location of image */ size_t datasize; /* size of image in bytes */ unsigned int version; /* version of the image */ }; .Ed .Ft "const struct firmware *" .Fo firmware_register .Fa "const char *imagename" .Fa "const void *data" .Fa "size_t datasize" .Fa "unsigned int version" .Fa "const struct firmware *parent" .Fc .Ft int .Fn firmware_unregister "const char *imagename" .Ft "const struct firmware *" .Fn firmware_get "const char *imagename" .Ft void .Fn firmware_put "const struct firmware *fp" "int flags" .Sh DESCRIPTION The .Nm firmware abstraction provides a convenient interface for loading .Nm firmware images into the kernel, and for accessing such images from kernel components. .Pp A .Nm firmware image (or .Nm image for brevity) is an opaque block of data residing in kernel memory. It is associated to a unique .Nm imagename which constitutes a search key, and to an integer .Nm version number, which is also an opaque piece of information for the firmware subsystem. .Pp An image is registered with the .Nm firmware subsystem by calling the function .Fn firmware_register , and unregistered by calling .Fn firmware_unregister . These functions are usually (but not exclusively) called by specially crafted kernel modules that contain the firmware image. The modules can be statically compiled in the kernel, or loaded by .Nm /boot/loader , manually at runtime, or on demand by the firmware subsystem. .Pp .Nm Clients of the firmware subsystem can request access to a given image by calling the function .Fn firmware_get with the .Nm imagename -they want as an argument. If a matching image is not already registered, +they want as an argument. +If a matching image is not already registered, the firmware subsystem will try to load it using the mechanisms specified below (typically, a kernel module with .Nm the same name as the image). .Sh API DESCRIPTION The kernel .Nm firmware API is made of the following functions: .Pp .Fn firmware_register registers with the kernel an image of size .Nm datasize located at address .Nm data , under the name .Nm imagename . .Pp The function returns NULL on error (e.g. because an image with the same name already exists, or the image table is full), or a .Ft const struct firmware * pointer to the image requested. .Pp .Fn firmware_unregister tries to unregister the firmware image .Nm imagename -from the system. The function is successful and returns 0 +from the system. +The function is successful and returns 0 if there are no pending references to the image, otherwise it does not unregister the image and returns EBUSY. .Pp .Fn firmware_get returns the requested firmware image. If the image is not yet registered with the system, the function tries to load it. This involves the linker subsystem and disk access, so .Fn firmware_get must not be called with any locks (except for .Va Giant ) . Note also that if the firmware image is loaded from a filesystem it must already be mounted. In particular this means that it may be necessary to defer requests from a driver attach method unless it is known the root filesystem is already mounted. .Pp On success, .Fn firmware_get returns a pointer to the image description and increases the reference count -for this image. On failure, the function returns NULL. +for this image. +On failure, the function returns NULL. .Pp .Fn firmware_put drops a reference to a firmware image. The .Fa flags argument may be set to .Dv FIRMWARE_UNLOAD to indicate that firmware_put is free to reclaim resources associated with the firmware image if this is the last reference. By default a firmware image will be deferred to a .Xr taskqueue 9 thread so the call may be done while holding a lock. In certain cases, such as on driver detach, this cannot be allowed. .Sh FIRMWARE LOADING MECHANISMS As mentioned before, any component of the system can register firmware images at any time by simply calling .Fn firmware_register . .Pp This is typically done when a module containing a firmware image is given control, whether compiled in, or preloaded by .Nm /boot/loader , or manually loaded with .Xr kldload 8 . However, a system can implement additional mechanisms to bring these images in memory before calling .Fn firmware_register . .Pp When .Fn firmware_get does not find the requested image, it tries to load it using one of the available loading mechanisms. At the moment, there is only one, namely .Nm Loadable kernel modules : .Pp A firmware image named .Nm foo is looked up by trying to load the module named .Nm foo.ko , using the facilities described in .Xr kld 4 . In particular, images are looked up in the directories specified by the sysctl variable .Nm kern.module_path which on most systems defaults to .Nm /boot/kernel;/boot/modules . .Pp Note that in case a module contains multiple images, the caller should first request a .Fn firmware_get for the first image contained in the module, followed by requests for the other images. .Sh BUILDING FIRMWARE LOADABLE MODULES A firmware module is built by embedding the .Nm firmware image into a suitable loadable kernel module that calls .Fn firmware_register on loading, and .Fn firmware_unregister on unloading. .Pp Various system scripts and makefiles let you build a module by simply writing a Makefile with the following entries: .Bd -literal KMOD= imagename FIRMWS= image_file:imagename[:version] .include .Ed where KMOD is the basename of the module; FIRMWS is a list of colon-separated tuples indicating the image_file's to be embedded in the module, the imagename and version of each firmware image. .Pp If you need to embed firmware images into a system, you should write appropriate entries in the file, e.g. this example is from .Nm sys/arm/xscale/ixp425/files.ixp425 : .Bd -literal ixp425_npe_fw.c optional npe_fw \\ compile-with "${AWK} -f $S/tools/fw_stub.awk \\ IxNpeMicrocode.dat:npe_fw -mnpe -c${.TARGET}" \\ no-implicit-rule before-depend local \\ clean "ixp425_npe_fw.c" # # NB: ld encodes the path in the binary symbols generated for the # firmware image so link the file to the object directory to # get known values for reference in the _fw.c file. # IxNpeMicrocode.fwo optional npe_fw \\ dependency "IxNpeMicrocode.dat" \\ compile-with "${LD} -b binary -d -warn-common \\ -r -d -o ${.TARGET} IxNpeMicrocode.dat" \\ no-implicit-rule \\ clean "IxNpeMicrocode.fwo" IxNpeMicrocode.dat optional npe_fw \\ dependency ".PHONY" \\ compile-with "uudecode < $S/contrib/dev/npe/IxNpeMicrocode.dat.uu" \\ no-obj no-implicit-rule \\ clean "IxNpeMicrocode.dat" .Ed .Pp Note that generating the firmware modules in this way requires the availability of the following tools: .Xr awk 1 , .Xr make 1 , the compiler and the linker. .Sh SEE ALSO .Xr kld 4 , .Xr module 9 .Pp .Pa /usr/share/examples/kld/firmware .Sh HISTORY The .Nm firmware system was introduced in .Fx 6.1 . .Sh AUTHORS This manual page was written by .An Max Laier Aq Mt mlaier@FreeBSD.org . Index: head/share/man/man9/lock.9 =================================================================== --- head/share/man/man9/lock.9 (revision 301589) +++ head/share/man/man9/lock.9 (revision 301590) @@ -1,423 +1,424 @@ .\" .\" Copyright (C) 2002 Chad David . 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(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 November 2, 2014 .Dt LOCK 9 .Os .Sh NAME .Nm lockinit , .Nm lockdestroy , .Nm lockmgr , .Nm lockmgr_args , .Nm lockmgr_args_rw , .Nm lockmgr_disown , .Nm lockmgr_printinfo , .Nm lockmgr_recursed , .Nm lockmgr_rw , .Nm lockmgr_waiters , .Nm lockstatus , .Nm lockmgr_assert .Nd "lockmgr family of functions" .Sh SYNOPSIS .In sys/types.h .In sys/lock.h .In sys/lockmgr.h .Ft void .Fn lockinit "struct lock *lkp" "int prio" "const char *wmesg" "int timo" "int flags" .Ft void .Fn lockdestroy "struct lock *lkp" .Ft int .Fn lockmgr "struct lock *lkp" "u_int flags" "struct mtx *ilk" .Ft int .Fn lockmgr_args "struct lock *lkp" "u_int flags" "struct mtx *ilk" "const char *wmesg" "int prio" "int timo" .Ft int .Fn lockmgr_args_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" "const char *wmesg" "int prio" "int timo" .Ft void .Fn lockmgr_disown "struct lock *lkp" .Ft void .Fn lockmgr_printinfo "const struct lock *lkp" .Ft int .Fn lockmgr_recursed "const struct lock *lkp" .Ft int .Fn lockmgr_rw "struct lock *lkp" "u_int flags" "struct rwlock *ilk" .Ft int .Fn lockmgr_waiters "const struct lock *lkp" .Ft int .Fn lockstatus "const struct lock *lkp" .Pp .Cd "options INVARIANTS" .Cd "options INVARIANT_SUPPORT" .Ft void .Fn lockmgr_assert "const struct lock *lkp" "int what" .Sh DESCRIPTION The .Fn lockinit function is used to initialize a lock. It must be called before any operation can be performed on a lock. Its arguments are: .Bl -tag -width ".Fa wmesg" .It Fa lkp A pointer to the lock to initialize. .It Fa prio The priority passed to .Xr sleep 9 . .It Fa wmesg The lock message. This is used for both debugging output and .Xr sleep 9 . .It Fa timo The timeout value passed to .Xr sleep 9 . .It Fa flags The flags the lock is to be initialized with: .Bl -tag -width ".Dv LK_CANRECURSE" .It Dv LK_ADAPTIVE Enable adaptive spinning for this lock if the kernel is compiled with the ADAPTIVE_LOCKMGRS option. .It Dv LK_CANRECURSE Allow recursive exclusive locks. .It Dv LK_NOPROFILE Disable lock profiling for this lock. .It Dv LK_NOSHARE Allow exclusive locks only. .It Dv LK_NOWITNESS Instruct .Xr witness 4 to ignore this lock. .It Dv LK_NODUP .Xr witness 4 should log messages about duplicate locks being acquired. .It Dv LK_QUIET Disable .Xr ktr 4 logging for this lock. .It Dv LK_TIMELOCK Use .Fa timo during a sleep; otherwise, 0 is used. .El .El .Pp The .Fn lockdestroy function is used to destroy a lock, and while it is called in a number of places in the kernel, it currently does nothing. .Pp The .Fn lockmgr and .Fn lockmgr_rw functions handle general locking functionality within the kernel, including support for shared and exclusive locks, and recursion. .Fn lockmgr and .Fn lockmgr_rw are also able to upgrade and downgrade locks. .Pp Their arguments are: .Bl -tag -width ".Fa flags" .It Fa lkp A pointer to the lock to manipulate. .It Fa flags Flags indicating what action is to be taken. .Bl -tag -width ".Dv LK_NODDLKTREAT" .It Dv LK_SHARED Acquire a shared lock. If an exclusive lock is currently held, .Dv EDEADLK will be returned. .It Dv LK_EXCLUSIVE Acquire an exclusive lock. If an exclusive lock is already held, and .Dv LK_CANRECURSE is not set, the system will .Xr panic 9 . .It Dv LK_DOWNGRADE Downgrade exclusive lock to a shared lock. Downgrading a shared lock is not permitted. If an exclusive lock has been recursed, the system will .Xr panic 9 . .It Dv LK_UPGRADE Upgrade a shared lock to an exclusive lock. If this call fails, the shared lock is lost, even if the .Dv LK_NOWAIT flag is specified. During the upgrade, the shared lock could be temporarily dropped. Attempts to upgrade an exclusive lock will cause a .Xr panic 9 . .It Dv LK_TRYUPGRADE Try to upgrade a shared lock to an exclusive lock. The failure to upgrade does not result in the dropping of the shared lock ownership. .It Dv LK_RELEASE Release the lock. Releasing a lock that is not held can cause a .Xr panic 9 . .It Dv LK_DRAIN Wait for all activity on the lock to end, then mark it decommissioned. This is used before freeing a lock that is part of a piece of memory that is about to be freed. (As documented in .In sys/lockmgr.h . ) .It Dv LK_SLEEPFAIL Fail if operation has slept. .It Dv LK_NOWAIT Do not allow the call to sleep. This can be used to test the lock. .It Dv LK_NOWITNESS Skip the .Xr witness 4 checks for this instance. .It Dv LK_CANRECURSE Allow recursion on an exclusive lock. For every lock there must be a release. .It Dv LK_INTERLOCK Unlock the interlock (which should be locked already). .It Dv LK_NODDLKTREAT Normally, .Fn lockmgr postpones serving further shared requests for shared-locked lock if there is exclusive waiter, to avoid exclusive lock starvation. But, if the thread requesting the shared lock already owns a shared lockmgr lock, the request is granted even in presence of the parallel exclusive lock request, which is done to avoid deadlocks with recursive shared acquisition. .Pp The .Dv LK_NODDLKTREAT flag can only be used by code which requests shared non-recursive lock. The flag allows exclusive requests to preempt the current shared request even if the current thread owns shared locks. This is safe since shared lock is guaranteed to not recurse, and is used when thread is known to held unrelated shared locks, to not cause -unnecessary starvation. An example is +unnecessary starvation. +An example is .Dv vp locking in VFS .Xr lookup 9 , when .Dv dvp is already locked. .El .It Fa ilk An interlock mutex for controlling group access to the lock. If .Dv LK_INTERLOCK is specified, .Fn lockmgr and .Fn lockmgr_rw assume .Fa ilk is currently owned and not recursed, and will return it unlocked. See .Xr mtx_assert 9 . .El .Pp The .Fn lockmgr_args and .Fn lockmgr_args_rw function work like .Fn lockmgr and .Fn lockmgr_rw but accepting a .Fa wmesg , .Fa timo and .Fa prio on a per-instance basis. The specified values will override the default ones, but this can still be used passing, respectively, .Dv LK_WMESG_DEFAULT , .Dv LK_PRIO_DEFAULT and .Dv LK_TIMO_DEFAULT . .Pp The .Fn lockmgr_disown function switches the owner from the current thread to be .Dv LK_KERNPROC , if the lock is already held. .Pp The .Fn lockmgr_printinfo function prints debugging information about the lock. It is used primarily by .Xr VOP_PRINT 9 functions. .Pp The .Fn lockmgr_recursed function returns true if the lock is recursed, 0 otherwise. .Pp The .Fn lockmgr_waiters function returns true if the lock has waiters, 0 otherwise. .Pp The .Fn lockstatus function returns the status of the lock in relation to the current thread. .Pp When compiled with .Cd "options INVARIANTS" and .Cd "options INVARIANT_SUPPORT" , the .Fn lockmgr_assert function tests .Fa lkp for the assertions specified in .Fa what , and panics if they are not met. One of the following assertions must be specified: .Bl -tag -width ".Dv KA_UNLOCKED" .It Dv KA_LOCKED Assert that the current thread has either a shared or an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_SLOCKED Assert that the current thread has a shared lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_XLOCKED Assert that the current thread has an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_UNLOCKED Assert that the current thread has no lock on the .Vt lkp lock pointed to by the first argument. .El .Pp In addition, one of the following optional assertions can be used with either an .Dv KA_LOCKED , .Dv KA_SLOCKED , or .Dv KA_XLOCKED assertion: .Bl -tag -width ".Dv KA_NOTRECURSED" .It Dv KA_RECURSED Assert that the current thread has a recursed lock on .Fa lkp . .It Dv KA_NOTRECURSED Assert that the current thread does not have a recursed lock on .Fa lkp . .El .Sh RETURN VALUES The .Fn lockmgr and .Fn lockmgr_rw functions return 0 on success and non-zero on failure. .Pp The .Fn lockstatus function returns: .Bl -tag -width ".Dv LK_EXCLUSIVE" .It Dv LK_EXCLUSIVE An exclusive lock is held by the current thread. .It Dv LK_EXCLOTHER An exclusive lock is held by someone other than the current thread. .It Dv LK_SHARED A shared lock is held. .It Li 0 The lock is not held by anyone. .El .Sh ERRORS .Fn lockmgr and .Fn lockmgr_rw fail if: .Bl -tag -width Er .It Bq Er EBUSY .Dv LK_FORCEUPGRADE was requested and another thread had already requested a lock upgrade. .It Bq Er EBUSY .Dv LK_NOWAIT was set, and a sleep would have been required, or .Dv LK_TRYUPGRADE operation was not able to upgrade the lock. .It Bq Er ENOLCK .Dv LK_SLEEPFAIL was set and .Fn lockmgr or .Fn lockmgr_rw did sleep. .It Bq Er EINTR .Dv PCATCH was set in the lock priority, and a signal was delivered during a sleep. Note the .Er ERESTART error below. .It Bq Er ERESTART .Dv PCATCH was set in the lock priority, a signal was delivered during a sleep, and the system call is to be restarted. .It Bq Er EWOULDBLOCK a non-zero timeout was given, and the timeout expired. .El .Sh LOCKS If .Dv LK_INTERLOCK is passed in the .Fa flags argument to .Fn lockmgr or .Fn lockmgr_rw , the .Fa ilk must be held prior to calling .Fn lockmgr or .Fn lockmgr_rw , and will be returned unlocked. .Pp Upgrade attempts that fail result in the loss of the lock that is currently held. Also, it is invalid to upgrade an exclusive lock, and a .Xr panic 9 will be the result of trying. .Sh SEE ALSO .Xr condvar 9 , .Xr locking 9 , .Xr mtx_assert 9 , .Xr mutex 9 , .Xr panic 9 , .Xr rwlock 9 , .Xr sleep 9 , .Xr sx 9 , .Xr VOP_PRINT 9 .Sh AUTHORS This manual page was written by .An Chad David Aq Mt davidc@acns.ab.ca . Index: head/share/man/man9/locking.9 =================================================================== --- head/share/man/man9/locking.9 (revision 301589) +++ head/share/man/man9/locking.9 (revision 301590) @@ -1,414 +1,415 @@ .\" Copyright (c) 2007 Julian Elischer (julian - freebsd org ) .\" 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 July 5, 2015 .Dt LOCKING 9 .Os .Sh NAME .Nm locking .Nd kernel synchronization primitives .Sh DESCRIPTION The .Em FreeBSD kernel is written to run across multiple CPUs and as such provides several different synchronization primitives to allow developers to safely access and manipulate many data types. .Ss Mutexes Mutexes (also called "blocking mutexes") are the most commonly used synchronization primitive in the kernel. A thread acquires (locks) a mutex before accessing data shared with other threads (including interrupt threads), and releases (unlocks) it afterwards. If the mutex cannot be acquired, the thread requesting it will wait. Mutexes are adaptive by default, meaning that if the owner of a contended mutex is currently running on another CPU, then a thread attempting to acquire the mutex will spin rather than yielding the processor. Mutexes fully support priority propagation. .Pp See .Xr mutex 9 for details. .Ss Spin Mutexes Spin mutexes are a variation of basic mutexes; the main difference between the two is that spin mutexes never block. Instead, they spin while waiting for the lock to be released. To avoid deadlock, a thread that holds a spin mutex must never yield its CPU. Unlike ordinary mutexes, spin mutexes disable interrupts when acquired. Since disabling interrupts can be expensive, they are generally slower to acquire and release. Spin mutexes should be used only when absolutely necessary, e.g. to protect data shared with interrupt filter code (see .Xr bus_setup_intr 9 for details), or for scheduler internals. .Ss Mutex Pools With most synchronization primitives, such as mutexes, the programmer must provide memory to hold the primitive. For example, a mutex may be embedded inside the structure it protects. Mutex pools provide a preallocated set of mutexes to avoid this requirement. Note that mutexes from a pool may only be used as leaf locks. .Pp See .Xr mtx_pool 9 for details. .Ss Reader/Writer Locks Reader/writer locks allow shared access to protected data by multiple threads or exclusive access by a single thread. The threads with shared access are known as .Em readers since they should only read the protected data. A thread with exclusive access is known as a .Em writer since it may modify protected data. .Pp Reader/writer locks can be treated as mutexes (see above and .Xr mutex 9 ) with shared/exclusive semantics. Reader/writer locks support priority propagation like mutexes, but priority is propagated only to an exclusive holder. This limitation comes from the fact that shared owners are anonymous. .Pp See .Xr rwlock 9 for details. .Ss Read-Mostly Locks Read-mostly locks are similar to .Em reader/writer locks but optimized for very infrequent write locking. .Em Read-mostly locks implement full priority propagation by tracking shared owners using a caller-supplied .Em tracker data structure. .Pp See .Xr rmlock 9 for details. .Ss Sleepable Read-Mostly Locks Sleepable read-mostly locks are a variation on read-mostly locks. Threads holding an exclusive lock may sleep, but threads holding a shared lock may not. Priority is propagated to shared owners but not to exclusive owners. .Ss Shared/exclusive locks Shared/exclusive locks are similar to reader/writer locks; the main difference between them is that shared/exclusive locks may be held during unbounded sleep. Acquiring a contested shared/exclusive lock can perform an unbounded sleep. These locks do not support priority propagation. .Pp See .Xr sx 9 for details. .Ss Lockmanager locks Lockmanager locks are sleepable shared/exclusive locks used mostly in .Xr VFS 9 .Po as a .Xr vnode 9 lock .Pc and in the buffer cache .Po .Xr BUF_LOCK 9 .Pc . They have features other lock types do not have such as sleep timeouts, blocking upgrades, writer starvation avoidance, draining, and an interlock mutex, but this makes them complicated both to use and to implement; for this reason, they should be avoided. .Pp See .Xr lock 9 for details. .Ss Counting semaphores Counting semaphores provide a mechanism for synchronizing access to a pool of resources. Unlike mutexes, semaphores do not have the concept of an owner, so they can be useful in situations where one thread needs to acquire a resource, and another thread needs to release it. They are largely deprecated. .Pp See .Xr sema 9 for details. .Ss Condition variables Condition variables are used in conjunction with locks to wait for a condition to become true. A thread must hold the associated lock before calling one of the .Fn cv_wait , functions. When a thread waits on a condition, the lock is atomically released before the thread yields the processor and reacquired before the function call returns. Condition variables may be used with blocking mutexes, reader/writer locks, read-mostly locks, and shared/exclusive locks. .Pp See .Xr condvar 9 for details. .Ss Sleep/Wakeup The functions .Fn tsleep , .Fn msleep , .Fn msleep_spin , .Fn pause , .Fn wakeup , and .Fn wakeup_one also handle event-based thread blocking. Unlike condition variables, arbitrary addresses may be used as wait channels and a dedicated structure does not need to be allocated. However, care must be taken to ensure that wait channel addresses are unique to an event. If a thread must wait for an external event, it is put to sleep by .Fn tsleep , .Fn msleep , .Fn msleep_spin , or .Fn pause . Threads may also wait using one of the locking primitive sleep routines .Xr mtx_sleep 9 , .Xr rw_sleep 9 , or .Xr sx_sleep 9 . .Pp The parameter .Fa chan is an arbitrary address that uniquely identifies the event on which the thread is being put to sleep. All threads sleeping on a single .Fa chan are woken up later by .Fn wakeup .Pq often called from inside an interrupt routine to indicate that the event the thread was blocking on has occurred. .Pp Several of the sleep functions including .Fn msleep , .Fn msleep_spin , and the locking primitive sleep routines specify an additional lock parameter. The lock will be released before sleeping and reacquired before the sleep routine returns. If .Fa priority includes the .Dv PDROP flag, then the lock will not be reacquired before returning. The lock is used to ensure that a condition can be checked atomically, and that the current thread can be suspended without missing a change to the condition or an associated wakeup. In addition, all of the sleep routines will fully drop the .Va Giant mutex .Pq even if recursed while the thread is suspended and will reacquire the .Va Giant mutex .Pq restoring any recursion before the function returns. .Pp The .Fn pause function is a special sleep function that waits for a specified amount of time to pass before the thread resumes execution. This sleep cannot be terminated early by either an explicit .Fn wakeup or a signal. .Pp See .Xr sleep 9 for details. .Ss Giant Giant is a special mutex used to protect data structures that do not yet have their own locks. Since it provides semantics akin to the old .Xr spl 9 interface, Giant has special characteristics: .Bl -enum .It It is recursive. .It Drivers can request that Giant be locked around them by not marking themselves MPSAFE. Note that infrastructure to do this is slowly going away as non-MPSAFE drivers either became properly locked or disappear. .It Giant must be locked before other non-sleepable locks. .It Giant is dropped during unbounded sleeps and reacquired after wakeup. .It There are places in the kernel that drop Giant and pick it back up again. Sleep locks will do this before sleeping. Parts of the network or VM code may do this as well. This means that you cannot count on Giant keeping other code from running if your code sleeps, even if you want it to. .El .Sh INTERACTIONS The primitives can interact and have a number of rules regarding how they can and can not be combined. Many of these rules are checked by .Xr witness 4 . .Ss Bounded vs. Unbounded Sleep In a bounded sleep .Po also referred to as .Dq blocking .Pc the only resource needed to resume execution of a thread is CPU time for the owner of a lock that the thread is waiting to acquire. In an unbounded sleep .Po often referred to as simply .Dq sleeping .Pc a thread waits for an external event or for a condition to become true. In particular, a dependency chain of threads in bounded sleeps should always make forward progress, since there is always CPU time available. This requires that no thread in a bounded sleep is waiting for a lock held by a thread in an unbounded sleep. To avoid priority inversions, a thread in a bounded sleep lends its priority to the owner of the lock that it is waiting for. .Pp The following primitives perform bounded sleeps: mutexes, reader/writer locks and read-mostly locks. .Pp The following primitives perform unbounded sleeps: sleepable read-mostly locks, shared/exclusive locks, lockmanager locks, counting semaphores, condition variables, and sleep/wakeup. .Ss General Principles .Bl -bullet .It It is an error to do any operation that could result in yielding the processor while holding a spin mutex. .It It is an error to do any operation that could result in unbounded sleep while holding any primitive from the 'bounded sleep' group. For example, it is an error to try to acquire a shared/exclusive lock while holding a mutex, or to try to allocate memory with M_WAITOK while holding a reader/writer lock. .Pp Note that the lock passed to one of the .Fn sleep or .Fn cv_wait functions is dropped before the thread enters the unbounded sleep and does not violate this rule. .It It is an error to do any operation that could result in yielding of the processor when running inside an interrupt filter. .It It is an error to do any operation that could result in unbounded sleep when running inside an interrupt thread. .El .Ss Interaction table The following table shows what you can and can not do while holding -one of the locking primitives discussed. Note that +one of the locking primitives discussed. +Note that .Dq sleep includes .Fn sema_wait , .Fn sema_timedwait , any of the .Fn cv_wait functions, and any of the .Fn sleep functions. .Bl -column ".Ic xxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXXXX" ".Xr XXXXXX" -offset 3n .It Em " You want:" Ta spin mtx Ta mutex/rw Ta rmlock Ta sleep rm Ta sx/lk Ta sleep .It Em "You have: " Ta -------- Ta -------- Ta ------ Ta -------- Ta ------ Ta ------ .It spin mtx Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-1 .It mutex/rw Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no-1 .It rmlock Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no-1 .It sleep rm Ta \&ok Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok-2 Ta \&ok-2/3 .It sx Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok-3 .It lockmgr Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok .El .Pp .Em *1 There are calls that atomically release this primitive when going to sleep and reacquire it on wakeup .Po .Fn mtx_sleep , .Fn rw_sleep , .Fn msleep_spin , etc. .Pc . .Pp .Em *2 These cases are only allowed while holding a write lock on a sleepable read-mostly lock. .Pp .Em *3 Though one can sleep while holding this lock, one can also use a .Fn sleep function to atomically release this primitive when going to sleep and reacquire it on wakeup. .Pp Note that non-blocking try operations on locks are always permitted. .Ss Context mode table The next table shows what can be used in different contexts. At this time this is a rather easy to remember table. .Bl -column ".Ic Xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXXXX" ".Xr XXXXXX" -offset 3n .It Em "Context:" Ta spin mtx Ta mutex/rw Ta rmlock Ta sleep rm Ta sx/lk Ta sleep .It interrupt filter: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no .It interrupt thread: Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no .It callout: Ta \&ok Ta \&ok Ta \&ok Ta \&no Ta \&no Ta \&no .It direct callout: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no .It system call: Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok .El .Sh SEE ALSO .Xr witness 4 , .Xr BUS_SETUP_INTR 9 , .Xr condvar 9 , .Xr lock 9 , .Xr LOCK_PROFILING 9 , .Xr mtx_pool 9 , .Xr mutex 9 , .Xr rmlock 9 , .Xr rwlock 9 , .Xr sema 9 , .Xr sleep 9 , .Xr sx 9 , .Xr timeout 9 .Sh HISTORY These functions appeared in .Bsx 4.1 through .Fx 7.0 . .Sh BUGS There are too many locking primitives to choose from. Index: head/share/man/man9/sysctl.9 =================================================================== --- head/share/man/man9/sysctl.9 (revision 301589) +++ head/share/man/man9/sysctl.9 (revision 301590) @@ -1,852 +1,854 @@ .\" .\" Copyright (c) 2006 Robert N. M. Watson .\" 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 23, 2015 .Dt SYSCTL 9 .Os .Sh NAME .Nm SYSCTL_DECL , .Nm SYSCTL_ADD_INT , .Nm SYSCTL_ADD_LONG , .Nm SYSCTL_ADD_NODE , .Nm SYSCTL_ADD_OPAQUE , .Nm SYSCTL_ADD_PROC , .Nm SYSCTL_ADD_QUAD , .Nm SYSCTL_ADD_ROOT_NODE , .Nm SYSCTL_ADD_S8 , .Nm SYSCTL_ADD_S16 , .Nm SYSCTL_ADD_S32 , .Nm SYSCTL_ADD_S64 , .Nm SYSCTL_ADD_STRING , .Nm SYSCTL_ADD_STRUCT , .Nm SYSCTL_ADD_U8 , .Nm SYSCTL_ADD_U16 , .Nm SYSCTL_ADD_U32 , .Nm SYSCTL_ADD_U64 , .Nm SYSCTL_ADD_UAUTO , .Nm SYSCTL_ADD_UINT , .Nm SYSCTL_ADD_ULONG , .Nm SYSCTL_ADD_UQUAD , .Nm SYSCTL_CHILDREN , .Nm SYSCTL_STATIC_CHILDREN , .Nm SYSCTL_NODE_CHILDREN , .Nm SYSCTL_PARENT , .Nm SYSCTL_INT , .Nm SYSCTL_LONG , .Nm SYSCTL_NODE , .Nm SYSCTL_OPAQUE , .Nm SYSCTL_PROC , .Nm SYSCTL_QUAD , .Nm SYSCTL_ROOT_NODE , .Nm SYSCTL_S8 , .Nm SYSCTL_S16 , .Nm SYSCTL_S32 , .Nm SYSCTL_S64 , .Nm SYSCTL_STRING , .Nm SYSCTL_STRUCT , .Nm SYSCTL_U8 , .Nm SYSCTL_U16 , .Nm SYSCTL_U32 , .Nm SYSCTL_U64 , .Nm SYSCTL_UINT , .Nm SYSCTL_ULONG , .Nm SYSCTL_UQUAD .Nd Dynamic and static sysctl MIB creation functions .Sh SYNOPSIS .In sys/types.h .In sys/sysctl.h .Fn SYSCTL_DECL name .Ft struct sysctl_oid * .Fo SYSCTL_ADD_INT .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int *ptr" .Fa "int val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_LONG .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "long *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_NODE .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_OPAQUE .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *ptr" .Fa "intptr_t len" .Fa "const char *format" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_PROC .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *arg1" .Fa "intptr_t arg2" .Fa "int (*handler) (SYSCTL_HANDLERARGS)" .Fa "const char *format" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_QUAD .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int64_t *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_ROOT_NODE .Fa "struct sysctl_ctx_list *ctx" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S8 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int8_t *ptr" .Fa "int8_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S16 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int16_t *ptr" .Fa "int16_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S32 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int32_t *ptr" .Fa "int32_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S64 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int64_t *ptr" .Fa "int64_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_STRING .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "char *ptr" .Fa "intptr_t len" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_STRUCT .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *ptr" .Fa struct_type .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U8 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint8_t *ptr" .Fa "uint8_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U16 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint16_t *ptr" .Fa "uint16_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U32 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint32_t *ptr" .Fa "uint32_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U64 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint64_t *ptr" .Fa "uint64_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_UINT .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "unsigned int *ptr" .Fa "unsigned int val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_ULONG .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "unsigned long *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_UQUAD .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint64_t *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_UAUTO .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid_list * .Fo SYSCTL_CHILDREN .Fa "struct sysctl_oid *oidp" .Fc .Ft struct sysctl_oid_list * .Fo SYSCTL_STATIC_CHILDREN .Fa "struct sysctl_oid_list OID_NAME" .Fc .Ft struct sysctl_oid_list * .Fo SYSCTL_NODE_CHILDREN .Fa "parent" .Fa "name" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_PARENT .Fa "struct sysctl_oid *oid" .Fc .Fn SYSCTL_INT parent number name ctlflags ptr val descr .Fn SYSCTL_LONG parent number name ctlflags ptr val descr .Fn SYSCTL_NODE parent number name ctlflags handler descr .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr .Fn SYSCTL_S8 parent number name ctlflags ptr val descr .Fn SYSCTL_S16 parent number name ctlflags ptr val descr .Fn SYSCTL_S32 parent number name ctlflags ptr val descr .Fn SYSCTL_S64 parent number name ctlflags ptr val descr .Fn SYSCTL_STRING parent number name ctlflags arg len descr .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr .Fn SYSCTL_U8 parent number name ctlflags ptr val descr .Fn SYSCTL_U16 parent number name ctlflags ptr val descr .Fn SYSCTL_U32 parent number name ctlflags ptr val descr .Fn SYSCTL_U64 parent number name ctlflags ptr val descr .Fn SYSCTL_UINT parent number name ctlflags ptr val descr .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr .Sh DESCRIPTION The .Nm SYSCTL kernel interface allows dynamic or static creation of .Xr sysctl 8 MIB entries. All static sysctls are automatically destroyed when the module which they are part of is unloaded. Most top level categories are created statically and are available to all kernel code and its modules. .Sh DESCRIPTION OF ARGUMENTS .Bl -tag -width ctlflags .It Fa ctx Pointer to sysctl context or NULL, if no context. See .Xr sysctl_ctx_init 9 for how to create a new sysctl context. Programmers are strongly advised to use contexts to organize the dynamic OIDs which they create because when a context is destroyed all belonging sysctls are destroyed as well. This makes the sysctl cleanup code much simpler. Else deletion of all created OIDs is required at module unload. .It Fa parent A pointer to a .Li struct sysctl_oid_list , which is the head of the parent's list of children. This pointer is retrieved using the .Fn SYSCTL_STATIC_CHILDREN macro for static sysctls and the .Fn SYSCTL_CHILDREN macro for dynamic sysctls. The .Fn SYSCTL_PARENT macro can be used to get the parent of an OID. The macro returns NULL if there is no parent. .It Fa number The OID number that will be assigned to this OID. In almost all cases this should be set to .Dv OID_AUTO , which will result in the assignment of the next available OID number. .It Fa name The name of the OID. The newly created OID will contain a copy of the name. .It Fa ctlflags A bit mask of sysctl control flags. See the section below describing all the control flags. .It Fa arg1 First callback argument for procedure sysctls. .It Fa arg2 Second callback argument for procedure sysctls. .It Fa len The length of the data pointed to by the .Fa ptr argument. For string type OIDs a length of zero means that .Xr strlen 3 will be used to get the length of the string at each access to the OID. .It Fa ptr Pointer to sysctl variable or string data. For sysctl values the pointer can be SYSCTL_NULL_XXX_PTR which means the OID is read-only and the returned value should be taken from the .Fa val argument. .It Fa val If the .Fa ptr argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID. Else this argument is not used. .It Fa struct_type Name of structure type. .It Fa handler A pointer to the function that is responsible for handling read and write requests to this OID. There are several standard handlers that support operations on nodes, integers, strings and opaque objects. It is possible to define custom handlers using the .Fn SYSCTL_PROC macro or the .Fn SYSCTL_ADD_PROC function. .It Fa format A pointer to a string which specifies the format of the OID in a symbolic way. This format is used as a hint by .Xr sysctl 8 to apply proper data formatting for display purposes. .Pp Current formats: .Bl -tag -width "S,TYPE" -compact -offset indent .It Cm N node .It Cm A .Li "char *" .It Cm I .Li "int" .It Cm IK Ns Op Ar n temperature in Kelvin, multiplied by an optional single digit power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3 gives milliKelvin .It Cm IU .Li "unsigned int" .It Cm L .Li "long" .It Cm LU .Li "unsigned long" .It Cm Q .Li "quad_t" .It Cm QU .Li "u_quad_t" .It Cm "S,TYPE" .Li "struct TYPE" structures .El .It Fa descr A pointer to a textual description of the OID. .El .Sh CREATING ROOT NODES Sysctl MIBs or OIDs are created in a hierarchical tree. The nodes at the bottom of the tree are called root nodes, and have no parent OID. To create bottom tree nodes the .Fn SYSCTL_ROOT_NODE macro or the .Fn SYSCTL_ADD_ROOT_NODE function needs to be used. By default all static sysctl node OIDs are global and need a .Fn SYSCTL_DECL statement prior to their .Fn SYSCTL_NODE definition statement, typically in a so-called header file. .Sh CREATING SYSCTL STRINGS Zero terminated character strings sysctls are created either using the .Fn SYSCTL_STRING macro or the .Fn SYSCTL_ADD_STRING function. If the .Fa len argument in zero, the string length is computed at every access to the OID using .Xr strlen 3 . .Sh CREATING OPAQUE SYSCTLS The .Fn SYSCTL_OPAQUE or .Fn SYSCTL_STRUCT macros or the .Fn SYSCTL_ADD_OPAQUE or .Fn SYSCTL_ADD_STRUCT functions create an OID that handle any chunk of data of the size specified by the .Fa len argument and data pointed to by the .Fa ptr argument. When using the structure version the type is encoded as part of the created sysctl. .Sh CREATING CUSTOM SYSCTLS The .Fn SYSCTL_PROC macro and the .Fn SYSCTL_ADD_PROC function create OIDs with the specified .Pa handler function. The handler is responsible for handling all read and write requests to the OID. This OID type is especially useful if the kernel data is not easily accessible, or needs to be processed before exporting. .Sh CREATING A STATIC SYSCTL Static sysctls are declared using one of the .Fn SYSCTL_INT , .Fn SYSCTL_LONG , .Fn SYSCTL_NODE , .Fn SYSCTL_OPAQUE , .Fn SYSCTL_PROC , .Fn SYSCTL_QUAD , .Fn SYSCTL_ROOT_NODE , .Fn SYSCTL_S8 , .Fn SYSCTL_S16 , .Fn SYSCTL_S32 , .Fn SYSCTL_S64 , .Fn SYSCTL_STRING , .Fn SYSCTL_STRUCT , .Fn SYSCTL_U8 , .Fn SYSCTL_U16 , .Fn SYSCTL_U32 , .Fn SYSCTL_U64 , .Fn SYSCTL_UINT , .Fn SYSCTL_ULONG or .Fn SYSCTL_UQUAD macros. .Sh CREATING A DYNAMIC SYSCTL Dynamic nodes are created using one of the .Fn SYSCTL_ADD_INT , .Fn SYSCTL_ADD_LONG , .Fn SYSCTL_ADD_NODE , .Fn SYSCTL_ADD_OPAQUE , .Fn SYSCTL_ADD_PROC , .Fn SYSCTL_ADD_QUAD , .Fn SYSCTL_ADD_ROOT_NODE , .Fn SYSCTL_ADD_S8 , .Fn SYSCTL_ADD_S16 , .Fn SYSCTL_ADD_S32 , .Fn SYSCTL_ADD_S64 , .Fn SYSCTL_ADD_STRING , .Fn SYSCTL_ADD_STRUCT , .Fn SYSCTL_ADD_U8 , .Fn SYSCTL_ADD_U16 , .Fn SYSCTL_ADD_U32 , .Fn SYSCTL_ADD_U64 , .Fn SYSCTL_ADD_UAUTO , .Fn SYSCTL_ADD_UINT , .Fn SYSCTL_ADD_ULONG , or .Fn SYSCTL_UQUAD functions. See .Xr sysctl_remove_oid 9 or .Xr sysctl_ctx_free 9 for more information on how to destroy a dynamically created OID. .Sh CONTROL FLAGS For most of the above functions and macros, declaring a type as part of the access flags is not necessary \[em] however, when declaring a sysctl implemented by a function, including a type in the access mask is required: .Bl -tag -width ".Dv CTLTYPE_NOFETCH" .It Dv CTLTYPE_NODE This is a node intended to be a parent for other nodes. .It Dv CTLTYPE_INT This is a signed integer. .It Dv CTLTYPE_STRING This is a nul-terminated string stored in a character array. .It Dv CTLTYPE_S8 This is an 8-bit signed integer. .It Dv CTLTYPE_S16 This is a 16-bit signed integer. .It Dv CTLTYPE_S32 This is a 32-bit signed integer. .It Dv CTLTYPE_S64 This is a 64-bit signed integer. .It Dv CTLTYPE_OPAQUE This is an opaque data structure. .It Dv CTLTYPE_STRUCT Alias for .Dv CTLTYPE_OPAQUE . .It Dv CTLTYPE_U8 This is an 8-bit unsigned integer. .It Dv CTLTYPE_U16 This is a 16-bit unsigned integer. .It Dv CTLTYPE_U32 This is a 32-bit unsigned integer. .It Dv CTLTYPE_U64 This is a 64-bit unsigned integer. .It Dv CTLTYPE_UINT This is an unsigned integer. .It Dv CTLTYPE_LONG This is a signed long. .It Dv CTLTYPE_ULONG This is an unsigned long. .El .Pp All sysctl types except for new node declarations require one of the following flags to be set indicating the read and write disposition of the sysctl: .Bl -tag -width ".Dv CTLFLAG_ANYBODY" .It Dv CTLFLAG_RD This is a read-only sysctl. .It Dv CTLFLAG_RDTUN This is a read-only sysctl and tunable which is tried fetched once from the system environment early during module load or system boot. .It Dv CTLFLAG_WR This is a writable sysctl. .It Dv CTLFLAG_RW This sysctl is readable and writable. .It Dv CTLFLAG_RWTUN This is a readable and writeable sysctl and tunable which is tried fetched once from the system environment early during module load or system boot. .It Dv CTLFLAG_NOFETCH In case the node is marked as a tunable using the CTLFLAG_[XX]TUN, this flag will prevent fetching the initial value from the system -environment. Typically this flag should only be used for very early +environment. +Typically this flag should only be used for very early low level system setup code, and not by common drivers and modules. .El .Pp Additionally, any of the following optional flags may also be specified: .Bl -tag -width ".Dv CTLFLAG_ANYBODY" .It Dv CTLFLAG_ANYBODY Any user or process can write to this sysctl. .It Dv CTLFLAG_SECURE This sysctl can be written to only if the effective securelevel of the process is \[<=] 0. .It Dv CTLFLAG_PRISON This sysctl can be written to by processes in .Xr jail 2 . .It Dv CTLFLAG_SKIP When iterating the sysctl name space, do not list this sysctl. .It Dv CTLFLAG_TUN Advisory flag that a system tunable also exists for this variable. The initial sysctl value is tried fetched once from the system environment early during module load or system boot. .It Dv CTLFLAG_DYN Dynamically created OIDs automatically get this flag set. .It Dv CTLFLAG_VNET OID references a VIMAGE-enabled variable. .El .Sh EXAMPLES Sample use of .Fn SYSCTL_DECL to declare the .Va security sysctl tree for use by new nodes: .Bd -literal -offset indent SYSCTL_DECL(_security); .Ed .Pp Examples of integer, opaque, string, and procedure sysctls follow: .Bd -literal -offset indent /* * Example of a constant integer value. Notice that the control * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR, * and the value is declared. */ SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR, sizeof(struct bio), "sizeof(struct bio)"); /* * Example of a variable integer value. Notice that the control * flags are CTLFLAG_RW, the variable pointer is set, and the * value is 0. */ static int doingcache = 1; /* 1 => enable the cache */ SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, "Enable name cache"); /* * Example of a variable string value. Notice that the control * flags are CTLFLAG_RW, that the variable pointer and string * size are set. Unlike newer sysctls, this older sysctl uses a * static oid number. */ char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */ SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW, kernelname, sizeof(kernelname), "Name of kernel file booted"); /* * Example of an opaque data type exported by sysctl. Notice that * the variable pointer and size are provided, as well as a format * string for sysctl(8). */ static l_fp pps_freq; /* scaled frequency offset (ns/s) */ SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD, &pps_freq, sizeof(pps_freq), "I", ""); /* * Example of a procedure based sysctl exporting string * information. Notice that the data type is declared, the NULL * variable pointer and 0 size, the function pointer, and the * format string for sysctl(8). */ SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING | CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A", ""); .Ed .Pp The following is an example of how to create a new top-level category and how to hook up another subtree to an existing static node. This example does not use contexts, which results in tedious management of all intermediate oids, as they need to be freed later on: .Bd -literal -offset indent #include ... /* * Need to preserve pointers to newly created subtrees, * to be able to free them later: */ static struct sysctl_oid *root1; static struct sysctl_oid *root2; static struct sysctl_oid *oidp; static int a_int; static char *string = "dynamic sysctl"; ... root1 = SYSCTL_ADD_ROOT_NODE(NULL, OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1), OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); ... root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug), OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2), OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); .Ed .Pp This example creates the following subtrees: .Bd -literal -offset indent debug.newtree.newstring newtree.newint .Ed .Pp .Em "Care should be taken to free all OIDs once they are no longer needed!" .Sh SYSCTL NAMING When adding, modifying, or removing sysctl names, it is important to be aware that these interfaces may be used by users, libraries, applications, or documentation (such as published books), and are implicitly published application interfaces. As with other application interfaces, caution must be taken not to break existing applications, and to think about future use of new name spaces so as to avoid the need to rename or remove interfaces that might be depended on in the future. .Pp The semantics chosen for a new sysctl should be as clear as possible, and the name of the sysctl must closely reflect its semantics. Therefore the sysctl name deserves a fair amount of consideration. It should be short but yet representative of the sysctl meaning. If the name consists of several words, they should be separated by underscore characters, as in .Va compute_summary_at_mount . Underscore characters may be omitted only if the name consists of not more than two words, each being not longer than four characters, as in .Va bootfile . For boolean sysctls, negative logic should be totally avoided. That is, do not use names like .Va no_foobar or .Va foobar_disable . They are confusing and lead to configuration errors. Use positive logic instead: .Va foobar , .Va foobar_enable . .Pp A temporary sysctl node OID that should not be relied upon must be designated -as such by a leading underscore character in its name. For example: +as such by a leading underscore character in its name. +For example: .Va _dirty_hack . .Sh SEE ALSO .Xr sysctl 3 , .Xr sysctl 8 , .Xr sysctl_add_oid 9 , .Xr sysctl_ctx_free 9 , .Xr sysctl_ctx_init 9 , .Xr sysctl_remove_oid 9 .Sh HISTORY The .Xr sysctl 8 utility first appeared in .Bx 4.4 . .Sh AUTHORS .An -nosplit The .Nm sysctl implementation originally found in .Bx has been extensively rewritten by .An Poul-Henning Kamp in order to add support for name lookups, name space iteration, and dynamic addition of MIB nodes. .Pp This man page was written by .An Robert N. M. Watson . .Sh SECURITY CONSIDERATIONS When creating new sysctls, careful attention should be paid to the security implications of the monitoring or management interface being created. Most sysctls present in the kernel are read-only or writable only by the superuser. Sysctls exporting extensive information on system data structures and operation, especially those implemented using procedures, will wish to implement access control to limit the undesired exposure of information about other processes, network connections, etc. .Pp The following top level sysctl name spaces are commonly used: .Bl -tag -width ".Va regression" .It Va compat Compatibility layer information. .It Va debug Debugging information. Various name spaces exist under .Va debug . .It Va hw Hardware and device driver information. .It Va kern Kernel behavior tuning; generally deprecated in favor of more specific name spaces. .It Va machdep Machine-dependent configuration parameters. .It Va net Network subsystem. Various protocols have name spaces under .Va net . .It Va regression Regression test configuration and information. .It Va security Security and security-policy configuration and information. .It Va sysctl Reserved name space for the implementation of sysctl. .It Va user Configuration settings relating to user application behavior. Generally, configuring applications using kernel sysctls is discouraged. .It Va vfs Virtual file system configuration and information. .It Va vm Virtual memory subsystem configuration and information. .El Index: head/share/man/man9/timeout.9 =================================================================== --- head/share/man/man9/timeout.9 (revision 301589) +++ head/share/man/man9/timeout.9 (revision 301590) @@ -1,846 +1,848 @@ .\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 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. .\" .\" $FreeBSD$ .\" .Dd September 14, 2015 .Dt TIMEOUT 9 .Os .Sh NAME .Nm callout_active , .Nm callout_deactivate , .Nm callout_async_drain , .Nm callout_drain , .Nm callout_handle_init , .Nm callout_init , .Nm callout_init_mtx , .Nm callout_init_rm , .Nm callout_init_rw , .Nm callout_pending , .Nm callout_reset , .Nm callout_reset_curcpu , .Nm callout_reset_on , .Nm callout_reset_sbt , .Nm callout_reset_sbt_curcpu , .Nm callout_reset_sbt_on , .Nm callout_schedule , .Nm callout_schedule_curcpu , .Nm callout_schedule_on , .Nm callout_schedule_sbt , .Nm callout_schedule_sbt_curcpu , .Nm callout_schedule_sbt_on , .Nm callout_stop , .Nm timeout , .Nm untimeout .Nd execute a function after a specified length of time .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .Bd -literal typedef void timeout_t (void *); .Ed .Ft int .Fn callout_active "struct callout *c" .Ft void .Fn callout_deactivate "struct callout *c" .Ft int .Fn callout_async_drain "struct callout *c" "timeout_t *drain" .Ft int .Fn callout_drain "struct callout *c" .Ft void .Fn callout_handle_init "struct callout_handle *handle" .Bd -literal struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle); .Ed .Ft void .Fn callout_init "struct callout *c" "int mpsafe" .Ft void .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags" .Ft void .Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags" .Ft void .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags" .Ft int .Fn callout_pending "struct callout *c" .Ft int .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" .Ft int .Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \ "void *arg" .Ft int .Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \ "void *arg" "int cpu" .Ft int .Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "timeout_t *func" "void *arg" "int flags" .Ft int .Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "timeout_t *func" "void *arg" "int flags" .Ft int .Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags" .Ft int .Fn callout_schedule "struct callout *c" "int ticks" .Ft int .Fn callout_schedule_curcpu "struct callout *c" "int ticks" .Ft int .Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu" .Ft int .Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "int flags" .Ft int .Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "int flags" .Ft int .Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "int cpu" "int flags" .Ft int .Fn callout_stop "struct callout *c" .Ft struct callout_handle .Fn timeout "timeout_t *func" "void *arg" "int ticks" .Ft void .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle" .Sh DESCRIPTION The .Nm callout API is used to schedule a call to an arbitrary function at a specific time in the future. Consumers of this API are required to allocate a callout structure .Pq struct callout for each pending function invocation. This structure stores state about the pending function invocation including the function to be called and the time at which the function should be invoked. Pending function calls can be cancelled or rescheduled to a different time. In addition, a callout structure may be reused to schedule a new function call after a scheduled call is completed. .Pp Callouts only provide a single-shot mode. If a consumer requires a periodic timer, it must explicitly reschedule each function call. This is normally done by rescheduling the subsequent call within the called function. .Pp Callout functions must not sleep. They may not acquire sleepable locks, wait on condition variables, perform blocking allocation requests, or invoke any other action that might sleep. .Pp Each callout structure must be initialized by .Fn callout_init , .Fn callout_init_mtx , .Fn callout_init_rm , or .Fn callout_init_rw before it is passed to any of the other callout functions. The .Fn callout_init function initializes a callout structure in .Fa c that is not associated with a specific lock. If the .Fa mpsafe argument is zero, the callout structure is not considered to be .Dq multi-processor safe ; and the Giant lock will be acquired before calling the callout function and released when the callout function returns. .Pp The .Fn callout_init_mtx , .Fn callout_init_rm , and .Fn callout_init_rw functions initialize a callout structure in .Fa c that is associated with a specific lock. The lock is specified by the .Fa mtx , .Fa rm , or .Fa rw parameter. The associated lock must be held while stopping or rescheduling the callout. The callout subsystem acquires the associated lock before calling the callout function and releases it after the function returns. If the callout was cancelled while the callout subsystem waited for the associated lock, the callout function is not called, and the associated lock is released. This ensures that stopping or rescheduling the callout will abort any previously scheduled invocation. .Pp Only regular mutexes may be used with .Fn callout_init_mtx ; spin mutexes are not supported. A sleepable read-mostly lock .Po one initialized with the .Dv RM_SLEEPABLE flag .Pc may not be used with .Fn callout_init_rm . Similarly, other sleepable lock types such as .Xr sx 9 and .Xr lockmgr 9 cannot be used with callouts because sleeping is not permitted in the callout subsystem. .Pp These .Fa flags may be specified for .Fn callout_init_mtx , .Fn callout_init_rm , or .Fn callout_init_rw : .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED" .It Dv CALLOUT_RETURNUNLOCKED The callout function will release the associated lock itself, so the callout subsystem should not attempt to unlock it after the callout function returns. .It Dv CALLOUT_SHAREDLOCK The lock is only acquired in read mode when running the callout handler. This flag is ignored by .Fn callout_init_mtx . .El .Pp The function .Fn callout_stop cancels a callout .Fa c if it is currently pending. If the callout is pending and successfully stopped, then .Fn callout_stop returns a value of one. If the callout is not set, or has already been serviced, then negative one is returned. If the callout is currently being serviced and cannot be stopped, then zero will be returned. If the callout has an associated lock, then that lock must be held when this function is called. .Pp The function .Fn callout_async_drain is identical to .Fn callout_stop with one difference. When .Fn callout_async_drain returns zero it will arrange for the function .Fa drain to be called using the same argument given to the .Fn callout_reset function. .Fn callout_async_drain If the callout has an associated lock, then that lock must be held when this function is called. Note that when stopping multiple callouts that use the same lock it is possible to get multiple return's of zero and multiple calls to the .Fa drain -function, depending upon which CPU's the callouts are running. The +function, depending upon which CPU's the callouts are running. +The .Fa drain function itself is called from the context of the completing callout i.e. softclock or hardclock, just like a callout itself. p .Pp The function .Fn callout_drain is identical to .Fn callout_stop except that it will wait for the callout .Fa c to complete if it is already in progress. This function MUST NOT be called while holding any locks on which the callout might block, or deadlock will result. Note that if the callout subsystem has already begun processing this callout, then the callout function may be invoked before .Fn callout_drain returns. However, the callout subsystem does guarantee that the callout will be fully stopped before .Fn callout_drain returns. .Pp The .Fn callout_reset and .Fn callout_schedule function families schedule a future function invocation for callout .Fa c . If .Fa c already has a pending callout, it is cancelled before the new invocation is scheduled. These functions return a value of one if a pending callout was cancelled and zero if there was no pending callout. If the callout has an associated lock, then that lock must be held when any of these functions are called. .Pp The time at which the callout function will be invoked is determined by either the .Fa ticks argument or the .Fa sbt , .Fa pr , and .Fa flags arguments. When .Fa ticks is used, the callout is scheduled to execute after .Fa ticks Ns No /hz seconds. Non-positive values of .Fa ticks are silently converted to the value .Sq 1 . .Pp The .Fa sbt , .Fa pr , and .Fa flags arguments provide more control over the scheduled time including support for higher resolution times, specifying the precision of the scheduled time, and setting an absolute deadline instead of a relative timeout. The callout is scheduled to execute in a time window which begins at the time specified in .Fa sbt and extends for the amount of time specified in .Fa pr . If .Fa sbt specifies a time in the past, the window is adjusted to start at the current time. A non-zero value for .Fa pr allows the callout subsystem to coalesce callouts scheduled close to each other into fewer timer interrupts, reducing processing overhead and power consumption. These .Fa flags may be specified to adjust the interpretation of .Fa sbt and .Fa pr : .Bl -tag -width ".Dv C_DIRECT_EXEC" .It Dv C_ABSOLUTE Handle the .Fa sbt argument as an absolute time since boot. By default, .Fa sbt is treated as a relative amount of time, similar to .Fa ticks . .It Dv C_DIRECT_EXEC Run the handler directly from hardware interrupt context instead of from the softclock thread. This reduces latency and overhead, but puts more constraints on the callout function. Callout functions run in this context may use only spin mutexes for locking and should be as small as possible because they run with absolute priority. .It Fn C_PREL Specifies relative event time precision as binary logarithm of time interval divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc. Note that the larger of .Fa pr or this value is used as the length of the time window. Smaller values .Pq which result in larger time intervals allow the callout subsystem to aggregate more events in one timer interrupt. .It Dv C_HARDCLOCK Align the timeouts to .Fn hardclock calls if possible. .El .Pp The .Fn callout_reset functions accept a .Fa func argument which identifies the function to be called when the time expires. It must be a pointer to a function that takes a single .Fa void * argument. Upon invocation, .Fa func will receive .Fa arg as its only argument. The .Fn callout_schedule functions reuse the .Fa func and .Fa arg arguments from the previous callout. Note that one of the .Fn callout_reset functions must always be called to initialize .Fa func and .Fa arg before one of the .Fn callout_schedule functions can be used. .Pp The callout subsystem provides a softclock thread for each CPU in the system. Callouts are assigned to a single CPU and are executed by the softclock thread for that CPU. Initially, callouts are assigned to CPU 0. The .Fn callout_reset_on , .Fn callout_reset_sbt_on , .Fn callout_schedule_on and .Fn callout_schedule_sbt_on functions assign the callout to CPU .Fa cpu . The .Fn callout_reset_curcpu , .Fn callout_reset_sbt_curpu , .Fn callout_schedule_curcpu and .Fn callout_schedule_sbt_curcpu functions assign the callout to the current CPU. The .Fn callout_reset , .Fn callout_reset_sbt , .Fn callout_schedule and .Fn callout_schedule_sbt functions schedule the callout to execute in the softclock thread of the CPU to which it is currently assigned. .Pp Softclock threads are not pinned to their respective CPUs by default. The softclock thread for CPU 0 can be pinned to CPU 0 by setting the .Va kern.pin_default_swi loader tunable to a non-zero value. Softclock threads for CPUs other than zero can be pinned to their respective CPUs by setting the .Va kern.pin_pcpu_swi loader tunable to a non-zero value. .Pp The macros .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate provide access to the current state of the callout. The .Fn callout_pending macro checks whether a callout is .Em pending ; a callout is considered .Em pending when a timeout has been set but the time has not yet arrived. Note that once the timeout time arrives and the callout subsystem starts to process this callout, .Fn callout_pending will return .Dv FALSE even though the callout function may not have finished .Pq or even begun executing. The .Fn callout_active macro checks whether a callout is marked as .Em active , and the .Fn callout_deactivate macro clears the callout's .Em active flag. The callout subsystem marks a callout as .Em active when a timeout is set and it clears the .Em active flag in .Fn callout_stop and .Fn callout_drain , but it .Em does not clear it when a callout expires normally via the execution of the callout function. .Ss "Avoiding Race Conditions" The callout subsystem invokes callout functions from its own thread context. Without some kind of synchronization, it is possible that a callout function will be invoked concurrently with an attempt to stop or reset the callout by another thread. In particular, since callout functions typically acquire a lock as their first action, the callout function may have already been invoked, but is blocked waiting for that lock at the time that another thread tries to reset or stop the callout. .Pp There are three main techniques for addressing these synchronization concerns. The first approach is preferred as it is the simplest: .Bl -enum -offset indent .It Callouts can be associated with a specific lock when they are initialized by .Fn callout_init_mtx , .Fn callout_init_rm , or .Fn callout_init_rw . When a callout is associated with a lock, the callout subsystem acquires the lock before the callout function is invoked. This allows the callout subsystem to transparently handle races between callout cancellation, scheduling, and execution. Note that the associated lock must be acquired before calling .Fn callout_stop or one of the .Fn callout_reset or .Fn callout_schedule functions to provide this safety. .Pp A callout initialized via .Fn callout_init with .Fa mpsafe set to zero is implicitly associated with the .Va Giant mutex. If .Va Giant is held when cancelling or rescheduling the callout, then its use will prevent races with the callout function. .It The return value from .Fn callout_stop .Po or the .Fn callout_reset and .Fn callout_schedule function families .Pc indicates whether or not the callout was removed. If it is known that the callout was set and the callout function has not yet executed, then a return value of .Dv FALSE indicates that the callout function is about to be called. For example: .Bd -literal -offset indent if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) { if (callout_stop(&sc->sc_callout)) { sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING; /* successfully stopped */ } else { /* * callout has expired and callout * function is about to be executed */ } } .Ed .It The .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate macros can be used together to work around the race conditions. When a callout's timeout is set, the callout subsystem marks the callout as both .Em active and .Em pending . When the timeout time arrives, the callout subsystem begins processing the callout by first clearing the .Em pending flag. It then invokes the callout function without changing the .Em active flag, and does not clear the .Em active flag even after the callout function returns. The mechanism described here requires the callout function itself to clear the .Em active flag using the .Fn callout_deactivate macro. The .Fn callout_stop and .Fn callout_drain functions always clear both the .Em active and .Em pending flags before returning. .Pp The callout function should first check the .Em pending flag and return without action if .Fn callout_pending returns .Dv TRUE . This indicates that the callout was rescheduled using .Fn callout_reset just before the callout function was invoked. If .Fn callout_active returns .Dv FALSE then the callout function should also return without action. This indicates that the callout has been stopped. Finally, the callout function should call .Fn callout_deactivate to clear the .Em active flag. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); if (callout_pending(&sc->sc_callout)) { /* callout was reset */ mtx_unlock(&sc->sc_mtx); return; } if (!callout_active(&sc->sc_callout)) { /* callout was stopped */ mtx_unlock(&sc->sc_mtx); return; } callout_deactivate(&sc->sc_callout); /* rest of callout function */ .Ed .Pp Together with appropriate synchronization, such as the mutex used above, this approach permits the .Fn callout_stop and .Fn callout_reset functions to be used at any time without races. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); callout_stop(&sc->sc_callout); /* The callout is effectively stopped now. */ .Ed .Pp If the callout is still pending then these functions operate normally, but if processing of the callout has already begun then the tests in the callout function cause it to return without further action. Synchronization between the callout function and other code ensures that stopping or resetting the callout will never be attempted while the callout function is past the .Fn callout_deactivate call. .Pp The above technique additionally ensures that the .Em active flag always reflects whether the callout is effectively enabled or disabled. If .Fn callout_active returns false, then the callout is effectively disabled, since even if the callout subsystem is actually just about to invoke the callout function, the callout function will return without action. .El .Pp There is one final race condition that must be considered when a callout is being stopped for the last time. In this case it may not be safe to let the callout function itself detect that the callout was stopped, since it may need to access data objects that have already been destroyed or recycled. To ensure that the callout is completely finished, a call to .Fn callout_drain should be used. In particular, a callout should always be drained prior to destroying its associated lock or releasing the storage for the callout structure. .Sh LEGACY API .Bf Sy The functions below are a legacy API that will be removed in a future release. New code should not use these routines. .Ef .Pp The function .Fn timeout schedules a call to the function given by the argument .Fa func to take place after .Fa ticks Ns No /hz seconds. Non-positive values of .Fa ticks are silently converted to the value .Sq 1 . .Fa func should be a pointer to a function that takes a .Fa void * argument. Upon invocation, .Fa func will receive .Fa arg as its only argument. The return value from .Fn timeout is a .Ft struct callout_handle which can be used in conjunction with the .Fn untimeout function to request that a scheduled timeout be canceled. .Pp The function .Fn callout_handle_init can be used to initialize a handle to a state which will cause any calls to .Fn untimeout with that handle to return with no side effects. .Pp Assigning a callout handle the value of .Fn CALLOUT_HANDLE_INITIALIZER performs the same function as .Fn callout_handle_init and is provided for use on statically declared or global callout handles. .Pp The function .Fn untimeout cancels the timeout associated with .Fa handle using the .Fa func and .Fa arg arguments to validate the handle. If the handle does not correspond to a timeout with the function .Fa func taking the argument .Fa arg no action is taken. .Fa handle must be initialized by a previous call to .Fn timeout , .Fn callout_handle_init , or assigned the value of .Fn CALLOUT_HANDLE_INITIALIZER "&handle" before being passed to .Fn untimeout . The behavior of calling .Fn untimeout with an uninitialized handle is undefined. .Pp As handles are recycled by the system, it is possible (although unlikely) that a handle from one invocation of .Fn timeout may match the handle of another invocation of .Fn timeout if both calls used the same function pointer and argument, and the first timeout is expired or canceled before the second call. The timeout facility offers O(1) running time for .Fn timeout and .Fn untimeout . Timeouts are executed from .Fn softclock with the .Va Giant lock held. Thus they are protected from re-entrancy. .Sh RETURN VALUES The .Fn callout_active macro returns the state of a callout's .Em active flag. .Pp The .Fn callout_pending macro returns the state of a callout's .Em pending flag. .Pp The .Fn callout_reset and .Fn callout_schedule function families return a value of one if the callout was pending before the new function invocation was scheduled. .Pp The .Fn callout_stop and .Fn callout_drain functions return a value of one if the callout was still pending when it was called, a zero if the callout could not be stopped and a negative one is it -was either not running or haas already completed. The +was either not running or haas already completed. +The .Fn timeout function returns a .Ft struct callout_handle that can be passed to .Fn untimeout . .Sh HISTORY The current timeout and untimeout routines are based on the work of .An Adam M. Costello and .An George Varghese , published in a technical report entitled .%T "Redesigning the BSD Callout and Timer Facilities" and modified slightly for inclusion in .Fx by .An Justin T. Gibbs . The original work on the data structures used in this implementation was published by .An G. Varghese and .An A. Lauck in the paper .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" in the .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . The current implementation replaces the long standing .Bx linked list callout mechanism which offered O(n) insertion and removal running time but did not generate or require handles for untimeout operations. Index: head/share/man/man9/usbdi.9 =================================================================== --- head/share/man/man9/usbdi.9 (revision 301589) +++ head/share/man/man9/usbdi.9 (revision 301590) @@ -1,641 +1,652 @@ .\" .\" Copyright (c) 2005 Ian Dowse .\" 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 June 24, 2009 .Dt USBDI 9 .Os .Sh NAME .Nm usb_fifo_alloc_buffer , .Nm usb_fifo_attach , .Nm usb_fifo_detach , .Nm usb_fifo_free_buffer , .Nm usb_fifo_get_data , .Nm usb_fifo_get_data_buffer , .Nm usb_fifo_get_data_error , .Nm usb_fifo_get_data_linear , .Nm usb_fifo_put_bytes_max , .Nm usb_fifo_put_data , .Nm usb_fifo_put_data_buffer , .Nm usb_fifo_put_data_error , .Nm usb_fifo_put_data_linear , .Nm usb_fifo_reset , .Nm usb_fifo_softc , .Nm usb_fifo_wakeup , .Nm usbd_do_request , .Nm usbd_do_request_flags , .Nm usbd_errstr , .Nm usbd_lookup_id_by_info , .Nm usbd_lookup_id_by_uaa , .Nm usbd_transfer_clear_stall , .Nm usbd_transfer_drain , .Nm usbd_transfer_pending , .Nm usbd_transfer_poll , .Nm usbd_transfer_setup , .Nm usbd_transfer_start , .Nm usbd_transfer_stop , .Nm usbd_transfer_submit , .Nm usbd_transfer_unsetup , .Nm usbd_xfer_clr_flag , .Nm usbd_xfer_frame_data , .Nm usbd_xfer_frame_len , .Nm usbd_xfer_get_frame , .Nm usbd_xfer_get_priv , .Nm usbd_xfer_is_stalled , .Nm usbd_xfer_max_framelen , .Nm usbd_xfer_max_frames , .Nm usbd_xfer_max_len , .Nm usbd_xfer_set_flag , .Nm usbd_xfer_set_frame_data , .Nm usbd_xfer_set_frame_len , .Nm usbd_xfer_set_frame_offset , .Nm usbd_xfer_set_frames , .Nm usbd_xfer_set_interval , .Nm usbd_xfer_set_priv , .Nm usbd_xfer_set_stall , .Nm usbd_xfer_set_timeout , .Nm usbd_xfer_softc , .Nm usbd_xfer_state , .Nm usbd_xfer_status .Nd Universal Serial Bus driver programming interface .Sh SYNOPSIS .In dev/usb/usb.h .In dev/usb/usbdi.h .In dev/usb/usbdi_util.h .Sh DESCRIPTION The Universal Serial Bus (USB) driver programming interface provides USB peripheral drivers with a host controller independent API for controlling and communicating with USB peripherals. The .Nm usb module supports both USB Host and USB Device side mode. . .Sh USB KERNEL PROGRAMMING Here is a list of commonly used functions: .Pp . .Ft "usb_error_t" .Fo "usbd_transfer_setup" .Fa "udev" .Fa "ifaces" .Fa "pxfer" .Fa "setup_start" .Fa "n_setup" .Fa "priv_sc" .Fa "priv_mtx" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_unsetup" .Fa "pxfer" .Fa "n_setup" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_start" .Fa "xfer" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_stop" .Fa "xfer" .Fc . .Pp . .Ft "void" .Fo "usbd_transfer_drain" .Fa "xfer" .Fc . . . .Sh USB TRANSFER MANAGEMENT FUNCTIONS The USB standard defines four types of USB transfers. . Control transfers, Bulk transfers, Interrupt transfers and Isochronous transfers. . All the transfer types are managed using the following five functions: . .Pp . .Fn usbd_transfer_setup This function will allocate memory for and initialise an array of USB transfers and all required DMA memory. . This function can sleep or block waiting for resources to become available. .Fa udev is a pointer to "struct usb_device". .Fa ifaces -is an array of interface index numbers to use. See "if_index". +is an array of interface index numbers to use. +See "if_index". .Fa pxfer is a pointer to an array of USB transfer pointers that are initialized to NULL, and then pointed to allocated USB transfers. .Fa setup_start is a pointer to an array of USB config structures. .Fa n_setup is a number telling the USB system how many USB transfers should be setup. .Fa priv_sc is the private softc pointer, which will be used to initialize "xfer->priv_sc". .Fa priv_mtx is the private mutex protecting the transfer structure and the -softc. This pointer is used to initialize "xfer->priv_mtx". -This function returns -zero upon success. A non-zero return value indicates failure. +softc. +This pointer is used to initialize "xfer->priv_mtx". +This function returns zero upon success. +A non-zero return value indicates failure. . .Pp . .Fn usbd_transfer_unsetup This function will release the given USB transfers and all allocated resources associated with these USB transfers. .Fa pxfer is a pointer to an array of USB transfer pointers, that may be NULL, that should be freed by the USB system. .Fa n_setup is a number telling the USB system how many USB transfers should be unsetup. . This function can sleep waiting for USB transfers to complete. . This function is NULL safe with regard to the USB transfer structure pointer. . It is not allowed to call this function from the USB transfer callback. . .Pp . .Fn usbd_transfer_start This function will start the USB transfer pointed to by .Fa xfer , if not already started. . This function is always non-blocking and must be called with the so-called private USB mutex locked. . This function is NULL safe with regard to the USB transfer structure pointer. . .Pp . .Fn usbd_transfer_stop This function will stop the USB transfer pointed to by .Fa xfer , if not already stopped. . This function is always non-blocking and must be called with the so-called private USB mutex locked. . This function can return before the USB callback has been called. . This function is NULL safe with regard to the USB transfer structure pointer. . If the transfer was in progress, the callback will called with "USB_ST_ERROR" and "error = USB_ERR_CANCELLED". . .Pp . .Fn usbd_transfer_drain This function will stop an USB transfer, if not already stopped and wait for any additional USB hardware operations to complete. . Buffers that are loaded into DMA using "usbd_xfer_set_frame_data()" can safely be freed after that this function has returned. . This function can block the caller and will not return before the USB callback has been called. . This function is NULL safe with regard to the USB transfer structure pointer. . .Sh USB TRANSFER CALLBACK . The USB callback has three states. . -USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. USB_ST_SETUP is the -initial state. +USB_ST_SETUP, USB_ST_TRANSFERRED and USB_ST_ERROR. +USB_ST_SETUP is the initial state. . After the callback has been called with this state it will always be called back at a later stage in one of the other two states. . The USB callback should not restart the USB transfer in case the error cause is USB_ERR_CANCELLED. . The USB callback is protected from recursion. . That means one can start and stop whatever transfer from the callback of another transfer one desires. . Also the transfer that is currently called back. . Recursion is handled like this that when the callback that wants to recurse returns it is called one more time. . . .Pp . .Fn usbd_transfer_submit This function should only be called from within the USB callback and is used to start the USB hardware. . An USB transfer can have multiple frames consisting of one or more USB packets making up an I/O vector for all USB transfer types. . .Bd -literal -offset indent void usb_default_callback(struct usb_xfer *xfer, usb_error_t error) { int actlen; usbd_xfer_status(xfer, &actlen, NULL, NULL, NULL); switch (USB_GET_STATE(xfer)) { case USB_ST_SETUP: /* * Setup xfer frame lengths/count and data */ usbd_transfer_submit(xfer); break; case USB_ST_TRANSFERRED: /* * Read usb frame data, if any. * "actlen" has the total length for all frames * transferred. */ break; default: /* Error */ /* * Print error message and clear stall * for example. */ break; } /* * Here it is safe to do something without the private * USB mutex locked. */ return; } .Ed . .Sh USB CONTROL TRANSFERS An USB control transfer has three parts. . First the SETUP packet, then DATA packet(s) and then a STATUS packet. . The SETUP packet is always pointed to by frame 0 and the length is set by .Fn usbd_xfer_frame_len also if there should not be -sent any SETUP packet! If an USB control transfer has no DATA stage, +sent any SETUP packet! +If an USB control transfer has no DATA stage, then the number of frames should be set to 1. . Else the default number of frames is 2. . .Bd -literal -offset indent Example1: SETUP + STATUS usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_transfer_submit(xfer); Example2: SETUP + DATA + STATUS usbd_xfer_set_frames(xfer, 2); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_xfer_set_frame_len(xfer, 1, 1); usbd_transfer_submit(xfer); Example3: SETUP + DATA + STATUS - split 1st callback: usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_transfer_submit(xfer); 2nd callback: /* IMPORTANT: frbuffers[0] must still point at the setup packet! */ usbd_xfer_set_frames(xfer, 2); usbd_xfer_set_frame_len(xfer, 0, 0); usbd_xfer_set_frame_len(xfer, 1, 1); usbd_transfer_submit(xfer); Example4: SETUP + STATUS - split 1st callback: usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 8); usbd_xfer_set_flag(xfer, USB_MANUAL_STATUS); usbd_transfer_submit(xfer); 2nd callback: usbd_xfer_set_frames(xfer, 1); usbd_xfer_set_frame_len(xfer, 0, 0); usbd_xfer_clr_flag(xfer, USB_MANUAL_STATUS); usbd_transfer_submit(xfer); .Ed .Sh USB TRANSFER CONFIG To simply the search for endpoints the .Nm usb module defines a USB config structure where it is possible to specify the characteristics of the wanted endpoint. .Bd -literal -offset indent struct usb_config { bufsize, callback direction, endpoint, frames, index flags, interval, timeout, type, }; .Ed . .Pp .Fa type field selects the USB pipe type. . Valid values are: UE_INTERRUPT, UE_CONTROL, UE_BULK, UE_ISOCHRONOUS. . The special value UE_BULK_INTR will select BULK and INTERRUPT pipes. . This field is mandatory. . .Pp .Fa endpoint field selects the USB endpoint number. . A value of 0xFF, "-1" or "UE_ADDR_ANY" will select the first matching endpoint. . This field is mandatory. . .Pp .Fa direction field selects the USB endpoint direction. . A value of "UE_DIR_ANY" will select the first matching endpoint. . Else valid values are: "UE_DIR_IN" and "UE_DIR_OUT". . "UE_DIR_IN" and "UE_DIR_OUT" can be binary OR'ed by "UE_DIR_SID" which means that the direction will be swapped in case of USB_MODE_DEVICE. . Note that "UE_DIR_IN" refers to the data transfer direction of the "IN" tokens and "UE_DIR_OUT" refers to the data transfer direction of the "OUT" tokens. . This field is mandatory. . .Pp .Fa interval field selects the interrupt interval. . The value of this field is given in milliseconds and is independent of device speed. . Depending on the endpoint type, this field has different meaning: .Bl -tag -width "UE_ISOCHRONOUS" .It UE_INTERRUPT "0" use the default interrupt interval based on endpoint descriptor. "Else" use the given value for polling rate. .It UE_ISOCHRONOUS -"0" use default. "Else" the value is ignored. +"0" use default. +"Else" the value is ignored. .It UE_BULK .It UE_CONTROL -"0" no transfer pre-delay. "Else" a delay as given by this field in +"0" no transfer pre-delay. +"Else" a delay as given by this field in milliseconds is inserted before the hardware is started when "usbd_transfer_submit()" is called. .Pp NOTE: The transfer timeout, if any, is started after that the pre-delay has elapsed! .El . .Pp .Fa timeout -field, if non-zero, will set the transfer timeout in milliseconds. If -the "timeout" field is zero and the transfer type is ISOCHRONOUS a +field, if non-zero, will set the transfer timeout in milliseconds. +If the "timeout" field is zero and the transfer type is ISOCHRONOUS a timeout of 250ms will be used. . .Pp .Fa frames -field sets the maximum number of frames. If zero is specified it will -yield the following results: +field sets the maximum number of frames. +If zero is specified it will yield the following results: .Bl -tag -width "UE_INTERRUPT" .It UE_BULK xfer->nframes = 1; .It UE_INTERRUPT xfer->nframes = 1; .It UE_CONTROL xfer->nframes = 2; .It UE_ISOCHRONOUS -Not allowed. Will cause an error. +Not allowed. +Will cause an error. .El . .Pp .Fa ep_index field allows you to give a number, in case more endpoints match the description, that selects which matching "ep_index" should be used. . .Pp .Fa if_index field allows you to select which of the interface numbers in the "ifaces" array parameter passed to "usbd_transfer_setup" that should be used when setting up the given USB transfer. . .Pp .Fa flags field has type "struct usb_xfer_flags" and allows one to set initial -flags an USB transfer. Valid flags are: +flags an USB transfer. +Valid flags are: .Bl -tag -width "force_short_xfer" .It force_short_xfer -This flag forces the last transmitted USB packet to be short. A short -packet has a length of less than "xfer->max_packet_size", which -derives from "wMaxPacketSize". This flag can be changed during -operation. +This flag forces the last transmitted USB packet to be short. +A short packet has a length of less than "xfer->max_packet_size", which +derives from "wMaxPacketSize". +This flag can be changed during operation. .It short_xfer_ok This flag allows the received transfer length, "xfer->actlen" to be -less than "xfer->sumlen" upon completion of a transfer. This flag can -be changed during operation. +less than "xfer->sumlen" upon completion of a transfer. +This flag can be changed during operation. .It short_frames_ok -This flag allows the reception of multiple short USB frames. This flag +This flag allows the reception of multiple short USB frames. +This flag only has effect for BULK and INTERRUPT endpoints and if the number of -frames received is greater than 1. This flag can be changed during -operation. +frames received is greater than 1. +This flag can be changed during operation. .It pipe_bof This flag causes a failing USB transfer to remain first in the PIPE queue except in the case of "xfer->error" equal to -"USB_ERR_CANCELLED". No other USB transfers in the affected PIPE queue +"USB_ERR_CANCELLED". +No other USB transfers in the affected PIPE queue will be started until either: .Bl -tag -width "X" .It 1 The failing USB transfer is stopped using "usbd_transfer_stop()". .It 2 The failing USB transfer performs a successful transfer. .El The purpose of this flag is to avoid races when multiple transfers are queued for execution on an USB endpoint, and the first executing transfer fails leading to the need for clearing of stall for example. . In this case this flag is used to prevent the following USB transfers from being executed at the same time the clear-stall command is executed on the USB control endpoint. . This flag can be changed during operation. .Pp "BOF" is short for "Block On Failure". .Pp NOTE: This flag should be set on all BULK and INTERRUPT USB transfers which use an endpoint that can be shared between userland and kernel. . . .It proxy_buffer Setting this flag will cause that the total buffer size will be rounded up to the nearest atomic hardware transfer size. . The maximum data length of any USB transfer is always stored in the "xfer->max_data_length". . For control transfers the USB kernel will allocate additional space for the 8-bytes of SETUP header. . These 8-bytes are not counted by the "xfer->max_data_length" variable. . This flag can not be changed during operation. . . .It ext_buffer Setting this flag will cause that no data buffer will be allocated. . Instead the USB client must supply a data buffer. . This flag can not be changed during operation. . . .It manual_status Setting this flag prevents an USB STATUS stage to be appended to the end of the USB control transfer. . If no control data is transferred this flag must be cleared. . Else an error will be returned to the USB callback. . This flag is mostly useful for the USB device side. . This flag can be changed during operation. . . .It no_pipe_ok -Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. This -flag can not be changed during operation. +Setting this flag causes the USB_ERR_NO_PIPE error to be ignored. +This flag can not be changed during operation. . . .It stall_pipe .Bl -tag -width "Device Side Mode" .It Device Side Mode Setting this flag will cause STALL pids to be sent to the endpoint belonging to this transfer before the transfer is started. . The transfer is started at the moment the host issues a clear-stall command on the STALL'ed endpoint. . This flag can be changed during operation. .It Host Side Mode Setting this flag will cause a clear-stall control request to be executed on the endpoint before the USB transfer is started. .El .Pp If this flag is changed outside the USB callback function you have to use the "usbd_xfer_set_stall()" and "usbd_transfer_clear_stall()" functions! This flag is automatically cleared after that the stall or clear stall has been executed. . .It pre_scale_frames If this flag is set the number of frames specified is assumed to give the buffering time in milliseconds instead of frames. During transfer setup the frames field is pre scaled with the corresponding value for the endpoint and rounded to the nearest number of frames greater than zero. This option only has effect for ISOCHRONOUS transfers. .El .Pp .Fa bufsize field sets the total buffer size in bytes. . If this field is zero, "wMaxPacketSize" will be used, multiplied by the "frames" field if the transfer type is ISOCHRONOUS. . This is useful for setting up interrupt pipes. . This field is mandatory. .Pp NOTE: For control transfers "bufsize" includes the length of the request structure. . .Pp .Fa callback -pointer sets the USB callback. This field is mandatory. +pointer sets the USB callback. +This field is mandatory. . . .Sh USB LINUX COMPAT LAYER The .Nm usb module supports the Linux USB API. . . .Sh SEE ALSO .Xr libusb 3 , .Xr usb 4 , .Xr usbconfig 8 .Sh STANDARDS The .Nm usb module complies with the USB 2.0 standard. .Sh HISTORY The .Nm usb module has been inspired by the NetBSD USB stack initially written by -Lennart Augustsson. The +Lennart Augustsson. +The .Nm usb module was written by .An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . Index: head/share/man/man9/vn_fullpath.9 =================================================================== --- head/share/man/man9/vn_fullpath.9 (revision 301589) +++ head/share/man/man9/vn_fullpath.9 (revision 301590) @@ -1,125 +1,126 @@ .\" .\" Copyright (c) 2003 Robert N. M. Watson. .\" 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(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 November 23, 2008 .Dt VN_FULLPATH 9 .Os .Sh NAME .Nm vn_fullpath .Nd "convert a vnode reference to a full pathname, given a process context" .Sh SYNOPSIS .In sys/param.h .In sys/vnode.h .Ft int .Fo vn_fullpath .Fa "struct thread *td" "struct vnode *vp" "char **retbuf" "char **freebuf" .Fc .Sh DESCRIPTION The .Fn vn_fullpath function makes a .Dq "best effort" attempt to generate a string pathname for the passed vnode; the resulting path, if any, will be relative to the root directory of the process associated with the passed thread pointer. The .Fn vn_fullpath function is implemented by inspecting the VFS name cache, and attempting to reconstruct a path from the process root to the object. .Pp This process is necessarily unreliable for several reasons: intermediate entries in the path may not be found in the cache; files may have more than one name (hard links), not all file systems use the name cache (specifically, most synthetic file systems do not); a single name may be used for more than one file (in the context of file systems covering other file systems); a file may have no name (if deleted but still open or referenced). However, the resulting string may still be more useable to a user than a vnode pointer value, or a device number and inode number. Code consuming the results of this function should anticipate (and properly handle) failure. .Pp Its arguments are: .Bl -tag -width ".Fa freebuf" .It Fa td The thread performing the call; this pointer will be dereferenced to find the process and its file descriptor structure, in order to identify the root vnode to use. .It Fa vp -The vnode to search for. No need to be locked by the caller. +The vnode to search for. +No need to be locked by the caller. .It Fa retbuf Pointer to a .Vt "char *" that .Fn vn_fullpath may (on success) point at a newly allocated buffer containing the resulting pathname. .It Fa freebuf Pointer to a .Vt "char *" that .Fn vn_fullpath may (on success) point at a buffer to be freed, when the caller is done with .Fa retbuf . .El .Pp Typical consumers will declare two character pointers: .Va fullpath and .Va freepath ; they will set .Va freepath to .Dv NULL , and .Va fullpath to a name to use in the event that the call to .Fn vn_fullpath fails. After done with the value of .Va fullpath , the caller will check if .Va freepath is .Pf non- Dv NULL , and if so, invoke .Xr free 9 with a pool type of .Dv M_TEMP . .Sh RETURN VALUES If the vnode is successfully converted to a pathname, 0 is returned; otherwise, an error number is returned. .Sh SEE ALSO .Xr free 9 .Sh AUTHORS This manual page was written by .An Robert Watson Aq Mt rwatson@FreeBSD.org . Index: head/share/man/man9/zone.9 =================================================================== --- head/share/man/man9/zone.9 (revision 301589) +++ head/share/man/man9/zone.9 (revision 301590) @@ -1,386 +1,388 @@ .\"- .\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav .\" 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 December 20, 2015 .Dt ZONE 9 .Os .Sh NAME .Nm uma_zcreate , .Nm uma_zalloc , .Nm uma_zalloc_arg , .Nm uma_zfree , .Nm uma_zfree_arg , .Nm uma_find_refcnt , .Nm uma_zdestroy , .Nm uma_zone_set_max, .Nm uma_zone_get_max, .Nm uma_zone_get_cur, .Nm uma_zone_set_warning, .Nm uma_zone_set_maxaction .Nd zone allocator .Sh SYNOPSIS .In sys/param.h .In sys/queue.h .In vm/uma.h .Ft uma_zone_t .Fo uma_zcreate .Fa "char *name" "int size" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" .Fa "int align" "uint16_t flags" .Fc .Ft "void *" .Fn uma_zalloc "uma_zone_t zone" "int flags" .Ft "void *" .Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" .Ft void .Fn uma_zfree "uma_zone_t zone" "void *item" .Ft void .Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" .Ft "uint32_t *" .Fn uma_find_refcnt "uma_zone_t zone" "void *item" .Ft void .Fn uma_zdestroy "uma_zone_t zone" .Ft int .Fn uma_zone_set_max "uma_zone_t zone" "int nitems" .Ft int .Fn uma_zone_get_max "uma_zone_t zone" .Ft int .Fn uma_zone_get_cur "uma_zone_t zone" .Ft void .Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning" .Ft void .Fn uma_zone_set_maxaction "uma_zone_t zone" "void (*maxaction)(uma_zone_t)" .In sys/sysctl.h .Fn SYSCTL_UMA_MAX parent nbr name access zone descr .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr .Fn SYSCTL_UMA_CUR parent nbr name access zone descr .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name access zone descr .Sh DESCRIPTION The zone allocator provides an efficient interface for managing dynamically-sized collections of items of similar size. The zone allocator can work with preallocated zones as well as with runtime-allocated ones, and is therefore available much earlier in the boot process than other memory management routines. .Pp A zone is an extensible collection of items of identical size. The zone allocator keeps track of which items are in use and which are not, and provides functions for allocating items from the zone and for releasing them back (which makes them available for later use). .Pp After the first allocation of an item, it will have been cleared to zeroes, however subsequent allocations will retain the contents as of the last free. .Pp The .Fn uma_zcreate function creates a new zone from which items may then be allocated from. The .Fa name argument is a text name of the zone for debugging and stats; this memory should not be freed until the zone has been deallocated. .Pp The .Fa ctor and .Fa dtor arguments are callback functions that are called by the uma subsystem at the time of the call to .Fn uma_zalloc and .Fn uma_zfree respectively. Their purpose is to provide hooks for initializing or destroying things that need to be done at the time of the allocation or release of a resource. A good usage for the .Fa ctor and .Fa dtor callbacks might be to adjust a global count of the number of objects allocated. .Pp The .Fa uminit and .Fa fini arguments are used to optimize the allocation of objects from the zone. They are called by the uma subsystem whenever it needs to allocate or free several items to satisfy requests or memory pressure. A good use for the .Fa uminit and .Fa fini callbacks might be to initialize and destroy mutexes contained within the object. This would allow one to re-use already initialized mutexes when an object is returned from the uma subsystem's object cache. They are not called on each call to .Fn uma_zalloc and .Fn uma_zfree but rather in a batch mode on several objects. .Pp The .Fa flags argument of the .Fn uma_zcreate is a subset of the following flags: .Bl -tag -width "foo" .It Dv UMA_ZONE_NOFREE Slabs of the zone are never returned back to VM. .It Dv UMA_ZONE_REFCNT Each item in the zone would have internal reference counter associated with it. See .Fn uma_find_refcnt . .It Dv UMA_ZONE_NODUMP Pages belonging to the zone will not be included into mini-dumps. .It Dv UMA_ZONE_PCPU An allocation from zone would have .Va mp_ncpu shadow copies, that are privately assigned to CPUs. A CPU can address its private copy using base allocation address plus multiple of current CPU id and .Fn sizeof "struct pcpu" : .Bd -literal -offset indent foo_zone = uma_zcreate(..., UMA_ZONE_PCPU); ... foo_base = uma_zalloc(foo_zone, ...); ... critical_enter(); foo_pcpu = (foo_t *)zpcpu_get(foo_base); /* do something with foo_pcpu */ critical_exit(); .Ed .It Dv UMA_ZONE_OFFPAGE By default book-keeping of items within a slab is done in the slab page itself. This flag explicitly tells subsystem that book-keeping structure should be allocated separately from special internal zone. This flag requires either .Dv UMA_ZONE_VTOSLAB or .Dv UMA_ZONE_HASH , since subsystem requires a mechanism to find a book-keeping structure to an item being freed. The subsystem may choose to prefer offpage book-keeping for certain zones implicitly. .It Dv UMA_ZONE_ZINIT The zone will have its .Ft uma_init method set to internal method that initializes a new allocated slab to all zeros. Do not mistake .Ft uma_init method with .Ft uma_ctor . A zone with .Dv UMA_ZONE_ZINIT flag would not return zeroed memory on every .Fn uma_zalloc . .It Dv UMA_ZONE_HASH The zone should use an internal hash table to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_VTOSLAB The zone should use special field of .Vt vm_page_t to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_MALLOC The zone is for the .Xr malloc 9 subsystem. .It Dv UMA_ZONE_VM The zone is for the VM subsystem. .El .Pp To allocate an item from a zone, simply call .Fn uma_zalloc with a pointer to that zone and set the .Fa flags argument to selected flags as documented in .Xr malloc 9 . It will return a pointer to an item if successful, or .Dv NULL in the rare case where all items in the zone are in use and the allocator is unable to grow the zone and .Dv M_NOWAIT is specified. .Pp Items are released back to the zone from which they were allocated by calling .Fn uma_zfree with a pointer to the zone and a pointer to the item. If .Fa item is .Dv NULL , then .Fn uma_zfree does nothing. .Pp The variations .Fn uma_zalloc_arg and .Fn uma_zfree_arg allow to specify an argument for the .Dv ctor and .Dv dtor functions, respectively. .Pp If zone was created with .Dv UMA_ZONE_REFCNT flag, then pointer to reference counter for an item can be retrieved with help of the .Fn uma_find_refcnt function. .Pp Created zones, which are empty, can be destroyed using .Fn uma_zdestroy , freeing all memory that was allocated for the zone. All items allocated from the zone with .Fn uma_zalloc must have been freed with .Fn uma_zfree before. .Pp The .Fn uma_zone_set_max function limits the number of items .Pq and therefore memory that can be allocated to .Fa zone . The .Fa nitems argument specifies the requested upper limit number of items. The effective limit is returned to the caller, as it may end up being higher than requested due to the implementation rounding up to ensure all memory pages allocated to the zone are utilised to capacity. The limit applies to the total number of items in the zone, which includes allocated items, free items and free items in the per-cpu caches. On systems with more than one CPU it may not be possible to allocate the specified number of items even when there is no shortage of memory, because all of the remaining free items may be in the caches of the other CPUs when the limit is hit. .Pp The .Fn uma_zone_get_max function returns the effective upper limit number of items for a zone. .Pp The .Fn uma_zone_get_cur function returns the approximate current occupancy of the zone. The returned value is approximate because appropriate synchronisation to determine an exact value is not performed by the implementation. This ensures low overhead at the expense of potentially stale data being used in the calculation. .Pp The .Fn uma_zone_set_warning function sets a warning that will be printed on the system console when the given zone becomes full and fails to allocate an item. The warning will be printed no more often than every five minutes. Warnings can be turned off globally by setting the .Va vm.zone_warnings sysctl tunable to .Va 0 . .Pp The .Fn uma_zone_set_maxaction function sets a function that will be called when the given zone becomes full and fails to allocate an item. -The function will be called with the zone locked. Also, the function -that called the allocation function may have held additional locks. Therefore, +The function will be called with the zone locked. +Also, the function +that called the allocation function may have held additional locks. +Therefore, this function should do very little work (similar to a signal handler). .Pp The .Fn SYSCTL_UMA_MAX parent nbr name access zone descr macro declares a static .Xr sysctl oid that exports the effective upper limit number of items for a zone. The .Fa zone argument should be a pointer to .Vt uma_zone_t . A read of the oid returns value obtained through .Fn uma_zone_get_max . A write to the oid sets new value via .Fn uma_zone_set_max . The .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr macro is provided to create this type of oid dynamically. .Pp The .Fn SYSCTL_UMA_CUR parent nbr name access zone descr macro declares a static read-only .Xr sysctl oid that exports the approximate current occupancy of the zone. The .Fa zone argument should be a pointer to .Vt uma_zone_t . A read of the oid returns value obtained through .Fn uma_zone_get_cur . The .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name zone descr macro is provided to create this type of oid dynamically. .Sh RETURN VALUES The .Fn uma_zalloc function returns a pointer to an item, or .Dv NULL if the zone ran out of unused items and .Dv M_NOWAIT was specified. .Sh SEE ALSO .Xr malloc 9 .Sh HISTORY The zone allocator first appeared in .Fx 3.0 . It was radically changed in .Fx 5.0 to function as a slab allocator. .Sh AUTHORS .An -nosplit The zone allocator was written by .An John S. Dyson . The zone allocator was rewritten in large parts by .An Jeff Roberson Aq Mt jeff@FreeBSD.org to function as a slab allocator. .Pp This manual page was written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . Changes for UMA by .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org .