csky-rt 0.0.4

Experimental C-SKY bare-metal runtime
Documentation
#![no_std]
#![cfg_attr(target_arch = "csky", feature(asm_experimental_arch))]
#![deny(missing_docs)]

//! Minimal reset-to-Rust runtime for C-SKY bare-metal targets.
//!
//! A device or board supplies `memory.x`. This crate supplies stack setup,
//! `.data`/`.bss` initialization, a generic 32/48/64-entry vector table, and
//! the section layout in `link.x`. It deliberately contains no SoC names,
//! peripheral addresses, interrupt numbers, or board policy.
//!
//! The default 32-entry table maps every non-reset entry to the default
//! exception handler. `vector-table-48` and `vector-table-64` append 16 or 32
//! generic external-interrupt entries. A device runtime may additionally map
//! architecture exception 10 or 22 to the interrupt trampoline when that is
//! its documented dispatch contract.
//!
//! Reset initially points VBR at the table in `FLASH`. Applications that need
//! mutable vectors may call `relocate_vector_table` while interrupts remain
//! disabled. This mirrors the two policies found in C-SKY SDKs without making
//! either one universal: some SDKs retain flash vectors, while others copy
//! the table to RAM and update VBR.

pub use csky_rt_macros::entry;

/// Required byte alignment of a C-SKY vector-table base.
///
/// C-SKY GCC startup implementations align VBR tables to 1 KiB. Keeping the
/// same conservative contract across the supported CK80x profiles also makes
/// flash and relocated RAM tables interchangeable.
pub const VECTOR_TABLE_ALIGNMENT: usize = 1024;

const VECTOR_TABLE_ENTRIES: usize = if cfg!(feature = "vector-table-64") {
    64
} else if cfg!(feature = "vector-table-48") {
    48
} else {
    32
};

#[cfg(target_arch = "csky")]
const EXTERNAL_INTERRUPT_ENTRIES: usize = VECTOR_TABLE_ENTRIES - 32;

#[cfg(target_arch = "csky")]
unsafe extern "C" {
    #[allow(dead_code)]
    fn csky_rt_irq();
    fn csky_rt_default_exception();
    static csky_rt_vector_table: u32;
}

#[cfg(target_arch = "csky")]
macro_rules! emit_runtime {
    ($exception_10:path, $exception_22:path) => {
        core::arch::global_asm!(
            r#"
    .section .vector_table, "a"
    .align 10
    .globl csky_rt_vector_table
csky_rt_vector_table:
    .long csky_rt_reset
    .rept 9
    .long csky_rt_default_exception
    .endr
    .long {exception_10}
    .rept 11
    .long csky_rt_default_exception
    .endr
    .long {exception_22}
    .rept 9
    .long csky_rt_default_exception
    .endr
    /* A 32-entry table ends here. The 48/64-entry modes append generic
       external IRQ slots; the owning device crate defines their meaning. */
    .rept {external_entries}
    .long csky_rt_irq
    .endr

    .section .text.csky_rt_reset, "ax"
    .align 2
    .globl csky_rt_reset
    .type csky_rt_reset, %function
csky_rt_reset:
    lrw r0, __stack_top
    mov16 sp, r0
    lrw r0, csky_rt_vector_table
    .short 0xc000, 0x6421 /* mtcr r0, cr<1, 0> (VBR) */
    .short 0xc100, 0x7420 /* psrset ee */
    br16 csky_rt_start
.Lhalt:
    br16 .Lhalt
    .size csky_rt_reset, . - csky_rt_reset

    .section .text.csky_rt_irq, "ax"
    .align 2
    .globl csky_rt_irq
    .type csky_rt_irq, %function
csky_rt_irq:
    .if {nested_entry}
    nie
    .short 0x1462 /* ipush; LLVM global_asm does not inherit +e1 yet */
    /* `ipush` preserves the low interrupt context. A high-register CPU
       variant must additionally preserve r18-r31, and every wrapper must
       preserve r15 before calling an ordinary Rust function. */
    .if {high_registers}
    .short 0x142e /* subi16 sp, sp, 56 */
    .short 0xd64e, 0x1c2d /* stm32 r18-r31, (sp) */
    .endif
    .short 0x14d0 /* push16 r15 */
    .if {high_registers} == 0
    /* Keep the PC-relative call word-aligned. */
    mov16 r0, r0
    .endif
    jbsr csky_irq_handler
    ld32.w r15, (sp, 0)
    addi16 sp, sp, 4
    .if {high_registers}
    .short 0xd24e, 0x1c2d /* ldm32 r18-r31, (sp) */
    .short 0x140e /* addi16 sp, sp, 56 */
    .endif
    .short 0x1463 /* ipop; LLVM global_asm does not inherit +e1 yet */
    nir
    .else
    subi16 sp, sp, 28
    st32.w r0, (sp, 0)
    st32.w r1, (sp, 4)
    st32.w r2, (sp, 8)
    st32.w r3, (sp, 12)
    st32.w r12, (sp, 16)
    st32.w r13, (sp, 20)
    st32.w r15, (sp, 24)
    subi16 sp, sp, 8
    .short 0xc002, 0x6020 /* mfcr r0, cr<2, 0> (EPSR) */
    st32.w r0, (sp, 4)
    .short 0xc004, 0x6021 /* mfcr r1, cr<4, 0> (EPC) */
    st32.w r1, (sp, 0)
    jbsr csky_irq_handler
    ld32.w r1, (sp, 0)
    .short 0xc001, 0x6424 /* mtcr r1, cr<4, 0> (EPC) */
    ld32.w r0, (sp, 4)
    .short 0xc000, 0x6422 /* mtcr r0, cr<2, 0> (EPSR) */
    addi16 sp, sp, 8
    ld32.w r0, (sp, 0)
    ld32.w r1, (sp, 4)
    ld32.w r2, (sp, 8)
    ld32.w r3, (sp, 12)
    ld32.w r12, (sp, 16)
    ld32.w r13, (sp, 20)
    ld32.w r15, (sp, 24)
    addi16 sp, sp, 28
    .short 0xc000, 0x4020 /* rte */
    .endif
    .size csky_rt_irq, . - csky_rt_irq

    .section .text.csky_rt_default_exception, "ax"
    .align 2
    .globl csky_rt_default_exception
    .type csky_rt_default_exception, %function
csky_rt_default_exception:
    br16 csky_rt_default_exception
    .size csky_rt_default_exception, . - csky_rt_default_exception

    .section .note.GNU-stack, "", %progbits
"#,
            external_entries = const EXTERNAL_INTERRUPT_ENTRIES,
            nested_entry = const cfg!(feature = "nested-interrupt-entry") as usize,
            high_registers = const (cfg!(feature = "high-registers")
                || cfg!(feature = "ck805")
                || cfg!(feature = "ck807")) as usize,
            exception_10 = sym $exception_10,
            exception_22 = sym $exception_22,
        );
    };
}

#[cfg(all(
    target_arch = "csky",
    feature = "exception-10-interrupt",
    feature = "exception-22-interrupt"
))]
emit_runtime!(csky_rt_irq, csky_rt_irq);

#[cfg(all(
    target_arch = "csky",
    feature = "exception-10-interrupt",
    not(feature = "exception-22-interrupt")
))]
emit_runtime!(csky_rt_irq, csky_rt_default_exception);

#[cfg(all(
    target_arch = "csky",
    not(feature = "exception-10-interrupt"),
    feature = "exception-22-interrupt"
))]
emit_runtime!(csky_rt_default_exception, csky_rt_irq);

#[cfg(all(
    target_arch = "csky",
    not(feature = "exception-10-interrupt"),
    not(feature = "exception-22-interrupt")
))]
emit_runtime!(csky_rt_default_exception, csky_rt_default_exception);

const CPU_FEATURE_COUNT: usize = cfg!(feature = "ck801") as usize
    + cfg!(feature = "ck802") as usize
    + cfg!(feature = "ck803") as usize
    + cfg!(feature = "ck804") as usize
    + cfg!(feature = "ck805") as usize
    + cfg!(feature = "ck807") as usize;

const _: () = assert!(
    CPU_FEATURE_COUNT <= 1,
    "csky-rt CPU features are mutually exclusive"
);

#[cfg(target_arch = "csky")]
const _: () = assert!(
    CPU_FEATURE_COUNT == 1,
    "select exactly one csky-rt CPU feature: ck801, ck802, ck803, ck804, ck805, or ck807"
);

#[cfg(all(feature = "vector-table-48", feature = "vector-table-64"))]
compile_error!("csky-rt vector-table-48 and vector-table-64 are mutually exclusive");

#[cfg(all(feature = "nested-interrupt-entry", feature = "ck807"))]
compile_error!(
    "csky-rt nested-interrupt-entry is not supported on CK807; use the non-nested exception frame"
);

#[cfg(all(feature = "high-registers", any(feature = "ck801", feature = "ck802")))]
compile_error!("csky-rt high-registers is not available on CK801 or CK802");

#[cfg(target_arch = "csky")]
unsafe extern "C" {
    static mut __bss_start: u8;
    static mut __bss_end: u8;
    static mut __data_start: u8;
    static mut __data_end: u8;
    static __data_load: u8;

    fn csky_main() -> !;
}

/// Returns the number of entries emitted in the selected vector table.
#[inline]
pub const fn vector_table_entries() -> usize {
    VECTOR_TABLE_ENTRIES
}

/// Returns the required byte alignment of a vector-table base.
#[inline]
pub const fn vector_table_alignment() -> usize {
    VECTOR_TABLE_ALIGNMENT
}

/// Copies the flash vector table to RAM and points VBR at the copy.
///
/// The reset path uses the immutable flash table by default. This function is
/// the explicit alternative for devices that require mutable vectors.
///
/// # Safety
///
/// `destination` must be non-null, writable, aligned to
/// [`VECTOR_TABLE_ALIGNMENT`], and valid for [`vector_table_entries`] `u32`
/// values. It must not overlap the source flash table and must remain allocated
/// for as long as VBR refers to it. Interrupts and exceptions that use the
/// table must remain masked until copying and VBR replacement complete.
#[cfg(target_arch = "csky")]
pub unsafe fn relocate_vector_table(destination: *mut u32) {
    let source = core::ptr::addr_of!(csky_rt_vector_table);
    for index in 0..VECTOR_TABLE_ENTRIES {
        unsafe {
            destination
                .add(index)
                .write_volatile(source.add(index).read_volatile());
        }
    }
    csky::asm::sync();
    unsafe { csky::register::vbr::write(destination as u32) };
}

/// Symbol referenced by the assembly reset entry.
///
/// # Safety
///
/// This must be entered only by the runtime reset assembly after establishing
/// a valid stack and masking interrupts.
#[cfg(target_arch = "csky")]
#[unsafe(no_mangle)]
pub unsafe extern "C" fn csky_rt_start() -> ! {
    unsafe {
        csky::interrupt::disable();
        initialize_data();
        zero_bss();
        csky_main()
    }
}

#[cfg(target_arch = "csky")]
unsafe fn initialize_data() {
    let mut source = core::ptr::addr_of!(__data_load);
    let mut destination = core::ptr::addr_of_mut!(__data_start);
    let end = core::ptr::addr_of_mut!(__data_end);

    if !core::ptr::eq(source, destination.cast_const()) {
        while destination < end {
            unsafe {
                destination.write_volatile(source.read_volatile());
                destination = destination.add(1);
                source = source.add(1);
            }
        }
    }
}

#[cfg(target_arch = "csky")]
unsafe fn zero_bss() {
    let mut current = core::ptr::addr_of_mut!(__bss_start);
    let end = core::ptr::addr_of_mut!(__bss_end);

    while current < end {
        unsafe {
            current.write_volatile(0);
            current = current.add(1);
        }
    }
}

#[cfg(test)]
mod tests {
    #[test]
    fn vector_table_uses_conservative_vbr_alignment() {
        assert_eq!(super::vector_table_alignment(), 1024);
        assert!(super::vector_table_alignment().is_power_of_two());
    }

    #[test]
    #[cfg(not(any(feature = "vector-table-48", feature = "vector-table-64")))]
    fn default_vector_table_has_32_entries() {
        assert_eq!(super::vector_table_entries(), 32);
    }

    #[test]
    #[cfg(feature = "vector-table-48")]
    fn selected_vector_table_has_48_entries() {
        assert_eq!(super::vector_table_entries(), 48);
    }

    #[test]
    #[cfg(feature = "vector-table-64")]
    fn selected_vector_table_has_64_entries() {
        assert_eq!(super::vector_table_entries(), 64);
    }
}