mik32-runtime 0.4.0

Minimal Rust runtime for the MIK32 Amur microcontroller
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

# mik32-runtime

Минимальный `no_std` runtime/startup для MIK32 Amur.

## Подключение

Добавьте runtime в `Cargo.toml` приложения:

```toml
[dependencies]
mik32-runtime = "0.1"
```

И настройте target и linker script в `.cargo/config.toml` приложения:

```toml
[build]
target = "riscv32imc-unknown-none-elf"

[target.riscv32imc-unknown-none-elf]
rustflags = [
    "-C", "link-arg=-Tlink.x",
    "-C", "link-arg=--gc-sections",
]
```

Установить target можно командой:

```console
rustup target add riscv32imc-unknown-none-elf
```

## Использование

```rust,ignore
#![no_std]
#![no_main]

use mik32_runtime::entry;

#[entry]
fn main() -> ! {
    loop {}
}

#[unsafe(export_name = "trap_handler")]
fn trap() {
    // Обработать и сбросить источник прерывания.
}
```

Приложение также должно определить `#[panic_handler]`. Функция `#[entry]`
обязана иметь сигнатуру `[unsafe] fn() -> !`.

## Прерывания и critical-section

Runtime экспортирует `mik32_runtime::interrupt` с базовыми операциями:

- `interrupt::disable()` выключает `mstatus.MIE` и `mie.MEIE`, возвращая прежнее состояние;
- `unsafe interrupt::restore(state)` восстанавливает состояние после `disable`;
- `unsafe interrupt::enable()` включает `mstatus.MIE` и `mie.MEIE`;
- `interrupt::free(|| { ... })` выполняет замыкание в локальной критической секции.

Если приложению нужен стандартный backend для crate `critical-section`, включите feature
`critical-section`:

```toml
mik32-runtime = { version = "0.1", features = ["critical-section"] }
```

После этого `critical_section::with` будет использовать single-hart реализацию runtime.

## Карта памяти

По умолчанию включена feature `memory-default`:

- EEPROM: `0x0100_0000`, 8 КиБ;
- SRAM: `0x0200_0000`, 16 КиБ.

Для исполнения из SPIFI отключите default features и включите `memory-spifi`:

```toml
mik32-runtime = { version = "0.1", default-features = false, features = ["memory-spifi"] }
```

Features взаимоисключающие. `build.rs` выбирает нужный layout и публикует его
линкеру под именем `memory.x`.

## Hooks и специальные секции

Приложение может определить символы `SmallSystemInit` и `SystemInit`; они
вызываются после инициализации RAM, перед `#[entry]`. Код, помеченный
`#[unsafe(link_section = ".ram_text")]`, загружается из EEPROM/SPIFI в SRAM.
Под trap и обычный RAM-код зарезервирован единый load image в начале SRAM;
стек размером 1 КиБ расположен в конце SRAM.

## Сборка

```console
cargo build --release --example minimal
```

Результат находится в
`target/riscv32imc-unknown-none-elf/release/examples/minimal`.

## Лицензия

CC0-1.0. Насколько это допускает закон, авторы передали эту работу в
общественное достояние.