Enum xous::syscall::SysCall

pub enum SysCall {
    MapMemory(Option<MemoryAddress>, Option<MemoryAddress>, MemorySize, MemoryFlags),
    UnmapMemory(MemoryRange),
    SetMemRegion(PID, MemoryType, MemoryAddress, usize),
    IncreaseHeap(usize, MemoryFlags),
    DecreaseHeap(usize),
    UpdateMemoryFlags(MemoryRange, MemoryFlags, Option<PID>),
    Yield,
    WaitEvent,
    ReceiveMessage(SID),
    TryReceiveMessage(SID),
    ReturnToParent(PID, CpuID),
    ClaimInterrupt(usize, MemoryAddress, Option<MemoryAddress>),
    FreeInterrupt(usize),
    SwitchTo(PID, usize),
    ReadyThreads(PID),
    CreateServerWithAddress(SID),
    Connect(SID),
    TryConnect(SID),
    SendMessage(CID, Message),
    TrySendMessage(CID, Message),
    ReturnMemory(MessageSender, MemoryRange, Option<MemorySize>, Option<MemorySize>),
    ReturnScalar1(MessageSender, usize),
    ReturnScalar2(MessageSender, usize, usize),
    CreateThread(ThreadInit),
    CreateProcess(ProcessInit),
    TerminateProcess(u32),
    Shutdown,
    CreateServer,
    CreateServerId,
    ConnectForProcess(PID, SID),
    GetThreadId,
    GetProcessId,
    DestroyServer(SID),
    Disconnect(CID),
    JoinThread(TID),
    SetExceptionHandler(usize, usize),
    AdjustProcessLimit(usize, usize, usize),
    ReturnScalar5(MessageSender, usize, usize, usize, usize, usize),
    ReplyAndReceiveNext(MessageSender, usize, usize, usize, usize, usize, usize),
    Invalid(usize, usize, usize, usize, usize, usize, usize),
}

Variants

MapMemory(Option<MemoryAddress>, Option<MemoryAddress>, MemorySize, MemoryFlags)

Allocates pages of memory, equal to a total of size bytes. A physical address may be specified, which can be used to allocate regions such as memory-mapped I/O.

If a virtual address is specified, then the returned pages are located at that address. Otherwise, they are located at the Default offset.

Returns

• MemoryRange: A memory range containing zeroed bytes.

Errors

• BadAlignment: Either the physical or virtual addresses aren’t page-aligned, or the size isn’t a multiple of the page width.
• OutOfMemory: A contiguous chunk of memory couldn’t be found, or the system’s memory size has been exceeded.

UnmapMemory(MemoryRange)

Release the memory back to the operating system.

Errors

• BadAlignment: The memory range was not page-aligned
• BadAddress: A page in the range was not mapped

SetMemRegion(PID, MemoryType, MemoryAddress, usize)

Sets the offset and size of a given memory region. This call may only be made by processes that have not yet started, or processes that have a PPID of 1. Care must be taken to ensure this region doesn’t run into other regions. Additionally, the base address must avoid the kernel regions.

Errors

• BadAlignment: Either the physical or virtual addresses aren’t page-aligned, or the size isn’t a multiple of the page width.
• BadAddress: The address conflicts with the kernel

IncreaseHeap(usize, MemoryFlags)

Add the given number of bytes to the heap. The number of bytes must be divisible by the page size. The newly-allocated pages will have the specified flags. To get the current heap base, call this with a size of 0, which will return a MemoryRange containing the heap base and the size.

Returns

• *MemoryRange( mut usize, / The newly-allocated offset / usize, / The amount of data added / )

Errors

• BadAlignment: Either the physical or virtual addresses aren’t page-aligned, or the size isn’t a multiple of the page width.
• OutOfMemory: A contiguous chunk of memory couldn’t be found, or the system’s memory size has been exceeded.

DecreaseHeap(usize)

Remove the given number of bytes from the heap.

Returns

• **MemoryRange(mut usize / The base of the heap /, usize / the new size of the heap */)

Errors

• BadAlignment: Either the physical or virtual addresses aren’t page-aligned, or the size isn’t a multiple of the page width.
• OutOfMemory: A contiguous chunk of memory couldn’t be found, or the system’s memory size has been exceeded.

UpdateMemoryFlags(MemoryRange, MemoryFlags, Option<PID>)

Set the specified flags on the virtual address range. This can be used to REMOVE flags on a memory region, for example to mark it as no-execute after writing program data.

If PID is None, then modifies this process. Note that it is not legal to modify the memory range of another process that has been started already.

Returns

• Ok: The call completed successfully

Errors

• ProcessNotChild: The given PID is not a child of the current process.
• MemoryInUse: The given PID has already been started, and it is not legal to modify memory flags anymore.

Yield

Pauses execution of the current thread and returns execution to the parent process. This may return at any time in the future, including immediately.

Returns

• Ok: The call completed successfully

Errors

This syscall will never return an error.

WaitEvent

This process will now wait for an event such as an IRQ or Message.

Returns

• Ok: The call completed successfully

Errors

This syscall will never error.

ReceiveMessage(SID)

This thread will now wait for a message with the given server ID. You can set up a pool by having multiple threads call ReceiveMessage with the same SID.

Returns

• MessageEnvelope: A valid message from the queue

Errors

• ServerNotFound: The given SID is not active or has terminated
• ProcessNotFound: The parent process terminated when we were getting ready to block. This is an internal error.
• BlockedProcess: When running in Hosted mode, this indicates that this thread is blocking.

TryReceiveMessage(SID)

If a message is available for the specified server, return that message and resume execution. If no message is available, return Result::None immediately without blocking.

Returns

• Message: A valid message from the queue
• None: Indicates that no message was in the queue

Errors

• ServerNotFound: The given SID is not active or has terminated
• ProcessNotFound: The parent process terminated when we were getting ready to block. This is an internal error.

ReturnToParent(PID, CpuID)

Stop running the given process and return control to the parent. This will force a Yield on the process currently running on the target CPU. This can be run during an Interrupt context.

Errors

• ProcessNotChild: The given PID is not a child of the current process

ClaimInterrupt(usize, MemoryAddress, Option<MemoryAddress>)

Claims an interrupt and unmasks it immediately. The provided function will be called from within an interrupt context, but using the ordinary privilege level of the process.

Returns

• Ok: The interrupt has been mapped to this process

Errors

• InterruptNotFound: The specified interrupt isn’t valid on this system
• InterruptInUse: The specified interrupt has already been claimed

FreeInterrupt(usize)

Returns the interrupt back to the operating system and masks it again. This function is implicitly called when a process exits.

Errors

• InterruptNotFound: The specified interrupt doesn’t exist, or isn’t assigned to this process.

SwitchTo(PID, usize)

Resumes a process using the given context. A parent could use this function to implement multi-threading inside a child process, or to create a task switcher.

To resume a process exactly where it left off, set context_id to 0. This would be done in a very simple system that has no threads.

If no more contexts are available when one is required, then the child automatically relinquishes its quantum.

Returns

When this function returns, it provides a list of the processes and contexts that are ready to be run. Three can fit as return values.

Examples

If a process called yield(), or if its quantum expired normally, then a single pair is returned: (pid, context).

If the child process called client_send() and ended up blocking due to the server not being ready, then this would return no pairs. This thread or process should not be scheduled to run.

If the child called client_send() and the server was ready, then the server process would be run immediately. If the child process’ quantum expired while the server was running, then this function would return a single pair containing the PID of the server, and the context number.

If the child called client_send() and the server was ready, then the server process would be run immediately. If the server then finishes, execution flow is returned to the child process. If the quantum then expires, this would return two pairs: the server’s PID and its context when it called client_reply(), and the child’s PID with its current context.

If the server in turn called another server, and both servers ended up returning to the child before the quantum expired, then there would be three pairs returned.

Errors

• ProcessNotFound: The requested process does not exist
• ProcessNotChild: The given process was not a child process, and therefore couldn’t be resumed.
• ProcessTerminated: The process has crashed.

ReadyThreads(PID)

Get a list of contexts that can be run in the given PID.

Errors

• UnhandledSyscall: This syscall is currently unimplemented.

CreateServerWithAddress(SID)

Create a new Server with a specified address

This will return a 128-bit Server ID that can be used to send messages to this server, as well as a connection ID. This connection ID will be unique per process, while the server ID is available globally.

Returns

• NewServerID(sid, cid): The specified SID, along with the connection ID for this process to talk to the server.

Errors

• OutOfMemory: The server table was full and a new server couldn’t be created.
• ServerExists: The server hash is already in use.

Connect(SID)

Connect to a server. This turns a 128-bit Server ID into a 32-bit Connection ID. Blocks until the server is available.

Returns

• ConnectionID(cid): The new connection ID for communicating with the server.

Errors

None

TryConnect(SID)

Try to connect to a server. This turns a 128-bit Server ID into a 32-bit Connection ID.

Returns

• ConnectionID(cid): The new connection ID for communicating with the server.

Errors

• ServerNotFound: The server could not be found.

SendMessage(CID, Message)

Send a message to a server (blocking until it’s ready)

Returns

• Ok: The Scalar / Send message was successfully sent
• Scalar1: The Server returned a Scalar1 value
• Scalar2: The Server returned a Scalar2 value
• Scalar5: The Server returned a Scalar5 value
• BlockedProcess: In Hosted mode, the target process is now blocked
• Message: For Scalar messages, this includes the args as returned by the server. For MemoryMessages, this will include the Opcode, Offset, and Valid fields.

Errors

• ServerNotFound: The server could not be found.
• ProcessNotFound: Internal error – the parent process couldn’t be found when blocking

TrySendMessage(CID, Message)

Try to send a message to a server

Returns

• Ok: The Scalar / Send message was successfully sent, or the Borrow has finished
• Scalar1: The Server returned a Scalar1 value
• Scalar2: The Server returned a Scalar2 value
• Scalar5: The Server returned a Scalar5 value
• BlockedProcess: In Hosted mode, the target process is now blocked

Errors

• ServerNotFound: The server could not be found.
• ServerQueueFull: The server’s mailbox is full
• ProcessNotFound: Internal error – the parent process couldn’t be found when blocking

ReturnMemory(MessageSender, MemoryRange, Option<MemorySize>, Option<MemorySize>)

Return a Borrowed memory region to the sender

ReturnScalar1(MessageSender, usize)

Return a scalar to the sender

ReturnScalar2(MessageSender, usize, usize)

Return two scalars to the sender

CreateThread(ThreadInit)

Spawn a new thread

CreateProcess(ProcessInit)

Create a new process, setting the current process as the parent ID. Starts the process immediately and returns a ProcessStartup value.

TerminateProcess(u32)

Terminate the current process, closing all server connections.

Shutdown

Shut down the entire system

CreateServer

Create a new Server

This will return a 128-bit Server ID that can be used to send messages to this server. The returned Server ID is random.

Returns

The SID, along with a Connection ID that can be used to immediately communicate with this process.

Errors

• OutOfMemory: The server table was full and a new server couldn’t be created.

CreateServerId

Returns a 128-bit server ID, but does not create the server itself. basically an API to access the TRNG inside the kernel.

ConnectForProcess(PID, SID)

Establish a connection in the given process to the given server. This call can be used by a nameserver to make server connections without disclosing SIDs.

GetThreadId

Get the current Thread ID

GetProcessId

Get the current Process ID

DestroyServer(SID)

Destroys the given Server ID. All clients that are waiting will be woken up and will receive a ServerNotFound response.

Disconnect(CID)

Disconnects from a Server. This invalidates the CID, which may be reused in a future reconnection.

JoinThread(TID)

Waits for a thread to finish, and returns the return value of that thread.

SetExceptionHandler(usize, usize)

A function to call when there is an exception such as a memory fault or illegal instruction.

AdjustProcessLimit(usize, usize, usize)

Adjust one of the limits within this process. Note that you must pass the current limit value in order to set the new limit. The current limit value is always returned, so this function may need to be called twice – once in order to get the current limit, and again to set the new limit.

Arguments

• Index: The item to adjust. Currently the following limits are supported: 1: Maximum heap size 2: Current heap size
• Current Limit: Pass the current limit value here. The current limit must match in order for the new limit to take effect. This is used to avoid a race condition if two threads try to set the same limit.
• Proposed Limit: The new value that you would like to use.

Returns

Returns a Scalar2 containing (Index, Limit).

Errors

• InvalidLimit: The specified index was not valid

ReturnScalar5(MessageSender, usize, usize, usize, usize, usize)

Return five scalars to the sender

ReplyAndReceiveNext(MessageSender, usize, usize, usize, usize, usize, usize)

Return a message with the given Message ID and the provided parameters, and listen for another message on the server ID that sent this message. This call is meant to be used in the main loop of a server in order to reduce latency when that server is called frequently.

This call works on both MemoryMessages and BlockingScalars, and does not distinguish between the two from the API.

Arguments

• MessageSender: This is the sender from the message envelope. It is a unique ID that identifies this message, as well as the server it came from.

The remaining arguments depend on whether the message was a BlockingScalar message or a MemoryMessage. Note that this function should NOT be called on non-blocking messages such as Send or Scalar.

Returns

• Message: A valid message from the queue

Errors

• ServerNotFound: The given SID is not active or has terminated
• ProcessNotFound: The parent process terminated when we were getting ready to block. This is an internal error.
• BlockedProcess: When running in Hosted mode, this indicates that this thread is blocking.

Invalid(usize, usize, usize, usize, usize, usize, usize)

This syscall does not exist. It captures all possible arguments so detailed analysis can be performed.

Implementations

impl SysCall

pub fn as_args(&self) -> [usize; 8]

Convert the SysCall into an array of eight usize elements, suitable for passing to the kernel.

pub fn from_args( a0: usize, a1: usize, a2: usize, a3: usize, a4: usize, a5: usize, a6: usize, a7: usize ) -> Result<Self, Error>

pub fn has_memory(&self) -> bool

Returns true if the associated syscall is a message that has memory attached to it

pub fn is_move(&self) -> bool

Returns true if the associated syscall is a message that is a Move

pub fn is_borrow(&self) -> bool

Returns true if the associated syscall is a message that is a Borrow

pub fn is_mutableborrow(&self) -> bool

Returns true if the associated syscall is a message that is a MutableBorrow

pub fn is_return_memory(&self) -> bool

Returns true if the associated syscall is returning memory

pub fn memory(&self) -> Option<MemoryRange>

If the syscall has memory attached to it, return the memory

pub unsafe fn replace_memory(&mut self, new: MemoryRange)

If the syscall has memory attached to it, replace the memory.

Safety

This function is only safe to call to fixup the pointer, particularly when running in hosted mode. It should not be used for any other purpose.

pub fn can_call_from_interrupt(&self) -> bool

Returns true if the given syscall may be called from an IRQ context

Trait Implementations

impl Debug for SysCall

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for SysCall

fn eq(&self, other: &SysCall) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for SysCall