Updating trunk VERSION from 2139.0 to 2140.0
[chromium-blink-merge.git] / ppapi / api / private / ppb_nacl_private.idl
blobcb5cc4e06a55f87208e8f1fa871fbdb67293ca87
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 */
6 /* This file contains NaCl private interfaces. This interface is not versioned
7 * and is for internal Chrome use. It may change without notice. */
9 label Chrome {
10 M25 = 1.0
13 #inline c
14 #include "ppapi/c/private/pp_file_handle.h"
15 #include "ppapi/c/private/ppb_instance_private.h"
16 #endinl
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.
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,
102 /* If you add a code, read the enum comment above on how to update
103 histograms. */
104 PP_NACL_ERROR_MAX
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
118 enum PP_UrlSchemeType {
119 PP_SCHEME_CHROME_EXTENSION,
120 PP_SCHEME_DATA,
121 PP_SCHEME_OTHER
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
136 struct PP_PNaClOptions {
137 PP_Bool translate;
138 PP_Bool is_debug;
139 int32_t opt_level;
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);
146 /* Corresponds to NaClFileInfo in
147 * native_client/src/trusted/validator/nacl_file_info.h */
148 struct PP_NaClFileInfo {
149 PP_FileHandle handle;
151 /* See NaClFileToken comment in nacl_file_info.h */
152 uint64_t token_lo;
153 uint64_t token_hi;
156 /* PPB_NaCl_Private */
157 interface 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.
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);
194 /* This function starts the IPC proxy so the nexe can communicate with the
195 * browser.
197 PP_Bool StartPpapiProxy(PP_Instance instance);
199 /* On POSIX systems, this function returns the file descriptor of
200 * /dev/urandom. On non-POSIX systems, this function returns 0.
202 int32_t UrandomFD();
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.
208 PP_Bool Are3DInterfacesDisabled();
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).
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);
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.
225 void GetReadExecPnaclFd([in] str_t url,
226 [out] PP_NaClFileInfo out_file_info);
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.
232 PP_FileHandle CreateTemporaryFile([in] PP_Instance instance);
234 /* Return the number of processors in the system as reported by the OS */
235 int32_t GetNumberOfProcessors();
237 /* Return whether the non-SFI mode is enabled. */
238 PP_Bool IsNonSFIModeEnabled();
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.)
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);
255 /* Dispatch a progress event on the DOM element where the given instance is
256 * embedded.
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);
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);
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);
275 /* Reports that loading a nexe was aborted. */
276 void ReportLoadAbort([in] PP_Instance instance);
278 /* Reports that the nexe has crashed. */
279 void NexeDidCrash([in] PP_Instance instance);
281 /* Performs internal setup when an instance is created. */
282 void InstanceCreated([in] PP_Instance instance);
284 /* Performs internal cleanup when an instance is destroyed. */
285 void InstanceDestroyed([in] PP_Instance instance);
287 /* Return true if the NaCl debug stub is enabled and the app loaded from
288 * alleged_nmf_url will be attached to a debugger.
290 PP_Bool NaClDebugEnabledForURL([in] str_t alleged_nmf_url);
292 /* Returns the kind of SFI sandbox implemented by NaCl on this
293 * platform.
295 str_t GetSandboxArch();
297 /* Logs the message to the console. */
298 void LogToConsole([in] PP_Instance instance,
299 [in] str_t message);
301 /* Returns the NaCl readiness status for this instance. */
302 PP_NaClReadyState GetNaClReadyState([in] PP_Instance instance);
304 /* Logs the message via VLOG. */
305 void Vlog([in] str_t message);
307 /* Initializes internal state for a NaCl plugin. */
308 void InitializePlugin([in] PP_Instance instance,
309 [in] uint32_t argc,
310 [in, size_as=argc] str_t[] argn,
311 [in, size_as=argv] str_t[] argv);
313 /* Returns the size of the nexe. */
314 int64_t GetNexeSize([in] PP_Instance instance);
316 /* Requests the NaCl manifest specified in the plugin arguments. */
317 void RequestNaClManifest([in] PP_Instance instance,
318 [in] PP_CompletionCallback callback);
320 PP_Var GetManifestBaseURL([in] PP_Instance instance);
322 /* Processes the NaCl manifest once it's been retrieved.
323 * TODO(teravest): Move the rest of the supporting logic out of the trusted
324 * plugin.
326 void ProcessNaClManifest([in] PP_Instance instance,
327 [in] str_t program_url);
329 PP_Bool DevInterfacesEnabled([in] PP_Instance instance);
331 PP_Bool GetManifestProgramURL([in] PP_Instance instance,
332 [out] PP_Var full_url,
333 [out] PP_PNaClOptions pnacl_options,
334 [out] PP_Bool uses_nonsfi_mode);
336 /* Returns the filenames for the llc and ld tools. */
337 PP_Bool GetPnaclResourceInfo([in] PP_Instance instance,
338 [out] PP_Var llc_tool_name,
339 [out] PP_Var ld_tool_name);
341 // PP_Var string of attributes describing the CPU features supported
342 // by the current architecture. The string is a comma-delimited list
343 // of attributes supported by LLVM in its -mattr= option:
344 // http://llvm.org/docs/CommandGuide/llc.html#cmdoption-mattr
345 PP_Var GetCpuFeatureAttrs();
347 /* Posts a message to the JavaScript object for the given instance.
348 * This method may be called on any thread.
350 void PostMessageToJavaScript([in] PP_Instance instance,
351 [in] str_t message);
353 /* Downloads the .nexe file at the given URL to a file, and sets |file_info|
354 * to information for a handle to a file containing its contents.
355 * If metadata for identity-based validation caching is available
356 * then it sets token information in |file_info| (otherwise left untouched).
358 void DownloadNexe([in] PP_Instance instance,
359 [in] str_t url,
360 [out] PP_NaClFileInfo file_info,
361 [in] PP_CompletionCallback callback);
363 /* Reports the status of sel_ldr for UMA reporting.
364 * |max_status| has to be provided because the implementation of this
365 * interface can't access the NaClErrorCode enum.
367 void ReportSelLdrStatus([in] PP_Instance instance,
368 [in] int32_t load_status,
369 [in] int32_t max_status);
371 /* Logs time taken by an operation to UMA histograms.
372 * This function is safe to call on any thread.
374 void LogTranslateTime([in] str_t histogram_name,
375 [in] int64_t time_us);
377 /* Opens a manifest entry for the given instance. If this is for a helper
378 * process, we consult our internal pnacl.json instead of the user-supplied
379 * NMF.
380 * Fails for files which require PNaCl translation.
382 void OpenManifestEntry([in] PP_Instance instance,
383 [in] PP_Bool is_helper_process,
384 [in] str_t key,
385 [out] PP_NaClFileInfo file_info,
386 [in] PP_CompletionCallback callback);
388 /* Sets the start time for PNaCl downloading and translation to the current
389 * time.
391 void SetPNaClStartTime([in] PP_Instance instance);
393 /* Downloads and streams a pexe file for PNaCl translation.
394 * Fetches the content at |pexe_url| for the given instance and opt_level.
395 * If a translated cached nexe is already available, |cache_hit_handle|
396 * is set and |cache_hit_callback| is called.
397 * Otherwise, |stream_callback| is called repeatedly with blocks of data
398 * as they are received. |stream_finished_callback| is called after all
399 * data has been received and dispatched to |stream_callback|.
401 void StreamPexe([in] PP_Instance instance,
402 [in] str_t pexe_url,
403 [in] int32_t opt_level,
404 [in] PPP_PexeStreamHandler stream_handler,
405 [inout] mem_t stream_handler_user_data);