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="ObjectApiArm" label_prefix="arm_"> 9 <interface name="seL4_ARM_PageTable" manual_name="Page Table" 10 cap_description="Capability to the page table being operated on."> 11 <method id="ARMPageTableMap" name="Map" manual_label="pagetable_map"> 12 <brief> 13 Map a page table into an address space. 14 </brief> 15 <description> 16 Takes a VSpace capability as an argument, 17 and installs a reference to the invoked 18 <texttt text='PageTable'/> in the VSpace according to the provided virtual address. 19 If higher-level paging structures do not exist for the virtual address 20 this operation will fail, returning a seL4_FailedLookup error. If the page table 21 is already mapped this operation will fail, returning a seL4_InvalidCapability error. If 22 another object is already mapped at this level for the virtual address 23 this operation will fail, returning a seL4_DeleteFirst error. 24 </description> 25 <param dir="in" name="vspace" type="seL4_CPtr" 26 description="Capability to the VSpace which will contain the mapping. 27 Must be assigned to an ASID pool."/> 28 <param dir="in" name="vaddr" type="seL4_Word" 29 description="Virtual address to map the page into."/> 30 <param dir="in" name="attr" type="seL4_ARM_VMAttributes"> 31 <description> 32 VM Attributes for the mapping. <docref>Possible values for this type are given in <autoref label="ch:vspace"/> .</docref> 33 </description> 34 </param> 35 </method> 36 <method id="ARMPageTableUnmap" name="Unmap" manual_label="pagetable_unmap"> 37 <brief> 38 Unmap a page table from its <texttt text="Page Directory"/> and zero it out. 39 </brief> 40 <description> 41 Removes the reference to the invoked <texttt text="Page Table"/> from its 42 containing <texttt text="Page Directory"/>. 43 </description> 44 </method> 45 </interface> 46 <interface name="seL4_ARM_IOPageTable" manual_name="I/O Page Table" 47 cap_description="Capability to the I/O page table being operated on."> 48 <method id="ARMIOPageTableMap" name="Map" condition="defined(CONFIG_TK1_SMMU)"> 49 <param dir="in" name="iospace" type="seL4_ARM_IOSpace"/> 50 <param dir="in" name="ioaddr" type="seL4_Word"/> 51 </method> 52 <method id="ARMIOPageTableUnmap" name="Unmap" condition="defined(CONFIG_TK1_SMMU)"> 53 </method> 54 </interface> 55 <interface name="seL4_ARM_Page" manual_name="Page" 56 cap_description="Capability to the page being operated on."> 57 <method id="ARMPageMap" name="Map"> 58 <brief> 59 Map a page into an address space or update the mapping attributes. 60 </brief> 61 <description> 62 Takes a VSpace capability, as an 63 argument and installs a reference 64 to the given <texttt text="Page"/> in the lowest-level unmapped paging structure 65 corresponding to the given address, or updates the mapping attributes if the page is 66 already mapped at this address. If the required paging structures are not present 67 this operation will fail, returning a seL4_FailedLookup error. The page must not 68 already be mapped through this capability in a different VSpace or at a different 69 address; the page may be mapped in multiple VSpaces by copying the capability. 70 </description> 71 <param dir="in" name="vspace" type="seL4_CPtr" 72 description="Capability to the VSpace which will contain the mapping. 73 Must be assigned to an ASID pool."/> 74 <param dir="in" name="vaddr" type="seL4_Word" 75 description="Virtual address to map the page into."/> 76 <param dir="in" name="rights" type="seL4_CapRights_t"> 77 <description> 78 Rights for the mapping.<docref>Possible values for this type are given in <autoref label="sec:cap_rights"/> .</docref> 79 </description> 80 </param> 81 <param dir="in" name="attr" type="seL4_ARM_VMAttributes"> 82 <description> 83 VM Attributes for the mapping.<docref>Possible values for this type are given in <autoref label="ch:vspace"/> .</docref> 84 </description> 85 </param> 86 </method> 87 <method id="ARMPageUnmap" name="Unmap"> 88 <brief> 89 Unmap a page. 90 </brief> 91 <description> 92 Removes an existing mapping. 93 </description> 94 </method> 95 <method id="ARMPageMapIO" name="MapIO" condition="defined(CONFIG_TK1_SMMU)" manual_name="Map I/O"> 96 <brief> 97 98 </brief> 99 <description> 100 101 </description> 102 <param dir="in" name="iospace" type="seL4_ARM_IOSpace"/> 103 <param dir="in" name="rights" type="seL4_CapRights_t"/> 104 <param dir="in" name="ioaddr" type="seL4_Word"/> 105 </method> 106 <method id="ARMPageClean_Data" name="Clean_Data" manual_name="Clean Data"> 107 <brief> 108 Cleans the data cache out to RAM. The start and end are relative to the page being serviced. 109 </brief> 110 <description> 111 <docref>See <autoref label="ch:vspace"/>.</docref> 112 </description> 113 <param dir="in" name="start_offset" type="seL4_Word" 114 description="The offset, relative to the start of the page inclusive."/> 115 <param dir="in" name="end_offset" type="seL4_Word" 116 description="The offset, relative to the start of the page exclusive."/> 117 </method> 118 <method id="ARMPageInvalidate_Data" name="Invalidate_Data" manual_name="Invalidate Data"> 119 <brief> 120 Invalidates the cache range within the given page. The start and end are relative to the page being serviced 121 and should be aligned to a cache line boundary where possible. 122 An additional clean is performed on the outer cache lines if the start and end are 123 not aligned, to clean out the bytes between the requested and the cache line boundary. 124 </brief> 125 <description> 126 <docref>See <autoref label="ch:vspace"/>.</docref> 127 </description> 128 <param dir="in" name="start_offset" type="seL4_Word" 129 description="The offset, relative to the start of the page inclusive."/> 130 <param dir="in" name="end_offset" type="seL4_Word" 131 description="The offset, relative to the start of the page exclusive."/> 132 </method> 133 <method id="ARMPageCleanInvalidate_Data" name="CleanInvalidate_Data" 134 manual_name="Clean and Invalidate Data"> 135 <brief> 136 Clean and invalidates the cache range within the given page. The range will be flushed out to RAM. 137 The start and end are relative to the page being serviced. 138 </brief> 139 <description> 140 <docref>See <autoref label="ch:vspace"/>.</docref> 141 </description> 142 <param dir="in" name="start_offset" type="seL4_Word" 143 description="The offset, relative to the start of the page inclusive."/> 144 <param dir="in" name="end_offset" type="seL4_Word" 145 description="The offset, relative to the start of the page exclusive."/> 146 </method> 147 <method id="ARMPageUnify_Instruction" name="Unify_Instruction" manual_name="Unify Instruction"> 148 <brief> 149 Unify Instruction Cache. Cleans data lines to point of unification, invalidate 150 corresponding instruction lines to point of unification, then invalidates branch 151 predictors. The start and end are relative to the page being 152 serviced. 153 </brief> 154 <description> 155 <docref>See <autoref label="ch:vspace"/>.</docref> 156 </description> 157 <param dir="in" name="start_offset" type="seL4_Word" 158 description="The offset, relative to the start of the page inclusive."/> 159 <param dir="in" name="end_offset" type="seL4_Word" 160 description="The offset, relative to the start of the page exclusive."/> 161 </method> 162 <method id="ARMPageGetAddress" name="GetAddress" manual_name="Get Address"> 163 <brief> 164 Get the physical address of the underlying frame. 165 </brief> 166 <description> 167 <docref>See <autoref label="ch:vspace"/>.</docref> 168 </description> 169 <return> 170 A <texttt text='seL4_ARM_Page_GetAddress_t'/> struct that contains a 171 <texttt text='seL4_Word paddr'/>, which holds the physical address of the page, 172 and <texttt text='int error'/>.<docref> See <autoref label='sec:errors'/> for a description 173 of the message register and tag contents upon error.</docref> 174 </return> 175 <param dir="out" name="paddr" type="seL4_Word"/> 176 </method> 177 </interface> 178 <interface name="seL4_ARM_ASIDControl" manual_name="ASID Control" 179 cap_description="The master ASIDControl capability being operated on."> 180 <method id="ARMASIDControlMakePool" name="MakePool" manual_name="Make Pool"> 181 <brief> 182 Create an ASID Pool. 183 </brief> 184 <description> 185 Together with a capability to <texttt text="Untyped Memory"/>, which is passed as an argument, 186 create an <texttt text="ASID Pool"/>. The untyped capability must represent a 187 4K memory object. This will create an ASID pool with enough space for 1024 VSpaces. 188 </description> 189 <param dir="in" name="untyped" type="seL4_Untyped" 190 description="Capability to an untyped memory object that will become the pool. Must be 4K bytes."/> 191 <param dir="in" name="root" type="seL4_CNode" 192 description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth equivalent to the wordsize."/> 193 <param dir="in" name="index" type="seL4_Word" 194 description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 195 <param dir="in" name="depth" type="seL4_Uint8" 196 description="Number of bits of index to resolve to find the destination slot."/> 197 </method> 198 </interface> 199 <interface name="seL4_ARM_ASIDPool" manual_name="ASID Pool" 200 cap_description="The ASID pool which is being assigned to. Must not be full. Each ASID pool can contain 1024 entries."> 201 <method id="ARMASIDPoolAssign" name="Assign" manual_label="asidpool_assign" 202 manual_name="Asid Pool Assign"> 203 <brief> 204 Assign an ASID Pool. 205 </brief> 206 <description> 207 Assigns an ASID to the VSpace passed in as an argument. 208 </description> 209 <param dir="in" name="vspace" type="seL4_CPtr" 210 description="The VSpace that is being assigned to an ASID pool. Must not already be assigned to an ASID pool."/> 211 </method> 212 </interface> 213 <interface name="seL4_ARM_VCPU" manual_name="VCPU" 214 cap_description="Capability to the VCPU being operated on."> 215 <method id="ARMVCPUSetTCB" name="SetTCB" condition="defined(CONFIG_ARM_HYPERVISOR_SUPPORT)" 216 manual_name="Set TCB"> 217 <brief> 218 Bind a TCB to a virtual CPU 219 </brief> 220 <description> 221 There is a 1:1 relationship between a virtual CPU and a TCB. If either (or both) of them is 222 associated with another one, they will be dissociated, and then associated to the 223 ones called in this system calls. 224 </description> 225 <param dir="in" name="tcb" type="seL4_TCB" 226 description="Capability to TCB to bind to a virtual CPU"/> 227 </method> 228 <method id="ARMVCPUInjectIRQ" name="InjectIRQ" condition="defined(CONFIG_ARM_HYPERVISOR_SUPPORT)" 229 manual_name="Inject IRQ"> 230 <brief> 231 Inject an IRQ to a virtual CPU 232 </brief> 233 <param dir="in" name="virq" type="seL4_Uint16" 234 description="Virtual IRQ ID"/> 235 <param dir="in" name="priority" type="seL4_Uint8" 236 description="Priority of the IRQ to be injected"/> 237 <param dir="in" name="group" type="seL4_Uint8" 238 description="IRQ group"/> 239 <param dir="in" name="index" type="seL4_Uint8" 240 description="IRQ index"/> 241 </method> 242 <method id="ARMVCPUReadReg" name="ReadRegs" condition="defined(CONFIG_ARM_HYPERVISOR_SUPPORT)" 243 manual_name="Read Registers"> 244 <brief> 245 Read a virtual CPU register 246 </brief> 247 <param dir="in" name="field" type="seL4_Word" 248 description="Register to read from a VCPU"/> 249 <param dir="out" name="value" type="seL4_Word" 250 description="Returned value of the VCPU register"/> 251 </method> 252 <method id="ARMVCPUWriteReg" name="WriteRegs" condition="defined(CONFIG_ARM_HYPERVISOR_SUPPORT)" 253 manual_name="Write Registers"> 254 <brief> 255 Write a virtual CPU register 256 </brief> 257 <param dir="in" name="field" type="seL4_Word" 258 description="Register ID to write to a VCPU"/> 259 <param dir="in" name="value" type="seL4_Word" 260 description="Value to be written to the VCPU register"/> 261 </method> 262 <method id="ARMVCPUAckVPPI" name="AckVPPI" condition="defined(CONFIG_ARM_HYPERVISOR_SUPPORT)" 263 manual_name="Acknowledge Virtual PPI IRQ"> 264 <brief> 265 Acknowledge a PPI IRQ previously forwarded from a VPPIEvent fault 266 </brief> 267 <description> 268 Acknowledge and unmask the PPI interrupt so that further interrupts can be forwarded 269 through VPPIEvent faults. 270 </description> 271 <param dir="in" name="irq" type="seL4_Word" 272 description="irq to ack."/> 273 274 </method> 275 </interface> 276 <interface name="seL4_IRQControl" manual_name="IRQ Control" cap_description="An IRQControl capability. This gives you the authority to make this call."> 277 278 <method id="ARMIRQIssueIRQHandlerTrigger" name="GetTrigger" manual_name="GetTrigger" 279 manual_label="irq_controlgettrigger"> 280 <brief> 281 Create an IRQ handler capability and specify the trigger method (edge or level). 282 </brief> 283 <description> 284 <docref>See <autoref label="sec:interrupts"/>.</docref> 285 </description> 286 <param dir="in" name="irq" type="seL4_Word" description="The IRQ that you want this capability to handle."/> 287 288 <param dir="in" name="trigger" type="seL4_Word" description="Indicates whether this IRQ is edge (1) or level (0) triggered."/> 289 <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."/> 290 <param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 291 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 292 </method> 293 294 <method id="ARMIRQIssueIRQHandlerTriggerCore" name="GetTriggerCore" manual_name="GetTriggerCore" 295 manual_label="irq_controlgettriggercore" condition="CONFIG_MAX_NUM_NODES > 1"> 296 <brief> 297 Create an IRQ handler capability and specify the trigger method (edge or level) and the target core. 298 </brief> 299 <description> 300 <docref>See <autoref label="sec:interrupts"/>.</docref> 301 </description> 302 <param dir="in" name="irq" type="seL4_Word" description="The IRQ that you want this capability to handle."/> 303 304 <param dir="in" name="trigger" type="seL4_Word" description="Indicates whether this IRQ is edge (1) or level (0) triggered."/> 305 <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."/> 306 <param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 307 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 308 <param dir="in" name="target" type="seL4_Word" description="Indicates the target core ID to which this irq will be sent."/> 309 </method> 310 </interface> 311 <interface name="seL4_ARM_SIDControl" manual_name="SID Control" cap_description="A SIDControl capability. This gives you the authority to make this call."> 312 <method id="ARMSIDIssueSIDManager" name="GetSID" manual_name="GetSID" 313 manual_label="sid_controlgetsid" condition="defined(CONFIG_ARM_SMMU)"> 314 <brief> 315 Create a SID capability. 316 </brief> 317 <description> 318 <docref>See <autoref label="sec:smmuv2-creating-sel4-arm-sid-capabilities"/>.</docref> 319 </description> 320 <param dir="in" name="sid" type="seL4_Word" description="The SID that you want this capability to manage."/> 321 <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."/> 322 <param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 323 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 324 </method> 325 <method id="ARMSIDGetFault" name="GetFault" manual_name="GetFault" 326 manual_label="sid_controlgetfault" condition="defined(CONFIG_ARM_SMMU)"> 327 <brief> 328 Get the fault status of the SMMU. 329 </brief> 330 <description> 331 <docref>See <autoref label="sec:smmuv2-fault-handling"/>.</docref> 332 </description> 333 <return> 334 A <texttt text='seL4_ARM_SMMU_GetFault_t'/> struct that contains a 335 <texttt text='seL4_Word status'/>, which holds the global fault status of the SMMU, 336 <texttt text='seL4_Word syndrome_0'/>, which holds the global fault syndrome 0 of the SMMU, 337 <texttt text='seL4_Word syndrome_1'/>, which holds the global fault syndrome 1 of the SMMU, 338 and <texttt text='int error'/>.<docref> See <autoref label='sec:errors'/> for a description 339 of the message register and tag contents upon error.</docref> 340 </return> 341 <param dir="out" name="status" type="seL4_Word"/> 342 <param dir="out" name="syndrome_0" type="seL4_Word"/> 343 <param dir="out" name="syndrome_1" type="seL4_Word"/> 344 </method> 345 <method id="ARMSIDClearFault" name="ClearFault" manual_name="ClearFault" 346 manual_label="sid_controlclearfault" condition="defined(CONFIG_ARM_SMMU)"> 347 <brief> 348 Clear the fault status of the SMMU. 349 </brief> 350 <description> 351 <docref>See <autoref label="sec:smmuv2-fault-handling"/>.</docref> 352 </description> 353 </method> 354 </interface> 355 <interface name="seL4_ARM_SID" manual_name="SID" cap_description="A SID capability. This gives you the authority to make this call."> 356 <method id="ARMSIDBindCB" name="BindCB" manual_name="BindCB" 357 manual_label="sid_bindcb" condition="defined(CONFIG_ARM_SMMU)"> 358 <brief> 359 Binding a context bank to a stream ID. 360 </brief> 361 <description> 362 <docref>See <autoref label="sec:smmuv2-configuring-streams-transactions"/>.</docref> 363 </description> 364 <param dir="in" name="cb" type="seL4_CPtr" 365 description="The CB that is being binded to a stream ID. Must already has an assigned vspace."/> 366 </method> 367 <method id="ARMSIDUnbindCB" name="UnbindCB" manual_name="UnbindCB" 368 manual_label="sid_unbindcb" condition="defined(CONFIG_ARM_SMMU)"> 369 <brief> 370 Unbinding a context bank from a stream ID. 371 </brief> 372 <description> 373 <docref>See <autoref label="sec:smmuv2-configuring-streams-transactions"/>.</docref> 374 </description> 375 </method> 376 </interface> 377 <interface name="seL4_ARM_CBControl" manual_name="CB Control" cap_description="A CBControl capability. This gives you the authority to make this call."> 378 <method id="ARMCBIssueCBManager" name="GetCB" manual_name="GetCB" 379 manual_label="cb_controlgetcb" condition="defined(CONFIG_ARM_SMMU)"> 380 <brief> 381 Create a CB capability. 382 </brief> 383 <description> 384 <docref>See <autoref label="sec:smmuv2-creating-sel4-arm-cb-capabilities"/>.</docref> 385 </description> 386 <param dir="in" name="cb" type="seL4_Word" description="The CB that you want this capability to manage."/> 387 <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."/> 388 <param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/> 389 <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/> 390 </method> 391 <method id="ARMCBTLBInvalidateAll" name="TLBInvalidateAll" manual_name="TLBInvalidateAll" 392 manual_label="cb_controltlbinvalidate" condition="defined(CONFIG_ARM_SMMU)"> 393 <brief> 394 Invalidate all TLB entries. 395 </brief> 396 <description> 397 <docref>See <autoref label="sec:smmuv2-tlb-invalidation"/>.</docref> 398 </description> 399 </method> 400 </interface> 401 <interface name="seL4_ARM_CB" manual_name="CB" cap_description="A CB capability. This gives you the authority to make this call."> 402 <method id="ARMCBAssignVspace" name="AssignVspace" manual_name="AssignVspace" 403 manual_label="cb_assignvspace" condition="defined(CONFIG_ARM_SMMU)"> 404 <brief> 405 Assigning a vspace to a context bank. 406 </brief> 407 <description> 408 <docref>See <autoref label="sec:smmuv2-configuring-context-banks"/>.</docref> 409 </description> 410 <param dir="in" name="vspace" type="seL4_CPtr" 411 description="The VSpace that is being assigned to a context bank. Must already has an assigned ASID."/> 412 </method> 413 <method id="ARMCBUnassignVspace" name="UnassignVspace" manual_name="UnassignVspace" 414 manual_label="cb_unassignvspace" condition="defined(CONFIG_ARM_SMMU)"> 415 <brief> 416 Unassigning a vspace to a context bank. 417 </brief> 418 <description> 419 <docref>See <autoref label="sec:smmuv2-configuring-context-banks"/>.</docref> 420 </description> 421 </method> 422 <method id="ARMCBTLBInvalidate" name="TLBInvalidate" manual_name="TLBInvalidate" 423 manual_label="cb_tlbinvalidate" condition="defined(CONFIG_ARM_SMMU)"> 424 <brief> 425 Invalidating TLB entries used by the current ASID in this context bank. 426 </brief> 427 <description> 428 <docref>See <autoref label="sec:smmuv2-tlb-invalidation"/>.</docref> 429 </description> 430 </method> 431 <method id="ARMCBGetFault" name="CBGetFault" manual_name="CBGetFault" 432 manual_label="cb_getfault" condition="defined(CONFIG_ARM_SMMU)"> 433 <brief> 434 Get the fault status of the context bank. 435 </brief> 436 <description> 437 <docref>See <autoref label="sec:smmuv2-fault-handling"/>.</docref> 438 </description> 439 <return> 440 A <texttt text='seL4_ARM_SMMU_CB_GetFault_t'/> struct that contains a 441 <texttt text='seL4_Word status'/>, which holds the fault status of the context bank, 442 <texttt text='seL4_Word address'/>, which holds the faulty address, 443 and <texttt text='int error'/>.<docref> See <autoref label='sec:errors'/> for a description 444 of the message register and tag contents upon error.</docref> 445 </return> 446 <param dir="out" name="status" type="seL4_Word"/> 447 <param dir="out" name="address" type="seL4_Word"/> 448 </method> 449 <method id="ARMCBClearFault" name="CBClearFault" manual_name="CBClearFault" 450 manual_label="cb_clearfault" condition="defined(CONFIG_ARM_SMMU)"> 451 <brief> 452 Clear the fault status of the context bank. 453 </brief> 454 <description> 455 <docref>See <autoref label="sec:smmuv2-fault-handling"/>.</docref> 456 </description> 457 </method> 458 </interface> 459</api> 460