sys/sys/iov.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   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  * $FreeBSD$
  29  */
  30
  31 #ifndef _SYS_IOV_H_
  32 #define _SYS_IOV_H_
  33
  34 #include <sys/ioccom.h>
  35
  36 #define PF_CONFIG_NAME          "PF"
  37 #define VF_SCHEMA_NAME          "VF"
  38
  39 #define VF_PREFIX               "VF-"
  40 #define VF_PREFIX_LEN           3
  41 #define VF_NUM_LEN              5       /* The maximum VF num is 65535. */
  42 #define VF_MAX_NAME             (VF_PREFIX_LEN + VF_NUM_LEN + 1)
  43
  44 #define DRIVER_CONFIG_NAME      "DRIVER"
  45 #define IOV_CONFIG_NAME         "IOV"
  46
  47 #define TYPE_SCHEMA_NAME        "TYPE"
  48 #define DEFAULT_SCHEMA_NAME     "DEFAULT"
  49 #define REQUIRED_SCHEMA_NAME    "REQUIRED"
  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  */
 160 struct 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/subystem 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  */
 248 struct 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