git.barrelfish.org Git - barrelfish/blob - if/octopus.if

   1 /*
   2  * Copyright (c) 2007, 2008, 2009, 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, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
   8  */
   9
  10 interface octopus "octopus RPC Interface" {
  11
  12     alias mode uint64;
  13     alias trigger_id uint64;
  14     typedef enum {BINDING_RPC, BINDING_EVENT} binding_type;
  15
  16     // XXX: No flounder support for pointer values
  17     typedef struct {
  18         errval in_case;
  19         binding_type send_to;
  20         mode m;
  21         uint64 trigger;
  22         uint64 st;
  23     } trigger;
  24
  25     //
  26     // Binding Identification
  27     //
  28     rpc get_identifier(out uint64 id);
  29     rpc identify(in uint64 id, in binding_type type);
  30
  31
  32     //
  33     // Get/Set API
  34     //
  35
  36     /**
  37      * \param query Records to find.
  38      * \param t Additional trigger to watch for future events.
  39      * \param output Comma separated string of record names or NULL on error.
  40      * \param tid Id of registered trigger (0 in case no trigger registered).
  41      * \param error_code Error value of request.
  42      */
  43     rpc get_names(in string query, in trigger t, out string output, out trigger_id tid, out errval error_code);
  44
  45     /**
  46      * \param query Record to find.
  47      * \param t Additional trigger to watch for future events.
  48      * \param output Retrieved record or NULL on error.
  49      * \param tid Id of registered trigger (0 in case no trigger registered).
  50      * \param error_code Error value of request.
  51      */
  52     rpc get(in string query, in trigger t, out string output, out trigger_id tid, out errval error_code);
  53
  54     /**
  55      * \param query Record to set.
  56      * \param mode Set mode (see getset.h).
  57      * \param t Additional trigger to watch for future events.
  58      * \param get Return record if it has been set.
  59      * \param record In case get is true and no error_code is ok
  60      * contains record, otherwise NULL
  61      * \param tid Id of registered trigger (0 in case no trigger registered).
  62      * \param error_code Error value of request
  63      */
  64     rpc set(in string query, in uint64 mode, in trigger t, in bool get, out string record, out trigger_id tid, out errval error_code);
  65
  66     /**
  67      * \param query Record(s) to delete.
  68      * \param t Additional trigger to watch for future events.
  69      * \param tid Id of registered trigger (0 in case no trigger registered).
  70      * \param error_code Error value of request
  71      */
  72     rpc del(in string query, in trigger t, out trigger_id tid, out errval error_code);
  73
  74     /**
  75      * \param query
  76      * \param t Additional trigger to watch for future events.
  77      * \param tid Id of registered trigger (0 in case no trigger registered).
  78      * \param error_code Error value of request.
  79      */
  80     rpc exists(in string query, in trigger t, out trigger_id tid, out errval error_code);
  81
  82     /**
  83      * \brief Blocks until a record matching the provided query is registered.
  84      *
  85      * This was introduced specifically for the nameserver API
  86      * due to limitations of the memory allocation during bootstrapping we
  87      * can't use THC but need to support nameservice blocking lookup.
  88      * If you use this call you might want to consider using
  89      * a combination of get and triggers.
  90      *
  91      * \param query
  92      * \param record
  93      * \param error_code
  94      */
  95     rpc wait_for(in string query, out string record, out errval error_code);
  96
  97     /**
  98      * \brief Used to remove Triggers in case they are not needed anymore.
  99      *
 100      * Note that non persistent trigger are removed automatically after
 101      * they have fired. For persistent triggers be aware that you might
 102      * still get a notification after the trigger has been removed because
 103      * trigger events are sent over another binding.
 104      *
 105      * \param id Trigger ID to remove
 106      * \param error_code Error of operation
 107      */
 108     rpc remove_trigger(in uint64 id, out errval error_code);
 109
 110
 111     //
 112     // Publish/Subscribe API
 113     //
 114
 115     /**
 116      * \param query
 117      * \param client_state Additional state supplied by client.
 118      * \param id Identifier for this subscription supplied by server.
 119      * \param error_code Status of request.
 120      */
 121     rpc subscribe(in string query, in uint64 trigger_fn, in uint64 state, out uint64 id, out errval error_code);
 122
 123     /**
 124      * \param id Id for the subscription
 125      * \param error_code Status of request
 126      */
 127     rpc unsubscribe(in uint64 id, out errval error_code);
 128
 129     /**
 130      * \param record Message to publish.
 131      * \param error_code Status of request.
 132      */
 133     rpc publish(in string record, out errval error_code);
 134
 135
 136     //
 137     // Async events (sent by server to client)
 138     //
 139     message trigger(trigger_id id, uint64 trigger_fn, mode m, string record, uint64 state);
 140     message subscription(trigger_id id, uint64 trigger_fn, mode m, string record, uint64 state);
 141
 142
 143     //
 144     // Backward compability with chips
 145     //
 146
 147     // Simple capability storage
 148     rpc get_cap(in string key, out cap retcap, out errval reterr);
 149     rpc put_cap(in string key, in cap storecap, out errval reterr);
 150     rpc remove_cap(in string key, out errval reterr);
 151 };