1<?xml version="1.0" ?> 2<!-- 3 Copyright 2020, Data61, CSIRO (ABN 41 687 119 230) 4 5 SPDX-License-Identifier: BSD-2-Clause 6--> 7 8<api name="ObjectApi"> 9 10 <interface name="seL4_Untyped" manual_name="Untyped" cap_description="CPTR to an untyped object."> 11 12 <method id="UntypedRetype" name="Retype" manual_name="Retype" manual_label="untyped_retype"> 13 <brief> 14 Retype an untyped object 15 </brief> 16 <description> 17 Given a capability, <texttt text="_service"/>, to an untyped object, 18 creates <texttt text="num_objects"/> of the requested type. Creates 19 <texttt text="num_objects"/> capabilities to the new objects starting 20 at <texttt text="node_offset"/> in the CNode specified by 21 <texttt text="root"/>, <texttt text="node_index"/>, and 22 <texttt text="node_depth"/>. 23 24 For variable-sized 25 kernel objects, the <texttt text="size_bits"/> argument is used to 26 determine the size of objects to create. The relationship between 27 <texttt text="size_bits"/> and object size depends on the type of object 28 being created. <docref>See <autoref label="sec:object_sizes"/> for more information 29 about object sizes.</docref> 30 31 <docref>See <autoref label="sec:kernmemalloc"/> for more information about how untyped 32 memory is retyped.</docref> 33 34 <docref>See <autoref label="sec:caps_to_new_objects"/> for more information about the 35 placement of capabilities to created objects.</docref> 36 </description> 37 <param dir="in" name="type" type="seL4_Word" 38 description="The seL4 object type that we are retyping to."/> 39 <param dir="in" name="size_bits" type="seL4_Word" 40 description="Used to determine the size of variable-sized objects."/> 41 <param dir="in" name="root" type="seL4_CNode" 42 description="CPTR to the CNode at the root of the destination CSpace."/> 43 <param dir="in" name="node_index" type="seL4_Word" 44 description="CPTR to the destination CNode. Resolved relative to the root parameter."/> 45 <param dir="in" name="node_depth" type="seL4_Word" 46 description="Number of bits of node_index to translate when addressing the destination CNode."/> 47 <param dir="in" name="node_offset" type="seL4_Word" 48 description="Number of slots into the node at which capabilities start being placed."/> 49 <param dir="in" name="num_objects" type="seL4_Word" 50 description="Number of capabilities to create."/> 51 </method> 52 53 </interface> 54 55 <interface name="seL4_TCB" manual_name="TCB" cap_description="Capability to the TCB which is being operated on."> 56 57 <method id="TCBReadRegisters" name="ReadRegisters" manual_name="Read Registers" manual_label="tcb_readregisters"> 58 <brief> 59 Read a thread's registers into the first <texttt text="count"/> fields of a given 60 seL4_UserContext 61 </brief> 62 <description> 63 <docref>See <autoref label="sec:read_write_registers"/></docref> 64 </description> 65 <param dir="in" name="suspend_source" type="seL4_Bool" 66 description="The invocation should also suspend the source thread."/> 67 <param dir="in" name="arch_flags" type="seL4_Uint8" 68 description="Architecture dependent flags. These have no mearing on either x86 or ARM."/> 69 <param dir="in" name="count" type="seL4_Word" description="The number of registers to read."/> 70 <param dir="out" name="regs" type="seL4_UserContext" 71 description="The structure to read the registers into."/> 72 </method> 73 74 <method id="TCBWriteRegisters" name="WriteRegisters" manual_name="Write Registers" manual_label="tcb_writeregisters"> 75 <brief> 76 Set a thread's registers to the first <texttt text="count"/> fields of a given seL4_UserContext 77 </brief> 78 <description> 79 <docref>See <autoref label="sec:read_write_registers"/></docref> 80 </description> 81 <param dir="in" name="resume_target" type="seL4_Bool" 82 description="The invocation should also resume the destination thread."/> 83 <param dir="in" name="arch_flags" type="seL4_Uint8" 84 description="Architecture dependent flags. These have no mearing on either x86 or ARM."/> 85 <param dir="in" name="count" type="seL4_Word" 86 description="The number of registers to be set."/> 87 <param dir="in" name="regs" type="seL4_UserContext" 88 description="Data structure containing the new register values."/> 89 </method> 90 91 <method id="TCBCopyRegisters" name="CopyRegisters" manual_name="Copy Registers" manual_label="tcb_copyregisters"> 92 <brief> 93 Copy the registers from one thread to another 94 </brief> 95 <description> 96 In the context of this function, frame registers are those that are read, modified or preserved by a 97 system call and integer registers are those that are not. Refer to the seL4 userland library source for specifics. 98 <docref><autoref label="sec:thread_deactivation"/></docref> 99 </description> 100 <cap_param append_description=" This is the destination TCB."/> 101 <param dir="in" name="source" type="seL4_TCB" description="Cap to the source TCB."/> 102 <param dir="in" name="suspend_source" type="seL4_Bool" 103 description="The invocation should also suspend the source thread."/> 104 <param dir="in" name="resume_target" type="seL4_Bool" 105 description="The invocation should also resume the destination thread."/> 106 <param dir="in" name="transfer_frame" type="seL4_Bool" 107 description="Frame registers should be transferred."/> 108 <param dir="in" name="transfer_integer" type="seL4_Bool" 109 description="Integer registers should be transferred."/> 110 <param dir="in" name="arch_flags" type="seL4_Uint8" 111 description="Architecture dependent flags. These have no mearing on either x86 or ARM."/> 112 </method> 113 114 <method id="TCBConfigure" name="Configure" manual_name="Configure" manual_label="tcb_configure" condition="!defined(CONFIG_KERNEL_MCS)"> 115 <brief> 116 Set the parameters of a TCB 117 </brief> 118 <description> 119 <docref>See <autoref label="sec:threads"/></docref> 120 </description> 121 <param dir="in" name="fault_ep" type="seL4_Word" 122 description="CPTR to the endpoint which receives IPCs when this thread faults. This capability is in the CSpace of the thread being configured."/> 123 <param dir="in" name="cspace_root" type="seL4_CNode" 124 description="The new CSpace root."/> 125 <param dir="in" name="cspace_root_data" type="seL4_Word" 126 description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/> 127 <param dir="in" name="vspace_root" type="seL4_CPtr" 128 description="The new VSpace root."/> 129 <param dir="in" name="vspace_root_data" type="seL4_Word" 130 description="Has no effect on x86 or ARM processors."/> 131 <param dir="in" name="buffer" type="seL4_Word" 132 description="Location of the thread's IPC buffer. Must be 512-byte aligned. The IPC buffer may not cross a page boundary."/> 133 <param dir="in" name="bufferFrame" type="seL4_CPtr" 134 description="Capability to a page containing the thread's IPC buffer."/> 135 </method> 136 <method id="TCBConfigure" name="Configure" manual_name="Configure (MCS)" manual_label="tcb_configure_mcs" condition="defined(CONFIG_KERNEL_MCS)"> 137 <brief> 138 Set the parameters of a TCB 139 </brief> 140 <description> 141 <docref>See <autoref label="sec:threads"/></docref> 142 </description> 143 <param dir="in" name="cspace_root" type="seL4_CNode" 144 description="The new CSpace root."/> 145 <param dir="in" name="cspace_root_data" type="seL4_Word" 146 description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/> 147 <param dir="in" name="vspace_root" type="seL4_CPtr" 148 description="The new VSpace root."/> 149 <param dir="in" name="vspace_root_data" type="seL4_Word" 150 description="Has no effect on x86 or ARM processors."/> 151 <param dir="in" name="buffer" type="seL4_Word" 152 description="Location of the thread's IPC buffer. Must be 512-byte aligned. The IPC buffer may not cross a page boundary."/> 153 <param dir="in" name="bufferFrame" type="seL4_CPtr" 154 description="Capability to a page containing the thread's IPC buffer."/> 155 </method> 156 157 <method id="TCBSetPriority" name="SetPriority" manual_name="Set Priority" manual_label="tcb_setpriority"> 158 <brief> 159 Change a thread's priority 160 </brief> 161 <description> 162 <docref>See <autoref label="sec:sched"/></docref> 163 </description> 164 <param dir="in" name="authority" type="seL4_TCB" 165 description="Capability to the TCB to use the MCP from when setting the priority."/> 166 <param dir="in" name="priority" type="seL4_Word" 167 description="The thread's new priority."/> 168 </method> 169 170 <method id="TCBSetMCPriority" name="SetMCPriority" manual_name="Set Maximum Controlled Priority" manual_label="tcb_setmcpriority"> 171 <brief> 172 Change a thread's maximum controlled priority 173 </brief> 174 <description> 175 <docref>See <autoref label="sec:sched"/></docref> 176 </description> 177 <param dir="in" name="authority" type="seL4_TCB" 178 description="Capability to the TCB to use the MCP from when setting the MCP."/> 179 <param dir="in" name="mcp" type="seL4_Word" 180 description="The thread's new maximum controlled priority."/> 181 </method> 182 183 <method id="TCBSetSchedParams" name="SetSchedParams" manual_name="Set Sched Params" manual_label="tcb_setschedparams" condition="!defined(CONFIG_KERNEL_MCS)"> 184 <brief> 185 Change a thread's priority and maximum controlled priority. 186 </brief> 187 <description> 188 <docref>See <autoref label="sec:sched"/></docref> 189 </description> 190 <param dir="in" name="authority" type="seL4_TCB" 191 description="Capability to the TCB to use the MCP from when setting the priority and MCP."/> 192 <param dir="in" name="mcp" type="seL4_Word" 193 description="The thread's new maximum controlled priority."/> 194 <param dir="in" name="priority" type="seL4_Word" 195 description="The thread's new priority."/> 196 </method> 197 <method id="TCBSetSchedParams" name="SetSchedParams" manual_name="Set Sched Params (MCS)" manual_label="tcb_setschedparams_mcs" condition="defined(CONFIG_KERNEL_MCS)"> 198 <brief> 199 Change a thread's priority, maximum controlled priority, scheduling context 200 and fault handler. 201 </brief> 202 <description> 203 <docref>See <autoref label="sec:sched"/></docref> 204 </description> 205 <param dir="in" name="authority" type="seL4_TCB" 206 description="Capability to the TCB to use the MCP from when setting the priority and MCP."/> 207 <param dir="in" name="mcp" type="seL4_Word" 208 description="The thread's new maximum controlled priority."/> 209 <param dir="in" name="priority" type="seL4_Word" 210 description="The thread's new priority."/> 211 <param dir="in" name="sched_context" type="seL4_CPtr" 212 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."/> 213 <param dir="in" name="fault_ep" type="seL4_CPtr" 214 description="CPTR to the endpoint which receives IPCs when this thread faults."/> 215 </method> 216 217 <method id="TCBSetTimeoutEndpoint" name="SetTimeoutEndpoint" manual_name="Set Timeout Endpoint" manual_label="tcb_settimeoutendpoint" condition="defined(CONFIG_KERNEL_MCS)"> 218 <brief> 219 Set a thread's timeout endpoint. 220 </brief> 221 <description> 222 Timeout exception messages will be delivered to this endpoint if it is not a null capability. 223 </description> 224 <param dir="in" name="timeout_fault_ep" type="seL4_CPtr" 225 description="CPTR to the endpoint which receives IPCs when this thread triggers timeout faults. Can be null."/> 226 </method> 227 <method id="TCBSetIPCBuffer" name="SetIPCBuffer" manual_name="Set IPC Buffer" manual_label="tcb_setipcbuffer"> 228 <brief> 229 Set a thread's IPC buffer 230 </brief> 231 <description> 232 See Sections <shortref sec="threads"/> and <shortref sec="messageinfo"/> 233 </description> 234 <param dir="in" name="buffer" type="seL4_Word" 235 description="Location of the thread's IPC buffer. Must be 512-byte aligned. The IPC buffer may not cross a page boundary."/> 236 <param dir="in" name="bufferFrame" type="seL4_CPtr" 237 description="Capability to a page containing the thread's IPC buffer."/> 238 </method> 239 240 <method id="TCBSetSpace" name="SetSpace" manual_name="Set Space" manual_label="tcb_setspace" condition="!defined(CONFIG_KERNEL_MCS)"> 241 <brief> 242 Set the fault endpoint, CSpace and VSpace of a thread 243 </brief> 244 <description> 245 <docref>See <autoref label="sec:threads"/></docref> 246 </description> 247 <param dir="in" name="fault_ep" type="seL4_Word" 248 description="CPTR to the endpoint which receives IPCs when this thread faults. This capability is in the CSpace of the thread being configured."/> 249 <param dir="in" name="cspace_root" type="seL4_CNode" 250 description="The new CSpace root."/> 251 <param dir="in" name="cspace_root_data" type="seL4_Word" 252 description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/> 253 <param dir="in" name="vspace_root" type="seL4_CPtr" 254 description="The new VSpace root."/> 255 <param dir="in" name="vspace_root_data" type="seL4_Word" 256 description="Has no effect on x86 or ARM processors."/> 257 </method> 258 259 <method id="TCBSetSpace" name="SetSpace" manual_name="Set Space" manual_label="tcb_setspace_mcs" condition="defined(CONFIG_KERNEL_MCS)"> 260 <brief> 261 Set the fault endpoint, CSpace and VSpace of a thread 262 </brief> 263 <description> 264 <docref>See <autoref label="sec:threads"/></docref> 265 </description> 266 <param dir="in" name="fault_ep" type="seL4_CPtr" 267 description="CPTR to the endpoint which receives IPCs when this thread faults. On MCS this cap gets copied into the TCB."/> 268 <param dir="in" name="cspace_root" type="seL4_CNode" 269 description="The new CSpace root."/> 270 <param dir="in" name="cspace_root_data" type="seL4_Word" 271 description="Optionally set the guard and guard size of the new root CNode. If set to zero, this parameter has no effect."/> 272 <param dir="in" name="vspace_root" type="seL4_CPtr" 273 description="The new VSpace root."/> 274 <param dir="in" name="vspace_root_data" type="seL4_Word" 275 description="Has no effect on x86 or ARM processors."/> 276 </method> 277 278 <method id="TCBSuspend" name="Suspend" manual_name="Suspend" manual_label="tcb_suspend"> 279 <brief> 280 Suspend a thread 281 </brief> 282 <description> 283 <docref>See <autoref label="sec:thread_deactivation"/></docref> 284 </description> 285 </method> 286 287 <method id="TCBResume" name="Resume" manual_name="Resume" manual_label="tcb_resume"> 288 <brief> 289 Resume a thread 290 </brief> 291 <description> 292 <docref>See <autoref label="sec:thread_deactivation"/></docref> 293 </description> 294 </method> 295 296 <method id="TCBBindNotification" name="BindNotification" manual_name="Bind Notification" manual_label="tcb_bindnotification"> 297 <brief> 298 Binds a notification object to a <obj name="TCB"/> 299 </brief> 300 <description> 301 <docref>See <autoref label="sec:notification-binding"/></docref> 302 </description> 303 <param dir="in" name="notification" type="seL4_CPtr" description="Notification to bind."/> 304 </method> 305 306 <method id="TCBUnbindNotification" name="UnbindNotification" manual_name="Unbind Notification" manual_label="tcb_unbindnotification"> 307 <brief> 308 Unbinds any notification object from a <obj name="TCB"/> 309 </brief> 310 <description> 311 <docref>See <autoref label="sec:notification-binding"/></docref> 312 </description> 313 </method> 314 315 <method id="TCBSetAffinity" name="SetAffinity" condition="(!defined CONFIG_KERNEL_MCS) && CONFIG_MAX_NUM_NODES > 1" manual_name="Set CPU Affinity" manual_label="tcb_setaffinity"> 316 <brief> 317 Change a thread's current CPU in multicore machine 318 </brief> 319 <description> 320 <docref>See <autoref label="sec:thread_creation"/></docref> 321 </description> 322 <param dir="in" name="affinity" type="seL4_Word" 323 description="The thread's new CPU to run."/> 324 </method> 325 326 <method id="TCBSetBreakpoint" name="SetBreakpoint" condition="defined(CONFIG_HARDWARE_DEBUG_API)" manual_name="Set Breakpoint" manual_label="tcb_setbreakpoint"> 327 <brief> 328 Set or modify a thread's breakpoints or watchpoints. Calls to this function 329 overwrite previous configurations for the target breakpoint. Do not use this 330 with seL4_SingleStep: the API will reject the call and return an error. 331 Instead, use seL4_TCB_ConfigureSingleStepping to configure single-stepping. 332 </brief> 333 <description> 334 <docref>See <autoref label="sec:debug_exceptions"/></docref> 335 </description> 336 <param dir="in" name="bp_num" type="seL4_Uint16" 337 description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/> 338 <param dir="in" name="vaddr" type="seL4_Word" 339 description="A virtual address which forms part of the match conditions for the triggering of the breakpoint."/> 340 <param dir="in" name="type" type="seL4_Word" 341 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."/> 342 <param dir="in" name="size" type="seL4_Word" 343 description="A positive integer indicating the trigger-span of the watchpoint. Must be zero when 'type' is seL4_InstructionBreakpoint."/> 344 <param dir="in" name="rw" type="seL4_Word" 345 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."/> 346 </method> 347 348 <method id="TCBGetBreakpoint" name="GetBreakpoint" condition="defined(CONFIG_HARDWARE_DEBUG_API)" manual_name="Get Breakpoint" manual_label="tcb_getbreakpoint"> 349 <brief> 350 Read a breakpoint or watchpoint's current configuration. 351 </brief> 352 <description> 353 <docref>See <autoref label="sec:debug_exceptions"/></docref> 354 </description> 355 <return> 356 A <texttt text="seL4_TCB_GetBreakpoint_t"/>: Struct that contains 357 <texttt text="seL4_Error error"/>, an seL4 API error value, 358 <texttt text="seL4_Word vaddr"/>, the virtual address at which the breakpoint will currently 359 be triggered; 360 <texttt text="seL4_Word type"/>, the type of operation which will currently trigger the 361 breakpoint, whether instruction execution, or data access; 362 <texttt text="seL4_Word size"/>, integer value for the span-size of the breakpoint. 363 Usually a power of two (1, 2, 4, etc.); 364 <texttt text="seL4_Word rw"/>, the access direction that will currently trigger the breakpoint, 365 whether read, write, or both and 366 <texttt text="seL4_Bool is_enabled"/>, which indicates whether or not the breakpoint 367 will currently be triggered if the match conditions are met. 368 </return> 369 <param dir="in" name="bp_num" type="seL4_Uint16" 370 description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/> 371 <param dir="out" name="vaddr" type="seL4_Word"/> 372 <param dir="out" name="type" type="seL4_Word"/> 373 <param dir="out" name="size" type="seL4_Word"/> 374 <param dir="out" name="rw" type="seL4_Word"/> 375 <param dir="out" name="is_enabled" type="seL4_Bool"/> 376 </method> 377 378 <method id="TCBUnsetBreakpoint" name="UnsetBreakpoint" condition="defined(CONFIG_HARDWARE_DEBUG_API)" manual_name="Unset Breakpoint" manual_label="tcb_unsetbreakpoint"> 379 <brief> 380 Disables a hardware breakpoint or watchpoint. The caller should assume that 381 the underlying configuration of the hardware registers has also been cleared. 382 Do not use this to clear single-stepping: the API will reject the call and 383 return an error. Instead, use seL4_TCB_ConfigureSingleStepping to disable 384 single-stepping. 385 </brief> 386 <description> 387 <docref>See <autoref label="sec:debug_exceptions"/></docref> 388 </description> 389 <param dir="in" name="bp_num" type="seL4_Uint16" 390 description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/> 391 </method> 392 393 <method id="TCBConfigureSingleStepping" name="ConfigureSingleStepping" condition="defined(CONFIG_HARDWARE_DEBUG_API)" 394 manual_name="Configure Single Stepping" manual_label="tcb_configuresinglestepping"> 395 <brief> 396 Set or modify single stepping options for the target TCB. Subsequent calls to this 397 function overwrite previous configuration. Depending on your processor architecture, 398 this may or may not require the consumption of a hardware register. 399 </brief> 400 <description> 401 <docref>See Sections <shortref sec="single_stepping_debug_exception"/> and <shortref sec="debug_exceptions"/></docref> 402 </description> 403 <return> 404 A <texttt text="seL4_TCB_ConfigureSingleStepping_t"/>: Struct that contains 405 <texttt text="seL4_Error error"/>, an seL4 API error value, 406 <texttt text="seL4_Bool bp_was_consumed"/>, a boolean which indicates whether or not the <texttt text="bp_num"/> 407 breakpoint ID that was passed to the function, was consumed in the setup of the single-stepping 408 functionality: if this is <texttt text="true"/>, the caller should not attempt to re-use <texttt text="bp_num"/> 409 until it has disabled the single-stepping functionality via a subsequent call to 410 seL4_TCB_ConfigureSingleStepping with an <texttt text="num_instructions"/> argument of 0. 411 </return> 412 <param dir="in" name="bp_num" type="seL4_Uint16" 413 description="The API-ID of a target breakpoint. This ID will be a positive integer, with values ranging from 0 to seL4_NumHWBreakpoints - 1."/> 414 <param dir="in" name="num_instructions" type="seL4_Word" 415 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."/> 416 <param dir="out" name="bp_was_consumed" type="seL4_Bool"/> 417 </method> 418 419 <method id="TCBSetTLSBase" name="SetTLSBase" manual_name="Set TLS Base" manual_label="tcb_settlsbase"> 420 <brief> 421 Set the TLS base of the target TCB. This intended for use on architectures where the register 422 used for TLS can only be written to in privilidged mode 423 </brief> 424 <description> 425 </description> 426 <return> 427 </return> 428 <param dir="in" name="tls_base" type="seL4_Word" 429 description="The TLS base to set"/> 430 </method> 431 432 </interface> 433 434 <interface name="seL4_CNode" manual_name="CNode"> 435 <method id="CNodeRevoke" name="Revoke" manual_name="Revoke" manual_label="cnode_revoke"> 436 <brief> 437 Delete all child capabilities of a capability 438 </brief> 439 <description> 440 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 441 </description> 442 <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."/> 443 <param dir="in" name="index" type="seL4_Word" description="CPTR to the capability. Resolved from the root of the _service parameter."/> 444 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the capability being operated on."/> 445 </method> 446 447 <method id="CNodeDelete" name="Delete" manual_name="Delete" manual_label="cnode_delete"> 448 <brief> 449 Delete a capability 450 </brief> 451 <description> 452 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 453 </description> 454 <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."/> 455 <param dir="in" name="index" type="seL4_Word" description="CPTR to the capability. Resolved from the root of the _service parameter."/> 456 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the capability being operated on."/> 457 </method> 458 459 <method id="CNodeCancelBadgedSends" name="CancelBadgedSends" manual_name="Cancel Badged Sends" manual_label="cnode_cancelbadgedsends"> 460 <brief> 461 The cancel badged sends method is intend to allow for the reuse of badges by an 462 authority. When used with a badged endpoint capability it 463 will cancel any outstanding send operations for that endpoint and badge. 464 This operation has no effect on un-badged or other objects. 465 </brief> 466 <description> 467 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 468 </description> 469 <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."/> 470 <param dir="in" name="index" type="seL4_Word" description="CPTR to the capability. Resolved from the root of the _service parameter."/> 471 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the capability being operated on."/> 472 </method> 473 474 <method id="CNodeCopy" name="Copy" manual_name="Copy" manual_label="cnode_copy"> 475 <brief> 476 Copy a capability, setting its access rights whilst doing so 477 </brief> 478 <description> 479 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 480 </description> 481 <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."/> 482 <param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 483 <param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 484 <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."/> 485 <param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/> 486 <param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/> 487 <param dir="in" name="rights" type="seL4_CapRights_t"> 488 <description> 489 The rights inherited by the new capability.<docref>Possible values for this type are given in <autoref label="sec:cap_rights"/> .</docref> 490 </description> 491 </param> 492 </method> 493 494 <method id="CNodeMint" name="Mint" manual_name="Mint" manual_label="cnode_mint"> 495 <brief> 496 Copy a capability, setting its access rights and badge whilst doing so 497 </brief> 498 <description> 499 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 500 </description> 501 <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."/> 502 <param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 503 <param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 504 <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."/> 505 <param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/> 506 <param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/> 507 <param dir="in" name="rights" type="seL4_CapRights_t"> 508 <description> 509 The rights inherited by the new capability.<docref>Possible values for this type are given in <autoref label="sec:cap_rights"/> .</docref> 510 </description> 511 </param> 512 <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."/> 513 </method> 514 515 <method id="CNodeMove" name="Move" manual_name="Move" manual_label="cnode_move"> 516 <brief> 517 Move a capability 518 </brief> 519 <description> 520 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 521 </description> 522 <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."/> 523 <param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 524 <param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 525 <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."/> 526 <param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/> 527 <param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/> 528 </method> 529 530 <method id="CNodeMutate" name="Mutate" manual_name="Mutate" manual_label="cnode_mutate"> 531 <brief> 532 Move a capability, setting its badge in the process 533 </brief> 534 <description> 535 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 536 </description> 537 <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."/> 538 <param dir="in" name="dest_index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 539 <param dir="in" name="dest_depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 540 <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."/> 541 <param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved from the root of the source CSpace."/> 542 <param dir="in" name="src_depth" type="seL4_Uint8" description="Number of bits of src_index to resolve to find the source slot."/> 543 <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."/> 544 </method> 545 546 <method id="CNodeRotate" name="Rotate" manual_name="Rotate" manual_label="cnode_rotate"> 547 <brief> 548 Given 3 capability slots - a destination, pivot and source - move the capability in the 549 pivot slot to the destination slot and the capability in the source slot to the pivot slot 550 </brief> 551 <description> 552 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 553 </description> 554 <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."/> 555 <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."/> 556 <param dir="in" name="dest_depth" type="seL4_Uint8" description="Depth to resolve dest_index to."/> 557 <param dir="in" name="dest_badge" type="seL4_Word" description="The new capdata for the capability that ends up in the destination slot."/> 558 <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."/> 559 <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."/> 560 <param dir="in" name="pivot_depth" type="seL4_Uint8" description="Depth to resolve pivot_index to."/> 561 <param dir="in" name="pivot_badge" type="seL4_Word" description="The new capdata for the capability that ends up in the pivot slot."/> 562 <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."/> 563 <param dir="in" name="src_index" type="seL4_Word" description="CPTR to the source slot. Resolved relative to src_root."/> 564 <param dir="in" name="src_depth" type="seL4_Uint8" description="Depth to resolve src_index to."/> 565 </method> 566 567 <method id="CNodeSaveCaller" name="SaveCaller" manual_name="Save Caller" manual_label="cnode_savecaller" condition="!defined(CONFIG_KERNEL_MCS)"> 568 <brief> 569 Save the reply capability from the last time the thread was called in the given CSpace so that it can be invoked later 570 </brief> 571 <description> 572 <docref>See <autoref label="sec:cnode-ops"/>.</docref> 573 </description> 574 <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."/> 575 <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."/> 576 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of index to resolve to find the slot being targeted."/> 577 </method> 578 579 </interface> 580 581 <interface name="seL4_IRQControl" manual_name="IRQ Control" cap_description="An IRQControl capability. This gives you the authority to make this call."> 582 583 <method id="IRQIssueIRQHandler" name="Get" manual_name="Get" manual_label="irq_controlget"> 584 <brief> 585 Create an IRQ handler capability 586 </brief> 587 <description> 588 <docref>See <autoref label="sec:interrupts"/>.</docref> 589 </description> 590 <param dir="in" name="irq" type="seL4_Word" description="The IRQ that you want this capability to handle."/> 591 <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."/> 592 <param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 593 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 594 </method> 595 596 </interface> 597 598 <interface name="seL4_IRQHandler" manual_name="IRQ Handler" cap_description="The IRQ handler capability."> 599 600 <method id="IRQAckIRQ" name="Ack" manual_name="Acknowledge" manual_label="irq_handleracknowledge"> 601 <brief> 602 Acknowledge the receipt of an interrupt and re-enable it 603 </brief> 604 <description> 605 <docref>See <autoref label="sec:interrupts"/>.</docref> 606 </description> 607 </method> 608 609 <method id="IRQSetIRQHandler" name="SetNotification" manual_name="Set Notification" manual_label="irq_handlersetnotification"> 610 <brief> 611 Set the notification which the kernel will signal on interrupts 612 controlled by the supplied IRQ handler capability 613 </brief> 614 <description> 615 <docref>See <autoref label="sec:interrupts"/>.</docref> 616 </description> 617 <param dir="in" name="notification" type="seL4_CPtr" description="The notification which the IRQs will signal."/> 618 </method> 619 620 <method id="IRQClearIRQHandler" name="Clear" manual_name="Clear" manual_label="irq_handlerclear"> 621 <brief> 622 Clear the handler capability from the IRQ slot 623 </brief> 624 <description> 625 <docref>See <autoref label="sec:interrupts"/>.</docref> 626 </description> 627 </method> 628 629 </interface> 630 631 <interface name="seL4_DomainSet" manual_name="Domain Set" cap_description="Capability allowing domain configuration."> 632 633 <method id="DomainSetSet" name="Set" manual_name="Set" manual_label="domainset_set"> 634 <brief> 635 Change the domain of a thread. 636 </brief> 637 <description> 638 <docref>See <autoref label="sec:domains"/>.</docref> 639 </description> 640 <param dir="in" name="domain" type="seL4_Uint8" description="The thread's new domain."/> 641 <param dir="in" name="thread" type="seL4_TCB" description="Capability to the TCB which is being operated on."/> 642 </method> 643 </interface> 644 645 <interface name="seL4_SchedControl"> 646 647 <method id="SchedControlConfigure" name="Configure" manual_name="Configure" manual_label="schedcontrol_configure" condition="defined(CONFIG_KERNEL_MCS)"> 648 <brief> 649 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). 650 </brief> 651 <description> 652 See <autoref label="sec:threads"/> 653 </description> 654 <return><errorenumdesc/></return> 655 <param dir="in" name="schedcontext" type="seL4_SchedContext" 656 description="Capability to the scheduling context which is being operated on."/> 657 <param dir="in" name="budget" type="seL4_Time" 658 description="Timeslice in microseconds, when the budget expires the thread will be pre-empted."/> 659 <param dir="in" name="period" type="seL4_Time" 660 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."/> 661 <param dir="in" name="extra_refills" type="seL4_Word" 662 description="Number of extra sporadic replenishments this scheduling context should use. Ignored for round-robin threads."/> 663 <param dir="in" name="badge" type="seL4_Word" 664 description="Identifier for this scheduling context. Delivered to timeout exception handler. Can be used to determine which scheduling context triggered the timeout." /> 665 </method> 666 667 </interface> 668 669 <interface name="seL4_SchedContext"> 670 671 <method id="SchedContextBind" name="Bind" 672 manual_name="Bind" manual_label="schedcontext_bind" condition="defined(CONFIG_KERNEL_MCS)"> 673 <brief> 674 Bind an object to a scheduling context. The object can be a notification object or a 675 thread. 676 677 If the object is a thread and the thread is in a runnable state and the scheduling 678 context has available budget, this will start the thread running. 679 680 If the object is a notification, when passive threads wait on the notification object and 681 a signal arrives, the passive thread will receive the scheduling context and possess it 682 until it waits on the notification object again. 683 684 This operation will fail if the scheduling context is already bound to a thread or 685 notification object. 686 </brief> 687 <description> 688 See <autoref label="sec:threads"/> 689 </description> 690 <return><errorenumdesc/></return> 691 <param dir="in" name="cap" type="seL4_CPtr" 692 description="Capability to a TCB or a notification object"/> 693 </method> 694 695 <method id="SchedContextUnbind" name="Unbind" 696 manual_name="Unbind" manual_label="schedcontext_unbind" condition="defined(CONFIG_KERNEL_MCS)"> 697 <brief> 698 Unbind any objects (threads or notification objects) from a scheduling context. This 699 will render the bound thread passive, see Section 6.1.5. 700 </brief> 701 <description> 702 See <autoref label="sec:threads"/> 703 </description> 704 <return><errorenumdesc/></return> 705 </method> 706 707 <method id="SchedContextUnbindObject" name="UnbindObject" 708 manual_name="UnbindObject" manual_label="schedcontext_unbindobject" condition="defined(CONFIG_KERNEL_MCS)"> 709 <brief> 710 Unbind an object from a scheduling context. The object can be either a thread or a 711 notification. 712 713 If the thread being unbound is the thread that is bound to this scheduling context, 714 this will render the thread passive. However if the thread being 715 unbound received the scheduling context via scheduling context donation over IPC, 716 the scheduling context will be returned to the thread that it was originally bound to. 717 718 If the object is a notification and it is bound to the scheduling context, unbind it. 719 </brief> 720 <description> 721 See <autoref label="sec:passive"/> 722 </description> 723 <return><errorenumdesc/></return> 724 <param dir="in" name="cap" type="seL4_CPtr" 725 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."/> 726 </method> 727 <method id="SchedContextConsumed" name="Consumed" manual_name="Consumed" 728 manual_label="schedcontext_consumed" condition="defined(CONFIG_KERNEL_MCS)"> 729 <brief> 730 Return the amount of time used by this scheduling context since this function was last called or a timeout exception triggered. 731 </brief> 732 <description> 733 See <autoref label="sec:threads"/> 734 </description> 735 <return><errorenumdesc/></return> 736 <param dir="out" name="consumed" type="seL4_Time" 737 description="Amount consumed by this scheduling context."/> 738 739 </method> 740 <method id="SchedContextYieldTo" name="YieldTo" 741 manual_name="YieldTo" manual_label="schedcontext_yieldto" condition="defined(CONFIG_KERNEL_MCS)"> 742 <brief> 743 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. 744 If the caller is at an equal priority to the thread this will result in the thread being scheduled. 745 If the caller is at a higher priority the thread will not run until the threads priority is the highest priority in the system. 746 The caller must have a maximum control priority greater than or equal to the threads priority. 747 </brief> 748 <description> 749 TODO 750 </description> 751 <param dir="out" name="consumed" type="seL4_Time"/> 752 </method> 753 </interface> 754 755</api> 756