Crate ra_hal

Expand description

§ra-hal

ra-hal is a Hardware Abstraction Layer (HAL) for the Renesas Renesas RA family of microcontrollers written in Rust. This HAL implements a variety of traits to provide both asynchronous and blocking interfaces that enable compatibility with software frameworks like Embassy and RTIC as well as more general libraries like embedded-hal. The end goal is to provide a safe, idiomatic Rust interface that surfaces most of the flexibility provided by the RA microcontrollers.

§Documentation

For more information check out the docs and take a peek at the examples. To build documentation for a specific group run:

just doc-<chip>

Replace <chip> with the model of your MCU. To automatically open the generated documentation in a web browser append the --open argument.

§Application Template

A template suitable for cargo-generate is available at: https://git.sr.ht/~az1/ra-template. This template can be used to generate an Embassy project that uses the HAL or a PAC based project.

§Prerequisites

Ensure cargo-generate is installed.
Get familiar with Embassy.

§Usage

$ cargo generate --git https://git.sr.ht/~az1/ra-template --branch metapac
<follow the prompts>
$ cd <name of your new project>
$ cargo build --release
$ cargo run --release

Check out the examples and the Embassy docs if you’re not already familiar.

§Limitations

Currently only one core per MCU is supported (relevant for multi-core RA8 MCUs).
On MCUs with TrustZone™ support the HAL is designed to only work in secure mode.
RA2: Use of the RA2 family is subject to significant caveats. No compile- or run-time checking of interrupt groups is done. Atomic ops may hang or report failure (TN-RA*-A0098A/E).
EK-RA2A1: Despite a reported 500 kHz maximum SWO speed, the onboard J-Link seems to work most reliably with probe-rs when the SWO frequency is limited to 125 kHz via the --speed 125 argument.
TODO: Add knobs to generate a HAL+RTICv2 project.

For the canonical list of known issues check the issue tracker.

https://todo.sr.ht/~az1/ra-rs/

§Development

§Prerequisites

MSRV is 1.95, rust-toolchain.toml has been set to 1.95. Older versions of Rust will not work as we depend on cfg_select!.
just. just can be installed by via cargo install just.
probe-rs for debugging and flashing.

To use a local version of ra-metapac for development you can patch cargo with a configuration file named cargo-config.toml in the root directory of ra-hal. For example:

[patch."https://git.sr.ht/~az1/ra-metapac"]
ra-metapac = { path = "/path/to/ra-metapac/ra-metapac" }

§Feature flags

rt (enabled by default) — Enable the rt feature of the PAC. With rt enabled the PAC provides interrupt vectors instead of letting cortex-m-rt do that. See https://docs.rs/cortex-m-rt/latest/cortex_m_rt/#device for more info.
cache — Enable the flash cache. The cache is invalidated after each DMAC / DTC operation. See: §44.3.
chrono (enabled by default) — Enable dependency on chrono and expose methods that work with chrono structures.
defmt — Use defmt for logging.
diag (enabled by default) — Log the reset reason during initialization. Only useful in conjunction with defmt feature.
swd-as-gpio — Allow access to pins normally used for JTAG/SWD debugging
unstable-pac — Re-export the PAC at ra_hal::pac. This is unstable because minor HAL updates may depend on major PAC updates.
strict-assert (enabled by default) — Extra runtime assertions.
skip-osm — Don’t set OSM registers in the HAL, instead define them in your application.

§Time features

time-driver-gpt0 — Enables support for embassy-time and provides a time driver using a 32-bit GPT instance (GPT32_0).
time-driver-gpt1 — Enables support for embassy-time and provides a time driver using a 32-bit GPT instance (GPT32_1).
time-driver-agt — Enables support for embassy-time and provides a time driver using a 32-bit AGTW instance.
time-driver-ulpt — Enables support for embassy-time and provides a time driver using a 32-bit ULPT instance.

§USB features

§On-Chip Oscillator Configuration

Consult your reference manual for valid frequencies. TODO: Decouple this from the embassy tick rate.

hoco_16mhz — Sets the high speed on-chip oscillator (HOCO) to 16 MHz.
hoco_18mhz — Sets the high speed on-chip oscillator (HOCO) to 18 MHz.
hoco_20mhz — Sets the high speed on-chip oscillator (HOCO) to 20 MHz.
hoco_32mhz — Sets the high speed on-chip oscillator (HOCO) to 32 MHz.
hoco_40mhz — Sets the high speed on-chip oscillator (HOCO) to 40 MHz.
hoco_48mhz — Sets the high speed on-chip oscillator (HOCO) to 48 MHz.
hoco_64mhz — Sets the high speed on-chip oscillator (HOCO) to 64 MHz.
hoco_80mhz — Sets the high speed on-chip oscillator (HOCO) to 80 MHz.

§Chip Features

ra2a1 — RA2A1
ra4l1 — RA4L1
ra4m1 — RA4M1
ra6m5 — RA6M5
ra8m1 — RA8M1

§Memory Configuration

Consult the reference manual for valid configurations for your chip.

mem_ram64k_flash256k — 64K RAM, 256K flash
mem_ram64k_flash512k — 64K RAM, 512K flash
mem_ram512k_flash1024k — 512K RAM, 1024K flash
mem_ram512k_flash1536k — 512K RAM, 1536K flash
mem_ram512k_flash2048k — 512K RAM, 2048K flash
mem_ram896k_flash2016k — 896K RAM, 2016K flash

§Chip Package

Consult the reference manual for valid packages for your chip.

32lqfp — 32-pin LQFP
36bga — 36-pin BGA
40qfn — 40-pin QFN
48lqfp — 48-pin LQFP
48qfn — 48-pin QFN
64bga — 64-pin BGA
64lqfp — 64-pin LQFP
64qfn — 64-pin QFN
100bga — 100-pin BGA
100lga — 100-pin LGA
100lqfp — 100-pin LQFP
144bga — 144-pin BGA
144lqfp — 144-pin LQFP
176bga — 176-pin BGA
176lqfp — 176-pin LQFP
224bga — 224-pin BGA

Re-exports§

pub use chrono;

Modules§

adc: Analog-to-Digital Converter (ADC12, ADC14, ADC16).
clock: Clock information and configuration.
constants
crc: Cyclic Redundancy Check Calculator (CRC).
dac: 12-bit Digital-to-Analog Converter (DAC12).
dmac: Direct Memory Access Controller (DMAC).
dtc: Data Transfer Controller (DTC).
event_link: Event Link Controller (ELC) and Interrupt Controller Unit (ICU) related shenanigans.
gpio: General Purpose Input/Output (PORT).
i2c: I2C Bus Interface (IIC).
interrupt: Interrupt definitions.
mcu_info: Factory MCU Information
module_stop: Module stop (MSTP).
osm: Option-Setting Memory (OFS0, OFS1, SECMPU).
peripherals: Types for the peripheral singletons.
pwm: Pulse Width Modulation driver utilizing the General PWM Timer (GPT).
qdec: Quadrature decoder driver (GPT) utilizing the General PWM Timer (GPT).
spi: Serial Peripheral Interface (SPI).
time_driver: Driver for embassy-time.
timer_agt: Timer that generates interrupts utilizing the Low Power Asynchronous General Purpose Timer (AGT / AGTW).
timer_gpt: Timer that generates interrupts utilizing the General PWM Timer (GPT).
uart: Universal Asynchronous Receiver-Transmitter
usb: USB Full-Speed 2.0 peripheral.
watchdog: Watchdog drivers.
write_protect: Conveniences for registers that are gated by a write protect flag.

Macros§

assert_eq: Expands to defmt::assert_eq! if the defmt feature is enabled, core impl otherwise.
bind_interrupts: Macro to bind interrupts to interrupt handlers.
debug: Log at the debug level if the defmt feature is enabled. No-op otherwise.
error: Log at the error level if the defmt feature is enabled. No-op otherwise.
exit: Calls the semihosting exit hook. Will cause an exception without a semihosting implementation on the host side.
info: Log at the info level if the defmt feature is enabled. No-op otherwise.
trace: Log at the trace level if the defmt feature is enabled. No-op otherwise.
warn: Log at the warn level if the defmt feature is enabled. No-op otherwise.

Structs§

Peri: An exclusive reference to a peripheral.
Peripherals: Struct containing all the peripheral singletons.

Enums§

ResetCause: Coarse indication of why the processor reset.

Constants§

CONFIGURED_FAMILY: MCU family e.g. RA4 that this firmware was configured/built for.
CONFIGURED_MCU: MCU group e.g. RA4M1 that this firmware was configured/built for.
NUM_INTERRUPTS: Number of interrupts exposed to the NVIC.

Functions§

init: Initializes the MCU.

Attribute Macros§

interrupt: Attribute to declare an interrupt (AKA device-specific exception) handler

Crate ra_hal

Crate ra_hal Copy item path

§ra-hal

§Documentation

§Application Template

§Prerequisites

§Usage

§Limitations

§Development

§Prerequisites

§Feature flags

§Time features

§USB features

§On-Chip Oscillator Configuration

§Chip Features

§Memory Configuration

§Chip Package

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Functions§

Attribute Macros§

Crate ra_hal