REBOOT_TYPE_* missing from bootrom_constants.h

[amsam0]

It seems that the REBOOT_TYPE_* constants are missing. The docs for the rom_reboot function mention them, but they do not exist. There are both the BOOT_TYPE_* constants from bootrom_constants.h and the REBOOT2_FLAG_REBOOT_TYPE_* constants from picoboot_constants.h. It is unclear which should be used (although they seem to have the same value); bootrom.c uses the REBOOT2 constants, but the BOOT_TYPE constants sound more correct and are from the correct header file.

In addition, bootrom_constants.h is missing flags such as NO_RETURN_ON_SUCCESS. This leads me to think that the REBOOT2 constants should actually be used.

[lurch]

Note that bootrom_constants.h says // todo these are duplicated in picoboot_constants.h and picoboot_constants.h says // note these match REBOOT_TYPE in pico/bootrom_constants.h, so these are the same values, rather than "seem to be" the same values 😉
This is probably just a "documentation problem" where the documentation is referring to the wrong constant-names?

Just for clarity:

bootrom_constants.h	picoboot_constants.h	bootrom.h	value
BOOT_TYPE_NORMAL	REBOOT2_FLAG_REBOOT_TYPE_NORMAL	BOOT_TYPE_NORMAL	0
BOOT_TYPE_BOOTSEL	REBOOT2_FLAG_REBOOT_TYPE_BOOTSEL	BOOT_TYPE_BOOTSEL	2
BOOT_TYPE_RAM_IMAGE	REBOOT2_FLAG_REBOOT_TYPE_RAM_IMAGE	BOOT_TYPE_RAM_IMAGE	3
BOOT_TYPE_FLASH_UPDATE	REBOOT2_FLAG_REBOOT_TYPE_FLASH_UPDATE	BOOT_TYPE_FLASH_UPDATE	4
BOOT_TYPE_PC_SP	REBOOT2_FLAG_REBOOT_TYPE_PC_SP	BOOT_TYPE_PC_SP	0xd
	REBOOT2_TYPE_MASK		0xf
	REBOOT2_FLAG_REBOOT_TO_ARM		0x10
	REBOOT2_FLAG_REBOOT_TO_RISCV		0x20
BOOT_TYPE_CHAINED_FLAG		BOOT_TYPE_CHAINED_FLAG	0x80
	REBOOT2_FLAG_NO_RETURN_ON_SUCCESS		0x100

bootrom.h already includes "pico/bootrom_constants.h", so those constants definitely seem unnecessarily duplicated. (EDIT: See #2621 )

And the doxygen for rom_rebootrefers to the (non-existent) constants: REBOOT_TYPE_NORMAL, REBOOT_TYPE_BOOTSEL, REBOOT_TYPE_RAM_IMAGE, REBOOT_TYPE_FLASH_UPDATE, REBOOT_TYPE_PC_SP, REBOOT_TO_ARM, REBOOT_TO_RISCV and NO_RETURN_ON_SUCCESS. (So as you suggest, perhaps these doxygen comments should be updated to use REBOOT2_FLAG_REBOOT_TYPE_NORMAL etc.)

And as for usages of these constants within pico-sdk itself:

• watchdog.c includes "pico/bootrom.h" and uses BOOT_TYPE_NORMAL
• bootrom.c includes "pico/bootrom.h" and "boot/picoboot.h", and uses REBOOT2_FLAG_REBOOT_TYPE_BOOTSEL, REBOOT2_FLAG_NO_RETURN_ON_SUCCESS and BOOT_TYPE_FLASH_UPDATE.
  • pico/bootrom.h includes bootrom_constants.h and hence BOOT_TYPE_FLASH_UPDATE
  • boot/picoboot.h includes picoboot_constants.h and hence REBOOT2_FLAG_REBOOT_TYPE_BOOTSEL
• bootrom.h uses BOOT_TYPE_CHAINED_FLAG