From owner-svn-src-head@freebsd.org Fri Mar 3 06:18:48 2017 Return-Path: Delivered-To: svn-src-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id DD3D1CF4525; Fri, 3 Mar 2017 06:18:48 +0000 (UTC) (envelope-from ngie@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 9DF1816A0; Fri, 3 Mar 2017 06:18:48 +0000 (UTC) (envelope-from ngie@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v236Il7c010581; Fri, 3 Mar 2017 06:18:47 GMT (envelope-from ngie@FreeBSD.org) Received: (from ngie@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v236Il5v010580; Fri, 3 Mar 2017 06:18:47 GMT (envelope-from ngie@FreeBSD.org) Message-Id: <201703030618.v236Il5v010580@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: ngie set sender to ngie@FreeBSD.org using -f From: Ngie Cooper Date: Fri, 3 Mar 2017 06:18:47 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r314586 - head/share/man/man4 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the src tree for head/-current List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 03 Mar 2017 06:18:49 -0000 Author: ngie Date: Fri Mar 3 06:18:47 2017 New Revision: 314586 URL: https://svnweb.freebsd.org/changeset/base/314586 Log: Clean up netmap(4) slightly - Add missing sections for .Xr references. - Replace .br with .Pp (the former macro is deprecated). - Use the .Sx (section reference) macro when referring to LIBRARIES, not the .Xr (cross-reference) macro. - Add commas after "e.g." and "i.e." [*]. Bump .Dd for the change Approved by: luigi MFC after: 1 week Reported by: igor [*], make manlint Sponsored by: Dell EMC Isilon Differential Revision: D9859 Modified: head/share/man/man4/netmap.4 Modified: head/share/man/man4/netmap.4 ============================================================================== --- head/share/man/man4/netmap.4 Fri Mar 3 06:13:59 2017 (r314585) +++ head/share/man/man4/netmap.4 Fri Mar 3 06:18:47 2017 (r314586) @@ -27,16 +27,15 @@ .\" .\" $FreeBSD$ .\" -.Dd December 14, 2015 +.Dd March 2, 2017 .Dt NETMAP 4 .Os .Sh NAME .Nm netmap .Nd a framework for fast packet I/O -.br .Nm VALE .Nd a fast VirtuAl Local Ethernet using the netmap API -.br +.Pp .Nm netmap pipes .Nd a shared memory packet transport channel .Sh SYNOPSIS @@ -61,7 +60,7 @@ implementing a very fast and modular in- a shared memory packet transport channel; .It Nm netmap monitors a mechanism similar to -.Xr bpf +.Xr bpf 4 to capture traffic .El .Pp @@ -85,7 +84,7 @@ NICs without native .Nm support can still use the API in emulated mode, which uses unmodified device drivers and is 3-5 times faster than -.Xr bpf +.Xr bpf 4 or raw sockets. .Pp Userspace clients can dynamically switch NICs into @@ -175,8 +174,9 @@ ports (including and .Nm netmap pipe ports). -Simpler, higher level functions are described in section -.Xr LIBRARIES . +Simpler, higher level functions are described in the +.Sx LIBRARIES +section. .Pp Ports and rings are created and controlled through a file descriptor, created by opening a special device @@ -191,14 +191,14 @@ argument. .Va arg.nr_name specifies the netmap port name, as follows: .Bl -tag -width XXXX -.It Dv OS network interface name (e.g. 'em0', 'eth1', ... ) +.It Dv OS network interface name (e.g., 'em0', 'eth1', ... ) the data path of the NIC is disconnected from the host stack, and the file descriptor is bound to the NIC (one or all queues), or to the host stack; .It Dv valeSSS:PPP the file descriptor is bound to port PPP of VALE switch SSS. Switch instances and ports are dynamically created if necessary. -.br +.Pp Both SSS and PPP have the form [0-9a-zA-Z_]+ , the string cannot exceed IFNAMSIZ characters, and PPP cannot be the name of any existing OS network interface. @@ -340,14 +340,14 @@ should not be assumed to be a power of t .Pp .Va head is the first slot available to userspace; -.br +.Pp .Va cur is the wakeup point: select/poll will unblock when .Va tail passes .Va cur ; -.br +.Pp .Va tail is the first slot reserved to the kernel. .Pp @@ -419,7 +419,7 @@ Below is an example of the evolution of .Fn select and .Fn poll -will block if there is no space in the ring, i.e. +will block if there is no space in the ring, i.e., .Dl ring->cur == ring->tail and return when new slots have become available. .Pp @@ -453,7 +453,7 @@ slots up to are returned to the kernel for further receives, and .Va tail may advance to report new incoming packets. -.br +.Pp Below is an example of the evolution of an RX ring: .Bd -literal after the syscall, there are some (h)eld and some (R)eceived slots @@ -510,7 +510,7 @@ packet must not be used in the learning indicates that the packet's payload is in a user-supplied buffer whose user virtual address is in the 'ptr' field of the slot. The size can reach 65535 bytes. -.br +.Pp This is only supported on the transmit ring of .Nm VALE ports, and it helps reducing data copies in the interconnection @@ -592,8 +592,8 @@ indicate the size of transmit and receiv indicate the number of transmit and receive rings. Both ring number and sizes may be configured at runtime -using interface-specific functions (e.g. -.Xr ethtool +using interface-specific functions (e.g., +.Xr ethtool 8 ). .El .It Dv NIOCREGIF @@ -611,7 +611,7 @@ The recommended way to bind a file descr to use function .Va nm_open(..) (see -.Xr LIBRARIES ) +.Sx LIBRARIES ) which parses names to access specific port types and enable features. In the following we document the main features. @@ -761,7 +761,7 @@ The following functions are available: .Bl -tag -width XXXXX .It Va struct nm_desc * nm_open(const char *ifname, const struct nmreq *req, uint64_t flags, const struct nm_desc *arg) similar to -.Xr pcap_open , +.Xr pcap_open 3pcap , binds a file descriptor to a port. .Bl -tag -width XX .It Va ifname @@ -774,7 +774,7 @@ The nm_flags and nm_ringid values are ov ifname and flags, and other fields can be overridden through the other two arguments. .It Va arg -points to a struct nm_desc containing arguments (e.g. from a previously +points to a struct nm_desc containing arguments (e.g., from a previously open file descriptor) that should override the defaults. The fields are used as described below .It Va flags @@ -830,10 +830,11 @@ mode but still significantly higher than Note that for slow devices (such as 1 Gbit/s and slower NICs, or several 10 Gbit/s NICs whose hardware is unable to sustain line rate), emulated and native mode will likely have similar or same throughput. -.br +.Pp When emulation is in use, packet sniffer programs such as tcpdump -could see received packets before they are diverted by netmap. This behaviour -is not intentional, being just an artifact of the implementation of emulation. +could see received packets before they are diverted by netmap. +This behaviour is not intentional, being just an artifact of the implementation +of emulation. Note that in case the netmap application subsequently moves packets received from the emulated adapter onto the host RX ring, the sniffer will intercept those packets again, since the packets are injected to the host stack as they @@ -854,11 +855,11 @@ and module parameters on Linux .Bl -tag -width indent .It Va dev.netmap.admode: 0 Controls the use of native or emulated adapter mode. -.br +.Pp 0 uses the best available option; -.br +.Pp 1 forces native mode and fails if not available; -.br +.Pp 2 forces emulated hence never fails. .It Va dev.netmap.generic_ringsize: 1024 Ring size used for emulated netmap mode @@ -939,7 +940,7 @@ directory in .Fx distributions. .Pp -.Xr pkt-gen +.Xr pkt-gen 8 is a general purpose traffic source/sink. .Pp As an example @@ -950,11 +951,11 @@ is a traffic sink. Both print traffic statistics, to help monitor how the system performs. .Pp -.Xr pkt-gen +.Xr pkt-gen 8 has many options can be uses to set packet sizes, addresses, rates, and use multiple send/receive threads and cores. .Pp -.Xr bridge +.Xr bridge 4 is another test program which interconnects two .Nm ports. @@ -1046,7 +1047,7 @@ to replenish the receive ring: .Ed .Ss ACCESSING THE HOST STACK The host stack is for all practical purposes just a regular ring pair, -which you can access with the netmap API (e.g. with +which you can access with the netmap API (e.g., with .Dl nm_open("netmap:eth0^", ... ) ; All packets that the host would send to an interface in .Nm @@ -1056,11 +1057,11 @@ TX ring are send up to the host stack. A simple way to test the performance of a .Nm VALE switch is to attach a sender and a receiver to it, -e.g. running the following in two different terminals: +e.g., running the following in two different terminals: .Dl pkt-gen -i vale1:a -f rx # receiver .Dl pkt-gen -i vale1:b -f tx # sender The same example can be used to test netmap pipes, by simply -changing port names, e.g. +changing port names, e.g., .Dl pkt-gen -i vale2:x{3 -f rx # receiver on the master side .Dl pkt-gen -i vale2:x}3 -f tx # sender on the slave side .Pp @@ -1128,7 +1129,7 @@ multiqueue, schedulers, packet filters. Multiple transmit and receive rings are supported natively and can be configured with ordinary OS tools, such as -.Xr ethtool +.Xr ethtool 8 or device-specific sysctl variables. The same goes for Receive Packet Steering (RPS)