include/coreinit: Start documenting OS* memory functions (decaf)

From QuarkTheAwesome/decaf-emu@865ac43 and
QuarkTheAwesome/decaf-emu@81cd110

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,

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);