v8-initialization.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315
  1. // Copyright 2021 the V8 project authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef INCLUDE_V8_INITIALIZATION_H_
  5. #define INCLUDE_V8_INITIALIZATION_H_
  6. #include <stddef.h>
  7. #include <stdint.h>
  8. #include "v8-callbacks.h" // NOLINT(build/include_directory)
  9. #include "v8-internal.h" // NOLINT(build/include_directory)
  10. #include "v8-isolate.h" // NOLINT(build/include_directory)
  11. #include "v8-platform.h" // NOLINT(build/include_directory)
  12. #include "v8config.h" // NOLINT(build/include_directory)
  13. // We reserve the V8_* prefix for macros defined in V8 public API and
  14. // assume there are no name conflicts with the embedder's code.
  15. /**
  16. * The v8 JavaScript engine.
  17. */
  18. namespace v8 {
  19. class PageAllocator;
  20. class Platform;
  21. template <class K, class V, class T>
  22. class PersistentValueMapBase;
  23. /**
  24. * EntropySource is used as a callback function when v8 needs a source
  25. * of entropy.
  26. */
  27. using EntropySource = bool (*)(unsigned char* buffer, size_t length);
  28. /**
  29. * ReturnAddressLocationResolver is used as a callback function when v8 is
  30. * resolving the location of a return address on the stack. Profilers that
  31. * change the return address on the stack can use this to resolve the stack
  32. * location to wherever the profiler stashed the original return address.
  33. *
  34. * \param return_addr_location A location on stack where a machine
  35. * return address resides.
  36. * \returns Either return_addr_location, or else a pointer to the profiler's
  37. * copy of the original return address.
  38. *
  39. * \note The resolver function must not cause garbage collection.
  40. */
  41. using ReturnAddressLocationResolver =
  42. uintptr_t (*)(uintptr_t return_addr_location);
  43. using DcheckErrorCallback = void (*)(const char* file, int line,
  44. const char* message);
  45. /**
  46. * Container class for static utility functions.
  47. */
  48. class V8_EXPORT V8 {
  49. public:
  50. /**
  51. * Hand startup data to V8, in case the embedder has chosen to build
  52. * V8 with external startup data.
  53. *
  54. * Note:
  55. * - By default the startup data is linked into the V8 library, in which
  56. * case this function is not meaningful.
  57. * - If this needs to be called, it needs to be called before V8
  58. * tries to make use of its built-ins.
  59. * - To avoid unnecessary copies of data, V8 will point directly into the
  60. * given data blob, so pretty please keep it around until V8 exit.
  61. * - Compression of the startup blob might be useful, but needs to
  62. * handled entirely on the embedders' side.
  63. * - The call will abort if the data is invalid.
  64. */
  65. static void SetSnapshotDataBlob(StartupData* startup_blob);
  66. /** Set the callback to invoke in case of Dcheck failures. */
  67. static void SetDcheckErrorHandler(DcheckErrorCallback that);
  68. /**
  69. * Sets V8 flags from a string.
  70. */
  71. static void SetFlagsFromString(const char* str);
  72. static void SetFlagsFromString(const char* str, size_t length);
  73. /**
  74. * Sets V8 flags from the command line.
  75. */
  76. static void SetFlagsFromCommandLine(int* argc, char** argv,
  77. bool remove_flags);
  78. /** Get the version string. */
  79. static const char* GetVersion();
  80. /**
  81. * Initializes V8. This function needs to be called before the first Isolate
  82. * is created. It always returns true.
  83. */
  84. V8_INLINE static bool Initialize() {
  85. const int kBuildConfiguration =
  86. (internal::PointerCompressionIsEnabled() ? kPointerCompression : 0) |
  87. (internal::SmiValuesAre31Bits() ? k31BitSmis : 0) |
  88. (internal::SandboxedExternalPointersAreEnabled()
  89. ? kSandboxedExternalPointers
  90. : 0) |
  91. (internal::SandboxIsEnabled() ? kSandbox : 0);
  92. return Initialize(kBuildConfiguration);
  93. }
  94. /**
  95. * Allows the host application to provide a callback which can be used
  96. * as a source of entropy for random number generators.
  97. */
  98. static void SetEntropySource(EntropySource source);
  99. /**
  100. * Allows the host application to provide a callback that allows v8 to
  101. * cooperate with a profiler that rewrites return addresses on stack.
  102. */
  103. static void SetReturnAddressLocationResolver(
  104. ReturnAddressLocationResolver return_address_resolver);
  105. /**
  106. * Releases any resources used by v8 and stops any utility threads
  107. * that may be running. Note that disposing v8 is permanent, it
  108. * cannot be reinitialized.
  109. *
  110. * It should generally not be necessary to dispose v8 before exiting
  111. * a process, this should happen automatically. It is only necessary
  112. * to use if the process needs the resources taken up by v8.
  113. */
  114. static bool Dispose();
  115. /**
  116. * Initialize the ICU library bundled with V8. The embedder should only
  117. * invoke this method when using the bundled ICU. Returns true on success.
  118. *
  119. * If V8 was compiled with the ICU data in an external file, the location
  120. * of the data file has to be provided.
  121. */
  122. static bool InitializeICU(const char* icu_data_file = nullptr);
  123. /**
  124. * Initialize the ICU library bundled with V8. The embedder should only
  125. * invoke this method when using the bundled ICU. If V8 was compiled with
  126. * the ICU data in an external file and when the default location of that
  127. * file should be used, a path to the executable must be provided.
  128. * Returns true on success.
  129. *
  130. * The default is a file called icudtl.dat side-by-side with the executable.
  131. *
  132. * Optionally, the location of the data file can be provided to override the
  133. * default.
  134. */
  135. static bool InitializeICUDefaultLocation(const char* exec_path,
  136. const char* icu_data_file = nullptr);
  137. /**
  138. * Initialize the external startup data. The embedder only needs to
  139. * invoke this method when external startup data was enabled in a build.
  140. *
  141. * If V8 was compiled with the startup data in an external file, then
  142. * V8 needs to be given those external files during startup. There are
  143. * three ways to do this:
  144. * - InitializeExternalStartupData(const char*)
  145. * This will look in the given directory for the file "snapshot_blob.bin".
  146. * - InitializeExternalStartupDataFromFile(const char*)
  147. * As above, but will directly use the given file name.
  148. * - Call SetSnapshotDataBlob.
  149. * This will read the blobs from the given data structure and will
  150. * not perform any file IO.
  151. */
  152. static void InitializeExternalStartupData(const char* directory_path);
  153. static void InitializeExternalStartupDataFromFile(const char* snapshot_blob);
  154. /**
  155. * Sets the v8::Platform to use. This should be invoked before V8 is
  156. * initialized.
  157. */
  158. static void InitializePlatform(Platform* platform);
  159. /**
  160. * Clears all references to the v8::Platform. This should be invoked after
  161. * V8 was disposed.
  162. */
  163. static void DisposePlatform();
  164. V8_DEPRECATED("Use DisposePlatform()")
  165. static void ShutdownPlatform() { DisposePlatform(); }
  166. #ifdef V8_SANDBOX
  167. //
  168. // Sandbox related API.
  169. //
  170. // This API is not yet stable and subject to changes in the future.
  171. //
  172. /**
  173. * Initializes the V8 sandbox.
  174. *
  175. * This must be invoked after the platform was initialized but before V8 is
  176. * initialized. The sandbox is torn down during platform shutdown.
  177. * Returns true on success, false otherwise.
  178. *
  179. * TODO(saelo) Once it is no longer optional to initialize the sandbox when
  180. * compiling with V8_SANDBOX, the sandbox initialization will likely happen
  181. * as part of V8::Initialize, at which point this function should be removed.
  182. */
  183. static bool InitializeSandbox();
  184. V8_DEPRECATE_SOON("Use InitializeSandbox()")
  185. static bool InitializeVirtualMemoryCage() { return InitializeSandbox(); }
  186. /**
  187. * Provides access to the virtual address subspace backing the sandbox.
  188. *
  189. * This can be used to allocate pages inside the sandbox, for example to
  190. * obtain virtual memory for ArrayBuffer backing stores, which must be
  191. * located inside the sandbox.
  192. *
  193. * It should be assumed that an attacker can corrupt data inside the sandbox,
  194. * and so in particular the contents of pages allocagted in this virtual
  195. * address space, arbitrarily and concurrently. Due to this, it is
  196. * recommended to to only place pure data buffers in them.
  197. *
  198. * This function must only be called after initializing the sandbox.
  199. */
  200. static VirtualAddressSpace* GetSandboxAddressSpace();
  201. V8_DEPRECATE_SOON("Use GetSandboxAddressSpace()")
  202. static PageAllocator* GetVirtualMemoryCagePageAllocator();
  203. /**
  204. * Returns the size of the sandbox in bytes.
  205. *
  206. * If the sandbox has not been initialized, or if the initialization failed,
  207. * this returns zero.
  208. */
  209. static size_t GetSandboxSizeInBytes();
  210. V8_DEPRECATE_SOON("Use GetSandboxSizeInBytes()")
  211. static size_t GetVirtualMemoryCageSizeInBytes() {
  212. return GetSandboxSizeInBytes();
  213. }
  214. /**
  215. * Returns whether the sandbox is configured securely.
  216. *
  217. * If V8 cannot create a proper sandbox, it will fall back to creating a
  218. * sandbox that doesn't have the desired security properties but at least
  219. * still allows V8 to function. This API can be used to determine if such an
  220. * insecure sandbox is being used, in which case it will return false.
  221. */
  222. static bool IsSandboxConfiguredSecurely();
  223. V8_DEPRECATE_SOON("Use IsSandboxConfiguredSecurely()")
  224. static bool IsUsingSecureVirtualMemoryCage() {
  225. return IsSandboxConfiguredSecurely();
  226. }
  227. #endif
  228. /**
  229. * Activate trap-based bounds checking for WebAssembly.
  230. *
  231. * \param use_v8_signal_handler Whether V8 should install its own signal
  232. * handler or rely on the embedder's.
  233. */
  234. static bool EnableWebAssemblyTrapHandler(bool use_v8_signal_handler);
  235. #if defined(V8_OS_WIN)
  236. /**
  237. * On Win64, by default V8 does not emit unwinding data for jitted code,
  238. * which means the OS cannot walk the stack frames and the system Structured
  239. * Exception Handling (SEH) cannot unwind through V8-generated code:
  240. * https://code.google.com/p/v8/issues/detail?id=3598.
  241. *
  242. * This function allows embedders to register a custom exception handler for
  243. * exceptions in V8-generated code.
  244. */
  245. static void SetUnhandledExceptionCallback(
  246. UnhandledExceptionCallback unhandled_exception_callback);
  247. #endif
  248. /**
  249. * Allows the host application to provide a callback that will be called when
  250. * v8 has encountered a fatal failure to allocate memory and is about to
  251. * terminate.
  252. */
  253. static void SetFatalMemoryErrorCallback(OOMErrorCallback oom_error_callback);
  254. /**
  255. * Get statistics about the shared memory usage.
  256. */
  257. static void GetSharedMemoryStatistics(SharedMemoryStatistics* statistics);
  258. private:
  259. V8();
  260. enum BuildConfigurationFeatures {
  261. kPointerCompression = 1 << 0,
  262. k31BitSmis = 1 << 1,
  263. kSandboxedExternalPointers = 1 << 2,
  264. kSandbox = 1 << 3,
  265. };
  266. /**
  267. * Checks that the embedder build configuration is compatible with
  268. * the V8 binary and if so initializes V8.
  269. */
  270. static bool Initialize(int build_config);
  271. friend class Context;
  272. template <class K, class V, class T>
  273. friend class PersistentValueMapBase;
  274. };
  275. } // namespace v8
  276. #endif // INCLUDE_V8_INITIALIZATION_H_