Repository: raspberrypi/pico-sdk
File: src/rp2_common/hardware_xip_cache/include/hardware/xip_cache.h (C/C++)

Code before:
 *  Must be 4-byte-aligned on RP2040. Must be a aligned to the start of a cache line
 *  (XIP_CACHE_LINE_SIZE) on other platforms.
 *
 * \param size_bytes The number of bytes to invalidate. Must be a multiple of 4 bytes on RP2040.
 *  Must be a multiple of XIP_CACHE_LINE_SIZE on other platforms.
 *
 * Invalidation ensures that subsequent reads will fetch data from the downstream memory, rather
 * than using (potentially stale) cached data.

 * @note Any pending write data held in the cache is lost: you can force the cache to commit these
 *  writes first, by calling xip_cache_clean_range() with the same parameters. Generally this is
 *  not necessary because invalidation is used with flash (write-behind via programming), and
 *  cleaning is used with PSRAM (writing through the cache).
 *
 */
void xip_cache_invalidate_range(uintptr_t start_offset, uintptr_t size_bytes);

#if !XIP_CACHE_IS_READ_ONLY

/*! \brief Clean the cache for the entire XIP address space
 *  \ingroup hardware_xip_cache
 *
 * This causes the cache to write out all pending write data to the downstream memory. For example,
 * when suspending the system with state retained in external PSRAM, this ensures all data has made
 * it out to external PSRAM before powering down.
 *
 * 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
 * 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
 * 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.
 * \endif
 *
 */

void xip_cache_clean_all(void);

/*! \brief Clean a range of offsets within the XIP address space
 *  \ingroup hardware_xip_cache
 *
 * This causes the cache to write out pending write data at these offsets to the downstream memory.
 *
 * \if rp2040-specific
 * On RP2040 this is a no-op, as the XIP cache is read-only. This is indicated by the

Review comment (performance):
Small nitpick, but IMHO it looks a bit weird having rp2040-specific doxygen inside a `#if !XIP_CACHE_IS_READ_ONLY` block, when `XIP_CACHE_IS_READ_ONLY` is 1 on RP2040.

I wonder if it might look better as e.g. :
```c
/*! Doxygen for the xip_cache_clean_all function
*/
#if !XIP_CACHE_IS_READ_ONLY
void xip_cache_clean_all(void);
#else
static inline void xip_cache_clean_all(void) {}
#endif
```
as that way the Doxygen remains "outisde" of the `#if` block. Or does my suggested approach of having the `#if` between doxygen and the function-declaration screw up the doxygen processing? (I'm aware that it can be a bit "delicate"!)

Code after:
 *  Must be a multiple of XIP_CACHE_LINE_SIZE on other platforms.
 *
 * Invalidation ensures that subsequent reads will fetch data from the downstream memory, rather
 * than using (potentially stale) cached data.

 * @note Any pending write data held in the cache is lost: you can force the cache to commit these
 *  writes first, by calling xip_cache_clean_range() with the same parameters. Generally this is
 *  not necessary because invalidation is used with flash (write-behind via programming), and
 *  cleaning is used with PSRAM (writing through the cache).
 *
 */
void xip_cache_invalidate_range(uintptr_t start_offset, uintptr_t size_bytes);

#if !XIP_CACHE_IS_READ_ONLY

/*! \brief Clean the cache for the entire XIP address space
 *  \ingroup hardware_xip_cache
 *
 * This causes the cache to write out all pending write data to the downstream memory. For example,
 * when suspending the system with state retained in external PSRAM, this ensures all data has made
 * it out to external PSRAM before powering down.
 *
 * 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
 * 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
 * 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.
 * \endif
 *
 */
void xip_cache_clean_all(void);

/*! \brief Clean a range of offsets within the XIP address space
 *  \ingroup hardware_xip_cache
 *
 * This causes the cache to write out pending write data at these offsets to the downstream memory.
 *
 * \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
 *
 * \param start_offset The first offset to be invalidated. Offset 0 means the first byte of XIP
 *  memory (e.g. flash). Pointers must have XIP_BASE subtracted before passing into this function.