From 31f8817ab0e841d27af38197927937052bea6826 Mon Sep 17 00:00:00 2001 From: vmaffione Date: Mon, 3 Dec 2018 17:46:53 +0000 Subject: [PATCH] MFC r339685 netmap: add man page for the vale-ctl program Added man page for vale-ctl program. Small fixes to vale-ctl, including the support for -m option (to specify the netmap memory allocator id). Reviewed by: 0mp Approved by: gnn (mentor) Differential Revision: https://reviews.freebsd.org/D17683 --- tools/tools/netmap/vale-ctl.4 | 163 ++++++++++++++++++++++++++++++++++ tools/tools/netmap/vale-ctl.c | 127 +++++++++++++++++--------- 2 files changed, 250 insertions(+), 40 deletions(-) create mode 100644 tools/tools/netmap/vale-ctl.4 diff --git a/tools/tools/netmap/vale-ctl.4 b/tools/tools/netmap/vale-ctl.4 new file mode 100644 index 00000000000..67e07e59f14 --- /dev/null +++ b/tools/tools/netmap/vale-ctl.4 @@ -0,0 +1,163 @@ +.\" Copyright (c) 2016 Michio Honda. +.\" 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 24, 2018 +.Dt VALE-CTL 4 +.Os +.Sh NAME +.Nm vale-ctl +.Nd manage VALE switches provided by netmap +.Sh SYNOPSIS +.Bk -words +.Bl -tag -width "vale-ctl" +.It Nm +.Op Fl g Ar valeSSS:PPP +.Op Fl a Ar valeSSS:interface +.Op Fl h Ar valeSSS:interface +.Op Fl d Ar valeSSS:interface +.Op Fl n Ar interface +.Op Fl r Ar interface +.Op Fl l Ar valeSSS:PPP +.Op Fl l +.Op Fl p Ar valeSSS:PPP +.Op Fl P Ar valeSSS:PPP +.Op Fl C Ar spec +.Op Fl m Ar memid +.El +.Ek +.Sh DESCRIPTION +.Nm +manages and inspects +.Xr vale 4 +switches, for instance attaching and detaching interfaces, creating +and deleting persistent VALE ports, or listing the existing switches +and their ports. +In the following, +.Ar valeSSS +is the name of a VALE switch, while +.Ar valeSSS:PPP +is the name of a VALE port of +.Ar valeSSS . +.Pp +When issued without options it lists all the existing switch ports together +with their internal bridge number and port number. +.Bl -tag -width Ds +.It Fl g Ar valeSSS:PPP +Print the number of receive rings of +.Ar valeSSS:PPP . +.It Fl a Ar valeSSS:interface +Attach +.Ar interface +(which must be an existing network interface) to +.Ar valeSSS +and detach it from the host stack. +.It Fl h Ar valeSSS:interface +Attach +.Ar interface +(which must be an existing network interface) to +.Ar valeSSS +while keeping it attached to the host stack. +More precisely, packets coming from +the host stack and directed to the interface will go through the switch, where +they can still reach the interface if the switch rules allow it. +Conversely, packets coming from the interface will go through the switch and, +if appropriate, will reach the host stack. +.It Fl d Ar valeSSS:interface +Detach +.Ar interface +from +.Ar valeSSS . +.It Fl n Ar interface +Create a new persistent VALE port with name +.Ar interface . +The name must be different from any other network interface +already present in the system. +.It Fl d Ar interface +Destroy the persistent VALE port with name +.Ar inteface . +.It Fl l Ar valeSSS:PPP +Show the internal bridge number and port number of the given switch port. +.It Fl p Ar valeSSS:PPP +Enable polling mode for +.Ar valeSSS:PPP . +In polling mode, a dedicated kernel thread is spawned to handle packets +received from +.Ar valeSSS:PPP +and push them into the switch. +The kernel thread busy waits on the switch port rather than relying on +interrupts or notifications. +Polling mode can only be used on physical NICs attached to a VALE switch. +.It Fl P Ar valeSSS:PPP +Disable polling mode for +.Ar valeSSS:PPP . +.It Fl C Ar x | Ar x,y | Ar x,y,z | Ar x,y,z,w +When used in conjunction with +.Fl n +it supplies the number of tx and rx rings and slots. +The full format with four numbers gives, in order, number of tx slots, number +of rx slots, number of tx rings and number of rx rings. +The form with three numbers uses +.Ar z +for both the number of tx and the number of rx rings. +The forms with less than two numbers use the default values for the number +of rings. +The form with two numbers supplies the numbers of tx and rx slots. +The form with only one number uses +.Ar x +for both the number of tx and the number of rx slots. +.Pp +When used in conjunction with +.Fl p +only the first three forms are used. +The first number may be either 0 or 1. +If 0, then all interface rings will be polled by a single thread, running +on the core id given by the second number (the third number, if present, +must be 1). +If the first number is 1, then the ring identified by the second number will +be polled by the core with the same id. +If a third number is given, then this is repeated for as many consecutive +rings and cores. +.It Fl m Ar memid +Used in conjunction with +.Fl n +supplies the netmap memory region identifier to use together with the newly +created persistent VALE port. +These ports use a private memory region by default. +Using this option you can let them share memory with other ports. +Pass 1 as +.Ar memid +to use the global memory region already shared by all +harware netmap ports. +.El +.Sh SEE ALSO +.Xr netmap 4 , +.Xr vale 4 +.Sh AUTHORS +.An -nosplit +.Nm +has been written by +.An Michio Honda +at NetApp. diff --git a/tools/tools/netmap/vale-ctl.c b/tools/tools/netmap/vale-ctl.c index c9e5f31b920..fc909144a3c 100644 --- a/tools/tools/netmap/vale-ctl.c +++ b/tools/tools/netmap/vale-ctl.c @@ -25,6 +25,10 @@ /* $FreeBSD$ */ +#define NETMAP_WITH_LIBS +#include +#include + #include #include #include /* PRI* macros */ @@ -35,17 +39,9 @@ #include #include /* apple needs sockaddr */ #include /* ifreq */ -#include -#include #include /* basename */ #include /* atoi, free */ -/* debug support */ -#define ND(format, ...) do {} while(0) -#define D(format, ...) \ - fprintf(stderr, "%s [%d] " format "\n", \ - __FUNCTION__, __LINE__, ##__VA_ARGS__) - /* XXX cut and paste from pkt-gen.c because I'm not sure whether this * program may include nm_util.h */ @@ -86,7 +82,7 @@ void parse_nmr_config(const char* conf, struct nmreq *nmr) } static int -bdg_ctl(const char *name, int nr_cmd, int nr_arg, char *nmr_config) +bdg_ctl(const char *name, int nr_cmd, int nr_arg, char *nmr_config, int nr_arg2) { struct nmreq nmr; int error = 0; @@ -100,9 +96,10 @@ bdg_ctl(const char *name, int nr_cmd, int nr_arg, char *nmr_config) bzero(&nmr, sizeof(nmr)); nmr.nr_version = NETMAP_API; if (name != NULL) /* might be NULL */ - strncpy(nmr.nr_name, name, sizeof(nmr.nr_name)); + strncpy(nmr.nr_name, name, sizeof(nmr.nr_name)-1); nmr.nr_cmd = nr_cmd; parse_nmr_config(nmr_config, &nmr); + nmr.nr_arg2 = nr_arg2; switch (nr_cmd) { case NETMAP_BDG_DELIF: @@ -117,8 +114,11 @@ bdg_ctl(const char *name, int nr_cmd, int nr_arg, char *nmr_config) break; case NETMAP_BDG_ATTACH: case NETMAP_BDG_DETACH: - if (nr_arg && nr_arg != NETMAP_BDG_HOST) + nmr.nr_flags = NR_REG_ALL_NIC; + if (nr_arg && nr_arg != NETMAP_BDG_HOST) { + nmr.nr_flags = NR_REG_NIC_SW; nr_arg = 0; + } nmr.nr_arg1 = nr_arg; error = ioctl(fd, NIOCREGIF, &nmr); if (error == -1) { @@ -152,6 +152,36 @@ bdg_ctl(const char *name, int nr_cmd, int nr_arg, char *nmr_config) break; + case NETMAP_BDG_POLLING_ON: + case NETMAP_BDG_POLLING_OFF: + /* We reuse nmreq fields as follows: + * nr_tx_slots: 0 and non-zero indicate REG_ALL_NIC + * REG_ONE_NIC, respectively. + * nr_rx_slots: CPU core index. This also indicates the + * first queue in the case of REG_ONE_NIC + * nr_tx_rings: (REG_ONE_NIC only) indicates the + * number of CPU cores or the last queue + */ + nmr.nr_flags |= nmr.nr_tx_slots ? + NR_REG_ONE_NIC : NR_REG_ALL_NIC; + nmr.nr_ringid = nmr.nr_rx_slots; + /* number of cores/rings */ + if (nmr.nr_flags == NR_REG_ALL_NIC) + nmr.nr_arg1 = 1; + else + nmr.nr_arg1 = nmr.nr_tx_rings; + + error = ioctl(fd, NIOCREGIF, &nmr); + if (!error) + D("polling on %s %s", nmr.nr_name, + nr_cmd == NETMAP_BDG_POLLING_ON ? + "started" : "stopped"); + else + D("polling on %s %s (err %d)", nmr.nr_name, + nr_cmd == NETMAP_BDG_POLLING_ON ? + "couldn't start" : "couldn't stop", error); + break; + default: /* GINFO */ nmr.nr_cmd = nmr.nr_arg1 = nmr.nr_arg2 = 0; error = ioctl(fd, NIOCGINFO, &nmr); @@ -166,36 +196,44 @@ bdg_ctl(const char *name, int nr_cmd, int nr_arg, char *nmr_config) return error; } +static void +usage(int errcode) +{ + fprintf(stderr, + "Usage:\n" + "vale-ctl arguments\n" + "\t-g interface interface name to get info\n" + "\t-d interface interface name to be detached\n" + "\t-a interface interface name to be attached\n" + "\t-h interface interface name to be attached with the host stack\n" + "\t-n interface interface name to be created\n" + "\t-r interface interface name to be deleted\n" + "\t-l list all or specified bridge's interfaces (default)\n" + "\t-C string ring/slot setting of an interface creating by -n\n" + "\t-p interface start polling. Additional -C x,y,z configures\n" + "\t\t x: 0 (REG_ALL_NIC) or 1 (REG_ONE_NIC),\n" + "\t\t y: CPU core id for ALL_NIC and core/ring for ONE_NIC\n" + "\t\t z: (ONE_NIC only) num of total cores/rings\n" + "\t-P interface stop polling\n" + "\t-m memid to use when creating a new interface\n"); + exit(errcode); +} + int main(int argc, char *argv[]) { int ch, nr_cmd = 0, nr_arg = 0; - const char *command = basename(argv[0]); char *name = NULL, *nmr_config = NULL; + int nr_arg2 = 0; - if (argc > 3) { -usage: - fprintf(stderr, - "Usage:\n" - "%s arguments\n" - "\t-g interface interface name to get info\n" - "\t-d interface interface name to be detached\n" - "\t-a interface interface name to be attached\n" - "\t-h interface interface name to be attached with the host stack\n" - "\t-n interface interface name to be created\n" - "\t-r interface interface name to be deleted\n" - "\t-l list all or specified bridge's interfaces (default)\n" - "\t-C string ring/slot setting of an interface creating by -n\n" - "", command); - return 0; - } - - while ((ch = getopt(argc, argv, "d:a:h:g:l:n:r:C:")) != -1) { - name = optarg; /* default */ + while ((ch = getopt(argc, argv, "d:a:h:g:l:n:r:C:p:P:m:")) != -1) { + if (ch != 'C' && ch != 'm') + name = optarg; /* default */ switch (ch) { default: fprintf(stderr, "bad option %c %s", ch, optarg); - goto usage; + usage(-1); + break; case 'd': nr_cmd = NETMAP_BDG_DETACH; break; @@ -217,19 +255,28 @@ main(int argc, char *argv[]) break; case 'l': nr_cmd = NETMAP_BDG_LIST; - if (optind < argc && argv[optind][0] == '-') - name = NULL; break; case 'C': nmr_config = strdup(optarg); break; - } - if (optind != argc) { - // fprintf(stderr, "optind %d argc %d\n", optind, argc); - goto usage; + case 'p': + nr_cmd = NETMAP_BDG_POLLING_ON; + break; + case 'P': + nr_cmd = NETMAP_BDG_POLLING_OFF; + break; + case 'm': + nr_arg2 = atoi(optarg); + break; } } - if (argc == 1) + if (optind != argc) { + // fprintf(stderr, "optind %d argc %d\n", optind, argc); + usage(-1); + } + if (argc == 1) { nr_cmd = NETMAP_BDG_LIST; - return bdg_ctl(name, nr_cmd, nr_arg, nmr_config) ? 1 : 0; + name = NULL; + } + return bdg_ctl(name, nr_cmd, nr_arg, nmr_config, nr_arg2) ? 1 : 0; } -- 2.45.0