Threos documentation System call index
Index of constants

Threos System Calls

TimerObject

SignalMessage

Exception

Objects

Events

MsgPort

Virtual

Store

Memory

Semaphore

Other

Iteration

ISR

Tasking


CreateGroup

Handle CreateGroup(uintptr_t session, uintptr_t type);

Description

Create a new task group.

Return value

Arguments


CreateTask

Handle CreateTask(Handle group, uintptr_t priority, uintptr_t type);

Description

Create a new task.

Return value

Arguments


CreateThread

Handle CreateThread(Handle task, PFN_THREADENTRY start, void* data, uintptr_t type, void* sp);

Description

Create a new thread in a task.

Return value

Arguments


CreateISR

Handle CreateISR(Handle task, uintptr_t irq_num, PFN_ISR pfn, void* data, uintptr_t type, void* sp);

Description

Create a new Interrupt Service Routine in a task.
Note that, an ISR function must return using the RetISR system call.

Return value

Arguments


RetISR

Result RetISR(uintptr_t retval);

Description

Return from an Interrupt Service Routine.
The code must return from an ISR using this system call, otherwise, it causes an undefined behaviour, and the task will possibly crash.
Important! Call to this system call shall be from ISR code only.

Return value

Arguments


CreateHandle

Handle CreateHandle(Handle task, Handle handle, uintptr_t perm);

Description

Create a new handle for a specific task. Permissions can be revoked from the new handle compared to the original one.

Return value

Arguments


CheckPermissions

Result CheckPermissions(Handle obj, uintptr_t perm, uintptr_t* got);

Description

Check which permissions the specified object has, using a permission mask.

Return value

Arguments


DeleteObject

Result DeleteObject(Handle obj, uintptr_t param);

Description

Delete a kernel object or a handle.

Return value

Arguments


GetObjectInfo

Result GetObjectInfo(Handle obj, uintptr_t tag, uintptr_t* val);

Description

Get information about a kernel object.

Return value

Arguments


ControlObject

Result ControlObject(Handle obj, uintptr_t cmd, uintptr_t param1, uintptr_t param2, uintptr_t param3, uintptr_t param4);

Description

Perform a change on a kernel object or on the kernel itself.

Return value

Arguments


CreateWatchObject

Handle CreateWatchObject(Handle task, Handle msgport, Handle obj, uintptr_t type);

Description

Create a watch object that will wait for the specified event, and send a message when the event occurs.
This call makes it possible to wait for events in the kernel. Once installed, the watch object persist until it is removed by a call to DeleteObject, by the parent task exiting or by the deletion of the object being watched.
An object can have a limited number of watch objects per slot. The limit is defined by WATCHSLOT_CAPACITY macro. A watch slot may share events. The slots are:
  1. object generic: KWATCH_OBJ_DELETED, KWATCH_OBJ_ERROR
  2. kernel only: KWATCH_KERNEL_NEWTASK
  3. memory object specific: KWATCH_MEMO_NEWVIEW, KWATCH_MEMO_DELVIEW KWATCH_MEMO_NEWCOPY, KWATCH_MEMO_DELCOPY
  4. task specific: KWATCH_TASK_NEWTHREAD, KWATCH_TASK_DELTHREAD
  5. event specific: KWATCH_EVENT_SET
As can be seen above, the watch ID indicates which slot will be used. This holds for further watch IDs are not introduced yet, unless otherwise documented.
Example: A MsgPort object has only one watch slot, the object generic, but an Event object has two watch slots: the object generic and the event specific.

Return value

Arguments


CreateMemo

Handle CreateMemo(Handle task, void* location, uintptr_t size, uintptr_t type);

Description

Create a new memory object.
Direct access to a memory object is rarely possible. To get access to it use the AllocView system call.

Return value

Arguments


CreateMemoCopy

Handle CreateMemoCopy(Handle task, Handle memo, void* location, uintptr_t type);

Description

Create a copy-on-write copy of a memory object. The parent memory object must not have any views.

Return value

Arguments


AllocView

void* AllocView(Handle task, Handle memo, const void* location, uintptr_t offset, uintptr_t size, uintptr_t type);

Description

Allocate a view for the given memory object.

Return value

Arguments


FreeView

Result FreeView(Handle task, const void* location, uintptr_t param);

Description

Free a previously allocated view created by AllocView.
Note: the preallocated virtual spaces will not be freed as expected (see VirtualFree).

Return value

Arguments


GetAddressMemo

Handle GetAddressMemo(Handle task, const void* loc, uintptr_t addrtype);

Description

Find a memory object by address.

Return value

Arguments


GetAddressView

Handle GetAddressView(Handle task, const void* loc);

Description

Find a memory view by address.

Return value

Arguments


VirtualAlloc

void* VirtualAlloc(Handle task, void* location, uintptr_t size, uintptr_t type);

Description

Allocate virtual memory space to a task.

Return value

Arguments


VirtualFree

Result VirtualFree(Handle task, void* location, uintptr_t type);

Description

Free a previously allocated virtual space by VirtualAlloc.

Return value

Arguments


CreateMsgPort

Handle CreateMsgPort(Handle task, uintptr_t param);

Description

Create a new Message Port. This is a synchronization object, and threads can wait on it.

Return value

Arguments


SendMsg

Result SendMsg(Hande mport, Handle sender, uintptr_t msg1, uintptr_t msg2, intptr_t timeout);

Description

Send a message to a Message Port.

Return value

Arguments


RecvMsg

Result RecvMsg(Hande mport, Handle* sender, uintptr_t* msg1, uintptr_t* msg2, intptr_t timeout);

Description

Receive a message from the Message Port.

Return value

Arguments


PeekMsg

Result PeekMsg(Hande mport, Handle* sender, uintptr_t* msg1, uintptr_t* msg2, intptr_t timeout);

Description

Receive a message from the Message Port without removing it from the Message Port.

Return value

Arguments


CreateMsgPipe

Handle CreateMsgPipe(Handle task, Handle to, Handle from, uintptr_t param);

Description

Create a Message Pipe that connects two Message Ports. This kernel object will automatically redirect messages from a Message Port to another.
Message Pipe chains cannot be longer than 2 message port: only one Message Pipe per continuous chain. A Message Port may have multiple Message Pipes. Source and destination Message Port cannot be the same.

Return value

Arguments


CreateSignalMsg

Handle CreateSignalMsg(Handle task, Hande msgport, Handle sender, uintptr_t msg1, uintptr_t msg2, uintptr_t type);

Description

Create a new Signal Message. This Message can be sent anytime (at most restricted by SIGMSG_CR_WAITFORRESET, but not the Message Port), and the kernel will record each SendSignalMsg call. Therefore, the right amount of messages will be delivered.
In Interrupt Service Routines this can be an important object.

Return value

Arguments


SendSignalMsg

Result SendSignalMsg(Hande sigmsg);

Description

Send the Signal Message. The operation can fail only when the target Message Port is deleted, or the Signal Message is deleted. Also, it may fail if the Signal Message must be reset (SIGMSG_CR_WAITFORRESET in CreateSignalMsg).

Return value

Arguments


ResetSignalMsg

Result ResetSignalMsg(Hande sigmsg, uintptr_t param);

Description

Reset the Signal Message.

Return value

Arguments


CreateSemaphore

Handle CreateSemaphore(Handle task, uintptr_t value, uintptr_t maxvalue, uintptr_t type);

Description

Create a new semaphore. This is a synchronization object, and threads can wait on it.

Return value

Arguments


WaitSemaphore

Result WaitSemaphore(Handle sema, uintptr_t value, intptr_t timeout);

Description

Wait for a semaphore. The call will be successful when the semaphore counter has the specified amount. Then the amount will be taken from the semaphore. It is the callers responsibility to give the correct amount back to the semaphore using the SignalSemaphore system call.

Return value

Arguments


SignalSemaphore

Result SignalSemaphore(Handle sema, uintptr_t value);

Description

Signal a semaphore (give some amount back to the semaphore). This call may wake another thread up.

Return value

Arguments


CreateEvent

Handle CreateEvent(Handle htask, uintptr_t type);

Description

Create a new event. This is a synchronization object, and threads can wait on it.

Return value

Arguments


WaitForEvent

Result WaitForEvent(Handle hev, Handle* sender, uintptr_t* msg1, uintptr_t* msg2, intptr_t timeout);

Description

Wait until the set flag of the event is set. Retrieve the message parameters as well.

Return value

Arguments


SetEvent

Result SetEvent(Handle hev, uintptr_t msg1, uintptr_t msg2, uintptr_t type);

Description

Set the set flag of the event. Also, modify the message values.

Return value

Arguments


ResetEvent

Result ResetEvent(Handle hev, uintptr_t type);

Description

Clear the set flag in the event.

Return value

Arguments


CreateTimerObj

Handle CreateTimerObj(Handle task, Hande msgport, uintptr_t msg1, uintptr_t msg2, uintptr_t timeout, uintptr_t param);

Description

Create a new Timer Object.

Return value

Arguments


RewindTimerObj

Result RewindTimerObj(Handle to, uintptr_t timeout);

Description

Rewind (or reconfigure) a Timer Object.

Return value

Arguments


StopTimerObj

Result StopTimerObj(Handle to);

Description

Stop a running Timer Object.

Return value

Arguments


SetExceptionHandler

Result SetExceptionHandler(Handle obj, uintptr_t type, PFN_EXC func, void* data);

Description

Set the exception handler of a task or a memory object.
Every task has two exception handlers: one for the system exceptions and one for the user exceptions.
Memory objects can have an exception handler to handle the page fault exceptions. The arguments are a bit different than the exception handlers for tasks. The arguments meant to be:
  1. void* userdata: user data as expected
  2. uintptr_t exid: this argument holds the handle of the memory object
  3. uintptr_t param: the offset in octets of the page that caused the fault
Note that, an exception handler must return with the RetException system call.

Return value

Arguments


RaiseException

Result RaiseException(Handle task, Handle thread, uintptr_t exid, uintptr_t param, uintptr_t type);

Description

Raise a user exception to the specified task (and thread, see below).

Return value

Arguments


RetException

Result RetException(uintptr_t result, void* pc);

Description

Return from an exception handler.
The code must return from an exception handler with this system call. Otherwise, it causes an undefined behaviour, and the task will possibly crash.
Important! Call to this system call shall be from exception handlers only.

Return value

Arguments


AllocStoreId

uintptr_t AllocStoreId();

Description

Allocate a new Store ID. There are a few preallocated Store IDs, such as STOREID_RES1. The last preallocated Store ID is available under STOREID_MAX.

Return value

Arguments


CreateStore

Result CreateStore(Handle obj, uintptr_t id, uintptr_t val, uintptr_t type);

Description

Create a new store in the specified kernel object.
Currently, only tasks can have stores.

Return value

Arguments


SetStore

Result SetStore(Handle obj, uintptr_t id, uintptr_t val);

Description

Set the value of the store in a kernel object.

Return value

Arguments


GetStore

Result GetStore(Handle obj, uintptr_t id, uintptr_t* val);

Description

Set the value of the store in a kernel object.

Return value

Arguments


RemoveStore

Result RemoveStore(Handle obj, uintptr_t id);

Description

Remove a store from a kernel object.

Return value

Arguments


CreateIterator

Handle CreateIterator(Handle task, uintptr_t type);

Description

Create a new iterator object. This object can be used for multiple iteration, by calling the BeginIterator multiple times (this system call will start a new iteration regardless of the current state of the iterator).
Quick guide how to use iterator objects:
  1. create iterator with CreateIterator
  2. begin a new iteration with BeginIterator
  3. if StepIterator returns E_ITERATION_HAS_ENDED, the iteration has ended, go to 6 (optionally go to 2)
  4. use GetIteratorInfo to acquire information about the current element
  5. goto 3
  6. delete the iterator with DeleteObject

Return value

Arguments


BeginIterator

Result BeginIterator(Handle iter, Handle obj, uintptr_t type);

Description

Begin a new iteration. This system call will drop the current state of the iterator, and reinitializes it.
After a successful call (E_OK was returned) the iterator does not hold any data. Use the StepIterator system call to access to the first and the subsequent elements.

Return value

Arguments


StepIterator

Result StepIterator(Handle iter);

Description

Step the iterator get acquire the first or the next element, depending on the iterator state. After a successful BeginIterator the first element (if any), after StepIterator the next element will be acquired.

Return value

Arguments


GetIteratorInfo

Result GetIteratorInfo(Handle iter, uintptr_t tag, uintptr_t* val);

Description

Get information about the acquired element by the StepIterator system call. This system call is similar to GetObjectInfo, except the required permissions, and the first argument is the iterator (that in turn will reference an object).

Return value

Arguments


GetLastError

Result GetLastError();

Description

Get the last error code of the current context (of the current thread).
The error codes are stored per context per thread basis, so the execution will not loose its error code during handling an exception.

Return value

Arguments


GetState

uintptr_t GetState(uintptr_t ks);

Description

Get kernel state, such as the current task, current thread, or the available memory.

Return value

Arguments


SetState

Result SetState(uintptr_t ks, uintptr_t s);

Description

Set kernel state.
Some states are read-only (RdOnly in the comment below), one-time writable (Once in the comment), architecture dependent (Arch in the command), or build dependent (Build in the command).
Note: KST_DEBUGCONSOLE seems to be writable, but actually no change will be made in the kernel. Only the debug console will be opened. Still, KST_DEBUGCONSOLE is build dependent.

Return value

Arguments


GetSystemData

Result GetSystemData(uintptr_t data_tag, uintptr_t index, uintptr_t* value);

Description

Read an uintptr_t-sized slot from a special kernel data table.
These tables can store trace data or any architecture dependent data.

Return value

Arguments


Delay

Result Delay(uintptr_t duration);

Description

Suspend the execution of the current task for the specified duration.
If the duration is zero, the thread is yield, and the next thread will be scheduled (if the current task has other threads on that priority; otherwise the current thread will be rescheduled).
The actual delay will be duration+1, because the scheduler can resume the thread in tick interrupts. Therefore, the expected error will be half of one tick (millisecond).

Return value

Arguments


LibBase

void* LibBase();

Description

This system call is reserved for future use.

Return value

Arguments


Index of constants


System call index

Author: Aron Barath, 2017