gd32e2-hal 0.26.0

HAL for the GD32E23x series (Cortex-M23), currently the GD32E230
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239

# gd32e2-hal

[![CI/CD](https://github.com/Szizoid/gd32e2-hal/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/Szizoid/gd32e2-hal/actions/workflows/ci-cd.yml)

[English](#english) · [Русский](#русский)

---

## English

Hardware abstraction layer (HAL) for the GD32E230 microcontrollers (Cortex-M23), written on top of the PAC crate: [github](https://github.com/gd32-rust/gd32-rs), [crates.io](https://crates.io/crates/gd32e2).

> **Work in progress.** Written piece by piece, the API is unstable. Implemented modules: `adc`, `cmp`, `crc`, `dma`, `exti`, `fmc`, `gpio`, `i2c`, `rcu`, `spi`, `syscfg`, `time`, `timer`, `usart`, `watchdog`. Usage examples live in `examples/`, all of them run on the board. Not verified: the I²C fast and fast plus modes — written, unreachable on the test bench without external pull-ups; `CMPHST`, `CMPOSEL` and `lock` of the comparator; USART `Event::Error`; internal EXTI lines (LVD, RTC, CMP, USART0 wakeup); option byte fields other than the data bytes; `SYSCFG` other than `EXTISS` — the `PA11`/`PA12` remap needs a package below 32 pins.

### Principles

- **Errors at compile time**. The identity of an entity (a pin, a peripheral, a peripheral channel and so on) determines the list of available methods — an input pin has no `.set_high()` to call;
- Thanks to Rust **ownership and borrowing**, the same peripheral cannot be initialized twice or taken before its clock is enabled, and hardware cannot be modified from two places at once;
- **Zero-cost.** The same register writes as less abstract PAC code; most of the abstractions are ZSTs.

### Chip variants

A feature name is the part number with `x` in the fields the code does not see: the letter is the number of bonded pads, the digit is the flash code, the trailing `x` is the temperature grade.

| feature | pads | flash | SRAM |
| --- | --- | --- | --- |
| [`gd32e230f4xx`](https://szizoid.github.io/gd32e2-hal/gd32e230f4xx/gd32e2_hal/index.html) / [`f6xx`](https://szizoid.github.io/gd32e2-hal/gd32e230f6xx/gd32e2_hal/index.html) / [`f8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230f8xx/gd32e2_hal/index.html) | 20 | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230e8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230e8xx/gd32e2_hal/index.html) | 24 | 64K | 8K |
| [`gd32e230g4xx`](https://szizoid.github.io/gd32e2-hal/gd32e230g4xx/gd32e2_hal/index.html) / [`g6xx`](https://szizoid.github.io/gd32e2-hal/gd32e230g6xx/gd32e2_hal/index.html) / [`g8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230g8xx/gd32e2_hal/index.html) | 28 | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230k4tx`](https://szizoid.github.io/gd32e2-hal/gd32e230k4tx/gd32e2_hal/index.html) / [`k6tx`](https://szizoid.github.io/gd32e2-hal/gd32e230k6tx/gd32e2_hal/index.html) / [`k8tx`](https://szizoid.github.io/gd32e2-hal/gd32e230k8tx/gd32e2_hal/index.html) | 32, LQFP | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230k4ux`](https://szizoid.github.io/gd32e2-hal/gd32e230k4ux/gd32e2_hal/index.html) / [`k6ux`](https://szizoid.github.io/gd32e2-hal/gd32e230k6ux/gd32e2_hal/index.html) / [`k8ux`](https://szizoid.github.io/gd32e2-hal/gd32e230k8ux/gd32e2_hal/index.html) | 32, QFN | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230c4xx`](https://szizoid.github.io/gd32e2-hal/gd32e230c4xx/gd32e2_hal/index.html) / [`c6xx`](https://szizoid.github.io/gd32e2-hal/gd32e230c6xx/gd32e2_hal/index.html) / [`c8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230c8xx/gd32e2_hal/index.html) | 48 | 16K / 32K / 64K | 4K / 6K / 8K |

32 pads is the only place where the package matters: on QFN32 ground moves to the belly pad, and the two freed pins go to `PB2` and `PB8`; LQFP32 has neither.

> Development targets `GD32E230K8U6`, that is `gd32e230k8ux`; the examples take the feature from the crate depending on itself in `[dev-dependencies]`. docs.rs is built for `gd32e230c8xx`, the largest part, and shows pins and peripherals the smaller parts do not have; each feature in the table links to the documentation of its own part. `build.rs` turns the choice into the `memory.x` the linker needs and into cfg flags that gate the source. The AF map depends on the flash code — the same pin on the same AF number may lead to a different peripheral.

The orthogonal **`defmt`** feature derives `defmt::Format` on public enums and error types. Off by default; it also enables `embedded-hal/defmt-03`.

### Documentation

Method details are in the documentation: [docs.rs](https://docs.rs/gd32e2-hal/latest/gd32e2_hal/) for `gd32e230c8xx`, [GitHub Pages](https://szizoid.github.io/gd32e2-hal/) for every part. A shorter view of most of the public API is in `examples/`.

### Example

```rust
use gd32e2_hal::prelude::*;
use gd32e2_hal::pac;
use gd32e2_hal::rcu::{ClockConfig, PllFreq, SysClk};
use gd32e2_hal::usart::{Usart, UsartConfig};

let dp = pac::Peripherals::take().unwrap();
let mut fmc = dp.fmc.constrain();
let config = ClockConfig::default()
    .sysclk(SysClk::Pll(PllFreq::Mhz48));    // PLL from IRC8M -> 48 MHz
let mut rcu = dp.rcu.constrain().freeze(&mut fmc, config);
let parts = dp.gpioa.split(&mut rcu);        // enables the GPIOA clock

let mut led = parts.pa5.into_output();
led.set_high();

let tx = parts.pa9.into_alternate::<1>();    // USART0_TX; ::<3>() does not compile
let rx = parts.pa10.into_alternate::<1>();
let mut usart0 = Usart::new(&mut rcu, dp.usart0, tx, rx, UsartConfig::default());
if let Ok(byte) = usart0.read_byte() {
    usart0.write_byte(byte);                 // verified on hardware: the echo comes back
}
```

### Building

> **Flashing and debugging over SWD** (ST-Link V2 + `probe-rs`, `PA13` / `PA14`). Firmware output goes over RTT through the same probe (`defmt` + `defmt-rtt`).

- Target `thumbv8m.base-none-eabi`;
- `build.rs` writes the `memory.x` the linker needs from the selected library feature, nothing has to be copied. (A `memory.x` in the project root still overrides the generated one — the linker looks there before the search paths — and that is the supported way out for a board that is not in the table);
- `scripts/check.ps1` / `scripts/check.sh` — every CI check, stopping at the first failure.

#### cargo aliases

```shell
cargo lib             # the library only, an alias for build --features gd32e230c8xx
cargo libclippy       # clippy over the library, with the same feature
cargo pubdry          # publish --dry-run with the same feature
cargo be usart-echo   # check that one example builds, no probe needed
cargo bre usart-echo  # the same in release
cargo examples        # every example in release, skipping the ones for another part
cargo examplesclippy  # clippy over the same examples
cargo re usart-echo   # build + flash over SWD, stays attached afterwards
```

### Roadmap

**Peripherals not covered at all**
- [ ] `PMU` — sleep / deep-sleep / standby, wakeup pin, LDO.
- [ ] The rest of `SYSCFG` — the second DMA channel map, and the `CFG2` links into the timer break input.
- [ ] `RTC` — calendar. With no crystal it runs off IRC40K, with the accuracy of IRC40K.

**Finishing what is there**
- [ ] DMA interrupts — the `Event` / `listen` shape has settled, the work is mechanical.
- [ ] DMA: circular mode, `M2M`, `embedded-dma` for buffers.
- [ ] ADC: scan over several channels, which needs DMA.
- [ ] Timers: complementary outputs, break and dead time; `TRGO` on `TIMER5` so it can drive DMA.
- [ ] I²C: 10-bit addressing, SMBus, slave, DMA.
- [ ] SPI: half-duplex and single-wire modes (`BDEN`/`BDOEN`/`RO`); hardware NSS, CRC, TI mode and slave — low priority.
- [ ] USART: hardware flow control (`CTS`/`RTS`); a non-blocking API for 9-bit words.
- [ ] FWDGT: window mode (`WND`); `FWDGT_HOLD` and `WWDGT_HOLD` in a DBG module, so that the watchdogs do not count under a halted debugger.
- [ ] RCU: `HXTAL` and `LXTAL` (no crystal is fitted on the board).
- [ ] FMC: `embedded-storage` (`ReadNorFlash` / `NorFlash`) on top of the existing program and erase.

**Infrastructure**
- [ ] gd32e231x support: part number features, pin map, gates. The PAC module exists, the chip is not at hand.
- [ ] Async: `embedded-hal-async` / `embedded-io-async`, starting with a time driver on one of the timers — that is what Embassy expects from a HAL.
- [ ] Host tests — there are none at all; the crate does not build for the host, so mocks are needed.
- [ ] Moving the HAL into its own crate/repository.

### License

Dual licensed, at your option:
- Apache License 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT ([LICENSE-MIT](LICENSE-MIT))

Any contribution submitted for inclusion in this work shall be licensed the same way, without additional terms, unless stated otherwise (Apache-2.0, section 5).

---

## Русский

Hardware abstraction layer (HAL) для микроконтроллеров GD32E230 (Cortex-M23), написанный поверх PAC-крейта: [github](https://github.com/gd32-rust/gd32-rs), [crates.io](https://crates.io/crates/gd32e2).

> **В работе.** Пишется частями, API нестабилен. Реализованные модули: `adc`, `cmp`, `crc`, `dma`, `exti`, `fmc`, `gpio`, `i2c`, `rcu`, `spi`, `syscfg`, `time`, `timer`, `usart`, `watchdog`. Имеются примеры использования в `examples/`, все прогнаны на плате. Из непроверенного: режимы I²C fast и fast plus — написаны, на стенде без внешних подтяжек недостижимы; `CMPHST`, `CMPOSEL` и `lock` у компаратора; `Event::Error` у USART; внутренние линии EXTI (LVD, RTC, CMP, USART0 wakeup); поля option bytes кроме байтов данных; `SYSCFG` кроме `EXTISS` — ремапу `PA11`/`PA12` нужен корпус меньше 32 выводов.

### Принципы

- **Ошибки на этапе компиляции**. Идентичность сущности (пин, элемент периферии, канал периферии и пр.) определяет список доступных методов (например, input-пин не позволит вызвать у него метод `.set_high()`);
- Благодаря концепциям **владения и заимствования** языка Rust одну и ту же периферию не удастся инициализировать дважды или взять до включения тактования, а также не получится менять железо из двух разных участков кода одновременно;
- **Zero-cost.** Те же записи в регистры, что и у менее абстрактного PAC-кода; большая часть абстракций — ZST.

### Варианты чипа

Имя фичи — партномер с `x` в тех полях, которых код не видит: буква — число разваренных выводов, цифра — код флеша, хвостовой `x` — температурный класс.

| фича | выводы | флеш | SRAM |
| --- | --- | --- | --- |
| [`gd32e230f4xx`](https://szizoid.github.io/gd32e2-hal/gd32e230f4xx/gd32e2_hal/index.html) / [`f6xx`](https://szizoid.github.io/gd32e2-hal/gd32e230f6xx/gd32e2_hal/index.html) / [`f8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230f8xx/gd32e2_hal/index.html) | 20 | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230e8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230e8xx/gd32e2_hal/index.html) | 24 | 64K | 8K |
| [`gd32e230g4xx`](https://szizoid.github.io/gd32e2-hal/gd32e230g4xx/gd32e2_hal/index.html) / [`g6xx`](https://szizoid.github.io/gd32e2-hal/gd32e230g6xx/gd32e2_hal/index.html) / [`g8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230g8xx/gd32e2_hal/index.html) | 28 | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230k4tx`](https://szizoid.github.io/gd32e2-hal/gd32e230k4tx/gd32e2_hal/index.html) / [`k6tx`](https://szizoid.github.io/gd32e2-hal/gd32e230k6tx/gd32e2_hal/index.html) / [`k8tx`](https://szizoid.github.io/gd32e2-hal/gd32e230k8tx/gd32e2_hal/index.html) | 32, LQFP | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230k4ux`](https://szizoid.github.io/gd32e2-hal/gd32e230k4ux/gd32e2_hal/index.html) / [`k6ux`](https://szizoid.github.io/gd32e2-hal/gd32e230k6ux/gd32e2_hal/index.html) / [`k8ux`](https://szizoid.github.io/gd32e2-hal/gd32e230k8ux/gd32e2_hal/index.html) | 32, QFN | 16K / 32K / 64K | 4K / 6K / 8K |
| [`gd32e230c4xx`](https://szizoid.github.io/gd32e2-hal/gd32e230c4xx/gd32e2_hal/index.html) / [`c6xx`](https://szizoid.github.io/gd32e2-hal/gd32e230c6xx/gd32e2_hal/index.html) / [`c8xx`](https://szizoid.github.io/gd32e2-hal/gd32e230c8xx/gd32e2_hal/index.html) | 48 | 16K / 32K / 64K | 4K / 6K / 8K |

32 вывода — единственное место, где корпус имеет значение: у QFN32 земля уходит на брюшко, и два освободившихся вывода достаются `PB2` и `PB8`, у LQFP32 нет.

> Разработка идёт под `GD32E230K8U6`, то есть `gd32e230k8ux`; примеры берут фичу из записи крейта на себя в `[dev-dependencies]`. docs.rs собрана для `gd32e230c8xx`, самой жирной детали, и показывает ноги и периферию, которых у мелкой нет; каждая фича в таблице ведёт на документацию своего партномера. `build.rs` превращает выбор в нужный линкеру `memory.x` и в cfg-флаги, по которым гейтится исходник. Карта AF зависит от кода флеша — одна и та же нога на одном номере AF может вести к разной периферии.

Ортогональная фича **`defmt`** вешает `defmt::Format` на публичные enum и типы ошибок. По умолчанию выключена; заодно включает `embedded-hal/defmt-03`.

### Документация

Подробности по методам — в документации: [docs.rs](https://docs.rs/gd32e2-hal/latest/gd32e2_hal/) для `gd32e230c8xx`, [GitHub Pages](https://szizoid.github.io/gd32e2-hal/) для каждого партномера. Более краткое отражение большей части публичного API библиотеки в `examples/`.

### Пример

```rust
use gd32e2_hal::prelude::*;
use gd32e2_hal::pac;
use gd32e2_hal::rcu::{ClockConfig, PllFreq, SysClk};
use gd32e2_hal::usart::{Usart, UsartConfig};

let dp = pac::Peripherals::take().unwrap();
let mut fmc = dp.fmc.constrain();
let config = ClockConfig::default()
    .sysclk(SysClk::Pll(PllFreq::Mhz48));    // PLL от IRC8M -> 48 МГц
let mut rcu = dp.rcu.constrain().freeze(&mut fmc, config);
let parts = dp.gpioa.split(&mut rcu);        // включает такт GPIOA

let mut led = parts.pa5.into_output();
led.set_high();

let tx = parts.pa9.into_alternate::<1>();    // USART0_TX; ::<3>() не соберётся
let rx = parts.pa10.into_alternate::<1>();
let mut usart0 = Usart::new(&mut rcu, dp.usart0, tx, rx, UsartConfig::default());
if let Ok(byte) = usart0.read_byte() {
    usart0.write_byte(byte);                 // проверено на железе: эхо возвращается
}
```

### Сборка

> **Прошивка и отладка по SWD** (ST-Link V2 + `probe-rs`, `PA13` / `PA14`). Вывод из прошивки идёт по RTT через тот же зонд (`defmt` + `defmt-rtt`).

- Таргет `thumbv8m.base-none-eabi`;
- `build.rs` пишет нужный линкеру `memory.x` из выбранной фичи библиотеки, копировать ничего не надо. (`memory.x` в корне проекта всё равно перебивает сгенерированный — линкер смотрит туда раньше путей поиска, — и это штатный выход для платы, которой нет в таблице);
- `scripts/check.ps1` / `scripts/check.sh` — все проверки CI, до первого падения.

#### Алиасы cargo

```shell
cargo lib             # только библиотека, алиас для build --features gd32e230c8xx
cargo libclippy       # clippy по библиотеке, с той же фичей
cargo pubdry          # publish --dry-run с той же фичей
cargo be usart-echo   # проверить сборку одного примера, зонд не нужен
cargo bre usart-echo  # то же в release
cargo examples        # все примеры в release, кроме примеров под другой партномер
cargo examplesclippy  # clippy по тем же примерам
cargo re usart-echo   # сборка + прошивка по SWD, дальше остаётся подключённым
```

### Roadmap

**Периферия, не покрытая вовсе**
- [ ] `PMU` — sleep / deep-sleep / standby, wakeup-нога, LDO.
- [ ] Остаток `SYSCFG` — вторая карта каналов DMA и подключения `CFG2` к break-входу таймеров.
- [ ] `RTC` — календарь. Без кварца пойдёт от IRC40K, с его же точностью.

**Доделать имеющееся**
- [ ] Прерывания DMA — форма `Event` / `listen` устоялась, работа механическая.
- [ ] DMA: циклический режим, `M2M`, `embedded-dma` для буферов.
- [ ] ADC: scan по нескольким каналам, для чего нужен DMA.
- [ ] Таймеры: комплементарные выходы, break и dead time; `TRGO` у `TIMER5`, чтобы он мог запускать DMA.
- [ ] I²C: 10-битная адресация, SMBus, slave, DMA.
- [ ] SPI: half-duplex и однопроводные режимы (`BDEN`/`BDOEN`/`RO`); аппаратный NSS, CRC, TI mode и slave — низкий приоритет.
- [ ] USART: аппаратное управление потоком (`CTS`/`RTS`); неблокирующий API для 9-битных слов.
- [ ] FWDGT: оконный режим (`WND`); `FWDGT_HOLD` и `WWDGT_HOLD` в модуле DBG, чтобы сторожа не считали под остановленным отладчиком.
- [ ] RCU: `HXTAL` и `LXTAL` (ни один кварц на плате не запаян).
- [ ] FMC: `embedded-storage` (`ReadNorFlash` / `NorFlash`) поверх готовых записи и стирания.

**Инфраструктура**
- [ ] Поддержка gd32e231x: фичи партномеров, карта пинов, гейты. PAC-модуль есть, чипа на руках нет.
- [ ] Async: `embedded-hal-async` / `embedded-io-async`, начиная с драйвера времени поверх одного из таймеров — именно его Embassy ждёт от HAL.
- [ ] Тесты на хосте — их нет вовсе; крейт не собирается под хост, поэтому нужны моки.
- [ ] Вынос HAL в отдельный крейт/репозиторий.

### Лицензия

Двойное лицензирование, на выбор:
- Apache License 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT ([LICENSE-MIT](LICENSE-MIT))

Любой вклад, отправленный для включения в эту работу, лицензируется так же, без дополнительных условий, если не оговорено иное (Apache-2.0, раздел 5).