mirror of
https://github.com/seL4/seL4.git
synced 2026-03-27 18:39:55 +00:00
526206aabe
Add error conditions for the lazy bind of SchedContexts to
notifications or TCBs (introduced in e18e32e28e).
Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>
1501 lines
87 KiB
XML
1501 lines
87 KiB
XML
<?xml version="1.0" ?>
|
|
<!--
|
|
Copyright 2020, Data61, CSIRO (ABN 41 687 119 230)
|
|
|
|
SPDX-License-Identifier: BSD-2-Clause
|
|
-->
|
|
|
|
<api name="ObjectApi">
|
|
|
|
<interface name="seL4_Untyped" manual_name="Untyped" cap_description="CPTR to an untyped object.">
|
|
|
|
<method id="UntypedRetype" name="Retype" manual_name="Retype" manual_label="untyped_retype">
|
|
<brief>
|
|
Retype an untyped object
|
|
</brief>
|
|
<description>
|
|
Given a capability, <texttt text="_service"/>, to an untyped object,
|
|
creates <texttt text="num_objects"/> of the requested type. Creates
|
|
<texttt text="num_objects"/> capabilities to the new objects starting
|
|
at <texttt text="node_offset"/> in the CNode specified by
|
|
<texttt text="root"/>, <texttt text="node_index"/>, and
|
|
<texttt text="node_depth"/>.
|
|
|
|
For variable-sized
|
|
kernel objects, the <texttt text="size_bits"/> argument is used to
|
|
determine the size of objects to create. The relationship between
|
|
<texttt text="size_bits"/> and object size depends on the type of object
|
|
being created. <docref>See <autoref label="sec:object_sizes"/> for more information
|
|
about object sizes.</docref>
|
|
|
|
<docref>See <autoref label="sec:kernmemalloc"/> for more information about how untyped
|
|
memory is retyped.</docref>
|
|
|
|
<docref>See <autoref label="sec:caps_to_new_objects"/> for more information about the
|
|
placement of capabilities to created objects.</docref>
|
|
</description>
|
|
<param dir="in" name="type" type="seL4_Word"
|
|
description="The seL4 object type that we are retyping to."/>
|
|
<param dir="in" name="size_bits" type="seL4_Word"
|
|
description="Used to determine the size of variable-sized objects."/>
|
|
<param dir="in" name="root" type="seL4_CNode"
|
|
description="CPTR to the CNode at the root of the destination CSpace."/>
|
|
<param dir="in" name="node_index" type="seL4_Word"
|
|
description="CPTR to the destination CNode. Resolved relative to the root parameter."/>
|
|
<param dir="in" name="node_depth" type="seL4_Word"
|
|
description="Number of bits of node_index to translate when addressing the destination CNode."/>
|
|
<param dir="in" name="node_offset" type="seL4_Word"
|
|
description="Number of slots into the node at which capabilities start being placed."/>
|
|
<param dir="in" name="num_objects" type="seL4_Word"
|
|
description="Number of capabilities to create."/>
|
|
<error name="seL4_DeleteFirst" description="A capability exists in the destination window of the CNode."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The <texttt text="root"/>, <texttt text="node_index"/>, or <texttt text="node_depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidArgument">
|
|
<description>
|
|
The <texttt text="size_bits"/> is too big or too small for the requested object type.
|
|
Or, <texttt text="type"/> cannot be created from a device untyped <docref>(see <autoref label="sec:kernmemalloc"/>)</docref>.
|
|
Or, the requested object <texttt text="type"/> does not exist.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_NotEnoughMemory" description="The total size of the new objects exceeds the space available."/>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="num_objects"/> do not fit in the destination CNode at <texttt text="node_offset"/>.
|
|
Or, <texttt text="num_objects"/> is greater than <texttt text="CONFIG_RETYPE_FAN_OUT_LIMIT"/>.
|
|
Or, <texttt text="size_bits"/> is too large.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
</interface>
|
|
|
|
<interface name="seL4_TCB" manual_name="TCB" cap_description="Capability to the TCB which is being operated on.">
|
|
|
|
<method id="TCBReadRegisters" name="ReadRegisters" manual_name="Read Registers" manual_label="tcb_readregisters">
|
|
<brief>
|
|
Read a thread's registers into the first <texttt text="count"/> fields of a given
|
|
seL4_UserContext
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:read_write_registers"/></docref>
|
|
</description>
|
|
<param dir="in" name="suspend_source" type="seL4_Bool"
|
|
description="The invocation should also suspend the source thread."/>
|
|
<param dir="in" name="arch_flags" type="seL4_Uint8"
|
|
description="Architecture dependent flags. These have no mearing on either x86 or ARM."/>
|
|
<param dir="in" name="count" type="seL4_Word" description="The number of registers to read."/>
|
|
<param dir="out" name="regs" type="seL4_UserContext"
|
|
description="The structure to read the registers into."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="_service"/> is the current thread's TCB.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="count"/> requested too few or too many registers.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBWriteRegisters" name="WriteRegisters" manual_name="Write Registers" manual_label="tcb_writeregisters">
|
|
<brief>
|
|
Set a thread's registers to the first <texttt text="count"/> fields of a given seL4_UserContext
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:read_write_registers"/></docref>
|
|
</description>
|
|
<param dir="in" name="resume_target" type="seL4_Bool"
|
|
description="The invocation should also resume the destination thread."/>
|
|
<param dir="in" name="arch_flags" type="seL4_Uint8"
|
|
description="Architecture dependent flags. These have no mearing on either x86 or ARM."/>
|
|
<param dir="in" name="count" type="seL4_Word"
|
|
description="The number of registers to be set."/>
|
|
<param dir="in" name="regs" type="seL4_UserContext"
|
|
description="Data structure containing the new register values."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="_service"/> is the current thread's TCB.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBCopyRegisters" name="CopyRegisters" manual_name="Copy Registers" manual_label="tcb_copyregisters">
|
|
<brief>
|
|
Copy the registers from one thread to another
|
|
</brief>
|
|
<description>
|
|
In the context of this function, frame registers are those that are read, modified or preserved by a
|
|
system call and integer registers are those that are not. Refer to the seL4 userland library source for specifics.
|
|
<docref><autoref label="sec:thread_deactivation"/></docref>
|
|
</description>
|
|
<cap_param append_description=" This is the destination TCB."/>
|
|
<param dir="in" name="source" type="seL4_TCB" description="Cap to the source TCB."/>
|
|
<param dir="in" name="suspend_source" type="seL4_Bool"
|
|
description="The invocation should also suspend the source thread."/>
|
|
<param dir="in" name="resume_target" type="seL4_Bool"
|
|
description="The invocation should also resume the destination thread."/>
|
|
<param dir="in" name="transfer_frame" type="seL4_Bool"
|
|
description="Frame registers should be transferred."/>
|
|
<param dir="in" name="transfer_integer" type="seL4_Bool"
|
|
description="Integer registers should be transferred."/>
|
|
<param dir="in" name="arch_flags" type="seL4_Uint8"
|
|
description="Architecture dependent flags. These have no mearing on either x86 or ARM."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="source"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBConfigure" name="Configure" manual_name="Configure" manual_label="tcb_configure" condition="!defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Set the parameters of a TCB
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:threads"/></docref>
|
|
</description>
|
|
<param dir="in" name="fault_ep" type="seL4_Word"
|
|
description="CPTR to the endpoint which receives IPCs when this thread faults. This capability is in the CSpace of the thread being configured."/>
|
|
<param dir="in" name="cspace_root" type="seL4_CNode"
|
|
description="The new CSpace root."/>
|
|
<param dir="in" name="cspace_root_data" type="seL4_Word"
|
|
description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/>
|
|
<param dir="in" name="vspace_root" type="seL4_CPtr"
|
|
description="The new VSpace root."/>
|
|
<param dir="in" name="vspace_root_data" type="seL4_Word"
|
|
description="Has no effect on x86 or ARM processors."/>
|
|
<param dir="in" name="buffer" type="seL4_Word"
|
|
description="Location of the thread's IPC buffer. Must be 512-byte aligned. The IPC buffer may not cross a page boundary."/>
|
|
<param dir="in" name="bufferFrame" type="seL4_CPtr"
|
|
description="Capability to a page containing the thread's IPC buffer."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/>, <texttt text="bufferFrame"/>, <texttt text="cspace_root"/>, or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="vspace_root"/> is not assigned to an ASID pool.
|
|
Or, <texttt text="cspace_root_data"/> is invalid.
|
|
Or, <texttt text="buffer"/> is not aligned.
|
|
Or, <texttt text="bufferFrame"/> is retyped from a device untyped <docref>(see <autoref label="sec:kernmemalloc"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
The <texttt text="bufferFrame"/>, <texttt text="cspace_root"/>, or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
<method id="TCBConfigure" name="Configure" manual_name="Configure (MCS)" manual_label="tcb_configure_mcs" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Set the parameters of a TCB
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:threads"/></docref>
|
|
</description>
|
|
<param dir="in" name="cspace_root" type="seL4_CNode"
|
|
description="The new CSpace root."/>
|
|
<param dir="in" name="cspace_root_data" type="seL4_Word"
|
|
description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/>
|
|
<param dir="in" name="vspace_root" type="seL4_CPtr"
|
|
description="The new VSpace root."/>
|
|
<param dir="in" name="vspace_root_data" type="seL4_Word"
|
|
description="Has no effect on x86 or ARM processors."/>
|
|
<param dir="in" name="buffer" type="seL4_Word"
|
|
description="Location of the thread's IPC buffer. Must be 512-byte aligned. The IPC buffer may not cross a page boundary."/>
|
|
<param dir="in" name="bufferFrame" type="seL4_CPtr"
|
|
description="Capability to a page containing the thread's IPC buffer."/>
|
|
<error name="seL4_AlignmentError">
|
|
<description>
|
|
The <texttt text="buffer"/> is not aligned.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/>, <texttt text="bufferFrame"/>, <texttt text="cspace_root"/>, or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="vspace_root"/> is not assigned to an ASID pool.
|
|
Or, <texttt text="cspace_root_data"/> is invalid.
|
|
Or, <texttt text="bufferFrame"/> is retyped from a device untyped <docref>(see <autoref label="sec:kernmemalloc"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
The <texttt text="bufferFrame"/>, <texttt text="cspace_root"/>, or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetPriority" name="SetPriority" manual_name="Set Priority" manual_label="tcb_setpriority">
|
|
<brief>
|
|
Change a thread's priority
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:sched"/></docref>
|
|
</description>
|
|
<param dir="in" name="authority" type="seL4_TCB"
|
|
description="Capability to the TCB to use the MCP from when setting the priority."/>
|
|
<param dir="in" name="priority" type="seL4_Word"
|
|
description="The thread's new priority."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="authority"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="priority"/> is greater than the maximum controlled priority of <texttt text="authority"/>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetMCPriority" name="SetMCPriority" manual_name="Set Maximum Controlled Priority" manual_label="tcb_setmcpriority">
|
|
<brief>
|
|
Change a thread's maximum controlled priority
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:sched"/></docref>
|
|
</description>
|
|
<param dir="in" name="authority" type="seL4_TCB"
|
|
description="Capability to the TCB to use the MCP from when setting the MCP."/>
|
|
<param dir="in" name="mcp" type="seL4_Word"
|
|
description="The thread's new maximum controlled priority."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="authority"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="mcp"/> is greater than the maximum controlled priority of <texttt text="authority"/>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetSchedParams" name="SetSchedParams" manual_name="Set Sched Params" manual_label="tcb_setschedparams" condition="!defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Change a thread's priority and maximum controlled priority.
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:sched"/></docref>
|
|
</description>
|
|
<param dir="in" name="authority" type="seL4_TCB"
|
|
description="Capability to the TCB to use the MCP from when setting the priority and MCP."/>
|
|
<param dir="in" name="mcp" type="seL4_Word"
|
|
description="The thread's new maximum controlled priority."/>
|
|
<param dir="in" name="priority" type="seL4_Word"
|
|
description="The thread's new priority."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="authority"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="mcp"/> is greater than the maximum controlled priority of <texttt text="authority"/>.
|
|
Or, <texttt text="priority"/> is greater than the maximum controlled priority of <texttt text="authority"/>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
<method id="TCBSetSchedParams" name="SetSchedParams" manual_name="Set Sched Params (MCS)" manual_label="tcb_setschedparams_mcs" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Change a thread's priority, maximum controlled priority, scheduling context
|
|
and fault handler.
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:sched"/></docref>
|
|
</description>
|
|
<param dir="in" name="authority" type="seL4_TCB"
|
|
description="Capability to the TCB to use the MCP from when setting the priority and MCP."/>
|
|
<param dir="in" name="mcp" type="seL4_Word"
|
|
description="The thread's new maximum controlled priority."/>
|
|
<param dir="in" name="priority" type="seL4_Word"
|
|
description="The thread's new priority."/>
|
|
<param dir="in" name="sched_context" type="seL4_CPtr"
|
|
description="Capability to the scheduling context that the TCB should run on. If the scheduling context is already bound to a notification or TCB that is not this TCB this operation will fail. Similarly, if this TCB is already bound to a scheduling context that is not this scheduling context, this will also fail."/>
|
|
<param dir="in" name="fault_ep" type="seL4_CPtr"
|
|
description="CPTR to the endpoint which receives IPCs when this thread faults."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="_service"/> or <texttt text="sched_context"/> is already bound.
|
|
Or, <texttt text="_service"/> is the current thread's TCB.
|
|
Or, <texttt text="_service"/> is a TCB in the blocked state and <texttt text="sched_context"/> is not schedulable.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/>, <texttt text="authority"/>, <texttt text="sched_context"/>, or <texttt text="fault_ep"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="fault_ep"/> does not have both Write rights and either Grant or GrantReply rights to the Endpoint <docref>(see <autoref label="sec:cap_rights"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="mcp"/> is greater than the maximum controlled priority of <texttt text="authority"/>.
|
|
Or, <texttt text="priority"/> is greater than the maximum controlled priority of <texttt text="authority"/>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetTimeoutEndpoint" name="SetTimeoutEndpoint" manual_name="Set Timeout Endpoint" manual_label="tcb_settimeoutendpoint" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Set a thread's timeout endpoint.
|
|
</brief>
|
|
<description>
|
|
Timeout exception messages will be delivered to this endpoint if it is not a null capability.
|
|
</description>
|
|
<param dir="in" name="timeout_fault_ep" type="seL4_CPtr"
|
|
description="CPTR to the endpoint which receives IPCs when this thread triggers timeout faults. Can be null."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="timeout_fault_ep"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="timeout_fault_ep"/> does not have both Write rights and either Grant or GrantReply rights to the Endpoint <docref>(see <autoref label="sec:cap_rights"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
<method id="TCBSetIPCBuffer" name="SetIPCBuffer" manual_name="Set IPC Buffer" manual_label="tcb_setipcbuffer">
|
|
<brief>
|
|
Set a thread's IPC buffer
|
|
</brief>
|
|
<description>
|
|
See Sections <shortref sec="threads"/> and <shortref sec="messageinfo"/>
|
|
</description>
|
|
<param dir="in" name="buffer" type="seL4_Word"
|
|
description="Location of the thread's IPC buffer. Must be 512-byte aligned. The IPC buffer may not cross a page boundary."/>
|
|
<param dir="in" name="bufferFrame" type="seL4_CPtr"
|
|
description="Capability to a page containing the thread's IPC buffer."/>
|
|
<error name="seL4_AlignmentError">
|
|
<description>
|
|
The <texttt text="buffer"/> is not aligned.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="bufferFrame"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="bufferFrame"/> is retyped from a device untyped <docref>(see <autoref label="sec:kernmemalloc"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
The <texttt text="bufferFrame"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetSpace" name="SetSpace" manual_name="Set Space" manual_label="tcb_setspace" condition="!defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Set the fault endpoint, CSpace and VSpace of a thread
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:threads"/></docref>
|
|
</description>
|
|
<param dir="in" name="fault_ep" type="seL4_Word"
|
|
description="CPTR to the endpoint which receives IPCs when this thread faults. This capability is in the CSpace of the thread being configured."/>
|
|
<param dir="in" name="cspace_root" type="seL4_CNode"
|
|
description="The new CSpace root."/>
|
|
<param dir="in" name="cspace_root_data" type="seL4_Word"
|
|
description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/>
|
|
<param dir="in" name="vspace_root" type="seL4_CPtr"
|
|
description="The new VSpace root."/>
|
|
<param dir="in" name="vspace_root_data" type="seL4_Word"
|
|
description="Has no effect on x86 or ARM processors."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/>, <texttt text="cspace_root"/>, or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="vspace_root"/> is not assigned to an ASID pool.
|
|
Or, <texttt text="cspace_root_data"/> is invalid.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
The <texttt text="cspace_root"/> or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetSpace" name="SetSpace" manual_name="Set Space" manual_label="tcb_setspace_mcs" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Set the fault endpoint, CSpace and VSpace of a thread
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:threads"/></docref>
|
|
</description>
|
|
<param dir="in" name="fault_ep" type="seL4_CPtr"
|
|
description="CPTR to the endpoint which receives IPCs when this thread faults. On MCS this cap gets copied into the TCB."/>
|
|
<param dir="in" name="cspace_root" type="seL4_CNode"
|
|
description="The new CSpace root."/>
|
|
<param dir="in" name="cspace_root_data" type="seL4_Word"
|
|
description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/>
|
|
<param dir="in" name="vspace_root" type="seL4_CPtr"
|
|
description="The new VSpace root."/>
|
|
<param dir="in" name="vspace_root_data" type="seL4_Word"
|
|
description="Has no effect on x86 or ARM processors."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/>, <texttt text="cspace_root"/>, or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="vspace_root"/> is not assigned to an ASID pool.
|
|
Or, <texttt text="cspace_root_data"/> is invalid.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="fault_ep"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="fault_ep"/> does not have both Write rights and either Grant or GrantReply rights to the Endpoint <docref>(see <autoref label="sec:cap_rights"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
The <texttt text="cspace_root"/> or <texttt text="vspace_root"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSuspend" name="Suspend" manual_name="Suspend" manual_label="tcb_suspend">
|
|
<brief>
|
|
Suspend a thread
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:thread_deactivation"/></docref>
|
|
</description>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBResume" name="Resume" manual_name="Resume" manual_label="tcb_resume">
|
|
<brief>
|
|
Resume a thread
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:thread_deactivation"/></docref>
|
|
</description>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBBindNotification" name="BindNotification" manual_name="Bind Notification" manual_label="tcb_bindnotification">
|
|
<brief>
|
|
Binds a notification object to a <obj name="TCB"/>
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:notification-binding"/></docref>
|
|
</description>
|
|
<param dir="in" name="notification" type="seL4_CPtr" description="Notification to bind."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="notification"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="_service"/> or <texttt text="notification"/> is already bound.
|
|
Or, <texttt text="notification"/> does not have Read rights to the Notification <docref>(see <autoref label="sec:cap_rights"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBUnbindNotification" name="UnbindNotification" manual_name="Unbind Notification" manual_label="tcb_unbindnotification">
|
|
<brief>
|
|
Unbinds any notification object from a <obj name="TCB"/>
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:notification-binding"/></docref>
|
|
</description>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="_service"/> is not bound to a notification.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetAffinity" name="SetAffinity" condition="(!defined CONFIG_KERNEL_MCS) && CONFIG_MAX_NUM_NODES > 1" manual_name="Set CPU Affinity" manual_label="tcb_setaffinity">
|
|
<brief>
|
|
Change a thread's current CPU in multicore machine
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:thread_creation"/></docref>
|
|
</description>
|
|
<param dir="in" name="affinity" type="seL4_Word"
|
|
description="The thread's new CPU to run."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="affinity"/> is not a valid CPU number.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetBreakpoint" name="SetBreakpoint" condition="defined(CONFIG_HARDWARE_DEBUG_API)" manual_name="Set Breakpoint" manual_label="tcb_setbreakpoint">
|
|
<brief>
|
|
Set or modify a thread's breakpoints or watchpoints. Calls to this function
|
|
overwrite previous configurations for the target breakpoint. Do not use this
|
|
with seL4_SingleStep: the API will reject the call and return an error.
|
|
Instead, use seL4_TCB_ConfigureSingleStepping to configure single-stepping.
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:debug_exceptions"/></docref>
|
|
</description>
|
|
<param dir="in" name="bp_num" type="seL4_Uint16"
|
|
description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/>
|
|
<param dir="in" name="vaddr" type="seL4_Word"
|
|
description="A virtual address which forms part of the match conditions for the triggering of the breakpoint."/>
|
|
<param dir="in" name="type" type="seL4_Word"
|
|
description="One of: seL4_InstructionBreakpoint, which specifies that the breakpoint should occur on instruction execution at the specified vaddr or seL4_DataBreakpoint, which states that the breakpoint should occur on data access at the specified vaddr."/>
|
|
<param dir="in" name="size" type="seL4_Word"
|
|
description="A positive integer indicating the trigger-span of the watchpoint. Must be zero when 'type' is seL4_InstructionBreakpoint."/>
|
|
<param dir="in" name="rw" type="seL4_Word"
|
|
description="One of seL4_BreakOnRead, meaning the breakpoint will only be triggered on read-access; seL4_BreakOnWrite meaning the breakpoint will only be triggered on write-access, and seL4_BreakOnReadWrite meaning the breakpoint will be triggered on any access."/>
|
|
<error name="seL4_AlignmentError">
|
|
<description>
|
|
The <texttt text="vaddr"/> is not aligned to <texttt text="size"/> bytes.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidArgument">
|
|
<description>
|
|
The <texttt text="bp_num"/>, <texttt text="size"/>, or <texttt text="rw"/> is not valid for the given <texttt text="type"/>.
|
|
Or, argument values are inappropriate for the target architecture.
|
|
Or, <texttt text="vaddr"/> is in the kernel virtual address range.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The argument values are inappropriate for the target architecture.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBGetBreakpoint" name="GetBreakpoint" condition="defined(CONFIG_HARDWARE_DEBUG_API)" manual_name="Get Breakpoint" manual_label="tcb_getbreakpoint">
|
|
<brief>
|
|
Read a breakpoint or watchpoint's current configuration.
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:debug_exceptions"/></docref>
|
|
</description>
|
|
<return>
|
|
A <texttt text="seL4_TCB_GetBreakpoint_t"/>: Struct that contains
|
|
<texttt text="seL4_Error error"/>, an seL4 API error value,
|
|
<texttt text="seL4_Word vaddr"/>, the virtual address at which the breakpoint will currently
|
|
be triggered;
|
|
<texttt text="seL4_Word type"/>, the type of operation which will currently trigger the
|
|
breakpoint, whether instruction execution, or data access;
|
|
<texttt text="seL4_Word size"/>, integer value for the span-size of the breakpoint.
|
|
Usually a power of two (1, 2, 4, etc.);
|
|
<texttt text="seL4_Word rw"/>, the access direction that will currently trigger the breakpoint,
|
|
whether read, write, or both and
|
|
<texttt text="seL4_Bool is_enabled"/>, which indicates whether or not the breakpoint
|
|
will currently be triggered if the match conditions are met.
|
|
</return>
|
|
<param dir="in" name="bp_num" type="seL4_Uint16"
|
|
description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/>
|
|
<param dir="out" name="vaddr" type="seL4_Word"/>
|
|
<param dir="out" name="type" type="seL4_Word"/>
|
|
<param dir="out" name="size" type="seL4_Word"/>
|
|
<param dir="out" name="rw" type="seL4_Word"/>
|
|
<param dir="out" name="is_enabled" type="seL4_Bool"/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The argument values are inappropriate for the target architecture.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBUnsetBreakpoint" name="UnsetBreakpoint" condition="defined(CONFIG_HARDWARE_DEBUG_API)" manual_name="Unset Breakpoint" manual_label="tcb_unsetbreakpoint">
|
|
<brief>
|
|
Disables a hardware breakpoint or watchpoint. The caller should assume that
|
|
the underlying configuration of the hardware registers has also been cleared.
|
|
Do not use this to clear single-stepping: the API will reject the call and
|
|
return an error. Instead, use seL4_TCB_ConfigureSingleStepping to disable
|
|
single-stepping.
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:debug_exceptions"/></docref>
|
|
</description>
|
|
<param dir="in" name="bp_num" type="seL4_Uint16"
|
|
description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the argument values are inappropriate for the target architecture.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The argument values are inappropriate for the target architecture.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBConfigureSingleStepping" name="ConfigureSingleStepping" condition="defined(CONFIG_HARDWARE_DEBUG_API)"
|
|
manual_name="Configure Single Stepping" manual_label="tcb_configuresinglestepping">
|
|
<brief>
|
|
Set or modify single stepping options for the target TCB. Subsequent calls to this
|
|
function overwrite previous configuration. Depending on your processor architecture,
|
|
this may or may not require the consumption of a hardware register.
|
|
</brief>
|
|
<description>
|
|
<docref>See Sections <shortref sec="single_stepping_debug_exception"/> and <shortref sec="debug_exceptions"/></docref>
|
|
</description>
|
|
<return>
|
|
A <texttt text="seL4_TCB_ConfigureSingleStepping_t"/>: Struct that contains
|
|
<texttt text="seL4_Error error"/>, an seL4 API error value,
|
|
<texttt text="seL4_Bool bp_was_consumed"/>, a boolean which indicates whether or not the <texttt text="bp_num"/>
|
|
breakpoint ID that was passed to the function, was consumed in the setup of the single-stepping
|
|
functionality: if this is <texttt text="true"/>, the caller should not attempt to re-use <texttt text="bp_num"/>
|
|
until it has disabled the single-stepping functionality via a subsequent call to
|
|
seL4_TCB_ConfigureSingleStepping with an <texttt text="num_instructions"/> argument of 0.
|
|
</return>
|
|
<param dir="in" name="bp_num" type="seL4_Uint16"
|
|
description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/>
|
|
<param dir="in" name="num_instructions" type="seL4_Word"
|
|
description="Number of instructions to step over before delivering a fault to the target thread's fault endpoint. Setting this to 0 disables single-stepping."/>
|
|
<param dir="out" name="bp_was_consumed" type="seL4_Bool"/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the argument values are inappropriate for the target architecture.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidArgument">
|
|
<description>
|
|
The argument values are inappropriate for the target architecture.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="TCBSetTLSBase" name="SetTLSBase" manual_name="Set TLS Base" manual_label="tcb_settlsbase">
|
|
<brief>
|
|
Set the TLS base of the target TCB. This intended for use on architectures where the register
|
|
used for TLS can only be written to in privilidged mode
|
|
</brief>
|
|
<description>
|
|
</description>
|
|
<return>
|
|
</return>
|
|
<param dir="in" name="tls_base" type="seL4_Word"
|
|
description="The TLS base to set"/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
</interface>
|
|
|
|
<interface name="seL4_CNode" manual_name="CNode">
|
|
<method id="CNodeRevoke" name="Revoke" manual_name="Revoke" manual_label="cnode_revoke">
|
|
<brief>
|
|
Delete all child capabilities of a capability
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode at the root of the CSpace where the capability will be found. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="index" type="seL4_Word" description="CPTR to the capability. Resolved from the root of the _service parameter."/>
|
|
<param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the capability being operated on."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The <texttt text="index"/> or <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeDelete" name="Delete" manual_name="Delete" manual_label="cnode_delete">
|
|
<brief>
|
|
Delete a capability
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode at the root of the CSpace where the capability will be found. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="index" type="seL4_Word" description="CPTR to the capability. Resolved from the root of the _service parameter."/>
|
|
<param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the capability being operated on."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The <texttt text="index"/> or <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeCancelBadgedSends" name="CancelBadgedSends" manual_name="Cancel Badged Sends" manual_label="cnode_cancelbadgedsends">
|
|
<brief>
|
|
The cancel badged sends method is intend to allow for the reuse of badges by an
|
|
authority. When used with a badged endpoint capability it
|
|
will cancel any outstanding send operations for that endpoint and badge.
|
|
This operation has no effect on un-badged or other objects.
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode at the root of the CSpace where the capability will be found. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="index" type="seL4_Word" description="CPTR to the capability. Resolved from the root of the _service parameter."/>
|
|
<param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the capability being operated on."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The <texttt text="index"/> or <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the capability does not have full rights to the Endpoint <docref>(see <autoref label="sec:cap_rights"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeCopy" name="Copy" manual_name="Copy" manual_label="cnode_copy">
|
|
<brief>
|
|
Copy a capability, setting its access rights whilst doing so
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/>
|
|
<param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/>
|
|
<param dir="in" name="src_root" type="seL4_CNode" description="CPTR to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/>
|
|
<param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/>
|
|
<param dir="in" name="rights" type="seL4_CapRights_t">
|
|
<description>
|
|
The rights inherited by the new capability.<docref>Possible values for this type are given in <autoref label="sec:cap_rights"/> .</docref>
|
|
</description>
|
|
</param>
|
|
<error name="seL4_DeleteFirst" description="The destination slot contains a capability."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The index or depth of the source or destination is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
Or, <texttt text="src_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, the source slot is empty.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the source capability cannot be derived <docref>(see <autoref label="sec:cap_derivation"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="dest_depth"/> or <texttt text="src_depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
The source capability cannot be derived <docref>(see <autoref label="sec:cap_derivation"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeMint" name="Mint" manual_name="Mint" manual_label="cnode_mint">
|
|
<brief>
|
|
Copy a capability, setting its access rights and badge whilst doing so
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/>
|
|
<param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/>
|
|
<param dir="in" name="src_root" type="seL4_CNode" description="CPTR to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/>
|
|
<param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/>
|
|
<param dir="in" name="rights" type="seL4_CapRights_t">
|
|
<description>
|
|
The rights inherited by the new capability.<docref>Possible values for this type are given in <autoref label="sec:cap_rights"/> .</docref>
|
|
</description>
|
|
</param>
|
|
<param dir="in" name="badge" type="seL4_Word" description="Badge or guard to be applied to the new capability. For badges on 32-bit platforms, the high 4 bits are ignored."/>
|
|
<error name="seL4_DeleteFirst" description="The destination slot contains a capability."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The index or depth of the source or destination is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
Or, <texttt text="src_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, the source slot is empty.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the source capability cannot be derived <docref>(see <autoref label="sec:cap_derivation"/>)</docref>.
|
|
Or, the badge or guard value is invalid.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="dest_depth"/> or <texttt text="src_depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
The source capability cannot be derived <docref>(see <autoref label="sec:cap_derivation"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeMove" name="Move" manual_name="Move" manual_label="cnode_move">
|
|
<brief>
|
|
Move a capability
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/>
|
|
<param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/>
|
|
<param dir="in" name="src_root" type="seL4_CNode" description="CPTR to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/>
|
|
<param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/>
|
|
<error name="seL4_DeleteFirst" description="The destination slot contains a capability."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The index or depth of the source or destination is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
Or, <texttt text="src_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, the source slot is empty.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="dest_depth"/> or <texttt text="src_depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeMutate" name="Mutate" manual_name="Mutate" manual_label="cnode_mutate">
|
|
<brief>
|
|
Move a capability, setting its badge in the process
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/>
|
|
<param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/>
|
|
<param dir="in" name="src_root" type="seL4_CNode" description="CPTR to the CNode that forms the root of the source CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/>
|
|
<param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/>
|
|
<param dir="in" name="badge" type="seL4_Word" description="Badge or guard to be applied to the new capability. For badges on 32-bit platforms, the high 4 bits are ignored."/>
|
|
<error name="seL4_DeleteFirst" description="The destination slot contains a capability."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The index or depth of the source or destination is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
Or, <texttt text="src_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, the source slot is empty.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the guard value is invalid.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="dest_depth"/> or <texttt text="src_depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeRotate" name="Rotate" manual_name="Rotate" manual_label="cnode_rotate">
|
|
<brief>
|
|
Given 3 capability slots - a destination, pivot and source - move the capability in the
|
|
pivot slot to the destination slot and the capability in the source slot to the pivot slot
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode at the root of the CSpace where the destination slot will be found. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved relative to _service. Must be empty unless it refers to the same slot as the source slot."/>
|
|
<param dir="in" name="dest_depth" type="seL4_Uint8" description="Depth to resolve dest_index to."/>
|
|
<param dir="in" name="dest_badge" type="seL4_Word" description="The new capdata for the capability that ends up in the destination slot."/>
|
|
<param dir="in" name="pivot_root" type="seL4_CNode" description="CPTR to the CNode at the root of the CSpace where the pivot slot will be found. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="pivot_index" type="seL4_Word" description="CPTR to the pivot slot. Resolved relative to pivot_root. The resolved slot must not refer to the source or destination slots."/>
|
|
<param dir="in" name="pivot_depth" type="seL4_Uint8" description="Depth to resolve pivot_index to."/>
|
|
<param dir="in" name="pivot_badge" type="seL4_Word" description="The new capdata for the capability that ends up in the pivot slot."/>
|
|
<param dir="in" name="src_root" type="seL4_CNode" description="CPTR to the CNode at the root of the CSpace where the source slot will be found. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved relative to src_root."/>
|
|
<param dir="in" name="src_depth" type="seL4_Uint8" description="Depth to resolve src_index to."/>
|
|
<error name="seL4_DeleteFirst" description="If the destination is not the same slot as the source and the destination slot contains a capability."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The index or depth of the source, destination, or pivot is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
Or, <texttt text="src_root"/> or <texttt text="pivot_root"/> is a CPtr to a capability of the wrong type.
|
|
Or, the source or pivot slot is empty.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the pivot is the same slot as the source or destination.
|
|
Or, the guard value on the destination or pivot is invalid.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="dest_depth"/>, <texttt text="src_depth"/>, or <texttt text="pivot_depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="CNodeSaveCaller" name="SaveCaller" manual_name="Save Caller" manual_label="cnode_savecaller" condition="!defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Save the reply capability from the last time the thread was called in the given CSpace so that it can be invoked later
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:cnode-ops"/>.</docref>
|
|
</description>
|
|
<cap_param append_description="CPTR to the CNode at the root of the CSpace where the capability is to be saved. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="index" type="seL4_Word" description="CPTR to the slot in which to save the capability. Resolved from the root of the _service parameter."/>
|
|
<param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the slot being targeted."/>
|
|
<error name="seL4_DeleteFirst" description="The destination slot contains a capability."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The <texttt text="index"/> or <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
</interface>
|
|
|
|
<interface name="seL4_IRQControl" manual_name="IRQ Control" cap_description="An IRQControl capability. This gives you the authority to make this call.">
|
|
|
|
<method id="IRQIssueIRQHandler" name="Get" manual_name="Get" manual_label="irq_controlget">
|
|
<brief>
|
|
Create an IRQ handler capability
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:interrupts"/>.</docref>
|
|
</description>
|
|
<param dir="in" name="irq" type="seL4_Word" description="The IRQ that you want this capability to handle."/>
|
|
<param dir="in" name="root" type="seL4_CNode" description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize."/>
|
|
<param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/>
|
|
<param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/>
|
|
<error name="seL4_DeleteFirst" description="The destination slot contains a capability."/>
|
|
<error name="seL4_FailedLookup">
|
|
<description>
|
|
The <texttt text="root"/>, <texttt text="index"/>, or <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, on x86, an IOAPIC is being used.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="irq"/> is invalid for the target architecture.
|
|
Or, on x86, <texttt text="irq"/> is not in the ISA IRQ range.
|
|
Or, <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RevokeFirst">
|
|
<description>
|
|
An IRQ handler capability for <texttt text="irq"/> has already been created.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
</interface>
|
|
|
|
<interface name="seL4_IRQHandler" manual_name="IRQ Handler" cap_description="The IRQ handler capability.">
|
|
|
|
<method id="IRQAckIRQ" name="Ack" manual_name="Acknowledge" manual_label="irq_handleracknowledge">
|
|
<brief>
|
|
Acknowledge the receipt of an interrupt and re-enable it
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:interrupts"/>.</docref>
|
|
</description>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="IRQSetIRQHandler" name="SetNotification" manual_name="Set Notification" manual_label="irq_handlersetnotification">
|
|
<brief>
|
|
Set the notification which the kernel will signal on interrupts
|
|
controlled by the supplied IRQ handler capability
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:interrupts"/>.</docref>
|
|
</description>
|
|
<param dir="in" name="notification" type="seL4_CPtr" description="The notification which the IRQs will signal."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="notification"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="notification"/> does not have the Write right <docref>(see <autoref label="sec:cap_rights"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="IRQClearIRQHandler" name="Clear" manual_name="Clear" manual_label="irq_handlerclear">
|
|
<brief>
|
|
Clear the handler capability from the IRQ slot
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:interrupts"/>.</docref>
|
|
</description>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
</interface>
|
|
|
|
<interface name="seL4_DomainSet" manual_name="Domain Set" cap_description="Capability allowing domain configuration.">
|
|
|
|
<method id="DomainSetSet" name="Set" manual_name="Set" manual_label="domainset_set">
|
|
<brief>
|
|
Change the domain of a thread.
|
|
</brief>
|
|
<description>
|
|
<docref>See <autoref label="sec:domains"/>.</docref>
|
|
</description>
|
|
<param dir="in" name="domain" type="seL4_Uint8" description="The thread's new domain."/>
|
|
<param dir="in" name="thread" type="seL4_TCB" description="Capability to the TCB which is being operated on."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidArgument">
|
|
<description>
|
|
The <texttt text="domain"/> is greater than <texttt text="CONFIG_NUM_DOMAINS"/>.
|
|
Or, <texttt text="thread"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
</interface>
|
|
|
|
<interface name="seL4_SchedControl">
|
|
|
|
<method id="SchedControlConfigureFlags" name="ConfigureFlags" manual_name="ConfigureFlags" manual_label="schedcontrol_configureflags" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Set the parameters of a scheduling context by invoking the scheduling control capability. If the scheduling context is bound to a currently running thread, the parameters will take effect immediately: that is the current budget will be increased or reduced by the difference between the new and previous budget and the replenishment time will be updated according to any difference in the period. This can result in active threads being post-poned or released depending on the nature of the parameter change and the state of the thread. Additionally, if the scheduling context was previously empty (no budget) but bound to a runnable thread, this can result in a thread running for the first time since it now has access to CPU time. This call will return seL4 Invalid Argument if the parameters are too small (smaller than the kernel WCET for this platform) or too large (will overflow the timer).
|
|
</brief>
|
|
<description>
|
|
See <autoref label="sec:threads"/>
|
|
</description>
|
|
<return><errorenumdesc/></return>
|
|
<param dir="in" name="schedcontext" type="seL4_SchedContext"
|
|
description="Capability to the scheduling context which is being operated on."/>
|
|
<param dir="in" name="budget" type="seL4_Time"
|
|
description="Timeslice in microseconds, when the budget expires the thread will be pre-empted."/>
|
|
<param dir="in" name="period" type="seL4_Time"
|
|
description="Period in microseconds, if equal to budget, this thread will be treated as a round-robin thread. Otherwise, sporadic servers will be used to assure the scheduling context does not exceed the budget over the specified period."/>
|
|
<param dir="in" name="extra_refills" type="seL4_Word"
|
|
description="Number of extra sporadic replenishments this scheduling context should use. Ignored for round-robin threads."/>
|
|
<param dir="in" name="badge" type="seL4_Word"
|
|
description="Identifier for this scheduling context. Delivered to timeout exception handler. Can be used to determine which scheduling context triggered the timeout." />
|
|
<param dir="in" name="flags" type="seL4_Word"
|
|
description="Bitwise OR'd set of seL4_SchedContextFlag." />
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="schedcontext"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_RangeError">
|
|
<description>
|
|
The <texttt text="budget"/> or <texttt text="period"/> or <texttt text="extra_refills"/> is too big or too small.
|
|
Or, <texttt text="budget"/> is greater than <texttt text="period"/>.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
</interface>
|
|
|
|
<interface name="seL4_SchedContext">
|
|
|
|
<method id="SchedContextBind" name="Bind"
|
|
manual_name="Bind" manual_label="schedcontext_bind" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Bind an object to a scheduling context. The object can be a notification object or a
|
|
thread.
|
|
|
|
If the object is a thread and the thread is in a runnable state and the scheduling
|
|
context has available budget, this will start the thread running.
|
|
|
|
If the object is a notification, when passive threads wait on the notification object and
|
|
a signal arrives, the passive thread will receive the scheduling context and possess it
|
|
until it waits on the notification object again.
|
|
|
|
This operation will fail for notification objects if the scheduling context is already
|
|
bound to a notification object, and for thread objects if the the scheduling context is
|
|
already bound to a thread.
|
|
</brief>
|
|
<description>
|
|
See <autoref label="sec:threads"/>
|
|
</description>
|
|
<return><errorenumdesc/></return>
|
|
<param dir="in" name="cap" type="seL4_CPtr"
|
|
description="Capability to a TCB or a notification object"/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="_service"/> or <texttt text="cap"/> is already bound to the same type of object.
|
|
Or, <texttt text="cap"/> is a TCB in the blocked state and <texttt text="_service"/> is not schedulable.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="cap"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="SchedContextUnbind" name="Unbind"
|
|
manual_name="Unbind" manual_label="schedcontext_unbind" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Unbind any objects (threads or notification objects) from a scheduling context. This
|
|
will render the bound thread passive, see Section 6.1.5.
|
|
</brief>
|
|
<description>
|
|
See <autoref label="sec:threads"/>
|
|
</description>
|
|
<return><errorenumdesc/></return>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, the current thread's TCB is bound to <texttt text="_service"/>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
|
|
<method id="SchedContextUnbindObject" name="UnbindObject"
|
|
manual_name="UnbindObject" manual_label="schedcontext_unbindobject" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Unbind an object from a scheduling context. The object can be either a thread or a
|
|
notification.
|
|
|
|
If the thread being unbound is the thread that is bound to this scheduling context,
|
|
this will render the thread passive. However if the thread being
|
|
unbound received the scheduling context via scheduling context donation over IPC,
|
|
the scheduling context will be returned to the thread that it was originally bound to.
|
|
|
|
If the object is a notification and it is bound to the scheduling context, unbind it.
|
|
</brief>
|
|
<description>
|
|
See <autoref label="sec:passive"/>
|
|
</description>
|
|
<return><errorenumdesc/></return>
|
|
<param dir="in" name="cap" type="seL4_CPtr"
|
|
description="Capability to a notification that is bound to the scheduling context or capability to a tcb that is bound to this scheduling context or has received it through scheduling context donation."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="cap"/> is not bound to <texttt text="_service"/>.
|
|
Or, <texttt text="cap"/> is the current thread's TCB.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> or <texttt text="cap"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
<method id="SchedContextConsumed" name="Consumed" manual_name="Consumed"
|
|
manual_label="schedcontext_consumed" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
Return the amount of time used by this scheduling context since this function was last called or a timeout exception triggered.
|
|
</brief>
|
|
<description>
|
|
See <autoref label="sec:threads"/>
|
|
</description>
|
|
<return><errorenumdesc/></return>
|
|
<param dir="out" name="consumed" type="seL4_Time"
|
|
description="Amount consumed by this scheduling context."/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
<method id="SchedContextYieldTo" name="YieldTo"
|
|
manual_name="YieldTo" manual_label="schedcontext_yieldto" condition="defined(CONFIG_KERNEL_MCS)">
|
|
<brief>
|
|
If a thread is currently runnable and running on this scheduling context and the scheduling context has available budget, place it at the head of the scheduling queue.
|
|
If the caller is at an equal priority to the thread this will result in the thread being scheduled.
|
|
If the caller is at a higher priority the thread will not run until the threads priority is the highest priority in the system.
|
|
The caller must have a maximum control priority greater than or equal to the threads priority.
|
|
</brief>
|
|
<description>
|
|
TODO
|
|
</description>
|
|
<param dir="out" name="consumed" type="seL4_Time"/>
|
|
<error name="seL4_IllegalOperation">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
Or, <texttt text="_service"/> is not bound to a TCB or is bound to the current thread's TCB.
|
|
Or, the target thread's priority is greater than the current thread's maximum controlled priority <docref>(see <autoref label="sec:sched"/>)</docref>.
|
|
</description>
|
|
</error>
|
|
<error name="seL4_InvalidCapability">
|
|
<description>
|
|
The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
|
|
</description>
|
|
</error>
|
|
</method>
|
|
</interface>
|
|
|
|
</api>
|