share/man/man9/pci_iov_schema.9

   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 July 8, 2015
  29 .Dt PCI_IOV_SCHEMA 9
  30 .Os
  31 .Sh NAME
  32 .Nm pci_iov_schema ,
  33 .Nm pci_iov_schema_alloc_node ,
  34 .Nm pci_iov_schema_add_bool ,
  35 .Nm pci_iov_schema_add_string ,
  36 .Nm pci_iov_schema_add_uint8 ,
  37 .Nm pci_iov_schema_add_uint16 ,
  38 .Nm pci_iov_schema_add_uint32 ,
  39 .Nm pci_iov_schema_add_uint64 ,
  40 .Nm pci_iov_schema_add_unicast_mac
  41 .Nd PCI SR-IOV config schema interface
  42 .Sh SYNOPSIS
  43 .In machine/stdarg.h
  44 .In sys/nv.h
  45 .In sys/iov_schema.h
  46 .Ft nvlist_t *
  47 .Fn pci_iov_schema_alloc_node "void"
  48 .Ft void
  49 .Fn pci_iov_schema_add_bool "nvlist_t *schema" "const char *name" \
  50 "uint32_t flags" "int defaultVal"
  51 .Ft void
  52 .Fn pci_iov_schema_add_string "nvlist_t *schema" "const char *name" \
  53 "uint32_t flags" "const char *defaultVal"
  54 .Ft void
  55 .Fn pci_iov_schema_add_uint8 "nvlist_t *schema" "const char *name" \
  56 "uint32_t flags" "uint8_t defaultVal"
  57 .Ft void
  58 .Fn pci_iov_schema_add_uint16 "nvlist_t *schema" "const char *name" \
  59 "uint32_t flags" "uint16_t defaultVal"
  60 .Ft void
  61 .Fn pci_iov_schema_add_uint32 "nvlist_t *schema" "const char *name" \
  62 "uint32_t flags" "uint32_t defaultVal"
  63 .Ft void
  64 .Fn pci_iov_schema_add_uint64 "nvlist_t *schema" "const char *name" \
  65 "uint32_t flags" "uint64_t defaultVal"
  66 .Ft void
  67 .Fn pci_iov_schema_add_unicast_mac "nvlist_t *schema" "const char *name" \
  68 "uint32_t flags" "const uint8_t *defaultVal"
  69 .Sh DESCRIPTION
  70 The PCI Single-Root I/O Virtualization
  71 .Pq SR-IOV
  72 configuration schema is a data
  73 structure that describes the device-specific configuration parameters that a PF
  74 driver will accept when SR-IOV is enabled on the PF device.
  75 Each PF driver defines two schema instances: the PF schema and the VF schema.
  76 The PF schema describes configuration that applies to the PF device as a whole.
  77 The VF schema describes configuration that applies to an individual VF device.
  78 Different VF devices may have different configuration applied to them, as long
  79 as the configuration for each VF conforms to the VF schema.
  80 .Pp
  81 A PF driver builds a configuration schema by first allocating a schema node and
  82 then adding configuration parameter specifications to the schema.
  83 The configuration parameter specification consists of a name and a value type.
  84 .Pp
  85 Configuration parameter names are case-insensitive.
  86 It is an error to specify two or more configuration parameters with the same
  87 name.
  88 It is also an error to specific a configuration parameter that uses the same
  89 name as a configuration parameter used by the SR-IOV infrastructure.
  90 See
  91 .Xr iovctl.conf 5
  92 for documentation of all configuration parameters used by the SR-IOV
  93 infrastructure.
  94 .Pp
  95 The parameter type constrains the possible values that the configuration
  96 parameter may take.
  97 .Pp
  98 A configuration parameter may be specified as a required parameter by setting
  99 the
 100 .Dv IOV_SCHEMA_REQUIRED
 101 flag in the
 102 .Pa flags
 103 argument.
 104 Required parameters must be specified by the user when SR-IOV is enabled.
 105 If the user does not specify a required parameter, the SR-IOV infrastructure
 106 will abort the request to enable SR-IOV and return an error to the user.
 107 .Pp
 108 Alternatively, a configuration parameter may be given a default value by
 109 setting the
 110 .Dv IOV_SCHEMA_HASDEFAULT
 111 flag in the
 112 .Pa flags
 113 argument.
 114 If a configuration parameter has a default value but the user has not specified
 115 a value for that parameter, then the SR-IOV infrastructure will apply
 116 .Pa defaultVal
 117 for that parameter in the configuration before passing it to the PF driver.
 118 It is an error for the value of the
 119 .Pa defaultVal
 120 parameter to not conform to the restrictions of the specified type.
 121 If this flag is not specified then the
 122 .Pa defaultVal
 123 argument is ignored.
 124 This flag is not compatible with the
 125 .Dv IOV_SCHEMA_REQUIRED
 126 flag; it is an error to specify both on the same parameter.
 127 .Pp
 128 The SR-IOV infrastructure guarantees that all configuration parameters that are
 129 either specified as required or given a default value will be present in the
 130 configuration passed to the PF driver.
 131 Configuration parameters that are neither specified as required nor given a
 132 default value are optional and may or may not be present in the configuration
 133 passed to the PF driver.
 134 .Pp
 135 It is highly recommended that a PF driver reserve the use of optional parameters
 136 for configuration that is truly optional.
 137 For example, a Network Interface PF device might have the option to encapsulate
 138 all traffic to and from a VF device in a vlan tag.
 139 The PF driver could expose that option as a "vlan" parameter accepting an
 140 integer argument specifying the vlan tag.
 141 In this case, it would be appropriate to set the "vlan" parameter as an optional
 142 parameter as it would be legitimate for a VF to be configured to have no vlan
 143 tagging enabled at all.
 144 .Pp
 145 Alternatively, if the PF device had an boolean option that controlled whether
 146 the VF was allowed to change its MAC address, it would not be appropriate to
 147 set this parameter as optional.
 148 The PF driver must either allow the MAC to change or not, so it would be more
 149 appropriate for the PF driver to document the default behaviour by specifying
 150 a default value in the schema
 151 .Po or potentially force the user to make the choice by setting the parameter
 152 to be required
 153 .Pc .
 154 .Pp
 155 Configuration parameters that have security implications must default to the
 156 most secure configuration possible.
 157 .Pp
 158 All device-specific configuration parameters must be documented in the manual
 159 page for the PF driver, or in a separate manual page that is cross-referenced
 160 from the main driver manual page.
 161 .Pp
 162 It is not necessary for a PF driver to check for failure from any of these
 163 functions.
 164 If an error occurs, it is flagged in the schema.
 165 The
 166 .Xr pci_iov_attach 9
 167 function checks for this error and will fail to initialize SR-IOV on the PF
 168 device if an error is set in the schema.
 169 If this occurs, it is recommended that the PF driver still succeed in attaching
 170 and run with SR-IOV disabled on the device.
 171 .Pp
 172 The
 173 .Fn pci_iov_schema_alloc_node
 174 function is used to allocate an empty configuration schema.
 175 It is not necessary to check for failure from this function.
 176 The SR-IOV infrastructure will gracefully handle failure to allocate a schema
 177 and will simply not enable SR-IOV on the PF device.
 178 .Pp
 179 The
 180 .Fn pci_iov_schema_add_bool
 181 function is used to specify a configuration parameter in the given schema with
 182 the name
 183 .Pa name
 184 and having a boolean type.
 185 Boolean values can only take the value true or false (1 or 0, respectively).
 186 .Pp
 187 The
 188 .Fn pci_iov_schema_add_string
 189 function is used to specify a configuration parameter in the given schema with
 190 the name
 191 .Pa name
 192 and having a string type.
 193 String values are standard C strings.
 194 .Pp
 195 The
 196 .Fn pci_iov_schema_add_uint8
 197 function is used to specify a configuration parameter in the given schema with
 198 the name
 199 .Pa name
 200 and having a
 201 .Vt uint8_t
 202 type.
 203 Values of type
 204 .Vt uint8_t
 205 are unsigned integers in the range 0 to 255, inclusive.
 206 .Pp
 207 The
 208 .Fn pci_iov_schema_add_uint16
 209 function is used to specify a configuration parameter in the given schema with
 210 the name
 211 .Pa name
 212 and having a
 213 .Vt uint16_t
 214 type.
 215 Values of type
 216 .Vt uint16_t
 217 are unsigned integers in the range 0 to 65535, inclusive.
 218 .Pp
 219 The
 220 .Fn pci_iov_schema_add_uint32
 221 function is used to specify a configuration parameter in the given schema with
 222 the name
 223 .Pa name
 224 and having a
 225 .Vt uint32_t
 226 type.
 227 Values of type
 228 .Vt uint32_t
 229 are unsigned integers in the range 0 to
 230 .Pq 2**32 - 1 ,
 231 inclusive.
 232 .Pp
 233 The
 234 .Fn pci_iov_schema_add_uint64
 235 function is used to specify a configuration parameter in the given schema with
 236 the name
 237 .Pa name
 238 and having a
 239 .Vt uint64_t
 240 type.
 241 Values of type
 242 .Vt uint64_t
 243 are unsigned integers in the range 0 to
 244 .Pq 2**64 - 1 ,
 245 inclusive.
 246 .Pp
 247 The
 248 .Fn pci_iov_schema_add_unicast_mac
 249 function is used to specify a configuration parameter in the given schema with
 250 the name
 251 .Pa name
 252 and having a unicast-mac type.
 253 Values of type unicast-mac are binary values exactly 6 bytes long.
 254 The MAC address is guaranteed to not be a multicast or broadcast address.
 255 .Sh RETURN VALUES
 256 The
 257 .Fn pci_iov_schema_alloc_node
 258 function returns a pointer to the allocated schema, or NULL if a failure occurs.
 259 .Sh SEE ALSO
 260 .Xr pci 9 ,
 261 .Xr PCI_IOV_ADD_VF 9 ,
 262 .Xr PCI_IOV_INIT 9
 263 .Sh AUTHORS
 264 This manual page was written by
 265 .An Ryan Stone Aq rstone@FreeBSD.org .