Bus:Device.Function (BDF) Notation

From Xen
Jump to navigationJump to search


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.

Retrieved from "https://wiki.xenproject.org/index.php?title=Bus:Device.Function_(BDF)_Notation&oldid=10596"