Difference between revisions of "Bus:Device.Function (BDF) Notation"

From Xen
(Migrated page)
 
(Anchor)
Line 24: Line 24:
 
For example, the following describes Bus 0, Device 2, Function 0:
 
For example, the following describes Bus 0, Device 2, Function 0:
   
*
 
 
<pre><nowiki>
 
<pre><nowiki>
 
00:02.0</nowiki></pre>
 
00:02.0</nowiki></pre>
Line 38: Line 37:
 
For example, for following describes Domain 0, Bus 0, Device 2, Function 0:
 
For example, for following describes Domain 0, Bus 0, Device 2, Function 0:
   
*
 
 
<pre><nowiki>
 
<pre><nowiki>
 
0000:00:02.0</nowiki></pre>
 
0000:00:02.0</nowiki></pre>
Line 46: Line 44:
 
<span id="vslot"></span>
 
<span id="vslot"></span>
 
<span id="option"></span>
 
<span id="option"></span>
  +
 
== Extension Virtual-Slots and Options ==
 
== Extension Virtual-Slots and Options ==
 
Xen further extends BDF notation to allow a virtual-slot and options to be supplied. This notation is used when specifying boot-time attachment with the configuration file of a domain. A side-effect of the work on multi-function PCI pass-through is that this notation is also now accepted for PCI hot-plug as well.
 
Xen further extends BDF notation to allow a virtual-slot and options to be supplied. This notation is used when specifying boot-time attachment with the configuration file of a domain. A side-effect of the work on multi-function PCI pass-through is that this notation is also now accepted for PCI hot-plug as well.
Line 61: Line 60:
 
In the case where both a virtual-slot and options are specified, the virtual-slot must come first. For example, the following denotes that physical function 0000:00:02.0 should be passed-through into virtual-slot 1c and that the resulting pass-through device will have the msitranslate option enabled.
 
In the case where both a virtual-slot and options are specified, the virtual-slot must come first. For example, the following denotes that physical function 0000:00:02.0 should be passed-through into virtual-slot 1c and that the resulting pass-through device will have the msitranslate option enabled.
   
*
 
 
<pre><nowiki>
 
<pre><nowiki>
 
0000:00:02.0@1c,msitranslate=1</nowiki></pre>
 
0000:00:02.0@1c,msitranslate=1</nowiki></pre>
Line 128: Line 126:
 
A limitation of this scheme is that it does not allow functions from different physical devices to be combined to form a multi-function virtual device. However it is of the concern that such combinations would be invalid due to hardware limitations. This needs further investigation.
 
A limitation of this scheme is that it does not allow functions from different physical devices to be combined to form a multi-function virtual device. However it is of the concern that such combinations would be invalid due to hardware limitations. This needs further investigation.
   
[[Category:Xen]
+
[[Category:Xen]]
[[Category:Users]
+
[[Category:Users]]
[[Category:HowTo]
+
[[Category:HowTo]]

Revision as of 17:21, 8 November 2011


Simple BDF notation

BDF stands for Bus Device Function and is a notation used to succinctly describe PCI and PCIe devices. The simple form of the notation is:

  • PCI Bus number in hexadecimal, often padded using a leading zeros to two or four digits
  • A colon (:)
  • PCI Device number in hexadecimal, often padded using a leading zero to two digits . Sometimes this also referred to as the slot number.
  • A decimal point (.)
  • PCI Function number in hexadecimal

For example, the following describes Bus 0, Device 2, Function 0:

00:02.0

BDF Notation Extension for PCI Domain

There is an extended form of the BDF notation, which confusingly is also typically referred to as BDF. Fortunately both variants are typically interchangeable.

The extension of the notation is to prefix the simple notation with:

  • PCI Domain number, often padded using leading zeros to four digits
  • A colon (:)

For example, for following describes Domain 0, Bus 0, Device 2, Function 0:

0000:00:02.0

Confusingly, PCI domains do not correspond to Xen domains. PCI domains are a physical property of the host, as are PCI buses. It is particular note that the output of "xm pci-list" refers to PCI domains and not Xen domains, whereas the command takes a Xen domain and not a PCI domain as one of its arguments. See Self:VTdHowTo for more information on the use of "xm pci-list"

Extension Virtual-Slots and Options

Xen further extends BDF notation to allow a virtual-slot and options to be supplied. This notation is used when specifying boot-time attachment with the configuration file of a domain. A side-effect of the work on multi-function PCI pass-through is that this notation is also now accepted for PCI hot-plug as well.

This notation is formed by optionally appending the following to extended BDF:

  • An at-sign (@)
  • A virtual slot number in hexadecimal, may be padded using leading zeros to two digits

Or number of:

  • A comma (,)
  • An option name. Currently the only valid option names are msitranslate and power_mgmt.
  • An equals-sign (=)
  • A value for the option. Currently the only valid values are 0 or 1, and yes or no

In the case where both a virtual-slot and options are specified, the virtual-slot must come first. For example, the following denotes that physical function 0000:00:02.0 should be passed-through into virtual-slot 1c and that the resulting pass-through device will have the msitranslate option enabled.

0000:00:02.0@1c,msitranslate=1


Anchor(multi-function)

BDF Notation Extension for Multi-Function PCI Pass-Through

BDF format is further extended to expand the function field to accept a comma-delimited list of:

  • Function unit
  • A range of function numbers, denoted by:
    • The first function unit
    • A hyphen (-)
    • The last function unit
  • An asterisk (*), used to denote all physical functions that are present in the device

Where a function unit comprises of:

  • Function number and optionally;
  • An equals sign and;
  • A virtual function number to use

None of the characters used in this expanded syntax for a function are valid in option names, so parsing can be done unambiguously.

This notation is internally expanded into groups of functions. For example:

Multi-Function Notation Physical
>0000:00:1d.0-2 >0000:00:1d.0
0000:00:1d.1
0000:00:1d.2
>0000:00:1d.0,3,5,7 >0000:00:1d.0
0000:00:1d.3
0000:00:1d.5
0000:00:1d.7
>0000:00:1d.* >0000:00:1d.0
0000:00:1d.1
0000:00:1d.2
0000:00:1d.3
0000:00:1d.5
0000:00:1d.7

The examples above assume that virtual slot 7 will be used. The last example is for a physical device that has functions 0, 1, 2, 3, 5 and 7.

As shown above the physical functions are identity mapped to virtual functions. The exceptions are:

  • If physical function zero isn't present then the numerically lowest physical function is mapped to virtual function zero. This is because PCI devices must always include function zero.
  • Explicit assignment of virtual functions.

Examples that explicitly assign virtual functions:

Multi-Function Notation Physical
>0000:00:1d.2=0-0=2 >0000:00:1d.2
0000:00:1d.1
0000:00:1d.0
>0000:00:1d.0=3,3=2,5=1,7=0 >0000:00:1d.7
0000:00:1d.5
0000:00:1d.3
0000:00:1d.0

Again, the examples above assume that virtual slot 7 will be used. The asterisk (*) notation can't be used in conjunction with explicitly setting the virtual function number.

A virtual device that has explicit virtual functions assigned in such a way that the virtual device doesn't include virtual function zero is invalid.

A limitation of this scheme is that it does not allow functions from different physical devices to be combined to form a multi-function virtual device. However it is of the concern that such combinations would be invalid due to hardware limitations. This needs further investigation.