From owner-svn-src-all@FreeBSD.ORG Sun Mar 1 00:59:22 2015 Return-Path: Delivered-To: svn-src-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id C28B5E8A; Sun, 1 Mar 2015 00:59:22 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id A38D5387; Sun, 1 Mar 2015 00:59:22 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.9/8.14.9) with ESMTP id t210xMXD001157; Sun, 1 Mar 2015 00:59:22 GMT (envelope-from rstone@FreeBSD.org) Received: (from rstone@localhost) by svn.freebsd.org (8.14.9/8.14.9/Submit) id t210xMEB001154; Sun, 1 Mar 2015 00:59:22 GMT (envelope-from rstone@FreeBSD.org) Message-Id: <201503010059.t210xMEB001154@svn.freebsd.org> X-Authentication-Warning: svn.freebsd.org: rstone set sender to rstone@FreeBSD.org using -f From: Ryan Stone Date: Sun, 1 Mar 2015 00:59:22 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r279464 - head/share/man/man9 X-SVN-Group: head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 01 Mar 2015 00:59:23 -0000 Author: rstone Date: Sun Mar 1 00:59:21 2015 New Revision: 279464 URL: https://svnweb.freebsd.org/changeset/base/279464 Log: Document the interface for defining a configuration schema Differential Revision: https://reviews.freebsd.org/D89 Reviewed by: wblock, emaste, allanjude MFC after: 1 month Sponsored by: Sandvine Inc. Added: head/share/man/man9/pci_iov_schema.9 (contents, props changed) Modified: head/share/man/man9/Makefile Modified: head/share/man/man9/Makefile ============================================================================== --- head/share/man/man9/Makefile Sun Mar 1 00:58:23 2015 (r279463) +++ head/share/man/man9/Makefile Sun Mar 1 00:59:21 2015 (r279464) @@ -197,6 +197,7 @@ MAN= accept_filter.9 \ pci.9 \ PCI_ADD_VF.9 \ PCI_INIT_IOV.9 \ + pci_iov_schema.9 \ PCI_UNINIT_IOV.9 \ pfil.9 \ pfind.9 \ @@ -1175,6 +1176,14 @@ MLINKS+=pci.9 pci_alloc_msi.9 \ pci.9 pci_set_powerstate.9 \ pci.9 pci_set_max_read_req.9 \ pci.9 pci_write_config.9 +MLINKS+=pci_iov_schema.9 pci_iov_schema_alloc_node.9 \ + pci_iov_schema.9 pci_iov_schema_add_bool.9 \ + pci_iov_schema.9 pci_iov_schema_add_string.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint8.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint16.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint32.9 \ + pci_iov_schema.9 pci_iov_schema_add_uint64.9 \ + pci_iov_schema.9 pci_iov_schema_add_unicast_mac.9 MLINKS+=pfil.9 pfil_add_hook.9 \ pfil.9 pfil_head_register.9 \ pfil.9 pfil_head_unregister.9 \ Added: head/share/man/man9/pci_iov_schema.9 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/share/man/man9/pci_iov_schema.9 Sun Mar 1 00:59:21 2015 (r279464) @@ -0,0 +1,265 @@ +.\" +.\" Copyright (c) 2014 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$ +.\" +.Dd May 25, 2014 +.Dt pci_iov_schema 9 +.Os +.Sh NAME +.Nm pci_iov_schema , +.Nm pci_iov_schema_alloc_node , +.Nm pci_iov_schema_add_bool , +.Nm pci_iov_schema_add_string , +.Nm pci_iov_schema_add_uint8 , +.Nm pci_iov_schema_add_uint16 , +.Nm pci_iov_schema_add_uint32 , +.Nm pci_iov_schema_add_uint64 , +.Nm pci_iov_schema_add_unicast_mac +.Nd PCI SR-IOV config schema interface +.Sh SYNOPSIS +.In machine/stdarg.h +.In sys/nv.h +.In sys/iov_schema.h +.Ft nvlist_t * +.Fn pci_iov_schema_alloc_node "void" +.Ft void +.Fn pci_iov_schema_add_bool "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "int defaultVal" +.Ft void +.Fn pci_iov_schema_add_string "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "const char *defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint8 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint8_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint16 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint16_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint32 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint32_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_uint64 "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "uint64_t defaultVal" +.Ft void +.Fn pci_iov_schema_add_unicast_mac "nvlist_t *schema" "const char *name" \ +"uint32_t flags" "const uint8_t *defaultVal" +.Sh DESCRIPTION +The PCI Single-Root I/O Virtualization +.Pq SR-IOV +configuration schema is a data +structure that describes the device-specific configuration parameters that a PF +driver will accept when SR-IOV is enabled on the PF device. +Each PF driver defines two schema instances: the PF schema and the VF schema. +The PF schema describes configuration that applies to the PF device as a whole. +The VF schema describes configuration that applies to an individual VF device. +Different VF devices may have different configuration applied to them, as long +as the configuration for each VF conforms to the VF schema. +.Pp +A PF driver builds a configuration schema by first allocating a schema node and +then adding configuration parameter specifications to the schema. +The configuration parameter specification consists of a name and a value type. +.Pp +Configuration parameter names are case-insensitive. +It is an error to specify two or more configuration parameters with the same +name. +It is also an error to specific a configuration parameter that uses the same +name as a configuration parameter used by the SR-IOV infrastructure. +See +.Xr iovctl.conf 5 +for documentation of all configuration parameters used by the SR-IOV +infrastructure. +.Pp +The parameter type constrains the possible values that the configuration +parameter may take. +.Pp +A configuration parameter may be specified as a required parameter by setting +the +.Dv IOV_SCHEMA_REQUIRED +flag in the +.Pa flags +argument. +Required parameters must be specified by the user when SR-IOV is enabled. +If the user does not specify a required parameter, the SR-IOV infrastructure +will abort the request to enable SR-IOV and return an error to the user. +.Pp +Alternatively, a configuration parameter may be given a default value by +setting the +.Dv IOV_SCHEMA_HASDEFAULT +flag in the +.Pa flags +argument. +If a configuration parameter has a default value but the user has not specified +a value for that parameter, then the SR-IOV infrastructure will apply +.Pa defaultVal +for that parameter in the configuration before passing it to the PF driver. +It is an error for the value of the +.Pa defaultVal +parameter to not conform to the restrictions of the specified type. +If this flag is not specified then the +.Pa defaultVal +argument is ignored. +This flag is not compatible with the +.Dv IOV_SCHEMA_REQUIRED +flag; it is an error to specify both on the same parameter. +.Pp +The SR-IOV infrastructure guarantees that all configuration parameters that are +either specified as required or given a default value will be present in the +configuration passed to the PF driver. +Configuration parameters that are neither specified as required nor given a +default value are optional and may or may not be present in the configuration +passed to the PF driver. +.Pp +It is highly recommended that a PF driver reserve the use of optional parameters +for configuration that is truly optional. +For example, a Network Interface PF device might have the option to encapsulate +all traffic to and from a VF device in a vlan tag. +The PF driver could expose that option as a "vlan" parameter accepting an +integer argument specifying the vlan tag. +In this case, it would be appropriate to set the "vlan" parameter as an optional +parameter as it would be legitimate for a VF to be configured to have no vlan +tagging enabled at all. +.Pp +Alternatively, if the PF device had an boolean option that controlled whether +the VF was allowed to change its MAC address, it would not be appropriate to +set this parameter as optional. +The PF driver must either allow the MAC to change or not, so it would be more +appropriate for the PF driver to document the default behaviour by specifying +a default value in the schema +.Po or potentially force the user to make the choice by setting the parameter +to be required +.Pc . +.Pp +Configuration parameters that have security implications must default to the +most secure configuration possible. +.Pp +All device-specific configuration parameters must be documented in the manual +page for the PF driver, or in a separate manual page that is cross-referenced +from the main driver manual page. +.Pp +It is not necessary for a PF driver to check for failure from any of these +functions. +If an error occurs, it is flagged in the schema. +The +.Xr pci_iov_attach 9 +function checks for this error and will fail to initialize SR-IOV on the PF +device if an error is set in the schema. +If this occurs, it is recommended that the PF driver still succeed in attaching +and run with SR-IOV disabled on the device. +.Pp +The +.Fn pci_iov_schema_alloc_node +function is used to allocate an empty configuration schema. +It is not necessary to check for failure from this function. +The SR-IOV infrastructure will gracefully handle failure to allocate a schema +and will simply not enable SR-IOV on the PF device. +.Pp +The +.Fn pci_iov_schema_add_bool +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a boolean type. +Boolean values can only take the value true or false (1 or 0, respectively). +.Pp +The +.Fn pci_iov_schema_add_string +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a string type. +String values are standard C strings. +.Pp +The +.Fn pci_iov_schema_add_uint8 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint8_t +type. +Values of type +.Vt uint8_t +are unsigned integers in the range 0 to 255, inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint16 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint16_t +type. +Values of type +.Vt uint16_t +are unsigned integers in the range 0 to 65535, inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint32 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint32_t +type. +Values of type +.Vt uint32_t +are unsigned integers in the range 0 to +.Po 2**32 - 1 Pc , +inclusive. +.Pp +The +.Fn pci_iov_schema_add_uint64 +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a +.Vt uint64_t +type. +Values of type +.Vt uint64_t +are unsigned integers in the range 0 to +.Po 2**64 - 1 Pc , +inclusive. +.Pp +The +.Fn pci_iov_schema_add_unicast_mac +function is used to specify a configuration parameter in the given schema with +the name +.Pa name +and having a unicast-mac type. +Values of type unicast-mac are binary values exactly 6 bytes long. +The MAC address is guaranteed to not be a multicast or broadcast address. +.Sh RETURN VALUES +The +.Fn pci_iov_schema_alloc_node +function returns a pointer to the allocated schema, or NULL if a failure occurs. +.Sh SEE ALSO +.Xr pci 9 , +.Xr PCI_ADD_VF 9 , +.Xr PCI_INIT_IOV 9 +.Sh AUTHORS +This manual page was written by +.An Ryan Stone Aq rstone@FreeBSD.org .