Teensy 4.1 Support - New Features, Migration Guide

mitchmindtree commented 4 years ago

We have a Teensy 4.1 board on the way that we'd like to start testing soon and ultimately use alongside teensy4-rs!

What are your thoughts on adding support into the bsp crate? I imagine this might involve splitting some of the crate into v40 and v41 modules (or something along these lines), e.g. Pins will likely be entirely different between both boards, only the 4.1 exposes the ethernet interface, etc.

mciantyre commented 4 years ago

Happy to support Teensy 4.1 here. I have plans to get the hardware, and I can eventually bring the BSP up to parity with the 4.0 implementation.

At the moment, I'm not sure what the BSP structure might look like. If we require feature flags, I might recommend that we co-locate shared code in a teensy4x-bsp crate, then have two teensy40-bsp and teensy41-bsp crates which depend on the shared code. We're talking about a similar approach in imxrt-rs/imxrt-rs#56.

mciantyre commented 4 years ago

My Teensy 4.1 boards arrived. It boots, and the LED blinks, even on today's master branch.

Pins 0 through 33 use the same 1062 pads on both boards. After that, the pad mappings diverge. I'm playing with 4.1 support in the proto/t41 branch. The branch introduces breaking changes that de-emphasize the BSP's role in the software stack.

Proposed Breaking Changes

BSP Pins

You create either a t40::Pins or t41::Pins aggregate by passing the HAL's IOMUXC object into a into_pins function. These Pins types rename pads, like b0.p03 (Pin 13's driving pad), to pins, like p13 (Pin 13). It keeps the pin API we're used to.

use teensy4_bsp as bsp;

let peripherals = bsp::Peripherals::take().unwrap();
// Constrain pads to the Teensy 4.1 pins
let pins = bsp::t41::into_pins(peripherals.iomuxc);
// Convert Pin 13 into the LED
let led = bsp::configure_led(pins.p13);

At this point, the bsp::Peripherals type is forwarding all of the HAL's peripherals. It no longer constrains the IOMUXC pads to any Teensy pins. So, rather than maintaining a custom Peripherals type, the BSP now forwards the HAL's Peripherals type. The imxrt_hal::Peripherals type can be taken and stolen, so it's nearly a drop-in...

SYSTICK

One behavior we lose by dropping the custom Peripherals type is SYSTICK configuration. You now use SysTick::new to initialize SysTick. You supply the SYST object provided from the cortex_m::Peripherals:

let core_peripherals = cortex_m::Peripherals::take().unwrap();
let mut systick = bsp::SysTick::new(core_peripherals.SYST);

USB

Another thing we lose without a custom Peripherals type is the USB object. You use usb::init to prepare the USB logger. Since the USB logger depends on SYSTICK, you supply the SysTick object that you initialized:

bsp::usb::init(&systick, Default::default()).unwrap();

Check out the proto/t41 branch, which updated examples to demonstrate these breaking changes. The branch depends on the iomuxc-integration changes.

Discussion

After these changes, the BSP crate is responsible for booting the system, re-naming pads to pins, letting you configure SYSTICK (for the USB stack), and exposing the USB stack. There are no BSP-specific Peripherals.

De-emphasizing the BSP's Peripherals aligns with changes I may make in the HAL. Specifically, I'd like to remove the HAL's Peripherals type. You would instead construct HAL peripherals by directly supplying RAL register blocks. The approach seems consistent with patterns I'm finding in other HALs. It may also support our i.MX RT split HALs.

Here's some other approaches:

Keep the BSP's Peripherals type. Specify the board type (T40, or T41) using type tags. The Peripherals::take / Peripherals::steal accept one of the type tags, and that describes what kinds of Pins object to return. This doesn't require any breaking changes in the BSP.
Really de-emphasize the BSP. There are no Pins types. You just use the HAL's IOMUXC type, and you convert from pads to pins. This is inconvenient for users who are familiar with pin numbers and not pad IDs.

mciantyre commented 3 years ago

Merged these ideas in #73. If anyone has suggestions for improvements, open a PR!

mciantyre commented 3 years ago

For anyone looking to migrate existing code to the new API, see the above post, specifically the "Proposed Breaking Changes."

The feature builds on 0.4.0 of the imxrt-hal, which also introduced breaking changes. See the HAL's release notes for another migration guide.

mciantyre / teensy4-rs