Compare revisions

  # LLD (shipped with the Rust toolchain) is used as the default linker

  # LLD (shipped with the Rust toolchain) is used as the default linker

  "-C", "link-arg=-Tlink.x",

  "-C", "link-arg=-Tlink.x",

  # To get inline assembly at link time

  "-C", "linker-plugin-lto",

  # if you run into problems with LLD switch to the GNU linker by commenting out

  # if you run into problems with LLD switch to the GNU linker by commenting out

  # this line

  # this line

  # "-C", "linker=arm-none-eabi-ld",

  # "-C", "linker=arm-none-eabi-ld",

            "runToMain": true,

            "runToMain": true,

            "svdFile": "${workspaceRoot}/.vscode/STM32F401.svd",

            "svdFile": "${workspaceRoot}/.vscode/STM32F401.svd",

            "configFiles": [

            "configFiles": [

                "interface/stlink-v2-1.cfg",

                "interface/stlink.cfg",

                "target/stm32f4x.cfg"

                "target/stm32f4x.cfg"

            ],

            ],

            "preRestartCommands": [

            "preRestartCommands": [

                    }

                    }

                ]

                ]

            },

            },

            "executable": "./target/thumbv7em-none-eabi/debug/examples/${fileBasenameNoExtension}",

            "executable": "./target/thumbv7em-none-eabihf/debug/examples/${fileBasenameNoExtension}",

            "cpu": "cortex-m4",

        },

        {

            "type": "cortex-debug",

            "request": "launch",

            "name": "Cortex Debug 48Mhz",

            "servertype": "openocd",

            "cwd": "${workspaceRoot}",

            "preLaunchTask": "cargo build --example",

            "runToMain": true,

            "svdFile": "${workspaceRoot}/.vscode/STM32F401.svd",

            "configFiles": [

                "interface/stlink.cfg",

                "target/stm32f4x.cfg"

            ],

            "preRestartCommands": [

                "load",

            ],

            "postLaunchCommands": [

                "monitor arm semihosting enable"

            ],

            "swoConfig": {

                "enabled": true,

                "cpuFrequency": 48000000,

                "swoFrequency": 2000000,

                "source": "probe",

                "decoders": [

                    {

                        "type": "console",

                        "label": "ITM",

                        "port": 0

                    }

                ]

            },

            "executable": "./target/thumbv7em-none-eabihf/debug/examples/${fileBasenameNoExtension}",

            "cpu": "cortex-m4",

            "cpu": "cortex-m4",

        },

        },

        {

        {

            "runToMain": true,

            "runToMain": true,

            "svdFile": "${workspaceRoot}/.vscode/STM32F401.svd",

            "svdFile": "${workspaceRoot}/.vscode/STM32F401.svd",

            "configFiles": [

            "configFiles": [

                "interface/stlink-v2-1.cfg",

                "interface/stlink.cfg",

                "target/stm32f4x.cfg"

                "target/stm32f4x.cfg"

            ],

            ],

            "preRestartCommands": [

            "preRestartCommands": [

                    }

                    }

                ]

                ]

            },

            },

            "executable": "./target/thumbv7em-none-eabi/release/examples/${fileBasenameNoExtension}",

            "executable": "./target/thumbv7em-none-eabihf/release/examples/${fileBasenameNoExtension}",

            "cpu": "cortex-m4",

            "cpu": "cortex-m4",

        },

        },

        {

        {

            "type": "cortex-debug",

            "type": "cortex-debug",

            "request": "launch",

            "request": "launch",

            "name": "Cortex Nightly",

            "name": "Cortex Release 48Mhz",

            "servertype": "openocd",

            "servertype": "openocd",

            "cwd": "${workspaceRoot}",

            "cwd": "${workspaceRoot}",

            "preLaunchTask": "cargo build --example --release --nightly",

            "preLaunchTask": "cargo build --example --release",

            "runToMain": true,

            "runToMain": true,

            "svdFile": "${workspaceRoot}/.vscode/STM32F401.svd",

            "svdFile": "${workspaceRoot}/.vscode/STM32F401.svd",

            "configFiles": [

            "configFiles": [

                "interface/stlink-v2-1.cfg",

                "interface/stlink.cfg",

                "target/stm32f4x.cfg"

                "target/stm32f4x.cfg"

            ],

            ],

            "preRestartCommands": [

            "preRestartCommands": [

            "postLaunchCommands": [

            "postLaunchCommands": [

                "monitor arm semihosting enable"

                "monitor arm semihosting enable"

            ],

            ],

            "executable": "./target/thumbv7em-none-eabi/release/examples/${fileBasenameNoExtension}",

            "swoConfig": {

            "cpu": "cortex-m4",

                "enabled": true,

        },

                "cpuFrequency": 48000000,

                "swoFrequency": 2000000,

                "source": "probe",

                "decoders": [

                    {

                        "type": "console",

                        "label": "ITM",

                        "port": 0

                    }

                ]

                ]

            },

            "executable": "./target/thumbv7em-none-eabihf/release/examples/${fileBasenameNoExtension}",

            "cpu": "cortex-m4",

        }

        }

    ]

}.

 No newline at end of file

    "version": "2.0.0",

    "version": "2.0.0",

    "tasks": [

    "tasks": [

        {

        {

            "type": "cargo",

            "label": "cargo build --example",

            "command": "build --example ${fileBasenameNoExtension}",

            "command": "cargo",

            "problemMatcher": [

            "args": [

                "$rustc"

                "build",

                "--example",

                "${fileBasenameNoExtension}"

            ],

            ],

            "group": "build",

            "label": "cargo build --example"

        },

        {

            "type": "cargo",

            "command": "build --example ${fileBasenameNoExtension} --release",

            "problemMatcher": [

            "problemMatcher": [

                "$rustc"

                "$rustc"

            ],

            ],

            "group": "build",

            "group": "build",

            "label": "cargo build --example --release"

        },

        },

        {

        {

            "type": "cargo",

            "label": "cargo build --example --release",

            "command": "build --example ${fileBasenameNoExtension} --release --features nightly",

            "command": "cargo",

            "args": [

                "build",

                "--example",

                "${fileBasenameNoExtension}",

                "--release"

            ],

            "problemMatcher": [

            "problemMatcher": [

                "$rustc"

                "$rustc"

            ],

            ],

            "group": "build",

            "group": "build",

            "label": "cargo build --example --release --nightly"

        },

        }

    ]

    ]

}

}

 No newline at end of file

# Changelog

## 2021-03-19

- `examples/itm_rtic_hello_48MHz.rs`, example to trace ITM, when processor runs at 48MHz, useful to debug USB applications.

- `.vscode/launch.json`, added 48MHz itm tracing profiles. (Now consistenly using `stlink.cfg`.)

## 2021-03-18

- `examples/usb-mouse.rs`, a very small example using external hid library.

## 2021-03-07

- `examples/rtic_bare7.rs`, using embedded HAL.

- `examples/rtic_bare8.rs`, serial communication, bad design.

- `examples/rtic_bare9.rs`, serial communication, good design.

## 2021-03-05

- `examples/rtic_bare6.rs`, setup and validate the clock tree.

## 2021-02-28

- `examples/rtic_bare2.rs`, raw timer access.

- `examples/rtic_bare3.rs`, timing abstractions.

- `examples/rtic_bare4.rs`, a simple bare metal peripheral access API.

- `examples/rtic_bare5.rs`, write your own C-like peripheral access API.

## 2021-02-26

- `examples/bare1.rs`, bare metal 101!

## 2021-02-23

- `examples/rtic_blinky.rs`, added instructions to terminal based debugging

## 2021-02-22

- `memory.x`, reduced flash size to 128k to match light-weight target

- `Cargo.toml`, updated dependencies to latest `stm32f4xx-hal/pac`

Some experiments (wip):

- `examples/rtt_rtic_i2c.rs`, spi emulation over i2c

- `src/pwm3389e`, driver using emulated spi

## 2021-02-16

- `rtt_rtic_usb_mouse` updated

  Notice, requires release build

## 2021-02-15

- Initial release for the e7020e course 2021

 No newline at end of file

version = "0.1.0"

version = "0.1.0"

[dependencies]

[dependencies]

cortex-m = "0.6.4"

cortex-m = { version = "0.7.1", features = ["linker-plugin-lto"] }

# cortex-m = { version = "0.7.1" }

cortex-m-rt = "0.6.13"

cortex-m-rt = "0.6.13"

cortex-m-semihosting = "0.3.7"

cortex-m-semihosting = "0.3.7"

cortex-m-rtic = "0.5.5"

cortex-m-rtic = "0.5.5"

# embedded-hal = { version = "0.2.4", features = ["unproven"] }

embedded-hal = "0.2.4"

embedded-hal = "0.2.4"

usb-device = "0.2.7"

usb-device = "0.2.7"

# Panic handlers, comment all but one to generate doc!

# Panic handlers, comment all but one to generate doc!

panic-halt = "0.2.0"

panic-halt = "0.2.0"

# Uncomment for the panic example.

# Uncomment for the itm panic examples.

#panic-itm = "0.4.2"

panic-itm = "0.4.2"

# Uncomment for the rtt-timing example.

# Uncomment for the rtt-timing examples.

#panic-rtt-target = { version = "0.1.1", features = ["cortex-m"] }

panic-rtt-target = { version = "0.1.1", features = ["cortex-m"] }

# Uncomment for the panic example.

# Uncomment for the semihosting examples.

#panic-semihosting = "0.5.6"

panic-semihosting = "0.5.6"

# Tracing

# Tracing

rtt-target = { version = "0.3.0", features = ["cortex-m"] }

rtt-target = { version = "0.3.1", features = ["cortex-m"] }

nb = "1.0.0"

usbd-hid = "0.5.0"

micromath = "1.1.0"

[dependencies.stm32f4]

[dependencies.stm32f4]

version = "0.12.1"

version = "0.13.0"

features = ["stm32f411", "rt"]

features = ["stm32f411", "rt"]

# Uncomment for the allocator example.

# alloc-cortex-m = "0.4.0"

[dependencies.stm32f4xx-hal]

[dependencies.stm32f4xx-hal]

version = "0.8.3"

version = "0.9.0"

features = ["rt", "stm32f411", "usb_fs"] 

features = ["rt", "stm32f411", "usb_fs"] 

git = "https://github.com/stm32-rs/stm32f4xx-hal"

# Enable to use the latest git version

# gitgit = "https://github.com/stm32-rs/stm32f4xx-hal"

# Enable to use your forked/cloned local repo 

# path = "../stm32f4xx-hal"

# this lets you use `cargo fix`!

# this lets you use `cargo fix`!

[[bin]]

# [[bin]]

name = "app"

# name = "app"

test = false

# # test = false

bench = false

# bench = false

[profile.dev]

[profile.dev]

incremental = false

incremental = false

codegen-units = 1

codegen-units = 1

overflow-checks = false  

[profile.release]

[profile.release]

incremental = false

codegen-units = 1 # better optimizations

codegen-units = 1 # better optimizations

debug = true      # symbols are nice and they don't increase the size on Flash

debug = true      # symbols are nice and they don't increase the size on Flash

lto = true        # better optimizations

lto = true        # better optimizations

# [features]

# nightly = ["cortex-m/inline-asm"]

# # this lets you use `cargo fix`!

# [[bin]]

# name = "app"

# test = false

# bench = false

# [profile.release]

# codegen-units = 1 # better optimizations

# debug = true      # symbols are nice and they don't increase the size on Flash

# lto = true        # better optimizations

# App

# RTIC on the STM32F4xx Nucleo board

## Resources

All tooling have been developed and tested under Linux. Any modern Linux distro should work, we usually recommend Arch linux as it provides a great package manager with rolling releases. If you want to run Arch, but don't want to install everything from scratch, you may opt for [Manjaro](https://manjaro.org/) or [Endeavour](https://endeavouros.com/). You will get the best user experience by a native install, but you may run Linux under a VM like virtualbox, or vmware (the player is free). You should install the guest extensions, to get better graphics performance (and perhaps better USB forwarding). Since you will connect your Nucleo using USB, you must make sure that USB port forwarding works (the Nucleo stlink programmer is a USB2 device running in full speed 12MBit).

This repo will be updated with more information throughout the course so please check the `CHANGELOG.md` and recent commits to see what has changed. (You should `pull` the upstream to keep your repository updated.) If you have suggestions to further improvements, please raise an issue and/or create a merge/pull request.

## Rust

We assume Rust to be installed using [rustup](https://www.rust-lang.org/tools/install).

Additionally you need to install the `thumbv7em-none-eabi` target.

```shell

> rustup target add thumbv7em-none-eabi 

```

You also need [cargo-binutils](https://github.com/rust-embedded/cargo-binutils), for inspecting the generated binaries. You install Rust applications through `cargo`

```shell

> cargo install cargo-binutils

```

There are a number of other useful [cargo subcommands](https://github.com/rust-lang/cargo/wiki/Third-party-cargo-subcommands), notably `cargo-bloat` (that gives you info on the size of different sections of the generated binary), `cargo-tree` (that list your dependency tree), etc.

## For RTT tracing

We assume the following tools are in place:

- [probe-run](https://crates.io/crates/probe-run)

## For programming and low level `gdb` based debugging

Linux tooling:

- `stlink`, this package will install programming utilities like `st-flash` (useful if you need to recover a bricked target by erasing the flash), and setup `udev` rules, allowing you to access the USB device without `sudo`. Install may require you to login/logout to have new `udev` rules applied.

- `openocd`, this tool allows the host to connect to the (stlink) programmer.

- `arm-none-eabi-gdb`, or `gdb-multiarch` (dependent on Linux distro). This tool allows you to program (flash) and debug your target.

## Editor

You may use any editor of choice. `vscode` supports Rust using the  `rust-analyzer` plugin. You may also want to install the `Cortex Debug` plugin. In the `.vscode` folder, there are a number of configuration files (`launch.json` for target debugging, `tasks.json` for building, etc.).

## Useful Resources

- Nucleo 64

- Nucleo 64

  - [UM1724 - stm32 Nucleo-64](https://www.st.com/resource/en/user_manual/dm00105823-stm32-nucleo64-boards-mb1136-stmicroelectronics.pdf).

  - [UM1724 - stm32 Nucleo-64](https://www.st.com/resource/en/user_manual/dm00105823-stm32-nucleo64-boards-mb1136-stmicroelectronics.pdf).

  - [Nucleo 64 Schematics](https://www.st.com/resource/en/schematic_pack/nucleo_64pins_sch.zip) (The file MB1136.pdf is the schematics in pdf.)

  - [Nucleo 64 Schematics](https://www.st.com/resource/en/schematic_pack/nucleo_64pins_sch.zip) (The file MB1136.pdf is the schematics in pdf.)

  - [stm32f4xx_hal](https://docs.rs/stm32f4xx-hal/0.8.3/stm32f4xx_hal/) documentation of the HAL API, and [git repository](https://github.com/stm32-rs/stm32f4xx-hal).

  - [stm32f4xx_hal](https://docs.rs/stm32f4xx-hal/0.8.3/stm32f4xx_hal/) documentation of the HAL API, and [git repository](https://github.com/stm32-rs/stm32f4xx-hal).

- STM32F01/FO11

- STM32F01/FO11

  - [RM0383 - F411 Reference Manual](https://www.st.com/resource/zh/reference_manual/dm00119316-stm32f411xce-advanced-armbased-32bit-mcus-stmicroelectronics.pdf) 

  - [RM0383 - F411 Reference Manual](https://www.st.com/resource/zh/reference_manual/dm00119316-stm32f411xce-advanced-armbased-32bit-mcus-stmicroelectronics.pdf) 

  - [RM0368 - F401 Reference Manual](https://www.st.com/resource/en/reference_manual/dm00096844-stm32f401xbc-and-stm32f401xde-advanced-armbased-32bit-mcus-stmicroelectronics.pdf)

  - [RM0368 - F401 Reference Manual](https://www.st.com/resource/en/reference_manual/dm00096844-stm32f401xbc-and-stm32f401xde-advanced-armbased-32bit-mcus-stmicroelectronics.pdf)

- General Embedded

- General Embedded

  - [Introduction to SPI](https://www.analog.com/en/analog-dialogue/articles/introduction-to-spi-interface.html#), a short introduction to the SPI interface.

  - [Introduction to SPI](https://www.analog.com/en/analog-dialogue/articles/introduction-to-spi-interface.html#), a short introduction to the SPI interface.

---

## Examples

### VSCODE based debug and trace

Some simple bare metal examples for you to try out before starting to run your own code:

Using `vscode` just press F5 to launch and debug the program in the currently active vscode window.

- `rtic_hello.rs`, this example uses semihosting to print the output terminal. Open the `OUTPUT` pane, and select `Adapter Output` (which is the openocd console).

- `itm_rtic_hello.rs`, this examples uses the ITM trace to print to an output trace channel. Open the `OUTPUT` pane, and select `SWO:ITM[port:0, type:console]`.

- `rtic_panic.rs`, this example shows how to trace panic messages (in this case over semihosting).  Open the `OUTPUT` pane, and select `Adapter Output` (which is the openocd console).

- `rtic_crash.rs`, this example shows how to trace a HardFault (an error raised by the ARM processor).

---

### Exercises

Bare metal programming:

- `examples/rtic_bare1.rs`, in this exercise you learn about debugging, inspecting the generated assembly code, inline assembly, and about checked vs. unchecked (wrapping) arithmetics. Provides essential skills and understanding of low level (bare metal) programming.

- `examples/rtic_bare2.rs`, in this exercise you learn how to measure execution time using raw timer access.

- `examples/rtic_bare3.rs`, here you learn more about RTIC timing semantics and timing abstractions.

- `examples/rtic_bare4.rs`, in this exercise you will encounter a simple bare metal peripheral access API. The API is very unsafe and easy to misuse.

- `examples/rtic_bare5.rs`, here you will write your own C-like peripheral access API. This API is much safer as you get control over bit-fields in a well defined way, thus less error prone.

- `examples/rtic_bare6.rs`, in this exercise you learn about clock tree generation and validation.

- `examples/rtic_bare7.rs`, here you learn more on using embedded HAL abstractions and the use of generics.

- `examples/rtic_bare8.rs`, in this exercise you will setup serial communication to receive and send data. You will also see that polling may lead to data loss in a bad design.

- `examples/rtic_bare9.rs`, here you revisit serial communication and implement a good design in RTIC leveraging preemptive scheduling to ensure lossless communication.

---

---

## Connections

### Console based debug and trace

- `rtt_rtic_hello.rs`, this example uses the RTT framework for tracing.

- [USB Cable]

  ```shell

  > cargo run --example rtt_rtic_hello

  ```

---

## Nucleo Connections

---

| Signl | Color | Pin  |

Some of the examples need external connection to the Nucleo to work.

| ----- | ----- | ---- |

| V+    | Red   | ---- |

| D-    | White | PA11 |

| D+    | Green | PA12 |

| Gnd   | Black | ---- |

D+ used for re-enumeration

---

### USB example

| Signal | Color | Pin  | Nucleo    |

| ------ | ----- | ---- | --------- |

| V+     | Red   |      |           |

| D-     | White | PA11 | CN10 - 14 |

| D+     | Green | PA12 | CN10 - 12 |

| Gnd    | Black |      | CN10 - 9  |

D+ used for re-enumeration. You don't need to connect the V+ from the USB cable, as the NUCLEO is self powered.

---

### PWM example

| Signal | Pin | Nucleo  |

| ------ | --- | ------- |

| PWM1   | PA8 | CN9 - 8 |

| PWM2   | PA9 | CN5 - 1 |

---

### I2C example

| Signal   | Pin | Nucleo |

| -------- | --- | ------ |

| I2C1_SDA | PB9 | CN10-5 |

| I2C1_SCL | PB8 | CN10-3 |

| +3.3v    |     | CN7-16 |

| GND      |     | Gnd    |

## Debug interface

## Debug interface

- Serial Wire debugging uses pins PA13 and PA14.

- Serial Wire debugging uses pins PA13 and PA14. So refrain from using those unless absolutely necessary.

---

## Troubleshooting

---

### Fail to connect or program (flash) your target

- Make sure you have the latest version of the [stlink](https://www.st.com/en/development-tools/stsw-link007.html) firmware (2.37.27 or later).

- Check that your stlink nucleo programmer is found by the host.

  ```shell

  > lsusb

  ...

  Bus 003 Device 013: ID 0483:374b STMicroelectronics ST-LINK/V2.1

  ...

  ```

  If not check your USB cable. Notice, you need a USB data cable (not a USB charging cable).

  If the problem is still there, there might be a USB issue with the host (or VM if you run Linux under a VM that is).

- If you get a connection error similar to the below:

  ```shell

  > openocd -f openocd.cfg

  Open On-Chip Debugger 0.10.0+dev-01157-gd6541a811-dirty (2020-03-28-18:34)

  Licensed under GNU GPL v2

  For bug reports, read

        http://openocd.org/doc/doxygen/bugs.html

  Info : auto-selecting first available session transport "hla_swd". To override use 'transport select <transport>'.

  Info : The selected transport took over low-level target control. The results might differ compared to plain JTAG/SWD

  Info : Listening on port 6666 for tcl connections

  Info : Listening on port 4444 for telnet connections

  Info : clock speed 2000 kHz

  Info : STLINK V2J37M26 (API v2) VID:PID 0483:374B

  Info : Target voltage: 3.243627

  Info : stm32f4x.cpu: hardware has 6 breakpoints, 4 watchpoints

  Info : Listening on port 3333 for gdb connections

  Error: jtag status contains invalid mode value - communication failure

  Polling target stm32f4x.cpu failed, trying to reexamine

  Examination failed, GDB will be halted. Polling again in 100ms

  Info : Previous state query failed, trying to reconnect

  Error: jtag status contains invalid mode value - communication failure

  Polling target stm32f4x.cpu failed, trying to reexamine 

  ```

  - First thing to try is holding the reset button while connecting.

  - If this does not work you can try to erase the flash memory (the program running on the STM32F401/F11).

    ``` shell

    > st-flash erase

    st-flash 1.7.0

    2021-06-23T14:07:35 INFO common.c: F4xx (Dynamic Efficency): 96 KiB SRAM, 512 KiB flash in at least 16 KiB pages.

    Mass erasing.......

    ```

  - If this still does not work you can connect `Boot0` to `VDD` (found on CN7 pins 7, and 5 respectively). Unplug/replug the Nucleo and try to erase the flash as above.

  - If this still does not work, the Nucleo might actually been damaged, or that the problem is the usb-cable or host   machine related.

//! updating `memory.x` ensures a rebuild of the application with the

//! updating `memory.x` ensures a rebuild of the application with the

//! new memory settings.

//! new memory settings.

use core::f64::consts::PI;

use std::env;

use std::env;

use std::fs::File;

use std::fs::File;

use std::io::Write;

use std::{

use std::path::PathBuf;

    io::{Result, Write},

    path::{Path, PathBuf},

};

fn main() {

fn main() -> Result<()> {

    // Put `memory.x` in our output directory and ensure it's

    // Put `memory.x` in our output directory and ensure it's

    // on the linker search path.

    // on the linker search path.

    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());

    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());

    // here, we ensure the build script is only re-run when

    // here, we ensure the build script is only re-run when

    // `memory.x` is changed.

    // `memory.x` is changed.

    println!("cargo:rerun-if-changed=memory.x");

    println!("cargo:rerun-if-changed=memory.x");

    // generate a sine table

    println!("cargo:rerun-if-changed=build.rs");