rust-embedded / book Goto Github PK

Add a small section that parallels the "who Rust is for" section from the Rust book to the landing page (introduction chapter).

cc @jamesmunns

Working through the book for the first time, cross compiling failed because I didn't have the cortex-m-quickstart dependencies installed.

It could be worthwhile including an extra step in the Getting Started/QEMU/Cross compiling section, namely to run: rustup target add thumbv7m-none-eabi.

See: https://rust-embedded.github.io/book/intro/hardware.html

The image link says https://rust-embedded.github.io/assets/f3.jpg ; it should be https://rust-embedded.github.io/book/assets/f3.jpg

when i go here https://github.com/rust-embedded/book/blob/15c4b8f60b924db32069ff49322dfc106d719b79/src/intro/install/linux.md#packages

and go to the box with the sudo command and click on the copy icon on the right, i copy:

$ sudo apt-get install \
  gdb-multiarch \
  openocd \
  qemu-system-arm

but $ is not accepted by my terminal.

The book contains various links to rendered docs stored in the repository, pointing to https://rust-embedded.github.io/cortex-m-rt/ (and potentially others), those should be replaced by links to the appropriate docs.rs sites.

From @japaric on July 17, 2018 14:37

In this section we cover how to get data structures like std::Vec and std::String working in #[no_std] applications. There are two ways: (a) using the alloc crate, #[global_allocator] and #[alloc_error] -- heap allocated collections -- and (b) using the heapless crate -- fixed capacity collections. There should be a subsection that covers the advantages and disadvantages of using one or the other.

Copied from original issue: rust-embedded/wg#125

When it comes to embedded development, I'm fairly used to not debugging. On a related note I'm not used to gdb. Is there any way I can build with cargo and then just use openocd to push the compiled bytes to my device? All the documentation I've seen requires gdb to flash the program to the board. Would this be worth adding to the book?

Secondly, where do I ask questions about embedded rust dev? Making an issue like this seems a bit clunky, but I couldn't find any info related to this topic either.

Triage(2018-08-20)

We have identified 4 topics so far and need help writing them. See #9 (comment) for details.

From @japaric on July 17, 2018 14:44

We agreed on having a section containing tips for embedded developers that have a C / C++ background. For example, they may be used to using for loop + indexing on arrays but it's more efficient to use iterators in Rust so they should use that instead.

Anything else that should be covered? cc @thejpster

Copied from original issue: rust-embedded/wg#126

First of all, thanks to all contributors for your great effort!

I wonder if I'm overlooking something but is there no downloadable version of this book? If not, how hard is it to compile a pdf/epub/mobi myself?

Related to #1.

We won't block the book on this but it would be useful to develop and collate resources on integrating Rust (and Cargo) with build systems such as make and cmake. We can then include them in the interoperability chapter.

From @jamesmunns on July 10, 2018 9:32

This section covers the equivalent of getting "Hello World" working for an embedded target. Examples should start high level, and build back up towards that point.

Copied from original issue: rust-embedded/wg#117

Should we be using Rust 2018 syntax in the book? The main change would be removing extern crate statements.

Here https://github.com/rust-embedded/book/blob/aadfc95f85e635c6a37a7b12ae9255fd39b08b36/src/intro/install/linux.md#udev-rules

Create this file in /etc/udev/rules.d with the contents shown below.

this is not referring to something the reader has already read. It's not good in english to refer to it or this before it was mentioned. Further cat /etc/udev/rules.d/70-st-link.rules should not be the contents of the file (obviously).

Suggested fix 1:

Create the file /etc/udev/rules.d/70-st-link.rules with the contents shown below.

Suggested fix 2:
Provide a command (cat + heredoc into file?) to write the file in one go

Suggested fix 3:
provide a command to open an editor

Moved from #36

I would like to see the following introduced to the embedded-hal/portability chapter:

• Examples (we've already discussed)
• Commentary on why these traits are useful, (N*M vs N+M implementation, where N is # of chip/board support crates, and M is the # of driver traits).

Additionally, we may want something like this image, to demonstrate how this all fits together, and we may want to talk about the different components in the ecosystem somewhere:

• Peripheral Access Crates
• HAL Implementations
• Board Support Crates
• embedded-hal
• Driver Crates
• no_std libraries/crates (such as heapless, menu, etc.)

Just a heads up, I've been refreshing myself on the nuances of OpenOCD-based HAL fun and hit this when following the discovery book:

Fauna2:bma222e me$ cargo run --example hello
   Compiling cortex-m-rt v0.6.7    # This is currently 0.6.5 in the project
   Compiling bma222e v0.1.0 (/Users/me/Documents/Code/rust/bma222e)
    Finished dev [unoptimized + debuginfo] target(s) in 1.07s
     Running `arm-none-eabi-gdb -q -x openocd.gdb target/thumbv7m-none-eabi/debug/examples/hello`
Reading symbols from target/thumbv7m-none-eabi/debug/examples/hello...
cortex_m_semihosting::export::hstdout_fmt (args=...)
    at /Users/me/.cargo/registry/src/github.com-1ecc6299db9ec823/cortex-m-semihosting-0.3.2/src/export.rs:44
44	    interrupt::free(|_| unsafe {
Breakpoint 1 at 0x1424: file /Users/me/.cargo/registry/src/github.com-1ecc6299db9ec823/cortex-m-rt-0.6.7/src/lib.rs, line 553.
Function "UserHardFault" not defined.
Make breakpoint pending on future shared library load? (y or [n]) [answered N; input not from terminal]
Breakpoint 2 at 0x1390: file /Users/me/.cargo/registry/src/github.com-1ecc6299db9ec823/panic-halt-0.2.0/src/lib.rs, line 33.
Breakpoint 3 at 0x49a: file examples/hello.rs, line 13.
semihosting is enabled
Loading section .vector_table, size 0x400 lma 0x0
Loading section .text, size 0x1210 lma 0x400
openocd.gdb:29: Error in sourced command file:
Load failed
(gdb)

I'm assuming this is what broke it all:

rust-embedded/cortex-m-rt@790e424

From @japaric on February 26, 2018 15:57

We have instructions for doing embedded development from the command line but we are missing
instructions for doing embedded development in an IDE.

I heard that VS Code plus the cortex-debug extension works nicely for embedded development but I
have no first hand experience.

We are looking for someone who can help us write down some instructions.

Tasks

• Write instructions for setting up a Cargo project in VS code including instructions for
  setting up the cortex-m extension, Xargo and the RLS. It could be any other IDE but VS code is the
  IDE with official RLS support.

• Bonus points if you write instructions for getting semihosting, ITM / SWO, register (SVD) view
  to work.

• Identify any changes that we could make to cortex-m-quickstart to make integration with VS
  Code, or any other IDE, easier. Like checking in some configuration file (?).

Copied from original issue: rust-embedded/wg#54

Let's write down the requirements for memory safe DMA transfers so that people can experiment with DMA abstractions independently.

The goal of the issue is to make Embedded Book multilingual.

From @jamesmunns on July 10, 2018 9:15

Update

We revised the outline during the meeting held on 2018-07-16 and came up with the following sections:

• Introduction - #116
  • covers setup
  • what #[no_std] means: no I/O (filesystems), allocation, etc.
• Blinking Your First LED - #117
  • use cortex-m-rt
  • emphasis on zero cost abstractions: high level vs unsafe manual way (same disassembly)
• "Static guarantees" - #118
  • static configuration, use svd2rust for the example
• Portability - #119
  • examples: embedded-hal + drivers
• The singleton pattern (*)
  • examples: static configuration, memory pools
• Concurrency - #124
  • examples: static+interrupts, RTFM
• Dynamic data structures - #125
  • fixed capacity collections: heapless
  • heap allocated collections: #[global_allocator], #[alloc_error]
• Tips for embedded C developers - #126
  • e.g. iterators instead of for loop + indexing
• Interop - #48
  • Binding a C SDK, Rust program on top (a little C with your Rust)
  • Exposing Rust code to a C program (a little Rust with your C)

We will probably reorder the sections in the future but we were content with the selection of topics.

(*) I see quite a bit of overlap between singletons and the "static guarantess" and "dynamic data structures" sections. It may be best to write those two first and the decide whether we want a standalone section on singletons (I think a standalone section would end up being too short and / or may not properly showcase its usefulness without applying it to something like configuration or memory management).

This issue is for decisions on the layout or outline of the book contents.

The outline can be seen as markdown, or rendered. Also check out the book tag on issues.

We will open new issues for managing chapters and sections of the book.

Current Section Outline:

1. Introduction - Issue
2. Blinking Your First LED - Issue
3. Embedded-HAL Ecosystem
   • 3A: Static Guarantees - Issue
   • 3B: Portability - Issue
4. Tock-OS Ecosystem - (No Tracking Issue)
5. Interoperability - (No Tracking Issue)
6. Testing - (No Tracking Issue)
7. Unsorted - (No Tracking Issue)

Copied from original issue: rust-embedded/wg#115

http://book.rust-embedded.org/ says 404 and http://rust-embedded.github.io/book forwards to the first url.

On the upcoming Rust website revision, we link to sections of the embedded book. We need to finalize/freeze these chapter names, so the links will be consistent (for now):

• Static Guarantees
  • #5
  • https://rust-embedded.github.io/book/static-guarantees/static-guarantees.html
• Dynamic Data Structures/Flexible Memory Management
  • #8
  • https://rust-embedded.github.io/book/collections/collections.html
• Concurrency
  • #7
  • https://rust-embedded.github.io/book/concurrency/concurrency.html
• Interoperability
  • #1
  • https://rust-embedded.github.io/book/interoperability/interoperability.html
• Portability
  • #6
  • https://rust-embedded.github.io/book/portability/portability.html

Currently we discuss peripherals/memory mapped registers in two places:

1. https://github.com/rust-embedded/book/blob/master/src/start/registers.md
2. https://github.com/rust-embedded/book/tree/master/src/peripherals

I think there is a little bit of overlap here, but generally the second portion covers a little more theory on why we don't do it like C does, but I haven't written the part that explains what we actually do instead. Instead there is just a placeholder. I think portion 1 above is generally most of what I wanted to cover in this section.

CC @thejpster for thoughts

In #58 the mdbook version was temporary hardcoded to v0.2.1 due to inavailability of the correct files for install.sh. As soon as those are available again this PR needs to be backed out.

The latest website page craze is to set the color of the text as gray. No doubt there is a long-winded explanation from page designers. Maybe it's the font choice. No matter how you "view" it, It's a FAIL. Maybe the font imposed this or some CSS was dropped onto the markup. I'm trying to avoiding Monkey-ing around with the DOMs.
See or not see here: https://github.com/rust-embedded/wg

Some people, like myself, need the black text on an almost white background to read the text. Sometimes the managers need to step-forward & assert design standards to web page developers.

Add a way to change the page text colors using the font change choice I've seen at the top of some website pages. This feature could also help when programmers have spent too much continuous time programming. That is, they are just plain tired.

From @jamesmunns on July 10, 2018 9:34

How can use of Rust improve portability between Projects, Targets, or even Operating Systems?

Copied from original issue: rust-embedded/wg#119

https://github.com/rust-embedded/book/blob/master/book.toml#L2 is wildly wrong, and I think it makes sense to add a page of contributors to the book.

At least, we should point back to the resources team, but I would be in favor of having a "Thanks" page at the end of the book, listing all of the contributors.

As mentioned in 2018-10-02 meeting by @japaric :

therealprof: I think it makes sense to have a chapter on profiling covering cargo-bloat, stack-sizes and other tools, if any

Triage(2018-08-21)

We need help writing the initial content for this section.

From @japaric on February 22, 2018 13:29

An approach that has worked well for the adoption of Rust in std land is to replace existing
components of a C codebase with Rust components (rather than the more radical rewrite everything in
Rust from scratch).

I think we are lacking guides for this important use case in embedded Rust land and we should fix
that. There are different aspects to integrating Rust into a existing C codebase:

• Integrate Rust / Cargo into a C project build system.

The Rust team has been working on making this easier since last year but I don't know what's the
current status.

What build systems can we expect to encounter in practice? Makefiles, cmake? Do we have examples of
integrating Cargo with those?

• Binding C code (FFI)

Some examples will probably come out of the work of binding RTOSes in #45. We should write a guide
(e.g. "how to use bindgen to bind C code that will be used in no_std context") once we have gained
experience.

• Calling Rust from C applications.

Example use case: write your parser in Rust and call it from C.

Do we have any examples of this? Anyone tried rusty-cheddar in no_std context?

Copied from original issue: rust-embedded/wg#48

Don't understand why this heading mention git

https://github.com/rust-embedded/book/blob/01327046e391d59de5de0079df30d1b57533e9da/src/intro/tooling.md#cargo-generate-or-git

only reference i see that it can be used as a download tools. But since there are more download tools they could all be put in the heading as well.

please clarify

What should the canonical link format be?

HTML or Markdown?

[foo]: ./relative/markdown.md
[foo]: ./relative/html.html

Relative or absolute?

[foo]: ./relative/markdown.md
[foo]: /absolute/markdown.md

From @japaric on March 22, 2018 12:53

As of the latest LLVM upgrade (4.0 -> 6.0 on 2018-02-11) LLVM seems to now perform loop unrolling more agressively; this increased the binary size of a minimal program that only zeroes .bss and initializes .data from 130 bytes .text (nightly-2018-02-10) to 1114 bytes (nightly-2018-03-20) when using opt-level=3 + LTO -- FWIW, I highly doubt the loop unrolling actually improves performance at all. Original report: rust-lang/rust#49260

This put us in a bad spot because by default we'll end with large optimized (--release) binaries -- I can already foresee future comparisons between C and Rust pointing out that the smallest embedded C program is only a hundred bytes in size whereas the smallest embedded Rust program is 1 KB.

So we should make sure we clearly document why Rust programs are so large by default and how to make Rust programs small. Using opt-level=s + LTO on the minimal program mentioned above brings the size back to 130 bytes .text.

cc @jamesmunns ^ that should be included in the book

There are other possibilites to explore here: like having something like C's / clang's #pragma nounroll to prevent LLVM from optimizing loops marked with that attribute, but I doubt we'll get any of that into the 2018 edition release -- it's too late, I think.

Copied from original issue: rust-embedded/wg#69

Hello, i tried to follow the guide in the rust book as well as possible, but i'm unable to load binaries on the microcontroller.

I already upgraded to the latest firmware with the tool from the st website.

This is what i'm doing in gdb: (i also ran monitor reset halt prior to this in gdb to make a "undefined debug reason 7 - target needs reset" error go away in openocd.)

~/Documents/programmeren/rust/micro/app : arm-none-eabi-gdb -q target/thumbv7em-none-eabihf/debug/examples/hello
Reading symbols from /home/frederik/Documents/programmeren/rust/micro/app/target/thumbv7em-none-eabihf/debug/examples/hello...done.
(gdb) target remote :3333
Remote debugging using :3333
0x08003cc8 in ?? ()
(gdb) load
Loading section .vector_table, size 0x400 lma 0x0
Loading section .text, size 0x2064 lma 0x400
Load failed

I'm sorry if this isn't the right place to post this.

Hello,

On this page, it asks us to run the following commands:

$ # GDB
$ brew cask install gcc-arm-embedded

$ brew install openocd

$ brew install qemu

Unfortunately, I get the error when executing the first command:

Error: Cask 'gcc-arm-embedded' is unavailable: No Cask with this name exists.

And when trying to tap Caskroom/tap:

htmacbook:local harrisonturton$ brew tap Caskroom/tap
==> Tapping caskroom/tap
Cloning into '/usr/local/Homebrew/Library/Taps/caskroom/homebrew-tap'...
remote: Repository not found.
fatal: repository 'https://github.com/Caskroom/homebrew-tap/' not found
Error: Failure while executing; `git clone https://github.com/Caskroom/homebrew-tap /usr/local/Homebrew/Library/Taps/caskroom/homebrew-tap --depth=1` exited with 128.

Any ideas? Not sure whats wrong.

At the bottom of the section 1.1 no_std there is a link for the FAQ, which is broken. It points to a page on rust-lang.org that does not longer exits and you get a 404 error.

svd2rust 0.14.0 is out so this is now unblocked

On IRC, quite a few people have asked about the ITM, have mentioned that they don't know how to use it, or mentioned that they tried to use it before but didn't get it to work. Let's document how to use the ITM in the book.

To cover:

• OpenOCD side: monitor itm
• Device side: iprintln!
• Host side: itmdump -F -f itm.txt
• Host side: itmdump -f /dev/ttyUSB0 (*nix only)
  • Cover how to configure the speed of ttyUSB*

From @jamesmunns on July 10, 2018 9:33

What sort of Static Guarantees are possible with Rust?

Copied from original issue: rust-embedded/wg#118

Things that could be covered:

• listing examples of PAC, HAL-impl crates, driver crates, i.e. names and links
• code using the above crates, for example a driver (sensor) crate

AIUI, https://docs.rust-embedded.org is now considered the main reference point for embedded docs.

If that's the case, please edit the GitHub repo description link from https://rust-embedded.github.io/book/ to https://docs.rust-embedded.org/book/ for consistency (even if the former one still works).

The table in section 1.4 suggests there's no heap with #![no_std]. I'd suggest that that box be marked "Optional" as if you bring in alloc you can have a heap. Maybe also add a new row for "collections (e.g. Vec and HashMap)" which is also marked "Optional" for "no_std".

I decided to finally plug in my STM32F3 board today and start on the embedded book.

First bug:
https://rust-embedded.github.io/bookshelf/discovery/index.html

From @jamesmunns on July 10, 2018 9:19

This issue tracks discussion around the Introduction Section of the book. This includes introducing concepts, obtaining and setting up hardware, and verifying a setup before starting the book.

Copied from original issue: rust-embedded/wg#116

The book mentions several times

When using real hardware [don't do this]

but makes no mention of how to configure the build so that we can leave the code in, but conditionally compile it in only when we wish to run in an emulator or with a debugger attached.
It would be very useful to have an example of how to accomplish this without modifying the code.

From @ryankurte on July 5, 2018 22:23

As mentioned here it'd be great to develop Running and Debugging into a useful tool-independent resource.

As far as I see it, we need:

• A common description of how embedded debugging works
  • JTAG
  • SWD
• An intro to embedded debugging
  • GDB for now
  • LLDB one day?
• An overview of available tools (hardware and software) and how to identify them
• An intro to the higher level tools (w/ arbitrary hardware)
  • bobbin-cli by @jcsoo
  • OpenOCD
• A page on the use of each tool for each of
  • JLink hardware + JLink software + GDB,
  • STLink hardware + texane/stlink + GDB,
  • BLackMagic Probe (BMP) hardware + GDB
  • CMSIS-DAP/DapLink

At this stage lldb isn't really viable for embedded debugging, so there's going to be a requirement for target GDB at least for now.

Any thoughts?

(@therealprof, @kjetilkjeka, @korken89)

Copied from original issue: rust-embedded/wg#112

The "Cross Compiling" paragraph of section 2.1 should mention that new users will need to install the thumbv7m-none-eabi target using rustup.

rustup target add thumbv7m-none-eabi

Related to #1.

We won't block the book on this, but it would be great to have some examples to point at and documentation around integrating Rust with common RTOSs. We can collect links and resources in this issue, and add them to the interoperability chapter.

Suggestions for RTOSs to consider:

• FreeRTOS
• ChibiOS
• mbed
• TockOS
• Zephyr
• MyNewt
• ?

From @japaric on July 17, 2018 14:34

This section should cover concurrency in embedded systems / microcontrollers. How the Send / Sync traits can be used with interrupts and static variables to achieve memory safe concurrency in those systems. We start with the simple case of interrupt handlers, static variables and critical sections and then show that a framework / DSL like Real Time for The Masses can built using those basic blocks.

If Tock userland apps (not the kernel) are working on stable then we can include a subsection about that as well as it demoes the multiprocess architecture. Same thing with freertos-rs which demoes a more traditional threading system (I think).

Copied from original issue: rust-embedded/wg#124

The link in the bottom links to https://github.com/rust-lang-nursery/embedded-wg/book, should probably link to https://github.com/rust-embedded/book.

Hi!
uucp is not an available group and it should be added manually (Fedora 26 here). I propose to modify src/intro/install/linux.md.

Hello,

While going trough tutorial I’ve encountered the following problems:

• cargo generate is used, but installation step for it is missing;
• in order to run example on nucleo-f303k8 you need to change values in memory.x to correct ones or else your debug session will always end in PanicHandler.

The second one is quite hostile for beginners.

Originally reported by @bofh in rust-embedded/cortex-m-semihosting#29