Trying to understand imxrt-hal vs teensy4_bsp

[tacertain]

Hi all -

Long-time (intermittent) embedded programmer here, new to both Rust and Teensy! I've been playing around with examples in the teensy4-rs and imxrt-rs projects, getting the hang of reading Rust code and trying to assemble pieces.

My medium-term goal is to write some Teensy4 DMA-to-SPI code, which seems like it should be pretty straightforward, after all there are DMA examples in the imxrt-rs project that seem to run on the Teensy. I think in part I'm struggling with not knowing all the Rust crate inclusion and visibility rules, but also there are some differences in the imxrt-rs project versus the teensy4-rs project that seem intentional but I don't understand. I'm hoping somebody here might be able to help me at least figure out which things are intentional and which things I'm just misunderstanding.

Concretely, what I'm currently doing is trying to get the async_dma_uart.rs example from the imxrt-rs project running with the teensy4_bsp instead of the teensy4 definitions in imxrt_rs::board.

Maybe the general question I have is that there seems to be some useful stuff in imxrt_hal::board but the package isn't exported with a comment saying that it's only for testing and documentation: why is that?

More specifically, imxrt_hal::board::new() returns a bunch of useful stuff, such as the led. board/teensy4.rs defines the led so that it's either connected to the right pin or null depending on whether the SPI is included. All a program has to do is grab the led object from the Specifics and manipulate it. However, in the teensy4_bsp::board version, you just get the pins back and then when you create the led you have to pass in pin 13 every time. Now it's compile-checked to make sure you pass the right pin in, but why isn't it all done automatically as in the imxrt_hal::board case?

Slightly more generally, is there a reason why the General/Specific paradigm is only used in the testing/examples rather than being the way that the teensy_bsp::board surfaces resources as well?

The one I'm really wondering about is imxrt_hal::board::blocking. Is that intentionally not published because it's not really suitable to use? Obviously, I can just copy the code, but if it's really not suitable that would be good to know.

I think I've read all the relevant documentation (e.g. The i.MX RT HAL book and references), but please let me know if I've missed something.

Thanks!

[mciantyre]

Besides selecting the function of pin 13, imxrt_hal::board::new() also decides that your only serial UART is using pins 14 and 15.
When imxrt_hal::board makes decisions like this, they may not be in your interest.

Here are some of the ways you can configure your Teensy 4's pins. There's more possibilities shown in this table. These show that pins 14 and 15 could be used for not just serial UART, but also SPDIF audio, PWM, or a quad timer, or a GPT input capture, or a FlexIO, or just a GPIO...

Suppose teensy4_bsp returned to you that specific LPUART peripheral on pins 14 and 15, like imxrt_hal::board::new(). What if you don't want that? You've already designed a carrier PCBA for your audio project that expects the SPDIF signals on pins 14 and 15!

I don't think teensy4_bsp should make these decisions. Instead, folks can build up their software drivers for their hardware setup, using the conveniences provided by the BSP.

---

imxrt_hal::board does an OK job at supporting the 34 example programs for imxrt-hal. All of those examples build and work across two different hardware platforms. Many work on three boards.

imxrt_hal::board supports six boards. If all those boards looked like teensy4_bsp, then when it comes to example development, I think that means either

• each example would need knowledge of which pins and peripheral block are needed for the given board. That would be distracting for folks studying / extending the example.
• there would be six examples -- one per board -- that look almost identical. That's not fun to maintain.

Moving the specificity down into the board means it's easier to maintain the examples, and to port the examples to new platforms. But that specificity might not work for all projects.

---

The one I'm really wondering about is imxrt_hal::board::blocking. Is that intentionally not published because it's not really suitable to use? Obviously, I can just copy the code, but if it's really not suitable that would be good to know.

It's a simple way to constantly poll a future with the CPU, without interrupts. That might be suitable for your project! Otherwise, I'd recommend using a real async executor, like RTIC v2.

[tacertain]

This all makes perfect sense - thanks. I'm definitely going to use RTIC for my real project (the thing that inspired me to switch to rust is that I'm sick of tracking down memory-access races) - I'm just trying to take baby steps in my education journey!

Thanks for the very informative response. Hopefully I'll be able to contribute some stuff back eventually.