From 2656225392db2357e7395ecd1633010b37c5f8fb Mon Sep 17 00:00:00 2001 From: Steven Smith Date: Sun, 4 Oct 2015 12:18:36 -0700 Subject: [PATCH 1/2] Finish documentation in include/3ds and include/3ds/util. --- libctru/include/3ds/console.h | 2 - libctru/include/3ds/gfx.h | 6 +- libctru/include/3ds/ipc.h | 7 +- libctru/include/3ds/linear.h | 2 - libctru/include/3ds/mappable.h | 2 - libctru/include/3ds/os.h | 6 +- libctru/include/3ds/romfs.h | 56 ++- libctru/include/3ds/sdmc.h | 8 +- libctru/include/3ds/srv.h | 51 +++ libctru/include/3ds/svc.h | 575 +++++++++++++++++++++----- libctru/include/3ds/synchronization.h | 52 ++- libctru/include/3ds/types.h | 55 +-- libctru/include/3ds/util/rbtree.h | 89 +++- libctru/include/3ds/util/utf.h | 4 + libctru/include/3ds/vram.h | 2 - 15 files changed, 727 insertions(+), 190 deletions(-) diff --git a/libctru/include/3ds/console.h b/libctru/include/3ds/console.h index 81fb52e..f635986 100644 --- a/libctru/include/3ds/console.h +++ b/libctru/include/3ds/console.h @@ -1,5 +1,3 @@ - - /*! \file console.h \brief 3ds stdio support. diff --git a/libctru/include/3ds/gfx.h b/libctru/include/3ds/gfx.h index 46d6909..cf37fec 100644 --- a/libctru/include/3ds/gfx.h +++ b/libctru/include/3ds/gfx.h @@ -13,10 +13,11 @@ #define RGB565(r,g,b) (((b)&0x1f)|(((g)&0x3f)<<5)|(((r)&0x1f)<<11)) #define RGB8_to_565(r,g,b) (((b)>>3)&0x1f)|((((g)>>2)&0x3f)<<5)|((((r)>>3)&0x1f)<<11) +//! Available screens. typedef enum { - GFX_TOP = 0, - GFX_BOTTOM = 1 + GFX_TOP = 0, ///< Top screen + GFX_BOTTOM = 1 ///< Bottom screen }gfxScreen_t; /** @@ -29,7 +30,6 @@ typedef enum { GFX_LEFT = 0, ///< Left eye framebuffer GFX_RIGHT = 1,///< Right eye framebuffer - // GFX_BOTTOM = 0 }gfx3dSide_t; diff --git a/libctru/include/3ds/ipc.h b/libctru/include/3ds/ipc.h index 339abf2..6baba48 100644 --- a/libctru/include/3ds/ipc.h +++ b/libctru/include/3ds/ipc.h @@ -7,11 +7,12 @@ #include <3ds/types.h> +//! IPC buffer access rights. typedef enum { - IPC_BUFFER_R = BIT(1), - IPC_BUFFER_W = BIT(2), - IPC_BUFFER_RW = IPC_BUFFER_R | IPC_BUFFER_W + IPC_BUFFER_R = BIT(1), ///< Readable + IPC_BUFFER_W = BIT(2), ///< Writable + IPC_BUFFER_RW = IPC_BUFFER_R | IPC_BUFFER_W ///< Readable and Writable } IPC_BufferRights; diff --git a/libctru/include/3ds/linear.h b/libctru/include/3ds/linear.h index 5ede128..8b09781 100644 --- a/libctru/include/3ds/linear.h +++ b/libctru/include/3ds/linear.h @@ -4,8 +4,6 @@ */ #pragma once -// Functions for allocating/deallocating memory from linear heap - /** * @brief Allocates a 0x80-byte aligned buffer. * @param size Size of the buffer to allocate. diff --git a/libctru/include/3ds/mappable.h b/libctru/include/3ds/mappable.h index 742f1f8..826bc74 100644 --- a/libctru/include/3ds/mappable.h +++ b/libctru/include/3ds/mappable.h @@ -4,8 +4,6 @@ */ #pragma once -// Functions for allocating/deallocating mappable memory - /** * @brief Allocates a page-aligned buffer. * @param size Size of the buffer to allocate. diff --git a/libctru/include/3ds/os.h b/libctru/include/3ds/os.h index b74ad5c..ddac573 100644 --- a/libctru/include/3ds/os.h +++ b/libctru/include/3ds/os.h @@ -34,14 +34,14 @@ u32 osConvertOldLINEARMemToNew(u32 addr); const char* osStrError(u32 error); /** - * @return the Firm version + * @return The Firm version * * This can be used to compare system versions easily with @ref SYSTEM_VERSION. */ u32 osGetFirmVersion(void); /** - * @return the kernel version + * @return The kernel version * * This can be used to compare system versions easily with @ref SYSTEM_VERSION. * @@ -52,7 +52,7 @@ u32 osGetFirmVersion(void); u32 osGetKernelVersion(void); /** - * @return number of milliseconds since 1st Jan 1900 00:00. + * @return The number of milliseconds since 1st Jan 1900 00:00. */ u64 osGetTime(void); diff --git a/libctru/include/3ds/romfs.h b/libctru/include/3ds/romfs.h index 0dc5789..5f5dab0 100644 --- a/libctru/include/3ds/romfs.h +++ b/libctru/include/3ds/romfs.h @@ -1,35 +1,59 @@ +/** + * @file romfs.h + * @brief RomFS driver. + */ #pragma once #include <3ds/types.h> +//! RomFS header. typedef struct { - u32 headerSize; - u32 dirHashTableOff, dirHashTableSize; - u32 dirTableOff, dirTableSize; - u32 fileHashTableOff, fileHashTableSize; - u32 fileTableOff, fileTableSize; - u32 fileDataOff; + u32 headerSize; ///< Size of the header. + u32 dirHashTableOff; ///< Offset of the directory hash table. + u32 dirHashTableSize; ///< Size of the directory hash table. + u32 dirTableOff; ///< Offset of the directory table. + u32 dirTableSize; ///< Size of the directory table. + u32 fileHashTableOff; ///< Offset of the file hash table. + u32 fileHashTableSize; ///< Size of the file hash table. + u32 fileTableOff; ///< Offset of the file table. + u32 fileTableSize; ///< Size of the file table. + u32 fileDataOff; ///< Offset of the file data. } romfs_header; +//! RomFS directory. typedef struct { - u32 parent, sibling; - u32 childDir, childFile; - u32 nextHash; - u32 nameLen; - u16 name[]; + u32 parent; ///< Offset of the parent directory. + u32 sibling; ///< Offset of the next sibling directory. + u32 childDir; ///< Offset of the first child directory. + u32 childFile; ///< Offset of the first file. + u32 nextHash; ///< Directory hash table pointer. + u32 nameLen; ///< Name length. + u16 name[]; ///< Name. (UTF-16) } romfs_dir; +//! RomFS file. typedef struct { - u32 parent, sibling; - u64 dataOff, dataSize; - u32 nextHash; - u32 nameLen; - u16 name[]; + u32 parent; ///< Offset of the parent directory. + u32 sibling; ///< Offset of the next sibling file. + u64 dataOff; ///< Offset of the file's data. + u64 dataSize; ///< Length of the file's data. + u32 nextHash; ///< File hash table pointer. + u32 nameLen; ///< Name length. + u16 name[]; ///< Name. (UTF-16) } romfs_file; +//! Initializes the RomFS driver. Result romfsInit(void); + +/** + * @brief Initializes the RomFS driver from a RomFS file. + * @param file Handle of the RomFS file. + * @param offset Offset of the RomFS within the file. + */ Result romfsInitFromFile(Handle file, u32 offset); + +//! Exits the RomFS driver. Result romfsExit(void); diff --git a/libctru/include/3ds/sdmc.h b/libctru/include/3ds/sdmc.h index f8513b8..9606510 100644 --- a/libctru/include/3ds/sdmc.h +++ b/libctru/include/3ds/sdmc.h @@ -6,12 +6,8 @@ #include <3ds/types.h> -/** - * @brief Initializes the SDMC driver. - */ +//! Initializes the SDMC driver. Result sdmcInit(void); -/** - * @brief Exits the SDMC driver. - */ +//! Exits the SDMC driver. Result sdmcExit(void); diff --git a/libctru/include/3ds/srv.h b/libctru/include/3ds/srv.h index 7f1f2be..6b2a8e2 100644 --- a/libctru/include/3ds/srv.h +++ b/libctru/include/3ds/srv.h @@ -1,14 +1,65 @@ +/** + * @file srv.h + * @brief Service API. + */ #pragma once +//! Initializes the service API. Result srvInit(void); + +//! Exits the service API. Result srvExit(void); + +/** + * @brief Gets the current service API session handle. + * @return The current service API session handle. + */ Handle *srvGetSessionHandle(void); + +//! Registers the current process as a client to the service API. Result srvRegisterClient(void); + +/** + * @brief Retrieves a service handle, bypassing the handle list. + * @param out Pointer to write the handle to. + * @param name Name of the service. + */ Result srvGetServiceHandleDirect(Handle* out, const char* name); + +/** + * @brief Retrieves a service handle. + * @param out Pointer to write the handle to. + * @param name Name of the service. + */ Result srvGetServiceHandle(Handle* out, const char* name); + +/** + * @brief Registers the current process as a service. + * @param out Pointer to write the service handle to. + * @param name Name of the service. + * @param maxSessions Maximum number of sessions the service can handle. + */ Result srvRegisterService(Handle* out, const char* name, int maxSessions); + +/** + * @brief Unregisters the current process as a service. + * @param name Name of the service. + */ Result srvUnregisterService(const char* name); +//! Initializes the srv:pm port. Result srvPmInit(void); + +/** + * @brief Registers a process with srv:pm. + * @param procid ID of the process to register. + * @param count Number of services to register access to. + * @param serviceaccesscontrol Service access permissions of the process. + */ Result srvRegisterProcess(u32 procid, u32 count, void *serviceaccesscontrol); + +/** + * @brief Unregisters a process with srv:pm. + * @param procid ID of the process to unregister. + */ Result srvUnregisterProcess(u32 procid); diff --git a/libctru/include/3ds/svc.h b/libctru/include/3ds/svc.h index 747a7e2..ba81b0b 100644 --- a/libctru/include/3ds/svc.h +++ b/libctru/include/3ds/svc.h @@ -2,7 +2,6 @@ * @file svc.h * @brief Syscall wrappers. */ - #pragma once #include "types.h" @@ -27,54 +26,55 @@ typedef enum { MEMOP_UNMAP = 5, ///< Mirror unmapping MEMOP_PROT = 6, ///< Change protection - MEMOP_REGION_APP = 0x100, - MEMOP_REGION_SYSTEM = 0x200, - MEMOP_REGION_BASE = 0x300, + MEMOP_REGION_APP = 0x100, ///< APPLICATION memory region. + MEMOP_REGION_SYSTEM = 0x200, ///< SYSTEM memory region. + MEMOP_REGION_BASE = 0x300, ///< BASE memory region. MEMOP_OP_MASK = 0xFF, MEMOP_REGION_MASK = 0xF00, MEMOP_LINEAR_FLAG = 0x10000, ///< Flag for linear memory operations - MEMOP_ALLOC_LINEAR = MEMOP_LINEAR_FLAG | MEMOP_ALLOC, - + MEMOP_ALLOC_LINEAR = MEMOP_LINEAR_FLAG | MEMOP_ALLOC, ///< Allocates linear memory. } MemOp; +//! The state of a memory block. typedef enum { - MEMSTATE_FREE = 0, - MEMSTATE_RESERVED = 1, - MEMSTATE_IO = 2, - MEMSTATE_STATIC = 3, - MEMSTATE_CODE = 4, - MEMSTATE_PRIVATE = 5, - MEMSTATE_SHARED = 6, - MEMSTATE_CONTINUOUS = 7, - MEMSTATE_ALIASED = 8, - MEMSTATE_ALIAS = 9, - MEMSTATE_ALIASCODE = 10, - MEMSTATE_LOCKED = 11 + MEMSTATE_FREE = 0, ///< Free memory + MEMSTATE_RESERVED = 1, ///< Reserved memory + MEMSTATE_IO = 2, ///< I/O memory + MEMSTATE_STATIC = 3, ///< Static memory + MEMSTATE_CODE = 4, ///< Code memory + MEMSTATE_PRIVATE = 5, ///< Private memory + MEMSTATE_SHARED = 6, ///< Shared memory + MEMSTATE_CONTINUOUS = 7, ///< Continuous memory + MEMSTATE_ALIASED = 8, ///< Aliased memory + MEMSTATE_ALIAS = 9, ///< Alias memory + MEMSTATE_ALIASCODE = 10, ///< Aliased code memory + MEMSTATE_LOCKED = 11 ///< Locked memory } MemState; -/** - * @brief Memory permission flags - */ +//! Memory permission flags typedef enum { - MEMPERM_READ = 1, - MEMPERM_WRITE = 2, - MEMPERM_EXECUTE = 4, - MEMPERM_DONTCARE = 0x10000000 + MEMPERM_READ = 1, ///< Readable + MEMPERM_WRITE = 2, ///< Writable + MEMPERM_EXECUTE = 4, ///< Executable + MEMPERM_DONTCARE = 0x10000000 ///< Don't care } MemPerm; +//! Memory information. typedef struct { - u32 base_addr; - u32 size; - u32 perm; ///< See @ref MemPerm - u32 state; ///< See @ref MemState + u32 base_addr; ///< Base address. + u32 size; ///< Size. + u32 perm; ///< Memory permissions. See @ref MemPerm + u32 state; ///< Memory state. See @ref MemState } MemInfo; +//! Memory page information. typedef struct { - u32 flags; + u32 flags; ///< Page flags. } PageInfo; +//! Arbitration modes. typedef enum { ARBITRATION_SIGNAL = 0, ///< Signal #value threads for wake-up. ARBITRATION_WAIT_IF_LESS_THAN = 1, ///< If the memory at the address is strictly lower than #value, then wait for signal. @@ -91,8 +91,9 @@ typedef enum { ///@name Multithreading ///@{ +//! Types of thread info. typedef enum { - THREADINFO_TYPE_UNKNOWN + THREADINFO_TYPE_UNKNOWN ///< Unknown. } ThreadInfoType; /// Pseudo handle for the current thread @@ -103,127 +104,148 @@ typedef enum { ///@name Debugging ///@{ + +//! Reasons for a process event. typedef enum { - REASON_CREATE = 1, - REASON_ATTACH = 2 + REASON_CREATE = 1, ///< Process created. + REASON_ATTACH = 2 ///< Process attached. } ProcessEventReason; +//! Event relating to a process. typedef struct { - u64 program_id; - u8 process_name[8]; - u32 process_id; - u32 reason; ///< See @ref ProcessEventReason + u64 program_id; ///< ID of the program. + u8 process_name[8]; ///< Name of the process. + u32 process_id; ///< ID of the process. + u32 reason; ///< Reason for the event. See @ref ProcessEventReason } ProcessEvent; +//! Reasons for an exit process event. typedef enum { - EXITPROCESS_EVENT_NONE = 0, - EXITPROCESS_EVENT_TERMINATE = 1, - EXITPROCESS_EVENT_UNHANDLED_EXCEPTION = 2 + EXITPROCESS_EVENT_NONE = 0, ///< No reason. + EXITPROCESS_EVENT_TERMINATE = 1, ///< Process terminated. + EXITPROCESS_EVENT_UNHANDLED_EXCEPTION = 2 ///< Unhandled exception occurred. } ExitProcessEventReason; +//! Event relating to the exiting of a process. typedef struct { - u32 reason; ///< See @ref ExitProcessEventReason + u32 reason; ///< Reason for exiting. See @ref ExitProcessEventReason } ExitProcessEvent; +//! Event relating to the creation of a thread. typedef struct { - u32 creator_thread_id; - u32 base_addr; - u32 entry_point; + u32 creator_thread_id; ///< ID of the creating thread. + u32 base_addr; ///< Base address. + u32 entry_point; ///< Entry point of the thread. } CreateThreadEvent; +//! Reasons for an exit thread event. typedef enum { - EXITTHREAD_EVENT_NONE = 0, - EXITTHREAD_EVENT_TERMINATE = 1, - EXITTHREAD_EVENT_UNHANDLED_EXC = 2, - EXITTHREAD_EVENT_TERMINATE_PROCESS = 3 + EXITTHREAD_EVENT_NONE = 0, ///< No reason. + EXITTHREAD_EVENT_TERMINATE = 1, ///< Thread terminated. + EXITTHREAD_EVENT_UNHANDLED_EXC = 2, ///< Unhandled exception occurred. + EXITTHREAD_EVENT_TERMINATE_PROCESS = 3 ///< Process terminated. } ExitThreadEventReason; +//! Event relating to the exiting of a thread. typedef struct { - u32 reason; ///< See @ref ExitThreadEventReason + u32 reason; ///< Reason for exiting. See @ref ExitThreadEventReason } ExitThreadEvent; +//! Reasons for a user break. typedef enum { - USERBREAK_PANIC = 0, - USERBREAK_ASSERT = 1, - USERBREAK_USER = 2 + USERBREAK_PANIC = 0, ///< Panic. + USERBREAK_ASSERT = 1, ///< Assertion failed. + USERBREAK_USER = 2 ///< User related. } UserBreakType; +//! Reasons for an exception event. typedef enum { - EXC_EVENT_UNDEFINED_INSTRUCTION = 0, ///< arg: (None) - EXC_EVENT_UNKNOWN1 = 1, ///< arg: (None) - EXC_EVENT_UNKNOWN2 = 2, ///< arg: address - EXC_EVENT_UNKNOWN3 = 3, ///< arg: address - EXC_EVENT_ATTACH_BREAK = 4, ///< arg: (None) - EXC_EVENT_BREAKPOINT = 5, ///< arg: (None) - EXC_EVENT_USER_BREAK = 6, ///< arg: @ref UserBreakType - EXC_EVENT_DEBUGGER_BREAK = 7, ///< arg: (None) - EXC_EVENT_UNDEFINED_SYSCALL = 8 ///< arg: attempted syscall + EXC_EVENT_UNDEFINED_INSTRUCTION = 0, ///< Undefined instruction. arg: (None) + EXC_EVENT_UNKNOWN1 = 1, ///< Unknown. arg: (None) + EXC_EVENT_UNKNOWN2 = 2, ///< Unknown. arg: address + EXC_EVENT_UNKNOWN3 = 3, ///< Unknown. arg: address + EXC_EVENT_ATTACH_BREAK = 4, ///< Attached break. arg: (None) + EXC_EVENT_BREAKPOINT = 5, ///< Breakpoint reached. arg: (None) + EXC_EVENT_USER_BREAK = 6, ///< User break occurred. arg: @ref UserBreakType + EXC_EVENT_DEBUGGER_BREAK = 7, ///< Debugger break occurred. arg: (None) + EXC_EVENT_UNDEFINED_SYSCALL = 8 ///< Undefined syscall. arg: attempted syscall } ExceptionEventType; +//! Event relating to exceptions. typedef struct { - u32 type; ///< See @ref ExceptionEventType - u32 address; - u32 argument; ///< See @ref ExceptionEventType + u32 type; ///< Type of event. See @ref ExceptionEventType + u32 address; ///< Address of the exception. + u32 argument; ///< Event argument. See @ref ExceptionEventType } ExceptionEvent; +//! Event relating to the scheduler. typedef struct { - u64 clock_tick; + u64 clock_tick; ///< Clock tick that the event occurred. } SchedulerInOutEvent; +//! Event relating to syscalls. typedef struct { - u64 clock_tick; - u32 syscall; + u64 clock_tick; ///< Clock tick that the event occurred. + u32 syscall; ///< Syscall sent/received. } SyscallInOutEvent; +//! Event relating to debug output. typedef struct { - u32 string_addr; - u32 string_size; + u32 string_addr; ///< Address of the outputted string. + u32 string_size; ///< Size of the outputted string. } OutputStringEvent; +//! Event relating to the mapping of memory. typedef struct { - u32 mapped_addr; - u32 mapped_size; - u32 memperm; - u32 memstate; + u32 mapped_addr; ///< Mapped address. + u32 mapped_size; ///< Mapped size. + u32 memperm; ///< Memory permissions. See @ref MemPerm + u32 memstate; ///< Memory state. See @ref MemState } MapEvent; +//! Debug event type. typedef enum { - DBG_EVENT_PROCESS = 0, - DBG_EVENT_CREATE_THREAD = 1, - DBG_EVENT_EXIT_THREAD = 2, - DBG_EVENT_EXIT_PROCESS = 3, - DBG_EVENT_EXCEPTION = 4, - DBG_EVENT_DLL_LOAD = 5, - DBG_EVENT_DLL_UNLOAD = 6, - DBG_EVENT_SCHEDULE_IN = 7, - DBG_EVENT_SCHEDULE_OUT = 8, - DBG_EVENT_SYSCALL_IN = 9, - DBG_EVENT_SYSCALL_OUT = 10, - DBG_EVENT_OUTPUT_STRING = 11, - DBG_EVENT_MAP = 12 + DBG_EVENT_PROCESS = 0, ///< Process event. + DBG_EVENT_CREATE_THREAD = 1, ///< Thread creation event. + DBG_EVENT_EXIT_THREAD = 2, ///< Thread exit event. + DBG_EVENT_EXIT_PROCESS = 3, ///< Process exit event. + DBG_EVENT_EXCEPTION = 4, ///< Exception event. + DBG_EVENT_DLL_LOAD = 5, ///< DLL load event. + DBG_EVENT_DLL_UNLOAD = 6, ///< DLL unload event. + DBG_EVENT_SCHEDULE_IN = 7, ///< Schedule in event. + DBG_EVENT_SCHEDULE_OUT = 8, ///< Schedule out event. + DBG_EVENT_SYSCALL_IN = 9, ///< Syscall in event. + DBG_EVENT_SYSCALL_OUT = 10, ///< Syscall out event. + DBG_EVENT_OUTPUT_STRING = 11, ///< Output string event. + DBG_EVENT_MAP = 12 ///< Map event. } DebugEventType; +//! Information about a debug event. typedef struct { - u32 type; ///< See @ref DebugEventType - u32 thread_id; - u32 unknown[2]; + u32 type; ///< Type of event. See @ref DebugEventType + u32 thread_id; ///< ID of the thread. + u32 unknown[2]; ///< Unknown data. union { - ProcessEvent process; - CreateThreadEvent create_thread; - ExitThreadEvent exit_thread; - ExitProcessEvent exit_process; - ExceptionEvent exception; + ProcessEvent process; ///< Process event data. + CreateThreadEvent create_thread; ///< Thread creation event data. + ExitThreadEvent exit_thread; ///< Thread exit event data. + ExitProcessEvent exit_process; ///< Process exit event data. + ExceptionEvent exception; ///< Exception event data. /* TODO: DLL_LOAD */ /* TODO: DLL_UNLOAD */ - SchedulerInOutEvent scheduler; - SyscallInOutEvent syscall; - OutputStringEvent output_string; - MapEvent map; + SchedulerInOutEvent scheduler; ///< Schedule in/out event data. + SyscallInOutEvent syscall; ///< Syscall in/out event data. + OutputStringEvent output_string; ///< Output string event data. + MapEvent map; ///< Map event data. }; } DebugEventInfo; ///@} +/** + * @brief Gets the thread local storage buffer. + * @return The thread local storage bufger. + */ static inline void* getThreadLocalStorage(void) { void* ret; @@ -231,11 +253,19 @@ static inline void* getThreadLocalStorage(void) return ret; } +/** + * @brief Gets the thread command buffer. + * @return The thread command bufger. + */ static inline u32* getThreadCommandBuffer(void) { return (u32*)((u8*)getThreadLocalStorage() + 0x80); } +/** + * @brief Gets the thread static buffer. + * @return The thread static bufger. + */ static inline u32* getThreadStaticBuffers(void) { return (u32*)((u8*)getThreadLocalStorage() + 0x180); @@ -243,7 +273,6 @@ static inline u32* getThreadStaticBuffers(void) ///@name Memory management ///@{ - /** * @brief Controls memory mapping * @param[out] addr_out The virtual address resulting from the operation. Usually the same as addr0. @@ -281,55 +310,183 @@ Result svcControlProcessMemory(Handle process, u32 addr0, u32 addr1, u32 size, u /** * @brief Creates a block of shared memory - * @param memblock Pointer to store the handle of the block + * @param[out] memblock Pointer to store the handle of the block * @param addr Address of the memory to map, page-aligned. So its alignment must be 0x1000. * @param size Size of the memory to map, a multiple of 0x1000. * @param my_perm Memory permissions for the current process - * @param my_perm Memory permissions for the other processes + * @param other_perm Memory permissions for the other processes * * @note The shared memory block, and its rights, are destroyed when the handle is closed. */ Result svcCreateMemoryBlock(Handle* memblock, u32 addr, u32 size, MemPerm my_perm, MemPerm other_perm); + +/** + * @brief Maps a block of shared memory + * @param memblock Handle of the block + * @param addr Address of the memory to map, page-aligned. So its alignment must be 0x1000. + * @param my_perm Memory permissions for the current process + * @param other_perm Memory permissions for the other processes + * + * @note The shared memory block, and its rights, are destroyed when the handle is closed. + */ Result svcMapMemoryBlock(Handle memblock, u32 addr, MemPerm my_perm, MemPerm other_perm); + +/** + * @brief Maps a block of process memory. + * @param process Handle of the process. + * @param startAddr Start address of the memory to map. + * @param endAddr End address of the memory to map. + */ Result svcMapProcessMemory(Handle process, u32 startAddr, u32 endAddr); + +/** + * @brief Unmaps a block of process memory. + * @param process Handle of the process. + * @param startAddr Start address of the memory to unmap. + * @param endAddr End address of the memory to unmap. + */ Result svcUnmapProcessMemory(Handle process, u32 startAddr, u32 endAddr); + +/** + * @brief Unmaps a block of shared memory + * @param memblock Handle of the block + * @param addr Address of the memory to unmap, page-aligned. So its alignment must be 0x1000. + */ Result svcUnmapMemoryBlock(Handle memblock, u32 addr); -Result svcStartInterProcessDma(Handle* dma, Handle dstProcess, void* dst, Handle srcProcess, const void* src, u32 size, void* dmaConfig); -Result svcStopDma(Handle dma); -Result svcGetDmaState(void* dmaState, Handle dma); /** - * @brief Memory information query - * @param addr Virtual memory address + * @brief Begins an inter-process DMA. + * @param[out] dma Pointer to output the handle of the DMA to. + * @param dstProcess Destination process. + * @param dst Buffer to write data to. + * @param srcprocess Source process. + * @param src Buffer to read data from. + * @param size Size of the data to DMA. + * @param dmaConfig DMA configuration data. + */ +Result svcStartInterProcessDma(Handle* dma, Handle dstProcess, void* dst, Handle srcProcess, const void* src, u32 size, void* dmaConfig); + +/** + * @brief Terminates an inter-process DMA. + * @param dma Handle of the DMA. + */ +Result svcStopDma(Handle dma); + +/** + * @brief Gets the state of an inter-process DMA. + * @param[out] dmaState Pointer to output the state of the DMA to. + * @param dma Handle of the DMA. + */ +Result svcGetDmaState(void* dmaState, Handle dma); + +/** + * @brief Queries memory information. + * @param[out] info Pointer to output memory info to. + * @param out Pointer to output page info to. + * @param addr Virtual memory address to query. */ Result svcQueryMemory(MemInfo* info, PageInfo* out, u32 addr); + +/** + * @brief Queries process memory information. + * @param[out] info Pointer to output memory info to. + * @param[out] out Pointer to output page info to. + * @param process Process to query memory from. + * @param addr Virtual memory address to query. + */ Result svcQueryProcessMemory(MemInfo* info, PageInfo* out, Handle process, u32 addr); - +/** + * @brief Invalidates a process's data cache. + * @param process Handle of the process. + * @param addr Address to invalidate. + * @param size Size of the memory to invalidate. + */ Result svcInvalidateProcessDataCache(Handle process, void* addr, u32 size); + +/** + * @brief Flushes a process's data cache. + * @param process Handle of the process. + * @param addr Address to flush. + * @param size Size of the memory to flush. + */ Result svcFlushProcessDataCache(Handle process, void const* addr, u32 size); +/** + * @brief Reads from a process's memory. + * @param buffer Buffer to read data to. + * @param debug Debug handle of the process. + * @param addr Address to read from. + * @param size Size of the memory to read. + */ Result svcReadProcessMemory(void* buffer, Handle debug, u32 addr, u32 size); + +/** + * @brief Writes to a process's memory. + * @param debug Debug handle of the process. + * @param buffer Buffer to write data from. + * @param addr Address to write to. + * @param size Size of the memory to write. + */ Result svcWriteProcessMemory(Handle debug, const void* buffer, u32 addr, u32 size); ///@} ///@name Process management ///@{ - /** * @brief Gets the handle of a process. * @param[out] process The handle of the process * @param processId The ID of the process to open */ Result svcOpenProcess(Handle* process, u32 processId); + +//! Exits the current process. void svcExitProcess() __attribute__((noreturn)); + +/** + * @brief Terminates a process. + * @param process Handle of the process to terminate. + */ Result svcTerminateProcess(Handle process); +/** + * @brief Gets information about a process. + * @param[out] out Pointer to output process info to. + * @param process Handle of the process to get information about. + * @param type Type of information to retreieve. + */ Result svcGetProcessInfo(s64* out, Handle process, u32 type); + +/** + * @brief Gets the ID of a process. + * @param[out] out Pointer to output the process ID to. + * @param handle Handle of the process to get the ID of. + */ Result svcGetProcessId(u32 *out, Handle handle); + +/** + * @brief Gets a list of running processes. + * @param[out] processCount Pointer to output the process count to. + * @param[out] processIds Pointer to output the process IDs to. + * @param processIdMaxCount Maximum number of process IDs. + */ Result svcGetProcessList(s32* processCount, u32* processIds, s32 processIdMaxCount); + +/** + * @brief Creates a port. + * @param[out] portServer Pointer to output the port server handle to. + * @param[out] portClient Pointer to output the port client handle to. + * @param name Name of the port. + * @param maxSessions Maximum number of sessions that can connect to the port. + */ Result svcCreatePort(Handle* portServer, Handle* portClient, const char* name, s32 maxSessions); + +/** + * @brief Connects to a port. + * @param[out] out Pointer to output the port handle to. + * @param portName Name of the port. + */ Result svcConnectToPort(volatile Handle* out, const char* portName); ///@} @@ -378,9 +535,7 @@ void svcExitThread(void) __attribute__((noreturn)); */ void svcSleepThread(s64 ns); -/** - * @brief Retrieves the priority of a thread. - */ +//! Retrieves the priority of a thread. Result svcGetThreadPriority(s32 *out, Handle handle); /** @@ -390,9 +545,35 @@ Result svcGetThreadPriority(s32 *out, Handle handle); * Low values gives the thread higher priority. */ Result svcSetThreadPriority(Handle thread, s32 prio); + +/** + * @brief Gets a thread's affinity mask. + * @param[out] affinitymask Pointer to output the affinity masks to. + * @param thread Handle of the thread. + * @param processorcount Number of processors. + */ Result svcGetThreadAffinityMask(u8* affinitymask, Handle thread, s32 processorcount); + +/** + * @brief Sets a thread's affinity mask. + * @param thread Handle of the thread. + * @param affinitymask Pointer to retreive the affinity masks from. + * @param processorcount Number of processors. + */ Result svcSetThreadAffinityMask(Handle thread, u8* affinitymask, s32 processorcount); + +/** + * @brief Gets a thread's ideal processor. + * @param[out] processorid Pointer to output the ID of the thread's ideal processor to. + * @param thread Handle of the thread. + */ Result svcGetThreadIdealProcessor(s32* processorid, Handle thread); + +/** + * Sets a thread's ideal processor. + * @param thread Handle of the thread. + * @param processorid ID of the thread's ideal processor. + */ Result svcSetThreadIdealProcessor(Handle thread, s32 processorid); /** @@ -402,12 +583,16 @@ Result svcSetThreadIdealProcessor(Handle thread, s32 processorid); s32 svcGetProcessorID(); /** - * @param out The thread ID of the thread @p handle. + * @brief Gets the ID of a thread. + * @param[out] out Pointer to output the thread ID of the thread @p handle to. + * @param handle Handle of the thread. */ Result svcGetThreadId(u32 *out, Handle handle); /** - * @param out The process ID of the thread @p handle. + * @brief Gets the process ID of a thread. + * @param[out] out Pointer to output the process ID of the thread @p handle to. + * @param handle Handle of the thread. * @sa svcOpenProcess */ Result svcGetProcessIdOfThread(u32 *out, Handle handle); @@ -424,21 +609,74 @@ Result svcGetThreadInfo(s64* out, Handle thread, ThreadInfoType type); ///@name Synchronization ///@{ +/** + * @brief Creates a mutex. + * @param[out] mutex Pointer to output the handle of the created mutex to. + * @param initially_locked Whether the mutex should be initially locked. + */ Result svcCreateMutex(Handle* mutex, bool initially_locked); + +/** + * @brief Releases a mutex. + * @param handle Handle of the mutex. + */ Result svcReleaseMutex(Handle handle); +/** + * @brief Creates a semaphore. + * @param[out] semaphore Pointer to output the handle of the created semaphore to. + * @param initial_count Initial count of the semaphore. + * @param max_count Maximum count of the semaphore. + */ Result svcCreateSemaphore(Handle* semaphore, s32 initial_count, s32 max_count); + +/** + * @brief Releases a semaphore. + * @param[out] count Pointer to output the current count of the semaphore to. + * @param semaphore Handle of the semaphore. + * @param release_count Number to increase the semaphore count by. + */ Result svcReleaseSemaphore(s32* count, Handle semaphore, s32 release_count); +/** + * @brief Creates an event handle. + * @param[out] event Pointer to output the created event handle to. + * @param reset_type Type of reset the event uses. + */ Result svcCreateEvent(Handle* event, u8 reset_type); + +/** + * @brief Signals an event. + * @param handle Handle of the event to signal. + */ Result svcSignalEvent(Handle handle); + +/** + * @brief Clears an event. + * @param handle Handle of the event to clear. + */ Result svcClearEvent(Handle handle); +/** + * @brief Waits for synchronization on a handle. + * @param handle Handle to wait on. + * @param nanoseconds Maximum nanoseconds to wait for. + */ Result svcWaitSynchronization(Handle handle, s64 nanoseconds); + +/** + * @brief Waits for synchronization on multiple handles. + * @param[out] out Pointer to output the index of the synchronized handle to. + * @param handles Handles to wait on. + * @param handles_num Number of handles. + * @param wait_all Whether to wait for synchronization on all handles. + * @param nanoseconds Maximum nanoseconds to wait for. + */ Result svcWaitSynchronizationN(s32* out, Handle* handles, s32 handles_num, bool wait_all, s64 nanoseconds); /** * @brief Creates an address arbiter + * @param[out] mutex Pointer to output the handle of the created address arbiter to. * @sa svcArbitrateAddress */ Result svcCreateAddressArbiter(Handle *arbiter); @@ -462,40 +700,151 @@ Result svcCreateAddressArbiter(Handle *arbiter); */ Result svcArbitrateAddress(Handle arbiter, u32 addr, ArbitrationType type, s32 value, s64 nanoseconds); +/** + * @brief Sends a synchronized request to a session handle. + * @param session Handle of the session. + */ Result svcSendSyncRequest(Handle session); + +/** + * @brief Accepts a session. + * @param[out] session Pointer to output the created session handle to. + * @param port Handle of the port to accept a session from. + */ Result svcAcceptSession(Handle* session, Handle port); + +/** + * @brief Replies to and receives a new request. + * @param index Pointer to the index of the request. + * @param handles Session handles to receive requests from. + * @param handleCount Number of handles. + * @param replyTarget Handle of the session to reply to. + */ Result svcReplyAndReceive(s32* index, Handle* handles, s32 handleCount, Handle replyTarget); ///@} ///@name Time ///@{ +/** + * @brief Creates a timer. + * @param[out] timer Pointer to output the handle of the created timer to. + * @param reset_type Type of reset to perform on the timer. + */ Result svcCreateTimer(Handle* timer, u8 reset_type); + +/** + * @brief Sets a timer. + * @param timer Handle of the timer to set. + * @param initial Initial value of the timer. + * @param interval Interval of the timer. + */ Result svcSetTimer(Handle timer, s64 initial, s64 interval); + +/** + * @brief Cancels a timer. + * @param timer Handle of the timer to cancel. + */ Result svcCancelTimer(Handle timer); + +/** + * @brief Clears a timer. + * @param timer Handle of the timer to clear. + */ Result svcClearTimer(Handle timer); + +/** + * @brief Gets the current system tick. + * @return The current system tick. + */ u64 svcGetSystemTick(); ///@} ///@name System ///@{ +/** + * @brief Closes a handle. + * @param handle Handle to close. + */ Result svcCloseHandle(Handle handle); + +/** + * @brief Duplicates a handle. + * @param[out] out Pointer to output the duplicated handle to. + * @param original Handle to duplicate. + */ Result svcDuplicateHandle(Handle* out, Handle original); + +/** + * @brief Gets the system info. + * @param[out] out Pointer to output the system info to. + * @param type Type of system info to retreive. + * @param param Parameter clarifying the system info type. + */ Result svcGetSystemInfo(s64* out, u32 type, s32 param); + +/** + * @brief Sets the current kernel state. + * @param type Type of state to set. + * @param param0 First parameter of the state. + * @param param1 Second parameter of the state. + * @param param2 Third parameter of the state. + */ Result svcKernelSetState(u32 type, u32 param0, u32 param1, u32 param2); ///@} ///@name Debugging ///@{ +/** + * @brief Breaks execution. + * @param breakReason Reason for breaking. + */ void svcBreak(UserBreakType breakReason); + +/** + * @brief Outputs a debug string. + * @param str String to output. + * @param length Length of the string to output. + */ Result svcOutputDebugString(const char* str, int length); +/** + * @brief Creates a debug handle for an active process. + * @param[out] debug Pointer to output the created debug handle to. + * @param processId ID of the process to debug. + */ Result svcDebugActiveProcess(Handle* debug, u32 processId); + +/** + * @brief Breaks a debugged process. + * @param debug Debug handle of the process. + */ Result svcBreakDebugProcess(Handle debug); + +/** + * @brief Terminates a debugged process. + * @param debug Debug handle of the process. + */ Result svcTerminateDebugProcess(Handle debug); + +/** + * @brief Gets the current debug event of a debugged process. + * @param[out] info Pointer to output the debug event information to. + * @param debug Debug handle of the process. + */ Result svcGetProcessDebugEvent(DebugEventInfo* info, Handle debug); + +/** + * @brief Continues the current debug event of a debugged process. + * @param debug Debug handle of the process. + * @param flags Flags to continue with. + */ Result svcContinueDebugEvent(Handle debug, u32 flags); ///@} +/** + * @brief Executes a function in kernel mode. + * @param callback Function to execute. + */ Result svcBackdoor(s32 (*callback)(void)); diff --git a/libctru/include/3ds/synchronization.h b/libctru/include/3ds/synchronization.h index e235e08..9d61ae1 100644 --- a/libctru/include/3ds/synchronization.h +++ b/libctru/include/3ds/synchronization.h @@ -1,19 +1,31 @@ +/** + * @file synchronization.h + * @brief Provides synchronization locks. + */ #pragma once +//! A light lock. typedef s32 LightLock; +//! A recursive lock. typedef struct { - LightLock lock; - u32 thread_tag; - u32 counter; + LightLock lock; ///< Inner light lock. + u32 thread_tag; ///< Tag of the thread that currently has the lock. + u32 counter; ///< Lock count. } RecursiveLock; +//! Performs a clrex operation. static inline void __clrex(void) { __asm__ __volatile__("clrex"); } +/** + * @brief Performs a ldrex operation. + * @param addr Address to perform the operation on. + * @return The resulting value. + */ static inline s32 __ldrex(s32* addr) { s32 val; @@ -21,6 +33,12 @@ static inline s32 __ldrex(s32* addr) return val; } +/** + * @brief Performs a strex operation. + * @param addr Address to perform the operation on. + * @param val Value to store. + * @return Whether the operation was successful. + */ static inline bool __strex(s32* addr, s32 val) { bool res; @@ -28,10 +46,38 @@ static inline bool __strex(s32* addr, s32 val) return res; } +/** + * @brief Initializes a light lock. + * @param lock Pointer to the lock. + */ void LightLock_Init(LightLock* lock); + +/** + * @brief Locks a light lock. + * @param lock Pointer to the lock. + */ void LightLock_Lock(LightLock* lock); + +/** + * @brief Unlocks a light lock. + * @param lock Pointer to the lock. + */ void LightLock_Unlock(LightLock* lock); +/** + * @brief Initializes a recursive lock. + * @param lock Pointer to the lock. + */ void RecursiveLock_Init(RecursiveLock* lock); + +/** + * @brief Locks a recursive lock. + * @param lock Pointer to the lock. + */ void RecursiveLock_Lock(RecursiveLock* lock); + +/** + * @brief Unlocks a recursive lock. + * @param lock Pointer to the lock. + */ void RecursiveLock_Unlock(RecursiveLock* lock); diff --git a/libctru/include/3ds/types.h b/libctru/include/3ds/types.h index 5cb67c2..5a5c45a 100644 --- a/libctru/include/3ds/types.h +++ b/libctru/include/3ds/types.h @@ -1,46 +1,49 @@ -/* - types.h _ Various system types. -*/ - +/** + * @file types.h + * @brief Various system types. + */ #pragma once #include #include #include +//! The maximum value of a u64. #define U64_MAX UINT64_MAX +//! Possible media types. typedef enum { - mediatype_NAND, - mediatype_SDMC, - mediatype_GAMECARD, + mediatype_NAND, ///< NAND + mediatype_SDMC, ///< SDMC + mediatype_GAMECARD, ///< Game card } mediatypes_enum; -typedef uint8_t u8; -typedef uint16_t u16; -typedef uint32_t u32; -typedef uint64_t u64; +typedef uint8_t u8; ///< 8-bit unsigned integer +typedef uint16_t u16; ///< 16-bit unsigned integer +typedef uint32_t u32; ///< 32-bit unsigned integer +typedef uint64_t u64; ///< 64-bit unsigned integer -typedef int8_t s8; -typedef int16_t s16; -typedef int32_t s32; -typedef int64_t s64; +typedef int8_t s8; ///< 8-bit signed integer +typedef int16_t s16; ///< 16-bit signed integer +typedef int32_t s32; ///< 32-bit signed integer +typedef int64_t s64; ///< 64-bit signed integer -typedef volatile u8 vu8; -typedef volatile u16 vu16; -typedef volatile u32 vu32; -typedef volatile u64 vu64; +typedef volatile u8 vu8; ///< 8-bit volatile unsigned integer. +typedef volatile u16 vu16; ///< 16-bit volatile unsigned integer. +typedef volatile u32 vu32; ///< 32-bit volatile unsigned integer. +typedef volatile u64 vu64; ///< 64-bit volatile unsigned integer. -typedef volatile s8 vs8; -typedef volatile s16 vs16; -typedef volatile s32 vs32; -typedef volatile s64 vs64; +typedef volatile s8 vs8; ///< 8-bit volatile signed integer. +typedef volatile s16 vs16; ///< 16-bit volatile signed integer. +typedef volatile s32 vs32; ///< 32-bit volatile signed integer. +typedef volatile s64 vs64; ///< 64-bit volatile signed integer. -typedef u32 Handle; -typedef s32 Result; -typedef void (*ThreadFunc)(void *); +typedef u32 Handle; ///< Resource handle. +typedef s32 Result; ///< Function result. +typedef void (*ThreadFunc)(void *); ///< Thread entrypoint function. +//! Creates a bitmask from a bit number. #define BIT(n) (1U<<(n)) //! aligns a struct (and other types?) to m, making sure that the size of the struct is a multiple of m. diff --git a/libctru/include/3ds/util/rbtree.h b/libctru/include/3ds/util/rbtree.h index 73110f0..c78c6b2 100644 --- a/libctru/include/3ds/util/rbtree.h +++ b/libctru/include/3ds/util/rbtree.h @@ -1,74 +1,145 @@ +/** + * @file rbtree.h + * @brief Red-black trees. + */ #pragma once #include #include +//! brief Retreives an rbtree item. #define rbtree_item(ptr, type, member) \ ((type*)(((char*)ptr) - offsetof(type, member))) -typedef struct rbtree rbtree_t; -typedef struct rbtree_node rbtree_node_t; +typedef struct rbtree rbtree_t; ///< rbtree type. +typedef struct rbtree_node rbtree_node_t; ///< rbtree node type. -typedef void (*rbtree_node_destructor_t)(rbtree_node_t *Node); +typedef void (*rbtree_node_destructor_t)(rbtree_node_t *Node); ///< rbtree node destructor. typedef int (*rbtree_node_comparator_t)(const rbtree_node_t *lhs, - const rbtree_node_t *rhs); + const rbtree_node_t *rhs); ///< rbtree node comparator. + +//! An rbtree node. struct rbtree_node { - uintptr_t parent_color; - rbtree_node_t *child[2]; + uintptr_t parent_color; ///< Parent color. + rbtree_node_t *child[2]; ///< Node children. }; +//! An rbtree. struct rbtree { - rbtree_node_t *root; - rbtree_node_comparator_t comparator; - size_t size; + rbtree_node_t *root; ///< Root node. + rbtree_node_comparator_t comparator; ///< Node comparator. + size_t size; ///< Size. }; #ifdef __cplusplus extern "C" { #endif +/** + * @brief Initializes an rbtree. + * @param tree Pointer to the tree. + * @param comparator Comparator to use. + */ void rbtree_init(rbtree_t *tree, rbtree_node_comparator_t comparator); +/** + * @brief Gets whether an rbtree is empty + * @param tree Pointer to the tree. + * @return A non-zero value if the tree is not empty. + */ int rbtree_empty(const rbtree_t *tree); +/** + * @brief Gets the size of an rbtree. + * @param tree Pointer to the tree. + */ size_t rbtree_size(const rbtree_t *tree); +/** + * @brief Inserts a node into an rbtree. + * @param tree Pointer to the tree. + * @param node Pointer to the node. + * @return The inserted node. + */ __attribute__((warn_unused_result)) rbtree_node_t* rbtree_insert(rbtree_t *tree, rbtree_node_t *node); +/** + * @brief Inserts multiple nodes into an rbtree. + * @param tree Pointer to the tree. + * @param node Pointer to the nodes. + */ void rbtree_insert_multi(rbtree_t *tree, rbtree_node_t *node); +/** + * @brief Finds a node within an rbtree. + * @param tree Pointer to the tree. + * @param node Pointer to the node. + * @return The located node. + */ rbtree_node_t* rbtree_find(const rbtree_t *tree, const rbtree_node_t *node); +/** + * @brief Gets the minimum node of an rbtree. + * @param tree Pointer to the tree. + * @return The minimum node. + */ rbtree_node_t* rbtree_min(const rbtree_t *tree); +/** + * @brief Gets the maximum node of an rbtree. + * @param tree Pointer to the tree. + * @return The maximum node. + */ rbtree_node_t* rbtree_max(const rbtree_t *tree); +/** + * @brief Gets the next node from an rbtree node. + * @param node Pointer to the node. + * @return The next node. + */ rbtree_node_t* rbtree_node_next(const rbtree_node_t *node); +/** + * @brief Gets the previous node from an rbtree node. + * @param node Pointer to the node. + * @return The previous node. + */ rbtree_node_t* rbtree_node_prev(const rbtree_node_t *node); +/** + * @brief Removes a node from an rbtree. + * @param tree Pointer to the tree. + * @param node Pointer to the node. + * @param destructor Destructor to use when removing the node. + * @return The removed node. + */ rbtree_node_t* rbtree_remove(rbtree_t *tree, rbtree_node_t *node, rbtree_node_destructor_t destructor); +/** + * @brief Clears an rbtree. + * @param tree Pointer to the tree. + * @param destructor Destructor to use when clearing the tree's nodes. + */ void rbtree_clear(rbtree_t *tree, rbtree_node_destructor_t destructor); diff --git a/libctru/include/3ds/util/utf.h b/libctru/include/3ds/util/utf.h index eaaae25..3d4e3c8 100644 --- a/libctru/include/3ds/util/utf.h +++ b/libctru/include/3ds/util/utf.h @@ -1,3 +1,7 @@ +/** + * @file utf.h + * @brief UTF conversion functions. + */ #pragma once #include diff --git a/libctru/include/3ds/vram.h b/libctru/include/3ds/vram.h index c78c0de..4355b2f 100644 --- a/libctru/include/3ds/vram.h +++ b/libctru/include/3ds/vram.h @@ -4,8 +4,6 @@ */ #pragma once -// Functions for allocating/deallocating VRAM - /** * @brief Allocates a 0x80-byte aligned buffer. * @param size Size of the buffer to allocate. From d6962f21222c74b5890166943cbcad6f6165c5e0 Mon Sep 17 00:00:00 2001 From: Steven Smith Date: Sun, 4 Oct 2015 14:08:02 -0700 Subject: [PATCH 2/2] Doc consistency. --- libctru/include/3ds/console.h | 191 +++++++++++++------------- libctru/include/3ds/gfx.h | 2 +- libctru/include/3ds/gpu/gx.h | 4 +- libctru/include/3ds/ipc.h | 2 +- libctru/include/3ds/os.h | 13 +- libctru/include/3ds/romfs.h | 10 +- libctru/include/3ds/sdmc.h | 4 +- libctru/include/3ds/services/fs.h | 119 ++++++++-------- libctru/include/3ds/srv.h | 8 +- libctru/include/3ds/svc.h | 48 +++---- libctru/include/3ds/synchronization.h | 6 +- libctru/include/3ds/types.h | 12 +- libctru/include/3ds/util/rbtree.h | 6 +- libctru/include/3ds/util/utf.h | 20 +-- 14 files changed, 225 insertions(+), 220 deletions(-) diff --git a/libctru/include/3ds/console.h b/libctru/include/3ds/console.h index f635986..05aef1a 100644 --- a/libctru/include/3ds/console.h +++ b/libctru/include/3ds/console.h @@ -1,19 +1,16 @@ -/*! \file console.h - \brief 3ds stdio support. - -
-Provides stdio integration for printing to the 3DS screen as well as debug print -functionality provided by stderr. - -General usage is to initialize the console by: -consoleDemoInit() -or to customize the console usage by: -consoleInit() - +/** + * @file console.h + * @brief 3ds stdio support. + * + * Provides stdio integration for printing to the 3DS screen as well as debug print + * functionality provided by stderr. + * + * General usage is to initialize the console by: + * consoleDemoInit() + * or to customize the console usage by: + * consoleInit() */ - -#ifndef CONSOLE_H -#define CONSOLE_H +#pragma once #include <3ds/types.h> #include <3ds/gfx.h> @@ -22,73 +19,74 @@ consoleInit() extern "C" { #endif -typedef bool(* ConsolePrint)(void* con, int c); +/// A callback for printing a character. +typedef bool(*ConsolePrint)(void* con, int c); -//! a font struct for the console. +/// A font struct for the console. typedef struct ConsoleFont { - u8* gfx; //!< A pointer to the font graphics - u16 asciiOffset; //!< Offset to the first valid character in the font table - u16 numChars; //!< Number of characters in the font graphics + u8* gfx; ///< A pointer to the font graphics + u16 asciiOffset; ///< Offset to the first valid character in the font table + u16 numChars; ///< Number of characters in the font graphics }ConsoleFont; -/** \brief console structure used to store the state of a console render context. - -Default values from consoleGetDefault(); -
-PrintConsole defaultConsole =
-{
-	//Font:
-	{
-		(u8*)default_font_bin, //font gfx
-		0, //first ascii character in the set
-		128, //number of characters in the font set
-	},
-	0,0, //cursorX cursorY
-	0,0, //prevcursorX prevcursorY
-	40, //console width
-	30, //console height
-	0,  //window x
-	0,  //window y
-	32, //window width
-	24, //window height
-	3, //tab size
-	0, //font character offset
-	0,  //print callback
-	false //console initialized
-};
-
-*/ +/** + * @brief console structure used to store the state of a console render context. + * + * Default values from consoleGetDefault(); + * 
+ * PrintConsole defaultConsole =
+ * {
+ * 	//Font:
+ * 	{
+ * 		(u8*)default_font_bin, //font gfx
+ * 		0, //first ascii character in the set
+ * 		128, //number of characters in the font set
+ *	},
+ *	0,0, //cursorX cursorY
+ *	0,0, //prevcursorX prevcursorY
+ *	40, //console width
+ *	30, //console height
+ *	0,  //window x
+ *	0,  //window y
+ *	32, //window width
+ *	24, //window height
+ *	3, //tab size
+ *	0, //font character offset
+ *	0,  //print callback
+ *	false //console initialized
+ * };
+ *
+ */ typedef struct PrintConsole { - ConsoleFont font; //!< font of the console. + ConsoleFont font; ///< Font of the console. - u16 *frameBuffer; //!< framebuffer address. + u16 *frameBuffer; ///< Framebuffer address. - int cursorX; /*!< Current X location of the cursor (as a tile offset by default) */ - int cursorY; /*!< Current Y location of the cursor (as a tile offset by default) */ + int cursorX; ///< Current X location of the cursor (as a tile offset by default) + int cursorY; ///< Current Y location of the cursor (as a tile offset by default) - int prevCursorX; /*!< Internal state */ - int prevCursorY; /*!< Internal state */ + int prevCursorX; ///< Internal state + int prevCursorY; ///< Internal state - int consoleWidth; /*!< Width of the console hardware layer in characters */ - int consoleHeight; /*!< Height of the console hardware layer in characters */ + int consoleWidth; ///< Width of the console hardware layer in characters + int consoleHeight; ///< Height of the console hardware layer in characters - int windowX; /*!< Window X location in characters (not implemented) */ - int windowY; /*!< Window Y location in characters (not implemented) */ - int windowWidth; /*!< Window width in characters (not implemented) */ - int windowHeight; /*!< Window height in characters (not implemented) */ + int windowX; ///< Window X location in characters (not implemented) + int windowY; ///< Window Y location in characters (not implemented) + int windowWidth; ///< Window width in characters (not implemented) + int windowHeight; ///< Window height in characters (not implemented) - int tabSize; /*!< Size of a tab*/ - int fg; /*!< foreground color*/ - int bg; /*!< background color*/ - int flags; /*!< reverse/bright flags*/ + int tabSize; ///< Size of a tab + int fg; ///< Foreground color + int bg; ///< Background color + int flags; ///< Reverse/bright flags - ConsolePrint PrintChar; /*!< callback for printing a character. Should return true if it has handled rendering the graphics - (else the print engine will attempt to render via tiles) */ + ConsolePrint PrintChar; ///< Callback for printing a character. Should return true if it has handled rendering the graphics (else the print engine will attempt to render via tiles). - bool consoleInitialised; /*!< True if the console is initialized */ + bool consoleInitialised; ///< True if the console is initialized }PrintConsole; #define CONSOLE_COLOR_BOLD (1<<0) @@ -101,58 +99,61 @@ typedef struct PrintConsole #define CONSOLE_CONCEAL (1<<7) #define CONSOLE_CROSSED_OUT (1<<8) -//! Console debug devices supported by libnds. +/// Console debug devices supported by libnds. typedef enum { - debugDevice_NULL, //!< swallows prints to stderr - debugDevice_3DMOO, //!< Directs stderr debug statements to 3dmoo - debugDevice_CONSOLE, //!< Directs stderr debug statements to 3DS console window + debugDevice_NULL, ///< swallows prints to stderr + debugDevice_3DMOO, ///< Directs stderr debug statements to 3dmoo + debugDevice_CONSOLE, ///< Directs stderr debug statements to 3DS console window } debugDevice; -/*! \brief Loads the font into the console - \param console pointer to the console to update, if NULL it will update the current console - \param font the font to load +/** + * @brief Loads the font into the console. + * @param console Pointer to the console to update, if NULL it will update the current console. + * @param font The font to load. */ void consoleSetFont(PrintConsole* console, ConsoleFont* font); -/*! \brief Sets the print window - \param console console to set, if NULL it will set the current console window - \param x x location of the window - \param y y location of the window - \param width width of the window - \param height height of the window +/** + * @brief Sets the print window. + * @param console Console to set, if NULL it will set the current console window. + * @param x X location of the window. + * @param y Y location of the window. + * @param width Width of the window. + * @param height Height of the window. */ void consoleSetWindow(PrintConsole* console, int x, int y, int width, int height); -/*! \brief Gets a pointer to the console with the default values - this should only be used when using a single console or without changing the console that is returned, other wise use consoleInit() - \return A pointer to the console with the default values +/** + * @brief Gets a pointer to the console with the default values. + * This should only be used when using a single console or without changing the console that is returned, otherwise use consoleInit(). + * @return A pointer to the console with the default values. */ PrintConsole* consoleGetDefault(void); -/*! \brief Make the specified console the render target - \param console A pointer to the console struct (must have been initialized with consoleInit(PrintConsole* console) - \return a pointer to the previous console +/** + * @brief Make the specified console the render target. + * @param console A pointer to the console struct (must have been initialized with consoleInit(PrintConsole* console)). + * @return A pointer to the previous console. */ PrintConsole *consoleSelect(PrintConsole* console); -/*! \brief Initialise the console. - \param screen The screen to use for the console - \param console A pointer to the console data to initialze (if it's NULL, the default console will be used) - \return A pointer to the current console. +/** + * @brief Initialise the console. + * @param screen The screen to use for the console. + * @param console A pointer to the console data to initialize (if it's NULL, the default console will be used). + * @return A pointer to the current console. */ PrintConsole* consoleInit(gfxScreen_t screen, PrintConsole* console); -/*! \brief Initializes debug console output on stderr to the specified device - \param device The debug device (or devices) to output debug print statements to +/** + * @brief Initializes debug console output on stderr to the specified device. + * @param device The debug device (or devices) to output debug print statements to. */ void consoleDebugInit(debugDevice device); - -//! Clears the screan by using iprintf("\x1b[2J"); +/// Clears the screan by using iprintf("\x1b[2J"); void consoleClear(void); #ifdef __cplusplus } #endif - -#endif diff --git a/libctru/include/3ds/gfx.h b/libctru/include/3ds/gfx.h index cf37fec..072ac6c 100644 --- a/libctru/include/3ds/gfx.h +++ b/libctru/include/3ds/gfx.h @@ -13,7 +13,7 @@ #define RGB565(r,g,b) (((b)&0x1f)|(((g)&0x3f)<<5)|(((r)&0x1f)<<11)) #define RGB8_to_565(r,g,b) (((b)>>3)&0x1f)|((((g)>>2)&0x3f)<<5)|((((r)>>3)&0x1f)<<11) -//! Available screens. +/// Available screens. typedef enum { GFX_TOP = 0, ///< Top screen diff --git a/libctru/include/3ds/gpu/gx.h b/libctru/include/3ds/gpu/gx.h index 2901196..8f059b0 100644 --- a/libctru/include/3ds/gpu/gx.h +++ b/libctru/include/3ds/gpu/gx.h @@ -32,9 +32,7 @@ typedef enum GX_TRANSFER_SCALE_XY = 2, ///< 2x2 anti-aliasing } GX_TRANSFER_SCALE; -/** - * @brief GX transfer control flags - */ +/// GX transfer control flags typedef enum { GX_FILL_TRIGGER = 0x001, ///< Trigger the PPF event diff --git a/libctru/include/3ds/ipc.h b/libctru/include/3ds/ipc.h index 6baba48..f13c59f 100644 --- a/libctru/include/3ds/ipc.h +++ b/libctru/include/3ds/ipc.h @@ -7,7 +7,7 @@ #include <3ds/types.h> -//! IPC buffer access rights. +/// IPC buffer access rights. typedef enum { IPC_BUFFER_R = BIT(1), ///< Readable diff --git a/libctru/include/3ds/os.h b/libctru/include/3ds/os.h index ddac573..dbf5453 100644 --- a/libctru/include/3ds/os.h +++ b/libctru/include/3ds/os.h @@ -13,20 +13,20 @@ #define GET_VERSION_REVISION(version) (((version)>> 8)&0xFF) /** - * Converts an address from virtual (process) memory to physical memory. + * @brief Converts an address from virtual (process) memory to physical memory. * It is sometimes required by services or when using the GPU command buffer. */ u32 osConvertVirtToPhys(u32 vaddr); /** - * Converts 0x14* vmem to 0x30*. + * @brief Converts 0x14* vmem to 0x30*. * @return The input address when it's already within the new vmem. * @return 0 when outside of either LINEAR mem areas. */ u32 osConvertOldLINEARMemToNew(u32 addr); /** - * @brief Basic information about a service error. + * @brief Retreives basic information about a service error. * @return A string of the summary of an error. * * This can be used to get some details about an error returned by a service call. @@ -34,14 +34,16 @@ u32 osConvertOldLINEARMemToNew(u32 addr); const char* osStrError(u32 error); /** - * @return The Firm version + * @brief Gets the system's FIRM version. + * @return The FIRM version. * * This can be used to compare system versions easily with @ref SYSTEM_VERSION. */ u32 osGetFirmVersion(void); /** - * @return The kernel version + * @brief Gets the system's kernel version. + * @return The kernel version. * * This can be used to compare system versions easily with @ref SYSTEM_VERSION. * @@ -52,6 +54,7 @@ u32 osGetFirmVersion(void); u32 osGetKernelVersion(void); /** + * @brief Gets the current time. * @return The number of milliseconds since 1st Jan 1900 00:00. */ u64 osGetTime(void); diff --git a/libctru/include/3ds/romfs.h b/libctru/include/3ds/romfs.h index 5f5dab0..e031cf7 100644 --- a/libctru/include/3ds/romfs.h +++ b/libctru/include/3ds/romfs.h @@ -6,7 +6,7 @@ #include <3ds/types.h> -//! RomFS header. +/// RomFS header. typedef struct { u32 headerSize; ///< Size of the header. @@ -21,7 +21,7 @@ typedef struct u32 fileDataOff; ///< Offset of the file data. } romfs_header; -//! RomFS directory. +/// RomFS directory. typedef struct { u32 parent; ///< Offset of the parent directory. @@ -33,7 +33,7 @@ typedef struct u16 name[]; ///< Name. (UTF-16) } romfs_dir; -//! RomFS file. +/// RomFS file. typedef struct { u32 parent; ///< Offset of the parent directory. @@ -45,7 +45,7 @@ typedef struct u16 name[]; ///< Name. (UTF-16) } romfs_file; -//! Initializes the RomFS driver. +/// Initializes the RomFS driver. Result romfsInit(void); /** @@ -55,5 +55,5 @@ Result romfsInit(void); */ Result romfsInitFromFile(Handle file, u32 offset); -//! Exits the RomFS driver. +/// Exits the RomFS driver. Result romfsExit(void); diff --git a/libctru/include/3ds/sdmc.h b/libctru/include/3ds/sdmc.h index 9606510..d86acde 100644 --- a/libctru/include/3ds/sdmc.h +++ b/libctru/include/3ds/sdmc.h @@ -6,8 +6,8 @@ #include <3ds/types.h> -//! Initializes the SDMC driver. +/// Initializes the SDMC driver. Result sdmcInit(void); -//! Exits the SDMC driver. +/// Exits the SDMC driver. Result sdmcExit(void); diff --git a/libctru/include/3ds/services/fs.h b/libctru/include/3ds/services/fs.h index a6e1f9b..d31cccc 100644 --- a/libctru/include/3ds/services/fs.h +++ b/libctru/include/3ds/services/fs.h @@ -1,72 +1,75 @@ +/** + * @file FS.h + * @brief Filesystem Services + */ #pragma once + #include <3ds/types.h> -/*! @file FS.h +/** + * @defgroup fs_open_flags FS Open Flags * - * Filesystem Services + * @sa FSUSER_OpenFile + * @sa FSUSER_OpenFileDirectly + * + * @{ */ -/*! @defgroup fs_open_flags FS Open Flags - * - * @sa FSUSER_OpenFile - * @sa FSUSER_OpenFileDirectly - * - * @{ - */ - -/*! Open file for read. */ +/// Open file for read. #define FS_OPEN_READ (1<<0) -/*! Open file for write. */ +/// Open file for write. #define FS_OPEN_WRITE (1<<1) -/*! Create file if it doesn't exist. */ +/// Create file if it doesn't exist. #define FS_OPEN_CREATE (1<<2) -/* @} */ +/// @} -/*! @defgroup fs_create_attributes FS Create Attributes +/** + * @defgroup fs_create_attributes FS Create Attributes * - * @sa FSUSER_OpenFile - * @sa FSUSER_OpenFileDirectly + * @sa FSUSER_OpenFile + * @sa FSUSER_OpenFileDirectly * - * @{ + * @{ */ -/*! No attributes. */ +/// No attributes. #define FS_ATTRIBUTE_NONE (0x00000000) -/*! Create with read-only attribute. */ +/// Create with read-only attribute. #define FS_ATTRIBUTE_READONLY (0x00000001) -/*! Create with archive attribute. */ +/// Create with archive attribute. #define FS_ATTRIBUTE_ARCHIVE (0x00000100) -/*! Create with hidden attribute. */ +/// Create with hidden attribute. #define FS_ATTRIBUTE_HIDDEN (0x00010000) -/*! Create with directory attribute. */ +/// Create with directory attribute. #define FS_ATTRIBUTE_DIRECTORY (0x01000000) -/*! @} */ +/// @} -/*! @defgroup fs_write_flush_flags FS Flush Flags +/** + * @defgroup fs_write_flush_flags FS Flush Flags * - * @sa FSFILE_Write + * @sa FSFILE_Write * - * @{ + * @{ */ -/*! Don't flush */ +/// Don't flush #define FS_WRITE_NOFLUSH (0x00000000) -/*! Flush */ +/// Flush #define FS_WRITE_FLUSH (0x00010001) -/* @} */ +/// @} -/*! FS path type */ +/// FS path type typedef enum { - PATH_INVALID = 0, //!< Specifies an invalid path. - PATH_EMPTY = 1, //!< Specifies an empty path. - PATH_BINARY = 2, //!< Specifies a binary path, which is non-text based. - PATH_CHAR = 3, //!< Specifies a text based path with a 8-bit byte per character. - PATH_WCHAR = 4, //!< Specifies a text based path with a 16-bit short per character. + PATH_INVALID = 0, ///< Specifies an invalid path. + PATH_EMPTY = 1, ///< Specifies an empty path. + PATH_BINARY = 2, ///< Specifies a binary path, which is non-text based. + PATH_CHAR = 3, ///< Specifies a text based path with a 8-bit byte per character. + PATH_WCHAR = 4, ///< Specifies a text based path with a 16-bit short per character. } FS_pathType; -/*! FS archive ids */ +/// FS archive ids typedef enum { ARCH_ROMFS = 0x3, @@ -83,48 +86,48 @@ typedef enum ARCH_NAND_RO_WRITE_ACCESS = 0x1234567F, } FS_archiveIds; -/*! FS path */ +/// FS path typedef struct { - FS_pathType type; //!< FS path type. - u32 size; //!< FS path size. - const u8 *data; //!< Pointer to FS path data. + FS_pathType type; ///< FS path type. + u32 size; ///< FS path size. + const u8 *data; ///< Pointer to FS path data. } FS_path; -/*! FS archive */ +/// FS archive typedef struct { - u32 id; //!< Archive ID. - FS_path lowPath; //!< FS path. - Handle handleLow; //!< High word of handle. - Handle handleHigh; //!< Low word of handle. + u32 id; ///< Archive ID. + FS_path lowPath; ///< FS path. + Handle handleLow; ///< High word of handle. + Handle handleHigh; ///< Low word of handle. } FS_archive; -/*! Directory entry */ +/// Directory entry typedef struct { // 0x00 - u16 name[0x106]; //!< UTF-16 encoded name + u16 name[0x106]; ///< UTF-16 encoded name // 0x20C - u8 shortName[0x09]; //!< 8.3 file name + u8 shortName[0x09]; ///< 8.3 file name // 0x215 - u8 unknown1; //!< ??? + u8 unknown1; ///< ??? // 0x216 - u8 shortExt[0x04]; //!< 8.3 file extension (set to spaces for directories) + u8 shortExt[0x04]; ///< 8.3 file extension (set to spaces for directories) // 0x21A - u8 unknown2; //!< ??? + u8 unknown2; ///< ??? // 0x21B - u8 unknown3; //!< ??? + u8 unknown3; ///< ??? // 0x21C - u8 isDirectory; //!< directory bit + u8 isDirectory; ///< directory bit // 0x21D - u8 isHidden; //!< hidden bit + u8 isHidden; ///< hidden bit // 0x21E - u8 isArchive; //!< archive bit + u8 isArchive; ///< archive bit // 0x21F - u8 isReadOnly; //!< read-only bit + u8 isReadOnly; ///< read-only bit // 0x220 - u64 fileSize; //!< file size + u64 fileSize; ///< file size } FS_dirent; Result fsInit(void); diff --git a/libctru/include/3ds/srv.h b/libctru/include/3ds/srv.h index 6b2a8e2..bbdbe58 100644 --- a/libctru/include/3ds/srv.h +++ b/libctru/include/3ds/srv.h @@ -4,10 +4,10 @@ */ #pragma once -//! Initializes the service API. +/// Initializes the service API. Result srvInit(void); -//! Exits the service API. +/// Exits the service API. Result srvExit(void); /** @@ -16,7 +16,7 @@ Result srvExit(void); */ Handle *srvGetSessionHandle(void); -//! Registers the current process as a client to the service API. +/// Registers the current process as a client to the service API. Result srvRegisterClient(void); /** @@ -47,7 +47,7 @@ Result srvRegisterService(Handle* out, const char* name, int maxSessions); */ Result srvUnregisterService(const char* name); -//! Initializes the srv:pm port. +/// Initializes the srv:pm port. Result srvPmInit(void); /** diff --git a/libctru/include/3ds/svc.h b/libctru/include/3ds/svc.h index ba81b0b..fd91721 100644 --- a/libctru/include/3ds/svc.h +++ b/libctru/include/3ds/svc.h @@ -37,7 +37,7 @@ typedef enum { MEMOP_ALLOC_LINEAR = MEMOP_LINEAR_FLAG | MEMOP_ALLOC, ///< Allocates linear memory. } MemOp; -//! The state of a memory block. +/// The state of a memory block. typedef enum { MEMSTATE_FREE = 0, ///< Free memory MEMSTATE_RESERVED = 1, ///< Reserved memory @@ -53,7 +53,7 @@ typedef enum { MEMSTATE_LOCKED = 11 ///< Locked memory } MemState; -//! Memory permission flags +/// Memory permission flags typedef enum { MEMPERM_READ = 1, ///< Readable MEMPERM_WRITE = 2, ///< Writable @@ -61,7 +61,7 @@ typedef enum { MEMPERM_DONTCARE = 0x10000000 ///< Don't care } MemPerm; -//! Memory information. +/// Memory information. typedef struct { u32 base_addr; ///< Base address. u32 size; ///< Size. @@ -69,12 +69,12 @@ typedef struct { u32 state; ///< Memory state. See @ref MemState } MemInfo; -//! Memory page information. +/// Memory page information. typedef struct { u32 flags; ///< Page flags. } PageInfo; -//! Arbitration modes. +/// Arbitration modes. typedef enum { ARBITRATION_SIGNAL = 0, ///< Signal #value threads for wake-up. ARBITRATION_WAIT_IF_LESS_THAN = 1, ///< If the memory at the address is strictly lower than #value, then wait for signal. @@ -91,7 +91,7 @@ typedef enum { ///@name Multithreading ///@{ -//! Types of thread info. +/// Types of thread info. typedef enum { THREADINFO_TYPE_UNKNOWN ///< Unknown. } ThreadInfoType; @@ -105,13 +105,13 @@ typedef enum { ///@name Debugging ///@{ -//! Reasons for a process event. +/// Reasons for a process event. typedef enum { REASON_CREATE = 1, ///< Process created. REASON_ATTACH = 2 ///< Process attached. } ProcessEventReason; -//! Event relating to a process. +/// Event relating to a process. typedef struct { u64 program_id; ///< ID of the program. u8 process_name[8]; ///< Name of the process. @@ -119,26 +119,26 @@ typedef struct { u32 reason; ///< Reason for the event. See @ref ProcessEventReason } ProcessEvent; -//! Reasons for an exit process event. +/// Reasons for an exit process event. typedef enum { EXITPROCESS_EVENT_NONE = 0, ///< No reason. EXITPROCESS_EVENT_TERMINATE = 1, ///< Process terminated. EXITPROCESS_EVENT_UNHANDLED_EXCEPTION = 2 ///< Unhandled exception occurred. } ExitProcessEventReason; -//! Event relating to the exiting of a process. +/// Event relating to the exiting of a process. typedef struct { u32 reason; ///< Reason for exiting. See @ref ExitProcessEventReason } ExitProcessEvent; -//! Event relating to the creation of a thread. +/// Event relating to the creation of a thread. typedef struct { u32 creator_thread_id; ///< ID of the creating thread. u32 base_addr; ///< Base address. u32 entry_point; ///< Entry point of the thread. } CreateThreadEvent; -//! Reasons for an exit thread event. +/// Reasons for an exit thread event. typedef enum { EXITTHREAD_EVENT_NONE = 0, ///< No reason. EXITTHREAD_EVENT_TERMINATE = 1, ///< Thread terminated. @@ -146,19 +146,19 @@ typedef enum { EXITTHREAD_EVENT_TERMINATE_PROCESS = 3 ///< Process terminated. } ExitThreadEventReason; -//! Event relating to the exiting of a thread. +/// Event relating to the exiting of a thread. typedef struct { u32 reason; ///< Reason for exiting. See @ref ExitThreadEventReason } ExitThreadEvent; -//! Reasons for a user break. +/// Reasons for a user break. typedef enum { USERBREAK_PANIC = 0, ///< Panic. USERBREAK_ASSERT = 1, ///< Assertion failed. USERBREAK_USER = 2 ///< User related. } UserBreakType; -//! Reasons for an exception event. +/// Reasons for an exception event. typedef enum { EXC_EVENT_UNDEFINED_INSTRUCTION = 0, ///< Undefined instruction. arg: (None) EXC_EVENT_UNKNOWN1 = 1, ///< Unknown. arg: (None) @@ -171,31 +171,31 @@ typedef enum { EXC_EVENT_UNDEFINED_SYSCALL = 8 ///< Undefined syscall. arg: attempted syscall } ExceptionEventType; -//! Event relating to exceptions. +/// Event relating to exceptions. typedef struct { u32 type; ///< Type of event. See @ref ExceptionEventType u32 address; ///< Address of the exception. u32 argument; ///< Event argument. See @ref ExceptionEventType } ExceptionEvent; -//! Event relating to the scheduler. +/// Event relating to the scheduler. typedef struct { u64 clock_tick; ///< Clock tick that the event occurred. } SchedulerInOutEvent; -//! Event relating to syscalls. +/// Event relating to syscalls. typedef struct { u64 clock_tick; ///< Clock tick that the event occurred. u32 syscall; ///< Syscall sent/received. } SyscallInOutEvent; -//! Event relating to debug output. +/// Event relating to debug output. typedef struct { u32 string_addr; ///< Address of the outputted string. u32 string_size; ///< Size of the outputted string. } OutputStringEvent; -//! Event relating to the mapping of memory. +/// Event relating to the mapping of memory. typedef struct { u32 mapped_addr; ///< Mapped address. u32 mapped_size; ///< Mapped size. @@ -203,7 +203,7 @@ typedef struct { u32 memstate; ///< Memory state. See @ref MemState } MapEvent; -//! Debug event type. +/// Debug event type. typedef enum { DBG_EVENT_PROCESS = 0, ///< Process event. DBG_EVENT_CREATE_THREAD = 1, ///< Thread creation event. @@ -220,7 +220,7 @@ typedef enum { DBG_EVENT_MAP = 12 ///< Map event. } DebugEventType; -//! Information about a debug event. +/// Information about a debug event. typedef struct { u32 type; ///< Type of event. See @ref DebugEventType u32 thread_id; ///< ID of the thread. @@ -441,7 +441,7 @@ Result svcWriteProcessMemory(Handle debug, const void* buffer, u32 addr, u32 siz */ Result svcOpenProcess(Handle* process, u32 processId); -//! Exits the current process. +/// Exits the current process. void svcExitProcess() __attribute__((noreturn)); /** @@ -535,7 +535,7 @@ void svcExitThread(void) __attribute__((noreturn)); */ void svcSleepThread(s64 ns); -//! Retrieves the priority of a thread. +/// Retrieves the priority of a thread. Result svcGetThreadPriority(s32 *out, Handle handle); /** diff --git a/libctru/include/3ds/synchronization.h b/libctru/include/3ds/synchronization.h index 9d61ae1..eb0ee84 100644 --- a/libctru/include/3ds/synchronization.h +++ b/libctru/include/3ds/synchronization.h @@ -4,10 +4,10 @@ */ #pragma once -//! A light lock. +/// A light lock. typedef s32 LightLock; -//! A recursive lock. +/// A recursive lock. typedef struct { LightLock lock; ///< Inner light lock. @@ -15,7 +15,7 @@ typedef struct u32 counter; ///< Lock count. } RecursiveLock; -//! Performs a clrex operation. +/// Performs a clrex operation. static inline void __clrex(void) { __asm__ __volatile__("clrex"); diff --git a/libctru/include/3ds/types.h b/libctru/include/3ds/types.h index 5a5c45a..d7754c0 100644 --- a/libctru/include/3ds/types.h +++ b/libctru/include/3ds/types.h @@ -8,10 +8,10 @@ #include #include -//! The maximum value of a u64. +/// The maximum value of a u64. #define U64_MAX UINT64_MAX -//! Possible media types. +/// Possible media types. typedef enum { mediatype_NAND, ///< NAND @@ -43,15 +43,15 @@ typedef u32 Handle; ///< Resource handle. typedef s32 Result; ///< Function result. typedef void (*ThreadFunc)(void *); ///< Thread entrypoint function. -//! Creates a bitmask from a bit number. +/// Creates a bitmask from a bit number. #define BIT(n) (1U<<(n)) -//! aligns a struct (and other types?) to m, making sure that the size of the struct is a multiple of m. +/// aligns a struct (and other types?) to m, making sure that the size of the struct is a multiple of m. #define ALIGN(m) __attribute__((aligned(m))) -//! packs a struct (and other types?) so it won't include padding bytes. +/// packs a struct (and other types?) so it won't include padding bytes. #define PACKED __attribute__((packed)) -//! flags a function as deprecated. +/// flags a function as deprecated. #ifndef LIBCTRU_NO_DEPRECATION #define DEPRECATED __attribute__ ((deprecated)) #else diff --git a/libctru/include/3ds/util/rbtree.h b/libctru/include/3ds/util/rbtree.h index c78c6b2..6e1cf34 100644 --- a/libctru/include/3ds/util/rbtree.h +++ b/libctru/include/3ds/util/rbtree.h @@ -7,7 +7,7 @@ #include #include -//! brief Retreives an rbtree item. +/// brief Retreives an rbtree item. #define rbtree_item(ptr, type, member) \ ((type*)(((char*)ptr) - offsetof(type, member))) @@ -18,14 +18,14 @@ typedef void (*rbtree_node_destructor_t)(rbtree_node_t *Node); ///< rbtree typedef int (*rbtree_node_comparator_t)(const rbtree_node_t *lhs, const rbtree_node_t *rhs); ///< rbtree node comparator. -//! An rbtree node. +/// An rbtree node. struct rbtree_node { uintptr_t parent_color; ///< Parent color. rbtree_node_t *child[2]; ///< Node children. }; -//! An rbtree. +/// An rbtree. struct rbtree { rbtree_node_t *root; ///< Root node. diff --git a/libctru/include/3ds/util/utf.h b/libctru/include/3ds/util/utf.h index 3d4e3c8..bc2966d 100644 --- a/libctru/include/3ds/util/utf.h +++ b/libctru/include/3ds/util/utf.h @@ -7,7 +7,7 @@ #include #include -/*! Convert a UTF-8 sequence into a UTF-32 codepoint +/** Convert a UTF-8 sequence into a UTF-32 codepoint * * @param[out] out Output codepoint * @param[in] in Input sequence @@ -17,7 +17,7 @@ */ ssize_t decode_utf8 (uint32_t *out, const uint8_t *in); -/*! Convert a UTF-16 sequence into a UTF-32 codepoint +/** Convert a UTF-16 sequence into a UTF-32 codepoint * * @param[out] out Output codepoint * @param[in] in Input sequence @@ -27,7 +27,7 @@ ssize_t decode_utf8 (uint32_t *out, const uint8_t *in); */ ssize_t decode_utf16(uint32_t *out, const uint16_t *in); -/*! Convert a UTF-32 codepoint into a UTF-8 sequence +/** Convert a UTF-32 codepoint into a UTF-8 sequence * * @param[out] out Output sequence * @param[in] in Input codepoint @@ -39,7 +39,7 @@ ssize_t decode_utf16(uint32_t *out, const uint16_t *in); */ ssize_t encode_utf8 (uint8_t *out, uint32_t in); -/*! Convert a UTF-32 codepoint into a UTF-16 sequence +/** Convert a UTF-32 codepoint into a UTF-16 sequence * * @param[out] out Output sequence * @param[in] in Input codepoint @@ -51,7 +51,7 @@ ssize_t encode_utf8 (uint8_t *out, uint32_t in); */ ssize_t encode_utf16(uint16_t *out, uint32_t in); -/*! Convert a UTF-8 sequence into a UTF-16 sequence +/** Convert a UTF-8 sequence into a UTF-16 sequence * * @param[out] out Output sequence * @param[in] in Input sequence @@ -61,7 +61,7 @@ ssize_t encode_utf16(uint16_t *out, uint32_t in); */ size_t utf8_to_utf16(uint16_t *out, const uint8_t *in, size_t len); -/*! Convert a UTF-8 sequence into a UTF-32 sequence +/** Convert a UTF-8 sequence into a UTF-32 sequence * * @param[out] out Output sequence * @param[in] in Input sequence @@ -71,7 +71,7 @@ size_t utf8_to_utf16(uint16_t *out, const uint8_t *in, size_t len); */ size_t utf8_to_utf32(uint32_t *out, const uint8_t *in, size_t len); -/*! Convert a UTF-16 sequence into a UTF-8 sequence +/** Convert a UTF-16 sequence into a UTF-8 sequence * * @param[out] out Output sequence * @param[in] in Input sequence @@ -81,7 +81,7 @@ size_t utf8_to_utf32(uint32_t *out, const uint8_t *in, size_t len); */ size_t utf16_to_utf8(uint8_t *out, const uint16_t *in, size_t len); -/*! Convert a UTF-16 sequence into a UTF-32 sequence +/** Convert a UTF-16 sequence into a UTF-32 sequence * * @param[out] out Output sequence * @param[in] in Input sequence @@ -91,7 +91,7 @@ size_t utf16_to_utf8(uint8_t *out, const uint16_t *in, size_t len); */ size_t utf16_to_utf32(uint32_t *out, const uint16_t *in, size_t len); -/*! Convert a UTF-32 sequence into a UTF-8 sequence +/** Convert a UTF-32 sequence into a UTF-8 sequence * * @param[out] out Output sequence * @param[in] in Input sequence @@ -101,7 +101,7 @@ size_t utf16_to_utf32(uint32_t *out, const uint16_t *in, size_t len); */ size_t utf32_to_utf8(uint8_t *out, const uint32_t *in, size_t len); -/*! Convert a UTF-32 sequence into a UTF-16 sequence +/** Convert a UTF-32 sequence into a UTF-16 sequence * * @param[out] out Output sequence * @param[in] in Input sequence