From patchwork Mon Mar 16 14:15:00 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Gabriel L. Somlo" X-Patchwork-Id: 450585 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [IPv6:2001:4830:134:3::11]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id EA1B91400D5 for ; Tue, 17 Mar 2015 01:16:03 +1100 (AEDT) Received: from localhost ([::1]:49563 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YXVoG-00066j-Og for incoming@patchwork.ozlabs.org; Mon, 16 Mar 2015 10:16:00 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:34820) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YXVnY-000560-1j for qemu-devel@nongnu.org; Mon, 16 Mar 2015 10:15:20 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1YXVnT-0003FK-16 for qemu-devel@nongnu.org; Mon, 16 Mar 2015 10:15:15 -0400 Received: from relay-05.andrew.cmu.edu ([128.2.157.12]:47905 helo=relay.andrew.cmu.edu) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1YXVnS-0003Ep-SK for qemu-devel@nongnu.org; Mon, 16 Mar 2015 10:15:10 -0400 Received: from HEDWIG.ini.cmu.edu (HEDWIG.INI.CMU.EDU [128.2.16.51]) by relay.andrew.cmu.edu (8.14.7/8.14.7) with ESMTP id t2GEF5u4008182; Mon, 16 Mar 2015 10:15:05 -0400 From: "Gabriel L. Somlo" To: qemu-devel@nongnu.org Date: Mon, 16 Mar 2015 10:15:00 -0400 Message-Id: <1426515305-17766-2-git-send-email-somlo@cmu.edu> X-Mailer: git-send-email 2.1.0 In-Reply-To: <1426515305-17766-1-git-send-email-somlo@cmu.edu> References: <1426515305-17766-1-git-send-email-somlo@cmu.edu> X-Scanned-By: MIMEDefang 2.74 on 128.2.157.12 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x X-Received-From: 128.2.157.12 Cc: matt.fleming@intel.com, rjones@redhat.com, jordan.l.justen@intel.com, gleb@cloudius-systems.com, mdroth@linux.vnet.ibm.com, gsomlo@gmail.com, kraxel@redhat.com, pbonzini@redhat.com, lersek@redhat.com Subject: [Qemu-devel] [PATCH 1/6] fw_cfg: add documentation file (docs/specs/fw_cfg.txt) X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org This document covers the generic portions of fw_cfg as well as the x86/x86-64 architecture specific components. Signed-off-by: Jordan Justen Signed-off-by: Gabriel Somlo --- 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