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.
high-registers adds r18 through r31 to that nested frame for CPU variants
that implement the optional high-register bank, including CK804E/CK804EF.
CK805 and CK807 select the high-register frame implicitly. Plain CK804 does
not: CK804 is an architecture family name, while the E variant is what adds
the high-register/DSP extension in the compiler CPU tables.
CK807 currently supports only the non-nested runtime frame. Although it
inherits encodings from earlier ISA levels, the vendor compiler does not mark
the CK807 architecture as supporting its ISR prologue contract, and the CK807
QEMU model stalls on the first interrupt with the nested frame. The crate
therefore rejects ck807 plus nested-interrupt-entry at compile time.
The experimental nested wrapper currently preserves integer registers only. Do not use it with a target that permits hardware floating-point instructions: soft-float describes the calling convention and does not necessarily disable LLVM's FPU instruction selection. A target using this wrapper must disable its FPU features until floating-point context preservation is implemented.
Application contract
Add the runtime and architecture crate to the firmware:
[]
= { = "0.0.2", = ["critical-section-single-core"] }
= { = "0.0.4", = ["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.