[PATCH v4 4/4] devicetree: update documentation for fw_cfg ARM bindings
From: Gabriel Somlo <somlo@cmu.edu> Remove redundant details from Documentation/devicetree/bindings/arm/fw-cfg.txt, and replace them with a pointer to the more comprehensive fw_cfg documentation privided by Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg, leaving the specific ARM DTB node description in place. Signed-off-by: Gabriel Somlo <somlo@cmu.edu> Cc: Laszlo Ersek <lersek@redhat.com> --- Documentation/devicetree/bindings/arm/fw-cfg.txt | 37 ++---------------------- 1 file changed, 2 insertions(+), 35 deletions(-) diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt index 953fb64..7aeb48a 100644 --- a/Documentation/devicetree/bindings/arm/fw-cfg.txt +++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt @@ -11,43 +11,10 @@ QEMU exposes the control and data register to ARM guests as memory mapped registers; their location is communicated to the guest's UEFI firmware in the DTB that QEMU places at the bottom of the guest's DRAM. -The guest writes a selector value (a key) to the selector register, and then -can read the corresponding data (produced by QEMU) via the data register. If -the selected entry is writable, the guest can rewrite it through the data -register. -The selector register takes keys in big endian byte order. +For a comprehensive description of the behavior of fw_cfg, please see +Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg. -The data register allows accesses with 8, 16, 32 and 64-bit width (only at -offset 0 of the register). Accesses larger than a byte are interpreted as -arrays, bundled together only for better performance. The bytes constituting -such a word, in increasing address order, correspond to the bytes that would -have been transferred by byte-wide accesses in chronological order. - -The interface allows guest firmware to download various parameters and blobs -that affect how the firmware works and what tables it installs for the guest -OS. For example, boot order of devices, ACPI tables, SMBIOS tables, kernel and -initrd images for direct kernel booting, virtual machine UUID, SMP information, -virtual NUMA topology, and so on. - -The authoritative registry of the valid selector values and their meanings is -the QEMU source code; the structure of the data blobs corresponding to the -individual key values is also defined in the QEMU source code. - -The presence of the registers can be verified by selecting the "signature" blob -with key 0x0000, and reading four bytes from the data register. The returned -signature is "QEMU". - -The outermost protocol (involving the write / read sequences of the control and -data registers) is expected to be versioned, and/or described by feature bits. -The interface revision / feature bitmap can be retrieved with key 0x0001. The -blob to be read from the data register has size 4, and it is to be interpreted -as a uint32_t value in little endian byte order. The current value -(corresponding to the above outer protocol) is zero. - -The guest kernel is not expected to use these registers (although it is -certainly allowed to); the device tree bindings are documented here because -this is where device tree bindings reside in general. Required properties: -- 2.4.3
On Fri, Nov 13, 2015 at 10:03:55PM -0500, Gabriel L. Somlo wrote:
From: Gabriel Somlo <somlo@cmu.edu>
Remove redundant details from Documentation/devicetree/bindings/arm/fw-cfg.txt, and replace them with a pointer to the more comprehensive fw_cfg documentation privided by Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg, leaving the specific ARM DTB node description in place.
We generally don't want DT docs to depend on other kernel documentation. That will make separating them harder.
Signed-off-by: Gabriel Somlo <somlo@cmu.edu> Cc: Laszlo Ersek <lersek@redhat.com> --- Documentation/devicetree/bindings/arm/fw-cfg.txt | 37 ++---------------------- 1 file changed, 2 insertions(+), 35 deletions(-)
diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt index 953fb64..7aeb48a 100644 --- a/Documentation/devicetree/bindings/arm/fw-cfg.txt +++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt @@ -11,43 +11,10 @@ QEMU exposes the control and data register to ARM guests as memory mapped registers; their location is communicated to the guest's UEFI firmware in the DTB that QEMU places at the bottom of the guest's DRAM.
-The guest writes a selector value (a key) to the selector register, and then -can read the corresponding data (produced by QEMU) via the data register. If -the selected entry is writable, the guest can rewrite it through the data -register.
-The selector register takes keys in big endian byte order. +For a comprehensive description of the behavior of fw_cfg, please see +Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg.
-The data register allows accesses with 8, 16, 32 and 64-bit width (only at -offset 0 of the register). Accesses larger than a byte are interpreted as -arrays, bundled together only for better performance. The bytes constituting -such a word, in increasing address order, correspond to the bytes that would -have been transferred by byte-wide accesses in chronological order. - -The interface allows guest firmware to download various parameters and blobs -that affect how the firmware works and what tables it installs for the guest -OS. For example, boot order of devices, ACPI tables, SMBIOS tables, kernel and -initrd images for direct kernel booting, virtual machine UUID, SMP information, -virtual NUMA topology, and so on. - -The authoritative registry of the valid selector values and their meanings is -the QEMU source code; the structure of the data blobs corresponding to the -individual key values is also defined in the QEMU source code. - -The presence of the registers can be verified by selecting the "signature" blob -with key 0x0000, and reading four bytes from the data register. The returned -signature is "QEMU". - -The outermost protocol (involving the write / read sequences of the control and -data registers) is expected to be versioned, and/or described by feature bits. -The interface revision / feature bitmap can be retrieved with key 0x0001. The -blob to be read from the data register has size 4, and it is to be interpreted -as a uint32_t value in little endian byte order. The current value -(corresponding to the above outer protocol) is zero. - -The guest kernel is not expected to use these registers (although it is -certainly allowed to); the device tree bindings are documented here because -this is where device tree bindings reside in general.
Required properties:
-- 2.4.3
On 15/11/2015 03:07, Rob Herring wrote:
We generally don't want DT docs to depend on other kernel documentation.
DT docs do not contain a copy of the data sheets, either. There is no reason to say how to use the device (and even then, only doing so partially) in the DT docs. Paolo
On Mon, Nov 16, 2015 at 09:38:18AM +0100, Paolo Bonzini wrote:
On 15/11/2015 03:07, Rob Herring wrote:
We generally don't want DT docs to depend on other kernel documentation.
DT docs do not contain a copy of the data sheets, either. There is no reason to say how to use the device (and even then, only doing so partially) in the DT docs.
I believe "Documentation/devicetree/bindings/arm/fw-cfg.txt" was added by Laszlo (via commit 53275a61) mainly to document the (base,size) DT node for ARM fw_cfg register set (based on the idea that Documentation/devicetree/... is the authoritative place to park DT node information like that. The additional bits about how fw_cfg works were added for context, since at the time the kernel itself didn't have anything else to do with fw_cfg. Since the sysfs driver I'm proposing (to allow fw_cfg data to be viewed from userspace) works on a wider set of architectures (x86, ARM, ppc/mac and sun4*), documentation on fw_cfg behavior belongs in a more cross-platform location, such as Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg. So Documentation/devicetree/bindings/arm/fw-cfg.txt should probably be limited to specifying the DT node details for ARM only. I figured it'd be nice to point at the new interface doc file to compensate for removing that information, but I'd be happy to not do that and just remove the redundant bits. Probably some of the stuff I just wrote should go into the commit log for the next version of the patch :) Thanks much, --Gabriel
On Mon, Nov 16, 2015 at 2:38 AM, Paolo Bonzini <pbonzini@redhat.com> wrote:
On 15/11/2015 03:07, Rob Herring wrote:
We generally don't want DT docs to depend on other kernel documentation.
DT docs do not contain a copy of the data sheets, either. There is no reason to say how to use the device (and even then, only doing so partially) in the DT docs.
The difference is datasheets apply to all OS's, kernel documentation does not. In theory at least this could be used for other OS's, right? Perhaps QEMU is the right place to thoroughly describe this and DT and sysfs docs can refer to it. Rob
On Tue, Nov 17, 2015 at 04:14:42PM -0600, Rob Herring wrote:
On Mon, Nov 16, 2015 at 2:38 AM, Paolo Bonzini <pbonzini@redhat.com> wrote:
On 15/11/2015 03:07, Rob Herring wrote:
We generally don't want DT docs to depend on other kernel documentation.
DT docs do not contain a copy of the data sheets, either. There is no reason to say how to use the device (and even then, only doing so partially) in the DT docs.
The difference is datasheets apply to all OS's, kernel documentation does not. In theory at least this could be used for other OS's, right?
Perhaps QEMU is the right place to thoroughly describe this and DT and sysfs docs can refer to it.
So, leave only ARM/DT specifc details in Documentation/devicetree/bindings/arm/fw-cfg.txt, and rework the fw_cfg sysfs patch (1/4) to only document sysfs specific details in Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg ? The fw_cfg "datasheet" does exist in QEMU already, so there is something to point at from either/both of the above. Thanks, --Gabriel
On 17/11/2015 23:14, Rob Herring wrote:
On Mon, Nov 16, 2015 at 2:38 AM, Paolo Bonzini <pbonzini@redhat.com> wrote:
On 15/11/2015 03:07, Rob Herring wrote:
We generally don't want DT docs to depend on other kernel documentation.
DT docs do not contain a copy of the data sheets, either. There is no reason to say how to use the device (and even then, only doing so partially) in the DT docs.
The difference is datasheets apply to all OS's, kernel documentation does not. In theory at least this could be used for other OS's, right?
Would be nice indeed, as it's part of their intended purpose. For now we have to shoehorn things into linux-only stuff (like initrd) because well, nobody cares enough about NetBSD to compile U-Boot with its internal API, so let alone adding custom Haiku code. And of course, for things linux doesn't care about (like framebuffer description) then we're stuck trying to guess where it's at and writing drivers for our bootloader. So if at least people were considering they aren't the only users of this, that'd make life better for everyone.
Perhaps QEMU is the right place to thoroughly describe this and DT and sysfs docs can refer to it.
The brilliant idea of FDT was that we could have a canonical source and blob for it where people could send patches, but of course Linux and BSD freaks disagreed, so you now find Linux-flavoured DTs for rPi and other things, as well as BSD versions. Please, at least get the binding documentation for this unique and usable for everyone! François.
On Wed, Nov 18, 2015 at 02:04:24PM +0100, François Revol wrote:
On 17/11/2015 23:14, Rob Herring wrote:
On Mon, Nov 16, 2015 at 2:38 AM, Paolo Bonzini <pbonzini@redhat.com> wrote:
On 15/11/2015 03:07, Rob Herring wrote:
We generally don't want DT docs to depend on other kernel documentation.
DT docs do not contain a copy of the data sheets, either. There is no reason to say how to use the device (and even then, only doing so partially) in the DT docs.
The difference is datasheets apply to all OS's, kernel documentation does not. In theory at least this could be used for other OS's, right?
Would be nice indeed, as it's part of their intended purpose.
For now we have to shoehorn things into linux-only stuff (like initrd) because well, nobody cares enough about NetBSD to compile U-Boot with its internal API, so let alone adding custom Haiku code.
And of course, for things linux doesn't care about (like framebuffer description) then we're stuck trying to guess where it's at and writing drivers for our bootloader.
So if at least people were considering they aren't the only users of this, that'd make life better for everyone.
Perhaps QEMU is the right place to thoroughly describe this and DT and sysfs docs can refer to it.
The brilliant idea of FDT was that we could have a canonical source and blob for it where people could send patches, but of course Linux and BSD freaks disagreed, so you now find Linux-flavoured DTs for rPi and other things, as well as BSD versions.
Please, at least get the binding documentation for this unique and usable for everyone!
That would be 'docs/specs/fw_cfg.txt' in the QEMU source tree. I will avoid cut'n'pasting anything from there into either the proposed Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg (leaving only the sysfs specific bits in there), and also remove any redundant bits from Documentation/devicetree/bindings/arm/fw-cfg.txt. I'm inclined to add (in v5) a mention of 'qemu:docs/specs/fw_cfg.txt' to both the proposed fw_cfg sysfs doc file, and to the existing fw_cfg arm/dt node doc file, unless I get strong objections against doing so... :) Thanks, --Gabriel
participants (4)
-
François Revol -
Gabriel L. Somlo -
Paolo Bonzini -
Rob Herring