Document kernel/: detect.h, jit.h, mutex.h, random.h, rwlock.h

nx/include/switch/kernel/detect.h

@@ -1,8 +1,17 @@
-// Copyright 2017 plutoo
+/**
+ * @file detect.h
+ * @brief Kernel version detection
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 
+/// Returns true if the kernel version is equal to or above 2.0.0.
 bool kernelAbove200(void);
+/// Returns true if the kernel version is equal to or above 3.0.0.
 bool kernelAbove300(void);
+/// Returns true if the kernel version is equal to or above 2.0.0.
 bool kernelAbove400(void);
+/// Returns true if code is running under a debugger.
 bool detectDebugger(void);

nx/include/switch/kernel/jit.h

@@ -1,12 +1,19 @@
-// Copyright 2018 plutoo
+/**
+ * @file jit.h
+ * @brief Just-in-time compilation support.
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 
+/// JIT implementation type.
 typedef enum {
-    JitType_CodeMemory,
+    JitType_CodeMemory, ///< JIT supported using svcSetProcessMemoryPermission
-    JitType_JitMemory
+    JitType_JitMemory,  ///< JIT supported using 4.0.0+ JIT syscalls.
 } JitType;
 
+/// JIT buffer object.
 typedef struct {
     JitType type;
     size_t  size;
@@ -16,10 +23,45 @@ typedef struct {
     Handle  handle;
 } Jit;
 
+/**
+ * @brief Creates a JIT buffer.
+ * @param j JIT buffer.
+ * @param size Size of the JIT buffer.
+ * @return Result code.
+ */
 Result jitCreate(Jit* j, size_t size);
+
+/**
+ * @brief Transition a JIT buffer to have writable permission.
+ * @param j JIT buffer.
+ * @return Result code.
+ */
 Result jitTransitionToWritable(Jit* j);
+
+/**
+ * @brief Transition a JIT buffer to have executable permission.
+ * @param j JIT buffer.
+ * @return Result code.
+ */
 Result jitTransitionToExecutable(Jit* j);
+
+/**
+ * @brief Destroys a JIT buffer.
+ * @param j JIT buffer.
+ * @return Result code.
+ */
 Result jitClose(Jit* j);
 
+/**
+ * @brief Gets the address of the writable memory alias of a JIT buffer.
+ * @param j JIT buffer.
+ * @return Pointer to alias of the JIT buffer that can be written to.
+ */
 void* jitGetRwAddr(Jit* j);
+
+/**
+ * @brief Gets the address of the executable memory alias of a JIT buffer.
+ * @param j JIT buffer.
+ * @return Pointer to alias of the JIT buffer that can be executed.
+ */
 void* jitGetRxAddr(Jit* j);

nx/include/switch/kernel/mutex.h

@@ -1,19 +1,43 @@
-// Copyright 2017 plutoo
+/**
+ * @file mutex.h
+ * @brief Mutex synchronization primitive.
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include <sys/lock.h>
 #include "../types.h" // not needed in this file, still including it
 
+/// Mutex datatype, defined in newlib.
 typedef _LOCK_T Mutex;
+/// Recursive mutex datatype, defined in newlib.
 typedef _LOCK_RECURSIVE_T RMutex;
 
+/**
+ * @brief Initializes a mutex.
+ * @param m Mutex object.
+ */
 static inline void mutexInit(Mutex* m)
 {
     *m = 0;
 }
 
+/**
+ * @brief Locks a mutex.
+ * @param m Mutex object.
+ */
 void mutexLock(Mutex* m);
+
+/**
+ * @brief Unlocks a mutex.
+ * @param m Mutex object.
+ */
 void mutexUnlock(Mutex* m);
 
+/**
+ * @brief Initializes a recursive mutex.
+ * @param m Recursive mutex object.
+ */
 static inline void rmutexInit(RMutex* m)
 {
     m->lock = 0;
@@ -21,5 +45,14 @@ static inline void rmutexInit(RMutex* m)
     m->counter = 0;
 }
 
+/**
+ * @brief Locks a recursive mutex.
+ * @param m Recursive mutex object.
+ */
 void rmutexLock(RMutex* m);
+
+/**
+ * @brief Unlocks a recursive mutex.
+ * @param m Recursive mutex object.
+ */
 void rmutexUnlock(RMutex* m);

nx/include/switch/kernel/random.h

@@ -1,6 +1,21 @@
-// Copyright 2018 plutoo
+/**
+ * @file random.h
+ * @brief OS-seeded pseudo-random number generation support (ChaCha algorithm).
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../types.h"
 
-void randomGet(u8* buf, size_t len);
+/**
+ * @brief Fills a buffer with random data.
+ * @param buf Pointer to the buffer.
+ * @param len Size of the buffer in bytes.
+ */
+void randomGet(void* buf, size_t len);
+
+/**
+ * @brief Returns a random 64-bit value.
+ * @return Random value.
+ */
 u64  randomGet64(void);

nx/include/switch/kernel/rwlock.h

@@ -1,15 +1,39 @@
-// Copyright 2018 plutoo
+/**
+ * @file rwlock.h
+ * @brief Read/write lock synchronization primitive.
+ * @author plutoo
+ * @copyright libnx Authors
+ */
 #pragma once
 #include "../kernel/mutex.h"
 
+/// Read/write lock structure.
 typedef struct {
     RMutex r;
     RMutex g;
     u64 b;
 } RwLock;
 
+/**
+ * @brief Locks the read/write lock for reading.
+ * @param r Read/write lock object.
+ */
 void rwlockReadLock(RwLock* r);
+
+/**
+ * @brief Unlocks the read/write lock for reading.
+ * @param r Read/write lock object.
+ */
 void rwlockReadUnlock(RwLock* r);
 
+/**
+ * @brief Locks the read/write lock for writing.
+ * @param r Read/write lock object.
+ */
 void rwlockWriteLock(RwLock* r);
+
+/**
+ * @brief Unlocks the read/write lock for writing.
+ * @param r Read/write lock object.
+ */
 void rwlockWriteUnlock(RwLock* r);

nx/source/kernel/random.c

@@ -146,14 +146,14 @@ static void _randomInit(void)
     g_randInit = true;
 }
 
-void randomGet(u8* buf, size_t len)
+void randomGet(void* buf, size_t len)
 {
     mutexLock(&g_randMutex);
 
     _randomInit();
 
     memset(buf, 0, len);
-    chachaEncrypt(&g_chacha, buf, buf, len);
+    chachaEncrypt(&g_chacha, (const u8*)buf, (u8*)buf, len);
 
     mutexUnlock(&g_randMutex);
 }
@@ -161,6 +161,6 @@ void randomGet(u8* buf, size_t len)
 u64 randomGet64(void)
 {
     u64 tmp;
-    randomGet((u8*) &tmp, sizeof(tmp));
+    randomGet(&tmp, sizeof(tmp));
     return tmp;
 }