1/*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (c) 2013-2015 Sandvine Inc.
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 * 1. Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * 2. Redistributions in binary form must reproduce the above copyright
13 * notice, this list of conditions and the following disclaimer in the
14 * documentation and/or other materials provided with the distribution.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 * SUCH DAMAGE.
27 */
28
29#ifndef _SYS_IOV_H_
30#define _SYS_IOV_H_
31
32#include <sys/ioccom.h>
33
34#define PF_CONFIG_NAME "PF"
35#define VF_SCHEMA_NAME "VF"
36
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)
41
42#define DRIVER_CONFIG_NAME "DRIVER"
43#define IOV_CONFIG_NAME "IOV"
44
45#define TYPE_SCHEMA_NAME "TYPE"
46#define DEFAULT_SCHEMA_NAME "DEFAULT"
47#define REQUIRED_SCHEMA_NAME "REQUIRED"
48
49#define VF_VLAN_TRUNK 4096
50
51/*
52 * Because each PF device is expected to expose a unique set of possible
53 * configurations, the SR-IOV infrastructure dynamically queries the PF
54 * driver for its capabilities. These capabilities are exposed to userland
55 * with a configuration schema. The schema is exported from the kernel as a
56 * packed nvlist. See nv(3) for the details of the nvlist API. The expected
57 * format of the nvlist is:
58 *
59 * BASIC RULES
60 * 1) All keys are case-insensitive.
61 * 2) No keys that are not specified below may exist at any level of the
62 * schema.
63 * 3) All keys are mandatory unless explicitly documented as optional. If a
64 * key is mandatory then the associated value is also mandatory.
65 * 4) Order of keys is irrelevant.
66 *
67 * TOP LEVEL
68 * 1) There must be a top-level key with the name PF_CONFIG_NAME. The value
69 * associated with this key is a nvlist that follows the device schema
70 * node format. The parameters in this node specify the configuration
71 * parameters that may be applied to a PF.
72 * 2) There must be a top-level key with the name VF_SCHEMA_NAME. The value
73 * associated with this key is a nvlist that follows the device schema
74 * node format. The parameters in this node specify the configuration
75 * parameters that may be applied to a VF.
76 *
77 * DEVICE SCHEMA NODE
78 * 1) There must be a key with the name DRIVER_CONFIG_NAME. The value
79 * associated with this key is a nvlist that follows the device/subsystem
80 * schema node format. The parameters in this node specify the
81 * configuration parameters that are specific to a particular device
82 * driver.
83 * 2) There must be a key with the name IOV_CONFIG_NAME. The value associated
84 * with this key is an nvlist that follows the device/subsystem schema node
85 * format. The parameters in this node specify the configuration
86 * parameters that are applied by the SR-IOV infrastructure.
87 *
88 * DEVICE/SUBSYSTEM SCHEMA NODE
89 * 1) All keys in the device/subsystem schema node are optional.
90 * 2) Each key specifies the name of a valid configuration parameter that may
91 * be applied to the device/subsystem combination specified by this node.
92 * The value associated with the key specifies the format of valid
93 * configuration values, and must be a nvlist in parameter schema node
94 * format.
95 *
96 * PARAMETER SCHEMA NODE
97 * 1) The parameter schema node must contain a key with the name
98 * TYPE_SCHEMA_NAME. The value associated with this key must be a string.
99 * This string specifies the type of value that the parameter specified by
100 * this node must take. The string must have one of the following values:
101 * - "bool" - The configuration value must be a boolean.
102 * - "mac-addr" - The configuration value must be a binary value. In
103 * addition, the value must be exactly 6 bytes long and
104 * the value must not be a multicast or broadcast mac.
105 * - "uint8_t" - The configuration value must be a integer value in
106 * the range [0, UINT8_MAX].
107 * - "uint16_t" - The configuration value must be a integer value in
108 * the range [0, UINT16_MAX].
109 * - "uint32_t" - The configuration value must be a integer value in
110 * the range [0, UINT32_MAX].
111 * - "uint64_t" - The configuration value must be a integer value in
112 * the range [0, UINT64_MAX].
113 * 2) The parameter schema may contain a key with the name
114 * REQUIRED_SCHEMA_NAME. This key is optional. If this key is present, the
115 * value associated with it must have a boolean type. If the value is true,
116 * then the parameter specified by this schema is a required parameter. All
117 * valid configurations must include all required parameters.
118 * 3) The parameter schema may contain a key with the name DEFAULT_SCHEMA_NAME.
119 * This key is optional. This key must not be present if the parameter
120 * specified by this schema is required. If this key is present, the value
121 * associated with the parent key must follow all restrictions specified by
122 * the type specified by this schema. If a configuration does not supply a
123 * value for the parameter specified by this schema, then the kernel will
124 * apply the value associated with this key in its place.
125 *
126 * The following is an example of a valid schema, as printed by nvlist_dump.
127 * Keys are printed followed by the type of the value in parantheses. The
128 * value is displayed following a colon. The indentation level reflects the
129 * level of nesting of nvlists. String values are displayed between []
130 * brackets. Binary values are shown with the length of the binary value (in
131 * bytes) followed by the actual binary values.
132 *
133 * PF (NVLIST):
134 * IOV (NVLIST):
135 * num_vfs (NVLIST):
136 * type (STRING): [uint16_t]
137 * required (BOOL): TRUE
138 * device (NVLIST):
139 * type (STRING): [string]
140 * required (BOOL): TRUE
141 * DRIVER (NVLIST):
142 * VF (NVLIST):
143 * IOV (NVLIST):
144 * passthrough (NVLIST):
145 * type (STRING): [bool]
146 * default (BOOL): FALSE
147 * DRIVER (NVLIST):
148 * mac-addr (NVLIST):
149 * type (STRING): [mac-addr]
150 * default (BINARY): 6 000000000000
151 * vlan (NVLIST):
152 * type (STRING): [uint16_t]
153 * spoof-check (NVLIST):
154 * type (STRING): [bool]
155 * default (BOOL): TRUE
156 * allow-set-mac (NVLIST):
157 * type (STRING): [bool]
158 * default (BOOL): FALSE
159 */
160struct pci_iov_schema
161{
162 void *schema;
163 size_t len;
164 int error;
165};
166
167/*
168 * SR-IOV configuration is passed to the kernel as a packed nvlist. See nv(3)
169 * for the details of the nvlist API. The expected format of the nvlist is:
170 *
171 * BASIC RULES
172 * 1) All keys are case-insensitive.
173 * 2) No keys that are not specified below may exist at any level of the
174 * config nvlist.
175 * 3) Unless otherwise specified, all keys are optional. It should go without
176 * saying a key being mandatory is transitive: that is, if a key is
177 * specified to contain a sub-nodes that contains a mandatory key, then
178 * the outer key is implicitly mandatory. If a key is mandatory then the
179 * associated value is also mandatory.
180 * 4) Order of keys is irrelevant.
181 *
182 * TOP LEVEL OF CONFIG NVLIST
183 * 1) All keys specified in this section are mandatory.
184 * 2) There must be a top-level key with the name PF_CONFIG_NAME. The value
185 * associated is an nvlist that follows the "device node" format. The
186 * parameters in this node specify parameters that apply to the PF.
187 * 3) For every VF being configured (this is set via the "num_vfs" parameter
188 * in the PF section), there must be a top-level key whose name is VF_PREFIX
189 * immediately followed by the index of the VF as a decimal integer. For
190 * example, this would be VF-0 for the first VF. VFs are numbered starting
191 * from 0. The value associated with this key follows the "device node"
192 * format. The parameters in this node specify configuration that applies
193 * to the VF specified in the key. Leading zeros are not permitted in VF
194 * index. Configuration for the second VF must be specified in a node with
195 * the key VF-1. VF-01 is not a valid key.
196 *
197 * DEVICE NODES
198 * 1) All keys specified in this section are mandatory.
199 * 2) The device node must contain a key with the name DRIVER_CONFIG_NAME. The
200 * value associated with this key is an nvlist following the subsystem node
201 * format. The parameters in this key specify configuration that is specific
202 * to a particular device driver.
203 * 3) The device node must contain a key with the name IOV_CONFIG_NAME. The
204 * value associated with this key is an nvlist following the subsystem node
205 * format. The parameters in this key specify configuration that is consumed
206 * by the SR-IOV infrastructure.
207 *
208 * SUBSYSTEM NODES
209 * 1) A subsystem node specifies configuration parameters that apply to a
210 * particular subsystem (driver or infrastructure) of a particular device
211 * (PF or individual VF).
212 * Note: We will refer to the section of the configuration schema that
213 * specifies the parameters for this subsystem and device
214 * configuration as the device/subsystem schema.
215 * 2) The subsystem node must contain only keys that correspond to parameters
216 * that are specified in the device/subsystem schema.
217 * 3) Every parameter specified as required in the device/subsystem schema is
218 * a mandatory key in the subsystem node.
219 * Note: All parameters that are not required in device/subsystem schema are
220 * optional keys. In particular, any parameter specified to have a
221 * default value in the device/subsystem schema is optional. The
222 * kernel is responsible for applying default values.
223 * 4) The value of every parameter in the device node must conform to the
224 * restrictions of the type specified for that parameter in the device/
225 * subsystem schema.
226 *
227 * The following is an example of a valid configuration, when validated against
228 * the schema example given above.
229 *
230 * PF (NVLIST):
231 * driver (NVLIST):
232 * iov (NVLIST):
233 * num_vfs (NUMBER): 3 (3) (0x3)
234 * device (STRING): [ix0]
235 * VF-0 (NVLIST):
236 * driver (NVLIST):
237 * vlan (NUMBER): 1000 (1000) (0x3e8)
238 * iov (NVLIST):
239 * passthrough (BOOL): TRUE
240 * VF-1 (NVLIST):
241 * driver (NVLIST):
242 * iov (NVLIST):
243 * VF-2 (NVLIST):
244 * driver (NVLIST):
245 * mac-addr (BINARY): 6 020102030405
246 * iov (NVLIST):
247 */
248struct pci_iov_arg
249{
250 void *config;
251 size_t len;
252};
253
254#define IOV_CONFIG _IOW('p', 10, struct pci_iov_arg)
255#define IOV_DELETE _IO('p', 11)
256#define IOV_GET_SCHEMA _IOWR('p', 12, struct pci_iov_schema)
257
258#endif