Start doxygen documentation.

docs/mainpage.dox

@@ -0,0 +1,10 @@
+/**
+ * \mainpage Wii U Toolchain
+ *
+ * \section Introduction
+ * An experimental in-development Wii U toolchain, the source can be found at
+ * https://github.com/decaf-emu/wut
+ *
+ * \section Usage
+ * TODO.
+ */

include/coreinit/alarm.h

@@ -4,6 +4,19 @@
 #include "threadqueue.h"
 #include "time.h"
 
+/**
+ * \defgroup coreinit_alarms Alarms
+ * \ingroup coreinit
+ *
+ * The alarm family of functions are used for creating alarms which call
+ * a callback or wake up waiting threads after a period of time.
+ *
+ * Alarms can be one shot alarms which trigger once after a period of time,
+ * or periodic which trigger at regular intervals until they are cancelled.
+ *
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -48,23 +61,47 @@ CHECK_SIZE(OSAlarmLink, 0x08);
 #define OS_ALARM_TAG 0x614C724Du
 struct OSAlarm
 {
-   // OS_ALARM_TAG
+   //! Should always be set to the value OS_ALARM_TAG.
    uint32_t tag;
 
-   // Name set from OSCreateAlarmEx
+   //! Name set from OSCreateAlarmEx.
    const char *name;
+
    UNKNOWN(4);
+
+   //! The callback to execute once the alarm is triggered.
    OSAlarmCallback callback;
+
+   //! Used with OSCancelAlarms for bulk cancellation of alarms.
    uint32_t group;
+
    UNKNOWN(4);
+
+   //! The time when the alarm will next be triggered.
    OSTime nextFire;
+
+   //! Link used for when this OSAlarm object is inside an OSAlarmQueue
    OSAlarmLink link;
+
+   //! The period between alarm triggers, this is only set for periodic alarms.
    OSTime period;
-   OSTime tbrStart;
+
+   //! The time the alarm was started.
+   OSTime start;
+
+   //! User data set with OSSetAlarmUserData and retrieved with OSGetAlarmUserData.
    void *userData;
+
+   //! The current state of the alarm, internal values.
    uint32_t state;
+
+   //! Queue of threads currently waiting for the alarm to trigger with OSWaitAlarm.
    OSThreadQueue threadQueue;
+
+   //! The queue that this alarm is currently in.
    OSAlarmQueue *alarmQueue;
+
+   //! The context the alarm was triggered on.
    OSContext *context;
 };
 CHECK_OFFSET(OSAlarm, 0x00, tag);
@@ -82,51 +119,112 @@ CHECK_OFFSET(OSAlarm, 0x50, alarmQueue);
 CHECK_OFFSET(OSAlarm, 0x54, context);
 CHECK_SIZE(OSAlarm, 0x58);
 
+
+/**
+ * Cancel an alarm.
+ */
 BOOL
 OSCancelAlarm(OSAlarm *alarm);
 
+
+/**
+ * Cancel all alarms which have a matching tag set by OSSetAlarmTag.
+ *
+ * \param group The alarm tag to cancel.
+ */
 void
 OSCancelAlarms(uint32_t group);
 
+
+/**
+ * Initialise an alarm structure.
+ */
 void
 OSCreateAlarm(OSAlarm *alarm);
 
+
+/**
+ * Initialise an alarm structure with a name.
+ */
 void
 OSCreateAlarmEx(OSAlarm *alarm,
                 const char *name);
 
+
+/**
+ * Return user data set by OSSetAlarmUserData.
+ */
 void *
 OSGetAlarmUserData(OSAlarm *alarm);
 
+
+/**
+ * Initialise an alarm queue structure.
+ */
 void
 OSInitAlarmQueue(OSAlarmQueue *queue);
 
+
+/**
+ * Initialise an alarm queue structure with a name.
+ */
 void
 OSInitAlarmQueueEx(OSAlarmQueue *queue,
                    const char *name);
 
+
+/**
+ * Set a one shot alarm to perform a callback after a set amount of time.
+ *
+ * \param alarm The alarm to set.
+ * \param time The duration until the alarm should be triggered.
+ * \param callback The alarm callback to call when the alarm is triggered.
+ */
 BOOL
 OSSetAlarm(OSAlarm *alarm,
            OSTime time,
-           AlarmCallback callback);
+           OSAlarmCallback callback);
 
+
+/**
+ * Set a repeated alarm to execute a callback every interval from start.
+ *
+ * \param alarm The alarm to set.
+ * \param start The duration until the alarm should first be triggered.
+ * \param interval The interval between triggers after the first trigger.
+ * \param callback The alarm callback to call when the alarm is triggered.
+ */
 BOOL
 OSSetPeriodicAlarm(OSAlarm *alarm,
                    OSTime start,
                    OSTime interval,
-                   AlarmCallback callback);
+                   OSAlarmCallback callback);
 
+
+/**
+ * Set an alarm tag which is used in OSCancelAlarms for bulk cancellation.
+ */
 void
 OSSetAlarmTag(OSAlarm *alarm,
               uint32_t group);
 
+
+/**
+ * Set alarm user data which is returned by OSGetAlarmUserData.
+ */
 void
 OSSetAlarmUserData(OSAlarm *alarm,
                    void *data);
 
+
+/**
+ * Sleep the current thread until the alarm has been triggered or cancelled.
+ */
 BOOL
 OSWaitAlarm(OSAlarm *alarm);
 
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/atomic64.h

@@ -1,6 +1,14 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_atomic64 Atomic 64 bit
+ * \ingroup coreinit
+ *
+ * These functions are used for atomically operating on 64 bit values in memory.
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -54,3 +62,5 @@ OSTestAndSetAtomic64(uint64_t *ptr,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/baseheap.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_baseheap Base Heap
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -28,3 +34,5 @@ MEMSetBaseHeapHandle(MEMBaseHeapType type,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/cache.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_cache Cache
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -36,3 +42,5 @@ DCTouchRange(void *addr,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/condition.h

@@ -2,6 +2,12 @@
 #include <wut.h>
 #include "threadqueue.h"
 
+/**
+ * \defgroup coreinit_cond Condition Variable
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -13,15 +19,15 @@ typedef struct OSMutex OSMutex;
 
 struct OSCondition
 {
-   // OS_CONDITION_TAG
+   //! Should always be set to the value OS_CONDITION_TAG.
    uint32_t tag;
 
-   // Name set by OSInitCondEx(condition, name)
+   //! Name set by OSInitCondEx.
    const char *name;
 
    UNKNOWN(4);
 
-   // Queue of threads waiting on condition
+   //! Queue of threads currently waiting on condition with OSWaitCond.
    OSThreadQueue queue;
 };
 CHECK_OFFSET(OSCondition, 0x00, tag);
@@ -46,3 +52,5 @@ OSSignalCond(OSCondition *condition);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/core.h

@@ -1,22 +1,47 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_core Core Identification
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+
+/**
+ * Returns the number of cores, should always be 3.
+ */
 uint32_t
 OSGetCoreCount();
 
+
+/**
+ * Returns the ID of the core currently executing this thread.
+ */
 uint32_t
 OSGetCoreId();
 
+
+/**
+ * Returns the ID of the main core.
+ */
 uint32_t
 OSGetMainCoreId();
 
+
+/**
+ * Returns true if the current core is the main core.
+ */
 BOOL
 OSIsMainCore();
 
+
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/debug.h

@@ -1,25 +1,38 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_debug Debug
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+
 void
 OSConsoleWrite(const char *msg,
                uint32_t size);
 
+
 void
 OSReport(const char *fmt, ...);
 
+
 void
 OSPanic(const char *file,
         uint32_t line,
         const char *fmt, ...);
 
+
 void
 OSFatal(const char *msg);
 
+
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/dynload.h

@@ -3,6 +3,12 @@
 #include "thread.h"
 #include "time.h"
 
+/**
+ * \defgroup coreinit_dynload Dynamic Loading
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -12,27 +18,57 @@ typedef void *OSDynLoadModule;
 typedef int (*OSDynLoadAllocFn)(int size, int align, void **outAddr);
 typedef void (*OSDynLoadFreeFn)(void *addr);
 
+
+/**
+ * Set the allocator function to use for dynamic loading.
+ */
 int32_t
 OSDynLoad_SetAllocator(OSDynLoadAllocFn allocFn,
                        OSDynLoadFreeFn freeFn);
 
+
+/**
+ * Get the allocator function used for dynamic loading.
+ */
 int32_t
 OSDynLoad_GetAllocator(OSDynLoadAllocFn *outAllocFn,
                        OSDynLoadFreeFn *outFreeFn);
 
+
+/**
+ * Load a module.
+ *
+ * If the module is already loaded, increase reference count.
+ * Similar to LoadLibrary on Windows.
+ */
 int32_t
 OSDynLoad_Acquire(char const *name,
                   OSDynLoadModule *outModule);
 
+
+/**
+ * Retrieve the address of a function or data export from a module.
+ *
+ * Similar to GetProcAddress on Windows.
+ */
 int32_t
 OSDynLoad_FindExport(OSDynLoadModule module,
                      int32_t isData,
                      char const *name,
                      void **outAddr);
 
+
+/**
+ * Free a module handle returned from OSDynLoad_Acquire.
+ *
+ * Will decrease reference count and only unload the module if count reaches 0.
+ * Similar to FreeLibrary on Windows.
+ */
 void
 OSDynLoad_Release(OSDynLoadModule module);
 
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/event.h

@@ -3,6 +3,12 @@
 #include "thread.h"
 #include "threadqueue.h"
 
+/**
+ * \defgroup coreinit_event Event Object
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -66,3 +72,5 @@ OSWaitEventWithTimeout(OSEvent *event,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/exception.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_exception Exception Handling
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -39,3 +45,5 @@ OSSetExceptionCallbackEx(UNKNOWN_ARG,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/exit.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_exit Exit
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -14,3 +20,5 @@ _Exit();
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/expandedheap.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_expheap Expanded Heap
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -87,3 +93,5 @@ MEMGetAllocDirForMBlockExpHeap(uint8_t *addr);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/fastcondition.h

@@ -2,6 +2,15 @@
 #include <wut.h>
 #include "threadqueue.h"
 
+/**
+ * \defgroup coreinit_fastcond Fast Condition Variable
+ * \ingroup coreinit
+ *
+ * A condition variable to be used with an OSFastMutex.
+ *
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -37,3 +46,5 @@ OSFastCond_Signal(OSFastCondition *condition);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/fastmutex.h

@@ -2,6 +2,12 @@
 #include <wut.h>
 #include "threadqueue.h"
 
+/**
+ * \defgroup coreinit_fastmutex Fast Mutex
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -51,3 +57,5 @@ OSFastMutex_TryLock(OSFastMutex *mutex);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/frameheap.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_frameheap Frame Heap
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -64,3 +70,5 @@ MEMGetAllocatableSizeForFrmHeapEx(MEMFrameHeap *heap,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/memlist.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_memlist Memory List
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -64,3 +70,5 @@ MEMGetNthListObject(MEMMEMMemoryList *list,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/messagequeue.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_msgq Message Queue
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -84,3 +90,5 @@ OSGetSystemMessageQueue();
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/mutex.h

@@ -2,6 +2,12 @@
 #include <wut.h>
 #include "threadqueue.h"
 
+/**
+ * \defgroup coreinit_mutex Mutex
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -71,3 +77,5 @@ OSTryLockMutex(OSMutex *mutex);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/rendezvous.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_rendezvous Rendezvous
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -32,3 +38,5 @@ OSWaitRendezvousWithTimeout(OSRendezvous *rendezvous,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/semaphore.h

@@ -2,6 +2,12 @@
 #include <wut.h>
 #include "threadqueue.h"
 
+/**
+ * \defgroup coreinit_semaphore Semaphore
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -48,3 +54,5 @@ OSTryWaitSemaphore(OSSemaphore *semaphore);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/spinlock.h

@@ -2,6 +2,12 @@
 #include <wut.h>
 #include "time.h"
 
+/**
+ * \defgroup coreinit_spinlock Spinlock
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -53,3 +59,5 @@ OSUninterruptibleSpinLock_Release(OSSpinLock *spinlock);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/taskqueue.h

@@ -2,6 +2,12 @@
 #include <wut.h>
 #include "time.h"
 
+/**
+ * \defgroup coreinit_taskq Task Queue
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -183,3 +189,5 @@ MPRunTask(MPTask *task);
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/thread.h

@@ -3,6 +3,12 @@
 #include "time.h"
 #include "threadqueue.h"
 
+/**
+ * \defgroup coreinit_thread Thread
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -326,3 +332,5 @@ OSYieldThread();
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/threadqueue.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_threadq Thread Queue
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -51,3 +57,5 @@ OSInitThreadQueueEx(OSThreadQueue *queue,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/time.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_time Time
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -49,3 +55,5 @@ OSTicksToCalendarTime(OSTime time,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/coreinit/unitheap.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup coreinit_unitheap Unit Heap
+ * \ingroup coreinit
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -43,3 +49,5 @@ MEMCalcHeapSizeForUnitHeap(uint32_t blockSize,
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */

include/gx2/state.h

@@ -1,6 +1,12 @@
 #pragma once
 #include <wut.h>
 
+/**
+ * \defgroup gx2_state State
+ * \ingroup gx2
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -25,3 +31,5 @@ GX2Shutdown();
 #ifdef __cplusplus
 }
 #endif
+
+/** @} */