Index: head/share/man/man9/bus_map_resource.9 =================================================================== --- head/share/man/man9/bus_map_resource.9 (revision 309065) +++ head/share/man/man9/bus_map_resource.9 (revision 309066) @@ -1,167 +1,166 @@ .\" -*- nroff -*- .\" .\" Copyright (c) 2016 John H. Baldwin .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 20, 2016 .Dt BUS_MAP_RESOURCE 9 .Os .Sh NAME .Nm bus_map_resource , bus_unmap_resource , resource_init_map_request .Nd map or unmap an active resource .Sh SYNOPSIS .In sys/param.h .In sys/bus.h .Pp .In machine/bus.h .In sys/rman.h .In machine/resource.h .Ft int .Fo bus_map_resource .Fa "device_t dev" "int type" "struct resource *r" .Fa "struct resource_map_request *args" "struct resource_map *map" .Fc .Ft int .Fo bus_unmap_resource .Fa "device_t dev" "int type" "struct resource *r" "struct resource_map *map" .Fc .Ft void .Fn resource_init_map_request "struct resource_map_request *args" .Sh DESCRIPTION These functions create or destroy a mapping of a previously activated resource. Mappings permit CPU access to the resource via the .Xr bus_space 9 API. .Pp The arguments are as follows: .Bl -tag -width indent .It Fa dev The device that owns the resource. .It Fa type The type of resource to map. It is one of: .Pp .Bl -tag -width ".Dv SYS_RES_MEMORY" -compact .It Dv SYS_RES_IOPORT for I/O ports .It Dv SYS_RES_MEMORY for I/O memory .El .It Fa r A pointer to the .Vt "struct resource" returned by .Xr bus_alloc_resource 9 . .It Fa args A set of optional properties to apply when creating a mapping. This argument can be set to .Dv NULL to request a mapping of the entire resource with the default properties. .It Fa map The resource mapping to create or destroy. .El .Ss Resource Mappings Resource mappings are described by a .Vt "struct resource_map" object. This structure contains a .Xr bus_space 9 tag and handle in the .Va r_bustag and .Va r_bushandle members that can be used for CPU access to the mapping. The structure also contains a .Va r_vaddr member which contains the virtual address of the mapping if one exists. .Pp The wrapper API for .Vt "struct resource" objects described in .Xr bus_activate_resource 9 can also be used with .Vt "struct resource_map" . For example, a pointer to a mapping object can be passed as the first argument to .Fn bus_read_4 . This wrapper API is preferred over using the .Va r_bustag and .Va r_bushandle members directly. .Ss Optional Mapping Properties The .Vt "struct resource_map_request" object passed in .Fa args can be used to specify optional properties of a mapping. The structure must be initialized by invoking .Fn resource_init_map_request . Properties are then specified by setting one or more of these members: .Bl -tag -width indent .It Va offset , length These two members specify a region of the resource to map. By default a mapping is created for the entire resource. The .Va offset is relative to the start of the resource. .It Va memattr Specifies a memory attribute to use when mapping the resource. By default memory mappings use the .Dv VM_MEMATTR_UNCACHEABLE attribute. .El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. .Sh EXAMPLES This maps a PCI memory BAR with the write-combining memory attribute and reads the first 32-bit word: .Bd -literal struct resource *r; struct resource_map map; struct resource_map_args args; uint32_t val; int rid; rid = PCIR_BAR(0); r = bus_alloc_resource_any(dev, SYS_RES_MEMORY, &rid, RF_ACTIVE | RF_UNMAPPED); resource_init_map_request(&args); args.memattr = VM_MEMATTR_WRITE_COMBINING; bus_map_resource(dev, SYS_RES_MEMORY, r, &args, &map); val = bus_read_4(&map, 0); .Ed -.Pp -.Sh RETURN VALUES -Zero is returned on success, otherwise an error is returned. .Sh SEE ALSO .Xr bus_activate_resource 9 , .Xr bus_alloc_resource 9 , .Xr bus_space 9 , .Xr device 9 , .Xr driver 9 .Sh AUTHORS This manual page was written by .An John Baldwin Aq Mt jhb@FreeBSD.org . Index: head/share/man/man9/cnv.9 =================================================================== --- head/share/man/man9/cnv.9 (revision 309065) +++ head/share/man/man9/cnv.9 (revision 309066) @@ -1,199 +1,199 @@ .\" .\" Copyright (c) 2016 Adam Starak .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 27, 2016 .Dt CNV 9 .Os .Sh NAME .Nm cnvlist_get, .Nm cnvlist_take, .Nm cnvlist_free, .Nd "API for managing name/value pairs by cookie." .Sh LIBRARY .Lb libnv .Sh SYNOPSIS .In sys/cnv.h .Ft bool .Fn cnvlist_get_bool "void *cookiep" .Ft uint64_t .Fn cnvlist_get_number "void *cookiep" .Ft "const char *" .Fn cnvlist_get_string "void *cookiep" .Ft "const nvlist_t *" .Fn cnvlist_get_nvlist "void *cookiep" .Ft "const void *" .Fn cnvlist_get_binary "void *cookiep" "size_t *sizep" .Ft "const bool *" .Fn cnvlist_get_bool_array "void *cookiep" "size_t *nitemsp" .Ft "const uint64_t *" .Fn cnvlist_get_number_array "void *cookiep" "size_t *nitemsp" .Ft "const char * const *" .Fn cnvlist_get_string_array "void *cookiep" "size_t *nitemsp" .Ft "const nvlist_t * const *" .Fn cnvlist_get_nvlist_array "void *cookiep" "size_t *nitemsp" .Ft int .Fn cnvlist_get_descriptor "void *cookiep" .Ft "const int *" .Fn cnvlist_get_descriptor_array "void *cookiep" "size_t *nitemsp" .\" .Ft bool .Fn cnvlist_take_bool "void *cookiep" .Ft uint64_t .Fn cnvlist_take_number "void *cookiep" .Ft "const char *" .Fn cnvlist_take_string "void *cookiep" .Ft "const nvlist_t *" .Fn cnvlist_take_nvlist "void *cookiep" .Ft "const void *" .Fn cnvlist_take_binary "void *cookiep" "size_t *sizep" .Ft "const bool *" .Fn cnvlist_take_bool_array "void *cookiep" "size_t *nitemsp" .Ft "const uint64_t *" .Fn cnvlist_take_number_array "void *cookiep" "size_t *nitemsp" .Ft "const char * const *" .Fn cnvlist_take_string_array "void *cookiep" "size_t *nitemsp" .Ft "const nvlist_t * const *" .Fn cnvlist_take_nvlist_array "void *cookiep" "size_t *nitemsp" .Ft int .Fn cnvlist_take_descriptor "void *cookiep" -.Ft "const int *' +.Ft "const int *" .Fn cnvlist_take_descriptor_array "void *cookiep" "size_t *nitemsp" .\" .Ft void .Fn cnvlist_free_null "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_bool "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_number "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_string "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_nvlist "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_descriptor "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_binary "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_bool_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_number_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_string_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_nvlist_array "nvlist_t *nvl" "void *cookiep" .Ft void .Fn cnvlist_free_descriptor_array "nvlist_t *nvl" "void *cookiep" .Sh DESCRIPTION The .Nm libnv library permits easy management of name/value pairs and can send and receive them over sockets. For more information, also see .Xr nv 9 . .Pp The concept of cookies is explained in .Fn nvlist_next , .Fn nvlist_get_parent , and .Fn nvlist_get_pararr from .Xr nv 9 . .Pp The .Nm cnvlist_get family of functions obtains the value associated with the given cookie. Returned strings, nvlists, descriptors, binaries, or arrays must not be modified by the user, since they still belong to the nvlist. The nvlist must not be in an error state. .Pp The .Nm cnvlist_take family of functions returns the value associated with the given cookie and removes the element from the nvlist. When the value is a string, binary, or array value, the caller is responsible for freeing the returned memory with .Fn free 3 . When the value is an nvlist, the caller is responsible for destroying the returned nvlist with .Fn nvlist_destroy . When the value is a descriptor, the caller is responsible for closing the returned descriptor with the .Fn close 2 . .Pp The .Nm cnvlist_free family of functions removes an element of the supplied cookie and frees all resources. If an element of the given cookie has the wrong type or does not exist, the program is aborted. .Sh EXAMPLE The following example demonstrates how to deal with cnvlist API. .Bd -literal int type; void *cookie, *scookie, *bcookie; nvlist_t *nvl; char *name; nvl = nvlist_create(0); nvlist_add_bool(nvl, "test", 1 == 2); nvlist_add_string(nvl, "test2", "cnvlist"); cookie = NULL; while (nvlist_next(nvl, &type, &cookie) != NULL) { switch (type) { case NV_TYPE_BOOL: printf("test: %d\\n", cnvlist_get_bool(cookie)); bcookie = cookie; break; case NV_TYPE_STRING: printf("test2: %s\\n", cnvlist_get_string(cookie)); scookie = cookie; break; } } name = cnvlist_take_string(nvl, scookie); cnvlist_free_bool(nvl, bcookie); printf("test2: %s\\n", name); free(name); printf("nvlist_empty = %d\\n", nvlist_empty(nvl)); nvlist_destroy(nvl); return (0); .Ed .Sh SEE ALSO -.Xr nv 9 , .Xr close 2 , -.Xr free 3 +.Xr free 3 , +.Xr nv 9 .Sh AUTHORS -.An -nosplit The .Nm cnv API was created during the Google Summer Of Code 2016 by +.An Adam Starak . Index: head/share/man/man9/counter.9 =================================================================== --- head/share/man/man9/counter.9 (revision 309065) +++ head/share/man/man9/counter.9 (revision 309066) @@ -1,247 +1,246 @@ .\"- .\" Copyright (c) 2013 Gleb Smirnoff .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 14, 2016 .Dt COUNTER 9 .Os .Sh NAME .Nm counter .Nd "SMP-friendly kernel counter implementation" .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .In sys/counter.h .Ft counter_u64_t .Fn counter_u64_alloc "int wait" .Ft void .Fn counter_u64_free "counter_u64_t c" .Ft void .Fn counter_u64_add "counter_u64_t c" "int64_t v" .Ft void .Fn counter_enter .Ft void .Fn counter_exit .Ft void .Fn counter_u64_add_protected "counter_u64_t c" "int64_t v" .Ft uint64_t .Fn counter_u64_fetch "counter_u64_t c" .Ft void .Fn counter_u64_zero "counter_u64_t c" .In sys/sysctl.h .Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr .Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr .Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr .Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr .Sh DESCRIPTION .Nm is a generic facility to create counters that can be utilized for any purpose (such as collecting statistical data). A .Nm is guaranteed to be lossless when several kernel threads do simultaneous updates. However, .Nm does not block the calling thread, also no .Xr atomic 9 operations are used for the update, therefore the counters can be used in any non-interrupt context. Moreover, .Nm has special optimisations for SMP environments, making .Nm update faster than simple arithmetic on the global variable. Thus .Nm is considered suitable for accounting in the performance-critical code paths. .Bl -tag -width indent .It Fn counter_u64_alloc wait Allocate a new 64-bit unsigned counter. The .Fa wait argument is the .Xr malloc 9 wait flag, should be either .Va M_NOWAIT or .Va M_WAITOK . If .Va M_NOWAIT is specified the operation may fail. .It Fn counter_u64_free c Free the previously allocated counter .Fa c . .It Fn counter_u64_add c v Add .Fa v to .Fa c . The KPI does not guarantee any protection from wraparound. .It Fn counter_enter Enter mode that would allow to safely update several counters via .Fn counter_u64_add_protected . On some machines this expands to .Xr critical 9 section, while on other is a nop. See .Sx IMPLEMENTATION DETAILS . .It Fn counter_exit Exit mode for updating several counters. .It Fn counter_u64_add_protected c v Same as .Fn counter_u64_add , but should be preceded by .Fn counter_enter . .It Fn counter_u64_fetch c Take a snapshot of counter .Fa c . The data obtained is not guaranteed to reflect the real cumulative value for any moment. .It Fn counter_u64_zero c Clear the counter .Fa c and set it to zero. .It Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr Declare a static .Xr sysctl oid that would represent a .Nm . The .Fa ptr argument should be a pointer to allocated .Vt counter_u64_t . A read of the oid returns value obtained through .Fn counter_u64_fetch . Any write to the oid zeroes it. .It Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr Create a .Xr sysctl oid that would represent a .Nm . The .Fa ptr argument should be a pointer to allocated .Vt counter_u64_t . A read of the oid returns value obtained through .Fn counter_u64_fetch . Any write to the oid zeroes it. .It Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr Declare a static .Xr sysctl oid that would represent an array of .Nm . The .Fa ptr argument should be a pointer to allocated array of .Vt counter_u64_t's . The .Fa len argument should specify number of elements in the array. A read of the oid returns len-sized array of .Vt uint64_t values obtained through .Fn counter_u64_fetch . Any write to the oid zeroes all array elements. .It Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr Create a .Xr sysctl oid that would represent an array of .Nm . The .Fa ptr argument should be a pointer to allocated array of .Vt counter_u64_t's . The .Fa len argument should specify number of elements in the array. A read of the oid returns len-sized array of .Vt uint64_t values obtained through .Fn counter_u64_fetch . Any write to the oid zeroes all array elements. .El .Sh IMPLEMENTATION DETAILS On all architectures .Nm is implemented using per-CPU data fields that are specially aligned in memory, to avoid inter-CPU bus traffic due to shared use of the variables between CPUs. These are allocated using .Va UMA_ZONE_PCPU .Xr uma 9 zone. The update operation only touches the field that is private to current CPU. Fetch operation loops through all per-CPU fields and obtains a snapshot sum of all fields. .Pp On amd64 a .Nm counter update is implemented as a single instruction without lock semantics, operating on the private data for the current CPU, which is safe against preemption and interrupts. .Pp On i386 architecture, when machine supports the cmpxchg8 instruction, this instruction is used. The multi-instruction sequence provides the same guarantees as the amd64 single-instruction implementation. .Pp On some architectures updating a counter require a .Xr critical 9 section. .Sh EXAMPLES The following example creates a static counter array exported to userspace through a sysctl: .Bd -literal -offset indent #define MY_SIZE 8 static counter_u64_t array[MY_SIZE]; SYSCTL_COUNTER_U64_ARRAY(_debug, OID_AUTO, counter_array, CTLFLAG_RW, &array[0], MY_SIZE, "Test counter array"); .Ed -.Pp .Sh SEE ALSO .Xr atomic 9 , .Xr critical 9 , .Xr locking 9 , .Xr malloc 9 , .Xr sysctl 9 , .Xr uma 9 .Sh HISTORY The .Nm facility first appeared in .Fx 10.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Gleb Smirnoff and .An Konstantin Belousov . Index: head/share/man/man9/osd.9 =================================================================== --- head/share/man/man9/osd.9 (revision 309065) +++ head/share/man/man9/osd.9 (revision 309066) @@ -1,449 +1,450 @@ .\" .\" Copyright (c) 2010 Lawrence Stewart .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification, immediately at the beginning of the file. .\" 2. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR .\" ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 26, 2016 .Dt OSD 9 .Os .Sh NAME .Nm osd , .Nm osd_register , .Nm osd_deregister , .Nm osd_set , .Nm osd_reserve , .Nm osd_set_reserved , .Nm osd_free_reserved , .Nm osd_get , .Nm osd_del , .Nm osd_call , .Nm osd_exit .Nd Object Specific Data .Sh SYNOPSIS .In sys/osd.h .Ft typedef void .Fn "\*(lp*osd_destructor_t\*(rp" "void *value" .Ft typedef int .Fn "\*(lp*osd_method_t\*(rp" "void *obj" "void *data" .Ft int .Fo osd_register .Fa "u_int type" .Fa "osd_destructor_t destructor" .Fa "osd_method_t *methods" .Fc .Ft void .Fo osd_deregister .Fa "u_int type" .Fa "u_int slot" .Fc .Ft int .Fo osd_set .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fa "void *value" .Fc .Ft void ** .Fo osd_reserve .Fa "u_int slot" .Fc .Ft int .Fo osd_set_reserved .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fa "void **rsv" .Fa "void *value" .Fc .Ft void .Fo osd_free_reserved .Fa "void **rsv" .Fc .Ft void * .Fo osd_get .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fc .Ft void .Fo osd_del .Fa "u_int type" .Fa "struct osd *osd" .Fa "u_int slot" .Fc .Ft int .Fo osd_call .Fa "u_int type" .Fa "u_int method" .Fa "void *obj" .Fa "void *data" .Fc .Ft void .Fo osd_exit .Fa "u_int type" .Fa "struct osd *osd" .Fc .Sh DESCRIPTION The .Nm framework provides a mechanism to dynamically associate arbitrary data at run-time with any kernel data structure which has been suitably modified for use with .Nm . The one-off modification required involves embedding a .Vt "struct osd" inside the kernel data structure. .Pp An additional benefit is that after the initial change to a structure is made, all subsequent use of .Nm with the structure involves no changes to the structure's layout. By extension, if the data structure is part of the ABI, .Nm provides a way of extending the structure in an ABI preserving manner. .Pp The details of the embedded .Vt "struct osd" are not relevant to consumers of the .Nm framework and should not be manipulated directly. .Pp Data associated with a structure is referenced by the .Nm framework using a type/slot identifier pair. Types are statically defined in .In sys/osd.h and provide a high-level grouping for slots to be registered under. Slot identifiers are dynamically assigned by the framework when a data type is registered using .Fn osd_register and remains valid until a corresponding call to .Fn osd_deregister . .Ss Functions The .Fn osd_register function registers a type/slot identifier pair with the .Nm framework for use with a new data type. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier should be allocated under. The .Fa destructor argument specifies an optional osd_destructor_t function pointer that will be called for objects of the type being registered which are later destroyed by the .Fn osd_del function. NULL may be passed if no destructor is required. The .Fa methods argument specifies an optional array of osd_method_t function pointers which can be later invoked by the .Fn osd_call function. NULL may be passed if no methods are required. The .Fa methods argument is currently only useful with the OSD_JAIL type identifier. .Pp The .Fn osd_deregister function deregisters a previously registered type/slot identifier pair. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa slot argument specifies the slot identifier which is being deregistered and should be the value that was returned by .Fn osd_register when the data type was registered. .Pp The .Fn osd_set function associates a data object pointer with a kernel data structure's .Vt struct osd member. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd which will have the .Fa value pointer associated with it. The .Fa slot argument specifies the slot identifier to assign the .Fa value pointer to. The .Fa value argument points to a data object to associate with .Fa osd . .Pp The .Fn osd_set_reserved function does the same as .Fn osd_set , but with an extra argument .Fa rsv that is internal-use memory previously allocated via .Fn osd_reserve . .Pp The .Fn osd_get function returns the data pointer associated with a kernel data structure's .Vt struct osd member from the specified type/slot identifier pair. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to retrieve the data pointer from. The .Fa slot argument specifies the slot identifier to retrieve the data pointer from. .Pp The .Fn osd_del function removes the data pointer associated with a kernel data structure's .Vt struct osd member from the specified type/slot identifier pair. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h the slot identifier is allocated under. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to remove the data pointer from. The .Fa slot argument specifies the slot identifier to remove the data pointer from. If an osd_destructor_t function pointer was specified at registration time, the destructor function will be called and passed the data pointer for the type/slot identifier pair which is being deleted. .Pp The .Fn osd_call function calls the specified osd_method_t function pointer for all currently registered slots of a given type on the specified .Fa obj and .Fa data pointers. The function may sleep and therefore cannot be called from a non-sleepable context. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h to call the method for. The .Fa method argument specifies the index into the osd_method_t array that was passed to .Fn osd_register . The .Fa obj and .Fa data arguments are passed to the method function pointer of each slot. .Pp The .Fn osd_exit function removes all data object pointers from all currently registered slots for a given type for the specified kernel data structure's .Vt struct osd member. The .Fa type argument specifies which high-level type grouping from .In sys/osd.h to remove data pointers from. The .Fa osd argument is a pointer to the kernel data structure's .Vt struct osd to remove all data object pointers for all currently registered slots from. .Sh IMPLEMENTATION NOTES .Nm uses a two dimensional matrix (array of arrays) as the data structure to manage the external data associated with a kernel data structure's .Vt struct osd member. The type identifier is used as the index into the outer array, and the slot identifier is used as the index into the inner array. To set or retrieve a data pointer for a given type/slot identifier pair, .Fn osd_set and .Fn osd_get perform the equivalent of array[type][slot], which is both constant time and fast. .Pp If .Fn osd_set is called on a .Vt struct osd for the first time, the array for storing data pointers is dynamically allocated using .Xr malloc 9 with M_NOWAIT to a size appropriate for the slot identifier being set. If a subsequent call to .Fn osd_set attempts to set a slot identifier which is numerically larger than the slot used in the previous .Fn osd_set call, .Xr realloc 9 is used to grow the array to the appropriate size such that the slot identifier can be used. To maximise the efficiency of any code which calls .Fn osd_set sequentially on a number of different slot identifiers (e.g., during an initialisation phase) one should loop through the slot identifiers in descending order from highest to lowest. This will result in only a single .Xr malloc 9 call to create an array of the largest slot size and all subsequent calls to .Fn osd_set will proceed without any .Xr realloc 9 calls. .Pp It is possible for .Fn osd_set to fail to allocate this array. To ensure that such allocation succeeds, .Fn osd_reserve may be called (in a non-blocking context), and it will pre-allocate the memory via .Xr malloc 9 with M_WAITOK. Then this pre-allocated memory is passed to .Fn osd_set_reserved , which will use it if necessary or otherwise discard it. The memory may also be explicitly discarded by calling .Fn osd_free_reserved . As this method always allocates memory whether or not it is ultimately needed, it should be used only rarely, such as in the unlikely event that .Fn osd_set fails. .Pp The .Nm API is geared towards slot identifiers storing pointers to the same underlying data structure type for a given .Nm type identifier. This is not a requirement, and .Xr khelp 9 for example stores completely different data types in slots under the OSD_KHELP type identifier. .Ss Locking .Nm internally uses a mix of .Xr mutex 9 , .Xr rmlock 9 and .Xr sx 9 locks to protect its internal data structures and state. .Pp Responsibility for synchronising access to a kernel data structure's .Vt struct osd member is left to the subsystem that uses the data structure and calls the .Nm API. .Pp .Fn osd_get only acquires an .Xr rmlock in read mode, therefore making it safe to use in the majority of contexts within the kernel including most fast paths. .Sh RETURN VALUES .Fn osd_register returns the slot identifier for the newly registered data type. .Pp .Fn osd_set and .Fn osd_set_reserved return zero on success or ENOMEM if the specified type/slot identifier pair triggered an internal .Xr realloc 9 which failed -.Fn ( osd_set_reserved +.Ns ( +.Fn osd_set_reserved will always succeed when .Fa rsv is non-NULL). .Pp .Fn osd_get returns the data pointer for the specified type/slot identifier pair, or NULL if the slot has not been initialised yet. .Pp .Fn osd_reserve returns a pointer suitable for passing to .Fn osd_set_reserved or .Fn osd_free_reserved . .Pp .Fn osd_call returns zero if no method is run or the method for each slot runs successfully. If a method for a slot returns non-zero, .Fn osd_call terminates prematurely and returns the method's error to the caller. .Sh SEE ALSO .Xr khelp 9 .Sh HISTORY The Object Specific Data (OSD) facility first appeared in .Fx 8.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . .Pp This manual page was written by .An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . Index: head/share/man/man9/pmap_zero_page.9 =================================================================== --- head/share/man/man9/pmap_zero_page.9 (revision 309065) +++ head/share/man/man9/pmap_zero_page.9 (revision 309066) @@ -1,61 +1,60 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 30, 2016 .Dt PMAP_ZERO 9 .Os .Sh NAME .Nm pmap_zero_page , .Nm pmap_zero_area , .Nd zero-fill a page using machine-dependent optimizations .Sh SYNOPSIS .In sys/param.h .In vm/vm.h .In vm/pmap.h .Ft void .Fn pmap_zero_page "vm_page_t m" .Ft void .Fn pmap_zero_page_area "vm_page_t m" "int off" "int size" .Sh DESCRIPTION The .Fn pmap_zero_page function zero-fills an entire page using machine-dependent optimizations. The .Fn pmap_zero_page_area function is used to zero-fill an area of a page. The range specified must not cross a page boundary; it must be contained entirely within a single page. -.Pp .Sh IMPLEMENTATION NOTES This function is required to be implemented for each architecture supported by .Fx . .Sh SEE ALSO .Xr bzero 3 , .Xr pmap 9 .Sh AUTHORS This manual page was written by .An Bruce M Simpson Aq Mt bms@spc.org . Index: head/share/man/man9/rman.9 =================================================================== --- head/share/man/man9/rman.9 (revision 309065) +++ head/share/man/man9/rman.9 (revision 309066) @@ -1,476 +1,476 @@ .\" .\" Copyright (c) 2003 Bruce M Simpson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 20, 2016 .Dt RMAN 9 .Os .Sh NAME .Nm rman , .Nm rman_activate_resource , .Nm rman_adjust_resource , .Nm rman_deactivate_resource , .Nm rman_fini , .Nm rman_init , .Nm rman_init_from_resource , .Nm rman_is_region_manager , .Nm rman_manage_region , .Nm rman_first_free_region , .Nm rman_last_free_region , .Nm rman_release_resource , .Nm rman_reserve_resource , .Nm rman_reserve_resource_bound , .Nm rman_make_alignment_flags , .Nm rman_get_start , .Nm rman_get_end , .Nm rman_get_device , .Nm rman_get_size , .Nm rman_get_flags , .Nm rman_set_mapping , .Nm rman_get_mapping , .Nm rman_set_virtual , .Nm rman_get_virtual , .Nm rman_set_bustag , .Nm rman_get_bustag , .Nm rman_set_bushandle , .Nm rman_get_bushandle , .Nm rman_set_rid , .Nm rman_get_rid .Nd resource management functions .Sh SYNOPSIS .In sys/types.h .In sys/rman.h .Ft int .Fn rman_activate_resource "struct resource *r" .Ft int .Fn rman_adjust_resource "struct resource *r" "rman_res_t start" "rman_res_t end" .Ft int .Fn rman_deactivate_resource "struct resource *r" .Ft int .Fn rman_fini "struct rman *rm" .Ft int .Fn rman_init "struct rman *rm" .Ft int .Fn rman_init_from_resource "struct rman *rm" "struct resource *r" .Ft int .Fn rman_is_region_manager "struct resource *r" "struct rman *rm" .Ft int .Fn rman_manage_region "struct rman *rm" "rman_res_t start" "rman_res_t end" .Ft int .Fn rman_first_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *end" .Ft int .Fn rman_last_free_region "struct rman *rm" "rman_res_t *start" "rman_res_t *end" .Ft int .Fn rman_release_resource "struct resource *r" .Ft "struct resource *" .Fo rman_reserve_resource .Fa "struct rman *rm" "rman_res_t start" "rman_res_t end" "rman_res_t count" .Fa "u_int flags" "struct device *dev" .Fc .Ft "struct resource *" .Fo rman_reserve_resource_bound .Fa "struct rman *rm" "rman_res_t start" "rman_res_t end" "rman_res_t count" .Fa "rman_res_t bound" "u_int flags" "struct device *dev" .Fc .Ft uint32_t .Fn rman_make_alignment_flags "uint32_t size" .Ft rman_res_t .Fn rman_get_start "struct resource *r" .Ft rman_res_t .Fn rman_get_end "struct resource *r" .Ft "struct device *" .Fn rman_get_device "struct resource *r" .Ft rman_res_t .Fn rman_get_size "struct resource *r" .Ft u_int .Fn rman_get_flags "struct resource *r" .Ft void .Fn rman_set_mapping "struct resource *r" "struct resource_map *map" .Ft void .Fn rman_get_mapping "struct resource *r" "struct resource_map *map" .Ft void .Fn rman_set_virtual "struct resource *r" "void *v" .Ft "void *" .Fn rman_get_virtual "struct resource *r" .Ft void .Fn rman_set_bustag "struct resource *r" "bus_space_tag_t t" .Ft bus_space_tag_t .Fn rman_get_bustag "struct resource *r" .Ft void .Fn rman_set_bushandle "struct resource *r" "bus_space_handle_t h" .Ft bus_space_handle_t .Fn rman_get_bushandle "struct resource *r" .Ft void .Fn rman_set_rid "struct resource *r" "int rid" .Ft int .Fn rman_get_rid "struct resource *r" .Sh DESCRIPTION The .Nm set of functions provides a flexible resource management abstraction. It is used extensively by the bus management code. It implements the abstractions of region and resource. A region descriptor is used to manage a region; this could be memory or some other form of bus space. .Pp Each region has a set of bounds. Within these bounds, allocated segments may reside. Each segment, termed a resource, has several properties which are represented by a 16-bit flag register, as follows. .Bd -literal #define RF_ALLOCATED 0x0001 /* resource has been reserved */ #define RF_ACTIVE 0x0002 /* resource allocation has been activated */ #define RF_SHAREABLE 0x0004 /* resource permits contemporaneous sharing */ #define RF_FIRSTSHARE 0x0020 /* first in sharing list */ #define RF_PREFETCHABLE 0x0040 /* resource is prefetchable */ #define RF_UNMAPPED 0x0100 /* don't map resource when activating */ .Ed .Pp Bits 15:10 of the flag register are used to represent the desired alignment of the resource within the region. .Pp The .Fn rman_init function initializes the region descriptor, pointed to by the .Fa rm argument, for use with the resource management functions. It is required that the fields .Va rm_type and .Va rm_descr of .Vt "struct rman" be set before calling .Fn rman_init . The field .Va rm_type shall be set to .Dv RMAN_ARRAY . The field .Va rm_descr shall be set to a string that describes the resource to be managed. The .Va rm_start and .Va rm_end fields may be set to limit the range of acceptable resource addresses. If these fields are not set, .Fn rman_init will initialize them to allow the entire range of resource addresses. It also initializes any mutexes associated with the structure. If .Fn rman_init fails to initialize the mutex, it will return .Er ENOMEM ; otherwise it will return 0 and .Fa rm will be initialized. .Pp The .Fn rman_fini function frees any structures associated with the structure pointed to by the .Fa rm argument. If any of the resources within the managed region have the .Dv RF_ALLOCATED flag set, it will return .Er EBUSY ; otherwise, any mutexes associated with the structure will be released and destroyed, and the function will return 0. .Pp The .Fn rman_manage_region function establishes the concept of a region which is under .Nm control. The .Fa rman argument points to the region descriptor. The .Fa start and .Fa end arguments specify the bounds of the region. If successful, .Fn rman_manage_region will return 0. If the region overlaps with an existing region, it will return .Er EBUSY . If any part of the region falls outside of the valid address range for .Fa rm , it will return .Er EINVAL . .Er ENOMEM will be returned when .Fn rman_manage_region failed to allocate memory for the region. .Pp The .Fn rman_init_from_resource function is a wrapper routine to create a resource manager backed by an existing resource. It initializes .Fa rm using .Fn rman_init and then adds a region to .Fa rm corresponding to the address range allocated to .Fa r via .Fn rman_manage_region . .Pp The .Fn rman_first_free_region and .Fn rman_last_free_region functions can be used to query a resource manager for its first .Pq or last unallocated region. If .Fa rm contains no free region, these functions will return .Er ENOENT . Otherwise, .Fa *start and .Fa *end are set to the bounds of the free region and zero is returned. .Pp The .Fn rman_reserve_resource_bound function is where the bulk of the .Nm logic is located. It attempts to reserve a contiguous range in the specified region .Fa rm for the use of the device .Fa dev . The caller can specify the .Fa start and .Fa end of an acceptable range, as well as a boundary restriction and required aligment, and the code will attempt to find a free segment which fits. The .Fa start argument is the lowest acceptable starting value of the resource. The .Fa end argument is the highest acceptable ending value of the resource. Therefore, .Fa start No + Fa count No \- 1 must be \[<=] .Fa end for any allocation to happen. The aligment requirement .Pq if any is specified in .Fa flags . The .Fa bound argument may be set to specify a boundary restriction such that an allocated region may cross an address that is a multiple of the boundary. The .Fa bound argument must be a power of two. It may be set to zero to specify no boundary restriction. A shared segment will be allocated if the .Dv RF_SHAREABLE flag is set, otherwise an exclusive segment will be allocated. If this shared segment already exists, the caller has its device added to the list of consumers. .Pp The .Fn rman_reserve_resource function is used to reserve resources within a previously established region. It is a simplified interface to .Fn rman_reserve_resource_bound which passes 0 for the .Fa bound argument. .Pp The .Fn rman_make_alignment_flags function returns the flag mask corresponding to the desired alignment .Fa size . This should be used when calling .Fn rman_reserve_resource_bound . .Pp The .Fn rman_is_region_manager function returns true if the allocated resource .Fa r was allocated from .Fa rm . Otherwise, it returns false. .Pp The .Fn rman_adjust_resource function is used to adjust the reserved address range of an allocated resource to reserve .Fa start through .Fa end . It can be used to grow or shrink one or both ends of the resource range. The current implementation does not support entirely relocating the resource and will fail with .Er EINVAL if the new resource range does not overlap the old resource range. If either end of the resource range grows and the new resource range would conflict with another allocated resource, the function will fail with .Er EBUSY . The .Fn rman_adjust_resource function does not support adjusting the resource range for shared resources and will fail such attempts with .Er EINVAL . Upon success, the resource .Fa r will have a start address of .Fa start and an end address of .Fa end and the function will return zero. Note that none of the constraints of the original allocation request such as alignment or boundary restrictions are checked by .Fn rman_adjust_resource . It is the caller's responsibility to enforce any such requirements. .Pp The .Fn rman_release_resource function releases the reserved resource .Fa r . It may attempt to merge adjacent free resources. .Pp The .Fn rman_activate_resource function marks a resource as active, by setting the .Dv RF_ACTIVE flag. If this is a time shared resource, and the caller has not yet acquired the resource, the function returns .Er EBUSY . .Pp The .Fn rman_deactivate_resource function marks a resource .Fa r as inactive, by clearing the .Dv RF_ACTIVE flag. If other consumers are waiting for this range, it will wakeup their threads. .Pp The .Fn rman_get_start , .Fn rman_get_end , .Fn rman_get_size , and .Fn rman_get_flags functions return the bounds, size and flags of the previously reserved resource .Fa r . .Pp The .Fn rman_set_bustag function associates a .Vt bus_space_tag_t .Fa t with the resource .Fa r . The .Fn rman_get_bustag function is used to retrieve this tag once set. .Pp The .Fn rman_set_bushandle function associates a .Vt bus_space_handle_t .Fa h with the resource .Fa r . The .Fn rman_get_bushandle function is used to retrieve this handle once set. .Pp The .Fn rman_set_virtual function is used to associate a kernel virtual address with a resource .Fa r . The .Fn rman_get_virtual function can be used to retrieve the KVA once set. .Pp The .Fn rman_set_mapping function is used to associate a resource mapping with a resource .Fa r . The mapping must cover the entire resource. Setting a mapping sets the associated .Xr bus_space 9 handle and tag for .Fa r as well as the kernel virtual address if the mapping contains one. These individual values can be retrieved via .Fn rman_get_bushandle , .Fn rman_get_bustag , and .Fn rman_get_virtual . .Pp The .Fn rman_get_mapping function can be used to retrieve the associated resource mapping once set. .Pp The .Fn rman_set_rid function associates a resource identifier with a resource .Fa r . The .Fn rman_get_rid function retrieves this RID. .Pp The .Fn rman_get_device function returns a pointer to the device which reserved the resource .Fa r . .Sh SEE ALSO .Xr bus_activate_resource 9 , .Xr bus_adjust_resource 9 , .Xr bus_alloc_resource 9 , .Xr bus_map_resource 9 , .Xr bus_release_resource 9 , -.Xr bus_space 9 , .Xr bus_set_resource 9 , +.Xr bus_space 9 , .Xr mutex 9 .Sh AUTHORS This manual page was written by .An Bruce M Simpson Aq Mt bms@spc.org . Index: head/share/man/man9/tcp_functions.9 =================================================================== --- head/share/man/man9/tcp_functions.9 (revision 309065) +++ head/share/man/man9/tcp_functions.9 (revision 309066) @@ -1,331 +1,332 @@ .\" .\" Copyright (c) 2016 Jonathan Looney .\" 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 28, 2016 .Dt TCP_FUNCTIONS 9 .Os .Sh NAME .Nm tcp_functions .Nd Alternate TCP Stack Framework .Sh SYNOPSIS .In netinet/tcp.h .In netinet/tcp_var.h .Ft int .Fn register_tcp_functions "struct tcp_function_block *blk" "int wait" .Ft int .Fn deregister_tcp_functions "struct tcp_function_block *blk" .Sh DESCRIPTION The .Nm framework allows a kernel developer to implement alternate TCP stacks. The alternate stacks can be compiled in the kernel or can be implemented in loadable kernel modules. This functionality is intended to encourage experimentation with the TCP stack and to allow alternate behaviors to be deployed for different TCP connections on a single system. .Pp A system administrator can set a system default stack. By default, all TCP connections will use the system default stack. Additionally, users can specify a particular stack to use on a per-connection basis. (See .Xr tcp 4 for details on setting the system default stack, or selecting a specific stack for a given connection.) .Pp This man page treats "TCP stacks" as synonymous with "function blocks". This is intentional. A "TCP stack" is a collection of functions that implement a set of behavior. Therefore, an alternate "function block" defines an alternate "TCP stack". .Pp .Nm modules must call the .Fn register_tcp_functions function during initialization and successfully call the .Fn deregister_tcp_functions function prior to allowing the module to be unloaded. .Pp The .Fn register_tcp_functions function requests that the system add a specified function block to the system. .Pp The .Fn deregister_tcp_functions function requests that the system remove a specified function block from the system. If the call fails because sockets are still using the specified function block, the system will mark the function block as being in the process of being removed. This will prevent additional sockets from using the specified function block. However, it will not impact sockets that are already using the function block. .Pp The .Fa blk argument is a pointer to a .Vt "struct tcp_function_block" , which is explained below (see .Sx Function Block Structure ) . The .Fa wait argument is used as the .Fa flags argument to .Xr malloc 9 , and must be set to one of the valid values defined in that man page. .Ss Function Block Structure The .Fa blk argument is a pointer to a .Vt "struct tcp_function_block" , which has the following members: .Bd -literal -offset indent struct tcp_function_block { char tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX]; int (*tfb_tcp_output)(struct tcpcb *); void (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *, struct socket *, struct tcpcb *, int, int, uint8_t, int); int (*tfb_tcp_ctloutput)(struct socket *so, struct sockopt *sopt, struct inpcb *inp, struct tcpcb *tp); /* Optional memory allocation/free routine */ void (*tfb_tcp_fb_init)(struct tcpcb *); void (*tfb_tcp_fb_fini)(struct tcpcb *, int); /* Optional timers, must define all if you define one */ int (*tfb_tcp_timer_stop_all)(struct tcpcb *); void (*tfb_tcp_timer_activate)(struct tcpcb *, uint32_t, u_int); int (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t); void (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t); /* Optional functions */ void (*tfb_tcp_rexmit_tmr)(struct tcpcb *); void (*tfb_tcp_handoff_ok)(struct tcpcb *); /* System use */ volatile uint32_t tfb_refcnt; uint32_t tfb_flags; }; .Ed .Pp The .Va tfb_tcp_block_name field identifies the unique name of the TCP stack, and should be no longer than TCP_FUNCTION_NAME_LEN_MAX-1 characters in length. .Pp The .Va tfb_tcp_output , .Va tfb_tcp_do_segment , and .Va tfb_tcp_ctloutput fields are pointers to functions that perform the equivalent actions as the default .Fn tcp_output , .Fn tcp_do_segment , and .Fn tcp_default_ctloutput functions, respectively. Each of these function pointers must be non-NULL. .Pp If a TCP stack needs to initialize data when a socket first selects the TCP stack (or, when the socket is first opened), it should set a non-NULL pointer in the .Va tfb_tcp_fb_init field. Likewise, if a TCP stack needs to cleanup data when a socket stops using the TCP stack (or, when the socket is closed), it should set a non-NULL pointer in the .Va tfb_tcp_fb_fini field. .Pp If the .Va tfb_tcp_fb_fini argument is non-NULL, the function to which it points is called when the kernel is destroying the TCP control block or when the socket is transitioning to use a different TCP stack. The function is called with arguments of the TCP control block and an integer flag. The flag will be zero if the socket is transitioning to use another TCP stack or one if the TCP control block is being destroyed. .Pp If the TCP stack implements additional timers, the TCP stack should set a non-NULL pointer in the .Va tfb_tcp_timer_stop_all , .Va tfb_tcp_timer_activate , .Va tfb_tcp_timer_active , and .Va tfb_tcp_timer_stop fields. These fields should all be .Dv NULL or should all contain pointers to functions. The .Va tfb_tcp_timer_activate , .Va tfb_tcp_timer_active , and .Va tfb_tcp_timer_stop functions will be called when the .Fn tcp_timer_activate , .Fn tcp_timer_active , and .Fn tcp_timer_stop functions, respectively, are called with a timer type other than the standard types. The functions defined by the TCP stack have the same semantics (both for arguments and return values) as the normal timer functions they supplement. .Pp Additionally, a stack may define its own actions to take when the retransmit timer fires by setting a non-NULL function pointer in the .Va tfb_tcp_rexmit_tmr field. This function is called very early in the process of handling a retransmit timer. However, care must be taken to ensure the retransmit timer leaves the TCP control block in a valid state for the remainder of the retransmit timer logic. .Pp A user may select a new TCP stack before calling .Xr connect 2 or .Xr listen 2 . Optionally, a TCP stack may also allow a user to begin using the TCP stack for a connection that is in a later state by setting a non-NULL function pointer in the .Va tfb_tcp_handoff_ok field. If this field is non-NULL and a user attempts to select that TCP stack after calling .Xr connect 2 or .Xr listen 2 for that socket, the kernel will call the function pointed to by the .Va tfb_tcp_handoff_ok field. The function should return 0 if the user is allowed to switch the socket to use the TCP stack. Otherwise, the function should return an error code, which will be returned to the user. If the .Va tfb_tcp_handoff_ok field is .Dv NULL and a user attempts to select the TCP stack after calling .Xr connect 2 or .Xr listen 2 for that socket, the operation will fail and the kernel will return .Er EINVAL . .Pp The .Va tfb_refcnt and .Va tfb_flags fields are used by the kernel's TCP code and will be initialized when the TCP stack is registered. .Ss Requirements for Alternate TCP Stacks If the TCP stack needs to store data beyond what is stored in the default TCP control block, the TCP stack can initialize its own per-connection storage. The .Va t_fb_ptr field in the .Vt "struct tcpcb" control block structure has been reserved to hold a pointer to this per-connection storage. If the TCP stack uses this alternate storage, it should understand that the value of the .Va t_fb_ptr pointer may not be initialized to .Dv NULL . Therefore, it should use a .Va tfb_tcp_fb_init function to initialize this field. Additionally, it should use a .Va tfb_tcp_fb_fini function to deallocate storage when the socket is closed. .Pp It is understood that alternate TCP stacks may keep different sets of data. However, in order to ensure that data is available to both the user and the rest of the system in a standardized format, alternate TCP stacks must update all fields in the TCP control block to the greatest extent practical. .Sh RETURN VALUES The .Fn register_tcp_functions and .Fn deregister_tcp_functions functions return zero on success and non-zero on failure. In particular, the .Fn deregister_tcp_functions will return .Er EBUSY until no more connections are using the specified TCP stack. A module calling .Fn deregister_tcp_functions must be prepared to wait until all connections have stopped using the specified TCP stack. .Sh ERRORS The .Fn register_tcp_functions function will fail if: .Bl -tag -width Er .It Bq Er EINVAL Any of the members of the .Fa blk argument are set incorrectly. .It Bq Er ENOMEM The function could not allocate memory for its internal data. .It Bq Er EALREADY A function block is already registered with the same name. .El The .Fn deregister_tcp_functions function will fail if: .Bl -tag -width Er .It Bq Er EPERM The .Fa blk argument references the kernel's compiled-in default function block. .It Bq Er EBUSY The function block is still in use by one or more sockets, or is defined as the current default function block. .It Bq Er ENOENT The .Fa blk argument references a function block that is not currently registered. +.El .Sh SEE ALSO .Xr connect 2 , .Xr listen 2 , .Xr tcp 4 , .Xr malloc 9 .Sh HISTORY This framework first appeared in .Fx 11.0 . .Sh AUTHORS .An -nosplit The .Nm framework was written by .An Randall Stewart Aq Mt rrs@FreeBSD.org . .Pp This manual page was written by .An Jonathan Looney Aq Mt jtl@FreeBSD.org .