Skip to content

API_v1

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.
  • Preemption mask (S3K_REG_PREEMPT): Mask for preemption error.
    • Hides the preemption of a system call if corresponding bit is clear.
    • When a system call X (see s3k_syscall_t) is preempted, the system call will be aborted and return S3K_ERR_PREEMPTED if bit X is set. Otherwise the system call will be retried.

Capabilities

TODO: Enumerate available capabilities and describe their fields.

System calls

Get Local Information

s3k_get_pid

int s3k_get_pid(void);

Returns the process ID of the caller.

Return: the process ID of the caller

s3k_get_time

uint64_t s3k_get_time(void);

Returns the current real-time.

Return: the current real-time.

s3k_get_timeout

uint64_t s3k_get_timeout(void);

Returns the timeout of the current minor frame.

Return: the timeout of the current minor frame.

Write and Read registers

s3k_reg_read

uint64_t s3k_reg_read(uint64_t reg);

Returns the value of register.

Parameters:

  • reg - index of register.

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

s3k_reg_write

void s3k_reg_write(uint64_t reg, uint64_t val);

Sets the value of a register. Has no effect if reg is invalid.

Parameters:

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

Note: Setting the standard RISC-V registers may have unintended consequences.

Process Synchronization

s3k_sync

void s3k_sync(void);

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

s3k_sync_mem

void s3k_sync_mem(void);

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

Basic capability operations

s3k_cap_read

error_t s3k_cap_read(uint64_t i, cap_t *cap);

Read the descriptor of the i'th capability.

Parameters:

  • i - index of capability.
  • cap - buffer to write the descriptor.

Returns:

  • S3K_SUCCESS - if descriptor was read.
  • S3K_ERR_INVALID_INDEX - if i is invalid (i >= N_CAP).

s3k_cap_move

error_t s3k_cap_move(uint64_t i, uint64_t j);

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

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_INVALID_INDEX - if j is invalid (j >= N_CAP).
  • S3K_ERR_SRC_EMPTY - if the i'th slot was empty.
  • S3K_ERR_DST_OCCUPIED - if the j'th slot was not empty

s3k_cap_delete

error_t s3k_cap_delete(uint64_t i);

Delete the i'th capability.

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_EMPTY - if the i'th slot was empty.

s3k_cap_revoke

error_t s3k_cap_revoke(uint64_t i);

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

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_EMPTY - if the i'th slot was empty.

s3k_cap_derive

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

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).

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_INVALID_INDEX - if j is invalid (j >= N_CAP).
  • S3K_ERR_EMPTY - if the i'th slot was empty.
  • S3K_ERR_DST_OCCUPIED - if the j'th slot was occupied.
  • S3K_ERR_INVALID_CAPABILITY - 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.

PMP Frame Invocations

s3k_pmp_load

error_t s3k_pmp_load(uint64_t i, uint64_t j)

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.

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_INVALID_SLOT - if j is invalid (j >= N_PMP).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_DST_OCCUPIED - if the j'th PMP slot was occupied.
  • S3K_ERR_INVALID_PMP - if i'th capability is invalid.

s3k_pmp_unload

error_t s3k_pmp_unload(uint64_t i)

Unload the i'th capability.

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

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_INVALID_PMP - if i'th capability is invalid.

Monitor Invocations

s3k_monitor_suspend

error_t s3k_monitor_suspend(uint64_t i, uint64_t pid)

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.

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_INVALID_PID - if pid is invalid (pid >= N_PROC).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_INVALID_MONITOR - if i'th capability is invalid.

s3k_monitor_resume

error_t s3k_monitor_resume(uint64_t i, uint64_t pid)

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.

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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_INVALID_PID - if pid is invalid (pid >= N_PROC).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_INVALID_MONITOR - 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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_INVALID_PID - if pid is invalid (pid >= N_PROC).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_INVALID_MONITOR - 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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_INVALID_PID - if pid is invalid (pid >= N_PROC).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_INVALID_MONITOR - 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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_INVALID_INDEX - if j is invalid (j >= N_CAP).
  • S3K_ERR_INVALID_SLOT - if k is invalid (k >= N_PMP).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_DST_OCCUPIED - if the k'th PMP slot of process pid was occupied.
  • S3K_ERR_INVALID_MONITOR - if i'th capability is invalid.
  • S3K_ERR_INVALID_PMP - if 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_INVALID_INDEX - if i is invalid (i >= N_CAP).
  • S3K_ERR_INVALID_INDEX - if j is invalid (j >= N_CAP).
  • S3K_ERR_EMPTY - if the i'th capability slot was empty.
  • S3K_ERR_INVALID_MONITOR - if i'th capability is invalid.
  • S3K_ERR_INVALID_PMP - if j'th capability is invalid.

s3k_monitor_cap_move

error_t s3k_monitor_cap_move();

Socket Invocations

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_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