xref: /freebsd/share/man/man9/PCI_IOV_ADD_VF.9 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19)
1f3bb9251SJohn Baldwin.\"
2f3bb9251SJohn Baldwin.\" Copyright (c) 2014 Sandvine Inc.
3f3bb9251SJohn Baldwin.\" All rights reserved.
4f3bb9251SJohn Baldwin.\"
5f3bb9251SJohn Baldwin.\" Redistribution and use in source and binary forms, with or without
6f3bb9251SJohn Baldwin.\" modification, are permitted provided that the following conditions
7f3bb9251SJohn Baldwin.\" are met:
8f3bb9251SJohn Baldwin.\" 1. Redistributions of source code must retain the above copyright
9f3bb9251SJohn Baldwin.\"    notice, this list of conditions and the following disclaimer.
10f3bb9251SJohn Baldwin.\" 2. Redistributions in binary form must reproduce the above copyright
11f3bb9251SJohn Baldwin.\"    notice, this list of conditions and the following disclaimer in the
12f3bb9251SJohn Baldwin.\"    documentation and/or other materials provided with the distribution.
13f3bb9251SJohn Baldwin.\"
14f3bb9251SJohn Baldwin.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15f3bb9251SJohn Baldwin.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16f3bb9251SJohn Baldwin.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17f3bb9251SJohn Baldwin.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18f3bb9251SJohn Baldwin.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19f3bb9251SJohn Baldwin.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20f3bb9251SJohn Baldwin.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21f3bb9251SJohn Baldwin.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22f3bb9251SJohn Baldwin.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23f3bb9251SJohn Baldwin.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24f3bb9251SJohn Baldwin.\" SUCH DAMAGE.
25f3bb9251SJohn Baldwin.\"
26f3bb9251SJohn Baldwin.Dd May 28, 2015
27f3bb9251SJohn Baldwin.Dt PCI_IOV_ADD_VF 9
28f3bb9251SJohn Baldwin.Os
29f3bb9251SJohn Baldwin.Sh NAME
30f3bb9251SJohn Baldwin.Nm PCI_IOV_ADD_VF
31f3bb9251SJohn Baldwin.Nd inform a PF driver that a VF is being created
32f3bb9251SJohn Baldwin.Sh SYNOPSIS
33f3bb9251SJohn Baldwin.In sys/bus.h
34f3bb9251SJohn Baldwin.In machine/stdarg.h
35f3bb9251SJohn Baldwin.In sys/nv.h
36f3bb9251SJohn Baldwin.In dev/pci/pci_iov.h
37f3bb9251SJohn Baldwin.Ft int
38f3bb9251SJohn Baldwin.Fn PCI_IOV_ADD_VF "device_t dev" "uint16_t vfnum" "const nvlist_t *vf_config"
39f3bb9251SJohn Baldwin.Sh DESCRIPTION
40f3bb9251SJohn BaldwinThe
41f3bb9251SJohn Baldwin.Fn PCI_IOV_ADD_VF
42f3bb9251SJohn Baldwinmethod is called by the PCI Single-Root I/O Virtualization
43f3bb9251SJohn Baldwin.Pq SR-IOV
44f3bb9251SJohn Baldwininfrastructure when it is initializating a new Virtual Function (VF) as a child
45f3bb9251SJohn Baldwinof the given Physical Function (PF) device.
46f3bb9251SJohn BaldwinThis method will not be called until a successful call to
47f3bb9251SJohn Baldwin.Xr PCI_IOV_INIT 9
48f3bb9251SJohn Baldwinhas been made.
49f3bb9251SJohn BaldwinIt is not guaranteed that this method will be called following a successful call
50f3bb9251SJohn Baldwinto
51f3bb9251SJohn Baldwin.Xr PCI_IOV_INIT 9 .
52f3bb9251SJohn BaldwinIf the infrastructure encounters a failure to allocate resources following the
53f3bb9251SJohn Baldwincall to
54f3bb9251SJohn Baldwin.Xr PCI_IOV_INIT 9 ,
55f3bb9251SJohn Baldwinthe VF creation will be aborted and
56f3bb9251SJohn Baldwin.Xr PCI_IOV_UNINIT 9
57f3bb9251SJohn Baldwinwill be called immediately without any preceding calls to
58f3bb9251SJohn Baldwin.Nm .
59f3bb9251SJohn Baldwin.Pp
60f3bb9251SJohn BaldwinThe index of the VF being initialized is passed in the
61f3bb9251SJohn Baldwin.Fa vfnum
62f3bb9251SJohn Baldwinargument.
63f3bb9251SJohn BaldwinVFs are always numbered sequentially starting at 0.
64f3bb9251SJohn Baldwin.Pp
65f3bb9251SJohn BaldwinIf the driver requested device-specific configuration parameters via a VF schema
66f3bb9251SJohn Baldwinin its call to
67f3bb9251SJohn Baldwin.Xr pci_iov_attach 9 ,
68f3bb9251SJohn Baldwinthose parameters will be contained in the
69f3bb9251SJohn Baldwin.Pa vf_config
70f3bb9251SJohn Baldwinargument.
71f3bb9251SJohn BaldwinAll configuration parameters that were either set as required parameters or that
72f3bb9251SJohn Baldwinhad a default value set in the VF schema are guaranteed to be present in
73f3bb9251SJohn Baldwin.Fa vf_config .
74f3bb9251SJohn BaldwinConfiguration parameters that were neither set as required nor were given a
75f3bb9251SJohn Baldwindefault value are optional and may or may not be present in
76f3bb9251SJohn Baldwin.Fa vf_config .
77f3bb9251SJohn Baldwin.Fa vf_config
78f3bb9251SJohn Baldwinwill not contain any configuration parameters that were not specified in the VF
79f3bb9251SJohn Baldwinschema.
80f3bb9251SJohn BaldwinAll configuration parameters will have the correct type and will be in the range
81f3bb9251SJohn Baldwinof valid values specified in the schema.
82f3bb9251SJohn Baldwin.Pp
83f3bb9251SJohn BaldwinNote that it is possible for the user to set different configuration values on
84f3bb9251SJohn Baldwindifferent VF devices that are children of the same PF.
85f3bb9251SJohn BaldwinThe PF driver must not cache configuration parameters passed in previous calls
86f3bb9251SJohn Baldwinto
87f3bb9251SJohn Baldwin.Fn PCI_IOV_ADD_VF
88f3bb9251SJohn Baldwinfor other VFs and apply those parameters to the current VF.
89f3bb9251SJohn Baldwin.Pp
90f3bb9251SJohn BaldwinThis function will not be called twice for the same
91f3bb9251SJohn Baldwin.Fa vf_num
92f3bb9251SJohn Baldwinon the same PF device without
93f3bb9251SJohn Baldwin.Xr PCI_IOV_UNINIT 9
94f3bb9251SJohn Baldwinand
95f3bb9251SJohn Baldwin.Xr PCI_IOV_INIT 9
96f3bb9251SJohn Baldwinfirst being called, in that order.
97f3bb9251SJohn Baldwin.Sh RETURN VALUES
98f3bb9251SJohn BaldwinThis method returns 0 on success, otherwise an appropriate error is returned.
99f3bb9251SJohn BaldwinIf this method returns an error then the current VF device will be destroyed
100f3bb9251SJohn Baldwinbut the rest of the VF devices will be created and SR-IOV will be enabled on
101f3bb9251SJohn Baldwinthe PF.
102f3bb9251SJohn Baldwin.Sh SEE ALSO
103f3bb9251SJohn Baldwin.Xr nv 9 ,
104f3bb9251SJohn Baldwin.Xr pci 9 ,
105f3bb9251SJohn Baldwin.Xr PCI_IOV_INIT 9 ,
106*548afe2bSChristian Brueffer.Xr pci_iov_schema 9 ,
107f3bb9251SJohn Baldwin.Xr PCI_IOV_UNINIT 9
108f3bb9251SJohn Baldwin.Sh AUTHORS
109f3bb9251SJohn BaldwinThis manual page was written by
110f3bb9251SJohn Baldwin.An Ryan Stone Aq Mt rstone@FreeBSD.org .
111