src/native_client/src/trusted/reverse_service/reverse_service_c.h

   1 /*
   2  * Copyright (c) 2012 The Native Client Authors. All rights reserved.
   3  * Use of this source code is governed by a BSD-style license that can be
   4  * found in the LICENSE file.
   5  */
   6
   7 #ifndef NATIVE_CLIENT_SRC_TRUSTED_REVERSE_SERVICE_REVERSE_SERVICE_C_H_
   8 #define NATIVE_CLIENT_SRC_TRUSTED_REVERSE_SERVICE_REVERSE_SERVICE_C_H_
   9
  10 #include "native_client/src/include/nacl_base.h"
  11 #include "native_client/src/include/portability.h"
  12
  13 #include "native_client/src/trusted/desc/nacl_desc_base.h"
  14
  15 #include "native_client/src/trusted/nacl_base/nacl_refcount.h"
  16 #include "native_client/src/trusted/threading/nacl_thread_interface.h"
  17
  18 #include "native_client/src/trusted/simple_service/nacl_simple_rservice.h"
  19
  20 EXTERN_C_BEGIN
  21
  22 struct NaClFileInfo;
  23 struct NaClReverseInterface;
  24 struct NaClReverseInterfaceVtbl;
  25
  26 struct NaClReverseService {
  27   struct NaClSimpleRevService base NACL_IS_REFCOUNT_SUBCLASS;
  28
  29   struct NaClReverseInterface *iface;
  30
  31   struct NaClMutex            mu;
  32   struct NaClCondVar          cv;
  33   /*
  34    * |mu| protects the thread count access.
  35    */
  36   uint32_t                    thread_count;
  37 };
  38
  39 int NaClReverseServiceCtor(struct NaClReverseService   *self,
  40                            struct NaClReverseInterface *iface,
  41                            struct NaClDesc             *conn_cap);
  42
  43 void NaClReverseServiceDtor(struct NaClRefCount *vself);
  44
  45 struct NaClReverseServiceVtbl {
  46   struct NaClSimpleRevServiceVtbl vbase;
  47
  48   int                             (*Start)(
  49       struct NaClReverseService   *self,
  50       int                         crash_report);
  51
  52   void                            (*WaitForServiceThreadsToExit)(
  53       struct NaClReverseService   *self);
  54
  55   void                            (*ThreadCountIncr)(
  56       struct NaClReverseService   *self);
  57
  58   void                            (*ThreadCountDecr)(
  59       struct NaClReverseService   *self);
  60 };
  61
  62 int NaClReverseServiceStart(
  63     struct NaClReverseService *self,
  64     int                       crash_report);
  65
  66 void NaClReverseServiceWaitForServiceThreadsToExit(
  67     struct NaClReverseService *self);
  68
  69 void NaClReverseServiceThreadCountIncr(
  70     struct NaClReverseService *self);
  71
  72 void NaClReverseServiceThreadCountDecr(
  73     struct NaClReverseService *self);
  74
  75 extern struct NaClReverseServiceVtbl const kNaClReverseServiceVtbl;
  76
  77 struct NaClReverseInterface {
  78   struct NaClRefCount base NACL_IS_REFCOUNT_SUBCLASS;
  79 };
  80
  81 struct NaClReverseInterfaceVtbl {
  82   struct NaClRefCountVtbl       vbase;
  83
  84   /* Startup handshake */
  85   void                          (*StartupInitializationComplete)(
  86       struct NaClReverseInterface   *self);
  87
  88   /*
  89    * Name service use.
  90    *
  91    * Some of these functions require that the actual operation be done
  92    * in a different thread, so that the implementation of the
  93    * interface will have to block the requesting thread.  However, on
  94    * surf away, the thread switch may get cancelled, and the
  95    * implementation will have to reply with a failure indication.
  96    *
  97    * The bool functions returns false if the service thread unblocked
  98    * because of surf-away, shutdown, or other issues.  The plugin,
  99    * when it tells sel_ldr to shut down, will also signal all threads
 100    * that are waiting for main thread callbacks to wake up and abandon
 101    * their vigil after the callbacks are all cancelled (by abandoning
 102    * the WeakRefAnchor or by bombing their CompletionCallbackFactory).
 103    * Since shutdown/surfaway is the only admissible error, we use bool
 104    * as the return type.
 105    */
 106
 107   /*
 108    * Stores the manifest keys into the |buffer| of size |nbytes|.
 109    * Returns the number of bytes copied if successful, otherwise
 110    * returns the size required if |buffer| is not large enough.
 111    */
 112   size_t                        (*EnumerateManifestKeys)(
 113       struct NaClReverseInterface   *self,
 114       char                          *buffer,
 115       size_t                        buffer_bytes);
 116
 117   /*
 118    * Opens manifest entry specified by |url_key|. Returns 1 if
 119    * successful and stores the file descriptor in |out_desc|, otherwise
 120    * returns 0.
 121    */
 122   int                           (*OpenManifestEntry)(
 123       struct NaClReverseInterface   *self,
 124       char const                    *url_key,
 125       struct NaClFileInfo           *info);
 126
 127   /*
 128    * Closes manifest entry with file descriptor |desc|. Returns 1 if
 129    * successful, 0 otherwise.
 130    */
 131   int                           (*CloseManifestEntry)(
 132       struct NaClReverseInterface   *self,
 133       int32_t                       desc);
 134
 135   /*
 136    * Reports the client crash.
 137    */
 138   void                          (*ReportCrash)(
 139       struct NaClReverseInterface   *self);
 140
 141   /*
 142    * The low-order 8 bits of the |exit_status| should be reported to
 143    * any interested parties.
 144    */
 145   void                          (*ReportExitStatus)(
 146       struct NaClReverseInterface   *self,
 147       int                           exit_status);
 148
 149   /*
 150    * Standard output and standard error redirection, via setting
 151    * NACL_EXE_STDOUT to the string "DEBUG_ONLY:dev://postmessage" (see
 152    * native_client/src/trusted/nacl_resource.* and sel_ldr).  NB: the
 153    * contents of |message| is arbitrary bytes and not an Unicode
 154    * string, so the implementation should take care to handle this
 155    * appropriately.
 156    */
 157   void                          (*DoPostMessage)(
 158       struct NaClReverseInterface   *self,
 159       char const                    *message,
 160       size_t                        message_bytes);
 161
 162   /*
 163    * Create new service runtime process and return secure command
 164    * channel and untrusted application channel socket addresses. Returns
 165    * 0 if successful or negative ABI error value otherwise (see
 166    * service_runtime/include/sys/errno.h).  DEPRECATED.
 167    */
 168   int                           (*CreateProcess)(
 169       struct NaClReverseInterface  *self,
 170       struct NaClDesc              **out_sock_addr,
 171       struct NaClDesc              **out_app_addr);
 172
 173   /*
 174    * Create new service runtime process and return secure command
 175    * channel, untrusted application channel socket addresses, and pid
 176    * via a result delivery functor.  Returns negated ABI errno value
 177    * in pid if there were errors (see the header file
 178    * service_runtime/include/sys/errno.h).  The |out_pid_or_errno|
 179    * functor argument is also used to allow the "init" process to
 180    * inform the embedding environment, via FinalizeProcess, that it is
 181    * okay to finalize any resources associated with the identified
 182    * subprocess when the subprocess has exited.
 183    */
 184   void                          (*CreateProcessFunctorResult)(
 185       struct NaClReverseInterface *self,
 186       void (*result_functor)(void *functor_state,
 187                              struct NaClDesc *out_sock_addr,
 188                              struct NaClDesc *out_app_addr,
 189                              int32_t out_pid_or_errno),
 190       void *functor_state);
 191
 192   void                          (*FinalizeProcess)(
 193       struct NaClReverseInterface *self,
 194       int32_t pid);
 195
 196   /*
 197    * Quota checking for files that were sent to the untrusted module.
 198    * TODO(sehr): remove the stub interface once the plugin provides one.
 199    */
 200   int64_t                       (*RequestQuotaForWrite)(
 201       struct NaClReverseInterface   *self,
 202       char const                    *file_id,
 203       int64_t                       offset,
 204       int64_t                       length);
 205 };
 206
 207 /*
 208  * The protected Ctor is intended for use by subclasses of
 209  * NaClReverseInterface.
 210  */
 211 int NaClReverseInterfaceCtor_protected(
 212     struct NaClReverseInterface   *self);
 213
 214 void NaClReverseInterfaceDtor(struct NaClRefCount *vself);
 215
 216 void NaClReverseInterfaceLog(
 217     struct NaClReverseInterface   *self,
 218     char const                    *message);
 219
 220 void NaClReverseInterfaceStartupInitializationComplete(
 221     struct NaClReverseInterface   *self);
 222
 223 size_t NaClReverseInterfaceEnumerateManifestKeys(
 224     struct NaClReverseInterface   *self,
 225     char                          *buffer,
 226     size_t                        buffer_bytes);
 227
 228 int NaClReverseInterfaceOpenManifestEntry(
 229     struct NaClReverseInterface   *self,
 230     char const                    *url_key,
 231     struct NaClFileInfo           *info);
 232
 233 int NaClReverseInterfaceCloseManifestEntry(
 234     struct NaClReverseInterface   *self,
 235     int32_t                       desc);
 236
 237 void NaClReverseInterfaceReportCrash(
 238     struct NaClReverseInterface   *self);
 239
 240 void NaClReverseInterfaceReportExitStatus(
 241     struct NaClReverseInterface   *self,
 242     int                           exit_status);
 243
 244 void NaClReverseInterfaceDoPostMessage(
 245     struct NaClReverseInterface   *self,
 246     char const                    *message,
 247     size_t                        message_bytes);
 248
 249 void NaClReverseInterfaceCreateProcessFunctorResult(
 250     struct NaClReverseInterface *self,
 251     void (*result_functor)(void *functor_state,
 252                            struct NaClDesc *out_sock_addr,
 253                            struct NaClDesc *out_app_addr,
 254                            int32_t out_pid_or_errno),
 255     void *functor_state);
 256
 257 void NaClReverseInterfaceFinalizeProcess(struct NaClReverseInterface *self,
 258                                          int32_t pid);
 259
 260 int NaClReverseInterfaceCreateProcess(
 261     struct NaClReverseInterface   *self,
 262     struct NaClDesc               **out_sock_addr,
 263     struct NaClDesc               **out_app_addr);
 264
 265 int64_t NaClReverseInterfaceRequestQuotaForWrite(
 266     struct NaClReverseInterface   *self,
 267     char const                    *file_id,
 268     int64_t                       offset,
 269     int64_t                       length);
 270
 271 extern struct NaClReverseInterfaceVtbl const kNaClReverseInterfaceVtbl;
 272
 273 EXTERN_C_END
 274
 275 #endif /* NATIVE_CLIENT_SRC_TRUSTED_REVERSE_SERVICE_REVERSE_SERVICE_C_H_ */