How to setup pins of SP7021 in device-tree source

The aim of this document is to explain how to setup pins of SP7021 in device-tree source. SP7021 has 99 general purpose IO (GPIO) pins which are multiplexed with other special functions, like eMMC device, SPI-NOR flash, SPI-NAND flash, Ethernet phy, UART, I2C control pins, and etc. Some special function pins are multiplexed on specified pins group while some special function pins are fully multiplexed on anyone pin of GPIO8 ~ GPIO72. The following sections will explain how to setup GPIOs and special function pins in device-tree source file in Linux.

Source files of SP7021 can be got from GitHub. Refer to https://github.com/sunplus-plus1/SP7021 or 2. HOW TO GET SOURCE FILE AND PACKAGE.

Please note that to comply with Linux rules, after version 5.10.59, 4 property-names of pin node of SP7021 are changed as shown in table below:

1. Device-tree source

Device-tree source (dts) files of SP7021 are put in folder linux/kernel/arch/arm/boot/dts/. Here lists all files for SP7021 boards:

A file is shared with all SP7021 boards:

sp7021-common.dtsi

2. GPIO

SP7021 has 99 general purpose IO (GPIO) pins. Most of them are multiplexed with other special function pins. The session explains how to modify device-tree source file to set up GPIO pins as digital input or output pins.

2.1 Define GPIO in device-tree source file

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 pinctl@9c000100 in SP7021). Pin configuration nodes (sub-nodes in node pinctl@9c000100) define the actual pins assignment.

To set up GPIOs as digital input or output pins for a device, users need to add properties pinctrl-names and pinctrl-0 to a node (device) in device-tree source file. For example,

where property pinctrl-0 sets up pins of mipicsirx@9c005280 device for “default” state. It is a handle (an address) to sub-node of pin-controller node.

Property cam_gpio0-gpios and cam_gpio1-gpios define two GPIO pins to GPIO92 and GPIO93 of pin controller, respectively. Linux driver can get GPIO descriptors using the two properties. pctl is a handle (an address) to pin controller.

The following device-tree source of SP7021 shows definitions of sub-node pinmux_mipicsi0-pins of node pinctl@9c000100.

Property sunplus,pins defines all pins of a device. Each pin is defined by macro SPPCTL_IOPAD. The fisrt item

defines that GPIO92 pin as digital output pin and by default output LOW.

The second item

defines that GPIO93 pin as digital output pin and by default output LOW.

The first argument of SPPCTL_IOPAD is GPIO number which device function pin is going to multiplex. The second argument of SPPCTL_IOPAD should be SPPCTL_PCTL_G_GPIO for general purpose digital input output pins. The third argument should always be 0. The fourth define the type general purpose input output pin. Support pin type of general purpose input output are listed below:

By default (The fourth argument is 0.), general digital input output pin is an input pin. Add or OR above defines to change type of input or output. Note that SPPCTL_PCTL_L_OUT and SPPCTL_PCTL_L_OU1 cannot be OR-ed together (SPPCTL_PCTL_L_OUT|SPPCTL_PCTL_L_OU1).

2.2 Manipulate GPIO in Linux drivers

In above example, property cam_gpio0-gpios and cam_gpio1-gpios define two GPIO pins to GPIO92 and GPIO93 of pin controller, respectively. Linux drivers can use function devm_gpiod_get to GPIO descriptors using the two properties. Use gpiod_set_value to set value to GPIO or use gpiod_get_value to get value from GPIO. Refer to the following C example code.

2.3 Setup and access GPIO using sysfs

Users can setup and access GPIO using sysfs interface. Path of gpio of sysfs is /sys/class/gpio. Go to the folder and use ls command to list contents:

where export and unexport are write-only control interface. gpiochip0 is a GPIO controller (a “gpio_chip instance).

For example, you can set up GPIO16 (P2_00) as output pin using echo command. First, use echo command to export GPIO16:

where folder P2_00 (GPIO16) was created. Contents of P2_00 are:

where active_low, direction and value are control interface.

Next, use echo command to setup GPIO16 as output port.

where read-back value of “out” means P2_00 (GPIO16) is set as output port.

Next, use echo command to write values to the port.

Another example is setup GPIO17 (P2_01) as input port.

GPIO17 (P2_01) is set as input port and the read-back value of the input port is 1.

Exported GPIO can be unexported:

3. Special function pins

Some devices pins of SP7021 are multiplexed to specified pin-group of SP7021. The session 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 pinctl@9c000100 in SP7021). Pin configuration nodes (sub-nodes in node pinctl@9c000100) define the actual pins assignment.

3.1 SPI-NOR flash

Pins of SPI-NOR flash of SP7021, [CLK, D1, CSN, D0], can be multiplexed to pin-group GPIO [83, 84, 86, 87] or pin-group GPIO [78, 79, 81, 76] when 1-bit or 2-bit mode is used. It’s 4-bit pins [D2, D3] can be multiplexed to pin-group GPIO [82, 85] or pin-group GPIO [77, 80].

To set up SPI-NOR flash pins, users need to add properties pinctrl-names and pinctrl-0 to SPI-NOR flash node spinor@9c000b00 in device-tree source file. For example,

Property pinctrl-0 sets up pin-group of SPI-NOR flash for “default” state. It contains two items. The first is for pin-group [CLK, D1, CSN, D0] for 1-bit and 2-bit mode, the second is for 4-bit mode pin-group [D2, D3]. Both are handles (an address) to sub-nodes of pin-controller node.

The following device-tree source of SP7021 shows definitions of sub-nodes pinmux_spi_flash2-pins, pinmux_spi_flash2-pins, pinmux_spi_fla4b1-pins and pinmux_spi_fla4b2-pins of node pinctl@9c000100.

String“SPI_FLASH1” is defined for pin-group GPIO [83, 84, 86, 87] and “SPI_FLASH2” is defined for pin-group GPIO [78, 79, 81, 76] for 1-bit or 2-bit mode. String “SPI_FLASH_4BIT1” is defined for pin-group GPIO [82, 85] and string “SPI_FLASH_4BIT2” is pin-group GPIO [77, 80] for 4-bit mode.

Property

pinctrl-0 = <&spi_flash2_mux &spi_fla4b2_mux>;

actually sets pins of SPI-NOR flash [CLK, D1, CSN, D0] to GPIO [78, 79, 81, 76] and [D2, D3] to GPIO [77, 80], respectively.

3.2 SPI-NAND flash

Pins of SPI-NAND flash of SP7021, [D0, D2, CLK, D1, D3, CSN], can be multiplexed to pin-group GPIO [76, 77, 78, 79, 80, 81]. To set up SPI-NAND flash pins, users need to add properties pinctrl-names and pinctrl-0 to SPI-NAND flash node spinand@9c002b80 in device-tree source file. For example,

Property pinctrl-0 sets up pin-group of SPI-NAND flash for “default” state. It is a handle (an address) to sub-node of pin-controller node.

The following device-tree source of SP7021 shows definition of sub-nodes pinmux_spinand0-pins of node pinctl@9c000100.

String“SPI_NAND” is defined for the only pin-group of SPI-NAND flash. That is, GPIO [76, 77, 78, 79, 80, 81].

Property

pinctrl-0 = <&pins_spinand0>;

actually sets pins of SPI-NAND flash [D0, D2, CLK, D1, D3, CSN] to GPIO [76, 77, 78, 79, 80, 81].

3.3 eMMC device

Pins of eMMC device of SP7021, [CMD, D5, D3, D4, D0, D1, CLK, D2, D7, D6], can be multiplexed to pin-group GPIO [72, 73, 74, 75, 76, 77, 78, 79, 80, 81]. To set up eMMC device pins, users need to add properties pinctrl-names and pinctrl-0 to eMMC device node mmc@9c003b00 in device-tree source file. For example,

Property pinctrl-0 sets up pin-group of eMMC device for “default” state. It is a handle (an address) to sub-node of pin-controller node.

The following device-tree source of SP7021 shows definition of sub-nodes pinmux_emmc-pins of node pinctl@9c000100.

String“CARD0_EMMC” is defined for the only pin-group of eMMC device. That is, GPIO [72, 73, 74, 75, 76, 77, 78, 79, 80, 81].

Property

pinctrl-0 = <&emmc_mux>;

actually sets pins of eMMC device [CMD, D5, D3, D4, D0, D1, CLK, D2, D7, D6] to GPIO [72, 73, 74, 75, 76, 77, 78, 79, 80, 81].

3.4 SD Card

Pins of SD card of SP7021, [D1, D0, CLK, CMD, D3, D2], can be multiplexed to pin-group GPIO [65, 66, 67, 68, 69, 70]. To set up SD card pins, users need to add properties pinctrl-names and pinctrl-0 to SD card node sdcard@9c003e80 in device-tree source file. For example,

Property pinctrl-0 sets up pin-group of SD card for “default” state. It contains two items. The first is for pin-group of SD card, the second is for a GPIO for card detection (CD pin) of SD card. Both are handles (an address) to sub-nodes of pin-controller node.

The following device-tree source of SP7021 shows definitions of sub-nodes pinmux_mmc1-pins and pinmux_mmc1_cd-pins of node pinctl@9c000100.

String“SD_CARD” is defined for the only pin-group of SD card. That is, GPIO [65, 66, 67, 68, 69, 70]. Node pinmux_mmc1_cd-pins defines GPIO91 as general purpose input pin. Refer to session 1. GIPO for detail.

Property

pinctrl-0 = <&mmc1_mux, &mmc1_mux_cd>;

actually sets pins of SD card [D1, D0, CLK, CMD, D3, D2] to GPIO [65, 66, 67, 68, 69, 70] and set GPIO [91] as input pin for card detection (CD).

3.5 UART0 device

Pins of UART0 device of SP7021, [TXD, RXD], can be multiplexed to pin-group GPIO [88, 89]. To set up UART0 device pins, users need to add properties pinctrl-names and pinctrl-0 to UART0 device node serial@9c000900 in device-tree source file. For example,

Property pinctrl-0 sets up pin-group of UART0 device for “default” state. It is a handle (an address) to sub-node of pin-controller node.

The following device-tree source of SP7021 shows definition of sub-nodes pinmux_uart0-pins of node pinctl@9c000100.

String“UA0” is defined for the only pin-group of UART0 device. That is, GPIO [88, 89].

Property

pinctrl-0 = <&pins_uart0>;

actually sets pins of UART0 device flash [TXD, RXD] to GPIO [88, 89].

3.6 HDMI-TX

Control pins of HDMI-TX of SP7021, [HPD, SCL, SDA], can be multiplexed to pin-group GPIO [86, 97, 98], pin-group GPIO [67, 70, 69] or pin-group GPIO [60, 63, 62].

To set up HDMI-TX control pins, users need to add properties pinctrl-names and pinctrl-0 to HDMI-TX device node display@9c005c80 in device-tree source file. For example,

Property pinctrl-0 sets up pin-group of HDMI-TX device for “default” state. It is a handle (an address) to sub-node of pin-controller node.

The following device-tree source of SP7021 shows definitions of sub-nodes pinmux_hdmi_tx1-pins, pinmux_hdmi_tx2-pins and pinmux_hdmi_tx3-pins of node pinctl@9c000100.

String“HDMI_TX1” is defined for pin-group GPIO [86, 97, 98], “HDMI_TX2“ is defined for pin-group GPIO [67, 70, 69] and “HDMI_TX3” is defined for pin-group GPIO [60, 63, 62].

Property

pinctrl-0 = <&hdmi_A_tx3>;

actually sets control pins of HDMI-TX device [HPD, SCL, SDA] to GPIO [60, 63, 62].

4. Fully-multiplexed special function pins

Some devices of SP7021 support fully-multiplex pins. This means control pins of those devices can be multiplexed to any of GPIO pin from GPIO[8] to GPIO[71]. The session 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 pinctl@9c000100 in SP7021). Pin configuration nodes (sub-nodes in node pinctl@9c000100) define the actual pins assignment.

The following devices of SP7021 support fully-multiplex: 2-port Ethernet (Layer 2 Switch, L2SW), SDIO, PWM (8-bit), ICM0~3, SPIM0~3, SPIS0~3, I2C0~I2C3, UART1~4, Timer0~3 and Interrupt (8-bit).

4.1 Ethernet

2 port Ethernet device have 22 pins totally. They are CLK_OUT, MAC_SMI_MDC, MAC_SMI_MDIO, LED_FLASH0, LED_FLASH1, LED_ON0, LED_ON1, P0_MAC_RMII_TXEN, P0_MAC_RMII_TXD0, P0_MAC_RMII_TXD1, P0_MAC_RMII_CRSDV, P0_MAC_RMII_RXD0, P0_MAC_RMII_RXD1, P0_MAC_RMII_RXER, P1_MAC_RMII_TXEN, P1_MAC_RMII_TXD0, P1_MAC_RMII_TXD1, P1_MAC_RMII_CRSDV, P1_MAC_RMII_RXD0, P1_MAC_RMII_RXD1, P1_MAC_RMII_RXER, and DAISY_MODE. All pins can be multiplexed to any pins of GPIO from GPIO[8] to GPIO[71]. Here lists the pin define used in device-tree source file:

To set up Ethernet pins, users need to add properties pinctrl-names and pinctrl-0 to Ethernet node l2sw@9c108000 in device-tree source file. For example,

Property pinctrl-0 sets up pins of Ethernet for “default” state. It is a handle (an address) to sub-node of pin-controller node.

The following device-tree source of SP7021 shows definitions of sub-node pinmux_l2sw-pins of node pinctl@9c000100.

The pins of 2-port Ethernet are multiplexed as shown in the table:

where function pins with prefix P0_ are for port 0 and with prefix P1_ are for port 1.

Property sunplus,pins defines all pins of a device. Each pin is defined by macro SPPCTL_IOPAD. For example, the first item

defines that Ethernet clock pin, MUXF_L2SW_CLK_OUT (CLK_OUT), and it is multiplexed to GPIO[40].

The first argument of SPPCTL_IOPAD is GPIO number which device function pin is going to multiplex. The second argument of SPPCTL_IOPAD should be SPPCTL_PCTL_G_PMUX for fully-multiplex pins. The third argument of SPPCTL_IOPAD is function pin of a device. Fourth argument should always be 0.

Property sunplus,zerofunc defines all unused pins. Each unused pin should be added in the list. This make sure the unused pins will be output to any GPIO [8] to [71] accidentally.

The following device-tree source of SP7021 shows another example of definitions of sub-node pinmux_l2sw-pins of node pinctl@9c000100.

The pins of port 0 of Ethernet are multiplexed as shown in the table:

where function pins with prefix P0_ are for port 0. Only port 0 of Ethernet is multiplexed to GPIO pins.

If only port 1 of Ethernet is going to be multiplexed to GPIO pins, the definitions of sub-node pinmux_l2sw-pins of node pinctl@9c000100. should look like, for example, this:

The pins of port 1 of Ethernet are defined as shown in the table:

where function pins with prefix P1_ are for port 1. Only port 1 of Ethernet is multiplexed to GPIO pins.

4.2 SDIO interface

SDIO interface have 6 pins totally. They are CLK, CMD, D0, D1, D2, and D3. All pins can be multiplexed to any pins of GPIO from GPIO[8] to GPIO[71]. Here lists the pin define used in device-tree source file:

To set up SDIO interface pins, users need to add properties pinctrl-names and pinctrl-0 to SDIO node sdio@9c008400 in device-tree source file. For example,

Property pinctrl-0 sets up pins of SDIO interface for “default” state. It is a handle (an address) to sub-node of pin-controller node.

The following device-tree source of SP7021 shows definitions of sub-node pinmux_sdio-pins of node pinctl@9c000100.

The pins of SDIO interface are multiplexed as shown in the table: