Skip to content

API_v1.1

Jump to bottom
Henrik Karlsson edited this page Oct 23, 2024 · 1 revision

Registers

Each process in S3K has access to the standard RISC-V general-purpose registers, and a few S3K specific registers. The general-purpose registers are as described in RISC-V and are fully controlled by the user process.

The S3K specific registers, are virtual registers that reside inside the kernel. They are used to control how the process behaves and for servicing exceptions.

  • Trap program-counter (S3K_REG_TPC): Pointer to process's trap handling routing.
  • Trap stack pointer (S3K_REG_TSP): Stack pointer for trap handling.
  • Exception program-counter (S3K_REG_EPC): Program counter at time of exception
  • Exception stack pointer (S3K_REG_ESP): Stack pointer at time of exception.
  • Exception cause (S3K_REG_ECAUSE): Cause of exception. See RISC-V's mcause register.
  • Exception value (S3K_REG_EVAL): Auxiliary information for exception handling. See RISC-V's mtval register.
  • Servicing time (S3K_REG_SERVTIME): Minimum execution time to donate when receiving a yielding IPC.

Capabilities

TODO: Enumerate available capabilities and describe their fields.

Memory Protection

Inter-process Communication

TODO: Explain in detail how IPC is inteded to be used

Process Monitoring

System Calls

s3k_get_pid

Get the process ID of the caller.

int s3k_get_pid(void);

Return: the process ID of the caller.

s3k_get_time

Get the current real-time.

uint64_t s3k_get_time(void);

Return: the current real-time.

s3k_get_timeout

Get the timeout of the current minor frame.

uint64_t s3k_get_timeout(void);

Return: the timeout of the current minor frame.

s3k_reg_read

Get the value of a register or 0 if reg is invalid.

uint64_t s3k_reg_read(uint64_t reg);

Parameters:

  • reg - index of register.

Return: the value of register with reg. If reg is invalid, returns 0.

s3k_reg_write

Set the value of a register. No effect if reg is invalid.

void s3k_reg_write(uint64_t reg, uint64_t val);

Parameters:

  • reg - ID of register.
  • val - value to write to the register.

Note: Writing to standard RISC-V registers may have unintended consequences.

s3k_sync

void s3k_sync(void);

s3k_sync_mem

Synchronize the process's memory permissions with the underlying capabilities.

void s3k_sync_mem(void);

General Capabilities

s3k_cap_read

Read the data of the i'th capability.

error_t s3k_cap_read(uint64_t i, cap_t *cap);

Parameters:

  • i - index of capability.
  • cap - buffer for data.

Returns:

  • S3K_SUCCESS - if data was read.
  • S3K_ERR_INVARG - if i is invalid.

s3k_cap_move

Move the i'th capability to the j'th slot.

error_t s3k_cap_move(uint64_t i, uint64_t j);

Parameters:

  • i - source index of capability to move.
  • j - destination index of capability to move.

Returns:

  • S3K_SUCCESS - if capability was moved.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i or j is invalid.
  • S3K_ERR_INVCAP - if the i'th slot was empty.
  • S3K_ERR_EXISTS - if the j'th slot was not empty

s3k_cap_delete

Delete the i'th capability.

error_t s3k_cap_delete(uint64_t i);

Parameters:

  • i - index of capability to delete.

Returns:

  • S3K_SUCCESS - if capability was deleted.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i is invalid.
  • S3K_ERR_INVCAP - if the i'th slot was empty.

s3k_cap_revoke

Recursively deletes the children of the i'th capability, then restore the i'th capability to its original state.

error_t s3k_cap_revoke(uint64_t i);

Parameters:

  • i - index of capability to revoke with.

Returns:

  • S3K_SUCCESS - if capabilities were revoked and restored.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i is invalid.
  • S3K_ERR_INVCAP - if the i'th slot was empty.

s3k_cap_derive

Create a new capability at the j'th slot using the i'th capability. If successful, the i'th capability is updated to reflect that resources were reallocated (only slice capabilities).

error_t s3k_cap_derive(uint64_t i, uint64_t j, cap_t cap);

Parameters:

  • i - index of capability to derive from.
  • j - destination of the new capability.
  • cap - description of capability to create

Returns:

  • S3K_SUCCESS - if the new capability wass successfully created.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i or j is invalid.
  • S3K_ERR_EXISTS - if the j'th slot was occupied.
  • S3K_ERR_INVCAP - if i'th capability can not be used to derive cap

Note: If preempted, the syscall may be partially; that is, only some child capabilities have been revoked.

s3k_pmp_load

Use the i'th capability to set the j'th PMP slot.

The i'th capability is valid if it is a PMP capability not in use.

error_t s3k_pmp_load(uint64_t i, uint64_t j)

Parameters:

  • i - source index of PMP capability to load
  • j - index of PMP slot

Returns:

  • S3K_SUCCESS - if PMP capability was loaded.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i of j is invalid.
  • S3K_ERR_INVCAP - if i'th capability is invalid.
  • S3K_ERR_EXISTS - if the j'th PMP slot was occupied.

s3k_pmp_unload

Unload the i'th capability.

The i'th capability is valid if it is a PMP capability in use.

error_t s3k_pmp_unload(uint64_t i)

Parameters:

  • i - source index of PMP capability to load
  • j - index of PMP slot

Returns:

  • S3K_SUCCESS - if PMP capability was unloaded.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i is invalid.
  • S3K_ERR_INVCAP - if i'th capability is invalid.

s3k_monitor_suspend

Use the i'th capability to suspend the process pid.

The i'th capability is valid if it is a monitor capability such that pid is in the free segment.

error_t s3k_monitor_suspend(uint64_t i, uint64_t pid)

Parameters:

  • i - index of monitor capability
  • pid - PID of the process to suspend

Returns:

  • S3K_SUCCESS - if process was resumed.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i or pid is invalid.
  • S3K_ERR_INVCAP - if i'th capability is invalid.

s3k_monitor_resume

Use the i'th capability to resume the process pid.

The i'th capability is valid if it is a monitor capability such that pid is in the free segment.

error_t s3k_monitor_resume(uint64_t i, uint64_t pid)

Parameters:

  • i - index of monitor capability
  • pid - PID of the process to resume

Returns:

  • S3K_SUCCESS - if capability was deleted.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i or pid is invalid.
  • S3K_ERR_INVCAP - if i'th capability is invalid.

s3k_monitor_reg_read

error_t s3k_monitor_reg_read(uint64_t i, uint64_t pid, uint64_t reg, uint64_t *val)

Use the i'th capability to read from register of process pid.

The i'th capability is valid if it is a monitor capability such that pid is in the free segment.

Parameters:

  • i - index of monitor capability
  • pid - PID of the process to resume
  • reg - index of register
  • val - buffer to read register value into, 0 if reg is invalid

Returns:

  • S3K_SUCCESS - if capability was deleted.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i or pid is invalid.
  • S3K_ERR_INVCAP - if i'th capability is invalid.

s3k_monitor_reg_write

error_t s3k_monitor_reg_write(uint64_t i, uint64_t pid, uint64_t reg, uint64_t val)

Use the i'th capability to write to register of process pid. Has no effect if reg is invalid.

The i'th capability is valid if it is a monitor capability such that pid is in the free segment.

Parameters:

  • i - index of monitor capability
  • pid - PID of the process to resume
  • reg - index of register
  • val - value to write

Returns:

  • S3K_SUCCESS - if capability was deleted.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i or pid is invalid.
  • S3K_ERR_INVCAP - if i'th capability is invalid.

s3k_monitor_pmp_load

error_t s3k_monitor_pmp_load(uint64_t i, uint64_t pid, uint64_t j, uint64_t k);

Parameters:

  • i - index of monitor capability
  • pid - PID of the process to resume
  • j - index of pmp capability
  • k - pmp slot

Returns:

  • S3K_SUCCESS - if PMP capability was loaded.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i, j or k is invalid.
  • S3K_ERR_EXISTS - if the k'th PMP slot of process pid was occupied.
  • S3K_ERR_INVCAP - if i'th or j'th capability is invalid.

s3k_monitor_pmp_unload

error_t s3k_monitor_pmp_unload();

Parameters:

  • i - index of monitor capability
  • pid - PID of the process to resume
  • j - index of pmp capability

Returns:

  • S3K_SUCCESS - if PMP capability was loaded.
  • S3K_PREEMPTED - if system call was aborted due to timer preemption.
  • S3K_ERR_INVARG - if i or j is invalid.
  • S3K_ERR_INVCAP - if i'th or j'th capability is invalid.

s3k_monitor_cap_move

error_t s3k_monitor_cap_move();

Socket Capabilities

s3k_sock_send

error_t s3k_sock_send(uint64_t sock_idx, uint64_t cap_idx, uint64_t data[4], bool send_cap);

Parameters:

  • sock_idx - index of socket capability
  • cap_idx - index of capability slot used for sending capabilities
  • data - data to send
  • send_cap - whether to send a capability or not

s3k_sock_recv

error_t s3k_sock_recv(uint64_t sock_idx, uint64_t cap_idx, uint64_t data[4]);

Parameters:

  • sock_idx - index of socket capability
  • cap_idx - index of capability slot used for sending capabilities
  • data - data to send
  • send_cap - whether to send a capability or not

s3k_sock_sendrecv

error_t s3k_sock_sendrecv(uint64_t sock_idx, uint64_t cap_idx, uint64_t data[4], uint64_t send_cap, uint64_t service_time);

Parameters:

  • sock_idx - index of socket capability
  • cap_idx - index of capability slot used for sending/receiving capabilities
  • data - buffer for data to send/recv
  • send_cap - whether to send a capability or not
  • service_time - only for yielding server sockets, how much remaining time a client should have when sending

This is the S3K Wiki.

Clone this wiki locally