FreeBSD/Linux Kernel Cross Reference
sys/sys/iov.h

     /*-
      * 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

Cache object: db832de885a908b0fa96fd4162be821d