From 31c762ed110527680c7c85b08d898effdf8b68dc Mon Sep 17 00:00:00 2001 From: Ash Date: Sat, 23 Jun 2018 20:13:38 +1000 Subject: [PATCH] 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 ff83221..e8805b5 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 fb38fb4..2565c73 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);