From 864ad21a0d9ec3c8560a93681c5e76f9765b15f0 Mon Sep 17 00:00:00 2001 From: Ash Date: Sat, 23 Jun 2018 19:35:30 +1000 Subject: [PATCH 1/4] include/vpad: Add Doxygen documentation for some functions (from decaf) From e9db64c9442f239792477e8b5c8e61286329b206. --- include/vpad/input.h | 89 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/include/vpad/input.h b/include/vpad/input.h index 746b51b9..9788d2f4 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,7 +111,9 @@ 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 @@ -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 channel 0. + * + * \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 channel 0. + * + * \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 channel 0. + * + * \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 channel 0. + * + * \param chan + * The channel of the Gamepad to stop rumbling. + */ void VPADStopMotor(VPADChan chan); From 2f995fec412d641dd99e5ecf6e4eaffbbe773947 Mon Sep 17 00:00:00 2001 From: Ash Date: Sat, 23 Jun 2018 19:52:13 +1000 Subject: [PATCH 2/4] include/vpad: Minor improvments, enum links, whatever --- include/vpad/input.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/include/vpad/input.h b/include/vpad/input.h index 9788d2f4..ed5e6523 100644 --- a/include/vpad/input.h +++ b/include/vpad/input.h @@ -119,7 +119,7 @@ struct VPADTouchData //! 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); @@ -241,7 +241,7 @@ VPADShutdown(); * Read controller data from the desired Gamepad. * * \note - * Retail Wii U systems have a single Gamepad on channel 0. + * 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. @@ -273,7 +273,7 @@ VPADRead(VPADChan chan, * application via VPADSetTPCalibrationParam(). * * \note - * Retail Wii U systems have a single Gamepad on channel 0. + * 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. @@ -451,7 +451,7 @@ VPADInitGyroZeroDriftMode(VPADChan chan); * A custom rumble pattern can be set by setting bytes in the input buffer. * * \note - * Retail Wii U systems have a single Gamepad on channel 0. + * 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. @@ -478,7 +478,7 @@ VPADControlMotor(VPADChan chan, * pattern. * * \note - * Retail Wii U systems have a single Gamepad on channel 0. + * 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. From 6a146f4b38fb51db770bf0494426989c87a4e6e3 Mon Sep 17 00:00:00 2001 From: Ash Date: Sat, 23 Jun 2018 20:11:31 +1000 Subject: [PATCH 3/4] include/proc_ui: Add basic Doxygen documentation (decaf) From QuarkTheAwesome/decaf-emu@7bc9ced68a0fea628b36a6deb761a5ab6ebf9d09 --- include/proc_ui/procui.h | 96 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) 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); From 31c762ed110527680c7c85b08d898effdf8b68dc Mon Sep 17 00:00:00 2001 From: Ash Date: Sat, 23 Jun 2018 20:13:38 +1000 Subject: [PATCH 4/4] include/coreinit: Start documenting OS* memory functions (decaf) From QuarkTheAwesome/decaf-emu@865ac43 and QuarkTheAwesome/decaf-emu@81cd110 --- include/coreinit/memory.h | 82 ++++++++++++++++++++++++ include/coreinit/memorymap.h | 117 +++++++++++++++++++++++++++++++++++ 2 files changed, 199 insertions(+) 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);