Document kernel/: shmem.h, thread.h, tmem.h, virtmem.h

nx/include/switch/kernel/shmem.h

@@ -1,18 +1,67 @@
+/**
+ * @file shmem.h
+ * @brief Shared memory object handling
+ * @author plutoo
+ * @copyright libnx Authors
+ * @remark Shared memory differs from transfer memory in the fact that the kernel (as opposed to the user process) allocates and owns its backing memory.
+ */
 #pragma once
 #include "../types.h"
 
+/// Shared memory information structure.
 typedef struct {
-    Handle      handle;
-    size_t      size;
-    Permission  perm;
-    void*       map_addr;
+    Handle      handle;   ///< Kernel object handle.
+    size_t      size;     ///< Size of the shared memory object.
+    Permission  perm;     ///< Permissions.
+    void*       map_addr; ///< Address to which the shared memory object is mapped.
 } SharedMemory;
 
+/**
+ * @brief Creates a shared memory object.
+ * @param s Shared memory information structure which will be filled in.
+ * @param size Size of the shared memory object to create.
+ * @param local_perm Permissions with which the shared memory object will be mapped in the local process.
+ * @param remote_perm Permissions with which the shared memory object will be mapped in the remote process.
+ * @return Result code.
+ * @warning This is a privileged operation; in normal circumstances applications cannot use this function.
+ */
 Result shmemCreate(SharedMemory* s, size_t size, Permission local_perm, Permission remote_perm);
-void shmemLoadRemote(SharedMemory* t, Handle handle, size_t size, Permission perm);
 
-Result shmemMap(SharedMemory* t);
-Result shmemUnmap(SharedMemory* t);
-void*  shmemGetAddr(SharedMemory* t);
+/**
+ * @brief Loads a shared memory object coming from a remote process.
+ * @param s Shared memory information structure which will be filled in.
+ * @param handle Handle of the shared memory object.
+ * @param size Size of the shared memory object to create.
+ * @param perm Permissions with which the shared memory object will be mapped in the local process.
+ */
+void shmemLoadRemote(SharedMemory* s, Handle handle, size_t size, Permission perm);
 
-Result shmemClose(SharedMemory* t);
+/**
+ * @brief Maps a shared memory object.
+ * @param s Shared memory information structure.
+ * @return Result code.
+ */
+Result shmemMap(SharedMemory* s);
+
+/**
+ * @brief Unmaps a shared memory object.
+ * @param s Shared memory information structure.
+ * @return Result code.
+ */
+Result shmemUnmap(SharedMemory* s);
+
+/**
+ * @brief Retrieves the mapped address of a shared memory object.
+ * @param s Shared memory information structure.
+ * @return Mapped address of the shared memory object.
+ */
+static inline void* shmemGetAddr(SharedMemory* s) {
+    return s->map_addr;
+}
+
+/**
+ * @brief Frees up resources used by a shared memory object, unmapping and closing handles, etc.
+ * @param s Shared memory information structure.
+ * @return Result code.
+ */
+Result shmemClose(SharedMemory* s);

nx/include/switch/kernel/thread.h

@@ -1,20 +1,67 @@
+/**
+ * @file thread.h
+ * @brief Multi-threading support
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 
+/// Thread information structure.
 typedef struct {
-    Handle     handle;
-    void*      stack_mem;
-    void*      stack_mirror;
-    size_t     stack_sz;
+    Handle handle;       ///< Thread handle.
+    void*  stack_mem;    ///< Pointer to stack memory.
+    void*  stack_mirror; ///< Pointer to stack memory mirror.
+    size_t stack_sz;     ///< Stack size.
 } Thread;
 
+/**
+ * @brief Creates a thread.
+ * @param t Thread information structure which will be filled in.
+ * @param entry Entrypoint of the thread.
+ * @param arg Argument to pass to the entrypoint.
+ * @param stack_sz Stack size (rounded up to page alignment).
+ * @param prio Thread priority (0x00~0x3F); 0x2C is the usual priority of the main thread.
+ * @param cpuid ID of the core on which to create the thread (0~3); or -2 to use the default core for the current process.
+ * @return Result code.
+ */
 Result threadCreate(
     Thread* t, ThreadFunc entry, void* arg, size_t stack_sz, int prio,
     int cpuid);
 
+/**
+ * @brief Starts the execution of a thread.
+ * @param t Thread information structure.
+ * @return Result code.
+ */
 Result threadStart(Thread* t);
+
+/**
+ * @brief Waits for a thread to finish executing.
+ * @param t Thread information structure.
+ * @return Result code.
+ */
 Result threadWaitForExit(Thread* t);
+
+/**
+ * @brief Frees up resources associated with a thread.
+ * @param t Thread information structure.
+ * @return Result code.
+ */
 Result threadClose(Thread* t);
 
+/**
+ * @brief Pauses the execution of a thread.
+ * @param t Thread information structure.
+ * @return Result code.
+ * @warning This is a privileged operation; in normal circumstances applications cannot use this function.
+ */
 Result threadPause(Thread* t);
+
+/**
+ * @brief Resumes the execution of a thread, after having been paused.
+ * @param t Thread information structure.
+ * @return Result code.
+ * @warning This is a privileged operation; in normal circumstances applications cannot use this function.
+ */
 Result threadResume(Thread* t);

nx/include/switch/kernel/tmem.h

@@ -1,19 +1,69 @@
+/**
+ * @file tmem.h
+ * @brief Transfer memory handling
+ * @author plutoo
+ * @copyright libnx Authors
+ * @remark Transfer memory differs from shared memory in the fact that the user process (as opposed to the kernel) allocates and owns its backing memory.
+ */
 #pragma once
 #include "../types.h"
 
+/// Transfer memory information structure.
 typedef struct {
-    Handle      handle;
-    size_t      size;
-    Permission  perm;
-    void*       src_addr;
-    void*       map_addr;
+    Handle      handle;   ///< Kernel object handle.
+    size_t      size;     ///< Size of the transfer memory object.
+    Permission  perm;     ///< Permissions of the transfer memory object.
+    void*       src_addr; ///< Address of the source backing memory.
+    void*       map_addr; ///< Address to which the transfer memory object is mapped.
 } TransferMemory;
 
+/**
+ * @brief Creates a transfer memory object.
+ * @param t Transfer memory information structure that will be filled in.
+ * @param size Size of the transfer memory object to create.
+ * @param perm Permissions to assign to the transfer memory object.
+ * @return Result code.
+ */
 Result tmemCreate(TransferMemory* t, size_t size, Permission perm);
-void   tmemLoadRemote(TransferMemory* t, Handle handle, size_t size, Permission perm);
 
+/**
+ * @brief Loads a transfer memory object coming from a remote process.
+ * @param t Transfer memory information structure which will be filled in.
+ * @param handle Handle of the transfer memory object.
+ * @param size Size of the transfer memory object to create.
+ * @param perm Permissions with which the transfer memory object will be mapped in the local process.
+ * @warning This is a privileged operation; in normal circumstances applications shouldn't use this function.
+ */
+void tmemLoadRemote(TransferMemory* t, Handle handle, size_t size, Permission perm);
+
+/**
+ * @brief Maps a transfer memory object.
+ * @param t Transfer memory information structure.
+ * @return Result code.
+ * @warning This is a privileged operation; in normal circumstances applications cannot use this function.
+ */
 Result tmemMap(TransferMemory* t);
-Result tmemUnmap(TransferMemory* t);
-void*  tmemGetAddr(TransferMemory* t);
 
+/**
+ * @brief Unmaps a transfer memory object.
+ * @param t Transfer memory information structure.
+ * @return Result code.
+ * @warning This is a privileged operation; in normal circumstances applications cannot use this function.
+ */
+Result tmemUnmap(TransferMemory* t);
+
+/**
+ * @brief Retrieves the mapped address of a transfer memory object.
+ * @param t Transfer memory information structure.
+ * @return Mapped address of the transfer memory object.
+ */
+static inline void* tmemGetAddr(TransferMemory* t){
+    return t->map_addr;
+}
+
+/**
+ * @brief Frees up resources used by a transfer memory object, unmapping and closing handles, etc.
+ * @param t Transfer memory information structure.
+ * @return Result code.
+ */
 Result tmemClose(TransferMemory* t);

nx/include/switch/kernel/virtmem.h

@@ -1,8 +1,36 @@
+/**
+ * @file virtmem.h
+ * @brief Virtual memory mapping utilities
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 
+/**
+ * @brief Reserves a slice of general purpose address space.
+ * @param size The size of the slice of address space that will be reserved (rounded up to page alignment).
+ * @return Pointer to the slice of address space, or NULL on failure.
+ */
 void* virtmemReserve(size_t size);
+
+/**
+ * @brief Relinquishes a slice of address space reserved with virtmemReserve (currently no-op).
+ * @param addr Pointer to the slice.
+ * @param size Size of the slice.
+ */
 void  virtmemFree(void* addr, size_t size);
 
+/**
+ * @brief Reserves a slice of address space inside the alias memory mapping region(s) (for use with svcMapMemory).
+ * @param size The size of the slice of address space that will be reserved (rounded up to page alignment).
+ * @return Pointer to the slice of address space, or NULL on failure.
+ */
 void* virtmemReserveMap(size_t size);
+
+/**
+ * @brief Relinquishes a slice of address space reserved with virtmemReserveMap (currently no-op).
+ * @param addr Pointer to the slice.
+ * @param size Size of the slice.
+ */
 void  virtmemFreeMap(void* addr, size_t size);

nx/source/kernel/shmem.c

@@ -66,10 +66,6 @@ Result shmemUnmap(SharedMemory* s)
     return rc;
 }
 
-void* shmemGetAddr(SharedMemory* s) {
-    return s->map_addr;
-}
-
 Result shmemClose(SharedMemory* s)
 {
     Result rc = 0;

nx/source/kernel/tmem.c

@@ -74,10 +74,6 @@ Result tmemUnmap(TransferMemory* t)
     return rc;
 }
 
-void* tmemGetAddr(TransferMemory* t) {
-    return t->map_addr;
-}
-
 Result tmemClose(TransferMemory* t)
 {
     Result rc = 0;