Fixes for/found by documentation generation (#2099)

* fix errors breaking extra_[cmake_]configs.py
* remove trailing whitespace which is confusing asciidoctor
* fix rp2xxx-specific -> rp2xxx_specific
* add missing xip_cache funcs to the combined docs
* Revert "fix errors breaking extra_[cmake_]configs.py"
* Fix typo in #define name
* Allow optional whitespace at the start of "commented out" config lines

Co-authored-by: Andrew Scheller <[email protected]>

src/rp2_common/hardware_gpio/include/hardware/gpio.h

@@ -42,12 +42,12 @@ extern "C" {
  *
  * RP-series microcontrollers have two banks of General Purpose Input / Output (GPIO) pins, which are assigned as follows:
  * 
- * \if rp2040-specific
+ * \if rp2040_specific
  * RP2040 has 30 user GPIO pins in bank 0, and 6 QSPI pins in the QSPI bank 1 (QSPI_SS, QSPI_SCLK and QSPI_SD0 to QSPI_SD3). The QSPI 
  * pins are used to execute code from an external flash device, leaving the User bank (GPIO0 to GPIO29) for the programmer to use. 
  * \endif
  * 
- * \if rp2350-specific
+ * \if rp2350_specific
  * The number of GPIO pins available depends on the package. There are 30 user GPIOs in bank 0 in the QFN-60 package (RP2350A), or 48 user GPIOs 
  * in the QFN-80 package. Bank 1 contains the 6 QSPI pins and the USB DP/DM pins.
  * \endif

src/rp2_common/hardware_pio/include/hardware/pio.h

@@ -919,7 +919,7 @@ int pio_set_gpio_base(PIO pio, uint gpio_base);
  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
  * \param program the program definition
  * \return true if the program can be loaded;
- *         false if not, e.g. if there is not suitable space in the instruction memory      
+ *         false if not, e.g. if there is not suitable space in the instruction memory
  */
 bool pio_can_add_program(PIO pio, const pio_program_t *program);
 

src/rp2_common/hardware_xip_cache/include/hardware/xip_cache.h

@@ -20,14 +20,14 @@
  * of flash), so pointers should have XIP_BASE subtracted before passing into one of these
  * functions.
  *
- * \if rp2040-specific
+ * \if rp2040_specific
  * The only valid cache maintenance operation on RP2040 is "invalidate", which tells the cache to
  * forget everything it knows about some address. This is necessary after a programming operation,
  * because the cache does not automatically know about any serial programming operations performed
  * on the external flash device, and could return stale data.
  * \endif
  *
- * \if rp2350-specific
+ * \if rp2350_specific
  * On RP2350, the three types of operation are:
  *
  * * Invalidate: tell the cache to forget everything it knows about some address. The next access to
@@ -124,7 +124,7 @@ void xip_cache_invalidate_all(void);
  */
 void xip_cache_invalidate_range(uintptr_t start_offset, uintptr_t size_bytes);
 
-#if !XIP_CACHE_IS_READ_ONLY
+#if !XIP_CACHE_IS_READ_ONLY || PICO_COMBINED_DOCS
 
 /*! \brief Clean the cache for the entire XIP address space
  *  \ingroup hardware_xip_cache
@@ -136,12 +136,12 @@ void xip_cache_invalidate_range(uintptr_t start_offset, uintptr_t size_bytes);
  * This function is faster than calling xip_cache_clean_range() for the entire address space,
  * because it iterates over cachelines instead of addresses.
  *
- * \if rp2040-specific
+ * \if rp2040_specific
  * On RP2040 this is a no-op, as the XIP cache is read-only. This is indicated by the
  * XIP_CACHE_IS_READ_ONLY macro.
  * \endif
  *
- * \if rp2350-specific
+ * \if rp2350_specific
  * On RP2350, due to the workaround applied for RP2350-E11, this function also effectively
  * invalidates all cache lines after cleaning them. The next access to each line will miss. Avoid
  * this by calling xip_cache_clean_range() which does not suffer this issue.
@@ -155,7 +155,7 @@ void xip_cache_clean_all(void);
  *
  * This causes the cache to write out pending write data at these offsets to the downstream memory.
  *
- * \if rp2040-specific
+ * \if rp2040_specific
  * On RP2040 this is a no-op, as the XIP cache is read-only. This is indicated by the
  * XIP_CACHE_IS_READ_ONLY macro.
  * \endif
@@ -177,7 +177,7 @@ static inline void xip_cache_clean_range(uintptr_t start_offset, uintptr_t size_
 }
 #endif
 
-#if !PICO_RP2040
+#if !PICO_RP2040 || PICO_COMBINED_DOCS
 
 /*! \brief Pin a range of offsets within the XIP address space
  *  \ingroup hardware_xip_cache

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

@@ -403,7 +403,7 @@ static inline void rom_flash_enter_cmd_xip(void) {
     func();
 }
 
-#if !PICO_RP2040
+#if !PICO_RP2040 || PICO_COMBINED_DOCS
 #ifdef __riscv
 /*!
  * \brief Give the bootrom a new stack

src/rp2_common/pico_double/include/pico/double.h

@@ -65,7 +65,7 @@ double exp10(double x);
 void sincos(double x, double *sinx, double *cosx);
 double powint(double x, int y);
 
-#if !PICO_RP2040
+#if !PICO_RP2040 || PICO_COMBINED_DOCS
 double ddiv_fast(double n, double d);
 double sqrt_fast(double d);
 double mla(double x, double y, double z); // note this is not fused

src/rp2_common/pico_stdio_usb/include/pico/stdio_usb.h

@@ -74,8 +74,8 @@
 // PICO_CONFIG: PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED, Optionally define a pin to use as bootloader activity LED when BOOTSEL mode is entered via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE), type=int, min=0, max=47 on RP2350B, 29 otherwise, group=pico_stdio_usb
 
 // PICO_CONFIG: PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW, Whether pin to use as bootloader activity LED when BOOTSEL mode is entered via USB (either VIA_BAUD_RATE or VIA_VENDOR_INTERFACE) is active low, type=bool, default=0, group=pico_stdio_usb
-#ifndef PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED_ACTIVE_LOW
-#define PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED_ACTIVE_LOW 0
+#ifndef PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW
+#define PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED_ACTIVE_LOW 0
 #endif
 
 // PICO_CONFIG: PICO_STDIO_USB_RESET_BOOTSEL_FIXED_ACTIVITY_LED, Whether the pin specified by PICO_STDIO_USB_RESET_BOOTSEL_ACTIVITY_LED is fixed or can be modified by picotool over the VENDOR USB interface, type=bool, default=0, group=pico_stdio_usb

tools/extract_build_defines.py

@@ -139,7 +139,7 @@ def ValidateAttrs(config_name, config_attrs, file_path, linenum):
                     elif BASE_BUILD_DEFINE_RE.search(line):
                         m = BUILD_DEFINE_RE.match(line)
                         if not m:
-                            if line.startswith("## "):
+                            if re.match(r"^\s*#\s*# ", line):
                                 logger.info("Possible misformatted {} at {}:{} ({})".format(BASE_BUILD_DEFINE_NAME, file_path, linenum, line))
                             else:
                                 raise Exception("Found misformatted {} at {}:{} ({})".format(BASE_BUILD_DEFINE_NAME, file_path, linenum, line))

tools/extract_cmake_configs.py

@@ -139,7 +139,7 @@ def ValidateAttrs(config_name, config_attrs, file_path, linenum):
                     elif BASE_CMAKE_CONFIG_RE.search(line):
                         m = CMAKE_CONFIG_RE.match(line)
                         if not m:
-                            if line.startswith("## "):
+                            if re.match("^\s*#\s*# ", line):
                                 logger.info("Possible misformatted {} at {}:{} ({})".format(BASE_CMAKE_CONFIG_NAME, file_path, linenum, line))
                             else:
                                 raise Exception("Found misformatted {} at {}:{} ({})".format(BASE_CMAKE_CONFIG_NAME, file_path, linenum, line))

tools/extract_configs.py

@@ -158,7 +158,7 @@ def ValidateAttrs(config_name, config_attrs, file_path, linenum):
                     elif BASE_CONFIG_RE.search(line):
                         m = CONFIG_RE.match(line)
                         if not m:
-                            if line.startswith("//// "):
+                            if re.match(r"^\s*//\s*// ", line):
                                 logger.info("Possible misformatted {} at {}:{} ({})".format(BASE_CONFIG_NAME, file_path, linenum, line))
                             else:
                                 raise Exception("Found misformatted {} at {}:{} ({})".format(BASE_CONFIG_NAME, file_path, linenum, line))