diff --git a/include/coreinit/memory.h b/include/coreinit/memory.h index ff832211..e8805b54 100644 --- a/include/coreinit/memory.h +++ b/include/coreinit/memory.h @@ -18,12 +18,50 @@ typedef enum OSMemoryType OS_MEM2 = 2, } OSMemoryType; +/** + * Moves chunks of memory around, similarly to memmove. Overlapping source and + * destination regions are supported. + * + * \param dst + * The destination address for the move. + * + * \param src + * The source address for the move. + * + * \param size + * The size of the data to be moved, in bytes. + * + * \param flush + * Whether to flush the data caches for the source and destination. + * + * \return + * dst is returned. + * + * \note + * This function makes use of the cache to speed up the copy, so a flush is + * recommended. + */ void * OSBlockMove(void *dst, const void *src, uint32_t size, BOOL flush); +/** + * Fills a chunk of memory with the given value, like memset. + * + * \param dst + * Pointer to the memory to fill. + * + * \param val + * Byte value to be set. + * + * \param size + * Number of bytes to be set to val. + * + * \return + * dst is returned. + */ void * OSBlockSet(void *dst, uint8_t val, @@ -36,14 +74,58 @@ OSAllocFromSystem(uint32_t size, void OSFreeToSystem(void *ptr); +/** + * Gets the location and size of the foreground bucket memory area. + * + * \note + * This function may not account for the system reserved portion of the + * foreground bucket. Consider using OSGetForegroundBucketFreeArea() instead. + * + * \param outAddr + * Pointer to write the foreground bucket's address to. + * + * \param outSize + * Pointer to write the foreground bucket's size to. + * + * \return + * \c true on success. + */ BOOL OSGetForegroundBucket(uint32_t *outAddr, uint32_t *outSize); +/** + * Gets the location and size of the application-usable portion of the + * foreground bucket area. + * + * \param outAddr + * Pointer to write the bucket area's address to. + * + * \param outSize + * Pointer to write the bucket area's size to. + * + * \return + * \c true on success. + */ BOOL OSGetForegroundBucketFreeArea(uint32_t *outAddr, uint32_t *outSize); +/** + * Gets the location and size of available memory areas. + * + * \param type + * Type of memory to get information about. See #OSMemoryType. + * + * \param outAddr + * Pointer to write the area's address to. + * + * \param outSize + * Pointer to write the area's size to. + * + * \return + * 0 on success, -1 otherwise. + */ int OSGetMemBound(OSMemoryType type, uint32_t *outAddr, diff --git a/include/coreinit/memorymap.h b/include/coreinit/memorymap.h index fb38fb49..2565c73c 100644 --- a/include/coreinit/memorymap.h +++ b/include/coreinit/memorymap.h @@ -26,36 +26,153 @@ typedef enum OSMemoryMapMode uint32_t OSEffectiveToPhysical(uint32_t virtualAddress); +/** + * Allocates virtual address range for later mapping. + * + * \param virtualAddress + * Requested start address for the range. If there is no preference, NULL can be + * used. + * + * \param size + * Size of address range to allocate. + * + * \param align + * Alignment of address range to allocate. + * + * \return + * The starting address of the newly allocated range, or NULL on failure. + * + * \sa + * - OSFreeVirtAddr() + * - OSMapMemory() + */ uint32_t OSAllocVirtAddr(uint32_t virtualAddress, uint32_t size, uint32_t align); +/** + * Frees a previously allocated virtual address range back to the system. + * + * \param virtualAddress + * The start of the virtual address range to free. + * + * \param size + * The size of the virtual address range to free. + * + * \return + * \c true on success. + */ BOOL OSFreeVirtAddr(uint32_t virtualAddress, uint32_t size); +/** + * Determines the status of the given virtual memory address - mapped read-write + * or read-only, free, allocated or invalid. + * + * \param virtualAddress + * The virtual address to query. + * + * \return + * The status of the memory address - see #OSMemoryMapMode. + */ OSMemoryMapMode OSQueryVirtAddr(uint32_t virtualAddress); +/** + * Maps a physical address to a virtual address, with a given size and set of + * permissions. + * + * \param virtualAddress + * The target virtual address for the mapping. + * + * \param physicalAddress + * Physical address of the memory to back the mapping. + * + * \param size + * Size, in bytes, of the desired mapping. Likely has an alignment requirement. + * + * \param mode + * Permissions to map the memory with - see #OSMemoryMapMode. + * + * \return + * \c true on success. + * + * \sa + * - OSAllocVirtAddr() + * - OSUnmapMemory() + */ BOOL OSMapMemory(uint32_t virtualAddress, uint32_t physicalAddress, uint32_t size, OSMemoryMapMode mode); +/** + * Unmaps previously mapped memory. + * + * \param virtualAddress + * Starting address of the area to unmap. + * + * \param size + * Size of the memory area to unmap. + * + * \return + * \c true on success. + */ BOOL OSUnmapMemory(uint32_t virtualAddress, uint32_t size); +/** + * Gets the range of virtual addresses available for mapping. + * + * \param outVirtualAddress + * Pointer to write the starting address of the memory area to. + * + * \param outSize + * Pointer to write the size of the memory area to. + * + * \sa + * - OSMapMemory() + */ void OSGetMapVirtAddrRange(uint32_t *outVirtualAddress, uint32_t *outSize); +/** + * Gets the range of available physical memory (not reserved for app code or + * data). + * + * \param outPhysicalAddress + * Pointer to write the starting physical address of the memory area to. + * + * \param outSize + * Pointer to write the size of the memory area to. + * + * \if false + * Is memory returned by this function actually safe to map and use? couldn't + * get a straight answer from decaf-emu's kernel_memory.cpp... + * \endif + */ void OSGetAvailPhysAddrRange(uint32_t *outPhysicalAddress, uint32_t *outSize); +/** + * Gets the range of physical memory used for the application's data. + * + * \param outPhysicalAddress + * Pointer to write the starting physical address of the memory area to. + * + * \param outSize + * Pointer to write the size of the memory area to. + * + * \if false + * does this include the main heap? + * \endif + */ void OSGetDataPhysAddrRange(uint32_t *outPhysicalAddress, uint32_t *outSize); diff --git a/include/proc_ui/procui.h b/include/proc_ui/procui.h index c68bf913..da05a5cb 100644 --- a/include/proc_ui/procui.h +++ b/include/proc_ui/procui.h @@ -11,8 +11,19 @@ extern "C" { #endif +/** + * Called when the application needs to save. + */ typedef void (*ProcUISaveCallback)(void); +/** + * Called when the application needs to save. + * void* argument is provided in ProcUIInitEx(). + */ typedef uint32_t (*ProcUISaveCallbackEx)(void *); +/** + * Generic ProcUI callback. + * void* argument is provided in ProcUIRegisterCallback(). + */ typedef uint32_t (*ProcUICallback)(void *); typedef enum ProcUICallbackType @@ -48,9 +59,33 @@ ProcUIInForeground(); BOOL ProcUIInShutdown(); +/** + * Initialises the ProcUI library for use. + * + * \param saveCallback + * A callback to be called when the application needs to save. The callback + * cannot be NULL and it must call OSSavesDone_ReadyToRelease(). + * + * \sa + * - OSSavesDone_ReadyToRelease() + */ void ProcUIInit(ProcUISaveCallback saveCallback); +/** + * Initialises the ProcUI library for use; using a save callback that takes + * arguments. + * + * \param saveCallback + * A callback to be called when the application needs to save. The callback + * cannot be NULL and it must call OSSavesDone_ReadyToRelease(). + * + * \param arg + * An argument to pass into saveCallbackEx. + * + * \sa + * - OSSavesDone_ReadyToRelease() + */ void ProcUIInitEx(ProcUISaveCallbackEx saveCallback, void *arg); @@ -58,9 +93,53 @@ ProcUIInitEx(ProcUISaveCallbackEx saveCallback, BOOL ProcUIIsRunning(); +/** + * Main runloop for ProcUI. This function processes messages from the OS and + * provides it an opportinity to take control (to open the HOME menu overlay, + * for example). Returns the current state of the application. + * + * \param block + * Determines whether the function should block before returning. If \c false, + * the function returns immediately. + * + * \return + * The current state of the program. See #ProcUIStatus. + * + * \warning + * At this time, using ProcUI's non-blocking mode is not recommended as not much + * is known about it. Instead, set block to \c true and examine the return + * value. + * + * \note + * This function should only be called from the main core. See OSIsMainCore(). + * + * \if false + * meta: what happens when block=false? is the return value trustworthy? how + * does it interact with ProcUIRegisterCallback? + * \endif + */ ProcUIStatus ProcUIProcessMessages(BOOL block); +/** + * Register a callback for certain ProcUI events. + * + * \param type + * The event to register a callback for. See #ProcUICallbackType. + * + * \param callback + * Function pointer for the callback to call when the given event occurs. + * + * \param param + * Argument for the callback. This will be passed in as the *second* argument. + * + * \param priority + * The priority of the callback. + * + * \if false + * higher-priority callbacks exec first? dunno + * \endif + */ void ProcUIRegisterCallback(ProcUICallbackType type, ProcUICallback callback, @@ -81,6 +160,23 @@ ProcUISetSaveCallback(ProcUISaveCallbackEx saveCallback, void ProcUIShutdown(); +/** + * ProcUIProcessMessages(), but for secondary cores. + * + * \param block + * Determines whether the function should block before returning. If \c false, + * the function returns immediately. + * + * \warning + * At this time, using ProcUI's non-blocking mode is not recommended as not much + * is known about it. Instead, set block to \c true and examine the return + * value. + * + * \if false + * didn't know what this did, only seen it in the else{} from OSIsMainCore... + * please research and correct! + * \endif + */ ProcUIStatus ProcUISubProcessMessages(BOOL block); diff --git a/include/vpad/input.h b/include/vpad/input.h index 746b51b9..ed5e6523 100644 --- a/include/vpad/input.h +++ b/include/vpad/input.h @@ -69,8 +69,11 @@ typedef enum VPADTouchPadValidity typedef enum VPADReadError { + //! No error occured, and data was written to the buffers. VPAD_READ_SUCCESS = 0, + //! There was no sample new data available to write. VPAD_READ_NO_SAMPLES = -1, + //! The requested controller or channel was invalid. VPAD_READ_INVALID_CONTROLLER = -2, } VPADReadError; @@ -108,13 +111,15 @@ WUT_CHECK_SIZE(VPADDirection, 0x24); struct VPADTouchData { + //! The x-coordinate of a touched point. uint16_t x; + //! The y-coordinate of a touched point. uint16_t y; //! 0 if screen is not currently being touched uint16_t touched; - //! Bitfield of VPADTouchPadValidity to indicate how touch sample accuracy + //! Bitfield of #VPADTouchPadValidity to indicate how touch sample accuracy uint16_t validity; }; WUT_CHECK_OFFSET(VPADTouchData, 0x00, x); @@ -219,19 +224,69 @@ WUT_CHECK_OFFSET(VPADStatus, 0xA2, micStatus); WUT_CHECK_OFFSET(VPADStatus, 0xA3, slideVolumeEx); WUT_CHECK_SIZE(VPADStatus, 0xAC); -//! Deprecated +/** + * Initialises the VPAD library for use. + * + * \deprecated + * As of Cafe OS 5.5.x (OSv10 v15702) this function simply logs a deprecation + * message and returns. However, this may not be the case on older versions. + */ void VPADInit(); void VPADShutdown(); +/** + * Read controller data from the desired Gamepad. + * + * \note + * Retail Wii U systems have a single Gamepad on \link VPADChan::VPAD_CHAN_0 VPAD_CHAN_0. \endlink + * + * \param chan + * The channel to read from. + * + * \param buffers + * Pointer to an array of VPADStatus buffers to fill. + * + * \param count + * Number of buffers to fill. + * + * \param outError + * Pointer to write read error to (if any). See #VPADReadError for meanings. + * + * \return + * 0 on success or 1 on failure. Check error for reason. + * + * \sa + * - VPADStatus + */ int32_t VPADRead(VPADChan chan, VPADStatus *buffers, uint32_t count, VPADReadError *outError); +/** + * Transform touch data according to the current calibration data. + * The calibration used may either be the system default or set by the + * application via VPADSetTPCalibrationParam(). + * + * \note + * Retail Wii U systems have a single Gamepad on \link VPADChan::VPAD_CHAN_0 VPAD_CHAN_0. \endlink + * + * \param chan + * Denotes which channel to get the calibration data from. + * + * \param calibratedData + * Pointer to write calibrated touch data to. + * + * \param uncalibratedData + * Pointer to the source data to apply the calibration to. + * + * \sa + * - VPADTouchData + */ void VPADGetTPCalibratedPoint(VPADChan chan, VPADTouchData *calibratedData, @@ -391,11 +446,43 @@ VPADInitGyroAccReviseParam(VPADChan chan); void VPADInitGyroZeroDriftMode(VPADChan chan); +/** + * Turns on the rumble motor on the desired Gamepad. + * A custom rumble pattern can be set by setting bytes in the input buffer. + * + * \note + * Retail Wii U systems have a single Gamepad on \link VPADChan::VPAD_CHAN_0 VPAD_CHAN_0. \endlink + * + * \param chan + * The channel of the Gamepad to rumble. + * + * \param pattern + * Pointer to an array of bytes, where each byte represents the status of the + * rumble at a given time. 0xFF denotes rumble while 0x00 denotes no rumble. + * + * \param length + * The size of the rumble pattern, in bytes. + * + * \if false + * meta: find out if the bytes in buffer are an analog intensity control (e.g + * is 0x7F "half intensity"?) or are simply binary motor on/off toggles + * \endif + */ int32_t VPADControlMotor(VPADChan chan, uint8_t *pattern, uint8_t length); +/** + * Stops the desired Gamepad's rumble motor and cancels any ongoing rumble + * pattern. + * + * \note + * Retail Wii U systems have a single Gamepad on \link VPADChan::VPAD_CHAN_0 VPAD_CHAN_0. \endlink + * + * \param chan + * The channel of the Gamepad to stop rumbling. + */ void VPADStopMotor(VPADChan chan);