This document covers the generic portions of fw_cfg as well as the x86/x86-64 architecture specific components.
Signed-off-by: Jordan Justen <jordan.l.jus...@intel.com> Signed-off-by: Gabriel Somlo <so...@cmu.edu> --- This is a resubmission of Jordan's patch from back when: http://lists.gnu.org/archive/html/qemu-devel/2011-04/msg00238.html My own signed-off-by may or may not belong in the commit log, not quite 100% sure what the etiquette is. Please apply with or without it :) Thanks, Gabriel docs/specs/fw_cfg.txt | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 167 insertions(+) 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..7d156b7 --- /dev/null +++ b/docs/specs/fw_cfg.txt @@ -0,0 +1,167 @@ + += 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 + += 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. + +== Generic Items == + +Index Data Type Data Meaning +----- --------- ------------ +0x00 4 bytes Signature - 'Q', 'E', 'M', 'U' +0x01 uint32_t 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 +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 + +== 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 -- 2.1.0
