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.
This commit is contained in:
rstone
parent
d13e84a414
commit
65800eac29
@ -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 \
|
||||
|
||||
265
share/man/man9/pci_iov_schema.9
Normal file
265
share/man/man9/pci_iov_schema.9
Normal file
@ -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 .
|
||||
Loading…
Reference in New Issue
Block a user