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
11interface 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};
192