1.\" Copyright (c) 2016 Michio Honda. 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd April 2, 2021 28.Dt VALECTL 8 29.Os 30.Sh NAME 31.Nm valectl 32.Nd manage VALE switches provided by netmap 33.Sh SYNOPSIS 34.Bk -words 35.Bl -tag -width "valectl" 36.It Nm 37.Op Fl g Ar valeSSS:PPP 38.Op Fl a Ar valeSSS:interface 39.Op Fl h Ar valeSSS:interface 40.Op Fl d Ar valeSSS:interface 41.Op Fl n Ar interface 42.Op Fl r Ar interface 43.Op Fl l Ar valeSSS:PPP 44.Op Fl l 45.Op Fl p Ar valeSSS:PPP 46.Op Fl P Ar valeSSS:PPP 47.Op Fl C Ar spec 48.Op Fl m Ar memid 49.El 50.Ek 51.Sh DESCRIPTION 52.Nm 53manages and inspects 54.Xr vale 4 55switches, for instance attaching and detaching interfaces, creating 56and deleting persistent VALE ports, or listing the existing switches 57and their ports. 58In the following, 59.Ar valeSSS 60is the name of a VALE switch, while 61.Ar valeSSS:PPP 62is the name of a VALE port of 63.Ar valeSSS . 64.Pp 65When issued without options it lists all the existing switch ports together 66with their internal bridge number and port number. 67.Bl -tag -width Ds 68.It Fl g Ar valeSSS:PPP 69Print the number of receive rings of 70.Ar valeSSS:PPP . 71.It Fl a Ar valeSSS:interface 72Attach 73.Ar interface 74(which must be an existing network interface) to 75.Ar valeSSS 76and detach it from the host stack. 77.It Fl h Ar valeSSS:interface 78Attach 79.Ar interface 80(which must be an existing network interface) to 81.Ar valeSSS 82while keeping it attached to the host stack. 83More precisely, packets coming from 84the host stack and directed to the interface will go through the switch, where 85they can still reach the interface if the switch rules allow it. 86Conversely, packets coming from the interface will go through the switch and, 87if appropriate, will reach the host stack. 88.It Fl d Ar valeSSS:interface 89Detach 90.Ar interface 91from 92.Ar valeSSS . 93.It Fl n Ar interface 94Create a new persistent VALE port with name 95.Ar interface . 96The name must be different from any other network interface 97already present in the system. 98.It Fl r Ar interface 99Destroy the persistent VALE port with name 100.Ar interface . 101.It Fl l Ar valeSSS:PPP 102Show the internal bridge number and port number of the given switch port. 103.It Fl p Ar valeSSS:PPP 104Enable polling mode for 105.Ar valeSSS:PPP . 106In polling mode, a dedicated kernel thread is spawned to handle packets 107received from 108.Ar valeSSS:PPP 109and push them into the switch. 110The kernel thread busy waits on the switch port rather than relying on 111interrupts or notifications. 112Polling mode can only be used on physical NICs attached to a VALE switch. 113.It Fl P Ar valeSSS:PPP 114Disable polling mode for 115.Ar valeSSS:PPP . 116.It Fl C Ar x | Ar x,y | Ar x,y,z | Ar x,y,z,w 117When used in conjunction with 118.Fl n 119it supplies the number of tx and rx rings and slots. 120The full format with four numbers gives, in order, number of tx slots, number 121of rx slots, number of tx rings and number of rx rings. 122The form with three numbers uses 123.Ar z 124for both the number of tx and the number of rx rings. 125The forms with less than two numbers use the default values for the number 126of rings. 127The form with two numbers supplies the numbers of tx and rx slots. 128The form with only one number uses 129.Ar x 130for both the number of tx and the number of rx slots. 131.Pp 132When used in conjunction with 133.Fl p 134only the first three forms are used. 135The first number may be either 0 or 1. 136If 0, then all interface rings will be polled by a single thread, running 137on the core id given by the second number (the third number, if present, 138must be 1). 139If the first number is 1, then the ring identified by the second number will 140be polled by the core with the same id. 141If a third number is given, then this is repeated for as many consecutive 142rings and cores. 143.It Fl m Ar memid 144Used in conjunction with 145.Fl n 146supplies the netmap memory region identifier to use together with the newly 147created persistent VALE port. 148These ports use a private memory region by default. 149Using this option you can let them share memory with other ports. 150Pass 1 as 151.Ar memid 152to use the global memory region already shared by all 153hardware netmap ports. 154.El 155.Sh SEE ALSO 156.Xr netmap 4 , 157.Xr vale 4 158.Sh AUTHORS 159.An -nosplit 160.Nm 161has been written by 162.An Michio Honda 163at NetApp. 164