Re: [Qemu-devel] [PATCH v4 4/4] devicetree: update documentation for fw_cfg ARM bindings

[Gabriel L. Somlo]

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