auto import from //branches/cupcake/...@130745

3 files changed, 94 insertions, 21 deletions

diff --git a/docs/dalvik-bytecode.html b/docs/dalvik-bytecode.html
index 28e6fb48d..2bbffe6b0 100644
--- a/docs/dalvik-bytecode.html
+++ b/docs/dalvik-bytecode.html
@@ -24,15 +24,17 @@
     such as (but not limited to) the program counter and a reference to the
     <code>.dex</code> file that contains the method.
   </li>
-  <li>The <i>N</i> arguments to a method land in the last <i>N</i> registers
-    of the method's invocation frame.
-  </li>
   <li>Registers are 32 bits wide. Adjacent register pairs are used for 64-bit
     values.
   </li>
   <li>In terms of bitwise representation, <code>(Object) null == (int)
     0</code>.
   </li>
+  <li>The <i>N</i> arguments to a method land in the last <i>N</i> registers
+    of the method's invocation frame, in order. Wide arguments consume
+    two registers. Instance methods are passed a <code>this</code> reference
+    as their first argument.
+  </li>
   </ul>
 <li>The storage unit in the instruction stream is a 16-bit unsigned quantity.
   Some bits in some instructions are ignored / must-be-zero.
@@ -385,9 +387,13 @@
   <td>check-cast vAA, type@BBBB</td>
   <td><code>A:</code> reference-bearing register (8 bits)<br/>
     <code>B:</code> type index (16 bits)</td>
-  <td>Throw if the reference in the given register cannot be cast to the
-    indicated type. The type must be a reference type (not a primitive
-    type).</td>
+  <td>Throw a <code>ClassCastException</code> if the reference in the
+    given register cannot be cast to the indicated type.
+    <p><b>Note:</b> Since <code>A</code> must always be a reference
+    (and not a primitive value), this will necessarily fail at runtime
+    (that is, it will throw an exception) if <code>B</code> refers to a
+    primitive type.</p>
+  </td>
 </tr>
 <tr>
   <td>20 22c</td>
@@ -397,8 +403,11 @@
     <code>C:</code> type index (16 bits)</td>
   <td>Store in the given destination register <code>1</code>
     if the indicated reference is an instance of the given type,
-    or <code>0</code> if not. The type must be a
-    reference type (not a primitive type).</td>
+    or <code>0</code> if not.
+    <p><b>Note:</b> Since <code>B</code> must always be a reference
+    (and not a primitive value), this will always result
+    in <code>0</code> being stored if <code>C</code> refers to a primitive
+    type.</td>
 </tr>
 <tr>
   <td>21 12x</td>
@@ -462,7 +471,9 @@
   </td>
   <td>Fill the given array with the indicated data. The reference must be
     to an array of primitives, and the data table must match it in type and
-    size.
+    must contain no more elements than will fit in the array. That is,
+    the array may be larger than the table, and if so, only the initial
+    elements of the array are set, leaving the remainder alone.
   </td>
 </tr>
 <tr>
diff --git a/docs/embedded-vm-control.html b/docs/embedded-vm-control.html
index 7812041de..f90f0e596 100644
--- a/docs/embedded-vm-control.html
+++ b/docs/embedded-vm-control.html
@@ -111,21 +111,21 @@ optimization and verification).
 <p>There are two command-line flags that control the just-in-time
 verification and optimization,
 <code>-Xverify</code> and <code>-Xdexopt</code>.  The Android framework
-configures these based on the <code>dalvik.vm.verify-bytecode</code>
+configures these based on the <code>dalvik.vm.dexopt-flags</code>
 property.
 
 <p>If you set:
-<pre>adb shell setprop dalvik.vm.verify-bytecode true</pre>
+<pre>adb shell setprop dalvik.vm.dexopt-flags v=a,o=v</pre>
 then the framework will pass <code>-Xverify:all -Xdexopt:verified</code>
 to the VM.  This enables verification, and only optimizes classes that
 successfully verified.  This is the safest setting, and is the default.
-<p>If <code>dalvik.vm.verify-bytecode</code> is set to <code>false</code>,
-the framework passes <code>-Xverify:none -Xdexopt:verified</code> to disable
-verification.  (We could pass in <code>-Xdexopt:all</code>, but that wouldn't
-necessarily optimize more of the code, since classes that fail
-verification may well be skipped by the optimizer for the same reasons.)
-Classes will not be verified by <code>dexopt</code>, and unverified code
-will be loaded and executed.
+<p>You could also set <code>dalvik.vm.dexopt-flags</code> to <code>v=n</code>
+to have the framework pass <code>-Xverify:none -Xdexopt:verified</code>
+to disable verification.  (We could pass in <code>-Xdexopt:all</code> to
+allow optimization, but that wouldn't necessarily optimize more of the
+code, since classes that fail verification may well be skipped by the
+optimizer for the same reasons.)  Classes will not be verified by
+<code>dexopt</code>, and unverified code will be loaded and executed.
 
 <p>Enabling verification will make the <code>dexopt</code> command
 take significantly longer, because the verification process is fairly slow.
@@ -143,6 +143,10 @@ this property changes.  You can do this with:
 This removes the cached versions of the DEX files.  Remember to
 stop and restart the runtime (<code>adb shell stop; adb shell start</code>).
 
+<p>(Previous version of the runtime supported the boolean
+<code>dalvik.vm.verify-bytecode</code> property, but that has been
+superceded by <code>dalvik.vm.dexopt-flags</code>.)</p>
+
 
 <h2><a name="execmode">Execution Mode</a></h2>
 
diff --git a/docs/jni-tips.html b/docs/jni-tips.html
index 423bca9b4..e2c3b8509 100644
--- a/docs/jni-tips.html
+++ b/docs/jni-tips.html
@@ -22,6 +22,8 @@
 </li>
 <li> <a href="#Arrays">Primitive Arrays</a>
 </li>
+<li> <a href="#RegionCalls">Region Calls</a>
+</li>
 <li> <a href="#Exceptions">Exceptions</a>
 </li>
 
@@ -29,6 +31,8 @@
 </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>
@@ -219,7 +223,9 @@ 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>
+<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
@@ -272,6 +278,45 @@ eventually.
 </p><p>
 
 
+</p><h2><a name="RegionCalls"> Region Calls </a></h2>
+
+<p>
+There is an alternative to calls like <code>Get&lt;Type&gt;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&lt;Type&gt;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>
@@ -380,7 +425,7 @@ storage is freed to trip up code that uses the data after calling Release.
 it continues on.
 </dl></blockquote>
 
-</p><p>
+
 </p><p>
 </p><h2><a name="Native_Libraries"> Native Libraries </a></h2>
 <p>
@@ -422,7 +467,7 @@ 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 less a less desirable
+    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
@@ -430,6 +475,19 @@ 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>