Status

Under Consideration

Contributors

• Last modified: June 6, 2011
• Authors: Sandeep Akula (Adobe Systems), Vinod Menon (Adobe Systems)
• Contributors: Josh Aas (Mozilla Corporation)

Problem Summary

Currently there are no mechanisms available for browser plug-ins to add plug-in specific data into browser-generated crash reports. Additional information added by browser plug-ins will facilitate easier and faster troubleshooting of plug-ins. This necessitates browsers to provide interfaces through which plug-in can indicate to the browser, plug-in specific data that it needs browser to capture as part of crash dumps in case a crash occurs. The NPAPI doesn’t have any interfaces to send plug-in’s custom data along with crash dump when an unhandled exception occurs in the plug-in. To support this we are proposing an extension to the current API.

Current Proposal

Two new functions for registering and unregistering blocks of memory are added.

NPError NPN_ErrorReportingRegisterMemoryBlock(const char* key, 
                                              uint32_t flags,
                                              void* pMemBlock, 
                                              size_t sizeOfMemBlock);

Parameters:

• key: unique string identifying the memory block
• flags:
  • Future use, no flags defined now.
• pMemBlock: The starting address of the memory block.
• sizeOfMemBlock: The size of the memory block in bytes

Return value:

• NPERR_OUT_OF_MEMORY_ERROR: If the memory size exceeds the maximum size allowed
• NPERR_INVALID_PARAM: If the registration fails
• NPERR_NO_ERROR: If successful

Registered buffers must contain textual UTF8/ASCII data which is NULL terminated. Non-textual data can be encoded as text before it is placed in a registered buffer.

The browser will not read a registered buffer upon registration, thus there is no need to re-register after changing the contents of a registered buffer. The buffer will only be read from a crash handler. Registering memory address NULL (zero) will not be allowed, to avoid the issue in which a plugin might register the result of a malloc call without a NULL check.

If the API is called with a key that has already been registered, the new registration will replace the old one. Plugins can attempt to register multiple buffers.

Calling NPN_GetValue with new key NPNVmaxCrashMemoryBlockSize can be used to get the maximum amount of memory available for a plugin's block registration. This is not a per-block or per-instance limit, it is a per-plugin limit.

NPError NPN_ErrorReportingUnregisterMemoryBlock(const char* key); 

Parameters:

• key: key value which was used to register the memory block

Return value:

• NPERR_INVALID_PARAM: invalid memory key
• NPERR_GENERIC_ERROR: any generic error
• NPERR_NO_ERROR: memory successfully unregistered

Open Issues

• We need to check with browser vendor crash reporting teams to make sure we can handle arbitrary blocks of memory. Right now, for example, I think Mozilla is only set up to handle string annotations and I'm not sure what additional challenges random memory will pose.