diff --git a/lib/librss/librss.3 b/lib/librss/librss.3 index 655e5ca17984..3964aa36891b 100644 --- a/lib/librss/librss.3 +++ b/lib/librss/librss.3 @@ -1,133 +1,133 @@ .\" .Dd October 23, 2016 .Dt LIBRSS 3 .Os .Sh NAME .Nm librss .Nd Provide Receive-side scaling awareness to userland applications .Sh LIBRARY .Lb librss .Sh SYNOPSIS .In sys/param.h .In sys/cpuset.h .In librss.h .Ft struct rss_config * .Fn rss_config_get "void" .Ft void .Fn rss_config_free "struct rss_config *cfg" .Ft int .Fn rss_config_get_bucket_count "struct rss_config *cfg" .Ft int .Fn rss_get_bucket_cpuset "struct rss_config *rc" "rss_bucket_type_t btype" "int bucket" "cpuset_t *cs" .Ft int .Fn rss_set_bucket_rebalance_cb "rss_bucket_rebalance_cb_t *cb" "void *cbdata" .Ft int .Fn rss_sock_set_recvrss "int fd" "int af" "int val" .Sh DESCRIPTION The .Nm library and the functions it provides are used for both fetching the system RSS configuration and interacting with RSS aware sockets. .Pp Applications will typically call .Fn rss_config_get to fetch the current RSS configuration from the system and perform initial setup. This typically involves spawning worker threads, one per RSS bucket, and optionally binding them to the per-bucket CPU set. .Pp The .Vt rss_config struct is defined as: .Bd -literal struct rss_config { int rss_ncpus; int rss_nbuckets; int rss_basecpu; int *rss_bucket_map; }; .Ed .Pp Applications will typically use the .Fn rss_config_get_bucket_count function to fetch the number of RSS buckets, create one thread per RSS bucket for RSS aware work, then one RSS aware socket to receive UDP datagrams or TCP connections in each particular RSS bucket / thread. .Pp The .Fn rss_get_bucket_cpuset function sets the given cpuset up for the given RSS bucket and behaviour. Typically applications will wish to just query for .Vt RSS_BUCKET_TYPE_KERNEL_ALL unless they wish to potentially setup different worker threads for transmit and receive. .Pp The .Vt rss_bucket_type_t enum is defined as: .Bd -literal typedef enum { RSS_BUCKET_TYPE_NONE = 0, RSS_BUCKET_TYPE_KERNEL_ALL = 1, RSS_BUCKET_TYPE_KERNEL_TX = 2, RSS_BUCKET_TYPE_KERNEL_RX = 3, RSS_BUCKET_TYPE_MAX = 3, } rss_bucket_type_t; .Ed .Pp The rebalance callback .Vt rss_bucket_rebalance_cb_t is defined as: .Bd -literal typedef void rss_bucket_rebalance_cb_t(void *arg); .Ed .Pp The .Fn rss_set_bucket_rebalance_cb function sets an optional callback that will be called if the kernel rebalances RSS buckets. This is intended as a future expansion to rebalance buckets rather than reprogram the RSS key, so typically the only work to be performed is to rebind worker threads to an updated cpuset. .Pp Once RSS setup is completed, .Fn rss_config_free is called to free the RSS configuration structure. .Pp If .Vt val is set to 1, the socket can be placed in an RSS bucket and will only accept datagrams (for UDP) or connections (for TCP) that are received for that RSS bucket. If set to 0, the socket is placed in the default PCB and will see datagrams/connections that are not initially consumed by a PCB aware socket. .Pp The .Fn rss_sock_set_recvrss function enables or disables receiving RSS related information -as socket options in. -.2 recvmsg +as socket options in +.Xr recvmsg 2 calls. .Pp When enabled, UDP datagrams will have a message with the .Vt IP_RECVFLOWID option indicating the 32-bit receive flowid as a uint32_t, and the .Vt IP_RECVRSSBUCKETID option indicating the 32 bit RSS bucket id as a uint32_t. .Sh ERRORS The functions return either <0 or NULL as appropriate upon error. .Sh HISTORY The .Xr librss.3 library first appeared in .Fx 11.0 . .Sh AUTHORS .An Adrian Chadd Aq Mt adrian@FreeBSD.org .Sh BUGS There is currently no kernel mechanism to rebalance the RSS bucket to CPU mapping, and so the callback mechanism is a no-op. diff --git a/share/man/man4/bpf.4 b/share/man/man4/bpf.4 index 4a40f4947dfd..8082f6eac39a 100644 --- a/share/man/man4/bpf.4 +++ b/share/man/man4/bpf.4 @@ -1,1192 +1,1192 @@ .\" Copyright (c) 2007 Seccuris Inc. .\" All rights reserved. .\" .\" This software was developed by Robert N. M. Watson under contract to .\" Seccuris Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this 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. .\" .\" Copyright (c) 1990 The Regents of the University of California. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that: (1) source code distributions .\" retain the above copyright notice and this paragraph in its entirety, (2) .\" distributions including binary code include the above copyright notice and .\" this paragraph in its entirety in the documentation or other materials .\" provided with the distribution, and (3) all advertising materials mentioning .\" features or use of this software display the following acknowledgement: .\" ``This product includes software developed by the University of California, .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of .\" the University nor the names of its contributors may be used to endorse .\" or promote products derived from this software without specific prior .\" written permission. .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. .\" .\" This document is derived in part from the enet man page (enet.4) .\" distributed with 4.3BSD Unix. .\" .Dd October 13, 2021 .Dt BPF 4 .Os .Sh NAME .Nm bpf .Nd Berkeley Packet Filter .Sh SYNOPSIS .Cd device bpf .Sh DESCRIPTION The Berkeley Packet Filter provides a raw interface to data link layers in a protocol independent fashion. All packets on the network, even those destined for other hosts, are accessible through this mechanism. .Pp The packet filter appears as a character special device, .Pa /dev/bpf . After opening the device, the file descriptor must be bound to a specific network interface with the .Dv BIOCSETIF ioctl. A given interface can be shared by multiple listeners, and the filter underlying each descriptor will see an identical packet stream. .Pp Associated with each open instance of a .Nm file is a user-settable packet filter. Whenever a packet is received by an interface, all file descriptors listening on that interface apply their filter. Each descriptor that accepts the packet receives its own copy. .Pp A packet can be sent out on the network by writing to a .Nm file descriptor. The writes are unbuffered, meaning only one packet can be processed per write. Currently, only writes to Ethernets and .Tn SLIP links are supported. .Sh BUFFER MODES .Nm devices deliver packet data to the application via memory buffers provided by the application. The buffer mode is set using the .Dv BIOCSETBUFMODE ioctl, and read using the .Dv BIOCGETBUFMODE ioctl. .Ss Buffered read mode By default, .Nm devices operate in the .Dv BPF_BUFMODE_BUFFER mode, in which packet data is copied explicitly from kernel to user memory using the .Xr read 2 system call. The user process will declare a fixed buffer size that will be used both for sizing internal buffers and for all .Xr read 2 operations on the file. This size is queried using the .Dv BIOCGBLEN ioctl, and is set using the .Dv BIOCSBLEN ioctl. Note that an individual packet larger than the buffer size is necessarily truncated. .Ss Zero-copy buffer mode .Nm devices may also operate in the .Dv BPF_BUFMODE_ZEROCOPY mode, in which packet data is written directly into two user memory buffers by the kernel, avoiding both system call and copying overhead. Buffers are of fixed (and equal) size, page-aligned, and an even multiple of the page size. The maximum zero-copy buffer size is returned by the .Dv BIOCGETZMAX ioctl. Note that an individual packet larger than the buffer size is necessarily truncated. .Pp The user process registers two memory buffers using the .Dv BIOCSETZBUF ioctl, which accepts a .Vt struct bpf_zbuf pointer as an argument: .Bd -literal struct bpf_zbuf { void *bz_bufa; void *bz_bufb; size_t bz_buflen; }; .Ed .Pp .Vt bz_bufa is a pointer to the userspace address of the first buffer that will be filled, and .Vt bz_bufb is a pointer to the second buffer. .Nm will then cycle between the two buffers as they fill and are acknowledged. .Pp Each buffer begins with a fixed-length header to hold synchronization and data length information for the buffer: .Bd -literal struct bpf_zbuf_header { volatile u_int bzh_kernel_gen; /* Kernel generation number. */ volatile u_int bzh_kernel_len; /* Length of data in the buffer. */ volatile u_int bzh_user_gen; /* User generation number. */ /* ...padding for future use... */ }; .Ed .Pp The header structure of each buffer, including all padding, should be zeroed before it is configured using .Dv BIOCSETZBUF . Remaining space in the buffer will be used by the kernel to store packet data, laid out in the same format as with buffered read mode. .Pp The kernel and the user process follow a simple acknowledgement protocol via the buffer header to synchronize access to the buffer: when the header generation numbers, .Vt bzh_kernel_gen and .Vt bzh_user_gen , hold the same value, the kernel owns the buffer, and when they differ, userspace owns the buffer. .Pp While the kernel owns the buffer, the contents are unstable and may change asynchronously; while the user process owns the buffer, its contents are stable and will not be changed until the buffer has been acknowledged. .Pp Initializing the buffer headers to all 0's before registering the buffer has the effect of assigning initial ownership of both buffers to the kernel. The kernel signals that a buffer has been assigned to userspace by modifying .Vt bzh_kernel_gen , and userspace acknowledges the buffer and returns it to the kernel by setting the value of .Vt bzh_user_gen to the value of .Vt bzh_kernel_gen . .Pp In order to avoid caching and memory re-ordering effects, the user process must use atomic operations and memory barriers when checking for and acknowledging buffers: .Bd -literal #include /* * Return ownership of a buffer to the kernel for reuse. */ static void buffer_acknowledge(struct bpf_zbuf_header *bzh) { atomic_store_rel_int(&bzh->bzh_user_gen, bzh->bzh_kernel_gen); } /* * Check whether a buffer has been assigned to userspace by the kernel. * Return true if userspace owns the buffer, and false otherwise. */ static int buffer_check(struct bpf_zbuf_header *bzh) { return (bzh->bzh_user_gen != atomic_load_acq_int(&bzh->bzh_kernel_gen)); } .Ed .Pp The user process may force the assignment of the next buffer, if any data is pending, to userspace using the .Dv BIOCROTZBUF ioctl. This allows the user process to retrieve data in a partially filled buffer before the buffer is full, such as following a timeout; the process must recheck for buffer ownership using the header generation numbers, as the buffer will not be assigned to userspace if no data was present. .Pp As in the buffered read mode, .Xr kqueue 2 , .Xr poll 2 , and .Xr select 2 may be used to sleep awaiting the availability of a completed buffer. They will return a readable file descriptor when ownership of the next buffer is assigned to user space. .Pp In the current implementation, the kernel may assign zero, one, or both buffers to the user process; however, an earlier implementation maintained the invariant that at most one buffer could be assigned to the user process at a time. In order to both ensure progress and high performance, user processes should acknowledge a completely processed buffer as quickly as possible, returning it for reuse, and not block waiting on a second buffer while holding another buffer. .Sh IOCTLS The .Xr ioctl 2 command codes below are defined in .In net/bpf.h . All commands require these includes: .Bd -literal #include #include #include #include .Ed .Pp Additionally, .Dv BIOCGETIF and .Dv BIOCSETIF require .In sys/socket.h and .In net/if.h . .Pp In addition to .Dv FIONREAD the following commands may be applied to any open .Nm file. The (third) argument to .Xr ioctl 2 should be a pointer to the type indicated. .Bl -tag -width BIOCGETBUFMODE .It Dv BIOCGBLEN .Pq Li u_int Returns the required buffer length for reads on .Nm files. .It Dv BIOCSBLEN .Pq Li u_int Sets the buffer length for reads on .Nm files. The buffer must be set before the file is attached to an interface with .Dv BIOCSETIF . If the requested buffer size cannot be accommodated, the closest allowable size will be set and returned in the argument. A read call will result in .Er EINVAL if it is passed a buffer that is not this size. .It Dv BIOCGDLT .Pq Li u_int Returns the type of the data link layer underlying the attached interface. .Er EINVAL is returned if no interface has been specified. The device types, prefixed with .Dq Li DLT_ , are defined in .In net/bpf.h . .It Dv BIOCGDLTLIST .Pq Li "struct bpf_dltlist" Returns an array of the available types of the data link layer underlying the attached interface: .Bd -literal -offset indent struct bpf_dltlist { u_int bfl_len; u_int *bfl_list; }; .Ed .Pp The available types are returned in the array pointed to by the .Va bfl_list field while their length in u_int is supplied to the .Va bfl_len field. .Er ENOMEM is returned if there is not enough buffer space and .Er EFAULT is returned if a bad address is encountered. The .Va bfl_len field is modified on return to indicate the actual length in u_int of the array returned. If .Va bfl_list is .Dv NULL , the .Va bfl_len field is set to indicate the required length of an array in u_int. .It Dv BIOCSDLT .Pq Li u_int Changes the type of the data link layer underlying the attached interface. .Er EINVAL is returned if no interface has been specified or the specified type is not available for the interface. .It Dv BIOCPROMISC Forces the interface into promiscuous mode. All packets, not just those destined for the local host, are processed. Since more than one file can be listening on a given interface, a listener that opened its interface non-promiscuously may receive packets promiscuously. This problem can be remedied with an appropriate filter. .Pp The interface remains in promiscuous mode until all files listening promiscuously are closed. .It Dv BIOCFLUSH Flushes the buffer of incoming packets, and resets the statistics that are returned by BIOCGSTATS. .It Dv BIOCGETIF .Pq Li "struct ifreq" Returns the name of the hardware interface that the file is listening on. The name is returned in the ifr_name field of the .Li ifreq structure. All other fields are undefined. .It Dv BIOCSETIF .Pq Li "struct ifreq" Sets the hardware interface associated with the file. This command must be performed before any packets can be read. The device is indicated by name using the .Li ifr_name field of the .Li ifreq structure. Additionally, performs the actions of .Dv BIOCFLUSH . .It Dv BIOCSRTIMEOUT .It Dv BIOCGRTIMEOUT .Pq Li "struct timeval" Sets or gets the read timeout parameter. The argument specifies the length of time to wait before timing out on a read request. This parameter is initialized to zero by .Xr open 2 , indicating no timeout. .It Dv BIOCGSTATS .Pq Li "struct bpf_stat" Returns the following structure of packet statistics: .Bd -literal struct bpf_stat { u_int bs_recv; /* number of packets received */ u_int bs_drop; /* number of packets dropped */ }; .Ed .Pp The fields are: .Bl -hang -offset indent .It Li bs_recv the number of packets received by the descriptor since opened or reset (including any buffered since the last read call); and .It Li bs_drop the number of packets which were accepted by the filter but dropped by the kernel because of buffer overflows (i.e., the application's reads are not keeping up with the packet traffic). .El .It Dv BIOCIMMEDIATE .Pq Li u_int Enables or disables .Dq immediate mode , based on the truth value of the argument. When immediate mode is enabled, reads return immediately upon packet reception. Otherwise, a read will block until either the kernel buffer becomes full or a timeout occurs. This is useful for programs like .Xr rarpd 8 which must respond to messages in real time. The default for a new file is off. .It Dv BIOCSETF .It Dv BIOCSETFNR .Pq Li "struct bpf_program" Sets the read filter program used by the kernel to discard uninteresting packets. An array of instructions and its length is passed in using the following structure: .Bd -literal struct bpf_program { u_int bf_len; struct bpf_insn *bf_insns; }; .Ed .Pp The filter program is pointed to by the .Li bf_insns field while its length in units of .Sq Li struct bpf_insn is given by the .Li bf_len field. See section .Sx "FILTER MACHINE" for an explanation of the filter language. The only difference between .Dv BIOCSETF and .Dv BIOCSETFNR is .Dv BIOCSETF performs the actions of .Dv BIOCFLUSH while .Dv BIOCSETFNR does not. .It Dv BIOCSETWF .Pq Li "struct bpf_program" Sets the write filter program used by the kernel to control what type of packets can be written to the interface. See the .Dv BIOCSETF command for more information on the .Nm filter program. .It Dv BIOCVERSION .Pq Li "struct bpf_version" Returns the major and minor version numbers of the filter language currently recognized by the kernel. Before installing a filter, applications must check that the current version is compatible with the running kernel. Version numbers are compatible if the major numbers match and the application minor is less than or equal to the kernel minor. The kernel version number is returned in the following structure: .Bd -literal struct bpf_version { u_short bv_major; u_short bv_minor; }; .Ed .Pp The current version numbers are given by .Dv BPF_MAJOR_VERSION and .Dv BPF_MINOR_VERSION from .In net/bpf.h . An incompatible filter may result in undefined behavior (most likely, an error returned by .Fn ioctl or haphazard packet matching). .It Dv BIOCGRSIG .It Dv BIOCSRSIG .Pq Li u_int Sets or gets the receive signal. This signal will be sent to the process or process group specified by .Dv FIOSETOWN . It defaults to .Dv SIGIO . .It Dv BIOCSHDRCMPLT .It Dv BIOCGHDRCMPLT .Pq Li u_int Sets or gets the status of the .Dq header complete flag. Set to zero if the link level source address should be filled in automatically by the interface output routine. Set to one if the link level source address will be written, as provided, to the wire. This flag is initialized to zero by default. .It Dv BIOCSSEESENT .It Dv BIOCGSEESENT .Pq Li u_int These commands are obsolete but left for compatibility. Use .Dv BIOCSDIRECTION and .Dv BIOCGDIRECTION instead. Sets or gets the flag determining whether locally generated packets on the interface should be returned by BPF. Set to zero to see only incoming packets on the interface. Set to one to see packets originating locally and remotely on the interface. This flag is initialized to one by default. .It Dv BIOCSDIRECTION .It Dv BIOCGDIRECTION .Pq Li u_int Sets or gets the setting determining whether incoming, outgoing, or all packets on the interface should be returned by BPF. Set to .Dv BPF_D_IN to see only incoming packets on the interface. Set to .Dv BPF_D_INOUT to see packets originating locally and remotely on the interface. Set to .Dv BPF_D_OUT to see only outgoing packets on the interface. This setting is initialized to .Dv BPF_D_INOUT by default. .It Dv BIOCSTSTAMP .It Dv BIOCGTSTAMP .Pq Li u_int Set or get format and resolution of the time stamps returned by BPF. Set to .Dv BPF_T_MICROTIME , .Dv BPF_T_MICROTIME_FAST , .Dv BPF_T_MICROTIME_MONOTONIC , or .Dv BPF_T_MICROTIME_MONOTONIC_FAST to get time stamps in 64-bit .Vt struct timeval format. Set to .Dv BPF_T_NANOTIME , .Dv BPF_T_NANOTIME_FAST , .Dv BPF_T_NANOTIME_MONOTONIC , or .Dv BPF_T_NANOTIME_MONOTONIC_FAST to get time stamps in 64-bit .Vt struct timespec format. Set to .Dv BPF_T_BINTIME , .Dv BPF_T_BINTIME_FAST , .Dv BPF_T_NANOTIME_MONOTONIC , or .Dv BPF_T_BINTIME_MONOTONIC_FAST to get time stamps in 64-bit .Vt struct bintime format. Set to .Dv BPF_T_NONE to ignore time stamp. All 64-bit time stamp formats are wrapped in .Vt struct bpf_ts . The .Dv BPF_T_MICROTIME_FAST , .Dv BPF_T_NANOTIME_FAST , .Dv BPF_T_BINTIME_FAST , .Dv BPF_T_MICROTIME_MONOTONIC_FAST , .Dv BPF_T_NANOTIME_MONOTONIC_FAST , and .Dv BPF_T_BINTIME_MONOTONIC_FAST are analogs of corresponding formats without _FAST suffix but do not perform a full time counter query, so their accuracy is one timer tick. The .Dv BPF_T_MICROTIME_MONOTONIC , .Dv BPF_T_NANOTIME_MONOTONIC , .Dv BPF_T_BINTIME_MONOTONIC , .Dv BPF_T_MICROTIME_MONOTONIC_FAST , .Dv BPF_T_NANOTIME_MONOTONIC_FAST , and .Dv BPF_T_BINTIME_MONOTONIC_FAST store the time elapsed since kernel boot. This setting is initialized to .Dv BPF_T_MICROTIME by default. .It Dv BIOCFEEDBACK .Pq Li u_int Set packet feedback mode. This allows injected packets to be fed back as input to the interface when output via the interface is successful. When .Dv BPF_D_INOUT direction is set, injected outgoing packet is not returned by BPF to avoid duplication. This flag is initialized to zero by default. .It Dv BIOCLOCK Set the locked flag on the .Nm descriptor. This prevents the execution of ioctl commands which could change the underlying operating parameters of the device. .It Dv BIOCGETBUFMODE .It Dv BIOCSETBUFMODE .Pq Li u_int Get or set the current .Nm buffering mode; possible values are .Dv BPF_BUFMODE_BUFFER , buffered read mode, and .Dv BPF_BUFMODE_ZBUF , zero-copy buffer mode. .It Dv BIOCSETZBUF .Pq Li struct bpf_zbuf Set the current zero-copy buffer locations; buffer locations may be set only once zero-copy buffer mode has been selected, and prior to attaching to an interface. Buffers must be of identical size, page-aligned, and an integer multiple of pages in size. The three fields .Vt bz_bufa , .Vt bz_bufb , and .Vt bz_buflen must be filled out. If buffers have already been set for this device, the ioctl will fail. .It Dv BIOCGETZMAX .Pq Li size_t Get the largest individual zero-copy buffer size allowed. As two buffers are used in zero-copy buffer mode, the limit (in practice) is twice the returned size. As zero-copy buffers consume kernel address space, conservative selection of buffer size is suggested, especially when there are multiple .Nm descriptors in use on 32-bit systems. .It Dv BIOCROTZBUF Force ownership of the next buffer to be assigned to userspace, if any data present in the buffer. If no data is present, the buffer will remain owned by the kernel. This allows consumers of zero-copy buffering to implement timeouts and retrieve partially filled buffers. In order to handle the case where no data is present in the buffer and therefore ownership is not assigned, the user process must check .Vt bzh_kernel_gen against .Vt bzh_user_gen . .It Dv BIOCSETVLANPCP Set the VLAN PCP bits to the supplied value. .El .Sh STANDARD IOCTLS .Nm now supports several standard .Xr ioctl 2 Ns 's which allow the user to do async and/or non-blocking I/O to an open -.I bpf +.Em bpf file descriptor. .Bl -tag -width SIOCGIFADDR .It Dv FIONREAD .Pq Li int Returns the number of bytes that are immediately available for reading. .It Dv SIOCGIFADDR .Pq Li "struct ifreq" Returns the address associated with the interface. .It Dv FIONBIO .Pq Li int Sets or clears non-blocking I/O. If arg is non-zero, then doing a .Xr read 2 when no data is available will return -1 and .Va errno will be set to .Er EAGAIN . If arg is zero, non-blocking I/O is disabled. Note: setting this overrides the timeout set by .Dv BIOCSRTIMEOUT . .It Dv FIOASYNC .Pq Li int Enables or disables async I/O. When enabled (arg is non-zero), the process or process group specified by .Dv FIOSETOWN will start receiving .Dv SIGIO 's when packets arrive. Note that you must do an .Dv FIOSETOWN in order for this to take effect, as the system will not default this for you. The signal may be changed via .Dv BIOCSRSIG . .It Dv FIOSETOWN .It Dv FIOGETOWN .Pq Li int Sets or gets the process or process group (if negative) that should receive .Dv SIGIO when packets are available. The signal may be changed using .Dv BIOCSRSIG (see above). .El .Sh BPF HEADER One of the following structures is prepended to each packet returned by .Xr read 2 or via a zero-copy buffer: .Bd -literal struct bpf_xhdr { struct bpf_ts bh_tstamp; /* time stamp */ uint32_t bh_caplen; /* length of captured portion */ uint32_t bh_datalen; /* original length of packet */ u_short bh_hdrlen; /* length of bpf header (this struct plus alignment padding) */ }; struct bpf_hdr { struct timeval bh_tstamp; /* time stamp */ uint32_t bh_caplen; /* length of captured portion */ uint32_t bh_datalen; /* original length of packet */ u_short bh_hdrlen; /* length of bpf header (this struct plus alignment padding) */ }; .Ed .Pp The fields, whose values are stored in host order, and are: .Pp .Bl -tag -compact -width bh_datalen .It Li bh_tstamp The time at which the packet was processed by the packet filter. .It Li bh_caplen The length of the captured portion of the packet. This is the minimum of the truncation amount specified by the filter and the length of the packet. .It Li bh_datalen The length of the packet off the wire. This value is independent of the truncation amount specified by the filter. .It Li bh_hdrlen The length of the .Nm header, which may not be equal to .\" XXX - not really a function call .Fn sizeof "struct bpf_xhdr" or .Fn sizeof "struct bpf_hdr" . .El .Pp The .Li bh_hdrlen field exists to account for padding between the header and the link level protocol. The purpose here is to guarantee proper alignment of the packet data structures, which is required on alignment sensitive architectures and improves performance on many other architectures. The packet filter ensures that the .Vt bpf_xhdr , .Vt bpf_hdr and the network layer header will be word aligned. Currently, .Vt bpf_hdr is used when the time stamp is set to .Dv BPF_T_MICROTIME , .Dv BPF_T_MICROTIME_FAST , .Dv BPF_T_MICROTIME_MONOTONIC , .Dv BPF_T_MICROTIME_MONOTONIC_FAST , or .Dv BPF_T_NONE for backward compatibility reasons. Otherwise, .Vt bpf_xhdr is used. However, .Vt bpf_hdr may be deprecated in the near future. Suitable precautions must be taken when accessing the link layer protocol fields on alignment restricted machines. (This is not a problem on an Ethernet, since the type field is a short falling on an even offset, and the addresses are probably accessed in a bytewise fashion). .Pp Additionally, individual packets are padded so that each starts on a word boundary. This requires that an application has some knowledge of how to get from packet to packet. The macro .Dv BPF_WORDALIGN is defined in .In net/bpf.h to facilitate this process. It rounds up its argument to the nearest word aligned value (where a word is .Dv BPF_ALIGNMENT bytes wide). .Pp For example, if .Sq Li p points to the start of a packet, this expression will advance it to the next packet: .Dl p = (char *)p + BPF_WORDALIGN(p->bh_hdrlen + p->bh_caplen) .Pp For the alignment mechanisms to work properly, the buffer passed to .Xr read 2 must itself be word aligned. The .Xr malloc 3 function will always return an aligned buffer. .Sh FILTER MACHINE A filter program is an array of instructions, with all branches forwardly directed, terminated by a .Em return instruction. Each instruction performs some action on the pseudo-machine state, which consists of an accumulator, index register, scratch memory store, and implicit program counter. .Pp The following structure defines the instruction format: .Bd -literal struct bpf_insn { u_short code; u_char jt; u_char jf; bpf_u_int32 k; }; .Ed .Pp The .Li k field is used in different ways by different instructions, and the .Li jt and .Li jf fields are used as offsets by the branch instructions. The opcodes are encoded in a semi-hierarchical fashion. There are eight classes of instructions: .Dv BPF_LD , .Dv BPF_LDX , .Dv BPF_ST , .Dv BPF_STX , .Dv BPF_ALU , .Dv BPF_JMP , .Dv BPF_RET , and .Dv BPF_MISC . Various other mode and operator bits are or'd into the class to give the actual instructions. The classes and modes are defined in .In net/bpf.h . .Pp Below are the semantics for each defined .Nm instruction. We use the convention that A is the accumulator, X is the index register, P[] packet data, and M[] scratch memory store. P[i:n] gives the data at byte offset .Dq i in the packet, interpreted as a word (n=4), unsigned halfword (n=2), or unsigned byte (n=1). M[i] gives the i'th word in the scratch memory store, which is only addressed in word units. The memory store is indexed from 0 to .Dv BPF_MEMWORDS - 1. .Li k , .Li jt , and .Li jf are the corresponding fields in the instruction definition. .Dq len refers to the length of the packet. .Bl -tag -width BPF_STXx .It Dv BPF_LD These instructions copy a value into the accumulator. The type of the source operand is specified by an .Dq addressing mode and can be a constant .Pq Dv BPF_IMM , packet data at a fixed offset .Pq Dv BPF_ABS , packet data at a variable offset .Pq Dv BPF_IND , the packet length .Pq Dv BPF_LEN , or a word in the scratch memory store .Pq Dv BPF_MEM . For .Dv BPF_IND and .Dv BPF_ABS , the data size must be specified as a word .Pq Dv BPF_W , halfword .Pq Dv BPF_H , or byte .Pq Dv BPF_B . The semantics of all the recognized .Dv BPF_LD instructions follow. .Bd -literal BPF_LD+BPF_W+BPF_ABS A <- P[k:4] BPF_LD+BPF_H+BPF_ABS A <- P[k:2] BPF_LD+BPF_B+BPF_ABS A <- P[k:1] BPF_LD+BPF_W+BPF_IND A <- P[X+k:4] BPF_LD+BPF_H+BPF_IND A <- P[X+k:2] BPF_LD+BPF_B+BPF_IND A <- P[X+k:1] BPF_LD+BPF_W+BPF_LEN A <- len BPF_LD+BPF_IMM A <- k BPF_LD+BPF_MEM A <- M[k] .Ed .It Dv BPF_LDX These instructions load a value into the index register. Note that the addressing modes are more restrictive than those of the accumulator loads, but they include .Dv BPF_MSH , a hack for efficiently loading the IP header length. .Bd -literal BPF_LDX+BPF_W+BPF_IMM X <- k BPF_LDX+BPF_W+BPF_MEM X <- M[k] BPF_LDX+BPF_W+BPF_LEN X <- len BPF_LDX+BPF_B+BPF_MSH X <- 4*(P[k:1]&0xf) .Ed .It Dv BPF_ST This instruction stores the accumulator into the scratch memory. We do not need an addressing mode since there is only one possibility for the destination. .Bd -literal BPF_ST M[k] <- A .Ed .It Dv BPF_STX This instruction stores the index register in the scratch memory store. .Bd -literal BPF_STX M[k] <- X .Ed .It Dv BPF_ALU The alu instructions perform operations between the accumulator and index register or constant, and store the result back in the accumulator. For binary operations, a source mode is required .Dv ( BPF_K or .Dv BPF_X ) . .Bd -literal BPF_ALU+BPF_ADD+BPF_K A <- A + k BPF_ALU+BPF_SUB+BPF_K A <- A - k BPF_ALU+BPF_MUL+BPF_K A <- A * k BPF_ALU+BPF_DIV+BPF_K A <- A / k BPF_ALU+BPF_MOD+BPF_K A <- A % k BPF_ALU+BPF_AND+BPF_K A <- A & k BPF_ALU+BPF_OR+BPF_K A <- A | k BPF_ALU+BPF_XOR+BPF_K A <- A ^ k BPF_ALU+BPF_LSH+BPF_K A <- A << k BPF_ALU+BPF_RSH+BPF_K A <- A >> k BPF_ALU+BPF_ADD+BPF_X A <- A + X BPF_ALU+BPF_SUB+BPF_X A <- A - X BPF_ALU+BPF_MUL+BPF_X A <- A * X BPF_ALU+BPF_DIV+BPF_X A <- A / X BPF_ALU+BPF_MOD+BPF_X A <- A % X BPF_ALU+BPF_AND+BPF_X A <- A & X BPF_ALU+BPF_OR+BPF_X A <- A | X BPF_ALU+BPF_XOR+BPF_X A <- A ^ X BPF_ALU+BPF_LSH+BPF_X A <- A << X BPF_ALU+BPF_RSH+BPF_X A <- A >> X BPF_ALU+BPF_NEG A <- -A .Ed .It Dv BPF_JMP The jump instructions alter flow of control. Conditional jumps compare the accumulator against a constant .Pq Dv BPF_K or the index register .Pq Dv BPF_X . If the result is true (or non-zero), the true branch is taken, otherwise the false branch is taken. Jump offsets are encoded in 8 bits so the longest jump is 256 instructions. However, the jump always .Pq Dv BPF_JA opcode uses the 32 bit .Li k field as the offset, allowing arbitrarily distant destinations. All conditionals use unsigned comparison conventions. .Bd -literal BPF_JMP+BPF_JA pc += k BPF_JMP+BPF_JGT+BPF_K pc += (A > k) ? jt : jf BPF_JMP+BPF_JGE+BPF_K pc += (A >= k) ? jt : jf BPF_JMP+BPF_JEQ+BPF_K pc += (A == k) ? jt : jf BPF_JMP+BPF_JSET+BPF_K pc += (A & k) ? jt : jf BPF_JMP+BPF_JGT+BPF_X pc += (A > X) ? jt : jf BPF_JMP+BPF_JGE+BPF_X pc += (A >= X) ? jt : jf BPF_JMP+BPF_JEQ+BPF_X pc += (A == X) ? jt : jf BPF_JMP+BPF_JSET+BPF_X pc += (A & X) ? jt : jf .Ed .It Dv BPF_RET The return instructions terminate the filter program and specify the amount of packet to accept (i.e., they return the truncation amount). A return value of zero indicates that the packet should be ignored. The return value is either a constant .Pq Dv BPF_K or the accumulator .Pq Dv BPF_A . .Bd -literal BPF_RET+BPF_A accept A bytes BPF_RET+BPF_K accept k bytes .Ed .It Dv BPF_MISC The miscellaneous category was created for anything that does not fit into the above classes, and for any new instructions that might need to be added. Currently, these are the register transfer instructions that copy the index register to the accumulator or vice versa. .Bd -literal BPF_MISC+BPF_TAX X <- A BPF_MISC+BPF_TXA A <- X .Ed .El .Pp The .Nm interface provides the following macros to facilitate array initializers: .Fn BPF_STMT opcode operand and .Fn BPF_JUMP opcode operand true_offset false_offset . .Sh SYSCTL VARIABLES A set of .Xr sysctl 8 variables controls the behaviour of the .Nm subsystem .Bl -tag -width indent .It Va net.bpf.optimize_writers : No 0 Various programs use BPF to send (but not receive) raw packets (cdpd, lldpd, dhcpd, dhcp relays, etc. are good examples of such programs). They do not need incoming packets to be send to them. Turning this option on makes new BPF users to be attached to write-only interface list until program explicitly specifies read filter via .Fn pcap_set_filter . This removes any performance degradation for high-speed interfaces. .It Va net.bpf.stats : Binary interface for retrieving general statistics. .It Va net.bpf.zerocopy_enable : No 0 Permits zero-copy to be used with net BPF readers. Use with caution. .It Va net.bpf.maxinsns : No 512 Maximum number of instructions that BPF program can contain. Use .Xr tcpdump 1 .Fl d option to determine approximate number of instruction for any filter. .It Va net.bpf.maxbufsize : No 524288 Maximum buffer size to allocate for packets buffer. .It Va net.bpf.bufsize : No 4096 Default buffer size to allocate for packets buffer. .El .Sh EXAMPLES The following filter is taken from the Reverse ARP Daemon. It accepts only Reverse ARP requests. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_REVARP, 0, 3), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ARPOP_REVREQUEST, 0, 1), BPF_STMT(BPF_RET+BPF_K, sizeof(struct ether_arp) + sizeof(struct ether_header)), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Pp This filter accepts only IP packets between host 128.3.112.15 and 128.3.112.35. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 8), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 26), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 2), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 3, 4), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x80037023, 0, 3), BPF_STMT(BPF_LD+BPF_W+BPF_ABS, 30), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 0x8003700f, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Pp Finally, this filter returns only TCP finger packets. We must parse the IP header to reach the TCP header. The .Dv BPF_JSET instruction checks that the IP fragment offset is 0 so we are sure that we have a TCP header. .Bd -literal struct bpf_insn insns[] = { BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 12), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, ETHERTYPE_IP, 0, 10), BPF_STMT(BPF_LD+BPF_B+BPF_ABS, 23), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, IPPROTO_TCP, 0, 8), BPF_STMT(BPF_LD+BPF_H+BPF_ABS, 20), BPF_JUMP(BPF_JMP+BPF_JSET+BPF_K, 0x1fff, 6, 0), BPF_STMT(BPF_LDX+BPF_B+BPF_MSH, 14), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 14), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 2, 0), BPF_STMT(BPF_LD+BPF_H+BPF_IND, 16), BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, 79, 0, 1), BPF_STMT(BPF_RET+BPF_K, (u_int)-1), BPF_STMT(BPF_RET+BPF_K, 0), }; .Ed .Sh SEE ALSO .Xr tcpdump 1 , .Xr ioctl 2 , .Xr kqueue 2 , .Xr poll 2 , .Xr select 2 , .Xr ng_bpf 4 , .Xr bpf 9 .Rs .%A McCanne, S. .%A Jacobson V. .%T "An efficient, extensible, and portable network monitor" .Re .Sh HISTORY The Enet packet filter was created in 1980 by Mike Accetta and Rick Rashid at Carnegie-Mellon University. Jeffrey Mogul, at Stanford, ported the code to .Bx and continued its development from 1983 on. Since then, it has evolved into the Ultrix Packet Filter at .Tn DEC , a .Tn STREAMS .Tn NIT module under .Tn SunOS 4.1 , and .Tn BPF . .Sh AUTHORS .An -nosplit .An Steven McCanne , of Lawrence Berkeley Laboratory, implemented BPF in Summer 1990. Much of the design is due to .An Van Jacobson . .Pp Support for zero-copy buffers was added by .An Robert N. M. Watson under contract to Seccuris Inc. .Sh BUGS The read buffer must be of a fixed size (returned by the .Dv BIOCGBLEN ioctl). .Pp A file that does not request promiscuous mode may receive promiscuously received packets as a side effect of another file requesting this mode on the same hardware interface. This could be fixed in the kernel with additional processing overhead. However, we favor the model where all files must assume that the interface is promiscuous, and if so desired, must utilize a filter to reject foreign packets. .Pp The .Dv SEESENT , .Dv DIRECTION , and .Dv FEEDBACK settings have been observed to work incorrectly on some interface types, including those with hardware loopback rather than software loopback, and point-to-point interfaces. They appear to function correctly on a broad range of Ethernet-style interfaces. diff --git a/share/man/man7/orders.7 b/share/man/man7/orders.7 index aef44adde125..c1c2c1200e42 100644 --- a/share/man/man7/orders.7 +++ b/share/man/man7/orders.7 @@ -1,115 +1,115 @@ .\" $NetBSD: orders.7,v 1.6 2011/08/06 11:07:18 jruoho Exp $ .\" .\" Copyright (c) 2010 The NetBSD Foundation, Inc. .\" All rights reserved. .\" .\" This code is derived from software contributed to The NetBSD Foundation .\" by Jukka Ruohonen. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this 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. .\" .Dd November 20, 2022 .Dt ORDERS 7 .Os .Sh NAME .Nm orders .Nd orders of magnitude .Sh DESCRIPTION The following table lists common multiples of bytes. .Bl -column -offset 2n \ "Kilobyte" "Prefix" "Power of 2" "Power of 10" .It Sy Name Ta Sy Prefix Ta Sy Power of 2 Ta Sy Power of 10 .It Kilobyte Ta kB Ta 2^10 Ta 10^3 .It Megabyte Ta MB Ta 2^20 Ta 10^6 .It Gigabyte Ta GB Ta 2^30 Ta 10^9 .It Terabyte Ta TB Ta 2^40 Ta 10^12 .It Petabyte Ta PB Ta 2^50 Ta 10^15 .It Exabyte Ta EB Ta 2^60 Ta 10^18 .It Zettabyte Ta ZB Ta 2^70 Ta 10^21 .It Yottabyte Ta YB Ta 2^80 Ta 10^24 .It Ronnabyte Ta RB Ta 2^90 Ta 10^27 -.It Quettabyte Ta QB Ta 2^100 Ta 10^30. -El +.It Quettabyte Ta QB Ta 2^100 Ta 10^30 +.El .Pp The following table lists common bit rates as a power of ten. .Bl -column -offset 2n \ "Megabit per second" "Prefix" "Bit per second" "Byte per second" .It Sy Name Ta Sy Prefix Ta Sy Bit per second Ta Sy Byte per second .It Bit per second Ta bit/s Ta 1 Ta 0.125 .It Byte per second Ta B/s Ta 8 Ta 1 .It Kilobit per second Ta kbit/s Ta 10^3 Ta 125 .It Kilobyte per second Ta kB/s Ta 8 * 10^3 Ta 1000 .It Megabit per second Ta Mbit/s Ta 10^6 Ta 125000 .It Megabyte per second Ta MB/s Ta 8 * 10^6 Ta 1000000 .It Gigabit per second Ta Gbit/s Ta 10^9 Ta 125000000 .It Gigabyte per second Ta GB/s Ta 8 * 10^9 Ta 1000000000 .It Terabit per second Ta Tbit/s Ta 10^12 Ta 125000000000 .It Terabyte per second Ta TB/s Ta 8 * 10^12 Ta 1000000000000 .El .Pp The following table lists common orders of magnitude as a power of ten. .Bl -column -offset 2n \ "Septillionth" "Order" "Prefix" "Symbol" "Decimal" .It Sy Name Ta Sy Order Ta Sy Prefix Ta Sy Symbol Ta Sy Decimal .It Nonillionth Ta 10^-30 Ta quecto Ta q Ta 0.000000000000000000000000000001 .It Octillionth Ta 10^-27 Ta ronto Ta r Ta 0.000000000000000000000000001 .It Septillionth Ta 10^-24 Ta yocto Ta y Ta 0.000000000000000000000001 .It Sextillionth Ta 10^-21 Ta zepto Ta z Ta 0.000000000000000000001 .It Quintillionth Ta 10^-18 Ta atto Ta a Ta 0.000000000000000001 .It Quadrillionth Ta 10^-15 Ta femto Ta f Ta 0.000000000000001 .It Trillionth Ta 10^-12 Ta pico Ta p Ta 0.000000000001 .It Billionth Ta 10^-9 Ta nano Ta n Ta 0.000000001 .It Millionth Ta 10^-6 Ta micro Ta mu Ta 0.000001 .It Thousandth Ta 10^-3 Ta milli Ta m Ta 0.001 .It Hundredth Ta 10^-2 Ta centi Ta c Ta 0.01 .It Tenth Ta 10^-1 Ta deci Ta d Ta 0.1 .It One Ta 10^0 Ta - Ta - Ta 1 .It Ten Ta 10^1 Ta deca Ta da Ta 10 .It Hundred Ta 10^2 Ta hecto Ta h Ta 100 .It Thousand Ta 10^3 Ta kilo Ta k Ta 1000 .It Million Ta 10^6 Ta mega Ta M Ta 1000000 .It Billion Ta 10^9 Ta giga Ta G Ta 1000000000 .It Trillion Ta 10^12 Ta tera Ta T Ta 1000000000000 .It Quadrillion Ta 10^15 Ta peta Ta P Ta 1000000000000000 .It Quintillion Ta 10^18 Ta exa Ta E Ta 1000000000000000000 .It Sextillion Ta 10^21 Ta zetta Ta Z Ta 1000000000000000000000 .It Septillion Ta 10^24 Ta yotta Ta Y Ta 1000000000000000000000000 .It Octillion Ta 10^27 Ta ronna Ta R Ta 1000000000000000000000000000 .It Nonillion Ta 10^30 Ta quetta Ta Q Ta 1000000000000000000000000000000 .El .Sh SEE ALSO .Xr units 1 , .Xr number 6 .Sh STANDARDS There have been various attempts to standardize the set of binary prefixes. Organizations such as International Electrotechnical Commission .Pq Tn IEC have proposed new prefixes such as .Dq kibi , .Dq mebi , .Dq gibi , and .Dq yobi , but the adoption has been slow at best. .Sh AUTHORS This manual page was written by .An Jukka Ruohonen Aq Mt jruoho@netbsd.org . diff --git a/share/man/man9/zone.9 b/share/man/man9/zone.9 index a6b8d2dfedbe..9f13cf0e504a 100644 --- a/share/man/man9/zone.9 +++ b/share/man/man9/zone.9 @@ -1,639 +1,639 @@ .\"- .\" Copyright (c) 2001 Dag-Erling 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. .\" .Dd January 16, 2023 .Dt UMA 9 .Os .Sh NAME .Nm UMA .Nd general-purpose kernel object allocator .Sh SYNOPSIS .In sys/param.h .In sys/queue.h .In vm/uma.h .Bd -literal typedef int (*uma_ctor)(void *mem, int size, void *arg, int flags); typedef void (*uma_dtor)(void *mem, int size, void *arg); typedef int (*uma_init)(void *mem, int size, int flags); typedef void (*uma_fini)(void *mem, int size); typedef int (*uma_import)(void *arg, void **store, int count, int domain, int flags); typedef void (*uma_release)(void *arg, void **store, int count); typedef void *(*uma_alloc)(uma_zone_t zone, vm_size_t size, int domain, uint8_t *pflag, int wait); typedef void (*uma_free)(void *item, vm_size_t size, uint8_t pflag); .Ed .Ft uma_zone_t .Fo uma_zcreate .Fa "char *name" "size_t size" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini" .Fa "int align" "uint16_t flags" .Fc .Ft uma_zone_t .Fo uma_zcache_create .Fa "char *name" "int size" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini" .Fa "uma_import zimport" "uma_release zrelease" .Fa "void *arg" "int flags" .Fc .Ft uma_zone_t .Fo uma_zsecond_create .Fa "char *name" .Fa "uma_ctor ctor" "uma_dtor dtor" "uma_init zinit" "uma_fini zfini" .Fa "uma_zone_t master" .Fc .Ft void .Fn uma_zdestroy "uma_zone_t zone" .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_zalloc_domain "uma_zone_t zone" "void *arg" "int domain" "int flags" .Ft "void *" .Fn uma_zalloc_pcpu "uma_zone_t zone" "int flags" .Ft "void *" .Fn uma_zalloc_pcpu_arg "uma_zone_t zone" "void *arg" "int flags" .Ft "void *" .Fn uma_zalloc_smr "uma_zone_t zone" "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 void .Fn uma_zfree_pcpu "uma_zone_t zone" "void *item" .Ft void .Fn uma_zfree_pcpu_arg "uma_zone_t zone" "void *item" "void *arg" .Ft void .Fn uma_zfree_smr "uma_zone_t zone" "void *item" .Ft void .Fn uma_prealloc "uma_zone_t zone" "int nitems" .Ft void .Fn uma_zone_reserve "uma_zone_t zone" "int nitems" .Ft void .Fn uma_zone_reserve_kva "uma_zone_t zone" "int nitems" .Ft void .Fn uma_reclaim "int req" .Ft void .Fn uma_reclaim_domain "int req" "int domain" .Ft void .Fn uma_zone_reclaim "uma_zone_t zone" "int req" .Ft void .Fn uma_zone_reclaim_domain "uma_zone_t zone" "int req" "int domain" .Ft void .Fn uma_zone_set_allocf "uma_zone_t zone" "uma_alloc allocf" .Ft void .Fn uma_zone_set_freef "uma_zone_t zone" "uma_free freef" .Ft int .Fn uma_zone_set_max "uma_zone_t zone" "int nitems" .Ft void .Fn uma_zone_set_maxcache "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)" .Ft smr_t .Fn uma_zone_get_smr "uma_zone_t zone" .Ft void .Fn uma_zone_set_smr "uma_zone_t zone" "smr_t smr" .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 UMA (Universal Memory Allocator) provides an efficient interface for managing dynamically-sized collections of items of identical size, referred to as zones. Zones keep track of which items are in use and which are not, and UMA provides functions for allocating items from a zone and for releasing them back, making them available for subsequent allocation requests. Zones maintain per-CPU caches with linear scalability on SMP systems as well as round-robin and first-touch policies for NUMA systems. The number of items cached per CPU is bounded, and each zone additionally maintains an unbounded cache of items that is used to quickly satisfy per-CPU cache allocation misses. .Pp Two types of zones exist: regular zones and cache zones. In a regular zone, items are allocated from a slab, which is one or more virtually contiguous memory pages that have been allocated from the kernel's page allocator. Internally, slabs are managed by a UMA keg, which is responsible for allocating slabs and keeping track of their usage by one or more zones. In typical usage, there is one keg per zone, so slabs are not shared among multiple zones. .Pp Normal zones import items from a keg, and release items back to that keg if requested. Cache zones do not have a keg, and instead use custom import and release methods. For example, some collections of kernel objects are statically allocated at boot-time, and the size of the collection does not change. A cache zone can be used to implement an efficient allocator for the objects in such a collection. .Pp The .Fn uma_zcreate and .Fn uma_zcache_create functions create a new regular zone and cache zone, respectively. The .Fn uma_zsecond_create function creates a regular zone which shares the keg of the zone specified by the .Fa master argument. 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 initialize a data structure embedded in the item, such as a .Xr queue 3 head. .Pp The .Fa zinit and .Fa zfini arguments are used to optimize the allocation of items from the zone. They are called by the UMA subsystem whenever it needs to allocate or free items to satisfy requests or memory pressure. A good use for the .Fa zinit and .Fa zfini callbacks might be to initialize and destroy a mutex contained within an item. This would allow one to avoid destroying and re-initializing the mutex each time the item is freed and re-allocated. They are not called on each call to .Fn uma_zalloc and .Fn uma_zfree but rather when an item is imported into a zone's cache, and when a zone releases an item to the slab allocator, typically as a response to memory pressure. .Pp For .Fn uma_zcache_create , the .Fa zimport and .Fa zrelease functions are called to import items into the zone and to release items from the zone, respectively. The .Fa zimport function should store pointers to items in the .Fa store array, which contains a maximum of .Fa count entries. The function must return the number of imported items, which may be less than the maximum. Similarly, the .Fa store parameter to the .Fa zrelease function contains an array of .Fa count pointers to items. The .Fa arg parameter passed to .Fn uma_zcache_create is provided to the import and release functions. The .Fa domain parameter to .Fa zimport specifies the requested .Xr numa 4 domain for the allocation. It is either a NUMA domain number or the special value .Dv UMA_ANYDOMAIN . .Pp The .Fa flags argument of .Fn uma_zcreate and .Fn uma_zcache_create is a subset of the following flags: .Bl -tag -width "foo" .It Dv UMA_ZONE_NOFREE Slabs allocated to the zone's keg are never freed. .It Dv UMA_ZONE_NODUMP Pages belonging to the zone will not be included in minidumps. .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 the allocation address plus a multiple of the 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 Note that .Dv M_ZERO cannot be used when allocating items from a PCPU zone. To obtain zeroed memory from a PCPU zone, use the .Fn uma_zalloc_pcpu function and its variants instead, and pass .Dv M_ZERO . .It Dv UMA_ZONE_NOTOUCH The UMA subsystem may not directly touch (i.e. read or write) the slab memory. Otherwise, by default, book-keeping of items within a slab may be done in the slab page itself, and .Dv INVARIANTS kernels may also do use-after-free checking by accessing the slab memory. .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_NOTPAGE An allocator function will be supplied with .Fn uma_zone_set_allocf and the memory that it returns may not be kernel virtual memory backed by VM pages in the page array. .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. .It Dv UMA_ZONE_CONTIG Items in this zone must be contiguous in physical address space. Items will follow normal alignment constraints and may span page boundaries between pages with contiguous physical addresses. .It Dv UMA_ZONE_UNMANAGED By default, UMA zone caches are shrunk to help resolve free page shortages. Cached items that have not been used for a long period may also be freed from zone. When this flag is set, the system will not reclaim memory from the zone's caches. .It Dv UMA_ZONE_SMR Create a zone whose items will be synchronized using the .Xr smr 9 mechanism. Upon creation the zone will have an associated -.Dt smr_t +.Ft smr_t structure which can be fetched using .Fn uma_zone_get_smr . .El .Pp Zones can be destroyed using .Fn uma_zdestroy , freeing all memory that is cached in the zone. All items allocated from the zone must be freed to the zone before the zone may be safely destroyed. .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 variants .Fn uma_zalloc_arg and .Fn uma_zfree_arg allow callers to specify an argument for the .Dv ctor and .Dv dtor functions of the zone, respectively. The variants .Fn uma_zalloc_pcpu and .Fn uma_zfree_pcpu allocate and free .Va mp_ncpu shadow copies as described for .Dv UMA_ZONE_PCPU . If .Fa item is .Dv NULL , then .Fn uma_zfree_pcpu does nothing. .Pp The .Fn uma_zalloc_smr and .Fn uma_zfree_smr functions allocate and free items from an SMR-enabled zone, that is, a zone created with .Dv UMA_ZONE_SMR or a zone that has had .Fn uma_zone_set_smr called. .Pp The .Fn uma_zalloc_domain function allows callers to specify a fixed .Xr numa 4 domain to allocate from. This uses a guaranteed but slow path in the allocator which reduces concurrency. .Pp The .Fn uma_prealloc function allocates slabs for the requested number of items, typically following the initial creation of a zone. Subsequent allocations from the zone will be satisfied using the pre-allocated slabs. Note that slab allocation is performed with the .Dv M_WAITOK flag, so .Fn uma_prealloc may sleep. .Pp The .Fn uma_zone_reserve function sets the number of reserved items for the zone. .Fn uma_zalloc and variants will ensure that the zone contains at least the reserved number of free items. Reserved items may be allocated by specifying .Dv M_USE_RESERVE in the allocation request flags. .Fn uma_zone_reserve does not perform any pre-allocation by itself. .Pp The .Fn uma_zone_reserve_kva function pre-allocates kernel virtual address space for the requested number of items. Subsequent allocations from the zone will be satisfied using the pre-allocated address space. Note that unlike .Fn uma_zone_reserve , .Fn uma_zone_reserve_kva does not restrict the use of the pre-allocation to .Dv M_USE_RESERVE requests. .Pp The .Fn uma_reclaim and .Fn uma_zone_reclaim functions reclaim cached items from UMA zones, releasing unused memory. The .Fn uma_reclaim function reclaims items from all regular zones, while .Fn uma_zone_reclaim reclaims items only from the specified zone. The .Fa req parameter must be one of three values which specify how aggressively items are to be reclaimed: .Bl -tag -width indent .It Dv UMA_RECLAIM_TRIM Reclaim items only in excess of the zone's estimated working set size. The working set size is periodically updated and tracks the recent history of the zone's usage. .It Dv UMA_RECLAIM_DRAIN Reclaim all items from the unbounded cache. Free items in the per-CPU caches are left alone. .It Dv UMA_RECLAIM_DRAIN_CPU Reclaim all cached items. .El The .Fn uma_reclaim_domain and .Fn uma_zone_reclaim_domain functions apply only to items allocated from the specified domain. In the case of domains using a round-robin NUMA policy, cached items from all domains are freed to the keg, but only slabs from the specific domain will be freed. .Pp The .Fn uma_zone_set_allocf and .Fn uma_zone_set_freef functions allow a zone's default slab allocation and free functions to be overridden. This is useful if memory with special constraints such as attributes, alignment, or address ranges must be used. .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_set_maxcache function limits the number of free items which may be cached in the zone. This limit applies to both the per-CPU caches and the cache of free buckets. .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 an approximation of the number of items currently allocated from 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 uma_zone_set_smr function associates an existing .Xr smr 9 structure with a UMA zone. The effect is similar to creating a zone with the .Dv UMA_ZONE_SMR flag, except that a new SMR structure is not created. This function must be called before any allocations from the zone are performed. .Pp The .Fn SYSCTL_UMA_MAX parent nbr name access zone descr macro declares a static .Xr sysctl 9 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 9 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 IMPLEMENTATION NOTES The memory that these allocation calls return is not executable. The .Fn uma_zalloc function does not support the .Dv M_EXEC flag to allocate executable memory. Not all platforms enforce a distinction between executable and non-executable memory. .Sh SEE ALSO .Xr numa 4 , .Xr vmstat 8 , .Xr malloc 9 , .Xr smr 9 .Rs .%A Jeff Bonwick .%T "The Slab Allocator: An Object-Caching Kernel Memory Allocator" .%D 1994 .Re .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 .