1# GD32 pin configurations
2
3This directory contains a set of files describing valid pin configurations for
4multiple GD32 devices, for example, that `USART0_TX` signal can only be mapped
5to `PA0` and `PC8`. These configurations can be used to generate valid pin
6mappings.
7
8GD32 devices use two distinct models to configure signal multiplexing. In
9some devices, like GD32F103XX, each pin has one or more associated alternate
10function. These alternate functions can be sometimes changed using the remap
11functionality, which allows routing all signals from a peripheral to a
12different set of pins. For this reason we will name the model used by such
13devices *AFIO model*. Some other devices, like GD32F450XX, have a simpler
14and more advanced model where each pin has a fixed list of alternate functions.
15Similarly, we will name the model used by such devices *AF model*. The datasheet
16(not reference manual) can be used to determine which model is used by a device.
17If the pin definition table mentions *remaps*, it means the device uses the
18*AFIO model*. Alternate function tables (AF0..15) will only be available on
19devices using the *AF model*.
20
21In the following sections the expected file format is described.
22
23## Common configuration
24
25Some fields are common independently of the pin configuration model.
26The commented example below describes common fields in detail.
27
28- `model` (required): Choose between `afio` or `af`
29- `series` (required): Series name, e.g. gd32vf103
30- `variants` (required): Each variant has a different set of valid pin
31  combinations, either because of a different number of pins or because devices
32  with certain memory configurations have less or more peripherals available.
33
34Example:
35
36```yaml
37model: afio
38
39series: gd32vf103
40
41variants:
42  - pincode: V
43    memories: [B, 8]
44  - pincode: R
45    memories: [B, 8]
46  # Same pin code as before but different memories: a variant because it has
47  # less peripherals (and so less signals) than B-8.
48  - pincode: R
49    memories: [6, 4]
50```
51
52## AFIO model
53
54The AFIO model supports the following fields in the configuration file:
55
56- `signal-configs` (required): A dictionary of signal configurations. Each
57  available signal is required since the mode has to be specified.
58
59  Available configuration fields for each signal are:
60
61  - `modes` (required): A list containing one or more of these modes: `analog`,
62    `inp` and `out`.
63  - `exclude-memories` (optional): A lit of memories where the signal is not
64    available. If not defined, it is assumed that signal is available on all
65    memory configurations.
66  - `exclude-pincodes` (optional): A list of pincodes where the signal is not
67    available. If not defined, it is assumed that signal is available on all
68    pin codes.
69
70- `pins` (required): A dictionary of pin configurations.
71
72  Available configuration options for each pin are:
73
74  - `pincodes` (required): A list of pin codes that contain this pin.
75  - `afs` (required): The list of valid alternate functions for that pin.
76    The list must not include signals that can be remapped.
77
78- `remaps` (required): Available remaps for each remappable signal.
79
80  Available configuration options for each remap are:
81
82  - `pins`: Available pins. The size of the list of pins determines wether
83    a signal can be remapped (2 options) or partially or fully remapped
84    (4 options). If a signal has a single partial remap, it still needs
85    to provide 4 entries, but setting the non-available one to null.
86
87Example:
88
89```yaml
90signal-configs:
91  # Configuration for 'ADC01_IN0': available on all pincodes/memories, can
92  # only operate in 'analog' mode.
93  ADC01_IN0:
94    modes: [analog]
95  # Configuration for 'I2S2_CK': available on all pincodes, all memories except
96  # 6, 4 and can operate in both 'inp' and 'out' modes.
97  I2S2_CK:
98    modes: [inp, out]
99    exclude-memories: [6, 4]
100
101pins:
102  # Configuration for pin 'PA0'. Supported on V, R, C, T pincodes, valid
103  # alternate functions include WKUP, USART1_CTS, ...
104  PA0:
105    pincodes: [V, R, C, T]
106    afs: [WKUP, USART1_CTS, ADC01_IN0, TIMER1_CH0_ETI，TIMER4_CH0]
107
108remaps:
109  # Configuration for CAN0_RX signal. It can be remapped to PA11 (no remap),
110  # PB8 (partial remap (1)) or PD0 (full remap).
111  CAN0_RX:
112    pins: [PA11, PB8, None, PD0]
113```
114
115## AF model
116
117The AFIO model supports the following fields in the configuration file:
118
119- `signal-configs` (optional): Configuration for signals that require it.
120
121  Available configuration fields are:
122
123  - `exclude-pincodes` (optional): A list of pincodes where the signal is not
124    available. If not defined, it is assumed that signal is available on all
125    pin codes.
126
127  - `exclude-memories` (optional): A lit of memories where the signal is not
128    available. If not available, it is assumed that signal is available on all
129    memories.
130
131- `pins` (required): Configuration for all pins.
132
133  Available configuration options for each pin are:
134
135  - `pincodes` (required): A list of pin codes that contain this pin.
136  - `afs` (required): A dictionary of signals <> alternate function
137    number (or `ANALOG`).
138
139Example:
140
141```yaml
142signal-configs:
143  # Configuration for 'EXMC_NOE': available on all memories except 6, 4.
144  EXMC_NOE:
145    exclude-memories: [6, 4]
146
147pins:
148  # Configuration for pin 'PA0'. Available on pin codes I, Z, V and has
149  # the alternate functions listed in afs.
150  PA0:
151    pincodes: [I, Z, V]
152    afs:
153      # ADC012_IN0 available in analog mode
154      ADC012_IN0: ANALOG
155      # TIMER1_CH0 if AF1 is selected
156      TIMER1_CH0: 1
157      # USART1_CTS if AF7 is selected
158      USART1_CTS: 7
159```
160
161## Exception
162
163### GD32F405
164For GD32F405Vx series, LQFP100 package have 82 I/O pins, but BGA100 package only have 81 I/O pins. PD8 is lost on BGA100 package.
165
166### GD32F350
167For GD32F350xB/8/6 devices, there have some invalid signal mapping for USART0, I2C0 and SPI0.
168This issue cause by peripheral number increased on GD32F350xB/8/6, related pins already mapping
169to another signals.
170
171Below table show the invalid signal, pins mapping.
172
173| SIGNAL     | PINS      |
174| ---------- | --------- |
175| USART0_CTS | PA0       |
176| USART0_RTS | PA1       |
177| USART0_TX  | PA2, PA14 |
178| USART0_RX  | PA3, PA15 |
179| USART0_CK  | PA4       |
180| I2C0_SCL   | PB10, PF6 |
181| I2C0_SDA   | PB11, PF7 |
182| SPI0_NSS   | PB12      |
183| SPI0_SCK   | PB13      |
184| SPI0_MISO  | PB14      |
185| SPI0_MOSI  | PB15      |
186
187#### GD32L233
188
189GD32L233Kx-QFN32 and GD32L233Kx-LQFP32 have same pincode 'K'. To avoid pincode conflict, change GD32L233Kx-QFN32 pincode to 'Q'.
190