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 <b08...@gmail.com> 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
>
