From 66335f1dc7767756d2cddd34135a804309f48a4d Mon Sep 17 00:00:00 2001
From: Peter Harper <77111776+peterharperuk@users.noreply.github.com>
Date: Sat, 28 Sep 2024 05:51:39 +0100
Subject: [PATCH] Clarify that RP2350 gets its unique id from OTP (#1942)

* Clarify that RP2350 gets its unique id from OTP

Fixes #1915

* Wrap rp2040_specific and rp2350_specific bits
---
 .../pico_unique_id/include/pico/unique_id.h   | 46 +++++++++++++++----
 1 file changed, 36 insertions(+), 10 deletions(-)

diff --git a/src/rp2_common/pico_unique_id/include/pico/unique_id.h b/src/rp2_common/pico_unique_id/include/pico/unique_id.h
index e8ff40d2a..367d32bff 100644
--- a/src/rp2_common/pico_unique_id/include/pico/unique_id.h
+++ b/src/rp2_common/pico_unique_id/include/pico/unique_id.h
@@ -18,6 +18,7 @@ extern "C" {
  *
  * \brief Unique device ID access API
  *
+ * \if rp2040_specific
  * RP2040 does not have an on-board unique identifier (all instances of RP2040
  * silicon are identical and have no persistent state). However, RP2040 boots
  * from serial NOR flash devices which have at least a 64-bit unique ID as a standard
@@ -31,6 +32,11 @@ extern "C" {
  *
  * This avoids some pitfalls of the hardware_flash API, which requires any
  * flash-resident interrupt routines to be disabled when called into.
+ * \endif
+ *
+ * \if rp2350_specific
+ * On boards using RP2350, the unique identifier is read from OTP memory on boot.
+ * \endif
  */
 
 #define PICO_UNIQUE_BOARD_ID_SIZE_BYTES 8
@@ -39,9 +45,18 @@ extern "C" {
  * \brief Unique board identifier
  * \ingroup pico_unique_id
  *
- * This struct is suitable for holding the unique identifier of a NOR flash
- * device on an RP2040-based board. It contains an array of
- * PICO_UNIQUE_BOARD_ID_SIZE_BYTES identifier bytes.
+ * This structure contains an array of PICO_UNIQUE_BOARD_ID_SIZE_BYTES identifier bytes suitable for
+ * holding the unique identifier for the device.
+ *
+ * \if rp2040_specific
+ * On an RP2040-based board, the unique identifier is retrieved from the external NOR flash device at boot,
+ * or for PICO_NO_FLASH builds the unique identifier is set to all 0xEE.
+ * \endif
+ *
+ * \if rp2350_specific
+ * On an RP2350-based board, the unique identifier is retrieved from OTP memory at boot.
+ * \endif
+ *
  */
 typedef struct {
 	uint8_t id[PICO_UNIQUE_BOARD_ID_SIZE_BYTES];
@@ -50,10 +65,16 @@ typedef struct {
 /*! \brief Get unique ID
  *  \ingroup pico_unique_id
  *
- * Get the unique 64-bit device identifier which was retrieved from the
- * external NOR flash device at boot.
+ * Get the unique 64-bit device identifier.
+ *
+ * \if rp2040_specific
+ * On an RP2040-based board, the unique identifier is retrieved from the external NOR flash device at boot,
+ * or for PICO_NO_FLASH builds the unique identifier is set to all 0xEE.
+ * \endif
  *
- * On PICO_NO_FLASH builds the unique identifier is set to all 0xEE.
+ * \if rp2350_specific
+ * On an RP2350-based board, the unique identifier is retrieved from OTP memory at boot.
+ * \endif
  *
  * \param id_out a pointer to a pico_unique_board_id_t struct, to which the identifier will be written
  */
@@ -62,11 +83,16 @@ void pico_get_unique_board_id(pico_unique_board_id_t *id_out);
 /*! \brief Get unique ID in string format
  *  \ingroup pico_unique_id
  *
- * Get the unique 64-bit device identifier which was retrieved from the
- * external NOR flash device at boot, formatted as an ASCII hex string.
- * Will always 0-terminate.
+ * Get the unique 64-bit device identifier formatted as a 0-terminated ASCII hex string.
+ *
+ * \if rp2040_specific
+ * On an RP2040-based board, the unique identifier is retrieved from the external NOR flash device at boot,
+ * or for PICO_NO_FLASH builds the unique identifier is set to all 0xEE.
+ * \endif
  *
- * On PICO_NO_FLASH builds the unique identifier is set to all 0xEE.
+ * \if rp2350_specific
+ * On an RP2350-based board, the unique identifier is retrieved from OTP memory at boot.
+ * \endif
  *
  * \param id_out a pointer to a char buffer of size len, to which the identifier will be written
  * \param len the size of id_out. For full serial, len >= 2 * PICO_UNIQUE_BOARD_ID_SIZE_BYTES + 1