[Qemu-devel] [PATCH 1/6] fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

["Gabriel L. Somlo" <somlo@cmu.edu>]

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.justen@intel.com>
Signed-off-by: Gabriel Somlo <somlo@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