1*1fe9f6f6SRyan Stone.\" 2*1fe9f6f6SRyan Stone.\" Copyright (c) 2014 Sandvine Inc. 3*1fe9f6f6SRyan Stone.\" All rights reserved. 4*1fe9f6f6SRyan Stone.\" 5*1fe9f6f6SRyan Stone.\" Redistribution and use in source and binary forms, with or without 6*1fe9f6f6SRyan Stone.\" modification, are permitted provided that the following conditions 7*1fe9f6f6SRyan Stone.\" are met: 8*1fe9f6f6SRyan Stone.\" 1. Redistributions of source code must retain the above copyright 9*1fe9f6f6SRyan Stone.\" notice, this list of conditions and the following disclaimer. 10*1fe9f6f6SRyan Stone.\" 2. Redistributions in binary form must reproduce the above copyright 11*1fe9f6f6SRyan Stone.\" notice, this list of conditions and the following disclaimer in the 12*1fe9f6f6SRyan Stone.\" documentation and/or other materials provided with the distribution. 13*1fe9f6f6SRyan Stone.\" 14*1fe9f6f6SRyan Stone.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15*1fe9f6f6SRyan Stone.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16*1fe9f6f6SRyan Stone.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17*1fe9f6f6SRyan Stone.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18*1fe9f6f6SRyan Stone.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19*1fe9f6f6SRyan Stone.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20*1fe9f6f6SRyan Stone.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21*1fe9f6f6SRyan Stone.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22*1fe9f6f6SRyan Stone.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23*1fe9f6f6SRyan Stone.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24*1fe9f6f6SRyan Stone.\" SUCH DAMAGE. 25*1fe9f6f6SRyan Stone.\" 26*1fe9f6f6SRyan Stone.\" $FreeBSD$ 27*1fe9f6f6SRyan Stone.\" 28*1fe9f6f6SRyan Stone.Dd May 25, 2014 29*1fe9f6f6SRyan Stone.Dt pci_iov_schema 9 30*1fe9f6f6SRyan Stone.Os 31*1fe9f6f6SRyan Stone.Sh NAME 32*1fe9f6f6SRyan Stone.Nm pci_iov_schema , 33*1fe9f6f6SRyan Stone.Nm pci_iov_schema_alloc_node , 34*1fe9f6f6SRyan Stone.Nm pci_iov_schema_add_bool , 35*1fe9f6f6SRyan Stone.Nm pci_iov_schema_add_string , 36*1fe9f6f6SRyan Stone.Nm pci_iov_schema_add_uint8 , 37*1fe9f6f6SRyan Stone.Nm pci_iov_schema_add_uint16 , 38*1fe9f6f6SRyan Stone.Nm pci_iov_schema_add_uint32 , 39*1fe9f6f6SRyan Stone.Nm pci_iov_schema_add_uint64 , 40*1fe9f6f6SRyan Stone.Nm pci_iov_schema_add_unicast_mac 41*1fe9f6f6SRyan Stone.Nd PCI SR-IOV config schema interface 42*1fe9f6f6SRyan Stone.Sh SYNOPSIS 43*1fe9f6f6SRyan Stone.In machine/stdarg.h 44*1fe9f6f6SRyan Stone.In sys/nv.h 45*1fe9f6f6SRyan Stone.In sys/iov_schema.h 46*1fe9f6f6SRyan Stone.Ft nvlist_t * 47*1fe9f6f6SRyan Stone.Fn pci_iov_schema_alloc_node "void" 48*1fe9f6f6SRyan Stone.Ft void 49*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_bool "nvlist_t *schema" "const char *name" \ 50*1fe9f6f6SRyan Stone"uint32_t flags" "int defaultVal" 51*1fe9f6f6SRyan Stone.Ft void 52*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_string "nvlist_t *schema" "const char *name" \ 53*1fe9f6f6SRyan Stone"uint32_t flags" "const char *defaultVal" 54*1fe9f6f6SRyan Stone.Ft void 55*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint8 "nvlist_t *schema" "const char *name" \ 56*1fe9f6f6SRyan Stone"uint32_t flags" "uint8_t defaultVal" 57*1fe9f6f6SRyan Stone.Ft void 58*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint16 "nvlist_t *schema" "const char *name" \ 59*1fe9f6f6SRyan Stone"uint32_t flags" "uint16_t defaultVal" 60*1fe9f6f6SRyan Stone.Ft void 61*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint32 "nvlist_t *schema" "const char *name" \ 62*1fe9f6f6SRyan Stone"uint32_t flags" "uint32_t defaultVal" 63*1fe9f6f6SRyan Stone.Ft void 64*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint64 "nvlist_t *schema" "const char *name" \ 65*1fe9f6f6SRyan Stone"uint32_t flags" "uint64_t defaultVal" 66*1fe9f6f6SRyan Stone.Ft void 67*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_unicast_mac "nvlist_t *schema" "const char *name" \ 68*1fe9f6f6SRyan Stone"uint32_t flags" "const uint8_t *defaultVal" 69*1fe9f6f6SRyan Stone.Sh DESCRIPTION 70*1fe9f6f6SRyan StoneThe PCI Single-Root I/O Virtualization 71*1fe9f6f6SRyan Stone.Pq SR-IOV 72*1fe9f6f6SRyan Stoneconfiguration schema is a data 73*1fe9f6f6SRyan Stonestructure that describes the device-specific configuration parameters that a PF 74*1fe9f6f6SRyan Stonedriver will accept when SR-IOV is enabled on the PF device. 75*1fe9f6f6SRyan StoneEach PF driver defines two schema instances: the PF schema and the VF schema. 76*1fe9f6f6SRyan StoneThe PF schema describes configuration that applies to the PF device as a whole. 77*1fe9f6f6SRyan StoneThe VF schema describes configuration that applies to an individual VF device. 78*1fe9f6f6SRyan StoneDifferent VF devices may have different configuration applied to them, as long 79*1fe9f6f6SRyan Stoneas the configuration for each VF conforms to the VF schema. 80*1fe9f6f6SRyan Stone.Pp 81*1fe9f6f6SRyan StoneA PF driver builds a configuration schema by first allocating a schema node and 82*1fe9f6f6SRyan Stonethen adding configuration parameter specifications to the schema. 83*1fe9f6f6SRyan StoneThe configuration parameter specification consists of a name and a value type. 84*1fe9f6f6SRyan Stone.Pp 85*1fe9f6f6SRyan StoneConfiguration parameter names are case-insensitive. 86*1fe9f6f6SRyan StoneIt is an error to specify two or more configuration parameters with the same 87*1fe9f6f6SRyan Stonename. 88*1fe9f6f6SRyan StoneIt is also an error to specific a configuration parameter that uses the same 89*1fe9f6f6SRyan Stonename as a configuration parameter used by the SR-IOV infrastructure. 90*1fe9f6f6SRyan StoneSee 91*1fe9f6f6SRyan Stone.Xr iovctl.conf 5 92*1fe9f6f6SRyan Stonefor documentation of all configuration parameters used by the SR-IOV 93*1fe9f6f6SRyan Stoneinfrastructure. 94*1fe9f6f6SRyan Stone.Pp 95*1fe9f6f6SRyan StoneThe parameter type constrains the possible values that the configuration 96*1fe9f6f6SRyan Stoneparameter may take. 97*1fe9f6f6SRyan Stone.Pp 98*1fe9f6f6SRyan StoneA configuration parameter may be specified as a required parameter by setting 99*1fe9f6f6SRyan Stonethe 100*1fe9f6f6SRyan Stone.Dv IOV_SCHEMA_REQUIRED 101*1fe9f6f6SRyan Stoneflag in the 102*1fe9f6f6SRyan Stone.Pa flags 103*1fe9f6f6SRyan Stoneargument. 104*1fe9f6f6SRyan StoneRequired parameters must be specified by the user when SR-IOV is enabled. 105*1fe9f6f6SRyan StoneIf the user does not specify a required parameter, the SR-IOV infrastructure 106*1fe9f6f6SRyan Stonewill abort the request to enable SR-IOV and return an error to the user. 107*1fe9f6f6SRyan Stone.Pp 108*1fe9f6f6SRyan StoneAlternatively, a configuration parameter may be given a default value by 109*1fe9f6f6SRyan Stonesetting the 110*1fe9f6f6SRyan Stone.Dv IOV_SCHEMA_HASDEFAULT 111*1fe9f6f6SRyan Stoneflag in the 112*1fe9f6f6SRyan Stone.Pa flags 113*1fe9f6f6SRyan Stoneargument. 114*1fe9f6f6SRyan StoneIf a configuration parameter has a default value but the user has not specified 115*1fe9f6f6SRyan Stonea value for that parameter, then the SR-IOV infrastructure will apply 116*1fe9f6f6SRyan Stone.Pa defaultVal 117*1fe9f6f6SRyan Stonefor that parameter in the configuration before passing it to the PF driver. 118*1fe9f6f6SRyan StoneIt is an error for the value of the 119*1fe9f6f6SRyan Stone.Pa defaultVal 120*1fe9f6f6SRyan Stoneparameter to not conform to the restrictions of the specified type. 121*1fe9f6f6SRyan StoneIf this flag is not specified then the 122*1fe9f6f6SRyan Stone.Pa defaultVal 123*1fe9f6f6SRyan Stoneargument is ignored. 124*1fe9f6f6SRyan StoneThis flag is not compatible with the 125*1fe9f6f6SRyan Stone.Dv IOV_SCHEMA_REQUIRED 126*1fe9f6f6SRyan Stoneflag; it is an error to specify both on the same parameter. 127*1fe9f6f6SRyan Stone.Pp 128*1fe9f6f6SRyan StoneThe SR-IOV infrastructure guarantees that all configuration parameters that are 129*1fe9f6f6SRyan Stoneeither specified as required or given a default value will be present in the 130*1fe9f6f6SRyan Stoneconfiguration passed to the PF driver. 131*1fe9f6f6SRyan StoneConfiguration parameters that are neither specified as required nor given a 132*1fe9f6f6SRyan Stonedefault value are optional and may or may not be present in the configuration 133*1fe9f6f6SRyan Stonepassed to the PF driver. 134*1fe9f6f6SRyan Stone.Pp 135*1fe9f6f6SRyan StoneIt is highly recommended that a PF driver reserve the use of optional parameters 136*1fe9f6f6SRyan Stonefor configuration that is truly optional. 137*1fe9f6f6SRyan StoneFor example, a Network Interface PF device might have the option to encapsulate 138*1fe9f6f6SRyan Stoneall traffic to and from a VF device in a vlan tag. 139*1fe9f6f6SRyan StoneThe PF driver could expose that option as a "vlan" parameter accepting an 140*1fe9f6f6SRyan Stoneinteger argument specifying the vlan tag. 141*1fe9f6f6SRyan StoneIn this case, it would be appropriate to set the "vlan" parameter as an optional 142*1fe9f6f6SRyan Stoneparameter as it would be legitimate for a VF to be configured to have no vlan 143*1fe9f6f6SRyan Stonetagging enabled at all. 144*1fe9f6f6SRyan Stone.Pp 145*1fe9f6f6SRyan StoneAlternatively, if the PF device had an boolean option that controlled whether 146*1fe9f6f6SRyan Stonethe VF was allowed to change its MAC address, it would not be appropriate to 147*1fe9f6f6SRyan Stoneset this parameter as optional. 148*1fe9f6f6SRyan StoneThe PF driver must either allow the MAC to change or not, so it would be more 149*1fe9f6f6SRyan Stoneappropriate for the PF driver to document the default behaviour by specifying 150*1fe9f6f6SRyan Stonea default value in the schema 151*1fe9f6f6SRyan Stone.Po or potentially force the user to make the choice by setting the parameter 152*1fe9f6f6SRyan Stoneto be required 153*1fe9f6f6SRyan Stone.Pc . 154*1fe9f6f6SRyan Stone.Pp 155*1fe9f6f6SRyan StoneConfiguration parameters that have security implications must default to the 156*1fe9f6f6SRyan Stonemost secure configuration possible. 157*1fe9f6f6SRyan Stone.Pp 158*1fe9f6f6SRyan StoneAll device-specific configuration parameters must be documented in the manual 159*1fe9f6f6SRyan Stonepage for the PF driver, or in a separate manual page that is cross-referenced 160*1fe9f6f6SRyan Stonefrom the main driver manual page. 161*1fe9f6f6SRyan Stone.Pp 162*1fe9f6f6SRyan StoneIt is not necessary for a PF driver to check for failure from any of these 163*1fe9f6f6SRyan Stonefunctions. 164*1fe9f6f6SRyan StoneIf an error occurs, it is flagged in the schema. 165*1fe9f6f6SRyan StoneThe 166*1fe9f6f6SRyan Stone.Xr pci_iov_attach 9 167*1fe9f6f6SRyan Stonefunction checks for this error and will fail to initialize SR-IOV on the PF 168*1fe9f6f6SRyan Stonedevice if an error is set in the schema. 169*1fe9f6f6SRyan StoneIf this occurs, it is recommended that the PF driver still succeed in attaching 170*1fe9f6f6SRyan Stoneand run with SR-IOV disabled on the device. 171*1fe9f6f6SRyan Stone.Pp 172*1fe9f6f6SRyan StoneThe 173*1fe9f6f6SRyan Stone.Fn pci_iov_schema_alloc_node 174*1fe9f6f6SRyan Stonefunction is used to allocate an empty configuration schema. 175*1fe9f6f6SRyan StoneIt is not necessary to check for failure from this function. 176*1fe9f6f6SRyan StoneThe SR-IOV infrastructure will gracefully handle failure to allocate a schema 177*1fe9f6f6SRyan Stoneand will simply not enable SR-IOV on the PF device. 178*1fe9f6f6SRyan Stone.Pp 179*1fe9f6f6SRyan StoneThe 180*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_bool 181*1fe9f6f6SRyan Stonefunction is used to specify a configuration parameter in the given schema with 182*1fe9f6f6SRyan Stonethe name 183*1fe9f6f6SRyan Stone.Pa name 184*1fe9f6f6SRyan Stoneand having a boolean type. 185*1fe9f6f6SRyan StoneBoolean values can only take the value true or false (1 or 0, respectively). 186*1fe9f6f6SRyan Stone.Pp 187*1fe9f6f6SRyan StoneThe 188*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_string 189*1fe9f6f6SRyan Stonefunction is used to specify a configuration parameter in the given schema with 190*1fe9f6f6SRyan Stonethe name 191*1fe9f6f6SRyan Stone.Pa name 192*1fe9f6f6SRyan Stoneand having a string type. 193*1fe9f6f6SRyan StoneString values are standard C strings. 194*1fe9f6f6SRyan Stone.Pp 195*1fe9f6f6SRyan StoneThe 196*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint8 197*1fe9f6f6SRyan Stonefunction is used to specify a configuration parameter in the given schema with 198*1fe9f6f6SRyan Stonethe name 199*1fe9f6f6SRyan Stone.Pa name 200*1fe9f6f6SRyan Stoneand having a 201*1fe9f6f6SRyan Stone.Vt uint8_t 202*1fe9f6f6SRyan Stonetype. 203*1fe9f6f6SRyan StoneValues of type 204*1fe9f6f6SRyan Stone.Vt uint8_t 205*1fe9f6f6SRyan Stoneare unsigned integers in the range 0 to 255, inclusive. 206*1fe9f6f6SRyan Stone.Pp 207*1fe9f6f6SRyan StoneThe 208*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint16 209*1fe9f6f6SRyan Stonefunction is used to specify a configuration parameter in the given schema with 210*1fe9f6f6SRyan Stonethe name 211*1fe9f6f6SRyan Stone.Pa name 212*1fe9f6f6SRyan Stoneand having a 213*1fe9f6f6SRyan Stone.Vt uint16_t 214*1fe9f6f6SRyan Stonetype. 215*1fe9f6f6SRyan StoneValues of type 216*1fe9f6f6SRyan Stone.Vt uint16_t 217*1fe9f6f6SRyan Stoneare unsigned integers in the range 0 to 65535, inclusive. 218*1fe9f6f6SRyan Stone.Pp 219*1fe9f6f6SRyan StoneThe 220*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint32 221*1fe9f6f6SRyan Stonefunction is used to specify a configuration parameter in the given schema with 222*1fe9f6f6SRyan Stonethe name 223*1fe9f6f6SRyan Stone.Pa name 224*1fe9f6f6SRyan Stoneand having a 225*1fe9f6f6SRyan Stone.Vt uint32_t 226*1fe9f6f6SRyan Stonetype. 227*1fe9f6f6SRyan StoneValues of type 228*1fe9f6f6SRyan Stone.Vt uint32_t 229*1fe9f6f6SRyan Stoneare unsigned integers in the range 0 to 230*1fe9f6f6SRyan Stone.Po 2**32 - 1 Pc , 231*1fe9f6f6SRyan Stoneinclusive. 232*1fe9f6f6SRyan Stone.Pp 233*1fe9f6f6SRyan StoneThe 234*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_uint64 235*1fe9f6f6SRyan Stonefunction is used to specify a configuration parameter in the given schema with 236*1fe9f6f6SRyan Stonethe name 237*1fe9f6f6SRyan Stone.Pa name 238*1fe9f6f6SRyan Stoneand having a 239*1fe9f6f6SRyan Stone.Vt uint64_t 240*1fe9f6f6SRyan Stonetype. 241*1fe9f6f6SRyan StoneValues of type 242*1fe9f6f6SRyan Stone.Vt uint64_t 243*1fe9f6f6SRyan Stoneare unsigned integers in the range 0 to 244*1fe9f6f6SRyan Stone.Po 2**64 - 1 Pc , 245*1fe9f6f6SRyan Stoneinclusive. 246*1fe9f6f6SRyan Stone.Pp 247*1fe9f6f6SRyan StoneThe 248*1fe9f6f6SRyan Stone.Fn pci_iov_schema_add_unicast_mac 249*1fe9f6f6SRyan Stonefunction is used to specify a configuration parameter in the given schema with 250*1fe9f6f6SRyan Stonethe name 251*1fe9f6f6SRyan Stone.Pa name 252*1fe9f6f6SRyan Stoneand having a unicast-mac type. 253*1fe9f6f6SRyan StoneValues of type unicast-mac are binary values exactly 6 bytes long. 254*1fe9f6f6SRyan StoneThe MAC address is guaranteed to not be a multicast or broadcast address. 255*1fe9f6f6SRyan Stone.Sh RETURN VALUES 256*1fe9f6f6SRyan StoneThe 257*1fe9f6f6SRyan Stone.Fn pci_iov_schema_alloc_node 258*1fe9f6f6SRyan Stonefunction returns a pointer to the allocated schema, or NULL if a failure occurs. 259*1fe9f6f6SRyan Stone.Sh SEE ALSO 260*1fe9f6f6SRyan Stone.Xr pci 9 , 261*1fe9f6f6SRyan Stone.Xr PCI_ADD_VF 9 , 262*1fe9f6f6SRyan Stone.Xr PCI_INIT_IOV 9 263*1fe9f6f6SRyan Stone.Sh AUTHORS 264*1fe9f6f6SRyan StoneThis manual page was written by 265*1fe9f6f6SRyan Stone.An Ryan Stone Aq rstone@FreeBSD.org . 266