aboutsummaryrefslogtreecommitdiff
path: root/sys/sys/iov.h
blob: 3be01180a10704741fac40dd0923fcfffe7f5b74 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
/*-
 * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
 *
 * Copyright (c) 2013-2015 Sandvine Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * $FreeBSD$
 */

#ifndef _SYS_IOV_H_
#define _SYS_IOV_H_

#include <sys/ioccom.h>

#define	PF_CONFIG_NAME		"PF"
#define	VF_SCHEMA_NAME		"VF"

#define	VF_PREFIX		"VF-"
#define	VF_PREFIX_LEN		3
#define	VF_NUM_LEN		5	/* The maximum VF num is 65535. */
#define	VF_MAX_NAME		(VF_PREFIX_LEN + VF_NUM_LEN + 1)

#define	DRIVER_CONFIG_NAME	"DRIVER"
#define	IOV_CONFIG_NAME		"IOV"

#define	TYPE_SCHEMA_NAME	"TYPE"
#define	DEFAULT_SCHEMA_NAME	"DEFAULT"
#define	REQUIRED_SCHEMA_NAME	"REQUIRED"

/*
 * Because each PF device is expected to expose a unique set of possible
 * configurations, the SR-IOV infrastructure dynamically queries the PF
 * driver for its capabilities.  These capabilities are exposed to userland
 * with a configuration schema.  The schema is exported from the kernel as a
 * packed nvlist.  See nv(3) for the details of the nvlist API.  The expected
 * format of the nvlist is:
 *
 * BASIC RULES
 *   1) All keys are case-insensitive.
 *   2) No keys that are not specified below may exist at any level of the
 *      schema.
 *   3) All keys are mandatory unless explicitly documented as optional.  If a
 *      key is mandatory then the associated value is also mandatory.
 *   4) Order of keys is irrelevant.
 *
 * TOP LEVEL
 *   1) There must be a top-level key with the name PF_CONFIG_NAME.  The value
 *      associated with this key is a nvlist that follows the device schema
 *      node format.  The parameters in this node specify the configuration
 *      parameters that may be applied to a PF.
 *   2) There must be a top-level key with the name VF_SCHEMA_NAME.  The value
 *      associated with this key is a nvlist that follows the device schema
 *      node format.  The parameters in this node specify the configuration
 *      parameters that may be applied to a VF.
 *
 * DEVICE SCHEMA NODE
 *   1) There must be a key with the name DRIVER_CONFIG_NAME.  The value
 *      associated with this key is a nvlist that follows the device/subsystem
 *      schema node format.  The parameters in this node specify the
 *      configuration parameters that are specific to a particular device
 *      driver.
 *   2) There must be a key with the name IOV_CONFIG_NAME.  The value associated
 *      with this key is an nvlist that follows the device/subsystem schema node
 *      format.  The parameters in this node specify the configuration
 *      parameters that are applied by the SR-IOV infrastructure.
 *
 * DEVICE/SUBSYSTEM SCHEMA NODE
 *   1) All keys in the device/subsystem schema node are optional.
 *   2) Each key specifies the name of a valid configuration parameter that may
 *      be applied to the device/subsystem combination specified by this node.
 *      The value associated with the key specifies the format of valid
 *      configuration values, and must be a nvlist in parameter schema node
 *      format.
 *
 * PARAMETER SCHEMA NODE
 *   1) The parameter schema node must contain a key with the name
 *      TYPE_SCHEMA_NAME.  The value associated with this key must be a string.
 *      This string specifies the type of value that the parameter specified by
 *      this node must take.  The string must have one of the following values:
 *         - "bool"     - The configuration value must be a boolean.
 *         - "mac-addr" - The configuration value must be a binary value.  In
 *                         addition, the value must be exactly 6 bytes long and
 *                         the value must not be a multicast or broadcast mac.
 *         - "uint8_t"  - The configuration value must be a integer value in
 *                         the range [0, UINT8_MAX].
 *         - "uint16_t" - The configuration value must be a integer value in
 *                         the range [0, UINT16_MAX].
 *         - "uint32_t" - The configuration value must be a integer value in
 *                         the range [0, UINT32_MAX].
 *         - "uint64_t" - The configuration value must be a integer value in
 *                         the range [0, UINT64_MAX].
 *  2) The parameter schema may contain a key with the name
 *     REQUIRED_SCHEMA_NAME.  This key is optional.  If this key is present, the
 *     value associated with it must have a boolean type.  If the value is true,
 *     then the parameter specified by this schema is a required parameter.  All
 *     valid configurations must include all required parameters.
 *  3) The parameter schema may contain a key with the name DEFAULT_SCHEMA_NAME.
 *     This key is optional.  This key must not be present if the parameter
 *     specified by this schema is required.  If this key is present, the value
 *     associated with the parent key must follow all restrictions specified by
 *     the type specified by this schema.  If a configuration does not supply a
 *     value for the parameter specified by this schema, then the kernel will
 *     apply the value associated with this key in its place.
 *
 * The following is an example of a valid schema, as printed by nvlist_dump.
 * Keys are printed followed by the type of the value in parantheses.  The
 * value is displayed following a colon.  The indentation level reflects the
 * level of nesting of nvlists.  String values are displayed between []
 * brackets.  Binary values are shown with the length of the binary value (in
 * bytes) followed by the actual binary values.
 *
 *  PF (NVLIST):
 *      IOV (NVLIST):
 *          num_vfs (NVLIST):
 *              type (STRING): [uint16_t]
 *              required (BOOL): TRUE
 *          device (NVLIST):
 *              type (STRING): [string]
 *              required (BOOL): TRUE
 *      DRIVER (NVLIST):
 *  VF (NVLIST):
 *      IOV (NVLIST):
 *          passthrough (NVLIST):
 *              type (STRING): [bool]
 *              default (BOOL): FALSE
 *      DRIVER (NVLIST):
 *          mac-addr (NVLIST):
 *              type (STRING): [mac-addr]
 *              default (BINARY): 6 000000000000
 *          vlan (NVLIST):
 *               type (STRING): [uint16_t]
 *          spoof-check (NVLIST):
 *              type (STRING): [bool]
 *              default (BOOL): TRUE
 *          allow-set-mac (NVLIST):
 *              type (STRING): [bool]
 *              default (BOOL): FALSE
 */
struct pci_iov_schema
{
	void *schema;
	size_t len;
	int error;
};

/*
 * SR-IOV configuration is passed to the kernel as a packed nvlist.  See nv(3)
 * for the details of the nvlist API.  The expected format of the nvlist is:
 *
 * BASIC RULES
 *   1) All keys are case-insensitive.
 *   2) No keys that are not specified below may exist at any level of the
 *      config nvlist.
 *   3) Unless otherwise specified, all keys are optional.  It should go without
 *      saying a key being mandatory is transitive: that is, if a key is
 *      specified to contain a sub-nodes that contains a mandatory key, then
 *      the outer key is implicitly mandatory.  If a key is mandatory then the
 *      associated value is also mandatory.
 *   4) Order of keys is irrelevant.
 *
 * TOP LEVEL OF CONFIG NVLIST
 * 1) All keys specified in this section are mandatory.
 * 2) There must be a top-level key with the name PF_CONFIG_NAME.  The value
 *    associated is an nvlist that follows the "device node" format.  The
 *    parameters in this node specify parameters that apply to the PF.
 * 3) For every VF being configured (this is set via the "num_vfs" parameter
 *    in the PF section), there must be a top-level key whose name is VF_PREFIX
 *    immediately followed by the index of the VF as a decimal integer.  For
 *    example, this would be VF-0 for the first VF.  VFs are numbered starting
 *    from 0.  The value associated with this key follows the "device node"
 *    format.  The parameters in this node specify configuration that applies
 *    to the VF specified in the key.  Leading zeros are not permitted in VF
 *    index.  Configuration for the second VF must be specified in a node with
 *    the key VF-1.  VF-01 is not a valid key.
 *
 * DEVICE NODES
 * 1) All keys specified in this section are mandatory.
 * 2) The device node must contain a key with the name DRIVER_CONFIG_NAME.  The
 *    value associated with this key is an nvlist following the subsystem node
 *    format.  The parameters in this key specify configuration that is specific
 *    to a particular device driver.
 * 3) The device node must contain a key with the name IOV_CONFIG_NAME.  The
 *    value associated with this key is an nvlist following the subsystem node
 *    format.  The parameters in this key specify configuration that is consumed
 *    by the SR-IOV infrastructure.
 *
 * SUBSYSTEM NODES
 * 1) A subsystem node specifies configuration parameters that apply to a
 *    particular subsystem (driver or infrastructure) of a particular device
 *    (PF or individual VF).
 *         Note: We will refer to the section of the configuration schema that
 *               specifies the parameters for this subsystem and device
 *               configuration as the device/subystem schema.
 * 2) The subsystem node must contain only keys that correspond to parameters
 *    that are specified in the device/subsystem schema.
 * 3) Every parameter specified as required in the device/subsystem schema is
 *    a mandatory key in the subsystem node.
 *    Note:  All parameters that are not required in device/subsystem schema are
 *           optional keys.  In particular, any parameter specified to have a
 *           default value in the device/subsystem schema is optional.  The
 *           kernel is responsible for applying default values.
 * 4) The value of every parameter in the device node must conform to the
 *    restrictions of the type specified for that parameter in the device/
 *    subsystem schema.
 *
 * The following is an example of a valid configuration, when validated against
 * the schema example given above.
 *
 * PF (NVLIST):
 *     driver (NVLIST):
 *     iov (NVLIST):
 *         num_vfs (NUMBER): 3 (3) (0x3)
 *         device (STRING): [ix0]
 * VF-0 (NVLIST):
 *     driver (NVLIST):
 *         vlan (NUMBER): 1000 (1000) (0x3e8)
 *     iov (NVLIST):
 *         passthrough (BOOL): TRUE
 * VF-1 (NVLIST):
 *     driver (NVLIST):
 *     iov (NVLIST):
 * VF-2 (NVLIST):
 *     driver (NVLIST):
 *         mac-addr (BINARY): 6 020102030405
 *     iov (NVLIST):
 */
struct pci_iov_arg
{
	void *config;
	size_t len;
};

#define	IOV_CONFIG	_IOW('p', 10, struct pci_iov_arg)
#define	IOV_DELETE	_IO('p', 11)
#define	IOV_GET_SCHEMA	_IOWR('p', 12, struct pci_iov_schema)

#endif