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