rust-embedded / embedonomicon Goto Github PK

The grep command in smallest-no-std.md should exclude N, not lowercase n.

This is causing #52

First of all: I'm sorry if this is the wrong place to ask, but at least it's related to the book :)

While reading the Embedonomicon I wrote some bare metal stuff without using any crate. Just for learning how everything works together. I didn't find out why this source code:

    // Copy DATA
    let mut sdata = &mut _sdata as *mut u32;
    let edata = &mut _edata as *mut u32;
    let mut sidata = &_sidata as *const u32;
    while sdata < edata {
        ptr::write(sdata, ptr::read(sidata));
        sdata = sdata.offset(1);
        sidata = sidata.offset(1);
    }

was compiled to this assembly (copied from gdb):

│   0x8000026 <rustymc::run+18>     ldmia   r1!, {r2}                                                │
│   0x8000028 <rustymc::run+20>     stmia   r0!, {r2}                                                │
│  >0x800002a <rustymc::run+22>     b.n     0x8000026 <rustymc::run+18>                              │

An endless loop which will write to invalid memory sooner or later.

I boiled it down to a minimal program which is attached. I used rustc 1.47.0 and cargo run --release.

What's wrong with my code?

v3mini.tar.gz

I was wondering how one would go about creating a target for unsupported embedded architectures (as of now) for the Rust Embedded Ecosystem ?. Eg the 8051 families of Microcontrollers

I'd fix it myself, but I did a bit of digging and not exactly sure why it's not linking properly. I'm assuming someone else will be able to find it much more quickly :)

https://rust-embedded.github.io/embedonomicon/memory-layout.html, which is what shows up in hyperlinks in the Embedonomicon, ends up taking you to http://embedonomicon.rust-embedded.org/memory-layout.html.

Thanks for this resource - learned a lot from it.

Thank for the great documentation!

I have a question about EXTERN, which is described in https://docs.rust-embedded.org/embedonomicon/memory-layout.html#extern

When I comment this line out, the output still seems to have all of its content. I also tried it with cargo clean and with --release. As I like to understand everything, can you explain or show an example where it is actually needed?

If one happens to have a Cargo.toml profile set to unwinding panics, a language item required, but not found: 'eh_personality' error will result. PR #42 adds a brief note explaining how to resolve the error.

It appears that the DMA API described in Chapter 8 - DMA is unsafe.

Consider this example. It is basically the motivating example from the "Immovable buffers" section, but with the complete read_exact API from the end of the chapter, including Pining and the 'static bound. The example shows that it is still possible to pass a stack-allocated array into this (supposedly safe) read_exact function, which means the DMA operation will corrupt the stack. All you need to do is wrap the array in a newtype and impl DerefMut for it.

I believe the root of the issue is a misunderstanding of the Pin API. Contrary to intuition, Pin does in most cases not pin the pointed-to data in memory: If the target type implements Unpin, Pin does nothing at all:

Many types are always freely movable, even when pinned, because they do not rely on having a stable address. This includes all the basic types (like bool, i32, and references) as well as types consisting solely of these types. Types that do not care about pinning implement the Unpin auto-trait, which cancels the effect of Pin<P>.

Basically all types we care about implement Unpin (I believe only self-referential types are supposed not to?). Which means Pining the buffer passed into the DMA doesn't help us make the code safe.

The DMA chapter also mentions the StableDeref trait as an alternative. As far as I see, using this would actually lead to a safe API, so we should change the chapter accordingly.

See #31 and rust-embedded/book#59

With link.x as specified in the book, cargo rustc -- -C link-arg=-Tlink.x produces

   Compiling no_std_app v0.1.0 (/home/austin/repos/personal/no_std_experiment)
error: linking with `rust-lld` failed: exit code: 1
  |
  = note: "rust-lld" "-flavor" "gnu" "-L" "/home/austin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/thumbv7m-none-eabi/lib" "/home/austin/repos/personal/no_std_experiment/target/thumbv7m-none-eabi/debug/deps/no_std_app-1e7c0fdb8e33f523.2ohn928r55zfdn1z.rcgu.o" "-o" "/home/austin/repos/personal/no_std_experiment/target/thumbv7m-none-eabi/debug/deps/no_std_app-1e7c0fdb8e33f523" "--gc-sections" "-L" "/home/austin/repos/personal/no_std_experiment/target/thumbv7m-none-eabi/debug/deps" "-L" "/home/austin/repos/personal/no_std_experiment/target/debug/deps" "-L" "/home/austin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/thumbv7m-none-eabi/lib" "-Bstatic" "/home/austin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/thumbv7m-none-eabi/lib/librustc_std_workspace_core-9864ecb2f3ae85f5.rlib" "/home/austin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/thumbv7m-none-eabi/lib/libcore-a54bcae7919f0f3f.rlib" "/home/austin/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/thumbv7m-none-eabi/lib/libcompiler_builtins-a509ea259a1bcbbf.rlib" "-Tlink.x" "-Bdynamic"
  = note: rust-lld: error: no memory region specified for section '.ARM.exidx'
          

error: aborting due to previous error

error: could not compile `no_std_app`.

To learn more, run the command again with --verbose.

This can be fixed by adding a bar .arm.exidx to the /DISCARD/ section of the script.

In following the embedonomicon I discovered that cargo objdump --bin app -- -d -no-show-raw-insn no longer works, for two reasons

1. llvm-objdump no longer accepts --arch-name
2. -no-show-raw-insn must have two -s instead of one on stable.

This is on https://docs.rust-embedded.org/embedonomicon/memory-layout.html#inspecting-it

If there's any extra content that we should ship in the embedonomicon for the 2018 edition all requests should be reported here at least 2 weeks before RC1.

I'm seeing

++grep '[0-9]* [^n] '
++cargo nm -- target/thumbv7m-none-eabi/debug/deps/app-5f2cff0f74a056ac.o
0a1,106
> 00000000 N 
> 00000039 N 
> 00000045 N 
> 00000087 N 
> 0000008c N 
> 00000090 N 
> 00000093 N 
> 00000096 N 
> 00000099 N 
> 0000009e N 
> 000000a4 N 
> 000000ab N 
> 000000b3 N 
> 000000bd N 
> 000000c4 N 
> 000000c7 N 
> 000000cb N 
> 000000d2 N 
> 000000d6 N 
> 000000e8 N 
> 000000ee N 
> 000000f0 N 
> 000000f7 N 
> 000000ff N 
> 00000103 N 
> 0000010b N 
> 00000113 N 
> 0000011a N 
> 00000120 N 
> 00000134 N 
> 00000140 N 
> 00000145 N 
> 0000014d N 
> 00000154 N 
> 00000158 N 
> 0000015d N 
> 00000164 N 
> 0000016d N 
> 00000177 N 
> 0000017e N 
> 00000183 N 
> 0000018f N 
> 00000197 N 
> 000001a0 N 
> 000001a5 N 
> 000001a8 N 
> 000001ac N 
> 000001b5 N 
> 000001bc N 
> 000001c1 N 
> 000001c6 N 
> 000001cc N 
> 000001d2 N 
> 000001dc N 
> 000001df N 
> 000001e5 N 
> 000001ef N 
> 000001f7 N 
> 000001fd N 
> 00000203 N 
> 0000020e N 
> 00000217 N 
> 0000023a N 
> 00000259 N 
> 0000025b N 
> 00000260 N 
> 00000287 N 
> 0000028c N 
> 00000292 N 
> 00000298 N 
> 0000029b N 
> 000002aa N 
> 000002b1 N 
> 000002b5 N 
> 000002be N 
> 000002ca N 
> 000002e3 N 
> 000002e8 N 
> 000002f9 N 
> 00000303 N 
> 00000311 N 
> 00000315 N 
> 00000320 N 
> 00000327 N 
> 0000032d N 
> 00000331 N 
> 00000335 N 
> 0000033d N 
> 00000354 N 
> 00000378 N 
> 00000394 N 
> 0000039e N 
> 000003b8 N 
> 00000416 N 
> 00000421 N 
> 0000043e N 
> 00000457 N 
> 00000461 N 
> 00000477 N 
> 00000495 N 
> 0000049e N 
> 000004a3 N 
> 000004a8 N 
> 000004ac N 
> 000004b5 N 
> 000004bf N 
The command "bash ci/script.sh" exited with 1.

on #51. I suspect that if the script gets further, it may choke on the issue in #50 itself, and there may be more things.

Initially written referencing this older version of the objdump output, the "Exception Handling" chapter vector table objdump output for section "Testing It" is now inconsistent since this commit changed the output.

All the code snippets must be using 2018 edition features and must compile on 1.30-beta by RC1.

The two I've seen are:

warning: trait objects without an explicit `dyn` are deprecated
 --> /home/austin/repos/personal/embedonomicon/ci/asm/rt/build.rs:5:29
  |
5 | fn main() -> Result<(), Box<Error>> {
  |                             ^^^^^ help: use `dyn`: `dyn Error`
  |
  = note: `#[warn(bare_trait_objects)]` on by default

and

warning: unused `core::result::Result` that must be used
  --> src/main.rs:22:5
   |
22 |     writeln!(hstdout, "{:#x}", &B as *const u8 as usize);
   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: this `Result` may be an `Err` variant, which should be handled
   = note: this warning originates in a macro outside of the current crate (in Nightly builds, run with -Z external-macro-backtrace for more info)

It should be relatively easy to fix these both

Some pages have this misprint in parameters of objdump call.

Pages:

https://docs.rust-embedded.org/embedonomicon/main.html
https://docs.rust-embedded.org/embedonomicon/exceptions.html
https://docs.rust-embedded.org/embedonomicon/asm.html

We can't test the code snippets embedded in the book because mdbook doesn't support building #![no_std] code, but we can add snapshots of the Cargo project built throughout the book to this repository and test building those snapshots in CI.

These three snapshots should be tested:

• End of chapter 2 ("Memory layout"),
• End of chapter 3 ("A main interface"), and
• End of chapter 4 ("Exception handling").

We should add links back to the main bookshelf (docs.rust-embedded.org) and to the FAQ to the front page of the embedonomicon.

If linker flavor inference doesn't make it into 1.30-beta we'll have to use arm-none-eabi-gcc to avoid the unstable -Z linker-flavor flag.

We should add a topic about implementing your own panic_unwind crate. I know this involves the "eh_personality" lang item but I have never done this myself. If someone has a working example that would be very useful!

As unwinding depends on an unstable feature this topic is not a blocker for the edition release.

#54 had to fix a lot of objdumps because whitespace changed in the expected output. It seems to me that whitespace changes here are not a big deal, and could be ignored.

@jamesmunns what would be the way to go here? Set travis CI to re-generate the gh-pages on each commit and use the CNAME file to set embedonomicon.rust-embedded.org as the domain name?

It seems GH pages now support https with custom domain names: https://blog.github.com/2018-05-01-github-pages-custom-domains-https/

Let us know if you had to significantly deviate from the instructions! (Other than using different built-in commands if you were using cmd instead of bash).

The links in this repository (repo summary and README at least) still point to the github.io site, but progress on rust-embedded/wg#208 have made those links inaccessible. The links should be updated to https://docs.rust-embedded.org/embedonomicon/

Let us know if you had to significantly deviate from the instructions!

My apologies if this is not the correct place to put this issue. I couldn't find a better one.

I am looking into creating a new board crate, but am also a relative newbie to the ARM architecture. As a result, I am having to learn a lot about how the ARM ecosystem itself works.

For example, the chip I'm looking at comes with an SDK, which is good enough if you are looking at their chip and writing one project in C. But in Rust, we want to look further than just one project on one chip, in addition to being a different language.

As a result, I had to figure out that the SDK was really a version of CMSIS-RTOS with patches on top -- and that CMSIS was something ARM built for OEMs to make their SDKs, CMSIS-RTOS being a now-unsupported variant thereof. That gave me an approach to figuring out what was new, and what was already taken care of by the cortex-rt crate.

There is an explanation of ARM's hardware designations and features, and how they map to Rust targets. I feel it would help others to have a similar section for software artifacts: a high-level overview of C code that ARM gave to OEMs to write their SDKs, what is handled already by equivalent libraries in the Rust ecosystem, and what kinds of things board crate writers should look for as they do a port to Rust from that source code.

The tools have changed the output format so our CI needs to be updated accordingly.
PRs to merge after fixing this:

• #74
• #75
• #76
• Any newer one

16.04 instructions did not work for me and some search results suggested this has changed for 18.04.
Not sure if this is the best way now, but these instructions worked: #38

The affected pages are these two.
https://docs.rust-embedded.org/embedonomicon/exceptions.html
https://docs.rust-embedded.org/embedonomicon/memory-layout.html

In chapter 2, it says "This is the disassembly of the .text section. We see that the reset handler, named Reset, is located at address 0x8." but that cannot be seen in the disassembly. In chapter 4 there is a similar mistake; the book says "The address of the Reset handler can be seen in the disassembly above, being 0x44." but this can't be seen.

A different oddity is that in Chapter 4 it says that address 0x0000_0045 means "jump to address 0x44". This lines up with what I expect from the explanation. We read the address, the lowest bit is 1, so function is run in "thumb mode" and we consider the actual address to be 0x44 since that is 0x45 with the lowest bit set to 0.
But then it says the address 0x83, which is 0b1000_0011, should be understood as 0x84 which is 0b1000_0100. This doesn't make sense to me.

There were files without a .o suffix containing symbos (reset handler and RESET_VECTOR symbol). I'm not sure if this is what the documentation intended to show, but if so, I am on rust 1.32.0, so this may have changed?. Documentation updated as per #39.

Note contents of #include ../ci/smallest-no-std/app.o.nm shows rust_begin_unwind` differ from above.