Skip to content

Getting started

Jump to bottom
Felipe Balbi edited this page Nov 19, 2024 · 9 revisions

Getting Started Guide

In order to contribute to most the repositories in this project, you will need a Text Editor of your choice --- which we assume to be installed already ---, git, a rust toolchain, and an RT685 EVK board.

Installing Rust

The easiest way to install rust is through the rustup toolchain installer. Please visit the official rustup.rs website and follow the on-screen instructions to get it installed on your OS of choice.

This will install:

  1. rustc: the rust compiler
  2. cargo: build system and package manager
  3. rust-analyzer: language server protocol implementation
  4. clippy: static analyzer
  5. rustfmt: code formatter

Install Dependencies

git

Most likely git is available from the various package managers of different operating systems, here are a few possibilities:

Windows

$ winget install -i Git.Git

macOS

$ brew install git

Debian and derivatives (Ubuntu, Mint, etc)

$ sudo apt install git

Arch Linux

$ sudo pacman -Sy git

Gentoo

$ sudo emerge --ask dev-vcs/git

Fedora

$ sudo dnf install git-all

flip-link

Most of the examples here rely on flip-link as a linker wrapper. The goal of flip-link is the add zero-cost stack overflow protection by flipping the order in which the binary is crated. Traditionally, the stack is placed at the top of RAM, growing in the direction of .bss section (placed at the bottom of RAM) as shown in the figure below:

left: default memory layout of ARM Cortex-M programs; right: stack overflow condition

With flip-link this order is reversed, with .bss placed at the top of RAM and the stack following it, as shown below.

left: flipped memory layout; right: stack overflow condition

We can install flip-link with a simple cargo command:

$ cargo install flip-link

probe-rs

We use probe-rs for flashing and debugging binaries on the target MCU. Currently, we need to use the latest HEAD from probe-rs repository.

We can install it with the following cargo command:

$ cargo install probe-rs-tools --git https://github.com/probe-rs/probe-rs --locked --force

Cloning the main repository

The main Embassy HAL repository is located here. You can use git to grab a copy for your local development:

$ git clone https://github.com/pop-project/embassy-imxrt.git

Once it's cloned, make sure to read our Programming RT685EVK guide for details of how to setup the board either with the embedded LINK2 probe or an external JLink.

Once that's done, you should be able to run e.g. the gpio-blinky example which will blink the blue LED on the EVK:

$ cd embassy-imxrt/examples/rt685s-evk
$ cargo run --bin gpio-blinky
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.21s
     Running `probe-rs run --chip MIMXRT685SFVKB target\thumbv8m.main-none-eabihf\debug\gpio-blinky`
      Erasing ✔ 100% [####################]  72.00 KiB @  49.86 KiB/s (took 1s)
  Programming ✔ 100% [####################]  69.00 KiB @   9.80 KiB/s (took 7s)
     Finished in 7.09s
60728.340000 TRACE SysOsc was already enabled
└─ embassy_imxrt::clocks::{impl#27}::enable_and_reset @ D:\workspace\pop-project\embassy-imxrt\src\clocks.rs:1241
60728.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27
60729.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27
60730.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27
60731.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27
60732.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27
60733.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27
60734.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27
60735.350000 INFO  Toggling LED
└─ gpio_blinky::____embassy_main_task::{async_fn#0} @ src\bin\gpio-blinky.rs:27

Further Reading

A few important Wiki pages to read:

  1. Rust Learning References
  2. Programming RT685EVK
  3. Debugging within VS Code

Troubleshooting

To use Jlink debug probe, v11 or newer that DOES support winusb:

Connect probe to host pc

Run c:\program files\segger\jlink[version]\jlinkconfig.exe

Change driver mode of probe to Winusb

To use Jlink debug probe, v10 or older that does not support windusb:

Install Zadig - USB driver installation made easy (akeo.ie)

Change Jlink driver from Jlink to winusb

If probe-rs or VC debug hits a blocking error with jlink:

Close any active debug session

Run:

c:\program files\segger\jlink[version]\Jlink.exe -device MIMXRT685S_M33 -if SWD -Speed 4000

connect

Q or ctrl+c to close jlink.exe

Then try debugging again

Clone this wiki locally