octopus: skb queries increased buffer size
[barrelfish] / if / octopus.if
1 /*
2  * Copyright (c) 2007, 2008, 2009, 2012, ETH Zurich.
3  * All rights reserved.
4  *
5  * This file is distributed under the terms in the attached LICENSE file.
6  * If you do not find this file, copies can be found by writing to:
7  * ETH Zurich D-INFK, CAB F.78, Universitaetstr. 6, CH-8092 Zurich,
8  * Attn: Systems Group.
9  */
10
11 interface octopus "octopus RPC Interface" {
12
13     alias mode uint64;
14     alias trigger_id uint64;
15     typedef enum {BINDING_RPC, BINDING_EVENT} binding_type;
16
17     // XXX: No flounder support for pointer values
18     typedef struct {
19         errval in_case;
20         binding_type send_to;
21         mode m;
22         uint64 trigger;
23         uint64 st;
24     } trigger;
25
26     //
27     // Binding Identification
28     //
29     rpc get_identifier(out uint64 id);
30     rpc identify(in uint64 id, in binding_type type);
31
32
33     //
34     // Get/Set API
35     //
36
37     /**
38      * \param query Records to find.
39      * \param t Additional trigger to watch for future events.
40      * \param output Comma separated String of record names or NULL on error.
41      * \param tid Id of registered trigger (0 in case no trigger registered).
42      * \param error_code Error value of request.
43      */
44     rpc get_names(in String query[8192], in trigger t, out String output[8192],
45                   out trigger_id tid, out errval error_code);
46
47     /**
48      * \param query Record to find.
49      * \param t Additional trigger to watch for future events.
50      * \param output Retrieved record or NULL on error.
51      * \param tid Id of registered trigger (0 in case no trigger registered).
52      * \param error_code Error value of request.
53      */
54     rpc get(in String query[8192], in trigger t, out String output[8192],
55             out trigger_id tid, out errval error_code);
56
57     /**
58      * \param query Record to set.
59      * \param mode Set mode (see getset.h).
60      * \param t Additional trigger to watch for future events.
61      * \param get Return record if it has been set.
62      * \param record In case get is true and no error_code is ok
63      * contains record, otherwise NULL
64      * \param tid Id of registered trigger (0 in case no trigger registered).
65      * \param error_code Error value of request
66      */
67     rpc set(in String query[8192], in uint64 mode, in trigger t, in bool get,
68             out String record[8192], out trigger_id tid, out errval error_code);
69
70     /**
71      * Find a record using an ID capability as the key/name of the record.
72      *
73      * \param idcap ID capability used as the name of the record.
74      * \param t Additional trigger to watch for future events.
75      * \param output Retrieved record or NULL on error.
76      * \param tid Id of registered trigger (0 in case no trigger registered).
77      * \param error_code Error value of request.
78      */
79     rpc get_with_idcap(in cap idcap, in trigger t, out String output[8192],
80                        out trigger_id tid, out errval error_code);
81
82     /**
83      * Set a record using an ID capability as the key/name of the record.
84      *
85      * \param idcap ID capability used as the key/name of the record.
86      * \param attributes Attributes to store in the record.
87      * \param mode Set mode (see getset.h).
88      * \param t Additional trigger to watch for future events.
89      * \param get Return record if it has been set.
90      * \param record In case get is true and no error_code is ok
91      *               contains record, otherwise NULL
92      * \param tid Id of registered trigger (0 in case no trigger registered).
93      * \param error_code Error value of request
94      */
95     rpc set_with_idcap(in cap idcap, in String attributes[2048], in uint64 mode,
96                        in trigger t, in bool get, out String record[2048],
97                        out trigger_id tid, out errval error_code);
98
99     /**
100      * \param query Record(s) to delete.
101      * \param t Additional trigger to watch for future events.
102      * \param tid Id of registered trigger (0 in case no trigger registered).
103      * \param error_code Error value of request
104      */
105     rpc del(in String query[8192], in trigger t, out trigger_id tid,
106             out errval error_code);
107
108     /**
109      * \param query
110      * \param t Additional trigger to watch for future events.
111      * \param tid Id of registered trigger (0 in case no trigger registered).
112      * \param error_code Error value of request.
113      */
114     rpc exists(in String query[8192], in trigger t, out trigger_id tid,
115                out errval error_code);
116
117     /**
118      * \brief Blocks until a record matching the provided query is registered.
119      *
120      * This was introduced specifically for the nameserver API
121      * due to limitations of the memory allocation during bootstrapping we
122      * can't use THC but need to support nameservice blocking lookup.
123      * If you use this call you might want to consider using
124      * a combination of get and triggers.
125      *
126      * \param query
127      * \param record
128      * \param error_code
129      */
130     rpc wait_for(in String query[8192], out String record[2048], out errval error_code);
131
132     /**
133      * \brief Used to remove Triggers in case they are not needed anymore.
134      *
135      * Note that non persistent trigger are removed automatically after
136      * they have fired. For persistent triggers be aware that you might
137      * still get a notification after the trigger has been removed because
138      * trigger events are sent over another binding.
139      *
140      * \param id Trigger ID to remove
141      * \param error_code Error of operation
142      */
143     rpc remove_trigger(in uint64 id, out errval error_code);
144
145
146     //
147     // Publish/Subscribe API
148     //
149
150     /**
151      * \param query
152      * \param client_state Additional state supplied by client.
153      * \param id Identifier for this subscription supplied by server.
154      * \param error_code Status of request.
155      */
156     rpc subscribe(in String query[8192], in uint64 trigger_fn, in uint64 state,
157                   out uint64 id, out errval error_code);
158
159     /**
160      * \param id Id for the subscription
161      * \param error_code Status of request
162      */
163     rpc unsubscribe(in uint64 id, out errval error_code);
164
165     /**
166      * \param record Message to publish.
167      * \param error_code Status of request.
168      */
169     rpc publish(in String record[2048], out errval error_code);
170
171
172     //
173     // Async events (sent by server to client)
174     //
175     message trigger(trigger_id id, uint64 trigger_fn, mode m, String record[2048],
176                     uint64 state);
177
178     message subscription(trigger_id id, uint64 trigger_fn, mode m,
179                          String record[2048], uint64 state);
180
181
182     //
183     // Backward compability with chips
184     //
185
186     // Simple capability storage
187     rpc get_cap(in String key[256], out cap retcap, out errval reterr);
188     rpc put_cap(in String key[256], in cap storecap, out errval reterr);
189     rpc sput_cap(in String key[256], in cap storecap, out String retkey[256], out errval reterr);
190     rpc remove_cap(in String key[256], out errval reterr);
191 };