[v2,1/9] of: Add NVIDIA Tegra XUSB mailbox binding

Add device-tree bindings for the Tegra XUSB mailbox which will be used
for communication between the Tegra xHCI controller's firmware and the
host processor.

Signed-off-by: Andrew Bresticker <abrestic@chromium.org>
---
Changes from v1:
 - Updated to use common mailbox bindings.
---
 .../bindings/mailbox/nvidia,tegra124-xusb-mbox.txt | 30 ++++++++++++++++++++++
 include/dt-bindings/mailbox/tegra-xusb-mailbox.h   |  7 +++++
 2 files changed, 37 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mailbox/nvidia,tegra124-xusb-mbox.txt
 create mode 100644 include/dt-bindings/mailbox/tegra-xusb-mailbox.h

On 08/18/2014 11:08 AM, Andrew Bresticker wrote:
> Add device-tree bindings for the Tegra XUSB mailbox which will be used
> for communication between the Tegra xHCI controller's firmware and the
> host processor.

> diff --git a/Documentation/devicetree/bindings/mailbox/nvidia,tegra124-xusb-mbox.txt b/Documentation/devicetree/bindings/mailbox/nvidia,tegra124-xusb-mbox.txt

> +NVIDIA Tegra XUSB mailbox
> +=========================
> +
> +The Tegra XUSB mailbox is used by the Tegra xHCI controller's firmware to
> +communicate requests to the host and PHY drivers.
> +
> +Required properties:
> +--------------------
> + - compatible: Should be "nvidia,tegra124-xusb-mbox".
> + - reg: Address and length of the XUSB FPCI registers.
> + - interrupts: XUSB mailbox interrupt.
> + - #mbox-cells: Should be 1.  The specifier is the index of the mailbox to
> +   reference.  See <dt-bindings/mailbox/tegra-xusb-mailbox.h> for the list
> +   of valid values.

Is there a common mailbox binding somewhere? I couldn't find one. While 
the text above specifies the value for #mbox-cells, it doesn't specify 
the details of what the property is used for (i.e. there's no 
documentation of the consumer-side of this property, for parsing the 
mboxes property). Typically, that would be part of a subsystem's common 
binding document, and that document would be referenced here.

> diff --git a/include/dt-bindings/mailbox/tegra-xusb-mailbox.h b/include/dt-bindings/mailbox/tegra-xusb-mailbox.h

> +#define TEGRA_XUSB_MBOX_CHAN_HOST	0
> +#define TEGRA_XUSB_MBOX_CHAN_PHY	1

I can't work out how these values relate to hardware at all. Are they in 
fact properties of the particular firmware that's loaded into the XUSB 
module? If so, I don't think the DT should contain these values at all. 
I wonder if the individual MBOX_CMD_* values from patch 2 are any 
better, although I think those are also defined by the firmware, not the 
hardware?
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

On 08/25/2014 12:48 PM, Stephen Warren wrote:
> On 08/18/2014 11:08 AM, Andrew Bresticker wrote:
>> Add device-tree bindings for the Tegra XUSB mailbox which will be used
>> for communication between the Tegra xHCI controller's firmware and the
>> host processor.
>
>> diff --git
>> a/Documentation/devicetree/bindings/mailbox/nvidia,tegra124-xusb-mbox.txt
>> b/Documentation/devicetree/bindings/mailbox/nvidia,tegra124-xusb-mbox.txt
>
>> +NVIDIA Tegra XUSB mailbox
>> +=========================
>> +
>> +The Tegra XUSB mailbox is used by the Tegra xHCI controller's
>> firmware to
>> +communicate requests to the host and PHY drivers.
>> +
>> +Required properties:
>> +--------------------
>> + - compatible: Should be "nvidia,tegra124-xusb-mbox".
>> + - reg: Address and length of the XUSB FPCI registers.
>> + - interrupts: XUSB mailbox interrupt.
>> + - #mbox-cells: Should be 1.  The specifier is the index of the
>> mailbox to
>> +   reference.  See <dt-bindings/mailbox/tegra-xusb-mailbox.h> for the
>> list
>> +   of valid values.
>
> Is there a common mailbox binding somewhere? I couldn't find one. While
> the text above specifies the value for #mbox-cells, it doesn't specify
> the details of what the property is used for (i.e. there's no
> documentation of the consumer-side of this property, for parsing the
> mboxes property). Typically, that would be part of a subsystem's common
> binding document, and that document would be referenced here.

Ah, I see it's still being developed. I found it at:
http://lkml.iu.edu/hypermail/linux/kernel/1408.0/00201.html

It would be good to mention that the semantics of this property are 
defined by ../mailbox/mailbox.txt.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

On Mon, Aug 25, 2014 at 11:48 AM, Stephen Warren <swarren@wwwdotorg.org> wrote:
> On 08/18/2014 11:08 AM, Andrew Bresticker wrote:
>
>> diff --git a/include/dt-bindings/mailbox/tegra-xusb-mailbox.h
>> b/include/dt-bindings/mailbox/tegra-xusb-mailbox.h
>
>
>> +#define TEGRA_XUSB_MBOX_CHAN_HOST      0
>> +#define TEGRA_XUSB_MBOX_CHAN_PHY       1
>
>
> I can't work out how these values relate to hardware at all. Are they in
> fact properties of the particular firmware that's loaded into the XUSB
> module? If so, I don't think the DT should contain these values at all.

Yes this is rather ugly... they're used by software for the demuxing
of messages and don't correspond to actual hardware.

> I wonder if the individual MBOX_CMD_* values from patch 2 are any
> better, although I think those are also defined by the firmware, not the
> hardware?

They are indeed defined by the firmware, so this would become an issue
if the firmware API ever changed.
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html