diff --git a/include/coreinit/cache.h b/include/coreinit/cache.h index 296bc44..f20a9ed 100644 --- a/include/coreinit/cache.h +++ b/include/coreinit/cache.h @@ -5,7 +5,19 @@ * \defgroup coreinit_cache Cache * \ingroup coreinit * - * Cache synchronisation functions. + * The Cache group of functions provide an interface to the low-level caching + * system of the PowerPC processor. The cache acts as a middleman between main + * memory and the processor, speeding up access to frequently-used data. + * + * However, the Wii U is not cache-coherent - written data may be cached + * without updating main memory, and data read from the cache may be out of date + * with respect to memory. While this isn't a problem for most code, certain + * hardware accesses may require manual synchronisation of the cache. This is + * achieved with coreinit's Cache group of functions. + * + * Since the PowerPC has a seperate cache for data and instructions, any data + * written with the intent of executing it as instructions requires manual + * flushing and invalidation of the data and instruction caches. * @{ */ @@ -13,45 +25,104 @@ extern "C" { #endif - /** - * Equivalent to dcbi instruction. + * Invalidates a range of cached data, in blocks. Equivalent to a loop of + * PowerPC \c dcbi instructions. + * + * This function forces the next reads from the given address to bypass the + * the cache and go straight to memory, resulting in slower reads that are + * guaranteed to reflect main memory. + * + * \param addr + * The effective address of the data to invalidate. + * + * \param size + * The size of the range to invalidate. Will be rounded up to the next 0x20. + * + * \note + * Unnecessary use of caching functions can have an adverse performance impact. + * They should only be used when needed while interfacing with hardware. */ void DCInvalidateRange(void *addr, uint32_t size); - /** - * Equivalent to dcbf, sync, eieio. + * Flushes a range of cached data, in blocks. Equivalent to a loop of PowerPC + * \c dcbf instructions, followed by a \c sync and \c eieio. + * + * This function flushes any recently cached data into main memory. + * This allows other hardware in the console to read the data without worry + * of main memory being outdated. It will also invalidate cached data. + * + * \param addr + * The effective address of the data to flush. + * + * \param size + * The size of the range to flush. Will be rounded up to the next 0x20. + * + * \note + * Unnecessary use of caching functions can have an adverse performance impact. + * They should only be used when needed while interfacing with hardware. */ void DCFlushRange(void *addr, uint32_t size); - /** - * Equivalent to dcbst, sync, eieio. + * Stores a range of cached data, in blocks. Equivalent to a loop of PowerPC + * \c dcbst instructions, followed by a \c sync and \c eieio. + * + * This function writes any recently cached data into main memory. + * This allows other hardware in the console to read the data without worry + * of main memory being outdated. This function does not invalidate + * the cached data. + * + * \param addr + * The effective address of the data to store. + * + * \param size + * The size of the range to store. Will be rounded up to the next 0x20. + * + * \note + * Unnecessary use of caching functions can have an adverse performance impact. + * They should only be used when needed while interfacing with hardware. */ void DCStoreRange(void *addr, uint32_t size); - /** - * Equivalent to dcbf. + * Similar to \link DCFlushRange \endlink, though this function will + * not run PowerPC \c sync and \c eieio instructions after flushing. * - * Does not perform sync, eieio like DCFlushRange. + * \param addr + * The effective address of the data to flush. + * + * \param size + * The size of the range to flush. Will be rounded up to the next 0x20. + * + * \note + * Unnecessary use of caching functions can have an adverse performance impact. + * They should only be used when needed while interfacing with hardware. */ void DCFlushRangeNoSync(void *addr, uint32_t size); - /** - * Equivalent to dcbst. + * Similar to \link DCStoreRange \endlink, though this function will + * not run PowerPC \c sync and \c eieio instructions after storing. * - * Does not perform sync, eieio like DCStoreRange. + * \param addr + * The effective address of the data to store. + * + * \param size + * The size of the range to store. Will be rounded up to the next 0x20. + * + * \note + * Unnecessary use of caching functions can have an adverse performance impact. + * They should only be used when needed while interfacing with hardware. */ void DCStoreRangeNoSync(void *addr, @@ -59,7 +130,22 @@ DCStoreRangeNoSync(void *addr, /** - * Equivalent to dcbz instruction. + * Zeroes the given area of the data cache (to the nearest block) with a loop of + * PowerPC \c dcbz instructions. + * This will not affect main memory immediately, though it will eventually + * trickle down. Can be combined with \link DCFlushRange \endlink or + * \link DCStoreRange \endlink to efficiently set memory to 0. + * + * \warning + * The size of the range passed into this function will be internally rounded up + * to the next multiple of 0x20. Failing to account for this could result in + * delayed, hard-to-diagnose memory corruption. + * + * \param addr + * The effective address of the data to zero. + * + * \param size + * The size of the range to zero. Will be rounded up to the next 0x20. */ void DCZeroRange(void *addr, @@ -67,7 +153,17 @@ DCZeroRange(void *addr, /** - * Equivalent to dcbt instruction. + * Gives the processor a hint that the given range of memory is likely to be + * accessed soon, and that performance would be improved if it were cached. + * The processor does not have to cache the requested area, but it may do so in + * response to this function. This function is equvalent to a loop of PowerPC + * \c dcbt instructions. + * + * \param addr + * The effective address of the data to cache. + * + * \param size + * The size of the range to cache. Will be rounded up to the next 0x20. */ void DCTouchRange(void *addr, @@ -75,7 +171,22 @@ DCTouchRange(void *addr, /** - * Equivalent to icbi instruction. + * Invalidates a range of cached instructions, in blocks. Equivalent to a loop + * of PowerPC \c icbi instructions. + * + * This function forces the next instruction fetches from the given address to + * bypass the the cache and go straight to memory, resulting in slower fetches + * that are guaranteed to reflect main memory. + * + * \param addr + * The effective address of the instructions to invalidate. + * + * \param size + * The size of the range to invalidate. Will be rounded up to the next 0x20. + * + * \note + * Unnecessary use of caching functions can have an adverse performance impact. + * They should only be used when needed while interfacing with hardware. */ void ICInvalidateRange(void *addr,