[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH] docs/specs/fw_cfg.txt: Add fw_cfg documentation
From: |
Blue Swirl |
Subject: |
Re: [Qemu-devel] [PATCH] docs/specs/fw_cfg.txt: Add fw_cfg documentation |
Date: |
Mon, 4 Apr 2011 18:47:40 +0300 |
On Mon, Apr 4, 2011 at 9:46 AM, Jordan Justen <address@hidden> wrote:
> This initial version covers the generic portions of fw_cfg and
> the x86/x86-64 architecture specific portions of fw_cfg.
>
> Signed-off-by: Jordan Justen <address@hidden>
> ---
> docs/specs/fw_cfg.txt | 168
> +++++++++++++++++++++++++++++++++++++++++++++++++
> 1 files changed, 168 insertions(+), 0 deletions(-)
> create mode 100644 docs/specs/fw_cfg.txt
>
> diff --git a/docs/specs/fw_cfg.txt b/docs/specs/fw_cfg.txt
> new file mode 100644
> index 0000000..554ac48
> --- /dev/null
> +++ b/docs/specs/fw_cfg.txt
> @@ -0,0 +1,168 @@
> +
> += Hardware Interface =
> +
> +== Index Port ==
> +* Two bytes in width (guest native endianness)
> +* Write only
> +* Can be an I/O port and/or Memory-Mapped I/O
> +* Location is platform dependent
> +
> +A write to this port sets the index of a firmware configuration item
> +which can subsequently be accessed at the data port.
> +
> +Setting the index port will cause the data offset to be set to zero.
> +The data offset impacts which data is accessed via the data port, and
> +is explained below.
> +
> +Bit15 of the index value indicates if the configuration setting is
> +architecture specific. If bit15 of the index is 0, then the item is
> +a generic configuration item. If bit15 of the index is 1, then the
> +item is specific to a particular architecture. (In other words,
> +generic configuration items are accessed when the index is between
> +0x0000-0x7fff, and architecture specific configuration items are
> +accessed when the index is between 0x8000-0xffff.)
> +
> +Bit14 of the index value indicates if the configuration setting is
> +being written. If bit14 of the index is 0, then the item is only
> +being read, and all write access to the data port will be completely
> +ignored. If bit14 of the index is 1, then the item's data can be
> +written to by writing to the data port. (In other words,
> +configuration write mode is enabled when the index is between
> +0x4000-0x7fff or 0xc000-0xffff.)
> +
> +== Data Port ==
> +* One byte in width
> +* Read + Write
> +* Can be an I/O port and/or Memory-Mapped I/O
> +* Location is platform dependent
> +
> +The data port allows for access to an array of bytes for each firmware
> +configuration data item. This item is selected by a write to the
> +index port.
> +
> +Initially following a write to the index port, the data offset will
> +be set to zero. Each successful read or write to the data port will
> +cause the data offset to increment by one byte. There is only one
> +data offset value, and it will be incremented by accesses to any of
> +the I/O or MMIO data ports. A write access will not increment the
> +data offset if the selected index did not have bit14 set.
> +
> +Each firmware configuration item has a maximum length of data
> +associated with the item. After the data offset has passed the
> +end of this maximum data length, then any reads will return a data
> +value of 0x00, and all writes will be ignored.
> +
> +A read of the data port will return the current byte of the firmware
> +configuration item.
> +
> +A write of the data port will set the current byte of the firmware
> +configuration item. A write access will not impact the firmware
> +configuration data if the selected index did not have bit14 set.
> +
> +== x86, x86-64 Ports ==
> +
> +I/O Index Port: 0x510
> +I/O Data Port: 0x511
> +MMIO Index Port: N/A
> +MMIO Data Port: N/A
This also applies to sun4u. PPC uses MMIO 0xf000051[01] and sun4m
0xd0000051[01]. Other architectures don't use the device.
> +
> += Firmware Configuration Items =
> +
> +== Ranges ==
> +
> +There are up to 0x4000 generic firmware configuration items, and up to
> +0x4000 architecturally specific firmware configuration items.
> +
> +Index Port Range Range Usage
> +---------------- -----------
> +0x0000 - 0x3fff Generic Items (0x0000 - 0x3fff) (Read-only)
> +0x4000 - 0x7fff Generic Items (0x0000 - 0x3fff) (Read+Write)
> +0x8000 - 0xbfff Architecture Specific Items (0x0000 - 0x3fff) (Read-only)
> +0xc000 - 0xffff Architecture Specific Items (0x0000 - 0x3fff) (Read+Write)
> +
> +== Data Items Format ==
> +
> +uint8_t : 8-bit unsigned integer
> +uint16_t: 16-bit unsigned integer
> +uint32_t: 32-bit unsigned integer
> +uint64_t: 64-bit unsigned integer
> +n bytes : byte array of length n
> +array : byte array of a format specific size
> +string : null byte terminated ascii string
> +
> +All integer data is accessed with the least significant byte first and
> +then proceeding to more significant bytes on subsequent accesses.
Due to properties of little endian data and because QEMU supplies
zeros for out of range access, any integers are automatically zero
extended. It is possible for BIOS to read 64 bit integers even when
QEMU supplies 32 bit data (but vice versa will not work). So I
wouldn't emphasize the data sizes.
> +
> +== Generic Items ==
> +
> +Index Data Type Data Meaning
> +----- --------- ------------
> +0x00 4 bytes Signature - 'Q', 'E', 'M', 'U'
> +0x01 uint32_t ID
This is used as interface version, currently 1 is used.
BIOS implementations must check the signature and ID.
> +0x02 16 bytes System UUID
> +0x03 uint64_t RAM Size
> +0x04 uint16_t 0 indicates graphics mode, otherwise non-graphics mode
> +0x05 uint16_t The number of SMP CPUs
> +0x06 uint16_t Machine ID
> +0x07 uint32_t Kernel Address
> +0x08 uint32_t Kernel Size
> +0x09 string Kernel command line
> +0x0a uint32_t Initrd Address
> +0x0b uint32_t Initrd Size
> +0x0c uint16_t Boot Device
> +0x0d array NUMA Data
> +0x0e uint16_t Boot Menu
> +0x0f uint16_t The maximum number of CPUs (hotpluggable)
> +0x10 uint32_t Kernel Entry
> +0x11 array Kernel Data
> +0x12 array Initrd Data
> +0x13 uint32_t Command Line Address
> +0x14 uint32_t Command Line Size
> +0x15 string Command Line Data
> +0x16 uint32_t Setup Address
> +0x17 uint32_t Setup Size
> +0x18 array Setup Data
> +0x19 array File Directory
> +
> +=== File Directory Structure ===
> +
> +Note: Integers in the file directory structure (index 0x19) are stored
> +in big-endian format regardless of the host or guest endianness. This
This was a design mistake. LE should have been used.
> +means that the first byte read of the integer is its most significant
> +byte.
> +
> +The structure begins with a uint32_t in big-endian format.
> +This number indicates the number of files that are available.
> +
> +Offset Data Type Data Meaning
> +------ ------------ ------------
> +0x00 uint32_t(be) File count
> +0x04 array Array of file instance structures. The total length
> + of this array is 64-bytes * file_count.
> +
> +As shown above, following the initial file count uint32_t,
> +there is an array of structures. Each structure is 64-bytes
> +in size. The number of instances of this structure in the
> +array is given by the initial uint32_t data value read.
> +Each structure within the array has this format:
> +
> +Offset Data Type Data Meaning
> +------ ------------ ------------
> +0x00 uint32_t(be) File size
> +0x04 uint16_t(be) Firmware configuration entry index for file data
> +0x06 2 bytes 2 reserved bytes
> +0x08 56 bytes File name as a null terminated ascii string
Currently used file names could be listed here.
> +
> +== x86, x86-64 Architecture Items ==
> +
> +As architecture specific items, these items should be accessed
> +starting at 0x8000 for reading or 0xc000 for reading and writing.
> +
> +Index Data Type Data Meaning
> +----- --------- ------------
> +0x00 array ACPI Tables Data
> +0x01 array SMBIOS Data
> +0x02 uint8_t IRQ0 Override
> +0x03 array E820 Table
> +0x04 array HPET Data
> +
Sun4m, sun4u and PPC pass graphics parameters and PPC also passes KVM
parameters using architecture specific items.