Module teensy4_bsp::board

source ·
Expand description

Pre-configured board resources.

The board module conveniently exposes drivers and hardware resources. It configures peripheral clocks and power so that you can simply use the board’s peripherals.

§Getting started

Create board resources depending on your board:

  • Teensy 4.0 boards should use t40.
  • Teensy 4.1 boards should use t41.
  • Teensy MicroMod boards should use tmm.

The produced resources are nearly the same, except for the pins.

use teensy4_bsp as bsp;
use bsp::board;

let resources = board::t40(board::instances());

Resources take ownership of all peripheral instances Instances. Use instances() to acquire these once.

Note that if you’re using RTIC, you can let the RTIC framework allocate the instances. The examples included in this package demonstrate this pattern.

§Resource categories

The objects in Resources have two main categories:

  1. ready-to-go drivers, like gpt1 and dma, which are unlikely to change no matter your hardware setup.
  2. lower-level resources, like pins and lpuart3, which you can compose to create drivers specific for your hardware setup.

Given the Teensy 4’s I/O flexibility, it would be difficult to expose all features as ready-to-go drivers. Instead, board tries to help you initialize drivers for your hardware setup. For example,

  • use led to prepare the on-board LED.
  • use lpspi to prepare SPI peripherals.
  • use lpuart to prepare serial peripherals.
  • use lpi2c to prepare I2C peripherals.

For the complete list of helper functions, study the rest of this API documentation and their examples. And for the complete driver documentation, see the hal module and its submodules.

These helper functions assume that you’re following the board’s clock (and power) policy.

§Clock policy

Once t40 and t41 return, the clocks of all returned resources are running, and clock gates are enabled. Essentially, board handles CCM configurations so that you can use peripherals with reasonable settings.

board exposes constants to help you understand those clock frequencies. You should use these frequencies, along with your own settings, to describe certain types of objects, like blocking delays.

The example below shows how a user configures a GPT to meet a given GPT frequency.

use bsp::hal::{gpt, timer::Blocking};

// Given this GPT clock source...
const GPT_CLOCK_SOURCE: gpt::ClockSource = gpt::ClockSource::PeripheralClock;
// ...and this GPT-specific divider...
const GPT_DIVIDER: u32 = 8;
/// ...the GPT frequency is
const GPT_FREQUENCY: u32 = board::PERCLK_FREQUENCY / GPT_DIVIDER;

let board::Resources{ mut gpt1, .. }  = board::t40(board::instances());

gpt1.set_clock_source(GPT_CLOCK_SOURCE);
gpt1.set_divider(GPT_DIVIDER);

let mut delay = Blocking::<_, { GPT_FREQUENCY }>::from_gpt(gpt1);
delay.block_ms(500);

Clock frequency constants, and all APIs depending on those constants, assume that you do not change the clock policy. But for those who want extra control, Resources exposes the clock management peripherals. If you take this route, you’re responsible for ensuring your peripheral’s clock configurations, and you should ignore the constants exposed by this module.

§Clock details

board makes a few guarantees about the clock policy. This section describes those guarantees.

It’s considered an API-breaking change to vary the frequencies and derivations of these clocks:

board does not touch the following root clock components. You should configure these components yourself.

  • FlexIO1 and FlexIO2 dividers and multiplexers.

Other clock frequencies are exempt from this policy; they may change value or derivation without notice. Nevertheless, if these clock frequencies / derivations change, board still guarantees that the functions to set peripheral baud and clock rates will work as expected.

By the time your code has access to Resources, the clock gates for all peripherals provided by Resources is set to “on.” If you’re not using specific resources, you may configure their clock gates to “off.” board code that borrows or converts peripherals may assume that clock gates are set to “on.”

If you’re not using the BSP to prepare board Resources, consider using prepare_clocks_and_power to realize the BSP’s clock policy.

§Naming conventions

This module identifies peripherals by their hardware names. It does not use identifiers from the Teensy 4 SDK and documentation. For instance, to name the serial peripheral that uses pins 14 and 15,

  • this module uses the name “LPUART2”.
  • the Teensy 4 SDK / documentation uses the name “UART3”.

There’s a few reasons for these differences:

  • It would be unintuitive to register a LPUART2 interrupt for the peripheral named UART3. Since the BSP typically does not manage interrupt registration, this naming decision makes it easier for you to register and implement interrupts.
  • It makes clear the peripheral implementation. You know that the serial peripheral supports low-power (LP) operation, and that it’s not a FlexIO peripheral emulating a UART device.

Structs§

Enums§

Constants§

Functions§

  • instances
    Acquire peripheral instances.
  • led
    Create the board’s LED.
  • lpi2c
    Create a LPI2C peripheral.
  • lpi2c_baud
    Computes a LPI2C baud rate, assuming ideal bus behavior.
  • lpspi
    Create a LPSPI peripheral.
  • lpuart
    Create a LPUART peripheral.
  • lpuart_baud
    Computes a UART baud rate.
  • prepare_clocks_and_power
    Prepare clocks and power for the MCU.
  • t40
    Create resources for the Teensy 4.0 board.
  • t41
    Create resources for the Teensy 4.1 board.
  • tmm
    Create resources for the Teensy MicroMod board.

Type Aliases§