Index: head/share/man/man5/stab.5 =================================================================== --- head/share/man/man5/stab.5 (revision 315527) +++ head/share/man/man5/stab.5 (revision 315528) @@ -1,217 +1,217 @@ .\" Copyright (c) 1980, 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. .\" .\" @(#)stab.5 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" .Dd June 10, 2010 .Dt STAB 5 .Os .Sh NAME .Nm stab .Nd symbol table types .Sh SYNOPSIS .In stab.h .Sh DESCRIPTION The file .In stab.h defines some of the symbol table .Fa n_type field values for a.out files. -These are the types for permanent symbols (i.e., not local labels, etc.) +These are the types for permanent symbols (i.e., not local labels, etc.\&) used by the old debugger .Em sdb and the Berkeley Pascal compiler .Xr pc 1 . Symbol table entries can be produced by the .Pa .stabs assembler directive. This allows one to specify a double-quote delimited name, a symbol type, one char and one short of information about the symbol, and an unsigned long (usually an address). To avoid having to produce an explicit label for the address field, the .Pa .stabd directive can be used to implicitly address the current location. If no name is needed, symbol table entries can be generated using the .Pa .stabn directive. The loader promises to preserve the order of symbol table entries produced by .Pa .stab directives. As described in .Xr a.out 5 , an element of the symbol table consists of the following structure: .Bd -literal /* * Format of a symbol table entry. */ struct nlist { union { const char *n_name; /* for use when in-core */ long n_strx; /* index into file string table */ } n_un; unsigned char n_type; /* type flag */ char n_other; /* unused */ short n_desc; /* see struct desc, below */ unsigned n_value; /* address or offset or line */ }; .Ed .Pp The low bits of the .Fa n_type field are used to place a symbol into at most one segment, according to the following masks, defined in .In a.out.h . A symbol can be in none of these segments by having none of these segment bits set. .Bd -literal /* * Simple values for n_type. */ #define N_UNDF 0x0 /* undefined */ #define N_ABS 0x2 /* absolute */ #define N_TEXT 0x4 /* text */ #define N_DATA 0x6 /* data */ #define N_BSS 0x8 /* bss */ #define N_EXT 01 /* external bit, or'ed in */ .Ed .Pp The .Fa n_value field of a symbol is relocated by the linker, .Xr ld 1 as an address within the appropriate segment. .Fa N_value fields of symbols not in any segment are unchanged by the linker. In addition, the linker will discard certain symbols, according to rules of its own, unless the .Fa n_type field has one of the following bits set: .Bd -literal /* * Other permanent symbol table entries have some of the N_STAB bits set. * These are given in */ #define N_STAB 0xe0 /* if any of these bits set, don't discard */ .Ed .Pp This allows up to 112 (7 \(** 16) symbol types, split between the various segments. Some of these have already been claimed. The old symbolic debugger, .Em sdb , uses the following n_type values: .Bd -literal #define N_GSYM 0x20 /* global symbol: name,,0,type,0 */ #define N_FNAME 0x22 /* procedure name (f77 kludge): name,,0 */ #define N_FUN 0x24 /* procedure: name,,0,linenumber,address */ #define N_STSYM 0x26 /* static symbol: name,,0,type,address */ #define N_LCSYM 0x28 /* .lcomm symbol: name,,0,type,address */ #define N_RSYM 0x40 /* register sym: name,,0,type,register */ #define N_SLINE 0x44 /* src line: 0,,0,linenumber,address */ #define N_SSYM 0x60 /* structure elt: name,,0,type,struct_offset */ #define N_SO 0x64 /* source file name: name,,0,0,address */ #define N_LSYM 0x80 /* local sym: name,,0,type,offset */ #define N_SOL 0x84 /* #included file name: name,,0,0,address */ #define N_PSYM 0xa0 /* parameter: name,,0,type,offset */ #define N_ENTRY 0xa4 /* alternate entry: name,linenumber,address */ #define N_LBRAC 0xc0 /* left bracket: 0,,0,nesting level,address */ #define N_RBRAC 0xe0 /* right bracket: 0,,0,nesting level,address */ #define N_BCOMM 0xe2 /* begin common: name,, */ #define N_ECOMM 0xe4 /* end common: name,, */ #define N_ECOML 0xe8 /* end common (local name): ,,address */ #define N_LENG 0xfe /* second stab entry with length information */ .Ed .Pp where the comments give .Em sdb conventional use for .Pa .stab .Fa s and the .Fa n_name , .Fa n_other , .Fa n_desc , and .Fa n_value fields of the given .Fa n_type . .Em Sdb uses the .Fa n_desc field to hold a type specifier in the form used by the Portable C Compiler, .Xr cc 1 ; see the header file .Pa pcc.h for details on the format of these type values. .Pp The Berkeley Pascal compiler, .Xr pc 1 , uses the following .Fa n_type value: .Bd -literal #define N_PC 0x30 /* global pascal symbol: name,,0,subtype,line */ .Ed .Pp and uses the following subtypes to do type checking across separately compiled files: .Bd -unfilled -offset indent 1 source file name 2 included file name 3 global label 4 global constant 5 global type 6 global variable 7 global function 8 global procedure 9 external function 10 external procedure 11 library variable 12 library routine .Ed .Sh SEE ALSO .Xr as 1 , .Xr ld 1 , .Xr a.out 5 .Sh HISTORY The .Nm file appeared in .Bx 4.0 . .Sh BUGS More basic types are needed. Index: head/share/man/man9/ieee80211.9 =================================================================== --- head/share/man/man9/ieee80211.9 (revision 315527) +++ head/share/man/man9/ieee80211.9 (revision 315528) @@ -1,568 +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.) +(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 Index: head/share/man/man9/ieee80211_vap.9 =================================================================== --- head/share/man/man9/ieee80211_vap.9 (revision 315527) +++ head/share/man/man9/ieee80211_vap.9 (revision 315528) @@ -1,154 +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.) +(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 Index: head/share/man/man9/taskqueue.9 =================================================================== --- head/share/man/man9/taskqueue.9 (revision 315527) +++ head/share/man/man9/taskqueue.9 (revision 315528) @@ -1,492 +1,492 @@ .\" -*- 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 March 1, 2016 .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_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 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. This function returns -1 if the task is being drained. Otherwise, the number of pending calls is returned. .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.) +(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. .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 . Index: head/share/man/man9/vnode.9 =================================================================== --- head/share/man/man9/vnode.9 (revision 315527) +++ head/share/man/man9/vnode.9 (revision 315528) @@ -1,197 +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.) +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 .