Update docs, update telnet example to use pthread_create.c

Author: maximecb

docs/syscalls.md

@@ -84,7 +84,7 @@ u64 thread_spawn(void* fptr, void* arg)
 
 **Returns:** `u64 tid`
 
-Spawn a new thread running the given function with the argument value `arg`.
+Spawn a new thread running the given function with the argument value `arg`. This is a low-level primitive: the spawned thread has no software (alloca) stack, so a C thread function that uses local arrays, address-taken locals, or alloca will fault. From C, prefer pthread_create() from <pthread.h>, which installs a private stack for the new thread.
 
 ## thread_id
 
@@ -112,7 +112,7 @@ u64 thread_join(u64 tid)
 
 **Returns:** `u64 val`
 
-Join on the thread with the given id. Produces the return value for the thread.
+Join on the thread with the given id (as returned by thread_spawn). Produces the return value for the thread. From C, prefer pthread_join() from <pthread.h> when the thread was created with pthread_create().
 
 ## cmd_argc
 

ncc/include/uvm/syscalls.h

@@ -50,7 +50,7 @@ extern void __uvm_exit(int8_t __status);
 #define exit(__status) __uvm_exit(__status)
 
 // u64 thread_spawn(void* fptr, void* arg)
-// Spawn a new thread running the given function with the argument value `arg`.
+// Spawn a new thread running the given function with the argument value `arg`. This is a low-level primitive: the spawned thread has no software (alloca) stack, so a C thread function that uses local arrays, address-taken locals, or alloca will fault. From C, prefer pthread_create() from <pthread.h>, which installs a private stack for the new thread.
 extern uint64_t __uvm_thread_spawn(void* __fptr, void* __arg);
 #define thread_spawn(__fptr, __arg) __uvm_thread_spawn(__fptr, __arg)
 
@@ -65,7 +65,7 @@ extern void __uvm_thread_sleep(uint64_t __time_ms);
 #define thread_sleep(__time_ms) __uvm_thread_sleep(__time_ms)
 
 // u64 thread_join(u64 tid)
-// Join on the thread with the given id. Produces the return value for the thread.
+// Join on the thread with the given id (as returned by thread_spawn). Produces the return value for the thread. From C, prefer pthread_join() from <pthread.h> when the thread was created with pthread_create().
 extern uint64_t __uvm_thread_join(uint64_t __tid);
 #define thread_join(__tid) __uvm_thread_join(__tid)
 
@@ -261,7 +261,7 @@ extern uint64_t __uvm_file_size(uint64_t __handle);
 #define exit(__status) asm (__status) -> void { syscall exit; }
 
 // u64 thread_spawn(void* fptr, void* arg)
-// Spawn a new thread running the given function with the argument value `arg`.
+// Spawn a new thread running the given function with the argument value `arg`. This is a low-level primitive: the spawned thread has no software (alloca) stack, so a C thread function that uses local arrays, address-taken locals, or alloca will fault. From C, prefer pthread_create() from <pthread.h>, which installs a private stack for the new thread.
 #define thread_spawn(__fptr, __arg) asm (__fptr, __arg) -> u64 { syscall thread_spawn; }
 
 // u64 thread_id()
@@ -273,7 +273,7 @@ extern uint64_t __uvm_file_size(uint64_t __handle);
 #define thread_sleep(__time_ms) asm (__time_ms) -> void { syscall thread_sleep; }
 
 // u64 thread_join(u64 tid)
-// Join on the thread with the given id. Produces the return value for the thread.
+// Join on the thread with the given id (as returned by thread_spawn). Produces the return value for the thread. From C, prefer pthread_join() from <pthread.h> when the thread was created with pthread_create().
 #define thread_join(__tid) asm (__tid) -> u64 { syscall thread_join; }
 
 // u64 cmd_argc()

spec/syscalls.json

@@ -160,7 +160,7 @@
         ],
         "permission": "default_allowed",
         "const_idx": 29,
-        "description": "Spawn a new thread running the given function with the argument value `arg`."
+        "description": "Spawn a new thread running the given function with the argument value `arg`. This is a low-level primitive: the spawned thread has no software (alloca) stack, so a C thread function that uses local arrays, address-taken locals, or alloca will fault. From C, prefer pthread_create() from <pthread.h>, which installs a private stack for the new thread."
       },
       {
         "name": "thread_id",
@@ -203,7 +203,7 @@
         ],
         "permission": "default_allowed",
         "const_idx": 31,
-        "description": "Join on the thread with the given id. Produces the return value for the thread."
+        "description": "Join on the thread with the given id (as returned by thread_spawn). Produces the return value for the thread. From C, prefer pthread_join() from <pthread.h> when the thread was created with pthread_create()."
       },
       {
         "name": "cmd_argc",

uvclang/examples/telnet_server.c

@@ -3,23 +3,25 @@
 //
 // This shows the blocking UVM networking API: net_accept blocks until a client
 // connects, and net_read blocks until data arrives. To serve several clients
-// at once, the server spawns one thread per connection instead of relying on
+// at once, the server spawns one pthread per connection instead of relying on
 // callbacks. Fallible calls report errors with negative return values
 // (NET_ERROR, NET_TIMEOUT); see <uvm/syscalls.h>.
 //
 
 #include <stdint.h>
 #include <stdio.h>
 #include <string.h>
+#include <pthread.h>
 #include <uvm/syscalls.h>
 
 // Handle a single client connection.
 //
-// One instance of this function runs per client, each on its own thread, so
+// One instance of this function runs per client, each on its own pthread, so
 // multiple clients can be served concurrently. The server echoes a reply for
 // each message and closes the connection when the client sends "exit".
-uint64_t handle_conn(uint64_t sock)
+void *handle_conn(void *arg)
 {
+    int64_t sock = (int64_t)arg;
     char read_buf[1024];
 
     for (;;)
@@ -85,7 +87,12 @@ int main(void)
         }
 
         printf("new connection from %s\n", client_addr);
-        thread_spawn((void *)handle_conn, (void *)conn_sock);
+
+        // Serve this client on its own thread. pthread_create gives the thread a
+        // private stack for handle_conn's locals (read_buf, etc.); the raw
+        // thread_spawn syscall does not, so alloca-bearing code must use pthreads.
+        pthread_t thread;
+        pthread_create(&thread, NULL, handle_conn, (void *)conn_sock);
     }
 
     return 0;

uvclang/include/uvm/syscalls.h

@@ -50,7 +50,7 @@ extern void __uvm_exit(int8_t __status);
 #define exit(__status) __uvm_exit(__status)
 
 // u64 thread_spawn(void* fptr, void* arg)
-// Spawn a new thread running the given function with the argument value `arg`.
+// Spawn a new thread running the given function with the argument value `arg`. This is a low-level primitive: the spawned thread has no software (alloca) stack, so a C thread function that uses local arrays, address-taken locals, or alloca will fault. From C, prefer pthread_create() from <pthread.h>, which installs a private stack for the new thread.
 extern uint64_t __uvm_thread_spawn(void* __fptr, void* __arg);
 #define thread_spawn(__fptr, __arg) __uvm_thread_spawn(__fptr, __arg)
 
@@ -65,7 +65,7 @@ extern void __uvm_thread_sleep(uint64_t __time_ms);
 #define thread_sleep(__time_ms) __uvm_thread_sleep(__time_ms)
 
 // u64 thread_join(u64 tid)
-// Join on the thread with the given id. Produces the return value for the thread.
+// Join on the thread with the given id (as returned by thread_spawn). Produces the return value for the thread. From C, prefer pthread_join() from <pthread.h> when the thread was created with pthread_create().
 extern uint64_t __uvm_thread_join(uint64_t __tid);
 #define thread_join(__tid) __uvm_thread_join(__tid)
 
@@ -261,7 +261,7 @@ extern uint64_t __uvm_file_size(uint64_t __handle);
 #define exit(__status) asm (__status) -> void { syscall exit; }
 
 // u64 thread_spawn(void* fptr, void* arg)
-// Spawn a new thread running the given function with the argument value `arg`.
+// Spawn a new thread running the given function with the argument value `arg`. This is a low-level primitive: the spawned thread has no software (alloca) stack, so a C thread function that uses local arrays, address-taken locals, or alloca will fault. From C, prefer pthread_create() from <pthread.h>, which installs a private stack for the new thread.
 #define thread_spawn(__fptr, __arg) asm (__fptr, __arg) -> u64 { syscall thread_spawn; }
 
 // u64 thread_id()
@@ -273,7 +273,7 @@ extern uint64_t __uvm_file_size(uint64_t __handle);
 #define thread_sleep(__time_ms) asm (__time_ms) -> void { syscall thread_sleep; }
 
 // u64 thread_join(u64 tid)
-// Join on the thread with the given id. Produces the return value for the thread.
+// Join on the thread with the given id (as returned by thread_spawn). Produces the return value for the thread. From C, prefer pthread_join() from <pthread.h> when the thread was created with pthread_create().
 #define thread_join(__tid) asm (__tid) -> u64 { syscall thread_join; }
 
 // u64 cmd_argc()