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