git.barrelfish.org Git - barrelfish/blob - 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 };