[PATCH 7/9] documentation: iommu: add description of ARM System MMU binding

[Stuart Yoder]

On Wed, Jun 26, 2013 at 8:39 AM, Will Deacon <will.deacon at arm.com> wrote:
> Hi Stuart,
>
> On Tue, Jun 25, 2013 at 08:18:19PM +0100, Stuart Yoder wrote:
>> On Mon, Jun 10, 2013 at 1:34 PM, Will Deacon <will.deacon at arm.com> wrote:
>> > diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.txt b/Documentation/devicetree/bindings/iommu/arm,smmu.txt
>> > new file mode 100644
>> > index 0000000..e34c6cd
>> > --- /dev/null
>> > +++ b/Documentation/devicetree/bindings/iommu/arm,smmu.txt
>> > @@ -0,0 +1,70 @@
>> > +* ARM System MMU Architecture Implementation
>> > +
>> > +ARM SoCs may contain an implementation of the ARM System Memory
>> > +Management Unit Architecture, which can be used to provide 1 or 2 stages
>> > +of address translation to bus masters external to the CPU.
>> > +
>> > +The SMMU may also raise interrupts in response to various fault
>> > +conditions.
>> > +
>> > +** System MMU required properties:
>> > +
>> > +- compatible    : Should be one of:
>> > +
>> > +                        "arm,smmu-v1"
>> > +                        "arm,smmu-v2"
>> > +                        "arm,mmu-400"
>> > +                        "arm,mmu-500"
>> > +
>> > +                  depending on the particular implementation and/or the
>> > +                  version of the architecture implemented.
>> > +
>> > +- reg           : Base address and size of the SMMU.
>> > +
>> > +- #global-interrupts : The number of global interrupts exposed by the
>> > +                       device.
>> > +
>> > +- interrupts    : Interrupt list, with the first #global-irqs entries
>> > +                  corresponding to the global interrupts
>>
>> It seems like we don't have enough information here.   It's not enough
>> for the OS to know that there are 2, 4, etc global interrupts, no?  It needs
>> to know which hardware interrupt each corresponds to.   That kind of
>> stuff is normally defined in the device binding.
>>
>> What is it that determines the number of global interrupts?
>
> I'd suggest looking at the driver I posted to get a gist of how the parsing
> code works, but suffice to say that we describe both the number of
> interrupts and the actual interrupt numbers here.

I understand that the number of interrupts and actual interrupt numbers
are described here, but was referring to the _meaning_ of the interrupt
numbers.   A binding for a device with 2 interrupts, a TX and RX would
normally identify which interrupt specifier is for TX and which is for RX.

Based on your code, the 2 global interrupts seem to be the secure
and non-secure fault interrupts...which your driver does not differentiate.
However, the device tree is describing hardware and  you can't assume
that all drivers don't care which is which.

So, I would suggest that the binding identify which interrupt specifier
is secure and which is non-secure.

If there are other interrupts added in the future like the performance interrupt
the definition could be expanded to add that.

But a question.... why do you need the #global-interrupts property
at all?   Is the number of "global" interrupts really implementation dependent?
Does't a specific compatible string imply the number of interrupts that there
actually are?

>> > +- mmu-masters   : A list of phandles to device nodes representing bus
>> > +                  masters for which the SMMU can provide a translation
>> > +                  and their corresponding StreamIDs (see example below).
>> > +                  Each device node linked from this list must have a
>> > +                  "#stream-id-cells" property, indicating the number of
>> > +                  StreamIDs associated with it.
>>
>> So to find a the SMMU for a given device, I walk up the bus hierarchy
>> until I find an SMMU?
>
> Again, the code is better than any explanation I can give here, but we
> basically construct a tree of masters for each SMMU in the system based on
> the mmu-masters property, which we can later search.

I see.

>> > +** System MMU optional properties:
>> > +
>> > +- smmu-parent   : When multiple SMMUs are chained together, this
>> > +                  property can be used to provide a phandle to the
>> > +                  parent SMMU (that is the next SMMU on the path going
>> > +                  from the mmu-masters towards memory) node for this
>> > +                  SMMU.
>>
>> Why is an explicit phandle link needed here when you don't need a
>> smmu-parent phandle in each mmu-master?    Won't walking the bus
>> hierarchy identify the parent SMMU if things are chained?
>
> What bus hierarchy? If I have two SMMU device nodes, how do I infer any
> topological information without an explicit linkage?

I really don't know anything about SMMU chaining, but am inferring what
this might look like.   Does the "child" SMMU look just like another
mmu-master to the parent?   If so, why not just use the mmu-masters
property to establish the relationship.

I just found it a bit strange that the relationship between I/O mmu-masters
is defined from parent SMMU node pointing to the device, and the
relationship between a 'child' SMMU and a parent is established
in the other direction.   Not a big deal.

Stuart