src/native_client/src/public/chrome_main.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_PUBLIC_CHROME_MAIN_H_
   8 #define NATIVE_CLIENT_SRC_PUBLIC_CHROME_MAIN_H_ 1
   9
  10 #include "native_client/src/include/nacl_base.h"
  11 #include "native_client/src/include/portability.h"
  12 /*
  13  * nacl_imc_c.h is used to define NaClHandle.  This should eventually
  14  * go away when Chromium's use of SRPC is removed
  15  * (http://crbug.com/239656).
  16  */
  17 #include "native_client/src/shared/imc/nacl_imc_c.h"
  18
  19 EXTERN_C_BEGIN
  20
  21 struct NaClApp;
  22 struct NaClValidationCache;
  23
  24
  25 /*
  26  * This interface may be used as follows:
  27  *
  28  *   #if OS_POSIX
  29  *   NaClChromeMainSetUrandomFd(urandom_fd);
  30  *   #endif
  31  *   NaClChromeMainInit();
  32  *   // The following may be done in any order:
  33  *   struct NaClApp *nap = NaClAppCreate();
  34  *   struct NaClChromeMainArgs *args = NaClChromeMainArgsCreate();
  35  *   // Fill out args...
  36  *   NaClAppSetDesc(nap, NACL_CHROME_DESC_BASE, NaClDescMakeCustomDesc(...));
  37  *   NaClChromeMainStartApp(nap, args);
  38  */
  39
  40 /*
  41  * Embedders of NaCl may use descriptor numbers of
  42  * NACL_CHROME_DESC_BASE and higher when setting up a NaClApp's
  43  * initial descriptors using NaClAppSetDesc().
  44  *
  45  * This number is chosen so as not to conflict with
  46  * NACL_SERVICE_PORT_DESCRIPTOR, NACL_SERVICE_ADDRESS_DESCRIPTOR and
  47  * export_addr_to inside NaClChromeMainStartApp().
  48  */
  49 #define NACL_CHROME_DESC_BASE 6
  50
  51
  52 struct NaClChromeMainArgs {
  53   /*
  54    * Handle for bootstrapping a NaCl IMC connection to the trusted
  55    * PPAPI plugin.  Required.
  56    */
  57   NaClHandle imc_bootstrap_handle;
  58
  59   /*
  60    * File descriptor for the NaCl integrated runtime (IRT) library.
  61    * Note that this is a file descriptor even on Windows (where file
  62    * descriptors are emulated by the C runtime library).
  63    * Optional; may be -1.  Optional when loading nexes that don't follow
  64    * NaCl's stable ABI, such as the PNaCl translator.
  65    */
  66   int irt_fd;
  67
  68   /* Whether to enable untrusted hardware exception handling.  Boolean. */
  69   int enable_exception_handling;
  70
  71   /* Whether to enable NaCl's built-in GDB RSP debug stub.  Boolean. */
  72   int enable_debug_stub;
  73
  74   /* Whether to enable NaCl's dynamic code system calls.  Boolean. */
  75   int enable_dyncode_syscalls;
  76
  77   /* Whether or not the app is a PNaCl app. Boolean. */
  78   int pnacl_mode;
  79
  80   /*
  81    * Maximum size of the initially loaded nexe's code segment, in
  82    * bytes.  0 for no limit, which is the default.
  83    *
  84    * This is intended for security hardening.  It reduces the
  85    * proportion of address space that can contain attacker-controlled
  86    * executable code.  It reduces the chance of a spraying attack
  87    * succeeding if there is a vulnerability that allows jumping into
  88    * the middle of an instruction.  Note that setting a limit here is
  89    * only useful if enable_dyncode_syscalls is false.
  90    */
  91   uint32_t initial_nexe_max_code_bytes;
  92
  93 #if NACL_LINUX || NACL_OSX
  94   /*
  95    * Server socket that will be used by debug stub to accept connections
  96    * from NaCl GDB.  This socket descriptor has already had bind() and listen()
  97    * called on it.  Optional; may be -1.
  98    */
  99   int debug_stub_server_bound_socket_fd;
 100 #endif
 101
 102 #if NACL_WINDOWS
 103   /*
 104    * Callback called when debug stub port is known.  Optional; may be NULL.
 105    */
 106   void (*debug_stub_server_port_selected_handler_func)(uint16_t port);
 107 #endif
 108
 109   /*
 110    * Callback to use for creating shared memory objects.  Optional;
 111    * may be NULL.
 112    */
 113   NaClCreateMemoryObjectFunc create_memory_object_func;
 114
 115   /* Cache for NaCl validation judgements.  Optional; may be NULL. */
 116   struct NaClValidationCache *validation_cache;
 117
 118 #if NACL_WINDOWS
 119   /*
 120    * Callback to use instead of DuplicateHandle() for copying a
 121    * Windows handle to another process.  Optional; may be NULL.
 122    */
 123   NaClBrokerDuplicateHandleFunc broker_duplicate_handle_func;
 124
 125   /*
 126    * Callback to use for requesting that a debug exception handler be
 127    * attached to this process for handling hardware exceptions via the
 128    * Windows debug API.  The data in info/info_size must be passed to
 129    * NaClDebugExceptionHandlerRun().  Optional; may be NULL.
 130    */
 131   int (*attach_debug_exception_handler_func)(const void *info,
 132                                              size_t info_size);
 133 #endif
 134
 135 #if NACL_LINUX || NACL_OSX
 136   /*
 137    * The result of sysconf(_SC_NPROCESSORS_ONLN).  The Chrome
 138    * outer-sandbox prevents the glibc implementation of sysconf from
 139    * working -- which just reads /proc/cpuinfo or similar file -- so
 140    * instead, the launcher should fill this in.  In principle this is
 141    * optional and may be -1, but this will make
 142    * sysconf(_SC_NPROCESSORS_ONLN) fail and result in some NaCl
 143    * modules failing.
 144    *
 145    * NB: sysconf(_SC_NPROCESSORS_ONLN) is the number of processors
 146    * on-line and not the same as sysconf(_SC_NPROCESSORS_CONF) -- the
 147    * former is possibly dynamic on systems with hotpluggable CPUs,
 148    * whereas the configured number of processors -- what the kernel is
 149    * configured to be able to handle or the number of processors
 150    * potentially available.  Setting number_of_cores below would
 151    * result in reporting a static value, rather than a potentially
 152    * changing, dynamic value.
 153    *
 154    * We are unlikely to ever run on hotpluggable multiprocessor
 155    * systems.
 156    */
 157   int number_of_cores;
 158 #endif
 159
 160 #if NACL_LINUX
 161   /*
 162    * Size of address space reserved at address zero onwards for the
 163    * sandbox.  This is optional and may be 0 if no address space has
 164    * been reserved, though some sandboxes (such as ARM) might fail in
 165    * that case.
 166    */
 167   size_t prereserved_sandbox_size;
 168 #endif
 169
 170   /*
 171    * Descriptor for the user nexe module to load and run. This is optional and
 172    * may be NULL if SRPC is used for module loading.
 173    */
 174   struct NaClDesc *nexe_desc;
 175 };
 176
 177 #if NACL_LINUX || NACL_OSX
 178 /*
 179  * Sets a file descriptor for /dev/urandom for reading random data.
 180  * This takes ownership of the file descriptor.  This is intended for
 181  * use inside an outer sandbox where NaCl may not be able to open()
 182  * /dev/urandom.
 183  *
 184  * If this is called, it must be called before NaClChromeMainInit(),
 185  * otherwise NaClChromeMainInit() will try to open() /dev/urandom.
 186  */
 187 void NaClChromeMainSetUrandomFd(int urandom_fd);
 188 #endif
 189
 190 /* Initialize NaCl.  This must be called before NaClAppCreate(). */
 191 void NaClChromeMainInit(void);
 192
 193 /*
 194  * Sets a function to be called when a fatal error is logged. When the passed
 195  * function is invoked, recent log messages will be passed in the data
 196  * parameter, and its length in the bytes parameter.
 197  * This function is only safe to call after NaClChromeMainInit().
 198  *
 199  * If NaClSetFatalErrorCallback() is not called, recent log messages will be
 200  * written to the IMC bootstrap channel on a fatal error.
 201  */
 202 void NaClSetFatalErrorCallback(void (*func)(const char *data, size_t bytes));
 203
 204 /* Create a new args struct containing default values. */
 205 struct NaClChromeMainArgs *NaClChromeMainArgsCreate(void);
 206
 207 /* Start NaCl. This does not return. */
 208 void NaClChromeMainStartApp(struct NaClApp *nap,
 209                             struct NaClChromeMainArgs *args);
 210
 211 EXTERN_C_END
 212
 213 #endif