On Wed, Jul 30, 2014 at 04:26:47PM +0100, Mark Rutland wrote:
> Hi Thierry,
> 
> This looks sane to me.
> 
> I just have a few questions below which are hopefully simple/stupid.
> 
> On Fri, Jul 04, 2014 at 04:29:17PM +0100, Thierry Reding wrote:
> > From: Thierry Reding <treding@nvidia.com>
> > 
> > This commit introduces a generic device tree binding for IOMMU devices.
> > Only a very minimal subset is described here, but it is enough to cover
> > the requirements of both the Exynos System MMU and Tegra SMMU as
> > discussed here:
> > 
> >     https://lkml.org/lkml/2014/4/27/346
> > 
> > Signed-off-by: Thierry Reding <treding@nvidia.com>
> > ---
> > Changes in v4:
> > - clarify that disabling an IOMMU DT node may not disable translation
> > - be more explicit that examples are only examples
> > - add multi-ID master example
> > 
> > Changes in v3:
> > - use #iommu-cells instead of #address-cells/#size-cells
> > - drop optional iommu-names property
> > 
> > Changes in v2:
> > - add notes about "dma-ranges" property (drop note from commit message)
> > - document priorities of "iommus" property vs. "dma-ranges" property
> > - drop #iommu-cells in favour of #address-cells and #size-cells
> > - remove multiple-master device example
> > 
> >  Documentation/devicetree/bindings/iommu/iommu.txt | 172 ++++++++++++++++++++++
> >  1 file changed, 172 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iommu/iommu.txt
> > 
> > diff --git a/Documentation/devicetree/bindings/iommu/iommu.txt b/Documentation/devicetree/bindings/iommu/iommu.txt
> > new file mode 100644
> > index 000000000000..464a81eaaf61
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iommu/iommu.txt
> > @@ -0,0 +1,172 @@
> > +This document describes the generic device tree binding for IOMMUs and their
> > +master(s).
> > +
> > +
> > +IOMMU device node:
> > +==================
> > +
> > +An IOMMU can provide the following services:
> > +
> > +* Remap address space to allow devices to access physical memory ranges that
> > +  they otherwise wouldn't be capable of accessing.
> > +
> > +  Example: 32-bit DMA to 64-bit physical addresses
> > +
> > +* Implement scatter-gather at page level granularity so that the device does
> > +  not have to.
> > +
> > +* Provide system protection against "rogue" DMA by forcing all accesses to go
> > +  through the IOMMU and faulting when encountering accesses to unmapped
> > +  address regions.
> > +
> > +* Provide address space isolation between multiple contexts.
> > +
> > +  Example: Virtualization
> > +
> > +Device nodes compatible with this binding represent hardware with some of the
> > +above capabilities.
> > +
> > +IOMMUs can be single-master or multiple-master. Single-master IOMMU devices
> > +typically have a fixed association to the master device, whereas multiple-
> > +master IOMMU devices can translate accesses from more than one master.
> > +
> > +The device tree node of the IOMMU device's parent bus must contain a valid
> > +"dma-ranges" property that describes how the physical address space of the
> > +IOMMU maps to memory. An empty "dma-ranges" property means that there is a
> > +1:1 mapping from IOMMU to memory.
> > +
> > +Required properties:
> > +--------------------
> > +- #iommu-cells: The number of cells in an IOMMU specifier needed to encode an
> > +  address.
> > +
> > +The meaning of the IOMMU specifier is defined by the device tree binding of
> > +the specific IOMMU. Below are a few examples of typical use-cases:
> > +
> > +- #iommu-cells = <0>: Single master IOMMU devices are not configurable and
> > +  therefore no additional information needs to be encoded in the specifier.
> > +  This may also apply to multiple master IOMMU devices that do not allow the
> > +  association of masters to be configured. Note that an IOMMU can by design
> > +  be multi-master yet only expose a single master in a given configuration.
> > +  In such cases the number of cells will usually be 1 as in the next case.
> > +- #iommu-cells = <1>: Multiple master IOMMU devices may need to be configured
> > +  in order to enable translation for a given master. In such cases the single
> > +  address cell corresponds to the master device's ID. In some cases more than
> > +  one cell can be required to represent a single master ID.
> > +- #iommu-cells = <4>: Some IOMMU devices allow the DMA window for masters to
> > +  be configured. The first cell of the address in this may contain the master
> > +  device's ID for example, while the second cell could contain the start of
> > +  the DMA window for the given device. The length of the DMA window is given
> > +  by the third and fourth cells.
> > +
> > +Note that these are merely examples and real-world use-cases may use different
> > +definitions to represent their individual needs. Always refer to the specific
> > +IOMMU binding for the exact meaning of the cells that make up the specifier.
> > +
> > +
> > +IOMMU master node:
> > +==================
> > +
> > +Devices that access memory through an IOMMU are called masters. A device can
> > +have multiple master interfaces (to one or more IOMMU devices).
> > +
> > +Required properties:
> > +--------------------
> > +- iommus: A list of phandle and IOMMU specifier pairs that describe the IOMMU
> > +  master interfaces of the device. One entry in the list describes one master
> > +  interface of the device.
> > +
> > +When an "iommus" property is specified in a device tree node, the IOMMU will
> > +be used for address translation. If a "dma-ranges" property exists in the
> > +device's parent node it will be ignored. An exception to this rule is if the
> > +referenced IOMMU is disabled, in which case the "dma-ranges" property of the
> > +parent shall take effect. Note that merely disabling a device tree node does
> > +not guarantee that the IOMMU is really disabled since the hardware may not
> > +have a means to turn off translation.
> > +
> > +
> > +Notes:
> > +======
> > +
> > +One possible extension to the above is to use an "iommus" property along with
> > +a "dma-ranges" property in a bus device node (such as PCI host bridges). This
> > +can be useful to describe how children on the bus relate to the IOMMU if they
> > +are not explicitly listed in the device tree (e.g. PCI devices). However, the
> > +requirements of that use-case haven't been fully determined yet. Implementing
> > +this is therefore not recommended without further discussion and extension of
> > +this binding.
> > +
> > +
> > +Examples:
> > +=========
> > +
> > +Single-master IOMMU:
> > +--------------------
> > +
> > +	iommu {
> > +		#iommu-cells = <0>;
> > +	};
> > +
> > +	master {
> > +		iommus = <&/iommu>;
> 
> Nit: this should be iommus = <&{/iommu}>, or it's not valid dts syntax.

Done.

> > +	};
> > +
> > +Multiple-master IOMMU with fixed associations:
> > +----------------------------------------------
> > +
> > +	/* multiple-master IOMMU */
> > +	iommu {
> > +		/*
> > +		 * Masters are statically associated with this IOMMU and
> > +		 * address translation is always enabled.
> > +		 */
> > +		#iommu-cells = <0>;
> 
> I don't follow why translation being always enabled is relevant to the
> example; that would seem to be independent from the binding.
> 
> Surely the key point is that with no way to distinguish devices, they
> presumably share the same translations?

Both aspects are important I think. For #iommu-cells = <0> there is no
way for the IOMMU driver to know how to enable translation for a given
device. So it must be either always on or always off.

I guess one could say that this is implicit if all masters share the
same translations. And I guess translations don't always have to be on
or off technically. Let me try to rephrase this:

		/*
		 * Masters are statically associated with this IOMMU and share
		 * the same address translations because the IOMMU does not
		 * have sufficient information to distinguish between masters.
		 *
		 * Consequently address translation is always on or off for
		 * all masters at any given point in time.
		 */

Does that sound better?

Thierry