Index: stable/10/share/man/man4/cxgbe.4 =================================================================== --- stable/10/share/man/man4/cxgbe.4 (revision 299385) +++ stable/10/share/man/man4/cxgbe.4 (revision 299386) @@ -1,329 +1,329 @@ .\" Copyright (c) 2011-2014, Chelsio 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. Neither the name of the Chelsio Inc 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 OWNER 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. .\" .\" * Other names and brands may be claimed as the property of others. .\" .\" $FreeBSD$ .\" .Dd March 20, 2014 .Dt CXGBE 4 .Os .Sh NAME .Nm cxgbe .Nd "Chelsio T4 and T5 based 40Gb, 10Gb, and 1Gb Ethernet adapter driver" .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device cxgbe" .Ed .Pp To load the driver as a module at boot time, place the following lines in .Xr loader.conf 5 : .Bd -literal -offset indent t4fw_cfg_load="YES" t5fw_cfg_load="YES" if_cxgbe_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for PCI Express Ethernet adapters based on the Chelsio Terminator 4 and Terminator 5 ASICs (T4 and T5). The driver supports Jumbo Frames, Transmit/Receive checksum offload, TCP segmentation offload (TSO), Large Receive Offload (LRO), VLAN tag insertion/extraction, VLAN checksum offload, VLAN TSO, and Receive Side Steering (RSS). For further hardware information and questions related to hardware requirements, see .Pa http://www.chelsio.com/ . .Pp Note that ports of T5 cards are named cxl and attach to a t5nex parent device (in contrast to ports named cxgbe that attach to a t4nex parent for a T4 card). Loader tunables with the hw.cxgbe prefix apply to both T4 and T5 cards. The sysctl MIBs are at dev.t5nex and dev.cxl for T5 cards and at dev.t4nex and dev.cxgbe for T4 cards. .Pp For more information on configuring this device, see .Xr ifconfig 8 . .Sh HARDWARE The .Nm driver supports 40Gb, 10Gb and 1Gb Ethernet adapters based on the T5 ASIC (ports will be named cxl): .Pp .Bl -bullet -compact .It Chelsio T580-CR .It Chelsio T580-LP-CR .It Chelsio T580-LP-SO-CR .It Chelsio T560-CR .It Chelsio T540-CR .It Chelsio T540-LP-CR .It Chelsio T522-CR .It Chelsio T520-LL-CR .It Chelsio T520-CR .It Chelsio T520-SO .It Chelsio T520-BT .It Chelsio T504-BT .El .Pp The .Nm driver supports 10Gb and 1Gb Ethernet adapters based on the T4 ASIC: .Pp .Bl -bullet -compact .It Chelsio T420-CR .It Chelsio T422-CR .It Chelsio T440-CR .It Chelsio T420-BCH .It Chelsio T440-BCH .It Chelsio T440-CH .It Chelsio T420-SO .It Chelsio T420-CX .It Chelsio T420-BT .It Chelsio T404-BT .El .Sh LOADER TUNABLES Tunables can be set at the .Xr loader 8 prompt before booting the kernel or stored in .Xr loader.conf 5 . .Bl -tag -width indent .It Va hw.cxgbe.ntxq10g The number of tx queues to use for a 10Gb or 40Gb port. The default is 16 or the number of CPU cores in the system, whichever is less. .It Va hw.cxgbe.nrxq10g The number of rx queues to use for a 10Gb or 40Gb port. The default is 8 or the number of CPU cores in the system, whichever is less. .It Va hw.cxgbe.ntxq1g The number of tx queues to use for a 1Gb port. The default is 4 or the number of CPU cores in the system, whichever is less. .It Va hw.cxgbe.nrxq1g The number of rx queues to use for a 1Gb port. The default is 2 or the number of CPU cores in the system, whichever is less. .It Va hw.cxgbe.nofldtxq10g The number of TOE tx queues to use for a 10Gb or 40Gb port. The default is 8 or the number of CPU cores in the system, whichever is less. .It Va hw.cxgbe.nofldrxq10g The number of TOE rx queues to use for a 10Gb or 40Gb port. The default is 2 or the number of CPU cores in the system, whichever is less. .It Va hw.cxgbe.nofldtxq1g The number of TOE tx queues to use for a 1Gb port. The default is 2 or the number of CPU cores in the system, whichever is less. .It Va hw.cxgbe.nofldrxq1g The number of TOE rx queues to use for a 1Gb port. The default is 1. .It Va hw.cxgbe.holdoff_timer_idx_10G .It Va hw.cxgbe.holdoff_timer_idx_1G The timer index value to use to delay interrupts. The holdoff timer list has the values 1, 5, 10, 50, 100, and 200 by default (all values are in microseconds) and the index selects a value from this list. The default value is 1 which means the timer value is 5us. Different interfaces can be assigned different values at any time via the dev.cxgbe.X.holdoff_tmr_idx or dev.cxl.X.holdoff_tmr_idx sysctl. .It Va hw.cxgbe.holdoff_pktc_idx_10G .It Va hw.cxgbe.holdoff_pktc_idx_1G The packet-count index value to use to delay interrupts. The packet-count list has the values 1, 8, 16, and 32 by default and the index selects a value from this list. The default value is -1 which means packet counting is disabled and interrupts are generated based solely on the holdoff timer value. Different interfaces can be assigned different values via the dev.cxgbe.X.holdoff_pktc_idx or dev.cxl.X.holdoff_pktc_idx sysctl. This sysctl works only when the interface has never been marked up (as done by ifconfig up). .It Va hw.cxgbe.qsize_txq The size, in number of entries, of the descriptor ring used for a tx queue. A buf_ring of the same size is also allocated for additional software queuing. See .Xr ifnet 9 . The default value is 1024. Different interfaces can be assigned different values via the dev.cxgbe.X.qsize_txq sysctl or dev.cxl.X.qsize_txq sysctl. This sysctl works only when the interface has never been marked up (as done by ifconfig up). .It Va hw.cxgbe.qsize_rxq The size, in number of entries, of the descriptor ring used for an rx queue. The default value is 1024. Different interfaces can be assigned different values via the dev.cxgbe.X.qsize_rxq or dev.cxl.X.qsize_rxq sysctl. This sysctl works only when the interface has never been marked up (as done by ifconfig up). .It Va hw.cxgbe.interrupt_types The interrupt types that the driver is allowed to use. Bit 0 represents INTx (line interrupts), bit 1 MSI, bit 2 MSI-X. The default is 7 (all allowed). The driver will select the best possible type out of the allowed types by itself. .It Va hw.cxgbe.fw_install 0 prohibits the driver from installing a firmware on the card. 1 allows the driver to install a new firmware if internal driver heuristics indicate that the new firmware is preferable to the one already on the card. 2 instructs the driver to always install the new firmware on the card as long as it is compatible with the driver and is a different version than the one already on the card. The default is 1. .It Va hw.cxgbe.fl_pktshift -The number of bytes of padding inserted before the begining of an Ethernet +The number of bytes of padding inserted before the beginning of an Ethernet frame in the receive buffer. The default value of 2 ensures that the Ethernet payload (usually the IP header) is at a 4 byte aligned address. 0-7 are all valid values. .It Va hw.cxgbe.fl_pad A non-zero value ensures that writes from the hardware to a receive buffer are padded up to the specified boundary. The default is -1 which lets the driver pick a pad boundary. 0 disables trailer padding completely. .It Va hw.cxgbe.cong_drop Controls the hardware response to congestion. -1 disables congestion feedback and is not recommended. 0 instructs the hardware to backpressure its pipeline on congestion. This usually results in the port emitting PAUSE frames. 1 instructs the hardware to drop frames destined for congested queues. .It Va hw.cxgbe.pause_settings PAUSE frame settings. Bit 0 is rx_pause, bit 1 is tx_pause. rx_pause = 1 instructs the hardware to heed incoming PAUSE frames, 0 instructs it to ignore them. tx_pause = 1 allows the hardware to emit PAUSE frames when its receive FIFO reaches a high threshold, 0 prohibits the hardware from emitting PAUSE frames. The default is 3 (both rx_pause and tx_pause = 1). This tunable establishes the default PAUSE settings for all ports. Settings can be displayed and controlled on a per-port basis via the dev.cxgbe.X.pause_settings (dev.cxl.X.pause_settings for T5 cards) sysctl. .It Va hw.cxgbe.buffer_packing Allow the hardware to deliver multiple frames in the same receive buffer opportunistically. The default is -1 which lets the driver decide. 0 or 1 explicitly disable or enable this feature. .It Va hw.cxgbe.allow_mbufs_in_cluster 1 allows the driver to lay down one or more mbufs within the receive buffer opportunistically. This is the default. 0 prohibits the driver from doing so. .It Va hw.cxgbe.largest_rx_cluster .It Va hw.cxgbe.safest_rx_cluster Sizes of rx clusters. Each of these must be set to one of the sizes available (usually 2048, 4096, 9216, and 16384) and largest_rx_cluster must be greater than or equal to safest_rx_cluster. The defaults are 16384 and 4096 respectively. The driver will never attempt to allocate a receive buffer larger than largest_rx_cluster and will fall back to allocating buffers of safest_rx_cluster size if an allocation larger than safest_rx_cluster fails. Note that largest_rx_cluster merely establishes a ceiling -- the driver is allowed to allocate buffers of smaller sizes. .It Va hw.cxgbe.config_file Select a pre-packaged device configuration file. A configuration file contains a recipe for partitioning and configuring the hardware resources on the card. This tunable is for specialized applications only and should not be used in normal operation. The configuration profile currently in use is available in the dev.t4nex.X.cf and dev.t4nex.X.cfcsum (dev.t5nex for T5 cards) sysctls. .It Va hw.cxgbe.linkcaps_allowed .It Va hw.cxgbe.niccaps_allowed .It Va hw.cxgbe.toecaps_allowed .It Va hw.cxgbe.rdmacaps_allowed .It Va hw.cxgbe.iscsicaps_allowed .It Va hw.cxgbe.fcoecaps_allowed Disallowing capabilities provides a hint to the driver and firmware to not reserve hardware resources for that feature. Each of these is a bit field with a bit for each sub-capability within the capability. This tunable is for specialized applications only and should not be used in normal operation. The capabilities for which hardware resources have been reserved are listed in dev.t4nex.X.*caps or dev.t5nex.X.*caps sysctls. .El .Sh SUPPORT For general information and support, go to the Chelsio support website at: .Pa http://www.chelsio.com/ . .Pp If an issue is identified with this driver with a supported adapter, email all the specific information related to the issue to .Aq support@chelsio.com . .Sh SEE ALSO .Xr altq 4 , .Xr arp 4 , .Xr cxgb 4 , .Xr netintro 4 , .Xr ng_ether 4 , .Xr ifconfig 8 .Sh HISTORY The .Nm device driver first appeared in .Fx 9.0 . Support for T5 cards first appeared in .Fx 9.2 and .Fx 10.0 . .Sh AUTHORS .An -nosplit The .Nm driver was written by .An Navdeep Parhar Aq np@FreeBSD.org . Index: stable/10/share/man/man4/ng_car.4 =================================================================== --- stable/10/share/man/man4/ng_car.4 (revision 299385) +++ stable/10/share/man/man4/ng_car.4 (revision 299386) @@ -1,214 +1,214 @@ .\" Copyright (c) 2005 Nuno Antunes .\" Copyright (c) 2007 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 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 13, 2012 .Dt NG_CAR 4 .Os .Sh NAME .Nm ng_car .Nd Committed Access Rate netgraph node type .Sh SYNOPSIS .In netgraph/ng_car.h .Sh DESCRIPTION The .Nm car node type limits traffic flowing through it using: .Pp .Bl -bullet -compact .It Single rate three color marker as described in RFC 2697, .It Two rate three color marker as described in RFC 2698, .It RED-like rate limit algorithm used by Cisco, .It Traffic shaping with RED. .El .Sh HOOKS This node type supports the following hooks: .Bl -tag -width ".Va upper" .It Va upper Hook leading to upper layer protocols. .It Va lower Hook leading to lower layer protocols. .El .Pp Traffic flowing from .Va upper to .Va lower is considered .Sy downstream traffic. Traffic flowing from .Va lower to .Va upper is considered .Sy upstream traffic. .Sh MODES OF OPERATION Each hook can operate in one of the following modes: .Bl -tag -width foo .It Dv NG_CAR_SINGLE_RATE Single rate three color marker as described in RFC 2697. Committed burst packets are counted as green, extended burst packets are counted as yellow and exceeding packets are counted as red. Committed burst getting refilled with CIR (Committed Information Rate) speed. When it is full, exceeded burst getting refilled. .It Dv NG_CAR_DOUBLE_RATE Two rate three color marker as described in RFC 2698. Committed burst packets are counted as green, peak burst packets are counted as yellow and exceeding packets are counted as red. Committed burst getting refilled with CIR speed. Peak burst getting refilled with PIR (Peak Information Rate) speed at the same time. .It Dv NG_CAR_RED Similar to .Dv NG_CAR_SINGLE_RATE , but with different understanding of extended burst. When normal burst exceeded and extended burst is used, packets are counted red with probability equal to part of extended burst consumed. Extended burst getting refilled first. When it is full, committed burst getting refilled. This behavior is similar to RED active queue management algorithm. .Pp This algorithm is more polite to the TCP traffic than NG_CAR_SINGLE_RATE. .It Dv NG_CAR_SHAPE Committed burst packets are counted as green, exceeding packets are delayed by queue with RED management and counted as yellow. Packets dropped by queue counted as red. Queue parameters are hardcoded: length 99 packets, min_th 8 packets, max_p 100%. .Pp Traffic shaping is much more polite to the TCP traffic than rate limit on links with bandwidth * delay product less than 6-8 TCP segments, but it consumes additional system resources for queue processing. .El By default, all information rates are measured in bits per second and bursts are measured in bytes. But when NG_CAR_COUNT_PACKETS option is enabled, rates are measured in packets per second and bursts are in packets. .Sh CONTROL MESSAGES This node type supports the generic control messages and the following specific messages. .Bl -tag -width foo .It Dv NGM_CAR_SET_CONF Pq Ic setconf Set node configuration to the specified at .Vt "struct ng_car_bulkconf" .It Dv NGM_CAR_GET_CONF Pq Ic getconf Return current node configuration as .Vt "struct ng_car_bulkconf" .Bd -literal struct ng_car_hookconf { - uint64_t cbs; /* Commited burst size (bytes) */ + uint64_t cbs; /* Committed burst size (bytes) */ uint64_t ebs; /* Exceeded/Peak burst size (bytes) */ - uint64_t cir; /* Commited information rate (bits/s) */ + uint64_t cir; /* Committed information rate (bits/s) */ uint64_t pir; /* Peak information rate (bits/s) */ uint8_t green_action; /* Action for green packets */ uint8_t yellow_action; /* Action for yellow packets */ uint8_t red_action; /* Action for red packets */ uint8_t mode; /* single/double rate, ... */ uint8_t opt; /* color-aware or color-blind */ }; /* possible actions (..._action) */ enum { NG_CAR_ACTION_FORWARD = 1, NG_CAR_ACTION_DROP }; /* operation modes (mode) */ enum { NG_CAR_SINGLE_RATE = 0, NG_CAR_DOUBLE_RATE, NG_CAR_RED, NG_CAR_SHAPE }; /* mode options (opt) */ #define NG_CAR_COUNT_PACKETS 2 struct ng_car_bulkconf { struct ng_car_hookconf upstream; struct ng_car_hookconf downstream; }; .Ed .It Dv NGM_CAR_GET_STATS Pq Ic getstats Return node statistics as .Vt "struct ng_car_bulkstats" .Bd -literal struct ng_car_hookstats { uint64_t passed_pkts; /* Counter for passed packets */ - uint64_t droped_pkts; /* Counter for droped packets */ + uint64_t droped_pkts; /* Counter for dropped packets */ uint64_t green_pkts; /* Counter for green packets */ uint64_t yellow_pkts; /* Counter for yellow packets */ uint64_t red_pkts; /* Counter for red packets */ uint64_t errors; /* Counter for operation errors */ }; struct ng_car_bulkstats { struct ng_car_hookstats upstream; struct ng_car_hookstats downstream; }; .Ed .It Dv NGM_CAR_CLR_STATS Pq Ic clrstats Clear node statistics. .It Dv NGM_CAR_GETCLR_STATS Pq Ic getclrstats Atomically return and clear node statistics. .El .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when all hooks have been disconnected. .Sh EXAMPLES Limit outgoing data rate over fxp0 Ethernet interface to 20Mbit/s and incoming packet rate to 5000pps. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer fxp0: car lower lower name fxp0:lower fxp0_car connect fxp0: fxp0_car: upper upper msg fxp0_car: setconf { downstream={ cir=20000000 cbs=2500000 ebs=2500000 greenAction=1 yellowAction=1 redAction=2 mode=2 } upstream={ cir=5000 cbs=100 ebs=100 greenAction=1 yellowAction=1 redAction=2 mode=2 opt=2 } } SEQ .Ed .Sh SEE ALSO .Xr netgraph 4 , .Xr ngctl 8 .Rs .%A J. Heinanen .%T "A Single Rate Three Color Marker" .%O RFC 2697 .Re .Rs .%A J. Heinanen .%T "A Two Rate Three Color Marker" .%O RFC 2698 .Re .Sh AUTHORS .An Nuno Antunes Aq nuno.antunes@gmail.com .An Alexander Motin Aq mav@FreeBSD.org .Sh BUGS At this moment only DROP and FORWARD actions are implemented. Index: stable/10/share/man/man4/ng_nat.4 =================================================================== --- stable/10/share/man/man4/ng_nat.4 (revision 299385) +++ stable/10/share/man/man4/ng_nat.4 (revision 299386) @@ -1,350 +1,350 @@ .\" 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 March 21, 2013 .Dt NG_NAT 4 .Os .Sh NAME .Nm ng_nat .Nd "NAT netgraph node type" .Sh SYNOPSIS .In netgraph/ng_nat.h .Sh DESCRIPTION An .Nm node performs network address translation (NAT) of packets passing through it. A .Nm nat node uses .Xr libalias 3 engine for packet aliasing. .Sh HOOKS This node type has two hooks: .Bl -tag -width ".Va out" .It Va out Packets received on this hook are considered outgoing and will be masqueraded to a configured address. .It Va in Packets coming on this hook are considered incoming and will be dealiased. .El .Sh CONTROL MESSAGES This node type supports the generic control messages, plus the following: .Bl -tag -width foo .It Dv NGM_NAT_SET_IPADDR Pq Ic setaliasaddr Configure aliasing address for a node. After both hooks have been connected and aliasing address was configured, a node is ready for aliasing operation. .It Dv NGM_NAT_SET_MODE Pq Ic setmode Set node's operation mode using supplied .Vt "struct ng_nat_mode" . .Bd -literal struct ng_nat_mode { uint32_t flags; uint32_t mask; }; /* Supported flags: */ #define NG_NAT_LOG 0x01 #define NG_NAT_DENY_INCOMING 0x02 #define NG_NAT_SAME_PORTS 0x04 #define NG_NAT_UNREGISTERED_ONLY 0x10 #define NG_NAT_RESET_ON_ADDR_CHANGE 0x20 #define NG_NAT_PROXY_ONLY 0x40 #define NG_NAT_REVERSE 0x80 .Ed .It Dv NGM_NAT_SET_TARGET Pq Ic settarget Configure target address for a node. When an incoming packet not associated with any pre-existing aliasing link arrives at the host machine, it will be sent to the specified address. .It Dv NGM_NAT_REDIRECT_PORT Pq Ic redirectport Redirect incoming connections arriving to given port(s) to another host and port(s). The following .Vt "struct ng_nat_redirect_port" must be supplied as argument. .Bd -literal #define NG_NAT_DESC_LENGTH 64 struct ng_nat_redirect_port { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Redirection is assigned an unique ID which is returned as response to this message, and information about redirection added to list of static redirects which later can be retrieved by .Dv NGM_NAT_LIST_REDIRECTS message. .It Dv NGM_NAT_REDIRECT_ADDR Pq Ic redirectaddr Redirect traffic for public IP address to a machine on the local network. This function is known as .Em static NAT . The following .Vt "struct ng_nat_redirect_addr" must be supplied as argument. .Bd -literal struct ng_nat_redirect_addr { struct in_addr local_addr; struct in_addr alias_addr; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Unique ID for this redirection is returned as response to this message. .It Dv NGM_NAT_REDIRECT_PROTO Pq Ic redirectproto Redirect incoming IP packets of protocol .Va proto (see .Xr protocols 5 ) to a machine on the local network. The following .Vt "struct ng_nat_redirect_proto" must be supplied as argument. .Bd -literal struct ng_nat_redirect_proto { struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint8_t proto; char description[NG_NAT_DESC_LENGTH]; }; .Ed .Pp Unique ID for this redirection is returned as response to this message. .It Dv NGM_NAT_REDIRECT_DYNAMIC Pq Ic redirectdynamic Mark redirection with specified ID as dynamic, i.e., it will serve for exactly one next connection and then will be automatically deleted from internal links table. Only fully specified links can be made dynamic. The redirection with this ID is also immediately deleted from user-visible list of static redirects (available through .Dv NGM_NAT_LIST_REDIRECTS message). .It Dv NGM_NAT_REDIRECT_DELETE Pq Ic redirectdelete Delete redirection with specified ID (currently active connections are not affected). .It Dv NGM_NAT_ADD_SERVER Pq Ic addserver Add another server to a pool. This is used to transparently offload network load on a single server and distribute the load across a pool of servers, also known as .Em LSNAT (RFC 2391). The following .Vt "struct ng_nat_add_server" must be supplied as argument. .Bd -literal struct ng_nat_add_server { uint32_t id; struct in_addr addr; uint16_t port; }; .Ed .Pp First, the redirection is set up by .Dv NGM_NAT_REDIRECT_PORT or .Dv NGM_NAT_REDIRECT_ADDR . Then, ID of that redirection is used in multiple .Dv NGM_NAT_ADD_SERVER messages to add necessary number of servers. For redirections created by .Dv NGM_NAT_REDIRECT_ADDR , the .Va port is ignored and could have any value. Original redirection's parameters .Va local_addr and .Va local_port are also ignored after .Dv NGM_NAT_ADD_SERVER was used (they are effectively replaced by server pool). .It Dv NGM_NAT_LIST_REDIRECTS Pq Ic listredirects Return list of configured static redirects as .Vt "struct ng_nat_list_redirects" . .Bd -literal struct ng_nat_listrdrs_entry { uint32_t id; /* Anything except zero */ struct in_addr local_addr; struct in_addr alias_addr; struct in_addr remote_addr; uint16_t local_port; uint16_t alias_port; uint16_t remote_port; uint16_t proto; /* Valid proto or NG_NAT_REDIRPROTO_ADDR */ uint16_t lsnat; /* LSNAT servers count */ char description[NG_NAT_DESC_LENGTH]; }; struct ng_nat_list_redirects { uint32_t total_count; struct ng_nat_listrdrs_entry redirects[]; }; #define NG_NAT_REDIRPROTO_ADDR (IPPROTO_MAX + 3) .Ed .Pp Entries of the .Va redirects array returned in the unified format for all redirect types. Ports are meaningful only if protocol is either TCP or UDP and .Em static NAT redirection (created by .Dv NGM_NAT_REDIRECT_ADDR ) is indicated by .Va proto set to .Dv NG_NAT_REDIRPROTO_ADDR . If .Va lsnat servers counter is greater than zero, then .Va local_addr and .Va local_port are also meaningless. .It Dv NGM_NAT_PROXY_RULE Pq Ic proxyrule Specify a transparent proxying rule (string must be supplied as argument). See .Xr libalias 3 for details. .It Dv NGM_NAT_LIBALIAS_INFO Pq Ic libaliasinfo Return internal statistics of .Xr libalias 3 instance as .Vt "struct ng_nat_libalias_info" . .Bd -literal struct ng_nat_libalias_info { uint32_t icmpLinkCount; uint32_t udpLinkCount; uint32_t tcpLinkCount; uint32_t sctpLinkCount; uint32_t pptpLinkCount; uint32_t protoLinkCount; uint32_t fragmentIdLinkCount; uint32_t fragmentPtrLinkCount; uint32_t sockCount; }; .Ed In case of .Nm -failed to retreive a certain counter +failed to retrieve a certain counter from its .Xr libalias instance, the corresponding field is returned as .Va UINT32_MAX . .El .Pp In all redirection messages .Va local_addr and .Va local_port mean address and port of target machine in the internal network, respectively. If .Va alias_addr is zero, then default aliasing address (set by .Dv NGM_NAT_SET_IPADDR ) is used. Connections can also be restricted to be accepted only from specific external machines by using non-zero .Va remote_addr and/or .Va remote_port . Each redirection assigned an ID which can be later used for redirection manipulation on individual basis (e.g., removal). This ID guaranteed to be unique until the node shuts down (it will not be reused after deletion), and is returned to user after making each new redirection or can be found in the stored list of all redirections. The .Va description passed to and from node unchanged, together with ID providing a way for several entities to concurrently manipulate redirections in automated way. .Sh SHUTDOWN This node shuts down upon receipt of a .Dv NGM_SHUTDOWN control message, or when both hooks are disconnected. .Sh EXAMPLES In the following example, the packets are injected into a .Nm nat node using the .Xr ng_ipfw 4 node. .Bd -literal -offset indent # Create NAT node ngctl mkpeer ipfw: nat 60 out ngctl name ipfw:60 nat ngctl connect ipfw: nat: 61 in ngctl msg nat: setaliasaddr x.y.35.8 # Divert traffic into NAT node ipfw add 300 netgraph 61 all from any to any in via fxp0 ipfw add 400 netgraph 60 all from any to any out via fxp0 # Let packets continue with after being (de)aliased sysctl net.inet.ip.fw.one_pass=0 .Ed .Pp The .Nm node can be inserted right after the .Xr ng_iface 4 node in the graph. In the following example, we perform masquerading on a serial line with HDLC encapsulation. .Bd -literal -offset indent /usr/sbin/ngctl -f- <<-SEQ mkpeer cp0: cisco rawdata downstream name cp0:rawdata hdlc mkpeer hdlc: nat inet in name hdlc:inet nat mkpeer nat: iface out inet msg nat: setaliasaddr x.y.8.35 SEQ ifconfig ng0 x.y.8.35 x.y.8.1 .Ed .Sh SEE ALSO .Xr libalias 3 , .Xr ng_ipfw 4 , .Xr natd 8 , .Xr ngctl 8 .Sh HISTORY The .Nm node type was implemented in .Fx 6.0 . .Sh AUTHORS .An Gleb Smirnoff Aq glebius@FreeBSD.org Index: stable/10/share/man/man4/uplcom.4 =================================================================== --- stable/10/share/man/man4/uplcom.4 (revision 299385) +++ stable/10/share/man/man4/uplcom.4 (revision 299386) @@ -1,197 +1,197 @@ .\" $NetBSD: uplcom.4,v 1.9 2002/02/07 03:15:09 ross Exp $ .\" .\" Copyright (c) 2001 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Lennart Augustsson. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this 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 July 25, 2012 .Dt UPLCOM 4 .Os .Sh NAME .Nm uplcom .Nd USB support for Prolific PL-2303/2303X/2303HX serial adapters driver .Sh SYNOPSIS To compile this driver into the kernel, place the following lines in your kernel configuration file: .Bd -ragged -offset indent .Cd "device usb" .Cd "device ucom" .Cd "device uplcom" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent uplcom_load="YES" .Ed .Sh DESCRIPTION The .Nm driver provides support for various serial adapters based on the Prolific PL-2303, PL-2303X and PL-2303HX USB-to-RS232 Bridge chips. .Pp The device is accessed through the .Xr ucom 4 driver which makes it behave like a .Xr tty 4 . .Sh HARDWARE The .Nm driver supports the following devices and adapters: .Pp .Bl -bullet -compact .It ADLINK ND-6530 USB-Serial Adapter .It Alcatel One Touch 535/735 Phone .It Alcor AU9720 USB-RS232 Serial Adapter .It AlDiga AL-11U Modem .It Alltronix ACM003U00 Modem .It Anchor Serial adapter .It ATEN UC-232A .It BAFO BF-800 and BF-810 .It Belkin F5U257 .It BenQ S81 Phone .It Corega CG-USBRS232R Serial Adapter .It Cressi Edy (Seiko) Diving Computer .It ELECOM UC-SGT Serial Adapter .It HAL Corporation Crossam2+USB IR commander .It Hama USB RS-232 Serial Adapter .It -Hamlet exagerate XURS232 +Hamlet exaggerate XURS232 .It HP LD220 Point-Of-Sale (POS) Display .It IOGEAR UC-232A .It I/O DATA USB-RSAQ, USB-RSAQ2, USB-RSAQ3 and USB-RSAQ5 .It iTegno WM1080A GSM/GFPRS Modem .It iTegno WM2080A CDMA Modem .It Leadtek 9531 GPS .It Micromax 610U Modem .It Microsoft Palm 700WX .It Mobile Action MA-620 Infrared Adapter .It Motorola Cables .It Nokia CA-42 Cable .It OTI DKU-5 cable .It Panasonic TY-TP50P6-S flat screen .It PLX CA-42 Phone Cable .It PLANEX USB-RS232 URS-03 .It Prolific Generic USB-Serial Adapters .It Prolific Pharos USB-Serial Adapter .It RATOC REX-USB60 .It Radio Shack USB Serial Cable .It Sagem USB-Serial Adapter .It Samsung I330 Phone Cradle .It Sandberg USB to Serial Link (model number 133-08) .It Sanwa KB-USB2 Multimeter cable .It Siemens/BenQ EF81, SX1, X65 and X75 Mobile Phones .It Sitecom USB-Serial Adapter .It SMART Technologies USB-Serial Adapter .It Sony QN3 Phone Cable .It Sony Ericsson Datapilot .It Sony Ericsson DCU-10 and DCU-11 (Susteen) USB Cables .It SOURCENEXT KeikaiDenwa 8 (with and without charger) .It Speed Dragon USB-Serial Cable .It Syntech CPT-8001C Barcode Scanner .It TDK UHA6400 and UPA9664 USB-PHS Adapters .It TRENDnet USB to Serial Converter (TU-S9) .It Tripp-Lite U209-000-R USB-Serial Adapter .It UIC HCR331 Magnetic Stripe Card Reader .It UIC MSR206 Magnetic Stripe Card Reader .It Willcom W-SIM DD PHS terminal.(WS002IN) .It YC-Cable USB-Serial Adapter .It Zeagle N2iTion3 Diving Computer .El .Sh SEE ALSO .Xr tty 4 , .Xr ucom 4 , .Xr usb 4 .Sh HISTORY The .Nm driver appeared in .Nx 1.6 . This manual page was adopted from .Nx by .An Tom Rhodes Aq trhodes@FreeBSD.org in April 2002. Index: stable/10/share/man/man9/counter.9 =================================================================== --- stable/10/share/man/man9/counter.9 (revision 299385) +++ stable/10/share/man/man9/counter.9 (revision 299386) @@ -1,201 +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. +code paths. .Bl -tag -width indent .It Fn counter_u64_alloc how 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 . Index: stable/10/share/man/man9/fpu_kern.9 =================================================================== --- stable/10/share/man/man9/fpu_kern.9 (revision 299385) +++ stable/10/share/man/man9/fpu_kern.9 (revision 299386) @@ -1,195 +1,195 @@ .\" 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 June 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 +are erroneous 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 provides an optimization for threads which never leave to the usermode. Such thread can reuse the usermode save area for the FPU state, which is allowed by the function call. There is no flags defined for the function, and no error states that the function returns. .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 . Index: stable/10/share/man/man9/hash.9 =================================================================== --- stable/10/share/man/man9/hash.9 (revision 299385) +++ stable/10/share/man/man9/hash.9 (revision 299386) @@ -1,196 +1,196 @@ .\" 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 September 4, 2012 .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_hash32 , .Nm jenkins_hash .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" .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 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. 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. +sized arrays, thus is simpler and faster. It accepts an array of .Ft uint32_t values in its first argument and size of this array in the second argument. .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 . .Sh AUTHORS The .Nm hash32 functions were written by .An Tobias Weingartner . The .Nm jenkins_hash functions was written by Bob Jenkins . Index: stable/10/share/man/man9/lock.9 =================================================================== --- stable/10/share/man/man9/lock.9 (revision 299385) +++ stable/10/share/man/man9/lock.9 (revision 299386) @@ -1,423 +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 +unnecessary starvation. An example is .Dv vp locking in VFS .Xr lookup 9 , when .Dv dvp is already locked. .El .It Fa ilk An interlock mutex for controlling group access to the lock. If .Dv LK_INTERLOCK is specified, .Fn lockmgr and .Fn lockmgr_rw assume .Fa ilk is currently owned and not recursed, and will return it unlocked. See .Xr mtx_assert 9 . .El .Pp The .Fn lockmgr_args and .Fn lockmgr_args_rw function work like .Fn lockmgr and .Fn lockmgr_rw but accepting a .Fa wmesg , .Fa timo and .Fa prio on a per-instance basis. The specified values will override the default ones, but this can still be used passing, respectively, .Dv LK_WMESG_DEFAULT , .Dv LK_PRIO_DEFAULT and .Dv LK_TIMO_DEFAULT . .Pp The .Fn lockmgr_disown function switches the owner from the current thread to be .Dv LK_KERNPROC , if the lock is already held. .Pp The .Fn lockmgr_printinfo function prints debugging information about the lock. It is used primarily by .Xr VOP_PRINT 9 functions. .Pp The .Fn lockmgr_recursed function returns true if the lock is recursed, 0 otherwise. .Pp The .Fn lockmgr_waiters function returns true if the lock has waiters, 0 otherwise. .Pp The .Fn lockstatus function returns the status of the lock in relation to the current thread. .Pp When compiled with .Cd "options INVARIANTS" and .Cd "options INVARIANT_SUPPORT" , the .Fn lockmgr_assert function tests .Fa lkp for the assertions specified in .Fa what , and panics if they are not met. One of the following assertions must be specified: .Bl -tag -width ".Dv KA_UNLOCKED" .It Dv KA_LOCKED Assert that the current thread has either a shared or an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_SLOCKED Assert that the current thread has a shared lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_XLOCKED Assert that the current thread has an exclusive lock on the .Vt lkp lock pointed to by the first argument. .It Dv KA_UNLOCKED Assert that the current thread has no lock on the .Vt lkp lock pointed to by the first argument. .El .Pp In addition, one of the following optional assertions can be used with either an .Dv KA_LOCKED , .Dv KA_SLOCKED , or .Dv KA_XLOCKED assertion: .Bl -tag -width ".Dv KA_NOTRECURSED" .It Dv KA_RECURSED Assert that the current thread has a recursed lock on .Fa lkp . .It Dv KA_NOTRECURSED Assert that the current thread does not have a recursed lock on .Fa lkp . .El .Sh RETURN VALUES The .Fn lockmgr and .Fn lockmgr_rw functions return 0 on success and non-zero on failure. .Pp The .Fn lockstatus function returns: .Bl -tag -width ".Dv LK_EXCLUSIVE" .It Dv LK_EXCLUSIVE An exclusive lock is held by the current thread. .It Dv LK_EXCLOTHER An exclusive lock is held by someone other than the current thread. .It Dv LK_SHARED A shared lock is held. .It Li 0 The lock is not held by anyone. .El .Sh ERRORS .Fn lockmgr and .Fn lockmgr_rw fail if: .Bl -tag -width Er .It Bq Er EBUSY .Dv LK_FORCEUPGRADE was requested and another thread had already requested a lock upgrade. .It Bq Er EBUSY .Dv LK_NOWAIT was set, and a sleep would have been required, or .Dv LK_TRYUPGRADE operation was not able to upgrade the lock. .It Bq Er ENOLCK .Dv LK_SLEEPFAIL was set and .Fn lockmgr or .Fn lockmgr_rw did sleep. .It Bq Er EINTR .Dv PCATCH was set in the lock priority, and a signal was delivered during a sleep. Note the .Er ERESTART error below. .It Bq Er ERESTART .Dv PCATCH was set in the lock priority, a signal was delivered during a sleep, and the system call is to be restarted. .It Bq Er EWOULDBLOCK a non-zero timeout was given, and the timeout expired. .El .Sh LOCKS If .Dv LK_INTERLOCK is passed in the .Fa flags argument to .Fn lockmgr or .Fn lockmgr_rw , the .Fa ilk must be held prior to calling .Fn lockmgr or .Fn lockmgr_rw , and will be returned unlocked. .Pp Upgrade attempts that fail result in the loss of the lock that is currently held. Also, it is invalid to upgrade an exclusive lock, and a .Xr panic 9 will be the result of trying. .Sh SEE ALSO .Xr condvar 9 , .Xr locking 9 , .Xr mutex 9 , .Xr rwlock 9 , .Xr sleep 9 , .Xr sx 9 , .Xr mtx_assert 9 , .Xr panic 9 , .Xr VOP_PRINT 9 .Sh AUTHORS This manual page was written by .An Chad David Aq davidc@acns.ab.ca . Index: stable/10/share/man/man9/pci.9 =================================================================== --- stable/10/share/man/man9/pci.9 (revision 299385) +++ stable/10/share/man/man9/pci.9 (revision 299386) @@ -1,827 +1,827 @@ .\" .\" 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_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" .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_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. +table indices. 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 This manual page was written by .An Bruce M Simpson Aq bms@FreeBSD.org and .An John Baldwin Aq 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. Index: stable/10/share/man/man9/sysctl.9 =================================================================== --- stable/10/share/man/man9/sysctl.9 (revision 299385) +++ stable/10/share/man/man9/sysctl.9 (revision 299386) @@ -1,311 +1,311 @@ .\" .\" 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 September 12, 2013 .Dt SYSCTL 9 .Os .Sh NAME .Nm SYSCTL_DECL , .Nm SYSCTL_INT , .Nm SYSCTL_LONG , .Nm SYSCTL_NODE , .Nm SYSCTL_OPAQUE , .Nm SYSCTL_PROC , .Nm SYSCTL_QUAD , .Nm SYSCTL_STRING , .Nm SYSCTL_STRUCT , .Nm SYSCTL_UINT , .Nm SYSCTL_ULONG , .Nm SYSCTL_UQUAD .Nd Static sysctl declaration functions .Sh SYNOPSIS .In sys/types.h .In sys/sysctl.h .Fn SYSCTL_DECL name .Fn SYSCTL_INT parent nbr name access ptr val descr .Fn SYSCTL_LONG parent nbr name access ptr val descr .Fn SYSCTL_NODE parent nbr name access handler descr .Fn SYSCTL_OPAQUE parent nbr name access ptr len fmt descr .Fn SYSCTL_PROC parent nbr name access ptr arg handler fmt descr .Fn SYSCTL_QUAD parent nbr name access ptr val descr .Fn SYSCTL_STRING parent nbr name access arg len descr .Fn SYSCTL_STRUCT parent nbr name access ptr type descr .Fn SYSCTL_UINT parent nbr name access ptr val descr .Fn SYSCTL_ULONG parent nbr name access ptr val descr .Fn SYSCTL_UQUAD parent nbr name access ptr val descr .Sh DESCRIPTION The .Nm SYSCTL kernel interfaces allow code to statically declare .Xr sysctl 8 MIB entries, which will be initialized when the kernel module containing the declaration is initialized. When the module is unloaded, the sysctl will be automatically destroyed. .Pp Sysctl nodes are created in a hierarchical tree, with all static nodes being represented by named C data structures; in order to create a new node under an existing node in the tree, the structure representing the desired parent node must be declared in the current context using .Fn SYSCTL_DECL . .Pp New nodes are declared using one of .Fn SYSCTL_INT , .Fn SYSCTL_LONG , .Fn SYSCTL_NODE , .Fn SYSCTL_OPAQUE , .Fn SYSCTL_PROC , .Fn SYSCTL_QUAD , .Fn SYSCTL_STRING , .Fn SYSCTL_STRUCT , .Fn SYSCTL_UINT , .Fn SYSCTL_ULONG , and .Fn SYSCTL_UQUAD . Each macro accepts a parent name, as declared using .Fn SYSCTL_DECL , an OID number, typically .Dv OID_AUTO , a node name, a set of control and access flags, and a description. Depending on the macro, a pointer to a variable supporting the MIB entry, a size, a value, and a function pointer implementing the MIB entry may also be present. .Pp For most of the above 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_STRING" .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_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_UINT This is an unsigned integer. .It Dv CTLTYPE_LONG This is a signed long. .It Dv CTLTYPE_ULONG This is an unsigned long. .It Dv CTLTYPE_U64 This is a 64-bit unsigned integer. .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 which can be set by a system tunable. .It Dv CTLFLAG_WR This is a writable sysctl. .It Dv CTLFLAG_RW This sysctl is readable and writable. .It Dv CTLFLAG_RWTUN This sysctl is readable and writable and can also be set by a system tunable. .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. .El .Pp 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 .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 NULL, and the * value is declared. */ SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, NULL, 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) */ +static l_fp pps_freq; /* scaled frequency offset (ns/s) */ SYSCTL_OPAQUE(_kern_ntp_pll, OID_AUTO, pps_freq, CTLFLAG_RD, &pps_freq, sizeof(pps_freq), "I", ""); /* * Example of a procedure based sysctl exporting string * information. Notice that the data type is declared, the NULL * variable pointer and 0 size, the function pointer, and the * format string for sysctl(8). */ SYSCTL_PROC(_kern_timecounter, OID_AUTO, hardware, CTLTYPE_STRING | CTLFLAG_RW, NULL, 0, sysctl_kern_timecounter_hardware, "A", ""); .Ed .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 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 . Index: stable/10/share/man/man9/zone.9 =================================================================== --- stable/10/share/man/man9/zone.9 (revision 299385) +++ stable/10/share/man/man9/zone.9 (revision 299386) @@ -1,375 +1,375 @@ .\"- .\" 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 February 7, 2014 .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 .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" .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. +to an item being freed. The subsystem may choose to prefer offpage book-keeping for certain zones implicitly. .It Dv UMA_ZONE_ZINIT The zone will have its .Ft uma_init method set to internal method that initializes a new allocated slab to all zeros. Do not mistake .Ft uma_init method with .Ft uma_ctor . A zone with .Dv UMA_ZONE_ZINIT flag would not return zeroed memory on every .Fn uma_zalloc . .It Dv UMA_ZONE_HASH The zone should use an internal hash table to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_VTOSLAB The zone should use special field of .Vt vm_page_t to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_MALLOC The zone is for the .Xr malloc 9 subsystem. .It Dv UMA_ZONE_VM The zone is for the VM subsystem. .El .Pp To allocate an item from a zone, simply call .Fn uma_zalloc with a pointer to that zone and set the .Fa flags argument to selected flags as documented in .Xr malloc 9 . It will return a pointer to an item if successful, or .Dv NULL in the rare case where all items in the zone are in use and the allocator is unable to grow the zone and .Dv M_NOWAIT is specified. .Pp Items are released back to the zone from which they were allocated by calling .Fn uma_zfree with a pointer to the zone and a pointer to the item. If .Fa item is .Dv NULL , then .Fn uma_zfree does nothing. .Pp The variations .Fn uma_zalloc_arg and .Fn uma_zfree_arg allow to specify an argument for the .Dv ctor and .Dv dtor functions, respectively. .Pp If zone was created with .Dv UMA_ZONE_REFCNT flag, then pointer to reference counter for an item can be retrieved with help of the .Fn uma_find_refcnt function. .Pp Created zones, which are empty, can be destroyed using .Fn uma_zdestroy , freeing all memory that was allocated for the zone. All items allocated from the zone with .Fn uma_zalloc must have been freed with .Fn uma_zfree before. .Pp The .Fn uma_zone_set_max function limits the number of items .Pq and therefore memory that can be allocated to .Fa zone . The .Fa nitems argument specifies the requested upper limit number of items. The effective limit is returned to the caller, as it may end up being higher than requested due to the implementation rounding up to ensure all memory pages allocated to the zone are utilised to capacity. The limit applies to the total number of items in the zone, which includes allocated items, free items and free items in the per-cpu caches. On systems with more than one CPU it may not be possible to allocate the specified number of items even when there is no shortage of memory, because all of the remaining free items may be in the caches of the other CPUs when the limit is hit. .Pp The .Fn uma_zone_get_max function returns the effective upper limit number of items for a zone. .Pp The .Fn uma_zone_get_cur function returns the approximate current occupancy of the zone. The returned value is approximate because appropriate synchronisation to determine an exact value is not performed by the implementation. This ensures low overhead at the expense of potentially stale data being used in the calculation. .Pp The .Fn uma_zone_set_warning function sets a warning that will be printed on the system console when the given zone becomes full and fails to allocate an item. The warning will be printed not 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 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 jeff@FreeBSD.org to function as a slab allocator. .Pp This manual page was written by .An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org . Changes for UMA by .An Jeroen Ruigrok van der Werven Aq asmodai@FreeBSD.org . Index: stable/10 =================================================================== --- stable/10 (revision 299385) +++ stable/10 (revision 299386) Property changes on: stable/10 ___________________________________________________________________ Modified: svn:mergeinfo ## -0,0 +0,1 ## Merged /head:r298904