[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH 1/6] fw_cfg: add documentation file (docs/specs/fw_c
From: |
Gabriel L. Somlo |
Subject: |
[Qemu-devel] [PATCH 1/6] fw_cfg: add documentation file (docs/specs/fw_cfg.txt) |
Date: |
Mon, 16 Mar 2015 10:15:00 -0400 |
This document covers the generic portions of fw_cfg as well as
the x86/x86-64 architecture specific components.
Signed-off-by: Jordan Justen <address@hidden>
Signed-off-by: Gabriel Somlo <address@hidden>
---
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