From patchwork Tue Jan 17 23:14:09 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Cercueil X-Patchwork-Id: 716441 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by ozlabs.org (Postfix) with ESMTP id 3v36986Rb9z9srY for ; Wed, 18 Jan 2017 10:42:52 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=crapouillou.net header.i=@crapouillou.net header.b="QsFNx4D0"; dkim-atps=neutral Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751894AbdAQXlK (ORCPT ); Tue, 17 Jan 2017 18:41:10 -0500 Received: from outils.crapouillou.net ([89.234.176.41]:60484 "EHLO outils.crapouillou.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751513AbdAQXk7 (ORCPT ); Tue, 17 Jan 2017 18:40:59 -0500 From: Paul Cercueil To: Linus Walleij , Rob Herring , Mark Rutland , Ralf Baechle , Ulf Hansson , Boris Brezillon , Thierry Reding , Bartlomiej Zolnierkiewicz , Maarten ter Huurne , Lars-Peter Clausen , Paul Burton Cc: linux-gpio@vger.kernel.org, devicetree@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mips@linux-mips.org, linux-mmc@vger.kernel.org, linux-mtd@lists.infradead.org, linux-pwm@vger.kernel.org, linux-fbdev@vger.kernel.org, james.hogan@imgtec.com, Paul Cercueil Subject: [PATCH 01/13] Documentation: dt/bindings: Document pinctrl-ingenic Date: Wed, 18 Jan 2017 00:14:09 +0100 Message-Id: <20170117231421.16310-2-paul@crapouillou.net> In-Reply-To: <20170117231421.16310-1-paul@crapouillou.net> References: <20170117231421.16310-1-paul@crapouillou.net> DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=crapouillou.net; s=mail; t=1484694893; bh=8Dq1BFEuPqk2Emy9COS1sdF8JwTEafQtpKxYrblOxws=; h=From:To:Cc:Subject:Date:Message-Id:In-Reply-To:References; b=QsFNx4D0ofUEzYeP/i1UOeDITeN4ssHT1jq4YT0ZsAKEx3RJjM8xVu/TJ+rjs1LsPZa2I6WpWYzMT7Z86bnZ7dQ795HDnJxmF60DZGbLrqXRjbEObv9m3PYDJdjd5gPSd+1lhcxznJ3y4zd5ckLZhBOWU07b83ualTieF5JZt4Q= Sender: linux-pwm-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-pwm@vger.kernel.org From: Paul Burton This commit adds documentation for the devicetree bidings of the pinctrl-ingenic driver, which handles pin configuration, pin muxing and GPIOs of the Ingenic SoCs currently supported by the Linux kernel. Signed-off-by: Paul Cercueil --- .../bindings/pinctrl/ingenic,pinctrl.txt | 173 +++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt diff --git a/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt new file mode 100644 index 000000000000..e59f7e7b6a49 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/ingenic,pinctrl.txt @@ -0,0 +1,173 @@ +Ingenic jz47xx pin controller + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +For the jz47xx SoCs, pin control is tightly bound with GPIO ports. All pins may +be used as GPIOs, multiplexed device functions are configured within the +GPIO port configuration registers and it is typical to refer to pins using the +naming scheme "PxN" where x is a character identifying the GPIO port with +which the pin is associated and N is an integer from 0 to 31 identifying the +pin within that GPIO port. For example PA0 is the first pin in GPIO port A, and +PB31 is the last pin in GPIO port B. The jz4740 contains 4 GPIO ports, PA to +PD, for a total of 128 pins. The jz4780 contains 6 GPIO ports, PA to PF, for a +total of 192 pins. + + +##### Pin controller node ##### + +Required properties: +- compatible: One of: + - "ingenic,jz4740-pinctrl" + - "ingenic,jz4780-pinctrl" +- #address-cells: Should contain the integer 1. +- #size-cells: Should contain the integer 1. +- ranges: Should be empty. + +Required sub-nodes: + - gpio-chips (see below) + - functions (see below) + +The pin controller node must have two sub-nodes, 'gpio-chips' and 'functions'. + + +##### 'gpio-chips' sub-node ##### + +The gpio-chips node will contain sub-nodes that correspond to GPIO controllers +(one sub-node per GPIO controller). + +Required properties: +- #address-cells: Should contain the integer 1. +- #size-cells: Should contain the integer 1. +- ranges: Should be empty. + + +##### 'functions' sub-node ##### + +The "functions" node will contain sub-nodes that correspond to pin function +nodes. + +Required properties: +- None. + + +##### GPIO controller node ##### + +Each subnode of the 'gpio-chips' node is a GPIO controller node. + +Required properties: +- gpio-controller: Identifies this node as a GPIO controller. +- #gpio-cells: Should contain the integer 2. +- reg: Should contain the physical address and length of the GPIO controller's + configuration registers. + +Optional properties: +- interrupt-controller: The GPIO controllers can optionally configure the + GPIOs as interrupt sources. In this case, the 'interrupt-controller' + standalone property should be supplied. +- #interrupt-cells: Required if 'interrupt-controller' is also specified. + In that case, it should contain the integer 2. +- interrupts: Required if 'interrupt-controller' is also specified. + In that case, it should contain the IRQ number of this GPIO controller. +- ingenic,pull-ups: A bit mask identifying the pins associated with this GPIO + port which feature a pull-up resistor. The default mask is 0x0. +- ingenic,pull-downs: A bit mask identifying the pins associated with this GPIO + port which feature a pull-down resistor. The default mask is 0x0. + Each pin of the jz47xx SoCs may feature a single bias resistor, thus there + should be no bits which are set in both ingenic,pull-ups & ingenic,pull-downs. + + +##### Pin function node ##### + +Each subnode of the 'functions' node is a pin function node. + +These subnodes represent a functionality of the SoC which may be exposed +through one or more groups of pins, represented as subnodes of the pin +function node. For example a function may be uart0, which may be exposed +through the group of pins PF0 to PF3. + +Required pin function node properties: +- None. + + +##### Pin group node ##### + +Each subnode of a pin function node is a pin group node. + +Required pin group node properties: +- ingenic,pins: A set of values representing the pins within this pin group and + their configuration. Four values should be provided for each pin: + - The phandle of the GPIO controller node for the GPIO port within which the + pin is found. + - The index of the pin within its GPIO port (an integer in the range 0 to 31 + inclusive). + - The index of the shared function port to be programmed in the GPIO port + registers for this pin. + Tables of these may be found in the jz4740 and jz4780 programming + manuals within the "General-Purpose I/O Ports" -> "Overview" section. + The value can either be supplied directly (0 for function 0, 1 for + function 1, etc.) or using the macros present in + . + The special macro JZ_PIN_MODE_GPIO can be used to specify that the pin is + to be used as a GPIO. This is useful, for instance, when you just want to + set the electrical configuration of a pin used as GPIO. + - The phandle of a pin configuration node specifying the electrical + configuration that should be applied to the pin. + +For example the function 'msc0' may be exposed through 2 different pin groups, +one in GPIO port A and one in GPIO port E: + + bias-configs { + nobias: nobias { + bias-disable; + }; + }; + + functions { + pinfunc_msc0: msc0 { + pins_msc0_pa: msc0-pa { + ingenic,pins = <&gpa 4 1 &nobias /* d4 */ + &gpa 5 1 &nobias /* d5 */ + &gpa 6 1 &nobias /* d6 */ + &gpa 7 1 &nobias /* d7 */ + &gpa 18 1 &nobias /* clk */ + &gpa 19 1 &nobias /* cmd */ + &gpa 20 1 &nobias /* d0 */ + &gpa 21 1 &nobias /* d1 */ + &gpa 22 1 &nobias /* d2 */ + &gpa 23 1 &nobias /* d3 */ + &gpa 24 1 &nobias>; /* rst */ + }; + + pins_msc0_pe: msc0-pe { + ingenic,pins = <&gpe 20 0 &nobias /* d0 */ + &gpe 21 0 &nobias /* d1 */ + &gpe 22 0 &nobias /* d2 */ + &gpe 23 0 &nobias /* d3 */ + &gpe 28 0 &nobias /* clk */ + &gpe 29 0 &nobias>; /* cmd */ + }; + }; + }; + + +##### Pin configuration node ##### + +The pin configuration nodes are referenced by phandle, and can be placed +anywhere in the device tree (including in the pin controller node, or in a +sub-node that is not 'gpio-chips' or 'functions'). + +Pin configuration nodes use generic pinconf properties to specify an electrical +configuration of a pin. The only configurable property for a pin of the jz47xx +SoCs is whether to enable its bias resistor. Thus the only supported pinconf +properties are: + +- bias-disable +- bias-pull-up +- bias-pull-down + +No arguments are supported for any of these properties. + +For more information about generic pinconfig properties, see +Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt