auto import from //depot/cupcake/@135843
diff --git a/docs/jni-tips.html b/docs/jni-tips.html
new file mode 100644
index 0000000..e2c3b85
--- /dev/null
+++ b/docs/jni-tips.html
@@ -0,0 +1,512 @@
+<html>
+ <head>
+ <title>Android JNI Tips</title>
+ <link rel=stylesheet href="android.css">
+ </head>
+
+ <body>
+ <h1><a name="JNI_Tips"></a>Android JNI Tips</h1>
+<p>
+</p><p>
+</p><ul>
+<li> <a href="#What_s_JNI_">What's JNI?</a>
+</li>
+<li> <a href="#JavaVM_and_JNIEnv">JavaVM and JNIEnv</a>
+
+</li>
+<li> <a href="#jclassID_jmethodID_and_jfieldID">jclassID, jmethodID, and jfieldID</a>
+</li>
+<li> <a href="#local_vs_global_references">Local vs. Global References</a>
+</li>
+<li> <a href="#UTF_8_and_UTF_16_strings">UTF-8 and UTF-16 Strings</a>
+</li>
+<li> <a href="#Arrays">Primitive Arrays</a>
+</li>
+<li> <a href="#RegionCalls">Region Calls</a>
+</li>
+<li> <a href="#Exceptions">Exceptions</a>
+</li>
+
+<li> <a href="#Extended_checking">Extended Checking</a>
+</li>
+<li> <a href="#Native_Libraries">Native Libraries</a>
+</li>
+<li> <a href="#64bit">64-bit Considerations</a>
+</li>
+
+<li> <a href="#Unsupported">Unsupported Features</a>
+</ul>
+<p>
+<noautolink>
+</noautolink></p><p>
+</p><h2><a name="What_s_JNI_"> </a> What's JNI? </h2>
+<p>
+
+JNI is the Java Native Interface. It defines a way for code written in the
+Java programming language to interact with native
+code, e.g. functions written in C/C++. It's VM-neutral, has support for loading code from
+dynamic shared libraries, and while cumbersome at times is reasonably efficient.
+</p><p>
+You really should read through the
+<a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html">JNI spec for J2SE 1.6</a>
+to get a sense for how JNI works and what features are available. Some
+aspects of the interface aren't immediately obvious on
+first reading, so you may find the next few sections handy.
+The more detailed <i>JNI Programmer's Guide and Specification</i> can be found
+<a href="http://java.sun.com/docs/books/jni/html/jniTOC.html">here</a>.
+</p><p>
+</p><p>
+</p><h2><a name="JavaVM_and_JNIEnv"> </a> JavaVM and JNIEnv </h2>
+<p>
+JNI defines two key data structures, "JavaVM" and "JNIEnv". Both of these are essentially
+pointers to pointers to function tables. (In the C++ version, it's a class whose sole member
+is a pointer to a function table.) The JavaVM provides the "invocation interface" functions,
+which allow you to create and destroy the VM. In theory you can have multiple VMs per process,
+but Android's VMs only allow one.
+</p><p>
+The JNIEnv provides most of the JNI functions. Your native functions all receive a JNIEnv as
+the first argument.
+</p><p>
+
+On some VMs, the JNIEnv is used for thread-local storage. For this reason, <strong>you cannot share a JNIEnv between threads</strong>.
+If a piece of code has no other way to get its JNIEnv, you should share
+the JavaVM, and use JavaVM->GetEnv to discover the thread's JNIEnv.
+</p><p>
+The C and C++ declarations of JNIEnv and JavaVM are different. "jni.h" provides different typedefs
+depending on whether it's included into ".c" or ".cpp". For this reason it's a bad idea to
+include JNIEnv arguments in header files included by both languages. (Put another way: if your
+header file requires "#ifdef __cplusplus", you may have to do some extra work if anything in
+that header refers to JNIEnv.)
+</p><p>
+</p><p>
+</p><h2><a name="jclassID_jmethodID_and_jfieldID"> jclassID, jmethodID, and jfieldID </a></h2>
+<p>
+If you want to access an object's field from native code, you would do the following:
+</p><p>
+</p><ul>
+<li> Get the class object reference for the class with <code>FindClass</code>
+</li>
+<li> Get the field ID for the field with <code>GetFieldID</code>
+</li>
+<li> Get the contents of the field with something appropriate, e.g.
+<code>GetIntField</code>
+</li>
+</ul>
+<p>
+Similarly, to call a method, you'd first get a class object reference and then a method ID. The IDs are often just
+pointers to internal VM data structures. Looking them up may require several string
+comparisons, but once you have them the actual call to get the field or invoke the method
+is very quick.
+</p><p>
+If performance is important, it's useful to look the values up once and cache the results
+in your native code. Because we are limiting ourselves to one VM per process, it's reasonable
+to store this data in a static local structure.
+</p><p>
+The class references, field IDs, and method IDs are guaranteed valid until the class is unloaded. Classes
+are only unloaded if all classes associated with a ClassLoader can be garbage collected,
+which is rare but will not be impossible in our system. The jclassID
+is a class reference and <strong>must be protected</strong> with a call
+to <code>NewGlobalRef</code> (see the next section).
+</p><p>
+If you would like to cache the IDs when a class is loaded, and automatically re-cache them
+if the class is ever unloaded and reloaded, the correct way to initialize
+the IDs is to add a piece of code that looks like this to the appropriate class:
+</p><p>
+
+</p><pre> /*
+ * We use a class initializer to allow the native code to cache some
+ * field offsets.
+ */
+
+ /*
+ * A native function that looks up and caches interesting
+ * class/field/method IDs for this class. Returns false on failure.
+ */
+ native private static boolean nativeClassInit();
+
+ /*
+ * Invoke the native initializer when the class is loaded.
+ */
+ static {
+ if (!nativeClassInit())
+ throw new RuntimeException("native init failed");
+ }
+</pre>
+<p>
+Create a nativeClassInit method in your C/C++ code that performs the ID lookups. The code
+will be executed once, when the class is initialized. If the class is ever unloaded and
+then reloaded, it will be executed again. (See the implementation of java.io.FileDescriptor
+for an example in our source tree.)
+</p><p>
+</p><p>
+</p><p>
+</p><h2><a name="local_vs_global_references"> Local vs. Global References </a></h2>
+<p>
+Every object that JNI returns is a "local reference". This means that it's valid for the
+duration of the current native method in the current thread.
+<strong>Even if the object itself continues to live on after the native method returns, the reference is not valid.</strong>
+This applies to all sub-classes of jobject, including jclass and jarray.
+(Dalvik VM will warn you about this when -Xcheck:jni is enabled.)
+</p><p>
+
+If you want to hold on to a reference for a longer period, you must use a "global" reference.
+The <code>NewGlobalRef</code> function takes the local reference as
+an argument and returns a global one:
+
+<p><pre>jobject* localRef = [...];
+jobject* globalRef;
+globalRef = env->NewGlobalRef(localRef);
+</pre>
+
+The global reference is guaranteed to be valid until you call
+<code>DeleteGlobalRef</code>.
+</p><p>
+All JNI methods accept both local and global references as arguments.
+</p><p>
+Programmers are required to "not excessively allocate" local references. In practical terms this means
+that if you're creating large numbers of local references, perhaps while running through an array of
+Objects, you should free them manually with
+<code>DeleteLocalRef</code> instead of letting JNI do it for you. The
+VM is only required to reserve slots for
+16 local references, so if you need more than that you should either delete as you go or use
+<code>EnsureLocalCapacity</code> to reserve more.
+</p><p>
+Note: method and field IDs are just 32-bit identifiers, not object
+references, and should not be passed to <code>NewGlobalRef</code>. The raw data
+pointers returned by functions like <code>GetStringUTFChars</code>
+and <code>GetByteArrayElements</code> are also not objects.
+</p><p>
+One unusual case deserves separate mention. If you attach a native
+thread to the VM with AttachCurrentThread, the code you are running will
+never "return" to the VM until the thread detaches from the VM. Any local
+references you create will have to be deleted manually unless the thread
+is about to exit or detach.
+</p><p>
+</p><p>
+</p><p>
+</p><h2><a name="UTF_8_and_UTF_16_strings"> </a> UTF-8 and UTF-16 Strings </h2>
+<p>
+The Java programming language uses UTF-16. For convenience, JNI provides methods that work with "modified UTF-8" encoding
+as well. (Some VMs use the modified UTF-8 internally to store strings; ours do not.) The
+modified encoding only supports the 8- and 16-bit forms, and stores ASCII NUL values in a 16-bit encoding.
+The nice thing about it is that you can count on having C-style zero-terminated strings,
+suitable for use with standard libc string functions. The down side is that you cannot pass
+arbitrary UTF-8 data into the VM and expect it to work correctly.
+</p><p>
+It's usually best to operate with UTF-16 strings. With our current VMs, the
+<code>GetStringChars</code> method
+does not require a copy, whereas <code>GetStringUTFChars</code> requires a malloc and a UTF conversion. Note that
+<strong>UTF-16 strings are not zero-terminated</strong>, and \u0000 is allowed,
+so you need to hang on to the string length as well as
+the string pointer.
+
+</p><p>
+<strong>Don't forget to Release the strings you Get</strong>. The string functions return <code>jchar*</code> or <code>jbyte*</code>, which
+are pointers to primitive types rather than local references. They are
+guaranteed valid until Release is called, which means they are not
+released when the native method returns.
+</p><p>
+</p><p>
+
+
+</p><h2><a name="Arrays"> </a> Primitive Arrays </h2>
+<p>
+JNI provides functions for accessing the contents of array objects.
+While arrays of objects must be accessed one entry at a time, arrays of
+primitives can be read and written directly as if they were declared in C.
+</p><p>
+To make the interface as efficient as possible without constraining
+the VM implementation,
+the <code>Get<PrimitiveType>ArrayElements</code> family of calls
+allows the VM to either return a pointer to the actual elements, or
+allocate some memory and make a copy. Either way, the raw pointer returned
+is guaranteed to be valid until the corresponding <code>Release</code> call
+is issued (which implies that, if the data wasn't copied, the array object
+will be pinned down and can't be relocated as part of compacting the heap).
+<strong>You must Release every array you Get.</strong> Also, if the Get
+call fails, you must ensure that your code doesn't try to Release a NULL
+pointer later.
+</p><p>
+You can determine whether or not the data was copied by passing in a
+non-NULL pointer for the <code>isCopy</code> argument. This is rarely
+useful.
+</p><p>
+The <code>Release</code> call takes a <code>mode</code> argument that can
+have one of three values. The actions performed by the VM depend upon
+whether it returned a pointer to the actual data or a copy of it:
+<ul>
+ <li><code>0</code>
+ <ul>
+ <li>Actual: the array object is un-pinned.
+ <li>Copy: data is copied back. The buffer with the copy is freed.
+ </ul>
+ <li><code>JNI_COMMIT</code>
+ <ul>
+ <li>Actual: does nothing.
+ <li>Copy: data is copied back. The buffer with the copy
+ <strong>is not freed</strong>.
+ </ul>
+ <li><code>JNI_ABORT</code>
+ <ul>
+ <li>Actual: the array object is un-pinned. Earlier
+ writes are <strong>not</strong> aborted.
+ <li>Copy: the buffer with the copy is freed; any changes to it are lost.
+ </ul>
+</ul>
+</p><p>
+One reason for checking the <code>isCopy</code> flag is to know if
+you need to call <code>Release</code> with <code>JNI_COMMIT</code>
+after making changes to an array -- if you're alternating between making
+changes and executing code that uses the contents of the array, you may be
+able to
+skip the no-op commit. Another possible reason for checking the flag is for
+efficient handling of <code>JNI_ABORT</code>. For example, you might want
+to get an array, modify it in place, pass pieces to other functions, and
+then discard the changes. If you know that JNI is making a new copy for
+you, there's no need to create another "editable" copy. If JNI is passing
+you the original, then you do need to make your own copy.
+</p><p>
+Some have asserted that you can skip the <code>Release</code> call if
+<code>*isCopy</code> is false. This is not the case. If no copy buffer was
+allocated, then the original memory must be pinned down and can't be moved by
+the garbage collector.
+</p><p>
+Also note that the <code>JNI_COMMIT</code> flag does NOT release the array,
+and you will need to call <code>Release</code> again with a different flag
+eventually.
+</p><p>
+</p><p>
+
+
+</p><h2><a name="RegionCalls"> Region Calls </a></h2>
+
+<p>
+There is an alternative to calls like <code>Get<Type>ArrayElements</code>
+and <code>GetStringChars</code> that may be very helpful when all you want
+to do is copy data in or out. Consider the following:
+<pre>
+ jbyte* data = env->GetByteArrayElements(array, NULL);
+ if (data != NULL) {
+ memcpy(buffer, data, len);
+ env->ReleaseByteArrayElements(array, data, JNI_ABORT);
+ }
+</pre>
+<p>
+This grabs the array, copies the first <code>len</code> byte
+elements out of it, and then releases the array. Depending upon the VM
+policies the <code>Get</code> call will either pin or copy the array contents.
+We copy the data (for perhaps a second time), then call Release; in this case
+we use <code>JNI_ABORT</code> so there's no chance of a third copy.
+</p><p>
+We can accomplish the same thing with this:
+<pre>
+ env->GetByteArrayRegion(array, 0, len, buffer);
+</pre>
+</p><p>
+This accomplishes the same thing, with several advantages:
+<ul>
+ <li>Requires one JNI call instead of 3, reducing overhead.
+ <li>Doesn't require pinning or extra data copies.
+ <li>Reduces the risk of programmer error -- no need to match up
+ <code>Get</code> and <code>Release</code> calls.
+</ul>
+</p><p>
+Similarly, you can use the <code>Set<Type>ArrayRegion</code> call
+to copy data into an array, and <code>GetStringRegion</code> or
+<code>GetStringUTFRegion</code> to copy characters out of a
+<code>String</code>.
+
+
+</p><h2><a name="Exceptions"> Exceptions </a></h2>
+<p>
+<strong>You may not call most JNI functions while an exception is pending.</strong>
+Your code is expected to notice the exception (via the function's return value,
+<code>ExceptionCheck()</code>, or <code>ExceptionOccurred()</code>) and return,
+or clear the exception and handle it.
+</p><p>
+The only JNI functions that you are allowed to call while an exception is
+pending are:
+<font size="-1"><ul>
+ <li>DeleteGlobalRef
+ <li>DeleteLocalRef
+ <li>DeleteWeakGlobalRef
+ <li>ExceptionCheck
+ <li>ExceptionClear
+ <li>ExceptionDescribe
+ <li>ExceptionOccurred
+ <li>MonitorExit
+ <li>PopLocalFrame
+ <li>PushLocalFrame
+ <li>Release<PrimitiveType>ArrayElements
+ <li>ReleasePrimitiveArrayCritical
+ <li>ReleaseStringChars
+ <li>ReleaseStringCritical
+ <li>ReleaseStringUTFChars
+</ul></font>
+</p><p>
+Note that exceptions thrown by interpreted code do not "leap over" native code,
+and C++ exceptions thrown by native code are not handled by Dalvik.
+The JNI <code>Throw</code> and <code>ThrowNew</code> instructions just
+set an exception pointer in the current thread. Upon returning to the VM from
+native code, the exception will be noted and handled appropriately.
+</p><p>
+Native code can "catch" an exception by calling <code>ExceptionCheck</code> or
+<code>ExceptionOccurred</code>, and clear it with
+<code>ExceptionClear</code>. As usual,
+discarding exceptions without handling them can lead to problems.
+</p><p>
+There are no built-in functions for manipulating the Throwable object
+itself, so if you want to (say) get the exception string you will need to
+find the Throwable class, look up the method ID for
+<code>getMessage "()Ljava/lang/String;"</code>, invoke it, and if the result
+is non-NULL use <code>GetStringUTFChars</code> to get something you can
+hand to printf or a LOG macro.
+
+</p><p>
+</p><p>
+</p><h2><a name="Extended_checking"> Extended Checking </a></h2>
+<p>
+JNI does very little error checking. Calling <code>SetFieldInt</code>
+on an Object field will succeed, even if the field is marked
+<code>private</code> and <code>final</code>. The
+goal is to minimize the overhead on the assumption that, if you've written it in native code,
+you probably did it for performance reasons.
+</p><p>
+Some VMs support extended checking with the "<code>-Xcheck:jni</code>" flag. If the flag is set, the VM
+puts a different table of functions into the JavaVM and JNIEnv pointers. These functions do
+an extended series of checks before calling the standard implementation.
+
+</p><p>
+Some things that may be verified:
+</p><p>
+</p>
+<ul>
+<li> Check for null pointers where not allowed.
+<li>
+<li> Verify argument type correctness (jclass is a class object,
+jfieldID points to field data, jstring is a java.lang.String).
+</li>
+<li> Field type correctness, e.g. don't store a HashMap in a String field.
+</li>
+<li> Check to see if an exception is pending on calls where pending exceptions are not legal.
+</li>
+<li> Check for calls to inappropriate functions between Critical get/release calls.
+</li>
+<li> Check that JNIEnv structs aren't being shared between threads.
+
+</li>
+<li> Make sure local references aren't used outside their allowed lifespan.
+</li>
+<li> UTF-8 strings contain valid "modified UTF-8" data.
+</li>
+</ul>
+<p>Accessibility of methods and fields (i.e. public vs. private) is not
+checked.
+<p>
+The Dalvik VM supports the <code>-Xcheck:jni</code> flag. For a
+description of how to enable it for Android apps, see
+<a href="embedded-vm-control.html">Controlling the Embedded VM</a>.
+It's currently enabled by default in the Android emulator and on
+"engineering" device builds.
+
+</p><p>
+JNI checks can be modified with the <code>-Xjniopts</code> command-line
+flag. Currently supported values include:
+</p>
+<blockquote><dl>
+<dt>forcecopy
+<dd>When set, any function that can return a copy of the original data
+(array of primitive values, UTF-16 chars) will always do so. The buffers
+are over-allocated and surrounded with a guard pattern to help identify
+code writing outside the buffer, and the contents are erased before the
+storage is freed to trip up code that uses the data after calling Release.
+<dt>warnonly
+<dd>By default, JNI "warnings" cause the VM to abort. With this flag
+it continues on.
+</dl></blockquote>
+
+
+</p><p>
+</p><h2><a name="Native_Libraries"> Native Libraries </a></h2>
+<p>
+You can load native code from shared libraries with the standard
+<code>System.loadLibrary()</code> call. The
+preferred way to get at your native code is:
+</p><p>
+</p><ul>
+<li> Call <code>System.loadLibrary()</code> from a static class initializer. (See the earlier example, where one is used to call nativeClassInit().) The argument is the "undecorated" library name, e.g. to load "libfubar.so" you would pass in "fubar".
+
+</li>
+<li> Provide a native function: <code><strong>jint JNI_OnLoad(JavaVM* vm, void* reserved)</strong></code>
+</li>
+<li>In <code>JNI_OnLoad</code>, register all of your native methods. You
+should declare
+the methods "static" so the names don't take up space in the symbol table
+on the device.
+</li>
+</ul>
+<p>
+The <code>JNI_OnLoad</code> function should look something like this if
+written in C:
+</p><blockquote><pre>jint JNI_OnLoad(JavaVM* vm, void* reserved)
+{
+ JNIEnv* env;
+ if ((*vm)->GetEnv(vm, (void**) &env, JNI_VERSION_1_4) != JNI_OK)
+ return -1;
+
+ /* get class with (*env)->FindClass */
+ /* register methods with (*env)->RegisterNatives */
+
+ return JNI_VERSION_1_4;
+}
+</pre></blockquote>
+</p><p>
+You can also call <code>System.load()</code> with the full path name of the
+shared library. For Android apps, you can get the full path to the
+application's private data storage area from the context object.
+</p><p>
+Dalvik does support "discovery" of native methods that are named in a
+specific way (see <a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp615">
+ the JNI spec</a> for details), but this is a less desirable
+approach. It requires more space in the shared object symbol table,
+loading is slower because it requires string searches through all of the
+loaded shared libraries, and if a method signature is wrong you won't know
+about it until the first time the method is actually used.
+</p><p>
+
+
+</p><h2><a name="64bit"> 64-bit Considerations </a></h2>
+
+<p>
+Android is currently expected to run on 32-bit platforms. In theory it
+could be built for a 64-bit system, but that is not a goal at this time.
+For the most part this isn't something that you will need to worry about
+when interacting with native code,
+but it becomes significant if you plan to store pointers to native
+structures in integer fields in an object. To support architectures
+that use 64-bit pointers, <strong>you need to stash your native pointers in a
+<code>long</code> field rather than an <code>int</code></strong>.
+
+
+</p><h2><a name="Unsupported"> Unsupported Features </a></h2>
+<p>All JNI 1.6 features are supported, with the following exceptions:
+<ul>
+ <li><code>DefineClass</code> is not implemented. Dalvik does not use
+ Java bytecodes or class files, so passing in binary class data
+ doesn't work. Translation facilities may be added in a future
+ version of the VM.</li>
+ <li><code>NewWeakGlobalRef</code> and <code>DeleteWeakGlobalRef</code>
+ are not implemented. The
+ VM supports weak references, but not JNI "weak global" references.
+ These will be supported in a future release.</li>
+ <li><code>GetObjectRefType</code> (new in 1.6) is implemented but not fully
+ functional -- it can't always tell the difference between "local" and
+ "global" references.</li>
+</ul>
+
+</p>
+
+<address>Copyright © 2008 The Android Open Source Project</address>
+
+ </body>
+</html>