Undergraduate Teaching Platform: for the TI TM4C Launchpad! 👷

Uses thejpster's tm4c-hal crates heavily.

🐝 🚧 This is very much not stable yet! 🚧 🐝

Usage

To be used in conjuction with the UTP TUI.

First: Flash your TM4C

You can grab a TM4C image (a .bin file; TODO: issue #5) from the releases page.

You'll need to grab lm4flash and potentially install a driver in order to flash your TM4C. This page has instructions on how to do so.

(TODO: replace with utp-tui --flash tm4c; flip the sections around so that installing the TUI comes first!) Once you've done this, to flash your board run lm4flash -v <path to the .bin file>.

On macOS and Linux:

• lm4flash -v utp-tm4c.bin On Windows:
• lm4flash.exe -v utp-tm4c.bin

At this point, if flashing the board was successful, your on-board LED should be blinking (TODO: issue #4).

(TODO: ulimately we want to switch to probe-rs and have the TUI handle this, actually...) (See: ut-utp/tui#11)

Next: Launch the TUI

First install the UTP TUI if you haven't already.

Next, find your device's serial port:

• Windows: open device manager, look for COM ports, find the one that says stellaris
• macOS: look in /dev/ for something that starts with /dev/cu.usbmodem
• Linux: dmesg | tail after you plug in or look in /dev/ (probably something like /dev/ttyACM0 if you don't have the udev rule; otherwise /dev/tm4c)

And finally, run the TUI with the --device board=<serial port path>:1500000 flag.

For example:

• Windows: utp-tui.exe --device board=COM11:1500000
• macOS: ./utp-tui --device board=/dev/cu.usbmodemABCD1234:1500000
• Linux: ./utp-tui --device board=/dev/tm4c:1500000

(TODO: ultimately we want to streamline this to just utp-tui --device tm4c, tui#6)

Development

Setup

If you're looking to make changes to or hack on utp-tm4c there are a few more things you'll need to set up!

Using Nix

Note: If you're using macOS or Linux we strongly recommend using nix and VSCode. This is the best supported workflow.

Otherwise

Follow these instructions to set up your dev environment. Be sure to also follow the "Embedded Development Setup" instructions.

Doing Development

TODO: VSCode aliases TODO: targets for all of these..

To build the project:

• cargo b to build just the main program
• cargo ba to build everything

rustup will automatically fetch the appropriate toolchain and the tools needed to build for ARM.

To flash your board (without attaching a debugger):

• cargo f
  • This uses lm4flash and attempts to grab lm4flash binaries from here if you do not already have it installed locally.

To run a program that has console output:

• cargo r --bin <bin name> for binaries
• cargo r --example <example name> for examples
• this will drop you into picocom if you have it installed (TODO)

To debug the project (launches a debugger):

• cargo d
  • This uses gdb as a "runner" as specified in .cargo/config.
  • If you're not using nix, make sure you have installed GDB, OpenOCD, and the LLVM binutils as described in the setup guide.
  • You may need to configure GDB to allow autoloading .gdbinit (optional).

🚨 NOTE 🚨: Be sure to run continue before exiting GDB! If you do not do this your board will enter a bad state and will need to be power cycled before you can attach a debugger to it again.

To run the tests:

• cargo t to run all tests (with assertions)
• cargo tr to run all tests in release mode
• cargo test --test <test name> --target thumbv7em-none-eabihf -- --test to run a specific test (add --release before the -- for release mode)

To run the benchmarks:

• cargo ben to run all the benchmarks
• cargo ben --bench <benchmark name> to run a specific benchmark

VSCode Support

This project also has a VSCode workspace that is configured with build and debug support for this project.

To build:

• the default build task builds the project
• trigger this with:
  • ctrl + shift + b on Windows/Linux
  • cmd + shift + b on macOS

To run/debug the project (launches VSCode's integrated debugger):

• the default launch configuration builds the project and starts a debugging session
• trigger this by pressing f5
  • or focus on the Debug tab in the sidebar and press the green play button
• Note: Windows users will need to modify launch.json to make reference to Windows executables for gdb, openocd, and llvm-objdump
  • i.e. replace gdb with gdb.exe, etc.
• Note: if you are not using nix you will need to manually fetch TM4C123GH6PM.svd and place it at .vscode/TM4C123GH6PM.svd if you want to use the device register views that the Cortex-Debug extension offers
  • i.e. curl -L https://raw.githubusercontent.com/posborne/cmsis-svd/master/data/TexasInstruments/TM4C123GH6PM.svd > .vscode/TM4C123GH6PM.svd

🚨 NOTE 🚨: Be sure to continue (F5) before exiting your debug session! If you do not do this your board will enter a bad state and will need to be power cycled before you can attach a debugger to it again.

(TODO: tests, test task, etc.)