Re: [Qemu-devel] RFC [v2]: vfio / device assignment -- layout of device fd files

[Stuart Yoder]

Meant to identify the changes in v2 of this proposal:

v2:
   -removed PCI_INFO record type
   -removed PCI_BAR_INFO record type
   -PCI_CONFIG_SPACE is now a sub-record/property of a REGION
   -removed physical address from region and made it
    a subrecord/property of a REGION
   -added PCI_BAR_INDEX sub-record type
   -updated magic numbers

Stuart

On Fri, Sep 9, 2011 at 8:11 AM, Stuart Yoder <address@hidden> wrote:
> Based on the discussions over the last couple of weeks
> I have updated the device fd file layout proposal and
> tried to specify it a bit more formally.
>
> ===============================================================
>
> 1.  Overview
>
>  This specification describes the layout of device files
>  used in the context of vfio, which gives user space
>  direct access to I/O devices that have been bound to
>  vfio.
>
>  When a device fd is opened and read, offset 0x0 contains
>  a fixed sized header followed by a number of variable length
>  records that describe different characteristics
>  of the device-- addressable regions, interrupts, etc.
>
>  0x0  +-------------+-------------+
>       |         magic             | u32  // identifies this as a vfio
> device file
>       +---------------------------+         and identifies the type of bus
>       |         version           | u32  // specifies the version of this
>       +---------------------------+
>       |         flags             | u32  // encodes any flags
>       +---------------------------+
>       |  dev info record 0        |
>       |    type                   | u32   // type of record
>       |    rec_len                | u32   // length in bytes of record
>       |                           |          (including record header)
>       |    flags                  | u32   // type specific flags
>       |    ...content...          |       // record content, which could
>       +---------------------------+       // include sub-records
>       |  dev info record 1        |
>       +---------------------------+
>       |  dev info record N        |
>       +---------------------------+
>
>  The device info records following the file header may have
>  the following record types each with content encoded in
>  a record specific way:
>
>  ------------+-------+------------------------------------------------------
>              |  type |
>   Region     |  num  | Description
>  ---------------------------------------------------------------------------
>  REGION           1    describes an addressable address range for the device
>  DTPATH           2    describes the device tree path for the device
>  DTINDEX          3    describes the index into the related device tree
>                          property (reg,ranges,interrupts,interrupt-map)
>  INTERRUPT        4    describes an interrupt for the device
>  PCI_CONFIG_SPACE 5    property identifying a region as PCI config space
>  PCI_BAR_INDEX    6    describes the BAR index for a PCI region
>  PHYS_ADDR        7    describes the physical address of the region
>  ---------------------------------------------------------------------------
>
> 2. Header
>
> The header is located at offset 0x0 in the device fd
> and has the following format:
>
>    struct devfd_header {
>        __u32 magic;
>        __u32 version;
>        __u32 flags;
>    };
>
>    The 'magic' field contains a magic value that will
>    identify the type bus the device is on.  Valid values
>    are:
>
>        0x70636900   // "pci" - PCI device
>        0x64740000   // "dt" - device tree (system bus)
>
> 3. Region
>
>  A REGION record an addressable address region for the device.
>
>    struct devfd_region {
>        __u32 type;   // must be 0x1
>        __u32 record_len;
>        __u32 flags;
>        __u64 offset; // seek offset to region from beginning
>                      // of file
>        __u64 len   ; // length of the region
>    };
>
>  The 'flags' field supports one flag:
>
>      IS_MMAPABLE
>
> 4. Device Tree Path (DTPATH)
>
>  A DTPATH record is a sub-record of a REGION and describes
>  the path to a device tree node for the region
>
>    struct devfd_dtpath {
>        __u32 type;   // must be 0x2
>        __u32 record_len;
>        __u64 char[]   ; // length of the region
>    };
>
> 5. Device Tree Index (DTINDEX)
>
>  A DTINDEX record is a sub-record of a REGION and specifies
>  the index into the resource list encoded in the associated
>  device tree property-- "reg", "ranges", "interrupts", or
>  "interrupt-map".
>
>    struct devfd_dtindex {
>        __u32 type;   // must be 0x3
>        __u32 record_len;
>        __u32 prop_type;
>        __u32 prop_index;  // index into the resource list
>    };
>
>    prop_type must have one of the follow values:
>       1   // "reg" property
>       2   // "ranges" property
>       3   // "interrupts" property
>       4   // "interrupts" property
>
>    Note: prop_index is not the byte offset into the property,
>    but the logical index.
>
> 6. Interrupts (INTERRUPT)
>
>  An INTERRUPT record describes one of a device's interrupts.
>  The handle field is an argument to VFIO_DEVICE_GET_IRQ_FD
>  which user space can use to receive device interrupts.
>
>    struct devfd_interrupts {
>        __u32 type;   // must be 0x4
>        __u32 record_len;
>        __u32 flags;
>        __u32 handle;  // parameter to VFIO_DEVICE_GET_IRQ_FD
>    };
>
> 7.  PCI Config Space (PCI_CONFIG_SPACE)
>
>    A PCI_CONFIG_SPACE record is a sub-record of a REGION record
>    and identifies the region as PCI configuration space.
>
>    struct devfd_cfgspace {
>        __u32 type;   // must be 0x5
>        __u32 record_len;
>        __u32 flags;
>    }
>
> 8.  PCI Bar Index (PCI_BAR_INDEX)
>
>    A PCI_BAR_INDEX record is a sub-record of a REGION record
>    and identifies the PCI BAR index for the region.
>
>    struct devfd_barindex {
>        __u32 type;   // must be 0x6
>        __u32 record_len;
>        __u32 flags;
>        __u32 bar_index;
>    }
>
> 9.  Physical Address (PHYS_ADDR)
>
>    A PHYS_ADDR record is a sub-record of a REGION record
>    and specifies the physical address of the region.
>
>    struct devfd_physaddr {
>        __u32 type;   // must be 0x7
>        __u32 record_len;
>        __u32 flags;
>        __u64 phys_addr;
>    }
>
> Regards,
> Stuart
>