2 * Copyright (c) 2013-2015 Sandvine Inc.
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
32 #include <sys/ioccom.h>
34 #define PF_CONFIG_NAME "PF"
35 #define VF_SCHEMA_NAME "VF"
37 #define VF_PREFIX "VF-"
38 #define VF_PREFIX_LEN 3
39 #define VF_NUM_LEN 5 /* The maximum VF num is 65535. */
40 #define VF_MAX_NAME (VF_PREFIX_LEN + VF_NUM_LEN + 1)
42 #define DRIVER_CONFIG_NAME "DRIVER"
43 #define IOV_CONFIG_NAME "IOV"
45 #define TYPE_SCHEMA_NAME "TYPE"
46 #define DEFAULT_SCHEMA_NAME "DEFAULT"
47 #define REQUIRED_SCHEMA_NAME "REQUIRED"
50 * Because each PF device is expected to expose a unique set of possible
51 * configurations, the SR-IOV infrastructure dynamically queries the PF
52 * driver for its capabilities. These capabilities are exposed to userland
53 * with a configuration schema. The schema is exported from the kernel as a
54 * packed nvlist. See nv(3) for the details of the nvlist API. The expected
55 * format of the nvlist is:
58 * 1) All keys are case-insensitive.
59 * 2) No keys that are not specified below may exist at any level of the
61 * 3) All keys are mandatory unless explicitly documented as optional. If a
62 * key is mandatory then the associated value is also mandatory.
63 * 4) Order of keys is irrelevant.
66 * 1) There must be a top-level key with the name PF_CONFIG_NAME. The value
67 * associated with this key is a nvlist that follows the device schema
68 * node format. The parameters in this node specify the configuration
69 * parameters that may be applied to a PF.
70 * 2) There must be a top-level key with the name VF_SCHEMA_NAME. The value
71 * associated with this key is a nvlist that follows the device schema
72 * node format. The parameters in this node specify the configuration
73 * parameters that may be applied to a VF.
76 * 1) There must be a key with the name DRIVER_CONFIG_NAME. The value
77 * associated with this key is a nvlist that follows the device/subsystem
78 * schema node format. The parameters in this node specify the
79 * configuration parameters that are specific to a particular device
81 * 2) There must be a key with the name IOV_CONFIG_NAME. The value associated
82 * with this key is an nvlist that follows the device/subsystem schema node
83 * format. The parameters in this node specify the configuration
84 * parameters that are applied by the SR-IOV infrastructure.
86 * DEVICE/SUBSYSTEM SCHEMA NODE
87 * 1) All keys in the device/subsystem schema node are optional.
88 * 2) Each key specifies the name of a valid configuration parameter that may
89 * be applied to the device/subsystem combination specified by this node.
90 * The value associated with the key specifies the format of valid
91 * configuration values, and must be a nvlist in parameter schema node
94 * PARAMETER SCHEMA NODE
95 * 1) The parameter schema node must contain a key with the name
96 * TYPE_SCHEMA_NAME. The value associated with this key must be a string.
97 * This string specifies the type of value that the parameter specified by
98 * this node must take. The string must have one of the following values:
99 * - "bool" - The configuration value must be a boolean.
100 * - "mac-addr" - The configuration value must be a binary value. In
101 * addition, the value must be exactly 6 bytes long and
102 * the value must not be a multicast or broadcast mac.
103 * - "uint8_t" - The configuration value must be a integer value in
104 * the range [0, UINT8_MAX].
105 * - "uint16_t" - The configuration value must be a integer value in
106 * the range [0, UINT16_MAX].
107 * - "uint32_t" - The configuration value must be a integer value in
108 * the range [0, UINT32_MAX].
109 * - "uint64_t" - The configuration value must be a integer value in
110 * the range [0, UINT64_MAX].
111 * 2) The parameter schema may contain a key with the name
112 * REQUIRED_SCHEMA_NAME. This key is optional. If this key is present, the
113 * value associated with it must have a boolean type. If the value is true,
114 * then the parameter specified by this schema is a required parameter. All
115 * valid configurations must include all required parameters.
116 * 3) The parameter schema may contain a key with the name DEFAULT_SCHEMA_NAME.
117 * This key is optional. This key must not be present if the parameter
118 * specified by this schema is required. If this key is present, the value
119 * associated with the parent key must follow all restrictions specified by
120 * the type specified by this schema. If a configuration does not supply a
121 * value for the parameter specified by this schema, then the kernel will
122 * apply the value associated with this key in its place.
124 * The following is an example of a valid schema, as printed by nvlist_dump.
125 * Keys are printed followed by the type of the value in parantheses. The
126 * value is displayed following a colon. The indentation level reflects the
127 * level of nesting of nvlists. String values are displayed between []
128 * brackets. Binary values are shown with the length of the binary value (in
129 * bytes) followed by the actual binary values.
134 * type (STRING): [uint16_t]
135 * required (BOOL): TRUE
137 * type (STRING): [string]
138 * required (BOOL): TRUE
142 * passthrough (NVLIST):
143 * type (STRING): [bool]
144 * default (BOOL): FALSE
147 * type (STRING): [mac-addr]
148 * default (BINARY): 6 000000000000
150 * type (STRING): [uint16_t]
151 * spoof-check (NVLIST):
152 * type (STRING): [bool]
153 * default (BOOL): TRUE
154 * allow-set-mac (NVLIST):
155 * type (STRING): [bool]
156 * default (BOOL): FALSE
158 struct pci_iov_schema
166 * SR-IOV configuration is passed to the kernel as a packed nvlist. See nv(3)
167 * for the details of the nvlist API. The expected format of the nvlist is:
170 * 1) All keys are case-insensitive.
171 * 2) No keys that are not specified below may exist at any level of the
173 * 3) Unless otherwise specified, all keys are optional. It should go without
174 * saying a key being mandatory is transitive: that is, if a key is
175 * specified to contain a sub-nodes that contains a mandatory key, then
176 * the outer key is implicitly mandatory. If a key is mandatory then the
177 * associated value is also mandatory.
178 * 4) Order of keys is irrelevant.
180 * TOP LEVEL OF CONFIG NVLIST
181 * 1) All keys specified in this section are mandatory.
182 * 2) There must be a top-level key with the name PF_CONFIG_NAME. The value
183 * associated is an nvlist that follows the "device node" format. The
184 * parameters in this node specify parameters that apply to the PF.
185 * 3) For every VF being configured (this is set via the "num_vfs" parameter
186 * in the PF section), there must be a top-level key whose name is VF_PREFIX
187 * immediately followed by the index of the VF as a decimal integer. For
188 * example, this would be VF-0 for the first VF. VFs are numbered starting
189 * from 0. The value associated with this key follows the "device node"
190 * format. The parameters in this node specify configuration that applies
191 * to the VF specified in the key. Leading zeros are not permitted in VF
192 * index. Configuration for the second VF must be specified in a node with
193 * the key VF-1. VF-01 is not a valid key.
196 * 1) All keys specified in this section are mandatory.
197 * 2) The device node must contain a key with the name DRIVER_CONFIG_NAME. The
198 * value associated with this key is an nvlist following the subsystem node
199 * format. The parameters in this key specify configuration that is specific
200 * to a particular device driver.
201 * 3) The device node must contain a key with the name IOV_CONFIG_NAME. The
202 * value associated with this key is an nvlist following the subsystem node
203 * format. The parameters in this key specify configuration that is consumed
204 * by the SR-IOV infrastructure.
207 * 1) A subsystem node specifies configuration parameters that apply to a
208 * particular subsystem (driver or infrastructure) of a particular device
209 * (PF or individual VF).
210 * Note: We will refer to the section of the configuration schema that
211 * specifies the parameters for this subsystem and device
212 * configuration as the device/subystem schema.
213 * 2) The subsystem node must contain only keys that correspond to parameters
214 * that are specified in the device/subsystem schema.
215 * 3) Every parameter specified as required in the device/subsystem schema is
216 * a mandatory key in the subsystem node.
217 * Note: All parameters that are not required in device/subsystem schema are
218 * optional keys. In particular, any parameter specified to have a
219 * default value in the device/subsystem schema is optional. The
220 * kernel is responsible for applying default values.
221 * 4) The value of every parameter in the device node must conform to the
222 * restrictions of the type specified for that parameter in the device/
225 * The following is an example of a valid configuration, when validated against
226 * the schema example given above.
231 * num_vfs (NUMBER): 3 (3) (0x3)
232 * device (STRING): [ix0]
235 * vlan (NUMBER): 1000 (1000) (0x3e8)
237 * passthrough (BOOL): TRUE
243 * mac-addr (BINARY): 6 020102030405
252 #define IOV_CONFIG _IOW('p', 10, struct pci_iov_arg)
253 #define IOV_DELETE _IO('p', 11)
254 #define IOV_GET_SCHEMA _IOWR('p', 12, struct pci_iov_schema)