From patchwork Fri May 23 20:36:35 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Thierry Reding X-Patchwork-Id: 4235891 Return-Path: X-Original-To: patchwork-linux-arm@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork1.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.19.201]) by patchwork1.web.kernel.org (Postfix) with ESMTP id 4B2179F32B for ; Fri, 23 May 2014 20:41:49 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id 3D71520295 for ; Fri, 23 May 2014 20:41:48 +0000 (UTC) Received: from bombadil.infradead.org (bombadil.infradead.org [198.137.202.9]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 331E6201E4 for ; Fri, 23 May 2014 20:41:47 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.80.1 #2 (Red Hat Linux)) id 1WnwFP-0005P1-ST; Fri, 23 May 2014 20:39:23 +0000 Received: from mail-we0-x22d.google.com ([2a00:1450:400c:c03::22d]) by bombadil.infradead.org with esmtps (Exim 4.80.1 #2 (Red Hat Linux)) id 1WnwFM-0005KT-Pj for linux-arm-kernel@lists.infradead.org; Fri, 23 May 2014 20:39:21 +0000 Received: by mail-we0-f173.google.com with SMTP id u57so5385435wes.4 for ; Fri, 23 May 2014 13:38:58 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id; bh=ZlOie7+YjW3nNv29HERG9pvV3BfzLk9zLEJTj2OqDx4=; b=Kb7AFM051w7co3YpMuvL0hrXMM7BdZ5ZuRjj+yDfddyUacBJHJaO5sc1zUi8CXcwkp xDNfYE/I8oZoSt/kseZ23YRE8qVgb2Kqa7jynLmnu1KbA/bgDuT8Vo2rMfA0wSW7Qt94 bzlgbGLOD756ArrYn9e8jMzfxZ7e61hMhbz6eN5qGmXFd6DpyJXbtCkt6fFpWBmezr3Z zug2UDVHm1zxAqtMgLyLn6VPv4fyMPgn1lt/uXO6Lx//9rEE4c3gIoKau/DSFJfPblce moYPmdmfD9D5EkmrZjrgkySbxGcdy8J8v6KRT3gtPAzB8VF/spre/oIpbKQEGfvOh3vT LhtA== X-Received: by 10.180.75.45 with SMTP id z13mr5374041wiv.41.1400877538278; Fri, 23 May 2014 13:38:58 -0700 (PDT) Received: from localhost (port-22380.pppoe.wtnet.de. [46.59.149.26]) by mx.google.com with ESMTPSA id h6sm10865033eew.38.2014.05.23.13.38.56 for (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 23 May 2014 13:38:57 -0700 (PDT) From: Thierry Reding To: Rob Herring , Pawel Moll , Mark Rutland , Ian Campbell , Kumar Gala Subject: [PATCH v2] devicetree: Add generic IOMMU device tree bindings Date: Fri, 23 May 2014 22:36:35 +0200 Message-Id: <1400877395-4235-1-git-send-email-thierry.reding@gmail.com> X-Mailer: git-send-email 1.9.2 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20140523_133921_139227_C6EC8366 X-CRM114-Status: GOOD ( 21.04 ) X-Spam-Score: -0.1 (/) Cc: devicetree@vger.kernel.org, linux-samsung-soc@vger.kernel.org, Arnd Bergmann , Stephen Warren , Grant Grundler , Joerg Roedel , Will Deacon , linux-kernel@vger.kernel.org, Marc Zyngier , iommu@lists.linux-foundation.org, linux-tegra@vger.kernel.org, Cho KyongHo , Dave Martin , linux-arm-kernel@lists.infradead.org, Hiroshi Doyu X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+patchwork-linux-arm=patchwork.kernel.org@lists.infradead.org X-Spam-Status: No, score=-2.4 required=5.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RP_MATCHES_RCVD, T_DKIM_INVALID, UNPARSEABLE_RELAY autolearn=unavailable version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Thierry Reding 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 --- Apologies for the noise, but apparently I mistyped one of the email addresses, should be fixed now. 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 | 167 ++++++++++++++++++++++ 1 file changed, 167 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..6ce759afcc94 --- /dev/null +++ b/Documentation/devicetree/bindings/iommu/iommu.txt @@ -0,0 +1,167 @@ +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: +-------------------- +- #address-cells: The number of cells in an IOMMU specifier needed to encode + an address. +- #size-cells: The number of cells in an IOMMU specifier needed to represent + the length of an address range. + +Typical values for the above include: +- #address-cells = <0>, size-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. +- #address-cells = <1>, size-cells = <0>: 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. +- #address-cells = <2>, size-cells = <2>: 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 specified by two additional cells. + + +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. + +Optional properties: +-------------------- +- iommu-names: A list of names identifying each entry in the "iommus" + property. + + +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 { + #address-cells = <0>; + #size-cells = <0>; + }; + + master { + iommus = <&/iommu>; + }; + +Multiple-master IOMMU with fixed associations: +---------------------------------------------- + + /* multiple-master IOMMU */ + iommu { + /* + * Masters are statically associated with this IOMMU and + * address translation is always enabled. + */ + #address-cells = <0>; + #size-cells = <0>; + }; + + /* static association with IOMMU */ + master@1 { + reg = <1>; + iommus = <&/iommu>; + }; + + /* static association with IOMMU */ + master@2 { + reg = <2>; + iommus = <&/iommu>; + }; + +Multiple-master IOMMU: +---------------------- + + iommu { + /* the specifier represents the ID of the master */ + #address-cells = <1>; + #size-cells = <0>; + }; + + master { + /* device has master ID 42 in the IOMMU */ + iommus = <&/iommu 42>; + }; + +Multiple-master IOMMU with configurable DMA window: +--------------------------------------------------- + + / { + #address-cells = <1>; + #size-cells = <1>; + + iommu { + /* master ID, address of DMA window */ + #address-cells = <2>; + #size-cells = <2>; + }; + + master { + /* master ID 42, 4 GiB DMA window starting at 0 */ + iommus = <&/iommu 42 0 0x1 0x0>; + }; + };