pic32-rs

Rust crates for PIC32 programming including PIC32 HAL modules

This repository contains code to program PIC32MX microcontrollers with Rust. It uses the mipsel-unknown-none target, which is intended for use with MIPS MCU ("bare metal") targets and is used to generate code for the classical MIPS32r2 ISA having 32 bit wide instructions.

The repository contains the following

• mips-rt: Basic Rust runtime and startup files for MIPS based microcontrollers
• pic32-hal: HAL crate for PIC32 microcontrollers. There are currently HAL modules for the MIPS core timer, GPIO, interrupt controller, SPI, UART, I2C and USB.
• example applications

Moreover, there are peripheral access crates (PACs) under the repository pic32-pac. There is also a repository alloc-pic32 to support dynamic memory allocation.

Compiling

To set up the toolchain, the following commands may be used.

rustup default nightly
rustup component add rust-src
cargo install cargo-binutils
rustup component add llvm-tools-preview

cargo-binutils includes cargo-objcopy that can be used to generate Intel HEX files. When other tools are used to generate HEX files (see below) or if your Flash memory programmer can deal with ELF files then cargo-binutils is not needed.

This code can be compiled with the nightly toolchain using cargo.

See also the blinky example on how to compile a PIC32 application.

A .cargo/config file is needed to specify the linker script (e.g. 32MX150F128B_procdefs.ld), to specify the target and to build standard library crates. Below see an example .cargo/config file.

[target.mipsel-unknown-none]
rustflags = ["-C", "link-arg=-T32MX150F128B_procdefs.ld"]

[build]
target = "mipsel-unknown-none"

[unstable]
build-std = ["core", "compiler_builtins", "alloc"]

Using the above files, the build can be done with cargo. To save code space, a release build may make sense.

cargo build --release

Creating hex files

The MMU-less PIC32 variants have a simple Fixed Mapping Translation (FMT) mechanism integrated in their cores that converts the virtual addresses used by the processor and known to the compiler to physical addresses. However, the Flash memory controller of the PIC32 MCUs operates on physical addresses.

Hex files with virtual addresses

If your programmer (such as pic32prog) accepts virtual addresses, cargo-objcopy can be used.

cargo objcopy --release -- -O ihex somefilename.hex

Hex files with physical addresses

If your programmer (such as the MPLAB IPE tools) accepts physical addresses only you need to create hex files that include physical addressed. One way to create such hex file is to use the tool xc32-bin2hex, which is part of the XC32 compiler toolchain. This tools converts the virtual addresses used in an ELF file to physical addresses before writing the hex file.

xc32-bin2hex target/mipsel-unknown-none/<your_elf_file>

An alternative to xc32-bin2hex is pic32-bin2hex, which is part of the chipKIT compiler.

Details on Linking

To link the final application image, three linker script files are used

• a file memory.x containing the memory map of the used device (needs to be adapted to the Flash memory size and the SRAM size).
• a file device.x contained in the peripheral access crate that provides symbolic names for the interrupt vectors
• a main linker script link.x, which is part of the mips-rt crate. This main linker scripts sources the contents of memory.x and device.x.

lib.rs:

Internal implementation details of mips-rt.

Do not use this crate directly. Almost identical to cortex_m_rt_macros