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