RP235x: datasheet link clean-ups

Also remove references to RP2040 that I missed.
rp-rs · Aug 22, 2024 · 86b4e69 · 86b4e69
1 parent 4d2d08f
commit 86b4e69
Show file tree

Hide file tree

Showing 25 changed files with 97 additions and 67 deletions.
diff --git a/rp2040-hal-examples/src/bin/alloc.rs b/rp2040-hal-examples/src/bin/alloc.rs
@@ -58,7 +58,7 @@ const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 /// as soon as all global variables are initialised.
 ///
 /// The function configures the RP2040 peripherals, then blinks the LED in an
-/// infinite loop.
+/// infinite loop where the duration indicates how many items were allocated.
 #[entry]
 fn main() -> ! {
     {

diff --git a/rp235x-hal-examples/src/bin/alloc.rs b/rp235x-hal-examples/src/bin/alloc.rs
@@ -47,8 +47,8 @@ const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 /// The `#[hal::entry]` macro ensures the Cortex-M start-up code calls this function
 /// as soon as all global variables are initialised.
 ///
-/// The function configures the RP2040 peripherals, then blinks the LED in an
-/// infinite loop.
+/// The function configures the RP2350 peripherals, then blinks the LED in an
+/// infinite loop where the duration indicates how many items were allocated.
 #[hal::entry]
 fn main() -> ! {
     {

diff --git a/rp235x-hal-examples/src/bin/pwm_blink_embedded_hal_1.rs b/rp235x-hal-examples/src/bin/pwm_blink_embedded_hal_1.rs
@@ -41,7 +41,7 @@ const XTAL_FREQ_HZ: u32 = 12_000_000u32;
 /// The `#[hal::entry]` macro ensures the Cortex-M start-up code calls this function
 /// as soon as all global variables and the spinlock are initialised.
 ///
-/// The function configures the RP2040 peripherals, then fades the LED in an
+/// The function configures the RP2350 peripherals, then fades the LED in an
 /// infinite loop.
 #[hal::entry]
 fn main() -> ! {

diff --git a/rp235x-hal/README.md b/rp235x-hal/README.md
@@ -58,6 +58,9 @@ https://github.com/rp-rs/rp-hal-boards/ for more details.
 
 [BSPs]: https://github.com/rp-rs/rp-hal-boards/
 
+Some of the source code herein refers to the "RP2350 Datasheet". This can be
+found at <https://rptl.io/rp2350-datasheet>.
+
 <!-- GETTING STARTED -->
 ## Getting Started
 

diff --git a/rp235x-hal/src/adc.rs b/rp235x-hal/src/adc.rs
@@ -1,6 +1,6 @@
 //! Analog-Digital Converter (ADC)
 //!
-//! See [Chapter 12.4](https://datasheets.raspberrypi.org/rp2350/rp2350-datasheet.pdf#section_adc) of the datasheet for more details
+//! See [Section 12.4](https://rptl.io/rp2350-datasheet#section_adc) of the datasheet for more details
 //!
 //! ## Usage
 //!
@@ -306,7 +306,7 @@ impl Channel<Adc> for TempSense {
 
 /// Analog to Digital Convertor (ADC).
 ///
-/// Represents an ADC within the RP2040. Each ADC has multiple channels, and each
+/// Represents an ADC within the RP2350. Each ADC has multiple channels, and each
 /// channel is either associated with a specific GPIO pin or attached to the internal
 /// temperature sensor. You should put the relevant pin into ADC mode by creating an
 /// [`AdcPin`] object with it, or you can put the ADC into `Temperature Sensing Mode`
@@ -478,7 +478,7 @@ where
 
 /// Used to configure & build an [`AdcFifo`]
 ///
-/// See [`Adc::build_fifo`] for details, as well as the `adc_fifo_*` [examples](https://github.com/rp-rs/rp-hal/tree/main/rp2040-hal/examples).
+/// See [`Adc::build_fifo`] for details, as well as the `adc_fifo_*` [examples](https://github.com/rp-rs/rp-hal/tree/main/rp235x-hal/examples).
 pub struct AdcFifoBuilder<'a, Word> {
     adc: &'a mut Adc,
     marker: PhantomData<Word>,
@@ -487,9 +487,9 @@ pub struct AdcFifoBuilder<'a, Word> {
 impl<'a, Word> AdcFifoBuilder<'a, Word> {
     /// Manually set clock divider to control sample rate
     ///
-    /// The ADC is tied to the USB clock, normally running at 48MHz.
-    /// ADC conversion happens at 96 cycles per sample, so with the dividers
-    /// both set to 0 (the default) the sample rate will be `48MHz / 96 = 500ksps`.
+    /// The ADC is tied to the USB clock, normally running at 48MHz. ADC
+    /// conversion happens at 96 cycles per sample, so with the dividers both
+    /// set to 0 (the default) the sample rate will be `48MHz / 96 = 500ksps`.
     ///
     /// Setting the `int` and / or `frac` dividers will hold off between
     /// samples, leading to an effective rate of:
@@ -498,8 +498,8 @@ impl<'a, Word> AdcFifoBuilder<'a, Word> {
     ///  rate = 48MHz / (1 + int + (frac / 256))
     /// ```
     ///
-    /// To determine the required `int` and `frac` values for a given target rate,
-    /// use these equations:
+    /// To determine the required `int` and `frac` values for a given target
+    /// rate, use these equations:
     ///
     /// ```text
     ///  int = floor((48MHz / rate) - 1)
@@ -516,12 +516,16 @@ impl<'a, Word> AdcFifoBuilder<'a, Word> {
     /// | 4096sps     | `11717` |  `192` |
     /// | 96ksps      |   `499` |    `0` |
     ///
-    /// Since each conversion takes 96 cycles, setting `int` to anything below 96 does
-    /// not make a difference, and leads to the same result as setting it to 0.
+    /// Since each conversion takes 96 cycles, setting `int` to anything below
+    /// 96 does not make a difference, and leads to the same result as setting
+    /// it to 0.
     ///
-    /// The lowest possible rate is 732.41Hz, attainable by setting `int = 0xFFFF, frac = 0xFF`.
+    /// The lowest possible rate is 732.41Hz, attainable by setting `int =
+    /// 0xFFFF, frac = 0xFF`.
     ///
-    /// For more details, please refer to section 4.9.2.2 in the RP2040 datasheet.
+    /// For more details, please refer to [Section
+    /// 12.4.3.2](https://rptl.io/rp2350-datasheet#section_adc) in the RP2350
+    /// datasheet.
     pub fn clock_divider(self, int: u16, frac: u8) -> Self {
         self.adc
             .device

diff --git a/rp235x-hal/src/atomic_register_access.rs b/rp235x-hal/src/atomic_register_access.rs
@@ -1,17 +1,17 @@
 //! Provide atomic access to peripheral registers
 //!
 //! This feature is not available for all peripherals.
-//! See [section 2.1.2 of the rp235x datasheet][section_2_1_2] for details.
+//! See [Section 2.1.3][section_2_1_3] of the RP2350 datasheet for details.
 //!
-//! [section_2_1_2]: https://datasheets.raspberrypi.com/rp235x/rp235x-datasheet.pdf#atomic-rwtype
+//! [section_2_1_3]: https://rptl.io/rp2350-datasheet#atomic-rwtype
 
 use core::ptr::write_volatile;
 
 /// Perform atomic bitmask set operation on register
 ///
-/// See [section 2.1.2 of the rp235x datasheet][section_2_1_2] for details.
+/// See [Section 2.1.3][section_2_1_3] of the RP2350 datasheet for details.
 ///
-/// [section_2_1_2]: https://datasheets.raspberrypi.com/rp235x/rp235x-datasheet.pdf#atomic-rwtype
+/// [section_2_1_3]: https://rptl.io/rp2350-datasheet#atomic-rwtype
 ///
 /// # Safety
 ///
@@ -25,9 +25,9 @@ pub(crate) unsafe fn write_bitmask_set(register: *mut u32, bits: u32) {
 
 /// Perform atomic bitmask clear operation on register
 ///
-/// See [section 2.1.2 of the rp235x datasheet][section_2_1_2] for details.
+/// See [Section 2.1.3][section_2_1_3] of the RP2350 datasheet for details.
 ///
-/// [section_2_1_2]: https://datasheets.raspberrypi.com/rp235x/rp235x-datasheet.pdf#atomic-rwtype
+/// [section_2_1_3]: https://rptl.io/rp2350-datasheet#atomic-rwtype
 ///
 /// # Safety
 ///

diff --git a/rp235x-hal/src/clocks/mod.rs b/rp235x-hal/src/clocks/mod.rs
@@ -70,7 +70,7 @@
 //! # }
 //! ```
 //!
-//! See [Chapter 8](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf#section_clocks) for more details.
+//! See [Chapter 8](https://rptl.io/rp2350-datasheet#section_clocks) for more details.
 
 use core::{convert::Infallible, marker::PhantomData};
 use fugit::{HertzU32, RateExtU32};

diff --git a/rp235x-hal/src/gpio/func.rs b/rp235x-hal/src/gpio/func.rs
@@ -18,7 +18,7 @@ pub trait Function: func_sealed::Function {}
 
 /// Describes the function currently assigned to a pin with a dynamic type.
 ///
-/// A 'pin' on the RP2040 can be connected to different parts of the chip
+/// A 'pin' on the RP2350 can be connected to different parts of the chip
 /// internally - for example, it could be configured as a GPIO pin and connected
 /// to the SIO block, or it could be configured as a UART pin and connected to
 /// the UART block.

diff --git a/rp235x-hal/src/i2c.rs b/rp235x-hal/src/i2c.rs
@@ -1,6 +1,6 @@
 //! Inter-Integrated Circuit (I2C) bus
 //!
-//! See [Chapter 12.2](https://datasheets.raspberrypi.org/rp2350/rp2350-datasheet.pdf#section_i2c) for more details
+//! See [Section 12.2](https://rptl.io/rp2350-datasheet#section_i2c) for more details
 //!
 //! ## Usage
 //! ```no_run

diff --git a/rp235x-hal/src/i2c/peripheral.rs b/rp235x-hal/src/i2c/peripheral.rs
@@ -1,6 +1,6 @@
 //! # I2C Peripheral (slave) implementation
 //!
-//! The RP2040 I2C block can behave as a peripheral node on an I2C bus.
+//! The RP2350 I2C block can behave as a peripheral node on an I2C bus.
 //!
 //! In order to handle peripheral transactions this driver exposes an iterator streaming I2C event
 //! that the usercode must handle to properly handle the I2C communitation. See [`Event`] for a
@@ -19,7 +19,7 @@
 //!   The I2C block holds the SCL line (clock stretching) until there is room for more data in the
 //!   Rx FIFO using [`read`](I2C::read).  
 //!   Data are automatically acknowledged by the I2C block and it is not possible to NACK incoming
-//!   data coming to the rp2040.
+//!   data coming to the RP2350.
 //!
 //! ## Warning
 //!

diff --git a/rp235x-hal/src/lib.rs b/rp235x-hal/src/lib.rs
@@ -18,8 +18,7 @@
 //! * **rt** -
 //!   Minimal startup / runtime for Cortex-M microcontrollers
 //! * **rtic-monotonic** -
-//!   Implement
-//!   `rtic_monotonic::Monotonic` based on the RP2040 timer peripheral
+//!   Implement `rtic_monotonic::Monotonic` based on the RP2350 timer peripheral
 //! * **i2c-write-iter** -
 //!   Implement `i2c_write_iter` traits for `I2C<_, _, Controller>`.
 //! * **binary-info** -

diff --git a/rp235x-hal/src/lposc.rs b/rp235x-hal/src/lposc.rs
@@ -1,7 +1,7 @@
 //! Low Power Oscillator (ROSC)
 //!
 //! See [Section
-//! 8.4](https://datasheets.raspberrypi.org/rp2350/rp2350_datasheet.pdf) for
+//! 8.4](https://datasheets.raspberrypi.org/.pdf) for
 //! more details
 //!
 //! The on-chip 32kHz Low Power Oscillator requires no external

diff --git a/rp235x-hal/src/pio.rs b/rp235x-hal/src/pio.rs
@@ -1,6 +1,7 @@
 //! Programmable IO (PIO)
 //!
-//! See [Chapter 11 of the datasheet](https://datasheets.raspberrypi.org/rp2350/rp2350-datasheet.pdf#section_pio) for more details.
+//! See [Chapter 11](https://rptl.io/rp2350-datasheet#section_pio) of the RP2350
+//! datasheet for more details.
 
 use core::ops::Deref;
 use pio::{Instruction, InstructionOperands, Program, SideSet, Wrap};
@@ -216,10 +217,18 @@ impl<P: PIOExt> PIO<P> {
 
     /// Allocates space in instruction memory and installs the program.
     ///
-    /// The function returns a handle to the installed program that can be used to configure a
-    /// `StateMachine` via `PIOBuilder`. The program can be uninstalled to free instruction memory
-    /// via `uninstall()` once the state machine using the program has been uninitialized.
-    // Safety: PIOExt is marked send and should be the only object allowed to access pio.instr_mem
+    /// The function returns a handle to the installed program that can be used
+    /// to configure a `StateMachine` via `PIOBuilder`. The program can be
+    /// uninstalled to free instruction memory via `uninstall()` once the state
+    /// machine using the program has been uninitialized.
+    ///
+    /// Note: We use the RP2040 program size constant, but the RP2350 has the
+    /// same size instruction memory.
+    ///
+    /// # Safety
+    ///
+    /// `PIOExt` is marked send and should be the only object allowed to access
+    /// `pio.instr_mem`
     pub fn install(
         &mut self,
         p: &Program<{ pio::RP2040_MAX_PROGRAM_SIZE }>,
@@ -1520,7 +1529,7 @@ impl<SM: ValidStateMachine, TxSize: TransferSize> Tx<SM, TxSize> {
     /// Memory mapped register writes that are smaller than 32bits will trigger
     /// "Narrow IO Register Write" behaviour in rp235x - the value written will
     /// be replicated to the rest of the register as described in
-    /// [rp235x Datasheet: 2.1.4. - Narrow IO Register Writes][section_2_1_4]
+    /// [RP2350 Datasheet: 2.1.5. - Narrow IO Register Writes][section_2_1_5]
     ///
     ///
     /// This 8bit write will set all 4 bytes of the FIFO to `value`
@@ -1532,7 +1541,7 @@ impl<SM: ValidStateMachine, TxSize: TransferSize> Tx<SM, TxSize> {
     ///
     /// Returns `true` if the value was written to FIFO, `false` otherwise.
     ///
-    /// [section_2_1_4]: <https://datasheets.raspberrypi.com/rp235x/rp235x-datasheet.pdf#_narrow_io_register_writes>
+    /// [section_2_1_5]: <https://rptl.io/rp2350-datasheet#_narrow_io_register_writes>
     pub fn write_u8_replicated(&mut self, value: u8) -> bool {
         self.write_generic(value)
     }
@@ -1542,7 +1551,7 @@ impl<SM: ValidStateMachine, TxSize: TransferSize> Tx<SM, TxSize> {
     /// Memory mapped register writes that are smaller than 32bits will trigger
     /// "Narrow IO Register Write" behaviour in rp235x - the value written will
     /// be replicated to the rest of the register as described in
-    /// [rp235x Datasheet: 2.1.4. - Narrow IO Register Writes][section_2_1_4]
+    /// [RP2350 Datasheet: 2.1.5. - Narrow IO Register Writes][section_2_1_5]
     ///
     /// This 16bit write will set both the upper and lower half of the FIFO entry to `value`.
     ///
@@ -1554,7 +1563,7 @@ impl<SM: ValidStateMachine, TxSize: TransferSize> Tx<SM, TxSize> {
     ///
     /// Returns `true` if the value was written to FIFO, `false` otherwise.
     ///
-    /// [section_2_1_4]: <https://datasheets.raspberrypi.com/rp235x/rp235x-datasheet.pdf#_narrow_io_register_writes>
+    /// [section_2_1_5]: <https://rptl.io/rp2350-datasheet#_narrow_io_register_writes>
     pub fn write_u16_replicated(&mut self, value: u16) -> bool {
         self.write_generic(value)
     }

diff --git a/rp235x-hal/src/pll.rs b/rp235x-hal/src/pll.rs
@@ -1,6 +1,6 @@
 //! Phase-Locked Loops (PLL)
 //!
-//! See [Chapter 8.6](https://datasheets.raspberrypi.org/rp2350/rp2350-datasheet.pdf#section_pll) for more details
+//! See [Section 8.6](https://rptl.io/rp2350-datasheet#section_pll) for more details
 
 use core::{
     convert::{Infallible, TryInto},
@@ -77,7 +77,9 @@ impl<S: State, D: PhaseLockedLoopDevice> PhaseLockedLoop<S, D> {
 }
 
 /// Error type for the PLL module.
-/// See Chapter 2, Section 18 §2 for details on constraints triggering these errors.
+///
+/// See [Section 8.6](https://rptl.io/rp2350-datasheet) for
+/// details on constraints triggering these errors.
 #[derive(Debug)]
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
 pub enum Error {
@@ -113,7 +115,8 @@ pub struct PLLConfig {
 }
 
 /// Common configs for the two PLLs. Both assume the XOSC is cadenced at 12MHz !
-/// See Datasheet Section 8.6.2
+///
+/// See [Section 8.6.2](https://rptl.io/rp2350-datasheet) of the RP2350 datasheet.
 pub mod common_configs {
     use super::PLLConfig;
     use fugit::HertzU32;

diff --git a/rp235x-hal/src/powman.rs b/rp235x-hal/src/powman.rs
@@ -9,7 +9,8 @@
 //! * [ ] Using as GPIO as a time reference or wake-up signal
 //! * [ ] The power-on statemachine, including last-power-on reason
 //!
-//! See Section 6.5 in the datasheet for more details
+//! See [Section 6.5](https://rptl.io/rp2350-datasheet) of the RP2350 datasheet
+//! for more details
 
 use crate::{
     gpio::{

diff --git a/rp235x-hal/src/resets.rs b/rp235x-hal/src/resets.rs
@@ -1,6 +1,6 @@
 //! Subsystem Resets
 //!
-//! See [Chapter 7](https://datasheets.raspberrypi.org/rp2350/rp2350-datasheet.pdf#section_resets) for more details.
+//! See [Chapter 7](https://rptl.io/rp2350-datasheet#section_resets) for more details.
 
 mod private {
     pub trait SubsystemReset {

diff --git a/rp235x-hal/src/rom_data.rs b/rp235x-hal/src/rom_data.rs
@@ -1,12 +1,12 @@
 //! Functions and data from the RPI Bootrom.
 //!
-//! From the [rp235x datasheet](https://datasheets.raspberrypi.org/rp235x/rp235x-datasheet.pdf), Section 2.8.3.1:
+//! From [Section 5.4](https://rptl.io/rp2350-datasheet#section_bootrom) of the
+//! RP2350 datasheet:
 //!
-//! > The Bootrom contains a number of public functions that provide useful
-//! > rp235x functionality that might be needed in the absence of any other code
-//! > on the device, as well as highly optimized versions of certain key
-//! > functionality that would otherwise have to take up space in most user
-//! > binaries.
+//! > Whilst some ROM space is dedicated to the implementation of the boot
+//! > sequence and USB/UART boot interfaces, the bootrom also contains public
+//! > functions that provide useful RP2350 functionality that may be useful for
+//! > any code or runtime running on the device
 
 /// A bootrom function table code.
 pub type RomFnTableCode = [u8; 2];
@@ -397,7 +397,8 @@ declare_rom_function! {
     /// identity map, i.e. the mapped and unmapped address are equal, and the
     /// entire space is fully mapped.
     ///
-    /// See Section 12.14.4.
+    /// See [Section 12.14.4](https://rptl.io/rp2350-datasheet#section_bootrom) of the RP2350
+    /// datasheet.
     ///
     /// Supported architectures: ARM-S, RISC-V
     unsafe fn flash_reset_address_trans() -> () {
@@ -411,7 +412,8 @@ declare_rom_function! {
     /// Applies the address translation currently configured by QMI address
     /// translation registers, ATRANS0 through ATRANS7.
     ///
-    /// See Section 12.14.4.
+    /// See [Section 12.14.4](https://rptl.io/rp2350-datasheet#section_bootrom) of the RP2350
+    /// datasheet.
     ///
     /// Translating an address outside of the XIP runtime address window, or
     /// beyond the bounds of an ATRANSx_SIZE field, returns

diff --git a/rp235x-hal/src/rosc.rs b/rp235x-hal/src/rosc.rs
@@ -1,6 +1,6 @@
 //! Ring Oscillator (ROSC)
 //!
-//! See [Chapter 8.3](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf#section_rosc) for more details.
+//! See [Section 8.3](https://rptl.io/rp2350-datasheet#section_rosc) for more details.
 //!
 //! In addition to its obvious role as a clock source, [`RingOscillator`] can also be used as a random number source
 //! for the [`rand`] crate:
@@ -113,7 +113,9 @@ impl RingOscillator<Enabled> {
     /// PLLs must be stopped and IRQs have to be properly configured.
     /// This method does not do any of that, it merely switches the ROSC to DORMANT state.
     /// It should only be called if this oscillator is the clock source for the system clock.
-    /// See Chapter 2, Section 16, §5) for details.
+    ///
+    /// See [Section 6.5.3](https://rptl.io/rp2350-datasheet#section_bootrom) of the RP2350
+    /// datasheet.
     pub unsafe fn dormant(&self) {
         //taken from the C SDK
         const ROSC_DORMANT_VALUE: u32 = 0x636f6d61;

diff --git a/rp235x-hal/src/spi.rs b/rp235x-hal/src/spi.rs
@@ -3,7 +3,7 @@
 //! [`Spi`] is the main struct exported by this module, representing a configured Spi bus. See its
 //! docs for more information on its type parameters.
 //!
-//! See [Chapter 12.3](https://datasheets.raspberrypi.com/rp2350/rp2350-datasheet.pdf#section_spi) for more details.
+//! See [Section 12.3](https://rptl.io/rp2350-datasheet#section_spi) for more details.
 //!
 //! ## Usage
 //!

diff --git a/rp235x-hal/src/timer.rs b/rp235x-hal/src/timer.rs
@@ -6,7 +6,7 @@
 //!
 //! Each of the 4 alarms can match on the lower 32 bits of Counter and trigger an interrupt.
 //!
-//! See [Chapter 4 Section 6](https://datasheets.raspberrypi.org/rp235x/rp235x_datasheet.pdf) of the datasheet for more details.
+//! See [Section 12.8](https://datasheets.raspberrypi.org/.pdf) of the datasheet for more details.
 
 use core::sync::atomic::{AtomicU8, Ordering};
 use fugit::{MicrosDurationU32, MicrosDurationU64, TimerInstantU64};