Date: Mon, 23 Nov 2015 11:47:39 -0500
From: "Gabriel L. Somlo" <somlo@cmu.edu>
To: Laszlo Ersek <lersek@redhat.com>
Cc: gregkh@linuxfoundation.org, robh+dt@kernel.org, pawel.moll@arm.com,
        mark.rutland@arm.com, ijc+devicetree@hellion.org.uk,
        galak@codeaurora.org, arnd@arndb.de, ralf@linux-mips.org,
        rmk+kernel@arm.linux.org.uk, eric@anholt.net, hanjun.guo@linaro.org,
        zajec5@gmail.com, sudeep.holla@arm.com, agross@codeaurora.org,
        linux-api@vger.kernel.org, linux-kernel@vger.kernel.org,
        devicetree@vger.kernel.org, qemu-devel@nongnu.org,
        jordan.l.justen@intel.com, mst@redhat.com, peter.maydell@linaro.org,
        leif.lindholm@linaro.org, ard.biesheuvel@linaro.org,
        pbonzini@redhat.com, kraxel@redhat.com, luto@amacapital.net,
        stefanha@gmail.com, revol@free.fr
Subject: Re: [PATCH v5 4/4] devicetree: update documentation for fw_cfg ARM
 bindings
Message-ID: <20151123164739.GD1980@HEDWIG.INI.CMU.EDU>
References: <1448294264-17388-1-git-send-email-somlo@cmu.edu>
 <1448294264-17388-5-git-send-email-somlo@cmu.edu>
 <56534067.6040401@redhat.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <56534067.6040401@redhat.com>
User-Agent: Mutt/1.5.24 (2015-08-30)
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 4111
Lines: 87

On Mon, Nov 23, 2015 at 05:35:51PM +0100, Laszlo Ersek wrote:
> On 11/23/15 16:57, Gabriel L. Somlo wrote:
> > From: Gabriel Somlo <somlo@cmu.edu>
> > 
> > Remove fw_cfg hardware interface details from
> > Documentation/devicetree/bindings/arm/fw-cfg.txt,
> > and replace them with a pointer to the authoritative
> > documentation in the QEMU source tree.
> > 
> > Signed-off-by: Gabriel Somlo <somlo@cmu.edu>
> > Cc: Laszlo Ersek <lersek@redhat.com>
> > ---
> >  Documentation/devicetree/bindings/arm/fw-cfg.txt | 38 ++----------------------
> >  1 file changed, 2 insertions(+), 36 deletions(-)
> > 
> > diff --git a/Documentation/devicetree/bindings/arm/fw-cfg.txt b/Documentation/devicetree/bindings/arm/fw-cfg.txt
> > index 953fb64..ce27386 100644
> > --- a/Documentation/devicetree/bindings/arm/fw-cfg.txt
> > +++ b/Documentation/devicetree/bindings/arm/fw-cfg.txt
> > @@ -11,43 +11,9 @@ 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 authoritative guest-side hardware interface documentation to the fw_cfg
> > +device ca be found in "docs/specs/fw_cfg.txt" in the QEMU source tree.
> 
> ca[n] be found

Same typo occurred in Patch 1/4 as well (both doc files refer to the
QEMU fw_cfg spec), so I pre-emptively fixed it there as well.

Thanks!
--Gabriel

> 
> >  
> > -The selector register takes keys in big endian byte order.
> > -
> > -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:
> >  
> > 
> 
> As long as Peter is fine with this, I don't object.
> 
> With the typo fixed:
> 
> Reviewed-by: Laszlo Ersek <lersek@redhat.com>
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/