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