From 53b0081472402bfbad6788863e28f31714d99cff Mon Sep 17 00:00:00 2001 From: Wink Saville Date: Sun, 28 Feb 2021 15:09:34 -0800 Subject: [PATCH] Update-03-setting-up-a-dev-env Update `*.md` files so that copy-to-clipboard button in code blocks works so that commands can be copied and pasted into terminal windows. Some reorganization of the text for clarity. --- src/03-setup/README.md | 53 ++++++++++++++++++++++------ src/03-setup/linux.md | 66 +++++++++++++++++++++-------------- src/03-setup/macos.md | 16 +++++---- src/03-setup/verify.md | 76 +++++++++++++++++++++++++---------------- src/03-setup/windows.md | 14 ++++++-- 5 files changed, 151 insertions(+), 74 deletions(-) diff --git a/src/03-setup/README.md b/src/03-setup/README.md index 7b1b2202f..01cdf1289 100644 --- a/src/03-setup/README.md +++ b/src/03-setup/README.md @@ -38,7 +38,7 @@ should work but we have listed the version we have tested. - Rust 1.31 or a newer toolchain. -- [`itmdump`] v0.3.1 (`cargo install itm`) +- [`itmdump`] >=0.3.1 (`cargo install itm`). Tested versions: 0.3.1. - OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0 @@ -84,37 +84,70 @@ rustc 1.31.0 (abe02cefd 2018-12-04) ### `itmdump` + ``` console -$ cargo install itm --vers 0.3.1 +cargo install itm +``` +Verify the version is >=0.3.1 +``` $ itmdump -V itmdump 0.3.1 ``` ### `cargo-binutils` +Install `llvm-tools-preview` + ``` console -$ rustup component add llvm-tools-preview +rustup component add llvm-tools-preview +``` + +Install `cargo-binutils` +``` +cargo install cargo-binutils +``` + +#### Verify tools are installed -$ cargo install cargo-binutils +Run the following commands at your terminal +``` console +cargo new test-size +``` +``` +cd test-size +``` +``` +cargo run +``` +``` +cargo size -- -version +``` +The results should be something like: +``` +~ $ cargo new test-size Created binary (application) `test-size` package +~ $ cd test-size +~/test-size (main) $ cargo run - Finished dev [unoptimized + debuginfo] target(s) in 0.01s - Running `target\debug\test-size.exe` + Compiling test-size v0.1.0 (~/test-size) + Finished dev [unoptimized + debuginfo] target(s) in 0.26s + Running `target/debug/test-size` Hello, world! +~/test-size (main) $ cargo size -- -version - Finished dev [unoptimized + debuginfo] target(s) in 0.50s + Finished dev [unoptimized + debuginfo] target(s) in 0.00s LLVM (http://llvm.org/): - LLVM version 11.0.0-rust-1.49.0-stable + LLVM version 11.0.0-rust-1.50.0-stable Optimized build. - Default target: x86_64-pc-windows-msvc - Host CPU: skylake + Default target: x86_64-unknown-linux-gnu + Host CPU: znver2 ``` ### OS specific instructions diff --git a/src/03-setup/linux.md b/src/03-setup/linux.md index 0c32c66d2..7985ccb7a 100644 --- a/src/03-setup/linux.md +++ b/src/03-setup/linux.md @@ -18,7 +18,7 @@ Here are the installation commands for a few Linux distributions. ``` console -$ sudo apt-get install \ +sudo apt-get install \ gdb-multiarch \ minicom \ openocd @@ -34,7 +34,7 @@ $ sudo apt-get install \ ``` console -$ sudo apt-get install \ +sudo apt-get install \ gdb-arm-none-eabi \ minicom \ openocd @@ -46,7 +46,7 @@ $ sudo apt-get install \ > Cortex-M programs ``` console -$ sudo dnf install \ +sudo dnf install \ arm-none-eabi-gdb \ minicom \ openocd @@ -58,7 +58,7 @@ $ sudo dnf install \ > Cortex-M programs ``` console -$ sudo pacman -S \ +sudo pacman -S \ arm-none-eabi-gdb \ minicom \ openocd @@ -75,15 +75,17 @@ download the "Linux 64-bit" file and put its `bin` directory on your path. Here's one way to do it: ``` console -$ mkdir -p ~/local && cd ~/local -$ tar xjf /path/to/downloaded/file/gcc-arm-none-eabi-7-2017-q4-major-linux.tar.bz2.tbz +mkdir -p ~/local && cd ~/local +``` +``` console +tar xjf /path/to/downloaded/file/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2 ``` Then, use your editor of choice to append to your `PATH` in the appropriate shell init file (e.g. `~/.zshrc` or `~/.bashrc`): ``` -PATH=$PATH:$HOME/local/gcc-arm-none-eabi-7-2017-q4-major/bin +PATH=$PATH:$HOME/local/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux/bin ``` ## Optional packages @@ -91,7 +93,7 @@ PATH=$PATH:$HOME/local/gcc-arm-none-eabi-7-2017-q4-major/bin ### Ubuntu / Debian ``` console -$ sudo apt-get install \ +sudo apt-get install \ bluez \ rfkill ``` @@ -99,7 +101,7 @@ $ sudo apt-get install \ ### Fedora ``` console -$ sudo dnf install \ +sudo dnf install \ bluez \ rfkill ``` @@ -107,7 +109,7 @@ $ sudo dnf install \ ### Arch Linux ``` console -$ sudo pacman -S \ +sudo pacman -S \ bluez \ bluez-utils \ rfkill @@ -118,35 +120,49 @@ $ sudo pacman -S \ These rules let you use USB devices like the F3 and the Serial module without root privilege, i.e. `sudo`. -Create these two files in `/etc/udev/rules.d` with the contents shown below. +Create `99-openocd.rules` in `/etc/udev/rules.d` using the `idVendor` and `idProduct` +from the `lsusb` output. +For example, connect the STM32F3DISCOVERY to your computer using a USB cable. +Be sure to connect the cable to the "USB ST-LINK" port, the USB port in the +center of the edge of the board. + +Execute `lsusb`: ``` console -$ cat /etc/udev/rules.d/99-ftdi.rules +lsusb | grep ST-LINK +``` +It should result in something like: ``` +$ lsusb | grep ST-LINK +Bus 003 Device 003: ID 0483:374b STMicroelectronics ST-LINK/V2.1 +``` +So the `idProduct` is `0483` and `idVendor` is `374b`. +### Create `/etc/udev/rules.d/99-openocd.rules`: +``` console +sudo vi /etc/udev/rules.d/99-openocd.rules +``` +With the contents: ``` text -# FT232 - USB <-> Serial Converter -ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE:="0666" +# STM32F3DISCOVERY - ST-LINK/V2.1 +ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666" ``` +#### For older devices with OPTIONAL USB <-> FT232 based Serial Module -If you have a different USB <-> Serial converter, get its vendor and product ids from `lsusb` output. - +Create `/etc/udev/rules.d/99-ftdi.rules`: ``` console -$ cat /etc/udev/rules.d/99-openocd.rules +sudo vi /etc/udev/rules.d/99-openocd.rules ``` - +With the contents: ``` text -# STM32F3DISCOVERY rev A/B - ST-LINK/V2 -ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE:="0666" - -# STM32F3DISCOVERY rev C+ - ST-LINK/V2-1 -ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666" +# FT232 - USB <-> Serial Converter +ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE:="0666" ``` -Then reload the udev rules with: +### Reload the udev rules with: ``` console -$ sudo udevadm control --reload-rules +sudo udevadm control --reload-rules ``` If you had any board plugged to your computer, unplug them and then plug them in again. diff --git a/src/03-setup/macos.md b/src/03-setup/macos.md index 0d0c67f3a..62672902c 100644 --- a/src/03-setup/macos.md +++ b/src/03-setup/macos.md @@ -4,13 +4,17 @@ All the tools can be install using [Homebrew]: [Homebrew]: http://brew.sh/ +Install ArmMbed ``` console -$ # Arm GCC toolchain -$ brew tap ArmMbed/homebrew-formulae -$ brew install arm-none-eabi-gcc - -$ # Minicom and OpenOCD -$ brew install minicom openocd +brew tap ArmMbed/homebrew-formulae +``` +Install the ARM GCC toolchain +``` console +brew install arm-none-eabi-gcc +``` +Install minicom and OpenOCD +``` console +brew install minicom openocd ``` That's all! Go to the [next section]. diff --git a/src/03-setup/verify.md b/src/03-setup/verify.md index 59996e065..b69d48999 100644 --- a/src/03-setup/verify.md +++ b/src/03-setup/verify.md @@ -6,24 +6,27 @@ Let's verify that all the tools were installed correctly. ### Verify permissions -Connect the F3 to your computer using an USB cable. Be sure to connect the cable to the "USB ST-LINK" +Connect the STM32F3DISCOVERY to your computer using an USB cable. Be sure to connect the cable to the "USB ST-LINK" port, the USB port in the center of the edge of the board. -The F3 should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got +The STM32F3DISCOVERY should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got enumerated: +``` console +lsusb | grep -i stm +``` +This should result in: ``` console $ lsusb | grep -i stm Bus 003 Device 004: ID 0483:374b STMicroelectronics ST-LINK/V2.1 $ # ^^^ ^^^ ``` -In my case, the F3 got connected to the bus #3 and got enumerated as the device #4. This means the -file `/dev/bus/usb/003/004` *is* the F3. Let's check its permissions: - +In my case, the STM32F3DISCOVERY got connected to the bus #3 and got enumerated as the device #4. This means the +file `/dev/bus/usb/003/004` *is* the STM32F3DISCOVERY. Let's check its permissions: ``` console -$ ls -l /dev/bus/usb/003/004 -crw-rw-rw- 1 root root 189, 20 Sep 13 00:00 /dev/bus/usb/003/004 +$ ls -la /dev/bus/usb/003/004 +crw-rw-rw-+ 1 root root 189, 259 Feb 28 13:32 /dev/bus/usb/003/00 ``` The permissions should be `crw-rw-rw-`. If it's not ... then check your [udev @@ -32,12 +35,12 @@ rules] and try re-loading them with: [udev rules]: linux.md#udev-rules ``` console -$ sudo udevadm control --reload-rules +sudo udevadm control --reload-rules ``` -Now let's repeat the procedure for the Serial module. +#### For older devices with OPTIONAL USB <-> FT232 based Serial Module -Unplug the F3 and plug the Serial module. Now, figure out what's its associated file: +Unplug the STM32F3DISCOVERY and plug the Serial module. Now, figure out what's its associated file: ``` console $ lsusb | grep -i ft232 @@ -53,36 +56,51 @@ crw-rw-rw- 1 root root 189, 21 Sep 13 00:00 /dev/bus/usb/003/005 As before, the permissions should be `crw-rw-rw-`. -## All +## Verify OpenOCD connection -### First OpenOCD connection - -First, connect the F3 to your computer using an USB cable. Connect the cable to the USB port in the +Connect the STM32F3DISCOVERY using the USB cable to the USB port in the center of edge of the board, the one that's labeled "USB ST-LINK". Two *red* LEDs should turn on right after connecting the USB cable to the board. -Next, run this command: +> **IMPORTANT** There is more than one hardware revision of the STM32F3DISCOVERY board. For older +> revisions, you'll need to change the "interface" argument to `-f interface/stlink-v2.cfg` (note: +> no `-1` at the end). Alternatively, older revisions can use `-f board/stm32f3discovery.cfg` +> instead of `-f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg`. + +### *Nix + +> **FYI:** The `interface` directory is typically located in `/usr/share/openocd/scripts/`, +> which is the default location OpenOCD expects these files. If you've installed them +> somewhere else use the `-s /path/to/scripts/` option to specify your install directory. ``` console -$ # *nix -$ openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg +openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg +``` -$ # Windows -$ # NOTE cygwin users have reported problems with the -s flag. If you run into -$ # that you can call openocd from the `C:\OpenOCD\share\scripts` directory -$ openocd -s C:\OpenOCD\share\scripts -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg +### Windows + +Below the references to `C:\OpenOCD` is the directory where OpenOCD is installed. + +``` console +openocd -s C:\OpenOCD\share\scripts -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg ``` -> **NOTE** Windows users: `C:\OpenOCD` is the directory where you installed OpenOCD to. +> **NOTE** cygwin users have reported problems with the -s flag. If you run into +> that problem you can add `C:\OpenOCD\share\scripts\` directory to the parameters. -> **IMPORTANT** There is more than one hardware revision of the STM32F3DISCOVERY board. For older -> revisions, you'll need to change the "interface" argument to `-f interface/stlink-v2.cfg` (note: -> no `-1` at the end). Alternatively, older revisions can use `-f board/stm32f3discovery.cfg` -> instead of `-f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg`. +cygwin users: +``` console +openocd -f C:\OpenOCD\share\scripts\interface\stlink-v2-1.cfg -f C:\OpenOCD\share\scripts\target\stm32f3x.cfg +``` -You should see output like this: +### All +OpenOCD is a service which forwards debug information from the ITM channel +to a file, `itm.txt`, as such it runs forever and does **not** return to the +terminal prompt. + +The initial output of OpenOCD is something like: ``` console Open On-Chip Debugger 0.10.0 Licensed under GNU GPL v2 @@ -106,9 +124,7 @@ Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints [general troubleshooting]: ../appendix/1-general-troubleshooting/index.html -`openocd` will block the terminal. That's fine. - Also, one of the red LEDs, the one closest to the USB port, should start oscillating between red light and green light. -That's it! It works. You can now close/kill `openocd`. +That's it! It works. You can now use `Ctrl-c` to stop OpenOCD or close/kill the terminal. diff --git a/src/03-setup/windows.md b/src/03-setup/windows.md index 4760b714c..df6ad9b19 100644 --- a/src/03-setup/windows.md +++ b/src/03-setup/windows.md @@ -6,9 +6,14 @@ ARM provides `.exe` installers for Windows. Grab one from [here][gcc], and follo Just before the installation process finishes tick/select the "Add path to environment variable" option. Then verify that the tools are in your `%PATH%`: +Verify gcc is installed: ``` console -$ arm-none-eabi-gcc -v +arm-none-eabi-gcc -v +``` +The results should be something like: +``` (..) +$ arm-none-eabi-gcc -v gcc version 5.4.1 20160919 (release) (..) ``` @@ -24,8 +29,11 @@ before). [openocd]: https://github.com/xpack-dev-tools/openocd-xpack/releases -Verify that OpenOCD is in yout `%PATH%` with: - +Verify OpenOCD is installed and in your `%PATH%` with: +``` console +openocd -v +``` +The results should be something like: ``` console $ openocd -v Open On-Chip Debugger 0.10.0