diff --git a/share/man/man4/cxgbe.4 b/share/man/man4/cxgbe.4 index ea17f35daeb4..98217975fb45 100644 --- a/share/man/man4/cxgbe.4 +++ b/share/man/man4/cxgbe.4 @@ -1,338 +1,338 @@ .\" 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 December 2, 2015 .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.num_vis The number of virtual interfaces (VIs) created for each port. Each virtual interface creates a separate network interface. The first virtual interface on each port is required and represents the primary network interface on the port. Additional virtual interfaces on a port are named vcxgbe (T4) or vcxl (T5) and only use a single rx and tx queue. Additional virtual interfaces use a single pair of queues for rx and tx as well an additional pair of queues for TOE rx and tx. 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 Mt 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 Mt np@FreeBSD.org . diff --git a/share/man/man4/ds3231.4 b/share/man/man4/ds3231.4 index 6fdcccc26eb4..4059a88ca815 100644 --- a/share/man/man4/ds3231.4 +++ b/share/man/man4/ds3231.4 @@ -1,148 +1,148 @@ .\" .\" Copyright (c) 2014 Luiz Otavio O Souza .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this 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 February 12, 2016 .Dt DS3231 4 .Os .Sh NAME .Nm ds3231 .Nd Extremely Accurate i2c-integrated RTC/TCXO/Crystal .Sh SYNOPSIS .Cd "device iic" .Cd "device iicbus" .Cd "device ds3231" .Sh DESCRIPTION The .Nm is a low-cost, extremely accurate I2C realtime clock (RTC) with an integrated temperature-compensated crystal oscillator (TCXO) and crystal. .Pp The device incorporates a battery input and maintains accurate timekeeping when main power to the device is interrupted. .Pp Access to .Nm data is made with the .Xr sysctl 8 interface: .Bd -literal dev.ds3231.0.%desc: Maxim DS3231 RTC dev.ds3231.0.%driver: ds3231 dev.ds3231.0.%location: addr=0xd0 dev.ds3231.0.%pnpinfo: name=rtc compat=maxim,ds3231 dev.ds3231.0.%parent: iicbus1 dev.ds3231.0.temperature: 23.2C dev.ds3231.0.temp_conv: 0 dev.ds3231.0.bbsqw: 0 dev.ds3231.0.sqw_freq: 8192 dev.ds3231.0.sqw_mode: interrupt dev.ds3231.0.32khz_enable: 1 .Ed .Bl -tag -width ".Va dev.ds3231.%d.temperature" .It Va dev.ds3231.%d.temperature The read-only value of the current temperature read by the RTC. .It Va dev.ds3231.%d.temp_conv -Start a new temperature convertion. +Start a new temperature conversion. When read as 1, a temperature conversion is in progress. -When read as 0 and then set to 1, a temperature convertion is started. +When read as 0 and then set to 1, a temperature conversion is started. The temperature conversion runs automatically on power up and once every 64 seconds afterward. .It Va dev.ds3231.%d.bbsqw If set to 1 and .Va dev.ds3231.%d.sqw_mode is set to square-wave, battery-backed square-wave output is enabled. If set to 0, the SQW pin will be set to high impendance when the RTC is being powered by battery. .It Va dev.ds3231.%d.sqw_freq Select the frequency of the SQW pin when the square-wave output is enabled on .Va dev.ds3231.%d.sqw_mode . It can be set to 1, 1024, 4096, and 8192. .It Va dev.ds3231.%d.sqw_mode Set the operation mode for the SQW pin. It can be set to 'interrupt' (default) or 'square-wave'. In interrupt mode, the SQW pin is used to generate interrupts for the RTC alarms. In square-wave mode, the SQW pin drives a square-wave of .Va dev.ds3231.%d.sqw_freq frequency. .It Va dev.ds3231.%d.32khz_enable Enable the 32kHz output. .El .Pp Please check the .Nm datasheet for more details. .Pp On a .Xr device.hints 5 based system, such as .Li MIPS , these values are configurable for .Nm : .Bl -tag -width ".Va hint.ds3231.%d.addr" .It Va hint.ds3231.%d.at The .Xr iicbus 4 that the .Nm is connected to. .It Va hint.ds3231.%d.addr The 8-bit i2c address of .Nm . The default 8-bit address for .Nm is 0xd0. .El .Pp On a .Xr FDT 4 based system the following properties must be set: .Bl -tag -width ".Va compatible" .It Va compatible Must always be set to "maxim,ds3231". .It Va reg The 7-bit i2c address of .Nm . The default 7-bit address for .Nm is 0x68. .El .Sh SEE ALSO .Xr fdt 4 , .Xr iic 4 , .Xr iicbus 4 , .Xr sysctl 8 .Sh HISTORY The .Nm driver first appeared in .Fx 11.0 . .Sh AUTHORS .An -nosplit The .Nm driver and this manual page were written by .An Luiz Otavio O Souza Aq Mt loos@FreeBSD.org . diff --git a/share/man/man4/ng_car.4 b/share/man/man4/ng_car.4 index ade46498fa63..5950b996a0e8 100644 --- a/share/man/man4/ng_car.4 +++ b/share/man/man4/ng_car.4 @@ -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 Mt nuno.antunes@gmail.com .An Alexander Motin Aq Mt mav@FreeBSD.org .Sh BUGS At this moment only DROP and FORWARD actions are implemented. diff --git a/share/man/man4/ng_nat.4 b/share/man/man4/ng_nat.4 index e0d056d2152f..d7ddc89cfe36 100644 --- a/share/man/man4/ng_nat.4 +++ b/share/man/man4/ng_nat.4 @@ -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 Mt glebius@FreeBSD.org diff --git a/share/man/man4/random.4 b/share/man/man4/random.4 index bd7dec90d722..5e5388f0ba3e 100644 --- a/share/man/man4/random.4 +++ b/share/man/man4/random.4 @@ -1,354 +1,354 @@ .\" Copyright (c) 2001-2015 Mark R V Murray. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 17, 2015 .Dt RANDOM 4 .Os .Sh NAME .Nm random .Nd the entropy device .Sh SYNOPSIS .Cd "device random" .Cd "options RANDOM_LOADABLE" .Cd "options RANDOM_ENABLE_UMA" .Sh DESCRIPTION The .Nm device returns an endless supply of random bytes when read. It also accepts and reads data as any ordinary file. .Pp The generator will start in an .Em unseeded state, and will block reads until it is seeded for the first time. This may cause trouble at system boot when keys and the like are generated from .Xr random 4 so steps should be taken to ensure a seeding as soon as possible. .Pp It is also possible to read random bytes by using the KERN_ARND sysctl. On the command line this could be done by .Pp .Dl "sysctl -x -B 16 kern.arandom" .Pp This sysctl will not return random bytes unless the .Xr random 4 device is seeded. .Pp This initial seeding of random number generators is a bootstrapping problem that needs very careful attention. In some cases, it may be difficult to find enough randomness to seed a random number generator until a system is fully operational, but the system requires random numbers to become fully operational. It is (or more accurately should be) critically important that the .Nm device is seeded before the first time it is used. In the case where a dummy or "blocking-only" device is used, it is the responsibility of the system architect to ensure that no blocking reads hold up critical processes. .Pp To see the current settings of the software .Nm device, use the command line: .Pp .Dl "sysctl kern.random" .Pp which results in something like: .Bd -literal -offset indent kern.random.fortuna.minpoolsize: 64 kern.random.harvest.mask_symbolic: [HIGH_PERFORMANCE], ... ,CACHED kern.random.harvest.mask_bin: 00111111111 kern.random.harvest.mask: 511 kern.random.random_sources: 'Intel Secure Key RNG' .Ed .Pp Other than .Dl kern.random.fortuna.minpoolsize and .Dl kern.random.harvest.mask all settings are read-only. .Pp The .Pa kern.random.fortuna.minpoolsize sysctl is used -to set the seed threshhold. +to set the seed threshold. A smaller number gives a faster seed, but a less secure one. In practice, values between 64 and 256 are acceptable. .Pp The .Va kern.random.harvest.mask bitmask is used to select the possible entropy sources. A 0 (zero) value means the corresponding source is not considered as an entropy source. Set the bit to 1 (one) if you wish to use that source. The .Va kern.random.harvest.mask_bin and .Va kern.random.harvest.mask_symbolic sysctls can be used to confirm that the choices are correct. Note that disabled items in the latter item are listed in square brackets. See .Xr random_harvest 9 for more on the harvesting of entropy. .Pp When .Cd "options RANDOM_LOADABLE" is used, the .Pa /dev/random device is not created until an "algorithm module" is loaded. Two of these modules are built by default, .Em random_fortuna and .Em random_yarrow . The .Em random_yarrow module is deprecated, and will be removed in .Fx 12. Use of the Yarrow algorithm is not encouraged, but while still present in the kernel source, it can be selected with the .Cd "options RANDOM_YARROW" kernel option. Note that these loadable modules are slightly less efficient than their compiled-in equivalents. This is because some functions must be locked against load and unload events, and also must be indirect calls to allow for removal. .Pp When .Cd "options RANDOM_ENABLE_UMA" is used, the .Pa /dev/random device will obtain entropy from the zone allocator. This is potentially very high rate, and if so will be of questionable use. If this is the case, use of this option is not recommended. Determining this is not trivial, so experimenting and measurement using tools such as .Xr dtrace 1 will be required. .Sh RANDOMNESS The use of randomness in the field of computing is a rather subtle issue because randomness means different things to different people. Consider generating a password randomly, simulating a coin tossing experiment or choosing a random back-off period when a server does not respond. Each of these tasks requires random numbers, but the random numbers in each case have different requirements. .Pp Generation of passwords, session keys and the like requires cryptographic randomness. A cryptographic random number generator should be designed so that its output is difficult to guess, even if a lot of auxiliary information is known (such as when it was seeded, subsequent or previous output, and so on). On .Fx , seeding for cryptographic random number generators is provided by the .Nm device, which provides real randomness. The .Xr arc4random 3 library call provides a pseudo-random sequence which is generally reckoned to be suitable for simple cryptographic use. The OpenSSL library also provides functions for managing randomness via functions such as .Xr RAND_bytes 3 and .Xr RAND_add 3 . Note that OpenSSL uses the .Nm device for seeding automatically. .Pp Randomness for simulation is required in engineering or scientific software and games. The first requirement of these applications is that the random numbers produced conform to some well-known, usually uniform, distribution. The sequence of numbers should also appear numerically uncorrelated, as simulation often assumes independence of its random inputs. Often it is desirable to reproduce the results of a simulation exactly, so that if the generator is seeded in the same way, it should produce the same results. A peripheral concern for simulation is the speed of a random number generator. .Pp Another issue in simulation is the size of the state associated with the random number generator, and how frequently it repeats itself. For example, a program which shuffles a pack of cards should have 52!\& possible outputs, which requires the random number generator to have 52!\& starting states. This means the seed should have at least log_2(52!) ~ 226 bits of state if the program is to stand a chance of outputting all possible sequences, and the program needs some unbiased way of generating these bits. Again, the .Nm device could be used for seeding here, but in practice, smaller seeds are usually considered acceptable. .Pp .Fx provides two families of functions which are considered suitable for simulation. The .Xr random 3 family of functions provides a random integer between 0 to .if t 2\u\s731\s10\d\(mi1. .if n (2**31)\(mi1. The functions .Xr srandom 3 , .Xr initstate 3 and .Xr setstate 3 are provided for deterministically setting the state of the generator and the function .Xr srandomdev 3 is provided for setting the state via the .Nm device. The .Xr drand48 3 family of functions are also provided, which provide random floating point numbers in various ranges. .Pp Randomness that is used for collision avoidance (for example, in certain network protocols) has slightly different semantics again. It is usually expected that the numbers will be uniform, as this produces the lowest chances of collision. Here again, the seeding of the generator is very important, as it is required that different instances of the generator produce independent sequences. However, the guessability or reproducibility of the sequence is unimportant, unlike the previous cases. .Pp .Fx does also provide the traditional .Xr rand 3 library call, for compatibility purposes. However, it is known to be poor for simulation and absolutely unsuitable for cryptographic purposes, so its use is discouraged. .Sh FILES .Bl -tag -width ".Pa /dev/random" .It Pa /dev/random .El .Sh SEE ALSO .Xr arc4random 3 , .Xr drand48 3 , .Xr rand 3 , .Xr RAND_add 3 , .Xr RAND_bytes 3 , .Xr random 3 , .Xr sysctl 8 , .Xr random 9 .Rs .%A Ferguson .%A Schneier .%A Kohno .%B Cryptography Engineering .%I Wiley .%O ISBN 978-0-470-47424-2 .Re .Sh HISTORY A .Nm device appeared in .Fx 2.2 . The current software implementation, introduced in .Fx 10.0 , is by .An Mark R V Murray , and is an implementation of the .Em Fortuna algorithm by Ferguson .Em et al . It replaces the previous .Em Yarrow implementation, introduced in .Fx 5.0 . The Yarrow algorithm is no longer supported by its authors, and is therefore deprecated. diff --git a/share/man/man4/uplcom.4 b/share/man/man4/uplcom.4 index 6ed2038da1f5..d38626107909 100644 --- a/share/man/man4/uplcom.4 +++ b/share/man/man4/uplcom.4 @@ -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 Mt trhodes@FreeBSD.org in April 2002. diff --git a/share/man/man9/counter.9 b/share/man/man9/counter.9 index 0fcf2ad97ba8..a89d14dcd25a 100644 --- a/share/man/man9/counter.9 +++ b/share/man/man9/counter.9 @@ -1,247 +1,247 @@ .\"- .\" Copyright (c) 2013 Gleb Smirnoff .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd March 14, 2016 .Dt COUNTER 9 .Os .Sh NAME .Nm counter .Nd "SMP-friendly kernel counter implementation" .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .In sys/counter.h .Ft counter_u64_t .Fn counter_u64_alloc "int wait" .Ft void .Fn counter_u64_free "counter_u64_t c" .Ft void .Fn counter_u64_add "counter_u64_t c" "int64_t v" .Ft void .Fn counter_enter .Ft void .Fn counter_exit .Ft void .Fn counter_u64_add_protected "counter_u64_t c" "int64_t v" .Ft uint64_t .Fn counter_u64_fetch "counter_u64_t c" .Ft void .Fn counter_u64_zero "counter_u64_t c" .In sys/sysctl.h .Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr .Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr .Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr .Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr .Sh DESCRIPTION .Nm is a generic facility to create counters that can be utilized for any purpose (such as collecting statistical data). A .Nm is guaranteed to be lossless when several kernel threads do simultaneous updates. However, .Nm does not block the calling thread, also no .Xr atomic 9 operations are used for the update, therefore the counters can be used in any non-interrupt context. Moreover, .Nm has special optimisations for SMP environments, making .Nm update faster than simple arithmetic on the global variable. Thus .Nm is considered suitable for accounting in the performance-critical -code pathes. +code paths. .Bl -tag -width indent .It Fn counter_u64_alloc wait Allocate a new 64-bit unsigned counter. The .Fa wait argument is the .Xr malloc 9 wait flag, should be either .Va M_NOWAIT or .Va M_WAITOK . If .Va M_NOWAIT is specified the operation may fail. .It Fn counter_u64_free c Free the previously allocated counter .Fa c . .It Fn counter_u64_add c v Add .Fa v to .Fa c . The KPI does not guarantee any protection from wraparound. .It Fn counter_enter Enter mode that would allow to safely update several counters via .Fn counter_u64_add_protected . On some machines this expands to .Xr critical 9 section, while on other is a nop. See .Sx IMPLEMENTATION DETAILS . .It Fn counter_exit Exit mode for updating several counters. .It Fn counter_u64_add_protected c v Same as .Fn counter_u64_add , but should be preceded by .Fn counter_enter . .It Fn counter_u64_fetch c Take a snapshot of counter .Fa c . The data obtained is not guaranteed to reflect the real cumulative value for any moment. .It Fn counter_u64_zero c Clear the counter .Fa c and set it to zero. .It Fn SYSCTL_COUNTER_U64 parent nbr name access ptr descr Declare a static .Xr sysctl oid that would represent a .Nm . The .Fa ptr argument should be a pointer to allocated .Vt counter_u64_t . A read of the oid returns value obtained through .Fn counter_u64_fetch . Any write to the oid zeroes it. .It Fn SYSCTL_ADD_COUNTER_U64 ctx parent nbr name access ptr descr Create a .Xr sysctl oid that would represent a .Nm . The .Fa ptr argument should be a pointer to allocated .Vt counter_u64_t . A read of the oid returns value obtained through .Fn counter_u64_fetch . Any write to the oid zeroes it. .It Fn SYSCTL_COUNTER_U64_ARRAY parent nbr name access ptr len descr Declare a static .Xr sysctl oid that would represent an array of .Nm . The .Fa ptr argument should be a pointer to allocated array of .Vt counter_u64_t's . The .Fa len argument should specify number of elements in the array. A read of the oid returns len-sized array of .Vt uint64_t values obtained through .Fn counter_u64_fetch . Any write to the oid zeroes all array elements. .It Fn SYSCTL_ADD_COUNTER_U64_ARRAY ctx parent nbr name access ptr len descr Create a .Xr sysctl oid that would represent an array of .Nm . The .Fa ptr argument should be a pointer to allocated array of .Vt counter_u64_t's . The .Fa len argument should specify number of elements in the array. A read of the oid returns len-sized array of .Vt uint64_t values obtained through .Fn counter_u64_fetch . Any write to the oid zeroes all array elements. .El .Sh IMPLEMENTATION DETAILS On all architectures .Nm is implemented using per-CPU data fields that are specially aligned in memory, to avoid inter-CPU bus traffic due to shared use of the variables between CPUs. These are allocated using .Va UMA_ZONE_PCPU .Xr uma 9 zone. The update operation only touches the field that is private to current CPU. Fetch operation loops through all per-CPU fields and obtains a snapshot sum of all fields. .Pp On amd64 a .Nm counter update is implemented as a single instruction without lock semantics, operating on the private data for the current CPU, which is safe against preemption and interrupts. .Pp On i386 architecture, when machine supports the cmpxchg8 instruction, this instruction is used. The multi-instruction sequence provides the same guarantees as the amd64 single-instruction implementation. .Pp On some architectures updating a counter require a .Xr critical 9 section. .Sh EXAMPLES The following example creates a static counter array exported to userspace through a sysctl: .Bd -literal -offset indent #define MY_SIZE 8 static counter_u64_t array[MY_SIZE]; SYSCTL_COUNTER_U64_ARRAY(_debug, OID_AUTO, counter_array, CTLFLAG_RW, &array[0], MY_SIZE, "Test counter array"); .Ed .Pp .Sh SEE ALSO .Xr atomic 9 , .Xr critical 9 , .Xr locking 9 , .Xr malloc 9 , .Xr sysctl 9 , .Xr uma 9 .Sh HISTORY The .Nm facility first appeared in .Fx 10.0 . .Sh AUTHORS .An -nosplit The .Nm facility was written by .An Gleb Smirnoff and .An Konstantin Belousov . diff --git a/share/man/man9/fpu_kern.9 b/share/man/man9/fpu_kern.9 index 748e6fca4b43..92204d2b3732 100644 --- a/share/man/man9/fpu_kern.9 +++ b/share/man/man9/fpu_kern.9 @@ -1,200 +1,200 @@ .\" Copyright (c) 2014 .\" Konstantin Belousov . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 23, 2014 .Dt FPU_KERN 9 .Os .Sh NAME .Nm fpu_kern .Nd "facility to use the FPU in the kernel" .Sh SYNOPSIS .Ft struct fpu_kern_ctx * .Fn fpu_kern_alloc_ctx "u_int flags" .Ft void .Fn fpu_kern_free_ctx "struct fpu_kern_ctx *ctx" .Ft int .Fn fpu_kern_enter "struct thread *td" "struct fpu_kern_ctx *ctx" "u_int flags" .Ft int .Fn fpu_kern_leave "struct thread *td" "struct fpu_kern_ctx *ctx" .Ft int .Fn fpu_kern_thread "u_int flags" .Ft int .Fn is_fpu_kern_thread "u_int flags" .Sh DESCRIPTION The .Nm family of functions allows the use of FPU hardware in kernel code. Modern FPUs are not limited to providing hardware implementation for floating point arithmetic; they offer advanced accelerators for cryptography and other computational-intensive algorithms. These facilities share registers with the FPU hardware. .Pp Typical kernel code does not need access to the FPU. Saving a large register file on each entry to the kernel would waste time. When kernel code uses the FPU, the current FPU state must be saved to avoid corrupting the user-mode state, and vice versa. .Pp The management of the save and restore is automatic. The processor catches accesses to the FPU registers when the non-current context tries to access them. Explicit calls are required for the allocation of the save area and the notification of the start and end of the code using the FPU. .Pp The .Fn fpu_kern_alloc_ctx function allocates the memory used by .Nm to track the use of the FPU hardware state and the related software state. The .Fn fpu_kern_alloc_ctx function requires the .Fa flags argument, which currently accepts the following flags: .Bl -tag -width ".Dv FPU_KERN_NOWAIT" -offset indent .It Dv FPU_KERN_NOWAIT Do not wait for the available memory if the request could not be satisfied without sleep. .It 0 No special handling is required. .El .Pp The function returns the allocated context area, or .Va NULL if the allocation failed. .Pp The .Fn fpu_kern_free_ctx function frees the context previously allocated by .Fn fpu_kern_alloc_ctx . .Pp The .Fn fpu_kern_enter function designates the start of the region of kernel code where the use of the FPU is allowed. Its arguments are: .Bl -tag -width ".Fa ctx" -offset indent .It Fa td Currently must be .Va curthread . .It Fa ctx The context save area previously allocated by .Fn fpu_kern_alloc_ctx and not currently in use by another call to .Fn fpu_kern_enter . .It Fa flags This argument currently accepts the following flags: .Bl -tag -width ".Dv FPU_KERN_NORMAL" -offset indent .It Dv FPU_KERN_NORMAL Indicates that the caller intends to access the full FPU state. Must be specified currently. .It Dv FPU_KERN_KTHR Indicates that no saving of the current FPU state should be performed, if the thread called .Xr fpu_kern_thread 9 function. This is intended to minimize code duplication in callers which could be used from both kernel thread and syscall contexts. The .Fn fpu_kern_leave function correctly handles such contexts. .El .El .Pp The function does not sleep or block. It could cause the .Nm Device Not Available exception during execution, and on the first FPU access after the function returns, as well as after each context switch (see Intel Software Developer Manual for the reference). Currently, no errors are defined which can be returned by .Fn fpu_kern_enter to the caller. .Pp The .Fn fpu_kern_leave function ends the region started by .Fn fpu_kern_enter . The uses of FPU in the kernel after the call to .Fn fpu_kern_leave -are erronous until the next call to +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 enables an optimization for threads which never leave to the usermode. The current thread will reuse the usermode save area for the kernel FPU state instead of requiring an explicitly allocated context. There are no flags defined for the function, and no error states that the function returns. Once this function has been called, neither .Fn fpu_kern_enter nor .Fn fpu_kern_leave is required to be called and the fpu is available for use in the calling thread. .Pp The .Fn is_fpu_kern_thread function returns the boolean indicating whether the current thread entered the mode enabled by .Fn fpu_kern_thread . There is currently no flags defined for the function, the return value is true if the current thread have the permanent FPU save area, and false otherwise. .Sh NOTES The .Nm is currently implemented only for the i386 and amd64 architectures. .Pp There is no way to handle floating point exceptions raised from kernel mode. .Pp The unused .Fa flags arguments to the .Nm functions are to be extended to allow specification of the set of the FPU hardware state used by the code region. This would allow optimizations of saving and restoring the state. .Sh AUTHORS The .Nm facitily and this manual page were written by .An Konstantin Belousov Aq Mt kib@FreeBSD.org . diff --git a/share/man/man9/hash.9 b/share/man/man9/hash.9 index 3276fd1877e3..9dade6cd1eab 100644 --- a/share/man/man9/hash.9 +++ b/share/man/man9/hash.9 @@ -1,227 +1,227 @@ .\" Copyright (c) 2001 Tobias Weingartner .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $OpenBSD: hash.9,v 1.5 2003/04/17 05:08:39 jmc Exp $ .\" $FreeBSD$ .\" .Dd June 30, 2015 .Dt HASH 9 .Os .Sh NAME .Nm hash , .Nm hash32 , .Nm hash32_buf , .Nm hash32_str , .Nm hash32_strn , .Nm hash32_stre , .Nm hash32_strne , .Nm jenkins_hash , .Nm jenkins_hash32 , .Nm murmur3_32_hash , .Nm murmur3_32_hash32 .Nd general kernel hashing functions .Sh SYNOPSIS .In sys/hash.h .Ft uint32_t .Fn hash32_buf "const void *buf" "size_t len" "uint32_t hash" .Ft uint32_t .Fn hash32_str "const void *buf" "uint32_t hash" .Ft uint32_t .Fn hash32_strn "const void *buf" "size_t len" "uint32_t hash" .Ft uint32_t .Fn hash32_stre "const void *buf" "int end" "const char **ep" "uint32_t hash" .Ft uint32_t .Fn hash32_strne "const void *buf" "size_t len" "int end" "const char **ep" "uint32_t hash" .Ft uint32_t .Fn jenkins_hash "const void *buf" "size_t len" "uint32_t hash" .Ft uint32_t .Fn jenkins_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash" .Ft uint32_t .Fn murmur3_32_hash "const void *buf" "size_t len" "uint32_t hash" .Ft uint32_t .Fn murmur3_32_hash32 "const uint32_t *buf" "size_t count" "uint32_t hash" .Sh DESCRIPTION The .Fn hash32 functions are used to give a consistent and general interface to a decent hashing algorithm within the kernel. These functions can be used to hash .Tn ASCII .Dv NUL terminated strings, as well as blocks of memory. .Pp A .Fa len argument is the length of the buffer in bytes. A .Fa count argument is the length of the buffer in 32-bit words. .Pp The .Fn hash32_buf function is used as a general buffer hashing function. The argument .Fa buf is used to pass in the location, and .Fa len is the length of the buffer in bytes. The argument .Fa hash is used to extend an existing hash, or is passed the initial value .Dv HASHINIT to start a new hash. .Pp The .Fn hash32_str function is used to hash a .Dv NUL terminated string passed in .Fa buf with initial hash value given in .Fa hash . .Pp The .Fn hash32_strn function is like the .Fn hash32_str function, except it also takes a .Fa len argument, which is the maximal length of the expected string. .Pp The .Fn hash32_stre and .Fn hash32_strne functions are helper functions used by the kernel to hash pathname components. These functions have the additional termination condition of terminating when they find a character given by .Fa end in the string to be hashed. If the argument .Fa ep is not .Dv NULL , it is set to the point in the buffer at which the hash function terminated hashing. .Pp The .Fn jenkins_hash function has same semantics as the .Fn hash32_buf , but provides more advanced hashing algorithm with better distribution. .Pp The .Fn jenkins_hash32 uses same hashing algorithm as the .Fn jenkins_hash function, but works only on .Ft uint32_t -sized arrays, thus is simplier and faster. +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. .Pp The .Fn murmur3_32_hash and .Fn murmur3_32_hash32 functions are similar to .Fn jenkins_hash and .Fn jenkins_hash32 , but implement the 32-bit version of MurmurHash3. .Sh RETURN VALUES The .Fn hash32 functions return a 32 bit hash value of the buffer or string. .Sh EXAMPLES .Bd -literal -offset indent LIST_HEAD(head, cache) *hashtbl = NULL; u_long mask = 0; void sample_init(void) { hashtbl = hashinit(numwanted, type, flags, &mask); } void sample_use(char *str, int len) { uint32_t hash; hash = hash32_str(str, HASHINIT); hash = hash32_buf(&len, sizeof(len), hash); hashtbl[hash & mask] = len; } .Ed .Sh SEE ALSO .Xr free 9 , .Xr hashinit 9 , .Xr malloc 9 .Sh LIMITATIONS The .Fn hash32 functions are only 32 bit functions. They will prove to give poor 64 bit performance, especially for the top 32 bits. At the current time, this is not seen as a great limitation, as these hash values are usually used to index into an array. Should these hash values be used for other means, this limitation should be revisited. .Sh HISTORY The .Nm functions first appeared in .Nx 1.6 . The current implementation of .Nm hash32 functions was first committed to .Ox 3.2 , and later imported to .Fx 6.1 . The .Nm jenkins_hash functions were added in .Fx 10.0 . The .Nm murmur3_32_hash functions were added in .Fx 10.1 . .Sh AUTHORS The .Nm hash32 functions were written by .An Tobias Weingartner . The .Nm jenkins_hash functions were written by .An Bob Jenkins . The .Nm murmur3_32_hash functions were written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . diff --git a/share/man/man9/lock.9 b/share/man/man9/lock.9 index 69afdc4e90f5..3ac23db944de 100644 --- a/share/man/man9/lock.9 +++ b/share/man/man9/lock.9 @@ -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 mtx_assert 9 , .Xr mutex 9 , .Xr panic 9 , .Xr rwlock 9 , .Xr sleep 9 , .Xr sx 9 , .Xr VOP_PRINT 9 .Sh AUTHORS This manual page was written by .An Chad David Aq Mt davidc@acns.ab.ca . diff --git a/share/man/man9/pci.9 b/share/man/man9/pci.9 index ac7b28b4384d..0e1024cf1850 100644 --- a/share/man/man9/pci.9 +++ b/share/man/man9/pci.9 @@ -1,904 +1,904 @@ .\" .\" Copyright (c) 2005 Bruce M Simpson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 23, 2015 .Dt PCI 9 .Os .Sh NAME .Nm pci , .Nm pci_alloc_msi , .Nm pci_alloc_msix , .Nm pci_disable_busmaster , .Nm pci_disable_io , .Nm pci_enable_busmaster , .Nm pci_enable_io , .Nm pci_find_bsf , .Nm pci_find_cap , .Nm pci_find_dbsf , .Nm pci_find_device , .Nm pci_find_extcap , .Nm pci_find_htcap , .Nm pci_find_pcie_root_port , .Nm pci_get_max_read_req , .Nm pci_get_powerstate , .Nm pci_get_vpd_ident , .Nm pci_get_vpd_readonly , .Nm pci_iov_attach , .Nm pci_iov_detach , .Nm pci_msi_count , .Nm pci_msix_count , .Nm pci_msix_pba_bar , .Nm pci_msix_table_bar , .Nm pci_pending_msix , .Nm pci_read_config , .Nm pci_release_msi , .Nm pci_remap_msix , .Nm pci_restore_state , .Nm pci_save_state , .Nm pci_set_max_read_req , .Nm pci_set_powerstate , .Nm pci_write_config , .Nm pcie_adjust_config , .Nm pcie_read_config , .Nm pcie_write_config .Nd PCI bus interface .Sh SYNOPSIS .In sys/bus.h .In dev/pci/pcireg.h .In dev/pci/pcivar.h .Ft int .Fn pci_alloc_msi "device_t dev" "int *count" .Ft int .Fn pci_alloc_msix "device_t dev" "int *count" .Ft int .Fn pci_disable_busmaster "device_t dev" .Ft int .Fn pci_disable_io "device_t dev" "int space" .Ft int .Fn pci_enable_busmaster "device_t dev" .Ft int .Fn pci_enable_io "device_t dev" "int space" .Ft device_t .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func" .Ft int .Fn pci_find_cap "device_t dev" "int capability" "int *capreg" .Ft device_t .Fn pci_find_dbsf "uint32_t domain" "uint8_t bus" "uint8_t slot" "uint8_t func" .Ft device_t .Fn pci_find_device "uint16_t vendor" "uint16_t device" .Ft int .Fn pci_find_extcap "device_t dev" "int capability" "int *capreg" .Ft int .Fn pci_find_htcap "device_t dev" "int capability" "int *capreg" .Ft device_t .Fn pci_find_pcie_root_port "device_t dev" .Ft int .Fn pci_get_max_read_req "device_t dev" .Ft int .Fn pci_get_powerstate "device_t dev" .Ft int .Fn pci_get_vpd_ident "device_t dev" "const char **identptr" .Ft int .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr" .Ft int .Fn pci_msi_count "device_t dev" .Ft int .Fn pci_msix_count "device_t dev" .Ft int .Fn pci_msix_pba_bar "device_t dev" .Ft int .Fn pci_msix_table_bar "device_t dev" .Ft int .Fn pci_pending_msix "device_t dev" "u_int index" .Ft uint32_t .Fn pci_read_config "device_t dev" "int reg" "int width" .Ft int .Fn pci_release_msi "device_t dev" .Ft int .Fn pci_remap_msix "device_t dev" "int count" "const u_int *vectors" .Ft void .Fn pci_restore_state "device_t dev" .Ft void .Fn pci_save_state "device_t dev" .Ft int .Fn pci_set_max_read_req "device_t dev" "int size" .Ft int .Fn pci_set_powerstate "device_t dev" "int state" .Ft void .Fn pci_write_config "device_t dev" "int reg" "uint32_t val" "int width" .Ft uint32_t .Fo pcie_adjust_config .Fa "device_t dev" .Fa "int reg" .Fa "uint32_t mask" .Fa "uint32_t val" .Fa "int width" .Fc .Ft uint32_t .Fn pcie_read_config "device_t dev" "int reg" "int width" .Ft void .Fn pcie_write_config "device_t dev" "int reg" "uint32_t val" "int width" .In dev/pci/pci_iov.h .Ft int .Fn pci_iov_attach "device_t dev" "nvlist_t *pf_schema" "nvlist_t *vf_schema" .Ft int .Fn pci_iov_detach "device_t dev" .Sh DESCRIPTION The .Nm set of functions are used for managing PCI devices. The functions are split into several groups: raw configuration access, locating devices, device information, device configuration, and message signaled interrupts. .Ss Raw Configuration Access The .Fn pci_read_config function is used to read data from the PCI configuration space of the device .Fa dev , at offset .Fa reg , with .Fa width specifying the size of the access. .Pp The .Fn pci_write_config function is used to write the value .Fa val to the PCI configuration space of the device .Fa dev , at offset .Fa reg , with .Fa width specifying the size of the access. .Pp The .Fn pcie_adjust_config function is used to modify the value of a register in the PCI-express capability register set of device .Fa dev . The offset .Fa reg specifies a relative offset in the register set with .Fa width specifying the size of the access. The new value of the register is computed by modifying bits set in .Fa mask to the value in .Fa val . Any bits not specified in .Fa mask are preserved. The previous value of the register is returned. .Pp The .Fn pcie_read_config function is used to read the value of a register in the PCI-express capability register set of device .Fa dev . The offset .Fa reg specifies a relative offset in the register set with .Fa width specifying the size of the access. .Pp The .Fn pcie_write_config function is used to write the value .Fa val to a register in the PCI-express capability register set of device .Fa dev . The offset .Fa reg specifies a relative offset in the register set with .Fa width specifying the size of the access. .Pp .Em NOTE : Device drivers should only use these functions for functionality that is not available via another .Fn pci function. .Ss Locating Devices The .Fn pci_find_bsf function looks up the .Vt device_t of a PCI device, given its .Fa bus , .Fa slot , and .Fa func . The .Fa slot number actually refers to the number of the device on the bus, which does not necessarily indicate its geographic location in terms of a physical slot. Note that in case the system has multiple PCI domains, the .Fn pci_find_bsf function only searches the first one. Actually, it is equivalent to: .Bd -literal -offset indent pci_find_dbsf(0, bus, slot, func); .Ed .Pp The .Fn pci_find_dbsf function looks up the .Vt device_t of a PCI device, given its .Fa domain , .Fa bus , .Fa slot , and .Fa func . The .Fa slot number actually refers to the number of the device on the bus, which does not necessarily indicate its geographic location in terms of a physical slot. .Pp The .Fn pci_find_device function looks up the .Vt device_t of a PCI device, given its .Fa vendor and .Fa device IDs. Note that there can be multiple matches for this search; this function only returns the first matching device. .Ss Device Information The .Fn pci_find_cap function is used to locate the first instance of a PCI capability register set for the device .Fa dev . The capability to locate is specified by ID via .Fa capability . Constant macros of the form .Dv PCIY_xxx for standard capability IDs are defined in .In dev/pci/pcireg.h . If the capability is found, then .Fa *capreg is set to the offset in configuration space of the capability register set, and .Fn pci_find_cap returns zero. If the capability is not found or the device does not support capabilities, .Fn pci_find_cap returns an error. .Pp The .Fn pci_find_extcap function is used to locate the first instance of a PCI-express extended capability register set for the device .Fa dev . The extended capability to locate is specified by ID via .Fa capability . Constant macros of the form .Dv PCIZ_xxx for standard extended capability IDs are defined in .In dev/pci/pcireg.h . If the extended capability is found, then .Fa *capreg is set to the offset in configuration space of the extended capability register set, and .Fn pci_find_extcap returns zero. If the extended capability is not found or the device is not a PCI-express device, .Fn pci_find_extcap returns an error. .Pp The .Fn pci_find_htcap function is used to locate the first instance of a HyperTransport capability register set for the device .Fa dev . The capability to locate is specified by type via .Fa capability . Constant macros of the form .Dv PCIM_HTCAP_xxx for standard HyperTransport capability types are defined in .In dev/pci/pcireg.h . If the capability is found, then .Fa *capreg is set to the offset in configuration space of the capability register set, and .Fn pci_find_htcap returns zero. If the capability is not found or the device is not a HyperTransport device, .Fn pci_find_htcap returns an error. .Pp The .Fn pci_find_pcie_root_port function walks up the PCI device hierarchy to locate the PCI-express root port upstream of .Fa dev . If a root port is not found, .Fn pci_find_pcie_root_port returns .Dv NULL . .Pp The .Fn pci_get_vpd_ident function is used to fetch a device's Vital Product Data .Pq VPD identifier string. If the device .Fa dev supports VPD and provides an identifier string, then .Fa *identptr is set to point at a read-only, null-terminated copy of the identifier string, and .Fn pci_get_vpd_ident returns zero. If the device does not support VPD or does not provide an identifier string, then .Fn pci_get_vpd_ident returns an error. .Pp The .Fn pci_get_vpd_readonly function is used to fetch the value of a single VPD read-only keyword for the device .Fa dev . The keyword to fetch is identified by the two character string .Fa kw . If the device supports VPD and provides a read-only value for the requested keyword, then .Fa *vptr is set to point at a read-only, null-terminated copy of the value, and .Fn pci_get_vpd_readonly returns zero. If the device does not support VPD or does not provide the requested keyword, then .Fn pci_get_vpd_readonly returns an error. .Ss Device Configuration The .Fn pci_enable_busmaster function enables PCI bus mastering for the device .Fa dev , by setting the .Dv PCIM_CMD_BUSMASTEREN bit in the .Dv PCIR_COMMAND register. The .Fn pci_disable_busmaster function clears this bit. .Pp The .Fn pci_enable_io function enables memory or I/O port address decoding for the device .Fa dev , by setting the .Dv PCIM_CMD_MEMEN or .Dv PCIM_CMD_PORTEN bit in the .Dv PCIR_COMMAND register appropriately. The .Fn pci_disable_io function clears the appropriate bit. The .Fa space argument specifies which resource is affected; this can be either .Dv SYS_RES_MEMORY or .Dv SYS_RES_IOPORT as appropriate. Device drivers should generally not use these routines directly. The PCI bus will enable decoding automatically when a .Dv SYS_RES_MEMORY or .Dv SYS_RES_IOPORT resource is activated via .Xr bus_alloc_resource 9 or .Xr bus_activate_resource 9 . .Pp The .Fn pci_get_max_read_req function returns the current maximum read request size in bytes for a PCI-express device. If the .Fa dev device is not a PCI-express device, .Fn pci_get_max_read_req returns zero. .Pp The .Fn pci_set_max_read_req sets the PCI-express maximum read request size for .Fa dev . The requested .Fa size may be adjusted, and .Fn pci_set_max_read_req returns the actual size set in bytes. If the .Fa dev device is not a PCI-express device, .Fn pci_set_max_read_req returns zero. .Pp The .Fn pci_get_powerstate function returns the current power state of the device .Fa dev . If the device does not support power management capabilities, then the default state of .Dv PCI_POWERSTATE_D0 is returned. The following power states are defined by PCI: .Bl -hang -width ".Dv PCI_POWERSTATE_UNKNOWN" .It Dv PCI_POWERSTATE_D0 State in which device is on and running. It is receiving full power from the system and delivering full functionality to the user. .It Dv PCI_POWERSTATE_D1 Class-specific low-power state in which device context may or may not be lost. Busses in this state cannot do anything to the bus, to force devices to lose context. .It Dv PCI_POWERSTATE_D2 Class-specific low-power state in which device context may or may not be lost. Attains greater power savings than .Dv PCI_POWERSTATE_D1 . Busses in this state can cause devices to lose some context. Devices .Em must be prepared for the bus to be in this state or higher. .It Dv PCI_POWERSTATE_D3 State in which the device is off and not running. Device context is lost, and power from the device can be removed. .It Dv PCI_POWERSTATE_UNKNOWN State of the device is unknown. .El .Pp The .Fn pci_set_powerstate function is used to transition the device .Fa dev to the PCI power state .Fa state . If the device does not support power management capabilities or it does not support the specific power state .Fa state , then the function will fail with .Er EOPNOTSUPP . .Pp The .Fn pci_iov_attach function is used to advertise that the given device .Pq and associated device driver supports PCI Single-Root I/O Virtualization .Pq SR-IOV . A driver that supports SR-IOV must implement the .Xr PCI_IOV_INIT 9 , .Xr PCI_IOV_ADD_VF 9 and .Xr PCI_IOV_UNINIT 9 methods. This function should be called during the .Xr DEVICE_ATTACH 9 method. If this function returns an error, it is recommended that the device driver still successfully attaches, but runs with SR-IOV disabled. The .Fa pf_schema and .Fa vf_schema parameters are used to define what device-specific configuration parameters the device driver accepts when SR-IOV is enabled for the Physical Function .Pq PF and for individual Virtual Functions .Pq VFs respectively. See .Xr pci_iov_schema 9 for details on how to construct the schema. If either the .Pa pf_schema or .Pa vf_schema is invalid or specifies parameter names that conflict with parameter names that are already in use, .Fn pci_iov_attach will return an error and SR-IOV will not be available on the PF device. If a driver does not accept configuration parameters for either the PF device or the VF devices, the driver must pass an empty schema for that device. The SR-IOV infrastructure takes ownership of the .Fa pf_schema and .Fa vf_schema and is responsible for freeing them. The driver must never free the schemas itself. .Pp The .Fn pci_iov_detach function is used to advise the SR-IOV infrastructure that the driver for the given device is attempting to detach and that all SR-IOV resources for the device must be released. This function must be called during the .Xr DEVICE_DETACH 9 method if .Fn pci_iov_attach was successfully called on the device and .Fn pci_iov_detach has not subsequently been called on the device and returned no error. If this function returns an error, the .Xr DEVICE_DETACH 9 method must fail and return an error, as detaching the PF driver while VF devices are active would cause system instability. This function is safe to call and will always succeed if .Fn pci_iov_attach previously failed with an error on the given device, or if .Fn pci_iov_attach was never called on the device. .Pp The .Fn pci_save_state and .Fn pci_restore_state functions can be used by a device driver to save and restore standard PCI config registers. The .Fn pci_save_state function must be invoked while the device has valid state before .Fn pci_restore_state can be used. If the device is not in the fully-powered state .Pq Dv PCI_POWERSTATE_D0 when .Fn pci_restore_state is invoked, then the device will be transitioned to .Dv PCI_POWERSTATE_D0 before any config registers are restored. .Ss Message Signaled Interrupts Message Signaled Interrupts .Pq MSI and Enhanced Message Signaled Interrupts .Pq MSI-X are PCI capabilities that provide an alternate method for PCI devices to signal interrupts. The legacy INTx interrupt is available to PCI devices as a .Dv SYS_RES_IRQ resource with a resource ID of zero. MSI and MSI-X interrupts are available to PCI devices as one or more .Dv SYS_RES_IRQ resources with resource IDs greater than zero. A driver must ask the PCI bus to allocate MSI or MSI-X interrupts using .Fn pci_alloc_msi or .Fn pci_alloc_msix before it can use MSI or MSI-X .Dv SYS_RES_IRQ resources. A driver is not allowed to use the legacy INTx .Dv SYS_RES_IRQ resource if MSI or MSI-X interrupts have been allocated, and attempts to allocate MSI or MSI-X interrupts will fail if the driver is currently using the legacy INTx .Dv SYS_RES_IRQ resource. A driver is only allowed to use either MSI or MSI-X, but not both. .Pp The .Fn pci_msi_count function returns the maximum number of MSI messages supported by the device .Fa dev . If the device does not support MSI, then .Fn pci_msi_count returns zero. .Pp The .Fn pci_alloc_msi function attempts to allocate .Fa *count MSI messages for the device .Fa dev . The .Fn pci_alloc_msi function may allocate fewer messages than requested for various reasons including requests for more messages than the device .Fa dev supports, or if the system has a shortage of available MSI messages. On success, .Fa *count is set to the number of messages allocated and .Fn pci_alloc_msi returns zero. The .Dv SYS_RES_IRQ resources for the allocated messages will be available at consecutive resource IDs beginning with one. If .Fn pci_alloc_msi is not able to allocate any messages, it returns an error. Note that MSI only supports message counts that are powers of two; requests to allocate a non-power of two count of messages will fail. .Pp The .Fn pci_release_msi function is used to release any allocated MSI or MSI-X messages back to the system. If any MSI or MSI-X .Dv SYS_RES_IRQ resources are allocated by the driver or have a configured interrupt handler, this function will fail with .Er EBUSY . The .Fn pci_release_msi function returns zero on success and an error on failure. .Pp The .Fn pci_msix_count function returns the maximum number of MSI-X messages supported by the device .Fa dev . If the device does not support MSI-X, then .Fn pci_msix_count returns zero. .Pp The .Fn pci_msix_pba_bar function returns the offset in configuration space of the Base Address Register .Pq BAR containing the MSI-X Pending Bit Array (PBA) for device .Fa dev . The returned value can be used as the resource ID with .Xr bus_alloc_resource 9 and .Xr bus_release_resource 9 to allocate the BAR. If the device does not support MSI-X, then .Fn pci_msix_pba_bar returns -1. .Pp The .Fn pci_msix_table_bar function returns the offset in configuration space of the BAR containing the MSI-X vector table for device .Fa dev . The returned value can be used as the resource ID with .Xr bus_alloc_resource 9 and .Xr bus_release_resource 9 to allocate the BAR. If the device does not support MSI-X, then .Fn pci_msix_table_bar returns -1. .Pp The .Fn pci_alloc_msix function attempts to allocate .Fa *count MSI-X messages for the device .Fa dev . The .Fn pci_alloc_msix function may allocate fewer messages than requested for various reasons including requests for more messages than the device .Fa dev supports, or if the system has a shortage of available MSI-X messages. On success, .Fa *count is set to the number of messages allocated and .Fn pci_alloc_msix returns zero. For MSI-X messages, the resource ID for each .Dv SYS_RES_IRQ resource identifies the index in the MSI-X table of the corresponding message. A resource ID of one maps to the first index of the MSI-X table; a resource ID two identifies the second index in the table, etc. The .Fn pci_alloc_msix function assigns the .Fa *count messages allocated to the first .Fa *count -table indicies. +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 .An -nosplit This manual page was written by .An Bruce M Simpson Aq Mt bms@FreeBSD.org and .An John Baldwin Aq Mt jhb@FreeBSD.org . .Sh BUGS The kernel PCI code has a number of references to .Dq "slot numbers" . These do not refer to the geographic location of PCI devices, but to the device number assigned by the combination of the PCI IDSEL mechanism and the platform firmware. This should be taken note of when working with the kernel PCI code. .Pp The PCI bus driver should allocate the MSI-X vector table and PBA internally as necessary rather than requiring the caller to do so. diff --git a/share/man/man9/sysctl.9 b/share/man/man9/sysctl.9 index ba1ffd9f2c8e..097cc97df877 100644 --- a/share/man/man9/sysctl.9 +++ b/share/man/man9/sysctl.9 @@ -1,852 +1,852 @@ .\" .\" Copyright (c) 2006 Robert N. M. Watson .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 23, 2015 .Dt SYSCTL 9 .Os .Sh NAME .Nm SYSCTL_DECL , .Nm SYSCTL_ADD_INT , .Nm SYSCTL_ADD_LONG , .Nm SYSCTL_ADD_NODE , .Nm SYSCTL_ADD_OPAQUE , .Nm SYSCTL_ADD_PROC , .Nm SYSCTL_ADD_QUAD , .Nm SYSCTL_ADD_ROOT_NODE , .Nm SYSCTL_ADD_S8 , .Nm SYSCTL_ADD_S16 , .Nm SYSCTL_ADD_S32 , .Nm SYSCTL_ADD_S64 , .Nm SYSCTL_ADD_STRING , .Nm SYSCTL_ADD_STRUCT , .Nm SYSCTL_ADD_U8 , .Nm SYSCTL_ADD_U16 , .Nm SYSCTL_ADD_U32 , .Nm SYSCTL_ADD_U64 , .Nm SYSCTL_ADD_UAUTO , .Nm SYSCTL_ADD_UINT , .Nm SYSCTL_ADD_ULONG , .Nm SYSCTL_ADD_UQUAD , .Nm SYSCTL_CHILDREN , .Nm SYSCTL_STATIC_CHILDREN , .Nm SYSCTL_NODE_CHILDREN , .Nm SYSCTL_PARENT , .Nm SYSCTL_INT , .Nm SYSCTL_LONG , .Nm SYSCTL_NODE , .Nm SYSCTL_OPAQUE , .Nm SYSCTL_PROC , .Nm SYSCTL_QUAD , .Nm SYSCTL_ROOT_NODE , .Nm SYSCTL_S8 , .Nm SYSCTL_S16 , .Nm SYSCTL_S32 , .Nm SYSCTL_S64 , .Nm SYSCTL_STRING , .Nm SYSCTL_STRUCT , .Nm SYSCTL_U8 , .Nm SYSCTL_U16 , .Nm SYSCTL_U32 , .Nm SYSCTL_U64 , .Nm SYSCTL_UINT , .Nm SYSCTL_ULONG , .Nm SYSCTL_UQUAD .Nd Dynamic and static sysctl MIB creation functions .Sh SYNOPSIS .In sys/types.h .In sys/sysctl.h .Fn SYSCTL_DECL name .Ft struct sysctl_oid * .Fo SYSCTL_ADD_INT .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int *ptr" .Fa "int val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_LONG .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "long *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_NODE .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_OPAQUE .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *ptr" .Fa "intptr_t len" .Fa "const char *format" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_PROC .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *arg1" .Fa "intptr_t arg2" .Fa "int (*handler) (SYSCTL_HANDLERARGS)" .Fa "const char *format" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_QUAD .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int64_t *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_ROOT_NODE .Fa "struct sysctl_ctx_list *ctx" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int (*handler)(SYSCTL_HANDLER_ARGS)" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S8 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int8_t *ptr" .Fa "int8_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S16 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int16_t *ptr" .Fa "int16_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S32 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int32_t *ptr" .Fa "int32_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_S64 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "int64_t *ptr" .Fa "int64_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_STRING .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "char *ptr" .Fa "intptr_t len" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_STRUCT .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *ptr" .Fa struct_type .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U8 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint8_t *ptr" .Fa "uint8_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U16 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint16_t *ptr" .Fa "uint16_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U32 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint32_t *ptr" .Fa "uint32_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_U64 .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint64_t *ptr" .Fa "uint64_t val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_UINT .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "unsigned int *ptr" .Fa "unsigned int val" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_ULONG .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "unsigned long *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_UQUAD .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "uint64_t *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_ADD_UAUTO .Fa "struct sysctl_ctx_list *ctx" .Fa "struct sysctl_oid_list *parent" .Fa "int number" .Fa "const char *name" .Fa "int ctlflags" .Fa "void *ptr" .Fa "const char *descr" .Fc .Ft struct sysctl_oid_list * .Fo SYSCTL_CHILDREN .Fa "struct sysctl_oid *oidp" .Fc .Ft struct sysctl_oid_list * .Fo SYSCTL_STATIC_CHILDREN .Fa "struct sysctl_oid_list OID_NAME" .Fc .Ft struct sysctl_oid_list * .Fo SYSCTL_NODE_CHILDREN .Fa "parent" .Fa "name" .Fc .Ft struct sysctl_oid * .Fo SYSCTL_PARENT .Fa "struct sysctl_oid *oid" .Fc .Fn SYSCTL_INT parent number name ctlflags ptr val descr .Fn SYSCTL_LONG parent number name ctlflags ptr val descr .Fn SYSCTL_NODE parent number name ctlflags handler descr .Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr .Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr .Fn SYSCTL_QUAD parent number name ctlflags ptr val descr .Fn SYSCTL_ROOT_NODE number name ctlflags handler descr .Fn SYSCTL_S8 parent number name ctlflags ptr val descr .Fn SYSCTL_S16 parent number name ctlflags ptr val descr .Fn SYSCTL_S32 parent number name ctlflags ptr val descr .Fn SYSCTL_S64 parent number name ctlflags ptr val descr .Fn SYSCTL_STRING parent number name ctlflags arg len descr .Fn SYSCTL_STRUCT parent number name ctlflags ptr struct_type descr .Fn SYSCTL_U8 parent number name ctlflags ptr val descr .Fn SYSCTL_U16 parent number name ctlflags ptr val descr .Fn SYSCTL_U32 parent number name ctlflags ptr val descr .Fn SYSCTL_U64 parent number name ctlflags ptr val descr .Fn SYSCTL_UINT parent number name ctlflags ptr val descr .Fn SYSCTL_ULONG parent number name ctlflags ptr val descr .Fn SYSCTL_UQUAD parent number name ctlflags ptr val descr .Sh DESCRIPTION The .Nm SYSCTL kernel interface allows dynamic or static creation of .Xr sysctl 8 MIB entries. All static sysctls are automatically destroyed when the module which they are part of is unloaded. Most top level categories are created statically and are available to all kernel code and its modules. .Sh DESCRIPTION OF ARGUMENTS .Bl -tag -width ctlflags .It Fa ctx Pointer to sysctl context or NULL, if no context. See .Xr sysctl_ctx_init 9 for how to create a new sysctl context. Programmers are strongly advised to use contexts to organize the dynamic OIDs which they create because when a context is destroyed all belonging sysctls are destroyed as well. This makes the sysctl cleanup code much simpler. Else deletion of all created OIDs is required at module unload. .It Fa parent A pointer to a .Li struct sysctl_oid_list , which is the head of the parent's list of children. This pointer is retrieved using the .Fn SYSCTL_STATIC_CHILDREN macro for static sysctls and the .Fn SYSCTL_CHILDREN macro for dynamic sysctls. The .Fn SYSCTL_PARENT macro can be used to get the parent of an OID. The macro returns NULL if there is no parent. .It Fa number The OID number that will be assigned to this OID. In almost all cases this should be set to .Dv OID_AUTO , which will result in the assignment of the next available OID number. .It Fa name The name of the OID. The newly created OID will contain a copy of the name. .It Fa ctlflags A bit mask of sysctl control flags. See the section below describing all the control flags. .It Fa arg1 First callback argument for procedure sysctls. .It Fa arg2 Second callback argument for procedure sysctls. .It Fa len The length of the data pointed to by the .Fa ptr argument. For string type OIDs a length of zero means that .Xr strlen 3 will be used to get the length of the string at each access to the OID. .It Fa ptr Pointer to sysctl variable or string data. For sysctl values the pointer can be SYSCTL_NULL_XXX_PTR which means the OID is read-only and the returned value should be taken from the .Fa val argument. .It Fa val If the .Fa ptr argument is SYSCTL_NULL_XXX_PTR, gives the constant value returned by this OID. Else this argument is not used. .It Fa struct_type Name of structure type. .It Fa handler A pointer to the function that is responsible for handling read and write requests to this OID. There are several standard handlers that support operations on nodes, integers, strings and opaque objects. It is possible to define custom handlers using the .Fn SYSCTL_PROC macro or the .Fn SYSCTL_ADD_PROC function. .It Fa format A pointer to a string which specifies the format of the OID in a symbolic way. This format is used as a hint by .Xr sysctl 8 to apply proper data formatting for display purposes. .Pp Current formats: .Bl -tag -width "S,TYPE" -compact -offset indent .It Cm N node .It Cm A .Li "char *" .It Cm I .Li "int" .It Cm IK Ns Op Ar n temperature in Kelvin, multiplied by an optional single digit power of ten scaling factor: 1 (default) gives deciKelvin, 0 gives Kelvin, 3 gives milliKelvin .It Cm IU .Li "unsigned int" .It Cm L .Li "long" .It Cm LU .Li "unsigned long" .It Cm Q .Li "quad_t" .It Cm QU .Li "u_quad_t" .It Cm "S,TYPE" .Li "struct TYPE" structures .El .It Fa descr A pointer to a textual description of the OID. .El .Sh CREATING ROOT NODES Sysctl MIBs or OIDs are created in a hierarchical tree. The nodes at the bottom of the tree are called root nodes, and have no parent OID. To create bottom tree nodes the .Fn SYSCTL_ROOT_NODE macro or the .Fn SYSCTL_ADD_ROOT_NODE function needs to be used. By default all static sysctl node OIDs are global and need a .Fn SYSCTL_DECL statement prior to their .Fn SYSCTL_NODE definition statement, typically in a so-called header file. .Sh CREATING SYSCTL STRINGS Zero terminated character strings sysctls are created either using the .Fn SYSCTL_STRING macro or the .Fn SYSCTL_ADD_STRING function. If the .Fa len argument in zero, the string length is computed at every access to the OID using .Xr strlen 3 . .Sh CREATING OPAQUE SYSCTLS The .Fn SYSCTL_OPAQUE or .Fn SYSCTL_STRUCT macros or the .Fn SYSCTL_ADD_OPAQUE or .Fn SYSCTL_ADD_STRUCT functions create an OID that handle any chunk of data of the size specified by the .Fa len argument and data pointed to by the .Fa ptr argument. When using the structure version the type is encoded as part of the created sysctl. .Sh CREATING CUSTOM SYSCTLS The .Fn SYSCTL_PROC macro and the .Fn SYSCTL_ADD_PROC function create OIDs with the specified .Pa handler function. The handler is responsible for handling all read and write requests to the OID. This OID type is especially useful if the kernel data is not easily accessible, or needs to be processed before exporting. .Sh CREATING A STATIC SYSCTL Static sysctls are declared using one of the .Fn SYSCTL_INT , .Fn SYSCTL_LONG , .Fn SYSCTL_NODE , .Fn SYSCTL_OPAQUE , .Fn SYSCTL_PROC , .Fn SYSCTL_QUAD , .Fn SYSCTL_ROOT_NODE , .Fn SYSCTL_S8 , .Fn SYSCTL_S16 , .Fn SYSCTL_S32 , .Fn SYSCTL_S64 , .Fn SYSCTL_STRING , .Fn SYSCTL_STRUCT , .Fn SYSCTL_U8 , .Fn SYSCTL_U16 , .Fn SYSCTL_U32 , .Fn SYSCTL_U64 , .Fn SYSCTL_UINT , .Fn SYSCTL_ULONG or .Fn SYSCTL_UQUAD macros. .Sh CREATING A DYNAMIC SYSCTL Dynamic nodes are created using one of the .Fn SYSCTL_ADD_INT , .Fn SYSCTL_ADD_LONG , .Fn SYSCTL_ADD_NODE , .Fn SYSCTL_ADD_OPAQUE , .Fn SYSCTL_ADD_PROC , .Fn SYSCTL_ADD_QUAD , .Fn SYSCTL_ADD_ROOT_NODE , .Fn SYSCTL_ADD_S8 , .Fn SYSCTL_ADD_S16 , .Fn SYSCTL_ADD_S32 , .Fn SYSCTL_ADD_S64 , .Fn SYSCTL_ADD_STRING , .Fn SYSCTL_ADD_STRUCT , .Fn SYSCTL_ADD_U8 , .Fn SYSCTL_ADD_U16 , .Fn SYSCTL_ADD_U32 , .Fn SYSCTL_ADD_U64 , .Fn SYSCTL_ADD_UAUTO , .Fn SYSCTL_ADD_UINT , .Fn SYSCTL_ADD_ULONG , or .Fn SYSCTL_UQUAD functions. See .Xr sysctl_remove_oid 9 or .Xr sysctl_ctx_free 9 for more information on how to destroy a dynamically created OID. .Sh CONTROL FLAGS For most of the above functions and macros, declaring a type as part of the access flags is not necessary \[em] however, when declaring a sysctl implemented by a function, including a type in the access mask is required: .Bl -tag -width ".Dv CTLTYPE_NOFETCH" .It Dv CTLTYPE_NODE This is a node intended to be a parent for other nodes. .It Dv CTLTYPE_INT This is a signed integer. .It Dv CTLTYPE_STRING This is a nul-terminated string stored in a character array. .It Dv CTLTYPE_S8 This is an 8-bit signed integer. .It Dv CTLTYPE_S16 This is a 16-bit signed integer. .It Dv CTLTYPE_S32 This is a 32-bit signed integer. .It Dv CTLTYPE_S64 This is a 64-bit signed integer. .It Dv CTLTYPE_OPAQUE This is an opaque data structure. .It Dv CTLTYPE_STRUCT Alias for .Dv CTLTYPE_OPAQUE . .It Dv CTLTYPE_U8 This is an 8-bit unsigned integer. .It Dv CTLTYPE_U16 This is a 16-bit unsigned integer. .It Dv CTLTYPE_U32 This is a 32-bit unsigned integer. .It Dv CTLTYPE_U64 This is a 64-bit unsigned integer. .It Dv CTLTYPE_UINT This is an unsigned integer. .It Dv CTLTYPE_LONG This is a signed long. .It Dv CTLTYPE_ULONG This is an unsigned long. .El .Pp All sysctl types except for new node declarations require one of the following flags to be set indicating the read and write disposition of the sysctl: .Bl -tag -width ".Dv CTLFLAG_ANYBODY" .It Dv CTLFLAG_RD This is a read-only sysctl. .It Dv CTLFLAG_RDTUN This is a read-only sysctl and tunable which is tried fetched once -from the system enviroment early during module load or system boot. +from the system environment early during module load or system boot. .It Dv CTLFLAG_WR This is a writable sysctl. .It Dv CTLFLAG_RW This sysctl is readable and writable. .It Dv CTLFLAG_RWTUN This is a readable and writeable sysctl and tunable which is tried -fetched once from the system enviroment early during module load or +fetched once from the system environment early during module load or system boot. .It Dv CTLFLAG_NOFETCH In case the node is marked as a tunable using the CTLFLAG_[XX]TUN, this flag will prevent fetching the initial value from the system environment. Typically this flag should only be used for very early low level system setup code, and not by common drivers and modules. .El .Pp Additionally, any of the following optional flags may also be specified: .Bl -tag -width ".Dv CTLFLAG_ANYBODY" .It Dv CTLFLAG_ANYBODY Any user or process can write to this sysctl. .It Dv CTLFLAG_SECURE This sysctl can be written to only if the effective securelevel of the process is \[<=] 0. .It Dv CTLFLAG_PRISON This sysctl can be written to by processes in .Xr jail 2 . .It Dv CTLFLAG_SKIP When iterating the sysctl name space, do not list this sysctl. .It Dv CTLFLAG_TUN Advisory flag that a system tunable also exists for this variable. The initial sysctl value is tried fetched once from the system -enviroment early during module load or system boot. +environment early during module load or system boot. .It Dv CTLFLAG_DYN Dynamically created OIDs automatically get this flag set. .It Dv CTLFLAG_VNET OID references a VIMAGE-enabled variable. .El .Sh EXAMPLES Sample use of .Fn SYSCTL_DECL to declare the .Va security sysctl tree for use by new nodes: .Bd -literal -offset indent SYSCTL_DECL(_security); .Ed .Pp Examples of integer, opaque, string, and procedure sysctls follow: .Bd -literal -offset indent /* * Example of a constant integer value. Notice that the control * flags are CTLFLAG_RD, the variable pointer is SYSCTL_NULL_INT_PTR, * and the value is declared. */ SYSCTL_INT(_debug_sizeof, OID_AUTO, bio, CTLFLAG_RD, SYSCTL_NULL_INT_PTR, sizeof(struct bio), "sizeof(struct bio)"); /* * Example of a variable integer value. Notice that the control * flags are CTLFLAG_RW, the variable pointer is set, and the * value is 0. */ static int doingcache = 1; /* 1 => enable the cache */ SYSCTL_INT(_debug, OID_AUTO, vfscache, CTLFLAG_RW, &doingcache, 0, "Enable name cache"); /* * Example of a variable string value. Notice that the control * flags are CTLFLAG_RW, that the variable pointer and string * size are set. Unlike newer sysctls, this older sysctl uses a * static oid number. */ char kernelname[MAXPATHLEN] = "/kernel"; /* XXX bloat */ SYSCTL_STRING(_kern, KERN_BOOTFILE, bootfile, CTLFLAG_RW, kernelname, sizeof(kernelname), "Name of kernel file booted"); /* * Example of an opaque data type exported by sysctl. Notice that * the variable pointer and size are provided, as well as a format * string for sysctl(8). */ -static l_fp pps_freq; /* scaled 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 .Pp The following is an example of how to create a new top-level category and how to hook up another subtree to an existing static node. This example does not use contexts, which results in tedious management of all intermediate oids, as they need to be freed later on: .Bd -literal -offset indent #include ... /* * Need to preserve pointers to newly created subtrees, * to be able to free them later: */ static struct sysctl_oid *root1; static struct sysctl_oid *root2; static struct sysctl_oid *oidp; static int a_int; static char *string = "dynamic sysctl"; ... root1 = SYSCTL_ADD_ROOT_NODE(NULL, OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); oidp = SYSCTL_ADD_INT(NULL, SYSCTL_CHILDREN(root1), OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); ... root2 = SYSCTL_ADD_NODE(NULL, SYSCTL_STATIC_CHILDREN(_debug), OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); oidp = SYSCTL_ADD_STRING(NULL, SYSCTL_CHILDREN(root2), OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); .Ed .Pp This example creates the following subtrees: .Bd -literal -offset indent debug.newtree.newstring newtree.newint .Ed .Pp .Em "Care should be taken to free all OIDs once they are no longer needed!" .Sh SYSCTL NAMING When adding, modifying, or removing sysctl names, it is important to be aware that these interfaces may be used by users, libraries, applications, or documentation (such as published books), and are implicitly published application interfaces. As with other application interfaces, caution must be taken not to break existing applications, and to think about future use of new name spaces so as to avoid the need to rename or remove interfaces that might be depended on in the future. .Pp The semantics chosen for a new sysctl should be as clear as possible, and the name of the sysctl must closely reflect its semantics. Therefore the sysctl name deserves a fair amount of consideration. It should be short but yet representative of the sysctl meaning. If the name consists of several words, they should be separated by underscore characters, as in .Va compute_summary_at_mount . Underscore characters may be omitted only if the name consists of not more than two words, each being not longer than four characters, as in .Va bootfile . For boolean sysctls, negative logic should be totally avoided. That is, do not use names like .Va no_foobar or .Va foobar_disable . They are confusing and lead to configuration errors. Use positive logic instead: .Va foobar , .Va foobar_enable . .Pp A temporary sysctl node OID that should not be relied upon must be designated as such by a leading underscore character in its name. For example: .Va _dirty_hack . .Sh SEE ALSO .Xr sysctl 3 , .Xr sysctl 8 , .Xr sysctl_add_oid 9 , .Xr sysctl_ctx_free 9 , .Xr sysctl_ctx_init 9 , .Xr sysctl_remove_oid 9 .Sh HISTORY The .Xr sysctl 8 utility first appeared in .Bx 4.4 . .Sh AUTHORS .An -nosplit The .Nm sysctl implementation originally found in .Bx has been extensively rewritten by .An Poul-Henning Kamp in order to add support for name lookups, name space iteration, and dynamic addition of MIB nodes. .Pp This man page was written by .An Robert N. M. Watson . .Sh SECURITY CONSIDERATIONS When creating new sysctls, careful attention should be paid to the security implications of the monitoring or management interface being created. Most sysctls present in the kernel are read-only or writable only by the superuser. Sysctls exporting extensive information on system data structures and operation, especially those implemented using procedures, will wish to implement access control to limit the undesired exposure of information about other processes, network connections, etc. .Pp The following top level sysctl name spaces are commonly used: .Bl -tag -width ".Va regression" .It Va compat Compatibility layer information. .It Va debug Debugging information. Various name spaces exist under .Va debug . .It Va hw Hardware and device driver information. .It Va kern Kernel behavior tuning; generally deprecated in favor of more specific name spaces. .It Va machdep Machine-dependent configuration parameters. .It Va net Network subsystem. Various protocols have name spaces under .Va net . .It Va regression Regression test configuration and information. .It Va security Security and security-policy configuration and information. .It Va sysctl Reserved name space for the implementation of sysctl. .It Va user Configuration settings relating to user application behavior. Generally, configuring applications using kernel sysctls is discouraged. .It Va vfs Virtual file system configuration and information. .It Va vm Virtual memory subsystem configuration and information. .El diff --git a/share/man/man9/timeout.9 b/share/man/man9/timeout.9 index 3f5b4dc82ccf..ee309429e80b 100644 --- a/share/man/man9/timeout.9 +++ b/share/man/man9/timeout.9 @@ -1,846 +1,846 @@ .\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ .\" .\" Copyright (c) 1996 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Paul Kranenburg. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 14, 2015 .Dt TIMEOUT 9 .Os .Sh NAME .Nm callout_active , .Nm callout_deactivate , .Nm callout_async_drain , .Nm callout_drain , .Nm callout_handle_init , .Nm callout_init , .Nm callout_init_mtx , .Nm callout_init_rm , .Nm callout_init_rw , .Nm callout_pending , .Nm callout_reset , .Nm callout_reset_curcpu , .Nm callout_reset_on , .Nm callout_reset_sbt , .Nm callout_reset_sbt_curcpu , .Nm callout_reset_sbt_on , .Nm callout_schedule , .Nm callout_schedule_curcpu , .Nm callout_schedule_on , .Nm callout_schedule_sbt , .Nm callout_schedule_sbt_curcpu , .Nm callout_schedule_sbt_on , .Nm callout_stop , .Nm timeout , .Nm untimeout .Nd execute a function after a specified length of time .Sh SYNOPSIS .In sys/types.h .In sys/systm.h .Bd -literal typedef void timeout_t (void *); .Ed .Ft int .Fn callout_active "struct callout *c" .Ft void .Fn callout_deactivate "struct callout *c" .Ft int .Fn callout_async_drain "struct callout *c" "timeout_t *drain" .Ft int .Fn callout_drain "struct callout *c" .Ft void .Fn callout_handle_init "struct callout_handle *handle" .Bd -literal struct callout_handle handle = CALLOUT_HANDLE_INITIALIZER(&handle); .Ed .Ft void .Fn callout_init "struct callout *c" "int mpsafe" .Ft void .Fn callout_init_mtx "struct callout *c" "struct mtx *mtx" "int flags" .Ft void .Fn callout_init_rm "struct callout *c" "struct rmlock *rm" "int flags" .Ft void .Fn callout_init_rw "struct callout *c" "struct rwlock *rw" "int flags" .Ft int .Fn callout_pending "struct callout *c" .Ft int .Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" .Ft int .Fn callout_reset_curcpu "struct callout *c" "int ticks" "timeout_t *func" \ "void *arg" .Ft int .Fn callout_reset_on "struct callout *c" "int ticks" "timeout_t *func" \ "void *arg" "int cpu" .Ft int .Fn callout_reset_sbt "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "timeout_t *func" "void *arg" "int flags" .Ft int .Fn callout_reset_sbt_curcpu "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "timeout_t *func" "void *arg" "int flags" .Ft int .Fn callout_reset_sbt_on "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "timeout_t *func" "void *arg" "int cpu" "int flags" .Ft int .Fn callout_schedule "struct callout *c" "int ticks" .Ft int .Fn callout_schedule_curcpu "struct callout *c" "int ticks" .Ft int .Fn callout_schedule_on "struct callout *c" "int ticks" "int cpu" .Ft int .Fn callout_schedule_sbt "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "int flags" .Ft int .Fn callout_schedule_sbt_curcpu "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "int flags" .Ft int .Fn callout_schedule_sbt_on "struct callout *c" "sbintime_t sbt" \ "sbintime_t pr" "int cpu" "int flags" .Ft int .Fn callout_stop "struct callout *c" .Ft struct callout_handle .Fn timeout "timeout_t *func" "void *arg" "int ticks" .Ft void .Fn untimeout "timeout_t *func" "void *arg" "struct callout_handle handle" .Sh DESCRIPTION The .Nm callout API is used to schedule a call to an arbitrary function at a specific time in the future. Consumers of this API are required to allocate a callout structure .Pq struct callout for each pending function invocation. This structure stores state about the pending function invocation including the function to be called and the time at which the function should be invoked. Pending function calls can be cancelled or rescheduled to a different time. In addition, a callout structure may be reused to schedule a new function call after a scheduled call is completed. .Pp Callouts only provide a single-shot mode. If a consumer requires a periodic timer, it must explicitly reschedule each function call. This is normally done by rescheduling the subsequent call within the called function. .Pp Callout functions must not sleep. They may not acquire sleepable locks, wait on condition variables, perform blocking allocation requests, or invoke any other action that might sleep. .Pp Each callout structure must be initialized by .Fn callout_init , .Fn callout_init_mtx , .Fn callout_init_rm , or .Fn callout_init_rw before it is passed to any of the other callout functions. The .Fn callout_init function initializes a callout structure in .Fa c that is not associated with a specific lock. If the .Fa mpsafe argument is zero, the callout structure is not considered to be .Dq multi-processor safe ; and the Giant lock will be acquired before calling the callout function and released when the callout function returns. .Pp The .Fn callout_init_mtx , .Fn callout_init_rm , and .Fn callout_init_rw functions initialize a callout structure in .Fa c that is associated with a specific lock. The lock is specified by the .Fa mtx , .Fa rm , or .Fa rw parameter. The associated lock must be held while stopping or rescheduling the callout. The callout subsystem acquires the associated lock before calling the callout function and releases it after the function returns. If the callout was cancelled while the callout subsystem waited for the associated lock, the callout function is not called, and the associated lock is released. This ensures that stopping or rescheduling the callout will abort any previously scheduled invocation. .Pp Only regular mutexes may be used with .Fn callout_init_mtx ; spin mutexes are not supported. A sleepable read-mostly lock .Po one initialized with the .Dv RM_SLEEPABLE flag .Pc may not be used with .Fn callout_init_rm . Similarly, other sleepable lock types such as .Xr sx 9 and .Xr lockmgr 9 cannot be used with callouts because sleeping is not permitted in the callout subsystem. .Pp These .Fa flags may be specified for .Fn callout_init_mtx , .Fn callout_init_rm , or .Fn callout_init_rw : .Bl -tag -width ".Dv CALLOUT_RETURNUNLOCKED" .It Dv CALLOUT_RETURNUNLOCKED The callout function will release the associated lock itself, so the callout subsystem should not attempt to unlock it after the callout function returns. .It Dv CALLOUT_SHAREDLOCK The lock is only acquired in read mode when running the callout handler. This flag is ignored by .Fn callout_init_mtx . .El .Pp The function .Fn callout_stop cancels a callout .Fa c if it is currently pending. -If the callout is pending and successfuly stopped, then +If the callout is pending and successfully stopped, then .Fn callout_stop returns a value of one. If the callout is not set, or has already been serviced, then negative one is returned. If the callout is currently being serviced and cannot be stopped, then zero will be returned. If the callout has an associated lock, then that lock must be held when this function is called. .Pp The function .Fn callout_async_drain is identical to .Fn callout_stop with one difference. When .Fn callout_async_drain returns zero it will arrange for the function .Fa drain to be called using the same argument given to the .Fn callout_reset function. .Fn callout_async_drain If the callout has an associated lock, then that lock must be held when this function is called. Note that when stopping multiple callouts that use the same lock it is possible to get multiple return's of zero and multiple calls to the .Fa drain function, depending upon which CPU's the callouts are running. The .Fa drain function itself is called from the context of the completing callout i.e. softclock or hardclock, just like a callout itself. p .Pp The function .Fn callout_drain is identical to .Fn callout_stop except that it will wait for the callout .Fa c to complete if it is already in progress. This function MUST NOT be called while holding any locks on which the callout might block, or deadlock will result. Note that if the callout subsystem has already begun processing this callout, then the callout function may be invoked before .Fn callout_drain returns. However, the callout subsystem does guarantee that the callout will be fully stopped before .Fn callout_drain returns. .Pp The .Fn callout_reset and .Fn callout_schedule function families schedule a future function invocation for callout .Fa c . If .Fa c already has a pending callout, it is cancelled before the new invocation is scheduled. These functions return a value of one if a pending callout was cancelled and zero if there was no pending callout. If the callout has an associated lock, then that lock must be held when any of these functions are called. .Pp The time at which the callout function will be invoked is determined by either the .Fa ticks argument or the .Fa sbt , .Fa pr , and .Fa flags arguments. When .Fa ticks is used, the callout is scheduled to execute after .Fa ticks Ns No /hz seconds. Non-positive values of .Fa ticks are silently converted to the value .Sq 1 . .Pp The .Fa sbt , .Fa pr , and .Fa flags arguments provide more control over the scheduled time including support for higher resolution times, specifying the precision of the scheduled time, and setting an absolute deadline instead of a relative timeout. The callout is scheduled to execute in a time window which begins at the time specified in .Fa sbt and extends for the amount of time specified in .Fa pr . If .Fa sbt specifies a time in the past, the window is adjusted to start at the current time. A non-zero value for .Fa pr allows the callout subsystem to coalesce callouts scheduled close to each other into fewer timer interrupts, reducing processing overhead and power consumption. These .Fa flags may be specified to adjust the interpretation of .Fa sbt and .Fa pr : .Bl -tag -width ".Dv C_DIRECT_EXEC" .It Dv C_ABSOLUTE Handle the .Fa sbt argument as an absolute time since boot. By default, .Fa sbt is treated as a relative amount of time, similar to .Fa ticks . .It Dv C_DIRECT_EXEC Run the handler directly from hardware interrupt context instead of from the softclock thread. This reduces latency and overhead, but puts more constraints on the callout function. Callout functions run in this context may use only spin mutexes for locking and should be as small as possible because they run with absolute priority. .It Fn C_PREL Specifies relative event time precision as binary logarithm of time interval divided by acceptable time deviation: 1 -- 1/2, 2 -- 1/4, etc. Note that the larger of .Fa pr or this value is used as the length of the time window. Smaller values .Pq which result in larger time intervals allow the callout subsystem to aggregate more events in one timer interrupt. .It Dv C_HARDCLOCK Align the timeouts to .Fn hardclock calls if possible. .El .Pp The .Fn callout_reset functions accept a .Fa func argument which identifies the function to be called when the time expires. It must be a pointer to a function that takes a single .Fa void * argument. Upon invocation, .Fa func will receive .Fa arg as its only argument. The .Fn callout_schedule functions reuse the .Fa func and .Fa arg arguments from the previous callout. Note that one of the .Fn callout_reset functions must always be called to initialize .Fa func and .Fa arg before one of the .Fn callout_schedule functions can be used. .Pp The callout subsystem provides a softclock thread for each CPU in the system. Callouts are assigned to a single CPU and are executed by the softclock thread for that CPU. Initially, callouts are assigned to CPU 0. The .Fn callout_reset_on , .Fn callout_reset_sbt_on , .Fn callout_schedule_on and .Fn callout_schedule_sbt_on functions assign the callout to CPU .Fa cpu . The .Fn callout_reset_curcpu , .Fn callout_reset_sbt_curpu , .Fn callout_schedule_curcpu and .Fn callout_schedule_sbt_curcpu functions assign the callout to the current CPU. The .Fn callout_reset , .Fn callout_reset_sbt , .Fn callout_schedule and .Fn callout_schedule_sbt functions schedule the callout to execute in the softclock thread of the CPU to which it is currently assigned. .Pp Softclock threads are not pinned to their respective CPUs by default. The softclock thread for CPU 0 can be pinned to CPU 0 by setting the .Va kern.pin_default_swi loader tunable to a non-zero value. Softclock threads for CPUs other than zero can be pinned to their respective CPUs by setting the .Va kern.pin_pcpu_swi loader tunable to a non-zero value. .Pp The macros .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate provide access to the current state of the callout. The .Fn callout_pending macro checks whether a callout is .Em pending ; a callout is considered .Em pending when a timeout has been set but the time has not yet arrived. Note that once the timeout time arrives and the callout subsystem starts to process this callout, .Fn callout_pending will return .Dv FALSE even though the callout function may not have finished .Pq or even begun executing. The .Fn callout_active macro checks whether a callout is marked as .Em active , and the .Fn callout_deactivate macro clears the callout's .Em active flag. The callout subsystem marks a callout as .Em active when a timeout is set and it clears the .Em active flag in .Fn callout_stop and .Fn callout_drain , but it .Em does not clear it when a callout expires normally via the execution of the callout function. .Ss "Avoiding Race Conditions" The callout subsystem invokes callout functions from its own thread context. Without some kind of synchronization, it is possible that a callout function will be invoked concurrently with an attempt to stop or reset the callout by another thread. In particular, since callout functions typically acquire a lock as their first action, the callout function may have already been invoked, but is blocked waiting for that lock at the time that another thread tries to reset or stop the callout. .Pp There are three main techniques for addressing these synchronization concerns. The first approach is preferred as it is the simplest: .Bl -enum -offset indent .It Callouts can be associated with a specific lock when they are initialized by .Fn callout_init_mtx , .Fn callout_init_rm , or .Fn callout_init_rw . When a callout is associated with a lock, the callout subsystem acquires the lock before the callout function is invoked. This allows the callout subsystem to transparently handle races between callout cancellation, scheduling, and execution. Note that the associated lock must be acquired before calling .Fn callout_stop or one of the .Fn callout_reset or .Fn callout_schedule functions to provide this safety. .Pp A callout initialized via .Fn callout_init with .Fa mpsafe set to zero is implicitly associated with the .Va Giant mutex. If .Va Giant is held when cancelling or rescheduling the callout, then its use will prevent races with the callout function. .It The return value from .Fn callout_stop .Po or the .Fn callout_reset and .Fn callout_schedule function families .Pc indicates whether or not the callout was removed. If it is known that the callout was set and the callout function has not yet executed, then a return value of .Dv FALSE indicates that the callout function is about to be called. For example: .Bd -literal -offset indent if (sc->sc_flags & SCFLG_CALLOUT_RUNNING) { if (callout_stop(&sc->sc_callout)) { sc->sc_flags &= ~SCFLG_CALLOUT_RUNNING; /* successfully stopped */ } else { /* * callout has expired and callout * function is about to be executed */ } } .Ed .It The .Fn callout_pending , .Fn callout_active and .Fn callout_deactivate macros can be used together to work around the race conditions. When a callout's timeout is set, the callout subsystem marks the callout as both .Em active and .Em pending . When the timeout time arrives, the callout subsystem begins processing the callout by first clearing the .Em pending flag. It then invokes the callout function without changing the .Em active flag, and does not clear the .Em active flag even after the callout function returns. The mechanism described here requires the callout function itself to clear the .Em active flag using the .Fn callout_deactivate macro. The .Fn callout_stop and .Fn callout_drain functions always clear both the .Em active and .Em pending flags before returning. .Pp The callout function should first check the .Em pending flag and return without action if .Fn callout_pending returns .Dv TRUE . This indicates that the callout was rescheduled using .Fn callout_reset just before the callout function was invoked. If .Fn callout_active returns .Dv FALSE then the callout function should also return without action. This indicates that the callout has been stopped. Finally, the callout function should call .Fn callout_deactivate to clear the .Em active flag. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); if (callout_pending(&sc->sc_callout)) { /* callout was reset */ mtx_unlock(&sc->sc_mtx); return; } if (!callout_active(&sc->sc_callout)) { /* callout was stopped */ mtx_unlock(&sc->sc_mtx); return; } callout_deactivate(&sc->sc_callout); /* rest of callout function */ .Ed .Pp Together with appropriate synchronization, such as the mutex used above, this approach permits the .Fn callout_stop and .Fn callout_reset functions to be used at any time without races. For example: .Bd -literal -offset indent mtx_lock(&sc->sc_mtx); callout_stop(&sc->sc_callout); /* The callout is effectively stopped now. */ .Ed .Pp If the callout is still pending then these functions operate normally, but if processing of the callout has already begun then the tests in the callout function cause it to return without further action. Synchronization between the callout function and other code ensures that stopping or resetting the callout will never be attempted while the callout function is past the .Fn callout_deactivate call. .Pp The above technique additionally ensures that the .Em active flag always reflects whether the callout is effectively enabled or disabled. If .Fn callout_active returns false, then the callout is effectively disabled, since even if the callout subsystem is actually just about to invoke the callout function, the callout function will return without action. .El .Pp There is one final race condition that must be considered when a callout is being stopped for the last time. In this case it may not be safe to let the callout function itself detect that the callout was stopped, since it may need to access data objects that have already been destroyed or recycled. To ensure that the callout is completely finished, a call to .Fn callout_drain should be used. In particular, a callout should always be drained prior to destroying its associated lock or releasing the storage for the callout structure. .Sh LEGACY API .Bf Sy The functions below are a legacy API that will be removed in a future release. New code should not use these routines. .Ef .Pp The function .Fn timeout schedules a call to the function given by the argument .Fa func to take place after .Fa ticks Ns No /hz seconds. Non-positive values of .Fa ticks are silently converted to the value .Sq 1 . .Fa func should be a pointer to a function that takes a .Fa void * argument. Upon invocation, .Fa func will receive .Fa arg as its only argument. The return value from .Fn timeout is a .Ft struct callout_handle which can be used in conjunction with the .Fn untimeout function to request that a scheduled timeout be canceled. .Pp The function .Fn callout_handle_init can be used to initialize a handle to a state which will cause any calls to .Fn untimeout with that handle to return with no side effects. .Pp Assigning a callout handle the value of .Fn CALLOUT_HANDLE_INITIALIZER performs the same function as .Fn callout_handle_init and is provided for use on statically declared or global callout handles. .Pp The function .Fn untimeout cancels the timeout associated with .Fa handle using the .Fa func and .Fa arg arguments to validate the handle. If the handle does not correspond to a timeout with the function .Fa func taking the argument .Fa arg no action is taken. .Fa handle must be initialized by a previous call to .Fn timeout , .Fn callout_handle_init , or assigned the value of .Fn CALLOUT_HANDLE_INITIALIZER "&handle" before being passed to .Fn untimeout . The behavior of calling .Fn untimeout with an uninitialized handle is undefined. .Pp As handles are recycled by the system, it is possible (although unlikely) that a handle from one invocation of .Fn timeout may match the handle of another invocation of .Fn timeout if both calls used the same function pointer and argument, and the first timeout is expired or canceled before the second call. The timeout facility offers O(1) running time for .Fn timeout and .Fn untimeout . Timeouts are executed from .Fn softclock with the .Va Giant lock held. Thus they are protected from re-entrancy. .Sh RETURN VALUES The .Fn callout_active macro returns the state of a callout's .Em active flag. .Pp The .Fn callout_pending macro returns the state of a callout's .Em pending flag. .Pp The .Fn callout_reset and .Fn callout_schedule function families return a value of one if the callout was pending before the new function invocation was scheduled. .Pp The .Fn callout_stop and .Fn callout_drain functions return a value of one if the callout was still pending when it was called, a zero if the callout could not be stopped and a negative one is it was either not running or haas already completed. The .Fn timeout function returns a .Ft struct callout_handle that can be passed to .Fn untimeout . .Sh HISTORY The current timeout and untimeout routines are based on the work of .An Adam M. Costello and .An George Varghese , published in a technical report entitled .%T "Redesigning the BSD Callout and Timer Facilities" and modified slightly for inclusion in .Fx by .An Justin T. Gibbs . The original work on the data structures used in this implementation was published by .An G. Varghese and .An A. Lauck in the paper .%T "Hashed and Hierarchical Timing Wheels: Data Structures for the Efficient Implementation of a Timer Facility" in the .%B "Proceedings of the 11th ACM Annual Symposium on Operating Systems Principles" . The current implementation replaces the long standing .Bx linked list callout mechanism which offered O(n) insertion and removal running time but did not generate or require handles for untimeout operations. diff --git a/share/man/man9/zone.9 b/share/man/man9/zone.9 index c9748000465f..5047107502f2 100644 --- a/share/man/man9/zone.9 +++ b/share/man/man9/zone.9 @@ -1,386 +1,386 @@ .\"- .\" Copyright (c) 2001 Dag-Erling Coïdan Smørgrav .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 20, 2015 .Dt ZONE 9 .Os .Sh NAME .Nm uma_zcreate , .Nm uma_zalloc , .Nm uma_zalloc_arg , .Nm uma_zfree , .Nm uma_zfree_arg , .Nm uma_find_refcnt , .Nm uma_zdestroy , .Nm uma_zone_set_max, .Nm uma_zone_get_max, .Nm uma_zone_get_cur, .Nm uma_zone_set_warning, .Nm uma_zone_set_maxaction .Nd zone allocator .Sh SYNOPSIS .In sys/param.h .In sys/queue.h .In vm/uma.h .Ft uma_zone_t .Fo uma_zcreate .Fa "char *name" "int size" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init uminit" "uma_fini fini" .Fa "int align" "uint16_t flags" .Fc .Ft "void *" .Fn uma_zalloc "uma_zone_t zone" "int flags" .Ft "void *" .Fn uma_zalloc_arg "uma_zone_t zone" "void *arg" "int flags" .Ft void .Fn uma_zfree "uma_zone_t zone" "void *item" .Ft void .Fn uma_zfree_arg "uma_zone_t zone" "void *item" "void *arg" .Ft "uint32_t *" .Fn uma_find_refcnt "uma_zone_t zone" "void *item" .Ft void .Fn uma_zdestroy "uma_zone_t zone" .Ft int .Fn uma_zone_set_max "uma_zone_t zone" "int nitems" .Ft int .Fn uma_zone_get_max "uma_zone_t zone" .Ft int .Fn uma_zone_get_cur "uma_zone_t zone" .Ft void .Fn uma_zone_set_warning "uma_zone_t zone" "const char *warning" .Ft void .Fn uma_zone_set_maxaction "uma_zone_t zone" "void (*maxaction)(uma_zone_t)" .In sys/sysctl.h .Fn SYSCTL_UMA_MAX parent nbr name access zone descr .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr .Fn SYSCTL_UMA_CUR parent nbr name access zone descr .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name access zone descr .Sh DESCRIPTION The zone allocator provides an efficient interface for managing dynamically-sized collections of items of similar size. The zone allocator can work with preallocated zones as well as with runtime-allocated ones, and is therefore available much earlier in the boot process than other memory management routines. .Pp A zone is an extensible collection of items of identical size. The zone allocator keeps track of which items are in use and which are not, and provides functions for allocating items from the zone and for releasing them back (which makes them available for later use). .Pp After the first allocation of an item, it will have been cleared to zeroes, however subsequent allocations will retain the contents as of the last free. .Pp The .Fn uma_zcreate function creates a new zone from which items may then be allocated from. The .Fa name argument is a text name of the zone for debugging and stats; this memory should not be freed until the zone has been deallocated. .Pp The .Fa ctor and .Fa dtor arguments are callback functions that are called by the uma subsystem at the time of the call to .Fn uma_zalloc and .Fn uma_zfree respectively. Their purpose is to provide hooks for initializing or destroying things that need to be done at the time of the allocation or release of a resource. A good usage for the .Fa ctor and .Fa dtor callbacks might be to adjust a global count of the number of objects allocated. .Pp The .Fa uminit and .Fa fini arguments are used to optimize the allocation of objects from the zone. They are called by the uma subsystem whenever it needs to allocate or free several items to satisfy requests or memory pressure. A good use for the .Fa uminit and .Fa fini callbacks might be to initialize and destroy mutexes contained within the object. This would allow one to re-use already initialized mutexes when an object is returned from the uma subsystem's object cache. They are not called on each call to .Fn uma_zalloc and .Fn uma_zfree but rather in a batch mode on several objects. .Pp The .Fa flags argument of the .Fn uma_zcreate is a subset of the following flags: .Bl -tag -width "foo" .It Dv UMA_ZONE_NOFREE Slabs of the zone are never returned back to VM. .It Dv UMA_ZONE_REFCNT Each item in the zone would have internal reference counter associated with it. See .Fn uma_find_refcnt . .It Dv UMA_ZONE_NODUMP Pages belonging to the zone will not be included into mini-dumps. .It Dv UMA_ZONE_PCPU An allocation from zone would have .Va mp_ncpu shadow copies, that are privately assigned to CPUs. A CPU can address its private copy using base allocation address plus multiple of current CPU id and .Fn sizeof "struct pcpu" : .Bd -literal -offset indent foo_zone = uma_zcreate(..., UMA_ZONE_PCPU); ... foo_base = uma_zalloc(foo_zone, ...); ... critical_enter(); foo_pcpu = (foo_t *)zpcpu_get(foo_base); /* do something with foo_pcpu */ critical_exit(); .Ed .It Dv UMA_ZONE_OFFPAGE By default book-keeping of items within a slab is done in the slab page itself. This flag explicitly tells subsystem that book-keeping structure should be allocated separately from special internal zone. This flag requires either .Dv UMA_ZONE_VTOSLAB or .Dv UMA_ZONE_HASH , since subsystem requires a mechanism to find a book-keeping structure -to an item beeing freed. +to an item being freed. The subsystem may choose to prefer offpage book-keeping for certain zones implicitly. .It Dv UMA_ZONE_ZINIT The zone will have its .Ft uma_init method set to internal method that initializes a new allocated slab to all zeros. Do not mistake .Ft uma_init method with .Ft uma_ctor . A zone with .Dv UMA_ZONE_ZINIT flag would not return zeroed memory on every .Fn uma_zalloc . .It Dv UMA_ZONE_HASH The zone should use an internal hash table to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_VTOSLAB The zone should use special field of .Vt vm_page_t to find slab book-keeping structure where an allocation being freed belongs to. .It Dv UMA_ZONE_MALLOC The zone is for the .Xr malloc 9 subsystem. .It Dv UMA_ZONE_VM The zone is for the VM subsystem. .El .Pp To allocate an item from a zone, simply call .Fn uma_zalloc with a pointer to that zone and set the .Fa flags argument to selected flags as documented in .Xr malloc 9 . It will return a pointer to an item if successful, or .Dv NULL in the rare case where all items in the zone are in use and the allocator is unable to grow the zone and .Dv M_NOWAIT is specified. .Pp Items are released back to the zone from which they were allocated by calling .Fn uma_zfree with a pointer to the zone and a pointer to the item. If .Fa item is .Dv NULL , then .Fn uma_zfree does nothing. .Pp The variations .Fn uma_zalloc_arg and .Fn uma_zfree_arg allow to specify an argument for the .Dv ctor and .Dv dtor functions, respectively. .Pp If zone was created with .Dv UMA_ZONE_REFCNT flag, then pointer to reference counter for an item can be retrieved with help of the .Fn uma_find_refcnt function. .Pp Created zones, which are empty, can be destroyed using .Fn uma_zdestroy , freeing all memory that was allocated for the zone. All items allocated from the zone with .Fn uma_zalloc must have been freed with .Fn uma_zfree before. .Pp The .Fn uma_zone_set_max function limits the number of items .Pq and therefore memory that can be allocated to .Fa zone . The .Fa nitems argument specifies the requested upper limit number of items. The effective limit is returned to the caller, as it may end up being higher than requested due to the implementation rounding up to ensure all memory pages allocated to the zone are utilised to capacity. The limit applies to the total number of items in the zone, which includes allocated items, free items and free items in the per-cpu caches. On systems with more than one CPU it may not be possible to allocate the specified number of items even when there is no shortage of memory, because all of the remaining free items may be in the caches of the other CPUs when the limit is hit. .Pp The .Fn uma_zone_get_max function returns the effective upper limit number of items for a zone. .Pp The .Fn uma_zone_get_cur function returns the approximate current occupancy of the zone. The returned value is approximate because appropriate synchronisation to determine an exact value is not performed by the implementation. This ensures low overhead at the expense of potentially stale data being used in the calculation. .Pp The .Fn uma_zone_set_warning function sets a warning that will be printed on the system console when the given zone becomes full and fails to allocate an item. The warning will be printed no more often than every five minutes. Warnings can be turned off globally by setting the .Va vm.zone_warnings sysctl tunable to .Va 0 . .Pp The .Fn uma_zone_set_maxaction function sets a function that will be called when the given zone becomes full and fails to allocate an item. The function will be called with the zone locked. Also, the function that called the allocation function may have held additional locks. Therefore, this function should do very little work (similar to a signal handler). .Pp The .Fn SYSCTL_UMA_MAX parent nbr name access zone descr macro declares a static .Xr sysctl oid that exports the effective upper limit number of items for a zone. The .Fa zone argument should be a pointer to .Vt uma_zone_t . A read of the oid returns value obtained through .Fn uma_zone_get_max . A write to the oid sets new value via .Fn uma_zone_set_max . The .Fn SYSCTL_ADD_UMA_MAX ctx parent nbr name access zone descr macro is provided to create this type of oid dynamically. .Pp The .Fn SYSCTL_UMA_CUR parent nbr name access zone descr macro declares a static read-only .Xr sysctl oid that exports the approximate current occupancy of the zone. The .Fa zone argument should be a pointer to .Vt uma_zone_t . A read of the oid returns value obtained through .Fn uma_zone_get_cur . The .Fn SYSCTL_ADD_UMA_CUR ctx parent nbr name zone descr macro is provided to create this type of oid dynamically. .Sh RETURN VALUES The .Fn uma_zalloc function returns a pointer to an item, or .Dv NULL if the zone ran out of unused items and .Dv M_NOWAIT was specified. .Sh SEE ALSO .Xr malloc 9 .Sh HISTORY The zone allocator first appeared in .Fx 3.0 . It was radically changed in .Fx 5.0 to function as a slab allocator. .Sh AUTHORS .An -nosplit The zone allocator was written by .An John S. Dyson . The zone allocator was rewritten in large parts by .An Jeff Roberson Aq Mt jeff@FreeBSD.org to function as a slab allocator. .Pp This manual page was written by .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . Changes for UMA by .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org .