[PATCH v8 3/9] dt-bindings: document stall property for IOMMU masters - Jean-Philippe Brucker

From: Jean-Philippe Brucker <jean-philippe@linaro.org>
To: joro@8bytes.org, will@kernel.org, lorenzo.pieralisi@arm.com,
	robh+dt@kernel.org
Cc: guohanjun@huawei.com, sudeep.holla@arm.com, rjw@rjwysocki.net,
	lenb@kernel.org, robin.murphy@arm.com, bhelgaas@google.com,
	Jonathan.Cameron@huawei.com, eric.auger@redhat.com,
	iommu@lists.linux-foundation.org, devicetree@vger.kernel.org,
	linux-acpi@vger.kernel.org, linux-arm-kernel@lists.infradead.org,
	linux-pci@vger.kernel.org, baolu.lu@linux.intel.com,
	zhangfei.gao@linaro.org, shameerali.kolothum.thodi@huawei.com,
	vivek.gautam@arm.com,
	Jean-Philippe Brucker <jean-philippe@linaro.org>,
	Rob Herring <robh@kernel.org>
Subject: [PATCH v8 3/9] dt-bindings: document stall property for IOMMU masters
Date: Thu, 12 Nov 2020 13:55:15 +0100	[thread overview]
Message-ID: <20201112125519.3987595-4-jean-philippe@linaro.org> (raw)
In-Reply-To: <20201112125519.3987595-1-jean-philippe@linaro.org>

On ARM systems, some platform devices behind an IOMMU may support stall,
which is the ability to recover from page faults. Let the firmware tell us
when a device supports stall.

Reviewed-by: Rob Herring <robh@kernel.org>
Signed-off-by: Jean-Philippe Brucker <jean-philippe@linaro.org>
---
 .../devicetree/bindings/iommu/iommu.txt        | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/devicetree/bindings/iommu/iommu.txt b/Documentation/devicetree/bindings/iommu/iommu.txt
index 3c36334e4f94..26ba9e530f13 100644
--- a/Documentation/devicetree/bindings/iommu/iommu.txt
+++ b/Documentation/devicetree/bindings/iommu/iommu.txt
@@ -92,6 +92,24 @@ Optional properties:
   tagging DMA transactions with an address space identifier. By default,
   this is 0, which means that the device only has one address space.
 
+- dma-can-stall: When present, the master can wait for a transaction to
+  complete for an indefinite amount of time. Upon translation fault some
+  IOMMUs, instead of aborting the translation immediately, may first
+  notify the driver and keep the transaction in flight. This allows the OS
+  to inspect the fault and, for example, make physical pages resident
+  before updating the mappings and completing the transaction. Such IOMMU
+  accepts a limited number of simultaneous stalled transactions before
+  having to either put back-pressure on the master, or abort new faulting
+  transactions.
+
+  Firmware has to opt-in stalling, because most buses and masters don't
+  support it. In particular it isn't compatible with PCI, where
+  transactions have to complete before a time limit. More generally it
+  won't work in systems and masters that haven't been designed for
+  stalling. For example the OS, in order to handle a stalled transaction,
+  may attempt to retrieve pages from secondary storage in a stalled
+  domain, leading to a deadlock.
+
 
 Notes:
 ======
-- 
2.29.1

