diff --git a/src/ch2_00_installation.md b/src/ch2_00_installation.md index 918894b9f36a92fd211f98da669c99efa5f15200..382ab155656894f0a31e5657a8fb1d73b8067413 100644 --- a/src/ch2_00_installation.md +++ b/src/ch2_00_installation.md @@ -3,20 +3,30 @@ Pick the appropriate subchapter for your operating system. ## Editor + There is no requirement on which editor you should use, but if you are undecided VS code offers quite a few nice features, is free and highly customizable. -It is also modular with a lot of extensions, including for example, the Rust core group maintained extension that is called ```Rust (rls)``` where you get all kinds of language-specific help such as code completion, IntelliSense, refactoring, reformatting, errors, snippets. +It is also modular with a lot of extensions, including for example, +the Rust core group maintained extension that is called ```Rust (rls)``` +where you get all kinds of language-specific help such as code completion, +IntelliSense, refactoring, reformatting, errors, snippets. ### VS Code -* Windows: Go to [VS Code for Windows](https://code.visualstudio.com/docs/setup/windows) and follow the instructions +* Windows: Go to [VS Code for Windows](https://code.visualstudio.com/docs/setup/windows) +* and follow the instructions * Linux: Use package manager of choice, see: [VS Code for Linux](https://code.visualstudio.com/docs/setup/linux) #### VS Code plugins -When installed, go to the extensions tab and install ```Rust (rls)``` and ```Better TOML```. -[Rust Analyzer](https://github.com/rust-analyzer/rust-analyzer) is an alternative to ```Rust (rls)``` +When installed, go to the extensions tab and install + +* ```Rust (rls)``` +* ```Better TOML``` + +[Rust Analyzer](https://github.com/rust-analyzer/rust-analyzer) +is an alternative to ```Rust (rls)``` diff --git a/src/ch2_01_linux_installation.md b/src/ch2_01_linux_installation.md index 3287479044d540639106463c2a9b265d7a985aa4..08f0e5c556a5acc46fab2e8dfe7c3f73b768e218 100644 --- a/src/ch2_01_linux_installation.md +++ b/src/ch2_01_linux_installation.md @@ -9,20 +9,19 @@ in case of troubles see if a newer package is available in the `backports` repos Debian -``` +```shell sudo apt install gdb-arm-none-eabi binutils-arm-none-eabi ``` Ubuntu -``` +```shell sudo apt install gcc-multilib gdb-multiarch binutils-multiarch ``` - Arch -``` +```shell sudo pacman -S arm-none-eabi-gdb arm-none-eabi-binutils ``` @@ -30,13 +29,13 @@ sudo pacman -S arm-none-eabi-gdb arm-none-eabi-binutils Debian/Ubuntu -``` +```shell sudo apt install openocd ``` Arch -``` +```shell sudo pacman -S openocd ``` @@ -44,14 +43,15 @@ sudo pacman -S openocd Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions. -then add the required ARM target: +Then add the required ARM target: -``` +```shell rustup target add thumbv7em-none-eabihf ``` ## Cargo tools -``` + +```shell cargo install cargo-binutils rustup component add llvm-tools-preview ``` @@ -59,7 +59,7 @@ rustup component add llvm-tools-preview ### If running Rust beta/nightly Use instead -``` + +```shell rustup component add llvm-tools ``` - diff --git a/src/ch2_02_windows_installation.md b/src/ch2_02_windows_installation.md index 3a982369ec9e1a64d017d35cf4274f5f296e0ab4..a37ae95fe20ab7c6b587993041dc8eb5db6dc61b 100644 --- a/src/ch2_02_windows_installation.md +++ b/src/ch2_02_windows_installation.md @@ -1,10 +1,12 @@ # Windows Toolchain setup -### Native +## Native -#### GDB +### GDB - Native + +Go to [mingw.org](http://www.mingw.org/), download and install MinGW. +In the MinGW Installation Manager select ```All Packages``` then mark for installation: -Go to [mingw.org](http://www.mingw.org/), download and install MinGW. In the MinGW Installation Manager select ```All Packages``` then mark for installation: - mingw32-gcc-g++ - mingw32-gdb (bin) - mingw32-gdb (doc) @@ -12,72 +14,115 @@ Go to [mingw.org](http://www.mingw.org/), download and install MinGW. In the Min - mingw32-gdb (lic) - mingw32-gdb (man) -then in the Installation menu choose ```Apply Changes```, you should see at the bottom of the window that there is going to be several packages in ```new/upgraded packages will be installed``` if so then click ```Apply```. +then in the Installation menu choose `Apply Changes`, +you should see at the bottom of the window that there is going to be +several packages in `new/upgraded packages will be installed` +if so then click `Apply`. -If everything went as expected then you should have the ```gdb.exe``` file is your MinGW install folder under /bin. However to effectively use gdb you need to set the environment variable. -Go to the Control panel -> System and Security -> System -> Advanced system settings, click the ```Environment Variables...``` button. In this window in the System variables view click ```Edit...``` then ```New``` and type in the path to the gdb.exe file (should be something like ```C:\MinGW\bin```). Then click OK in all the windows. +If everything went as expected then you should have the `gdb.exe` file is +your MinGW install folder under `/bin`. +However to effectively use gdb you need to set the environment variable. -To check that everything went as expected open a new terminal with ```CTRL+r``` and type cmd then ```ENTER```. -If you now type ```gdb``` you should be prompted with a text saying something like "GNU gdb (GDB) 7.6.1", gdb is now installed! +Go to the Control panel -> System and Security -> System -> Advanced system settings, +click the `Environment Variables...` button. -#### OpenOCD +In this window in the System variables view click `Edit...` then `New` +and type in the path to the `gdb.exe` file +(should be something like ```C:\MinGW\bin```). +Then click OK in all the windows. + +To check that everything went as expected open a new terminal with +`CTRL+r` and type cmd then `ENTER`. + +If you now type `gdb` you should be prompted with a text saying something like +"GNU gdb (GDB) 7.6.1". -Go to [openocd](http://gnutoolchains.com/arm-eabi/openocd/) and download the latest OpenOCD package. -Extract the package somewhere where it is easy to find (i.e C:). +GDB is now installed! +#### OpenOCD + +Go to [openocd](http://gnutoolchains.com/arm-eabi/openocd/) and download the +latest OpenOCD package. Extract the package somewhere where it is easy to find. +(i.e C:). /// TODO /// -### Windows Subsystem for Linux (WSL) - Windows 10 ONLY +## Windows Subsystem for Linux (WSL) - Windows 10 ONLY -To install WSL check out: [https://docs.microsoft.com/en-us/windows/wsl/install-win10](https://docs.microsoft.com/en-us/windows/wsl/install-win10). We recommend the Ubuntu distro. +To install WSL check out: [https://docs.microsoft.com/en-us/windows/wsl/install-win10][2]. +We recommend the Ubuntu distro. -To open a distro terminal: Ctrl+r and write ```cmd``` and run. In the terminal type ```bash```, this will spawn a ubuntu terminal. +[2]: https://docs.microsoft.com/en-us/windows/wsl/install-win10 + +To open a distro terminal: Ctrl+r and write `cmd` and run. +In the terminal type `bash`, this will spawn a ubuntu terminal. Using the terminal, update the distro: -```sudo apt update``` +```shell +sudo apt update -```sudo apt install build-essential``` +sudo apt install build-essential -```sudo apt install gdb``` +sudo apt install gdb -```sudo apt upgrade``` +sudo apt upgrade +``` -The ordinary C: drive will be found under /mnt/c +The ordinary `C:` drive will be found under `/mnt/c` -#### Rust +### Rust -Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions, run the command inside WSL. +Go to [https://rustup.rs/](https://rustup.rs/) and follow the instructions, +run the installation command inside WSL. -then add the required ARM target: +To add the required ARM target: -``` +```shell rustup target add thumbv7em-none-eabihf ``` -##### Cargo tools -``` +#### Cargo tools + +```shell cargo install cargo-binutils rustup component add llvm-tools ``` -#### GDB +### GDB - WSL /// TODO /// -#### OpenOCD +### OpenOCD in WSL Is the same as for native Windows as OpenOCD doesn't (currently) work under WSL. -#### Quality of life +### Quality of life -##### Shortcuts +#### Shortcuts -To be able to quickly get up and running I usually create a shortcut on the desktop with all flags I need for a certain project and with the configurations that I need. For example, if I have a project that uses OpenOCD, the STLink programmer and the target MCU is an STM32f4xx, I create a shortcut with the target: +To be able to quickly get up and running I usually create a shortcut +on the desktop with all flags I need for a certain project +with the configurations that I need. + +For example, if I have a project that uses OpenOCD, +the STLink programmer and the target MCU is an STM32f4xx. + +I would create a shortcut with the target: + +```text +C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe .\openocd.exe -f ../share/openocd/scripts/interface/stlink.cfg -f ../share/openocd/scripts/target/stm32f4x.cfg +``` -```C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe .\openocd.exe -f ../share/openocd/scripts/interface/stlink.cfg -f ../share/openocd/scripts/target/stm32f4x.cfg``` +and make it start in the openocd/bin folder i.e `C:\OpenOCD\bin`. +If you want it to be really fancy then under layout you can change where the +window should spawn as well as how it should look like. -and make it start in the openocd/bin folder i.e ```C:\OpenOCD\bin```. And if you want to be really fancy then under layout you can change where the window should spawn as well as how it should look like. +You can even make it spawn a WSL terminal to your liking, for example, +if you have the target set as +`C:\Windows\System32\bash.exe -c "tmux new-session \; split-window -h \; attach"` +and to start in the folder where your rust projects are located. -You can even make it spawn a WSL terminal to your liking, for example, if you have the target set as ```C:\Windows\System32\bash.exe -c "tmux new-session \; split-window -h \; attach"``` and to start in the folder where your rust projects are located. Then you will have a bash terminal in your project folder under WSL that starts up with tmux creating two panes splitting the terminal in two. +Then you will have a bash terminal in your project folder under WSL that starts +up with [tmux](https://github.com/tmux/tmux/wiki) creating two panes splitting +the terminal in two. diff --git a/src/ch2_03_testing_toolchain.md b/src/ch2_03_testing_toolchain.md index ce3be532038309d20be640ba5a589f44ac121947..75c616e9e44b82a32f101a3e5a91fb29386d5a08 100644 --- a/src/ch2_03_testing_toolchain.md +++ b/src/ch2_03_testing_toolchain.md @@ -5,27 +5,31 @@ Connect your STM32F401 to the computer via a mini-USB cable. Start OpenOCD -``` + +```shell openocd -f interface/stlink.cfg -f target/stm32f4x.cfg ``` ### Troubleshoot OpenOCD -If OpenOCD reports no such device, double check with eg. `lsusb` on Linux if you have something like +If OpenOCD reports no such device, double check with eg. `lsusb` +on Linux if you have something like: -``` +```text 0483:3752 STMicroelectronics ST-LINK/V2.1 ``` -The firmware in the ST-Link can be too new for your currently installed version of OpenOCD. +The firmware in the ST-Link can be too new +for your currently installed version of OpenOCD. If this is the case, then you may have to install/compile the latest version of OpenOCD. -See [OpenOCD git](https://sourceforge.net/p/openocd/code/ci/master/tree/) for complete instructions. +See [OpenOCD git](https://sourceforge.net/p/openocd/code/ci/master/tree/) +for complete instructions. tl;dr: -``` +```shell git://git.code.sf.net/p/openocd/code ./bootstrap (when building from the git repository) ./configure @@ -33,11 +37,11 @@ make sudo make install ``` -### If success! +### If success The next step assumes you get the following output from OpenOCD: -``` +```shell ➜ openocd -f interface/stlink.cfg -f target/stm32f4x.cfg Open On-Chip Debugger 0.10.0+dev-00973-g80f1a92bd (2019-12-01-00:09) Licensed under GNU GPL v2 @@ -54,36 +58,37 @@ Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints Info : Listening on port 3333 for gdb connections ``` - ## Software -Fetch the following project [https://gitlab.henriktjader.com/pln/stm32-rtic5/tree/rtic_start](https://gitlab.henriktjader.com/pln/stm32-rtic5/tree/rtic_start) -and switch to the `rtic_start` branch. -``` +Fetch the following project [3] and switch to the `rtic_start` branch. + +```shell git clone https://gitlab.henriktjader.com/pln/stm32-rtic5.git git checkout rtic_start ``` +[3]: https://gitlab.henriktjader.com/pln/stm32-rtic5/tree/rtic_start + You can run the cargo test inside the firmware directory: -``` +```shell cd firmware cargo test cd .. ``` -It will print that tests succeeded (hopefully). +It will print that tests succeeded (hopefully). Inside the binary directory run `cargo run`: -``` +```shell cd binary cargo run ``` If everything went as expected you will see the following: -``` +```shell cargo run Finished dev [optimized + debuginfo] target(s) in 0.06s Running `arm-none-eabi-gdb -q -x openocd.gdb target/thumbv7em-none-eabihf/debug/app` @@ -109,4 +114,5 @@ Section .text, range 0x8000400 -- 0x80018e8: matched. Section .rodata, range 0x80018f0 -- 0x8001d8c: matched. (gdb) ``` + including some messages in the OpenOCD terminal.