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.Dd April 2, 2021 26.Dt VALECTL 8 27.Os 28.Sh NAME 29.Nm valectl 30.Nd manage VALE switches provided by netmap 31.Sh SYNOPSIS 32.Bk -words 33.Bl -tag -width "valectl" 34.It Nm 35.Op Fl g Ar valeSSS:PPP 36.Op Fl a Ar valeSSS:interface 37.Op Fl h Ar valeSSS:interface 38.Op Fl d Ar valeSSS:interface 39.Op Fl n Ar interface 40.Op Fl r Ar interface 41.Op Fl l Ar valeSSS:PPP 42.Op Fl l 43.Op Fl p Ar valeSSS:PPP 44.Op Fl P Ar valeSSS:PPP 45.Op Fl C Ar spec 46.Op Fl m Ar memid 47.El 48.Ek 49.Sh DESCRIPTION 50.Nm 51manages and inspects 52.Xr vale 4 53switches, for instance attaching and detaching interfaces, creating 54and deleting persistent VALE ports, or listing the existing switches 55and their ports. 56In the following, 57.Ar valeSSS 58is the name of a VALE switch, while 59.Ar valeSSS:PPP 60is the name of a VALE port of 61.Ar valeSSS . 62.Pp 63When issued without options it lists all the existing switch ports together 64with their internal bridge number and port number. 65.Bl -tag -width Ds 66.It Fl g Ar valeSSS:PPP 67Print the number of receive rings of 68.Ar valeSSS:PPP . 69.It Fl a Ar valeSSS:interface 70Attach 71.Ar interface 72(which must be an existing network interface) to 73.Ar valeSSS 74and detach it from the host stack. 75.It Fl h Ar valeSSS:interface 76Attach 77.Ar interface 78(which must be an existing network interface) to 79.Ar valeSSS 80while keeping it attached to the host stack. 81More precisely, packets coming from 82the host stack and directed to the interface will go through the switch, where 83they can still reach the interface if the switch rules allow it. 84Conversely, packets coming from the interface will go through the switch and, 85if appropriate, will reach the host stack. 86.It Fl d Ar valeSSS:interface 87Detach 88.Ar interface 89from 90.Ar valeSSS . 91.It Fl n Ar interface 92Create a new persistent VALE port with name 93.Ar interface . 94The name must be different from any other network interface 95already present in the system. 96.It Fl r Ar interface 97Destroy the persistent VALE port with name 98.Ar interface . 99.It Fl l Ar valeSSS:PPP 100Show the internal bridge number and port number of the given switch port. 101.It Fl p Ar valeSSS:PPP 102Enable polling mode for 103.Ar valeSSS:PPP . 104In polling mode, a dedicated kernel thread is spawned to handle packets 105received from 106.Ar valeSSS:PPP 107and push them into the switch. 108The kernel thread busy waits on the switch port rather than relying on 109interrupts or notifications. 110Polling mode can only be used on physical NICs attached to a VALE switch. 111.It Fl P Ar valeSSS:PPP 112Disable polling mode for 113.Ar valeSSS:PPP . 114.It Fl C Ar x | Ar x,y | Ar x,y,z | Ar x,y,z,w 115When used in conjunction with 116.Fl n 117it supplies the number of tx and rx rings and slots. 118The full format with four numbers gives, in order, number of tx slots, number 119of rx slots, number of tx rings and number of rx rings. 120The form with three numbers uses 121.Ar z 122for both the number of tx and the number of rx rings. 123The forms with less than two numbers use the default values for the number 124of rings. 125The form with two numbers supplies the numbers of tx and rx slots. 126The form with only one number uses 127.Ar x 128for both the number of tx and the number of rx slots. 129.Pp 130When used in conjunction with 131.Fl p 132only the first three forms are used. 133The first number may be either 0 or 1. 134If 0, then all interface rings will be polled by a single thread, running 135on the core id given by the second number (the third number, if present, 136must be 1). 137If the first number is 1, then the ring identified by the second number will 138be polled by the core with the same id. 139If a third number is given, then this is repeated for as many consecutive 140rings and cores. 141.It Fl m Ar memid 142Used in conjunction with 143.Fl n 144supplies the netmap memory region identifier to use together with the newly 145created persistent VALE port. 146These ports use a private memory region by default. 147Using this option you can let them share memory with other ports. 148Pass 1 as 149.Ar memid 150to use the global memory region already shared by all 151hardware netmap ports. 152.El 153.Sh SEE ALSO 154.Xr netmap 4 , 155.Xr vale 4 156.Sh AUTHORS 157.An -nosplit 158.Nm 159has been written by 160.An Michio Honda 161at NetApp. 162