portugalfuturista/seL4
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
seL4/libsel4/include/interfaces/sel4.xml
Curtis Millar afbea15710 mcs: Add sporadic flag to SchedControl_Configure 
This adds a flags parameter to SchedControl_Configure to enable
configuration of a sporadic SC.

This also allows flags to be added in the future as needed without
breaking the API.

This allows the user to configure an SC either to be constrained as a
sporadic task where accumulated time is only delayed to when a task has
become runnable (implementing the sporadic server algorithm) or
whenever the task becomes the current executing task (implementing the
sliding-window constraint as in constant-bandwidth servers).

This can be used to prevent non-realtime tasks from exceeding bandwidth
under any circumstances, even in an over-committed configuration, whilst
also allowing work-conserving tasks to be configured in the same system.

To implement sporadic servers, we need to ensure that the suspension of
a task cannot be used as a mechanism to amplify budget of a task by
granting that task access to effectively multiple periods worth of
replenishments within a single period.

To align the implementation of SCs with the model of sporadic servers we
must delay available time until the release of a task. Within seL4, a
release would be any time where an SC changes from not being associated
with a Running, RunningVM, or Restart thread to one that is.

This can occur when an SC is bound to a new thread in such a state or
when a thread changes to such a state from any non-running states.

Critically, replenishments should not be delayed at the point when an SC
becomes the current SC (as was the case prior to this commit). This has
the effect of enforcing a continuous, constant bandwidth which is a
restriction that is incompatible with standard scheduling logic.

Accounting for this requires inserting a new refill_unblock_check
call whenever a sporadic SC is unblocked and removing the
refill_unblock_check call from when said SC is scheduled.

Signed-off-by: Curtis Millar <curtis.millar@data61.csiro.au>
2021-04-14 15:24:40 +10:00

757 lines
48 KiB
XML
Raw Blame History

<?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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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>
</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>
</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."/>
</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>
</method>
<method id="TCBSetAffinity" name="SetAffinity" condition="(!defined CONFIG_KERNEL_MCS) &amp;&amp; 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."/>
</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."/>
</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"/>
</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."/>
</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"/>
</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"/>
</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."/>
</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."/>
</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."/>
</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>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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."/>
</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>
</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."/>
</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>
</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."/>
</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." />
</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 if the scheduling context is already bound to a thread or
notification object.
</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"/>
</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>
</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."/>
</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."/>
</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"/>
</method>
</interface>
</api>
Reference in a new issue View git blame Copy permalink