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        </method>
66        <method id="RISCVPageTableUnmap" name="Unmap" manual_label="pagetable_unmap">
67            <brief>
68                Unmap a page table.
69            </brief>
70            <description>
71                <docref>See <autoref label="ch:vspace"/></docref>
72            </description>
73        </method>
74    </interface>
75    <interface name="seL4_RISCV_Page" manual_name="Page" cap_description="Capability to the page to invoke.">
76        <method id="RISCVPageMap" name="Map">
77            <brief>
78                Map a page into a page table.
79            </brief>
80            <description>
81                Takes a VSpace, or top-level <texttt text="Page Table"/>,
82                capability as an argument and installs a reference
83                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.
84                If the required paging structures are not present
85                this operation will fail, returning a seL4_FailedLookup error.
86            </description>
87            <param dir="in" name="vspace" type="seL4_RISCV_PageTable">
88                <description>VSpace to map the page into.</description>
89            </param>
90            <param dir="in" name="vaddr" type="seL4_Word">
91                <description>Virtual address at which to map the page.</description>
92            </param>
93            <param dir="in" name="rights" type="seL4_CapRights_t">
94                <description>
95                    Rights for the mapping. <docref>Possible values for this type are given in <autoref label="sec:cap_rights"/>.</docref>
96                </description>
97            </param>
98            <param dir="in" name="attr" type="seL4_RISCV_VMAttributes">
99            <description>
100                VM Attributes for the mapping. <docref>Possible values for this type are given
101                in <autoref label="ch:vspace"/>.</docref>
102            </description>
103            </param>
104        </method>
105        <method id="RISCVPageUnmap" name="Unmap">
106            <brief>
107               Unmap a page.
108            </brief>
109            <description>
110                Removes an existing mapping.
111            </description>
112        </method>
113        <method id="RISCVPageGetAddress" name="GetAddress">
114            <brief>
115                Get the physical address of a page.
116            </brief>
117            <description>
118                <docref>See <autoref label="ch:vspace"/>.</docref>
119            </description>
120            <return>
121                A <texttt text='seL4_RISCV_Page_GetAddress_t'/> struct that contains a
122                <texttt text='seL4_Word paddr'/>, which holds the physical address of the page,
123                and <texttt text='int error'/>. <docref>See <autoref label='sec:errors'/> for a description
124                of the message register and tag contents upon error.</docref>
125            </return>
126            <param dir="out" name="paddr" type="seL4_Word"/>
127        </method>
128    </interface>
129    <interface name="seL4_RISCV_ASIDControl" manual_name="ASID Control"
130        cap_description="The master ASIDControl capability to invoke.">
131        <method id="RISCVASIDControlMakePool" name="MakePool">
132           <brief>
133                Create an ASID Pool.
134            </brief>
135            <description>
136                Together with a capability to <texttt text="Untyped Memory"/>, which is passed as an argument,
137                create an <texttt text="ASID Pool"/>. The untyped capability must represent a
138                4K memory object. This will create an ASID pool with enough space for 1024 VSpaces.
139            </description>
140            <param dir="in" name="untyped" type="seL4_Untyped"
141            description="Capability to an untyped memory object that will become the pool. Must be 4K bytes."/>
142            <param dir="in" name="root" type="seL4_CNode"
143            description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth of 32."/>
144            <param dir="in" name="index" type="seL4_Word"
145            description="CPTR to the CNode that forms the root of the destination CSpace. Must be at a depth of 32."/>
146            <param dir="in" name="depth" type="seL4_Uint8"
147            description="Number of bits of index to resolve to find the destination slot."/>
148        </method>
149    </interface>
150    <interface name="seL4_RISCV_ASIDPool" manual_name="ASID Pool"
151        cap_description="The ASID Pool capability to invoke, which must be to an ASID pool that is not full.">
152        <method id="RISCVASIDPoolAssign" name="Assign">
153            <brief>
154                Assign an ASID Pool.
155            </brief>
156            <description>
157                Assigns an ASID to the VSpace passed in as an argument.
158            </description>
159            <param dir="in" name="vspace" type="seL4_CPtr">
160            <description>
161                The top-level <texttt text="PageTable" /> that is being assigned to an ASID pool. Must not already be assigned
162                    to an ASID pool.
163            </description>
164            </param>
165        </method>
166    </interface>
167    <interface name="seL4_IRQControl" manual_name="IRQ Control" cap_description="An IRQControl capability. This gives you the authority to make this call.">
168
169       <method id="RISCVIRQIssueIRQHandlerTrigger" name="GetTrigger" manual_name="GetTrigger"
170           manual_label="irq_controlgettrigger">
171            <brief>
172                Create an IRQ handler capability and specify the trigger method (edge or level).
173            </brief>
174            <description>
175                <docref>See <autoref label="sec:interrupts"/>.</docref>
176            </description>
177            <param dir="in" name="irq" type="seL4_Word" description="The IRQ that you want this capability to handle."/>
178
179            <param dir="in" name="trigger" type="seL4_Word" description="Indicates whether this IRQ is edge (1) or level (0) triggered."/>
180            <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."/>
181            <param dir="in" name="index" type="seL4_Word" description="CPTR to the destination slot. Resolved from the root of the destination CSpace."/>
182            <param dir="in" name="depth" type="seL4_Uint8" description="Number of bits of dest_index to resolve to find the destination slot."/>
183        </method>
184
185    </interface>
186
187</api>
188