mirror of
https://github.com/wiiu-env/wut.git
synced 2025-01-05 21:18:15 +01:00
Merge pull request #82 from QuarkTheAwesome/master
COS Docs: Add Doxygen for coreinit/cache, coreinit/core and coreinit/screen
This commit is contained in:
James
GitHub
commit
41073579f2
@ -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 <em>not</em> 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
|
||||
* <em>not</em> 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
|
||||
* <em>not</em> 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,
|
||||
|
||||
@ -4,6 +4,9 @@
|
||||
/**
|
||||
* \defgroup coreinit_core Core
|
||||
* \ingroup coreinit
|
||||
*
|
||||
* The coreinit Core group of functions provide information about each core of
|
||||
* the system's processor.
|
||||
* @{
|
||||
*/
|
||||
|
||||
@ -13,28 +16,44 @@ extern "C" {
|
||||
|
||||
|
||||
/**
|
||||
* Returns the number of cores, should always be 3.
|
||||
* Gets the number of cores in the system. On a retail Wii U, this is always 3.
|
||||
*
|
||||
* \returns
|
||||
* The core count of the system.
|
||||
*/
|
||||
uint32_t
|
||||
OSGetCoreCount();
|
||||
|
||||
|
||||
/**
|
||||
* Returns the ID of the core currently executing this thread.
|
||||
* Gets the core executing the current thread.
|
||||
*
|
||||
* \returns
|
||||
* The ID of the current core.
|
||||
*/
|
||||
uint32_t
|
||||
OSGetCoreId();
|
||||
|
||||
|
||||
/**
|
||||
* Returns the ID of the main core.
|
||||
* Gets the main core of the system. On a retail Wii U, this is always core 1.
|
||||
*
|
||||
* \returns
|
||||
* The ID of the main core.
|
||||
*/
|
||||
uint32_t
|
||||
OSGetMainCoreId();
|
||||
|
||||
|
||||
/**
|
||||
* Returns true if the current core is the main core.
|
||||
* Determines whether the current thread is running on the main core.
|
||||
* On a retail Wii U, the main core is always core 1.
|
||||
*
|
||||
* \returns
|
||||
* \c true if the current core is the main core.
|
||||
*
|
||||
* \sa
|
||||
* <ul><li>\link OSGetMainCoreId \endlink</li></ul>
|
||||
*/
|
||||
BOOL
|
||||
OSIsMainCore();
|
||||
|
||||
@ -4,6 +4,35 @@
|
||||
/**
|
||||
* \defgroup coreinit_screen Screen
|
||||
* \ingroup coreinit
|
||||
*
|
||||
* <!-- quick blurb - may show up on Modules page -->
|
||||
* Software-rendered graphics system, suitable for text output and simple
|
||||
* graphics.
|
||||
*
|
||||
* OSScreen is much more straightforward than GX2, which makes it appealing for
|
||||
* situations that do not require complex graphics. It can draw text and pixels
|
||||
* (one at a time!) to both the Gamepad and TV.
|
||||
*
|
||||
* To use OSScreen, first call \link OSScreenInit \endlink. Then, allocate a
|
||||
* memory area and pass it to OSScreen with \link OSScreenSetBufferEx \endlink -
|
||||
* after enabling the screens with \link OSScreenEnableEx \endlink, the library
|
||||
* will be ready to draw! Drawing is accomplished with \link
|
||||
* OSScreenClearBufferEx \endlink, \link OSScreenPutFontEx \endlink and \link
|
||||
* OSScreenPutPixelEx \endlink. Once drawing is complete, call \link
|
||||
* OSScreenFlipBuffersEx \endlink to show the results on-screen. Rinse and
|
||||
* repeat!
|
||||
*
|
||||
* <!-- Documentation meta: OSScreen has a weird naming convention, especially
|
||||
* around the word "buffer". So, here's what we're doing:
|
||||
* - A single framebuffer is a "buffer".
|
||||
* - The framebuffer that is visible is the "visible buffer" while the one
|
||||
* being drawn to is the "work buffer"
|
||||
* - The pointers going to OSScreenSetBufferEx are not buffers. Try "memory
|
||||
* area", "location", whatever.
|
||||
* - A "screen" refers to the Gamepad or TV.
|
||||
* - Members of OSScreenID are not buffers. Try "screen ID".
|
||||
* This should help prevent confusion. If you change this, make sure to
|
||||
* update all the docs to keep everything consistent. -->
|
||||
* @{
|
||||
*/
|
||||
|
||||
@ -11,44 +40,187 @@
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
//! Defines the ID of a display usable with OSScreen.
|
||||
typedef enum OSScreenID
|
||||
{
|
||||
//! Represents the TV connected to the system.
|
||||
SCREEN_TV = 0,
|
||||
//! Represents the screen in the DRC (gamepad).
|
||||
SCREEN_DRC = 1,
|
||||
} OSScreenID;
|
||||
|
||||
/**
|
||||
* Initialises the OSScreen library for use. This function must be called before
|
||||
* using any other OSScreen functions.
|
||||
*
|
||||
* \sa <ul>
|
||||
* <li>\link OSScreenSetBufferEx \endlink</li>
|
||||
* <li>\link OSScreenEnableEx \endlink</li>
|
||||
* <li>\link OSScreenShutdown \endlink</li>
|
||||
* </ul>
|
||||
*/
|
||||
void
|
||||
OSScreenInit();
|
||||
|
||||
/**
|
||||
* Cleans up and shuts down the OSScreen library.
|
||||
*
|
||||
* \sa <ul>
|
||||
* <li>\link OSScreenEnableEx \endlink</li>
|
||||
* </ul>
|
||||
*/
|
||||
void
|
||||
OSScreenShutdown();
|
||||
|
||||
/**
|
||||
* Gets the amount of memory required to fit both buffers of a given screen.
|
||||
*
|
||||
* \param screen
|
||||
* The ID of the screen to be sized.
|
||||
*
|
||||
* \sa <ul>
|
||||
* <li>\link OSScreenSetBufferEx \endlink</li>
|
||||
* </ul>
|
||||
*/
|
||||
uint32_t
|
||||
OSScreenGetBufferSizeEx(OSScreenID screen);
|
||||
|
||||
/**
|
||||
* Sets the memory location for both buffers of a given screen. This location
|
||||
* must be of the size prescribed by \link OSScreenGetBufferSizeEx \endlink and
|
||||
* at an address aligned to 0x100 bytes.
|
||||
*
|
||||
* \param screen
|
||||
* The ID of the screen whose memory location should be changed.
|
||||
*
|
||||
* \param addr
|
||||
* Pointer to the memory to use. This area must be 0x100 aligned, and of the
|
||||
* size given by \link OSScreenGetBufferSizeEx \endlink.
|
||||
*
|
||||
* \sa <ul>
|
||||
* <li>\link OSScreenGetBufferSizeEx \endlink</li>
|
||||
* </ul>
|
||||
*/
|
||||
void
|
||||
OSScreenSetBufferEx(OSScreenID screen,
|
||||
void *addr);
|
||||
|
||||
/**
|
||||
* Clear the work buffer of the given screen by setting all of its pixels to
|
||||
* a given colour.
|
||||
*
|
||||
* \param screen
|
||||
* The ID of the screen to clear. Only the work buffer will be cleared.
|
||||
*
|
||||
* \param colour
|
||||
* The colour to use, in big-endian RGBX8 format - 0xRRGGBBXX, where X bits are
|
||||
* ignored.
|
||||
*
|
||||
* \note
|
||||
* Since this function only affects the <em>work buffer</em>, its effect will
|
||||
* not appear on screen immediately. See \link OSScreenFlipBuffersEx \endlink.
|
||||
*
|
||||
* \sa <ul>
|
||||
* <li>\link OSScreenPutFontEx \endlink</li>
|
||||
* <li>\link OSScreenPutPixelEx \endlink</li>
|
||||
* </ul>
|
||||
*
|
||||
* <!-- TODO: Are the XX bits really ignored? I'm basing this off a vague memory
|
||||
* of setting them to 00 and nothing changing... Check this. -->
|
||||
*/
|
||||
void
|
||||
OSScreenClearBufferEx(OSScreenID screen,
|
||||
uint32_t colour);
|
||||
|
||||
/**
|
||||
* Swap the buffers of the given screen. The work buffer will become the visible
|
||||
* buffer and will start being shown on-screen, while the visible buffer becomes
|
||||
* the new work buffer. This operation is known as "flipping" the buffers.
|
||||
*
|
||||
* You must call this function once drawing is complete, otherwise draws will
|
||||
* not appear on-screen.
|
||||
*
|
||||
* \param screen
|
||||
* The ID of the screen to flip.
|
||||
*/
|
||||
void
|
||||
OSScreenFlipBuffersEx(OSScreenID screen);
|
||||
|
||||
/**
|
||||
* Draws text at the given position. The text will be drawn to the work
|
||||
* buffer with a built-in monospace font, coloured white, and anti-aliased.
|
||||
* The position coordinates are in <em>characters</em>, not pixels.
|
||||
*
|
||||
* \param screen
|
||||
* The ID of the screen to draw to. Only the work buffer will be affected.
|
||||
*
|
||||
* \param row
|
||||
* The row, in characters, to place the text in. 0 corresponds to the top of
|
||||
* the screen.
|
||||
*
|
||||
* \param column
|
||||
* The column, in characters, to place the text at. 0 corresponds to the left of
|
||||
* the screen.
|
||||
*
|
||||
* \param buffer
|
||||
* Pointer to the string of text to draw. Null-terminated.
|
||||
*
|
||||
* \note
|
||||
* Since this function only affects the <em>work buffer</em>, its effect will
|
||||
* not appear on screen immediately. See \link OSScreenFlipBuffersEx \endlink.
|
||||
*
|
||||
* \sa <ul>
|
||||
* <li>\link OSScreenPutPixelEx \endlink</li>
|
||||
* <li>\link OSScreenClearBufferEx \endlink</li>
|
||||
* </ul>
|
||||
*/
|
||||
void
|
||||
OSScreenPutFontEx(OSScreenID screen,
|
||||
uint32_t row,
|
||||
uint32_t column,
|
||||
const char *buffer);
|
||||
|
||||
/**
|
||||
* Draws a single pixel at the given position. The pixel, a 32-bit RGBX
|
||||
* colour, will be placed in the work buffer at the coordinates given.
|
||||
*
|
||||
* \param screen
|
||||
* The ID of the screen to place the pixel in.
|
||||
*
|
||||
* \param x
|
||||
* The x-coordinate, in pixels, to draw the pixel at.
|
||||
*
|
||||
* \param y
|
||||
* The y-coordinate, in pixels, to draw the pixel at.
|
||||
*
|
||||
* \param colour
|
||||
* The desired colour of the pixel to draw, in RGBX32 colour (0xRRGGBBXX, where
|
||||
* the XX value is ignored).
|
||||
*
|
||||
* \note
|
||||
* Since this function only affects the <em>work buffer</em>, its effect will
|
||||
* not appear on screen immediately. See \link OSScreenFlipBuffersEx \endlink.
|
||||
*
|
||||
* \sa <ul>
|
||||
* <li>\link OSScreenPutFontEx \endlink</li>
|
||||
* <li>\link OSScreenClearBufferEx \endlink</li>
|
||||
* </ul>
|
||||
*/
|
||||
void
|
||||
OSScreenPutPixelEx(OSScreenID screen,
|
||||
uint32_t x,
|
||||
uint32_t y,
|
||||
uint32_t colour);
|
||||
|
||||
/**
|
||||
* Enables or disables a given screen. If a screen is disabled, it shows black.
|
||||
*
|
||||
* \param screen
|
||||
* The ID of the screen to enable or disable.
|
||||
*
|
||||
* \param enable
|
||||
* \c true if the screen should be enabled, otherwise false.
|
||||
*/
|
||||
void
|
||||
OSScreenEnableEx(OSScreenID screen,
|
||||
BOOL enable);
|
||||
|
||||
Loading…
Reference in New Issue
Block a user