From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([140.186.70.92]:53074) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R20sD-0006rS-I6 for qemu-devel@nongnu.org; Fri, 09 Sep 2011 09:12:06 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1R20s7-0005kP-Gz for qemu-devel@nongnu.org; Fri, 09 Sep 2011 09:12:01 -0400 Received: from mail-qw0-f67.google.com ([209.85.216.67]:59743) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1R20s7-0005kC-E4 for qemu-devel@nongnu.org; Fri, 09 Sep 2011 09:11:55 -0400 Received: by qwi2 with SMTP id 2so47907qwi.10 for ; Fri, 09 Sep 2011 06:11:54 -0700 (PDT) MIME-Version: 1.0 Date: Fri, 9 Sep 2011 08:11:54 -0500 Message-ID: From: Stuart Yoder Content-Type: text/plain; charset=ISO-8859-1 Subject: [Qemu-devel] RFC [v2]: vfio / device assignment -- layout of device fd files List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: alex.williamson@redhat.com, Scott Wood , qemu-devel@nongnu.org, agraf@suse.de, kvm@vger.kernel.org, avi@redhat.com, anthony@codemonkey.ws 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