I have tried to keep it functionally identical to the travis workflow. This is a bit tricky for me to test.

There are some minor changes though.

• Added MSRV of 1.51.0 - I just picked a version out of thin air here.
• I could not see an easy way of preventing master branch runs for PRs that have passed so this should run on all.
• For deploying to github pages I'm using a 3rd party action. It looks reasonable and just uses the default repo scoped token.

Hi,

The brew cask command is updated. Will encounter this error when installing the tools.

$ brew cask install gcc-arm-embedded
Error: `brew cask` is no longer a `brew` command. Use `brew <command> --cask` instead.

So this PR mainly just update that specific command for macos.

This was a little boring! There aren't any serious changes except to the exceptions app which has changed around a bit; I haven't thoroughly checked the new assembly but don't have any reason to think it's wrong, just the result of much newer LLVM/Rust.

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

It looked like the link to the edition guide was missing. But it might have been intentional because the edition guide might be moved to doc.rust-lang.org later on (https://github.com/rust-lang-nursery/edition-guide/issues/76) :-)

As mentioned in rust-lang-nursery/embedded-wg#145

Added a CNAME file, this requires related A records to take effect.

See https://help.github.com/articles/setting-up-an-apex-domain/ for domain setup, needs at least 2x DNS A records for embedonomicon on rust-embedded.org pointing to 185.199.108.153 and 185.199.109.153 to become active (4x A records as in the instructions if you feel like it).

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

As we were discussing rust-lang/rust#58500, I realized that there is nowhere other than community blogs that actually discusses how to create a new target. This adds new documentation about creating custom targets and common pitfalls that you may encounter.

The section on memory barrier requirements for DMA previously suggested that memory barriers are only required when using the data cache. This is not the complete story, as reordering can still occur in the write buffer.

The details will depend on how the involved memory is marked (Normal/Device/…), but a common case where barriers will be needed on e.g. a STM32H7x3-series chip is when interfacing with the Ethernet DMA engine. Even if the dcache is disabled, a barrier will be needed before updating the DMA tail pointer to ensure the driver's writes to the newly-queued packet buffer and buffer descriptor will be seen by the hardware.

I'm not sure whether a more thorough explanation would be in scope here, since it depends on platform details, but with this change, readers are at least made aware of the issue. (We recently stumbled over this in an open-source hardware/software project, see https://github.com/quartiq/stabilizer/issues/33.)

Closes #55

Based at #54

If the output of cargo objdump changes only with regard to whitespace, it's probably OK to still pass CI. Most readers probably won't even notice whitespace differences in the first place.

The diff documentation says of whitespace-suppressing options:

The --ignore-space-change (-b) option is stronger than -E and -Z combined. It ignores white space at line end, and considers all other sequences of one or more white space characters within a line to be equivalent.

This ignores only changes within a line -- changes which span multiple lines (i.e. the addition or removal of whitespace-only lines) will still compare as different. This is a good thing, because there are places the book includes a subset of a file based on line numbers.

Fixes #50, #52, #53

~This is a work-in-progress. I'm not sure when I'm going to have time to revisit it -- hopefully within the next week or two. If anyone else feels compelled to take it over, please feel free.~

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

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

This enables assignment through triagebot on this repository, in preparation for the migration from highfive to triagebot for PR assignment.

cc rust-lang/highfive#258 rust-lang/triagebot#433

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.

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.