1<?xml version="1.0" ?>
2<!--
3     Copyright 2020, Data61, CSIRO (ABN 41 687 119 230)
4     Copyright 2015, 2016 Hesham Almatary <heshamelmatary@gmail.com>
5
6     SPDX-License-Identifier: BSD-2-Clause
7-->
8
9<api name="ObjectApiRISCV" label_prefix="riscv_">
10
11    <struct name="seL4_UserContext">
12            <member name="pc"/>
13            <member name="ra"/>
14            <member name="sp"/>
15            <member name="gp"/>
16            <member name="s0"/>
17            <member name="s1"/>
18            <member name="s2"/>
19            <member name="s3"/>
20            <member name="s4"/>
21            <member name="s5"/>
22            <member name="s6"/>
23            <member name="s7"/>
24            <member name="s8"/>
25            <member name="s9"/>
26            <member name="s10"/>
27            <member name="s11"/>
28            <member name="a0"/>
29            <member name="a1"/>
30            <member name="a2"/>
31            <member name="a3"/>
32            <member name="a4"/>
33            <member name="a5"/>
34            <member name="a6"/>
35            <member name="a7"/>
36            <member name="t0"/>
37            <member name="t1"/>
38            <member name="t2"/>
39            <member name="t3"/>
40            <member name="t4"/>
41            <member name="t5"/>
42            <member name="t6"/>
43            <member name="tp"/>
44    </struct>
45    <interface name="seL4_RISCV_PageTable" manual_name="Page Table" cap_description="Capability to the page table to invoke.">
46        <method id="RISCVPageTableMap" name="Map" manual_label="pagetable_map">
47            <brief>
48                Map a page table at a specific virtual address.
49            </brief>
50            <description>
51                Starting from the VSpace, map the page table object at any unpopulated level for the provided virtual address. If all paging structures and mappings are present for this virtual address, return an seL4_DeleteFirst error.
52            </description>
53            <param dir="in" name="vspace" type="seL4_RISCV_PageTable">
54                <description>VSpace to map the lower-level page table into.</description>
55            </param>
56            <param dir="in" name="vaddr" type="seL4_Word">
57                <description>Virtual address at which to map the page table.</description>
58            </param>
59            <param dir="in" name="attr" type="seL4_RISCV_VMAttributes">
60            <description>
61                VM Attributes for the mapping. <docref>Possible values for this type are given
62                in <autoref label="ch:vspace"/>.</docref>
63            </description>
64            </param>
65            <error name="seL4_DeleteFirst">
66                <description>
67                    A page is mapped in <texttt text="vspace"/> at <texttt text="vaddr"/>.
68                    Or, all required page tables are already mapped in <texttt text="vspace"/> at <texttt text="vaddr"/>.
69                </description>
70            </error>
71            <error name="seL4_FailedLookup">
72                <description>
73                    The <texttt text="vspace"/> is not assigned to an ASID pool.
74                </description>
75            </error>
76            <error name="seL4_IllegalOperation">
77                <description>
78                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
79                </description>
80            </error>
81            <error name="seL4_InvalidArgument">
82                <description>
83                    The <texttt text="vaddr"/> is in the kernel virtual address range.
84                </description>
85            </error>
86            <error name="seL4_InvalidCapability">
87                <description>
88                    The <texttt text="_service"/> or <texttt text="vspace"/> is a CPtr to a capability of the wrong type.
89                    Or, <texttt text="vspace"/> is not assigned to an ASID pool.
90                    Or, <texttt text="_service"/> is already mapped in a VSpace.
91                </description>
92            </error>
93        </method>
94        <method id="RISCVPageTableUnmap" name="Unmap" manual_label="pagetable_unmap">
95            <brief>
96                Unmap a page table.
97            </brief>
98            <description>
99                <docref>See <autoref label="ch:vspace"/></docref>
100            </description>
101            <error name="seL4_IllegalOperation">
102                <description>
103                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
104                </description>
105            </error>
106            <error name="seL4_InvalidCapability">
107                <description>
108                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
109                </description>
110            </error>
111            <error name="seL4_RevokeFirst">
112                <description>
113                    The <texttt text="_service"/> is the root of a VSpace.
114                    Or, a copy of the <texttt text="_service"/> capability exists.
115                </description>
116            </error>
117        </method>
118    </interface>
119    <interface name="seL4_RISCV_Page" manual_name="Page" cap_description="Capability to the page to invoke.">
120        <method id="RISCVPageMap" name="Map">
121            <brief>
122                Map a page into a page table.
123            </brief>
124            <description>
125                Takes a VSpace, or top-level <texttt text="Page Table"/>,
126                capability as an argument and installs a reference
127                to the given <texttt text="Page"/> in the page table slot corresponding to the given address. If a page is already mapped at the same virtual address, update the mapping attributes.
128                If the required paging structures are not present
129                this operation will fail, returning a seL4_FailedLookup error.
130            </description>
131            <param dir="in" name="vspace" type="seL4_RISCV_PageTable">
132                <description>VSpace to map the page into.</description>
133            </param>
134            <param dir="in" name="vaddr" type="seL4_Word">
135                <description>Virtual address at which to map the page.</description>
136            </param>
137            <param dir="in" name="rights" type="seL4_CapRights_t">
138                <description>
139                    Rights for the mapping. <docref>Possible values for this type are given in <autoref label="sec:cap_rights"/>.</docref>
140                </description>
141            </param>
142            <param dir="in" name="attr" type="seL4_RISCV_VMAttributes">
143            <description>
144                VM Attributes for the mapping. <docref>Possible values for this type are given
145                in <autoref label="ch:vspace"/>.</docref>
146            </description>
147            </param>
148            <error name="seL4_AlignmentError">
149                <description>
150                    The <texttt text="vaddr"/> is not aligned to the page size of <texttt text="_service"/>.
151                </description>
152            </error>
153            <error name="seL4_DeleteFirst">
154                <description>
155                    A mapping already exists in <texttt text="vspace"/> at <texttt text="vaddr"/>.
156                </description>
157            </error>
158            <error name="seL4_FailedLookup">
159                <description>
160                    The <texttt text="vspace"/> does not have a paging structure at the required level mapped at <texttt text="vaddr"/>.
161                    Or, <texttt text="vspace"/> is not assigned to an ASID pool.
162                </description>
163            </error>
164            <error name="seL4_IllegalOperation">
165                <description>
166                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
167                </description>
168            </error>
169            <error name="seL4_InvalidArgument">
170                <description>
171                    The <texttt text="_service"/> is already mapped in <texttt text="vspace"/> at a different virtual address.
172                    Or, <texttt text="vaddr"/> is in the kernel virtual address range.
173                </description>
174            </error>
175            <error name="seL4_InvalidCapability">
176                <description>
177                    The <texttt text="_service"/> or <texttt text="vspace"/> is a CPtr to a capability of the wrong type.
178                    Or, <texttt text="vspace"/> is not the root of a VSpace.
179                    Or, <texttt text="vspace"/> is not assigned to an ASID pool.
180                    Or, <texttt text="_service"/> is already mapped in a different VSpace.
181                </description>
182            </error>
183        </method>
184        <method id="RISCVPageUnmap" name="Unmap">
185            <brief>
186               Unmap a page.
187            </brief>
188            <description>
189                Removes an existing mapping.
190            </description>
191            <error name="seL4_IllegalOperation">
192                <description>
193                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
194                </description>
195            </error>
196            <error name="seL4_InvalidCapability">
197                <description>
198                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
199                </description>
200            </error>
201        </method>
202        <method id="RISCVPageGetAddress" name="GetAddress">
203            <brief>
204                Get the physical address of a page.
205            </brief>
206            <description>
207                <docref>See <autoref label="ch:vspace"/>.</docref>
208            </description>
209            <return>
210                A <texttt text='seL4_RISCV_Page_GetAddress_t'/> struct that contains a
211                <texttt text='seL4_Word paddr'/>, which holds the physical address of the page,
212                and <texttt text='int error'/>. <docref>See <autoref label='sec:errors'/> for a description
213                of the message register and tag contents upon error.</docref>
214            </return>
215            <param dir="out" name="paddr" type="seL4_Word"/>
216            <error name="seL4_IllegalOperation">
217                <description>
218                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
219                </description>
220            </error>
221            <error name="seL4_InvalidCapability">
222                <description>
223                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
224                </description>
225            </error>
226        </method>
227    </interface>
228    <interface name="seL4_RISCV_ASIDControl" manual_name="ASID Control"
229        cap_description="The master ASIDControl capability to invoke.">
230        <method id="RISCVASIDControlMakePool" name="MakePool">
231           <brief>
232                Create an ASID Pool.
233            </brief>
234            <description>
235                Together with a capability to <texttt text="Untyped Memory"/>, which is passed as an argument,
236                create an <texttt text="ASID Pool"/>. The untyped capability must represent a
237                4K memory object. This will create an ASID pool with enough space for 1024 VSpaces.
238            </description>
239            <param dir="in" name="untyped" type="seL4_Untyped"
240            description="Capability to an untyped memory object that will become the pool. Must be 4K bytes."/>
241            <param dir="in" name="root" type="seL4_CNode"
242            description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth of 32."/>
243            <param dir="in" name="index" type="seL4_Word"
244            description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth of 32."/>
245            <param dir="in" name="depth" type="seL4_Uint8"
246            description="Number of bits of index to resolve to find the destination slot."/>
247            <error name="seL4_DeleteFirst">
248                <description>
249                    The destination slot contains a capability.
250                    Or, there are no more ASID pools available.
251                </description>
252            </error>
253            <error name="seL4_FailedLookup">
254                <description>
255                    The <texttt text="index"/> or <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
256                    Or, <texttt text="root"/> is a CPtr to a capability of the wrong type.
257                </description>
258            </error>
259            <error name="seL4_IllegalOperation">
260                <description>
261                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
262                </description>
263            </error>
264            <error name="seL4_InvalidCapability">
265                <description>
266                    The <texttt text="_service"/> or <texttt text="untyped"/> is a CPtr to a capability of the wrong type.
267                    Or, <texttt text="untyped"/> is not the exact size of an ASID pool object.
268                    Or, <texttt text="untyped"/> is a device untyped <docref>(see <autoref label="sec:kernmemalloc"/>)</docref>.
269                </description>
270            </error>
271            <error name="seL4_RangeError">
272                <description>
273                    The <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
274                </description>
275            </error>
276            <error name="seL4_RevokeFirst">
277                <description>
278                    The <texttt text="untyped"/> has been used to retype an object.
279                    Or, a copy of the <texttt text="untyped"/> capability exists.
280                </description>
281            </error>
282        </method>
283    </interface>
284    <interface name="seL4_RISCV_ASIDPool" manual_name="ASID Pool"
285        cap_description="The ASID Pool capability to invoke, which must be to an ASID pool that is not full.">
286        <method id="RISCVASIDPoolAssign" name="Assign">
287            <brief>
288                Assign an ASID Pool.
289            </brief>
290            <description>
291                Assigns an ASID to the VSpace passed in as an argument.
292            </description>
293            <param dir="in" name="vspace" type="seL4_CPtr">
294            <description>
295                The top-level <texttt text="PageTable" /> that is being assigned to an ASID pool. Must not already be assigned
296                    to an ASID pool.
297            </description>
298            </param>
299            <error name="seL4_DeleteFirst">
300                <description>
301                    There are no more ASIDs available in <texttt text="_service"/>.
302                </description>
303            </error>
304            <error name="seL4_IllegalOperation">
305                <description>
306                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
307                </description>
308            </error>
309            <error name="seL4_InvalidCapability">
310                <description>
311                    The <texttt text="_service"/> or <texttt text="vspace"/> is a CPtr to a capability of the wrong type.
312                    Or, <texttt text="vspace"/> is already assigned to an ASID pool.
313                    Or, <texttt text="vspace"/> is mapped in a VSpace.
314                </description>
315            </error>
316        </method>
317    </interface>
318    <interface name="seL4_IRQControl" manual_name="IRQ Control" cap_description="An IRQControl capability. This gives you the authority to make this call.">
319
320       <method id="RISCVIRQIssueIRQHandlerTrigger" name="GetTrigger" manual_name="GetTrigger"
321           manual_label="irq_controlgettrigger">
322            <brief>
323                Create an IRQ handler capability and specify the trigger method (edge or level).
324            </brief>
325            <description>
326                <docref>See <autoref label="sec:interrupts"/>.</docref>
327            </description>
328            <param dir="in" name="irq" type="seL4_Word" description="The IRQ that you want this capability to handle."/>
329
330            <param dir="in" name="trigger" type="seL4_Word" description="Indicates whether this IRQ is edge (1) or level (0) triggered."/>
331            <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."/>
332            <param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/>
333            <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/>
334            <error name="seL4_DeleteFirst">
335                <description>
336                    The destination slot contains a capability.
337                </description>
338            </error>
339            <error name="seL4_FailedLookup">
340                <description>
341                    The <texttt text="index"/> or <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
342                    Or, <texttt text="root"/> is a CPtr to a capability of the wrong type.
343                </description>
344            </error>
345            <error name="seL4_IllegalOperation">
346                <description>
347                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
348                    Or, the platform does not support setting the IRQ trigger.
349                </description>
350            </error>
351            <error name="seL4_InvalidCapability">
352                <description>
353                    The <texttt text="_service"/> is a CPtr to a capability of the wrong type.
354                </description>
355            </error>
356            <error name="seL4_RangeError">
357                <description>
358                    The <texttt text="irq"/> is invalid.
359                    Or, <texttt text="depth"/> is invalid <docref>(see <autoref label="s:cspace-addressing"/>)</docref>.
360                </description>
361            </error>
362            <error name="seL4_RevokeFirst">
363                <description>
364                    An IRQ handler capability for <texttt text="irq"/> has already been created.
365                </description>
366            </error>
367        </method>
368
369    </interface>
370
371</api>
372