usr.sbin/iovctl/iovctl.conf.5

   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 .\" $FreeBSD$
  27 .\"
  28 .Dd May 29, 2020
  29 .Dt IOVCTL.CONF 5
  30 .Os
  31 .Sh NAME
  32 .Nm iovctl.conf
  33 .Nd IOVCTL configuration file
  34 .Sh DESCRIPTION
  35 The
  36 .Nm
  37 file is the configuration file for the
  38 .Xr iovctl 8
  39 program.
  40 This file specifies configuration parameters for a single Physical Function
  41 .Pq PF
  42 device.
  43 To configure SR-IOV on multiple PF devices, use one configuration file for each
  44 PF.
  45 The locations of all
  46 .Xr iovctl 8
  47 configuration files are specified in
  48 .Xr rc.conf 5 .
  49 .Pp
  50 The
  51 .Nm
  52 file uses UCL format.
  53 UCL syntax is documented at the official UCL website:
  54 .Lk http://github.com/vstakhov/libucl .
  55 .Pp
  56 There are three types of sections in the
  57 .Nm
  58 file.
  59 A section is a key at the top level of the file with a list as its value.
  60 The list may contain the keys specified in the
  61 .Sx OPTIONS
  62 section of this manual page.
  63 Individual PF driver implementations may specify additional device-specific
  64 configuration keys that they will accept.
  65 The order in which sections appear in
  66 .Nm
  67 is ignored.
  68 No two sections may have the same key.
  69 For example, two sections for VF-1 must not be defined.
  70 .Pp
  71 The first section type is the PF section.
  72 This section always has the key "PF"; therefore, only one such section may be
  73 defined.
  74 This section defines configuration parameters that apply to the PF as a whole.
  75 .Pp
  76 The second section type is the VF section.
  77 This section has the key "VF-" followed by a VF index.
  78 VF indices start at 0 and always increment by 1.
  79 Valid VF indices are in the range of 0 to
  80 .Pq num_vfs - 1 .
  81 The VF index must be given as a decimal integer with no leading zeros.
  82 This section defines configuration parameters that apply to a single VF.
  83 .Pp
  84 The third section type is the default section.
  85 This section always has the key "DEFAULT"; therefore, only one such section may
  86 be specified.
  87 This section defines default configuration parameters that apply to all VFs.
  88 All configuration keys that are valid to be applied to a VF are valid in this
  89 section.
  90 An individual VF section may override a default specified in this section by
  91 providing a different value for the configuration parameter.
  92 Note that the default section applies to ALL VFs.
  93 The default section must appear before any VF sections.
  94 The default section may appear before or after the PF section.
  95 .Pp
  96 The following option types are supported:
  97 .Bl -tag -width indent
  98 .It boolean
  99 Accepts a boolean value of true or false.
 100 .It mac-addr
 101 Accepts a unicast MAC address specified as a string of the form
 102 xx:xx:xx:xx:xx:xx, where xx is one or two hexadecimal digits.
 103 .It string
 104 Accepts any string value.
 105 .It uint8_t
 106 Accepts any integer in the range 0 to 255, inclusive.
 107 .It uint16_t
 108 Accepts any integer in the range 0 to 65535, inclusive.
 109 .It uint32_t
 110 Accepts any integer in the range 0 to
 111 .Pq 2**32 - 1 ,
 112 inclusive.
 113 .It uint64_t
 114 Accepts any integer in the range 0 to
 115 .Pq 2**64 - 1 ,
 116 inclusive.
 117 .El
 118 .Sh OPTIONS
 119 The following parameters are accepted by all PF drivers:
 120 .Bl -tag -width indent
 121 .It device Pq string
 122 This parameter specifies the name of the PF device.
 123 This parameter is required to be specified.
 124 .It num_vfs Pq uint16_t
 125 This parameter specifies the number of VF children to create.
 126 This parameter may not be zero.
 127 The maximum value of this parameter is device-specific.
 128 .El
 129 .Pp
 130 The following parameters are accepted by all VFs:
 131 .Bl -tag -width indent
 132 .It passthrough Pq boolean
 133 This parameter controls whether the VF is reserved for the use of the
 134 .Xr bhyve 8
 135 hypervisor as a PCI passthrough device.
 136 If this parameter is set to true, then the VF will be reserved as a PCI
 137 passthrough device and it will not be accessible from the host OS.
 138 The default value of this parameter is false.
 139 .El
 140 .Pp
 141 See the PF driver manual page for configuration parameters specific to
 142 particular hardware.
 143 .Sh EXAMPLES
 144 This sample file will create 3 VFs as children of the ix0 device.
 145 VF-1 and VF-2 are set as
 146 .Xr bhyve 8
 147 passthrough devices through the use of the default section.
 148 VF-0 is not configured as a passthrough device as it explicitly overrides the
 149 default.
 150 VF-0 also sets a device-specific parameter named mac-addr.
 151 .Bd -literal -offset ident
 152 PF {
 153         device : "ix0";
 154         num_vfs : 3;
 155 }
 156
 157 DEFAULT {
 158         passthrough : true;
 159 }
 160
 161 VF-0 {
 162         mac-addr : "02:56:48:7e:d9:f7";
 163         passthrough : false;
 164 }
 165 .Ed
 166 .Sh SEE ALSO
 167 .Xr rc.conf 5 ,
 168 .Xr iovctl 8
 169 .Sh AUTHORS
 170 This manual page was written by
 171 .An Ryan Stone Aq Mt rstone@FreeBSD.org .