1 /* Copyright (c) 2012 The Chromium 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 */ 5 6 /* This file contains NaCl private interfaces. This interface is not versioned 7 * and is for internal Chrome use. It may change without notice. */ 8 9 label Chrome { 10 M25 = 1.0 11 }; 12 13 #inline c 14 #include "ppapi/c/private/pp_file_handle.h" 15 #include "ppapi/c/private/ppb_instance_private.h" 16 #endinl 17 18 /** NaCl-specific errors that should be reported to the user. 19 * These error codes are reported via UMA so, if you edit them: 20 * 1) make sure you understand UMA first. 21 * 2) update src/tools/metrics/histograms/histograms.xml 22 * Values are explicitly specified to make sure they don't shift around when 23 * edited, and also to make reading about:histograms easier. 24 */ 25 enum PP_NaClError { 26 PP_NACL_ERROR_LOAD_SUCCESS = 0, 27 PP_NACL_ERROR_LOAD_ABORTED = 1, 28 PP_NACL_ERROR_UNKNOWN = 2, 29 PP_NACL_ERROR_MANIFEST_RESOLVE_URL = 3, 30 PP_NACL_ERROR_MANIFEST_LOAD_URL = 4, 31 PP_NACL_ERROR_MANIFEST_STAT = 5, 32 PP_NACL_ERROR_MANIFEST_TOO_LARGE = 6, 33 PP_NACL_ERROR_MANIFEST_OPEN = 7, 34 PP_NACL_ERROR_MANIFEST_MEMORY_ALLOC = 8, 35 PP_NACL_ERROR_MANIFEST_READ = 9, 36 PP_NACL_ERROR_MANIFEST_PARSING = 10, 37 PP_NACL_ERROR_MANIFEST_SCHEMA_VALIDATE = 11, 38 PP_NACL_ERROR_MANIFEST_GET_NEXE_URL = 12, 39 PP_NACL_ERROR_NEXE_LOAD_URL = 13, 40 PP_NACL_ERROR_NEXE_ORIGIN_PROTOCOL = 14, 41 PP_NACL_ERROR_NEXE_FH_DUP = 15, 42 PP_NACL_ERROR_NEXE_STAT = 16, 43 PP_NACL_ERROR_ELF_CHECK_IO = 17, 44 PP_NACL_ERROR_ELF_CHECK_FAIL = 18, 45 PP_NACL_ERROR_SEL_LDR_INIT = 19, 46 PP_NACL_ERROR_SEL_LDR_CREATE_LAUNCHER = 20, 47 PP_NACL_ERROR_SEL_LDR_FD = 21, 48 PP_NACL_ERROR_SEL_LDR_LAUNCH = 22, 49 /* Deprecated, safe to reuse the value because it's never logged in UMA. 50 PP_NACL_ERROR_SEL_LDR_COMMUNICATION = 23, */ 51 PP_NACL_ERROR_SEL_LDR_SEND_NEXE = 24, 52 PP_NACL_ERROR_SEL_LDR_HANDLE_PASSING = 25, 53 PP_NACL_ERROR_SEL_LDR_START_MODULE = 26, 54 PP_NACL_ERROR_SEL_LDR_START_STATUS = 27, 55 PP_NACL_ERROR_SRPC_CONNECTION_FAIL = 28, 56 PP_NACL_ERROR_START_PROXY_CHECK_PPP = 29, 57 PP_NACL_ERROR_START_PROXY_ALLOC = 30, 58 PP_NACL_ERROR_START_PROXY_MODULE = 31, 59 PP_NACL_ERROR_START_PROXY_INSTANCE = 32, 60 PP_NACL_ERROR_SEL_LDR_COMMUNICATION_CMD_CHANNEL = 33, 61 PP_NACL_ERROR_SEL_LDR_COMMUNICATION_REV_SETUP = 34, 62 PP_NACL_ERROR_SEL_LDR_COMMUNICATION_WRAPPER = 35, 63 PP_NACL_ERROR_SEL_LDR_COMMUNICATION_REV_SERVICE = 36, 64 PP_NACL_ERROR_START_PROXY_CRASH = 37, 65 PP_NACL_ERROR_MANIFEST_PROGRAM_MISSING_ARCH = 38, 66 PP_NACL_ERROR_PNACL_CACHE_OPEN_INPROGRESS = 39, 67 PP_NACL_ERROR_PNACL_CACHE_OPEN_NOACCESS = 40, 68 PP_NACL_ERROR_PNACL_CACHE_OPEN_NOQUOTA = 41, 69 PP_NACL_ERROR_PNACL_CACHE_OPEN_NOSPACE = 42, 70 PP_NACL_ERROR_PNACL_CACHE_OPEN_OTHER = 43, 71 PP_NACL_ERROR_PNACL_CACHE_DIRECTORY_CREATE = 44, 72 PP_NACL_ERROR_PNACL_CACHE_FILEOPEN_NOACCESS = 45, 73 PP_NACL_ERROR_PNACL_CACHE_FILEOPEN_NOQUOTA = 46, 74 PP_NACL_ERROR_PNACL_CACHE_FILEOPEN_NOSPACE = 47, 75 PP_NACL_ERROR_PNACL_CACHE_FILEOPEN_NOTAFILE = 48, 76 PP_NACL_ERROR_PNACL_CACHE_FILEOPEN_OTHER = 49, 77 PP_NACL_ERROR_PNACL_CACHE_FETCH_NOACCESS = 50, 78 PP_NACL_ERROR_PNACL_CACHE_FETCH_NOTFOUND = 51, 79 PP_NACL_ERROR_PNACL_CACHE_FETCH_OTHER = 52, 80 PP_NACL_ERROR_PNACL_CACHE_FINALIZE_COPY_NOQUOTA = 53, 81 PP_NACL_ERROR_PNACL_CACHE_FINALIZE_COPY_NOSPACE = 54, 82 PP_NACL_ERROR_PNACL_CACHE_FINALIZE_COPY_OTHER = 55, 83 PP_NACL_ERROR_PNACL_CACHE_FINALIZE_RENAME_NOACCESS = 56, 84 PP_NACL_ERROR_PNACL_CACHE_FINALIZE_RENAME_OTHER = 57, 85 PP_NACL_ERROR_PNACL_RESOURCE_FETCH = 58, 86 PP_NACL_ERROR_PNACL_PEXE_FETCH_ABORTED = 59, 87 PP_NACL_ERROR_PNACL_PEXE_FETCH_NOACCESS = 60, 88 PP_NACL_ERROR_PNACL_PEXE_FETCH_OTHER = 61, 89 PP_NACL_ERROR_PNACL_THREAD_CREATE = 62, 90 PP_NACL_ERROR_PNACL_LLC_SETUP = 63, 91 PP_NACL_ERROR_PNACL_LD_SETUP = 64, 92 PP_NACL_ERROR_PNACL_LLC_INTERNAL = 65, 93 PP_NACL_ERROR_PNACL_LD_INTERNAL = 66, 94 PP_NACL_ERROR_PNACL_CREATE_TEMP = 67, 95 /* This entry is no longer used, but should not be removed, because UMA 96 numbers need to be kept consistent. */ 97 PP_NACL_ERROR_PNACL_NOT_ENABLED = 68, 98 PP_NACL_ERROR_MANIFEST_NOACCESS_URL = 69, 99 PP_NACL_ERROR_NEXE_NOACCESS_URL = 70, 100 PP_NACL_ERROR_PNACL_CRASH_THROTTLED = 71, 101 102 /* If you add a code, read the enum comment above on how to update 103 histograms. */ 104 PP_NACL_ERROR_MAX 105 }; 106 107 /** Event types that NaCl may use when reporting load progress or errors. */ 108 enum PP_NaClEventType { 109 PP_NACL_EVENT_LOADSTART, 110 PP_NACL_EVENT_PROGRESS, 111 PP_NACL_EVENT_ERROR, 112 PP_NACL_EVENT_ABORT, 113 PP_NACL_EVENT_LOAD, 114 PP_NACL_EVENT_LOADEND, 115 PP_NACL_EVENT_CRASH 116 }; 117 118 enum PP_UrlSchemeType { 119 PP_SCHEME_CHROME_EXTENSION, 120 PP_SCHEME_DATA, 121 PP_SCHEME_OTHER 122 }; 123 124 enum PP_NaClReadyState { 125 /* The trusted plugin begins in this ready state. */ 126 PP_NACL_READY_STATE_UNSENT = 0, 127 /* The manifest file has been requested, but not yet received. */ 128 PP_NACL_READY_STATE_OPENED = 1, 129 /* The manifest file has been received and the nexe successfully requested. */ 130 PP_NACL_READY_STATE_LOADING = 3, 131 /* The nexe has been loaded and the proxy started, so it is ready for 132 interaction with the page. */ 133 PP_NACL_READY_STATE_DONE = 4 134 }; 135 136 struct PP_PNaClOptions { 137 PP_Bool translate; 138 PP_Bool is_debug; 139 int32_t opt_level; 140 }; 141 142 /* Callback invoked upon completion of PPP_ManifestService::OpenResource(). */ 143 typedef void PP_OpenResourceCompletionCallback([inout] mem_t user_data, 144 [in] PP_FileHandle file_handle); 145 146 /* ManifestService to support irt_open_resource() function. 147 * All functions of the service should have PP_Bool return value. It represents 148 * whether the service is still alive or not. Trivially Quit() should always 149 * return false. However, other functions also can return false. 150 * Once false is called, as the service has been destructed, all functions 151 * should never be called afterwords. 152 */ 153 interface PPP_ManifestService { 154 /* Called when ManifestService should be destructed. */ 155 PP_Bool Quit([inout] mem_t user_data); 156 157 /* Called when PPAPI initialization in the NaCl plugin is finished. */ 158 PP_Bool StartupInitializationComplete([inout] mem_t user_data); 159 160 /* Called when irt_open_resource() is invoked in the NaCl plugin. 161 * Upon completion, callback will be invoked with given callback_user_data 162 * and the result file handle (or PP_kInvalidFileHandle on error). */ 163 PP_Bool OpenResource([inout] mem_t user_data, 164 [in] str_t entry_key, 165 [in] PP_OpenResourceCompletionCallback callback, 166 [inout] mem_t callback_user_data); 167 }; 168 169 /* Corresponds to NaClFileInfo in 170 * native_client/src/trusted/validator/nacl_file_info.h */ 171 struct PP_NaClFileInfo { 172 PP_FileHandle handle; 173 174 /* See NaClFileToken comment in nacl_file_info.h */ 175 uint64_t token_lo; 176 uint64_t token_hi; 177 }; 178 179 /* PPB_NaCl_Private */ 180 interface PPB_NaCl_Private { 181 /* Launches NaCl's sel_ldr process. Returns PP_EXTERNAL_PLUGIN_OK on success 182 * and writes a NaClHandle to imc_handle. Returns PP_EXTERNAL_PLUGIN_FAILED on 183 * failure. The |enable_ppapi_dev| parameter controls whether GetInterface 184 * returns 'Dev' interfaces to the NaCl plugin. The |uses_ppapi| flag 185 * indicates that the nexe run by sel_ldr will use the PPAPI APIs. 186 * This implies that LaunchSelLdr is run from the main thread. If a nexe 187 * does not need PPAPI, then it can run off the main thread. 188 * The |uses_irt| flag indicates whether the IRT should be loaded in this 189 * NaCl process. This is true for ABI stable nexes. 190 * The |uses_nonsfi_mode| flag indicates whether or not nonsfi-mode should 191 * be used with the binary pointed by the url. 192 * The |enable_dyncode_syscalls| flag indicates whether or not the nexe 193 * will be able to use dynamic code system calls (e.g., mmap with PROT_EXEC). 194 * The |enable_exception_handling| flag indicates whether or not the nexe 195 * will be able to use hardware exception handling. 196 * The |enable_crash_throttling| flag indicates whether or not crashes of 197 * the nexe contribute to crash throttling statisics and whether nexe starts 198 * are throttled by crash throttling. 199 */ 200 void LaunchSelLdr([in] PP_Instance instance, 201 [in] PP_Bool main_service_runtime, 202 [in] str_t alleged_url, 203 [in] PP_Bool uses_irt, 204 [in] PP_Bool uses_ppapi, 205 [in] PP_Bool uses_nonsfi_mode, 206 [in] PP_Bool enable_ppapi_dev, 207 [in] PP_Bool enable_dyncode_syscalls, 208 [in] PP_Bool enable_exception_handling, 209 [in] PP_Bool enable_crash_throttling, 210 [in] PPP_ManifestService manifest_service_interface, 211 [inout] mem_t manifest_service_user_data, 212 [out] mem_t imc_handle, 213 [in] PP_CompletionCallback callback); 214 215 /* This function starts the IPC proxy so the nexe can communicate with the 216 * browser. 217 */ 218 PP_Bool StartPpapiProxy(PP_Instance instance); 219 220 /* On POSIX systems, this function returns the file descriptor of 221 * /dev/urandom. On non-POSIX systems, this function returns 0. 222 */ 223 int32_t UrandomFD(); 224 225 /* Whether the Pepper 3D interfaces should be disabled in the NaCl PPAPI 226 * proxy. This is so paranoid admins can effectively prevent untrusted shader 227 * code to be processed by the graphics stack. 228 */ 229 PP_Bool Are3DInterfacesDisabled(); 230 231 /* This is Windows-specific. This is a replacement for DuplicateHandle() for 232 * use inside the Windows sandbox. Note that we provide this via dependency 233 * injection only to avoid the linkage problems that occur because the NaCl 234 * plugin is built as a separate DLL/DSO 235 * (see http://code.google.com/p/chromium/issues/detail?id=114439#c8). 236 */ 237 int32_t BrokerDuplicateHandle([in] PP_FileHandle source_handle, 238 [in] uint32_t process_id, 239 [out] PP_FileHandle target_handle, 240 [in] uint32_t desired_access, 241 [in] uint32_t options); 242 243 /* Returns a read-only file descriptor for a url for pnacl translator tools, 244 * or an invalid handle on failure. 245 */ 246 PP_FileHandle GetReadonlyPnaclFd([in] str_t url); 247 248 /* This creates a temporary file that will be deleted by the time 249 * the last handle is closed (or earlier on POSIX systems), and 250 * returns a posix handle to that temporary file. 251 */ 252 PP_FileHandle CreateTemporaryFile([in] PP_Instance instance); 253 254 /* Return the number of processors in the system as reported by the OS */ 255 int32_t GetNumberOfProcessors(); 256 257 /* Return whether the non-SFI mode is enabled. */ 258 PP_Bool IsNonSFIModeEnabled(); 259 260 /* Create a temporary file, which will be deleted by the time the 261 * last handle is closed (or earlier on POSIX systems), to use for 262 * the nexe with the cache information given by |pexe_url|, 263 * |abi_version|, |opt_level|, and |headers|. If the nexe is already present 264 * in the cache, |is_hit| is set to PP_TRUE and the contents of the nexe will 265 * be copied into the temporary file. Otherwise |is_hit| is set to PP_FALSE 266 * and the temporary file will be writeable. Currently the implementation is 267 * a stub, which always sets is_hit to false and calls the implementation of 268 * CreateTemporaryFile. In a subsequent CL it will call into the browser 269 * which will remember the association between the cache key and the fd, and 270 * copy the nexe into the cache after the translation finishes. 271 */ 272 int32_t GetNexeFd([in] PP_Instance instance, 273 [in] str_t pexe_url, 274 [in] uint32_t abi_version, 275 [in] uint32_t opt_level, 276 [in] str_t headers, 277 [in] str_t extra_flags, 278 [out] PP_Bool is_hit, 279 [out] PP_FileHandle nexe_handle, 280 [in] PP_CompletionCallback callback); 281 282 /* Report to the browser that translation of the pexe for |instance| 283 * has finished, or aborted with an error. If |success| is true, the 284 * browser may then store the translation in the cache. The renderer 285 * must first have called GetNexeFd for the same instance. (The browser is 286 * not guaranteed to store the nexe even if |success| is true; if there is 287 * an error on the browser side, or the file is too big for the cache, or 288 * the browser is in incognito mode, no notification will be delivered to 289 * the plugin.) 290 */ 291 void ReportTranslationFinished([in] PP_Instance instance, 292 [in] PP_Bool success, 293 [in] int32_t opt_level, 294 [in] int64_t pexe_size, 295 [in] int64_t compile_time_us, 296 [in] int64_t total_time_us); 297 298 /* Dispatch a progress event on the DOM element where the given instance is 299 * embedded. 300 */ 301 void DispatchEvent([in] PP_Instance instance, 302 [in] PP_NaClEventType event_type, 303 [in] str_t resource_url, 304 [in] PP_Bool length_is_computable, 305 [in] uint64_t loaded_bytes, 306 [in] uint64_t total_bytes); 307 308 /* Report that the nexe loaded successfully. */ 309 void ReportLoadSuccess([in] PP_Instance instance, 310 [in] str_t url, 311 [in] uint64_t loaded_bytes, 312 [in] uint64_t total_bytes); 313 314 /* Report an error that occured while attempting to load a nexe. */ 315 void ReportLoadError([in] PP_Instance instance, 316 [in] PP_NaClError error, 317 [in] str_t error_message); 318 319 /* Reports that loading a nexe was aborted. */ 320 void ReportLoadAbort([in] PP_Instance instance); 321 322 /* Reports that the nexe has crashed. */ 323 void NexeDidCrash([in] PP_Instance instance, 324 [in] str_t crash_log); 325 326 /* Performs internal setup when an instance is created. */ 327 void InstanceCreated([in] PP_Instance instance); 328 329 /* Performs internal cleanup when an instance is destroyed. */ 330 void InstanceDestroyed([in] PP_Instance instance); 331 332 /* Return true if the NaCl debug stub is enabled and the app loaded from 333 * alleged_nmf_url will be attached to a debugger. 334 */ 335 PP_Bool NaClDebugEnabledForURL([in] str_t alleged_nmf_url); 336 337 /* Returns the kind of SFI sandbox implemented by NaCl on this 338 * platform. 339 */ 340 str_t GetSandboxArch(); 341 342 /* Logs the message to the console. */ 343 void LogToConsole([in] PP_Instance instance, 344 [in] str_t message); 345 346 /* Returns the NaCl readiness status for this instance. */ 347 PP_NaClReadyState GetNaClReadyState([in] PP_Instance instance); 348 349 /* Returns the exit status of the plugin process. */ 350 int32_t GetExitStatus([in] PP_Instance instance); 351 352 /* Sets the exit status of the plugin process. */ 353 void SetExitStatus([in] PP_Instance instance, 354 [in] int32_t exit_status); 355 356 /* Logs the message via VLOG. */ 357 void Vlog([in] str_t message); 358 359 /* Initializes internal state for a NaCl plugin. */ 360 void InitializePlugin([in] PP_Instance instance, 361 [in] uint32_t argc, 362 [in, size_as=argc] str_t[] argn, 363 [in, size_as=argv] str_t[] argv); 364 365 /* Returns the size of the nexe. */ 366 int64_t GetNexeSize([in] PP_Instance instance); 367 368 /* Requests the NaCl manifest specified in the plugin arguments. */ 369 void RequestNaClManifest([in] PP_Instance instance, 370 [in] PP_CompletionCallback callback); 371 372 PP_Var GetManifestBaseURL([in] PP_Instance instance); 373 374 /* Processes the NaCl manifest once it's been retrieved. 375 * TODO(teravest): Move the rest of the supporting logic out of the trusted 376 * plugin. 377 */ 378 void ProcessNaClManifest([in] PP_Instance instance, 379 [in] str_t program_url); 380 381 PP_Bool DevInterfacesEnabled([in] PP_Instance instance); 382 383 PP_Bool GetManifestProgramURL([in] PP_Instance instance, 384 [out] PP_Var full_url, 385 [out] PP_PNaClOptions pnacl_options, 386 [out] PP_Bool uses_nonsfi_mode); 387 388 PP_Bool ManifestResolveKey([in] PP_Instance instance, 389 [in] PP_Bool helper_process, 390 [in] str_t key, 391 [out] PP_Var full_url, 392 [out] PP_PNaClOptions pnacl_options); 393 394 /* Returns the filenames for the llc and ld tools, parsing that information 395 * from the file given in |filename|. 396 */ 397 PP_Bool GetPnaclResourceInfo([in] PP_Instance instance, 398 [in] str_t filename, 399 [out] PP_Var llc_tool_name, 400 [out] PP_Var ld_tool_name); 401 402 // PP_Var string of attributes describing the CPU features supported 403 // by the current architecture. The string is a comma-delimited list 404 // of attributes supported by LLVM in its -mattr= option: 405 // http://llvm.org/docs/CommandGuide/llc.html#cmdoption-mattr 406 PP_Var GetCpuFeatureAttrs(); 407 408 /* Posts a message to the JavaScript object for the given instance. 409 * This method may be called on any thread. 410 */ 411 void PostMessageToJavaScript([in] PP_Instance instance, 412 [in] str_t message); 413 414 /* Downloads the .nexe file at the given URL to a file, and sets |file_info| 415 * to information for a handle to a file containing its contents. 416 * If metadata for identity-based validation caching is available 417 * then it sets token information in |file_info| (otherwise left untouched). 418 */ 419 void DownloadNexe([in] PP_Instance instance, 420 [in] str_t url, 421 [out] PP_NaClFileInfo file_info, 422 [in] PP_CompletionCallback callback); 423 424 /* Downloads a non-nexe file specified in the manifest, and sets |file_info| 425 * to corresponding information about the file. */ 426 void DownloadFile([in] PP_Instance instance, 427 [in] str_t url, 428 [out] PP_NaClFileInfo file_info, 429 [in] PP_CompletionCallback callback); 430 431 /* Reports the status of sel_ldr for UMA reporting. 432 * |max_status| has to be provided because the implementation of this 433 * interface can't access the NaClErrorCode enum. 434 */ 435 void ReportSelLdrStatus([in] PP_Instance instance, 436 [in] int32_t load_status, 437 [in] int32_t max_status); 438 439 /* Logs time taken by an operation to UMA histograms. 440 * This function is safe to call on any thread. 441 */ 442 void LogTranslateTime([in] str_t histogram_name, 443 [in] int64_t time_us); 444 }; 445
