|new 0.2.4||Nov 17, 2023|
|0.2.2||Jul 3, 2023|
|0.2.1||Feb 23, 2023|
|0.2.0||Nov 30, 2022|
|0.1.2||Nov 23, 2020|
#30 in Embedded development
1,876 downloads per month
Used in 10 crates (2 directly)
i.MX RT pad definitions and pin configuration. Use this library to
- configure a pad for a peripheral, and specify its electrical properties.
- manage pad objects as ownable resources.
- statically constrain pads to work with peripherals.
imxrt-iomuxc targets the latest stable Rust compiler.
If you're already using
you're hardware abstraction layer, there's nothing more to do.
re-exports this API and ensures compatibility with your i.MX RT processor. See
imxrt-hal documentation for more information on acquiring pads and
If you're defining a new i.MX RT hardware driver, consider using
to constrain the pads that are compatible with your driver. Depend on the latest
imxrt-iomuxc package, and do not enable any package features. Then, implement
your APIs with the various
imxrt-iomuxc pin traits. See the
documentation for examples. For even more examples, study the
If you're defining a board support package, consider using
rename the pads that are supported by your board. Depend on the latest
imxrt-iomuxc package, and enable the feature for your i.MX RT processor. Then,
expose type aliases and / or objects that rename i.MX RT processor pads
according to your board. If you're looking for an example of this pattern,
The table below shows the chips and their corresponding crate feature. Note that chips are denoted by reference manuals and may support different variants. For instance, the 1060 feature supports 1061 and 1062 chip variants.
Read on if you're interested in adding support for another i.MX RT microcontroller, or if you want to expand existing support.
We appreciate your contributions. After discussing the development basics, this section describes how you can
- add support for new i.MX RT chips.
- implement pin traits on pads.
- define new pin traits for peripherals.
Generally, open an issue if you're interested in any type of contribution, or if you find a defect.
Build the package with
cargo. The first command only builds the pin traits and
configuration API; it does not include any chip support. The second command
includes 1060 pad definitions and pin implementations. The third command
includes all supported pad definitions and pin implementations for an ARM
cargo build cargo build --features=imxrt1060 cargo build --all-features --target=thumbv7em-none-eabihf
All code must build for your host and for an embedded target. Notice how a
thumbv7em-none-eabihf is optional.
Run tests with
cargo test --all-features
In particular, documementation tests may that the crate is built with the 1060 feature. Please follow this precedent when adding documentation examples.
Generate documentation with
cargo doc. You can optionally enable (all) chip
cargo doc cargo doc --features=imxrt1060 cargo doc --all-features
If you're interested in generating the docs.rs documentation, use a nightly
toolchain, and supply the
docsrs configuration. This will include the
documentation tags that highlight build configurations.
cargo +nightly rustdoc --all-features -- --cfg=docsrs
Adding support for new chips
iomuxc.py script to generate all pads for a new i.MX RT
chip. The script extracts pad definitions from a system view description (SVD)
file. Consider using the SVDs maintained in the
Once you have an SVD and can generate the pads module, integrate the pads module into the package. Use the existing 1010, 1060, and 1170 support as your guide. As of now, the process roughly follows
- Conditionally include the module in
- Create a new directory for your chip, and add a
mod.rsfile. Include and re-export your script-generated pads module.
- Add a
Cargo.tomlfeature for your chip.
By the end of this process, you have definitions for your i.MX RT chip's pads. You should also have GPIO pin implementations. However, you do not have pin implementations for other peripherals. Read on to learn about that contribution process.
Extending pin implementations for existing pads
This section assumes that a pin trait exists for your peripheral. If this doesn't exist, read the next section for guidance.
When you implement a pin trait for a processor pad, you signal to users that this pad supports a particular peripheral function. As of this writing, we write these implementations by hand using the reference manual (RM) or SVD as a source of truth. The general imxrt-rs project documentation has tips for obtaining a RM. Once you have an RM, the table in the "External Signals and Pin Multiplexing" chapter should reveal the pads that support peripheral functions.
To extend pin implementations, either append to the existing pin module for your
chip, or create a new pin module for your chip. If your pin implementation
requires daisy registers, consider using the
daisy.py script to
extract them from a SVD file. (If you don't have SVD files, see the previous
section.) Again, use the existing 1010, 1060, and 1170 support as your guide.
We welcome any contribution to automate this process. See the tracking issue for more information.
Define new pin traits
When you define a new pin trait, you specify all of the information needed for a pad to be configured for a particular peripheral function. For example, an LPUART pin trait needs to be concerned with specifing
- the peripheral instance (LPUART1 or LPUART2?).
- the function (transmit, receive?).
- the alternate value for muxing.
- any required electrical settings (no pulls, slow slew, etc.).
The trait describes these parameters, and functions designed to those traits prepare the pads for the chosen configuration.
The trait complexity may vary depending on the peripheral. If you're not sure what a trait might look like, start by studying the pad multiplexing options, then translate that into a trait. Consult the existing pin traits for different design techniques.
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.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.