2 .\" Copyright (c) 2014 Sandvine Inc.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
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
47 .Fn pci_iov_schema_alloc_node "void"
49 .Fn pci_iov_schema_add_bool "nvlist_t *schema" "const char *name" \
50 "uint32_t flags" "int defaultVal"
52 .Fn pci_iov_schema_add_string "nvlist_t *schema" "const char *name" \
53 "uint32_t flags" "const char *defaultVal"
55 .Fn pci_iov_schema_add_uint8 "nvlist_t *schema" "const char *name" \
56 "uint32_t flags" "uint8_t defaultVal"
58 .Fn pci_iov_schema_add_uint16 "nvlist_t *schema" "const char *name" \
59 "uint32_t flags" "uint16_t defaultVal"
61 .Fn pci_iov_schema_add_uint32 "nvlist_t *schema" "const char *name" \
62 "uint32_t flags" "uint32_t defaultVal"
64 .Fn pci_iov_schema_add_uint64 "nvlist_t *schema" "const char *name" \
65 "uint32_t flags" "uint64_t defaultVal"
67 .Fn pci_iov_schema_add_unicast_mac "nvlist_t *schema" "const char *name" \
68 "uint32_t flags" "const uint8_t *defaultVal"
70 The PCI Single-Root I/O Virtualization
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.
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.
85 Configuration parameter names are case-insensitive.
86 It is an error to specify two or more configuration parameters with the same
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.
92 for documentation of all configuration parameters used by the SR-IOV
95 The parameter type constrains the possible values that the configuration
98 A configuration parameter may be specified as a required parameter by setting
100 .Dv IOV_SCHEMA_REQUIRED
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.
108 Alternatively, a configuration parameter may be given a default value by
110 .Dv IOV_SCHEMA_HASDEFAULT
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
117 for that parameter in the configuration before passing it to the PF driver.
118 It is an error for the value of the
120 parameter to not conform to the restrictions of the specified type.
121 If this flag is not specified then the
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.
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.
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.
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
155 Configuration parameters that have security implications must default to the
156 most secure configuration possible.
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.
162 It is not necessary for a PF driver to check for failure from any of these
164 If an error occurs, it is flagged in the schema.
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.
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.
180 .Fn pci_iov_schema_add_bool
181 function is used to specify a configuration parameter in the given schema with
184 and having a boolean type.
185 Boolean values can only take the value true or false (1 or 0, respectively).
188 .Fn pci_iov_schema_add_string
189 function is used to specify a configuration parameter in the given schema with
192 and having a string type.
193 String values are standard C strings.
196 .Fn pci_iov_schema_add_uint8
197 function is used to specify a configuration parameter in the given schema with
205 are unsigned integers in the range 0 to 255, inclusive.
208 .Fn pci_iov_schema_add_uint16
209 function is used to specify a configuration parameter in the given schema with
217 are unsigned integers in the range 0 to 65535, inclusive.
220 .Fn pci_iov_schema_add_uint32
221 function is used to specify a configuration parameter in the given schema with
229 are unsigned integers in the range 0 to
234 .Fn pci_iov_schema_add_uint64
235 function is used to specify a configuration parameter in the given schema with
243 are unsigned integers in the range 0 to
248 .Fn pci_iov_schema_add_unicast_mac
249 function is used to specify a configuration parameter in the given schema with
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.
257 .Fn pci_iov_schema_alloc_node
258 function returns a pointer to the allocated schema, or NULL if a failure occurs.
261 .Xr PCI_IOV_ADD_VF 9 ,
264 This manual page was written by
265 .An Ryan Stone Aq rstone@FreeBSD.org .