1<?xml version="1.0" ?>
2
3<!--
4     Copyright 2016, Data61
5     Commonwealth Scientific and Industrial Research Organisation (CSIRO)
6     ABN 41 687 119 230.
7
8     This software may be distributed and modified according to the terms of
9     the BSD 2-Clause license. Note that NO WARRANTY is provided.
10     See "LICENSE_BSD2.txt" for details.
11
12     @TAG(D61_BSD)
13  -->
14
15<interface label_min='PROCSERV_METHODS_BASE' connect_ep='REFOS_PROCSERV_EP'>
16    <include>refos/refos.h</include>
17 
18    <function name="proc_ping" return='refos_err_t'>
19        ! @brief Ping the process server. Useful for debugging.
20        @return ESUCCESS if success, refos_error error code otherwise.
21    </function>
22
23    <function name="proc_new_endpoint_internal" return='seL4_CPtr'>
24        ! @brief Create a new sync endpoint.
25
26        The client's vspace owns the created endpoint, and the EP will be deleted when the client
27        exits.
28
29        @param errno Variable to store error code in.
30        @return Recieved cap if success, 0 otherwise.
31
32        <param type="refos_err_t*" name="errno" dir="out"/>
33    </function>
34    
35    <function name="proc_new_async_endpoint_internal" return='seL4_CPtr'>
36        ! @brief Create a new asynchronous endpoint.
37
38        The client's vspace owns the created endpoint, and the EP will be deleted when the client
39        exits.
40
41        @param errno Variable to store error code in.
42        @return Recieved cap if success, 0 otherwise.
43
44        <param type="refos_err_t*" name="errno" dir="out"/>
45    </function>
46
47    <function name="proc_watch_client" return='refos_err_t'>
48        ! @brief Watch a client and set up to be notified of its death.
49        @param liveness The liveliness cap of the client.
50        @param deathEP The endpoint through which death notification will happen.
51        @param deathID The deathID which will be passed in the notification.
52        @return ESUCCESS if success, refos_error error code otherwise.
53
54        <param type="seL4_CPtr" name="liveness"/>
55        <param type="seL4_CPtr" name="deathEP"/>
56        <param type="int32_t*" name="deathID" dir="out"/>
57    </function>
58 
59    <function name="proc_unwatch_client" return='refos_err_t'>
60        ! @brief Stop watching a client and remove death notifications about it.
61
62        @param liveness The liveliness cap of the client.
63        @return ESUCCESS if success, refos_error error code otherwise.
64        
65        <param type="seL4_CPtr" name="liveness"/>
66    </function>
67
68    <function name="proc_create_mem_window_internal" return='seL4_CPtr'>
69        ! @brief Create a new memory window segment.
70
71        Likely to have implementation and/or technical restrictions regarding window base addrs and
72        mapped dataspaces. For the details, looking at the documentation for the implementation is
73        strongly recommended. On error, 0 is returned and errno is set.
74
75        @param vaddr The window base address in the calling client's VSpace.
76        @param size The size of the mem window.
77        @param permissions The read / write permission bitmask.
78        @param permissions The flags bitmask (cached / uncached).
79        @param errno The returned error number, if any errors.
80        @return Capability to created window if success, 0 otherwise (errno will be set).
81                (Gives ownership)
82
83        <param type="uint32_t" name="vaddr"/>
84        <param type="uint32_t" name="size"/>
85        <param type="uint32_t" name="permissions"/>
86        <param type="uint32_t" name="flags"/>
87        <param type="refos_err_t*" name="errno" dir="out"/>
88    </function>
89
90    <function name="proc_resize_mem_window" return='refos_err_t'>
91        ! @brief Resize a memory window segment.
92
93        @param window Capability of the window to resize. (No ownership)
94        @param size The new window size.
95        @return ESUCCESS if success, refos_error error code otherwise.
96
97        <param type="seL4_CPtr" name="window"/>
98        <param type="uint32_t" name="size"/>
99    </function>
100
101    <function name="proc_delete_mem_window" return='refos_err_t'>
102        ! @brief Delete a memory window segment.
103
104        @param window Capability of the window to delete. (Takes ownersip)
105        @return ESUCCESS if success, refos_error error code otherwise.
106
107        <param type="seL4_CPtr" name="window"/>
108    </function>
109
110    <function name="proc_get_mem_window" return='seL4_CPtr'>
111        ! @brief Get the memory window segment in calling client's own vspace at given addr.
112
113        @param vaddr The virtual memory address to get window for.
114        @return Capability to window at the given vaddr.  (Gives ownership)
115
116        <param type="uint32_t" name="vaddr"/>
117    </function>
118
119    <function name="proc_get_mem_window_dspace" return='seL4_CPtr'>
120        ! @brief Get the anonymous dataspace mapped at the given window.
121
122        Get the anonymous dataspace mapped at the given window. This function is very useful to
123        avoid some complex double-book-keeping scenarios.
124
125        @param window The window to get mapped dataspace for. (No ownership)
126        @param errno The returned error number, if any errors.
127        @return 0 if error or no dataspace mapped, capability to the mapped dataspace at the given
128                window otherwise. (Gives ownership)
129
130        <param type="seL4_CPtr" name="window"/>
131        <param type="refos_err_t*" name="errno" dir="out"/>
132    </function>
133
134    <function name="proc_register_as_pager" return='refos_err_t'>
135        ! @brief Register to be the pager for a client process's memory window.
136
137        @param window the memory window to page for.
138        @param faultNotifyEP The async endpoint which the fault notifications will be sent through.
139        @param winID The ID of the window, which will be used to identify which window faulted. The
140                     server most likely will have to book-keep this ID to handle faults correctly.
141        @return ESUCCESS if success, refos_error error code otherwise.
142
143        <param type="seL4_CPtr" name="window"/>
144        <param type="seL4_CPtr" name="faultNotifyEP"/>
145        <param type="seL4_Word*" name="winID" dir="out"/>
146    </function>
147
148    <function name="proc_unregister_as_pager" return='refos_err_t'>
149        ! @brief Unregister to stop being the pager for a client process's memory window.
150        @param window the memory window stop paging for.
151
152        <param type="seL4_CPtr" name="window"/>
153    </function>
154
155    <function name="proc_notification_buffer" return='refos_err_t'>
156        ! @brief Use the given RAM dataspace as the notification buffer.
157
158        The specific implementation of the process server may or may not support notification
159        buffers backed by internal and/or external dataspaces. Referring to the documentation for
160        the process server implementation is strongly recommended in order to find out what kind(s)
161        of dataspaces are supported.
162
163        @param dataspace The dataspace to use as the notification buffer.
164        @return ESUCCESS if success, refos_error error code otherwise.
165
166        <param type="seL4_CPtr" name="dataspace"/>
167    </function>
168
169    <function name="proc_window_map" return='refos_err_t'>
170        ! @brief Map a frame in the dataserver's own VSpace into the faulted window.
171
172        This syscall is most commonly used in response to a prior fault notification from the
173        process server. Maps the frame at the given VSpace into the client's faulted window, and
174        then resolves the fault and resumes execution of the faulting client. Also may be used to
175        eagerly map frames into clients before they VMfault there.
176
177        @param window Cap to the window to map the frame into.
178        @param windowOffset The offset into the window to map the frame into.
179        @param srcAddr The address of the source frame in the calling process's own VSpace;
180               this address should contain a valid frame, and should be page-aligned.
181        @return ESUCCESS if success, refos_error error code otherwise.
182
183        <param type="seL4_CPtr" name="window"/>
184        <param type="uint32_t" name="windowOffset"/>
185        <param type="uint32_t" name="srcAddr"/>
186    </function>
187
188    <function name="proc_window_unmap" return='refos_err_t'>
189    </function>
190
191    <function name="proc_window_getID" return='int'>
192        ! @brief Get the window ID associated with window capability.
193        @param window The window capability to retrieve window ID for.
194        @return -refos_err_t error on error, windowID value otherwise.
195
196        <param type="seL4_CPtr" name="window"/>
197    </function>
198
199    <function name="proc_set_parambuffer" return='refos_err_t'>
200        ! @brief Use the given dataspace as the parameter buffer for process server syscalls.
201
202        Whether internal and/or external dataspaces are supported for use as the parameter buffer is
203        implementation-specific. Referring to the documentation for the process server
204        implementation is strongly recommended in order to find out which type(s) of dataspaces are
205        supported.
206
207        @param dataspace The dataspace to use as the parameter buffer for subsequent procserv
208                         syscalls.
209        @param size The size of the param buffer.
210        @return ESUCCESS if success, refos_error error code otherwise.
211
212        <param type="seL4_CPtr" name="dataspace"/>
213        <param type="uint32_t" name="size"/>
214    </function>
215
216    <function name="proc_new_proc" return='refos_err_t'>
217        ! @brief Runs a new process. 
218
219        Starts a new process, blocking or non-blocking.
220    
221        @param name The executable file name of the process to start.
222        @param params The parameters to pass onto the new process.
223        @param block Whether to block until the process exits. (1/0) (non-blocking unimplemented)
224        @param priority The priority (0-255) of the new process.
225        @param status The exit status of the process. (output, only used if blocking is set)
226        @return ESUCCESS if success, refos_error error code otherwise.
227
228        <param type="char*" name="name"/>
229        <param type="char*" name="params"/>
230        <param type="bool" name="block"/>
231        <param type="int32_t" name="priority"/>
232        <param type="int32_t*" name="status" dir="out"/>
233    </function>
234
235    <function name="proc_exit" return='refos_err_t'>
236        ! @brief Exits and deletes the calling process.
237        @param status The exit status of the process.
238        @return doesn't return.
239        <param type="int32_t" name="status"/>
240    </function>
241
242    <function name="proc_clone_internal" return='int'>
243        ! @brief Clones a new thread for process.
244
245        Starts a new thread, sharing the current process' vspace. Each thread must have its own
246        entry point, stack and IPC buffer (the IPC buffer will be dynamically allocated). The child
247        thread will have the same priority as the parent process.
248
249        @param entryPoint The entry point vaddr of the new thread.
250        @param childStack The stack vaddr of the new thread.
251        @param flags Unused, must be 0.
252        @param arg Unused, must be 0.
253        @param errno The resulting refos_error error code, if an error occured.
254        @return threadID if success, negative if error occured.
255
256        <param type="seL4_Word" name="entryPoint"/>
257        <param type="seL4_Word" name="childStack"/>
258        <param type="int" name="flags"/>
259        <param type="seL4_Word" name="arg"/>
260        <param type="refos_err_t*" name="errno" dir="out"/>
261    </function>
262
263    <function name="proc_nice" return='refos_err_t'>
264        ! @brief Set the given thread's priority.
265
266        @param threadID The thread ID to set priority for.
267        @param priority The priority to set to.
268        @return ESUCCESS if success, refos_error error code otherwise.
269        
270        <param type="int" name="threadID"/>
271        <param type="int" name="priority"/>
272    </function>
273
274    <function name="proc_get_irq_handler" return='seL4_CPtr'>
275        ! @brief Get the IRQ handler endpoint for the given IRQ number. Requires IRQ handler
276                 permission.
277        @param irq The IRQ number to get handler for
278        @return IRQ handler endpoint on success, 0 otherwise.
279        <param type="int" name="irq"/>
280    </function>
281
282</interface>
283
284
285
286