Mutable Global State

[flip111]

https://rust-embedded.github.io/book/peripherals/borrowck.html

Unfortunately, hardware is basically nothing but mutable global state, which can feel very frightening for a Rust developer.

I think this is just pretentious to project feelings onto (a hypothetical) rust developer. Instead provide a technical argument why global state is considered bad. Or link to some other website that explains this.

Hardware exists independently from the structures of the code we write, and can be modified at any time by the real world.

This sentence seems like a very simple statements. But it covers actually something incredibly complex. Program boundaries and which guarantees the compiler can make. I think the wording right here is not good to explain this and also it's not presenting a take-away for the reader or giving an introduction to the next section in the book.

The next section says the word "reliably", implicitly saying before it was "unreliable". This already needs to be covered in the first paragraph. Now it's taking steps which are not easy to follow for someone without some background knowledge. If the background knowledge of the reader would already be there there is no point explaining this in the first place.

[flip111]

Always use volatile methods to read or write to peripheral memory, as it can change at any time

In previous section of book it says:

. In C, we can mark variables as volatile to ensure that every read or write occurs as intended. In Rust, we instead mark the accesses as volatile, not the variable.

try to keep this information in 1 section of the book, avoid trying to explain concepts multiple times to make it more clear.

[flip111]

In software, we should be able to share any number of read-only accesses to these peripherals

No idea what this means. Both from logically reading the sentence (on an english level). As well as the hardware level.

The access is a hardware concept that happens on one point of time (atomically). This can be triggered from multiple sections in the code.

My gut feeling is that this sentence refers to something of the borrow checker or some other guarantees rust provides.

[flip111]

If some software should have read-write access to a peripheral, it should hold the only reference to that peripheral

book makes a too big step how we go from structs to methods to passing around references.

[flip111]

Well, luckliy in the hardware, there is only one instance of any given peripheral

I think "instance" is used as a software term here. Which is strange because it's about hardware. After all there can be two ADC's in one hardware. When we talk about software-hardware functionality mapping. We have 1 software functionality for 2 hardware devices. The opposite can be true as well, where we have for example 1 pin with multiple software functionalities.

I don't have a suggestion for this at the moment, need more knowledge first.

[flip111]

Or link to some other website that explains this.

I read further, this is explained here. https://rust-embedded.github.io/book/peripherals/borrowck.html Consider forward looking sentence or merging these two sections.

[flip111]

I don't have a suggestion for this at the moment, need more knowledge first.

Related?? section of book https://rust-embedded.github.io/book/static-guarantees/state-machines.html

[flip111]

http://blog.japaric.io/brave-new-io/

Physical pins on a microcontroller can be configured as digital inputs, as digital outputs or as peripheral pins (pins associated to peripherals like the USART). We can encode this configuration in the type of a pin to enforce at compile time that a pin has a certain configuration. We can think of the different configurations as the different states the pin can be in. This pattern of encoding states in the type system is known as type state (some people also call it session types).