Add XIP cache maintenance API (fixes #2005)

[Wren6991]

Also add a cache clean to all hardware_flash implementations which flush the cache, to avoid losing cached PSRAM writes.

This adds five new functions:

• xip_cache_invalidate_all()
• xip_cache_invalidate_range()
• xip_cache_clean_all() (no-op on RP2040)
• xip_cache_clean_range() (no-op on RP2040)
• xip_cache_pin_range() (unavailable on RP2040)

It uses offsets (- XIP_BASE) instead of addresses, to be consistent with the hardware_flash APIs. If anyone strongly disagrees then we should change it now before we're stuck with it.

The library is unfortunately dependent on hardware_sync, just to get the barrier macros.

[kilograham]

pls add new library to docs/index.h

[will-v-pi]

LGTM for RP2350 - I've tested all the functions and they work as expected with PSRAM and Flash

[lurch]

@kilograham @Wren6991 If I try building the kitchen_sink in the SDK with arm-none-eabi-gcc 6.3.1 (which is admittedly pretty ancient) it complains at me that:

...../pico-sdk/src/rp2_common/hardware_xip_cache/xip_cache.c:27:29: error: always_inline function might not be inlinable [-Werror=attributes]
 __always_inline static void check_xip_offset_range(uintptr_t start_offset, uintptr_t size_bytes) {
                             ^~~~~~~~~~~~~~~~~~~~~~
cc1: all warnings being treated as errors

If I replace the __always_inline there with __force_inline then the kitchen_sink builds successfully to completion.

Let me know if this was the right fix, and I'll submit a PR (or of course you can fix it directly yourself if that's easier).

EDIT: Ahh, and according to https://github.com/raspberrypi/pico-sdk/actions/runs/11936570350 this is failing the CI builds for GCC 6.2.1, GCC 6.3.1 and GCC 7.2.1

[kilograham]

correct; we have __force_inline to work around GCC variations/bugs