[PATCH] Docs: dt: Be explicit and consistent in reference to IOMMU specifiers

[Stuart Yoder]

The generic IOMMU binding says that the meaning of an 'IOMMU specifier'
is defined by the binding of a specific SMMU. The ARM SMMU binding
never explicitly uses the term 'specifier' at all. Update implicit
references to use the explicit term.

In the iommu-map binding change references to iommu-specifier to
"IOMMU specifier" so we are 100% consistent everywhere with terminology
and capitalization.

Signed-off-by: Stuart Yoder <***@nxp.com>
---
Documentation/devicetree/bindings/iommu/arm,smmu.txt | 10 +++++-----
Documentation/devicetree/bindings/pci/pci-iommu.txt | 6 +++---
2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.txt b/Documentation/devicetree/bindings/iommu/arm,smmu.txt
index e862d148..6cdf32d 100644
--- a/Documentation/devicetree/bindings/iommu/arm,smmu.txt
+++ b/Documentation/devicetree/bindings/iommu/arm,smmu.txt
@@ -36,15 +36,15 @@ conditions.
combined interrupt, it must be listed multiple times.

- #iommu-cells : See Documentation/devicetree/bindings/iommu/iommu.txt
- for details. With a value of 1, each "iommus" entry
+ for details. With a value of 1, each IOMMU specifier
represents a distinct stream ID emitted by that device
into the relevant SMMU.

SMMUs with stream matching support and complex masters
- may use a value of 2, where the second cell represents
- an SMR mask to combine with the ID in the first cell.
- Care must be taken to ensure the set of matched IDs
- does not result in conflicts.
+ may use a value of 2, where the second cell of the
+ IOMMU specifier represents an SMR mask to combine with
+ the ID in the first cell. Care must be taken to ensure
+ the set of matched IDs does not result in conflicts.

** System MMU optional properties:

diff --git a/Documentation/devicetree/bindings/pci/pci-iommu.txt b/Documentation/devicetree/bindings/pci/pci-iommu.txt
index 56c8296..0def586 100644
--- a/Documentation/devicetree/bindings/pci/pci-iommu.txt
+++ b/Documentation/devicetree/bindings/pci/pci-iommu.txt
@@ -32,17 +32,17 @@ PCI root complex
Optional properties
-------------------

-- iommu-map: Maps a Requester ID to an IOMMU and associated iommu-specifier
+- iommu-map: Maps a Requester ID to an IOMMU and associated IOMMU specifier
data.

The property is an arbitrary number of tuples of
(rid-base,iommu,iommu-base,length).

Any RID r in the interval [rid-base, rid-base + length) is associated with
- the listed IOMMU, with the iommu-specifier (r - rid-base + iommu-base).
+ the listed IOMMU, with the IOMMU specifier (r - rid-base + iommu-base).

- iommu-map-mask: A mask to be applied to each Requester ID prior to being
- mapped to an iommu-specifier per the iommu-map property.
+ mapped to an IOMMU specifier per the iommu-map property.


Example (1)

[Mark Rutland]

Hi Stuart,

Post by Stuart Yoder
The generic IOMMU binding says that the meaning of an 'IOMMU specifier'
is defined by the binding of a specific SMMU. The ARM SMMU binding
never explicitly uses the term 'specifier' at all. Update implicit
references to use the explicit term.
In the iommu-map binding change references to iommu-specifier to
"IOMMU specifier" so we are 100% consistent everywhere with terminology
and capitalization.

Elsewhere, we always use lower case "xxx-specifier" or "xxx specifier",
e.g. Documentation/devicetree/bindings/gpio/gpio.txt defines
"gpio-specifier", ePAPR defines "interrupt specifier".

Given we're morstly consistent on "iommu-specifier" today, could we
please jsut update the ARM SMMU binding to match that? If we're going to
fix the dash mismatch, that's a more general, cross-binding thing.

Thanks,
Mark.

Post by Stuart Yoder
---
Documentation/devicetree/bindings/iommu/arm,smmu.txt | 10 +++++-----
Documentation/devicetree/bindings/pci/pci-iommu.txt | 6 +++---
2 files changed, 8 insertions(+), 8 deletions(-)
diff --git a/Documentation/devicetree/bindings/iommu/arm,smmu.txt b/Documentation/devicetree/bindings/iommu/arm,smmu.txt
index e862d148..6cdf32d 100644
--- a/Documentation/devicetree/bindings/iommu/arm,smmu.txt
+++ b/Documentation/devicetree/bindings/iommu/arm,smmu.txt
@@ -36,15 +36,15 @@ conditions.
combined interrupt, it must be listed multiple times.
- #iommu-cells : See Documentation/devicetree/bindings/iommu/iommu.txt
- for details. With a value of 1, each "iommus" entry
+ for details. With a value of 1, each IOMMU specifier
represents a distinct stream ID emitted by that device
into the relevant SMMU.
SMMUs with stream matching support and complex masters
- may use a value of 2, where the second cell represents
- an SMR mask to combine with the ID in the first cell.
- Care must be taken to ensure the set of matched IDs
- does not result in conflicts.
+ may use a value of 2, where the second cell of the
+ IOMMU specifier represents an SMR mask to combine with
+ the ID in the first cell. Care must be taken to ensure
+ the set of matched IDs does not result in conflicts.
diff --git a/Documentation/devicetree/bindings/pci/pci-iommu.txt b/Documentation/devicetree/bindings/pci/pci-iommu.txt
index 56c8296..0def586 100644
--- a/Documentation/devicetree/bindings/pci/pci-iommu.txt
+++ b/Documentation/devicetree/bindings/pci/pci-iommu.txt
@@ -32,17 +32,17 @@ PCI root complex
Optional properties
-------------------
-- iommu-map: Maps a Requester ID to an IOMMU and associated iommu-specifier
+- iommu-map: Maps a Requester ID to an IOMMU and associated IOMMU specifier
data.
The property is an arbitrary number of tuples of
(rid-base,iommu,iommu-base,length).
Any RID r in the interval [rid-base, rid-base + length) is associated with
- the listed IOMMU, with the iommu-specifier (r - rid-base + iommu-base).
+ the listed IOMMU, with the IOMMU specifier (r - rid-base + iommu-base).
- iommu-map-mask: A mask to be applied to each Requester ID prior to being
- mapped to an iommu-specifier per the iommu-map property.
+ mapped to an IOMMU specifier per the iommu-map property.
Example (1)
--
1.9.0

[Stuart Yoder]

-----Original Message-----
Sent: Friday, December 16, 2016 5:33 AM
Subject: Re: [PATCH] Docs: dt: Be explicit and consistent in reference to IOMMU specifiers
Hi Stuart,

Post by Stuart Yoder
The generic IOMMU binding says that the meaning of an 'IOMMU specifier'
is defined by the binding of a specific SMMU. The ARM SMMU binding
never explicitly uses the term 'specifier' at all. Update implicit
references to use the explicit term.
In the iommu-map binding change references to iommu-specifier to
"IOMMU specifier" so we are 100% consistent everywhere with terminology
and capitalization.

Elsewhere, we always use lower case "xxx-specifier" or "xxx specifier",
e.g. Documentation/devicetree/bindings/gpio/gpio.txt defines
"gpio-specifier", ePAPR defines "interrupt specifier".
Given we're morstly consistent on "iommu-specifier" today,could we
please jsut update the ARM SMMU binding to match that? If we're going to
fix the dash mismatch, that's a more general, cross-binding thing.

The notable place where we don't use "iommu-specifier" in in the generic
IOMMU binding itself where we use "IOMMU specifier". You're suggesting
using "iommu-specifier" everywhere including the generic binding? Sounds
fine to me. It's a nit but would like to see it consistent everywhere.

Thanks,
Stuart

[Mark Rutland]

Post by Stuart Yoder

-----Original Message-----

Post by Stuart Yoder
In the iommu-map binding change references to iommu-specifier to
"IOMMU specifier" so we are 100% consistent everywhere with terminology
and capitalization.

Elsewhere, we always use lower case "xxx-specifier" or "xxx specifier",
e.g. Documentation/devicetree/bindings/gpio/gpio.txt defines
"gpio-specifier", ePAPR defines "interrupt specifier".
Given we're morstly consistent on "iommu-specifier" today,could we
please jsut update the ARM SMMU binding to match that? If we're going to
fix the dash mismatch, that's a more general, cross-binding thing.

The notable place where we don't use "iommu-specifier" in in the generic
IOMMU binding itself where we use "IOMMU specifier".

True; I failed to notice that. You are right in that the pci-iommu
binding is the odd one out. Sorry for the misinformation above. :/

Post by Stuart Yoder
You're suggesting using "iommu-specifier" everywhere including the
generic binding? Sounds fine to me. It's a nit but would like to see
it consistent everywhere.

I certainly agree that we should be consistent.

So FWIW, for this patch (as-is):

Acked-by: Mark Rutland <***@arm.com>

Thanks,
Mark.