rewrite comments into one, unified style

code/user/personalities/posix/posix.h

@@ -1,3 +1,5 @@
+// POSIX compatibility support for posix.
+
 #pragma once
 // posix.h - POSIX type and constant definitions for posix.dll
 // Covers just what open/read/write/close/lseek/spawn/pthread/chdir need.
@@ -6,9 +8,7 @@
 #include <stddef.h>
 #include <stdbool.h>
 
-// ---------------------------------------------------------------------------
-// errno
-// ---------------------------------------------------------------------------
+// errno.
 #ifdef errno
 #undef errno
 #endif
@@ -59,9 +59,7 @@ extern int errno;   // defined in posix_fd.c; single global in v1
 #define ETIMEDOUT 116
 #define ECONNRESET 104
 
-// ---------------------------------------------------------------------------
-// open() flags
-// ---------------------------------------------------------------------------
+// open() flags.
 #define O_RDONLY    0x0000
 #define O_WRONLY    0x0001
 #define O_RDWR      0x0002
@@ -69,25 +67,19 @@ extern int errno;   // defined in posix_fd.c; single global in v1
 #define O_TRUNC     0x0200
 #define O_APPEND    0x0400
 
-// ---------------------------------------------------------------------------
-// lseek() whence
-// ---------------------------------------------------------------------------
+// lseek() whence.
 #define SEEK_SET 0
 #define SEEK_CUR 1
 #define SEEK_END 2
 
-// ---------------------------------------------------------------------------
-// Scalar types
-// ---------------------------------------------------------------------------
+// Scalar types.
 typedef int32_t  pid_t;
 typedef int32_t  off_t;
 typedef uint32_t mode_t;
 typedef int64_t ssize_t;
 
 
-// ---------------------------------------------------------------------------
-// Sockets
-// ---------------------------------------------------------------------------
+// Sockets.
 typedef uint16_t sa_family_t;
 typedef uint16_t in_port_t;
 typedef uint32_t in_addr_t;
@@ -195,25 +187,19 @@ __declspec(dllexport) struct hostent* gethostbyname(const char* name);
 __declspec(dllexport) int getaddrinfo(const char* node, const char* service, const struct addrinfo* hints, struct addrinfo** res);
 __declspec(dllexport) void freeaddrinfo(struct addrinfo* res);
 
-// ---------------------------------------------------------------------------
-// pthread types
-// ---------------------------------------------------------------------------
+// pthread types.
 typedef struct { uint32_t Tid; }     pthread_t;
 typedef struct { uint32_t Handle; }  pthread_mutex_t;
 typedef void*                        pthread_attr_t;     // unused in v1
 typedef void*                        pthread_mutexattr_t;
 
-// ---------------------------------------------------------------------------
-// posix_spawn types  (file_actions and attrp both ignored in v1)
-// ---------------------------------------------------------------------------
+// posix_spawn types  (file_actions and attrp both ignored in v1).
 typedef void* posix_spawn_file_actions_t;
 typedef void* posix_spawnattr_t;
 
 __declspec(dllexport) const char* posix_get_command_line(void);
 
-// ---------------------------------------------------------------------------
-// dirent  (used by posix_dir.c)
-// ---------------------------------------------------------------------------
+// dirent  (used by posix_dir.c).
 #define NAME_MAX 259
 
 typedef struct dirent {

code/user/personalities/posix/posix_dir.c

@@ -1,4 +1,5 @@
-// posix_dir.c - chdir, getcwd, opendir, readdir, closedir
+// POSIX compatibility support for posix dir.
+
 #include <string.h>
 #include <ntlite/syscall.h>
 #include <stdlib.h>
@@ -10,6 +11,7 @@ typedef SYS_DIR_ENTRY KDIR_ENTRY;
 
 #define KATTR_DIR  0x10
 
+// Implements the chdir operation.
 __declspec(dllexport) int chdir(const char* path) {
     char native[512];
     PosixTranslatePath(path, native, sizeof(native));
@@ -19,6 +21,7 @@ __declspec(dllexport) int chdir(const char* path) {
     return 0;
 }
 
+// Implements the getcwd operation.
 __declspec(dllexport) char* getcwd(char* buf, size_t size) {
     if (!buf || size == 0) { errno = EINVAL; return (char*)0; }
     char native[512];
@@ -31,6 +34,7 @@ __declspec(dllexport) char* getcwd(char* buf, size_t size) {
     return buf;
 }
 
+// Implements the opendir operation.
 __declspec(dllexport) DIR* opendir(const char* path) {
     char native[512];
     PosixTranslatePath(path, native, sizeof(native));
@@ -47,6 +51,7 @@ __declspec(dllexport) DIR* opendir(const char* path) {
     return d;
 }
 
+// Implements the readdir operation.
 __declspec(dllexport) struct dirent* readdir(DIR* d) {
     if (!d) { errno = EBADF; return (struct dirent*)0; }
     KDIR_ENTRY ke;
@@ -62,6 +67,7 @@ __declspec(dllexport) struct dirent* readdir(DIR* d) {
     return &d->Current;
 }
 
+// Implements the closedir operation.
 __declspec(dllexport) int closedir(DIR* d) {
     if (!d) { errno = EBADF; return -1; }
     SysCloseHandle(d->KHandle);

code/user/personalities/posix/posix_fd.c

@@ -1,10 +1,12 @@
-// posix_fd.c - file descriptor table
+// POSIX compatibility support for posix fd.
+
 #include <ntlite/syscall.h>
 #include "posix.h"
 #include "posix_fd.h"
 
 int errno = 0;
 
+// Implements the status To Errno operation.
 int PosixStatusToErrno(uint32_t s) {
     switch (s) {
         case 0x0000: return 0;       // STATUS_SUCCESS
@@ -26,6 +28,7 @@ int PosixStatusToErrno(uint32_t s) {
 
 static FD_ENTRY gFdTable[FD_TABLE_PIDS][FD_MAX];
 
+// Implements the fd Init operation.
 __declspec(dllexport) void PosixFdInit(void) {
     uint32_t pid = SysGetCurrentPid();
     uint32_t slot = pid % FD_TABLE_PIDS;
@@ -40,6 +43,7 @@ __declspec(dllexport) void PosixFdInit(void) {
     gFdTable[slot][2] = (FD_ENTRY){ FD_CONSOLE_W, 0, true };
 }
 
+// Implements the fd Alloc operation.
 __declspec(dllexport) int FdAlloc(uint32_t pid, FD_TYPE type, uint32_t khandle) {
     uint32_t slot = pid % FD_TABLE_PIDS;
     for (int fd = 3; fd < FD_MAX; fd++) {
@@ -52,6 +56,7 @@ __declspec(dllexport) int FdAlloc(uint32_t pid, FD_TYPE type, uint32_t khandle)
     return -1;
 }
 
+// Implements the fd Get operation.
 __declspec(dllexport) FD_ENTRY* FdGet(uint32_t pid, int fd) {
     if (fd < 0 || fd >= FD_MAX) { errno = EBADF; return (FD_ENTRY*)0; }
     uint32_t slot = pid % FD_TABLE_PIDS;
@@ -60,6 +65,7 @@ __declspec(dllexport) FD_ENTRY* FdGet(uint32_t pid, int fd) {
     return e;
 }
 
+// Implements the fd Free operation.
 __declspec(dllexport) void FdFree(uint32_t pid, int fd) {
     if (fd < 0 || fd >= FD_MAX) return;
     uint32_t slot = pid % FD_TABLE_PIDS;

code/user/personalities/posix/posix_fd.h

@@ -1,5 +1,7 @@
+// POSIX compatibility support for posix fd.
+
 #pragma once
-// posix_fd.h - file descriptor table (internal to posix.dll)
+// posix_fd.h - file descriptor table (internal to posix.dll).
 #include <stdint.h>
 #include <stdbool.h>
 

code/user/personalities/posix/posix_io.c

@@ -1,4 +1,5 @@
-// posix_io.c - open, read, write, close, lseek
+// POSIX compatibility support for posix io.
+
 #include <stddef.h>
 #include <string.h>
 #include <ntlite/syscall.h>
@@ -6,14 +7,17 @@
 #include "posix_fd.h"
 #include "posix_path.h"
 
+// Implements the clearscreen operation.
 __declspec(dllexport) void clearscreen(void) {
     SysClearScreen(0x012456);
 }
 
+// Implements the clearkeyboard operation.
 __declspec(dllexport) void clearkeyboard(void) {
     while (SysPollKeyboard()) (void)SysReadKeyboardChar();
 }
 
+// Opens the requested operation.
 __declspec(dllexport) int open(const char* path, int flags, ...) {
     char native[512];
     const char* p = PosixTranslatePath(path, native, sizeof(native));
@@ -21,7 +25,7 @@ __declspec(dllexport) int open(const char* path, int flags, ...) {
     uint32_t pid = SysGetCurrentPid();
     FD_TYPE type = FD_FILE;
 
-    // Synthetic devices
+    // Synthetic devices.
     if (strcmp(p, SYNTH_DEVNULL) == 0) {
         int fd = FdAlloc(pid, FD_DEVNULL, 0);
         return fd;
@@ -53,6 +57,7 @@ __declspec(dllexport) int open(const char* path, int flags, ...) {
     return fd;
 }
 
+// Returns the requested value.
 __declspec(dllexport) ssize_t read(int fd, void* buf, size_t count) {
     if (count == 0) return 0;
     uint32_t pid = SysGetCurrentPid();
@@ -92,6 +97,7 @@ __declspec(dllexport) ssize_t read(int fd, void* buf, size_t count) {
     }
 }
 
+// Updates the requested value.
 __declspec(dllexport) ssize_t write(int fd, const void* buf, size_t count) {
     if (count == 0) return 0;
     uint32_t pid = SysGetCurrentPid();
@@ -125,6 +131,7 @@ __declspec(dllexport) ssize_t write(int fd, const void* buf, size_t count) {
     }
 }
 
+// Releases the requested object.
 __declspec(dllexport) int close(int fd) {
     uint32_t pid = SysGetCurrentPid();
     FD_ENTRY* e = FdGet(pid, fd);
@@ -135,6 +142,7 @@ __declspec(dllexport) int close(int fd) {
     return 0;
 }
 
+// Implements the unlink operation.
 __declspec(dllexport) int unlink(const char* path) {
     if (!path) { errno = EINVAL; return -1; }
 
@@ -152,6 +160,7 @@ __declspec(dllexport) int unlink(const char* path) {
     return 0;
 }
 
+// Implements the lseek operation.
 __declspec(dllexport) off_t lseek(int fd, off_t offset, int whence) {
     uint32_t pid = SysGetCurrentPid();
     FD_ENTRY* e = FdGet(pid, fd);

code/user/personalities/posix/posix_path.c

@@ -1,12 +1,15 @@
-// posix_path.c - POSIX <-> native path translation
+// POSIX compatibility support for posix path.
+
 #include <stddef.h>
 #include <string.h>
 #include "posix_path.h"
 
+// Implements the flip Slashes operation.
 static void FlipSlashes(char* s) {
     for (; *s; s++) if (*s == '/') *s = '\\';
 }
 
+// Checks whether drive Mount.
 static int IsDriveMount(const char* p) {
     return p && p[0] == '/' && p[1] >= '0' && p[1] <= '7' &&
            (p[2] == '\0' || p[2] == '/');
@@ -50,6 +53,7 @@ const char* PosixTranslatePath(const char* in, char* out, size_t outSize) {
     return out;
 }
 
+// Implements the native To Posix operation.
 void NativeToPosix(const char* in, char* out, size_t outSize) {
     if (!in || !out || outSize == 0) return;
 

code/user/personalities/posix/posix_path.h

@@ -1,5 +1,7 @@
+// POSIX compatibility support for posix path.
+
 #pragma once
-// posix_path.h - POSIX <-> native path translation
+// posix_path.h - POSIX <-> native path translation.
 
 // SYNTHETIC sentinel returned from PosixTranslatePath for /dev/null and
 // /dev/zero; the caller must handle these before passing to any syscall.

code/user/personalities/posix/posix_proc.c

@@ -1,4 +1,5 @@
-// posix_proc.c - posix_spawn, waitpid, getpid
+// POSIX compatibility support for posix proc.
+
 #include <stddef.h>
 #include <string.h>
 #include <ntlite/syscall.h>
@@ -8,18 +9,20 @@
 
 static SYS_PEB* gProcessPeb = NULL;
 
+// Implements the peb operation.
 static SYS_PEB* PosixPeb(void) {
     if (!gProcessPeb) gProcessPeb = SysGetPeb();
     return gProcessPeb;
 }
 
+// Implements the posix get command line operation.
 __declspec(dllexport) const char* posix_get_command_line(void) {
     SYS_PEB* peb = PosixPeb();
     if (!peb || peb->Magic != SYS_PEB_MAGIC || !peb->CommandLine.Data) return "";
     return peb->CommandLine.Data;
 }
 
-// pid -> proc handle table (user-mode side, for waitpid)
+// pid -> proc handle table (user-mode side, for waitpid).
 #define PROC_TABLE_SIZE 32
 typedef struct { 
     pid_t pid; 
@@ -29,6 +32,7 @@ typedef struct {
 
 static ProcEntry gProcTable[PROC_TABLE_SIZE];
 
+// Implements the proc Table Insert operation.
 static void ProcTableInsert(pid_t pid, uint32_t handle) {
     for (int i = 0; i < PROC_TABLE_SIZE; i++) {
         if (!gProcTable[i].used) {
@@ -39,6 +43,7 @@ static void ProcTableInsert(pid_t pid, uint32_t handle) {
     SysCloseHandle(handle);
 }
 
+// Implements the proc Table Find operation.
 static uint32_t ProcTableFind(pid_t pid) {
     for (int i = 0; i < PROC_TABLE_SIZE; i++)
         if (gProcTable[i].used && gProcTable[i].pid == pid)
@@ -46,6 +51,7 @@ static uint32_t ProcTableFind(pid_t pid) {
     return 0;
 }
 
+// Implements the proc Table Remove operation.
 static void ProcTableRemove(pid_t pid) {
     for (int i = 0; i < PROC_TABLE_SIZE; i++)
         if (gProcTable[i].used && gProcTable[i].pid == pid)
@@ -72,9 +78,7 @@ static void BuildCmdline(char* const argv[], char* out, size_t outSize) {
     if (pos < outSize) out[pos] = '\0';
 }
 
-// ---------------------------------------------------------------------------
-// POSIX API
-// ---------------------------------------------------------------------------
+// POSIX API.
 
 __declspec(dllexport) pid_t getpid(void) {
     return (pid_t)SysGetCurrentPid();
@@ -133,6 +137,7 @@ __declspec(dllexport) pid_t waitpid(pid_t pid, int* status, int options) {
     return pid;
 }
 
+// Implements the exit operation.
 __declspec(dllexport) void exit(int status) {
     SysExitProcess(status);
 }

code/user/personalities/posix/posix_socket.c

@@ -1,4 +1,5 @@
-// posix_socket.c - POSIX-ish socket wrappers over native Sys* sockets.
+// POSIX compatibility support for posix socket.
+
 #include <stddef.h>
 #include <stdlib.h>
 #include <stdint.h>
@@ -7,10 +8,12 @@
 #include "posix.h"
 #include "posix_fd.h"
 
+// Implements the bswap16 operation.
 static uint16_t bswap16(uint16_t x) {
     return (uint16_t)((x << 8) | (x >> 8));
 }
 
+// Implements the bswap32 operation.
 static uint32_t bswap32(uint32_t x) {
     return ((x & 0x000000FFu) << 24) |
            ((x & 0x0000FF00u) << 8)  |
@@ -18,11 +21,16 @@ static uint32_t bswap32(uint32_t x) {
            ((x & 0xFF000000u) >> 24);
 }
 
+// Implements the htons operation.
 __declspec(dllexport) uint16_t htons(uint16_t x) { return bswap16(x); }
+// Implements the ntohs operation.
 __declspec(dllexport) uint16_t ntohs(uint16_t x) { return bswap16(x); }
+// Implements the htonl operation.
 __declspec(dllexport) uint32_t htonl(uint32_t x) { return bswap32(x); }
+// Implements the ntohl operation.
 __declspec(dllexport) uint32_t ntohl(uint32_t x) { return bswap32(x); }
 
+// Parses byte.
 static int ParseByte(const char** p, uint8_t* out) {
     const char* s = *p;
     if (*s < '0' || *s > '9') return 0;
@@ -37,6 +45,7 @@ static int ParseByte(const char** p, uint8_t* out) {
     return 1;
 }
 
+// Parses ipv4 Bytes.
 static int ParseIpv4Bytes(const char* text, uint8_t out[4]) {
     const char* p = text;
     for (int i = 0; i < 4; i++) {
@@ -49,6 +58,7 @@ static int ParseIpv4Bytes(const char* text, uint8_t out[4]) {
     return *p == '\0';
 }
 
+// Implements the inet addr operation.
 __declspec(dllexport) in_addr_t inet_addr(const char* text) {
     uint8_t b[4];
     if (!text || !ParseIpv4Bytes(text, b)) return INADDR_NONE;
@@ -58,6 +68,7 @@ __declspec(dllexport) in_addr_t inet_addr(const char* text) {
     return out;
 }
 
+// Implements the inet ntoa operation.
 __declspec(dllexport) char* inet_ntoa(struct in_addr in) {
     static char buf[16];
     const uint8_t* p = (const uint8_t*)&in.s_addr;
@@ -74,6 +85,7 @@ __declspec(dllexport) char* inet_ntoa(struct in_addr in) {
     return buf;
 }
 
+// Implements the sock Addr To Sys operation.
 static int SockAddrToSys(const struct sockaddr* addr, socklen_t addrlen, SYS_SOCKET_ADDRESS_IPV4* out) {
     if (!addr || !out || addrlen < sizeof(struct sockaddr_in)) { errno = EINVAL; return -1; }
     const struct sockaddr_in* in = (const struct sockaddr_in*)addr;
@@ -90,6 +102,7 @@ static int SockAddrToSys(const struct sockaddr* addr, socklen_t addrlen, SYS_SOC
     return 0;
 }
 
+// Implements the to Sock Addr operation.
 static void SysToSockAddr(const SYS_SOCKET_ADDRESS_IPV4* in, struct sockaddr* addr, socklen_t* addrlen) {
     if (!addr || !addrlen) return;
     if (*addrlen < sizeof(struct sockaddr_in)) {
@@ -109,6 +122,7 @@ static void SysToSockAddr(const SYS_SOCKET_ADDRESS_IPV4* in, struct sockaddr* ad
     *addrlen = sizeof(struct sockaddr_in);
 }
 
+// Implements the socket Fd Get operation.
 static FD_ENTRY* SocketFdGet(int fd) {
     FD_ENTRY* e = FdGet(SysGetCurrentPid(), fd);
     if (!e) return (FD_ENTRY*)0;
@@ -116,6 +130,7 @@ static FD_ENTRY* SocketFdGet(int fd) {
     return e;
 }
 
+// Implements the socket operation.
 __declspec(dllexport) int socket(int domain, int type, int protocol) {
     uint32_t kh = 0;
     uint32_t s = SysCreateSocket((uint32_t)domain, (uint32_t)type, (uint32_t)protocol, &kh);
@@ -129,6 +144,7 @@ __declspec(dllexport) int socket(int domain, int type, int protocol) {
     return fd;
 }
 
+// Implements the bind operation.
 __declspec(dllexport) int bind(int fd, const struct sockaddr* addr, socklen_t addrlen) {
     FD_ENTRY* e = SocketFdGet(fd);
     if (!e) return -1;
@@ -139,6 +155,7 @@ __declspec(dllexport) int bind(int fd, const struct sockaddr* addr, socklen_t ad
     return 0;
 }
 
+// Implements the listen operation.
 __declspec(dllexport) int listen(int fd, int backlog) {
     FD_ENTRY* e = SocketFdGet(fd);
     if (!e) return -1;
@@ -147,6 +164,7 @@ __declspec(dllexport) int listen(int fd, int backlog) {
     return 0;
 }
 
+// Implements the accept operation.
 __declspec(dllexport) int accept(int fd, struct sockaddr* addr, socklen_t* addrlen) {
     FD_ENTRY* e = SocketFdGet(fd);
     if (!e) return -1;
@@ -167,6 +185,7 @@ __declspec(dllexport) int accept(int fd, struct sockaddr* addr, socklen_t* addrl
     return outfd;
 }
 
+// Implements the connect operation.
 __declspec(dllexport) int connect(int fd, const struct sockaddr* addr, socklen_t addrlen) {
     FD_ENTRY* e = SocketFdGet(fd);
     if (!e) return -1;
@@ -177,6 +196,7 @@ __declspec(dllexport) int connect(int fd, const struct sockaddr* addr, socklen_t
     return 0;
 }
 
+// Implements the send operation.
 __declspec(dllexport) ssize_t send(int fd, const void* buf, size_t len, int flags) {
     FD_ENTRY* e = SocketFdGet(fd);
     if (!e) return -1;
@@ -186,6 +206,7 @@ __declspec(dllexport) ssize_t send(int fd, const void* buf, size_t len, int flag
     return (ssize_t)sent;
 }
 
+// Implements the recv operation.
 __declspec(dllexport) ssize_t recv(int fd, void* buf, size_t len, int flags) {
     FD_ENTRY* e = SocketFdGet(fd);
     if (!e) return -1;
@@ -240,6 +261,7 @@ __declspec(dllexport) ssize_t recvfrom(int fd, void* buf, size_t len, int flags,
     return (ssize_t)got;
 }
 
+// Implements the shutdown operation.
 __declspec(dllexport) int shutdown(int fd, int how) {
     FD_ENTRY* e = SocketFdGet(fd);
     if (!e) return -1;
@@ -248,12 +270,14 @@ __declspec(dllexport) int shutdown(int fd, int how) {
     return 0;
 }
 
+// Implements the timeval To Ms operation.
 static uint32_t TimevalToMs(const struct timeval* tv) {
     if (!tv) return 0;
     uint64_t ms = (uint64_t)tv->tv_sec * 1000u + (uint64_t)(tv->tv_usec / 1000);
     return ms > 0xFFFFFFFFu ? 0xFFFFFFFFu : (uint32_t)ms;
 }
 
+// Implements the setsockopt operation.
 __declspec(dllexport) int setsockopt(int fd, int level, int optname, const void* optval, socklen_t optlen) {
     if (level != SOL_SOCKET || !optval) { errno = EINVAL; return -1; }
     FD_ENTRY* e = SocketFdGet(fd);
@@ -285,6 +309,7 @@ __declspec(dllexport) int setsockopt(int fd, int level, int optname, const void*
     return 0;
 }
 
+// Implements the getsockopt operation.
 __declspec(dllexport) int getsockopt(int fd, int level, int optname, void* optval, socklen_t* optlen) {
     if (level != SOL_SOCKET || !optval || !optlen) { errno = EINVAL; return -1; }
     FD_ENTRY* e = SocketFdGet(fd);
@@ -322,6 +347,7 @@ __declspec(dllexport) int getsockopt(int fd, int level, int optname, void* optva
     return 0;
 }
 
+// Polls the requested operation.
 __declspec(dllexport) int poll(struct pollfd* fds, nfds_t nfds, int timeout) {
     if (!fds || nfds == 0 || nfds > 64) { errno = EINVAL; return -1; }
 
@@ -370,6 +396,7 @@ __declspec(dllexport) int poll(struct pollfd* fds, nfds_t nfds, int timeout) {
     return out;
 }
 
+// Parses port.
 static unsigned ParsePort(const char* s) {
     unsigned v = 0;
     if (!s) return 0;
@@ -381,6 +408,7 @@ static unsigned ParsePort(const char* s) {
     return *s == '\0' ? v : 0;
 }
 
+// Implements the resolve Name Ipv4 operation.
 static int ResolveNameIpv4(const char* name, SYS_SOCKET_ADDRESS_IPV4* out) {
     uint8_t b[4];
     if (ParseIpv4Bytes(name, b)) {
@@ -402,6 +430,7 @@ static int ResolveNameIpv4(const char* name, SYS_SOCKET_ADDRESS_IPV4* out) {
     return 0;
 }
 
+// Implements the gethostbyname operation.
 __declspec(dllexport) struct hostent* gethostbyname(const char* name) {
     static struct hostent h;
     static char hname[256];
@@ -467,6 +496,7 @@ __declspec(dllexport) int getaddrinfo(const char* node, const char* service,
     return 0;
 }
 
+// Implements the freeaddrinfo operation.
 __declspec(dllexport) void freeaddrinfo(struct addrinfo* res) {
     if (res) free(res);
 }

code/user/personalities/posix/posix_thread.c

@@ -1,10 +1,11 @@
-// posix_thread.c - pthread_create, pthread_join, pthread_exit, pthread_mutex_*
+// POSIX compatibility support for posix thread.
+
 #include <stddef.h>
 #include <stdlib.h>
 #include <ntlite/syscall.h>
 #include "posix.h"
 
-// Thread return-value table (PID-keyed like the fd table)
+// Thread return-value table (PID-keyed like the fd table).
 #define PTHREAD_TABLE_PIDS 32
 #define PTHREAD_TABLE_SIZE 32
 
@@ -16,6 +17,7 @@ typedef struct {
 
 static PTHREAD_SLOT gPthreadTable[PTHREAD_TABLE_PIDS][PTHREAD_TABLE_SIZE];
 
+// Implements the pthread Slot Alloc operation.
 static PTHREAD_SLOT* PthreadSlotAlloc(uint32_t pid, uint32_t tid) {
     PTHREAD_SLOT* table = gPthreadTable[pid % PTHREAD_TABLE_PIDS];
     for (int i = 0; i < PTHREAD_TABLE_SIZE; i++) {
@@ -27,6 +29,7 @@ static PTHREAD_SLOT* PthreadSlotAlloc(uint32_t pid, uint32_t tid) {
     return (PTHREAD_SLOT*)0;
 }
 
+// Implements the pthread Slot Find operation.
 static PTHREAD_SLOT* PthreadSlotFind(uint32_t pid, uint32_t tid) {
     PTHREAD_SLOT* table = gPthreadTable[pid % PTHREAD_TABLE_PIDS];
     for (int i = 0; i < PTHREAD_TABLE_SIZE; i++)
@@ -35,15 +38,14 @@ static PTHREAD_SLOT* PthreadSlotFind(uint32_t pid, uint32_t tid) {
     return (PTHREAD_SLOT*)0;
 }
 
-// ---------------------------------------------------------------------------
-// Trampoline - this is what actually runs as the new thread
-// ---------------------------------------------------------------------------
+// Trampoline - this is what actually runs as the new thread.
 typedef struct {
     void* (*Fn)(void*);
     void*    Arg;
     uint32_t Pid;   // owner pid, for the retval table
 } PTHREAD_TRAMP;
 
+// Implements the pthread Trampoline operation.
 static void PthreadTrampoline(uintptr_t raw) {
     PTHREAD_TRAMP* tr = (PTHREAD_TRAMP*)raw;
     void* (*fn)(void*) = tr->Fn;
@@ -67,9 +69,7 @@ static void PthreadTrampoline(uintptr_t raw) {
     SysExitThread(0);
 }
 
-// ---------------------------------------------------------------------------
-// pthread API
-// ---------------------------------------------------------------------------
+// pthread API.
 
 __declspec(dllexport) int pthread_create(pthread_t* t, const pthread_attr_t* attr,
                    void* (*fn)(void*), void* arg) {
@@ -85,7 +85,7 @@ __declspec(dllexport) int pthread_create(pthread_t* t, const pthread_attr_t* att
 
     uint32_t tid = 0;
     uint32_t s = SysCreateThread((uint64_t)PthreadTrampoline,
-                                  (uint64_t)tr, 1 /*PriorityNormal*/, &tid);
+                                  (uint64_t)tr, 1, &tid);
     if (s != 0) {
         free(tr);
         return EAGAIN;
@@ -96,10 +96,11 @@ __declspec(dllexport) int pthread_create(pthread_t* t, const pthread_attr_t* att
     return 0;
 }
 
+// Implements the pthread join operation.
 __declspec(dllexport) int pthread_join(pthread_t t, void** retval) {
     uint32_t pid = SysGetCurrentPid();
     uint32_t s = SysWaitThread(t.Tid);
-    // STATUS_NOT_FOUND (0x22) means already dead - treat as success
+    // STATUS_NOT_FOUND (0x22) means already dead - treat as success.
     if (s != 0 && s != 0x0022) return ESRCH;
 
     PTHREAD_SLOT* slot = PthreadSlotFind(pid, t.Tid);
@@ -108,6 +109,7 @@ __declspec(dllexport) int pthread_join(pthread_t t, void** retval) {
     return 0;
 }
 
+// Implements the pthread exit operation.
 __declspec(dllexport) void pthread_exit(void* retval) {
     uint32_t pid = SysGetCurrentPid();
     uint32_t tid = SysGetCurrentTid();
@@ -117,6 +119,7 @@ __declspec(dllexport) void pthread_exit(void* retval) {
     while (1);   // unreachable
 }
 
+// Implements the pthread mutex init operation.
 __declspec(dllexport) int pthread_mutex_init(pthread_mutex_t* m, const pthread_mutexattr_t* attr) {
     (void)attr;
     uint32_t h;
@@ -126,22 +129,26 @@ __declspec(dllexport) int pthread_mutex_init(pthread_mutex_t* m, const pthread_m
     return 0;
 }
 
+// Implements the pthread mutex destroy operation.
 __declspec(dllexport) int pthread_mutex_destroy(pthread_mutex_t* m) {
     SysCloseHandle(m->Handle);
     m->Handle = 0;
     return 0;
 }
 
+// Implements the pthread mutex lock operation.
 __declspec(dllexport) int pthread_mutex_lock(pthread_mutex_t* m) {
     uint32_t s = SysAcquireMutex(m->Handle);
     return s == 0 ? 0 : EINVAL;
 }
 
+// Implements the pthread mutex trylock operation.
 __declspec(dllexport) int pthread_mutex_trylock(pthread_mutex_t* m) {
     uint32_t s = SysTryAcquireMutex(m->Handle);
     return s == 0 ? 0 : EAGAIN;
 }
 
+// Implements the pthread mutex unlock operation.
 __declspec(dllexport) int pthread_mutex_unlock(pthread_mutex_t* m) {
     uint32_t s = SysReleaseMutex(m->Handle);
     return s == 0 ? 0 : EINVAL;