The embeddonomicon

[japaric]

Triage

2018-07-03

Work left to do here:

• panic_fmt -> #[panic_implementation]
• flip the structure to start with the "doesn't require unstable features" way to build a no-std binary. The appendix will cover unstable features like start, termination, etc.
• cover targeting custom targets (not in rustc --print target-list): sysroot, Xargo, LLVM relationship.

---

This issue is for tracking documentation about low level details that most users won't have to
concern themselves with, but that are still important to document to help others bringing Rust to
new architectures and to help others implement glue crates like cortex-m-rt. This information may
also be relevant to binding RTOSes and other SDKs that take over the booting process.

The (first) topics to cover are:

• What pieces are required to compile and link a no-std Rust program.

• The entry point and life before main. What needs to happen before main and who's responsible of
  doing what.

• Linker (script) magic and how to deal with stuff like the vector table and static registration of
  interrupt handlers -- there are at least two ways to do this; both should be documented.

I don't know what else should be covered.

TODO

• @japaric will make a draft of this. I'll probably write it in a braindump / guide style, and
  will probably need help editing the text into a more readable state.

[jdub]

Happy to help with editing. I'll watch this ticket.

[japaric]

I've put up a first draft for the embedonomicon. I have not proofread it so expect typos and
grammatical errors. It's also probably missing detail in some areas but at least it have all the
topics I wanted to cover.

@jdub Thanks for volunteering; I've added you as a collaborator. Feel free to fix typos and the
like, and to open issues regarding re-structuring things, adding more detail in some places, etc.

@jcsoo @thejpster I think you wanted to read about how cortex-m-rt works. The first draft will
give you an idea. If you think there's anything unclear or that should be expanded open an issue in
the embedonomicon issue tracker.

I've also used the embedonomicon as a chance to figure out how close we are to making no-std
binaries work on stable and we are pretty close, but I'll say more about that in #42.

I think what's left to be answer in this thread is where do we want this documentation to live. cc
@jamesmunns

[japaric]

I think what's left to be answer in this thread is where do we want this documentation to live.

Also how to maintain this document. Sadly mdbook test doesn't work with no_std programs, much less with one that requires a non-standard linking process.

[ryankurte]

@japaric this is really neat!

wrt. where to put it, how about at rust-embedded/docs or similar? That way it'll be accessible as a subdirectory of rust-embedded.org and maintainable as part of the rust-embedded project.
And it's reasonably easy to setup travis-ci to auto build the docs from master into a clean branch to serve up (edit: I see you've already got that running).

[ryankurte]

I've had a go at porting a new platform (not yet successfully) and have run into a couple of issues that might be useful additions to the embeddedonomicon.

The first is a description of target json files and their use for out-of-tree targets (along with a link to rust-lang/rfcs/text/0131-target-specification.md and how to list rustc and llvm targets).

The second is approaches to combine rust with assembly crt0 or other assembly files, there are some cases where you need boot code or ISRs to be full 32-bit arm instructions rather than 16-bit thumb(1/2), and afaik(?) there's no useful way of specifying that with LLVM, so the asm! attribute won't help.

I'm building the crt0 with a build.rs file:

let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());

let mut build = gcc::Build::new();
    build.compiler("arm-none-eabi-gcc").archiver("arm-none-eabi-ar");
    build.flag("-mcpu=arm7tdmi").flag("-mthumb-interwork").flag("-nostdlib");
    build.clone().file("src/gba_crt0.s").compile("gba_crt0.o");
println!("cargo:rerun-if-changed=src/gba_crt0.s");

Which builds correctly and can then be included in the build either with rustflags = [ "-C", "link-arg=-Lgba_crt0" ] in .cargo/config or with "pre-link-args": [ "-Lgba_crt0" ] in target.json.

But I'm struggling to work out how to wire together or replace the _start symbols from the assembled file and rust components, my current attempt is here if you have any thoughts.

Cheers,

Ryan

[whitequark]

and afaik(?) there's no useful way of specifying that with LLVM, so the asm! attribute won't help.

Try .arm or .code32 in inline assembly. Might need some tweaking to make sure interworking works correctly, but I'm quite sure it's possible.

[andre-richter]

@ryankurte:
Edit: pls ignore what I wrote before, didn't see you put the rest of embedonomicon startup stuff in the gba-rs lib.rs. The way you set it up looks like you want crt0.s code to run first, and then call into reset()? In that case you'll need to modify your linker script that execution starts with crt0.s and modify crt0.s to call reset() instead of main().
I did exactly that yesterday, but it's not uploaded yet. If you're patient I can do so tonight for reference.

[andre-richter]

@ryankurte I've uploaded an example for the RPi3 at https://github.com/andre-richter/rust-raspi3-tutorial

It has the _start' init code from the embedonomicon and the reset(), but also has an assembler file that runs before the embedonomicon stuff, like you need it. In my case _boot_cores calls reset(). I think that is what you need too. That _boot_cores runs as the first code in this case is thanks to the linker script, which puts this text section as the first on address 0x800000, which is where RPi3 CPU has its entry point.

Maybe it helps in your case.

[ryankurte]

@whitequark @andre-richter thanks for the help! I got it going with a combination of the two.

It appears global_asm! doesn't support a combination of instruction modes which is a little more complicated, and I still have no idea why the compile and link externally (like one would do with c/c++) approach doesn't work for me when global_asm! does with the same code, but I'd propose the additional startup code stuff might be useful in the embeddonomicon.

[andre-richter]

For the embedded book, in #74, it was agreed to go with CC License for prose and MIT/Apache for code snippets for convenience and easier reuse. @japaric, would you be open to do that for the embedonomicon too?
Currently everything is CC.

[japaric]

would you be open to do that for the embedonomicon too?

done

[alexreg]

Is this meant to be different from https://book.rust-embedded.org/?

[japaric]

Triage: work left to do here:

• panic_fmt -> #[panic_implementation]
• flip the structure to start with the "doesn't require unstable features" way to build a no-std binary. The appendix will cover unstable features like start, termination, etc.
• cover targeting custom targets (not in rustc --print target-list): sysroot, Xargo, LLVM relationship.

---

@alexreg yes, the books have different audiences. See #56 (comment) for details. The nomicon is hosted at https://embedonomicon.rust-embedded.org/

[alexreg]

@japaric Thanks for clarifying.

Is the Discovery book hosted somewhere too, right now?

[JoshMcguigan]

@alexreg The Discovery book is hosted at https://japaric.github.io/discovery/

[alexreg]

Thanks! Will that move to rust-embedded.org at some point too?

[japaric]

@alexreg yes, eventually.

The second edition will all the pending changes listed in the issue description is now up at https://github.com/rust-embedded/embedonomicon and it's being temporarily hosted at https://rust-embedded.github.io/embedonomicon/. If you have feedback on the second edition please use the rust-embedded/embedonomicon issue tracker. Pull requests fixing typos are welcome as well!