teensy4_bsp/
lib.rs

1//! A Rust board support package (BSP) for the Teensy 4.
2//!
3//! `teensy4-bsp` supports the following boards:
4//!
5//! - Teensy 4.0
6//! - Teensy 4.1
7//! - Teensy MicroMod
8//!
9//! If you're just getting started with embedded Rust development on the Teensy 4, take
10//! a look at [the `board` module](crate::board). This module provides pre-configured drivers
11//! and helper functions to define hardware drivers.
12//!
13//! Peripherals are re-exported from the [`imxrt-hal`](crate::hal)
14//! hardware abstraction layer. For more information on drivers, consult the `imxrt-hal` documentation.
15//! Note that `imxrt-hal` drivers depend on low-level resources from `imxrt-ral`. For convenience,
16//! the BSP also exposes [`imxrt-ral`](crate::ral). Combine `imxrt-hal` and `imxrt-ral` to have full
17//! control of your hardware.
18//!
19//! Finally, the BSP provides a runtime to simplify application development. It exposes board pins through
20//! the [`pins`] module.
21//!
22//! # Features
23//!
24//! `teensy4-bsp` supports these features.
25//!
26//! | Flag            |         Description                          |
27//! | --------------- | -------------------------------------------- |
28//! | `"rt"`          | Adds runtime support using `imxrt-rt`.       |
29//!
30//! # Runtime
31//!
32//! When the runtime is enabled, `teensy4-bsp` defines the memory map. In order to use the memory map,
33//! you must **link your program with `t4link.x`**.
34//!
35//! The memory organization includes
36//!
37//! - 320 KiB of DTCM, comprised of
38//!   - a 16 KiB stack.
39//!   - the vector table.
40//!   - all zero- and runtime-initialized data (`.bss`, `.data`).
41//! - 192 KiB of ITCM, containing _all_ instructions (`.text`).
42//! - 512 KiB of OCRAM, comprised of
43//!   - any uninitialized data (`.uninit`)
44//!   - a 16 KiB heap.
45//!
46//! If the runtime is disabled, then `teensy4-bsp` does no define the memory map, and it does not
47//! depend on `imxrt-rt`. Consider disabling the BSP's runtime feature if you want to implement your
48//! own runtime, or if you want to use `imxrt-rt` to define your own memory map.
49//!
50//! ## Environment variable overrides
51//!
52//! You can override the size of some memory regions by setting environment variables.
53//!
54//! - To change the *stack* size, set `TEENSY4_STACK_SIZE` when building.
55//! - To change the *heap* size, set `TEENSY4_HEAP_SIZE` when building.
56//!
57//! The examples below show how to set a 4096 byte stack using its environment variable.
58//!
59//! ```text
60//! TEENSY4_STACK_SIZE=4096
61//! TEENSY4_STACK_SIZE=4k     # Convenience for multiples of 1024 bytes.
62//! TEENSY4_STACK_SIZE=4K     # Equivalent to the above.
63//! ```
64//!
65//! # Notes
66//!
67//! ## SRTC reset by loader
68//!
69//! When the SRTC is enabled, setting the board into program mode then using the Teensy Loader
70//! application (GUI) to reboot it will set the current time (Unix epoch, but time in local
71//! timezone). This will overwrite whatever time you may have previously set and is ambiguous
72//! around the backwards daylight savings transition point.
73
74#![no_std]
75#![cfg_attr(docsrs, feature(doc_cfg))]
76
77pub use imxrt_hal as hal;
78pub use imxrt_ral as ral;
79#[cfg(all(feature = "rt", target_arch = "arm", target_os = "none"))]
80#[cfg_attr(docsrs, doc(cfg(feature = "rt")))]
81pub use imxrt_rt as rt;
82
83pub use teensy4_pins as pins;
84
85// Need to reference this so that it doesn't get stripped out
86use teensy4_fcb as _;
87
88/// Exported for RTIC. Do not use.
89#[doc(hidden)]
90pub struct Peripherals(ral::Instances);
91
92#[doc(hidden)]
93impl Peripherals {
94    #[inline]
95    pub unsafe fn steal() -> Self {
96        Self(board::instances())
97    }
98}
99
100#[doc(hidden)]
101impl From<Peripherals> for ral::Instances {
102    #[inline]
103    fn from(periphs: Peripherals) -> Self {
104        periphs.0
105    }
106}
107
108/// Exported for RTIC. Do not use.
109#[doc(hidden)]
110pub use ral::{interrupt, Interrupt, NVIC_PRIO_BITS};
111
112pub mod board;
113mod clock_power;
114
115/// SYSTICK external clock frequency.
116///
117/// This represents the frequency (Hz) of the external clock
118/// that can supply SYSTICK.
119// See Section 12.3.2.1 of the reference manual. The note
120// explains that the 24MHz clock is divided down to 100KHz
121// before reaching SYSTICK.
122pub const EXT_SYSTICK_HZ: u32 = 100_000;
teensy4_bsp/lib.rs

teensy4_bsp/
lib.rs
