Remove duplicated defines from bootrom.h (#2621)

* Remove duplicated defines from bootrom.h

See #2619 for rationale

* more rationalization of constant names

* comment fix

* Apply suggestions from code review

Co-authored-by: Andrew Scheller <andrew.scheller@raspberrypi.com>

---------

Co-authored-by: graham sanderson <graham.sanderson@raspberrypi.com>

Author: lurch

src/common/boot_picoboot_headers/include/boot/picoboot_constants.h

@@ -9,18 +9,18 @@
 
 #define REBOOT2_TYPE_MASK  0x0f
 
-// note these match REBOOT_TYPE in pico/bootrom_constants.h
+// --- note these match BOOT_TYPE_ constants in pico/bootrom_constants.h
 // values 0-7 are secure/non-secure
 #define REBOOT2_FLAG_REBOOT_TYPE_NORMAL       0x0 // param0 = diagnostic partition
 #define REBOOT2_FLAG_REBOOT_TYPE_BOOTSEL      0x2 // param0 = gpio_pin_number, param1 = flags
 #define REBOOT2_FLAG_REBOOT_TYPE_RAM_IMAGE    0x3 // param0 = image_region_base, param1 = image_region_size
 #define REBOOT2_FLAG_REBOOT_TYPE_FLASH_UPDATE 0x4 // param0 = update_base
-
 // values 8-15 are secure only
 #define REBOOT2_FLAG_REBOOT_TYPE_PC_SP        0xd
 
 #define REBOOT2_FLAG_REBOOT_TO_ARM            0x10
 #define REBOOT2_FLAG_REBOOT_TO_RISCV          0x20
+// ---
 
 #define REBOOT2_FLAG_NO_RETURN_ON_SUCCESS    0x100
 

src/rp2_common/boot_bootrom_headers/include/boot/bootrom_constants.h

@@ -70,18 +70,19 @@
 // note this is deliberately > MAX_PARTITIONs is likely to be, and also -1 as a signed byte
 #define PARTITION_TABLE_NO_PARTITION_INDEX 0xff
 
-// todo these are duplicated in picoboot_constants.h
+// values returned from \ref rom_get_last_boot_type()
+// --- note these match the REBOOT2_FLAG_REBOOT_TYPE_ constants in pico/bootrom_constants.h
 // values 0-7 are secure/non-secure
 #define BOOT_TYPE_NORMAL     0
 #define BOOT_TYPE_BOOTSEL    2
 #define BOOT_TYPE_RAM_IMAGE  3
 #define BOOT_TYPE_FLASH_UPDATE 4
-
 // values 8-15 are secure only
 #define BOOT_TYPE_PC_SP      0xd
 
 // ORed in if a bootloader chained into the image
 #define BOOT_TYPE_CHAINED_FLAG 0x80
+// ---
 
 // call from NS to S
 #ifndef __riscv

src/rp2_common/pico_bootrom/include/pico/bootrom.h

@@ -464,35 +464,35 @@ static inline int rom_set_bootrom_stack(bootrom_stack_t *stack) {
  * 
  * The flags field contains one of the following values:
  * 
- * REBOOT_TYPE_NORMAL - reboot into the normal boot path.
+ * \ref REBOOT2_FLAG_REBOOT_TYPE_NORMAL - reboot into the normal boot path.
  * 
- * REBOOT_TYPE_BOOTSEL - reboot into BOOTSEL mode.
+ * \ref REBOOT2_FLAG_REBOOT_TYPE_BOOTSEL - reboot into BOOTSEL mode.
  *  p0 - the GPIO number to use as an activity indicator (enabled by flag in p1).
  *  p1 - a set of flags:
  *   0x01 : DISABLE_MSD_INTERFACE - Disable the BOOTSEL USB drive (see <<section_bootrom_mass_storage>>)
  *   0x02 : DISABLE_PICOBOOT_INTERFACE - Disable the {picoboot} interface (see <<section_bootrom_picoboot>>).
  *   0x10 : GPIO_PIN_ACTIVE_LOW - The GPIO in p0 is active low.
  *   0x20 : GPIO_PIN_ENABLED - Enable the activity indicator on the specified GPIO.
  * 
- * REBOOT_TYPE_RAM_IMAGE - reboot into an image in RAM. The region of RAM or XIP RAM is searched for an image to run. This is the type
+ * \ref REBOOT2_FLAG_REBOOT_TYPE_RAM_IMAGE - reboot into an image in RAM. The region of RAM or XIP RAM is searched for an image to run. This is the type
  * of reboot used when a RAM UF2 is dragged onto the BOOTSEL USB drive.
  *  p0 - the region start address (word-aligned).
  *  p1 - the region size (word-aligned).
  * 
- * REBOOT_TYPE_FLASH_UPDATE - variant of REBOOT_TYPE_NORMAL to use when flash has been updated. This is the type
+ * \ref REBOOT2_FLAG_REBOOT_TYPE_FLASH_UPDATE - variant of \ref REBOOT2_FLAG_REBOOT_TYPE_NORMAL to use when flash has been updated. This is the type
  * of reboot used after dragging a flash UF2 onto the BOOTSEL USB drive.
  *  p0 - the address of the start of the region of flash that was updated. If this address matches the start address of a partition or slot, then that
  *       partition or slot is treated preferentially during boot (when there is a choice). This type of boot facilitates TBYB and version downgrades.
  * 
- * REBOOT_TYPE_PC_SP - reboot to a specific PC and SP. Note: this is not allowed in the ARM-NS variant.
+ * \ref REBOOT2_FLAG_REBOOT_TYPE_PC_SP - reboot to a specific PC and SP. Note: this is not allowed in the ARM-NS variant.
  *  p0 - the initial program counter (PC) to start executing at. This must have the lowest bit set for Arm and clear for RISC-V
  *  p1 - the initial stack pointer (SP).
  * 
  * All of the above, can have optional flags ORed in:
  * 
- * REBOOT_TO_ARM - switch both cores to the Arm architecture (rather than leaving them as is). The call will fail with BOOTROM_ERROR_INVALID_STATE if the Arm architecture is not supported.
- * REBOOT_TO_RISCV - switch both cores to the RISC-V architecture (rather than leaving them as is). The call will fail with BOOTROM_ERROR_INVALID_STATE if the RISC-V architecture is not supported.
- * NO_RETURN_ON_SUCCESS - the watchdog h/w is asynchronous. Setting this bit forces this method not to return if the reboot is successfully initiated.
+ * \ref REBOOT2_FLAG_REBOOT_TO_ARM - switch both cores to the Arm architecture (rather than leaving them as is). The call will fail with BOOTROM_ERROR_INVALID_STATE if the Arm architecture is not supported.
+ * \ref REBOOT2_FLAG_REBOOT_TO_RISCV - switch both cores to the RISC-V architecture (rather than leaving them as is). The call will fail with BOOTROM_ERROR_INVALID_STATE if the RISC-V architecture is not supported.
+ * \ref REBOOT2_FLAG_NO_RETURN_ON_SUCCESS - the watchdog h/w is asynchronous. Setting this bit forces this method not to return if the reboot is successfully initiated.
  * 
  * \param flags the reboot flags, as detailed above
  * \param delay_ms millisecond delay before the reboot occurs
@@ -1010,17 +1010,6 @@ static inline intptr_t rom_set_rom_callback(uint callback_num, bootrom_api_callb
     return func(callback_num, funcptr);
 }
 
-#define BOOT_TYPE_NORMAL     0
-#define BOOT_TYPE_BOOTSEL    2
-#define BOOT_TYPE_RAM_IMAGE  3
-#define BOOT_TYPE_FLASH_UPDATE 4
-
-// values 8-15 are secure only
-#define BOOT_TYPE_PC_SP      0xd
-
-// ORed in if a bootloader chained into the image
-#define BOOT_TYPE_CHAINED_FLAG 0x80
-
 /*!
  * \brief Get system information
  * \ingroup pico_bootrom