Wrap rp2040_specific and rp2350_specific bits

peterharperuk · Sep 25, 2024 · ed843a0 · ed843a0
1 parent 6f83725
commit ed843a0
Showing 1 changed file with 35 additions and 11 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
@@ -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,8 +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
  *
- * On boards using RP2350, the unique identifier is read from OTP memory.
+ * \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
@@ -41,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 or the unique identifier read from OTP on an RP2350-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];
@@ -52,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 or OTP memory at boot.
+ * Get the unique 64-bit device identifier.
  *
- * On PICO_NO_FLASH builds the unique identifier is set to all 0xEE.
+ * \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
  *
  * \param id_out a pointer to a pico_unique_board_id_t struct, to which the identifier will be written
  */
@@ -64,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 or OTP memory 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 on RP2040-based boards, 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