Repository: raspberrypi/pico-sdk
File: src/rp2_common/pico_bootrom/include/pico/bootrom.h (C/C++)

Code before:
 * This function reboots the device into the BOOTSEL mode ('usb boot").
 *
 * Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device,
 * and to limit the USB interfaces exposed.
 *
 * \param usb_activity_gpio_pin_mask 0 No pins are used as per a cold boot. Otherwise a single bit set indicating which
 *                               GPIO pin should be set to output and raised whenever there is mass storage activity
 *                               from the host.
 * \param disable_interface_mask value to control exposed interfaces
 *  - 0 To enable both interfaces (as per a cold boot)
 *  - 1 To disable the USB Mass Storage Interface
 *  - 2 To disable the USB PICOBOOT Interface
 */
void __attribute__((noreturn)) rom_reset_usb_boot(uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask);
static inline void __attribute__((noreturn)) reset_usb_boot(uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask) {
    rom_reset_usb_boot(usb_activity_gpio_pin_mask, disable_interface_mask);
}

/*!
 * \brief Connect the SSI/QMI to the QSPI pads
 * \ingroup pico_bootrom
 * 
 * Restore all QSPI pad controls to their default state, and connect the SSI/QMI peripheral to the QSPI pads.
 * 
 * \if rp2350_specific
 * On RP2350 if a secondary flash chip select GPIO has been configured via OTP OTP_DATA_FLASH_DEVINFO, or by writing to the runtime
 * copy of FLASH_DEVINFO in bootram, then this bank 0 GPIO is also initialised and the QMI peripheral is connected. Otherwise,
 * bank 0 IOs are untouched.
 * \endif
 */
static inline void rom_connect_internal_flash(void) {
    rom_connect_internal_flash_fn func = (rom_connect_internal_flash_fn) rom_func_lookup_inline(ROM_FUNC_CONNECT_INTERNAL_FLASH);
    func();
}

/*!
 * \brief Return the QSPI device from its XIP state to a serial command state
 * \ingroup pico_bootrom
 * 
 * \if rp2040_specific
 * On RP2040, first set up the SSI for serial-mode operations, then issue the fixed XIP exit sequence described in Section 2.8.1.2
 * of the datasheet. Note that the bootrom code uses the IO forcing logic to drive the CS pin, which must be cleared before returning
 * the SSI to XIP mode (e.g. by a call to _flash_flush_cache). This function configures the SSI with a fixed SCK clock divisor of /6.
 * \endif
 * 
 * \if rp2350_specific
 * On RP2350, Initialise the QMI for serial operations (direct mode), and also initialise a basic XIP mode, where the QMI will perform
 * 03h serial read commands at low speed (CLKDIV=12) in response to XIP reads.
 * 
 * Then, issue a sequence to the QSPI device on chip select 0, designed to return it from continuous read mode ("XIP mode") and/or
 * QPI mode to a state where it will accept serial commands. This is necessary after system reset to restore the QSPI device to a known

Review comment (suggestion):
This chunk of doxygen is **identical** to that for `rom_reset_usb_boot`, which will probably look pretty confusing in the rendered Doxygen output? (both https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf and https://www.raspberrypi.com/documentation/pico-sdk/ )

Is the addition of active_low the only difference between `rom_reset_usb_boot` and `rom_reset_usb_boot_extra` ?
EDIT: Ah, according to the PR's title `rom_reset_usb_boot_extra` also supports more than 32 pins :joy: 

Code after:
 * This function reboots the device into the BOOTSEL mode ('usb boot").
 *
 * Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device,
 * and to limit the USB interfaces exposed.
 *
 * \param usb_activity_gpio_pin_mask 0 No pins are used as per a cold boot. Otherwise a single bit set indicating which
 *                               GPIO pin should be set to output and raised whenever there is mass storage activity
 *                               from the host.
 * \param disable_interface_mask value to control exposed interfaces
 *  - 0 To enable both interfaces (as per a cold boot)
 *  - 1 To disable the USB Mass Storage Interface
 *  - 2 To disable the USB PICOBOOT Interface
 */
void __attribute__((noreturn)) rom_reset_usb_boot(uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask);
static inline void __attribute__((noreturn)) reset_usb_boot(uint32_t usb_activity_gpio_pin_mask, uint32_t disable_interface_mask) {
    rom_reset_usb_boot(usb_activity_gpio_pin_mask, disable_interface_mask);
}

/*!
 * \brief Reboot the device into BOOTSEL mode
 * \ingroup pico_bootrom
 *
 * This function reboots the device into the BOOTSEL mode ('usb boot").
 *
 * Facilities are provided to enable an "activity light" via GPIO attached LED for the USB Mass Storage Device,
 * and to limit the USB interfaces exposed.
 *
 * \param usb_activity_gpio_pin  GPIO pin to be used as an activitiy pin, or -1 for none
 *                               from the host.
 * \param disable_interface_mask value to control exposed interfaces
 *  - 0 To enable both interfaces (as per a cold boot)
 *  - 1 To disable the USB Mass Storage Interface
 *  - 2 To disable the USB PICOBOOT Interface
 * \param usb_activity_gpio_pin_active_low Activity GPIO is active low (ignored on RP2040)
 */
void __attribute__((noreturn)) rom_reset_usb_boot_extra(int usb_activity_gpio_pin, uint32_t disable_interface_mask, bool usb_activity_gpio_pin_active_low);

/*!
 * \brief Connect the SSI/QMI to the QSPI pads
 * \ingroup pico_bootrom
 * 
 * Restore all QSPI pad controls to their default state, and connect the SSI/QMI peripheral to the QSPI pads.
 * 
 * \if rp2350_specific
 * On RP2350 if a secondary flash chip select GPIO has been configured via OTP OTP_DATA_FLASH_DEVINFO, or by writing to the runtime
 * copy of FLASH_DEVINFO in bootram, then this bank 0 GPIO is also initialised and the QMI peripheral is connected. Otherwise,
 * bank 0 IOs are untouched.
 * \endif
 */
static inline void rom_connect_internal_flash(void) {
    rom_connect_internal_flash_fn func = (rom_connect_internal_flash_fn) rom_func_lookup_inline(ROM_FUNC_CONNECT_INTERNAL_FLASH);