imxrt-hal
A Rust hardware abstraction layer (HAL) for NXP i.MX RT processors.
Goals
- Create the collaborative group to support using Rust on NXP's i.MX RT series.
- Simple but useful register level access. It compiles quickly, and it's intuitive for existing embedded developers. Every hal republishes the RAL.
- Embedded HAL support.
- RTIC support.
- NXP EVK board support
- Supporting popular boards such as the Teensy 4.
Getting Started
HAL
If you want to develop Rust libraries and applications for an i.MX RT-based system, use the imxrt-hal
crate. The imxrt-hal
crate provides implementations of the embedded-hal
traits specific to i.MX RT processors. Use the HAL if you want to
- toggle GPIOs
- use timers (GPTs, PITs)
- control PWM outputs (single pin)
- talk to I2C devices
- read and write serial data (UART)
- send and receive data over SPI
The publicly-supported HAL is on crates.io. Include the HAL in your Rust library or binary:
[dependencies.imxrt-hal]
version = "0.4"
features = ["imxrt1062", "rt"] # "rt" flag optional
Note the "imxrt1062"
feature flag. You're required to supply a feature flag that describes your i.MX RT variant. The HAL supports the following processors, as identified by feature flags:
-
"imxrt1062"
The "rt"
feature flag is recommended for users who are
- building executables that run on i.MX RT processors
- creating board support packages (BSP), or higher-level libraries, for i.MX RT systems
Enabling the "rt"
feature-flag will link in the i.MX RT interrupt table. If you're familiar with crates that are generated from svd2rust
, the "rt"
feature has the same behaviors in the imxrt-hal
as it does in svd2rust
-generated crates.
Future of the HAL
Follow #56 to understand how we're breaking imxrt-hal
into separate crates. If you'd like to try the new HAL crate(s), depend on imxrt1060-hal
, and skip the feature flag that describes your i.MX RT variant.
Q/A
imxrt-hal
crate?
Are there any board support packages (BSP) that use the There are a few BSPs that use the imxrt-hal
crate:
- The
imxrt1060evk-bsp
crate, useful for the i.MX RT 1060 Evaluation Kit (EVK). - The
teensy4-bsp
crate, supporting Rust development on the Teensy 4.
Consider using those crates if you already own those hardware platforms, as they may provide a simpler foundation for building Rust applications.
How can I use Rust to boot an i.MX RT-based system? Does the HAL provide the reset handler?
Neither the HAL nor the RAL can help you boot an i.MX RT-based system. Typically, Rust developers use the cortex-m-rt
crate as a minimal runtime for Cortex-M processors. However, i.MX RT processors require more setup than what the cortex-m-rt
crate offers. As of now, you're required to use your own runtime crate to support i.MX RT processor start-up.
We have some components that might be helpful when building your own runtime crate:
- The
imxrt-boot-gen
crate lets you define some of the data structures that are required to boot i.MX RT processors. It's used in the other projects listed below. - The
imxrt-rt
crate provides a runtime crate that may be useful for other i.MX RT processors. It's the runtime crate used in theimxrt1060evk-bsp
crate. - The
teensy4-rs
project provides its own runtime crate that utilizes the tightly-coupled memory (TCM) regions. The runtime is specific for the Teensy 4, although it may be used elsewhere.
svd2rust
to generate a crate for register access?
Why not use See here and here. svd2rust
generates a crate that's nearly 1 million lines of Rust code, and it takes a few minutes to compile. On the other hand, the RAL compiles in a few seconds. Additionally, svd2rust
only supports one SVD input, but the RAL auto-generation script accepts multiple SVD inputs, sharing the common peripherals across processor families. This means that we can more easily support all i.MX RT processor variants from a single crate.
Contributing & Development
For contributions and development guidance, see CONTRIBUTING.md
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.