xref: /freebsd/usr.sbin/iovctl/iovctl.conf.5 (revision 7fdf597e96a02165cfe22ff357b857d5fa15ed8a)
1.\"
2.\" Copyright (c) 2014 Sandvine Inc.
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.Dd May 30, 2024
27.Dt IOVCTL.CONF 5
28.Os
29.Sh NAME
30.Nm iovctl.conf
31.Nd IOVCTL configuration file
32.Sh DESCRIPTION
33The
34.Nm
35file is the configuration file for the
36.Xr iovctl 8
37program.
38This file specifies configuration parameters for a single Physical Function
39.Pq PF
40device.
41To configure SR-IOV on multiple PF devices, use one configuration file for each
42PF.
43The locations of all
44.Xr iovctl 8
45configuration files are specified in
46.Xr rc.conf 5 .
47.Pp
48The
49.Nm
50file uses UCL format.
51UCL syntax is documented at the official UCL website:
52.Lk http://github.com/vstakhov/libucl .
53.Pp
54There are three types of sections in the
55.Nm
56file.
57A section is a key at the top level of the file with a list as its value.
58The list may contain the keys specified in the
59.Sx OPTIONS
60section of this manual page.
61Individual PF driver implementations may specify additional device-specific
62configuration keys that they will accept.
63The order in which sections appear in
64.Nm
65is ignored.
66No two sections may have the same key.
67For example, two sections for VF-1 must not be defined.
68.Pp
69The first section type is the PF section.
70This section always has the key "PF"; therefore, only one such section may be
71defined.
72This section defines configuration parameters that apply to the PF as a whole.
73.Pp
74The second section type is the VF section.
75This section has the key "VF-" followed by a VF index.
76VF indices start at 0 and always increment by 1.
77Valid VF indices are in the range of 0 to
78.Pq num_vfs - 1 .
79The VF index must be given as a decimal integer with no leading zeros.
80This section defines configuration parameters that apply to a single VF.
81.Pp
82The third section type is the default section.
83This section always has the key "DEFAULT"; therefore, only one such section may
84be specified.
85This section defines default configuration parameters that apply to all VFs.
86All configuration keys that are valid to be applied to a VF are valid in this
87section.
88An individual VF section may override a default specified in this section by
89providing a different value for the configuration parameter.
90Note that the default section applies to ALL VFs.
91The default section must appear before any VF sections.
92The default section may appear before or after the PF section.
93.Pp
94The following option types are supported:
95.Bl -tag -width indent
96.It boolean
97Accepts a boolean value of true or false.
98.It vlan
99Accepts a VLAN ID, or "trunk" to allow any VLAN ID.
100.It mac-addr
101Accepts a unicast MAC address specified as a string of the form
102xx:xx:xx:xx:xx:xx, where xx is one or two hexadecimal digits.
103.It string
104Accepts any string value.
105.It uint8_t
106Accepts any integer in the range 0 to 255, inclusive.
107.It uint16_t
108Accepts any integer in the range 0 to 65535, inclusive.
109.It uint32_t
110Accepts any integer in the range 0 to
111.Pq 2**32 - 1 ,
112inclusive.
113.It uint64_t
114Accepts any integer in the range 0 to
115.Pq 2**64 - 1 ,
116inclusive.
117.El
118.Sh OPTIONS
119The following parameters are accepted by all PF drivers:
120.Bl -tag -width indent
121.It device Pq string
122This parameter specifies the name of the PF device.
123This parameter is required to be specified.
124.It num_vfs Pq uint16_t
125This parameter specifies the number of VF children to create.
126This parameter may not be zero.
127The maximum value of this parameter is device-specific.
128.El
129.Pp
130The following parameters are accepted by all VFs:
131.Bl -tag -width indent
132.It passthrough Pq boolean
133This parameter controls whether the VF is reserved for the use of the
134.Xr bhyve 8
135hypervisor as a PCI passthrough device.
136If this parameter is set to true, then the VF will be reserved as a PCI
137passthrough device and it will not be accessible from the host OS.
138The default value of this parameter is false.
139.El
140.Pp
141See the PF driver manual page for configuration parameters specific to
142particular hardware.
143.Sh EXAMPLES
144This sample file will create 3 VFs as children of the ix0 device.
145VF-1 and VF-2 are set as
146.Xr bhyve 8
147passthrough devices through the use of the default section.
148VF-0 is not configured as a passthrough device as it explicitly overrides the
149default.
150VF-0 also sets a device-specific parameter named mac-addr.
151.Bd -literal -offset ident
152PF {
153	device : "ix0";
154	num_vfs : 3;
155}
156
157DEFAULT {
158	passthrough : true;
159}
160
161VF-0 {
162	mac-addr : "02:56:48:7e:d9:f7";
163	passthrough : false;
164	vlan: 1;
165}
166.Ed
167.Sh SEE ALSO
168.Xr rc.conf 5 ,
169.Xr iovctl 8
170.Sh AUTHORS
171This manual page was written by
172.An Ryan Stone Aq Mt rstone@FreeBSD.org .
173