Index: user/imp/camdoc/vrele.9 =================================================================== --- user/imp/camdoc/vrele.9 (nonexistent) +++ user/imp/camdoc/vrele.9 (revision 296049) @@ -0,0 +1,103 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" Copyright (c) 2010 Konstantin Belousov +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 24, 2016 +.Dt VRELE 9 +.Os +.Sh NAME +.Nm vput , +.Nm vrele , +.Nm vunref +.Nd decrement the use count for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vput "struct vnode *vp" +.Ft void +.Fn vrele "struct vnode *vp" +.Ft void +.Fn vunref "struct vnode *vp" +.Sh DESCRIPTION +Decrement the +.Va v_usecount +field of a vnode. +.Bl -tag -width 2n +.It Fa vp +the vnode to decrement +.El +.Pp +The +.Fn vrele +function takes an unlocked vnode and returns with the vnode unlocked. +.Pp +The +.Fn vput +function should be given a locked vnode as argument, the vnode is unlocked +after the function returned. +The +.Fn vput +is operationally equivalent to calling +.Xr VOP_UNLOCK 9 +followed by +.Xr vrele 9 , +with less overhead. +.Pp +The +.Fn vunref +function takes a locked vnode as argument, and returns with the vnode locked. +.Pp +Any code in the system which signified its use of a vnode by usecount +should call one of the listed function to decrement use counter. +If the +.Va v_usecount +field of the non-doomed vnode reaches zero, then it will be inactivated +and placed on the free list. +.Pp +The +.Fn vrele +function may lock the vnode. +All three functions may sleep. +.Pp +The hold count for the vnode is always greater or equal to the usecount. +Non-forced unmount fails when mount point owns a vnode that has non-zero +usecount, see +.Xr vflush 9 . +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vref 9 , +.Xr vrefcnt 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson +and +.An Konstantin Belousov . Property changes on: user/imp/camdoc/vrele.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bios.9 =================================================================== --- user/imp/camdoc/bios.9 (nonexistent) +++ user/imp/camdoc/bios.9 (revision 296049) @@ -0,0 +1,180 @@ +.\" $FreeBSD$ +.\" +.\" Copyright (c) 1997 Michael Smith +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd August 9, 2005 +.Dt BIOS 9 +.Os +.Sh NAME +.Nm bios_sigsearch , +.Nm bios32_SDlookup , +.Nm bios32 , +.Nm bios_oem_strings +.Nd interact with PC BIOS +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.In machine/pc/bios.h +.Ft uint32_t +.Fn bios_sigsearch "uint32_t start" "u_char *sig" "int siglen" "int paralen" "int sigofs" +.Ft int +.Fn bios32_SDlookup "struct bios32_SDentry *ent" +.Ft int +.Fn bios32 "struct bios_regs *br" "u_int offset" "u_short segment" +.Fn BIOS_PADDRTOVADDR "addr" +.Fn BIOS_VADDRTOPADDR "addr" +.Vt extern struct bios32_SDentry PCIbios ; +.Vt extern struct SMBIOS_table SMBIOStable ; +.Vt extern struct DMI_table DMItable ; +.Ft int +.Fn bios_oem_strings "struct bios_oem *oem" "u_char *buffer" "size_t maxlen" +.Bd -literal +struct bios_oem_signature { + char * anchor; /* search anchor string in BIOS memory */ + size_t offset; /* offset from anchor (may be negative) */ + size_t totlen; /* total length of BIOS string to copy */ +}; +struct bios_oem_range { + u_int from; /* shouldn't be below 0xe0000 */ + u_int to; /* shouldn't be above 0xfffff */ +}; +struct bios_oem { + struct bios_oem_range range; + struct bios_oem_signature signature[]; +}; +.Ed +.Sh DESCRIPTION +These functions provide a general-purpose interface for dealing with +the BIOS functions and data encountered on x86 PC-architecture systems. +.Bl -tag -width 20n +.It Fn bios_sigsearch +Searches the BIOS address space for a service signature, usually an +uppercase ASCII sequence surrounded by underscores. +The search begins at +.Fa start , +or at the beginning of the BIOS if +.Fa start +is zero. +.Fa siglen +bytes of the BIOS image and +.Fa sig +are compared at +.Fa sigofs +bytes offset from the current location. +If no match is found, the +current location is incremented by +.Fa paralen +bytes and the search repeated. +If the signature is found, its effective +physical address is returned. +If no signature is found, zero is returned. +.It Fn bios_oem_strings +Searches a given BIOS memory range for one or more strings, +and composes a printable concatenation of those found. +The routine expects a structure describing the BIOS address +.Fa range +(within +.Li 0xe0000 +- +.Li 0xfffff ) , +and a { +.Dv NULL , Li 0 , 0 +} -terminated array of +.Vt bios_oem_signature +structures which define the +.Va anchor +string, an +.Va offset +from the beginning of the match (which may be negative), and +.Va totlen +number of bytes to be collected from BIOS memory starting at that offset. +Unmatched anchors are ignored, whereas matches are copied from BIOS memory +starting at their corresponding +.Vt offset +with unprintable characters being replaced with space, and consecutive spaces +being suppressed. +This composed string is stored in +.Fa buffer +up to the given +.Fa maxlen +bytes (including trailing +.Ql \e0 , +and any trailing space suppressed). +If an error is encountered, i.e.\& trying to read out of said BIOS range, +other invalid input, or +.Fa buffer +overflow, a negative integer is returned, otherwise the +length of the composed string is returned. +In particular, a return +value of 0 means that none of the given anchor strings were found in +the specified BIOS memory range. +.It Fn BIOS_VADDRTOPADDR +Returns the effective physical address which corresponds to the kernel +virtual address +.Fa addr . +.It Fn BIOS_PADDRTOVADDR +Returns the kernel virtual address which corresponds to the effective +physical address +.Fa addr . +.It SMBIOStable +If not NULL, points to a +.Ft struct SMBIOS_table +structure containing information read from the System Management BIOS table +during system startup. +.It DMItable +If not NULL, points to a +.Ft struct DMI_table +structure containing information read from the Desktop Management Interface +parameter table during system startup. +.El +.Sh BIOS32 +At system startup, the BIOS is scanned for the BIOS32 Service Directory +(part of the PCI specification), and the existence of the directory is +recorded. +This can then be used to locate other services. +.Bl -tag -width 20n +.It Fn bios32_SDlookup +Attempts to locate the BIOS32 service matching the 4-byte identifier +passed in the +.Fa ident +field of the +.Fa ent +argument. +.It Fn bios32 +Calls a bios32 function. +This presumes that the function is capable of +working within the kernel segment (normally the case). +The virtual address +of the entrypoint is supplied in +.Fa entry +and the register arguments to the function are supplied in +.Fa args . +.It PCIbios +If not NULL, points to a +.Ft struct bios32_SDentry +structure describing the PCI BIOS entrypoint which was found during system +startup. +.El Property changes on: user/imp/camdoc/bios.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mod_cc.9 =================================================================== --- user/imp/camdoc/mod_cc.9 (nonexistent) +++ user/imp/camdoc/mod_cc.9 (revision 296049) @@ -0,0 +1,350 @@ +.\" +.\" Copyright (c) 2008-2009 Lawrence Stewart +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this documentation were written at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by David Hayes and Lawrence Stewart under sponsorship from the +.\" FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE 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 January 21, 2016 +.Dt MOD_CC 9 +.Os +.Sh NAME +.Nm mod_cc , +.Nm DECLARE_CC_MODULE , +.Nm CCV +.Nd Modular Congestion Control +.Sh SYNOPSIS +.In netinet/tcp.h +.In netinet/cc/cc.h +.In netinet/cc/cc_module.h +.Fn DECLARE_CC_MODULE "ccname" "ccalgo" +.Fn CCV "ccv" "what" +.Sh DESCRIPTION +The +.Nm +framework allows congestion control algorithms to be implemented as dynamically +loadable kernel modules via the +.Xr kld 4 +facility. +Transport protocols can select from the list of available algorithms on a +connection-by-connection basis, or use the system default (see +.Xr mod_cc 4 +for more details). +.Pp +.Nm +modules are identified by an +.Xr ascii 7 +name and set of hook functions encapsulated in a +.Vt "struct cc_algo" , +which has the following members: +.Bd -literal -offset indent +struct cc_algo { + char name[TCP_CA_NAME_MAX]; + int (*mod_init) (void); + int (*mod_destroy) (void); + int (*cb_init) (struct cc_var *ccv); + void (*cb_destroy) (struct cc_var *ccv); + void (*conn_init) (struct cc_var *ccv); + void (*ack_received) (struct cc_var *ccv, uint16_t type); + void (*cong_signal) (struct cc_var *ccv, uint32_t type); + void (*post_recovery) (struct cc_var *ccv); + void (*after_idle) (struct cc_var *ccv); + int (*ctl_output)(struct cc_var *, struct sockopt *, void *); +}; +.Ed +.Pp +The +.Va name +field identifies the unique name of the algorithm, and should be no longer than +TCP_CA_NAME_MAX-1 characters in length (the TCP_CA_NAME_MAX define lives in +.In netinet/tcp.h +for compatibility reasons). +.Pp +The +.Va mod_init +function is called when a new module is loaded into the system but before the +registration process is complete. +It should be implemented if a module needs to set up some global state prior to +being available for use by new connections. +Returning a non-zero value from +.Va mod_init +will cause the loading of the module to fail. +.Pp +The +.Va mod_destroy +function is called prior to unloading an existing module from the kernel. +It should be implemented if a module needs to clean up any global state before +being removed from the kernel. +The return value is currently ignored. +.Pp +The +.Va cb_init +function is called when a TCP control block +.Vt struct tcpcb +is created. +It should be implemented if a module needs to allocate memory for storing +private per-connection state. +Returning a non-zero value from +.Va cb_init +will cause the connection set up to be aborted, terminating the connection as a +result. +.Pp +The +.Va cb_destroy +function is called when a TCP control block +.Vt struct tcpcb +is destroyed. +It should be implemented if a module needs to free memory allocated in +.Va cb_init . +.Pp +The +.Va conn_init +function is called when a new connection has been established and variables are +being initialised. +It should be implemented to initialise congestion control algorithm variables +for the newly established connection. +.Pp +The +.Va ack_received +function is called when a TCP acknowledgement (ACK) packet is received. +Modules use the +.Fa type +argument as an input to their congestion management algorithms. +The ACK types currently reported by the stack are CC_ACK and CC_DUPACK. +CC_ACK indicates the received ACK acknowledges previously unacknowledged data. +CC_DUPACK indicates the received ACK acknowledges data we have already received +an ACK for. +.Pp +The +.Va cong_signal +function is called when a congestion event is detected by the TCP stack. +Modules use the +.Fa type +argument as an input to their congestion management algorithms. +The congestion event types currently reported by the stack are CC_ECN, CC_RTO, +CC_RTO_ERR and CC_NDUPACK. +CC_ECN is reported when the TCP stack receives an explicit congestion notification +(RFC3168). +CC_RTO is reported when the retransmission time out timer fires. +CC_RTO_ERR is reported if the retransmission time out timer fired in error. +CC_NDUPACK is reported if N duplicate ACKs have been received back-to-back, +where N is the fast retransmit duplicate ack threshold (N=3 currently as per +RFC5681). +.Pp +The +.Va post_recovery +function is called after the TCP connection has recovered from a congestion event. +It should be implemented to adjust state as required. +.Pp +The +.Va after_idle +function is called when data transfer resumes after an idle period. +It should be implemented to adjust state as required. +.Pp +The +.Va ctl_output +function is called when +.Xr getsockopt 2 +or +.Xr setsockopt 2 +is called on a +.Xr tcp 4 +socket with the +.Va struct sockopt +pointer forwarded unmodified from the TCP control, and a +.Va void * +pointer to algorithm specific argument. +.Pp +The +.Fn DECLARE_CC_MODULE +macro provides a convenient wrapper around the +.Xr DECLARE_MODULE 9 +macro, and is used to register a +.Nm +module with the +.Nm +framework. +The +.Fa ccname +argument specifies the module's name. +The +.Fa ccalgo +argument points to the module's +.Vt struct cc_algo . +.Pp +.Nm +modules must instantiate a +.Vt struct cc_algo , +but are only required to set the name field, and optionally any of the function +pointers. +The stack will skip calling any function pointer which is NULL, so there is no +requirement to implement any of the function pointers. +Using the C99 designated initialiser feature to set fields is encouraged. +.Pp +Each function pointer which deals with congestion control state is passed a +pointer to a +.Vt struct cc_var , +which has the following members: +.Bd -literal -offset indent +struct cc_var { + void *cc_data; + int bytes_this_ack; + tcp_seq curack; + uint32_t flags; + int type; + union ccv_container { + struct tcpcb *tcp; + struct sctp_nets *sctp; + } ccvc; +}; +.Ed +.Pp +.Vt struct cc_var +groups congestion control related variables into a single, embeddable structure +and adds a layer of indirection to accessing transport protocol control blocks. +The eventual goal is to allow a single set of +.Nm +modules to be shared between all congestion aware transport protocols, though +currently only +.Xr tcp 4 +is supported. +.Pp +To aid the eventual transition towards this goal, direct use of variables from +the transport protocol's data structures is strongly discouraged. +However, it is inevitable at the current time to require access to some of these +variables, and so the +.Fn CCV +macro exists as a convenience accessor. +The +.Fa ccv +argument points to the +.Vt struct cc_var +passed into the function by the +.Nm +framework. +The +.Fa what +argument specifies the name of the variable to access. +.Pp +Apart from the +.Va type +and +.Va ccv_container +fields, the remaining fields in +.Vt struct cc_var +are for use by +.Nm +modules. +.Pp +The +.Va cc_data +field is available for algorithms requiring additional per-connection state to +attach a dynamic memory pointer to. +The memory should be allocated and attached in the module's +.Va cb_init +hook function. +.Pp +The +.Va bytes_this_ack +field specifies the number of new bytes acknowledged by the most recently +received ACK packet. +It is only valid in the +.Va ack_received +hook function. +.Pp +The +.Va curack +field specifies the sequence number of the most recently received ACK packet. +It is only valid in the +.Va ack_received , +.Va cong_signal +and +.Va post_recovery +hook functions. +.Pp +The +.Va flags +field is used to pass useful information from the stack to a +.Nm +module. +The CCF_ABC_SENTAWND flag is relevant in +.Va ack_received +and is set when appropriate byte counting (RFC3465) has counted a window's worth +of bytes has been sent. +It is the module's responsibility to clear the flag after it has processed the +signal. +The CCF_CWND_LIMITED flag is relevant in +.Va ack_received +and is set when the connection's ability to send data is currently constrained +by the value of the congestion window. +Algorithms should use the absence of this flag being set to avoid accumulating +a large difference between the congestion window and send window. +.Sh SEE ALSO +.Xr cc_cdg 4 , +.Xr cc_chd 4 , +.Xr cc_cubic 4 , +.Xr cc_hd 4 , +.Xr cc_htcp 4 , +.Xr cc_newreno 4 , +.Xr cc_vegas 4 , +.Xr mod_cc 4 , +.Xr tcp 4 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh FUTURE WORK +Integrate with +.Xr sctp 4 . +.Sh HISTORY +The modular Congestion Control (CC) framework first appeared in +.Fx 9.0 . +.Pp +The framework was first released in 2007 by James Healy and Lawrence Stewart +whilst working on the NewTCP research project at Swinburne University of +Technology's Centre for Advanced Internet Architectures, Melbourne, Australia, +which was made possible in part by a grant from the Cisco University Research +Program Fund at Community Foundation Silicon Valley. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org , +.An James Healy Aq Mt jimmy@deefa.com +and +.An David Hayes Aq Mt david.hayes@ieee.org . +.Pp +This manual page was written by +.An David Hayes Aq Mt david.hayes@ieee.org +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . Property changes on: user/imp/camdoc/mod_cc.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/bus_adjust_resource.9 =================================================================== --- user/imp/camdoc/bus_adjust_resource.9 (nonexistent) +++ user/imp/camdoc/bus_adjust_resource.9 (revision 296049) @@ -0,0 +1,102 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2011 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 29, 2011 +.Dt BUS_ADJUST_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_adjust_resource +.Nd adjust resource allocated from a parent bus +.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_adjust_resource +.Fa "device_t dev" "int type" "struct resource *r" "rman_res_t start" "rman_res_t end" +.Sh DESCRIPTION +This function is used to ask the parent bus to adjust the resource range +assigned to an allocated resource. +The resource +.Fa r +should have been allocated by a previous call to +.Xr bus_alloc_resource 9 . +The new resource range must overlap the existing range of +.Fa r . +The +.Fa type +argument should match the +.Fa type +argument passed to +.Xr bus_alloc_resource 9 +when the resource was initially allocated. +.Pp +Note that none of the constraints of the original allocation request such +as alignment or boundary restrictions are checked by +.Fn bus_adjust_resource . +It is the caller's responsibility to enforce any such requirements. +.Sh RETURN VALUES +The +.Fn bus_adjust_resource +method returns zero on success or an error code on failure. +.Sh EXAMPLES +Grow an existing memory resource by 4096 bytes. +.Bd -literal + struct resource *res; + int error; + + error = bus_adjust_resource(dev, SYS_RES_MEMORY, res, + rman_get_start(res), rman_get_end(res) + 0x1000); +.Ed +.Sh ERRORS +.Fn bus_adjust_resource +will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa dev +device does not have a parent device. +.It Bq Er EINVAL +The +.Fa r +resource is a shared resource. +.It Bq Er EINVAL +The new address range does not overlap with the existing address range of +.Fa r . +.It Bq Er EBUSY +The new address range conflicts with another allocated resource. +.El +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr bus_release_resource 9 , +.Xr device 9 , +.Xr driver 9 Property changes on: user/imp/camdoc/bus_adjust_resource.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/bus_alloc_resource.9 =================================================================== --- user/imp/camdoc/bus_alloc_resource.9 (nonexistent) +++ user/imp/camdoc/bus_alloc_resource.9 (revision 296049) @@ -0,0 +1,186 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 18, 2000 +.Dt BUS_ALLOC_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_alloc_resource , +.Nm bus_alloc_resource_any +.Nd allocate resources from a parent bus +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Pp +.In machine/bus.h +.In sys/rman.h +.In machine/resource.h +.Ft struct resource * +.Fo bus_alloc_resource +.Fa "device_t dev" "int type" "int *rid" "rman_res_t start" "rman_res_t end" +.Fa "rman_res_t count" "u_int flags" +.Fc +.Ft struct resource * +.Fn bus_alloc_resource_any "device_t dev" "int type" "int *rid" "u_int flags" +.Sh DESCRIPTION +This is an easy interface to the resource-management functions. +It hides the indirection through the parent's method table. +This function generally should be called in attach, but (except in some +rare cases) never earlier. +.Pp +The +.Fn bus_alloc_resource_any +function is a convenience wrapper for +.Fn bus_alloc_resource . +It sets the values for +.Fa start , +.Fa end , +and +.Fa count +to the default resource (see description of +.Fa start +below). +.Pp +The arguments are as follows: +.Bl -item +.It +.Fa dev +is the device that requests ownership of the resource. +Before allocation, the resource is owned by the parent bus. +.It +.Fa type +is the type of resource you want to allocate. +It is one of: +.Bl -tag -width SYS_RES_MEMORY +.It Dv SYS_RES_IRQ +for IRQs +.It Dv SYS_RES_DRQ +for ISA DMA lines +.It Dv SYS_RES_IOPORT +for I/O ports +.It Dv SYS_RES_MEMORY +for I/O memory +.El +.It +.Fa rid +points to a bus specific handle that identifies the resource being allocated. +For ISA this is an index into an array of resources that have been setup +for this device by either the PnP mechanism, or via the hints mechanism. +For PCCARD, this is an index into the array of resources described by the PC Card's +CIS entry. +For PCI, the offset into pci config space which has the BAR to use to access +the resource. +The bus methods are free to change the RIDs that they are given as a parameter. +You must not depend on the value you gave it earlier. +.It +.Fa start +and +.Fa end +are the start/end addresses of the resource. +If you specify values of 0ul for +.Fa start +and ~0ul for +.Fa end +and 1 for +.Fa count , +the default values for the bus are calculated. +.It +.Fa count +is the size of the resource. +For example, the size of an I/O port is usually 1 byte (but some devices +override this). +If you specified the default values for +.Fa start +and +.Fa end , +then the default value of the bus is used if +.Fa count +is smaller than the default value and +.Fa count +is used, if it is bigger than the default value. +.It +.Fa flags +sets the flags for the resource. +You can set one or more of these flags: +.Bl -tag -width RF_SHAREABLE +.It Dv RF_ALLOCATED +resource has been reserved. +The resource still needs to be activated with +.Xr bus_activate_resource 9 . +.It Dv RF_ACTIVE +activate resource atomically. +.It Dv RF_SHAREABLE +resource permits contemporaneous sharing. +It should always be set unless you know that the resource cannot be shared. +It is the bus driver's task to filter out the flag if the bus does not +support sharing. +For example, +.Xr pccard 4 +cannot share IRQs while +.Xr cardbus 4 +can. +.It Dv RF_TIMESHARE +resource permits time-division sharing. +.El +.El +.Sh RETURN VALUES +A pointer to +.Va struct resource +is returned on success, a null pointer otherwise. +.Sh EXAMPLES +This is some example code that allocates a 32 byte I/O port range and an IRQ. +The values of +.Va portid +and +.Va irqid +should be saved in the softc of the device after these calls. +.Bd -literal + struct resource *portres, *irqres; + int portid, irqid; + + portid = 0; + irqid = 0; + portres = bus_alloc_resource(dev, SYS_RES_IOPORT, &portid, + 0ul, ~0ul, 32, RF_ACTIVE); + irqres = bus_alloc_resource_any(dev, SYS_RES_IRQ, &irqid, + RF_ACTIVE | RF_SHAREABLE); +.Ed +.Sh SEE ALSO +.Xr bus_activate_resource 9 , +.Xr bus_adjust_resource 9 , +.Xr bus_release_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@big.endian.de +with parts by +.An Warner Losh Aq Mt imp@FreeBSD.org . Property changes on: user/imp/camdoc/bus_alloc_resource.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_get_resource.9 =================================================================== --- user/imp/camdoc/bus_get_resource.9 (nonexistent) +++ user/imp/camdoc/bus_get_resource.9 (revision 296049) @@ -0,0 +1,94 @@ +.\" +.\" Copyright (c) 2008 +.\" The DragonFly Project. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in +.\" the documentation and/or other materials provided with the +.\" distribution. +.\" 3. Neither the name of The DragonFly Project nor the names of its +.\" contributors may be used to endorse or promote products derived +.\" from this software without specific, prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS 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. +.\" +.\" $DragonFly: src/share/man/man9/bus_get_resource.9,v 1.1 2008/11/09 09:48:41 swildner Exp $ +.\" $FreeBSD$ +.\" +.Dd September 26, 2015 +.Dt BUS_GET_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_get_resource +.Nd "read a resource range/value with a given resource ID" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/rman.h +.Ft int +.Fo bus_get_resource +.Fa "device_t dev" "int type" "int rid" "rman_res_t *startp" "rman_res_t *countp" +.Fc +.Sh DESCRIPTION +The +.Fn bus_get_resource +function reads the range or value of the resource +.Fa type , rid +pair and stores it in the +.Fa startp +and +.Fa countp +arguments. +.Pp +The arguments are as follows: +.Bl -tag -width ".Fa startp" +.It Fa dev +The device to read the resource from. +.It Fa type +The type of resource you want to read. +It is one of: +.Pp +.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact +.It Dv SYS_RES_IRQ +for IRQs +.It Dv SYS_RES_DRQ +for ISA DMA lines +.It Dv SYS_RES_MEMORY +for I/O memory +.It Dv SYS_RES_IOPORT +for I/O ports +.El +.It Fa rid +A bus-specific handle that identifies the resource being read. +.It Fa startp +A pointer to the start address of this resource. +.It Fa countp +A pointer to the length of the resource. +For example, the size of the memory in bytes. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr bus_set_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Sascha Wildner . Property changes on: user/imp/camdoc/bus_get_resource.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/bus_set_resource.9 =================================================================== --- user/imp/camdoc/bus_set_resource.9 (nonexistent) +++ user/imp/camdoc/bus_set_resource.9 (revision 296049) @@ -0,0 +1,96 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 29, 2003 +.Dt BUS_SET_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_set_resource +.Nd "associate a definite resource with a given resource ID" +.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_set_resource +.Fa "device_t dev" "int type" "int rid" "rman_res_t start" "rman_res_t count" +.Fc +.Sh DESCRIPTION +The +.Fn bus_set_resource +function +sets the start address of the resource +.Fa type , rid +pair to be +.Fa count +long. +Typically, client drivers do not use this interface. +Bus drivers, however, often use it to set up the resources a client +driver uses. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device to set the resource on. +.It Fa type +The type of resource you want to allocate. +It is one of: +.Pp +.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact +.It Dv SYS_RES_IRQ +for IRQs +.It Dv SYS_RES_DRQ +for ISA DMA lines +.It Dv SYS_RES_IOPORT +for I/O ports +.It Dv SYS_RES_MEMORY +for I/O memory +.El +.It Fa rid +A bus-specific handle that identifies the resource being allocated. +.It Fa start +The start address of this resource. +.It Fa count +The length of the resource. +For example, the size of the memory in bytes. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr bus_get_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh Aq Mt imp@FreeBSD.org . Property changes on: user/imp/camdoc/bus_set_resource.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/rman.9 =================================================================== --- user/imp/camdoc/rman.9 (nonexistent) +++ user/imp/camdoc/rman.9 (revision 296049) @@ -0,0 +1,467 @@ +.\" +.\" 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 July 15, 2014 +.Dt RMAN 9 +.Os +.Sh NAME +.Nm rman , +.Nm rman_activate_resource , +.Nm rman_adjust_resource , +.Nm rman_await_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_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_await_resource "struct resource *r" "int pri2" "int timo" +.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_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 */ +.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_await_resource +function performs an asynchronous wait for a resource +.Fa r +to become inactive, that is, for the +.Dv RF_ACTIVE +flag to be cleared. +It is used to enable cooperative sharing of a resource +which can only be safely used by one thread at a time. +The arguments +.Fa pri +and +.Fa timo +are passed to the +.Fn rman_await_resource +function. +.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_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_release_resource 9 , +.Xr bus_set_resource 9 , +.Xr mutex 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/rman.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/hashinit.9 =================================================================== --- user/imp/camdoc/hashinit.9 (nonexistent) +++ user/imp/camdoc/hashinit.9 (revision 296049) @@ -0,0 +1,178 @@ +.\" +.\" Copyright (c) 2004 Joseph Koshy +.\" 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 January 23, 2016 +.Dt HASHINIT 9 +.Os +.Sh NAME +.Nm hashinit , hashinit_flags , hashdestroy , phashinit +.Nd manage kernel hash tables +.Sh SYNOPSIS +.In sys/malloc.h +.In sys/systm.h +.In sys/queue.h +.Ft "void *" +.Fn hashinit "int nelements" "struct malloc_type *type" "u_long *hashmask" +.Ft void +.Fo hashinit_flags +.Fa "int nelements" "struct malloc_type *type" "u_long *hashmask" "int flags" +.Fc +.Ft void +.Fn hashdestroy "void *hashtbl" "struct malloc_type *type" "u_long hashmask" +.Ft "void *" +.Fn phashinit "int nelements" "struct malloc_type *type" "u_long *nentries" +.Sh DESCRIPTION +The +.Fn hashinit , +.Fn hashinit_flags +and +.Fn phashinit +functions allocate space for hash tables of size given by the argument +.Fa nelements . +.Pp +The +.Fn hashinit +function allocates hash tables that are sized to largest power of two +less than or equal to argument +.Fa nelements . +The +.Fn phashinit +function allocates hash tables that are sized to the largest prime +number less than or equal to argument +.Fa nelements . +The +.Fn hashinit_flags +function operates like +.Fn hashinit +but also accepts an additional argument +.Fa flags +which control various options during allocation. +Allocated hash tables are contiguous arrays of +.Xr LIST_HEAD 3 +entries, allocated using +.Xr malloc 9 , +and initialized using +.Xr LIST_INIT 3 . +The malloc arena to be used for allocation is pointed to by argument +.Fa type . +.Pp +The +.Fn hashdestroy +function frees the space occupied by the hash table pointed to by argument +.Fa hashtbl . +Argument +.Fa type +determines the malloc arena to use when freeing space. +The argument +.Fa hashmask +should be the bit mask returned by the call to +.Fn hashinit +that allocated the hash table. +The argument +.Fa flags +must be used with one of the following values. +.Pp +.Bl -tag -width ".Dv HASH_NOWAIT" -offset indent -compact +.It Dv HASH_NOWAIT +Any malloc performed by the +.Fn hashinit_flags +function will not be allowed to wait, and therefore may fail. +.It Dv HASH_WAITOK +Any malloc performed by +.Fn hashinit_flags +function is allowed to wait for memory. +This is also the behavior of +.Fn hashinit . +.El +.Sh IMPLEMENTATION NOTES +The largest prime hash value chosen by +.Fn phashinit +is 32749. +.Sh RETURN VALUES +The +.Fn hashinit +function returns a pointer to an allocated hash table and sets the +location pointed to by +.Fa hashmask +to the bit mask to be used for computing the correct slot in the +hash table. +.Pp +The +.Fn phashinit +function returns a pointer to an allocated hash table and sets the +location pointed to by +.Fa nentries +to the number of rows in the hash table. +.Sh EXAMPLES +A typical example is shown below: +.Bd -literal -offset indent +\&... +static LIST_HEAD(foo, foo) *footable; +static u_long foomask; +\&... +footable = hashinit(32, M_FOO, &foomask); +.Ed +.Pp +Here we allocate a hash table with 32 entries from the malloc arena +pointed to by +.Dv M_FOO . +The mask for the allocated hash table is returned in +.Va foomask . +A subsequent call to +.Fn hashdestroy +uses the value in +.Va foomask : +.Bd -literal -offset indent +\&... +hashdestroy(footable, M_FOO, foomask); +.Ed +.Sh DIAGNOSTICS +The +.Fn hashinit +and +.Fn phashinit +functions will panic if argument +.Fa nelements +is less than or equal to zero. +.Pp +The +.Fn hashdestroy +function will panic if the hash table +pointed to by +.Fa hashtbl +is not empty. +.Sh SEE ALSO +.Xr LIST_HEAD 3 , +.Xr malloc 9 +.Sh BUGS +There is no +.Fn phashdestroy +function, and using +.Fn hashdestroy +to free a hash table allocated by +.Fn phashinit +usually has grave consequences. Property changes on: user/imp/camdoc/hashinit.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vref.9 =================================================================== --- user/imp/camdoc/vref.9 (nonexistent) +++ user/imp/camdoc/vref.9 (revision 296049) @@ -0,0 +1,77 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 18, 2016 +.Dt VREF 9 +.Os +.Sh NAME +.Nm vref , vrefl +.Nd increment the use count for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vref "struct vnode *vp" +.Ft void +.Fn vrefl "struct vnode *vp" +.Sh DESCRIPTION +Increment the +.Va v_usecount +field of a vnode. +.Bl -tag -width 2n +.It Fa vp +the vnode to increment +.El +.Pp +Each vnode maintains a reference count of how many parts of the system +are using the vnode. +This allows the system to detect when a vnode is +no longer being used and can be safely recycled for a different file. +.Pp +Any code in the system which is using a vnode (e.g.\& during the +operation of some algorithm or to store in a data structure) should +call +.Fn vref +or +.Fn vrefl . +.Pp +.Fn vref +locks the vnode interlock while +.Fn vrefl +expects the interlock to already be held. +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vrefcnt 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/vref.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/cd.9 =================================================================== --- user/imp/camdoc/cd.9 (nonexistent) +++ user/imp/camdoc/cd.9 (revision 296049) @@ -0,0 +1,123 @@ +.\" Copyright (c) 1997 +.\" John-Mark Gurney. 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 John-Mark Gurney 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 25, 2014 +.Dt CD 9 +.Os +.Sh NAME +.Nm cd +.Nd CDROM driver for the CAM SCSI subsystem +.Sh DESCRIPTION +The +.Nm +device driver provides a read-only interface for CDROM drives +.Tn ( SCSI +type 5) +and WORM drives +.Tn ( SCSI +type 4) +that support CDROM type commands. +Some drives do not behave as the driver expects. +See the +.Sx QUIRKS +section for information on possible flags. +.Sh QUIRKS +Each +.Tn CD-ROM +device can have different interpretations of the +.Tn SCSI +spec. +This can lead to drives requiring special handling in the driver. +The following is a list of quirks that the driver recognize. +.Bl -tag -width CD_Q_BCD_TRACKS +.It Dv CD_Q_NO_TOUCH +This flag tells the driver not to probe the drive at attach time to see if +there is a disk in the drive and find out what size it is. +This flag is currently unimplemented in the CAM +.Nm +driver. +.It Dv CD_Q_BCD_TRACKS +This flag is for broken drives that return the track numbers in packed BCD +instead of straight decimal. +If the drive seems to skip tracks +(tracks 10-15 are skipped) +then you have a drive that is in need of this flag. +.It Dv CD_Q_NO_CHANGER +This flag tells the driver that the device in question is not a changer. +This is only necessary for a CDROM device with multiple luns that are not a +part of a changer. +.It Dv CD_Q_CHANGER +This flag tells the driver that the given device is a multi-lun changer. +In general, the driver will figure this out automatically when it sees a +LUN greater than 0. +Setting this flag only has the effect of telling the +driver to run the initial read capacity command for LUN 0 of the changer +through the changer scheduling code. +.It Dv CD_Q_10_BYTE_ONLY +This flag tells the driver that the given device only accepts 10 byte MODE +SENSE/MODE SELECT commands. +In general these types of quirks should not be +added to the +.Xr cd 4 +driver. +The reason is that the driver does several things to attempt to +determine whether the drive in question needs 10 byte commands. +First, it +issues a CAM Path Inquiry command to determine whether the protocol that +the drive speaks typically only allows 10 byte commands. +(ATAPI and USB +are two prominent examples of protocols where you generally only want to +send 10 byte commands.) +Then, if it gets an ILLEGAL REQUEST error back +from a 6 byte MODE SENSE or MODE SELECT command, it attempts to send the 10 +byte version of the command instead. +The only reason you would need a +quirk is if your drive uses a protocol (e.g., +.Tn SCSI ) +that typically does not have a problem with 6 byte commands. +.El +.Sh FILES +.Bl -tag -width /sys/cam/scsi/scsi_cd.c -compact +.It Pa /sys/cam/scsi/scsi_cd.c +is the driver source file. +.El +.Sh SEE ALSO +.Xr cd 4 , +.Xr scsi 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +This +manual page was written by +.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . +It was updated for CAM and +.Fx 3.0 +by +.An Kenneth Merry Aq Mt ken@FreeBSD.org . Property changes on: user/imp/camdoc/cd.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/zone.9 =================================================================== --- user/imp/camdoc/zone.9 (nonexistent) +++ user/imp/camdoc/zone.9 (revision 296049) @@ -0,0 +1,386 @@ +.\"- +.\" 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 beeing 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, +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 . Property changes on: user/imp/camdoc/zone.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DEVICE_PROBE.9 =================================================================== --- user/imp/camdoc/DEVICE_PROBE.9 (nonexistent) +++ user/imp/camdoc/DEVICE_PROBE.9 (revision 296049) @@ -0,0 +1,140 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 8, 2012 +.Dt DEVICE_PROBE 9 +.Os +.Sh NAME +.Nm DEVICE_PROBE +.Nd probe for device existence +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_PROBE "device_t dev" +.Sh DESCRIPTION +The +.Fn DEVICE_PROBE +method should probe to see if the device is present. +It should return 0 if the device exists, +.Er ENXIO +if it cannot be found. +If some other error happens during the probe (such as a memory +allocation failure), an appropriate error code should be returned. +For +cases where more than one driver matches a device, a priority value can +be returned. +In this case, success codes are values less than or equal +to zero with the highest value representing the best match. +Failure +codes are represented by positive values and the regular +.Ux +error +codes should be used for the purpose. +.Pp +If a driver returns a success code which is less than zero, it must +not assume that it will be the same driver which is attached to the +device. +In particular, it must not assume that any values stored in +the softc structure will be available for its attach method and any +resources allocated during probe must be released and re-allocated +if the attach method is called. +In addition it is an absolute requirement that the probe routine have +no side effects whatsoever. +The probe routine may be called more than once before the attach +routine is called. +.Pp +If a success code of zero is +returned, the driver can assume that it will be the one attached, but +must not hold any resources when the probe routine returns. +A driver may assume that the softc is preserved when it returns +a success code of zero. +.Sh RETURN VALUES +A value equal to or less than zero indicates success, greater than +zero indicates an error (errno). +For values equal to or less than +zero: zero indicates highest priority, no further probing is done; +for a value less than zero, the lower the value the lower the +priority, e.g.\& -100 indicates a lower priority than -50. +.Pp +The following values are used by convention to indicate different +strengths of matching in a probe routine. +Except as noted, these are just suggested values, and there's nothing +magical about them. +.Bl -tag -width BUS_PROBE_NOWILDCARD +.It BUS_PROBE_SPECIFIC +The device that cannot be reprobed, and that no +possible other driver may exist (typically legacy drivers who don't follow +all the rules, or special needs drivers). +.It BUS_PROBE_VENDOR +The device is supported by a vendor driver. +This is for source or binary drivers that are not yet integrated into the +.Fx +tree. +Its use in the base OS is prohibited. +.It BUS_PROBE_DEFAULT +The device is a normal device matching some plug and play ID. +This is +the normal return value for drivers to use. +It is intended that nearly all of the drivers in the tree should return +this value. +.It BUS_PROBE_LOW_PRIORITY +The driver is a legacy driver, or an otherwise less desirable driver +for a given plug and play ID. +The driver has special requirements like when there are two drivers +that support overlapping series of hardware devices. +In this case the one that supports the older part of the line would +return this value, while the one that supports the newer ones would +return BUS_PROBE_DEFAULT. +.It BUS_PROBE_GENERIC +The driver matches the type of device generally. +This allows drivers to match all serial ports generally, with specialized +drivers matching particular types of serial ports that need special +treatment for some reason. +.It BUS_PROBE_HOOVER +The driver matches all unclaimed devices on a bus. +The +.Xr ugen 4 +device is one example. +.It BUS_PROBE_NOWILDCARD +The driver expects its parent to tell it which children to manage +and no probing is really done. +The device only matches if its parent bus specifically said to use +this driver. +.El +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_SHUTDOWN 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/DEVICE_PROBE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/kern_testfrwk.9 =================================================================== --- user/imp/camdoc/kern_testfrwk.9 (nonexistent) +++ user/imp/camdoc/kern_testfrwk.9 (revision 296049) @@ -0,0 +1,194 @@ +.\" +.\" Copyright (c) 2015 Netflix 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 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 November 12, 2015 +.Dt KERN_TESTFRWK 9 +.Os +.Sh NAME +.Nm kern_testfrwk +.Nd A kernel testing framework +.Sh SYNOPSIS +kld_load kern_testfrwk +.Sh DESCRIPTION +.\" This whole section is not written in manual page style and should be ripped +.\" out and replaced. -CEM +So what is this sys/tests directory in the kernel all about? +.Pp +Have you ever wanted to test a part of the FreeBSD kernel in some way and you +had no real way from user-land to make what you want to occur happen? +Say an error path or situation where locking occurs in a particular manner that +happens only once in a blue moon? +.Pp +If so, then the kernel test framework is just what you are looking for. +It is designed to help you create the situation you want. +.Pp +There are two components to the system: the test framework and your test. +This document will describe both components and use the test submitted with the +initial commit of this code to discuss the test +.Xr ( callout_test 4 ) . +All of the tests become kernel loadable modules. +The test you write should have a dependency on the test framework. +That way it will be loaded automatically with your test. +For example, you can see how to do this in the bottom of callout_test.c in +.Pa sys/tests/callout_test/callout_test.c . +.Pp +The framework itself is in +.Pa sys/tests/framework/kern_testfrwk.c . +Its job is to manage the tests that are loaded. +(More than one can be loaded.) +The idea is pretty simple; you load the test framework and then load your test. +.Pp +When your test loads, you register your tests with the kernel test framework. +You do that through a call to +.Fn kern_testframework_register . +Usually this is done at the module load event as shown below: +.Bd -literal -offset indent + switch (type) { + case MOD_LOAD: + err = kern_testframework_register("callout_test", + run_callout_test); +.Ed +.Pp +Here the test is "callout_test" and it is registered to run the function +.Fn run_callout_test +passing it a +.Fa struct kern_test *ptr . +The +.Vt kern_test +structure is defined in +.Pa kern_testfrwk.h . +.Bd -literal -offset indent +struct kern_test { + char name[TEST_NAME_LEN]; + int num_threads; /* Fill in how many threads you want */ + int tot_threads_running; /* Private to framework */ + uint8_t test_options[TEST_OPTION_SPACE]; +}; +.Ed +.Pp +The user sends this structure down via a sysctl to start your test. +He or she places the same name you registered ("callout_test" +in our example) in the +.Va name +field. +The user can also set the number of threads to run with +.Va num_threads . +.Pp +The framework will start the requested number of kernel threads, all running +your test at the same time. +The user does not specify anything in +.Va tot_threads_running ; +it is private to the framework. +As the framework calls each of your tests, it will set the +.Va tot_threads_running +to the index of the thread that your call is made from. +For example, if the user sets +.Va num_threads +to 2, then the function +.Fn run_callout_test +will be called once with +.Va tot_threads_running +to 0, and a second time with +.Va tot_threads_running +set to 1. +.Pp +The +.Va test_options +field is a test-specific set of information that is an opaque blob. +It is passed in from user space and has a maximum size of 256 bytes. +You can pass arbitrary test input in the space. +In the case of callout_test we reshape that to: +.Bd -literal -offset indent +struct callout_test { + int number_of_callouts; + int test_number; +}; +.Ed +.Pp +So the first lines of +.Fn run_callout_test +does the following to get at the user specific data: +.\" This is a bad example and violates strict aliasing. It should be replaced. +.Bd -literal -offset indent + struct callout_test *u; + size_t sz; + int i; + struct callout_run *rn; + int index = test->tot_threads_running; + + u = (struct callout_test *)test->test_options; +.Ed +.Pp +That way it can access: +.Va u->test_number +(there are two types of tests provided with this test) +and +.Va u->number_of_callouts +(how many simultaneous callouts to run). +.Pp +Your test can do anything with these bytes. +So the callout_test in question wants to create a situation where multiple +callouts are all run, that is the +.Va number_of_callouts , +and it tries to cancel the callout with the new +.Fn callout_async_drain . +The threads do this by acquiring the lock in question, and then +starting each of the callouts. +It waits for the callouts to all go off (the executor spins waits). +This forces the situation that the callouts have expired and are all waiting on +the lock that the executor holds. +After the callouts are all blocked, the executor calls +.Fn callout_async_drain +on each callout and releases the lock. +.Pp +.\" callout_test(4) specific documentation should probably be moved to its own +.\" page. +After all the callouts are done, a total status is printed +showing the results via +.Xr printf 9 . +The human tester can run +.Xr dmesg 8 +to see the results. +In this case it is expected that if you are running test 0, all the callouts +expire on the same CPU so only one callout_drain function would have been +called. +the number of zero_returns should match the number of callout_drains that were +called, i.e., 1. +The one_returns should be the remainder of the callouts. +If the test number was 1, the callouts were spread across all CPUs. +The number of zero_returns will again match the number of drain calls made +which matches the number of CPUs that were put in use. +.Pp +More than one thread can be used with this test, though in the example case it +is probably not necessary. +.Pp +You should not need to change the framework. +Just add tests and register them after loading. +.Sh AUTHORS +The kernel test framework was written by +.An Randall Stewart Aq Mt rrs@FreeBSD.org +with help from +.An John Mark Gurney Aq Mt jmg@FreeBSD.org . Property changes on: user/imp/camdoc/kern_testfrwk.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/malloc.9 =================================================================== --- user/imp/camdoc/malloc.9 (nonexistent) +++ user/imp/camdoc/malloc.9 (revision 296049) @@ -0,0 +1,281 @@ +.\" +.\" 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. +.\" +.\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ +.\" $FreeBSD$ +.\" +.Dd November 19, 2015 +.Dt MALLOC 9 +.Os +.Sh NAME +.Nm malloc , +.Nm free , +.Nm realloc , +.Nm reallocf , +.Nm MALLOC_DEFINE , +.Nm MALLOC_DECLARE +.Nd kernel memory management routines +.Sh SYNOPSIS +.In sys/types.h +.In sys/malloc.h +.Ft void * +.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" +.Ft void +.Fn free "void *addr" "struct malloc_type *type" +.Ft void * +.Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" +.Ft void * +.Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" +.Fn MALLOC_DECLARE type +.In sys/param.h +.In sys/malloc.h +.In sys/kernel.h +.Fn MALLOC_DEFINE type shortdesc longdesc +.Sh DESCRIPTION +The +.Fn malloc +function allocates uninitialized memory in kernel address space for an +object whose size is specified by +.Fa size . +.Pp +The +.Fn free +function releases memory at address +.Fa addr +that was previously allocated by +.Fn malloc +for re-use. +The memory is not zeroed. +If +.Fa addr +is +.Dv NULL , +then +.Fn free +does nothing. +.Pp +The +.Fn realloc +function changes the size of the previously allocated memory referenced by +.Fa addr +to +.Fa size +bytes. +The contents of the memory are unchanged up to the lesser of the new and +old sizes. +Note that the returned value may differ from +.Fa addr . +If the requested memory cannot be allocated, +.Dv NULL +is returned and the memory referenced by +.Fa addr +is valid and unchanged. +If +.Fa addr +is +.Dv NULL , +the +.Fn realloc +function behaves identically to +.Fn malloc +for the specified size. +.Pp +The +.Fn reallocf +function is identical to +.Fn realloc +except that it +will free the passed pointer when the requested memory cannot be allocated. +.Pp +Unlike its standard C library counterpart +.Pq Xr malloc 3 , +the kernel version takes two more arguments. +The +.Fa flags +argument further qualifies +.Fn malloc Ns 's +operational characteristics as follows: +.Bl -tag -width indent +.It Dv M_ZERO +Causes the allocated memory to be set to all zeros. +.It Dv M_NODUMP +For allocations greater than page size, causes the allocated +memory to be excluded from kernel core dumps. +.It Dv M_NOWAIT +Causes +.Fn malloc , +.Fn realloc , +and +.Fn reallocf +to return +.Dv NULL +if the request cannot be immediately fulfilled due to resource shortage. +Note that +.Dv M_NOWAIT +is required when running in an interrupt context. +.It Dv M_WAITOK +Indicates that it is OK to wait for resources. +If the request cannot be immediately fulfilled, the current process is put +to sleep to wait for resources to be released by other processes. +The +.Fn malloc , +.Fn realloc , +and +.Fn reallocf +functions cannot return +.Dv NULL +if +.Dv M_WAITOK +is specified. +.It Dv M_USE_RESERVE +Indicates that the system can use its reserve of memory to satisfy the +request. +This option should only be used in combination with +.Dv M_NOWAIT +when an allocation failure cannot be tolerated by the caller without +catastrophic effects on the system. +.El +.Pp +Exactly one of either +.Dv M_WAITOK +or +.Dv M_NOWAIT +must be specified. +.Pp +The +.Fa type +argument is used to perform statistics on memory usage, and for +basic sanity checks. +It can be used to identify multiple allocations. +The statistics can be examined by +.Sq vmstat -m . +.Pp +A +.Fa type +is defined using +.Vt "struct malloc_type" +via the +.Fn MALLOC_DECLARE +and +.Fn MALLOC_DEFINE +macros. +.Bd -literal -offset indent +/* sys/something/foo_extern.h */ + +MALLOC_DECLARE(M_FOOBUF); + +/* sys/something/foo_main.c */ + +MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether"); + +/* sys/something/foo_subr.c */ + +\&... +buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT); + +.Ed +.Pp +In order to use +.Fn MALLOC_DEFINE , +one must include +.In sys/param.h +(instead of +.In sys/types.h ) +and +.In sys/kernel.h . +.Sh CONTEXT +.Fn malloc , +.Fn realloc +and +.Fn reallocf +may not be called from fast interrupts handlers. +When called from threaded interrupts, +.Fa flags +must contain +.Dv M_NOWAIT . +.Pp +.Fn malloc , +.Fn realloc +and +.Fn reallocf +may sleep when called with +.Dv M_WAITOK . +.Fn free +never sleeps. +However, +.Fn malloc , +.Fn realloc , +.Fn reallocf +and +.Fn free +may not be called in a critical section or while holding a spin lock. +.Pp +Any calls to +.Fn malloc +(even with +.Dv M_NOWAIT ) +or +.Fn free +when holding a +.Xr vnode 9 +interlock, will cause a LOR (Lock Order Reversal) due to the +intertwining of VM Objects and Vnodes. +.Sh IMPLEMENTATION NOTES +The memory allocator allocates memory in chunks that have size a power +of two for requests up to the size of a page of memory. +For larger requests, one or more pages is allocated. +While it should not be relied upon, this information may be useful for +optimizing the efficiency of memory use. +.Sh RETURN VALUES +The +.Fn malloc , +.Fn realloc , +and +.Fn reallocf +functions return a kernel virtual address that is suitably aligned for +storage of any type of object, or +.Dv NULL +if the request could not be satisfied (implying that +.Dv M_NOWAIT +was set). +.Sh DIAGNOSTICS +A kernel compiled with the +.Dv INVARIANTS +configuration option attempts to detect memory corruption caused by +such things as writing outside the allocated area and imbalanced calls to the +.Fn malloc +and +.Fn free +functions. +Failing consistency checks will cause a panic or a system console +message. +.Sh SEE ALSO +.Xr vmstat 8 , +.Xr contigmalloc 9 , +.Xr memguard 9 , +.Xr vnode 9 Property changes on: user/imp/camdoc/malloc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/timeout.9 =================================================================== --- user/imp/camdoc/timeout.9 (nonexistent) +++ user/imp/camdoc/timeout.9 (revision 296049) @@ -0,0 +1,846 @@ +.\" $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 successfuly 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 +.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 +.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. Property changes on: user/imp/camdoc/timeout.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/Makefile =================================================================== --- user/imp/camdoc/Makefile (nonexistent) +++ user/imp/camdoc/Makefile (revision 296049) @@ -0,0 +1,1920 @@ +# $FreeBSD$ + +.include + +MAN= accept_filter.9 \ + accf_data.9 \ + accf_dns.9 \ + accf_http.9 \ + acl.9 \ + alq.9 \ + altq.9 \ + atomic.9 \ + bios.9 \ + bitset.9 \ + boot.9 \ + bpf.9 \ + buf.9 \ + buf_ring.9 \ + BUF_ISLOCKED.9 \ + BUF_LOCK.9 \ + BUF_LOCKFREE.9 \ + BUF_LOCKINIT.9 \ + BUF_RECURSED.9 \ + BUF_TIMELOCK.9 \ + BUF_UNLOCK.9 \ + bus_activate_resource.9 \ + BUS_ADD_CHILD.9 \ + bus_adjust_resource.9 \ + bus_alloc_resource.9 \ + BUS_BIND_INTR.9 \ + bus_child_present.9 \ + BUS_CHILD_DELETED.9 \ + BUS_CHILD_DETACHED.9 \ + BUS_CONFIG_INTR.9 \ + BUS_DESCRIBE_INTR.9 \ + bus_dma.9 \ + bus_generic_attach.9 \ + bus_generic_detach.9 \ + bus_generic_new_pass.9 \ + bus_generic_print_child.9 \ + bus_generic_read_ivar.9 \ + bus_generic_shutdown.9 \ + bus_get_resource.9 \ + BUS_NEW_PASS.9 \ + BUS_PRINT_CHILD.9 \ + BUS_READ_IVAR.9 \ + bus_release_resource.9 \ + bus_set_pass.9 \ + bus_set_resource.9 \ + BUS_SETUP_INTR.9 \ + bus_space.9 \ + byteorder.9 \ + casuword.9 \ + cd.9 \ + condvar.9 \ + config_intrhook.9 \ + contigmalloc.9 \ + copy.9 \ + counter.9 \ + cpuset.9 \ + cr_cansee.9 \ + critical_enter.9 \ + cr_seeothergids.9 \ + cr_seeotheruids.9 \ + crypto.9 \ + CTASSERT.9 \ + DB_COMMAND.9 \ + DECLARE_GEOM_CLASS.9 \ + DECLARE_MODULE.9 \ + DELAY.9 \ + devclass.9 \ + devclass_find.9 \ + devclass_get_device.9 \ + devclass_get_devices.9 \ + devclass_get_drivers.9 \ + devclass_get_maxunit.9 \ + devclass_get_name.9 \ + devclass_get_softc.9 \ + dev_clone.9 \ + devfs_set_cdevpriv.9 \ + device.9 \ + device_add_child.9 \ + DEVICE_ATTACH.9 \ + device_delete_child.9 \ + DEVICE_DETACH.9 \ + device_enable.9 \ + device_find_child.9 \ + device_get_children.9 \ + device_get_devclass.9 \ + device_get_driver.9 \ + device_get_ivars.9 \ + device_get_name.9 \ + device_get_parent.9 \ + device_get_softc.9 \ + device_get_state.9 \ + device_get_sysctl.9 \ + device_get_unit.9 \ + DEVICE_IDENTIFY.9 \ + device_printf.9 \ + DEVICE_PROBE.9 \ + device_probe_and_attach.9 \ + device_quiet.9 \ + device_set_desc.9 \ + device_set_driver.9 \ + device_set_flags.9 \ + DEVICE_SHUTDOWN.9 \ + DEV_MODULE.9 \ + devstat.9 \ + devtoname.9 \ + disk.9 \ + domain.9 \ + drbr.9 \ + driver.9 \ + DRIVER_MODULE.9 \ + EVENTHANDLER.9 \ + eventtimers.9 \ + extattr.9 \ + fail.9 \ + fetch.9 \ + firmware.9 \ + fpu_kern.9 \ + g_access.9 \ + g_attach.9 \ + g_bio.9 \ + g_consumer.9 \ + g_data.9 \ + get_cyclecount.9 \ + getenv.9 \ + getnewvnode.9 \ + g_event.9 \ + g_geom.9 \ + g_provider.9 \ + g_provider_by_name.9 \ + groupmember.9 \ + g_wither_geom.9 \ + hash.9 \ + hashinit.9 \ + hexdump.9 \ + hhook.9 \ + ieee80211.9 \ + ieee80211_amrr.9 \ + ieee80211_beacon.9 \ + ieee80211_bmiss.9 \ + ieee80211_crypto.9 \ + ieee80211_ddb.9 \ + ieee80211_input.9 \ + ieee80211_node.9 \ + ieee80211_output.9 \ + ieee80211_proto.9 \ + ieee80211_radiotap.9 \ + ieee80211_regdomain.9 \ + ieee80211_scan.9 \ + ieee80211_vap.9 \ + ifnet.9 \ + inittodr.9 \ + insmntque.9 \ + intro.9 \ + ithread.9 \ + KASSERT.9 \ + kern_testfrwk.9 \ + kernacc.9 \ + kernel_mount.9 \ + khelp.9 \ + kobj.9 \ + kproc.9 \ + kqueue.9 \ + kthread.9 \ + ktr.9 \ + lock.9 \ + locking.9 \ + LOCK_PROFILING.9 \ + mac.9 \ + make_dev.9 \ + malloc.9 \ + mbchain.9 \ + mbpool.9 \ + mbuf.9 \ + mbuf_tags.9 \ + MD5.9 \ + mdchain.9 \ + memcchr.9 \ + memguard.9 \ + microseq.9 \ + microtime.9 \ + microuptime.9 \ + mi_switch.9 \ + mod_cc.9 \ + module.9 \ + MODULE_DEPEND.9 \ + MODULE_VERSION.9 \ + mtx_pool.9 \ + mutex.9 \ + namei.9 \ + netisr.9 \ + nv.9 \ + osd.9 \ + owll.9 \ + own.9 \ + panic.9 \ + pbuf.9 \ + PCBGROUP.9 \ + p_candebug.9 \ + p_cansee.9 \ + pci.9 \ + PCI_IOV_ADD_VF.9 \ + PCI_IOV_INIT.9 \ + pci_iov_schema.9 \ + PCI_IOV_UNINIT.9 \ + pfil.9 \ + pfind.9 \ + pget.9 \ + pgfind.9 \ + PHOLD.9 \ + physio.9 \ + pmap.9 \ + pmap_activate.9 \ + pmap_clear_modify.9 \ + pmap_copy.9 \ + pmap_enter.9 \ + pmap_extract.9 \ + pmap_growkernel.9 \ + pmap_init.9 \ + pmap_is_modified.9 \ + pmap_is_prefaultable.9 \ + pmap_map.9 \ + pmap_mincore.9 \ + pmap_object_init_pt.9 \ + pmap_page_exists_quick.9 \ + pmap_page_init.9 \ + pmap_pinit.9 \ + pmap_protect.9 \ + pmap_qenter.9 \ + pmap_quick_enter_page.9 \ + pmap_release.9 \ + pmap_remove.9 \ + pmap_resident_count.9 \ + pmap_unwire.9 \ + pmap_zero_page.9 \ + printf.9 \ + prison_check.9 \ + priv.9 \ + proc_rwmem.9 \ + pseudofs.9 \ + psignal.9 \ + random.9 \ + random_harvest.9 \ + redzone.9 \ + refcount.9 \ + resettodr.9 \ + resource_int_value.9 \ + rijndael.9 \ + rman.9 \ + rmlock.9 \ + rtalloc.9 \ + rtentry.9 \ + runqueue.9 \ + rwlock.9 \ + sbuf.9 \ + scheduler.9 \ + SDT.9 \ + securelevel_gt.9 \ + selrecord.9 \ + sema.9 \ + sf_buf.9 \ + sglist.9 \ + shm_map.9 \ + signal.9 \ + sleep.9 \ + sleepqueue.9 \ + socket.9 \ + stack.9 \ + store.9 \ + style.9 \ + swi.9 \ + sx.9 \ + SYSCALL_MODULE.9 \ + sysctl.9 \ + sysctl_add_oid.9 \ + sysctl_ctx_init.9 \ + SYSINIT.9 \ + taskqueue.9 \ + thread_exit.9 \ + time.9 \ + timeout.9 \ + tvtohz.9 \ + ucred.9 \ + uidinfo.9 \ + uio.9 \ + unr.9 \ + utopia.9 \ + vaccess.9 \ + vaccess_acl_nfs4.9 \ + vaccess_acl_posix1e.9 \ + vcount.9 \ + vflush.9 \ + VFS.9 \ + vfs_busy.9 \ + VFS_CHECKEXP.9 \ + vfsconf.9 \ + VFS_FHTOVP.9 \ + vfs_getnewfsid.9 \ + vfs_getopt.9 \ + vfs_getvfs.9 \ + VFS_MOUNT.9 \ + vfs_mountedfrom.9 \ + VFS_QUOTACTL.9 \ + VFS_ROOT.9 \ + vfs_rootmountalloc.9 \ + VFS_SET.9 \ + VFS_STATFS.9 \ + vfs_suser.9 \ + VFS_SYNC.9 \ + vfs_timestamp.9 \ + vfs_unbusy.9 \ + VFS_UNMOUNT.9 \ + vfs_unmountall.9 \ + VFS_VGET.9 \ + vget.9 \ + vgone.9 \ + vhold.9 \ + vinvalbuf.9 \ + vm_fault_prefault.9 \ + vm_map.9 \ + vm_map_check_protection.9 \ + vm_map_create.9 \ + vm_map_delete.9 \ + vm_map_entry_resize_free.9 \ + vm_map_find.9 \ + vm_map_findspace.9 \ + vm_map_inherit.9 \ + vm_map_init.9 \ + vm_map_insert.9 \ + vm_map_lock.9 \ + vm_map_lookup.9 \ + vm_map_madvise.9 \ + vm_map_max.9 \ + vm_map_protect.9 \ + vm_map_remove.9 \ + vm_map_simplify_entry.9 \ + vm_map_stack.9 \ + vm_map_submap.9 \ + vm_map_sync.9 \ + vm_map_wire.9 \ + vm_page_alloc.9 \ + vm_page_bits.9 \ + vm_page_busy.9 \ + vm_page_cache.9 \ + vm_page_deactivate.9 \ + vm_page_dontneed.9 \ + vm_page_aflag.9 \ + vm_page_free.9 \ + vm_page_grab.9 \ + vm_page_hold.9 \ + vm_page_insert.9 \ + vm_page_lookup.9 \ + vm_page_rename.9 \ + vm_page_wire.9 \ + vm_set_page_size.9 \ + vmem.9 \ + vn_fullpath.9 \ + vn_isdisk.9 \ + vnet.9 \ + vnode.9 \ + VOP_ACCESS.9 \ + VOP_ACLCHECK.9 \ + VOP_ADVISE.9 \ + VOP_ADVLOCK.9 \ + VOP_ALLOCATE.9 \ + VOP_ATTRIB.9 \ + VOP_BWRITE.9 \ + VOP_CREATE.9 \ + VOP_FSYNC.9 \ + VOP_GETACL.9 \ + VOP_GETEXTATTR.9 \ + VOP_GETPAGES.9 \ + VOP_INACTIVE.9 \ + VOP_IOCTL.9 \ + VOP_LINK.9 \ + VOP_LISTEXTATTR.9 \ + VOP_LOCK.9 \ + VOP_LOOKUP.9 \ + VOP_OPENCLOSE.9 \ + VOP_PATHCONF.9 \ + VOP_PRINT.9 \ + VOP_RDWR.9 \ + VOP_READDIR.9 \ + VOP_READLINK.9 \ + VOP_REALLOCBLKS.9 \ + VOP_REMOVE.9 \ + VOP_RENAME.9 \ + VOP_REVOKE.9 \ + VOP_SETACL.9 \ + VOP_SETEXTATTR.9 \ + VOP_STRATEGY.9 \ + VOP_VPTOCNP.9 \ + VOP_VPTOFH.9 \ + vref.9 \ + vrefcnt.9 \ + vrele.9 \ + vslock.9 \ + watchdog.9 \ + zone.9 + +MLINKS= unr.9 alloc_unr.9 \ + unr.9 alloc_unrl.9 \ + unr.9 alloc_unr_specific.9 \ + unr.9 delete_unrhdr.9 \ + unr.9 free_unr.9 \ + unr.9 new_unrhdr.9 +MLINKS+=accept_filter.9 accept_filt_add.9 \ + accept_filter.9 accept_filt_del.9 \ + accept_filter.9 accept_filt_generic_mod_event.9 \ + accept_filter.9 accept_filt_get.9 +MLINKS+=alq.9 ALQ.9 \ + alq.9 alq_close.9 \ + alq.9 alq_flush.9 \ + alq.9 alq_get.9 \ + alq.9 alq_getn.9 \ + alq.9 alq_open.9 \ + alq.9 alq_open_flags.9 \ + alq.9 alq_post.9 \ + alq.9 alq_post_flags.9 \ + alq.9 alq_write.9 \ + alq.9 alq_writen.9 +MLINKS+=altq.9 ALTQ.9 +MLINKS+=atomic.9 atomic_add.9 \ + atomic.9 atomic_clear.9 \ + atomic.9 atomic_cmpset.9 \ + atomic.9 atomic_fetchadd.9 \ + atomic.9 atomic_load.9 \ + atomic.9 atomic_readandclear.9 \ + atomic.9 atomic_set.9 \ + atomic.9 atomic_store.9 \ + atomic.9 atomic_subtract.9 \ + atomic.9 atomic_swap.9 \ + atomic.9 atomic_testandset.9 +MLINKS+=bitset.9 BITSET_DEFINE.9 \ + bitset.9 BITSET_T_INITIALIZER.9 \ + bitset.9 BITSET_FSET.9 \ + bitset.9 BIT_CLR.9 \ + bitset.9 BIT_COPY.9 \ + bitset.9 BIT_ISSET.9 \ + bitset.9 BIT_SET.9 \ + bitset.9 BIT_ZERO.9 \ + bitset.9 BIT_FILL.9 \ + bitset.9 BIT_SETOF.9 \ + bitset.9 BIT_EMPTY.9 \ + bitset.9 BIT_ISFULLSET.9 \ + bitset.9 BIT_FFS.9 \ + bitset.9 BIT_COUNT.9 \ + bitset.9 BIT_SUBSET.9 \ + bitset.9 BIT_OVERLAP.9 \ + bitset.9 BIT_CMP.9 \ + bitset.9 BIT_OR.9 \ + bitset.9 BIT_AND.9 \ + bitset.9 BIT_NAND.9 \ + bitset.9 BIT_CLR_ATOMIC.9 \ + bitset.9 BIT_SET_ATOMIC.9 \ + bitset.9 BIT_SET_ATOMIC_ACQ.9 \ + bitset.9 BIT_AND_ATOMIC.9 \ + bitset.9 BIT_OR_ATOMIC.9 \ + bitset.9 BIT_COPY_STORE_REL.9 +MLINKS+=bpf.9 bpfattach.9 \ + bpf.9 bpfattach2.9 \ + bpf.9 bpfdetach.9 \ + bpf.9 bpf_filter.9 \ + bpf.9 bpf_mtap.9 \ + bpf.9 bpf_mtap2.9 \ + bpf.9 bpf_tap.9 \ + bpf.9 bpf_validate.9 +MLINKS+=buf.9 bp.9 +MLINKS+=buf_ring.9 buf_ring_alloc.9 \ + buf_ring.9 buf_ring_free.9 \ + buf_ring.9 buf_ring_enqueue.9 \ + buf_ring.9 buf_ring_enqueue_bytes.9 \ + buf_ring.9 buf_ring_dequeue_mc.9 \ + buf_ring.9 buf_ring_dequeue_sc.9 \ + buf_ring.9 buf_ring_count.9 \ + buf_ring.9 buf_ring_empty.9 \ + buf_ring.9 buf_ring_full.9 \ + buf_ring.9 buf_ring_peek.9 +MLINKS+=bus_activate_resource.9 bus_deactivate_resource.9 +MLINKS+=bus_alloc_resource.9 bus_alloc_resource_any.9 +MLINKS+=BUS_BIND_INTR.9 bus_bind_intr.9 +MLINKS+=BUS_DESCRIBE_INTR.9 bus_describe_intr.9 +MLINKS+=bus_dma.9 busdma.9 \ + bus_dma.9 bus_dmamap_create.9 \ + bus_dma.9 bus_dmamap_destroy.9 \ + bus_dma.9 bus_dmamap_load.9 \ + bus_dma.9 bus_dmamap_load_bio.9 \ + bus_dma.9 bus_dmamap_load_ccb.9 \ + bus_dma.9 bus_dmamap_load_mbuf.9 \ + bus_dma.9 bus_dmamap_load_mbuf_sg.9 \ + bus_dma.9 bus_dmamap_load_uio.9 \ + bus_dma.9 bus_dmamap_sync.9 \ + bus_dma.9 bus_dmamap_unload.9 \ + bus_dma.9 bus_dmamem_alloc.9 \ + bus_dma.9 bus_dmamem_free.9 \ + bus_dma.9 bus_dma_tag_create.9 \ + bus_dma.9 bus_dma_tag_destroy.9 +MLINKS+=bus_generic_read_ivar.9 bus_generic_write_ivar.9 +MLINKS+=BUS_READ_IVAR.9 BUS_WRITE_IVAR.9 +MLINKS+=BUS_SETUP_INTR.9 bus_setup_intr.9 \ + BUS_SETUP_INTR.9 BUS_TEARDOWN_INTR.9 \ + BUS_SETUP_INTR.9 bus_teardown_intr.9 +MLINKS+=bus_space.9 bus_space_alloc.9 \ + bus_space.9 bus_space_barrier.9 \ + bus_space.9 bus_space_copy_region_1.9 \ + bus_space.9 bus_space_copy_region_2.9 \ + bus_space.9 bus_space_copy_region_4.9 \ + bus_space.9 bus_space_copy_region_8.9 \ + bus_space.9 bus_space_copy_region_stream_1.9 \ + bus_space.9 bus_space_copy_region_stream_2.9 \ + bus_space.9 bus_space_copy_region_stream_4.9 \ + bus_space.9 bus_space_copy_region_stream_8.9 \ + bus_space.9 bus_space_free.9 \ + bus_space.9 bus_space_map.9 \ + bus_space.9 bus_space_read_1.9 \ + bus_space.9 bus_space_read_2.9 \ + bus_space.9 bus_space_read_4.9 \ + bus_space.9 bus_space_read_8.9 \ + bus_space.9 bus_space_read_multi_1.9 \ + bus_space.9 bus_space_read_multi_2.9 \ + bus_space.9 bus_space_read_multi_4.9 \ + bus_space.9 bus_space_read_multi_8.9 \ + bus_space.9 bus_space_read_multi_stream_1.9 \ + bus_space.9 bus_space_read_multi_stream_2.9 \ + bus_space.9 bus_space_read_multi_stream_4.9 \ + bus_space.9 bus_space_read_multi_stream_8.9 \ + bus_space.9 bus_space_read_region_1.9 \ + bus_space.9 bus_space_read_region_2.9 \ + bus_space.9 bus_space_read_region_4.9 \ + bus_space.9 bus_space_read_region_8.9 \ + bus_space.9 bus_space_read_region_stream_1.9 \ + bus_space.9 bus_space_read_region_stream_2.9 \ + bus_space.9 bus_space_read_region_stream_4.9 \ + bus_space.9 bus_space_read_region_stream_8.9 \ + bus_space.9 bus_space_read_stream_1.9 \ + bus_space.9 bus_space_read_stream_2.9 \ + bus_space.9 bus_space_read_stream_4.9 \ + bus_space.9 bus_space_read_stream_8.9 \ + bus_space.9 bus_space_set_multi_1.9 \ + bus_space.9 bus_space_set_multi_2.9 \ + bus_space.9 bus_space_set_multi_4.9 \ + bus_space.9 bus_space_set_multi_8.9 \ + bus_space.9 bus_space_set_multi_stream_1.9 \ + bus_space.9 bus_space_set_multi_stream_2.9 \ + bus_space.9 bus_space_set_multi_stream_4.9 \ + bus_space.9 bus_space_set_multi_stream_8.9 \ + bus_space.9 bus_space_set_region_1.9 \ + bus_space.9 bus_space_set_region_2.9 \ + bus_space.9 bus_space_set_region_4.9 \ + bus_space.9 bus_space_set_region_8.9 \ + bus_space.9 bus_space_set_region_stream_1.9 \ + bus_space.9 bus_space_set_region_stream_2.9 \ + bus_space.9 bus_space_set_region_stream_4.9 \ + bus_space.9 bus_space_set_region_stream_8.9 \ + bus_space.9 bus_space_subregion.9 \ + bus_space.9 bus_space_unmap.9 \ + bus_space.9 bus_space_write_1.9 \ + bus_space.9 bus_space_write_2.9 \ + bus_space.9 bus_space_write_4.9 \ + bus_space.9 bus_space_write_8.9 \ + bus_space.9 bus_space_write_multi_1.9 \ + bus_space.9 bus_space_write_multi_2.9 \ + bus_space.9 bus_space_write_multi_4.9 \ + bus_space.9 bus_space_write_multi_8.9 \ + bus_space.9 bus_space_write_multi_stream_1.9 \ + bus_space.9 bus_space_write_multi_stream_2.9 \ + bus_space.9 bus_space_write_multi_stream_4.9 \ + bus_space.9 bus_space_write_multi_stream_8.9 \ + bus_space.9 bus_space_write_region_1.9 \ + bus_space.9 bus_space_write_region_2.9 \ + bus_space.9 bus_space_write_region_4.9 \ + bus_space.9 bus_space_write_region_8.9 \ + bus_space.9 bus_space_write_region_stream_1.9 \ + bus_space.9 bus_space_write_region_stream_2.9 \ + bus_space.9 bus_space_write_region_stream_4.9 \ + bus_space.9 bus_space_write_region_stream_8.9 \ + bus_space.9 bus_space_write_stream_1.9 \ + bus_space.9 bus_space_write_stream_2.9 \ + bus_space.9 bus_space_write_stream_4.9 \ + bus_space.9 bus_space_write_stream_8.9 +MLINKS+=byteorder.9 be16dec.9 \ + byteorder.9 be16enc.9 \ + byteorder.9 be16toh.9 \ + byteorder.9 be32dec.9 \ + byteorder.9 be32enc.9 \ + byteorder.9 be32toh.9 \ + byteorder.9 be64dec.9 \ + byteorder.9 be64enc.9 \ + byteorder.9 be64toh.9 \ + byteorder.9 bswap16.9 \ + byteorder.9 bswap32.9 \ + byteorder.9 bswap64.9 \ + byteorder.9 htobe16.9 \ + byteorder.9 htobe32.9 \ + byteorder.9 htobe64.9 \ + byteorder.9 htole16.9 \ + byteorder.9 htole32.9 \ + byteorder.9 htole64.9 \ + byteorder.9 le16dec.9 \ + byteorder.9 le16enc.9 \ + byteorder.9 le16toh.9 \ + byteorder.9 le32dec.9 \ + byteorder.9 le32enc.9 \ + byteorder.9 le32toh.9 \ + byteorder.9 le64dec.9 \ + byteorder.9 le64enc.9 \ + byteorder.9 le64toh.9 +MLINKS+=condvar.9 cv_broadcast.9 \ + condvar.9 cv_broadcastpri.9 \ + condvar.9 cv_destroy.9 \ + condvar.9 cv_init.9 \ + condvar.9 cv_signal.9 \ + condvar.9 cv_timedwait.9 \ + condvar.9 cv_timedwait_sig.9 \ + condvar.9 cv_timedwait_sig_sbt.9 \ + condvar.9 cv_wait.9 \ + condvar.9 cv_wait_sig.9 \ + condvar.9 cv_wait_unlock.9 \ + condvar.9 cv_wmesg.9 +MLINKS+=config_intrhook.9 config_intrhook_disestablish.9 \ + config_intrhook.9 config_intrhook_establish.9 +MLINKS+=contigmalloc.9 contigfree.9 +MLINKS+=casuword.9 casueword.9 \ + casuword.9 casueword32.9 \ + casuword.9 casuword32.9 +MLINKS+=copy.9 copyin.9 \ + copy.9 copyin_nofault.9 \ + copy.9 copyinstr.9 \ + copy.9 copyout.9 \ + copy.9 copyout_nofault.9 \ + copy.9 copystr.9 +MLINKS+=counter.9 counter_u64_alloc.9 \ + counter.9 counter_u64_free.9 \ + counter.9 counter_u64_add.9 \ + counter.9 counter_enter.9 \ + counter.9 counter_exit.9 \ + counter.9 counter_u64_add_protected.9 \ + counter.9 counter_u64_fetch.9 \ + counter.9 counter_u64_zero.9 +MLINKS+=cpuset.9 CPUSET_T_INITIALIZER.9 \ + cpuset.9 CPUSET_FSET.9 \ + cpuset.9 CPU_CLR.9 \ + cpuset.9 CPU_COPY.9 \ + cpuset.9 CPU_ISSET.9 \ + cpuset.9 CPU_SET.9 \ + cpuset.9 CPU_ZERO.9 \ + cpuset.9 CPU_FILL.9 \ + cpuset.9 CPU_SETOF.9 \ + cpuset.9 CPU_EMPTY.9 \ + cpuset.9 CPU_ISFULLSET.9 \ + cpuset.9 CPU_FFS.9 \ + cpuset.9 CPU_COUNT.9 \ + cpuset.9 CPU_SUBSET.9 \ + cpuset.9 CPU_OVERLAP.9 \ + cpuset.9 CPU_CMP.9 \ + cpuset.9 CPU_OR.9 \ + cpuset.9 CPU_AND.9 \ + cpuset.9 CPU_NAND.9 \ + cpuset.9 CPU_CLR_ATOMIC.9 \ + cpuset.9 CPU_SET_ATOMIC.9 \ + cpuset.9 CPU_SET_ATOMIC_ACQ.9 \ + cpuset.9 CPU_AND_ATOMIC.9 \ + cpuset.9 CPU_OR_ATOMIC.9 \ + cpuset.9 CPU_COPY_STORE_REL.9 +MLINKS+=critical_enter.9 critical.9 \ + critical_enter.9 critical_exit.9 +MLINKS+=crypto.9 crypto_dispatch.9 \ + crypto.9 crypto_done.9 \ + crypto.9 crypto_freereq.9 \ + crypto.9 crypto_freesession.9 \ + crypto.9 crypto_get_driverid.9 \ + crypto.9 crypto_getreq.9 \ + crypto.9 crypto_kdispatch.9 \ + crypto.9 crypto_kdone.9 \ + crypto.9 crypto_kregister.9 \ + crypto.9 crypto_newsession.9 \ + crypto.9 crypto_register.9 \ + crypto.9 crypto_unblock.9 \ + crypto.9 crypto_unregister.9 \ + crypto.9 crypto_unregister_all.9 +MLINKS+=DB_COMMAND.9 DB_SHOW_ALL_COMMAND.9 \ + DB_COMMAND.9 DB_SHOW_COMMAND.9 +MLINKS+=dev_clone.9 drain_dev_clone_events.9 +MLINKS+=devfs_set_cdevpriv.9 devfs_clear_cdevpriv.9 \ + devfs_set_cdevpriv.9 devfs_get_cdevpriv.9 +MLINKS+=device_add_child.9 device_add_child_ordered.9 +MLINKS+=device_enable.9 device_disable.9 \ + device_enable.9 device_is_enabled.9 +MLINKS+=device_get_ivars.9 device_set_ivars.9 +MLINKS+=device_get_name.9 device_get_nameunit.9 +MLINKS+=device_get_state.9 device_busy.9 \ + device_get_state.9 device_is_alive.9 \ + device_get_state.9 device_is_attached.9 \ + device_get_state.9 device_unbusy.9 +MLINKS+=device_get_sysctl.9 device_get_sysctl_ctx.9 \ + device_get_sysctl.9 device_get_sysctl_tree.9 +MLINKS+=device_quiet.9 device_is_quiet.9 \ + device_quiet.9 device_verbose.9 +MLINKS+=device_set_desc.9 device_get_desc.9 \ + device_set_desc.9 device_set_desc_copy.9 +MLINKS+=device_set_flags.9 device_get_flags.9 +MLINKS+=devstat.9 devicestat.9 \ + devstat.9 devstat_add_entry.9 \ + devstat.9 devstat_end_transaction.9 \ + devstat.9 devstat_remove_entry.9 \ + devstat.9 devstat_start_transaction.9 +MLINKS+=disk.9 disk_alloc.9 \ + disk.9 disk_create.9 \ + disk.9 disk_destroy.9 \ + disk.9 disk_gone.9 \ + disk.9 disk_resize.9 +MLINKS+=domain.9 DOMAIN_SET.9 \ + domain.9 domain_add.9 \ + domain.9 pfctlinput.9 \ + domain.9 pfctlinput2.9 \ + domain.9 pffinddomain.9 \ + domain.9 pffindproto.9 \ + domain.9 pffindtype.9 +MLINKS+=drbr.9 drbr_free.9 \ + drbr.9 drbr_enqueue.9 \ + drbr.9 drbr_dequeue.9 \ + drbr.9 drbr_dequeue_cond.9 \ + drbr.9 drbr_flush.9 \ + drbr.9 drbr_empty.9 \ + drbr.9 drbr_inuse.9 \ + drbr.9 drbr_stats_update.9 +MLINKS+=DRIVER_MODULE.9 DRIVER_MODULE_ORDERED.9 \ + DRIVER_MODULE.9 EARLY_DRIVER_MODULE.9 \ + DRIVER_MODULE.9 EARLY_DRIVER_MODULE_ORDERED.9 +MLINKS+=EVENTHANDLER.9 EVENTHANDLER_DECLARE.9 \ + EVENTHANDLER.9 EVENTHANDLER_DEREGISTER.9 \ + EVENTHANDLER.9 eventhandler_deregister.9 \ + EVENTHANDLER.9 eventhandler_find_list.9 \ + EVENTHANDLER.9 EVENTHANDLER_INVOKE.9 \ + EVENTHANDLER.9 eventhandler_prune_list.9 \ + EVENTHANDLER.9 EVENTHANDLER_REGISTER.9 \ + EVENTHANDLER.9 eventhandler_register.9 +MLINKS+=eventtimers.9 et_register.9 \ + eventtimers.9 et_deregister.9 \ + eventtimers.9 et_ban.9 \ + eventtimers.9 et_find.9 \ + eventtimers.9 et_free.9 \ + eventtimers.9 et_init.9 \ + eventtimers.9 ET_LOCK.9 \ + eventtimers.9 ET_UNLOCK.9 \ + eventtimers.9 et_start.9 \ + eventtimers.9 et_stop.9 +MLINKS+=fail.9 KFAIL_POINT_CODE.9 \ + fail.9 KFAIL_POINT_ERROR.9 \ + fail.9 KFAIL_POINT_GOTO.9 \ + fail.9 KFAIL_POINT_RETURN.9 \ + fail.9 KFAIL_POINT_RETURN_VOID.9 +MLINKS+=fetch.9 fubyte.9 \ + fetch.9 fuswintr.9 \ + fetch.9 fuword.9 \ + fetch.9 fuword16.9 \ + fetch.9 fuword32.9 \ + fetch.9 fuword64.9 \ + fetch.9 fueword.9 \ + fetch.9 fueword32.9 \ + fetch.9 fueword64.9 +MLINKS+=firmware.9 firmware_get.9 \ + firmware.9 firmware_put.9 \ + firmware.9 firmware_register.9 \ + firmware.9 firmware_unregister.9 +MLINKS+=fpu_kern.9 fpu_kern_alloc_ctx.9 \ + fpu_kern.9 fpu_kern_free_ctx.9 \ + fpu_kern.9 fpu_kern_enter.9 \ + fpu_kern.9 fpu_kern_leave.9 \ + fpu_kern.9 fpu_kern_thread.9 \ + fpu_kern.9 is_fpu_kern_thread.9 +MLINKS+=g_attach.9 g_detach.9 +MLINKS+=g_bio.9 g_alloc_bio.9 \ + g_bio.9 g_clone_bio.9 \ + g_bio.9 g_destroy_bio.9 \ + g_bio.9 g_duplicate_bio.9 \ + g_bio.9 g_new_bio.9 \ + g_bio.9 g_print_bio.9 +MLINKS+=g_consumer.9 g_destroy_consumer.9 \ + g_consumer.9 g_new_consumer.9 +MLINKS+=g_data.9 g_read_data.9 \ + g_data.9 g_write_data.9 +MLINKS+=getenv.9 freeenv.9 \ + getenv.9 getenv_int.9 \ + getenv.9 getenv_long.9 \ + getenv.9 getenv_string.9 \ + getenv.9 getenv_quad.9 \ + getenv.9 getenv_uint.9 \ + getenv.9 getenv_ulong.9 \ + getenv.9 setenv.9 \ + getenv.9 testenv.9 \ + getenv.9 unsetenv.9 +MLINKS+=g_event.9 g_cancel_event.9 \ + g_event.9 g_post_event.9 \ + g_event.9 g_waitfor_event.9 +MLINKS+=g_geom.9 g_destroy_geom.9 \ + g_geom.9 g_new_geomf.9 +MLINKS+=g_provider.9 g_destroy_provider.9 \ + g_provider.9 g_error_provider.9 \ + g_provider.9 g_new_providerf.9 +MLINKS+=hash.9 hash32.9 \ + hash.9 hash32_buf.9 \ + hash.9 hash32_str.9 \ + hash.9 hash32_stre.9 \ + hash.9 hash32_strn.9 \ + hash.9 hash32_strne.9 \ + hash.9 jenkins_hash.9 \ + hash.9 jenkins_hash32.9 +MLINKS+=hashinit.9 hashdestroy.9 \ + hashinit.9 hashinit_flags.9 \ + hashinit.9 phashinit.9 +MLINKS+=hhook.9 hhook_head_register.9 \ + hhook.9 hhook_head_deregister.9 \ + hhook.9 hhook_head_deregister_lookup.9 \ + hhook.9 hhook_run_hooks.9 \ + hhook.9 HHOOKS_RUN_IF.9 \ + hhook.9 HHOOKS_RUN_LOOKUP_IF.9 +MLINKS+=ieee80211.9 ieee80211_ifattach.9 \ + ieee80211.9 ieee80211_ifdetach.9 +MLINKS+=ieee80211_amrr.9 ieee80211_amrr_choose.9 \ + ieee80211_amrr.9 ieee80211_amrr_cleanup.9 \ + ieee80211_amrr.9 ieee80211_amrr_init.9 \ + ieee80211_amrr.9 ieee80211_amrr_node_init.9 \ + ieee80211_amrr.9 ieee80211_amrr_setinterval.9 \ + ieee80211_amrr.9 ieee80211_amrr_tx_complete.9 \ + ieee80211_amrr.9 ieee80211_amrr_tx_update.9 +MLINKS+=ieee80211_beacon.9 ieee80211_beacon_alloc.9 \ + ieee80211_beacon.9 ieee80211_beacon_notify.9 \ + ieee80211_beacon.9 ieee80211_beacon_update.9 +MLINKS+=ieee80211_bmiss.9 ieee80211_beacon_miss.9 +MLINKS+=ieee80211_crypto.9 ieee80211_crypto_available.9 \ + ieee80211_crypto.9 ieee80211_crypto_decap.9 \ + ieee80211_crypto.9 ieee80211_crypto_delglobalkeys.9 \ + ieee80211_crypto.9 ieee80211_crypto_delkey.9 \ + ieee80211_crypto.9 ieee80211_crypto_demic.9 \ + ieee80211_crypto.9 ieee80211_crypto_encap.9 \ + ieee80211_crypto.9 ieee80211_crypto_enmic.9 \ + ieee80211_crypto.9 ieee80211_crypto_newkey.9 \ + ieee80211_crypto.9 ieee80211_crypto_register.9 \ + ieee80211_crypto.9 ieee80211_crypto_reload_keys.9 \ + ieee80211_crypto.9 ieee80211_crypto_setkey.9 \ + ieee80211_crypto.9 ieee80211_crypto_unregister.9 \ + ieee80211_crypto.9 ieee80211_key_update_begin.9 \ + ieee80211_crypto.9 ieee80211_key_update_end.9 \ + ieee80211_crypto.9 ieee80211_notify_michael_failure.9 \ + ieee80211_crypto.9 ieee80211_notify_replay_failure.9 +MLINKS+=ieee80211_input.9 ieee80211_input_all.9 +MLINKS+=ieee80211_node.9 ieee80211_dump_node.9 \ + ieee80211_node.9 ieee80211_dump_nodes.9 \ + ieee80211_node.9 ieee80211_find_rxnode.9 \ + ieee80211_node.9 ieee80211_find_rxnode_withkey.9 \ + ieee80211_node.9 ieee80211_free_node.9 \ + ieee80211_node.9 ieee80211_iterate_nodes.9 \ + ieee80211_node.9 ieee80211_ref_node.9 \ + ieee80211_node.9 ieee80211_unref_node.9 +MLINKS+=ieee80211_output.9 ieee80211_process_callback.9 \ + ieee80211_output.9 M_SEQNO_GET.9 \ + ieee80211_output.9 M_WME_GETAC.9 +MLINKS+=ieee80211_proto.9 ieee80211_new_state.9 \ + ieee80211_proto.9 ieee80211_resume_all.9 \ + ieee80211_proto.9 ieee80211_start_all.9 \ + ieee80211_proto.9 ieee80211_stop_all.9 \ + ieee80211_proto.9 ieee80211_suspend_all.9 \ + ieee80211_proto.9 ieee80211_waitfor_parent.9 +MLINKS+=ieee80211_radiotap.9 ieee80211_radiotap_active.9 \ + ieee80211_radiotap.9 ieee80211_radiotap_active_vap.9 \ + ieee80211_radiotap.9 ieee80211_radiotap_attach.9 \ + ieee80211_radiotap.9 ieee80211_radiotap_tx.9 \ + ieee80211_radiotap.9 radiotap.9 +MLINKS+=ieee80211_regdomain.9 ieee80211_alloc_countryie.9 \ + ieee80211_regdomain.9 ieee80211_init_channels.9 \ + ieee80211_regdomain.9 ieee80211_sort_channels.9 +MLINKS+=ieee80211_scan.9 ieee80211_add_scan.9 \ + ieee80211_scan.9 ieee80211_bg_scan.9 \ + ieee80211_scan.9 ieee80211_cancel_scan.9 \ + ieee80211_scan.9 ieee80211_cancel_scan_any.9 \ + ieee80211_scan.9 ieee80211_check_scan.9 \ + ieee80211_scan.9 ieee80211_check_scan_current.9 \ + ieee80211_scan.9 ieee80211_flush.9 \ + ieee80211_scan.9 ieee80211_probe_curchan.9 \ + ieee80211_scan.9 ieee80211_scan_assoc_fail.9 \ + ieee80211_scan.9 ieee80211_scan_done.9 \ + ieee80211_scan.9 ieee80211_scan_dump_channels.9 \ + ieee80211_scan.9 ieee80211_scan_flush.9 \ + ieee80211_scan.9 ieee80211_scan_iterate.9 \ + ieee80211_scan.9 ieee80211_scan_next.9 \ + ieee80211_scan.9 ieee80211_scan_timeout.9 \ + ieee80211_scan.9 ieee80211_scanner_get.9 \ + ieee80211_scan.9 ieee80211_scanner_register.9 \ + ieee80211_scan.9 ieee80211_scanner_unregister.9 \ + ieee80211_scan.9 ieee80211_scanner_unregister_all.9 \ + ieee80211_scan.9 ieee80211_start_scan.9 +MLINKS+=ieee80211_vap.9 ieee80211_vap_attach.9 \ + ieee80211_vap.9 ieee80211_vap_detach.9 \ + ieee80211_vap.9 ieee80211_vap_setup.9 +MLINKS+=ifnet.9 if_addmulti.9 \ + ifnet.9 if_alloc.9 \ + ifnet.9 if_allmulti.9 \ + ifnet.9 if_attach.9 \ + ifnet.9 if_data.9 \ + ifnet.9 IF_DEQUEUE.9 \ + ifnet.9 if_delmulti.9 \ + ifnet.9 if_detach.9 \ + ifnet.9 if_down.9 \ + ifnet.9 if_findmulti.9 \ + ifnet.9 if_free.9 \ + ifnet.9 if_free_type.9 \ + ifnet.9 if_up.9 \ + ifnet.9 ifa_free.9 \ + ifnet.9 ifa_ifwithaddr.9 \ + ifnet.9 ifa_ifwithdstaddr.9 \ + ifnet.9 ifa_ifwithnet.9 \ + ifnet.9 ifa_ref.9 \ + ifnet.9 ifaddr.9 \ + ifnet.9 ifaddr_byindex.9 \ + ifnet.9 ifaof_ifpforaddr.9 \ + ifnet.9 ifioctl.9 \ + ifnet.9 ifpromisc.9 \ + ifnet.9 ifqueue.9 \ + ifnet.9 ifunit.9 \ + ifnet.9 ifunit_ref.9 +MLINKS+=insmntque.9 insmntque1.9 +MLINKS+=ithread.9 ithread_add_handler.9 \ + ithread.9 ithread_create.9 \ + ithread.9 ithread_destroy.9 \ + ithread.9 ithread_priority.9 \ + ithread.9 ithread_remove_handler.9 \ + ithread.9 ithread_schedule.9 +MLINKS+=kernacc.9 useracc.9 +MLINKS+=kernel_mount.9 free_mntarg.9 \ + kernel_mount.9 kernel_vmount.9 \ + kernel_mount.9 mount_arg.9 \ + kernel_mount.9 mount_argb.9 \ + kernel_mount.9 mount_argf.9 \ + kernel_mount.9 mount_argsu.9 +MLINKS+=khelp.9 khelp_add_hhook.9 \ + khelp.9 KHELP_DECLARE_MOD.9 \ + khelp.9 KHELP_DECLARE_MOD_UMA.9 \ + khelp.9 khelp_destroy_osd.9 \ + khelp.9 khelp_get_id.9 \ + khelp.9 khelp_get_osd.9 \ + khelp.9 khelp_init_osd.9 \ + khelp.9 khelp_remove_hhook.9 +MLINKS+=kobj.9 DEFINE_CLASS.9 \ + kobj.9 kobj_class_compile.9 \ + kobj.9 kobj_class_compile_static.9 \ + kobj.9 kobj_class_free.9 \ + kobj.9 kobj_create.9 \ + kobj.9 kobj_delete.9 \ + kobj.9 kobj_init.9 \ + kobj.9 kobj_init_static.9 +MLINKS+=kproc.9 kproc_create.9 \ + kproc.9 kproc_exit.9 \ + kproc.9 kproc_kthread_add.9 \ + kproc.9 kproc_resume.9 \ + kproc.9 kproc_shutdown.9 \ + kproc.9 kproc_start.9 \ + kproc.9 kproc_suspend.9 \ + kproc.9 kproc_suspend_check.9 \ + kproc.9 kthread_create.9 +MLINKS+=kqueue.9 knlist_add.9 \ + kqueue.9 knlist_clear.9 \ + kqueue.9 knlist_delete.9 \ + kqueue.9 knlist_destroy.9 \ + kqueue.9 knlist_empty.9 \ + kqueue.9 knlist_init.9 \ + kqueue.9 knlist_init_mtx.9 \ + kqueue.9 knlist_init_rw_reader.9 \ + kqueue.9 knlist_remove.9 \ + kqueue.9 knlist_remove_inevent.9 \ + kqueue.9 knote_fdclose.9 \ + kqueue.9 KNOTE_LOCKED.9 \ + kqueue.9 KNOTE_UNLOCKED.9 \ + kqueue.9 kqfd_register.9 \ + kqueue.9 kqueue_add_filteropts.9 \ + kqueue.9 kqueue_del_filteropts.9 +MLINKS+=kthread.9 kthread_add.9 \ + kthread.9 kthread_exit.9 \ + kthread.9 kthread_resume.9 \ + kthread.9 kthread_shutdown.9 \ + kthread.9 kthread_start.9 \ + kthread.9 kthread_suspend.9 \ + kthread.9 kthread_suspend_check.9 +MLINKS+=ktr.9 CTR0.9 \ + ktr.9 CTR1.9 \ + ktr.9 CTR2.9 \ + ktr.9 CTR3.9 \ + ktr.9 CTR4.9 \ + ktr.9 CTR5.9 \ + ktr.9 CTR6.9 +MLINKS+=lock.9 lockdestroy.9 \ + lock.9 lockinit.9 \ + lock.9 lockmgr.9 \ + lock.9 lockmgr_args.9 \ + lock.9 lockmgr_args_rw.9 \ + lock.9 lockmgr_assert.9 \ + lock.9 lockmgr_disown.9 \ + lock.9 lockmgr_printinfo.9 \ + lock.9 lockmgr_recursed.9 \ + lock.9 lockmgr_rw.9 \ + lock.9 lockmgr_waiters.9 \ + lock.9 lockstatus.9 +MLINKS+=LOCK_PROFILING.9 MUTEX_PROFILING.9 +MLINKS+=make_dev.9 destroy_dev.9 \ + make_dev.9 destroy_dev_drain.9 \ + make_dev.9 destroy_dev_sched.9 \ + make_dev.9 destroy_dev_sched_cb.9 \ + make_dev.9 dev_depends.9 \ + make_dev.9 make_dev_alias.9 \ + make_dev.9 make_dev_alias_p.9 \ + make_dev.9 make_dev_cred.9 \ + make_dev.9 make_dev_credf.9 \ + make_dev.9 make_dev_p.9 \ + make_dev.9 make_dev_s.9 +MLINKS+=malloc.9 free.9 \ + malloc.9 MALLOC_DECLARE.9 \ + malloc.9 MALLOC_DEFINE.9 \ + malloc.9 realloc.9 \ + malloc.9 reallocf.9 +MLINKS+=mbchain.9 mb_detach.9 \ + mbchain.9 mb_done.9 \ + mbchain.9 mb_fixhdr.9 \ + mbchain.9 mb_init.9 \ + mbchain.9 mb_initm.9 \ + mbchain.9 mb_put_int64be.9 \ + mbchain.9 mb_put_int64le.9 \ + mbchain.9 mb_put_mbuf.9 \ + mbchain.9 mb_put_mem.9 \ + mbchain.9 mb_put_uint16be.9 \ + mbchain.9 mb_put_uint16le.9 \ + mbchain.9 mb_put_uint32be.9 \ + mbchain.9 mb_put_uint32le.9 \ + mbchain.9 mb_put_uint8.9 \ + mbchain.9 mb_put_uio.9 \ + mbchain.9 mb_reserve.9 +MLINKS+=mbpool.9 mbp_alloc.9 \ + mbpool.9 mbp_card_free.9 \ + mbpool.9 mbp_count.9 \ + mbpool.9 mbp_create.9 \ + mbpool.9 mbp_destroy.9 \ + mbpool.9 mbp_ext_free.9 \ + mbpool.9 mbp_free.9 \ + mbpool.9 mbp_get.9 \ + mbpool.9 mbp_get_keep.9 \ + mbpool.9 mbp_sync.9 +MLINKS+=\ + mbuf.9 m_adj.9 \ + mbuf.9 m_align.9 \ + mbuf.9 M_ALIGN.9 \ + mbuf.9 m_append.9 \ + mbuf.9 m_apply.9 \ + mbuf.9 m_cat.9 \ + mbuf.9 MCHTYPE.9 \ + mbuf.9 MCLGET.9 \ + mbuf.9 m_collapse.9 \ + mbuf.9 m_copyback.9 \ + mbuf.9 m_copydata.9 \ + mbuf.9 m_copym.9 \ + mbuf.9 m_copypacket.9 \ + mbuf.9 m_copyup.9 \ + mbuf.9 m_defrag.9 \ + mbuf.9 m_devget.9 \ + mbuf.9 m_dup.9 \ + mbuf.9 m_dup_pkthdr.9 \ + mbuf.9 MEXTADD.9 \ + mbuf.9 m_fixhdr.9 \ + mbuf.9 m_free.9 \ + mbuf.9 m_freem.9 \ + mbuf.9 MGET.9 \ + mbuf.9 m_get.9 \ + mbuf.9 m_get2.9 \ + mbuf.9 m_getjcl.9 \ + mbuf.9 m_getcl.9 \ + mbuf.9 m_getclr.9 \ + mbuf.9 MGETHDR.9 \ + mbuf.9 m_gethdr.9 \ + mbuf.9 m_getm.9 \ + mbuf.9 m_getptr.9 \ + mbuf.9 MH_ALIGN.9 \ + mbuf.9 M_LEADINGSPACE.9 \ + mbuf.9 m_length.9 \ + mbuf.9 M_MOVE_PKTHDR.9 \ + mbuf.9 m_move_pkthdr.9 \ + mbuf.9 M_PREPEND.9 \ + mbuf.9 m_prepend.9 \ + mbuf.9 m_pulldown.9 \ + mbuf.9 m_pullup.9 \ + mbuf.9 m_split.9 \ + mbuf.9 mtod.9 \ + mbuf.9 M_TRAILINGSPACE.9 \ + mbuf.9 m_unshare.9 \ + mbuf.9 M_WRITABLE.9 +MLINKS+=\ + mbuf_tags.9 m_tag_alloc.9 \ + mbuf_tags.9 m_tag_copy.9 \ + mbuf_tags.9 m_tag_copy_chain.9 \ + mbuf_tags.9 m_tag_delete.9 \ + mbuf_tags.9 m_tag_delete_chain.9 \ + mbuf_tags.9 m_tag_delete_nonpersistent.9 \ + mbuf_tags.9 m_tag_find.9 \ + mbuf_tags.9 m_tag_first.9 \ + mbuf_tags.9 m_tag_free.9 \ + mbuf_tags.9 m_tag_get.9 \ + mbuf_tags.9 m_tag_init.9 \ + mbuf_tags.9 m_tag_locate.9 \ + mbuf_tags.9 m_tag_next.9 \ + mbuf_tags.9 m_tag_prepend.9 \ + mbuf_tags.9 m_tag_unlink.9 +MLINKS+=MD5.9 MD5Init.9 \ + MD5.9 MD5Transform.9 +MLINKS+=mdchain.9 md_append_record.9 \ + mdchain.9 md_done.9 \ + mdchain.9 md_get_int64.9 \ + mdchain.9 md_get_int64be.9 \ + mdchain.9 md_get_int64le.9 \ + mdchain.9 md_get_mbuf.9 \ + mdchain.9 md_get_mem.9 \ + mdchain.9 md_get_uint16.9 \ + mdchain.9 md_get_uint16be.9 \ + mdchain.9 md_get_uint16le.9 \ + mdchain.9 md_get_uint32.9 \ + mdchain.9 md_get_uint32be.9 \ + mdchain.9 md_get_uint32le.9 \ + mdchain.9 md_get_uint8.9 \ + mdchain.9 md_get_uio.9 \ + mdchain.9 md_initm.9 \ + mdchain.9 md_next_record.9 +MLINKS+=microtime.9 bintime.9 \ + microtime.9 getbintime.9 \ + microtime.9 getmicrotime.9 \ + microtime.9 getnanotime.9 \ + microtime.9 nanotime.9 +MLINKS+=microuptime.9 binuptime.9 \ + microuptime.9 getbinuptime.9 \ + microuptime.9 getmicrouptime.9 \ + microuptime.9 getnanouptime.9 \ + microuptime.9 getsbinuptime.9 \ + microuptime.9 nanouptime.9 \ + microuptime.9 sbinuptime.9 +MLINKS+=mi_switch.9 cpu_switch.9 \ + mi_switch.9 cpu_throw.9 +MLINKS+=mod_cc.9 CCV.9 \ + mod_cc.9 DECLARE_CC_MODULE.9 +MLINKS+=mtx_pool.9 mtx_pool_alloc.9 \ + mtx_pool.9 mtx_pool_create.9 \ + mtx_pool.9 mtx_pool_destroy.9 \ + mtx_pool.9 mtx_pool_find.9 \ + mtx_pool.9 mtx_pool_lock.9 \ + mtx_pool.9 mtx_pool_lock_spin.9 \ + mtx_pool.9 mtx_pool_unlock.9 \ + mtx_pool.9 mtx_pool_unlock_spin.9 +MLINKS+=mutex.9 mtx_assert.9 \ + mutex.9 mtx_destroy.9 \ + mutex.9 mtx_init.9 \ + mutex.9 mtx_initialized.9 \ + mutex.9 mtx_lock.9 \ + mutex.9 mtx_lock_flags.9 \ + mutex.9 mtx_lock_spin.9 \ + mutex.9 mtx_lock_spin_flags.9 \ + mutex.9 mtx_owned.9 \ + mutex.9 mtx_recursed.9 \ + mutex.9 mtx_sleep.9 \ + mutex.9 MTX_SYSINIT.9 \ + mutex.9 mtx_trylock.9 \ + mutex.9 mtx_trylock_flags.9 \ + mutex.9 mtx_unlock.9 \ + mutex.9 mtx_unlock_flags.9 \ + mutex.9 mtx_unlock_spin.9 \ + mutex.9 mtx_unlock_spin_flags.9 +MLINKS+=namei.9 NDFREE.9 \ + namei.9 NDINIT.9 +MLINKS+=netisr.9 netisr_clearqdrops.9 \ + netisr.9 netisr_default_flow2cpu.9 \ + netisr.9 netisr_dispatch.9 \ + netisr.9 netisr_dispatch_src.9 \ + netisr.9 netisr_get_cpucount.9 \ + netisr.9 netisr_get_cpuid.9 \ + netisr.9 netisr_getqdrops.9 \ + netisr.9 netisr_getqlimit.9 \ + netisr.9 netisr_queue.9 \ + netisr.9 netisr_queue_src.9 \ + netisr.9 netisr_register.9 \ + netisr.9 netisr_setqlimit.9 \ + netisr.9 netisr_unregister.9 +MLINKS+=nv.9 libnv.9 \ + nv.9 nvlist.9 \ + nv.9 nvlist_add_binary.9 \ + nv.9 nvlist_add_bool.9 \ + nv.9 nvlist_add_descriptor.9 \ + nv.9 nvlist_add_null.9 \ + nv.9 nvlist_add_number.9 \ + nv.9 nvlist_add_nvlist.9 \ + nv.9 nvlist_add_string.9 \ + nv.9 nvlist_add_stringf.9 \ + nv.9 nvlist_add_stringv.9 \ + nv.9 nvlist_clone.9 \ + nv.9 nvlist_create.9 \ + nv.9 nvlist_destroy.9 \ + nv.9 nvlist_dump.9 \ + nv.9 nvlist_empty.9 \ + nv.9 nvlist_error.9 \ + nv.9 nvlist_exists.9 \ + nv.9 nvlist_exists_binary.9 \ + nv.9 nvlist_exists_bool.9 \ + nv.9 nvlist_exists_descriptor.9 \ + nv.9 nvlist_exists_null.9 \ + nv.9 nvlist_exists_number.9 \ + nv.9 nvlist_exists_nvlist.9 \ + nv.9 nvlist_exists_string.9 \ + nv.9 nvlist_exists_type.9 \ + nv.9 nvlist_fdump.9 \ + nv.9 nvlist_flags.9 \ + nv.9 nvlist_free.9 \ + nv.9 nvlist_free_binary.9 \ + nv.9 nvlist_free_bool.9 \ + nv.9 nvlist_free_descriptor.9 \ + nv.9 nvlist_free_null.9 \ + nv.9 nvlist_free_number.9 \ + nv.9 nvlist_free_nvlist.9 \ + nv.9 nvlist_free_string.9 \ + nv.9 nvlist_free_type.9 \ + nv.9 nvlist_get_binary.9 \ + nv.9 nvlist_get_bool.9 \ + nv.9 nvlist_get_descriptor.9 \ + nv.9 nvlist_get_number.9 \ + nv.9 nvlist_get_nvlist.9 \ + nv.9 nvlist_get_parent.9 \ + nv.9 nvlist_get_string.9 \ + nv.9 nvlist_move_binary.9 \ + nv.9 nvlist_move_descriptor.9 \ + nv.9 nvlist_move_nvlist.9 \ + nv.9 nvlist_move_string.9 \ + nv.9 nvlist_next.9 \ + nv.9 nvlist_pack.9 \ + nv.9 nvlist_recv.9 \ + nv.9 nvlist_send.9 \ + nv.9 nvlist_set_error.9 \ + nv.9 nvlist_size.9 \ + nv.9 nvlist_take_binary.9 \ + nv.9 nvlist_take_bool.9 \ + nv.9 nvlist_take_descriptor.9 \ + nv.9 nvlist_take_number.9 \ + nv.9 nvlist_take_nvlist.9 \ + nv.9 nvlist_take_string.9 \ + nv.9 nvlist_unpack.9 \ + nv.9 nvlist_xfer.9 +MLINKS+=osd.9 osd_call.9 \ + osd.9 osd_del.9 \ + osd.9 osd_deregister.9 \ + osd.9 osd_exit.9 \ + osd.9 osd_get.9 \ + osd.9 osd_register.9 \ + osd.9 osd_set.9 +MLINKS+=panic.9 vpanic.9 +MLINKS+=pbuf.9 getpbuf.9 \ + pbuf.9 relpbuf.9 \ + pbuf.9 trypbuf.9 +MLINKS+=PCBGROUP.9 in_pcbgroup_byhash.9 \ + PCBGROUP.9 in_pcbgroup_byinpcb.9 \ + PCBGROUP.9 in_pcbgroup_destroy.9 \ + PCBGROUP.9 in_pcbgroup_enabled.9 \ + PCBGROUP.9 in_pcbgroup_init.9 \ + PCBGROUP.9 in_pcbgroup_remove.9 \ + PCBGROUP.9 in_pcbgroup_update.9 \ + PCBGROUP.9 in_pcbgroup_update_mbuf.9 \ + PCBGROUP.9 in6_pcbgroup_byhash.9 +MLINKS+=pci.9 pci_alloc_msi.9 \ + pci.9 pci_alloc_msix.9 \ + pci.9 pci_disable_busmaster.9 \ + pci.9 pci_disable_io.9 \ + pci.9 pci_enable_busmaster.9 \ + pci.9 pci_enable_io.9 \ + pci.9 pci_find_bsf.9 \ + pci.9 pci_find_cap.9 \ + pci.9 pci_find_dbsf.9 \ + pci.9 pci_find_device.9 \ + pci.9 pci_find_extcap.9 \ + pci.9 pci_find_htcap.9 \ + pci.9 pci_find_pcie_root_port.9 \ + pci.9 pci_get_max_read_req.9 \ + pci.9 pci_get_powerstate.9 \ + pci.9 pci_get_vpd_ident.9 \ + pci.9 pci_get_vpd_readonly.9 \ + pci.9 pci_iov_attach.9 \ + pci.9 pci_iov_detach.9 \ + pci.9 pci_msi_count.9 \ + pci.9 pci_msix_count.9 \ + pci.9 pci_msix_pba_bar.9 \ + pci.9 pci_msix_table_bar.9 \ + pci.9 pci_pending_msix.9 \ + pci.9 pci_read_config.9 \ + pci.9 pci_release_msi.9 \ + pci.9 pci_remap_msix.9 \ + pci.9 pci_restore_state.9 \ + pci.9 pci_save_state.9 \ + pci.9 pci_set_powerstate.9 \ + pci.9 pci_set_max_read_req.9 \ + pci.9 pci_write_config.9 \ + pci.9 pcie_adjust_config.9 \ + pci.9 pcie_read_config.9 \ + pci.9 pcie_write_config.9 +MLINKS+=pci_iov_schema.9 pci_iov_schema_alloc_node.9 \ + pci_iov_schema.9 pci_iov_schema_add_bool.9 \ + pci_iov_schema.9 pci_iov_schema_add_string.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint8.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint16.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint32.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint64.9 \ + pci_iov_schema.9 pci_iov_schema_add_unicast_mac.9 +MLINKS+=pfil.9 pfil_add_hook.9 \ + pfil.9 pfil_head_register.9 \ + pfil.9 pfil_head_unregister.9 \ + pfil.9 pfil_hook_get.9 \ + pfil.9 pfil_remove_hook.9 \ + pfil.9 pfil_rlock.9 \ + pfil.9 pfil_run_hooks.9 \ + pfil.9 pfil_runlock.9 \ + pfil.9 pfil_wlock.9 \ + pfil.9 pfil_wunlock.9 +MLINKS+=pfind.9 zpfind.9 +MLINKS+=PHOLD.9 PRELE.9 \ + PHOLD.9 _PHOLD.9 \ + PHOLD.9 _PRELE.9 \ + PHOLD.9 PROC_ASSERT_HELD.9 \ + PHOLD.9 PROC_ASSERT_NOT_HELD.9 +MLINKS+=pmap_copy.9 pmap_copy_page.9 +MLINKS+=pmap_extract.9 pmap_extract_and_hold.9 +MLINKS+=pmap_init.9 pmap_init2.9 +MLINKS+=pmap_is_modified.9 pmap_ts_referenced.9 +MLINKS+=pmap_pinit.9 pmap_pinit0.9 \ + pmap_pinit.9 pmap_pinit2.9 +MLINKS+=pmap_qenter.9 pmap_qremove.9 +MLINKS+=pmap_quick_enter_page.9 pmap_quick_remove_page.9 +MLINKS+=pmap_remove.9 pmap_remove_all.9 \ + pmap_remove.9 pmap_remove_pages.9 +MLINKS+=pmap_resident_count.9 pmap_wired_count.9 +MLINKS+=pmap_zero_page.9 pmap_zero_area.9 \ + pmap_zero_page.9 pmap_zero_idle.9 +MLINKS+=printf.9 log.9 \ + printf.9 tprintf.9 \ + printf.9 uprintf.9 +MLINKS+=priv.9 priv_check.9 \ + priv.9 priv_check_cred.9 +MLINKS+=proc_rwmem.9 proc_readmem.9 \ + proc_rwmem.9 proc_writemem.9 +MLINKS+=psignal.9 gsignal.9 \ + psignal.9 pgsignal.9 \ + psignal.9 tdsignal.9 +MLINKS+=random.9 arc4rand.9 \ + random.9 arc4random.9 \ + random.9 read_random.9 \ + random.9 read_random_uio.9 \ + random.9 srandom.9 +MLINKS+=refcount.9 refcount_acquire.9 \ + refcount.9 refcount_init.9 \ + refcount.9 refcount_release.9 +MLINKS+=resource_int_value.9 resource_long_value.9 \ + resource_int_value.9 resource_string_value.9 +MLINKS+=rman.9 rman_activate_resource.9 \ + rman.9 rman_adjust_resource.9 \ + rman.9 rman_await_resource.9 \ + rman.9 rman_deactivate_resource.9 \ + rman.9 rman_fini.9 \ + rman.9 rman_first_free_region.9 \ + rman.9 rman_get_bushandle.9 \ + rman.9 rman_get_bustag.9 \ + rman.9 rman_get_device.9 \ + rman.9 rman_get_end.9 \ + rman.9 rman_get_flags.9 \ + rman.9 rman_get_rid.9 \ + rman.9 rman_get_size.9 \ + rman.9 rman_get_start.9 \ + rman.9 rman_get_virtual.9 \ + rman.9 rman_init.9 \ + rman.9 rman_init_from_resource.9 \ + rman.9 rman_is_region_manager.9 \ + rman.9 rman_last_free_region.9 \ + rman.9 rman_make_alignment_flags.9 \ + rman.9 rman_manage_region.9 \ + rman.9 rman_release_resource.9 \ + rman.9 rman_reserve_resource.9 \ + rman.9 rman_reserve_resource_bound.9 \ + rman.9 rman_set_bushandle.9 \ + rman.9 rman_set_bustag.9 \ + rman.9 rman_set_rid.9 \ + rman.9 rman_set_virtual.9 +MLINKS+=rmlock.9 rm_assert.9 \ + rmlock.9 rm_destroy.9 \ + rmlock.9 rm_init.9 \ + rmlock.9 rm_init_flags.9 \ + rmlock.9 rm_rlock.9 \ + rmlock.9 rm_runlock.9 \ + rmlock.9 rm_sleep.9 \ + rmlock.9 RM_SYSINIT.9 \ + rmlock.9 rm_try_rlock.9 \ + rmlock.9 rm_wlock.9 \ + rmlock.9 rm_wowned.9 \ + rmlock.9 rm_wunlock.9 +MLINKS+=rtalloc.9 rtalloc1.9 \ + rtalloc.9 rtalloc_ign.9 \ + rtalloc.9 RT_ADDREF.9 \ + rtalloc.9 RT_LOCK.9 \ + rtalloc.9 RT_REMREF.9 \ + rtalloc.9 RT_RTFREE.9 \ + rtalloc.9 RT_UNLOCK.9 \ + rtalloc.9 RTFREE_LOCKED.9 \ + rtalloc.9 RTFREE.9 \ + rtalloc.9 rtfree.9 \ + rtalloc.9 rtalloc1_fib.9 \ + rtalloc.9 rtalloc_ign_fib.9 \ + rtalloc.9 rtalloc_fib.9 +MLINKS+=runqueue.9 choosethread.9 \ + runqueue.9 procrunnable.9 \ + runqueue.9 remrunqueue.9 \ + runqueue.9 setrunqueue.9 +MLINKS+=rwlock.9 rw_assert.9 \ + rwlock.9 rw_destroy.9 \ + rwlock.9 rw_downgrade.9 \ + rwlock.9 rw_init.9 \ + rwlock.9 rw_init_flags.9 \ + rwlock.9 rw_initialized.9 \ + rwlock.9 rw_rlock.9 \ + rwlock.9 rw_runlock.9 \ + rwlock.9 rw_unlock.9 \ + rwlock.9 rw_sleep.9 \ + rwlock.9 RW_SYSINIT.9 \ + rwlock.9 rw_try_rlock.9 \ + rwlock.9 rw_try_upgrade.9 \ + rwlock.9 rw_try_wlock.9 \ + rwlock.9 rw_wlock.9 \ + rwlock.9 rw_wowned.9 \ + rwlock.9 rw_wunlock.9 +MLINKS+=sbuf.9 sbuf_bcat.9 \ + sbuf.9 sbuf_bcopyin.9 \ + sbuf.9 sbuf_bcpy.9 \ + sbuf.9 sbuf_cat.9 \ + sbuf.9 sbuf_clear.9 \ + sbuf.9 sbuf_copyin.9 \ + sbuf.9 sbuf_cpy.9 \ + sbuf.9 sbuf_data.9 \ + sbuf.9 sbuf_delete.9 \ + sbuf.9 sbuf_done.9 \ + sbuf.9 sbuf_error.9 \ + sbuf.9 sbuf_finish.9 \ + sbuf.9 sbuf_len.9 \ + sbuf.9 sbuf_new.9 \ + sbuf.9 sbuf_new_auto.9 \ + sbuf.9 sbuf_new_for_sysctl.9 \ + sbuf.9 sbuf_printf.9 \ + sbuf.9 sbuf_putc.9 \ + sbuf.9 sbuf_set_drain.9 \ + sbuf.9 sbuf_setpos.9 \ + sbuf.9 sbuf_start_section.9 \ + sbuf.9 sbuf_end_section.9 \ + sbuf.9 sbuf_trim.9 \ + sbuf.9 sbuf_vprintf.9 +MLINKS+=scheduler.9 curpriority_cmp.9 \ + scheduler.9 maybe_resched.9 \ + scheduler.9 propagate_priority.9 \ + scheduler.9 resetpriority.9 \ + scheduler.9 roundrobin.9 \ + scheduler.9 roundrobin_interval.9 \ + scheduler.9 schedclock.9 \ + scheduler.9 schedcpu.9 \ + scheduler.9 sched_setup.9 \ + scheduler.9 setrunnable.9 \ + scheduler.9 updatepri.9 +MLINKS+=SDT.9 SDT_PROVIDER_DECLARE.9 \ + SDT.9 SDT_PROVIDER_DEFINE.9 \ + SDT.9 SDT_PROBE_DECLARE.9 \ + SDT.9 SDT_PROBE_DEFINE.9 \ + SDT.9 SDT_PROBE.9 +MLINKS+=securelevel_gt.9 securelevel_ge.9 +MLINKS+=selrecord.9 seldrain.9 \ + selrecord.9 selwakeup.9 +MLINKS+=sema.9 sema_destroy.9 \ + sema.9 sema_init.9 \ + sema.9 sema_post.9 \ + sema.9 sema_timedwait.9 \ + sema.9 sema_trywait.9 \ + sema.9 sema_value.9 \ + sema.9 sema_wait.9 +MLINKS+=sf_buf.9 sf_buf_alloc.9 \ + sf_buf.9 sf_buf_free.9 \ + sf_buf.9 sf_buf_kva.9 \ + sf_buf.9 sf_buf_page.9 +MLINKS+=sglist.9 sglist_alloc.9 \ + sglist.9 sglist_append.9 \ + sglist.9 sglist_append_bio.9 \ + sglist.9 sglist_append_mbuf.9 \ + sglist.9 sglist_append_phys.9 \ + sglist.9 sglist_append_uio.9 \ + sglist.9 sglist_append_user.9 \ + sglist.9 sglist_build.9 \ + sglist.9 sglist_clone.9 \ + sglist.9 sglist_consume_uio.9 \ + sglist.9 sglist_count.9 \ + sglist.9 sglist_free.9 \ + sglist.9 sglist_hold.9 \ + sglist.9 sglist_init.9 \ + sglist.9 sglist_join.9 \ + sglist.9 sglist_length.9 \ + sglist.9 sglist_reset.9 \ + sglist.9 sglist_slice.9 \ + sglist.9 sglist_split.9 +MLINKS+=shm_map.9 shm_unmap.9 +MLINKS+=signal.9 cursig.9 \ + signal.9 execsigs.9 \ + signal.9 issignal.9 \ + signal.9 killproc.9 \ + signal.9 pgsigio.9 \ + signal.9 postsig.9 \ + signal.9 SETSETNEQ.9 \ + signal.9 SETSETOR.9 \ + signal.9 SIGADDSET.9 \ + signal.9 SIG_CONTSIGMASK.9 \ + signal.9 SIGDELSET.9 \ + signal.9 SIGEMPTYSET.9 \ + signal.9 sigexit.9 \ + signal.9 SIGFILLSET.9 \ + signal.9 siginit.9 \ + signal.9 SIGISEMPTY.9 \ + signal.9 SIGISMEMBER.9 \ + signal.9 SIGNOTEMPTY.9 \ + signal.9 signotify.9 \ + signal.9 SIGPENDING.9 \ + signal.9 SIGSETAND.9 \ + signal.9 SIGSETCANTMASK.9 \ + signal.9 SIGSETEQ.9 \ + signal.9 SIGSETNAND.9 \ + signal.9 SIG_STOPSIGMASK.9 \ + signal.9 trapsignal.9 +MLINKS+=sleep.9 msleep.9 \ + sleep.9 msleep_sbt.9 \ + sleep.9 msleep_spin.9 \ + sleep.9 msleep_spin_sbt.9 \ + sleep.9 pause.9 \ + sleep.9 pause_sbt.9 \ + sleep.9 tsleep.9 \ + sleep.9 tsleep_sbt.9 \ + sleep.9 wakeup.9 \ + sleep.9 wakeup_one.9 +MLINKS+=sleepqueue.9 init_sleepqueues.9 \ + sleepqueue.9 sleepq_abort.9 \ + sleepqueue.9 sleepq_add.9 \ + sleepqueue.9 sleepq_alloc.9 \ + sleepqueue.9 sleepq_broadcast.9 \ + sleepqueue.9 sleepq_free.9 \ + sleepqueue.9 sleepq_lookup.9 \ + sleepqueue.9 sleepq_lock.9 \ + sleepqueue.9 sleepq_release.9 \ + sleepqueue.9 sleepq_remove.9 \ + sleepqueue.9 sleepq_set_timeout.9 \ + sleepqueue.9 sleepq_set_timeout_sbt.9 \ + sleepqueue.9 sleepq_signal.9 \ + sleepqueue.9 sleepq_sleepcnt.9 \ + sleepqueue.9 sleepq_timedwait.9 \ + sleepqueue.9 sleepq_timedwait_sig.9 \ + sleepqueue.9 sleepq_type.9 \ + sleepqueue.9 sleepq_wait.9 \ + sleepqueue.9 sleepq_wait_sig.9 +MLINKS+=socket.9 soabort.9 \ + socket.9 soaccept.9 \ + socket.9 sobind.9 \ + socket.9 socheckuid.9 \ + socket.9 soclose.9 \ + socket.9 soconnect.9 \ + socket.9 socreate.9 \ + socket.9 sodisconnect.9 \ + socket.9 sodupsockaddr.9 \ + socket.9 sofree.9 \ + socket.9 sogetopt.9 \ + socket.9 sohasoutofband.9 \ + socket.9 solisten.9 \ + socket.9 solisten_proto.9 \ + socket.9 solisten_proto_check.9 \ + socket.9 sonewconn.9 \ + socket.9 sooptcopyin.9 \ + socket.9 sooptcopyout.9 \ + socket.9 sopoll.9 \ + socket.9 sopoll_generic.9 \ + socket.9 soreceive.9 \ + socket.9 soreceive_dgram.9 \ + socket.9 soreceive_generic.9 \ + socket.9 soreceive_stream.9 \ + socket.9 soreserve.9 \ + socket.9 sorflush.9 \ + socket.9 sosend.9 \ + socket.9 sosend_dgram.9 \ + socket.9 sosend_generic.9 \ + socket.9 sosetopt.9 \ + socket.9 soshutdown.9 \ + socket.9 sotoxsocket.9 \ + socket.9 soupcall_clear.9 \ + socket.9 soupcall_set.9 \ + socket.9 sowakeup.9 +MLINKS+=stack.9 stack_copy.9 \ + stack.9 stack_create.9 \ + stack.9 stack_destroy.9 \ + stack.9 stack_print.9 \ + stack.9 stack_print_ddb.9 \ + stack.9 stack_print_short.9 \ + stack.9 stack_print_short_ddb.9 \ + stack.9 stack_put.9 \ + stack.9 stack_save.9 \ + stack.9 stack_sbuf_print.9 \ + stack.9 stack_sbuf_print_ddb.9 \ + stack.9 stack_zero.9 +MLINKS+=store.9 subyte.9 \ + store.9 suswintr.9 \ + store.9 suword.9 \ + store.9 suword16.9 \ + store.9 suword32.9 \ + store.9 suword64.9 +MLINKS+=swi.9 swi_add.9 \ + swi.9 swi_remove.9 \ + swi.9 swi_sched.9 +MLINKS+=sx.9 sx_assert.9 \ + sx.9 sx_destroy.9 \ + sx.9 sx_downgrade.9 \ + sx.9 sx_init.9 \ + sx.9 sx_init_flags.9 \ + sx.9 sx_sleep.9 \ + sx.9 sx_slock.9 \ + sx.9 sx_slock_sig.9 \ + sx.9 sx_sunlock.9 \ + sx.9 SX_SYSINIT.9 \ + sx.9 sx_try_slock.9 \ + sx.9 sx_try_upgrade.9 \ + sx.9 sx_try_xlock.9 \ + sx.9 sx_unlock.9 \ + sx.9 sx_xholder.9 \ + sx.9 sx_xlock.9 \ + sx.9 sx_xlock_sig.9 \ + sx.9 sx_xlocked.9 \ + sx.9 sx_xunlock.9 +MLINKS+=sysctl.9 SYSCTL_DECL.9 \ + sysctl.9 SYSCTL_ADD_INT.9 \ + sysctl.9 SYSCTL_ADD_LONG.9 \ + sysctl.9 SYSCTL_ADD_NODE.9 \ + sysctl.9 SYSCTL_ADD_OPAQUE.9 \ + sysctl.9 SYSCTL_ADD_PROC.9 \ + sysctl.9 SYSCTL_ADD_QUAD.9 \ + sysctl.9 SYSCTL_ADD_ROOT_NODE.9 \ + sysctl.9 SYSCTL_ADD_S8.9 \ + sysctl.9 SYSCTL_ADD_S16.9 \ + sysctl.9 SYSCTL_ADD_S32.9 \ + sysctl.9 SYSCTL_ADD_S64.9 \ + sysctl.9 SYSCTL_ADD_STRING.9 \ + sysctl.9 SYSCTL_ADD_STRUCT.9 \ + sysctl.9 SYSCTL_ADD_U8.9 \ + sysctl.9 SYSCTL_ADD_U16.9 \ + sysctl.9 SYSCTL_ADD_U32.9 \ + sysctl.9 SYSCTL_ADD_U64.9 \ + sysctl.9 SYSCTL_ADD_UAUTO.9 \ + sysctl.9 SYSCTL_ADD_UINT.9 \ + sysctl.9 SYSCTL_ADD_ULONG.9 \ + sysctl.9 SYSCTL_ADD_UQUAD.9 \ + sysctl.9 SYSCTL_CHILDREN.9 \ + sysctl.9 SYSCTL_STATIC_CHILDREN.9 \ + sysctl.9 SYSCTL_NODE_CHILDREN.9 \ + sysctl.9 SYSCTL_PARENT.9 \ + sysctl.9 SYSCTL_INT.9 \ + sysctl.9 SYSCTL_LONG.9 \ + sysctl.9 SYSCTL_NODE.9 \ + sysctl.9 SYSCTL_OPAQUE.9 \ + sysctl.9 SYSCTL_PROC.9 \ + sysctl.9 SYSCTL_QUAD.9 \ + sysctl.9 SYSCTL_ROOT_NODE.9 \ + sysctl.9 SYSCTL_S8.9 \ + sysctl.9 SYSCTL_S16.9 \ + sysctl.9 SYSCTL_S32.9 \ + sysctl.9 SYSCTL_S64.9 \ + sysctl.9 SYSCTL_STRING.9 \ + sysctl.9 SYSCTL_STRUCT.9 \ + sysctl.9 SYSCTL_U8.9 \ + sysctl.9 SYSCTL_U16.9 \ + sysctl.9 SYSCTL_U32.9 \ + sysctl.9 SYSCTL_U64.9 \ + sysctl.9 SYSCTL_UINT.9 \ + sysctl.9 SYSCTL_ULONG.9 \ + sysctl.9 SYSCTL_UQUAD.9 +MLINKS+=sysctl_add_oid.9 sysctl_move_oid.9 \ + sysctl_add_oid.9 sysctl_remove_oid.9 \ + sysctl_add_oid.9 sysctl_remove_name.9 +MLINKS+=sysctl_ctx_init.9 sysctl_ctx_entry_add.9 \ + sysctl_ctx_init.9 sysctl_ctx_entry_del.9 \ + sysctl_ctx_init.9 sysctl_ctx_entry_find.9 \ + sysctl_ctx_init.9 sysctl_ctx_free.9 +MLINKS+=SYSINIT.9 SYSUNINIT.9 +MLINKS+=taskqueue.9 TASK_INIT.9 \ + taskqueue.9 TASK_INITIALIZER.9 \ + taskqueue.9 taskqueue_block.9 \ + taskqueue.9 taskqueue_cancel.9 \ + taskqueue.9 taskqueue_cancel_timeout.9 \ + taskqueue.9 taskqueue_create.9 \ + taskqueue.9 taskqueue_create_fast.9 \ + taskqueue.9 TASKQUEUE_DECLARE.9 \ + taskqueue.9 TASKQUEUE_DEFINE.9 \ + taskqueue.9 TASKQUEUE_DEFINE_THREAD.9 \ + taskqueue.9 taskqueue_drain.9 \ + taskqueue.9 taskqueue_drain_all.9 \ + taskqueue.9 taskqueue_drain_timeout.9 \ + taskqueue.9 taskqueue_enqueue.9 \ + taskqueue.9 taskqueue_enqueue_fast.9 \ + taskqueue.9 taskqueue_enqueue_timeout.9 \ + taskqueue.9 TASKQUEUE_FAST_DEFINE.9 \ + taskqueue.9 TASKQUEUE_FAST_DEFINE_THREAD.9 \ + taskqueue.9 taskqueue_free.9 \ + taskqueue.9 taskqueue_member.9 \ + taskqueue.9 taskqueue_run.9 \ + taskqueue.9 taskqueue_set_callback.9 \ + taskqueue.9 taskqueue_start_threads.9 \ + taskqueue.9 taskqueue_start_threads_pinned.9 \ + taskqueue.9 taskqueue_unblock.9 \ + taskqueue.9 TIMEOUT_TASK_INIT.9 +MLINKS+=time.9 boottime.9 \ + time.9 time_second.9 \ + time.9 time_uptime.9 +MLINKS+=timeout.9 callout.9 \ + timeout.9 callout_active.9 \ + timeout.9 callout_async_drain.9 \ + timeout.9 callout_deactivate.9 \ + timeout.9 callout_drain.9 \ + timeout.9 callout_handle_init.9 \ + timeout.9 callout_init.9 \ + timeout.9 callout_init_mtx.9 \ + timeout.9 callout_init_rm.9 \ + timeout.9 callout_init_rw.9 \ + timeout.9 callout_pending.9 \ + timeout.9 callout_reset.9 \ + timeout.9 callout_reset_curcpu.9 \ + timeout.9 callout_reset_on.9 \ + timeout.9 callout_reset_sbt.9 \ + timeout.9 callout_reset_sbt_curcpu.9 \ + timeout.9 callout_reset_sbt_on.9 \ + timeout.9 callout_schedule.9 \ + timeout.9 callout_schedule_curcpu.9 \ + timeout.9 callout_schedule_on.9 \ + timeout.9 callout_schedule_sbt.9 \ + timeout.9 callout_schedule_sbt_curcpu.9 \ + timeout.9 callout_schedule_sbt_on.9 \ + timeout.9 callout_stop.9 \ + timeout.9 untimeout.9 +MLINKS+=ucred.9 cred_update_thread.9 \ + ucred.9 crcopy.9 \ + ucred.9 crcopysafe.9 \ + ucred.9 crdup.9 \ + ucred.9 crfree.9 \ + ucred.9 crget.9 \ + ucred.9 crhold.9 \ + ucred.9 crsetgroups.9 \ + ucred.9 crshared.9 \ + ucred.9 cru2x.9 +MLINKS+=uidinfo.9 uifind.9 \ + uidinfo.9 uifree.9 \ + uidinfo.9 uihashinit.9 \ + uidinfo.9 uihold.9 +MLINKS+=uio.9 uiomove.9 \ + uio.9 uiomove_nofault.9 + +.if ${MK_USB} != "no" +MAN+= usbdi.9 +MLINKS+=usbdi.9 usbd_do_request.9 \ + usbdi.9 usbd_do_request_flags.9 \ + usbdi.9 usbd_errstr.9 \ + usbdi.9 usbd_lookup_id_by_info.9 \ + usbdi.9 usbd_lookup_id_by_uaa.9 \ + usbdi.9 usbd_transfer_clear_stall.9 \ + usbdi.9 usbd_transfer_drain.9 \ + usbdi.9 usbd_transfer_pending.9 \ + usbdi.9 usbd_transfer_poll.9 \ + usbdi.9 usbd_transfer_setup.9 \ + usbdi.9 usbd_transfer_start.9 \ + usbdi.9 usbd_transfer_stop.9 \ + usbdi.9 usbd_transfer_submit.9 \ + usbdi.9 usbd_transfer_unsetup.9 \ + usbdi.9 usbd_xfer_clr_flag.9 \ + usbdi.9 usbd_xfer_frame_data.9 \ + usbdi.9 usbd_xfer_frame_len.9 \ + usbdi.9 usbd_xfer_get_frame.9 \ + usbdi.9 usbd_xfer_get_priv.9 \ + usbdi.9 usbd_xfer_is_stalled.9 \ + usbdi.9 usbd_xfer_max_framelen.9 \ + usbdi.9 usbd_xfer_max_frames.9 \ + usbdi.9 usbd_xfer_max_len.9 \ + usbdi.9 usbd_xfer_set_flag.9 \ + usbdi.9 usbd_xfer_set_frame_data.9 \ + usbdi.9 usbd_xfer_set_frame_len.9 \ + usbdi.9 usbd_xfer_set_frame_offset.9 \ + usbdi.9 usbd_xfer_set_frames.9 \ + usbdi.9 usbd_xfer_set_interval.9 \ + usbdi.9 usbd_xfer_set_priv.9 \ + usbdi.9 usbd_xfer_set_stall.9 \ + usbdi.9 usbd_xfer_set_timeout.9 \ + usbdi.9 usbd_xfer_softc.9 \ + usbdi.9 usbd_xfer_state.9 \ + usbdi.9 usbd_xfer_status.9 \ + usbdi.9 usb_fifo_alloc_buffer.9 \ + usbdi.9 usb_fifo_attach.9 \ + usbdi.9 usb_fifo_detach.9 \ + usbdi.9 usb_fifo_free_buffer.9 \ + usbdi.9 usb_fifo_get_data.9 \ + usbdi.9 usb_fifo_get_data_buffer.9 \ + usbdi.9 usb_fifo_get_data_error.9 \ + usbdi.9 usb_fifo_get_data_linear.9 \ + usbdi.9 usb_fifo_put_bytes_max.9 \ + usbdi.9 usb_fifo_put_data.9 \ + usbdi.9 usb_fifo_put_data_buffer.9 \ + usbdi.9 usb_fifo_put_data_error.9 \ + usbdi.9 usb_fifo_put_data_linear.9 \ + usbdi.9 usb_fifo_reset.9 \ + usbdi.9 usb_fifo_softc.9 \ + usbdi.9 usb_fifo_wakeup.9 +.endif +MLINKS+=vcount.9 count_dev.9 +MLINKS+=vfsconf.9 vfs_modevent.9 \ + vfsconf.9 vfs_register.9 \ + vfsconf.9 vfs_unregister.9 +MLINKS+=vfs_getopt.9 vfs_copyopt.9 \ + vfs_getopt.9 vfs_filteropt.9 \ + vfs_getopt.9 vfs_flagopt.9 \ + vfs_getopt.9 vfs_getopts.9 \ + vfs_getopt.9 vfs_scanopt.9 \ + vfs_getopt.9 vfs_setopt.9 \ + vfs_getopt.9 vfs_setopt_part.9 \ + vfs_getopt.9 vfs_setopts.9 +MLINKS+=vhold.9 vdrop.9 \ + vhold.9 vdropl.9 \ + vhold.9 vholdl.9 +MLINKS+=vmem.9 vmem_add.9 \ + vmem.9 vmem_alloc.9 \ + vmem.9 vmem_create.9 \ + vmem.9 vmem_destroy.9 \ + vmem.9 vmem_free.9 \ + vmem.9 vmem_xalloc.9 \ + vmem.9 vmem_xfree.9 +MLINKS+=vm_map_lock.9 vm_map_lock_downgrade.9 \ + vm_map_lock.9 vm_map_lock_read.9 \ + vm_map_lock.9 vm_map_lock_upgrade.9 \ + vm_map_lock.9 vm_map_trylock.9 \ + vm_map_lock.9 vm_map_trylock_read.9 \ + vm_map_lock.9 vm_map_unlock.9 \ + vm_map_lock.9 vm_map_unlock_read.9 +MLINKS+=vm_map_lookup.9 vm_map_lookup_done.9 +MLINKS+=vm_map_max.9 vm_map_min.9 \ + vm_map_max.9 vm_map_pmap.9 +MLINKS+=vm_map_stack.9 vm_map_growstack.9 +MLINKS+=vm_map_wire.9 vm_map_unwire.9 +MLINKS+=vm_page_bits.9 vm_page_clear_dirty.9 \ + vm_page_bits.9 vm_page_dirty.9 \ + vm_page_bits.9 vm_page_is_valid.9 \ + vm_page_bits.9 vm_page_set_invalid.9 \ + vm_page_bits.9 vm_page_set_validclean.9 \ + vm_page_bits.9 vm_page_test_dirty.9 \ + vm_page_bits.9 vm_page_undirty.9 \ + vm_page_bits.9 vm_page_zero_invalid.9 +MLINKS+=vm_page_busy.9 vm_page_busied.9 \ + vm_page_busy.9 vm_page_busy_downgrade.9 \ + vm_page_busy.9 vm_page_busy_sleep.9 \ + vm_page_busy.9 vm_page_sbusied.9 \ + vm_page_busy.9 vm_page_sbusy.9 \ + vm_page_busy.9 vm_page_sleep_if_busy.9 \ + vm_page_busy.9 vm_page_sunbusy.9 \ + vm_page_busy.9 vm_page_trysbusy.9 \ + vm_page_busy.9 vm_page_tryxbusy.9 \ + vm_page_busy.9 vm_page_xbusied.9 \ + vm_page_busy.9 vm_page_xbusy.9 \ + vm_page_busy.9 vm_page_xunbusy.9 \ + vm_page_busy.9 vm_page_assert_sbusied.9 \ + vm_page_busy.9 vm_page_assert_unbusied.9 \ + vm_page_busy.9 vm_page_assert_xbusied.9 +MLINKS+=vm_page_aflag.9 vm_page_aflag_clear.9 \ + vm_page_aflag.9 vm_page_aflag_set.9 \ + vm_page_aflag.9 vm_page_reference.9 +MLINKS+=vm_page_free.9 vm_page_free_toq.9 \ + vm_page_free.9 vm_page_free_zero.9 \ + vm_page_free.9 vm_page_try_to_free.9 +MLINKS+=vm_page_hold.9 vm_page_unhold.9 +MLINKS+=vm_page_insert.9 vm_page_remove.9 +MLINKS+=vm_page_wire.9 vm_page_unwire.9 +MLINKS+=VOP_ACCESS.9 VOP_ACCESSX.9 +MLINKS+=VOP_ATTRIB.9 VOP_GETATTR.9 \ + VOP_ATTRIB.9 VOP_SETATTR.9 +MLINKS+=VOP_CREATE.9 VOP_MKDIR.9 \ + VOP_CREATE.9 VOP_MKNOD.9 \ + VOP_CREATE.9 VOP_SYMLINK.9 +MLINKS+=VOP_GETPAGES.9 VOP_PUTPAGES.9 +MLINKS+=VOP_INACTIVE.9 VOP_RECLAIM.9 +MLINKS+=VOP_LOCK.9 vn_lock.9 \ + VOP_LOCK.9 VOP_ISLOCKED.9 \ + VOP_LOCK.9 VOP_UNLOCK.9 +MLINKS+=VOP_OPENCLOSE.9 VOP_CLOSE.9 \ + VOP_OPENCLOSE.9 VOP_OPEN.9 +MLINKS+=VOP_RDWR.9 VOP_READ.9 \ + VOP_RDWR.9 VOP_WRITE.9 +MLINKS+=VOP_REMOVE.9 VOP_RMDIR.9 +MLINKS+=vnet.9 vimage.9 +MLINKS+=vref.9 VREF.9 +MLINKS+=vrele.9 vput.9 \ + vrele.9 vunref.9 +MLINKS+=vslock.9 vsunlock.9 +MLINKS+=zone.9 uma.9 \ + zone.9 uma_find_refcnt.9 \ + zone.9 uma_zalloc.9 \ + zone.9 uma_zalloc_arg.9 \ + zone.9 uma_zcreate.9 \ + zone.9 uma_zdestroy.9 \ + zone.9 uma_zfree.9 \ + zone.9 uma_zfree_arg.9 \ + zone.9 uma_zone_get_cur.9 \ + zone.9 uma_zone_get_max.9 \ + zone.9 uma_zone_set_max.9 \ + zone.9 uma_zone_set_warning.9 \ + zone.9 uma_zone_set_maxaction.9 + +.include Property changes on: user/imp/camdoc/Makefile ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/make_dev.9 =================================================================== --- user/imp/camdoc/make_dev.9 (nonexistent) +++ user/imp/camdoc/make_dev.9 (revision 296049) @@ -0,0 +1,493 @@ +.\" Copyright (c) 1999 Chris Costello +.\" 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 Jan 3, 2016 +.Dt MAKE_DEV 9 +.Os +.Sh NAME +.Nm make_dev , +.Nm make_dev_cred , +.Nm make_dev_credf , +.Nm make_dev_p , +.Nm make_dev_s , +.Nm make_dev_alias , +.Nm make_dev_alias_p , +.Nm destroy_dev , +.Nm destroy_dev_sched , +.Nm destroy_dev_sched_cb , +.Nm destroy_dev_drain , +.Nm dev_depends +.Nd manage +.Vt cdev Ns 's +and DEVFS registration for devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft void +.Fn make_dev_args_init "struct make_dev_args *args" +.Ft int +.Fn make_dev_s "struct make_dev_args *args" "struct cdev **cdev" "const char *fmt" ... +.Ft int +.Fn make_dev_alias_p "int flags" "struct cdev **cdev" "struct cdev *pdev" "const char *fmt" ... +.Ft void +.Fn destroy_dev "struct cdev *dev" +.Ft void +.Fn destroy_dev_sched "struct cdev *dev" +.Ft void +.Fn destroy_dev_sched_cb "struct cdev *dev" "void (*cb)(void *)" "void *arg" +.Ft void +.Fn destroy_dev_drain "struct cdevsw *csw" +.Ft void +.Fn dev_depends "struct cdev *pdev" "struct cdev *cdev" +.Pp +LEGACY INTERFACES +.Ft struct cdev * +.Fn make_dev "struct cdevsw *cdevsw" "int unit" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_cred "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_credf "int flags" "struct cdevsw *cdevsw" "int unit" "struct ucred *cr" "uid_t uid" "gid_t gid" "int perms" "const char *fmt" ... +.Ft int +.Fn make_dev_p "int flags" "struct cdev **cdev" "struct cdevsw *devsw" "struct ucred *cr" "uid_t uid" "gid_t gid" "int mode" "const char *fmt" ... +.Ft struct cdev * +.Fn make_dev_alias "struct cdev *pdev" "const char *fmt" ... +.Sh DESCRIPTION +The +.Fn make_dev_s +function creates a +.Fa cdev +structure for a new device, which is returned into the +.Fa cdev +argument. +It also notifies +.Xr devfs 5 +of the presence of the new device, that causes corresponding nodes +to be created. +Besides this, a +.Xr devctl 4 +notification is sent. +The function takes the structure +.Va struct make_dev_args args , +which specifies the parameters for the device creation: +.Pp +.Bd -literal -offset indent -compact +struct make_dev_args { + size_t mda_size; + int mda_flags; + struct cdevsw *mda_devsw; + struct ucred *mda_cr; + uid_t mda_uid; + gid_t mda_gid; + int mda_mode; + int mda_unit; + void *mda_si_drv1; + void *mda_si_drv2; +}; +.Ed +Before use and filling with the desired values, the structure must be +initialized by the +.Fn make_dev_args_init +function, which ensures that future kernel interface expansion does +not affect driver source code or binary interface. +.Pp +The created device will be owned by +.Va args.mda_uid , +with the group ownership as +.Va args.mda_gid . +The name is the expansion of +.Va fmt +and following arguments as +.Xr printf 9 +would print it. +The name determines its path under +.Pa /dev +or other +.Xr devfs 5 +mount point and may contain slash +.Ql / +characters to denote subdirectories. +The permissions of the file specified in +.Va args.mda_mode +are defined in +.In sys/stat.h : +.Pp +.Bd -literal -offset indent -compact +#define S_IRWXU 0000700 /* RWX mask for owner */ +#define S_IRUSR 0000400 /* R for owner */ +#define S_IWUSR 0000200 /* W for owner */ +#define S_IXUSR 0000100 /* X for owner */ + +#define S_IRWXG 0000070 /* RWX mask for group */ +#define S_IRGRP 0000040 /* R for group */ +#define S_IWGRP 0000020 /* W for group */ +#define S_IXGRP 0000010 /* X for group */ + +#define S_IRWXO 0000007 /* RWX mask for other */ +#define S_IROTH 0000004 /* R for other */ +#define S_IWOTH 0000002 /* W for other */ +#define S_IXOTH 0000001 /* X for other */ + +#define S_ISUID 0004000 /* set user id on execution */ +#define S_ISGID 0002000 /* set group id on execution */ +#define S_ISVTX 0001000 /* sticky bit */ +#ifndef _POSIX_SOURCE +#define S_ISTXT 0001000 +#endif +.Ed +.Pp +The +.Va args.mda_cr +argument specifies credentials that will be stored in the +.Fa si_cred +member of the initialized +.Fa struct cdev . +.Pp +The +.Va args.mda_flags +argument alters the operation of +.Fn make_dev_s. +The following values are currently accepted: +.Pp +.Bl -tag -width "It Dv MAKEDEV_CHECKNAME" -compact -offset indent +.It Dv MAKEDEV_REF +reference the created device +.It Dv MAKEDEV_NOWAIT +do not sleep, the call may fail +.It Dv MAKEDEV_WAITOK +allow the function to sleep to satisfy malloc +.It Dv MAKEDEV_ETERNAL +created device will be never destroyed +.It Dv MAKEDEV_CHECKNAME +return an error if the device name is invalid or already exists +.El +.Pp +Only +.Dv MAKEDEV_NOWAIT , +.Dv MAKEDEV_WAITOK +and +.Dv MAKEDEV_CHECKNAME +values are accepted for the +.Fn make_dev_alias_p +function. +.Pp +The +.Dv MAKEDEV_WAITOK +flag is assumed if none of +.Dv MAKEDEV_WAITOK , +.Dv MAKEDEV_NOWAIT +is specified. +.Pp +The +.Xr dev_clone 9 +event handler shall specify +.Dv MAKEDEV_REF +flag when creating a device in response to lookup, to avoid race where +the device created is destroyed immediately after +.Xr devfs_lookup 9 +drops his reference to cdev. +.Pp +The +.Dv MAKEDEV_ETERNAL +flag allows the kernel to not acquire some locks when translating system +calls into the cdevsw methods calls. +It is responsibility of the driver author to make sure that +.Fn destroy_dev +is never called on the returned cdev. +For the convenience, use the +.Dv MAKEDEV_ETERNAL_KLD +flag for the code that can be compiled into kernel or loaded +(and unloaded) as loadable module. +.Pp +A panic will occur if the +.Dv MAKEDEV_CHECKNAME +flag is not specified +and the device name is invalid or already exists. +.Pp +The +.Fn make_dev_p +use of the form +.Bd -literal -offset indent +struct cdev *dev; +int res; +res = make_dev_p(flags, &dev, cdevsw, cred, uid, gid, perms, name); +.Ed +is equivalent to the code +.Bd -literal -offset indent +struct cdev *dev; +struct make_dev_args args; +int res; + +make_dev_args_init(&args); +args.mda_flags = flags; +args.mda_devsw = cdevsw; +args.mda_cred = cred; +args.mda_uid = uid; +args.mda_gid = gid; +args.mda_mode = perms; +res = make_dev_s(&args, &dev, name); +.Ed +.Pp +Similarly, the +.Fn make_dev_credf +function call is equivalent to +.Bd -literal -offset indent + (void) make_dev_s(&args, &dev, name); +.Ed +In other words, +.Fn make_dev_credf +does not allow the caller to obtain the return value, and in +kernels compiled with the +.Va INVARIANTS +options, the function asserts that the device creation succeeded. +.Pp +The +.Fn make_dev_cred +function is equivalent to the call +.Bd -literal -offset indent +make_dev_credf(0, cdevsw, unit, cr, uid, gid, perms, fmt, ...); +.Ed +.Pp +The +.Fn make_dev +function call is the same as +.Bd -literal -offset indent +make_dev_credf(0, cdevsw, unit, NULL, uid, gid, perms, fmt, ...); +.Ed +.Pp +The +.Fn make_dev_alias_p +function takes the returned +.Ft cdev +from +.Fn make_dev +and makes another (aliased) name for this device. +It is an error to call +.Fn make_dev_alias_p +prior to calling +.Fn make_dev . +.Pp +The +.Fn make_dev_alias +function is similar to +.Fn make_dev_alias +but it returns the resulting aliasing +.Ft *cdev +and may not return an error. +.Pp +The +.Fa cdev +returned by +.Fn make_dev_s +and +.Fn make_dev_alias_p +has two fields, +.Fa si_drv1 +and +.Fa si_drv2 , +that are available to store state. +Both fields are of type +.Ft void * , +and can be initialized simultaneously with the +.Va cdev +allocation by filling +.Va args.mda_si_drv1 +and +.Va args.mda_si_drv2 +members of the +.Fn make_dev_s +argument structure, or filled after the +.Va cdev +is allocated, if using legacy interfaces. +In the latter case, the driver should handle the race of +accessing uninitialized +.Va si_drv1 +and +.Va si_drv2 +itself. +These are designed to replace the +.Fa unit +argument to +.Fn make_dev , +which can be obtained with +.Fn dev2unit . +.Pp +The +.Fn destroy_dev +function takes the returned +.Fa cdev +from +.Fn make_dev +and destroys the registration for that device. +The notification is sent to +.Xr devctl 4 +about the destruction event. +Do not call +.Fn destroy_dev +on devices that were created with +.Fn make_dev_alias . +.Pp +The +.Fn dev_depends +function establishes a parent-child relationship between two devices. +The net effect is that a +.Fn destroy_dev +of the parent device will also result in the destruction of the +child device(s), +if any exist. +A device may simultaneously be a parent and a child, +so it is possible to build a complete hierarchy. +.Pp +The +.Fn destroy_dev_sched_cb +function schedules execution of the +.Fn destroy_dev +for the specified +.Fa cdev +in the safe context. +After +.Fn destroy_dev +is finished, and if the supplied +.Fa cb +is not +.Dv NULL , +the callback +.Fa cb +is called, with argument +.Fa arg . +The +.Fn destroy_dev_sched +function is the same as +.Bd -literal -offset indent +destroy_dev_sched_cb(cdev, NULL, NULL); +.Ed +.Pp +The +.Fn d_close +driver method cannot call +.Fn destroy_dev +directly. +Doing so causes deadlock when +.Fn destroy_dev +waits for all threads to leave the driver methods. +Also, because +.Fn destroy_dev +sleeps, no non-sleepable locks may be held over the call. +The +.Fn destroy_dev_sched +family of functions overcome these issues. +.Pp +The device driver may call the +.Fn destroy_dev_drain +function to wait until all devices that have supplied +.Fa csw +as cdevsw, are destroyed. +This is useful when driver knows that +.Fn destroy_dev_sched +is called for all instantiated devices, but need to postpone module +unload until +.Fn destroy_dev +is actually finished for all of them. +.Sh RETURN VALUES +If successful, +.Fn make_dev_s +and +.Fn make_dev_p +will return 0, otherwise they will return an error. +If successful, +.Fn make_dev_credf +will return a valid +.Fa cdev +pointer, otherwise it will return +.Dv NULL . +.Sh ERRORS +The +.Fn make_dev_s , +.Fn make_dev_p +and +.Fn make_dev_alias_p +calls will fail and the device will be not registered if: +.Bl -tag -width Er +.It Bq Er ENOMEM +The +.Dv MAKEDEV_NOWAIT +flag was specified and a memory allocation request could not be satisfied. +.It Bq Er ENAMETOOLONG +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name is longer than +.Dv SPECNAMELEN . +.It Bq Er EINVAL +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name is empty, contains a +.Qq \&. +or +.Qq .. +path component or ends with +.Ql / . +.It Bq Er EINVAL +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name contains invalid characters. +.It Bq Er EEXIST +The +.Dv MAKEDEV_CHECKNAME +flag was specified and the provided device name already exists. +.El +.Sh SEE ALSO +.Xr devctl 4 , +.Xr devfs 5 , +.Xr destroy_dev_drain 9 , +.Xr dev_clone 9 +.Sh HISTORY +The +.Fn make_dev +and +.Fn destroy_dev +functions first appeared in +.Fx 4.0 . +The function +.Fn make_dev_alias +first appeared in +.Fx 4.1 . +The function +.Fn dev_depends +first appeared in +.Fx 5.0 . +The functions +.Fn make_dev_credf , +.Fn destroy_dev_sched , +.Fn destroy_dev_sched_cb +first appeared in +.Fx 7.0 . +The function +.Fn make_dev_p +first appeared in +.Fx 8.2 . +The function +.Fn make_dev_s +first appeared in +.Fx 11.0 . Property changes on: user/imp/camdoc/make_dev.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pci.9 =================================================================== --- user/imp/camdoc/pci.9 (nonexistent) +++ user/imp/camdoc/pci.9 (revision 296049) @@ -0,0 +1,904 @@ +.\" +.\" Copyright (c) 2005 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 December 23, 2015 +.Dt PCI 9 +.Os +.Sh NAME +.Nm pci , +.Nm pci_alloc_msi , +.Nm pci_alloc_msix , +.Nm pci_disable_busmaster , +.Nm pci_disable_io , +.Nm pci_enable_busmaster , +.Nm pci_enable_io , +.Nm pci_find_bsf , +.Nm pci_find_cap , +.Nm pci_find_dbsf , +.Nm pci_find_device , +.Nm pci_find_extcap , +.Nm pci_find_htcap , +.Nm pci_find_pcie_root_port , +.Nm pci_get_max_read_req , +.Nm pci_get_powerstate , +.Nm pci_get_vpd_ident , +.Nm pci_get_vpd_readonly , +.Nm pci_iov_attach , +.Nm pci_iov_detach , +.Nm pci_msi_count , +.Nm pci_msix_count , +.Nm pci_msix_pba_bar , +.Nm pci_msix_table_bar , +.Nm pci_pending_msix , +.Nm pci_read_config , +.Nm pci_release_msi , +.Nm pci_remap_msix , +.Nm pci_restore_state , +.Nm pci_save_state , +.Nm pci_set_max_read_req , +.Nm pci_set_powerstate , +.Nm pci_write_config , +.Nm pcie_adjust_config , +.Nm pcie_read_config , +.Nm pcie_write_config +.Nd PCI bus interface +.Sh SYNOPSIS +.In sys/bus.h +.In dev/pci/pcireg.h +.In dev/pci/pcivar.h +.Ft int +.Fn pci_alloc_msi "device_t dev" "int *count" +.Ft int +.Fn pci_alloc_msix "device_t dev" "int *count" +.Ft int +.Fn pci_disable_busmaster "device_t dev" +.Ft int +.Fn pci_disable_io "device_t dev" "int space" +.Ft int +.Fn pci_enable_busmaster "device_t dev" +.Ft int +.Fn pci_enable_io "device_t dev" "int space" +.Ft device_t +.Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" +.Ft int +.Fn pci_find_cap "device_t dev" "int capability" "int *capreg" +.Ft device_t +.Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func" +.Ft device_t +.Fn pci_find_device "uint16_t vendor" "uint16_t device" +.Ft int +.Fn pci_find_extcap "device_t dev" "int capability" "int *capreg" +.Ft int +.Fn pci_find_htcap "device_t dev" "int capability" "int *capreg" +.Ft device_t +.Fn pci_find_pcie_root_port "device_t dev" +.Ft int +.Fn pci_get_max_read_req "device_t dev" +.Ft int +.Fn pci_get_powerstate "device_t dev" +.Ft int +.Fn pci_get_vpd_ident "device_t dev" "const char **identptr" +.Ft int +.Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr" +.Ft int +.Fn pci_msi_count "device_t dev" +.Ft int +.Fn pci_msix_count "device_t dev" +.Ft int +.Fn pci_msix_pba_bar "device_t dev" +.Ft int +.Fn pci_msix_table_bar "device_t dev" +.Ft int +.Fn pci_pending_msix "device_t dev" "u_int index" +.Ft uint32_t +.Fn pci_read_config "device_t dev" "int reg" "int width" +.Ft int +.Fn pci_release_msi "device_t dev" +.Ft int +.Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors" +.Ft void +.Fn pci_restore_state "device_t dev" +.Ft void +.Fn pci_save_state "device_t dev" +.Ft int +.Fn pci_set_max_read_req "device_t dev" "int size" +.Ft int +.Fn pci_set_powerstate "device_t dev" "int state" +.Ft void +.Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" +.Ft uint32_t +.Fo pcie_adjust_config +.Fa "device_t dev" +.Fa "int reg" +.Fa "uint32_t mask" +.Fa "uint32_t val" +.Fa "int width" +.Fc +.Ft uint32_t +.Fn pcie_read_config "device_t dev" "int reg" "int width" +.Ft void +.Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width" +.In dev/pci/pci_iov.h +.Ft int +.Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema" +.Ft int +.Fn pci_iov_detach "device_t dev" +.Sh DESCRIPTION +The +.Nm +set of functions are used for managing PCI devices. +The functions are split into several groups: +raw configuration access, +locating devices, +device information, +device configuration, +and +message signaled interrupts. +.Ss Raw Configuration Access +The +.Fn pci_read_config +function is used to read data from the PCI configuration +space of the device +.Fa dev , +at offset +.Fa reg , +with +.Fa width +specifying the size of the access. +.Pp +The +.Fn pci_write_config +function is used to write the value +.Fa val +to the PCI configuration +space of the device +.Fa dev , +at offset +.Fa reg , +with +.Fa width +specifying the size of the access. +.Pp +The +.Fn pcie_adjust_config +function is used to modify the value of a register in the PCI-express +capability register set of device +.Fa dev . +The offset +.Fa reg +specifies a relative offset in the register set with +.Fa width +specifying the size of the access. +The new value of the register is computed by modifying bits set in +.Fa mask +to the value in +.Fa val . +Any bits not specified in +.Fa mask +are preserved. +The previous value of the register is returned. +.Pp +The +.Fn pcie_read_config +function is used to read the value of a register in the PCI-express +capability register set of device +.Fa dev . +The offset +.Fa reg +specifies a relative offset in the register set with +.Fa width +specifying the size of the access. +.Pp +The +.Fn pcie_write_config +function is used to write the value +.Fa val +to a register in the PCI-express capability register set of device +.Fa dev . +The offset +.Fa reg +specifies a relative offset in the register set with +.Fa width +specifying the size of the access. +.Pp +.Em NOTE : +Device drivers should only use these functions for functionality that +is not available via another +.Fn pci +function. +.Ss Locating Devices +The +.Fn pci_find_bsf +function looks up the +.Vt device_t +of a PCI device, given its +.Fa bus , +.Fa slot , +and +.Fa func . +The +.Fa slot +number actually refers to the number of the device on the bus, +which does not necessarily indicate its geographic location +in terms of a physical slot. +Note that in case the system has multiple PCI domains, +the +.Fn pci_find_bsf +function only searches the first one. +Actually, it is equivalent to: +.Bd -literal -offset indent +pci_find_dbsf(0, bus, slot, func); +.Ed +.Pp +The +.Fn pci_find_dbsf +function looks up the +.Vt device_t +of a PCI device, given its +.Fa domain , +.Fa bus , +.Fa slot , +and +.Fa func . +The +.Fa slot +number actually refers to the number of the device on the bus, +which does not necessarily indicate its geographic location +in terms of a physical slot. +.Pp +The +.Fn pci_find_device +function looks up the +.Vt device_t +of a PCI device, given its +.Fa vendor +and +.Fa device +IDs. +Note that there can be multiple matches for this search; this function +only returns the first matching device. +.Ss Device Information +The +.Fn pci_find_cap +function is used to locate the first instance of a PCI capability +register set for the device +.Fa dev . +The capability to locate is specified by ID via +.Fa capability . +Constant macros of the form +.Dv PCIY_xxx +for standard capability IDs are defined in +.In dev/pci/pcireg.h . +If the capability is found, then +.Fa *capreg +is set to the offset in configuration space of the capability register set, +and +.Fn pci_find_cap +returns zero. +If the capability is not found or the device does not support capabilities, +.Fn pci_find_cap +returns an error. +.Pp +The +.Fn pci_find_extcap +function is used to locate the first instance of a PCI-express +extended capability register set for the device +.Fa dev . +The extended capability to locate is specified by ID via +.Fa capability . +Constant macros of the form +.Dv PCIZ_xxx +for standard extended capability IDs are defined in +.In dev/pci/pcireg.h . +If the extended capability is found, then +.Fa *capreg +is set to the offset in configuration space of the extended capability +register set, and +.Fn pci_find_extcap +returns zero. +If the extended capability is not found or the device is not a +PCI-express device, +.Fn pci_find_extcap +returns an error. +.Pp +The +.Fn pci_find_htcap +function is used to locate the first instance of a HyperTransport capability +register set for the device +.Fa dev . +The capability to locate is specified by type via +.Fa capability . +Constant macros of the form +.Dv PCIM_HTCAP_xxx +for standard HyperTransport capability types are defined in +.In dev/pci/pcireg.h . +If the capability is found, then +.Fa *capreg +is set to the offset in configuration space of the capability register set, +and +.Fn pci_find_htcap +returns zero. +If the capability is not found or the device is not a HyperTransport device, +.Fn pci_find_htcap +returns an error. +.Pp +The +.Fn pci_find_pcie_root_port +function walks up the PCI device hierarchy to locate the PCI-express root +port upstream of +.Fa dev . +If a root port is not found, +.Fn pci_find_pcie_root_port +returns +.Dv NULL . +.Pp +The +.Fn pci_get_vpd_ident +function is used to fetch a device's Vital Product Data +.Pq VPD +identifier string. +If the device +.Fa dev +supports VPD and provides an identifier string, +then +.Fa *identptr +is set to point at a read-only, null-terminated copy of the identifier +string, +and +.Fn pci_get_vpd_ident +returns zero. +If the device does not support VPD or does not provide an identifier +string, +then +.Fn pci_get_vpd_ident +returns an error. +.Pp +The +.Fn pci_get_vpd_readonly +function is used to fetch the value of a single VPD read-only keyword +for the device +.Fa dev . +The keyword to fetch is identified by the two character string +.Fa kw . +If the device supports VPD and provides a read-only value for the +requested keyword, +then +.Fa *vptr +is set to point at a read-only, null-terminated copy of the value, +and +.Fn pci_get_vpd_readonly +returns zero. +If the device does not support VPD or does not provide the requested +keyword, +then +.Fn pci_get_vpd_readonly +returns an error. +.Ss Device Configuration +The +.Fn pci_enable_busmaster +function enables PCI bus mastering for the device +.Fa dev , +by setting the +.Dv PCIM_CMD_BUSMASTEREN +bit in the +.Dv PCIR_COMMAND +register. +The +.Fn pci_disable_busmaster +function clears this bit. +.Pp +The +.Fn pci_enable_io +function enables memory or I/O port address decoding for the device +.Fa dev , +by setting the +.Dv PCIM_CMD_MEMEN +or +.Dv PCIM_CMD_PORTEN +bit in the +.Dv PCIR_COMMAND +register appropriately. +The +.Fn pci_disable_io +function clears the appropriate bit. +The +.Fa space +argument specifies which resource is affected; this can be either +.Dv SYS_RES_MEMORY +or +.Dv SYS_RES_IOPORT +as appropriate. +Device drivers should generally not use these routines directly. +The PCI bus will enable decoding automatically when a +.Dv SYS_RES_MEMORY +or +.Dv SYS_RES_IOPORT +resource is activated via +.Xr bus_alloc_resource 9 +or +.Xr bus_activate_resource 9 . +.Pp +The +.Fn pci_get_max_read_req +function returns the current maximum read request size in bytes for a +PCI-express device. +If the +.Fa dev +device is not a PCI-express device, +.Fn pci_get_max_read_req +returns zero. +.Pp +The +.Fn pci_set_max_read_req +sets the PCI-express maximum read request size for +.Fa dev . +The requested +.Fa size +may be adjusted, +and +.Fn pci_set_max_read_req +returns the actual size set in bytes. +If the +.Fa dev +device is not a PCI-express device, +.Fn pci_set_max_read_req +returns zero. +.Pp +The +.Fn pci_get_powerstate +function returns the current power state of the device +.Fa dev . +If the device does not support power management capabilities, then the default +state of +.Dv PCI_POWERSTATE_D0 +is returned. +The following power states are defined by PCI: +.Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" +.It Dv PCI_POWERSTATE_D0 +State in which device is on and running. +It is receiving full power from the system and delivering +full functionality to the user. +.It Dv PCI_POWERSTATE_D1 +Class-specific low-power state in which device context may or +may not be lost. +Busses in this state cannot do anything to the bus, to +force devices to lose context. +.It Dv PCI_POWERSTATE_D2 +Class-specific low-power state in which device context may or +may not be lost. +Attains greater power savings than +.Dv PCI_POWERSTATE_D1 . +Busses in this state can cause devices to lose some context. +Devices +.Em must +be prepared for the bus to be in this state or higher. +.It Dv PCI_POWERSTATE_D3 +State in which the device is off and not running. +Device context is lost, and power from the device can +be removed. +.It Dv PCI_POWERSTATE_UNKNOWN +State of the device is unknown. +.El +.Pp +The +.Fn pci_set_powerstate +function is used to transition the device +.Fa dev +to the PCI power state +.Fa state . +If the device does not support power management capabilities or +it does not support the specific power state +.Fa state , +then the function will fail with +.Er EOPNOTSUPP . +.Pp +The +.Fn pci_iov_attach +function is used to advertise that the given device +.Pq and associated device driver +supports PCI Single-Root I/O Virtualization +.Pq SR-IOV . +A driver that supports SR-IOV must implement the +.Xr PCI_IOV_INIT 9 , +.Xr PCI_IOV_ADD_VF 9 +and +.Xr PCI_IOV_UNINIT 9 +methods. +This function should be called during the +.Xr DEVICE_ATTACH 9 +method. +If this function returns an error, it is recommended that the device driver +still successfully attaches, but runs with SR-IOV disabled. +The +.Fa pf_schema +and +.Fa vf_schema +parameters are used to define what device-specific configuration parameters the +device driver accepts when SR-IOV is enabled for the Physical Function +.Pq PF +and for individual Virtual Functions +.Pq VFs +respectively. +See +.Xr pci_iov_schema 9 +for details on how to construct the schema. +If either the +.Pa pf_schema +or +.Pa vf_schema +is invalid or specifies parameter names that conflict with parameter names that +are already in use, +.Fn pci_iov_attach +will return an error and SR-IOV will not be available on the PF device. +If a driver does not accept configuration parameters for either the PF device +or the VF devices, the driver must pass an empty schema for that device. +The SR-IOV infrastructure takes ownership of the +.Fa pf_schema +and +.Fa vf_schema +and is responsible for freeing them. +The driver must never free the schemas itself. +.Pp +The +.Fn pci_iov_detach +function is used to advise the SR-IOV infrastructure that the driver for the +given device is attempting to detach and that all SR-IOV resources for the +device must be released. +This function must be called during the +.Xr DEVICE_DETACH 9 +method if +.Fn pci_iov_attach +was successfully called on the device and +.Fn pci_iov_detach +has not subsequently been called on the device and returned no error. +If this function returns an error, the +.Xr DEVICE_DETACH 9 +method must fail and return an error, as detaching the PF driver while VF +devices are active would cause system instability. +This function is safe to call and will always succeed if +.Fn pci_iov_attach +previously failed with an error on the given device, or if +.Fn pci_iov_attach +was never called on the device. +.Pp +The +.Fn pci_save_state +and +.Fn pci_restore_state +functions can be used by a device driver to save and restore standard PCI +config registers. +The +.Fn pci_save_state +function must be invoked while the device has valid state before +.Fn pci_restore_state +can be used. +If the device is not in the fully-powered state +.Pq Dv PCI_POWERSTATE_D0 +when +.Fn pci_restore_state +is invoked, +then the device will be transitioned to +.Dv PCI_POWERSTATE_D0 +before any config registers are restored. +.Ss Message Signaled Interrupts +Message Signaled Interrupts +.Pq MSI +and +Enhanced Message Signaled Interrupts +.Pq MSI-X +are PCI capabilities that provide an alternate method for PCI +devices to signal interrupts. +The legacy INTx interrupt is available to PCI devices as a +.Dv SYS_RES_IRQ +resource with a resource ID of zero. +MSI and MSI-X interrupts are available to PCI devices as one or more +.Dv SYS_RES_IRQ +resources with resource IDs greater than zero. +A driver must ask the PCI bus to allocate MSI or MSI-X interrupts +using +.Fn pci_alloc_msi +or +.Fn pci_alloc_msix +before it can use MSI or MSI-X +.Dv SYS_RES_IRQ +resources. +A driver is not allowed to use the legacy INTx +.Dv SYS_RES_IRQ +resource if MSI or MSI-X interrupts have been allocated, +and attempts to allocate MSI or MSI-X interrupts will fail if the +driver is currently using the legacy INTx +.Dv SYS_RES_IRQ +resource. +A driver is only allowed to use either MSI or MSI-X, +but not both. +.Pp +The +.Fn pci_msi_count +function returns the maximum number of MSI messages supported by the +device +.Fa dev . +If the device does not support MSI, +then +.Fn pci_msi_count +returns zero. +.Pp +The +.Fn pci_alloc_msi +function attempts to allocate +.Fa *count +MSI messages for the device +.Fa dev . +The +.Fn pci_alloc_msi +function may allocate fewer messages than requested for various +reasons including requests for more messages than the device +.Fa dev +supports, +or if the system has a shortage of available MSI messages. +On success, +.Fa *count +is set to the number of messages allocated and +.Fn pci_alloc_msi +returns zero. +The +.Dv SYS_RES_IRQ +resources for the allocated messages will be available at consecutive +resource IDs beginning with one. +If +.Fn pci_alloc_msi +is not able to allocate any messages, +it returns an error. +Note that MSI only supports message counts that are powers of two; +requests to allocate a non-power of two count of messages will fail. +.Pp +The +.Fn pci_release_msi +function is used to release any allocated MSI or MSI-X messages back +to the system. +If any MSI or MSI-X +.Dv SYS_RES_IRQ +resources are allocated by the driver or have a configured interrupt +handler, +this function will fail with +.Er EBUSY . +The +.Fn pci_release_msi +function returns zero on success and an error on failure. +.Pp +The +.Fn pci_msix_count +function returns the maximum number of MSI-X messages supported by the +device +.Fa dev . +If the device does not support MSI-X, +then +.Fn pci_msix_count +returns zero. +.Pp +The +.Fn pci_msix_pba_bar +function returns the offset in configuration space of the Base Address Register +.Pq BAR +containing the MSI-X Pending Bit Array (PBA) for device +.Fa dev . +The returned value can be used as the resource ID with +.Xr bus_alloc_resource 9 +and +.Xr bus_release_resource 9 +to allocate the BAR. +If the device does not support MSI-X, +then +.Fn pci_msix_pba_bar +returns -1. +.Pp +The +.Fn pci_msix_table_bar +function returns the offset in configuration space of the BAR +containing the MSI-X vector table for device +.Fa dev . +The returned value can be used as the resource ID with +.Xr bus_alloc_resource 9 +and +.Xr bus_release_resource 9 +to allocate the BAR. +If the device does not support MSI-X, +then +.Fn pci_msix_table_bar +returns -1. +.Pp +The +.Fn pci_alloc_msix +function attempts to allocate +.Fa *count +MSI-X messages for the device +.Fa dev . +The +.Fn pci_alloc_msix +function may allocate fewer messages than requested for various +reasons including requests for more messages than the device +.Fa dev +supports, +or if the system has a shortage of available MSI-X messages. +On success, +.Fa *count +is set to the number of messages allocated and +.Fn pci_alloc_msix +returns zero. +For MSI-X messages, +the resource ID for each +.Dv SYS_RES_IRQ +resource identifies the index in the MSI-X table of the +corresponding message. +A resource ID of one maps to the first index of the MSI-X table; +a resource ID two identifies the second index in the table, etc. +The +.Fn pci_alloc_msix +function assigns the +.Fa *count +messages allocated to the first +.Fa *count +table indicies. +If +.Fn pci_alloc_msix +is not able to allocate any messages, +it returns an error. +Unlike MSI, +MSI-X does not require message counts that are powers of two. +.Pp +The BARs containing the MSI-X vector table and PBA must be +allocated via +.Xr bus_alloc_resource 9 +before calling +.Fn pci_alloc_msix +and must not be released until after calling +.Fn pci_release_msi . +Note that the vector table and PBA may be stored in the same BAR or in +different BARs. +.Pp +The +.Fn pci_pending_msix +function examines the +.Fa dev +device's PBA +to determine the pending status of the MSI-X message at table index +.Fa index . +If the indicated message is pending, +this function returns a non-zero value; +otherwise, +it returns zero. +Passing an invalid +.Fa index +to this function will result in undefined behavior. +.Pp +As mentioned in the description of +.Fn pci_alloc_msix , +MSI-X messages are initially assigned to the first N table entries. +A driver may use a different distribution of available messages to +table entries via the +.Fn pci_remap_msix +function. +Note that this function must be called after a successful call to +.Fn pci_alloc_msix +but before any of the +.Dv SYS_RES_IRQ +resources are allocated. +The +.Fn pci_remap_msix +function returns zero on success, +or an error on failure. +.Pp +The +.Fa vectors +array should contain +.Fa count +message vectors. +The array maps directly to the MSI-X table in that the first entry in +the array specifies the message used for the first entry in the MSI-X +table, +the second entry in the array corresponds to the second entry in the +MSI-X table, +etc. +The vector value in each array index can either be zero to indicate +that no message should be assigned to the corresponding MSI-X table entry, +or it can be a number from one to N +.Po +where N is the count returned from the previous call to +.Fn pci_alloc_msix +.Pc +to indicate which of the allocated messages should be assigned to the +corresponding MSI-X table entry. +.Pp +If +.Fn pci_remap_msix +succeeds, +each MSI-X table entry with a non-zero vector will have an associated +.Dv SYS_RES_IRQ +resource whose resource ID corresponds to the table index as described +above for +.Fn pci_alloc_msix . +MSI-X table entries that with a vector of zero will not have an +associated +.Dv SYS_RES_IRQ +resource. +Additionally, +if any of the original messages allocated by +.Fn pci_alloc_msix +are not used in the new distribution of messages in the MSI-X table, +they will be released automatically. +Note that if a driver wishes to use fewer messages than were allocated by +.Fn pci_alloc_msix , +the driver must use a single, contiguous range of messages beginning +with one in the new distribution. +The +.Fn pci_remap_msix +function will fail if this condition is not met. +.Sh IMPLEMENTATION NOTES +The +.Vt pci_addr_t +type varies according to the size of the PCI bus address +space on the target architecture. +.Sh SEE ALSO +.Xr pci 4 , +.Xr pciconf 8 , +.Xr bus_alloc_resource 9 , +.Xr bus_dma 9 , +.Xr bus_release_resource 9 , +.Xr bus_setup_intr 9 , +.Xr bus_teardown_intr 9 , +.Xr devclass 9 , +.Xr device 9 , +.Xr driver 9 , +.Xr rman 9 +.Rs +.%B FreeBSD Developers' Handbook +.%T NewBus +.%U http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/ +.Re +.Rs +.%A Shanley +.%A Anderson +.%B PCI System Architecture +.%N 2nd Edition +.%I Addison-Wesley +.%O ISBN 0-201-30974-2 +.Re +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Bruce M Simpson Aq Mt bms@FreeBSD.org +and +.An John Baldwin Aq Mt jhb@FreeBSD.org . +.Sh BUGS +The kernel PCI code has a number of references to +.Dq "slot numbers" . +These do not refer to the geographic location of PCI devices, +but to the device number assigned by the combination of the PCI IDSEL +mechanism and the platform firmware. +This should be taken note of when working with the kernel PCI code. +.Pp +The PCI bus driver should allocate the MSI-X vector table and PBA internally +as necessary rather than requiring the caller to do so. Property changes on: user/imp/camdoc/pci.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_GETPAGES.9 =================================================================== --- user/imp/camdoc/VOP_GETPAGES.9 (nonexistent) +++ user/imp/camdoc/VOP_GETPAGES.9 (revision 296049) @@ -0,0 +1,172 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" Copyright 2003, Garrett A. Wollman +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 16, 2015 +.Dt VOP_GETPAGES 9 +.Os +.Sh NAME +.Nm VOP_GETPAGES , +.Nm VOP_PUTPAGES +.Nd read or write VM pages from a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In vm/vm.h +.Ft int +.Fn VOP_GETPAGES "struct vnode *vp" "vm_page_t *ma" "int count" "int *rbehind" "int *rahead" +.Ft int +.Fn VOP_PUTPAGES "struct vnode *vp" "vm_page_t *ma" "int count" "int sync" "int *rtvals" +.Sh DESCRIPTION +The +.Fn VOP_GETPAGES +method is called to read in pages of virtual memory which are backed by +ordinary files. +If other adjacent pages are backed by adjacent regions of the same file, +.Fn VOP_GETPAGES +is requested to read those pages as well, although it is not required to +do so. +The +.Fn VOP_PUTPAGES +method does the converse; that is to say, it writes out adjacent dirty +pages of virtual memory. +.Pp +On entry, the vnode lock is held but neither the page queue nor VM object +locks are held. +Both methods return in the same state on both success and error returns. +.Pp +The arguments are: +.Bl -tag -width rbehind +.It Fa vp +The file to access. +.It Fa ma +Pointer to the first element of an array of pages representing a +contiguous region of the file to be read or written. +.It Fa count +The number of bytes that should be read into the pages of the array. +.It Fa sync +.Dv VM_PAGER_PUT_SYNC +if the write should be synchronous. +.It Fa rtvals +An array of VM system result codes indicating the status of each +page written by +.Fn VOP_PUTPAGES . +.It Fa rbehind +Optional pointer to integer specifying number of pages to be read behind, if +possible. +If the filesystem supports that feature, number of actually read pages is +reported back, otherwise zero is returned. +.It Fa rahead +Optional pointer to integer specifying number of pages to be read ahead, if +possible. +If the filesystem supports that feature, number of actually read pages is +reported back, otherwise zero is returned. +.El +.Pp +The status of the +.Fn VOP_PUTPAGES +method is returned on a page-by-page basis in the array +.Fa rtvals[] . +The possible status values are as follows: +.Bl -tag -width VM_PAGER_ERROR +.It Dv VM_PAGER_OK +The page was successfully written. +The implementation must call +.Xr vm_page_undirty 9 +to mark the page as clean. +.It Dv VM_PAGER_PEND +The page was scheduled to be written asynchronously. +When the write completes, the completion callback should +call +.Xr vm_object_pip_wakeup 9 +and +.Xr vm_page_sunbusy 9 +to clear the busy flag and awaken any other threads waiting for this page, +in addition to calling +.Xr vm_page_undirty 9 . +.It Dv VM_PAGER_BAD +The page was entirely beyond the end of the backing file. +This condition should not be possible if the vnode's file system +is correctly implemented. +.It Dv VM_PAGER_ERROR +The page could not be written because of an error on the underlying storage +medium or protocol. +.It Dv VM_PAGER_FAIL +Treated identically to +.Dv VM_PAGER_ERROR . +.It Dv VM_PAGER_AGAIN +The page was not handled by this request. +.El +.Pp +The +.Fn VOP_GETPAGES +method is expected to release any pages in +.Fa ma +that it does not successfully handle, by calling +.Xr vm_page_free 9 . +When it succeeds, +.Fn VOP_GETPAGES +must set the valid bits appropriately. +.Fn VOP_GETPAGES +must keep +.Fa reqpage +busy. +It must unbusy all other successfully handled pages and put them +on appropriate page queue(s). +For example, +.Fn VOP_GETPAGES +may either activate a page (if its wanted bit is set) +or deactivate it (otherwise), and finally call +.Xr vm_page_xunbusy 9 +to arouse any threads currently waiting for the page to be faulted in. +.Sh RETURN VALUES +If it successfully reads +.Fa ma[reqpage] , +.Fn VOP_GETPAGES +returns +.Dv VM_PAGER_OK ; +otherwise, +.Dv VM_PAGER_ERROR . +By convention, the return value of +.Fn VOP_PUTPAGES +is +.Fa rtvals[0] . +.Sh SEE ALSO +.Xr vm_object_pip_wakeup 9 , +.Xr vm_page_free 9 , +.Xr vm_page_sunbusy 9 , +.Xr vm_page_undirty 9 , +.Xr vm_page_xunbusy 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson +and then substantially rewritten by +.An Garrett Wollman . Property changes on: user/imp/camdoc/VOP_GETPAGES.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUS_DESCRIBE_INTR.9 =================================================================== --- user/imp/camdoc/BUS_DESCRIBE_INTR.9 (nonexistent) +++ user/imp/camdoc/BUS_DESCRIBE_INTR.9 (revision 296049) @@ -0,0 +1,104 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 9, 2015 +.Dt BUS_DESCRIBE_INTR 9 +.Os +.Sh NAME +.Nm BUS_DESCRIBE_INTR , +.Nm bus_describe_intr +.Nd "associate a description with an active interrupt handler" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fo BUS_DESCRIBE_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookie" +.Fa "const char *descr" +.Fc +.Ft int +.Fo bus_describe_intr +.Fa "device_t dev" "struct resource *irq" "void *cookie" "const char *fmt" +.Fa ... +.Fc +.Sh DESCRIPTION +The +.Fn BUS_DESCRIBE_INTR +method associates a description with an active interrupt handler. +The +.Fa cookie +parameter must be the value returned by a successful call to +.Xr BUS_SETUP_INTR 9 +for the interrupt +.Fa irq . +.Pp +The +.Fn bus_describe_intr +function is a simple wrapper around +.Fn BUS_DESCRIBE_INTR . +As a convenience, +.Fn bus_describe_intr +allows the caller to use +.Xr printf 9 +style formatting to build the description string using +.Fa fmt . +.Pp +When an interrupt handler is established by +.Xr BUS_SETUP_INTR 9 , +the handler is named after the device the handler is established for. +This name is then used in various places such as interrupt statistics +displayed by +.Xr systat 1 +and +.Xr vmstat 8 . +For devices that use a single interrupt, +the device name is sufficiently unique to identify the interrupt handler. +However, for devices that use multiple interrupts it can be useful to +distinguish the interrupt handlers. +When a description is set for an active interrupt handler, +a colon followed by the description is appended to the device name to form +the interrupt handler name. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr systat 1 , +.Xr vmstat 8 , +.Xr BUS_SETUP_INTR 9 , +.Xr device 9 , +.Xr printf 9 +.Sh HISTORY +The +.Fn BUS_DESCRIBE_INTR +method and +.Fn bus_describe_intr +functions first appeared in +.Fx 8.1 . +.Sh BUGS +It is not currently possible to remove a description from an active interrupt +handler. Property changes on: user/imp/camdoc/BUS_DESCRIBE_INTR.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/proc_rwmem.9 =================================================================== --- user/imp/camdoc/proc_rwmem.9 (nonexistent) +++ user/imp/camdoc/proc_rwmem.9 (revision 296049) @@ -0,0 +1,104 @@ +.\" +.\" Copyright (c) 2015 Mark Johnston +.\" +.\" 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 December 7, 2015 +.Dt PROC_RWMEM 9 +.Os +.Sh NAME +.Nm proc_rwmem , +.Nm proc_readmem , +.Nm proc_writemem +.Nd read from or write to a process address space +.Sh SYNOPSIS +.In sys/types.h +.In sys/ptrace.h +.Ft int +.Fn proc_rwmem "struct proc *p" "struct uio *uio" +.Ft ssize_t +.Fn proc_readmem "struct thread *td" "struct proc *p" "vm_offset_t va" "void *buf" "size_t len" +.Ft ssize_t +.Fn proc_writemem "struct thread *td" "struct proc *p" "vm_offset_t va" "void *buf" "size_t len" +.Sh DESCRIPTION +These functions are used to read to or write from the address space of the +process +.Fa p . +The +.Fn proc_rwmem +function requires the caller to specify the I/O parameters using a +.Vt "struct uio" , +described in +.Xr uio 9 . +The +.Fn proc_readmem +and +.Fn proc_writemem +functions provide a simpler, less general interface which allows the caller to +read into or write the kernel buffer +.Fa buf +of size +.Fa len +from or to the memory at offset +.Fa va +in the address space of +.Fa p . +The operation is performed on behalf of thread +.Fa td , +which will most often be the current thread. +.Pp +These functions may sleep and thus may not be called with any non-sleepable +locks held. +The process +.Fa p +must be held by the caller using +.Xr PHOLD 9 . +.Sh RETURN VALUES +The +.Fn proc_rwmem +function returns +.Dv 0 +on success. +.Dv EFAULT +is returned if the specified user address is invalid, and +.Dv ENOMEM +is returned if the target pages could not be faulted in due to a resource +shortage. +.Pp +The +.Fn proc_readmem +and +.Fn proc_writemem +functions return the number of bytes read or written, respectively. +This may be smaller than the number of bytes requested, for example if the +request spans multiple pages in the process address space and one of them after +the first is not mapped. +Otherwise, -1 is returned. +.Sh SEE ALSO +.Xr copyin 9 , +.Xr locking 9 , +.Xr PHOLD 9 , +.Xr uio 9 +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . Property changes on: user/imp/camdoc/proc_rwmem.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/g_bio.9 =================================================================== --- user/imp/camdoc/g_bio.9 (nonexistent) +++ user/imp/camdoc/g_bio.9 (revision 296049) @@ -0,0 +1,277 @@ +.\" +.\" Copyright (c) 2004-2006 Pawel Jakub Dawidek +.\" 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 December 7, 2015 +.Dt G_BIO 9 +.Os +.Sh NAME +.Nm g_new_bio , +.Nm g_clone_bio , +.Nm g_destroy_bio , +.Nm g_print_bio +.Nd "GEOM bio controlling functions" +.Sh SYNOPSIS +.In sys/bio.h +.In geom/geom.h +.Ft "struct bio *" +.Fn g_new_bio void +.Ft "struct bio *" +.Fn g_alloc_bio void +.Ft "struct bio *" +.Fn g_clone_bio "struct bio *bp" +.Ft "struct bio *" +.Fn g_duplicate_bio "struct bio *bp" +.Ft void +.Fn g_destroy_bio "struct bio *bp" +.Ft void +.Fn g_print_bio "struct bio *bp" +.Sh DESCRIPTION +A +.Vt "struct bio" +is used by GEOM to describe I/O requests, its +most important fields are described below: +.Bl -tag -width ".Va bio_attribute" +.It Va bio_cmd +I/O request command. +There are four I/O requests available in GEOM: +.Bl -tag -width ".Dv BIO_GETATTR" +.It Dv BIO_READ +A read request. +.It Dv BIO_WRITE +A write request. +.It Dv BIO_DELETE +Indicates that a certain range of data is no longer used and that +it can be erased or freed as the underlying technology supports. +Technologies like flash adaptation layers can arrange to erase the relevant +blocks before they will become reassigned and cryptographic devices may +want to fill random bits into the range to reduce the amount of data +available for attack. +.It Dv BIO_GETATTR +Inspect and manipulate out-of-band +attributes on a particular provider or path. +Attributes are named by ascii strings and are stored in the +.Va bio_attribute +field. +.It Dv BIO_FLUSH +Tells underlying providers to flush their write caches. +.El +.It Va bio_flags +Available flags: +.Bl -tag -width ".Dv BIO_ERROR" +.It Dv BIO_ERROR +Request failed (error value is stored in +.Va bio_error +field). +.It Dv BIO_DONE +Request finished. +.El +.It Va bio_cflags +Private use by the consumer. +.It Va bio_pflags +Private use by the provider. +.It Va bio_offset +Offset into provider. +.It Va bio_data +Pointer to data buffer. +.It Va bio_error +Error value when +.Dv BIO_ERROR +is set. +.It Va bio_done +Pointer to function which will be called when the request is finished. +.It Va bio_driver1 +Private use by the provider. +.It Va bio_driver2 +Private use by the provider. +.It Va bio_caller1 +Private use by the consumer. +.It Va bio_caller2 +Private use by the consumer. +.It Va bio_attribute +Attribute string for +.Dv BIO_GETATTR +request. +.It Va bio_from +Consumer to use for request (attached to provider stored in +.Va bio_to +field) (typically read-only for a class). +.It Va bio_to +Destination provider (typically read-only for a class). +.It Va bio_length +Request length in bytes. +.It Va bio_completed +Number of bytes completed, but they may not be completed from +the front of the request. +.It Va bio_children +Number of +.Vt bio +clones (typically read-only for a class). +.It Va bio_inbed +Number of finished +.Vt bio +clones. +.It Va bio_parent +Pointer to parent +.Vt bio . +.El +.Pp +The +.Fn g_new_bio +function allocates a new, empty +.Vt bio +structure. +.Pp +.Fn g_alloc_bio +- same as +.Fn g_new_bio , +but always succeeds (allocates bio with the +.Dv M_WAITOK +malloc flag). +.Pp +The +.Fn g_clone_bio +function allocates a new +.Vt bio +structure and copies the following fields from the +.Vt bio +given as an argument to clone: +.Va bio_cmd , +.Va bio_length , +.Va bio_offset , +.Va bio_data , +.Va bio_attribute . +The field +.Va bio_parent +in the clone points to the passed +.Vt bio +and the field +.Va bio_children +in the passed +.Vt bio +is incremented. +.Pp +This function should be used for every request which enters through +the provider of a particular geom and needs to be scheduled down. +Proper order is: +.Pp +.Bl -enum -compact +.It +Clone the received +.Vt "struct bio" . +.It +Modify the clone. +.It +Schedule the clone on its own consumer. +.El +.Pp +.Fn g_duplicate_bio +- same as +.Fn g_clone_bio , +but always succeeds (allocates bio with the +.Dv M_WAITOK +malloc flag). +.Pp +The +.Fn g_destroy_bio +function deallocates and destroys the given +.Vt bio +structure. +.Pp +The +.Fn g_print_bio +function prints information about the given +.Vt bio +structure (for debugging purposes). +.Sh RETURN VALUES +The +.Fn g_new_bio +and +.Fn g_clone_bio +functions return a pointer to the allocated +.Vt bio , +or +.Dv NULL +if an error occurred. +.Sh EXAMPLES +Implementation of +.Dq Dv NULL Ns -transformation , +meaning that an I/O request is cloned and scheduled down without any +modifications. +Let us assume that field +.Va ex_consumer +in structure +.Vt example_softc +contains a consumer attached to the provider we want to operate on. +.Bd -literal -offset indent +void +example_start(struct bio *bp) +{ + struct example_softc *sc; + struct bio *cbp; + + printf("Request received: "); + g_print_bio(bp); + printf("\\n"); + + sc = bp->bio_to->geom->softc; + if (sc == NULL) { + g_io_deliver(bp, ENXIO); + return; + } + + /* Let's clone our bio request. */ + cbp = g_clone_bio(bp); + if (cbp == NULL) { + g_io_deliver(bp, ENOMEM); + return; + } + cbp->bio_done = g_std_done; /* Standard 'done' function. */ + + /* Ok, schedule it down. */ + /* + * The consumer can be obtained from + * LIST_FIRST(&bp->bio_to->geom->consumer) as well, + * if there is only one in our geom. + */ + g_io_request(cbp, sc->ex_consumer); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_bio.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/style.9 =================================================================== --- user/imp/camdoc/style.9 (nonexistent) +++ user/imp/camdoc/style.9 (revision 296049) @@ -0,0 +1,881 @@ +.\"- +.\" Copyright (c) 1995-2005 The FreeBSD Project +.\" 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. +.\" +.\" From: @(#)style 1.14 (Berkeley) 4/28/95 +.\" $FreeBSD$ +.\" +.Dd December 5, 2015 +.Dt STYLE 9 +.Os +.Sh NAME +.Nm style +.Nd "kernel source file style guide" +.Sh DESCRIPTION +This file specifies the preferred style for kernel source files in the +.Fx +source tree. +It is also a guide for the preferred userland code style. +Many of the style rules are implicit in the examples. +Be careful to check the examples before assuming that +.Nm +is silent on an issue. +.Bd -literal +/* + * Style guide for FreeBSD. Based on the CSRG's KNF (Kernel Normal Form). + * + * @(#)style 1.14 (Berkeley) 4/28/95 + * $FreeBSD$ + */ + +/* + * VERY important single-line comments look like this. + */ + +/* Most single-line comments look like this. */ + +/* + * Multi-line comments look like this. Make them real sentences. Fill + * them so they look like real paragraphs. + */ +.Ed +.Pp +The copyright header should be a multi-line comment, with the first +line of the comment having a dash after the star like so: +.Bd -literal +/*- + * Copyright (c) 1984-2025 John Q. Public + * All rights reserved. + * + * Long, boring license goes here, but trimmed for brevity + */ +.Ed +.Pp +An automatic script collects license information from the tree for +all comments that start in the first column with +.Dq Li "/*-" . +If you desire to flag +.Xr indent 1 +to not reformat a comment that starts in the first column which is not a +license or copyright notice, change the dash to a star for those +comments. +Comments starting in columns other than the first are never +considered license statements. +.Pp +After any copyright header, there is a blank line, and the +.Li $\&FreeBSD$ +for non C/C++ language source files. +Version control system ID tags should only exist once in a file +(unlike in this one). +Non-C/C++ source files follow the example above, while C/C++ source files +follow the one below. +All VCS (version control system) revision identification in files obtained +from elsewhere should be maintained, including, where applicable, multiple IDs +showing a file's history. +In general, do not edit foreign IDs or their infrastructure. +Unless otherwise wrapped (such as +.Dq Li "#if defined(LIBC_SCCS)" ) , +enclose both in +.Dq Li "#if 0 ... #endif" +to hide any uncompilable bits +and to keep the IDs out of object files. +Only add +.Dq Li "From: " +in front of foreign VCS IDs if the file is renamed. +.Bd -literal +#if 0 +#ifndef lint +static char sccsid[] = "@(#)style 1.14 (Berkeley) 4/28/95"; +#endif /* not lint */ +#endif + +#include +__FBSDID("$FreeBSD$"); +.Ed +.Pp +Leave another blank line before the header files. +.Pp +Kernel include files (i.e.\& +.Pa sys/*.h ) +come first; normally, include +.In sys/types.h +OR +.In sys/param.h , +but not both. +.In sys/types.h +includes +.In sys/cdefs.h , +and it is okay to depend on that. +.Bd -literal +#include /* Non-local includes in angle brackets. */ +.Ed +.Pp +For a network program, put the network include files next. +.Bd -literal +#include +#include +#include +#include +#include +.Ed +.Pp +Do not use files in +.Pa /usr/include +for files in the kernel. +.Pp +Leave a blank line before the next group, the +.Pa /usr/include +files, +which should be sorted alphabetically by name. +.Bd -literal +#include +.Ed +.Pp +Global pathnames are defined in +.In paths.h . +Pathnames local +to the program go in +.Qq Pa pathnames.h +in the local directory. +.Bd -literal +#include +.Ed +.Pp +Leave another blank line before the user include files. +.Bd -literal +#include "pathnames.h" /* Local includes in double quotes. */ +.Ed +.Pp +Do not +.Ic #define +or declare names in the implementation namespace except +for implementing application interfaces. +.Pp +The names of +.Dq unsafe +macros (ones that have side effects), and the names of macros for +manifest constants, are all in uppercase. +The expansions of expression-like macros are either a single token +or have outer parentheses. +Put a single tab character between the +.Ic #define +and the macro name. +If a macro is an inline expansion of a function, the function name is +all in lowercase and the macro has the same name all in uppercase. +.\" XXX the above conflicts with ANSI style where the names are the +.\" same and you #undef the macro (if any) to get the function. +.\" It is not followed for MALLOC(), and not very common if inline +.\" functions are used. +Right-justify the +backslashes; it makes it easier to read. +If the macro encapsulates a compound statement, enclose it in a +.Ic do +loop, +so that it can safely be used in +.Ic if +statements. +Any final statement-terminating semicolon should be +supplied by the macro invocation rather than the macro, to make parsing easier +for pretty-printers and editors. +.Bd -literal +#define MACRO(x, y) do { \e + variable = (x) + (y); \e + (y) += 2; \e +} while (0) +.Ed +.Pp +When code is conditionally compiled using +.Ic #ifdef +or +.Ic #if , +a comment may be added following the matching +.Ic #endif +or +.Ic #else +to permit the reader to easily discern where conditionally compiled code +regions end. +This comment should be used only for (subjectively) long regions, regions +greater than 20 lines, or where a series of nested +.Ic #ifdef 's +may be confusing to the reader. +Exceptions may be made for cases where code is conditionally not compiled for +the purposes of +.Xr lint 1 , +even though the uncompiled region may be small. +The comment should be separated from the +.Ic #endif +or +.Ic #else +by a single space. +For short conditionally compiled regions, a closing comment should not be +used. +.Pp +The comment for +.Ic #endif +should match the expression used in the corresponding +.Ic #if +or +.Ic #ifdef . +The comment for +.Ic #else +and +.Ic #elif +should match the inverse of the expression(s) used in the preceding +.Ic #if +and/or +.Ic #elif +statements. +In the comments, the subexpression +.Dq Li defined(FOO) +is abbreviated as +.Dq Li FOO . +For the purposes of comments, +.Dq Ic #ifndef Li FOO +is treated as +.Dq Ic #if Li !defined(FOO) . +.Bd -literal +#ifdef KTRACE +#include +#endif + +#ifdef COMPAT_43 +/* A large region here, or other conditional code. */ +#else /* !COMPAT_43 */ +/* Or here. */ +#endif /* COMPAT_43 */ + +#ifndef COMPAT_43 +/* Yet another large region here, or other conditional code. */ +#else /* COMPAT_43 */ +/* Or here. */ +#endif /* !COMPAT_43 */ +.Ed +.Pp +The project is slowly moving to use the +.St -isoC-99 +unsigned integer identifiers of the form +.Vt uintXX_t +in preference to the older +.Bx Ns -style +integer identifiers of the form +.Vt u_intXX_t . +New code should use the former, and old code should be converted to +the new form if other major work is being done in that area and +there is no overriding reason to prefer the older +.Bx Ns -style . +Like white-space commits, care should be taken in making +.Vt uintXX_t +only commits. +.Pp +Similarly, the project is slowly moving to use the +.St -isoC-99 +.Vt bool +in preference to the older +.Vt int +or +.Vt boolean_t . +New code should use +.Vt bool , +and old code may be converted if it is +reasonable to do so. +Literal values are named +.Dv true +and +.Dv false . +These are preferred to the old spellings +.Dv TRUE +and +.Dv FALSE . +Userspace code should include +.In stdbool.h , +while kernel code should include +.In sys/types.h . +.Pp +Enumeration values are all uppercase. +.Bd -literal +enum enumtype { ONE, TWO } et; +.Ed +.Pp +The use of internal_underscores in identifiers is preferred over +camelCase or TitleCase. +.Pp +In declarations, do not put any whitespace between asterisks and +adjacent tokens, except for tokens that are identifiers related to +types. +(These identifiers are the names of basic types, type +qualifiers, and +.Ic typedef Ns -names +other than the one being declared.) +Separate these identifiers from asterisks using a single space. +.Pp +When declaring variables in structures, declare them sorted by use, then +by size (largest to smallest), and then in alphabetical order. +The first category normally does not apply, but there are exceptions. +Each one gets its own line. +Try to make the structure +readable by aligning the member names using either one or two tabs +depending upon your judgment. +You should use one tab only if it suffices to align at least 90% of +the member names. +Names following extremely long types +should be separated by a single space. +.Pp +Major structures should be declared at the top of the file in which they +are used, or in separate header files if they are used in multiple +source files. +Use of the structures should be by separate declarations +and should be +.Ic extern +if they are declared in a header file. +.Bd -literal +struct foo { + struct foo *next; /* List of active foo. */ + struct mumble amumble; /* Comment for mumble. */ + int bar; /* Try to align the comments. */ + struct verylongtypename *baz; /* Won't fit in 2 tabs. */ +}; +struct foo *foohead; /* Head of global foo list. */ +.Ed +.Pp +Use +.Xr queue 3 +macros rather than rolling your own lists, whenever possible. +Thus, +the previous example would be better written: +.Bd -literal +#include + +struct foo { + LIST_ENTRY(foo) link; /* Use queue macros for foo lists. */ + struct mumble amumble; /* Comment for mumble. */ + int bar; /* Try to align the comments. */ + struct verylongtypename *baz; /* Won't fit in 2 tabs. */ +}; +LIST_HEAD(, foo) foohead; /* Head of global foo list. */ +.Ed +.Pp +Avoid using typedefs for structure types. +Typedefs are problematic because they do not properly hide their +underlying type; for example you need to know if the typedef is +the structure itself or a pointer to the structure. +In addition they must be declared exactly once, whereas an +incomplete structure type can be mentioned as many times as +necessary. +Typedefs are difficult to use in stand-alone header files: +the header that defines the typedef must be included +before the header that uses it, or by the header that uses +it (which causes namespace pollution), or there must be a +back-door mechanism for obtaining the typedef. +.Pp +When convention requires a +.Ic typedef , +make its name match the struct tag. +Avoid typedefs ending in +.Dq Li _t , +except as specified in Standard C or by +.Tn POSIX . +.Bd -literal +/* Make the structure name match the typedef. */ +typedef struct bar { + int level; +} BAR; +typedef int foo; /* This is foo. */ +typedef const long baz; /* This is baz. */ +.Ed +.Pp +All functions are prototyped somewhere. +.Pp +Function prototypes for private functions (i.e., functions not used +elsewhere) go at the top of the first source module. +Functions +local to one source module should be declared +.Ic static . +.Pp +Functions used from other parts of the kernel are prototyped in the +relevant include file. +Function prototypes should be listed in a logical order, preferably +alphabetical unless there is a compelling reason to use a different +ordering. +.Pp +Functions that are used locally in more than one module go into a +separate header file, e.g.\& +.Qq Pa extern.h . +.Pp +Do not use the +.Dv __P +macro. +.Pp +In general code can be considered +.Dq "new code" +when it makes up about 50% or more of the file(s) involved. +This is enough +to break precedents in the existing code and use the current +.Nm +guidelines. +.Pp +The kernel has a name associated with parameter types, e.g., in the kernel +use: +.Bd -literal +void function(int fd); +.Ed +.Pp +In header files visible to userland applications, prototypes that are +visible must use either +.Dq protected +names (ones beginning with an underscore) +or no names with the types. +It is preferable to use protected names. +E.g., use: +.Bd -literal +void function(int); +.Ed +.Pp +or: +.Bd -literal +void function(int _fd); +.Ed +.Pp +Prototypes may have an extra space after a tab to enable function names +to line up: +.Bd -literal +static char *function(int _arg, const char *_arg2, struct foo *_arg3, + struct bar *_arg4); +static void usage(void); + +/* + * All major routines should have a comment briefly describing what + * they do. The comment before the "main" routine should describe + * what the program does. + */ +int +main(int argc, char *argv[]) +{ + char *ep; + long num; + int ch; +.Ed +.Pp +For consistency, +.Xr getopt 3 +should be used to parse options. +Options +should be sorted in the +.Xr getopt 3 +call and the +.Ic switch +statement, unless +parts of the +.Ic switch +cascade. +Elements in a +.Ic switch +statement that cascade should have a +.Li FALLTHROUGH +comment. +Numerical arguments should be checked for accuracy. +Code which is unreachable for non-obvious reasons may be marked /* +.Li NOTREACHED +*/. +.Bd -literal + while ((ch = getopt(argc, argv, "abNn:")) != -1) + switch (ch) { /* Indent the switch. */ + case 'a': /* Don't indent the case. */ + aflag = 1; /* Indent case body one tab. */ + /* FALLTHROUGH */ + case 'b': + bflag = 1; + break; + case 'N': + Nflag = 1; + break; + case 'n': + num = strtol(optarg, &ep, 10); + if (num <= 0 || *ep != '\e0') { + warnx("illegal number, -n argument -- %s", + optarg); + usage(); + } + break; + case '?': + default: + usage(); + } + argc -= optind; + argv += optind; +.Ed +.Pp +Space after keywords +.Pq Ic if , while , for , return , switch . +Two styles of braces +.Ql ( \&{ +and +.Ql \&} ) +are allowed for single line statements. +Either they are used for all single statements, or +they are used only where needed for clarity. +Usage within a function should be consistent. +Forever loops are done with +.Ic for Ns 's , +not +.Ic while Ns 's . +.Bd -literal + for (p = buf; *p != '\e0'; ++p) + ; /* nothing */ + for (;;) + stmt; + for (;;) { + z = a + really + long + statement + that + needs + + two + lines + gets + indented + four + spaces + + on + the + second + and + subsequent + lines; + } + for (;;) { + if (cond) + stmt; + } + if (val != NULL) + val = realloc(val, newsize); +.Ed +.Pp +Parts of a +.Ic for +loop may be left empty. +Do not put declarations +inside blocks unless the routine is unusually complicated. +.Bd -literal + for (; cnt < 15; cnt++) { + stmt1; + stmt2; + } +.Ed +.Pp +Indentation is an 8 character tab. +Second level indents are four spaces. +If you have to wrap a long statement, put the operator at the end of the +line. +.Bd -literal + while (cnt < 20 && this_variable_name_is_too_long && + ep != NULL) + z = a + really + long + statement + that + needs + + two + lines + gets + indented + four + spaces + + on + the + second + and + subsequent + lines; +.Ed +.Pp +Do not add whitespace at the end of a line, and only use tabs +followed by spaces +to form the indentation. +Do not use more spaces than a tab will produce +and do not use spaces in front of tabs. +.Pp +Closing and opening braces go on the same line as the +.Ic else . +Braces that are not necessary may be left out. +.Bd -literal + if (test) + stmt; + else if (bar) { + stmt; + stmt; + } else + stmt; +.Ed +.Pp +No spaces after function names. +Commas have a space after them. +No spaces +after +.Ql \&( +or +.Ql \&[ +or preceding +.Ql \&] +or +.Ql \&) +characters. +.Bd -literal + error = function(a1, a2); + if (error != 0) + exit(error); +.Ed +.Pp +Unary operators do not require spaces, binary operators do. +Do not use parentheses unless they are required for precedence or unless the +statement is confusing without them. +Remember that other people may +confuse easier than you. +Do YOU understand the following? +.Bd -literal + a = b->c[0] + ~d == (e || f) || g && h ? i : j >> 1; + k = !(l & FLAGS); +.Ed +.Pp +Exits should be 0 on success, or 1 on failure. +.Bd -literal + exit(0); /* + * Avoid obvious comments such as + * "Exit 0 on success." + */ +} +.Ed +.Pp +The function type should be on a line by itself +preceding the function. +The opening brace of the function body should be +on a line by itself. +.Bd -literal +static char * +function(int a1, int a2, float fl, int a4) +{ +.Ed +.Pp +When declaring variables in functions declare them sorted by size, +then in alphabetical order; multiple ones per line are okay. +If a line overflows reuse the type keyword. +.Pp +Be careful to not obfuscate the code by initializing variables in +the declarations. +Use this feature only thoughtfully. +DO NOT use function calls in initializers. +.Bd -literal + struct foo one, *two; + double three; + int *four, five; + char *six, seven, eight, nine, ten, eleven, twelve; + + four = myfunction(); +.Ed +.Pp +Do not declare functions inside other functions; ANSI C says that +such declarations have file scope regardless of the nesting of the +declaration. +Hiding file declarations in what appears to be a local +scope is undesirable and will elicit complaints from a good compiler. +.Pp +Casts and +.Ic sizeof Ns 's +are not followed by a space. +Note that +.Xr indent 1 +does not understand this rule. +.Ic sizeof Ns 's +are written with parenthesis always. +The redundant parenthesis rules do not apply to +.Fn sizeof var +instances. +.Pp +.Dv NULL +is the preferred null pointer constant. +Use +.Dv NULL +instead of +.Vt ( "type *" ) Ns 0 +or +.Vt ( "type *" ) Ns Dv NULL +in contexts where the compiler knows the +type, e.g., in assignments. +Use +.Vt ( "type *" ) Ns Dv NULL +in other contexts, +in particular for all function args. +(Casting is essential for +variadic args and is necessary for other args if the function prototype +might not be in scope.) +Test pointers against +.Dv NULL , +e.g., use: +.Bd -literal +(p = f()) == NULL +.Ed +.Pp +not: +.Bd -literal +!(p = f()) +.Ed +.Pp +Do not use +.Ic \&! +for tests unless it is a boolean, e.g.\& use: +.Bd -literal +if (*p == '\e0') +.Ed +.Pp +not: +.Bd -literal +if (!*p) +.Ed +.Pp +Routines returning +.Vt "void *" +should not have their return values cast +to any pointer type. +.Pp +Values in +.Ic return +statements should be enclosed in parentheses. +.Pp +Use +.Xr err 3 +or +.Xr warn 3 , +do not roll your own. +.Bd -literal + if ((four = malloc(sizeof(struct foo))) == NULL) + err(1, (char *)NULL); + if ((six = (int *)overflow()) == NULL) + errx(1, "number overflowed"); + return (eight); +} +.Ed +.Pp +Old-style function declarations look like this: +.Bd -literal +static char * +function(a1, a2, fl, a4) + int a1, a2; /* Declare ints, too, don't default them. */ + float fl; /* Beware double vs. float prototype differences. */ + int a4; /* List in order declared. */ +{ +.Ed +.Pp +Use ANSI function declarations unless you explicitly need K&R compatibility. +Long parameter lists are wrapped with a normal four space indent. +.Pp +Variable numbers of arguments should look like this: +.Bd -literal +#include + +void +vaf(const char *fmt, ...) +{ + va_list ap; + + va_start(ap, fmt); + STUFF; + va_end(ap); + /* No return needed for void functions. */ +} + +static void +usage() +{ + /* Insert an empty line if the function has no local variables. */ +.Ed +.Pp +Use +.Xr printf 3 , +not +.Xr fputs 3 , +.Xr puts 3 , +.Xr putchar 3 , +whatever; it is faster and usually cleaner, not +to mention avoiding stupid bugs. +.Pp +Usage statements should look like the manual pages +.Sx SYNOPSIS . +The usage statement should be structured in the following order: +.Bl -enum +.It +Options without operands come first, +in alphabetical order, +inside a single set of brackets +.Ql ( \&[ +and +.Ql \&] ) . +.It +Options with operands come next, +also in alphabetical order, +with each option and its argument inside its own pair of brackets. +.It +Required arguments +(if any) +are next, +listed in the order they should be specified on the command line. +.It +Finally, +any optional arguments should be listed, +listed in the order they should be specified, +and all inside brackets. +.El +.Pp +A bar +.Pq Ql \&| +separates +.Dq either-or +options/arguments, +and multiple options/arguments which are specified together are +placed in a single set of brackets. +.Bd -literal -offset 4n +"usage: f [-aDde] [-b b_arg] [-m m_arg] req1 req2 [opt1 [opt2]]\en" +"usage: f [-a | -b] [-c [-dEe] [-n number]]\en" +.Ed +.Bd -literal + (void)fprintf(stderr, "usage: f [-ab]\en"); + exit(1); +} +.Ed +.Pp +Note that the manual page options description should list the options in +pure alphabetical order. +That is, without regard to whether an option takes arguments or not. +The alphabetical ordering should take into account the case ordering +shown above. +.Pp +New core kernel code should be reasonably compliant with the +.Nm +guides. +The guidelines for third-party maintained modules and device drivers are more +relaxed but at a minimum should be internally consistent with their style. +.Pp +Stylistic changes (including whitespace changes) are hard on the source +repository and are to be avoided without good reason. +Code that is approximately +.Fx +KNF +.Nm +compliant in the repository must not diverge from compliance. +.Pp +Whenever possible, code should be run through a code checker +(e.g., +.Xr lint 1 +or +.Nm cc Fl Wall ) +and produce minimal warnings. +.Sh SEE ALSO +.Xr indent 1 , +.Xr lint 1 , +.Xr err 3 , +.Xr warn 3 , +.Xr style.Makefile 5 +.Sh HISTORY +This manual page is largely based on the +.Pa src/admin/style/style +file from the +.Bx 4.4 Lite2 +release, with occasional updates to reflect the current practice and +desire of the +.Fx +project. +.Pa src/admin/style/style +is a codification by the CSRG of the programming style of Ken Thompson and +Dennis Ritchie in +.At v6 . Property changes on: user/imp/camdoc/style.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devfs_set_cdevpriv.9 =================================================================== --- user/imp/camdoc/devfs_set_cdevpriv.9 (nonexistent) +++ user/imp/camdoc/devfs_set_cdevpriv.9 (revision 296049) @@ -0,0 +1,124 @@ +.\" Copyright (c) 2008 Konstantin Belousov +.\" 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 2, 2015 +.Dt DEVFS_CDEVPRIV 9 +.Os +.Sh NAME +.Nm devfs_set_cdevpriv , +.Nm devfs_get_cdevpriv , +.Nm devfs_clear_cdevpriv +.Nd manage per-open filedescriptor data for devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Bd -literal +typedef void d_priv_dtor_t(void *data); +.Ed +.Ft int +.Fn devfs_get_cdevpriv "void **datap" +.Ft int +.Fn devfs_set_cdevpriv "void *priv" "d_priv_dtor_t *dtr" +.Ft void +.Fn devfs_clear_cdevpriv "void" +.Sh DESCRIPTION +The +.Fn devfs_xxx_cdevpriv +family of functions allows the +.Fa cdev +driver methods to associate some driver-specific data with each +user process +.Xr open 2 +of the device special file. +Currently, functioning of these functions is restricted to the context +of the +.Fa cdevsw +switch method calls performed as +.Xr devfs 5 +operations in response to system calls that use filedescriptors. +.Pp +The +.Fn devfs_set_cdevpriv +function associates a data pointed by +.Va priv +with current calling context (filedescriptor). +The data may be retrieved later, possibly from another call +performed on this filedescriptor, by the +.Fn devfs_get_cdevpriv +function. +The +.Fn devfs_clear_cdevpriv +disassociates previously attached data from context. +Immediately after +.Fn devfs_clear_cdevpriv +finished operating, the +.Va dtr +callback is called, with private data supplied +.Va data +argument. +The +.Fn devfs_clear_cdevpriv +function will be also be called if the open callback +function returns an error code. +.Pp +On the last filedescriptor close, system automatically arranges +.Fn devfs_clear_cdevpriv +call. +.Pp +If successful, the functions return 0. +.Pp +The function +.Fn devfs_set_cdevpriv +returns the following values on error: +.Bl -tag -width Er +.It Bq Er ENOENT +The current call is not associated with some filedescriptor. +.It Bq Er EBUSY +The private driver data is already associated with current +filedescriptor. +.El +.Pp +The function +.Fn devfs_get_cdevpriv +returns the following values on error: +.Bl -tag -width Er +.It Bq Er EBADF +The current call is not associated with some filedescriptor. +.It Bq Er ENOENT +The private driver data was not associated with current +filedescriptor, or +.Fn devfs_clear_cdevpriv +was called. +.El +.Sh SEE ALSO +.Xr close 2 , +.Xr open 2 , +.Xr devfs 5 +.Sh HISTORY +The +.Fn devfs_cdevpriv +family of functions first appeared in +.Fx 7.1 . Property changes on: user/imp/camdoc/devfs_set_cdevpriv.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/printf.9 =================================================================== --- user/imp/camdoc/printf.9 (nonexistent) +++ user/imp/camdoc/printf.9 (revision 296049) @@ -0,0 +1,180 @@ +.\" +.\" Copyright (c) 2001 Andrew R. Reiter +.\" Copyright (c) 2004 Joerg Wunsch +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 18, 2015 +.Dt PRINTF 9 +.Os +.Sh NAME +.Nm printf , uprintf , tprintf, log +.Nd formatted output conversion +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn printf "const char *fmt" ... +.Ft void +.Fn tprintf "struct proc *p" "int pri" "const char *fmt" ... +.Ft int +.Fn uprintf "const char *fmt" ... +.Ft int +.Fn vprintf "const char *fmt" "va_list ap" +.In sys/syslog.h +.Ft void +.Fn log "int pri" "const char *fmt" ... +.Ft void +.Fn vlog "int pri" "const char *fmt" "va_list ap" +.Sh DESCRIPTION +The +.Xr printf 9 +family of functions are similar to the +.Xr printf 3 +family of functions. +The different functions each use a different output stream. +The +.Fn uprintf +function outputs to the current process' controlling tty, while +.Fn printf +writes to the console as well as to the logging facility. +The +.Fn tprintf +function outputs to the tty associated with the process +.Fa p +and the logging facility if +.Fa pri +is not \-1. +The +.Fn log +function sends the message to the kernel logging facility, using +the log level as indicated by +.Fa pri , +and to the console if no process is yet reading the log. +.Pp +Each of these related functions use the +.Fa fmt +parameter in the same manner as +.Xr printf 3 . +However, +.Xr printf 9 +adds two other conversion specifiers. +.Pp +The +.Cm \&%b +identifier expects two arguments: an +.Vt int +and a +.Vt "char *" . +These are used as a register value and a print mask for decoding bitmasks. +The print mask is made up of two parts: the base and the +arguments. +The base value is the output base expressed as an integer value; +for example, \e10 gives octal and \e20 gives hexadecimal. +The arguments are made up of a sequence of bit identifiers. +Each bit identifier begins with an integer value which is the number of the +bit (starting from 1) this identifier describes. +The rest of the identifier is a string of characters containing the name of +the bit. +The string is terminated by either the bit number at the start of the next +bit identifier or +.Dv NUL +for the last bit identifier. +.Pp +The +.Cm \&%D +identifier is meant to assist in hexdumps. +It requires two arguments: a +.Vt "u_char *" +pointer and a +.Vt "char *" +string. +The memory pointed to be the pointer is output in hexadecimal one byte at +a time. +The string is used as a delimiter between individual bytes. +If present, a width directive will specify the number of bytes to display. +By default, 16 bytes of data are output. +.Pp +The +.Fn log +function uses +.Xr syslog 3 +level values +.Dv LOG_DEBUG +through +.Dv LOG_EMERG +for its +.Fa pri +parameter (mistakenly called +.Sq priority +here). +Alternatively, if a +.Fa pri +of \-1 is given, the message will be appended to the last log message +started by a previous call to +.Fn log . +As these messages are generated by the kernel itself, the facility will +always be +.Dv LOG_KERN . +.Sh RETURN VALUES +The +.Fn printf +and the +.Fn uprintf +functions return the number of characters displayed. +.Sh EXAMPLES +This example demonstrates the use of the +.Cm \&%b +and +.Cm \&%D +conversion specifiers. +The function +.Bd -literal -offset indent +void +printf_test(void) +{ + + printf("reg=%b\en", 3, "\e10\e2BITTWO\e1BITONE"); + printf("out: %4D\en", "AAAA", ":"); +} +.Ed +.Pp +will produce the following output: +.Bd -literal -offset indent +reg=3 +out: 41:41:41:41 +.Ed +.Pp +The call +.Bd -literal -offset indent +log(LOG_DEBUG, "%s%d: been there.\en", sc->sc_name, sc->sc_unit); +.Ed +.Pp +will add the appropriate debug message at priority +.Dq Li kern.debug +to the system log. +.Sh SEE ALSO +.Xr printf 3 , +.Xr syslog 3 Property changes on: user/imp/camdoc/printf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/PHOLD.9 =================================================================== --- user/imp/camdoc/PHOLD.9 (nonexistent) +++ user/imp/camdoc/PHOLD.9 (revision 296049) @@ -0,0 +1,67 @@ +.\" Copyright (c) 2015 Mark Johnston +.\" +.\" 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 November 7, 2015 +.Dt PHOLD 9 +.Os +.Sh NAME +.Nm PHOLD +.Nd hold a process +.Sh SYNOPSIS +.In sys/proc.h +.Fn PHOLD "struct proc *p" +.Fn _PHOLD "struct proc *p" +.Fn PRELE "struct proc *p" +.Fn _PRELE "struct proc *p" +.Fn PROC_ASSERT_HELD "struct proc *p" +.Fn PROC_ASSERT_NOT_HELD "struct proc *p" +.Sh DESCRIPTION +The +.Fn PHOLD +macro increments the hold count of a process, and the +.Fn PRELE +macro decrements the hold count of a process. +.Pp +If a process with a non-zero hold count attempts to exit, it will sleep until +its hold count has reached zero before the kernel begins releasing resources +associated with the process. +Once a process has started exiting, it is invalid to increase its hold count. +Thus, callers must not attempt to hold a process that has the +.Dv P_WEXIT +flag set. +The VM daemon will not swap out the kernel stack of a thread belonging to a +process with a non-zero hold count. +.Pp +The +.Fn _PHOLD +and +.Fn _PRELE +macros are identical to +.Fn PHOLD +and +.Fn PRELE , +except that they must be called with the process lock held. +.Sh AUTHORS +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . Property changes on: user/imp/camdoc/PHOLD.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/sysctl_add_oid.9 =================================================================== --- user/imp/camdoc/sysctl_add_oid.9 (nonexistent) +++ user/imp/camdoc/sysctl_add_oid.9 (revision 296049) @@ -0,0 +1,202 @@ +.\" +.\" Copyright (c) 2000, Andrzej Bialecki +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 November 6, 2015 +.Dt SYSCTL_ADD_OID 9 +.Os +.Sh NAME +.Nm sysctl_add_oid , +.Nm sysctl_move_oid , +.Nm sysctl_remove_oid , +.Nm sysctl_remove_name +.Nd runtime sysctl tree manipulation +.Sh SYNOPSIS +.In sys/types.h +.In sys/sysctl.h +.Ft struct sysctl_oid * +.Fo sysctl_add_oid +.Fa "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *parent" +.Fa "int number" +.Fa "const char *name" +.Fa "int kind" +.Fa "void *arg1" +.Fa "intmax_t arg2" +.Fa "int (*handler) (SYSCTL_HANDLER_ARGS)" +.Fa "const char *format" +.Fa "const char *descr" +.Fc +.Ft int +.Fo sysctl_move_oid +.Fa "struct sysctl_oid *oidp" +.Fa "struct sysctl_oid_list *parent" +.Fc +.Ft int +.Fo sysctl_remove_oid +.Fa "struct sysctl_oid *oidp" +.Fa "int del" +.Fa "int recurse" +.Fc +.Ft int +.Fo sysctl_remove_name +.Fa "struct sysctl_oid *oidp" +.Fa "const char *name" +.Fa "int del" +.Fa "int recurse" +.Fc +.Sh DESCRIPTION +These functions provide the interface for creating and deleting sysctl +OIDs at runtime for example during the lifetime of a module. +The wrapper macros defined by +.Xr sysctl 9 +are recommended when creating new OIDs. +.Fn sysctl_add_oid +should not be called directly from the code. +.Pp +Dynamic OIDs of type +.Dv CTLTYPE_NODE +are reusable +so that several code sections can create and delete them, +but in reality they are allocated and freed +based on their reference count. +As a consequence, +it is possible for two or more code sections +to create partially overlapping trees that they both can use. +It is not possible to create overlapping leaves, +nor to create different child types with the same name and parent. +.Pp +The +.Fn sysctl_add_oid +function creates a raw OID of any type and connects it to its parent node, if any. +If the OID is successfully created, +the function returns a pointer to it else +it returns +.Dv NULL . +Many of the arguments for +.Fn sysctl_add_oid +are common to the wrapper macros defined by +.Xr sysctl 9 . +.Pp +The +.Fn sysctl_move_oid +function reparents an existing OID. +The OID is assigned a new number as if it had been created with +.Fa number +set to +.Dv OID_AUTO . +.Pp +The +.Fn sysctl_remove_oid +function removes a dynamically created OID from the tree and +optionally freeing its resources. +It takes the following arguments: +.Bl -tag -width recurse +.It Fa oidp +A pointer to the dynamic OID to be removed. +If the OID is not dynamic, or the pointer is +.Dv NULL , +the function returns +.Er EINVAL . +.It Fa del +If non-zero, +.Fn sysctl_remove_oid +will try to free the OID's resources +when the reference count of the OID becomes zero. +However, if +.Fa del +is set to 0, +the routine will only deregister the OID from the tree, +without freeing its resources. +This behaviour is useful when the caller expects to rollback +(possibly partially failed) +deletion of many OIDs later. +.It Fa recurse +If non-zero, attempt to remove the node and all its children. +If +.Pa recurse +is set to 0, +any attempt to remove a node that contains any children +will result in a +.Er ENOTEMPTY +error. +.Em WARNING : "use recursive deletion with extreme caution" ! +Normally it should not be needed if contexts are used. +Contexts take care of tracking inter-dependencies +between users of the tree. +However, in some extreme cases it might be necessary +to remove part of the subtree no matter how it was created, +in order to free some other resources. +Be aware, though, that this may result in a system +.Xr panic 9 +if other code sections continue to use removed subtrees. +.El +.Pp +The +.Fn sysctl_remove_name +function looks up the child node matching the +.Fa name +argument and then invokes the +.Fn sysctl_remove_oid +function on that node, passing along the +.Fa del +and +.Fa recurse +arguments. +If a node having the specified name does not exist an error code of +.Er ENOENT +is returned. +Else the error code from +.Fn sysctl_remove_oid +is returned. +.Pp +In most cases the programmer should use contexts, +as described in +.Xr sysctl_ctx_init 9 , +to keep track of created OIDs, +and to delete them later in orderly fashion. +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr sysctl 9 , +.Xr sysctl_ctx_free 9 , +.Xr sysctl_ctx_init 9 +.Sh HISTORY +These functions first appeared in +.Fx 4.2 . +.Sh AUTHORS +.An Andrzej Bialecki Aq Mt abial@FreeBSD.org +.Sh BUGS +Sharing nodes between many code sections +causes interdependencies that sometimes may lock the resources. +For example, +if module A hooks up a subtree to an OID created by module B, +module B will be unable to delete that OID. +These issues are handled properly by sysctl contexts. +.Pp +Many operations on the tree involve traversing linked lists. +For this reason, OID creation and removal is relatively costly. Property changes on: user/imp/camdoc/sysctl_add_oid.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/sysctl.9 =================================================================== --- user/imp/camdoc/sysctl.9 (nonexistent) +++ user/imp/camdoc/sysctl.9 (revision 296049) @@ -0,0 +1,852 @@ +.\" +.\" 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 enviroment 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 enviroment 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 +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 +enviroment 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 frequence 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: +.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 Property changes on: user/imp/camdoc/sysctl.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUS_ADD_CHILD.9 =================================================================== --- user/imp/camdoc/BUS_ADD_CHILD.9 (nonexistent) +++ user/imp/camdoc/BUS_ADD_CHILD.9 (revision 296049) @@ -0,0 +1,89 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2004 M. Warner Losh. +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 28, 2015 +.Dt BUS_ADD_CHILD 9 +.Os +.Sh NAME +.Nm BUS_ADD_CHILD +.Nd "add a device node to the tree with a given priority" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn BUS_ADD_CHILD "device_t dev" "int order" "const char *name" "int unit" +.Sh DESCRIPTION +The +.Fn BUS_ADD_CHILD +method +is used by the driver identify routine to add devices to the tree. +It can also be used to add children to buses that implement this +routine in other contexts, although the behavior is bus specific. +Please see +.Xr device_add_child 9 +for more details. +The interface is the same as +.Xr device_add_child 9 +however, the bus' +.Fn BUS_ADD_CHILD +is called. +.Pp +Buses implementing +.Fn BUS_ADD_CHILD +should insert the device into the tree using +.Xr device_add_child 9 +before adding things such as their own ivars and resource lists to the device. +.Fn BUS_ADD_CHILD +is not called by +.Xr device_add_child 9 . +.Fn BUS_ADD_CHILD +instead calls +.Xr device_add_child 9 . +.Pp +A panic will result when called for a bus that does not implement +.Fn BUS_ADD_CHILD . +Some buses require a special bus-specific routine to be called instead +of +.Fn BUS_ADD_CHILD . +.Sh RETURN VALUES +The +.Fn BUS_ADD_CHILD +method returns +.Vt device_t +added to the tree, or +.Dv NULL +to indicate failure. +.Sh SEE ALSO +.Xr device 9 , +.Xr device_add_child 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An M. Warner Losh . Property changes on: user/imp/camdoc/BUS_ADD_CHILD.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_add_child.9 =================================================================== --- user/imp/camdoc/device_add_child.9 (nonexistent) +++ user/imp/camdoc/device_add_child.9 (revision 296049) @@ -0,0 +1,133 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 28, 2015 +.Dt DEVICE_ADD_CHILD 9 +.Os +.Sh NAME +.Nm device_add_child , +.Nm device_add_child_ordered +.Nd "add a new device as a child of an existing device" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn device_add_child "device_t dev" "const char *name" "int unit" +.Ft device_t +.Fn device_add_child_ordered "device_t dev" "int order" "const char *name" "int unit" +.Sh DESCRIPTION +Create a new child device of +.Fa dev . +The +.Fa name +and +.Fa unit +arguments specify the name and unit number of the device. +If the name is unknown then the caller should pass +.Dv NULL . +If the unit is unknown then the caller should pass +.Dv -1 +and the system will choose the next available unit number. +.Pp +The name of the device is used to determine which drivers might be +appropriate for the device. +If a name is specified then only drivers of that name are probed. +If no name is given then all drivers for the owning bus are probed. +In any event, only the name of the device is stored so that one may +safely unload/load a driver bound to that name. +.Pp +This allows busses which can uniquely identify device instances (such +as PCI) to allow each driver to check each device instance for a +match. +For busses which rely on supplied probe hints where only one +driver can have a chance of probing the device, the driver name should +be specified as the device name. +.Pp +Normally unit numbers will be chosen automatically by the system and a +unit number of +.Dv -1 +should be given. +When a specific unit number is desired (e.g.,\& for wiring a particular +piece of hardware to a pre-configured unit number), that unit should +be passed. +If the specified unit number is already allocated, a new +unit will be allocated and a diagnostic message printed. +.Pp +If the devices attached to a bus must be probed in a specific order +(e.g.,\& for the ISA bus some devices are sensitive to failed probe attempts +of unrelated drivers and therefore must be probed first), +the +.Fa order +argument of +.Fn device_add_child_ordered +should be used to specify a partial ordering. +The new device will be added before any existing device with a greater +order. +If +.Fn device_add_child +is used, then the new child will be added as if its order was zero. +.Pp +When adding a device in the context of +.Xr DEVICE_IDENTIFY 9 +routine, the +.Xr device_find_child 9 +routine should be used to ensure that the device has not already been +added to the tree. +Because the device name and +.Vt devclass_t +are associated at probe time (not child addition time), previous +instances of the driver (say in a module that was later unloaded) may +have already added the instance. +Authors of bus drivers must likewise be careful when adding children +when they are loaded and unloaded to avoid duplication of children +devices. +.Pp +When adding a child to another device node, such as in an identify +routine, use +.Xr BUS_ADD_CHILD 9 +instead of +.Xr device_add_child 9 . +.Xr BUS_ADD_CHILD 9 +will call +.Xr device_add_child 9 +and add the proper bus-specific data to the new child. +.Fn device_add_child +does not call +.Xr BUS_ADD_CHILD 9 . +.Sh RETURN VALUES +The new device if successful, NULL otherwise. +.Sh SEE ALSO +.Xr BUS_ADD_CHILD 9 , +.Xr device 9 , +.Xr device_find_child 9 , +.Xr DEVICE_IDENTIFY 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_add_child.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/getenv.9 =================================================================== --- user/imp/camdoc/getenv.9 (nonexistent) +++ user/imp/camdoc/getenv.9 (revision 296049) @@ -0,0 +1,222 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 22, 2015 +.Dt GETENV 9 +.Os +.Sh NAME +.Nm freeenv , +.Nm getenv , +.Nm getenv_int , +.Nm getenv_long , +.Nm getenv_string , +.Nm getenv_quad , +.Nm getenv_uint , +.Nm getenv_ulong , +.Nm setenv , +.Nm testenv , +.Nm unsetenv +.Nd kernel environment variable functions +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Ft void +.Fn freeenv "char *env" +.Ft char * +.Fn getenv "const char *name" +.Ft int +.Fn getenv_int "const char *name" "int *data" +.Ft int +.Fn getenv_long "const char *name" "long *data" +.Ft int +.Fn getenv_string "const char *name" "char *data" "int size" +.Ft int +.Fn getenv_quad "const char *name" "quad_t *data" +.Ft int +.Fn getenv_uint "const char *name" "unsigned int *data" +.Ft int +.Fn getenv_ulong "const char *name" "unsigned long *data" +.Ft int +.Fn setenv "const char *name" "const char *value" +.Ft int +.Fn testenv "const char *name" +.Ft int +.Fn unsetenv "const char *name" +.Sh DESCRIPTION +These functions set, unset, fetch, and parse variables from the kernel's +environment. +.Pp +The +.Fn getenv +function obtains the current value of the kernel environment variable +.Fa name +and returns a pointer to the string value. +The caller should not modify the string pointed to by the return value. +The +.Fn getenv +function may allocate temporary storage, +so the +.Fn freeenv +function must be called to release any allocated resources when the value +returned by +.Fn getenv +is no longer needed. +.Pp +The +.Fn freeenv +function is used to release the resources allocated by a previous call to +.Fn getenv . +The +.Fa env +argument passed to +.Fn freeenv +is the pointer returned by the earlier call to +.Fn getenv . +Like +.Xr free 3 , +the +.Fa env +argument can be +.Va NULL , +in which case no action occurs. +.Pp +The +.Fn setenv +function inserts or resets the kernel environment variable +.Fa name +to +.Fa value . +If the variable +.Fa name +already exists, +its value is replaced. +This function can fail if an internal limit on the number of environment +variables is exceeded. +.Pp +The +.Fn unsetenv +function deletes the kernel environment variable +.Fa name . +.Pp +The +.Fn testenv +function is used to determine if a kernel environment variable exists. +It returns a non-zero value if the variable +.Fa name +exists and zero if it does not. +.Pp +The +.Fn getenv_int , +.Fn getenv_long , +.Fn getenv_quad , +.Fn getenv_uint , +and +.Fn getenv_ulong +functions look for a kernel environment variable +.Fa name +and parse it as a signed integer, +long integer, +signed 64-bit integer, +unsigned integer, +or an unsigned long integer, +respectively. +These functions fail and return zero if +.Fa name +does not exist or if any invalid characters are present in its value. +On success, +these function store the parsed value in the integer variable pointed to +by +.Fa data . +If the parsed value overflows the integer type, +a truncated value is stored in +.Fa data +and zero is returned. +If the value begins with a prefix of +.Dq 0x +it is interpreted as hexadecimal. +If it begins with a prefix of +.Dq 0 +it is interpreted as octal. +Otherwise, +the value is interpreted as decimal. +The value may contain a single character suffix specifying a unit for +the value. +The interpreted value is multiplied by the unit's magnitude before being +returned. +The following unit suffixes are supported: +.Bl -column -offset indent ".Sy Unit" ".Sy Magnitude" +.It Sy Unit Ta Sy Magnitude +.It k Ta 2^10 +.It m Ta 2^20 +.It g Ta 2^30 +.It t Ta 2^40 +.El +.Pp +The +.Fn getenv_string +function stores a copy of the kernel environment variable +.Fa name +in the buffer described by +.Fa data +and +.Fa size. +If the variable does not exist, +zero is returned. +If the variable exists, +up to +.Fa size - 1 +characters of its value are copied to the buffer pointed to by +.Fa data +followed by a null character and a non-zero value is returned. +.Sh RETURN VALUES +The +.Fn getenv +function returns a pointer to an environment variable's value on success or +.Dv NULL +if the variable does not exist. +.Pp +The +.Fn setenv +and +.Fn unsetenv +functions return zero on success and -1 on failure. +.Pp +The +.Fn testenv +function returns zero if the specified environment variable does not exist and +a non-zero value if it does exist. +The +.Fn getenv_int , +.Fn getenv_long , +.Fn getenv_string , +.Fn getenv_quad , +.Fn getenv_uint , +and +.Fn getenv_ulong +functions return a non-zero value on success and zero on failure. Property changes on: user/imp/camdoc/getenv.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/cpuset.9 =================================================================== --- user/imp/camdoc/cpuset.9 (nonexistent) +++ user/imp/camdoc/cpuset.9 (revision 296049) @@ -0,0 +1,352 @@ +.\" Copyright (c) 2015 Conrad Meyer +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 20, 2015 +.Dt CPUSET 9 +.Os +.Sh NAME +.Nm cpuset(9) +\(em +.Nm CPUSET_T_INITIALIZER , +.Nm CPUSET_FSET , +.Nm CPU_CLR , +.Nm CPU_COPY , +.Nm CPU_ISSET , +.Nm CPU_SET , +.Nm CPU_ZERO , +.Nm CPU_FILL , +.Nm CPU_SETOF , +.Nm CPU_EMPTY , +.Nm CPU_ISFULLSET , +.Nm CPU_FFS , +.Nm CPU_COUNT , +.Nm CPU_SUBSET , +.Nm CPU_OVERLAP , +.Nm CPU_CMP , +.Nm CPU_OR , +.Nm CPU_AND , +.Nm CPU_NAND , +.Nm CPU_CLR_ATOMIC , +.Nm CPU_SET_ATOMIC , +.Nm CPU_SET_ATOMIC_ACQ , +.Nm CPU_AND_ATOMIC , +.Nm CPU_OR_ATOMIC , +.Nm CPU_COPY_STORE_REL +.Nd cpuset manipulation macros +.Sh SYNOPSIS +.In sys/_cpuset.h +.In sys/cpuset.h +.\" +.Fn CPUSET_T_INITIALIZER "ARRAY_CONTENTS" +.Vt CPUSET_FSET +.\" +.Fn CPU_CLR "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_COPY "cpuset_t *from" "cpuset_t *to" +.Ft bool +.Fn CPU_ISSET "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_ZERO "cpuset_t *cpuset" +.Fn CPU_FILL "cpuset_t *cpuset" +.Fn CPU_SETOF "size_t cpu_idx" "cpuset_t *cpuset" +.Ft bool +.Fn CPU_EMPTY "cpuset_t *cpuset" +.Ft bool +.Fn CPU_ISFULLSET "cpuset_t *cpuset" +.Ft size_t +.Fn CPU_FFS "cpuset_t *cpuset" +.Ft size_t +.Fn CPU_COUNT "cpuset_t *cpuset" +.\" +.Ft bool +.Fn CPU_SUBSET "cpuset_t *haystack" "cpuset_t *needle" +.Ft bool +.Fn CPU_OVERLAP "cpuset_t *cpuset1" "cpuset_t *cpuset2" +.Ft bool +.Fn CPU_CMP "cpuset_t *cpuset1" "cpuset_t *cpuset2" +.Fn CPU_OR "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_AND "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_NAND "cpuset_t *dst" "cpuset_t *src" +.\" +.Fn CPU_CLR_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET_ATOMIC "size_t cpu_idx" "cpuset_t *cpuset" +.Fn CPU_SET_ATOMIC_ACQ "size_t cpu_idx" "cpuset_t *cpuset" +.\" +.Fn CPU_AND_ATOMIC "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_OR_ATOMIC "cpuset_t *dst" "cpuset_t *src" +.Fn CPU_COPY_STORE_REL "cpuset_t *from" "cpuset_t *to" +.Sh DESCRIPTION +The +.Nm +family of macros provide a flexible and efficient CPU set implementation, +backed by the +.Xr bitset 9 +macros. +Each CPU is represented by a single bit. +The maximum number of CPUs representable by +.Vt cpuset_t +is +.Va MAXCPU . +Individual CPUs in cpusets are referenced with indices zero through +.Fa MAXCPU - 1 . +.Pp +The +.Fn CPUSET_T_INITIALIZER +macro allows one to initialize a +.Vt cpuset_t +with a compile time literal value. +.Pp +The +.Fn CPUSET_FSET +macro defines a compile time literal, usable by +.Fn CPUSET_T_INITIALIZER , +representing a full cpuset (all CPUs present). +For examples of +.Fn CPUSET_T_INITIALIZER +and +.Fn CPUSET_FSET +usage, see the +.Sx CPUSET_T_INITIALIZER EXAMPLE +section. +.Pp +The +.Fn CPU_CLR +macro removes CPU +.Fa cpu_idx +from the cpuset pointed to by +.Fa cpuset . +The +.Fn CPU_CLR_ATOMIC +macro is identical, but the bit representing the CPU is cleared with atomic +machine instructions. +.Pp +The +.Fn CPU_COPY +macro copies the contents of the cpuset +.Fa from +to the cpuset +.Fa to . +.Fn CPU_COPY_STORE_REL +is similar, but copies component machine words from +.Fa from +and writes them to +.Fa to +with atomic store with release semantics. +(That is, if +.Fa to +is composed of multiple machine words, +.Fn CPU_COPY_STORE_REL +performs multiple individually atomic operations.) +.Pp +The +.Fn CPU_SET +macro adds CPU +.Fa cpu_idx +to the cpuset pointed to by +.Fa cpuset , +if it is not already present. +The +.Fn CPU_SET_ATOMIC +macro is identical, but the bit representing the CPU is set with atomic +machine instructions. +The +.Fn CPU_SET_ATOMIC_ACQ +macro sets the bit representing the CPU with atomic acquire semantics. +.Pp +The +.Fn CPU_ZERO +macro removes all CPUs from +.Fa cpuset . +.Pp +The +.Fn CPU_FILL +macro adds all CPUs to +.Fa cpuset . +.Pp +The +.Fn CPU_SETOF +macro removes all CPUs in +.Fa cpuset +before adding only CPU +.Fa cpu_idx . +.Pp +The +.Fn CPU_EMPTY +macro returns +.Dv true +if +.Fa cpuset +is empty. +.Pp +The +.Fn CPU_ISFULLSET +macro returns +.Dv true +if +.Fa cpuset +is full (the set of all CPUs). +.Pp +The +.Fn CPU_FFS +macro returns the 1-index of the first (lowest) CPU in +.Fa cpuset , +or zero if +.Fa cpuset +is empty. +Like with +.Xr ffs 3 , +to use the non-zero result of +.Fn CPU_FFS +as a +.Fa cpu_idx +index parameter to any other +.Nm +macro, you must subtract one from the result. +.Pp +The +.Fn CPU_COUNT +macro returns the total number of CPUs in +.Fa cpuset . +.Pp +The +.Fn CPU_SUBSET +macro returns +.Dv true +if +.Fa needle +is a subset of +.Fa haystack . +.Pp +The +.Fn CPU_OVERLAP +macro returns +.Dv true +if +.Fa cpuset1 +and +.Fa cpuset2 +have any common CPUs. +(That is, if +.Fa cpuset1 +AND +.Fa cpuset2 +is not the empty set.) +.Pp +The +.Fn CPU_CMP +macro returns +.Dv true +if +.Fa cpuset1 +is NOT equal to +.Fa cpuset2 . +.Pp +The +.Fn CPU_OR +macro adds CPUs present in +.Fa src +to +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +|= +.Fa src . ) +.Fn CPU_OR_ATOMIC +is similar, but sets the bits representing CPUs in the component machine words +in +.Fa dst +with atomic machine instructions. +(That is, if +.Fa dst +is composed of multiple machine words, +.Fn CPU_OR_ATOMIC +performs multiple individually atomic operations.) +.Pp +The +.Fn CPU_AND +macro removes CPUs absent from +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa src . ) +.Fn CPU_AND_ATOMIC +is similar, with the same atomic semantics as +.Fn CPU_OR_ATOMIC . +.Pp +The +.Fn CPU_NAND +macro removes CPUs in +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa ~ src . ) +.Sh CPUSET_T_INITIALIZER EXAMPLE +.Bd -literal +cpuset_t myset; + +/* Initialize myset to filled (all CPUs) */ +myset = CPUSET_T_INITIALIZER(CPUSET_FSET); + +/* Initialize myset to only the lowest CPU */ +myset = CPUSET_T_INITIALIZER(0x1); +.Ed +.Sh SEE ALSO +.Xr cpuset 1 , +.Xr cpuset 2 , +.Xr bitset 9 +.Sh HISTORY +.In sys/cpuset.h +first appeared in +.Fx 7.1 , +released in January 2009, and in +.Fx 8.0 , +released in November 2009. +.Pp +This manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +macros were written by +.An Jeff Roberson Aq Mt jeff@FreeBSD.org . +This manual page was written by +.An Conrad Meyer Aq Mt cem@FreeBSD.org . +.Sh CAVEATS +Unlike every other reference to individual set members, which are zero-indexed, +.Fn CPU_FFS +returns a one-indexed result (or zero if the cpuset is empty). Property changes on: user/imp/camdoc/cpuset.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/bitset.9 =================================================================== --- user/imp/camdoc/bitset.9 (nonexistent) +++ user/imp/camdoc/bitset.9 (revision 296049) @@ -0,0 +1,391 @@ +.\" Copyright (c) 2015 Conrad Meyer +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' +.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 20, 2015 +.Dt BITSET 9 +.Os +.Sh NAME +.Nm bitset(9) +\(em +.Nm BITSET_DEFINE , +.Nm BITSET_T_INITIALIZER , +.Nm BITSET_FSET , +.Nm BIT_CLR , +.Nm BIT_COPY , +.Nm BIT_ISSET , +.Nm BIT_SET , +.Nm BIT_ZERO , +.Nm BIT_FILL , +.Nm BIT_SETOF , +.Nm BIT_EMPTY , +.Nm BIT_ISFULLSET , +.Nm BIT_FFS , +.Nm BIT_COUNT , +.Nm BIT_SUBSET , +.Nm BIT_OVERLAP , +.Nm BIT_CMP , +.Nm BIT_OR , +.Nm BIT_AND , +.Nm BIT_NAND , +.Nm BIT_CLR_ATOMIC , +.Nm BIT_SET_ATOMIC , +.Nm BIT_SET_ATOMIC_ACQ , +.Nm BIT_AND_ATOMIC , +.Nm BIT_OR_ATOMIC , +.Nm BIT_COPY_STORE_REL +.Nd bitset manipulation macros +.Sh SYNOPSIS +.In sys/_bitset.h +.In sys/bitset.h +.\" +.Fn BITSET_DEFINE "STRUCTNAME" "const SETSIZE" +.Fn BITSET_T_INITIALIZER "ARRAY_CONTENTS" +.Fn BITSET_FSET "N_WORDS" +.\" +.Fn BIT_CLR "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_COPY "const SETSIZE" "struct STRUCTNAME *from" "struct STRUCTNAME *to" +.Ft bool +.Fn BIT_ISSET "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_SET "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_ZERO "const SETSIZE" "struct STRUCTNAME *bitset" +.Fn BIT_FILL "const SETSIZE" "struct STRUCTNAME *bitset" +.Fn BIT_SETOF "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Ft bool +.Fn BIT_EMPTY "const SETSIZE" "struct STRUCTNAME *bitset" +.Ft bool +.Fn BIT_ISFULLSET "const SETSIZE" "struct STRUCTNAME *bitset" +.Ft size_t +.Fn BIT_FFS "const SETSIZE" "struct STRUCTNAME *bitset" +.Ft size_t +.Fn BIT_COUNT "const SETSIZE" "struct STRUCTNAME *bitset" +.\" +.Ft bool +.Fo BIT_SUBSET +.Fa "const SETSIZE" "struct STRUCTNAME *haystack" "struct STRUCTNAME *needle" +.Fc +.Ft bool +.Fo BIT_OVERLAP +.Fa "const SETSIZE" "struct STRUCTNAME *bitset1" "struct STRUCTNAME *bitset2" +.Fc +.Ft bool +.Fo BIT_CMP +.Fa "const SETSIZE" "struct STRUCTNAME *bitset1" "struct STRUCTNAME *bitset2" +.Fc +.Fn BIT_OR "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fn BIT_AND "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fn BIT_NAND "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.\" +.Fn BIT_CLR_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_SET_ATOMIC "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.Fn BIT_SET_ATOMIC_ACQ "const SETSIZE" "size_t bit" "struct STRUCTNAME *bitset" +.\" +.Fo BIT_AND_ATOMIC +.Fa "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fc +.Fo BIT_OR_ATOMIC +.Fa "const SETSIZE" "struct STRUCTNAME *dst" "struct STRUCTNAME *src" +.Fc +.Fo BIT_COPY_STORE_REL +.Fa "const SETSIZE" "struct STRUCTNAME *from" "struct STRUCTNAME *to" +.Fc +.Sh DESCRIPTION +The +.Nm +family of macros provide a flexible and efficient bitset implementation if the +maximum size of the set is known at compilation. +Throughout this manual page, the name +.Fa SETSIZE +refers to the size of the bitset in bits. +Individual bits in bitsets are referenced with indices zero through +.Fa SETSIZE - 1 . +One example use of +.In sys/bitset.h +is +.In sys/cpuset.h . +.Pp +The +.Fn BITSET_DEFINE +macro defines a bitset struct +.Fa STRUCTNAME +with room to represent +.Fa SETSIZE +bits. +.Pp +The +.Fn BITSET_T_INITIALIZER +macro allows one to initialize a bitset struct with a compile time literal +value. +.Pp +The +.Fn BITSET_FSET +macro generates a compile time literal, usable by +.Fn BITSET_T_INITIALIZER , +representing a full bitset (all bits set). +For examples of +.Fn BITSET_T_INITIALIZER +and +.Fn BITSET_FSET +usage, see the +.Sx BITSET_T_INITIALIZER EXAMPLE +section. +The +.Fa N_WORDS +parameter to +.Fn BITSET_FSET +should be: +.Bd -literal -offset indent +__bitset_words(SETSIZE) +.Ed +.Pp +The +.Fn BIT_CLR +macro clears bit +.Fa bit +in the bitset pointed to by +.Fa bitset . +The +.Fn BIT_CLR_ATOMIC +macro is identical, but the bit is cleared atomically. +.Pp +The +.Fn BIT_COPY +macro copies the contents of the bitset +.Fa from +to the bitset +.Fa to . +.Fn BIT_COPY_STORE_REL +is similar, but copies component machine words from +.Fa from +and writes them to +.Fa to +with atomic store with release semantics. +(That is, if +.Fa to +is composed of multiple machine words, +.Fn BIT_COPY_STORE_REL +performs multiple individually atomic operations.) +.Pp +The +.Fn BIT_SET +macro sets bit +.Fa bit +in the bitset pointed to by +.Fa bitset . +The +.Fn BIT_SET_ATOMIC +macro is identical, but the bit is set atomically. +The +.Fn BIT_SET_ATOMIC_ACQ +macro sets the bit with acquire semantics. +.Pp +The +.Fn BIT_ZERO +macro clears all bits in +.Fa bitset . +.Pp +The +.Fn BIT_FILL +macro sets all bits in +.Fa bitset . +.Pp +The +.Fn BIT_SETOF +macro clears all bits in +.Fa bitset +before setting only bit +.Fa bit . +.Pp +The +.Fn BIT_EMPTY +macro returns +.Dv true +if +.Fa bitset +is empty. +.Pp +The +.Fn BIT_ISFULLSET +macro returns +.Dv true +if +.Fa bitset +is full (all bits set). +.Pp +The +.Fn BIT_FFS +macro returns the 1-index of the first (lowest) set bit in +.Fa bitset , +or zero if +.Fa bitset +is empty. +Like with +.Xr ffs 3 , +to use the non-zero result of +.Fn BIT_FFS +as a +.Fa bit +index parameter to any other +.Nm +macro, you must subtract one from the result. +.Pp +The +.Fn BIT_COUNT +macro returns the total number of set bits in +.Fa bitset . +.Pp +The +.Fn BIT_SUBSET +macro returns +.Dv true +if +.Fa needle +is a subset of +.Fa haystack . +.Pp +The +.Fn BIT_OVERLAP +macro returns +.Dv true +if +.Fa bitset1 +and +.Fa bitset2 +have any common bits. +(That is, if +.Fa bitset1 +AND +.Fa bitset2 +is not the empty set.) +.Pp +The +.Fn BIT_CMP +macro returns +.Dv true +if +.Fa bitset1 +is NOT equal to +.Fa bitset2 . +.Pp +The +.Fn BIT_OR +macro sets bits present in +.Fa src +in +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +|= +.Fa src . ) +.Fn BIT_OR_ATOMIC +is similar, but sets bits in the component machine words in +.Fa dst +atomically. +(That is, if +.Fa dst +is composed of multiple machine words, +.Fn BIT_OR_ATOMIC +performs multiple individually atomic operations.) +.Pp +The +.Fn BIT_AND +macro clears bits absent from +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa src . ) +.Fn BIT_AND_ATOMIC +is similar, with the same atomic semantics as +.Fn BIT_OR_ATOMIC . +.Pp +The +.Fn BIT_NAND +macro clears bits set in +.Fa src +from +.Fa dst . +(It is the +.Nm +equivalent of the scalar: +.Fa dst +&= +.Fa ~ src . ) +.Sh BITSET_T_INITIALIZER EXAMPLE +.Bd -literal +BITSET_DEFINE(_myset, MYSETSIZE); + +struct _myset myset; + +/* Initialize myset to filled (all bits set) */ +myset = BITSET_T_INITIALIZER(BITSET_FSET(__bitset_words(MYSETSIZE))); + +/* Initialize myset to only the lowest bit set */ +myset = BITSET_T_INITIALIZER(0x1); +.Ed +.Sh SEE ALSO +.Xr bitstring 3 , +.Xr cpuset 9 +.Sh HISTORY +The +.Nm +macros first appeared in +.Fx 10.0 +in January 2014. +They were MFCed to +.Fx 9.3 , +released in July 2014. +.Pp +This manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +macros were generalized and pulled out of +.In sys/cpuset.h +as +.In sys/_bitset.h +and +.In sys/bitset.h +by +.An Attilio Rao Aq Mt attilio@FreeBSD.org . +This manual page was written by +.An Conrad Meyer Aq Mt cem@FreeBSD.org . +.Sh CAVEATS +The +.Fa SETSIZE +argument to all of these macros must match the value given to +.Fn BITSET_DEFINE . +.Pp +Unlike every other reference to individual set members, which are zero-indexed, +.Fn BIT_FFS +returns a one-indexed result (or zero if the set is empty). Property changes on: user/imp/camdoc/bitset.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/mbuf.9 =================================================================== --- user/imp/camdoc/mbuf.9 (nonexistent) +++ user/imp/camdoc/mbuf.9 (revision 296049) @@ -0,0 +1,1209 @@ +.\" Copyright (c) 2000 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 March 11, 2015 +.Dt MBUF 9 +.Os +.\" +.Sh NAME +.Nm mbuf +.Nd "memory management in the kernel IPC subsystem" +.\" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/mbuf.h +.\" +.Ss Mbuf allocation macros +.Fn MGET "struct mbuf *mbuf" "int how" "short type" +.Fn MGETHDR "struct mbuf *mbuf" "int how" "short type" +.Ft int +.Fn MCLGET "struct mbuf *mbuf" "int how" +.Fo MEXTADD +.Fa "struct mbuf *mbuf" +.Fa "caddr_t buf" +.Fa "u_int size" +.Fa "void (*free)(void *opt_arg1, void *opt_arg2)" +.Fa "void *opt_arg1" +.Fa "void *opt_arg2" +.Fa "short flags" +.Fa "int type" +.Fc +.\" +.Ss Mbuf utility macros +.Fn mtod "struct mbuf *mbuf" "type" +.Fn M_ALIGN "struct mbuf *mbuf" "u_int len" +.Fn MH_ALIGN "struct mbuf *mbuf" "u_int len" +.Ft int +.Fn M_LEADINGSPACE "struct mbuf *mbuf" +.Ft int +.Fn M_TRAILINGSPACE "struct mbuf *mbuf" +.Fn M_MOVE_PKTHDR "struct mbuf *to" "struct mbuf *from" +.Fn M_PREPEND "struct mbuf *mbuf" "int len" "int how" +.Fn MCHTYPE "struct mbuf *mbuf" "short type" +.Ft int +.Fn M_WRITABLE "struct mbuf *mbuf" +.\" +.Ss Mbuf allocation functions +.Ft struct mbuf * +.Fn m_get "int how" "short type" +.Ft struct mbuf * +.Fn m_get2 "int size" "int how" "short type" "int flags" +.Ft struct mbuf * +.Fn m_getm "struct mbuf *orig" "int len" "int how" "short type" +.Ft struct mbuf * +.Fn m_getjcl "int how" "short type" "int flags" "int size" +.Ft struct mbuf * +.Fn m_getcl "int how" "short type" "int flags" +.Ft struct mbuf * +.Fn m_getclr "int how" "short type" +.Ft struct mbuf * +.Fn m_gethdr "int how" "short type" +.Ft struct mbuf * +.Fn m_free "struct mbuf *mbuf" +.Ft void +.Fn m_freem "struct mbuf *mbuf" +.\" +.Ss Mbuf utility functions +.Ft void +.Fn m_adj "struct mbuf *mbuf" "int len" +.Ft void +.Fn m_align "struct mbuf *mbuf" "int len" +.Ft int +.Fn m_append "struct mbuf *mbuf" "int len" "c_caddr_t cp" +.Ft struct mbuf * +.Fn m_prepend "struct mbuf *mbuf" "int len" "int how" +.Ft struct mbuf * +.Fn m_copyup "struct mbuf *mbuf" "int len" "int dstoff" +.Ft struct mbuf * +.Fn m_pullup "struct mbuf *mbuf" "int len" +.Ft struct mbuf * +.Fn m_pulldown "struct mbuf *mbuf" "int offset" "int len" "int *offsetp" +.Ft struct mbuf * +.Fn m_copym "struct mbuf *mbuf" "int offset" "int len" "int how" +.Ft struct mbuf * +.Fn m_copypacket "struct mbuf *mbuf" "int how" +.Ft struct mbuf * +.Fn m_dup "struct mbuf *mbuf" "int how" +.Ft void +.Fn m_copydata "const struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" +.Ft void +.Fn m_copyback "struct mbuf *mbuf" "int offset" "int len" "caddr_t buf" +.Ft struct mbuf * +.Fo m_devget +.Fa "char *buf" +.Fa "int len" +.Fa "int offset" +.Fa "struct ifnet *ifp" +.Fa "void (*copy)(char *from, caddr_t to, u_int len)" +.Fc +.Ft void +.Fn m_cat "struct mbuf *m" "struct mbuf *n" +.Ft u_int +.Fn m_fixhdr "struct mbuf *mbuf" +.Ft void +.Fn m_dup_pkthdr "struct mbuf *to" "struct mbuf *from" +.Ft void +.Fn m_move_pkthdr "struct mbuf *to" "struct mbuf *from" +.Ft u_int +.Fn m_length "struct mbuf *mbuf" "struct mbuf **last" +.Ft struct mbuf * +.Fn m_split "struct mbuf *mbuf" "int len" "int how" +.Ft int +.Fn m_apply "struct mbuf *mbuf" "int off" "int len" "int (*f)(void *arg, void *data, u_int len)" "void *arg" +.Ft struct mbuf * +.Fn m_getptr "struct mbuf *mbuf" "int loc" "int *off" +.Ft struct mbuf * +.Fn m_defrag "struct mbuf *m0" "int how" +.Ft struct mbuf * +.Fn m_collapse "struct mbuf *m0" "int how" "int maxfrags" +.Ft struct mbuf * +.Fn m_unshare "struct mbuf *m0" "int how" +.\" +.Sh DESCRIPTION +An +.Vt mbuf +is a basic unit of memory management in the kernel IPC subsystem. +Network packets and socket buffers are stored in +.Vt mbufs . +A network packet may span multiple +.Vt mbufs +arranged into a +.Vt mbuf chain +(linked list), +which allows adding or trimming +network headers with little overhead. +.Pp +While a developer should not bother with +.Vt mbuf +internals without serious +reason in order to avoid incompatibilities with future changes, it +is useful to understand the general structure of an +.Vt mbuf . +.Pp +An +.Vt mbuf +consists of a variable-sized header and a small internal +buffer for data. +The total size of an +.Vt mbuf , +.Dv MSIZE , +is a constant defined in +.In sys/param.h . +The +.Vt mbuf +header includes: +.Bl -tag -width "m_nextpkt" -offset indent +.It Va m_next +.Pq Vt struct mbuf * +A pointer to the next +.Vt mbuf +in the +.Vt mbuf chain . +.It Va m_nextpkt +.Pq Vt struct mbuf * +A pointer to the next +.Vt mbuf chain +in the queue. +.It Va m_data +.Pq Vt caddr_t +A pointer to data attached to this +.Vt mbuf . +.It Va m_len +.Pq Vt int +The length of the data. +.It Va m_type +.Pq Vt short +The type of the data. +.It Va m_flags +.Pq Vt int +The +.Vt mbuf +flags. +.El +.Pp +The +.Vt mbuf +flag bits are defined as follows: +.Bd -literal +/* mbuf flags */ +#define M_EXT 0x00000001 /* has associated external storage */ +#define M_PKTHDR 0x00000002 /* start of record */ +#define M_EOR 0x00000004 /* end of record */ +#define M_RDONLY 0x00000008 /* associated data marked read-only */ +#define M_PROTO1 0x00001000 /* protocol-specific */ +#define M_PROTO2 0x00002000 /* protocol-specific */ +#define M_PROTO3 0x00004000 /* protocol-specific */ +#define M_PROTO4 0x00008000 /* protocol-specific */ +#define M_PROTO5 0x00010000 /* protocol-specific */ +#define M_PROTO6 0x00020000 /* protocol-specific */ +#define M_PROTO7 0x00040000 /* protocol-specific */ +#define M_PROTO8 0x00080000 /* protocol-specific */ +#define M_PROTO9 0x00100000 /* protocol-specific */ +#define M_PROTO10 0x00200000 /* protocol-specific */ +#define M_PROTO11 0x00400000 /* protocol-specific */ +#define M_PROTO12 0x00800000 /* protocol-specific */ + +/* mbuf pkthdr flags (also stored in m_flags) */ +#define M_BCAST 0x00000010 /* send/received as link-level broadcast */ +#define M_MCAST 0x00000020 /* send/received as link-level multicast */ +.Ed +.Pp +The available +.Vt mbuf +types are defined as follows: +.Bd -literal +/* mbuf types */ +#define MT_DATA 1 /* dynamic (data) allocation */ +#define MT_HEADER MT_DATA /* packet header */ +#define MT_SONAME 8 /* socket name */ +#define MT_CONTROL 14 /* extra-data protocol message */ +#define MT_OOBDATA 15 /* expedited data */ +.Ed +.Pp +The available external buffer types are defined as follows: +.Bd -literal +/* external buffer types */ +#define EXT_CLUSTER 1 /* mbuf cluster */ +#define EXT_SFBUF 2 /* sendfile(2)'s sf_bufs */ +#define EXT_JUMBOP 3 /* jumbo cluster 4096 bytes */ +#define EXT_JUMBO9 4 /* jumbo cluster 9216 bytes */ +#define EXT_JUMBO16 5 /* jumbo cluster 16184 bytes */ +#define EXT_PACKET 6 /* mbuf+cluster from packet zone */ +#define EXT_MBUF 7 /* external mbuf reference (M_IOVEC) */ +#define EXT_NET_DRV 252 /* custom ext_buf provided by net driver(s) */ +#define EXT_MOD_TYPE 253 /* custom module's ext_buf type */ +#define EXT_DISPOSABLE 254 /* can throw this buffer away w/page flipping */ +#define EXT_EXTREF 255 /* has externally maintained ref_cnt ptr */ +.Ed +.Pp +If the +.Dv M_PKTHDR +flag is set, a +.Vt struct pkthdr Va m_pkthdr +is added to the +.Vt mbuf +header. +It contains a pointer to the interface +the packet has been received from +.Pq Vt struct ifnet Va *rcvif , +and the total packet length +.Pq Vt int Va len . +Optionally, it may also contain an attached list of packet tags +.Pq Vt "struct m_tag" . +See +.Xr mbuf_tags 9 +for details. +Fields used in offloading checksum calculation to the hardware are kept in +.Va m_pkthdr +as well. +See +.Sx HARDWARE-ASSISTED CHECKSUM CALCULATION +for details. +.Pp +If small enough, data is stored in the internal data buffer of an +.Vt mbuf . +If the data is sufficiently large, another +.Vt mbuf +may be added to the +.Vt mbuf chain , +or external storage may be associated with the +.Vt mbuf . +.Dv MHLEN +bytes of data can fit into an +.Vt mbuf +with the +.Dv M_PKTHDR +flag set, +.Dv MLEN +bytes can otherwise. +.Pp +If external storage is being associated with an +.Vt mbuf , +the +.Va m_ext +header is added at the cost of losing the internal data buffer. +It includes a pointer to external storage, the size of the storage, +a pointer to a function used for freeing the storage, +a pointer to an optional argument that can be passed to the function, +and a pointer to a reference counter. +An +.Vt mbuf +using external storage has the +.Dv M_EXT +flag set. +.Pp +The system supplies a macro for allocating the desired external storage +buffer, +.Dv MEXTADD . +.Pp +The allocation and management of the reference counter is handled by the +subsystem. +.Pp +The system also supplies a default type of external storage buffer called an +.Vt mbuf cluster . +.Vt Mbuf clusters +can be allocated and configured with the use of the +.Dv MCLGET +macro. +Each +.Vt mbuf cluster +is +.Dv MCLBYTES +in size, where MCLBYTES is a machine-dependent constant. +The system defines an advisory macro +.Dv MINCLSIZE , +which is the smallest amount of data to put into an +.Vt mbuf cluster . +It is equal to +.Dv MHLEN +plus one. +It is typically preferable to store data into the data region of an +.Vt mbuf , +if size permits, as opposed to allocating a separate +.Vt mbuf cluster +to hold the same data. +.\" +.Ss Macros and Functions +There are numerous predefined macros and functions that provide the +developer with common utilities. +.\" +.Bl -ohang -offset indent +.It Fn mtod mbuf type +Convert an +.Fa mbuf +pointer to a data pointer. +The macro expands to the data pointer cast to the specified +.Fa type . +.Sy Note : +It is advisable to ensure that there is enough contiguous data in +.Fa mbuf . +See +.Fn m_pullup +for details. +.It Fn MGET mbuf how type +Allocate an +.Vt mbuf +and initialize it to contain internal data. +.Fa mbuf +will point to the allocated +.Vt mbuf +on success, or be set to +.Dv NULL +on failure. +The +.Fa how +argument is to be set to +.Dv M_WAITOK +or +.Dv M_NOWAIT . +It specifies whether the caller is willing to block if necessary. +A number of other functions and macros related to +.Vt mbufs +have the same argument because they may +at some point need to allocate new +.Vt mbufs . +.It Fn MGETHDR mbuf how type +Allocate an +.Vt mbuf +and initialize it to contain a packet header +and internal data. +See +.Fn MGET +for details. +.It Fn MEXTADD mbuf buf size free opt_arg1 opt_arg2 flags type +Associate externally managed data with +.Fa mbuf . +Any internal data contained in the mbuf will be discarded, and the +.Dv M_EXT +flag will be set. +The +.Fa buf +and +.Fa size +arguments are the address and length, respectively, of the data. +The +.Fa free +argument points to a function which will be called to free the data +when the mbuf is freed; it is only used if +.Fa type +is +.Dv EXT_EXTREF . +The +.Fa opt_arg1 +and +.Fa opt_arg2 +arguments will be passed unmodified to +.Fa free . +The +.Fa flags +argument specifies additional +.Vt mbuf +flags; it is not necessary to specify +.Dv M_EXT . +Finally, the +.Fa type +argument specifies the type of external data, which controls how it +will be disposed of when the +.Vt mbuf +is freed. +In most cases, the correct value is +.Dv EXT_EXTREF . +.It Fn MCLGET mbuf how +Allocate and attach an +.Vt mbuf cluster +to +.Fa mbuf . +On success, a non-zero value returned; otherwise, 0. +Historically, consumers would check for success by testing the +.Dv M_EXT +flag on the mbuf, but this is now discouraged to avoid unnecessary awareness +of the implementation of external storage in protocol stacks and device +drivers. +.It Fn M_ALIGN mbuf len +Set the pointer +.Fa mbuf->m_data +to place an object of the size +.Fa len +at the end of the internal data area of +.Fa mbuf , +long word aligned. +Applicable only if +.Fa mbuf +is newly allocated with +.Fn MGET +or +.Fn m_get . +.It Fn MH_ALIGN mbuf len +Serves the same purpose as +.Fn M_ALIGN +does, but only for +.Fa mbuf +newly allocated with +.Fn MGETHDR +or +.Fn m_gethdr , +or initialized by +.Fn m_dup_pkthdr +or +.Fn m_move_pkthdr . +.It Fn m_align mbuf len +Services the same purpose as +.Fn M_ALIGN +but handles any type of mbuf. +.It Fn M_LEADINGSPACE mbuf +Returns the number of bytes available before the beginning +of data in +.Fa mbuf . +.It Fn M_TRAILINGSPACE mbuf +Returns the number of bytes available after the end of data in +.Fa mbuf . +.It Fn M_PREPEND mbuf len how +This macro operates on an +.Vt mbuf chain . +It is an optimized wrapper for +.Fn m_prepend +that can make use of possible empty space before data +(e.g.\& left after trimming of a link-layer header). +The new +.Vt mbuf chain +pointer or +.Dv NULL +is in +.Fa mbuf +after the call. +.It Fn M_MOVE_PKTHDR to from +Using this macro is equivalent to calling +.Fn m_move_pkthdr to from . +.It Fn M_WRITABLE mbuf +This macro will evaluate true if +.Fa mbuf +is not marked +.Dv M_RDONLY +and if either +.Fa mbuf +does not contain external storage or, +if it does, +then if the reference count of the storage is not greater than 1. +The +.Dv M_RDONLY +flag can be set in +.Fa mbuf->m_flags . +This can be achieved during setup of the external storage, +by passing the +.Dv M_RDONLY +bit as a +.Fa flags +argument to the +.Fn MEXTADD +macro, or can be directly set in individual +.Vt mbufs . +.It Fn MCHTYPE mbuf type +Change the type of +.Fa mbuf +to +.Fa type . +This is a relatively expensive operation and should be avoided. +.El +.Pp +The functions are: +.Bl -ohang -offset indent +.It Fn m_get how type +A function version of +.Fn MGET +for non-critical paths. +.It Fn m_get2 size how type flags +Allocate an +.Vt mbuf +with enough space to hold specified amount of data. +.It Fn m_getm orig len how type +Allocate +.Fa len +bytes worth of +.Vt mbufs +and +.Vt mbuf clusters +if necessary and append the resulting allocated +.Vt mbuf chain +to the +.Vt mbuf chain +.Fa orig , +if it is +.No non- Ns Dv NULL . +If the allocation fails at any point, +free whatever was allocated and return +.Dv NULL . +If +.Fa orig +is +.No non- Ns Dv NULL , +it will not be freed. +It is possible to use +.Fn m_getm +to either append +.Fa len +bytes to an existing +.Vt mbuf +or +.Vt mbuf chain +(for example, one which may be sitting in a pre-allocated ring) +or to simply perform an all-or-nothing +.Vt mbuf +and +.Vt mbuf cluster +allocation. +.It Fn m_gethdr how type +A function version of +.Fn MGETHDR +for non-critical paths. +.It Fn m_getcl how type flags +Fetch an +.Vt mbuf +with a +.Vt mbuf cluster +attached to it. +If one of the allocations fails, the entire allocation fails. +This routine is the preferred way of fetching both the +.Vt mbuf +and +.Vt mbuf cluster +together, as it avoids having to unlock/relock between allocations. +Returns +.Dv NULL +on failure. +.It Fn m_getjcl how type flags size +This is like +.Fn m_getcl +but it the size of the cluster allocated will be large enough for +.Fa size +bytes. +.It Fn m_getclr how type +Allocate an +.Vt mbuf +and zero out the data region. +.It Fn m_free mbuf +Frees +.Vt mbuf . +Returns +.Va m_next +of the freed +.Vt mbuf . +.El +.Pp +The functions below operate on +.Vt mbuf chains . +.Bl -ohang -offset indent +.It Fn m_freem mbuf +Free an entire +.Vt mbuf chain , +including any external storage. +.\" +.It Fn m_adj mbuf len +Trim +.Fa len +bytes from the head of an +.Vt mbuf chain +if +.Fa len +is positive, from the tail otherwise. +.\" +.It Fn m_append mbuf len cp +Append +.Vt len +bytes of data +.Vt cp +to the +.Vt mbuf chain . +Extend the mbuf chain if the new data does not fit in +existing space. +.\" +.It Fn m_prepend mbuf len how +Allocate a new +.Vt mbuf +and prepend it to the +.Vt mbuf chain , +handle +.Dv M_PKTHDR +properly. +.Sy Note : +It does not allocate any +.Vt mbuf clusters , +so +.Fa len +must be less than +.Dv MLEN +or +.Dv MHLEN , +depending on the +.Dv M_PKTHDR +flag setting. +.\" +.It Fn m_copyup mbuf len dstoff +Similar to +.Fn m_pullup +but copies +.Fa len +bytes of data into a new mbuf at +.Fa dstoff +bytes into the mbuf. +The +.Fa dstoff +argument aligns the data and leaves room for a link layer header. +Returns the new +.Vt mbuf chain +on success, +and frees the +.Vt mbuf chain +and returns +.Dv NULL +on failure. +.Sy Note : +The function does not allocate +.Vt mbuf clusters , +so +.Fa len + dstoff +must be less than +.Dv MHLEN . +.\" +.It Fn m_pullup mbuf len +Arrange that the first +.Fa len +bytes of an +.Vt mbuf chain +are contiguous and lay in the data area of +.Fa mbuf , +so they are accessible with +.Fn mtod mbuf type . +It is important to remember that this may involve +reallocating some mbufs and moving data so all pointers +referencing data within the old mbuf chain +must be recalculated or made invalid. +Return the new +.Vt mbuf chain +on success, +.Dv NULL +on failure +(the +.Vt mbuf chain +is freed in this case). +.Sy Note : +It does not allocate any +.Vt mbuf clusters , +so +.Fa len +must be less than or equal to +.Dv MHLEN . +.\" +.It Fn m_pulldown mbuf offset len offsetp +Arrange that +.Fa len +bytes between +.Fa offset +and +.Fa offset + len +in the +.Vt mbuf chain +are contiguous and lay in the data area of +.Fa mbuf , +so they are accessible with +.Fn mtod mbuf type . +.Fa len +must be smaller than, or equal to, the size of an +.Vt mbuf cluster . +Return a pointer to an intermediate +.Vt mbuf +in the chain containing the requested region; +the offset in the data region of the +.Vt mbuf chain +to the data contained in the returned mbuf is stored in +.Fa *offsetp . +If +.Fa offsetp +is NULL, the region may be accessed using +.Fn mtod mbuf type . +If +.Fa offsetp +is non-NULL, the region may be accessed using +.Fn mtod mbuf uint8_t ++ *offsetp. +The region of the mbuf chain between its beginning and +.Fa offset +is not modified, therefore it is safe to hold pointers to data within +this region before calling +.Fn m_pulldown . +.\" +.It Fn m_copym mbuf offset len how +Make a copy of an +.Vt mbuf chain +starting +.Fa offset +bytes from the beginning, continuing for +.Fa len +bytes. +If +.Fa len +is +.Dv M_COPYALL , +copy to the end of the +.Vt mbuf chain . +.Sy Note : +The copy is read-only, because the +.Vt mbuf clusters +are not copied, only their reference counts are incremented. +.\" +.It Fn m_copypacket mbuf how +Copy an entire packet including header, which must be present. +This is an optimized version of the common case +.Fn m_copym mbuf 0 M_COPYALL how . +.Sy Note : +the copy is read-only, because the +.Vt mbuf clusters +are not copied, only their reference counts are incremented. +.\" +.It Fn m_dup mbuf how +Copy a packet header +.Vt mbuf chain +into a completely new +.Vt mbuf chain , +including copying any +.Vt mbuf clusters . +Use this instead of +.Fn m_copypacket +when you need a writable copy of an +.Vt mbuf chain . +.\" +.It Fn m_copydata mbuf offset len buf +Copy data from an +.Vt mbuf chain +starting +.Fa off +bytes from the beginning, continuing for +.Fa len +bytes, into the indicated buffer +.Fa buf . +.\" +.It Fn m_copyback mbuf offset len buf +Copy +.Fa len +bytes from the buffer +.Fa buf +back into the indicated +.Vt mbuf chain , +starting at +.Fa offset +bytes from the beginning of the +.Vt mbuf chain , +extending the +.Vt mbuf chain +if necessary. +.Sy Note : +It does not allocate any +.Vt mbuf clusters , +just adds +.Vt mbufs +to the +.Vt mbuf chain . +It is safe to set +.Fa offset +beyond the current +.Vt mbuf chain +end: zeroed +.Vt mbufs +will be allocated to fill the space. +.\" +.It Fn m_length mbuf last +Return the length of the +.Vt mbuf chain , +and optionally a pointer to the last +.Vt mbuf . +.\" +.It Fn m_dup_pkthdr to from how +Upon the function's completion, the +.Vt mbuf +.Fa to +will contain an identical copy of +.Fa from->m_pkthdr +and the per-packet attributes found in the +.Vt mbuf chain +.Fa from . +The +.Vt mbuf +.Fa from +must have the flag +.Dv M_PKTHDR +initially set, and +.Fa to +must be empty on entry. +.\" +.It Fn m_move_pkthdr to from +Move +.Va m_pkthdr +and the per-packet attributes from the +.Vt mbuf chain +.Fa from +to the +.Vt mbuf +.Fa to . +The +.Vt mbuf +.Fa from +must have the flag +.Dv M_PKTHDR +initially set, and +.Fa to +must be empty on entry. +Upon the function's completion, +.Fa from +will have the flag +.Dv M_PKTHDR +and the per-packet attributes cleared. +.\" +.It Fn m_fixhdr mbuf +Set the packet-header length to the length of the +.Vt mbuf chain . +.\" +.It Fn m_devget buf len offset ifp copy +Copy data from a device local memory pointed to by +.Fa buf +to an +.Vt mbuf chain . +The copy is done using a specified copy routine +.Fa copy , +or +.Fn bcopy +if +.Fa copy +is +.Dv NULL . +.\" +.It Fn m_cat m n +Concatenate +.Fa n +to +.Fa m . +Both +.Vt mbuf chains +must be of the same type. +.Fa N +is still valid after the function returned. +.Sy Note : +It does not handle +.Dv M_PKTHDR +and friends. +.\" +.It Fn m_split mbuf len how +Partition an +.Vt mbuf chain +in two pieces, returning the tail: +all but the first +.Fa len +bytes. +In case of failure, it returns +.Dv NULL +and attempts to restore the +.Vt mbuf chain +to its original state. +.\" +.It Fn m_apply mbuf off len f arg +Apply a function to an +.Vt mbuf chain , +at offset +.Fa off , +for length +.Fa len +bytes. +Typically used to avoid calls to +.Fn m_pullup +which would otherwise be unnecessary or undesirable. +.Fa arg +is a convenience argument which is passed to the callback function +.Fa f . +.Pp +Each time +.Fn f +is called, it will be passed +.Fa arg , +a pointer to the +.Fa data +in the current mbuf, and the length +.Fa len +of the data in this mbuf to which the function should be applied. +.Pp +The function should return zero to indicate success; +otherwise, if an error is indicated, then +.Fn m_apply +will return the error and stop iterating through the +.Vt mbuf chain . +.\" +.It Fn m_getptr mbuf loc off +Return a pointer to the mbuf containing the data located at +.Fa loc +bytes from the beginning of the +.Vt mbuf chain . +The corresponding offset into the mbuf will be stored in +.Fa *off . +.It Fn m_defrag m0 how +Defragment an mbuf chain, returning the shortest possible +chain of mbufs and clusters. +If allocation fails and this can not be completed, +.Dv NULL +will be returned and the original chain will be unchanged. +Upon success, the original chain will be freed and the new +chain will be returned. +.Fa how +should be either +.Dv M_WAITOK +or +.Dv M_NOWAIT , +depending on the caller's preference. +.Pp +This function is especially useful in network drivers, where +certain long mbuf chains must be shortened before being added +to TX descriptor lists. +.It Fn m_collapse m0 how maxfrags +Defragment an mbuf chain, returning a chain of at most +.Fa maxfrags +mbufs and clusters. +If allocation fails or the chain cannot be collapsed as requested, +.Dv NULL +will be returned, with the original chain possibly modified. +As with +.Fn m_defrag , +.Fa how +should be one of +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It Fn m_unshare m0 how +Create a version of the specified mbuf chain whose +contents can be safely modified without affecting other users. +If allocation fails and this operation can not be completed, +.Dv NULL +will be returned. +The original mbuf chain is always reclaimed and the reference +count of any shared mbuf clusters is decremented. +.Fa how +should be either +.Dv M_WAITOK +or +.Dv M_NOWAIT , +depending on the caller's preference. +As a side-effect of this process the returned +mbuf chain may be compacted. +.Pp +This function is especially useful in the transmit path of +network code, when data must be encrypted or otherwise +altered prior to transmission. +.El +.Sh HARDWARE-ASSISTED CHECKSUM CALCULATION +This section currently applies to TCP/IP only. +In order to save the host CPU resources, computing checksums is +offloaded to the network interface hardware if possible. +The +.Va m_pkthdr +member of the leading +.Vt mbuf +of a packet contains two fields used for that purpose, +.Vt int Va csum_flags +and +.Vt int Va csum_data . +The meaning of those fields depends on the direction a packet flows in, +and on whether the packet is fragmented. +Henceforth, +.Va csum_flags +or +.Va csum_data +of a packet +will denote the corresponding field of the +.Va m_pkthdr +member of the leading +.Vt mbuf +in the +.Vt mbuf chain +containing the packet. +.Pp +On output, checksum offloading is attempted after the outgoing +interface has been determined for a packet. +The interface-specific field +.Va ifnet.if_data.ifi_hwassist +(see +.Xr ifnet 9 ) +is consulted for the capabilities of the interface to assist in +computing checksums. +The +.Va csum_flags +field of the packet header is set to indicate which actions the interface +is supposed to perform on it. +The actions unsupported by the network interface are done in the +software prior to passing the packet down to the interface driver; +such actions will never be requested through +.Va csum_flags . +.Pp +The flags demanding a particular action from an interface are as follows: +.Bl -tag -width ".Dv CSUM_TCP" -offset indent +.It Dv CSUM_IP +The IP header checksum is to be computed and stored in the +corresponding field of the packet. +The hardware is expected to know the format of an IP header +to determine the offset of the IP checksum field. +.It Dv CSUM_TCP +The TCP checksum is to be computed. +(See below.) +.It Dv CSUM_UDP +The UDP checksum is to be computed. +(See below.) +.El +.Pp +Should a TCP or UDP checksum be offloaded to the hardware, +the field +.Va csum_data +will contain the byte offset of the checksum field relative to the +end of the IP header. +In this case, the checksum field will be initially +set by the TCP/IP module to the checksum of the pseudo header +defined by the TCP and UDP specifications. +.Pp +On input, an interface indicates the actions it has performed +on a packet by setting one or more of the following flags in +.Va csum_flags +associated with the packet: +.Bl -tag -width ".Dv CSUM_IP_CHECKED" -offset indent +.It Dv CSUM_IP_CHECKED +The IP header checksum has been computed. +.It Dv CSUM_IP_VALID +The IP header has a valid checksum. +This flag can appear only in combination with +.Dv CSUM_IP_CHECKED . +.It Dv CSUM_DATA_VALID +The checksum of the data portion of the IP packet has been computed +and stored in the field +.Va csum_data +in network byte order. +.It Dv CSUM_PSEUDO_HDR +Can be set only along with +.Dv CSUM_DATA_VALID +to indicate that the IP data checksum found in +.Va csum_data +allows for the pseudo header defined by the TCP and UDP specifications. +Otherwise the checksum of the pseudo header must be calculated by +the host CPU and added to +.Va csum_data +to obtain the final checksum to be used for TCP or UDP validation purposes. +.El +.Pp +If a particular network interface just indicates success or +failure of TCP or UDP checksum validation without returning +the exact value of the checksum to the host CPU, its driver can mark +.Dv CSUM_DATA_VALID +and +.Dv CSUM_PSEUDO_HDR +in +.Va csum_flags , +and set +.Va csum_data +to +.Li 0xFFFF +hexadecimal to indicate a valid checksum. +It is a peculiarity of the algorithm used that the Internet checksum +calculated over any valid packet will be +.Li 0xFFFF +as long as the original checksum field is included. +.Sh STRESS TESTING +When running a kernel compiled with the option +.Dv MBUF_STRESS_TEST , +the following +.Xr sysctl 8 Ns +-controlled options may be used to create +various failure/extreme cases for testing of network drivers +and other parts of the kernel that rely on +.Vt mbufs . +.Bl -tag -width ident +.It Va net.inet.ip.mbuf_frag_size +Causes +.Fn ip_output +to fragment outgoing +.Vt mbuf chains +into fragments of the specified size. +Setting this variable to 1 is an excellent way to +test the long +.Vt mbuf chain +handling ability of network drivers. +.It Va kern.ipc.m_defragrandomfailures +Causes the function +.Fn m_defrag +to randomly fail, returning +.Dv NULL . +Any piece of code which uses +.Fn m_defrag +should be tested with this feature. +.El +.Sh RETURN VALUES +See above. +.Sh SEE ALSO +.Xr ifnet 9 , +.Xr mbuf_tags 9 +.Sh HISTORY +.\" Please correct me if I'm wrong +.Vt Mbufs +appeared in an early version of +.Bx . +Besides being used for network packets, they were used +to store various dynamic structures, such as routing table +entries, interface addresses, protocol control blocks, etc. +In more recent +.Fx +use of +.Vt mbufs +is almost entirely limited to packet storage, with +.Xr uma 9 +zones being used directly to store other network-related memory. +.Pp +Historically, the +.Vt mbuf +allocator has been a special-purpose memory allocator able to run in +interrupt contexts and allocating from a special kernel address space map. +As of +.Fx 5.3 , +the +.Vt mbuf +allocator is a wrapper around +.Xr uma 9 , +allowing caching of +.Vt mbufs , +clusters, and +.Vt mbuf ++ cluster pairs in per-CPU caches, as well as bringing other benefits of +slab allocation. +.Sh AUTHORS +The original +.Nm +manual page was written by +.An Yar Tikhiy . +The +.Xr uma 9 +.Vt mbuf +allocator was written by +.An Bosko Milekic . Property changes on: user/imp/camdoc/mbuf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_ADVISE.9 =================================================================== --- user/imp/camdoc/VOP_ADVISE.9 (nonexistent) +++ user/imp/camdoc/VOP_ADVISE.9 (revision 296049) @@ -0,0 +1,91 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 26, 2015 +.Dt VOP_ADVISE 9 +.Os +.Sh NAME +.Nm VOP_ADVISE +.Nd apply advice about use of file data +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_ADVISE "struct vnode *vp" "off_t start" "off_t end" "int advice" +.Sh DESCRIPTION +This call applies advice for a range of a file's data. +It is used to implement the +.Xr posix_fadvise +system call. +.Pp +Its arguments are: +.Bl -tag -width offset +.It Fa vp +The vnode of the file. +.It Fa start +The start of the range of file data. +.It Fa end +The end of the range of file data. +A value of +.Dv OFF_MAX +indicates that the advice is to be applied up to the end of the file. +.It Fa advice +The type of operation to apply to the file data. +Possible values are: +.Bl -tag -width POSIX_FADV_WILLNEED +.It Dv POSIX_FADV_WILLNEED +Initiate an asynchronous read of the file data if it is not already resident. +.It Dv POSIX_FADV_DONTNEED +Decrease the in-memory priority of clean file data or discard clean file data. +.El +.El +.Pp +If the +.Fa start +and +.Fa end +offsets are both zero, +then the operation should be applied to the entire file. +Note that this call is advisory only and may perform the requested +operation on a subset of the requested range +.Pq including not performing it at all +and still return success. +.Sh LOCKS +The file should be unlocked on entry. +.Sh RETURN VALUES +Zero is returned if the call is successful, otherwise an appropriate +error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +An invalid value was given for +.Fa advice . +.El +.Sh SEE ALSO +.Xr vnode 9 Property changes on: user/imp/camdoc/VOP_ADVISE.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/stack.9 =================================================================== --- user/imp/camdoc/stack.9 (nonexistent) +++ user/imp/camdoc/stack.9 (revision 296049) @@ -0,0 +1,181 @@ +.\" +.\" Copyright (c) 2007-2009 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 September 10, 2015 +.Dt STACK 9 +.Os +.Sh NAME +.Nm stack +.Nd kernel thread stack tracing routines +.Sh SYNOPSIS +.In sys/param.h +.In sys/stack.h +.Pp +In the kernel configuration file: +.Cd "options DDB" +.Cd "options STACK" +.Pp +.Ft struct stack * +.Fn stack_create "void" +.Ft void +.Fn stack_destroy "struct stack *st" +.Ft int +.Fn stack_put "struct stack *st" "vm_offset_t pc" +.Ft void +.Fn stack_copy "const struct stack *src" "struct stack dst" +.Ft void +.Fn stack_zero "struct stack *st" +.Ft void +.Fn stack_print "const struct stack *st" +.Ft void +.Fn stack_print_ddb "const struct stack *st" +.Ft void +.Fn stack_print_short "const struct stack *st" +.Ft void +.Fn stack_print_short_ddb "const struct stack *st" +.Ft void +.Fn stack_sbuf_print "struct sbuf sb*" "const struct stack *st" +.Ft void +.Fn stack_sbuf_print_ddb "struct sbuf sb*" "const struct stack *st" +.Ft void +.Fn stack_save "struct stack *st" +.Ft void +.Fn stack_save_td "struct stack *st" "struct thread *td" +.Ft int +.Fn stack_save_td_running "struct stack *st" "struct thread *td" +.Sh DESCRIPTION +The +.Nm +KPI allows querying of kernel stack trace information and the automated +generation of kernel stack trace strings for the purposes of debugging and +tracing. +To use the KPI, at least one of +.Cd "options DDB" +and +.Cd "options STACK" +must be compiled into the kernel. +.Pp +Each stack trace is described by a +.Vt "struct stack" . +Before a trace may be created or otherwise manipulated, storage for the trace +must be allocated with +.Fn stack_create , +which may sleep. +Memory associated with a trace is freed by calling +.Fn stack_destroy . +.Pp +A trace of the current kernel thread's call stack may be captured using +.Fn stack_save . +.Fn stack_save_td +and +.Fn stack_save_td_running +can also be used to capture the stack of a caller-specified thread. +Callers of these functions must own the thread lock of the specified thread. +.Fn stack_save_td +can capture the stack of a kernel thread that is not running or +swapped out at the time of the call. +.Fn stack_save_td_running +can capture the stack of a running kernel thread. +.Pp +.Fn stack_print +and +.Fn stack_print_short +may be used to print a stack trace using the kernel +.Xr printf 9 , +and may sleep as a result of acquiring +.Xr sx 9 +locks in the kernel linker while looking up symbol names. +In locking-sensitive environments, the unsynchronized +.Fn stack_print_ddb +and +.Fn stack_print_short_ddb +variants may be invoked. +This function bypasses kernel linker locking, making it usable in +.Xr ddb 4 , +but not in a live system where linker data structures may change. +.Pp +.Fn stack_sbuf_print +may be used to construct a human-readable string, including conversion (where +possible) from a simple kernel instruction pointer to a named symbol and +offset. +The argument +.Ar sb +must be an initialized +.Dv struct sbuf +as described in +.Xr sbuf 9 . +This function may sleep if an auto-extending +.Dv struct sbuf +is used, or due to kernel linker locking. +In locking-sensitive environments, such as +.Xr ddb 4 , +the unsynchronized +.Fn stack_sbuf_print_ddb +variant may be invoked to avoid kernel linker locking; it should be used with +a fixed-length sbuf. +.Pp +The utility functions +.Nm stack_zero , +.Nm stack_copy , +and +.Nm stack_put +may be used to manipulate stack data structures directly. +.Sh RETURN VALUES +.Fn stack_put +returns 0 on success. +Otherwise the +.Dv struct stack +does not contain space to record additional frames, and a non-zero value is +returned. +.Pp +.Fn stack_save_td_running +returns 0 when the stack capture was successful and a non-zero error number +otherwise. +In particular, +.Er EAGAIN +is returned if the thread was running in user mode at the time that the +capture was attempted, and +.Er EOPNOTSUPP +is returned if the operation is not implemented. +.Sh SEE ALSO +.Xr ddb 4 , +.Xr printf 9 , +.Xr sbuf 9 , +.Xr sx 9 +.Sh AUTHORS +.An -nosplit +The +.Xr stack 9 +function suite was created by +.An Antoine Brodin . +.Xr stack 9 +was extended by +.An Robert Watson +for general-purpose use outside of +.Xr ddb 4 . Property changes on: user/imp/camdoc/stack.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/acl.9 =================================================================== --- user/imp/camdoc/acl.9 (nonexistent) +++ user/imp/camdoc/acl.9 (revision 296049) @@ -0,0 +1,225 @@ +.\"- +.\" Copyright (c) 1999-2001 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 September 4, 2015 +.Dt ACL 9 +.Os +.Sh NAME +.Nm acl +.Nd virtual file system access control lists +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Pp +In the kernel configuration file: +.Cd "options UFS_ACL" +.Sh DESCRIPTION +Access control lists, or ACLs, +allow fine-grained specification of rights +for vnodes representing files and directories. +However, as there are a plethora of file systems with differing ACL semantics, +the vnode interface is aware only of the syntax of ACLs, +relying on the underlying file system to implement the details. +Depending on the underlying file system, each file or directory +may have zero or more ACLs associated with it, named using the +.Fa type +field of the appropriate vnode ACL calls: +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 , +and +.Xr VOP_SETACL 9 . +.Pp +Currently, each ACL is represented in-kernel by a fixed-size +.Vt acl +structure, defined as follows: +.Bd -literal -offset indent +struct acl { + unsigned int acl_maxcnt; + unsigned int acl_cnt; + int acl_spare[4]; + struct acl_entry acl_entry[ACL_MAX_ENTRIES]; +}; +.Ed +.Pp +An ACL is constructed from a fixed size array of ACL entries, +each of which consists of a set of permissions, principal namespace, +and principal identifier. +In this implementation, the +.Vt acl_maxcnt +field is always set to +.Dv ACL_MAX_ENTRIES . +.Pp +Each individual ACL entry is of the type +.Vt acl_entry_t , +which is a structure with the following members: +.Bl -tag -width 2n +.It Vt acl_tag_t Va ae_tag +The following is a list of definitions of ACL types +to be set in +.Va ae_tag : +.Pp +.Bl -tag -width ".Dv ACL_UNDEFINED_FIELD" -offset indent -compact +.It Dv ACL_UNDEFINED_FIELD +Undefined ACL type. +.It Dv ACL_USER_OBJ +Discretionary access rights for processes whose effective user ID +matches the user ID of the file's owner. +.It Dv ACL_USER +Discretionary access rights for processes whose effective user ID +matches the ACL entry qualifier. +.It Dv ACL_GROUP_OBJ +Discretionary access rights for processes whose effective group ID +or any supplemental groups +match the group ID of the file's owner. +.It Dv ACL_GROUP +Discretionary access rights for processes whose effective group ID +or any supplemental groups +match the ACL entry qualifier. +.It Dv ACL_MASK +The maximum discretionary access rights that can be granted +to a process in the file group class. +This is only valid for POSIX.1e ACLs. +.It Dv ACL_OTHER +Discretionary access rights for processes not covered by any other ACL +entry. +This is only valid for POSIX.1e ACLs. +.It Dv ACL_OTHER_OBJ +Same as +.Dv ACL_OTHER . +.It Dv ACL_EVERYONE +Discretionary access rights for all users. +This is only valid for NFSv4 ACLs. +.El +.Pp +Each POSIX.1e ACL must contain exactly one +.Dv ACL_USER_OBJ , +one +.Dv ACL_GROUP_OBJ , +and one +.Dv ACL_OTHER . +If any of +.Dv ACL_USER , +.Dv ACL_GROUP , +or +.Dv ACL_OTHER +are present, then exactly one +.Dv ACL_MASK +entry should be present. +.It Vt uid_t Va ae_id +The ID of user for whom this ACL describes access permissions. +For entries other than +.Dv ACL_USER +and +.Dv ACL_GROUP , +this field should be set to +.Dv ACL_UNDEFINED_ID . +.It Vt acl_perm_t Va ae_perm +This field defines what kind of access the process matching this ACL has +for accessing the associated file. +For POSIX.1e ACLs, the following are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_EXECUTE +The process may execute the associated file. +.It Dv ACL_WRITE +The process may write to the associated file. +.It Dv ACL_READ +The process may read from the associated file. +.It Dv ACL_PERM_NONE +The process has no read, write or execute permissions +to the associated file. +.El +.Pp +For NFSv4 ACLs, the following are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_READ_DATA +The process may read from the associated file. +.It Dv ACL_LIST_DIRECTORY +Same as +.Dv ACL_READ_DATA . +.It Dv ACL_WRITE_DATA +The process may write to the associated file. +.It Dv ACL_ADD_FILE +Same as +.Dv ACL_ACL_WRITE_DATA . +.It Dv ACL_APPEND_DATA +.It Dv ACL_ADD_SUBDIRECTORY +Same as +.Dv ACL_APPEND_DATA . +.It Dv ACL_READ_NAMED_ATTRS +Ignored. +.It Dv ACL_WRITE_NAMED_ATTRS +Ignored. +.It Dv ACL_EXECUTE +The process may execute the associated file. +.It Dv ACL_DELETE_CHILD +.It Dv ACL_READ_ATTRIBUTES +.It Dv ACL_WRITE_ATTRIBUTES +.It Dv ACL_DELETE +.It Dv ACL_READ_ACL +.It Dv ACL_WRITE_ACL +.It Dv ACL_WRITE_OWNER +.It Dv ACL_SYNCHRONIZE +Ignored. +.El +.It Vt acl_entry_type_t Va ae_entry_type +This field defines the type of NFSv4 ACL entry. +It is not used with POSIX.1e ACLs. +The following values are valid: +.Bl -tag -width ".Dv ACL_WRITE_NAMED_ATTRS" +.It Dv ACL_ENTRY_TYPE_ALLOW +.It Dv ACL_ENTRY_TYPE_DENY +.El +.It Vt acl_flag_t Va ae_flags +This field defines the inheritance flags of NFSv4 ACL entry. +It is not used with POSIX.1e ACLs. +The following values are valid: +.Bl -tag -width ".Dv ACL_ENTRY_DIRECTORY_INHERIT" +.It Dv ACL_ENTRY_FILE_INHERIT +.It Dv ACL_ENTRY_DIRECTORY_INHERIT +.It Dv ACL_ENTRY_NO_PROPAGATE_INHERIT +.It Dv ACL_ENTRY_INHERIT_ONLY +.It Dv ACL_ENTRY_INHERITED +.El +The +.Dv ACL_ENTRY_INHERITED +flag is set on an ACE that has been inherited from its parent. +It may also be set programmatically, and is valid on both files +and directories. +.El +.Sh SEE ALSO +.Xr acl 3 , +.Xr vaccess 9 , +.Xr vaccess_acl_nfs4 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr VFS 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . Property changes on: user/imp/camdoc/acl.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/nv.9 =================================================================== --- user/imp/camdoc/nv.9 (nonexistent) +++ user/imp/camdoc/nv.9 (revision 296049) @@ -0,0 +1,935 @@ +.\" +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" Copyright (c) 2013-2015 Mariusz Zaborski +.\" All rights reserved. +.\" +.\" This documentation was written by Pawel Jakub Dawidek under sponsorship +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 15, 2015 +.Dt NV 9 +.Os +.Sh NAME +.Nm nvlist_create , +.Nm nvlist_destroy , +.Nm nvlist_error , +.Nm nvlist_set_error , +.Nm nvlist_empty , +.Nm nvlist_flags , +.Nm nvlist_exists , +.Nm nvlist_free , +.Nm nvlist_clone , +.Nm nvlist_dump , +.Nm nvlist_fdump , +.Nm nvlist_size , +.Nm nvlist_pack , +.Nm nvlist_unpack , +.Nm nvlist_send , +.Nm nvlist_recv , +.Nm nvlist_xfer , +.Nm nvlist_in_array , +.Nm nvlist_next , +.Nm nvlist_add , +.Nm nvlist_move , +.Nm nvlist_get , +.Nm nvlist_take +.Nd "library for name/value pairs" +.Sh LIBRARY +.Lb libnv +.Sh SYNOPSIS +.In sys/nv.h +.Ft "nvlist_t *" +.Fn nvlist_create "int flags" +.Ft void +.Fn nvlist_destroy "nvlist_t *nvl" +.Ft int +.Fn nvlist_error "const nvlist_t *nvl" +.Ft void +.Fn nvlist_set_error "nvlist_t *nvl" "int error" +.Ft bool +.Fn nvlist_empty "const nvlist_t *nvl" +.Ft int +.Fn nvlist_flags "const nvlist_t *nvl" +.Ft bool +.Fn nvlist_in_array "const nvlist_t *nvl" +.\" +.Ft "nvlist_t *" +.Fn nvlist_clone "const nvlist_t *nvl" +.\" +.Ft void +.Fn nvlist_dump "const nvlist_t *nvl" "int fd" +.Ft void +.Fn nvlist_fdump "const nvlist_t *nvl" "FILE *fp" +.\" +.Ft size_t +.Fn nvlist_size "const nvlist_t *nvl" +.Ft "void *" +.Fn nvlist_pack "const nvlist_t *nvl" "size_t *sizep" +.Ft "nvlist_t *" +.Fn nvlist_unpack "const void *buf" "size_t size" "int flags" +.\" +.Ft int +.Fn nvlist_send "int sock" "const nvlist_t *nvl" +.Ft "nvlist_t *" +.Fn nvlist_recv "int sock" "int flags" +.Ft "nvlist_t *" +.Fn nvlist_xfer "int sock" "nvlist_t *nvl" "int flags" +.\" +.Ft "const char *" +.Fn nvlist_next "const nvlist_t *nvl" "int *typep" "void **cookiep" +.\" +.Ft bool +.Fn nvlist_exists "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_type "const nvlist_t *nvl" "const char *name" "int type" +.Ft bool +.Fn nvlist_exists_null "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_bool "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_number "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_string "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_nvlist "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_descriptor "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_binary "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_bool_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_number_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_string_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_nvlist_array "const nvlist_t *nvl" "const char *name" +.Ft bool +.Fn nvlist_exists_descriptor_array "const nvlist_t *nvl" "const char *name" +.\" +.Ft void +.Fn nvlist_add_null "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_add_bool "nvlist_t *nvl" "const char *name" "bool value" +.Ft void +.Fn nvlist_add_number "nvlist_t *nvl" "const char *name" "uint64_t value" +.Ft void +.Fn nvlist_add_string "nvlist_t *nvl" "const char *name" "const char *value" +.Ft void +.Fn nvlist_add_stringf "nvlist_t *nvl" "const char *name" "const char *valuefmt" "..." +.Ft void +.Fn nvlist_add_stringv "nvlist_t *nvl" "const char *name" "const char *valuefmt" "va_list valueap" +.Ft void +.Fn nvlist_add_nvlist "nvlist_t *nvl" "const char *name" "const nvlist_t *value" +.Ft void +.Fn nvlist_add_descriptor "nvlist_t *nvl" "const char *name" "int value" +.Ft void +.Fn nvlist_add_binary "nvlist_t *nvl" "const char *name" "const void *value" "size_t size" +.Ft void +.Fn nvlist_add_bool_array "nvlist_t *nvl" "const char *name" "const bool *value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_number_array "nvlist_t *nvl" "const char *name" "const uint64_t *value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_string_array "nvlist_t *nvl" "const char *name" "const char * const * value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_nvlist_array "nvlist_t *nvl" "const char *name" "const nvlist_t * const * value" "size_t nitems" +. +.Ft void +.Fn nvlist_add_descriptor_array "nvlist_t *nvl" "const char *name" "const int *value" "size_t nitems" +.\" +.Ft void +.Fn nvlist_move_string "nvlist_t *nvl" "const char *name" "char *value" +.Ft void +.Fn nvlist_move_nvlist "nvlist_t *nvl" "const char *name" "nvlist_t *value" +.Ft void +.Fn nvlist_move_descriptor "nvlist_t *nvl" "const char *name" "int value" +.Ft void +.Fn nvlist_move_binary "nvlist_t *nvl" "const char *name" "void *value" "size_t size" +.Ft void +.Fn nvlist_move_bool_array "nvlist_t *nvl" "const char *name" "bool *value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_number_array "nvlist_t *nvl" "const char *name" "uint64_t *value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_string_array "nvlist_t *nvl" "const char *name" "char **value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_nvlist_array "nvlist_t *nvl" "const char *name" "nvlist_t **value" "size_t nitems" +. +.Ft void +.Fn nvlist_move_descriptor_array "nvlist_t *nvl" "const char *name" "int *value" "size_t nitems" +.\" +.Ft bool +.Fn nvlist_get_bool "const nvlist_t *nvl" "const char *name" +.Ft uint64_t +.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" +.Ft "const char *" +.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" +.Ft "const nvlist_t *" +.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" +.Ft int +.Fn nvlist_get_descriptor "const nvlist_t *nvl" "const char *name" +.Ft "const void *" +.Fn nvlist_get_binary "const nvlist_t *nvl" "const char *name" "size_t *sizep" +.Ft "const bool *" +.Fn nvlist_get_bool_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const uint64_t *" +.Fn nvlist_get_number "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const char * const *" +.Fn nvlist_get_string "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const nvlist_t * const *" +.Fn nvlist_get_nvlist "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const int *" +.Fn nvlist_get_descriptor_array "const nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "const nvlist_t *" +.Fn nvlist_get_parent "const nvlist_t *nvl" "void **cookiep" +.Ft "const nvlist_t *" +.Fn nvlist_get_array_next "const nvlist_t *nvl" +.Ft "const nvlist_t *" +.Fn nvlist_get_pararr "const nvlist_t *nvl" "void **cookiep" +.\" +.Ft bool +.Fn nvlist_take_bool "nvlist_t *nvl" "const char *name" +.Ft uint64_t +.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" +.Ft "char *" +.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" +.Ft "nvlist_t *" +.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" +.Ft int +.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" +.Ft "void *" +.Fn nvlist_take_binary "nvlist_t *nvl" "const char *name" "size_t *sizep" +.Ft "bool *" +.Fn nvlist_take_bool_array "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "uint64_t **" +.Fn nvlist_take_number "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "char **" +.Fn nvlist_take_string "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "nvlist_t **" +.Fn nvlist_take_nvlist "nvlist_t *nvl" "const char *name" "size_t *nitems" +.Ft "int *" +.Fn nvlist_take_descriptor "nvlist_t *nvl" "const char *name" "size_t *nitems" +.\" +.Ft void +.Fn nvlist_free "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_type "nvlist_t *nvl" "const char *name" "int type" +.\" +.Ft void +.Fn nvlist_free_null "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_bool "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_number "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_string "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_nvlist "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_descriptor "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_binary "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_bool_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_number_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_string_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_nvlist_array "nvlist_t *nvl" "const char *name" +.Ft void +.Fn nvlist_free_descriptor_array "nvlist_t *nvl" "const char *name" +.Sh DESCRIPTION +The +.Nm libnv +library allows to easily manage name value pairs as well as send and receive +them over sockets. +A group (list) of name value pairs is called an +.Nm nvlist . +The API supports the following data types: +.Bl -ohang -offset indent +.It Sy null ( NV_TYPE_NULL ) +There is no data associated with the name. +.It Sy bool ( NV_TYPE_BOOL ) +The value can be either +.Dv true +or +.Dv false . +.It Sy number ( NV_TYPE_NUMBER ) +The value is a number stored as +.Vt uint64_t . +.It Sy string ( NV_TYPE_STRING ) +The value is a C string. +.It Sy nvlist ( NV_TYPE_NVLIST ) +The value is a nested nvlist. +.It Sy descriptor ( NV_TYPE_DESCRIPTOR ) +The value is a file descriptor. +Note that file descriptors can be sent only over +.Xr unix 4 +domain sockets. +.It Sy binary ( NV_TYPE_BINARY ) +The value is a binary buffer. +.It Sy bool array ( NV_TYPE_BOOL_ARRAY ) +The value is an array of boolean values. +.It Sy number array ( NV_TYPE_NUMBER_ARRAY ) +The value is an array of numbers, each stored as +.Vt uint64_t . +.It Sy string array ( NV_TYPE_STRING_ARRAY ) +The value is an array of C strings. +.It Sy nvlist array ( NV_TYPE_NVLIST_ARRAY ) +The value is an array of nvlists. +When an nvlist is added to an array, it becomes part of the primary nvlist. +Traversing these arrays can be done using the +.Fn nvlist_get_array_next +and +.Fn nvlist_get_pararr +functions. +.It Sy descriptor array ( NV_TYPE_DESCRIPTOR_ARRAY ) +The value is an array of files descriptors. +.El +.Pp +The +.Fn nvlist_create +function allocates memory and initializes an nvlist. +.Pp +The following flag can be provided: +.Pp +.Bl -tag -width "NV_FLAG_IGNORE_CASE" -compact -offset indent +.It Dv NV_FLAG_IGNORE_CASE +Perform case-insensitive lookups of provided names. +.It Dv NV_FLAG_NO_UNIQUE +Names in the nvlist do not have to be unique. +.El +.Pp +The +.Fn nvlist_destroy +function destroys the given nvlist. +Function does nothing if +.Dv NULL +nvlist is provided. +Function never modifies the +.Va errno +global variable. +.Pp +The +.Fn nvlist_error +function returns any error value that the nvlist accumulated. +If the given nvlist is +.Dv NULL +the +.Er ENOMEM +error will be returned. +.Pp +The +.Fn nvlist_set_error +function sets an nvlist to be in the error state. +Subsequent calls to +.Fn nvlist_error +will return the given error value. +This function cannot be used to clear the error state from an nvlist. +This function does nothing if the nvlist is already in the error state. +.Pp +The +.Fn nvlist_empty +function returns +.Dv true +if the given nvlist is empty and +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_flags +function returns flags used to create the nvlist with the +.Fn nvlist_create +function. +.Pp +The +.Fn nvlist_in_array +function returns +.Dv true +if +.Fa nvl +is part of an array that is a member of another nvlist. +.Pp +The +.Fn nvlist_clone +functions clones the given nvlist. +The clone shares no resources with its origin. +This also means that all file descriptors that are part of the nvlist will be +duplicated with the +.Xr dup 2 +system call before placing them in the clone. +.Pp +The +.Fn nvlist_dump +dumps nvlist content for debugging purposes to the given file descriptor +.Fa fd . +.Pp +The +.Fn nvlist_fdump +dumps nvlist content for debugging purposes to the given file stream +.Fa fp . +.Pp +The +.Fn nvlist_size +function returns the size of the given nvlist after converting it to binary +buffer with the +.Fn nvlist_pack +function. +.Pp +The +.Fn nvlist_pack +function converts the given nvlist to a binary buffer. +The function allocates memory for the buffer, which should be freed with the +.Xr free 3 +function. +If the +.Fa sizep +argument is not +.Dv NULL , +the size of the buffer will be stored there. +The function returns +.Dv NULL +in case of an error (allocation failure). +If the nvlist contains any file descriptors +.Dv NULL +will be returned. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_unpack +function converts the given buffer to the nvlist. +The +.Fa flags +argument defines what type of the top level nvlist is expected to be. +Flags are set up using the +.Fn nvlist_create +function. +If the nvlist flags do not match the flags passed to +.Fn nvlist_unpack , +the nvlist will not be returned. +Every nested nvlist list should be checked using +.Fn nvlist_flags +function. +The function returns +.Dv NULL +in case of an error. +.Pp +The +.Fn nvlist_send +function sends the given nvlist over the socket given by the +.Fa sock +argument. +Note that nvlist that contains file descriptors can only be send over +.Xr unix 4 +domain sockets. +.Pp +The +.Fn nvlist_recv +function receives nvlist over the socket given by the +.Fa sock +argument. +The +.Fa flags +argument defines what type of the top level nvlist is expected to be. +Flags are set up using the +.Fn nvlist_create +function. +If the nvlist flags do not match the flags passed to +.Fn nvlist_recv , +the nvlist will not be returned. +Every nested nvlist list should be checked using +.Fn nvlist_flags +function. +.Pp +The +.Fn nvlist_xfer +function sends the given nvlist over the socket given by the +.Fa sock +argument and receives nvlist over the same socket. +The +.Fa flags +argument defines what type of the top level nvlist is expected to be. +Flags are set up using the +.Fn nvlist_create +function. +If the nvlist flags do not match the flags passed to +.Fn nvlist_xfer , +the nvlist will not be returned. +Every nested nvlist list should be checked using +.Fn nvlist_flags +function. +The given nvlist is always destroyed. +.Pp +The +.Fn nvlist_next +function iterates over the given nvlist returning names and types of subsequent +elements. +The +.Fa cookiep +argument allows the function to figure out which element should be returned +next. +The +.Va *cookiep +should be set to +.Dv NULL +for the first call and should not be changed later. +Returning +.Dv NULL +means there are no more elements on the nvlist. +The +.Fa typep +argument can be NULL. +Elements may not be removed from the nvlist while traversing it. +The nvlist must not be in error state. +Note that +.Fn nvlist_next +will handle +.Va cookiep +being set to +.Dv NULL . +In this case first element is returned or +.Dv NULL +if nvlist is empty. +This behavior simplifies removing the first element from the list. +.Pp +The +.Fn nvlist_exists +function returns +.Dv true +if element of the given name exists (besides of its type) or +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_exists_type +function returns +.Dv true +if element of the given name and the given type exists or +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_exists_null , +.Fn nvlist_exists_bool , +.Fn nvlist_exists_number , +.Fn nvlist_exists_string , +.Fn nvlist_exists_nvlist , +.Fn nvlist_exists_descriptor , +.Fn nvlist_exists_binary , +.Fn nvlist_exists_bool_array , +.Fn nvlist_exists_number_array , +.Fn nvlist_exists_string_array , +.Fn nvlist_exists_nvlist_array , +.Fn nvlist_exists_descriptor_array +functions return +.Dv true +if element of the given name and the given type determined by the function name +exists or +.Dv false +otherwise. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_add_null , +.Fn nvlist_add_bool , +.Fn nvlist_add_number , +.Fn nvlist_add_string , +.Fn nvlist_add_stringf , +.Fn nvlist_add_stringv , +.Fn nvlist_add_nvlist , +.Fn nvlist_add_descriptor , +.Fn nvlist_add_binary , +.Fn nvlist_add_bool_array , +.Fn nvlist_add_number_array , +.Fn nvlist_add_string_array , +.Fn nvlist_add_nvlist_array , +.Fn nvlist_add_descriptor_array +functions add element to the given nvlist. +When adding string or binary buffor the functions will allocate memory +and copy the data over. +When adding nvlist, the nvlist will be cloned and clone will be added. +When adding descriptor, the descriptor will be duplicated using the +.Xr dup 2 +system call and the new descriptor will be added. +The array functions will fail if there are any +.Dv NULL +elements in the array, or if the array pointer is +.Dv NULL . +If an error occurs while adding new element, internal error is set which can be +examined using the +.Fn nvlist_error +function. +.Pp +The +.Fn nvlist_move_string , +.Fn nvlist_move_nvlist , +.Fn nvlist_move_descriptor , +.Fn nvlist_move_binary , +.Fn nvlist_move_bool_array , +.Fn nvlist_move_number_array , +.Fn nvlist_move_string_array , +.Fn nvlist_move_nvlist_array , +.Fn nvlist_move_descriptor_array +functions add new element to the given nvlist, but unlike +.Fn nvlist_add_ +functions they will consume the given resource. +In the case of strings, descriptors, or nvlists every elements must be +unique, or it could cause a double free. +The array functions will fail if there are any +.Dv NULL +elements, or if the array pointer is +.Dv NULL . +If an error occurs while adding new element, the resource is destroyed and +internal error is set which can be examined using the +.Fn nvlist_error +function. +.Pp +The +.Fn nvlist_get_bool , +.Fn nvlist_get_number , +.Fn nvlist_get_string , +.Fn nvlist_get_nvlist , +.Fn nvlist_get_descriptor , +.Fn nvlist_get_binary , +.Fn nvlist_get_bool_array , +.Fn nvlist_get_number_array , +.Fn nvlist_get_string_array , +.Fn nvlist_get_nvlist_array , +.Fn nvlist_get_descriptor_array +functions return the value that corresponds to the given key name. +In the case of strings, nvlists, descriptors, binary, or arrays, the returned +resource should not be modified - they still belong to the nvlist. +If an element of the given name does not exist, the program will be aborted. +To avoid this, the caller should check for the existence of the name before +trying to obtain the value, or use the +.Xr dnvlist 3 +extension, which can provide a default value in the case of a missing element. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_get_parent +function returns the parent nvlist of the nested nvlist. +.Pp +The +.Fn nvlist_get_array_next +function returns the next element from the array or +.Dv NULL +if the nvlist is not in array or it is the last element. +Note that +.Fn nvlist_get_array_next +only works if you added the nvlist array using the +.Fn nvlist_move_nvlist_array +or +.Fn nvlist_add_nvlist_array +functions. +.Pp +The +.Fn nvlist_get_pararr +function returns the next element in the array, or if not available +the parent of the nested nvlist. +.Pp +The +.Fn nvlist_take_bool , +.Fn nvlist_take_number , +.Fn nvlist_take_string , +.Fn nvlist_take_nvlist , +.Fn nvlist_take_descriptor , +.Fn nvlist_take_binary , +.Fn nvlist_take_bool_array , +.Fn nvlist_take_number_array , +.Fn nvlist_take_string_array , +.Fn nvlist_take_nvlist_array , +.Fn nvlist_take_descriptor_array +functions return value associated with the given name and remove the element +from the nvlist. +In case of string and binary values, the caller is responsible for free returned +memory using the +.Xr free 3 +function. +In case of nvlist, the caller is responsible for destroying returned nvlist +using the +.Fn nvlist_destroy +function. +In case of descriptor, the caller is responsible for closing returned descriptor +using the +.Fn close 2 +system call. +If an element of the given name does not exist, the program will be aborted. +To avoid that the caller should check for the existence of the given name +before trying to obtain the value, or use the +.Xr dnvlist 3 +extension, which can provide a default value in the case of a missing element. +In the case of an array of strings or binary values, the caller is responsible +for freeing every element of the array using the +.Xr free 3 +function. +In the case of an array of nvlists, the caller is responsible for destroying +every element of array using the +.Fn nvlist_destroy +function. +In the case of descriptors, the caller is responsible for closing every +element of array using the +.Fn close 2 +system call. +In every case involving an array, the caller must also free the pointer to +the array using the +.Xr free 3 +function. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_free +function removes element of the given name from the nvlist (besides of its type) +and frees all resources associated with it. +If element of the given name does not exist, the program will be aborted. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_free_type +function removes element of the given name and the given type from the nvlist +and frees all resources associated with it. +If element of the given name and the given type does not exist, the program +will be aborted. +The nvlist must not be in error state. +.Pp +The +.Fn nvlist_free_null , +.Fn nvlist_free_bool , +.Fn nvlist_free_number , +.Fn nvlist_free_string , +.Fn nvlist_free_nvlist , +.Fn nvlist_free_descriptor , +.Fn nvlist_free_binary , +.Fn nvlist_free_bool_array , +.Fn nvlist_free_number_array , +.Fn nvlist_free_string_array , +.Fn nvlist_free_nvlist_array , +.Fn nvlist_free_descriptor_array +functions remove element of the given name and the given type determined by the +function name from the nvlist and free all resources associated with it. +If element of the given name and the given type does not exist, the program +will be aborted. +The nvlist must not be in error state. +.Sh EXAMPLES +The following example demonstrates how to prepare an nvlist and send it over +.Xr unix 4 +domain socket. +.Bd -literal +nvlist_t *nvl; +int fd; + +fd = open("/tmp/foo", O_RDONLY); +if (fd < 0) + err(1, "open(\\"/tmp/foo\\") failed"); + +nvl = nvlist_create(0); +/* + * There is no need to check if nvlist_create() succeeded, + * as the nvlist_add_() functions can cope. + * If it failed, nvlist_send() will fail. + */ +nvlist_add_string(nvl, "filename", "/tmp/foo"); +nvlist_add_number(nvl, "flags", O_RDONLY); +/* + * We just want to send the descriptor, so we can give it + * for the nvlist to consume (that's why we use nvlist_move + * not nvlist_add). + */ +nvlist_move_descriptor(nvl, "fd", fd); +if (nvlist_send(sock, nvl) < 0) { + nvlist_destroy(nvl); + err(1, "nvlist_send() failed"); +} +nvlist_destroy(nvl); +.Ed +.Pp +Receiving nvlist and getting data: +.Bd -literal +nvlist_t *nvl; +const char *command; +char *filename; +int fd; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +/* For command we take pointer to nvlist's buffer. */ +command = nvlist_get_string(nvl, "command"); +/* + * For filename we remove it from the nvlist and take + * ownership of the buffer. + */ +filename = nvlist_take_string(nvl, "filename"); +/* The same for the descriptor. */ +fd = nvlist_take_descriptor(nvl, "fd"); + +printf("command=%s filename=%s fd=%d\n", command, filename, fd); + +nvlist_destroy(nvl); +free(filename); +close(fd); +/* command was freed by nvlist_destroy() */ +.Ed +.Pp +Iterating over nvlist: +.Bd -literal +nvlist_t *nvl; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +cookie = NULL; +while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + printf("%s=", name); + switch (type) { + case NV_TYPE_NUMBER: + printf("%ju", (uintmax_t)nvlist_get_number(nvl, name)); + break; + case NV_TYPE_STRING: + printf("%s", nvlist_get_string(nvl, name)); + break; + default: + printf("N/A"); + break; + } + printf("\\n"); +} +.Ed +.Pp +Iterating over every nested nvlist: +.Bd -literal +nvlist_t *nvl; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == NULL) + err(1, "nvlist_recv() failed"); + +cookie = NULL; +do { + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, name); + cookie = NULL; + } + } +} while ((nvl = nvlist_get_parent(nvl, &cookie)) != NULL); +.Ed +.Pp +Iterating over every nested nvlist and every nvlist element: +.Bd -literal +nvlist_t *nvl; +const nvlist_t * const *array; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == null) + err(1, "nvlist_recv() failed"); + +cookie = null; +do { + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, name); + cookie = NULL; + } else if (type == NV_TYPE_NVLIST_ARRAY) { + nvl = nvlist_get_nvlist_array(nvl, name, NULL)[0]; + cookie = NULL; + } + } +} while ((nvl = nvlist_get_pararr(nvl, &cookie)) != NULL); +.Ed +.Pp +Or alternatively: +.Bd -literal +nvlist_t *nvl, *tmp; +const nvlist_t * const *array; +const char *name; +void *cookie; +int type; + +nvl = nvlist_recv(sock, 0); +if (nvl == null) + err(1, "nvlist_recv() failed"); + +cooke = NULL; +tmp = nvl; +do { + do { + nvl = tmp; + while ((name = nvlist_next(nvl, &type, &cookie)) != NULL) { + if (type == NV_TYPE_NVLIST) { + nvl = nvlist_get_nvlist(nvl, + name); + cookie = NULL; + } else if (type == NV_TYPE_NVLIST_ARRAY) { + nvl = nvlist_get_nvlist_array(nvl, name, + NULL)[0]; + cookie = NULL; + } + } + cookie = NULL; + } while ((tmp = nvlist_get_array_next(nvl)) != NULL); +} while ((tmp = nvlist_get_parent(nvl, &cookie)) != NULL); +.Ed +.Sh SEE ALSO +.Xr close 2 , +.Xr dup 2 , +.Xr open 2 , +.Xr err 3 , +.Xr free 3 , +.Xr printf 3 , +.Xr unix 4 +.Sh HISTORY +The +.Nm libnv +library appeared in +.Fx 11.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm libnv +library was implemented by +.An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net +under sponsorship from the FreeBSD Foundation. Property changes on: user/imp/camdoc/nv.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/owll.9 =================================================================== --- user/imp/camdoc/owll.9 (nonexistent) +++ user/imp/camdoc/owll.9 (revision 296049) @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2015 M. Warner Losh +.\" 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. 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 July 20, 2015 +.Dt OWLL 9 +.Os +.Sh NAME +.Nm owll +.Nm OWLL_WRITE_ONE, +.Nm OWLL_WRITE_ZERO, +.Nm OWLL_READ_DATA, +.Nm OWLL_REASET_AND_PRESENCE +.Nd Dallas Semiconductor 1-Wire Link Layer Interface +.Sh SYNOPSIS +.Ft int +.Fn OWLL_WRITE_ONE "device_t lldev" "struct ow_timing *timing" +.Ft int +.Fn OWLL_WRITE_ZERO "device_t lldev" "struct ow_timing *timing" +.Ft int +.Fn OWLL_READ_DATA "device_t lldev" "struct ow_timing *timing" "int *bit" +.Ft int +.Fn OWLL_RESET_AND_PRESENCE "device_t lldev" "struct ow_timing *timing" "int *bit" +.Sh DESCRIPTION +The +.Nm +interface provides access to the link layer of the Dallas +Semiconductor 1-Wire from upper layers of the protocol. +.Pp +.Fn OWLL_WRITE_ONE +and +.Fn OWLL_WRITE_ZERO +writes a one bitor a zero bit respectively on the 1-Wire bus. +.Pp +.Fn OWLL_READ_DATA +reads one bit from the 1-Wire bus. +This is often referred to as a +.Dq Read Time Slot +in the 1-Wire device data sheets. +.Pp +The +.Fn OWLL_RESET_AND_PRESENCE +function starts a reset sequence and detects if any device(s) are +present on the bus. +This is the beginning of all 1-Wire transactions. +.Sh NOTES +This interface is intended to be used only by the +.Xr ow 4 +device to talk to the low-level bus. +By convention, the device that implements this interface is called +.Xr owc 4 . +Only devices that implement +.Xr own 9 +should call these interfaces. +.Sh SEE ALSO +.Xr ow 4 , +.Xr owc 4 , +.Xr own 9 +.Sh LEGAL +.Tn 1-Wire +is a registered trademark of Maxim Integrated Products, Inc. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Warner Losh . Property changes on: user/imp/camdoc/owll.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/own.9 =================================================================== --- user/imp/camdoc/own.9 (nonexistent) +++ user/imp/camdoc/own.9 (revision 296049) @@ -0,0 +1,230 @@ +.\" +.\" Copyright (c) 2015 M. Warner Losh +.\" 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. 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 July 20, 2015 +.Dt OWN 9 +.Os +.Sh NAME +.Nm own , +.Nm own_send_command , +.Nm own_commmand_wait , +.Nm own_self_command , +.Nm own_acquire_bus , +.Nm own crc , +.Nm own_release_bus , +.Nm OWN_ACQUIRE_BUS , +.Nm OWN_CRC , +.Nm OWN_RELEASE_BUS , +.Nm OWN_SEND_COMMAND +.Nd Dallas Semiconductor 1-Wire Network and Transport Interface +.Sh SYNOPSIS +.In sys/bus.h +.In dev/ow/own.h +.Ft int +.Fn own_send_command "device_t pdev" "struct ow_cmd *cmd" +.Ft int +.Fn own_command_wait "device_t pdev" "struct ow_cmd *cmd" +.Ft int +.Fn own_self_command "device_t pdev" "struct ow_cmd *cmd" "uint8_t xpt_cmd" +.Ft int +.Fn own_acquire_bus "device_t pdev" "int how" +.Ft int +.Fn own_release_bus "device_t pdev" +.Ft int +.Fn own_crc "device_t pdev" "uint8_t *buffer" "size_t len" +.Ft int +.Fn OWN_SEND_COMMAND "device_t ndev" "device_t pdev" "struct ow_cmd *cmd" +.Ft int +.Fn OWN_ACQUIRE_BUS "device_t ndev" "device_t pdev" "int how" +.Ft void +.Fn OWN_RELEASE_BUS "device_t ndev" "device_t pdev" +.Ft uint8_t +.Fn OWN_CRC "device_t ndev" "device_t pdev" "uint8_t *buffer" "size_t len" +.Sh DESCRIPTION +The +.Nm +interface defines three sets of functions for interacting with 1-Wire +devices: +sending commands, +reserving the bus, +and +ensuring data integrity. +Wrappers are provided for the raw +.Nm OWN +.Xr kobj 9 +interfaces and should be used for improved safety over the +.Xr kobj 9 +ones. +.Ss Bus Commands +The 1-Wire bus defines different layers of access to the devices on +the bus. +The +.Nm +functions provide access to the network and transport layers. +The network layer designates the next command as being either for all +devices on the bus, or for a specific device. +The network layer also specifies the speed used by the link layer. +.Pp +.Vt "struct ow_cmd" +encapsulates network access, speed, and timing information. +It specifies the commands to send and whether or not to read data. +Its members are: +.Bl -tag -width ".Va xxxx" +.It Va flags +Flags controlling the interpretation of the structure. +These flags are defined in +.In dev/ow/ow.h : +.Bl -tag -width indent +.It OW_FLAG_OVERDRIVE +Send +.Va xpt_cmd +bytes and read +.Va xpt_read +bytes at overdrive speed. +.It OW_FLAG_READ_BIT +Interpret +.Va xpt_read_len +to be in bits to be read after +.Va xpt_cmd +rather than bytes. +.El +.It Va rom_cmd +ROM command bytes to send. +.It Va rom_len +Number of ROM command bytes to send. +.It Va rom_read_len +Number of bytes to read after sending the ROM command. +.It Va rom_read +Buffer for bytes read after the ROM command. +.It Va xpt_cmd +Transport command to send. +.It Va xpt_len +Length of the transport command bytes to send. +Specify 0 for no transport command. +.It Va xpt_read_len +Number of bytes to read after +.Va xpt_cmd +bytes are sent. +If the +.Dv OW_FLAG_READ_BIT +bit is set in +.Va flags , +then it is the number of bits to read. +Bits read are packed into bytes. +.It Va xpt_read +Buffer for data read. +.El +.Pp +.Fn own_command_wait +acquires the 1-Wire bus, waiting if necessary, +sends the command, +and +then releases the bus. +.Fn own_send_command +sends the command without bus reservation. +.Fa pdev +is the client device (the presentation layer device) sending the command. +The +.Fa cmd +argument describes the transaction to send to the 1-Wire bus. +.Pp +.Fn own_self_command +fills in +.Fa cmd +with a MATCH_ROM ROM command, the ROM address of +.Fa pdev +and the +.Fa xpt_cmd +as a convenient way to create directed commands. +.Ss Bus Reservation +The 1-Wire system includes an advisory lock for the bus that +presentation layer devices can use to coordinate access. +Locking is purely advisory at this time. +.Pp +.Fn own_acquire_bus +reserves the bus. +It waits indefinitely if the +.Fa how +argument is +.Dv OWN_WAIT +and returns the error +.Dv EWOULDBLOCK +if passed +.Dv OWN_DONTWAIT +when the bus is owned by another client. +.Pp +.Fn own_release_bus +releases the bus. +.Ss Data Integrity +.Fn own_crc +computes the 1-Wire standard CRC function over the data +passed in +.Fa buffer +and +.Fa len +and returns the result. +.Ss Notes +The 1-Wire standard (Maxim AN937) defines layers that are akin to ISO +networking layers. +The lowest relevant layer, the link layer, defines the polling windows +and the timing of the signaling of different modes. +The network layer is built on top of the link layer +and is used to address devices in a unicast or multicast manner. +The transport layer defines commands and responses from the devices. +The presentation layer is composed of the device specific commands and +actions used to control the specific 1-Wire devices on bus. +.Pp +These interfaces are implemented by the +.Xr ow 4 +device. +Presentation layer devices (children of the newbus +.Xr ow 4 +device) should only call the functions described here. +The functionality provided by the +.Xr owc 4 +device (specifically the +.Xr owll 9 +interface) should only be called by the +.Xr ow 4 +driver. +.Sh SEE ALSO +.Xr ow 4 , +.Xr owc 4 , +.Xr owll 9 +.Pa http://pdfserv.maximintegrated.com/en/an/AN937.pdf +.Sh LEGAL +.Tn 1-Wire +is a registered trademark of Maxim Integrated Products, Inc. +.Sh HISTORY +The +.Nm +driver first appeared in +.Fx 11.0 . +.Sh AUTHORS +The +.Nm +device driver and this manual page were written by +.An Warner Losh . Property changes on: user/imp/camdoc/own.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/atomic.9 =================================================================== --- user/imp/camdoc/atomic.9 (nonexistent) +++ user/imp/camdoc/atomic.9 (revision 296049) @@ -0,0 +1,427 @@ +.\" Copyright (c) 2000-2001 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 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 14, 2015 +.Dt ATOMIC 9 +.Os +.Sh NAME +.Nm atomic_add , +.Nm atomic_clear , +.Nm atomic_cmpset , +.Nm atomic_fetchadd , +.Nm atomic_load , +.Nm atomic_readandclear , +.Nm atomic_set , +.Nm atomic_subtract , +.Nm atomic_store +.Nd atomic operations +.Sh SYNOPSIS +.In sys/types.h +.In machine/atomic.h +.Ft void +.Fn atomic_add_[acq_|rel_] "volatile *p" " v" +.Ft void +.Fn atomic_clear_[acq_|rel_] "volatile *p" " v" +.Ft int +.Fo atomic_cmpset_[acq_|rel_] +.Fa "volatile *dst" +.Fa " old" +.Fa " new" +.Fc +.Ft +.Fn atomic_fetchadd_ "volatile *p" " v" +.Ft +.Fn atomic_load_acq_ "volatile *p" +.Ft +.Fn atomic_readandclear_ "volatile *p" +.Ft void +.Fn atomic_set_[acq_|rel_] "volatile *p" " v" +.Ft void +.Fn atomic_subtract_[acq_|rel_] "volatile *p" " v" +.Ft void +.Fn atomic_store_rel_ "volatile *p" " v" +.Ft +.Fn atomic_swap_ "volatile *p" " v" +.Ft int +.Fn atomic_testandset_ "volatile *p" "u_int v" +.Sh DESCRIPTION +Each of the atomic operations is guaranteed to be atomic across multiple +threads and in the presence of interrupts. +They can be used to implement reference counts or as building blocks for more +advanced synchronization primitives such as mutexes. +.Ss Types +Each atomic operation operates on a specific +.Fa type . +The type to use is indicated in the function name. +The available types that can be used are: +.Pp +.Bl -tag -offset indent -width short -compact +.It Li int +unsigned integer +.It Li long +unsigned long integer +.It Li ptr +unsigned integer the size of a pointer +.It Li 32 +unsigned 32-bit integer +.It Li 64 +unsigned 64-bit integer +.El +.Pp +For example, the function to atomically add two integers is called +.Fn atomic_add_int . +.Pp +Certain architectures also provide operations for types smaller than +.Dq Li int . +.Pp +.Bl -tag -offset indent -width short -compact +.It Li char +unsigned character +.It Li short +unsigned short integer +.It Li 8 +unsigned 8-bit integer +.It Li 16 +unsigned 16-bit integer +.El +.Pp +These must not be used in MI code because the instructions to implement them +efficiently might not be available. +.Ss Acquire and Release Operations +By default, a thread's accesses to different memory locations might not be +performed in +.Em program order , +that is, the order in which the accesses appear in the source code. +To optimize the program's execution, both the compiler and processor might +reorder the thread's accesses. +However, both ensure that their reordering of the accesses is not visible to +the thread. +Otherwise, the traditional memory model that is expected by single-threaded +programs would be violated. +Nonetheless, other threads in a multithreaded program, such as the +.Fx +kernel, might observe the reordering. +Moreover, in some cases, such as the implementation of synchronization between +threads, arbitrary reordering might result in the incorrect execution of the +program. +To constrain the reordering that both the compiler and processor might perform +on a thread's accesses, the thread should use atomic operations with +.Em acquire +and +.Em release +semantics. +.Pp +Most of the atomic operations on memory have three variants. +The first variant performs the operation without imposing any ordering +constraints on memory accesses to other locations. +The second variant has acquire semantics, and the third variant has release +semantics. +In effect, operations with acquire and release semantics establish one-way +barriers to reordering. +.Pp +When an atomic operation has acquire semantics, the effects of the operation +must have completed before any subsequent load or store (by program order) is +performed. +Conversely, acquire semantics do not require that prior loads or stores have +completed before the atomic operation is performed. +To denote acquire semantics, the suffix +.Dq Li _acq +is inserted into the function name immediately prior to the +.Dq Li _ Ns Aq Fa type +suffix. +For example, to subtract two integers ensuring that subsequent loads and +stores happen after the subtraction is performed, use +.Fn atomic_subtract_acq_int . +.Pp +When an atomic operation has release semantics, the effects of all prior +loads or stores (by program order) must have completed before the operation +is performed. +Conversely, release semantics do not require that the effects of the +atomic operation must have completed before any subsequent load or store is +performed. +To denote release semantics, the suffix +.Dq Li _rel +is inserted into the function name immediately prior to the +.Dq Li _ Ns Aq Fa type +suffix. +For example, to add two long integers ensuring that all prior loads and +stores happen before the addition, use +.Fn atomic_add_rel_long . +.Pp +The one-way barriers provided by acquire and release operations allow the +implementations of common synchronization primitives to express their +ordering requirements without also imposing unnecessary ordering. +For example, for a critical section guarded by a mutex, an acquire operation +when the mutex is locked and a release operation when the mutex is unlocked +will prevent any loads or stores from moving outside of the critical +section. +However, they will not prevent the compiler or processor from moving loads +or stores into the critical section, which does not violate the semantics of +a mutex. +.Ss Multiple Processors +In multiprocessor systems, the atomicity of the atomic operations on memory +depends on support for cache coherence in the underlying architecture. +In general, cache coherence on the default memory type, +.Dv VM_MEMATTR_DEFAULT , +is guaranteed by all architectures that are supported by +.Fx . +For example, cache coherence is guaranteed on write-back memory by the +.Tn amd64 +and +.Tn i386 +architectures. +However, on some architectures, cache coherence might not be enabled on all +memory types. +To determine if cache coherence is enabled for a non-default memory type, +consult the architecture's documentation. +.Ss Semantics +This section describes the semantics of each operation using a C like notation. +.Bl -hang +.It Fn atomic_add p v +.Bd -literal -compact +*p += v; +.Ed +.It Fn atomic_clear p v +.Bd -literal -compact +*p &= ~v; +.Ed +.It Fn atomic_cmpset dst old new +.Bd -literal -compact +if (*dst == old) { + *dst = new; + return (1); +} else + return (0); +.Ed +.El +.Pp +The +.Fn atomic_cmpset +functions are not implemented for the types +.Dq Li char , +.Dq Li short , +.Dq Li 8 , +and +.Dq Li 16 . +.Bl -hang +.It Fn atomic_fetchadd p v +.Bd -literal -compact +tmp = *p; +*p += v; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_fetchadd +functions are only implemented for the types +.Dq Li int , +.Dq Li long +and +.Dq Li 32 +and do not have any variants with memory barriers at this time. +.Bl -hang +.It Fn atomic_load p +.Bd -literal -compact +return (*p); +.Ed +.El +.Pp +The +.Fn atomic_load +functions are only provided with acquire memory barriers. +.Bl -hang +.It Fn atomic_readandclear p +.Bd -literal -compact +tmp = *p; +*p = 0; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_readandclear +functions are not implemented for the types +.Dq Li char , +.Dq Li short , +.Dq Li ptr , +.Dq Li 8 , +and +.Dq Li 16 +and do not have any variants with memory barriers at this time. +.Bl -hang +.It Fn atomic_set p v +.Bd -literal -compact +*p |= v; +.Ed +.It Fn atomic_subtract p v +.Bd -literal -compact +*p -= v; +.Ed +.It Fn atomic_store p v +.Bd -literal -compact +*p = v; +.Ed +.El +.Pp +The +.Fn atomic_store +functions are only provided with release memory barriers. +.Bl -hang +.It Fn atomic_swap p v +.Bd -literal -compact +tmp = *p; +*p = v; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_swap +functions are not implemented for the types +.Dq Li char , +.Dq Li short , +.Dq Li ptr , +.Dq Li 8 , +and +.Dq Li 16 +and do not have any variants with memory barriers at this time. +.Bl -hang +.It Fn atomic_testandset p v +.Bd -literal -compact +bit = 1 << (v % (sizeof(*p) * NBBY)); +tmp = (*p & bit) != 0; +*p |= bit; +return (tmp); +.Ed +.El +.Pp +The +.Fn atomic_testandset +functions are only implemented for the types +.Dq Li int , +.Dq Li long +and +.Dq Li 32 +and do not have any variants with memory barriers at this time. +.Pp +The type +.Dq Li 64 +is currently not implemented for any of the atomic operations on the +.Tn arm , +.Tn i386 , +and +.Tn powerpc +architectures. +.Sh RETURN VALUES +The +.Fn atomic_cmpset +function returns the result of the compare operation. +The +.Fn atomic_fetchadd , +.Fn atomic_load , +.Fn atomic_readandclear , +and +.Fn atomic_swap +functions return the value at the specified address. +The +.Fn atomic_testandset +function returns the result of the test operation. +.Sh EXAMPLES +This example uses the +.Fn atomic_cmpset_acq_ptr +and +.Fn atomic_set_ptr +functions to obtain a sleep mutex and handle recursion. +Since the +.Va mtx_lock +member of a +.Vt "struct mtx" +is a pointer, the +.Dq Li ptr +type is used. +.Bd -literal +/* Try to obtain mtx_lock once. */ +#define _obtain_lock(mp, tid) \\ + atomic_cmpset_acq_ptr(&(mp)->mtx_lock, MTX_UNOWNED, (tid)) + +/* Get a sleep lock, deal with recursion inline. */ +#define _get_sleep_lock(mp, tid, opts, file, line) do { \\ + uintptr_t _tid = (uintptr_t)(tid); \\ + \\ + if (!_obtain_lock(mp, tid)) { \\ + if (((mp)->mtx_lock & MTX_FLAGMASK) != _tid) \\ + _mtx_lock_sleep((mp), _tid, (opts), (file), (line));\\ + else { \\ + atomic_set_ptr(&(mp)->mtx_lock, MTX_RECURSE); \\ + (mp)->mtx_recurse++; \\ + } \\ + } \\ +} while (0) +.Ed +.Sh HISTORY +The +.Fn atomic_add , +.Fn atomic_clear , +.Fn atomic_set , +and +.Fn atomic_subtract +operations were first introduced in +.Fx 3.0 . +This first set only supported the types +.Dq Li char , +.Dq Li short , +.Dq Li int , +and +.Dq Li long . +The +.Fn atomic_cmpset , +.Fn atomic_load , +.Fn atomic_readandclear , +and +.Fn atomic_store +operations were added in +.Fx 5.0 . +The types +.Dq Li 8 , +.Dq Li 16 , +.Dq Li 32 , +.Dq Li 64 , +and +.Dq Li ptr +and all of the acquire and release variants +were added in +.Fx 5.0 +as well. +The +.Fn atomic_fetchadd +operations were added in +.Fx 6.0 . +The +.Fn atomic_swap +and +.Fn atomic_testandset +operations were added in +.Fx 10.0 . Property changes on: user/imp/camdoc/atomic.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/PCI_IOV_ADD_VF.9 =================================================================== --- user/imp/camdoc/PCI_IOV_ADD_VF.9 (nonexistent) +++ user/imp/camdoc/PCI_IOV_ADD_VF.9 (revision 296049) @@ -0,0 +1,112 @@ +.\" +.\" Copyright (c) 2014 Sandvine 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 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 28, 2015 +.Dt PCI_IOV_ADD_VF 9 +.Os +.Sh NAME +.Nm PCI_IOV_ADD_VF +.Nd inform a PF driver that a VF is being created +.Sh SYNOPSIS +.In sys/bus.h +.In machine/stdarg.h +.In sys/nv.h +.In dev/pci/pci_iov.h +.Ft int +.Fn PCI_IOV_ADD_VF "device_t dev" "uint16_t vfnum" "const nvlist_t *vf_config" +.Sh DESCRIPTION +The +.Fn PCI_IOV_ADD_VF +method is called by the PCI Single-Root I/O Virtualization +.Pq SR-IOV +infrastructure when it is initializating a new Virtual Function (VF) as a child +of the given Physical Function (PF) device. +This method will not be called until a successful call to +.Xr PCI_IOV_INIT 9 +has been made. +It is not guaranteed that this method will be called following a successful call +to +.Xr PCI_IOV_INIT 9 . +If the infrastructure encounters a failure to allocate resources following the +call to +.Xr PCI_IOV_INIT 9 , +the VF creation will be aborted and +.Xr PCI_IOV_UNINIT 9 +will be called immediately without any preceding calls to +.Nm . +.Pp +The index of the VF being initialized is passed in the +.Fa vfnum +argument. +VFs are always numbered sequentially starting at 0. +.Pp +If the driver requested device-specific configuration parameters via a VF schema +in its call to +.Xr pci_iov_attach 9 , +those parameters will be contained in the +.Pa vf_config +argument. +All configuration parameters that were either set as required parameters or that +had a default value set in the VF schema are guaranteed to be present in +.Fa vf_config . +Configuration parameters that were neither set as required nor were given a +default value are optional and may or may not be present in +.Fa vf_config . +.Fa vf_config +will not contain any configuration parameters that were not specified in the VF +schema. +All configuration parameters will have the correct type and will be in the range +of valid values specified in the schema. +.Pp +Note that it is possible for the user to set different configuration values on +different VF devices that are children of the same PF. +The PF driver must not cache configuration parameters passed in previous calls +to +.Fn PCI_IOV_ADD_VF +for other VFs and apply those parameters to the current VF. +.Pp +This function will not be called twice for the same +.Fa vf_num +on the same PF device without +.Xr PCI_IOV_UNINIT 9 +and +.Xr PCI_IOV_INIT 9 +first being called, in that order. +.Sh RETURN VALUES +This method returns 0 on success, otherwise an appropriate error is returned. +If this method returns an error then the current VF device will be destroyed +but the rest of the VF devices will be created and SR-IOV will be enabled on +the PF. +.Sh SEE ALSO +.Xr nv 9 , +.Xr pci 9 , +.Xr PCI_IOV_INIT 9 , +.Xr pci_iov_schema 9 , +.Xr PCI_IOV_UNINIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq Mt rstone@FreeBSD.org . Property changes on: user/imp/camdoc/PCI_IOV_ADD_VF.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/PCI_IOV_INIT.9 =================================================================== --- user/imp/camdoc/PCI_IOV_INIT.9 (nonexistent) +++ user/imp/camdoc/PCI_IOV_INIT.9 (revision 296049) @@ -0,0 +1,85 @@ +.\" +.\" Copyright (c) 2014 Sandvine 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 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 28, 2015 +.Dt PCI_IOV_INIT 9 +.Os +.Sh NAME +.Nm PCI_IOV_INIT +.Nd enable SR-IOV on a PF device +.Sh SYNOPSIS +.In sys/bus.h +.In machine/stdarg.h +.In sys/nv.h +.In dev/pci/pci_iov.h +.Ft int +.Fn PCI_IOV_INIT "device_t dev" "uint16_t num_vfs" "const nvlist_t *pf_config" +.Sh DESCRIPTION +The +.Fn PCI_IOV_INIT +method is called by the PCI Single-Root I/O Virtualization (SR-IOV) +infrastucture when the user requests that SR-IOV be enabled on a Physical +Function (PF). +The number of Virtual Functions (VFs) that will be created is passed to this +method in the +.Fa num_vfs +argument. +.Pp +If the driver requested device-specific PF configuration parameters via a PF +schema in its call to +.Xr pci_iov_attach 9 , +those parameters will be available in the +.Fa pf_config +argument. +All configuration parameters that were either set as required parameters or that +had a default value set in the PF schema are guaranteed to be present in +.Fa pf_config . +Configuration parameters that were neither set as required nor were given a +default value are optional and may or may not be present in +.Fa pf_config . +.Fa pf_config +will not contain any configuration parameters that were not specified in the PF +schema. +All configuration parameters will have the correct type and are in the range of +valid values specified in the schema. +.Pp +If this method returns successfully, then this method will not be called again +on the same device until after a call to +.Xr PCI_IOV_UNINIT . +.Sh RETURN VALUES +Returns 0 on success, otherwise an appropriate error is returned. +If this method returns an error then the SR-IOV configuration will be aborted +and no VFs will be created. +.Sh SEE ALSO +.Xr nv 9 , +.Xr pci 9 , +.Xr PCI_IOV_ADD_VF 9 , +.Xr pci_iov_schema 9 , +.Xr PCI_IOV_UNINIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq Mt rstone@FreeBSD.org . Property changes on: user/imp/camdoc/PCI_IOV_INIT.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/altq.9 =================================================================== --- user/imp/camdoc/altq.9 (nonexistent) +++ user/imp/camdoc/altq.9 (revision 296049) @@ -0,0 +1,598 @@ +.\" $NetBSD: altq.9,v 1.8 2002/05/28 11:41:45 wiz Exp $ +.\" $OpenBSD: altq.9,v 1.4 2001/07/12 12:41:42 itojun Exp $ +.\" +.\" Copyright (C) 2004 Max Laier. All rights reserved. +.\" Copyright (C) 2001 +.\" Sony Computer Science Laboratories 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 SONY CSL 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 SONY CSL 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 25, 2004 +.Dt ALTQ 9 +.Os +.\" +.Sh NAME +.Nm ALTQ +.Nd kernel interfaces for manipulating output queues on network interfaces +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/if.h +.In net/if_var.h +.\" +.Ss Enqueue macros +.Fn IFQ_ENQUEUE "struct ifaltq *ifq" "struct mbuf *m" "int error" +.Fn IFQ_HANDOFF "struct ifnet *ifp" "struct mbuf *m" "int error" +.Fo IFQ_HANDOFF_ADJ +.Fa "struct ifnet *ifp" "struct mbuf *m" "int adjust" "int error" +.Fc +.\" +.Ss Dequeue macros +.Fn IFQ_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_POLL_NOLOCK "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_PURGE "struct ifaltq *ifq" +.Fn IFQ_IS_EMPTY "struct ifaltq *ifq" +.\" +.Ss Driver managed dequeue macros +.Fn IFQ_DRV_DEQUEUE "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_DRV_PREPEND "struct ifaltq *ifq" "struct mbuf *m" +.Fn IFQ_DRV_PURGE "struct ifaltq *ifq" +.Fn IFQ_DRV_IS_EMPTY "struct ifaltq *ifq" +.\" +.Ss General setup macros +.Fn IFQ_SET_MAXLEN "struct ifaltq *ifq" "int len" +.Fn IFQ_INC_LEN "struct ifaltq *ifq" +.Fn IFQ_DEC_LEN "struct ifaltq *ifq" +.Fn IFQ_INC_DROPS "struct ifaltq *ifq" +.Fn IFQ_SET_READY "struct ifaltq *ifq" +.Sh DESCRIPTION +The +.Nm +system is a framework to manage queuing disciplines on network +interfaces. +.Nm +introduces new macros to manipulate output queues. +The output queue macros are used to abstract queue operations and not to +touch the internal fields of the output queue structure. +The macros are independent from the +.Nm +implementation, and compatible with the traditional +.Vt ifqueue +macros for ease of transition. +.Pp +.Fn IFQ_ENQUEUE , +.Fn IFQ_HANDOFF +and +.Fn IFQ_HANDOFF_ADJ +enqueue a packet +.Fa m +to the queue +.Fa ifq . +The underlying queuing discipline may discard the packet. +The +.Fa error +argument is set to 0 on success, or +.Er ENOBUFS +if the packet is discarded. +The packet pointed to by +.Fa m +will be freed by the device driver on success, or by the queuing discipline on +failure, so the caller should not touch +.Fa m +after enqueuing. +.Fn IFQ_HANDOFF +and +.Fn IFQ_HANDOFF_ADJ +combine the enqueue operation with statistic generation and call +.Fn if_start +upon successful enqueue to initiate the actual send. +.Pp +.Fn IFQ_DEQUEUE +dequeues a packet from the queue. +The dequeued packet is returned in +.Fa m , +or +.Fa m +is set to +.Dv NULL +if no packet is dequeued. +The caller must always check +.Fa m +since a non-empty queue could return +.Dv NULL +under rate-limiting. +.Pp +.Fn IFQ_POLL_NOLOCK +returns the next packet without removing it from the queue. +The caller must hold the queue mutex when calling +.Fn IFQ_POLL_NOLOCK +in order to guarantee that a subsequent call to +.Fn IFQ_DEQUEUE_NOLOCK +dequeues the same packet. +.Pp +.Fn IFQ_*_NOLOCK +variants (if available) always assume that the caller holds the queue mutex. +They can be grabbed with +.Fn IFQ_LOCK +and released with +.Fn IFQ_UNLOCK . +.Pp +.Fn IFQ_PURGE +discards all the packets in the queue. +The purge operation is needed since a non-work conserving queue cannot be +emptied by a dequeue loop. +.Pp +.Fn IFQ_IS_EMPTY +can be used to check if the queue is empty. +Note that +.Fn IFQ_DEQUEUE +could still return +.Dv NULL +if the queuing discipline is non-work conserving. +.Pp +.Fn IFQ_DRV_DEQUEUE +moves up to +.Fa ifq->ifq_drv_maxlen +packets from the queue to the +.Dq "driver managed" +queue and returns the first one via +.Fa m . +As for +.Fn IFQ_DEQUEUE , +.Fa m +can be +.Dv NULL +even for a non-empty queue. +Subsequent calls to +.Fn IFQ_DRV_DEQUEUE +pass the packets from the +.Dq "driver managed" +queue without obtaining the queue mutex. +It is the responsibility of the caller to protect against concurrent access. +Enabling +.Nm +for a given queue sets +.Va ifq_drv_maxlen +to 0 as the +.Dq "bulk dequeue" +performed by +.Fn IFQ_DRV_DEQUEUE +for higher values of +.Va ifq_drv_maxlen +is adverse to +.Nm ALTQ Ns 's +internal timing. +Note that a driver must not mix +.Fn IFQ_DRV_* +macros with the default dequeue macros as the default macros do not look at the +.Dq "driver managed" +queue which might lead to an mbuf leak. +.Pp +.Fn IFQ_DRV_PREPEND +prepends +.Fa m +to the +.Dq "driver managed" +queue from where it will be obtained with the next call to +.Fn IFQ_DRV_DEQUEUE . +.Pp +.Fn IFQ_DRV_PURGE +flushes all packets in the +.Dq "driver managed" +queue and calls to +.Fn IFQ_PURGE +afterwards. +.Pp +.Fn IFQ_DRV_IS_EMPTY +checks for packets in the +.Dq "driver managed" +part of the queue. +If it is empty, it forwards to +.Fn IFQ_IS_EMPTY . +.Pp +.Fn IFQ_SET_MAXLEN +sets the queue length limit to the default FIFO queue. +The +.Va ifq_drv_maxlen +member of the +.Vt ifaltq +structure controls the length limit of the +.Dq "driver managed" +queue. +.Pp +.Fn IFQ_INC_LEN +and +.Fn IFQ_DEC_LEN +increment or decrement the current queue length in packets. +This is mostly for internal purposes. +.Pp +.Fn IFQ_INC_DROPS +increments the drop counter and is identical to +.Fn IF_DROP . +It is defined for naming consistency only. +.Pp +.Fn IFQ_SET_READY +sets a flag to indicate that a driver was converted to use the new macros. +.Nm +can be enabled only on interfaces with this flag. +.Sh COMPATIBILITY +.Ss Vt ifaltq structure +In order to keep compatibility with the existing code, the new +output queue structure +.Vt ifaltq +has the same fields. +The traditional +.Fn IF_* +macros and the code directly referencing the fields within +.Va if_snd +still work with +.Vt ifaltq . +.Bd -literal + ##old-style## ##new-style## + | + struct ifqueue { | struct ifaltq { + struct mbuf *ifq_head; | struct mbuf *ifq_head; + struct mbuf *ifq_tail; | struct mbuf *ifq_tail; + int ifq_len; | int ifq_len; + int ifq_maxlen; | int ifq_maxlen; + }; | /* driver queue fields */ + | ...... + | /* altq related fields */ + | ...... + | }; + | +.Ed +The new structure replaces +.Vt "struct ifqueue" +in +.Vt "struct ifnet" . +.Bd -literal + ##old-style## ##new-style## + | + struct ifnet { | struct ifnet { + .... | .... + | + struct ifqueue if_snd; | struct ifaltq if_snd; + | + .... | .... + }; | }; + | +.Ed +The (simplified) new +.Fn IFQ_* +macros look like: +.Bd -literal + #define IFQ_DEQUEUE(ifq, m) \e + if (ALTQ_IS_ENABLED((ifq)) \e + ALTQ_DEQUEUE((ifq), (m)); \e + else \e + IF_DEQUEUE((ifq), (m)); +.Ed +.Ss Enqueue operation +The semantics of the enqueue operation is changed. +In the new style, +enqueue and packet drop are combined since they cannot be easily +separated in many queuing disciplines. +The new enqueue operation corresponds to the following macro that is +written with the old macros. +.Bd -literal +#define IFQ_ENQUEUE(ifq, m, error) \e +do { \e + if (IF_QFULL((ifq))) { \e + m_freem((m)); \e + (error) = ENOBUFS; \e + IF_DROP(ifq); \e + } else { \e + IF_ENQUEUE((ifq), (m)); \e + (error) = 0; \e + } \e +} while (0) +.Ed +.Pp +.Fn IFQ_ENQUEUE +does the following: +.Pp +.Bl -hyphen -compact +.It +queue a packet, +.It +drop (and free) a packet if the enqueue operation fails. +.El +.Pp +If the enqueue operation fails, +.Fa error +is set to +.Er ENOBUFS . +The +.Fa m +mbuf is freed by the queuing discipline. +The caller should not touch mbuf after calling +.Fn IFQ_ENQUEUE +so that the caller may need to copy +.Va m_pkthdr.len +or +.Va m_flags +field beforehand for statistics. +.Fn IFQ_HANDOFF +and +.Fn IFQ_HANDOFF_ADJ +can be used if only default interface statistics and an immediate call to +.Fn if_start +are desired. +The caller should not use +.Fn senderr +since mbuf was already freed. +.Pp +The new style +.Fn if_output +looks as follows: +.Bd -literal + ##old-style## ##new-style## + | + int | int + ether_output(ifp, m0, dst, rt0) | ether_output(ifp, m0, dst, rt0) + { | { + ...... | ...... + | + | mflags = m->m_flags; + | len = m->m_pkthdr.len; + s = splimp(); | s = splimp(); + if (IF_QFULL(&ifp->if_snd)) { | IFQ_ENQUEUE(&ifp->if_snd, m, + | error); + IF_DROP(&ifp->if_snd); | if (error != 0) { + splx(s); | splx(s); + senderr(ENOBUFS); | return (error); + } | } + IF_ENQUEUE(&ifp->if_snd, m); | + ifp->if_obytes += | ifp->if_obytes += len; + m->m_pkthdr.len; | + if (m->m_flags & M_MCAST) | if (mflags & M_MCAST) + ifp->if_omcasts++; | ifp->if_omcasts++; + | + if ((ifp->if_flags & IFF_OACTIVE) | if ((ifp->if_flags & IFF_OACTIVE) + == 0) | == 0) + (*ifp->if_start)(ifp); | (*ifp->if_start)(ifp); + splx(s); | splx(s); + return (error); | return (error); + | + bad: | bad: + if (m) | if (m) + m_freem(m); | m_freem(m); + return (error); | return (error); + } | } + | +.Ed +.Sh HOW TO CONVERT THE EXISTING DRIVERS +First, make sure the corresponding +.Fn if_output +is already converted to the new style. +.Pp +Look for +.Va if_snd +in the driver. +Probably, you need to make changes to the lines that include +.Va if_snd . +.Ss Empty check operation +If the code checks +.Va ifq_head +to see whether the queue is empty or not, use +.Fn IFQ_IS_EMPTY . +.Bd -literal + ##old-style## ##new-style## + | + if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_IS_EMPTY(&ifp->if_snd)) + | +.Ed +.Fn IFQ_IS_EMPTY +only checks if there is any packet stored in the queue. +Note that even when +.Fn IFQ_IS_EMPTY +is +.Dv FALSE , +.Fn IFQ_DEQUEUE +could still return +.Dv NULL +if the queue is under rate-limiting. +.Ss Dequeue operation +Replace +.Fn IF_DEQUEUE +by +.Fn IFQ_DEQUEUE . +Always check whether the dequeued mbuf is +.Dv NULL +or not. +Note that even when +.Fn IFQ_IS_EMPTY +is +.Dv FALSE , +.Fn IFQ_DEQUEUE +could return +.Dv NULL +due to rate-limiting. +.Bd -literal + ##old-style## ##new-style## + | + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE(&ifp->if_snd, m); + | if (m == NULL) + | return; + | +.Ed +A driver is supposed to call +.Fn if_start +from transmission complete interrupts in order to trigger the next dequeue. +.Ss Poll-and-dequeue operation +If the code polls the packet at the head of the queue and actually uses +the packet before dequeuing it, use +.Fn IFQ_POLL_NOLOCK +and +.Fn IFQ_DEQUEUE_NOLOCK . +.Bd -literal + ##old-style## ##new-style## + | + | IFQ_LOCK(&ifp->if_snd); + m = ifp->if_snd.ifq_head; | IFQ_POLL_NOLOCK(&ifp->if_snd, m); + if (m != NULL) { | if (m != NULL) { + | + /* use m to get resources */ | /* use m to get resources */ + if (something goes wrong) | if (something goes wrong) + | IFQ_UNLOCK(&ifp->if_snd); + return; | return; + | + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m); + | IFQ_UNLOCK(&ifp->if_snd); + | + /* kick the hardware */ | /* kick the hardware */ + } | } + | +.Ed +It is guaranteed that +.Fn IFQ_DEQUEUE_NOLOCK +under the same lock as a previous +.Fn IFQ_POLL_NOLOCK +returns the same packet. +Note that they need to be guarded by +.Fn IFQ_LOCK . +.Ss Eliminating Fn IF_PREPEND +If the code uses +.Fn IF_PREPEND , +you have to eliminate it unless you can use a +.Dq "driver managed" +queue which allows the use of +.Fn IFQ_DRV_PREPEND +as a substitute. +A common usage of +.Fn IF_PREPEND +is to cancel the previous dequeue operation. +You have to convert the logic into poll-and-dequeue. +.Bd -literal + ##old-style## ##new-style## + | + | IFQ_LOCK(&ifp->if_snd); + IF_DEQUEUE(&ifp->if_snd, m); | IFQ_POLL_NOLOCK(&ifp->if_snd, m); + if (m != NULL) { | if (m != NULL) { + | + if (something_goes_wrong) { | if (something_goes_wrong) { + IF_PREPEND(&ifp->if_snd, m); | IFQ_UNLOCK(&ifp->if_snd); + return; | return; + } | } + | + | /* at this point, the driver + | * is committed to send this + | * packet. + | */ + | IFQ_DEQUEUE_NOLOCK(&ifp->if_snd, m); + | IFQ_UNLOCK(&ifp->if_snd); + | + /* kick the hardware */ | /* kick the hardware */ + } | } + | +.Ed +.Ss Purge operation +Use +.Fn IFQ_PURGE +to empty the queue. +Note that a non-work conserving queue cannot be emptied by a dequeue loop. +.Bd -literal + ##old-style## ##new-style## + | + while (ifp->if_snd.ifq_head != NULL) {| IFQ_PURGE(&ifp->if_snd); + IF_DEQUEUE(&ifp->if_snd, m); | + m_freem(m); | + } | + | +.Ed +.Ss Conversion using a driver managed queue +Convert +.Fn IF_* +macros to their equivalent +.Fn IFQ_DRV_* +and employ +.Fn IFQ_DRV_IS_EMPTY +where appropriate. +.Bd -literal + ##old-style## ##new-style## + | + if (ifp->if_snd.ifq_head != NULL) | if (!IFQ_DRV_IS_EMPTY(&ifp->if_snd)) + | +.Ed +Make sure that calls to +.Fn IFQ_DRV_DEQUEUE , +.Fn IFQ_DRV_PREPEND +and +.Fn IFQ_DRV_PURGE +are protected with a mutex of some kind. +.Ss Attach routine +Use +.Fn IFQ_SET_MAXLEN +to set +.Va ifq_maxlen +to +.Fa len . +Initialize +.Va ifq_drv_maxlen +with a sensible value if you plan to use the +.Fn IFQ_DRV_* +macros. +Add +.Fn IFQ_SET_READY +to show this driver is converted to the new style. +(This is used to distinguish new-style drivers.) +.Bd -literal + ##old-style## ##new-style## + | + ifp->if_snd.ifq_maxlen = qsize; | IFQ_SET_MAXLEN(&ifp->if_snd, qsize); + | ifp->if_snd.ifq_drv_maxlen = qsize; + | IFQ_SET_READY(&ifp->if_snd); + if_attach(ifp); | if_attach(ifp); + | +.Ed +.Ss Other issues +The new macros for statistics: +.Bd -literal + ##old-style## ##new-style## + | + IF_DROP(&ifp->if_snd); | IFQ_INC_DROPS(&ifp->if_snd); + | + ifp->if_snd.ifq_len++; | IFQ_INC_LEN(&ifp->if_snd); + | + ifp->if_snd.ifq_len--; | IFQ_DEC_LEN(&ifp->if_snd); + | +.Ed +.Sh QUEUING DISCIPLINES +Queuing disciplines need to maintain +.Fa ifq_len +(used by +.Fn IFQ_IS_EMPTY ) . +Queuing disciplines also need to guarantee that the same mbuf is returned if +.Fn IFQ_DEQUEUE +is called immediately after +.Fn IFQ_POLL . +.Sh SEE ALSO +.Xr pf 4 , +.Xr pf.conf 5 , +.Xr pfctl 8 +.Sh HISTORY +The +.Nm +system first appeared in March 1997. Property changes on: user/imp/camdoc/altq.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ifnet.9 =================================================================== --- user/imp/camdoc/ifnet.9 (nonexistent) +++ user/imp/camdoc/ifnet.9 (revision 296049) @@ -0,0 +1,1530 @@ +.\" -*- Nroff -*- +.\" Copyright 1996, 1997 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 29, 2014 +.Dt IFNET 9 +.Os +.Sh NAME +.Nm ifnet , +.Nm ifaddr , +.Nm ifqueue , +.Nm if_data +.Nd kernel interfaces for manipulating network interfaces +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/socket.h +.In net/if.h +.In net/if_var.h +.In net/if_types.h +.\" +.Ss "Interface Manipulation Functions" +.Ft "struct ifnet *" +.Fn if_alloc "u_char type" +.Ft void +.Fn if_attach "struct ifnet *ifp" +.Ft void +.Fn if_detach "struct ifnet *ifp" +.Ft void +.Fn if_free "struct ifnet *ifp" +.Ft void +.Fn if_free_type "struct ifnet *ifp" "u_char type" +.Ft void +.Fn if_down "struct ifnet *ifp" +.Ft int +.Fn ifioctl "struct socket *so" "u_long cmd" "caddr_t data" "struct thread *td" +.Ft int +.Fn ifpromisc "struct ifnet *ifp" "int pswitch" +.Ft int +.Fn if_allmulti "struct ifnet *ifp" "int amswitch" +.Ft "struct ifnet *" +.Fn ifunit "const char *name" +.Ft "struct ifnet *" +.Fn ifunit_ref "const char *name" +.Ft void +.Fn if_up "struct ifnet *ifp" +.\" +.Ss "Interface Address Functions" +.Ft "struct ifaddr *" +.Fn ifaddr_byindex "u_short idx" +.Ft "struct ifaddr *" +.Fn ifa_ifwithaddr "struct sockaddr *addr" +.Ft "struct ifaddr *" +.Fn ifa_ifwithdstaddr "struct sockaddr *addr" "int fib" +.Ft "struct ifaddr *" +.Fn ifa_ifwithnet "struct sockaddr *addr" "int ignore_ptp" "int fib" +.Ft "struct ifaddr *" +.Fn ifaof_ifpforaddr "struct sockaddr *addr" "struct ifnet *ifp" +.Ft void +.Fn ifa_ref "struct ifaddr *ifa" +.Ft void +.Fn ifa_free "struct ifaddr *ifa" +.\" +.Ss "Interface Multicast Address Functions" +.Ft int +.Fn if_addmulti "struct ifnet *ifp" "struct sockaddr *sa" "struct ifmultiaddr **ifmap" +.Ft int +.Fn if_delmulti "struct ifnet *ifp" "struct sockaddr *sa" +.Ft "struct ifmultiaddr *" +.Fn if_findmulti "struct ifnet *ifp" "struct sockaddr *sa" +.Ss "Output queue macros" +.Fn IF_DEQUEUE "struct ifqueue *ifq" "struct mbuf *m" +.\" +.Ss "struct ifnet Member Functions" +.Ft void +.Fn \*(lp*if_input\*(rp "struct ifnet *ifp" "struct mbuf *m" +.Ft int +.Fo \*(lp*if_output\*(rp +.Fa "struct ifnet *ifp" "struct mbuf *m" +.Fa "const struct sockaddr *dst" "struct route *ro" +.Fc +.Ft void +.Fn \*(lp*if_start\*(rp "struct ifnet *ifp" +.Ft int +.Fn \*(lp*if_transmit\*(rp "struct ifnet *ifp" "struct mbuf *m" +.Ft void +.Fn \*(lp*if_qflush\*(rp "struct ifnet *ifp" +.Ft int +.Fn \*(lp*if_ioctl\*(rp "struct ifnet *ifp" "u_long cmd" "caddr_t data" +.Ft void +.Fn \*(lp*if_init\*(rp "void *if_softc" +.Ft int +.Fo \*(lp*if_resolvemulti\*(rp +.Fa "struct ifnet *ifp" "struct sockaddr **retsa" "struct sockaddr *addr" +.Fc +.Ss "struct ifaddr member function" +.Ft void +.Fo \*(lp*ifa_rtrequest\*(rp +.Fa "int cmd" "struct rtentry *rt" "struct rt_addrinfo *info" +.Fc +.\" +.Ss "Global Variables" +.Vt extern struct ifnethead ifnet ; +.\" extern struct ifindex_entry *ifindex_table ; +.Vt extern int if_index ; +.Vt extern int ifqmaxlen ; +.Sh DATA STRUCTURES +The kernel mechanisms for handling network interfaces reside primarily +in the +.Vt ifnet , if_data , ifaddr , +and +.Vt ifmultiaddr +structures in +.In net/if.h +and +.In net/if_var.h +and the functions named above and defined in +.Pa /sys/net/if.c . +Those interfaces which are intended to be used by user programs +are defined in +.In net/if.h ; +these include the interface flags, the +.Vt if_data +structure, and the structures defining the appearance of +interface-related messages on the +.Xr route 4 +routing socket and in +.Xr sysctl 3 . +The header file +.In net/if_var.h +defines the kernel-internal interfaces, including the +.Vt ifnet , ifaddr , +and +.Vt ifmultiaddr +structures and the functions which manipulate them. +(A few user programs will need +.In net/if_var.h +because it is the prerequisite of some other header file like +.In netinet/if_ether.h . +Most references to those two files in particular can be replaced by +.In net/ethernet.h . ) +.Pp +The system keeps a linked list of interfaces using the +.Li TAILQ +macros defined in +.Xr queue 3 ; +this list is headed by a +.Vt "struct ifnethead" +called +.Va ifnet . +The elements of this list are of type +.Vt "struct ifnet" , +and most kernel routines which manipulate interface as such accept or +return pointers to these structures. +Each interface structure +contains an +.Vt if_data +structure used for statistics and information. +Each interface also has a +.Li TAILQ +of interface addresses, described by +.Vt ifaddr +structures. +An +.Dv AF_LINK +address +(see +.Xr link_addr 3 ) +describing the link layer implemented by the interface (if any) +is accessed by the +.Fn ifaddr_byindex +function or +.Va if_addr +structure. +(Some trivial interfaces do not provide any link layer addresses; +this structure, while still present, serves only to identify the +interface name and index.) +.Pp +Finally, those interfaces supporting reception of multicast datagrams +have a +.Li TAILQ +of multicast group memberships, described by +.Vt ifmultiaddr +structures. +These memberships are reference-counted. +.Pp +Interfaces are also associated with an output queue, defined as a +.Vt "struct ifqueue" ; +this structure is used to hold packets while the interface is in the +process of sending another. +.Pp +.Ss The ifnet Structure +The fields of +.Vt "struct ifnet" +are as follows: +.Bl -tag -width ".Va if_capabilities" -offset indent +.It Va if_softc +.Pq Vt "void *" +A pointer to the driver's private state block. +(Initialized by driver.) +.It Va if_l2com +.Pq Vt "void *" +A pointer to the common data for the interface's layer 2 protocol. +(Initialized by +.Fn if_alloc . ) +.It Va if_vnet +.Pq Vt "struct vnet *" +A pointer to the virtual network stack instance. +(Initialized by +.Fn if_attach . ) +.It Va if_home_vnet +.Pq Vt "struct vnet *" +A pointer to the parent virtual network stack, where this +.Vt "struct ifnet" +originates from. +(Initialized by +.Fn if_attach . ) +.It Va if_link +.Pq Fn TAILQ_ENTRY ifnet +.Xr queue 3 +macro glue. +.It Va if_xname +.Pq Vt "char *" +The name of the interface, +(e.g., +.Dq Li fxp0 +or +.Dq Li lo0 ) . +(Initialized by driver +(usually via +.Fn if_initname ) . ) +.It Va if_dname +.Pq Vt "const char *" +The name of the driver. +(Initialized by driver +(usually via +.Fn if_initname ) . ) +.It Va if_dunit +.Pq Vt int +A unique number assigned to each interface managed by a particular +driver. +Drivers may choose to set this to +.Dv IF_DUNIT_NONE +if a unit number is not associated with the device. +(Initialized by driver +(usually via +.Fn if_initname ) . ) +.It Va if_refcount +.Pq Vt u_int +The reference count. +(Initialized by +.Fn if_alloc . ) +.It Va if_addrhead +.Pq Vt "struct ifaddrhead" +The head of the +.Xr queue 3 +.Li TAILQ +containing the list of addresses assigned to this interface. +.It Va if_pcount +.Pq Vt int +A count of promiscuous listeners on this interface, used to +reference-count the +.Dv IFF_PROMISC +flag. +.It Va if_carp +.Pq Vt "struct carp_if *" +A pointer to the CARP interface structure, +.Xr carp 4 . +(Initialized by the driver-specific +.Fn if_ioctl +routine.) +.It Va if_bpf +.Pq Vt "struct bpf_if *" +Opaque per-interface data for the packet filter, +.Xr bpf 4 . +(Initialized by +.Fn bpf_attach . ) +.It Va if_index +.Pq Vt u_short +A unique number assigned to each interface in sequence as it is +attached. +This number can be used in a +.Vt "struct sockaddr_dl" +to refer to a particular interface by index +(see +.Xr link_addr 3 ) . +(Initialized by +.Fn if_alloc . ) +.It Va if_vlantrunk +.Pq Vt struct ifvlantrunk * +A pointer to 802.1Q trunk structure, +.Xr vlan 4 . +(Initialized by the driver-specific +.Fn if_ioctl +routine.) +.It Va if_flags +.Pq Vt int +Flags describing operational parameters of this interface (see below). +(Manipulated by generic code.) +.It Va if_drv_flags +.Pq Vt int +Flags describing operational status of this interface (see below). +(Manipulated by driver.) +.It Va if_capabilities +.Pq Vt int +Flags describing the capabilities the interface supports (see below). +.It Va if_capenable +.Pq Vt int +Flags describing the enabled capabilities of the interface (see below). +.It Va if_linkmib +.Pq Vt "void *" +A pointer to an interface-specific MIB structure exported by +.Xr ifmib 4 . +(Initialized by driver.) +.It Va if_linkmiblen +.Pq Vt size_t +The size of said structure. +(Initialized by driver.) +.It Va if_data +.Pq Vt "struct if_data" +More statistics and information; see +.Sx "The if_data structure" , +below. +(Initialized by driver, manipulated by both driver and generic +code.) +.It Va if_multiaddrs +.Pq Vt struct ifmultihead +The head of the +.Xr queue 3 +.Li TAILQ +containing the list of multicast addresses assigned to this interface. +.It Va if_amcount +.Pq Vt int +A number of multicast requests on this interface, used to +reference-count the +.Dv IFF_ALLMULTI +flag. +.It Va if_addr +.Pq Vt "struct ifaddr *" +A pointer to the link-level interface address. +(Initialized by +.Fn if_alloc . ) +.\" .It Va if_llsoftc +.\" .Pq Vt "void *" +.\" The purpose of the field is unclear. +.It Va if_snd +.Pq Vt "struct ifaltq" +The output queue. +(Manipulated by driver.) +.It Va if_broadcastaddr +.Pq Vt "const u_int8_t *" +A link-level broadcast bytestring for protocols with variable address +length. +.It Va if_bridge +.Pq Vt "void *" +A pointer to the bridge interface structure, +.Xr if_bridge 4 . +(Initialized by the driver-specific +.Fn if_ioctl +routine.) +.It Va if_label +.Pq Vt "struct label *" +A pointer to the MAC Framework label structure, +.Xr mac 4 . +(Initialized by +.Fn if_alloc . ) +.It Va if_afdata +.Pq Vt "void *" +An address family dependent data region. +.It Va if_afdata_initialized +.Pq Vt int +Used to track the current state of address family initialization. +.It Va if_afdata_lock +.Pq Vt "struct rwlock" +An +.Xr rwlock 9 +lock used to protect +.Va if_afdata +internals. +.It Va if_linktask +.Pq Vt "struct task" +A +.Xr taskqueue 9 +task scheduled for link state change events of the interface. +.It Va if_addr_lock +.Pq Vt "struct rwlock" +An +.Xr rwlock 9 +lock used to protect interface-related address lists. +.It Va if_clones +.Pq Fn LIST_ENTRY ifnet +.Xr queue 3 +macro glue for the list of clonable network interfaces. +.It Va if_groups +.Pq Fn TAILQ_HEAD "" "ifg_list" +The head of the +.Xr queue 3 +.Li TAILQ +containing the list of groups per interface. +.It Va if_pf_kif +.Pq Vt "void *" +A pointer to the structure used for interface abstraction by +.Xr pf 4 . +.It Va if_lagg +.Pq Vt "void *" +A pointer to the +.Xr lagg 4 +interface structure. +.It Va if_alloctype +.Pq Vt u_char +The type of the interface as it was at the time of its allocation. +It is used to cache the type passed to +.Fn if_alloc , +but unlike +.Va if_type , +it would not be changed by drivers. +.El +.Pp +References to +.Vt ifnet +structures are gained by calling the +.Fn if_ref +function and released by calling the +.Fn if_rele +function. +They are used to allow kernel code walking global interface lists +to release the +.Vt ifnet +lock yet keep the +.Vt ifnet +structure stable. +.Pp +There are in addition a number of function pointers which the driver +must initialize to complete its interface with the generic interface +layer: +.Bl -ohang -offset indent +.It Fn if_input +Pass a packet to an appropriate upper layer as determined +from the link-layer header of the packet. +This routine is to be called from an interrupt handler or +used to emulate reception of a packet on this interface. +A single function implementing +.Fn if_input +can be shared among multiple drivers utilizing the same link-layer +framing, e.g., Ethernet. +.It Fn if_output +Output a packet on interface +.Fa ifp , +or queue it on the output queue if the interface is already active. +.It Fn if_transmit +Transmit a packet on an interface or queue it if the interface is +in use. +This function will return +.Dv ENOBUFS +if the devices software and hardware queues are both full. +This function must be installed after +.Fn if_attach +to override the default implementation. +This function is exposed in order to allow drivers to manage their own queues +and to reduce the latency caused by a frequently gratuitous enqueue / dequeue +pair to ifq. +The suggested internal software queueing mechanism is buf_ring. +.It Fn if_qflush +Free mbufs in internally managed queues when the interface is marked down. +This function must be installed after +.Fn if_attach +to override the default implementation. +This function is exposed in order to allow drivers to manage their own queues +and to reduce the latency caused by a frequently gratuitous enqueue / dequeue +pair to ifq. +The suggested internal software queueing mechanism is buf_ring. +.It Fn if_start +Start queued output on an interface. +This function is exposed in +order to provide for some interface classes to share a +.Fn if_output +among all drivers. +.Fn if_start +may only be called when the +.Dv IFF_DRV_OACTIVE +flag is not set. +(Thus, +.Dv IFF_DRV_OACTIVE +does not literally mean that output is active, but rather that the +device's internal output queue is full.) Please note that this function +will soon be deprecated. +.It Fn if_ioctl +Process interface-related +.Xr ioctl 2 +requests +(defined in +.In sys/sockio.h ) . +Preliminary processing is done by the generic routine +.Fn ifioctl +to check for appropriate privileges, locate the interface being +manipulated, and perform certain generic operations like twiddling +flags and flushing queues. +See the description of +.Fn ifioctl +below for more information. +.It Fn if_init +Initialize and bring up the hardware, +e.g., reset the chip and enable the receiver unit. +Should mark the interface running, +but not active +.Dv ( IFF_DRV_RUNNING , ~IIF_DRV_OACTIVE ) . +.It Fn if_resolvemulti +Check the requested multicast group membership, +.Fa addr , +for validity, and if necessary compute a link-layer group which +corresponds to that address which is returned in +.Fa *retsa . +Returns zero on success, or an error code on failure. +.El +.Ss "Interface Flags" +Interface flags are used for a number of different purposes. +Some +flags simply indicate information about the type of interface and its +capabilities; others are dynamically manipulated to reflect the +current state of the interface. +Flags of the former kind are marked +.Aq S +in this table; the latter are marked +.Aq D . +Flags which begin with +.Dq IFF_DRV_ +are stored in +.Va if_drv_flags ; +all other flags are stored in +.Va if_flags . +.Pp +The macro +.Dv IFF_CANTCHANGE +defines the bits which cannot be set by a user program using the +.Dv SIOCSIFFLAGS +command to +.Xr ioctl 2 ; +these are indicated by an asterisk +.Pq Ql * +in the following listing. +.Pp +.Bl -tag -width ".Dv IFF_POINTOPOINT" -offset indent -compact +.It Dv IFF_UP +.Aq D +The interface has been configured up by the user-level code. +.It Dv IFF_BROADCAST +.Aq S* +The interface supports broadcast. +.It Dv IFF_DEBUG +.Aq D +Used to enable/disable driver debugging code. +.It Dv IFF_LOOPBACK +.Aq S +The interface is a loopback device. +.It Dv IFF_POINTOPOINT +.Aq S* +The interface is point-to-point; +.Dq broadcast +address is actually the address of the other end. +.It Dv IFF_DRV_RUNNING +.Aq D* +The interface has been configured and dynamic resources were +successfully allocated. +Probably only useful internal to the +interface. +.It Dv IFF_NOARP +.Aq D +Disable network address resolution on this interface. +.It Dv IFF_PROMISC +.Aq D* +This interface is in promiscuous mode. +.It Dv IFF_PPROMISC +.Aq D +This interface is in the permanently promiscuous mode (implies +.Dv IFF_PROMISC ) . +.It Dv IFF_ALLMULTI +.Aq D* +This interface is in all-multicasts mode (used by multicast routers). +.It Dv IFF_DRV_OACTIVE +.Aq D* +The interface's hardware output queue (if any) is full; output packets +are to be queued. +.It Dv IFF_SIMPLEX +.Aq S* +The interface cannot hear its own transmissions. +.It Dv IFF_LINK0 +.It Dv IFF_LINK1 +.It Dv IFF_LINK2 +.Aq D +Control flags for the link layer. +(Currently abused to select among +multiple physical layers on some devices.) +.It Dv IFF_MULTICAST +.Aq S* +This interface supports multicast. +.It Dv IFF_CANTCONFIG +.Aq S* +The interface is not configurable in a meaningful way. +Primarily useful for +.Dv IFT_USB +interfaces registered at the interface list. +.It Dv IFF_MONITOR +.Aq D +This interface blocks transmission of packets and discards incoming +packets after BPF processing. +Used to monitor network traffic but not interact +with the network in question. +.It Dv IFF_STATICARP +.Aq D +Used to enable/disable ARP requests on this interface. +.It Dv IFF_DYING +.Aq D* +Set when the +.Vt ifnet +structure of this interface is being released and still has +.Va if_refcount +references. +.It Dv IFF_RENAMING +.Aq D* +Set when this interface is being renamed. +.El +.Ss "Interface Capabilities Flags" +Interface capabilities are specialized features an interface may +or may not support. +These capabilities are very hardware-specific +and allow, when enabled, +to offload specific network processing to the interface +or to offer a particular feature for use by other kernel parts. +.Pp +It should be stressed that a capability can be completely +uncontrolled (i.e., stay always enabled with no way to disable it) +or allow limited control over itself (e.g., depend on another +capability's state.) +Such peculiarities are determined solely by the hardware and driver +of a particular interface. +Only the driver possesses +the knowledge on whether and how the interface capabilities +can be controlled. +Consequently, capabilities flags in +.Va if_capenable +should never be modified directly by kernel code other than +the interface driver. +The command +.Dv SIOCSIFCAP +to +.Fn ifioctl +is the dedicated means to attempt altering +.Va if_capenable +on an interface. +Userland code shall use +.Xr ioctl 2 . +.Pp +The following capabilities are currently supported by the system: +.Bl -tag -width ".Dv IFCAP_POLLING_NOCOUNT" -offset indent +.It Dv IFCAP_RXCSUM +This interface can do checksum validation on receiving data. +Some interfaces do not have sufficient buffer storage to store frames +above a certain MTU-size completely. +The driver for the interface might disable hardware checksum validation +if the MTU is set above the hardcoded limit. +.It Dv IFCAP_TXCSUM +This interface can do checksum calculation on transmitting data. +.It Dv IFCAP_HWCSUM +A shorthand for +.Pq Dv IFCAP_RXCSUM | IFCAP_TXCSUM . +.It Dv IFCAP_NETCONS +This interface can be a network console. +.It Dv IFCAP_VLAN_MTU +The +.Xr vlan 4 +driver can operate over this interface in software tagging mode +without having to decrease MTU on +.Xr vlan 4 +interfaces below 1500 bytes. +This implies the ability of this interface to cope with frames somewhat +longer than permitted by the Ethernet specification. +.It Dv IFCAP_VLAN_HWTAGGING +This interface can do VLAN tagging on output and +demultiplex frames by their VLAN tag on input. +.It Dv IFCAP_JUMBO_MTU +This Ethernet interface can transmit and receive frames up to +9000 bytes long. +.It Dv IFCAP_POLLING +This interface supports +.Xr polling 4 . +See below for details. +.It Dv IFCAP_VLAN_HWCSUM +This interface can do checksum calculation on both transmitting +and receiving data on +.Xr vlan 4 +interfaces (implies +.Dv IFCAP_HWCSUM ) . +.It Dv IFCAP_TSO4 +This Ethernet interface supports TCP4 Segmentation offloading. +.It Dv IFCAP_TSO6 +This Ethernet interface supports TCP6 Segmentation offloading. +.It Dv IFCAP_TSO +A shorthand for +.Pq Dv IFCAP_TSO4 | IFCAP_TSO6 . +.It Dv IFCAP_TOE4 +This Ethernet interface supports TCP offloading. +.It Dv IFCAP_TOE6 +This Ethernet interface supports TCP6 offloading. +.It Dv IFCAP_TOE +A shorthand for +.Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . +.It Dv IFCAP_WOL_UCAST +This Ethernet interface supports waking up on any Unicast packet. +.It Dv IFCAP_WOL_MCAST +This Ethernet interface supports waking up on any Multicast packet. +.It Dv IFCAP_WOL_MAGIC +This Ethernet interface supports waking up on any Magic packet such +as those sent by +.Xr wake 8 . +.It Dv IFCAP_WOL +A shorthand for +.Pq Dv IFCAP_WOL_UCAST | IFCAP_WOL_MCAST | IFCAP_WOL_MAGIC . +.It Dv IFCAP_TOE4 +This Ethernet interface supports TCP4 Offload Engine. +.It Dv IFCAP_TOE6 +This Ethernet interface supports TCP6 Offload Engine. +.It Dv IFCAP_TOE +A shorthand for +.Pq Dv IFCAP_TOE4 | IFCAP_TOE6 . +.It Dv IFCAP_VLAN_HWFILTER +This interface supports frame filtering in hardware on +.Xr vlan 4 +interfaces. +.It Dv IFCAP_POLLING_NOCOUNT +The return value for the number of processed packets should be +skipped for this interface. +.It Dv IFCAP_VLAN_HWTSO +This interface supports TCP Segmentation offloading on +.Xr vlan 4 +interfaces (implies +.Dv IFCAP_TSO ) . +.It Dv IFCAP_LINKSTATE +This Ethernet interface supports dynamic link state changes. +.El +.Pp +The ability of advanced network interfaces to offload certain +computational tasks from the host CPU to the board is limited +mostly to TCP/IP. +Therefore a separate field associated with an interface +(see +.Va ifnet.if_data.ifi_hwassist +below) +keeps a detailed description of its enabled capabilities +specific to TCP/IP processing. +The TCP/IP module consults the field to see which tasks +can be done on an +.Em outgoing +packet by the interface. +The flags defined for that field are a superset of those for +.Va mbuf.m_pkthdr.csum_flags , +namely: +.Bl -tag -width ".Dv CSUM_FRAGMENT" -offset indent +.It Dv CSUM_IP +The interface will compute IP checksums. +.It Dv CSUM_TCP +The interface will compute TCP checksums. +.It Dv CSUM_UDP +The interface will compute UDP checksums. +.It Dv CSUM_IP_FRAGS +The interface can compute a TCP or UDP checksum for a packet +fragmented by the host CPU. +Makes sense only along with +.Dv CSUM_TCP +or +.Dv CSUM_UDP . +.It Dv CSUM_FRAGMENT +The interface will do the fragmentation of IP packets if necessary. +The host CPU does not need to care about MTU on this interface +as long as a packet to transmit through it is an IP one and it +does not exceed the size of the hardware buffer. +.El +.Pp +An interface notifies the TCP/IP module about the tasks +the former has performed on an +.Em incoming +packet by setting the corresponding flags in the field +.Va mbuf.m_pkthdr.csum_flags +of the +.Vt mbuf chain +containing the packet. +See +.Xr mbuf 9 +for details. +.Pp +The capability of a network interface to operate in +.Xr polling 4 +mode involves several flags in different +global variables and per-interface fields. +The capability flag +.Dv IFCAP_POLLING +set in interface's +.Va if_capabilities +indicates support for +.Xr polling 4 +on the particular interface. +If set in +.Va if_capabilities , +the same flag can be marked or cleared in the interface's +.Va if_capenable +within +.Fn ifioctl , +thus initiating switch of the interface to +.Xr polling 4 +mode or interrupt +mode, respectively. +The actual mode change is managed by the driver-specific +.Fn if_ioctl +routine. +The +.Xr polling +handler returns the number of packets processed. +.Ss The if_data Structure +The +.Vt if_data +structure contains statistics and identifying information used +by management programs, and which is exported to user programs by way +of the +.Xr ifmib 4 +branch of the +.Xr sysctl 3 +MIB. +The following elements of the +.Vt if_data +structure are initialized by the interface and are not expected to change +significantly over the course of normal operation: +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_type +.Pq Vt u_char +The type of the interface, as defined in +.In net/if_types.h +and described below in the +.Sx "Interface Types" +section. +.It Va ifi_physical +.Pq Vt u_char +Intended to represent a selection of physical layers on devices which +support more than one; never implemented. +.It Va ifi_addrlen +.Pq Vt u_char +Length of a link-layer address on this device, or zero if there are +none. +Used to initialized the address length field in +.Vt sockaddr_dl +structures referring to this interface. +.It Va ifi_hdrlen +.Pq Vt u_char +Maximum length of any link-layer header which might be prepended by +the driver to a packet before transmission. +The generic code computes +the maximum over all interfaces and uses that value to influence the +placement of data in +.Vt mbuf Ns s +to attempt to ensure that there is always +sufficient space to prepend a link-layer header without allocating an +additional +.Vt mbuf . +.It Va ifi_datalen +.Pq Vt u_char +Length of the +.Vt if_data +structure. +Allows some stabilization of the routing socket ABI in the face of +increases in the length of +.Vt struct ifdata . +.It Va ifi_mtu +.Pq Vt u_long +The maximum transmission unit of the medium, exclusive of any +link-layer overhead. +.It Va ifi_metric +.Pq Vt u_long +A dimensionless metric interpreted by a user-mode routing process. +.It Va ifi_baudrate +.Pq Vt u_long +The line rate of the interface, in bits per second. +.It Va ifi_hwassist +.Pq Vt u_long +A detailed interpretation of the capabilities +to offload computational tasks for +.Em outgoing +packets. +The interface driver must keep this field in accord with +the current value of +.Va if_capenable . +.It Va ifi_epoch +.Pq Vt time_t +The system uptime when interface was attached or the statistics +below were reset. +This is intended to be used to set the SNMP variable +.Va ifCounterDiscontinuityTime . +It may also be used to determine if two successive queries for an +interface of the same index have returned results for the same +interface. +.El +.Pp +The structure additionally contains generic statistics applicable to a +variety of different interface types (except as noted, all members are +of type +.Vt u_long ) : +.Bl -tag -width ".Va ifi_lastchange" -offset indent +.It Va ifi_link_state +.Pq Vt u_char +The current link state of Ethernet interfaces. +See the +.Sx Interface Link States +section for possible values. +.It Va ifi_ipackets +Number of packets received. +.It Va ifi_ierrors +Number of receive errors detected (e.g., FCS errors, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_opackets +Number of packets transmitted. +.It Va ifi_oerrors +Number of output errors detected (e.g., late collisions, DMA overruns, +etc.). +More detailed breakdowns can often be had by way of a +link-specific MIB. +.It Va ifi_collisions +Total number of collisions detected on output for CSMA interfaces. +(This member is sometimes [ab]used by other types of interfaces for +other output error counts.) +.It Va ifi_ibytes +Total traffic received, in bytes. +.It Va ifi_obytes +Total traffic transmitted, in bytes. +.It Va ifi_imcasts +Number of packets received which were sent by link-layer multicast. +.It Va ifi_omcasts +Number of packets sent by link-layer multicast. +.It Va ifi_iqdrops +Number of packets dropped on input. +Rarely implemented. +.It Va ifi_noproto +Number of packets received for unknown network-layer protocol. +.It Va ifi_lastchange +.Pq Vt "struct timeval" +The time of the last administrative change to the interface (as required +for +.Tn SNMP ) . +.El +.Ss Interface Types +The header file +.In net/if_types.h +defines symbolic constants for a number of different types of +interfaces. +The most common are: +.Pp +.Bl -tag -offset indent -width ".Dv IFT_PROPVIRTUAL" -compact +.It Dv IFT_OTHER +none of the following +.It Dv IFT_ETHER +Ethernet +.It Dv IFT_ISO88023 +ISO 8802-3 CSMA/CD +.It Dv IFT_ISO88024 +ISO 8802-4 Token Bus +.It Dv IFT_ISO88025 +ISO 8802-5 Token Ring +.It Dv IFT_ISO88026 +ISO 8802-6 DQDB MAN +.It Dv IFT_FDDI +FDDI +.It Dv IFT_PPP +Internet Point-to-Point Protocol +.Pq Xr ppp 8 +.It Dv IFT_LOOP +The loopback +.Pq Xr lo 4 +interface +.It Dv IFT_SLIP +Serial Line IP +.It Dv IFT_PARA +Parallel-port IP +.Pq Dq Tn PLIP +.It Dv IFT_ATM +Asynchronous Transfer Mode +.It Dv IFT_USB +USB Interface +.El +.Ss Interface Link States +The following link states are currently defined: +.Pp +.Bl -tag -offset indent -width ".Dv LINK_STATE_UNKNOWN" -compact +.It Dv LINK_STATE_UNKNOWN +The link is in an invalid or unknown state. +.It Dv LINK_STATE_DOWN +The link is down. +.It Dv LINK_STATE_UP +The link is up. +.El +.Ss The ifaddr Structure +Every interface is associated with a list +(or, rather, a +.Li TAILQ ) +of addresses, rooted at the interface structure's +.Va if_addrlist +member. +The first element in this list is always an +.Dv AF_LINK +address representing the interface itself; multi-access network +drivers should complete this structure by filling in their link-layer +addresses after calling +.Fn if_attach . +Other members of the structure represent network-layer addresses which +have been configured by means of the +.Dv SIOCAIFADDR +command to +.Xr ioctl 2 , +called on a socket of the appropriate protocol family. +The elements of this list consist of +.Vt ifaddr +structures. +Most protocols will declare their own protocol-specific +interface address structures, but all begin with a +.Vt "struct ifaddr" +which provides the most-commonly-needed functionality across all +protocols. +Interface addresses are reference-counted. +.Pp +The members of +.Vt "struct ifaddr" +are as follows: +.Bl -tag -width ".Va ifa_rtrequest" -offset indent +.It Va ifa_addr +.Pq Vt "struct sockaddr *" +The local address of the interface. +.It Va ifa_dstaddr +.Pq Vt "struct sockaddr *" +The remote address of point-to-point interfaces, and the broadcast +address of broadcast interfaces. +.Va ( ifa_broadaddr +is a macro for +.Va ifa_dstaddr . ) +.It Va ifa_netmask +.Pq Vt "struct sockaddr *" +The network mask for multi-access interfaces, and the confusion +generator for point-to-point interfaces. +.It Va ifa_ifp +.Pq Vt "struct ifnet *" +A link back to the interface structure. +.It Va ifa_link +.Pq Fn TAILQ_ENTRY ifaddr +.Xr queue 3 +glue for list of addresses on each interface. +.It Va ifa_rtrequest +See below. +.It Va ifa_flags +.Pq Vt u_short +Some of the flags which would be used for a route representing this +address in the route table. +.It Va ifa_refcnt +.Pq Vt short +The reference count. +.El +.Pp +References to +.Vt ifaddr +structures are gained by calling the +.Fn ifa_ref +function and released by calling the +.Fn ifa_free +function. +.Pp +.Fn ifa_rtrequest +is a pointer to a function which receives callouts from the routing +code +.Pq Fn rtrequest +to perform link-layer-specific actions upon requests to add, +or delete routes. +The +.Fa cmd +argument indicates the request in question: +.Dv RTM_ADD , +or +.Dv RTM_DELETE . +The +.Fa rt +argument is the route in question; the +.Fa info +argument contains the specific destination being manipulated. +.Sh FUNCTIONS +The functions provided by the generic interface code can be divided +into two groups: those which manipulate interfaces, and those which +manipulate interface addresses. +In addition to these functions, there +may also be link-layer support routines which are used by a number of +drivers implementing a specific link layer over different hardware; +see the documentation for that link layer for more details. +.Ss The ifmultiaddr Structure +Every multicast-capable interface is associated with a list of +multicast group memberships, which indicate at a low level which +link-layer multicast addresses (if any) should be accepted, and at a +high level, in which network-layer multicast groups a user process has +expressed interest. +.Pp +The elements of the structure are as follows: +.Bl -tag -width ".Va ifma_refcount" -offset indent +.It Va ifma_link +.Pq Fn LIST_ENTRY ifmultiaddr +.Xr queue 3 +macro glue. +.It Va ifma_addr +.Pq Vt "struct sockaddr *" +A pointer to the address which this record represents. +The +memberships for various address families are stored in arbitrary +order. +.It Va ifma_lladdr +.Pq Vt "struct sockaddr *" +A pointer to the link-layer multicast address, if any, to which the +network-layer multicast address in +.Va ifma_addr +is mapped, else a null pointer. +If this element is non-nil, this +membership also holds an invisible reference to another membership for +that link-layer address. +.It Va ifma_refcount +.Pq Vt u_int +A reference count of requests for this particular membership. +.El +.Ss Interface Manipulation Functions +.Bl -ohang -offset indent +.It Fn if_alloc +Allocate and initialize +.Vt "struct ifnet" . +Initialization includes the allocation of an interface index and may +include the allocation of a +.Fa type +specific structure in +.Va if_l2com . +.It Fn if_attach +Link the specified interface +.Fa ifp +into the list of network interfaces. +Also initialize the list of +addresses on that interface, and create a link-layer +.Vt ifaddr +structure to be the first element in that list. +(A pointer to +this address structure is saved in the +.Vt ifnet +structure and is accessed by the +.Fn ifaddr_byindex +function.) +The +.Fa ifp +must have been allocated by +.Fn if_alloc . +.It Fn if_detach +Shut down and unlink the specified +.Fa ifp +from the interface list. +.It Fn if_free +Free the given +.Fa ifp +back to the system. +The interface must have been previously detached if it was ever attached. +.It Fn if_free_type +Identical to +.Fn if_free +except that the given +.Fa type +is used to free +.Va if_l2com +instead of the type in +.Va if_type . +This is intended for use with drivers that change their interface type. +.It Fn if_down +Mark the interface +.Fa ifp +as down (i.e., +.Dv IFF_UP +is not set), +flush its output queue, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn if_up +Mark the interface +.Fa ifp +as up, notify protocols of the transition, +and generate a message from the +.Xr route 4 +routing socket. +.It Fn ifpromisc +Add or remove a promiscuous reference to +.Fa ifp . +If +.Fa pswitch +is true, add a reference; +if it is false, remove a reference. +On reference count transitions +from zero to one and one to zero, set the +.Dv IFF_PROMISC +flag appropriately and call +.Fn if_ioctl +to set up the interface in the desired mode. +.It Fn if_allmulti +As +.Fn ifpromisc , +but for the all-multicasts +.Pq Dv IFF_ALLMULTI +flag instead of the promiscuous flag. +.It Fn ifunit +Return an +.Vt ifnet +pointer for the interface named +.Fa name . +.It Fn ifunit_ref +Return a reference-counted (via +.Fn ifa_ref ) +.Vt ifnet +pointer for the interface named +.Fa name . +This is the preferred function over +.Fn ifunit . +The caller is responsible for releasing the reference with +.Fn if_rele +when it is finished with the ifnet. +.It Fn ifioctl +Process the ioctl request +.Fa cmd , +issued on socket +.Fa so +by thread +.Fa td , +with data parameter +.Fa data . +This is the main routine for handling all interface configuration +requests from user mode. +It is ordinarily only called from the socket-layer +.Xr ioctl 2 +handler, and only for commands with class +.Sq Li i . +Any unrecognized commands will be passed down to socket +.Fa so Ns 's +protocol for +further interpretation. +The following commands are handled by +.Fn ifioctl : +.Pp +.Bl -tag -width ".Dv SIOCGIFNETMASK" -offset indent -compact +.It Dv SIOCGIFCONF +Get interface configuration. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFNAME +Set the interface name. +.Dv RTM_IFANNOUNCE +departure and arrival messages are sent so that +routing code that relies on the interface name will update its interface +list. +Caller must have appropriate privilege. +(No call-down to driver.) +.It Dv SIOCGIFCAP +.It Dv SIOCGIFFIB +.It Dv SIOCGIFFLAGS +.It Dv SIOCGIFMETRIC +.It Dv SIOCGIFMTU +.It Dv SIOCGIFPHYS +Get interface capabilities, FIB, flags, metric, MTU, medium selection. +(No call-down to driver.) +.Pp +.It Dv SIOCSIFCAP +Enable or disable interface capabilities. +Caller must have appropriate privilege. +Before a call to the driver-specific +.Fn if_ioctl +routine, the requested mask for enabled capabilities is checked +against the mask of capabilities supported by the interface, +.Va if_capabilities . +Requesting to enable an unsupported capability is invalid. +The rest is supposed to be done by the driver, +which includes updating +.Va if_capenable +and +.Va if_data.ifi_hwassist +appropriately. +.Pp +.It Dv SIOCSIFFIB +Sets interface FIB. +Caller must have appropriate privilege. +FIB values start at 0 and values greater or equals than +.Va net.fibs +are considered invalid. +.It Dv SIOCSIFFLAGS +Change interface flags. +Caller must have appropriate privilege. +If a change to the +.Dv IFF_UP +flag is requested, +.Fn if_up +or +.Fn if_down +is called as appropriate. +Flags listed in +.Dv IFF_CANTCHANGE +are masked off, and the field +.Va if_flags +in the interface structure is updated. +Finally, the driver +.Fn if_ioctl +routine is called to perform any setup +requested. +.Pp +.It Dv SIOCSIFMETRIC +.It Dv SIOCSIFPHYS +Change interface metric or medium. +Caller must have appropriate privilege. +.Pp +.It Dv SIOCSIFMTU +Change interface MTU. +Caller must have appropriate privilege. +MTU +values less than 72 or greater than 65535 are considered invalid. +The driver +.Fn if_ioctl +routine is called to implement the change; it is responsible for any +additional sanity checking and for actually modifying the MTU in the +interface structure. +.Pp +.It Dv SIOCADDMULTI +.It Dv SIOCDELMULTI +Add or delete permanent multicast group memberships on the interface. +Caller must have appropriate privilege. +The +.Fn if_addmulti +or +.Fn if_delmulti +function is called to perform the operation; qq.v. +.Pp +.It Dv SIOCAIFADDR +.It Dv SIOCDIFADDR +The socket's protocol control routine is called to implement the +requested action. +.El +.El +.Pp +.Fn if_down , +.Fn ifioctl , +.Fn ifpromisc , +and +.Fn if_up +must be called at +.Fn splnet +or higher. +.Ss "Interface Address Functions" +Several functions exist to look up an interface address structure +given an address. +.Fn ifa_ifwithaddr +returns an interface address with either a local address or a +broadcast address precisely matching the parameter +.Fa addr . +.Fn ifa_ifwithdstaddr +returns an interface address for a point-to-point interface whose +remote +.Pq Dq destination +address is +.Fa addr +and a fib is +.Fa fib . +If +.Fa fib +is +.Dv RT_ALL_FIBS , +then the first interface address matching +.Fa addr +will be returned. +.Pp +.Fn ifa_ifwithnet +returns the most specific interface address which matches the +specified address, +.Fa addr , +subject to its configured netmask, or a point-to-point interface +address whose remote address is +.Fa addr +if one is found. +If +.Fa ignore_ptp +is true, skip point-to-point interface addresses. +The +.Fa fib +parameter is handled the same way as by +.Fn ifa_ifwithdstaddr . +.Pp +.Fn ifaof_ifpforaddr +returns the most specific address configured on interface +.Fa ifp +which matches address +.Fa addr , +subject to its configured netmask. +If the interface is +point-to-point, only an interface address whose remote address is +precisely +.Fa addr +will be returned. +.Pp +.Fn ifaddr_byindex +returns the link-level address of the interface with the given index +.Fa idx . +.Pp +All of these functions return a null pointer if no such address can be +found. +.Ss "Interface Multicast Address Functions" +The +.Fn if_addmulti , +.Fn if_delmulti , +and +.Fn if_findmulti +functions provide support for requesting and relinquishing multicast +group memberships, and for querying an interface's membership list, +respectively. +The +.Fn if_addmulti +function takes a pointer to an interface, +.Fa ifp , +and a generic address, +.Fa sa . +It also takes a pointer to a +.Vt "struct ifmultiaddr *" +which is filled in on successful return with the address of the +group membership control block. +The +.Fn if_addmulti +function performs the following four-step process: +.Bl -enum -offset indent +.It +Call the interface's +.Fn if_resolvemulti +entry point to determine the link-layer address, if any, corresponding +to this membership request, and also to give the link layer an +opportunity to veto this membership request should it so desire. +.It +Check the interface's group membership list for a pre-existing +membership for this group. +If one is not found, allocate a new one; +if one is, increment its reference count. +.It +If the +.Fn if_resolvemulti +routine returned a link-layer address corresponding to the group, +repeat the previous step for that address as well. +.It +If the interface's multicast address filter needs to be changed +because a new membership was added, call the interface's +.Fn if_ioctl +routine +(with a +.Fa cmd +argument of +.Dv SIOCADDMULTI ) +to request that it do so. +.El +.Pp +The +.Fn if_delmulti +function, given an interface +.Fa ifp +and an address, +.Fa sa , +reverses this process. +Both functions return zero on success, or a +standard error number on failure. +.Pp +The +.Fn if_findmulti +function examines the membership list of interface +.Fa ifp +for an address matching +.Fa sa , +and returns a pointer to that +.Vt "struct ifmultiaddr" +if one is found, else it returns a null pointer. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr link_addr 3 , +.Xr queue 3 , +.Xr sysctl 3 , +.Xr bpf 4 , +.Xr ifmib 4 , +.Xr lo 4 , +.Xr netintro 4 , +.Xr polling 4 , +.Xr config 8 , +.Xr ppp 8 , +.Xr mbuf 9 , +.Xr rtentry 9 +.Rs +.%A Gary R. Wright +.%A W. Richard Stevens +.%B TCP/IP Illustrated +.%V Vol. 2 +.%O Addison-Wesley, ISBN 0-201-63354-X +.Re +.Sh AUTHORS +This manual page was written by +.An Garrett A. Wollman . Property changes on: user/imp/camdoc/ifnet.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap.9 =================================================================== --- user/imp/camdoc/pmap.9 (nonexistent) +++ user/imp/camdoc/pmap.9 (revision 296049) @@ -0,0 +1,130 @@ +.\" +.\" 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 3, 2014 +.Dt PMAP 9 +.Os +.Sh NAME +.Nm pmap +.Nd machine-dependent portion of virtual memory subsystem +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Sh DESCRIPTION +The +.Nm +module is the machine-dependent portion of the +.Fx +VM (Virtual Memory) sub-system. +Each function documented herein must have its own +architecture-dependent implementation. +.Pp +The +.Nm +module +is responsible for managing hardware-dependent objects such as page tables, +address maps, TLBs, etc. +.Pp +Machine-dependent code must provide the header file +.In machine/pmap.h . +This file contains the definition of the +.Vt pmap +structure: +.Bd -literal -offset indent +struct pmap { + /* Contents defined by pmap implementation. */ +}; +typedef struct pmap *pmap_t; +.Ed +.Pp +This header file may also define other data structures used by the +.Nm +implementation. +.Pp +The header file +.In vm/pmap.h +defines a structure for tracking +.Nm +statistics (see below). +This structure is defined as: +.Bd -literal -offset indent +struct pmap_statistics { + long resident_count; /* number of mapped pages */ + long wired_count; /* number of wired pages */ +}; +.Ed +.Pp +The implementation's +.Vt "struct pmap" +must contain an instance of this structure having the name +.Va pm_stats , +and it must be updated by the implementation after each relevant +.Nm +operation. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_activate 9 , +.Xr pmap_clear_modify 9 , +.Xr pmap_copy 9 , +.Xr pmap_copy_page 9 , +.Xr pmap_enter 9 , +.Xr pmap_extract 9 , +.Xr pmap_extract_and_hold 9 , +.Xr pmap_growkernel 9 , +.Xr pmap_init 9 , +.Xr pmap_init2 9 , +.Xr pmap_is_modified 9 , +.Xr pmap_is_prefaultable 9 , +.Xr pmap_map 9 , +.Xr pmap_mincore 9 , +.Xr pmap_object_init_pt 9 , +.Xr pmap_page_exists_quick 9 , +.Xr pmap_page_init 9 , +.Xr pmap_pinit 9 , +.Xr pmap_pinit0 9 , +.Xr pmap_pinit2 9 , +.Xr pmap_protect 9 , +.Xr pmap_qenter 9 , +.Xr pmap_qremove 9 , +.Xr pmap_quick_enter_page 9 , +.Xr pmap_quick_remove_page 9 , +.Xr pmap_release 9 , +.Xr pmap_remove 9 , +.Xr pmap_remove_all 9 , +.Xr pmap_remove_pages 9 , +.Xr pmap_resident_count 9 , +.Xr pmap_ts_referenced 9 , +.Xr pmap_unwire 9 , +.Xr pmap_wired_count 9 , +.Xr pmap_zero_area 9 , +.Xr pmap_zero_idle 9 , +.Xr pmap_zero_page 9 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_quick_enter_page.9 =================================================================== --- user/imp/camdoc/pmap_quick_enter_page.9 (nonexistent) +++ user/imp/camdoc/pmap_quick_enter_page.9 (revision 296049) @@ -0,0 +1,103 @@ +.\" +.\" Copyright (c) 2015 Jason A. Harmening +.\" 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 6, 2015 +.Dt PMAP_QUICK_ENTER_PAGE 9 +.Os +.Sh NAME +.Nm pmap_quick_enter_page , +.Nm pmap_quick_remove_page +.Nd manage fast, single-page kernel address space mappings +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft vm_offset_t +.Fn pmap_quick_enter_page "vm_page_t m" +.Ft void +.Fn pmap_quick_remove_page "vm_offset_t kva" +.Sh DESCRIPTION +The +.Fn pmap_quick_enter_page +function accepts a single page +.Fa m , +and enters this page into a preallocated address in kernel virtual +address (KVA) space. +This function is intended for temporary mappings that will only +be used for a very short period, for example a copy operation on +the page contents. +.Pp +The +.Fn pmap_quick_remove_page +function removes a mapping previously created by +.Fn pmap_quick_enter_page +at +.Fa kva , +making the KVA frame used by +.Fn pmap_quick_enter_page +available for reuse. +.Pp +On many architectures, +.Fn pmap_quick_enter_page +uses a per-CPU pageframe. +In those cases, it must disable preemption on the local CPU. +The corresponding call to +.Fn pmap_quick_remove_page +then re-enables preemption. +It is therefore not safe for machine-independent code to sleep +or perform locking operations while holding these mappings. +Current implementations only guarantee the availability of a single +page for the calling thread, so calls to +.Fn pmap_quick_enter_page +must not be nested. +.Pp +.Fn pmap_quick_enter_page +and +.Fn pmap_quick_remove_page +do not sleep, and +.Fn pmap_quick_enter_page +always returns a valid address. +It is safe to use these functions under all types of locks except spin mutexes. +It is also safe to use them in all thread contexts except primary interrupt +context. +.Pp +The page +.Em must +not be swapped or otherwise reused while the mapping is active. +It must be either wired or held, or it must belong to an unmanaged +region such as I/O device memory. +.Sh RETURN VALUES +The +.Fn pmap_quick_enter_page +function returns the kernel virtual address +that is mapped to the page +.Fa m . +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Jason A Harmening Aq Mt jah@FreeBSD.org . Property changes on: user/imp/camdoc/pmap_quick_enter_page.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/vgone.9 =================================================================== --- user/imp/camdoc/vgone.9 (nonexistent) +++ user/imp/camdoc/vgone.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" +.\" Copyright (C) 2001 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 12, 2010 +.Dt VGONE 9 +.Os +.Sh NAME +.Nm vgone +.Nd "prepare a vnode for reuse" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vgone "struct vnode *vp" +.Sh DESCRIPTION +The +.Fn vgone +function prepares the vnode to be destroyed. +The preparation includes the cleaning of all file system specific data and +the removal from its mount point vnode list. +.Pp +If the vnode has a +.Va v_usecount +of zero, and its +.Dv VI_DOOMED +flag is not set, it is moved to the head of the free list +as in most cases the vnode +is about to be reused, or its file system is being unmounted. +.Pp +The +.Fn vgone +function takes an exclusively locked vnode, and returns with the vnode +exclusively locked. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vgone.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/CTASSERT.9 =================================================================== --- user/imp/camdoc/CTASSERT.9 (nonexistent) +++ user/imp/camdoc/CTASSERT.9 (revision 296049) @@ -0,0 +1,70 @@ +.\" Copyright (c) 2003 Hiten M. Pandya +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 1, 2015 +.Dt CTASSERT 9 +.Os +.Sh NAME +.Nm CTASSERT +.Nd compile time assertion macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Fn CTASSERT expression +.Sh DESCRIPTION +The +.Fn CTASSERT +macro is deprecated and the C11 standard +.Fn _Static_assert +should be used instead. +The header +.Fa sys/cdefs.h +should be included to provide compatibility for pre-C11 compilers. +.Pp +The +.Fn CTASSERT +macro evaluates +.Fa expression +at compile time and causes a compiler error if it is false. +.Pp +The +.Fn CTASSERT +macro is useful for asserting the size or alignment of important +data structures and variables during compilation, which would +otherwise cause the code to fail at run time. +.Sh EXAMPLES +Assert that the size of the +.Vt uuid +structure is 16 bytes. +.Pp +.Dl "CTASSERT(sizeof(struct uuid) == 16);" +.Sh SEE ALSO +.Xr KASSERT 9 +.Sh AUTHORS +This manual page was written by +.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . Property changes on: user/imp/camdoc/CTASSERT.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mac.9 =================================================================== --- user/imp/camdoc/mac.9 (nonexistent) +++ user/imp/camdoc/mac.9 (revision 296049) @@ -0,0 +1,231 @@ +.\"- +.\" Copyright (c) 1999-2002 Robert N. M. Watson +.\" Copyright (c) 2002-2004 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed by Robert Watson for the TrustedBSD Project. +.\" +.\" This software was developed for the FreeBSD Project in part by Network +.\" Associates Laboratories, the Security Research Division of Network +.\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 +.\" ("CBOSS"), as part of the DARPA CHATS research program. +.\" +.\" 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 25, 2015 +.Dt MAC 9 +.Os +.Sh NAME +.Nm mac +.Nd TrustedBSD Mandatory Access Control framework +.Sh SYNOPSIS +.In sys/types.h +.In sys/mac.h +.Pp +In the kernel configuration file: +.Cd "options MAC" +.Cd "options MAC_DEBUG" +.Sh DESCRIPTION +.Ss Introduction +The +.Tn TrustedBSD +mandatory access control framework permits dynamically +introduced system security modules to modify system security functionality. +This can be used to support a variety of new security services, including +traditional labeled mandatory access control models. +The framework provides a series of entry points which must be called by +code supporting various kernel services, especially with respects to access +control points and object creation. +The framework then calls out to security modules to offer them the +opportunity to modify security behavior at those MAC API entry points. +Both consumers of the API (normal kernel services) and security modules +must be aware of the semantics of the API calls, particularly with respect +to synchronization primitives (such as locking). +.Ss Kernel Objects Supported by the Framework +The MAC framework manages labels on a variety of types of in-kernel +objects, including process credentials, vnodes, devfs_dirents, mount +points, sockets, mbufs, bpf descriptors, network interfaces, IP fragment +queues, and pipes. +Label data on kernel objects, represented by +.Vt "struct label" , +is policy-unaware, and may be used in the manner seen fit by policy modules. +.Ss API for Consumers +The MAC API provides a large set of entry points, too broad to specifically +document here. +In general, these entry points represent an access control check or other +MAC-relevant operations, accept one or more subjects (credentials) +authorizing the activity, a set of objects on which the operation +is to be performed, and a set of operation arguments providing information +about the type of operation being requested. +.Ss Locking for Consumers +Consumers of the MAC API must be aware of the locking requirements for +each API entry point: generally, appropriate locks must be held over each +subject or object being passed into the call, so that MAC modules may +make use of various aspects of the object for access control purposes. +For example, vnode locks are frequently required in order that the MAC +framework and modules may retrieve security labels and attributes from the +vnodes for the purposes of access control. +Similarly, the caller must be aware of the reference counting semantics +of any subject or object passed into the MAC API: all calls require that +a valid reference to the object be held for the duration of the +(potentially lengthy) MAC API call. +Under some circumstances, objects must be held in either a shared or +exclusive manner. +.Ss API for Module Writers +Each module exports a structure describing the MAC API operations that +the module chooses to implement, including initialization and destruction +API entry points, a variety of object creation and destruction calls, +and a large set of access control check points. +In the future, additional audit entry points will also be present. +Module authors may choose to only implement a subset of the entry points, +setting API function pointers in the description structure to +.Dv NULL , +permitting the framework to avoid calling into the module. +.Ss Locking for Module Writers +Module writers must be aware of the locking semantics of entry points +that they implement: MAC API entry points will have specific locking +or reference counting semantics for each argument, and modules must follow +the locking and reference counting protocol or risk a variety of failure +modes (including race conditions, inappropriate pointer dereferences, +etc). +.Pp +MAC module writers must also be aware that MAC API entry points will +frequently be invoked from deep in a kernel stack, and as such must be +careful to avoid violating more global locking requirements, such as +global lock order requirements. +For example, it may be inappropriate to lock additional objects not +specifically maintained and ordered by the policy module, or the +policy module might violate a global ordering requirement relating +to those additional objects. +.Pp +Finally, MAC API module implementors must be careful to avoid +inappropriately calling back into the MAC framework: the framework +makes use of locking to prevent inconsistencies during policy module +attachment and detachment. +MAC API modules should avoid producing scenarios in which deadlocks +or inconsistencies might occur. +.Ss Adding New MAC Entry Points +The MAC API is intended to be easily expandable as new services are +added to the kernel. +In order that policies may be guaranteed the opportunity to ubiquitously +protect system subjects and objects, it is important that kernel +developers maintain awareness of when security checks or relevant +subject or object operations occur in newly written or modified kernel +code. +New entry points must be carefully documented so as to prevent any +confusion regarding lock orders and semantics. +Introducing new entry points requires four distinct pieces of work: +introducing new MAC API entries reflecting the operation arguments, +scattering these MAC API entry points throughout the new or modified +kernel service, extending the front-end implementation of the MAC API +framework, and modifying appropriate modules to take advantage of +the new entry points so that they may consistently enforce their +policies. +.Sh ENTRY POINTS +System service and module authors should reference the +.%T "FreeBSD Architecture Handbook" +for information on the MAC Framework APIs. +.Sh SEE ALSO +.Xr acl 3 , +.Xr mac 3 , +.Xr posix1e 3 , +.Xr mac_biba 4 , +.Xr mac_bsdextended 4 , +.Xr mac_ifoff 4 , +.Xr mac_lomac 4 , +.Xr mac_mls 4 , +.Xr mac_none 4 , +.Xr mac_partition 4 , +.Xr mac_seeotheruids 4 , +.Xr mac_test 4 , +.Xr ucred 9 , +.Xr vaccess 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr VFS 9 +.Rs +.%T "The FreeBSD Architecture Handbook" +.%U "http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/arch-handbook/" +.Re +.Sh HISTORY +The +.Tn TrustedBSD +MAC Framework first appeared in +.Fx 5.0 . +.Sh AUTHORS +This manual page was written by +.An Robert Watson . +This software was contributed to the +.Fx +Project by Network Associates Laboratories, the Security Research +Division of Network Associates Inc.\& under DARPA/SPAWAR contract +N66001-01-C-8035 +.Pq Dq CBOSS , +as part of the DARPA CHATS research program. +.Pp +.An -nosplit +The +.Tn TrustedBSD +MAC Framework was designed by +.An Robert Watson , +and implemented by the Network Associates Laboratories Network Security +(NETSEC), Secure Execution Environment (SEE), and Adaptive +Network Defense research groups. +Network Associates Laboratory staff contributing to the CBOSS Project +include (in alphabetical order): +.An Lee Badger , +.An Brian Feldman , +.An Hrishikesh Dandekar , +.An Tim Fraser , +.An Doug Kilpatrick , +.An Suresh Krishnaswamy , +.An Adam Migus , +.An Wayne Morrison , +.An Andrew Reisse , +.An Chris Vance , +and +.An Robert Watson . +.Pp +Sub-contracted staff include: +.An Chris Costello , +.An Poul-Henning Kamp , +.An Jonathan Lemon , +.An Kirk McKusick , +.An Dag-Erling Sm\(/orgrav . +.Pp +Additional contributors include: +.An Pawel Dawidek , +.An Chris Faulhaber , +.An Ilmar Habibulin , +.An Mike Halderman , +.An Bosko Milekic , +.An Thomas Moestl , +.An Andrew Reiter , +and +.An Tim Robbins . +.Sh BUGS +While the MAC Framework design is intended to support the containment of +the root user, not all attack channels are currently protected by entry +point checks. +As such, MAC Framework policies should not be relied on, in isolation, +to protect against a malicious privileged user. Property changes on: user/imp/camdoc/mac.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/random.9 =================================================================== --- user/imp/camdoc/random.9 (nonexistent) +++ user/imp/camdoc/random.9 (revision 296049) @@ -0,0 +1,212 @@ +.\" +.\" Copyright (c) 2015 +.\" Mark R V Murray +.\" Copyright (c) 2000 +.\" The Regents of the University of California. 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 July 16, 2015 +.Dt RANDOM 9 +.Os +.Sh NAME +.Nm arc4rand , +.Nm arc4random , +.Nm random , +.Nm read_random , +.Nm read_random_uio , +.Nm srandom +.Nd supply pseudo-random numbers +.Sh SYNOPSIS +.In sys/libkern.h +.Ft void +.Fn srandom "u_long seed" +.Ft u_long +.Fn random "void" +.Ft void +.Fn arc4rand "void *ptr" "u_int length" "int reseed" +.Ft uint32_t +.Fn arc4random "void" +.Pp +.In sys/random.h +.Ft int +.Fn read_random "void *buffer" "int count" +.Ft int +.Fn read_random_uio "struct uio *uio" "bool nonblock" +.Sh DESCRIPTION +The +.Fn random +function will by default produce +a sequence of numbers +that can be duplicated +by calling +.Fn srandom +with some constant +as the +.Fa seed . +The +.Fn srandom +function may be called with any arbitrary +.Fa seed +value to get slightly more unpredictable numbers. +It is important to remember that the +.Fn random +function is entirely predictable, +and is therefore not of use where +knowledge of the sequence of numbers +may be of benefit to an attacker. +.Pp +The +.Fn arc4rand +function will return very good quality random numbers, +better suited +for security-related purposes. +The random numbers from +.Fn arc4rand +are seeded from the entropy device +if it is available. +Automatic reseeds happen +after a certain timeinterval +and after a certain number of bytes +have been delivered. +A forced reseed +can be forced +by passing a non-zero +value in the +.Fa reseed +argument. +.Pp +The +.Fn read_random +function is used to return entropy directly from the entropy device +if it has been loaded. +If the entropy device is not loaded, then +the +.Fa buffer +is ignored +and zero is returned. +The +.Fa buffer +is filled with no more than +.Fa count +bytes. +It is strongly advised that +.Fn read_random +is not used; +instead use +.Fn arc4rand +unless it is +necessary to know +that no entropy +has been returned. +.Pp +The +.Fn read_random_uio +function behaves identically to +.Xr read 2 +on +.Pa /dev/random . +The +.Fa uio +argument points to a buffer where random data should be stored. +This function only returns data if the random device is seeded. +It blocks if unseeded, +except when the +.Fa nonblock +argument is true. +.Pp +All the bits returned by +.Fn random , +.Fn arc4rand , +.Fn read_random , +and +.Fn read_random_uio +are usable. +For example, +.Sq Li random()&01 +will produce a random binary value. +.Pp +The +.Fn arc4random +is a convenience function which calls +.Fn arc4rand +to return a 32 bit pseudo-random integer. +.Sh RETURN VALUES +The +.Fn random +function uses +a non-linear additive feedback random number generator +employing a default table +of size 31 +containing long integers +to return successive pseudo-random +numbers in the range from 0 to +.if t 2\u\s731\s10\d\(mi1. +.if n (2**31)\(mi1. +The period of this random number generator +is very large, +approximately +.if t 16\(mu(2\u\s731\s10\d\(mi1). +.if n 16*((2**31)\(mi1). +.Pp +The +.Fn arc4rand +function uses the RC4 algorithm +to generate successive pseudo-random bytes. +The +.Fn arc4random +function uses +.Fn arc4rand +to generate pseudo-random numbers +in the range from 0 to +.if t 2\u\s732\s10\d\(mi1. +.if n (2**32)\(mi1. +.Pp +The +.Fn read_random +function returns +the number of bytes placed in +.Fa buffer . +.Pp +.Fn read_random_uio +returns zero when successful, +otherwise an error code is returned. +.Sh ERRORS +.Fn read_random_uio +may fail if: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa uio +points to an invalid memory region. +.It Bq Er EWOULDBLOCK +The random device is unseeded and +.Fa nonblock +is true. +.El +.Sh AUTHORS +.An Dan Moschuk +wrote +.Fn arc4random . +.An Mark R V Murray +wrote +.Fn read_random . Property changes on: user/imp/camdoc/random.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/random_harvest.9 =================================================================== --- user/imp/camdoc/random_harvest.9 (nonexistent) +++ user/imp/camdoc/random_harvest.9 (revision 296049) @@ -0,0 +1,147 @@ +.\" +.\" Copyright (c) 2002-2015 Mark R V Murray +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 13, 2015 +.Dt RANDOM_HARVEST 9 +.Os +.Sh NAME +.Nm random_harvest +.Nd gather entropy from the kernel for the entropy device +.Sh SYNOPSIS +.In sys/types.h +.In sys/random.h +.Ft void +.Fo random_harvest_direct +.Fa "void *entropy" +.Fa "u_int size" +.Fa "u_int bits" +.Fa "enum esource source" +.Fc +.Ft void +.Fo random_harvest_fast +.Fa "void *entropy" +.Fa "u_int size" +.Fa "u_int bits" +.Fa "enum esource source" +.Fc +.Ft void +.Fo random_harvest_queue +.Fa "void *entropy" +.Fa "u_int size" +.Fa "u_int bits" +.Fa "enum esource source" +.Fc +.Sh DESCRIPTION +The +.Fn random_harvest_* +functions are used by device drivers +and other kernel processes to pass data +that is considered (at least partially) stochastic +to the entropy device. +.Pp +The caller should pass +a pointer pointing to the +.Dq random +data in +.Fa entropy . +The argument +.Fa size +contains the number of bytes pointed to. +The +.Fa source +is chosen from one of +the values enumerated in +.Pa sys/dev/random.h . +and is used to indicate the source of the entropy. +.Pp +The +.Fo random_harvest_direct +.Fc +variant is used +for early harvesting +before any multitasking +is enabled. +.Pp +The +.Fn random_harvest_fast +variant is used +by sources that +should not take +a performance hit +from harvesting, +as they are high-rate +sources. +Some entropy is sacrificed, +but the high rate of supply +will compensate for this. +.Pp +The +.Fn random_harvest_queue +variant is used +for general harvesting +and is the default +choice for most entropy sources +such as interrupts +or console events. +.Pp +The +.Fa bits +argument is only used +by the deprecated Yarrow algorithm. +For compatibility, +the caller should +.Em "very conservatively" +estimate the number of random bits +in the sample, +and pass this in +.Fa bits . +.Pp +Interrupt harvesting has been +in part simplified +for the kernel programmer. +If a device driver registers an interrupt handler +with +.Xr BUS_SETUP_INTR 9 +or +.Xr bus_setup_intr 9 , +then it is only necessary to +include the +.Dv INTR_ENTROPY +bit in the +.Fa flags +argument to have that interrupt source +be used for entropy harvesting. +This should be done wherever practicable. +.Sh SEE ALSO +.Xr random 4 , +.Xr BUS_SETUP_INTR 9 +.Sh AUTHORS +The +.Fx +.Xr random 4 +entropy device and supporting documentation was written by +.An Mark R V Murray . Property changes on: user/imp/camdoc/random_harvest.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/crypto.9 =================================================================== --- user/imp/camdoc/crypto.9 (nonexistent) +++ user/imp/camdoc/crypto.9 (revision 296049) @@ -0,0 +1,710 @@ +.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ +.\" +.\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu) +.\" +.\" Copyright (c) 2000, 2001 Angelos D. Keromytis +.\" +.\" Permission to use, copy, and modify this software with or without fee +.\" is hereby granted, provided that this entire notice is included in +.\" all source code copies of any software which is or includes a copy or +.\" modification of this software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 10, 2015 +.Dt CRYPTO 9 +.Os +.Sh NAME +.Nm crypto +.Nd API for cryptographic services in the kernel +.Sh SYNOPSIS +.In opencrypto/cryptodev.h +.Ft int32_t +.Fn crypto_get_driverid device_t int +.Ft int +.Fn crypto_register uint32_t int uint16_t uint32_t "int \*[lp]*\*[rp]\*[lp]void *, uint32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, uint64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *" +.Ft int +.Fn crypto_kregister uint32_t int uint32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *" +.Ft int +.Fn crypto_unregister uint32_t int +.Ft int +.Fn crypto_unregister_all uint32_t +.Ft void +.Fn crypto_done "struct cryptop *" +.Ft void +.Fn crypto_kdone "struct cryptkop *" +.Ft int +.Fn crypto_find_driver "const char *" +.Ft int +.Fn crypto_newsession "uint64_t *" "struct cryptoini *" int +.Ft int +.Fn crypto_freesession uint64_t +.Ft int +.Fn crypto_dispatch "struct cryptop *" +.Ft int +.Fn crypto_kdispatch "struct cryptkop *" +.Ft int +.Fn crypto_unblock uint32_t int +.Ft "struct cryptop *" +.Fn crypto_getreq int +.Ft void +.Fn crypto_freereq void +.Bd -literal +#define CRYPTO_SYMQ 0x1 +#define CRYPTO_ASYMQ 0x2 + +#define EALG_MAX_BLOCK_LEN 16 + +struct cryptoini { + int cri_alg; + int cri_klen; + int cri_mlen; + caddr_t cri_key; + uint8_t cri_iv[EALG_MAX_BLOCK_LEN]; + struct cryptoini *cri_next; +}; + +struct cryptodesc { + int crd_skip; + int crd_len; + int crd_inject; + int crd_flags; + struct cryptoini CRD_INI; +#define crd_iv CRD_INI.cri_iv +#define crd_key CRD_INI.cri_key +#define crd_alg CRD_INI.cri_alg +#define crd_klen CRD_INI.cri_klen + struct cryptodesc *crd_next; +}; + +struct cryptop { + TAILQ_ENTRY(cryptop) crp_next; + uint64_t crp_sid; + int crp_ilen; + int crp_olen; + int crp_etype; + int crp_flags; + caddr_t crp_buf; + caddr_t crp_opaque; + struct cryptodesc *crp_desc; + int (*crp_callback) (struct cryptop *); + caddr_t crp_mac; +}; + +struct crparam { + caddr_t crp_p; + u_int crp_nbits; +}; + +#define CRK_MAXPARAM 8 + +struct cryptkop { + TAILQ_ENTRY(cryptkop) krp_next; + u_int krp_op; /* ie. CRK_MOD_EXP or other */ + u_int krp_status; /* return status */ + u_short krp_iparams; /* # of input parameters */ + u_short krp_oparams; /* # of output parameters */ + uint32_t krp_hid; + struct crparam krp_param[CRK_MAXPARAM]; + int (*krp_callback)(struct cryptkop *); +}; +.Ed +.Sh DESCRIPTION +.Nm +is a framework for drivers of cryptographic hardware to register with +the kernel so +.Dq consumers +(other kernel subsystems, and +users through the +.Pa /dev/crypto +device) are able to make use of it. +Drivers register with the framework the algorithms they support, +and provide entry points (functions) the framework may call to +establish, use, and tear down sessions. +Sessions are used to cache cryptographic information in a particular driver +(or associated hardware), so initialization is not needed with every request. +Consumers of cryptographic services pass a set of +descriptors that instruct the framework (and the drivers registered +with it) of the operations that should be applied on the data (more +than one cryptographic operation can be requested). +.Pp +Keying operations are supported as well. +Unlike the symmetric operators described above, +these sessionless commands perform mathematical operations using +input and output parameters. +.Pp +Since the consumers may not be associated with a process, drivers may +not +.Xr sleep 9 . +The same holds for the framework. +Thus, a callback mechanism is used +to notify a consumer that a request has been completed (the +callback is specified by the consumer on a per-request basis). +The callback is invoked by the framework whether the request was +successfully completed or not. +An error indication is provided in the latter case. +A specific error code, +.Er EAGAIN , +is used to indicate that a session number has changed and that the +request may be re-submitted immediately with the new session number. +Errors are only returned to the invoking function if not +enough information to call the callback is available (meaning, there +was a fatal error in verifying the arguments). +For session initialization and teardown there is no callback mechanism used. +.Pp +The +.Fn crypto_find_driver +function may be called to return the specific id of the provided name. +If the specified driver could not be found, the returned id is -1. +.Pp +The +.Fn crypto_newsession +routine is called by consumers of cryptographic services (such as the +.Xr ipsec 4 +stack) that wish to establish a new session with the framework. +The second argument contains all the necessary information for +the driver to establish the session. +The third argument is either a specific driver id, or one or both +of +.Dv CRYPTOCAP_F_HARDWARE , +to select hardware devices, +or +.Dv CRYPTOCAP_F_SOFTWARE , +to select software devices. +If both are specified, a hardware device will be returned +before a software device will be. +On success, the value pointed to by the first argument will be the +Session IDentifier (SID). +The various fields in the +.Vt cryptoini +structure are: +.Bl -tag -width ".Va cri_next" +.It Va cri_alg +Contains an algorithm identifier. +Currently supported algorithms are: +.Pp +.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact +.It Dv CRYPTO_AES_128_NIST_GMAC +.It Dv CRYPTO_AES_192_NIST_GMAC +.It Dv CRYPTO_AES_256_NIST_GMAC +.It Dv CRYPTO_AES_CBC +.It Dv CRYPTO_AES_ICM +.It Dv CRYPTO_AES_NIST_GCM_16 +.It Dv CRYPTO_AES_NIST_GMAC +.It Dv CRYPTO_AES_XTS +.It Dv CRYPTO_ARC4 +.It Dv CRYPTO_BLF_CBC +.It Dv CRYPTO_CAMELLIA_CBC +.It Dv CRYPTO_CAST_CBC +.It Dv CRYPTO_DEFLATE_COMP +.It Dv CRYPTO_DES_CBC +.It Dv CRYPTO_3DES_CBC +.It Dv CRYPTO_MD5 +.It Dv CRYPTO_MD5_HMAC +.It Dv CRYPTO_MD5_KPDK +.It Dv CRYPTO_NULL_HMAC +.It Dv CRYPTO_NULL_CBC +.It Dv CRYPTO_RIPEMD160_HMAC +.It Dv CRYPTO_SHA1 +.It Dv CRYPTO_SHA1_HMAC +.It Dv CRYPTO_SHA1_KPDK +.It Dv CRYPTO_SHA2_256_HMAC +.It Dv CRYPTO_SHA2_384_HMAC +.It Dv CRYPTO_SHA2_512_HMAC +.It Dv CRYPTO_SKIPJACK_CBC +.El +.It Va cri_klen +Specifies the length of the key in bits, for variable-size key +algorithms. +.It Va cri_mlen +Specifies how many bytes from the calculated hash should be copied back. +0 means entire hash. +.It Va cri_key +Contains the key to be used with the algorithm. +.It Va cri_iv +Contains an explicit initialization vector (IV), if it does not prefix +the data. +This field is ignored during initialization +.Pq Nm crypto_newsession . +If no IV is explicitly passed (see below on details), a random IV is used +by the device driver processing the request. +.It Va cri_next +Contains a pointer to another +.Vt cryptoini +structure. +Multiple such structures may be linked to establish multi-algorithm sessions +.Xr ( ipsec 4 +is an example consumer of such a feature). +.El +.Pp +The +.Vt cryptoini +structure and its contents will not be modified by the framework (or +the drivers used). +Subsequent requests for processing that use the +SID returned will avoid the cost of re-initializing the hardware (in +essence, SID acts as an index in the session cache of the driver). +.Pp +.Fn crypto_freesession +is called with the SID returned by +.Fn crypto_newsession +to disestablish the session. +.Pp +.Fn crypto_dispatch +is called to process a request. +The various fields in the +.Vt cryptop +structure are: +.Bl -tag -width ".Va crp_callback" +.It Va crp_sid +Contains the SID. +.It Va crp_ilen +Indicates the total length in bytes of the buffer to be processed. +.It Va crp_olen +On return, contains the total length of the result. +For symmetric crypto operations, this will be the same as the input length. +This will be used if the framework needs to allocate a new +buffer for the result (or for re-formatting the input). +.It Va crp_callback +This routine is invoked upon completion of the request, whether +successful or not. +It is invoked through the +.Fn crypto_done +routine. +If the request was not successful, an error code is set in the +.Va crp_etype +field. +It is the responsibility of the callback routine to set the appropriate +.Xr spl 9 +level. +.It Va crp_etype +Contains the error type, if any errors were encountered, or zero if +the request was successfully processed. +If the +.Er EAGAIN +error code is returned, the SID has changed (and has been recorded in the +.Va crp_sid +field). +The consumer should record the new SID and use it in all subsequent requests. +In this case, the request may be re-submitted immediately. +This mechanism is used by the framework to perform +session migration (move a session from one driver to another, because +of availability, performance, or other considerations). +.Pp +Note that this field only makes sense when examined by +the callback routine specified in +.Va crp_callback . +Errors are returned to the invoker of +.Fn crypto_process +only when enough information is not present to call the callback +routine (i.e., if the pointer passed is +.Dv NULL +or if no callback routine was specified). +.It Va crp_flags +Is a bitmask of flags associated with this request. +Currently defined flags are: +.Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC" +.It Dv CRYPTO_F_IMBUF +The buffer pointed to by +.Va crp_buf +is an mbuf chain. +.It Dv CRYPTO_F_IOV +The buffer pointed to by +.Va crp_buf +is an +.Vt uio +structure. +.It Dv CRYPTO_F_BATCH +Batch operation if possible. +.It Dv CRYPTO_F_CBIMM +Do callback immediately instead of doing it from a dedicated kernel thread. +.It Dv CRYPTO_F_DONE +Operation completed. +.It Dv CRYPTO_F_CBIFSYNC +Do callback immediately if operation is synchronous (that the driver +specified the +.Dv CRYPTOCAP_F_SYNC +flag). +.El +.It Va crp_buf +Points to the input buffer. +On return (when the callback is invoked), +it contains the result of the request. +The input buffer may be an mbuf +chain or a contiguous buffer, +depending on +.Va crp_flags . +.It Va crp_opaque +This is passed through the crypto framework untouched and is +intended for the invoking application's use. +.It Va crp_desc +This is a linked list of descriptors. +Each descriptor provides +information about what type of cryptographic operation should be done +on the input buffer. +The various fields are: +.Bl -tag -width ".Va crd_inject" +.It Va crd_iv +When the flag +.Dv CRD_F_IV_EXPLICIT +is set, this field contains the IV. +.It Va crd_key +When the +.Dv CRD_F_KEY_EXPLICIT +flag is set, the +.Va crd_key +points to a buffer with encryption or authentication key. +.It Va crd_alg +An algorithm to use. +Must be the same as the one given at newsession time. +.It Va crd_klen +The +.Va crd_key +key length. +.It Va crd_skip +The offset in the input buffer where processing should start. +.It Va crd_len +How many bytes, after +.Va crd_skip , +should be processed. +.It Va crd_inject +The +.Va crd_inject +field specifies an offset in bytes from the beginning of the buffer. +For encryption algorithms, this may be where the IV will be inserted +when encrypting or where the IV may be found for +decryption (subject to +.Va crd_flags ) . +For MAC algorithms, this is where the result of the keyed hash will be +inserted. +.It Va crd_flags +The following flags are defined: +.Bl -tag -width 3n +.It Dv CRD_F_ENCRYPT +For encryption algorithms, this bit is set when encryption is required +(when not set, decryption is performed). +.It Dv CRD_F_IV_PRESENT +.\" This flag name has nothing to do w/ it's behavior, fix the name. +For encryption, if this bit is not set the IV used to encrypt the packet +will be written at the location pointed to by +.Va crd_inject . +The IV length is assumed to be equal to the blocksize of the +encryption algorithm. +For encryption, if this bit is set, nothing is done. +For decryption, this flag has no meaning. +Applications that do special +.Dq "IV cooking" , +such as the half-IV mode in +.Xr ipsec 4 , +can use this flag to indicate that the IV should not be written on the packet. +This flag is typically used in conjunction with the +.Dv CRD_F_IV_EXPLICIT +flag. +.It Dv CRD_F_IV_EXPLICIT +This bit is set when the IV is explicitly +provided by the consumer in the +.Va crd_iv +field. +Otherwise, for encryption operations the IV is provided for by +the driver used to perform the operation, whereas for decryption +operations the offset of the IV is provided by the +.Va crd_inject +field. +This flag is typically used when the IV is calculated +.Dq "on the fly" +by the consumer, and does not precede the data (some +.Xr ipsec 4 +configurations, and the encrypted swap are two such examples). +.It Dv CRD_F_KEY_EXPLICIT +For encryption and authentication (MAC) algorithms, this bit is set when the key +is explicitly provided by the consumer in the +.Va crd_key +field for the given operation. +Otherwise, the key is taken at newsession time from the +.Va cri_key +field. +As calculating the key schedule may take a while, it is recommended that often +used keys are given their own session. +.It Dv CRD_F_COMP +For compression algorithms, this bit is set when compression is required (when +not set, decompression is performed). +.El +.It Va CRD_INI +This +.Vt cryptoini +structure will not be modified by the framework or the device drivers. +Since this information accompanies every cryptographic +operation request, drivers may re-initialize state on-demand +(typically an expensive operation). +Furthermore, the cryptographic +framework may re-route requests as a result of full queues or hardware +failure, as described above. +.It Va crd_next +Point to the next descriptor. +Linked operations are useful in protocols such as +.Xr ipsec 4 , +where multiple cryptographic transforms may be applied on the same +block of data. +.El +.El +.Pp +.Fn crypto_getreq +allocates a +.Vt cryptop +structure with a linked list of as many +.Vt cryptodesc +structures as were specified in the argument passed to it. +.Pp +.Fn crypto_freereq +deallocates a structure +.Vt cryptop +and any +.Vt cryptodesc +structures linked to it. +Note that it is the responsibility of the +callback routine to do the necessary cleanups associated with the +opaque field in the +.Vt cryptop +structure. +.Pp +.Fn crypto_kdispatch +is called to perform a keying operation. +The various fields in the +.Vt cryptkop +structure are: +.Bl -tag -width ".Va krp_callback" +.It Va krp_op +Operation code, such as +.Dv CRK_MOD_EXP . +.It Va krp_status +Return code. +This +.Va errno Ns -style +variable indicates whether lower level reasons +for operation failure. +.It Va krp_iparams +Number if input parameters to the specified operation. +Note that each operation has a (typically hardwired) number of such parameters. +.It Va krp_oparams +Number if output parameters from the specified operation. +Note that each operation has a (typically hardwired) number of such parameters. +.It Va krp_kvp +An array of kernel memory blocks containing the parameters. +.It Va krp_hid +Identifier specifying which low-level driver is being used. +.It Va krp_callback +Callback called on completion of a keying operation. +.El +.Sh DRIVER-SIDE API +The +.Fn crypto_get_driverid , +.Fn crypto_register , +.Fn crypto_kregister , +.Fn crypto_unregister , +.Fn crypto_unblock , +and +.Fn crypto_done +routines are used by drivers that provide support for cryptographic +primitives to register and unregister with the kernel crypto services +framework. +.Pp +Drivers must first use the +.Fn crypto_get_driverid +function to acquire a driver identifier, specifying the +.Fa flags +as an argument. +One of +.Dv CRYPTOCAP_F_SOFTWARE +or +.Dv CRYPTOCAP_F_HARDWARE +must be specified. +The +.Dv CRYPTOCAP_F_SYNC +may also be specified, and should be specified if the driver does all of +it's operations synchronously. +.Pp +For each algorithm the driver supports, it must then call +.Fn crypto_register . +The first two arguments are the driver and algorithm identifiers. +The next two arguments specify the largest possible operator length (in bits, +important for public key operations) and flags for this algorithm. +The last four arguments must be provided in the first call to +.Fn crypto_register +and are ignored in all subsequent calls. +They are pointers to three +driver-provided functions that the framework may call to establish new +cryptographic context with the driver, free already established +context, and ask for a request to be processed (encrypt, decrypt, +etc.); and an opaque parameter to pass when calling each of these routines. +.Pp +.Fn crypto_unregister +is called by drivers that wish to withdraw support for an algorithm. +The two arguments are the driver and algorithm identifiers, respectively. +Typically, drivers for +PCMCIA +crypto cards that are being ejected will invoke this routine for all +algorithms supported by the card. +.Fn crypto_unregister_all +will unregister all algorithms registered by a driver +and the driver will be disabled (no new sessions will be allocated on +that driver, and any existing sessions will be migrated to other +drivers). +The same will be done if all algorithms associated with a driver are +unregistered one by one. +After a call to +.Fn crypto_unregister_all +there will be no threads in either the newsession or freesession function +of the driver. +.Pp +The calling convention for the three driver-supplied routines are: +.Pp +.Bl -item -compact +.It +.Ft int +.Fn \*[lp]*newsession\*[rp] "device_t" "uint32_t *" "struct cryptoini *" ; +.It +.Ft int +.Fn \*[lp]*freesession\*[rp] "device_t" "uint64_t" ; +.It +.Ft int +.Fn \*[lp]*process\*[rp] "device_t" "struct cryptop *" "int" ; +.It +.Ft int +.Fn \*[lp]*kprocess\*[rp] "device_t" "struct cryptkop *" "int" ; +.El +.Pp +On invocation, the first argument to +all routines is the +.Fa device_t +that was provided to +.Fn crypto_get_driverid . +The second argument to +.Fn newsession +contains the driver identifier obtained via +.Fn crypto_get_driverid . +On successful return, it should contain a driver-specific session +identifier. +The third argument is identical to that of +.Fn crypto_newsession . +.Pp +The +.Fn freesession +routine takes as arguments the opaque data value and the SID +(which is the concatenation of the +driver identifier and the driver-specific session identifier). +It should clear any context associated with the session (clear hardware +registers, memory, etc.). +.Pp +The +.Fn process +routine is invoked with a request to perform crypto processing. +This routine must not block or sleep, but should queue the request and return +immediately or process the request to completion. +In case of an unrecoverable error, the error indication must be placed in the +.Va crp_etype +field of the +.Vt cryptop +structure. +When the request is completed, or an error is detected, the +.Fn process +routine must invoke +.Fn crypto_done . +Session migration may be performed, as mentioned previously. +.Pp +In case of a temporary resource exhaustion, the +.Fn process +routine may return +.Er ERESTART +in which case the crypto services will requeue the request, mark the driver +as +.Dq blocked , +and stop submitting requests for processing. +The driver is then responsible for notifying the crypto services +when it is again able to process requests through the +.Fn crypto_unblock +routine. +This simple flow control mechanism should only be used for short-lived +resource exhaustion as it causes operations to be queued in the crypto +layer. +Doing so is preferable to returning an error in such cases as +it can cause network protocols to degrade performance by treating the +failure much like a lost packet. +.Pp +The +.Fn kprocess +routine is invoked with a request to perform crypto key processing. +This routine must not block, but should queue the request and return +immediately. +Upon processing the request, the callback routine should be invoked. +In case of an unrecoverable error, the error indication must be placed in the +.Va krp_status +field of the +.Vt cryptkop +structure. +When the request is completed, or an error is detected, the +.Fn kprocess +routine should invoked +.Fn crypto_kdone . +.Sh RETURN VALUES +.Fn crypto_register , +.Fn crypto_kregister , +.Fn crypto_unregister , +.Fn crypto_newsession , +.Fn crypto_freesession , +and +.Fn crypto_unblock +return 0 on success, or an error code on failure. +.Fn crypto_get_driverid +returns a non-negative value on error, and \-1 on failure. +.Fn crypto_getreq +returns a pointer to a +.Vt cryptop +structure and +.Dv NULL +on failure. +.Fn crypto_dispatch +returns +.Er EINVAL +if its argument or the callback function was +.Dv NULL , +and 0 otherwise. +The callback is provided with an error code in case of failure, in the +.Va crp_etype +field. +.Sh FILES +.Bl -tag -width ".Pa sys/opencrypto/crypto.c" +.It Pa sys/opencrypto/crypto.c +most of the framework code +.El +.Sh SEE ALSO +.Xr crypto 4 , +.Xr ipsec 4 , +.Xr crypto 7 , +.Xr malloc 9 , +.Xr sleep 9 +.Sh HISTORY +The cryptographic framework first appeared in +.Ox 2.7 +and was written by +.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . +.Sh BUGS +The framework currently assumes that all the algorithms in a +.Fn crypto_newsession +operation must be available by the same driver. +If that is not the case, session initialization will fail. +.Pp +The framework also needs a mechanism for determining which driver is +best for a specific set of algorithms associated with a session. +Some type of benchmarking is in order here. +.Pp +Multiple instances of the same algorithm in the same session are not +supported. +Note that 3DES is considered one algorithm (and not three +instances of DES). +Thus, 3DES and DES could be mixed in the same request. Property changes on: user/imp/camdoc/crypto.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pci_iov_schema.9 =================================================================== --- user/imp/camdoc/pci_iov_schema.9 (nonexistent) +++ user/imp/camdoc/pci_iov_schema.9 (revision 296049) @@ -0,0 +1,265 @@ +.\" +.\" Copyright (c) 2014 Sandvine 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 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 8, 2015 +.Dt PCI_IOV_SCHEMA 9 +.Os +.Sh NAME +.Nm pci_iov_schema , +.Nm pci_iov_schema_alloc_node , +.Nm pci_iov_schema_add_bool , +.Nm pci_iov_schema_add_string , +.Nm pci_iov_schema_add_uint8 , +.Nm pci_iov_schema_add_uint16 , +.Nm pci_iov_schema_add_uint32 , +.Nm pci_iov_schema_add_uint64 , +.Nm pci_iov_schema_add_unicast_mac +.Nd PCI SR-IOV config schema interface +.Sh SYNOPSIS +.In machine/stdarg.h +.In sys/nv.h +.In sys/iov_schema.h +.Ft nvlist_t * +.Fn pci_iov_schema_alloc_node "void" +.Ft void +.Fn pci_iov_schema_add_bool "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "int defaultVal" +.Ft void +.Fn pci_iov_schema_add_string "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "const char *defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint8 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint8_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint16 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint16_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint32 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint32_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint64 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint64_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_unicast_mac "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "const uint8_t *defaultVal" +.Sh DESCRIPTION +The PCI Single-Root I/O Virtualization +.Pq SR-IOV +configuration schema is a data +structure that describes the device-specific configuration parameters that a PF +driver will accept when SR-IOV is enabled on the PF device. +Each PF driver defines two schema instances: the PF schema and the VF schema. +The PF schema describes configuration that applies to the PF device as a whole. +The VF schema describes configuration that applies to an individual VF device. +Different VF devices may have different configuration applied to them, as long +as the configuration for each VF conforms to the VF schema. +.Pp +A PF driver builds a configuration schema by first allocating a schema node and +then adding configuration parameter specifications to the schema. +The configuration parameter specification consists of a name and a value type. +.Pp +Configuration parameter names are case-insensitive. +It is an error to specify two or more configuration parameters with the same +name. +It is also an error to specific a configuration parameter that uses the same +name as a configuration parameter used by the SR-IOV infrastructure. +See +.Xr iovctl.conf 5 +for documentation of all configuration parameters used by the SR-IOV +infrastructure. +.Pp +The parameter type constrains the possible values that the configuration +parameter may take. +.Pp +A configuration parameter may be specified as a required parameter by setting +the +.Dv IOV_SCHEMA_REQUIRED +flag in the +.Pa flags +argument. +Required parameters must be specified by the user when SR-IOV is enabled. +If the user does not specify a required parameter, the SR-IOV infrastructure +will abort the request to enable SR-IOV and return an error to the user. +.Pp +Alternatively, a configuration parameter may be given a default value by +setting the +.Dv IOV_SCHEMA_HASDEFAULT +flag in the +.Pa flags +argument. +If a configuration parameter has a default value but the user has not specified +a value for that parameter, then the SR-IOV infrastructure will apply +.Pa defaultVal +for that parameter in the configuration before passing it to the PF driver. +It is an error for the value of the +.Pa defaultVal +parameter to not conform to the restrictions of the specified type. +If this flag is not specified then the +.Pa defaultVal +argument is ignored. +This flag is not compatible with the +.Dv IOV_SCHEMA_REQUIRED +flag; it is an error to specify both on the same parameter. +.Pp +The SR-IOV infrastructure guarantees that all configuration parameters that are +either specified as required or given a default value will be present in the +configuration passed to the PF driver. +Configuration parameters that are neither specified as required nor given a +default value are optional and may or may not be present in the configuration +passed to the PF driver. +.Pp +It is highly recommended that a PF driver reserve the use of optional parameters +for configuration that is truly optional. +For example, a Network Interface PF device might have the option to encapsulate +all traffic to and from a VF device in a vlan tag. +The PF driver could expose that option as a "vlan" parameter accepting an +integer argument specifying the vlan tag. +In this case, it would be appropriate to set the "vlan" parameter as an optional +parameter as it would be legitimate for a VF to be configured to have no vlan +tagging enabled at all. +.Pp +Alternatively, if the PF device had an boolean option that controlled whether +the VF was allowed to change its MAC address, it would not be appropriate to +set this parameter as optional. +The PF driver must either allow the MAC to change or not, so it would be more +appropriate for the PF driver to document the default behaviour by specifying +a default value in the schema +.Po or potentially force the user to make the choice by setting the parameter +to be required +.Pc . +.Pp +Configuration parameters that have security implications must default to the +most secure configuration possible. +.Pp +All device-specific configuration parameters must be documented in the manual +page for the PF driver, or in a separate manual page that is cross-referenced +from the main driver manual page. +.Pp +It is not necessary for a PF driver to check for failure from any of these +functions. +If an error occurs, it is flagged in the schema. +The +.Xr pci_iov_attach 9 +function checks for this error and will fail to initialize SR-IOV on the PF +device if an error is set in the schema. +If this occurs, it is recommended that the PF driver still succeed in attaching +and run with SR-IOV disabled on the device. +.Pp +The +.Fn pci_iov_schema_alloc_node +function is used to allocate an empty configuration schema. +It is not necessary to check for failure from this function. +The SR-IOV infrastructure will gracefully handle failure to allocate a schema +and will simply not enable SR-IOV on the PF device. +.Pp +The +.Fn pci_iov_schema_add_bool +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a boolean type. +Boolean values can only take the value true or false (1 or 0, respectively). +.Pp +The +.Fn pci_iov_schema_add_string +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a string type. +String values are standard C strings. +.Pp +The +.Fn pci_iov_schema_add_uint8 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint8_t +type. +Values of type +.Vt uint8_t +are unsigned integers in the range 0 to 255, inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint16 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint16_t +type. +Values of type +.Vt uint16_t +are unsigned integers in the range 0 to 65535, inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint32 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint32_t +type. +Values of type +.Vt uint32_t +are unsigned integers in the range 0 to +.Pq 2**32 - 1 , +inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint64 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint64_t +type. +Values of type +.Vt uint64_t +are unsigned integers in the range 0 to +.Pq 2**64 - 1 , +inclusive. +.Pp +The +.Fn pci_iov_schema_add_unicast_mac +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a unicast-mac type. +Values of type unicast-mac are binary values exactly 6 bytes long. +The MAC address is guaranteed to not be a multicast or broadcast address. +.Sh RETURN VALUES +The +.Fn pci_iov_schema_alloc_node +function returns a pointer to the allocated schema, or NULL if a failure occurs. +.Sh SEE ALSO +.Xr pci 9 , +.Xr PCI_IOV_ADD_VF 9 , +.Xr PCI_IOV_INIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq rstone@FreeBSD.org . Property changes on: user/imp/camdoc/pci_iov_schema.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/SDT.9 =================================================================== --- user/imp/camdoc/SDT.9 (nonexistent) +++ user/imp/camdoc/SDT.9 (revision 296049) @@ -0,0 +1,346 @@ +.\" Copyright (c) 2013-2015 Mark Johnston +.\" 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 April 18, 2015 +.Dt SDT 9 +.Os +.Sh NAME +.Nm SDT +.Nd a DTrace framework for adding statically-defined tracing probes +.Sh SYNOPSIS +.In sys/param.h +.In sys/queue.h +.In sys/sdt.h +.Fn SDT_PROVIDER_DECLARE prov +.Fn SDT_PROVIDER_DEFINE prov +.Fn SDT_PROBE_DECLARE prov mod func name +.Fn SDT_PROBE_DEFINE prov mod func name +.Fn SDT_PROBE_DEFINE0 prov mod func name +.Fn SDT_PROBE_DEFINE1 prov mod func name arg0 +.Fn SDT_PROBE_DEFINE2 prov mod func name arg0 arg1 +.Fn SDT_PROBE_DEFINE3 prov mod func name arg0 arg1 arg2 +.Fn SDT_PROBE_DEFINE4 prov mod func name arg0 arg1 arg2 arg3 +.Fn SDT_PROBE_DEFINE5 prov mod func name arg0 arg1 arg2 arg3 arg4 +.Fn SDT_PROBE_DEFINE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 +.Fn SDT_PROBE_DEFINE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 \ + arg6 +.Fn SDT_PROBE_DEFINE0_XLATE prov mod func name +.Fn SDT_PROBE_DEFINE1_XLATE prov mod func name arg0 xarg0 +.Fn SDT_PROBE_DEFINE2_XLATE prov mod func name arg0 xarg0 arg1 xarg1 +.Fn SDT_PROBE_DEFINE3_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 +.Fn SDT_PROBE_DEFINE4_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 +.Fn SDT_PROBE_DEFINE5_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 arg4 xarg4 +.Fn SDT_PROBE_DEFINE6_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 +.Fn SDT_PROBE_DEFINE7_XLATE prov mod func name arg0 xarg0 arg1 xarg1 \ + arg2 xarg2 arg3 xarg3 arg4 xarg4 arg5 xarg5 arg6 xarg6 +.Fn SDT_PROBE0 prov mod func name +.Fn SDT_PROBE1 prov mod func name arg0 +.Fn SDT_PROBE2 prov mod func name arg0 arg1 +.Fn SDT_PROBE3 prov mod func name arg0 arg1 arg2 +.Fn SDT_PROBE4 prov mod func name arg0 arg1 arg2 arg3 +.Fn SDT_PROBE5 prov mod func name arg0 arg1 arg2 arg3 arg4 +.Fn SDT_PROBE6 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 +.Fn SDT_PROBE7 prov mod func name arg0 arg1 arg2 arg3 arg4 arg5 arg6 +.Sh DESCRIPTION +The +.Nm +macros allow programmers to define static trace points in kernel code. +These trace points are used by the +.Nm +framework to create DTrace probes, allowing the code to be instrumented +using +.Xr dtrace 1 . +By default, +.Nm +trace points are disabled and have no effect on the surrounding code. +When a DTrace probe corresponding to a given trace point is enabled, threads +that execute the trace point will call a handler and cause the probe to fire. +Moreover, trace points can take arguments, making it possible to pass data +to the DTrace framework when an enabled probe fires. +.Pp +Multiple trace points may correspond to a single DTrace probe, allowing +programmers to create DTrace probes that correspond to logical system events +rather than tying probes to specific code execution paths. +For instance, a DTrace probe corresponding to the arrival of an IP packet into +the network stack may be defined using two +.Nm +trace points: one for IPv4 packets and one for IPv6 packets. +.Pp +In addition to defining DTrace probes, the +.Nm +macros allow programmers to define new DTrace providers, making it possible to +namespace logically-related probes. +An example is FreeBSD's sctp provider, which contains +.Nm +probes for FreeBSD's +.Xr sctp 4 +implementation. +.Pp +The +.Fn SDT_PROVIDER_DECLARE +and +.Fn SDT_PROVIDER_DEFINE +macros are used respectively to declare and define a DTrace provider named +.Ar prov +with the +.Nm +framework. +A provider need only be defined once; however, the provider must be declared +before defining any +.Nm +probes belonging to that provider. +.Pp +Similarly, the +.Fn SDT_PROBE_DECLARE +and +.Fn SDT_PROBE_DEFINE* +macros are used to declare and define DTrace probes using the +.Nm +framework. +Once a probe has been defined, trace points for that probe may be added to +kernel code. +DTrace probe identifiers consist of a provider, module, function and name, all +of which may be specified in the +.Nm +probe definition. +Note that probes should not specify a module name: the module name of a probe is +used to determine whether or not it should be destroyed when a kernel module is +unloaded. +See the +.Sx BUGS +section. +Note in particular that probes must not be defined across multiple kernel +modules. +.Pp +If +.Ql - +character (dash) is wanted in a probe name, +then it should be represented as +.Ql __ +(double underscore) in the probe +.Ar name +parameter passed to various +.Fn SDT_* +macros, +because of technical reasons +(a dash is not valid in C identifiers). +.Pp +The +.Fn SDT_PROBE_DEFINE* +macros also allow programmers to declare the types of the arguments that are +passed to probes. +This is optional; if the argument types are omitted (through use of the +.Fn SDT_PROBE_DEFINE +macro), users wishing to make use of the arguments will have to manually cast +them to the correct types in their D scripts. +It is strongly recommended that probe definitions include a declaration of their +argument types. +.Pp +The +.Fn SDT_PROBE_DEFINE*_XLATE +macros are used for probes whose argument types are to be dynamically translated +to the types specified by the corresponding +.Ar xarg +arguments. +This is mainly useful when porting probe definitions from other operating +systems. +As seen by +.Xr dtrace 1 , +the arguments of a probe defined using these macros will have types which match +the +.Ar xarg +types in the probe definition. +However, the arguments passed in at the trace point will have types matching the +native argument types in the probe definition, and thus the native type is +dynamically translated to the translated type. +So long as an appropriate translator is defined in +.Pa /usr/lib/dtrace , +scripts making use of the probe need not concern themselves with the underlying +type of a given +.Nm +probe argument. +.Pp +The +.Fn SDT_PROBE* +macros are used to create +.Nm +trace points. +They are meant to be added to executable code and can be used to instrument the +code in which they are called. +.Sh PROVIDERS +A number of kernel DTrace providers are available. +In general, these providers define stable interfaces and should be treated as +such: existing D scripts may be broken if a probe is renamed or its arguments +are modified. +However, it is often useful to define ad-hoc +.Nm +probes for debugging a subsystem or driver. +Similarly, a developer may wish to provide a group of +.Nm +probes without committing to their future stability. +Such probes should be added to the +.Ql sdt +provider instead of defining a new provider. +.Sh EXAMPLES +The DTrace providers available on the current system can be listed with +.Bd -literal -offset indent +dtrace -l | sed 1d | awk '{print $2}' | sort -u +.Ed +.Pp +A detailed list of the probes offered by a given provider can be obtained by +specifying the provider using the +.Fl P +flag. +For example, to view the probes and argument types for the +.Ql sched +provider, run +.Bd -literal -offset indent +dtrace -lv -P sched +.Ed +.Pp +The following probe definition will create a DTrace probe called +.Ql icmp:::receive-unreachable , +which would hypothetically be triggered when the kernel receives an ICMP packet +of type Destination Unreachable: +.Bd -literal -offset indent +SDT_PROVIDER_DECLARE(icmp); + +SDT_PROBE_DEFINE1(icmp, , , receive__unreachable, + "struct icmp *"); + +.Ed +This particular probe would take a single argument: a pointer to the struct +containing the ICMP header for the packet. +Note that the module name of this probe is not specified. +.Pp +Consider a DTrace probe which fires when the network stack receives an IP +packet. +Such a probe would be defined by multiple tracepoints: +.Bd -literal -offset indent +SDT_PROBE_DEFINE3(ip, , , receive, "struct ifnet *", + "struct ip *", "struct ip6_hdr *"); + +int +ip_input(struct mbuf *m) +{ + struct ip *ip; + ... + ip = mtod(m, struct ip *); + SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, ip, NULL); + ... +} + +int +ip6_input(struct mbuf *m) +{ + struct ip6_hdr *ip6; + ... + ip6 = mtod(m, struct ip6_hdr *); + SDT_PROBE3(ip, , , receive, m->m_pkthdr.rcvif, NULL, ip6); + ... +} + +.Ed +In particular, the probe should fire when the kernel receives either an IPv4 +packet or an IPv6 packet. +.Pp +Consider the ICMP probe discussed above. +We note that its second argument is of type +.Ar struct icmp , +which is a type defined in the FreeBSD kernel to represent the ICMP header of +an ICMP packet, defined in RFC 792. +Linux has a corresponding type, +.Ar struct icmphdr , +for the same purpose, but its field names differ from FreeBSD's +.Ar struct icmp . +Similarly, illumos defines the +.Ar icmph_t +type, again with different field names. +Even with the +.Ql icmp:::pkt-receive +probes defined in all three operating systems, +one would still have to write OS-specific scripts to extract a given field out +of the ICMP header argument. +Dynamically-translated types solve this problem: one can define an +OS-independent +.Xr c 7 +struct to represent an ICMP header, say +.Ar struct icmp_hdr_dt , +and define translators from each of the three OS-specific types to +.Ar struct icmp_hdr_dt , +all in the +.Xr dtrace 1 +library path. +Then the FreeBSD probe above can be defined with: +.Bd -literal -offset indent +SDT_PROBE_DEFINE1_XLATE(ip, , , receive, "struct icmp *", + "struct icmp_hdr_dt *"); +.Ed +.Sh SEE ALSO +.Xr dtrace 1 , +.Xr dtrace_io 4 , +.Xr dtrace_ip 4 , +.Xr dtrace_proc 4 , +.Xr dtrace_sched 4 , +.Xr dtrace_tcp 4 , +.Xr dtrace_udp 4 +.Sh AUTHORS +.An -nosplit +DTrace and the +.Nm +framework were originally ported to FreeBSD from Solaris by +.An John Birrell Aq Mt jb@FreeBSD.org . +This manual page was written by +.An Mark Johnston Aq Mt markj@FreeBSD.org . +.Sh BUGS +The +.Nm +macros allow the module and function names of a probe to be specified as part of +a probe definition. +The DTrace framework uses the module name of probes to determine which probes +should be destroyed when a kernel module is unloaded, so the module +name of a probe should match the name of the module in which its defined. +.Nm +will set the module name properly if it is left unspecified in the probe +definition; see the +.Sx EXAMPLES +section. +.Pp +One of the goals of the original +.Nm +implementation (and by extension, of FreeBSD's port) is that inactive +.Nm +probes should have no performance impact. +This is unfortunately not the case; +.Nm +trace points will add a small but non-zero amount of latency to the code +in which they are defined. +A more sophisticated implementation of the probes will help alleviate this +problem. Property changes on: user/imp/camdoc/SDT.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/locking.9 =================================================================== --- user/imp/camdoc/locking.9 (nonexistent) +++ user/imp/camdoc/locking.9 (revision 296049) @@ -0,0 +1,414 @@ +.\" 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 +.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. Property changes on: user/imp/camdoc/locking.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/hash.9 =================================================================== --- user/imp/camdoc/hash.9 (nonexistent) +++ user/imp/camdoc/hash.9 (revision 296049) @@ -0,0 +1,227 @@ +.\" Copyright (c) 2001 Tobias Weingartner +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $OpenBSD: hash.9,v 1.5 2003/04/17 05:08:39 jmc Exp $ +.\" $FreeBSD$ +.\" +.Dd June 30, 2015 +.Dt HASH 9 +.Os +.Sh NAME +.Nm hash , +.Nm hash32 , +.Nm hash32_buf , +.Nm hash32_str , +.Nm hash32_strn , +.Nm hash32_stre , +.Nm hash32_strne , +.Nm jenkins_hash , +.Nm jenkins_hash32 , +.Nm murmur3_32_hash , +.Nm murmur3_32_hash32 +.Nd general kernel hashing functions +.Sh SYNOPSIS +.In sys/hash.h +.Ft uint32_t +.Fn hash32_buf "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn hash32_str "const void *buf" "uint32_t hash" +.Ft uint32_t +.Fn hash32_strn "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn hash32_stre "const void *buf" "int end" "const char **ep" "uint32_t hash" +.Ft uint32_t +.Fn hash32_strne "const void *buf" "size_t len" "int end" "const char **ep" "uint32_t hash" +.Ft uint32_t +.Fn jenkins_hash "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn jenkins_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash" +.Ft uint32_t +.Fn murmur3_32_hash "const void *buf" "size_t len" "uint32_t hash" +.Ft uint32_t +.Fn murmur3_32_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash" +.Sh DESCRIPTION +The +.Fn hash32 +functions are used to give a consistent and general interface to +a decent hashing algorithm within the kernel. +These functions can be used to hash +.Tn ASCII +.Dv NUL +terminated strings, as well as blocks of memory. +.Pp +A +.Fa len +argument is the length of the buffer in bytes. +A +.Fa count +argument is the length of the buffer in 32-bit words. +.Pp +The +.Fn hash32_buf +function is used as a general buffer hashing function. +The argument +.Fa buf +is used to pass in the location, and +.Fa len +is the length of the buffer in bytes. +The argument +.Fa hash +is used to extend an existing hash, or is passed the initial value +.Dv HASHINIT +to start a new hash. +.Pp +The +.Fn hash32_str +function is used to hash a +.Dv NUL +terminated string passed in +.Fa buf +with initial hash value given in +.Fa hash . +.Pp +The +.Fn hash32_strn +function is like the +.Fn hash32_str +function, except it also takes a +.Fa len +argument, which is the maximal length of the expected string. +.Pp +The +.Fn hash32_stre +and +.Fn hash32_strne +functions are helper functions used by the kernel to hash pathname +components. +These functions have the additional termination condition +of terminating when they find a character given by +.Fa end +in the string to be hashed. +If the argument +.Fa ep +is not +.Dv NULL , +it is set to the point in the buffer at which the hash function +terminated hashing. +.Pp +The +.Fn jenkins_hash +function has same semantics as the +.Fn hash32_buf , +but provides more advanced hashing algorithm with better distribution. +.Pp +The +.Fn jenkins_hash32 +uses same hashing algorithm as the +.Fn jenkins_hash +function, but works only on +.Ft uint32_t +sized arrays, thus is simplier and faster. +It accepts an array of +.Ft uint32_t +values in its first argument and size of this array in the second argument. +.Pp +The +.Fn murmur3_32_hash +and +.Fn murmur3_32_hash32 +functions are similar to +.Fn jenkins_hash +and +.Fn jenkins_hash32 , +but implement the 32-bit version of MurmurHash3. +.Sh RETURN VALUES +The +.Fn hash32 +functions return a 32 bit hash value of the buffer or string. +.Sh EXAMPLES +.Bd -literal -offset indent +LIST_HEAD(head, cache) *hashtbl = NULL; +u_long mask = 0; + +void +sample_init(void) +{ + + hashtbl = hashinit(numwanted, type, flags, &mask); +} + +void +sample_use(char *str, int len) +{ + uint32_t hash; + + hash = hash32_str(str, HASHINIT); + hash = hash32_buf(&len, sizeof(len), hash); + hashtbl[hash & mask] = len; +} +.Ed +.Sh SEE ALSO +.Xr free 9 , +.Xr hashinit 9 , +.Xr malloc 9 +.Sh LIMITATIONS +The +.Fn hash32 +functions are only 32 bit functions. +They will prove to give poor 64 bit performance, especially for the +top 32 bits. +At the current time, this is not seen as a great limitation, as these +hash values are usually used to index into an array. +Should these hash values be used for other means, this limitation should +be revisited. +.Sh HISTORY +The +.Nm +functions first appeared in +.Nx 1.6 . +The current implementation of +.Nm hash32 +functions was first committed to +.Ox 3.2 , +and later imported to +.Fx 6.1 . +The +.Nm jenkins_hash +functions were added in +.Fx 10.0 . +The +.Nm murmur3_32_hash +functions were added in +.Fx 10.1 . +.Sh AUTHORS +The +.Nm hash32 +functions were written by +.An Tobias Weingartner . +The +.Nm jenkins_hash +functions were written by +.An Bob Jenkins . +The +.Nm murmur3_32_hash +functions were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . Property changes on: user/imp/camdoc/hash.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/sbuf.9 =================================================================== --- user/imp/camdoc/sbuf.9 (nonexistent) +++ user/imp/camdoc/sbuf.9 (revision 296049) @@ -0,0 +1,606 @@ +.\"- +.\" Copyright (c) 2000 Poul-Henning Kamp and 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 March 14, 2015 +.Dt SBUF 9 +.Os +.Sh NAME +.Nm sbuf , +.Nm sbuf_new , +.Nm sbuf_new_auto , +.Nm sbuf_new_for_sysctl , +.Nm sbuf_clear , +.Nm sbuf_get_flags , +.Nm sbuf_set_flags , +.Nm sbuf_clear_flags , +.Nm sbuf_setpos , +.Nm sbuf_bcat , +.Nm sbuf_bcopyin , +.Nm sbuf_bcpy , +.Nm sbuf_cat , +.Nm sbuf_copyin , +.Nm sbuf_cpy , +.Nm sbuf_printf , +.Nm sbuf_vprintf , +.Nm sbuf_putc , +.Nm sbuf_set_drain , +.Nm sbuf_trim , +.Nm sbuf_error , +.Nm sbuf_finish , +.Nm sbuf_data , +.Nm sbuf_len , +.Nm sbuf_done , +.Nm sbuf_delete , +.Nm sbuf_start_section , +.Nm sbuf_end_section , +.Nm sbuf_hexdump +.Nd safe string composition +.Sh SYNOPSIS +.In sys/types.h +.In sys/sbuf.h +.Ft typedef\ int ( sbuf_drain_func ) ( void\ *arg, const\ char\ *data, int\ len ) ; +.Pp +.Ft struct sbuf * +.Fn sbuf_new "struct sbuf *s" "char *buf" "int length" "int flags" +.Ft struct sbuf * +.Fn sbuf_new_auto +.Ft void +.Fn sbuf_clear "struct sbuf *s" +.Ft int +.Fn sbuf_get_flags "struct sbuf *s" +.Ft void +.Fn sbuf_set_flags "struct sbuf *s" "int flags" +.Ft void +.Fn sbuf_clear_flags "struct sbuf *s" "int flags" +.Ft int +.Fn sbuf_setpos "struct sbuf *s" "int pos" +.Ft int +.Fn sbuf_bcat "struct sbuf *s" "const void *buf" "size_t len" +.Ft int +.Fn sbuf_bcopyin "struct sbuf *s" "const void *uaddr" "size_t len" +.Ft int +.Fn sbuf_bcpy "struct sbuf *s" "const void *buf" "size_t len" +.Ft int +.Fn sbuf_cat "struct sbuf *s" "const char *str" +.Ft int +.Fn sbuf_copyin "struct sbuf *s" "const void *uaddr" "size_t len" +.Ft int +.Fn sbuf_cpy "struct sbuf *s" "const char *str" +.Ft int +.Fn sbuf_printf "struct sbuf *s" "const char *fmt" "..." +.Ft int +.Fn sbuf_vprintf "struct sbuf *s" "const char *fmt" "va_list ap" +.Ft int +.Fn sbuf_putc "struct sbuf *s" "int c" +.Ft void +.Fn sbuf_set_drain "struct sbuf *s" "sbuf_drain_func *func" "void *arg" +.Ft int +.Fn sbuf_trim "struct sbuf *s" +.Ft int +.Fn sbuf_error "struct sbuf *s" +.Ft int +.Fn sbuf_finish "struct sbuf *s" +.Ft char * +.Fn sbuf_data "struct sbuf *s" +.Ft ssize_t +.Fn sbuf_len "struct sbuf *s" +.Ft int +.Fn sbuf_done "struct sbuf *s" +.Ft void +.Fn sbuf_delete "struct sbuf *s" +.Ft void +.Fn sbuf_start_section "struct sbuf *s" "ssize_t *old_lenp" +.Ft ssize_t +.Fn sbuf_end_section "struct sbuf *s" "ssize_t old_len" "size_t pad" "int c" +.Ft void +.Fo sbuf_hexdump +.Fa "struct sbuf *sb" +.Fa "void *ptr" +.Fa "int length" +.Fa "const char *hdr" +.Fa "int flags" +.Fc +.In sys/sysctl.h +.Ft struct sbuf * +.Fn sbuf_new_for_sysctl "struct sbuf *s" "char *buf" "int length" "struct sysctl_req *req" +.Sh DESCRIPTION +The +.Nm +family of functions allows one to safely allocate, compose and +release strings in kernel or user space. +.Pp +Instead of arrays of characters, these functions operate on structures +called +.Fa sbufs , +defined in +.In sys/sbuf.h . +.Pp +Any errors encountered during the allocation or composition of the +string will be latched in the data structure, +making a single error test at the end of the composition +sufficient to determine success or failure of the entire process. +.Pp +The +.Fn sbuf_new +function initializes the +.Fa sbuf +pointed to by its first argument. +If that pointer is +.Dv NULL , +.Fn sbuf_new +allocates a +.Vt struct sbuf +using +.Xr malloc 9 . +The +.Fa buf +argument is a pointer to a buffer in which to store the actual string; +if it is +.Dv NULL , +.Fn sbuf_new +will allocate one using +.Xr malloc 9 . +The +.Fa length +is the initial size of the storage buffer. +The fourth argument, +.Fa flags , +may be comprised of the following flags: +.Bl -tag -width ".Dv SBUF_AUTOEXTEND" +.It Dv SBUF_FIXEDLEN +The storage buffer is fixed at its initial size. +Attempting to extend the sbuf beyond this size results in an overflow condition. +.It Dv SBUF_AUTOEXTEND +This indicates that the storage buffer may be extended as necessary, so long +as resources allow, to hold additional data. +.It Dv SBUF_INCLUDENUL +This causes the final nulterm byte to be counted in the length of the data. +.El +.Pp +Note that if +.Fa buf +is not +.Dv NULL , +it must point to an array of at least +.Fa length +characters. +The result of accessing that array directly while it is in use by the +sbuf is undefined. +.Pp +The +.Fn sbuf_new_auto +function is a shortcut for creating a completely dynamic +.Nm . +It is the equivalent of calling +.Fn sbuf_new +with values +.Dv NULL , +.Dv NULL , +.Dv 0 , +and +.Dv SBUF_AUTOEXTEND . +.Pp +The +.Fn sbuf_new_for_sysctl +function will set up an sbuf with a drain function to use +.Fn SYSCTL_OUT +when the internal buffer fills. +Note that if the various functions which append to an sbuf are used while +a non-sleepable lock is held, the user buffer should be wired using +.Fn sysctl_wire_old_buffer . +.Pp +The +.Fn sbuf_delete +function clears the +.Fa sbuf +and frees any memory allocated for it. +There must be a call to +.Fn sbuf_delete +for every call to +.Fn sbuf_new . +Any attempt to access the sbuf after it has been deleted will fail. +.Pp +The +.Fn sbuf_clear +function invalidates the contents of the +.Fa sbuf +and resets its position to zero. +.Pp +The +.Fn sbuf_get_flags +function returns the current user flags. +The +.Fn sbuf_set_flags +and +.Fn sbuf_get_flags +functions set or clear one or more user flags, respectively. +The user flags are described under the +.Fn sbuf_new +function. +.Pp +The +.Fn sbuf_setpos +function sets the +.Fa sbuf Ns 's +end position to +.Fa pos , +which is a value between zero and one less than the size of the +storage buffer. +This effectively truncates the sbuf at the new position. +.Pp +The +.Fn sbuf_bcat +function appends the first +.Fa len +bytes from the buffer +.Fa buf +to the +.Fa sbuf . +.Pp +The +.Fn sbuf_bcopyin +function copies +.Fa len +bytes from the specified userland address into the +.Fa sbuf . +.Pp +The +.Fn sbuf_bcpy +function replaces the contents of the +.Fa sbuf +with the first +.Fa len +bytes from the buffer +.Fa buf . +.Pp +The +.Fn sbuf_cat +function appends the NUL-terminated string +.Fa str +to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_set_drain +function sets a drain function +.Fa func +for the +.Fa sbuf , +and records a pointer +.Fa arg +to be passed to the drain on callback. +The drain function cannot be changed while +.Fa sbuf_len +is non-zero. +.Pp +The registered drain function +.Vt sbuf_drain_func +will be called with the argument +.Fa arg +provided to +.Fn sbuf_set_drain , +a pointer +.Fa data +to a byte string that is the contents of the sbuf, and the length +.Fa len +of the data. +If the drain function exists, it will be called when the sbuf internal +buffer is full, or on behalf of +.Fn sbuf_finish . +The drain function may drain some or all of the data, but must drain +at least 1 byte. +The return value from the drain function, if positive, indicates how +many bytes were drained. +If negative, the return value indicates the negative error code which +will be returned from this or a later call to +.Fn sbuf_finish . +The returned drained length cannot be zero. +To do unbuffered draining, initialize the sbuf with a two-byte buffer. +The drain will be called for every byte added to the sbuf. +The +.Fn sbuf_bcopyin , +.Fn sbuf_copyin , +.Fn sbuf_trim , +and +.Fn sbuf_data +functions cannot be used on an sbuf with a drain. +.Pp +The +.Fn sbuf_copyin +function copies a NUL-terminated string from the specified userland +address into the +.Fa sbuf . +If the +.Fa len +argument is non-zero, no more than +.Fa len +characters (not counting the terminating NUL) are copied; otherwise +the entire string, or as much of it as can fit in the +.Fa sbuf , +is copied. +.Pp +The +.Fn sbuf_cpy +function replaces the contents of the +.Fa sbuf +with those of the NUL-terminated string +.Fa str . +This is equivalent to calling +.Fn sbuf_cat +with a fresh +.Fa sbuf +or one which position has been reset to zero with +.Fn sbuf_clear +or +.Fn sbuf_setpos . +.Pp +The +.Fn sbuf_printf +function formats its arguments according to the format string pointed +to by +.Fa fmt +and appends the resulting string to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_vprintf +function behaves the same as +.Fn sbuf_printf +except that the arguments are obtained from the variable-length argument list +.Fa ap . +.Pp +The +.Fn sbuf_putc +function appends the character +.Fa c +to the +.Fa sbuf +at the current position. +.Pp +The +.Fn sbuf_trim +function removes trailing whitespace from the +.Fa sbuf . +.Pp +The +.Fn sbuf_error +function returns any error value that the +.Fa sbuf +may have accumulated, either from the drain function, or ENOMEM if the +.Fa sbuf +overflowed. +This function is generally not needed and instead the error code from +.Fn sbuf_finish +is the preferred way to discover whether an sbuf had an error. +.Pp +The +.Fn sbuf_finish +function will call the attached drain function if one exists until all +the data in the +.Fa sbuf +is flushed. +If there is no attached drain, +.Fn sbuf_finish +NUL-terminates the +.Fa sbuf . +In either case it marks the +.Fa sbuf +as finished, which means that it may no longer be modified using +.Fn sbuf_setpos , +.Fn sbuf_cat , +.Fn sbuf_cpy , +.Fn sbuf_printf +or +.Fn sbuf_putc , +until +.Fn sbuf_clear +is used to reset the sbuf. +.Pp +The +.Fn sbuf_data +function returns the actual string; +.Fn sbuf_data +only works on a finished +.Fa sbuf . +The +.Fn sbuf_len +function returns the length of the string. +For an +.Fa sbuf +with an attached drain, +.Fn sbuf_len +returns the length of the un-drained data. +.Fn sbuf_done +returns non-zero if the +.Fa sbuf +is finished. +.Pp +The +.Fn sbuf_start_section +and +.Fn sbuf_end_section +functions may be used for automatic section alignment. +The arguments +.Fa pad +and +.Fa c +specify the padding size and a character used for padding. +The arguments +.Fa old_lenp +and +.Fa old_len +are to save and restore the current section length when nested sections +are used. +For the top level section +.Dv NULL +and \-1 can be specified for +.Fa old_lenp +and +.Fa old_len +respectively. +.Pp +The +.Fn sbuf_hexdump +function prints an array of bytes to the supplied sbuf, along with an ASCII +representation of the bytes if possible. +See the +.Xr hexdump 3 +man page for more details on the interface. +.Sh NOTES +If an operation caused an +.Fa sbuf +to overflow, most subsequent operations on it will fail until the +.Fa sbuf +is finished using +.Fn sbuf_finish +or reset using +.Fn sbuf_clear , +or its position is reset to a value between 0 and one less than the +size of its storage buffer using +.Fn sbuf_setpos , +or it is reinitialized to a sufficiently short string using +.Fn sbuf_cpy . +.Pp +Drains in user-space will not always function as indicated. +While the drain function will be called immediately on overflow from +the +.Fa sbuf_putc , +.Fa sbuf_bcat , +.Fa sbuf_cat +functions, +.Fa sbuf_printf +and +.Fa sbuf_vprintf +currently have no way to determine whether there will be an overflow +until after it occurs, and cannot do a partial expansion of the format +string. +Thus when using libsbuf the buffer may be extended to allow completion +of a single printf call, even though a drain is attached. +.Sh RETURN VALUES +The +.Fn sbuf_new +function returns +.Dv NULL +if it failed to allocate a storage buffer, and a pointer to the new +.Fa sbuf +otherwise. +.Pp +The +.Fn sbuf_setpos +function returns \-1 if +.Fa pos +was invalid, and zero otherwise. +.Pp +The +.Fn sbuf_cat , +.Fn sbuf_cpy , +.Fn sbuf_printf , +.Fn sbuf_putc , +and +.Fn sbuf_trim +functions +all return \-1 if the buffer overflowed, and zero otherwise. +.Pp +The +.Fn sbuf_error +function returns a non-zero value if the buffer has an overflow or +drain error, and zero otherwise. +.Pp +The +.Fn sbuf_len +function returns \-1 if the buffer overflowed. +.Pp +The +.Fn sbuf_copyin +function +returns \-1 if copying string from userland failed, and number of bytes +copied otherwise. +.Pp +The +.Fn sbuf_end_section +function returns the section length or \-1 if the buffer has an error. +.Pp +The +.Fn sbuf_finish 9 +function (the kernel version) returns ENOMEM if the sbuf overflowed before +being finished, +or returns the error code from the drain if one is attached. +.Pp +The +.Fn sbuf_finish 3 +function (the userland version) +will return zero for success and \-1 and set errno on error. +.Sh EXAMPLES +.Bd -literal -compact +#include + +struct sbuf *sb; + +sb = sbuf_new_auto(); +sbuf_cat(sb, "Customers found:\en"); +TAILQ_FOREACH(foo, &foolist, list) { + sbuf_printf(sb, " %4d %s\en", foo->index, foo->name); + sbuf_printf(sb, " Address: %s\en", foo->address); + sbuf_printf(sb, " Zip: %s\en", foo->zipcode); +} +if (sbuf_finish(sb) != 0) /* Check for any and all errors */ + err(1, "Could not generate message"); +transmit_msg(sbuf_data(sb), sbuf_len(sb)); +sbuf_delete(sb); +.Ed +.Sh SEE ALSO +.Xr hexdump 3 , +.Xr printf 3 , +.Xr strcat 3 , +.Xr strcpy 3 , +.Xr copyin 9 , +.Xr copyinstr 9 , +.Xr printf 9 +.Sh HISTORY +The +.Nm +family of functions first appeared in +.Fx 4.4 . +.Sh AUTHORS +.An -nosplit +The +.Nm +family of functions was designed by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org +and implemented by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +Additional improvements were suggested by +.An Justin T. Gibbs Aq Mt gibbs@FreeBSD.org . +Auto-extend support added by +.An Kelly Yancey Aq Mt kbyanc@FreeBSD.org . +Drain functionality added by +.An Matthew Fleming Aq Mt mdf@FreeBSD.org . +.Pp +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . Property changes on: user/imp/camdoc/sbuf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/taskqueue.9 =================================================================== --- user/imp/camdoc/taskqueue.9 (nonexistent) +++ user/imp/camdoc/taskqueue.9 (revision 296049) @@ -0,0 +1,508 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 4, 2015 +.Dt TASKQUEUE 9 +.Os +.Sh NAME +.Nm taskqueue +.Nd asynchronous task execution +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/malloc.h +.In sys/queue.h +.In sys/taskqueue.h +.Bd -literal +typedef void (*task_fn_t)(void *context, int pending); + +typedef void (*taskqueue_enqueue_fn)(void *context); + +struct task { + STAILQ_ENTRY(task) ta_link; /* link for queue */ + u_short ta_pending; /* count times queued */ + u_short ta_priority; /* priority of task in queue */ + task_fn_t ta_func; /* task handler */ + void *ta_context; /* argument for handler */ +}; + +enum taskqueue_callback_type { + TASKQUEUE_CALLBACK_TYPE_INIT, + TASKQUEUE_CALLBACK_TYPE_SHUTDOWN, +}; + +typedef void (*taskqueue_callback_fn)(void *context); + +struct timeout_task; +.Ed +.Ft struct taskqueue * +.Fn taskqueue_create "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" +.Ft struct taskqueue * +.Fn taskqueue_create_fast "const char *name" "int mflags" "taskqueue_enqueue_fn enqueue" "void *context" +.Ft int +.Fn taskqueue_start_threads "struct taskqueue **tqp" "int count" "int pri" "const char *name" "..." +.Ft int +.Fo taskqueue_start_threads_pinned +.Fa "struct taskqueue **tqp" "int count" "int pri" "int cpu_id" +.Fa "const char *name" "..." +.Fc +.Ft void +.Fn taskqueue_set_callback "struct taskqueue *queue" "enum taskqueue_callback_type cb_type" "taskqueue_callback_fn callback" "void *context" +.Ft void +.Fn taskqueue_free "struct taskqueue *queue" +.Ft int +.Fn taskqueue_enqueue "struct taskqueue *queue" "struct task *task" +.Ft int +.Fn taskqueue_enqueue_fast "struct taskqueue *queue" "struct task *task" +.Ft int +.Fn taskqueue_enqueue_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "int ticks" +.Ft int +.Fn taskqueue_cancel "struct taskqueue *queue" "struct task *task" "u_int *pendp" +.Ft int +.Fn taskqueue_cancel_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" "u_int *pendp" +.Ft void +.Fn taskqueue_drain "struct taskqueue *queue" "struct task *task" +.Ft void +.Fn taskqueue_drain_timeout "struct taskqueue *queue" "struct timeout_task *timeout_task" +.Ft void +.Fn taskqueue_drain_all "struct taskqueue *queue" +.Ft void +.Fn taskqueue_block "struct taskqueue *queue" +.Ft void +.Fn taskqueue_unblock "struct taskqueue *queue" +.Ft int +.Fn taskqueue_member "struct taskqueue *queue" "struct thread *td" +.Ft void +.Fn taskqueue_run "struct taskqueue *queue" +.Fn TASK_INIT "struct task *task" "int priority" "task_fn_t func" "void *context" +.Fn TASK_INITIALIZER "int priority" "task_fn_t func" "void *context" +.Fn TASKQUEUE_DECLARE "name" +.Fn TASKQUEUE_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" +.Fn TASKQUEUE_FAST_DEFINE "name" "taskqueue_enqueue_fn enqueue" "void *context" "init" +.Fn TASKQUEUE_DEFINE_THREAD "name" +.Fn TASKQUEUE_FAST_DEFINE_THREAD "name" +.Fn TIMEOUT_TASK_INIT "struct taskqueue *queue" "struct timeout_task *timeout_task" "int priority" "task_fn_t func" "void *context" +.Sh DESCRIPTION +These functions provide a simple interface for asynchronous execution +of code. +.Pp +The function +.Fn taskqueue_create +is used to create new queues. +The arguments to +.Fn taskqueue_create +include a name that should be unique, +a set of +.Xr malloc 9 +flags that specify whether the call to +.Fn malloc +is allowed to sleep, +a function that is called from +.Fn taskqueue_enqueue +when a task is added to the queue, +and a pointer to the memory location where the identity of the +thread that services the queue is recorded. +.\" XXX The rest of the sentence gets lots in relation to the first part. +The function called from +.Fn taskqueue_enqueue +must arrange for the queue to be processed +(for instance by scheduling a software interrupt or waking a kernel +thread). +The memory location where the thread identity is recorded is used +to signal the service thread(s) to terminate--when this value is set to +zero and the thread is signaled it will terminate. +If the queue is intended for use in fast interrupt handlers +.Fn taskqueue_create_fast +should be used in place of +.Fn taskqueue_create . +.Pp +The function +.Fn taskqueue_free +should be used to free the memory used by the queue. +Any tasks that are on the queue will be executed at this time after +which the thread servicing the queue will be signaled that it should exit. +.Pp +Once a taskqueue has been created, its threads should be started using +.Fn taskqueue_start_threads +or +.Fn taskqueue_start_threads_pinned . +.Fn taskqueue_start_threads_pinned +takes a +.Va cpu_id +argument which will cause the threads which are started for the taskqueue +to be pinned to run on the given CPU. +Callbacks may optionally be registered using +.Fn taskqueue_set_callback . +Currently, callbacks may be registered for the following purposes: +.Bl -tag -width TASKQUEUE_CALLBACK_TYPE_SHUTDOWN +.It Dv TASKQUEUE_CALLBACK_TYPE_INIT +This callback is called by every thread in the taskqueue, before it executes +any tasks. +This callback must be set before the taskqueue's threads are started. +.It Dv TASKQUEUE_CALLBACK_TYPE_SHUTDOWN +This callback is called by every thread in the taskqueue, after it executes +its last task. +This callback will always be called before the taskqueue structure is +reclaimed. +.El +.Pp +To add a task to the list of tasks queued on a taskqueue, call +.Fn taskqueue_enqueue +with pointers to the queue and task. +If the task's +.Va ta_pending +field is non-zero, +then it is simply incremented to reflect the number of times the task +was enqueued, up to a cap of USHRT_MAX. +Otherwise, +the task is added to the list before the first task which has a lower +.Va ta_priority +value or at the end of the list if no tasks have a lower priority. +Enqueueing a task does not perform any memory allocation which makes +it suitable for calling from an interrupt handler. +This function will return +.Er EPIPE +if the queue is being freed. +.Pp +The function +.Fn taskqueue_enqueue_fast +should be used in place of +.Fn taskqueue_enqueue +when the enqueuing must happen from a fast interrupt handler. +This method uses spin locks to avoid the possibility of sleeping in the fast +interrupt context. +.Pp +When a task is executed, +first it is removed from the queue, +the value of +.Va ta_pending +is recorded and then the field is zeroed. +The function +.Va ta_func +from the task structure is called with the value of the field +.Va ta_context +as its first argument +and the value of +.Va ta_pending +as its second argument. +After the function +.Va ta_func +returns, +.Xr wakeup 9 +is called on the task pointer passed to +.Fn taskqueue_enqueue . +.Pp +The +.Fn taskqueue_enqueue_timeout +is used to schedule the enqueue after the specified amount of +.Va ticks . +Only non-fast task queues can be used for +.Va timeout_task +scheduling. +If the +.Va ticks +argument is negative, the already scheduled enqueueing is not re-scheduled. +Otherwise, the task is scheduled for enqueueing in the future, +after the absolute value of +.Va ticks +is passed. +.Pp +The +.Fn taskqueue_cancel +function is used to cancel a task. +The +.Va ta_pending +count is cleared, and the old value returned in the reference +parameter +.Fa pendp , +if it is +.Pf non- Dv NULL . +If the task is currently running, +.Dv EBUSY +is returned, otherwise 0. +To implement a blocking +.Fn taskqueue_cancel +that waits for a running task to finish, it could look like: +.Bd -literal -offset indent +while (taskqueue_cancel(tq, task, NULL) != 0) + taskqueue_drain(tq, task); +.Ed +.Pp +Note that, as with +.Fn taskqueue_drain , +the caller is responsible for ensuring that the task is not re-enqueued +after being canceled. +.Pp +Similarly, the +.Fn taskqueue_cancel_timeout +function is used to cancel the scheduled task execution. +.Pp +The +.Fn taskqueue_drain +function is used to wait for the task to finish, and +the +.Fn taskqueue_drain_timeout +function is used to wait for the scheduled task to finish. +There is no guarantee that the task will not be +enqueued after call to +.Fn taskqueue_drain . +If the caller wants to put the task into a known state, +then before calling +.Fn taskqueue_drain +the caller should use out-of-band means to ensure that the task +would not be enqueued. +For example, if the task is enqueued by an interrupt filter, then +the interrupt could be disabled. +.Pp +The +.Fn taskqueue_drain_all +function is used to wait for all pending and running tasks that +are enqueued on the taskqueue to finish. +Tasks posted to the taskqueue after +.Fn taskqueue_drain_all +begins processing, +including pending enqueues scheduled by a previous call to +.Fn taskqueue_enqueue_timeout , +do not extend the wait time of +.Fn taskqueue_drain_all +and may complete after +.Fn taskqueue_drain_all +returns. +.Pp +The +.Fn taskqueue_block +function blocks the taskqueue. +It prevents any enqueued but not running tasks from being executed. +Future calls to +.Fn taskqueue_enqueue +will enqueue tasks, but the tasks will not be run until +.Fn taskqueue_unblock +is called. +Please note that +.Fn taskqueue_block +does not wait for any currently running tasks to finish. +Thus, the +.Fn taskqueue_block +does not provide a guarantee that +.Fn taskqueue_run +is not running after +.Fn taskqueue_block +returns, but it does provide a guarantee that +.Fn taskqueue_run +will not be called again +until +.Fn taskqueue_unblock +is called. +If the caller requires a guarantee that +.Fn taskqueue_run +is not running, then this must be arranged by the caller. +Note that if +.Fn taskqueue_drain +is called on a task that is enqueued on a taskqueue that is blocked by +.Fn taskqueue_block , +then +.Fn taskqueue_drain +can not return until the taskqueue is unblocked. +This can result in a deadlock if the thread blocked in +.Fn taskqueue_drain +is the thread that is supposed to call +.Fn taskqueue_unblock . +Thus, use of +.Fn taskqueue_drain +after +.Fn taskqueue_block +is discouraged, because the state of the task can not be known in advance. +The same caveat applies to +.Fn taskqueue_drain_all . +.Pp +The +.Fn taskqueue_unblock +function unblocks the previously blocked taskqueue. +All enqueued tasks can be run after this call. +.Pp +The +.Fn taskqueue_member +function returns +.No 1 +if the given thread +.Fa td +is part of the given taskqueue +.Fa queue +and +.No 0 +otherwise. +.Pp +The +.Fn taskqueue_run +function will run all pending tasks in the specified +.Fa queue . +Normally this function is only used internally. +.Pp +A convenience macro, +.Fn TASK_INIT "task" "priority" "func" "context" +is provided to initialise a +.Va task +structure. +The +.Fn TASK_INITIALIZER +macro generates an initializer for a task structure. +A macro +.Fn TIMEOUT_TASK_INIT "queue" "timeout_task" "priority" "func" "context" +initializes the +.Va timeout_task +structure. +The values of +.Va priority , +.Va func , +and +.Va context +are simply copied into the task structure fields and the +.Va ta_pending +field is cleared. +.Pp +Five macros +.Fn TASKQUEUE_DECLARE "name" , +.Fn TASKQUEUE_DEFINE "name" "enqueue" "context" "init" , +.Fn TASKQUEUE_FAST_DEFINE "name" "enqueue" "context" "init" , +and +.Fn TASKQUEUE_DEFINE_THREAD "name" +.Fn TASKQUEUE_FAST_DEFINE_THREAD "name" +are used to declare a reference to a global queue, to define the +implementation of the queue, and declare a queue that uses its own thread. +The +.Fn TASKQUEUE_DEFINE +macro arranges to call +.Fn taskqueue_create +with the values of its +.Va name , +.Va enqueue +and +.Va context +arguments during system initialisation. +After calling +.Fn taskqueue_create , +the +.Va init +argument to the macro is executed as a C statement, +allowing any further initialisation to be performed +(such as registering an interrupt handler etc.) +.Pp +The +.Fn TASKQUEUE_DEFINE_THREAD +macro defines a new taskqueue with its own kernel thread to serve tasks. +The variable +.Vt struct taskqueue *taskqueue_name +is used to enqueue tasks onto the queue. +.Pp +.Fn TASKQUEUE_FAST_DEFINE +and +.Fn TASKQUEUE_FAST_DEFINE_THREAD +act just like +.Fn TASKQUEUE_DEFINE +and +.Fn TASKQUEUE_DEFINE_THREAD +respectively but taskqueue is created with +.Fn taskqueue_create_fast . +.Ss Predefined Task Queues +The system provides four global taskqueues, +.Va taskqueue_fast , +.Va taskqueue_swi , +.Va taskqueue_swi_giant , +and +.Va taskqueue_thread . +The +.Va taskqueue_fast +queue is for swi handlers dispatched from fast interrupt handlers, +where sleep mutexes cannot be used. +The swi taskqueues are run via a software interrupt mechanism. +The +.Va taskqueue_swi +queue runs without the protection of the +.Va Giant +kernel lock, and the +.Va taskqueue_swi_giant +queue runs with the protection of the +.Va Giant +kernel lock. +The thread taskqueue +.Va taskqueue_thread +runs in a kernel thread context, and tasks run from this thread do +not run under the +.Va Giant +kernel lock. +If the caller wants to run under +.Va Giant , +he should explicitly acquire and release +.Va Giant +in his taskqueue handler routine. +.Pp +To use these queues, +call +.Fn taskqueue_enqueue +with the value of the global taskqueue variable for the queue you wish to +use +.Va ( taskqueue_swi , +.Va taskqueue_swi_giant , +or +.Va taskqueue_thread ) . +Use +.Fn taskqueue_enqueue_fast +for the global taskqueue variable +.Va taskqueue_fast . +.Pp +The software interrupt queues can be used, +for instance, for implementing interrupt handlers which must perform a +significant amount of processing in the handler. +The hardware interrupt handler would perform minimal processing of the +interrupt and then enqueue a task to finish the work. +This reduces to a minimum +the amount of time spent with interrupts disabled. +.Pp +The thread queue can be used, for instance, by interrupt level routines +that need to call kernel functions that do things that can only be done +from a thread context. +(e.g., call malloc with the M_WAITOK flag.) +.Pp +Note that tasks queued on shared taskqueues such as +.Va taskqueue_swi +may be delayed an indeterminate amount of time before execution. +If queueing delays cannot be tolerated then a private taskqueue should +be created with a dedicated processing thread. +.Sh SEE ALSO +.Xr ithread 9 , +.Xr kthread 9 , +.Xr swi 9 +.Sh HISTORY +This interface first appeared in +.Fx 5.0 . +There is a similar facility called work_queue in the Linux kernel. +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/taskqueue.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/Makefile.depend =================================================================== --- user/imp/camdoc/Makefile.depend (nonexistent) +++ user/imp/camdoc/Makefile.depend (revision 296049) @@ -0,0 +1,11 @@ +# $FreeBSD$ +# Autogenerated - do NOT edit! + +DIRDEPS = \ + + +.include + +.if ${DEP_RELDIR} == ${_DEP_RELDIR} +# local dependencies - needed for -jN in clean tree +.endif Property changes on: user/imp/camdoc/Makefile.depend ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/PCI_IOV_UNINIT.9 =================================================================== --- user/imp/camdoc/PCI_IOV_UNINIT.9 (nonexistent) +++ user/imp/camdoc/PCI_IOV_UNINIT.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2014 Sandvine 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 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 28, 2015 +.Dt PCI_IOV_UNINIT 9 +.Os +.Sh NAME +.Nm PCI_IOV_UNINIT +.Nd disable SR-IOV on a PF device +.Sh SYNOPSIS +.In sys/bus.h +.In dev/pci/pci_iov.h +.Ft void +.Fn PCI_IOV_UNINIT "device_t dev" +.Sh DESCRIPTION +The +.Fn PCI_IOV_UNINIT +method is called by the PCI Single-Root I/O Virtualization (SR-IOV) +infrastructure when the user requests that SR-IOV be disabled on a Physical +Function (PF). +When this method is called, the PF driver must release any SR-IOV-related +resources that it has allocated and disable any device-specific SR-IOV +configuration in the device. +.Pp +This method will only be called following a successful call to +.Xr PCI_IOV_INIT . +It is not guaranteed that +.Xr PCI_IOV_ADD_VF +will have been called for any Virtual Function (VF) after the call to +.Xr PCI_IOV_INIT +and before the call to +.Nm . +.Sh SEE ALSO +.Xr pci 9 , +.Xr PCI_IOV_ADD_VF 9 , +.Xr PCI_IOV_INIT 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq Mt rstone@FreeBSD.org . Property changes on: user/imp/camdoc/PCI_IOV_UNINIT.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/sleep.9 =================================================================== --- user/imp/camdoc/sleep.9 (nonexistent) +++ user/imp/camdoc/sleep.9 (revision 296049) @@ -0,0 +1,373 @@ +.\" +.\" Copyright (c) 1996 Joerg Wunsch +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE 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 May 24, 2015 +.Dt SLEEP 9 +.Os +.Sh NAME +.Nm msleep , +.Nm msleep_sbt , +.Nm msleep_spin , +.Nm msleep_spin_sbt , +.Nm pause , +.Nm pause_sbt , +.Nm tsleep , +.Nm tsleep_sbt , +.Nm wakeup +.Nd wait for events +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/proc.h +.Ft int +.Fn msleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn msleep_sbt "void *chan" "struct mtx *mtx" "int priority" \ +"const char *wmesg" "sbintime_t sbt" "sbintime_t pr" "int flags" +.Ft int +.Fn msleep_spin "void *chan" "struct mtx *mtx" "const char *wmesg" "int timo" +.Ft int +.Fn msleep_spin_sbt "void *chan" "struct mtx *mtx" "const char *wmesg" \ +"sbintime_t sbt" "sbintime_t pr" "int flags" +.Ft void +.Fn pause "const char *wmesg" "int timo" +.Ft void +.Fn pause_sbt "const char *wmesg" "sbintime_t sbt" "sbintime_t pr" \ + "int flags" +.Ft int +.Fn tsleep "void *chan" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn tsleep_sbt "void *chan" "int priority" "const char *wmesg" \ +"sbintime_t sbt" "sbintime_t pr" "int flags" +.Ft void +.Fn wakeup "void *chan" +.Ft void +.Fn wakeup_one "void *chan" +.Sh DESCRIPTION +The functions +.Fn tsleep , +.Fn msleep , +.Fn msleep_spin , +.Fn pause , +.Fn wakeup , +and +.Fn wakeup_one +handle event-based thread blocking. +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 , +often called from inside an interrupt routine, to indicate that the +resource the thread was blocking on is available now. +.Pp +The parameter +.Fa priority +specifies a new priority for the thread as well as some optional flags. +If the new priority is not 0, +then the thread will be made +runnable with the specified +.Fa priority +when it resumes. +.Dv PZERO +should never be used, as it is for compatibility only. +A new priority of 0 means to use the thread's current priority when +it is made runnable again. +.Pp +If +.Fa priority +includes the +.Dv PCATCH +flag, pending signals are allowed to interrupt the sleep, otherwise +pending signals are ignored during the sleep. +If +.Dv PCATCH +is set and a signal becomes pending, +.Er ERESTART +is returned if the current system call should be restarted if +possible, and +.Er EINTR +is returned if the system call should be interrupted by the signal +(return +.Er EINTR ) . +.Pp +The parameter +.Fa wmesg +is a string describing the sleep condition for tools like +.Xr ps 1 . +Due to the limited space of those programs to display arbitrary strings, +this message should not be longer than 6 characters. +.Pp +The parameter +.Fa timo +specifies a timeout for the sleep. +If +.Fa timo +is not 0, +then the thread will sleep for at most +.Fa timo No / Va hz +seconds. +If the timeout expires, +then the sleep function will return +.Er EWOULDBLOCK . +.Pp +.Fn msleep_sbt , +.Fn msleep_spin_sbt , +.Fn pause_sbt +and +.Fn tsleep_sbt +functions take +.Fa sbt +parameter instead of +.Fa timo . +It allows the caller to specify relative or absolute wakeup time with higher resolution +in form of +.Vt sbintime_t . +The parameter +.Fa pr +allows the caller to specify wanted absolute event precision. +The parameter +.Fa flags +allows the caller to pass additional +.Fn callout_reset_sbt +flags. +.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 +(even if recursed) +while the thread is suspended and will reacquire the +.Va Giant +mutex before the function returns. +Note that the +.Va Giant +mutex may be specified as the lock to drop. +In that case, however, the +.Dv PDROP +flag is not allowed. +.Pp +To avoid lost wakeups, +either a lock should be used to protect against races, +or a timeout should be specified to place an upper bound on the delay due +to a lost wakeup. +As a result, +the +.Fn tsleep +function should only be invoked with a timeout of 0 when the +.Va Giant +mutex is held. +.Pp +The +.Fn msleep +function requires that +.Fa mtx +reference a default, i.e. non-spin, mutex. +Its use is deprecated in favor of +.Xr mtx_sleep 9 +which provides identical behavior. +.Pp +The +.Fn msleep_spin +function requires that +.Fa mtx +reference a spin mutex. +The +.Fn msleep_spin +function does not accept a +.Fa priority +parameter and thus does not support changing the current thread's priority, +the +.Dv PDROP +flag, +or catching signals via the +.Dv PCATCH +flag. +.Pp +The +.Fn pause +function is a wrapper around +.Fn tsleep +that suspends execution of the current thread for the indicated timeout. +The thread can not be awakened early by signals or calls to +.Fn wakeup +or +.Fn wakeup_one . +.Pp +The +.Fn wakeup_one +function makes the first thread in the queue that is sleeping on the +parameter +.Fa chan +runnable. +This reduces the load when a large number of threads are sleeping on +the same address, but only one of them can actually do any useful work +when made runnable. +.Pp +Due to the way it works, the +.Fn wakeup_one +function requires that only related threads sleep on a specific +.Fa chan +address. +It is the programmer's responsibility to choose a unique +.Fa chan +value. +The older +.Fn wakeup +function did not require this, though it was never good practice +for threads to share a +.Fa chan +value. +When converting from +.Fn wakeup +to +.Fn wakeup_one , +pay particular attention to ensure that no other threads wait on the +same +.Fa chan . +.Sh RETURN VALUES +When awakened by a call to +.Fn wakeup +or +.Fn wakeup_one , +if a signal is pending and +.Dv PCATCH +is specified, +a non-zero error code is returned. +If the thread is awakened by a call to +.Fn wakeup +or +.Fn wakeup_one , +the +.Fn msleep , +.Fn msleep_spin , +.Fn tsleep , +and locking primitive sleep functions return 0. +Otherwise, a non-zero error code is returned. +.Sh ERRORS +.Fn msleep , +.Fn msleep_spin , +.Fn tsleep , +and the locking primitive sleep functions will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +The +.Dv PCATCH +flag was specified, a signal was caught, and the system call should be +interrupted. +.It Bq Er ERESTART +The +.Dv PCATCH +flag was specified, a signal was caught, and the system call should be +restarted. +.It Bq Er EWOULDBLOCK +A non-zero timeout was specified and the timeout expired. +.El +.Sh SEE ALSO +.Xr ps 1 , +.Xr locking 9 , +.Xr malloc 9 , +.Xr mi_switch 9 , +.Xr mtx_sleep 9 , +.Xr rw_sleep 9 , +.Xr sx_sleep 9 , +.Xr timeout 9 +.Sh HISTORY +The functions +.Fn sleep +and +.Fn wakeup +were present in +.At v1 . +They were probably also present in the preceding +PDP-7 version of +.Ux . +They were the basic process synchronization model. +.Pp +The +.Fn tsleep +function appeared in +.Bx 4.4 +and added the parameters +.Fa wmesg +and +.Fa timo . +The +.Fn sleep +function was removed in +.Fx 2.2 . +The +.Fn wakeup_one +function appeared in +.Fx 2.2 . +The +.Fn msleep +function appeared in +.Fx 5.0 , +and the +.Fn msleep_spin +function appeared in +.Fx 6.2 . +The +.Fn pause +function appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An J\(:org Wunsch Aq Mt joerg@FreeBSD.org . Property changes on: user/imp/camdoc/sleep.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/psignal.9 =================================================================== --- user/imp/camdoc/psignal.9 (nonexistent) +++ user/imp/camdoc/psignal.9 (revision 296049) @@ -0,0 +1,165 @@ +.\" 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. +.\" +.\" $NetBSD: psignal.9,v 1.1 1996/06/22 22:57:35 pk Exp $ +.\" $FreeBSD$ +.\" +.Dd October 8, 2011 +.Dt PSIGNAL 9 +.Os +.Sh NAME +.Nm psignal , +.Nm kern_psignal , +.Nm pgsignal , +.Nm gsignal , +.Nm tdsignal +.Nd post signal to a thread, process, or process group +.Sh SYNOPSIS +.In sys/types.h +.In sys/signalvar.h +.Ft void +.Fn kern_psignal "struct proc *p" "int signum" +.Ft void +.Fn pgsignal "struct pgrp *pgrp" "int signum" "int checkctty" +.Ft void +.Fn gsignal "int pgid" "int signum" +.Ft void +.Fn tdsignal "struct thread *td" "int signum" +.Sh DESCRIPTION +These functions post a signal to a thread or one or more processes. +The argument +.Fa signum +common to all three functions should be in the range +.Bq 1- Ns Dv NSIG . +.Pp +The +.Fn kern_psignal +function posts signal number +.Fa signum +to the process represented by the process structure +.Fa p . +The +.Fn kern_psignal +function used to be called +.Fn psignal +but was renamed in order to eliminate a name collision with the libc +function of that name and facilitate code reuse. +With a few exceptions noted below, the target process signal disposition is +updated and is marked as runnable, so further handling of the signal is done +in the context of the target process after a context switch. +Note that +.Fn kern_psignal +does not by itself cause a context switch to happen. +.Pp +The target process is not marked as runnable in the following cases: +.Bl -bullet -offset indent +.It +The target process is sleeping uninterruptibly. +The signal will be +noticed when the process returns from the system call or trap. +.It +The target process is currently ignoring the signal. +.It +If a stop signal is sent to a sleeping process that takes the +default action +(see +.Xr sigaction 2 ) , +the process is stopped without awakening it. +.It +.Dv SIGCONT +restarts a stopped process +(or puts them back to sleep) +regardless of the signal action +(e.g., blocked or ignored). +.El +.Pp +If the target process is being traced +.Fn kern_psignal +behaves as if the target process were taking the default action for +.Fa signum . +This allows the tracing process to be notified of the signal. +.Pp +The +.Fn pgsignal +function posts signal number +.Fa signum +to each member of the process group described by +.Fa pgrp . +If +.Fa checkctty +is non-zero, the signal will be posted only to processes that have +a controlling terminal. +.Fn pgsignal +is implemented by walking along the process list headed by the field +.Li pg_members +of the process group structure +pointed at by +.Fa pgrp +and calling +.Fn kern_psignal +as appropriate. +If +.Fa pgrp +is +.Dv NULL +no action is taken. +.Pp +The +.Fn gsignal +function posts signal number +.Fa signum +to each member of the process group identified by the group id +.Fa pgid . +.Fn gsignal +first finds the group structure associated with +.Fa pgid , +then invokes +.Fn pgsignal +with the argument +.Fa checkctty +set to zero. +If +.Fa pgid +is zero no action is taken. +.Pp +The +.Fn tdsignal +function posts signal number +.Fa signum +to the thread represented by the thread structure +.Fa td . +.Sh SEE ALSO +.Xr sigaction 2 , +.Xr signal 9 , +.Xr tsleep 9 +.Sh HISTORY +The +.Fn psignal +function was renamed to +.Fn kern_psignal +in +.Fx 9.0 . Property changes on: user/imp/camdoc/psignal.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/namei.9 =================================================================== --- user/imp/camdoc/namei.9 (nonexistent) +++ user/imp/camdoc/namei.9 (revision 296049) @@ -0,0 +1,351 @@ +.\" +.\" Copyright (c) 1998, 1999 Eivind Eklund +.\" Copyright (c) 2003 Hiten M. Pandya +.\" Copyright (c) 2005 Robert N. M. Watson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.\" If you integrate this manpage in another OS, I'd appreciate a note +.\" - eivind@FreeBSD.org +.\" +.\" $FreeBSD$ +.\" +.Dd May 6, 2015 +.Dt NAMEI 9 +.Os +.Sh NAME +.Nm namei , +.Nm NDINIT , +.Nm NDFREE , +.Nd pathname translation and lookup operations +.Sh SYNOPSIS +.In sys/param.h +.In sys/fcntl.h +.In sys/namei.h +.Ft int +.Fn namei "struct nameidata *ndp" +.Ft void +.Fo NDINIT +.Fa "struct nameidata *ndp" "u_long op" "u_long flags" +.Fa "enum uio_seg segflg" "const char *namep" "struct thread *td" +.Fc +.Ft void +.Fn NDFREE "struct nameidata *ndp" "const uint flags" +.Sh DESCRIPTION +The +.Nm +facility allows the client to perform pathname translation and lookup +operations. +The +.Nm +functions will increment the reference count for the vnode in question. +The reference count has to be decremented after use of the vnode, by +using either +.Xr vrele 9 +or +.Xr vput 9 , +depending on whether the +.Dv LOCKLEAF +flag was specified or not. +.Pp +The +.Fn NDINIT +function is used to initialize +.Nm +components. +It takes the following arguments: +.Bl -tag -width ".Fa segflg" +.It Fa ndp +The +.Vt "struct nameidata" +to initialize. +.It Fa op +The operation which +.Fn namei +will perform. +The following operations are valid: +.Dv LOOKUP , CREATE , DELETE , +and +.Dv RENAME . +The latter three are just setup for those +effects; just calling +.Fn namei +will not result in +.Fn VOP_RENAME +being called. +.It Fa flags +Operation flags. +Several of these can be effective at the same time. +.It Fa segflg +UIO segment indicator. +This indicates if the name of the object is in userspace +.Pq Dv UIO_USERSPACE +or in the kernel address space +.Pq Dv UIO_SYSSPACE . +.It Fa namep +Pointer to the component's pathname buffer +(the file or directory name that will be looked up). +.It Fa td +The thread context to use for +.Nm +operations and locks. +.El +.Sh NAMEI OPERATION FLAGS +The +.Fn namei +function takes the following set of +.Dq "operation flags" +that influence its operation: +.Bl -tag -width ".Dv WANTPARENT" +.It Dv LOCKLEAF +Lock vnode on return. +This is a full lock of the vnode; the +.Xr VOP_UNLOCK 9 +should be used +to release the lock (or +.Xr vput 9 +which is equivalent to calling +.Xr VOP_UNLOCK 9 +followed by +.Xr vrele 9 , +all in one). +.It Dv LOCKPARENT +This flag lets the +.Fn namei +function return the parent (directory) vnode, +.Va ni_dvp +in locked state, unless it is identical to +.Va ni_vp , +in which case +.Va ni_dvp +is not locked per se (but may be locked due to +.Dv LOCKLEAF ) . +If a lock is enforced, it should be released using +.Xr vput 9 +or +.Xr VOP_UNLOCK 9 +and +.Xr vrele 9 . +.It Dv WANTPARENT +This flag allows the +.Fn namei +function to return the parent (directory) vnode in an unlocked state. +The parent vnode must be released separately by using +.Xr vrele 9 . +.It Dv NOCACHE +Avoid +.Fn namei +creating this entry in the namecache if it is not +already present. +Normally, +.Fn namei +will add entries to the name cache +if they are not already there. +.It Dv FOLLOW +With this flag, +.Fn namei +will follow the symbolic link if the last part +of the path supplied is a symbolic link (i.e., it will return a vnode +for whatever the link points at, instead for the link itself). +.It Dv NOFOLLOW +Do not follow symbolic links (pseudo). +This flag is not looked for by the actual code, which looks for +.Dv FOLLOW . +.Dv NOFOLLOW +is used to indicate to the source code reader that symlinks +are intentionally not followed. +.It Dv SAVENAME +Do not free the pathname buffer at the end of the +.Fn namei +invocation; instead, free it later in +.Fn NDFREE +so that the caller may access the pathname buffer. +See below for details. +.It Dv SAVESTART +Retain an additional reference to the parent directory; do not free +the pathname buffer. +See below for details. +.El +.Sh ALLOCATED ELEMENTS +The +.Vt nameidata +structure is composed of the following fields: +.Bl -tag -width ".Va ni_cnd.cn_pnbuf" +.It Va ni_startdir +In the normal case, this is either the current directory or the root. +It is the current directory if the name passed in does not start with +.Ql / +and we have not gone through any symlinks with an absolute path, and +the root otherwise. +.Pp +In this case, it is only used by +.Fn lookup , +and should not be +considered valid after a call to +.Fn namei . +If +.Dv SAVESTART +is set, this is set to the same as +.Va ni_dvp , +with an extra +.Xr vref 9 . +To block +.Fn NDFREE +from releasing +.Va ni_startdir , +the +.Dv NDF_NO_STARTDIR_RELE +can be set. +.It Va ni_dvp +Vnode pointer to directory of the object on which lookup is performed. +This is available on successful return if +.Dv LOCKPARENT +or +.Dv WANTPARENT +is set. +It is locked if +.Dv LOCKPARENT +is set. +Freeing this in +.Fn NDFREE +can be inhibited by +.Dv NDF_NO_DVP_RELE , NDF_NO_DVP_PUT , +or +.Dv NDF_NO_DVP_UNLOCK +(with the obvious effects). +.It Va ni_vp +Vnode pointer to the resulting object, +.Dv NULL +otherwise. +The +.Va v_usecount +field of this vnode is incremented. +If +.Dv LOCKLEAF +is set, it is also locked. +.Pp +Freeing this in +.Fn NDFREE +can be inhibited by +.Dv NDF_NO_VP_RELE , NDF_NO_VP_PUT , +or +.Dv NDF_NO_VP_UNLOCK +(with the obvious effects). +.It Va ni_cnd.cn_pnbuf +The pathname buffer contains the location of the file or directory +that will be used by the +.Nm +operations. +It is managed by the +.Xr uma 9 +zone allocation interface. +If the +.Dv SAVESTART +or +.Dv SAVENAME +flag is set, then the pathname buffer is available +after calling the +.Fn namei +function. +.Pp +To only deallocate resources used by the pathname buffer, +.Va ni_cnd.cn_pnbuf , +then +.Dv NDF_ONLY_PNBUF +flag can be passed to the +.Fn NDFREE +function. +To keep the pathname buffer intact, +the +.Dv NDF_NO_FREE_PNBUF +flag can be passed to the +.Fn NDFREE +function. +.El +.Sh RETURN VALUES +If successful, +.Fn namei +will return 0, otherwise it will return an error. +.Sh FILES +.Bl -tag -width Pa +.It Pa src/sys/kern/vfs_lookup.c +.El +.Sh ERRORS +Errors which +.Fn namei +may return: +.Bl -tag -width Er +.It Bq Er ENOTDIR +A component of the specified pathname is not a directory when a directory is +expected. +.It Bq Er ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire pathname exceeded 1023 characters. +.It Bq Er ENOENT +A component of the specified pathname does not exist, +or the pathname is an empty string. +.It Bq Er EACCES +An attempt is made to access a file in a way forbidden by its file access +permissions. +.It Bq Er ELOOP +Too many symbolic links were encountered in translating the pathname. +.It Bq Er EISDIR +An attempt is made to open a directory with write mode specified. +.It Bq Er EINVAL +The last component of the pathname specified for a +.Dv DELETE +or +.Dv RENAME +operation is +.Ql \&. . +.It Bq Er EROFS +An attempt is made to modify a file or directory on a read-only file system. +.El +.Sh SEE ALSO +.Xr uio 9 , +.Xr uma 9 , +.Xr VFS 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vref 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Eivind Eklund Aq Mt eivind@FreeBSD.org +and later significantly revised by +.An Hiten M. Pandya Aq Mt hmp@FreeBSD.org . +.Sh BUGS +The +.Dv LOCKPARENT +flag does not always result in the parent vnode being locked. +This results in complications when the +.Dv LOCKPARENT +is used. +In order to solve this for the cases where both +.Dv LOCKPARENT +and +.Dv LOCKLEAF +are used, it is necessary to resort to recursive locking. Property changes on: user/imp/camdoc/namei.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/panic.9 =================================================================== --- user/imp/camdoc/panic.9 (nonexistent) +++ user/imp/camdoc/panic.9 (revision 296049) @@ -0,0 +1,74 @@ +.\" $NetBSD: panic.9,v 1.2 1996/10/09 17:20:04 explorer Exp $ +.\" +.\" Copyright (c) 1996 Michael Graff. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Michael Graff +.\" for the NetBSD Project. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 23, 2015 +.Dt PANIC 9 +.Os +.Sh NAME +.Nm panic +.Nd bring down system on fatal error +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn panic "const char *fmt" ... +.Ft void +.Fn vpanic "const char *fmt" "va_list ap" +.Sh DESCRIPTION +The +.Fn panic +and +.Fn vpanic +functions terminate the running system. +The message +.Fa fmt +is a +.Xr printf 3 +style format string. +The message is printed to the console and the location +.Fa panicstr +is set to the address of the message text for retrieval from the OS +core dump. +.Pp +If the kernel debugger is installed control is passed to it, otherwise +an attempt to save a core dump of the OS to a configured dump device +is made. +.Pp +If +.Fn panic +is called twice (from the disk sync routines, for example) the system is +rebooted without syncing the disks. +.Sh RETURN VALUES +The +.Fn panic +function does not return. Property changes on: user/imp/camdoc/panic.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUS_BIND_INTR.9 =================================================================== --- user/imp/camdoc/BUS_BIND_INTR.9 (nonexistent) +++ user/imp/camdoc/BUS_BIND_INTR.9 (revision 296049) @@ -0,0 +1,98 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 14, 2009 +.Dt BUS_BIND_INTR 9 +.Os +.Sh NAME +.Nm BUS_BIND_INTR , +.Nm bus_bind_intr +.Nd "bind an interrupt resource to a specific CPU" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fo BUS_BIND_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "int cpu" +.Fc +.Ft int +.Fn bus_bind_intr "device_t dev" "struct resource *irq" "int cpu" +.Sh DESCRIPTION +The +.Fn BUS_BIND_INTR +method allows an interrupt resource to be pinned to a specific CPU. +The interrupt resource must have an interrupt handler attached via +.Xr BUS_SETUP_INTR 9 . +The +.Fa cpu +parameter corresponds to the ID of a valid CPU in the system. +Binding an interrupt restricts the +.Xr cpuset 2 +of any associated interrupt threads to only include the specified CPU. +It may also direct the low-level interrupt handling of the interrupt to the +specified CPU as well, +but this behavior is platform-dependent. +If the value +.Dv NOCPU +is used for +.Fa cpu , +then the interrupt will be +.Dq unbound +which restores any associated interrupt threads back to the default cpuset. +.Pp +Non-sleepable locks such as mutexes should not be held across calls to these +functions. +.Pp +The +.Fn bus_bind_intr +function is a simple wrapper around +.Fn BUS_BIND_INTR . +.Pp +Note that currently there is no attempt made to arbitrate between +multiple bind requests for the same interrupt from either the same +device or multiple devices. +There is also no arbitration between interrupt binding requests submitted +by userland via +.Xr cpuset 2 +and +.Fn BUS_BIND_INTR . +The most recent binding request is the one that will be in effect. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr cpuset 2 , +.Xr BUS_SETUP_INTR 9 , +.Xr device 9 +.Sh HISTORY +The +.Fn BUS_BIND_INTR +method and +.Fn bus_bind_intr +functions first appeared in +.Fx 7.2 . Property changes on: user/imp/camdoc/BUS_BIND_INTR.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/BUS_CHILD_DELETED.9 =================================================================== --- user/imp/camdoc/BUS_CHILD_DELETED.9 (nonexistent) +++ user/imp/camdoc/BUS_CHILD_DELETED.9 (revision 296049) @@ -0,0 +1,55 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2012 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 21, 2012 +.Dt BUS_CHILD_DELETED 9 +.Os +.Sh NAME +.Nm BUS_CHILD_DELETED +.Nd "notify a bus device that a child is being deleted" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_CHILD_DELETED "device_t dev" "device_t child" +.Sh DESCRIPTION +The +.Fn BUS_CHILD_DELETED +method is invoked by the new-bus framework when a device is deleted. +A bus driver can provide an implementation of this method to +release bus-specific resources associated with a device such as +instance variables. +.Sh SEE ALSO +.Xr BUS_ADD_CHILD 9 , +.Xr device 9 +.Sh HISTORY +The +.Fn BUS_CHILD_DELETED +method first appeared in +.Fx 10.0 . Property changes on: user/imp/camdoc/BUS_CHILD_DELETED.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/BUS_CHILD_DETACHED.9 =================================================================== --- user/imp/camdoc/BUS_CHILD_DETACHED.9 (nonexistent) +++ user/imp/camdoc/BUS_CHILD_DETACHED.9 (revision 296049) @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2012 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 21, 2012 +.Dt BUS_CHILD_DETACHED 9 +.Os +.Sh NAME +.Nm BUS_CHILD_DETACHED +.Nd "notify a bus device that a child was detached" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_CHILD_DETACHED "device_t dev" "device_t child" +.Sh DESCRIPTION +The +.Fn BUS_CHILD_DETACHED +method is invoked by the new-bus framework after a device is detached. +A bus driver can provide an implementation of this method to +reclaim any resources allocated on behalf of the child or +to cleanup state not properly released by a +.Xr DEVICE_DETACH 9 +method. +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_DETACH 9 Property changes on: user/imp/camdoc/BUS_CHILD_DETACHED.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/BUS_NEW_PASS.9 =================================================================== --- user/imp/camdoc/BUS_NEW_PASS.9 (nonexistent) +++ user/imp/camdoc/BUS_NEW_PASS.9 (revision 296049) @@ -0,0 +1,56 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 8, 2009 +.Dt BUS_NEW_PASS 9 +.Os +.Sh NAME +.Nm BUS_NEW_PASS +.Nd "notify a bus that the pass level has been changed" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn BUS_NEW_PASS "device_t dev" +.Sh DESCRIPTION +The +.Fn BUS_NEW_PASS +method is called on each bus device to rescan the device tree when the pass +level has been changed. +This method is responsible for invoking +.Xr BUS_NEW_PASS 9 +on child bus devices to propagate the rescan to child devices. +It is also responsible for reprobing any unattached child devices and +allowing drivers for the current pass to identify new children. +A default implementation is provided by +.Xr bus_generic_new_pass 9 . +.Sh SEE ALSO +.Xr bus_generic_new_pass 9 , +.Xr bus_set_pass 9 , +.Xr device 9 Property changes on: user/imp/camdoc/BUS_NEW_PASS.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/VOP_ALLOCATE.9 =================================================================== --- user/imp/camdoc/VOP_ALLOCATE.9 (nonexistent) +++ user/imp/camdoc/VOP_ALLOCATE.9 (revision 296049) @@ -0,0 +1,84 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2013 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 3, 2013 +.Dt VOP_ALLOCATE 9 +.Os +.Sh NAME +.Nm VOP_ALLOCATE +.Nd allocate storage for a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_ALLOCATE "struct vnode *vp" "off_t *offset" "off_t *len" +.Sh DESCRIPTION +This call allocates storage for a range of offsets in a file. +It is used to implement the +.Xr posix_fallocate +system call. +.Pp +Its arguments are: +.Bl -tag -width offset +.It Fa vp +The vnode of the file. +.It Fa offset +The start of the range to allocate storage for in the file. +.It Fa len +The length of the range to allocate storage for in the file. +.El +.Pp +The +.Fa offset +and +.Fa len +arguments are updated to reflect the portion of the range that +still needs to be allocated on return. +A partial allocation is considered a successful operation. +The file's contents are not changed. +.Sh LOCKS +The file should be exclusively locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned if the call is successful, otherwise an appropriate +error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFBIG +An attempt was made to write a file that exceeds the process's file size +limit or the maximum file size. +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EPERM +An append-only flag is set on the file, but the caller is attempting to +write before the current end of file. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_READ 9 , +.Xr VOP_WRITE 9 Property changes on: user/imp/camdoc/VOP_ALLOCATE.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/bus_generic_new_pass.9 =================================================================== --- user/imp/camdoc/bus_generic_new_pass.9 (nonexistent) +++ user/imp/camdoc/bus_generic_new_pass.9 (revision 296049) @@ -0,0 +1,57 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 8, 2009 +.Dt BUS_GENERIC_NEW_PASS 9 +.Os +.Sh NAME +.Nm bus_generic_new_pass +.Nd "generic implementation of BUS_NEW_PASS for bus devices" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn bus_generic_new_pass "device_t dev" +.Sh DESCRIPTION +This function provides an implementation of the +.Xr BUS_NEW_PASS 9 +method which can be used by bus drivers. +It first invokes the +.Xr DEVICE_IDENTIFY 9 +method for any drivers whose pass level is equal to the new pass level. +Then, for each attached child device it calls +.Xr BUS_NEW_PASS 9 +to rescan child busses, +and for each unattached child device it calls +.Xr device_probe_and_attach 9 . +.Sh SEE ALSO +.Xr BUS_NEW_PASS 9 , +.Xr bus_set_pass 9 , +.Xr device 9 , +.Xr DEVICE_IDENTIFY 9 Property changes on: user/imp/camdoc/bus_generic_new_pass.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/bus_set_pass.9 =================================================================== --- user/imp/camdoc/bus_set_pass.9 (nonexistent) +++ user/imp/camdoc/bus_set_pass.9 (revision 296049) @@ -0,0 +1,54 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 8, 2009 +.Dt BUS_SET_PASS 9 +.Os +.Sh NAME +.Nm bus_set_pass +.Nd "raise the bus pass level" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn bus_set_pass "int pass" +.Sh DESCRIPTION +The +.Nm +function is called during boot to raise the bus pass level to +.Fa pass . +The function will rescan the device tree for each pass level between the +current pass level and the new level that has at least one associated +driver. +The device tree rescans are implemented by invoking the +.Xr BUS_NEW_PASS 9 +method on the root bus device. +.Sh SEE ALSO +.Xr BUS_NEW_PASS 9 , +.Xr device 9 Property changes on: user/imp/camdoc/bus_set_pass.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/refcount.9 =================================================================== --- user/imp/camdoc/refcount.9 (nonexistent) +++ user/imp/camdoc/refcount.9 (revision 296049) @@ -0,0 +1,96 @@ +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 20, 2009 +.Dt REFCOUNT 9 +.Os +.Sh NAME +.Nm refcount , +.Nm refcount_init , +.Nm refcount_acquire , +.Nm refcount_release +.Nd manage a simple reference counter +.Sh SYNOPSIS +.In sys/param.h +.In sys/refcount.h +.Ft void +.Fn refcount_init "volatile u_int *count" "u_int value" +.Ft void +.Fn refcount_acquire "volatile u_int *count" +.Ft int +.Fn refcount_release "volatile u_int *count" +.Sh DESCRIPTION +The +.Nm +functions provide an API to manage a simple reference counter. +The caller provides the storage for the counter in an unsigned integer. +A pointer to this integer is passed via +.Fa count . +Usually the counter is used to manage the lifetime of an object and is +stored as a member of the object. +.Pp +The +.Fn refcount_init +function is used to set the initial value of the counter to +.Fa value . +It is normally used when creating a reference-counted object. +.Pp +The +.Fn refcount_acquire +function is used to acquire a new reference. +The caller is responsible for ensuring that it holds a valid reference +while obtaining a new reference. +For example, +if an object is stored on a list and the list holds a reference on the +object, then holding a lock that protects the list provides sufficient +protection for acquiring a new reference. +.Pp +The +.Fn refcount_release +function is used to release an existing reference. +The function returns a non-zero value if the reference being released was +the last reference; +otherwise, it returns zero. +.Pp +Note that these routines do not provide any inter-CPU synchronization, +data protection, +or memory ordering guarantees except for managing the counter. +The caller is responsible for any additional synchronization needed by +consumers of any containing objects. +In addition, +the caller is also responsible for managing the life cycle of any containing +objects including explicitly releasing any resources when the last reference +is released. +.Sh RETURN VALUES +The +.Nm refcount_release +function returns non-zero when releasing the last reference and zero when +releasing any other reference. +.Sh HISTORY +These functions were introduced in +.Fx 6.0 . Property changes on: user/imp/camdoc/refcount.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/sglist.9 =================================================================== --- user/imp/camdoc/sglist.9 (nonexistent) +++ user/imp/camdoc/sglist.9 (revision 296049) @@ -0,0 +1,518 @@ +.\" +.\" Copyright (c) 2009 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 12, 2014 +.Dt SGLIST 9 +.Os +.Sh NAME +.Nm sglist , +.Nm sglist_alloc , +.Nm sglist_append , +.Nm sglist_append_bio , +.Nm sglist_append_mbuf , +.Nm sglist_append_phys , +.Nm sglist_append_uio , +.Nm sglist_append_user , +.Nm sglist_build , +.Nm sglist_clone , +.Nm sglist_consume_uio , +.Nm sglist_count , +.Nm sglist_free , +.Nm sglist_hold , +.Nm sglist_init , +.Nm sglist_join , +.Nm sglist_length , +.Nm sglist_reset , +.Nm sglist_slice , +.Nm sglist_split +.Nd manage a scatter/gather list of physical memory addresses +.Sh SYNOPSIS +.In sys/types.h +.In sys/sglist.h +.Ft struct sglist * +.Fn sglist_alloc "int nsegs" "int mflags" +.Ft int +.Fn sglist_append "struct sglist *sg" "void *buf" "size_t len" +.Ft int +.Fn sglist_append_bio "struct sglist *sg" "struct bio *bp" +.Ft int +.Fn sglist_append_mbuf "struct sglist *sg" "struct mbuf *m" +.Ft int +.Fn sglist_append_phys "struct sglist *sg" "vm_paddr_t paddr" "size_t len" +.Ft int +.Fn sglist_append_uio "struct sglist *sg" "struct uio *uio" +.Ft int +.Fn sglist_append_user "struct sglist *sg" "void *buf" "size_t len" "struct thread *td" +.Ft struct sglist * +.Fn sglist_build "void *buf" "size_t len" "int mflags" +.Ft struct sglist * +.Fn sglist_clone "struct sglist *sg" "int mflags" +.Ft int +.Fn sglist_consume_uio "struct sglist *sg" "struct uio *uio" "size_t resid" +.Ft int +.Fn sglist_count "void *buf" "size_t len" +.Ft void +.Fn sglist_free "struct sglist *sg" +.Ft struct sglist * +.Fn sglist_hold "struct sglist *sg" +.Ft void +.Fn sglist_init "struct sglist *sg" "int maxsegs" "struct sglist_seg *segs" +.Ft int +.Fn sglist_join "struct sglist *first" "struct sglist *second" +.Ft size_t +.Fn sglist_length "struct sglist *sg" +.Ft void +.Fn sglist_reset "struct sglist *sg" +.Ft int +.Fn sglist_slice "struct sglist *original" "struct sglist **slice" "size_t offset" "size_t length" "int mflags" +.Ft int +.Fn sglist_split "struct sglist *original" "struct sglist **head" "size_t length" "int mflags" +.Sh DESCRIPTION +The +.Nm +API manages physical address ranges. +Each list contains one or more elements. +Each element contains a starting physical address and a length. +Scatter/gather lists are read-only while they are shared. +If one wishes to alter an existing scatter/gather list and does not hold the +sole reference to the list, +then one should create a new list instead of modifying the existing list. +.Pp +Each scatter/gather list object contains a reference count. +New lists are created with a single reference. +New references are obtained by calling +.Nm sglist_hold +and are released by calling +.Nm sglist_free . +.Ss Allocating and Initializing Lists +Each +.Nm +object consists of a header structure and a variable-length array of +scatter/gather list elements. +The +.Nm sglist_alloc +function allocates a new list that contains a header and +.Fa nsegs +scatter/gather list elements. +The +.Fa mflags +argument can be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +.Pp +The +.Nm sglist_count +function returns the number of scatter/gather list elements needed to describe +the physical address ranges mapped by a single kernel virtual address range. +The kernel virtual address range starts at +.Fa buf +and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_build +function allocates a new scatter/gather list object that describes the physical +address ranges mapped by a single kernel virtual address range. +The kernel virtual address range starts at +.Fa buf +and is +.Fa len +bytes long. +The +.Fa mflags +argument can be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +.Pp +The +.Nm sglist_clone +function returns a copy of an existing scatter/gather list object +.Fa sg . +The +.Fa mflags +argument can be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +This can be used to obtain a private copy of a scatter/gather list before +modifying it. +.Pp +The +.Nm sglist_init +function initializes a scatter/gather list header. +The header is pointed to by +.Fa sg +and is initialized to manage an array of +.Fa maxsegs +scatter/gather list elements pointed to by +.Fa segs . +This can be used to initialize a scatter/gather list header whose storage +is not provided by +.Nm sglist_alloc . +In that case, the caller should not call +.Nm sglist_free +to release its own reference and is responsible for ensuring all other +references to the list are dropped before it releases the storage for +.Fa sg +and +.Fa segs . +.Ss Constructing Scatter/Gather Lists +The +.Nm +API provides several routines for building a scatter/gather list to describe +one or more objects. +Specifically, the +.Nm sglist_append +family of routines can be used to append the physical address ranges described +by an object to the end of a scatter/gather list. +All of these routines return 0 on success or an error on failure. +If a request to append an address range to a scatter/gather list fails, +the scatter/gather list will remain unchanged. +.Pp +The +.Nm sglist_append +function appends the physical address ranges described by a single kernel +virtual address range to the scatter/gather list +.Fa sg . +The kernel virtual address range starts at +.Fa buf +and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_append_bio +function appends the physical address ranges described by a single bio +.Fa bp +to the scatter/gather list +.Fa sg . +.Pp +The +.Nm sglist_append_mbuf +function appends the physical address ranges described by an entire mbuf +chain +.Fa m +to the scatter/gather list +.Fa sg . +.Pp +The +.Nm sglist_append_phys +function appends a single physical address range to the scatter/gather list +.Fa sg . +The physical address range starts at +.Fa paddr +and is +.Fa len +bytes long. +.Pp +The +.Nm sglist_append_uio +function appends the physical address ranges described by a +.Xr uio 9 +object to the scatter/gather list +.Fa sg . +Note that it is the caller's responsibility to ensure that the pages backing +the I/O request are wired for the lifetime of +.Fa sg . +Note also that this routine does not modify +.Fa uio . +.Pp +The +.Nm sglist_append_user +function appends the physical address ranges described by a single user +virtual address range to the scatter/gather list +.Fa sg . +The user virtual address range is relative to the address space of the thread +.Fa td . +It starts at +.Fa buf +and is +.Fa len +bytes long. +Note that it is the caller's responsibility to ensure that the pages backing +the user buffer are wired for the lifetime of +.Fa sg . +.Pp +The +.Nm sglist_consume_uio +function is a variation of +.Nm sglist_append_uio . +As with +.Nm sglist_append_uio , +it appends the physical address ranges described by +.Fa uio +to the scatter/gather list +.Fa sg . +Unlike +.Nm sglist_append_uio , +however, +.Nm sglist_consume_uio +modifies the I/O request to indicate that the appended address ranges have +been processed similar to calling +.Xr uiomove 9 . +This routine will only append ranges that describe up to +.Fa resid +total bytes in length. +If the available segments in the scatter/gather list are exhausted before +.Fa resid +bytes are processed, +then the +.Fa uio +structure will be updated to reflect the actual number of bytes processed, +and +.Nm sglist_consume_io +will return zero to indicate success. +In effect, this function will perform partial reads or writes. +The caller can compare the +.Fa uio_resid +member of +.Fa uio +before and after calling +.Nm sglist_consume_uio +to determine the actual number of bytes processed. +.Ss Manipulating Scatter/Gather Lists +The +.Nm sglist_join +function appends physical address ranges from the scatter/gather list +.Fa second +onto +.Fa first +and then resets +.Fa second +to an empty list. +It returns zero on success or an error on failure. +.Pp +The +.Nm sglist_split +function splits an existing scatter/gather list into two lists. +The first +.Fa length +bytes described by the list +.Fa original +are moved to a new list +.Fa *head . +If +.Fa original +describes a total address range that is smaller than +.Fa length +bytes, +then all of the address ranges will be moved to the new list at +.Fa *head +and +.Fa original +will be an empty list. +The caller may supply an existing scatter/gather list in +.Fa *head . +If so, the list must be empty. +Otherwise, the caller may set +.Fa *head +to +.Dv NULL +in which case a new scatter/gather list will be allocated. +In that case, +.Fa mflags +may be set to either +.Dv M_NOWAIT +or +.Dv M_WAITOK . +Note that since the +.Fa original +list is modified by this call, it must be a private list with no other +references. +The +.Nm sglist_split +function returns zero on success or an error on failure. +.Pp +The +.Nm sglist_slice +function generates a new scatter/gather list from a sub-range of an existing +scatter/gather list +.Fa original . +The sub-range to extract is specified by the +.Fa offset +and +.Fa length +parameters. +The new scatter/gather list is stored in +.Fa *slice . +As with +.Fa head +for +.Nm sglist_join , +the caller may either provide an empty scatter/gather list, +or it may set +.Fa *slice +to +.Dv NULL +in which case +.Nm sglist_slice +will allocate a new list subject to +.Fa mflags . +Unlike +.Nm sglist_split , +.Nm sglist_slice +does not modify +.Fa original +and does not require it to be a private list. +The +.Nm sglist_split +function returns zero on success or an error on failure. +.Ss Miscellaneous Routines +The +.Nm sglist_reset +function clears the scatter/gather list +.Fa sg +so that it no longer maps any address ranges. +This can allow reuse of a single scatter/gather list object for multiple +requests. +.Pp +The +.Nm sglist_length +function returns the total length of the physical address ranges described +by the scatter/gather list +.Fa sg . +.Sh RETURN VALUES +The +.Nm sglist_alloc , +.Nm sglist_build , +and +.Nm sglist_clone +functions return a new scatter/gather list on success or +.Dv NULL +on failure. +.Pp +The +.Nm sglist_append +family of functions and the +.Nm sglist_consume_uio , +.Nm sglist_join , +.Nm sglist_slice , +and +.Nm sglist_split +functions return zero on success or an error on failure. +.Pp +The +.Nm sglist_count +function returns a count of scatter/gather list elements. +.Pp +The +.Nm sglist_length +function returns a count of address space described by a scatter/gather list +in bytes. +.Sh ERRORS +The +.Nm sglist_append +functions return the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The scatter/gather list has zero segments. +.It Bq Er EFBIG +There are not enough available segments in the scatter/gather list to append +the specified physical address ranges. +.El +.Pp +The +.Nm sglist_consume_uio +function returns the following error on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The scatter/gather list has zero segments. +.El +.Pp +The +.Nm sglist_join +function returns the following error on failure: +.Bl -tag -width Er +.It Bq Er EFBIG +There are not enough available segments in the scatter/gather list +.Fa first +to append the physical address ranges from +.Fa second . +.El +.Pp +The +.Nm sglist_slice +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa original +scatter/gather list does not describe enough address space to cover the +requested sub-range. +.It Bq Er EINVAL +The caller-supplied scatter/gather list in +.Fa *slice +is not empty. +.It Bq Er ENOMEM +An attempt to allocate a new scatter/gather list with +.Dv M_NOWAIT +set in +.Fa mflags +failed. +.It Bq Er EFBIG +There are not enough available segments in the caller-supplied scatter/gather +list in +.Fa *slice +to describe the requested physical address ranges. +.El +.Pp +The +.Nm sglist_split +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EDOOFUS +The +.Fa original +scatter/gather list has more than one reference. +.It Bq Er EINVAL +The caller-supplied scatter/gather list in +.Fa *head +is not empty. +.It Bq Er ENOMEM +An attempt to allocate a new scatter/gather list with +.Dv M_NOWAIT +set in +.Fa mflags +failed. +.It Bq Er EFBIG +There are not enough available segments in the caller-supplied scatter/gather +list in +.Fa *head +to describe the requested physical address ranges. +.El +.Sh SEE ALSO +.Xr g_bio 9 , +.Xr malloc 9 , +.Xr mbuf 9 , +.Xr uio 9 +.Sh HISTORY +This API was first introduced in +.Fx 8.0 . Property changes on: user/imp/camdoc/sglist.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/shm_map.9 =================================================================== --- user/imp/camdoc/shm_map.9 (nonexistent) +++ user/imp/camdoc/shm_map.9 (revision 296049) @@ -0,0 +1,186 @@ +.\" +.\" Copyright (c) 2011 Hudson River Trading LLC +.\" Written by: John H. Baldwin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 14, 2011 +.Dt SHM_MAP 9 +.Os +.Sh NAME +.Nm shm_map , shm_unmap +.Nd "map shared memory objects into the kernel's address space" +.Sh SYNOPSIS +.In sys/types.h +.In sys/mman.h +.Ft int +.Fn shm_map "struct file *fp" "size_t size" "off_t offset" "void **memp" +.Ft int +.Fn shm_unmap "struct file *fp" "void *mem" "size_t size" +.Sh DESCRIPTION +The +.Fn shm_map +and +.Fn shm_unmap +functions provide an API for mapping shared memory objects into the kernel. +Shared memory objects are created by +.Xr shm_open 2 . +These objects can then be passed into the kernel via file descriptors. +.Pp +A shared memory object cannot be shrunk while it is mapped into the kernel. +This is to avoid invalidating any pages that may be wired into the kernel's +address space. +Shared memory objects can still be grown while mapped into the kernel. +.Pp +To simplify the accounting needed to enforce the above requirement, +callers of this API are required to unmap the entire region mapped by +.Fn shm_map +when calling +.Fn shm_unmap . +Unmapping only a portion of the region is not permitted. +.Pp +The +.Fn shm_map +function locates the shared memory object associated with the open file +.Fa fp . +It maps the region of that object described by +.Fa offset +and +.Fa size +into the kernel's address space. +If it succeeds, +.Fa *memp +will be set to the start of the mapping. +All pages for the range will be wired into memory upon successful return. +.Pp +The +.Fn shm_unmap +function unmaps a region previously mapped by +.Fn shm_map . +The +.Fa mem +argument should match the value previously returned in +.Fa *memp , +and the +.Fa size +argument should match the value passed to +.Fn shm_map . +.Pp +Note that +.Fn shm_map +will not hold an extra reference on the open file +.Fa fp +for the lifetime of the mapping. +Instead, +the calling code is required to do this if it wishes to use +.Fn shm_unmap +on the region in the future. +.Sh RETURN VALUES +The +.Fn shm_map +and +.Fn shm_unmap +functions return zero on success or an error on failure. +.Sh EXAMPLES +The following function accepts a file descriptor for a shared memory +object. +It maps the first sixteen kilobytes of the object into the kernel, +performs some work on that address, +and then unmaps the address before returning. +.Bd -literal -offset indent +int +shm_example(int fd) +{ + struct file *fp; + void *mem; + int error; + + error = fget(curthread, fd, CAP_MMAP, &fp); + if (error) + return (error); + error = shm_map(fp, 16384, 0, &mem); + if (error) { + fdrop(fp, curthread); + return (error); + } + + /* Do something with 'mem'. */ + + error = shm_unmap(fp, mem, 16384); + fdrop(fp, curthread); + return (error); +} +.Ed +.Sh ERRORS +The +.Fn shm_map +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The open file +.Fa fp +is not a shared memory object. +.It Bq Er EINVAL +The requested region described by +.Fa offset +and +.Fa size +extends beyond the end of the shared memory object. +.It Bq Er ENOMEM +Insufficient address space was available. +.It Bq Er EACCES +The shared memory object could not be mapped due to a protection error. +.It Bq Er EINVAL +The shared memory object could not be mapped due to some other VM error. +.El +.Pp +The +.Fn shm_unmap +function returns the following errors on failure: +.Bl -tag -width Er +.It Bq Er EINVAL +The open file +.Fa fp +is not a shared memory object. +.It Bq Er EINVAL +The address range described by +.Fa mem +and +.Fa size +is not a valid address range. +.It Bq Er EINVAL +The address range described by +.Fa mem +and +.Fa size +is not backed by the shared memory object associated with the open file +.Fa fp , +or the address range does not cover the entire mapping of the object. +.El +.Sh SEE ALSO +.Xr shm_open 2 +.Sh HISTORY +This API was first introduced in +.Fx 10.0 . Property changes on: user/imp/camdoc/shm_map.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/VOP_VPTOCNP.9 =================================================================== --- user/imp/camdoc/VOP_VPTOCNP.9 (nonexistent) +++ user/imp/camdoc/VOP_VPTOCNP.9 (revision 296049) @@ -0,0 +1,96 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2008 Joe Marcus Clarke +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 8, 2015 +.Dt VOP_VPTOCNP 9 +.Os +.Sh NAME +.Nm VOP_VPTOCNP +.Nd translate a vnode to its component name +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.In sys/vnode.h +.Ft int +.Fn VOP_VPTOCNP "struct vnode *vp" "struct vnode **dvp" "struct ucred *cred" "char *buf" "int *buflen" +.Sh DESCRIPTION +This translates a vnode into its component name, and writes that name to +the head of the buffer specified by +.Fa buf . +.Bl -tag -width buflen +.It Fa vp +The vnode to translate. +.It Fa dvp +The vnode of the parent directory of +.Fa vp . +.It Fa cred +The caller credentials. +.It Fa buf +The buffer into which to prepend the component name. +.It Fa buflen +The remaining size of the buffer. +.El +.Pp +The default implementation of +.Nm +scans through +.Fa vp Ns 's +parent directory looking for a dirent with a matching file number. +If +.Fa vp +is not a directory, then +.Nm +returns ENOENT. +.Sh LOCKS +The vnode should be locked on entry and will still be locked on exit. +The parent directory vnode will be unlocked on a successful exit. +However, it will have its use count incremented. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOMEM +The buffer was not large enough to hold the vnode's component name. +.It Bq Er ENOENT +The vnode was not found on the file system. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh NOTES +This interface is a work in progress. +.Sh HISTORY +The function +.Nm +appeared in +.Fx 8.0 . +.Sh AUTHORS +This manual page was written by +.An Joe Marcus Clarke . Property changes on: user/imp/camdoc/VOP_VPTOCNP.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/microuptime.9 =================================================================== --- user/imp/camdoc/microuptime.9 (nonexistent) +++ user/imp/camdoc/microuptime.9 (revision 296049) @@ -0,0 +1,124 @@ +.\" Copyright (c) 2000 Kelly Yancey +.\" 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 February 21, 2015 +.Dt MICROUPTIME 9 +.Os +.Sh NAME +.Nm binuptime , +.Nm getbinuptime , +.Nm microuptime , +.Nm getmicrouptime , +.Nm nanouptime , +.Nm getnanouptime , +.Nm sbinuptime , +.Nm getsbinuptime +.Nd get the time elapsed since boot +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn binuptime "struct bintime *bt" +.Ft void +.Fn getbinuptime "struct bintime *bt" +.Ft void +.Fn microuptime "struct timeval *tv" +.Ft void +.Fn getmicrouptime "struct timeval *tv" +.Ft void +.Fn nanouptime "struct timespec *ts" +.Ft void +.Fn getnanouptime "struct timespec *tsp" +.Ft sbintime_t +.Fn sbinuptime "void" +.Ft sbintime_t +.Fn getsbinuptime "void" +.Sh DESCRIPTION +The +.Fn binuptime +and +.Fn getbinuptime +functions store the time elapsed since boot as a +.Vt "struct bintime" +at the address specified by +.Fa bt . +The +.Fn microuptime +and +.Fn getmicrouptime +functions perform the same utility, but record the elapsed time as a +.Vt "struct timeval" +instead. +Similarly the +.Fn nanouptime +and +.Fn getnanouptime +functions store the elapsed time as a +.Vt "struct timespec" . +The +.Fn sbinuptime +and +.Fn getsbinuptime +functions return the time elapsed since boot as a +.Vt "sbintime_t" . +.Pp +The +.Fn binuptime , +.Fn microuptime , +.Fn nanouptime , +and +.Fn sbinuptime +functions +always query the timecounter to return the current time as precisely as +possible. +Whereas +.Fn getbinuptime , +.Fn getmicrouptime , +.Fn getnanouptime , +and +.Fn getsbinuptime +functions are abstractions which return a less precise, but +faster to obtain, time. +.Pp +The intent of the +.Fn getbinuptime , +.Fn getmicrouptime , +.Fn getnanouptime , +and +.Fn getsbinuptime +functions is to enforce the user's preference for timer accuracy versus +execution time. +.Sh SEE ALSO +.Xr bintime 9 , +.Xr get_cyclecount 9 , +.Xr getbintime 9 , +.Xr getmicrotime 9 , +.Xr getnanotime 9 , +.Xr microtime 9 , +.Xr nanotime 9 , +.Xr tvtohz 9 +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . Property changes on: user/imp/camdoc/microuptime.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/contigmalloc.9 =================================================================== --- user/imp/camdoc/contigmalloc.9 (nonexistent) +++ user/imp/camdoc/contigmalloc.9 (revision 296049) @@ -0,0 +1,139 @@ +.\" +.\" Copyright (c) 2004 Joseph Koshy +.\" 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 January 29, 2015 +.Dt CONTIGMALLOC 9 +.Os +.Sh NAME +.Nm contigmalloc , contigfree +.Nd manage contiguous kernel physical memory +.Sh SYNOPSIS +.In sys/types.h +.In sys/malloc.h +.Ft "void *" +.Fo contigmalloc +.Fa "unsigned long size" +.Fa "struct malloc_type *type" +.Fa "int flags" +.Fa "vm_paddr_t low" +.Fa "vm_paddr_t high" +.Fa "unsigned long alignment" +.Fa "vm_paddr_t boundary" +.Fc +.Ft void +.Fo contigfree +.Fa "void *addr" +.Fa "unsigned long size" +.Fa "struct malloc_type *type" +.Fc +.Sh DESCRIPTION +The +.Fn contigmalloc +function allocates +.Fa size +bytes of contiguous physical memory that is aligned to +.Fa alignment +bytes, and which does not cross a boundary of +.Fa boundary +bytes. +If successful, the allocation will reside between physical addresses +.Fa low +and +.Fa high . +The returned pointer points to a wired kernel virtual +address range of +.Fa size +bytes allocated from the kernel virtual address (KVA) map. +.Pp +The +.Fa flags +parameter modifies +.Fn contigmalloc Ns 's +behaviour as follows: +.Bl -tag -width indent +.It Dv M_ZERO +Causes the allocated physical memory to be zero filled. +.It Dv M_NOWAIT +Causes +.Fn contigmalloc +to return +.Dv NULL +if the request cannot be immediately fulfilled due to resource shortage. +.El +.Pp +Other flags (if present) are ignored. +.Pp +The +.Fn contigfree +function deallocates memory allocated by a previous call to +.Fn contigmalloc . +.Sh IMPLEMENTATION NOTES +The +.Fn contigmalloc +function does not sleep waiting for memory resources to be freed up, +but instead actively reclaims pages before giving up. +However, unless +.Dv M_NOWAIT +is specified, it may select a page for reclamation that must first be +written to backing storage, causing it to sleep. +.Pp +The +.Fn contigfree +function does not accept +.Dv NULL +as an address input, unlike +.Xr free 9 . +.Sh RETURN VALUES +The +.Fn contigmalloc +function returns a kernel virtual address if allocation succeeds, +or +.Dv NULL +otherwise. +.Sh EXAMPLES +.Bd -literal +void *p; +p = contigmalloc(8192, M_DEVBUF, M_ZERO, 0, (1L << 22), + 32 * 1024, 1024 * 1024); +.Ed +.Pp +Ask for 8192 bytes of zero-filled memory residing between physical +address 0 and 4194303 inclusive, aligned to a 32K boundary and not +crossing a 1M address boundary. +.Sh DIAGNOSTICS +The +.Fn contigmalloc +function will panic if +.Fa size +is zero, or if +.Fa alignment +or +.Fa boundary +is not a power of two. +.Sh SEE ALSO +.Xr malloc 9 , +.Xr memguard 9 Property changes on: user/imp/camdoc/contigmalloc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_enter.9 =================================================================== --- user/imp/camdoc/pmap_enter.9 (nonexistent) +++ user/imp/camdoc/pmap_enter.9 (revision 296049) @@ -0,0 +1,164 @@ +.\" +.\" Copyright (c) 2003 Bruce M Simpson +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" 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 January 27, 2015 +.Dt PMAP_ENTER 9 +.Os +.Sh NAME +.Nm pmap_enter +.Nd insert a virtual page into a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft int +.Fo pmap_enter +.Fa "pmap_t pmap" "vm_offset_t va" "vm_page_t m" "vm_prot_t prot" +.Fa "u_int flags" "int8_t psind" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_enter +function creates a mapping in the physical map +.Fa pmap +from the virtual address +.Fa va +to the physical page +.Fa m +with the protection +.Fa prot . +Any previous mapping at the virtual address +.Fa va +is destroyed. +.Pp +The +.Fa flags +argument may have the following values: +.Bl -tag -width ".Dv PMAP_ENTER_NOSLEEP" +.It Dv VM_PROT_READ +A read access to the given virtual address triggered the call. +.It Dv VM_PROT_WRITE +A write access to the given virtual address triggered the call. +.It Dv VM_PROT_EXECUTE +An execute access to the given virtual address triggered the call. +.It Dv PMAP_ENTER_WIRED +The mapping should be marked as wired. +.It Dv PMAP_ENTER_NOSLEEP +This function may not sleep during creation of the mapping. +If the mapping cannot be created without sleeping, an appropriate +Mach VM error is returned. +.El +If the +.Dv PMAP_ENTER_NOSLEEP +flag is not specified, this function must create the requested mapping +before returning. +It may not fail. +In order to create the requested mapping, this function may destroy +any non-wired mapping in any pmap. +.Pp +The +.Fa psind +parameter specifies the page size that should be used by the mapping. +The supported page sizes are described by the global array +.Dv pagesizes[] . +The desired page size is specified by passing the index of the array +element that equals the desired page size. +.Pp +When the +.Fn pmap_enter +function destroys or updates a managed mapping, including an existing +mapping at virtual address +.Fa va , +it updates the +.Ft vm_page +structure corresponding to the previously mapped physical page. +If the physical page was accessed through the managed mapping, +then the +.Ft vm_page +structure's +.Dv PGA_REFERENCED +aflag is set. +If the physical page was modified through the managed mapping, then the +.Fn vm_page_dirty +function is called on the +.Ft vm_page +structure. +.Pp +The +.Dv PGA_WRITEABLE +aflag must be set for the page +.Fa m +if the new mapping is managed and writeable. +It is advised to clear +.Dv PGA_WRITEABLE +for destroyed mappings if the implementation can ensure +that no other writeable managed mappings for the previously +mapped pages exist. +.Pp +If the page +.Fa m +is managed, the page must be busied by the caller +or the owning object must be locked. +In the later case, the +.Dv PMAP_ENTER_NOSLEEP +must be specified by the caller. +.Pp +The +.Fn pmap_enter +function must handle the multiprocessor TLB consistency for the +given address. +.Sh NOTES +On amd64, arm and i386 architectures the existing implementation +of the +.Nm +function is incomplete, only value 0 for +.Fa psind +is supported. +Other supported architectures have +.Dv pagesizes[] +array of size 1. +.Sh RETURN VALUES +If successful, the +.Fn pmap_enter +function returns +.Er KERN_SUCCESS . +If the +.Dv PMAP_ENTER_NOSLEEP +flag was specified and the resources required for the mapping cannot +be acquired without sleeping, +.Dv KERN_RESOURCE_SHORTAGE +is returned. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was first written by +.An Bruce M Simpson Aq Mt bms@spc.org +and then rewritten by +.An Alan Cox Aq Mt alc@FreeBSD.org +and +.An Konstantin Belousov Aq Mt kib@FreeBSD.org . Property changes on: user/imp/camdoc/pmap_enter.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/SYSCALL_MODULE.9 =================================================================== --- user/imp/camdoc/SYSCALL_MODULE.9 (nonexistent) +++ user/imp/camdoc/SYSCALL_MODULE.9 (revision 296049) @@ -0,0 +1,84 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 24, 2015 +.Dt SYSCALL_MODULE 9 +.Os +.Sh NAME +.Nm SYSCALL_MODULE +.Nd syscall kernel module declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/proc.h +.In sys/module.h +.In sys/sysent.h +.Fn SYSCALL_MODULE name "int *offset" "struct sysent *new_sysent" "modeventhand_t evh" "void *arg" +.Sh DESCRIPTION +The +.Fn SYSCALL_MODULE +macro declares a new syscall. +.Fn SYSCALL_MODULE +expands into a kernel module declaration with name +.Ql sys/ Ns Fa name . +.Pp +The rest of the arguments expected by this macro are: +.Bl -tag -width ".Fa new_sysent" +.It Fa offset +A pointer to an +.Vt int +which saves the offset in +.Vt "struct sysent" +where the syscall is allocated. +.It Fa new_sysent +is a pointer to a structure that specifies the function implementing +the syscall and the number of arguments this function needs (see +.In sys/sysent.h ) . +.It Fa evh +A pointer to the kernel module event handler function with the argument +.Fa arg . +Please refer to +.Xr module 9 +for more information. +.It Fa arg +The argument passed to the callback functions of the +.Fa evh +event handler when it is called. +.El +.Sh EXAMPLES +A minimal example for a syscall module can be found in +.Pa /usr/share/examples/kld/syscall/module/syscall.c . +.Sh SEE ALSO +.Xr module 9 +.Pp +.Pa /usr/share/examples/kld/syscall/module/syscall.c +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . Property changes on: user/imp/camdoc/SYSCALL_MODULE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_softc.9 =================================================================== --- user/imp/camdoc/device_get_softc.9 (nonexistent) +++ user/imp/camdoc/device_get_softc.9 (revision 296049) @@ -0,0 +1,69 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 21, 2015 +.Dt DEVICE_GET_SOFTC 9 +.Os +.Sh NAME +.Nm device_get_softc +.Nd access driver private instance variables +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void * +.Fn device_get_softc "device_t dev" +.Sh DESCRIPTION +Return the driver-specific software context of +.Fa dev . +The softc is automatically allocated and zeroed when the device is +attached. +The softc is also initialized and present when a device is probed, +but is subject to caveats as described in +.Xr DEVICE_PROBE 9 . +The size of the allocation is determined by the device's +.Vt driver_t +information used to define the driver. +The softc typically encapsulates the state of this instance of the +device. +.Pp +Driver writers are discouraged from using their own softc management +mechanisms. +Driver writers should not copy such mechanisms found in drivers in the +tree that predate this function. +.Sh RETURN VALUES +The pointer to the driver-specific instance variable is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_PROBE 9 , +.Xr device_set_softc 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_get_softc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/netisr.9 =================================================================== --- user/imp/camdoc/netisr.9 (nonexistent) +++ user/imp/camdoc/netisr.9 (revision 296049) @@ -0,0 +1,213 @@ +.\" +.\" Copyright (c) 2009 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 January 11, 2015 +.Dt NETISR 9 +.Os +.Sh NAME +.Nm netisr +.Nd Kernel network dispatch service +.Sh SYNOPSIS +.In net/netisr.h +.Ft void +.Fn netisr_register "const struct netisr_handler *nhp" +.Ft void +.Fn netisr_unregister "const struct netisr_handler *nhp" +.Ft int +.Fn netisr_dispatch "u_int proto" "struct mbuf *m" +.Ft int +.Fn netisr_dispatch_src "u_int proto" "uintptr_t source" "struct mbuf *m" +.Ft int +.Fn netisr_queue "u_int proto" "struct mbuf *m" +.Ft int +.Fn netisr_queue_src "u_int proto" "uintptr_t source" "struct mbuf *m" +.Ft void +.Fn netisr_clearqdrops "const struct netisr_handler *nhp" +.Ft void +.Fn netisr_getqdrops "const struct netisr_handler *nhp" "uint64_t *qdropsp" +.Ft void +.Fn netisr_getqlimit "const struct netisr_handler *nhp" "u_int *qlimitp" +.Ft int +.Fn netisr_setqlimit "const struct netisr_handler *nhp" "u_int qlimit" +.Ft u_int +.Fn netisr_default_flow2cpu "u_int flowid" +.Ft u_int +.Fn netisr_get_cpucount "void" +.Ft u_int +.Fn netisr_get_cpuid "u_int cpunumber" +.Sh DESCRIPTION +The +.Nm +kernel interface suite allows device drivers (and other packet sources) to +direct packets to protocols for directly dispatched or deferred processing. +Protocol registration and work stream statistics may be monitored using +.Xr netstat 1 . +.Ss Protocol registration +Protocols register and unregister handlers using +.Fn netisr_register +and +.Fn netisr_unregister , +and may also manage queue limits and statistics using the +.Fn netisr_clearqdrops , +.Fn netisr_getqdrops , +.Fn netisr_getqlimit , +and +.Fn netisr_setqlimit . +.Pp +.Nm +supports multi-processor execution of handlers, and relies on a combination +of source ordering and protocol-specific ordering and work-placement +policies to decide how to distribute work across one or more worker +threads. +Registering protocols will declare one of three policies: +.Bl -tag -width NETISR_POLICY_SOURCE +.It Dv NETISR_POLICY_SOURCE +.Nm +should maintain source ordering without advice from the protocol. +.Nm +will ignore any flow IDs present on +.Vt mbuf +headers for the purposes of work placement. +.It Dv NETISR_POLICY_FLOW +.Nm +should maintain flow ordering as defined by the +.Vt mbuf +header flow ID field. +If the protocol implements +.Va nh_m2flow , +then +.Nm +will query the protocol in the event that the +.Vt mbuf +doesn't have a flow ID, falling back on source ordering. +.It NETISR_POLICY_CPU +.Nm +will entirely delegate all work placement decisions to the protocol, +querying +.Va nh_m2cpuid +for each packet. +.El +.Pp +Registration is declared using +.Vt "struct netisr_handler" , +whose fields are defined as follows: +.Bl -tag -width "netisr_handler_t nh_handler" +.It Vt "const char *" Va nh_name +Unique character string name of the protocol, which may be included in +.Xr sysctl 2 +MIB names, so should not contain whitespace. +.It Vt netisr_handler_t Va nh_handler +Protocol handler function that will be invoked on each packet received for +the protocol. +.It Vt netisr_m2flow_t Va nh_m2flow +Optional protocol function to generate a flow ID and set a valid +hashtype for packets that enter the +.Nm +with +.Dv M_HASHTYPE_GET(m) +equal to +.Dv M_HASHTYPE_NONE . +Will be used only with +.Dv NETISR_POLICY_FLOW . +.It Vt netisr_m2cpuid_t Va nh_m2cpuid +Protocol function to determine what CPU a packet should be processed on. +Will be used only with +.Dv NETISR_POLICY_CPU . +.It Vt netisr_drainedcpu_t Va nh_drainedcpu +Optional callback function that will be invoked when a per-CPU queue +was drained. +It will never fire for directly dispatched packets. +Unless fully understood, this special-purpose function should not be used. +.\" In case you intend to use this please send 50 chocolate bars to each +.\" of rwatson and bz and wait for an answer. +.It Vt u_int Va nh_proto +Protocol number used by both protocols to identify themselves to +.Nm , +and by packet sources to select what handler will be used to process +packets. +A table of supported protocol numbers appears below. +For implementation reasons, protocol numbers great than 15 are currently +unsupported. +.It Vt u_int Va nh_qlimit +The maximum per-CPU queue depth for the protocol; due to internal +implementation details, the effective queue depth may be as much as twice +this number. +.It Vt u_int Va nh_policy +The ordering and work placement policy for the protocol, as described +earlier. +.El +.Ss Packet source interface +Packet sources, such as network interfaces, may request protocol processing +using the +.Fn netisr_dispatch +and +.Fn netisr_queue +interfaces. +Both accept a protocol number and +.Vt mbuf +argument, but while +.Fn netisr_queue +will always execute the protocol handler asynchronously in a deferred +context, +.Fn netisr_dispatch +will optionally direct dispatch if permitted by global and per-protocol +policy. +.Pp +In order to provide additional load balancing and flow information, +packet sources may also specify an opaque source identifier, which in +practice might be a network interface number or socket pointer, using +the +.Fn netisr_dispatch_src +and +.Fn netisr_queue_src +variants. +.Ss Protocol number constants +The follow protocol numbers are currently defined: +.Bl -tag -width NETISR_ROUTE +.It Dv NETISR_IP +IPv4 +.It Dv NETISR_IGMP +IGMPv3 loopback +.It Dv NETISR_ROUTE +Routing socket loopback +.It Dv NETISR_ARP +ARP +.It Dv NETISR_IPV6 +IPv6 +.It Dv NETISR_NATM +ATM +.It Dv NETISR_EPAIR +.Xr netstat 1 , +.Xr epair 4 +.El +.Sh AUTHORS +This manual page and the +.Nm +implementation were written by +.An Robert N. M. Watson . Property changes on: user/imp/camdoc/netisr.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/counter.9 =================================================================== --- user/imp/camdoc/counter.9 (nonexistent) +++ user/imp/camdoc/counter.9 (revision 296049) @@ -0,0 +1,201 @@ +.\"- +.\" 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 February 7, 2014 +.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 +.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 pathes. +.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. +.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 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 . Property changes on: user/imp/camdoc/counter.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/BUF_ISLOCKED.9 =================================================================== --- user/imp/camdoc/BUF_ISLOCKED.9 (nonexistent) +++ user/imp/camdoc/BUF_ISLOCKED.9 (revision 296049) @@ -0,0 +1,69 @@ +.\" +.\" Copyright (C) 2008 Attilio Rao +.\" 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 January 22, 2008 +.Dt BUF_ISLOCKED 9 +.Os +.Sh NAME +.Nm BUF_ISLOCKED +.Nd "returns the state of the lock linked to the buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_ISLOCKED "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_ISLOCKED +function returns the status of the lock linked to the buffer in relation to +curthread. +.Pp +It can return: +.Bl -tag -width ".Dv LK_EXCLUSIVE" +.It Dv LK_EXCLUSIVE +An exclusive lock is held by curthread. +.It Dv LK_EXCLOTHER +An exclusive lock is held by someone other than curthread. +.It Dv LK_SHARED +A shared lock is held. +.It Li 0 +The lock is not held by anyone. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 , +.Xr lockstatus 9 +.Sh AUTHORS +This manual page was written by +.An Attilio Rao Aq Mt attilio@FreeBSD.org . Property changes on: user/imp/camdoc/BUF_ISLOCKED.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DB_COMMAND.9 =================================================================== --- user/imp/camdoc/DB_COMMAND.9 (nonexistent) +++ user/imp/camdoc/DB_COMMAND.9 (revision 296049) @@ -0,0 +1,110 @@ +.\"- +.\" Copyright (c) 2008 Guillaume Ballet +.\" 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, 2008 +.Dt DB_COMMAND 9 +.Os +.Sh NAME +.Nm DB_COMMAND , +.Nm DB_SHOW_COMMAND , +.Nm DB_SHOW_ALL_COMMAND +.Nd Extends the ddb command set +.Sh SYNOPSIS +.In ddb/ddb.h +.Fo DB_COMMAND +.Fa command_name +.Fa command_function +.Fc +.Fn DB_SHOW_COMMAND "command_name" "command_function" +.Fn DB_SHOW_ALL_COMMAND "command_name" "command_function" +.Sh DESCRIPTION +The +.Fn DB_COMMAND +macro adds +.Fa command_name +to the list of top-level commands. +Invoking +.Fa command_name +from ddb will call +.Fa command_function . +.Pp +The +.Fn DB_SHOW_COMMAND +and +.Fn DB_SHOW_ALL_COMMAND +are roughly equivalent to +.Fn DB_COMMAND +but in these cases, +.Fa command_name +is a sub-command of the ddb +.Sy show +command and +.Sy show all +command, respectively. +.Pp +The general command syntax: +.Cm command Ns Op Li \&/ Ns Ar modifier +.Ar address Ns Op , Ns Ar count , +translates into the following parameters for +.Fa command_function : +.Bl -tag -width Fa -offset indent +.It Fa addr +The address passed to the command as an argument. +.It Fa have_addr +A boolean value that is true if the addr field is valid. +.It Fa count +The number of quad words starting at offset +.Fa addr +that the command must process. +.It Fa modif +A pointer to the string of modifiers. That is, a series of symbols used to pass some options to the command. For example, the +.Sy examine +command will display words in decimal form if it is passed the modifier "d". +.El +.Sh EXAMPLE +In your module, the command is declared as: +.Bd -literal +DB_COMMAND(mycmd, my_cmd_func) +{ + if (have_addr) + db_printf("Calling my command with address %p\\n", addr); +} +.Ed +.Pp +Then, when in ddb: +.Bd -literal +.Bf Sy +db> mycmd 0x1000 +Calling my command with address 0x1000 +db> +.Ef +.Ed +.Sh SEE ALSO +.Xr ddb 4 +.Sh AUTHORS +This manual page was written by +.An Guillaume Ballet Aq Mt gballet@gmail.com . Property changes on: user/imp/camdoc/DB_COMMAND.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/EVENTHANDLER.9 =================================================================== --- user/imp/camdoc/EVENTHANDLER.9 (nonexistent) +++ user/imp/camdoc/EVENTHANDLER.9 (revision 296049) @@ -0,0 +1,337 @@ +.\" Copyright (c) 2004 Joseph Koshy +.\" 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 April 19, 2014 +.Dt EVENTHANDLER 9 +.Os +.Sh NAME +.Nm EVENTHANDLER +.Nd kernel event handling functions +.Sh SYNOPSIS +.In sys/eventhandler.h +.Fn EVENTHANDLER_DECLARE name type +.Fn EVENTHANDLER_INVOKE name ... +.Ft eventhandler_tag +.Fn EVENTHANDLER_REGISTER name func arg priority +.Fn EVENTHANDLER_DEREGISTER name tag +.Ft eventhandler_tag +.Fo eventhandler_register +.Fa "struct eventhandler_list *list" +.Fa "const char *name" +.Fa "void *func" +.Fa "void *arg" +.Fa "int priority" +.Fc +.Ft void +.Fo eventhandler_deregister +.Fa "struct eventhandler_list *list" +.Fa "eventhandler_tag tag" +.Fc +.Ft "struct eventhandler_list *" +.Fn eventhandler_find_list "const char *name" +.Ft void +.Fn eventhandler_prune_list "struct eventhandler_list *list" +.Sh DESCRIPTION +The +.Nm +mechanism provides a way for kernel subsystems to register interest in +kernel events and have their callback functions invoked when these +events occur. +.Pp +The normal way to use this subsystem is via the macro interface. +The macros that can be used for working with event handlers and callback +function lists are: +.Bl -tag -width indent +.It Fn EVENTHANDLER_DECLARE +This macro declares an event handler named by argument +.Fa name +with callback functions of type +.Fa type . +.It Fn EVENTHANDLER_REGISTER +This macro registers a callback function +.Fa func +with event handler +.Fa name . +When invoked, function +.Fa func +will be invoked with argument +.Fa arg +as its first parameter along with any additional parameters passed in +via macro +.Fn EVENTHANDLER_INVOKE +(see below). +Callback functions are invoked in order of priority. +The relative priority of each callback among other callbacks +associated with an event is given by argument +.Fa priority , +which is an integer ranging from +.Dv EVENTHANDLER_PRI_FIRST +(highest priority), to +.Dv EVENTHANDLER_PRI_LAST +(lowest priority). +The symbol +.Dv EVENTHANDLER_PRI_ANY +may be used if the handler does not have a specific priority +associated with it. +If registration is successful, +.Fn EVENTHANDLER_REGISTER +returns a cookie of type +.Vt eventhandler_tag . +.It Fn EVENTHANDLER_DEREGISTER +This macro removes a previously registered callback associated with tag +.Fa tag +from the event handler named by argument +.Fa name . +.It Fn EVENTHANDLER_INVOKE +This macro is used to invoke all the callbacks associated with event +handler +.Fa name . +This macro is a variadic one. +Additional arguments to the macro after the +.Fa name +parameter are passed as the second and subsequent arguments to each +registered callback function. +.El +.Pp +The macros are implemented using the following functions: +.Bl -tag -width indent +.It Fn eventhandler_register +The +.Fn eventhandler_register +function is used to register a callback with a given event. +The arguments expected by this function are: +.Bl -tag -width ".Fa priority" +.It Fa list +A pointer to an existing event handler list, or +.Dv NULL . +If +.Fa list +is +.Dv NULL , +the event handler list corresponding to argument +.Fa name +is used. +.It Fa name +The name of the event handler list. +.It Fa func +A pointer to a callback function. +Argument +.Fa arg +is passed to the callback function +.Fa func +as its first argument when it is invoked. +.It Fa priority +The relative priority of this callback among all the callbacks +registered for this event. +Valid values are those in the range +.Dv EVENTHANDLER_PRI_FIRST +to +.Dv EVENTHANDLER_PRI_LAST . +.El +.Pp +The +.Fn eventhandler_register +function returns a +.Fa tag +that can later be used with +.Fn eventhandler_deregister +to remove the particular callback function. +.It Fn eventhandler_deregister +The +.Fn eventhandler_deregister +function removes the callback associated with tag +.Fa tag +from the event handler list pointed to by +.Fa list . +This function is safe to call from inside an event handler +callback. +.It Fn eventhandler_find_list +The +.Fn eventhandler_find_list +function returns a pointer to event handler list structure corresponding +to event +.Fa name . +.It Fn eventhandler_prune_list +The +.Fn eventhandler_prune_list +function removes all deregistered callbacks from the event list +.Fa list . +.El +.Ss Kernel Event Handlers +The following event handlers are present in the kernel: +.Bl -tag -width indent +.It Vt acpi_sleep_event +Callbacks invoked when the system is being sent to sleep. +.It Vt acpi_wakeup_event +Callbacks invoked when the system is being woken up. +.It Vt app_coredump_start +Callbacks invoked at start of application core dump. +.It Vt app_coredump_progress +Callbacks invoked during progress of application core dump. +.It Vt app_coredump_finish +Callbacks invoked at finish of application core dump. +.It Vt app_coredump_error +Callbacks invoked on error of application core dump. +.It Vt bpf_track +Callbacks invoked when a BPF listener attaches to/detaches from network interface. +.It Vt cpufreq_levels_changed +Callback invoked when cpu frequence levels have changed. +.It Vt cpufreq_post_change +Callback invoked after cpu frequence has changed. +.It Vt cpufreq_pre_change +Callback invoked before cpu frequence has changed +.It Vt dcons_poll +Callback invoked to poll for dcons changes. +.It Vt dev_clone +Callbacks invoked when a new entry is created under +.Pa /dev . +.It Vt group_attach_event +Callback invoked when an interfance has been added to an interface group. +.It Vt group_change_event +Callback invoked when an change has been made to an interface group. +.It Vt group_detach_event +Callback invoked when an interfance has been removed from an interface group. +.It Vt ifaddr_event +Callbacks invoked when an address is set up on a network interface. +.It Vt if_clone_event +Callbacks invoked when an interface is cloned. +.It Vt iflladdr_event +Callback invoked when an if link layer address event has happened. +.It Vt ifnet_arrival_event +Callbacks invoked when a new network interface appears. +.It Vt ifnet_departure_event +Callbacks invoked when a network interface is taken down. +.It Vt ifnet_link_event +Callback invoked when an interfance link event has happened. +.It Vt kld_load +Callbacks invoked after a linker file has been loaded. +.It Vt kld_unload +Callbacks invoked after a linker file has been successfully unloaded. +.It Vt kld_unload_try +Callbacks invoked before a linker file is about to be unloaded. +These callbacks may be used to return an error and prevent the unload from +proceeding. +.It Vt lle_event +Callback invoked when an link layer event has happened. +.It Vt nmbclusters_change +Callback invoked when the number of mbuf clusters has changed. +.It Vt nmbufs_change +Callback invoked when the number of mbufs has changed. +.It Vt maxsockets_change +Callback invoked when the maximum number of sockets has changed. +.It Vt mountroot +Callback invoked when root has been mounted. +.It Vt power_profile_change +Callbacks invoked when the power profile of the system changes. +.It Vt power_resume +Callback invoked when the system has resumed. +.It Vt power_suspend +Callback invoked just before the system is suspended. +.It Vt process_ctor +Callback invoked when a process is created. +.It Vt process_dtor +Callback invoked when a process is destroyed. +.It Vt process_exec +Callbacks invoked when a process performs an +.Fn exec +operation. +.It Vt process_exit +Callbacks invoked when a process exits. +.It Vt process_fini +Callback invoked when a process memory is destroyed. +This is never called. +.It Vt process_fork +Callbacks invoked when a process forks a child. +.It Vt process_init +Callback invoked when a process is initalized. +.It Vt random_adaptor_attach +Callback invoked when a new random module has been loaded. +.It Vt register_framebuffer +Callback invoked when a new frame buffer is registered. +.It Vt route_redirect_event +Callback invoked when a route gets redirected to a new location. +.It Vt shutdown_pre_sync +Callbacks invoked at shutdown time, before file systems are synchronized. +.It Vt shutdown_post_sync +Callbacks invoked at shutdown time, after all file systems are synchronized. +.It Vt shutdown_final +Callbacks invoked just before halting the system. +.It Vt tcp_offload_listen_start +Callback invoked for TCP Offload to start listening for new connections. +.It Vt tcp_offload_listen_stop +Callback invoked ror TCP Offload to stop listening for new connections. +.It Vt thread_ctor +Callback invoked when a thread object is created. +.It Vt thread_dtor +Callback invoked when a thread object is destroyed. +.It Vt thread_init +Callback invoked when a thread object is initalized. +.It Vt thread_fini +Callback invoked when a thread object is deinitalized. +.It Vt usb_dev_configured +Callback invoked when a USB device is configured +.It Vt unregister_framebuffer +Callback invoked when a frame buffer is deregistered. +.It Vt vfs_mounted +Callback invoked when a file system is mounted. +.It Vt vfs_unmounted +Callback invoked when a file system is unmounted. +.It Vt vlan_config +Callback invoked when the vlan configuration has changed. +.It Vt vlan_unconfig +Callback invoked when a vlan is destroyed. +.It Vt vm_lowmem +Callbacks invoked when virtual memory is low. +.It Vt watchdog_list +Callbacks invoked when the system watchdog timer is reinitialized. +.El +.Sh RETURN VALUES +The macro +.Fn EVENTHANDLER_REGISTER +and function +.Fn eventhandler_register +return a cookie of type +.Vt eventhandler_tag , +which may be used in a subsequent call to +.Fn EVENTHANDLER_DEREGISTER +or +.Fn eventhandler_deregister . +.Pp +The +.Fn eventhandler_find_list +function +returns a pointer to an event handler list corresponding to parameter +.Fa name , +or +.Dv NULL +if no such list was found. +.Sh HISTORY +The +.Nm +facility first appeared in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An Joseph Koshy Aq Mt jkoshy@FreeBSD.org . Property changes on: user/imp/camdoc/EVENTHANDLER.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS.9 =================================================================== --- user/imp/camdoc/VFS.9 (nonexistent) +++ user/imp/camdoc/VFS.9 (revision 296049) @@ -0,0 +1,61 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 9, 2010 +.Dt VFS 9 +.Os +.Sh NAME +.Nm VFS +.Nd kernel interface to file systems +.Sh DESCRIPTION +Calls used to set or query file systems for settings or information. +.Pp +File systems that do not implement a VFS operation should use the appropriate +.Fa vfs_std +function from +.Pa src/sys/kern/vfs_default.c +rather than implementing empty functions or casting to +.Fa eopnotsupp . +.Sh SEE ALSO +.Xr VFS_CHECKEXP 9 , +.Xr VFS_FHTOVP 9 , +.Xr VFS_INIT 9 , +.Xr VFS_MOUNT 9 , +.Xr VFS_QUOTACTL 9 , +.Xr VFS_SET 9 , +.Xr VFS_STATFS 9 , +.Xr VFS_SYNC 9 , +.Xr VFS_UNMOUNT 9 , +.Xr VFS_VGET 9 , +.Xr vnode 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_CHECKEXP.9 =================================================================== --- user/imp/camdoc/VFS_CHECKEXP.9 (nonexistent) +++ user/imp/camdoc/VFS_CHECKEXP.9 (revision 296049) @@ -0,0 +1,88 @@ +.\" +.\" Copyright (c) 1999 Alfred Perlstein +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following condition +.\" is met: +.\" Redistributions of source code must retain the above copyright +.\" notice, this condition and the following disclaimer. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 4, 2010 +.Dt VFS_CHECKEXP 9 +.Os +.Sh NAME +.Nm VFS_CHECKEXP +.Nd check if a file system is exported to a client +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn VFS_CHECKEXP "struct mount *mp" "struct sockaddr *nam" "int *exflagsp" "struct ucred **credanonp" +.Sh DESCRIPTION +The +.Fn VFS_CHECKEXP +macro is used by the NFS server to check if a mount point is exported +to a client. +.Pp +The arguments it expects are: +.Bl -tag -width credanonp +.It Fa mp +The mount point to be checked. +.It Fa nam +An mbuf containing the network address of the client. +.It Fa exflagsp +Return parameter for the export flags for this client. +.It Fa credanonp +Return parameter for the anonymous credentials for this client. +.El +.Pp +The +.Fn VFS_CHECKEXP +macro should be called on a file system's mount structure to determine if it +is exported to a client whose address is contained in +.Fa nam . +.Pp +It is generally called before +.Xr VFS_FHTOVP 9 +to validate that a client has access to the file system. +.Pp +The file system should call +.Xr vfs_export_lookup 9 +with the address of an appropriate +.Vt netexport +structure and the address of the client, +.Fa nam , +to verify that the client can access this file system. +.Sh RETURN VALUES +The export flags and anonymous credentials specific to the client (returned +by +.Xr vfs_export_lookup 9 ) +will be returned in +.Fa *exflagsp +and +.Fa *credanonp . +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_FHTOVP 9 , +.Xr vnode 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Alfred Perlstein . Property changes on: user/imp/camdoc/VFS_CHECKEXP.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_FHTOVP.9 =================================================================== --- user/imp/camdoc/VFS_FHTOVP.9 (nonexistent) +++ user/imp/camdoc/VFS_FHTOVP.9 (revision 296049) @@ -0,0 +1,83 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 4, 2010 +.Dt VFS_FHTOVP 9 +.Os +.Sh NAME +.Nm VFS_FHTOVP +.Nd turn an NFS filehandle into a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_FHTOVP "struct mount *mp" "struct fid *fhp" "struct vnode **vpp" +.Sh DESCRIPTION +The +.Fn VFS_FHTOVP +macro is used by the NFS server to turn an NFS filehandle into a vnode. +.Pp +The arguments it expects are: +.Bl -tag -width vpp +.It Fa mp +The file system. +.It Fa fhp +The filehandle to convert. +.It Fa vpp +Return parameter for the new locked vnode. +.El +.Pp +The contents of the filehandle are defined by the file system and are +not examined by any other part of the system. +It should contain +enough information to uniquely identify a file within the file system +as well as noticing when a file has been removed and the file system +resources have been reused for a new file. +For instance, UFS +file system stores the inode number and inode generation counter in its +filehandle. +.Pp +A call to +.Fn VFS_FHTOVP +should generally be preceded by a call to +.Xr VFS_CHECKEXP 9 +to check if the file is accessible to the client. +.Sh RETURN VALUES +The locked vnode for the file will be returned in +.Fa *vpp . +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_CHECKEXP 9 , +.Xr vnode 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_FHTOVP.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_SET.9 =================================================================== --- user/imp/camdoc/VFS_SET.9 (nonexistent) +++ user/imp/camdoc/VFS_SET.9 (revision 296049) @@ -0,0 +1,111 @@ +.\" +.\" Copyright (C) 2001 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 February 21, 2013 +.Dt VFS_SET 9 +.Os +.Sh NAME +.Nm VFS_SET +.Nd set up loadable file system +.Vt vfsconf +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/module.h +.In sys/mount.h +.Ft void +.Fn VFS_SET "struct vfsops *vfsops" "fsname" "int flags" +.Sh DESCRIPTION +.Fn VFS_SET +creates a +.Vt vfsconf +structure for the loadable module with the given +.Fa vfsops , fsname +and +.Fa flags , +and declares it by calling +.Xr DECLARE_MODULE 9 +using +.Fn vfs_modevent +as the event handler. +.Pp +Possible values for the +.Fa flags +argument are: +.Bl -hang -width ".Dv VFCF_DELEGADMIN" +.It Dv VFCF_STATIC +File system should be statically available in the kernel. +.It Dv VFCF_NETWORK +Network exportable file system. +.It Dv VFCF_READONLY +Does not support write operations. +.It Dv VFCF_SYNTHETIC +Pseudo file system, data does not represent on-disk files. +.It Dv VFCF_LOOPBACK +Loopback file system layer. +.It Dv VFCF_UNICODE +File names are stored as Unicode. +.It Dv VFCF_JAIL +Can be mounted from within a jail if +.Va security.jail.mount_allowed +sysctl is set to +.Dv 1 . +.It Dv VFCF_DELEGADMIN +Supports delegated administration if +.Va vfs.usermount +sysctl is set to +.Dv 1 . +.It Dv VFCF_SBDRY +When in VFS method, the thread suspension is deferred to the user +boundary upon arrival of stop action. +.El +.Sh PSEUDOCODE +.Bd -literal +/* + * Fill in the fields for which we have special methods. + * The others are initially null. This tells vfs to change them to + * pointers to vfs_std* functions during file system registration. + */ +static struct vfsops myfs_vfsops = { + .vfs_mount = myfs_mount, + .vfs_root = myfs_root, + .vfs_statfs = myfs_statfs, + .vfs_unmount = myfs_unmount, +}; + +VFS_SET(myfs_vfsops, myfs, 0); +.Ed +.Sh SEE ALSO +.Xr jail 2 , +.Xr jail 8 , +.Xr DECLARE_MODULE 9 , +.Xr vfs_modevent 9 , +.Xr vfsconf 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/VFS_SET.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_LOCK.9 =================================================================== --- user/imp/camdoc/VOP_LOCK.9 (nonexistent) +++ user/imp/camdoc/VOP_LOCK.9 (revision 296049) @@ -0,0 +1,125 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 25, 2008 +.Dt VOP_LOCK 9 +.Os +.Sh NAME +.Nm VOP_LOCK , +.Nm VOP_UNLOCK , +.Nm VOP_ISLOCKED , +.Nm vn_lock +.Nd serialize access to a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/vnode.h +.Ft int +.Fn VOP_LOCK "struct vnode *vp" "int flags" +.Ft int +.Fn VOP_UNLOCK "struct vnode *vp" "int flags" +.Ft int +.Fn VOP_ISLOCKED "struct vnode *vp" +.Ft int +.Fn vn_lock "struct vnode *vp" "int flags" +.Sh DESCRIPTION +These calls are used to serialize access to the file system, such as +to prevent two writes to the same file from happening at the +same time. +.Pp +The arguments are: +.Bl -tag -width flags +.It Fa vp +The vnode being locked or unlocked. +.It Fa flags +One of the lock request types: +.Pp +.Bl -tag -width ".Dv LK_CANRECURSE" -offset indent -compact +.It Dv LK_SHARED +Shared lock. +.It Dv LK_EXCLUSIVE +Exclusive lock. +.It Dv LK_UPGRADE +Shared-to-exclusive upgrade. +.It Dv LK_DOWNGRADE +Exclusive-to-shared downgrade. +.It Dv LK_RELEASE +Release any type of lock. +.It Dv LK_DRAIN +Wait for all lock activity to end. +.El +.Pp +The lock type may be +.Em or Ns 'ed +with these lock flags: +.Pp +.Bl -tag -width ".Dv LK_CANRECURSE" -offset indent -compact +.It Dv LK_NOWAIT +Do not sleep to wait for lock. +.It Dv LK_SLEEPFAIL +Sleep, then return failure. +.It Dv LK_CANRECURSE +Allow recursive exclusive lock. +.It Dv LK_NOWITNESS +Instruct +.Xr witness 4 +to ignore this instance. +.El +.Pp +The lock type may be +.Em or Ns 'ed +with these control flags: +.Pp +.Bl -tag -width ".Dv LK_CANRECURSE" -offset indent -compact +.It Dv LK_INTERLOCK +Specify when the caller already has a simple lock +.Po Fn VOP_LOCK +will unlock the simple lock after getting the lock +.Pc . +.It Dv LK_RETRY +Retry until locked. +.El +.Pp +Kernel code should use +.Fn vn_lock +to lock a vnode rather than calling +.Fn VOP_LOCK +directly. +.Fn vn_lock +also does not want a thread specified as argument but it +assumes curthread to be used. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_LOCK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/accf_data.9 =================================================================== --- user/imp/camdoc/accf_data.9 (nonexistent) +++ user/imp/camdoc/accf_data.9 (revision 296049) @@ -0,0 +1,78 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" 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 November 15, 2000 +.Dt ACCF_DATA 9 +.Os +.Sh NAME +.Nm accf_data +.Nd buffer incoming connections until data arrives +.Sh SYNOPSIS +.Nm options INET +.Nm options ACCEPT_FILTER_DATA +.Nm kldload accf_data +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming connections. +.Pp +It prevents the application from receiving the connected descriptor via +.Fn accept +until data arrives on the connection. +.Pp +The +.Fa ACCEPT_FILTER_DATA +kernel option is also a module that can be enabled at runtime via +.Xr kldload 8 +if the INET option has been compiled into the kernel. +.Sh EXAMPLES +Assuming ACCEPT_FILTER_DATA has been included in the kernel config +file or the +.Nm +module +has been loaded, this will enable the data accept filter +on the socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "dataready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 , +.Xr accf_dns 9 , +.Xr accf_http 9 +.Sh HISTORY +The accept filter mechanism and the +accf_data filter were introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An Alfred Perlstein . Property changes on: user/imp/camdoc/accf_data.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/accf_dns.9 =================================================================== --- user/imp/camdoc/accf_dns.9 (nonexistent) +++ user/imp/camdoc/accf_dns.9 (revision 296049) @@ -0,0 +1,79 @@ +.\" +.\" Copyright (c) 2008 David Malone +.\" +.\" 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 July 16, 2008 +.Dt ACCF_DNS 9 +.Os +.Sh NAME +.Nm accf_dns +.Nd buffer incoming DNS requests until the whole first request is present +.Sh SYNOPSIS +.Nm options INET +.Nm options ACCEPT_FILTER_DNS +.Nm kldload accf_dns +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming connections. +.Pp +It prevents the application from receiving the connected descriptor via +.Fn accept +until a whole DNS request is available on the socket. +It does this by reading the first two bytes of the request, +to determine its size, +and waiting until the required amount of data is available to be read. +.Pp +The +.Fa ACCEPT_FILTER_DNS +kernel option is also a module that can be enabled at runtime via +.Xr kldload 8 +if the INET option has been compiled into the kernel. +.Sh EXAMPLES +If the +.Nm +module is available in the kernel, +the following code will enable the DNS accept filter +on a socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "dnsready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 , +.Xr accf_data 9 , +.Xr accf_http 9 +.Sh HISTORY +The accept filter mechanism was introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An David Malone . Property changes on: user/imp/camdoc/accf_dns.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/alq.9 =================================================================== --- user/imp/camdoc/alq.9 (nonexistent) +++ user/imp/camdoc/alq.9 (revision 296049) @@ -0,0 +1,441 @@ +.\" +.\" Copyright (c) 2003 Hiten Pandya +.\" Copyright (c) 2009-2010 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Portions of this software were developed at the Centre for Advanced +.\" Internet Architectures, Swinburne University of Technology, Melbourne, +.\" Australia by Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" 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, 2010 +.Dt ALQ 9 +.Os +.Sh NAME +.Nm alq , +.Nm alq_open_flags , +.Nm alq_open , +.Nm alq_writen , +.Nm alq_write , +.Nm alq_flush , +.Nm alq_close , +.Nm alq_getn , +.Nm alq_get , +.Nm alq_post_flags , +.Nm alq_post +.Nd Asynchronous Logging Queues +.Sh SYNOPSIS +.In sys/alq.h +.Ft int +.Fo alq_open_flags +.Fa "struct alq **app" +.Fa "const char *file" +.Fa "struct ucred *cred" +.Fa "int cmode" +.Fa "int size" +.Fa "int flags" +.Fc +.Ft int +.Fo alq_open +.Fa "struct alq **app" +.Fa "const char *file" +.Fa "struct ucred *cred" +.Fa "int cmode" +.Fa "int size" +.Fa "int count" +.Fc +.Ft int +.Fn alq_writen "struct alq *alq" "void *data" "int len" "int flags" +.Ft int +.Fn alq_write "struct alq *alq" "void *data" "int flags" +.Ft void +.Fn alq_flush "struct alq *alq" +.Ft void +.Fn alq_close "struct alq *alq" +.Ft struct ale * +.Fn alq_getn "struct alq *alq" "int len" "int flags" +.Ft struct ale * +.Fn alq_get "struct alq *alq" "int flags" +.Ft void +.Fn alq_post_flags "struct alq *alq" "struct ale *ale" "int flags" +.Ft void +.Fn alq_post "struct alq *alq" "struct ale *ale" +.Sh DESCRIPTION +The +.Nm +facility provides an asynchronous fixed or variable length recording +mechanism, known as Asynchronous Logging Queues. +It can record to any +.Xr vnode 9 , +thus providing the ability to journal logs to character +devices as well as regular files. +All functions accept a +.Vt "struct alq" +argument, which is an opaque type that maintains state information +for an Asynchronous Logging Queue. +The logging facility runs in a separate kernel thread, which services +all log entry requests. +.Pp +An +.Dq asynchronous log entry +is defined as +.Vt "struct ale" , +which has the following members: +.Bd -literal -offset indent +struct ale { + intptr_t ae_bytesused; /* # bytes written to ALE. */ + char *ae_data; /* Write ptr. */ + int ae_pad; /* Unused, compat. */ +}; +.Ed +.Pp +An +.Nm +can be created in either fixed or variable length mode. +A variable length +.Nm +accommodates writes of varying length using +.Fn alq_writen +and +.Fn alq_getn . +A fixed length +.Nm +accommodates a fixed number of writes using +.Fn alq_write +and +.Fn alq_get , +each of fixed size (set at queue creation time). +Fixed length mode is deprecated in favour of variable length mode. +.Sh FUNCTIONS +The +.Fn alq_open_flags +function creates a new variable length asynchronous logging queue. +The +.Fa file +argument is the name of the file to open for logging. +If the file does not yet exist, +.Fn alq_open +will attempt to create it. +The +.Fa cmode +argument will be passed to +.Fn vn_open +as the requested creation mode, to be used if the file will be created by +.Fn alq_open . +Consumers of this API may wish to pass +.Dv ALQ_DEFAULT_CMODE , +a default creation mode suitable for most applications. +The +.Fa cred +argument specifies the credentials to use when opening and performing I/O on the file. +The +.Fa size +argument sets the size (in bytes) of the underlying queue. +The ALQ_ORDERED flag may be passed in via +.Fa flags +to indicate that the ordering of writer threads waiting for a busy +.Nm +to free up resources should be preserved. +.Pp +The deprecated +.Fn alq_open +function is implemented as a wrapper around +.Fn alq_open_flags +to provide backwards compatibility to consumers that have not been updated to +utilise the newer +.Fn alq_open_flags +function. +It passes all arguments through to +.Fn alq_open_flags +untouched except for +.Fa size +and +.Fa count , +and sets +.Fa flags +to 0. +To create a variable length mode +.Nm , +the +.Fa size +argument should be set to the size (in bytes) of the underlying queue and the +.Fa count +argument should be set to 0. +To create a fixed length mode +.Nm , +the +.Fa size +argument should be set to the size (in bytes) of each write and the +.Fa count +argument should be set to the number of +.Fa size +byte chunks to reserve capacity for. +.Pp +The +.Fn alq_writen +function writes +.Fa len +bytes from +.Fa data +to the designated variable length mode queue +.Fa alq . +If +.Fn alq_writen +could not write the entry immediately and +.Dv ALQ_WAITOK +is set in +.Fa flags , +the function will be allowed to +.Xr msleep_spin 9 +with the +.Dq Li alqwnord +or +.Dq Li alqwnres +wait message. +A write will automatically schedule the queue +.Fa alq +to be flushed to disk. +This behaviour can be controlled by passing ALQ_NOACTIVATE via +.Fa flags +to indicate that the write should not schedule +.Fa alq +to be flushed to disk. +.Pp +The deprecated +.Fn alq_write +function is implemented as a wrapper around +.Fn alq_writen +to provide backwards compatibility to consumers that have not been updated to +utilise variable length mode queues. +The function will write +.Fa size +bytes of data (where +.Fa size +was specified at queue creation time) from the +.Fa data +buffer to the +.Fa alq . +Note that it is an error to call +.Fn alq_write +on a variable length mode queue. +.Pp +The +.Fn alq_flush +function is used for flushing +.Fa alq +to the log medium that was passed to +.Fn alq_open . +If +.Fa alq +has data to flush and is not already in the process of being flushed, the +function will block doing IO. +Otherwise, the function will return immediately. +.Pp +The +.Fn alq_close +function will close the asynchronous logging queue +.Fa alq +and flush all pending write requests to the log medium. +It will free all resources that were previously allocated. +.Pp +The +.Fn alq_getn +function returns an asynchronous log entry from +.Fa alq , +initialised to point at a buffer capable of receiving +.Fa len +bytes of data. +This function leaves +.Fa alq +in a locked state, until a subsequent +.Fn alq_post +or +.Fn alq_post_flags +call is made. +If +.Fn alq_getn +could not obtain +.Fa len +bytes of buffer immediately and +.Dv ALQ_WAITOK +is set in +.Fa flags , +the function will be allowed to +.Xr msleep_spin 9 +with the +.Dq Li alqgnord +or +.Dq Li alqgnres +wait message. +The caller can choose to write less than +.Fa len +bytes of data to the returned asynchronous log entry by setting the entry's +ae_bytesused field to the number of bytes actually written. +This must be done prior to calling +.Fn alq_post . +.Pp +The deprecated +.Fn alq_get +function is implemented as a wrapper around +.Fn alq_getn +to provide backwards compatibility to consumers that have not been updated to +utilise variable length mode queues. +The asynchronous log entry returned will be initialised to point at a buffer +capable of receiving +.Fa size +bytes of data (where +.Fa size +was specified at queue creation time). +Note that it is an error to call +.Fn alq_get +on a variable length mode queue. +.Pp +The +.Fn alq_post_flags +function schedules the asynchronous log entry +.Fa ale +(obtained from +.Fn alq_getn +or +.Fn alq_get ) +for writing to +.Fa alq . +The ALQ_NOACTIVATE flag may be passed in via +.Fa flags +to indicate that the queue should not be immediately scheduled to be flushed to +disk. +This function leaves +.Fa alq +in an unlocked state. +.Pp +The +.Fn alq_post +function is implemented as a wrapper around +.Fn alq_post_flags +to provide backwards compatibility to consumers that have not been updated to +utilise the newer +.Fn alq_post_flags +function. +It simply passes all arguments through to +.Fn alq_post_flags +untouched, and sets +.Fa flags +to 0. +.Sh IMPLEMENTATION NOTES +The +.Fn alq_writen +and +.Fn alq_write +functions both perform a +.Xr bcopy 3 +from the supplied +.Fa data +buffer into the underlying +.Nm +buffer. +Performance critical code paths may wish to consider using +.Fn alq_getn +(variable length queues) or +.Fn alq_get +(fixed length queues) to avoid the extra memory copy. Note that a queue +remains locked between calls to +.Fn alq_getn +or +.Fn alq_get +and +.Fn alq_post +or +.Fn alq_post_flags , +so this method of writing to a queue is unsuitable for situations where the +time between calls may be substantial. +.Sh LOCKING +Each asynchronous logging queue is protected by a spin mutex. +.Pp +Functions +.Fn alq_flush +and +.Fn alq_open +may attempt to acquire an internal sleep mutex, and should +consequently not be used in contexts where sleeping is +not allowed. +.Sh RETURN VALUES +The +.Fn alq_open +function returns one of the error codes listed in +.Xr open 2 , +if it fails to open +.Fa file , +or else it returns 0. +.Pp +The +.Fn alq_writen +and +.Fn alq_write +functions return +.Er EWOULDBLOCK +if +.Dv ALQ_NOWAIT +was set in +.Fa flags +and either the queue is full or the system is shutting down. +.Pp +The +.Fn alq_getn +and +.Fn alq_get +functions return +.Dv NULL +if +.Dv ALQ_NOWAIT +was set in +.Fa flags +and either the queue is full or the system is shutting down. +.Pp +NOTE: invalid arguments to non-void functions will result in +undefined behaviour. +.Sh SEE ALSO +.Xr syslog 3 , +.Xr kproc 9 , +.Xr ktr 9 , +.Xr msleep_spin 9 , +.Xr vnode 9 +.Sh HISTORY +The +Asynchronous Logging Queues (ALQ) facility first appeared in +.Fx 5.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org +and extended by +.An Lawrence Stewart Aq Mt lstewart@freebsd.org . +.Pp +This manual page was written by +.An Hiten Pandya Aq Mt hmp@FreeBSD.org +and revised by +.An Lawrence Stewart Aq Mt lstewart@freebsd.org . Property changes on: user/imp/camdoc/alq.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/eventtimers.9 =================================================================== --- user/imp/camdoc/eventtimers.9 (nonexistent) +++ user/imp/camdoc/eventtimers.9 (revision 296049) @@ -0,0 +1,253 @@ +.\" +.\" Copyright (c) 2011-2013 Alexander Motin +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 2, 2014 +.Dt EVENTTIMERS 9 +.Os +.Sh NAME +.Nm eventtimers +.Nd kernel event timers subsystem +.Sh SYNOPSIS +.In sys/timeet.h +.Bd -literal +struct eventtimer; + +typedef int et_start_t(struct eventtimer *et, + sbintime_t first, sbintime_t period); +typedef int et_stop_t(struct eventtimer *et); +typedef void et_event_cb_t(struct eventtimer *et, void *arg); +typedef int et_deregister_cb_t(struct eventtimer *et, void *arg); + +struct eventtimer { + SLIST_ENTRY(eventtimer) et_all; + char *et_name; + int et_flags; +#define ET_FLAGS_PERIODIC 1 +#define ET_FLAGS_ONESHOT 2 +#define ET_FLAGS_PERCPU 4 +#define ET_FLAGS_C3STOP 8 +#define ET_FLAGS_POW2DIV 16 + int et_quality; + int et_active; + uint64_t et_frequency; + sbintime_t et_min_period; + sbintime_t et_max_period; + et_start_t *et_start; + et_stop_t *et_stop; + et_event_cb_t *et_event_cb; + et_deregister_cb_t *et_deregister_cb; + void *et_arg; + void *et_priv; + struct sysctl_oid *et_sysctl; +}; +.Ed +.Ft int +.Fn et_register "struct eventtimer *et" +.Ft int +.Fn et_deregister "struct eventtimer *et" +.Ft void +.Fn et_change_frequency "struct eventtimer *et" "uint64_t newfreq" +.Fn ET_LOCK +.Fn ET_UNLOCK +.Ft struct eventtimer * +.Fn et_find "const char *name" "int check" "int want" +.Ft int +.Fn et_init "struct eventtimer *et" "et_event_cb_t *event" "et_deregister_cb_t *deregister" "void *arg" +.Ft int +.Fn et_start "struct eventtimer *et" "sbintime_t first" "sbintime_t period" +.Ft int +.Fn et_stop "struct eventtimer *et" +.Ft int +.Fn et_ban "struct eventtimer *et" +.Ft int +.Fn et_free "struct eventtimer *et" +.Sh DESCRIPTION +Event timers are responsible for generating interrupts at specified time +or periodically, to run different time-based events. +Subsystem consists of three main parts: +.Bl -tag -width "Consumers" +.It Drivers +Manage hardware to generate requested time events. +.It Consumers +.Pa sys/kern/kern_clocksource.c +uses event timers to supply kernel with +.Fn hardclock , +.Fn statclock +and +.Fn profclock +time events. +.It Glue code +.Pa sys/sys/timeet.h , +.Pa sys/kern/kern_et.c +provide APIs for event timer drivers and consumers. +.El +.Sh DRIVER API +Driver API is built around eventtimer structure. +To register its functionality driver allocates that structure and calls +.Fn et_register . +Driver should fill following fields there: +.Bl -tag -width Va +.It Va et_name +Unique name of the event timer for management purposes. +.It Va et_flags +Set of flags, describing timer capabilities: +.Bl -tag -width "ET_FLAGS_PERIODIC" -compact +.It ET_FLAGS_PERIODIC +Periodic mode supported. +.It ET_FLAGS_ONESHOT +One-shot mode supported. +.It ET_FLAGS_PERCPU +Timer is per-CPU. +.It ET_FLAGS_C3STOP +Timer may stop in CPU sleep state. +.It ET_FLAGS_POW2DIV +Timer supports only 2^n divisors. +.El +.It Va et_quality +Abstract value to certify whether this timecounter is better than the others. +Higher value means better. +.It Va et_frequency +Timer oscillator's base frequency, if applicable and known. +Used by consumers to predict set of possible frequencies that could be +obtained by dividing it. +Should be zero if not applicable or unknown. +.It Va et_min_period , et_max_period +Minimal and maximal reliably programmable time periods. +.It Va et_start +Driver's timer start function pointer. +.It Va et_stop +Driver's timer stop function pointer. +.It Va et_priv +Driver's private data storage. +.El +.Pp +After the event timer functionality is registered, it is controlled via +.Va et_start +and +.Va et_stop +methods. +.Va et_start +method is called to start the specified event timer. +The last two arguments are used to specify time when events should be +generated. +.Va first +argument specifies time period before the first event generated. +In periodic mode NULL value specifies that first period is equal to the +.Va period +argument value. +.Va period +argument specifies the time period between following events for the +periodic mode. +The NULL value there specifies the one-shot mode. +At least one of these two arguments should be not NULL. +When event time arrive, driver should call +.Va et_event_cb +callback function, passing +.Va et_arg +as the second argument. +.Va et_stop +method is called to stop the specified event timer. +For the per-CPU event timers +.Va et_start +and +.Va et_stop +methods control timers associated with the current CPU. +.Pp +Driver may deregister its functionality by calling +.Fn et_deregister . +.Pp +If the frequency of the clock hardware can change while it is +running (for example, during power-saving modes), the driver must call +.Fn et_change_frequency +on each change. +If the given event timer is the active timer, +.Fn et_change_frequency +stops the timer on all CPUs, updates +.Va et->frequency , +then restarts the timer on all CPUs so that all +current events are rescheduled using the new frequency. +If the given timer is not currently active, +.Fn et_change_frequency +simply updates +.Va et->frequency . +.Sh CONSUMER API +.Fn et_find +allows consumer to find available event timer, optionally matching specific +name and/or capability flags. +Consumer may read returned eventtimer structure, but should not modify it. +When wanted event timer is found, +.Fn et_init +should be called for it, submitting +.Va event +and optionally +.Va deregister +callbacks functions, and the opaque argument +.Va arg . +That argument will be passed as argument to the callbacks. +Event callback function will be called on scheduled time events. +It is called from the hardware interrupt context, so no sleep is permitted +there. +Deregister callback function may be called to report consumer that the event +timer functionality is no longer available. +On this call, consumer should stop using event timer before the return. +.Pp +After the timer is found and initialized, it can be controlled via +.Fn et_start +and +.Fn et_stop . +The arguments are the same as described in driver API. +Per-CPU event timers can be controlled only from specific CPUs. +.Pp +.Fn et_ban +allows consumer to mark event timer as broken via clearing both one-shot and +periodic capability flags, if it was somehow detected. +.Fn et_free +is the opposite to +.Fn et_init . +It releases the event timer for other consumers use. +.Pp +.Fn ET_LOCK +and +.Fn ET_UNLOCK +macros should be used to manage +.Xr mutex 9 +lock around +.Fn et_find , +.Fn et_init +and +.Fn et_free +calls to serialize access to the list of the registered event timers and the +pointers returned by +.Fn et_find . +.Fn et_start +and +.Fn et_stop +calls should be serialized in consumer's internal way to avoid concurrent +timer hardware access. +.Sh SEE ALSO +.Xr eventtimers 4 +.Sh AUTHORS +.An Alexander Motin Aq Mt mav@FreeBSD.org Property changes on: user/imp/camdoc/eventtimers.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/ieee80211_crypto.9 =================================================================== --- user/imp/camdoc/ieee80211_crypto.9 (nonexistent) +++ user/imp/camdoc/ieee80211_crypto.9 (revision 296049) @@ -0,0 +1,260 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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$ +.\" $Id: ieee80211_crypto.9,v 1.3 2004/03/04 10:42:56 bruce Exp $ +.\" +.Dd March 29, 2010 +.Dt IEEE80211_CRYPTO 9 +.Os +.Sh NAME +.Nm ieee80211_crypto +.Nd 802.11 cryptographic support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Pp +.Ft void +.Fn ieee80211_crypto_register "const struct ieee80211_cipher *" +.\" +.Ft void +.Fn ieee80211_crypto_unregister "const struct ieee80211_cipher *" +.\" +.Ft int +.Fn ieee80211_crypto_available "int cipher" +.\" +.Pp +.Ft void +.Fo ieee80211_notify_replay_failure +.Fa "struct ieee80211vap *" +.Fa "const struct ieee80211_frame *" +.Fa "const struct ieee80211_key *" +.Fa "uint64_t rsc" +.Fa "int tid" +.Fc +.\" +.Ft void +.Fo ieee80211_notify_michael_failure +.Fa "struct ieee80211vap *" +.Fa "const struct ieee80211_frame *" +.Fa "u_int keyix" +.Fc +.\" +.Ft int +.Fo ieee80211_crypto_newkey +.Fa "struct ieee80211vap *" +.Fa "int cipher" +.Fa "int flags" +.Fa "struct ieee80211_key *" +.Fc +.\" +.Ft int +.Fn ieee80211_crypto_setkey "struct ieee80211vap *" "struct ieee80211_key *" +.\" +.Ft int +.Fn ieee80211_crypto_delkey "struct ieee80211vap *" "struct ieee80211_key *" +.\" +.Ft void +.Fn ieee80211_key_update_begin "struct ieee80211vap *" +.\" +.Ft void +.Fn ieee80211_key_update_end "struct ieee80211vap *" +.\" +.Ft void +.Fn ieee80211_crypto_delglobalkeys "struct ieee80211vap *" +.\" +.Ft void +.Fn ieee80211_crypto_reload_keys "struct ieee80211com *" +.\" +.Pp +.Ft struct ieee80211_key * +.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *" +.\" +.Ft struct ieee80211_key * +.Fn ieee80211_crypto_decap "struct ieee80211_node *" "struct mbuf *" "int flags" +.\" +.Ft int +.Fo ieee80211_crypto_demic +.Fa "struct ieee80211vap *" +.Fa "struct ieee80211_key *" +.Fa "struct mbuf *" +.Fa "int force" +.Fc +.\" +.Ft int +.Fo ieee80211_crypto_enmic +.Fa "struct ieee80211vap *" +.Fa "struct ieee80211_key *" +.Fa "struct mbuf *" +.Fa "int force" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer includes comprehensive cryptographic support for 802.11 protocols. +Software implementations of ciphers required by +WPA and 802.11i are provided as well as encap/decap processing of 802.11 frames. +Software ciphers are written as kernel modules and +register with the core crypto support. +The cryptographic framework supports hardware acceleration of ciphers +by drivers with automatic fall-back to software implementations when a +driver is unable to provide necessary hardware services. +.Sh CRYPTO CIPHER MODULES +.Nm net80211 +cipher modules register their services using +.Fn ieee80211_crypto_register +and supply a template that describes their operation. +This +.Vt ieee80211_cipher +structure defines protocol-related state such as the number of bytes +of space in the 802.11 header to reserve/remove during encap/decap +and entry points for setting up keys and doing cryptographic operations. +.Pp +Cipher modules can associate private state to each key through the +.Vt wk_private +structure member. +If state is setup by the module it will be called before a key is destroyed +so it can reclaim resources. +.Pp +Crypto modules can notify the system of two events. +When a packet replay event is recognized +.Fn ieee80211_notify_replay_failure +can be used to signal the event. +When a +.Dv TKIP +Michael failure is detected +.Fn ieee80211_notify_michael_failure +can be invoked. +Drivers may also use these routines to signal events detected by the +hardware. +.Sh CRYPTO KEY MANAGEMENT +The +.Nm net80211 +layer implements a per-vap 4-element +.Dq global key table +and a per-station +.Dq unicast key +for protocols such as WPA, 802.1x, and 802.11i. +The global key table is designed to support legacy WEP operation +and Multicast/Group keys, +though some applications also use it to implement WPA in station mode. +Keys in the global table are identified by a key index in the range 0-3. +Per-station keys are identified by the MAC address of the station and +are typically used for unicast PTK bindings. +.Pp +.Nm net80211 +provides +.Xr ioctl 2 +operations for managing both global and per-station keys. +Drivers typically do not participate in software key management; +they are involved only when providing hardware acceleration of +cryptographic operations. +.Pp +.Fn ieee80211_crypto_newkey +is used to allocate a new +.Nm net80211 +key or reconfigure an existing key. +The cipher must be specified along with any fixed key index. +The +.Nm net80211 +layer will handle allocating cipher and driver resources to support the key. +.Pp +Once a key is allocated it's contents can be set using +.Fn ieee80211_crypto_setkey +and deleted with +.Fn ieee80211_crypto_delkey +(with any cipher and driver resources reclaimed). +.Pp +.Fn ieee80211_crypto_delglobalkeys +is used to reclaim all keys in the global key table for a vap; it +typically is used only within the +.Nm net80211 +layer. +.Pp +.Fn ieee80211_crypto_reload_keys +handles hardware key state reloading from software key state, such +as required after a suspend/resume cycle. +.Sh DRIVER CRYPTO SUPPORT +Drivers identify ciphers they have hardware support for through the +.Vt ic_cryptocaps +field of the +.Vt ieee80211com +structure. +If hardware support is available then a driver should also fill in the +.Dv iv_key_alloc , +.Dv iv_key_set , +and +.Dv iv_key_delete +methods of each +.Vt ieee80211vap +created for use with the device. +In addition the methods +.Dv iv_key_update_begin +and +.Dv iv_key_update_end +can be setup to handle synchronization requirements +for updating hardware key state. +.Pp +When +.Nm net80211 +allocates a software key and the driver can accelerate the +cipher operations the +.Dv iv_key_alloc +method will be invoked. +Drivers may return a token that is associated with outbound traffic +(for use in encrypting frames). +Otherwise, e.g. if hardware resources are not available, the driver will +not return a token and +.Nm net80211 +will arrange to do the work in software and pass frames +to the driver that are already prepared for transmission. +.Pp +For receive, drivers mark frames with the +.Dv M_WEP +mbuf flag to indicate the hardware has decrypted the payload. +If frames have the +.Dv IEEE80211_FC1_PROTECTED +bit marked in their 802.11 header and are not tagged with +.Dv M_WEP +then decryption is done in software. +For more complicated scenarios the software key state is consulted; e.g. +to decide if Michael verification needs to be done in software after +the hardware has handled TKIP decryption. +.Pp +Drivers that manage complicated key data structures, e.g. faulting +software keys into a hardware key cache, can safely manipulate software +key state by bracketing their work with calls to +.Fn ieee80211_key_update_begin +and +.Fn ieee80211_key_update_end . +These calls also synchronize hardware key state update +when receive traffic is active. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr wlan_ccmp 4 , +.Xr wlan_tkip 4 , +.Xr wlan_wep 4 , +.Xr ieee80211 9 Property changes on: user/imp/camdoc/ieee80211_crypto.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/kqueue.9 =================================================================== --- user/imp/camdoc/kqueue.9 (nonexistent) +++ user/imp/camdoc/kqueue.9 (revision 296049) @@ -0,0 +1,467 @@ +.\" Copyright 2006,2011 John-Mark Gurney +.\" 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 26, 2012 +.Dt KQUEUE 9 +.Os +.Sh NAME +.Nm kqueue_add_filteropts , kqueue_del_filteropts , +.Nm kqfd_register , +.Nm knote_fdclose , +.Nm knlist_init , knlist_init_mtx , knlist_init_rw_reader , +.Nm knlist_add , knlist_remove , knlist_remove_inevent , knlist_empty , +.Nm knlist_clear , knlist_delete , knlist_destroy , +.Nm KNOTE_LOCKED , KNOTE_UNLOCKED +.Nd "event delivery subsystem" +.Sh SYNOPSIS +.In sys/event.h +.Ft int +.Fn kqueue_add_filteropts "int filt" "struct filterops *filtops" +.Ft int +.Fn kqueue_del_filteropts "int filt" +.Ft int +.Fn kqfd_register "int fd" "struct kevent *kev" "struct thread *td" "int waitok" +.Ft void +.Fn knote_fdclose "struct thread *td" "int fd" +.Ft void +.Fo knlist_init +.Fa "struct knlist *knl" +.Fa "void *lock" +.Fa "void \*[lp]*kl_lock\*[rp]\*[lp]void *\*[rp]" +.Fa "void \*[lp]*kl_unlock\*[rp]\*[lp]void *\*[rp]" +.Fa "int \*[lp]*kl_locked\*[rp]\*[lp]void *\*[rp]" +.Fc +.Ft void +.Fn knlist_init_mtx "struct knlist *knl" "struct mtx *lock" +.Ft void +.Fn knlist_init_rw_reader "struct knlist *knl" "struct rwlock *lock" +.Ft void +.Fn knlist_add "struct knlist *knl" "struct knote *kn" "int islocked" +.Ft void +.Fn knlist_remove "struct knlist *knl" "struct knote *kn" "int islocked" +.Ft void +.Fn knlist_remove_inevent "struct knlist *knl" "struct knote *kn" +.Ft int +.Fn knlist_empty "struct knlist *knl" +.Ft void +.Fn knlist_clear "struct knlist *knl" "int islocked" +.Ft void +.Fn knlist_delete "struct knlist *knl" "struct thread *td" "int islocked" +.Ft void +.Fn knlist_destroy "struct knlist *knl" +.Ft void +.Fn KNOTE_LOCKED "struct knlist *knl" "long hint" +.Ft void +.Fn KNOTE_UNLOCKED "struct knlist *knl" "long hint" +.Sh DESCRIPTION +The functions +.Fn kqueue_add_filteropts +and +.Fn kqueue_del_filteropts +allow for the addition and removal of a filter type. +The filter is statically defined by the +.Dv EVFILT_* +macros. +The function +.Fn kqueue_add_filteropts +will make +.Fa filt +available. +The +.Vt "struct filterops" +has the following members: +.Bl -tag -width ".Va f_attach" +.It Va f_isfd +If +.Va f_isfd +is set, +.Va ident +in +.Vt "struct kevent" +is taken to be a file descriptor. +In this case, the +.Vt knote +passed into +.Va f_attach +will have the +.Va kn_fp +member initialized to the +.Vt "struct file *" +that represents the file descriptor. +.It Va f_attach +The +.Va f_attach +function will be called when attaching a +.Vt knote +to the object. +The method should call +.Fn knlist_add +to add the +.Vt knote +to the list that was initialized with +.Fn knlist_init . +The call to +.Fn knlist_add +is only necessary if the object can have multiple +.Vt knotes +associated with it. +If there is no +.Vt knlist +to call +.Fn knlist_add +with, the function +.Va f_attach +must clear the +.Dv KN_DETACHED +bit of +.Va kn_status +in the +.Vt knote . +The function shall return 0 on success, or appropriate error for the failure, +such as when the object is being destroyed, or does not exist. +During +.Va f_attach , +it is valid to change the +.Va kn_fops +pointer to a different pointer. +This will change the +.Va f_event +and +.Va f_detach +functions called when processing the +.Vt knote . +.It Va f_detach +The +.Va f_detach +function will be called to detach the +.Vt knote +if the +.Vt knote +has not already been detached by a call to +.Fn knlist_remove , +.Fn knlist_remove_inevent +or +.Fn knlist_delete . +The list +.Fa lock +will not be held when this function is called. +.It Va f_event +The +.Va f_event +function will be called to update the status of the +.Vt knote . +If the function returns 0, it will be assumed that the object is not +ready (or no longer ready) to be woken up. +The +.Fa hint +argument will be 0 when scanning +.Vt knotes +to see which are triggered. +Otherwise, the +.Fa hint +argument will be the value passed to either +.Dv KNOTE_LOCKED +or +.Dv KNOTE_UNLOCKED . +The +.Va kn_data +value should be updated as necessary to reflect the current value, such as +number of bytes available for reading, or buffer space available for writing. +If the note needs to be removed, +.Fn knlist_remove_inevent +must be called. +The function +.Fn knlist_remove_inevent +will remove the note from the list, the +.Va f_detach +function will not be called and the +.Vt knote +will not be returned as an event. +.Pp +Locks +.Em must not +be acquired in +.Va f_event . +If a lock is required in +.Va f_event , +it must be obtained in the +.Fa kl_lock +function of the +.Vt knlist +that the +.Va knote +was added to. +.El +.Pp +The function +.Fn kqfd_register +will register the +.Vt kevent +on the kqueue file descriptor +.Fa fd . +If it is safe to sleep, +.Fa waitok +should be set. +.Pp +The function +.Fn knote_fdclose +is used to delete all +.Vt knotes +associated with +.Fa fd . +Once returned, there will no longer be any +.Vt knotes +associated with the +.Fa fd . +The +.Vt knotes +removed will never be returned from a +.Xr kevent 2 +call, so if userland uses the +.Vt knote +to track resources, they will be leaked. +The +.Fn FILEDESC_LOCK +lock must be held over the call to +.Fn knote_fdclose +so that file descriptors cannot be added or removed. +.Pp +The +.Fn knlist_* +family of functions are for managing +.Vt knotes +associated with an object. +A +.Vt knlist +is not required, but is commonly used. +If used, the +.Vt knlist +must be initialized with either +.Fn knlist_init , +.Fn knlist_init_mtx +or +.Fn knlist_init_rw_reader . +The +.Vt knlist +structure may be embedded into the object structure. +The +.Fa lock +will be held over +.Va f_event +calls. +.Pp +For the +.Fn knlist_init +function, if +.Fa lock +is +.Dv NULL , +a shared global lock will be used and the remaining arguments must be +.Dv NULL . +The function pointers +.Fa kl_lock , kl_unlock +and +.Fa kl_locked +will be used to manipulate the argument +.Fa lock . +If any of the function pointers are +.Dv NULL , +a function operating on +.Dv MTX_DEF +style +.Xr mutex 9 +locks will be used instead. +.Pp +The function +.Fn knlist_init_mtx +may be used to initialize a +.Vt knlist +when +.Fa lock +is a +.Dv MTX_DEF +style +.Xr mutex 9 +lock. +.Pp +The function +.Fn knlist_init_rw_reader +may be used to initialize a +.Vt knlist +when +.Fa lock +is a +.Xr rwlock 9 +read lock. +Lock is acquired via +.Fn rw_rlock +function. +.Pp +The function +.Fn knlist_empty +returns true when there are no +.Vt knotes +on the list. +The function requires that the +.Fa lock +be held when called. +.Pp +The function +.Fn knlist_clear +removes all +.Vt knotes +from the list. +The +.Fa islocked +argument declares if the +.Fa lock +has been acquired. +All +.Vt knotes +will have +.Dv EV_ONESHOT +set so that the +.Vt knote +will be returned and removed durning the next scan. +The +.Va f_detach +function will be called when the +.Vt knote +is deleted durning the next scan. +This function must not be used when +.Va f_isfd +is set in +.Vt "struct filterops" , +as the +.Fa td +argument of +.Fn fdrop +will be +.Dv NULL . +.Pp +The function +.Fn knlist_delete +removes and deletes all +.Vt knotes +on the list. +The function +.Va f_detach +will not be called, and the +.Vt knote +will not be returned on the next scan. +Using this function could leak user land resources if a process uses the +.Vt knote +to track resources. +.Pp +Both the +.Fn knlist_clear +and +.Fn knlist_delete +functions may sleep. +They also may release the +.Fa lock +to wait for other +.Vt knotes +to drain. +.Pp +The +.Fn knlist_destroy +function is used to destroy a +.Vt knlist . +There must be no +.Vt knotes +associated with the +.Vt knlist +.Po Fn knlist_empty +returns true +.Pc +and no more +.Vt knotes +may be attached to the object. +A +.Vt knlist +may be emptied by calling +.Fn knlist_clear +or +.Fn knlist_delete . +.Pp +The macros +.Fn KNOTE_LOCKED +and +.Fn KNOTE_UNLOCKED +are used to notify +.Vt knotes +about events associated with the object. +It will iterate over all +.Vt knotes +on the list calling the +.Va f_event +function associated with the +.Vt knote . +The macro +.Fn KNOTE_LOCKED +must be used if the lock associated with the +.Fa knl +is held. +The function +.Fn KNOTE_UNLOCKED +will acquire the lock before iterating over the list of +.Vt knotes . +.Sh RETURN VALUES +The function +.Fn kqueue_add_filteropts +will return zero on success, +.Er EINVAL +in the case of an invalid +.Fa filt , +or +.Er EEXIST +if the filter has already been installed. +.Pp +The function +.Fn kqueue_del_filteropts +will return zero on success, +.Er EINVAL +in the case of an invalid +.Fa filt , +or +.Er EBUSY +if the filter is still in use. +.Pp +The function +.Fn kqfd_register +will return zero on success, +.Er EBADF +if the file descriptor is not a kqueue, or any of the possible values returned +by +.Xr kevent 2 . +.Sh SEE ALSO +.Xr kevent 2 , +.Xr kqueue 2 +.Sh AUTHORS +This +manual page was written by +.An John-Mark Gurney Aq Mt jmg@FreeBSD.org . Property changes on: user/imp/camdoc/kqueue.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/lock.9 =================================================================== --- user/imp/camdoc/lock.9 (nonexistent) +++ user/imp/camdoc/lock.9 (revision 296049) @@ -0,0 +1,423 @@ +.\" +.\" 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 +unneccessary 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 . Property changes on: user/imp/camdoc/lock.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/usbdi.9 =================================================================== --- user/imp/camdoc/usbdi.9 (nonexistent) +++ user/imp/camdoc/usbdi.9 (revision 296049) @@ -0,0 +1,641 @@ +.\" +.\" 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". +.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. +. +.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. +. +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, +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. +.It UE_BULK +.It UE_CONTROL +"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 +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: +.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. +.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: +.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. +.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. +.It short_frames_ok +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. +.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 +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. +. +. +.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. +. +. +.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 +.Nm usb +module was written by +.An Hans Petter Selasky Aq Mt hselasky@FreeBSD.org . Property changes on: user/imp/camdoc/usbdi.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_busy.9 =================================================================== --- user/imp/camdoc/vm_page_busy.9 (nonexistent) +++ user/imp/camdoc/vm_page_busy.9 (revision 296049) @@ -0,0 +1,216 @@ +.\" +.\" Copyright (c) 2013 EMC Corp. +.\" 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 07, 2013 +.Dt VM_PAGE_BUSY 9 +.Os +.Sh NAME +.Nm vm_page_busied , +.Nm vm_page_busy_downgrade , +.Nm vm_page_busy_sleep , +.Nm vm_page_sbusied , +.Nm vm_page_sbusy , +.Nm vm_page_sleep_if_busy , +.Nm vm_page_sunbusy , +.Nm vm_page_trysbusy , +.Nm vm_page_tryxbusy , +.Nm vm_page_xbusied , +.Nm vm_page_xbusy , +.Nm vm_page_xunbusy , +.Nm vm_page_assert_sbusied , +.Nm vm_page_assert_unbusied , +.Nm vm_page_assert_xbusied +.Nd protect page identity changes and page content references +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft int +.Fn vm_page_busied "vm_page_t m" +.Ft void +.Fn vm_page_busy_downgrade "vm_page_t m" +.Ft void +.Fn vm_page_busy_sleep "vm_page_t m" "const char *msg" +.Ft int +.Fn vm_page_sbusied "vm_page_t m" +.Ft void +.Fn vm_page_sbusy "vm_page_t m" +.Ft int +.Fn vm_page_sleep_if_busy "vm_page_t m" "const char *msg" +.Ft void +.Fn vm_page_sunbusy "vm_page_t m" +.Ft int +.Fn vm_page_trysbusy "vm_page_t m" +.Ft int +.Fn vm_page_tryxbusy "vm_page_t m" +.Ft int +.Fn vm_page_xbusied "vm_page_t m" +.Ft void +.Fn vm_page_xbusy "vm_page_t m" +.Ft void +.Fn vm_page_xunbusy "vm_page_t m" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn vm_page_assert_sbusied "vm_page_t m" +.Ft void +.Fn vm_page_assert_unbusied "vm_page_t m" +.Ft void +.Fn vm_page_assert_xbusied "vm_page_t m" +.Sh DESCRIPTION +Page identity is usually protected by higher level locks like vm_object +locks and vm page locks. +However, sometimes it is not possible to hold such locks for the time +necessary to complete the identity change. +In such case the page can be exclusively busied by a thread which needs +to own the identity for a certain amount of time. +.Pp +In other situations, threads do not need to change the identity of the +page but they want to prevent other threads from changing the identity +themselves. +For example, when a thread wants to access or update page contents +without a lock held the page is shared busied. +.Pp +Before busying a page the vm_object lock must be held. +The same rule applies when a page is unbusied. +This makes the vm_object lock a real busy interlock. +.Pp +The +.Fn vm_page_busied +function returns non-zero if the current thread busied +.Fa m +in either exclusive or shared mode. +Returns zero otherwise. +.Pp +The +.Fn vm_page_busy_downgrade +function must be used to downgrade +.Fa m +from an exclusive busy state to a shared busy state. +.Pp +The +.Fn vm_page_busy_sleep +function puts the invoking thread to sleep using the appropriate +waitchannels for the busy mechanism. +The parameter +.Fa msg +is a string describing the sleep condition for userland tools. +.Pp +The +.Fn vm_page_busied +function returns non-zero if the current thread busied +.Fa m +in shared mode. +Returns zero otherwise. +.Pp +The +.Fn vm_page_sbusy +function shared busies +.Fa m . +.Pp +The +.Fn vm_page_sleep_if_busy +function puts the invoking thread to sleep, using the appropriate +waitchannels for the busy mechanism, if +.Fa m . +is busied in either exclusive or shared mode. +If the invoking thread slept a non-zero value is returned, otherwise +0 is returned. +The parameter +.Fa msg +is a string describing the sleep condition for userland tools. +.Pp +The +.Fn vm_page_sunbusy +function shared unbusies +.Fa m . +.Pp +The +.Fn vm_page_trysbusy +attempts to shared busy +.Fa m . +If the operation cannot immediately succeed +.Fn vm_page_trysbusy +returns 0, otherwise a non-zero value is returned. +.Pp +The +.Fn vm_page_tryxbusy +attempts to exclusive busy +.Fa m . +If the operation cannot immediately succeed +.Fn vm_page_tryxbusy +returns 0, otherwise a non-zero value is returned. +.Pp +The +.Fn vm_page_xbusied +function returns non-zero if the current thread busied +.Fa m +in exclusive mode. +Returns zero otherwise. +.Pp +The +.Fn vm_page_xbusy +function exclusive busies +.Fa m . +.Pp +The +.Fn vm_page_xunbusy +function exclusive unbusies +.Fa m . +Assertions on the busy state allow kernels compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" +to panic if they are not respected. +.Pp +The +.Fn vm_page_assert_sbusied +function panics if +.Fa m +is not shared busied. +.Pp +The +.Fn vm_page_assert_unbusied +function panics if +.Fa m +is not unbusied. +.Pp +The +.Fn vm_page_assert_xbusied +function panics if +.Fa m +is not exclusive busied. +.Sh SEE ALSO +.Xr vm_page_aflag 9 , +.Xr vm_page_alloc 9 , +.Xr vm_page_deactivate 9 , +.Xr vm_page_free 9 , +.Xr vm_page_grab 9 , +.Xr vm_page_insert 9 , +.Xr vm_page_lookup 9 , +.Xr vm_page_rename 9 , +.Xr VOP_GETPAGES 9 Property changes on: user/imp/camdoc/vm_page_busy.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/vnet.9 =================================================================== --- user/imp/camdoc/vnet.9 (nonexistent) +++ user/imp/camdoc/vnet.9 (revision 296049) @@ -0,0 +1,497 @@ +.\"- +.\" Copyright (c) 2010 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by CK Software GmbH under sponsorship from +.\" the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE 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 November 20, 2014 +.Dt VNET 9 +.Os +.Sh NAME +.Nm VNET +.Nd "network subsystem virtualization infrastructure" +.Sh SYNOPSIS +.Cd "options VIMAGE" +.Cd "options VNET_DEBUG" +.Pp +.In sys/vnet.h +.Pp +.\"------------------------------------------------------------ +.Ss "Constants and Global Variables" +.\" +.Dv VNET_SETNAME +.\" "set_vnet" +.Dv VNET_SYMPREFIX +.\" "vnet_entry_" +.Vt extern struct vnet *vnet0; +.\"------------------------------------------------------------ +.Ss "Variable Declaration" +.Fo VNET +.Fa "name" +.Fc +.\" +.Fo VNET_NAME +.Fa "name" +.Fc +.\" +.Fo VNET_DECLARE +.Fa "type" "name" +.Fc +.\" +.Fo VNET_DEFINE +.Fa "type" "name" +.Fc +.\" +.Bd -literal +#define V_name VNET(name) +.Ed +.\" ------------------------------------------------------------ +.Ss "Virtual Instance Selection" +.\" +.Fo CRED_TO_VNET +.Fa "struct ucred *" +.Fc +.\" +.Fo TD_TO_VNET +.Fa "struct thread *" +.Fc +.\" +.Fo P_TO_VNET +.Fa "struct proc *" +.Fc +.\" +.Fo IS_DEFAULT_VNET +.Fa "struct vnet *" +.Fc +.\" +.Fo VNET_ASSERT +.Fa exp msg +.Fc +.\" +.Fo CURVNET_SET +.Fa "struct vnet *" +.Fc +.\" +.Fo CURVNET_SET_QUIET +.Fa "struct vnet *" +.Fc +.\" +.Fn CURVNET_RESTORE +.\" +.Fo VNET_ITERATOR_DECL +.Fa "struct vnet *" +.Fc +.\" +.Fo VNET_FOREACH +.Fa "struct vnet *" +.Fc +.\" ------------------------------------------------------------ +.Ss "Locking" +.\" +.Fn VNET_LIST_RLOCK +.Fn VNET_LIST_RUNLOCK +.Fn VNET_LIST_RLOCK_NOSLEEP +.Fn VNET_LIST_RUNLOCK_NOSLEEP +.\" ------------------------------------------------------------ +.Ss "Startup and Teardown Functions" +.\" +.Ft "struct vnet *" +.Fo vnet_alloc +.Fa void +.Fc +.\" +.Ft void +.Fo vnet_destroy +.Fa "struct vnet *" +.Fc +.\" +.Fo VNET_SYSINIT +.Fa ident +.Fa "enum sysinit_sub_id subsystem" +.Fa "enum sysinit_elem_order order" +.Fa "sysinit_cfunc_t func" +.Fa "const void *arg" +.Fc +.\" +.Fo VNET_SYSUNINIT +.Fa ident +.Fa "enum sysinit_sub_id subsystem" +.Fa "enum sysinit_elem_order order" +.Fa "sysinit_cfunc_t func" +.Fa "const void *arg" +.Fc +.\" ------------------------------------------------------------ +.Ss "Eventhandlers" +.\" +.Fo VNET_GLOBAL_EVENTHANDLER_REGISTER +.Fa "const char *name" +.Fa "void *func" +.Fa "void *arg" +.Fa "int priority" +.Fc +.\" +.Fo VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG +.Fa "eventhandler_tag tag" +.Fa "const char *name" +.Fa "void *func" +.Fa "void *arg" +.Fa "int priority" +.Fc +.\" ------------------------------------------------------------ +.Ss "Sysctl Handling" +.Fo SYSCTL_VNET_INT +.Fa parent nbr name access ptr val descr +.Fc +.Fo SYSCTL_VNET_PROC +.Fa parent nbr name access ptr arg handler fmt descr +.Fc +.Fo SYSCTL_VNET_STRING +.Fa parent nbr name access arg len descr +.Fc +.Fo SYSCTL_VNET_STRUCT +.Fa parent nbr name access ptr type descr +.Fc +.Fo SYSCTL_VNET_UINT +.Fa parent nbr name access ptr val descr +.Fc +.Fo VNET_SYSCTL_ARG +.Fa req arg1 +.Fc +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +.Nm +is the name of a technique to virtualize the network stack. +The basic idea is to change global resources most notably variables into +per network stack resources and have functions, sysctls, eventhandlers, +etc. access and handle them in the context of the correct instance. +Each (virtual) network stack is attached to a +.Em prison , +with +.Vt vnet0 +being the unrestricted default network stack of the base system. +.Pp +The global defines for +.Dv VNET_SETNAME +and +.Dv VNET_SYMPREFIX +are shared with +.Xr kvm 3 +to access internals for debugging reasons. +.\" ------------------------------------------------------------ +.Ss "Variable Declaration" +.\" +Variables are virtualized by using the +.Fn VNET_DEFINE +macro rather than writing them out as +.Em type name . +One can still use static initialization or storage class specifiers, e.g., +.Pp +.Dl Li static VNET_DEFINE(int, foo) = 1; +or +.Dl Li static VNET_DEFINE(SLIST_HEAD(, bar), bars); +.Pp +Static initialization is not possible when the virtualized variable +would need to be referenced, e.g., with +.Dq TAILQ_HEAD_INITIALIZER() . +In that case a +.Fn VNET_SYSINIT +based initialization function must be used. +.Pp +External variables have to be declared using the +.Fn VNET_DECLARE +macro. +In either case the convention is to define another macro, +that is then used throughout the implementation to access that variable. +The variable name is usually prefixed by +.Em V_ +to express that it is virtualized. +The +.Fn VNET +macro will then translate accesses to that variable to the copy of the +currently selected instance (see the +.Sx "Virtual instance selection" +section): +.Pp +.Dl Li #define V_name VNET(name) +.Pp +.Em NOTE: +Do not confuse this with the convention used by +.Xr VFS 9 . +.Pp +The +.Fn VNET_NAME +macro returns the offset within the memory region of the virtual network +stack instance. +It is usually only used with +.Fn SYSCTL_VNET_* +macros. +.\" ------------------------------------------------------------ +.Ss "Virtual Instance Selection" +.\" +There are three different places where the current virtual +network stack pointer is stored and can be taken from: +.Bl -enum -offset indent +.It +a +.Em prison : +.Dl "(struct prison *)->pr_vnet" +.Pp +For convenience the following macros are provided: +.Bd -literal -compact -offset indent +.Fn CRED_TO_VNET "struct ucred *" +.Fn TD_TO_VNET "struct thread *" +.Fn P_TO_VNET "struct proc *" +.Ed +.It +a +.Em socket : +.Dl "(struct socket *)->so_vnet" +.It +an +.Em interface : +.Dl "(struct ifnet *)->if_vnet" +.El +.Pp +.\" +In addition the currently active instance is cached in +.Dq "curthread->td_vnet" +which is usually only accessed through the +.Dv curvnet +macro. +.Pp +.\" +To set the correct context of the current virtual network instance, use the +.Fn CURVNET_SET +or +.Fn CURVNET_SET_QUIET +macros. +The +.Fn CURVNET_SET_QUIET +version will not record vnet recursions in case the kernel was compiled +with +.Cd "options VNET_DEBUG" +and should thus only be used in well known cases, where recursion is +unavoidable. +Both macros will save the previous state on the stack and it must be restored +with the +.Fn CURVNET_RESTORE +macro. +.Pp +.Em NOTE: +As the previous state is saved on the stack, you cannot have multiple +.Fn CURVNET_SET +calls in the same block. +.Pp +.Em NOTE: +As the previous state is saved on the stack, a +.Fn CURVNET_RESTORE +call has to be in the same block as the +.Fn CURVNET_SET +call or in a subblock with the same idea of the saved instances as the +outer block. +.Pp +.Em NOTE: +As each macro is a set of operations and, as previously explained, cannot +be put into its own block when defined, one cannot conditionally set +the current vnet context. +The following will +.Em not +work: +.Bd -literal -offset indent +if (condition) + CURVNET_SET(vnet); +.Ed +.Pp +nor would this work: +.Bd -literal -offset indent +if (condition) { + CURVNET_SET(vnet); +} +CURVNET_RESTORE(); +.Ed +.Pp +.\" +Sometimes one needs to loop over all virtual instances, for example to update +virtual from global state, to run a function from a +.Xr callout 9 +for each instance, etc. +For those cases the +.Fn VNET_ITERATOR_DECL +and +.Fn VNET_FOREACH +macros are provided. +The former macro defines the variable that iterates over the loop, +and the latter loops over all of the virtual network stack instances. +See +.Sx "Locking" +for how to savely traverse the list of all virtual instances. +.Pp +.\" +The +.Fn IS_DEFAULT_VNET +macro provides a safe way to check whether the currently active instance is the +unrestricted default network stack of the base system +.Pq Vt vnet0 . +.Pp +.\" +The +.Fn VNET_ASSERT +macro provides a way to conditionally add assertions that are only active with +.Cd "options VIMAGE" +compiled in and either +.Cd "options VNET_DEBUG" +or +.Cd "options INVARIANTS" +enabled as well. +It uses the same semantics as +.Xr KASSERT 9 . +.\" ------------------------------------------------------------ +.Ss "Locking" +.\" +For public access to the list of virtual network stack instances +e.g., by the +.Fn VNET_FOREACH +macro, read locks are provided. +Macros are used to abstract from the actual type of the locks. +If a caller may sleep while traversing the list, it must use the +.Fn VNET_LIST_RLOCK +and +.Fn VNET_LIST_RUNLOCK +macros. +Otherwise, the caller can use +.Fn VNET_LIST_RLOCK_NOSLEEP +and +.Fn VNET_LIST_RUNLOCK_NOSLEEP . +.\" ------------------------------------------------------------ +.Ss "Startup and Teardown Functions" +.\" +To start or tear down a virtual network stack instance the internal +functions +.Fn vnet_alloc +and +.Fn vnet_destroy +are provided and called from the jail framework. +They run the publicly provided methods to handle network stack +startup and teardown. +.Pp +For public control, the system startup interface has been enhanced +to not only handle a system boot but to also handle a virtual +network stack startup and teardown. +To the base system the +.Fn VNET_SYSINIT +and +.Fn VNET_SYSUNINIT +macros look exactly as if there were no virtual network stack. +In fact, if +.Cd "options VIMAGE" +is not compiled in they are compiled to the standard +.Fn SYSINIT +macros. +In addition to that they are run for each virtual network stack +when starting or, in reverse order, when shutting down. +.\" ------------------------------------------------------------ +.Ss "Eventhandlers" +.\" +Eventhandlers can be handled in two ways: +.Pp +.Bl -enum -offset indent -compact +.It +save the +.Em tags +returned in each virtual instance and properly free the eventhandlers +on teardown using those, or +.It +use one eventhandler that will iterate over all virtual network +stack instances. +.El +.Pp +For the first case one can just use the normal +.Xr EVENTHANDLER 9 +functions, while for the second case the +.Fn VNET_GLOBAL_EVENTHANDLER_REGISTER +and +.Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG +macros are provided. +These differ in that +.Fn VNET_GLOBAL_EVENTHANDLER_REGISTER_TAG +takes an extra first argument that will carry the +.Fa "tag" +upon return. +Eventhandlers registered with either of these will not run +.Fa func +directly but +.Fa func +will be called from an internal iterator function for each vnet. +Both macros can only be used for eventhandlers that do not take +additional arguments, as the variadic arguments from an +.Xr EVENTHANDLER_INVOKE 9 +call will be ignored. +.\" ------------------------------------------------------------ +.Ss "Sysctl Handling" +.\" +A +.Xr sysctl 9 +can be virtualized by using one of the +.Fn SYSCTL_VNET_* +macros. +.Pp +They take the same arguments as the standard +.Xr sysctl 9 +functions, with the only difference, that the +.Fa ptr +argument has to be passed as +.Ql &VNET_NAME(foo) +instead of +.Ql &foo +so that the variable can be selected from the correct memory +region of the virtual network stack instance of the caller. +.Pp +For the very rare case a sysctl handler function would want to +handle +.Fa arg1 +itself the +.Fn VNET_SYSCTL_ARG req arg1 +is provided that will translate the +.Fa arg1 +argument to the correct memory address in the virtual network stack +context of the caller. +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr jail 2 , +.Xr kvm 3 , +.Xr EVENTHANDLER 9 , +.\" .Xr pcpu 9 , +.Xr KASSERT 9 , +.Xr sysctl 9 +.\" .Xr SYSINIT 9 +.Sh HISTORY +The virtual network stack implementation first appeared in +.Fx 8.0 . +.Sh AUTHORS +This manual page was written by +.An Bjoern A. Zeeb, CK Software GmbH, +under sponsorship from the FreeBSD Foundation. Property changes on: user/imp/camdoc/vnet.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/vnode.9 =================================================================== --- user/imp/camdoc/vnode.9 (nonexistent) +++ user/imp/camdoc/vnode.9 (revision 296049) @@ -0,0 +1,197 @@ +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 12, 2014 +.Dt VNODE 9 +.Os +.Sh NAME +.Nm vnode +.Nd internal representation of a file or directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Sh DESCRIPTION +The vnode is the focus of all file activity in +.Ux . +A vnode is described by +.Vt "struct vnode" . +There is a +unique vnode allocated for each active file, each current directory, +each mounted-on file, text file, and the root. +.Pp +Each vnode has three reference counts, +.Va v_usecount , +.Va v_holdcnt +and +.Va v_writecount . +The first is the number of clients within the kernel which are +using this vnode. +This count is maintained by +.Xr vref 9 , +.Xr vrele 9 +and +.Xr vput 9 . +The second is the number of clients within the kernel who veto +the recycling of this vnode. +This count is +maintained by +.Xr vhold 9 +and +.Xr vdrop 9 . +When both the +.Va v_usecount +and the +.Va v_holdcnt +of a vnode reaches zero then the vnode will be put on the freelist +and may be reused for another file, possibly in another file system. +The transition from the freelist is handled by +.Xr getnewvnode 9 . +The third is a count of the number of clients which are writing into +the file. +It is maintained by the +.Xr open 2 +and +.Xr close 2 +system calls. +.Pp +Any call which returns a vnode (e.g.,\& +.Xr vget 9 , +.Xr VOP_LOOKUP 9 , +etc.) +will increase the +.Va v_usecount +of the vnode by one. +When the caller is finished with the vnode, it +should release this reference by calling +.Xr vrele 9 +(or +.Xr vput 9 +if the vnode is locked). +.Pp +Other commonly used members of the vnode structure are +.Va v_id +which is used to maintain consistency in the name cache, +.Va v_mount +which points at the file system which owns the vnode, +.Va v_type +which contains the type of object the vnode represents and +.Va v_data +which is used by file systems to store file system specific data with +the vnode. +The +.Va v_op +field is used by the +.Dv VOP_* +macros to call functions in the file system which implement the vnode's +functionality. +.Sh VNODE TYPES +.Bl -tag -width VSOCK +.It Dv VNON +No type. +.It Dv VREG +A regular file; may be with or without VM object backing. +If you want to make sure this get a backing object, call +.Fn vnode_create_vobject . +.It Dv VDIR +A directory. +.It Dv VBLK +A block device; may be with or without VM object backing. +If you want to make sure this get a backing object, call +.Fn vnode_create_vobject . +.It Dv VCHR +A character device. +.It Dv VLNK +A symbolic link. +.It Dv VSOCK +A socket. +Advisory locking will not work on this. +.It Dv VFIFO +A FIFO (named pipe). +Advisory locking will not work on this. +.It Dv VBAD +Indicates that the vnode has been reclaimed. +.El +.Sh IMPLEMENTATION NOTES +VFIFO uses the "struct fileops" from +.Pa /sys/kern/sys_pipe.c . +VSOCK uses the "struct fileops" from +.Pa /sys/kern/sys_socket.c . +Everything else uses the one from +.Pa /sys/kern/vfs_vnops.c . +.Pp +The VFIFO/VSOCK code, which is why "struct fileops" is used at all, is +an artifact of an incomplete integration of the VFS code into the +kernel. +.Pp +Calls to +.Xr malloc 9 +or +.Xr free 9 +when holding a +.Nm +interlock, will cause a LOR (Lock Order Reversal) due to the +intertwining of VM Objects and Vnodes. +.Sh SEE ALSO +.Xr malloc 9 , +.Xr VFS 9 , +.Xr VOP_ACCESS 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_ADVISE 9 , +.Xr VOP_ADVLOCK 9 , +.Xr VOP_ALLOCATE 9 , +.Xr VOP_ATTRIB 9 , +.Xr VOP_BWRITE 9 , +.Xr VOP_CREATE 9 , +.Xr VOP_FSYNC 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_GETPAGES 9 , +.Xr VOP_INACTIVE 9 , +.Xr VOP_IOCTL 9 , +.Xr VOP_LINK 9 , +.Xr VOP_LISTEXTATTR 9 , +.Xr VOP_LOCK 9 , +.Xr VOP_LOOKUP 9 , +.Xr VOP_OPENCLOSE 9 , +.Xr VOP_PATHCONF 9 , +.Xr VOP_PRINT 9 , +.Xr VOP_RDWR 9 , +.Xr VOP_READDIR 9 , +.Xr VOP_READLINK 9 , +.Xr VOP_REALLOCBLKS 9 , +.Xr VOP_REMOVE 9 , +.Xr VOP_RENAME 9 , +.Xr VOP_REVOKE 9 , +.Xr VOP_SETACL 9 , +.Xr VOP_SETEXTATTR 9 , +.Xr VOP_STRATEGY 9 , +.Xr VOP_VPTOCNP 9 , +.Xr VOP_VPTOFH 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/vnode.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/rmlock.9 =================================================================== --- user/imp/camdoc/rmlock.9 (nonexistent) +++ user/imp/camdoc/rmlock.9 (revision 296049) @@ -0,0 +1,323 @@ +.\" Copyright (c) 2007 Stephan Uphoff +.\" Copyright (c) 2006 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$ +.\" +.\" Based on rwlock.9 man page +.Dd December 13, 2014 +.Dt RMLOCK 9 +.Os +.Sh NAME +.Nm rmlock , +.Nm rm_init , +.Nm rm_init_flags , +.Nm rm_destroy , +.Nm rm_rlock , +.Nm rm_try_rlock , +.Nm rm_wlock , +.Nm rm_runlock , +.Nm rm_wunlock , +.Nm rm_wowned , +.Nm rm_sleep , +.Nm rm_assert , +.Nm RM_SYSINIT +.Nd kernel reader/writer lock optimized for read-mostly access patterns +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/rmlock.h +.Ft void +.Fn rm_init "struct rmlock *rm" "const char *name" +.Ft void +.Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" +.Ft void +.Fn rm_destroy "struct rmlock *rm" +.Ft void +.Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +.Ft int +.Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +.Ft void +.Fn rm_wlock "struct rmlock *rm" +.Ft void +.Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" +.Ft void +.Fn rm_wunlock "struct rmlock *rm" +.Ft int +.Fn rm_wowned "const struct rmlock *rm" +.Ft int +.Fn rm_sleep "void *wchan" "struct rmlock *rm" "int priority" "const char *wmesg" "int timo" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn rm_assert "struct rmlock *rm" "int what" +.In sys/kernel.h +.Fn RM_SYSINIT "name" "struct rmlock *rm" "const char *desc" "int opts" +.Sh DESCRIPTION +Read-mostly 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 only read the protected data. +A thread with exclusive access is known as a +.Em writer +since it can modify protected data. +.Pp +Read-mostly locks are designed to be efficient for locks almost exclusively +used as reader locks and as such should be used for protecting data that +rarely changes. +Acquiring an exclusive lock after the lock has been locked for shared access +is an expensive operation. +.Pp +Normal read-mostly locks are similar to +.Xr rwlock 9 +locks and follow the same lock ordering rules as +.Xr rwlock 9 +locks. +Read-mostly locks have full priority propagation like mutexes. +Unlike +.Xr rwlock 9 , +read-mostly locks propagate priority to both readers and writers. +This is implemented via the +.Va rm_priotracker +structure argument supplied to +.Fn rm_rlock +and +.Fn rm_runlock . +Readers can recurse if the lock is initialized with the +.Dv RM_RECURSE +option; +however, writers are never allowed to recurse. +.Pp +Sleepable read-mostly locks are created by passing +.Dv RM_SLEEPABLE +to +.Fn rm_init_flags . +Unlike normal read-mostly locks, +sleepable read-mostly locks follow the same lock ordering rules as +.Xr sx 9 +locks. +Sleepable read-mostly locks do not propagate priority to writers, +but they do propagate priority to readers. +Writers are permitted to sleep while holding a read-mostly lock, +but readers are not. +Unlike other sleepable locks such as +.Xr sx 9 +locks, +readers must use try operations on other sleepable locks to avoid sleeping. +.Ss Macros and Functions +.Bl -tag -width indent +.It Fn rm_init "struct rmlock *rm" "const char *name" +Initialize the read-mostly lock +.Fa rm . +The +.Fa name +description is used solely for debugging purposes. +This function must be called before any other operations +on the lock. +.It Fn rm_init_flags "struct rmlock *rm" "const char *name" "int opts" +Similar to +.Fn rm_init , +initialize the read-mostly lock +.Fa rm +with a set of optional flags. +The +.Fa opts +arguments contains one or more of the following flags: +.Bl -tag -width ".Dv RM_NOWITNESS" +.It Dv RM_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv RM_RECURSE +Allow threads to recursively acquire shared locks for +.Fa rm . +.It Dv RM_SLEEPABLE +Create a sleepable read-mostly lock. +.It Dv RM_NEW +If the kernel has been compiled with +.Cd "option INVARIANTS" , +.Fn rm_init_flags +will assert that the +.Fa rm +has not been initialized multiple times without intervening calls to +.Fn rm_destroy +unless this option is specified. +.El +.It Fn rm_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +Lock +.Fa rm +as a reader using +.Fa tracker +to track read owners of a lock for priority propagation. +This data structure is only used internally by +.Nm +and must persist until +.Fn rm_runlock +has been called. +This data structure can be allocated on the stack since +readers cannot sleep. +If any thread holds this lock exclusively, the current thread blocks, +and its priority is propagated to the exclusive holder. +If the lock was initialized with the +.Dv RM_RECURSE +option the +.Fn rm_rlock +function can be called when the current thread has already acquired reader +access on +.Fa rm . +.It Fn rm_try_rlock "struct rmlock *rm" "struct rm_priotracker* tracker" +Try to lock +.Fa rm +as a reader. +.Fn rm_try_rlock +will return 0 if the lock cannot be acquired immediately; +otherwise, +the lock will be acquired and a non-zero value will be returned. +Note that +.Fn rm_try_rlock +may fail even while the lock is not currently held by a writer. +If the lock was initialized with the +.Dv RM_RECURSE +option, +.Fn rm_try_rlock +will succeed if the current thread has already acquired reader access. +.It Fn rm_wlock "struct rmlock *rm" +Lock +.Fa rm +as a writer. +If there are any shared owners of the lock, the current thread blocks. +The +.Fn rm_wlock +function cannot be called recursively. +.It Fn rm_runlock "struct rmlock *rm" "struct rm_priotracker* tracker" +This function releases a shared lock previously acquired by +.Fn rm_rlock . +The +.Fa tracker +argument must match the +.Fa tracker +argument used for acquiring the shared lock +.It Fn rm_wunlock "struct rmlock *rm" +This function releases an exclusive lock previously acquired by +.Fn rm_wlock . +.It Fn rm_destroy "struct rmlock *rm" +This functions destroys a lock previously initialized with +.Fn rm_init . +The +.Fa rm +lock must be unlocked. +.It Fn rm_wowned "const struct rmlock *rm" +This function returns a non-zero value if the current thread owns an +exclusive lock on +.Fa rm . +.It Fn rm_sleep "void *wchan" "struct rmlock *rm" "int priority" "const char *wmesg" "int timo" +This function atomically releases +.Fa rm +while waiting for an event. +The +.Fa rm +lock must be exclusively locked. +For more details on the parameters to this function, +see +.Xr sleep 9 . +.It Fn rm_assert "struct rmlock *rm" "int what" +This function asserts that the +.Fa rm +lock is in the state specified by +.Fa what . +If the assertions are not true and the kernel is compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the kernel will panic. +Currently the following base assertions are supported: +.Bl -tag -width ".Dv RA_UNLOCKED" +.It Dv RA_LOCKED +Assert that current thread holds either a shared or exclusive lock +of +.Fa rm . +.It Dv RA_RLOCKED +Assert that current thread holds a shared lock of +.Fa rm . +.It Dv RA_WLOCKED +Assert that current thread holds an exclusive lock of +.Fa rm . +.It Dv RA_UNLOCKED +Assert that current thread holds neither a shared nor exclusive lock of +.Fa rm . +.El +.Pp +In addition, one of the following optional flags may be specified with +.Dv RA_LOCKED , +.Dv RA_RLOCKED , +or +.Dv RA_WLOCKED : +.Bl -tag -width ".Dv RA_NOTRECURSED" +.It Dv RA_RECURSED +Assert that the current thread holds a recursive lock of +.Fa rm . +.It Dv RA_NOTRECURSED +Assert that the current thread does not hold a recursive lock of +.Fa rm . +.El +.El +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 , +.Xr panic 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 +.Sh HISTORY +These +functions appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An "Stephan Uphoff" . +This manual page was written by +.An "Gleb Smirnoff" +for rwlock and modified to reflect rmlock by +.An "Stephan Uphoff" . +.Sh BUGS +The +.Nm +implementation is currently not optimized for single processor systems. +.Pp +.Fn rm_try_rlock +can fail transiently even when there is no writer, while another reader +updates the state on the local CPU. +.Pp +The +.Nm +implementation uses a single per CPU list shared by all +rmlocks in the system. +If rmlocks become popular, hashing to multiple per CPU queues may +be needed to speed up the writer lock process. Property changes on: user/imp/camdoc/rmlock.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/sx.9 =================================================================== --- user/imp/camdoc/sx.9 (nonexistent) +++ user/imp/camdoc/sx.9 (revision 296049) @@ -0,0 +1,337 @@ +.\" +.\" Copyright (C) 2001 Jason Evans . 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 December 13, 2014 +.Dt SX 9 +.Os +.Sh NAME +.Nm sx , +.Nm sx_init , +.Nm sx_init_flags , +.Nm sx_destroy , +.Nm sx_slock , +.Nm sx_xlock , +.Nm sx_slock_sig , +.Nm sx_xlock_sig , +.Nm sx_try_slock , +.Nm sx_try_xlock , +.Nm sx_sunlock , +.Nm sx_xunlock , +.Nm sx_unlock , +.Nm sx_try_upgrade , +.Nm sx_downgrade , +.Nm sx_sleep , +.Nm sx_xholder , +.Nm sx_xlocked , +.Nm sx_assert , +.Nm SX_SYSINIT +.Nd kernel shared/exclusive lock +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/sx.h +.Ft void +.Fn sx_init "struct sx *sx" "const char *description" +.Ft void +.Fn sx_init_flags "struct sx *sx" "const char *description" "int opts" +.Ft void +.Fn sx_destroy "struct sx *sx" +.Ft void +.Fn sx_slock "struct sx *sx" +.Ft void +.Fn sx_xlock "struct sx *sx" +.Ft int +.Fn sx_slock_sig "struct sx *sx" +.Ft int +.Fn sx_xlock_sig "struct sx *sx" +.Ft int +.Fn sx_try_slock "struct sx *sx" +.Ft int +.Fn sx_try_xlock "struct sx *sx" +.Ft void +.Fn sx_sunlock "struct sx *sx" +.Ft void +.Fn sx_xunlock "struct sx *sx" +.Ft void +.Fn sx_unlock "struct sx *sx" +.Ft int +.Fn sx_try_upgrade "struct sx *sx" +.Ft void +.Fn sx_downgrade "struct sx *sx" +.Ft int +.Fn sx_sleep "void *chan" "struct sx *sx" "int priority" "const char *wmesg" "int timo" +.Ft "struct thread *" +.Fn sx_xholder "struct sx *sx" +.Ft int +.Fn sx_xlocked "const struct sx *sx" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn sx_assert "const struct sx *sx" "int what" +.In sys/kernel.h +.Fn SX_SYSINIT "name" "struct sx *sx" "const char *description" +.Sh DESCRIPTION +Shared/exclusive locks are used to protect data that are read far more often +than they are written. +Shared/exclusive locks do not implement priority propagation like mutexes and +reader/writer locks to prevent priority inversions, so +shared/exclusive locks should be used prudently. +.Pp +Shared/exclusive locks are created with either +.Fn sx_init +or +.Fn sx_init_flags +where +.Fa sx +is a pointer to space for a +.Vt struct sx , +and +.Fa description +is a pointer to a null-terminated character string that describes the +shared/exclusive lock. +The +.Fa opts +argument to +.Fn sx_init_flags +specifies a set of optional flags to alter the behavior of +.Fa sx . +It contains one or more of the following flags: +.Bl -tag -width SX_NOADAPTIVE +.It Dv SX_NOADAPTIVE +If the kernel is not compiled with +.Cd "options NO_ADAPTIVE_SX" , +then lock operations for +.Fa sx +will spin instead of sleeping while an exclusive lock holder is executing on +another CPU. +.It Dv SX_DUPOK +Witness should not log messages about duplicate locks being acquired. +.It Dv SX_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv SX_NOPROFILE +Do not profile this lock. +.It Dv SX_RECURSE +Allow threads to recursively acquire exclusive locks for +.Fa sx . +.It Dv SX_QUIET +Do not log any operations for this lock via +.Xr ktr 4 . +.It Dv SX_NEW +If the kernel has been compiled with +.Cd "options INVARIANTS" , +.Fn sx_init +will assert that the +.Fa sx +has not been initialized multiple times without intervening calls to +.Fn sx_destroy +unless this option is specified. +.El +.Pp +Shared/exclusive locks are destroyed with +.Fn sx_destroy . +The lock +.Fa sx +must not be locked by any thread when it is destroyed. +.Pp +Threads acquire and release a shared lock by calling +.Fn sx_slock , +.Fn sx_slock_sig +or +.Fn sx_try_slock +and +.Fn sx_sunlock +or +.Fn sx_unlock . +Threads acquire and release an exclusive lock by calling +.Fn sx_xlock , +.Fn sx_xlock_sig +or +.Fn sx_try_xlock +and +.Fn sx_xunlock +or +.Fn sx_unlock . +A thread can attempt to upgrade a currently held shared lock to an exclusive +lock by calling +.Fn sx_try_upgrade . +A thread that has an exclusive lock can downgrade it to a shared lock by +calling +.Fn sx_downgrade . +.Pp +.Fn sx_try_slock +and +.Fn sx_try_xlock +will return 0 if the shared/exclusive lock cannot be acquired immediately; +otherwise the shared/exclusive lock will be acquired and a non-zero value will +be returned. +.Pp +.Fn sx_try_upgrade +will return 0 if the shared lock cannot be upgraded to an exclusive lock +immediately; otherwise the exclusive lock will be acquired and a non-zero value +will be returned. +.Pp +.Fn sx_slock_sig +and +.Fn sx_xlock_sig +do the same as their normal versions but performing an interruptible sleep. +They return a non-zero value if the sleep has been interrupted by a signal +or an interrupt, otherwise 0. +.Pp +A thread can atomically release a shared/exclusive lock while waiting for an +event by calling +.Fn sx_sleep . +For more details on the parameters to this function, +see +.Xr sleep 9 . +.Pp +When compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the +.Fn sx_assert +function tests +.Fa sx +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 SA_UNLOCKED" +.It Dv SA_LOCKED +Assert that the current thread has either a shared or an exclusive lock on the +.Vt sx +lock pointed to by the first argument. +.It Dv SA_SLOCKED +Assert that the current thread has a shared lock on the +.Vt sx +lock pointed to by +the first argument. +.It Dv SA_XLOCKED +Assert that the current thread has an exclusive lock on the +.Vt sx +lock pointed to +by the first argument. +.It Dv SA_UNLOCKED +Assert that the current thread has no lock on the +.Vt sx +lock pointed to +by the first argument. +.El +.Pp +In addition, one of the following optional assertions may be included with +either an +.Dv SA_LOCKED , +.Dv SA_SLOCKED , +or +.Dv SA_XLOCKED +assertion: +.Bl -tag -width ".Dv SA_NOTRECURSED" +.It Dv SA_RECURSED +Assert that the current thread has a recursed lock on +.Fa sx . +.It Dv SA_NOTRECURSED +Assert that the current thread does not have a recursed lock on +.Fa sx . +.El +.Pp +.Fn sx_xholder +will return a pointer to the thread which currently holds an exclusive lock on +.Fa sx . +If no thread holds an exclusive lock on +.Fa sx , +then +.Dv NULL +is returned instead. +.Pp +.Fn sx_xlocked +will return non-zero if the current thread holds the exclusive lock; +otherwise, it will return zero. +.Pp +For ease of programming, +.Fn sx_unlock +is provided as a macro frontend to the respective functions, +.Fn sx_sunlock +and +.Fn sx_xunlock . +Algorithms that are aware of what state the lock is in should use either +of the two specific functions for a minor performance benefit. +.Pp +The +.Fn SX_SYSINIT +macro is used to generate a call to the +.Fn sx_sysinit +routine at system startup in order to initialize a given +.Fa sx +lock. +The parameters are the same as +.Fn sx_init +but with an additional argument, +.Fa name , +that is used in generating unique variable names for the related +structures associated with the lock and the sysinit routine. +.Pp +A thread may not hold both a shared lock and an exclusive lock on the same +lock simultaneously; +attempting to do so will result in deadlock. +.Sh CONTEXT +A thread may hold a shared or exclusive lock on an +.Nm +lock while sleeping. +As a result, an +.Nm +lock may not be acquired while holding a mutex. +Otherwise, if one thread slept while holding an +.Nm +lock while another thread blocked on the same +.Nm +lock after acquiring a mutex, then the second thread would effectively +end up sleeping while holding a mutex, which is not allowed. +.Sh SEE ALSO +.Xr lock 9 , +.Xr locking 9 , +.Xr mutex 9 , +.Xr panic 9 , +.Xr rwlock 9 , +.Xr sema 9 +.Sh BUGS +Currently there is no way to assert that a lock is not held. +This is not possible in the +.No non- Ns Dv WITNESS +case for asserting that this thread +does not hold a shared lock. +In the +.No non- Ns Dv WITNESS +case, the +.Dv SA_LOCKED +and +.Dv SA_SLOCKED +assertions merely check that some thread holds a shared lock. +They do not ensure that the current thread holds a shared lock. Property changes on: user/imp/camdoc/sx.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mutex.9 =================================================================== --- user/imp/camdoc/mutex.9 (nonexistent) +++ user/imp/camdoc/mutex.9 (revision 296049) @@ -0,0 +1,536 @@ +.\" +.\" Copyright (c) 1998 Berkeley Software Design, 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. +.\" 3. Berkeley Software Design Inc's name may not be used to endorse or +.\" promote products derived from this software without specific prior +.\" written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY BERKELEY SOFTWARE DESIGN INC ``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 BERKELEY SOFTWARE DESIGN INC 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. +.\" +.\" from BSDI $Id: mutex.4,v 1.1.2.3 1998/04/27 22:53:13 ewv Exp $ +.\" $FreeBSD$ +.\" +.Dd December 13, 2014 +.Dt MUTEX 9 +.Os +.Sh NAME +.Nm mutex , +.Nm mtx_init , +.Nm mtx_destroy , +.Nm mtx_lock , +.Nm mtx_lock_spin , +.Nm mtx_lock_flags , +.Nm mtx_lock_spin_flags , +.Nm mtx_trylock , +.Nm mtx_trylock_flags , +.Nm mtx_unlock , +.Nm mtx_unlock_spin , +.Nm mtx_unlock_flags , +.Nm mtx_unlock_spin_flags , +.Nm mtx_sleep , +.Nm mtx_initialized , +.Nm mtx_owned , +.Nm mtx_recursed , +.Nm mtx_assert , +.Nm MTX_SYSINIT +.Nd kernel synchronization primitives +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/mutex.h +.Ft void +.Fn mtx_init "struct mtx *mutex" "const char *name" "const char *type" "int opts" +.Ft void +.Fn mtx_destroy "struct mtx *mutex" +.Ft void +.Fn mtx_lock "struct mtx *mutex" +.Ft void +.Fn mtx_lock_spin "struct mtx *mutex" +.Ft void +.Fn mtx_lock_flags "struct mtx *mutex" "int flags" +.Ft void +.Fn mtx_lock_spin_flags "struct mtx *mutex" "int flags" +.Ft int +.Fn mtx_trylock "struct mtx *mutex" +.Ft int +.Fn mtx_trylock_flags "struct mtx *mutex" "int flags" +.Ft void +.Fn mtx_unlock "struct mtx *mutex" +.Ft void +.Fn mtx_unlock_spin "struct mtx *mutex" +.Ft void +.Fn mtx_unlock_flags "struct mtx *mutex" "int flags" +.Ft void +.Fn mtx_unlock_spin_flags "struct mtx *mutex" "int flags" +.Ft int +.Fn mtx_sleep "void *chan" "struct mtx *mtx" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn mtx_initialized "const struct mtx *mutex" +.Ft int +.Fn mtx_owned "const struct mtx *mutex" +.Ft int +.Fn mtx_recursed "const struct mtx *mutex" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn mtx_assert "const struct mtx *mutex" "int what" +.In sys/kernel.h +.Fn MTX_SYSINIT "name" "struct mtx *mtx" "const char *description" "int opts" +.Sh DESCRIPTION +Mutexes are the most basic and primary method of thread synchronization. +The major design considerations for mutexes are: +.Bl -enum +.It +Acquiring and releasing uncontested mutexes should be as cheap +as possible. +.It +They must have the information and storage space to support +priority propagation. +.It +A thread must be able to recursively acquire a mutex, +provided that the mutex is initialized to support recursion. +.El +.Pp +There are currently two flavors of mutexes, those that context switch +when they block and those that do not. +.Pp +By default, +.Dv MTX_DEF +mutexes will context switch when they are already held. +As an optimization, +they may spin for some amount +of time before context switching. +It is important to remember that since a thread may be preempted at any time, +the possible context switch introduced by acquiring a mutex is guaranteed +to not break anything that is not already broken. +.Pp +Mutexes which do not context switch are +.Dv MTX_SPIN +mutexes. +These should only be used to protect data shared with primary interrupt +code. +This includes interrupt filters and low level scheduling code. +In all architectures both acquiring and releasing of a +uncontested spin mutex is more expensive than the same operation +on a non-spin mutex. +In order to protect an interrupt service routine from blocking +against itself all interrupts are either blocked or deferred on a processor +while holding a spin lock. +It is permissible to hold multiple spin mutexes. +.Pp +Once a spin mutex has been acquired it is not permissible to acquire a +blocking mutex. +.Pp +The storage needed to implement a mutex is provided by a +.Vt struct mtx . +In general this should be treated as an opaque object and +referenced only with the mutex primitives. +.Pp +The +.Fn mtx_init +function must be used to initialize a mutex +before it can be passed to any of the other mutex functions. +The +.Fa name +option is used to identify the lock in debugging output etc. +The +.Fa type +option is used by the witness code to classify a mutex when doing checks +of lock ordering. +If +.Fa type +is +.Dv NULL , +.Fa name +is used in its place. +The pointer passed in as +.Fa name +and +.Fa type +is saved rather than the data it points to. +The data pointed to must remain stable +until the mutex is destroyed. +The +.Fa opts +argument is used to set the type of mutex. +It may contain either +.Dv MTX_DEF +or +.Dv MTX_SPIN +but not both. +If the kernel has been compiled with +.Cd "option INVARIANTS" , +.Fn mtx_init +will assert that the +.Fa mutex +has not been initialized multiple times without intervening calls to +.Fn mtx_destroy +unless the +.Dv MTX_NEW +option is specified. +See below for additional initialization options. +.Pp +The +.Fn mtx_lock +function acquires a +.Dv MTX_DEF +mutual exclusion lock +on behalf of the currently running kernel thread. +If another kernel thread is holding the mutex, +the caller will be disconnected from the CPU +until the mutex is available +(i.e., it will block). +.Pp +The +.Fn mtx_lock_spin +function acquires a +.Dv MTX_SPIN +mutual exclusion lock +on behalf of the currently running kernel thread. +If another kernel thread is holding the mutex, +the caller will spin until the mutex becomes available. +Interrupts are disabled during the spin and remain disabled +following the acquiring of the lock. +.Pp +It is possible for the same thread to recursively acquire a mutex +with no ill effects, provided that the +.Dv MTX_RECURSE +bit was passed to +.Fn mtx_init +during the initialization of the mutex. +.Pp +The +.Fn mtx_lock_flags +and +.Fn mtx_lock_spin_flags +functions acquire a +.Dv MTX_DEF +or +.Dv MTX_SPIN +lock, respectively, and also accept a +.Fa flags +argument. +In both cases, the only flags presently available for lock acquires are +.Dv MTX_QUIET +and +.Dv MTX_RECURSE . +If the +.Dv MTX_QUIET +bit is turned on in the +.Fa flags +argument, then if +.Dv KTR_LOCK +tracing is being done, +it will be silenced during the lock acquire. +If the +.Dv MTX_RECURSE +bit is turned on in the +.Fa flags +argument, then the mutex can be acquired recursively. +.Pp +The +.Fn mtx_trylock +attempts to acquire the +.Dv MTX_DEF +mutex pointed to by +.Fa mutex . +If the mutex cannot be immediately acquired +.Fn mtx_trylock +will return 0, +otherwise the mutex will be acquired +and a non-zero value will be returned. +.Pp +The +.Fn mtx_trylock_flags +function has the same behavior as +.Fn mtx_trylock +but should be used when the caller desires to pass in a +.Fa flags +value. +Presently, the only valid value in the +.Fn mtx_trylock +case is +.Dv MTX_QUIET , +and its effects are identical to those described for +.Fn mtx_lock +above. +.Pp +The +.Fn mtx_unlock +function releases a +.Dv MTX_DEF +mutual exclusion lock. +The current thread may be preempted if a higher priority thread is waiting +for the mutex. +.Pp +The +.Fn mtx_unlock_spin +function releases a +.Dv MTX_SPIN +mutual exclusion lock. +.Pp +The +.Fn mtx_unlock_flags +and +.Fn mtx_unlock_spin_flags +functions behave in exactly the same way as do the standard mutex +unlock routines above, while also allowing a +.Fa flags +argument which may specify +.Dv MTX_QUIET . +The behavior of +.Dv MTX_QUIET +is identical to its behavior in the mutex lock routines. +.Pp +The +.Fn mtx_destroy +function is used to destroy +.Fa mutex +so the data associated with it may be freed +or otherwise overwritten. +Any mutex which is destroyed +must previously have been initialized with +.Fn mtx_init . +It is permissible to have a single hold count +on a mutex when it is destroyed. +It is not permissible to hold the mutex recursively, +or have another thread blocked on the mutex +when it is destroyed. +.Pp +The +.Fn mtx_sleep +function is used to atomically release +.Fa mtx +while waiting for an event. +For more details on the parameters to this function, +see +.Xr sleep 9 . +.Pp +The +.Fn mtx_initialized +function returns non-zero if +.Fa mutex +has been initialized and zero otherwise. +.Pp +The +.Fn mtx_owned +function returns non-zero +if the current thread holds +.Fa mutex . +If the current thread does not hold +.Fa mutex +zero is returned. +.Pp +The +.Fn mtx_recursed +function returns non-zero if the +.Fa mutex +is recursed. +This check should only be made if the running thread already owns +.Fa mutex . +.Pp +The +.Fn mtx_assert +function allows assertions specified in +.Fa what +to be made about +.Fa mutex . +If the assertions are not true and the kernel is compiled with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the kernel will panic. +Currently the following assertions are supported: +.Bl -tag -width MA_NOTRECURSED +.It Dv MA_OWNED +Assert that the current thread +holds the mutex +pointed to by the first argument. +.It Dv MA_NOTOWNED +Assert that the current thread +does not hold the mutex +pointed to by the first argument. +.It Dv MA_RECURSED +Assert that the current thread has recursed on the mutex +pointed to by the first argument. +This assertion is only valid in conjunction with +.Dv MA_OWNED . +.It Dv MA_NOTRECURSED +Assert that the current thread has not recursed on the mutex +pointed to by the first argument. +This assertion is only valid in conjunction with +.Dv MA_OWNED . +.El +.Pp +The +.Fn MTX_SYSINIT +macro is used to generate a call to the +.Fn mtx_sysinit +routine at system startup in order to initialize a given mutex lock. +The parameters are the same as +.Fn mtx_init +but with an additional argument, +.Fa name , +that is used in generating unique variable names for the related structures associated with the lock and the sysinit routine. +.Ss The Default Mutex Type +Most kernel code should use the default lock type, +.Dv MTX_DEF . +The default lock type will allow the thread +to be disconnected from the CPU +if the lock is already held by another thread. +The implementation +may treat the lock as a short term spin lock +under some circumstances. +However, it is always safe to use these forms of locks +in an interrupt thread +without fear of deadlock +against an interrupted thread on the same CPU. +.Ss The Spin Mutex Type +A +.Dv MTX_SPIN +mutex will not relinquish the CPU +when it cannot immediately get the requested lock, +but will loop, waiting for the mutex to be released by another CPU. +This could result in deadlock +if another thread interrupted the thread which held a mutex +and then tried to acquire the mutex. +For this reason spin locks disable all interrupts on the local CPU. +.Pp +Spin locks are fairly specialized locks +that are intended to be held for very short periods of time. +Their primary purpose is to protect portions of the code +that implement other synchronization primitives such as default mutexes, +thread scheduling, and interrupt threads. +.Ss Initialization Options +The options passed in the +.Fa opts +argument of +.Fn mtx_init +specify the mutex type. +One of the +.Dv MTX_DEF +or +.Dv MTX_SPIN +options is required and only one of those two options may be specified. +The possibilities are: +.Bl -tag -width MTX_NOWITNESS +.It Dv MTX_DEF +Default mutexes +will always allow the current thread to be suspended +to avoid deadlock conditions against interrupt threads. +The implementation of this lock type +may spin for a while before suspending the current thread. +.It Dv MTX_SPIN +Spin mutexes +will never relinquish the CPU. +All interrupts are disabled on the local CPU +while any spin lock is held. +.It Dv MTX_RECURSE +Specifies that the initialized mutex is allowed to recurse. +This bit must be present if the mutex is permitted to recurse. +.It Dv MTX_QUIET +Do not log any mutex operations for this lock. +.It Dv MTX_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv MTX_DUPOK +Witness should not log messages about duplicate locks being acquired. +.It Dv MTX_NOPROFILE +Do not profile this lock. +.It Dv MTX_NEW +Do not check for double-init. +.El +.Ss Lock and Unlock Flags +The flags passed to the +.Fn mtx_lock_flags , +.Fn mtx_lock_spin_flags , +.Fn mtx_unlock_flags , +and +.Fn mtx_unlock_spin_flags +functions provide some basic options to the caller, +and are often used only under special circumstances to modify lock or +unlock behavior. +Standard locking and unlocking should be performed with the +.Fn mtx_lock , +.Fn mtx_lock_spin , +.Fn mtx_unlock , +and +.Fn mtx_unlock_spin +functions. +Only if a flag is required should the corresponding +flags-accepting routines be used. +.Pp +Options that modify mutex behavior: +.Bl -tag -width MTX_QUIET +.It Dv MTX_QUIET +This option is used to quiet logging messages during individual mutex +operations. +This can be used to trim superfluous logging messages for debugging purposes. +.El +.Ss Giant +If +.Va Giant +must be acquired, it must be acquired prior to acquiring +other mutexes. +Put another way: it is impossible to acquire +.Va Giant +non-recursively while +holding another mutex. +It is possible to acquire other mutexes while holding +.Va Giant , +and it is possible to acquire +.Va Giant +recursively while holding other mutexes. +.Ss Sleeping +Sleeping while holding a mutex (except for +.Va Giant ) +is never safe +and should be avoided. +There are numerous assertions which will fail if this is attempted. +.Ss Functions Which Access Memory in Userspace +No mutexes should be held (except for +.Va Giant ) +across functions which +access memory in userspace, such as +.Xr copyin 9 , +.Xr copyout 9 , +.Xr uiomove 9 , +.Xr fuword 9 , +etc. +No locks are needed when calling these functions. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr LOCK_PROFILING 9 , +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr panic 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 +.Sh HISTORY +These +functions appeared in +.Bsx 4.1 +and +.Fx 5.0 . Property changes on: user/imp/camdoc/mutex.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/rwlock.9 =================================================================== --- user/imp/camdoc/rwlock.9 (nonexistent) +++ user/imp/camdoc/rwlock.9 (revision 296049) @@ -0,0 +1,334 @@ +.\" Copyright (c) 2006 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 December 13, 2014 +.Dt RWLOCK 9 +.Os +.Sh NAME +.Nm rwlock , +.Nm rw_init , +.Nm rw_init_flags, +.Nm rw_destroy , +.Nm rw_rlock , +.Nm rw_wlock , +.Nm rw_runlock , +.Nm rw_wunlock , +.Nm rw_unlock , +.Nm rw_try_rlock , +.Nm rw_try_upgrade , +.Nm rw_try_wlock , +.Nm rw_downgrade , +.Nm rw_sleep , +.Nm rw_initialized , +.Nm rw_wowned , +.Nm rw_assert , +.Nm RW_SYSINIT +.Nd kernel reader/writer lock +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/rwlock.h +.Ft void +.Fn rw_init "struct rwlock *rw" "const char *name" +.Ft void +.Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts" +.Ft void +.Fn rw_destroy "struct rwlock *rw" +.Ft void +.Fn rw_rlock "struct rwlock *rw" +.Ft void +.Fn rw_wlock "struct rwlock *rw" +.Ft int +.Fn rw_try_rlock "struct rwlock *rw" +.Ft int +.Fn rw_try_wlock "struct rwlock *rw" +.Ft void +.Fn rw_runlock "struct rwlock *rw" +.Ft void +.Fn rw_wunlock "struct rwlock *rw" +.Ft void +.Fn rw_unlock "struct rwlock *rw" +.Ft int +.Fn rw_try_upgrade "struct rwlock *rw" +.Ft void +.Fn rw_downgrade "struct rwlock *rw" +.Ft int +.Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" +.Ft int +.Fn rw_initialized "const struct rwlock *rw" +.Ft int +.Fn rw_wowned "const struct rwlock *rw" +.Pp +.Cd "options INVARIANTS" +.Cd "options INVARIANT_SUPPORT" +.Ft void +.Fn rw_assert "const struct rwlock *rw" "int what" +.In sys/kernel.h +.Fn RW_SYSINIT "name" "struct rwlock *rw" "const char *desc" +.Sh DESCRIPTION +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 only read the protected data. +A thread with exclusive access is known as a +.Em writer +since it can modify protected data. +.Pp +Although reader/writer locks look very similar to +.Xr sx 9 +locks, their usage pattern is different. +Reader/writer locks can be treated as mutexes (see +.Xr mutex 9 ) +with shared/exclusive semantics. +Unlike +.Xr sx 9 , +an +.Nm +can be locked while holding a non-spin mutex, and an +.Nm +cannot be held while sleeping. +The +.Nm +locks have priority propagation like mutexes, but priority +can be propagated only to writers. +This limitation comes from the fact that readers +are anonymous. +Another important property is that readers can always recurse, +and exclusive locks can be made recursive selectively. +.Ss Macros and Functions +.Bl -tag -width indent +.It Fn rw_init "struct rwlock *rw" "const char *name" +Initialize structure located at +.Fa rw +as reader/writer lock, described by name +.Fa name . +The description is used solely for debugging purposes. +This function must be called before any other operations +on the lock. +.It Fn rw_init_flags "struct rwlock *rw" "const char *name" "int opts" +Initialize the rw lock just like the +.Fn rw_init +function, but specifying a set of optional flags to alter the +behaviour of +.Fa rw , +through the +.Fa opts +argument. +It contains one or more of the following flags: +.Bl -tag -width ".Dv RW_NOPROFILE" +.It Dv RW_DUPOK +Witness should not log messages about duplicate locks being acquired. +.It Dv RW_NOPROFILE +Do not profile this lock. +.It Dv RW_NOWITNESS +Instruct +.Xr witness 4 +to ignore this lock. +.It Dv RW_QUIET +Do not log any operations for this lock via +.Xr ktr 4 . +.It Dv RW_RECURSE +Allow threads to recursively acquire exclusive locks for +.Fa rw . +.It Dv RW_NEW +If the kernel has been compiled with +.Cd "option INVARIANTS" , +.Fn rw_init_flags +will assert that the +.Fa rw +has not been initialized multiple times without intervening calls to +.Fn rw_destroy +unless this option is specified. +.El +.It Fn rw_rlock "struct rwlock *rw" +Lock +.Fa rw +as a reader. +If any thread holds this lock exclusively, the current thread blocks, +and its priority is propagated to the exclusive holder. +The +.Fn rw_rlock +function can be called when the thread has already acquired reader +access on +.Fa rw . +This is called +.Dq "recursing on a lock" . +.It Fn rw_wlock "struct rwlock *rw" +Lock +.Fa rw +as a writer. +If there are any shared owners of the lock, the current thread blocks. +The +.Fn rw_wlock +function can be called recursively only if +.Fa rw +has been initialized with the +.Dv RW_RECURSE +option enabled. +.It Fn rw_try_rlock "struct rwlock *rw" +Try to lock +.Fa rw +as a reader. +This function will return true if the operation succeeds, otherwise 0 +will be returned. +.It Fn rw_try_wlock "struct rwlock *rw" +Try to lock +.Fa rw +as a writer. +This function will return true if the operation succeeds, otherwise 0 +will be returned. +.It Fn rw_runlock "struct rwlock *rw" +This function releases a shared lock previously acquired by +.Fn rw_rlock . +.It Fn rw_wunlock "struct rwlock *rw" +This function releases an exclusive lock previously acquired by +.Fn rw_wlock . +.It Fn rw_unlock "struct rwlock *rw" +This function releases a shared lock previously acquired by +.Fn rw_rlock +or an exclusive lock previously acquired by +.Fn rw_wlock . +.It Fn rw_try_upgrade "struct rwlock *rw" +Attempt to upgrade a single shared lock to an exclusive lock. +The current thread must hold a shared lock of +.Fa rw . +This will only succeed if the current thread holds the only shared lock on +.Fa rw , +and it only holds a single shared lock. +If the attempt succeeds +.Fn rw_try_upgrade +will return a non-zero value, +and the current thread will hold an exclusive lock. +If the attempt fails +.Fn rw_try_upgrade +will return zero, +and the current thread will still hold a shared lock. +.It Fn rw_downgrade "struct rwlock *rw" +Convert an exclusive lock into a single shared lock. +The current thread must hold an exclusive lock of +.Fa rw . +.It Fn rw_sleep "void *chan" "struct rwlock *rw" "int priority" "const char *wmesg" "int timo" +Atomically release +.Fa rw +while waiting for an event. +For more details on the parameters to this function, +see +.Xr sleep 9 . +.It Fn rw_initialized "const struct rwlock *rw" +This function returns non-zero if +.Fa rw +has been initialized, and zero otherwise. +.It Fn rw_destroy "struct rwlock *rw" +This functions destroys a lock previously initialized with +.Fn rw_init . +The +.Fa rw +lock must be unlocked. +.It Fn rw_wowned "const struct rwlock *rw" +This function returns a non-zero value if the current thread owns an +exclusive lock on +.Fa rw . +.It Fn rw_assert "const struct rwlock *rw" "int what" +This function allows assertions specified in +.Fa what +to be made about +.Fa rw . +If the assertions are not true and the kernel is compiled +with +.Cd "options INVARIANTS" +and +.Cd "options INVARIANT_SUPPORT" , +the kernel will panic. +Currently the following base assertions are supported: +.Bl -tag -width ".Dv RA_UNLOCKED" +.It Dv RA_LOCKED +Assert that current thread holds either a shared or exclusive lock +of +.Fa rw . +.It Dv RA_RLOCKED +Assert that current thread holds a shared lock of +.Fa rw . +.It Dv RA_WLOCKED +Assert that current thread holds an exclusive lock of +.Fa rw . +.It Dv RA_UNLOCKED +Assert that current thread holds neither a shared nor exclusive lock of +.Fa rw . +.El +.Pp +In addition, one of the following optional flags may be specified with +.Dv RA_LOCKED , +.Dv RA_RLOCKED , +or +.Dv RA_WLOCKED : +.Bl -tag -width ".Dv RA_NOTRECURSED" +.It Dv RA_RECURSED +Assert that the current thread holds a recursive lock of +.Fa rw . +.It Dv RA_NOTRECURSED +Assert that the current thread does not hold a recursive lock of +.Fa rw . +.El +.El +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 , +.Xr panic 9 , +.Xr sema 9 , +.Xr sx 9 +.Sh HISTORY +These +functions appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +facility was written by +.An "John Baldwin" . +This manual page was written by +.An "Gleb Smirnoff" . +.Sh BUGS +If +.Dv WITNESS +is not included in the kernel, +then it is impossible to assert that the current thread does or does not +hold a read lock. +In the +.Pf non- Dv WITNESS +case, the +.Dv RA_LOCKED +and +.Dv RA_RLOCKED +assertions merely check that some thread holds a read lock. +.Pp +Reader/writer is a bit of an awkward name. +An +.Nm +can also be called a +.Dq Robert Watson +lock if desired. Property changes on: user/imp/camdoc/rwlock.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/get_cyclecount.9 =================================================================== --- user/imp/camdoc/get_cyclecount.9 (nonexistent) +++ user/imp/camdoc/get_cyclecount.9 (revision 296049) @@ -0,0 +1,89 @@ +.\" Copyright (c) 2000 Mark R V Murray +.\" 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 15, 2011 +.Dt GET_CYCLECOUNT 9 +.Os +.Sh NAME +.Nm get_cyclecount +.Nd get the CPU's fast counter register contents +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In machine/cpu.h +.Ft uint64_t +.Fn get_cyclecount "void" +.Sh DESCRIPTION +The +.Fn get_cyclecount +function uses a register +available in most modern CPUs +to return a value +that is monotonically increasing +inside each CPU. +.Pp +On SMP systems, +there will be a number of +separate monotonic sequences, +one for each CPU running. +The value in the SMP case is +selected from one of these sequences, +dependent on which CPU +was scheduled to service the request. +.Pp +The speed and the maximum value +of each counter +is CPU-dependent. +Some CPUs +(such as the +.Tn Intel +80486) +do not have such a register, +so +.Fn get_cyclecount +on these platforms +returns a (monotonic) combination of numbers +represented by the +structure returned by +.Xr binuptime 9 . +.Pp +The +.Tn AMD64 +and +.Tn Intel 64 +processors use the +.Li TSC +register. +.Sh SEE ALSO +.Xr binuptime 9 +.Sh HISTORY +The +.Fn get_cyclecount +function first appeared in +.Fx 5.0 . +.Sh AUTHORS +This manual page was written by +.An Mark Murray Aq Mt markm@FreeBSD.org . Property changes on: user/imp/camdoc/get_cyclecount.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/sleepqueue.9 =================================================================== --- user/imp/camdoc/sleepqueue.9 (nonexistent) +++ user/imp/camdoc/sleepqueue.9 (revision 296049) @@ -0,0 +1,390 @@ +.\" Copyright (c) 2000-2004 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 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 September 22, 2014 +.Dt SLEEPQUEUE 9 +.Os +.Sh NAME +.Nm init_sleepqueues , +.Nm sleepq_abort , +.Nm sleepq_add , +.Nm sleepq_alloc , +.Nm sleepq_broadcast , +.Nm sleepq_free , +.Nm sleepq_lock , +.Nm sleepq_lookup , +.Nm sleepq_release , +.Nm sleepq_remove , +.Nm sleepq_signal , +.Nm sleepq_set_timeout , +.Nm sleepq_set_timeout_sbt , +.Nm sleepq_sleepcnt , +.Nm sleepq_timedwait , +.Nm sleepq_timedwait_sig , +.Nm sleepq_type , +.Nm sleepq_wait , +.Nm sleepq_wait_sig +.Nd manage the queues of sleeping threads +.Sh SYNOPSIS +.In sys/param.h +.In sys/sleepqueue.h +.Ft void +.Fn init_sleepqueues "void" +.Ft int +.Fn sleepq_abort "struct thread *td" +.Ft void +.Fn sleepq_add "void *wchan" "struct lock_object *lock" "const char *wmesg" "int flags" "int queue" +.Ft struct sleepqueue * +.Fn sleepq_alloc "void" +.Ft int +.Fn sleepq_broadcast "void *wchan" "int flags" "int pri" "int queue" +.Ft void +.Fn sleepq_free "struct sleepqueue *sq" +.Ft struct sleepqueue * +.Fn sleepq_lookup "void *wchan" +.Ft void +.Fn sleepq_lock "void *wchan" +.Ft void +.Fn sleepq_release "void *wchan" +.Ft void +.Fn sleepq_remove "struct thread *td" "void *wchan" +.Ft int +.Fn sleepq_signal "void *wchan" "int flags" "int pri" "int queue" +.Ft void +.Fn sleepq_set_timeout "void *wchan" "int timo" +.Ft void +.Fn sleepq_set_timeout_sbt "void *wchan" "sbintime_t sbt" \ +"sbintime_t pr" "int flags" +.Ft u_int +.Fn sleepq_sleepcnt "void *wchan" "int queue" +.Ft int +.Fn sleepq_timedwait "void *wchan" "int pri" +.Ft int +.Fn sleepq_timedwait_sig "void *wchan" "int pri" +.Ft int +.Fn sleepq_type "void *wchan" +.Ft void +.Fn sleepq_wait "void *wchan" "int pri" +.Ft int +.Fn sleepq_wait_sig "void *wchan" "int pri" +.Sh DESCRIPTION +Sleep queues provide a mechanism for suspending execution of a thread until +some condition is met. +Each queue is associated with a specific wait channel when it is active, +and only one queue may be associated with a wait channel at any given point +in time. +The implementation of each wait channel splits its sleepqueue into 2 sub-queues +in order to enable some optimizations on threads' wakeups. +An active queue holds a list of threads that are blocked on the associated +wait channel. +Threads that are not blocked on a wait channel have an associated inactive +sleep queue. +When a thread blocks on a wait channel it donates its inactive sleep queue +to the wait channel. +When a thread is resumed, +the wait channel that it was blocked on gives it an inactive sleep queue for +later use. +.Pp +The +.Fn sleepq_alloc +function allocates an inactive sleep queue and is used to assign a +sleep queue to a thread during thread creation. +The +.Fn sleepq_free +function frees the resources associated with an inactive sleep queue and is +used to free a queue during thread destruction. +.Pp +Active sleep queues are stored in a hash table hashed on the addresses pointed +to by wait channels. +Each bucket in the hash table contains a sleep queue chain. +A sleep queue chain contains a spin mutex and a list of sleep queues that hash +to that specific chain. +Active sleep queues are protected by their chain's spin mutex. +The +.Fn init_sleepqueues +function initializes the hash table of sleep queue chains. +.Pp +The +.Fn sleepq_lock +function locks the sleep queue chain associated with wait channel +.Fa wchan . +.Pp +The +.Fn sleepq_lookup +returns a pointer to the currently active sleep queue for that wait +channel associated with +.Fa wchan +or +.Dv NULL +if there is no active sleep queue associated with +argument +.Fa wchan . +It requires the sleep queue chain associated with +.Fa wchan +to have been locked by a prior call to +.Fn sleepq_lock . +.Pp +The +.Fn sleepq_release +function unlocks the sleep queue chain associated with +.Fn wchan +and is primarily useful when aborting a pending sleep request before one of +the wait functions is called. +.Pp +The +.Fn sleepq_add +function places the current thread on the sleep queue associated with the +wait channel +.Fa wchan . +The sleep queue chain associated with argument +.Fa wchan +must be locked by a prior call to +.Fn sleepq_lock +when this function is called. +If a lock is specified via the +.Fa lock +argument, and if the kernel was compiled with +.Cd "options INVARIANTS" , +then the sleep queue code will perform extra checks to ensure that +the lock is used by all threads sleeping on +.Fa wchan . +The +.Fa wmesg +parameter should be a short description of +.Fa wchan . +The +.Fa flags +parameter is a bitmask consisting of the type of sleep queue being slept on +and zero or more optional flags. +The +.Fa queue +parameter specifies the sub-queue, in which the contending thread will be +inserted. +.Pp +There are currently three types of sleep queues: +.Pp +.Bl -tag -width ".Dv SLEEPQ_CONDVAR" -compact +.It Dv SLEEPQ_CONDVAR +A sleep queue used to implement condition variables. +.It Dv SLEEPQ_SLEEP +A sleep queue used to implement +.Xr sleep 9 , +.Xr wakeup 9 +and +.Xr wakeup_one 9 . +.It Dv SLEEPQ_PAUSE +A sleep queue used to implement +.Xr pause 9 . +.El +.Pp +There are currently two optional flag: +.Pp +.Bl -tag -width ".Dv SLEEPQ_INTERRUPTIBLE" -compact +.It Dv SLEEPQ_INTERRUPTIBLE +The current thread is entering an interruptible sleep. +.El +.Bl -tag -width ".Dv SLEEPQ_STOP_ON_BDRY" -compact +.It Dv SLEEPQ_STOP_ON_BDRY +When thread is entering an interruptible sleep, do not stop it upon +arrival of stop action, like +.Dv SIGSTOP . +Wake it up instead. +.El +.Pp +A timeout on the sleep may be specified by calling +.Fn sleepq_set_timeout +after +.Fn sleepq_add . +The +.Fa wchan +parameter should be the same value from the preceding call to +.Fn sleepq_add , +and the sleep queue chain associated with +.Fa wchan +must have been locked by a prior call to +.Fn sleepq_lock . +The +.Fa timo +parameter should specify the timeout value in ticks. +.Pp +.Fn sleepq_set_timeout_sbt +function takes +.Fa sbt +argument instead of +.Fa timo . +It allows to specify relative or absolute wakeup time with higher resolution +in form of +.Vt sbintime_t . +The parameter +.Fa pr +allows to specify wanted absolute event precision. +The parameter +.Fa flags +allows to pass additional +.Fn callout_reset_sbt +flags. +.Pp +Once the thread is ready to suspend, +one of the wait functions is called to put the current thread to sleep +until it is awakened and to context switch to another thread. +The +.Fn sleepq_wait +function is used for non-interruptible sleeps that do not have a timeout. +The +.Fn sleepq_timedwait +function is used for non-interruptible sleeps that have had a timeout set via +.Fn sleepq_set_timeout . +The +.Fn sleepq_wait_sig +function is used for interruptible sleeps that do not have a timeout. +The +.Fn sleepq_timedwait_sig +function is used for interruptible sleeps that do have a timeout set. +The +.Fa wchan +argument to all of the wait functions is the wait channel being slept +on. +The sleep queue chain associated with argument +.Fa wchan +needs to have been locked with a prior call to +.Fn sleepq_lock . +The +.Fa pri +argument is used to set the priority of the thread when it is awakened. +If it is set to zero, the thread's priority is left alone. +.Pp +When the thread is resumed, +the wait functions return a non-zero value if the thread was awakened due to +an interrupt other than a signal or a timeout. +If the sleep timed out, then +.Er EWOULDBLOCK +is returned. +If the sleep was interrupted by something other than a signal, +then some other return value will be returned. +.Pp +A sleeping thread is normally resumed by the +.Fn sleepq_broadcast +and +.Fn sleepq_signal +functions. +The +.Fn sleepq_signal +function awakens the highest priority thread sleeping on a wait channel while +.Fn sleepq_broadcast +awakens all of the threads sleeping on a wait channel. +The +.Fa wchan +argument specifics which wait channel to awaken. +The +.Fa flags +argument must match the sleep queue type contained in the +.Fa flags +argument passed to +.Fn sleepq_add +by the threads sleeping on the wait channel. +If the +.Fa pri +argument does not equal \-1, +then each thread that is awakened will have its priority raised to +.Fa pri +if it has a lower priority. +The sleep queue chain associated with argument +.Fa wchan +must be locked by a prior call to +.Fn sleepq_lock +before calling any of these functions. +The +.Fa queue +argument specifies the sub-queue, from which threads need to be woken up. +.Pp +A thread in an interruptible sleep can be interrupted by another thread via +the +.Fn sleepq_abort +function. +The +.Fa td +argument specifies the thread to interrupt. +An individual thread can also be awakened from sleeping on a specific wait +channel via the +.Fn sleepq_remove +function. +The +.Fa td +argument specifies the thread to awaken and the +.Fa wchan +argument specifies the wait channel to awaken it from. +If the thread +.Fa td +is not blocked on the wait channel +.Fa wchan +then this function will not do anything, +even if the thread is asleep on a different wait channel. +This function should only be used if one of the other functions above is not +sufficient. +One possible use is waking up a specific thread from a widely shared sleep +channel. +.Pp +The +.Fn sleepq_sleepcnt +function offer a simple way to retrieve the number of threads sleeping for +the specified +.Fa queue , +given a +.Fa wchan . +.Pp +The +.Fn sleepq_type +function returns the type of +.Fa wchan +associated to a sleepqueue. +.Pp +The +.Fn sleepq_abort , +.Fn sleepq_broadcast , +and +.Fn sleepq_signal +functions all return a boolean value. +If the return value is true, +then at least one thread was resumed that is currently swapped out. +The caller is responsible for awakening the scheduler process so that the +resumed thread will be swapped back in. +This is done by calling the +.Fn kick_proc0 +function after releasing the sleep queue chain lock via a call to +.Fn sleepq_release . +.Pp +The sleep queue interface is currently used to implement the +.Xr sleep 9 +and +.Xr condvar 9 +interfaces. +Almost all other code in the kernel should use one of those interfaces rather +than manipulating sleep queues directly. +.Sh SEE ALSO +.Xr condvar 9 , +.Xr runqueue 9 , +.Xr scheduler 9 , +.Xr sleep 9 , +.Xr timeout 9 Property changes on: user/imp/camdoc/sleepqueue.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/domain.9 =================================================================== --- user/imp/camdoc/domain.9 (nonexistent) +++ user/imp/camdoc/domain.9 (revision 296049) @@ -0,0 +1,242 @@ +.\" +.\" Copyright (C) 2001 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 6, 2014 +.Dt DOMAIN 9 +.Os +.Sh NAME +.Nm domain_add , +.Nm pfctlinput , +.Nm pfctlinput2 , +.Nm pffinddomain , +.Nm pffindproto , +.Nm pffindtype , +.Nm DOMAIN_SET +.Nd "network domain management" +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/protosw.h +.In sys/domain.h +.Ft void +.Fn domain_add "void *data" +.Ft void +.Fn pfctlinput "int cmd" "struct sockaddr *sa" +.Ft void +.Fn pfctlinput2 "int cmd" "struct sockaddr *sa" "void *ctlparam" +.Ft struct domain * +.Fn pffinddomain "int family" +.Ft struct protosw * +.Fn pffindproto "int family" "int protocol" "int type" +.Ft struct protosw * +.Fn pffindtype "int family" "int type" +.Ft void +.Fn DOMAIN_SET "name" +.Sh DESCRIPTION +Network protocols installed in the system are maintained within what +are called domains +(for example the +.Va inetdomain +and +.Va localdomain ) . +.Bd -literal +struct domain { + int dom_family; /* AF_xxx */ + char *dom_name; + void (*dom_init) /* initialize domain data structures */ + (void); + void (*dom_destroy) /* cleanup structures / state */ + (void); + int (*dom_externalize) /* externalize access rights */ + (struct mbuf *, struct mbuf **); + void (*dom_dispose) /* dispose of internalized rights */ + (struct mbuf *); + struct protosw *dom_protosw, *dom_protoswNPROTOSW; + struct domain *dom_next; + int (*dom_rtattach) /* initialize routing table */ + (void **, int); + int (*dom_rtdetach) /* clean up routing table */ + (void **, int); + void *(*dom_ifattach)(struct ifnet *); + void (*dom_ifdetach)(struct ifnet *, void *); + int (*dom_ifmtu)(struct ifnet *); + /* af-dependent data on ifnet */ +}; +.Ed +.Pp +Each domain contains an array of protocol switch structures +.Pq Vt "struct protosw *" , +one for each socket type supported. +.Bd -literal +struct protosw { + short pr_type; /* socket type used for */ + struct domain *pr_domain; /* domain protocol a member of */ + short pr_protocol; /* protocol number */ + short pr_flags; /* see below */ +/* protocol-protocol hooks */ + pr_input_t *pr_input; /* input to protocol (from below) */ + pr_output_t *pr_output; /* output to protocol (from above) */ + pr_ctlinput_t *pr_ctlinput; /* control input (from below) */ + pr_ctloutput_t *pr_ctloutput; /* control output (from above) */ +/* utility hooks */ + pr_init_t *pr_init; + pr_destroy_t *pr_destroy; + pr_fasttimo_t *pr_fasttimo; /* fast timeout (200ms) */ + pr_slowtimo_t *pr_slowtimo; /* slow timeout (500ms) */ + pr_drain_t *pr_drain; /* flush any excess space possible */ + + struct pr_usrreqs *pr_usrreqs; /* user-protocol hook */ +}; +.Ed +.Pp +The following functions handle the registration of a new domain, +lookups of specific protocols and protocol types within those domains, +and handle control messages from the system. +.Pp +.Fn pfctlinput +is called by the system whenever an event occurs that could affect every +domain. +Examples of those types of events are routing table changes, interface +shutdowns or certain +.Tn ICMP +message types. +When called, +.Fn pfctlinput +calls the protocol specific +.Fn pr_ctlinput +function for each protocol in that has defined one, in every domain. +.Pp +.Fn pfctlinput2 +provides that same functionality of +.Fn pfctlinput , +but with a few additional checks and a new +.Vt "void *" +argument that is passed directly to the protocol's +.Fn pr_ctlinput +function. +Unlike +.Fn pfctlinput , +.Fn pfctlinput2 +verifies that +.Fa sa +is not +.Dv NULL , +and that only the protocol families that are the same as +.Fa sa +have their +.Fn pr_ctlinput +function called. +.Pp +.Fn domain_add +adds a new protocol domain to the system. +The argument +.Fa data +is cast directly to +.Vt "struct domain *" +within the function, but is declared +.Vt "void *" +in order to prevent compiler warnings when new domains are registered with +.Fn SYSINIT . +In most cases +.Fn domain_add +is not called directly, instead +.Fn DOMAIN_SET +is used. +.Pp +If the new domain has defined an initialization routine, it is called by +.Fn domain_add ; +as well, each of the protocols within the domain that have defined an +initialization routine will have theirs called. +.Pp +Once a domain is added it cannot be unloaded. +This is because there is +no reference counting system in place to determine if there are any +active references from sockets within that domain. +.Pp +.Fn pffinddomain +finds a domain by family. +If the domain cannot be found, +.Dv NULL +is returned. +.Pp +.Fn pffindtype +and +.Fn pffindproto +look up a protocol by its number or by its type. +In most cases, if the protocol or type cannot be found, +.Dv NULL +is returned, but +.Fn pffindproto +may return the default if the requested type is +.Dv SOCK_RAW , +a protocol switch type of +.Dv SOCK_RAW +is found, and the domain has a default raw protocol. +.Pp +Both functions are called by +.Fn socreate +in order to resolve the protocol for the socket currently being created. +.Pp +.Fn DOMAIN_SET +is a macro that simplifies the registration of a domain via +.Fn SYSINIT . +The code resulting from the macro expects there to be a domain structure +named +.Dq Fa name Ns Li domain +where +.Fa name +is the argument to +.Fn DOMAIN_SET : +.Bd -literal +struct domain localdomain = +{ AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose, + localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] }; + +DOMAIN_SET(local); +.Ed +.Sh RETURN VALUES +Both +.Fn pffindtype +and +.Fn pffindproto +return a +.Vt "struct protosw *" +for the protocol requested. +If the protocol or socket type is not found, +.Dv NULL +is returned. +In the case of +.Fn pffindproto , +the default protocol may be returned for +.Dv SOCK_RAW +types if the domain has a default raw protocol. +.Sh SEE ALSO +.Xr socket 2 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/domain.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/fetch.9 =================================================================== --- user/imp/camdoc/fetch.9 (nonexistent) +++ user/imp/camdoc/fetch.9 (revision 296049) @@ -0,0 +1,149 @@ +.\" $NetBSD: fetch.9,v 1.2 1996/01/09 21:59:24 perry Exp $ +.\" +.\" Copyright (c) 1996 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed by Kenneth Stailey. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 29, 2014 +.Dt FETCH 9 +.Os +.Sh NAME +.Nm fetch , +.Nm fubyte , +.Nm fuswintr , +.Nm fuword , +.Nm fuword16 , +.Nm fuword32 , +.Nm fuword64 , +.Nm fueword , +.Nm fueword32 , +.Nm fueword64 +.Nd fetch data from user-space +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn fubyte "volatile const void *base" +.Ft long +.Fn fuword "volatile const void *base" +.Ft int +.Fn fuword16 "volatile const void *base" +.Ft int32_t +.Fn fuword32 "volatile const void *base" +.Ft int64_t +.Fn fuword64 "volatile const void *base" +.Ft long +.Fn fueword "volatile const void *base" "long *val" +.Ft int32_t +.Fn fueword32 "volatile const void *base" "int32_t *val" +.Ft int64_t +.Fn fueword64 "volatile const void *base" "int64_t *val" +.In sys/resourcevar.h +.Ft int +.Fn fuswintr "void *base" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy small amounts of data from user-space +of the current process. +If read is successful, it is performed atomically. +The data read must be naturally aligned. +.Pp +The +.Nm +routines provide the following functionality: +.Bl -tag -width "fueword32()" +.It Fn fubyte +Fetches a byte of data from the user-space address +.Pa base . +The byte read is zero-extended into the results variable. +.It Fn fuword +Fetches a word of data (long) from the user-space address +.Pa base . +.It Fn fuword16 +Fetches 16 bits of data from the user-space address +.Pa base . +The half-word read is zero-extended into the results variable. +.It Fn fuword32 +Fetches 32 bits of data from the user-space address +.Pa base . +.It Fn fuword64 +Fetches 64 bits of data from the user-space address +.Pa base . +.It Fn fuswintr +Fetches a short word of data from the user-space address +.Pa base . +This function is safe to call during an interrupt context. +.It Fn fueword +Fetches a word of data (long) from the user-space address +.Pa base +and stores the result in the variable pointed by +.Pa val . +.It Fn fueword32 +Fetches 32 bits of data from the user-space address +.Pa base +and stores the result in the variable pointed by +.Pa val . +.It Fn fueword64 +Fetches 64 bits of data from the user-space address +.Pa base +and stores the result in the variable pointed by +.Pa val . +.El +.Pp +The callers of +.Fn fuword , +.Fn fuword32 +and +.Fn fuword64 +functions cannot distinguish between -1 read from +userspace and function failure. +.Sh RETURN VALUES +The +.Fn fubyte , +.Fn fuword , +.Fn fuword16 , +.Fn fuword32 , +.Fn fuword64 , +and +.Fn fuswintr +functions return the data fetched or -1 on failure. +The +.Fn fueword , +.Fn fueword32 +and +.Fn fueword64 +functions return 0 on success and -1 on failure. +.Sh SEE ALSO +.Xr copy 9 , +.Xr store 9 Property changes on: user/imp/camdoc/fetch.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/store.9 =================================================================== --- user/imp/camdoc/store.9 (nonexistent) +++ user/imp/camdoc/store.9 (revision 296049) @@ -0,0 +1,100 @@ +.\" $NetBSD: store.9,v 1.2 1996/01/09 21:59:27 perry Exp $ +.\" +.\" Copyright (c) 1996 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed by Kenneth Stailey. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 29, 2014 +.Dt STORE 9 +.Os +.Sh NAME +.Nm store , +.Nm subyte , +.Nm suswintr , +.Nm suword +.Nd store data to user-space +.Sh SYNOPSIS +.In sys/types.h +.In sys/time.h +.In sys/systm.h +.Ft int +.Fn subyte "volatile void *base" "int byte" +.Ft int +.Fn suword "volatile void *base" "long word" +.Ft int +.Fn suword16 "volatile void *base" "int word" +.Ft int +.Fn suword32 "volatile void *base" "int32_t word" +.Ft int +.Fn suword64 "volatile void *base" "int64_t word" +.In sys/resourcevar.h +.Ft int +.Fn suswintr "void *base" "int word" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy small amounts of data to user-space. +If write is successful, it is performed atomically. +The data written must be naturally aligned. +.Pp +The +.Nm +routines provide the following functionality: +.Bl -tag -width "suswintr()" +.It Fn subyte +Stores a byte of data to the user-space address +.Pa base . +.It Fn suword +Stores a word of data to the user-space address +.Pa base . +.It Fn suword16 +Stores 16 bits of data to the user-space address +.Pa base . +.It Fn suword32 +Stores 32 bits of data to the user-space address +.Pa base . +.It Fn suword64 +Stores 64 bits of data to the user-space address +.Pa base . +.It Fn suswintr +Stores a short word of data to the user-space address +.Pa base . +This function is safe to call during an interrupt context. +.El +.Sh RETURN VALUES +The +.Nm +functions return 0 on success or -1 on failure. +.Sh SEE ALSO +.Xr copy 9 , +.Xr fetch 9 Property changes on: user/imp/camdoc/store.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/casuword.9 =================================================================== --- user/imp/camdoc/casuword.9 (nonexistent) +++ user/imp/camdoc/casuword.9 (revision 296049) @@ -0,0 +1,95 @@ +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" Part of this documentation was written by +.\" Konstantin Belousov under sponsorship +.\" from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 21, 2014 +.Dt CASU 9 +.Os +.Sh NAME +.Nm casueword , +.Nm casueword32 , +.Nm casuword , +.Nm casuword32 +.Nd fetch, compare and store data from user-space +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn casueword "volatile u_long *base" "u_long oldval" "u_long *oldvalp" "u_long newval" +.Ft int +.Fn casueword32 "volatile uint32_t *base" "uint32_t oldval" "uint32_t *oldvalp" "uint32_t newval" +.Ft u_long +.Fn casuword "volatile u_long *base" "u_long oldval" "u_long newval" +.Ft uint32_t +.Fn casuword32 "volatile uint32_t *base" "uint32_t oldval" "uint32_t newval" +.Sh DESCRIPTION +The +.Nm +functions are designed to perform atomic compare-and-swap operation on +the value in the usermode memory of the current process. +.Pp +The +.Nm +routines reads the value from user memory with address +.Pa base , +and compare the value read with +.Pa oldval . +If the values are equal, +.Pa newval +is written to the +.Pa *base . +In case of +.Fn casueword32 +and +.Fn casueword , +old value is stored into the (kernel-mode) variable pointed by +.Pa *oldvalp . +The userspace value must be naturally aligned. +.Pp +The callers of +.Fn casuword +and +.Fn casuword32 +functions cannot distinguish between -1 read from +userspace and function failure. +.Sh RETURN VALUES +The +.Fn casuword +and +.Fn casuword32 +functions return the data fetched or -1 on failure. +The +.Fn casueword +and +.Fn casueword32 +functions return 0 on success and -1 on failure. +.Sh SEE ALSO +.Xr atomic 9 , +.Xr fetch 9 , +.Xr store 9 Property changes on: user/imp/camdoc/casuword.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/fpu_kern.9 =================================================================== --- user/imp/camdoc/fpu_kern.9 (nonexistent) +++ user/imp/camdoc/fpu_kern.9 (revision 296049) @@ -0,0 +1,200 @@ +.\" Copyright (c) 2014 +.\" Konstantin Belousov . All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd October 23, 2014 +.Dt FPU_KERN 9 +.Os +.Sh NAME +.Nm fpu_kern +.Nd "facility to use the FPU in the kernel" +.Sh SYNOPSIS +.Ft struct fpu_kern_ctx * +.Fn fpu_kern_alloc_ctx "u_int flags" +.Ft void +.Fn fpu_kern_free_ctx "struct fpu_kern_ctx *ctx" +.Ft int +.Fn fpu_kern_enter "struct thread *td" "struct fpu_kern_ctx *ctx" "u_int flags" +.Ft int +.Fn fpu_kern_leave "struct thread *td" "struct fpu_kern_ctx *ctx" +.Ft int +.Fn fpu_kern_thread "u_int flags" +.Ft int +.Fn is_fpu_kern_thread "u_int flags" +.Sh DESCRIPTION +The +.Nm +family of functions allows the use of FPU hardware in kernel code. +Modern FPUs are not limited to providing hardware implementation for +floating point arithmetic; they offer advanced accelerators for cryptography +and other computational-intensive algorithms. +These facilities share registers with the FPU hardware. +.Pp +Typical kernel code does not need access to the FPU. +Saving a large register file on each entry to the kernel would waste +time. +When kernel code uses the FPU, the current FPU state must be saved to +avoid corrupting the user-mode state, and vice versa. +.Pp +The management of the save and restore is automatic. +The processor catches accesses to the FPU registers +when the non-current context tries to access them. +Explicit calls are required for the allocation of the save area and +the notification of the start and end of the code using the FPU. +.Pp +The +.Fn fpu_kern_alloc_ctx +function allocates the memory used by +.Nm +to track the use of the FPU hardware state and the related software state. +The +.Fn fpu_kern_alloc_ctx +function requires the +.Fa flags +argument, which currently accepts the following flags: +.Bl -tag -width ".Dv FPU_KERN_NOWAIT" -offset indent +.It Dv FPU_KERN_NOWAIT +Do not wait for the available memory if the request could not be satisfied +without sleep. +.It 0 +No special handling is required. +.El +.Pp +The function returns the allocated context area, or +.Va NULL +if the allocation failed. +.Pp +The +.Fn fpu_kern_free_ctx +function frees the context previously allocated by +.Fn fpu_kern_alloc_ctx . +.Pp +The +.Fn fpu_kern_enter +function designates the start of the region of kernel code where the +use of the FPU is allowed. +Its arguments are: +.Bl -tag -width ".Fa ctx" -offset indent +.It Fa td +Currently must be +.Va curthread . +.It Fa ctx +The context save area previously allocated by +.Fn fpu_kern_alloc_ctx +and not currently in use by another call to +.Fn fpu_kern_enter . +.It Fa flags +This argument currently accepts the following flags: +.Bl -tag -width ".Dv FPU_KERN_NORMAL" -offset indent +.It Dv FPU_KERN_NORMAL +Indicates that the caller intends to access the full FPU state. +Must be specified currently. +.It Dv FPU_KERN_KTHR +Indicates that no saving of the current FPU state should be performed, +if the thread called +.Xr fpu_kern_thread 9 +function. +This is intended to minimize code duplication in callers which +could be used from both kernel thread and syscall contexts. +The +.Fn fpu_kern_leave +function correctly handles such contexts. +.El +.El +.Pp +The function does not sleep or block. +It could cause the +.Nm Device Not Available +exception during execution, and on the first FPU access after the +function returns, as well as after each context switch +(see Intel Software Developer Manual for the reference). +Currently, no errors are defined which can be returned by +.Fn fpu_kern_enter +to the caller. +.Pp +The +.Fn fpu_kern_leave +function ends the region started by +.Fn fpu_kern_enter . +The uses of FPU in the kernel after the call to +.Fn fpu_kern_leave +are erronous until the next call to +.Fn fpu_kern_enter +is performed. +The function takes the +.Fa td +thread argument, which currently must be +.Va curthread , +and the +.Fa ctx +context pointer, previously passed to +.Fn fpu_kern_enter . +After the function returns, the context may be freed or reused +by other invocation of +.Fn fpu_kern_enter . +There are no errors defined for the function, it always returns 0. +.Pp +The +.Fn fpu_kern_thread +function enables an optimization for threads which never leave to +the usermode. +The current thread will reuse the usermode save area for the kernel FPU state +instead of requiring an explicitly allocated context. +There are no flags defined for the function, and no error states +that the function returns. +Once this function has been called, neither +.Fn fpu_kern_enter +nor +.Fn fpu_kern_leave +is required to be called and the fpu is available for use in the calling thread. +.Pp +The +.Fn is_fpu_kern_thread +function returns the boolean indicating whether the current thread +entered the mode enabled by +.Fn fpu_kern_thread . +There is currently no flags defined for the function, the return +value is true if the current thread have the permanent FPU save area, +and false otherwise. +.Sh NOTES +The +.Nm +is currently implemented only for the i386 and amd64 architectures. +.Pp +There is no way to handle floating point exceptions raised from +kernel mode. +.Pp +The unused +.Fa flags +arguments +to the +.Nm +functions are to be extended to allow specification of the +set of the FPU hardware state used by the code region. +This would allow optimizations of saving and restoring the state. +.Sh AUTHORS +The +.Nm +facitily and this manual page were written by +.An Konstantin Belousov Aq Mt kib@FreeBSD.org . Property changes on: user/imp/camdoc/fpu_kern.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/sysctl_ctx_init.9 =================================================================== --- user/imp/camdoc/sysctl_ctx_init.9 (nonexistent) +++ user/imp/camdoc/sysctl_ctx_init.9 (revision 296049) @@ -0,0 +1,247 @@ +.\" +.\" Copyright (c) 2000, Andrzej Bialecki +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 31, 2014 +.Dt SYSCTL_CTX_INIT 9 +.Os +.Sh NAME +.Nm sysctl_ctx_init , +.Nm sysctl_ctx_free , +.Nm sysctl_ctx_entry_add , +.Nm sysctl_ctx_entry_find , +.Nm sysctl_ctx_entry_del +.Nd "sysctl context for managing dynamically created sysctl OIDs" +.Sh SYNOPSIS +.In sys/types.h +.In sys/sysctl.h +.Ft int +.Fo sysctl_ctx_init +.Fa "struct sysctl_ctx_list *clist" +.Fc +.Ft int +.Fo sysctl_ctx_free +.Fa "struct sysctl_ctx_list *clist" +.Fc +.Ft struct sysctl_ctx_entry * +.Fo sysctl_ctx_entry_add +.Fa "struct sysctl_ctx_list *clist" +.Fa "struct sysctl_oid *oidp" +.Fc +.Ft struct sysctl_ctx_entry * +.Fo sysctl_ctx_entry_find +.Fa "struct sysctl_ctx_list *clist" +.Fa "struct sysctl_oid *oidp" +.Fc +.Ft int +.Fo sysctl_ctx_entry_del +.Fa "struct sysctl_ctx_list *clist" +.Fa "struct sysctl_oid *oidp" +.Fc +.Sh DESCRIPTION +These functions provide an interface +for managing dynamically created OIDs. +The sysctl context is responsible for keeping track of created OIDs, +as well as their proper removal when needed. +It adds a simple transactional aspect to OID removal operations; +i.e., if a removal operation fails part way, +it is possible to roll back the sysctl tree +to its previous state. +.Pp +The +.Fn sysctl_ctx_init +function initializes a sysctl context. +The +.Fa clist +argument must point to an already allocated variable. +A context +.Em must +be initialized before use. +Once it is initialized, +a pointer to the context can be passed as an argument to all the +.Fa SYSCTL_ADD_* +macros (see +.Xr sysctl_add_oid 9 ) , +and it will be updated with entries pointing to newly created OIDS. +.Pp +Internally, the context is represented as a +.Xr queue 3 +TAILQ linked list. +The list consists of +.Li struct sysctl_ctx_entry +entries: +.Bd -literal -offset indent +struct sysctl_ctx_entry { + struct sysctl_oid *entry; + TAILQ_ENTRY(sysctl_ctx_entry) link; +}; + +TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry); +.Ed +.Pp +Each context entry points to one dynamic OID that it manages. +Newly created OIDs are always inserted in the front of the list. +.Pp +The +.Fn sysctl_ctx_free +function removes the context and associated OIDs it manages. +If the function completes successfully, +all managed OIDs have been unregistered +(removed from the tree) +and freed, +together with all their allocated memory, +and the entries of the context have been freed as well. +.Pp +The removal operation is performed in two steps. +First, for each context entry, the function +.Xr sysctl_remove_oid 9 +is executed, with parameter +.Fa del +set to 0, which inhibits the freeing of resources. +If there are no errors during this step, +.Fn sysctl_ctx_free +proceeds to the next step. +If the first step fails, +all unregistered OIDs associated with the context are registered again. +.Pp +.Em Note : +in most cases, the programmer specifies +.Dv OID_AUTO +as the OID number when creating an OID. +However, during registration of the OID in the tree, +this number is changed to the first available number +greater than or equal to +.Dv CTL_AUTO_START . +If the first step of context deletion fails, +re-registration of the OID does not change the already assigned OID number +(which is different from OID_AUTO). +This ensures that re-registered entries +maintain their original positions in the tree. +.Pp +The second step actually performs the deletion of the dynamic OIDs. +.Xr sysctl_remove_oid 9 +iterates through the context list, +starting from beginning (i.e., the newest entries). +.Em Important : +this time, the function not only deletes the OIDs from the tree, +but also frees their memory (provided that oid_refcnt == 0), +as well as the memory of all context entries. +.Pp +The +.Fn sysctl_ctx_entry_add +function allows the addition of an existing dynamic OID to a context. +.Pp +The +.Fn sysctl_ctx_entry_del +function removes an entry from the context. +.Em Important : +in this case, only the corresponding +.Li struct sysctl_ctx_entry +is freed, but the +.Fa oidp +pointer remains intact. +Thereafter, the programmer is responsible for managing the resources +allocated to this OID. +.Pp +The +.Fn sysctl_ctx_entry_find +function searches for a given +.Fa oidp +within a context list, +either returning a pointer to the +.Fa struct sysctl_ctx_entry +found, +or +.Dv NULL . +.Sh EXAMPLES +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 uses contexts to keep track of the OIDs. +.Bd -literal +#include + ... +static struct sysctl_ctx_list clist; +static struct sysctl_oid *oidp; +static int a_int; +static const char *string = "dynamic sysctl"; + ... + +sysctl_ctx_init(&clist); +oidp = SYSCTL_ADD_ROOT_NODE(&clist, + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); +oidp = SYSCTL_ADD_INT(&clist, SYSCTL_CHILDREN(oidp), + OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); + ... +oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug), + OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); +oidp = SYSCTL_ADD_STRING(&clist, SYSCTL_CHILDREN(oidp), + OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); + ... +/* Now we can free up the OIDs */ +if (sysctl_ctx_free(&clist)) { + printf("can't free this context - other OIDs depend on it"); + return (ENOTEMPTY); +} else { + printf("Success!\\n"); + return (0); +} +.Ed +.Pp +This example creates the following subtrees: +.Bd -literal -offset indent +debug.newtree.newstring +newtree.newint +.Ed +.Pp +Note that both trees are removed, and their resources freed, +through one +.Fn sysctl_ctx_free +call, which starts by freeing the newest entries (leaves) +and then proceeds to free the older entries (in this case the nodes). +.Sh SEE ALSO +.Xr queue 3 , +.Xr sysctl 8 , +.Xr sysctl 9 , +.Xr sysctl_add_oid 9 , +.Xr sysctl_remove_oid 9 +.Sh HISTORY +These functions first appeared in +.Fx 4.2 . +.Sh AUTHORS +.An Andrzej Bialecki Aq Mt abial@FreeBSD.org +.Sh BUGS +The current removal algorithm is somewhat heavy. +In the worst case, +all OIDs need to be unregistered, registered again, +and then unregistered and deleted. +However, the algorithm does guarantee transactional properties +for removal operations. +.Pp +All operations on contexts involve linked list traversal. +For this reason, +creation and removal of entries is relatively costly. Property changes on: user/imp/camdoc/sysctl_ctx_init.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/kernel_mount.9 =================================================================== --- user/imp/camdoc/kernel_mount.9 (nonexistent) +++ user/imp/camdoc/kernel_mount.9 (revision 296049) @@ -0,0 +1,211 @@ +.\" +.\" Copyright (c) 2004 Tom Rhodes +.\" 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 13, 2004 +.Dt KERNEL_MOUNT 9 +.Os +.Sh NAME +.Nm free_mntarg , +.Nm kernel_mount , +.Nm kernel_vmount , +.Nm mount_arg , +.Nm mount_argb , +.Nm mount_argf , +.Nm mount_argsu +.Nd "functions provided as part of the kernel mount interface" +.Sh SYNOPSIS +.Ft void +.Fn free_mntarg "struct mntarg *ma" +.Ft int +.Fn kernel_mount "struct mntarg *ma" "int flags" +.Ft int +.Fn kernel_vmount "int flags" ... +.Ft "struct mntarg *" +.Fo mount_arg +.Fa "struct mntarg *ma" "const char *name" "const void *val" "int len" +.Fc +.Ft "struct mntarg *" +.Fn mount_argb "struct mntarg *ma" "int flag" "const char *name" +.Ft "struct mntarg *" +.Fn mount_argf "struct mntarg *ma" "const char *name" "const char *fmt" ... +.Ft "struct mntarg *" +.Fo mount_argsu +.Fa "struct mntarg *ma" "const char *name" "const void *val" "int len" +.Fc +.Sh DESCRIPTION +The +.Fn kernel_mount +family of functions are provided as an API for building a list +of mount arguments which will be used to mount file systems +from inside the kernel. +By accumulating a list of arguments, the API takes shape and +provides the information necessary for the kernel to control +the +.Xr mount 8 +utility. +When an error occurs, the process will stop. +This will not cause a +.Xr panic 9 . +.Pp +The header of the structure is stored in +.Pa src/sys/kern/vfs_mount.c +which permits automatic structure creation to +ease the mount process. +Memory allocation must always be freed when the entire +process is complete, it is an error otherwise. +.Pp +The +.Fn free_mntarg +function is used to free or clear the +.Vt mntarg +structure. +.Pp +The +.Fn kernel_mount +function pulls information from the structure to perform +the mount request on a given file system. +Additionally, the +.Fn kernel_mount +function always calls the +.Fn free_mntarg +function. +If +.Fa ma +contains any error code generated during the construction, +that code will be called and the file system mount will +not be attempted. +.Pp +The +.Fn kernel_vmount +is a function similar to +.Xr printf 9 +which is used to mount a file system. +.Pp +The +.Fn mount_arg +function takes a plain argument and crafts parts of +the structure with regards to various mount options. +If the length is a value less than 0, +.Xr strlen 3 +is used. +This argument will be referenced until either +.Fn free_mntarg +or +.Fn kernel_mount +is called. +.Pp +The +.Fn mount_argb +function is used to add boolean arguments to +the structure. +The +.Fa flag +is the boolean value and +.Fa name +must start with +.Qq Li no , +otherwise a panic will occur. +.Pp +The +.Fn mount_argf +function adds +.Xr printf 9 +style arguments to the current structure. +.Pp +The +.Fn mount_argsu +function will add arguments to the structure from a +userland string. +.Sh EXAMPLES +An example of the +.Fn *_cmount +function: +.Bd -literal +static int +msdosfs_cmount(struct mntarg *ma, void *data, int flags, struct thread *td) +{ + struct msdosfs_args args; + int error; + + if (data == NULL) + return (EINVAL); + error = copyin(data, &args, sizeof(args)); + if (error) + return (error); + + ma = mount_argsu(ma, "from", args.fspec, MAXPATHLEN); + ma = mount_arg(ma, "export", &args.export, sizeof(args.export)); + ma = mount_argf(ma, "uid", "%d", args.uid); + ma = mount_argf(ma, "gid", "%d", args.gid); + ma = mount_argf(ma, "mask", "%d", args.mask); + ma = mount_argf(ma, "dirmask", "%d", args.dirmask); + + ma = mount_argb(ma, args.flags & MSDOSFSMNT_SHORTNAME, "noshortname"); + ma = mount_argb(ma, args.flags & MSDOSFSMNT_LONGNAME, "nolongname"); + ma = mount_argb(ma, !(args.flags & MSDOSFSMNT_NOWIN95), "nowin95"); + ma = mount_argb(ma, args.flags & MSDOSFSMNT_KICONV, "nokiconv"); + + ma = mount_argsu(ma, "cs_win", args.cs_win, MAXCSLEN); + ma = mount_argsu(ma, "cs_dos", args.cs_dos, MAXCSLEN); + ma = mount_argsu(ma, "cs_local", args.cs_local, MAXCSLEN); + + error = kernel_mount(ma, flags); + + return (error); +} +.Ed +.Pp +When working with +.Fn kernel_vmount , +.Fa varargs +must come in pairs, e.g., +.Brq Va name , value . +.Bd -literal + error = kernel_vmount( + MNT_RDONLY, + "fstype", vfsname, + "fspath", "/", + "from", path, + NULL); +.Ed +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_MOUNT 9 +.Sh HISTORY +The +.Fn kernel_mount +family of functions and this manual page first +appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +The +.Fn kernel_mount +family of functions and API was developed by +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . +This manual page was written by +.An Tom Rhodes Aq Mt trhodes@FreeBSD.org . Property changes on: user/imp/camdoc/kernel_mount.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_unwire.9 =================================================================== --- user/imp/camdoc/pmap_unwire.9 (nonexistent) +++ user/imp/camdoc/pmap_unwire.9 (revision 296049) @@ -0,0 +1,65 @@ +.\" +.\" Copyright (c) 2014 Alan L. Cox +.\" 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 17, 2014 +.Dt PMAP_UNWIRE 9 +.Os +.Sh NAME +.Nm pmap_unwire +.Nd unwire a range of virtual pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_unwire +.Fa "pmap_t pmap" "vm_offset_t start" "vm_offset_t end" +.Fc +.Sh DESCRIPTION +The function +.Fn pmap_unwire +removes the wired attribute from each of the virtual-to-physical page mappings +within the virtual address range from +.Fa start +to +.Fa end +of the physical map +.Fa pmap . +Every valid mapping within that range is required to have the wired attribute +set. +Invalid mappings are ignored, since they cannot have the wired attribute set. +.Sh NOTES +Only the function +.Xr pmap_enter 9 +can be used to set the wired attribute of a virtual-to-physical page mapping. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_enter 9 , +.Xr pmap_wired_count 9 +.Sh AUTHORS +This manual page was written by +.An Alan L. Cox Aq alc@rice.edu . Property changes on: user/imp/camdoc/pmap_unwire.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/VOP_INACTIVE.9 =================================================================== --- user/imp/camdoc/VOP_INACTIVE.9 (nonexistent) +++ user/imp/camdoc/VOP_INACTIVE.9 (revision 296049) @@ -0,0 +1,78 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 27, 2014 +.Dt VOP_INACTIVE 9 +.Os +.Sh NAME +.Nm VOP_INACTIVE , +.Nm VOP_RECLAIM +.Nd reclaim file system resources for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_INACTIVE "struct vnode *vp" "struct thread *td" +.Ft int +.Fn VOP_RECLAIM "struct vnode *vp" "struct thread *td" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode being reclaimed. +.El +.Pp +.Fn VOP_INACTIVE +is called when the kernel is no longer using the vnode. +This may be +because the reference count reaches zero or it may be that the +file system is being forcibly unmounted while there are open files. +It can be used to reclaim space for +.Sq open but deleted +files. +.Pp +.Fn VOP_RECLAIM +is called when a vnode is being reused for a different file system. +Any file system specific resources associated with the vnode should be +freed. +.Sh LOCKS +For both +.Fn VOP_INACTIVE +and +.Fn VOP_RECLAIM , +the +.Fa vp +will be exclusively locked on entry, and must be left exclusively +locked on return. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_INACTIVE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/PCBGROUP.9 =================================================================== --- user/imp/camdoc/PCBGROUP.9 (nonexistent) +++ user/imp/camdoc/PCBGROUP.9 (revision 296049) @@ -0,0 +1,221 @@ +.\" Copyright (c) 2014 Adrian Chadd +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 23, 2014 +.Dt PCBGROUP 9 +.Os +.Sh NAME +.Nm PCBGROUP +.Nd Distributed Protocol Control Block Groups +.Sh SYNOPSIS +.Cd "options PCBGROUP" +.Pp +.In sys/param.h +.In netinet/in.h +.In netinet/in_pcb.h +.Ft void +.Fo in_pcbgroup_init +.Fa "struct inpcbinfo *pcbinfo" "u_int hashfields" "int hash_nelements" +.Fc +.Ft void +.Fn in_pcbgroup_destroy "struct inpcbinfo *pcbinfo" +.Ft struct inpcbgroup * +.Fo in_pcbgroup_byhash +.Fa "struct inpcbinfo *pcbinfo" "u_int hashtype" "uint32_t hash" +.Fc +.Ft struct inpcbgroup * +.Fn in_pcbgroup_byinpcb "struct inpcb *inp" +.Ft void +.Fn in_pcbgroup_update "struct inpcb *inp" +.Ft void +.Fn in_pcbgroup_update_mbuf "struct inpcb *inp" "struct mbuf *m" +.Ft void +.Fn in_pcbgroup_remove "struct inpcb *inp" +.Ft int +.Fn in_pcbgroup_enabled "struct inpcbinfo *pcbinfo" +.In netinet6/in6_pcb.h +.Ft struct inpcbgroup * +.Fo in6_pcbgroup_byhash +.Fa "struct inpcbinfo *pcbinfo" "u_int hashtype" "uint32_t hash" +.Fc +.Sh DESCRIPTION +This implementation introduces notions of affinity +for connections and distribute work so as to reduce lock contention, +with hardware work distribution strategies +such as RSS. +In this construction, connection groups supplement, rather than replace, +existing reservation tables for protocol 4-tuples, offering CPU-affine +lookup tables with minimal cache line migration and lock contention +during steady state operation. +.Pp +Internet protocols like UDP and TCP register to use connection groups +by providing an ipi_hashfields value other than IPI_HASHFIELDS_NONE. +This indicates to the connection group code whether a 2-tuple or +4-tuple is used as an argument to hashes that assign a connection to +a particular group. +This must be aligned with any hardware-offloaded distribution model, +such as RSS or similar approaches taken in embedded network boards. +Wildcard sockets require special handling, as in Willmann 2006, and +are shared between connection groups while being protected by +group-local locks. +Connection establishment and teardown can be signficantly more +expensive than without connection groups, but that steady-state +processing can be significantly faster. +.Pp +Enabling PCBGROUP in the kernel only provides the infrastructure +required to create and manage multiple PCB groups. +An implementation needs to fill in a few functions to provide PCB +group hash information in order for PCBs to be placed in a PCB group. +.Ss Operation +By default, each PCB info block (struct pcbinfo) has a single hash for +all PCB entries for the given protocol with a single lock protecting it. +This can be a significant source of lock contention on SMP hardware. +When a PCBGROUP is created, an array of separate hash tables are +created, each with its own lock. +A separate table for wildcard PCBs is provided. +By default, a PCBGROUP table is created for each available CPU. +The PCBGROUP code attempts to calculate a hash value from the given +PCB or mbuf when looking up a PCBGROUP. +While processing a received frame, +.Fn in_pcbgroup_byhash +can be used in conjunction with either a hardware-provided hash +value +.Po +eg the +.Xr RSS 9 +calculated hash value provided by some NICs +.Pc +or a software-provided hash value in order to choose a PCBGROUP +table to query. +A single table lock is held while performing a wildcard match. +However, all of the table locks are acquired before modifying the +wildcard table. +The PCBGROUP tables operate in conjunction with the normal single PCB list +in a PCB info block. +Thus, inserting and removing a PCB will still incur the same costs +as without PCBGROUP. +A protocol which uses PCBGROUP should fall back to the normal PCB list +lookup if a call to the PCBGROUP layer does not yield a lookup hit. +.Ss Usage +Initialize a PCBGROUP in a PCB info block +.Pq Vt "struct pcbinfo" +by calling +.Fn in_pcbgroup_init . +.Pp +Add a connection to a PCBGROUP with +.Fn in_pcbgroup_update . +Connections are removed by with +.Fn in_pcbgroup_remove . +These in turn will determine which PCBGROUP bucket the given PCB +is placed into and calculate the hash value appropriately. +.Pp +Wildcard PCBs are hashed differently and placed in a single wildcard +PCB list. +If +.Xr RSS 9 +is enabled and in use, RSS-aware wildcard PCBs are placed in a single +PCBGROUP based on RSS information. +Protocols may look up the PCB entry in a PCBGROUP by using the lookup +functions +.Fn in_pcbgroup_byhash +and +.Fn in_pcbgroup_byinpcb . +.Sh IMPLEMENTATION NOTES +The PCB code in +.Pa sys/netinet +and +.Pa sys/netinet6 +is aware of PCBGROUP and will call into the PCBGROUP code to do +PCBGROUP assignment and lookup, preferring a PCBGROUP lookup to the +default global PCB info table. +.Pp +An implementor wishing to experiment or modify the PCBGROUP assignment +should modify this set of functions: +.Bl -tag -width "12345678" -offset indent +.It Fn in_pcbgroup_getbucket No and Fn in6_pcbgroup_getbucket +Map a given 32 bit hash value to a PCBGROUP. +By default this is hash % number_of_pcbgroups. +However, this distribution may not align with NIC receive queues or +the +.Xr netisr 9 +configuration. +.It Fn in_pcbgroup_byhash No and Fn in6_pcbgroup_byhash +Map a 32 bit hash value and a hash type identifier to a PCBGROUP. +By default, this simply returns NULL. +This function is used by the +.Xr mbuf 9 +receive path in +.Pa sys/netinet/in_pcb.c +to map an mbuf to a PCBGROUP. +.It Fn in_pcbgroup_bytuple No and Fn in6_pcbgroup_bytuple +Map the source and destination address and port details to a PCBGROUP. +By default, this does a very simple XOR hash. +This function is used by both the PCB lookup code and as a fallback in +the +.Xr mbuf 9 +receive path in +.Pa sys/netinet/in_pcb.c . +.El +.Sh SEE ALSO +.Xr mbuf 9 , +.Xr netisr 9 , +.Xr RSS 9 +.Rs +.%A Paul Willmann +.%A Scott Rixner +.%A Alan L. Cox +.%T "An Evaluation of Network Stack Parallelization Strategies in Modern Operating Systems" +.%J "2006 USENIX Annual Technical Conference" +.%D 2006 +.%U http://www.ece.rice.edu/~willmann/pubs/paranet_usenix.pdf +.Re +.Sh HISTORY +PCBGROUP first appeared in +.Fx 9.0 . +.Sh AUTHORS +.An -nosplit +The PCBGROUP implementation was written by +.An Robert N. M. Watson Aq Mt rwatson@FreeBSD.org +under contract to Juniper Networks, Inc. +.Pp +This manual page written by +.An Adrian Chadd Aq Mt adrian@FreeBSD.org . +.Sh NOTES +The +.Xr RSS 9 +implementation currently uses +.Ic #ifdef +blocks to tie into PCBGROUP. +This is a sign that a more abstract programming API is needed. +.Pp +There is currently no support for re-balancing the PCBGROUP assignment, +nor is there any support for overriding which PCBGROUP a socket/PCB +should be in. +.Pp +No statistics are kept to indicate how often PCBGROUP lookups +succeed or fail. Property changes on: user/imp/camdoc/PCBGROUP.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/pmap_protect.9 =================================================================== --- user/imp/camdoc/pmap_protect.9 (nonexistent) +++ user/imp/camdoc/pmap_protect.9 (revision 296049) @@ -0,0 +1,57 @@ +.\" +.\" 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 July 18, 2014 +.Dt PMAP_PROTECT 9 +.Os +.Sh NAME +.Nm pmap_protect +.Nd set physical page protection +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_protect +.Fa "pmap_t pmap" "vm_offset_t sva" "vm_offset_t eva" "vm_prot_t prot" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_protect +function sets the physical page permissions to +.Fa prot +for all physical pages in the physical map +.Fa pmap +in the virtual address range between +.Fa sva +and +.Fa eva . +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_protect.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/socket.9 =================================================================== --- user/imp/camdoc/socket.9 (nonexistent) +++ user/imp/camdoc/socket.9 (revision 296049) @@ -0,0 +1,636 @@ +.\"- +.\" Copyright (c) 2006 Robert N. M. Watson +.\" Copyright (c) 2014 Benjamin J. Kaduk +.\" 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 26, 2014 +.Dt SOCKET 9 +.Os +.Sh NAME +.Nm socket +.Nd "kernel socket interface" +.Sh SYNOPSIS +.In sys/socket.h +.In sys/socketvar.h +.Ft void +.Fn soabort "struct socket *so" +.Ft int +.Fn soaccept "struct socket *so" "struct sockaddr **nam" +.Ft int +.Fn socheckuid "struct socket *so" "uid_t uid" +.Ft int +.Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td" +.Ft void +.Fn soclose "struct socket *so" +.Ft int +.Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td" +.Ft int +.Fo socreate +.Fa "int dom" "struct socket **aso" "int type" "int proto" +.Fa "struct ucred *cred" "struct thread *td" +.Fc +.Ft int +.Fn sodisconnect "struct socket *so" +.Ft struct sockaddr * +.Fn sodupsockaddr "const struct sockaddr *sa" "int mflags" +.Ft void +.Fn sofree "struct socket *so" +.Ft void +.Fn sohasoutofband "struct socket *so" +.Ft int +.Fn solisten "struct socket *so" "int backlog" "struct thread *td" +.Ft void +.Fn solisten_proto "struct socket *so" "int backlog" +.Ft int +.Fn solisten_proto_check "struct socket *so" +.Ft struct socket * +.Fn sonewconn "struct socket *head" "int connstatus" +.Ft int +.Fo sopoll +.Fa "struct socket *so" "int events" "struct ucred *active_cred" +.Fa "struct thread *td" +.Fc +.Ft int +.Fo sopoll_generic +.Fa "struct socket *so" "int events" "struct ucred *active_cred" +.Fa "struct thread *td" +.Fc +.Ft int +.Fo soreceive +.Fa "struct socket *so" "struct sockaddr **psa" "struct uio *uio" +.Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp" +.Fc +.Ft int +.Fo soreceive_stream +.Fa "struct socket *so" "struct sockaddr **paddr" +.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" +.Fa "int *flagsp" +.Fc +.Ft int +.Fo soreceive_dgram +.Fa "struct socket *so" "struct sockaddr **paddr" +.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" +.Fa "int *flagsp" +.Fc +.Ft int +.Fo soreceive_generic +.Fa "struct socket *so" "struct sockaddr **paddr" +.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp" +.Fa "int *flagsp" +.Fc +.Ft int +.Fn soreserve "struct socket *so" "u_long sndcc" "u_long rcvcc" +.Ft void +.Fn sorflush "struct socket *so" +.Ft int +.Fo sosend +.Fa "struct socket *so" "struct sockaddr *addr" "struct uio *uio" +.Fa "struct mbuf *top" "struct mbuf *control" "int flags" "struct thread *td" +.Fc +.Ft int +.Fo sosend_dgram +.Fa "struct socket *so" "struct sockaddr *addr" +.Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control" +.Fa "int flags" "struct thread *td" +.Fc +.Ft int +.Fo sosend_generic +.Fa "struct socket *so" "struct sockaddr *addr" +.Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control" +.Fa "int flags" "struct thread *td" +.Fc +.Ft int +.Fn soshutdown "struct socket *so" "int how" +.Ft void +.Fn sotoxsocket "struct socket *so" "struct xsocket *xso" +.Ft void +.Fn soupcall_clear "struct socket *so" "int which" +.Ft void +.Fo soupcall_set +.Fa "struct socket *so" "int which" +.Fa "int (*func)(struct socket *, void *, int)" "void *arg" +.Fc +.Ft void +.Fn sowakeup "struct socket *so" "struct sockbuf *sb" +.In sys/sockopt.h +.Ft int +.Fn sosetopt "struct socket *so" "struct sockopt *sopt" +.Ft int +.Fn sogetopt "struct socket *so" "struct sockopt *sopt" +.Ft int +.Fn sooptcopyin "struct sockopt *sopt" "void *buf" "size_t len" "size_t minlen" +.Ft int +.Fn sooptcopyout "struct sockopt *sopt" "const void *buf" "size_t len" +.Sh DESCRIPTION +The kernel +.Nm +programming interface permits in-kernel consumers to interact with +local and network socket objects in a manner similar to that permitted using +the +.Xr socket 2 +user API. +These interfaces are appropriate for use by distributed file systems and +other network-aware kernel services. +While the user API operates on file descriptors, the kernel interfaces +operate directly on +.Vt "struct socket" +pointers. +Some portions of the kernel API exist only to implement the user API, +and are not expected to be used by kernel code. +The portions of the socket API used by socket consumers and +implementations of network protocols will differ; some routines +are only useful for protocol implementors. +.Pp +Except where otherwise indicated, +.Nm +functions may sleep, and are not appropriate for use in an +.Xr ithread 9 +context or while holding non-sleepable kernel locks. +.Ss Creating and Destroying Sockets +A new socket may be created using +.Fn socreate . +As with +.Xr socket 2 , +arguments specify the requested domain, type, and protocol via +.Fa dom , type , +and +.Fa proto . +The socket is returned via +.Fa aso +on success. +In addition, the credential used to authorize operations associated with the +socket will be passed via +.Fa cred +(and will be cached for the lifetime of the socket), and the thread +performing the operation via +.Fa td . +.Em Warning : +authorization of the socket creation operation will be performed +using the thread credential for some protocols (such as raw sockets). +.Pp +Sockets may be closed and freed using +.Fn soclose , +which has similar semantics to +.Xr close 2 . +.Pp +In certain circumstances, it is appropriate to destroy a socket without +waiting for it to disconnect, for which +.Fn soabort +is used. +This is only appropriate for incoming connections which are in a +partially connected state. +It must be called on an unreferenced socket, by the thread which +removed the socket from its listen queue, to prevent races. +It will call into protocol code, so no socket locks may be held +over the call. +The caller of +.Fn soabort +is responsible for setting the VNET context. +The normal path to freeing a socket is +.Fn sofree , +which handles reference counting on the socket. +It should be called whenever a reference is released, and also whenever +reference flags are cleared in socket or protocol code. +Calls to +.Fn sofree +should not be made from outside the socket layer; outside callers +should use +.Fn soclose +instead. +.Ss Connections and Addresses +The +.Fn sobind +function is equivalent to the +.Xr bind 2 +system call, and binds the socket +.Fa so +to the address +.Fa nam . +The operation would be authorized using the credential on thread +.Fa td . +.Pp +The +.Fn soconnect +function is equivalent to the +.Xr connect 2 +system call, and initiates a connection on the socket +.Fa so +to the address +.Fa nam . +The operation will be authorized using the credential on thread +.Fa td . +Unlike the user system call, +.Fn soconnect +returns immediately; the caller may +.Xr msleep 9 +on +.Fa so->so_timeo +while holding the socket mutex and waiting for the +.Dv SS_ISCONNECTING +flag to clear or +.Fa so->so_error +to become non-zero. +If +.Fn soconnect +fails, the caller must manually clear the +.Dv SS_ISCONNECTING +flag. +.Pp +A call to +.Fn sodisconnect +disconnects the socket without closing it. +.Pp +The +.Fn soshutdown +function is equivalent to the +.Xr shutdown 2 +system call, and causes part or all of a connection on a socket to be closed +down. +.Pp +Sockets are transitioned from non-listening status to listening with +.Fn solisten . +.Ss Socket Options +The +.Fn sogetopt +function is equivalent to the +.Xr getsockopt 2 +system call, and retrieves a socket option on socket +.Fa so . +The +.Fn sosetopt +function is equivalent to the +.Xr setsockopt 2 +system call, and sets a socket option on socket +.Fa so . +.Pp +The second argument in both +.Fn sogetopt +and +.Fn sosetopt +is the +.Fa sopt +pointer to a +.Vt "struct sopt" +describing the socket option operation. +The caller-allocated structure must be zeroed, and then have its fields +initialized to specify socket option operation arguments: +.Bl -tag -width ".Va sopt_valsize" +.It Va sopt_dir +Set to +.Dv SOPT_SET +or +.Dv SOPT_GET +depending on whether this is a get or set operation. +.It Va sopt_level +Specify the level in the network stack the operation is targeted at; for +example, +.Dv SOL_SOCKET . +.It Va sopt_name +Specify the name of the socket option to set. +.It Va sopt_val +Kernel space pointer to the argument value for the socket option. +.It Va sopt_valsize +Size of the argument value in bytes. +.El +.Ss Socket Upcalls +In order for the owner of a socket to be notified when the socket +is ready to send or receive data, an upcall may be registered on +the socket. +The upcall is a function that will be called by the socket framework +when a socket buffer associated with the given socket is ready for +reading or writing. +.Fn soupcall_set +is used to register a socket upcall. +The function +.Va func +is registered, and the pointer +.Va arg +will be passed as its second argument when it is called by the framework. +The possible values for +.Va which +are +.Dv SO_RCV +and +.Dv SO_SND , +which register upcalls for receive and send events, respectively. +The upcall function +.Fn func +must return either +.Dv SU_OK +or +.Dv SU_ISCONNECTED , +depending on whether or not a call to +.Xr soisconnected +should be made by the socket framework after the upcall returns. +The upcall +.Va func +cannot call +.Xr soisconnected +itself due to lock ordering with the socket buffer lock. +Only +.Dv SO_RCV +upcalls should return +.Dv SU_ISCONNECTED . +When a +.Dv SO_RCV +upcall returns +.Dv SU_ISCONNECTED , +the upcall will be removed from the socket. +.Pp +Upcalls are removed from their socket by +.Fn soupcall_clear . +The +.Va which +argument again specifies whether the sending or receiving upcall is to +be cleared, with +.Dv SO_RCV +or +.Dv SO_SND . +.Ss Socket I/O +The +.Fn soreceive +function is equivalent to the +.Xr recvmsg 2 +system call, and attempts to receive bytes of data from the socket +.Fa so , +optionally blocking awaiting for data if none is ready to read. +Data may be retrieved directly to kernel or user memory via the +.Fa uio +argument, or as an mbuf chain returned to the caller via +.Fa mp0 , +avoiding a data copy. +The +.Fa uio +must always be +.Pf non- Dv NULL . +If +.Fa mp0 +is +.Pf non- Dv NULL , +only the +.Fa uio_resid +of +.Fa uio +is used. +The caller may optionally retrieve a socket address on a protocol with the +.Dv PR_ADDR +capability by providing storage via +.Pf non- Dv NULL +.Fa psa +argument. +The caller may optionally retrieve control data mbufs via a +.Pf non- Dv NULL +.Fa controlp +argument. +Optional flags may be passed to +.Fn soreceive +via a +.Pf non- Dv NULL +.Fa flagsp +argument, and use the same flag name space as the +.Xr recvmsg 2 +system call. +.Pp +The +.Fn sosend +function is equivalent to the +.Xr sendmsg 2 +system call, and attempts to send bytes of data via the socket +.Fa so , +optionally blocking if data cannot be immediately sent. +Data may be sent directly from kernel or user memory via the +.Fa uio +argument, or as an mbuf chain via +.Fa top , +avoiding a data copy. +Only one of the +.Fa uio +or +.Fa top +pointers may be +.Pf non- Dv NULL . +An optional destination address may be specified via a +.Pf non- Dv NULL +.Fa addr +argument, which may result in an implicit connect if supported by the +protocol. +The caller may optionally send control data mbufs via a +.Pf non- Dv NULL +.Fa control +argument. +Flags may be passed to +.Fn sosend +using the +.Fa flags +argument, and use the same flag name space as the +.Xr sendmsg 2 +system call. +.Pp +Kernel callers running in +.Xr ithread 9 +context, or with a mutex held, will wish to use non-blocking sockets and pass +the +.Dv MSG_DONTWAIT +flag in order to prevent these functions from sleeping. +.Pp +A socket can be queried for readability, writability, out-of-band data, +or end-of-file using +.Fn sopoll . +The possible values for +.Va events +are as for +.Xr poll 2 , +with symbolic values +.Dv POLLIN , +.Dv POLLPRI , +.Dv POLLOUT , +.Dv POLLRDNORM , +.Dv POLLWRNORM , +.Dv POLLRDBAND , +and +.Dv POLLINGEOF +taken from +.In sys/poll.h . +.Pp +Calls to +.Fn soaccept +pass through to the protocol's accept routine to accept an incoming connection. +.Ss Socket Utility Functions +The uid of a socket's credential may be compared against a +.Va uid +with +.Fn socheckuid . +.Pp +A copy of an existing +.Vt struct sockaddr +may be made using +.Fn sodupsockaddr . +.Pp +Protocol implementations notify the socket layer of the arrival of +out-of-band data using +.Fn sohasoutofband , +so that the socket layer can notify socket consumers of the available data. +.Pp +An +.Dq external-format +version of a +.Vt struct socket +can be created using +.Fn sotoxsocket , +suitable for isolating user code from changes in the kernel structure. +.Ss Protocol Implementations +Protocols must supply an implementation for +.Fn solisten ; +such protocol implementations can call back into the socket layer using +.Fn solisten_proto_check +and +.Fn solisten_proto +to check and set the socket-layer listen state. +These callbacks are provided so that the protocol implementation +can order the socket layer and protocol locks as necessary. +Protocols must supply an implementation of +.Fn soreceive ; +the functions +.Fn soreceive_stream , +.Fn soreceive_dgram , +and +.Fn soreceive_generic +are supplied for use by such implementations. +.Pp +Protocol implementations can use +.Fn sonewconn +to create a socket and attach protocol state to that socket. +This can be used to create new sockets available for +.Fn soaccept +on a listen socket. +The returned socket has a reference count of zero. +.Pp +Protocols must supply an implementation for +.Fn sopoll ; +.Fn sopoll_generic +is provided for the use by protocol implementations. +.Pp +The functions +.Fn sosend_dgram +and +.Fn sosend_generic +are supplied to assist in protocol implementations of +.Fn sosend . +.Pp +When a protocol creates a new socket structure, it is necessary to +reserve socket buffer space for that socket, by calling +.Fn soreserve . +The rough inverse of this reservation is performed by +.Fn sorflush , +which is called automatically by the socket framework. +.Pp +When a protocol needs to wake up threads waiting for the socket to +become ready to read or write, variants of +.Fn sowakeup +are used. +The +.Fn sowakeup +function should not be called directly by protocol code, instead use the +wrappers +.Fn sorwakeup , +.Fn sorwakeup_locked , +.Fn sowwakeup , +and +.Fn sowwakeup_locked +for readers and writers, with the corresponding socket buffer lock +not already locked, or already held, respectively. +.Pp +The functions +.Fn sooptcopyin +and +.Fn sooptcopyout +are useful for transferring +.Vt struct sockopt +data between user and kernel code. +.Sh SEE ALSO +.Xr bind 2 , +.Xr close 2 , +.Xr connect 2 , +.Xr getsockopt 2 , +.Xr recv 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr shutdown 2 , +.Xr socket 2 , +.Xr ng_ksocket 4 , +.Xr ithread 9 , +.Xr msleep 9 , +.Xr ucred 9 +.Sh HISTORY +The +.Xr socket 2 +system call appeared in +.Bx 4.2 . +This manual page was introduced in +.Fx 7.0 . +.Sh AUTHORS +This manual page was written by +.An Robert Watson +and +.An Benjamin Kaduk . +.Sh BUGS +The use of explicitly passed credentials, credentials hung from explicitly +passed threads, the credential on +.Dv curthread , +and the cached credential from +socket creation time is inconsistent, and may lead to unexpected behaviour. +It is possible that several of the +.Fa td +arguments should be +.Fa cred +arguments, or simply not be present at all. +.Pp +The caller may need to manually clear +.Dv SS_ISCONNECTING +if +.Fn soconnect +returns an error. +.Pp +The +.Dv MSG_DONTWAIT +flag is not implemented for +.Fn sosend , +and may not always work with +.Fn soreceive +when zero copy sockets are enabled. +.Pp +This manual page does not describe how to register socket upcalls or monitor +a socket for readability/writability without using blocking I/O. +.Pp +The +.Fn soref +and +.Fn sorele +functions are not described, and in most cases should not be used, due to +confusing and potentially incorrect interactions when +.Fn sorele +is last called after +.Fn soclose . Property changes on: user/imp/camdoc/socket.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_clear_modify.9 =================================================================== --- user/imp/camdoc/pmap_clear_modify.9 (nonexistent) +++ user/imp/camdoc/pmap_clear_modify.9 (revision 296049) @@ -0,0 +1,52 @@ +.\" +.\" 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 July 17, 2014 +.Dt PMAP_CLEAR_MODIFY 9 +.Os +.Sh NAME +.Nm pmap_clear_modify +.Nd set information about physical pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_clear_modify "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_clear_modify +function clears the +.Dq modified +bit on the physical page +.Fa m . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_is_modified 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_clear_modify.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_is_modified.9 =================================================================== --- user/imp/camdoc/pmap_is_modified.9 (nonexistent) +++ user/imp/camdoc/pmap_is_modified.9 (revision 296049) @@ -0,0 +1,70 @@ +.\" +.\" 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 July 17, 2014 +.Dt PMAP_IS_MODIFIED 9 +.Os +.Sh NAME +.Nm pmap_is_modified , +.Nm pmap_ts_modified +.Nd return information about physical pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft boolean_t +.Fn pmap_is_modified "vm_page_t m" +.Ft int +.Fn pmap_ts_referenced "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_is_modified +and +.Fn pmap_ts_referenced +functions return information about physical pages. +.Sh RETURN VALUES +The +.Fn pmap_is_modified +function returns the status of the +.Dq "page modified" +bit for the physical page +.Fa m . +.Pp +The +.Fn pmap_ts_referenced +function returns a count of reference bits for a page +.Fa m , +clearing those bits. +It is not necessary for every reference bit to be cleared, but it is +necessary that 0 only be returned when there are no remaining reference +bits set on the page. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_clear_modify 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_is_modified.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/kthread.9 =================================================================== --- user/imp/camdoc/kthread.9 (nonexistent) +++ user/imp/camdoc/kthread.9 (revision 296049) @@ -0,0 +1,349 @@ +.\" Copyright (c) 2000-2001 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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 July 15, 2014 +.Dt KTHREAD 9 +.Os +.Sh NAME +.Nm kthread_start , +.Nm kthread_shutdown , +.Nm kthread_add , +.Nm kthread_exit , +.Nm kthread_resume , +.Nm kthread_suspend , +.Nm kthread_suspend_check +.Nd "kernel threads" +.Sh SYNOPSIS +.In sys/kthread.h +.Ft void +.Fn kthread_start "const void *udata" +.Ft void +.Fn kthread_shutdown "void *arg" "int howto" +.Ft void +.Fn kthread_exit "void" +.Ft int +.Fn kthread_resume "struct thread *td" +.Ft int +.Fn kthread_suspend "struct thread *td" "int timo" +.Ft void +.Fn kthread_suspend_check "void" +.In sys/unistd.h +.Ft int +.Fo kthread_add +.Fa "void (*func)(void *)" "void *arg" "struct proc *procp" +.Fa "struct thread **newtdpp" "int flags" "int pages" +.Fa "const char *fmt" ... +.Fc +.Ft int +.Fo kproc_kthread_add +.Fa "void (*func)(void *)" "void *arg" +.Fa "struct proc **procptr" "struct thread **tdptr" +.Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." +.Fc +.Sh DESCRIPTION +In +.Fx 8.0 , +the older family of +.Fn kthread_* 9 +functions was renamed to be the +.Fn kproc_* 9 +family of functions, +as they were previously misnamed +and actually produced kernel processes. +This new family of +.Fn kthread_* 9 +functions was added to produce +.Em real +kernel threads. +See the +.Xr kproc 9 +man page for more information on the renamed calls. +Also note that the +.Fn kproc_kthread_add 9 +function appears in both pages as its functionality is split. +.Pp +The function +.Fn kthread_start +is used to start +.Dq internal +daemons such as +.Nm bufdaemon , pagedaemon , vmdaemon , +and the +.Nm syncer +and is intended +to be called from +.Xr SYSINIT 9 . +The +.Fa udata +argument is actually a pointer to a +.Vt "struct kthread_desc" +which describes the kernel thread that should be created: +.Bd -literal -offset indent +struct kthread_desc { + char *arg0; + void (*func)(void); + struct thread **global_threadpp; +}; +.Ed +.Pp +The structure members are used by +.Fn kthread_start +as follows: +.Bl -tag -width ".Va global_threadpp" -offset indent +.It Va arg0 +String to be used for the name of the thread. +This string will be copied into the +.Va td_name +member of the new threads' +.Vt "struct thread" . +.It Va func +The main function for this kernel thread to run. +.It Va global_threadpp +A pointer to a +.Vt "struct thread" +pointer that should be updated to point to the newly created thread's +.Vt thread +structure. +If this variable is +.Dv NULL , +then it is ignored. +The thread will be a subthread of +.Va proc0 +(PID 0). +.El +.Pp +The +.Fn kthread_add +function is used to create a kernel thread. +The new thread runs in kernel mode only. +It is added to the process specified by the +.Fa procp +argument, or if that is +.Dv NULL , +to +.Va proc0 . +The +.Fa func +argument specifies the function that the thread should execute. +The +.Fa arg +argument is an arbitrary pointer that is passed in as the only argument to +.Fa func +when it is called by the new thread. +The +.Fa newtdpp +pointer points to a +.Vt "struct thread" +pointer that is to be updated to point to the newly created thread. +If this argument is +.Dv NULL , +then it is ignored. +The +.Fa flags +argument may be set to +.Dv RFSTOPPED +to leave the thread in a stopped state. +The caller must call +.Fn sched_add +to start the thread. +The +.Fa pages +argument specifies the size of the new kernel thread's stack in pages. +If 0 is used, the default kernel stack size is allocated. +The rest of the arguments form a +.Xr printf 9 +argument list that is used to build the name of the new thread and is stored +in the +.Va td_name +member of the new thread's +.Vt "struct thread" . +.Pp +The +.Fn kproc_kthread_add +function is much like the +.Fn kthread_add +function above except that if the kproc does not already +exist, it is created. +This function is better documented in the +.Xr kproc 9 +manual page. +.Pp +The +.Fn kthread_exit +function is used to terminate kernel threads. +It should be called by the main function of the kernel thread rather than +letting the main function return to its caller. +.\" XXX "int ecode" argument isn't documented. +.Pp +The +.Fn kthread_resume , +.Fn kthread_suspend , +and +.Fn kthread_suspend_check +functions are used to suspend and resume a kernel thread. +During the main loop of its execution, a kernel thread that wishes to allow +itself to be suspended should call +.Fn kthread_suspend_check +in order to check if the it has been asked to suspend. +If it has, it will +.Xr msleep 9 +until it is told to resume. +Once it has been told to resume it will return allowing execution of the +kernel thread to continue. +The other two functions are used to notify a kernel thread of a suspend or +resume request. +The +.Fa td +argument points to the +.Vt "struct thread" +of the kernel thread to suspend or resume. +For +.Fn kthread_suspend , +the +.Fa timo +argument specifies a timeout to wait for the kernel thread to acknowledge the +suspend request and suspend itself. +.Pp +The +.Fn kthread_shutdown +function is meant to be registered as a shutdown event for kernel threads that +need to be suspended voluntarily during system shutdown so as not to interfere +with system shutdown activities. +The actual suspension of the kernel thread is done with +.Fn kthread_suspend . +.Sh RETURN VALUES +The +.Fn kthread_add , +.Fn kthread_resume , +and +.Fn kthread_suspend +functions return zero on success and non-zero on failure. +.Sh EXAMPLES +This example demonstrates the use of a +.Vt "struct kthread_desc" +and the functions +.Fn kthread_start , +.Fn kthread_shutdown , +and +.Fn kthread_suspend_check +to run the +.Nm bufdaemon +process. +.Bd -literal -offset indent +static struct thread *bufdaemonthread; + +static struct kthread_desc buf_kp = { + "bufdaemon", + buf_daemon, + &bufdaemonthread +}; +SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kthread_start, + &buf_kp) + +static void +buf_daemon() +{ + ... + /* + * This process needs to be suspended prior to shutdown sync. + */ + EVENTHANDLER_REGISTER(shutdown_pre_sync, kthread_shutdown, + bufdaemonthread, SHUTDOWN_PRI_LAST); + ... + for (;;) { + kthread_suspend_check(); + ... + } +} +.Ed +.Sh ERRORS +The +.Fn kthread_resume +and +.Fn kthread_suspend +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa td +argument does not reference a kernel thread. +.El +.Pp +The +.Fn kthread_add +function will fail if: +.Bl -tag -width Er +.It Bq Er ENOMEM +Memory for a thread's stack could not be allocated. +.El +.Sh SEE ALSO +.Xr kproc 9 , +.Xr SYSINIT 9 , +.Xr wakeup 9 +.Sh HISTORY +The +.Fn kthread_start +function first appeared in +.Fx 2.2 +where it created a whole process. +It was converted to create threads in +.Fx 8.0 . +The +.Fn kthread_shutdown , +.Fn kthread_exit , +.Fn kthread_resume , +.Fn kthread_suspend , +and +.Fn kthread_suspend_check +functions were introduced in +.Fx 4.0 +and were converted to threads in +.Fx 8.0 . +The +.Fn kthread_create +call was renamed to +.Fn kthread_add +in +.Fx 8.0 . +The old functionality of creating a kernel process was renamed +to +.Xr kproc_create 9 . +Prior to +.Fx 5.0 , +the +.Fn kthread_shutdown , +.Fn kthread_resume , +.Fn kthread_suspend , +and +.Fn kthread_suspend_check +functions were named +.Fn shutdown_kproc , +.Fn resume_kproc , +.Fn shutdown_kproc , +and +.Fn kproc_suspend_loop , +respectively. Property changes on: user/imp/camdoc/kthread.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUF_LOCK.9 =================================================================== --- user/imp/camdoc/BUF_LOCK.9 (nonexistent) +++ user/imp/camdoc/BUF_LOCK.9 (revision 296049) @@ -0,0 +1,75 @@ +.\" +.\" Copyright (C) 2001 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 July 9, 2001 +.Dt BUF_LOCK 9 +.Os +.Sh NAME +.Nm BUF_LOCK +.Nd "locks a buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_LOCK "struct buf *bp" "int locktype" +.Sh DESCRIPTION +The +.Fn BUF_LOCK +function locks the given buffer. +If the lock is already held this +call will block until it can acquire the lock unless +.Dv LK_NOWAIT +is set. +.Pp +Its arguments are: +.Bl -tag -width ".Fa locktype" +.It Fa bp +The buffer to lock. +.It Fa locktype +Flags controlling the type of lock. +See +.Xr lockmgr 9 +for details. +.El +.Sh RETURN VALUES +A value of 0 is returned upon success. +See +.Xr lockmgr 9 +for +information on non-zero return values. +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_TIMELOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/BUF_LOCK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUF_LOCKFREE.9 =================================================================== --- user/imp/camdoc/BUF_LOCKFREE.9 (nonexistent) +++ user/imp/camdoc/BUF_LOCKFREE.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" +.\" Copyright (C) 2001 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 July 9, 2001 +.Dt BUF_LOCKFREE 9 +.Os +.Sh NAME +.Nm BUF_LOCKFREE +.Nd "destroys a buffer's lock" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft void +.Fn BUF_LOCKFREE "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_LOCKFREE +macro destroys the buffer lock. +The lock must not be held when +this macro is called or a panic will result. +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer whose lock is to be destroyed. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_TIMELOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockdestroy 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/BUF_LOCKFREE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUF_LOCKINIT.9 =================================================================== --- user/imp/camdoc/BUF_LOCKINIT.9 (nonexistent) +++ user/imp/camdoc/BUF_LOCKINIT.9 (revision 296049) @@ -0,0 +1,62 @@ +.\" +.\" Copyright (C) 2001 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 January 6, 2005 +.Dt BUF_LOCKINIT 9 +.Os +.Sh NAME +.Nm BUF_LOCKINIT +.Nd "initializes a buffer lock" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft void +.Fn BUF_LOCKINIT "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_LOCKINIT +macro initializes a buffer lock. +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer whose lock it to be initialized. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_TIMELOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockinit 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/BUF_LOCKINIT.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUF_RECURSED.9 =================================================================== --- user/imp/camdoc/BUF_RECURSED.9 (nonexistent) +++ user/imp/camdoc/BUF_RECURSED.9 (revision 296049) @@ -0,0 +1,65 @@ +.\" +.\" Copyright (C) 2008 Attilio Rao +.\" 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 January 22, 2008 +.Dt BUF_RECURSED 9 +.Os +.Sh NAME +.Nm BUF_RECURSED +.Nd "checks if the lock linked to the buffer is recursed" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_RECURSED "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_RECURSED +function checks if the lock linked to the given buffer is recursed and +returns 1 if the condition is true, 0 otherwise. +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer linked to the lock. +See +.Xr lockmgr_recursed 9 +for details. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Attilio Rao Aq Mt attilio@FreeBSD.org . Property changes on: user/imp/camdoc/BUF_RECURSED.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUF_TIMELOCK.9 =================================================================== --- user/imp/camdoc/BUF_TIMELOCK.9 (nonexistent) +++ user/imp/camdoc/BUF_TIMELOCK.9 (revision 296049) @@ -0,0 +1,83 @@ +.\" +.\" Copyright (C) 2001 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 July 9, 2001 +.Dt BUF_TIMELOCK 9 +.Os +.Sh NAME +.Nm BUF_TIMELOCK +.Nd "locks a buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn BUF_TIMELOCK "struct buf *bp" "int locktype" "char *wmesg" "int catch" "int timo" +.Sh DESCRIPTION +The +.Fn BUF_TIMELOCK +function locks the given buffer, and limits the amount of time it +will sleep to +.Fa timo +and OR's +.Fa catch +into the sleep's priority. +.Fa wmesg +is the wmesg used in the sleep. +.Pp +Its arguments are: +.Bl -tag -width ".Fa locktype" +.It Fa bp +The buffer to lock. +.It Fa locktype +Flags controlling the type of lock. +See +.Xr lockmgr 9 +for details. +.It Fa wmesg +The wmesg used in any sleeps while acquiring the lock. +.It Fa catch +Priority OR'd into the sleep's priority. +.It Fa timo +The timeout for any sleeps encountered during the lock. +.El +.Sh RETURN VALUES +A value of 0 is returned on success. +See +.Xr lockmgr 9 +for details on non-zero return values. +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_UNLOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/BUF_TIMELOCK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUF_UNLOCK.9 =================================================================== --- user/imp/camdoc/BUF_UNLOCK.9 (nonexistent) +++ user/imp/camdoc/BUF_UNLOCK.9 (revision 296049) @@ -0,0 +1,64 @@ +.\" +.\" Copyright (C) 2001 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 July 9, 2001 +.Dt BUF_UNLOCK 9 +.Os +.Sh NAME +.Nm BUF_UNLOCK +.Nd "unlocks a locked buffer" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/uio.h +.In sys/bio.h +.In sys/buf.h +.Ft void +.Fn BUF_UNLOCK "struct buf *bp" +.Sh DESCRIPTION +The +.Fn BUF_UNLOCK +function unlocks a buffer that was previously locked with +.Fn BUF_LOCK +or +.Fn BUF_TIMELOCK . +.Pp +Its argument is: +.Bl -tag -width ".Fa bp" +.It Fa bp +The buffer to unlock. +The buffer must already be locked. +.El +.Sh SEE ALSO +.Xr buf 9 , +.Xr BUF_LOCK 9 , +.Xr BUF_TIMELOCK 9 , +.Xr lockmgr 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/BUF_UNLOCK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUS_CONFIG_INTR.9 =================================================================== --- user/imp/camdoc/BUS_CONFIG_INTR.9 (nonexistent) +++ user/imp/camdoc/BUS_CONFIG_INTR.9 (revision 296049) @@ -0,0 +1,105 @@ +.\" Copyright (c) 2003 Marcel Moolenaar +.\" 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 January 6, 2005 +.Dt BUS_CONFIG_INTR 9 +.Os +.\" +.Sh NAME +.Nm BUS_CONFIG_INTR +.Nd "configure interrupt polarity and trigger mode" +.\" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fo BUS_CONFIG_INTR +.Fa "device_t dev" "int irq" "enum intr_trigger trig" "enum intr_polarity pol" +.Fc +.\" +.Sh DESCRIPTION +The +.Fn BUS_CONFIG_INTR +method allows bus or device drivers to provide interrupt polarity and trigger +mode to parent busses. +This typically bubbles all the way up to the root bus (e.g.\& nexus) where the +necessary actions are taken to actually program the hardware. +Since the +.Fn BUS_CONFIG_INTR +method takes an interrupt number, it is assumed but not necessarily required +that it is called prior to +.Xr BUS_SETUP_INTR 9 . +.Pp +The +.Fa trig +argument can be one of: +.Bl -tag -width ".Dv INTR_TRIGGER_CONFORM" +.It Dv INTR_TRIGGER_CONFORM +The interrupt trigger mode is standard for the bus to which the device is +attached. +.It Dv INTR_TRIGGER_EDGE +The interrupt is edge triggered. +This means that the interrupt is raised by the rising edge of the signal on +the interrupt line. +The signal typically reverts to the original state so as to cause a spike. +.It Dv INTR_TRIGGER_LEVEL +The interrupt is level triggered. +This means that the interrupt is raised when the signal on the interrupt line +transitions and remains unchanged after that until the interrupt has been +serviced, after which the signal transitions back. +.El +.Pp +The +.Fa pol +argument can be any one of: +.Bl -tag -width ".Dv INTR_POLARITY_CONFORM" +.It Dv INTR_POLARITY_CONFORM +The interrupt polarity is standard for the bus to which the device is attached. +.It Dv INTR_POLARITY_HIGH +The interrupt is activated by a high voltage on the interrupt line. +.It Dv INTR_POLARITY_LOW +The interrupt is activated by a low voltage on the interrupt line. +.El +.\" +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.\" +.Sh SEE ALSO +.Xr BUS_SETUP_INTR 9 , +.Xr BUS_TEARDOWN_INTR 9 , +.Xr device 9 , +.Xr driver 9 +.\" +.Sh HISTORY +The +.Fn BUS_CONFIG_INTR +method first appeared in +.Fx 5.2 . +.\" +.Sh AUTHORS +This manual page was written by +.An Marcel Moolenaar Aq Mt marcel@xcllnt.net . Property changes on: user/imp/camdoc/BUS_CONFIG_INTR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUS_SETUP_INTR.9 =================================================================== --- user/imp/camdoc/BUS_SETUP_INTR.9 (nonexistent) +++ user/imp/camdoc/BUS_SETUP_INTR.9 (revision 296049) @@ -0,0 +1,214 @@ +.\" Copyright (c) 2000 Jeroen Ruigrok van der Werven +.\" 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 November 3, 2010 +.Dt BUS_SETUP_INTR 9 +.Os +.Sh NAME +.Nm BUS_SETUP_INTR , +.Nm bus_setup_intr , +.Nm BUS_TEARDOWN_INTR , +.Nm bus_teardown_intr +.Nd create, attach and teardown an interrupt handler +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fo BUS_SETUP_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "int flags" +.Fa "driver_filter_t *filter" "driver_intr_t *ithread" "void *arg" +.Fa "void **cookiep" +.Fc +.Ft int +.Fo bus_setup_intr +.Fa "device_t dev" "struct resource *r" "int flags" +.Fa "driver_filter_t filter" "driver_intr_t ithread" "void *arg" +.Fa "void **cookiep" +.Fc +.Ft int +.Fo BUS_TEARDOWN_INTR +.Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookiep" +.Fc +.Ft int +.Fn bus_teardown_intr "device_t dev" "struct resource *r" "void *cookiep" +.Sh DESCRIPTION +The +.Fn BUS_SETUP_INTR +method +will create and attach an interrupt handler to an interrupt +previously allocated by the resource manager's +.Xr BUS_ALLOC_RESOURCE 9 +method. +The +.Fa flags +are found in +.In sys/bus.h , +and give the broad category of interrupt. +The +.Fa flags +also tell the interrupt handlers about certain +device driver characteristics. +.Dv INTR_EXCL +marks the handler as being +an exclusive handler for this interrupt. +.Dv INTR_MPSAFE +tells the scheduler that the interrupt handler +is well behaved in a preemptive environment +(``SMP safe''), +and does not need +to be protected by the ``Giant Lock'' mutex. +.Dv INTR_ENTROPY +marks the interrupt as being a good source of entropy - +this may be used by the entropy device +.Pa /dev/random . +.Pp +To define a time-critical handler that will not execute any potentially +blocking operation, use the +.Fa filter +argument. +See the +.Sx "Filter Routines" +section below for information on writing a filter. +Otherwise, use the +.Fa ithread +argument. +The defined handler +will be called with the value +.Fa arg +as its only argument. +See the +.Sx "ithread Routines" +section below for more information on writing an interrupt handler. +.Pp +The +.Fa cookiep +argument is a pointer to a +.Vt "void *" +that +.Fn BUS_SETUP_INTR +will write a cookie for the parent bus' use to if it is successful in +establishing an interrupt. +Driver writers may assume that this cookie will be non-zero. +The nexus driver will write 0 on failure to +.Fa cookiep . +.Pp +The interrupt handler will be detached by +.Fn BUS_TEARDOWN_INTR . +The cookie needs to be passed to +.Fn BUS_TEARDOWN_INTR +in order to tear down the correct interrupt handler. +Once +.Fn BUS_TEARDOWN_INTR +returns, it is guaranteed that the interrupt function is not active and +will no longer be called. +.Pp +Mutexes are not allowed to be held across calls to these functions. +.Ss "Filter Routines" +A filter runs in primary interrupt context. +In this context, normal mutexes cannot be used. +Only the spin lock version of these can be used (specified by passing +.Dv MTX_SPIN +to +.Fn mtx_init +when initializing the mutex). +.Xr wakeup 9 +and similar routines can be called. +Atomic operations from +.Pa machine/atomic +may be used. +Reads and writes to hardware through +.Xr bus_space 9 +may be used. +PCI configuration registers may be read and written. +All other kernel interfaces cannot be used. +.Pp +In this restricted environment, care must be taken to account for all +races. +A careful analysis of races should be done as well. +It is generally cheaper to take an extra interrupt, for example, than +to protect variables with spinlocks. +Read, modify, write cycles of hardware registers need to be carefully +analyzed if other threads are accessing the same registers. +.Pp +Generally, a filter routine will use one of two strategies. +The first strategy is to simply mask the interrupt in hardware and +allow the +.Dv ithread +routine to read the state from the hardware and then reenable +interrupts. +The +.Dv ithread +also acknowledges the interrupt before re-enabling the interrupt +source in hardware. +Most PCI hardware can mask its interrupt source. +.Pp +The second common approach is to use a filter with multiple +.Xr taskqueue 9 +tasks. +In this case, the filter acknowledges the interrupts and queues the +work to the appropriate taskqueue. +Where one has to multiplex different kinds of interrupt sources, like +a network card's transmit and receive paths, this can reduce lock +contention and increase performance. +.Pp +You should not +.Xr malloc 9 +from inside a filter. +You may not call anything that uses a normal mutex. +Witness may complain about these. +.Ss "ithread Routines" +You can do whatever you want in an ithread routine, except sleep. +Care must be taken not to sleep in an ithread. +In addition, one should minimize lock contention in an ithread routine +because contested locks ripple over to all other ithread routines on +that interrupt. +.Ss "Sleeping" +Sleeping is voluntarily giving up control of your thread. +All the sleep routine found in +.Xr msleep 9 +sleep. +Waiting for a condition variable described in +.Xr condvar 9 +is sleeping. +Calling any function that does any of these things is sleeping. +.Sh RETURN VALUES +Zero is returned on success, +otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr random 4 , +.Xr device 9 , +.Xr driver 9 , +.Xr locking 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org +based on the manual pages for +.Fn BUS_CREATE_INTR +and +.Fn BUS_CONNECT_INTR +written by +.An Doug Rabson Aq Mt dfr@FreeBSD.org . Property changes on: user/imp/camdoc/BUS_SETUP_INTR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DECLARE_GEOM_CLASS.9 =================================================================== --- user/imp/camdoc/DECLARE_GEOM_CLASS.9 (nonexistent) +++ user/imp/camdoc/DECLARE_GEOM_CLASS.9 (revision 296049) @@ -0,0 +1,179 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 13, 2007 +.Dt DECLARE_GEOM_CLASS 9 +.Os +.Sh NAME +.Nm DECLARE_GEOM_CLASS +.Nd "GEOM class declaration macro" +.Sh SYNOPSIS +.In geom/geom.h +.Fn DECLARE_GEOM_CLASS "class" "mod_name" +.Sh DESCRIPTION +The +.Fn DECLARE_GEOM_CLASS +macro registers a GEOM class in GEOM. +A GEOM class itself implements one particular kind of transformation. +Typical examples are: MBR disk partition, +.Bx +disklabel and RAID5 classes. +.Fn DECLARE_GEOM_CLASS +can be used both for compiled in and loaded as +.Xr kld 4 +modules GEOM classes and it is the only official way for class registration. +.Pp +The arguments to +.Fn DECLARE_GEOM_CLASS +are: +.Bl -tag -offset indent -width Fa +.It Fa class +The +.Vt g_class +structure which describes a GEOM class. +.It Fa mod_name +A kernel module name (not a class name!). +.El +.Pp +Structure +.Vt g_class +contains data describing the class. +They are: +.Bl -tag -offset indent -width indent +.It Vt "const char *" Va name +Class name. +.It Vt "g_taste_t *" Va taste +Pointer to function used for taste event handling. +If it is +.Pf non- Dv NULL +it is called in three situations: +.Pp +.Bl -dash -compact +.It +On class activation, all existing providers are offered for tasting. +.It +When new provider is created it is offered for tasting. +.It +After last write access to a provider is closed it is offered for retasting +(on first write open event +.Dq spoil +was sent). +.El +.It Vt "g_config_t *" Va config +This field is not used anymore, its functionality was replaced by the +.Va ctlreq +field. +.It Vt "g_ctl_req_t *" Va ctlreq +Pointer to function used for handling events from userland applications. +.It Vt "g_init_t *" Va init +Pointer to function which is called right after class registration. +.It Vt "g_fini_t *" Va fini +Pointer to function which is called right before class deregistration. +.It Vt "g_ctl_destroy_geom_t *" Va destroy_geom +Pointer to a function which is called for every geom on class unload. +If this field is not set, the class can not be unloaded. +.El +.Pp +Only a +.Fa name +field is required; the rest are optional. +.Sh RESTRICTIONS/CONDITIONS +The fields of +.Vt g_class +should always be initialized using C99-style field naming +(see the initialization of +.Va example_class +below). +.Sh EXAMPLES +Example class declaration. +.Bd -literal -offset indent +static struct g_geom * +g_example_taste(struct g_class *mp, struct g_provider *pp, + int flags __unused) +{ + g_topology_assert(); + + [...] +} + +static void +g_example_ctlreq(struct gctl_req *req, struct g_class *cp, + char const *verb) +{ + + [...] +} + +static int +g_example_destroy_geom(struct gctl_req *req, struct g_class *cp, + struct g_geom *gp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_init(struct g_class *mp) +{ + + [...] +} + +static void +g_example_fini(struct g_class *mp) +{ + + [...] +} + +struct g_class example_class = { + .name = "EXAMPLE", + .taste = g_example_taste, + .ctlreq = g_example_ctlreq, + .init = g_example_init, + .fini = g_example_fini, + .destroy_geom = g_example_destroy_geom +}; + +DECLARE_GEOM_CLASS(example_class, g_example); +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/DECLARE_GEOM_CLASS.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DECLARE_MODULE.9 =================================================================== --- user/imp/camdoc/DECLARE_MODULE.9 (nonexistent) +++ user/imp/camdoc/DECLARE_MODULE.9 (revision 296049) @@ -0,0 +1,112 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 6, 2005 +.Dt DECLARE_MODULE 9 +.Os +.Sh NAME +.Nm DECLARE_MODULE +.Nd kernel module declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/module.h +.Fn DECLARE_MODULE "name" "moduledata_t data" "sub" "order" +.Sh DESCRIPTION +The +.Fn DECLARE_MODULE +macro declares a generic kernel module. +It is used to register the module with the system, using the +.Fn SYSINIT +macro. +.Fn DECLARE_MODULE +is usually used within other macros, such as +.Xr DRIVER_MODULE 9 , +.Xr DEV_MODULE 9 +and +.Xr SYSCALL_MODULE 9 . +Of course, it can also be called directly, for example in +order to implement dynamic sysctls. +.Pp +The arguments it expects are: +.Bl -tag -width indent +.It Fa name +The module name, which will be used in the +.Fn SYSINIT +call to identify the module. +.It Fa data +A +.Vt moduledata_t +structure, which contains two main items, the official name of the +module name, which will be used in the +.Vt module_t +structure and a pointer to the event handler function of type +.Vt modeventhand_t . +.It Fa sub +An argument directed to the +.Fn SYSINIT +macro. +Valid values for this are contained in the +.Vt sysinit_sub_id +enumeration +(see +.In sys/kernel.h ) +and specify the type of system startup interfaces. +The +.Xr DRIVER_MODULE 9 +macro uses a value of +.Dv SI_SUB_DRIVERS +here for example, since these modules contain a driver for a device. +For kernel modules that are loaded at runtime, a value of +.Dv SI_SUB_EXEC +is common. +.It Fa order +An argument for +.Fn SYSINIT . +It represents the KLDs order of initialization within the subsystem. +Valid values are defined in the +.Vt sysinit_elem_order +enumeration +.Pq In sys/kernel.h . +.El +.Sh SEE ALSO +.Xr DEV_MODULE 9 , +.Xr DRIVER_MODULE 9 , +.Xr module 9 , +.Xr SYSCALL_MODULE 9 +.Pp +.Pa /usr/include/sys/kernel.h , +.Pa /usr/share/examples/kld +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org , +inspired by the KLD Facility Programming Tutorial by +.An Andrew Reiter Aq Mt arr@watson.org . Property changes on: user/imp/camdoc/DECLARE_MODULE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DEVICE_ATTACH.9 =================================================================== --- user/imp/camdoc/DEVICE_ATTACH.9 (nonexistent) +++ user/imp/camdoc/DEVICE_ATTACH.9 (revision 296049) @@ -0,0 +1,71 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 6, 2005 +.Dt DEVICE_ATTACH 9 +.Os +.Sh NAME +.Nm DEVICE_ATTACH +.Nd attach a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_ATTACH "device_t dev" +.Sh DESCRIPTION +Attach a device to the system after the +.Fn DEVICE_PROBE +method has been called and has indicated that +the device exists. +The +.Fn DEVICE_ATTACH +method should initialize the hardware and allocate other +system resources (such as +.Xr devfs 5 +entries). +.Pp +Devices which implement busses should use this method to probe for +the existence of devices attached to the bus and add them as +children. +If this is combined with the use of +.Xr bus_generic_attach 9 +the child devices will be automatically probed and attached. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr devfs 5 , +.Xr device 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_SHUTDOWN 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson Aq Mt dfr@FreeBSD.org . Property changes on: user/imp/camdoc/DEVICE_ATTACH.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DEVICE_IDENTIFY.9 =================================================================== --- user/imp/camdoc/DEVICE_IDENTIFY.9 (nonexistent) +++ user/imp/camdoc/DEVICE_IDENTIFY.9 (revision 296049) @@ -0,0 +1,94 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 13, 2004 +.Dt DEVICE_IDENTIFY 9 +.Os +.Sh NAME +.Nm DEVICE_IDENTIFY +.Nd identify a device, register it +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn DEVICE_IDENTIFY "driver_t *driver" "device_t parent" +.Sh DESCRIPTION +The identify function for a device is only needed for devices on busses +that cannot identify their children independently, e.g.\& the ISA bus. +It is used to recognize the device (usually done by accessing non-ambiguous +registers in the hardware) and to tell the kernel about it and thus +creating a new device instance. +.Pp +.Xr BUS_ADD_CHILD 9 +is used to register the device as a child of the bus. +The device's resources (such as IRQ and I/O ports) are registered +with the kernel by calling +.Fn bus_set_resource +for each resource (refer to +.Xr bus_set_resource 9 +for more information). +.Pp +Since the device tree and the device driver tree are disjoint, the +.Fn DEVICE_IDENTIFY +routine needs to take this into account. +If you load and unload your device driver that has the identify +routine, the child node has the potential for adding the same node +multiple times unless specific measure are taken to preclude that +possibility. +.Sh EXAMPLES +The following pseudo-code shows an example of a function that +probes for a piece of hardware and registers it and its resource +(an I/O port) with the kernel. +.Bd -literal +void +foo_identify(driver_t *driver, device_t parent) +{ + device_t child; + + retrieve_device_information; + if (devices matches one of your supported devices && + not already in device tree) { + child = BUS_ADD_CHILD(parent, 0, "foo", -1); + bus_set_resource(child, SYS_RES_IOPORT, 0, FOO_IOADDR, 1); + } +} +.Ed +.Sh SEE ALSO +.Xr BUS_ADD_CHILD 9 , +.Xr bus_set_resource 9 , +.Xr device 9 , +.Xr device_add_child 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_SHUTDOWN 9 +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . Property changes on: user/imp/camdoc/DEVICE_IDENTIFY.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DEV_MODULE.9 =================================================================== --- user/imp/camdoc/DEV_MODULE.9 (nonexistent) +++ user/imp/camdoc/DEV_MODULE.9 (revision 296049) @@ -0,0 +1,105 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 19, 2012 +.Dt DEV_MODULE 9 +.Os +.Sh NAME +.Nm DEV_MODULE +.Nd device driver module declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/module.h +.In sys/conf.h +.Fn DEV_MODULE "name" "modeventhand_t evh" "void *arg" +.Sh DESCRIPTION +The +.Fn DEV_MODULE +macro declares a device driver kernel module. +It fills in a +.Vt moduledata_t +structure and then calls +.Fn DECLARE_MODULE +with the correct args, where +.Fa name +is the name of the module and +.Fa evh +(with its argument +.Fa arg ) +is the event handler for the module (refer to +.Xr DECLARE_MODULE 9 +for more information). +The event handler is supposed to create the device with +.Fn make_dev +on load and to destroy it when it is unloaded using +.Fn destroy_dev . +.Sh EXAMPLES +.Bd -literal +#include +#include + +static struct cdevsw foo_devsw = { ... }; + +static struct cdev *sdev; + +static int +foo_load(module_t mod, int cmd, void *arg) +{ + int err = 0; + + switch (cmd) { + case MOD_LOAD: + sdev = make_dev(&foo_devsw, 0, UID_ROOT, GID_WHEEL, 0600, "foo"); + break; /* Success*/ + + case MOD_UNLOAD: + case MOD_SHUTDOWN: + destroy_dev(sdev); + break; /* Success*/ + + default: + err = EINVAL; + break; + } + + return(err); +} + +DEV_MODULE(foo, foo_load, NULL); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr destroy_dev 9 , +.Xr make_dev 9 , +.Xr module 9 +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . Property changes on: user/imp/camdoc/DEV_MODULE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DRIVER_MODULE.9 =================================================================== --- user/imp/camdoc/DRIVER_MODULE.9 (nonexistent) +++ user/imp/camdoc/DRIVER_MODULE.9 (revision 296049) @@ -0,0 +1,150 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 21, 2012 +.Dt DRIVER_MODULE 9 +.Os +.Sh NAME +.Nm DRIVER_MODULE , +.Nm DRIVER_MODULE_ORDERED , +.Nm EARLY_DRIVER_MODULE , +.Nm EARLY_DRIVER_MODULE_ORDERED +.Nd kernel driver declaration macro +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.In sys/bus.h +.In sys/module.h +.Fn DRIVER_MODULE name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg" +.Fn DRIVER_MODULE_ORDERED name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg" "int order" +.Fn EARLY_DRIVER_MODULE name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg" "enum sysinit_elem_order order" "int pass" +.Fn EARLY_DRIVER_MODULE_ORDERED name busname "driver_t driver" "devclass_t devclass" "modeventhand_t evh" "void *arg" "enum sysinit_elem_order order" "int pass" +.Sh DESCRIPTION +The +.Fn DRIVER_MODULE +macro declares a kernel driver. +.Fn DRIVER_MODULE +expands to the real driver declaration, where the phrase +.Fa name +is used as the naming prefix for the driver and its functions. +Note that it is supplied as plain text, and not a +.Li char +or +.Li char * . +.Pp +.Fa busname +is the parent bus of the driver (PCI, ISA, PPBUS and others), e.g.\& +.Ql pci , +.Ql isa , +or +.Ql ppbus . +.Pp +The identifier used in +.Fn DRIVER_MODULE +can be different from the driver name. +Also, the same driver identifier can exist on different busses, +which is a pretty clean way of making front ends for different cards +using the same driver on the same or different busses. +For example, the following is allowed: +.Pp +.Fn DRIVER_MODULE foo isa foo_driver foo_devclass NULL NULL ; +.Pp +.Fn DRIVER_MODULE foo pci foo_driver foo_devclass NULL NULL ; +.Pp +.Fa driver +is the driver of type +.Li driver_t , +which contains the information about the driver and is therefore one of the +two most important parts of the call to +.Fn DRIVER_MODULE . +.Pp +The +.Fa devclass +argument contains the kernel-internal information about the device, +which will be used within the kernel driver module. +.Pp +The +.Fa evh +argument is the event handler which is called when the driver (or module) +is loaded or unloaded (see +.Xr module 9 ) . +.Pp +The +.Fa arg +is unused at this time and should be a +.Dv NULL +pointer. +.Pp +The +.Fn DRIVER_MODULE_ORDERED +macro allows a driver to be registered in a specific order. +This can be useful if a single kernel module contains multiple drivers +that are inter-dependent. +The +.Fa order +argument should be one of the +.Xr SYSINIT 9 +initialization ordering constants +.Pq Dv SI_ORDER_* . +The default order for a driver module is +.Dv SI_ORDER_MIDDLE . +Typically a module will specify an order of +.Dv SI_ORDER_ANY +for a single driver to ensure it is registered last. +.Pp +The +.Fn EARLY_DRIVER_MODULE +macro allows a driver to be registered for a specific pass level. +The boot time probe and attach process makes multiple passes over the +device tree. +Certain critical drivers that provide basic services needed by other +devices are attach during earlier passes. +Most drivers are attached in a final general pass. +A driver that attaches during an early pass must register for a specific +pass level +.Pq BUS_PASS_* +via the +.Fa pass +argument. +Once a driver is registered it is available to attach to devices for +all subsequent passes. +.Pp +The +.Fn EARLY_DRIVER_MODULE_ORDERED +macro allows a driver to be registered both in a specific order and +for a specific pass level. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 , +.Xr module 9 , +.Xr SYSINIT 9 +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . Property changes on: user/imp/camdoc/DRIVER_MODULE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/KASSERT.9 =================================================================== --- user/imp/camdoc/KASSERT.9 (nonexistent) +++ user/imp/camdoc/KASSERT.9 (revision 296049) @@ -0,0 +1,86 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Jonathan M. Bresler +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 14, 2000 +.Dt KASSERT 9 +.Os +.Sh NAME +.Nm KASSERT +.Nd kernel expression verification macro +.Sh SYNOPSIS +.Cd "options INVARIANTS" +.Pp +.In sys/param.h +.In sys/systm.h +.Fn KASSERT expression msg +.Sh DESCRIPTION +In a kernel compiled with +.Cd "options INVARIANTS" , +the +.Fn KASSERT +macro tests the given +.Fa expression +and if it is false, +calls the +.Xr panic 9 +function, terminating the running system. +.Pp +In a kernel that does not have +.Cd "options INVARIANTS" , +the +.Fn KASSERT +macro is defined to be a no-op. +The +second argument is a +.Xr printf 9 +format string and its arguments, +enclosed in parentheses. +.Sh EXAMPLES +The kernel function +.Fn vput +must not be called with a +.Dv NULL +pointer. +.Bd -literal -offset indent +void +vput(vp) + struct vnode *vp; +{ + struct proc *p = curproc; + KASSERT(vp != NULL, ("vput: null vp")); + ... +} +.Ed +.Sh SEE ALSO +.Xr config 8 , +.Xr panic 9 +.Sh AUTHORS +This manual page was written by +.An Jonathan M. Bresler Aq Mt jmb@FreeBSD.org . Property changes on: user/imp/camdoc/KASSERT.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/LOCK_PROFILING.9 =================================================================== --- user/imp/camdoc/LOCK_PROFILING.9 (nonexistent) +++ user/imp/camdoc/LOCK_PROFILING.9 (revision 296049) @@ -0,0 +1,187 @@ +.\"- +.\" Copyright (c) 2004 Dag-Erling Coïdan Smørgrav +.\" Copyright (c) 2005 Robert N. M. Watson +.\" Copyright (c) 2006 Kip Macy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 7, 2012 +.Dt LOCK_PROFILING 9 +.Os +.Sh NAME +.Nm LOCK_PROFILING +.Nd kernel lock profiling support +.Sh SYNOPSIS +.Cd "options LOCK_PROFILING" +.Sh DESCRIPTION +The +.Dv LOCK_PROFILING +kernel option adds support for measuring and reporting lock use and +contention statistics. +These statistics are collated by +.Dq acquisition point . +Acquisition points are +distinct places in the kernel source code (identified by source file +name and line number) where a lock is acquired. +.Pp +For each acquisition point, the following statistics are accumulated: +.Bl -bullet +.It +The longest time the lock was ever continuously held after being +acquired at this point. +.It +The total time the lock was held after being acquired at this point. +.It +The total time that threads have spent waiting to acquire the lock. +.It +The total number of non-recursive acquisitions. +.It +The total number of times the lock was already held by another thread +when this point was reached, requiring a spin or a sleep. +.It +The total number of times another thread tried to acquire the lock +while it was held after having been acquired at this point. +.El +.Pp +In addition, the average hold time and average wait time are derived +from the total hold time +and total wait time respectively and the number of acquisitions. +.Pp +The +.Dv LOCK_PROFILING +kernel option also adds the following +.Xr sysctl 8 +variables to control and monitor the profiling code: +.Bl -tag -width indent +.It Va debug.lock.prof.enable +Enable or disable the lock profiling code. +This defaults to 0 (off). +.It Va debug.lock.prof.reset +Reset the current lock profiling buffers. +.It Va debug.lock.prof.stats +The actual profiling statistics in plain text. +The columns are as follows, from left to right: +.Bl -tag -width ".Va cnt_hold" +.It Va max +The longest continuous hold time in microseconds. +.It Va wait_max +The longest continuous wait time in microseconds. +.It Va total +The total (accumulated) hold time in microseconds. +.It Va wait_total +The total (accumulated) wait time in microseconds. +.It Va count +The total number of acquisitions. +.It Va avg +The average hold time in microseconds, derived from the total hold time +and the number of acquisitions. +.It Va wait_avg +The average wait time in microseconds, derived from the total wait time +and the number of acquisitions. +.It Va cnt_hold +The number of times the lock was held and another thread attempted to +acquire the lock. +.It Va cnt_lock +The number of times the lock was already held when this point was +reached. +.It Va name +The name of the acquisition point, derived from the source file name +and line number, followed by the name of the lock in parentheses. +.El +.It Va debug.lock.prof.rejected +The number of acquisition points that were ignored after the table +filled up. +.It Va debug.lock.prof.skipspin +Disable or enable the lock profiling code for the spin locks. +This defaults to 0 (do profiling for the spin locks). +.It Va debug.lock.prof.skipcount +Do sampling approximately every N lock acquisitions. +.El +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr mutex 9 +.Sh HISTORY +Mutex profiling support appeared in +.Fx 5.0 . +Generalized lock profiling support appeared in +.Fx 7.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm MUTEX_PROFILING +code was written by +.An Eivind Eklund Aq Mt eivind@FreeBSD.org , +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org +and +.An Robert Watson Aq Mt rwatson@FreeBSD.org . +The +.Nm +code was written by +.An Kip Macy Aq Mt kmacy@FreeBSD.org . +This manual page was written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . +.Sh NOTES +The +.Dv LOCK_PROFILING +option increases the size of +.Vt "struct lock_object" , +so a kernel built with that option will not work with modules built +without it. +.Pp +The +.Dv LOCK_PROFILING +option also prevents inlining of the mutex code, which can result in a +fairly severe performance penalty. +This is, however, not always the case. +.Dv LOCK_PROFILING +can introduce a substantial performance overhead that is easily +monitorable using other profiling tools, so combining profiling tools +with +.Dv LOCK_PROFILING +is not recommended. +.Pp +Measurements are made and stored in nanoseconds using +.Xr nanotime 9 , +(on architectures without a synchronized TSC) but are presented in microseconds. +This should still be sufficient for the locks one would be most +interested in profiling (those that are held long and/or acquired +often). +.Pp +.Dv LOCK_PROFILING +should generally not be used in combination with other debugging options, as +the results may be strongly affected by interactions between the features. +In particular, +.Dv LOCK_PROFILING +will report higher than normal +.Xr uma 9 +lock contention when run with +.Dv INVARIANTS +due to extra locking that occurs when +.Dv INVARIANTS +is present; likewise, using it in combination with +.Dv WITNESS +will lead to much higher lock hold times and contention in profiling output. Property changes on: user/imp/camdoc/LOCK_PROFILING.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/MODULE_DEPEND.9 =================================================================== --- user/imp/camdoc/MODULE_DEPEND.9 (nonexistent) +++ user/imp/camdoc/MODULE_DEPEND.9 (revision 296049) @@ -0,0 +1,80 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 11, 2005 +.Dt MODULE_DEPEND 9 +.Os +.Sh NAME +.Nm MODULE_DEPEND +.Nd set kernel module dependencies +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Fn MODULE_DEPEND "name" "moddepend" "int minversion" "int prefversion" "int maxversion" +.Sh DESCRIPTION +The +.Fn MODULE_DEPEND +macro sets a dependency on another kernel module with name +.Fa moddepend , +which has registered +its version with +.Fn MODULE_VERSION . +.Pp +The +.Fn MODULE_DEPEND +macro provides hints to the kernel +.Xr loader 8 +and to the kernel linker to ensure that the named dependency is loaded +prior to the existing module. +It does not change or dictate the order in which modules are +initialized at runtime. +.Pp +Three versions must be specified for +.Fa moddepend : +.Bl -tag -width ".Fa prefversion" +.It Fa minversion +The minimum version on which the current module can depend. +.It Fa maxversion +The maximum version on which the current module can depend. +.It Fa prefversion +The preferred version on which the current module can depend. +.El +.Sh EXAMPLES +.Bd -literal +MODULE_DEPEND(foo, bar, 1, 3, 4); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr module 9 , +.Xr MODULE_VERSION 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . Property changes on: user/imp/camdoc/MODULE_DEPEND.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/MODULE_VERSION.9 =================================================================== --- user/imp/camdoc/MODULE_VERSION.9 (nonexistent) +++ user/imp/camdoc/MODULE_VERSION.9 (revision 296049) @@ -0,0 +1,59 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 11, 2001 +.Dt MODULE_VERSION 9 +.Os +.Sh NAME +.Nm MODULE_VERSION +.Nd set kernel module version +.Sh SYNOPSIS +.In sys/param.h +.In sys/module.h +.Fn MODULE_VERSION "name" "int version" +.Sh DESCRIPTION +The +.Fn MODULE_VERSION +macro sets the version of the module called +.Fa name . +Other kernel modules can then depend on this module (see +.Xr MODULE_DEPEND 9 ) . +.Sh EXAMPLES +.Bd -literal +MODULE_VERSION(foo, 1); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr module 9 , +.Xr MODULE_DEPEND 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . Property changes on: user/imp/camdoc/MODULE_VERSION.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/SYSINIT.9 =================================================================== --- user/imp/camdoc/SYSINIT.9 (nonexistent) +++ user/imp/camdoc/SYSINIT.9 (revision 296049) @@ -0,0 +1,163 @@ +.\" Copyright (c) 2003 Hiten M. Pandya +.\" 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 1, 2010 +.Dt SYSINIT 9 +.Os +.Sh NAME +.Nm SYSINIT , +.Nm SYSUNINIT +.Nd a framework for dynamic kernel initialization +.Sh SYNOPSIS +.In sys/param.h +.In sys/kernel.h +.Fn SYSINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident" +.Fn SYSUNINIT "uniquifier" "enum sysinit_sub_id subsystem" "enum sysinit_elem_order order" "sysinit_cfunc_t func" "const void *ident" +.Sh DESCRIPTION +.Nm +is a mechanism for scheduling the execution of initialization and teardown +routines. +This is similar to init and fini routines with the addition of explicit +ordering metadata. +It allows runtime ordering of subsystem initialization in the kernel as well +as kernel modules (KLDs). +.Pp +The +.Fn SYSINIT +macro creates a +.Vt struct sysinit +and stores it in a startup linker set. +The +.Vt struct sysinit +type as well as the subsystem identifier constants +.Pq Dv SI_SUB_* +and initialization ordering constants +.Pq Dv SI_ORDER_* +are defined in +.In sys/kernel.h : +.Bd -literal +struct sysinit { + enum sysinit_sub_id subsystem; /* subsystem identifier*/ + enum sysinit_elem_order order; /* init order within subsystem*/ + sysinit_cfunc_t func; /* function */ + const void *udata; /* multiplexer/argument */ +}; +.Ed +.Pp +The +.Fn SYSINIT +macro takes a +.Fa uniquifier +argument to identify the particular function dispatch data, +the +.Fa subsystem +type of startup interface, the subsystem element +.Fa order +of initialization within the subsystem, the +.Fa func +function to call, +and the data specified in +.Fa ident +argument to pass the function. +.Pp +The +.Fn SYSUNINIT +macro behaves similarly to the +.Fn SYSINIT +macro except that it adds the data to a shutdown linker set. +.Pp +The startup linker set for the kernel is scanned during boot to build a +sorted list of initialization routines. +The initialization routines are then executed in the sorted order. +The +.Fa subsystem +is used as the primary key and is sorted in ascending order. +The +.Fa order +is used as the secondary key and is sorted in ascending order. +The relative order of two routines that have the same +.Fa subsystem +and +.Fa order +is undefined. +.Pp +The startup linker sets for modules that are loaded together with the kernel +by the boot loader are scanned during the +.Dv SI_SUB_KLD +subsystem initialization. +These modules' initialization routines are sorted and merged into the kernel's +list of startup routines and are executed during boot along with the kernel's +initialization routines. +Note that this has the effect that any initialization routines in a kernel +module that are scheduled earlier than +.Dv SI_SUB_KLD +are not executed until after +.Dv SI_SUB_KLD +during boot. +.Pp +The startup linker set for a kernel module loaded at runtime via +.Xr kldload 2 +is scanned, sorted, and executed when the module is loaded. +.Pp +The shutdown linker set for a kernel module is scanned, sorted, and executed +when a kernel module is unloaded. +The teardown routines are sorted in the reverse order of the initialization +routines. +The teardown routines of the kernel and any loaded modules are +.Sy not +executed during shutdown. +.Sh EXAMPLES +This example shows the SYSINIT which displays the copyright notice during boot: +.Bd -literal -offset indent +static void +print_caddr_t(void *data) +{ + printf("%s", (char *)data); +} +SYSINIT(announce, SI_SUB_COPYRIGHT, SI_ORDER_FIRST, print_caddr_t, + copyright); +.Ed +.Sh SEE ALSO +.Xr kld 4 , +.Xr DECLARE_MODULE 9 , +.Xr DEV_MODULE 9 , +.Xr DRIVER_MODULE 9 , +.Xr MTX_SYSINIT 9 , +.Xr SYSCALL_MODULE 9 +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 2.2 . +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Terrence Lambert Aq Mt terry@FreeBSD.org . +.Pp +This manual page was written by +.An Hiten Pandya Aq Mt hmp@FreeBSD.org . Property changes on: user/imp/camdoc/SYSINIT.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/bus_activate_resource.9 =================================================================== --- user/imp/camdoc/bus_activate_resource.9 (nonexistent) +++ user/imp/camdoc/bus_activate_resource.9 (revision 296049) @@ -0,0 +1,93 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 28, 2003 +.Dt BUS_ACTIVATE_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_activate_resource , bus_deactivate_resource +.Nd activate or deactivate a 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_activate_resource +.Fa "device_t dev" "int type" "int rid" "struct resource *r" +.Fc +.Ft int +.Fo bus_deactivate_resource +.Fa "device_t dev" "int type" "int rid" "struct resource *r" +.Fc +.Sh DESCRIPTION +These functions activate or deactivate a previously allocated resource. +In general, resources must be activated before they can be accessed by +the driver so that the bus driver can map the resource into the +devices space. +.Pp +The arguments are as follows: +.Bl -tag -width indent +.It Fa dev +The device that requests ownership of the resource. +Before allocation, the resource is owned by the parent bus. +.It Fa type +The type of resource you want to allocate. +It is one of: +.Pp +.Bl -tag -width ".Dv SYS_RES_MEMORY" -compact +.It Dv SYS_RES_IRQ +for IRQs +.It Dv SYS_RES_DRQ +for ISA DMA lines +.It Dv SYS_RES_IOPORT +for I/O ports +.It Dv SYS_RES_MEMORY +for I/O memory +.El +.It Fa rid +A pointer to a bus specific handle that identifies the resource being allocated. +.It Fa r +A pointer to the +.Vt "struct resource" +returned by +.Xr bus_alloc_resource 9 . +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh Aq Mt imp@FreeBSD.org . Property changes on: user/imp/camdoc/bus_activate_resource.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_child_present.9 =================================================================== --- user/imp/camdoc/bus_child_present.9 (nonexistent) +++ user/imp/camdoc/bus_child_present.9 (revision 296049) @@ -0,0 +1,87 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 27, 2003 +.Dt BUS_CHILD_PRESENT 9 +.Os +.Sh NAME +.Nm bus_child_present +.Nd "ask the bus driver to see if this device is still really present" +.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 +.Fn bus_child_present "device_t dev" +.Sh DESCRIPTION +The +.Fn bus_child_present +function requests that the parent device driver of +.Fa dev +check to see if the +hardware represented by +.Fa dev +is still physically accessible at this time. +While the notion of accessible varies from bus to bus, generally +hardware that is not accessible cannot be accessed via the +.Fn bus_space* +methods that would otherwise be used to access the device. +.Pp +This does not ask the question +.Dq does this device have children? +which can better be answered by +.Xr device_get_children 9 . +.Sh RETURN VALUES +A zero return value indicates that the device is not present in the +system. +A non-zero return value indicates that the device is present in the +system, or that the state of the device cannot be determined. +.Sh EXAMPLES +This is some example code. +It only calls stop when the +.Xr dc 4 +device is actually present. +.Bd -literal -offset indent +device_t dev; +dc_softc *sc; + +sc = device_get_softc(dev); +if (bus_child_present(dev)) + dc_stop(sc); +.Ed +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh Aq Mt imp@FreeBSD.org . Property changes on: user/imp/camdoc/bus_child_present.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_release_resource.9 =================================================================== --- user/imp/camdoc/bus_release_resource.9 (nonexistent) +++ user/imp/camdoc/bus_release_resource.9 (revision 296049) @@ -0,0 +1,106 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 18, 2000 +.Dt BUS_RELEASE_RESOURCE 9 +.Os +.Sh NAME +.Nm bus_release_resource +.Nd release resources on a bus +.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 +.Fn bus_release_resource "device_t dev" "int type" "int rid" "struct resource *r" +.Sh DESCRIPTION +Free a resource allocated by +.Xr bus_alloc_resource 9 . +The resource must not be in use on release, i.e., call an appropriate function +before (e.g.\& +.Xr bus_teardown_intr 9 +for IRQs). +.Bl -item +.It +.Fa dev +is the device that owns the resource. +.It +.Fa type +is the type of resource that is released. +It must be of the same type you allocated it as before. +See +.Xr bus_alloc_resource 9 +for valid types. +.It +.Fa rid +is the resource ID of the resource. +The +.Fa rid +value must be the same as the one returned by +.Xr bus_alloc_resource 9 . +.It +.Fa r +is the pointer to +.Va struct resource , +i.e., the resource itself, +returned by +.Xr bus_alloc_resource 9 . +.El +.Sh RETURN VALUES +.Er EINVAL +is returned, if the device +.Fa dev +has no parent, +.Dv 0 +otherwise. +The kernel will panic, if it cannot release the resource. +.Sh EXAMPLES +.Bd -literal + /* deactivate IRQ */ + bus_teardown_intr(dev, foosoftc->irqres, foosoftc->irqid); + + /* release IRQ resource */ + bus_release_resource(dev, SYS_RES_IRQ, foosoftc->irqid, + foosoftc->irqres); + + /* release I/O port resource */ + bus_release_resource(dev, SYS_RES_IOPORT, foosoftc->portid, + foosoftc->portres); +.Ed +.Sh SEE ALSO +.Xr bus_alloc_resource 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@big.endian.de . Property changes on: user/imp/camdoc/bus_release_resource.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/config_intrhook.9 =================================================================== --- user/imp/camdoc/config_intrhook.9 (nonexistent) +++ user/imp/camdoc/config_intrhook.9 (revision 296049) @@ -0,0 +1,105 @@ +.\" +.\" Copyright (C) 2006 M. Warner Losh . 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 September 24, 2006 +.Dt CONFIG_INTRHOOK 9 +.Os +.Sh NAME +.Nm config_intrhook +.Nd schedule a function to be run after interrupts have been enabled, +but before root is mounted +.Sh SYNOPSIS +.In sys/kernel.h +.Ft int +.Fn config_intrhook_establish "struct intr_config_hook *hook" +.Ft void +.Fn config_intrhook_disestablish "struct intr_config_hook *hook" +.Sh DESCRIPTION +The +.Fn config_intrhook_establish +function schedules a function to be run after interrupts have been +enabled, but before root is mounted. +If the system has already passed this point in its initialization, +the function is called immediately. +.Pp +The +.Fn config_intrhook_disestablish +function removes the entry from the hook queue. +.Pp +Before root is mounted, all the previously established hooks are +run. +The boot process is then stalled until all handlers remove their hook +from the hook queue with +.Fn config_intrhook_disestablish . +The boot process then proceeds to attempt to mount the root file +system. +Any driver that can potentially provide devices they wish to be +mounted as root must use either this hook, or probe all these devices +in the initial probe. +Since interrupts are disabled during the probe process, many drivers +need a method to probe for devices with interrupts enabled. +.Pp +The requests are made with the +.Vt intr_config_hook +structure. +This structure is defined as follows: +.Bd -literal +struct intr_config_hook { + TAILQ_ENTRY(intr_config_hook) ich_links;/* Private */ + void (*ich_func)(void *arg); /* function to call */ + void *ich_arg; /* Argument to call */ +}; +.Ed +.Pp +Storage for the +.Vt intr_config_hook +structure must be provided by the driver. +It must be stable from just before the hook is established until +after the hook is disestablished. +.Pp +Specifically, hooks are run at +.Fn SI_SUB_INT_CONFIG_HOOKS , +which is immediately after the scheduler is started, +and just before the root file system device is discovered. +.Sh RETURN VALUES +A zero return value means the hook was successfully added to the queue +(with either deferred or immediate execution). +A non-zero return value means the hook could not be added to the queue +because it was already on the queue. +.Sh SEE ALSO +.Xr DEVICE_ATTACH 9 +.Sh HISTORY +These functions were introduced in +.Fx 3.0 +with the CAM subsystem, but are available for any driver to use. +.Sh AUTHORS +.An -nosplit +The functions were written by +.An Justin Gibbs Aq Mt gibbs@FreeBSD.org . +This manual page was written by +.An M. Warner Losh Aq Mt imp@FreeBSD.org . Property changes on: user/imp/camdoc/config_intrhook.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devstat.9 =================================================================== --- user/imp/camdoc/devstat.9 (nonexistent) +++ user/imp/camdoc/devstat.9 (revision 296049) @@ -0,0 +1,455 @@ +.\" +.\" Copyright (c) 1998, 1999 Kenneth D. Merry. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 22, 1998 +.Dt DEVSTAT 9 +.Os +.Sh NAME +.Nm devstat , +.Nm devstat_add_entry , +.Nm devstat_end_transaction , +.Nm devstat_end_transaction_bio , +.Nm devstat_remove_entry , +.Nm devstat_start_transaction +.Nd kernel interface for keeping device statistics +.Sh SYNOPSIS +.In sys/devicestat.h +.Ft void +.Fo devstat_add_entry +.Fa "struct devstat *ds" +.Fa "const char *dev_name" +.Fa "int unit_number" +.Fa "uint32_t block_size" +.Fa "devstat_support_flags flags" +.Fa "devstat_type_flags device_type" +.Fa "devstat_priority priority" +.Fc +.Ft void +.Fn devstat_remove_entry "struct devstat *ds" +.Ft void +.Fn devstat_start_transaction "struct devstat *ds" +.Ft void +.Fo devstat_end_transaction +.Fa "struct devstat *ds" +.Fa "uint32_t bytes" +.Fa "devstat_tag_type tag_type" +.Fa "devstat_trans_flags flags" +.Fc +.Ft void +.Fo devstat_end_transaction_bio +.Fa "struct devstat *ds" +.Fa "struct bio *bp" +.Fc +.Sh DESCRIPTION +The devstat subsystem is an interface for recording device +statistics, as its name implies. +The idea is to keep reasonably detailed +statistics while utilizing a minimum amount of CPU time to record them. +Thus, no statistical calculations are actually performed in the kernel +portion of the +.Nm +code. +Instead, that is left for user programs to handle. +.Pp +.Fn devstat_add_entry +registers a device with the +.Nm +subsystem. +The caller is expected to have already allocated \fBand zeroed\fR +the devstat structure before calling this function. +.Fn devstat_add_entry +takes several arguments: +.Bl -tag -width device_type +.It ds +The +.Va devstat +structure, allocated and zeroed by the client. +.It dev_name +The device name, e.g.\& da, cd, sa. +.It unit_number +Device unit number. +.It block_size +Block size of the device, if supported. +If the device does not support a +block size, or if the blocksize is unknown at the time the device is added +to the +.Nm +list, it should be set to 0. +.It flags +Flags indicating operations supported or not supported by the device. +See below for details. +.It device_type +The device type. +This is broken into three sections: base device type +(e.g.\& direct access, CDROM, sequential access), interface type (IDE, SCSI +or other) and a pass-through flag to indicate pas-through devices. +See below for a complete list of types. +.It priority +The device priority. +The priority is used to determine how devices are +sorted within +.Nm devstat Ns 's +list of devices. +Devices are sorted first by priority (highest to lowest), +and then by attach order. +See below for a complete list of available +priorities. +.El +.Pp +.Fn devstat_remove_entry +removes a device from the +.Nm +subsystem. +It takes the devstat structure for the device in question as +an argument. +The +.Nm +generation number is incremented and the number of devices is decremented. +.Pp +.Fn devstat_start_transaction +registers the start of a transaction with the +.Nm +subsystem. +The busy count is incremented with each transaction start. +When a device goes from idle to busy, the system uptime is recorded in the +.Va start_time +field of the +.Va devstat +structure. +.Pp +.Fn devstat_end_transaction +registers the end of a transaction with the +.Nm +subsystem. +It takes four arguments: +.Bl -tag -width tag_type +.It ds +The +.Va devstat +structure for the device in question. +.It bytes +The number of bytes transferred in this transaction. +.It tag_type +Transaction tag type. +See below for tag types. +.It flags +Transaction flags indicating whether the transaction was a read, write, or +whether no data was transferred. +.El +.Pp +.Fn devstat_end_transaction_bio +is a wrapper for +.Fn devstat_end_transaction +which pulls all the information from a +.Va "struct bio" +which is ready for biodone(). +.Pp +The +.Va devstat +structure is composed of the following fields: +.Bl -tag -width dev_creation_time +.It dev_links +Each +.Va devstat +structure is placed in a linked list when it is registered. +The +.Va dev_links +field contains a pointer to the next entry in the list of +.Va devstat +structures. +.It device_number +The device number is a unique identifier for each device. +The device +number is incremented for each new device that is registered. +The device +number is currently only a 32-bit integer, but it could be enlarged if +someone has a system with more than four billion device arrival events. +.It device_name +The device name is a text string given by the registering driver to +identify itself. +(e.g.\& +.Dq da , +.Dq cd , +.Dq sa , +etc.) +.It unit_number +The unit number identifies the particular instance of the peripheral driver +in question. +.It bytes_written +This is the number of bytes that have been written to the device. +This number is currently an unsigned 64 bit integer. +This will hopefully +eliminate the counter wrap that would come very quickly on some systems if +32 bit integers were used. +.It bytes_read +This is the number of bytes that have been read from the device. +.It bytes_freed +This is the number of bytes that have been freed/erased on the device. +.It num_reads +This is the number of reads from the device. +.It num_writes +This is the number of writes to the device. +.It num_frees +This is the number of free/erase operations on the device. +.It num_other +This is the number of transactions to the device which are neither reads or +writes. +For instance, +.Tn SCSI +drivers often send a test unit ready command to +.Tn SCSI +devices. +The test unit ready command does not read or write any data. +It merely causes the device to return its status. +.It busy_count +This is the current number of outstanding transactions for the device. +This should never go below zero, and on an idle device it should be zero. +If either one of these conditions is not true, it indicates a problem in +the way +.Fn devstat_start_transaction +and +.Fn devstat_end_transaction +are being called in client code. +There should be one and only one +transaction start event and one transaction end event for each transaction. +.It block_size +This is the block size of the device, if the device has a block size. +.It tag_types +This is an array of counters to record the number of various tag types that +are sent to a device. +See below for a list of tag types. +.It dev_creation_time +This is the time, as reported by +.Fn getmicrotime +that the device was registered. +.It busy_time +This is the amount of time that the device busy count has been greater than +zero. +This is only updated when the busy count returns to zero. +.It start_time +This is the time, as reported by +.Fn getmicrouptime +that the device busy count went from zero to one. +.It last_comp_time +This is the time as reported by +.Fn getmicrouptime +that a transaction last completed. +It is used along with +.Va start_time +to calculate the device busy time. +.It flags +These flags indicate which statistics measurements are supported by a +particular device. +These flags are primarily intended to serve as an aid +to userland programs that decipher the statistics. +.It device_type +This is the device type. +It consists of three parts: the device type +(e.g.\& direct access, CDROM, sequential access, etc.), the interface (IDE, +SCSI or other) and whether or not the device in question is a pass-through +driver. +See below for a complete list of device types. +.It priority +This is the priority. +This is the first parameter used to determine where +to insert a device in the +.Nm +list. +The second parameter is attach order. +See below for a list of +available priorities. +.El +.Pp +Each device is given a device type. +Pass-through devices have the same +underlying device type and interface as the device they provide an +interface for, but they also have the pass-through flag set. +The base +device types are identical to the +.Tn SCSI +device type numbers, so with +.Tn SCSI +peripherals, the device type returned from an inquiry is usually ORed with +the +.Tn SCSI +interface type and the pass-through flag if appropriate. +The device type +flags are as follows: +.Bd -literal -offset indent +typedef enum { + DEVSTAT_TYPE_DIRECT = 0x000, + DEVSTAT_TYPE_SEQUENTIAL = 0x001, + DEVSTAT_TYPE_PRINTER = 0x002, + DEVSTAT_TYPE_PROCESSOR = 0x003, + DEVSTAT_TYPE_WORM = 0x004, + DEVSTAT_TYPE_CDROM = 0x005, + DEVSTAT_TYPE_SCANNER = 0x006, + DEVSTAT_TYPE_OPTICAL = 0x007, + DEVSTAT_TYPE_CHANGER = 0x008, + DEVSTAT_TYPE_COMM = 0x009, + DEVSTAT_TYPE_ASC0 = 0x00a, + DEVSTAT_TYPE_ASC1 = 0x00b, + DEVSTAT_TYPE_STORARRAY = 0x00c, + DEVSTAT_TYPE_ENCLOSURE = 0x00d, + DEVSTAT_TYPE_FLOPPY = 0x00e, + DEVSTAT_TYPE_MASK = 0x00f, + DEVSTAT_TYPE_IF_SCSI = 0x010, + DEVSTAT_TYPE_IF_IDE = 0x020, + DEVSTAT_TYPE_IF_OTHER = 0x030, + DEVSTAT_TYPE_IF_MASK = 0x0f0, + DEVSTAT_TYPE_PASS = 0x100 +} devstat_type_flags; +.Ed +.Pp +Devices have a priority associated with them, which controls roughly where +they are placed in the +.Nm +list. +The priorities are as follows: +.Bd -literal -offset indent +typedef enum { + DEVSTAT_PRIORITY_MIN = 0x000, + DEVSTAT_PRIORITY_OTHER = 0x020, + DEVSTAT_PRIORITY_PASS = 0x030, + DEVSTAT_PRIORITY_FD = 0x040, + DEVSTAT_PRIORITY_WFD = 0x050, + DEVSTAT_PRIORITY_TAPE = 0x060, + DEVSTAT_PRIORITY_CD = 0x090, + DEVSTAT_PRIORITY_DISK = 0x110, + DEVSTAT_PRIORITY_ARRAY = 0x120, + DEVSTAT_PRIORITY_MAX = 0xfff +} devstat_priority; +.Ed +.Pp +Each device has associated with it flags to indicate what operations are +supported or not supported. +The +.Va devstat_support_flags +values are as follows: +.Bl -tag -width DEVSTAT_NO_ORDERED_TAGS +.It DEVSTAT_ALL_SUPPORTED +Every statistic type is supported by the device. +.It DEVSTAT_NO_BLOCKSIZE +This device does not have a blocksize. +.It DEVSTAT_NO_ORDERED_TAGS +This device does not support ordered tags. +.It DEVSTAT_BS_UNAVAILABLE +This device supports a blocksize, but it is currently unavailable. +This +flag is most often used with removable media drives. +.El +.Pp +Transactions to a device fall into one of three categories, which are +represented in the +.Va flags +passed into +.Fn devstat_end_transaction . +The transaction types are as follows: +.Bd -literal -offset indent +typedef enum { + DEVSTAT_NO_DATA = 0x00, + DEVSTAT_READ = 0x01, + DEVSTAT_WRITE = 0x02, + DEVSTAT_FREE = 0x03 +} devstat_trans_flags; +.Ed +.Pp +There are four possible values for the +.Va tag_type +argument to +.Fn devstat_end_transaction : +.Bl -tag -width DEVSTAT_TAG_ORDERED +.It DEVSTAT_TAG_SIMPLE +The transaction had a simple tag. +.It DEVSTAT_TAG_HEAD +The transaction had a head of queue tag. +.It DEVSTAT_TAG_ORDERED +The transaction had an ordered tag. +.It DEVSTAT_TAG_NONE +The device does not support tags. +.El +.Pp +The tag type values correspond to the lower four bits of the +.Tn SCSI +tag definitions. +In CAM, for instance, the +.Va tag_action +from the CCB is ORed with 0xf to determine the tag type to pass in to +.Fn devstat_end_transaction . +.Pp +There is a macro, +.Dv DEVSTAT_VERSION +that is defined in +.In sys/devicestat.h . +This is the current version of the +.Nm +subsystem, and it should be incremented each time a change is made that +would require recompilation of userland programs that access +.Nm +statistics. +Userland programs use this version, via the +.Va kern.devstat.version +.Nm sysctl +variable to determine whether they are in sync with the kernel +.Nm +structures. +.Sh SEE ALSO +.Xr systat 1 , +.Xr devstat 3 , +.Xr iostat 8 , +.Xr rpc.rstatd 8 , +.Xr vmstat 8 +.Sh HISTORY +The +.Nm +statistics system appeared in +.Fx 3.0 . +.Sh AUTHORS +.An Kenneth Merry Aq Mt ken@FreeBSD.org +.Sh BUGS +There may be a need for +.Fn spl +protection around some of the +.Nm +list manipulation code to ensure, for example, that the list of devices +is not changed while someone is fetching the +.Va kern.devstat.all +.Nm sysctl +variable. +.Pp +It is impossible with the current +.Nm +architecture to accurately measure time per transaction. +The only feasible +way to accurately measure time per transaction would be to record a +timestamp for every transaction. +This measurement is probably not +worthwhile for most people as it would adversely affect the performance of +the system and cost space to store the timestamps for individual +transactions. Property changes on: user/imp/camdoc/devstat.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/fail.9 =================================================================== --- user/imp/camdoc/fail.9 (nonexistent) +++ user/imp/camdoc/fail.9 (revision 296049) @@ -0,0 +1,208 @@ +.\" +.\" Copyright (c) 2009 Isilon Inc http://www.isilon.com/ +.\" +.\" 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 May 10, 2009 +.Dt FAIL 9 +.Os +.Sh NAME +.Nm KFAIL_POINT_CODE , +.Nm KFAIL_POINT_RETURN , +.Nm KFAIL_POINT_RETURN_VOID , +.Nm KFAIL_POINT_ERROR , +.Nm KFAIL_POINT_GOTO , +.Nm fail_point , +.Nm DEBUG_FP +.Nd fail points +.Sh SYNOPSIS +.In sys/fail.h +.Fn KFAIL_POINT_CODE "parent" "name" "code" +.Fn KFAIL_POINT_RETURN "parent" "name" +.Fn KFAIL_POINT_RETURN_VOID "parent" "name" +.Fn KFAIL_POINT_ERROR "parent" "name" "error_var" +.Fn KFAIL_POINT_GOTO "parent" "name" "error_var" "label" +.Sh DESCRIPTION +Fail points are used to add code points where errors may be injected +in a user controlled fashion. +Fail points provide a convenient wrapper around user-provided error +injection code, providing a +.Xr sysctl 9 +MIB, and a parser for that MIB that describes how the error +injection code should fire. +.Pp +The base fail point macro is +.Fn KFAIL_POINT_CODE +where +.Fa parent +is a sysctl tree (frequently +.Sy DEBUG_FP +for kernel fail points, but various subsystems may wish to provide +their own fail point trees), and +.Fa name +is the name of the MIB in that tree, and +.Fa code +is the error injection code. +The +.Fa code +argument does not require braces, but it is considered good style to +use braces for any multi-line code arguments. +Inside the +.Fa code +argument, the evaluation of +.Sy RETURN_VALUE +is derived from the +.Fn return +value set in the sysctl MIB. +See +.Sx SYSCTL VARIABLES +below. +.Pp +The remaining +.Fn KFAIL_POINT_* +macros are wrappers around common error injection paths: +.Bl -inset +.It Fn KFAIL_POINT_RETURN parent name +is the equivalent of +.Sy KFAIL_POINT_CODE(..., return RETURN_VALUE) +.It Fn KFAIL_POINT_RETURN_VOID parent name +is the equivalent of +.Sy KFAIL_POINT_CODE(..., return) +.It Fn KFAIL_POINT_ERROR parent name error_var +is the equivalent of +.Sy KFAIL_POINT_CODE(..., error_var = RETURN_VALUE) +.It Fn KFAIL_POINT_GOTO parent name error_var label +is the equivalent of +.Sy KFAIL_POINT_CODE(..., { error_var = RETURN_VALUE; goto label;}) +.El +.Sh SYSCTL VARIABLES +The +.Fn KFAIL_POINT_* +macros add sysctl MIBs where specified. +Many base kernel MIBs can be found in the +.Sy debug.fail_point +tree (referenced in code by +.Sy DEBUG_FP ) . +.Pp +The sysctl variable may be set using the following grammar: +.Bd -literal + :: + ( "->" )* + + :: + ( ( "%") | ( "*" ) )* + + [ "(" ")" ] + [ "[pid " "]" ] + + :: + [ "." ] | + "." + + :: + "off" | "return" | "sleep" | "panic" | "break" | "print" +.Ed +.Pp +The argument specifies which action to take: +.Bl -tag -width ".Dv return" +.It Sy off +Take no action (does not trigger fail point code) +.It Sy return +Trigger fail point code with specified argument +.It Sy sleep +Sleep the specified number of milliseconds +.It Sy panic +Panic +.It Sy break +Break into the debugger, or trap if there is no debugger support +.It Sy print +Print that the fail point executed +.El +.Pp +The % and * modifiers prior to control when + is executed. +The % form (e.g. "1.2%") can be used to specify a +probability that will execute. +The * form (e.g. "5*") can be used to specify the number of +times should be executed before this is disabled. +Only the last probability and the last count are used if multiple +are specified, i.e. "1.2%2%" is the same as "2%". +When both a probability and a count are specified, the probability +is evaluated before the count, i.e. "2%5*" means "2% of the time, +but only 5 times total". +.Pp +The operator -> can be used to express cascading terms. +If you specify ->, it means that if does not +.Ql execute , + is evaluated. +For the purpose of this operator, the return() and print() operators +are the only types that cascade. +A return() term only cascades if the code executes, and a print() +term only cascades when passed a non-zero argument. +A pid can optionally be specified. +The fail point term is only executed when invoked by a process with a +matching p_pid. +.Sh EXAMPLES +.Bl -tag -width Sy +.It Sy sysctl debug.fail_point.foobar="2.1%return(5)" +21/1000ths of the time, execute +.Fa code +with RETURN_VALUE set to 5. +.It Sy sysctl debug.fail_point.foobar="2%return(5)->5%return(22)" +2/100ths of the time, execute +.Fa code +with RETURN_VALUE set to 5. +If that does not happen, 5% of the time execute +.Fa code +with RETURN_VALUE set to 22. +.It Sy sysctl debug.fail_point.foobar="5*return(5)->0.1%return(22)" +For 5 times, return 5. +After that, 1/1000th of the time, return 22. +.It Sy sysctl debug.fail_point.foobar="0.1%5*return(5)" +Return 5 for 1 in 1000 executions, but only 5 times total. +.It Sy sysctl debug.fail_point.foobar="1%*sleep(50)" +1/100th of the time, sleep 50ms. +.It Sy sysctl debug.fail_point.foobar="1*return(5)[pid 1234]" +Return 5 once, when pid 1234 executes the fail point. +.El +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Zach Loafman Aq Mt zml@FreeBSD.org . +.Sh CAVEATS +It is easy to shoot yourself in the foot by setting fail points too +aggressively or setting too many in combination. +For example, forcing +.Fn malloc +to fail consistently is potentially harmful to uptime. +.Pp +The +.Fn sleep +sysctl setting may not be appropriate in all situations. +Currently, +.Fn fail_point_eval +does not verify whether the context is appropriate for calling +.Fn msleep . Property changes on: user/imp/camdoc/fail.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/firmware.9 =================================================================== --- user/imp/camdoc/firmware.9 (nonexistent) +++ user/imp/camdoc/firmware.9 (revision 296049) @@ -0,0 +1,272 @@ +.\" 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, +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 +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. +.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 . Property changes on: user/imp/camdoc/firmware.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_access.9 =================================================================== --- user/imp/camdoc/g_access.9 (nonexistent) +++ user/imp/camdoc/g_access.9 (revision 296049) @@ -0,0 +1,165 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_ACCESS 9 +.Os +.Sh NAME +.Nm g_access +.Nd "control access to GEOM consumers and their providers" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_access "struct g_consumer *cp" "int dcr" "int dcw" "int dce" +.Sh DESCRIPTION +The +.Fn g_access +function allows to open, close, and generally change access to the provider +which is attached to the given consumer +.Fa cp . +The arguments +.Fa dcr , +.Fa dcw , +and +.Fa dce +represent relative read, write, and exclusive access count changes. +Read and write access counts are self explanatory, and +exclusive access counts deny write access to other interested parties. +A provider's access count is the sum of the access counts of all +attached consumers. +.Pp +After attaching a consumer to a provider with +.Xr g_attach 9 , +the +.Fn g_access +function has to be called on the consumer before starting I/O requests. +.Sh RESTRICTIONS/CONDITIONS +The consumer has to be attached to a provider. +.Pp +The intended change must not result in a negative access count. +.Pp +No-operation is not permitted +.Fa ( dcr += +.Fa dcw += +.Fa dce += +.Li 0 ) . +.Pp +The provider's geom must have an access method defined (e.g., +.Va gp->access ) . +.Pp +The topology lock has to be held. +.Sh RETURN VALUES +The +.Fn g_access +function returns 0 if successful; otherwise an error code is returned. +Note that +.Fn g_access +cannot fail when the arguments +.Fa dcr , +.Fa dcw , +and +.Fa dce +are less than or equal to 0. +.Sh EXAMPLES +Create a consumer, attach it to a given provider, gain read access and +read first sector. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + void *ptr; + int error; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + error = g_access(cp, 1, 0, 0); + if (error != 0) { + printf("Cannot access provider: %s\\n", error); + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + /* + * Don't hold topology lock while reading. + */ + g_topology_unlock(); + ptr = g_read_data(cp, 0, pp->sectorsize, &error); + if (ptr == NULL) + printf("Error while reading: %d\\n", error); + /* + * Do something useful with data. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er EPERM +The function is trying to open a provider with an exclusive access count, but +it is already open for writing. +.It Bq Er EPERM +The function is trying to open a provider for writing, but it is already +exclusively open. +.El +.Pp +Any other error that can be returned by the provider's access method. +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_access.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_attach.9 =================================================================== --- user/imp/camdoc/g_attach.9 (nonexistent) +++ user/imp/camdoc/g_attach.9 (revision 296049) @@ -0,0 +1,141 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_ATTACH 9 +.Os +.Sh NAME +.Nm g_attach , +.Nm g_detach +.Nd "attach/detach GEOM consumers to/from providers" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_attach "struct g_consumer *cp" "struct g_provider *pp" +.Ft void +.Fn g_detach "struct g_consumer *cp" +.Sh DESCRIPTION +The +.Fn g_attach +function attaches given consumer +.Fa cp +to given provider +.Fa pp , +thus establishing a communication channel between the consumer and the +provider that allows to change access counts and perform I/O operations. +.Pp +The +.Fn g_detach +function detaches given consumer +.Fa cp +from its corresponding provider, tearing down the communication channel +between them. +.Sh RESTRICTIONS/CONDITIONS +.Fn g_attach : +.Bl -item -offset indent +.It +The consumer must not be attached to a provider. +.It +The operation must not create a topology loop. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_detach : +.Bl -item -offset indent +.It +The consumer has to be attached. +.It +The access count has to be 0. +.It +There must be no active requests. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_attach +function returns 0 if successful; otherwise an error code is returned. +.Sh EXAMPLES +Create a consumer, attach it to a given provider, gain read access and clean up. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + if (g_access(cp, 1, 0, 0) != 0) { + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + g_topology_unlock(); + /* + * Read data from provider. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er ELOOP +The operation creates a topology loop. +.El +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_attach.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_consumer.9 =================================================================== --- user/imp/camdoc/g_consumer.9 (nonexistent) +++ user/imp/camdoc/g_consumer.9 (revision 296049) @@ -0,0 +1,137 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_CONSUMER 9 +.Os +.Sh NAME +.Nm g_new_consumer , +.Nm g_destroy_consumer +.Nd "GEOM consumers management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_consumer *" +.Fn g_new_consumer "struct g_geom *gp" +.Ft void +.Fn g_destroy_consumer "struct g_consumer *cp" +.Sh DESCRIPTION +A GEOM consumer is the backdoor through which a geom connects to +another GEOM provider and through which I/O requests are sent. +.Pp +The +.Fn g_new_consumer +function creates a new consumer on geom +.Fa gp . +Before using the new consumer, it has to be attached to a provider with +.Xr g_attach 9 +and opened with +.Xr g_access 9 . +.Pp +The +.Fn g_destroy_consumer +function destroys the given consumer and cancels all related pending events. +This function is the last stage of killing an unwanted consumer. +.Sh RESTRICTIONS/CONDITIONS +.Fn g_new_consumer : +.Bl -item -offset indent +.It +The geom +.Fa gp +has to have an +.Va orphan +method defined. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_consumer : +.Bl -item -offset indent +.It +The consumer must not be attached to a provider. +.It +The access count has to be 0. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_new_consumer +function +returns a pointer to the newly created consumer. +.Sh EXAMPLES +Create consumer, attach it to given provider, gain read access and clean up. +.Bd -literal -offset indent +void +some_function(struct g_geom *mygeom, struct g_provider *pp) +{ + struct g_consumer *cp; + + g_topology_assert(); + + /* Create new consumer on 'mygeom' geom. */ + cp = g_new_consumer(mygeom); + /* Attach newly created consumer to given provider. */ + if (g_attach(cp, pp) != 0) { + g_destroy_consumer(cp); + return; + } + /* Open provider for reading through our consumer. */ + if (g_access(cp, 1, 0, 0) != 0) { + g_detach(cp); + g_destroy_consumer(cp); + return; + } + + g_topology_unlock(); + /* + * Read data from provider. + */ + g_topology_lock(); + + /* Disconnect from provider (release access count). */ + g_access(cp, -1, 0, 0); + /* Detach from provider. */ + g_detach(cp); + /* Destroy consumer. */ + g_destroy_consumer(cp); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_consumer.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_data.9 =================================================================== --- user/imp/camdoc/g_data.9 (nonexistent) +++ user/imp/camdoc/g_data.9 (revision 296049) @@ -0,0 +1,122 @@ +.\" +.\" Copyright (c) 2004-2005 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_DATA 9 +.Os +.Sh NAME +.Nm g_read_data , +.Nm g_write_data +.Nd "read/write data from/to GEOM consumer" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "void *" +.Fo g_read_data +.Fa "struct g_consumer *cp" "off_t offset" "off_t length" "int *error" +.Fc +.Ft int +.Fo g_write_data +.Fa "struct g_consumer *cp" "off_t offset" "void *ptr" "off_t length" +.Fc +.Sh DESCRIPTION +The +.Fn g_read_data +function reads +.Fa length +bytes of data from the provider attached to consumer +.Fa cp , +starting at offset +.Fa offset . +The buffer returned from +.Fn g_read_data +is allocated with +.Fn g_malloc , +so it should be freed by the caller with +.Fn g_free +after use. +If the operation fails, an error value will be stored in the +.Fa error +argument if it is not +.Dv NULL . +.Pp +The +.Fn g_write_data +function writes +.Fa length +bytes of data from the buffer pointed to by +.Fa ptr +to the provider attached to consumer +.Fa cp , +starting at offset +.Fa offset . +.Sh RESTRICTIONS/CONDITIONS +The +.Fa length +argument +should be a multiple of the provider's sectorsize +and less than or equal to +.Dv DFLTPHYS +.Dv ( DFLTPHYS +is defined in +.In sys/param.h ) . +.Pp +The topology lock must not be held. +.Sh RETURN VALUES +The +.Fn g_read_data +function returns a pointer to a data buffer or +.Dv NULL +if an error occurred. +In that case an error value is stored in the +.Fa error +argument unless it is +.Dv NULL . +.Pp +The +.Fn g_write_data +function returns 0 if successful; otherwise an error code is returned. +.Sh ERRORS +Possible errors: +.Bl -tag -width Er +.It Bq Er EIO +An I/O error occurred while reading from or writing to the consumer. +.El +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_data.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_event.9 =================================================================== --- user/imp/camdoc/g_event.9 (nonexistent) +++ user/imp/camdoc/g_event.9 (revision 296049) @@ -0,0 +1,189 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_EVENT 9 +.Os +.Sh NAME +.Nm g_post_event , +.Nm g_waitfor_event , +.Nm g_cancel_event +.Nd "GEOM events management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft int +.Fn g_post_event "g_event_t *func" "void *arg" "int flag" ... +.Ft int +.Fn g_waitfor_event "g_event_t *func" "void *arg" "int flag" ... +.Ft void +.Fn g_cancel_event "void *ref" +.Sh DESCRIPTION +The GEOM framework has its own event queue to inform classes about important +events. +The event queue can be also used by GEOM classes themselves, for example +to work around some restrictions in the I/O path, where sleeping, heavy weight +tasks, etc.\& are not permitted. +.Pp +The +.Fn g_post_event +function tells the GEOM framework to call function +.Fa func +with argument +.Fa arg +from the event queue. +The +.Fa flag +argument is passed to +.Xr malloc 9 +for memory allocations inside of +.Fn g_post_event . +The only allowed flags are +.Dv M_WAITOK +and +.Dv M_NOWAIT . +The rest of the arguments are used as references to identify the event. +An event can be canceled by using any of the given references as an +argument to +.Fn g_cancel_event . +The list of references has to end with a +.Dv NULL +value. +.Pp +The +.Fn g_waitfor_event +function is a blocking version of the +.Fn g_post_event +function. +It waits until the event is finished or canceled and then returns. +.Pp +The +.Fn g_cancel_event +function cancels all event(s) identified by +.Fa ref . +Cancellation is equivalent to calling the requested function +with requested arguments and argument +.Fa flag +set to +.Dv EV_CANCEL . +.Sh RESTRICTIONS/CONDITIONS +.Fn g_post_event : +.Bl -item -offset indent +.It +The argument +.Fa flag +has to be +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It +The list of references has to end with a +.Dv NULL +value. +.El +.Pp +.Fn g_waitfor_event : +.Bl -item -offset indent +.It +The argument +.Fa flag +has to be +.Dv M_WAITOK +or +.Dv M_NOWAIT . +.It +The list of references has to end with a +.Dv NULL +value. +.It +The +.Fn g_waitfor_event +function cannot be called from an event, since doing so would result +in a deadlock. +.El +.Sh RETURN VALUES +The +.Fn g_post_event +and +.Fn g_waitfor_event +functions +return 0 if successful; otherwise an error code is returned. +.Sh EXAMPLES +Example of a function called from the event queue. +.Bd -literal -offset indent +void +example_event(void *arg, int flag) +{ + + if (flag == EV_CANCEL) { + printf("Event with argument %p canceled.\\n", arg); + return; + } + + printf("Event with argument %p called.\\n", arg); +} +.Ed +.Sh ERRORS +Possible errors for the +.Fn g_post_event +function: +.Bl -tag -width Er +.It Bq Er ENOMEM +The +.Fa flag +argument was set to +.Dv M_NOWAIT +and there was insufficient memory. +.El +.Pp +Possible errors for the +.Fn g_waitfor_event +function: +.Bl -tag -width Er +.It Bq Er EAGAIN +The event was canceled. +.It Bq Er ENOMEM +The +.Fa flag +argument was set to +.Dv M_NOWAIT +and there was insufficient memory. +.El +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_event.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_geom.9 =================================================================== --- user/imp/camdoc/g_geom.9 (nonexistent) +++ user/imp/camdoc/g_geom.9 (revision 296049) @@ -0,0 +1,206 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_GEOM 9 +.Os +.Sh NAME +.Nm g_new_geomf , +.Nm g_destroy_geom +.Nd "geom management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_geom *" +.Fn g_new_geomf "struct g_class *mp" "const char *fmt" ... +.Ft void +.Fn g_destroy_geom "struct g_geom *gp" +.Sh DESCRIPTION +The geom (do not confuse +.Dq geom +with +.Dq GEOM ) +is an instance of a GEOM class. +For example: in a typical i386 +.Fx +system, there will be one geom +of class MBR for each disk. +The geom's name is not really important, it is only used in the XML +dump and for debugging purposes. +There can be many geoms with the same name. +.Pp +The +.Fn g_new_geomf +function creates a new geom, which will be an instance of the class +.Fa mp . +The geom's name is created in a +.Xr printf 3 Ns +-like way from the rest of the arguments. +.Pp +The +.Fn g_destroy_geom +function destroys the given geom immediately and cancels all related pending +events. +.Pp +The +.Vt g_geom +structure +contains fields that should be set by the caller after geom creation, but before +creating any providers or consumers related to this geom (not all are required): +.Bl -tag -offset indent -width indent +.It Vt "g_start_t *" Va start +Pointer to a function used for I/O processing. +.It Vt "g_spoiled_t *" Va spoiled +Pointer to a function used for consumers spoiling. +.It Vt "g_dumpconf_t *" Va dumpconf +Pointer to a function used for configuration in XML format dumping. +.It Vt "g_access_t *" Va access +Pointer to a function used for access control. +.It Vt "g_orphan_t *" Va orphan +Pointer to a function used to inform about orphaned consumer. +.It Vt "g_ioctl_t *" Va ioctl +Pointer to a function used for handling ioctl requests. +.It Vt "void *" Va softc +Field for private use. +.El +.Sh RESTRICTIONS/CONDITIONS +If you intend to use providers in this geom you must set field +.Va start +of your geom. +.Pp +If you are planning to use consumers in your geom you must set fields +.Va orphan +and +.Va access +for it. +.Pp +.Fn g_new_geomf : +.Bl -item -offset indent +.It +Class +.Fa mp +must be valid (registered in GEOM). +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_geom : +.Bl -item -offset indent +.It +The geom cannot possess any providers. +.It +The geom cannot possess any consumers. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_new_geomf +function +returns a pointer to the newly created geom. +.Sh EXAMPLES +Create an example geom. +.Bd -literal -offset indent +static struct geom * +g_example_start(struct bio *bp) +{ + + [...] +} + +static void +g_example_orphan(struct g_consumer *cp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_spoiled(struct g_consumer *cp) +{ + + g_topology_assert(); + + [...] +} + +static void +g_example_access(struct g_provider *pp, int dr, int dw, int de) +{ + + [...] +} + +static struct g_geom * +create_example_geom(struct g_class *myclass) +{ + struct g_geom *gp; + + g_topology_lock(); + gp = g_new_geomf(myclass, "example_geom"); + g_topology_unlock(); + gp->start = g_example_start; + gp->orphan = g_example_orphan; + gp->spoiled = g_example_spoiled; + gp->access = g_example_access; + gp->softc = NULL; + + return (gp); +} + +static int +destroy_example_geom(struct g_geom *gp) +{ + + g_topology_lock(); + if (!LIST_EMPTY(&gp->provider) || + !LIST_EMPTY(&gp->consumer)) { + g_topology_unlock(); + return (EBUSY); + } + g_destroy_geom(gp); + g_topology_unlock(); + + return (0); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_geom.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_provider.9 =================================================================== --- user/imp/camdoc/g_provider.9 (nonexistent) +++ user/imp/camdoc/g_provider.9 (revision 296049) @@ -0,0 +1,145 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_PROVIDER 9 +.Os +.Sh NAME +.Nm g_new_providerf , +.Nm g_destroy_provider , +.Nm g_error_provider +.Nd "GEOM providers management" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_provider *" +.Fn g_new_providerf "struct g_geom *gp" "const char *fmt" ... +.Ft void +.Fn g_destroy_provider "struct g_provider *pp" +.Ft void +.Fn g_error_provider "struct g_provider *pp" "int error" +.Sh DESCRIPTION +A GEOM provider is the front gate at which a geom offers service. +A provider is +.Dq a disk-like thing which appears in Pa /dev +\[en] a logical disk in other words. +All providers have three main properties: name, sectorsize and size. +.Pp +The +.Fn g_new_providerf +function creates a new provider on given geom +.Fa gp . +The name of the provider, which will appear as device in +.Xr devfs 5 , +is created +in a +.Xr printf 3 Ns +-like way from the rest of +the arguments. +After creation, the caller has to set the provider's +.Va mediasize +and +.Va sectorsize , +as well as other desired initializations, and then call +.Fn g_error_provider +to reset the provider's error, which is initially set to +.Er ENXIO . +.Pp +The +.Fn g_destroy_provider +function destroys the given provider, cancels all related pending events and +removes the corresponding devfs entry. +.Pp +The +.Fn g_error_provider +function is used to set the provider's error value. +If set to a nonzero, all I/O requests will be denied, +as well as increasing its access count will not be possible (error +.Fa error +will be returned). +.Sh RESTRICTIONS/CONDITIONS +.Fn g_new_provider : +.Bl -item -offset indent +.It +The provider name should be unique, but this is not enforced by GEOM. +If the name is not unique, one will end up with two (or more) files +with the same name, which is a programmer error. +.It +The geom +.Fa gp +has to have a +.Fa start +method defined. +.It +The topology lock has to be held. +.El +.Pp +.Fn g_destroy_provider : +.Bl -item -offset indent +.It +The provider must not have consumers attached. +.It +The access count has to be 0. +.It +The topology lock has to be held. +.El +.Sh RETURN VALUES +The +.Fn g_new_providerf +function returns a pointer to the newly created provider. +.Sh EXAMPLES +Create an example provider, set its parameters and make it usable. +.Bd -literal -offset indent +struct g_provider * +create_example_provider(struct g_geom *gp) +{ + struct g_provider *pp; + + g_topology_lock(); + pp = g_new_providerf(gp, "example_provider"); + g_topology_unlock(); + pp->mediasize = 65536; + pp->sectorsize = 512; + g_error_provider(pp, 0); + + return (pp); +} +.Ed +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider_by_name 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_provider.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_provider_by_name.9 =================================================================== --- user/imp/camdoc/g_provider_by_name.9 (nonexistent) +++ user/imp/camdoc/g_provider_by_name.9 (revision 296049) @@ -0,0 +1,77 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_PROVIDER_BY_NAME 9 +.Os +.Sh NAME +.Nm g_provider_by_name +.Nd "find GEOM provider with given name" +.Sh SYNOPSIS +.In geom/geom.h +.Ft "struct g_provider *" +.Fn g_provider_by_name "const char *name" +.Sh DESCRIPTION +The +.Fn g_provider_by_name +function searches for a provider called +.Fa name +and returns the structure +.Vt g_provider +bound to it. +Argument +.Fa name +should be a name, not a full path (i.e., +.Dq Pa da0 , +instead of +.Dq Pa /dev/da0 ) . +.Sh RESTRICTIONS/CONDITIONS +The topology lock has to be held. +.Sh RETURN VALUES +The +.Fn g_provider_by_name +function +returns a pointer to the provider called +.Fa name +or +.Dv NULL +if there is no such provider. +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_wither_geom 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_provider_by_name.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/g_wither_geom.9 =================================================================== --- user/imp/camdoc/g_wither_geom.9 (nonexistent) +++ user/imp/camdoc/g_wither_geom.9 (revision 296049) @@ -0,0 +1,86 @@ +.\" +.\" Copyright (c) 2004 Pawel Jakub Dawidek +.\" 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 January 16, 2004 +.Dt G_WITHER_GEOM 9 +.Os +.Sh NAME +.Nm g_wither_geom +.Nd "destroy geom and related providers and consumers when you get a chance" +.Sh SYNOPSIS +.In geom/geom.h +.Ft void +.Fn g_wither_geom "struct g_geom *gp" "int error" +.Sh DESCRIPTION +The +.Fn g_wither_geom +function tells GEOM that geom +.Fa gp +is to be destroyed. +GEOM sets an error on each provider of the given geom (in the +orphaning process) and waits for a chance to destroy the geom. +If the access count of any possessed consumer goes to 0, the consumer will be +detached and destroyed automatically. +If the last consumer attached to any possessed provider will be detached, +the provider will be destroyed. +If there are no more providers nor consumers, the geom will be +destroyed. +.Pp +This is an automatic +.Dq garbage collect +to avoid duplicated code in all classes. +Before it is called, field +.Va softc +should be disposed of and set to +.Dv NULL . +Note that the +.Fn g_wither_geom +function gives no guarantee that the geom will be immediately destroyed, mostly +because the access counts of the geom's consumers and providers may not be 0. +That is why calling this function for every geom from a given class is not enough +to be sure that the class can be unloaded. +.Sh RESTRICTIONS/CONDITIONS +The argument +.Fa error +must be nonzero. +.Pp +The topology lock has to be held. +.Sh SEE ALSO +.Xr geom 4 , +.Xr DECLARE_GEOM_CLASS 9 , +.Xr g_access 9 , +.Xr g_attach 9 , +.Xr g_bio 9 , +.Xr g_consumer 9 , +.Xr g_data 9 , +.Xr g_event 9 , +.Xr g_geom 9 , +.Xr g_provider 9 , +.Xr g_provider_by_name 9 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org . Property changes on: user/imp/camdoc/g_wither_geom.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/getnewvnode.9 =================================================================== --- user/imp/camdoc/getnewvnode.9 (nonexistent) +++ user/imp/camdoc/getnewvnode.9 (revision 296049) @@ -0,0 +1,69 @@ +.\" +.\" Copyright (C) 2001 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 21, 2001 +.Dt GETNEWVNODE 9 +.Os +.Sh NAME +.Nm getnewvnode +.Nd "get a new vnode" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/mount.h +.Ft int +.Fn getnewvnode "const char *tag" "struct mount *mp" "vop_t **vops" "struct vnode **vpp" +.Sh DESCRIPTION +The +.Fn getnewvnode +function initializes a new vnode, assigning it the vnode operations passed in +.Fa vops . +The vnode is either freshly allocated, or taken from the head of the +free list depending on the number of vnodes already in the system. +.Pp +The arguments to +.Fn getnewvnode +are: +.Bl -tag -width ".Fa vops" +.It Fa tag +The file system type string. +This field should only be referenced for debugging or for userland utilities. +.It Fa mp +The mount point to add the new vnode to. +.It Fa vops +The vnode operations to assign to the new vnode. +.It Fa vpp +Points to the new vnode upon successful completion. +.El +.Sh RETURN VALUES +.Fn getnewvnode +returns 0 on success. +There are currently no failure conditions - that do not result in a panic. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/getnewvnode.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/groupmember.9 =================================================================== --- user/imp/camdoc/groupmember.9 (nonexistent) +++ user/imp/camdoc/groupmember.9 (revision 296049) @@ -0,0 +1,60 @@ +.\" +.\" Copyright (C) 2001 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 July 9, 2001 +.Dt GROUPMEMBER 9 +.Os +.Sh NAME +.Nm groupmember +.Nd checks group set for a group ID +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.Ft int +.Fn groupmember "gid_t gid" "struct ucred *cred" +.Sh DESCRIPTION +The +.Fn groupmember +function checks to see if the given +.Fa gid +is in the group set of the credentials. +.Pp +Its arguments are: +.Bl -tag -width ".Fa cred" +.It Fa gid +The group ID to check for. +.It Fa cred +The credentials to search for the group in. +.El +.Sh RETURN VALUES +If the +.Fa gid +is found, 1 is returned; otherwise, 0 is returned. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/groupmember.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/hhook.9 =================================================================== --- user/imp/camdoc/hhook.9 (nonexistent) +++ user/imp/camdoc/hhook.9 (revision 296049) @@ -0,0 +1,382 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE 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 21, 2013 +.Dt HHOOK 9 +.Os +.Sh NAME +.Nm hhook , +.Nm hhook_head_register , +.Nm hhook_head_deregister , +.Nm hhook_head_deregister_lookup , +.Nm hhook_run_hooks , +.Nm HHOOKS_RUN_IF , +.Nm HHOOKS_RUN_LOOKUP_IF +.Nd Helper Hook Framework +.Sh SYNOPSIS +.In sys/hhook.h +.Ft typedef int +.Fn "\*(lp*hhook_func_t\*(rp" "int32_t hhook_type" "int32_t hhook_id" \ +"void *udata" "void *ctx_data" "void *hdata" "struct osd *hosd" +.Fn "int hhook_head_register" "int32_t hhook_type" "int32_t hhook_id" \ +"struct hhook_head **hhh" "uint32_t flags" +.Fn "int hhook_head_deregister" "struct hhook_head *hhh" +.Fn "int hhook_head_deregister_lookup" "int32_t hhook_type" "int32_t hhook_id" +.Fn "void hhook_run_hooks" "struct hhook_head *hhh" "void *ctx_data" \ +"struct osd *hosd" +.Fn HHOOKS_RUN_IF "hhh" "ctx_data" "hosd" +.Fn HHOOKS_RUN_LOOKUP_IF "hhook_type" "hhook_id" "ctx_data" "hosd" +.Sh DESCRIPTION +.Nm +provides a framework for managing and running arbitrary hook functions at +defined hook points within the kernel. +The KPI was inspired by +.Xr pfil 9 , +and in many respects can be thought of as a more generic superset of pfil. +.Pp +The +.Xr khelp 9 +and +.Nm +frameworks are tightly integrated. +Khelp is responsible for registering and deregistering Khelp module hook +functions with +.Nm +points. +The KPI functions used by +.Xr khelp 9 +to do this are not documented here as they are not relevant to consumers wishing +to instantiate hook points. +.Ss Information for Khelp Module Implementors +Khelp modules indirectly interact with +.Nm +by defining appropriate hook functions for insertion into hook points. +Hook functions must conform to the +.Ft hhook_func_t +function pointer declaration +outlined in the +.Sx SYNOPSIS . +.Pp +The +.Fa hhook_type +and +.Fa hhook_id +arguments identify the hook point which has called into the hook function. +These are useful when a single hook function is registered for multiple hook +points and wants to know which hook point has called into it. +.In sys/hhook.h +lists available +.Fa hhook_type +defines and subsystems which export hook points are responsible for defining +the +.Fa hhook_id +value in appropriate header files. +.Pp +The +.Fa udata +argument will be passed to the hook function if it was specified in the +.Vt struct hookinfo +at hook registration time. +.Pp +The +.Fa ctx_data +argument contains context specific data from the hook point call site. +The data type passed is subsystem dependent. +.Pp +The +.Fa hdata +argument is a pointer to the persistent per-object storage allocated for use by +the module if required. +The pointer will only ever be NULL if the module did not request per-object +storage. +.Pp +The +.Fa hosd +argument can be used with the +.Xr khelp 9 +framework's +.Fn khelp_get_osd +function to access data belonging to a different Khelp module. +.Pp +Khelp modules instruct the Khelp framework to register their hook functions with +.Nm +points by creating a +.Vt "struct hookinfo" +per hook point, which contains the following members: +.Bd -literal -offset indent +struct hookinfo { + hhook_func_t hook_func; + struct helper *hook_helper; + void *hook_udata; + int32_t hook_id; + int32_t hook_type; +}; +.Ed +.Pp +Khelp modules are responsible for setting all members of the struct except +.Va hook_helper +which is handled by the Khelp framework. +.Ss Creating and Managing Hook Points +Kernel subsystems that wish to provide +.Nm +points typically need to make four and possibly five key changes to their +implementation: +.Bl -bullet +.It +Define a list of +.Va hhook_id +mappings in an appropriate subsystem header. +.It +Register each hook point with the +.Fn hhook_head_register +function during initialisation of the subsystem. +.It +Select or create a standardised data type to pass to hook functions as +contextual data. +.It +Add a call to +.Fn HHOOKS_RUN_IF +or +.Fn HHOOKS_RUN_IF_LOOKUP +at the point in the subsystem's code where the hook point should be executed. +.It +If the subsystem can be dynamically added/removed at runtime, each hook +point registered with the +.Fn hhook_head_register +function when the subsystem was initialised needs to be deregistered with the +.Fn hhook_head_deregister +or +.Fn hhook_head_deregister_lookup +functions when the subsystem is being deinitialised prior to removal. +.El +.Pp +The +.Fn hhook_head_register +function registers a hook point with the +.Nm +framework. +The +.Fa hook_type +argument defines the high level type for the hook point. +Valid types are defined in +.In sys/hhook.h +and new types should be added as required. +The +.Fa hook_id +argument specifies a unique, subsystem specific identifier for the hook point. +The +.Fa hhh +argument will, if not NULL, be used to store a reference to the +.Vt struct hhook_head +created as part of the registration process. +Subsystems will generally want to store a local copy of the +.Vt struct hhook_head +so that they can use the +.Fn HHOOKS_RUN_IF +macro to instantiate hook points. +The HHOOK_WAITOK flag may be passed in via the +.Fa flags +argument if +.Xr malloc 9 +is allowed to sleep waiting for memory to become available. +If the hook point is within a virtualised subsystem (e.g. the network stack), +the HHOOK_HEADISINVNET flag should be passed in via the +.Fa flags +argument so that the +.Vt struct hhook_head +created during the registration process will be added to a virtualised list. +.Pp +The +.Fn hhook_head_deregister +function deregisters a previously registered hook point from the +.Nm +framework. +The +.Fa hhh +argument is the pointer to the +.Vt struct hhook_head +returned by +.Fn hhoook_head_register +when the hook point was registered. +.Pp +The +.Fn hhook_head_deregister_lookup +function can be used instead of +.Fn hhook_head_deregister +in situations where the caller does not have a cached copy of the +.Vt struct hhook_head +and wants to deregister a hook point using the appropriate +.Fa hook_type +and +.Fa hook_id +identifiers instead. +.Pp +The +.Fn hhook_run_hooks +function should normally not be called directly and should instead be called +indirectly via the +.Fn HHOOKS_RUN_IF +macro. +However, there may be circumstances where it is preferable to call the function +directly, and so it is documented here for completeness. +The +.Fa hhh +argument references the +.Nm +point to call all registered hook functions for. +The +.Fa ctx_data +argument specifies a pointer to the contextual hook point data to pass into the +hook functions. +The +.Fa hosd +argument should be the pointer to the appropriate object's +.Vt struct osd +if the subsystem provides the ability for Khelp modules to associate per-object +data. +Subsystems which do not should pass NULL. +.Pp +The +.Fn HHOOKS_RUN_IF +macro is the preferred way to implement hook points. +It only calls the +.Fn hhook_run_hooks +function if at least one hook function is registered for the hook point. +By checking for registered hook functions, the macro minimises the cost +associated with adding hook points to frequently used code paths by reducing to +a simple if test in the common case where no hook functions are registered. +The arguments are as described for the +.Fn hhook_run_hooks +function. +.Pp +The +.Fn HHOOKS_RUN_IF_LOOKUP +macro performs the same function as the +.Fn HHOOKS_RUN_IF +macro, but performs an additional step to look up the +.Vt struct hhook_head +for the specified +.Fa hook_type +and +.Fa hook_id +identifiers. +It should not be used except in code paths which are infrequently executed +because of the reference counting overhead associated with the look up. +.Sh IMPLEMENTATION NOTES +Each +.Vt struct hhook_head +protects its internal list of hook functions with a +.Xr rmlock 9 . +Therefore, anytime +.Fn hhook_run_hooks +is called directly or indirectly via the +.Fn HHOOKS_RUN_IF +or +.Fn HHOOKS_RUN_IF_LOOKUP +macros, a non-sleepable read lock will be acquired and held across the calls to +all registered hook functions. +.Sh RETURN VALUES +.Fn hhook_head_register +returns 0 if no errors occurred. +It returns EEXIST if a hook point with the same +.Fa hook_type +and +.Fa hook_id +is already registered. +It returns EINVAL if the HHOOK_HEADISINVNET flag is not set in +.Fa flags +because the implementation does not yet support hook points in non-virtualised +subsystems (see the +.Sx BUGS +section for details). +It returns ENOMEM if +.Xr malloc 9 +failed to allocate memory for the new +.Vt struct hhook_head . +.Pp +.Fn hhook_head_deregister +and +.Fn hhook_head_deregister_lookup +return 0 if no errors occurred. +They return ENOENT if +.Fa hhh +is NULL. +They return EBUSY if the reference count of +.Fa hhh +is greater than one. +.Sh EXAMPLES +A well commented example Khelp module can be found at: +.Pa /usr/share/examples/kld/khelp/h_example.c +.Pp +The +.Xr tcp 4 +implementation provides two +.Nm +points which are called for packets sent/received when a connection is in the +established phase. +Search for HHOOK in the following files: +.Pa sys/netinet/tcp_var.h , +.Pa sys/netinet/tcp_input.c , +.Pa sys/netinet/tcp_output.c +and +.Pa sys/netinet/tcp_subr.c . +.Sh SEE ALSO +.Xr khelp 9 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +framework first appeared in +.Fx 9.0 . +.Pp +The +.Nm +framework was first released in 2010 by Lawrence Stewart whilst studying at +Swinburne University of Technology's Centre for Advanced Internet Architectures, +Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . +.Pp +This manual page was written by +.An David Hayes Aq Mt david.hayes@ieee.org +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . Property changes on: user/imp/camdoc/hhook.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/ieee80211_radiotap.9 =================================================================== --- user/imp/camdoc/ieee80211_radiotap.9 (nonexistent) +++ user/imp/camdoc/ieee80211_radiotap.9 (revision 296049) @@ -0,0 +1,302 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson , +.\" Darron Broad , +.\" David Young . +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 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 4, 2009 +.Dt IEEE80211_RADIOTAP 9 +.Os +.Sh NAME +.Nm ieee80211_radiotap +.Nd 802.11 device packet capture support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Pp +.Ft void +.Fo ieee80211_radiotap_attach +.Fa "struct ieee80211com *" +.Fa "struct ieee80211_radiotap_header *th" +.Fa "int tlen" +.Fa "uint32_t tx_radiotap" +.Fa "struct ieee80211_radiotap_header *rh" +.Fa "int rlen" +.Fa "uint32_t rx_radiotap" +.Fc +.\" +.Ft int +.Fn ieee80211_radiotap_active_vap "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_radiotap_active "struct ieee80211com *" +.\" +.Ft void +.Fn ieee80211_radiotap_tx "struct ieee80211vap *" "struct mbuf *" +.Sh DESCRIPTION +The +.Nm net80211 +layer used by 802.11 drivers includes support for a device-independent +packet capture format called +.Nm radiotap +that is understood by tools such as +.Xr tcpdump 1 . +This facility is designed for capturing 802.11 traffic, +including information that is not part of the normal 802.11 frame structure. +.Pp +Radiotap was designed to balance the desire for a hardware-independent, +extensible capture format against the need to +conserve CPU and memory bandwidth on embedded systems. +These considerations led to a format consisting of +a standard preamble followed by an extensible bitmap indicating the +presence of optional capture fields. +A +.Nm net80211 +device driver supporting +.Vt radiotap +defines two packed structures that it shares with +.Nm net80211 . +These structures embed an instance of a +.Vt ieee80211_radiotap_header +structure at the beginning, +with subsequent fields in the appropriate order, +and macros to set the bits of the +.Va it_present +bitmap to indicate which fields exist and are filled in by the driver. +This information is then supplied through the +.Fn ieee80211_radiotap_attach +call after a successful +.Fn ieee80211_ifattach +request. +.Pp +With radiotap setup, drivers just need to fill in per-packet +capture state for frames sent/received and dispatch capture state +in the transmit path (since control is not returned to the +.Nm net80211 +layer before the packet is handed to the device). +To minimize overhead this work should be done only when one +or more processes are actively capturing data; +this is checked with one of +.Fn ieee80211_radiotap_active_vap +and +.Fn ieee80211_radiotap_active . +In the transmit path capture work looks like this: +.Bd -literal -offset indent +if (ieee80211_radiotap_active_vap(vap)) { + ... /* record transmit state */ + ieee80211_radiotap_tx(vap, m); /* capture transmit event */ +} +.Ed +.Pp +While in the receive path capture is handled in +.Nm net80211 +but state must be captured before dispatching a frame: +.Bd -literal -offset indent +if (ieee80211_radiotap_active(ic)) { + ... /* record receive state */ +} +\&... +ieee80211_input(...); /* packet capture handled in net80211 */ +.Ed +.Pp +.\" +The following fields are defined for +.Vt radiotap , +in the order in which they should appear in the buffer supplied +to +.Nm net80211 . +.Bl -tag -width indent +.It Dv IEEE80211_RADIOTAP_TSFT +This field contains the unsigned 64-bit value, in microseconds, +of the MAC's 802.11 Time Synchronization Function (TSF). +In theory, for each received frame, this value is recorded +when the first bit of the MPDU arrived at the MAC. +In practice, hardware snapshots the TSF otherwise and one cannot assume +this data is accurate without driver adjustment. +.It Dv IEEE80211_RADIOTAP_FLAGS +This field contains a single unsigned 8-bit value, containing one or +more of these bit flags: +.Bl -tag -width indent +.It Dv IEEE80211_RADIOTAP_F_CFP +Frame was sent/received during the Contention Free Period (CFP). +.It Dv IEEE80211_RADIOTAP_F_SHORTPRE +Frame was sent/received with short preamble. +.It Dv IEEE80211_RADIOTAP_F_WEP +Frame was encrypted. +.It Dv IEEE80211_RADIOTAP_F_FRAG +Frame was an 802.11 fragment. +.It Dv IEEE80211_RADIOTAP_F_FCS +Frame contents includes the FCS. +.It Dv IEEE80211_RADIOTAP_F_DATAPAD +Frame contents potentially has padding between the 802.11 header and the +data payload to align the payload to a 32-bit boundary. +.It Dv IEEE80211_RADIOTAP_F_BADFCS +Frame was received with an invalid FCS. +.It Dv IEEE80211_RADIOTAP_F_SHORTGI +Frame was sent/received with Short Guard Interval. +.El +.It Dv IEEE80211_RADIOTAP_RATE +This field contains a single unsigned 8-bit value that is the data rate. +Legacy rates are in units of 500Kbps. +MCS rates (used on 802.11n/HT channels) have the high bit set and +the MCS in the low 7 bits. +.It Dv IEEE80211_RADIOTAP_CHANNEL +This field contains two unsigned 16-bit values. +The first value is the center frequency for the channel +the frame was sent/received on. +The second value is a bitmap containing flags that specify channel properties. +.Pp +This field is deprecated in favor of +.Dv IEEE80211_RADIOTAP_XCHANNEL +but may be used to save space in the capture file for legacy devices. +.\".It Dv IEEE80211_RADIOTAP_FHSS +.\"This field contains two 8-bit values. +.\"This field should be present only for frequency-hopping radios. +.\"The first byte is the hop set. +.\"The second byte is the pattern in use. +.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL +This field contains a single signed 8-bit value that indicates the +RF signal power at the antenna, in decibels difference from 1mW. +.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE +This field contains a single signed 8-bit value that indicates the +RF noise power at the antenna, in decibels difference from 1mW. +.\".It Dv IEEE80211_RADIOTAP_LOCK_QUALITY +.\"This field contains a single unsigned 16-bit value, indicating the +.\"quality of the Barker Code lock. +.\"No unit is specified for this field. +.\"There does not appear to be a standard way of measuring this at this time; +.\"this quantity is often referred to as +.\".Dq "Signal Quality" +.\"in some datasheets. +.\".It Dv IEEE80211_RADIOTAP_TX_ATTENUATION +.\"This field contains a single unsigned 16-bit value, expressing transmit +.\"power as unitless distance from maximum power set at factory calibration. +.\"0 indicates maximum transmit power. +.\"Monotonically nondecreasing with lower power levels. +.\".It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION +.\"This field contains a single unsigned 16-bit value, expressing transmit +.\"power as decibel distance from maximum power set at factory calibration. +.\"0 indicates maximum transmit power. +.\"Monotonically nondecreasing with lower power levels. +.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER +Transmit power expressed as decibels from a 1mW reference. +This field is a single signed 8-bit value. +This is the absolute power level measured at the antenna port. +.It Dv IEEE80211_RADIOTAP_ANTENNA +This field contains a single unsigned 8-bit value that specifies +which antenna was used to transmit or receive the frame. +Antenna numbering is device-specific but typically the primary antenna has +the lowest number. +On transmit a value of zero may be seen which typically means +antenna selection is left to the device. +.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL +This field contains a single unsigned 8-bit value that indicates the +RF signal power at the antenna, in decibels difference from an +arbitrary, fixed reference. +.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE +This field contains a single unsigned 8-bit value that indicates the +RF noise power at the antenna, in decibels difference from an +arbitrary, fixed reference. +.It Dv IEEE80211_RADIOTAP_XCHANNEL +This field contains four values: a 32-bit unsigned bitmap of +flags that describe the channel attributes, a 16-bit unsigned +frequency in MHz (typically the channel center), an 8-bit +unsigned IEEE channel number, and a signed 8-bit value that +holds the maximum regulatory transmit power cap in .5 dBm +(8 bytes total). +Channel flags are defined in: +.In net80211/_ieee80211.h +(only a subset are found in +.In net80211/ieee80211_radiotap.h ). +This property supersedes +.Dv IEEE80211_RADIOTAP_CHANNEL +and is the only way to completely express all +channel attributes and the +mapping between channel frequency and IEEE channel number. +.El +.Sh EXAMPLES +Radiotap receive definitions for the Intersil Prism driver: +.Bd -literal -offset indent +#define WI_RX_RADIOTAP_PRESENT \\ + ((1 << IEEE80211_RADIOTAP_TSFT) \\ + (1 << IEEE80211_RADIOTAP_FLAGS) | \\ + (1 << IEEE80211_RADIOTAP_RATE) | \\ + (1 << IEEE80211_RADIOTAP_CHANNEL) | \\ + (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\ + (1 << IEEE80211_RADIOTAP_DB_ANTNOISE)) + +struct wi_rx_radiotap_header { + struct ieee80211_radiotap_header wr_ihdr; + uint64_t wr_tsf; + uint8_t wr_flags; + uint8_t wr_rate; + uint16_t wr_chan_freq; + uint16_t wr_chan_flags; + uint8_t wr_antsignal; + uint8_t wr_antnoise; +} __packed; +.Ed +.Pp +and transmit definitions for the Atheros driver: +.Bd -literal -offset indent +#define ATH_TX_RADIOTAP_PRESENT ( \\ + (1 << IEEE80211_RADIOTAP_TSFT) | \\ + (1 << IEEE80211_RADIOTAP_FLAGS) | \\ + (1 << IEEE80211_RADIOTAP_RATE) | \\ + (1 << IEEE80211_RADIOTAP_DBM_TX_POWER) | \\ + (1 << IEEE80211_RADIOTAP_ANTENNA) | \\ + (1 << IEEE80211_RADIOTAP_XCHANNEL) | \\ + 0) + +struct ath_tx_radiotap_header { + struct ieee80211_radiotap_header wt_ihdr; + uint64_t wt_tsf; + uint8_t wt_flags; + uint8_t wt_rate; + uint8_t wt_txpower; + uint8_t wt_antenna; + uint32_t wt_chan_flags; + uint16_t wt_chan_freq; + uint8_t wt_chan_ieee; + int8_t wt_chan_maxpow; +} __packed; +.Ed +.Sh SEE ALSO +.Xr tcpdump 1 , +.Xr bpf 4 , +.Xr ieee80211 9 +.Sh HISTORY +The +.Nm +definitions first appeared in +.Nx 1.5 . +.\" +.Sh AUTHORS +.An -nosplit +The original version of this manual page was written by +.An Bruce M. Simpson Aq Mt bms@FreeBSD.org +and +.An Darron Broad Aq Mt darron@kewl.org . Property changes on: user/imp/camdoc/ieee80211_radiotap.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/insmntque.9 =================================================================== --- user/imp/camdoc/insmntque.9 (nonexistent) +++ user/imp/camdoc/insmntque.9 (revision 296049) @@ -0,0 +1,95 @@ +.\" Copyright (C) 2008 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 September 8, 2008 +.Dt INSMNTQUE 9 +.Os +.Sh NAME +.Nm insmntque , +.Nm insmntque1 +.Nd "associate a vnode with a mount" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn insmntque "struct vnode *vp" "struct mount *mp" +.Ft int +.Fn insmntque1 "struct vnode *vp" "struct mount *mp" "void (*dtr)(struct vnode *, void *)" "void *dtr_arg" +.Sh DESCRIPTION +The +.Fn insmntque +function associates a vnode with a mount. +This includes updating +.Va v_mount +for the vnode, and inserting the vnode into the mount's vnode list. +.Pp +The mount reference count is incremented for each vnode added to the +mount, and that reference is decremented by +.Xr vgone 9 . +.Pp +The mount's interlock is held while the vnode is inserted. +For MP-safe file systems, the vnode must be exclusively locked. +.Pp +On failure, +.Fn insmntque +calls +.Xr vgone 9 +on the supplied vnode, and then drops the vnode lock and reference. +If more elaborated cleanup after +.Fn insmntque +failure is needed, the +.Fn insmntque1 +function may be used instead. +The +.Fa dtr +argument is a pointer to a function that is called on failure. +This function may perform any custom cleanup. +The vnode pointer is supplied as the first argument to +.Fa dtr . +The +.Fa dtr_arg +argument is the second, supplying any additional context needed. +.Sh RETURN VALUES +The +.Fn insmntque +function will always return 0, unless the file system is currently being unmounted +in which case it may return +.Dv EBUSY . +Also, +.Fn insmntque +may be forced to insert the vnode into the mount's vnode list +by setting the +.Va VV_FORCEINSMQ +flag in the vnode +.Va v_flag , +even if the file system is being unmounted. +.Sh SEE ALSO +.Xr vgone 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/insmntque.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/khelp.9 =================================================================== --- user/imp/camdoc/khelp.9 (nonexistent) +++ user/imp/camdoc/khelp.9 (revision 296049) @@ -0,0 +1,438 @@ +.\" +.\" Copyright (c) 2010-2011 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written at the Centre for Advanced Internet +.\" Architectures, Swinburne University of Technology, Melbourne, Australia by +.\" David Hayes and Lawrence Stewart under sponsorship from the FreeBSD +.\" Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE 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 February 15, 2011 +.Dt KHELP 9 +.Os +.Sh NAME +.Nm khelp , +.Nm khelp_init_osd , +.Nm khelp_destroy_osd , +.Nm khelp_get_id , +.Nm khelp_get_osd , +.Nm khelp_add_hhook , +.Nm khelp_remove_hhook , +.Nm KHELP_DECLARE_MOD , +.Nm KHELP_DECLARE_MOD_UMA +.Nd Kernel Helper Framework +.Sh SYNOPSIS +.In sys/khelp.h +.In sys/module_khelp.h +.Fn "int khelp_init_osd" "uint32_t classes" "struct osd *hosd" +.Fn "int khelp_destroy_osd" "struct osd *hosd" +.Fn "int32_t khelp_get_id" "char *hname" +.Fn "void * khelp_get_osd" "struct osd *hosd" "int32_t id" +.Fn "int khelp_add_hhook" "struct hookinfo *hki" "uint32_t flags" +.Fn "int khelp_remove_hhook" "struct hookinfo *hki" +.Fn KHELP_DECLARE_MOD "hname" "hdata" "hhooks" "version" +.Fn KHELP_DECLARE_MOD_UMA "hname" "hdata" "hhooks" "version" "ctor" "dtor" +.Sh DESCRIPTION +.Nm +provides a framework for managing +.Nm +modules, which indirectly use the +.Xr hhook 9 +KPI to register their hook functions with hook points of interest within the +kernel. +Khelp modules aim to provide a structured way to dynamically extend the kernel +at runtime in an ABI preserving manner. +Depending on the subsystem providing hook points, a +.Nm +module may be able to associate per-object data for maintaining relevant state +between hook calls. +The +.Xr hhook 9 +and +.Nm +frameworks are tightly integrated and anyone interested in +.Nm +should also read the +.Xr hhook 9 +manual page thoroughly. +.Ss Information for Khelp Module Implementors +.Nm +modules are represented within the +.Nm +framework by a +.Vt struct helper +which has the following members: +.Bd -literal -offset indent +struct helper { + int (*mod_init) (void); + int (*mod_destroy) (void); +#define HELPER_NAME_MAXLEN 16 + char h_name[HELPER_NAME_MAXLEN]; + uma_zone_t h_zone; + struct hookinfo *h_hooks; + uint32_t h_nhooks; + uint32_t h_classes; + int32_t h_id; + volatile uint32_t h_refcount; + uint16_t h_flags; + TAILQ_ENTRY(helper) h_next; +}; +.Ed +.Pp +Modules must instantiate a +.Vt struct helper , +but are only required to set the +.Va h_classes +field, and may optionally set the +.Va h_flags , +.Va mod_init +and +.Va mod_destroy +fields where required. +The framework takes care of all other fields and modules should refrain from +manipulating them. +Using the C99 designated initialiser feature to set fields is encouraged. +.Pp +If specified, the +.Va mod_init +function will be run by the +.Nm +framework prior to completing the registration process. +Returning a non-zero value from the +.Va mod_init +function will abort the registration process and fail to load the module. +If specified, the +.Va mod_destroy +function will be run by the +.Nm +framework during the deregistration process, after the module has been +deregistered by the +.Nm +framework. +The return value is currently ignored. +Valid +.Nm +classes are defined in +.In sys/khelp.h . +Valid flags are defined in +.In sys/module_khelp.h . +The HELPER_NEEDS_OSD flag should be set in the +.Va h_flags +field if the +.Nm +module requires persistent per-object data storage. +There is no programmatic way (yet) to check if a +.Nm +class provides the ability for +.Nm +modules to associate persistent per-object data, so a manual check is required. +.Pp +The +.Fn KHELP_DECLARE_MOD +and +.Fn KHELP_DECLARE_MOD_UMA +macros provide convenient wrappers around the +.Xr DECLARE_MODULE 9 +macro, and are used to register a +.Nm +module with the +.Nm +framework. +.Fn KHELP_DECLARE_MOD_UMA +should only be used by modules which require the use of persistent per-object +storage i.e. modules which set the HELPER_NEEDS_OSD flag in their +.Vt struct helper Ns 's +.Va h_flags +field. +.Pp +The first four arguments common to both macros are as follows. +The +.Fa hname +argument specifies the unique +.Xr ascii 7 +name for the +.Nm +module. +It should be no longer than HELPER_NAME_MAXLEN-1 characters in length. +The +.Fa hdata +argument is a pointer to the module's +.Vt struct helper . +The +.Fa hhooks +argument points to a static array of +.Vt struct hookinfo +structures. +The array should contain a +.Vt struct hookinfo +for each +.Xr hhook 9 +point the module wishes to hook, even when using the same hook function multiple +times for different +.Xr hhook 9 +points. +The +.Fa version +argument specifies a version number for the module which will be passed to +.Xr MODULE_VERSION 9 . +The +.Fn KHELP_DECLARE_MOD_UMA +macro takes the additional +.Fa ctor +and +.Fa dtor +arguments, which specify optional +.Xr uma 9 +constructor and destructor functions. +NULL should be passed where the functionality is not required. +.Pp +The +.Fn khelp_get_id +function returns the numeric identifier for the +.Nm +module with name +.Fa hname . +.Pp +The +.Fn khelp_get_osd +function is used to obtain the per-object data pointer for a specified +.Nm +module. +The +.Fa hosd +argument is a pointer to the underlying subsystem object's +.Vt struct osd . +This is provided by the +.Xr hhook 9 +framework when calling into a +.Nm +module's hook function. +The +.Fa id +argument specifies the numeric identifier for the +.Nm +module to extract the data pointer from +.Fa hosd +for. +The +.Fa id +is obtained using the +.Fn khelp_get_id +function. +.Pp +The +.Fn khelp_add_hhook +and +.Fn khelp_remove_hhook +functions allow a +.Nm +module to dynamically hook/unhook +.Xr hhook 9 +points at run time. +The +.Fa hki +argument specifies a pointer to a +.Vt struct hookinfo +which encapsulates the required information about the +.Xr hhook 9 +point and hook function being manipulated. +The HHOOK_WAITOK flag may be passed in via the +.Fa flags +argument of +.Fn khelp_add_hhook +if +.Xr malloc 9 +is allowed to sleep waiting for memory to become available. +.Ss Integrating Khelp Into a Kernel Subsystem +Most of the work required to allow +.Nm +modules to do useful things relates to defining and instantiating suitable +.Xr hhook 9 +points for +.Nm +modules to hook into. +The only additional decision a subsystem needs to make is whether it wants to +allow +.Nm +modules to associate persistent per-object data. +Providing support for persistent data storage can allow +.Nm +modules to perform more complex functionality which may be desirable. +Subsystems which want to allow Khelp modules to associate +persistent per-object data with one of the subsystem's data structures need to +make the following two key changes: +.Bl -bullet +.It +Embed a +.Vt struct osd +pointer in the structure definition for the object. +.It +Add calls to +.Fn khelp_init_osd +and +.Fn khelp_destroy_osd +to the subsystem code paths which are responsible for respectively initialising +and destroying the object. +.El +.Pp +The +.Fn khelp_init_osd +function initialises the per-object data storage for all currently loaded +.Nm +modules of appropriate classes which have set the HELPER_NEEDS_OSD flag in their +.Va h_flags +field. +The +.Fa classes +argument specifies a bitmask of +.Nm +classes which this subsystem associates with. +If a +.Nm +module matches any of the classes in the bitmask, that module will be associated +with the object. +The +.Fa hosd +argument specifies the pointer to the object's +.Vt struct osd +which will be used to provide the persistent storage for use by +.Nm +modules. +.Pp +The +.Fn khelp_destroy_osd +function frees all memory that was associated with an object's +.Vt struct osd +by a previous call to +.Fn khelp_init_osd . +The +.Fa hosd +argument specifies the pointer to the object's +.Vt struct osd +which will be purged in preparation for destruction. +.Sh IMPLEMENTATION NOTES +.Nm +modules are protected from being prematurely unloaded by a reference count. +The count is incremented each time a subsystem calls +.Fn khelp_init_osd +causing persistent storage to be allocated for the module, and decremented for +each corresponding call to +.Fn khelp_destroy_osd . +Only when a module's reference count has dropped to zero can the module be +unloaded. +.Sh RETURN VALUES +The +.Fn khelp_init_osd +function returns zero if no errors occurred. +It returns ENOMEM if a +.Nm +module which requires per-object storage fails to allocate the necessary memory. +.Pp +The +.Fn khelp_destroy_osd +function only returns zero to indicate that no errors occurred. +.Pp +The +.Fn khelp_get_id +function returns the unique numeric identifier for the registered +.Nm +module with name +.Fa hname . +It return -1 if no module with the specified name is currently registered. +.Pp +The +.Fn khelp_get_osd +function returns the pointer to the +.Nm +module's persistent object storage memory. +If the module identified by +.Fa id +does not have persistent object storage registered with the object's +.Fa hosd +.Vt struct osd , +NULL is returned. +.Pp +The +.Fn khelp_add_hhook +function returns zero if no errors occurred. +It returns ENOENT if it could not find the requested +.Xr hhook 9 +point. +It returns ENOMEM if +.Xr malloc 9 +failed to allocate memory. +It returns EEXIST if attempting to register the same hook function more than +once for the same +.Xr hhook 9 +point. +.Pp +The +.Fn khelp_remove_hhook +function returns zero if no errors occurred. +It returns ENOENT if it could not find the requested +.Xr hhook 9 +point. +.Sh EXAMPLES +A well commented example Khelp module can be found at: +.Pa /usr/share/examples/kld/khelp/h_example.c +.Pp +The Enhanced Round Trip Time (ERTT) +.Xr h_ertt 4 +.Nm +module provides a more complex example of what is possible. +.Sh SEE ALSO +.Xr h_ertt 4 , +.Xr hhook 9 , +.Xr osd 9 +.Sh ACKNOWLEDGEMENTS +Development and testing of this software were made possible in part by grants +from the FreeBSD Foundation and Cisco University Research Program Fund at +Community Foundation Silicon Valley. +.Sh HISTORY +The +.Nm +kernel helper framework first appeared in +.Fx 9.0 . +.Pp +The +.Nm +framework was first released in 2010 by Lawrence Stewart whilst studying at +Swinburne University of Technology's Centre for Advanced Internet Architectures, +Melbourne, Australia. +More details are available at: +.Pp +http://caia.swin.edu.au/urp/newtcp/ +.Sh AUTHORS +.An -nosplit +The +.Nm +framework was written by +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . +.Pp +This manual page was written by +.An David Hayes Aq Mt david.hayes@ieee.org +and +.An Lawrence Stewart Aq Mt lstewart@FreeBSD.org . Property changes on: user/imp/camdoc/khelp.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/mbchain.9 =================================================================== --- user/imp/camdoc/mbchain.9 (nonexistent) +++ user/imp/camdoc/mbchain.9 (revision 296049) @@ -0,0 +1,222 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Boris Popov +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 20, 2001 +.Dt MBCHAIN 9 +.Os +.Sh NAME +.Nm mbchain , +.Nm mb_init , +.Nm mb_initm , +.Nm mb_done , +.Nm mb_detach , +.Nm mb_fixhdr , +.Nm mb_reserve , +.Nm mb_put_uint8 , +.Nm mb_put_uint16be , +.Nm mb_put_uint16le , +.Nm mb_put_uint32be , +.Nm mb_put_uint32le , +.Nm mb_put_int64be , +.Nm mb_put_int64le , +.Nm mb_put_mem , +.Nm mb_put_mbuf , +.Nm mb_put_uio +.Nd "set of functions to build an mbuf chain from various data types" +.Sh SYNOPSIS +.Cd options LIBMCHAIN +.Li kldload libmchain +.Pp +.In sys/param.h +.In sys/uio.h +.In sys/mchain.h +.Ft int +.Fn mb_init "struct mbchain *mbp" +.Ft void +.Fn mb_initm "struct mbchain *mbp" "struct mbuf *m" +.Ft void +.Fn mb_done "struct mbchain *mbp" +.Ft struct mbuf * +.Fn mb_detach "struct mbchain *mbp" +.Ft int +.Fn mb_fixhdr "struct mbchain *mbp" +.Ft caddr_t +.Fn mb_reserve "struct mbchain *mbp" "int size" +.Ft int +.Fn mb_put_uint8 "struct mbchain *mbp" "uint8_t x" +.Ft int +.Fn mb_put_uint16be "struct mbchain *mbp" "uint16_t x" +.Ft int +.Fn mb_put_uint16le "struct mbchain *mbp" "uint16_t x" +.Ft int +.Fn mb_put_uint32be "struct mbchain *mbp" "uint32_t x" +.Ft int +.Fn mb_put_uint32le "struct mbchain *mbp" "uint32_t x" +.Ft int +.Fn mb_put_int64be "struct mbchain *mbp" "int64_t x" +.Ft int +.Fn mb_put_int64le "struct mbchain *mbp" "int64_t x" +.Ft int +.Fn mb_put_mem "struct mbchain *mbp" "c_caddr_t source" "int size" "int type" +.Ft int +.Fn mb_put_mbuf "struct mbchain *mbp" "struct mbuf *m" +.Ft int +.Fn mb_put_uio "struct mbchain *mbp" "struct uio *uiop" "int size" +.Sh DESCRIPTION +These functions are used to compose mbuf chains from various data types. +The +.Vt mbchain +structure is used as a working context and should be initialized with a call +to either +.Fn mb_init +or +.Fn mb_initm . +It has the following fields: +.Bl -tag -width ".Va mb_count" +.It Va "mb_top" +.Pq Vt "struct mbuf *" +A pointer to the top of constructed mbuf chain. +.It Va mb_cur +.Pq Vt "struct mbuf *" +A pointer to the currently filled mbuf. +.It Va mb_mleft +.Pq Vt int +Number of bytes left in the current mbuf. +.It Va mb_count +.Pq Vt int +Total number of bytes placed in the mbuf chain. +.It Va mb_copy +.Pq Vt "mb_copy_t *" +User-defined function to perform a copy into mbuf; +useful if any unusual +data conversion is necessary. +.It Va mb_udata +.Pq Vt "void *" +User-supplied data which can be used in the +.Va mb_copy +function. +.El +.Pp +.Fn mb_done +function disposes an mbuf chain pointed to by +.Fa mbp->mb_top +field and sets +the field to +.Dv NULL . +.Pp +.Fn mb_detach +function returns the value of +.Fa mbp->mb_top +field and sets its value to +.Dv NULL . +.Pp +.Fn mb_fixhdr +recalculates the length of an mbuf chain and updates the +.Va m_pkthdr.len +field of the first mbuf in the chain. +It returns the calculated length. +.Pp +.Fn mb_reserve +ensures that the object of the length specified by the +.Fa size +argument will fit in the current mbuf (mbuf allocation is performed if +necessary), and advances all pointers as if the real data was placed. +Returned +value will point to the beginning of the reserved space. +Note that the size +of the object should not exceed +.Dv MLEN +bytes. +.Pp +All +.Fn mb_put_* +functions perform an actual copy of the data into mbuf chain. +Functions which have +.Cm le +or +.Cm be +suffixes will perform conversion to the little\- or big\-endian data formats. +.Pp +.Fn mb_put_mem +function copies +.Fa size +bytes of data specified by the +.Fa source +argument to an mbuf chain. +The +.Fa type +argument specifies the method used to perform a copy, +and can be one of the following: +.Bl -tag -width ".Dv MB_MINLINE" +.It Dv MB_MSYSTEM +Use +.Fn bcopy +function. +.It Dv MB_MUSER +Use +.Xr copyin 9 +function. +.It Dv MB_MINLINE +Use an +.Dq inline +loop which does not call any function. +.It Dv MB_MZERO +Do not copy any data, but just fill the destination with zero bytes. +.It Dv MB_MCUSTOM +Call function specified by the +.Fa mbp->mb_copy +field. +.El +.Sh RETURN VALUES +All +.Ft int +functions except +.Fn mb_fixhdr +return zero if successful and an error code otherwise. +.Pp +.Em Note : +after failure of any function, an mbuf chain is left in the broken state, +and only +.Fn mb_done +function can safely be called to destroy it. +.Sh EXAMPLES +.Bd -literal +struct mbchain *mbp; +struct mbuf *m; + +mb_init(mbp); +mb_put_uint8(mbp, 33); +mb_put_uint16le(mbp, length); +m = m_copym(mbp->mb_top, 0, M_COPYALL, M_WAIT); +send(m); +mb_done(mbp); +.Ed +.Sh SEE ALSO +.Xr mbuf 9 , +.Xr mdchain 9 +.Sh AUTHORS +This manual page was written by +.An Boris Popov Aq Mt bp@FreeBSD.org . Property changes on: user/imp/camdoc/mbchain.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mbpool.9 =================================================================== --- user/imp/camdoc/mbpool.9 (nonexistent) +++ user/imp/camdoc/mbpool.9 (revision 296049) @@ -0,0 +1,264 @@ +.\" Copyright (c) 2003 +.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). +.\" 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. +.\" +.\" Author: Hartmut Brandt +.\" +.\" $FreeBSD$ +.\" +.Dd July 15, 2003 +.Dt MBPOOL 9 +.Os +.Sh NAME +.Nm mbpool +.Nd "buffer pools for network interfaces" +.Sh SYNOPSIS +.In sys/types.h +.In machine/bus.h +.In sys/mbpool.h +.Vt struct mbpool ; +.Ft int +.Fo mbp_create +.Fa "struct mbpool **mbp" "const char *name" "bus_dma_tag_t dmat" +.Fa "u_int max_pages" "size_t page_size" "size_t chunk_size" +.Fc +.Ft void +.Fn mbp_destroy "struct mbpool *mbp" +.Ft "void *" +.Fn mbp_alloc "struct mbpool *mbp" "bus_addr_t *pa" "uint32_t *hp" +.Ft void +.Fn mbp_free "struct mbpool *mbp" "void *p" +.Ft void +.Fn mbp_ext_free "void *" "void *" +.Ft void +.Fn mbp_card_free "struct mbpool *mbp" +.Ft void +.Fn mbp_count "struct mbpool *mbp" "u_int *used" "u_int *card" "u_int *free" +.Ft "void *" +.Fn mbp_get "struct mbpool *mbp" "uint32_t h" +.Ft "void *" +.Fn mbp_get_keep "struct mbpool *mbp" "uint32_t h" +.Ft void +.Fo mbp_sync +.Fa "struct mbpool *mbp" "uint32_t h" "bus_addr_t off" "bus_size_t len" +.Fa "u_int op" +.Fc +.Pp +.Fn MODULE_DEPEND "your_module" "libmbpool" 1 1 1 +.Pp +.Cd "options LIBMBPOOL" +.Sh DESCRIPTION +Mbuf pools are intended to help drivers for interface cards that need huge +amounts of receive buffers, and additionally provides a mapping between these +buffers and 32-bit handles. +.Pp +An example of these cards are the Fore/Marconi ForeRunnerHE cards. +These +employ up to 8 receive groups, each with two buffer pools, each of which +can contain up to 8192. +This gives a total maximum number of more than +100000 buffers. +Even with a more moderate configuration the card eats several +thousand buffers. +Each of these buffers must be mapped for DMA. +While for +machines without an IOMMU and with lesser than 4GByte memory this is not +a problem, for other machines this may quickly eat up all available IOMMU +address space and/or bounce buffers. +On sparc64, the default I/O page size +is 16k, so mapping a simple mbuf wastes 31/32 of the address space. +.Pp +Another problem with most of these cards is that they support putting a 32-bit +handle into the buffer descriptor together with the physical address. +This handle is reflected back to the driver when the buffer is filled, and +assists the driver in finding the buffer in host memory. +For 32-bit machines, +the virtual address of the buffer is usually used as the handle. +This does not +work for 64-bit machines for obvious reasons, so a mapping is needed between +these handles and the buffers. +This mapping should be possible without +searching lists and the like. +.Pp +An mbuf pool overcomes both problems by allocating DMA-able memory page wise +with a per-pool configurable page size. +Each page is divided into a number of +equally-sized chunks, the last +.Dv MBPOOL_TRAILER_SIZE +of which are used by the pool code (4 bytes). +The rest of each chunk is +usable as a buffer. +There is a per-pool limit on pages that will be allocated. +.Pp +Additionally, the code manages two flags for each buffer: +.Dq on-card +and +.Dq used . +A buffer may be in one of three states: +.Bl -tag -width "on-card" +.It free +None of the flags is set. +.It on-card +Both flags are set. +The buffer is assumed to be handed over to the card and +waiting to be filled. +.It used +The buffer was returned by the card and is now travelling through the system. +.El +.Pp +A pool is created with +.Fn mbp_create . +This call specifies a DMA tag +.Fa dmat +to be used to create and map the memory pages via +.Xr bus_dmamem_alloc 9 . +The +.Fa chunk_size +includes the pool overhead. +It means that to get buffers for 5 ATM cells +(240 bytes), a chunk size of 256 should be specified. +This results in 12 unused +bytes between the buffer, and the pool overhead of four byte. +The total +maximum number of buffers in a pool is +.Fa max_pages +* +.Fa ( page_size +/ +.Fa chunk_size ) . +The maximum value for +.Fa max_pages +is 2^14-1 (16383) and the maximum of +.Fa page_size +/ +.Fa chunk_size +is 2^9 (512). +If the call is successful, a pointer to a newly allocated +.Vt "struct mbpool" +is set into the variable pointed to by +.Fa mpb . +.Pp +A pool is destroyed with +.Fn mbp_destroy . +This frees all pages and the pool structure itself. +If compiled with +.Dv DIAGNOSTICS , +the code checks that all buffers are free. +If not, a warning message is issued +to the console. +.Pp +A buffer is allocated with +.Fn mbp_alloc . +This returns the virtual address of the buffer and stores the physical +address into the variable pointed to by +.Fa pa . +The handle is stored into the variable pointed to by +.Fa hp . +The two most significant bits and the 7 least significant bits of the handle +are unused by the pool code and may be used by the caller. +These are +automatically stripped when passing a handle to one of the other functions. +If a buffer cannot be allocated (either because the maximum number of pages +is reached, no memory is available or the memory cannot be mapped), +.Dv NULL +is returned. +If a buffer could be allocated, it is in the +.Dq on-card +state. +.Pp +When the buffer is returned by the card, the driver calls +.Fn mbp_get +with the handle. +This function returns the virtual address of the buffer +and clears the +.Dq on-card +bit. +The buffer is now in the +.Dq used +state. +The function +.Fn mbp_get_keep +differs from +.Fn mbp_get +in that it does not clear the +.Dq on-card +bit. +This can be used for buffers +that are returned +.Dq partially +by the card. +.Pp +A buffer is freed by calling +.Fn mbp_free +with the virtual address of the buffer. +This clears the +.Dq used +bit, and +puts the buffer on the free list of the pool. +Note that free buffers +are NOT returned to the system. +The function +.Fn mbp_ext_free +can be given to +.Fn m_extadd +as the free function. +The user argument must be the pointer to +the pool. +.Pp +Before using the contents of a buffer returned by the card, the driver +must call +.Fn mbp_sync +with the appropriate parameters. +This results in a call to +.Xr bus_dmamap_sync 9 +for the buffer. +.Pp +All buffers in the pool that are currently in the +.Dq on-card +state can be freed +with a call to +.Fn mbp_card_free . +This may be called by the driver when it stops the interface. +Buffers in the +.Dq used +state are not freed by this call. +.Pp +For debugging it is possible to call +.Fn mbp_count . +This returns the number of buffers in the +.Dq used +and +.Dq on-card +states and +the number of buffers on the free list. +.Sh SEE ALSO +.Xr mbuf 9 +.Sh AUTHORS +.An Harti Brandt Aq Mt harti@FreeBSD.org +.Sh CAVEATS +The function +.Fn mbp_sync +is currently a no-op because +.Xr bus_dmamap_sync 9 +is missing the offset and length parameters. Property changes on: user/imp/camdoc/mbpool.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mbuf_tags.9 =================================================================== --- user/imp/camdoc/mbuf_tags.9 (nonexistent) +++ user/imp/camdoc/mbuf_tags.9 (revision 296049) @@ -0,0 +1,286 @@ +.\" $OpenBSD: mbuf_tags.9,v 1.18 2003/12/08 07:07:35 mcbride Exp $ +.\" +.\" The authors of this manual page are Angelos D. Keromytis +.\" (angelos@cis.upenn.edu), Gleb Smirnoff , and +.\" Robert Watson +.\" +.\" Copyright (c) 2004 Robert N. M. Watson +.\" Copyright (c) 2001 Angelos D. Keromytis +.\" +.\" Permission to use, copy, and modify this software with or without +.\" fee is hereby granted, provided that this entire notice is included +.\" in all source code copies of any software which is or includes a copy +.\" or modification of this software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 12, 2008 +.Dt MBUF_TAGS 9 +.Os +.Sh NAME +.Nm mbuf_tags +.Nd a framework for generic packet attributes +.Sh SYNOPSIS +.In sys/mbuf.h +.Ft "struct m_tag *" +.Fn m_tag_alloc "uint32_t cookie" "int type" "int len" "int wait" +.Ft "struct m_tag *" +.Fn m_tag_copy "struct m_tag *t" "int how" +.Ft int +.Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from" "int how" +.Ft void +.Fn m_tag_delete "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_delete_nonpersistent "struct mbuf *m" +.Ft "struct m_tag *" +.Fn m_tag_find "struct mbuf *m" "int type" "struct m_tag *start" +.Ft "struct m_tag *" +.Fn m_tag_first "struct mbuf *m" +.Ft void +.Fn m_tag_free "struct m_tag *t" +.Ft "struct m_tag *" +.Fn m_tag_get "int type" "int len" "int wait" +.Ft void +.Fn m_tag_init "struct mbuf *m" +.Ft struct m_tag * +.Fn m_tag_locate "struct mbuf *m" "uint32_t cookie" "int type" "struct m_tag *t" +.Ft "struct m_tag *" +.Fn m_tag_next "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t" +.Ft void +.Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t" +.Sh DESCRIPTION +Mbuf tags allow additional meta-data to be associated with in-flight packets +by providing a mechanism for the tagging of additional kernel memory onto +packet header mbufs. +Tags are maintained in chains off of the +.Xr mbuf 9 +header, and maintained using a series of API calls to allocate, search, and +delete tags. +Tags are identified using an ID and cookie that uniquely identify a class +of data tagged onto the packet, and may contain an arbitrary amount of +additional storage. +Typical uses of mbuf tags include Mandatory Access Control (MAC) labels as +described in +.Xr mac 9 , +IPsec policy information as described in +.Xr ipsec 4 , +and packet filter tags used by +.Xr pf 4 . +.Pp +Tags will be maintained across a variety of operations, including the copying +of packet headers using facilities such as +.Fn M_COPY_PKTHDR +and +.Fn M_MOVE_PKTHDR . +Any tags associated with an mbuf header will be automatically freed when the +mbuf is freed, although some subsystems will wish to delete the tags prior +to that time. +.Pp +Packet tags are used by different kernel APIs +to keep track of operations done or +scheduled to happen to packets. +Each packet tag can be distinguished by its type and cookie. +The cookie is used to identify a specific module or API. +The packet tags are attached to mbuf packet headers. +.Pp +The first +.Fn sizeof "struct m_tag" +bytes of a tag contain a +.Vt "struct m_tag" : +.Bd -literal +struct m_tag { + SLIST_ENTRY(m_tag) m_tag_link; /* List of packet tags */ + uint16_t m_tag_id; /* Tag ID */ + uint16_t m_tag_len; /* Length of data */ + uint32_t m_tag_cookie; /* ABI/Module ID */ + void (*m_tag_free)(struct m_tag *); +}; +.Ed +.Pp +The +.Va m_tag_link +field is used to link tags together (see +.Xr queue 3 +for more details). +The +.Va m_tag_id , m_tag_len +and +.Va m_tag_cookie +fields are set to type, length, +and +cookie, respectively. +.Va m_tag_free +points to +.Fn m_tag_free_default . +Following this structure are +.Va m_tag_len +bytes of space that can be used to store tag-specific information. +Addressing this data region may be tricky. +A safe way is embedding +.Vt "struct m_tag" +into a private data structure, as follows: +.Bd -literal -offset indent +struct foo { + struct m_tag tag; + ... +}; +struct foo *p = (struct foo *)m_tag_alloc(...); +struct m_tag *mtag = &p->tag; +.Ed +.Pp +Note that +.Ox +does not support cookies, it needs +.Va m_tag_id +to be globally unique. +To keep compatibility with +.Ox , +a cookie +.Dv MTAG_ABI_COMPAT +is provided along with some compatibility functions. +When writing an +.Ox +compatible code, one should be careful not to take already +used tag type. +Tag types are defined in +.In sys/mbuf.h . +.Ss Packet Tag Manipulation Functions +.Bl -ohang -offset indent +.It Fn m_tag_alloc cookie type len wait +Allocate a new tag of type +.Fa type +and cookie +.Fa cookie +with +.Va len +bytes of space following the tag header itself. +The +.Fa wait +argument is passed directly to +.Xr malloc 9 . +If successful, +.Fn m_tag_alloc +returns a memory buffer of +.Pq Va len No + Fn sizeof "struct m_tag" +bytes. +Otherwise, +.Dv NULL +is returned. +A compatibility function +.Fn m_tag_get +is also provided. +.It Fn m_tag_copy tag how +Allocate a copy of +.Fa tag . +The +.Fa how +argument is passed directly to +.Fn m_tag_alloc . +The return values are the same as in +.Fn m_tag_alloc . +.It Fn m_tag_copy_chain tombuf frommbuf how +Allocate and copy all tags from mbuf +.Fa frommbuf +to mbuf +.Fa tombuf . +Returns 1 on success, and 0 on failure. +In the latter case, mbuf +.Fa tombuf +loses all its tags, even previously present. +.It Fn m_tag_delete mbuf tag +Remove +.Fa tag +from +.Fa mbuf Ns 's +list and free it. +.It Fn m_tag_delete_chain mbuf tag +Remove and free a packet tag chain, starting from +.Fa tag . +If +.Fa tag +is +.Dv NULL , +all tags are deleted. +.It Fn m_tag_delete_nonpersistent mbuf +Traverse +.Fa mbuf Ns 's +tags and delete those which do not have the +.Dv MTAG_PERSISTENT +flag set. +.It Fn m_tag_first mbuf +Return the first tag associated with +.Fa mbuf . +.It Fn m_tag_free tag +Free +.Fa tag +using its +.Va m_tag_free +method. +The +.Fn m_tag_free_default +function +is used by default. +.It Fn m_tag_init mbuf +Initialize the tag storage for packet +.Fa mbuf . +.It Fn m_tag_locate mbuf cookie type tag +Search for a tag defined by +.Fa type +and +.Fa cookie +in +.Fa mbuf , +starting from position specified by +.Fa tag . +If the latter is +.Dv NULL , +then search through the whole list. +Upon success, a pointer to the first found tag is returned. +In either case, +.Dv NULL +is returned. +A compatibility function +.Fn m_tag_find +is also provided. +.It Fn m_tag_next mbuf tag +Return tag next to +.Fa tag +in +.Fa mbuf . +If absent, +.Dv NULL +is returned. +.It Fn m_tag_prepend mbuf tag +Add the new tag +.Fa tag +at the head of the tag list for packet +.Fa mbuf . +.It Fn m_tag_unlink mbuf tag +Remove tag +.Fa tag +from the list of tags of packet +.Fa mbuf . +.El +.Sh CODE REFERENCES +The tag-manipulating code is contained in the file +.Pa sys/kern/uipc_mbuf2.c . +Inlined functions are defined in +.In sys/mbuf.h . +.Sh SEE ALSO +.Xr queue 3 , +.Xr mbuf 9 +.Sh HISTORY +The packet tags first appeared in +.Ox 2.9 +and were written by +.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . Property changes on: user/imp/camdoc/mbuf_tags.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mdchain.9 =================================================================== --- user/imp/camdoc/mdchain.9 (nonexistent) +++ user/imp/camdoc/mdchain.9 (revision 296049) @@ -0,0 +1,211 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 Boris Popov +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 28, 2001 +.Dt MDCHAIN 9 +.Os +.Sh NAME +.Nm mdchain , +.Nm md_initm , +.Nm md_done , +.Nm md_append_record , +.Nm md_next_record , +.Nm md_get_uint8 , +.Nm md_get_uint16 , +.Nm md_get_uint16be , +.Nm md_get_uint16le , +.Nm md_get_uint32 , +.Nm md_get_uint32be , +.Nm md_get_uint32le , +.Nm md_get_int64 , +.Nm md_get_int64be , +.Nm md_get_int64le , +.Nm md_get_mem , +.Nm md_get_mbuf , +.Nm md_get_uio +.Nd "set of functions to dissect an mbuf chain to various data types" +.Sh SYNOPSIS +.Cd options LIBMCHAIN +.Li kldload libmchain +.Pp +.In sys/param.h +.In sys/uio.h +.In sys/mchain.h +.Ft void +.Fn md_initm "struct mdchain *mdp" "struct mbuf *m" +.Ft void +.Fn md_done "struct mdchain *mdp" +.Ft void +.Fn md_append_record "struct mdchain *mdp" "struct mbuf *top" +.Ft int +.Fn md_next_record "struct mdchain *mdp" +.Ft int +.Fn md_get_uint8 "struct mdchain *mdp" "uint8_t *x" +.Ft int +.Fn md_get_uint16 "struct mdchain *mdp" "uint16_t *x" +.Ft int +.Fn md_get_uint16be "struct mdchain *mdp" "uint16_t *x" +.Ft int +.Fn md_get_uint16le "struct mdchain *mdp" "uint16_t *x" +.Ft int +.Fn md_get_uint32 "struct mdchain *mdp" "uint32_t *x" +.Ft int +.Fn md_get_uint32be "struct mdchain *mdp" "uint32_t *x" +.Ft int +.Fn md_get_uint32le "struct mdchain *mdp" "uint32_t *x" +.Ft int +.Fn md_get_int64 "struct mdchain *mdp" "int64_t *x" +.Ft int +.Fn md_get_int64be "struct mdchain *mdp" "int64_t *x" +.Ft int +.Fn md_get_int64le "struct mdchain *mdp" "int64_t *x" +.Ft int +.Fn md_get_mem "struct mdchain *mdp" "caddr_t target" "int size" "int type" +.Ft int +.Fn md_get_mbuf "struct mdchain *mdp" "int size" "struct mbuf **m" +.Ft int +.Fn md_get_uio "struct mdchain *mdp" "struct uio *uiop" "int size" +.Sh DESCRIPTION +These functions are used to decompose mbuf chains to various data types. +The +.Vt mdchain +structure is used as a working context +and should be initialized through a call of the +.Fn mb_initm +function. +It has the following fields: +.Bl -tag -width "md_top" +.It Va "md_top" +.Pq Vt "struct mbuf *" +A pointer to the top of the parsed mbuf chain. +.It Va md_cur +.Pq Vt "struct mbuf *" +A pointer to the currently parsed mbuf. +.It Va md_pas +.Pq Vt int +Offset in the current mbuf. +.El +.Pp +The +.Fn md_done +function disposes of an mbuf chain pointed to by the +.Fa mdp->md_top +field and sets the field to +.Dv NULL . +.Pp +The +.Fn md_append_record +appends a new mbuf chain using +.Va m_nextpkt +field to form a single linked list of mbuf chains. +If the +.Fa mdp->md_top +field is +.Dv NULL , +then this function behaves exactly as the +.Fn md_initm +function. +.Pp +The +.Fn md_next_record +function extracts the next mbuf chain and disposes the current one, if any. +For a new mbuf chain it calls the +.Fn md_initm +function. +If there is no data left the function returns +.Er ENOENT . +.Pp +All +.Fn md_get_* +functions perform an actual copy of the data from an mbuf chain. +Functions which have +.Cm le +or +.Cm be +suffixes will perform conversion to the little\- or big\-endian data formats. +.Pp +.Fn md_get_mem +function copies +.Fa size +bytes of data specified by the +.Fa source +argument from an mbuf chain. +The +.Fa type +argument specifies the method used to perform a copy, +and can be one of the following: +.Bl -tag -width ".Dv MB_MINLINE" +.It Dv MB_MSYSTEM +Use the +.Fn bcopy +function. +.It Dv MB_MUSER +Use the +.Xr copyin 9 +function. +.It Dv MB_MINLINE +Use an +.Dq inline +loop which does not call any function. +.El +.Pp +If +.Fa target +is +.Dv NULL , +an actual copy is not performed +and the function just skips the given number of bytes. +.Sh RETURN VALUES +All +.Ft int +functions return zero if successful, +otherwise an error code is returned. +.Pp +.Em Note : +after failure of any function, +an mbuf chain is left in the broken state and only the +.Fn md_done +function can safely be called to destroy it. +.Sh EXAMPLES +.Bd -literal +struct mdchain *mdp; +struct mbuf *m; +uint16_t length; +uint8_t byte; + +receive(so, &m); +md_initm(mdp, m); +if (md_get_uint8(mdp, &byte) != 0 || + md_get_uint16le(mdp, &length) != 0) + error = EBADRPC; +mb_done(mdp); +.Ed +.Sh SEE ALSO +.Xr mbchain 9 , +.Xr mbuf 9 +.Sh AUTHORS +This manual page was written by +.An Boris Popov Aq Mt bp@FreeBSD.org . Property changes on: user/imp/camdoc/mdchain.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/memguard.9 =================================================================== --- user/imp/camdoc/memguard.9 (nonexistent) +++ user/imp/camdoc/memguard.9 (revision 296049) @@ -0,0 +1,220 @@ +.\" Copyright (c) 2005 Christian Brueffer +.\" 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 21, 2014 +.Dt MEMGUARD 9 +.Os +.Sh NAME +.Nm MemGuard +.Nd "memory allocator for debugging purposes" +.Sh SYNOPSIS +.Cd "options DEBUG_MEMGUARD" +.Sh DESCRIPTION +.Nm +is a simple and small replacement memory allocator designed +to help detect tamper-after-free scenarios. +These problems are more and more common and likely with +multithreaded kernels where race conditions are more prevalent. +.Pp +.Nm +can take over +.Fn malloc , +.Fn realloc +and +.Fn free +for a single malloc type. +Alternatively +.Nm +can take over +.Fn uma_zalloc , +.Fn uma_zalloc_arg +and +.Fn uma_free +for a single +.Xr uma +zone. +Also +.Nm +can guard all allocations larger than +.Dv PAGE_SIZE , +and can guard a random fraction of all allocations. +There is also a knob to prevent allocations smaller than a specified +size from being guarded, to limit memory waste. +.Sh EXAMPLES +To use +.Nm +for a memory type, either add an entry to +.Pa /boot/loader.conf : +.Bd -literal -offset indent +vm.memguard.desc= +.Ed +.Pp +Or set the +.Va vm.memguard.desc +.Xr sysctl 8 +variable at run-time: +.Bd -literal -offset indent +sysctl vm.memguard.desc= +.Ed +.Pp +Where +.Ar memory_type +can be either a short description of the memory type to monitor, +either name of +.Xr uma 9 +zone. +Only allocations from that +.Ar memory_type +made after +.Va vm.memguard.desc +is set will potentially be guarded. +If +.Va vm.memguard.desc +is modified at run-time then only allocations of the new +.Ar memory_type +will potentially be guarded once the +.Xr sysctl 8 +is set. +Existing guarded allocations will still be properly released by +either +.Xr free 9 +or +.Xr uma_zfree 9 , +depending on what kind of allocation was taken over. +.Pp +To determine short description of a +.Xr malloc 9 +type one can either take it from the first column of +.Xr vmstat 8 Fl m +output, or to find it in the kernel source. +It is the second argument to +.Xr MALLOC_DEFINE 9 +macro. +To determine name of +.Xr uma 9 +zone one can either take it from the first column of +.Xr vmstat 8 Fl z +output, or to find it in the kernel source. +It is the first argument to the +.Xr uma_zcreate 9 +function. +.Pp +The +.Va vm.memguard.divisor +boot-time tunable is used to scale how much of the system's physical +memory +.Nm +is allowed to consume. +The default is 10, so up to +.Va vm_cnt.v_page_count Ns /10 +pages can be used. +.Nm +will reserve +.Va vm_kmem_max +/ +.Va vm.memguard.divisor +bytes of virtual address space, limited by twice the physical memory +size. +The physical limit is reported as +.Va vm.memguard.phys_limit +and the virtual space reserved for +.Nm +is reported as +.Va vm.memguard.mapsize . +.Pp +.Nm +will not do page promotions for any allocation smaller than +.Va vm.memguard.minsize +bytes. +The default is 0, meaning all allocations can potentially be guarded. +.Nm +can guard sufficiently large allocations randomly, with average +frequency of every one in 100000 / +.Va vm.memguard.frequency +allocations. +The default is 0, meaning no allocations are randomly guarded. +.Pp +.Nm +can optionally add unmapped guard pages around each allocation to +detect overflow and underflow, if +.Va vm.memguard.options +has the 1 bit set. +This option is enabled by default. +.Nm +will optionally guard all allocations of +.Dv PAGE_SIZE +or larger if +.Va vm.memguard.options +has the 2 bit set. +This option is off by default. +By default +.Nm +doesn't guard those +.Xr uma 9 +zones that have been initialized with the +.Dv UMA_ZONE_NOFREE +flag set, since it can produce false positives on them. +However, this safety measure can be turned off by setting bit 3 +of the +.Va vm.memguard.options +tunable. +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr vmstat 8 , +.Xr contigmalloc 9 , +.Xr malloc 9 , +.Xr redzone 9 , +.Xr uma 9 +.Sh HISTORY +.Nm +first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +.Nm +was originally written by +.An Bosko Milekic Aq Mt bmilekic@FreeBSD.org . +This manual page was originally written by +.An Christian Brueffer Aq Mt brueffer@FreeBSD.org . +Additions have been made by +.An Matthew Fleming Aq Mt mdf@FreeBSD.org +and +.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org +to both the implementation and the documentation. +.Sh BUGS +It is not possible to guard allocations that really expect themselves to be +allocated from +.Xr uma 9 , +utilizing additional interfaces apart from +.Fn uma_zalloc +and +.Fn uma_free , +for example +.Fn uma_find_refcnt . +For the moment of writing only +.Xr mbuf 9 +cluster zones belong to that kind of allocations. +Attempt to guard them would lead to kernel panic. Property changes on: user/imp/camdoc/memguard.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/microtime.9 =================================================================== --- user/imp/camdoc/microtime.9 (nonexistent) +++ user/imp/camdoc/microtime.9 (revision 296049) @@ -0,0 +1,121 @@ +.\" Copyright (c) 2000 Kelly Yancey +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 16, 2004 +.Dt MICROTIME 9 +.Os +.Sh NAME +.Nm bintime , +.Nm getbintime , +.Nm microtime , +.Nm getmicrotime , +.Nm nanotime , +.Nm getnanotime +.Nd get the current time +.Sh SYNOPSIS +.In sys/time.h +.Ft void +.Fn bintime "struct bintime *bt" +.Ft void +.Fn getbintime "struct bintime *bt" +.Ft void +.Fn microtime "struct timeval *tv" +.Ft void +.Fn getmicrotime "struct timeval *tv" +.Ft void +.Fn nanotime "struct timespec *ts" +.Ft void +.Fn getnanotime "struct timespec *tsp" +.Sh DESCRIPTION +The +.Fn bintime +and +.Fn getbintime +functions store the system time as a +.Vt "struct bintime" +at the addresses specified by +.Fa bt . +The +.Fn microtime +and +.Fn getmicrotime +functions perform the same utility, but record the time as a +.Vt "struct timeval" +instead. +Similarly the +.Fn nanotime +and +.Fn getnanotime +functions store the time as a +.Vt "struct timespec" . +.Pp +The +.Fn bintime , +.Fn microtime , +and +.Fn nanotime +functions +always query the timecounter to return the current time as precisely as +possible. +Whereas +.Fn getbintime , +.Fn getmicrotime , +and +.Fn getnanotime +functions are abstractions which return a less precise, but +faster to obtain, time. +.Pp +The intent of the +.Fn getbintime , +.Fn getmicrotime , +and +.Fn getnanotime +functions is to enforce the user's preference for timer accuracy versus +execution time. +.Sh SEE ALSO +.Xr binuptime 9 , +.Xr getbinuptime 9 , +.Xr getmicrouptime 9 , +.Xr getnanouptime 9 , +.Xr microuptime 9 , +.Xr nanouptime 9 , +.Xr tvtohz 9 +.Sh HISTORY +The +.Nm bintime +functions first appeared in +.Fx 5.0 . +The +.Nm microtime +and +.Nm nanotime +functions first appeared in +.Fx 3.0 +but have existed in other incarnations since +.Bx 4.4 . +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . Property changes on: user/imp/camdoc/microtime.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/module.9 =================================================================== --- user/imp/camdoc/module.9 (nonexistent) +++ user/imp/camdoc/module.9 (revision 296049) @@ -0,0 +1,121 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Alexander Langer +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 19, 2007 +.Dt MODULE 9 +.Os +.Sh NAME +.Nm module +.Nd structure describing a kernel module +.Sh DESCRIPTION +Each module in the kernel is described by a +.Vt module_t +structure. +The structure contains the name of the device, a unique ID number, +a pointer to an event handler function and to an argument, +which is given to the event handler, +as well as some kernel internal data. +.Pp +The +.Xr DECLARE_MODULE 9 +macro +registers the module with the system. +.Pp +When the module is loaded, the event handler function is called with +the +.Fa what +argument set to +.Dv MOD_LOAD . +.Pp +On unload it is first called with +.Fa what +set to +.Dv MOD_QUIESCE . +If the unload was not forced, a non-zero return will prevent the +unload from happening. +.Pp +If the unload continues +.Fa what +is set to +.Dv MOD_UNLOAD . +If the module returns non-zero to this, the unload will not happen. +.Pp +The difference between +.Dv MOD_QUIESCE +and +.Dv MOD_UNLOAD +is that the module should fail +.Dv MOD_QUIESCE +if it is currently in use, whereas +.Dv MOD_UNLOAD +should only fail if it is impossible to unload the module, for instance +because there are memory references to the module which cannot be revoked. +.Pp +When the system is shutting down, +.Fa what +contains the value of +.Dv MOD_SHUTDOWN . +.Pp +The module should return +.Er EOPNOTSUPP +for unsupported and unrecognized values of +.Fa what . +.Sh EXAMPLES +.Bd -literal +#include +#include +#include + +static int foo_handler(module_t mod, int /*modeventtype_t*/ what, + void *arg); + +static moduledata_t mod_data= { + "foo", + foo_handler, + NULL +}; + +MODULE_VERSION(foo, 1); +MODULE_DEPEND(foo, bar, 1, 3, 4); + +DECLARE_MODULE(foo, mod_data, SI_SUB_EXEC, SI_ORDER_ANY); +.Ed +.Sh SEE ALSO +.Xr DECLARE_MODULE 9 , +.Xr DEV_MODULE 9 , +.Xr DRIVER_MODULE 9 , +.Xr MODULE_DEPEND 9 , +.Xr MODULE_VERSION 9 , +.Xr SYSCALL_MODULE 9 +.Pp +.Pa /usr/share/examples/kld +.Sh AUTHORS +This manual page was written by +.An Alexander Langer Aq Mt alex@FreeBSD.org . Property changes on: user/imp/camdoc/module.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/osd.9 =================================================================== --- user/imp/camdoc/osd.9 (nonexistent) +++ user/imp/camdoc/osd.9 (revision 296049) @@ -0,0 +1,390 @@ +.\" +.\" 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 January 5, 2011 +.Dt OSD 9 +.Os +.Sh NAME +.Nm osd , +.Nm osd_register , +.Nm osd_deregister , +.Nm osd_set , +.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_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_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 +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 +returns zero on success or ENOMEM if the specified type/slot identifier pair +triggered an internal +.Xr realloc 9 +which failed. +.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_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 . Property changes on: user/imp/camdoc/osd.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/pbuf.9 =================================================================== --- user/imp/camdoc/pbuf.9 (nonexistent) +++ user/imp/camdoc/pbuf.9 (revision 296049) @@ -0,0 +1,132 @@ +.\" +.\" Copyright (C) 2001 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 July 9, 2001 +.Dt PBUF 9 +.Os +.Sh NAME +.Nm pbuf , +.Nm getpbuf , +.Nm trypbuf , +.Nm relpbuf +.Nd "functions for managing physical buffers" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/bio.h +.In sys/buf.h +.Ft "struct buf *" +.Fn getpbuf "int *pfreecnt" +.Ft "struct buf *" +.Fn trypbuf "int *pfreecnt" +.Ft void +.Fn relpbuf "struct buf *bp" "int *pfreecnt" +.Sh DESCRIPTION +These functions are used to allocate and release physical buffers. +.Pp +The physical buffers are allocated at system startup and are +maintained in a separate pool from the main system buffers. +They are intended for use by subsystems that cannot or should not be +reliant on the main pool of buffers (for example the swap pager). +The system allocates between 16 and 256 physical buffers depending +on the amount of memory in the system. +.Pp +Each subsystem that allocates buffers via these calls is expected +to manage its own percentage free counter. +If the value is initialized to \-1 the number of buffers available +to the subsystem is limited only by the number of physical buffers +available. +The number of buffers is stored in +.Va nswbuf +which is defined in +.In sys/buf.h +and initialized in +.Fn cpu_startup . +A recommended initialization value is 1/2 +.Va nswbuf . +.Pp +The +.Fn getpbuf +function returns the first available buffer to the user. +If there are no buffers available, +.Fn getpbuf +will sleep waiting for one to become available. +If +.Fa pfreecnt +is zero, +.Fn getpbuf +will sleep until it increases. +.Fa pfreecnt +is decremented prior to returning. +.Pp +The +.Fn trypbuf +function returns the first available buffer. +If there are no buffers available, +.Dv NULL +is returned. +As well, if +.Fa pfreecnt +is zero, +.Dv NULL +is returned. +.Fa pfreecnt +is decremented prior to returning a valid buffer. +If +.Dv NULL +is returned, +.Fa pfreecnt +is not modified. +.Pp +The +.Fn relpbuf +function releases the buffer back to the free list. +If the buffers +.Va b_rcred +or +.Va b_wcred +structures are not +.Dv NULL , +they are freed. +See +.Xr crfree 9 . +.Pp +.Fa pfreecnt +is incremented prior to returning. +.Sh RETURN VALUES +.Fn getpbuf +and +.Fn trypbuf +return a pointer to the buffer. +In the case of +.Fn trypbuf , +.Dv NULL +can also be returned indicating that there are no buffers available. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/pbuf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pfind.9 =================================================================== --- user/imp/camdoc/pfind.9 (nonexistent) +++ user/imp/camdoc/pfind.9 (revision 296049) @@ -0,0 +1,88 @@ +.\" Copyright (c) 2001 Evan Sarmiento. +.\" 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 11, 2001 +.Dt PFIND 9 +.Os +.Sh NAME +.Nm pfind , zpfind +.Nd locate a process by number +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft "struct proc *" +.Fn pfind "pid_t pid" +.Ft "struct proc *" +.Fn zpfind "pid_t pid" +.Sh DESCRIPTION +.Fn pfind +takes a +.Fa pid +as its argument and returns a pointer to the +.Vt proc +structure whose PID is specified in the argument only if the +.Fa pid +is on the +.Va allproc +list. +.Pp +.Fn zpfind +takes a +.Fa pid +as its argument. +If +.Fn zpfind +finds a process whose PID is equal to that of argument +and is a zombie process, meaning that it must reside on the +.Va zombproc +list, +.Fn zpfind +returns a pointer to that +.Vt proc +structure. +.Pp +Both +.Fn pfind +and +.Fn zpfind +lock the +.Vt proc +structure that is returned using +.Fn PROC_LOCK "p" . +.Sh RETURN VALUES +.Fn pfind +and +.Fn zpfind +return a pointer to a +.Vt proc +structure on success and a +.Dv NULL +on failure. +.Sh SEE ALSO +.Xr pgfind 9 +.Sh AUTHORS +This manual page was written by +.An Evan Sarmiento Aq Mt kaworu@sektor7.ath.cx . Property changes on: user/imp/camdoc/pfind.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pgfind.9 =================================================================== --- user/imp/camdoc/pgfind.9 (nonexistent) +++ user/imp/camdoc/pgfind.9 (revision 296049) @@ -0,0 +1,65 @@ +.\" Copyright (c) 2001 Evan Sarmiento. +.\" 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 8, 2001 +.Dt PGFIND 9 +.Os +.Sh NAME +.Nm pgfind +.Nd "locate a process group by number" +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft "struct pgrp *" +.Fn pgfind "pid_t pgid" +.Sh DESCRIPTION +The +.Fn pgfind +function takes a +.Fa pgid +as its argument and returns a pointer to the +.Vt pgrp +structure whose +.Va pg_id +is specified in the argument. +.Pp +.Fn pgfind +locks the +.Vt pgrp +structure that is returned. +.Sh RETURN VALUES +The +.Fn pgfind +function returns +.Dv NULL +on failure or a pointer to a +.Vt pgrp +structure on successful completion. +.Sh SEE ALSO +.Xr pfind 9 +.Sh AUTHORS +This manual page was written by +.An Evan Sarmiento Aq Mt kaworu@sektor7.ath.cx . Property changes on: user/imp/camdoc/pgfind.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_activate.9 =================================================================== --- user/imp/camdoc/pmap_activate.9 (nonexistent) +++ user/imp/camdoc/pmap_activate.9 (revision 296049) @@ -0,0 +1,51 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_ACTIVATE 9 +.Os +.Sh NAME +.Nm pmap_activate +.Nd activate a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_activate "struct thread *td" +.Sh DESCRIPTION +The +.Fn pmap_activate +function activates the physical map for a user thread +.Fa td . +This function must be called before the thread's address space may be +accessed. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_activate.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_copy.9 =================================================================== --- user/imp/camdoc/pmap_copy.9 (nonexistent) +++ user/imp/camdoc/pmap_copy.9 (revision 296049) @@ -0,0 +1,84 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_COPY 9 +.Os +.Sh NAME +.Nm pmap_copy , +.Nm pmap_copy_page +.Nd copy physical memory pages +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_copy +.Fa "pmap_t dst_pmap" "pmap_t src_pmap" "vm_offset_t dst_addr" +.Fa "vm_size_t len" "vm_offset_t src_addr" +.Fc +.Ft void +.Fn pmap_copy_page "vm_page_t src" "vm_page_t dst" +.Sh DESCRIPTION +The +.Fn pmap_copy +function copies the range specified by +.Fa src_addr +and +.Fa len +from the source physical map +.Fa src_pmap +to the destination physical map +.Fa dst_pmap +at the address +.Fa dst_addr . +.Pp +The +.Fn pmap_copy_page +function +copies the physical page +.Fa src +to the physical page +.Fa dst , +by mapping the page into kernel virtual address space (KVA), and using +.Fn bcopy +to copy the page. +.Sh IMPLEMENTATION NOTES +The +.Fn pmap_copy +routine is only advisory and need not do anything. +Actually implementing it may seriously reduce system performance. +.Pp +The +.Fn pmap_copy_page +routine only operates upon a single page. +.Sh SEE ALSO +.Xr bcopy 3 , +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_copy.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_extract.9 =================================================================== --- user/imp/camdoc/pmap_extract.9 (nonexistent) +++ user/imp/camdoc/pmap_extract.9 (revision 296049) @@ -0,0 +1,95 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_EXTRACT 9 +.Os +.Sh NAME +.Nm pmap_extract , +.Nm pmap_extract_and_hold +.Nd map a virtual address to a physical page +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft vm_paddr_t +.Fn pmap_extract "pmap_t pmap" "vm_offset_t va" +.Ft vm_paddr_t +.Fn pmap_extract_and_hold "pmap_t pmap" "vm_offset_t va" "vm_prot_t prot" +.Sh DESCRIPTION +The +.Fn pmap_extract +function maps a virtual address to a physical page. +In certain situations, callers may use +.Fn pmap_extract_and_hold +instead, to ensure that the returned page is held. +.Pp +The +.Fn pmap_extract_and_hold +function maps a virtual address to a physical page, and atomically holds +the returned page for use by the caller, only if the mapping permits +the given page protection. +.Sh IMPLEMENTATION NOTES +Currently, the page protection requested by the caller is not verified. +.Sh RETURN VALUES +The +.Fn pmap_extract +function will return the physical page address associated with the +virtual address +.Fa va +inside the physical map +.Fa pmap . +If the mapping does not exist, or if the +.Fa pmap +parameter is +.Dv NULL , +then +.Dv NULL +will be returned. +.Pp +The +.Fn pmap_extract_and_hold +function will return the physical page address associated with the +virtual address +.Fa va +inside the physical map +.Fa pmap . +If the mapping does not exist, the result is a no-op, and +.Dv NULL +will +be returned. +.Sh SEE ALSO +.Xr mutex 9 , +.Xr pmap 9 +.Sh AUTHORS +.An -nosplit +The +.Fn pmap_extract_and_hold +function was implemented by +.An Alan L. Cox Aq Mt alc@imimic.com . +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_extract.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_growkernel.9 =================================================================== --- user/imp/camdoc/pmap_growkernel.9 (nonexistent) +++ user/imp/camdoc/pmap_growkernel.9 (revision 296049) @@ -0,0 +1,51 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_GROWKERNEL 9 +.Os +.Sh NAME +.Nm pmap_growkernel +.Nd grow the kernel virtual address (KVA) space +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_growkernel "vm_offset_t addr" +.Sh DESCRIPTION +The +.Fn pmap_growkernel +function grows the kernel virtual address space to the virtual address +.Fa addr . +.Pp +It will allocate more page entries if required. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_growkernel.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_init.9 =================================================================== --- user/imp/camdoc/pmap_init.9 (nonexistent) +++ user/imp/camdoc/pmap_init.9 (revision 296049) @@ -0,0 +1,65 @@ +.\" +.\" 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 June 10, 2005 +.Dt PMAP_INIT 9 +.Os +.Sh NAME +.Nm pmap_init , +.Nm pmap_init2 +.Nd initialize the pmap subsystem +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_init "void" +.Ft void +.Fn pmap_init2 "void" +.Sh DESCRIPTION +The +.Fn pmap_init +function initializes the +.Xr pmap 9 +sub-system. +It is called during system initialization by +.Fn vm_init , +to initialize any structures that the +.Nm +system needs in order to map between physical and virtual memory. +.Pp +The +.Fn pmap_init2 +function initializes a zone for the PV entries. +These are used to implement page sharing at the physical level. +A high water mark is set so that the system can recover from +excessive numbers of PV entries. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_init.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_is_prefaultable.9 =================================================================== --- user/imp/camdoc/pmap_is_prefaultable.9 (nonexistent) +++ user/imp/camdoc/pmap_is_prefaultable.9 (revision 296049) @@ -0,0 +1,57 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_IS_PREFAULTABLE 9 +.Os +.Sh NAME +.Nm pmap_is_prefaultable +.Nd determine if a page may be prefaulted +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft boolean_t +.Fn pmap_is_prefaultable "pmap_t pmap" "vm_offset_t va" +.Sh DESCRIPTION +The +.Fn pmap_is_prefaultable +function provides a means of determining if the page residing at +virtual address +.Fa va +in the physical map +.Fa pmap +may be pre-faulted into main memory. +.Pp +This is a helper function which is called by +.Xr vm_fault_prefault 9 . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_fault_prefault 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_is_prefaultable.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_map.9 =================================================================== --- user/imp/camdoc/pmap_map.9 (nonexistent) +++ user/imp/camdoc/pmap_map.9 (revision 296049) @@ -0,0 +1,80 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_MAP 9 +.Os +.Sh NAME +.Nm pmap_map +.Nd map a physical memory range into kernel virtual address (KVA) space +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft vm_offset_t +.Fo pmap_map +.Fa "vm_offset_t *virt" "vm_paddr_t start" "vm_paddr_t end" "int prot" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_map +function maps a range of physical addresses into kernel virtual address (KVA) +space, from +.Fa start +to +.Fa end , +with protection bits +.Fa prot . +.Pp +The value passed in +.Fa *virt +is treated as a hint for the virtual address of the beginning of the mapping. +.Sh IMPLEMENTATION NOTES +The +.Fa prot +argument is currently ignored by machine-dependent implementations. +.Pp +Architectures which can support a direct mapped physical to virtual +region can return the appropriate address within that region, leaving +.Fa *virt +unchanged. +.Sh RETURN VALUES +The +.Fn pmap_map +function returns the virtual address of the beginning of the mapping, if +the mapping was successfully made; +.Fa *virt +will also be updated with the first usable address after the mapped region. +.Pp +If the function is unsuccessful, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_map.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_mincore.9 =================================================================== --- user/imp/camdoc/pmap_mincore.9 (nonexistent) +++ user/imp/camdoc/pmap_mincore.9 (revision 296049) @@ -0,0 +1,74 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_MINCORE 9 +.Os +.Sh NAME +.Nm pmap_mincore +.Nd determine if a virtual address is resident in physical memory +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft int +.Fn pmap_mincore "pmap_t pmap" "vm_offset_t addr" +.Sh DESCRIPTION +The +.Fn pmap_mincore +function determines if the page at the virtual address +.Fa addr +in the physical map +.Fa pmap +is resident in physical memory. +It is the machine-dependent interface used by the +.Xr mincore 2 +system call. +.Sh RETURN VALUES +If the page is resident in physical memory, +a mask of flags is returned, +whose meaning is documented in +.Xr mincore 2 ; +otherwise, +0 +is returned. +.Pp +The +.Fa pmap +must exist and +.Fa addr +must be mapped into the +.Fa pmap . +If any error occurs, the machine-dependent implementation should +return +0. +.Sh SEE ALSO +.Xr mincore 2 , +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_mincore.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_object_init_pt.9 =================================================================== --- user/imp/camdoc/pmap_object_init_pt.9 (nonexistent) +++ user/imp/camdoc/pmap_object_init_pt.9 (revision 296049) @@ -0,0 +1,73 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_OBJECT_INIT_PT 9 +.Os +.Sh NAME +.Nm pmap_object_init_pt +.Nd initialize page tables for a VM object +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fo pmap_object_init_pt +.Fa "pmap_t pmap" "vm_offset_t addr" "vm_object_t object" +.Fa "vm_pindex_t pindex" "vm_size_t size" "int limit" +.Fc +.Sh DESCRIPTION +The +.Fn pmap_object_init_pt +function preloads the page table entries into the specified physical map +.Fa pmap , +for the given +.Fa object +at the virtual address +.Fa addr , +for +.Fa size +bytes, beginning at the page index +.Fa pindex +within the object. +The map bits +.Fa limit +are heeded when creating the mapping. +.Sh IMPLEMENTATION NOTES +This function is not strictly required by an architecture's +.Xr pmap 9 +implementation, but it does provide performance benefits if implemented. +.Pp +It is intended to eliminate the blast of soft faults on process +startup, and immediately following a call to +.Xr mmap 2 . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_object_init_pt.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_page_exists_quick.9 =================================================================== --- user/imp/camdoc/pmap_page_exists_quick.9 (nonexistent) +++ user/imp/camdoc/pmap_page_exists_quick.9 (revision 296049) @@ -0,0 +1,66 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_PAGE_EXISTS_QUICK 9 +.Os +.Sh NAME +.Nm pmap_page_exists_quick +.Nd determine if a page exists in a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft boolean_t +.Fn pmap_page_exists_quick "pmap_t pmap" "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_page_exists_quick +function is used to quickly determine if the page +.Fa m +exists in the physical map +.Fa pmap . +It is typically called from the VM paging code. +.Sh IMPLEMENTATION NOTES +The PV count used above may be changed upwards or downwards in future; +it is only necessary that +.Dv TRUE +be returned for a small subset of pmaps for proper page aging. +.Sh RETURN VALUES +The +.Fn pmap_page_exists_quick +returns +.Dv TRUE +only if the PV entry for the physical map +.Fa pmap +is one of the first 16 PVs linked from the page +.Fa m . +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_page_exists_quick.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_page_init.9 =================================================================== --- user/imp/camdoc/pmap_page_init.9 (nonexistent) +++ user/imp/camdoc/pmap_page_init.9 (revision 296049) @@ -0,0 +1,51 @@ +.\" +.\" Copyright (c) 2005 Hiten Pandya +.\" 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 10, 2005 +.Dt PMAP_PAGE_INIT 9 +.Os +.Sh NAME +.Nm pmap_page_init +.Nd initialize machine-dependent fields of a VM page +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_page_init "vm_page_t m" +.Sh DESCRIPTION +The +.Fn pmap_page_init +function initializes the machine-dependent fields of a VM page structure. +This procedure is normally used when adding new pages to the VM page +queue management lists. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_pinit 9 +.Sh AUTHORS +This manual page was written by +.An Hiten Pandya Aq Mt hmp@FreeBSD.org . Property changes on: user/imp/camdoc/pmap_page_init.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_pinit.9 =================================================================== --- user/imp/camdoc/pmap_pinit.9 (nonexistent) +++ user/imp/camdoc/pmap_pinit.9 (revision 296049) @@ -0,0 +1,67 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_PINIT 9 +.Os +.Sh NAME +.Nm pmap_pinit , +.Nm pmap_pinit0 +.Nd initialize pmap structures +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_pinit "pmap_t pmap" +.Ft void +.Fn pmap_pinit0 "pmap_t pm" +.Sh DESCRIPTION +The +.Fn pmap_pinit +function initializes the preallocated and zeroed structure +.Fa pmap , +such as one in a +.Vt vmspace +structure. +.Pp +The +.Fn pmap_pinit0 +function initializes the physical map +.Fa pm , +associated with process 0, the first process created in the system. +.Sh IMPLEMENTATION NOTES +The +.Fn pmap_pinit2 +function has been deprecated, and should be implemented as a stub +until further notice. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_growkernel 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_pinit.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_qenter.9 =================================================================== --- user/imp/camdoc/pmap_qenter.9 (nonexistent) +++ user/imp/camdoc/pmap_qenter.9 (revision 296049) @@ -0,0 +1,79 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_QENTER 9 +.Os +.Sh NAME +.Nm pmap_qenter , +.Nm pmap_qremove +.Nd manage temporary kernel space mappings +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_qenter "vm_offset_t sva" "vm_page_t *m" "int count" +.Ft void +.Fn pmap_qremove "vm_offset_t sva" "int count" +.Sh DESCRIPTION +The +.Fn pmap_qenter +function accepts a linear array of +.Fa count +pointers to wired pages +.Fa *m , +and enters each of these pages into the kernel virtual address (KVA) space, +beginning at the address +.Fa sva . +.Pp +The +.Fn pmap_qremove +function tears out a mapping from the kernel virtual address space, +beginning at +.Fa sva +and for +.Fa count +pages. +.Sh IMPLEMENTATION NOTES +The +.Fn pmap_qenter +function is intended for temporary mappings that do not require page +modification or reference counting. +Old mappings are simply overwritten. +The pages +.Em must +be wired into physical memory. +.Pp +The corresponding +.Fn pmap_qremove +function is intended to remove such temporary mappings. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_qenter.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_release.9 =================================================================== --- user/imp/camdoc/pmap_release.9 (nonexistent) +++ user/imp/camdoc/pmap_release.9 (revision 296049) @@ -0,0 +1,58 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_RELEASE 9 +.Os +.Sh NAME +.Nm pmap_release +.Nd release resources held by a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_release "pmap_t pmap" +.Sh DESCRIPTION +The +.Fn pmap_release +function releases any resources held by the physical map +.Fa pmap . +This function is +called when a pmap initialized by the corresponding function, +.Fn pmap_pinit +is being released. +.Sh IMPLEMENTATION NOTES +This function should only be called if +.Fa pmap +no longer contains any valid mappings. +.Sh SEE ALSO +.Xr pmap 9 , +.Xr pmap_pinit 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_release.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_remove.9 =================================================================== --- user/imp/camdoc/pmap_remove.9 (nonexistent) +++ user/imp/camdoc/pmap_remove.9 (revision 296049) @@ -0,0 +1,84 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_REMOVE 9 +.Os +.Sh NAME +.Nm pmap_remove , +.Nm pmap_remove_all , +.Nm pmap_remove_pages +.Nd remove pages from a physical map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn pmap_remove "pmap_t pmap" "vm_offset_t sva" "vm_offset_t eva" +.Ft void +.Fn pmap_remove_all "vm_page_t m" +.Ft void +.Fn pmap_remove_pages "pmap_t pmap" +.Sh DESCRIPTION +The +.Fn pmap_remove +function removes the range of addresses between +.Fa sva +and +.Fa eva +from the physical map +.Fa pmap . +If +.Fa eva +is less than +.Fa sva , +then the result is undefined. +It is assumed that both +.Fa sva +and +.Fa eva +are page-aligned addresses. +.Pp +The +.Fn pmap_remove_all +removes the physical page +.Fa m +from all physical maps in which it resides, and reflects back the modify +bits to the appropriate pager. +.Pp +The +.Fn pmap_remove_pages +function removes all user pages from the physical map +.Fa pmap . +This function is called when a process exits to run down its address space +more quickly than would be the case for calling +.Fn pmap_remove . +.Sh SEE ALSO +.Fn pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_remove.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_resident_count.9 =================================================================== --- user/imp/camdoc/pmap_resident_count.9 (nonexistent) +++ user/imp/camdoc/pmap_resident_count.9 (revision 296049) @@ -0,0 +1,74 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_RESIDENT_COUNT 9 +.Os +.Sh NAME +.Nm pmap_resident_count , +.Nm pmap_wired_count +.Nd return page resident and wiring statistics +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft long +.Fn pmap_resident_count "pmap_t pmap" +.Ft long +.Fn pmap_wired_count "pmap_t pmap" +.Sh DESCRIPTION +The +.Fn pmap_resident_count +and +.Fn pmap_wired_count +macros allow +.Nm pmap +consumers to retrieve statistics from the +.Va pm_stats +member of the machine-dependent structure +.Vt struct pmap . +.Sh IMPLEMENTATION NOTES +Both functions are defined as in-line macros. +The members which they access have type +.Vt long . +.Sh RETURN VALUES +The +.Fn pmap_resident_count +returns the number of pages in the physical map +.Va pmap +which are currently resident in main memory. +.Pp +The +.Fn pmap_wired_count +returns the number of pages in the physical map +.Va pmap +which are currently wired into in main memory. +.Sh SEE ALSO +.Xr pmap 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/pmap_resident_count.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pmap_zero_page.9 =================================================================== --- user/imp/camdoc/pmap_zero_page.9 (nonexistent) +++ user/imp/camdoc/pmap_zero_page.9 (revision 296049) @@ -0,0 +1,72 @@ +.\" +.\" 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 July 21, 2003 +.Dt PMAP_ZERO 9 +.Os +.Sh NAME +.Nm pmap_zero_page , +.Nm pmap_zero_area , +.Nm pmap_zero_idle +.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" +.Ft void +.Fn pmap_zero_page_idle "vm_page_t m" +.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 +The +.Fn pmap_zero_page_idle +interface is used by the +.Nm vm_pagezero +process. +The system-wide +.Va Giant +lock should not be required to be held in order to call this interface. +.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 . Property changes on: user/imp/camdoc/pmap_zero_page.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pseudofs.9 =================================================================== --- user/imp/camdoc/pseudofs.9 (nonexistent) +++ user/imp/camdoc/pseudofs.9 (revision 296049) @@ -0,0 +1,70 @@ +.\"- +.\" 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 April 20, 2007 +.Dt PSEUDOFS 9 +.Os +.Sh NAME +.Nm pseudofs +.Nd pseudo file system construction kit +.Sh SYNOPSIS +.In fs/pseudofs/pseudofs.h +.\" Insert usage example here +.Sh DESCRIPTION +The +.Nm +module offers an abstract API for pseudo-file systems such as +.Xr procfs 5 +and +.Xr linprocfs 5 . +It takes care of all the hairy bits like interfacing with the VFS +system, enforcing access control, keeping track of file numbers, and +cloning files and directories that are process-specific. +The consumer module, i.e., the module that implements the actual guts +of the file system, needs only provide the directory structure +(represented by a collection of structures declared and initialized by +macros provided by +.Nm ) +and callbacks that report file attributes or write the actual file +contents into sbufs. +.\" Insert more info here +.Sh SEE ALSO +.Xr linprocfs 5 , +.Xr linsysfs 5 , +.Xr procfs 5 , +.Xr sbuf 9 , +.Xr vnode 9 +.Sh HISTORY +The +.Nm +module appeared in +.Fx 5.0 . +.Sh AUTHORS +The +.Nm +module and this manual page were written by +.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . Property changes on: user/imp/camdoc/pseudofs.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/redzone.9 =================================================================== --- user/imp/camdoc/redzone.9 (nonexistent) +++ user/imp/camdoc/redzone.9 (revision 296049) @@ -0,0 +1,125 @@ +.\" Copyright (c) 2006 Pawel Jakub Dawidek +.\" 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 AUTHORS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 9, 2009 +.Dt REDZONE 9 +.Os +.Sh NAME +.Nm RedZone +.Nd "buffer corruptions detector" +.Sh SYNOPSIS +.Cd "options KDB" +.Cd "options DDB" +.Cd "options DEBUG_REDZONE" +.Sh DESCRIPTION +.Nm +detects buffer underflow and buffer overflow bugs at runtime. +Currently +.Nm +only detects buffer corruptions for memory allocated with +.Xr malloc 9 . +When such corruption is detected two backtraces are printed on the console. +The first one shows from where memory was allocated, the second one shows from +where memory was freed. +By default the system will not panic when buffer corruption is detected. +This can be changed by setting the +.Va vm.redzone.panic +.Xr sysctl 8 +variable to 1. +The amount of extra memory allocated for +.Nm Ns 's +needs is stored in the +.Va vm.redzone.extra_mem +.Xr sysctl 8 +variable. +.Sh EXAMPLE +The example below shows the logs from the detection of a buffer underflow and a +buffer overflow. +.Bd -literal -offset indent +REDZONE: Buffer underflow detected. 2 bytes corrupted before 0xc8688580 (16 bytes allocated). +Allocation backtrace: +#0 0xc0583e4e at redzone_setup+0x3c +#1 0xc04a23fa at malloc+0x19e +#2 0xcdeb69ca at redzone_modevent+0x60 +#3 0xc04a3f3c at module_register_init+0x82 +#4 0xc049d96a at linker_file_sysinit+0x8e +#5 0xc049dc7c at linker_load_file+0xed +#6 0xc04a041f at linker_load_module+0xc4 +#7 0xc049e883 at kldload+0x116 +#8 0xc05d9b3d at syscall+0x325 +#9 0xc05c944f at Xint0x80_syscall+0x1f +Free backtrace: +#0 0xc0583f92 at redzone_check+0xd4 +#1 0xc04a2422 at free+0x1c +#2 0xcdeb69a6 at redzone_modevent+0x3c +#3 0xc04a438d at module_unload+0x61 +#4 0xc049e0b3 at linker_file_unload+0x89 +#5 0xc049e979 at kern_kldunload+0x96 +#6 0xc049ea00 at kldunloadf+0x2c +#7 0xc05d9b3d at syscall+0x325 +#8 0xc05c944f at Xint0x80_syscall+0x1f + +REDZONE: Buffer overflow detected. 4 bytes corrupted after 0xc8688590 (16 bytes allocated). +Allocation backtrace: +#0 0xc0583e4e at redzone_setup+0x3c +#1 0xc04a23fa at malloc+0x19e +#2 0xcdeb69ca at redzone_modevent+0x60 +#3 0xc04a3f3c at module_register_init+0x82 +#4 0xc049d96a at linker_file_sysinit+0x8e +#5 0xc049dc7c at linker_load_file+0xed +#6 0xc04a041f at linker_load_module+0xc4 +#7 0xc049e883 at kldload+0x116 +#8 0xc05d9b3d at syscall+0x325 +#9 0xc05c944f at Xint0x80_syscall+0x1f +Free backtrace: +#0 0xc0584020 at redzone_check+0x162 +#1 0xc04a2422 at free+0x1c +#2 0xcdeb69a6 at redzone_modevent+0x3c +#3 0xc04a438d at module_unload+0x61 +#4 0xc049e0b3 at linker_file_unload+0x89 +#5 0xc049e979 at kern_kldunload+0x96 +#6 0xc049ea00 at kldunloadf+0x2c +#7 0xc05d9b3d at syscall+0x325 +#8 0xc05c944f at Xint0x80_syscall+0x1f +.Ed +.Sh SEE ALSO +.Xr sysctl 8 , +.Xr malloc 9 , +.Xr memguard 9 +.Sh HISTORY +.Nm +first appeared in +.Fx 7.0 . +.Sh AUTHORS +.An Pawel Jakub Dawidek Aq Mt pjd@FreeBSD.org +.Sh BUGS +Currently, +.Nm +does not cooperate with +.Xr memguard 9 . +Allocations from a memory type controlled by +.Xr memguard 9 +are simply skipped, so buffer corruptions will not be detected there. Property changes on: user/imp/camdoc/redzone.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/resource_int_value.9 =================================================================== --- user/imp/camdoc/resource_int_value.9 (nonexistent) +++ user/imp/camdoc/resource_int_value.9 (revision 296049) @@ -0,0 +1,79 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2001 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 1, 2001 +.Dt RESOURCE_INT_VALUE 9 +.Os +.Sh NAME +.Nm resource_int_value , resource_long_value , resource_string_value +.Nd get a value from the hints mechanism +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn resource_int_value "const char *name" "int unit" "const char *resname" "int *result" +.Ft int +.Fn resource_long_value "const char *name" "int unit" "const char *resname" "long *result" +.Ft int +.Fn resource_string_value "const char *name" "int unit" "const char *resname" "const char **result" +.Sh DESCRIPTION +These functions fetch a value from the +.Dq hints +mechanism. +.Pp +The functions take the following arguments: +.Bl -tag -width "resname" +.It Fa name +The name of the device to get the resource value from. +.It Fa unit +The unit number of the device. +\-1 is special and is used for wildcard entries. +.It Fa resname +The resource name. +.It Fa result +A pointer to memory in which to store the resource value. +.El +.Sh RETURN VALUES +If successful, the functions return 0. +Otherwise, a non\-zero error code is returned. +.Sh ERRORS +The functions will fail if: +.Bl -tag -width Er +.It Bq Er ENOENT +The resource could not be found. +.It Bq Er EFTYPE +Inappropriate resource type. +.El +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh Aq Mt imp@FreeBSD.org . Property changes on: user/imp/camdoc/resource_int_value.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/selrecord.9 =================================================================== --- user/imp/camdoc/selrecord.9 (nonexistent) +++ user/imp/camdoc/selrecord.9 (revision 296049) @@ -0,0 +1,126 @@ +.\" +.\" 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 August 25, 2011 +.Dt SELRECORD 9 +.Os +.Sh NAME +.Nm seldrain , +.Nm selrecord , +.Nm selwakeup +.Nd "record and wakeup select requests" +.Sh SYNOPSIS +.In sys/param.h +.In sys/selinfo.h +.Ft void +.Fn seldrain "struct selinfo *sip" +.Ft void +.Fn selrecord "struct thread *td" "struct selinfo *sip" +.Ft void +.Fn selwakeup "struct selinfo *sip" +.Sh DESCRIPTION +.Fn seldrain , +.Fn selrecord +and +.Fn selwakeup +are the three central functions used by +.Xr select 2 , +.Xr poll 2 +and the objects that are being selected on. +They handle the task of recording which threads are waiting on which objects +and the waking of the proper threads when an event of interest occurs on an +object. +.Pp +.Fn selrecord +records that the calling thread is interested in events related to a given +object. +If another thread is already waiting on the object a collision will be flagged +in +.Fa sip +which will be later dealt with by +.Fn selwakeup . +.Pp +.Fn selrecord +acquires and releases +.Va sellock . +.Pp +.Fn selwakeup +is called by the underlying object handling code in order to notify any waiting +threads that an event of interest has occurred. +If a collision has occurred, +.Fn selwakeup +will increment +.Va nselcoll , +and broadcast on the global cv in order to wake all waiting threads so that +they can handle it. +If the thread waiting on the object is not currently sleeping or the wait +channel is not +.Va selwait , +.Fn selwakeup +will clear the +.Dv TDF_SELECT +flag which should be noted by +.Xr select 2 +and +.Xr poll 2 +when they wake up. +.Pp +.Fn seldrain +will flush the waiters queue on a specified object before its +destruction. +The object handling code must ensure that +.Fa *sip +cannot be used once +.Fn seldrain +has been called. +.Pp +The contents of +.Fa *sip +must be zeroed, such as by softc initialization, before any call to +.Fn selrecord +or +.Fn selwakeup , +otherwise a panic may occur. +.Fn selwakeup +acquires and releases +.Va sellock +and may acquire and release +.Va sched_lock . +.Fn seldrain +could usually be just a wrapper for +.Fn selwakeup , +but consumers should not generally rely on this feature. +.Sh SEE ALSO +.Xr poll 2 , +.Xr select 2 +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org +and +.An Alfred Perlstein Aq Mt alfred@FreeBSD.org . Property changes on: user/imp/camdoc/selrecord.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/signal.9 =================================================================== --- user/imp/camdoc/signal.9 (nonexistent) +++ user/imp/camdoc/signal.9 (revision 296049) @@ -0,0 +1,438 @@ +.\" +.\" 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 June 8, 2013 +.Dt SIGNAL 9 +.Os +.Sh NAME +.Nm signal , +.Nm SIGADDSET , +.Nm SIGDELSET , +.Nm SETEMPTYSET , +.Nm SIGFILLSET , +.Nm SIGISMEMBER , +.Nm SIGISEMPTY , +.Nm SIGNOTEMPTY , +.Nm SIGSETEQ , +.Nm SIGSETNEQ , +.Nm SIGSETOR , +.Nm SIGSETAND , +.Nm SIGSETNAND , +.Nm SIGSETCANTMASK , +.Nm SIG_STOPSIGMASK , +.Nm SIG_CONTSIGMASK , +.Nm SIGPENDING , +.Nm cursig , +.Nm execsigs , +.Nm issignal , +.Nm killproc , +.Nm pgsigio , +.Nm postsig , +.Nm sigexit , +.Nm siginit , +.Nm signotify , +.Nm trapsignal +.Nd "kernel signal functions" +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/signalvar.h +.Ft void +.Fn SIGADDSET "sigset_t set" "int signo" +.Ft void +.Fn SIGDELSET "sigset_t set" "int signo" +.Ft void +.Fn SIGEMPTYSET "sigset_t set" +.Ft void +.Fn SIGFILLSET "sigset_t set" +.Ft int +.Fn SIGISMEMBER "sigset_t set" "int signo" +.Ft int +.Fn SIGISEMPTY "sigset_t set" +.Ft int +.Fn SIGNOTEMPTY "sigset_t set" +.Ft int +.Fn SIGSETEQ "sigset_t set1" "sigset_t set2" +.Ft int +.Fn SIGSETNEQ "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIGSETOR "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIGSETAND "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIGSETNAND "sigset_t set1" "sigset_t set2" +.Ft void +.Fn SIG_CANTMASK "sigset_t set" +.Ft void +.Fn SIG_STOPSIGMASK "sigset_t set" +.Ft void +.Fn SIG_CONTSIGMASK "sigset_t set" +.Ft int +.Fn SIGPENDING "struct proc *p" +.Ft int +.Fn cursig "struct thread *td" +.Ft void +.Fn execsigs "struct proc *p" +.Ft int +.Fn issignal "struct thread *td" +.Ft void +.Fn killproc "struct proc *p" "char *why" +.Ft void +.Fn pgsigio "struct sigio **sigiop" "int sig" "int checkctty" +.Ft void +.Fn postsig "int sig" +.Ft void +.Fn sigexit "struct thread *td" "int signum" +.Ft void +.Fn siginit "struct proc *p" +.Ft void +.Fn signotify "struct thread *td" +.Ft void +.Fn trapsignal "struct thread *td" "int sig" "u_long code" +.Sh DESCRIPTION +The +.Fn SIGADDSET +macro adds +.Fa signo +to +.Fa set . +No effort is made to ensure that +.Fa signo +is a valid signal number. +.Pp +The +.Fn SIGDELSET +macro removes +.Fa signo +from +.Fa set . +No effort is made to ensure that +.Fa signo +is a valid signal number. +.Pp +The +.Fn SIGEMPTYSET +macro clears all signals in +.Fa set . +.Pp +The +.Fn SIGFILLSET +macro sets all signals in +.Fa set . +.Pp +The +.Fn SIGISMEMBER +macro determines if +.Fa signo +is set in +.Fa set . +.Pp +The +.Fn SIGISEMPTY +macro determines if +.Fa set +does not have any signals set. +.Pp +The +.Fn SIGNOTEMPTY +macro determines if +.Fa set +has any signals set. +.Pp +The +.Fn SIGSETEQ +macro determines if two signal sets are equal; that is, the same signals +are set in both. +.Pp +The +.Fn SIGSETNEQ +macro determines if two signal sets differ; that is, if any signal set in +one is not set in the other. +.Pp +The +.Fn SIGSETOR +macro ORs the signals set in +.Fa set2 +into +.Fa set1 . +.Pp +The +.Fn SIGSETAND +macro ANDs the signals set in +.Fa set2 +into +.Fa set1 . +.Pp +The +.Fn SIGSETNAND +macro NANDs the signals set in +.Fa set2 +into +.Fa set1 . +.Pp +The +.Fn SIG_CANTMASK +macro clears the +.Dv SIGKILL +and +.Dv SIGSTOP +signals from +.Fa set . +These two signals cannot be blocked or caught and +.Fn SIG_CANTMASK +is used in code where signals are manipulated to ensure this policy +is enforced. +.Pp +The +.Fn SIG_STOPSIGMASK +macro clears the +.Dv SIGSTOP , +.Dv SIGTSTP , +.Dv SIGTTIN , +and +.Dv SIGTTOU +signals from +.Fa set . +.Fn SIG_STOPSIGMASK +is used to clear stop signals when a process is waiting for a child to +exit or exec, and when a process is continuing after having been +suspended. +.Pp +The +.Fn SIG_CONTSIGMASK +macro clears the +.Dv SIGCONT +signal from +.Fa set . +.Fn SIG_CONTSIGMASK +is called when a process is stopped. +.Pp +The +.Fn SIGPENDING +macro determines if the given process has any pending signals that are +not masked. +If the process has a pending signal and the process is currently being +traced, +.Fn SIGPENDING +will return true even if the signal is masked. +.Pp +The +.Fn cursig +function returns the signal number that should be delivered to process +.Fa td->td_proc . +If there are no signals pending, zero is returned. +.Pp +The +.Fn execsigs +function resets the signal set and signal stack of a process in preparation +for an +.Xr execve 2 . +The process lock for +.Fa p +must be held before +.Fn execsigs +is called. +.Pp +The +.Fn issignal +function determines if there are any pending signals for process +.Fa td->td_proc +that should be caught, or cause this process to terminate or interrupt its +current system call. +If process +.Fa td->td_proc +is currently being traced, ignored signals will be handled and the process +is always stopped. +Stop signals are handled and cleared right away by +.Fn issignal +unless the process is a member of an orphaned process group and the stop +signal originated from a TTY. +The process spin lock for +.Fa td->td_proc +may be acquired and released. +The +.Vt sigacts +structure +.Fa td->td_proc->p_sigacts +must be locked before calling +.Fn issignal +and may be released and reacquired during the call. +The process lock for +.Fa td->td_proc +must be acquired before calling +.Fn issignal +and may be released and reacquired during the call. +Default signal actions are not taken for system processes and init. +.Pp +The +.Fn killproc +function delivers +.Dv SIGKILL +to +.Fa p . +.Fa why +is logged as the reason +.Em why +the process was killed. +.Pp +The +.Fn pgsigio +function sends the signal +.Fa sig +to the process or process group +.Fa sigiop->sio_pgid . +If +.Fa checkctty +is non-zero, the signal is only delivered to processes in the process group +that have a controlling terminal. +If +.Fa sigiop->sio_pgid +is for a process (> 0), the lock for +.Fa sigiop->sio_proc +is acquired and released. +If +.Fa sigiop->sio_pgid +is for a process group (< 0), the process group lock for +.Fa sigiop->sio_pgrp +is acquired and released. +The lock +.Va sigio_lock +is acquired and released. +.Pp +The +.Fn postsig +function handles the actual delivery of the signal +.Fa sig . +.Fn postsig +is called from +.Fn ast +after the kernel has been notified that a signal should be delivered +(via a call to +.Fn signotify , +which causes the flag +.Dv PS_NEEDSIGCHK +to be set). +The process lock for process that owns +.Va curthread +must be held before +.Fn postsig +is called, and the current process cannot be 0. +The lock for the +.Va p_sigacts +field of the current process must be held before +.Fn postsig +is called, and may be released and reacquired. +.Pp +The +.Fn sigexit +function causes the process that owns +.Fa td +to exit with a return value of signal number +.Fa sig . +If required, the process will dump core. +The process lock for the process that owns +.Fa td +must be held before +.Fn sigexit +is called. +.Pp +The +.Fn siginit +function is called during system initialization to cause every signal with +a default property of +.Dv SA_IGNORE +(except +.Dv SIGCONT ) +to be ignored by +.Fa p . +The process lock for +.Fa p +is acquired and released, as is the lock for sigacts structure +.Fa p->p_sigacts . +The only process that +.Fn siginit +is ever called for +is +.Va proc0 . +.Pp +The +.Fn signotify +function flags that there are unmasked signals pending that +.Fn ast +should handle. +The process lock for process +.Fa td->td_proc +must be held before +.Fn signotify +is called, and the thread lock is acquired and released. +.Pp +The +.Fn trapsignal +function sends a signal that is the result of a trap to process +.Fa td->td_proc . +If the process is not being traced and the signal can be delivered +immediately, +.Fn trapsignal +will deliver it directly; otherwise, +.Fn trapsignal +will call +.Xr psignal 9 +to cause the signal to be delivered. +The process lock for +.Fa td->td_proc +is acquired and released. +The lock for the +.Va p_sigacts +field of +.Fa td->td_proc +is acquired and released. +.Sh RETURN VALUES +The +.Fn SIGISMEMBER , +.Fn SIGISEMPTY , +.Fn SIGNOTEMPTY , +.Fn SIGSETEQ , +.Fn SIGSETNEQ , +and +.Fn SIGPENDING +macros all return non-zero (true) if the condition they are checking +is found to be true; otherwise, zero (false) is returned. +.Pp +The +.Fn cursig +function returns either a valid signal number or zero. +.Pp +.Fn issignal +returns either a valid signal number or zero. +.Sh SEE ALSO +.Xr gsignal 9 , +.Xr pgsignal 9 , +.Xr psignal 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org . Property changes on: user/imp/camdoc/signal.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/tvtohz.9 =================================================================== --- user/imp/camdoc/tvtohz.9 (nonexistent) +++ user/imp/camdoc/tvtohz.9 (revision 296049) @@ -0,0 +1,58 @@ +.\" Copyright (c) 2000 Kelly Yancey +.\" 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 January 3, 2000 +.Dt TVTOHZ 9 +.Os +.Sh NAME +.Nm tvtohz +.Nd convert time interval to tick count +.Sh SYNOPSIS +.In sys/time.h +.Ft int +.Fn tvtohz "struct timeval *tv" +.Sh DESCRIPTION +The +.Fn tvtohz +function accepts a single argument +.Fa tv +which specifies the time interval over which to calculate the number +of system ticks that would elapse. +.Sh RETURN VALUES +Returns the integral number of system ticks expected to elapse in the given +interval, including the current tick. +.Sh SEE ALSO +.Xr microtime 9 , +.Xr microuptime 9 , +.Xr timeout 9 +.Sh HISTORY +The +.Nm +function first appeared in +.Fx 3.0 +.Sh AUTHORS +This manual page was written by +.An Kelly Yancey Aq Mt kbyanc@posi.net . Property changes on: user/imp/camdoc/tvtohz.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ucred.9 =================================================================== --- user/imp/camdoc/ucred.9 (nonexistent) +++ user/imp/camdoc/ucred.9 (revision 296049) @@ -0,0 +1,236 @@ +.\" +.\" Copyright (C) 2001 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 June 19, 2009 +.Dt UCRED 9 +.Os +.Sh NAME +.Nm ucred , +.Nm crget , +.Nm crhold , +.Nm crfree , +.Nm crshared , +.Nm crcopy , +.Nm crdup , +.Nm cru2x , +.Nm cred_update_thread +.Nd "functions related to user credentials" +.Sh SYNOPSIS +.In sys/param.h +.In sys/ucred.h +.Ft "struct ucred *" +.Fn crget void +.Ft "struct ucred *" +.Fn crhold "struct ucred *cr" +.Ft void +.Fn crfree "struct ucred *cr" +.Ft int +.Fn crshared "struct ucred *cr" +.Ft void +.Fn crcopy "struct ucred *dest" "struct ucred *src" +.Ft "struct ucred *" +.Fn crcopysafe "struct proc *p" "struct ucred *cr" +.Ft "struct ucred *" +.Fn crdup "struct ucred *cr" +.Ft void +.Fn crsetgroups "struct ucred *cr" "int ngrp" "gid_t *groups" +.Ft void +.Fn cru2x "struct ucred *cr" "struct xucred *xcr" +.Ft void +.Fn cred_update_thread "struct thread *td" +.Sh DESCRIPTION +The +.Nm +family of functions is used to manage user credential structures +.Pq Vt "struct ucred" +within the kernel. +.Pp +The +.Fn crget +function allocates memory +for a new structure, sets its reference count to 1, and +initializes its lock. +.Pp +The +.Fn crhold +function increases the reference count on the credential. +.Pp +The +.Fn crfree +function decreases the reference count on the credential. +If the count drops to 0, the storage for the structure is freed. +.Pp +The +.Fn crshared +function returns true if the credential is shared. +A credential is considered to be shared if its reference +count is greater than one. +.Pp +The +.Fn crcopy +function copies the contents of the source (template) +credential into the destination template. +The +.Vt uidinfo +structure within the destination is referenced +by calling +.Xr uihold 9 . +.Pp +The +.Fn crcopysafe +function copies the current credential associated with the process +.Fa p +into the newly allocated credential +.Fa cr . +The process lock on +.Fa p +must be held and will be dropped and reacquired as needed to allocate +group storage space in +.Fa cr . +.Pp +The +.Fn crdup +function allocates memory for a new structure and copies the +contents of +.Fa cr +into it. +The actual copying is performed by +.Fn crcopy . +.Pp +The +.Fn crsetgroups +function sets the +.Va cr_groups +and +.Va cr_ngroups +variables and allocates space as needed. +It also truncates the group list to the current maximum number of +groups. +No other mechanism should be used to modify the +.Va cr_groups +array except for updating the primary group via assignment to +.Va cr_groups[0] . +.Pp +The +.Fn cru2x +function converts a +.Vt ucred +structure to an +.Vt xucred +structure. +That is, +it copies data from +.Fa cr +to +.Fa xcr ; +it ignores fields in the former that are not present in the latter +(e.g., +.Va cr_uidinfo ) , +and appropriately sets fields in the latter that are not present in +the former +(e.g., +.Va cr_version ) . +.Pp +The +.Fn cred_update_thread +function sets the credentials of +.Fa td +to that of its process, freeing its old credential if required. +.Sh RETURN VALUES +.Fn crget , +.Fn crhold , +.Fn crdup , +and +.Fn crcopysafe +all return a pointer to a +.Vt ucred +structure. +.Pp +.Fn crshared +returns 0 if the credential has a reference count greater than 1; +otherwise, 1 is returned. +.Sh USAGE NOTES +As of +.Fx 5.0 , +the +.Vt ucred +structure contains extensible fields. +This means that the correct protocol must always be followed to create +a fresh and writable credential structure: new credentials must always +be derived from existing credentials using +.Fn crget , +.Fn crcopy , +and +.Fn crcopysafe . +.Pp +In the common case, credentials required for access control decisions are +used in a read-only manner. +In these circumstances, the thread credential +.Va td_ucred +should be used, as it requires no locking to access safely, and remains stable +for the duration of the call even in the face of a multi-threaded +application changing the process credentials from another thread. +.Pp +During a process credential update, the process lock must be held across +check and update, to prevent race conditions. +The process credential, +.Va td->td_proc->p_ucred , +must be used both for check and update. +If a process credential is updated during a system call and checks against +the thread credential are to be made later during the same system call, +the thread credential must also be refreshed from the process credential +so as to prevent use of a stale value. +To avoid this scenario, it is recommended that system calls updating the +process credential be designed to avoid other authorization functions. +.Pp +If temporarily elevated privileges are required for a thread, the thread +credential can by replaced for the duration of an activity, or for +the remainder of the system call. +However, as a thread credential is often shared, appropriate care should be +taken to make sure modifications are made to a writable credential +through the use of +.Fn crget +and +.Fn crcopy . +.Pp +Caution should be exercised when checking authorization for a thread or +process perform an operation on another thread or process. +As a result of temporary elevation, the target thread credential should +.Em never +be used as the target credential in an access control decision: the process +credential associated with the thread, +.Va td->td_proc->p_ucred , +should be used instead. +For example, +.Xr p_candebug 9 +accepts a target process, not a target thread, for access control purposes. +.Sh SEE ALSO +.Xr uihold 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/ucred.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/uidinfo.9 =================================================================== --- user/imp/camdoc/uidinfo.9 (nonexistent) +++ user/imp/camdoc/uidinfo.9 (revision 296049) @@ -0,0 +1,109 @@ +.\" +.\" Copyright (C) 2001 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 July 10, 2001 +.Dt UIDINFO 9 +.Os +.Sh NAME +.Nm uidinfo , +.Nm uihashinit , +.Nm uifind , +.Nm uihold , +.Nm uifree +.Nd "functions for managing UID information" +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/resourcevar.h +.Ft void +.Fn uihashinit void +.Ft "struct uidinfo *" +.Fn uifind "uid_t uid" +.Ft void +.Fn uihold "struct uidinfo *uip" +.Ft void +.Fn uifree "struct uidinfo *uip" +.Sh DESCRIPTION +The +.Nm +family of functions +is used to manage +.Vt uidinfo +structures. +Each +.Vt uidinfo +structure maintains per uid resource consumption counts, including the +process count and socket buffer space usage. +.Pp +The +.Fn uihashinit +function initializes the +.Vt uidinfo +hash table and its mutex. +This function should only be called during system initialization. +.Pp +The +.Fn uifind +function looks up and returns the +.Vt uidinfo +structure for +.Fa uid . +If no +.Vt uidinfo +structure exists for +.Fa uid , +a new structure will be allocated and initialized. +The +.Nm +hash mutex is acquired and released. +.Pp +The +.Fn uihold +function increases the reference count on +.Fa uip . +.Fa uip Ns 's +lock is acquired and released. +.Pp +The +.Fn uifree +function decreases the reference count on +.Fa uip , +and if the count reaches 0 +.Fa uip +is freed. +.Fa uip Ns 's +lock is acquired and release and the uidinfo hash mutex may be +acquired and released. +.Sh RETURN VALUES +.Fn uifind +returns a pointer to an initialized +.Vt uidinfo +structure, and should not fail. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/uidinfo.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/utopia.9 =================================================================== --- user/imp/camdoc/utopia.9 (nonexistent) +++ user/imp/camdoc/utopia.9 (revision 296049) @@ -0,0 +1,353 @@ +.\" Copyright (c) 2003 +.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). +.\" 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. +.\" +.\" Author: Hartmut Brandt +.\" +.\" $FreeBSD$ +.\" +.Dd May 8, 2003 +.Dt UTOPIA 9 +.Os +.Sh NAME +.Nm utopia +.Nd "driver module for ATM PHY chips" +.Sh SYNOPSIS +.In dev/utopia/utopia.h +.Ft int +.Fo utopia_attach +.Fa "struct utopia *utp" "struct ifatm *ifatm" "struct ifmedia *media" +.Fa "struct mtx *lock" "struct sysctl_ctx_list *ctx" +.Fa "struct sysctl_oid_list *tree" "const struct utopia_methods *vtab" +.Fc +.Ft void +.Fn utopia_detach "struct utopia *utp" +.Ft int +.Fn utopia_start "struct utopia *utp" +.Ft void +.Fn utopia_stop "struct utopia *utp" +.Ft void +.Fn utopia_init_media "struct utopia *utp" +.Ft void +.Fn utopia_reset_media "struct utopia *utp" +.Ft int +.Fn utopia_reset "struct utopia *utp" +.Ft int +.Fn utopia_set_sdh "struct utopia *utp" "int sdh" +.Ft int +.Fn utopia_set_unass "struct utopia *utp" "int unass" +.Ft int +.Fn utopia_set_noscramb "struct utopia *utp" "int noscramb" +.Ft int +.Fn utopia_update_carrier "struct utopia *utp" +.Ft int +.Fn utopia_set_loopback "struct utopia *utp" "u_int mode" +.Ft void +.Fn utopia_intr "struct utopia *utp" +.Ft void +.Fn utopia_update_stats "struct utopia *utp" +.Sh DESCRIPTION +This module is used by all ATM drivers for cards that use a number of known +PHY chips to provide uniform functionality. +The module implements status monitoring in either interrupt or polling mode, +media option handling and application access to PHY registers. +.Pp +To use this interface, a driver must implement two functions for reading and +writing PHY registers, and initialize the following structure with pointers +to these functions: +.Bd -literal -offset indent +struct utopia_methods { + int (*readregs)(struct ifatm *, u_int reg, + uint8_t *val, u_int *n); + int (*writereg)(struct ifatm *, u_int reg, + u_int mask, u_int val); +}; +.Ed +.Pp +The +.Fn readregs +function should read PHY registers starting at register +.Fa reg . +The maximum number of registers to read is given by the integer pointed +to by +.Fa n . +The function should either return 0 on success, or an error code. +In the first case, +.Fa *n +should be set to the actual number of registers read. +The +.Fn writereg +function should write one register. +It must change all bits for which the corresponding bit in +.Fa mask +is 1 to the value of the corresponding bit in +.Fa val . +It returns either 0 on success, or an error code. +.Pp +The ATM driver's private state block +.Pq Va softc +must begin with a +.Vt "struct ifatm" . +.Pp +The +.Vt "struct utopia" +holds the current state of the PHY chip and contains the following fields: +.Bd -literal -offset indent +struct utopia { + struct ifatm *ifatm; /* driver data */ + struct ifmedia *media; /* driver supplied */ + struct mtx *lock; /* driver supplied */ + const struct utopia_methods *methods; + LIST_ENTRY(utopia) link; /* list of these structures */ + u_int flags; /* flags set by the driver */ + u_int state; /* current state */ + u_int carrier; /* carrier state */ + u_int loopback; /* loopback mode */ + const struct utopia_chip *chip; /* chip operations */ + struct utopia_stats1 stats; /* statistics */ +}; +.Ed +The public accessible fields have the following functions: +.Bl -tag -width indent +.It Va ifatm +Pointer to the driver's private data +.Pq Va softc . +.It Va media +Pointer to the driver's media structure. +.It Va lock +Pointer to a mutex provided by the driver. +This mutex is used to synchronize +with the kernel thread that handles device polling. +It is locked in several +places: +.Bl -enum -offset indent +.It +In +.Fn utopia_detach +the mutex is locked to sleep and wait for the kernel thread to remove the +.Vt "struct utopia" +from the list of all +.Nm +devices. +Before returning to the caller the mutex is unlocked. +.It +In the +.Nm +kernel thread the mutex is locked, and the +.Fn utopia_carrier_update +function is called with this mutex locked. +This will result in the driver's +.Fn readregs +function being called with the mutex locked. +.It +In the sysctl handlers the mutex will be locked before calling into the driver's +.Fn readreg +or +.Fn writereg +functions. +.El +.It Va flags +Flags set by either the driver or the +.Nm +module. +The following flags are +defined: +.Bl -tag -width indent +.It Dv UTP_FL_NORESET +If this flag is set, the module will not try to write the +SUNI master reset register. +(Set by the driver.) +.It Dv UTP_FL_POLL_CARRIER +If this flag is set, the module will periodically poll the carrier state +(as opposed to interrupt driven carrier state changes). +(Set by the driver.) +.El +.It Va state +Flags describing the current state of the PHY chip. +These are managed +by the module: +.Bl -tag -width indent +.It Dv UTP_ST_ACTIVE +The driver is active and the PHY registers can be accessed. +This is set by calling +.Fn utopia_start , +which should be called either in the attach routine of the driver or +in the network interface initialisation routine (depending on whether the +registers are accessible all the time or only when the interface is up). +.It Dv UTP_ST_SDH +Interface is in SDH mode as opposed to SONET mode. +.It Dv UTP_ST_UNASS +Interface is producing unassigned cells instead of idle cells. +.It Dv UTP_ST_NOSCRAMB +Cell scrambling is switched off. +.It Dv UTP_ST_DETACH +(Internal use.) +Interface is currently detaching. +.It Dv UTP_ST_ATTACHED +The attach routine has been run successfully. +.El +.It Va carrier +The carrier state of the interface. +This field can have one of three values: +.Bl -tag -width indent +.It Dv UTP_CARR_UNKNOWN +Carrier state is still unknown. +.It Dv UTP_CARR_OK +Carrier has been detected. +.It Dv UTP_CARR_LOST +Carrier has been lost. +.El +.It Va loopback +This is the current loopback mode of the interface. +Note that not all +chips support all loopback modes. +Refer to the chip documentation. +The +following modes may be supported: +.Bl -tag -width indent +.It Dv UTP_LOOP_NONE +No loopback, normal operation. +.It Dv UTP_LOOP_TIME +Timing source loopback. +The transmitter clock is driven by the receive clock. +.It Dv UTP_LOOP_DIAG +Diagnostic loopback. +.It Dv UTP_LOOP_LINE +Serial line loopback. +.It Dv UTP_LOOP_PARAL +Parallel diagnostic loopback. +.It Dv UTP_LOOP_TWIST +Twisted pair diagnostic loopback. +.It Dv UTP_LOOP_PATH +Diagnostic path loopback. +.El +.It Va chip +This points to a function vector for chip specific functions. +Two fields +in this vector are publicly available: +.Bl -tag -width indent +.It Va type +This is the type of the detected PHY chip. +One of: +.Pp +.Bl -tag -width indent -compact +.It Dv UTP_TYPE_UNKNOWN Pq No 0 +.It Dv UTP_TYPE_SUNI_LITE Pq No 1 +.It Dv UTP_TYPE_SUNI_ULTRA Pq No 2 +.It Dv UTP_TYPE_SUNI_622 Pq No 3 +.It Dv UTP_TYPE_IDT77105 Pq No 4 +.El +.It Va name +This is a string with the name of the PHY chip. +.El +.El +.Pp +The following functions are used by the driver during attach/detach and/or +initialisation/stopping the interface: +.Bl -tag -width indent +.It Fn utopia_attach +Attach the PHY chip. +This is called with a preallocated +.Vt "struct utopia" +(which may be part of the driver's +.Va softc ) . +The module initializes all fields of the +.Nm +state and the media field. +User settable flags should be set after the call to +.Fn utopia_attach . +This function may fail due to the inability to install the sysctl handlers. +In this case it will return \-1. +On success, 0 is returned and the +.Dv UTP_ST_ATTACHED +flag is set. +.It Fn utopia_detach +Remove the +.Nm +attachment from the system. +This cancels all outstanding polling +timeouts. +.It Fn utopia_start +Start operation of that PHY. +This should be called at a time +when the PHY registers are known to be accessible. +This may be either in +the driver's attach function or when the interface is set running. +.It Fn utopia_stop +Stop operation of the PHY attachment. +This may be called either in the detach +function of the driver or when the interface is brought down. +.It Fn utopia_init_media +This must be called if the media field in the ATM MIB was changed. +The function +makes sure, that the ifmedia fields contain the same information as the +ATM MIB. +.It Fn utopia_reset_media +This may be called to remove all media information from the ifmedia field. +.El +.Pp +The following functions can be used to modify the PHY state while the interface +is running: +.Bl -tag -width indent +.It Fn utopia_reset +Reset the operational parameters to the default state (SONET, idle cells, +scrambling enabled). +Returns 0 on success, an error code otherwise, leaving +the state undefined. +.It Fn utopia_set_sdh +If the argument is zero the chip is switched to Sonet mode, if it is non-zero +the chip is switched to SDH mode. +Returns 0 on success, an error code otherwise, +leaving the previous state. +.It Fn utopia_set_unass +If the argument is zero the chip is switched to produce idle cells, if it is +non-zero the chip is switched to produce unassigned cells. +Returns 0 on success, +an error code otherwise, leaving the previous state. +.It Fn utopia_set_noscramb +If the argument is zero enables scrambling, if it is +non-zero disables scrambling. +Returns 0 on success, +an error code otherwise, leaving the previous state. +.It Fn utopia_update_carrier +Check the carrier state and update the carrier field in the state structure. +This will generate a message to the Netgraph stack if the carrier state changes. +For chips that are polled this is called automatically, for interrupt +driven attachments this must be called on interrupts from the PHY chip. +.It Fn utopia_set_loopback +Set the loopback mode of the chip. +Returns 0 on success, an error code +otherwise, leaving the previous state. +.It Fn utopia_intr +Called when an interrupt from the PHY chip is detected. +This resets the +interrupt state by reading all registers and, if the interrupt was from the +RSOP, checks the carrier state. +.It Fn utopia_update_stats +Update the statistics with counters read from the chip. +.El +.Sh SEE ALSO +.Xr utopia 4 +.Sh AUTHORS +.An Harti Brandt Aq Mt harti@FreeBSD.org Property changes on: user/imp/camdoc/utopia.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vaccess_acl_nfs4.9 =================================================================== --- user/imp/camdoc/vaccess_acl_nfs4.9 (nonexistent) +++ user/imp/camdoc/vaccess_acl_nfs4.9 (revision 296049) @@ -0,0 +1,129 @@ +.\"- +.\" Copyright (c) 2001 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 September 18, 2009 +.Dt VACCESS_ACL_NFS4 9 +.Os +.Sh NAME +.Nm vaccess_acl_nfs4 +.Nd generate a NFSv4 ACL access control decision using vnode parameters +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fo vaccess_acl_nfs4 +.Fa "enum vtype type" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "struct acl *acl" +.Fa "accmode_t accmode" +.Fa "struct ucred *cred" +.Fa "int *privused" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +with NFSv4 ACL extensions. +It accepts the vnodes type +.Fa type , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +access ACL for the file +.Fa acl , +desired access mode +.Fa accmode , +requesting credential +.Fa cred , +and an optional call-by-reference +.Vt int +pointer returning whether or not +privilege was required for successful evaluation of the call; the +.Fa privused +pointer may be set to +.Dv NULL +by the caller in order not to be informed of +privilege information, or it may point to an integer that will be set to +1 if privilege is used, and 0 otherwise. +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn vaccess_acl_nfs4 +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn vaccess_acl_nfs4 +is based on the NFSv4 ACL evaluation algorithm, as described in +NFSv4 Minor Version 1, draft-ietf-nfsv4-minorversion1-21.txt. +The algorithm selects a +.Em matching +entry from the access ACL, which may +then be composed with an available ACL mask entry, providing +.Ux +security compatibility. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn vaccess_acl_nfs4 +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr vaccess 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +Current implementation of +.Fn vaccess_acl_nfs4 +was written by +.An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org . +.Sh BUGS +This manual page should include a full description of the NFSv4 ACL +evaluation algorithm, or cross reference another page that does. Property changes on: user/imp/camdoc/vaccess_acl_nfs4.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/vflush.9 =================================================================== --- user/imp/camdoc/vflush.9 (nonexistent) +++ user/imp/camdoc/vflush.9 (revision 296049) @@ -0,0 +1,81 @@ +.\" +.\" Copyright (C) 2001 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 21, 2001 +.Dt VFLUSH 9 +.Os +.Sh NAME +.Nm vflush +.Nd "flush vnodes for a mount point" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vflush "struct mount *mp" "int rootrefs" "int flags" "struct thread *td" +.Sh DESCRIPTION +The +.Fn vflush +function removes any vnodes in the vnode table that belong to the given +.Vt mount +structure. +.Pp +Its arguments are: +.Bl -tag -width ".Fa rootrefs" +.It Fa mp +The mount point whose vnodes should be removed. +.It Fa rootrefs +The number of references expected on the root vnode. +.Xr vrele 9 +will be invoked on the root vnode +.Fa rootrefs +times. +.It Fa flags +The flags indicating how vnodes should be handled. +.Bl -tag -width ".Dv WRITECLOSE" +.It Dv FORCECLOSE +If set, busy vnodes will be forcibly closed. +.It Dv SKIPSYSTEM +If set, vnodes with the +.Dv VV_SYSTEM +flag set will be skipped. +.It Dv WRITECLOSE +If set, only regular files currently opened for writing will be removed. +.El +.It Fa td +The calling thread. +.El +.Sh RETURN VALUES +A value of 0 is returned if the flush is successful; otherwise, +.Er EBUSY +will be returned. +.Sh SEE ALSO +.Xr vgone 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vflush.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_busy.9 =================================================================== --- user/imp/camdoc/vfs_busy.9 (nonexistent) +++ user/imp/camdoc/vfs_busy.9 (revision 296049) @@ -0,0 +1,91 @@ +.\" +.\" Copyright (C) 2001 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 February 11, 2013 +.Dt VFS_BUSY 9 +.Os +.Sh NAME +.Nm vfs_busy +.Nd "marks a mount point as busy" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn vfs_busy "struct mount *mp" "int flags" +.Sh DESCRIPTION +The +.Fn vfs_busy +function marks a mount point as busy by incrementing +the reference count of a mount point. +It also delays unmounting by sleeping on +.Fa mp +if the +.Dv MNTK_UNMOUNT +flag is set in +.Fa mp->mnt_kern_flag +and the +.Dv MBF_NOWAIT +flag is +.Em not +set. +.Pp +Its arguments are: +.Bl -tag -width ".Fa flags" +.It Fa mp +The mount point to busy. +.It Fa flags +Flags controlling how +.Fn vfs_busy +should act. +.Bl -tag -width ".Dv MBF_MNTLSTLOCK" +.It Dv MBF_NOWAIT +do not sleep if +.Dv MNTK_UNMOUNT +is set. +.It Dv MBF_MNTLSTLOCK +drop the mountlist_mtx in the critical path. +.El +.El +.Sh RETURN VALUES +A 0 value is returned on success. +If the mount point is being +unmounted and MBF_NOWAIT flag is specified +.Er ENOENT +will be returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOENT +The mount point is being unmounted +.Dv ( MNTK_UNMOUNT +is set). +.El +.Sh SEE ALSO +.Xr vfs_unbusy 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfs_busy.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_getnewfsid.9 =================================================================== --- user/imp/camdoc/vfs_getnewfsid.9 (nonexistent) +++ user/imp/camdoc/vfs_getnewfsid.9 (revision 296049) @@ -0,0 +1,77 @@ +.\" +.\" Copyright (C) 2001 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 21, 2001 +.Dt VFS_GETNEWFSID 9 +.Os +.Sh NAME +.Nm vfs_getnewfsid +.Nd "allocate a new file system identifier" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_getnewfsid "struct mount *mp" +.Sh DESCRIPTION +The +.Fn vfs_getnewfsid +function allocates a new file system identifier for the mount point given. +File systems typically call +.Fn vfs_getnewfsid +in their mount routine in order to acquire a unique ID within the system +which can later be used to uniquely identify the file system via calls such as +.Xr vfs_getvfs 9 . +.Pp +The actual +.Vt fsid +is made up of two 32 bit integers, that are stored in the +.Vt statfs +structure of +.Fa mp . +The first integer is unique in the set of mounted file systems, +while the second holds the file system type. +.Bd -literal +typedef struct fsid { + int32_t val[2]; +} fsid_t; +.Ed +.Sh PSEUDOCODE +.Bd -literal +xxx_mount(struct mount *mp, char *path, caddr_t data, + struct nameidata *ndp, struct thread *td) +{ + ... + vfs_getnewfsid(mp); + ... +} +.Ed +.Sh SEE ALSO +.Xr vfs_getvfs 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfs_getnewfsid.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_getopt.9 =================================================================== --- user/imp/camdoc/vfs_getopt.9 (nonexistent) +++ user/imp/camdoc/vfs_getopt.9 (revision 296049) @@ -0,0 +1,245 @@ +.\" +.\" Copyright (C) 2007 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 July 31, 2011 +.Dt VFS_GETOPT 9 +.Os +.Sh NAME +.Nm vfs_getopt , +.Nm vfs_getopts , +.Nm vfs_flagopt , +.Nm vfs_scanopt , +.Nm vfs_copyopt , +.Nm vfs_filteropt , +.Nm vfs_setopt , +.Nm vfs_setopt_part , +.Nm vfs_setopts +.Nd "manipulate mount options and their values" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fo vfs_getopt +.Fa "struct vfsoptlist *opts" "const char *name" "void **buf" "int *len" +.Fc +.Ft "char *" +.Fn vfs_getops "struct vfsoptlist *opts" "const char *name" "int *error" +.Ft int +.Fo vfs_flagopt +.Fa "struct vfsoptlist *opts" "const char *name" "uint64_t *flags" "uint64_t flag" +.Fc +.Ft int +.Fo vfs_scanopt +.Fa "struct vfsoptlist *opts" "const char *name" "const char *fmt" ... +.Fc +.Ft int +.Fo vfs_copyopt +.Fa "struct vfsoptlist *opts" "const char *name" "void *dest" "int len" +.Fc +.Ft int +.Fo vfs_filteropt +.Fa "struct vfsoptlist *opts" "const char **legal" +.Fc +.Ft int +.Fo vfs_setopt +.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len" +.Fc +.Ft int +.Fo vfs_setopt_part +.Fa "struct vfsoptlist *opts" "const char *name" "void *value" "int len" +.Fc +.Ft int +.Fo vfs_setopts +.Fa "struct vfsoptlist *opts" "const char *name" "const char *value" +.Fc +.Sh DESCRIPTION +The +.Fn vfs_getopt +function sets +.Fa buf +to point to the value of the named mount option, and sets +.Fa len +to the length of the value if it is not +.Dv NULL . +The +.Fa buf +argument +will point to the actual value, and does not need to be freed or released +(and probably should not be modified). +.Pp +The +.Fn vfs_getopts +function +returns the value of the specified option if it is a string (i.e., +.Dv NUL +terminated). +.Pp +The +.Fn vfs_flagopt +function determines if an option exists. +If the option does exist, and +.Fa flags +is not +.Dv NULL , +.Fa flag +is added to those already set in +.Fa flags . +If the option does not exist, and +.Fa flags +is not +.Dv NULL , +.Fa flag +is removed from those already set in +.Fa flags . +An example of typical usage is: +.Bd -literal +if (vfs_flagopt(mp->mnt_optnew, "wormlike", NULL, 0)) + vfs_flagopt(mp->mnt_optnew, "appendok", &(mp->flags), F_APPENDOK); +.Ed +.Pp +The +.Fn vfs_scanopt +function performs a +.Xr vsscanf 3 +with the option's value, using the given format, +into the specified variable arguments. +The value must be a string (i.e., +.Dv NUL +terminated). +.Pp +The +.Fn vfs_copyopt +function creates a copy of the option's value. +The +.Fa len +argument must match the length of the option's value exactly +(i.e., a larger buffer will still cause +.Fn vfs_copyout +to fail with +.Er EINVAL ) . +.Pp +The +.Fn vfs_filteropt +function ensures that no unknown options were specified. +A option is valid if its name matches one of the names in the +list of legal names. +An option may be prefixed with 'no', and still be considered valid. +.Pp +The +.Fn vfs_setopt +and +.Fn vfs_setopt_part +functions copy new data into the option's value. +In +.Fn vfs_setopt , +the +.Fa len +argument must match the length of the option's value exactly +(i.e., a larger buffer will still cause +.Fn vfs_copyout +to fail with +.Er EINVAL ) . +.Pp +The +.Fn vfs_setopts +function copies a new string into the option's value. +The string, including +.Dv NUL +byte, must be no longer than the option's length. +.Sh RETURN VALUES +The +.Fn vfs_getopt +function returns 0 if the option was found; otherwise, +.Er ENOENT +is returned. +.Pp +The +.Fn vfs_getops +function returns the specified option if it is found, and is +.Dv NUL +terminated. +If the option was found, but is not +.Dv NUL +terminated, +.Fa error +is set to +.Er EINVAL +and +.Dv NULL +is returned. +If the option was not found, +.Fa error +is set to 0, and +.Dv NULL +is returned. +.Pp +The +.Fn vfs_flagopt +function returns 1 if the option was found, and 0 if it was not. +.Pp +The +.Fn vfs_scanopt +function returns 0 if the option was not found, or was not +.Dv NUL +terminated; otherwise, the return value of +.Xr vsscanf 3 +is returned. +If +.Xr vsscanf 3 +returns 0, it will be returned unchanged; therefore, a return value of 0 does +not always mean the option does not exist, or is not a valid string. +.Pp +The +.Fn vfs_copyopt +and +.Fn vfs_setopt +functions return 0 if the copy was successful, +.Er EINVAL +if the option was found but the lengths did not match, and +.Er ENOENT +if the option was not found. +.Pp +The +.Fn vfs_filteropt +function returns 0 if all of the options are legal; otherwise, +.Er EINVAL +is returned. +.Pp +The +.Fn vfs_setopts +function returns 0 if the copy was successful, +.Er EINVAL +if the option was found but the string was too long, and +.Er ENOENT +if the option was not found. +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Chad David Aq Mt davidc@FreeBSD.org +and +.An Ruslan Ermilov Aq Mt ru@FreeBSD.org . Property changes on: user/imp/camdoc/vfs_getopt.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_getvfs.9 =================================================================== --- user/imp/camdoc/vfs_getvfs.9 (nonexistent) +++ user/imp/camdoc/vfs_getvfs.9 (revision 296049) @@ -0,0 +1,77 @@ +.\" +.\" Copyright (C) 2001 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 21, 2001 +.Dt VFS_GETVFS 9 +.Os +.Sh NAME +.Nm vfs_getvfs +.Nd "returns a mount point given its file system identifier" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft "struct mount *" +.Fn vfs_getvfs "fsid_t *fsid" +.Sh DESCRIPTION +The +.Fn vfs_getvfs +function returns the mount point structure for a file system given its file system +identifier. +The file system ID should have been allocated by calling +.Xr vfs_getnewfsid 9 ; +otherwise, it will not be found. +.Pp +A major user of +.Fn vfs_getvfs +is NFS, which uses the +.Vt fsid +as part of file handles in order to determine the +file system a given RPC is for. +If +.Fn vfs_getvfs +fails to find the mount point related to +.Fa fsid , +the file system is considered stale. +.Sh RETURN VALUES +If +.Fa fsid +is found, the mount point for the ID is returned; otherwise, +.Dv NULL +is returned. +.Sh PSEUDOCODE +.Bd -literal +if ((mp = vfs_getvfs(&fhp->fh_fsid)) == NULL) { + error = ESTALE; + goto out; +} +.Ed +.Sh SEE ALSO +.Xr vfs_getnewfsid 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfs_getvfs.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_mountedfrom.9 =================================================================== --- user/imp/camdoc/vfs_mountedfrom.9 (nonexistent) +++ user/imp/camdoc/vfs_mountedfrom.9 (revision 296049) @@ -0,0 +1,55 @@ +.\" Copyright (C) 2008 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 February 25, 2008 +.Dt VFS_MOUNTEDFROM 9 +.Os +.Sh NAME +.Nm vfs_mountedfrom +.Nd "sets the mounted from name for a mount" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_mountedfrom "struct mount *mp" "const char *from" +.Sh DESCRIPTION +The +.Fn vfs_mountedfrom +function sets the mounted from name for a mount. +This value is used by +.Fn statfs 2 +to fill in +.Va f_mntfromname . +.Pp +In most cases +.Va from +is the device that contains the file system, but in the case of a pseudo +file system it could be a descriptive name like "devfs" or "procfs". +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfs_mountedfrom.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_rootmountalloc.9 =================================================================== --- user/imp/camdoc/vfs_rootmountalloc.9 (nonexistent) +++ user/imp/camdoc/vfs_rootmountalloc.9 (revision 296049) @@ -0,0 +1,66 @@ +.\" +.\" Copyright (C) 2001 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 21, 2001 +.Dt VFS_ROOTMOUNTALLOC 9 +.Os +.Sh NAME +.Nm vfs_rootmountalloc +.Nd "allocate a root" +.Vt mount +structure +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn vfs_rootmountalloc "char *fstypename" "char *devname" "struct mount **mpp" +.Sh DESCRIPTION +.Fn vfs_rootmountalloc +allocates a +.Vt mount +structure initialized from the +.Vt vfsconf +type that matches +.Fa fstypename . +.Sh RETURN VALUES +If successful, 0 is returned and +.Fa mpp +points to the newly allocated +.Vt mount +structure. +.Er ENODEV +is returned if +.Fa fstypename +is +.Dv NULL +or invalid. +.Sh SEE ALSO +.Xr vfsconf 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfs_rootmountalloc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_timestamp.9 =================================================================== --- user/imp/camdoc/vfs_timestamp.9 (nonexistent) +++ user/imp/camdoc/vfs_timestamp.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" +.\" Copyright (C) 2001 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 21, 2001 +.Dt VFS_TIMESTAMP 9 +.Os +.Sh NAME +.Nm vfs_timestamp +.Nd "generate current timestamp" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vfs_timestamp "struct timespec *tsp" +.Sh DESCRIPTION +The +.Fn vfs_timestamp +function fills in +.Fa tsp +with the current time. +.Pp +The precision is based on the value of the +.Va vfs.timestamp_precision +sysctl variable: +.Pp +.Bl -tag -width ".No \(>=3" -compact +.It 0 +seconds only; nanoseconds are zeroed. +.It 1 +seconds and nanoseconds, accurate within 1/HZ. +.It 2 +seconds and nanoseconds, truncated to microseconds. +.It \(>=3 +seconds and nanoseconds, maximum precision. +.El +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfs_timestamp.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_unbusy.9 =================================================================== --- user/imp/camdoc/vfs_unbusy.9 (nonexistent) +++ user/imp/camdoc/vfs_unbusy.9 (revision 296049) @@ -0,0 +1,58 @@ +.\" +.\" Copyright (C) 2001 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 June 14, 2010 +.Dt VFS_UNBUSY 9 +.Os +.Sh NAME +.Nm vfs_unbusy +.Nd "unbusy a mount point" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_unbusy "struct mount *mp" +.Sh DESCRIPTION +The +.Fn vfs_unbusy +function un-busies a mount point by decrementing +the reference count of a mount point. +The reference count is typically incremented by calling +.Xr vfs_busy 9 +prior to this call. +.Pp +Its arguments are: +.Bl -tag -width ".Fa mp" +.It Fa mp +The mount point to unbusy. +.El +.Sh SEE ALSO +.Xr vfs_busy 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfs_unbusy.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfsconf.9 =================================================================== --- user/imp/camdoc/vfsconf.9 (nonexistent) +++ user/imp/camdoc/vfsconf.9 (revision 296049) @@ -0,0 +1,151 @@ +.\" +.\" Copyright (C) 2001 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 June 16, 2013 +.Dt VFSCONF 9 +.Os +.Sh NAME +.Nm vfsconf +.Nd "vfs configuration information" +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft int +.Fn vfs_register "struct vfsconf *vfc" +.Ft int +.Fn vfs_unregister "struct vfsconf *vfc" +.Ft int +.Fn vfs_modevent "module_t mod" "int type" "void *data" +.Sh DESCRIPTION +Each file system type known to the kernel has a +.Vt vfsconf +structure that contains the +information required to create a new mount of that file systems type. +.Bd -literal +struct vfsconf { + struct vfsops *vfc_vfsops; /* file system operations vector */ + char vfc_name[MFSNAMELEN]; /* file system type name */ + int vfc_typenum; /* historic file system type number */ + int vfc_refcount; /* number mounted of this type */ + int vfc_flags; /* permanent flags */ + struct vfsconf *vfc_next; /* next in list */ +}; +.Ed +.Pp +When a new file system is mounted, +.Xr mount 2 +does a lookup of the +.Vt vfsconf +structure by its name, and if it is not already registered, +attempts to load a kernel module for it. +The file system operations for the new mount point are taken from +.Va vfc_vfsops , +and +.Va mnt_vfc +in the +.Vt mount +structure is made to point directly at the +.Vt vfsconf +structure for the +file system type. +The file system type number is taken from +.Va vfc_typenum +which was assigned in +.Fn vfs_register , +and the mount flags are taken from a mask of +.Va vfc_flags . +Each time a file system of a given type is mounted, +.Va vfc_refcount +is incremented. +.Pp +.Fn vfs_register +takes a new +.Vt vfsconf +structure and adds it to the list of existing file systems. +If the type has not already been registered, it is initialized by calling the +.Fn vfs_init +function in the file system operations vector. +.Fn vfs_register +also updates the oid's of any sysctl nodes for this file system type +to be the same as the newly assigned type number. +.Pp +.Fn vfs_unregister +unlinks +.Fa vfc +from the list of registered file system types if there are currently no mounted instances. +If the +.Fn vfs_uninit +function in the file systems initialization vector is defined, it is called. +.Pp +.Fn vfs_modevent +is registered by +.Fn VFS_SET +to handle the loading and unloading of file system kernel modules. +In the case of +.Dv MOD_LOAD , +.Fn vfs_register +is called. +In the case of +.Dv MOD_UNLOAD , +.Fn vfs_unregister +is called. +.Sh RETURN VALUES +.Fn vfs_register +returns 0 if successful; otherwise, +.Er EEXIST +is returned indicating that the file system type has already been registered. +.Pp +.Fn vfs_unregister +returns 0 if successful. +If no +.Vt vfsconf +entry can be found matching the name in +.Fa vfc , +.Er EINVAL +is returned. +If the reference count of mounted instances of the file system type is not zero, +.Er EBUSY +is returned. +If +.Fn vfs_uninit +is called, any errors it returns will be returned by +.Fn vfs_unregister . +.Pp +.Fn vfs_modevent +returns the result of the call to +.Fn vfs_register +or +.Fn vfs_unregister , +whatever the case. +.Sh SEE ALSO +.Xr mount 2 , +.Xr vfs_rootmountalloc 9 , +.Xr VFS_SET 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vfsconf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vhold.9 =================================================================== --- user/imp/camdoc/vhold.9 (nonexistent) +++ user/imp/camdoc/vhold.9 (revision 296049) @@ -0,0 +1,83 @@ +.\" +.\" Copyright (C) 2001 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 April 1, 2007 +.Dt VHOLD 9 +.Os +.Sh NAME +.Nm vhold , vdrop , vdropl +.Nd "acquire/release a hold on a vnode" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft void +.Fn vhold "struct vnode *vp" +.Ft void +.Fn vholdl "struct vnode *vp" +.Ft void +.Fn vdrop "struct vnode *vp" +.Ft void +.Fn vdropl "struct vnode *vp" +.Sh DESCRIPTION +The +.Fn vhold +and +.Fn vholdl +functions increment the +.Va v_holdcnt +of the given vnode. +If the vnode has already been added to the free list and is still referenced, +it will be removed. +.Pp +The +.Fn vdrop +and +.Fn vdropl +functions decrement the +.Va v_holdcnt +of the vnode. +If the holdcount is less than or equal to zero prior to calling +.Fn vdrop +or +.Fn vdropl , +the system will panic. +If the vnode is no longer referenced, it will be freed. +.Pp +.Fn vhold +and +.Fn vdrop +lock the vnode interlock while +.Fn vholdl +and +.Fn vdropl +expect the interlock to already be held. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vhold.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vinvalbuf.9 =================================================================== --- user/imp/camdoc/vinvalbuf.9 (nonexistent) +++ user/imp/camdoc/vinvalbuf.9 (revision 296049) @@ -0,0 +1,117 @@ +.\" +.\" Copyright (C) 2001 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 October 20, 2008 +.Dt VINVALBUF 9 +.Os +.Sh NAME +.Nm vinvalbuf +.Nd "flushes and invalidates all buffers associated with a vnode" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vinvalbuf "struct vnode *vp" "int flags" "struct ucred *cred" "int slpflag" "int slptimeo" +.Sh DESCRIPTION +The +.Fn vinvalbuf +function invalidates all of the buffers associated with the given vnode. +This includes buffers on the clean list and the dirty list. +If the +.Dv V_SAVE +flag is specified then the buffers on the dirty list are synced prior to being +released. +If there is a VM Object associated with the vnode, it is removed. +.Pp +Its arguments are: +.Bl -tag -width ".Fa spltimeo" +.It Fa vp +A pointer to the vnode whose buffers will be invalidated. +.It Fa flags +The only supported flag is +.Dv V_SAVE +and it indicates that dirty buffers should be synced with the disk. +.It Fa cred +The user credentials that are used to +.Xr VOP_FSYNC 9 +buffers if +.Dv V_SAVE +is set. +.It Fa slpflag +The slp flag that will be used in the priority of any sleeps in the function. +.It Fa slptimeo +The timeout for any sleeps in the function. +.El +.Sh LOCKS +The vnode is assumed to be locked prior to the call and remains locked upon return. +.Pp +.Va Giant +must be held by prior to the call and remains locked upon return. +.Sh RETURN VALUES +A 0 value is returned on success. +.Sh PSEUDOCODE +.Bd -literal -offset indent +vn_lock(devvp, LK_EXCLUSIVE | LK_RETRY); +error = vinvalbuf(devvp, V_SAVE, cred, 0, 0); +VOP_UNLOCK(devvp, 0); +if (error) + return (error); +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOSPC +The file system is full. +(With +.Dv V_SAVE ) +.It Bq Er EDQUOT +Disc quota exceeded. +(With +.Dv V_SAVE ) +.It Bq Er EWOULDBLOCK +Sleep operation timed out. +(See +.Fa slptimeo ) +.It Bq Er ERESTART +A signal needs to be delivered and the system call should be restarted. +(With +.Dv PCATCH +set in +.Fa slpflag ) +.It Bq Er EINTR +The system has been interrupted by a signal. +(With +.Dv PCATCH +set in +.Fa slpflag ) +.El +.Sh SEE ALSO +.Xr tsleep 9 , +.Xr VOP_FSYNC 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vinvalbuf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_fault_prefault.9 =================================================================== --- user/imp/camdoc/vm_fault_prefault.9 (nonexistent) +++ user/imp/camdoc/vm_fault_prefault.9 (revision 296049) @@ -0,0 +1,72 @@ +.\" +.\" 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 July 21, 2003 +.Dt VM_FAULT_PREFAULT 9 +.Os +.Sh NAME +.Nm vm_fault_prefault +.Nd cluster page faults into a process's address space +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/pmap.h +.Ft void +.Fn vm_fault_prefault "pmap_t pmap" "vm_offset_t addra" "vm_map_entry_t entry" +.Sh DESCRIPTION +The +.Fn vm_fault_prefault +function provides a means of clustering pagefaults into a process's +address space. +It operates upon the physical map +.Fa pmap . +The +.Fa entry +argument specifies the entry to be prefaulted; the +.Fa addra +argument specifies the beginning of the mapping in the process's virtual +address space. +.Pp +It is typically called by +.Fn vm_fault +after the first page fault. +It benefits the +.Xr execve 2 +system call by eliminating repetitive calls to +.Fn vm_fault , +which would otherwise be made to bring the process's executable pages +into physical memory. +.Sh IMPLEMENTATION NOTES +This is a machine-independent function which calls the machine-dependent +.Xr pmap_is_prefaultable 9 +helper function to determine if a page may be prefaulted into physical memory. +.Sh SEE ALSO +.Xr execve 2 , +.Xr pmap_is_prefaultable 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_fault_prefault.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map.9 =================================================================== --- user/imp/camdoc/vm_map.9 (nonexistent) +++ user/imp/camdoc/vm_map.9 (revision 296049) @@ -0,0 +1,350 @@ +.\" +.\" 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 July 9, 2011 +.Dt VM_MAP 9 +.Os +.Sh NAME +.Nm vm_map +.Nd virtual address space portion of virtual memory subsystem +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Sh DESCRIPTION +The +.Nm +subsystem is used to manage virtual address spaces. +This section describes the main data structures used within the code. +.Pp +The +.Vt "struct vm_map" +is a generic representation of an address space. +This address space may belong to a user process or the kernel. +The kernel actually uses several maps, which are maintained as +subordinate maps, created using the +.Xr vm_map_submap 9 +function. +.Bd -literal -offset indent +struct vm_map { + struct vm_map_entry header; + struct sx lock; + struct mtx system_mtx; + int nentries; + vm_size_t size; + u_int timestamp; + u_char needs_wakeup; + u_char system_map; + vm_flags_t flags; + vm_map_entry_t root; + pmap_t pmap; +#define min_offset header.start +#define max_offset header.end +}; +.Ed +.Pp +The fields of +.Vt struct vm_map +are as follows: +.Bl -tag -width ".Va needs_wakeup" +.It Va header +Head node of a circular, doubly linked list of +.Vt struct vm_map_entry +objects. +Each object defines a particular region within this map's address space. +.It Va lock +Used to serialize access to the structure. +.It Va system_mtx +A mutex which is used if the map is a system map. +.It Va nentries +A count of the members in use within the circular map entry list. +.It Va size +Specifies the size of the virtual address space. +.It Va timestamp +Used to determine if the map has changed since its last access. +.It Va needs_wakeup +Indicates if a thread is waiting for an allocation within the map. +Used only by system maps. +.It Va system_map +Set to TRUE to indicate that map is a system map; otherwise, it belongs +to a user process. +.It Va flags +Map flags, described below. +.It Va root +Root node of a binary search tree used for fast lookup of map entries. +.It Va pmap +Pointer to the underlying physical map with which this virtual map +is associated. +.It Va min_offset +The minimum +.Vt vm_offset_t +in this map. +Programs should never use +.Va header.start +or +.Va header.end +directly, use +.Va min_offset +and +.Va max_offset +instead. +.It Va max_offset +The maximum +.Vt vm_offset_t +in this map. +.El +.Pp +There is one possible map flag: +.Bl -tag -width ".Dv MAP_PREFAULT_MADVISE" +.It Dv MAP_WIREFUTURE +Wire all future pages in this map. +.El +.Pp +The following flags can be passed to +.Xr vm_map_find 9 +and +.Xr vm_map_insert 9 +to specify the copy-on-write properties of regions within the map: +.Bl -tag -width ".Dv MAP_PREFAULT_MADVISE" +.It Dv MAP_COPY_ON_WRITE +The mapping is copy-on-write. +.It Dv MAP_NOFAULT +The mapping should not generate page faults. +.It Dv MAP_PREFAULT +The mapping should be prefaulted into physical memory. +.It Dv MAP_PREFAULT_PARTIAL +The mapping should be partially prefaulted into physical memory. +.It Dv MAP_DISABLE_SYNCER +Do not periodically flush dirty pages; only flush them when absolutely +necessary. +.It Dv MAP_DISABLE_COREDUMP +Do not include the mapping in a core dump. +.It Dv MAP_PREFAULT_MADVISE +Specify that the request is from a user process calling +.Xr madvise 2 . +.It Dv MAP_ACC_CHARGED +Region is already charged to the requestor by some means. +.It Dv MAP_ACC_NO_CHARGE +Do not charge for allocated region. +.El +.Pp +The +.Vt struct vm_map_entry +is a generic representation of a region. +The region managed by each entry is associated with a +.Vt union vm_map_object , +described below. +.Bd -literal -offset indent +struct vm_map_entry { + struct vm_map_entry *prev; + struct vm_map_entry *next; + struct vm_map_entry *left; + struct vm_map_entry *right; + vm_offset_t start; + vm_offset_t end; + vm_offset_t avail_ssize; + vm_size_t adj_free; + vm_size_t max_free; + union vm_map_object object; + vm_ooffset_t offset; + vm_eflags_t eflags; + /* Only in task maps: */ + vm_prot_t protection; + vm_prot_t max_protection; + vm_inherit_t inheritance; + int wired_count; + vm_pindex_t lastr; +}; +.Ed +.Pp +The fields of +.Vt struct vm_map_entry +are as follows: +.Bl -tag -width ".Va avail_ssize" +.It Va prev +Pointer to the previous node in a doubly-linked, circular list. +.It Va next +Pointer to the next node in a doubly-linked, circular list. +.It Va left +Pointer to the left node in a binary search tree. +.It Va right +Pointer to the right node in a binary search tree. +.It Va start +Lower address bound of this entry's region. +.It Va end +Upper address bound of this entry's region. +.It Va avail_ssize +If the entry is for a process stack, specifies how much the entry can grow. +.It Va adj_free +The amount of free, unmapped address space adjacent to and immediately +following this map entry. +.It Va max_free +The maximum amount of contiguous free space in this map entry's subtree. +.It Va object +Pointer to the +.Vt struct vm_map_object +with which this entry is associated. +.It Va offset +Offset within the +.Va object +which is mapped from +.Va start +onwards. +.It Va eflags +Flags applied to this entry, described below. +.El +.Pp +The following five members are only valid for entries forming part of +a user process's address space: +.Bl -tag -width ".Va max_protection" +.It Va protection +Memory protection bits applied to this region. +.It Va max_protection +Mask for the memory protection bits which may be actually be applied to +this region. +.It Va inheritance +Contains flags which specify how this entry should be treated +during fork processing. +.It Va wired_count +Count of how many times this entry has been wired into physical memory. +.It Va lastr +Contains the address of the last read which caused a page fault. +.El +.Pp +The following flags may be applied to each entry, by specifying them +as a mask within the +.Va eflags +member: +.Bl -tag -width ".Dv MAP_ENTRY_BEHAV_SEQUENTIAL" +.It Dv MAP_ENTRY_NOSYNC +The system should not flush the data associated with this map +periodically, but only when it needs to. +.It Dv MAP_ENTRY_IS_SUB_MAP +If set, then the +.Va object +member specifies a subordinate map. +.It Dv MAP_ENTRY_COW +Indicate that this is a copy-on-write region. +.It Dv MAP_ENTRY_NEEDS_COPY +Indicate that a copy-on-write region needs to be copied. +.It Dv MAP_ENTRY_NOFAULT +Specifies that accesses within this region should never cause a page fault. +If a page fault occurs within this region, the system will panic. +.It Dv MAP_ENTRY_USER_WIRED +Indicate that this region was wired on behalf of a user process. +.It Dv MAP_ENTRY_BEHAV_NORMAL +The system should use the default paging behaviour for this region. +.It Dv MAP_ENTRY_BEHAV_SEQUENTIAL +The system should depress the priority of pages immediately preceding +each page within this region when faulted in. +.It Dv MAP_ENTRY_BEHAV_RANDOM +Is a hint that pages within this region will be accessed randomly, +and that prefetching is likely not advantageous. +.It Dv MAP_ENTRY_IN_TRANSITION +Indicate that wiring or unwiring of an entry is in progress, and that +other kernel threads should not attempt to modify fields in the structure. +.It Dv MAP_ENTRY_NEEDS_WAKEUP +Indicate that there are kernel threads waiting for this region to become +available. +.It Dv MAP_ENTRY_NOCOREDUMP +The region should not be included in a core dump. +.El +.Pp +The +.Va inheritance +member has type +.Vt vm_inherit_t . +This governs the inheritance behaviour for a map entry during fork processing. +The following values are defined for +.Vt vm_inherit_t : +.Bl -tag -width ".Dv VM_INHERIT_DEFAULT" +.It Dv VM_INHERIT_SHARE +The object associated with the entry should be cloned and shared +with the new map. +A new +.Vt struct vm_object +will be created if necessary. +.It Dv VM_INHERIT_COPY +The object associated with the entry should be copied to the new map. +.It Dv VM_INHERIT_NONE +The entry should not be copied to the new map. +.It Dv VM_INHERIT_DEFAULT +Specifies the default behaviour, +.Dv VM_INHERIT_COPY . +.El +.Pp +The +.Vt union vm_map_object +is used to specify the structure which a +.Vt struct vm_map_entry +is associated with. +.Pp +The fields of +.Vt union vm_map_object +are as follows: +.Bd -literal -offset indent +union vm_map_object { + struct vm_object *vm_object; + struct vm_map *sub_map; +}; +.Ed +.Pp +Normally, the +.Va sub_map +member is only used by system maps to indicate that a memory range +is managed by a subordinate system map. +Within a user process map, each +.Vt struct vm_map_entry +is backed by a +.Vt struct vm_object . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map_check_protection 9 , +.Xr vm_map_create 9 , +.Xr vm_map_delete 9 , +.Xr vm_map_entry_resize_free 9 , +.Xr vm_map_find 9 , +.Xr vm_map_findspace 9 , +.Xr vm_map_inherit 9 , +.Xr vm_map_init 9 , +.Xr vm_map_insert 9 , +.Xr vm_map_lock 9 , +.Xr vm_map_lookup 9 , +.Xr vm_map_madvise 9 , +.Xr vm_map_max 9 , +.Xr vm_map_min 9 , +.Xr vm_map_pmap 9 , +.Xr vm_map_protect 9 , +.Xr vm_map_remove 9 , +.Xr vm_map_simplify_entry 9 , +.Xr vm_map_stack 9 , +.Xr vm_map_submap 9 , +.Xr vm_map_sync 9 , +.Xr vm_map_wire 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_check_protection.9 =================================================================== --- user/imp/camdoc/vm_map_check_protection.9 (nonexistent) +++ user/imp/camdoc/vm_map_check_protection.9 (revision 296049) @@ -0,0 +1,70 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_CHECK_PROTECTION 9 +.Os +.Sh NAME +.Nm vm_map_check_protection +.Nd check memory protection for a vm_map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft boolean_t +.Fo vm_map_check_protection +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_prot_t protection" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_check_protection +function asserts that the target +.Fa map +allows the specified privilege +.Fa protection +over the entire address range from +.Fa start +to +.Fa end . +The region MUST be contiguous; no holes are allowed. +.Sh IMPLEMENTATION NOTES +This code does not and SHOULD not check whether the contents of +the region are accessible. +For example, a small file may be mapped into an address space which +is significantly larger in size. +.Sh RETURN VALUES +The +.Fn vm_map_check_protection +function returns TRUE if the privilege is allowed; if it is not allowed, +or if any other error occurred, the value FALSE is returned. +.Sh SEE ALSO +.Xr munmap 2 , +.Xr vm_map 9 , +.Xr vm_map_protect 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_check_protection.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_create.9 =================================================================== --- user/imp/camdoc/vm_map_create.9 (nonexistent) +++ user/imp/camdoc/vm_map_create.9 (revision 296049) @@ -0,0 +1,66 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_CREATE 9 +.Os +.Sh NAME +.Nm vm_map_create +.Nd create a new vm_map structure +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft vm_map_t +.Fn vm_map_create "pmap_t pmap" "vm_offset_t min" "vm_offset_t max" +.Sh DESCRIPTION +The +.Fn vm_map_create +function creates and returns a new, empty map structure, associated +with the physical map +.Fa pmap , +and with the +upper and lower address bounds specified by +.Fa max +and +.Fa min +respectively. +.Sh IMPLEMENTATION NOTES +The kernel's zone allocator is used to allocate the map. +.Sh RETURN VALUES +The +.Fn vm_map_create +function returns a pointer to the newly allocated map if successful. +Otherwise, it returns +.Dv NULL . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map 9 , +.Xr vm_map_init 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_create.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_delete.9 =================================================================== --- user/imp/camdoc/vm_map_delete.9 (nonexistent) +++ user/imp/camdoc/vm_map_delete.9 (revision 296049) @@ -0,0 +1,68 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_DELETE 9 +.Os +.Sh NAME +.Nm vm_map_delete +.Nd deallocate an address range from a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fn vm_map_delete "vm_map_t map" "vm_offset_t start" "vm_offset_t end" +.Sh DESCRIPTION +The +.Fn vm_map_delete +function deallocates the address range bounded by +.Fa start +and +.Fa end +from the +.Fa map . +.Sh IMPLEMENTATION NOTES +This function is for +.Fx +VM internal use only. +The +.Xr vm_map_remove 9 +function should be called by +.Fx +VM consumers instead. +.Sh RETURN VALUES +The +.Fn vm_map_delete +function always returns +.Dv KERN_SUCCESS . +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_remove 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_delete.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_entry_resize_free.9 =================================================================== --- user/imp/camdoc/vm_map_entry_resize_free.9 (nonexistent) +++ user/imp/camdoc/vm_map_entry_resize_free.9 (revision 296049) @@ -0,0 +1,243 @@ +.\" +.\" Copyright (c) 2004 Mark W. Krentel +.\" 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 17, 2004 +.Dt VM_MAP_ENTRY_RESIZE_FREE 9 +.Os +.Sh NAME +.Nm vm_map_entry_resize_free +.Nd "vm map free space algorithm" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft void +.Fn vm_map_entry_resize_free "vm_map_t map" "vm_map_entry_t entry" +.Sh DESCRIPTION +This manual page describes the +.Vt vm_map_entry +fields used in the VM map free space algorithm, how to maintain +consistency of these variables, and the +.Fn vm_map_entry_resize_free +function. +.Pp +VM map entries are organized as both a doubly-linked list +.Va ( prev +and +.Va next +pointers) and as a binary search tree +.Va ( left +and +.Va right +pointers). +The search tree is organized as a Sleator and Tarjan splay tree, +also known as a +.Dq "self-adjusting tree" . +.Bd -literal -offset indent +struct vm_map_entry { + struct vm_map_entry *prev; + struct vm_map_entry *next; + struct vm_map_entry *left; + struct vm_map_entry *right; + vm_offset_t start; + vm_offset_t end; + vm_offset_t avail_ssize; + vm_size_t adj_free; + vm_size_t max_free; + ... +}; +.Ed +.Pp +The free space algorithm adds two fields to +.Vt "struct vm_map_entry" : +.Va adj_free +and +.Va max_free . +The +.Va adj_free +field +is the amount of free address space adjacent to and immediately +following (higher address) the map entry. +This field is unused in the map header. +Note that +.Va adj_free +depends on the linked list, not the splay tree and that +.Va adj_free +can be computed as: +.Bd -literal -offset indent +entry->adj_free = (entry->next == &map->header ? + map->max_offset : entry->next->start) - entry->end; +.Ed +.Pp +The +.Va max_free +field +is the maximum amount of contiguous free space in the entry's subtree. +Note that +.Va max_free +depends on the splay tree, not the linked list and that +.Va max_free +is computed by taking the maximum of its own +.Va adj_free +and the +.Va max_free +of its left and right subtrees. +Again, +.Va max_free +is unused in the map header. +.Pp +These fields allow for an +.Fn O "log n" +implementation of +.Fn vm_map_findspace . +Using +.Va max_free , +we can immediately test for a sufficiently large free region +in an entire subtree. +This makes it possible to find a first-fit free region of a given size +in one pass down the tree, so +.Fn O "log n" +amortized using splay trees. +.Pp +When a free region changes size, we must update +.Va adj_free +and +.Va max_free +in the preceding map entry and propagate +.Va max_free +up the tree. +This is handled in +.Fn vm_map_entry_link +and +.Fn vm_map_entry_unlink +for the cases of inserting and deleting an entry. +Note that +.Fn vm_map_entry_link +updates both the new entry and the previous entry, and that +.Fn vm_map_entry_unlink +updates the previous entry. +Also note that +.Va max_free +is not actually propagated up the tree. +Instead, that entry is first splayed to the root and +then the change is made there. +This is a common technique in splay trees and is also +how map entries are linked and unlinked into the tree. +.Pp +The +.Fn vm_map_entry_resize_free +function updates the free space variables in the given +.Fa entry +and propagates those values up the tree. +This function should be called whenever a map entry is resized +in-place, that is, by modifying its +.Va start +or +.Va end +values. +Note that if you change +.Va end , +then you should resize that entry, but if you change +.Va start , +then you should resize the previous entry. +The map must be locked before calling this function, +and again, propagating +.Va max_free +is performed by splaying that entry to the root. +.Sh EXAMPLES +Consider adding a map entry with +.Fn vm_map_insert . +.Bd -literal -offset indent +ret = vm_map_insert(map, object, offset, start, end, prot, + max_prot, cow); +.Ed +.Pp +In this case, no further action is required to maintain +consistency of the free space variables. +The +.Fn vm_map_insert +function calls +.Fn vm_map_entry_link +which updates both the new entry and the previous entry. +The same would be true for +.Fn vm_map_delete +and for calling +.Fn vm_map_entry_link +or +.Fn vm_map_entry_unlink +directly. +.Pp +Now consider resizing an entry in-place without a call to +.Fn vm_map_entry_link +or +.Fn vm_map_entry_unlink . +.Bd -literal -offset indent +entry->start = new_start; +if (entry->prev != &map->header) + vm_map_entry_resize_free(map, entry->prev); +.Ed +.Pp +In this case, resetting +.Va start +changes the amount of free space following the previous entry, +so we use +.Fn vm_map_entry_resize_free +to update the previous entry. +.Pp +Finally, suppose we change an entry's +.Va end +address. +.Bd -literal -offset indent +entry->end = new_end; +vm_map_entry_resize_free(map, entry); +.Ed +.Pp +Here, we call +.Fn vm_map_entry_resize_free +on the entry itself. +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_findspace 9 +.Rs +.%A Daniel D. Sleator +.%A Robert E. Tarjan +.%T Self-Adjusting Binary Search Trees +.%J JACM +.%V vol. 32(3) +.%P pp. 652-686 +.%D July 1985 +.Re +.Sh HISTORY +Splay trees were added to the VM map in +.Fx 5.0 , +and the +.Fn O "log n" +tree-based free space algorithm was added in +.Fx 5.3 . +.Sh AUTHORS +The tree-based free space algorithm and this manual page were written by +.An Mark W. Krentel Aq Mt krentel@dreamscape.com . Property changes on: user/imp/camdoc/vm_map_entry_resize_free.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_find.9 =================================================================== --- user/imp/camdoc/vm_map_find.9 (nonexistent) +++ user/imp/camdoc/vm_map_find.9 (revision 296049) @@ -0,0 +1,161 @@ +.\" +.\" 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 September 12, 2013 +.Dt VM_MAP_FIND 9 +.Os +.Sh NAME +.Nm vm_map_find +.Nd find a free region within a map, and optionally map a vm_object +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_find +.Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" +.Fa "vm_offset_t *addr" "vm_size_t length" "vm_offset_t max_addr" +.Fa "int find_space" "vm_prot_t prot" "vm_prot_t max" "int cow" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_find +function attempts to find a free region in the target +.Fa map , +with the given +.Fa length. +If a free region is found, +.Fn vm_map_find +creates a mapping of +.Fa object +via a call to +.Xr vm_map_insert 9 . +.Pp +The arguments +.Fa offset , +.Fa prot , +.Fa max , +and +.Fa cow +are passed unchanged to +.Xr vm_map_insert 9 +when creating the mapping, if and only if a free region is found. +.Pp +If +.Fa object +is +.Pf non- Dv NULL , +the reference count on the object must be incremented +by the caller before calling this function to account for the new entry. +.Pp +If +.Fa max_addr +is non-zero, +it specifies an upper bound on the mapping. +The mapping will only succeed if a free region can be found that resides +entirely below +.Fa max_addr . +.Pp +The +.Fa find_space +argument specifies the strategy to use when searching for a free region of +the requested length. +For all values other than +.Dv VMFS_NO_SPACE , +.Xr vm_map_findspace 9 +is called to locate a free region of the requested length with a starting +address at or above +.Fa *addr . +The following strategies are supported: +.Bl -tag -width "Dv VMFS_ALIGNED_SPACE Ns" +.It Dv VMFS_NO_SPACE +The mapping will only succeed if there is a free region of the requested +length at the given address +.Fa *addr . +.It Dv VMFS_ANY_SPACE +The mapping will succeed as long as there is a free region. +.It Dv VMFS_SUPER_SPACE +The mapping will succeed as long as there is a free region that begins on +a superpage boundary. +If +.Fa object +is +.Pf non- Dv NULL +and is already backed by superpages, +then the mapping will require a free region that aligns relative to the +existing superpages rather than one beginning on a superpage boundary. +.It Dv VMFS_OPTIMAL_SPACE +The mapping will succeed as long as there is a free region. +However, if +.Fa object +is +.Pf non- Dv NULL +and is already backed by superpages, +this strategy will attempt to find a free region aligned relative to +the existing superpages. +.It Dv VMFS_ALIGNED_SPACE Ns Pq Fa n +The mapping will succeed as long as there is a free region that aligns on +a +.Pf 2^ Fa n +boundary. +.El +.Sh IMPLEMENTATION NOTES +This function acquires a lock on +.Fa map +by calling +.Xr vm_map_lock 9 , +and holds it until the function returns. +.Pp +The search for a free region is defined to be first-fit, from the address +.Fa addr +onwards. +.Sh RETURN VALUES +The +.Fn vm_map_find +function returns +.Dv KERN_SUCCESS +if the mapping was successfully created. +If space could not be found or +.Fa find_space +was +.Dv VMFS_NO_SPACE +and the given address, +.Fa addr , +was already mapped, +.Dv KERN_NO_SPACE +will be returned. +If the discovered range turned out to be bogus, +.Dv KERN_INVALID_ADDRESS +will be returned. +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_findspace 9 , +.Xr vm_map_insert 9 , +.Xr vm_map_lock 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_find.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_findspace.9 =================================================================== --- user/imp/camdoc/vm_map_findspace.9 (nonexistent) +++ user/imp/camdoc/vm_map_findspace.9 (revision 296049) @@ -0,0 +1,78 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_FINDSPACE 9 +.Os +.Sh NAME +.Nm vm_map_findspace +.Nd find a free region within a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_findspace +.Fa "vm_map_t map" "vm_offset_t start" "vm_size_t length" "vm_offset_t *addr" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_findspace +function attempts to find a region with sufficient space in the +.Fa map +for an object of size +.Fa length +at the address +.Fa addr . +.Sh IMPLEMENTATION NOTES +It is the caller's responsibility to obtain a lock on the +.Fa map +using +.Xr vm_map_lock 9 +before calling this function. +.Pp +This routine may call +.Xr pmap_growkernel 9 +to grow the kernel's address space, if and only if the mapping is being +made within the kernel address space, and if insufficient space remains +in the +.Va kernel_map . +.Sh RETURN VALUES +The +.Fn vm_map_findspace +function returns the value 0 if successful, and +.Fa *addr +will contain the first virtual address in the found region; +otherwise, the value 1 is returned. +.Sh SEE ALSO +.Xr pmap_growkernel 9 , +.Xr vm_map 9 , +.Xr vm_map_entry_resize_free 9 , +.Xr vm_map_lock 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_findspace.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_inherit.9 =================================================================== --- user/imp/camdoc/vm_map_inherit.9 (nonexistent) +++ user/imp/camdoc/vm_map_inherit.9 (revision 296049) @@ -0,0 +1,85 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_INHERIT 9 +.Os +.Sh NAME +.Nm vm_map_inherit +.Nd set fork inheritance flags for a range within a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_inherit +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" +.Fa "vm_inherit_t new_inheritance" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_inherit +function sets the inheritance flags for the range +.Fa start +to +.Fa end +within the target +.Fa map +to the value +.Fa new_inheritance . +.Pp +The +.Fa new_inheritance +flag must have one of the values +.Dv VM_INHERIT_NONE , +.Dv VM_INHERIT_COPY , +or +.Dv VM_INHERIT_SHARE . +This affects how the map will be shared with child maps when the +associated process forks. +.Sh IMPLEMENTATION NOTES +The +.Fn vm_map_inherit +function obtains a lock on the +.Fa map +using +.Xr vm_map_lock 9 +for the duration of the function. +.Sh RETURN VALUES +The +.Fn vm_map_inherit +function returns +.Dv KERN_SUCCESS +if the inheritance flags could be set. +Otherwise, if the provided flags were invalid, +.Dv KERN_INVALID_ARGUMENT +will be returned. +.Sh SEE ALSO +.Xr fork 2 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_inherit.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_init.9 =================================================================== --- user/imp/camdoc/vm_map_init.9 (nonexistent) +++ user/imp/camdoc/vm_map_init.9 (revision 296049) @@ -0,0 +1,59 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_INIT 9 +.Os +.Sh NAME +.Nm vm_map_init +.Nd initialize a vm_map structure for process zero +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft void +.Fn vm_map_init "vm_map_t map" "vm_offset_t min" "vm_offset_t max" +.Sh DESCRIPTION +The +.Fn vm_map_init +function initializes the system map +.Fa map +by setting its upper and lower address bounds to +.Fa max +and +.Fa min +respectively. +.Pp +It also initializes the system map mutex. +.Sh IMPLEMENTATION NOTES +This routine is for internal use only. +It is called during early system initialization. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_init.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_insert.9 =================================================================== --- user/imp/camdoc/vm_map_insert.9 (nonexistent) +++ user/imp/camdoc/vm_map_insert.9 (revision 296049) @@ -0,0 +1,93 @@ +.\" +.\" 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 January 11, 2013 +.Dt VM_MAP_INSERT 9 +.Os +.Sh NAME +.Nm vm_map_insert +.Nd insert an object into a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_insert +.Fa "vm_map_t map" "vm_object_t object" "vm_ooffset_t offset" +.Fa "vm_offset_t start" "vm_offset_t end" "vm_prot_t prot" +.Fa "vm_prot_t max" "int cow" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_insert +function inserts a mapping for the entire vm_object +.Fa object +into the target map +.Fa map . +.Pp +The +.Fa offset +argument specifies the offset into the +.Fa object +at which to begin mapping. +The object's size should match that of the specified address range. +.Pp +The +.Fa start +and +.Fa end +arguments specify the bounds of the mapped object's window in the +address space of +.Fa map . +.Pp +The +.Fa cow +argument specifies the flags which should be propagated to the new entry, +for example, to indicate that this is a copy-on-write mapping. +.Sh IMPLEMENTATION NOTES +This function implicitly creates a new +.Vt vm_map_entry +by calling the internal function +.Fn vm_map_entry_create . +.Sh RETURN VALUES +The +.Fn vm_map_insert +function returns +.Dv KERN_SUCCESS +if the mapping could be made successfully. +.Pp +Otherwise, +.Dv KERN_INVALID_ADDRESS +will be returned if the start of the range could not be found, or +.Dv KERN_NO_SPACE +if the range was found to be part of an existing entry or if it +overlaps the end of the map. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_insert.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_lock.9 =================================================================== --- user/imp/camdoc/vm_map_lock.9 (nonexistent) +++ user/imp/camdoc/vm_map_lock.9 (revision 296049) @@ -0,0 +1,113 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_LOCK 9 +.Os +.Sh NAME +.Nm vm_map_lock , +.Nm vm_map_unlock , +.Nm vm_map_lock_read , +.Nm vm_map_unlock_read , +.Nm vm_map_trylock , +.Nm vm_map_trylock_read , +.Nm vm_map_lock_upgrade , +.Nm vm_map_lock_downgrade +.Nd vm_map locking macros +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft void +.Fn vm_map_lock "vm_map_t map" +.Ft void +.Fn vm_map_unlock "vm_map_t map" +.Ft void +.Fn vm_map_lock_read "vm_map_t map" +.Ft void +.Fn vm_map_unlock_read "vm_map_t map" +.Ft int +.Fn vm_map_trylock "vm_map_t map" +.Ft int +.Fn vm_map_trylock_read "vm_map_t map" +.Ft int +.Fn vm_map_lock_upgrade "vm_map_t map" +.Ft int +.Fn vm_map_lock_downgrade "vm_map_t map" +.Sh DESCRIPTION +The +.Fn vm_map_lock +macro obtains an exclusive lock on +.Fa map . +.Pp +The +.Fn vm_map_unlock +macro releases an exclusive lock on +.Fa map . +.Pp +The +.Fn vm_map_lock_read +macro obtains a read-lock on +.Fa map . +.Pp +The +.Fn vm_map_unlock_read +macro releases a read-lock on +.Fa map . +.Pp +The +.Fn vm_map_trylock +macro attempts to obtain an exclusive lock on +.Fa map . +It returns FALSE if the lock cannot be immediately acquired; +otherwise return TRUE with the lock acquired. +.Pp +The +.Fn vm_map_trylock_read +macro attempts to obtain a read-lock on +.Fa map . +It returns FALSE if the lock cannot be immediately acquired; +otherwise return TRUE with the lock acquired. +.Pp +The +.Fn vm_map_lock_upgrade +macro attempts to atomically upgrade a read-lock on +.Fa map +to an exclusive lock. +.Pp +The +.Fn vm_map_lock_downgrade +macro attempts to downgrade an exclusive lock on +.Fa map +to a read-lock. +.Sh IMPLEMENTATION NOTES +Currently, all of the locking macros implement their locks as sleep locks. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_lock.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_lookup.9 =================================================================== --- user/imp/camdoc/vm_map_lookup.9 (nonexistent) +++ user/imp/camdoc/vm_map_lookup.9 (revision 296049) @@ -0,0 +1,88 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_LOOKUP 9 +.Os +.Sh NAME +.Nm vm_map_lookup , +.Nm vm_map_lookup_done +.Nd lookup the vm_object backing a given virtual region +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_lookup +.Fa "vm_map_t *var_map" "vm_offset_t vaddr" "vm_prot_t fault_type" +.Fa "vm_map_entry_t *out_entry" "vm_object_t *object" "vm_pindex_t *pindex" +.Fa "vm_prot_t *out_prot" "boolean_t *wired" +.Fc +.Ft void +.Fn vm_map_lookup_done "vm_map_t map" "vm_map_entry_t entry" +.Sh DESCRIPTION +The +.Fn vm_map_lookup +function attempts to find the +.Vt vm_object , +page index and protection, for the given virtual address +.Fa vaddr , +in the map +.Fa var_map , +assuming a page fault of the type +.Fa fault_type +had occurred. +.Pp +Return values are guaranteed until +.Fn vm_map_lookup_done +is called to release the lock. +.Sh IMPLEMENTATION NOTES +The function +.Fn vm_map_lookup +acquires a read-lock on the map +.Fa *var_map , +but does not release it. +The caller should invoke +.Fn vm_map_lookup_done +in order to release this lock. +.Sh RETURN VALUES +The +.Fn vm_map_lookup +function returns +.Dv KERN_SUCCESS , +and sets the +.Fa *object , +.Fa *pindex , +.Fa *out_prot , +and +.Fa *out_entry +arguments appropriately for the hypothetical page fault. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_lookup.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_madvise.9 =================================================================== --- user/imp/camdoc/vm_map_madvise.9 (nonexistent) +++ user/imp/camdoc/vm_map_madvise.9 (revision 296049) @@ -0,0 +1,77 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_MADVISE 9 +.Os +.Sh NAME +.Nm vm_map_madvise +.Nd apply advice about use of memory to map entries +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_madvise +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int behav" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_madvise +function applies the flags +.Fa behav +to the entries within +.Fa map +between +.Fa start +and +.Fa end . +.Pp +Advisories are classified as either those affecting the +.Vt vm_map_entry +structure, or those affecting the underlying objects. +.Pp +The +.Fn vm_map_madvise +function is used by the +.Xr madvise 2 +system call. +.Sh RETURN VALUES +The +.Fn vm_map_madvise +function returns 0 if successful. +If the +.Fa behav +argument was not recognised, +.Dv KERN_INVALID_ARGUMENT +is returned. +.Sh SEE ALSO +.Xr madvise 2 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_madvise.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_max.9 =================================================================== --- user/imp/camdoc/vm_map_max.9 (nonexistent) +++ user/imp/camdoc/vm_map_max.9 (revision 296049) @@ -0,0 +1,66 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_MAX 9 +.Os +.Sh NAME +.Nm vm_map_max , +.Nm vm_map_min , +.Nm vm_map_pmap +.Nd return map properties +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft vm_offset_t +.Fn vm_map_max "vm_map_t map" +.Ft vm_offset_t +.Fn vm_map_min "vm_map_t map" +.Ft pmap_t +.Fn vm_map_pmap "vm_map_t map" +.Sh DESCRIPTION +The function +.Fn vm_map_max +returns the upper address bound of the map +.Fa map . +.Pp +The function +.Fn vm_map_min +returns the lower address bound of the map +.Fa map . +.Pp +The function +.Fn vm_map_pmap +returns a pointer to the physical map associated with the virtual map +.Fa map . +.Sh SEE ALSO +.Xr pmap 9 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_max.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_protect.9 =================================================================== --- user/imp/camdoc/vm_map_protect.9 (nonexistent) +++ user/imp/camdoc/vm_map_protect.9 (revision 296049) @@ -0,0 +1,93 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_PROTECT 9 +.Os +.Sh NAME +.Nm vm_map_protect +.Nd apply protection bits to a virtual memory region +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_protect +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_prot_t new_prot" +.Fa "boolean_t set_max" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_protect +function sets the protection bits of the address region bounded by +.Fa start +and +.Fa end +within the map +.Fa map +to +.Fa new_prot . +.Pp +If +.Fa set_max +is TRUE, +.Fa new_prot +is treated as the new +.Va max_protection +setting for each underlying entry. +Otherwise, only the +.Va protection +field is affected. +.Pp +The range MUST be contiguous, and MUST NOT contain sub-maps. +.Sh IMPLEMENTATION NOTES +The function acquires a lock on the +.Fa map +for the duration, by calling +.Xr vm_map_lock 9 . +.Sh RETURN VALUES +The +.Fn vm_map_protect +function returns +.Dv KERN_SUCCESS +if the protection bits could be set successfully. +.Pp +If a sub-map entry was encountered in the range, +.Dv KERN_INVALID_ARGUMENT +is returned. +If the value of +.Fa new_prot +would exceed +.Va max_protection +for an entry within the range, +.Dv KERN_PROTECTION_FAILURE +is returned. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_protect.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_remove.9 =================================================================== --- user/imp/camdoc/vm_map_remove.9 (nonexistent) +++ user/imp/camdoc/vm_map_remove.9 (revision 296049) @@ -0,0 +1,69 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_REMOVE 9 +.Os +.Sh NAME +.Nm vm_map_remove +.Nd remove a virtual address range from a map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fn vm_map_remove "vm_map_t map" "vm_offset_t start" "vm_offset_t end" +.Sh DESCRIPTION +The +.Fn vm_map_remove +function removes the given address range bounded by +.Fa start +and +.Fa end +from the target +.Fa map . +.Sh IMPLEMENTATION NOTES +This is the exported form of +.Xr vm_map_delete 9 +which may be called by consumers of the VM subsystem. +.Pp +The function calls +.Xr vm_map_lock 9 +to hold a lock on +.Fa map +for the duration of the function call. +.Sh RETURN VALUES +The +.Fn vm_map_remove +always returns +.Dv KERN_SUCCESS . +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_delete 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_remove.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_simplify_entry.9 =================================================================== --- user/imp/camdoc/vm_map_simplify_entry.9 (nonexistent) +++ user/imp/camdoc/vm_map_simplify_entry.9 (revision 296049) @@ -0,0 +1,61 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_SIMPLIFY_ENTRY 9 +.Os +.Sh NAME +.Nm vm_map_simplify_entry +.Nd simplify a +.Vt vm_map_entry +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft void +.Fn vm_map_simplify_entry "vm_map_t map" "vm_map_entry_t entry" +.Sh DESCRIPTION +The +.Fn vm_map_simplify_entry +function simplifies the given +.Fa entry +by merging with either neighbour. +The +.Fa map +must be locked upon entry. +.Pp +This function also has the ability to merge with both neighbours. +.Pp +This function guarantees that the passed entry remains valid, although +possibly extended. +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_insert 9 , +.Xr vm_map_remove 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_simplify_entry.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_stack.9 =================================================================== --- user/imp/camdoc/vm_map_stack.9 (nonexistent) +++ user/imp/camdoc/vm_map_stack.9 (revision 296049) @@ -0,0 +1,132 @@ +.\" +.\" 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 January 11, 2013 +.Dt VM_MAP_STACK 9 +.Os +.Sh NAME +.Nm vm_map_stack , +.Nm vm_map_growstack +.Nd manage process stacks +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_stack +.Fa "vm_map_t map" "vm_offset_t addrbos" "vm_size_t max_ssize" "vm_prot_t prot" +.Fa "vm_prot_t max" "int cow" +.Fc +.Ft int +.Fn vm_map_growstack "struct proc *p" "vm_offset_t addr" +.Sh DESCRIPTION +The +.Fn vm_map_stack +function maps a process stack for a new process image. +The stack is mapped +.Fa addrbos +in +.Fa map , +with a maximum size of +.Fa max_ssize . +Copy-on-write flags passed in +.Fa cow +are also applied to the new mapping. +Protection bits are supplied by +.Fa prot +and +.Fa max . +.Pp +It is typically called by +.Xr execve 2 . +.Pp +The +.Fn vm_map_growstack +function is responsible for growing a stack for the process +.Fa p +to the desired address +.Fa addr , +similar to the legacy +.Xr sbrk 2 +call. +.Sh IMPLEMENTATION NOTES +The +.Fn vm_map_stack +function calls +.Xr vm_map_insert 9 +to create its mappings. +.Pp +The +.Fn vm_map_stack +and +.Fn vm_map_growstack +functions acquire the process lock on +.Fa p +for the duration of the call. +.Sh RETURN VALUES +The +.Fn vm_map_stack +function returns +.Dv KERN_SUCCESS +if the mapping was allocated successfully. +.Pp +Otherwise, +if mapping the stack would exceed the process's VMEM resource limit, +or if the specified bottom-of-stack address is out of range for the map, +or if there is already a mapping at the address which would result, +or if +.Fa max_ssize +could not be accommodated within the current mapping, +.Dv KERN_NO_SPACE +is returned. +.Pp +Other possible return values for this function are documented in +.Xr vm_map_insert 9 . +.Pp +The +.Fn vm_map_growstack +function returns +.Dv KERN_SUCCESS +if +.Fa addr +is already mapped, or if the stack was grown successfully. +.Pp +It also returns +.Dv KERN_SUCCESS +if +.Fa addr +is outside the stack range; this is done in order to preserve +compatibility with the deprecated +.Fn grow +function previously located in the file +.Pa vm_machdep.c . +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_insert 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_stack.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_submap.9 =================================================================== --- user/imp/camdoc/vm_map_submap.9 (nonexistent) +++ user/imp/camdoc/vm_map_submap.9 (revision 296049) @@ -0,0 +1,95 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_SUBMAP 9 +.Os +.Sh NAME +.Nm vm_map_submap +.Nd create a subordinate map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_submap +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "vm_map_t submap" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_submap +function marks the range bounded by +.Fa start +and +.Fa end +within the map +.Fa map +as being handled by a subordinate map +.Fa sub_map . +.Pp +It is generally called by the kernel memory allocator. +.Sh IMPLEMENTATION NOTES +This function is for internal use only. +.Pp +Both maps must exist. +The range must have been created with +.Xr vm_map_find 9 +previously. +.Pp +No other operations may have been performed on this range +before calling this function. +Only the +.Fn vm_fault +operation may be performed within this range after calling +this function. +.Pp +To remove a submapping, one must first remove the range from +the parent +.Fa map , +and then destroy the +.Fa sub_map . +This procedure is not recommended. +.Sh RETURN VALUES +The +.Fn vm_map_submap +function returns +.Dv KERN_SUCCESS +if successful. +.Pp +Otherwise, it returns +.Dv KERN_INVALID_ARGUMENT +if the caller requested copy-on-write flags, +or if the range specified for the sub-map was out of range for the parent map, +or if a +.Dv NULL +backing object was specified. +.Sh SEE ALSO +.Xr vm_map 9 , +.Xr vm_map_find 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_submap.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_sync.9 =================================================================== --- user/imp/camdoc/vm_map_sync.9 (nonexistent) +++ user/imp/camdoc/vm_map_sync.9 (revision 296049) @@ -0,0 +1,81 @@ +.\" +.\" 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 July 9, 2011 +.Dt VM_MAP_SYNC 9 +.Os +.Sh NAME +.Nm vm_map_sync +.Nd push dirty pages to their pager +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fo vm_map_sync +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "boolean_t syncio" +.Fa "boolean_t invalidate" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_sync +function forces any dirty cached pages in the range +.Fa start +to +.Fa end +within the +.Fa map +to be pushed to their underlying pager. +.Pp +If +.Fa syncio +is TRUE, dirty pages are written synchronously. +.Pp +If +.Fa invalidate +is TRUE, any cached pages are also freed. +.Pp +The range provided must be contiguous, it MUST NOT contain holes. +The range provided MUST NOT contain any sub-map entries. +.Sh RETURN VALUES +The +.Fn vm_map_sync +function returns +.Dv KERN_SUCCESS +if successful. +.Pp +Otherwise, +.Dv KERN_INVALID_ADDRESS +will be returned if the function encountered a sub-map entry; +.Dv KERN_INVALID_ARGUMENT +will be returned if the function encountered a hole in the region provided, +or if an entry could not be found for the given start address. +.Sh SEE ALSO +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_sync.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_map_wire.9 =================================================================== --- user/imp/camdoc/vm_map_wire.9 (nonexistent) +++ user/imp/camdoc/vm_map_wire.9 (revision 296049) @@ -0,0 +1,114 @@ +.\" +.\" 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 July 19, 2003 +.Dt VM_MAP_WIRE 9 +.Os +.Sh NAME +.Nm vm_map_wire , +.Nm vm_map_unwire +.Nd manage page wiring within a virtual memory map +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_map.h +.Ft int +.Fn vm_map_wire "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int flags" +.Ft int +.Fo vm_map_unwire +.Fa "vm_map_t map" "vm_offset_t start" "vm_offset_t end" "int flags" +.Fc +.Sh DESCRIPTION +The +.Fn vm_map_wire +function is responsible for wiring pages in the range between +.Fa start +and +.Fa end +within the map +.Fa map . +Wired pages are locked into physical memory, and may not be paged out +as long as their wire count remains above zero. +.Pp +The +.Fn vm_map_unwire +function performs the corresponding unwire operation. +.Pp +The +.Fa flags +argument is a bit mask, consisting of the following flags: +.Pp +If the +.Dv VM_MAP_WIRE_USER +flag is set, the function operates within user address space. +.Pp +If the +.Dv VM_MAP_WIRE_HOLESOK +flag is set, it may operate upon an arbitrary range within the +address space of +.Fa map . +.Pp +If a contiguous range is desired, callers should explicitly express +their intent by specifying the +.Dv VM_MAP_WIRE_NOHOLES +flag. +.Sh IMPLEMENTATION NOTES +Both functions will attempt to acquire a lock on the map using +.Xr vm_map_lock 9 +and hold it for the duration of the call. +If they detect +.Dv MAP_ENTRY_IN_TRANSITION , +they will call +.Xr vm_map_unlock_and_wait 9 +until the map becomes available again. +.Pp +The map could have changed during this window as it was held by another +consumer, therefore consumers of this interface should check for this +condition using the return values below. +.Sh RETURN VALUES +The +.Fn vm_map_wire +and +.Fn vm_map_unwire +functions have identical return values. +The functions return +.Dv KERN_SUCCESS +if all pages within the range were [un]wired successfully. +.Pp +Otherwise, if the specified range was not valid, +or if the map changed while the +.Dv MAP_ENTRY_IN_TRANSITION +flag was set, +.Dv KERN_INVALID_ADDRESS +is returned. +.Sh SEE ALSO +.Xr mlockall 2 , +.Xr munlockall 2 , +.Xr vm_map 9 +.Sh AUTHORS +This manual page was written by +.An Bruce M Simpson Aq Mt bms@spc.org . Property changes on: user/imp/camdoc/vm_map_wire.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_aflag.9 =================================================================== --- user/imp/camdoc/vm_page_aflag.9 (nonexistent) +++ user/imp/camdoc/vm_page_aflag.9 (revision 296049) @@ -0,0 +1,100 @@ +.\" +.\" Copyright (C) 2001 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 August 31, 2011 +.Dt VM_PAGE_AFLAG 9 +.Os +.Sh NAME +.Nm vm_page_aflag_clear , vm_page_aflag_set , vm_page_reference +.Nd "change page atomic flags" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_aflag_clear "vm_page_t m" "uint8_t bits" +.Ft void +.Fn vm_page_aflag_set "vm_page_t m" "uint8_t bits" +.Ft void +.Fn vm_page_reference "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_aflag_clear +atomically clears the specified bits on the page's +.Va aflags . +.Pp +The +.Fn vm_page_aflag_set +atomically sets the specified bits on the page's +.Va aflags . +.Pp +The +.Fn vm_page_reference m +call is the same as +.Bd -literal -offset indent +vm_page_aflag_set(m, PGA_REFERENCED); +.Ed +.Lp +and is the recommended way to mark the page as referenced from +third-party kernel modules. +.Pp +These functions neither block nor require any locks to be held +around the calls for correctness. +.Pp +The functions arguments are: +.Bl -tag -width ".Fa bits" +.It Fa m +The page whose +.Va aflags +are updated. +.It Fa bits +The bits that are set or cleared on the page's flags. +.El +.Pp +The following +.Va aflags +can be set or cleared: +.Bl -tag -width ".Fa PGA_REFERENCED" +.It Fa PGA_REFERENCED +The bit may be set to indicate that the page has been recently accessed. +For instance, +.Xr pmap 9 +sets this bit to reflect the accessed attribute of the page mapping +typically updated by processor's memory management unit on the page access. +.It Fa PGA_WRITEABLE +A writeable mapping for the page may exist. +.El +.Pp +Both +.Dv PGA_REFERENCED +and +.Dv PGA_WRITEABLE +bits are only valid for the managed pages. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_aflag.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_alloc.9 =================================================================== --- user/imp/camdoc/vm_page_alloc.9 (nonexistent) +++ user/imp/camdoc/vm_page_alloc.9 (revision 296049) @@ -0,0 +1,139 @@ +.\" +.\" Copyright (C) 2001 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 January 28, 2012 +.Dt VM_PAGE_ALLOC 9 +.Os +.Sh NAME +.Nm vm_page_alloc +.Nd "allocate a page for a" +.Vt vm_object +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft vm_page_t +.Fn vm_page_alloc "vm_object_t object" "vm_pindex_t pindex" "int req" +.Sh DESCRIPTION +The +.Fn vm_page_alloc +function allocates a page at +.Fa pindex +within +.Fa object . +It is assumed that a page has not already been allocated at +.Fa pindex . +The page returned is inserted into the object, unless +.Dv VM_ALLOC_NOOBJ +is specified in the +.Fa req . +The page may exist in the vm object cache, in which case it will +be reactivated instead, moving from the cache into the object page list. +.Pp +.Fn vm_page_alloc +will not sleep. +.Pp +Its arguments are: +.Bl -tag -width ".Fa object" +.It Fa object +The VM object to allocate the page for. +The +.Fa object +must be locked if +.Dv VM_ALLOC_NOOBJ +is not specified. +.It Fa pindex +The index into the object at which the page should be inserted. +.It Fa req +The bitwise-inclusive OR of a class and any optional flags indicating +how the page should be allocated. +.Pp +Exactly one of the following classes must be specified: +.Bl -tag -width ".Dv VM_ALLOC_INTERRUPT" +.It Dv VM_ALLOC_NORMAL +The page should be allocated with no special treatment. +.It Dv VM_ALLOC_SYSTEM +The page can be allocated if the cache is empty and the free +page count is above the interrupt reserved water mark. +This flag should be used only when the system really needs the page. +.It Dv VM_ALLOC_INTERRUPT +.Fn vm_page_alloc +is being called during an interrupt. +A page will be returned successfully if the free page count is greater +than zero. +.El +.Pp +The optional flags are: +.Bl -tag -width ".Dv VM_ALLOC_IFNOTCACHED" +.It Dv VM_ALLOC_NOBUSY +The returned page will not be exclusive busy. +.It Dv VM_ALLOC_NODUMP +The returned page will not be included in any kernel core dumps +regardless of whether or not it is mapped in to KVA. +.It Dv VM_ALLOC_NOOBJ +Do not associate the allocated page with a vm object. +The +.Fa object +argument is ignored. +.It Dv VM_ALLOC_IFCACHED +Allocate the page only if it is cached. +Otherwise, return +.Dv NULL . +.It Dv VM_ALLOC_IFNOTCACHED +Only allocate the page if it is not cached in the +.Fa object . +If the page at the specified +.Fa pindex +is cached, NULL is returned instead. +.It Dv VM_ALLOC_SBUSY +The returned page will be shared busy. +.It Dv VM_ALLOC_WIRED +The returned page will be wired. +.It Dv VM_ALLOC_ZERO +Indicate a preference for a pre-zeroed page. +There is no guarantee that the returned page will be zeroed, but it +will have the +.Dv PG_ZERO +flag set if it is zeroed. +.El +.El +.Sh RETURN VALUES +The +.Vt vm_page_t +that was allocated is returned if successful; otherwise, +.Dv NULL +is returned. +.Sh NOTES +The pager process is always upgraded to +.Dv VM_ALLOC_SYSTEM +unless +.Dv VM_ALLOC_INTERRUPT +is set. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_alloc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_bits.9 =================================================================== --- user/imp/camdoc/vm_page_bits.9 (nonexistent) +++ user/imp/camdoc/vm_page_bits.9 (revision 296049) @@ -0,0 +1,167 @@ +.\" +.\" Copyright (C) 2001 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 December 1, 2001 +.Dt VM_PAGE_BITS 9 +.Os +.Sh NAME +.Nm vm_page_bits , +.Nm vm_page_set_validclean , +.Nm vm_page_clear_dirty , +.Nm vm_page_set_invalid , +.Nm vm_page_zero_invalid , +.Nm vm_page_is_valid , +.Nm vm_page_test_dirty , +.Nm vm_page_dirty , +.Nm vm_page_undirty +.Nd "manage page clean and dirty bits" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft int +.Fn vm_page_bits "int base" "int size" +.Ft void +.Fn vm_page_set_validclean "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_clear_dirty "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_set_invalid "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_zero_invalid "vm_page_t m" "boolean_t setvalid" +.Ft int +.Fn vm_page_is_valid "vm_page_t m" "int base" "int size" +.Ft void +.Fn vm_page_test_dirty "vm_page_t m" +.Ft void +.Fn vm_page_dirty "vm_page_t m" +.Ft void +.Fn vm_page_undirty "vm_page_t m" +.Sh DESCRIPTION +.Fn vm_page_bits +calculates the bits representing the +.Dv DEV_BSIZE +range of bytes between +.Fa base +and +.Fa size . +The byte range is expected to be within a single page, and if +.Fa size +is zero, no bits will be set. +.Pp +.Fn vm_page_set_validclean +flags the byte range between +.Fa base +and +.Fa size +as valid and clean. +The range is expected to be +.Dv DEV_BSIZE +aligned and no larger than +.Dv PAGE_SIZE . +If it is not properly aligned, any unaligned chunks of the +.Dv DEV_BSIZE +blocks at the beginning and end of the range will be zeroed. +.Pp +If +.Fa base +is zero and +.Fa size +is one page, the modified bit in the page map is cleared; as well, +the +.Dv VPO_NOSYNC +flag is cleared. +.Pp +.Fn vm_page_clear_dirty +clears the dirty bits within a page in the range between +.Fa base +and +.Fa size . +The bits representing the range are calculated by calling +.Fn vm_page_bits . +.Pp +.Fn vm_page_set_invalid +clears the bits in both the valid and dirty flags representing +the +.Dv DEV_BSIZE +blocks between +.Fa base +and +.Fa size +in the page. +The bits are calculated by calling +.Fn vm_page_bits . +As well as clearing the bits within the page, the generation +number within the object holding the page is incremented. +.Pp +.Fn vm_page_zero_invalid +zeroes all of the blocks within the page that are currently +flagged as invalid. +If +.Fa setvalid +is +.Dv TRUE , +all of the valid bits within the page are set. +.Pp +In some cases, such as NFS, the valid bits cannot be set +in order to maintain cache consistency. +.Pp +.Fn vm_page_is_valid +checks to determine if the all of the +.Dv DEV_BSIZE +blocks between +.Fa base +and +.Fa size +of the page are valid. +If +.Fa size +is zero and the page is entirely invalid +.Fn vm_page_is_valid +will return +.Dv TRUE , +in all other cases a size of zero will return +.Dv FALSE . +.Pp +.Fn vm_page_test_dirty +checks if a page has been modified via any of its physical maps, +and if so, flags the entire page as dirty. +.Fn vm_page_dirty +is called to modify the dirty bits. +.Pp +.Fn vm_page_dirty +flags the entire page as dirty. +It is expected that the page is not currently on the cache queue. +.Pp +.Fn vm_page_undirty +clears all of the dirty bits in a page. +.Sh NOTES +None of these functions are allowed to block. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_bits.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_cache.9 =================================================================== --- user/imp/camdoc/vm_page_cache.9 (nonexistent) +++ user/imp/camdoc/vm_page_cache.9 (revision 296049) @@ -0,0 +1,51 @@ +.\" +.\" Copyright (C) 2001 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 July 24, 2001 +.Dt VM_PAGE_CACHE 9 +.Os +.Sh NAME +.Nm vm_page_cache +.Nd "move a page onto the cache queue" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_cache "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_cache +function moves a page onto the cache queue, +and removes any protection that may be set on the page. +If the page is busy, wired or unmanaged then the move +to the cache queue will fail. +If the page is dirty the system will panic. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_cache.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_deactivate.9 =================================================================== --- user/imp/camdoc/vm_page_deactivate.9 (nonexistent) +++ user/imp/camdoc/vm_page_deactivate.9 (revision 296049) @@ -0,0 +1,50 @@ +.\" +.\" Copyright (C) 2001 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 July 24, 2001 +.Dt VM_PAGE_DEACTIVATE 9 +.Os +.Sh NAME +.Nm vm_page_deactivate +.Nd "deactivate a page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_deactivate "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_deactivate +function moves the given page to the inactive queue as long as it is +unmanaged and is not wired. +.Sh SEE ALSO +.Xr vm_page_wire 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_deactivate.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_dontneed.9 =================================================================== --- user/imp/camdoc/vm_page_dontneed.9 (nonexistent) +++ user/imp/camdoc/vm_page_dontneed.9 (revision 296049) @@ -0,0 +1,59 @@ +.\" +.\" Copyright (C) 2001 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 July 30, 2001 +.Dt VM_PAGE_DONTNEED 9 +.Os +.Sh NAME +.Nm vm_page_dontneed +.Nd "indicate that a page is not needed anymore" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_dontneed "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_dontneed +function advises the VM system that the given page is no longer +required. +If the page is already in the inactive queue or in the cache queue, this +function does nothing; otherwise the page is deactivated. +.Pp +Note that +.Fn vm_page_dontneed +does not necessarily deactivate a page, but instead implements an +algorithm that attempts to prevent small objects from having their +pages reused too quickly, and large objects from flushing smaller +ones from the queues as their pages are released. +.Sh SEE ALSO +.Xr vm_page_deactivate 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_dontneed.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_free.9 =================================================================== --- user/imp/camdoc/vm_page_free.9 (nonexistent) +++ user/imp/camdoc/vm_page_free.9 (revision 296049) @@ -0,0 +1,98 @@ +.\" +.\" Copyright (C) 2001 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 July 24, 2001 +.Dt VM_PAGE_FREE 9 +.Os +.Sh NAME +.Nm vm_page_free , +.Nm vm_page_free_toq , +.Nm vm_page_free_zero , +.Nm vm_page_try_to_free +.Nd "free a page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_free "vm_page_t m" +.Ft void +.Fn vm_page_free_toq "vm_page_t m" +.Ft void +.Fn vm_page_free_zero "vm_page_t m" +.Ft int +.Fn vm_page_try_to_free "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_free_toq +function moves a page into the free queue, and disassociates it from +its object. +If the page is held, wired, already free, or its busy count is not +zero, the system will panic. +If the +.Dv PG_ZERO +flag is set on the page, it is placed at the end of the free queue; +otherwise, it is placed at the front. +.Pp +If the page's object is of type +.Dv OBJT_VNODE +and it is the last page associated with the object, the underlying +vnode may be freed. +.Pp +The +.Fn vm_page_free +and +.Fn vm_page_free_zero +functions both call +.Fn vm_page_free_toq +to actually free the page, but +.Fn vm_page_free_zero +sets the +.Dv PG_ZERO +flag and +.Fn vm_page_free +clears the +.Dv PG_ZERO +flag prior to the call to +.Fn vm_page_free_toq . +.Pp +The +.Fn vm_page_try_to_free +function verifies that the page is not held, wired, busy or dirty, and +if so, marks the page as busy, drops any protection that may be set on +the page, and frees it. +.Sh RETURN VALUES +.Fn vm_page_try_to_free +returns 1 if it is able to free the page; otherwise, 0 is returned. +.Sh SEE ALSO +.Xr vm_page_busy 9 , +.Xr vm_page_hold 9 , +.Xr vm_page_wire 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_free.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_grab.9 =================================================================== --- user/imp/camdoc/vm_page_grab.9 (nonexistent) +++ user/imp/camdoc/vm_page_grab.9 (revision 296049) @@ -0,0 +1,84 @@ +.\" +.\" Copyright (C) 2001 Chad David . All rights reserved. +.\" Copyright (c) 2013 The FreeBSD Foundation +.\" +.\" Portions of this documentation were written by Konstantin Belousov +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(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 August 23, 2013 +.Dt VM_PAGE_GRAB 9 +.Os +.Sh NAME +.Nm vm_page_grab +.Nd "returns a page from an object" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft vm_page_t +.Fn vm_page_grab "vm_object_t object" "vm_pindex_t pindex" "int allocflags" +.Sh DESCRIPTION +The +.Fn vm_page_grab +function returns the page at +.Fa pindex +from the given object. +If the page exists and is busy, +.Fn vm_page_grab +will sleep while waiting for it. +If the page does not exist, it is allocated. +The function sleeps until the allocation request can be satisfied. +.Pp +The function requires the +.Fa object +to be locked on entry, and returns with the object locked. +If the +.Fn vm_page_grab +function sleeps for any reason, the object lock is temporary dropped. +.Pp +The +.Fn vm_page_grab +supports all of the flags supported by +.Xr vm_page_alloc 9 . +In addition, +.Fn vm_page_grab +supports the following flags: +.Bl -tag -width ".Dv VM_ALLOC_IGN_SBUSY" +.It Dv VM_ALLOC_IGN_SBUSY +When waiting for the busy state of the existing page to drain, +only test for exclusive busy; ignore the shared busy counter. +.El +.Sh RETURN VALUES +The +.Fn vm_page_grab +always returns the page. +.Sh SEE ALSO +.Xr vm_page_alloc 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_grab.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_hold.9 =================================================================== --- user/imp/camdoc/vm_page_hold.9 (nonexistent) +++ user/imp/camdoc/vm_page_hold.9 (revision 296049) @@ -0,0 +1,75 @@ +.\" +.\" Copyright (C) 2001 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 July 13, 2001 +.Dt VM_PAGE_HOLD 9 +.Os +.Sh NAME +.Nm vm_page_hold , +.Nm vm_page_unhold +.Nd "update a page's hold count" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_hold "vm_page_t m" +.Ft void +.Fn vm_page_unhold "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_hold +function increases the hold count on a page. +This prevents the page daemon from freeing the page. +.Pp +.Fn vm_page_hold +should only be used for very temporary wiring of a page, +as that page will not be considered for paging or +reallocation for as long as its hold count is greater +than zero. +Also note that while wired pages are removed from whatever +queue they are on, +.Fn vm_page_hold +does not affect the location of the page. +If it is on a queue prior to the call, it will still +be there afterward. +.Pp +If the page needs to be held for a long period of time, +.Xr vm_page_wire 9 +should be used. +.Pp +.Fn vm_page_unhold +function reduces the hold count on a page. +If the hold count is zero it is possible that the page will be freed by the +page daemon. +.Sh SEE ALSO +.Xr vm_page_unwire 9 , +.Xr vm_page_wire 9 +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_hold.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_insert.9 =================================================================== --- user/imp/camdoc/vm_page_insert.9 (nonexistent) +++ user/imp/camdoc/vm_page_insert.9 (revision 296049) @@ -0,0 +1,96 @@ +.\" +.\" Copyright (C) 2001 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 July 17, 2001 +.Dt VM_PAGE_INSERT 9 +.Os +.Sh NAME +.Nm vm_page_insert , +.Nm vm_page_remove +.Nd "add/remove page from an object" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_insert "vm_page_t m" "vm_object_t object" "vm_pindex_t pindex" +.Ft void +.Fn vm_page_remove "vm_page_t m" +.Sh DESCRIPTION +The +.Fn vm_page_insert +function adds a page to the given object at the given index. +The page is added to both the VM page hash table and to the +object's list of pages, but the hardware page tables are not updated. +In the case of a user page, it will be faulted in when it is +accessed. +If the page is a kernel page, the caller is expected to +handle adding the page to the kernel's pmap. +.Pp +If +.Dv PG_WRITEABLE +is set in the page's flags, +.Dv OBJ_WRITEABLE +and +.Dv OBJ_MIGHTBEDIRTY +are set in the object's flags. +.Pp +The +.Fn vm_page_remove +function removes the given page from its object, and from the +VM page hash table. +The page must be busy prior to this call, or the system will panic. +The pmap entry for the page is not removed by this function. +.Pp +The arguments to +.Fn vm_page_insert +are: +.Bl -tag -width ".Fa object" +.It Fa m +The page to add to the object. +.It Fa object +The object the page should be added to. +.It Fa pindex +The index into the object the page should be at. +.El +.Pp +The arguments to +.Fn vm_page_remove +are: +.Bl -tag -width ".Fa m" +.It Fa m +The page to remove. +.El +.Sh IMPLEMENTATION NOTES +The index of a page in a VM object is the byte index into the +same object truncated to a page boundary. +For example, if the page size is 4096 bytes, and the address +in the object is 81944, the page index is 20. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_insert.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_lookup.9 =================================================================== --- user/imp/camdoc/vm_page_lookup.9 (nonexistent) +++ user/imp/camdoc/vm_page_lookup.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" +.\" Copyright (C) 2001 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 July 13, 2001 +.Dt VM_PAGE_LOOKUP 9 +.Os +.Sh NAME +.Nm vm_page_lookup +.Nd "lookup a vm page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft vm_page_t +.Fn vm_page_lookup "vm_object_t object" "vm_pindex_t pindex" +.Sh DESCRIPTION +The +.Fn vm_page_lookup +function searches for a VM page given its VM object and index. +If the page is not found, +.Dv NULL +is returned. +Its arguments are: +.Bl -tag -width ".Fa object" +.It Fa object +The VM object to search on. +.It Fa pindex +The page index to search on. +.El +.Sh RETURN VALUES +A +.Vt vm_page_t +is returned if successful; otherwise, +.Dv NULL +is returned. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_lookup.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_rename.9 =================================================================== --- user/imp/camdoc/vm_page_rename.9 (nonexistent) +++ user/imp/camdoc/vm_page_rename.9 (revision 296049) @@ -0,0 +1,72 @@ +.\" +.\" Copyright (C) 2001 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 July 17, 2001 +.Dt VM_PAGE_RENAME 9 +.Os +.Sh NAME +.Nm vm_page_rename +.Nd "move a page" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fo vm_page_rename +.Fa "vm_page_t m" +.Fa "vm_object_t new_object" +.Fa "vm_pindex_t new_pindex" +.Fc +.Sh DESCRIPTION +The +.Fn vm_page_rename +function removes a page from one object, and adds it to another +at the given page index. +The page is added to the given object, and is removed from the +object that is currently associated with. +If the page is currently on the cache queue it will be deactivated +unless it is wired or unmanaged, in which case the deactivation will +fail. +The entire page is marked as dirty after the move. +.Pp +The arguments to +.Fn vm_page_rename +are: +.Bl -tag -width ".Fa new_object" +.It Fa m +The page to move. +.It Fa new_object +The object the page should be inserted into. +.It Fa new_pindex +The page index into +.Fa new_object +at which the new page should be inserted. +.El +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_rename.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_page_wire.9 =================================================================== --- user/imp/camdoc/vm_page_wire.9 (nonexistent) +++ user/imp/camdoc/vm_page_wire.9 (revision 296049) @@ -0,0 +1,67 @@ +.\" +.\" Copyright (C) 2001 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 July 13, 2001 +.Dt VM_PAGE_WIRE 9 +.Os +.Sh NAME +.Nm vm_page_wire , +.Nm vm_page_unwire +.Nd "wire and unwire pages" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_page_wire "vm_page_t m" +.Ft void +.Fn vm_page_unwire "vm_page_t m" "int activate" +.Sh DESCRIPTION +The +.Fn vm_page_wire +function increments the wire count on a page, and removes it from +whatever queue it is on. +.Pp +The +.Fn vm_page_unwire +function releases one of the wirings on the page. +When +.Va write_count +reaches zero the page is placed back onto either the active queue +(if +.Fa activate +is non-zero) or onto the inactive queue (if +.Fa activate +is zero). +If the page is unmanaged +.Dv ( PG_UNMANAGED +is set) then the page is left on +.Dv PQ_NONE . +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_page_wire.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vm_set_page_size.9 =================================================================== --- user/imp/camdoc/vm_set_page_size.9 (nonexistent) +++ user/imp/camdoc/vm_set_page_size.9 (revision 296049) @@ -0,0 +1,62 @@ +.\" +.\" Copyright (C) 2001 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 March 21, 2014 +.Dt VM_SET_PAGE_SIZE 9 +.Os +.Sh NAME +.Nm vm_set_page_size +.Nd "initialize the system page size" +.Sh SYNOPSIS +.In sys/param.h +.In vm/vm.h +.In vm/vm_page.h +.Ft void +.Fn vm_set_page_size void +.Sh DESCRIPTION +The +.Fn vm_set_page_size +function initializes the system page size. +If +.Va vm_cnt.v_page_size +(see +.In sys/vmmeter.h ) +equals 0, +.Dv PAGE_SIZE +is used; otherwise, the value stored in +.Va vm_cnt.v_page_size +is used. +If +.Va vm_cnt.v_page_size +is not a power of two, the system will panic. +.Pp +.Fn vm_set_page_size +must be called prior to any page size dependent functions. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vm_set_page_size.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vn_fullpath.9 =================================================================== --- user/imp/camdoc/vn_fullpath.9 (nonexistent) +++ user/imp/camdoc/vn_fullpath.9 (revision 296049) @@ -0,0 +1,125 @@ +.\" +.\" 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. +.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 . Property changes on: user/imp/camdoc/vn_fullpath.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vn_isdisk.9 =================================================================== --- user/imp/camdoc/vn_isdisk.9 (nonexistent) +++ user/imp/camdoc/vn_isdisk.9 (revision 296049) @@ -0,0 +1,73 @@ +.\" +.\" Copyright (C) 2001 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 July 9, 2001 +.Dt VN_ISDISK 9 +.Os +.Sh NAME +.Nm vn_isdisk +.Nd "checks if a vnode represents a disk" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vn_isdisk "struct vnode *vp" "int *errp" +.Sh DESCRIPTION +The +.Fn vn_isdisk +function checks to see if +.Fa vp +represents a disk. +In order for +.Fa vp +to be a disk, +it must be a character device, +.Va v_rdev +must be valid, and the +.Vt cdevsw +entry's +.Va flags +must have +.Dv D_DISK +set. +.Pp +Its arguments are: +.Bl -tag -width ".Fa errp" +.It Fa vp +The vnode to check. +.It Fa errp +An integer pointer to store the error number in if the call fails. +.El +.Sh RETURN VALUES +If the vnode represents a disk, 1 is returned; otherwise, 0 +is returned and +.Fa errp +will contain the error number. +.Sh AUTHORS +This manual page was written by +.An Chad David Aq Mt davidc@acns.ab.ca . Property changes on: user/imp/camdoc/vn_isdisk.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/watchdog.9 =================================================================== --- user/imp/camdoc/watchdog.9 (nonexistent) +++ user/imp/camdoc/watchdog.9 (revision 296049) @@ -0,0 +1,81 @@ +.\" +.\" Copyright (c) 2004 Poul-Henning Kamp +.\" 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 February 28, 2004 +.Dt WATCHDOG 9 +.Os +.Sh NAME +.Nm watchdog +.Nd "software and hardware watchdog facility" +.Sh SYNOPSIS +.In sys/watchdog.h +.Ft void +.Fn watchdog_fn "void *private" "u_int cmd" "int *error" +.Fn EVENTHANDLER_REGISTER watchdog_list watchdog_fn private 0 +.Fn EVENTHANDLER_DEREGISTER watchdog_list eventhandler_tag +.Sh DESCRIPTION +To implement a watchdog in software or hardware, only a single +function needs to be written and registered on the global +.Va watchdog_list . +.Pp +The function must examine the +.Fa cmd +argument and act on it as +follows: +.Pp +If +.Fa cmd +is zero, the watchdog must be disabled and the +.Fa error +argument left untouched. +If the watchdog cannot be disabled, the +.Fa error +argument must be set to +.Dv EOPNOTSUPP . +.Pp +Else the watchdog should be reset and configured to a timeout of +.Pq 1 << Pq Fa cmd No & Dv WD_INTERVAL +nanoseconds or larger and the +.Fa error +argument be set to zero to signal arming of a watchdog. +.Pp +If the watchdog cannot be configured to the proposed timeout, it +must be disabled and the +.Fa error +argument left as is (to avoid hiding the arming of another watchdog). +.Pp +There is no specification of what the watchdog should do when it +times out, but a hardware reset or similar +.Dq "drastic but certain" +behaviour is recommended. +.Sh SEE ALSO +.Xr watchdog 4 +.Sh AUTHORS +.An -nosplit +The +.Nm +facility and this manual page was written +.An Poul-Henning Kamp Aq Mt phk@FreeBSD.org . Property changes on: user/imp/camdoc/watchdog.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pget.9 =================================================================== --- user/imp/camdoc/pget.9 (nonexistent) +++ user/imp/camdoc/pget.9 (revision 296049) @@ -0,0 +1,107 @@ +.\" Copyright (c) 2011 Sergey Kandaurov +.\" 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 3, 2014 +.Dt PGET 9 +.Os +.Sh NAME +.Nm pget +.Nd locate a process by number +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft int +.Fn pget "pid_t pid" "int flags" "struct proc **pp" +.Sh DESCRIPTION +This function +takes a +.Fa pid +as its argument, +which can be either a process or thread id, +and fills a pointer to the +.Vt proc +structure in +.Fa *pp . +In the latter case, a process owning the specified thread is looked for. +The operation is performed by invoking the +.Xr pfind 9 +function. +The found process is returned locked. +For the +.Dv PGET_HOLD +case, it is returned unlocked (but held). +The +.Fn pget +function can +perform additional manipulations, depending on a +.Fa flags +argument. +.Pp +The +.Fa flags +argument is the logical OR of some subset of: +.Bl -tag -width ".Dv PGET_NOTINEXEC" +.It Dv PGET_HOLD +If set, the found process will be held and unlocked. +.It Dv PGET_CANSEE +If set, the found process will be checked for its visibility. +See +.Xr p_cansee 9 . +.It Dv PGET_CANDEBUG +If set, the found process will be checked for its debuggability. +See +.Xr p_candebug 9 . +.It Dv PGET_ISCURRENT +If set, the found process will be checked that it matches the current +process context. +.It Dv PGET_NOTWEXIT +If set, the found process will be checked that it does not have the process +flag +.Dv P_WEXIT +set. +.It Dv PGET_NOTINEXEC +If set, the found process will be checked that it does not have the process +flag +.Dv P_INEXEC +set. +.It Dv PGET_NOTID +If set, +.Fa pid +is not assumed as a thread id for values larger than +.Dv PID_MAX . +.It Dv PGET_WANTREAD +If set, the found process will be checked that the caller may get +a read access to its structure. +A shorthand for +.Pq Dv PGET_HOLD | PGET_CANDEBUG | PGET_NOTWEXIT . +.El +.Sh RETURN VALUES +If the process is found in the specified way, then zero is returned, +otherwise an appropriate error code is returned. +.Sh SEE ALSO +.Xr p_candebug 9 , +.Xr p_cansee 9 , +.Xr pfind 9 Property changes on: user/imp/camdoc/pget.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_dma.9 =================================================================== --- user/imp/camdoc/bus_dma.9 (nonexistent) +++ user/imp/camdoc/bus_dma.9 (revision 296049) @@ -0,0 +1,1059 @@ +.\" Copyright (c) 2002, 2003 Hiten M. Pandya. +.\" 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, CONTRIBUTORS OR THE +.\" VOICES IN HITEN PANDYA'S HEAD 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. +.\" +.\" Copyright (c) 1996, 1997, 1998, 2001 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility, +.\" NASA Ames Research Center. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" $NetBSD: bus_dma.9,v 1.25 2002/10/14 13:43:16 wiz Exp $ +.\" +.Dd July 17, 2013 +.Dt BUS_DMA 9 +.Os +.Sh NAME +.Nm bus_dma , +.Nm bus_dma_tag_create , +.Nm bus_dma_tag_destroy , +.Nm bus_dmamap_create , +.Nm bus_dmamap_destroy , +.Nm bus_dmamap_load , +.Nm bus_dmamap_load_bio , +.Nm bus_dmamap_load_ccb , +.Nm bus_dmamap_load_mbuf , +.Nm bus_dmamap_load_mbuf_sg , +.Nm bus_dmamap_load_uio , +.Nm bus_dmamap_unload , +.Nm bus_dmamap_sync , +.Nm bus_dmamem_alloc , +.Nm bus_dmamem_free +.Nd Bus and Machine Independent DMA Mapping Interface +.Sh SYNOPSIS +.In machine/bus.h +.Ft int +.Fn bus_dma_tag_create "bus_dma_tag_t parent" "bus_size_t alignment" \ +"bus_addr_t boundary" "bus_addr_t lowaddr" "bus_addr_t highaddr" \ +"bus_dma_filter_t *filtfunc" "void *filtfuncarg" "bus_size_t maxsize" \ +"int nsegments" "bus_size_t maxsegsz" "int flags" "bus_dma_lock_t *lockfunc" \ +"void *lockfuncarg" "bus_dma_tag_t *dmat" +.Ft int +.Fn bus_dma_tag_destroy "bus_dma_tag_t dmat" +.Ft int +.Fn bus_dmamap_create "bus_dma_tag_t dmat" "int flags" "bus_dmamap_t *mapp" +.Ft int +.Fn bus_dmamap_destroy "bus_dma_tag_t dmat" "bus_dmamap_t map" +.Ft int +.Fn bus_dmamap_load "bus_dma_tag_t dmat" "bus_dmamap_t map" "void *buf" \ +"bus_size_t buflen" "bus_dmamap_callback_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_bio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct bio *bio" "bus_dmamap_callback_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_ccb "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"union ccb *ccb" "bus_dmamap_callback_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_mbuf "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct mbuf *mbuf" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ +"int flags" +.Ft int +.Fn bus_dmamap_load_mbuf_sg "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct mbuf *mbuf" "bus_dma_segment_t *segs" "int *nsegs" "int flags" +.Ft int +.Fn bus_dmamap_load_uio "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"struct uio *uio" "bus_dmamap_callback2_t *callback" "void *callback_arg" \ +"int flags" +.Ft void +.Fn bus_dmamap_unload "bus_dma_tag_t dmat" "bus_dmamap_t map" +.Ft void +.Fn bus_dmamap_sync "bus_dma_tag_t dmat" "bus_dmamap_t map" \ +"op" +.Ft int +.Fn bus_dmamem_alloc "bus_dma_tag_t dmat" "void **vaddr" \ +"int flags" "bus_dmamap_t *mapp" +.Ft void +.Fn bus_dmamem_free "bus_dma_tag_t dmat" "void *vaddr" \ +"bus_dmamap_t map" +.Sh DESCRIPTION +Direct Memory Access (DMA) is a method of transferring data +without involving the CPU, thus providing higher performance. +A DMA transaction can be achieved between device to memory, +device to device, or memory to memory. +.Pp +The +.Nm +API is a bus, device, and machine-independent (MI) interface to +DMA mechanisms. +It provides the client with flexibility and simplicity by +abstracting machine dependent issues like setting up +DMA mappings, handling cache issues, bus specific features +and limitations. +.Sh STRUCTURES AND TYPES +.Bl -tag -width indent +.It Vt bus_dma_tag_t +A machine-dependent (MD) opaque type that describes the +characteristics of DMA transactions. +DMA tags are organized into a hierarchy, with each child +tag inheriting the restrictions of its parent. +This allows all devices along the path of DMA transactions +to contribute to the constraints of those transactions. +.It Vt bus_dma_filter_t +Client specified address filter having the format: +.Bl -tag -width indent +.It Ft int +.Fn "client_filter" "void *filtarg" "bus_addr_t testaddr" +.El +.Pp +Address filters can be specified during tag creation to allow +for devices whose DMA address restrictions cannot be specified +by a single window. +The +.Fa filtarg +argument is specified by the client during tag creation to be passed to all +invocations of the callback. +The +.Fa testaddr +argument contains a potential starting address of a DMA mapping. +The filter function operates on the set of addresses from +.Fa testaddr +to +.Ql trunc_page(testaddr) + PAGE_SIZE - 1 , +inclusive. +The filter function should return zero if any mapping in this range +can be accommodated by the device and non-zero otherwise. +.It Vt bus_dma_segment_t +A machine-dependent type that describes individual +DMA segments. +It contains the following fields: +.Bd -literal + bus_addr_t ds_addr; + bus_size_t ds_len; +.Ed +.Pp +The +.Fa ds_addr +field contains the device visible address of the DMA segment, and +.Fa ds_len +contains the length of the DMA segment. +Although the DMA segments returned by a mapping call will adhere to +all restrictions necessary for a successful DMA operation, some conversion +(e.g.\& a conversion from host byte order to the device's byte order) is +almost always required when presenting segment information to the device. +.It Vt bus_dmamap_t +A machine-dependent opaque type describing an individual mapping. +One map is used for each memory allocation that will be loaded. +Maps can be reused once they have been unloaded. +Multiple maps can be associated with one DMA tag. +While the value of the map may evaluate to +.Dv NULL +on some platforms under certain conditions, +it should never be assumed that it will be +.Dv NULL +in all cases. +.It Vt bus_dmamap_callback_t +Client specified callback for receiving mapping information resulting from +the load of a +.Vt bus_dmamap_t +via +.Fn bus_dmamap_load , +.Fn bus_dmamap_load_bio +or +.Fn bus_dmamap_load_ccb . +Callbacks are of the format: +.Bl -tag -width indent +.It Ft void +.Fn "client_callback" "void *callback_arg" "bus_dma_segment_t *segs" \ +"int nseg" "int error" +.El +.Pp +The +.Fa callback_arg +is the callback argument passed to dmamap load functions. +The +.Fa segs +and +.Fa nseg +arguments describe an array of +.Vt bus_dma_segment_t +structures that represent the mapping. +This array is only valid within the scope of the callback function. +The success or failure of the mapping is indicated by the +.Fa error +argument. +More information on the use of callbacks can be found in the +description of the individual dmamap load functions. +.It Vt bus_dmamap_callback2_t +Client specified callback for receiving mapping information resulting from +the load of a +.Vt bus_dmamap_t +via +.Fn bus_dmamap_load_uio +or +.Fn bus_dmamap_load_mbuf . +.Pp +Callback2s are of the format: +.Bl -tag -width indent +.It Ft void +.Fn "client_callback2" "void *callback_arg" "bus_dma_segment_t *segs" \ +"int nseg" "bus_size_t mapsize" "int error" +.El +.Pp +Callback2's behavior is the same as +.Vt bus_dmamap_callback_t +with the addition that the length of the data mapped is provided via +.Fa mapsize . +.It Vt bus_dmasync_op_t +Memory synchronization operation specifier. +Bus DMA requires explicit synchronization of memory with its device +visible mapping in order to guarantee memory coherency. +The +.Vt bus_dmasync_op_t +allows the type of DMA operation that will be or has been performed +to be communicated to the system so that the correct coherency measures +are taken. +The operations are represented as bitfield flags that can be combined together, +though it only makes sense to combine PRE flags or POST flags, not both. +See the +.Fn bus_dmamap_sync +description below for more details on how to use these operations. +.Pp +All operations specified below are performed from the host memory point of view, +where a read implies data coming from the device to the host memory, and a write +implies data going from the host memory to the device. +Alternatively, the operations can be thought of in terms of driver operations, +where reading a network packet or storage sector corresponds to a read operation +in +.Nm . +.Bl -tag -width ".Dv BUS_DMASYNC_POSTWRITE" +.It Dv BUS_DMASYNC_PREREAD +Perform any synchronization required prior to an update of host memory by the +device. +.It Dv BUS_DMASYNC_PREWRITE +Perform any synchronization required after an update of host memory by the CPU +and prior to device access to host memory. +.It Dv BUS_DMASYNC_POSTREAD +Perform any synchronization required after an update of host memory by the +device and prior to CPU access to host memory. +.It Dv BUS_DMASYNC_POSTWRITE +Perform any synchronization required after device access to host memory. +.El +.It Vt bus_dma_lock_t +Client specified lock/mutex manipulation method. +This will be called from +within busdma whenever a client lock needs to be manipulated. +In its current form, the function will be called immediately before +the callback for a DMA load operation that has been deferred with +.Dv BUS_DMA_LOCK +and immediately after with +.Dv BUS_DMA_UNLOCK . +If the load operation does not need to be deferred, then it +will not be called since the function loading the map should +be holding the appropriate locks. +This method is of the format: +.Bl -tag -width indent +.It Ft void +.Fn "lockfunc" "void *lockfunc_arg" "bus_dma_lock_op_t op" +.El +.Pp +The +.Fa lockfuncarg +argument is specified by the client during tag creation to be passed to all +invocations of the callback. +The +.Fa op +argument specifies the lock operation to perform. +.Pp +Two +.Vt lockfunc +implementations are provided for convenience. +.Fn busdma_lock_mutex +performs standard mutex operations on the sleep mutex provided via +.Fa lockfuncarg . +.Fn dflt_lock +will generate a system panic if it is called. +It is substituted into the tag when +.Fa lockfunc +is passed as +.Dv NULL +to +.Fn bus_dma_tag_create +and is useful for tags that should not be used with deferred load operations. +.It Vt bus_dma_lock_op_t +Operations to be performed by the client-specified +.Fn lockfunc . +.Bl -tag -width ".Dv BUS_DMA_UNLOCK" +.It Dv BUS_DMA_LOCK +Acquires and/or locks the client locking primitive. +.It Dv BUS_DMA_UNLOCK +Releases and/or unlocks the client locking primitive. +.El +.El +.Sh FUNCTIONS +.Bl -tag -width indent +.It Fn bus_dma_tag_create "parent" "alignment" "boundary" "lowaddr" \ +"highaddr" "*filtfunc" "*filtfuncarg" "maxsize" "nsegments" "maxsegsz" \ +"flags" "lockfunc" "lockfuncarg" "*dmat" +Allocates a device specific DMA tag, and initializes it according to +the arguments provided: +.Bl -tag -width ".Fa filtfuncarg" +.It Fa parent +Indicates restrictions between the parent bridge, CPU memory, and the +device. +Each device must use a master parent tag by calling +.Fn bus_get_dma_tag . +.It Fa alignment +Alignment constraint, in bytes, of any mappings created using this tag. +The alignment must be a power of 2. +Hardware that can DMA starting at any address would specify +.Em 1 +for byte alignment. +Hardware requiring DMA transfers to start on a multiple of 4K +would specify +.Em 4096 . +.It Fa boundary +Boundary constraint, in bytes, of the target DMA memory region. +The boundary indicates the set of addresses, all multiples of the +boundary argument, that cannot be crossed by a single +.Vt bus_dma_segment_t . +The boundary must be a power of 2 and must be no smaller than the +maximum segment size. +.Ql 0 +indicates that there are no boundary restrictions. +.It Fa lowaddr , highaddr +Bounds of the window of bus address space that +.Em cannot +be directly accessed by the device. +The window contains all addresses greater than +.Fa lowaddr +and less than or equal to +.Fa highaddr . +For example, a device incapable of DMA above 4GB, would specify a +.Fa highaddr +of +.Dv BUS_SPACE_MAXADDR +and a +.Fa lowaddr +of +.Dv BUS_SPACE_MAXADDR_32BIT . +Similarly a device that can only perform DMA to addresses below +16MB would specify a +.Fa highaddr +of +.Dv BUS_SPACE_MAXADDR +and a +.Fa lowaddr +of +.Dv BUS_SPACE_MAXADDR_24BIT . +Some implementations requires that some region of device visible +address space, overlapping available host memory, be outside the +window. +This area of +.Ql safe memory +is used to bounce requests that would otherwise conflict with +the exclusion window. +.It Fa filtfunc +Optional filter function (may be +.Dv NULL ) +to be called for any attempt to +map memory into the window described by +.Fa lowaddr +and +.Fa highaddr . +A filter function is only required when the single window described +by +.Fa lowaddr +and +.Fa highaddr +cannot adequately describe the constraints of the device. +The filter function will be called for every machine page +that overlaps the exclusion window. +.It Fa filtfuncarg +Argument passed to all calls to the filter function for this tag. +May be +.Dv NULL . +.It Fa maxsize +Maximum size, in bytes, of the sum of all segment lengths in a given +DMA mapping associated with this tag. +.It Fa nsegments +Number of discontinuities (scatter/gather segments) allowed +in a DMA mapped region. +If there is no restriction, +.Dv BUS_SPACE_UNRESTRICTED +may be specified. +.It Fa maxsegsz +Maximum size, in bytes, of a segment in any DMA mapped region associated +with +.Fa dmat . +.It Fa flags +Are as follows: +.Bl -tag -width ".Dv BUS_DMA_ALLOCNOW" +.It Dv BUS_DMA_ALLOCNOW +Pre-allocate enough resources to handle at least one map load operation on +this tag. +If sufficient resources are not available, +.Er ENOMEM +is returned. +This should not be used for tags that only describe buffers that will be +allocated with +.Fn bus_dmamem_alloc . +Also, due to resource sharing with other tags, this flag does not guarantee +that resources will be allocated or reserved exclusively for this tag. +It should be treated only as a minor optimization. +.El +.It Fa lockfunc +Optional lock manipulation function (may be +.Dv NULL ) +to be called when busdma +needs to manipulate a lock on behalf of the client. +If +.Dv NULL +is specified, +.Fn dflt_lock +is used. +.It Fa lockfuncarg +Optional argument to be passed to the function specified by +.Fa lockfunc . +.It Fa dmat +Pointer to a bus_dma_tag_t where the resulting DMA tag will +be stored. +.El +.Pp +Returns +.Er ENOMEM +if sufficient memory is not available for tag creation +or allocating mapping resources. +.It Fn bus_dma_tag_destroy "dmat" +Deallocate the DMA tag +.Fa dmat +that was created by +.Fn bus_dma_tag_create . +.Pp +Returns +.Er EBUSY +if any DMA maps remain associated with +.Fa dmat +or +.Ql 0 +on success. +.It Fn bus_dmamap_create "dmat" "flags" "*mapp" +Allocates and initializes a DMA map. +Arguments are as follows: +.Bl -tag -width ".Fa nsegments" +.It Fa dmat +DMA tag. +.It Fa flags +Are as follows: +.Bl -tag -width ".Dv BUS_DMA_COHERENT" +.It Dv BUS_DMA_COHERENT +Attempt to map the memory loaded with this map such that cache sync +operations are as cheap as possible. +This flag is typically set on maps when the memory loaded with these will +be accessed by both a CPU and a DMA engine, frequently such as control data +and as opposed to streamable data such as receive and transmit buffers. +Use of this flag does not remove the requirement of using +.Fn bus_dmamap_sync , +but it may reduce the cost of performing these operations. +For +.Fn bus_dmamap_create , +the +.Dv BUS_DMA_COHERENT +flag is currently implemented on sparc64. +.El +.It Fa mapp +Pointer to a +.Vt bus_dmamap_t +where the resulting DMA map will be stored. +.El +.Pp +Returns +.Er ENOMEM +if sufficient memory is not available for creating the +map or allocating mapping resources. +.It Fn bus_dmamap_destroy "dmat" "map" +Frees all resources associated with a given DMA map. +Arguments are as follows: +.Bl -tag -width ".Fa dmat" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +The DMA map to destroy. +.El +.Pp +Returns +.Er EBUSY +if a mapping is still active for +.Fa map . +.It Fn bus_dmamap_load "dmat" "map" "buf" "buflen" "*callback" \ +"callback_arg" "flags" +Creates a mapping in device visible address space of +.Fa buflen +bytes of +.Fa buf , +associated with the DMA map +.Fa map . +This call will always return immediately and will not block for any reason. +Arguments are as follows: +.Bl -tag -width ".Fa buflen" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +A DMA map without a currently active mapping. +.It Fa buf +A kernel virtual address pointer to a contiguous (in KVA) buffer, to be +mapped into device visible address space. +.It Fa buflen +The size of the buffer. +.It Fa callback Fa callback_arg +The callback function, and its argument. +This function is called once sufficient mapping resources are available for +the DMA operation. +If resources are temporarily unavailable, this function will be deferred until +later, but the load operation will still return immediately to the caller. +Thus, callers should not assume that the callback will be called before the +load returns, and code should be structured appropriately to handle this. +See below for specific flags and error codes that control this behavior. +.It Fa flags +Are as follows: +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" +.It Dv BUS_DMA_NOWAIT +The load should not be deferred in case of insufficient mapping resources, +and instead should return immediately with an appropriate error. +.It Dv BUS_DMA_NOCACHE +The generated transactions to and from the virtual page are non-cacheable. +For +.Fn bus_dmamap_load , +the +.Dv BUS_DMA_NOCACHE +flag is currently implemented on sparc64. +.El +.El +.Pp +Return values to the caller are as follows: +.Bl -tag -width ".Er EINPROGRESS" +.It 0 +The callback has been called and completed. +The status of the mapping has been delivered to the callback. +.It Er EINPROGRESS +The mapping has been deferred for lack of resources. +The callback will be called as soon as resources are available. +Callbacks are serviced in FIFO order. +.Pp +Note that subsequent load operations for the same tag that do not require +extra resources will still succeed. +This may result in out-of-order processing of requests. +If the caller requires the order of requests to be preserved, +then the caller is required to stall subsequent requests until a pending +request's callback is invoked. +.It Er ENOMEM +The load request has failed due to insufficient resources, and the caller +specifically used the +.Dv BUS_DMA_NOWAIT +flag. +.It Er EINVAL +The load request was invalid. +The callback has been called and has been provided the same error. +This error value may indicate that +.Fa dmat , +.Fa map , +.Fa buf , +or +.Fa callback +were invalid, or +.Fa buflen +was larger than the +.Fa maxsize +argument used to create the dma tag +.Fa dmat . +.El +.Pp +When the callback is called, it is presented with an error value +indicating the disposition of the mapping. +Error may be one of the following: +.Bl -tag -width ".Er EINPROGRESS" +.It 0 +The mapping was successful and the +.Fa dm_segs +callback argument contains an array of +.Vt bus_dma_segment_t +elements describing the mapping. +This array is only valid during the scope of the callback function. +.It Er EFBIG +A mapping could not be achieved within the segment constraints provided +in the tag even though the requested allocation size was less than maxsize. +.El +.It Fn bus_dmamap_load_bio "dmat" "map" "bio" "callback" "callback_arg" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps buffers pointed to by +.Fa bio +for DMA transfers. +.Fa bio +may point to either a mapped or unmapped buffer. +.It Fn bus_dmamap_load_ccb "dmat" "map" "ccb" "callback" "callback_arg" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps data pointed to by +.Fa ccb +for DMA transfers. +The data for +.Fa ccb +may be any of the following types: +.Bl -tag -width ".Er CAM_DATA_SG_PADDR" +.It CAM_DATA_VADDR +The data is a single KVA buffer. +.It CAM_DATA_PADDR +The data is a single bus address range. +.It CAM_DATA_SG +The data is a scatter/gather list of KVA buffers. +.It CAM_DATA_SG_PADDR +The data is a scatter/gather list of bus address ranges. +.It CAM_DATA_BIO +The data is contained in a +.Vt struct bio +attached to the CCB. +.El +.Pp +.Fn bus_dmamap_load_ccb +supports the following CCB XPT function codes: +.Pp +.Bl -item -offset indent -compact +.It +XPT_ATA_IO +.It +XPT_CONT_TARGET_IO +.It +XPT_SCSI_IO +.El +.It Fn bus_dmamap_load_mbuf "dmat" "map" "mbuf" "callback2" "callback_arg" \ +"flags" +This is a variation of +.Fn bus_dmamap_load +which maps mbuf chains +for DMA transfers. +A +.Vt bus_size_t +argument is also passed to the callback routine, which +contains the mbuf chain's packet header length. +The +.Dv BUS_DMA_NOWAIT +flag is implied, thus no callback deferral will happen. +.Pp +Mbuf chains are assumed to be in kernel virtual address space. +.Pp +Beside the error values listed for +.Fn bus_dmamap_load , +.Er EINVAL +will be returned if the size of the mbuf chain exceeds the maximum limit of the +DMA tag. +.It Fn bus_dmamap_load_mbuf_sg "dmat" "map" "mbuf" "segs" "nsegs" "flags" +This is just like +.Fn bus_dmamap_load_mbuf +except that it returns immediately without calling a callback function. +It is provided for efficiency. +The scatter/gather segment array +.Va segs +is provided by the caller and filled in directly by the function. +The +.Va nsegs +argument is returned with the number of segments filled in. +Returns the same errors as +.Fn bus_dmamap_load_mbuf . +.It Fn bus_dmamap_load_uio "dmat" "map" "uio" "callback2" "callback_arg" "flags" +This is a variation of +.Fn bus_dmamap_load +which maps buffers pointed to by +.Fa uio +for DMA transfers. +A +.Vt bus_size_t +argument is also passed to the callback routine, which contains the size of +.Fa uio , +i.e. +.Fa uio->uio_resid . +The +.Dv BUS_DMA_NOWAIT +flag is implied, thus no callback deferral will happen. +Returns the same errors as +.Fn bus_dmamap_load . +.Pp +If +.Fa uio->uio_segflg +is +.Dv UIO_USERSPACE , +then it is assumed that the buffer, +.Fa uio +is in +.Fa "uio->uio_td->td_proc" Ns 's +address space. +User space memory must be in-core and wired prior to attempting a map +load operation. +Pages may be locked using +.Xr vslock 9 . +.It Fn bus_dmamap_unload "dmat" "map" +Unloads a DMA map. +Arguments are as follows: +.Bl -tag -width ".Fa dmam" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +The DMA map that is to be unloaded. +.El +.Pp +.Fn bus_dmamap_unload +will not perform any implicit synchronization of DMA buffers. +This must be done explicitly by a call to +.Fn bus_dmamap_sync +prior to unloading the map. +.It Fn bus_dmamap_sync "dmat" "map" "op" +Performs synchronization of a device visible mapping with the CPU visible +memory referenced by that mapping. +Arguments are as follows: +.Bl -tag -width ".Fa dmat" +.It Fa dmat +DMA tag used to allocate +.Fa map . +.It Fa map +The DMA mapping to be synchronized. +.It Fa op +Type of synchronization operation to perform. +See the definition of +.Vt bus_dmasync_op_t +for a description of the acceptable values for +.Fa op . +.El +.Pp +The +.Fn bus_dmamap_sync +function +is the method used to ensure that CPU's and device's direct +memory access (DMA) to shared +memory is coherent. +For example, the CPU might be used to set up the contents of a buffer +that is to be made available to a device. +To ensure that the data are visible via the device's mapping of that +memory, the buffer must be loaded and a DMA sync operation of +.Dv BUS_DMASYNC_PREWRITE +must be performed after the CPU has updated the buffer and before the device +access is initiated. +If the CPU modifies this buffer again later, another +.Dv BUS_DMASYNC_PREWRITE +sync operation must be performed before an additional device +access. +Conversely, suppose a device updates memory that is to be read by a CPU. +In this case, the buffer must be loaded, and a DMA sync operation of +.Dv BUS_DMASYNC_PREREAD +must be performed before the device access is initiated. +The CPU will only be able to see the results of this memory update +once the DMA operation has completed and a +.Dv BUS_DMASYNC_POSTREAD +sync operation has been performed. +.Pp +If read and write operations are not preceded and followed by the +appropriate synchronization operations, behavior is undefined. +.It Fn bus_dmamem_alloc "dmat" "**vaddr" "flags" "*mapp" +Allocates memory that is mapped into KVA at the address returned +in +.Fa vaddr +and that is permanently loaded into the newly created +.Vt bus_dmamap_t +returned via +.Fa mapp . +Arguments are as follows: +.Bl -tag -width ".Fa alignment" +.It Fa dmat +DMA tag describing the constraints of the DMA mapping. +.It Fa vaddr +Pointer to a pointer that will hold the returned KVA mapping of +the allocated region. +.It Fa flags +Flags are defined as follows: +.Bl -tag -width ".Dv BUS_DMA_NOWAIT" +.It Dv BUS_DMA_WAITOK +The routine can safely wait (sleep) for resources. +.It Dv BUS_DMA_NOWAIT +The routine is not allowed to wait for resources. +If resources are not available, +.Dv ENOMEM +is returned. +.It Dv BUS_DMA_COHERENT +Attempt to map this memory in a coherent fashion. +See +.Fn bus_dmamap_create +above for a description of this flag. +For +.Fn bus_dmamem_alloc , +the +.Dv BUS_DMA_COHERENT +flag is currently implemented on arm and sparc64. +.It Dv BUS_DMA_ZERO +Causes the allocated memory to be set to all zeros. +.It Dv BUS_DMA_NOCACHE +The allocated memory will not be cached in the processor caches. +All memory accesses appear on the bus and are executed +without reordering. +For +.Fn bus_dmamem_alloc , +the +.Dv BUS_DMA_NOCACHE +flag is currently implemented on amd64 and i386 where it results in the +Strong Uncacheable PAT to be set for the allocated virtual address range. +.El +.It Fa mapp +Pointer to a +.Vt bus_dmamap_t +where the resulting DMA map will be stored. +.El +.Pp +The size of memory to be allocated is +.Fa maxsize +as specified in the call to +.Fn bus_dma_tag_create +for +.Fa dmat . +.Pp +The current implementation of +.Fn bus_dmamem_alloc +will allocate all requests as a single segment. +.Pp +An initial load operation is required to obtain the bus address of the allocated +memory, and an unload operation is required before freeing the memory, as +described below in +.Fn bus_dmamem_free . +Maps are automatically handled by this function and should not be explicitly +allocated or destroyed. +.Pp +Although an explicit load is not required for each access to the memory +referenced by the returned map, the synchronization requirements +as described in the +.Fn bus_dmamap_sync +section still apply and should be used to achieve portability on architectures +without coherent buses. +.Pp +Returns +.Er ENOMEM +if sufficient memory is not available for completing +the operation. +.It Fn bus_dmamem_free "dmat" "*vaddr" "map" +Frees memory previously allocated by +.Fn bus_dmamem_alloc . +Any mappings +will be invalidated. +Arguments are as follows: +.Bl -tag -width ".Fa vaddr" +.It Fa dmat +DMA tag. +.It Fa vaddr +Kernel virtual address of the memory. +.It Fa map +DMA map to be invalidated. +.El +.El +.Sh RETURN VALUES +Behavior is undefined if invalid arguments are passed to +any of the above functions. +If sufficient resources cannot be allocated for a given +transaction, +.Er ENOMEM +is returned. +All +routines that are not of type +.Vt void +will return 0 on success or an error +code on failure as discussed above. +.Pp +All +.Vt void +routines will succeed if provided with valid arguments. +.Sh LOCKING +Two locking protocols are used by +.Nm . +The first is a private global lock that is used to synchronize access to the +bounce buffer pool on the architectures that make use of them. +This lock is strictly a leaf lock that is only used internally to +.Nm +and is not exposed to clients of the API. +.Pp +The second protocol involves protecting various resources stored in the tag. +Since almost all +.Nm +operations are done through requests from the driver that created the tag, +the most efficient way to protect the tag resources is through the lock that +the driver uses. +In cases where +.Nm +acts on its own without being called by the driver, the lock primitive +specified in the tag is acquired and released automatically. +An example of this is when the +.Fn bus_dmamap_load +callback function is called from a deferred context instead of the driver +context. +This means that certain +.Nm +functions must always be called with the same lock held that is specified in the +tag. +These functions include: +.Pp +.Bl -item -offset indent -compact +.It +.Fn bus_dmamap_load +.It +.Fn bus_dmamap_load_bio +.It +.Fn bus_dmamap_load_ccb +.It +.Fn bus_dmamap_load_mbuf +.It +.Fn bus_dmamap_load_mbuf_sg +.It +.Fn bus_dmamap_load_uio +.It +.Fn bus_dmamap_unload +.It +.Fn bus_dmamap_sync +.El +.Pp +There is one exception to this rule. +It is common practice to call some of these functions during driver start-up +without any locks held. +So long as there is a guarantee of no possible concurrent use of the tag by +different threads during this operation, it is safe to not hold a lock for +these functions. +.Pp +Certain +.Nm +operations should not be called with the driver lock held, either because +they are already protected by an internal lock, or because they might sleep +due to memory or resource allocation. +The following functions must not be +called with any non-sleepable locks held: +.Pp +.Bl -item -offset indent -compact +.It +.Fn bus_dma_tag_create +.It +.Fn bus_dmamap_create +.It +.Fn bus_dmamem_alloc +.El +.Pp +All other functions do not have a locking protocol and can thus be +called with or without any system or driver locks held. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 , +.Xr driver 9 , +.Xr rman 9 , +.Xr vslock 9 +.Pp +.Rs +.%A "Jason R. Thorpe" +.%T "A Machine-Independent DMA Framework for NetBSD" +.%J "Proceedings of the Summer 1998 USENIX Technical Conference" +.%Q "USENIX Association" +.%D "June 1998" +.Re +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 1.3 . +.Pp +The +.Nm +API was adopted from +.Nx +for use in the CAM SCSI subsystem. +The alterations to the original API were aimed to remove the need for +a +.Vt bus_dma_segment_t +array stored in each +.Vt bus_dmamap_t +while allowing callers to queue up on scarce resources. +.Sh AUTHORS +The +.Nm +interface was designed and implemented by +.An Jason R. Thorpe +of the Numerical Aerospace Simulation Facility, NASA Ames Research Center. +Additional input on the +.Nm +design was provided by +.An -nosplit +.An Chris Demetriou , +.An Charles Hannum , +.An Ross Harvey , +.An Matthew Jacob , +.An Jonathan Stone , +and +.An Matt Thomas . +.Pp +The +.Nm +interface in +.Fx +benefits from the contributions of +.An Justin T. Gibbs , +.An Peter Wemm , +.An Doug Rabson , +.An Matthew N. Dodd , +.An Sam Leffler , +.An Maxime Henrion , +.An Jake Burkholder , +.An Takahashi Yoshihiro , +.An Scott Long +and many others. +.Pp +This manual page was written by +.An Hiten M. Pandya +and +.An Justin T. Gibbs . Property changes on: user/imp/camdoc/bus_dma.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_space.9 =================================================================== --- user/imp/camdoc/bus_space.9 (nonexistent) +++ user/imp/camdoc/bus_space.9 (revision 296049) @@ -0,0 +1,1715 @@ +.\" $NetBSD: bus_space.9,v 1.9 1999/03/06 22:09:29 mycroft Exp $ +.\" +.\" Copyright (c) 2005 M. Warner Losh. 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 NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.\" Copyright (c) 1997 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Christopher G. Demetriou. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 13, 2005 +.Dt BUS_SPACE 9 +.Os +.Sh NAME +.Nm bus_space , +.Nm bus_space_barrier , +.Nm bus_space_copy_region_1 , +.Nm bus_space_copy_region_2 , +.Nm bus_space_copy_region_4 , +.Nm bus_space_copy_region_8 , +.Nm bus_space_copy_region_stream_1 , +.Nm bus_space_copy_region_stream_2 , +.Nm bus_space_copy_region_stream_4 , +.Nm bus_space_copy_region_stream_8 , +.Nm bus_space_free , +.Nm bus_space_map , +.Nm bus_space_read_1 , +.Nm bus_space_read_2 , +.Nm bus_space_read_4 , +.Nm bus_space_read_8 , +.Nm bus_space_read_multi_1 , +.Nm bus_space_read_multi_2 , +.Nm bus_space_read_multi_4 , +.Nm bus_space_read_multi_8 , +.Nm bus_space_read_multi_stream_1 , +.Nm bus_space_read_multi_stream_2 , +.Nm bus_space_read_multi_stream_4 , +.Nm bus_space_read_multi_stream_8 , +.Nm bus_space_read_region_1 , +.Nm bus_space_read_region_2 , +.Nm bus_space_read_region_4 , +.Nm bus_space_read_region_8 , +.Nm bus_space_read_region_stream_1 , +.Nm bus_space_read_region_stream_2 , +.Nm bus_space_read_region_stream_4 , +.Nm bus_space_read_region_stream_8 , +.Nm bus_space_read_stream_1 , +.Nm bus_space_read_stream_2 , +.Nm bus_space_read_stream_4 , +.Nm bus_space_read_stream_8 , +.Nm bus_space_set_multi_1 , +.Nm bus_space_set_multi_2 , +.Nm bus_space_set_multi_4 , +.Nm bus_space_set_multi_8 , +.Nm bus_space_set_multi_stream_1 , +.Nm bus_space_set_multi_stream_2 , +.Nm bus_space_set_multi_stream_4 , +.Nm bus_space_set_multi_stream_8 , +.Nm bus_space_set_region_1 , +.Nm bus_space_set_region_2 , +.Nm bus_space_set_region_4 , +.Nm bus_space_set_region_8 , +.Nm bus_space_set_region_stream_1 , +.Nm bus_space_set_region_stream_2 , +.Nm bus_space_set_region_stream_4 , +.Nm bus_space_set_region_stream_8 , +.Nm bus_space_subregion , +.Nm bus_space_unmap , +.Nm bus_space_write_1 , +.Nm bus_space_write_2 , +.Nm bus_space_write_4 , +.Nm bus_space_write_8 , +.Nm bus_space_write_multi_1 , +.Nm bus_space_write_multi_2 , +.Nm bus_space_write_multi_4 , +.Nm bus_space_write_multi_8 , +.Nm bus_space_write_multi_stream_1 , +.Nm bus_space_write_multi_stream_2 , +.Nm bus_space_write_multi_stream_4 , +.Nm bus_space_write_multi_stream_8 , +.Nm bus_space_write_region_1 , +.Nm bus_space_write_region_2 , +.Nm bus_space_write_region_4 , +.Nm bus_space_write_region_8 , +.Nm bus_space_write_region_stream_1 , +.Nm bus_space_write_region_stream_2 , +.Nm bus_space_write_region_stream_4 , +.Nm bus_space_write_region_stream_8 , +.Nm bus_space_write_stream_1 , +.Nm bus_space_write_stream_2 , +.Nm bus_space_write_stream_4 , +.Nm bus_space_write_stream_8 +.Nd "bus space manipulation functions" +.Sh SYNOPSIS +.In machine/bus.h +.Ft int +.Fo bus_space_map +.Fa "bus_space_tag_t space" "bus_addr_t address" +.Fa "bus_size_t size" "int flags" "bus_space_handle_t *handlep" +.Fc +.Ft void +.Fo bus_space_unmap +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size" +.Fc +.Ft int +.Fo bus_space_subregion +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "bus_size_t size" "bus_space_handle_t *nhandlep" +.Fc +.Ft int +.Fo bus_space_alloc +.Fa "bus_space_tag_t space" "bus_addr_t reg_start" "bus_addr_t reg_end" +.Fa "bus_size_t size" "bus_size_t alignment" "bus_size_t boundary" +.Fa "int flags" "bus_addr_t *addrp" "bus_space_handle_t *handlep" +.Fc +.Ft void +.Fo bus_space_free +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t size" +.Fc +.Ft uint8_t +.Fo bus_space_read_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint16_t +.Fo bus_space_read_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint32_t +.Fo bus_space_read_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint64_t +.Fo bus_space_read_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint8_t +.Fo bus_space_read_stream_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint16_t +.Fo bus_space_read_stream_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint32_t +.Fo bus_space_read_stream_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft uint64_t +.Fo bus_space_read_stream_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" "bus_size_t offset" +.Fc +.Ft void +.Fo bus_space_write_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint8_t value" +.Fc +.Ft void +.Fo bus_space_write_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint16_t value" +.Fc +.Ft void +.Fo bus_space_write_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint32_t value" +.Fc +.Ft void +.Fo bus_space_write_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint64_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_1 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint8_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_2 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint16_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_4 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint32_t value" +.Fc +.Ft void +.Fo bus_space_write_stream_8 +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "uint64_t value" +.Fc +.Ft void +.Fo bus_space_barrier +.Fa "bus_space_tag_t space" "bus_space_handle_t handle" +.Fa "bus_size_t offset" "bus_size_t length" "int flags" +.Fc +.Ft void +.Fo bus_space_read_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_copy_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t srchandle" "bus_size_t srcoffset" +.Fa "bus_space_handle_t dsthandle" "bus_size_t dstoffset" "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_region_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_read_multi_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_write_multi_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t *datap" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_1 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint8_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_2 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint16_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_4 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint32_t value" +.Fa "bus_size_t count" +.Fc +.Ft void +.Fo bus_space_set_multi_stream_8 +.Fa "bus_space_tag_t space" +.Fa "bus_space_handle_t handle" "bus_size_t offset" "uint64_t value" +.Fa "bus_size_t count" +.Fc +.Sh DESCRIPTION +The +.Nm +functions exist to allow device drivers +machine-independent access to bus memory and register areas. +All of the +functions and types described in this document can be used by including +the +.In machine/bus.h +header file. +.Pp +Many common devices are used on multiple architectures, but are accessed +differently on each because of architectural constraints. +For instance, a device which is mapped in one system's I/O space may be +mapped in memory space on a second system. +On a third system, architectural +limitations might change the way registers need to be accessed (e.g.\& +creating a non-linear register space). +In some cases, a single +driver may need to access the same type of device in multiple ways in a +single system or architecture. +The goal of the +.Nm +functions is to allow a single driver source file to manipulate a set +of devices on different system architectures, and to allow a single driver +object file to manipulate a set of devices on multiple bus types on a +single architecture. +.Pp +Not all busses have to implement all functions described in this +document, though that is encouraged if the operations are logically +supported by the bus. +Unimplemented functions should cause +compile-time errors if possible. +.Pp +All of the interface definitions described in this document are shown as +function prototypes and discussed as if they were required to be +functions. +Implementations are encouraged to implement prototyped +(type-checked) versions of these interfaces, but may implement them as +macros if appropriate. +Machine-dependent types, variables, and functions +should be marked clearly in +.In machine/bus.h +to avoid confusion with the +machine-independent types and functions, and, if possible, should be +given names which make the machine-dependence clear. +.Sh CONCEPTS AND GUIDELINES +Bus spaces are described by bus space tags, which can be created only by +machine-dependent code. +A given machine may have several different types +of bus space (e.g.\& memory space and I/O space), and thus may provide +multiple different bus space tags. +Individual busses or devices on a machine may use more than one bus space +tag. +For instance, ISA devices are +given an ISA memory space tag and an ISA I/O space tag. +Architectures +may have several different tags which represent the same type of +space, for instance because of multiple different host bus interface +chipsets. +.Pp +A range in bus space is described by a bus address and a bus size. +The +bus address describes the start of the range in bus space. +The bus +size describes the size of the range in bytes. +Busses which are not byte +addressable may require use of bus space ranges with appropriately +aligned addresses and properly rounded sizes. +.Pp +Access to regions of bus space is facilitated by use of bus space handles, +which are usually created by mapping a specific range of a bus space. +Handles may also be created by allocating +and mapping a range of bus space, the actual location of which is picked +by the implementation within bounds specified by the caller of the +allocation function. +.Pp +All of the bus space access functions require one bus space tag +argument, at least one handle argument, and at least one offset argument +(a bus size). +The bus space tag specifies the space, each handle specifies a region in +the space, and each offset specifies the offset into the region of the +actual location(s) to be accessed. +Offsets are given in bytes, though busses +may impose alignment constraints. +The offset used to access data +relative to a given handle must be such that all of the data being +accessed is in the mapped region that the handle describes. +Trying to +access data outside that region is an error. +.Pp +Because some architectures' memory systems use buffering to improve +memory and device access performance, there is a mechanism which can be +used to create +.Dq barriers +in the bus space read and write stream. +There +are three types of barriers: read, write, and read/write. +All reads +started to the region before a read barrier must complete before any reads +after the read barrier are started. +(The analogous requirement is true for +write barriers.) +Read/write barriers force all reads and writes started +before the barrier to complete before any reads or writes after the +barrier are started. +Correctly-written drivers will include all +appropriate barriers, and assume only the read/write ordering imposed by +the barrier operations. +.Pp +People trying to write portable drivers with the +.Nm +functions should +try to make minimal assumptions about what the system allows. +In particular, +they should expect that the system requires bus space addresses being +accessed to be naturally aligned (i.e., base address of handle added to +offset is a multiple of the access size), and that the system does +alignment checking on pointers (i.e., pointer to objects being read and +written must point to properly-aligned data). +.Pp +The descriptions of the +.Nm +functions given below all assume that +they are called with proper arguments. +If called with invalid arguments +or arguments that are out of range (e.g.\& trying to access data outside of +the region mapped when a given handle was created), undefined behaviour +results. +In that case, they may cause the +system to halt, either intentionally (via panic) or unintentionally (by +causing a fatal trap of by some other means) or may cause improper +operation which is not immediately fatal. +Functions which return +.Ft void +or which return data read from bus space (i.e., functions which +do not obviously return an error code) do not fail. +They could only fail +if given invalid arguments, and in that case their behaviour is undefined. +Functions which take a count of bytes have undefined results if the specified +.Fa count +is zero. +.Sh TYPES +Several types are defined in +.In machine/bus.h +to facilitate use of the +.Nm +functions by drivers. +.Ss Vt bus_addr_t +The +.Vt bus_addr_t +type is used to describe bus addresses. +It must be an +unsigned integral type +capable of holding the largest bus address usable by the architecture. +This +type is primarily used when mapping and unmapping bus space. +.Ss Vt bus_size_t +The +.Vt bus_size_t +type is used to describe sizes of ranges in bus space. +It must be an +unsigned integral type capable of holding the size of the largest bus +address range usable on the architecture. +This type is used by virtually all +of the +.Nm +functions, describing sizes when mapping regions and +offsets into regions when performing space access operations. +.Ss Vt bus_space_tag_t +The +.Vt bus_space_tag_t +type is used to describe a particular bus space on a machine. +Its +contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used by all +.Nm +functions to name the space on which they are operating. +.Ss Vt bus_space_handle_t +The +.Vt bus_space_handle_t +type is used to describe a mapping of a range of bus space. +Its +contents are machine-dependent and should be considered opaque by +machine-independent code. +This type is used when performing bus space +access operations. +.Sh MAPPING AND UNMAPPING BUS SPACE +This section is specific to the +.Nx +version of these functions and may or may not apply to the +.Fx +version. +.Pp +Bus space must be mapped before it can be used, and should be +unmapped when it is no longer needed. +The +.Fn bus_space_map +and +.Fn bus_space_unmap +functions provide these capabilities. +.Pp +Some drivers need to be able to pass a subregion of already-mapped bus +space to another driver or module within a driver. +The +.Fn bus_space_subregion +function allows such subregions to be created. +.Ss Fn bus_space_map space address size flags handlep +The +.Fn bus_space_map +function maps the region of bus space named by the +.Fa space , address , +and +.Fa size +arguments. +If successful, it returns zero +and fills in the bus space handle pointed to by +.Fa handlep +with the handle +that can be used to access the mapped region. +If unsuccessful, +it will return non-zero and leave the bus space handle pointed +to by +.Fa handlep +in an undefined state. +.Pp +The +.Fa flags +argument controls how the space is to be mapped. +Supported flags include: +.Bl -tag -width ".Dv BUS_SPACE_MAP_CACHEABLE" +.It Dv BUS_SPACE_MAP_CACHEABLE +Try to map the space so that accesses can be cached and/or +prefetched by the system. +If this flag is not specified, the +implementation should map the space so that it will not be cached or +prefetched. +.Pp +This flag must have a value of 1 on all implementations for backward +compatibility. +.It Dv BUS_SPACE_MAP_LINEAR +Try to map the space so that its contents can be accessed linearly via +normal memory access methods (e.g.\& pointer dereferencing and structure +accesses). +This is useful when software wants to do direct access to a memory +device, e.g.\& a frame buffer. +If this flag is specified and linear +mapping is not possible, the +.Fn bus_space_map +call should fail. +If this +flag is not specified, the system may map the space in whatever way is +most convenient. +.El +.Pp +Not all combinations of flags make sense or are supported with all +spaces. +For instance, +.Dv BUS_SPACE_MAP_CACHEABLE +may be meaningless when +used on many systems' I/O port spaces, and on some systems +.Dv BUS_SPACE_MAP_LINEAR +without +.Dv BUS_SPACE_MAP_CACHEABLE +may never work. +When the system hardware or firmware provides hints as to how spaces should be +mapped (e.g.\& the PCI memory mapping registers' +.Dq prefetchable +bit), those +hints should be followed for maximum compatibility. +On some systems, +requesting a mapping that cannot be satisfied (e.g.\& requesting a +non-cacheable mapping when the system can only provide a cacheable one) +will cause the request to fail. +.Pp +Some implementations may keep track of use of bus space for some or all +bus spaces and refuse to allow duplicate allocations. +This is encouraged +for bus spaces which have no notion of slot-specific space addressing, +such as ISA and VME, and for spaces which coexist with those spaces +(e.g.\& EISA and PCI memory and I/O spaces co-existing with ISA memory and +I/O spaces). +.Pp +Mapped regions may contain areas for which there is no device on the +bus. +If space in those areas is accessed, the results are +bus-dependent. +.Ss Fn bus_space_unmap space handle size +The +.Fn bus_space_unmap +function unmaps a region of bus space mapped with +.Fn bus_space_map . +When unmapping a region, the +.Fa size +specified should be +the same as the size given to +.Fn bus_space_map +when mapping that region. +.Pp +After +.Fn bus_space_unmap +is called on a handle, that handle is no longer +valid. +(If copies were made of the handle they are no longer valid, +either.) +.Pp +This function will never fail. +If it would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, +.Fn bus_space_unmap +will never return. +.Ss Fn bus_space_subregion space handle offset size nhandlep +The +.Fn bus_space_subregion +function is a convenience function which makes a +new handle to some subregion of an already-mapped region of bus space. +The subregion described by the new handle starts at byte offset +.Fa offset +into the region described by +.Fa handle , +with the size give by +.Fa size , +and must be wholly contained within the original region. +.Pp +If successful, +.Fn bus_space_subregion +returns zero and fills in the bus +space handle pointed to by +.Fa nhandlep . +If unsuccessful, it returns non-zero and leaves the bus space handle +pointed to by +.Fa nhandlep +in an +undefined state. +In either case, the handle described by +.Fa handle +remains valid and is unmodified. +.Pp +When done with a handle created by +.Fn bus_space_subregion , +the handle should +be thrown away. +Under no circumstances should +.Fn bus_space_unmap +be used on the handle. +Doing so may confuse any resource management +being done on the space, and will result in undefined behaviour. +When +.Fn bus_space_unmap +or +.Fn bus_space_free +is called on a handle, all subregions of that handle become invalid. +.Sh ALLOCATING AND FREEING BUS SPACE +This section is specific to the +.Nx +version of these functions and may or may not apply to the +.Fx +version. +.Pp +Some devices require or allow bus space to be allocated by the operating +system for device use. +When the devices no longer need the space, the +operating system should free it for use by other devices. +The +.Fn bus_space_alloc +and +.Fn bus_space_free +functions provide these capabilities. +.Ss Fn bus_space_alloc space reg_start reg_end size alignment boundary \ +flags addrp handlep +The +.Fn bus_space_alloc +function allocates and maps a region of bus space with the size given by +.Fa size , +corresponding to the given constraints. +If successful, it returns +zero, fills in the bus address pointed to by +.Fa addrp +with the bus space address of the allocated region, and fills in +the bus space handle pointed to by +.Fa handlep +with the handle that can be used to access that region. +If unsuccessful, it returns non-zero and leaves the bus address pointed to by +.Fa addrp +and the bus space handle pointed to by +.Fa handlep +in an undefined state. +.Pp +Constraints on the allocation are given by the +.Fa reg_start , reg_end , alignment , +and +.Fa boundary +parameters. +The allocated region will start at or after +.Fa reg_start +and end before or at +.Fa reg_end . +The +.Fa alignment +constraint must be a power of two, and the allocated region will start at +an address that is an even multiple of that power of two. +The +.Fa boundary +constraint, if non-zero, ensures that the region is allocated so that +.Fa "first address in region" +/ +.Fa boundary +has the same value as +.Fa "last address in region" +/ +.Fa boundary . +If the constraints cannot be met, +.Fn bus_space_alloc +will fail. +It is an error to specify a set of +constraints that can never be met +(for example, +.Fa size +greater than +.Fa boundary ) . +.Pp +The +.Fa flags +parameter is the same as the like-named parameter to +.Fn bus_space_map , +the same flag values should be used, and they have the +same meanings. +.Pp +Handles created by +.Fn bus_space_alloc +should only be freed with +.Fn bus_space_free . +Trying to use +.Fn bus_space_unmap +on them causes undefined behaviour. +The +.Fn bus_space_subregion +function can be used on +handles created by +.Fn bus_space_alloc . +.Ss Fn bus_space_free space handle size +The +.Fn bus_space_free +function unmaps and frees a region of bus space mapped +and allocated with +.Fn bus_space_alloc . +When unmapping a region, the +.Fa size +specified should be the same as the size given to +.Fn bus_space_alloc +when allocating the region. +.Pp +After +.Fn bus_space_free +is called on a handle, that handle is no longer valid. +(If copies were +made of the handle, they are no longer valid, either.) +.Pp +This function will never fail. +If it would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, +.Fn bus_space_free +will never return. +.Sh READING AND WRITING SINGLE DATA ITEMS +The simplest way to access bus space is to read or write a single data +item. +The +.Fn bus_space_read_N +and +.Fn bus_space_write_N +families of functions provide +the ability to read and write 1, 2, 4, and 8 byte data items on busses +which support those access sizes. +.Ss Fn bus_space_read_1 space handle offset +.Ss Fn bus_space_read_2 space handle offset +.Ss Fn bus_space_read_4 space handle offset +.Ss Fn bus_space_read_8 space handle offset +The +.Fn bus_space_read_N +family of functions reads a 1, 2, 4, or 8 byte data item from +the offset specified by +.Fa offset +into the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The location being read must lie within the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data item being read. +On some systems, not obeying this requirement may cause incorrect data to +be read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_N +functions may be executed out +of order with respect to other pending read and write operations unless +order is enforced by use of the +.Fn bus_space_barrier +function. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_write_1 space handle offset value +.Ss Fn bus_space_write_2 space handle offset value +.Ss Fn bus_space_write_4 space handle offset value +.Ss Fn bus_space_write_8 space handle offset value +The +.Fn bus_space_write_N +family of functions writes a 1, 2, 4, or 8 byte data item to the offset +specified by +.Fa offset +into the region specified by +.Fa handle +of the bus space specified by +.Fa space . +The location being written must lie within +the bus space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data item being +written. +On some systems, not obeying this requirement may cause +incorrect data to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_N +functions may be executed +out of order with respect to other pending read and write operations +unless order is enforced by use of the +.Fn bus_space_barrier +function. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Sh BARRIERS +In order to allow high-performance buffering implementations to avoid bus +activity on every operation, read and write ordering should be specified +explicitly by drivers when necessary. +The +.Fn bus_space_barrier +function provides that ability. +.Ss Fn bus_space_barrier space handle offset length flags +The +.Fn bus_space_barrier +function enforces ordering of bus space read and write operations +for the specified subregion (described by the +.Fa offset +and +.Fa length +parameters) of the region named by +.Fa handle +in the space named by +.Fa space . +.Pp +The +.Fa flags +argument controls what types of operations are to be ordered. +Supported flags are: +.Bl -tag -width ".Dv BUS_SPACE_BARRIER_WRITE" +.It Dv BUS_SPACE_BARRIER_READ +Synchronize read operations. +.It Dv BUS_SPACE_BARRIER_WRITE +Synchronize write operations. +.El +.Pp +Those flags can be combined (or-ed together) to enforce ordering on both +read and write operations. +.Pp +All of the specified type(s) of operation which are done to the region +before the barrier operation are guaranteed to complete before any of the +specified type(s) of operation done after the barrier. +.Pp +Example: Consider a hypothetical device with two single-byte ports, one +write-only input port (at offset 0) and a read-only output port (at +offset 1). +Operation of the device is as follows: data bytes are written +to the input port, and are placed by the device on a stack, the top of +which is read by reading from the output port. +The sequence to correctly +write two data bytes to the device then read those two data bytes back +would be: +.Bd -literal +/* + * t and h are the tag and handle for the mapped device's + * space. + */ +bus_space_write_1(t, h, 0, data0); +bus_space_barrier(t, h, 0, 1, BUS_SPACE_BARRIER_WRITE); /* 1 */ +bus_space_write_1(t, h, 0, data1); +bus_space_barrier(t, h, 0, 2, + BUS_SPACE_BARRIER_READ|BUS_SPACE_BARRIER_WRITE); /* 2 */ +ndata1 = bus_space_read_1(t, h, 1); +bus_space_barrier(t, h, 1, 1, BUS_SPACE_BARRIER_READ); /* 3 */ +ndata0 = bus_space_read_1(t, h, 1); +/* data0 == ndata0, data1 == ndata1 */ +.Ed +.Pp +The first barrier makes sure that the first write finishes before the +second write is issued, so that two writes to the input port are done +in order and are not collapsed into a single write. +This ensures that +the data bytes are written to the device correctly and in order. +.Pp +The second barrier makes sure that the writes to the output port finish +before any of the reads to the input port are issued, thereby making sure +that all of the writes are finished before data is read. +This ensures +that the first byte read from the device really is the last one that was +written. +.Pp +The third barrier makes sure that the first read finishes before the +second read is issued, ensuring that data is read correctly and in order. +.Pp +The barriers in the example above are specified to cover the absolute +minimum number of bus space locations. +It is correct (and often +easier) to make barrier operations cover the device's whole range of bus +space, that is, to specify an offset of zero and the size of the +whole region. +.Sh REGION OPERATIONS +Some devices use buffers which are mapped as regions in bus space. +Often, drivers want to copy the contents of those buffers to or from +memory, e.g.\& into mbufs which can be passed to higher levels of the +system or from mbufs to be output to a network. +In order to allow +drivers to do this as efficiently as possible, the +.Fn bus_space_read_region_N +and +.Fn bus_space_write_region_N +families of functions are provided. +.Pp +Drivers occasionally need to copy one region of a bus space to another, +or to set all locations in a region of bus space to contain a single +value. +The +.Fn bus_space_copy_region_N +family of functions and the +.Fn bus_space_set_region_N +family of functions allow drivers to perform these operations. +.Ss Fn bus_space_read_region_1 space handle offset datap count +.Ss Fn bus_space_read_region_2 space handle offset datap count +.Ss Fn bus_space_read_region_4 space handle offset datap count +.Ss Fn bus_space_read_region_8 space handle offset datap count +The +.Fn bus_space_read_region_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from bus space +starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space +and writes them into the array specified by +.Fa datap . +Each successive data item is read from an offset +1, 2, 4, or 8 bytes after the previous data item (depending on which +function is used). +All locations being read must lie within the bus +space region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +read and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_region_N +functions may be executed in any order. +They may also be executed out +of order with respect to other pending read and write operations unless +order is enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between reads of +individual bus space locations executed by the +.Fn bus_space_read_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_write_region_1 space handle offset datap count +.Ss Fn bus_space_write_region_2 space handle offset datap count +.Ss Fn bus_space_write_region_4 space handle offset datap count +.Ss Fn bus_space_write_region_8 space handle offset datap count +The +.Fn bus_space_write_region_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from the array +specified by +.Fa datap +and writes them to bus space starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified +by +.Fa space . +Each successive data item is written to an offset 1, 2, 4, +or 8 bytes after the previous data item (depending on which function is +used). +All locations being written must lie within the bus space region +specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_region_N +functions may be +executed in any order. +They may also be executed out of order with +respect to other pending read and write operations unless order is +enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between writes of +individual bus space locations executed by the +.Fn bus_space_write_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_copy_region_1 space srchandle srcoffset dsthandle \ +dstoffset count +.Ss Fn bus_space_copy_region_2 space srchandle srcoffset dsthandle \ +dstoffset count +.Ss Fn bus_space_copy_region_4 space srchandle srcoffset dsthandle \ +dstoffset count +.Ss Fn bus_space_copy_region_8 space srchandle srcoffset dsthandle \ +dstoffset count +The +.Fn bus_space_copy_region_N +family of functions copies +.Fa count +1, 2, 4, or 8 byte data items in bus space +from the area starting at byte offset +.Fa srcoffset +in the region specified by +.Fa srchandle +of the bus space specified by +.Fa space +to the area starting at byte offset +.Fa dstoffset +in the region specified by +.Fa dsthandle +in the same bus space. +Each successive data item read or written has +an offset 1, 2, 4, or 8 bytes after the previous data item (depending +on which function is used). +All locations being read and written must +lie within the bus space region specified by their respective handles. +.Pp +For portability, the starting addresses of the regions specified by the +each handle plus its respective offset should be a multiple of the size +of data items being copied. +On some systems, not obeying this +requirement may cause incorrect data to be copied, on others it may cause +a system crash. +.Pp +Read and write operations done by the +.Fn bus_space_copy_region_N +functions may be executed in any order. +They may also be executed out +of order with respect to other pending read and write operations unless +order is enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between reads or writes of +individual bus space locations executed by the +.Fn bus_space_copy_region_N +functions. +.Pp +Overlapping copies between different subregions of a single region +of bus space are handled correctly by the +.Fn bus_space_copy_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_set_region_1 space handle offset value count +.Ss Fn bus_space_set_region_2 space handle offset value count +.Ss Fn bus_space_set_region_4 space handle offset value count +.Ss Fn bus_space_set_region_8 space handle offset value count +The +.Fn bus_space_set_region_N +family of functions writes the given +.Fa value +to +.Fa count +1, 2, 4, or 8 byte +data items in bus space starting at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +Each successive data item has an offset 1, 2, 4, or 8 bytes after the +previous data item (depending on which function is used). +All +locations being written must lie within the bus space region specified +by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written. +On some systems, not obeying this requirement may cause +incorrect data to be written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_set_region_N +functions may be +executed in any order. +They may also be executed out of order with +respect to other pending read and write operations unless order is +enforced by use of the +.Fn bus_space_barrier +function. +There is no way to insert barriers between writes of +individual bus space locations executed by the +.Fn bus_space_set_region_N +functions. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Sh READING AND WRITING A SINGLE LOCATION MULTIPLE TIMES +Some devices implement single locations in bus space which are to be read +or written multiple times to communicate data, e.g.\& some ethernet +devices' packet buffer FIFOs. +In order to allow drivers to manipulate +these types of devices as efficiently as possible, the +.Fn bus_space_read_multi_N , +.Fn bus_space_set_multi_N , +and +.Fn bus_space_write_multi_N +families of functions are provided. +.Ss Fn bus_space_read_multi_1 space handle offset datap count +.Ss Fn bus_space_read_multi_2 space handle offset datap count +.Ss Fn bus_space_read_multi_4 space handle offset datap count +.Ss Fn bus_space_read_multi_8 space handle offset datap count +The +.Fn bus_space_read_multi_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from bus space +at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space +and writes them into the array specified by +.Fa datap . +Each successive data item is read from the same location in bus +space. +The location being read must lie within the bus space region +specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +read and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +read, on others it may cause a system crash. +.Pp +Read operations done by the +.Fn bus_space_read_multi_N +functions may be +executed out of order with respect to other pending read and write +operations unless order is enforced by use of the +.Fn bus_space_barrier +function. +Because the +.Fn bus_space_read_multi_N +functions read the same bus space location multiple times, they +place an implicit read barrier between each successive read of that bus +space location. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_write_multi_1 space handle offset datap count +.Ss Fn bus_space_write_multi_2 space handle offset datap count +.Ss Fn bus_space_write_multi_4 space handle offset datap count +.Ss Fn bus_space_write_multi_8 space handle offset datap count +The +.Fn bus_space_write_multi_N +family of functions reads +.Fa count +1, 2, 4, or 8 byte data items from the array +specified by +.Fa datap +and writes them into bus space at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space . +Each successive data item is written to the same location in +bus space. +The location being written must lie within the bus space +region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_write_multi_N +functions may be executed out of order with respect to other pending +read and write operations unless order is enforced by use of the +.Fn bus_space_barrier +function. +Because the +.Fn bus_space_write_multi_N +functions write the same bus space location multiple times, they +place an implicit write barrier between each successive write of that +bus space location. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Ss Fn bus_space_set_multi_1 space handle offset value count +.Ss Fn bus_space_set_multi_2 space handle offset value count +.Ss Fn bus_space_set_multi_4 space handle offset value count +.Ss Fn bus_space_set_multi_8 space handle offset value count +The +.Fn bus_space_set_multi_N +writes +.Fa value +into bus space at byte offset +.Fa offset +in the region specified by +.Fa handle +of the bus space specified by +.Fa space , +.Fa count +times. +The location being written must lie within the bus space +region specified by +.Fa handle . +.Pp +For portability, the starting address of the region specified by +.Fa handle +plus the offset should be a multiple of the size of data items being +written and the data array pointer should be properly aligned. +On some +systems, not obeying these requirements may cause incorrect data to be +written, on others it may cause a system crash. +.Pp +Write operations done by the +.Fn bus_space_set_multi_N +functions may be executed out of order with respect to other pending +read and write operations unless order is enforced by use of the +.Fn bus_space_barrier +function. +Because the +.Fn bus_space_set_multi_N +functions write the same bus space location multiple times, they +place an implicit write barrier between each successive write of that +bus space location. +.Pp +These functions will never fail. +If they would fail (e.g.\& because of an +argument error), that indicates a software bug which should cause a +panic. +In that case, they will never return. +.Sh STREAM FUNCTIONS +Most of the +.Nm +functions imply a host byte-order and a bus byte-order and take care of +any translation for the caller. +In some cases, however, hardware may map a FIFO or some other memory region +for which the caller may want to use multi-word, yet untranslated access. +Access to these types of memory regions should be with the +.Fn bus_space_*_stream_N +functions. +.Pp +.Bl -tag -compact -width Fn +.It Fn bus_space_read_stream_1 +.It Fn bus_space_read_stream_2 +.It Fn bus_space_read_stream_4 +.It Fn bus_space_read_stream_8 +.It Fn bus_space_read_multi_stream_1 +.It Fn bus_space_read_multi_stream_2 +.It Fn bus_space_read_multi_stream_4 +.It Fn bus_space_read_multi_stream_8 +.It Fn bus_space_read_region_stream_1 +.It Fn bus_space_read_region_stream_2 +.It Fn bus_space_read_region_stream_4 +.It Fn bus_space_read_region_stream_8 +.It Fn bus_space_write_stream_1 +.It Fn bus_space_write_stream_2 +.It Fn bus_space_write_stream_4 +.It Fn bus_space_write_stream_8 +.It Fn bus_space_write_multi_stream_1 +.It Fn bus_space_write_multi_stream_2 +.It Fn bus_space_write_multi_stream_4 +.It Fn bus_space_write_multi_stream_8 +.It Fn bus_space_write_region_stream_1 +.It Fn bus_space_write_region_stream_2 +.It Fn bus_space_write_region_stream_4 +.It Fn bus_space_write_region_stream_8 +.It Fn bus_space_copy_region_stream_1 +.It Fn bus_space_copy_region_stream_2 +.It Fn bus_space_copy_region_stream_4 +.It Fn bus_space_copy_region_stream_8 +.It Fn bus_space_set_multi_stream_1 +.It Fn bus_space_set_multi_stream_2 +.It Fn bus_space_set_multi_stream_4 +.It Fn bus_space_set_multi_stream_8 +.It Fn bus_space_set_region_stream_1 +.It Fn bus_space_set_region_stream_2 +.It Fn bus_space_set_region_stream_4 +.It Fn bus_space_set_region_stream_8 +.El +.Pp +These functions are defined just as their non-stream counterparts, +except that they provide no byte-order translation. +.Sh COMPATIBILITY +The current +.Nx +version of the +.Nm +interface specification differs slightly from the original +specification that came into wide use and +.Fx +adopted. +A few of the function names and arguments have changed +for consistency and increased functionality. +.Sh SEE ALSO +.Xr bus_dma 9 +.Sh HISTORY +The +.Nm +functions were introduced in a different form (memory and I/O spaces +were accessed via different sets of functions) in +.Nx 1.2 . +The functions were merged to work on generic +.Dq spaces +early in the +.Nx 1.3 +development cycle, and many drivers were converted to use them. +This document was written later during the +.Nx 1.3 +development cycle, and the specification was updated to fix some +consistency problems and to add some missing functionality. +.Pp +The manual page was then adapted to the version of the interface that +.Fx +imported for the CAM SCSI drivers, plus subsequent evolution. +The +.Fx +.Nm +version was imported in +.Fx 3.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +interfaces were designed and implemented by the +.Nx +developer +community. +Primary contributors and implementors were +.An Chris Demetriou , +.An Jason Thorpe , +and +.An Charles Hannum , +but the rest of the +.Nx +developers and the user community played a significant role in development. +.Pp +.An Justin Gibbs +ported these interfaces to +.Fx . +.Pp +.An Chris Demetriou +wrote this manual page. +.Pp +.An Warner Losh +modified it for the +.Fx +implementation. +.Sh BUGS +This manual may not completely and accurately document the interface, +and many parts of the interface are unspecified. Property changes on: user/imp/camdoc/bus_space.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/rtentry.9 =================================================================== --- user/imp/camdoc/rtentry.9 (nonexistent) +++ user/imp/camdoc/rtentry.9 (revision 296049) @@ -0,0 +1,252 @@ +.\" +.\" Copyright 1996 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 5, 2014 +.Dt RTENTRY 9 +.Os +.Sh NAME +.Nm rtentry +.Nd structure of an entry in the kernel routing table +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/route.h +.Sh DESCRIPTION +The kernel provides a common mechanism by which all protocols can store +and retrieve entries from a central table of routes. +Parts of this +mechanism are also used to interact with user-level processes by means +of a socket in the +.Xr route 4 +pseudo-protocol family. +The +.In net/route.h +header file defines the structures and manifest constants used in this +facility. +.Pp +The basic structure of a route is defined by +.Vt "struct rtentry" , +which includes the following fields: +.Bl -tag -offset indent -width 6n +.It Vt "struct radix_node rt_nodes[2]" ; +Glue used by the radix-tree routines. +These members also include in +their substructure the key (i.e., destination address) and mask used +when the route was created. +The +.Fn rt_key rt +and +.Fn rt_mask rt +macros can be used to extract this information (in the form of a +.Vt "struct sockaddr *" ) +given a +.Vt "struct rtentry *" . +.It Vt "struct sockaddr *rt_gateway" ; +The +.Dq target +of the route, which can either represent a destination in its own +right (some protocols will put a link-layer address here), or some +intermediate stop on the way to that destination (if the +.Dv RTF_GATEWAY +flag is set). +.It Vt "int rt_flags" ; +See below. +If the +.Dv RTF_UP +flag is not present, the +.Fn rtfree +function will delete the route from the radix tree when the last +reference drops. +.It Vt "int rt_refcnt" ; +Route entries are reference-counted; this field indicates the number +of external (to the radix tree) references. +.It Vt "struct ifnet *rt_ifp" ; +.It Vt "struct ifaddr *rt_ifa" ; +These two fields represent the +.Dq answer , +as it were, to the question posed by a route lookup; that is, they +name the interface and interface address to be used in sending a +packet to the destination or set of destinations which this route +represents. +.It Vt "u_long rt_mtu"; +See description of rmx_mtu below. +.It Vt "u_long rt_weight"; +See description of rmx_weight below. +.It Vt "u_long rt_expire"; +See description of rmx_expire below. +.It Vt "counter64_t rt_pksent"; +See description of rmx_pksent below. +.It Vt "struct rtentry *rt_gwroute" ; +This member is a reference to a route whose destination is +.Va rt_gateway . +It is only used for +.Dv RTF_GATEWAY +routes. +.It Vt "struct mtx rt_mtx" ; +Mutex to lock this routing entry. +.El +.Pp +The following flag bits are defined: +.Bl -tag -offset indent -width ".Dv RTF_BLACKHOLE" -compact +.It Dv RTF_UP +The route is not deleted. +.It Dv RTF_GATEWAY +The route points to an intermediate destination and not the ultimate +recipient; the +.Va rt_gateway +and +.Va rt_gwroute +fields name that destination. +.It Dv RTF_HOST +This is a host route. +.It Dv RTF_REJECT +The destination is presently unreachable. +This should result in an +.Er EHOSTUNREACH +error from output routines. +.It Dv RTF_DYNAMIC +This route was created dynamically by +.Fn rtredirect . +.It Dv RTF_MODIFIED +This route was modified by +.Fn rtredirect . +.It Dv RTF_DONE +Used only in the +.Xr route 4 +protocol, indicating that the request was executed. +.It Dv RTF_XRESOLVE +When this route is returned as a result of a lookup, send a report on +the +.Xr route 4 +interface requesting that an external process perform resolution for +this route. +.It Dv RTF_STATIC +Indicates that this route was manually added by means of the +.Xr route 8 +command. +.It Dv RTF_BLACKHOLE +Requests that output sent via this route be discarded. +.It Dv RTF_PROTO1 +.It Dv RTF_PROTO2 +.It Dv RTF_PROTO3 +Protocol-specific. +.It Dv RTF_PINNED +Indicates that this route is immutable to a routing protocol. +.It Dv RTF_LOCAL +Indicates that the destination of this route is an address configured +as belonging to this system. +.It Dv RTF_BROADCAST +Indicates that the destination is a broadcast address. +.It Dv RTF_MULTICAST +Indicates that the destination is a multicast address. +.El +.Pp +Several metrics are supplied in +.Vt "struct rt_metrics" +passed with routing control messages via +.Xr route 4 +API. +Currently only +.Vt rmx_mtu , rmx_expire , +and +.Vt rmx_pksent +metrics are supplied. +All others are ignored. +.Pp +The following metrics are defined by +.Vt "struct rt_metrics" : +.Bl -tag -offset indent -width 6n +.It Vt "u_long rmx_locks" ; +Flag bits indicating which metrics the kernel is not permitted to +dynamically modify. +.It Vt "u_long rmx_mtu" ; +MTU for this path. +.It Vt "u_long rmx_hopcount" ; +Number of intermediate systems on the path to this destination. +.It Vt "u_long rmx_expire" ; +The time +(a la +.Xr time 3 ) +at which this route should expire, or zero if it should never expire. +It is the responsibility of individual protocol suites to ensure that routes +are actually deleted once they expire. +.It Vt "u_long rmx_recvpipe" ; +Nominally, the bandwidth-delay product for the path +.Em from +the destination +.Em to +this system. +In practice, this value is used to set the size of the +receive buffer (and thus the window in sliding-window protocols like +.Tn TCP ) . +.It Vt "u_long rmx_sendpipe" ; +As before, but in the opposite direction. +.It Vt "u_long rmx_ssthresh" ; +The slow-start threshold used in +.Tn TCP +congestion-avoidance. +.It Vt "u_long rmx_rtt" ; +The round-trip time to this destination, in units of +.Dv RMX_RTTUNIT +per second. +.It Vt "u_long rmx_rttvar" ; +The average deviation of the round-trip time to this destination, in +units of +.Dv RMX_RTTUNIT +per second. +.It Vt "u_long rmx_pksent" ; +A count of packets successfully sent via this route. +.It Vt "u_long rmx_filler[4]" ; +.\" XXX badly named +Empty space available for protocol-specific information. +.El +.Sh SEE ALSO +.Xr route 4 , +.Xr route 8 , +.Xr rtalloc 9 +.Sh HISTORY +The +.Vt rtentry +structure first appeared in +.Bx 4.2 . +The radix-tree representation of the routing table and the +.Vt rt_metrics +structure first appeared in +.Bx 4.3 reno . +.Sh AUTHORS +This manual page was written by +.An Garrett Wollman . +.Sh BUGS +There are a number of historical relics remaining in this interface. +The +.Va rt_gateway +and +.Va rmx_filler +fields could be named better. Property changes on: user/imp/camdoc/rtentry.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/buf.9 =================================================================== --- user/imp/camdoc/buf.9 (nonexistent) +++ user/imp/camdoc/buf.9 (revision 296049) @@ -0,0 +1,146 @@ +.\" Copyright (c) 1998 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 22, 1998 +.Dt BUF 9 +.Os +.Sh NAME +.Nm buf +.Nd "kernel buffer I/O scheme used in FreeBSD VM system" +.Sh DESCRIPTION +The kernel implements a KVM abstraction of the buffer cache which allows it +to map potentially disparate vm_page's into contiguous KVM for use by +(mainly file system) devices and device I/O. +This abstraction supports +block sizes from DEV_BSIZE (usually 512) to upwards of several pages or more. +It also supports a relatively primitive byte-granular valid range and dirty +range currently hardcoded for use by NFS. +The code implementing the +VM Buffer abstraction is mostly concentrated in +.Pa /usr/src/sys/kern/vfs_bio.c . +.Pp +One of the most important things to remember when dealing with buffer pointers +(struct buf) is that the underlying pages are mapped directly from the buffer +cache. +No data copying occurs in the scheme proper, though some file systems +such as UFS do have to copy a little when dealing with file fragments. +The second most important thing to remember is that due to the underlying page +mapping, the b_data base pointer in a buf is always *page* aligned, not +*block* aligned. +When you have a VM buffer representing some b_offset and +b_size, the actual start of the buffer is (b_data + (b_offset & PAGE_MASK)) +and not just b_data. +Finally, the VM system's core buffer cache supports +valid and dirty bits (m->valid, m->dirty) for pages in DEV_BSIZE chunks. +Thus +a platform with a hardware page size of 4096 bytes has 8 valid and 8 dirty +bits. +These bits are generally set and cleared in groups based on the device +block size of the device backing the page. +Complete page's worth are often +referred to using the VM_PAGE_BITS_ALL bitmask (i.e., 0xFF if the hardware page +size is 4096). +.Pp +VM buffers also keep track of a byte-granular dirty range and valid range. +This feature is normally only used by the NFS subsystem. +I am not sure why it +is used at all, actually, since we have DEV_BSIZE valid/dirty granularity +within the VM buffer. +If a buffer dirty operation creates a 'hole', +the dirty range will extend to cover the hole. +If a buffer validation +operation creates a 'hole' the byte-granular valid range is left alone and +will not take into account the new extension. +Thus the whole byte-granular +abstraction is considered a bad hack and it would be nice if we could get rid +of it completely. +.Pp +A VM buffer is capable of mapping the underlying VM cache pages into KVM in +order to allow the kernel to directly manipulate the data associated with +the (vnode,b_offset,b_size). +The kernel typically unmaps VM buffers the moment +they are no longer needed but often keeps the 'struct buf' structure +instantiated and even bp->b_pages array instantiated despite having unmapped +them from KVM. +If a page making up a VM buffer is about to undergo I/O, the +system typically unmaps it from KVM and replaces the page in the b_pages[] +array with a place-marker called bogus_page. +The place-marker forces any kernel +subsystems referencing the associated struct buf to re-lookup the associated +page. +I believe the place-marker hack is used to allow sophisticated devices +such as file system devices to remap underlying pages in order to deal with, +for example, re-mapping a file fragment into a file block. +.Pp +VM buffers are used to track I/O operations within the kernel. +Unfortunately, +the I/O implementation is also somewhat of a hack because the kernel wants +to clear the dirty bit on the underlying pages the moment it queues the I/O +to the VFS device, not when the physical I/O is actually initiated. +This +can create confusion within file system devices that use delayed-writes because +you wind up with pages marked clean that are actually still dirty. +If not +treated carefully, these pages could be thrown away! +Indeed, a number of +serious bugs related to this hack were not fixed until the 2.2.8/3.0 release. +The kernel uses an instantiated VM buffer (i.e., struct buf) to place-mark pages +in this special state. +The buffer is typically flagged B_DELWRI. +When a +device no longer needs a buffer it typically flags it as B_RELBUF. +Due to +the underlying pages being marked clean, the B_DELWRI|B_RELBUF combination must +be interpreted to mean that the buffer is still actually dirty and must be +written to its backing store before it can actually be released. +In the case +where B_DELWRI is not set, the underlying dirty pages are still properly +marked as dirty and the buffer can be completely freed without losing that +clean/dirty state information. +(XXX do we have to check other flags in +regards to this situation ???) +.Pp +The kernel reserves a portion of its KVM space to hold VM Buffer's data +maps. +Even though this is virtual space (since the buffers are mapped +from the buffer cache), we cannot make it arbitrarily large because +instantiated VM Buffers (struct buf's) prevent their underlying pages in the +buffer cache from being freed. +This can complicate the life of the paging +system. +.\" .Sh SEE ALSO +.\" .Xr 9 +.Sh HISTORY +The +.Nm +manual page was originally written by +.An Matthew Dillon +and first appeared in +.Fx 3.1 , +December 1998. Property changes on: user/imp/camdoc/buf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/intro.9 =================================================================== --- user/imp/camdoc/intro.9 (nonexistent) +++ user/imp/camdoc/intro.9 (revision 296049) @@ -0,0 +1,105 @@ +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 13, 1995 +.Dt INTRO 9 +.Os +.Sh NAME +.Nm intro +.Nd "introduction to system kernel interfaces" +.Sh DESCRIPTION +This section contains information about the interfaces and +subroutines in the kernel. +.Sh PROTOTYPES ANSI-C AND ALL THAT +Yes please. +.Pp +We would like all code to be fully prototyped. +.Pp +If your code compiles cleanly with +.Nm cc +.Ar -Wall +we would feel happy about it. +It is important to understand that this is not a question of just shutting up +.Nm cc , +it is a question about avoiding the things it complains about. +To put it bluntly, do not hide the problem by casting and other +obfuscating practices, solve the problem. +.Sh INDENTATION AND STYLE +Believe it or not, there actually exists a guide for indentation and style. +It is not generally applied though. +.Pp +We would appreciate if people would pay attention to it, and at least not +violate it blatantly. +.Pp +We do not mind it too badly if you have your own style, but please make +sure we can read it too. +.Pp +Please take time to read +.Xr style 9 +for more information. +.Sh NAMING THINGS +Some general rules exist: +.Bl -enum +.It +If a function is meant as a debugging aid in DDB, it should be enclosed +in +.Bd -literal -offset indent +#ifdef DDB + +#endif /* DDB */ +.Ed +.Pp +And the name of the procedure should start with the prefix +.Li DDB_ +to clearly identify the procedure as a debugger routine. +.El +.Sh SCOPE OF SYMBOLS +It is important to carefully consider the scope of symbols in the kernel. +The default is to make everything static, unless some reason requires +the opposite. +.Pp +There are several reasons for this policy, +the main one is that the kernel is one monolithic name-space, +and pollution is not a good idea here either. +.Pp +For device drivers and other modules that do not add new internal interfaces +to the kernel, the entire source should be in one file if possible. +That way all symbols can be made static. +.Pp +If for some reason a module is split over multiple source files, then try +to split the module along some major fault-line and consider using the +number of global symbols as your guide. +The fewer the better. +.Sh SEE ALSO +.Xr style 9 +.Sh HISTORY +The +.Nm +section manual page appeared in +.Fx 2.2 . Property changes on: user/imp/camdoc/intro.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_STRATEGY.9 =================================================================== --- user/imp/camdoc/VOP_STRATEGY.9 (nonexistent) +++ user/imp/camdoc/VOP_STRATEGY.9 (revision 296049) @@ -0,0 +1,64 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 2, 2014 +.Dt VOP_STRATEGY 9 +.Os +.Sh NAME +.Nm VOP_STRATEGY +.Nd read or write a file system buffer +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_STRATEGY "struct vnode *vp" "struct buf *bp" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode that the buffer is for. +.It Fa bp +The buffer to be read or written. +.El +.Pp +This call either reads or writes data from a file, depending on the value of +.Fa bp->b_io.bio_cmd . +.Pp +The call may block. +.Sh RETURN VALUES +Always zero. +Errors should be signalled by setting BIO_ERROR on b_ioflags field in struct buf, +and setting b_error to the appropriate errno value. +.Sh SEE ALSO +.Xr buf 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_STRATEGY.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/disk.9 =================================================================== --- user/imp/camdoc/disk.9 (nonexistent) +++ user/imp/camdoc/disk.9 (revision 296049) @@ -0,0 +1,233 @@ +.\" +.\" 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 October 30, 2012 +.Dt DISK 9 +.Os +.Sh NAME +.Nm disk +.Nd kernel disk storage API +.Sh SYNOPSIS +.In geom/geom_disk.h +.Ft struct disk * +.Fn disk_alloc void +.Ft void +.Fn disk_create "struct disk *disk" "int version" +.Ft void +.Fn disk_gone "struct disk *disk" +.Ft void +.Fn disk_destroy "struct disk *disk" +.Ft int +.Fn disk_resize "struct disk *disk" "int flags" +.Sh DESCRIPTION +The disk storage API permits kernel device drivers providing access to +disk-like storage devices to advertise the device to other kernel +components, including +.Xr GEOM 4 +and +.Xr devfs 5 . +.Pp +Each disk device is described by a +.Vt "struct disk" +structure, which contains a variety of parameters for the disk device, +function pointers for various methods that may be performed on the device, +as well as private data storage for the device driver. +In addition, some fields are reserved for use by GEOM in managing access +to the device and its statistics. +.Pp +GEOM has the ownership of +.Vt "struct disk" , +and drivers must allocate storage for it with the +.Fn disk_alloc +function, +fill in the fields and call +.Fn disk_create +when the device is ready to service requests. +.Fn disk_resize +can be called by the driver after modifying +.Va d_mediasize +to notify GEOM about the disk capacity change. +The +.Fa flags +field should be set to either M_WAITOK, or M_NOWAIT. +.Fn disk_gone +orphans all of the providers associated with the drive, setting an error +condition of ENXIO in each one. +In addition, it prevents a re-taste on last close for writing if an error +condition has been set in the provider. +After calling +.Fn disk_destroy , +the device driver is not allowed to access the contents of +.Vt "struct disk" +anymore. +.Pp +The +.Fn disk_create +function +takes a second parameter, +.Fa version , +which must always be passed +.Dv DISK_VERSION . +If GEOM detects that the driver is compiled against an unsupported version, +it will ignore the device and print a warning on the console. +.Ss Descriptive Fields +The following fields identify the disk device described by the structure +instance, and must be filled in prior to submitting the structure to +.Fn disk_create +and may not be subsequently changed: +.Bl -tag -width indent +.It Vt u_int Va d_flags +Optional flags indicating to the storage framework what optional features +or descriptions the storage device driver supports. +Currently supported flags are +.Dv DISKFLAG_OPEN +(maintained by storage framework), +.Dv DISKFLAG_CANDELETE +(maintained by device driver), +and +.Dv DISKFLAG_CANFLUSHCACHE +(maintained by device driver). +.It Vt "const char *" Va d_name +Holds the name of the storage device class, e.g., +.Dq Li ahd . +This value typically uniquely identifies a particular driver device, +and must not conflict with devices serviced by other device drivers. +.It Vt u_int Va d_unit +Holds the instance of the storage device class, e.g., +.Dq Li 4 . +This namespace is managed by the device driver, and assignment of unit +numbers might be a property of probe order, or in some cases topology. +Together, the +.Va d_name +and +.Va d_unit +values will uniquely identify a disk storage device. +.El +.Ss Disk Device Methods +The following fields identify various disk device methods, if implemented: +.Bl -tag -width indent +.It Vt "disk_open_t *" Va d_open +Optional: invoked when the disk device is opened. +If no method is provided, open will always succeed. +.It Vt "disk_close_t *" Va d_close +Optional: invoked when the disk device is closed. +Although an error code may be returned, the call should always terminate +any state setup by the corresponding open method call. +.It Vt "disk_strategy_t *" Va d_strategy +Mandatory: invoked when a new +.Vt "struct bio" +is to be initiated on the disk device. +.It Vt "disk_ioctl_t *" Va d_ioctl +Optional: invoked when an I/O control operation is initiated on the disk device. +Please note that for security reasons these operations should not +be able to affect other devices than the one on which they are performed. +.It Vt "dumper_t *" Va d_dump +Optional: if configured with +.Xr dumpon 8 , +this function is invoked from a very restricted system state after a +kernel panic to record a copy of the system RAM to the disk. +.It Vt "disk_getattr_t *" Va d_getattr +Optional: if this method is provided, it gives the disk driver the +opportunity to override the default GEOM response to BIO_GETATTR requests. +This function should return -1 if the attribute is not handled, 0 if the +attribute is handled, or an errno to be passed to g_io_deliver(). +.It Vt "disk_gone_t *" Va d_gone +Optional: if this method is provided, it will be called after disk_gone() +is called, once GEOM has finished its cleanup process. +Once this callback is called, it is safe for the disk driver to free all of +its resources, as it will not be receiving further calls from GEOM. +.El +.Ss Mandatory Media Properties +The following fields identify the size and granularity of the disk device. +These fields must stay stable from return of the drivers open method until +the close method is called, but it is perfectly legal to modify them in +the open method before returning. +.Bl -tag -width indent +.It Vt u_int Va d_sectorsize +The sector size of the disk device in bytes. +.It Vt off_t Va d_mediasize +The size of the disk device in bytes. +.It Vt u_int Va d_maxsize +The maximum supported size in bytes of an I/O request. +Requests larger than this size will be chopped up by GEOM. +.El +.Ss Optional Media Properties +These optional fields can provide extra information about the disk +device. +Do not initialize these fields if the field/concept does not apply. +These fields must stay stable from return of the drivers open method until +the close method is called, but it is perfectly legal to modify them in +the open method before returning. +.Bl -tag -width indent +.It Vt u_int Va d_fwsectors , Vt u_int Va d_fwheads +The number of sectors and heads advertised on the disk device by the +firmware or BIOS. +These values are almost universally bogus, but on some architectures +necessary for the correct calculation of disk partitioning. +.It Vt u_int Va d_stripeoffset , Vt u_int Va d_stripesize +These two fields can be used to describe the width and location of +natural performance boundaries for most disk technologies. +Please see +.Pa src/sys/geom/notes +for details. +.It Vt char Va d_ident[DISK_IDENT_SIZE] +This field can and should be used to store disk's serial number if the +d_getattr method described above isn't implemented, or if it does not +support the GEOM::ident attribute. +.It Vt char Va d_descr[DISK_IDENT_SIZE] +This field can be used to store the disk vendor and product description. +.It Vt uint16_t Va d_hba_vendor +This field can be used to store the PCI vendor ID for the HBA connected to +the disk. +.It Vt uint16_t Va d_hba_device +This field can be used to store the PCI device ID for the HBA connected to +the disk. +.It Vt uint16_t Va d_hba_subvendor +This field can be used to store the PCI subvendor ID for the HBA connected to +the disk. +.It Vt uint16_t Va d_hba_subdevice +This field can be used to store the PCI subdevice ID for the HBA connected to +the disk. +.El +.Ss Driver Private Data +This field may be used by the device driver to store a pointer to +private data to implement the disk service. +.Bl -tag -width indent +.It Vt "void *" Va d_drv1 +Private data pointer. +Typically used to store a pointer to the drivers +.Vt softc +structure for this disk device. +.El +.Sh SEE ALSO +.Xr GEOM 4 , +.Xr devfs 5 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . Property changes on: user/imp/camdoc/disk.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_FSYNC.9 =================================================================== --- user/imp/camdoc/VOP_FSYNC.9 (nonexistent) +++ user/imp/camdoc/VOP_FSYNC.9 (revision 296049) @@ -0,0 +1,84 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_FSYNC 9 +.Os +.Sh NAME +.Nm VOP_FSYNC +.Nd flush file system buffers for a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_FSYNC "struct vnode *vp" "int waitfor" "struct thread *td" +.Sh DESCRIPTION +This call flushes any dirty file system buffers for the file. +It is used to implement the +.Xr sync 2 +and +.Xr fsync 2 +system calls. +.Pp +Its arguments are: +.Bl -tag -width waitfor +.It Fa vp +The vnode of the file. +.It Fa waitfor +Whether the function should wait for I/O to complete. +Possible values are: +.Bl -tag -width MNT_NOWAIT +.It Dv MNT_WAIT +Synchronously wait for I/O to complete. +.It Dv MNT_NOWAIT +Start all I/O, but do not wait for it. +.It Dv MNT_LAZY +Push data not written by file system syncer. +.El +.It Fa td +The calling thread. +.El +.Sh LOCKS +The file should be locked on entry. +.Sh RETURN VALUES +Zero is returned if the call is successful, otherwise an appropriate +error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EDQUOT +Quota exceeded. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_FSYNC.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/pfil.9 =================================================================== --- user/imp/camdoc/pfil.9 (nonexistent) +++ user/imp/camdoc/pfil.9 (revision 296049) @@ -0,0 +1,254 @@ +.\" $NetBSD: pfil.9,v 1.22 2003/07/01 13:04:06 wiz Exp $ +.\" +.\" Copyright (c) 1996 Matthew R. Green +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 23, 2013 +.Dt PFIL 9 +.Os +.Sh NAME +.Nm pfil , +.Nm pfil_head_register , +.Nm pfil_head_unregister , +.Nm pfil_head_get , +.Nm pfil_add_hook , +.Nm pfil_remove_hook , +.Nm pfil_run_hooks , +.Nm pfil_rlock , +.Nm pfil_runlock , +.Nm pfil_wlock , +.Nm pfil_wunlock +.Nd packet filter interface +.Sh SYNOPSIS +.In sys/param.h +.In sys/mbuf.h +.In net/if.h +.In net/pfil.h +.Bd -literal +typedef int (*pfil_func_t)(void *arg, struct mbuf **mp, struct ifnet *, int dir, struct inpcb); +.Ft int +.Fn pfil_head_register "struct pfil_head *head" +.Ft int +.Fn pfil_head_unregister "struct pfil_head *head" +.Ft "struct pfil_head *" +.Fn pfil_head_get "int af" "u_long dlt" +.Ft void +.Fn pfil_add_hook "pfil_func_t" "void *arg" "int flags" "struct pfil_head *" +.Ft void +.Fn pfil_remove_hook "pfil_func_t" "void *arg" "int flags" "struct pfil_head *" +.Ft int +.Fn pfil_run_hooks "struct pfil_head *head" "struct mbuf **mp" "struct ifnet *" "int dir" "struct inpcb *" +.Ft void +.Fn pfil_rlock "struct pfil_head *" "struct rm_priotracker *" +.Ft void +.Fn pfil_runlock "struct pfil_head *" "struct rm_priotracker *" +.Ft void +.Fn pfil_wlock "struct pfil_head *" +.Ft void +.Fn pfil_wunlock "struct pfil_head *" +.Ed +.Sh DESCRIPTION +The +.Nm +framework allows for a specified function to be invoked for every +incoming or outgoing packet for a particular network I/O stream. +These hooks may be used to implement a firewall or perform packet +transformations. +.Pp +Packet filtering points are registered with +.Fn pfil_head_register . +Filtering points are identified by a key +.Pq Vt "void *" +and a data link type +.Pq Vt int +in the +.Vt pfil_head +structure. +Packet filters use the key and data link type to look up the filtering +point with which they register themselves. +The key is unique to the filtering point. +The data link type is a +.Xr bpf 4 +DLT constant indicating what kind of header is present on the packet +at the filtering point. +Each filtering point uses common per-VNET rmlock by default. +This can be changed by specifying +.Vt PFIL_FLAG_PRIVATE_LOCK +as +.Vt "flags" +field in the +.Vt pfil_head +structure. +Note that specifying private lock can break filters sharing the same +ruleset and/or state between different data link types. +Filtering points may be unregistered with the +.Fn pfil_head_unregister +function. +.Pp +Packet filters register/unregister themselves with a filtering point +with the +.Fn pfil_add_hook +and +.Fn pfil_remove_hook +functions, respectively. +The head is looked up using the +.Fn pfil_head_get +function, which takes the key and data link type that the packet filter +expects. +Filters may provide an argument to be passed to the filter when +invoked on a packet. +.Pp +When a filter is invoked, the packet appears just as if it +.Dq came off the wire . +That is, all protocol fields are in network byte order. +The filter is called with its specified argument, the pointer to the +pointer to the +.Vt mbuf +containing the packet, the pointer to the network +interface that the packet is traversing, and the direction +.Dv ( PFIL_IN +or +.Dv PFIL_OUT ) +that the packet is traveling. +The filter may change which mbuf the +.Vt "mbuf\ **" +argument references. +The filter returns an error (errno) if the packet processing is to stop, or 0 +if the processing is to continue. +If the packet processing is to stop, it is the responsibility of the +filter to free the packet. +.Pp +Every filter hook is called with +.Nm +read lock held. +All heads uses the same lock within the same VNET instance. +Packet filter can use this lock instead of own locking model to +improve performance. +Since +.Nm +uses +.Xr rmlock 9 +.Fn pfil_rlock +and +.Fn pfil_runlock +require +.Va struct rm_priotracker +to be passed as argument. +Filter can acquire and release writer lock via +.Fn pfil_wlock +and +.Fn pfil_wunlock +functions. +See +.Xr rmlock 9 +for more details. +.Sh FILTERING POINTS +Currently, filtering points are implemented for the following link types: +.Pp +.Bl -tag -width "AF_INET6" -offset XXX -compact +.It AF_INET +IPv4 packets. +.It AF_INET6 +IPv6 packets. +.It AF_LINK +Link-layer packets. +.El +.Sh RETURN VALUES +If successful, +.Fn pfil_head_get +returns the +.Vt pfil_head +structure for the given key/dlt. +The +.Fn pfil_add_hook +and +.Fn pfil_remove_hook +functions +return 0 if successful. +If called with flag +.Dv PFIL_WAITOK , +.Fn pfil_remove_hook +is expected to always succeed. +.Pp +The +.Fn pfil_head_unregister +function +might sleep! +.Sh SEE ALSO +.Xr bpf 4 , +.Xr if_bridge 4 , +.Xr rmlock 9 +.Sh HISTORY +The +.Nm +interface first appeared in +.Nx 1.3 . +The +.Nm +input and output lists were originally implemented as +.In sys/queue.h +.Dv LIST +structures; +however this was changed in +.Nx 1.4 +to +.Dv TAILQ +structures. +This change was to allow the input and output filters to be processed in +reverse order, to allow the same path to be taken, in or out of the kernel. +.Pp +The +.Nm +interface was changed in 1.4T to accept a 3rd parameter to both +.Fn pfil_add_hook +and +.Fn pfil_remove_hook , +introducing the capability of per-protocol filtering. +This was done primarily in order to support filtering of IPv6. +.Pp +In 1.5K, the +.Nm +framework was changed to work with an arbitrary number of filtering points, +as well as be less IP-centric. +.Pp +Fine-grained locking was added in +.Fx 5.2 . +.Nm +lock export was added in +.Fx 10.0 . +.Sh BUGS +When a +.Vt pfil_head +is being modified, no traffic is diverted +(to avoid deadlock). +This means that traffic may be dropped unconditionally for a short period +of time. +.Fn pfil_run_hooks +will return +.Er ENOBUFS +to indicate this. Property changes on: user/imp/camdoc/pfil.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vmem.9 =================================================================== --- user/imp/camdoc/vmem.9 (nonexistent) +++ user/imp/camdoc/vmem.9 (revision 296049) @@ -0,0 +1,315 @@ +.\" $NetBSD: vmem.9,v 1.15 2013/01/29 22:02:17 wiz Exp $ +.\" +.\" Copyright (c)2006 YAMAMOTO Takashi, +.\" 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 12, 2013 +.Dt VMEM 9 +.Os +.\" ------------------------------------------------------------ +.Sh NAME +.Nm vmem +.Nd general purpose resource allocator +.\" ------------------------------------------------------------ +.Sh SYNOPSIS +.In sys/vmem.h +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft vmem_t * +.Fn vmem_create \ +"const char *name" "vmem_addr_t base" "vmem_size_t size" "vmem_size_t quantum" \ +"vmem_size_t qcache_max" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_add \ +"vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" "int flags" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_xalloc \ +"vmem_t *vm" "const vmem_size_t size" "vmem_size_t align" \ +"const vmem_size_t phase" "const vmem_size_t nocross" \ +"const vmem_addr_t minaddr" "const vmem_addr_t maxaddr" "int flags" \ +"vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_xfree "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft int +.Fn vmem_alloc "vmem_t *vm" "vmem_size_t size" "int flags" "vmem_addr_t *addrp" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_free "vmem_t *vm" "vmem_addr_t addr" "vmem_size_t size" +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Ft void +.Fn vmem_destroy "vmem_t *vm" +.\" ------------------------------------------------------------ +.Sh DESCRIPTION +The +.Nm +is a general purpose resource allocator. +Despite its name, it can be used for arbitrary resources +other than virtual memory. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_create +creates a new vmem arena. +.Bl -tag -width qcache_max +.It Fa name +The string to describe the vmem. +.It Fa base +The start address of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa size +The size of the initial span. +Pass +.Dv 0 +if no initial span is required. +.It Fa quantum +The smallest unit of allocation. +.It Fa qcache_max +The largest size of allocations which can be served by quantum cache. +It is merely a hint and can be ignored. +.It Fa flags +Combination of +.Xr malloc 9 +wait flag and +.Nm +allocation strategy flag: +.Bl -tag -width M_FIRSTFIT +.It Dv M_FIRSTFIT +Prefer allocation performance. +.It Dv M_BESTFIT +Prefer space efficiency. +.El +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_add +adds a span of size +.Fa size +starting at +.Fa addr +to the arena. +Returns +0 +on success, +.Dv ENOMEM +on failure. +.Fa flags +is +.Xr malloc 9 +wait flag. +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_xalloc +allocates a resource from the arena. +.Bl -tag -width nocross +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa align +If zero, don't care about the alignment of the allocation. +Otherwise, request a resource segment starting at +offset +.Fa phase +from an +.Fa align +aligned boundary. +.It Fa phase +See the above description of +.Fa align . +If +.Fa align +is zero, +.Fa phase +should be zero. +Otherwise, +.Fa phase +should be smaller than +.Fa align . +.It Fa nocross +Request a resource which doesn't cross +.Fa nocross +aligned boundary. +.It Fa minaddr +Specify the minimum address which can be allocated, or +.Dv VMEM_ADDR_MIN +if the caller does not care. +.It Fa maxaddr +Specify the maximum address which can be allocated, or +.Dv VMEM_ADDR_MAX +if the caller does not care. +.It Fa flags +A bitwise OR of an allocation strategy and a +.Xr malloc 9 +wait flag. +The allocation strategy is one of +.Dv M_FIRSTFIT +and +.Dv M_BESTFIT . +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_xalloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_xfree +frees resource allocated by +.Fn vmem_xalloc +to the arena. +.Bl -tag -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must be the one returned by +.Fn vmem_xalloc . +Notably, it must not be the one from +.Fn vmem_alloc . +Otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_xalloc . +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_alloc +allocates a resource from the arena. +.Bl -tag -width flags +.It Fa vm +The arena which we allocate from. +.It Fa size +Specify the size of the allocation. +.It Fa flags +A bitwise OR of an +.Nm +allocation strategy flag (see above) and a +.Xr malloc 9 +sleep flag. +.It Fa addrp +On success, if +.Fa addrp +is not +.Dv NULL , +.Fn vmem_alloc +overwrites it with the start address of the allocated span. +.El +.Pp +.\" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +.Fn vmem_free +frees resource allocated by +.Fn vmem_alloc +to the arena. +.Bl -tag -width addr +.It Fa vm +The arena which we free to. +.It Fa addr +The resource being freed. +It must be the one returned by +.Fn vmem_alloc . +Notably, it must not be the one from +.Fn vmem_xalloc . +Otherwise, the behaviour is undefined. +.It Fa size +The size of the resource being freed. +It must be the same as the +.Fa size +argument used for +.Fn vmem_alloc . +.El +.Pp +.\" ------------------------------------------------------------ +.Fn vmem_destroy +destroys a vmem arena. +.Bl -tag -width vm +.It Fa vm +The vmem arena being destroyed. +The caller should ensure that no one will use it anymore. +.El +.\" ------------------------------------------------------------ +.Sh RETURN VALUES +.Fn vmem_create +returns a pointer to the newly allocated vmem_t. +Otherwise, it returns +.Dv NULL . +.Pp +On success, +.Fn vmem_xalloc +and +.Fn vmem_alloc +return 0. +Otherwise, +.Dv ENOMEM +is returned. +.\" ------------------------------------------------------------ +.Sh CODE REFERENCES +The +.Nm +subsystem is implemented within the file +.Pa sys/kern/subr_vmem.c . +.\" ------------------------------------------------------------ +.Sh SEE ALSO +.Xr malloc 9 +.Rs +.%A Jeff Bonwick +.%A Jonathan Adams +.%T "Magazines and Vmem: Extending the Slab Allocator to Many CPUs and Arbitrary Resources" +.%J "2001 USENIX Annual Technical Conference" +.%D 2001 +.Re +.\" ------------------------------------------------------------ +.Sh HISTORY +The +.Nm +allocator was originally implemented in +.Nx . +It was introduced in +.Fx 10.0 . +.Sh AUTHORS +.An -nosplit +Original implementation of +.Nm +was written by +.An "YAMAMOTO Takashi" . +The +.Fx +port was made by +.An "Jeff Roberson" . +.Sh BUGS +.Nm +relies on +.Xr malloc 9 , +so it cannot be used as early during system bootstrap. Property changes on: user/imp/camdoc/vmem.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DELAY.9 =================================================================== --- user/imp/camdoc/DELAY.9 (nonexistent) +++ user/imp/camdoc/DELAY.9 (revision 296049) @@ -0,0 +1,49 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 20, 2013 +.Dt DELAY 9 +.Os +.Sh NAME +.Nm DELAY +.Nd busy loop for an interval +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn DELAY "int delay" +.Sh DESCRIPTION +Delay for +.Fa delay +microseconds (1/1000000th of a second). +.Sh SEE ALSO +.Xr pause 9 +.Sh AUTHORS +This manual page was written by +.An Alfred Perlstein . Property changes on: user/imp/camdoc/DELAY.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/condvar.9 =================================================================== --- user/imp/camdoc/condvar.9 (nonexistent) +++ user/imp/camdoc/condvar.9 (revision 296049) @@ -0,0 +1,261 @@ +.\" +.\" Copyright (C) 2000 Jason Evans . 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 February 19, 2013 +.Dt CONDVAR 9 +.Os +.Sh NAME +.Nm condvar , +.Nm cv_init , +.Nm cv_destroy , +.Nm cv_wait , +.Nm cv_wait_sig , +.Nm cv_wait_unlock , +.Nm cv_timedwait , +.Nm cv_timedwait_sbt , +.Nm cv_timedwait_sig , +.Nm cv_timedwait_sig_sbt , +.Nm cv_signal , +.Nm cv_broadcast , +.Nm cv_broadcastpri , +.Nm cv_wmesg +.Nd kernel condition variable +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In sys/condvar.h +.Ft void +.Fn cv_init "struct cv *cvp" "const char *desc" +.Ft void +.Fn cv_destroy "struct cv *cvp" +.Ft void +.Fn cv_wait "struct cv *cvp" "lock" +.Ft int +.Fn cv_wait_sig "struct cv *cvp" "lock" +.Ft void +.Fn cv_wait_unlock "struct cv *cvp" "lock" +.Ft int +.Fn cv_timedwait "struct cv *cvp" "lock" "int timo" +.Ft int +.Fn cv_timedwait_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \ +"sbintime_t pr" "int flags" +.Ft int +.Fn cv_timedwait_sig "struct cv *cvp" "lock" "int timo" +.Ft int +.Fn cv_timedwait_sig_sbt "struct cv *cvp" "lock" "sbintime_t sbt" \ +"sbintime_t pr" "int flags" +.Ft void +.Fn cv_signal "struct cv *cvp" +.Ft void +.Fn cv_broadcast "struct cv *cvp" +.Ft void +.Fn cv_broadcastpri "struct cv *cvp" "int pri" +.Ft const char * +.Fn cv_wmesg "struct cv *cvp" +.Sh DESCRIPTION +Condition variables are used in conjunction with mutexes to wait for conditions +to occur. +Condition variables are created with +.Fn cv_init , +where +.Fa cvp +is a pointer to space for a +.Vt struct cv , +and +.Fa desc +is a pointer to a null-terminated character string that describes the condition +variable. +Condition variables are destroyed with +.Fn cv_destroy . +Threads wait on condition variables by calling +.Fn cv_wait , +.Fn cv_wait_sig , +.Fn cv_wait_unlock , +.Fn cv_timedwait , +or +.Fn cv_timedwait_sig . +Threads unblock waiters by calling +.Fn cv_signal +to unblock one waiter, or +.Fn cv_broadcast +or +.Fn cv_broadcastpri +to unblock all waiters. +In addition to waking waiters, +.Fn cv_broadcastpri +ensures that all of the waiters have a priority of at least +.Fa pri +by raising the priority of any threads that do not. +.Fn cv_wmesg +returns the description string of +.Fa cvp , +as set by the initial call to +.Fn cv_init . +.Pp +The +.Fa lock +argument is a pointer to either a +.Xr mutex 9 , +.Xr rwlock 9 , +or +.Xr sx 9 +lock. +A +.Xr mutex 9 +argument must be initialized with +.Dv MTX_DEF +and not +.Dv MTX_SPIN . +A thread must hold +.Fa lock +before calling +.Fn cv_wait , +.Fn cv_wait_sig , +.Fn cv_wait_unlock , +.Fn cv_timedwait , +or +.Fn cv_timedwait_sig . +When a thread waits on a condition, +.Fa lock +is atomically released before the thread is blocked, then reacquired +before the function call returns. +In addition, the thread will fully drop the +.Va Giant +mutex +(even if recursed) +while the it is suspended and will reacquire the +.Va Giant +mutex before the function returns. +The +.Fn cv_wait_unlock +function does not reacquire the lock before returning. +Note that the +.Va Giant +mutex may be specified as +.Fa lock . +However, +.Va Giant +may not be used as +.Fa lock +for the +.Fn cv_wait_unlock +function. +All waiters must pass the same +.Fa lock +in conjunction with +.Fa cvp . +.Pp +When +.Fn cv_wait , +.Fn cv_wait_sig , +.Fn cv_wait_unlock , +.Fn cv_timedwait , +and +.Fn cv_timedwait_sig +unblock, their calling threads are made runnable. +.Fn cv_timedwait +and +.Fn cv_timedwait_sig +wait for at most +.Fa timo +/ +.Dv HZ +seconds before being unblocked and returning +.Er EWOULDBLOCK ; +otherwise, they return 0. +.Fn cv_wait_sig +and +.Fn cv_timedwait_sig +return prematurely with a value of +.Er EINTR +or +.Er ERESTART +if a signal is caught, or 0 if signaled via +.Fn cv_signal +or +.Fn cv_broadcast . +.Pp +.Fn cv_timedwait_sbt +and +.Fn cv_timedwait_sig_sbt +functions take +.Fa sbt +argument instead of +.Fa timo . +It allows to specify relative or absolute unblock time with higher resolution +in form of +.Vt sbintime_t . +The parameter +.Fa pr +allows to specify wanted absolute event precision. +The parameter +.Fa flags +allows to pass additional +.Fn callout_reset_sbt +flags. +.Sh RETURN VALUES +If successful, +.Fn cv_wait_sig , +.Fn cv_timedwait , +and +.Fn cv_timedwait_sig +return 0. +Otherwise, a non-zero error code is returned. +.Pp +.Fn cv_wmesg +returns the description string that was passed to +.Fn cv_init . +.Sh ERRORS +.Fn cv_wait_sig +and +.Fn cv_timedwait_sig +will fail if: +.Bl -tag -width Er +.It Bq Er EINTR +A signal was caught and the system call should be interrupted. +.It Bq Er ERESTART +A signal was caught and the system call should be restarted. +.El +.Pp +.Fn cv_timedwait +and +.Fn cv_timedwait_sig +will fail if: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +Timeout expired. +.El +.Sh SEE ALSO +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr sema 9 , +.Xr sleep 9 , +.Xr sx 9 , +.Xr timeout 9 Property changes on: user/imp/camdoc/condvar.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mi_switch.9 =================================================================== --- user/imp/camdoc/mi_switch.9 (nonexistent) +++ user/imp/camdoc/mi_switch.9 (revision 296049) @@ -0,0 +1,158 @@ +.\" $NetBSD: ctxsw.9,v 1.2 1996/12/02 00:11:31 tls 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 November 24, 1996 +.Dt MI_SWITCH 9 +.Os +.Sh NAME +.Nm mi_switch , +.Nm cpu_switch , +.Nm cpu_throw +.Nd switch to another thread context +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft void +.Fn mi_switch "void" +.Ft void +.Fn cpu_switch "void" +.Ft void +.Fn cpu_throw "void" +.Sh DESCRIPTION +The +.Fn mi_switch +function implements the machine independent prelude to a thread context +switch. +It is called from only a few distinguished places in the kernel +code as a result of the principle of non-preemptable kernel mode execution. +The various major uses of +.Nm +can be enumerated as follows: +.Bl -enum -offset indent +.It +From within a function such as +.Xr cv_wait 9 , +.Xr mtx_lock 9 , +or +.Xr tsleep 9 +when the current thread +voluntarily relinquishes the CPU to wait for some resource or lock to become +available. +.It +After handling a trap +(e.g.\& a system call, device interrupt) +when the kernel prepares a return to user-mode execution. +This case is +typically handled by machine dependent trap-handling code after detection +of a change in the signal disposition of the current process, or when a +higher priority thread might be available to run. +The latter event is +communicated by the machine independent scheduling routines by calling +the machine defined +.Fn need_resched . +.It +In the signal handling code +(see +.Xr issignal 9 ) +if a signal is delivered that causes a process to stop. +.It +When a thread dies in +.Xr thread_exit 9 +and control of the processor can be passed to the next runnable thread. +.It +In +.Xr thread_suspend_check 9 +where a thread needs to stop execution due to the suspension state of +the process as a whole. +.El +.Pp +.Fn mi_switch +records the amount of time the current thread has been running in the +process structures and checks this value against the CPU time limits +allocated to the process +(see +.Xr getrlimit 2 ) . +Exceeding the soft limit results in a +.Dv SIGXCPU +signal to be posted to the process, while exceeding the hard limit will +cause a +.Dv SIGKILL . +.Pp +If the thread is still in the +.Dv TDS_RUNNING +state, +.Fn mi_switch +will put it back onto the run queue, assuming that +it will want to run again soon. +If it is in one of the other +states and KSE threading is enabled, the associated +.Em KSE +will be made available to any higher priority threads from the same +group, to allow them to be scheduled next. +.Pp +After these administrative tasks are done, +.Fn mi_switch +hands over control to the machine dependent routine +.Fn cpu_switch , +which will perform the actual thread context switch. +.Pp +.Fn cpu_switch +first saves the context of the current thread. +Next, it calls +.Fn choosethread +to determine which thread to run next. +Finally, it reads in the saved context of the new thread and starts to +execute the new thread. +.Pp +.Fn cpu_throw +is similar to +.Fn cpu_switch +except that it does not save the context of the old thread. +This function is useful when the kernel does not have an old thread +context to save, such as when CPUs other than the boot CPU perform their +first task switch, or when the kernel does not care about the state of the +old thread, such as in +.Fn thread_exit +when the kernel terminates the current thread and switches into a new +thread. +.Pp +To protect the +.Xr runqueue 9 , +all of these functions must be called with the +.Va sched_lock +mutex held. +.Sh SEE ALSO +.Xr cv_wait 9 , +.Xr issignal 9 , +.Xr mutex 9 , +.Xr runqueue 9 , +.Xr tsleep 9 , +.Xr wakeup 9 Property changes on: user/imp/camdoc/mi_switch.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/drbr.9 =================================================================== --- user/imp/camdoc/drbr.9 (nonexistent) +++ user/imp/camdoc/drbr.9 (revision 296049) @@ -0,0 +1,140 @@ +.\" Copyright (c) 2009 Bitgravity Inc +.\" Written by: Kip Macy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 27, 2012 +.Dt DRBR 9 +.Os +.Sh NAME +.Nm drbr , +.Nm drbr_free , +.Nm drbr_enqueue , +.Nm drbr_dequeue , +.Nm drbr_dequeue_cond , +.Nm drbr_flush , +.Nm drbr_empty , +.Nm drbr_inuse , +.Nd network driver interface to buf_ring +.Sh SYNOPSIS +.In sys/param.h +.In net/if.h +.In net/if_var.h +.Ft void +.Fn drbr_free "struct buf_ring *br" "struct malloc_type *type" +.Ft int +.Fn drbr_enqueue "struct ifnet *ifp" "struct buf_ring *br" "struct mbuf *m" +.Ft struct mbuf * +.Fn drbr_dequeue "struct ifnet *ifp" "struct buf_ring *br" +.Ft struct mbuf * +.Fn drbr_dequeue_cond "struct ifnet *ifp" "struct buf_ring *br" "int (*func) (struct mbuf *, void *)" "void *arg" +.Ft void +.Fn drbr_flush "struct ifnet *ifp" "struct buf_ring *br" +.Ft int +.Fn drbr_empty "struct ifnet *ifp" "struct buf_ring *br" +.Ft int +.Fn drbr_inuse "struct ifnet *ifp" "struct buf_ring *br" +.Sh DESCRIPTION +The +.Nm +functions provide an API to network drivers for using +.Xr buf_ring 9 +for enqueueing and dequeueing packets. +This is meant as a replacement for the IFQ interface for packet queuing. +It allows a packet to be enqueued with a single atomic and packet +dequeue to be done without any per-packet atomics as it is protected +by the driver's tx queue lock. +If +.Dv INVARIANTS +is enabled, +.Fn drbr_dequeue +will assert that the tx queue lock is held when it is called. +.Pp +The +.Fn drbr_free +function frees all the enqueued mbufs and then frees the buf_ring. +.Pp +The +.Fn drbr_enqueue +function is used to enqueue an mbuf to a buf_ring, falling back to the +ifnet's IFQ if +.Xr ALTQ 4 +is enabled. +.Pp +The +.Fn drbr_dequeue +function is used to dequeue an mbuf from a buf_ring or, if +.Xr ALTQ 4 +is enabled, from the ifnet's IFQ. +.Pp +The +.Fn drbr_dequeue_cond +function is used to conditionally dequeue an mbuf from a buf_ring based +on whether +.Fa func +returns +.Dv TRUE +or +.Dv FALSE . +.Pp +The +.Fn drbr_flush +function frees all mbufs enqueued in the buf_ring and the ifnet's IFQ. +.Pp +The +.Fn drbr_empty +function returns +.Dv TRUE +if there are no mbufs enqueued, +.Dv FALSE +otherwise. +.Pp +The +.Fn drbr_inuse +function returns the number of mbufs enqueued. +Note to users that this is intrinsically racy as there is no guarantee that +there will not be more mbufs when +.Fn drbr_dequeue +is actually called. +Provided the tx queue lock is held there will not be less. +.Sh RETURN VALUES +The +.Fn drbr_enqueue +function returns +.Er ENOBUFS +if there are no slots available in the buf_ring and +.Dv 0 +on success. +.Pp +The +.Fn drbr_dequeue +and +.Fn drbr_dequeue_cond +functions return an mbuf on success and +.Dv NULL +if the buf_ring is empty. +.Sh HISTORY +These functions were introduced in +.Fx 8.0 . Property changes on: user/imp/camdoc/drbr.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/buf_ring.9 =================================================================== --- user/imp/camdoc/buf_ring.9 (nonexistent) +++ user/imp/camdoc/buf_ring.9 (revision 296049) @@ -0,0 +1,133 @@ +.\" Copyright (c) 2009 Bitgravity Inc +.\" Written by: Kip Macy +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 27, 2012 +.Dt BUF_RING 9 +.Os +.Sh NAME +.Nm buf_ring , +.Nm buf_ring_alloc , +.Nm buf_ring_free , +.Nm buf_ring_enqueue , +.Nm buf_ring_dequeue_mc , +.Nm buf_ring_dequeue_sc , +.Nm buf_ring_count , +.Nm buf_ring_empty , +.Nm buf_ring_full , +.Nm buf_ring_peek , +.Nd multi-producer, {single, multi}-consumer lock-less ring buffer +.Sh SYNOPSIS +.In sys/param.h +.In sys/buf_ring.h +.Ft struct buf_ring * +.Fn buf_ring_alloc "int count" "struct malloc_type *type" "int flags" "struct mtx *sc_lock" +.Ft void +.Fn buf_ring_free "struct buf_ring *br" "struct malloc_type *type" +.Ft int +.Fn buf_ring_enqueue "struct buf_ring *br" "void *buf" +.Ft void * +.Fn buf_ring_dequeue_mc "struct buf_ring *br" +.Ft void * +.Fn buf_ring_dequeue_sc "struct buf_ring *br" +.Ft int +.Fn buf_ring_count "struct buf_ring *br" +.Ft int +.Fn buf_ring_empty "struct buf_ring *br" +.Ft int +.Fn buf_ring_full "struct buf_ring *br" +.Ft void * +.Fn buf_ring_peek "struct buf_ring *br" +.Sh DESCRIPTION +The +.Nm +functions provide a lock-less multi-producer and lock-less multi-consumer as +well as single-consumer ring buffer. +.Pp +The +.Fn buf_ring_alloc +function is used to allocate a buf_ring ring buffer with +.Fa count +slots using malloc_type +.Fa type +and memory flags +.Fa flags . +The single consumer interface is protected by +.Fa sc_lock . +.Pp +The +.Fn buf_ring_free +function is used to free a buf_ring. +The user is responsible for freeing any enqueued items. +.Pp +The +.Fn buf_ring_enqueue +function is used to enqueue a buffer to a buf_ring. +.Pp +The +.Fn buf_ring_dequeue_mc +function is a multi-consumer safe way of dequeueing elements from a buf_ring. +.Pp +The +.Fn buf_ring_dequeue_sc +function is a single-consumer interface to dequeue elements - requiring +the user to serialize accesses with a lock. +.Pp +The +.Fn buf_ring_count +function returns the number of elements in a buf_ring. +.Pp +The +.Fn buf_ring_empty +function returns +.Dv TRUE +if the buf_ring is empty, +.Dv FALSE +otherwise. +.Pp +The +.Fn buf_ring_full +function returns +.Dv TRUE +if no more items can be enqueued, +.Dv FALSE +otherwise. +.Pp +The +.Fn buf_ring_peek +function returns a pointer to the last element in the buf_ring if the +buf_ring is not empty, +.Dv NULL +otherwise. +.Sh RETURN VALUES +The +.Fn buf_ring_enqueue +function return +.Er ENOBUFS +if there are no available slots in the buf_ring. +.Sh HISTORY +These functions were introduced in +.Fx 8.0 . Property changes on: user/imp/camdoc/buf_ring.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/vslock.9 =================================================================== --- user/imp/camdoc/vslock.9 (nonexistent) +++ user/imp/camdoc/vslock.9 (revision 296049) @@ -0,0 +1,88 @@ +.\" $NetBSD: vslock.9,v 1.1 1996/06/15 20:47:29 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 August 29, 2012 +.Dt VSLOCK 9 +.Os +.Sh NAME +.Nm vslock , +.Nm vsunlock +.Nd lock/unlock user space addresses in memory +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In vm/vm.h +.In vm/vm_extern.h +.Ft int +.Fn vslock "void *addr" "size_t len" +.Ft void +.Fn vsunlock "void *addr" "size_t len" +.Sh DESCRIPTION +The +.Fn vslock +and +.Fn vsunlock +functions respectively lock and unlock a range of +addresses belonging to the currently running process into memory. +The actual amount of memory locked is a multiple of the machine's page size. +The starting page number is computed by truncating +.Fa addr +to the nearest preceding page boundary, and by rounding up +.Fa addr + +.Fa len +to the next page boundary. +The process context to use for this operation is taken from the +global variable +.Va curproc . +.Sh RETURN VALUES +The +.Fn vslock +function will return 0 on success, otherwise it will return +one of the errors listed below. +.Sh ERRORS +The +.Fn vslock +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa addr +and +.Fa len +parameters specify a memory range that wraps around the end of the +machine address space. +.It Bq Er ENOMEM +The size of the specified address range exceeds the system +limit on locked memory. +.It Bq Er EFAULT +Some portion of the indicated address range is not allocated. +There was an error faulting/mapping a page. +.El Property changes on: user/imp/camdoc/vslock.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211_node.9 =================================================================== --- user/imp/camdoc/ieee80211_node.9 (nonexistent) +++ user/imp/camdoc/ieee80211_node.9 (revision 296049) @@ -0,0 +1,251 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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 April 28, 2010 +.Dt IEEE80211_NODE 9 +.Os +.Sh NAME +.Nm ieee80211_node +.Nd software 802.11 stack node management functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Ft struct ieee80211_node * +.Fo ieee80211_find_rxnode +.Fa "struct ieee80211com *" +.Fa "const struct ieee80211_frame_min *" +.Fc +.\" +.Ft struct ieee80211_node * +.Fo ieee80211_find_rxnode_withkey +.Fa "struct ieee80211com *" +.Fa "const struct ieee80211_frame_min *" +.Fa "ieee80211_keyix" +.Fc +.\" +.Ft struct ieee80211_node * +.Fn ieee80211_ref_node "struct ieee80211_node *" +.\" +.Ft void +.Fn ieee80211_unref_node "struct ieee80211_node *" +.\" +.Ft void +.Fn ieee80211_free_node "struct ieee80211_node *" +.\" +.Ft void +.Fo ieee80211_iterate_nodes +.Fa "struct ieee80211_node_table *" +.Fa "ieee80211_iter_func *f" +.Fa "void *arg" +.Fc +.\" +.Ft void +.Fo ieee80211_dump_nodes +.Fa "struct ieee80211_node_table *" +.Fc +.\" +.Ft void +.Fo ieee80211_dump_node +.Fa "struct ieee80211_node *" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers maintains a database of +peer stations called the +.Dq node table +in the +.Vt ic_sta +entry of the +.Vt ieee80211com +structure. +Station mode vaps create an entry for the access point +the station is associated to. +AP mode vaps create entries for associated stations. +Adhoc and mesh mode vaps create entries for neighbor stations. +WDS mode vaps create an entry for the peer station. +Stations for all vaps reside in the same table; each node +entry has a +.Vt ni_vap +field that identifies the vap that created it. +In some instances an entry is used by multiple vaps (e.g. for +dynamic WDS a station associated to an ap vap may also be the peer +of a WDS vap). +.Pp +Node table entries are reference counted. +That is, there is a count of all long term references that determines +when an entry may be reclaimed. +References are held by every in-flight frame sent to a station to +ensure the entry is not reclaimed while the frame is queued or otherwise +held by a driver. +Routines that lookup a table entry return a +.Dq held reference +(i.e. a pointer to a table entry with the reference count incremented). +The +.Fn ieee80211_ref_node +and +.Fn ieee80211_unref_node +calls explicitly increment/decrement the reference count of a node, +but are rarely used. +Instead most callers use +.Fn ieee80211_free_node +to release a reference and, if the count goes to zero, reclaim the +table entry. +.Pp +The station table and its entries are exposed to drivers in several ways. +Each frame transmitted to a station includes a reference to the +associated node in the +.Vt m_pkthdr.rcvif +field. +This reference must be reclaimed by the driver when transmit processing +is done. +For each frame received the driver must lookup the table entry to +use in dispatching the frame +.Dq up the stack . +This lookup implicitly obtains a reference to the table entry and +the driver must reclaim the reference when frame processing is completed. +Otherwise drivers frequently inspect the contents of the +.Vt iv_bss +node when handling state machine changes as important information +is maintained in the data structure. +.Pp +The node table is opaque to drivers. +Entries may be looked up using one of the pre-defined API's or the +.Fn ieee80211_iterate_nodes +call may be used to iterate through all entries to do per-node +processing or implement some non-standard search mechanism. +Note that +.Fn ieee80211_iterate_nodes +is single-threaded per-device +and the effort processing involved is fairly +substantial so it should be used carefully. +.Pp +Two routines are provided to print the contents of nodes to the console +for debugging: +.Fn ieee80211_dump_node +displays the contents of a single node while +.Fn ieee80211_dump_nodes +displays the contents of the specified node table. +Nodes may also be displayed using +.Xr ddb 4 +with the +.Dq show node +directive and the station node table can be displayed with +.Dq show statab . +.Sh DRIVER PRIVATE STATE +Node data structures may be extended by the driver to include +driver-private state. +This is done by overriding the +.Vt ic_node_alloc +method used to allocate a node table entry. +The driver method must allocate a structure that is an extension +of the +.Vt ieee80211_node +structure. +For example the +.Xr iwi 4 +driver defines a private node structure as: +.Bd -literal -offset indent +struct iwi_node { + struct ieee80211_node in_node; + int in_station; +}; +.Ed +.Pp +and then provides a private allocation routine that does this: +.Bd -literal -offset indent +static struct ieee80211_node * +iwi_node_alloc(struct ieee80211vap *vap, + const uint8_t mac[IEEE80211_ADDR_LEN]) +{ + struct iwi_node *in; + + in = malloc(sizeof(struct iwi_node), M_80211_NODE, + M_NOWAIT | M_ZERO); + if (in == NULL) + return NULL; + in->in_station = -1; + return &in->in_node; +} +.Ed +.Pp +Note that when reclaiming a node allocated by the driver the +.Dq parent method +must be called to ensure +.Nm net80211 +state is reclaimed; for example: +.Bd -literal -offset indent +static void +iwi_node_free(struct ieee80211_node *ni) +{ + struct ieee80211com *ic = ni->ni_ic; + struct iwi_softc *sc = ic->ic_ifp->if_softc; + struct iwi_node *in = (struct iwi_node *)ni; + + if (in->in_station != -1) + free_unr(sc->sc_unr, in->in_station); + sc->sc_node_free(ni); /* invoke net80211 free handler */ +} +.Ed +.Pp +Beware that care must be taken to avoid holding references that +might cause nodes from being reclaimed. +.Nm net80211 +will reclaim a node when the last reference is reclaimed in +its data structures. +However if a driver holds additional references then +.Nm net80211 +will not recognize this and table entries will not be reclaimed. +Such references should not be needed if the driver overrides the +.Vt ic_node_cleanup +and/or +.Vt ic_node_free +methods. +.Sh KEY TABLE SUPPORT +Node table lookups are typically done using a hash of the stations' +mac address. +When receiving frames this is sufficient to find the node table entry +for the transmitter. +But some devices also identify the sending station in the device +state received with each frame and this data can be used to optimize +lookups on receive using a companion table called the +.Dq keytab . +This table records a separate node table reference that can be fetched +without any locking using the table index. +This logic is handled with the +.Fn ieee80211_find_rxnode_withkey +call: if a keytab entry is found using the specified index then it is +returned directly; otherwise a normal lookup is done and the keytab +entry is written using the specified index. +If the specified index is +.Dv IEEE80211_KEYIX_NONE +then a normal lookup is done without a table update. +.Sh SEE ALSO +.Xr ddb 9 , +.Xr ieee80211 9 , +.Xr ieee80211_proto 9 Property changes on: user/imp/camdoc/ieee80211_node.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/rtalloc.9 =================================================================== --- user/imp/camdoc/rtalloc.9 (nonexistent) +++ user/imp/camdoc/rtalloc.9 (revision 296049) @@ -0,0 +1,282 @@ +.\" +.\" Copyright 1996 Massachusetts Institute of Technology +.\" +.\" Permission to use, copy, modify, and distribute this software and +.\" its documentation for any purpose and without fee is hereby +.\" granted, provided that both the above copyright notice and this +.\" permission notice appear in all copies, that both the above +.\" copyright notice and this permission notice appear in all +.\" supporting documentation, and that the name of M.I.T. not be used +.\" in advertising or publicity pertaining to distribution of the +.\" software without specific, written prior permission. M.I.T. makes +.\" no representations about the suitability of this software for any +.\" purpose. It is provided "as is" without express or implied +.\" warranty. +.\" +.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS +.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE, +.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT +.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF +.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT +.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 4, 2012 +.Dt RTALLOC 9 +.Os +.Sh NAME +.Nm rtalloc1_fib , +.Nm rtalloc_ign_fib , +.Nm rtalloc_fib +.Nd look up a route in the kernel routing table +.Sh SYNOPSIS +.In sys/types.h +.In sys/socket.h +.In net/route.h +.Ft "struct rtentry *" +.Fn rtalloc1_fib "struct sockaddr *dst" "int report" "u_long flags" "u_int fibnum" +.Ft void +.Fn rtalloc_fib "struct route *ro" "u_int fibnum" +.Ft void +.Fn rtalloc_ign_fib "struct route *ro" "u_long flags" "u_int fibnum" +.Fn RTFREE_LOCKED "struct rt_entry *rt" +.Fn RTFREE "struct rt_entry *rt" +.Fn RT_LOCK "struct rt_entry *rt" +.Fn RT_UNLOCK "struct rt_entry *rt" +.Fn RT_ADDREF "struct rt_entry *rt" +.Fn RT_REMREF "struct rt_entry *rt" +.Fn RO_RTFREE "struct route *ro" +.Ft void +.Fn rtfree "struct rt_entry *rt" +.Ft "struct rtentry *" +.Fn rtalloc1 "struct sockaddr *dst" "int report" "u_long flags" +.Ft void +.Fn rtalloc "struct route *ro" +.Ft void +.Fn rtalloc_ign "struct route *ro" "u_long flags" +.Pp +.Cd options RADIX_MPATH +.Sh DESCRIPTION +The kernel uses a radix tree structure to manage routes for the +networking subsystem. +If compiled with +.Cd options RADIX_MPATH +kernel may maintain several independent forwarding information databases (FIBs). +The +.Fn rtalloc +family of routines is used by protocols to query these structures for a +route corresponding to a particular end-node address, and to cause +certain protocol\- and interface-specific actions to take place. +.Pp +The +.Fn rtalloc1_fib +function is the most general form of +.Fn rtalloc , +and all of the other forms are implemented as calls to it. +It takes a +.Fa "struct sockaddr *" +directly as the +.Fa dst +argument. +The second argument, +.Fa report , +controls whether the routing sockets are notified when a lookup fails. +The third argument, +.Fa flags , +is a combination of +the following values: +.Bl -item -offset indent +.It +.Dv RTF_RNH_LOCKED +indicates that the radix tree lock is already held +.El +.Pp +The last argument +.Fa fibnum +specifies number of forwarding information database (FIB) on which +the lookup should be performed. +In case of success the +.Fn rtalloc1_fib +function returns a pointer to a locked +.Vt "struct rtentry" +with an additional reference. +.Pp +The +.Fn rtalloc_fib +is the most simple variant. +Its main argument is +.Fa ro , +a pointer to a +.Fa "struct route" , +which is defined as follows: +.Bd -literal -offset indent +struct route { + struct rtentry *ro_rt; + struct llentry *ro_lle; + struct sockaddr ro_dst; +}; +.Ed +.Pp +Thus, this function can only be used for address families which are +smaller than the default +.Ft "struct sockaddr" . +Before calling +.Fn rtalloc_fib +for the first time, callers should ensure that unused bits of the +structure are set to zero. +The second argument +.Fa fibnum +is FIB number. +In case of success of the +.Fn rtalloc_fib +the +.Fa ro_rt +points to a valid and unlocked +.Xr rtentry 9 , +which has an additional reference put on it, freeing which is +responsibility of the caller. +On subsequent calls, +.Fn rtalloc_fib +returns without performing a lookup if +.Fa ro->ro_rt +is non-null and the +.Dv RTF_UP +flag is set in the rtentry's +.Fa rt_flags +field. +.Pp +The +.Fn rtalloc_ign_fib +function is the same as the +.Fn rtalloc_fib , +but there is additional +.Fa flags +argument, which is same as in +.Fn rtalloc1_fib . +.Pp +The +.Fn RTFREE_LOCKED +macro is used to unref and possibly free a locked routing entry +with one our reference, for example previously allocated by +.Fn rtalloc1_fib . +.Pp +The +.Fn RTFREE +macro is used to unref and possibly free an unlocked route entries with +one our reference, for example previously allocated by +.Fn rtalloc_fib +or +.Fn rtalloc_ign_fib . +.Pp +Both +.Fn RTFREE_LOCKED +and +.Fn RTFREE +macros decrement the reference count on the routing table entry, +and proceed with actual freeing if the reference count has reached zero. +.Pp +The +.Fn RT_LOCK +macro is used to lock a routing table entry. +.Pp +The +.Fn RT_UNLOCK +macro is used to unlock a routing table entry. +.Pp +The +.Fn RT_ADDREF +macro increments the reference count on a previously locked route entry. +It should be used whenever a reference to an +.Xr rtentry 9 +is going to be stored outside the routing table. +.Pp +The +.Fn RT_REMREF +macro decrements the reference count on a previously locked route entry. +Its usage is contrary to +.Fn RT_ADDREF . +.Pp +The +.Fn RO_RTFREE +macro is used to free route entry that is referenced by struct route. +At certain circumstances the latter may not hold a reference on rtentry, +and +.Fn RO_RTFREE +treats such routes correctly. +.Pp +The +.Fn rtfree +function does the actual free of the routing table entry, and shouldn't +be called directly by facilities, that just perform routing table lookups. +.Sh LEGACY INTERFACE +Prior to introduction of multiple routing tables functions did not +require the +.Fa "u_int fibnum" +argument. +Legacy +.Fn rtalloc1 , +.Fn rtalloc +and +.Fn rtalloc_ign +functions are kept for compatibility, and are equivalent to +calling new interface with +.Fa fibnum +argument equal to +.Va 0 , +which implies default forwarding table. +.Sh RETURN VALUES +The +.Fn rtalloc1_fib +function returns a pointer to a locked routing-table entry if it succeeds, +otherwise a null pointer. +The +.Fn rtalloc_fib +and +.Fn rtalloc_ign_fib +functions do not return a value, but they fill in the +.Fa *ro_rt +member of the +.Fa *ro +argument with a pointer to an unlocked routing-table entry if they +succeed, otherwise a null pointer. +In a case of success all functions put a reference on the +routing-table entry, freeing of which is responsibility of the caller. +Lack of a route should in most cases be +translated to the +.Xr errno 2 +value +.Er EHOSTUNREACH . +.Sh SEE ALSO +.Xr route 4 , +.Xr rtentry 9 +.Sh HISTORY +The +.Nm rtalloc +facility first appeared in +.Bx 4.2 , +although with much different internals. +The +.Fn rtalloc_ign +function and the +.Fa flags +argument to +.Fn rtalloc1 +first appeared in +.Fx 2.0 . +Routing table locking was introduced in +.Fx 5.2 . +Multiple routing tables were introduced in +.Fx 8.0 . +.Sh AUTHORS +The original version of this manual page was written by +.An -nosplit +.An "Garrett Wollman" . +It was significantly updated by +.An "Gleb Smirnoff" . Property changes on: user/imp/camdoc/rtalloc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bpf.9 =================================================================== --- user/imp/camdoc/bpf.9 (nonexistent) +++ user/imp/camdoc/bpf.9 (revision 296049) @@ -0,0 +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). +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 . Property changes on: user/imp/camdoc/bpf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_GETEXTATTR.9 =================================================================== --- user/imp/camdoc/VOP_GETEXTATTR.9 (nonexistent) +++ user/imp/camdoc/VOP_GETEXTATTR.9 (revision 296049) @@ -0,0 +1,133 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001, 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, 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 23, 1999 +.Dt VOP_GETEXTATTR 9 +.Os +.Sh NAME +.Nm VOP_GETEXTATTR +.Nd retrieve named extended attribute from a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Ft int +.Fo VOP_GETEXTATTR +.Fa "struct vnode *vp" +.Fa "int attrnamespace" +.Fa "const char *name" +.Fa "struct uio *uio" +.Fa "size_t *size" +.Fa "struct ucred *cred" +.Fa "struct thread *td" +.Fc +.Sh DESCRIPTION +This vnode call may be used to retrieve a specific named extended attribute +from a file or directory. +.Pp +Its arguments are: +.Bl -tag -width ".Fa attrnamespace" +.It Fa vp +The vnode of the file or directory. +.It Fa attrnamespace +Integer constant indicating which extended attribute namespace the attribute +name is present in. +.It Fa name +Pointer to a null-terminated character string containing the attribute name. +.It Fa uio +The location of the data to be read. +.It Fa size +If not +.Dv NULL , +on return it will contain the number of bytes required to read all of the +attribute data. +In most cases +.Fa uio +will be +.Dv NULL +when +.Fa size +is not, and vice versa. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread requesting the extended attribute. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This +.Fa cred +setting might be used to allow the kernel to authorize extended attribute +retrieval that the active process might not be permitted to do. +.Pp +Extended attribute semantics may vary by file system implementing the call. +More information on extended attributes may be found in +.Xr extattr 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +On success, zero will be returned, and the uio structure will be updated to +reflect data read. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOATTR +The requested attribute was not defined for this vnode. +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENXIO +The request was not valid in this file system for the specified vnode and +attribute name. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EFAULT +The uio structure refers to an invalid userspace address. +.It Bq Er EINVAL +The +.Fa name , +.Fa namespace , +or +.Fa uio +argument is invalid. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_GETEXTATTR . +.El +.Sh SEE ALSO +.Xr extattr 9 , +.Xr vnode 9 , +.Xr VOP_LISTEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 +.Sh BUGS +By passing in the empty string as the attribute name, some file systems +will return a list of defined names on the target vnode for the +requested namespace. +This is a bad API, and will be replaced by an explicit VOP. Property changes on: user/imp/camdoc/VOP_GETEXTATTR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_SETEXTATTR.9 =================================================================== --- user/imp/camdoc/VOP_SETEXTATTR.9 (nonexistent) +++ user/imp/camdoc/VOP_SETEXTATTR.9 (revision 296049) @@ -0,0 +1,119 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001 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 December 23, 1999 +.Dt VOP_SETEXTATTR 9 +.Os +.Sh NAME +.Nm VOP_SETEXTATTR +.Nd set named extended attribute for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Ft int +.Fn VOP_SETEXTATTR "struct vnode *vp" "int attrnamespace" "const char *name" "struct uio *uio" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to set specific named extended attribute for a +file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa attrnamespace +Integer constant indicating which extended attribute namespace the attribute +name is present in. +.It Fa name +Pointer to a null-terminated character string containing the attribute name. +.It Fa uio +The location of the data to be read or written. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread setting the extended attribute. +.El +.Pp +The uio structure is used in a manner similar to the argument of the same +name in +.Xr VOP_WRITE 9 . +However, as extended attributes provide a strict "name=value" semantic, +non-zero offsets will be rejected. +.Pp +The +.Fa uio +pointer may be +.Dv NULL +to indicate that the specified extended attribute should be deleted. +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This +.Fa cred +setting might be used to allow the kernel to authorize extended attribute +changes that the active process might not be permitted to make. +.Pp +Extended attribute semantics may vary by file system implementing the call. +More information on extended attributes may be found in +.Xr extattr 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the extended attribute is successfully set, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENXIO +The request was not valid in this file system for the specified vnode and +attribute name. +.It Bq Er ENOMEM +Insufficient memory available to fulfill the request. +.It Bq Er EFAULT +The uio structure refers to an invalid userspace address. +.It Bq Er EINVAL +The name, namespace, or uio argument is invalid. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_SETEXTATTR . +.It Bq Er ENOSPC +The file system is out of space. +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr extattr 9 , +.Xr vnode 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_LISTEXTATTR 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . Property changes on: user/imp/camdoc/VOP_SETEXTATTR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_generic_print_child.9 =================================================================== --- user/imp/camdoc/bus_generic_print_child.9 (nonexistent) +++ user/imp/camdoc/bus_generic_print_child.9 (revision 296049) @@ -0,0 +1,65 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt BUS_GENERIC_PRINT_CHILD 9 +.Os +.Sh NAME +.Nm bus_generic_print_child +.Nd generic implementation of +.Dv DEVICE_PRINT_CHILD +for busses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_print_child "device_t dev" "device_t child" +.Sh DESCRIPTION +This implementation prints out the default device announcement message. +Given device 'foo0' on bus 'bar0' where foo0 has the name "FooCard 1234" the +following would be printed: +.Pp +foo0: on bar0 +.Pp +bus_generic_print_child itself calls two functions +.Fn bus_print_child_header +and +.Fn bus_print_child_footer . +The former prints "foo0: " and the latter "on bar0". +These routines should be used if possible in your own code if +.Fn bus_generic_print_child +does not completely suit your needs. +.Sh RETURN VALUES +The number of characters output. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/bus_generic_print_child.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/byteorder.9 =================================================================== --- user/imp/camdoc/byteorder.9 (nonexistent) +++ user/imp/camdoc/byteorder.9 (revision 296049) @@ -0,0 +1,169 @@ +.\" Copyright (c) 2002 Mike Barcroft +.\" 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 April 29, 2002 +.Dt BYTEORDER 9 +.Os +.Sh NAME +.Nm bswap16 , bswap32 , bswap64 , +.Nm be16toh , be32toh , be64toh , htobe16 , htobe32 , htobe64 , +.Nm htole16 , htole32 , htole64 , le16toh , le32toh , le64toh , +.Nm be16enc , be16dec , be32enc , be32dec , be64enc , be64dec , +.Nm le16enc , le16dec , le32enc , le32dec , le64enc , le64dec +.Nd byte order operations +.Sh SYNOPSIS +.In sys/endian.h +.Ft uint16_t +.Fn bswap16 "uint16_t int16" +.Ft uint32_t +.Fn bswap32 "uint32_t int32" +.Ft uint64_t +.Fn bswap64 "uint64_t int64" +.Ft uint16_t +.Fn be16toh "uint16_t big16" +.Ft uint32_t +.Fn be32toh "uint32_t big32" +.Ft uint64_t +.Fn be64toh "uint64_t big64" +.Ft uint16_t +.Fn htobe16 "uint16_t host16" +.Ft uint32_t +.Fn htobe32 "uint32_t host32" +.Ft uint64_t +.Fn htobe64 "uint64_t host64" +.Ft uint16_t +.Fn htole16 "uint16_t host16" +.Ft uint32_t +.Fn htole32 "uint32_t host32" +.Ft uint64_t +.Fn htole64 "uint64_t host64" +.Ft uint16_t +.Fn le16toh "uint16_t little16" +.Ft uint32_t +.Fn le32toh "uint32_t little32" +.Ft uint64_t +.Fn le64toh "uint64_t little64" +.Ft uint16_t +.Fn be16dec "const void *" +.Ft uint32_t +.Fn be32dec "const void *" +.Ft uint64_t +.Fn be64dec "const void *" +.Ft uint16_t +.Fn le16dec "const void *" +.Ft uint32_t +.Fn le32dec "const void *" +.Ft uint64_t +.Fn le64dec "const void *" +.Ft void +.Fn be16enc "void *" uint16_t +.Ft void +.Fn be32enc "void *" uint32_t +.Ft void +.Fn be64enc "void *" uint64_t +.Ft void +.Fn le16enc "void *" uint16_t +.Ft void +.Fn le32enc "void *" uint32_t +.Ft void +.Fn le64enc "void *" uint64_t +.Sh DESCRIPTION +The +.Fn bswap16 , +.Fn bswap32 , +and +.Fn bswap64 +functions return a byte order swapped integer. +On big endian systems, the number is converted to little endian byte order. +On little endian systems, the number is converted to big endian byte order. +.Pp +The +.Fn be16toh , +.Fn be32toh , +and +.Fn be64toh +functions return a big endian byte ordered integer +converted to the system's native byte order. +The return value will be the same as the argument on big endian systems. +.Pp +The +.Fn le16toh , +.Fn le32toh , +and +.Fn le64toh +functions return a little endian byte ordered integer +converted to the system's native byte order. +The return value will be the same as the argument on little endian systems. +.Pp +The +.Fn htobe16 , +.Fn htobe32 , +and +.Fn htobe64 +functions return an integer in the system's native +byte order converted to big endian byte order. +The return value will be the same as the argument on big endian systems. +.Pp +The +.Fn htole16 , +.Fn htole32 , +and +.Fn htole64 +functions return a integer in the system's native +byte order converted to little endian byte order. +The return value will be the same as the argument on little endian systems. +.Pp +The +.Fn be16enc , +.Fn be16dec , +.Fn be32enc , +.Fn be32dec , +.Fn be64enc , +.Fn be64dec , +.Fn le16enc , +.Fn le16dec , +.Fn le32enc , +.Fn le32dec , +.Fn le64enc , +and +.Fn le64dec +functions encode and decode integers to/from byte strings on any alignment +in big/little endian format. +.Sh SEE ALSO +.Xr byteorder 3 +.Sh HISTORY +The +.Fn hto* +and +.Fn *toh +functions first appeared in +.Fx 5.0 , +and were originally developed by the +.Nx +project. +.Pp +The encode/decode functions first appeared in +.Fx 5.1 . Property changes on: user/imp/camdoc/byteorder.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_get_maxunit.9 =================================================================== --- user/imp/camdoc/devclass_get_maxunit.9 (nonexistent) +++ user/imp/camdoc/devclass_get_maxunit.9 (revision 296049) @@ -0,0 +1,66 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 10, 2010 +.Dt DEVCLASS_GET_MAXUNIT 9 +.Os +.Sh NAME +.Nm devclass_get_maxunit +.Nd find the maximum unit number in the class +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_maxunit "devclass_t dc" +.Sh DESCRIPTION +Returns the next unit number to be allocated to device instances in the +.Dv devclass . +This is one greater than the highest currently allocated unit. +.Sh RETURN VALUES +The +.Fn devclass_get_maxunit +function returns -1 if +.Fa dc +is +.Dv NULL , +otherwise it returns the next unit +number in +.Fa dc's +devclass. +.Sh ERRORS +None. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . +.Sh BUGS +The name is confusing since it is one greater than the maximum unit. Property changes on: user/imp/camdoc/devclass_get_maxunit.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_find_child.9 =================================================================== --- user/imp/camdoc/device_find_child.9 (nonexistent) +++ user/imp/camdoc/device_find_child.9 (revision 296049) @@ -0,0 +1,62 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 8, 2005 +.Dt DEVICE_FIND_CHILD 9 +.Os +.Sh NAME +.Nm device_find_child +.Nd search for a child of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn device_find_child "device_t dev" "const char *classname" "int unit" +.Sh DESCRIPTION +This function looks for a specific child of +.Dv dev +with the given +.Fa classname +and +.Fa unit . +If +.Fa unit +is \-1, it returns the first child of +.Fa dev +with a matching +.Fa classname +(that is, the one with the lowest unit). +.Sh RETURN VALUES +If it exists, the child device is returned, otherwise NULL. +.Sh SEE ALSO +.Xr device_add_child 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_find_child.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211_proto.9 =================================================================== --- user/imp/camdoc/ieee80211_proto.9 (nonexistent) +++ user/imp/camdoc/ieee80211_proto.9 (revision 296049) @@ -0,0 +1,241 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 4, 2009 +.Dt IEEE80211_PROTO 9 +.Os +.Sh NAME +.Nm ieee80211_proto +.Nd 802.11 state machine support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft void +.Fn ieee80211_start_all "struct ieee80211com *" +.Ft void +.Fn ieee80211_stop_all "struct ieee80211com *" +.Ft void +.Fn ieee80211_suspend_all "struct ieee80211com *" +.Ft void +.Fn ieee80211_resume_all "struct ieee80211com *" +.Pp +.Dv enum ieee80211_state ; +.Ft int +.Fn ieee80211_new_state "struct ieee80211vap *" "enum ieee80211_state" "int" +.Pp +.Ft void +.Fn ieee80211_wait_for_parent "struct ieee80211com *" +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers uses a state machine +to control operation of vaps. +These state machines vary according to the vap operating mode. +Station mode state machines follow the 802.11 MLME states +in the protocol specification. +Other state machines are simpler and reflect operational work +such as scanning for a BSS or automatically selecting a channel to +operate on. +When multiple vaps are operational the state machines are used to +coordinate operation such as choosing a channel. +The state machine mechanism also serves to bind the +.Nm net80211 +layer to a driver; this is described more below. +.Pp +The following states are defined for state machines: +.Bl -tag -width IEEE80211_S_ASSOC +.It Dv IEEE80211_S_INIT +Default/initial state. +A vap in this state should not hold any dynamic state (e.g. entries +for associated stations in the node table). +The driver must quiesce the hardware; e.g. there should be no +interrupts firing. +.It Dv IEEE80211_S_SCAN +Scanning for a BSS or choosing a channel to operate on. +Note that scanning can also take place in other states (e.g. when +background scanning is active); this state is entered when +initially bringing a vap to an operational state or after an +event such as a beacon miss (in station mode). +.It Dv IEEE80211_S_AUTH +Authenticating to an access point (in station mode). +This state is normally reached from +.Dv IEEE80211_S_SCAN +after selecting a BSS, but may also be reached from +.Dv IEEE80211_S_ASSOC +or +.Dv IEEE80211_S_RUN +if the authentication handshake fails. +.It Dv IEEE80211_S_ASSOC +Associating to an access point (in station mode). +This state is reached from +.Dv IEEE80211_S_AUTH +after successfully authenticating or from +.Dv IEEE80211_S_RUN +if a DisAssoc frame is received. +.It Dv IEEE80211_S_CAC +Doing Channel Availability Check (CAC). +This state is entered only when DFS is enabled and the channel selected +for operation requires CAC. +.It Dv IEEE80211_S_RUN +Operational. +In this state a vap can transmit data frames, accept requests for +stations associating, etc. +Beware that data traffic is also gated by whether the associated +.Dq port +is authorized. +When WPA/802.11i/802.1x is operational authorization may happen separately; +e.g. in station mode +.Xr wpa_supplicant 8 +must complete the handshakes and plumb the necessary keys before a port +is authorized. +In this state a BSS is operational and associated state is valid and may +be used; e.g. +.Vt ic_bss +and +.Vt ic_bsschan +are guaranteed to be usable. +.It Dv IEEE80211_S_CSA +Channel Switch Announcement (CSA) is pending. +This state is reached only from +.Dv IEEE80211_S_RUN +when either a CSA is received from an access point (in station mode) +or the local station is preparing to change channel. +In this state traffic may be muted depending on the Mute setting in the CSA. +.It Dv IEEE80211_S_SLEEP +Asleep to save power (in station mode). +This state is reached only from +.Dv IEEE80211_S_RUN +when power save operation is enabled and the local station is deemed +sufficiently idle to enter low power mode. +.El +.Pp +Note that states are ordered (as shown above); +e.g. a vap must be in the +.Dv IEEE80211_S_RUN +or +.Dq greater +before it can transmit frames. +Certain +.Nm net80211 +data are valid only in certain states; e.g. the +.Vt iv_bsschan +that specifies the channel for the operating BSS should never be used +except in +.Dv IEEE80211_S_RUN +or greater. +.Sh STATE CHANGES +State machine changes are typically handled internal to the +.Nm net80211 +layer in response to +.Xr ioctl 2 +requests, received frames, or external events such as a beacon miss. +The +.Fn ieee80211_new_state +function is used to initiate a state machine change on a vap. +The new state and an optional argument are supplied. +The request is initially processed to handle coordination of multiple vaps. +For example, only one vap at a time can be scanning, if multiple vaps +request a change to +.Dv IEEE80211_S_SCAN +the first will be permitted to run and the others will be +.Em deferred +until the scan operation completes at which time the selected channel +will be adopted. +Similarly +.Nm net80211 +handles coordination of combinations of vaps such as an AP and station vap +where the station may need to roam to follow the AP it is associated to +(dragging along the AP vap to the new channel). +Another important coordination is the handling of +.Dv IEEE80211_S_CAC +and +.Dv IEEE80211_S_CSA . +No more than one vap can ever be actively changing state at a time. +In fact +.Nm net80211 +single-threads the state machine logic in a dedicated +.Xr taskqueue 9 +thread that is also used to synchronize work such as scanning and +beacon miss handling. +.Pp +After multi-vap scheduling/coordination is done the per-vap +.Vt iv_newstate +method is called to carry out the state change work. +Drivers use this entry to setup private state and then dispatch +the call to the +.Nm net80211 +layer using the previously defined method pointer (in OOP-parlance they +call the +.Dq super method +). +.Pp +.Nm net80211 +handles two state changes specially. +On transition to +.Dv IEEE80211_S_RUN +the +.Dv IFF_DRV_OACTIVE +bit on the vap's transmit queue is cleared so traffic can flow. +On transition to +.Dv IEEE80211_S_INIT +any state in the scan cache associated with the vap is flushed +and any frames pending on the transmit queue are flushed. +.Sh DRIVER INTEGRATION +Drivers are expected to override the +.Vt iv_newstate +method to interpose their own code and handle setup work required +by state changes. +Otherwise drivers must call +.Fn ieee80211_start_all +in response to being marked up through an +.Dv SIOCSIFFLAGS +ioctl request and they should use +.Fn ieee80211_suspend_all +and +.Fn ieee80211_resume_all +to implement suspend/resume support. +.Pp +There is also an +.Fn ieee80211_stop_all +call to force all vaps to an +.Dv IEEE80211_S_INIT +state but this should not be needed by a driver; control is usually +handled by +.Nm net80211 +or, in the case of card eject or vap destroy, +work will be initiated outside the driver. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr wpa_supplicant 8 , +.Xr ieee80211 9 , +.Xr ifnet 9 , +.Xr taskqueue 9 +.Sh HISTORY +The state machine concept was part of the original +.Nm ieee80211 +code base that first appeared in +.Nx 1.5 . Property changes on: user/imp/camdoc/ieee80211_proto.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_GETACL.9 =================================================================== --- user/imp/camdoc/VOP_GETACL.9 (nonexistent) +++ user/imp/camdoc/VOP_GETACL.9 (revision 296049) @@ -0,0 +1,96 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001 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 December 23, 1999 +.Dt VOP_GETACL 9 +.Os +.Sh NAME +.Nm VOP_GETACL +.Nd retrieve access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_GETACL "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to retrieve the access control list (ACL) from a +file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to retrieve. +.It Fa aclp +A pointer to an ACL structure to receive the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread requesting the ACL. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This cred setting might be used to allow the kernel to authorize ACL +retrieval that the active process might not be permitted to do. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel may be found in +.Xr acl 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the +.Fa aclp +pointer will point to a valid ACL, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode. +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_GETACL . +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . Property changes on: user/imp/camdoc/VOP_GETACL.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_SETACL.9 =================================================================== --- user/imp/camdoc/VOP_SETACL.9 (nonexistent) +++ user/imp/camdoc/VOP_SETACL.9 (revision 296049) @@ -0,0 +1,105 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001 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 December 23, 1999 +.Dt VOP_SETACL 9 +.Os +.Sh NAME +.Nm VOP_SETACL +.Nd set the access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_SETACL "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to set the access control list (ACL) for a file +or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to set. +.It Fa aclp +A pointer to an ACL structure from which to retrieve the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread setting the ACL. +.El +.Pp +The +.Fa aclp +pointer may be +.Dv NULL +to indicate that the specified ACL should be deleted. +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This cred setting might be used to allow the kernel to authorize ACL +changes that the active process might not be permitted to make. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel +may be found in +.Xr acl 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the ACL is successfully set, then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode, or the ACL data is invalid. +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_SETACL . +.It Bq Er ENOSPC +The file system is out of space. +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_ACLCHECK 9 , +.Xr VOP_GETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . Property changes on: user/imp/camdoc/VOP_SETACL.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/swi.9 =================================================================== --- user/imp/camdoc/swi.9 (nonexistent) +++ user/imp/camdoc/swi.9 (revision 296049) @@ -0,0 +1,250 @@ +.\" Copyright (c) 2000-2001 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 April 19, 2012 +.Dt SWI 9 +.Os +.Sh NAME +.Nm swi_add , +.Nm swi_remove , +.Nm swi_sched +.Nd register and schedule software interrupt handlers +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/interrupt.h +.Vt "extern struct intr_event *tty_intr_event" ; +.Vt "extern struct intr_event *clk_intr_event" ; +.Vt "extern void *vm_ih" ; +.Ft int +.Fo swi_add +.Fa "struct intr_event **eventp" +.Fa "const char *name" +.Fa "driver_intr_t handler" +.Fa "void *arg" +.Fa "int pri" +.Fa "enum intr_type flags" +.Fa "void **cookiep" +.Fc +.Ft int +.Fn swi_remove "void *cookie" +.Ft void +.Fn swi_sched "void *cookie" "int flags" +.Sh DESCRIPTION +These functions are used to register and schedule software interrupt handlers. +Software interrupt handlers are attached to a software interrupt thread, just +as hardware interrupt handlers are attached to a hardware interrupt thread. +Multiple handlers can be attached to the same thread. +Software interrupt handlers can be used to queue up less critical processing +inside of hardware interrupt handlers so that the work can be done at a later +time. +Software interrupt threads are different from other kernel threads in that they +are treated as an interrupt thread. +This means that time spent executing these threads is counted as interrupt +time, and that they can be run via a lightweight context switch. +.Pp +The +.Fn swi_add +function is used to add a new software interrupt handler to a specified +interrupt event. +The +.Fa eventp +argument is an optional pointer to a +.Vt struct intr_event +pointer. +If this argument points to an existing event that holds a list of +interrupt handlers, then this handler will be attached to that event. +Otherwise a new event will be created, and if +.Fa eventp +is not +.Dv NULL , +then the pointer at that address to will be modified to point to the +newly created event. +The +.Fa name +argument is used to associate a name with a specific handler. +This name is appended to the name of the software interrupt thread that this +handler is attached to. +The +.Fa handler +argument is the function that will be executed when the handler is scheduled +to run. +The +.Fa arg +parameter will be passed in as the only parameter to +.Fa handler +when the function is executed. +The +.Fa pri +value specifies the priority of this interrupt handler relative to other +software interrupt handlers. +If an interrupt event is created, then this value is used as the vector, +and the +.Fa flags +argument is used to specify the attributes of a handler such as +.Dv INTR_MPSAFE . +The +.Fa cookiep +argument points to a +.Vt void * +cookie. +This cookie will be set to a value that uniquely identifies this handler, +and is used to schedule the handler for execution later on. +.Pp +The +.Fn swi_remove +function is used to teardown an interrupt handler pointed to by the +.Fa cookie +argument. +It detaches the interrupt handler from the associated interrupt event +and frees its memory. +.Pp +The +.Fn swi_sched +function is used to schedule an interrupt handler and its associated thread to +run. +The +.Fa cookie +argument specifies which software interrupt handler should be scheduled to run. +The +.Fa flags +argument specifies how and when the handler should be run and is a mask of one +or more of the following flags: +.Bl -tag -width SWI_DELAY +.It Dv SWI_DELAY +Specifies that the kernel should mark the specified handler as needing to run, +but the kernel should not schedule the software interrupt thread to run. +Instead, +.Fa handler +will be executed the next time that the software interrupt thread runs after +being scheduled by another event. +Attaching a handler to the clock software interrupt thread and using this flag +when scheduling a software interrupt handler can be used to implement the +functionality performed by +.Fn setdelayed +in earlier versions of +.Fx . +.El +.Pp +The +.Va tty_intr_event +and +.Va clk_intr_event +variables contain pointers to the software interrupt handlers for the tty and +clock software interrupts, respectively. +.Va tty_intr_event +is used to hang tty software interrupt handlers off of the same thread. +.Va clk_intr_event +is used to hang delayed handlers off of the clock software interrupt thread so +that the functionality of +.Fn setdelayed +can be obtained in conjunction with +.Dv SWI_DELAY . +The +.Va vm_ih +handler cookie is used to schedule software interrupt threads to run for the +VM subsystem. +.Sh RETURN VALUES +The +.Fn swi_add +and +.Fn swi_remove +functions return zero on success and non-zero on failure. +.Sh ERRORS +The +.Fn swi_add +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +.It Bq Er EINVAL +The +.Fa flags +argument specifies +.Dv INTR_ENTROPY . +.It Bq Er EINVAL +The +.Fa eventp +argument points to a hardware interrupt thread. +.It Bq Er EINVAL +Either of the +.Fa name +or +.Fa handler +arguments are +.Dv NULL . +.It Bq Er EINVAL +The +.Dv INTR_EXCL +flag is specified and the interrupt event pointed to by +.Fa eventp +already has at least one handler, or the interrupt event already has an +exclusive handler. +.El +.Pp +The +.Fn swi_remove +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +A software interrupt handler pointed to by +.Fa cookie +is +.Dv NULL . +.El +.Sh SEE ALSO +.Xr ithread 9 , +.Xr taskqueue 9 +.Sh HISTORY +The +.Fn swi_add +and +.Fn swi_sched +functions first appeared in +.Fx 5.0 . +They replaced the +.Fn register_swi +function which appeared in +.Fx 3.0 +and the +.Fn setsoft* , +and +.Fn schedsoft* +functions which date back to at least +.Bx 4.4 . +The +.Fn swi_remove +function first appeared in +.Fx 6.1 . +.Sh BUGS +Most of the global variables described in this manual page should not be +global, or at the very least should not be declared in +.In sys/interrupt.h . Property changes on: user/imp/camdoc/swi.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_children.9 =================================================================== --- user/imp/camdoc/device_get_children.9 (nonexistent) +++ user/imp/camdoc/device_get_children.9 (revision 296049) @@ -0,0 +1,62 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 23, 2008 +.Dt DEVICE_GET_CHILDREN 9 +.Os +.Sh NAME +.Nm device_get_children +.Nd get a list of devices connected to a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_get_children "device_t dev" "device_t **devlistp" "int *devcountp" +.Sh DESCRIPTION +Retrieve a list of all device instances currently connected to +.Pa dev +and return the list in +.Fa *devlistp +and the count in +.Fa *devcountp . +The memory allocated for the list should be freed using +.Fn free "*devlistp" "M_TEMP" . +.Fa devlistp +and +.Fa devcountp +are not changed when an error is returned. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_get_children.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211.9 =================================================================== --- user/imp/camdoc/ieee80211.9 (nonexistent) +++ user/imp/camdoc/ieee80211.9 (revision 296049) @@ -0,0 +1,568 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 April 28, 2010 +.Dt IEEE80211 9 +.Os +.Sh NAME +.Nm IEEE80211 +.Nd 802.11 network layer +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Ft void +.Fn ieee80211_ifattach "struct ieee80211com *ic" "const uint8_t macaddr[IEEE80211_ADDR_LEN]" +.Ft void +.Fn ieee80211_ifdetach "struct ieee80211com *ic" +.Sh DESCRIPTION +IEEE 802.11 device drivers are written to use the infrastructure provided +by the +.Nm +software layer. +This software provides a support framework for drivers that includes +ifnet cloning, state management, and a user management API by which +applications interact with 802.11 devices. +Most drivers depend on the +.Nm +layer for protocol services but devices that off-load functionality +may bypass the layer to connect directly to the device +(e.g. the +.Xr ndis 4 +emulation support does this). +.Pp +A +.Nm +device driver implements a virtual radio API that is exported to +users through network interfaces (aka vaps) that are cloned from the +underlying device. +These interfaces have an operating mode +(station, adhoc, hostap, wds, monitor, etc.) +that is fixed for the lifetime of the interface. +Devices that can support multiple concurrent interfaces allow +multiple vaps to be cloned. +This enables construction of interesting applications such as +an AP vap and one or more WDS vaps +or multiple AP vaps, each with a different security model. +The +.Nm +layer virtualizes most 802.11 state +and coordinates vap state changes including scheduling multiple vaps. +State that is not virtualized includes the current channel and +WME/WMM parameters. +Protocol processing is typically handled entirely in the +.Nm +layer with drivers responsible purely for moving data between the host +and device. +Similarly, +.Nm +handles most +.Xr ioctl 2 +requests without entering the driver; +instead drivers are notified of state changes that +require their involvement. +.Pp +The virtual radio interface defined by the +.Nm +layer means that drivers must be structured to follow specific rules. +Drivers that support only a single interface at any time must still +follow these rules. +.Sh DATA STRUCTURES +The virtual radio architecture splits state between a single per-device +.Vt ieee80211com +structure and one or more +.Vt ieee80211vap +structures. +Drivers are expected to setup various shared state in these structures +at device attach and during vap creation but otherwise should treat them +as read-only. +The +.Vt ieee80211com +structure is allocated by the +.Nm +layer as adjunct data to a device's +.Vt ifnet ; +it is accessed through the +.Vt if_l2com +structure member. +The +.Vt ieee80211vap +structure is allocated by the driver in the +.Dq vap create +method +and should be extended with any driver-private state. +This technique of giving the driver control to allocate data structures +is used for other +.Nm +data structures and should be exploited to maintain driver-private state +together with public +.Nm +state. +.Pp +The other main data structures are the station, or node, table +that tracks peers in the local BSS, and the channel table that defines +the current set of available radio channels. +Both tables are bound to the +.Vt ieee80211com +structure and shared by all vaps. +Long-lasting references to a node are counted to guard against +premature reclamation. +In particular every packet sent/received holds a node reference +(either explicitly for transmit or implicitly on receive). +.Pp +The +.Vt ieee80211com +and +.Vt ieee80211vap +structures also hold a collection of method pointers that drivers +fill-in and/or override to take control of certain operations. +These methods are the primary way drivers are bound to the +.Nm +layer and are described below. +.Sh DRIVER ATTACH/DETACH +Drivers attach to the +.Nm +layer with the +.Fn ieee80211_ifattach +function. +The driver is expected to allocate and setup any device-private +data structures before passing control. +The +.Vt ieee80211com +structure must be pre-initialized with state required to setup the +.Nm +layer: +.Bl -tag -width ic_channels +.It Dv ic_ifp +Backpointer to the physical device's ifnet. +.It Dv ic_caps +Device/driver capabilities; see below for a complete description. +.It Dv ic_channels +Table of channels the device is capable of operating on. +This is initially provided by the driver but may be changed +through calls that change the regulatory state. +.It Dv ic_nchan +Number of entries in +.Dv ic_channels . +.El +.Pp +On return from +.Fn ieee80211_ifattach +the driver is expected to override default callback functions in the +.Vt ieee80211com +structure to register it's private routines. +Methods marked with a +.Dq * +must be provided by the driver. +.Bl -tag -width ic_channels +.It Dv ic_vap_create* +Create a vap instance of the specified type (operating mode). +Any fixed BSSID and/or MAC address is provided. +Drivers that support multi-bssid operation may honor the requested BSSID +or assign their own. +.It Dv ic_vap_delete* +Destroy a vap instance created with +.Dv ic_vap_create . +.It Dv ic_getradiocaps +Return the list of calibrated channels for the radio. +The default method returns the current list of channels +(space permitting). +.It Dv ic_setregdomain +Process a request to change regulatory state. +The routine may reject a request or constrain changes (e.g. reduce +transmit power caps). +The default method accepts all proposed changes. +.It Dv ic_send_mgmt +Send an 802.11 management frame. +The default method fabricates the frame using +.Nm +state and passes it to the driver through the +.Dv ic_raw_xmit +method. +.It Dv ic_raw_xmit +Transmit a raw 802.11 frame. +The default method drops the frame and generates a message on the console. +.It Dv ic_updateslot +Update hardware state after an 802.11 IFS slot time change. +There is no default method; the pointer may be NULL in which case +it will not be used. +.It Dv ic_update_mcast +Update hardware for a change in the multicast packet filter. +The default method prints a console message. +.It Dv ic_update_promisc +Update hardware for a change in the promiscuous mode setting. +The default method prints a console message. +.It Dv ic_newassoc +Update driver/device state for association to a new AP (in station mode) +or when a new station associates (e.g. in AP mode). +There is no default method; the pointer may be NULL in which case +it will not be used. +.It Dv ic_node_alloc +Allocate and initialize a +.Vt ieee80211_node +structure. +This method cannot sleep. +The default method allocates zero'd memory using +.Xr malloc 9 . +Drivers should override this method to allocate extended storage +for their own needs. +Memory allocated by the driver must be tagged with +.Dv M_80211_NODE +to balance the memory allocation statistics. +.It Dv ic_node_free +Reclaim storage of a node allocated by +.Dv ic_node_alloc . +Drivers are expected to +.Em interpose +their own method to cleanup private state but must call through +this method to allow +.Nm +to reclaim it's private state. +.It Dv ic_node_cleanup +Cleanup state in a +.Vt ieee80211_node +created by +.Dv ic_node_alloc . +This operation is distinguished from +.Dv ic_node_free +in that it may be called long before the node is actually reclaimed +to cleanup adjunct state. +This can happen, for example, when a node must not be reclaimed +due to references held by packets in the transmit queue. +Drivers typically interpose +.Dv ic_node_cleanup +instead of +.Dv ic_node_free . +.It Dv ic_node_age +Age, and potentially reclaim, resources associated with a node. +The default method ages frames on the power-save queue (in AP mode) +and pending frames in the receive reorder queues (for stations using A-MPDU). +.It Dv ic_node_drain +Reclaim all optional resources associated with a node. +This call is used to free up resources when they are in short supply. +.It Dv ic_node_getrssi +Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for +the specified node. +This interface returns a subset of the information +returned by +.Dv ic_node_getsignal . +The default method calculates a filtered average over the last ten +samples passed in to +.Xr ieee80211_input 9 +or +.Xr ieee80211_input_all 9 . +.It Dv ic_node_getsignal +Return the RSSI and noise floor (in .5 dBm units) for a station. +The default method calculates RSSI as described above; +the noise floor returned is the last value supplied to +.Xr ieee80211_input 9 +or +.Xr ieee80211_input_all 9 . +.It Dv ic_node_getmimoinfo +Return MIMO radio state for a station in support of the +.Dv IEEE80211_IOC_STA_INFO +ioctl request. +The default method returns nothing. +.It Dv ic_scan_start* +Prepare driver/hardware state for scanning. +This callback is done in a sleepable context. +.It Dv ic_scan_end* +Restore driver/hardware state after scanning completes. +This callback is done in a sleepable context. +.It Dv ic_set_channel* +Set the current radio channel using +.Vt ic_curchan . +This callback is done in a sleepable context. +.It Dv ic_scan_curchan +Start scanning on a channel. +This method is called immediately after each channel change +and must initiate the work to scan a channel and schedule a timer +to advance to the next channel in the scan list. +This callback is done in a sleepable context. +The default method handles active scan work (e.g. sending ProbeRequest +frames), and schedules a call to +.Xr ieee80211_scan_next 9 +according to the maximum dwell time for the channel. +Drivers that off-load scan work to firmware typically use this method +to trigger per-channel scan activity. +.It Dv ic_scan_mindwell +Handle reaching the minimum dwell time on a channel when scanning. +This event is triggered when one or more stations have been found on +a channel and the minimum dwell time has been reached. +This callback is done in a sleepable context. +The default method signals the scan machinery to advance +to the next channel as soon as possible. +Drivers can use this method to preempt further work (e.g. if scanning +is handled by firmware) or ignore the request to force maximum dwell time +on a channel. +.It Dv ic_recv_action +Process a received Action frame. +The default method points to +.Xr ieee80211_recv_action 9 +which provides a mechanism for setting up handlers for each Action frame class. +.It Dv ic_send_action +Transmit an Action frame. +The default method points to +.Xr ieee80211_send_action 9 +which provides a mechanism for setting up handlers for each Action frame class. +.It Dv ic_ampdu_enable +Check if transmit A-MPDU should be enabled for the specified station and AC. +The default method checks a per-AC traffic rate against a per-vap +threshold to decide if A-MPDU should be enabled. +This method also rate-limits ADDBA requests so that requests are not +made too frequently when a receiver has limited resources. +.It Dv ic_addba_request +Request A-MPDU transmit aggregation. +The default method sets up local state and issues an +ADDBA Request Action frame. +Drivers may interpose this method if they need to setup private state +for handling transmit A-MPDU. +.It Dv ic_addb_response +Process a received ADDBA Response Action frame and setup resources as +needed for doing transmit A-MPDU. +.It Dv ic_addb_stop +Shutdown an A-MPDU transmit stream for the specified station and AC. +The default method reclaims local state after sending a DelBA Action frame. +.It Dv ic_bar_response +Process a response to a transmitted BAR control frame. +.It Dv ic_ampdu_rx_start +Prepare to receive A-MPDU data from the specified station for the TID. +.It Dv ic_ampdu_rx_stop +Terminate receipt of A-MPDU data from the specified station for the TID. +.El +.Pp +Once the +.Nm +layer is attached to a driver there are two more steps typically done +to complete the work: +.Bl -enum +.It +Setup +.Dq radiotap support +for capturing raw 802.11 packets that pass through the device. +This is done with a call to +.Xr ieee80211_radiotap_attach 9 . +.It +Do any final device setup like enabling interrupts. +.El +.Pp +State is torn down and reclaimed with a call to +.Fn ieee80211_ifdetach . +Note this call may result in multiple callbacks into the driver +so it should be done before any critical driver state is reclaimed. +On return from +.Fn ieee80211_ifdetach +all associated vaps and ifnet structures are reclaimed or inaccessible +to user applications so it is safe to teardown driver state without +worry about being re-entered. +The driver is responsible for calling +.Xr if_free 9 +on the ifnet it allocated for the physical device. +.Sh DRIVER CAPABILITIES +Driver/device capabilities are specified using several sets of flags +in the +.Vt ieee80211com +structure. +General capabilities are specified by +.Vt ic_caps . +Hardware cryptographic capabilities are specified by +.Vt ic_cryptocaps . +802.11n capabilities, if any, are specified by +.Vt ic_htcaps . +The +.Nm +layer propagates a subset of these capabilities to each vap through +the equivalent fields: +.Vt iv_caps , +.Vt iv_cryptocaps , +and +.Vt iv_htcaps . +The following general capabilities are defined: +.Bl -tag -width IEEE80211_C_8023ENCAP +.It Dv IEEE80211_C_STA +Device is capable of operating in station (aka Infrastructure) mode. +.It Dv IEEE80211_C_8023ENCAP +Device requires 802.3-encapsulated frames be passed for transmit. +By default +.Nm +will encapsulate all outbound frames as 802.11 frames (without a PLCP header). +.It Dv IEEE80211_C_FF +Device supports Atheros Fast-Frames. +.It Dv IEEE80211_C_TURBOP +Device supports Atheros Dynamic Turbo mode. +.It Dv IEEE80211_C_IBSS +Device is capable of operating in adhoc/IBSS mode. +.It Dv IEEE80211_C_PMGT +Device supports dynamic power-management (aka power save) in station mode. +.It Dv IEEE80211_C_HOSTAP +Device is capable of operating as an Access Point in Infrastructure mode. +.It Dv IEEE80211_C_AHDEMO +Device is capable of operating in Adhoc Demo mode. +In this mode the device is used purely to send/receive raw 802.11 frames. +.It Dv IEEE80211_C_SWRETRY +Device supports software retry of transmitted frames. +.It Dv IEEE80211_C_TXPMGT +Device support dynamic transmit power changes on transmitted frames; +also known as Transmit Power Control (TPC). +.It Dv IEEE80211_C_SHSLOT +Device supports short slot time operation (for 802.11g). +.It Dv IEEE80211_C_SHPREAMBLE +Device supports short preamble operation (for 802.11g). +.It Dv IEEE80211_C_MONITOR +Device is capable of operating in monitor mode. +.It Dv IEEE80211_C_DFS +Device supports radar detection and/or DFS. +DFS protocol support can be handled by +.Nm +but the device must be capable of detecting radar events. +.It Dv IEEE80211_C_MBSS +Device is capable of operating in MeshBSS (MBSS) mode +(as defined by 802.11s Draft 3.0). +.It Dv IEEE80211_C_WPA1 +Device supports WPA1 operation. +.It Dv IEEE80211_C_WPA2 +Device supports WPA2/802.11i operation. +.It Dv IEEE80211_C_BURST +Device supports frame bursting. +.It Dv IEEE80211_C_WME +Device supports WME/WMM operation +(at the moment this is mostly support for sending and receiving +QoS frames with EDCF). +.It Dv IEEE80211_C_WDS +Device supports transmit/receive of 4-address frames. +.It Dv IEEE80211_C_BGSCAN +Device supports background scanning. +.It Dv IEEE80211_C_TXFRAG +Device supports transmit of fragmented 802.11 frames. +.It Dv IEEE80211_C_TDMA +Device is capable of operating in TDMA mode. +.El +.Pp +The follow general crypto capabilities are defined. +In general +.Nm +will fall-back to software support when a device is not capable +of hardware acceleration of a cipher. +This can be done on a per-key basis. +.Nm +can also handle software +.Dv Michael +calculation combined with hardware +.Dv AES +acceleration. +.Bl -tag -width IEEE80211_C_8023ENCAP +.It Dv IEEE80211_CRYPTO_WEP +Device supports hardware WEP cipher. +.It Dv IEEE80211_CRYPTO_TKIP +Device supports hardware TKIP cipher. +.It Dv IEEE80211_CRYPTO_AES_OCB +Device supports hardware AES-OCB cipher. +.It Dv IEEE80211_CRYPTO_AES_CCM +Device supports hardware AES-CCM cipher. +.It Dv IEEE80211_CRYPTO_TKIPMIC +Device supports hardware Michael for use with TKIP. +.It Dv IEEE80211_CRYPTO_CKIP +Devices supports hardware CKIP cipher. +.El +.Pp +The follow general 802.11n capabilities are defined. +The first capabilities are defined exactly as they appear in the +802.11n specification. +Capabilities beginning with IEEE80211_HTC_AMPDU are used solely by the +.Nm +layer. +.Bl -tag -width IEEE80211_C_8023ENCAP +.It Dv IEEE80211_HTCAP_CHWIDTH40 +Device supports 20/40 channel width operation. +.It Dv IEEE80211_HTCAP_SMPS_DYNAMIC +Device supports dynamic SM power save operation. +.It Dv IEEE80211_HTCAP_SMPS_ENA +Device supports static SM power save operation. +.It Dv IEEE80211_HTCAP_GREENFIELD +Device supports Greenfield preamble. +.It Dv IEEE80211_HTCAP_SHORTGI20 +Device supports Short Guard Interval on 20MHz channels. +.It Dv IEEE80211_HTCAP_SHORTGI40 +Device supports Short Guard Interval on 40MHz channels. +.It Dv IEEE80211_HTCAP_TXSTBC +Device supports Space Time Block Convolution (STBC) for transmit. +.It Dv IEEE80211_HTCAP_RXSTBC_1STREAM +Device supports 1 spatial stream for STBC receive. +.It Dv IEEE80211_HTCAP_RXSTBC_2STREAM +Device supports 1-2 spatial streams for STBC receive. +.It Dv IEEE80211_HTCAP_RXSTBC_3STREAM +Device supports 1-3 spatial streams for STBC receive. +.It Dv IEEE80211_HTCAP_MAXAMSDU_7935 +Device supports A-MSDU frames up to 7935 octets. +.It Dv IEEE80211_HTCAP_MAXAMSDU_3839 +Device supports A-MSDU frames up to 3839 octets. +.It Dv IEEE80211_HTCAP_DSSSCCK40 +Device supports use of DSSS/CCK on 40MHz channels. +.It Dv IEEE80211_HTCAP_PSMP +Device supports PSMP. +.It Dv IEEE80211_HTCAP_40INTOLERANT +Device is intolerant of 40MHz wide channel use. +.It Dv IEEE80211_HTCAP_LSIGTXOPPROT +Device supports L-SIG TXOP protection. +.It Dv IEEE80211_HTC_AMPDU +Device supports A-MPDU aggregation. +Note that any 802.11n compliant device must support A-MPDU receive +so this implicitly means support for +.Em transmit +of A-MPDU frames. +.It Dv IEEE80211_HTC_AMSDU +Device supports A-MSDU aggregation. +Note that any 802.11n compliant device must support A-MSDU receive +so this implicitly means support for +.Em transmit +of A-MSDU frames. +.It Dv IEEE80211_HTC_HT +Device supports High Throughput (HT) operation. +This capability must be set to enable 802.11n functionality +in +.Nm . +.It Dv IEEE80211_HTC_SMPS +Device supports MIMO Power Save operation. +.It Dv IEEE80211_HTC_RIFS +Device supports Reduced Inter Frame Spacing (RIFS). +.El +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr ndis 4 , +.Xr ieee80211_amrr 9 , +.Xr ieee80211_beacon 9 , +.Xr ieee80211_bmiss 9 , +.Xr ieee80211_crypto 9 , +.Xr ieee80211_ddb 9 , +.Xr ieee80211_input 9 , +.Xr ieee80211_node 9 , +.Xr ieee80211_output 9 , +.Xr ieee80211_proto 9 , +.Xr ieee80211_radiotap 9 , +.Xr ieee80211_regdomain 9 , +.Xr ieee80211_scan 9 , +.Xr ieee80211_vap 9 , +.Xr ifnet 9 , +.Xr malloc 9 Property changes on: user/imp/camdoc/ieee80211.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211_amrr.9 =================================================================== --- user/imp/camdoc/ieee80211_amrr.9 (nonexistent) +++ user/imp/camdoc/ieee80211_amrr.9 (revision 296049) @@ -0,0 +1,194 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 4, 2009 +.Dt IEEE8021_AMRR 9 +.Os +.Sh NAME +.Nm ieee80211_amrr +.Nd 802.11 network driver transmit rate control support +.Sh SYNOPSIS +.In net80211/ieee80211_amrr.h +.Ft void +.Fo ieee80211_amrr_init +.Fa "struct ieee80211_amrr *" +.Fa "struct ieee80211vap *" +.Fa "int amin" +.Fa "int amax" +.Fa "int interval" +.Fc +.\" +.Ft void +.Fn ieee80211_amrr_cleanup "struct ieee80211_amrr *" +.\" +.Ft void +.Fn ieee80211_amrr_setinterval "struct ieee80211_amrr *" "int interval" +.\" +.Ft void +.Fo ieee80211_amrr_node_init +.Fa "struct ieee80211_amrr *" +.Fa "struct ieee80211_amrr_node *" +.Fa "struct ieee80211_node *" +.Fc +.\" +.Ft int +.Fo ieee80211_amrr_choose +.Fa "struct ieee80211_node *" +.Fa "struct ieee80211_amrr_node *" +.Fc +.\" +.Ft void +.Fo ieee80211_amrr_tx_complete +.Fa "struct ieee80211_amrr_node *" +.Fa "int ok" +.Fa "int retries" +.Fc +.\" +.Ft void +.Fo ieee80211_amrr_tx_update +.Fa "struct ieee80211_amrr_node *" +.Fa "int txnct" +.Fa "int success" +.Fa "int retrycnt" +.Fc +.Sh DESCRIPTION +.Nm +is an implementation of the AMRR transmit rate control algorithm +for drivers that use the +.Nm net80211 +software layer. +A rate control algorithm is responsible for choosing the transmit +rate for each frame. +To maximize throughput algorithms try to use the highest rate that +is appropriate for the operating conditions. +The rate will vary as conditions change; the distance between two stations +may change, transient noise may be present that affects signal quality, +etc. +.Nm +uses very simple information from a driver to do it's job: +whether a frame was successfully delivered and how many transmit +attempts were made. +While this enables its use with virtually any wireless device it +limits it's effectiveness--do not expect it to function well in +difficult environments and/or respond quickly to changing conditions. +.Pp +.Nm +requires per-vap state and per-node state for each station it is to +select rates for. +The API's are designed for drivers to pre-allocate state in the +driver-private extension areas of each vap and node. +For example the +.Xr ral 4 +driver defines a vap as: +.Bd -literal -offset indent +struct rt2560_vap { + struct ieee80211vap ral_vap; + struct ieee80211_beacon_offsets ral_bo; + struct ieee80211_amrr amrr; + + int (*ral_newstate)(struct ieee80211vap *, + enum ieee80211_state, int); +}; +.Ed +.Pp +The +.Vt amrr +structure member holds the per-vap state for +.Nm +and +.Xr ral 4 +initializes it in the vap create method with: +.Bd -literal -offset indent +ieee80211_amrr_init(&rvp->amrr, vap, + IEEE80211_AMRR_MIN_SUCCESS_THRESHOLD, + IEEE80211_AMRR_MAX_SUCCESS_THRESHOLD, + 500 /* ms */); +.Ed +.Pp +The node is defined as: +.Bd -literal -offset indent +struct rt2560_node { + struct ieee80211_node ni; + struct ieee80211_amrr_node amrr; +}; +.Ed +.Pp +with initialization done in the driver's +.Vt iv_newassoc +method: +.Bd -literal -offset indent +static void +rt2560_newassoc(struct ieee80211_node *ni, int isnew) +{ + struct ieee80211vap *vap = ni->ni_vap; + + ieee80211_amrr_node_init(&RT2560_VAP(vap)->amrr, + &RT2560_NODE(ni)->amrr, ni); +} +.Ed +.Pp +Once +.Nm +state is setup, transmit rates are requested by calling +.Fn ieee80211_amrr_choose +in the transmit path; e.g.: +.Bd -literal -offset indent +tp = &vap->iv_txparms[ieee80211_chan2mode(ni->ni_chan)]; +if (IEEE80211_IS_MULTICAST(wh->i_addr1)) { + rate = tp->mcastrate; +} else if (m0->m_flags & M_EAPOL) { + rate = tp->mgmtrate; +} else if (tp->ucastrate != IEEE80211_FIXED_RATE_NONE) { + rate = tp->ucastrate; +} else { + (void) ieee80211_amrr_choose(ni, &RT2560_NODE(ni)->amrr); + rate = ni->ni_txrate; +} +.Ed +.Pp +Note a rate is chosen only for unicast data frames when a fixed +transmit rate is not configured; the other cases are handled with +the +.Nm net80211 +transmit parameters. +Note also that +.Fn ieee80211_amrr_choose +writes the chosen rate in +.Vt ni_txrate ; +this eliminates copying the value as it is exported to user applications so +they can display the current transmit rate in status. +.Pp +The remaining work a driver must do is feed status back to +.Nm +when a frame transmit completes using +.Fn ieee80211_amrr_tx_complete . +Drivers that poll a device to retrieve statistics can use +.Fn ieee80211_amrr_tx_update +(instead or in addition). +.Sh SEE ALSO +.Xr ieee80211 9 , +.Xr ieee80211_output 9 Property changes on: user/imp/camdoc/ieee80211_amrr.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/ieee80211_bmiss.9 =================================================================== --- user/imp/camdoc/ieee80211_bmiss.9 (nonexistent) +++ user/imp/camdoc/ieee80211_bmiss.9 (revision 296049) @@ -0,0 +1,91 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 4, 2009 +.Dt IEEE80211_BMISS 9 +.Os +.Sh NAME +.Nm ieee80211_bmiss +.Nd 802.11 beacon miss support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft void +.Fn ieee80211_beacon_miss "struct ieee80211com *" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +handling beacon miss events in station mode. +Drivers can dispatch beacon miss events that are recognized in hardware or +.Nm net80211 +can detect beacon miss if the driver dispatches received beacon frames +through the normal receive path. +Software beacon miss support is especially useful when multiple vaps +are operating and any hardware beacon miss support is not available +(e.g. operating as an access point together with one or more station +mode vaps). +.Pp +Drivers should dispatch beacon miss events recognized in the driver with +.Fn ieee80211_beacon_miss . +This causes some number of ProbeRequest frames to be sent to the +access point to check if the association is still alive. +If no response is received and roaming mode is set to +.Dv IEEE80211_ROAMING_AUTO +then +.Nm net80211 +will try to re-associate and if that fails +trigger a scan to look for the access point or another suitable AP. +When the +.Nm net80211 +state machine is being operated manually, e.g. by +.Xr wpa_supplicant 8 , +then applications are notified of the state change and are responsible +for handling the work of scanning for a new access point. +The number of beacon miss events (without a ProbeResponse) is user +settable with the +.Dv IEEE80211_IOC_BMISSTHRESHOLD +request. +.Pp +Software beacon miss detection is enabled per-vap by setting the +.Dv IEEE80211_FEXT_SWBMISS +flag. +Typically this is done when a vap is setup +when the +.Dv IEEE80211_CLONE_NOBEACONS +option is supplied to the clone operation. +But drivers may also force this when they know they need help detecting +beacon miss. +When beacon miss is detected in software the event is dispatched without +driver involvement. +Note that software beacon miss handling is not limited to station mode; +it can be used in any operating mode where beacons from a peer station +are received. +.Sh SEE ALSO +.Xr wpa_supplicant 8 , +.Xr ieee80211 9 , +.Xr ieee80211_vap 9 Property changes on: user/imp/camdoc/ieee80211_bmiss.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/ieee80211_input.9 =================================================================== --- user/imp/camdoc/ieee80211_input.9 (nonexistent) +++ user/imp/camdoc/ieee80211_input.9 (revision 296049) @@ -0,0 +1,116 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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 4, 2009 +.Dt IEEE80211_INPUT 9 +.Os +.Sh NAME +.Nm ieee80211_input +.Nd software 802.11 stack input functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Ft void +.Fo ieee80211_input +.Fa "struct ieee80211_node *" +.Fa "struct mbuf *" +.Fa "int rssi" +.Fa "int noise" +.Fc +.Ft void +.Fo ieee80211_input_all +.Fa "struct ieee80211com *" +.Fa "struct mbuf *" +.Fa "int rssi" +.Fa "int noise" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers requires that +receive processing be single-threaded. +Typically this is done using a dedicated driver +.Xr taskqueue 9 +thread. +.Fn ieee80211_input +and +.Fn ieee80211_input_all +process received 802.11 frames and are designed +for use in that context; e.g. no driver locks may be held. +.Pp +The frame passed up in the +.Vt mbuf +must have the 802.11 protocol header at the front; all device-specific +information and/or PLCP must be removed. +Any CRC must be stripped from the end of the frame. +The 802.11 protocol header should be 32-bit aligned for +optimal performance but receive processing does not require it. +If the frame holds a payload and that is not aligned to a 32-bit +boundary then the payload will be re-aligned so that it is suitable +for processing by protocols such as +.Xr ip 4 . +.Pp +If a device (such as +.Xr ath 4 ) +inserts padding after the 802.11 header to align +the payload to a 32-bit boundary the +.Dv IEEE80211_C_DATAPAD +capability must be set. +Otherwise header and payload are assumed contiguous in the mbuf chain. +.Pp +If a received frame must pass +through the A-MPDU receive reorder buffer then the mbuf +must be marked with the +.Dv M_AMPDU +flag. +Note that for the moment this is required of all frames received from +a station and TID where a Block ACK stream is active, not just A-MPDU +aggregates. +It is sufficient to check for +.Dv IEEE80211_NODE_HT +in the +.Vt ni_flags +of the station's node table entry, any frames that do not require reorder +processing will be dispatched with only minimal overhead. +.Pp +The +.Vt rssi +parameter is the Receive Signal Strength Indication of the frame +measured in 0.5dBm units relative to the noise floor. +The +.Vt noise +parameter is the best approximation of the noise floor in +dBm units at the time the frame was received. +RSSI and noise are used by the +.Nm net80211 +layer to make scanning and roaming decisions in station mode +and to do auto channel selection for hostap and similar modes. +Otherwise the values are made available to user applications +(with the rssi presented as a filtered average over the last ten values +and the noise floor the last reported value). +.Sh SEE ALSO +.Xr ieee80211 9 Property changes on: user/imp/camdoc/ieee80211_input.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211_output.9 =================================================================== --- user/imp/camdoc/ieee80211_output.9 (nonexistent) +++ user/imp/camdoc/ieee80211_output.9 (revision 296049) @@ -0,0 +1,194 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson +.\" Copyright (c) 2004 Darron Broad +.\" 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$ +.\" $Id: ieee80211_output.9,v 1.5 2004/03/04 12:31:18 bruce Exp $ +.\" +.Dd March 29, 2010 +.Dt IEEE80211_OUTPUT 9 +.Os +.Sh NAME +.Nm ieee80211_output +.Nd software 802.11 stack output functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.\" +.Ft int +.Fn M_WME_GETAC "struct mbuf *" +.\" +.Ft int +.Fn M_SEQNO_GET "struct mbuf *" +.\" +.Ft struct ieee80211_key * +.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *" +.\" +.Ft void +.Fo ieee80211_process_callback +.Fa "struct ieee80211_node *" +.Fa "struct mbuf *" +.Fa "int" +.Fc +.Sh DESCRIPTION +The +.Nm net80211 +layer that supports 802.11 device drivers handles most of the +work required to transmit frames. +Drivers usually receive fully-encapsulated 802.11 frames that +have been classified and assigned a transmit priority; +all that is left is to do +crypto encapsulation, +prepare any hardware-specific state, +and +push the packet out to the device. +Outbound frames are either generated by the +.Nm net80211 +layer (e.g. management frames) or are passed down +from upper layers through the +.Xr ifnet 9 +transmit queue. +Data frames passed down for transmit flow through +.Nm net80211 +which handles aggregation, 802.11 encapsulation, and then +dispatches the frames to the driver through it's transmit queue. +.Pp +There are two control paths by which frames reach a driver for transmit. +Data packets are queued to the device's +.Vt if_snd +queue and the driver's +.Vt if_start +method is called. +Other frames are passed down using the +.Vt ic_raw_xmit +method without queueing (unless done by the driver). +The raw transmit path may include data frames from user applications +that inject them through +.Xr bpf 4 +and NullData frames generated by +.Nm net80211 +to probe for idle stations (when operating as an access point). +.Pp +.Nm net80211 +handles all state-related bookkeeping and management for the handling +of data frames. +Data frames are only transmit for a vap in the +.Dv IEEE80211_S_RUN +state; there is no need, for example, to check for frames sent down +when CAC or CSA is active. +Similarly, +.Nm net80211 +handles activities such as background scanning and power save mode, +frames will not be sent to a driver unless it is operating on the +BSS channel with +.Dq full power . +.Pp +All frames passed to a driver for transmit hold a reference to a +node table entry in the +.Vt m_pkthdr.rcvif +field. +The node is associated with the frame destination. +Typically it is the receiver's entry but in some situations it may be +a placeholder entry or the +.Dq next hop station +(such as in a mesh network). +In all cases the reference must be reclaimed with +.Fn ieee80211_free_node +when the transmit work is completed. +The rule to remember is: +.Nm net80211 +passes responsibility for the +.Vt mbuf +and +.Dq node reference +to the driver with each frame it hands off for transmit. +.Sh PACKET CLASSIFICATION +All frames passed by +.Nm net80211 +for transmit are assigned a priority based on any vlan tag +assigned to the receiving station and/or any Diffserv setting +in an IP or IPv6 header. +If both vlan and Diffserv priority are present the higher of the +two is used. +If WME/WMM is being used then any ACM policy (in station mode) is +also enforced. +The resulting AC is attached to the mbuf and may be read back using the +.Fn M_WME_GETAC +macro. +.Pp +PAE/EAPOL frames are tagged with an +.Dv M_EAPOL +mbuf flag; drivers should transmit them with care, usually by +using the transmit rate for management frames. +Multicast/broadcast frames are marked with the +.Dv M_MCAST +mbuf flag. +Frames coming out of a station's power save queue and that have +more frames immediately following are marked with the +.Dv M_MORE_DATA +mbuf flag. +Such frames will be queued consecutively in the driver's +.Vt if_snd +queue and drivers should preserve the ordering when passing +them to the device. +.Sh FRAGMENTED FRAMES +The +.Nm net80211 +layer will fragment data frames according to the setting of +.Vt iv_fragthreshold +if a driver marks the +.Dv IEEE80211_C_TXFRAG +capability. +Fragmented frames are placed +in the devices transmit queue with the fragments chained together with +.Vt m_nextpkt . +Each frame is marked with the +.Dv M_FRAG +mbuf flag, and the first and last are marked with +.Dv M_FIRSTFRAG +and +.Dv M_LASTFRAG , +respectively. +Drivers are expected to process all fragments or none. +.Sh TRANSMIT CALLBACKS +Frames sent by +.Nm net80211 +may be tagged with the +.Dv M_TXCB +mbuf flag to indicate a callback should be done +when their transmission completes. +The callback is done using +.Fn ieee80211_process_callback +with the last parameter set to a non-zero value if an error occurred +and zero otherwise. +Note +.Nm net80211 +understands that drivers may be incapable of determining status; +a device may not report if an ACK frame is received and/or a device may queue +transmit requests in its hardware and only report status on whether +the frame was successfully queued. +.Sh SEE ALSO +.Xr bpf 4 , +.Xr ieee80211 9 , +.Xr ifnet 9 Property changes on: user/imp/camdoc/ieee80211_output.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211_regdomain.9 =================================================================== --- user/imp/camdoc/ieee80211_regdomain.9 (nonexistent) +++ user/imp/camdoc/ieee80211_regdomain.9 (revision 296049) @@ -0,0 +1,143 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 4, 2009 +.Dt IEEE80211_REGDOMAIN 9 +.Os +.Sh NAME +.Nm ieee80211_regdomain +.Nd 802.11 regulatory support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_regdomain.h +.Pp +.Ft int +.Fo ieee80211_init_channels +.Fa "struct ieee80211com *" +.Fa "const struct ieee80211_regdomain *" +.Fa "const uint8_t bands[]" +.Fc +.\" +.Ft void +.Fo ieee80211_sort_channels +.Fa "struct ieee80211_channel *" +.Fa "int nchans" +.Fc +.\" +.Ft "struct ieee80211_appie *" +.Fn ieee80211_alloc_countryie "struct ieee80211com *" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +comprehensive regulatory support. +.Nm net80211 +provides mechanisms that enforce +.Em "regulatory policy" +by privileged user applications. +.Pp +Drivers define a device's capabilities and can +intercept and control regulatory changes requested through +.Nm net80211 . +The initial regulatory state, including the channel list, must be +filled in by the driver before calling +.Fn ieee80211_ifattach . +The channel list should reflect the set of channels the device is +.Em calibrated +for use on. +This list may also be requested later through the +.Vt ic_getradiocaps +method in the +.Vt ieee80211com +structure. +The +.Fn ieee80211_init_channels +function is provided as a rudimentary fallback for drivers that do not +(or cannot) fill in a proper channel list. +Default regulatory state is supplied such as the regulatory SKU, +ISO country code, location (e.g. indoor, outdoor), and a set of +frequency bands the device is capable of operating on. +.Nm net80211 +populates the channel table in +.Vt ic_channels +with a default set of channels and capabilities. +Note this mechanism should be used with care as any mismatch between +the channel list created and the device's capabilities can result +in runtime errors (e.g. a request to operate on a channel the device +does not support). +The SKU and country information are used for generating 802.11h protocol +elements and related operation such as for 802.11d; mis-setup by a +driver is not fatal, only potentially confusing. +.Pp +Devices that do not have a fixed/default regulatory state can set +the regulatory SKU to +.Dv SKU_DEBUG +and country code to +.Dv CTRY_DEFAULT +and leave proper setup to user applications. +If default settings are known they can be installed and/or an event +can be dispatched to user space using +.Fn ieee80211_notify_country +so that +.Xr devd 8 +will do the appropriate setup work at system boot (or device insertion). +.Pp +The channel table is sorted to optimize lookups using the +.Fn ieee80211_sort_channels +routine. +This should be done whenever the channel table contents are modified. +.Pp +The +.Fn ieee80211_alloc_countryie +function allocates an information element as specified by 802.11h. +Because this is expensive to generate it is cached in +.Vt ic_countryie +and generated only when regulatory state changes. +Drivers that call +.Fn ieee80211_alloc_countryie +directly should not help with this caching; doing so may confuse the +.Nm net80211 +layer. +.Sh DRIVER REGULATORY CONTROL +Drivers can control regulatory change requests by overriding the +.Vt ic_setregdomain +method that checks change requests. +While drivers can reject any request that does not meet its requirements +it is recommended that one be lenient in what is accepted and, whenever +possible, instead of rejecting a request, alter it to be correct. +For example, if the transmit power cap for a channel is too high the +driver can either reject the request or (better) reduce the cap to be +compliant. +Requests that include unacceptable channels should cause the request +to be rejected as otherwise a mismatch may be created between application +state and the state managed by +.Nm net80211 . +The exact rules by which to operate are still being codified. +.Sh SEE ALSO +.Xr regdomain 5 , +.Xr ifconfig 8 , +.Xr ieee80211 9 Property changes on: user/imp/camdoc/ieee80211_regdomain.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/ieee80211_scan.9 =================================================================== --- user/imp/camdoc/ieee80211_scan.9 (nonexistent) +++ user/imp/camdoc/ieee80211_scan.9 (revision 296049) @@ -0,0 +1,350 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 29, 2010 +.Dt IEEE80211_SCAN 9 +.Os +.Sh NAME +.Nm ieee80211_scan +.Nd 802.11 scanning support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft int +.Fo ieee80211_start_scan +.Fa "struct ieee80211vap *" +.Fa "int flags" +.Fa "u_int duration" +.Fa "u_int mindwell" +.Fa "u_int maxdwell" +.Fa "u_int nssid" +.Fa "const struct ieee80211_scan_ssid ssids[]" +.Fc +.\" +.Ft int +.Fo ieee80211_check_scan +.Fa "struct ieee80211vap *" +.Fa "int flags" +.Fa "u_int duration" +.Fa "u_int mindwell" +.Fa "u_int maxdwell" +.Fa "u_int nssid" +.Fa "const struct ieee80211_scan_ssid ssids[]" +.Fc +.\" +.Ft int +.Fn ieee80211_check_scan_current "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_bg_scan "struct ieee80211vap *" "int" +.\" +.Ft int +.Fn ieee80211_cancel_scan "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_cancel_scan_any "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_scan_next "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_scan_done "struct ieee80211vap *" +.\" +.Ft int +.Fn ieee80211_probe_curchan "struct ieee80211vap *" "int" +.\" +.Ft void +.Fo ieee80211_add_scan +.Fa "struct ieee80211vap *" +.Fa "const struct ieee80211_scanparams *" +.Fa "const struct ieee80211_frame *" +.Fa "int subtype" +.Fa "int rssi" +.Fa "int noise" +.Fc +.\" +.Ft void +.Fn ieee80211_scan_timeout "struct ieee80211com *" +.\" +.Ft void +.Fo ieee80211_scan_assoc_fail +.Fa "struct ieee80211vap *" +.Fa "const uint8_t mac[IEEE80211_ADDR_LEN]" +.Fa "int reason" +.Fc +.\" +.Ft void +.Fn ieee80211_scan_flush "struct ieee80211vap *" +.\" +.Ft void +.Fo ieee80211_scan_iterate +.Fa "struct ieee80211vap *" +.Fa "ieee80211_scan_iter_func" +.Fa "void *" +.Fc +.\" +.Ft void +.Fn ieee80211_scan_dump_channels "const struct ieee80211_scan_state *" +.\" +.Ft void +.Fo ieee80211_scanner_register +.Fa "enum ieee80211_opmode" +.Fa "const struct ieee80211_scanner *" +.Fc +.\" +.Ft void +.Fo ieee80211_scanner_unregister +.Fa "enum ieee80211_opmode" +.Fa "const struct ieee80211_scanner *" +.Fc +.\" +.Ft void +.Fn ieee80211_scanner_unregister_all "const struct ieee80211_scanner *" +.\" +.Ft const struct ieee80211_scanner * +.Fn ieee80211_scanner_get "enum ieee80211_opmode" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides an extensible framework for scanning. +Scanning is the procedure by which a station locates a BSS to join +(in infrastructure and IBSS mode), or a channel to use (when operating +as an AP or an IBSS master). +Scans are either +.Dq active +or +.Dq passive . +An active scan causes one or more ProbeRequest frames to be sent on +visiting each channel. +A passive request causes each channel in the scan set to be visited but +no frames to be transmitted; the station only listens for traffic. +Note that active scanning may still need to listen for traffic before +sending ProbeRequest frames depending on regulatory constraints. +.Pp +A scan operation involves constructing a set of channels to inspect +(the scan set), +visiting each channel and collecting information +(e.g. what BSS are present), +and then analyzing the results to make decisions such as which BSS to join. +This process needs to be as fast as possible so +.Nm net80211 +does things like intelligently construct scan sets and dwell on a channel +only as long as necessary. +Scan results are cached and the scan cache is used to avoid scanning when +possible and to enable roaming between access points when operating +in infrastructure mode. +.Pp +Scanning is handled by pluggable modules that implement +.Em policy +per-operating mode. +The core scanning support provides an infrastructure to support these +modules and exports a common API to the rest of the +.Nm net80211 +layer. +Policy modules decide what channels to visit, what state to record to +make decisions, and selects the final station/channel to return as the +result of a scan. +.Pp +Scanning is done synchronously when initially bringing a vap to +an operational state and optionally in the background to maintain +the scan cache for doing roaming and rogue AP monitoring. +Scanning is not tied to the +.Nm net80211 +state machine that governs vaps except for linkage to the +.Dv IEEE80211_S_SCAN +state. +Only one vap at a time may be scanning; this scheduling policy +is handled in +.Fn ieee80211_new_state +and is transparent to scanning code. +.Pp +Scanning is controlled by a set of parameters that (potentially) +constrains the channel set and any desired SSID's and BSSID's. +.Nm net80211 +comes with a standard scanner module that works with all available +operating modes and supports +.Dq background scanning +and +.Dq roaming +operation. +.Sh SCANNER MODULES +Scanning modules use a registration mechanism to hook into the +.Nm net80211 +layer. +Use +.Fn ieee80211_scanner_register +to register a scan module for a particular operating mode and +.Fn ieee80211_scanner_unregister +or +.Fn ieee80211_scanner_unregister_all +to clear entries (typically on module unload). +Only one scanner module can be registered at any time for an operating mode. +.Sh DRIVER SUPPORT +Scanning operations are usually managed by the +.Nm net80211 +layer. +Drivers must provide +.Vt ic_scan_start +and +.Vt ic_scan_stop +methods that are called at the start of a scan and when the +work is done; these should handle work such as enabling receive +of Beacon and ProbeResponse frames and disable any BSSID matching. +The +.Vt ic_set_channel +method is used to change channels while scanning. +.Nm net80211 +will generate ProbeRequest frames and transmit them using the +.Nm ic_raw_xmit +method. +Frames received while scanning are dispatched to +.Nm net80211 +using the normal receive path. +Devices that off-load scan work to firmware most easily mesh with +.Nm net80211 +by operating on a channel-at-a-time basis as this defers control to +.Nm net80211's +scan machine scheduler. +But multi-channel scanning +is supported if the driver manually dispatches results using +.Fn ieee80211_add_scan +routine to enter results into the scan cache. +.Sh SCAN REQUESTS +Scan requests occur by way of the +.Dv IEEE80211_SCAN_REQUEST +ioctl or through a change in a vap's state machine that requires +scanning. +In both cases the scan cache can be checked first and, if it is deemed +suitably +.Dq warm +then it's contents are used without leaving the current channel. +To start a scan without checking the cache +.Fn ieee80211_start_scan +can be called; otherwise +.Fn ieee80211_check_scan +can be used to first check the scan cache, kicking off a scan if +the cache contents are out of date. +There is also +.Fn ieee80211_check_scan_current +which is a shorthand for using previously set scan parameters for +checking the scan cache and then scanning. +.Pp +Background scanning is done using +.Fn ieee80211_bg_scan +in a co-routine fashion. +The first call to this routine will start a background scan that +runs for a limited period of time before returning to the BSS channel. +Subsequent calls advance through the scan set until all channels are +visited. +Typically these later calls are timed to allow receipt of +frames buffered by an access point for the station. +.Pp +A scan operation can be canceled using +.Fn ieee80211_cancel_scan +if it was initiated by the specified vap, or +.Fn ieee80211_cancel_scan_any +to force termination regardless which vap started it. +These requests are mostly used by +.Nm net80211 +in the transmit path to cancel background scans when frames are to be sent. +Drivers should not need to use these calls (or most of the calls described +on this page). +.Pp +The +.Fn ieee80211_scan_next +and +.Fn ieee80211_scan_done +routines do explicit iteration through the scan set and should +not normally be used by drivers. +.Fn ieee80211_probe_curchan +handles the work of transmitting ProbeRequest frames when visiting +a channel during an active scan. +When the channel attributes are marked with +.Dv IEEE80211_CHAN_PASSIVE +this function will arrange that before any frame is transmitted 802.11 +traffic is first received (in order to comply with regulatory constraints). +.Pp +Min/max dwell time parameters are used to constrain time spent visiting +a channel. +The maximum dwell time constrains the time spent listening for traffic. +The minimum dwell time is used to reduce this time--when it is reached +and one or more frames have been received then an immediate channel +change will be done. +Drivers can override this behaviour through the +.Vt iv_scan_mindwell +method. +.Sh SCAN CACHE MANAGEMENT +The scan cache contents are managed by the scan policy module and +are opaque outside this module. +The +.Nm net80211 +scan framework defines API's for interacting. +The validity of the scan cache contents are controlled by +.Vt iv_scanvalid +which is exported to user space through the +.Dv IEEE80211_SCAN_VALID +request. +.Pp +The cache contents can be explicitly flushed with +.Fn ieee80211_scan_flush +or by setting the +.Dv IEEE80211_SCAN_FLUSH +flag when starting a scan operation. +.Pp +Scan cache entries are created with the +.Fn ieee80211_add_scan +routine; usually on receipt of Beacon or ProbeResponse frames. +Existing entries are typically updated based on the latest information +though some information such as RSSI and noise floor readings may be +combined to present an average. +.Pp +The cache contents is aged through +.Fn ieee80211_scan_timeout +calls. +Typically these happen together with other station table activity; every +.Dv IEEE80211_INACT_WAIT +seconds (default 15). +.Pp +Individual cache entries are marked usable with +.Fn ieee80211_scan_assoc_success +and faulty with +.Fn ieee80211_scan_assoc_fail +with the latter taking an argument to identify if there was no response +to Authentication/Association requests or if a negative response was +received (which might hasten cache eviction or blacklist the entry). +.Pp +The cache contents can be viewed using the +.Fn ieee80211_scan_iterate +call. +Cache entries are exported in a public format that is exported to user +applications through the +.Dv IEEE80211_SCAN_RESULTS +request. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr ieee80211 9 , +.Xr ieee80211_proto 9 Property changes on: user/imp/camdoc/ieee80211_scan.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/ieee80211_vap.9 =================================================================== --- user/imp/camdoc/ieee80211_vap.9 (nonexistent) +++ user/imp/camdoc/ieee80211_vap.9 (revision 296049) @@ -0,0 +1,154 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 4, 2009 +.Dt IEEE8021_VAP 9 +.Os +.Sh NAME +.Nm net80211_vap +.Nd 802.11 network layer virtual radio support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Ft int +.Fo ieee80211_vap_setup +.Fa "struct ieee80211com *" +.Fa "struct ieee80211vap *" +.Fa "const char name[IFNAMSIZ]" +.Fa "int unit" +.Fa "int opmode" +.Fa "int flags" +.Fa "const uint8_t bssid[IEEE80211_ADDR_LEN]" +.Fa "const uint8_t macaddr[IEEE80211_ADDR_LEN]" +.Fc +.\" +.Ft int +.Fo ieee80211_vap_attach +.Fa "struct ieee80211vap *" +.Fa "ifm_change_cb_t media_change" +.Fa "ifm_stat_cb_t media_stat" +.Fc +.\" +.Ft void +.Fn ieee80211_vap_detach "struct ieee80211vap *" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +a virtual radio API that is exported to +users through network interfaces (aka vaps) that are cloned from the +underlying device. +These interfaces have an operating mode +(station, adhoc, hostap, wds, monitor, etc.) +that is fixed for the lifetime of the interface. +Devices that can support multiple concurrent interfaces allow +multiple vaps to be cloned. +.Pp +The virtual radio interface defined by the +.Nm net80211 +layer means that drivers must be structured to follow specific rules. +Drivers that support only a single interface at any time must still +follow these rules. +.Pp +The virtual radio architecture splits state between a single per-device +.Vt ieee80211com +structure and one or more +.Vt ieee80211vap +structures. +Vaps are created with the +.Dv SIOCIFCREATE2 +request. +This results in a call into the driver's +.Vt ic_vap_create +method where the driver can decide if the request should be accepted. +.Pp +The vap creation process is done in three steps. +First the driver allocates the data structure with +.Xr malloc 9 . +This data structure must have an +.Vt ieee80211vap +structure at the front but is usually extended with driver-private state. +Next the vap is setup with a call to +.Fn ieee80211_vap_setup . +This request initializes +.Nm net80211 +state but does not activate the interface. +The driver can then override methods setup by +.Nm net80211 +and setup driver resources before finally calling +.Fn ieee80211_vap_attach +to complete the process. +Both these calls must be done without holding any driver locks as +work may require the process block/sleep. +.Pp +A vap is deleted when an +.Dv SIOCIFDESTROY +ioctl request is made or when the device detaches (causing all +associated vaps to automatically be deleted). +Delete requests cause the +.Vt ic_vap_delete +method to be called. +Drivers must quiesce the device before calling +.Fn ieee80211_vap_detach +to deactivate the vap and isolate it from activities such as requests +from user applications. +The driver can then reclaim resources held by the vap and re-enable +device operation. +The exact procedure for quiescing a device is unspecified but typically +it involves blocking interrupts and stopping transmit and receive +processing. +.Sh MULTI-VAP OPERATION +Drivers are responsible for deciding if multiple vaps can be created +and how to manage them. +Whether or not multiple concurrent vaps can be supported depends on a +device's capabilities. +For example, multiple hostap vaps can usually be supported but many +devices do not support assigning each vap a unique BSSID. +If a device supports hostap operation it can usually support concurrent +station mode vaps but possibly with limitations such as losing support +for hardware beacon miss support. +Devices that are capable of hostap operation and can send and receive +4-address frames should be able to support WDS vaps together with an +ap vap. +But in contrast some devices cannot support WDS vaps without at least one +ap vap (this however can be finessed by forcing the ap vap to not transmit +beacon frames). +All devices should support the creation of any number of monitor mode vaps +concurrent with other vaps but it is the responsibility of the driver to +allow this. +.Pp +An important consequence of supporting multiple concurrent vaps is that +a driver's +.Vt iv_newstate +method must be written to handle being called for each vap. +Where necessary, drivers must track private state for all vaps +and not just the one whose state is being changed (e.g. for +handling beacon timers the driver may need to know if all vaps +that beacon are stopped before stopping the hardware timers). +.Sh SEE ALSO +.Xr ieee80211 9 , +.Xr ifnet 9 , +.Xr malloc 9 Property changes on: user/imp/camdoc/ieee80211_vap.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/kproc.9 =================================================================== --- user/imp/camdoc/kproc.9 (nonexistent) +++ user/imp/camdoc/kproc.9 (revision 296049) @@ -0,0 +1,395 @@ +.\" Copyright (c) 2000-2001 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" 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 October 19, 2007 +.Dt KPROC 9 +.Os +.Sh NAME +.Nm kproc_start , +.Nm kproc_shutdown , +.Nm kproc_create , +.Nm kproc_exit , +.Nm kproc_resume , +.Nm kproc_suspend , +.Nm kproc_suspend_check +.Nd "kernel processes" +.Sh SYNOPSIS +.In sys/kthread.h +.Ft void +.Fn kproc_start "const void *udata" +.Ft void +.Fn kproc_shutdown "void *arg" "int howto" +.Ft int +.Fo kproc_create +.Fa "void (*func)(void *)" "void *arg" "struct proc **newpp" +.Fa "int flags" "int pages" +.Fa "const char *fmt" ... +.Fc +.Ft void +.Fn kproc_exit "int ecode" +.Ft int +.Fn kproc_resume "struct proc *p" +.Ft int +.Fn kproc_suspend "struct proc *p" "int timo" +.Ft void +.Fn kproc_suspend_check "struct proc *p" +.Ft int +.Fo kproc_kthread_add +.Fa "void (*func)(void *)" "void *arg" +.Fa "struct proc **procptr" "struct thread **tdptr" +.Fa "int flags" "int pages" "char * procname" "const char *fmt" "..." +.Fc +.Sh DESCRIPTION +In +.Fx 8.0 , +the +.Fn kthread* 9 +family of functions was renamed to be the +.Fn kproc* 9 +family of functions, as they were misnamed +and actually produced kernel processes. +A new family of +.Em different +.Fn kthread_* 9 +functions was added to produce +.Em real +kernel +.Em threads . +See the +.Xr kthread 9 +man page for more information on those calls. +Also note that the +.Fn kproc_kthread_add 9 +function appears in both pages as its functionality is split. +.Pp +The function +.Fn kproc_start +is used to start +.Dq internal +daemons such as +.Nm bufdaemon , pagedaemon , vmdaemon , +and the +.Nm syncer +and is intended +to be called from +.Xr SYSINIT 9 . +The +.Fa udata +argument is actually a pointer to a +.Vt "struct kproc_desc" +which describes the kernel process that should be created: +.Bd -literal -offset indent +struct kproc_desc { + char *arg0; + void (*func)(void); + struct proc **global_procpp; +}; +.Ed +.Pp +The structure members are used by +.Fn kproc_start +as follows: +.Bl -tag -width ".Va global_procpp" -offset indent +.It Va arg0 +String to be used for the name of the process. +This string will be copied into the +.Va p_comm +member of the new process' +.Vt "struct proc" . +.It Va func +The main function for this kernel process to run. +.It Va global_procpp +A pointer to a +.Vt "struct proc" +pointer that should be updated to point to the newly created process' process +structure. +If this variable is +.Dv NULL , +then it is ignored. +.El +.Pp +The +.Fn kproc_create +function is used to create a kernel process. +The new process shares its address space with process 0, the +.Nm swapper +process, +and runs in kernel mode only. +The +.Fa func +argument specifies the function that the process should execute. +The +.Fa arg +argument is an arbitrary pointer that is passed in as the only argument to +.Fa func +when it is called by the new process. +The +.Fa newpp +pointer points to a +.Vt "struct proc" +pointer that is to be updated to point to the newly created process. +If this argument is +.Dv NULL , +then it is ignored. +The +.Fa flags +argument specifies a set of flags as described in +.Xr rfork 2 . +The +.Fa pages +argument specifies the size of the new kernel process's stack in pages. +If 0 is used, the default kernel stack size is allocated. +The rest of the arguments form a +.Xr printf 9 +argument list that is used to build the name of the new process and is stored +in the +.Va p_comm +member of the new process's +.Vt "struct proc" . +.Pp +The +.Fn kproc_exit +function is used to terminate kernel processes. +It should be called by the main function of the kernel process rather than +letting the main function return to its caller. +The +.Fa ecode +argument specifies the exit status of the process. +While exiting, the function +.Xr exit1 9 +will initiate a call to +.Xr wakeup 9 +on the process handle. +.Pp +The +.Fn kproc_resume , +.Fn kproc_suspend , +and +.Fn kproc_suspend_check +functions are used to suspend and resume a kernel process. +During the main loop of its execution, a kernel process that wishes to allow +itself to be suspended should call +.Fn kproc_suspend_check +passing in +.Va curproc +as the only argument. +This function checks to see if the kernel process has been asked to suspend. +If it has, it will +.Xr tsleep 9 +until it is told to resume. +Once it has been told to resume it will return allowing execution of the +kernel process to continue. +The other two functions are used to notify a kernel process of a suspend or +resume request. +The +.Fa p +argument points to the +.Vt "struct proc" +of the kernel process to suspend or resume. +For +.Fn kproc_suspend , +the +.Fa timo +argument specifies a timeout to wait for the kernel process to acknowledge the +suspend request and suspend itself. +.Pp +The +.Fn kproc_shutdown +function is meant to be registered as a shutdown event for kernel processes that +need to be suspended voluntarily during system shutdown so as not to interfere +with system shutdown activities. +The actual suspension of the kernel process is done with +.Fn kproc_suspend . +.Pp +The +.Fn kproc_kthread_add +function is much like the +.Fn kproc_create +function above except that if the kproc already exists, +then only a new thread (see +.Xr kthread 9 ) +is created on the existing process. +The +.Fa func +argument specifies the function that the process should execute. +The +.Fa arg +argument is an arbitrary pointer that is passed in as the only argument to +.Fa func +when it is called by the new process. +The +.Fa procptr +pointer points to a +.Vt "struct proc" +pointer that is the location to be updated with the new proc pointer +if a new process is created, or if not +.Dv NULL , +must contain the process pointer for the already existing process. +If this argument points to +.Dv NULL , +then a new process is created and the field updated. +If not NULL, the +.Fa tdptr +pointer points to a +.Vt "struct thread" +pointer that is the location to be updated with the new thread pointer. +The +.Fa flags +argument specifies a set of flags as described in +.Xr rfork 2 . +The +.Fa pages +argument specifies the size of the new kernel thread's stack in pages. +If 0 is used, the default kernel stack size is allocated. +The procname argument is the name the new process should be given if it needs to be created. +It is +.Em NOT +a printf style format specifier but a simple string. +The rest of the arguments form a +.Xr printf 9 +argument list that is used to build the name of the new thread and is stored +in the +.Va td_name +member of the new thread's +.Vt "struct thread" . +.Sh RETURN VALUES +The +.Fn kproc_create , +.Fn kproc_resume , +and +.Fn kproc_suspend +functions return zero on success and non-zero on failure. +.Sh EXAMPLES +This example demonstrates the use of a +.Vt "struct kproc_desc" +and the functions +.Fn kproc_start , +.Fn kproc_shutdown , +and +.Fn kproc_suspend_check +to run the +.Nm bufdaemon +process. +.Bd -literal -offset indent +static struct proc *bufdaemonproc; + +static struct kproc_desc buf_kp = { + "bufdaemon", + buf_daemon, + &bufdaemonproc +}; +SYSINIT(bufdaemon, SI_SUB_KTHREAD_BUF, SI_ORDER_FIRST, kproc_start, + &buf_kp) + +static void +buf_daemon() +{ + ... + /* + * This process needs to be suspended prior to shutdown sync. + */ + EVENTHANDLER_REGISTER(shutdown_pre_sync, kproc_shutdown, + bufdaemonproc, SHUTDOWN_PRI_LAST); + ... + for (;;) { + kproc_suspend_check(bufdaemonproc); + ... + } +} +.Ed +.Sh ERRORS +The +.Fn kproc_resume +and +.Fn kproc_suspend +functions will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa p +argument does not reference a kernel process. +.El +.Pp +The +.Fn kproc_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +.It Bq Er EINVAL +The +.Dv RFCFDG +flag was specified in the +.Fa flags +parameter. +.El +.Sh SEE ALSO +.Xr rfork 2 , +.Xr exit1 9 , +.Xr kthread 9 , +.Xr SYSINIT 9 , +.Xr wakeup 9 +.Sh HISTORY +The +.Fn kproc_start +function first appeared in +.Fx 2.2 . +The +.Fn kproc_shutdown , +.Fn kproc_create , +.Fn kproc_exit , +.Fn kproc_resume , +.Fn kproc_suspend , +and +.Fn kproc_suspend_check +functions were introduced in +.Fx 4.0 . +Prior to +.Fx 5.0 , +the +.Fn kproc_shutdown , +.Fn kproc_resume , +.Fn kproc_suspend , +and +.Fn kproc_suspend_check +functions were named +.Fn shutdown_kproc , +.Fn resume_kproc , +.Fn shutdown_kproc , +and +.Fn kproc_suspend_loop , +respectively. +Originally they had the names +.Fn kthread_* +but were changed to +.Fn kproc_* +when real kthreads became available. Property changes on: user/imp/camdoc/kproc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/MD5.9 =================================================================== --- user/imp/camdoc/MD5.9 (nonexistent) +++ user/imp/camdoc/MD5.9 (revision 296049) @@ -0,0 +1,78 @@ +.\" $OpenBSD: md5.9,v 1.1 1996/04/17 21:40:14 mickey Exp $ +.\" +.\" Copyright (c) 1996 Michael Shalayeff +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Michael Shalayeff +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 17, 1996 +.Dt MD5 9 +.Os +.Sh NAME +.Nm MD5 , +.Nm MD5Init , +.Nm MD5Transform +.Nd message digest routines +.Sh SYNOPSIS +.In sys/types.h +.In sys/md5.h +.Ft void +.Fn MD5Init "MD5_CTX *buf" +.Ft void +.Fn MD5Transform "uint32_t buf[4]" "const unsigned char block[64]" +.Sh DESCRIPTION +The +.Nm +module implements the RSA Data Security, Inc.\& MD5 Message-Digest Algorithm +(MD5). +It produces 128-bit MD5 Digest of data. +.Bl -hang -width MD5Transformxxx +.It Pa MD5Init +must be called just before +.Fn MD5Transform +will be used to produce a digest. +The +.Fa buf +argument is the storage for the digest being produced on subsequent +calls to the +.Fn MD5Transform +routine. +.It Pa MD5Transform +is the core of the MD5 algorithm, this alters an existing MD5 hash +kept in +.Fa buf +to reflect the addition of 64 characters +of new data passed in +.Fa block +argument. +.El +.Sh COPYRIGHTS +The code for MD5 transform was taken from Colin Plumb's +implementation, which has been placed in the public domain. +The MD5 cryptographic checksum was devised by Ronald Rivest, and is +documented in RFC 1321, "The MD5 Message Digest Algorithm". Property changes on: user/imp/camdoc/MD5.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_set_flags.9 =================================================================== --- user/imp/camdoc/device_set_flags.9 (nonexistent) +++ user/imp/camdoc/device_set_flags.9 (revision 296049) @@ -0,0 +1,56 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1999 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 6, 1999 +.Dt DEVICE_GET_FLAGS 9 +.Os +.Sh NAME +.Nm device_set_flags , +.Nm device_get_flags +.Nd manipulate driver flags +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_set_flags "device_t dev" "uint32_t flags" +.Ft uint32_t +.Fn device_get_flags "device_t dev" +.Sh DESCRIPTION +Each device supports a set of driver-dependent flags which are often +used to control device behaviour. +These flags are read by calling +.Fn device_get_flags +and written by calling +.Fn device_set_flags . +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_set_flags.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/rijndael.9 =================================================================== --- user/imp/camdoc/rijndael.9 (nonexistent) +++ user/imp/camdoc/rijndael.9 (revision 296049) @@ -0,0 +1,135 @@ +.\" +.\" Copyright (c) 2002 +.\" Mark R V Murray. All rights reserved. +.\" +.\" 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 February 6, 2002 +.Dt RIJNDAEL 9 +.Os +.Sh NAME +.Nm rijndael_makeKey , +.Nm rijndael_cipherInit , +.Nm rijndael_blockEncrypt , +.Nm rijndael_padEncrypt , +.Nm rijndael_blockDecrypt , +.Nm rijndael_padDecrypt +.Nd AES encryption +.Sh SYNOPSIS +.In sys/types.h +.In crypto/rijndael.h +.Ft int +.Fo rijndael_makeKey +.Fa "keyInstance *key" +.Fa "uint8_t direction" +.Fa "int keyLen" +.Fa "char *keyMaterial" +.Fc +.Ft int +.Fo rijndael_cipherInit +.Fa "cipherInstance *cipher" +.Fa "uint8_t mode" +.Fa "char *IV" +.Fc +.Ft int +.Fo rijndael_blockEncrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputLen" +.Fa "uint8_t *outBuffer" +.Fc +.Ft int +.Fo rijndael_padEncrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputOctets" +.Fa "uint8_t *outBuffer" +.Fc +.Ft int +.Fo rijndael_blockDecrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputLen" +.Fa "uint8_t *outBuffer" +.Fc +.Ft int +.Fo rijndael_padDecrypt +.Fa "cipherInstance *cipher" +.Fa "keyInstance *key" +.Fa "uint8_t *input" +.Fa "int inputOctets" +.Fa "uint8_t *outBuffer" +.Fc +.Sh DESCRIPTION +The +.Fn rijndael_makeKey +function is used to set up the key schedule in +.Fa key . +The +.Fa direction +(which may be +.Dv DIR_ENCRYPT +or +.Dv DIR_DECRYPT ) +specifies the intended use of the key. +The length of the key (in bits) is given in +.Fa keyLen , +and must be 128, 192 or 256. +The actual key is supplied in the buffer pointed to by +.Fa keyMaterial . +This material may be raw binary data, +or an ASCII string containing a hexadecimal rendition +of the raw binary data, +dependent on a compile-time option in the +.Nm +sources, +.Dv BINARY_KEY_MATERIAL . +.Sh RETURN VALUES +The +.Fn rijndael_makeKey +function will return +.Dv BAD_KEY_INSTANCE +if a +.Dv NULL +.Fa key +is passed, +.Dv BAD_KEY_DIR +if +.Fa direction +is not +.Dv DIR_ENCRYPT +or +.Dv DIR_DECRYPT , +.Dv BAD_KEY_MAT +if the key materials are not a hexadecimal string +(and binary keys are not set), +and +.Dv TRUE +otherwise. +.Sh AUTHORS +.An Mark R V Murray Property changes on: user/imp/camdoc/rijndael.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devtoname.9 =================================================================== --- user/imp/camdoc/devtoname.9 (nonexistent) +++ user/imp/camdoc/devtoname.9 (revision 296049) @@ -0,0 +1,48 @@ +.\" Copyright (c) 1999 Chris Costello +.\" 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 February 10, 2012 +.Dt DEVTONAME 9 +.Os +.Sh NAME +.Nm devtoname +.Nd "converts character device into a string indicating the device name" +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft const char * +.Fn devtoname "struct cdev *dev" +.Sh DESCRIPTION +The +.Fn devtoname +function returns a pointer to the name of the device passed to it. +The name is whatever was set to it in +.Fn make_dev . +.Sh HISTORY +The +.Fn devtoname +interface first appeared in +.Fx 4.0 Property changes on: user/imp/camdoc/devtoname.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/physio.9 =================================================================== --- user/imp/camdoc/physio.9 (nonexistent) +++ user/imp/camdoc/physio.9 (revision 296049) @@ -0,0 +1,131 @@ +.\" $NetBSD: physio.9,v 1.2 1996/11/11 00:05:12 lukem 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 January 19, 2012 +.Dt PHYSIO 9 +.Os +.Sh NAME +.Nm physio +.Nd initiate I/O on raw devices +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/bio.h +.In sys/buf.h +.Ft int +.Fn physio "struct cdev *dev" "struct uio *uio" "int ioflag" +.Sh DESCRIPTION +The +.Fn physio +is a helper function typically called from character device +.Fn read +and +.Fn write +routines to start I/O on a user process buffer. +The maximum amount of data to transfer with each call +is determined by +.Fa dev->si_iosize_max . +The +.Fn physio +call converts the I/O request into a +.Fn strategy +request and passes the new request to the driver's +.Fn strategy +routine for processing. +.Pp +Since +.Fa uio +normally describes user space addresses, +.Fn physio +needs to lock those pages into memory. +This is done by calling +.Fn vmapbuf +for the appropriate pages. +.Fn physio +always awaits the completion of the entire requested transfer before +returning, unless an error condition is detected earlier. +.Pp +A break-down of the arguments follows: +.Bl -tag -width indent +.It Fa dev +The device number identifying the device to interact with. +.It Fa uio +The description of the entire transfer as requested by the user process. +Currently, the results of passing a +.Fa uio +structure with the +.Va uio_segflg +set to anything other than +.Dv UIO_USERSPACE +are undefined. +.It Fa ioflag +The ioflag argument from the +.Fn read +or +.Fn write +function calling +.Fn physio . +.El +.Sh RETURN VALUES +If successful +.Fn physio +returns 0. +.Er EFAULT +is returned if the address range described by +.Fa uio +is not accessible by the requesting process. +.Fn physio +will return any error resulting from calls to the device strategy routine, +by examining the +.Dv B_ERROR +buffer flag and the +.Va b_error +field. +Note that the actual transfer size may be less than requested by +.Fa uio +if the device signals an +.Dq "end of file" +condition. +.Sh SEE ALSO +.Xr read 2 , +.Xr write 2 +.Sh HISTORY +The +.Nm +manual page is originally from +.Nx +with minor changes for applicability with +.Fx . +.Pp +The +.Nm +call has been completely re-written for providing higher +I/O and paging performance. Property changes on: user/imp/camdoc/physio.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/uio.9 =================================================================== --- user/imp/camdoc/uio.9 (nonexistent) +++ user/imp/camdoc/uio.9 (revision 296049) @@ -0,0 +1,215 @@ +.\" +.\" Copyright (c) 1997 Joerg Wunsch +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 19, 2012 +.Dt UIO 9 +.Os +.Sh NAME +.Nm uio , +.Nm uiomove , +.Nm uiomove_nofault +.Nd device driver I/O routines +.Sh SYNOPSIS +.In sys/types.h +.In sys/uio.h +.Bd -literal +struct uio { + struct iovec *uio_iov; /* scatter/gather list */ + int uio_iovcnt; /* length of scatter/gather list */ + off_t uio_offset; /* offset in target object */ + ssize_t uio_resid; /* remaining bytes to copy */ + enum uio_seg uio_segflg; /* address space */ + enum uio_rw uio_rw; /* operation */ + struct thread *uio_td; /* owner */ +}; +.Ed +.Ft int +.Fn uiomove "void *buf" "int howmuch" "struct uio *uiop" +.Ft int +.Fn uiomove_nofault "void *buf" "int howmuch" "struct uio *uiop" +.Sh DESCRIPTION +The functions +.Fn uiomove +and +.Fn uiomove_nofault +are used to transfer data between buffers and I/O vectors that might +possibly cross the user/kernel space boundary. +.Pp +As a result of any +.Xr read 2 , +.Xr write 2 , +.Xr readv 2 , +or +.Xr writev 2 +system call that is being passed to a character-device driver, the +appropriate driver +.Va d_read +or +.Va d_write +entry will be called with a pointer to a +.Vt "struct uio" +being passed. +The transfer request is encoded in this structure. +The driver itself should use +.Fn uiomove +or +.Fn uiomove_nofault +to get at the data in this structure. +.Pp +The fields in the +.Vt uio +structure are: +.Bl -tag -width ".Va uio_iovcnt" +.It Va uio_iov +The array of I/O vectors to be processed. +In the case of scatter/gather +I/O, this will be more than one vector. +.It Va uio_iovcnt +The number of I/O vectors present. +.It Va uio_offset +The offset into the device. +.It Va uio_resid +The remaining number of bytes to process, updated after transfer. +.It Va uio_segflg +One of the following flags: +.Bl -tag -width ".Dv UIO_USERSPACE" +.It Dv UIO_USERSPACE +The I/O vector points into a process's address space. +.It Dv UIO_SYSSPACE +The I/O vector points into the kernel address space. +.It Dv UIO_NOCOPY +Do not copy, already in object. +.El +.It Va uio_rw +The direction of the desired transfer, either +.Dv UIO_READ +or +.Dv UIO_WRITE . +.It Va uio_td +The pointer to a +.Vt "struct thread" +for the associated thread; used if +.Va uio_segflg +indicates that the transfer is to be made from/to a process's address +space. +.El +.Pp +The function +.Fn uiomove_nofault +requires that the buffer and I/O vectors be accessible without +incurring a page fault. +The source and destination addresses must be physically mapped for +read and write access, respectively, and neither the source nor +destination addresses may be pageable. +Thus, the function +.Fn uiomove_nofault +can be called from contexts where acquiring virtual memory system +locks or sleeping are prohibited. +.Sh RETURN VALUES +On success +.Fn uiomove +and +.Fn uiomove_nofault +will return 0; on error they will return an appropriate error code. +.Sh EXAMPLES +The idea is that the driver maintains a private buffer for its data, +and processes the request in chunks of maximal the size of this +buffer. +Note that the buffer handling below is very simplified and +will not work (the buffer pointer is not being advanced in case of a +partial read), it is just here to demonstrate the +.Nm +handling. +.Bd -literal +/* MIN() can be found there: */ +#include + +#define BUFSIZE 512 +static char buffer[BUFSIZE]; + +static int data_available; /* amount of data that can be read */ + +static int +fooread(struct cdev *dev, struct uio *uio, int flag) +{ + int rv, amnt; + + rv = 0; + while (uio->uio_resid > 0) { + if (data_available > 0) { + amnt = MIN(uio->uio_resid, data_available); + rv = uiomove(buffer, amnt, uio); + if (rv != 0) + break; + data_available -= amnt; + } else + tsleep(...); /* wait for a better time */ + } + if (rv != 0) { + /* do error cleanup here */ + } + return (rv); +} +.Ed +.Sh ERRORS +.Fn uiomove +and +.Fn uiomove_nofault +will fail and return the following error code if: +.Bl -tag -width Er +.It Bq Er EFAULT +The invoked +.Xr copyin 9 +or +.Xr copyout 9 +returned +.Er EFAULT +.El +.Pp +In addition, +.Fn uiomove_nofault +will fail and return the following error code if: +.Bl -tag -width Er +.It Bq Er EFAULT +A page fault occurs. +.El +.Sh SEE ALSO +.Xr read 2 , +.Xr readv 2 , +.Xr write 2 , +.Xr writev 2 , +.Xr copyin 9 , +.Xr copyout 9 , +.Xr sleep 9 +.Sh HISTORY +The +.Nm +mechanism appeared in some early version of +.Ux . +.Sh AUTHORS +This manual page was written by +.An J\(:org Wunsch . Property changes on: user/imp/camdoc/uio.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vcount.9 =================================================================== --- user/imp/camdoc/vcount.9 (nonexistent) +++ user/imp/camdoc/vcount.9 (revision 296049) @@ -0,0 +1,73 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Andrew Stevenson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" If this manual page travels to places exotic (like projects other than +.\" FreeBSD) I would love to hear about it. +.\" Andrew +.\" +.\" $FreeBSD$ +.\" +.Dd January 19, 2012 +.Dt VCOUNT 9 +.Os +.Sh NAME +.Nm vcount , +.Nm count_dev +.Nd "get total number of references to a device" +.Sh SYNOPSIS +.In sys/param.h +.In sys/time.h +.In sys/conf.h +.In sys/vnode.h +.Ft int +.Fn vcount "struct vnode *vp" +.Ft int +.Fn count_dev "struct cdev *dev" +.Sh DESCRIPTION +.Fn vcount +is used to get the number of references to a particular device. +It allows for the fact that multiple vnodes may reference the same device. +.Fn count_dev +does the same thing as +.Fn vcount , +but takes a +.Vt "struct cdev" +rather than a +.Vt "struct vnode" +pointer as an argument. +.Sh RETURN VALUES +.Fn vcount +and +.Fn count_dev +both return the number of references to the device. +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Andrew Stevenson . Property changes on: user/imp/camdoc/vcount.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/memcchr.9 =================================================================== --- user/imp/camdoc/memcchr.9 (nonexistent) +++ user/imp/camdoc/memcchr.9 (revision 296049) @@ -0,0 +1,59 @@ +.\" Copyright (c) 2012 Ed Schouten +.\" 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 January 1, 2012 +.Dt MEMCCHR 9 +.Os +.Sh NAME +.Nm memcchr +.Nd locate the complement of a byte in byte string +.Sh SYNOPSIS +.In sys/libkern.h +.Ft void * +.Fn memcchr "const void *b" "int c" "size_t len" +.Sh DESCRIPTION +The +.Fn memcchr +function locates the first occurrence of a byte unequal to +.Fa c +(converted to an +.Vt "unsigned char" ) +in string +.Fa b . +.Sh RETURN VALUES +The +.Fn memcchr +function returns a pointer to the byte located, or NULL if no such byte +exists within +.Fa len +bytes. +.Sh SEE ALSO +.Xr memchr 3 +.Sh HISTORY +The +.Fn memcchr +function first appeared in +.Fx 10.0 . Property changes on: user/imp/camdoc/memcchr.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/driver.9 =================================================================== --- user/imp/camdoc/driver.9 (nonexistent) +++ user/imp/camdoc/driver.9 (revision 296049) @@ -0,0 +1,116 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 22, 2011 +.Dt DRIVER 9 +.Os +.Sh NAME +.Nm driver +.Nd structure describing a device driver +.Sh SYNOPSIS +.Bd -literal +#include +#include +#include +#include + +static int foo_probe(device_t); +static int foo_attach(device_t); +static int foo_detach(device_t); +static int foo_frob(device_t, int, int); +static int foo_twiddle(device_t, char *); + +static device_method_t foo_methods[] = { + /* Methods from the device interface */ + DEVMETHOD(device_probe, foo_probe), + DEVMETHOD(device_attach, foo_attach), + DEVMETHOD(device_detach, foo_detach), + + /* Methods from the bogo interface */ + DEVMETHOD(bogo_frob, foo_frob), + DEVMETHOD(bogo_twiddle, foo_twiddle), + + /* Terminate method list */ + DEVMETHOD_END +}; + +static driver_t foo_driver = { + "foo", + foo_methods, + sizeof(struct foo_softc) +}; + +static devclass_t foo_devclass; + +DRIVER_MODULE(foo, bogo, foo_driver, foo_devclass, NULL, NULL); +.Ed +.Sh DESCRIPTION +Each driver in the kernel is described by a +.Dv driver_t +structure. +The structure contains the name of the device, a pointer +to a list of methods, an indication of the kind of device which the +driver implements and the size of the private data which the driver +needs to associate with a device instance. +Each driver will implement +one or more sets of methods (called interfaces). +The example driver +implements the standard "driver" interface and the fictitious "bogo" +interface. +.Pp +When a driver is registered with the system (by the +.Dv DRIVER_MODULE +macro, see +.Xr DRIVER_MODULE 9 ) , +it is added to the list of drivers contained in the devclass +of its parent bus type. +For instance all PCI drivers would be +contained in the devclass named "pci" and all ISA drivers would be +in the devclass named "isa". +The reason the drivers are not held in the device object of the parent +bus is to handle multiple instances of a given type of bus. +The +.Dv DRIVER_MODULE +macro will also create the devclass with the name of the driver and +can optionally call extra initialisation code in the driver by +specifying an extra module event handler and argument as the last two +arguments. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_SHUTDOWN 9 , +.Xr DRIVER_MODULE 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/driver.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/kobj.9 =================================================================== --- user/imp/camdoc/kobj.9 (nonexistent) +++ user/imp/camdoc/kobj.9 (revision 296049) @@ -0,0 +1,156 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2000 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 14, 2011 +.Dt KOBJ 9 +.Os +.Sh NAME +.Nm kobj +.Nd a kernel object system for FreeBSD +.Sh SYNOPSIS +.In sys/param.h +.In sys/kobj.h +.Ft void +.Fn kobj_class_compile "kobj_class_t cls" +.Ft void +.Fn kobj_class_compile_static "kobj_class_t cls" "kobj_ops_t ops" +.Ft void +.Fn kobj_class_free "kobj_class_t cls" +.Ft kobj_t +.Fn kobj_create "kobj_class_t cls" "struct malloc_type *mtype" "int mflags" +.Ft void +.Fn kobj_init "kobj_t obj" "kobj_class_t cls" +.Ft void +.Fn kobj_init_static "kobj_t obj" "kobj_class_t cls" +.Ft void +.Fn kobj_delete "kobj_t obj" "struct malloc_type *mtype" +.Fn DEFINE_CLASS name "kobj_method_t *methods" "size_t size" +.Sh DESCRIPTION +The kernel object system implements an object-oriented programming +system in the +.Fx +kernel. +The system is based around the concepts of interfaces, which are +descriptions of sets of methods; classes, which are lists of functions +implementing certain methods from those interfaces; and objects, +which combine a class with a structure in memory. +.Pp +Methods are called using a dynamic method dispatching algorithm which +is designed to allow new interfaces and classes to be introduced into +the system at runtime. +The method dispatch algorithm is designed to be both fast and robust +and is only slightly more expensive than a direct function call, +making kernel objects suitable for performance-critical algorithms. +.Pp +Suitable uses for kernel objects are any algorithms which need some +kind of polymorphism (i.e., many different objects which can be treated +in a uniform way). +The common behaviour of the objects is described by a suitable +interface and each different type of object is implemented by a +suitable class. +.Pp +The simplest way to create a kernel object is to call +.Fn kobj_create +with a suitable class, malloc type and flags (see +.Xr malloc 9 +for a description of the malloc type and flags). +This will allocate memory for the object based on the object size +specified by the class and initialise it by zeroing the memory and +installing a pointer to the class' method dispatch table. +Objects created in this way should be freed by calling +.Fn kobj_delete . +.Pp +Clients which would like to manage the allocation of memory +themselves should call +.Fn kobj_init +or +.Fn kobj_init_static +with a pointer to the memory for the object and the class which +implements it. +It is also possible to use +.Fn kobj_init +and +.Fn kobj_init_static +to change the class for an object. +This should be done with care as the classes must agree on the layout +of the object. +The device framework uses this feature to associate drivers with +devices. +.Pp +The functions +.Fn kobj_class_compile , +.Fn kobj_class_compile_static +and +.Fn kobj_class_free +are used to process a class description to make method dispatching +efficient. +A client should not normally need to call these since a class +will automatically be compiled the first time it is used. +If a class is to be used before +.Xr malloc 9 +and +.Xr mutex 9 +are initialised, +then +.Fn kobj_class_compile_static +should be called with the class and a pointer to a statically +allocated +.Vt kobj_ops +structure before the class is used to initialise any objects. +In that case, also +.Fn kobj_init_static +should be used instead of +.Fn kobj_init . +.Pp +To define a class, first define a simple array of +.Vt kobj_method_t . +Each method which the class implements should be entered into the +table using the macro +.Fn KOBJMETHOD +which takes the name of the method (including its interface) and a +pointer to a function which implements it. +The table should be terminated with two zeros. +The macro +.Fn DEFINE_CLASS +can then be used to initialise a +.Vt kobj_class_t +structure. +The size argument to +.Fn DEFINE_CLASS +specifies how much memory should be allocated for each object. +.Sh HISTORY +Some of the concepts for this interface appeared in the device +framework used for the alpha port of +.Fx 3.0 +and more widely in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/kobj.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/copy.9 =================================================================== --- user/imp/camdoc/copy.9 (nonexistent) +++ user/imp/camdoc/copy.9 (revision 296049) @@ -0,0 +1,173 @@ +.\" $NetBSD: copy.9,v 1.2 1996/01/09 03:23:04 thorpej Exp $ +.\" +.\" Copyright (c) 1996 Jason R. Thorpe. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed by Kenneth Stailey. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed for the NetBSD Project +.\" by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 9, 2011 +.Dt COPY 9 +.Os +.Sh NAME +.Nm copy , +.Nm copyin , +.Nm copyin_nofault , +.Nm copyout , +.Nm copyout_nofault , +.Nm copystr , +.Nm copyinstr +.Nd kernel copy functions +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft int +.Fn copyin "const void *uaddr" "void *kaddr" "size_t len" +.Ft int +.Fn copyin_nofault "const void *uaddr" "void *kaddr" "size_t len" +.Ft int +.Fn copyout "const void *kaddr" "void *uaddr" "size_t len" +.Ft int +.Fn copyout_nofault "const void *kaddr" "void *uaddr" "size_t len" +.Ft int +.Fn copystr "const void *kfaddr" "void *kdaddr" "size_t len" "size_t *done" +.Ft int +.Fn copyinstr "const void *uaddr" "void *kaddr" "size_t len" "size_t *done" +.\" .Ft int +.\" .Fn copyoutstr "const void *kaddr" "void *uaddr" "size_t len" "size_t *done" +.Sh DESCRIPTION +The +.Nm +functions are designed to copy contiguous data from one address +to another. +All but +.Fn copystr +copy data from user-space to kernel-space or vice-versa. +.Pp +The +.Fn copyin +and +.Fn copyin_nofault +functions copy +.Fa len +bytes of data from the user-space address +.Fa uaddr +to the kernel-space address +.Fa kaddr . +.Pp +The +.Fn copyout +and +.Fn copyout_nofault +functions copy +.Fa len +bytes of data from the kernel-space address +.Fa kaddr +to the user-space address +.Fa uaddr . +.Pp +The +.Fn copyin_nofault +and +.Fn copyout_nofault +functions require that the kernel-space and user-space data be +accessible without incurring a page fault. +The source and destination addresses must be physically mapped for +read and write access, respectively, and neither the source nor +destination addresses may be pageable. +.Pp +The +.Fn copystr +function copies a NUL-terminated string, at most +.Fa len +bytes long, from kernel-space address +.Fa kfaddr +to kernel-space address +.Fa kdaddr . +The number of bytes actually copied, including the terminating +NUL, is returned in +.Fa *done +(if +.Fa done +is +.No non- Ns Dv NULL ) . +.Pp +The +.Fn copyinstr +function copies a NUL-terminated string, at most +.Fa len +bytes long, from user-space address +.Fa uaddr +to kernel-space address +.Fa kaddr . +The number of bytes actually copied, including the terminating +NUL, is returned in +.Fa *done +(if +.Fa done +is +.No non- Ns Dv NULL ) . +.\" .It Fn copyoutstr +.\" Copies a NUL-terminated string, at most +.\" bytes long, from kernel-space address +.\" .Fa kaddr +.\" to user-space address +.\" .Fa uaddr . +.\" The number of bytes actually copied, including the terminating +.\" NUL, is returned in +.\" .Fa *done . +.Sh RETURN VALUES +The +.Nm +functions return 0 on success or +.Er EFAULT +if a bad address is encountered. +In addition, the +.Fn copyin_nofault +and +.Fn copyout_nofault +functions return +.Er EFAULT +if a page fault occurs, and the +.Fn copystr +and +.Fn copyinstr +.\" .Fn copyinstr , +.\" and +.\" .Fn copyoutstr +functions return +.Er ENAMETOOLONG +if the string is longer than +.Fa len +bytes. +.Sh SEE ALSO +.Xr fetch 9 , +.Xr store 9 Property changes on: user/imp/camdoc/copy.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_sysctl.9 =================================================================== --- user/imp/camdoc/device_get_sysctl.9 (nonexistent) +++ user/imp/camdoc/device_get_sysctl.9 (revision 296049) @@ -0,0 +1,58 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2006 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 18, 2011 +.Dt DEVICE_GET_SYSCTL 9 +.Os +.Sh NAME +.Nm device_get_sysctl_ctx , +.Nm device_get_sysctl_tree +.Nd manipulate the sysctl oid tree for driver specific sysctl nodes +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft "struct sysctl_ctx_list *" +.Fn device_get_sysctl_ctx "device_t dev" +.Ft "struct sysctl_oid *" +.Fn device_get_sysctl_tree "device_t dev" +.Sh DESCRIPTION +The newbus system automatically adds a sysctl node for each device +in the system. +This node can be accessed with the +.Fn device_get_sysctl_tree +function. +The context for the node can be obtained with the +.Fn device_get_sysctl_ctx +function. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh . Property changes on: user/imp/camdoc/device_get_sysctl.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/unr.9 =================================================================== --- user/imp/camdoc/unr.9 (nonexistent) +++ user/imp/camdoc/unr.9 (revision 296049) @@ -0,0 +1,110 @@ +.\" Copyright (c) 2005 Gleb Smirnoff +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 5, 2010 +.Dt UNR 9 +.Os +.Sh NAME +.Nm new_unrhdr , +.Nm delete_unrhdr , +.Nm alloc_unr , +.Nm alloc_unr_specific , +.Nm free_unr +.Nd "kernel unit number allocator" +.Sh SYNOPSIS +.In sys/systm.h +.Ft "struct unrhdr *" +.Fn new_unrhdr "int low" "int high" "struct mtx *mutex" +.Ft void +.Fn delete_unrhdr "struct unrhdr *uh" +.Ft int +.Fn alloc_unr "struct unrhdr *uh" +.Ft int +.Fn alloc_unrl "struct unrhdr *uh" +.Ft int +.Fn alloc_unr_specific "struct unrhdr *uh" "u_int item" +.Ft void +.Fn free_unr "struct unrhdr *uh" "u_int item" +.Sh DESCRIPTION +The kernel unit number allocator is a generic facility, which allows to allocate +unit numbers within a specified range. +.Bl -tag -width indent +.It Fn new_unrhdr low high mutex +Initialize a new unit number allocator entity. +The +.Fa low +and +.Fa high +arguments +specify minimum and maximum number of unit numbers. +There is no cost associated with the range of unit numbers, so unless the resource +really is finite, +.Dv INT_MAX +can be used. +If +.Fa mutex +is not +.Dv NULL , +it is used for locking when allocating and freeing units. +Otherwise, internal mutex is used. +.It Fn delete_unrhdr uh +Destroy specified unit number allocator entity. +.It Fn alloc_unr uh +Return a new unit number. +The lowest free number is always allocated. +This function does not allocate memory and never sleeps, however it may +block on a mutex. +If no free unit numbers are left, +.Li \-1 +is returned. +.It Fn alloc_unrl uh +Same as +.Fn alloc_unr +except that mutex is assumed to be already locked and thus is not used. +.It Fn alloc_unr_specific uh item +Allocate a specific unit number. +This function allocates memory and thus may sleep. +The allocated unit number is returned on success. +If the specified number is already allocated or out of the range, +.Li \-1 +is returned. +.It Fn free_unr uh item +Free a previously allocated unit number. +This function may require allocating memory, and thus it can sleep. +There is no pre-locked variant. +.El +.Sh CODE REFERENCES +The above functions are implemented in +.Pa sys/kern/subr_unit.c . +.Sh HISTORY +Kernel unit number allocator first appeared in +.Fx 6.0 . +.Sh AUTHORS +.An -nosplit +Kernel unit number allocator was written by +.An Poul-Henning Kamp . +This manpage was written by +.An Gleb Smirnoff . Property changes on: user/imp/camdoc/unr.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ithread.9 =================================================================== --- user/imp/camdoc/ithread.9 (nonexistent) +++ user/imp/camdoc/ithread.9 (revision 296049) @@ -0,0 +1,351 @@ +.\" Copyright (c) 2001 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 August 25, 2006 +.Dt ITHREAD 9 +.Os +.Sh NAME +.Nm ithread_add_handler , +.Nm ithread_create , +.Nm ithread_destroy , +.Nm ithread_priority , +.Nm ithread_remove_handler , +.Nm ithread_schedule +.Nd kernel interrupt threads +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.In sys/interrupt.h +.Ft int +.Fo ithread_add_handler +.Fa "struct ithd *ithread" +.Fa "const char *name" +.Fa "driver_intr_t handler" +.Fa "void *arg" +.Fa "u_char pri" +.Fa "enum intr_type flags" +.Fa "void **cookiep" +.Fc +.Ft int +.Fo ithread_create +.Fa "struct ithd **ithread" +.Fa "int vector" +.Fa "int flags" +.Fa "void (*disable)(int)" +.Fa "void (*enable)(int)" +.Fa "const char *fmt" +.Fa "..." +.Fc +.Ft int +.Fn ithread_destroy "struct ithd *ithread" +.Ft u_char +.Fn ithread_priority "enum intr_type flags" +.Ft int +.Fn ithread_remove_handler "void *cookie" +.Ft int +.Fn ithread_schedule "struct ithd *ithread" "int do_switch" +.Sh DESCRIPTION +Interrupt threads are kernel threads that run a list of handlers when +triggered by either a hardware or software interrupt. +Each interrupt handler has a name, handler function, handler argument, +priority, and various flags. +Each interrupt thread maintains a list of handlers sorted by priority. +This results in higher priority handlers being executed prior to lower +priority handlers. +Each thread assumes the priority of its highest priority handler for its +process priority, or +.Dv PRIO_MAX +if it has no handlers. +Interrupt threads are also associated with a single interrupt source, +represented as a vector number. +.Pp +The +.Fn ithread_create +function creates a new interrupt thread. +The +.Fa ithread +argument points to an +.Vt struct ithd +pointer that will point to the newly created thread upon success. +The +.Fa vector +argument specifies the interrupt source to associate this thread with. +The +.Fa flags +argument is a mask of properties of this thread. +The only valid flag currently for +.Fn ithread_create +is +.Dv IT_SOFT +to specify that this interrupt thread is a software interrupt. +The +.Fa enable +and +.Fa disable +arguments specify optional functions used to enable and disable this +interrupt thread's interrupt source. +The functions receive the vector corresponding to the thread's interrupt +source as their only argument. +The remaining arguments form a +.Xr printf 9 +argument list that is used to build the base name of the new ithread. +The full name of an interrupt thread is formed by concatenating the base +name of an interrupt thread with the names of all of its interrupt handlers. +.Pp +The +.Fn ithread_destroy +function destroys a previously created interrupt thread by releasing its +resources and arranging for the backing kernel thread to terminate. +An interrupt thread can only be destroyed if it has no handlers remaining. +.Pp +The +.Fn ithread_add_handler +function adds a new handler to an existing interrupt thread specified by +.Fa ithread . +The +.Fa name +argument specifies a name for this handler. +The +.Fa handler +and +.Fa arg +arguments provide the function to execute for this handler and an argument +to pass to it. +The +.Fa pri +argument specifies the priority of this handler and is used both in sorting +it in relation to the other handlers for this thread and to specify the +priority of the backing kernel thread. +The +.Fa flags +argument can be used to specify properties of this handler as defined in +.In sys/bus.h . +If +.Fa cookiep +is not +.Dv NULL , +then it will be assigned a cookie that can be used later to remove this +handler. +.Pp +The +.Fn ithread_remove_handler +removes a handler from an interrupt thread. +The +.Fa cookie +argument specifies the handler to remove from its thread. +.Pp +The +.Fn ithread_schedule +function schedules an interrupt thread to run. +If the +.Fa do_switch +argument is non-zero and the interrupt thread is idle, then a context switch +will be forced after putting the interrupt thread on the run queue. +.Pp +The +.Fn ithread_priority +function translates the +.Dv INTR_TYPE_* +interrupt flags into interrupt handler priorities. +.Pp +The interrupt flags not related to the type of a particular interrupt +.Pq Dv INTR_TYPE_* +can be used to specify additional properties of both hardware and software +interrupt handlers. +The +.Dv INTR_EXCL +flag specifies that this handler cannot share an interrupt thread with +another handler. +The +.Dv INTR_MPSAFE +flag specifies that this handler is MP safe in that it does not need the +Giant mutex to be held while it is executed. +The +.Dv INTR_ENTROPY +flag specifies that the interrupt source this handler is tied to is a good +source of entropy, and thus that entropy should be gathered when an interrupt +from the handler's source triggers. +Presently, the +.Dv INTR_ENTROPY +flag is not valid for software interrupt handlers. +.Pp +It is not permitted to sleep in an interrupt thread; hence, any memory +or zone allocations in an interrupt thread should be specified with the +.Dv M_NOWAIT +flag set. +Any allocation errors must be handled thereafter. +.Sh RETURN VALUES +The +.Fn ithread_add_handler , +.Fn ithread_create , +.Fn ithread_destroy , +.Fn ithread_remove_handler , +and +.Fn ithread_schedule +functions return zero on success and non-zero on failure. +The +.Fn ithread_priority +function returns a process priority corresponding to the passed in interrupt +flags. +.Sh EXAMPLES +The +.Fn swi_add +function demonstrates the use of +.Fn ithread_create +and +.Fn ithread_add_handler . +.Bd -literal -offset indent +int +swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler, + void *arg, int pri, enum intr_type flags, void **cookiep) +{ + struct proc *p; + struct ithd *ithd; + int error; + + if (flags & INTR_ENTROPY) + return (EINVAL); + + ithd = (ithdp != NULL) ? *ithdp : NULL; + + if (ithd != NULL) { + if ((ithd->it_flags & IT_SOFT) == 0) + return(EINVAL); + } else { + error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL, + "swi%d:", pri); + if (error) + return (error); + + if (ithdp != NULL) + *ithdp = ithd; + } + return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT, + flags, cookiep)); +} +.Ed +.Sh ERRORS +The +.Fn ithread_add_handler +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +Any of the +.Fa ithread , +.Fa handler , +or +.Fa name +arguments are +.Dv NULL . +.It Bq Er EINVAL +The +.Dv INTR_EXCL +flag is specified and the interrupt thread +.Fa ithread +already has at least one handler, or the interrupt thread +.Fa ithread +already has an exclusive handler. +.It Bq Er ENOMEM +Could not allocate needed memory for this handler. +.El +.Pp +The +.Fn ithread_create +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The system-imposed limit on the total +number of processes under execution would be exceeded. +The limit is given by the +.Xr sysctl 3 +MIB variable +.Dv KERN_MAXPROC . +.It Bq Er EINVAL +A flag other than +.Dv IT_SOFT +was specified in the +.Fa flags +parameter. +.It Bq Er ENOMEM +Could not allocate needed memory for this interrupt thread. +.El +.Pp +The +.Fn ithread_destroy +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ithread +argument is +.Dv NULL . +.It Bq Er EINVAL +The interrupt thread pointed to by +.Fa ithread +has at least one handler. +.El +.Pp +The +.Fn ithread_remove_handler +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa cookie +argument is +.Dv NULL . +.El +.Pp +The +.Fn ithread_schedule +function will fail if: +.Bl -tag -width Er +.It Bq Er EINVAL +The +.Fa ithread +argument is +.Dv NULL . +.It Bq Er EINVAL +The interrupt thread pointed to by +.Fa ithread +has no interrupt handlers. +.El +.Sh SEE ALSO +.Xr kthread 9 , +.Xr malloc 9 , +.Xr swi 9 , +.Xr uma 9 +.Sh HISTORY +Interrupt threads and their corresponding API first appeared in +.Fx 5.0 . +.Sh BUGS +Currently +.Vt struct ithd +represents both an interrupt source and an interrupt thread. +There should be a separate +.Vt struct isrc +that contains a vector number, enable and disable functions, etc.\& that +an ithread holds a reference to. Property changes on: user/imp/camdoc/ithread.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_READDIR.9 =================================================================== --- user/imp/camdoc/VOP_READDIR.9 (nonexistent) +++ user/imp/camdoc/VOP_READDIR.9 (revision 296049) @@ -0,0 +1,108 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_READDIR 9 +.Os +.Sh NAME +.Nm VOP_READDIR +.Nd read contents of a directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/dirent.h +.In sys/vnode.h +.Ft int +.Fn VOP_READDIR "struct vnode *vp" "struct uio *uio" "struct ucred *cred" "int *eofflag" "int *ncookies" "u_long **cookies" +.Sh DESCRIPTION +Read directory entries. +.Bl -tag -width ncookies +.It Fa vp +The vnode of the directory. +.It Fa uio +Where to read the directory contents. +.It Fa cred +The caller's credentials. +.It Fa eofflag +Return end of file status +.Dv ( NULL +if not wanted). +.It Fa ncookies +Number of directory cookies generated for NFS +.Dv ( NULL +if not wanted). +.It Fa cookies +Directory seek cookies generated for NFS +.Dv ( NULL +if not wanted). +.El +The directory contents are read into +.Vt struct dirent +structures. +If the on-disc data structures differ from this then they +should be translated. +.Sh LOCKS +The directory should be locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Pp +If this is called from the NFS server, the extra arguments +.Fa eofflag , +.Fa ncookies +and +.Fa cookies +are given. +The value of +.Fa *eofflag +should be set to TRUE if the end of the directory is reached while +reading. +The directory seek cookies are returned to the NFS client and may be used +later to restart a directory read part way through the directory. +There should be one cookie returned per directory entry. +The value of +the cookie should be the offset within the directory where the on-disc +version of the appropriate directory entry starts. +Memory for the cookies should be allocated using: +.Bd -literal + ...; + *ncookies = number of entries read; + *cookies = malloc(*ncookies * sizeof(u_long), M_TEMP, M_WAITOK); +.Ed +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +An attempt was made to read from an illegal offset in the directory. +.It Bq Er EIO +A read error occurred while reading the directory. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_READDIR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211_ddb.9 =================================================================== --- user/imp/camdoc/ieee80211_ddb.9 (nonexistent) +++ user/imp/camdoc/ieee80211_ddb.9 (revision 296049) @@ -0,0 +1,71 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 4, 2009 +.Dt IEEE80211_DDB 9 +.Os +.Sh NAME +.Nm ieee80211_ddb +.Nd 802.11 ddb support +.Sh SYNOPSIS +.Bd -ragged +.Cd options DDB +.Ed +.Bd -ragged +.Cd show vap [addr] +.Cd show all vaps +.Cd show com [addr] +.Cd show sta [addr] +.Cd show statab [addr] +.Cd show mesh [addr] +.Ed +.Sh DESCRIPTION +The +.Nm net80211 +layer includes +.Xr ddb 4 +support for displaying important data structures. +This is especially important because wireless applications are often +built for embedded environments where cross-machine or post-mortem +debugging facilities like +.Xr kgdb 1 +are infeasible. +.Pp +The most commonly used command is +.Bd -literal -offset indent +show all vaps/a +.Ed +.Pp +which dumps the contents of all +.Vt ieee80211vap , +.Vt ieee80211com , +and +.Vt ieee80211_node +data structures in the system. +.Sh SEE ALSO +.Xr ddb 4 , +.Xr ieee80211 9 Property changes on: user/imp/camdoc/ieee80211_ddb.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/VOP_LISTEXTATTR.9 =================================================================== --- user/imp/camdoc/VOP_LISTEXTATTR.9 (nonexistent) +++ user/imp/camdoc/VOP_LISTEXTATTR.9 (revision 296049) @@ -0,0 +1,136 @@ +.\"- +.\" Copyright (c) 2003 Network Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project in part by Network +.\" Associates Laboratories, the Security Research Division of Network +.\" Associates, Inc. under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), +.\" as part of the DARPA CHATS research program. +.\" +.\" 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 19, 2005 +.Dt VOP_LISTEXTATTR 9 +.Os +.Sh NAME +.Nm VOP_LISTEXTATTR +.Nd retrieve a list of named extended attribute from a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Ft int +.Fo VOP_LISTEXTATTR +.Fa "struct vnode *vp" +.Fa "int attrnamespace" +.Fa "struct uio *uio" +.Fa "size_t *size" +.Fa "struct ucred *cred" +.Fa "struct thread *td" +.Fc +.Sh DESCRIPTION +This vnode call may be used to retrieve a list of named extended attributes +from a specified namespace on a file or directory. +.Pp +Its arguments are: +.Bl -tag -width ".Fa attrnamespace" +.It Fa vp +The vnode of the file or directory. +.It Fa attrnamespace +Integer constant indicating which extended attribute namespace the attribute +name is present in. +.It Fa uio +The location of the data to be read. +The resulting data will be a list of attribute names. +Each list entry consists of a single byte containing the length of +the attribute name, followed by the attribute name. +The attribute name is not terminated by +.Tn ASCII +.Dv NUL . +.It Fa size +If not +.Dv NULL , +on return it will contain the number of bytes required to read the list. +In most cases +.Fa uio +will be +.Dv NULL +when +.Fa size +is not, and vice versa. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread requesting the extended attribute. +.El +.Pp +The +.Fa cred +pointer may be +.Dv NULL +to indicate that access control checks are not to be performed, if possible. +This +.Fa cred +setting might be used to allow the kernel to authorize extended attribute +retrieval that the active process might not be permitted to do. +.Pp +Extended attribute semantics may vary by file system implementing the call. +More information on extended attributes may be found in +.Xr extattr 9 . +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +On success, zero will be returned, and the +.Fa uio +structure will be updated to +reflect the list read. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +The caller does not have the appropriate privilege. +.It Bq Er ENXIO +The request was not valid in this file system for the specified vnode and +attribute name. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EFAULT +The +.Fa uio +structure refers to an invalid userspace address. +.It Bq Er EINVAL +The +.Fa namespace +or +.Fa uio +argument is invalid. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_LISTEXTATTR . +.El +.Sh SEE ALSO +.Xr extattr 9 , +.Xr vnode 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 Property changes on: user/imp/camdoc/VOP_LISTEXTATTR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/runqueue.9 =================================================================== --- user/imp/camdoc/runqueue.9 (nonexistent) +++ user/imp/camdoc/runqueue.9 (revision 296049) @@ -0,0 +1,137 @@ +.\" Copyright (c) 2000-2001 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 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 15, 2010 +.Dt RUNQUEUE 9 +.Os +.Sh NAME +.Nm choosethread , +.Nm procrunnable , +.Nm remrunqueue , +.Nm setrunqueue +.Nd manage the queue of runnable processes +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Vt "extern struct rq itqueues[]" ; +.Vt "extern struct rq rtqueues[]" ; +.Vt "extern struct rq queues[]" ; +.Vt "extern struct rq idqueues[]" ; +.Ft struct thread * +.Fn choosethread "void" +.Ft int +.Fn procrunnable "void" +.Ft void +.Fn remrunqueue "struct thread *td" +.Ft void +.Fn setrunqueue "struct thread *td" +.Sh DESCRIPTION +The run queue consists of four priority queues: +.Va itqueues +for interrupt threads, +.Va rtqueues +for realtime priority processes, +.Va queues +for time sharing processes, and +.Va idqueues +for idle priority processes. +Each priority queue consists of an array of +.Dv NQS +queue header structures. +Each queue header identifies a list of runnable processes of equal priority. +Each queue also has a single word that contains a bit mask identifying +non-empty queues to assist in selecting a process quickly. +These are named +.Va itqueuebits , +.Va rtqueuebits , +.Va queuebits , +and +.Va idqueuebits . +The run queues are protected by the +.Va sched_lock +mutex. +.Pp +.Fn procrunnable +returns zero if there are no runnable processes other than the idle process. +If there is at least one runnable process other than the idle process, it +will return a non-zero value. +Note that the +.Va sched_lock +mutex does +.Em not +need to be held when this function is called. +There is a small race window where one CPU may place a process on the run queue +when there are currently no other runnable processes while another CPU is +calling this function. +In that case the second CPU will simply travel through the idle loop one +additional time before noticing that there is a runnable process. +This works because idle CPUs are not halted in SMP systems. +If idle CPUs are halted in SMP systems, then this race condition might have +more serious repercussions in the losing case, and +.Fn procrunnable +may have to require that the +.Va sched_lock +mutex be acquired. +.Pp +.Fn choosethread +returns the highest priority runnable thread. +If there are no runnable threads, then the idle thread is returned. +This function is called by +.Fn cpu_switch +and +.Fn cpu_throw +to determine which thread to switch to. +.Fn choosethread +must be called with the +.Va sched_lock +mutex held. +.Pp +.Fn setrunqueue +adds the thread +.Fa td +to the tail of the appropriate queue in the proper priority queue. +The thread must be runnable, i.e.\& +.Va p_stat +must be set to +.Dv SRUN . +This function must be called with the +.Va sched_lock +mutex held. +.Pp +.Fn remrunqueue +removes thread +.Fa td +from its run queue. +If +.Fa td +is not on a run queue, then the kernel will +.Xr panic 9 . +This function must be called with the +.Va sched_lock +mutex held. +.Sh SEE ALSO +.Xr cpu_switch 9 , +.Xr scheduler 9 , +.Xr sleepqueue 9 Property changes on: user/imp/camdoc/runqueue.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_VGET.9 =================================================================== --- user/imp/camdoc/VFS_VGET.9 (nonexistent) +++ user/imp/camdoc/VFS_VGET.9 (revision 296049) @@ -0,0 +1,83 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 7, 2005 +.Dt VFS_VGET 9 +.Os +.Sh NAME +.Nm VFS_VGET +.Nd convert an inode number to a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_VGET "struct mount *mp" "ino_t ino" "int flags" "struct vnode **vpp" +.Sh DESCRIPTION +The +.Fn VFS_VGET +looks up or creates a vnode from a (mount, inode#) tuple. +.Pp +Its arguments are: +.Bl -tag -width ".Fa flags" +.It Fa mp +The mount point. +.It Fa ino +The inode representing the file. +This is a unique number assigned by the file system when vnodes are first +created. +.It Fa flags +Additional locking flags to pass through to +.Xr vget 9 . +.It Fa vpp +Return parameter for the vnode. +.El +.Pp +This is an optional file system entry-point for file systems mainly +intended for NFS server use, but many file systems +use it internally in +.Xr VOP_LOOKUP 9 +and similar. +.Pp +If the file system does not support this call, then it should return +.Er EOPNOTSUPP . +.Pp +Please see +.Fn ffs_vget +in +.Pa sys/ufs/ffs/ffs_vfsops.c +for the canonical example. +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vget 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_VGET.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/cr_seeothergids.9 =================================================================== --- user/imp/camdoc/cr_seeothergids.9 (nonexistent) +++ user/imp/camdoc/cr_seeothergids.9 (revision 296049) @@ -0,0 +1,82 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 11, 2003 +.Dt CR_SEEOTHERGIDS 9 +.Os +.Sh NAME +.Nm cr_seeothergids +.Nd determine visibility of objects given their group memberships +.Sh SYNOPSIS +.Ft int +.Fn cr_seeothergids "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +This function determines the visibility of objects in the +kernel based on the group IDs in the credentials +.Fa u1 +and +.Fa u2 +associated with them. +.Pp +The visibility of objects is influenced by the +.Xr sysctl 8 +variable +.Va security.bsd.see_other_gids . +If this variable is non-zero then all objects in the kernel +are visible to each other irrespective of their group membership. +If this variable is zero then the object with credentials +.Fa u2 +is visible to the object with credentials +.Fa u1 +if either +.Fa u1 +is the super-user credential, or if at least one of +.Fa u1 Ns 's +group IDs is present in +.Fa u2 Ns 's +group set. +.Sh SYSCTL VARIABLES +.Bl -tag -width indent +.It Va security.bsd.see_other_gids +Must be non-zero if objects with unprivileged credentials are to be +able to see each other. +.El +.Sh RETURN VALUES +This function returns zero if the object with credential +.Fa u1 +can +.Dq see +the object with credential +.Fa u2 , +or +.Er ESRCH +otherwise. +.Sh SEE ALSO +.Xr cr_seeotheruids 9 , +.Xr p_candebug 9 Property changes on: user/imp/camdoc/cr_seeothergids.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/cr_seeotheruids.9 =================================================================== --- user/imp/camdoc/cr_seeotheruids.9 (nonexistent) +++ user/imp/camdoc/cr_seeotheruids.9 (revision 296049) @@ -0,0 +1,82 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 11, 2003 +.Dt CR_SEEOTHERUIDS 9 +.Os +.Sh NAME +.Nm cr_seeotheruids +.Nd determine visibility of objects given their user credentials +.Sh SYNOPSIS +.Ft int +.Fn cr_seeotheruids "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +This function determines the visibility of objects in the +kernel based on the real user IDs in the credentials +.Fa u1 +and +.Fa u2 +associated with them. +.Pp +The visibility of objects is influenced by the +.Xr sysctl 8 +variable +.Va security.bsd.see_other_uids . +If this variable is non-zero then all objects in the kernel +are visible to each other irrespective of their user IDs. +If this variable is zero then the object with credentials +.Fa u2 +is visible to the object with credentials +.Fa u1 +if either +.Fa u1 +is the super-user credential, or if +.Fa u1 +and +.Fa u2 +have the same real user ID. +.Sh SYSCTL VARIABLES +.Bl -tag -width indent +.It Va security.bsd.see_other_uids +Must be non-zero if objects with unprivileged credentials are to be +able to see each other. +.El +.Sh RETURN VALUES +This function returns zero if the object with credential +.Fa u1 +can +.Dq see +the object with credential +.Fa u2 , +or +.Er ESRCH +otherwise. +.Sh SEE ALSO +.Xr cr_seeothergids 9 , +.Xr p_candebug 9 Property changes on: user/imp/camdoc/cr_seeotheruids.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/p_candebug.9 =================================================================== --- user/imp/camdoc/p_candebug.9 (nonexistent) +++ user/imp/camdoc/p_candebug.9 (revision 296049) @@ -0,0 +1,138 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 19, 2006 +.Dt P_CANDEBUG 9 +.Os +.Sh NAME +.Nm p_candebug +.Nd determine debuggability of a process +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft int +.Fn p_candebug "struct thread *td" "struct proc *p" +.Sh DESCRIPTION +This function can be used to determine if a given process +.Fa p +is debuggable by the thread +.Fa td . +.Sh SYSCTL VARIABLES +The following +.Xr sysctl 8 +variables directly influence the behaviour of +.Fn p_candebug : +.Bl -tag -width indent +.It Va kern.securelevel +Debugging of the init process is not allowed if this variable is +.Li 1 +or greater. +.It Va security.bsd.unprivileged_proc_debug +Must be set to a non-zero value to allow unprivileged processes +access to the kernel's debug facilities. +.El +.Sh RETURN VALUES +The +.Fn p_candebug +function +returns +.Li 0 +if the process denoted by +.Fa p +is debuggable by thread +.Fa td , +or a non-zero error return value otherwise. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCESS +The MAC subsystem denied debuggability. +.It Bq Er EAGAIN +Process +.Fa p +is in the process of being +.Fn exec Ns 'ed. +.It Bq Er EPERM +Thread +.Fa td +lacks super-user credentials and process +.Fa p +is executing a set-user-ID or set-group-ID executable. +.It Bq Er EPERM +Thread +.Fa td +lacks super-user credentials and process +.Fa p Ns 's +group set is not a subset of +.Fa td Ns 's +effective group set. +.It Bq Er EPERM +Thread +.Fa td +lacks super-user credentials and process +.Fa p Ns 's +user IDs do not match thread +.Fa td Ns 's +effective user ID. +.It Bq Er EPERM +Process +.Fa p +denotes the initial process +.Fn initproc +and the +.Xr sysctl 8 +variable +.Va kern.securelevel +is greater than zero. +.It Bq Er ESRCH +Process +.Fa p +is not visible to thread +.Fa td +as determined by +.Xr cr_seeotheruids 9 +or +.Xr cr_seeothergids 9 . +.It Bq Er ESRCH +Thread +.Fa td +has been jailed and process +.Fa p +does not belong to the same jail as +.Fa td . +.It Bq Er ESRCH +The MAC subsystem denied debuggability. +.El +.Sh SEE ALSO +.Xr jail 2 , +.Xr sysctl 8 , +.Xr cr_seeothergids 9 , +.Xr cr_seeotheruids 9 , +.Xr mac 9 , +.Xr p_cansee 9 , +.Xr prison_check 9 Property changes on: user/imp/camdoc/p_candebug.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/p_cansee.9 =================================================================== --- user/imp/camdoc/p_cansee.9 (nonexistent) +++ user/imp/camdoc/p_cansee.9 (revision 296049) @@ -0,0 +1,93 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" Copyright (c) 2006 Ceri Davies +.\" +.\" 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 November 19, 2006 +.Dt P_CANSEE 9 +.Os +.Sh NAME +.Nm p_cansee +.Nd determine visibility of a process +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft int +.Fn p_cansee "struct thread *td" "struct proc *p" +.Sh DESCRIPTION +This function can be used to determine if a given process +.Fa p +is visible to the thread +.Fa td , +where the notion of +.Dq visibility +may be read as +.Dq "awareness of existence" . +.Pp +The function is implemented using +.Xr cr_cansee 9 , +and the dependencies on +.Xr sysctl 8 +variables documented in the +.Xr cr_cansee 9 +manual page apply. +.Sh RETURN VALUES +The +.Fn p_cansee +function +returns +.Li 0 +if the process denoted by +.Fa p +is visible by thread +.Fa td , +or a non-zero error return value otherwise. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ESRCH +Process +.Fa p +is not visible to thread +.Fa td +as determined by +.Xr cr_cansee 9 . +.It Bq Er ESRCH +Thread +.Fa td +has been jailed and process +.Fa p +does not belong to the same jail as +.Fa td . +.It Bq Er ESRCH +The MAC subsystem denied visibility. +.El +.Sh SEE ALSO +.Xr jail 2 , +.Xr sysctl 8 , +.Xr cr_cansee 9 , +.Xr mac 9 , +.Xr p_candebug 9 , +.Xr prison_check 9 Property changes on: user/imp/camdoc/p_cansee.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/prison_check.9 =================================================================== --- user/imp/camdoc/prison_check.9 (nonexistent) +++ user/imp/camdoc/prison_check.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2003 Joseph Koshy +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 11, 2003 +.Dt PRISON_CHECK 9 +.Os +.Sh NAME +.Nm prison_check +.Nd determine if two credentials belong to the same jail +.Sh SYNOPSIS +.In sys/jail.h +.Ft int +.Fn prison_check "struct ucred *cred1" "struct ucred *cred2" +.Sh DESCRIPTION +This function can be used to determine if the two credentials +.Fa cred1 +and +.Fa cred2 +belong to the same jail. +.Sh RETURN VALUES +The +.Fn prison_check +function +returns +.Er ESRCH +if +.Fa cred1 +has been jailed, and +.Fa cred1 +and +.Fa cred2 +do not belong to the same jail. +In all other cases, +.Fn prison_check +returns zero. +.Sh SEE ALSO +.Xr jail 2 Property changes on: user/imp/camdoc/prison_check.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_MOUNT.9 =================================================================== --- user/imp/camdoc/VFS_MOUNT.9 (nonexistent) +++ user/imp/camdoc/VFS_MOUNT.9 (revision 296049) @@ -0,0 +1,84 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 23, 2009 +.Dt VFS_MOUNT 9 +.Os +.Sh NAME +.Nm VFS_MOUNT +.Nd mount a file system +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_MOUNT "struct mount *mp" +.Sh DESCRIPTION +The +.Fn VFS_MOUNT +macro mounts a file system into the system's namespace or updates the +attributes of an already mounted file system. +.Pp +The arguments it expects are: +.Bl -tag -width data +.It Fa mp +Structure representing the file system. +.El +.Pp +The +.Fn VFS_MOUNT +macro is called both to mount new file systems and to change the +attributes of an existing file system. +If the +.Dv MNT_UPDATE +flag is set in +.Fa mp->mnt_flag +then the file system should update its internal state from the value of +.Fa mp->mnt_flag . +This can be used, for instance, to convert a read-only file system to +read-write. +It is also used by +.Xr mountd 8 +to update the NFS export information for the file system. +.Pp +If the +.Dv MNT_UPDATE +flag is not specified, then this is a newly mounted file system. +The file system code should allocate and initialize +any private data needed to represent +the file system (it can use the +.Fa mp->mnt_data +field to store this information). +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_MOUNT.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_QUOTACTL.9 =================================================================== --- user/imp/camdoc/VFS_QUOTACTL.9 (nonexistent) +++ user/imp/camdoc/VFS_QUOTACTL.9 (revision 296049) @@ -0,0 +1,53 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 23, 2009 +.Dt VFS_QUOTACTL 9 +.Os +.Sh NAME +.Nm VFS_QUOTACTL +.Nd manipulate file system quotas +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_QUOTACTL "struct mount *mp" "int cmds" "uid_t uid" "caddr_t arg" +.Sh DESCRIPTION +Implement file system quotas. +See +.Xr quotactl 2 +for a description of the arguments. +.Sh SEE ALSO +.Xr quotactl 2 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_QUOTACTL.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_ROOT.9 =================================================================== --- user/imp/camdoc/VFS_ROOT.9 (nonexistent) +++ user/imp/camdoc/VFS_ROOT.9 (revision 296049) @@ -0,0 +1,67 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 23, 2009 +.Dt VFS_ROOT 9 +.Os +.Sh NAME +.Nm VFS_ROOT +.Nd return the root vnode of a file system +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_ROOT "struct mount *mp" "int flags" "struct vnode **vpp" +.Sh DESCRIPTION +Return a locked vnode for the root directory of the file system. +.Pp +Its arguments are: +.Bl -tag -width flags +.It Fa mp +The file system. +.It Fa flags +The lock type. +Could be +.Dv LK_EXCLUSIVE +or +.Dv LK_SHARED . +File system is free to ignore the +.Fa flags +argument and instead acquire an exclusive lock. +.It Fa vpp +Return parameter for the root vnode. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_ROOT.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_STATFS.9 =================================================================== --- user/imp/camdoc/VFS_STATFS.9 (nonexistent) +++ user/imp/camdoc/VFS_STATFS.9 (revision 296049) @@ -0,0 +1,116 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 23, 2009 +.Dt VFS_STATFS 9 +.Os +.Sh NAME +.Nm VFS_STATFS +.Nd return file system status +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_STATFS "struct mount *mp" "struct statfs *sbp" +.Sh DESCRIPTION +The +.Fn VFS_STATFS +macro returns various pieces of information about the file system, +including recommended I/O sizes, free space, free inodes, etc. +.Pp +The arguments it expects are: +.Bl -tag -width sbp +.It Fa mp +The file system. +.It Fa sbp +A +.Vt statfs +structure, as defined by +.In sys/mount.h , +into which information is placed about the file system. +.El +.Pp +The fields of +.Vt "struct statfs" +related to the file system are as follows: +.Bl -tag -width ".Va f_mntfromname" +.It Va f_type +Type of file system. +.It Va f_flags +A copy of mount exported flags. +.It Va f_bsize +Fragment size. +.It Va f_iosize +Optimal transfer block size. +.It Va f_blocks +The total number of data blocks in the file system. +.It Va f_bfree +The number of free blocks in the file system. +.It Va f_bavail +The number of free blocks available to non-superuser processes. +.It Va f_files +The total number of file nodes in the file system. +.It Va f_ffree +The number of free nodes available to non-superuser processes. +.It Va f_syncwrites +The number of synchronous writes since the file system was mounted. +.It Va f_asyncwrites +The number of asynchronous writes since the file system was mounted. +.It Va f_syncreads +The number of synchronous reads since the file system was mounted. +.It Va f_asyncreads +The number of asynchronous reads since the file system was mounted. +.It Va f_namemax +The maximum file name length for this file system. +.It Va f_owner +The user ID of the user that mounted the file system. +.It Va f_fsid +Unique file system ID. +.It Va f_fstypename +The file system type name; a string of at most +.Dv MFSNAMELEN +bytes. +.It Va f_mntfromname +The device name the file system was mounted from; a string of at most +.Dv MNAMELEN +bytes. +.It Va f_mntonname +The name of the directory on which the file system is mounted; +a string of at most +.Dv MNAMELEN +bytes. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_STATFS.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_SYNC.9 =================================================================== --- user/imp/camdoc/VFS_SYNC.9 (nonexistent) +++ user/imp/camdoc/VFS_SYNC.9 (revision 296049) @@ -0,0 +1,81 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 23, 2009 +.Dt VFS_SYNC 9 +.Os +.Sh NAME +.Nm VFS_SYNC +.Nd flush unwritten data +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_SYNC "struct mount *mp" "int waitfor" +.Sh DESCRIPTION +The +.Fn VFS_SYNC +macro writes out all unwritten data in the file system mounted as +.Fa mp . +.Pp +The arguments it expects are: +.Bl -tag -width ".Fa waitfor" +.It Fa mp +The file system. +.It Fa waitfor +Whether the function should wait for I/O to complete. +Possible values are: +.Bl -tag -width MNT_NOWAIT +.It Dv MNT_WAIT +synchronously wait for I/O to complete +.It Dv MNT_NOWAIT +start all I/O, but do not wait for it +.It Dv MNT_LAZY +push data not written by file system syncer +.El +.El +.Pp +The +.Fn VFS_SYNC +macro calls the +.Va vfs_sync +method of the file system, which normally calls +.Xr VOP_FSYNC 9 +for all the vnodes in the file system. +.Sh SEE ALSO +.Xr fsync 2 , +.Xr sync 2 , +.Xr VFS 9 , +.Xr vnode 9 , +.Xr VOP_FSYNC 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_SYNC.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VFS_UNMOUNT.9 =================================================================== --- user/imp/camdoc/VFS_UNMOUNT.9 (nonexistent) +++ user/imp/camdoc/VFS_UNMOUNT.9 (revision 296049) @@ -0,0 +1,68 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 23, 2009 +.Dt VFS_UNMOUNT 9 +.Os +.Sh NAME +.Nm VFS_UNMOUNT +.Nd unmount a file system +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.In sys/vnode.h +.Ft int +.Fn VFS_UNMOUNT "struct mount *mp" "int mntflags" +.Sh DESCRIPTION +The +.Fn VFS_UNMOUNT +macro unmounts a file system. +.Pp +The arguments it expects are: +.Bl -tag -width mntflags +.It Fa mp +The file system. +.It Fa mntflags +Bit-mask of flags for the unmount operation. +The flags currently supported by +.Fn VFS_UNMOUNT +are: +.Bl -tag -width ".Dv MNT_FORCE" +.It Dv MNT_FORCE +Open files are forcibly closed before the file system is unmounted. +.El +.El +.Sh SEE ALSO +.Xr vflush 9 , +.Xr VFS 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VFS_UNMOUNT.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_ACCESS.9 =================================================================== --- user/imp/camdoc/VOP_ACCESS.9 (nonexistent) +++ user/imp/camdoc/VOP_ACCESS.9 (revision 296049) @@ -0,0 +1,103 @@ +.\" -*- nroff -*- +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 18, 2009 +.Dt VOP_ACCESS 9 +.Os +.Sh NAME +.Nm VOP_ACCESS , +.Nm VOP_ACCESSX +.Nd "check access permissions of a file or Unix domain socket" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_ACCESS "struct vnode *vp" "accmode_t accmode" "struct ucred *cred" "struct thread *td" +.Ft int +.Fn VOP_ACCESSX "struct vnode *vp" "accmode_t accmode" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This entry point checks the access permissions of the file against the +given credentials. +.Pp +Its arguments are: +.Bl -tag -width accmode +.It Fa vp +The vnode of the file to check. +.It Fa accmode +The type of access required. +.It Fa cred +The user credentials to check. +.It Fa td +The thread which is checking. +.El +.Pp +The +.Fa accmode +is a mask which can contain flags described in , e.g. +.Dv VREAD , +.Dv VWRITE +or +.Dv VEXEC . +For +.Fn VOP_ACCESS , +the only flags that may be set in +.Fa accmode +are +.Dv VEXEC , +.Dv VWRITE , +.Dv VREAD , +.Dv VADMIN +and +.Dv VAPPEND . +To check for other flags, one has to use +.Fn VOP_ACCESSX +instead. +.Sh LOCKS +The vnode will be locked on entry and should remain locked on return. +.Sh RETURN VALUES +If the file is accessible in the specified way, then zero is returned, +otherwise an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +An attempt was made to change an immutable file. +.It Bq Er EACCES +The permission bits the file mode or the ACL do not permit the +requested access. +.El +.Sh SEE ALSO +.Xr vaccess 9 , +.Xr vaccess_acl_nfs4 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_ACCESS.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_ACLCHECK.9 =================================================================== --- user/imp/camdoc/VOP_ACLCHECK.9 (nonexistent) +++ user/imp/camdoc/VOP_ACLCHECK.9 (revision 296049) @@ -0,0 +1,102 @@ +.\"- +.\" Copyright (c) 1999 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 December 23, 1999 +.Dt VOP_ACLCHECK 9 +.Os +.Sh NAME +.Nm VOP_ACLCHECK +.Nd check an access control list for a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fn VOP_ACLCHECK "struct vnode *vp" "acl_type_t type" "struct acl *aclp" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +This vnode call may be used to determine the validity of a particular access +control list (ACL) for a particular file or directory. +.Pp +Its arguments are: +.Bl -tag -width type +.It Fa vp +The vnode of the file or directory. +.It Fa type +The type of ACL to check. +.It Fa aclp +A pointer to an ACL structure from which to retrieve the ACL data. +.It Fa cred +The user credentials to use in authorizing the request. +.It Fa td +The thread checking the ACL. +.El +.Pp +The +.Fa cred +pointer may be NULL to indicate that access control checks are not to be +performed, if possible. +This cred setting might be used to allow the +kernel to authorize ACL verification that the active process might not be +permitted to do. +.Pp +The vnode ACL interface defines the syntax, and not semantics, of file and +directory ACL interfaces. +More information about ACL management in kernel +may be found in +.Xr acl 9 . +.Sh LOCKS +No locks are required to call this vnode method, and any locks held on +entry will be held on exit. +.Sh RETURN VALUES +If the +.Fa aclp +pointer points to a valid ACL of type +.Fa type +for the object +.Fa vp , +then zero is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EINVAL +The ACL type passed is invalid for this vnode, or the ACL data is invalid. +.It Bq Er EACCES +The file or directory ACL does not permit access. +.It Bq Er ENOMEM +Sufficient memory is not available to fulfill the request. +.It Bq Er EOPNOTSUPP +The file system does not support +.Fn VOP_ACLCHECK . +.El +.Sh SEE ALSO +.Xr acl 9 , +.Xr vnode 9 , +.Xr VOP_GETACL 9 , +.Xr VOP_SETACL 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . Property changes on: user/imp/camdoc/VOP_ACLCHECK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_ADVLOCK.9 =================================================================== --- user/imp/camdoc/VOP_ADVLOCK.9 (nonexistent) +++ user/imp/camdoc/VOP_ADVLOCK.9 (revision 296049) @@ -0,0 +1,88 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 30, 1999 +.Dt VOP_ADVLOCK 9 +.Os +.Sh NAME +.Nm VOP_ADVLOCK +.Nd advisory record locking +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/fcntl.h +.In sys/lockf.h +.Ft int +.Fn VOP_ADVLOCK "struct vnode *vp" "caddr_t id" "int op" "struct flock *fl" "int flags" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width flags +.It Fa vp +The vnode being manipulated. +.It Fa id +The id token which is changing the lock. +.It Fa op +The operation to perform (see +.Xr fcntl 2 ) . +.It Fa fl +Description of the lock. +.It Fa flags +One of more of the following: +.Pp +.Bl -tag -width ".Dv F_UNLCK" -offset indent -compact +.It Dv F_RDLCK +Shared or read lock. +.It Dv F_UNLCK +Unlock. +.It Dv F_WRLCK +Exclusive or write lock. +.It Dv F_WAIT +Wait until lock is granted. +.It Dv F_FLOCK +Use +.Xr flock 2 +semantics for lock. +.It Dv F_POSIX +Use POSIX semantics for lock. +.El +.El +.Pp +This entry point manipulates advisory record locks on the file. +Most file systems delegate the work for this call to +.Fn lf_advlock . +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr fcntl 2 , +.Xr flock 2 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_ADVLOCK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_ATTRIB.9 =================================================================== --- user/imp/camdoc/VOP_ATTRIB.9 (nonexistent) +++ user/imp/camdoc/VOP_ATTRIB.9 (revision 296049) @@ -0,0 +1,102 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd August 29, 2008 +.Dt VOP_ATTRIB 9 +.Os +.Sh NAME +.Nm VOP_GETATTR , +.Nm VOP_SETATTR +.Nd get and set attributes on a file or directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_GETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" +.Ft int +.Fn VOP_SETATTR "struct vnode *vp" "struct vattr *vap" "struct ucred *cred" +.Sh DESCRIPTION +These entry points manipulate various attributes of a file or directory, +including file permissions, owner, group, size, +access time and modification time. +.Pp +The arguments are: +.Bl -tag -width cred +.It Fa vp +The vnode of the file. +.It Fa vap +The attributes of the file. +.It Fa cred +The user credentials of the calling process. +.El +.Pp +Attributes which are not being modified by +.Fn VOP_SETATTR +should be set to the value +.Dv VNOVAL ; +.Fn VATTR_NULL +may be used to clear all the values, and should generally be used to reset +the contents of +.Fa *vap +prior to setting specific values. +.Sh LOCKS +.Fn VOP_GETATTR +expects the vnode to be locked on entry and will leave the vnode locked on +return. +The lock type can be either shared or exclusive. +.Pp +.Fn VOP_SETATTR +expects the vnode to be locked on entry and will leave the vnode locked on +return. +The lock type must be exclusive. +.Sh RETURN VALUES +.Fn VOP_GETATTR +returns 0 if it was able to retrieve the attribute data via +.Fa *vap , +otherwise an appropriate error is returned. +.Fn VOP_SETATTR +returns zero if the attributes were changed successfully, otherwise an +appropriate error is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The file is immutable. +.It Bq Er EACCES +The caller does not have permission to modify the file or directory attributes. +.It Bq Er EROFS +The file system is read-only. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_ATTRIB.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_BWRITE.9 =================================================================== --- user/imp/camdoc/VOP_BWRITE.9 (nonexistent) +++ user/imp/camdoc/VOP_BWRITE.9 (revision 296049) @@ -0,0 +1,56 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_BWRITE 9 +.Os +.Sh NAME +.Nm VOP_BWRITE +.Nd write a file system buffer +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_BWRITE "struct vnode *vp" "struct buf *bp" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode of the file being written to. +.It Fa bp +The buffer to be written. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_BWRITE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_CREATE.9 =================================================================== --- user/imp/camdoc/VOP_CREATE.9 (nonexistent) +++ user/imp/camdoc/VOP_CREATE.9 (revision 296049) @@ -0,0 +1,100 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_CREATE 9 +.Os +.Sh NAME +.Nm VOP_CREATE , +.Nm VOP_MKNOD , +.Nm VOP_MKDIR , +.Nm VOP_SYMLINK +.Nd create a file, socket, fifo, device, directory or symlink +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/namei.h +.Ft int +.Fn VOP_CREATE "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_MKNOD "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_MKDIR "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" +.Ft int +.Fn VOP_SYMLINK "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" "struct vattr *vap" "char *target" +.Sh DESCRIPTION +These entry points create a new file, socket, fifo, device, directory or symlink +in a given directory. +.Pp +The arguments are: +.Bl -tag -width target +.It Fa dvp +The locked vnode of the directory. +.It Fa vpp +The address of a variable where the resulting locked vnode should be stored. +.It Fa cnp +The pathname component created. +.It Fa vap +The attributes that the new object should be created with. +.It Fa target +The pathname of the target of the symlink. +.El +.Pp +These entry points are called after +.Xr VOP_LOOKUP 9 +when an object is being created. +.Sh LOCKS +The directory, +.Fa dvp +will be locked on entry and must remain locked on return. +If the call is successful, the new object will be returned locked. +.Sh RETURN VALUES +If successful, the vnode for the new object is placed in +.Fa *vpp +and zero is returned. +Otherwise, an appropriate error is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EDQUOT +The user's file system space or inode quota would be exceeded. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh HISTORY +The function +.Nm +appeared in +.Bx 4.3 . +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_CREATE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_IOCTL.9 =================================================================== --- user/imp/camdoc/VOP_IOCTL.9 (nonexistent) +++ user/imp/camdoc/VOP_IOCTL.9 (revision 296049) @@ -0,0 +1,74 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_IOCTL 9 +.Os +.Sh NAME +.Nm VOP_IOCTL +.Nd device specific control +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_IOCTL "struct vnode *vp" "u_long command" "caddr_t data" "int fflag" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +Manipulate a file in device dependent ways. +.Pp +Its arguments are: +.Bl -tag -width command +.It Fa vp +The vnode of the file (normally representing a device). +.It Fa command +The device specific operation to perform. +.It Fa data +Extra data for the specified operation. +.It Fa fflag +Some flags ??? +.It Fa cred +The caller's credentials. +.It Fa td +The calling thread. +.El +.Pp +Most file systems do not implement this entry point. +.Sh LOCKS +The file should not be locked on entry. +.Sh RETURN VALUES +If successful, zero is returned, otherwise an appropriate error code. +.Pp +If the ioctl is not recognized or not handled, +.Er ENOTTY +should be returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_IOCTL.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_LINK.9 =================================================================== --- user/imp/camdoc/VOP_LINK.9 (nonexistent) +++ user/imp/camdoc/VOP_LINK.9 (revision 296049) @@ -0,0 +1,83 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_LINK 9 +.Os +.Sh NAME +.Nm VOP_LINK +.Nd create a new name for a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_LINK "struct vnode *dvp" "struct vnode *vp" "struct componentname *cnp" +.Sh DESCRIPTION +This links a new name in the specified directory to an existing file. +.Pp +Its arguments are: +.Bl -tag -width 8n +.It Fa dvp +The vnode of the directory. +.It Fa vp +The vnode of the file to be linked. +.It Fa cnp +Pathname information about the file. +.El +.Pp +The pathname info should +.Em not +be released on exit because it is done +by the caller. +The directory and file vnodes should +.Em not +be released on exit. +.Sh LOCKS +.Fn VOP_LINK +expects the directory and file vnodes to be locked on entry and will leave +the vnodes locked on return. +.Sh RETURN VALUES +Zero is returned if the file was linked successfully, otherwise an +error is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EMLINK +The file has too many links. +.It Bq Er EPERM +The file is immutable. +.It Bq Er EXDEV +A hard link is not possible between different file systems. +.El +.Sh SEE ALSO +.Xr vn_lock 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was originally written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_LINK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_LOOKUP.9 =================================================================== --- user/imp/camdoc/VOP_LOOKUP.9 (nonexistent) +++ user/imp/camdoc/VOP_LOOKUP.9 (revision 296049) @@ -0,0 +1,195 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 24, 1997 +.Dt VOP_LOOKUP 9 +.Os +.Sh NAME +.Nm VOP_LOOKUP +.Nd lookup a component of a pathname +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/namei.h +.Ft int +.Fn VOP_LOOKUP "struct vnode *dvp" "struct vnode **vpp" "struct componentname *cnp" +.Sh DESCRIPTION +This entry point looks up a single pathname component in a given directory. +.Pp +Its arguments are: +.Bl -tag -width vpp +.It Fa dvp +The locked vnode of the directory to search. +.It Fa vpp +The address of a variable where the resulting locked vnode should be stored. +.It Fa cnp +The pathname component to be searched for. +.El +.Pp +.Fa Cnp +is a pointer to a componentname structure defined as follows: +.Bd -literal +struct componentname { + /* + * Arguments to lookup. + */ + u_long cn_nameiop; /* namei operation */ + u_long cn_flags; /* flags to namei */ + struct thread *cn_thread; /* thread requesting lookup */ + struct ucred *cn_cred; /* credentials */ + /* + * Shared between lookup and commit routines. + */ + char *cn_pnbuf; /* pathname buffer */ + char *cn_nameptr; /* pointer to looked up name */ + long cn_namelen; /* length of looked up component */ + u_long cn_hash; /* hash value of looked up name */ + long cn_consume; /* chars to consume in lookup() */ +}; +.Ed +.Pp +Convert a component of a pathname into a pointer to a locked vnode. +This is a very central and rather complicated routine. +If the file system is not maintained in a strict tree hierarchy, +this can result in a deadlock situation. +.Pp +The +.Fa cnp->cn_nameiop +argument is +.Dv LOOKUP , +.Dv CREATE , +.Dv RENAME , +or +.Dv DELETE +depending on the intended use of the object. +When +.Dv CREATE , +.Dv RENAME , +or +.Dv DELETE +is specified, information usable in +creating, renaming, or deleting a directory entry may be calculated. +.Pp +Overall outline of VOP_LOOKUP: +.Bd -ragged -offset indent +Check accessibility of directory. +Look for name in cache, if found, then return name. +Search for name in directory, goto to found or notfound as appropriate. +.Ed +.Pp +notfound: +.Bd -ragged -offset indent +If creating or renaming and at end of pathname, +return +.Er EJUSTRETURN , +leaving info on available slots else return +.Er ENOENT . +.Ed +.Pp +found: +.Bd -ragged -offset indent +If at end of path and deleting, return information to allow delete. +If at end of path and renaming, lock target +inode and return info to allow rename. +If not at end, add name to cache; if at end and neither creating +nor deleting, add name to cache. +.Ed +.Sh LOCKS +The directory, +.Fa dvp +should be locked on entry. +If an error (note: the return value +.Er EJUSTRETURN +is not considered an error) +is detected, it will be returned locked. +Otherwise, it will be unlocked unless both +.Dv LOCKPARENT +and +.Dv ISLASTCN +are specified in +.Fa cnp->cn_flags . +If an entry is found in the directory, it will be returned locked. +.Sh RETURN VALUES +Zero is returned with +.Fa *vpp +set to the locked vnode of the file if the component is found. +If the component being searched for is ".", then the vnode just has +an extra reference added to it with +.Xr vref 9 . +The caller must take care to release the locks appropriately in this +case. +.Pp +If the component is not found and the operation is +.Dv CREATE +or +.Dv RENAME , +the flag +.Dv ISLASTCN +is specified and the operation would succeed, the special return value +.Er EJUSTRETURN +is returned. +Otherwise, an appropriate error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ENOTDIR +The vnode +.Fa dvp +does not represent a directory. +.It Bq Er ENOENT +The component +.Fa dvp +was not found in this directory. +.It Bq Er EACCES +Access for the specified operation is denied. +.It Bq Er EJUSTRETURN +A +.Dv CREATE +or +.Dv RENAME +operation would be successful. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_ACCESS 9 , +.Xr VOP_CREATE 9 , +.Xr VOP_MKDIR 9 , +.Xr VOP_MKNOD 9 , +.Xr VOP_RENAME 9 , +.Xr VOP_SYMLINK 9 +.Sh HISTORY +The function +.Nm +appeared in +.Bx 4.3 . +.Sh AUTHORS +This manual page was written by +.An Doug Rabson , +with some text from comments in +.Pa ufs_lookup.c . Property changes on: user/imp/camdoc/VOP_LOOKUP.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_OPENCLOSE.9 =================================================================== --- user/imp/camdoc/VOP_OPENCLOSE.9 (nonexistent) +++ user/imp/camdoc/VOP_OPENCLOSE.9 (revision 296049) @@ -0,0 +1,104 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 2, 2009 +.Dt VOP_OPEN 9 +.Os +.Sh NAME +.Nm VOP_OPEN , +.Nm VOP_CLOSE +.Nd open or close a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_OPEN "struct vnode *vp" "int mode" "struct ucred *cred" "struct thread *td" "struct file *fp" +.Ft int +.Fn VOP_CLOSE "struct vnode *vp" "int mode" "struct ucred *cred" "struct thread *td" +.Sh DESCRIPTION +The +.Fn VOP_OPEN +entry point is called before a file is accessed by a process and the +.Fn VOP_CLOSE +entry point is called after a file is finished with by the process. +.Pp +The arguments are: +.Bl -tag -width mode +.It Fa vp +The vnode of the file. +.It Fa mode +The access mode required by the calling process. +.It Fa cred +The caller's credentials. +.It Fa td +The thread which is accessing the file. +.It Fa fp +The file being opened. +.El +.Pp +Pointer to the file +.Fa fp +is useful for file systems which require such information, e.g., +.Xr fdescfs 5 . +Use +.Ql NULL +as +.Fa fp +argument to +.Fn VOP_OPEN +for in-kernel opens. +.Pp +The access mode is a set of flags, including +.Dv FREAD , +.Dv FWRITE , +.Dv O_NONBLOCK , +.Dv O_APPEND . +.Sh LOCKS +.Fn VOP_OPEN +expects +.Fa vp +to be locked on entry and will leave it locked on return. +.Pp +.Fn VOP_CLOSE +expects at least a reference to be associated with the vnode and does not +care whether the vnode is locked or not. +The lock and reference state is left unchanged on return. +Note that +.Fa vn_close +expects an unlocked, referenced vnode and will dereference the vnode prior +to returning. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_OPENCLOSE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_PATHCONF.9 =================================================================== --- user/imp/camdoc/VOP_PATHCONF.9 (nonexistent) +++ user/imp/camdoc/VOP_PATHCONF.9 (revision 296049) @@ -0,0 +1,88 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_PATHCONF 9 +.Os +.Sh NAME +.Nm VOP_PATHCONF +.Nd return POSIX pathconf information +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/unistd.h +.Ft int +.Fn VOP_PATHCONF "struct vnode *vp" "int name" "int *retval" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width retval +.It Fa vp +The vnode to get information about. +.It Fa name +The type of information to return. +.It Fa retval +The place to return the information. +.El +.Pp +The value of +.Fa name +specifies what should be returned: +.Bl -tag -width _PC_CHOWN_RESTRICTED +.It Dv _PC_LINK_MAX +The maximum number of links to a file. +.It Dv _PC_NAME_MAX +The maximum number of bytes in a file name. +.It Dv _PC_PATH_MAX +The maximum number of bytes in a pathname. +.It Dv _PC_PIPE_BUF +The maximum number of bytes which will be written atomically to a pipe. +.It Dv _PC_CHOWN_RESTRICTED +Return 1 if appropriate privileges are required for the +.Xr chown 2 +system call, otherwise 0. +.It Dv _PC_NO_TRUNC +Return 1 if file names longer than +.Dv KERN_NAME_MAX +are truncated. +.El +.Sh RETURN VALUES +If +.Fa name +is recognized, +.Fa *retval +is set to the specified value and zero is returned, otherwise +.Er EINVAL +is returned. +.Sh SEE ALSO +.Xr pathconf 2 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_PATHCONF.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_PRINT.9 =================================================================== --- user/imp/camdoc/VOP_PRINT.9 (nonexistent) +++ user/imp/camdoc/VOP_PRINT.9 (revision 296049) @@ -0,0 +1,54 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_PRINT 9 +.Os +.Sh NAME +.Nm VOP_PRINT +.Nd print debugging information +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_PRINT "struct vnode *vp" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width 2n +.It Fa vp +The vnode to print. +.El +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_PRINT.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_RDWR.9 =================================================================== --- user/imp/camdoc/VOP_RDWR.9 (nonexistent) +++ user/imp/camdoc/VOP_RDWR.9 (revision 296049) @@ -0,0 +1,104 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_RDWR 9 +.Os +.Sh NAME +.Nm VOP_READ , +.Nm VOP_WRITE +.Nd read or write a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/uio.h +.Ft int +.Fn VOP_READ "struct vnode *vp" "struct uio *uio" "int ioflag" "struct ucred *cred" +.Ft int +.Fn VOP_WRITE "struct vnode *vp" "struct uio *uio" "int ioflag" "struct ucred *cred" +.Sh DESCRIPTION +These entry points read or write the contents of a file +.Pp +The arguments are: +.Bl -tag -width ioflag +.It Fa vp +The vnode of the file. +.It Fa uio +The location of the data to be read or written. +.It Fa ioflag +Various flags. +.It Fa cnp +The credentials of the caller. +.El +.Pp +The +.Fa ioflag +argument is used to give directives and hints to the file system. +When attempting a read, the high 16 bits are used to provide a +read-ahead hint (in units of file system blocks) that the file system +should attempt. +The low 16 bits are a bit mask which can contain +the following flags: +.Bl -tag -width ".Dv IO_NODELOCKED" +.It Dv IO_UNIT +Do I/O as atomic unit. +.It Dv IO_APPEND +Append write to end. +.It Dv IO_SYNC +Do I/O synchronously. +.It Dv IO_NODELOCKED +Underlying node already locked. +.It Dv IO_NDELAY +.Dv FNDELAY +flag set in file table. +.It Dv IO_VMIO +Data already in VMIO space. +.El +.Sh LOCKS +The file should be locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EFBIG +An attempt was made to write a file that exceeds the process's file size +limit or the maximum file size. +.It Bq Er ENOSPC +The file system is full. +.It Bq Er EPERM +An append-only flag is set on the file, but the caller is attempting to +write before the current end of file. +.El +.Sh SEE ALSO +.Xr uiomove 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_RDWR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_READLINK.9 =================================================================== --- user/imp/camdoc/VOP_READLINK.9 (nonexistent) +++ user/imp/camdoc/VOP_READLINK.9 (revision 296049) @@ -0,0 +1,67 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_READLINK 9 +.Os +.Sh NAME +.Nm VOP_READLINK +.Nd read the target of a symbolic link +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/uio.h +.Ft int +.Fn VOP_READLINK "struct vnode *vp" "struct uio *uio" "struct ucred *cred" +.Sh DESCRIPTION +This reads the target pathname of a symbolic link +.Bl -tag -width uio +.It Fa vp +The vnode of the symlink. +.It Fa uio +The location of the data to be read or written. +.It Fa cred +The credentials of the caller. +.El +.Sh LOCKS +The vnode should be locked on entry and will still be locked on exit. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EIO +A read error occurred while reading the contents of the symlink. +.El +.Sh SEE ALSO +.Xr uiomove 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_READLINK.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_REALLOCBLKS.9 =================================================================== --- user/imp/camdoc/VOP_REALLOCBLKS.9 (nonexistent) +++ user/imp/camdoc/VOP_REALLOCBLKS.9 (revision 296049) @@ -0,0 +1,59 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_REALLOCBLKS 9 +.Os +.Sh NAME +.Nm VOP_REALLOCBLKS +.Nd rearrange blocks in a file to be contiguous +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_REALLOCBLKS "struct vnode *vp" "struct cluster_save *buflist" +.Sh DESCRIPTION +The arguments are: +.Bl -tag -width buflist +.It Fa vp +The file to manipulate. +.It Fa buflist +A list of buffers to rearrange. +.El +.Pp +This seems to be part of a work in progress. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr buf 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_REALLOCBLKS.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_REMOVE.9 =================================================================== --- user/imp/camdoc/VOP_REMOVE.9 (nonexistent) +++ user/imp/camdoc/VOP_REMOVE.9 (revision 296049) @@ -0,0 +1,77 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_REMOVE 9 +.Os +.Sh NAME +.Nm VOP_REMOVE , +.Nm VOP_RMDIR +.Nd remove a file or directory +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_REMOVE "struct vnode *dvp" "struct vnode *vp" "struct componentname *cnp" +.Ft int +.Fn VOP_RMDIR "struct vnode *dvp" "struct vnode *vp" "struct componentname *cnp" +.Sh DESCRIPTION +These entry points remove files and directories respectively. +.Pp +The arguments are: +.Bl -tag -width dvp +.It Fa dvp +The vnode of the directory. +.It Fa vp +The vnode of the file to be removed. +.It Fa cnp +Pathname information about the file. +.El +.Sh LOCKS +Both +.Fa dvp +and +.Fa vp +should be locked on entry and remain locked on return. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error code is returned. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The file is immutable. +.It Bq Er ENOTEMPTY +An attempt was made to remove a directory which is not empty. +.El +.Sh SEE ALSO +.Xr vnode 9 , +.Xr VOP_LOOKUP 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_REMOVE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_RENAME.9 =================================================================== --- user/imp/camdoc/VOP_RENAME.9 (nonexistent) +++ user/imp/camdoc/VOP_RENAME.9 (revision 296049) @@ -0,0 +1,96 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VOP_RENAME 9 +.Os +.Sh NAME +.Nm VOP_RENAME +.Nd rename a file +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_RENAME "struct vnode *fdvp" "struct vnode *fvp" "struct componentname *fcnp" "struct vnode *tdvp" "struct vnode *tvp" "struct componentname *tcnp" +.Sh DESCRIPTION +This renames a file and possibly changes its parent directory. +If the destination object exists, it will be removed first. +.Pp +Its arguments are: +.Bl -tag -width fdvp +.It Fa fdvp +The vnode of the old parent directory. +.It Fa fvp +The vnode of the file to be renamed. +.It Fa fcnp +Pathname information about the file's current name. +.It Fa tdvp +The vnode of the new parent directory. +.It Fa tvp +The vnode of the target file (if it exists). +.It Fa tcnp +Pathname information about the file's new name. +.El +.Sh LOCKS +The source directory and file are unlocked but are expected to have their +ref count bumped on entry. +The VOP routine is expected to +.Xr vrele 9 +both prior +to returning. +.Pp +The destination directory and file are locked as well as having their ref +count bumped. +The VOP routine is expected to +.Xr vput 9 +both prior to +returning. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EPERM +The file is immutable. +.It Bq Er EXDEV +It is not possible to rename a file between different file systems. +.It Bq Er EINVAL +An attempt was made to rename +.Pa \&. +or +.Pa .. , +or to perform an operation which would break the directory tree structure. +.It Bq Er ENOTDIR +An attempt was made to rename a directory to a file or vice versa. +.It Bq Er ENOTEMPTY +An attempt was made to remove a directory which is not empty. +.El +.Sh SEE ALSO +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_RENAME.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_REVOKE.9 =================================================================== --- user/imp/camdoc/VOP_REVOKE.9 (nonexistent) +++ user/imp/camdoc/VOP_REVOKE.9 (revision 296049) @@ -0,0 +1,70 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2002 Networks Associates Technology, Inc. +.\" All rights reserved. +.\" +.\" This software was developed for the FreeBSD Project by NAI Labs, the +.\" Security Research Division of Network Associates, Inc. under +.\" DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the DARPA +.\" CHATS research program. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The names of the authors 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 February 5, 2002 +.Dt VOP_REVOKE 9 +.Os +.Sh NAME +.Nm VOP_REVOKE +.Nd "revoke access to a device and its aliases" +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_REVOKE "struct vnode *vp" "int flags" +.Sh DESCRIPTION +.Fn VOP_REVOKE +will administratively revoke access to the device specified by +.Fa vp , +as well as any aliases created via +.Xr make_dev_alias 9 . +Further file operations on any of these devices by processes +which have them open will nominally fail. +The +.Fa flags +must be set to +.Dv REVOKEALL +to signify that all access will be revoked; any other value is invalid. +.Sh LOCKS +The +.Fa vp +must be unlocked on entry, and will remain unlocked upon return. +.Sh SEE ALSO +.Xr make_dev_alias 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Brian Fundakowski Feldman . Property changes on: user/imp/camdoc/VOP_REVOKE.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/VOP_VPTOFH.9 =================================================================== --- user/imp/camdoc/VOP_VPTOFH.9 (nonexistent) +++ user/imp/camdoc/VOP_VPTOFH.9 (revision 296049) @@ -0,0 +1,60 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 16, 2007 +.Dt VOP_VPTOFH 9 +.Os +.Sh NAME +.Nm VOP_VPTOFH +.Nd turn a vnode into an NFS filehandle +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn VOP_VPTOFH "struct vnode *vp" "struct fid *fhp" +.Sh DESCRIPTION +This is used by the NFS server to create an opaque filehandle which +uniquely identifies the file and which can be used by an NFS client +to access the file in the future. +.Pp +Its arguments are: +.Bl -tag -width fhp +.It Fa vp +The vnode to make a filehandle for. +.It Fa fhp +Return parameter for the filehandle. +.El +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_FHTOVP 9 , +.Xr vnode 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/VOP_VPTOFH.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/accept_filter.9 =================================================================== --- user/imp/camdoc/accept_filter.9 (nonexistent) +++ user/imp/camdoc/accept_filter.9 (revision 296049) @@ -0,0 +1,152 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" " +.Dd June 25, 2000 +.Dt ACCEPT_FILTER 9 +.Os +.Sh NAME +.Nm accept_filter , +.Nm accept_filt_add , +.Nm accept_filt_del , +.Nm accept_filt_generic_mod_event , +.Nm accept_filt_get +.Nd filter incoming connections +.Sh SYNOPSIS +.In sys/types.h +.In sys/module.h +.In sys/socket.h +.Fd #define ACCEPT_FILTER_MOD +.In sys/socketvar.h +.Ft int +.Fn accept_filt_add "struct accept_filter *filt" +.Ft int +.Fn accept_filt_del "char *name" +.Ft int +.Fn accept_filt_generic_mod_event "module_t mod" "int event" "void *data" +.Ft struct accept_filter * +.Fn accept_filt_get "char *name" +.Sh DESCRIPTION +Accept filters allow an application to request +that the kernel pre-process incoming connections. +An accept filter is requested via the +.Xr setsockopt 2 +system call, passing in an +.Fa optname +of +.Dv SO_ACCEPTFILTER . +.Sh IMPLEMENTATION NOTES +A module that wants to be an accept filter +must provide a +.Vt "struct accept_filter" +to the system: +.Bd -literal +struct accept_filter { + char accf_name[16]; + void (*accf_callback)(struct socket *so, void *arg, int waitflag); + void * (*accf_create)(struct socket *so, char *arg); + void (*accf_destroy)(struct socket *so); + SLIST_ENTRY(accept_filter) accf_next; /* next on the list */ +}; +.Ed +.Pp +The module should register it with the function +.Fn accept_filt_add , +passing a pointer to a +.Vt "struct accept_filter" , +allocated with +.Xr malloc 9 . +.Pp +The fields of +.Vt "struct accept_filter" +are as follows: +.Bl -tag -width ".Va accf_callback" +.It Va accf_name +Name of the filter; +this is how it will be accessed from userland. +.It Va accf_callback +The callback that the kernel will do +once the connection is established. +It is the same as a socket upcall +and will be called when the connection is established +and whenever new data arrives on the socket, +unless the callback modifies the socket's flags. +.It Va accf_create +Called whenever a +.Xr setsockopt 2 +installs the filter onto +a listening socket. +.It Va accf_destroy +Called whenever the user removes the accept filter on the socket. +.El +.Pp +The +.Fn accept_filt_del +function +passed the same string used in +.Va accept_filter.accf_name +during registration with +.Fn accept_filt_add , +the kernel will then disallow and further userland use of the filter. +.Pp +The +.Fn accept_filt_get +function is used internally to locate which accept filter to use via the +.Xr setsockopt 2 +system call. +.Pp +The +.Fn accept_filt_generic_mod_event +function provides a simple way to avoid duplication of code +for accept filters which do not use the argument field to load +and unload themselves. +This function can be used in the +.Vt moduledata_t +struct for the +.Xr DECLARE_MODULE 9 +macro. +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accf_data 9 , +.Xr accf_dns 9 , +.Xr accf_http 9 , +.Xr malloc 9 +.Sh HISTORY +The accept filter mechanism was introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page was written by +.An -nosplit +.An Alfred Perlstein , +.An Sheldon Hearn +and +.An Jeroen Ruigrok van der Werven. +.Pp +The accept filter concept was pioneered by +.An David Filo +at Yahoo!\& +and refined to be a loadable module system by +.An Alfred Perlstein . Property changes on: user/imp/camdoc/accept_filter.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/accf_http.9 =================================================================== --- user/imp/camdoc/accf_http.9 (nonexistent) +++ user/imp/camdoc/accf_http.9 (revision 296049) @@ -0,0 +1,98 @@ +.\" +.\" Copyright (c) 2000 Alfred Perlstein +.\" +.\" 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 November 15, 2000 +.Dt ACCF_HTTP 9 +.Os +.Sh NAME +.Nm accf_http +.Nd "buffer incoming connections until a certain complete HTTP requests arrive" +.Sh SYNOPSIS +.Nm options INET +.Nm options ACCEPT_FILTER_HTTP +.Nm kldload accf_http +.Sh DESCRIPTION +This is a filter to be placed on a socket that will be using +.Fn accept +to receive incoming HTTP connections. +.Pp +It prevents the application from receiving the connected descriptor via +.Fn accept +until either a full HTTP/1.0 or HTTP/1.1 HEAD or GET request has +been buffered by the kernel. +.Pp +If something other than a HTTP/1.0 or +HTTP/1.1 HEAD or GET request is received the kernel will +allow the application to receive the connection descriptor +via +.Fn accept . +.Pp +The utility of +.Nm +is such that a server will not have to context switch several times +before performing the initial parsing of the request. +This effectively reduces the amount of required CPU utilization +to handle incoming requests by keeping active +processes in preforking servers such as Apache low +and reducing the size of the file descriptor set that needs +to be managed by interfaces such as +.Fn select , +.Fn poll +or +.Fn kevent +based servers. +.Pp +The +.Nm +kernel option is also a module that can be enabled at runtime via +.Xr kldload 8 +if the INET option has been compiled into the kernel. +.Sh EXAMPLES +Assuming ACCEPT_FILTER_HTTP has been included in the kernel config +file or the +.Nm +module +has been loaded, this will enable the http accept filter +on the socket +.Fa sok . +.Bd -literal -offset 0i + struct accept_filter_arg afa; + + bzero(&afa, sizeof(afa)); + strcpy(afa.af_name, "httpready"); + setsockopt(sok, SOL_SOCKET, SO_ACCEPTFILTER, &afa, sizeof(afa)); +.Ed +.Sh SEE ALSO +.Xr setsockopt 2 , +.Xr accept_filter 9 +.Sh HISTORY +The accept filter mechanism and the +accf_http filter were introduced in +.Fx 4.0 . +.Sh AUTHORS +This manual page and the filter were written by +.An Alfred Perlstein . Property changes on: user/imp/camdoc/accf_http.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/cr_cansee.9 =================================================================== --- user/imp/camdoc/cr_cansee.9 (nonexistent) +++ user/imp/camdoc/cr_cansee.9 (revision 296049) @@ -0,0 +1,92 @@ +.\" +.\" Copyright (c) 2006 Ceri Davies +.\" +.\" 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 November 19, 2006 +.Dt CR_CANSEE 9 +.Os +.Sh NAME +.Nm cr_cansee +.Nd "determine visibility of objects given their user credentials" +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/ucred.h +.Ft int +.Fn cr_cansee "struct ucred *u1" "struct ucred *u2" +.Sh DESCRIPTION +This function determines the visibility of objects in the +kernel based on the real user IDs and group IDs in the credentials +.Fa u1 +and +.Fa u2 +associated with them. +.Pp +The visibility of objects is influenced by the +.Xr sysctl 8 +variables +.Va security.bsd.see_other_gids +and +.Va security.bsd.see_other_uids , +as per the description in +.Xr cr_seeothergids 9 +and +.Xr cr_seeotheruids 9 +respectively. +.Sh RETURN VALUES +This function returns zero if the object with credential +.Fa u1 +can +.Dq see +the object with credential +.Fa u2 , +or +.Er ESRCH +otherwise. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er ESRCH +The object with credential +.Fa u1 +cannot +.Dq see +the object with credential +.Fa u2 . +.It Bq Er ESRCH +The object with credential +.Fa u1 +has been jailed and the object with credential +.Fa u2 +does not belong to the same jail as +.Fa u1 . +.It Bq Er ESRCH +The MAC subsystem denied visibility. +.El +.Sh SEE ALSO +.Xr cr_seeothergids 9 , +.Xr cr_seeotheruids 9 , +.Xr mac 9 , +.Xr p_cansee 9 Property changes on: user/imp/camdoc/cr_cansee.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/extattr.9 =================================================================== --- user/imp/camdoc/extattr.9 (nonexistent) +++ user/imp/camdoc/extattr.9 (revision 296049) @@ -0,0 +1,96 @@ +.\"- +.\" Copyright (c) 1999, 2000, 2001, 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, 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 23, 1999 +.Dt EXTATTR 9 +.Os +.Sh NAME +.Nm extattr +.Nd virtual file system named extended attributes +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/extattr.h +.Sh DESCRIPTION +Named extended attributes allow additional meta-data to be associated +with vnodes representing files and directories. +The semantics of this additional data is that of a "name=value" pair, where +a name may be defined or undefined, and if defined, associated with zero or +more bytes of arbitrary binary data. +Extended attribute names exist within a set of namespaces; each operation +on an extended attribute is required to provide the namespace to which to +operation refers. +If the same name is present in multiple namespaces, the extended attributes +associated with the names are stored and manipulated independently. +The following two namespaces are defined universally, although individual +file systems may implement additional namespaces, or not implement +these namespaces: +.Dv EXTATTR_NAMESPACE_USER , +.Dv EXTATTR_NAMESPACE_SYSTEM . +The semantics of these attributes are intended to be as follows: user +attribute data is protected according the normal discretionary +and mandatory protections associated with the data in the file or +directory; system attribute data is protected such that appropriate +privilege is required to directly access or manipulate these attributes. +.Pp +Reads of extended attribute data may return specific contiguous regions of +the meta-data, in the style of +.Xr VOP_READ 9 , +but writes will replace the entire current "value" associated with +a given name. +As there are a plethora of file systems with differing extended attributes, +availability and functionality of these functions may be limited, and they +should be used with awareness of the underlying semantics of the supporting +file system. +Authorization schemes for extended attribute data may also vary by file +system, as well as maximum attribute size, and whether or not any or +specific new attributes may be defined. +.Pp +Extended attributes are named using a null-terminated character string. +Depending on underlying file system semantics, this name may or may not be +case-sensitive. +Appropriate vnode extended attribute calls are: +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_LISTEXTATTR 9 , +and +.Xr VOP_SETEXTATTR 9 . +.Sh SEE ALSO +.Xr VFS 9 , +.Xr VFS_EXTATTRCTL 9 , +.Xr VOP_GETEXTATTR 9 , +.Xr VOP_LISTEXTATTR 9 , +.Xr VOP_SETEXTATTR 9 +.Sh AUTHORS +This manual page was written by +.An Robert Watson . +.Sh BUGS +In addition, the interface does not provide a mechanism to retrieve +the current set of available attributes; it has been suggested that +providing a +.Dv NULL +attribute name should cause a list of defined attributes for the passed file +or directory, but this is not currently implemented. Property changes on: user/imp/camdoc/extattr.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/hexdump.9 =================================================================== --- user/imp/camdoc/hexdump.9 (nonexistent) +++ user/imp/camdoc/hexdump.9 (revision 296049) @@ -0,0 +1,94 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 Scott Long +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd December 7, 2003 +.Dt HEXDUMP 9 +.Os +.Sh NAME +.Nm hexdump +.Nd "dump a block of bytes to the console in hexadecimal form" +.Sh SYNOPSIS +.In sys/systm.h +.Ft void +.Fn hexdump "void *ptr" "int length" "const char *hdr" "int flags" +.Sh DESCRIPTION +The +.Fn hexdump +function prints an array of bytes to the console in hexadecimal form, along with +the +.Tn ASCII +representation of the bytes, if possible. +By default, each line of +output will start with an offset count, followed by 16 hexadecimal values, +followed by 16 +.Tn ASCII +characters. +.Bl -tag -width indent +.It Fa ptr +Pointer to the array of bytes to print. +It does not need to be +.Dv NUL Ns +-terminated. +.It Fa length +Number of bytes to print. +.It Fa hdr +Pointer to a +.Dv NUL Ns +-terminated character string that will be prepended to each +line of output. +A value of +.Dv NULL +implies that no header will be printed. +.It Fa flags +Flags for controlling the formatting of the output. +.Bl -tag -width ".Dv HD_OMIT_COUNT" +.It Bits 0-7 +Integer value of the number of bytes to display on each line. +A value of 0 implies that the default value of 16 will be used. +.It Bits 8-15 +Character +.Tn ASCII +value to use as the separator for the hexadecimal output. +A value of 0 implies that the default value of 32 +.Tn ( ASCII +space) will be used. +.It Dv HD_OMIT_COUNT +Do not print the offset column at the beginning of each line. +.It Dv HD_OMIT_HEX +Do not print the hexadecimal values on each line. +.It Dv HD_OMIT_CHARS +Do not print the character values on each line. +.El +.El +.Sh SEE ALSO +.Xr ascii 7 +.Sh AUTHORS +This manual page was written by +.An Scott Long . Property changes on: user/imp/camdoc/hexdump.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vaccess.9 =================================================================== --- user/imp/camdoc/vaccess.9 (nonexistent) +++ user/imp/camdoc/vaccess.9 (revision 296049) @@ -0,0 +1,128 @@ +.\"- +.\" Copyright (c) 2001 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 September 18, 2009 +.Dt VACCESS 9 +.Os +.Sh NAME +.Nm vaccess +.Nd generate an access control decision using vnode parameters +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fo vaccess +.Fa "enum vtype type" +.Fa "mode_t file_mode" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "accmode_t accmode" +.Fa "struct ucred *cred" +.Fa "int *privused" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +common to many file systems in +.Fx . +It accepts the vnodes type +.Fa type , +permissions via +.Fa file_mode , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +desired access mode +.Fa accmode , +requesting credential +.Fa cred , +and an optional call-by-reference +.Vt int +pointer returning whether or not +privilege was required for successful evaluation of the call; the +.Fa privused +pointer may be set to +.Dv NULL +by the caller in order not to be informed of +privilege information, or it may point to an integer that will be set to +1 if privilege is used, and 0 otherwise. +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn vaccess +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn vaccess +selects a component of the file permission bits based on comparing the +passed credential, file owner, and file group. +If the credential's effective UID matches the file owner, then the +owner component of the permission bits is selected. +If the UID does not match, then the credential's effective GID, followed +by additional groups, are compared with the file group\[em]if there is +a match, then the group component of the permission bits is selected. +If neither the credential UID or GIDs match the passed file owner and +group, then the other component of the permission bits is selected. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn vaccess +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr vaccess_acl_nfs4 9 , +.Xr vaccess_acl_posix1e 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page and the current implementation of +.Fn vaccess +were written by +.An Robert Watson . Property changes on: user/imp/camdoc/vaccess.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vaccess_acl_posix1e.9 =================================================================== --- user/imp/camdoc/vaccess_acl_posix1e.9 (nonexistent) +++ user/imp/camdoc/vaccess_acl_posix1e.9 (revision 296049) @@ -0,0 +1,128 @@ +.\"- +.\" Copyright (c) 2001 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 August 22, 2001 +.Dt VACCESS_ACL_POSIX1E 9 +.Os +.Sh NAME +.Nm vaccess_acl_posix1e +.Nd generate a POSIX.1e ACL access control decision using vnode parameters +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.In sys/acl.h +.Ft int +.Fo vaccess_acl_posix1e +.Fa "enum vtype type" +.Fa "uid_t file_uid" +.Fa "gid_t file_gid" +.Fa "struct acl *acl" +.Fa "accmode_t accmode" +.Fa "struct ucred *cred" +.Fa "int *privused" +.Fc +.Sh DESCRIPTION +This call implements the logic for the +.Ux +discretionary file security model +with POSIX.1e ACL extensions. +It accepts the vnodes type +.Fa type , +owning UID +.Fa file_uid , +owning GID +.Fa file_gid , +access ACL for the file +.Fa acl , +desired access mode +.Fa accmode , +requesting credential +.Fa cred , +and an optional call-by-reference +.Vt int +pointer returning whether or not +privilege was required for successful evaluation of the call; the +.Fa privused +pointer may be set to +.Dv NULL +by the caller in order not to be informed of +privilege information, or it may point to an integer that will be set to +1 if privilege is used, and 0 otherwise. +.Pp +This call is intended to support implementations of +.Xr VOP_ACCESS 9 , +which will use their own access methods to retrieve the vnode properties, +and then invoke +.Fn vaccess_acl_posix1e +in order to perform the actual check. +Implementations of +.Xr VOP_ACCESS 9 +may choose to implement additional security mechanisms whose results will +be composed with the return value. +.Pp +The algorithm used by +.Fn vaccess_acl_posix1e +is based on the POSIX.1e ACL evaluation algorithm. +The algorithm selects a +.Em matching +entry from the access ACL, which may +then be composed with an available ACL mask entry, providing +.Ux +security compatibility. +.Pp +Once appropriate protections are selected for the current credential, +the requested access mode, in combination with the vnode type, will be +compared with the discretionary rights available for the credential. +If the rights granted by discretionary protections are insufficient, +then super-user privilege, if available for the credential, will also be +considered. +.Sh RETURN VALUES +.Fn vaccess_acl_posix1e +will return 0 on success, or a non-zero error value on failure. +.Sh ERRORS +.Bl -tag -width Er +.It Bq Er EACCES +Permission denied. +An attempt was made to access a file in a way forbidden by its file access +permissions. +.It Bq Er EPERM +Operation not permitted. +An attempt was made to perform an operation limited to processes with +appropriate privileges or to the owner of a file or other resource. +.El +.Sh SEE ALSO +.Xr vaccess 9 , +.Xr vnode 9 , +.Xr VOP_ACCESS 9 +.Sh AUTHORS +This manual page and the current implementation of +.Fn vaccess_acl_posix1e +were written by +.An Robert Watson . +.Sh BUGS +This manual page should include a full description of the POSIX.1e ACL +evaluation algorithm, or cross reference another page that does. Property changes on: user/imp/camdoc/vaccess_acl_posix1e.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vget.9 =================================================================== --- user/imp/camdoc/vget.9 (nonexistent) +++ user/imp/camdoc/vget.9 (revision 296049) @@ -0,0 +1,71 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1996 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd July 24, 1996 +.Dt VGET 9 +.Os +.Sh NAME +.Nm vget +.Nd get a vnode from the free list +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vget "struct vnode *vp" "int lockflag" "struct thread *td" +.Sh DESCRIPTION +Get a vnode from the free list and increment its reference count. +.Bl -tag -width lockflag +.It Fa vp +The vnode to remove from the free list. +.It Fa lockflag +If non-zero, the vnode will also be locked. +.El +.Pp +When not in use, vnodes are kept on a free list. +The vnodes still +reference valid files but may be reused to refer to a new file at any +time. +Often, these vnodes are also held in caches in the system, such +as the name cache. +.Pp +When a vnode which is on the free list is used again, for instance if +the vnode was found in the name cache as a result of a call to +.Xr VOP_LOOKUP 9 +then the new user must call +.Fn vget +to increment the reference count and remove it from the free list. +.Sh SEE ALSO +.Xr vnode 9 , +.Xr vput 9 , +.Xr vref 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/vget.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vrefcnt.9 =================================================================== --- user/imp/camdoc/vrefcnt.9 (nonexistent) +++ user/imp/camdoc/vrefcnt.9 (revision 296049) @@ -0,0 +1,53 @@ +.\" Copyright (C) 2007 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 February 10, 2008 +.Dt VREFCNT 9 +.Os +.Sh NAME +.Nm vrefcnt +.Nd returns the use count of a vnode +.Sh SYNOPSIS +.In sys/param.h +.In sys/vnode.h +.Ft int +.Fn vrefcnt "struct vnode *vp" +.Sh DESCRIPTION +Returns the use count of a vnode. +.Pp +See +.Xr vnode 9 +for a detailed description of the vnode reference counts. +.Sh SEE ALSO +.Xr vget 9 , +.Xr vnode 9 , +.Xr vput 9 , +.Xr vrele 9 +.Sh AUTHORS +This manual page was written by +.An Chad David . Property changes on: user/imp/camdoc/vrefcnt.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/kernacc.9 =================================================================== --- user/imp/camdoc/kernacc.9 (nonexistent) +++ user/imp/camdoc/kernacc.9 (revision 296049) @@ -0,0 +1,83 @@ +.\" $NetBSD: access.9,v 1.1 1996/06/16 10:38:35 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 June 16, 1996 +.Dt KERNACC 9 +.Os +.Sh NAME +.Nm kernacc , +.Nm useracc +.Nd check memory regions for accessibility +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.In vm/vm.h +.In vm/vm_extern.h +.Ft int +.Fn kernacc "void *addr" "int len" "int rw" +.Ft int +.Fn useracc "void *addr" "int len" "int rw" +.Sh DESCRIPTION +The +.Fn kernacc +and +.Fn useracc +functions check whether operations of the type specified in +.Fa rw +are permitted in the range of virtual addresses given by +.Fa addr +and +.Fa len . +The possible values of +.Fa rw +are any bitwise combination of +.Dv VM_PROT_READ , +.Dv VM_PROT_WRITE +and +.Dv VM_PROT_EXECUTE . +.Fn kernacc +checks addresses in the kernel address space, while +.Fn useracc +considers +.Fa addr +to represent an user space address. +The process context to use for this +operation is taken from the global variable +.Va curproc . +.Sh RETURN VALUES +Both functions return boolean true if the type of access specified +by +.Fa rw +is permitted. +Otherwise boolean false is returned. +.Sh BUGS +The process pointer should be passed in as an argument to +.Fn useracc . Property changes on: user/imp/camdoc/kernacc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/mtx_pool.9 =================================================================== --- user/imp/camdoc/mtx_pool.9 (nonexistent) +++ user/imp/camdoc/mtx_pool.9 (revision 296049) @@ -0,0 +1,184 @@ +.\" +.\" Copyright (C) 2002 Garrett Rooney . +.\" 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 February 6, 2010 +.Dt MTX_POOL 9 +.Os +.Sh NAME +.Nm mtx_pool , +.Nm mtx_pool_alloc , +.Nm mtx_pool_find , +.Nm mtx_pool_lock , +.Nm mtx_pool_lock_spin , +.Nm mtx_pool_unlock , +.Nm mtx_pool_unlock_spin , +.Nm mtx_pool_create , +.Nm mtx_pool_destroy +.Nd "mutex pool routines" +.Sh SYNOPSIS +.In sys/param.h +.In sys/lock.h +.In sys/mutex.h +.Ft "struct mtx *" +.Fn mtx_pool_alloc "struct mtx_pool *pool" +.Ft "struct mtx *" +.Fn mtx_pool_find "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_lock "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_lock_spin "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_unlock "struct mtx_pool *pool" "void *ptr" +.Ft void +.Fn mtx_pool_unlock_spin "struct mtx_pool *pool" "void *ptr" +.Ft "struct mtx_pool *" +.Fn mtx_pool_create "const char *mtx_name" "int pool_size" "int opts" +.Ft "void" +.Fn mtx_pool_destroy "struct mtx_pool **poolp" +.Sh DESCRIPTION +Mutex pools are designed to be used as short term leaf mutexes; +i.e., the last mutex one might acquire before calling +.Xr mtx_sleep 9 . +They operate using a shared pool of mutexes. +A mutex may be chosen from the pool based on a supplied pointer, +which may or may not point to anything valid, +or the caller may allocate an arbitrary shared mutex from the pool +and save the returned mutex pointer for later use. +.Pp +The shared mutexes in the +.Va mtxpool_sleep +mutex pool, +which is created by default, +are standard, non-recursive, +blockable mutexes, and should only be used in appropriate situations. +The mutexes in the +.Va mtxpool_lockbuilder +mutex pool are similar, except that they are initialized with the MTX_NOWITNESS +flag so that they may be used to build higher-level locks. +Other mutex pools may be created that contain mutexes with different +properties, such as spin mutexes. +.Pp +The caller can lock and unlock mutexes returned by the pool routines, but +since the mutexes are shared, the caller should not attempt to destroy them +or modify their characteristics. +While pool mutexes are normally leaf mutexes +(meaning that one cannot depend on any ordering guarantees +after obtaining one), +one can still obtain other mutexes under carefully controlled circumstances. +Specifically, if one has a private mutex +(one that was allocated and initialized by the caller), +one can obtain it after obtaining a pool mutex if ordering issues are +carefully accounted for. +In these cases the private mutex winds up being the true leaf mutex. +.Pp +Pool mutexes have the following advantages: +.Pp +.Bl -enum -offset indent -compact +.It +No structural overhead; +i.e., they can be associated with a structure without adding bloat to it. +.It +Mutexes can be obtained for invalid pointers, which is useful when one uses +mutexes to interlock destructor operations. +.It +No initialization or destruction overhead. +.It +Can be used with +.Xr mtx_sleep 9 . +.El +.Pp +And the following disadvantages: +.Pp +.Bl -enum -offset indent -compact +.It +Should generally only be used as leaf mutexes. +.It +Pool/pool dependency ordering cannot be guaranteed. +.It +Possible L1 cache mastership contention between CPUs. +.El +.Pp +.Fn mtx_pool_alloc +obtains a shared mutex from the specified pool. +This routine uses a simple rover to choose one of the shared mutexes managed +by the +.Nm +subsystem. +.Pp +.Fn mtx_pool_find +returns the shared mutex associated with the specified address. +This routine will create a hash out of the pointer passed into it +and will choose a shared mutex from the specified pool based on that hash. +The pointer does not need to point to anything real. +.Pp +.Fn mtx_pool_lock , +.Fn mtx_pool_lock_spin , +.Fn mtx_pool_unlock , +and +.Fn mtx_pool_unlock_spin +lock and unlock the shared mutex from the specified pool +associated with the specified address; +they are a combination of +.Fn mtx_pool_find +and +.Xr mtx_lock 9 , +.Xr mtx_lock_spin 9 , +.Xr mtx_unlock 9 , +and +.Xr mtx_unlock_spin 9 , +respectively. +Since these routines must first find the mutex to operate on, +they are not as fast as directly using the mutex pointer returned by +a previous invocation of +.Fn mtx_pool_find +or +.Fn mtx_pool_alloc . +.Pp +.Fn mtx_pool_create +allocates and initializes a new mutex pool of the +specified size. +The pool size must be a power of two. +The +.Fa opts +argument is passed to +.Xr mtx_init 9 +to set the options for each mutex in the pool. +.Pp +.Fn mtx_pool_destroy +calls +.Xr mtx_destroy 9 +on each mutex in the specified pool, +deallocates the memory associated with the pool, +and assigns NULL to the pool pointer. +.Sh SEE ALSO +.Xr locking 9 , +.Xr mutex 9 +.Sh HISTORY +These routines first appeared in +.Fx 5.0 . Property changes on: user/imp/camdoc/mtx_pool.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ieee80211_beacon.9 =================================================================== --- user/imp/camdoc/ieee80211_beacon.9 (nonexistent) +++ user/imp/camdoc/ieee80211_beacon.9 (revision 296049) @@ -0,0 +1,115 @@ +.\" +.\" Copyright (c) 2009 Sam Leffler, Errno Consulting +.\" 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 4, 2009 +.Dt IEEE80211_BEACON 9 +.Os +.Sh NAME +.Nm ieee80211_beacon +.Nd 802.11 beacon support +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.Pp +.Ft "struct mbuf *" +.Fo ieee80211_beacon_alloc +.Fa "struct ieee80211_node *" +.Fa "struct ieee80211_beacon_offsets *" +.Fc +.\" +.Ft int +.Fo ieee80211_beacon_update +.Fa "struct ieee80211_node *" +.Fa "struct ieee80211_beacon_offsets *" +.Fa "struct mbuf *" +.Fa "int mcast" +.Fc +.\" +.Ft void +.Fn ieee80211_beacon_notify "struct ieee80211vap *" "int what" +.Sh DESCRIPTION +The +.Nm net80211 +software layer provides a support framework for drivers that includes +a template-based mechanism for dynamic update of beacon frames transmit +in hostap, adhoc, and mesh operating modes. +Drivers should use +.Fn ieee80211_beacon_alloc +to create an initial beacon frame. +The +.Vt ieee80211_beacon_offsets +structure holds information about the beacon contents that is used +to optimize updates done with +.Fn ieee80211_beacon_update . +.Pp +Update calls should only be done when something changes that +affects the contents of the beacon frame. +When this happens the +.Dv iv_update_beacon +method is invoked and a driver-supplied routine must do the right thing. +For devices that involve the host to transmit each +beacon frame this work may be as simple as marking a bit in the +.Vt ieee80211_beacon_offsets +structure: +.Bd -literal +static void +ath_beacon_update(struct ieee80211vap *vap, int item) +{ + struct ieee80211_beacon_offsets *bo = &ATH_VAP(vap)->av_boff; + setbit(bo->bo_flags, item); +} +.Ed +.Pp +with the +.Fn ieee80211_beacon_update +call done before the next beacon is to be sent. +.Pp +Devices that off-load beacon generation may instead choose to use +this callback to push updates immediately to the device. +Exactly how that is accomplished is unspecified. +One possibility is to update the beacon frame contents and extract +the appropriate information element, but other scenarios are possible. +.Sh MULTI-VAP BEACON SCHEDULING +Drivers that support multiple vaps that can each beacon need to consider +how to schedule beacon frames. +There are two possibilities at the moment: +.Em burst +all beacons at TBTT or +.Em stagger beacons +over the beacon interval. +Bursting beacon frames may result in aperiodic delivery that can affect +power save operation of associated stations. +Applying some jitter (e.g. by randomly ordering burst frames) may be +sufficient to combat this and typically this is not an issue unless +stations are using aggressive power save techniques +such as U-APSD (sometimes employed by VoIP phones). +Staggering frames requires more interrupts and device support that +may not be available. +Staggering beacon frames is usually superior to bursting frames, up to +about eight vaps, at which point the overhead becomes significant and +the channel becomes noticeably busy anyway. +.Sh SEE ALSO +.Xr ieee80211 9 Property changes on: user/imp/camdoc/ieee80211_beacon.9 ___________________________________________________________________ Added: svn:eol-style ## -0,0 +1 ## +native \ No newline at end of property Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Added: svn:mime-type ## -0,0 +1 ## +text/plain \ No newline at end of property Index: user/imp/camdoc/dev_clone.9 =================================================================== --- user/imp/camdoc/dev_clone.9 (nonexistent) +++ user/imp/camdoc/dev_clone.9 (revision 296049) @@ -0,0 +1,78 @@ +.\" Copyright (c) 2008 Konstantin Belousov +.\" 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 January 3, 2009 +.Dt DEV_CLONE 9 +.Os +.Sh NAME +.Nm dev_clone , +.Nm drain_dev_clone_events +.Nd eventhandler for name-based device cloning in devfs +.Sh SYNOPSIS +.In sys/param.h +.In sys/conf.h +.Ft void +.Fn clone_handler "void *arg" "struct ucred *cr" "char *name" "int namelen" "struct cdev **dev" +.Bd -literal +EVENTHANDLER_REGISTER(dev_clone, clone_handler, arg, priority); +.Ed +.Ft void +.Fn drain_dev_clone_events +.Sh DESCRIPTION +A device driver may register a listener that will be notified each time +a name lookup on the +.Xr devfs 5 +mount point fails to find the vnode. +A listener shall be registered for the +.Va dev_clone +event. +When called, it is supplied with the first argument +.Va arg +that was specified at handler registration time, +appropriate credentials +.Va cr , +and a name +.Va name +of length +.Va namelen +that we look for. +If the handler decides that the name is appropriate and wants to create the device +that will be associated with the name, it should return it to devfs +in the +.Va dev +argument. +.Pp +The +.Fn drain_dev_clone_events +function is a barrier. +It is guaranteed that all calls to eventhandlers for +.Nm dev_clone +that were started before +.Fn drain_dev_clone_events +call, are finished before it returns control. +.Sh SEE ALSO +.Xr devfs 5 , +.Xr namei 9 Property changes on: user/imp/camdoc/dev_clone.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/ktr.9 =================================================================== --- user/imp/camdoc/ktr.9 (nonexistent) +++ user/imp/camdoc/ktr.9 (revision 296049) @@ -0,0 +1,162 @@ +.\" Copyright (c) 2001 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 November 30, 2008 +.Dt KTR 9 +.Os +.Sh NAME +.Nm CTR0 , CTR1 , CTR2 , CTR3 , CTR4 , CTR5 +.Nd kernel tracing facility +.Sh SYNOPSIS +.In sys/param.h +.In sys/ktr.h +.Vt "extern int ktr_cpumask" ; +.Vt "extern int ktr_entries" ; +.Vt "extern int ktr_extend" ; +.Vt "extern int ktr_mask" ; +.Vt "extern int ktr_verbose" ; +.Vt "extern struct ktr_entry ktr_buf[]" ; +.Ft void +.Fn CTR0 "u_int mask" "char *format" +.Ft void +.Fn CTR1 "u_int mask" "char *format" "arg1" +.Ft void +.Fn CTR2 "u_int mask" "char *format" "arg1" "arg2" +.Ft void +.Fn CTR3 "u_int mask" "char *format" "arg1" "arg2" "arg3" +.Ft void +.Fn CTR4 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" +.Ft void +.Fn CTR5 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" +.Ft void +.Fn CTR6 "u_int mask" "char *format" "arg1" "arg2" "arg3" "arg4" "arg5" "arg6" +.Sh DESCRIPTION +KTR provides a circular buffer of events that can be logged in a +.Xr printf 9 +style +fashion. +These events can then be dumped with +.Xr ddb 4 , +.Xr gdb 1 +or +.Xr ktrdump 8 . +.Pp +Events are created and logged in the kernel via the +.Dv CTR Ns Ar x +macros. +The first parameter is a mask of event types +.Pq Dv KTR_* +defined in +.In sys/ktr.h . +The event will be logged only if any of the event types specified in +.Fa mask +are enabled in the global event mask stored in +.Va ktr_mask . +The +.Fa format +argument is a +.Xr printf 9 +style format string used to build the text of the event log message. +Following the +.Fa format +string are zero to five arguments referenced by +.Fa format . +Each event is logged with a file name and source line number of the +originating CTR call, and a timestamp in addition to the log message. +.Pp +The event is stored in the circular buffer with supplied arguments as is, +and formatting is done at the dump time. +Do not use pointers to the objects with limited lifetime, for instance, +strings, because the pointer may become invalid when buffer is printed. +.Pp +Note that the different macros differ only in the number of arguments each +one takes, as indicated by its name. +.Pp +The +.Va ktr_entries +variable contains the number of entries in the +.Va ktr_buf +array. +These variables are mostly useful for post-mortem crash dump tools to locate +the base of the circular trace buffer and its length. +.Pp +The +.Va ktr_mask +variable contains the run time mask of events to log. +.Pp +The CPU event mask is stored in the +.Va ktr_cpumask +variable. +.Pp +The +.Va ktr_verbose +variable stores the verbose flag that controls whether events are logged to +the console in addition to the event buffer. +.Sh EXAMPLES +This example demonstrates the use of tracepoints at the +.Dv KTR_PROC +logging level. +.Bd -literal +void +mi_switch() +{ + ... + /* + * Pick a new current process and record its start time. + */ + ... + CTR3(KTR_PROC, "mi_switch: old proc %p (pid %d)", p, p->p_pid); + ... + cpu_switch(); + ... + CTR3(KTR_PROC, "mi_switch: new proc %p (pid %d)", p, p->p_pid); + ... +} +.Ed +.Sh SEE ALSO +.Xr ktr 4 , +.Xr ktrdump 8 +.Sh HISTORY +The KTR kernel tracing facility first appeared in +.Bsx 3.0 +and was imported into +.Fx 5.0 . +.Sh BUGS +Currently there is one global buffer shared among all CPUs. +It might be profitable at some point in time to use per-CPU buffers instead +so that if one CPU halts or starts spinning, then the log messages it +emitted just prior to halting or spinning will not be drowned out by events +from the other CPUs. +.Pp +The arguments given in +.Fn CTRx +macros are stored as +.Vt u_long , +so do not pass arguments larger than size of an +.Vt u_long +type. +For example passing 64bit arguments on 32bit architectures will give incorrect +results. Property changes on: user/imp/camdoc/ktr.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/priv.9 =================================================================== --- user/imp/camdoc/priv.9 (nonexistent) +++ user/imp/camdoc/priv.9 (revision 296049) @@ -0,0 +1,122 @@ +.\"- +.\" Copyright (c) 2006 nCircle Network Security, Inc. +.\" All rights reserved. +.\" +.\" This software was developed by Robert N. M. Watson for the TrustedBSD +.\" Project under contract to nCircle Network Security, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" 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, NCIRCLE NETWORK SECURITY, +.\" INC., 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, 2006 +.Dt PRIV 9 +.Os +.Sh NAME +.Nm priv +.Nd kernel privilege checking API +.Sh SYNOPSIS +.In sys/priv.h +.Ft int +.Fn priv_check "struct thread *td" "int priv" +.Ft int +.Fn priv_check_cred "struct ucred *cred" "int priv" "int flags" +.Sh DESCRIPTION +The +.Nm +interfaces check to see if specific system privileges are granted to the +passed thread, +.Fa td , +or credential, +.Fa cred . +This interface replaces the now removed +.Xr suser 9 +privilege checking interface. +Privileges typically represent rights in one of two categories: the right to +manage a particular component of the system, or an exemption to a specific +policy or access control list. +The caller identifies the desired privilege via the +.Fa priv +argument. +The optional flags argument, +.Fa flags , +is currently unused. +.Ss Privilege Policies +Privileges are typically granted based on one of two base system policies: +the superuser policy, which grants privilege based on the effective (or +sometimes real) UID having a value of 0, and the +.Xr jail 2 +policy, which permits only certain privileges to be granted to processes in a +jail. +The set of available privileges may also be influenced by the TrustedBSD MAC +Framework, described in +.Xr mac 9 . +.Sh IMPLEMENTATION NOTES +When adding a new privilege check to a code path, first check the complete +list of current privileges in +.Pa sys/priv.h +to see if one already exists for the class of privilege required. +Only if there is not an exact match should a new privilege be added to the +privilege list. +As privilege numbers becomes encoded in the kernel module ABI, privilege +constants must not be changed as any kernel modules depending on privileges +will then need to be recompiled. +When adding a new privilege, be certain to also determine whether it should +be listed in +.Fn prison_priv_check , +which includes a complete list of privileges granted to the root user in +.Xr jail 2 . +.Pp +Certain catch-all privileges exist, such as +.Dv PRIV_DRIVER , +intended to be used by device drivers, rather than adding a new +driver-specific privilege. +.Sh RETURN VALUES +Typically, 0 will be returned for success, and +.Er EPERM +will be returned on failure. +Most consumers of +.Nm +will wish to directly return the error code from a failed privilege check to +user space; a small number will wish to translate it to another error code +appropriate to a specific context. +.Pp +When designing new APIs, it is preferable to return explicit errors from a +call if privilege is not granted rather than changing the semantics of the +call but returning success. +For example, the behavior exhibited by +.Xr stat 2 , +in which the generation field is optionally zero'd out when there is +insufficient privilege is highly undesirable, as it results in frequent +privilege checks, and the caller is unable to tell if an access control +failure occurred. +.Sh SEE ALSO +.Xr jail 2 , +.Xr mac 9 , +.Xr ucred 9 +.Sh AUTHORS +The +.Nm +API and implementation were created by +.An Robert Watson +under contract to +nCircle Network Security, Inc. Property changes on: user/imp/camdoc/priv.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_suser.9 =================================================================== --- user/imp/camdoc/vfs_suser.9 (nonexistent) +++ user/imp/camdoc/vfs_suser.9 (revision 296049) @@ -0,0 +1,72 @@ +.\" +.\" Copyright (c) 2004 Alfred Perlstein +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 2, 2004 +.Dt VFS_SUSER 9 +.Os +.Sh NAME +.Nm vfs_suser +.Nd check if credentials have superuser privileges for a mount point +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.In sys/mount.h +.Ft int +.Fn vfs_suser "struct mount *mp" "struct thread *td" +.Sh DESCRIPTION +The +.Fn vfs_suser +function checks if the credentials given include superuser powers +for the given mount point. +It will check to see if the thread +passed in has the same credentials as the user that mounted the +file system. +If so, it returns 0, otherwise it returns what +.Xr priv_check 9 +would have returned. +.Sh RETURN VALUES +The +.Fn vfs_suser +function returns 0 if the user has superuser powers and +.Er EPERM +otherwise. +This is the +.Em reverse logic +of some other implementations of +.Fn suser +in which a TRUE response indicates superuser powers. +.Sh SEE ALSO +.Xr chroot 2 , +.Xr jail 2 +.Sh HISTORY +The +.Fn vfs_suser +function was introduced in +.Fx 5.2 . +.Sh AUTHORS +This manual page was written by +.An Alfred Perlstein . Property changes on: user/imp/camdoc/vfs_suser.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/sf_buf.9 =================================================================== --- user/imp/camdoc/sf_buf.9 (nonexistent) +++ user/imp/camdoc/sf_buf.9 (revision 296049) @@ -0,0 +1,142 @@ +.\" +.\" Copyright (c) 2007 Seccuris Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by Robert N. M. Watson under contract to +.\" Seccuris Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice(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 January 28, 2007 +.Dt SF_BUF 9 +.Os +.Sh NAME +.Nm sf_buf +.Nd manage temporary kernel address space mapping for memory pages +.Sh SYNOPSIS +.In sys/sf_buf.h +.Ft struct sf_buf * +.Fn sf_buf_alloc "struct vm_page *m" "int flags" +.Ft void +.Fn sf_buf_free "struct sf_buf *sf" +.Ft vm_offset_t +.Fn sf_buf_kva "struct sf_buf *sf" +.Ft struct vm_page * +.Fn sf_buf_page "struct sf_buf *sf" +.Sh DESCRIPTION +The +.Nm +interface, historically the +.Xr sendfile 2 +buffer interface, allows kernel subsystems to manage temporary kernel address +space mappings for physical memory pages. +On systems with a direct memory map region (allowing all physical pages to be +visible in the kernel address space at all times), the +.Vt "struct sf_buf" +will point to an address in the direct map region; on systems without a +direct memory map region, the +.Vt "struct sf_buf" +will manage a temporary kernel address space mapping valid for the lifetime +of the +.Vt "struct sf_buf". +.Pp +Call +.Fn sf_buf_alloc +to allocate a +.Vt "struct sf_buf" +for a physical memory page. +.Fn sf_buf_alloc +is not responsible for arranging for the page to be present in physical +memory; the caller should already have arranged for the page to be wired, +i.e., by calling +.Xr vm_page_wire 9 . +Several flags may be passed to +.Fn sf_buf_alloc : +.Bl -tag -width SFB_CPUPRIVATE +.It Dv SFB_CATCH +Cause +.Fn sf_buf_alloc +to abort and return +.Dv NULL +if a signal is received waiting for a +.Vt "struct sf_buf" +to become available. +.It Dv SFB_NOWAIT +Cause +.Fn sf_buf_alloc +to return +.Dv NULL +rather than sleeping if a +.Vt "struct sf_buf" +is not immediately available. +.It Dv SFB_CPUPRIVATE +Cause +.Fn sf_buf_alloc +to only arrange that the temporary mapping be valid on the current CPU, +avoiding unnecessary TLB shootdowns for mappings that will only be accessed +on a single CPU at a time. +The caller must ensure that accesses to the virtual address occur only on the +CPU from which +.Fn sf_buf_alloc +was invoked, perhaps by using +.Fn sched_pin . +.El +.Pp +Call +.Fn sf_buf_kva +to return a kernel mapped address for the page. +.Pp +Call +.Fn sf_buf_page +to return a pointer to the page originally passed into +.Fn sf_buf_alloc . +.Pp +Call +.Fn sf_buf_free +to release the +.Vt "struct sf_buf" +reference. +The caller is responsible for releasing any wiring they have previously +acquired on the physical page; +.Fn sf_buf_free +releases only the temporary kernel address space mapping, not the page +itself. +.Pp +Uses of this interface include managing mappings of borrowed pages from user +memory, such as in zero-copy socket I/O, or pages of memory from the buffer +cache referenced by mbuf external storage for +.Xr sendfile 2 . +.Sh SEE ALSO +.Xr sendfile 2 , +.Xr vm_page_wire 9 +.Sh AUTHORS +.An -nosplit +The +.Vt "struct sf_buf" +API was designed and implemented by +.An Alan L. Cox . +This manual page was written by +.An Robert N. M. Watson . Property changes on: user/imp/camdoc/sf_buf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/securelevel_gt.9 =================================================================== --- user/imp/camdoc/securelevel_gt.9 (nonexistent) +++ user/imp/camdoc/securelevel_gt.9 (revision 296049) @@ -0,0 +1,71 @@ +.\" +.\" Copyright (c) 2000 Christian S.J. Peron +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 2, 2007 +.Dt SECURELEVEL_GT 9 +.Os +.Sh NAME +.Nm securelevel_gt , securelevel_ge +.Nd test active securelevel +.Sh SYNOPSIS +.In sys/types.h +.In sys/proc.h +.Ft int +.Fn securelevel_gt "struct ucred *cr" "int level" +.Ft int +.Fn securelevel_ge "struct ucred *cr" "int level" +.Sh DESCRIPTION +These functions test the active security level against the given +.Fa level . +If the calling credential +.Fa cr +was imprisoned by the +.Xr jail 2 +system call, and has a +different security level set than the host environment, +the security level with the highest value is used. +.Pp +The +.Fn securelevel_gt +function +will evaluate whether or not the active security +level is greater than the supplied +.Fa level . +.Pp +The +.Fn securelevel_ge +function +will evaluate whether or not the active security +level is greater than or equal to the supplied +.Fa level . +.Sh RETURN VALUES +These functions return +.Er EPERM +if condition evaluated to true, and 0 otherwise. +.Sh SEE ALSO +.Xr securelevel 7 Property changes on: user/imp/camdoc/securelevel_gt.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/sema.9 =================================================================== --- user/imp/camdoc/sema.9 (nonexistent) +++ user/imp/camdoc/sema.9 (revision 296049) @@ -0,0 +1,132 @@ +.\" +.\" Copyright (C) 2001 Jason Evans . 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 February 1, 2006 +.Dt SEMA 9 +.Os +.Sh NAME +.Nm sema , +.Nm sema_init , +.Nm sema_destroy , +.Nm sema_post , +.Nm sema_wait , +.Nm sema_timedwait , +.Nm sema_trywait , +.Nm sema_value +.Nd kernel counting semaphore +.Sh SYNOPSIS +.In sys/types.h +.In sys/lock.h +.In sys/sema.h +.Ft void +.Fn sema_init "struct sema *sema" "int value" "const char *description" +.Ft void +.Fn sema_destroy "struct sema *sema" +.Ft void +.Fn sema_post "struct sema *sema" +.Ft void +.Fn sema_wait "struct sema *sema" +.Ft int +.Fn sema_timedwait "struct sema *sema" "int timo" +.Ft int +.Fn sema_trywait "struct sema *sema" +.Ft int +.Fn sema_value "struct sema *sema" +.Sh DESCRIPTION +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 also +be useful in situations where one thread needs to acquire a resource, and +another thread needs to release it. +Each semaphore has an integer value associated with it. +Posting (incrementing) always succeeds, but waiting (decrementing) can only +successfully complete if the resulting value of the semaphore is greater than or +equal to zero. +.Pp +Semaphores should not be used where mutexes and condition variables +will suffice. +Semaphores are a more complex synchronization mechanism than mutexes and +condition variables, and are not as efficient. +.Pp +Semaphores are created with +.Fn sema_init , +where +.Fa sema +is a pointer to space for a +.Vt "struct sema" , +.Fa value +is the initial value of the semaphore, and +.Fa description +is a pointer to a null-terminated character string that describes the semaphore. +Semaphores are destroyed with +.Fn sema_destroy . +A semaphore is posted (incremented) with +.Fn sema_post . +A semaphore is waited on (decremented) with +.Fn sema_wait , +.Fn sema_timedwait , +or +.Fn sema_trywait . +The +.Fa timo +argument to +.Fn sema_timedwait +specifies the minimum time in ticks to wait before returning with failure. +.Fn sema_value +is used to read the current value of the semaphore. +.Sh RETURN VALUES +The +.Fn sema_value +function +returns the current value of the semaphore. +.Pp +If decrementing the semaphore would result in its value being negative, +.Fn sema_trywait +returns 0 to indicate failure. +Otherwise, a non-zero value is returned to indicate success. +.Pp +The +.Fn sema_timedwait +function +returns 0 if waiting on the semaphore succeeded; otherwise a +non-zero error code is returned. +.Sh ERRORS +The +.Fn sema_timedwait +function will fail if: +.Bl -tag -width Er +.It Bq Er EWOULDBLOCK +Timeout expired. +.El +.Sh SEE ALSO +.Xr condvar 9 , +.Xr locking 9 , +.Xr mtx_pool 9 , +.Xr mutex 9 , +.Xr rwlock 9 , +.Xr sx 9 Property changes on: user/imp/camdoc/sema.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/thread_exit.9 =================================================================== --- user/imp/camdoc/thread_exit.9 (nonexistent) +++ user/imp/camdoc/thread_exit.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2002 Julian Elischer +.\" 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, 2002 +.Dt THREAD_EXIT 9 +.Os +.Sh NAME +.Nm thread_exit +.Nd abandon current thread context +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft void +.Fn thread_exit "void" +.Sh DESCRIPTION +The +.Fn thread_exit +function implements the machine independent prelude to a thread +shutdown. +It will not return, and will result in a call to +.Xr mi_switch 9 +to schedule some other thread. +.Pp +.Fn thread_exit +arranges to free all the resources of the thread, specifically the kernel +stack. +.Pp +To protect the +.Xr runqueue 9 , +.Fn thread_exit +must be called with the +.Va sched_lock +mutex held. +.Sh SEE ALSO +.Xr mi_switch 9 , +.Xr mutex 9 , +.Xr runqueue 9 , +.Xr sleep 9 Property changes on: user/imp/camdoc/thread_exit.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_set_driver.9 =================================================================== --- user/imp/camdoc/device_set_driver.9 (nonexistent) +++ user/imp/camdoc/device_set_driver.9 (revision 296049) @@ -0,0 +1,53 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 21, 2003 +.Dt DEVICE_SET_DRIVER 9 +.Os +.Sh NAME +.Nm device_set_driver +.Nd "associate a specific driver with a device node in the tree" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_set_driver "device_t dev" "driver_t *driver" +.Sh DESCRIPTION +This function associates a specific driver with a given device node +in the tree. +It is typically used in +.Xr DEVICE_IDENTIFY 9 +functions to add devices to a bus that does not support doing so +automatically, such as the ISA bus. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An M. Warner Losh . Property changes on: user/imp/camdoc/device_set_driver.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/time.9 =================================================================== --- user/imp/camdoc/time.9 (nonexistent) +++ user/imp/camdoc/time.9 (revision 296049) @@ -0,0 +1,115 @@ +.\" $NetBSD: time.9,v 1.1 1995/11/25 21:24:53 perry Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd September 17, 2004 +.Dt TIME 9 +.Os +.Sh NAME +.Nm boottime , +.Nm time_second , +.Nm time_uptime +.Nd system time variables +.Sh SYNOPSIS +.In sys/time.h +.Pp +.Vt extern struct timeval boottime ; +.Vt extern time_t time_second ; +.Vt extern time_t time_uptime ; +.Sh DESCRIPTION +The +.Va boottime +variable holds the system boot time. +.Pp +The +.Va time_second +variable is the system's +.Dq wall time +clock to the second. +.Pp +The +.Va time_uptime +variable is the number of seconds since boot. +.Pp +The +.Xr bintime 9 , +.Xr getbintime 9 , +.Xr microtime 9 , +.Xr getmicrotime 9 , +.Xr nanotime 9 , +and +.Xr getnanotime 9 +functions can be used to get the current time more accurately and in an +atomic manner. +Similarly, the +.Xr binuptime 9 , +.Xr getbinuptime 9 , +.Xr microuptime 9 , +.Xr getmicrouptime 9 , +.Xr nanouptime 9 , +and +.Xr getnanouptime 9 +functions can be used to get the time elapse since boot more accurately +and in an atomic manner. +The +.Va boottime +variable may be read and written without special precautions. +.Sh SEE ALSO +.Xr clock_settime 2 , +.Xr ntp_adjtime 2 , +.Xr settimeofday 2 , +.Xr bintime 9 , +.Xr binuptime 9 , +.Xr getbintime 9 , +.Xr getbinuptime 9 , +.Xr getmicrotime 9 , +.Xr getmicrouptime 9 , +.Xr getnanotime 9 , +.Xr getnanouptime 9 , +.Xr microtime 9 , +.Xr microuptime 9 , +.Xr nanotime 9 , +.Xr nanouptime 9 +.Rs +.%A "Poul-Henning Kamp" +.%T "Timecounters: Efficient and precise timekeeping in SMP kernels" +.%J "Proceedings of EuroBSDCon 2002, Amsterdam" +.%O /usr/share/doc/papers/timecounter.ascii.gz +.Re +.Rs +.%A "Marshall Kirk McKusick" +.%A "George V. Neville-Neil" +.%B "The Design and Implementation of the FreeBSD Operating System" +.%D "July 2004" +.%I "Addison-Wesley" +.%P "57-61,65-66" +.Re Property changes on: user/imp/camdoc/time.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/critical_enter.9 =================================================================== --- user/imp/camdoc/critical_enter.9 (nonexistent) +++ user/imp/camdoc/critical_enter.9 (revision 296049) @@ -0,0 +1,74 @@ +.\" Copyright (c) 2001,2002 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 October 5, 2005 +.Dt CRITICAL_ENTER 9 +.Os +.Sh NAME +.Nm critical_enter , +.Nm critical_exit +.Nd enter and exit a critical region +.Sh SYNOPSIS +.In sys/param.h +.In sys/systm.h +.Ft void +.Fn critical_enter "void" +.Ft void +.Fn critical_exit "void" +.Sh DESCRIPTION +These functions are used to prevent preemption in a critical region of code. +All that is guaranteed is that the thread currently executing on a CPU will +not be preempted. +Specifically, a thread in a critical region will not migrate to another +CPU while it is in a critical region. +The current CPU may still trigger faults and exceptions during a critical +section; however, these faults are usually fatal. +.Pp +The +.Fn critical_enter +and +.Fn critical_exit +functions manage a per-thread counter to handle nested critical sections. +If a thread is made runnable that would normally preempt the current thread +while the current thread is in a critical section, +then the preemption will be deferred until the current thread exits the +outermost critical section. +.Pp +Note that these functions are not required to provide any inter-CPU +synchronization, data protection, or memory ordering guarantees and thus +should +.Em not +be used to protect shared data structures. +.Pp +These functions should be used with care as an infinite loop within a +critical region will deadlock the CPU. +Also, they should not be interlocked with operations on mutexes, sx locks, +semaphores, or other synchronization primitives. +One exception to this is that spin mutexes include a critical section, +so in certain cases critical sections may be interlocked with spin mutexes. +.Sh HISTORY +These functions were introduced in +.Fx 5.0 . Property changes on: user/imp/camdoc/critical_enter.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DEVICE_DETACH.9 =================================================================== --- user/imp/camdoc/DEVICE_DETACH.9 (nonexistent) +++ user/imp/camdoc/DEVICE_DETACH.9 (revision 296049) @@ -0,0 +1,65 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_DETACH 9 +.Os +.Sh NAME +.Nm DEVICE_DETACH +.Nd detach a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_DETACH "device_t dev" +.Sh DESCRIPTION +Detach a device. +This can be called if the user is replacing the +driver software or if a device is about to be physically removed from +the system (e.g.\& for +.Xr pccard 4 +devices). +.Pp +The method should deallocate any system resources allocated during the +.Xr DEVICE_ATTACH 9 +method and reset the hardware to a sane state (i.e., disable interrupts +etc.) +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr pccard 4 , +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 , +.Xr DEVICE_SHUTDOWN 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/DEVICE_DETACH.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/DEVICE_SHUTDOWN.9 =================================================================== --- user/imp/camdoc/DEVICE_SHUTDOWN.9 (nonexistent) +++ user/imp/camdoc/DEVICE_SHUTDOWN.9 (revision 296049) @@ -0,0 +1,57 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 6, 2005 +.Dt DEVICE_SHUTDOWN 9 +.Os +.Sh NAME +.Nm DEVICE_SHUTDOWN +.Nd called during system shutdown +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn DEVICE_SHUTDOWN "device_t dev" +.Sh DESCRIPTION +The +.Fn DEVICE_SHUTDOWN +method is called during system shutdown to allow the driver to put the +hardware into a consistent state for rebooting the computer. +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr DEVICE_ATTACH 9 , +.Xr DEVICE_DETACH 9 , +.Xr DEVICE_IDENTIFY 9 , +.Xr DEVICE_PROBE 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/DEVICE_SHUTDOWN.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_generic_attach.9 =================================================================== --- user/imp/camdoc/bus_generic_attach.9 (nonexistent) +++ user/imp/camdoc/bus_generic_attach.9 (revision 296049) @@ -0,0 +1,58 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt BUS_GENERIC_ATTACH 9 +.Os +.Sh NAME +.Nm bus_generic_attach +.Nd generic implementation of +.Dv DEVICE_ATTACH +for busses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_attach "device_t dev" +.Sh DESCRIPTION +This function provides an implementation of the +.Xr DEVICE_ATTACH 9 +method which can be used by most bus code. +It simply calls +.Xr device_probe_and_attach 9 +for each child device attached to the bus. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/bus_generic_attach.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_generic_detach.9 =================================================================== --- user/imp/camdoc/bus_generic_detach.9 (nonexistent) +++ user/imp/camdoc/bus_generic_detach.9 (revision 296049) @@ -0,0 +1,59 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt BUS_GENERIC_DETACH 9 +.Os +.Sh NAME +.Nm bus_generic_detach +.Nd generic implementation of +.Dv DEVICE_DETACH +for busses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_detach "device_t dev" +.Sh DESCRIPTION +This function provides an implementation of the +.Xr DEVICE_DETACH 9 +method +which can be used by most bus code. +It simply calls the +.Xr DEVICE_DETACH 9 +method of each child device attached to the bus. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/bus_generic_detach.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_generic_read_ivar.9 =================================================================== --- user/imp/camdoc/bus_generic_read_ivar.9 (nonexistent) +++ user/imp/camdoc/bus_generic_read_ivar.9 (revision 296049) @@ -0,0 +1,57 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt BUS_GENERIC_READ_IVAR 9 +.Os +.Sh NAME +.Nm bus_generic_read_ivar , +.Nm bus_generic_write_ivar +.Nd generic implementation of +.Dv BUS_READ_IVAR +and +.Dv BUS_WRITE_IVAR +for busses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_read_ivar "device_t dev" "device_t child" "int index" "uintptr_t *result" +.Ft int +.Fn bus_generic_write_ivar "device_t dev" "device_t child" "int index" "uintptr_t value" +.Sh DESCRIPTION +These functions simply return +.Er ENOENT . +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/bus_generic_read_ivar.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/bus_generic_shutdown.9 =================================================================== --- user/imp/camdoc/bus_generic_shutdown.9 (nonexistent) +++ user/imp/camdoc/bus_generic_shutdown.9 (revision 296049) @@ -0,0 +1,59 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt BUS_GENERIC_SHUTDOWN 9 +.Os +.Sh NAME +.Nm bus_generic_shutdown +.Nd generic implementation of +.Dv DEVICE_SHUTDOWN +for busses +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn bus_generic_shutdown "device_t dev" +.Sh DESCRIPTION +This function provides an implementation of the +.Xr DEVICE_SHUTDOWN 9 +method +which can be used by most bus code. +It simply calls the +.Xr DEVICE_SHUTDOWN 9 +method of each child device attached to the bus. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/bus_generic_shutdown.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass.9 =================================================================== --- user/imp/camdoc/devclass.9 (nonexistent) +++ user/imp/camdoc/devclass.9 (revision 296049) @@ -0,0 +1,69 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVCLASS 9 +.Os +.Sh NAME +.Nm devclass +.Nd object representing a class of devices +.Sh SYNOPSIS +.Vt typedef struct devclass *devclass_t ; +.Sh DESCRIPTION +The +.Vt devclass +object has two main functions in the system. +The first is to manage +the allocation of unit numbers for device instances and the second is +to hold the list of device drivers for a particular bus type. +Each +.Vt devclass +has a name and there cannot be two devclasses with the same name. +This ensures that unique unit numbers are allocated to device +instances. +.Pp +Beware that this means +.Vt devclass +must be the same for different bus attachments of the same device driver. +.Sh SEE ALSO +.Xr devclass_add_driver 9 , +.Xr devclass_delete_driver 9 , +.Xr devclass_find 9 , +.Xr devclass_find_driver 9 , +.Xr devclass_get_device 9 , +.Xr devclass_get_devices 9 , +.Xr devclass_get_maxunit 9 , +.Xr devclass_get_name 9 , +.Xr devclass_get_softc 9 , +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/devclass.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_find.9 =================================================================== --- user/imp/camdoc/devclass_find.9 (nonexistent) +++ user/imp/camdoc/devclass_find.9 (revision 296049) @@ -0,0 +1,56 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVCLASS_FIND 9 +.Os +.Sh NAME +.Nm devclass_find +.Nd search for a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft devclass_t +.Fn devclass_find "const char *classname" +.Sh DESCRIPTION +Search for the +.Vt devclass +with the specified name. +.Sh RETURN VALUES +If the +.Vt devclass +exists, it is returned, otherwise +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr devclass 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/devclass_find.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_get_count.9 =================================================================== --- user/imp/camdoc/devclass_get_count.9 (nonexistent) +++ user/imp/camdoc/devclass_get_count.9 (revision 296049) @@ -0,0 +1,47 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2004 Nate Lawson +.\" 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 December 5, 2004 +.Dt DEVCLASS_GET_COUNT 9 +.Os +.Sh NAME +.Nm devclass_get_count +.Nd get the number of devices in a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_count "devclass_t dc" +.Sh DESCRIPTION +Returns the number of device instances in the specified +.Vt devclass . +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Nate Lawson . Property changes on: user/imp/camdoc/devclass_get_count.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_get_device.9 =================================================================== --- user/imp/camdoc/devclass_get_device.9 (nonexistent) +++ user/imp/camdoc/devclass_get_device.9 (revision 296049) @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVCLASS_GET_DEVICE 9 +.Os +.Sh NAME +.Nm devclass_get_device +.Nd translate unit number to device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn devclass_get_device "devclass_t dc" "int unit" +.Sh DESCRIPTION +This function retrieves the device instance with the given unit number +and returns it. +.Sh RETURN VALUES +If the device exists, it is returned, otherwise NULL is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/devclass_get_device.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_get_devices.9 =================================================================== --- user/imp/camdoc/devclass_get_devices.9 (nonexistent) +++ user/imp/camdoc/devclass_get_devices.9 (revision 296049) @@ -0,0 +1,60 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 19, 2005 +.Dt DEVCLASS_GET_DEVICES 9 +.Os +.Sh NAME +.Nm devclass_get_devices +.Nd get a list of devices in a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_devices "devclass_t dc" "device_t **devlistp" "int *devcountp" +.Sh DESCRIPTION +Retrieve a list of all device instances currently in the devclass and +return the list in +.Fa *devlistp +and the count in +.Fa *devcountp . +The memory allocated for the list should be freed using +.Fn free "*devlistp" "M_TEMP" , +even if +.Fa *devcountp +is 0. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/devclass_get_devices.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_get_drivers.9 =================================================================== --- user/imp/camdoc/devclass_get_drivers.9 (nonexistent) +++ user/imp/camdoc/devclass_get_drivers.9 (revision 296049) @@ -0,0 +1,60 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2005 Nate Lawson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd May 19, 2005 +.Dt DEVCLASS_GET_DRIVERS 9 +.Os +.Sh NAME +.Nm devclass_get_drivers +.Nd "get a list of drivers in a devclass" +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn devclass_get_drivers "devclass_t dc" "driver_t ***listp" "int *countp" +.Sh DESCRIPTION +Retrieve a list of pointers to all driver instances currently in the +devclass and return the list in +.Fa *listp +and the number of drivers in the list in +.Fa *countp . +The memory allocated for the list should be freed using +.Fn free *listp M_TEMP , +even if +.Fa *countp +is 0. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Nate Lawson . Property changes on: user/imp/camdoc/devclass_get_drivers.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_get_name.9 =================================================================== --- user/imp/camdoc/devclass_get_name.9 (nonexistent) +++ user/imp/camdoc/devclass_get_name.9 (revision 296049) @@ -0,0 +1,49 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVCLASS_GET_NAME 9 +.Os +.Sh NAME +.Nm devclass_get_name +.Nd access the name of a devclass +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft const char * +.Fn devclass_get_name "devclass_t dc" +.Sh DESCRIPTION +Return the name of a devclass. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/devclass_get_name.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/devclass_get_softc.9 =================================================================== --- user/imp/camdoc/devclass_get_softc.9 (nonexistent) +++ user/imp/camdoc/devclass_get_softc.9 (revision 296049) @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVCLASS_GET_SOFTC 9 +.Os +.Sh NAME +.Nm devclass_get_softc +.Nd translate unit number to driver private structure +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void * +.Fn devclass_get_softc "devclass_t dc" "int unit" +.Sh DESCRIPTION +This function retrieves the driver private instance variables for the +device with the given unit number and returns it. +.Sh RETURN VALUES +If the device exists, its driver-private variables are returned, +otherwise NULL is returned. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/devclass_get_softc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device.9 =================================================================== --- user/imp/camdoc/device.9 (nonexistent) +++ user/imp/camdoc/device.9 (revision 296049) @@ -0,0 +1,104 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE 9 +.Os +.Sh NAME +.Nm device +.Nd an abstract representation of a device +.Sh SYNOPSIS +.Vt typedef struct device *device_t ; +.Sh DESCRIPTION +The device object represents a piece of hardware attached to the +system such as an expansion card, the bus which that card is plugged +into, disk drives attached to the expansion card etc. +The system defines one device, +.Va root_bus +and all other devices are created dynamically during +autoconfiguration. +Normally devices representing top-level busses in +the system (ISA, PCI etc.) will be attached directly to +.Va root_bus +and other devices will be added as children of their relevant bus. +.Pp +The devices in a system form a tree. +All devices except +.Va root_bus +have a parent (see +.Xr device_get_parent 9 ) . +In addition, any device can have children attached to it (see +.Xr device_add_child 9 , +.Xr device_add_child_ordered 9 , +.Xr device_find_child 9 , +.Xr device_get_children 9 , +and +.Xr device_delete_child 9 ) . +.Pp +A device which has been successfully probed and attached to the +system will also have a driver (see +.Xr device_get_driver 9 +and +.Xr driver 9 ) +and a devclass (see +.Xr device_get_devclass 9 +and +.Xr devclass 9 ) . +Various other attributes of the device include a unit number (see +.Xr device_get_unit 9 ) , +verbose description (normally supplied by the driver, see +.Xr device_set_desc 9 +and +.Xr device_get_desc 9 ) , +a set of bus-specific variables (see +.Xr device_get_ivars 9 ) +and a set of driver-specific variables (see +.Xr device_get_softc 9 ) . +.Pp +Devices can be in one of several states: +.Bl -tag -width DS_NOTPRESENT +.It Dv DS_NOTPRESENT +the device has not been probed for existence or the probe failed +.It Dv DS_ALIVE +the device probe succeeded but not yet attached +.It Dv DS_ATTACHED +the device has been successfully attached +.It Dv DS_BUSY +the device is currently open +.El +.Pp +The current state of the device can be determined by calling +.Xr device_get_state 9 . +.Sh SEE ALSO +.Xr devclass 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/vfs_unmountall.9 =================================================================== --- user/imp/camdoc/vfs_unmountall.9 (nonexistent) +++ user/imp/camdoc/vfs_unmountall.9 (revision 296049) @@ -0,0 +1,47 @@ +.\" Copyright (c) 2001 Chris Costello +.\" 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 26, 2001 +.Dt VFS_UNMOUNTALL 9 +.Os +.Sh NAME +.Nm vfs_unmountall +.Nd unmount all file systems +.Sh SYNOPSIS +.In sys/param.h +.In sys/mount.h +.Ft void +.Fn vfs_unmountall "void" +.Sh DESCRIPTION +The +.Nm +function, +run only at system shutdown, +unmounts all mounted file systems +from most recent to oldest +in order to avoid handling dependencies. +.Sh SEE ALSO +.Xr boot 9 Property changes on: user/imp/camdoc/vfs_unmountall.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUS_PRINT_CHILD.9 =================================================================== --- user/imp/camdoc/BUS_PRINT_CHILD.9 (nonexistent) +++ user/imp/camdoc/BUS_PRINT_CHILD.9 (revision 296049) @@ -0,0 +1,64 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd January 6, 2005 +.Dt BUS_PRINT_CHILD 9 +.Os +.Sh NAME +.Nm BUS_PRINT_CHILD +.Nd print information about a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn BUS_PRINT_CHILD "device_t dev" "device_t child" +.Sh DESCRIPTION +The +.Fn BUS_PRINT_CHILD +method +is called from system code which prints out a description of a +device. +It should describe the attachment that the child has with +the parent. +For instance the TurboLaser bus prints which node the +device is attached to. +Please see +.Xr bus_generic_print_child 9 +for more information regarding the proper formatting of the messages +printed by +.Fn BUS_PRINT_CHILD . +.Sh RETURN VALUES +The number of characters output. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/BUS_PRINT_CHILD.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/microseq.9 =================================================================== --- user/imp/camdoc/microseq.9 (nonexistent) +++ user/imp/camdoc/microseq.9 (revision 296049) @@ -0,0 +1,493 @@ +.\" Copyright (c) 1998, 1999, Nicolas Souchu +.\" 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 6, 1998 +.Dt MICROSEQ 9 +.Os +.Sh NAME +.Nm microseq +.Nd ppbus microsequencer developer's guide +.Sh SYNOPSIS +.In sys/types.h +.In dev/ppbus/ppbconf.h +.In dev/ppbus/ppb_msq.h +.Sh DESCRIPTION +See +.Xr ppbus 4 +for ppbus description and general info about the microsequencer. +.Pp +The purpose of this document is to encourage developers to use the +microsequencer mechanism in order to have: +.Bl -enum -offset indent +.It +a uniform programming model +.It +efficient code +.El +.Pp +Before using microsequences, you are encouraged to look at +.Xr ppc 4 +microsequencer implementation and an example of how using it in +.Xr vpo 4 . +.Sh PPBUS register model +.Ss Background +The parallel port model chosen for ppbus is the PC parallel port model. +Thus, any register described later has the same semantic than its counterpart +in a PC parallel port. +For more info about ISA/ECP programming, get the +Microsoft standard referenced as "Extended Capabilities Port Protocol and +ISA interface Standard". +Registers described later are standard parallel port +registers. +.Pp +Mask macros are defined in the standard ppbus include files for each valid +bit of parallel port registers. +.Ss Data register +In compatible or nibble mode, writing to this register will drive data to the +parallel port data lines. +In any other mode, drivers may be tri-stated by +setting the direction bit (PCD) in the control register. +Reads to this register +return the value on the data lines. +.Ss Device status register +This read-only register reflects the inputs on the parallel port interface. +.Pp +.Bl -column "Bit" "Name" "Description" -compact +.It Em Bit Ta Em Name Ta Em Description +.It 7 Ta nBUSY Ta "inverted version of parallel port Busy signal" +.It 6 Ta nACK Ta "version of parallel port nAck signal" +.It 5 Ta PERROR Ta "version of parallel port PERROR signal" +.It 4 Ta SELECT Ta "version of parallel port Select signal" +.It 3 Ta nFAULT Ta "version of parallel port nFault signal" +.El +.Pp +Others are reserved and return undefined result when read. +.Ss Device control register +This register directly controls several output signals as well as enabling +some functions. +.Pp +.Bl -column "Bit" "Name " "Description" -compact +.It Em Bit Ta Em Name Ta Em Description +.It 5 Ta PCD Ta "direction bit in extended modes" +.It 4 Ta IRQENABLE Ta "1 enables an interrupt on the rising edge of nAck" +.It 3 Ta SELECTIN Ta "inverted and driven as parallel port nSelectin signal" +.It 2 Ta nINIT Ta "driven as parallel port nInit signal" +.It 1 Ta AUTOFEED Ta "inverted and driven as parallel port nAutoFd signal" +.It 0 Ta STROBE Ta "inverted and driven as parallel port nStrobe signal" +.El +.Sh MICROINSTRUCTIONS +.Ss Description +.Em Microinstructions +are either parallel port accesses, program iterations, submicrosequence or +C calls. +The parallel port must be considered as the logical model described in +.Xr ppbus 4 . +.Pp +Available microinstructions are: +.Bd -literal +#define MS_OP_GET 0 /* get , */ +#define MS_OP_PUT 1 /* put , */ +#define MS_OP_RFETCH 2 /* rfetch , , */ +#define MS_OP_RSET 3 /* rset , , */ +#define MS_OP_RASSERT 4 /* rassert , */ +#define MS_OP_DELAY 5 /* delay */ +#define MS_OP_SET 6 /* set */ +#define MS_OP_DBRA 7 /* dbra */ +#define MS_OP_BRSET 8 /* brset , */ +#define MS_OP_BRCLEAR 9 /* brclear , */ +#define MS_OP_RET 10 /* ret */ +#define MS_OP_C_CALL 11 /* c_call , */ +#define MS_OP_PTR 12 /* ptr */ +#define MS_OP_ADELAY 13 /* adelay */ +#define MS_OP_BRSTAT 14 /* brstat , , */ +#define MS_OP_SUBRET 15 /* subret */ +#define MS_OP_CALL 16 /* call */ +#define MS_OP_RASSERT_P 17 /* rassert_p , */ +#define MS_OP_RFETCH_P 18 /* rfetch_p , , */ +#define MS_OP_TRIG 19 /* trigger , , */ +.Ed +.Ss Execution context +The +.Em execution context +of microinstructions is: +.Bl -bullet -offset indent +.It +the +.Em program counter +which points to the next microinstruction to execute either in the main +microsequence or in a subcall +.It +the current value of +.Em ptr +which points to the next char to send/receive +.It +the current value of the internal +.Em branch register +.El +.Pp +This data is modified by some of the microinstructions, not all. +.Ss MS_OP_GET and MS_OP_PUT +are microinstructions used to do either predefined standard IEEE1284-1994 +transfers or programmed non-standard io. +.Ss MS_OP_RFETCH - Register FETCH +is used to retrieve the current value of a parallel port register, apply a +mask and save it in a buffer. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +character mask +.It +pointer to the buffer +.El +.Pp +Predefined macro: MS_RFETCH(reg,mask,ptr) +.Ss MS_OP_RSET - Register SET +is used to assert/clear some bits of a particular parallel port register, +two masks are applied. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +mask of bits to assert +.It +mask of bits to clear +.El +.Pp +Predefined macro: MS_RSET(reg,assert,clear) +.Ss MS_OP_RASSERT - Register ASSERT +is used to assert all bits of a particular parallel port register. +.Pp +Parameters: +.Bl -enum -offset indent +.It +register +.It +byte to assert +.El +.Pp +Predefined macro: MS_RASSERT(reg,byte) +.Ss MS_OP_DELAY - microsecond DELAY +is used to delay the execution of the microsequence. +.Pp +Parameter: +.Bl -enum -offset indent +.It +delay in microseconds +.El +.Pp +Predefined macro: MS_DELAY(delay) +.Ss MS_OP_SET - SET internal branch register +is used to set the value of the internal branch register. +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer value +.El +.Pp +Predefined macro: MS_SET(accum) +.Ss MS_OP_DBRA - \&Do BRAnch +is used to branch if internal branch register decremented by one result value +is positive. +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_DBRA(offset) +.Ss MS_OP_BRSET - BRanch on SET +is used to branch if some of the status register bits of the parallel port +are set. +.Pp +Parameter: +.Bl -enum -offset indent +.It +bits of the status register +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRSET(mask,offset) +.Ss MS_OP_BRCLEAR - BRanch on CLEAR +is used to branch if some of the status register bits of the parallel port +are cleared. +.Pp +Parameter: +.Bl -enum -offset indent +.It +bits of the status register +.It +integer offset in the current executed (sub)microsequence. +Offset is added to +the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRCLEAR(mask,offset) +.Ss MS_OP_RET - RETurn +is used to return from a microsequence. +This instruction is mandatory. +This +is the only way for the microsequencer to detect the end of the microsequence. +The return code is returned in the integer pointed by the (int *) parameter +of the ppb_MS_microseq(). +.Pp +Parameter: +.Bl -enum -offset indent +.It +integer return code +.El +.Pp +Predefined macro: MS_RET(code) +.Ss MS_OP_C_CALL - C function CALL +is used to call C functions from microsequence execution. +This may be useful +when a non-standard i/o is performed to retrieve a data character from the +parallel port. +.Pp +Parameter: +.Bl -enum -offset indent +.It +the C function to call +.It +the parameter to pass to the function call +.El +.Pp +The C function shall be declared as a +.Ft int(*)(void *p, char *ptr) . +The ptr parameter is the current position in the buffer currently scanned. +.Pp +Predefined macro: MS_C_CALL(func,param) +.Ss MS_OP_PTR - initialize internal PTR +is used to initialize the internal pointer to the currently scanned buffer. +This pointer is passed to any C call (see above). +.Pp +Parameter: +.Bl -enum -offset indent +.It +pointer to the buffer that shall be accessed by xxx_P() microsequence calls. +Note that this pointer is automatically incremented during xxx_P() calls +.El +.Pp +Predefined macro: MS_PTR(ptr) +.Ss MS_OP_ADELAY - do an Asynchronous DELAY +is used to make a tsleep() during microsequence execution. +The tsleep is +executed at PPBPRI level. +.Pp +Parameter: +.Bl -enum -offset indent +.It +delay in ms +.El +.Pp +Predefined macro: MS_ADELAY(delay) +.Ss MS_OP_BRSTAT - BRanch on STATe +is used to branch on status register state condition. +.Pp +Parameter: +.Bl -enum -offset indent +.It +mask of asserted bits. +Bits that shall be asserted in the status register +are set in the mask +.It +mask of cleared bits. +Bits that shall be cleared in the status register +are set in the mask +.It +integer offset in the current executed (sub)microsequence. +Offset is added +to the index of the next microinstruction to execute. +.El +.Pp +Predefined macro: MS_BRSTAT(asserted_bits,clear_bits,offset) +.Ss MS_OP_SUBRET - SUBmicrosequence RETurn +is used to return from the submicrosequence call. +This action is mandatory +before a RET call. +Some microinstructions (PUT, GET) may not be callable +within a submicrosequence. +.Pp +No parameter. +.Pp +Predefined macro: MS_SUBRET() +.Ss MS_OP_CALL - submicrosequence CALL +is used to call a submicrosequence. +A submicrosequence is a microsequence with +a SUBRET call. +Parameter: +.Bl -enum -offset indent +.It +the submicrosequence to execute +.El +.Pp +Predefined macro: MS_CALL(microseq) +.Ss MS_OP_RASSERT_P - Register ASSERT from internal PTR +is used to assert a register with data currently pointed by the internal PTR +pointer. +Parameter: +.Bl -enum -offset indent +.It +amount of data to write to the register +.It +register +.El +.Pp +Predefined macro: MS_RASSERT_P(iter,reg) +.Ss MS_OP_RFETCH_P - Register FETCH to internal PTR +is used to fetch data from a register. +Data is stored in the buffer currently +pointed by the internal PTR pointer. +Parameter: +.Bl -enum -offset indent +.It +amount of data to read from the register +.It +register +.It +mask applied to fetched data +.El +.Pp +Predefined macro: MS_RFETCH_P(iter,reg,mask) +.Ss MS_OP_TRIG - TRIG register +is used to trigger the parallel port. +This microinstruction is intended to +provide a very efficient control of the parallel port. +Triggering a register +is writing data, wait a while, write data, wait a while... +This allows to +write magic sequences to the port. +Parameter: +.Bl -enum -offset indent +.It +amount of data to read from the register +.It +register +.It +size of the array +.It +array of unsigned chars. +Each couple of u_chars define the data to write to +the register and the delay in us to wait. +The delay is limited to 255 us to +simplify and reduce the size of the array. +.El +.Pp +Predefined macro: MS_TRIG(reg,len,array) +.Sh MICROSEQUENCES +.Ss C structures +.Bd -literal +union ppb_insarg { + int i; + char c; + void *p; + int (* f)(void *, char *); +}; + +struct ppb_microseq { + int opcode; /* microins. opcode */ + union ppb_insarg arg[PPB_MS_MAXARGS]; /* arguments */ +}; +.Ed +.Ss Using microsequences +To instantiate a microsequence, just declare an array of ppb_microseq +structures and initialize it as needed. +You may either use predefined macros +or code directly your microinstructions according to the ppb_microseq +definition. +For example, +.Bd -literal + struct ppb_microseq select_microseq[] = { + + /* parameter list + */ + #define SELECT_TARGET MS_PARAM(0, 1, MS_TYP_INT) + #define SELECT_INITIATOR MS_PARAM(3, 1, MS_TYP_INT) + + /* send the select command to the drive */ + MS_DASS(MS_UNKNOWN), + MS_CASS(H_nAUTO | H_nSELIN | H_INIT | H_STROBE), + MS_CASS( H_AUTO | H_nSELIN | H_INIT | H_STROBE), + MS_DASS(MS_UNKNOWN), + MS_CASS( H_AUTO | H_nSELIN | H_nINIT | H_STROBE), + + /* now, wait until the drive is ready */ + MS_SET(VP0_SELTMO), +/* loop: */ MS_BRSET(H_ACK, 2 /* ready */), + MS_DBRA(-2 /* loop */), +/* error: */ MS_RET(1), +/* ready: */ MS_RET(0) + }; +.Ed +.Pp +Here, some parameters are undefined and must be filled before executing +the microsequence. +In order to initialize each microsequence, one +should use the ppb_MS_init_msq() function like this: +.Bd -literal + ppb_MS_init_msq(select_microseq, 2, + SELECT_TARGET, 1 << target, + SELECT_INITIATOR, 1 << initiator); +.Ed +.Pp +and then execute the microsequence. +.Ss The microsequencer +The microsequencer is executed either at ppbus or adapter level (see +.Xr ppbus 4 +for info about ppbus system layers). +Most of the microsequencer is executed +at ppc level to avoid ppbus to adapter function call overhead. +But some +actions like deciding whereas the transfer is IEEE1284-1994 compliant are +executed at ppbus layer. +.Sh SEE ALSO +.Xr ppbus 4 , +.Xr ppc 4 , +.Xr vpo 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 3.0 . +.Sh AUTHORS +This +manual page was written by +.An Nicolas Souchu . +.Sh BUGS +Only one level of submicrosequences is allowed. +.Pp +When triggering the port, maximum delay allowed is 255 us. Property changes on: user/imp/camdoc/microseq.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/boot.9 =================================================================== --- user/imp/camdoc/boot.9 (nonexistent) +++ user/imp/camdoc/boot.9 (revision 296049) @@ -0,0 +1,100 @@ +.\" $NetBSD: boot.9,v 1.2 1996/09/24 07:01:26 ghudson Exp $ +.\" +.\" Copyright (c) 1997 +.\" Mike Pritchard. All rights reserved. +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd February 14, 1997 +.Dt BOOT 9 +.Os +.Sh NAME +.Nm boot +.Nd halt or reboot the system +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.In sys/reboot.h +.Ft void +.Fn boot "int howto" +.Sh DESCRIPTION +The +.Fn boot +function handles final system shutdown, and either halts or reboots +the system. +The exact action to be taken is determined by the flags passed in +.Fa howto +and by whether or not the system has finished autoconfiguration. +.Pp +If the system has finished autoconfiguration, +.Fn boot +does the following: +.Bl -enum -offset indent +.It +If this is the first invocation of +.Fn boot +and the +.Dv RB_NOSYNC +flag is not set in +.Fa howto , +syncs and unmounts the system disks by calling +.Xr vfs_unmountall 9 . +.It +Disables interrupts. +.It +If rebooting after a crash (i.e., if +.Dv RB_DUMP +is set in +.Fa howto , +but +.Dv RB_HALT +is not), saves a system crash dump. +.It +Runs any shutdown hooks previously registered. +.It +Prints a message indicating that the system is about to be halted +or rebooted. +.It +If +.Dv RB_HALT +is set in +.Fa howto , +halts the system. +Otherwise, reboots the system. +.El +.Pp +If the system has not finished autoconfiguration, +.Fn boot +runs any shutdown hooks previously registered, +prints a message, and halts the system. +.Sh SEE ALSO +.Xr vfs_unmountall 9 Property changes on: user/imp/camdoc/boot.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_name.9 =================================================================== --- user/imp/camdoc/device_get_name.9 (nonexistent) +++ user/imp/camdoc/device_get_name.9 (revision 296049) @@ -0,0 +1,56 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 21, 2003 +.Dt DEVICE_GET_NAME 9 +.Os +.Sh NAME +.Nm device_get_name , device_get_nameunit +.Nd access the name of a device's device class or instance +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft const char * +.Fn device_get_name "device_t dev" +.Ft const char * +.Fn device_get_nameunit "device_t dev" +.Sh DESCRIPTION +The +.Fn device_get_name +function returns the name of the device's device class. +.Pp +The +.Fn device_get_nameunit +function returns the name of the device's instance. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh . Property changes on: user/imp/camdoc/device_get_name.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/BUS_READ_IVAR.9 =================================================================== --- user/imp/camdoc/BUS_READ_IVAR.9 (nonexistent) +++ user/imp/camdoc/BUS_READ_IVAR.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt BUS_READ_IVAR 9 +.Os +.Sh NAME +.Nm BUS_READ_IVAR , +.Nm BUS_WRITE_IVAR +.Nd manipulate bus-specific device instance variables +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn BUS_READ_IVAR "device_t dev" "device_t child" "int index" "uintptr_t *result" +.Ft int +.Fn BUS_WRITE_IVAR "device_t dev" "device_t child" "int index" "uintptr_t value" +.Sh DESCRIPTION +These two methods manage a bus specific set of instance variables of +a child device. +The intention is that each different type of bus +defines a set of appropriate instance variables (such as ports and +irqs for ISA bus etc.) +.Pp +This information could be given to the child device as a struct but +that makes it hard for a bus to add or remove variables without +forcing an edit and recompile for all drivers which may not be +possible for vendor supplied binary drivers. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/BUS_READ_IVAR.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_delete_child.9 =================================================================== --- user/imp/camdoc/device_delete_child.9 (nonexistent) +++ user/imp/camdoc/device_delete_child.9 (revision 296049) @@ -0,0 +1,56 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_DELETE_CHILD 9 +.Os +.Sh NAME +.Nm device_delete_child +.Nd delete a child from a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_delete_child "device_t dev" "device_t child" +.Sh DESCRIPTION +The specified device is removed from +.Fa dev +and deleted. +If the device is currently attached, it is first detached (see +.Xr DEVICE_ATTACH 9 +and +.Xr DEVICE_DETACH 9 ) . +.Sh RETURN VALUES +Zero is returned on success, otherwise an error is returned. +.Sh SEE ALSO +.Xr device_add_child 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_delete_child.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_enable.9 =================================================================== --- user/imp/camdoc/device_enable.9 (nonexistent) +++ user/imp/camdoc/device_enable.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_ENABLE 9 +.Os +.Sh NAME +.Nm device_enable , +.Nm device_disable , +.Nm device_is_enabled +.Nd manipulate device enabled flag +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_enable "device_t dev" +.Ft void +.Fn device_disable "device_t dev" +.Ft int +.Fn device_is_enabled "device_t dev" +.Sh DESCRIPTION +Each device has an enabled flag associated with it. +A device is +enabled by default when it is created but may be disabled (for +instance to prevent a destructive or time consuming probe attempt). +To disable a device, call +.Fn device_disable , +to re-enable it, call +.Fn device_enable +and to test to see if a device is enabled, call +.Fn device_is_enabled . +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_enable.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_devclass.9 =================================================================== --- user/imp/camdoc/device_get_devclass.9 (nonexistent) +++ user/imp/camdoc/device_get_devclass.9 (revision 296049) @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_GET_DEVCLASS 9 +.Os +.Sh NAME +.Nm device_get_devclass +.Nd access the devclass of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft devclass_t +.Fn device_get_devclass "device_t dev" +.Sh DESCRIPTION +The current devclass associated with the device is returned. +If the device has no devclass, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr devclass 9 , +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_get_devclass.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_driver.9 =================================================================== --- user/imp/camdoc/device_get_driver.9 (nonexistent) +++ user/imp/camdoc/device_get_driver.9 (revision 296049) @@ -0,0 +1,52 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_GET_DRIVER 9 +.Os +.Sh NAME +.Nm device_get_driver +.Nd access the current driver of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft driver_t * +.Fn device_get_driver "device_t dev" +.Sh DESCRIPTION +The current driver associated with the device is returned. +If the device has no driver, +.Dv NULL +is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_get_driver.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_ivars.9 =================================================================== --- user/imp/camdoc/device_get_ivars.9 (nonexistent) +++ user/imp/camdoc/device_get_ivars.9 (revision 296049) @@ -0,0 +1,64 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_GET_IVARS 9 +.Os +.Sh NAME +.Nm device_get_ivars , +.Nm device_set_ivars +.Nd access bus private variables +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft "void *" +.Fn device_get_ivars "device_t dev" +.Ft void +.Fn device_set_ivars "device_t dev" "void *ivar" +.Sh DESCRIPTION +The +.Fn device_get_ivars +function returns the bus-specific instance variables of a device. +.Pp +The +.Fn device_set_ivars +function sets the bus-specific instance variables of a device. +.Pp +Typically, only bus drivers will use these functions. +The kernel assumes that the bus driver will manage this memory, and no +automatic memory allocation or deallocation happens. +Client drivers should access ivars through the +.Xr BUS_READ_IVAR 9 +interface instead. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_get_ivars.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_parent.9 =================================================================== --- user/imp/camdoc/device_get_parent.9 (nonexistent) +++ user/imp/camdoc/device_get_parent.9 (revision 296049) @@ -0,0 +1,50 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 2003 M. Warner Losh +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 21, 2003 +.Dt DEVICE_GET_PARENT 9 +.Os +.Sh NAME +.Nm device_get_parent +.Nd return the device's parent +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_t +.Fn device_get_parent "device_t dev" +.Sh DESCRIPTION +The +.Fn device_get_parent +function returns the name of the device's parent device. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Warner Losh . Property changes on: user/imp/camdoc/device_get_parent.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_state.9 =================================================================== --- user/imp/camdoc/device_get_state.9 (nonexistent) +++ user/imp/camdoc/device_get_state.9 (revision 296049) @@ -0,0 +1,99 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_GET_STATE 9 +.Os +.Sh NAME +.Nm device_get_state , +.Nm device_busy , +.Nm device_unbusy , +.Nm device_is_alive , +.Nm device_is_attached +.Nd manipulate device state +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft device_state_t +.Fn device_get_state "device_t dev" +.Ft void +.Fn device_busy "device_t dev" +.Ft void +.Fn device_unbusy "device_t dev" +.Ft int +.Fn device_is_alive "device_t dev" +.Ft int +.Fn device_is_attached "device_t dev" +.Sh DESCRIPTION +The current state of a device is accessed by calling +.Fn device_get_state +which returns +.Dv DS_NOTPRESENT , +.Dv DS_ALIVE , +.Dv DS_ATTACHED +or +.Dv DS_BUSY +(described in +.Xr device 9 ) . +To test see if a device was successfully probed, call +.Fn device_is_alive +which simply returns if the state is greater or equal to +.Dv DS_ALIVE . +To test see if a device was successfully attached, call +.Fn device_is_attached +which simply returns if the state is greater or equal to +.Dv DS_ATTACHED . +.Pp +Each device has a busy count which is incremented when +.Fn device_busy +is called and decremented when +.Fn device_unbusy +is called. +Both routines return an error if the device state is less than +.Dv DS_ATTACHED . +.Pp +When +.Fn device_busy +is called on a device in the +.Dv DS_ATTACHED +state, the device changes to the +.Dv DS_BUSY +state. +When +.Fn device_unbusy +is called and after decrementing, the busy count for the device is +zero, the device changes to the +.Dv DS_ATTACHED +state. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_get_state.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_get_unit.9 =================================================================== --- user/imp/camdoc/device_get_unit.9 (nonexistent) +++ user/imp/camdoc/device_get_unit.9 (revision 296049) @@ -0,0 +1,48 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_GET_UNIT 9 +.Os +.Sh NAME +.Nm device_get_unit +.Nd access the unit number of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_get_unit "device_t dev" +.Sh DESCRIPTION +Return the unit number of the device. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_get_unit.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_probe_and_attach.9 =================================================================== --- user/imp/camdoc/device_probe_and_attach.9 (nonexistent) +++ user/imp/camdoc/device_probe_and_attach.9 (revision 296049) @@ -0,0 +1,61 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_PROBE_AND_ATTACH 9 +.Os +.Sh NAME +.Nm device_probe_and_attach +.Nd initialise a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_probe_and_attach "device_t dev" +.Sh DESCRIPTION +This function is called during autoconfiguration to initialise the +devices in the system. +For each device, the +.Xr DEVICE_PROBE 9 +method of each suitable driver is called and if a probe succeeds, a +description of the device is printed and the +.Xr DEVICE_ATTACH 9 +method is called. +If the device is disabled using +.Xr device_disable 9 +then it will not be probed. +.Sh RETURN VALUES +Zero is returned on success, otherwise an appropriate error is returned. +.Sh SEE ALSO +.Xr device 9 , +.Xr driver 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_probe_and_attach.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_quiet.9 =================================================================== --- user/imp/camdoc/device_quiet.9 (nonexistent) +++ user/imp/camdoc/device_quiet.9 (revision 296049) @@ -0,0 +1,66 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 21, 1999 +.Dt DEVICE_QUIET 9 +.Os +.Sh NAME +.Nm device_quiet , +.Nm device_verbose , +.Nm device_is_quiet +.Nd manipulate device quiet flag +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_quiet "device_t dev" +.Ft void +.Fn device_verbose "device_t dev" +.Ft int +.Fn device_is_quiet "device_t dev" +.Sh DESCRIPTION +Each device has a quiet flag associated with it. +A device is +verbose by default when it is created but may be quieted to prevent +the device identification string to be printed during probe. +To quiet a device, call +.Fn device_quiet , +to re-enable to probe message (to make the message appear again, for +example after a +.Xr device_detach 9 ) +call +.Fn device_verbose . +To test to see if a device is quieted, call +.Fn device_is_quiet . +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_quiet.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_set_desc.9 =================================================================== --- user/imp/camdoc/device_set_desc.9 (nonexistent) +++ user/imp/camdoc/device_set_desc.9 (revision 296049) @@ -0,0 +1,63 @@ +.\" -*- nroff -*- +.\" +.\" Copyright (c) 1998 Doug Rabson +.\" +.\" All rights reserved. +.\" +.\" This program is free software. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE DEVELOPERS ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE DEVELOPERS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 16, 1998 +.Dt DEVICE_SET_DESC 9 +.Os +.Sh NAME +.Nm device_set_desc , +.Nm device_set_desc_copy , +.Nm device_get_desc +.Nd access the description of a device +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft void +.Fn device_set_desc "device_t dev" "const char *desc" +.Ft void +.Fn device_set_desc_copy "device_t dev" "const char *desc" +.Ft const char * +.Fn device_get_desc "device_t dev" +.Sh DESCRIPTION +Manipulate the verbose description of a device. +This description (if +present) is printed as part of the message when it is attached during +autoconfiguration. +The variation +.Fn device_set_desc_copy +is used to set the description if the string passed is a temporary +buffer which will be overwritten. +In this case, the system will copy +the string, otherwise the pointer passed will be used directly. +.Sh SEE ALSO +.Xr device 9 +.Sh AUTHORS +This manual page was written by +.An Doug Rabson . Property changes on: user/imp/camdoc/device_set_desc.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/inittodr.9 =================================================================== --- user/imp/camdoc/inittodr.9 (nonexistent) +++ user/imp/camdoc/inittodr.9 (revision 296049) @@ -0,0 +1,123 @@ +.\" $NetBSD: inittodr.9,v 1.2 1996/03/27 21:16:06 jtc Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd March 22, 1997 +.Dt INITTODR 9 +.Os +.Sh NAME +.Nm inittodr +.Nd initialize system time +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn inittodr "time_t base" +.Sh DESCRIPTION +The +.Fn inittodr +function determines the time and sets the system clock. +It tries to pick the correct time using a set of heuristics that examine +the system's battery backed clock and the time obtained from the root +file system, as given in +.Fa base . +How the +.Fa base +value is obtained will vary depending on the +root file system type. +The heuristics used include: +.Bl -bullet +.It +If the battery-backed clock has a valid time, it is used. +.\" .It +.\" If the battery-backed clock does not have a valid time, and +.\" the time provided in +.\" .Fa base +.\" is within reason, +.\" .Fa base +.\" is used as the current time. +.\" .It +.\" If the battery-backed clock appears invalid, and +.\" .Fa base +.\" appears non-sensical or was not provided (was given as zero), +.\" a arbitrary base (typically some time in the late 1970s) +.\" will be used. +.It +If the battery-backed clock does not have a valid time, +the time provided in +.Fa base +will be used. +.El +.Pp +Once a system time has been determined, it is stored in the +.Va time +variable. +.Sh DIAGNOSTICS +The +.Fn inittodr +function prints diagnostic messages if it has trouble figuring +out the system time. +Conditions that can cause diagnostic messages to be printed include: +.Bl -bullet +.It +The battery-backed clock's time appears nonsensical. +.\" .It +.\" The +.\" .Fa base +.\" time appears nonsensical. +.\" .It +.\" The +.\" .Fa base +.\" time and the battery-backed clock's time differ by a large amount. +.El +.Sh SEE ALSO +.Xr resettodr 9 , +.Xr time 9 +.Sh BUGS +On many systems, +.Fn inittodr +has to convert from +a time expressed in terms of year, month, day, hours, minutes, +and seconds to +.Va time , +expressed in seconds. +Many of the implementations could share code, but do not. +.Pp +Each system's heuristics for picking the correct time are slightly +different. +.Pp +The +.Fx +implementation should do a better job of validating the time provided in +.Fa base +when the battery-backed clock is unusable. +Currently it unconditionally sets the system clock to this value. Property changes on: user/imp/camdoc/inittodr.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/resettodr.9 =================================================================== --- user/imp/camdoc/resettodr.9 (nonexistent) +++ user/imp/camdoc/resettodr.9 (revision 296049) @@ -0,0 +1,62 @@ +.\" $NetBSD: resettodr.9,v 1.1 1995/11/25 21:24:51 perry Exp $ +.\" +.\" Copyright (c) 1994 Christopher G. Demetriou +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Christopher G. Demetriou +.\" for the NetBSD Project. +.\" 3. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 13, 1995 +.Dt RESETTODR 9 +.Os +.Sh NAME +.Nm resettodr +.Nd set battery-backed clock from system time +.Sh SYNOPSIS +.In sys/types.h +.In sys/systm.h +.Ft void +.Fn resettodr "void" +.Sh DESCRIPTION +The +.Fn resettodr +function sets the system's battery-backed clock based on the contents +of the system +.Va time +variable. +.Sh SEE ALSO +.Xr inittodr 9 , +.Xr time 9 +.Sh BUGS +On many systems, +.Fn resettodr +has to convert from +.Va time +to a time expressed in terms of year, month, day, hours, minutes, +and seconds. +Many of the implementations could share code, but do not. Property changes on: user/imp/camdoc/resettodr.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/device_printf.9 =================================================================== --- user/imp/camdoc/device_printf.9 (nonexistent) +++ user/imp/camdoc/device_printf.9 (revision 296049) @@ -0,0 +1,58 @@ +.\" +.\" Copyright (c) 2003 M. Warner Losh +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd April 21, 2003 +.Dt DEVICE_PRINTF 9 +.Os +.Sh NAME +.Nm device_printf +.Nd formatted output conversion +.Sh SYNOPSIS +.In sys/param.h +.In sys/bus.h +.Ft int +.Fn device_printf "device_t dev" "const char *fmt" ... +.Sh DESCRIPTION +The +.Fn device_printf +function is a convenience interface to the +.Xr printf 9 +function. +It outputs the name of the +.Fa dev +device, followed by a colon and a space, and then what +.Xr printf 9 +would print if you passed +.Fa fmt +and the remaining arguments to it. +.Sh RETURN VALUES +The +.Fn device_printf +function returns the number of characters displayed. +.Sh SEE ALSO +.Xr printf 3 , +.Xr printf 9 Property changes on: user/imp/camdoc/device_printf.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc/scheduler.9 =================================================================== --- user/imp/camdoc/scheduler.9 (nonexistent) +++ user/imp/camdoc/scheduler.9 (revision 296049) @@ -0,0 +1,276 @@ +.\" Copyright (c) 2000-2001 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 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 November 3, 2000 +.Dt SCHEDULER 9 +.Os +.Sh NAME +.Nm curpriority_cmp , +.Nm maybe_resched , +.Nm resetpriority , +.Nm roundrobin , +.Nm roundrobin_interval , +.Nm sched_setup , +.Nm schedclock , +.Nm schedcpu , +.Nm setrunnable , +.Nm updatepri +.Nd perform round-robin scheduling of runnable processes +.Sh SYNOPSIS +.In sys/param.h +.In sys/proc.h +.Ft int +.Fn curpriority_cmp "struct proc *p" +.Ft void +.Fn maybe_resched "struct thread *td" +.Ft void +.Fn propagate_priority "struct proc *p" +.Ft void +.Fn resetpriority "struct ksegrp *kg" +.Ft void +.Fn roundrobin "void *arg" +.Ft int +.Fn roundrobin_interval "void" +.Ft void +.Fn sched_setup "void *dummy" +.Ft void +.Fn schedclock "struct thread *td" +.Ft void +.Fn schedcpu "void *arg" +.Ft void +.Fn setrunnable "struct thread *td" +.Ft void +.Fn updatepri "struct thread *td" +.Sh DESCRIPTION +Each process has three different priorities stored in +.Vt "struct proc" : +.Va p_usrpri , +.Va p_nativepri , +and +.Va p_priority . +.Pp +The +.Va p_usrpri +member is the user priority of the process calculated from a process' +estimated CPU time and nice level. +.Pp +The +.Va p_nativepri +member is the saved priority used by +.Fn propagate_priority . +When a process obtains a mutex, its priority is saved in +.Va p_nativepri . +While it holds the mutex, the process's priority may be bumped by another +process that blocks on the mutex. +When the process releases the mutex, then its priority is restored to the +priority saved in +.Va p_nativepri . +.Pp +The +.Va p_priority +member is the actual priority of the process and is used to determine what +.Xr runqueue 9 +it runs on, for example. +.Pp +The +.Fn curpriority_cmp +function compares the cached priority of the currently running process with +process +.Fa p . +If the currently running process has a higher priority, then it will return +a value less than zero. +If the current process has a lower priority, then it will return a value +greater than zero. +If the current process has the same priority as +.Fa p , +then +.Fn curpriority_cmp +will return zero. +The cached priority of the currently running process is updated when a process +resumes from +.Xr tsleep 9 +or returns to userland in +.Fn userret +and is stored in the private variable +.Va curpriority . +.Pp +The +.Fn maybe_resched +function compares the priorities of the current thread and +.Fa td . +If +.Fa td +has a higher priority than the current thread, then a context switch is +needed, and +.Dv KEF_NEEDRESCHED +is set. +.Pp +The +.Fn propagate_priority +looks at the process that owns the mutex +.Fa p +is blocked on. +That process's priority is bumped to the priority of +.Fa p +if needed. +If the process is currently running, then the function returns. +If the process is on a +.Xr runqueue 9 , +then the process is moved to the appropriate +.Xr runqueue 9 +for its new priority. +If the process is blocked on a mutex, its position in the list of +processes blocked on the mutex in question is updated to reflect its new +priority. +Then, the function repeats the procedure using the process that owns the +mutex just encountered. +Note that a process's priorities are only bumped to the priority of the +original process +.Fa p , +not to the priority of the previously encountered process. +.Pp +The +.Fn resetpriority +function recomputes the user priority of the ksegrp +.Fa kg +(stored in +.Va kg_user_pri ) +and calls +.Fn maybe_resched +to force a reschedule of each thread in the group if needed. +.Pp +The +.Fn roundrobin +function is used as a +.Xr timeout 9 +function to force a reschedule every +.Va sched_quantum +ticks. +.Pp +The +.Fn roundrobin_interval +function simply returns the number of clock ticks in between reschedules +triggered by +.Fn roundrobin . +Thus, all it does is return the current value of +.Va sched_quantum . +.Pp +The +.Fn sched_setup +function is a +.Xr SYSINIT 9 +that is called to start the callout driven scheduler functions. +It just calls the +.Fn roundrobin +and +.Fn schedcpu +functions for the first time. +After the initial call, the two functions will propagate themselves by +registering their callout event again at the completion of the respective +function. +.Pp +The +.Fn schedclock +function is called by +.Fn statclock +to adjust the priority of the currently running thread's ksegrp. +It updates the group's estimated CPU time and then adjusts the priority via +.Fn resetpriority . +.Pp +The +.Fn schedcpu +function updates all process priorities. +First, it updates statistics that track how long processes have been in various +process states. +Secondly, it updates the estimated CPU time for the current process such +that about 90% of the CPU usage is forgotten in 5 * load average seconds. +For example, if the load average is 2.00, +then at least 90% of the estimated CPU time for the process should be based +on the amount of CPU time the process has had in the last 10 seconds. +It then recomputes the priority of the process and moves it to the +appropriate +.Xr runqueue 9 +if necessary. +Thirdly, it updates the %CPU estimate used by utilities such as +.Xr ps 1 +and +.Xr top 1 +so that 95% of the CPU usage is forgotten in 60 seconds. +Once all process priorities have been updated, +.Fn schedcpu +calls +.Fn vmmeter +to update various other statistics including the load average. +Finally, it schedules itself to run again in +.Va hz +clock ticks. +.Pp +The +.Fn setrunnable +function is used to change a process's state to be runnable. +The process is placed on a +.Xr runqueue 9 +if needed, and the swapper process is woken up and told to swap the process in +if the process is swapped out. +If the process has been asleep for at least one run of +.Fn schedcpu , +then +.Fn updatepri +is used to adjust the priority of the process. +.Pp +The +.Fn updatepri +function is used to adjust the priority of a process that has been asleep. +It retroactively decays the estimated CPU time of the process for each +.Fn schedcpu +event that the process was asleep. +Finally, it calls +.Fn resetpriority +to adjust the priority of the process. +.Sh SEE ALSO +.Xr mi_switch 9 , +.Xr runqueue 9 , +.Xr sleepqueue 9 , +.Xr tsleep 9 +.Sh BUGS +The +.Va curpriority +variable really should be per-CPU. +In addition, +.Fn maybe_resched +should compare the priority of +.Fa chk +with that of each CPU, and then send an IPI to the processor with the lowest +priority to trigger a reschedule if needed. +.Pp +Priority propagation is broken and is thus disabled by default. +The +.Va p_nativepri +variable is only updated if a process does not obtain a sleep mutex on the +first try. +Also, if a process obtains more than one sleep mutex in this manner, and +had its priority bumped in between, then +.Va p_nativepri +will be clobbered. Property changes on: user/imp/camdoc/scheduler.9 ___________________________________________________________________ Added: svn:keywords ## -0,0 +1 ## +FreeBSD=%H \ No newline at end of property Index: user/imp/camdoc =================================================================== --- user/imp/camdoc (nonexistent) +++ user/imp/camdoc (revision 296049) Property changes on: user/imp/camdoc ___________________________________________________________________ Added: svn:mergeinfo ## -0,0 +0,21 ## Merged /projects/clang-sparc64/share/man/man9:r262258-262612 Merged /projects/pf/head/share/man/man9:r263908 Merged /projects/clang-trunk/share/man/man9:r283596-287505 Merged /projects/release-embedded/share/man/man9:r262314,262504,262510-262511,262580,262660,262662,262700,262713,262774,262786-262788,262790-262792,262798,262802,262808 Merged /projects/building-blocks/share/man/man9:r275142-275144,275556,275558 Merged /projects/collation/share/man/man9:r286424-290491 Merged /projects/largeSMP/share/man/man9:r221273-222812,222815-223757 Merged /projects/head_mfi/share/man/man9:r233621 Merged /vendor/resolver/dist/share/man/man9:r1540-186085 Merged /projects/clang350-import/share/man/man9:r274961-276476 Merged /projects/clang360-import/share/man/man9:r277327-280030 Merged /projects/clang370-import/share/man/man9:r287506-288928 Merged /projects/quota64/share/man/man9:r184125-207707 Merged /projects/clang380-import/share/man/man9:r293006 Merged /projects/lldb-r201577/share/man/man9:r262185-262527 Merged /projects/random_number_generator/share/man/man9:r254613-256243 Merged /projects/mpsutil/share/man/man9:r286179-290100 Merged /user/ngie/bug203673/share/man/man9:r289470-289489 Merged /projects/multi-fibv6/head/share/man/man9:r230929-231848 Merged /projects/elftoolchain/share/man/man9:r260687-261245 Merged /head/share/vt/man/man9:r266839