document use of naked_functions

[orangecms]

We're using a naked function: (rfc2972) in sunxi/nezha at the moment. See also naked-functions

We should document that that is the way to go, and why.

https://interrupt.memfault.com/blog/zero-to-main-rust-1#the-reset-handler-for-real
looks very promising, like we could get rid of asm, just pull the symbols from the LD - BUT... wait, not so fast!
Rust Embedded folks say it's undefined behavior (UB) in some regards sweat_smile

via @jamesmunns:

A lot of the core problem is:

• Rust assumes certain things about the world before it starts (e.g. statics are initialized)
• Rust assumes certain things are ALWAYS true (there is never aliasing access to variables)
• Therefore: you can't initialize your own program from within your own program, because it would break one or both of the above statements

This is also true in C/C++, for the record
so, you COULD write that code in Rust, it just CAN'T be the same "program". e.g. a bootloader could do that initialization for the program it loads, but the program cannot do it itself
the reason we usually "fall back" to ASM for this is that ASM has essentially no "environment rules", e.g. there are no invariants to violate, therefore there can be no undefined behavior (i'm sure this statement could be lawyered, but you get the point)
in the old days, we wrote crt0 in Rust
it was decided that this was (at least theoretically) a bad idea
now we use inline asm
(or global asm? Not sure exactly. But asm inits the world before we get to rust)
it's also not uncommon (in C/C++ embedded) projects to see a startup_$PLATFORM.s file in the build directories

via @adamgreig:

currently the cortex_m_rt reset vector is a bastardised global_asm, hopefully soon a naked_fn

[orangecms]

Note: naked functions are not yet stable, which is at least one reason why we need to remain on nightly; see also:

• Tracking Issue for RFC #2972: Constrained Naked Functions  rust-lang/rust#90957 (comment)
• Stabilize naked_functions rust-lang/rust#93587