csky-rt 0.0.4

Experimental C-SKY bare-metal runtime
Documentation

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:

  • ck801
  • ck802
  • ck803
  • ck804
  • ck805
  • ck807

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:

[dependencies]
csky = { version = "0.0.2", features = ["critical-section-single-core"] }
csky-rt = { version = "0.0.4", features = ["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):

[patch.crates-io]
csky = { path = "../path/to/csky" }

Define the firmware entry point with the runtime attribute:

#![no_std]
#![no_main]

#[csky_rt::entry]
fn main() -> ! {
    loop {
        csky::asm::wait();
    }
}

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:

#[unsafe(no_mangle)]
extern "C" fn csky_irq_handler() {
    // Identify and acknowledge the interrupt in the device interrupt
    // controller before returning.
}

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:

[target.'cfg(all(target_arch = "csky", target_os = "none"))']
rustflags = ["-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 sections
  • csky: 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

at your option.

Unless explicitly stated otherwise, contributions submitted for inclusion in this project are licensed under the same terms, without additional conditions.