Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PCI_IOV_SCHEMA(9)	 BSD Kernel Developer's	Manual	     PCI_IOV_SCHEMA(9)

NAME
     pci_iov_schema, pci_iov_schema_alloc_node,	pci_iov_schema_add_bool,
     pci_iov_schema_add_string,	pci_iov_schema_add_uint8,
     pci_iov_schema_add_uint16,	pci_iov_schema_add_uint32,
     pci_iov_schema_add_uint64,	pci_iov_schema_add_unicast_mac -- PCI SR-IOV
     config schema interface

SYNOPSIS
     #include <machine/stdarg.h>
     #include <sys/nv.h>
     #include <sys/iov_schema.h>

     nvlist_t *
     pci_iov_schema_alloc_node(void);

     void
     pci_iov_schema_add_bool(nvlist_t *schema, const char *name,
	 uint32_t flags, int defaultVal);

     void
     pci_iov_schema_add_string(nvlist_t	*schema, const char *name,
	 uint32_t flags, const char *defaultVal);

     void
     pci_iov_schema_add_uint8(nvlist_t *schema,	const char *name,
	 uint32_t flags, uint8_t defaultVal);

     void
     pci_iov_schema_add_uint16(nvlist_t	*schema, const char *name,
	 uint32_t flags, uint16_t defaultVal);

     void
     pci_iov_schema_add_uint32(nvlist_t	*schema, const char *name,
	 uint32_t flags, uint32_t defaultVal);

     void
     pci_iov_schema_add_uint64(nvlist_t	*schema, const char *name,
	 uint32_t flags, uint64_t defaultVal);

     void
     pci_iov_schema_add_unicast_mac(nvlist_t *schema, const char *name,
	 uint32_t flags, const uint8_t *defaultVal);

DESCRIPTION
     The PCI Single-Root I/O Virtualization (SR-IOV) configuration schema is a
     data structure that describes the device-specific configuration parame-
     ters that a PF driver will	accept when SR-IOV is enabled on the PF	de-
     vice.  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 config-
     uration applied to	them, as long as the configuration for each VF con-
     forms to the VF schema.

     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.

     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
     iovctl.conf(5) for	documentation of all configuration parameters used by
     the SR-IOV	infrastructure.

     The parameter type	constrains the possible	values that the	configuration
     parameter may take.

     A configuration parameter may be specified	as a required parameter	by
     setting the IOV_SCHEMA_REQUIRED flag in the flags argument.  Required pa-
     rameters 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.

     Alternatively, a configuration parameter may be given a default value by
     setting the IOV_SCHEMA_HASDEFAULT flag in the flags argument.  If a con-
     figuration	parameter has a	default	value but the user has not specified a
     value for that parameter, then the	SR-IOV infrastructure will apply
     defaultVal	for that parameter in the configuration	before passing it to
     the PF driver.  It	is an error for	the value of the defaultVal parameter
     to	not conform to the restrictions	of the specified type.	If this	flag
     is	not specified then the defaultVal argument is ignored.	This flag is
     not compatible with the IOV_SCHEMA_REQUIRED flag; it is an	error to spec-
     ify both on the same parameter.

     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 pa-
     rameters 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.

     It	is highly recommended that a PF	driver reserve the use of optional pa-
     rameters for configuration	that is	truly optional.	 For example, a	Net-
     work 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"	param-
     eter as an	optional parameter as it would be legitimate for a VF to be
     configured	to have	no vlan	tagging	enabled	at all.

     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 ap-
     propriate 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 (or potentially force the user to make the choice by
     setting the parameter to be required).

     Configuration parameters that have	security implications must default to
     the most secure configuration possible.

     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.

     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
     pci_iov_attach(9) function	checks for this	error and will fail to ini-
     tialize 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	at-
     taching and run with SR-IOV disabled on the device.

     The 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.

     The pci_iov_schema_add_bool() function is used to specify a configuration
     parameter in the given schema with	the name name and having a boolean
     type.  Boolean values can only take the value true	or false (1 or 0, re-
     spectively).

     The pci_iov_schema_add_string() function is used to specify a configura-
     tion parameter in the given schema	with the name name and having a	string
     type.  String values are standard C strings.

     The pci_iov_schema_add_uint8() function is	used to	specify	a configura-
     tion parameter in the given schema	with the name name and having a
     uint8_t type.  Values of type uint8_t are unsigned	integers in the	range
     0 to 255, inclusive.

     The pci_iov_schema_add_uint16() function is used to specify a configura-
     tion parameter in the given schema	with the name name and having a
     uint16_t type.  Values of type uint16_t are unsigned integers in the
     range 0 to	65535, inclusive.

     The pci_iov_schema_add_uint32() function is used to specify a configura-
     tion parameter in the given schema	with the name name and having a
     uint32_t type.  Values of type uint32_t are unsigned integers in the
     range 0 to	(2**32 - 1), inclusive.

     The pci_iov_schema_add_uint64() function is used to specify a configura-
     tion parameter in the given schema	with the name name and having a
     uint64_t type.  Values of type uint64_t are unsigned integers in the
     range 0 to	(2**64 - 1), inclusive.

     The pci_iov_schema_add_unicast_mac() function is used to specify a	con-
     figuration	parameter in the given schema with the name 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.

RETURN VALUES
     The pci_iov_schema_alloc_node() function returns a	pointer	to the allo-
     cated schema, or NULL if a	failure	occurs.

SEE ALSO
     pci(9), PCI_IOV_ADD_VF(9),	PCI_IOV_INIT(9)

AUTHORS
     This manual page was written by Ryan Stone	<rstone@FreeBSD.org>.

BSD				 July 8, 2015				   BSD

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pci_iov_schema&sektion=9&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help