πOS — Syscall manual

SYSCALLS(2)πOS Programmer’s ManualSYSCALLS(2)

NAME

syscalls — task creation, scheduling, message passing, and hardware events

SYNOPSIS

#include "kern/syscall.h"

tid_t Create(int priority, void (*function)(void),
             const char* name = nullptr);
int MyTid(void);
int MyParentTid(void);
int MyPriority(void);
int NumTaskRunning(void);
void Yield(void);
void Exit(void);

int Send(tid_t tid, const char* msg, int msglen,
         char* reply, int replylen);
int Receive(tid_t* tid, char* msg, int msglen);
int Reply(tid_t tid, const char* reply, int replylen);
int AwaitEvent(Event_t eventid);

uint32_t MyTime(void);
uint32_t TotalTime(void);
int Quit(void);

tid_t and syscall_return_t are aliases for int. The optional Create name is currently unused.

DESCRIPTION

These C++ calls enter the AArch64 kernel through SVC. The scheduler selects the highest-priority ready task when control returns. Lower priority numbers run first.

Create(priority, fn): Create a task at the given entry point. Priorities are 0–49; lower numbers run first. Returns the new ID, −1 for an invalid priority, or −2 when descriptors are exhausted.
MyTid(): Return the calling task’s ID.
MyParentTid(): Return the ID of the task that created the caller.
MyPriority(): Return the caller’s scheduling priority.
NumTaskRunning(): Count allocated live tasks, including tasks blocked on messages or events.
Yield(): Requeue the caller so another ready task at the same priority can run. Higher-priority ready tasks still run first.
Exit(): End the current task and release its descriptor. Does not return.
Send(tid, msg, msglen, reply, replylen): Copy a message to another task and block until a reply arrives. Returns bytes copied into the reply buffer; −1 for an unknown/dead target, −2 for sending to self.
Receive(&sender, msg, msglen): Wait for a message, copy it into the buffer, and write the sender’s ID. Returns bytes copied. The sender remains blocked until Reply.
Reply(tid, reply, replylen): Copy a reply to a reply-blocked task and make it ready. Does not wait for another message. Negative results indicate an invalid target or a task not waiting for a reply.
AwaitEvent(event): Block for a hardware event. Browser devices provide CLOCK_TICK, CONSOLE_READ_READY, and CONSOLE_WRITE_READY. Notifier tasks normally own these waits.
MyTime(): Return accumulated execution time for the caller in microseconds.
TotalTime(): Return elapsed kernel time in microseconds. This and MyTime wrap after about 71 minutes.
Quit(): Enter the platform shutdown/reboot path; does not return. The browser virt target halts. Use the page’s Reboot button to start a fresh machine.

RETURN VALUES

Create returns a task ID. Identity, priority, and count calls return the requested integer. Receive returns the number of message bytes copied; Send returns the number of reply bytes copied. MyTime and TotalTime return unsigned 32-bit microsecond counts.

Yield has no return value. Exit and Quit do not return. AwaitEvent returns event-specific data. Do not interpret the successful Reply result as a byte count; the reply length is returned to the blocked sender.

ERRORS

Errors are negative return values; this API does not use errno.

Create: −1: priority outside 0–49.
−2: no task descriptor available.
Send: −1: unknown or dead target.
−2: caller attempted to send to itself.
Reply: −1: unknown target.
−2: dead target, caller itself, or target not waiting for a reply.

NOTES

Messages and replies are copied as bytes and truncated to the receiver’s buffer size. Lengths are byte counts; strings are not automatically terminated. Check return lengths before interpreting a response.

The browser target supplies the generic timer and PL011 console events. Clock ticks represent 10 ms of guest time. Emulated timings are not Raspberry Pi benchmarks.