MINIX 3 Kernel API

In general, kernel calls allows system processes to request kernel services, for example to perform privileged operations. This document briefly discusses the organization of kernel calls in MINIX 3 and provides an overview of all kernel calls.

This document aims to describe the Kernel API of MINIX 3 git-trunk. While it is a constant work in progress, any mismatches between this document and SVN-current are unintentional.

A kernel call means that a request is sent to a kernel where it is handled by one of the kernel tasks. The details of assembling a request message, sending it to the kernel and awaiting the response are conveniently hidden in a system library. The header file of this library is src/include/minix/syslib.h and its implementation is found in src/lib/syslib.

The actual implementation of the kernel calls is defined in the SYSTEM kernel task. Suppose that a program makes a sys_call() system call. By convention, this call is transformed into a request message with type SYS_CALL that is sent to the kernel task SYSTEM. The SYSTEM task handles the request in a function named do_call() and returns the result.

The mapping of kernel call numbers and handler functions is done during the SYSTEM task's initialization response. src/kernel/system.c. The prototypes of the handler functions are declared in src/kernel/system.h. Their implementation is contained in separate files in the directory src/kernel/system/. These files are compiled into the library /src/kernel/system/system.a that is linked to the kernel.

The kernel call numbers and their request and response parameters are defined in src/include/minix/com.h. Kernel calls all start with SYS_ and all parameters that belong to the same kernel call share a common prefix.

A concise overview of the kernel calls in MINIX 3 is given in Table 1.

Table 1: This table provides an overview of the kernel calls in MINIX 3.

The kernel call interface is detailed below. For each kernel the message type, the purpose, message type, request and/or response parameters and return value are specified. The shorthand additional remarks about the future status of the call may also be provided.

Legends
CONSTANT: defined constant; a number indicating the request type or status.
PARAMETER: message parameter; a field in the request or response message.
void sys_call(arguments): system library function; shorthand to make a kernel call.

Alphabetical Overview

Shutdown MINIX and return to the boot monitor, if possible. This is used by PM, FS and TTY. Normal aborts usually are initiated by the user, for example by means of the shutdown command or typing Ctrl-Alt-Del. MINIX will also be taken down if a fatal error occurs in the PM or FS.

request parameters
ABRT_HOW: How to abort. One of the values defined in src/include/unistd.h

• RBT_HALT: Halt MINIX and return to the boot monitor.
• RBT_REBOOT: Reboot MINIX.
• RBT_PANIC: A kernel panic occurred.
• RBT_MONITOR: Run the specified code at the boot monitor.
• RBT_RESET: Hard reset the system.

ABRT_MON_ENDPT: Process to get the boot monitor parameters from.
ABRT_MON_LEN: Length of the boot monitor parameters.
ABRT_MON_ADDR: Virtual address of the parameters.

return value
OK: The shutdown sequence was started.
ENIVAL: Invalid process number.
EFAULT: Illegal monitor parameters address.
E2BIG: Monitor parameters exceed maximum length.

library functions
int sys_abort(int shutdown_status, …);

request parameters
(to be documented)

response parameters
(to be documented)

return value
(to be documented)

library functions
int sys_cprof(int action, int size, int endpt, void *ctl_ptr, void *mem_ptr);

Perform device I/O on behalf of a user-space device driver. The driver can request a single port to be read or written with this call. Also see the SYS_SDEVIO and SYS_VDEVIO kernel calls.

request parameters
DIO_REQUEST: Flags indicating what to do.

• _DIO_INPUT: Read a value from the given port.
• _DIO_OUTPUT: Write the given value to the given port.\\
  
• _DIO_BYTE: Read/write a byte value.
• _DIO_WORD: Read/write a word value.
• _DIO_LONG: Read/write a long value.

DIO_PORT: The port to be read or written.
DIO_VALUE: Value to write to the given port. For DIO_OUTPUT only.

response parameters
DIO_VALUE: Value that was read from the given port. For DIO_INPUT only.

return value
OK: The port I/O was successfully done.
EINVAL: An invalid DIO_REQUEST or DIO_TYPE was provided.

library functions
int sys_in(port_t port, unsigned long value, int io_type);
int sys_inb(port_t port, u8_t *byte);
int sys_inw(port_t port, u16_t *word);
int sys_inl(port_t port, u32_t *long);
int sys_out(port_t port, unsigned long value, int io_type);
int sys_outb(port_t port, u8_t byte);
int sys_outw(port_t port, u16_t word);
int sys_outl(port_t port, u32t long);

Finish a kernel signal. The PM uses this call to indicate if it has processed the kernel signals in the map obtained through a SYS_GETKSIG kernel call.

request parameters
SIG_ENDPT: The process that it concerns.

return value
EINVAL: The process had no pending signals or already exited.
OK: The kernel cleared all pending signals.

library functions
int sys_endksig(endpoint_t proc_nr);

Update a process' registers after a successful exec() POSIX-call. After the FS has copied the binary image into memory, the PM informs the kernel about the new register details.

request parameters
PR_ENDPT: Process that executed a program.
PR_STACK_PTR: New stack pointer.
PR_IP_PTR: New program counter.
PR_NAME_PTR: Pointer to a name of program.

return value
OK: This call always succeeds.

library functions
int sys_exec(endpoint_t proc, char *stack_ptr, char *prog_name, vir_bytes pc);

Clear a process slot. This call is to be used by PM only.

request parameters
PR_ENDPT: Slot number of exiting process if caller is PM. Use SELF to exit the PM.

return value
OK: The cleanup succeeded.
EINVAL: Incorrect process number.
EDONTREPLY: This call does not return if a system process exited.

library functions
int sys_exit(endpoint_t proc_nr);

Allocate a new (child) process in the kernel process table and initialize it based on the prototype (parent) process. The PM has found a free process slot for the child process in its own process table and now requests the kernel to update the kernel's process table.

request parameters
PR_ENDPT: Parent, the process that forked.
PR_SLOT: Child's process table slot.
PR_MEM_PTR: New memory map for the child.
PR_FORK_FLAGS: Fork flags.

• PFF_VMINHIBIT: Don't schedule process in VM mode until it has a new pagetable.

response parameters
PR_ENDPT: Process endpoint of the child.

return value:
OK: A new process slot was successfully assigned.
EINVAL: Invalid parent process number or child slot to use.

library functions:
int sys_fork(endpoint_t parent, int child, endpoint_t *child_endpoint, struct mem_map *ptr, u32_t flags);

Obtain a copy of a kernel data structure. This call supports user-space device drivers and servers that need certain system information.

request parameters
I_REQUEST: The type of system information that is requested.

• GET_AOUTHEADER: Copy boot image a.out headers.
• GET_HZ: Copy system clock frequency in ticks per second.
• GET_IDLETSC: Copy accumulated idle timestamp counter, if CONFIG_IDLE_TSC is defined.
• GET_IMAGE: Copy boot image table.
• GET_IRQACTIDS: Copy IRQ is-hook-active bits.
• GET_IRQHOOKS: Copy table with interrupt hooks.
• GET_KINFO: Copy kernel information structure.
• GET_KMESSAGES: Copy buffer with diagnostic kernel messages.
• GET_LOADINFO: Copy system load information.
• GET_LOCKTIMING: Copy lock times, if DEBUG_TIME_LOCKS is set.
• GET_MACHINE: Copy system information.
• GET_MONPARAMS: Copy parameters set by the boot monitor.
• GET_PRIV: Copy system privileges table slot.
• GET_PRIVTAB: Copy system privileges table.
• GET_PROC: Copy single process table slot.
• GET PROCTAB: Copy entire kernel process table.
• GET_RANDOMNESS: Copy randomness gathered by kernel events.
• GET_RANDOMNESS_BIN: Copy and wipe randomness bin.
• GET_WHOAMI: Copy process name and endpoint.

I_VAL_PTR: Virtual address where the information should be copied to.
I_VAL_LEN: Maximum length that the caller can handle.
I_VAL_PTR2: Optional, second address. Used when copying scheduling data.
I_VAL_LEN2: Optional, second length. Overloaded for process number.

return number
OK: The information request succeeded.
EFAULT: An illegal memory address was detected.
E2BIG: Requested data exceeds the maximum provided by the caller.

library functions
int sys_getaoutheader(struct exec *e_hdr, int index);
int sys_getidletsc(u64_t *idle_tsc);
int sys_getinfo(int request,void *ptr,int len,void *ptr2,int len2);
int sys_getirqactids(int *irq_actids);
int sys_getirqhooks(struct irq_hook *ptr);
int sys_getimage(struct boot_image *ptr);
int sys_getkinfo(struct kinfo *ptr);
int sys_getkmessages(struct kmessages *ptr);
int sys_getloadinfo(struct loadinfo *ptr);
int sys_getlocktimings(struct lock_timingdata *ptr);
int sys_getmachine(struct machine *ptr);
int sys_getmonparams(char *ptr,int max_len);
int sys_getpriv(struct priv *ptr, endpoint_t proc_nr);
int sys_getprivtab(struct priv *ptr);
int sys_getproc(struct proc *ptr,int proc_nr);
int sys_getproctab(struct proc *ptr);
int sys_getrandomness(struct randomness *ptr);
int sys_getrandom_bin(struct k_randomness_bin *ptr, int bin);
int sys_whoami(endpoint_t *ep, char *name, int namelen);

Checks whether there is a process that must be signaled. This is repeatedly done by the PM after receiving a notification that there are kernel signals pending.

response parameters
SIG_ENDPT: Return next process with pending signals or NONE.
SIG_MAP: Bit map with pending kernel signals.

return value
OK: This call always succeeds.

library functions
int sys_getksig(endpoint_t *proc_nr, sigset_t *sig_map);

Make a real-mode BIOS on behalf of a user-space device driver. This temporarily switches from 32-bit protected mode to 16-bit real-mode to access the BIOS calls. It is here to support the BIOS_WINI device driver.

request parameters
INT86_REG86: Address of request at the caller.

return value
OK: BIOS call successfully done.
EFAULT: Invalid request address.

library functions
int sys_int86(struct reg86u *reg86p);

Enable the CPU's I/O privilege level bits for the given process, so that it is allowed to directly perform I/O in user space.

request parameters
IOP_ENDPT: The process to give I/O privileges.

return value
OK: Always succeeds.

library functions
int sys_enable_iop(endpoint_t proc);

Set or reset a hardware interrupt policy for a given IRQ line and enable or disable interrupts for this line. This call allows user-space device drivers to grab a hook for use with the kernel's generic interrupt handler. The kernel's interrupt handler merely notifies the driver about the interrupt with a HARD_INT message and reenables the IRQ line if the policy says so. The notification message will contain the id provided by the caller as an argument. Once a policy is in place, drivers can enable and disable interrupts.

request parameters
IRQ_REQUEST: Interrupt control request to perform.

• IRQ_SETPOLICY: Set interrupt policy for the generic interrupt handler.
• IRQ_RMPOLICY: Remove a previously set interrupt policy.
• IRQ_ENABLE: Enable IRQs for the given IRQ line.
• IRQ_DISABLE: Disable IRQs for the given IRQ line.

IRQ_VECTOR: IRQ line that must be controlled.
IRQ_POLICY: Bit map with flags indicating IRQ policy.
IRQ_HOOK_ID: When setting a policy this provides index sent to caller upon interrupt. For other requests it is the kernel hook identifier returned by the kernel.

response parameters
IRQ_HOOK_ID: Kernel hook identifier associated with the driver.

return value
EINVAL: Invalid request, IRQ line, hook id, or process number.
EPERM: Only owner of hook can toggle interrupts or release the hook.
ENOSPC: No free IRQ hook could be found.
OK: The request was successfully handled.

library functions
int sys_irqctl(int request, int irq_vec, int policy, int *hook_id);
int sys_irqsetpolicy(int irq_vec, int policy, int *hook_id);
int sys_irqrmpolicy(int *hook_id);
int sys_irqenable(int *hook_id);
int sys_irqdisable(int *hook_id);

Signal a process on behalf of a system server. A system process can signal another process with this call. The kernel notifies the PM about the pending signal for further processing (Note that the kill() POSIX-call is directly handled at the PM). The PM uses this call to indirectly send a signal message to a system process. This happens when a signal arrives for a system process that set the special SIG_MESS signal handler with the sigaction() POSIX-call.

request parameters
SIG_ENDPT: Process to be signalled.
SIG_NUMBER: Signal number. Range from 0 to _NSIG.

return value
OK: Call succeeded.
EINVAL: Illegal process or signal number.
EPERM: Cannot send a signal to a kernel task. PM cannot signal a user process with a notification message.

library functions
int sys_kill(endpoint_t proc_nr, int sig_nr);

Write a 4-byte pattern into the indicated memory area. The call is used by the PM to zero the BSS segment on an exec() POSIX-call. The kernel is asked to do the work for performance reasons.

request parameters
MEM_PTR: Physical base address of the memory area.
MEM_COUNT: Length in bytes of the memory area.
MEM_PATTERN: The pattern byte to be written.

return value
OK: Call always succeeds.

library functions
int sys_memset(long pattern, phys_bytes base, phys_bytes length);

Install a new memory map for a newly forked process or if a process's memory map is changed. The kernel fetches the new memory map from PM and updates its data structures.

request parameters
PR_ENDPT: Install new map for this process.
PR_MEM_PTR: Pointer to memory map at PM.

return value
OK: New map was successfully installed.
EFAULT: Incorrect address for new memory map.
EINVAL: Invalid process number.

library functions
int sys_newmap(endpoint_t proc_nr, struct mem_map *ptr);

Change a process' priority. This is done by passing a nice value between PRIO_MIN(negative) and PRIO_MAX(positive). A nice value of zero resets the priority to the default.

request parameters
PR_ENDPT: Process whose priority should be changed.
PR_PRIORITY: New nice value for process' priority.

return value
OK: New priority was successfully set.
EINVAL: Invalid process number of priority.
EPERM: Cannot change priority of kernel task.

library functions
int sys_nice(endpoint_t proc_nr, int priority);

Copy data using physical addressing. The source and/or destination address can be virtual like with SYS_VIRCOPY, but in addition an arbitrary physical address is accepted with PHYS_SEG.

request parameters
CP_SRC_SPACE: Source segment.
CP_SRC_ADDR: Virtual source address.
CP_SRC_ENDPT: Process number of the source process.
CP_DST_SPACE: Destination segment.
CP_DST_ADDR: Virtual destination address.
CP_DST_ENDPT: Process number of the destination process.
CP_NR_BYTES: Number of bytes to copy.

return value
OK: The copying was done.
EDOM: Invalid copy count.
EFAULT: Virtual to physical mapping failed.
EINVAL: Incorrect segment type of process number.
EPERM: Only owner of REMOTE_SEG can copy to or from it.

library functions
int sys_abscopy(phys_bytes src_phys, phys_bytes dst_phys, phys_bytes count);
int sys_physcopy(endpoint_t src_proc, int src_seg, vir_bytes src_vir, endpoint_t dst_proc, int dst_seg, vir_bytes dst_vir, phys_bytes count);

Get a private privilege structure and update a process' privileges. This is used to dynamically start system services. For VM, this call also supports querying a memory range for previously added memory permissions.

request parameters
CTL_ENDPT: Process whose privileges should be updated/queried.
CTL_REQUEST: The privilege modification/query request.

• SYS_PRIV_ALLOW: Allow a process to run.
• SYS_PRIV_DISALLOW: Disallow a process from running.
• SYS_PRIV_SET_SYS: Give a process system privileges.
• SYS_PRIV_SET_USER: Give a process user privileges.
• SYS_PRIV_ADD_IO: Add an I/O range to the process's resources.
• SYS_PRIV_ADD_MEM: Add a memory range to the process's resources
• SYS_PRIV_ADD_IRQ: Add an IRQ to the process's resources.
• SYS_PRIV_QUERY_MEM: Check if the process has permission to access a physical memory range.

CTL_ARG_PTR: Pointer to arguments for this request (not for SYS_PRIV_QUERY_MEM).
CTL_PHYSSTART: Start of physical memory range to test (only for SYS_PRIV_QUERY_MEM).
CTL_PHYSLEN: Length of physical memory range to test (only for SYS_PRIV_QUERY_MEM).

return value
OK: The calls succeeded.
EINVAL: Invalid process number, request, or arguments.
ENOSPC: No free privilege structure found.
EPERM: Resources can not be added to user processes, or permission denied.
ENOMEM: No storage available for this resource.

library functions
int sys_privctl(endpoint_t proc, int req, void *p);
int sys_privquery_mem(endpoint_t proc, phys_bytes start, phys_bytes len);

request parameters
(to be documented)

response parameters
(to be documented)

return value
(to be documented)

library functions
int sys_profbuf(void *ctl_ptr, void *mem_ptr);

Copy from the BIOS area.

request parameters
RDB_ADDR: Absolute address in BIOS area.
RDB_BUF: Buffer address in the requesting process.
RDB_SIZE: The number of bytes to copy.

return value
OK: The call succeeded.
EDOM: Invalid number of bytes.
EFAULT: Invalid buffer address.

library functions
int sys_readbios(phys_bytes address, void *buf, size_t size);

Control the process's PROC_STOP flag. Used for process management (by PM). Stopping a process is generally done for the purpose of either setting up a signal handler or stopping a process that is about to be killed. When stopping for setting up a signal handler, the RC_DELAY flag will be supplied. This means that if the process is queued sending a message, or stopped for system call tracing, then this call will, instead of stopping the process, return EBUSY and later send a SIGNDELAY pseudo-signal to the process when it has been established that this process will not send a message anymore. The process never becomes actually runnable before PM eventually tells the kernel that it is done processing the SIGNDELAY (using SYS_ENDKSIG). This “delay stop” mechanism is used by PM to make sure that no signal is delivered to a process that still has a call pending to a system server. This is required for POSIX compliance.

request parameters
RC_ENDPT: The process number to control.
RC_ACTION: Stop or resume the process.

• RC_STOP: Stop the process.
• RC_RESUME: Resume the process.

RC_FLAGS: Request flags.

• RC_DELAY: Delay stop if process is sending.

return value
OK: The call succeeded.
EINVAL: Invalid process number.
EPERM: The caller is a kernel task.
EBUSY: The process is blocked sending a message or blocked for system call tracing.

library functions
int sys_runctl(endpoint_t proc_ep, int action, int flags);
int sys_stop(endpoint_t proc_ep);
int sys_delay_stop(endpoint_t proc_ep);
int sys_resume(endpoint_t proc_ep);

Copy data from a granted memory area of another process, into one's own address space. The caller must have CPF_READ access to the grant.

request parameters
SCP_FROM_TO: The process endpoint to copy from.
SCP_SEG: The segment within the caller to copy to (typically D).
SCP_GID: The grant ID.
SCP_OFFSET: Starting byte offset within the grant.
SCP_ADDRESS: Pointer to buffer to store the data in.
SCP_BYTES: Number of bytes to copy.

return value
OK: The call succeeded.
EINVAL: Invalid process number.
EPERM: Invalid grant ID, insufficient access, or bad byte range.
ELOOP: Chain of indirect grants too long.

library functions
int sys_safecopyfrom(endpoint_t source, cp_grant_id_t grant, vir_bytes grant_offset, vir_bytes my_address, size_t bytes, int my_seg);

Copy data from one's own address space, to a granted memory area of another process. The caller must have CPF_WRITE access to the grant.

request parameters
SCP_FROM_TO: The process endpoint to copy to.
SCP_SEG: The segment within the caller to copy from (typically D).
SCP_GID: The grant ID.
SCP_OFFSET: Starting byte offset within the grant.
SCP_ADDRESS: Pointer to data to copy.
SCP_BYTES: Number of bytes to copy.

return value
OK: The call succeeded.
EINVAL: Invalid process number.
EPERM: Invalid grant ID, insufficient access, or bad byte range.
ELOOP: Chain of indirect grants too long.

library functions
int sys_safecopyto(endpoint_t dest, cp_grant_id_t grant, vir_bytes grant_offset, vir_bytes my_address, size_t bytes, int my_seg);

Map a block of data for which the other process has previously granted permission. The result is that the granted area is mapped into the caller's local address space as shared memory. The caller decides where in its address space the mapping is placed. Any previous memory mapping at the chosen location will be undone.

request parameters
SMAP_EP: The process endpoint of the granting party.
SMAP_GID: The grant ID.
SMAP_OFFSET: Starting byte offset within the grant.
SMAP_SEG: The segment within the caller to map the area to (typically D).
SMAP_ADDRESS: Base address for the mapping. Must be page-aligned.
SMAP_BYTES: Number of bytes to map in. Must be multiple of the page size {X} in theory.
SMAP_FLAG: If 0, the mapping will be read-only. If 1, the mapping will be read-write.

return value
OK: The call succeeded.
EINVAL: Invalid process number.
EPERM: Invalid grant ID, insufficient access, or bad byte range.
ELOOP: Chain of indirect grants too long.
EBUSY: Too many shared mappings.
{X} any virtual memory errors are currently discarded

library functions
int sys_safemap(endpoint_t grantor, cp_grant_id_t grant, vir_bytes grant_offset, vir_bytes my_address, size_t bytes, int my_seg, int writable);

Revoke a grant-based shared memory mapping by grant ID or local address. For use by the granting party. The result is that the two parties each continue with a private copy of the memory area. If a local address is provided, there may be multiple matching mappings; in that case, all of them will be removed.

request parameters
SMAP_FLAG: If 0, revoke by local address. If 1, revoke by grant ID.
SMAP_GID: Local address or grant ID.

return value
OK: The call succeeded, or no matching mapping was found {X} .
EPERM: One of the original grants no longer exists {X} . The call may have partially succeeded in this case {X} .

library functions
int sys_saferevmap_gid(cp_grant_id_t grant);
int sys_saferevmap_addr(vir_bytes addr);

Revoke a grant-based shared memory mapping by local segment and address. For use by the receiver of the grant. The result is that the two parties each continue with a private copy of the memory area.

request parameters
SMAP_SEG: The segment of the mapping.
SMAP_ADDRESS: Base address of the mapping.

return value
OK: The call succeeded, or no matching mapping was found {X} .
EPERM: The original grant no longer exists {X} .

library functions
int sys_safeunmap(int my_seg, vir_bytes my_address);

Perform device I/O on behalf of a user-space device driver. Note that this call supports only byte and word granularity. The driver can request input or output of an entire buffer. Also see SYS_DEVIO and SYS_VDEVIO kernel calls.

request parameters
DIO_REQUEST: Flags indicating what to do.

• _DIO_INPUT: Read one or more values from the given port.
• _DIO_OUTPUT: Write one or more values to the given port.\\
  
• _DIO_BYTE: Read/write byte values.
• _DIO_WORD: Read/write word values.\\
  
• _DIO_SAFE: The given address is a grant.

DIO_PORT: The port to be read or written.
DIO_VEC_ENDPT: Process number where buffer is.
DIO_VEC_ADDR: Virtual address of buffer, or grant ID.
DIO_VEC_SIZE: Number of elements to input or output.
DIO_OFFSET: Offset into grant.

return value
OK: The port I/O was successfully done.
EINVAL: Invalid request or port granularity.
EPERM: Cannot do I/O for kernel tasks.
EFAULT: Invalid virtual address of buffer.

library functions
int sys_insb(port_t port, u8_t buffer, int count);
int sys_insw(port_t port, u16_t buffer, int count);
int sys_outsb(port_t port, u8_t buffer, int count);
int sys_outsw(port_t port, u16_t buffer, int count);
int sys_safe_insb(port_t port, endpoint_t proc_nr, void *grant, int count, vir_bytes offset);
int sys_safe_insw(port_t port, endpoint_t proc_nr, void *grant, int count, vir_bytes offset);
int sys_safe_outsb(port_t port, endpoint_t proc_nr, void *grant, int count, vir_bytes offset);
int sys_safe_outsw(port_t port, endpoint_t proc_nr, void *grant, int count, vir_bytes offset);
int sys_sdevio(int req, long port, endpoint_t proc_nr, void *buffer, int count, vir_bytes offset);

Add a memory segment to the process' LDT and its remote memory map. The call returns a selector and offset that can be used to directly reach the remote segment, as well as an index into the remote memory map that can be used with the SYS_VIRCOPY kernel call. No longer used.

request parameters
SEG_PHYS: Physical base address segment.
SEG_SIZE: Size of segment.

response parameters
SEG_INDEX: Index into remote memory map.
SEG_SELECT: Segment selector for LDT entry.
SEG_OFFSET: Offset within segment. Zero, unless 4K granularity is used.

return value
ENOSPC: No free slot in remote memory map and LDT.
OK: Segment descriptor successfully added.

library functions
int sys_segctl(int *index,u16_t *seg,vir_bytes *off,phys_bytes phys,vir_bytes size);

Set or reset a synchronous alarm timer. When the timer expires it causes a SYN_ALARM notification message with the current uptime as an argument to be sent to the caller. Only system processes can request synchronous alarms.

request parameters
ALRM_EXP_TIME: Absolute or relative expiration time in ticks for this alarm.
ALRM_ABS_TIME: Zero if expire time is relative to the current uptime.

response parameters
ALRM_TIME_LEFT: Ticks left on the previous alarm.

return value
OK: The alarm was successfully set.
EPERM: User processes cannot request alarms.

library functions
int sys_setalarm(clock_t expire_time, int abs_flag);

Set the address and size of the process's grant table. The previous address and size will be replaced.

request parameters
SG_ADDR: Address of grant table in own address space.
SG_SIZE: Number of entries.

return value
OK: The grant table has been set.
EPERM: The caller has no privilege table.

library functions
int sys_setgrant(cp_grant_t *grants, int ngrants);

Return from a POSIX-style signal handler. The PM requests the kernel to put things in order before the signalled process can resume execution. Also see the SYS_SIGSEND kernel call that pushes a signal context frame onto the stack.

request parameters
SIG_ENDPT: Indicates the process was signalled.
SIG_CTXT_PTR: Pointer to context structure for POSIX-style signal handling.

return value
OK: Signal handling action successfully performed.
EINVAL: Invalid process number or context structure.
EFAULT: Invalid context structure address, or could not copy signal frame.

library functions
int sys_sigreturn(endpoint_t proc_nr, struct sigmsg *sig_context);

Signal a process on behalf of the PM by placing the context structure onto the stack. The kernel fetches the structure, initializes it, and copies it to the user's stack.

request parameters
SIG_ENDPT: Indicates the process that was signalled.
SIG_CTXT_PTR: Pointer to content structure for POSIX-style signal handling.

return value
OK: Signal handling action successfully performed.
EINVAL: Invalid process number.
EPERM: Cannot signal kernel tasks.
EFAULT: Invalid context structure address, or could not copy signal frame.

library functions
int sys_sigsend(endpoint_t proc_nr, struct sigmsg *sig_context);

request parameters
(to be documented)

response parameters
(to be documented)

return value
(to be documented)

library functions
(to be documented)

Set the boot time. This effectively sets the current time, as the current time is computed by adding the uptime to the boot time.

request parameters
T_BOOTTIME: Boot time in seconds.

return value
OK: Always succeeds.

library functions
int sys_stime(time_t boottime);

request parameters
(to be documented)

response parameters
(to be documented)

return value
(to be documented)

library functions
(to be documented)

Get the kernel's uptime since boot and process execution times.

request parameters
T_ENDPT: Process for which to request the user and system time, or NONE.

response parameters
T_USER_TIME: Process' user time in ticks, if given endpoint is not NONE.
T_SYSTEM_TIME: Process's system time in ticks, if given endpoint is not NONE.
T_BOOT_TICKS: Number of ticks since MINIX boot (uptime).
T_BOOTTIME: Boot time in seconds.

return value
OK: Always succeeds.

library functions
int sys_times(endpoint_t proc_nr, clock_t *user_time, clock_t *system_time, clock_t *uptime);

Monitor or control execution of the given process. Handle the debugging commands supported by the ptrace() system call.

request parameters
CTL_REQUEST: The tracing request.

• T_STOP: Stop the process.
• T_GETINS: Return value from instruction space.
• T_GETDATA: Return value from data space.
• T_GETUSER: Return value from user process table.
• T_SETINS: Set value from instruction space.
• T_SETDATA: Set value from data space.
• T_SETUSER: Set value in user process table.
• T_RESUME: Resume execution.
• T_STEP: Set trace bit.
• T_SYSCALL: Trace system call.
• T_DETACH: Detach from a traced process.

CTL_ENDPT: The process number that is being traced.
CTL_ADDRESS: Virtual address in the traced process' space.
CTL_DATA: Data to be written.

response parameters
CTL_DATA: Data to be returned.

return value
OK: Trace operation succeeded.
EIO: Set or get value failed.
EINVAL: Unsupported trace request.
PERM: Can only trace user processes.

library functions
int sys_trace(int request, endpoint_t proc_nr, long addr, long *data_ptr);

Map a virtual address to a physical address and return the physical address. The virtual address can be in LOCAL_SEG, REMOTE_SEG or BIOS_SEG. An offset in bytes can be passed to verify whether this also falls within the segment.

request parameters
CP_SRC_ENDPT: Process number of the address relates to.
CP_SRC_SPACE: Segment identifier.
CP_SRC_ADDR: Offset within segment.
CP_NR_BYTES: Number of bytes from start.

response parameters
CP_DST_ADDR: Physical address if mapping succeeded.

return value
OK: The copying was done.
EFAULT: Virtual to physical mapping failed.
EINVAL: Incorrect segment type or process number.

remarks
Address zero within BIOS_SEG returns EFAULT, while the zeroth BIOS interrupt vector is in fact a valid address.

library functions
int sys_umap(endpoint_t proc_nr, int seg, vir_bytes vir_addr, vir_bytes count, phys_bytes *phys_addr);

Perform a series of device I/O on behalf of a user process. The call accepts a pointer to the first element of an array of (port,value)-pairs that are to be handled at once. Hardware interrupts are temporarily disabled to prevent the batch of I/O calls to be interrupted. Also see SYS_DEVIO and SYS_SDEVIO.

request parameters
DIO_REQUEST: Flags indicating what to do.

• _DIO_INPUT: Read values from ports.
• _DIO_OUTPUT: Write values to ports.\\
  
• _DIO_BYTE: Read/write byte values.
• _DIO_WORD: Read/write word values.
• _DIO_LONG: Read/write long values.

DIO_VEC_SIZE: The number of ports to be handled.
DIO_VEC_ADDR: Virtual address of the (port,address)-pairs in the caller's space.

return value
OK: The port I/O was successfully done.
EINVAL: Invalid request or granularity.
E2BIG: Vector size exceeds maximum that can be handled.
EFAULT: The address of the (port,value)-pair is erroneous.

library functions
int sys_voutb(pvb_pair_t *pvb_vec, int vec_size);
int sys_voutw(pvb_pair_t *pvw_vec, int vec_size);
int sys_voutl(pvb_pair_t *pvl_vec, int vec_size);
int sys_vinb(pvb_pair_t *pvb_vec, int vec_size);
int sys_vinw(pvb_pair_t *pvw_vec, int vec_size);
int sys_vinl(pvb_pair_t *pvl_vec, int vec_size);

Copy data using virtual addressing. The virtual can be in three segments: LOCAL_SEG(text, stack, data segments), REMOTE_SEG(e.g. RAM disk, video memory) and the BIOS_SEG(BIOS interrupt vectors, BIOS data area). This is the most common system call relating to copying.

request parameters
CP_SRC_SPACE: Source segment
CP_SRC_ADDR: Virtual source address.
CP_SRC_ENDPT: Process number of the source process.
CP_DST_SPACE: Destination segment.
CP_DST_ADDR: Virtual destination address.
CP_DST_ENDPT: Process number of the destination process.
CP_NR_BYTES: Number of bytes to copy.

return value
OK: The copying was done.
EDOM: Invalid copy count.
EFAULT: Virtual to physical mapping failed.
EPERM: No permission to use PHYS_SEG.
EINVAL: Incorrect segment type or process number.
EPERM: Only owner of REMOTE_SEG can copy to or from it.

library functions
int sys_biosin(vir_bytes bios_vir, vir_bytes dst_vir, phys_bytes bytes);
int sys_biosout(vir_bytes src_vir, vir_bytes bios_vir, phys_bytes bytes);
int sys_datacopy(vir_bytes src_proc, vir_bytes src_vir, endpoint_t dst_proc, vir_bytes dst_vir, phys_bytes bytes);
int sys_textcopy(vir_bytes src_proc, vir_bytes src_vir, endpoint_t dst_proc, vir_bytes dst_vir, phys_bytes bytes);
int sys_stackcopy(vir_bytes src_proc, vir_bytes src_vir, endpoint_t dst_proc, vir_bytes dst_vir, phys_bytes bytes);
int sys_vircopy(endpoint_t src_proc, int src_seg, vir_bytes src_vir, endpoint_t dst_proc, int dst_seg, vir_bytes dst_vir, phys_bytes bytes);

request parameters
(to be documented)

response parameters
(to be documented)

return value
(to be documented)

library functions
int sys_vmctl(endpoint_t who, int param, u32_t value);
int sys_vmctl_get_pagefault_i386(endpoint_t *who, u32_t *cr2, u32_t *err);
int sys_vmctl_get_cr3_i386(endpoint_t who, u32_t *cr3);
int sys_vmctl_get_memreq(endpoint_t *who, vir_bytes *mem, vir_bytes *len, int *wrflag, endpoint_t *who_s, vir_bytes *mem_s, endpoint_t *);
int sys_vmctl_enable_paging(struct mem_map *);
int sys_vmctl_get_mapping(int index, phys_bytes *addr, phys_bytes *len, int *flags);
int sys_vmctl_reply_mapping(int index, vir_bytes addr);

Perform a vectored safecopy operation. Each vector element specifies the source, destination, grant ID, grant offset, pointer into caller's address space, and number of bytes to copy. For each element, either source or destination must be set to SELF. The data segment is used for both source and destination.

request parameters
VSCP_VEC_ADDR: Pointer to a vector of struct vscp_vec elements.
VSCP_VEC_SIZE: Number of elements in the given vector.

return value
OK: The call succeeded.
EDOM: Invalid number of vector elements.
EFAULT: Invalid address.
EINVAL: Invalid process number, or neither source nor destination is set to SELF.
EPERM: Invalid grant ID, insufficient access, or bad byte range.
ELOOP: Chain of indirect grants too long.

remarks
The operation does not fail atomically: Upon failure, the receiving buffers should be considered to be in an undefined state.

library functions
int sys_vsafecopy(struct vscp_vec *copyvec, int elements);

Set and/or retrieve the value of one of a process' virtual timers. Each process may have two virtual timers: a virtual timer that is decreased as the process itself executes (user time), and a profile timer that decreases as the process executes (user time) or a system server executes on behalf of the process (system time). If a timer expires, the process will get a SIGVTALRM or SIGPROF signal, respectively.

request parameters
VT_WHICH: The timer to set/retrieve: VT_VIRTUAL for the virtual timer, or VT_PROF for the profile timer.
VT_SET: A flag indicating whether to set, or just retrieve, the timer's value.
VT_VALUE: The new expiration time, if VT_SET is nonzero.
VT_ENDPT: Endpoint of the target process.

response parameters
VT_VALUE: The old expiration time.

return value
OK: The timer was set (if requested), and the old timer value was returned.
EPERM: User processes cannot request timers.
EINVAL: Invalid timer or process.

library functions
int sys_vtimer(endpoint_t proc_nr, int which, clock_t *newval, clock_t *oldval);

Batch mapping of virtual to physical addresses.

int sys_vumap(endpoint_t endpt, struct vumap_vir *vvec, int vcount, size_t offset, int access, struct vumap_phys *pvec, int *pcount);

The sys_vumap function perform batch conversion of one or more virtual buffers, to a series of physical addresses for those buffers. It is intended to be used by drivers that want to perform DMA directly from or to buffers in another process, authorized by that other process by means of memory grants. It can also be used to look up local addresses in the calling processes itself.

The buffers to convert are provided in the vvec vector. Each entry in this vector contains either a grant identifier (vv_grant) or a local virtual address (vv_addr) for the buffer, and a size (vv_size) of the buffer. The owner of the buffer is specified using the endpt parameter; If endpt is set to SELF, the local virtual addresses are used; otherwise, the grant identifiers are used. The vcount parameter specifies the number of entries in the vvec vector. The caller must provide at least one entry. No more than MAPVEC_NR input entries are processed in one call.

The offset parameter determines the offset into the first entry of the vvec vector. This allows the caller to perform multiple sys_vumap calls to map input that exceeds the size limits for a single call. The offset affects both the address and the size of the first entry.

The access parameter specifies the access requested for the buffers. At least one of the following flags must be specified: VUA_READ (to read from the buffers), VUA_WRITE (to write to the buffers). If the VUA_READ flag is not set, any unallocated pages in the address range will be allocated automatically. If the VUA_READ flag is set, the caller must always provide allocated pages. The requested access must match that of the given grants, and thus acts as a sanity check; it however does not prevent the caller from performing DMA in the wrong direction on the resolved physical addresses.

The kernel stores the resulting physical addresses in the pvec vector. Each entry in this vector contains a physical address (pv_addr) and a size (pv_size). The caller must set the pcount integer to the maximum number of entries in the pvec vector; upon success, the variable will be set to the number of entries filled in by the kernel. The caller must provide at least one entry. Upon success, at least one and at most MAPVEC_NR output entries are returned. Upon failure, the pvec and pcount contents are unchanged.

The caller is encouraged not to pay too much attention to the returned pcount value for determining whether the entire input vector has been mapped. Instead, it should consider the sizes returned in the pvec entries. If the sum of the sizes in the pvec vector equals the sum of the sizes in the vvec vector, the entire virtual vector has been resolved. Otherwise, additional sys_vumap calls are necessary to resolve the rest of the virtual vector.

Return values (not complete):
OK: addresses successfully mapped
EINVAL: vcount or pcount is negative or zero
EINVAL: access contains neither VUA_READ nor VUA_WRITE
EFAULT: vvec or pvec point to invalid memory
EINVAL: one of the entries in vvec is zero-sized
EINVAL: one of the grants in vvec is invalid
EPERM: one of the grants in vvec is revoked
EPERM: the requested access does not match the granted access
EFAULT: the memory provided in one of the vvec entries is invalid
EFAULT: VUA_READ access is specified, and part of the given memory is not allocated

~-Original MINIX 3 Kernel API Document by Jorrit N. Herder jnhderder AT cs DOT vu DOT nl