Merge pull request #82 from QuarkTheAwesome/master

COS Docs: Add Doxygen for coreinit/cache, coreinit/core and coreinit/screen

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 <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,

include/coreinit/core.h

@@ -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();

include/coreinit/screen.h

@@ -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);