[Qemu-devel] [PULL for-2.3 0/1] fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

[Qemu-devel] [PULL for-2.3 0/1] fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

[Gerd Hoffmann]

  Hi,

Damn, wanted to sent this out last week, then forgot, so it missed -rc3.
But it is a documentation-only change, so it should still be fine for
2.3, right?

please pull,
  Gerd

The following changes since commit b8df9208f357d2b36e1b19634aea973618dc7ba8:

  Update version for v2.3.0-rc3 release (2015-04-13 17:35:44 +0100)

are available in the git repository at:

  git://git.kraxel.org/qemu tags/pull-fwcfg-20150414-1

for you to fetch changes up to 6cec43e178cde38a3eac43a2cd741ce741b10f36:

  fw_cfg: add documentation file (docs/specs/fw_cfg.txt) (2015-04-14 13:21:08 +0200)

----------------------------------------------------------------
fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

----------------------------------------------------------------
Gabriel L. Somlo (1):
      fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

 docs/specs/fw_cfg.txt | 205 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 docs/specs/fw_cfg.txt

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

[Gerd Hoffmann]

From: "Gabriel L. Somlo" <somlo@cmu.edu>

This document covers the guest-side hardware interface, as
well as the host-side programming API of QEMU's firmware
configuration (fw_cfg) device.

Signed-off-by: Jordan Justen <jordan.l.justen@intel.com>
Signed-off-by: Gabriel Somlo <somlo@cmu.edu>
Reviewed-by: Laszlo Ersek <lersek@redhat.com>
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 docs/specs/fw_cfg.txt | 205 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 205 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..6accd92
--- /dev/null
+++ b/docs/specs/fw_cfg.txt
@@ -0,0 +1,205 @@
+QEMU Firmware Configuration (fw_cfg) Device
+===========================================
+
+= Guest-side Hardware Interface =
+
+This hardware interface allows the guest to retrieve various data items
+(blobs) that can influence how the firmware configures itself, or may
+contain tables to be installed for the guest OS. Examples include device
+boot order, ACPI and SMBIOS tables, virtual machine UUID, SMP and NUMA
+information, kernel/initrd images for direct (Linux) kernel booting, etc.
+
+== Selector (Control) Register ==
+
+* Write only
+* Location: platform dependent (IOport or MMIO)
+* Width: 16-bit
+* Endianness: little-endian (if IOport), or big-endian (if MMIO)
+
+A write to this register sets the index of a firmware configuration
+item which can subsequently be accessed via the data register.
+
+Setting the selector register will cause the data offset to be set
+to zero. The data offset impacts which data is accessed via the data
+register, and is explained below.
+
+Bit14 of the selector register indicates whether the configuration
+setting is being written. A value of 0 means the item is only being
+read, and all write access to the data port will be ignored. A value
+of 1 means the item's data can be overwritten by writes to the data
+register. In other words, configuration write mode is enabled when
+the selector value is between 0x4000-0x7fff or 0xc000-0xffff.
+
+NOTE: As of QEMU v2.4, writes to the fw_cfg data register are no
+      longer supported, and will be ignored (treated as no-ops)!
+
+Bit15 of the selector register indicates whether the configuration
+setting is architecture specific. A value of 0 means the item is a
+generic configuration item. A value of 1 means the item is specific
+to a particular architecture. In other words, generic configuration
+items are accessed with a selector value between 0x0000-0x7fff, and
+architecture specific configuration items are accessed with a selector
+value between 0x8000-0xffff.
+
+== Data Register ==
+
+* Read/Write (writes ignored as of QEMU v2.4)
+* Location: platform dependent (IOport [*] or MMIO)
+* Width: 8-bit (if IOport), 8/16/32/64-bit (if MMIO)
+* Endianness: string-preserving
+
+[*] On platforms where the data register is exposed as an IOport, its
+port number will always be one greater than the port number of the
+selector register. In other words, the two ports overlap, and can not
+be mapped separately.
+
+The data register allows access to an array of bytes for each firmware
+configuration data item. The specific item is selected by writing to
+the selector register, as described above.
+
+Initially following a write to the selector register, the data offset
+will be set to zero. Each successful access to the data register will
+increment the data offset by the appropriate access width.
+
+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.
+
+An N-byte wide read of the data register will return the next available
+N bytes of the selected firmware configuration item, as a substring, in
+increasing address order, similar to memcpy().
+
+== Register Locations ==
+
+=== x86, x86_64 Register Locations ===
+
+Selector Register IOport: 0x510
+Data Register IOport:     0x511
+
+== Firmware Configuration Items ==
+
+=== Signature (Key 0x0000, FW_CFG_SIGNATURE) ===
+
+The presence of the fw_cfg selector and data registers can be verified
+by selecting the "signature" item using key 0x0000 (FW_CFG_SIGNATURE),
+and reading four bytes from the data register. If the fw_cfg device is
+present, the four bytes read will contain the characters "QEMU".
+
+=== Revision (Key 0x0001, FW_CFG_ID) ===
+
+A 32-bit little-endian unsigned int, this item is used as an interface
+revision number, and is currently set to 1 by QEMU when fw_cfg is
+initialized.
+
+=== File Directory (Key 0x0019, FW_CFG_FILE_DIR) ===
+
+Firmware configuration items stored at selector keys 0x0020 or higher
+(FW_CFG_FILE_FIRST or higher) have an associated entry in a directory
+structure, which makes it easier for guest-side firmware to identify
+and retrieve them. The format of this file directory (from fw_cfg.h in
+the QEMU source tree) is shown here, slightly annotated for clarity:
+
+struct FWCfgFiles {		/* the entire file directory fw_cfg item */
+    uint32_t count;		/* number of entries, in big-endian format */
+    struct FWCfgFile f[];	/* array of file entries, see below */
+};
+
+struct FWCfgFile {		/* an individual file entry, 64 bytes total */
+    uint32_t size;		/* size of referenced fw_cfg item, big-endian */
+    uint16_t select;		/* selector key of fw_cfg item, big-endian */
+    uint16_t reserved;
+    char name[56];		/* fw_cfg item name, NUL-terminated ascii */
+};
+
+=== All Other Data Items ===
+
+Please consult the QEMU source for the most up-to-date and authoritative
+list of selector keys and their respective items' purpose and format.
+
+=== Ranges ===
+
+Theoretically, there may be up to 0x4000 generic firmware configuration
+items, and up to 0x4000 architecturally specific ones.
+
+Selector Reg.    Range Usage
+---------------  -----------
+0x0000 - 0x3fff  Generic (0x0000 - 0x3fff, RO)
+0x4000 - 0x7fff  Generic (0x0000 - 0x3fff, RW, ignored in QEMU v2.4+)
+0x8000 - 0xbfff  Arch. Specific (0x0000 - 0x3fff, RO)
+0xc000 - 0xffff  Arch. Specific (0x0000 - 0x3fff, RW, ignored in v2.4+)
+
+In practice, the number of allowed firmware configuration items is given
+by the value of FW_CFG_MAX_ENTRY (see fw_cfg.h).
+
+= Host-side API =
+
+The following functions are available to the QEMU programmer for adding
+data to a fw_cfg device during guest initialization (see fw_cfg.h for
+each function's complete prototype):
+
+== fw_cfg_add_bytes() ==
+
+Given a selector key value, starting pointer, and size, create an item
+as a raw "blob" of the given size, available by selecting the given key.
+The data referenced by the starting pointer is only linked, NOT copied,
+into the data structure of the fw_cfg device.
+
+== fw_cfg_add_string() ==
+
+Instead of a starting pointer and size, this function accepts a pointer
+to a NUL-terminated ascii string, and inserts a newly allocated copy of
+the string (including the NUL terminator) into the fw_cfg device data
+structure.
+
+== fw_cfg_add_iXX() ==
+
+Insert an XX-bit item, where XX may be 16, 32, or 64. These functions
+will convert a 16-, 32-, or 64-bit integer to little-endian, then add
+a dynamically allocated copy of the appropriately sized item to fw_cfg
+under the given selector key value.
+
+== fw_cfg_add_file() ==
+
+Given a filename (i.e., fw_cfg item name), starting pointer, and size,
+create an item as a raw "blob" of the given size. Unlike fw_cfg_add_bytes()
+above, the next available selector key (above 0x0020, FW_CFG_FILE_FIRST)
+will be used, and a new entry will be added to the file directory structure
+(at key 0x0019), containing the item name, blob size, and automatically
+assigned selector key value. The data referenced by the starting pointer
+is only linked, NOT copied, into the fw_cfg data structure.
+
+== fw_cfg_add_file_callback() ==
+
+Like fw_cfg_add_file(), but additionally sets pointers to a callback
+function (and opaque argument), which will be executed host-side by
+QEMU each time a byte is read by the guest from this particular item.
+
+NOTE: The callback function is given the opaque argument set by
+fw_cfg_add_file_callback(), but also the current data offset,
+allowing it the option of only acting upon specific offset values
+(e.g., 0, before the first data byte of the selected item is
+returned to the guest).
+
+== fw_cfg_modify_file() ==
+
+Given a filename (i.e., fw_cfg item name), starting pointer, and size,
+completely replace the configuration item referenced by the given item
+name with the new given blob. If an existing blob is found, its
+callback information is removed, and a pointer to the old data is
+returned to allow the caller to free it, helping avoid memory leaks.
+If a configuration item does not already exist under the given item
+name, a new item will be created as with fw_cfg_add_file(), and NULL
+is returned to the caller. In any case, the data referenced by the
+starting pointer is only linked, NOT copied, into the fw_cfg data
+structure.
+
+== fw_cfg_add_callback() ==
+
+Like fw_cfg_add_bytes(), but additionally sets pointers to a callback
+function (and opaque argument), which will be executed host-side by
+QEMU each time a guest-side write operation to this particular item
+completes fully overwriting the item's data.
+
+NOTE: This function is deprecated, and will be completely removed
+starting with QEMU v2.4.
-- 
1.8.3.1

Re: [Qemu-devel] [PULL for-2.3 0/1] fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

[Peter Maydell]

On 14 April 2015 at 12:27, Gerd Hoffmann <kraxel@redhat.com> wrote:
>   Hi,
>
> Damn, wanted to sent this out last week, then forgot, so it missed -rc3.
> But it is a documentation-only change, so it should still be fine for
> 2.3, right?

My inclination is to only put this in if something else turns
up that we must fix in rc3. Otherwise I would want to just release
2.3 with our current tree.

thanks
-- PMM

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

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1278 bytes --]

On 04/14/2015 05:27 AM, Gerd Hoffmann wrote:
> From: "Gabriel L. Somlo" <somlo@cmu.edu>
> 
> This document covers the guest-side hardware interface, as
> well as the host-side programming API of QEMU's firmware
> configuration (fw_cfg) device.
> 
> Signed-off-by: Jordan Justen <jordan.l.justen@intel.com>
> Signed-off-by: Gabriel Somlo <somlo@cmu.edu>
> Reviewed-by: Laszlo Ersek <lersek@redhat.com>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  docs/specs/fw_cfg.txt | 205 ++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 205 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..6accd92
> --- /dev/null
> +++ b/docs/specs/fw_cfg.txt
> @@ -0,0 +1,205 @@
> +QEMU Firmware Configuration (fw_cfg) Device
> +===========================================
> +
> += Guest-side Hardware Interface =

No explicit copyright, so it inherits the default GPLv2+ from the top
level.  I've been encouraging new documents to include explicit
copyright/license for the avoidance of doubt, where it makes sense.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

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

[Gabriel L. Somlo]

Hi Eric,

On Tue, Apr 14, 2015 at 06:29:45AM -0600, Eric Blake wrote:
> On 04/14/2015 05:27 AM, Gerd Hoffmann wrote:
> > From: "Gabriel L. Somlo" <somlo@cmu.edu>
> > 
> > This document covers the guest-side hardware interface, as
> > well as the host-side programming API of QEMU's firmware
> > configuration (fw_cfg) device.
> > 
> > Signed-off-by: Jordan Justen <jordan.l.justen@intel.com>
> > Signed-off-by: Gabriel Somlo <somlo@cmu.edu>
> > Reviewed-by: Laszlo Ersek <lersek@redhat.com>
> > Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> > ---
> 
> No explicit copyright, so it inherits the default GPLv2+ from the top
> level.  I've been encouraging new documents to include explicit
> copyright/license for the avoidance of doubt, where it makes sense.

This started out with Jordan's 2011 patch:

http://lists.gnu.org/archive/html/qemu-devel/2011-04/msg00238.html

which I picked up and re-submitted with some moderate editing to
bring it in line with the current state of fw_cfg, work in lots of
good suggestions from Laszlo, add documentation for the host-side
API, etc.

The original patch didn't have a copyright line either, so at this
point I believe the default is preferable (path of least resistance).

Alternatively, if Jordan would like to add a copyright line to the
top of the file (as the original author), I have no problem with that
whatsoever.

Thanks much,
--Gabriel

Re: [Qemu-devel] [PULL for-2.3 0/1] fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

[Michael S. Tsirkin]

On Tue, Apr 14, 2015 at 12:34:02PM +0100, Peter Maydell wrote:
> On 14 April 2015 at 12:27, Gerd Hoffmann <kraxel@redhat.com> wrote:
> >   Hi,
> >
> > Damn, wanted to sent this out last week, then forgot, so it missed -rc3.
> > But it is a documentation-only change, so it should still be fine for
> > 2.3, right?
> 
> My inclination is to only put this in if something else turns
> up that we must fix in rc3. Otherwise I would want to just release
> 2.3 with our current tree.
> 
> thanks
> -- PMM

Looks like there's a vhost bug that might justify making
code changes :( I posted the patch fixing this, and Cc'd you -
patch is under test.

-- 
MST

Re: [Qemu-devel] [PULL for-2.3 0/1] fw_cfg: add documentation file (docs/specs/fw_cfg.txt)

[Peter Maydell]

On 14 April 2015 at 12:34, Peter Maydell <peter.maydell@linaro.org> wrote:
> On 14 April 2015 at 12:27, Gerd Hoffmann <kraxel@redhat.com> wrote:
>>   Hi,
>>
>> Damn, wanted to sent this out last week, then forgot, so it missed -rc3.
>> But it is a documentation-only change, so it should still be fine for
>> 2.3, right?
>
> My inclination is to only put this in if something else turns
> up that we must fix in rc3. Otherwise I would want to just release
> 2.3 with our current tree.

Well, we got some other RC bugs, so I've applied this.

-- PMM