New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

The embeddonomicon #59

Closed
japaric opened this Issue Mar 11, 2018 · 17 comments

Comments

Projects
None yet
7 participants
@japaric
Copy link
Member

japaric commented Mar 11, 2018

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.

@japaric japaric added the docs label Mar 11, 2018

@jdub

This comment has been minimized.

Copy link

jdub commented Mar 12, 2018

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

@japaric

This comment has been minimized.

Copy link
Member Author

japaric commented Mar 21, 2018

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

This comment has been minimized.

Copy link
Member Author

japaric commented Mar 21, 2018

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

This comment has been minimized.

Copy link
Contributor

ryankurte commented Mar 22, 2018

@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).

@japaric japaric referenced this issue Mar 22, 2018

Closed

Embedded development on stable #42

5 of 6 tasks complete
@ryankurte

This comment has been minimized.

Copy link
Contributor

ryankurte commented Mar 31, 2018

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

This comment has been minimized.

Copy link

whitequark commented Mar 31, 2018

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

This comment has been minimized.

Copy link
Member

andre-richter commented Mar 31, 2018

@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

This comment has been minimized.

Copy link
Member

andre-richter commented Mar 31, 2018

@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

This comment has been minimized.

Copy link
Contributor

ryankurte commented Apr 1, 2018

@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

This comment has been minimized.

Copy link
Member

andre-richter commented Apr 1, 2018

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

This comment has been minimized.

Copy link
Member Author

japaric commented Apr 1, 2018

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

done

@alexreg

This comment has been minimized.

Copy link

alexreg commented Jul 3, 2018

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

@japaric

This comment has been minimized.

Copy link
Member Author

japaric commented Jul 3, 2018

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

This comment has been minimized.

Copy link

alexreg commented Jul 3, 2018

@japaric Thanks for clarifying.

Is the Discovery book hosted somewhere too, right now?

@JoshMcguigan

This comment has been minimized.

Copy link

JoshMcguigan commented Jul 3, 2018

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

@alexreg

This comment has been minimized.

Copy link

alexreg commented Jul 3, 2018

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

@japaric japaric added this to the Preview 2 milestone Jul 17, 2018

@japaric japaric self-assigned this Jul 17, 2018

@japaric

This comment has been minimized.

Copy link
Member Author

japaric commented Aug 2, 2018

@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!

@japaric japaric closed this Aug 2, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment