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.

2 files changed, 274 insertions, 0 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index e85dd7136776..d8fd5855ff40 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -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 \
diff --git a/share/man/man9/pci_iov_schema.9 b/share/man/man9/pci_iov_schema.9
new file mode 100644
index 000000000000..f2f1f303fdf4
--- /dev/null
+++ b/share/man/man9/pci_iov_schema.9
@@ -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 .