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