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

From Xen
m (BDF Notation Extension for PCI Domain: "For example, for following ..."->"For example, the following ..." "It is particular note ..."->"In particular note ..." "Self:VTdHowTo"->"VTdHowTo)
 
(4 intermediate revisions by one other user not shown)
Line 15: Line 15:
 
<span id="simple"></span>
 
<span id="simple"></span>
 
== Simple BDF notation ==
 
== 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:
+
BDF stands for the Bus:Device.Function 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
 
* PCI Bus number in hexadecimal, often padded using a leading zeros to two or four digits
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>00:02.0</pre>
00:02.0</nowiki></pre>
 
   
 
<span id="domain"></span>
 
<span id="domain"></span>
Line 38: Line 37:
 
For example, the following describes Domain 0, Bus 0, Device 2, Function 0:
 
For example, the following describes Domain 0, Bus 0, Device 2, Function 0:
   
<pre><nowiki>
+
<pre>0000:00:02.0</pre>
0000:00:02.0</nowiki></pre>
 
   
Confusingly, '''PCI domains do not correspond to Xen domains'''. PCI domains are a physical property of the host, as are PCI buses. In 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 [[VTdHowTo]] for more information on the use of "xm pci-list"
+
Confusingly, '''PCI domains do not correspond to Xen domains'''. PCI domains are a physical property of the host, as are PCI buses. In particular note that the output of "xl pci-list <domain>" will provide output which refers PCI domains, but the argument expected is a xen domain. See [[VTdHowTo]] for more information on the use of "xl pci-list <domain>"
   
 
<span id="vslot"></span>
 
<span id="vslot"></span>
Line 52: Line 50:
   
 
* An at-sign (@)
 
* An at-sign (@)
* A virtual slot number in hexadecimal, may be padded using leading zeros to two digits
+
* A virtual slot number in hexadecimal, which may be padded using leading zeros to two digits
 
Or number of:
 
Or number of:
   
Line 61: Line 59:
 
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>0000:00:02.0@1c,msitranslate=1</pre>
<pre><nowiki>
 
0000:00:02.0@1c,msitranslate=1</nowiki></pre>
 
   
   

Latest revision as of 21:00, 22 February 2014


Simple BDF notation

BDF stands for the Bus:Device.Function 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 is 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, the 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. In particular note that the output of "xl pci-list <domain>" will provide output which refers PCI domains, but the argument expected is a xen domain. See VTdHowTo for more information on the use of "xl pci-list <domain>"

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, which 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


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.