document/embbed-rust
2
0
Fork 0
mirror of https://github.com/nkbai/book.git synced 2026-09-04 05:32:47 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge #74

Browse Source 
74: edits to the introduction chapter r=jamesmunns a=japaric

see individual commit messages for details

Co-authored-by: Jorge Aparicio <jorge@japaric.io>
This commit is contained in:
bors[bot]
2018-11-10 15:06:06 +00:00
parent 9dc27f523a 9da22bdd21
commit ec90335f16
7 changed files with 32 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/SUMMARY.md
View File

@@ -10,14 +10,14 @@ more information and coordination
-->
- [Introduction](./intro/introduction.md)
- [`no_std`](./intro/no-std.md)
- [Tooling](./intro/tooling.md)
- [Installation](./intro/install.md)
- [Linux](./intro/install/linux.md)
- [MacOS](./intro/install/macos.md)
- [Windows](./intro/install/windows.md)
- [Verify Installation](./intro/install/verify.md)
- [Tooling](./intro/tooling.md)
- [Hardware](./intro/hardware.md)
- [`no_std`](./intro/no-std.md)
- [Getting started](./start.md)
- [QEMU](./start/qemu.md)
- [Hardware](./start/hardware.md)

62
src/intro/install.md
View File

@@ -1,57 +1,6 @@
> **⚠️: This section still references `beta` Rust**
>
> Contents should be updated to work on `stable` Rust when possible
# Installing the tools
> **⚠️: This section was last checked on 2018-09-13**
# Setting up a Development Environment
Dealing with microcontrollers involves using several different tools as we'll be
dealing with an architecture different than your laptop's and we'll have to run
and debug programs on a *remote* device.
<!-- NOTE(japaric) I'm not sure we are going to need the user to download *all* -->
<!-- these docs so I'm going to comment out this section. If it turns out we do -->
<!-- need some doc I think it would be best to link it from the section where -->
<!-- it's needed -->
<!-- ## Documentation -->
<!-- Tooling is not everything though. Without documentation is pretty much impossible to work with microcontrollers. -->
<!-- We'll be referring to all these documents throughout this book: -->
<!-- *HEADS UP* All these links point to PDF files and some of them are hundreds of pages long and -->
<!-- several MBs in size. -->
<!-- - [STM32F3DISCOVERY User Manual][um] -->
<!-- - [STM32F303VC Datasheet][ds] -->
<!-- - [STM32F303VC Reference Manual][rm] -->
<!-- - [LSM303DLHC] -->
<!-- - [L3GD20] -->
<!-- [L3GD20]: http://www.st.com/resource/en/datasheet/l3gd20.pdf -->
<!-- [LSM303DLHC]: http://www.st.com/resource/en/datasheet/lsm303dlhc.pdf -->
<!-- [ds]: http://www.st.com/resource/en/datasheet/stm32f303vc.pdf -->
<!-- [rm]: http://www.st.com/resource/en/reference_manual/dm00043574.pdf -->
<!-- [um]: http://www.st.com/resource/en/user_manual/dm00063382.pdf -->
## Tools
We'll use all the tools listed below. Any recent version should work when a minimum version is not specified, but we have listed the versions we have tested.
- Rust 1.30, 1.30-beta, nightly-2018-09-13, or a newer toolchain PLUS ARM
Cortex-M compilation support.
- [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils) ~0.1.4
- [`qemu-system-arm`](https://www.qemu.org/). Tested versions: 3.0.0
- OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0
- GDB with ARM support. Version 7.12 or newer highly recommended. Tested
versions: 7.10, 7.11, 7.12 and 8.1
- [OPTIONAL] `git` OR
[`cargo-generate`](https://github.com/ashleygwilliams/cargo-generate). If you
have neither installed then don't worry about installing either.
Next, follow OS-agnostic installation instructions for a few of the tools:
This page contains OS-agnostic installation instructions for a few of the tools:
### Rust Toolchain
@@ -63,13 +12,12 @@ Then switch to the beta channel.
$ rustup default beta
```
**NOTE** Make sure you have a beta equal to or newer than `1.30-beta`. `rustc
-V` should return a date newer than the one shown below. If `1.30-beta` is not
out yet then use the nightly channel for the time being.
**NOTE** Make sure you have a beta equal to or newer than `1.31-beta`. `rustc
-V` should return a date newer than the one shown below.
``` console
$ rustc -V
rustc 1.30.0-beta (????????? 2018-09-1?)
rustc 1.31.0-beta.4 (04da282bb 2018-11-01)
```
For bandwidth and disk usage concerns the default installation only supports

2
src/intro/install/linux.md
View File

@@ -1,5 +1,3 @@
> **⚠️: This section was last checked on 2018-09-13
# Linux
Here are the installation commands for a few Linux distributions.

2
src/intro/install/macos.md
View File

@@ -1,5 +1,3 @@
> **⚠️: This section has not been checked as of 2018-09-13**
# macOS
All the tools can be install using [Homebrew]:

2
src/intro/install/windows.md
View File

@@ -1,5 +1,3 @@
> **⚠️: This section has not been checked as of 2018-09-13**
# Windows
## `arm-none-eabi-gdb`

3
src/intro/introduction.md
View File

@@ -56,7 +56,6 @@ If you are unfamiliar with anything mentioned above or if you want more informat
| Topic | Resource | Description |
|--------------|----------|-------------|
| Rust | [Rust Book 2018 Edition](https://doc.rust-lang.org/book/2018-edition/index.html) | If you are not yet comfortable with Rust, we highly suggest reading the this book. |
| Rust | [Rust Book Second Edition](https://doc.rust-lang.org/book/second-edition) | - |
| Rust, Embedded | [Embedded Rust Bookshelf](https://docs.rust-embedded.org) | Here you can find several other resources provided by Rust's Embedded Working Group. |
| Rust, Embedded | [Embedonomicon](https://docs.rust-embedded.org/embedonomicon/) | The nitty gritty details when doing embedded programming in Rust. |
| Rust, Embedded | [embedded FAQ](https://docs.rust-embedded.org/faq.html) | Frequently asked questions about Rust in an embedded context. |
@@ -86,7 +85,7 @@ for the purpose of following the examples in this book.
> **HEADS UP** Until the official release of this book, which is planned to
> coincide with the 2018 edition release of the Rust Programming Language,
> expect the sections of this book to change quite a bit. We recommend
> bookmarking the root of this book instead of any specific version.
> bookmarking the root of this book instead of any specific section.
## Contributing to This Book

29
src/intro/tooling.md
View File

@@ -1,6 +1,26 @@
# Tooling
This section contains details about the tools we'll be using.
Dealing with microcontrollers involves using several different tools as we'll be
dealing with an architecture different than your laptop's and we'll have to run
and debug programs on a *remote* device.
We'll use all the tools listed below. Any recent version should work when a
minimum version is not specified, but we have listed the versions we have
tested.
- Rust 1.31, 1.31-beta, or a newer toolchain PLUS ARM Cortex-M compilation
support.
- [`cargo-binutils`](https://github.com/rust-embedded/cargo-binutils) ~0.1.4
- [`qemu-system-arm`](https://www.qemu.org/). Tested versions: 3.0.0
- OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0
- GDB with ARM support. Version 7.12 or newer highly recommended. Tested
versions: 7.10, 7.11, 7.12 and 8.1
- [OPTIONAL] `git` OR
[`cargo-generate`](https://github.com/ashleygwilliams/cargo-generate). If you
have neither installed then don't worry about installing either.
The text below explains why we are using these tools. Installation instructions
can be found in the next page.
## `cargo-generate` OR `git`
@@ -36,9 +56,9 @@ can follow some parts of this book even if you don't have any hardware with you!
## GDB
Debugging is very important skill for embedded development as you may not always
have the luxury to log stuff to the host console. In some cases, you may not
have LEDs to blink on your hardware!
A debugger is a very important component of embedded development as you may not
always have the luxury to log stuff to the host console. In some cases, you may
not have LEDs to blink on your hardware!
In general, LLDB works as well as GDB when it comes to debugging but we haven't
found an LLDB counterpart to GDB's `load` command, which uploads the program to
@@ -63,4 +83,3 @@ development board:
* Continuing CPU execution after a debug event has been encountered
* etc.
* It also knows how to erase and write to the microcontroller's FLASH