====== GPIO control ======

===== Built-in GPIO =====

A number of GPIO pins are available on the SoC's package. For the RTL8380 series with LQF216 only has a limited number of GPIOs broken out, but the RTL8390 and later use BGA packages with more pins available.
The GPIO port registers provide controls for four GPIO ports. The bits per port are MSB first, but per 32-bit registers the ports are in least-significant order.
The rtl8380-gpio driver fixes this mixed layout, and provides A0 as gpio 0, B0 as gpio 8, and so on. This is done so the GPIO numbers used in the SDK and datasheets are consistent with rtl8380-gpio.

==== Registers ====
On the [[RTL838x]] and [[RTL839x]] SoCs, these registers can be found on the SoC bus (base address 0xB8003500). The FUNCTION register doesn't appear to be used anywhere however. A second bank of identical registers is available on some SoCs (e.g. RTL8389, RTL8328), but not on the ones currently supported.

^ Offset ^ Name ^ Description ^
| 0x00 | CONTROL    | (To confirm) Pinmux register. Set bit to 1 to use as GPIO, 0 to use the alternate function(s). |
| 0x04 | FUNCTION   | (To confirm) Alternative function selection register. |
| 0x08 | DIRECTION  | Pin direction register. Set bit to 0 for input, 1 for output. |
| 0x0C | DATA       | Pin data register. Write to set a GPIO output value, read to get the input value. |
| 0x10 | ISR        | Interrupt status register. If a pin interrupt was triggered, read this register to find out which pin caused the interrupt. \\ To clear a pin interrupt, write 1 to the respective bit. |
| 0x14 | IMR_LOW    | Low port interrupt mask register. Each port has two bits to indicate on which edges the pin should trigger. Set the lowest bit to trigger on falling edges, the highest bit to trigger on rising edges, or both to trigger on both edges. \\ Register is packed as two big-endian U16 values, the first port at sub-offset 0x0, the second at sub-offset 0x2. |
| 0x18 | IMR_HIGH   | High port interrupt mask register, see IMR_LOW.\\ Register is packed as two big-endian U16 values, the third port at sub-offset 0x0, the fourth at sub-offset 0x2. |
| 0x38 | C0_IER     | (optional) VPE0 interrupt enable register.\\ Enables routing of GPIO interrupts to VPE0. |
| 0x3C | C1_IER     | (optional) VPE1 interrupt enable register.\\ Enables routing of GPIO interrupts to VPE1. |

===== RTL8380 pin muxing =====

^ Peripheral ^ Package pin ^ GPIO index ^ Alternative function ^ Pin configuration ^
| System LED | 113 | 0 | sys-led | Use the SYS_LED_EN bit in LED_GLB_CTRL to mux sys-led peripheral |
| GPIO1 | 112 | 1 | N/A | No known alternative functions |
| RTL8231 MIIM bus | 111 | 2 | MDC  | Setting the enable bit (BIT(0)) in the EXTRA_GPIO_CTRL register (0xBB00A0E0) selects the MIIM peripheral, otherwise the GPIO function is used. |
| :::              | 110 | 3 | MDIO | ::: |
| UART1 | 116 | ? | RX | Setting BIT(4) in GMII_INTF_SEL (0xBB001000) enables UART1, Clearing BIT(4) selects SPI_SLAVE mode. |
| :::   | 117 | ? | TX | ::: |
| GPIO8 | ? | 8 | N/A | Configured by the [[GS1900-24EP]], no known mux or pin location |
| GPIO9 | ? | 9 | N/A | Configured by the [[GS1900-24EP]], no known mux or pin location |
| JTAG | 29 | 12 | TMS   | BIT(2) and BIT(3) in GMII_INTF_SEL (0xBB001000) allow selecting the JTAG interface. \\ Set to 0 for JTAG (default), 2 for GPIO. |
| :::  | 28 | 13 | TCK   | ::: |
| :::  | 32 | 14 | /TRST | ::: |
| :::  | 30 | 10 | TDO   | ::: |
| :::  | 31 | 11 | TDI   | ::: |
| GPIO15 | ? | 15 | N/A | Configured by the [[GS310TP]] and [[GS1900-24EP]], no known mux or pin location |
| GPIO16 | ? | 16 | N/A | Configured by the [[GS310TP]] and [[GS1900-24EP]], no known mux or pin location |
| GPIO17 | ? | 17 | N/A | Configured by the [[GS310TP]] and [[GS1900-24EP]], no known mux or pin location |
| GPIO18 | ? | 18 | N/A | Configured by the [[GS310TP]] and [[GS1900-24EP]], no known mux or pin location |
| GPIO19 | ? | 19 | N/A | Configured by the [[GS1900-24EP]], no known mux or pin location |
| GPIO20 | ? | 20 | N/A | Configured by the [[GS1900-24EP]], no known mux or pin location |
| GPIO21 | ? | 21 | N/A | Configured by the [[GS1900-24EP]], no known mux or pin location |
| GPIO22 | ? | 22 | N/A | Configured by the [[GS1900-24EP]], no known mux or pin location |
| GPIO23 | ? | 23 | N/A | Configured by the [[GS1900-24EP]], no known mux or pin location | 

===== RTL8390 pin muxing =====

^ Peripheral ^ Package pin ^ GPIO index ^ Alternative function ^ Pin configuration ^
| System LED |  | 0 | sys-led | Use the SYS_LED_EN bit in LED_GLB_CTRL to mux sys-led peripheral |
| GPIO1 |  | 1 | N/A | No known alternative functions |
| RTL8231 MIIM bus |  | 2 | MDC  |  |
| :::              |  | 3 | MDIO | ::: |
| UART1 |  | 6 | RX | Set JTAG_SEL to 1 for UART1, 2 for GPIO |
| :::   |  | 7 | TX | ::: |
| JTAG |  |  | TMS   | Set JTAG_SEL to 0 (default) for JTAG, 2 for GPIO |
| :::  |  | 4 | TCK   | ::: |
| :::  |  |  | /TRST | ::: |
| :::  |  | 7 | TDO   | ::: |
| :::  |  | 6 | TDI   | ::: |


===== External GPIO =====
The SoCs have been designed with the [[RTL8231]] GPIO expanders in mind as a first-class citizen.
A hardware peripheral is present that can keep track of the state of one (or two on RTL93xx) RTL8231 chip(s).
The SoC's have dedicated pins and controllers for this task. For rtl930x B6 `EXT_GPIO_MDIO` and A5 `EXT_GPIO_MDC` For rtl931x, AM25: `GPIO_MDC` and AL25: `GPIO_MDIO`. This does require the RTL8231 connected to only function as GPIO expander. This should not be confused with the dedicated `LED_MDxx` pins!

To allow direct access to the devices, a raw command can be sent. For RTL8380 and RTL8390, there is no indication of request failure. RTL9300 and RTL9310 do have a flag to indicate failed read commands.

==== RTL8380 registers ====
On [[RTL838x]] SoCs the status and control registers are on the switch core bus (base address 0xBB000000).

^ Offset ^ Name ^ Description ^
| 0x0144 | CONTROL_1  | External GPIO bus control register. \\ bit[3:2] Preamble length. Values: 0 = 16-bit preamble, 1 = 32-bit preamble, 2 = suppressed preamble, 3 = 8-bit preamble. \\ bit[1] Enable external GPIO peripheral register shadowing. Must be cleared before changing other properties. \\ bit[0] Interface type. 0 for I2C bus, 1 for MIIM bus.|
| 0xA09C | COMMAND    | Command register. To issue a read or write command to a certain device, this register can be used to directly talk to the external chip, instead of relying on the peripheral. \\ bit[31:16] Frame data. For write commands: data to be sent. For read commands: the received data. \\ bit[11:7] Number of the register to be read or written. \\ bit[6:2] Device bus address. \\ bit[1] Operation bit. Set to 0 for read requests, 1 for write requests \\ bit[0] Execute command. Set to 1 to perform the request. Will self-clear after the command is completed or times out. |
| 0xA0E0 | CONTROL_2  | External GPIO device control register \\ bit[9:8] Bus clock rate. In MIIM mode, values 0-3 correspond to 2.5MHz, 5MHz, 10MHz, and 20MHz. \\ bit[7] Sync flag. \\ bit[6] Ready flag. \\ bit[5:1] RTL8231 bus address \\ bit[0] Enable device. Must be set in order to send commands and to let the registers be shadowed. |
| 0xA0E4 | DIR_LOW    | Pin direction shadow register for GPIOs 0-31. 0 is output, 1 is input. |
| 0xA0E8 | DIR_HIGH   | Pin direction shadow register for GPIOs 32-36. 0 is output, 1 is input. Only five lowest bits are valid. |
| 0xA0EC | DATA_LOW   | Pin value shadow register for GPIOs 0-31. |
| 0xA0F0 | DATA_HIGH  | Pin value shadow register for GPIOs 32-36. Only five lowest bits are valid. |
| 0x113C | IMR_LOW    | Interrupt mask register |
| 0x1140 | IMR_HIGH   | Interrupt mask register |
| 0x1188 | ISR_LOW    | Interrupt status register |
| 0x118C | ISR_HIGH   | Interrupt status register |

==== RTL930x muxing ====
The RTL930x doesn't have a dedicated muxing section in the address space. Instead, the GPIO pin muxing is all over the SoC's addressing space, so this will be a challange. A dedicated page exists to inventory the [[rtl93xx:gpio_space|GPIO mux registers]].