[U-Boot] [PATCH] spi: Tegra: add device tree binding doc for SPI and QSPI

[Stephen Warren <swarren@wwwdotorg.org>]

On 10/23/2015 11:11 AM, Tom Warren wrote:
> This patch adds the device tree binding doc for the Tegra114
> SPI controller and the Tegra210 QSPI controller.

Initially, this should be sent as a Linux kernel patch, since the kernel 
currently holds the definitive repository for DT bindings.

The binding should be based on the Tegra SPI binding present there, not 
on the non-standard binding for Tegra114 SPI that's evidently in the 
U-Boot tree.

That would imply sending the patch to the people/lists listed in the 
following Linux kernel MAINTAINERS entry for DT bindings, plus at least 
the Tegra mailing list and maintainers too:

OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
M:      Rob Herring <robh+dt@kernel.org>
M:      Pawel Moll <pawel.moll@arm.com>
M:      Mark Rutland <mark.rutland@arm.com>
M:      Ian Campbell <ijc+devicetree@hellion.org.uk>
M:      Kumar Gala <galak@codeaurora.org>
L:      devicetree at vger.kernel.org

> diff --git a/doc/device-tree-bindings/spi/spi-tegra.txt b/doc/device-tree-bindings/spi/spi-tegra.txt
> new file mode 100644
> index 0000000..e215efe
> --- /dev/null
> +++ b/doc/device-tree-bindings/spi/spi-tegra.txt
> @@ -0,0 +1,47 @@
> +NVIDIA Tegra114 SPI controller.

Isn't this intended to be a binding for the QSPI controller?

> +Required properties:
> +- compatible : should be "nvidia,tegra114-spi".

This should be "qspi" not "spi", assuming the HW really is different. 
This is a separate HW module, right?

> +- reg: Should contain SPI registers location and length.
> +- interrupts: Should contain SPI interrupts.
> +- clocks : Should contain an entry for SPI clock.

Reset- and DMA-related properties are missing here.

You could mark the DMA properties optional, and leave it up to drivers 
to support PIO mode if the DMA properties are missing.

> +Recommended properties:
> +- spi-max-frequency: Definition as per
> +                     doc/device-tree-bindings/spi/spi-bus.txt

That should use a relative path ("spi-bus.txt"), so that the same text 
applies irrespective of whether the file is contained within the Linux 
kernel or U-Boot source trees.

> +NVIDIA Tegra210 QSPI controller.

The binding for Tegra114 and Tegra210 should be (and appears to be) 
identical. There's no need to duplicate the text. Instead, simply say 
something like the following for the compatible value in the one copy of 
the text:

- compatible : should be one of the following:
  "nvidia,tegra114-qspi" (for Tegra114)
  "nvidia,tegra210-qspi" (for Tegra210)

However, if a driver that supports Tegra114 could operate correctly on 
Tegra210 without knowledge that it was running on different HW, the 
following compatible values area appropriate:

- compatible : should be one of the following:
   "nvidia,tegra114-qspi" (for Tegra114)
   "nvidia,tegra210-qspi", "nvidia,tegra114-qspi" (for Tegra210)