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   /* For debugging, messaging. |message| goes to console. */
  85   void                          (*Log)(
  86       struct NaClReverseInterface   *self,
  87       char const                    *message);
  88
  89   /* Startup handshake */
  90   void                          (*StartupInitializationComplete)(
  91       struct NaClReverseInterface   *self);
  92
  93   /*
  94    * Name service use.
  95    *
  96    * Some of these functions require that the actual operation be done
  97    * in a different thread, so that the implementation of the
  98    * interface will have to block the requesting thread.  However, on
  99    * surf away, the thread switch may get cancelled, and the
 100    * implementation will have to reply with a failure indication.
 101    *
 102    * The bool functions returns false if the service thread unblocked
 103    * because of surf-away, shutdown, or other issues.  The plugin,
 104    * when it tells sel_ldr to shut down, will also signal all threads
 105    * that are waiting for main thread callbacks to wake up and abandon
 106    * their vigil after the callbacks are all cancelled (by abandoning
 107    * the WeakRefAnchor or by bombing their CompletionCallbackFactory).
 108    * Since shutdown/surfaway is the only admissible error, we use bool
 109    * as the return type.
 110    */
 111
 112   /*
 113    * Stores the manifest keys into the |buffer| of size |nbytes|.
 114    * Returns the number of bytes copied if successful, otherwise
 115    * returns the size required if |buffer| is not large enough.
 116    */
 117   size_t                        (*EnumerateManifestKeys)(
 118       struct NaClReverseInterface   *self,
 119       char                          *buffer,
 120       size_t                        buffer_bytes);
 121
 122   /*
 123    * Opens manifest entry specified by |url_key|. Returns 1 if
 124    * successful and stores the file descriptor in |out_desc|, otherwise
 125    * returns 0.
 126    */
 127   int                           (*OpenManifestEntry)(
 128       struct NaClReverseInterface   *self,
 129       char const                    *url_key,
 130       struct NaClFileInfo           *info);
 131
 132   /*
 133    * Closes manifest entry with file descriptor |desc|. Returns 1 if
 134    * successful, 0 otherwise.
 135    */
 136   int                           (*CloseManifestEntry)(
 137       struct NaClReverseInterface   *self,
 138       int32_t                       desc);
 139
 140   /*
 141    * Reports the client crash.
 142    */
 143   void                          (*ReportCrash)(
 144       struct NaClReverseInterface   *self);
 145
 146   /*
 147    * The low-order 8 bits of the |exit_status| should be reported to
 148    * any interested parties.
 149    */
 150   void                          (*ReportExitStatus)(
 151       struct NaClReverseInterface   *self,
 152       int                           exit_status);
 153
 154   /*
 155    * Standard output and standard error redirection, via setting
 156    * NACL_EXE_STDOUT to the string "DEBUG_ONLY:dev://postmessage" (see
 157    * native_client/src/trusted/nacl_resource.* and sel_ldr).  NB: the
 158    * contents of |message| is arbitrary bytes and not an Unicode
 159    * string, so the implementation should take care to handle this
 160    * appropriately.
 161    */
 162   void                          (*DoPostMessage)(
 163       struct NaClReverseInterface   *self,
 164       char const                    *message,
 165       size_t                        message_bytes);
 166
 167   /*
 168    * Create new service runtime process and return secure command
 169    * channel and untrusted application channel socket addresses. Returns
 170    * 0 if successful or negative ABI error value otherwise (see
 171    * service_runtime/include/sys/errno.h).  DEPRECATED.
 172    */
 173   int                           (*CreateProcess)(
 174       struct NaClReverseInterface  *self,
 175       struct NaClDesc              **out_sock_addr,
 176       struct NaClDesc              **out_app_addr);
 177
 178   /*
 179    * Create new service runtime process and return secure command
 180    * channel, untrusted application channel socket addresses, and pid
 181    * via a result delivery functor.  Returns negated ABI errno value
 182    * in pid if there were errors (see the header file
 183    * service_runtime/include/sys/errno.h).  The |out_pid_or_errno|
 184    * functor argument is also used to allow the "init" process to
 185    * inform the embedding environment, via FinalizeProcess, that it is
 186    * okay to finalize any resources associated with the identified
 187    * subprocess when the subprocess has exited.
 188    */
 189   void                          (*CreateProcessFunctorResult)(
 190       struct NaClReverseInterface *self,
 191       void (*result_functor)(void *functor_state,
 192                              struct NaClDesc *out_sock_addr,
 193                              struct NaClDesc *out_app_addr,
 194                              int32_t out_pid_or_errno),
 195       void *functor_state);
 196
 197   void                          (*FinalizeProcess)(
 198       struct NaClReverseInterface *self,
 199       int32_t pid);
 200
 201   /*
 202    * Quota checking for files that were sent to the untrusted module.
 203    * TODO(sehr): remove the stub interface once the plugin provides one.
 204    */
 205   int64_t                       (*RequestQuotaForWrite)(
 206       struct NaClReverseInterface   *self,
 207       char const                    *file_id,
 208       int64_t                       offset,
 209       int64_t                       length);
 210 };
 211
 212 /*
 213  * The protected Ctor is intended for use by subclasses of
 214  * NaClReverseInterface.
 215  */
 216 int NaClReverseInterfaceCtor_protected(
 217     struct NaClReverseInterface   *self);
 218
 219 void NaClReverseInterfaceDtor(struct NaClRefCount *vself);
 220
 221 void NaClReverseInterfaceLog(
 222     struct NaClReverseInterface   *self,
 223     char const                    *message);
 224
 225 void NaClReverseInterfaceStartupInitializationComplete(
 226     struct NaClReverseInterface   *self);
 227
 228 size_t NaClReverseInterfaceEnumerateManifestKeys(
 229     struct NaClReverseInterface   *self,
 230     char                          *buffer,
 231     size_t                        buffer_bytes);
 232
 233 int NaClReverseInterfaceOpenManifestEntry(
 234     struct NaClReverseInterface   *self,
 235     char const                    *url_key,
 236     struct NaClFileInfo           *info);
 237
 238 int NaClReverseInterfaceCloseManifestEntry(
 239     struct NaClReverseInterface   *self,
 240     int32_t                       desc);
 241
 242 void NaClReverseInterfaceReportCrash(
 243     struct NaClReverseInterface   *self);
 244
 245 void NaClReverseInterfaceReportExitStatus(
 246     struct NaClReverseInterface   *self,
 247     int                           exit_status);
 248
 249 void NaClReverseInterfaceDoPostMessage(
 250     struct NaClReverseInterface   *self,
 251     char const                    *message,
 252     size_t                        message_bytes);
 253
 254 void NaClReverseInterfaceCreateProcessFunctorResult(
 255     struct NaClReverseInterface *self,
 256     void (*result_functor)(void *functor_state,
 257                            struct NaClDesc *out_sock_addr,
 258                            struct NaClDesc *out_app_addr,
 259                            int32_t out_pid_or_errno),
 260     void *functor_state);
 261
 262 void NaClReverseInterfaceFinalizeProcess(struct NaClReverseInterface *self,
 263                                          int32_t pid);
 264
 265 int NaClReverseInterfaceCreateProcess(
 266     struct NaClReverseInterface   *self,
 267     struct NaClDesc               **out_sock_addr,
 268     struct NaClDesc               **out_app_addr);
 269
 270 int64_t NaClReverseInterfaceRequestQuotaForWrite(
 271     struct NaClReverseInterface   *self,
 272     char const                    *file_id,
 273     int64_t                       offset,
 274     int64_t                       length);
 275
 276 extern struct NaClReverseInterfaceVtbl const kNaClReverseInterfaceVtbl;
 277
 278 EXTERN_C_END
 279
 280 #endif /* NATIVE_CLIENT_SRC_TRUSTED_REVERSE_SERVICE_REVERSE_SERVICE_C_H_ */