xref: /freebsd/share/man/man9/pci_iov_schema.9 (revision 1fe9f6f6a7459d95f756b03ea6b764906465c83e)
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