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 /* 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: 56 * 57 * BASIC RULES 58 * 1) All keys are case-insensitive. 59 * 2) No keys that are not specified below may exist at any level of the 60 * schema. 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. 64 * 65 * TOP LEVEL 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. 74 * 75 * DEVICE SCHEMA NODE 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 80 * driver. 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. 85 * 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 92 * format. 93 * 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. 123 * 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. 130 * 131 * PF (NVLIST): 132 * IOV (NVLIST): 133 * num_vfs (NVLIST): 134 * type (STRING): [uint16_t] 135 * required (BOOL): TRUE 136 * device (NVLIST): 137 * type (STRING): [string] 138 * required (BOOL): TRUE 139 * DRIVER (NVLIST): 140 * VF (NVLIST): 141 * IOV (NVLIST): 142 * passthrough (NVLIST): 143 * type (STRING): [bool] 144 * default (BOOL): FALSE 145 * DRIVER (NVLIST): 146 * mac-addr (NVLIST): 147 * type (STRING): [mac-addr] 148 * default (BINARY): 6 000000000000 149 * vlan (NVLIST): 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 157 */ 158 struct pci_iov_schema 159 { 160 void *schema; 161 size_t len; 162 int error; 163 }; 164 165 /* 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: 168 * 169 * BASIC RULES 170 * 1) All keys are case-insensitive. 171 * 2) No keys that are not specified below may exist at any level of the 172 * config nvlist. 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. 179 * 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. 194 * 195 * DEVICE NODES 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. 205 * 206 * SUBSYSTEM NODES 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/subsystem 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/ 223 * subsystem schema. 224 * 225 * The following is an example of a valid configuration, when validated against 226 * the schema example given above. 227 * 228 * PF (NVLIST): 229 * driver (NVLIST): 230 * iov (NVLIST): 231 * num_vfs (NUMBER): 3 (3) (0x3) 232 * device (STRING): [ix0] 233 * VF-0 (NVLIST): 234 * driver (NVLIST): 235 * vlan (NUMBER): 1000 (1000) (0x3e8) 236 * iov (NVLIST): 237 * passthrough (BOOL): TRUE 238 * VF-1 (NVLIST): 239 * driver (NVLIST): 240 * iov (NVLIST): 241 * VF-2 (NVLIST): 242 * driver (NVLIST): 243 * mac-addr (BINARY): 6 020102030405 244 * iov (NVLIST): 245 */ 246 struct pci_iov_arg 247 { 248 void *config; 249 size_t len; 250 }; 251 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) 255 256 #endif 257