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 9label 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 */ 25enum 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. */ 108enum 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 118enum PP_UrlSchemeType { 119 PP_SCHEME_CHROME_EXTENSION, 120 PP_SCHEME_DATA, 121 PP_SCHEME_OTHER 122}; 123 124enum 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 136struct 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(). */ 143typedef void PP_OpenResourceCompletionCallback([inout] mem_t user_data, 144 [in] PP_FileHandle file_handle); 145 146/* Corresponds to NaClFileInfo in 147 * native_client/src/trusted/validator/nacl_file_info.h */ 148struct PP_NaClFileInfo { 149 PP_FileHandle handle; 150 151 /* See NaClFileToken comment in nacl_file_info.h */ 152 uint64_t token_lo; 153 uint64_t token_hi; 154}; 155 156/* PPB_NaCl_Private */ 157interface PPB_NaCl_Private { 158 /* Launches NaCl's sel_ldr process. Returns PP_EXTERNAL_PLUGIN_OK on success 159 * and writes a NaClHandle to imc_handle. Returns PP_EXTERNAL_PLUGIN_FAILED on 160 * failure. The |enable_ppapi_dev| parameter controls whether GetInterface 161 * returns 'Dev' interfaces to the NaCl plugin. The |uses_ppapi| flag 162 * indicates that the nexe run by sel_ldr will use the PPAPI APIs. 163 * This implies that LaunchSelLdr is run from the main thread. If a nexe 164 * does not need PPAPI, then it can run off the main thread. 165 * The |nexe_file_info| is currently used only in non-SFI mode. It is the 166 * file handle for the main nexe file, which should be initially loaded. 167 * LaunchSelLdr takes the ownership of the file handle. 168 * The |uses_irt| flag indicates whether the IRT should be loaded in this 169 * NaCl process. This is true for ABI stable nexes. 170 * The |uses_nonsfi_mode| flag indicates whether or not nonsfi-mode should 171 * be used with the binary pointed by the url. 172 * The |enable_dyncode_syscalls| flag indicates whether or not the nexe 173 * will be able to use dynamic code system calls (e.g., mmap with PROT_EXEC). 174 * The |enable_exception_handling| flag indicates whether or not the nexe 175 * will be able to use hardware exception handling. 176 * The |enable_crash_throttling| flag indicates whether or not crashes of 177 * the nexe contribute to crash throttling statisics and whether nexe starts 178 * are throttled by crash throttling. 179 */ 180 void LaunchSelLdr([in] PP_Instance instance, 181 [in] PP_Bool main_service_runtime, 182 [in] str_t alleged_url, 183 [in] PP_NaClFileInfo nexe_file_info, 184 [in] PP_Bool uses_irt, 185 [in] PP_Bool uses_ppapi, 186 [in] PP_Bool uses_nonsfi_mode, 187 [in] PP_Bool enable_ppapi_dev, 188 [in] PP_Bool enable_dyncode_syscalls, 189 [in] PP_Bool enable_exception_handling, 190 [in] PP_Bool enable_crash_throttling, 191 [out] mem_t imc_handle, 192 [in] PP_CompletionCallback callback); 193 194 /* This function starts the IPC proxy so the nexe can communicate with the 195 * browser. 196 */ 197 PP_Bool StartPpapiProxy(PP_Instance instance); 198 199 /* On POSIX systems, this function returns the file descriptor of 200 * /dev/urandom. On non-POSIX systems, this function returns 0. 201 */ 202 int32_t UrandomFD(); 203 204 /* Whether the Pepper 3D interfaces should be disabled in the NaCl PPAPI 205 * proxy. This is so paranoid admins can effectively prevent untrusted shader 206 * code to be processed by the graphics stack. 207 */ 208 PP_Bool Are3DInterfacesDisabled(); 209 210 /* This is Windows-specific. This is a replacement for DuplicateHandle() for 211 * use inside the Windows sandbox. Note that we provide this via dependency 212 * injection only to avoid the linkage problems that occur because the NaCl 213 * plugin is built as a separate DLL/DSO 214 * (see http://code.google.com/p/chromium/issues/detail?id=114439#c8). 215 */ 216 int32_t BrokerDuplicateHandle([in] PP_FileHandle source_handle, 217 [in] uint32_t process_id, 218 [out] PP_FileHandle target_handle, 219 [in] uint32_t desired_access, 220 [in] uint32_t options); 221 222 /* Returns a read-only (but executable) file descriptor / file info for 223 * a url for pnacl translator tools. Returns an invalid handle on failure. 224 */ 225 void GetReadExecPnaclFd([in] str_t url, 226 [out] PP_NaClFileInfo out_file_info); 227 228 /* This creates a temporary file that will be deleted by the time 229 * the last handle is closed (or earlier on POSIX systems), and 230 * returns a posix handle to that temporary file. 231 */ 232 PP_FileHandle CreateTemporaryFile([in] PP_Instance instance); 233 234 /* Return the number of processors in the system as reported by the OS */ 235 int32_t GetNumberOfProcessors(); 236 237 /* Return whether the non-SFI mode is enabled. */ 238 PP_Bool IsNonSFIModeEnabled(); 239 240 /* Report to the browser that translation of the pexe for |instance| 241 * has finished, or aborted with an error. If |success| is true, the 242 * browser may then store the translation in the cache. The renderer 243 * must first have called GetNexeFd for the same instance. (The browser is 244 * not guaranteed to store the nexe even if |success| is true; if there is 245 * an error on the browser side, or the file is too big for the cache, or 246 * the browser is in incognito mode, no notification will be delivered to 247 * the plugin.) 248 */ 249 void ReportTranslationFinished([in] PP_Instance instance, 250 [in] PP_Bool success, 251 [in] int32_t opt_level, 252 [in] int64_t pexe_size, 253 [in] int64_t compile_time_us); 254 255 /* Dispatch a progress event on the DOM element where the given instance is 256 * embedded. 257 */ 258 void DispatchEvent([in] PP_Instance instance, 259 [in] PP_NaClEventType event_type, 260 [in] str_t resource_url, 261 [in] PP_Bool length_is_computable, 262 [in] uint64_t loaded_bytes, 263 [in] uint64_t total_bytes); 264 265 /* Report that the nexe loaded successfully. */ 266 void ReportLoadSuccess([in] PP_Instance instance, 267 [in] uint64_t loaded_bytes, 268 [in] uint64_t total_bytes); 269 270 /* Report an error that occured while attempting to load a nexe. */ 271 void ReportLoadError([in] PP_Instance instance, 272 [in] PP_NaClError error, 273 [in] str_t error_message); 274 275 /* Reports that loading a nexe was aborted. */ 276 void ReportLoadAbort([in] PP_Instance instance); 277 278 /* Performs internal setup when an instance is created. */ 279 void InstanceCreated([in] PP_Instance instance); 280 281 /* Performs internal cleanup when an instance is destroyed. */ 282 void InstanceDestroyed([in] PP_Instance instance); 283 284 /* Return true if the NaCl debug stub is enabled and the app loaded from 285 * alleged_nmf_url will be attached to a debugger. 286 */ 287 PP_Bool NaClDebugEnabledForURL([in] str_t alleged_nmf_url); 288 289 /* Returns the kind of SFI sandbox implemented by NaCl on this 290 * platform. 291 */ 292 str_t GetSandboxArch(); 293 294 /* Logs the message to the console. */ 295 void LogToConsole([in] PP_Instance instance, 296 [in] str_t message); 297 298 /* Returns the NaCl readiness status for this instance. */ 299 PP_NaClReadyState GetNaClReadyState([in] PP_Instance instance); 300 301 /* Logs the message via VLOG. */ 302 void Vlog([in] str_t message); 303 304 /* Initializes internal state for a NaCl plugin. */ 305 void InitializePlugin([in] PP_Instance instance, 306 [in] uint32_t argc, 307 [in, size_as=argc] str_t[] argn, 308 [in, size_as=argv] str_t[] argv); 309 310 /* Returns the size of the nexe. */ 311 int64_t GetNexeSize([in] PP_Instance instance); 312 313 /* Requests the NaCl manifest specified in the plugin arguments. */ 314 void RequestNaClManifest([in] PP_Instance instance, 315 [in] PP_CompletionCallback callback); 316 317 PP_Var GetManifestBaseURL([in] PP_Instance instance); 318 319 /* Processes the NaCl manifest once it's been retrieved. 320 * TODO(teravest): Move the rest of the supporting logic out of the trusted 321 * plugin. 322 */ 323 void ProcessNaClManifest([in] PP_Instance instance, 324 [in] str_t program_url); 325 326 PP_Bool DevInterfacesEnabled([in] PP_Instance instance); 327 328 PP_Bool GetManifestProgramURL([in] PP_Instance instance, 329 [out] PP_Var full_url, 330 [out] PP_PNaClOptions pnacl_options, 331 [out] PP_Bool uses_nonsfi_mode); 332 333 /* Returns the filenames for the llc and ld tools. */ 334 PP_Bool GetPnaclResourceInfo([in] PP_Instance instance, 335 [out] PP_Var llc_tool_name, 336 [out] PP_Var ld_tool_name); 337 338 // PP_Var string of attributes describing the CPU features supported 339 // by the current architecture. The string is a comma-delimited list 340 // of attributes supported by LLVM in its -mattr= option: 341 // http://llvm.org/docs/CommandGuide/llc.html#cmdoption-mattr 342 PP_Var GetCpuFeatureAttrs(); 343 344 /* Downloads the .nexe file at the given URL to a file, and sets |file_info| 345 * to information for a handle to a file containing its contents. 346 * If metadata for identity-based validation caching is available 347 * then it sets token information in |file_info| (otherwise left untouched). 348 */ 349 void DownloadNexe([in] PP_Instance instance, 350 [in] str_t url, 351 [out] PP_NaClFileInfo file_info, 352 [in] PP_CompletionCallback callback); 353 354 /* Reports the status of sel_ldr for UMA reporting. 355 * |max_status| has to be provided because the implementation of this 356 * interface can't access the NaClErrorCode enum. 357 */ 358 void ReportSelLdrStatus([in] PP_Instance instance, 359 [in] int32_t load_status, 360 [in] int32_t max_status); 361 362 /* Logs time taken by an operation to UMA histograms. 363 * This function is safe to call on any thread. 364 */ 365 void LogTranslateTime([in] str_t histogram_name, 366 [in] int64_t time_us); 367 368 /* Opens a manifest entry for the given instance. If this is for a helper 369 * process, we consult our internal pnacl.json instead of the user-supplied 370 * NMF. 371 * Fails for files which require PNaCl translation. 372 */ 373 void OpenManifestEntry([in] PP_Instance instance, 374 [in] PP_Bool is_helper_process, 375 [in] str_t key, 376 [out] PP_NaClFileInfo file_info, 377 [in] PP_CompletionCallback callback); 378 379 /* Sets the start time for PNaCl downloading and translation to the current 380 * time. 381 */ 382 void SetPNaClStartTime([in] PP_Instance instance); 383 384 /* Downloads and streams a pexe file for PNaCl translation. 385 * Fetches the content at |pexe_url| for the given instance and opt_level. 386 * If a translated cached nexe is already available, |cache_hit_handle| 387 * is set and |cache_hit_callback| is called. 388 * Otherwise, |stream_callback| is called repeatedly with blocks of data 389 * as they are received. |stream_finished_callback| is called after all 390 * data has been received and dispatched to |stream_callback|. 391 */ 392 void StreamPexe([in] PP_Instance instance, 393 [in] str_t pexe_url, 394 [in] int32_t opt_level, 395 [in] PPP_PexeStreamHandler stream_handler, 396 [inout] mem_t stream_handler_user_data); 397}; 398