How to Setup Pins in Device-tree Source
The aim of this document is to explain how to setup pins of SP7350 in device-tree source. SP7350 has 106 general purpose IO (GPIO) pins which are multiplexed with other special functions, like eMMC device, SPI-NOR flash, SPI-NAND flash, Ethernet PHY (RGMII or RMII interface), UART, I2C pins, and etc.
The following sections will explain how to setup GPIOs and special function pins in device-tree source file. Note that the same device-tree source file is used by U-Boot and Linux in SP7350. Both Pinctrl drivers support generic helper bindings.
Table of Contents
IO Pins
In the Linux, name of IO pin is in form of GPIO(id), like GPIO0, GPIO1, GPIO2, …, GPIO105, and etc. These IO pins of SP7350 are categorized, based on their operating voltage, into two groups:
Single-supply IO pins: The IO pins operate on a single power supply, specifically at 1.8V.
Dual-supply IO pins: The IO pins offer a dual power supply option, supporting both 1.8V and 3.0V. These pins are referred to as DVIO pins in the subsequent sections.
Refer to table below for a breakdown of power domain, supplying voltage, pin name (hardware pin name), supplying power pins of all IO pins of SP7350:
GPIO # | Power domain | Type | Pin name | Power-supply |
0 - 19 | Main | 1.8V GPIO | G_MX0 - G_MX19 | VDDPST18_GPIO |
20 | 1.8V/3.0V DVIO | G_MX20 | VDDPST3018_DVIO_2 | |
21 - 27 | G_MX21 - G_MX27 | VDDPST3018_DVIO_1 | ||
28 - 37 | G_MX28 - G_MX37 | VDDPST3018_DVIO_2 | ||
38 - 43 | G_MX38 - G_MX43 | AVDDIO_3018_SD | ||
44 - 49 | G_MX44 - G_MX49 | AVDDIO_3018_SDIO | ||
50 - 59 | CM4 (AO) | AO_MX0 - AO_MX9 | VDDPST3018_DVIO_AO_1 | |
60 - 69 | AO_MX10 - AO_MX19 | VDDPST3018_DVIO_AO_2 | ||
70 - 79 | AO_MX20 - AO_MX29 | VDDPST3018_DVIO_AO_3 | ||
80 - 98 | 1.8V GPIO | AO_MX30 - AO_MX48 | VDDPST18_GPIO_AO | |
99 - 105 | IV_MX0 - IV_MX6 |
Voltage Mode Select
Beyond configuring the 1.8V or 3.0V power to supply pins of a DVIO group in circuit boards (hardware), setting up the voltage mode select (ms control) control-bits is crucial for the normal operation of IO pins. The following properties configure voltage mode select control-bits in the Device Tree Source (DTS) file:
Properties | Pins | Value |
|---|---|---|
sunplus,ms-dvio-group-0 | G_MX21~G_MX27 | “3V0“ for 3.0V; “1V8“ for 1.8V. |
sunplus,ms-dvio-group-1 | G_MX20, G_MX28~G_MX37 | “3V0“ for 3.0V; “1V8“ for 1.8V. |
sunplus,ms-dvio-ao-group-0 | AO_MX0~AO_MX9 | “3V0“ for 3.0V; “1V8“ for 1.8V. |
sunplus,ms-dvio-ao-group-1 | AO_MX10~AO_MX19 | “3V0“ for 3.0V; “1V8“ for 1.8V. |
sunplus,ms-dvio-ao-group-2 | AO_MX20~AO_MX29 | “3V0“ for 3.0V; “1V8“ for 1.8V. |
These properties should be set in the pinctrl node in the DTS file. For example:
pctl: pinctrl@f8800080 {
:
:
sunplus,ms-dvio-group-0 = “1V8“;
sunplus,ms-dvio-group-1 = “3V0“;
sunplus,ms-dvio-ao-group-2 = “1V8“;
:
};Default voltage is “3V0”.
Pin Multiplexing Nodes
function - the multiplex function to select.
groups - the list of groups to select with this function. Either this or "pins" must be specified.
pins - the list of pins to select with this function. Either this or "groups" must be specified.
Refer to examples below:
Set a Single Pin to GPIO function
pinmux_example {
function = "GPIO";
pins = "GPIO0";
};Set pin GPIO0 to GPIO function.
Set Several Pins to GPIO function
pinmux_example {
function = "GPIO";
pins = "GPIO0", "GPIO1", "GPIO10";
};Set pins GPIO0, GPIO1, GPIO10 to GPIO function.
Set a Group of Pins to a Specified Function
pinmux_example {
function = "UART0";
groups = "UART0_X1";
};Set a group of pins, whose group-name is UART0_X1, to UART0 function. Actually, the group includes pins GPIO50 and GPIO51.
Refer to Function-group Table in appendix.
Pin Configuration Nodes
Here we only list the generic pin configuration parameters supported by SP7350.
bias-disable
description
Disable any pin bias on the pin.
argument
The argument is ignored.
usage
pinconf_example {
:
:
bias-disable;
:
:
};
bias-high-impedance
description
The pin will be set to a high impedance mode, also know as "third-state" (tri-state) or "high-Z" or "floating".
argument
The argument is ignored.
usage
pinconf_example {
:
:
bias-high-impedance;
:
:
};
bias-pull-up
description
The pin will be pulled up.
argument
The argument is ignored.
usage
pinconf_example {
:
:
bias-pull-up;
:
:
};
bias-pull-down
description
The pin will be pulled down.
argument
The argument is ignored.
usage
pinconf_example {
:
:
bias-pull-down;
:
:
};
drive-open-drain
description
The pin will be driven with open drain (open collector) which means it is usually wired with other output ports which are then pulled up with an external resistor. Setting this config will enable open drain mode.
argument
The argument is ignored.
usage
pinconf_example {
:
:
drive-open-drain;
:
:
};
drive-strength-microamp
description
The pin will sink or source at most the current passed as argument.
argument
The argument is in uA.
See linux/kernel/include/dt-bindings/pinctrl/pinctrl-config-sp7350.h for selectable argument.
usage
pinconf_example {
:
:
/* source current 1100uA for GPIO*/
drive-strength-microamp = <SPPCTRL_GPIO_DRV_IOH_1100_IOL_1100UA>;
:
:
};pinconf_example {
:
:
/* source current 5100uA for DVIO*/
drive-strength-microamp = <SPPCTRL_DVIO_DRV_IOH_5100_IOL_6200UA>;
:
:
};
input-enable
description
Enable the pin's input.
argument
The argument is ignored.
usage
pinconf_example {
:
:
input-enable;
:
:
};
input-disable
description
Disable the pin's input.
argument
The argument is ignored.
usage
pinconf_example {
:
:
input-disable;
:
:
};
input-schmitt-enable
description
This will configure an input pin to run in Schmitt-trigger mode.
argument
The argument is ignored.
usage
pinconf_example {
:
:
input-schmitt-enable;
:
:
};
input-schmitt-disable
description
This will disable the pin's Schmitt-trigger mode.
argument
The argument is ignored.
usage
pinconf_example {
:
:
input-schmitt-disable;
:
:
};
output-enable
description
This will enable the pin's output mode without driving a value there.
argument
The argument is ignored.
usage
pinconf_example {
:
:
output-enable;
:
:
};
output-disable
description
This will disable the pin's output mode.
argument
The argument is ignored.
usage
pinconf_example {
:
:
output-disable;
:
:
};
output-high
description
This will configure the pin as output and drive high level on the line.
argument
The argument is ignored.
usage
pinconf_example {
:
:
output-high;
:
:
};
output-low
description
This will configure the pin as output and drive low level on the line.
argument
The argument is ignored.
usage
pinconf_example {
:
:
output-low;
:
:
};
sunplus,input-invert-enable
description
This will invert the pin's input value. High level as 0, Low level as 1.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,input-invert-enable;
:
:
};
sunplus,output-invert-enable
description
This will invert the pin's output value. 1 as low level, 0 as high level.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,output-invert-enable;
:
:
};
sunplus,input-invert-disable
description
This will normalize the pin's input value. High level as 1, Low level as 0.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,input-invert-disable;
:
:
};
sunplus,output-invert-disable
description
This will normalize the pin's output value. 1 as high level, 0 as low level.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,output-invert-disable;
:
:
};
sunplus,bias-strong-pull-up
description
The pin will be pulled up strongly.
For GPIO only, excluding DVIO.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,bias-strong-pull-up;
:
:
};
sunplus,ao-int-enable
description
Enable interrrupt for pins in group of GPIO_AO_INT.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,ao-int-enable;
:
:
};
sunplus,ao-int-disable
description
Disable interrrupt for pins in group of GPIO_AO_INT.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,ao-int-disable;
:
:
};
sunplus,ao-int-debounce-enable
description
Enable debounce for pins in group of GPIO_AO_INT.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,ao-int-debounce-enable;
:
:
};
sunplus,ao-int-debounce-disable
description
Disable debounce for pins in group of GPIO_AO_INT.
argument
The argument is ignored.
usage
pinconf_example {
:
:
sunplus,ao-int-debounce-disable;
:
:
};
sunplus,ao-int-trigger-type
description
Set interrupt trigger type for pins in group of GPIO_AO_INT.
argument
IRQ_TYPE_LEVEL_HIGH：High-Level Trigger
IRQ_TYPE_EDGE_RISING：Rising-Edge Trigger（by default if this property is not set）
usage
pinconf_example {
:
:
sunplus,ao-int-trigger-type=<IRQ_TYPE_EDGE_RISING>;
:
:
};DTS Files
Device-tree source files of SP7350 are located in linux/kernel/arch/arm64/boot/dts/sunplus/.
Here lists all files for SP7350 boards:
Boards | Device-tree source files |
C3V-W Evaluation Board | sp7350-ev.dts |
C3V-W Demo Board | sp7350-dm.dts |
Example
Voltage Mode Select
For 1.8V/3.0V Dual Voltage IO (DVIO) pins, we need to select their voltage in pinctrl top node in DTS file. For example,
pctl: pinctrl@f8800080 {
compatible = "sunplus,sp7350-pctl";
:
:
sunplus,ms-dvio-group-0 = "1V8";
sunplus,ms-dvio-group-1 = "1V8";
sunplus,ms-dvio-ao-group-0 = "1V8";
sunplus,ms-dvio-ao-group-1 = "3V0";
sunplus,ms-dvio-ao-group-2 = "3V0";
:
:
};In this example, DVIO groups 0 and 1 are configured to operate at 1.8V, while DVIO AO group 0 is designated with a voltage setting of 1.8V. Conversely, DVIO AO groups 1 and 2 are specifically set to operate at 3.0V. It is crucial to note that in the absence of a specified selection, the default voltage for these groups is set to 3.0V.
GPIO
SP7350 has 106 general purpose IO (GPIO) pins. Most of them are multiplexed with other special function pins. This section explains how to modify device-tree source file to set up GPIO pins as digital input or output pins.
Define GPIO in device-tree source file
Every single device has a node in device-tree source (dts) file in Linux. Property pinctrl-0 (or pinctrl-1, pinctrl-2,… if a device has more states) is used to point at pin configuration node within pin controller (node pinctrl@f8800080 in SP7350). Pin configuration nodes (sub-nodes in node pinctrl@f8800080 ) define the actual pins assignment.
Users need to add properties pinctrl-names and pinctrl-0 to a node (device) in device-tree source file to set up GPIOs as digital input or output pins for a device . For example:
u3phy0: uphy@f80bd000 {
:
:
pinctrl-names = "default";
pinctrl-0 = <&typec_pins>;
typec-gpios = <&pctl 98 GPIO_ACTIVE_HIGH>;
:
:
};where property pinctrl-0 sets up pins of uphy@f80bd000 device for "default" state. It is a handle (an address) to sub-node of pin-controller node.
Property typec-gpios defines one GPIO pin to GPIO98 of pin controller. Linux driver can get GPIO descriptors using the property. pctl is a handle (an address) to pin controller.
The following device-tree source of SP7350 shows definitions of sub-node pinmux_typec-pins of node pinctrl@f8800080.
typec_pins: pinmux_typec-pins {
function = "GPIO";
pins = "GPIO98";
};Setting GPIO Characteristics
GPIO pins' characteristics, such as setting them to high, low, or configuring additional features, can also be directly specified within the pin node. For instance, we extend the previous example to add GPIO0 and GPIO1 and configure them as input and output, respectively. We introduce the extra_gpio_pins node label after typec_pins:
u3phy0: uphy@f80bd000 {
:
:
pinctrl-names = "default";
pinctrl-0 = <&typec_pins &extra_gpio_pins>;
typec-gpios = <&pctl 98 GPIO_ACTIVE_HIGH>;
:
:
};Add extra_gpio-pins node and label as shown below:
typec_pins: pinmux_typec-pins {
function = "GPIO";
pins = "GPIO98";
};
extra_gpio_pins: extra_gpio-pins {
gpio0_pinconf {
function = "GPIO";
pins = "GPIO0";
input-enable;
input-schmitt-enable;
};
gpio1_pinconf {
function = "GPIO";
pins = "GPIO1";
output-enable;
output-low;
drive-strength-microamp = <SPPCTRL_GPIO_DRV_IOH_1100_IOL_1100UA>;
};
};In the extra_gpio-pins node, GPIO0 is configured as an input with Schmitt trigger. Meanwhile, GPIO1 is configured as an output set to low, with a specified drive strength.
Special Function Pins
Some devices pins of SP7350 are multiplexed to specified pin-group of SP7350. This section explains how to modify device-tree source file to enable pins of those devices.
Every device should have a node in device-tree source (dts) file in Linux. Property pinctrl-0 (or pinctrl-1, pinctrl-2,… if a device has more states) is used to point at pin configuration node within pin controller (node pinctrl@f8800080 in SP7021). Pin configuration nodes (sub-nodes in node pinctrl@f8800080 ) define the actual pins assignment. For examples: