diff --git a/nx/include/switch/kernel/shmem.h b/nx/include/switch/kernel/shmem.h index 25c77681..12ccdd95 100644 --- a/nx/include/switch/kernel/shmem.h +++ b/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); diff --git a/nx/include/switch/kernel/thread.h b/nx/include/switch/kernel/thread.h index b80d13fd..da146b29 100644 --- a/nx/include/switch/kernel/thread.h +++ b/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); diff --git a/nx/include/switch/kernel/tmem.h b/nx/include/switch/kernel/tmem.h index 0fda4686..e893424c 100644 --- a/nx/include/switch/kernel/tmem.h +++ b/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); diff --git a/nx/include/switch/kernel/virtmem.h b/nx/include/switch/kernel/virtmem.h index a41161e2..f5cec3a6 100644 --- a/nx/include/switch/kernel/virtmem.h +++ b/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); diff --git a/nx/source/kernel/shmem.c b/nx/source/kernel/shmem.c index db25070e..15c1a121 100644 --- a/nx/source/kernel/shmem.c +++ b/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; diff --git a/nx/source/kernel/tmem.c b/nx/source/kernel/tmem.c index 24dc66a1..338a1e07 100644 --- a/nx/source/kernel/tmem.c +++ b/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;