csky-rt
Experimental startup code and minimal no_std runtime for C-SKY ABIv2
microcontrollers.
This crate owns the reset-to-Rust boundary: initial stack setup, vector-table
layout, .data copying, .bss zeroing, default exception handling, and the
generic linker script. It does not own chip peripheral definitions, interrupt
assignments, clocks, watchdogs, flash image headers, or board memory maps.
Status
This crate currently requires a custom C-SKY Rust target, the csky crate's
temporary LLVM assembly bootstrap, and a patched LLVM/LLD toolchain. The
runtime has been exercised with CK80x QEMU models, but hardware validation and
the exception/interrupt ABI audit are not complete. Treat version 0.0.x as an
experimental interface.
The assembly required before Rust can safely execute is embedded in the Rust
crate with global_asm!; no external assembler or C compiler is invoked by
this crate. Some privileged instructions remain reviewed raw encodings because
LLVM's C-SKY assembler does not yet accept their mnemonics.
CPU and vector-table features
Select exactly one CPU feature for a C-SKY firmware build:
ck801ck802ck803ck804ck805ck807
The default vector table has 32 entries. vector-table-48 and
vector-table-64 append generic external-interrupt entries and are mutually
exclusive. A device crate must define what those external entries mean.
exception-10-interrupt and exception-22-interrupt route the corresponding
architecture exception slot through the common IRQ trampoline. Enable either
only when the target's documented dispatch contract requires it.
nested-interrupt-entry selects the experimental nie/ipush/ipop/nir
entry sequence. Its equivalence to the non-nested save/restore path still
requires profile-specific hardware validation.
Application contract
Add the runtime and architecture crate to the firmware:
[]
= { = "0.0.1", = ["critical-section-single-core"] }
= { = "0.0.2", = ["ck804", "vector-table-64"] }
When developing both crates from local checkouts, patch the registry source so
the application and csky-rt cannot link two different instances of the
architecture crate (which would duplicate its assembly symbols):
[]
= { = "../path/to/csky" }
Define the firmware entry point with the runtime attribute:
!
The macro checks that the function is safe, non-async, takes no arguments, and
returns !. It exports the private runtime symbol used after stack, .data,
and .bss initialization, so applications do not define csky_main directly.
The application still supplies the interrupt dispatcher consumed by the generic runtime:
extern "C"
csky_irq_handler runs in exception context and
must obey the selected profile's interrupt, nesting, acknowledgement, and
stack-usage requirements.
Memory layout and linking
The final firmware supplies a memory.x containing FLASH and RAM regions:
MEMORY
{
FLASH : ORIGIN = 0x00000000, LENGTH = 512K
RAM : ORIGIN = 0x20000000, LENGTH = 64K
}
The addresses above are examples, not C-SKY architectural constants. Use the memory map from the target chip's public documentation.
The runtime aligns the vector table to 1024 bytes, matching C-SKY GCC startup
implementations across the supported CK80x profiles. RAM passed to
relocate_vector_table must have the same 1024-byte alignment; ordinary
[u32; N] alignment is not sufficient by itself.
The crate's build script places link.x on the linker search path. The final
binary still needs to pass -Tlink.x to the linker, normally in the
application's .cargo/config.toml:
[]
= ["-C", "link-arg=-Tlink.x"]
Reset initially points VBR at the vector table in FLASH. A target that needs
mutable vectors can use unsafe { csky_rt::relocate_vector_table(ptr) } while
interrupts remain disabled and after providing correctly aligned, persistent
RAM storage.
Runtime boundary
csky-rt: reset, vector/exception entry, memory initialization, linker sectionscsky: CPU registers, instructions, interrupt masking, critical sections- PAC/HAL/device crate: interrupt controller, peripherals, chip memory map
- board/image tooling: boot headers, checksums, flashing and recovery
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE); or
- MIT License (LICENSE-MIT)
at your option.
Unless explicitly stated otherwise, contributions submitted for inclusion in this project are licensed under the same terms, without additional conditions.