Skip to content

Commit

Permalink
Filter out nullptr peripheral instances
Browse files Browse the repository at this point in the history 
There are a few peripheral instances that have `NULL` as their base
address in the SVD. My guess is that `NULL` is a signal to humans to not
use this address. If I remember correctly , the peripherals tagged with
`NULL` require indirect access through ANATOP. Until this commit, we've
generated those peripheral instances, despite the silly address.

However, a runtime check in `NonNull` will panic when the core library
is built with debug assertions. Users may hit this panic if they build
their firmware with this configuration, then try to acquire the
individual peripheral instance or the `Instances` aggregate. The panic
in the latter case is inconvenient, especially when the user doesn't
care about these instances.

This commit removes these `NULL` instances from the public API. I'm
keeping the register blocks; pairing `core::mem::offset_of!` with
register blocks is useful.

For convenience / ease of implementation, I'm doing the filtering down
in the codegen step of `raltool`. It would be better to implement this
as a standard transform / cleanup step that kept the register block
while discarding the instances. We can try this later.

I plan to release this breaking change in the 0.5 and 0.6 series. This
will affect users who were relying on these incorrect symbols.
  • Loading branch information
@mciantyre
mciantyre committed Dec 16, 2024
1 parent fa738f2 commit 86770ee
Show file tree
Hide file tree
Showing 6 changed files with 71 additions and 196 deletions.
1 change: 1 addition & 0 deletions .github/workflows/rust.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,7 @@ jobs:
- "imxrt1021"
- "imxrt1062,rt"
- "imxrt1176_cm4"
- "imxrt1176_cm7"
- "imxrt1189_cm33"
steps:
- uses: actions/checkout@v4
Expand Down
17 changes: 17 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,19 @@
Add support for NXP's i.MX RT 1189 dual-core MCUs. An `"imxrt1189_cm33"` feature
targets the Cortex-M33, and an `"imxrt1189_cm7"` feature targets the Cortex-M7.

## [0.6.1] 2024-12-17

Remove the following peripheral instances from the 1176 API. The base address
for these instances is incorrectly `NULL`.

- OSC_RC_400M
- PHY_LDO
- TMPSNS
- VMBANDGAP

The register blocks remain part of the API. Users who rely on these instances
may still use `offset_of!` to compute addresses for indirect accesses.

## [0.6.0] 2024-12-02

**BREAKING** Remove the NVIC and SCB peripherals from the 1176. If you need an
Expand Down Expand Up @@ -51,6 +64,10 @@ reserved fields.

Fix the documentation associated with IOMUXC field values.

## [0.5.4] 2024-12-17

See the 0.6.1 changelog entry.

## [0.5.3] 2023-08-21

Exclude the interrupt vector table when we're building for a target with an
Expand Down
56 changes: 36 additions & 20 deletions raltool/src/generate/device.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,10 @@ pub fn render(_opts: &super::Options, _ir: &IR, d: &Device) -> Result<TokenStrea
for (mod_name, (block_path, periphs)) in &block_to_peripherals {
let mut consts = TokenStream::new();
for peripheral in periphs.iter() {
if peripheral.base_address == 0 {
continue;
}

let name = Ident::new(&peripheral.name, span);
let address = util::hex(peripheral.base_address as u64);
let doc = util::doc(&peripheral.description);
Expand Down Expand Up @@ -101,6 +105,9 @@ pub fn render(_opts: &super::Options, _ir: &IR, d: &Device) -> Result<TokenStrea
let mut instances = TokenStream::new();
let mut const_to_num: Vec<TokenStream> = Vec::new();
for peripheral in periphs.iter() {
if peripheral.base_address == 0 {
continue;
}
let name = Ident::new(&peripheral.name, span);
let num = num_endings.captures(&peripheral.name).unwrap();
let num = util::unsuffixed(
Expand Down Expand Up @@ -146,28 +153,33 @@ you should use transforms to rename peripherals, putting numbers at the end of t
name."#
);
let peripheral = periphs.first().unwrap();
let name = Ident::new(&peripheral.name, span);
number_fn = quote! {
/// Returns the instance number `N` for a peripheral instance.
pub fn number(rb: *const RegisterBlock) -> Option<u8> {
core::ptr::eq(rb, #name).then_some(0)
}
};
quote! {
pub type #name = Instance<{crate::SOLE_INSTANCE}>;
impl crate::private::Sealed for #name {}
impl crate::Valid for #name {}
impl #name {
/// Acquire a vaild, but possibly aliased, instance.
///
/// # Safety
///
/// See [the struct-level safety documentation](crate::Instance).
#[inline]
pub const unsafe fn instance() -> Self {
Instance::new(#name)
if peripheral.base_address != 0 {
let name = Ident::new(&peripheral.name, span);
number_fn = quote! {
/// Returns the instance number `N` for a peripheral instance.
pub fn number(rb: *const RegisterBlock) -> Option<u8> {
core::ptr::eq(rb, #name).then_some(0)
}
};
quote! {
pub type #name = Instance<{crate::SOLE_INSTANCE}>;
impl crate::private::Sealed for #name {}
impl crate::Valid for #name {}
impl #name {
/// Acquire a vaild, but possibly aliased, instance.
///
/// # Safety
///
/// See [the struct-level safety documentation](crate::Instance).
#[inline]
pub const unsafe fn instance() -> Self {
Instance::new(#name)
}
}
}
} else {
number_fn = quote!();
quote!()
}
};

Expand Down Expand Up @@ -236,6 +248,10 @@ name."#
let mut member_inits = TokenStream::new();
for (mod_name, (_, peripherals)) in &block_to_peripherals {
for peripheral in peripherals {
if peripheral.base_address == 0 {
continue;
}

let name = Ident::new(&peripheral.name, span);
let mod_name = Ident::new(mod_name, span);
member_decls.extend(quote! {
Expand Down
88 changes: 0 additions & 88 deletions src/imxrt1176_cm4.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3738,30 +3738,10 @@ pub mod ocotp {
}
#[path = "."]
pub mod osc_rc_400m {
#[doc = "no description available"]
pub const OSC_RC_400M: *const RegisterBlock = 0 as *const RegisterBlock;
#[path = "blocks/imxrt1176_cm4/osc_rc_400m.rs"]
mod blocks;
pub use blocks::*;
pub type Instance<const N: u8> = crate::Instance<RegisterBlock, N>;
pub type OSC_RC_400M = Instance<{ crate::SOLE_INSTANCE }>;
impl crate::private::Sealed for OSC_RC_400M {}
impl crate::Valid for OSC_RC_400M {}
impl OSC_RC_400M {
#[doc = r" Acquire a vaild, but possibly aliased, instance."]
#[doc = r""]
#[doc = r" # Safety"]
#[doc = r""]
#[doc = r" See [the struct-level safety documentation](crate::Instance)."]
#[inline]
pub const unsafe fn instance() -> Self {
Instance::new(OSC_RC_400M)
}
}
#[doc = r" Returns the instance number `N` for a peripheral instance."]
pub fn number(rb: *const RegisterBlock) -> Option<u8> {
core::ptr::eq(rb, OSC_RC_400M).then_some(0)
}
}
#[path = "."]
pub mod otfad {
Expand Down Expand Up @@ -4145,30 +4125,10 @@ pub mod pgmc_ppc0 {
}
#[path = "."]
pub mod phy_ldo {
#[doc = "no description available"]
pub const PHY_LDO: *const RegisterBlock = 0 as *const RegisterBlock;
#[path = "blocks/imxrt1176_cm4/phy_ldo.rs"]
mod blocks;
pub use blocks::*;
pub type Instance<const N: u8> = crate::Instance<RegisterBlock, N>;
pub type PHY_LDO = Instance<{ crate::SOLE_INSTANCE }>;
impl crate::private::Sealed for PHY_LDO {}
impl crate::Valid for PHY_LDO {}
impl PHY_LDO {
#[doc = r" Acquire a vaild, but possibly aliased, instance."]
#[doc = r""]
#[doc = r" # Safety"]
#[doc = r""]
#[doc = r" See [the struct-level safety documentation](crate::Instance)."]
#[inline]
pub const unsafe fn instance() -> Self {
Instance::new(PHY_LDO)
}
}
#[doc = r" Returns the instance number `N` for a peripheral instance."]
pub fn number(rb: *const RegisterBlock) -> Option<u8> {
core::ptr::eq(rb, PHY_LDO).then_some(0)
}
}
#[path = "."]
pub mod pit {
Expand Down Expand Up @@ -4736,30 +4696,10 @@ pub mod ssarc_lp {
}
#[path = "."]
pub mod tmpsns {
#[doc = "Temperature Sensor Memory Map"]
pub const TMPSNS: *const RegisterBlock = 0 as *const RegisterBlock;
#[path = "blocks/imxrt1176_cm4/tmpsns.rs"]
mod blocks;
pub use blocks::*;
pub type Instance<const N: u8> = crate::Instance<RegisterBlock, N>;
pub type TMPSNS = Instance<{ crate::SOLE_INSTANCE }>;
impl crate::private::Sealed for TMPSNS {}
impl crate::Valid for TMPSNS {}
impl TMPSNS {
#[doc = r" Acquire a vaild, but possibly aliased, instance."]
#[doc = r""]
#[doc = r" # Safety"]
#[doc = r""]
#[doc = r" See [the struct-level safety documentation](crate::Instance)."]
#[inline]
pub const unsafe fn instance() -> Self {
Instance::new(TMPSNS)
}
}
#[doc = r" Returns the instance number `N` for a peripheral instance."]
pub fn number(rb: *const RegisterBlock) -> Option<u8> {
core::ptr::eq(rb, TMPSNS).then_some(0)
}
}
#[path = "."]
pub mod tmr {
Expand Down Expand Up @@ -5096,30 +5036,10 @@ pub mod video_mux {
}
#[path = "."]
pub mod vmbandgap {
#[doc = "no description available"]
pub const VMBANDGAP: *const RegisterBlock = 0 as *const RegisterBlock;
#[path = "blocks/imxrt1176_cm4/vmbandgap.rs"]
mod blocks;
pub use blocks::*;
pub type Instance<const N: u8> = crate::Instance<RegisterBlock, N>;
pub type VMBANDGAP = Instance<{ crate::SOLE_INSTANCE }>;
impl crate::private::Sealed for VMBANDGAP {}
impl crate::Valid for VMBANDGAP {}
impl VMBANDGAP {
#[doc = r" Acquire a vaild, but possibly aliased, instance."]
#[doc = r""]
#[doc = r" # Safety"]
#[doc = r""]
#[doc = r" See [the struct-level safety documentation](crate::Instance)."]
#[inline]
pub const unsafe fn instance() -> Self {
Instance::new(VMBANDGAP)
}
}
#[doc = r" Returns the instance number `N` for a peripheral instance."]
pub fn number(rb: *const RegisterBlock) -> Option<u8> {
core::ptr::eq(rb, VMBANDGAP).then_some(0)
}
}
#[path = "."]
pub mod wdog {
Expand Down Expand Up @@ -5476,7 +5396,6 @@ pub struct Instances {
pub MMCAU: mmcau::MMCAU,
pub MUB: mub::MUB,
pub OCOTP: ocotp::OCOTP,
pub OSC_RC_400M: osc_rc_400m::OSC_RC_400M,
pub OTFAD1: otfad::OTFAD1,
pub OTFAD2: otfad::OTFAD2,
pub PDM: pdm::PDM,
Expand All @@ -5495,7 +5414,6 @@ pub struct Instances {
pub PGMC_CPC_MIF10: pgmc_cpc0_mif::PGMC_CPC_MIF10,
pub PGMC_CPC_MIF11: pgmc_cpc0_mif::PGMC_CPC_MIF11,
pub PGMC_PPC0: pgmc_ppc0::PGMC_PPC0,
pub PHY_LDO: phy_ldo::PHY_LDO,
pub PIT1: pit::PIT1,
pub PIT2: pit::PIT2,
pub PWM1: pwm::PWM1,
Expand All @@ -5520,7 +5438,6 @@ pub struct Instances {
pub SRC: src::SRC,
pub SSARC_HP: ssarc_hp::SSARC_HP,
pub SSARC_LP: ssarc_lp::SSARC_LP,
pub TMPSNS: tmpsns::TMPSNS,
pub TMR1: tmr::TMR1,
pub TMR2: tmr::TMR2,
pub TMR3: tmr::TMR3,
Expand All @@ -5536,7 +5453,6 @@ pub struct Instances {
pub USDHC1: usdhc::USDHC1,
pub USDHC2: usdhc::USDHC2,
pub VIDEO_MUX: video_mux::VIDEO_MUX,
pub VMBANDGAP: vmbandgap::VMBANDGAP,
pub WDOG1: wdog::WDOG1,
pub WDOG2: wdog::WDOG2,
pub XBARA1: xbara1::XBARA1,
Expand Down Expand Up @@ -5680,7 +5596,6 @@ impl Instances {
MMCAU: mmcau::MMCAU::instance(),
MUB: mub::MUB::instance(),
OCOTP: ocotp::OCOTP::instance(),
OSC_RC_400M: osc_rc_400m::OSC_RC_400M::instance(),
OTFAD1: otfad::OTFAD1::instance(),
OTFAD2: otfad::OTFAD2::instance(),
PDM: pdm::PDM::instance(),
Expand All @@ -5699,7 +5614,6 @@ impl Instances {
PGMC_CPC_MIF10: pgmc_cpc0_mif::PGMC_CPC_MIF10::instance(),
PGMC_CPC_MIF11: pgmc_cpc0_mif::PGMC_CPC_MIF11::instance(),
PGMC_PPC0: pgmc_ppc0::PGMC_PPC0::instance(),
PHY_LDO: phy_ldo::PHY_LDO::instance(),
PIT1: pit::PIT1::instance(),
PIT2: pit::PIT2::instance(),
PWM1: pwm::PWM1::instance(),
Expand All @@ -5724,7 +5638,6 @@ impl Instances {
SRC: src::SRC::instance(),
SSARC_HP: ssarc_hp::SSARC_HP::instance(),
SSARC_LP: ssarc_lp::SSARC_LP::instance(),
TMPSNS: tmpsns::TMPSNS::instance(),
TMR1: tmr::TMR1::instance(),
TMR2: tmr::TMR2::instance(),
TMR3: tmr::TMR3::instance(),
Expand All @@ -5740,7 +5653,6 @@ impl Instances {
USDHC1: usdhc::USDHC1::instance(),
USDHC2: usdhc::USDHC2::instance(),
VIDEO_MUX: video_mux::VIDEO_MUX::instance(),
VMBANDGAP: vmbandgap::VMBANDGAP::instance(),
WDOG1: wdog::WDOG1::instance(),
WDOG2: wdog::WDOG2::instance(),
XBARA1: xbara1::XBARA1::instance(),
Expand Down
Loading

0 comments on commit 86770ee

Please sign in to comment.