From patchwork Fri Aug 11 15:42:33 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Stephen Boyd X-Patchwork-Id: 800623 Return-Path: X-Original-To: incoming-imx@patchwork.ozlabs.org Delivered-To: patchwork-incoming-imx@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=none (mailfrom) smtp.mailfrom=lists.infradead.org (client-ip=65.50.211.133; helo=bombadil.infradead.org; envelope-from=linux-arm-kernel-bounces+incoming-imx=patchwork.ozlabs.org@lists.infradead.org; receiver=) Authentication-Results: ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=lists.infradead.org header.i=@lists.infradead.org header.b="cEkESZ4O"; dkim=fail reason="signature verification failed" (1024-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.b="jFOAB8FF"; dkim-atps=neutral Received: from bombadil.infradead.org (bombadil.infradead.org [65.50.211.133]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3xTTn12RN0z9sDB for ; Sat, 12 Aug 2017 01:43:33 +1000 (AEST) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=lists.infradead.org; s=bombadil.20170209; h=Sender: Content-Transfer-Encoding:Content-Type:Cc:List-Subscribe:List-Help:List-Post: List-Archive:List-Unsubscribe:List-Id:MIME-Version:References:In-Reply-To: Message-Id:Date:Subject:To:From:Reply-To:Content-ID:Content-Description: Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID: List-Owner; bh=dHIB+1zXzE3/G5xjTqo4fWJBBTq+OsngO06tyyu+W20=; b=cEkESZ4OSuuI3w w8PB54JCSJ20X2YqzijlWJFANMHCEhvgtY0wYK59DONtXFHt+4W9aYRlaQMceNgX265YC/r+iXf9N jqeVj6o6LqRwclkkAIRHOPs4/DiglHSU2ymUJoq1L6OyKWExc/J3PNoQq7yrIyZS9QSEijDpWpXlk +TMkuPoQ7pVge/uKDFI8GRKeCQ2g2P4XldYFzfIqBdDANmRuoUVQKeoQxHb7WRHU7VrFn81crZWuM f2Bcfc8n2m5T/8vcpNQxXST0Ym928VHv2hAyY2/7k3VQxtcSG8rezSO+vlJWjo/KcLF26yNV6bvTa KOULeQiQAHaFLZLaMozA==; Received: from localhost ([127.0.0.1] helo=bombadil.infradead.org) by bombadil.infradead.org with esmtp (Exim 4.87 #1 (Red Hat Linux)) id 1dgC5x-0002DC-Q9; Fri, 11 Aug 2017 15:43:29 +0000 Received: from mail-pg0-x230.google.com ([2607:f8b0:400e:c05::230]) by bombadil.infradead.org with esmtps (Exim 4.87 #1 (Red Hat Linux)) id 1dgC5X-0001oP-7d for linux-arm-kernel@lists.infradead.org; Fri, 11 Aug 2017 15:43:08 +0000 Received: by mail-pg0-x230.google.com with SMTP id u5so17065461pgn.0 for ; Fri, 11 Aug 2017 08:42:40 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=AB8am0REOkhfntEGal1rjAOunxPU744WX2yPer7FEFM=; b=jFOAB8FFDx2/fd4SWYkF3DQmoCqn9j++ZEfI5LL26qvFVigvvZevYsGU1fICZ7rc5l Dbx18mHy7VG/e3cE/KydUTi9k1zGuV3RityY0rWUQuBXLRqCy4n5EVd9ZRCZ6FYHlWsd BxiqUOGvh+yMv2aURmInVQ7+yNUZNIYjrVqkc= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=AB8am0REOkhfntEGal1rjAOunxPU744WX2yPer7FEFM=; b=mO141i4oeW7fSO8y4cvqV4yhLG7go41f3HUF/YR+1if30Zp9vFzo/LoweEHNWgzfTD FBZVvZa7Y/GYbkezxUk91Gcuv2uLgUQrge3/pM76LHp5qHpvbEoekjtRXDpTJX+0Cy52 f/+DV2KHSgAwnxYuaqR5dbV2M5hzcJqASqxd3YKuHHIhyQIOcUnaqjVul8vBPjYdmP9X LsSGiaQsHjT4aKjm6ERWPvWjizq9EYkST1ALWeN/P7B1MO89K3Oiawlz1tEJ8lF1jbYY FLOUpO9F4SOQhDsbuWdq2//N3MaT723k838QvxgkKq255Z4R0UMxeSwS9y0NhzqEAwD6 kO9w== X-Gm-Message-State: AHYfb5jh4dOEZpi6V71PTx9H6E3vpOJ9AJ30AjE5BqpnThCC/bpBnWWT Aqsu7AcTWKrZW55J X-Received: by 10.101.91.66 with SMTP id y2mr10450011pgr.88.1502466159427; Fri, 11 Aug 2017 08:42:39 -0700 (PDT) Received: from localhost.localdomain (i-global254.qualcomm.com. [199.106.103.254]) by smtp.gmail.com with ESMTPSA id a63sm2351071pfc.165.2017.08.11.08.42.38 (version=TLS1_2 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Fri, 11 Aug 2017 08:42:38 -0700 (PDT) From: Stephen Boyd To: Rob Herring , Frank Rowand Subject: [RFC/PATCH v4 1/4] Document nexus nodes/specifier remapping Date: Fri, 11 Aug 2017 08:42:33 -0700 Message-Id: <20170811154236.12891-2-stephen.boyd@linaro.org> X-Mailer: git-send-email 2.14.GIT In-Reply-To: <20170811154236.12891-1-stephen.boyd@linaro.org> References: <20170811154236.12891-1-stephen.boyd@linaro.org> MIME-Version: 1.0 X-CRM114-Version: 20100106-BlameMichelson ( TRE 0.8.0 (BSD) ) MR-646709E3 X-CRM114-CacheID: sfid-20170811_084303_447432_4B9FE0D9 X-CRM114-Status: GOOD ( 23.78 ) X-Spam-Score: -2.0 (--) X-Spam-Report: SpamAssassin version 3.4.1 on bombadil.infradead.org summary: Content analysis details: (-2.0 points) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at http://www.dnswl.org/, no trust [2607:f8b0:400e:c05:0:0:0:230 listed in] [list.dnswl.org] -0.0 SPF_PASS SPF: sender matches SPF record -1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1% [score: 0.0000] -0.1 DKIM_VALID Message has at least one valid DKIM or DK signature 0.1 DKIM_SIGNED Message has a DKIM or DK signature, not necessarily valid -0.1 DKIM_VALID_AU Message has a valid DKIM or DK signature from author's domain X-BeenThere: linux-arm-kernel@lists.infradead.org X-Mailman-Version: 2.1.21 Precedence: list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: devicetree-spec@vger.kernel.org, devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, linux-arm-kernel@lists.infradead.org, Russell King - ARM Linux Sender: "linux-arm-kernel" Errors-To: linux-arm-kernel-bounces+incoming-imx=patchwork.ozlabs.org@lists.infradead.org List-Id: linux-imx-kernel.lists.patchwork.ozlabs.org Document the generic nexus node properties. This can be used by any specifier that conforms to #-cells where they want to support remapping phandle lists through nexus nodes. This is similar to interrupt remapping, but slightly different because we don't consider unit addresses when doing mappings. This is mostly a copy/paste of the interrupt specification, with the unit address parts removed and generalized to any specifier. There's also the addition of a pass through mechanism to make things more compact if desired in the mapping table. Signed-off-by: Stephen Boyd --- I still need to write the blurb about what this is all about, but I wanted to send this out now to get early feedback. Some starting points: 1) Replace child/parent with incoming/outgoing everywhere? 2) Make a pretty picture to describe remapping phandle+specifiers similar to the interrupt hierarchy diagram? 3) Come up with some better name than ? Kernel-doc uses but I'm not sure that's any better. source/devicetree-basics.rst | 208 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 208 insertions(+) diff --git a/source/devicetree-basics.rst b/source/devicetree-basics.rst index 02696bac15c7..b0571145ee40 100644 --- a/source/devicetree-basics.rst +++ b/source/devicetree-basics.rst @@ -1280,3 +1280,211 @@ performed: * That result is looked up in the *interrupt-map* table, which maps to the parent interrupt specifier ``<4 1>``. +.. _sect-nexus: + +Nexus Nodes and Specifier Mapping +--------------------------------- + +TODO: Write blurb here about nexus nodes and remapping them + +Nexus Node Properties +~~~~~~~~~~~~~~~~~~~~~ + +A nexus node shall have a *#-cells* property, where is +some specifier space like 'gpio', 'clock', 'reset', etc. + +-map +^^^^^^^^^^^^^^^ + +Property: ``-map`` + +Value type: ```` encoded as an arbitrary number of +specifier mapping entries. + +Description: + + A *-map* is a property in a nexus node that bridges one + specifier domain with a set of parent specifier domains and describes + how specifiers in the child domain are mapped to their respective parent + domains. + + The map is a table where each row is a mapping entry + consisting of three components: *child specifier*, *specifier parent*, and + *parent specifier*. + + child specifier + The specifier of the child node being mapped. The number + of 32-bit cells required to specify this component is described by + the *#-cells* property of this node—the nexus node + containing the *-map* property. + + specifier parent + A single ** value that points to the specifier parent to + which the child domain is being mapped. + + parent specifier + The specifier in the parent domain. The number of 32-bit + cells required to specify this component is described by the + *#-cells* property of the specifier parent node. + + Lookups are performed on the mapping table by matching a specifier against + the child specifier in the map. Because some fields in the specifier may + not be relevant or need to be modified, a mask is applied before the lookup + is done. This mask is defined in the *-map-mask* property (see + section :ref:`sect-specifier-map-mask`). + + Similarly, when the specifier is mapped some fields in the unit specifier + may need to be kept unmodified and passed through from the child node to the + parent node. In this case, a *-map-pass-thru* property (see + section :ref:`sect-specifier-map-pass-thru`) may be specified to apply + a mask to the incoming specifier and copy any bits that match to the outgoing + unit specifier. + +.. _sect-specifier-map-mask: + +-map-mask +^^^^^^^^^^^^^^^^^^^^ + +Property: ``-map-mask`` + +Value type: ```` encoded as a bit mask + +Description: + + A *-map-mask* property may be specified for a nexus node. + This property specifies a mask that is applied to the incoming unit + specifier being looked up in the table specified in the *-map* + property. If this property is not specified, the mask is assumed to be + a mask with all bits set. + +.. _sect-specifier-map-pass-thru: + +-map-pass-thru +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Property: ``-map-pass-thru`` + +Value type: ```` encoded as a bit mask + +Description: + + A *-map-pass-thru* property may be specified for a nexus node. + This property specifies a mask that is applied to the incoming unit + specifier being looked up in the table specified in the *-map* + property. Any matching bits in the incoming unit specifier are copied over + to the outgoing specifier. If this property is not specified, the mask is + assumed to be a mask with no bits set. + +#-cells +^^^^^^^^^^^^^^^^^^ + +Property: ``#-cells`` + +Value type: ```` + +Description: + + The *#-cells* property defines the number of cells required to + encode a specifier for a domain. + +Specifier Mapping Example +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following shows the representation of a fragment of a devicetree with +two GPIO controllers and a sample specifier map for describing the +GPIO routing of a few gpios on both of the controllers through a connector +on a board to a device. The expansion device node is one one side of the +connector node and the SoC with the two GPIO controllers is on the other +side of the connector. + +.. _example-specifier-mapping: + +.. code-block:: dts + + soc { + soc_gpio1: gpio-controller1 { + #gpio-cells = <2>; + }; + + soc_gpio2: gpio-controller2 { + #gpio-cells = <2>; + }; + }; + + connector: connector { + #gpio-cells = <2>; + gpio-map = <0 0 &soc_gpio1 1 0>, + <1 0 &soc_gpio2 4 0>, + <2 0 &soc_gpio1 3 0>, + <3 0 &soc_gpio2 2 0>; + gpio-map-mask = <0xf 0x0>; + gpio-map-pass-thru = <0x0 0x1>; + }; + + expansion_device { + reset-gpios = <&connector 2 GPIO_ACTIVE_LOW>; + }; + + +Each row in the gpio-map table consists of three parts: a child unit +specifier, which is mapped to a *gpio-controller* +node with a parent specifier. + +* For example, the first row of the specifier-map table specifies the + mapping for GPIO 0 of the connector. The components of that row are shown + here + + | child specifier: ``0 0`` + | specifier parent: ``&soc_gpio1`` + | parent specifier: ``1 0`` + + * The child specifier is ``<0 0>``, which specifies GPIO 0 in the connector + with a *flags* field of ``0``. This takes two 32-bit cells as specified + by the *#gpio-cells* property of the connector node, which is the + child specifier domian. + + * The specifier parent is specified by a phandle which points to the + specifier parent of the connector, the first GPIO controller in the SoC. + + * The parent specifier is ``<1 0>``. The number of cells to + represent the gpio specifier (two cells) is determined by the + *#gpio-cells* property on the specifier parent, the soc_gpio1 + node. + + * The value ``<1 0>`` is a value specified by the device binding for + the GPIO controller. The value ``<1>`` specifies the + GPIO pin number on the GPIO controller to which GPIO 0 on the connector + is wired. The value ``<0>`` specifies the flags (active low, + active high, etc.). + +In this example, the *gpio-map-mask* property has a value of ``<0xf 0>``. +This mask is applied to a child unit specifier before performing a lookup in +the *gpio-map* table. Similarly, the *gpio-map-pass-thru* property has a value +of ``<0x0 0x1>``. This mask is applied to a child unit specifier when mapping +it to the parent unit specifier. Any bits set in the mask are cleared out of +the parent unit specifier and copied over from the child unit specifier +to the parent unit specifier. + +To perform a lookup of the connector's specifier source number for GPIO 2 +from the expansion device's reset-gpios property, the following steps would be +performed: + +* The child specifier forms the value + ``<2 GPIO_ACTIVE_LOW>``. + + * The specifier is encoding GPIO 2 with active low flags per the GPIO + binding. + +* The *gpio-map-mask* value ``<0xf 0x0>`` is applied, giving a + result of ``<0x2 0>``. + +* That result is looked up in the *gpio-map* table, which maps to + the parent specifier ``<3 0>`` and &soc_gpio1 *phandle*. + +* That *gpio-map-pass-thru* value ``<0x0 0x1>`` is applied to child specifier, + forming ``<0 GPIO_ACTIVE_LOW>`` which is then ORed with the parent + specifier ``<3 0>`` ANDed with the inverse of the pass-thru mask + ``<0xffffffff 0xffffffe>`` resulting in ``<3 GPIO_ACTIVE_LOW>``. + +* That specifier is combined with the mapped *phandle* &soc_gpio1 resulting + in ``<&soc_gpio1 3 GPIO_ACTIVE_LOW>``.