Skip to main content

xtensa_lx_rt/
lib.rs

1//! Minimal startup/runtime for Xtensa LX CPUs.
2//!
3//! ## Feature Flags
4#![doc = document_features::document_features!(feature_label = r#"<span class="stab portability"><code>{feature}</code></span>"#)]
5#![doc(html_logo_url = "https://docs.espressif.com/projects/rust/esp-rs-grey-bg.svg")]
6#![allow(asm_sub_register, named_asm_labels)]
7#![feature(asm_experimental_arch)]
8#![no_std]
9
10use core::arch::global_asm;
11
12pub use macros::{entry, exception, interrupt, pre_init};
13pub use xtensa_lx;
14
15pub mod exception;
16pub mod interrupt;
17
18#[doc(hidden)]
19#[unsafe(no_mangle)]
20pub unsafe extern "C" fn no_init_hook() {}
21
22unsafe extern "C" {
23    fn __pre_init();
24    fn __post_init();
25
26    fn __zero_bss() -> bool;
27    fn __init_data() -> bool;
28
29    fn main() -> !;
30
31    static _bss_start: u32;
32    static _bss_end: u32;
33
34    static _data_start: u32;
35    static _data_end: u32;
36    static _sidata: u32;
37
38    static _init_start: u32;
39
40    static _stack_start_cpu0: u32;
41}
42
43global_asm!(
44    "
45    // LLVM does not emit `.xtensa.info`. Without an input `.xtensa.info`, GNU ld crashes in
46    // `NOCROSSREFS` checks.
47    .section .xtensa.info,\"\",@note
48    .4byte 12, 32, 1
49    .asciz \"Xtensa_Info\"
50    .ascii \"USE_ABSOLUTE_LITERALS=0\\nABI=0\\n\"
51    .2byte 0
52
53    .section .rwtext,\"ax\",@progbits
54    .literal sym__pre_init, {__pre_init}
55    .literal sym__post_init, {__post_init}
56    .literal sym__zero_bss, {__zero_bss}
57    .literal sym_main, {main}
58
59    .literal sym_stack_start_cpu0, {_stack_start_cpu0}
60
61    .literal sym_init_start, {_init_start}
62    .literal sym_bss_end, {_bss_end}
63    .literal sym_bss_start, {_bss_start}
64    .literal sym__init_data, {__init_data}
65    .literal sym_data_start, {_data_start}
66    .literal sym_data_end, {_data_end}
67    .literal sym_sidata, {_sidata}
68",
69    __pre_init = sym __pre_init,
70    __post_init = sym __post_init,
71    __zero_bss = sym __zero_bss,
72
73    _stack_start_cpu0 = sym _stack_start_cpu0,
74
75    _bss_end =  sym _bss_end,
76    _bss_start =  sym _bss_start,
77    __init_data = sym __init_data,
78    _data_start = sym _data_start,
79    _data_end = sym _data_end,
80    _sidata = sym _sidata,
81
82    _init_start = sym _init_start,
83    main = sym main,
84);
85
86// `Reset` must be a single item: rustc does not emit separate `global_asm!` items in source
87// order.
88cfg_global_asm!(
89    "
90    // _xtensa_lx_rt_zero_fill
91    //
92    // Input arguments:
93    // a2: start address (used as a cursor)
94    // a3: end address
95
96    .section .rwtext,\"ax\",@progbits
97    .global _xtensa_lx_rt_zero_fill
98    .p2align 2
99    .type _xtensa_lx_rt_zero_fill,@function
100_xtensa_lx_rt_zero_fill:
101    entry  a1, 0                  // Leaf function, no need to reserve stack
102    bgeu   a2, a3, .Lfill_done    // If start >= end, skip zeroing
103    movi.n a5, 0
104
105.Lfill_loop:
106    s32i.n a5, a2, 0              // Store the zero at the current cursor
107    addi.n a2, a2, 4              // Increment the cursor by 4 bytes
108    bltu   a2, a3, .Lfill_loop    // If cursor < end, repeat
109.Lfill_done:
110    retw.n
111
112    // _xtensa_lx_rt_copy
113    //
114    // Input arguments:
115    // a2: source address
116    // a3: destination start address (used as a cursor)
117    // a4: destination end address
118
119    .section .rwtext,\"ax\",@progbits
120    .global _xtensa_lx_rt_copy
121    .p2align 2
122    .type _xtensa_lx_rt_copy,@function
123_xtensa_lx_rt_copy:
124    entry  a1, 0                 // Leaf function, no need to reserve stack
125    bgeu   a3, a4, .Lcopy_done   // If start >= end, skip copying
126.Lcopy_loop:
127    l32i.n a5, a2, 0             // Load word from source pointer
128    s32i.n a5, a3, 0             // Store word at destination pointer
129    addi.n a3, a3, 4             // Increment destination pointer by 4 bytes
130    addi.n a2, a2, 4             // Increment source pointer by 4 bytes
131    bltu   a3, a4, .Lcopy_loop   // If cursor < end, repeat
132.Lcopy_done:
133    retw.n
134
135    .section .rwtext,\"ax\",@progbits
136    .global Reset
137    .p2align 2
138    .type Reset,@function
139Reset:
140    entry  a1, 0x10                 // We're using call4/callx4, reserve 16 bytes for register spill area
141    movi   a0, 0                    // Trash the return address. Debuggers may use this to stop unwinding.
142
143    wsr.intenable a0                // Disable interrupts
144
145    l32r   a2, sym_stack_start_cpu0 // a2 is our temporary value register
146    mov    sp, a2                   // Set the stack pointer.
147
148    l32r   a2, sym__pre_init
149    callx4 a2                       // Call the pre-initialization function.
150
151.Linit_bss:
152    l32r   a2, sym__zero_bss        // Do we need to zero-initialize memory?
153    callx4 a2
154    beqz   a6, .Linit_data          // No -> skip to copying initialized data
155
156    l32r   a6, sym_bss_start        // Set input range to .bss
157    l32r   a7, sym_bss_end          //
158    call4  _xtensa_lx_rt_zero_fill  // Zero-fill
159
160.Linit_data:
161    l32r   a2, sym__init_data       // Do we need to initialize data sections?
162    callx4 a2
163    beqz   a6, .Linit_data_done     // If not, skip initialization
164
165    l32r   a6, sym_sidata           // Arguments - source data pointer
166    l32r   a7, sym_data_start       //           - destination pointer
167    l32r   a8, sym_data_end         //           - destination end pointer
168    call4  _xtensa_lx_rt_copy       // Copy .data section
169
170.Linit_data_done:
171    memw    // Make sure all writes are completed before proceeding. At this point, all static variables have been initialized.
172",
173    // According to 4.4.7.2 of the xtensa isa, ccount and compare are undefined on
174    // reset, set all values to zero to disable. ("timer interrupts are cleared by writing CCOMPARE[i]")
175    #[cfg(XCHAL_HAVE_TIMER0)]
176    "wsr.ccompare0 a0",
177    #[cfg(XCHAL_HAVE_TIMER1)]
178    "wsr.ccompare1 a0",
179    #[cfg(XCHAL_HAVE_TIMER2)]
180    "wsr.ccompare2 a0",
181    #[cfg(XCHAL_HAVE_TIMER3)]
182    "wsr.ccompare3 a0",
183    #[cfg(any(
184        XCHAL_HAVE_TIMER0,
185        XCHAL_HAVE_TIMER1,
186        XCHAL_HAVE_TIMER2,
187        XCHAL_HAVE_TIMER3
188    ))]
189    "isync",
190    "
191    l32r   a2, sym_init_start // vector table address
192    wsr.vecbase a2
193
194    l32r   a2, sym__post_init
195    callx4 a2
196
197    l32r   a2, sym_main       // program entry point
198    callx4 a2
199    ",
200);
201
202// We redefine these functions to avoid pulling in `xtensa-lx` as a dependency:
203
204// CPU Interrupts
205unsafe extern "C" {
206    #[cfg(XCHAL_HAVE_TIMER0)]
207    pub fn Timer0(save_frame: &mut crate::exception::Context);
208    #[cfg(XCHAL_HAVE_TIMER1)]
209    pub fn Timer1(save_frame: &mut crate::exception::Context);
210    #[cfg(XCHAL_HAVE_TIMER2)]
211    pub fn Timer2(save_frame: &mut crate::exception::Context);
212    #[cfg(XCHAL_HAVE_TIMER3)]
213    pub fn Timer3(save_frame: &mut crate::exception::Context);
214
215    #[cfg(XCHAL_HAVE_PROFILING)]
216    pub fn Profiling(save_frame: &mut crate::exception::Context);
217
218    #[cfg(XCHAL_HAVE_SOFTWARE0)]
219    pub fn Software0(save_frame: &mut crate::exception::Context);
220    #[cfg(XCHAL_HAVE_SOFTWARE1)]
221    pub fn Software1(save_frame: &mut crate::exception::Context);
222
223    #[cfg(XCHAL_HAVE_NMI)]
224    pub fn NMI(save_frame: &mut crate::exception::Context);
225}
226
227#[doc(hidden)]
228#[unsafe(no_mangle)]
229pub extern "C" fn default_mem_hook() -> bool {
230    true // default to zeroing bss & initializing data
231}
232
233#[doc(hidden)]
234#[macro_export]
235macro_rules! cfg_asm {
236    (@inner, [$($x:tt)*], [$($opts:tt)*], ) => {
237        asm!($($x)* $($opts)*)
238    };
239    (@inner, [$($x:tt)*], [$($opts:tt)*], #[cfg($meta:meta)] $asm:literal, $($rest:tt)*) => {
240        #[cfg($meta)]
241        cfg_asm!(@inner, [$($x)* $asm,], [$($opts)*], $($rest)*);
242        #[cfg(not($meta))]
243        cfg_asm!(@inner, [$($x)*], [$($opts)*], $($rest)*)
244    };
245    (@inner, [$($x:tt)*], [$($opts:tt)*], $asm:literal, $($rest:tt)*) => {
246        cfg_asm!(@inner, [$($x)* $asm,], [$($opts)*], $($rest)*)
247    };
248    ({$($asms:tt)*}, $($opts:tt)*) => {
249        cfg_asm!(@inner, [], [$($opts)*], $($asms)*)
250    };
251}
252
253#[doc(hidden)]
254#[macro_export]
255macro_rules! cfg_global_asm {
256    {@inner, [$($x:tt)*], } => {
257        global_asm!{$($x)*}
258    };
259    (@inner, [$($x:tt)*], #[cfg($meta:meta)] $asm:literal, $($rest:tt)*) => {
260        #[cfg($meta)]
261        cfg_global_asm!{@inner, [$($x)* $asm,], $($rest)*}
262        #[cfg(not($meta))]
263        cfg_global_asm!{@inner, [$($x)*], $($rest)*}
264    };
265    {@inner, [$($x:tt)*], $asm:literal, $($rest:tt)*} => {
266        cfg_global_asm!{@inner, [$($x)* $asm,], $($rest)*}
267    };
268    {$($asms:tt)*} => {
269        cfg_global_asm!{@inner, [], $($asms)*}
270    };
271}