writing your first embedded Rust program #20
Conversation
|
I tried and failed to follow this tutorial using the current beta. Do you know when you expect it to work on beta / stable, and/or when the quickstart example will be updated to match? |
|
I should add, this is excellent, by the way. I'm very much looking forward to people being able to work through it and do some embedded rust at their desk. |
src/blinky/blinky.md
Outdated
|
|
||
| ``` console | ||
| $ cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart |
There was a problem hiding this comment.
Where do users get cargo-generate from? Running cargo install cargo-generate almost certainly fails unless you have gcc, cmake and libssl-dev installed, which causes new users quite a bit of grief. Can we suggest an alternative command here, so you can get up and running more quickly?
There was a problem hiding this comment.
Where do users get cargo-generate from?
https://github.com/ashleygwilliams/cargo-generate#installation
Before we were using cargo-clone which has about the same dependencies (i.e. openssl). I asked the Cargo team and having cargo-generate as a built-in command will require an RFC being written and approved which is very unlikely to happen in ~5 weeks (which is deadline for getting stuff into the edition release).
If we really want to have a template solution that doesn't have this problem we could create our very ad hoc thing (e.g. cortex-m-quickstart new) that doesn't use the network but instead has hardcoded the contents of the Cargo project template as strings in the binary ...
src/intro/install/linux.md
Outdated
|
|
||
| $ yaourt -S openocd | ||
| ``` | ||
|
|
||
| ## udev rules | ||
|
|
||
| These rules let you use USB devices like the F3 and the Serial module without root privilege, i.e. | ||
| `sudo`. | ||
| These rules let you use OpenOCD with the Discovery board without root privilege. | ||
|
|
||
| Create these two files in `/etc/udev/rules.d` with the contents shown below. |
There was a problem hiding this comment.
Docs reference two files but there is just one udev rule now as the FTDI rule from the discovery book has been dropped.
There was a problem hiding this comment.
It's been awhile since I've done the bare metal stuff (been mostly working on the embedded Linux side of things) but I picked up a discovery board and was able to follow these instructions without too many problems on Ubuntu 18.04.
Once the required form of the cortex-m-quickstart lands and it works as expected to use cargo-generate I see no big reason to hold this up for any extended period of time.
Doing this work tonight, I ended up using nightly as the beta was still on 1.29 and didn't appear to have all the required features as of yet.
|
I have expanded / updated the first section (introduction and installation) and split the second section, which I have from "Blinking your first LED" to "Getting started". This should be ready to go pending the cortex-m-quickstart update. Could you give a read to the new text? (last 4 commits). |
src/intro/install/linux.md
Outdated
| @@ -79,7 +79,7 @@ $ yaourt -S openocd | |||
|
|
|||
| These rules let you use OpenOCD with the Discovery board without root privilege. | |||
There was a problem hiding this comment.
This line still references "rules" in the plural.
|
@japaric Left one comment following up on the udev change but other than that the new changes LGTM from my read through. |
|
@thejpster are you happy with the latest changes? I believe we can't send this to bors until you resolve / change your pending "requested changes" review. The cortex-m-quickstart PR landed so this can land anytime. The beta is not out yet but it should be out sometime this week. In any case, the text tells the reader to use nightly if the beta is not out yet so the beta is not a blocker. |
|
As discussed on IRC, I'm still fundamentally against cargo-generate because it takes too long to compile/install and has annoying dependencies that you don't find out until half-way through. I'd be happy to add it back one once rustup can install the binary. |
|
@thejpster the latest commit explains how to instantiate the template using git, curl or your web browser. It also turns |
also turn `cargo-generate`, and `git`, into optional dependencies where the recommendation is to install neither
japaric
dismissed stale reviews from thejpster, therealprof, and posborne
via
10aba53
|
Pushed a commit to fix a link and that invalidated the approvals. Since this had already 3 approvals and CI I'm going to skip bors and directly merge it. |
27: new section: panicking r=therealprof a=japaric this probably should go in the second chapter but I'm putting it in the unsorted section until #20 lands Is there anything else that should be mentioned in this section? r? @rust-embedded/resources Co-authored-by: Jorge Aparicio <jorge@japaric.io>
writing your first embedded Rust program
27: new section: panicking r=therealprof a=japaric this probably should go in the second chapter but I'm putting it in the unsorted section until rust-embedded#20 lands Is there anything else that should be mentioned in this section? r? @rust-embedded/resources Co-authored-by: Jorge Aparicio <jorge@japaric.io>
This project was originally based on https://github.com/rust-embedded/cortex-m-quickstart however most of those parts are no longer relevant. The squash is in no way intended to take credit for their work, only to simplify the history. initial commit enable LTO fix `cargo new` invocation adapt to changes in cortex-m-srp build compiler-builtins as part of the Xargo sysroot update dependencies add nrf51 to the list of supported families add an example of overriding an exception closes #2 link using ld use an older Cargo to instantiate the template no need to enable the cortex-m-rt/linker-script feature as it's enabled by default more docs, sort examples note where code is device dependent all dependencies are dev-dependencies add a comment to the SRP example turn into a Cargo crate v0.1.1 Include debug information in release builds. Without debug information, `tbreak cortex_m_rt::reset_handler` does not work: rustc does not include the Rust support script directive, gdb does not load it, and breakpoints can only be set on functions using their full mangled name. v0.1.2 Fix documentation mistype in examples/crash.rs add troubleshooting section v0.1.3 add dependencies section to documentation add 'used stable toolchain' sub-section to the troubleshooting section v0.1.4 warn against using CARGO_INCREMENTAL v0.1.5 set default runner to arm-none-eabi-gdb with this `xargo run` will build the program *and* immediately start a GDB session. v0.1.6 document how to use the heap and a dynamic allocator v0.1.7 gdbinit: don't reset the microcontroller simply `step` after the `load` command. This should just work now that we are using cortex-m-rt v0.2.2 .gdbinit: add a commented out option to make the SWO pin functional when ... it's not connected to a programmer / debugger SWO pin bump cortex-m-rt version to v0.2.3; document the _stext symbol v0.1.8 Remove 'monitor tpiu itm port 0 on' from .gdbinit This happens automatically when openocd sets up the tpiu; see openocd manual 16.5.4. Revert "Remove 'monitor tpiu itm port 0 on' from .gdbinit" This reverts commit f88a44f. It's required on OpenOCD 0.10.0 v0.2.0 fix CHANGELOG Build compiler-builtins from rust source instead of github repository. expand the device example enable the "mem" feature of the compiler-builtins crate turns out it *is* required if your application ends up requiring a `memcmp` operation. document another common error overwriting the `.cargo/config` file instead of appending text to it v0.2.1 gdbinit: print demangled symbols by default this change turns this: ``` console (gdb) x/4 0x200003f0 0x200003f0 <_ZN3app2XS17h4b49405669958fd2E+1008>: 0x20000400 0x080004f5 0x00000000 0x00000001 ``` into this: ``` console (gdb) x/4 0x200003f0 0x200003f0 <app::XS+1008>: 0x20000400 0x080004f5 0x00000000 0x00000001 ``` bump the cortex-m-rt dependency disable incremental compilation and parallel codegen in dev mode document workaround for "Ignoring packet error" update the CHANGELOG v0.2.3 v0.2.4 Update examples to newer svd2rust api. Similarly, the cortex-m crate API was also updated. Add comments to Cargo.toml/Xargo.toml. This should make it easier to comment/uncomment stuff for the various examples. use stable release of alloc-cortex-m remove unused #[allow] examples/panic: add column information fix the allocator example v0.2.5 remove all mentions of Xargo as you can use plain Cargo to do ARM Cortex-M development v0.2.6 bump the cortex-m-rt to v0.4.0 ci: don't install cargo-edit remove panic-itm dependency don't call ci/after_success.sh use less unstable dependencies make the hello example work drop linker-flavor, port more examples update examples and docs TODO: drop opt-level=s use published versions, doc up, update CHANGELOG fix tests v0.3.0 document the no #![no_main] issue v0.3.1 Update lib.rs fixed doc: clone command should be cargo, not git Update panic-semihosting dependency to 0.3.0 This is due to #[lang = "panic_fmt"] -> #[panic_implementation] breakage v0.3.2 stop recommending LLD until https://bugs.llvm.org/show_bug.cgi?id=38435 is fixed fix the allocator example add CODEOWNERS, CoC; tweak bors and Travis README: mention the CoC and who maintains this repo Add comment to build script about rerun-if-changed, and remove redundant line for build.rs Update comment on rerun-if-changed to better reflect what it does v0.3.3 tweak bors.toml use LLD as the default linker closes #39 update symptom for the 'overwrite .cargo/config' problem bump dependencies to not depend on arm-none-eabi-gcc publish docs on GH pages update the minimal example fix some warnings use size instead of arm-none-eabi-size v0.3.4 add CHANGELOG for v0.3.4 deduplicate the contents .cargo/config using `cfg`s. Also add all the possible compilation targets to .cargo/config. be explicit about the GDB script to use with this change the user doesn't need to set an [auto-load-safe-path] [auto-load-safe-path]: https://sourceware.org/gdb/onlinedocs/gdb/Auto_002dloading-safe-path.html workaround rust-lang/cargo#5946 add a comment indicating which core each target maps to bump dependencies move to cargo-generate; start with QEMU move out most of text see rust-embedded/book#20 backport fixes from the book plus other small updates openocd.cfg: add support for older revisions of the discovery change the link to the book book.rust-embedded.org is pointing to an old version quieter GDB minify note that 1.30-beta is not out yet bump dependencies try to break at `main` the symbol is now stable. However, in optimized build it may be inlined into Reset add commented out ITM configuration this got lost in a previous commit Update rust version requirements in README.md As Cargo.toml now includes edition = "2018", it won't build with rust 1.30-stable. 1.31-stable will be the first stable version to have the edition feature enabled. (See https://internals.rust-lang.org/t/rust-2018-release-schedule-and-extended-beta/8076 for details.) At the same time, remove the remark about 1.30-beta not being out yet, as it's out by now. Add example moving .bss data into custom memory We're using a STM32F429 and wanted to move stuff around in memory, notably put stack+data into CPU coupled memory, and put framebuffers for the integrated LCD controller into the normal SRAM. Getting this right while not completely overriding the default `link.x` was quite tricky (especially finding the `INSERT AFTER` life-saver...) so I thought an example would not hurt here. It should probably also be mentioned in other places (book/...)? fix example Default to extended-remote instead of remote mode Extended remote allows a lot more features like attaching and detaching and much more fine-grained execution options. If a gdbserver implementation supports it (and OpenOCD sure does) it should be preferred over `remote`. Add additional meta data to improve crate experience * Add readme setting, so README.md is shown on https://crates.io/ use hprint macros fix the allocator example importing alloc is a bit weird use NVIC::pend instead of the deprecated NVIC.set_pending bump dependencies Workaround for loop {} until it is fixed Fixes code of conduct link. Closes #60 Add example of writing tests that run on host machine Make sure we can actually test prod code Add more documentation for testing on host Adjust the default breakpoint name to match cortex-m-rt pull #144 update interrupt usage Added backtrace limit to mitigate infinite backtraces Bump dependency versions added missing import NVIC wasn't imported from the stm32f30x crate add openocd.gdb hint how to print panic immediatly Update instructions for device example, closes #73 Update of cortex-m-rt for coming stable breakage Add VS Code support Adds basic configuration for VS Code for QEMU and STM32F3DISCOVERY. Track launch.json, tasks.json, md & svd files Ignoring the .vscode/ directory is good default behavior, but it's probably best to track the files that define build tasks, debug configs, documentation, and any system view description files. The gitignore.io sample takes the same approach. https://www.gitignore.io/api/visualstudiocode > We in the VS Code team share debug and task specific settings as well because we want our team to have the same set of debug targets and task targets for VS Code. https://stackoverflow.com/a/32979933/3198973 Even people who vehemently argue that .vscode shouldn't be track, agree that complex debug configs should be tracked and shared. > The only .vscode that makes sense to include are complex launch configs for debugging. https://stackoverflow.com/a/47668283/3198973 Add recommended extensions file Add vscode build tasks for examples and release Corrected default VSCode build task. Corrected default VSCode clean task. Update vscode docs to reflect fixes from PR #83 9977613 6c26219 rust-embedded/cortex-m-quickstart#83 Remove unnecessary build.rs Replace unidiomatic 'extern crate' to 'use x as _' Re-add build script with note this time Update build.rs Co-authored-by: Jonas Schievink <jonasschievink@gmail.com> Add --nmagic linker arg, for unaligned flash origin support. Without this, the linker places some extra program header entries that can confuse flashing tools. Many thanks to @jonas-schievink for pointing me to this flag in Matrix. Also add examples to target Armv8-M Signed-off-by: Hugues de Valon <hugues.devalon@arm.com> Fix alloc example Fixes #99: Disambiguates VSCode Tasks Using the equivalent command line as the task name caused some confusion. Users were under the impression that they could use any valid cargo command as a preLaunchTask in the launch configurations. move .cargo/config to .cargo/config.toml openocd.cfg: use the unified stlink.cfg configuration In newer versions of openocd, all the stlink-v* configuration files are deprecated, and just source stlink.cfg. docs: updates documentation to include correct path and full list of ISAs
cc #4
As I proposed in
#4 (comment) this
section starts with the default configuration that targets QEMU to get the
reader familiar with the tools. Then it moves to the reference hardware, the
STM32F3DISCOVERY, to cover device specific configuration.
This PR depends on rust-embedded/cortex-m-quickstart#45
r? @rust-embedded/resources
From here we could cover some of the quickstart examples like debugging a hard
fault and picking a panicking behavior and then do the blinky program.