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='DATASERV_METHODS_BASE' connect_ep='0'>
16    <include>refos/refos.h</include>
17    <include>refos/vmlayout.h</include>
18    <include>sys/types.h</include>
19
20    <function name="data_open" return='seL4_CPtr'>
21        ! @brief Opens a new dataspace at the dataspace server.
22
23        Opens a new dataspace at the dataspace server, which represents a series of bytes. Dataspace
24        mapping methods such as data_datamap() and data_init_data() directly or indirectly maps the
25        contents of this dataspace into a memory window, after which the contents can be read from /
26        written to. Alternatively, data_read() or data_write() may be used to read / write straight
27        into a dataspace. The concept of a dataspace in RefOS is similar to a file in UNIX; what
28        this dataspace represents depends on the server that is implementing this interface. See
29        \ref dataspace for more info.
30
31        Loosely based on the UNIX open() syscall.
32
33        @param session The client connection session to the dataspace server.  (No ownership)
34        @param name The name of the dataspace to open.
35        @param flags The read / write / create flags.
36        @param mode The mode to create new file with, in the case that a new one is created.
37        @param size The size of dataspace to open. Note that some data servers may ignore this.
38        @param errno Output errno variable, in the case that an error occurs. (No ownership)
39        @return Capability to the new dataspace. (Transfers ownership)
40
41        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
42        <param type="char*" name="name"/>
43        <param type="int" name="flags"/>
44        <param type="int" name="mode"/>
45        <param type="int" name="size"/>
46        <param type="int*" name="errno" dir='out'/>
47    </function>
48
49    <function name="data_close" return='refos_err_t'>
50        ! @brief Close a dataspace.
51
52        Close a dataspace that has previously been opened with data_open(), at the given dataspace
53        server. Based loosely on the UNIX close() syscall.
54
55        @param session The client connection session to the dataspace server.  (No ownership)
56        @param dspace_fd The dataspace to close.
57        @return ESUCCESS on success, refos_err_t error otherwise.
58
59        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
60        <param type="seL4_CPtr" name="dspace_fd"/>
61    </function>
62
63    <function name="data_read" return='int'>
64        ! @brief Read from a dataspace into a buffer.
65
66        Directly read from a dataspace. Note that the dataspace server may or may not support this.
67        Contents are transferred directly over IPC; so this method of reading is slow and can't send
68        more than what the IPC buffer can't handle. Based loosely on the UNIX read() syscall.
69
70        @param session The client connection session to the dataspace server.  (No ownership)
71        @param dspace_fd The dataspace to read from.
72        @param offset The offset into the dataspace to start reading from.
73        @param buf The buffer to read into.
74        @param count The length of the given buffer.
75        @return Number of bytes read if success, negative value if error.
76
77        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
78        <param type="seL4_CPtr" name="dspace_fd"/>
79        <param type="uint32_t" name="offset"/>
80        <param type="byte*" name="buf" mode="array" dir="out" lenvar="count"/>
81        <param type="uint32_t" name="count"/>
82    </function>
83
84    <function name="data_write" return='int'>
85        ! @brief Write to a dataspace.
86
87        Directly write to a dataspace from IPC buffer. This methods requires no setup, but is slow
88        and can't write more than what the IPC buffer can't store. Note that the dataspace server
89        may or may not support this. Based loosely on the UNIX write() syscall.
90
91        @param session The client connection session to the dataspace server.  (No ownership)
92        @param dspace_fd The dataspace to write to.
93        @param offset The offset into the dataspace to start writing to.
94        @param buf The buffer to write from.
95        @param count The length of the given buffer.
96        @return Number of bytes written if success, negative value if error.
97
98        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
99        <param type="seL4_CPtr" name="dspace_fd"/>
100        <param type="uint32_t" name="offset"/>
101        <param type="byte*" name="buf" mode="array" lenvar="count"/>
102        <param type="uint32_t" name="count"/>
103    </function>
104
105    <function name="data_getc" return='int'>
106        ! @brief Read the next character from a dataspace. Based loosely on the cstdlib fgetc().
107
108        @param session The client connection session to the dataspace server.  (No ownership)
109        @param dspace_fd The dataspace to read from.
110        @param block Whether to block.
111        @return The next character in dataspace. If block is enabled, then when there is no more
112                info to read, the data server blocks us until there is. Otherwise, -1 is returned.
113
114        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
115        <param type="seL4_CPtr" name="dspace_fd"/>
116        <param type="int" name="block"/>
117    </function>
118
119    <function name="data_putc" return='refos_err_t'>
120        ! @brief Writes the next character to a dataspace. Based loosely on the cstdlib fputc().
121
122        @param session The client connection session to the dataspace server.  (No ownership)
123        @param dspace_fd The dataspace to write to.
124        @param c The character value to write.
125        @return ESUCCESS if success, refos_err_t error otherwise.
126
127        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
128        <param type="seL4_CPtr" name="dspace_fd"/>
129        <param type="int" name="c"/>
130    </function>
131
132    <function name = "data_lseek" return = 'off_t'>
133        ! @brief Sets the current offset from beginning of file. Based loosely on the UNIX
134                 lseek() syscall.
135
136        @param session The client connection session to the dataspace server.  (No ownership)
137        @param dspace_fd The dataspace to lseek for.
138        @param offset The offset to lseek with. What this means depends on the whence parameter.
139        @param whence The whence parameter of lseek; simiular to the UNIX version:
140                      SEEK_SET will Directly set the offset to given offset in bytes,
141                      SEEK_CUR will set offset to current location plus offset bytes (ie. relative),
142                      SEEK_END will set the offset to the size of the file in bytes.
143        @return Resulting offset if success, negative value if error.
144
145        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
146        <param type="seL4_CPtr" name="dspace_fd"/>
147        <param type="off_t" name="offset" />
148        <param type="int" name="whence" />
149    </function>
150
151    <function name = "data_get_size" return = 'uint32_t'>
152        ! @brief Get the size of the dataspace.
153
154        This provides a shortcut alternative to abusing data_lseek() with SEEK_END to get the file
155        size of a dataspace. Note that some dataspaces may not support this, as sometimes the size
156        of a dataspaces makes no sense (eg. serial input).
157
158        @param session The client connection session to the dataspace server.  (No ownership)
159        @param dspace_fd The dataspace to get size for.
160        @return Dataspace size in bytes.
161
162        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
163        <param type="seL4_CPtr" name="dspace_fd"/>
164    </function>
165
166    <function name = "data_expand" return = 'refos_err_t'>
167        ! @brief Expand a given dataspace in size.
168
169        Resize and expand a given dataspace. Note that some dataspaces may not support this, as
170        sometimes the size of a dataspaces makes no sense (eg. serial input).
171
172        @param session The client connection session to the dataspace server. (No ownership)
173        @param dspace_fd The dataspace to expand.
174        @param size The new size to expand dataspace to. Must be larger or equal to the value
175                    returned by data_get_size().
176        @return ESUCCESS if success, refos_err_t error otherwise.
177
178        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
179        <param type="seL4_CPtr" name="dspace_fd"/>
180        <param type="uint32_t" name="size"/>
181    </function>
182
183    <function name = "data_datamap" return = 'refos_err_t'>
184        ! @brief Map the contents of the data to the given memory window.
185
186        Map the contents of the data to the given memory window, so that the contents of the
187        dataspace may be read by reading the window. Effectively sets the dataspace server up to be
188        the pager. Writing using this method is not implemented yet.
189               
190        @param session The established session cap to the dataspace server. (No ownership)
191        @param dataspace_fd The cap to the dataspace server's opened dataspace.
192        @param memoryWindow Cap to the memory window to map the dataspace contents into.
193        @param offset The offset in bytes from the beginning of the dataspace.
194        @return ESUCCESS if success, refos_error error code otherwise.
195
196        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
197        <param type="seL4_CPtr" name="dspace_fd"/>
198        <param type="seL4_CPtr" name="memoryWindow"/>
199        <param type="uint32_t" name="offset"/>
200    </function>
201
202    <function name = "data_dataunmap" return = 'refos_err_t'>
203        ! @brief Unmap the contents of the data from the given memory window.
204
205        @param session The client connection session to the dataspace server. (No ownership)
206        @param memoryWindow Capability to window to unmap dataspace from. (No ownership)
207        @return ESUCCESS if success, refos_error error code otherwise.
208
209        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
210        <param type="seL4_CPtr" name="memoryWindow"/>
211    </function>
212
213    <function name = "data_init_data" return = 'refos_err_t'>
214        ! @brief Initialises another dataspace by the contents of given dataspace.
215
216        Initialises another dataspace by the contents of a source dataspace. The source dataspace is
217        where the content is, and must originate from the invoked dataserver. Whether the
218        destination dataspace and the source dataspace coming from the same dataserver is supported
219        is up to the dataserver implementation; the dataserver documentation should be referred to.
220
221        @param session The established session cap to the dataspace server.
222        @param destDataspace Another dataspace to be initialised with content from the srcDataspace.
223        @param srcDataspace The dataserver's own dataspace, where the content is.
224        @param srcDataspaceOffset The content offset into the source dataspace.
225        @return ESUCCESS if success, refos_error error code otherwise.
226
227        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
228        <param type="seL4_CPtr" name="destDataspace"/>
229        <param type="seL4_CPtr" name="srcDataspace"/>
230        <param type="uint32_t" name="srcDataspaceOffset"/>
231    </function>
232
233    <function name = "data_have_data" return = 'refos_err_t'>
234        !@brief Tell another dataspace to content initialise its dataspace via this dataserver.
235
236        The local dataspace server calls another remote dataspace server to have the remote
237        dataspace initalised by the contents of the local dataspace.
238        
239        The local dataspace must book-keep the given dataID. The remote dataspace then will notify
240        through the given endpoint asking for content initialisation, the dataID being given in the
241        notification.
242               
243        @param session The established session cap to the remote dataspace server.
244        @param dspace_fd The cap to the remote dataspace to be initialised with content.
245        @param faultNotifyEP The async endpoint to ask for content initialisation with.
246        @param dataID The remote endpoint's unique data ID number, used for notification.
247        @return ESUCCESS if success, refos_error error code otherwise.
248
249        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
250        <param type="seL4_CPtr" name="dspace_fd"/>
251        <param type="seL4_CPtr" name="faultNotifyEP"/>
252        <param type="uint32_t*" name="dataID" dir='out'/>
253    </function>
254
255    <function name = "data_unhave_data" return = 'refos_err_t'>
256        !@brief Tell dataserver to stop providing content initialise data for its dataspace.
257               
258        @param session The established session cap to the remote dataspace server.
259        @param dspace_fd The cap to the remote dataspace to be initialised with content.
260        @return ESUCCESS if success, refos_error error code otherwise.
261
262        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
263        <param type="seL4_CPtr" name="dspace_fd"/>
264    </function>
265
266    <function name = "data_provide_data_from_parambuffer" return = 'refos_err_t'>
267        !@brief Reply to content initialisation notification with the data.
268
269        Gives the content from the local dataserver to the remote dataserver, in response to the
270        remote server's earlier notification asking for content. The content is assumed to be in
271        the set up parameter buffer. This call implicitly requires a parameter buffer to be
272        set up, and will return ENOPARAMBUFFER if one has not been set up. 
273        
274        Note that even though the notification from the dataserver asking for content uses dataID to
275        identify which dataspace, the reply, for security reasons, gives the actual dataspace cap.
276        The dataID may be used securely iff the dataserver implementation supports per-client dataID
277        checking, and a version of this method with dataID instead of a cap may be added.
278               
279        @param session The established session cap to the remote dataspace server.
280        @param dspace_fd The cap to the remote dataspace to provide the content for.
281        @param offset The offset into the remote dataspace to provide content for.
282        @param contentSize The size of the content. (May have maximum content size.)
283        @return ESUCCESS if success, refos_error error code otherwise.
284
285        <param type="seL4_CPtr" name="session" mode="connect_ep"/>
286        <param type="seL4_CPtr" name="dspace_fd"/>
287        <param type="uint32_t" name="offset"/>
288        <param type="uint32_t" name="contentSize"/>
289    </function>
290
291</interface>
292