docs/dex-format.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   2
   3 <html>
   4
   5 <head>
   6 <title>.dex &mdash; Dalvik Executable Format</title>
   7 <link rel=stylesheet href="dex-format.css">
   8 </head>
   9
  10 <body>
  11
  12 <h1 class="title"><code>.dex</code> &mdash; Dalvik Executable Format</h1>
  13 <p>Copyright &copy; 2007 The Android Open Source Project
  14
  15 <p>This document describes the layout and contents of <code>.dex</code>
  16 files, which are used to hold a set of class definitions and their associated
  17 adjunct data.</p>
  18
  19 <h1>Guide To Types</h1>
  20
  21 <table class="guide">
  22 <thead>
  23 <tr>
  24   <th>Name</th>
  25   <th>Description</th>
  26 </tr>
  27 </thead>
  28 <tbody>
  29 <tr>
  30   <td>byte</td>
  31   <td>8-bit signed int</td>
  32 </tr>
  33 <tr>
  34   <td>ubyte</td>
  35   <td>8-bit unsigned int</td>
  36 </tr>
  37 <tr>
  38   <td>short</td>
  39   <td>16-bit signed int, little-endian</td>
  40 </tr>
  41 <tr>
  42   <td>ushort</td>
  43   <td>16-bit unsigned int, little-endian</td>
  44 </tr>
  45 <tr>
  46   <td>int</td>
  47   <td>32-bit signed int, little-endian</td>
  48 </tr>
  49 <tr>
  50   <td>uint</td>
  51   <td>32-bit unsigned int, little-endian</td>
  52 </tr>
  53 <tr>
  54   <td>long</td>
  55   <td>64-bit signed int, little-endian</td>
  56 </tr>
  57 <tr>
  58   <td>ulong</td>
  59   <td>64-bit unsigned int, little-endian</td>
  60 </tr>
  61 <tr>
  62   <td>sleb128</td>
  63   <td>signed LEB128, variable-length (see below)</td>
  64 </tr>
  65 <tr>
  66   <td>uleb128</td>
  67   <td>unsigned LEB128, variable-length (see below)</td>
  68 </tr>
  69 <tr>
  70   <td>uleb128p1</td>
  71   <td>unsigned LEB128 plus <code>1</code>, variable-length (see below)</td>
  72 </tr>
  73 </tbody>
  74 </table>
  75
  76 <h3>LEB128</h3>
  77
  78 <p>LEB128 ("<b>L</b>ittle-<b>E</b>ndian <b>B</b>ase <b>128</b>") is a
  79 variable-length encoding for
  80 arbitrary signed or unsigned integer quantities. The format was
  81 borrowed from the <a href="http://dwarfstd.org/Dwarf3Std.php">DWARF3</a>
  82 specification. In a <code>.dex</code> file, LEB128 is only ever used to
  83 encode 32-bit quantities.</p>
  84
  85 <p>Each LEB128 encoded value consists of one to five
  86 bytes, which together represent a single 32-bit value. Each
  87 byte has its most significant bit set except for the final byte in the
  88 sequence, which has its most significant bit clear. The remaining
  89 seven bits of each byte are payload, with the least significant seven
  90 bits of the quantity in the first byte, the next seven in the second
  91 byte and so on. In the case of a signed LEB128 (<code>sleb128</code>),
  92 the most significant payload bit of the final byte in the sequence is
  93 sign-extended to produce the final value. In the unsigned case
  94 (<code>uleb128</code>), any bits not explicitly represented are
  95 interpreted as <code>0</code>.
  96
  97 <table class="leb128Bits">
  98 <thead>
  99 <tr><th colspan="16">Bitwise diagram of a two-byte LEB128 value</th></tr>
 100 <tr>
 101   <th colspan="8">First byte</td>
 102   <th colspan="8">Second byte</td>
 103 </tr>
 104 </thead>
 105 <tbody>
 106 <tr>
 107   <td class="start1"><code>1</code></td>
 108   <td>bit<sub>6</sub></td>
 109   <td>bit<sub>5</sub></td>
 110   <td>bit<sub>4</sub></td>
 111   <td>bit<sub>3</sub></td>
 112   <td>bit<sub>2</sub></td>
 113   <td>bit<sub>1</sub></td>
 114   <td>bit<sub>0</sub></td>
 115   <td class="start2"><code>0</code></td>
 116   <td>bit<sub>13</sub></td>
 117   <td>bit<sub>12</sub></td>
 118   <td>bit<sub>11</sub></td>
 119   <td>bit<sub>10</sub></td>
 120   <td>bit<sub>9</sub></td>
 121   <td>bit<sub>8</sub></td>
 122   <td class="end2">bit<sub>7</sub></td>
 123 </tr>
 124 </tbody>
 125 </table>
 126
 127 <p>The variant <code>uleb128p1</code> is used to represent a signed
 128 value, where the representation is of the value <i>plus one</i> encoded
 129 as a <code>uleb128</code>. This makes the encoding of <code>-1</code>
 130 (alternatively thought of as the unsigned value <code>0xffffffff</code>)
 131 &mdash; but no other negative number &mdash; a single byte, and is
 132 useful in exactly those cases where the represented number must either
 133 be non-negative or <code>-1</code> (or <code>0xffffffff</code>),
 134 and where no other negative values are allowed (or where large unsigned
 135 values are unlikely to be needed).</p>
 136
 137 <p>Here are some examples of the formats:</p>
 138
 139 <table class="leb128">
 140 <thead>
 141 <tr>
 142   <th>Encoded Sequence</th>
 143   <th>As <code>sleb128</code></th>
 144   <th>As <code>uleb128</code></th>
 145   <th>As <code>uleb128p1</code></th>
 146 </tr>
 147 </thead>
 148 <tbody>
 149   <tr><td>00</td><td>0</td><td>0</td><td>-1</td></tr>
 150   <tr><td>01</td><td>1</td><td>1</td><td>0</td></tr>
 151   <tr><td>7f</td><td>-1</td><td>127</td><td>126</td></tr>
 152   <tr><td>80 7f</td><td>-128</td><td>16256</td><td>16255</td></tr>
 153 </tbody>
 154 </table>
 155
 156 <h1>Overall File Layout</h1>
 157
 158 <table class="format">
 159 <thead>
 160 <tr>
 161   <th>Name</th>
 162   <th>Format</th>
 163   <th>Description</th>
 164 </tr>
 165 </thead>
 166 <tbody>
 167 <tr>
 168   <td>header</td>
 169   <td>header_item</td>
 170   <td>the header</td>
 171 </tr>
 172 <tr>
 173   <td>string_ids</td>
 174   <td>string_id_item[]</td>
 175   <td>string identifiers list. These are identifiers for all the strings
 176     used by this file, either for internal naming (e.g., type descriptors)
 177     or as constant objects referred to by code. This list must be sorted
 178     by string contents, using UTF-16 code point values (not in a
 179     locale-sensitive manner), and it must not contain any duplicate entries.
 180   </td>
 181 </tr>
 182 <tr>
 183   <td>type_ids</td>
 184   <td>type_id_item[]</td>
 185   <td>type identifiers list. These are identifiers for all types (classes,
 186     arrays, or primitive types) referred to by this file, whether defined
 187     in the file or not. This list must be sorted by <code>string_id</code>
 188     index, and it must not contain any duplicate entries.
 189   </td>
 190 </tr>
 191 <tr>
 192   <td>proto_ids</td>
 193   <td>proto_id_item[]</td>
 194   <td>method prototype identifiers list. These are identifiers for all
 195     prototypes referred to by this file. This list must be sorted in
 196     return-type (by <code>type_id</code> index) major order, and then
 197     by arguments (also by <code>type_id</code> index). The list must not
 198     contain any duplicate entries.
 199   </td>
 200 </tr>
 201 <tr>
 202   <td>field_ids</td>
 203   <td>field_id_item[]</td>
 204   <td>field identifiers list. These are identifiers for all fields
 205     referred to by this file, whether defined in the file or not. This
 206     list must be sorted, where the defining type (by <code>type_id</code>
 207     index) is the major order, field name (by <code>string_id</code> index)
 208     is the intermediate order, and type (by <code>type_id</code> index)
 209     is the minor order. The list must not contain any duplicate entries.
 210   </td>
 211 </tr>
 212 <tr>
 213   <td>method_ids</td>
 214   <td>method_id_item[]</td>
 215   <td>method identifiers list. These are identifiers for all methods
 216     referred to by this file, whether defined in the file or not. This
 217     list must be sorted, where the defining type (by <code>type_id</code>
 218     index) is the major order, method name (by <code>string_id</code>
 219     index) is the intermediate order, and method prototype (by
 220     <code>proto_id</code> index) is the minor order.  The list must not
 221     contain any duplicate entries.
 222   </td>
 223 </tr>
 224 <tr>
 225   <td>class_defs</td>
 226   <td>class_def_item[]</td>
 227   <td>class definitions list. The classes must be ordered such that a given
 228     class's superclass and implemented interfaces appear in the
 229     list earlier than the referring class. Furthermore, it is invalid for
 230     a definition for the same-named class to appear more than once in
 231     the list.
 232   </td>
 233 </tr>
 234 <tr>
 235   <td>data</td>
 236   <td>ubyte[]</td>
 237   <td>data area, containing all the support data for the tables listed above.
 238     Different items have different alignment requirements, and
 239     padding bytes are inserted before each item if necessary to achieve
 240     proper alignment.
 241   </td>
 242 </tr>
 243 <tr>
 244   <td>link_data</td>
 245   <td>ubyte[]</td>
 246   <td>data used in statically linked files. The format of the data in
 247     this section is left unspecified by this document.
 248     This section is empty in unlinked files, and runtime implementations
 249     may use it as they see fit.
 250   </td>
 251 </tr>
 252 </tbody>
 253 </table>
 254
 255 <h1>Bitfield, String, and Constant Definitions</h1>
 256
 257 <h2><code>DEX_FILE_MAGIC</code></h2>
 258 <h4>embedded in <code>header_item</code></h4>
 259
 260 <p>The constant array/string <code>DEX_FILE_MAGIC</code> is the list of
 261 bytes that must appear at the beginning of a <code>.dex</code> file
 262 in order for it to be recognized as such. The value intentionally
 263 contains a newline (<code>"\n"</code> or <code>0x0a</code>) and a
 264 null byte (<code>"\0"</code> or <code>0x00</code>) in order to help
 265 in the detection of certain forms of corruption. The value also
 266 encodes a format version number as three decimal digits, which is
 267 expected to increase monotonically over time as the format evolves.</p>
 268
 269 <pre>
 270 ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x35 0x00 }
 271                         = "dex\n035\0"
 272 </pre>
 273
 274 <p><b>Note:</b> At least a couple earlier versions of the format have
 275 been used in widely-available public software releases. For example,
 276 version <code>009</code> was used for the M3 releases of the
 277 Android platform (November&ndash;December 2007),
 278 and version <code>013</code> was used for the M5 releases of the Android
 279 platform (February&ndash;March 2008). In several respects, these earlier
 280 versions of the format differ significantly from the version described in this
 281 document.</p>
 282
 283 <h2><code>ENDIAN_CONSTANT</code> and <code>REVERSE_ENDIAN_CONSTANT</code></h2>
 284 <h4>embedded in <code>header_item</code></h4>
 285
 286 <p>The constant <code>ENDIAN_CONSTANT</code> is used to indicate the
 287 endianness of the file in which it is found. Although the standard
 288 <code>.dex</code> format is little-endian, implementations may choose
 289 to perform byte-swapping. Should an implementation come across a
 290 header whose <code>endian_tag</code> is <code>REVERSE_ENDIAN_CONSTANT</code>
 291 instead of <code>ENDIAN_CONSTANT</code>, it would know that the file
 292 has been byte-swapped from the expected form.</p>
 293
 294 <pre>
 295 uint ENDIAN_CONSTANT = 0x12345678;
 296 uint REVERSE_ENDIAN_CONSTANT = 0x78563412;
 297 </pre>
 298
 299 <h2><code>NO_INDEX</code></h2>
 300 <h4>embedded in <code>class_def_item</code> and
 301 <code>debug_info_item</code></h4>
 302
 303 <p>The constant <code>NO_INDEX</code> is used to indicate that
 304 an index value is absent.</p>
 305
 306 <p><b>Note:</b> This value isn't defined to be
 307 <code>0</code>, because that is in fact typically a valid index.</p>
 308
 309 <p><b>Also Note:</b> The chosen value for <code>NO_INDEX</code> is
 310 representable as a single byte in the <code>uleb128p1</code> encoding.</p>
 311
 312 <pre>
 313 uint NO_INDEX = 0xffffffff;    // == -1 if treated as a signed int
 314 </pre>
 315
 316 <h2><code>access_flags</code> Definitions</h2>
 317 <h4>embedded in <code>class_def_item</code>,
 318 <code>encoded_field</code>, <code>encoded_method</code>, and
 319 <code>InnerClass</code></h4>
 320
 321 <p>Bitfields of these flags are used to indicate the accessibility and
 322 overall properties of classes and class members.</p>
 323
 324 <table class="accessFlags">
 325 <thead>
 326 <tr>
 327   <th>Name</th>
 328   <th>Value</th>
 329   <th>For Classes (and <code>InnerClass</code> annotations)</th>
 330   <th>For Fields</th>
 331   <th>For Methods</th>
 332 </tr>
 333 </thead>
 334 <tbody>
 335 <tr>
 336   <td>ACC_PUBLIC</td>
 337   <td>0x1</td>
 338   <td><code>public</code>: visible everywhere</td>
 339   <td><code>public</code>: visible everywhere</td>
 340   <td><code>public</code>: visible everywhere</td>
 341 </tr>
 342 <tr>
 343   <td>ACC_PRIVATE</td>
 344   <td>0x2</td>
 345   <td><super>*</super>
 346     <code>private</code>: only visible to defining class
 347   </td>
 348   <td><code>private</code>: only visible to defining class</td>
 349   <td><code>private</code>: only visible to defining class</td>
 350 </tr>
 351 <tr>
 352   <td>ACC_PROTECTED</td>
 353   <td>0x4</td>
 354   <td><super>*</super>
 355     <code>protected</code>: visible to package and subclasses
 356   </td>
 357   <td><code>protected</code>: visible to package and subclasses</td>
 358   <td><code>protected</code>: visible to package and subclasses</td>
 359 </tr>
 360 <tr>
 361   <td>ACC_STATIC</td>
 362   <td>0x8</td>
 363   <td><super>*</super>
 364     <code>static</code>: is not constructed with an outer
 365     <code>this</code> reference</td>
 366   <td><code>static</code>: global to defining class</td>
 367   <td><code>static</code>: does not take a <code>this</code> argument</td>
 368 </tr>
 369 <tr>
 370   <td>ACC_FINAL</td>
 371   <td>0x10</td>
 372   <td><code>final</code>: not subclassable</td>
 373   <td><code>final</code>: immutable after construction</td>
 374   <td><code>final</code>: not overridable</td>
 375 </tr>
 376 <tr>
 377   <td>ACC_SYNCHRONIZED</td>
 378   <td>0x20</td>
 379   <td>&nbsp;</td>
 380   <td>&nbsp;</td>
 381   <td><code>synchronized</code>: associated lock automatically acquired
 382     around call to this method. <b>Note:</b> This is only valid to set when
 383     <code>ACC_NATIVE</code> is also set.</td>
 384 </tr>
 385 <tr>
 386   <td>ACC_VOLATILE</td>
 387   <td>0x40</td>
 388   <td>&nbsp;</td>
 389   <td><code>volatile</code>: special access rules to help with thread
 390     safety</td>
 391   <td>&nbsp;</td>
 392 </tr>
 393 <tr>
 394   <td>ACC_BRIDGE</td>
 395   <td>0x40</td>
 396   <td>&nbsp;</td>
 397   <td>&nbsp;</td>
 398   <td>bridge method, added automatically by compiler as a type-safe
 399     bridge</td>
 400 </tr>
 401 <tr>
 402   <td>ACC_TRANSIENT</td>
 403   <td>0x80</td>
 404   <td>&nbsp;</td>
 405   <td><code>transient</code>: not to be saved by default serialization</td>
 406   <td>&nbsp;</td>
 407 </tr>
 408 <tr>
 409   <td>ACC_VARARGS</td>
 410   <td>0x80</td>
 411   <td>&nbsp;</td>
 412   <td>&nbsp;</td>
 413   <td>last argument should be treated as a "rest" argument by compiler</td>
 414 </tr>
 415 <tr>
 416   <td>ACC_NATIVE</td>
 417   <td>0x100</td>
 418   <td>&nbsp;</td>
 419   <td>&nbsp;</td>
 420   <td><code>native</code>: implemented in native code</td>
 421 </tr>
 422 <tr>
 423   <td>ACC_INTERFACE</td>
 424   <td>0x200</td>
 425   <td><code>interface</code>: multiply-implementable abstract class</td>
 426   <td>&nbsp;</td>
 427   <td>&nbsp;</td>
 428 </tr>
 429 <tr>
 430   <td>ACC_ABSTRACT</td>
 431   <td>0x400</td>
 432   <td><code>abstract</code>: not directly instantiable</td>
 433   <td>&nbsp;</td>
 434   <td><code>abstract</code>: unimplemented by this class</td>
 435 </tr>
 436 <tr>
 437   <td>ACC_STRICT</td>
 438   <td>0x800</td>
 439   <td>&nbsp;</td>
 440   <td>&nbsp;</td>
 441   <td><code>strictfp</code>: strict rules for floating-point arithmetic</td>
 442 </tr>
 443 <tr>
 444   <td>ACC_SYNTHETIC</td>
 445   <td>0x1000</td>
 446   <td>not directly defined in source code</td>
 447   <td>not directly defined in source code</td>
 448   <td>not directly defined in source code</td>
 449 </tr>
 450 <tr>
 451   <td>ACC_ANNOTATION</td>
 452   <td>0x2000</td>
 453   <td>declared as an annotation class</td>
 454   <td>&nbsp;</td>
 455   <td>&nbsp;</td>
 456 </tr>
 457 <tr>
 458   <td>ACC_ENUM</td>
 459   <td>0x4000</td>
 460   <td>declared as an enumerated type</td>
 461   <td>declared as an enumerated value</td>
 462   <td>&nbsp;</td>
 463 </tr>
 464 <tr>
 465   <td><i>(unused)</i></td>
 466   <td>0x8000</td>
 467   <td>&nbsp;</td>
 468   <td>&nbsp;</td>
 469   <td>&nbsp;</td>
 470 </tr>
 471 <tr>
 472   <td>ACC_CONSTRUCTOR</td>
 473   <td>0x10000</td>
 474   <td>&nbsp;</td>
 475   <td>&nbsp;</td>
 476   <td>constructor method (class or instance initializer)</td>
 477 </tr>
 478 <tr>
 479   <td>ACC_DECLARED_<br/>SYNCHRONIZED</td>
 480   <td>0x20000</td>
 481   <td>&nbsp;</td>
 482   <td>&nbsp;</td>
 483   <td>declared <code>synchronized</code>. <b>Note:</b> This has no effect on
 484     execution (other than in reflection of this flag, per se).
 485   </td>
 486 </tr>
 487 </tbody>
 488 </table>
 489
 490 <p><super>*</super> Only allowed on for <code>InnerClass</code> annotations,
 491 and must not ever be on in a <code>class_def_item</code>.</p>
 492
 493 <h2>MUTF-8 (Modified UTF-8) Encoding</h2>
 494
 495 <p>As a concession to easier legacy support, the <code>.dex</code> format
 496 encodes its string data in a de facto standard modified UTF-8 form, hereafter
 497 referred to as MUTF-8. This form is identical to standard UTF-8, except:</p>
 498
 499 <ul>
 500   <li>Only the one-, two-, and three-byte encodings are used.</li>
 501   <li>Code points in the range <code>U+10000</code> &hellip;
 502     <code>U+10ffff</code> are encoded as a surrogate pair, each of
 503     which is represented as a three-byte encoded value.</li>
 504   <li>The code point <code>U+0000</code> is encoded in two-byte form.</li>
 505   <li>A plain null byte (value <code>0</code>) indicates the end of
 506     a string, as is the standard C language interpretation.</li>
 507 </ul>
 508
 509 <p>The first two items above can be summarized as: MUTF-8
 510 is an encoding format for UTF-16, instead of being a more direct
 511 encoding format for Unicode characters.</p>
 512
 513 <p>The final two items above make it simultaneously possible to include
 514 the code point <code>U+0000</code> in a string <i>and</i> still manipulate
 515 it as a C-style null-terminated string.</p>
 516
 517 <p>However, the special encoding of <code>U+0000</code> means that, unlike
 518 normal UTF-8, the result of calling the standard C function
 519 <code>strcmp()</code> on a pair of MUTF-8 strings does not always
 520 indicate the properly signed result of comparison of <i>unequal</i> strings.
 521 When ordering (not just equality) is a concern, the most straightforward
 522 way to compare MUTF-8 strings is to decode them character by character,
 523 and compare the decoded values. (However, more clever implementations are
 524 also possible.)</p>
 525
 526 <p>Please refer to <a href="http://unicode.org">The Unicode
 527 Standard</a> for further information about character encoding.
 528 MUTF-8 is actually closer to the (relatively less well-known) encoding
 529 <a href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8
 530 per se.</p>
 531
 532 <h2><code>encoded_value</code> Encoding</h2>
 533 <h4>embedded in <code>annotation_element</code> and
 534 <code>encoded_array_item</code></h4>
 535
 536 <p>An <code>encoded_value</code> is an encoded piece of (nearly)
 537 arbitrary hierarchically structured data. The encoding is meant to
 538 be both compact and straightforward to parse.</p>
 539
 540 <table class="format">
 541 <thead>
 542 <tr>
 543   <th>Name</th>
 544   <th>Format</th>
 545   <th>Description</th>
 546 </tr>
 547 </thead>
 548 <tbody>
 549 <tr>
 550   <td>(value_arg &lt;&lt; 5) | value_type</td>
 551   <td>ubyte</td>
 552   <td>byte indicating the type of the immediately subsequent
 553     <code>value</code> along
 554     with an optional clarifying argument in the high-order three bits.
 555     See below for the various <code>value</code> definitions.
 556     In most cases, <code>value_arg</code> encodes the length of
 557     the immediately-subsequent <code>value</code> in bytes, as
 558     <code>(size - 1)</code>, e.g., <code>0</code> means that
 559     the value requires one byte, and <code>7</code> means it requires
 560     eight bytes; however, there are exceptions as noted below.
 561   </td>
 562 </tr>
 563 <tr>
 564   <td>value</td>
 565   <td>ubyte[]</td>
 566   <td>bytes representing the value, variable in length and interpreted
 567     differently for different <code>value_type</code> bytes, though
 568     always little-endian. See the various value definitions below for
 569     details.
 570   </td>
 571 </tr>
 572 </tbody>
 573 </table>
 574
 575 <h3>Value Formats</h3>
 576
 577 <table class="encodedValue">
 578 <thead>
 579 <tr>
 580   <th>Type Name</th>
 581   <th><code>value_type</code></th>
 582   <th><code>value_arg</code> Format</th>
 583   <th><code>value</code> Format</th>
 584   <th>Description</th>
 585 </tr>
 586 </thead>
 587 <tbody>
 588 <tr>
 589   <td>VALUE_BYTE</td>
 590   <td>0x00</td>
 591   <td><i>(none; must be <code>0</code>)</i></td>
 592   <td>ubyte[1]</td>
 593   <td>signed one-byte integer value</td>
 594 </tr>
 595 <tr>
 596   <td>VALUE_SHORT</td>
 597   <td>0x02</td>
 598   <td>size - 1 (0&hellip;1)</td>
 599   <td>ubyte[size]</td>
 600   <td>signed two-byte integer value, sign-extended</td>
 601 </tr>
 602 <tr>
 603   <td>VALUE_CHAR</td>
 604   <td>0x03</td>
 605   <td>size - 1 (0&hellip;1)</td>
 606   <td>ubyte[size]</td>
 607   <td>unsigned two-byte integer value, zero-extended</td>
 608 </tr>
 609 <tr>
 610   <td>VALUE_INT</td>
 611   <td>0x04</td>
 612   <td>size - 1 (0&hellip;3)</td>
 613   <td>ubyte[size]</td>
 614   <td>signed four-byte integer value, sign-extended</td>
 615 </tr>
 616 <tr>
 617   <td>VALUE_LONG</td>
 618   <td>0x06</td>
 619   <td>size - 1 (0&hellip;7)</td>
 620   <td>ubyte[size]</td>
 621   <td>signed eight-byte integer value, sign-extended</td>
 622 </tr>
 623 <tr>
 624   <td>VALUE_FLOAT</td>
 625   <td>0x10</td>
 626   <td>size - 1 (0&hellip;3)</td>
 627   <td>ubyte[size]</td>
 628   <td>four-byte bit pattern, zero-extended <i>to the right</i>, and
 629     interpreted as an IEEE754 32-bit floating point value
 630   </td>
 631 </tr>
 632 <tr>
 633   <td>VALUE_DOUBLE</td>
 634   <td>0x11</td>
 635   <td>size - 1 (0&hellip;7)</td>
 636   <td>ubyte[size]</td>
 637   <td>eight-byte bit pattern, zero-extended <i>to the right</i>, and
 638     interpreted as an IEEE754 64-bit floating point value
 639   </td>
 640 </tr>
 641 <tr>
 642   <td>VALUE_STRING</td>
 643   <td>0x17</td>
 644   <td>size - 1 (0&hellip;3)</td>
 645   <td>ubyte[size]</td>
 646   <td>unsigned (zero-extended) four-byte integer value,
 647     interpreted as an index into
 648     the <code>string_ids</code> section and representing a string value
 649   </td>
 650 </tr>
 651 <tr>
 652   <td>VALUE_TYPE</td>
 653   <td>0x18</td>
 654   <td>size - 1 (0&hellip;3)</td>
 655   <td>ubyte[size]</td>
 656   <td>unsigned (zero-extended) four-byte integer value,
 657     interpreted as an index into
 658     the <code>type_ids</code> section and representing a reflective
 659     type/class value
 660   </td>
 661 </tr>
 662 <tr>
 663   <td>VALUE_FIELD</td>
 664   <td>0x19</td>
 665   <td>size - 1 (0&hellip;3)</td>
 666   <td>ubyte[size]</td>
 667   <td>unsigned (zero-extended) four-byte integer value,
 668     interpreted as an index into
 669     the <code>field_ids</code> section and representing a reflective
 670     field value
 671   </td>
 672 </tr>
 673 <tr>
 674   <td>VALUE_METHOD</td>
 675   <td>0x1a</td>
 676   <td>size - 1 (0&hellip;3)</td>
 677   <td>ubyte[size]</td>
 678   <td>unsigned (zero-extended) four-byte integer value,
 679     interpreted as an index into
 680     the <code>method_ids</code> section and representing a reflective
 681     method value
 682   </td>
 683 </tr>
 684 <tr>
 685   <td>VALUE_ENUM</td>
 686   <td>0x1b</td>
 687   <td>size - 1 (0&hellip;3)</td>
 688   <td>ubyte[size]</td>
 689   <td>unsigned (zero-extended) four-byte integer value,
 690     interpreted as an index into
 691     the <code>field_ids</code> section and representing the value of
 692     an enumerated type constant
 693   </td>
 694 </tr>
 695 <tr>
 696   <td>VALUE_ARRAY</td>
 697   <td>0x1c</td>
 698   <td><i>(none; must be <code>0</code>)</i></td>
 699   <td>encoded_array</td>
 700   <td>an array of values, in the format specified by
 701     "<code>encoded_array</code> Format" below. The size
 702     of the <code>value</code> is implicit in the encoding.
 703   </td>
 704 </tr>
 705 <tr>
 706   <td>VALUE_ANNOTATION</td>
 707   <td>0x1d</td>
 708   <td><i>(none; must be <code>0</code>)</i></td>
 709   <td>encoded_annotation</td>
 710   <td>a sub-annotation, in the format specified by
 711     "<code>encoded_annotation</code> Format" below. The size
 712     of the <code>value</code> is implicit in the encoding.
 713   </td>
 714 </tr>
 715 <tr>
 716   <td>VALUE_NULL</td>
 717   <td>0x1e</td>
 718   <td><i>(none; must be <code>0</code>)</i></td>
 719   <td><i>(none)</i></td>
 720   <td><code>null</code> reference value</td>
 721 </tr>
 722 <tr>
 723   <td>VALUE_BOOLEAN</td>
 724   <td>0x1f</td>
 725   <td>boolean (0&hellip;1)</td>
 726   <td><i>(none)</i></td>
 727   <td>one-bit value; <code>0</code> for <code>false</code> and
 728     <code>1</code> for <code>true</code>. The bit is represented in the
 729     <code>value_arg</code>.
 730   </td>
 731 </tr>
 732 </tbody>
 733 </table>
 734
 735 <h3><code>encoded_array</code> Format</h3>
 736
 737 <table class="format">
 738 <thead>
 739 <tr>
 740   <th>Name</th>
 741   <th>Format</th>
 742   <th>Description</th>
 743 </tr>
 744 </thead>
 745 <tbody>
 746 <tr>
 747   <td>size</td>
 748   <td>uleb128</td>
 749   <td>number of elements in the array</td>
 750 </tr>
 751 <tr>
 752   <td>values</td>
 753   <td>encoded_value[size]</td>
 754   <td>a series of <code>size</code> <code>encoded_value</code> byte
 755     sequences in the format specified by this section, concatenated
 756     sequentially.
 757   </td>
 758 </tr>
 759 </tbody>
 760 </table>
 761
 762 <h3><code>encoded_annotation</code> Format</h3>
 763
 764 <table class="format">
 765 <thead>
 766 <tr>
 767   <th>Name</th>
 768   <th>Format</th>
 769   <th>Description</th>
 770 </tr>
 771 </thead>
 772 <tbody>
 773 <tr>
 774   <td>type_idx</td>
 775   <td>uleb128</td>
 776   <td>type of the annotation. This must be a class (not array or primitive)
 777     type.
 778   </td>
 779 </tr>
 780 <tr>
 781   <td>size</td>
 782   <td>uleb128</td>
 783   <td>number of name-value mappings in this annotation</td>
 784 </tr>
 785 <tr>
 786   <td>elements</td>
 787   <td>annotation_element[size]</td>
 788   <td>elements of the annotataion, represented directly in-line (not as
 789     offsets). Elements must be sorted in increasing order by
 790     <code>string_id</code> index.
 791   </td>
 792 </tr>
 793 </tbody>
 794 </table>
 795
 796 <h3><code>annotation_element</code> Format</h3>
 797
 798 <table class="format">
 799 <thead>
 800 <tr>
 801   <th>Name</th>
 802   <th>Format</th>
 803   <th>Description</th>
 804 </tr>
 805 </thead>
 806 <tbody>
 807 <tr>
 808   <td>name_idx</td>
 809   <td>uleb128</td>
 810   <td>element name, represented as an index into the
 811     <code>string_ids</code> section. The string must conform to the
 812     syntax for <i>MemberName</i>, defined above.
 813   </td>
 814 </tr>
 815 <tr>
 816   <td>value</td>
 817   <td>encoded_value</td>
 818   <td>element value</td>
 819 </tr>
 820 </tbody>
 821 </table>
 822
 823 <h2>String Syntax</h2>
 824
 825 <p>There are several kinds of item in a <code>.dex</code> file which
 826 ultimately refer to a string. The following BNF-style definitions
 827 indicate the acceptable syntax for these strings.</p>
 828
 829 <h3><i>SimpleName</i></h3>
 830
 831 <p>A <i>SimpleName</i> is the basis for the syntax of the names of other
 832 things. The <code>.dex</code> format allows a fair amount of latitude
 833 here (much more than most common source languages). In brief, a simple
 834 name consists of any low-ASCII alphabetic character or digit, a few
 835 specific low-ASCII symbols, and most non-ASCII code points that are not
 836 control, space, or special characters. Note that surrogate code points
 837 (in the range <code>U+d800</code> &hellip; <code>U+dfff</code>) are not
 838 considered valid name characters, per se, but Unicode supplemental
 839 characters <i>are</i> valid (which are represented by the final
 840 alternative of the rule for <i>SimpleNameChar</i>), and they should be
 841 represented in a file as pairs of surrogate code points in the MUTF-8
 842 encoding.</p>
 843
 844 <table class="bnf">
 845   <tr><td colspan="2" class="def"><i>SimpleName</i> &rarr;</td></tr>
 846   <tr>
 847     <td/>
 848     <td><i>SimpleNameChar</i> (<i>SimpleNameChar</i>)*</td>
 849   </tr>
 850
 851   <tr><td colspan="2" class="def"><i>SimpleNameChar</i> &rarr;</td></tr>
 852   <tr>
 853     <td/>
 854     <td><code>'A'</code> &hellip; <code>'Z'</code></td>
 855   </tr>
 856   <tr>
 857     <td class="bar">|</td>
 858     <td><code>'a'</code> &hellip; <code>'z'</code></td>
 859   </tr>
 860   <tr>
 861     <td class="bar">|</td>
 862     <td><code>'0'</code> &hellip; <code>'9'</code></td>
 863   </tr>
 864   <tr>
 865     <td class="bar">|</td>
 866     <td><code>'$'</code></td>
 867   </tr>
 868   <tr>
 869     <td class="bar">|</td>
 870     <td><code>'-'</code></td>
 871   </tr>
 872   <tr>
 873     <td class="bar">|</td>
 874     <td><code>'_'</code></td>
 875   </tr>
 876   <tr>
 877     <td class="bar">|</td>
 878     <td><code>U+00a1</code> &hellip; <code>U+1fff</code></td>
 879   </tr>
 880   <tr>
 881     <td class="bar">|</td>
 882     <td><code>U+2010</code> &hellip; <code>U+2027</code></td>
 883   </tr>
 884   <tr>
 885     <td class="bar">|</td>
 886     <td><code>U+2030</code> &hellip; <code>U+d7ff</code></td>
 887   </tr>
 888   <tr>
 889     <td class="bar">|</td>
 890     <td><code>U+e000</code> &hellip; <code>U+ffef</code></td>
 891   </tr>
 892   <tr>
 893     <td class="bar">|</td>
 894     <td><code>U+10000</code> &hellip; <code>U+10ffff</code></td>
 895   </tr>
 896 </table>
 897
 898 <h3><i>MemberName</i></h3>
 899 <h4>used by <code>field_id_item</code> and <code>method_id_item</code></h4>
 900
 901 <p>A <i>MemberName</i> is the name of a member of a class, members being
 902 fields, methods, and inner classes.</p>
 903
 904 <table class="bnf">
 905   <tr><td colspan="2" class="def"><i>MemberName</i> &rarr;</td></tr>
 906   <tr>
 907     <td/>
 908     <td><i>SimpleName</i></td>
 909   </tr>
 910   <tr>
 911     <td class="bar">|</td>
 912     <td><code>'&lt;'</code> <i>SimpleName</i> <code>'&gt;'</code></td>
 913   </tr>
 914 </table>
 915
 916 <h3><i>FullClassName</i></h3>
 917
 918 <p>A <i>FullClassName</i> is a fully-qualified class name, including an
 919 optional package specifier followed by a required name.</p>
 920
 921 <table class="bnf">
 922   <tr><td colspan="2" class="def"><i>FullClassName</i> &rarr;</td></tr>
 923   <tr>
 924     <td/>
 925     <td><i>OptionalPackagePrefix</i> <i>SimpleName</i></td>
 926   </tr>
 927
 928   <tr><td colspan="2" class="def"><i>OptionalPackagePrefix</i> &rarr;</td></tr>
 929   <tr>
 930     <td/>
 931     <td>(<i>SimpleName</i> <code>'/'</code>)*</td>
 932   </tr>
 933 </table>
 934
 935 <h3><i>TypeDescriptor</i></h3>
 936 <h4>used by <code>type_id_item</code></h4>
 937
 938 <p>A <i>TypeDescriptor</i> is the representation of any type, including
 939 primitives, classes, arrays, and <code>void</code>. See below for
 940 the meaning of the various versions.</p>
 941
 942 <table class="bnf">
 943   <tr><td colspan="2" class="def"><i>TypeDescriptor</i> &rarr;</td></tr>
 944   <tr>
 945     <td/>
 946     <td><code>'V'</code></td>
 947   </tr>
 948   <tr>
 949     <td class="bar">|</td>
 950     <td><i>FieldTypeDescriptor</i></td>
 951   </tr>
 952
 953   <tr><td colspan="2" class="def"><i>FieldTypeDescriptor</i> &rarr;</td></tr>
 954   <tr>
 955     <td/>
 956     <td><i>NonArrayFieldTypeDescriptor</i></td>
 957   </tr>
 958   <tr>
 959     <td class="bar">|</td>
 960     <td>(<code>'['</code> * 1&hellip;255)
 961       <i>NonArrayFieldTypeDescriptor</i></td>
 962   </tr>
 963
 964   <tr>
 965     <td colspan="2" class="def"><i>NonArrayFieldTypeDescriptor</i>&rarr;</td>
 966   </tr>
 967   <tr>
 968     <td/>
 969     <td><code>'Z'</code></td>
 970   </tr>
 971   <tr>
 972     <td class="bar">|</td>
 973     <td><code>'B'</code></td>
 974   </tr>
 975   <tr>
 976     <td class="bar">|</td>
 977     <td><code>'S'</code></td>
 978   </tr>
 979   <tr>
 980     <td class="bar">|</td>
 981     <td><code>'C'</code></td>
 982   </tr>
 983   <tr>
 984     <td class="bar">|</td>
 985     <td><code>'I'</code></td>
 986   </tr>
 987   <tr>
 988     <td class="bar">|</td>
 989     <td><code>'J'</code></td>
 990   </tr>
 991   <tr>
 992     <td class="bar">|</td>
 993     <td><code>'F'</code></td>
 994   </tr>
 995   <tr>
 996     <td class="bar">|</td>
 997     <td><code>'D'</code></td>
 998   </tr>
 999   <tr>
1000     <td class="bar">|</td>
1001     <td><code>'L'</code> <i>FullClassName</i> <code>';'</code></td>
1002   </tr>
1003 </table>
1004
1005 <h3><i>ShortyDescriptor</i></h3>
1006 <h4>used by <code>proto_id_item</code></h4>
1007
1008 <p>A <i>ShortyDescriptor</i> is the short form representation of a method
1009 prototype, including return and parameter types, except that there is
1010 no distinction between various reference (class or array) types. Instead,
1011 all reference types are represented by a single <code>'L'</code> character.</p>
1012
1013 <table class="bnf">
1014   <tr><td colspan="2" class="def"><i>ShortyDescriptor</i> &rarr;</td></tr>
1015   <tr>
1016     <td/>
1017     <td><i>ShortyReturnType</i> (<i>ShortyFieldType</i>)*</td>
1018   </tr>
1019
1020   <tr><td colspan="2" class="def"><i>ShortyReturnType</i> &rarr;</td></tr>
1021   <tr>
1022     <td/>
1023     <td><code>'V'</code></td>
1024   </tr>
1025   <tr>
1026     <td class="bar">|</td>
1027     <td><i>ShortyFieldType</i></td>
1028   </tr>
1029
1030   <tr><td colspan="2" class="def"><i>ShortyFieldType</i> &rarr;</td></tr>
1031   <tr>
1032     <td/>
1033     <td><code>'Z'</code></td>
1034   </tr>
1035   <tr>
1036     <td class="bar">|</td>
1037     <td><code>'B'</code></td>
1038   </tr>
1039   <tr>
1040     <td class="bar">|</td>
1041     <td><code>'S'</code></td>
1042   </tr>
1043   <tr>
1044     <td class="bar">|</td>
1045     <td><code>'C'</code></td>
1046   </tr>
1047   <tr>
1048     <td class="bar">|</td>
1049     <td><code>'I'</code></td>
1050   </tr>
1051   <tr>
1052     <td class="bar">|</td>
1053     <td><code>'J'</code></td>
1054   </tr>
1055   <tr>
1056     <td class="bar">|</td>
1057     <td><code>'F'</code></td>
1058   </tr>
1059   <tr>
1060     <td class="bar">|</td>
1061     <td><code>'D'</code></td>
1062   </tr>
1063   <tr>
1064     <td class="bar">|</td>
1065     <td><code>'L'</code></td>
1066   </tr>
1067 </table>
1068
1069 <h2><i>TypeDescriptor</i> Semantics</h2>
1070
1071 <p>This is the meaning of each of the variants of <i>TypeDescriptor</i>.</p>
1072
1073 <table class="descriptor">
1074 <thead>
1075 <tr>
1076   <th>Syntax</th>
1077   <th>Meaning</th>
1078 </tr>
1079 </thead>
1080 <tbody>
1081 <tr>
1082   <td>V</td>
1083   <td><code>void</code>; only valid for return types</td>
1084 </tr>
1085 <tr>
1086   <td>Z</td>
1087   <td><code>boolean</code></td>
1088 </tr>
1089 <tr>
1090   <td>B</td>
1091   <td><code>byte</code></td>
1092 </tr>
1093 <tr>
1094   <td>S</td>
1095   <td><code>short</code></td>
1096 </tr>
1097 <tr>
1098   <td>C</td>
1099   <td><code>char</code></td>
1100 </tr>
1101 <tr>
1102   <td>I</td>
1103   <td><code>int</code></td>
1104 </tr>
1105 <tr>
1106   <td>J</td>
1107   <td><code>long</code></td>
1108 </tr>
1109 <tr>
1110   <td>F</td>
1111   <td><code>float</code></td>
1112 </tr>
1113 <tr>
1114   <td>D</td>
1115   <td><code>double</code></td>
1116 </tr>
1117 <tr>
1118   <td>L<i>fully/qualified/Name</i>;</td>
1119   <td>the class <code><i>fully.qualified.Name</i></code></td>
1120 </tr>
1121 <tr>
1122   <td>[<i>descriptor</i></td>
1123   <td>array of <code><i>descriptor</i></code>, usable recursively for
1124     arrays-of-arrays, though it is invalid to have more than 255
1125     dimensions.
1126   </td>
1127 </tr>
1128 </tbody>
1129 </table>
1130
1131 <h1>Items and Related Structures</h1>
1132
1133 <p>This section includes definitions for each of the top-level items that
1134 may appear in a <code>.dex</code> file.
1135
1136 <h2><code>header_item</code></h2>
1137 <h4>appears in the <code>header</code> section</h4>
1138 <h4>alignment: 4 bytes</h4>
1139
1140 <table class="format">
1141 <thead>
1142 <tr>
1143   <th>Name</th>
1144   <th>Format</th>
1145   <th>Description</th>
1146 </tr>
1147 </thead>
1148 <tbody>
1149 <tr>
1150   <td>magic</td>
1151   <td>ubyte[8] = DEX_FILE_MAGIC</td>
1152   <td>magic value. See discussion above under "<code>DEX_FILE_MAGIC</code>"
1153     for more details.
1154   </td>
1155 </tr>
1156 <tr>
1157   <td>checksum</td>
1158   <td>uint</td>
1159   <td>adler32 checksum of the rest of the file (everything but
1160     <code>magic</code> and this field); used to detect file corruption
1161   </td>
1162 </tr>
1163 <tr>
1164   <td>signature</td>
1165   <td>ubyte[20]</td>
1166   <td>SHA-1 signature (hash) of the rest of the file (everything but
1167     <code>magic</code>, <code>checksum</code>, and this field); used
1168     to uniquely identify files
1169   </td>
1170 </tr>
1171 <tr>
1172   <td>file_size</td>
1173   <td>uint</td>
1174   <td>size of the entire file (including the header), in bytes
1175 </tr>
1176 <tr>
1177   <td>header_size</td>
1178   <td>uint = 0x70</td>
1179   <td>size of the header (this entire section), in bytes. This allows for at
1180     least a limited amount of backwards/forwards compatibility without
1181     invalidating the format.
1182   </td>
1183 </tr>
1184 <tr>
1185   <td>endian_tag</td>
1186   <td>uint = ENDIAN_CONSTANT</td>
1187   <td>endianness tag. See discussion above under "<code>ENDIAN_CONSTANT</code>
1188     and <code>REVERSE_ENDIAN_CONSTANT</code>" for more details.
1189   </td>
1190 </tr>
1191 <tr>
1192   <td>link_size</td>
1193   <td>uint</td>
1194   <td>size of the link section, or <code>0</code> if this file isn't
1195     statically linked</td>
1196 </tr>
1197 <tr>
1198   <td>link_off</td>
1199   <td>uint</td>
1200   <td>offset from the start of the file to the link section, or
1201     <code>0</code> if <code>link_size == 0</code>. The offset, if non-zero,
1202     should be to an offset into the <code>link_data</code> section. The
1203     format of the data pointed at is left unspecified by this document;
1204     this header field (and the previous) are left as hooks for use by
1205     runtime implementations.
1206   </td>
1207 </tr>
1208 <tr>
1209   <td>map_off</td>
1210   <td>uint</td>
1211   <td>offset from the start of the file to the map item, or
1212     <code>0</code> if this file has no map. The offset, if non-zero,
1213     should be to an offset into the <code>data</code> section,
1214     and the data should be in the format specified by "<code>map_list</code>"
1215     below.
1216   </td>
1217 </tr>
1218 <tr>
1219   <td>string_ids_size</td>
1220   <td>uint</td>
1221   <td>count of strings in the string identifiers list</td>
1222 </tr>
1223 <tr>
1224   <td>string_ids_off</td>
1225   <td>uint</td>
1226   <td>offset from the start of the file to the string identifiers list, or
1227     <code>0</code> if <code>string_ids_size == 0</code> (admittedly a
1228     strange edge case). The offset, if non-zero,
1229     should be to the start of the <code>string_ids</code> section.
1230   </td>
1231 </tr>
1232 <tr>
1233   <td>type_ids_size</td>
1234   <td>uint</td>
1235   <td>count of elements in the type identifiers list</td>
1236 </tr>
1237 <tr>
1238   <td>type_ids_off</td>
1239   <td>uint</td>
1240   <td>offset from the start of the file to the type identifiers list, or
1241     <code>0</code> if <code>type_ids_size == 0</code> (admittedly a
1242     strange edge case). The offset, if non-zero,
1243     should be to the start of the <code>type_ids</code>
1244     section.
1245   </td>
1246 </tr>
1247 <tr>
1248   <td>proto_ids_size</td>
1249   <td>uint</td>
1250   <td>count of elements in the prototype identifiers list</td>
1251 </tr>
1252 <tr>
1253   <td>proto_ids_off</td>
1254   <td>uint</td>
1255   <td>offset from the start of the file to the prototype identifiers list, or
1256     <code>0</code> if <code>proto_ids_size == 0</code> (admittedly a
1257     strange edge case). The offset, if non-zero,
1258     should be to the start of the <code>proto_ids</code>
1259     section.
1260   </td>
1261 </tr>
1262 <tr>
1263   <td>field_ids_size</td>
1264   <td>uint</td>
1265   <td>count of elements in the field identifiers list</td>
1266 </tr>
1267 <tr>
1268   <td>field_ids_off</td>
1269   <td>uint</td>
1270   <td>offset from the start of the file to the field identifiers list, or
1271     <code>0</code> if <code>field_ids_size == 0</code>. The offset, if
1272     non-zero, should be to the start of the <code>field_ids</code>
1273     section.</td>
1274 </td>
1275 </tr>
1276 <tr>
1277   <td>method_ids_size</td>
1278   <td>uint</td>
1279   <td>count of elements in the method identifiers list</td>
1280 </tr>
1281 <tr>
1282   <td>method_ids_off</td>
1283   <td>uint</td>
1284   <td>offset from the start of the file to the method identifiers list, or
1285     <code>0</code> if <code>method_ids_size == 0</code>. The offset, if
1286     non-zero, should be to the start of the <code>method_ids</code>
1287     section.</td>
1288 </tr>
1289 <tr>
1290   <td>class_defs_size</td>
1291   <td>uint</td>
1292   <td>count of elements in the class definitions list</td>
1293 </tr>
1294 <tr>
1295   <td>class_defs_off</td>
1296   <td>uint</td>
1297   <td>offset from the start of the file to the class definitions list, or
1298     <code>0</code> if <code>class_defs_size == 0</code> (admittedly a
1299     strange edge case). The offset, if non-zero,
1300     should be to the start of the <code>class_defs</code> section.
1301   </td>
1302 </tr>
1303 <tr>
1304   <td>data_size</td>
1305   <td>uint</td>
1306   <td>Size of <code>data</code> section in bytes. Must be an even
1307     multiple of sizeof(uint).</td>
1308 </tr>
1309 <tr>
1310   <td>data_off</td>
1311   <td>uint</td>
1312   <td>offset from the start of the file to the start of the
1313    <code>data</code> section.
1314   </td>
1315 </tr>
1316 </tbody>
1317 </table>
1318
1319 <h2><code>map_list</code></h2>
1320 <h4>appears in the <code>data</code> section</h4>
1321 <h4>referenced from <code>header_item</code></h4>
1322 <h4>alignment: 4 bytes</h4>
1323
1324 <p>This is a list of the entire contents of a file, in order. It
1325 contains some redundancy with respect to the <code>header_item</code>
1326 but is intended to be an easy form to use to iterate over an entire
1327 file. A given type must appear at most once in a map, but there is no
1328 restriction on what order types may appear in, other than the
1329 restrictions implied by the rest of the format (e.g., a
1330 <code>header</code> section must appear first, followed by a
1331 <code>string_ids</code> section, etc.). Additionally, the map entries must
1332 be ordered by initial offset and must not overlap.</p>
1333
1334 <table class="format">
1335 <thead>
1336 <tr>
1337   <th>Name</th>
1338   <th>Format</th>
1339   <th>Description</th>
1340 </tr>
1341 </thead>
1342 <tbody>
1343 <tr>
1344   <td>size</td>
1345   <td>uint</td>
1346   <td>size of the list, in entries</td>
1347 </tr>
1348 <tr>
1349   <td>list</td>
1350   <td>map_item[size]</td>
1351   <td>elements of the list</td>
1352 </tr>
1353 </tbody>
1354 </table>
1355
1356 <h3><code>map_item</code> Format</h3>
1357
1358 <table class="format">
1359 <thead>
1360 <tr>
1361   <th>Name</th>
1362   <th>Format</th>
1363   <th>Description</th>
1364 </tr>
1365 </thead>
1366 <tbody>
1367 <tr>
1368   <td>type</td>
1369   <td>ushort</td>
1370   <td>type of the items; see table below</td>
1371 </tr>
1372 <tr>
1373   <td>unused</td>
1374   <td>ushort</td>
1375   <td><i>(unused)</i></td>
1376 </tr>
1377 <tr>
1378   <td>size</td>
1379   <td>uint</td>
1380   <td>count of the number of items to be found at the indicated offset</td>
1381 </tr>
1382 <tr>
1383   <td>offset</td>
1384   <td>uint</td>
1385   <td>offset from the start of the file to the items in question</td>
1386 </tr>
1387 </tbody>
1388 </table>
1389
1390
1391 <h3>Type Codes</h3>
1392
1393 <table class="typeCodes">
1394 <thead>
1395 <tr>
1396   <th>Item Type</th>
1397   <th>Constant</th>
1398   <th>Value</th>
1399   <th>Item Size In Bytes</th>
1400 </tr>
1401 </thead>
1402 <tbody>
1403 <tr>
1404   <td>header_item</td>
1405   <td>TYPE_HEADER_ITEM</td>
1406   <td>0x0000</td>
1407   <td>0x70</td>
1408 </tr>
1409 <tr>
1410   <td>string_id_item</td>
1411   <td>TYPE_STRING_ID_ITEM</td>
1412   <td>0x0001</td>
1413   <td>0x04</td>
1414 </tr>
1415 <tr>
1416   <td>type_id_item</td>
1417   <td>TYPE_TYPE_ID_ITEM</td>
1418   <td>0x0002</td>
1419   <td>0x04</td>
1420 </tr>
1421 <tr>
1422   <td>proto_id_item</td>
1423   <td>TYPE_PROTO_ID_ITEM</td>
1424   <td>0x0003</td>
1425   <td>0x0c</td>
1426 </tr>
1427 <tr>
1428   <td>field_id_item</td>
1429   <td>TYPE_FIELD_ID_ITEM</td>
1430   <td>0x0004</td>
1431   <td>0x08</td>
1432 </tr>
1433 <tr>
1434   <td>method_id_item</td>
1435   <td>TYPE_METHOD_ID_ITEM</td>
1436   <td>0x0005</td>
1437   <td>0x08</td>
1438 </tr>
1439 <tr>
1440   <td>class_def_item</td>
1441   <td>TYPE_CLASS_DEF_ITEM</td>
1442   <td>0x0006</td>
1443   <td>0x20</td>
1444 </tr>
1445 <tr>
1446   <td>map_list</td>
1447   <td>TYPE_MAP_LIST</td>
1448   <td>0x1000</td>
1449   <td>4 + (item.size * 12)</td>
1450 </tr>
1451 <tr>
1452   <td>type_list</td>
1453   <td>TYPE_TYPE_LIST</td>
1454   <td>0x1001</td>
1455   <td>4 + (item.size * 2)</td>
1456 </tr>
1457 <tr>
1458   <td>annotation_set_ref_list</td>
1459   <td>TYPE_ANNOTATION_SET_REF_LIST</td>
1460   <td>0x1002</td>
1461   <td>4 + (item.size * 4)</td>
1462 </tr>
1463 <tr>
1464   <td>annotation_set_item</td>
1465   <td>TYPE_ANNOTATION_SET_ITEM</td>
1466   <td>0x1003</td>
1467   <td>4 + (item.size * 4)</td>
1468 </tr>
1469 <tr>
1470   <td>class_data_item</td>
1471   <td>TYPE_CLASS_DATA_ITEM</td>
1472   <td>0x2000</td>
1473   <td><i>implicit; must parse</i></td>
1474 </tr>
1475 <tr>
1476   <td>code_item</td>
1477   <td>TYPE_CODE_ITEM</td>
1478   <td>0x2001</td>
1479   <td><i>implicit; must parse</i></td>
1480 </tr>
1481 <tr>
1482   <td>string_data_item</td>
1483   <td>TYPE_STRING_DATA_ITEM</td>
1484   <td>0x2002</td>
1485   <td><i>implicit; must parse</i></td>
1486 </tr>
1487 <tr>
1488   <td>debug_info_item</td>
1489   <td>TYPE_DEBUG_INFO_ITEM</td>
1490   <td>0x2003</td>
1491   <td><i>implicit; must parse</i></td>
1492 </tr>
1493 <tr>
1494   <td>annotation_item</td>
1495   <td>TYPE_ANNOTATION_ITEM</td>
1496   <td>0x2004</td>
1497   <td><i>implicit; must parse</i></td>
1498 </tr>
1499 <tr>
1500   <td>encoded_array_item</td>
1501   <td>TYPE_ENCODED_ARRAY_ITEM</td>
1502   <td>0x2005</td>
1503   <td><i>implicit; must parse</i></td>
1504 </tr>
1505 <tr>
1506   <td>annotations_directory_item</td>
1507   <td>TYPE_ANNOTATIONS_DIRECTORY_ITEM</td>
1508   <td>0x2006</td>
1509   <td><i>implicit; must parse</i></td>
1510 </tr>
1511 </tbody>
1512 </table>
1513
1514
1515 <h2><code>string_id_item</code></h2>
1516 <h4>appears in the <code>string_ids</code> section</h4>
1517 <h4>alignment: 4 bytes</h4>
1518
1519 <table class="format">
1520 <thead>
1521 <tr>
1522   <th>Name</th>
1523   <th>Format</th>
1524   <th>Description</th>
1525 </tr>
1526 </thead>
1527 <tbody>
1528 <tr>
1529   <td>string_data_off</td>
1530   <td>uint</td>
1531   <td>offset from the start of the file to the string data for this
1532     item. The offset should be to a location
1533     in the <code>data</code> section, and the data should be in the
1534     format specified by "<code>string_data_item</code>" below.
1535     There is no alignment requirement for the offset.
1536   </td>
1537 </tr>
1538 </tbody>
1539 </table>
1540
1541 <h2><code>string_data_item</code></h2>
1542 <h4>appears in the <code>data</code> section</h4>
1543 <h4>alignment: none (byte-aligned)</h4>
1544
1545 <table class="format">
1546 <thead>
1547 <tr>
1548   <th>Name</th>
1549   <th>Format</th>
1550   <th>Description</th>
1551 </tr>
1552 </thead>
1553 <tbody>
1554 <tr>
1555   <td>utf16_size</td>
1556   <td>uleb128</td>
1557   <td>size of this string, in UTF-16 code units (which is the "string
1558     length" in many systems). That is, this is the decoded length of
1559     the string. (The encoded length is implied by the position of
1560     the <code>0</code> byte.)</td>
1561 </tr>
1562 <tr>
1563   <td>data</td>
1564   <td>ubyte[]</td>
1565   <td>a series of MUTF-8 code units (a.k.a. octets, a.k.a. bytes)
1566     followed by a byte of value <code>0</code>. See
1567     "MUTF-8 (Modified UTF-8) Encoding" above for details and
1568     discussion about the data format.
1569     <p><b>Note:</b> It is acceptable to have a string which includes
1570     (the encoded form of) UTF-16 surrogate code units (that is,
1571     <code>U+d800</code> &hellip; <code>U+dfff</code>)
1572     either in isolation or out-of-order with respect to the usual
1573     encoding of Unicode into UTF-16. It is up to higher-level uses of
1574     strings to reject such invalid encodings, if appropriate.</p>
1575   </td>
1576 </tr>
1577 </tbody>
1578 </table>
1579
1580 <h2><code>type_id_item</code></h2>
1581 <h4>appears in the <code>type_ids</code> section</h4>
1582 <h4>alignment: 4 bytes</h4>
1583
1584 <table class="format">
1585 <thead>
1586 <tr>
1587   <th>Name</th>
1588   <th>Format</th>
1589   <th>Description</th>
1590 </tr>
1591 </thead>
1592 <tbody>
1593 <tr>
1594   <td>descriptor_idx</td>
1595   <td>uint</td>
1596   <td>index into the <code>string_ids</code> list for the descriptor
1597     string of this type. The string must conform to the syntax for
1598     <i>TypeDescriptor</i>, defined above.
1599   </td>
1600 </tr>
1601 </tbody>
1602 </table>
1603
1604 <h2><code>proto_id_item</code></h2>
1605 <h4>appears in the <code>proto_ids</code> section</h4>
1606 <h4>alignment: 4 bytes</h4>
1607
1608 <table class="format">
1609 <thead>
1610 <tr>
1611   <th>Name</th>
1612   <th>Format</th>
1613   <th>Description</th>
1614 </tr>
1615 </thead>
1616 <tbody>
1617 <tr>
1618   <td>shorty_idx</td>
1619   <td>uint</td>
1620   <td>index into the <code>string_ids</code> list for the short-form
1621     descriptor string of this prototype. The string must conform to the
1622     syntax for <i>ShortyDescriptor</i>, defined above, and must correspond
1623     to the return type and parameters of this item.
1624   </td>
1625 </tr>
1626 <tr>
1627   <td>return_type_idx</td>
1628   <td>uint</td>
1629   <td>index into the <code>type_ids</code> list for the return type
1630     of this prototype
1631   </td>
1632 </tr>
1633 <tr>
1634   <td>parameters_off</td>
1635   <td>uint</td>
1636   <td>offset from the start of the file to the list of parameter types
1637     for this prototype, or <code>0</code> if this prototype has no
1638     parameters. This offset, if non-zero, should be in the
1639     <code>data</code> section, and the data there should be in the
1640     format specified by <code>"type_list"</code> below. Additionally, there
1641     should be no reference to the type <code>void</code> in the list.
1642   </td>
1643 </tr>
1644 </tbody>
1645 </table>
1646
1647 <h2><code>field_id_item</code></h2>
1648 <h4>appears in the <code>field_ids</code> section</h4>
1649 <h4>alignment: 4 bytes</h4>
1650
1651 <table class="format">
1652 <thead>
1653 <tr>
1654   <th>Name</th>
1655   <th>Format</th>
1656   <th>Description</th>
1657 </tr>
1658 </thead>
1659 <tbody>
1660 <tr>
1661   <td>class_idx</td>
1662   <td>ushort</td>
1663   <td>index into the <code>type_ids</code> list for the definer of this
1664     field. This must be a class type, and not an array or primitive type.
1665   </td>
1666 </tr>
1667 <tr>
1668   <td>type_idx</td>
1669   <td>ushort</td>
1670   <td>index into the <code>type_ids</code> list for the type of
1671     this field
1672   </td>
1673 </tr>
1674 <tr>
1675   <td>name_idx</td>
1676   <td>uint</td>
1677   <td>index into the <code>string_ids</code> list for the name of this
1678     field. The string must conform to the syntax for <i>MemberName</i>,
1679     defined above.
1680   </td>
1681 </tr>
1682 </tbody>
1683 </table>
1684
1685 <h2><code>method_id_item</code></h2>
1686 <h4>appears in the <code>method_ids</code> section</h4>
1687 <h4>alignment: 4 bytes</h4>
1688
1689 <table class="format">
1690 <thead>
1691 <tr>
1692   <th>Name</th>
1693   <th>Format</th>
1694   <th>Description</th>
1695 </tr>
1696 </thead>
1697 <tbody>
1698 <tr>
1699   <td>class_idx</td>
1700   <td>ushort</td>
1701   <td>index into the <code>type_ids</code> list for the definer of this
1702     method. This must be a class or array type, and not a primitive type.
1703   </td>
1704 </tr>
1705 <tr>
1706   <td>proto_idx</td>
1707   <td>ushort</td>
1708   <td>index into the <code>proto_ids</code> list for the prototype of
1709     this method
1710   </td>
1711 </tr>
1712 <tr>
1713   <td>name_idx</td>
1714   <td>uint</td>
1715   <td>index into the <code>string_ids</code> list for the name of this
1716     method. The string must conform to the syntax for <i>MemberName</i>,
1717     defined above.
1718   </td>
1719 </tr>
1720 </tbody>
1721 </table>
1722
1723 <h2><code>class_def_item</code></h2>
1724 <h4>appears in the <code>class_defs</code> section</h4>
1725 <h4>alignment: 4 bytes</h4>
1726
1727 <table class="format">
1728 <thead>
1729 <tr>
1730   <th>Name</th>
1731   <th>Format</th>
1732   <th>Description</th>
1733 </tr>
1734 </thead>
1735 <tbody>
1736 <tr>
1737   <td>class_idx</td>
1738   <td>uint</td>
1739   <td>index into the <code>type_ids</code> list for this class.
1740     This must be a class type, and not an array or primitive type.
1741   </td>
1742 </tr>
1743 <tr>
1744   <td>access_flags</td>
1745   <td>uint</td>
1746   <td>access flags for the class (<code>public</code>, <code>final</code>,
1747     etc.). See "<code>access_flags</code> Definitions" for details.
1748   </td>
1749 </tr>
1750 <tr>
1751   <td>superclass_idx</td>
1752   <td>uint</td>
1753   <td>index into the <code>type_ids</code> list for the superclass, or
1754     the constant value <code>NO_INDEX</code> if this class has no
1755     superclass (i.e., it is a root class such as <code>Object</code>).
1756     If present, this must be a class type, and not an array or primitive type.
1757   </td>
1758 </tr>
1759 <tr>
1760   <td>interfaces_off</td>
1761   <td>uint</td>
1762   <td>offset from the start of the file to the list of interfaces, or
1763     <code>0</code> if there are none. This offset
1764     should be in the <code>data</code> section, and the data
1765     there should be in the format specified by
1766     "<code>type_list</code>" below. Each of the elements of the list
1767     must be a class type (not an array or primitive type), and there
1768     must not be any duplicates.
1769   </td>
1770 </tr>
1771 <tr>
1772   <td>source_file_idx</td>
1773   <td>uint</td>
1774   <td>index into the <code>string_ids</code> list for the name of the
1775     file containing the original source for (at least most of) this class,
1776     or the special value <code>NO_INDEX</code> to represent a lack of
1777     this information. The <code>debug_info_item</code> of any given method
1778     may override this source file, but the expectation is that most classes
1779     will only come from one source file.
1780   </td>
1781 </tr>
1782 <tr>
1783   <td>annotations_off</td>
1784   <td>uint</td>
1785   <td>offset from the start of the file to the annotations structure
1786     for this class, or <code>0</code> if there are no annotations on
1787     this class. This offset, if non-zero, should be in the
1788     <code>data</code> section, and the data there should be in
1789     the format specified by "<code>annotations_directory_item</code>" below,
1790     with all items referring to this class as the definer.
1791   </td>
1792 </tr>
1793 <tr>
1794   <td>class_data_off</td>
1795   <td>uint</td>
1796   <td>offset from the start of the file to the associated
1797     class data for this item, or <code>0</code> if there is no class
1798     data for this class. (This may be the case, for example, if this class
1799     is a marker interface.) The offset, if non-zero, should be in the
1800     <code>data</code> section, and the data there should be in the
1801     format specified by "<code>class_data_item</code>" below, with all
1802     items referring to this class as the definer.
1803   </td>
1804 </tr>
1805 <tr>
1806   <td>static_values_off</td>
1807   <td>uint</td>
1808   <td>offset from the start of the file to the list of initial
1809     values for <code>static</code> fields, or <code>0</code> if there
1810     are none (and all <code>static</code> fields are to be initialized with
1811     <code>0</code> or <code>null</code>). This offset should be in the
1812     <code>data</code> section, and the data there should be in the
1813     format specified by "<code>encoded_array_item</code>" below. The size
1814     of the array must be no larger than the number of <code>static</code>
1815     fields declared by this class, and the elements correspond to the
1816     <code>static</code> fields in the same order as declared in the
1817     corresponding <code>field_list</code>. The type of each array
1818     element must match the declared type of its corresponding field.
1819     If there are fewer elements in the array than there are
1820     <code>static</code> fields, then the leftover fields are initialized
1821     with a type-appropriate <code>0</code> or <code>null</code>.
1822   </td>
1823 </tr>
1824 </tbody>
1825 </table>
1826
1827 <h2><code>class_data_item</code></h2>
1828 <h4>referenced from <code>class_def_item</code></h4>
1829 <h4>appears in the <code>data</code> section</h4>
1830 <h4>alignment: none (byte-aligned)</h4>
1831
1832 <table class="format">
1833 <thead>
1834 <tr>
1835   <th>Name</th>
1836   <th>Format</th>
1837   <th>Description</th>
1838 </tr>
1839 </thead>
1840 <tbody>
1841 <tr>
1842   <td>static_fields_size</td>
1843   <td>uleb128</td>
1844   <td>the number of static fields defined in this item</td>
1845 </tr>
1846 <tr>
1847   <td>instance_fields_size</td>
1848   <td>uleb128</td>
1849   <td>the number of instance fields defined in this item</td>
1850 </tr>
1851 <tr>
1852   <td>direct_methods_size</td>
1853   <td>uleb128</td>
1854   <td>the number of direct methods defined in this item</td>
1855 </tr>
1856 <tr>
1857   <td>virtual_methods_size</td>
1858   <td>uleb128</td>
1859   <td>the number of virtual methods defined in this item</td>
1860 </tr>
1861 <tr>
1862   <td>static_fields</td>
1863   <td>encoded_field[static_fields_size]</td>
1864   <td>the defined static fields, represented as a sequence of
1865     encoded elements. The fields must be sorted by
1866     <code>field_idx</code> in increasing order.
1867   </td>
1868 </tr>
1869 <tr>
1870   <td>instance_fields</td>
1871   <td>encoded_field[instance_fields_size]</td>
1872   <td>the defined instance fields, represented as a sequence of
1873     encoded elements. The fields must be sorted by
1874     <code>field_idx</code> in increasing order.
1875   </td>
1876 </tr>
1877 <tr>
1878   <td>direct_methods</td>
1879   <td>encoded_method[direct_methods_size]</td>
1880   <td>the defined direct (any of <code>static</code>, <code>private</code>,
1881     or constructor) methods, represented as a sequence of
1882     encoded elements. The methods must be sorted by
1883     <code>method_idx</code> in increasing order.
1884   </td>
1885 </tr>
1886 <tr>
1887   <td>virtual_methods</td>
1888   <td>encoded_method[virtual_methods_size]</td>
1889   <td>the defined virtual (none of <code>static</code>, <code>private</code>,
1890     or constructor) methods, represented as a sequence of
1891     encoded elements. This list should <i>not</i> include inherited
1892     methods unless overridden by the class that this item represents. The
1893     methods must be sorted by <code>method_idx</code> in increasing order.
1894   </td>
1895 </tr>
1896 </tbody>
1897 </table>
1898
1899 <p><b>Note:</b> All elements' <code>field_id</code>s and
1900 <code>method_id</code>s must refer to the same defining class.</p>
1901
1902 <h3><code>encoded_field</code> Format</h3>
1903
1904 <table class="format">
1905 <thead>
1906 <tr>
1907   <th>Name</th>
1908   <th>Format</th>
1909   <th>Description</th>
1910 </tr>
1911 </thead>
1912 <tbody>
1913 <tr>
1914   <td>field_idx_diff</td>
1915   <td>uleb128</td>
1916   <td>index into the <code>field_ids</code> list for the identity of this
1917     field (includes the name and descriptor), represented as a difference
1918     from the index of previous element in the list. The index of the
1919     first element in a list is represented directly.
1920   </td>
1921 </tr>
1922 <tr>
1923   <td>access_flags</td>
1924   <td>uleb128</td>
1925   <td>access flags for the field (<code>public</code>, <code>final</code>,
1926     etc.). See "<code>access_flags</code> Definitions" for details.
1927   </td>
1928 </tr>
1929 </tbody>
1930 </table>
1931
1932 <h3><code>encoded_method</code> Format</h3>
1933
1934 <table class="format">
1935 <thead>
1936 <tr>
1937   <th>Name</th>
1938   <th>Format</th>
1939   <th>Description</th>
1940 </tr>
1941 </thead>
1942 <tbody>
1943 <tr>
1944   <td>method_idx_diff</td>
1945   <td>uleb128</td>
1946   <td>index into the <code>method_ids</code> list for the identity of this
1947     method (includes the name and descriptor), represented as a difference
1948     from the index of previous element in the list. The index of the
1949     first element in a list is represented directly.
1950   </td>
1951 </tr>
1952 <tr>
1953   <td>access_flags</td>
1954   <td>uleb128</td>
1955   <td>access flags for the method (<code>public</code>, <code>final</code>,
1956     etc.). See "<code>access_flags</code> Definitions" for details.
1957   </td>
1958 </tr>
1959 <tr>
1960   <td>code_off</td>
1961   <td>uleb128</td>
1962   <td>offset from the start of the file to the code structure for this
1963     method, or <code>0</code> if this method is either <code>abstract</code>
1964     or <code>native</code>. The offset should be to a location in the
1965     <code>data</code> section. The format of the data is specified by
1966     "<code>code_item</code>" below.
1967   </td>
1968 </tr>
1969 </tbody>
1970 </table>
1971
1972 <h2><code>type_list</code></h2>
1973 <h4>referenced from <code>class_def_item</code> and
1974 <code>proto_id_item</code></h4>
1975 <h4>appears in the <code>data</code> section</h4>
1976 <h4>alignment: 4 bytes</h4>
1977
1978 <table class="format">
1979 <thead>
1980 <tr>
1981   <th>Name</th>
1982   <th>Format</th>
1983   <th>Description</th>
1984 </tr>
1985 </thead>
1986 <tbody>
1987 <tr>
1988   <td>size</td>
1989   <td>uint</td>
1990   <td>size of the list, in entries</td>
1991 </tr>
1992 <tr>
1993   <td>list</td>
1994   <td>type_item[size]</td>
1995   <td>elements of the list</td>
1996 </tr>
1997 </tbody>
1998 </table>
1999
2000 <h3><code>type_item</code> Format</h3>
2001
2002 <table class="format">
2003 <thead>
2004 <tr>
2005   <th>Name</th>
2006   <th>Format</th>
2007   <th>Description</th>
2008 </tr>
2009 </thead>
2010 <tbody>
2011 <tr>
2012   <td>type_idx</td>
2013   <td>ushort</td>
2014   <td>index into the <code>type_ids</code> list</td>
2015 </tr>
2016 </tbody>
2017 </table>
2018
2019 <h2><code>code_item</code></h2>
2020 <h4>referenced from <code>encoded_method</code></h4>
2021 <h4>appears in the <code>data</code> section</h4>
2022 <h4>alignment: 4 bytes</h4>
2023
2024 <table class="format">
2025 <thead>
2026 <tr>
2027   <th>Name</th>
2028   <th>Format</th>
2029   <th>Description</th>
2030 </tr>
2031 </thead>
2032 <tbody>
2033 <tr>
2034   <td>registers_size</td>
2035   <td>ushort</td>
2036   <td>the number of registers used by this code</td>
2037 </tr>
2038 <tr>
2039   <td>ins_size</td>
2040   <td>ushort</td>
2041   <td>the number of words of incoming arguments to the method that this
2042     code is for</td>
2043 </tr>
2044 <tr>
2045   <td>outs_size</td>
2046   <td>ushort</td>
2047   <td>the number of words of outgoing argument space required by this
2048     code for method invocation
2049   </td>
2050 </tr>
2051 <tr>
2052   <td>tries_size</td>
2053   <td>ushort</td>
2054   <td>the number of <code>try_item</code>s for this instance. If non-zero,
2055     then these appear as the <code>tries</code> array just after the
2056     <code>insns</code> in this instance.
2057   </td>
2058 </tr>
2059 <tr>
2060   <td>debug_info_off</td>
2061   <td>uint</td>
2062   <td>offset from the start of the file to the debug info (line numbers +
2063     local variable info) sequence for this code, or <code>0</code> if
2064     there simply is no information. The offset, if non-zero, should be
2065     to a location in the <code>data</code> section. The format of
2066     the data is specified by "<code>debug_info_item</code>" below.
2067   </td>
2068 </tr>
2069 <tr>
2070   <td>insns_size</td>
2071   <td>uint</td>
2072   <td>size of the instructions list, in 16-bit code units</td>
2073 </tr>
2074 <tr>
2075   <td>insns</td>
2076   <td>ushort[insns_size]</td>
2077   <td>actual array of bytecode. The format of code in an <code>insns</code>
2078     array is specified by the companion document
2079     <a href="dalvik-bytecode.html">"Bytecode for the Dalvik VM"</a>. Note
2080     that though this is defined as an array of <code>ushort</code>, there
2081     are some internal structures that prefer four-byte alignment. Also,
2082     if this happens to be in an endian-swapped file, then the swapping is
2083     <i>only</i> done on individual <code>ushort</code>s and not on the
2084     larger internal structures.
2085   </td>
2086 </tr>
2087 <tr>
2088   <td>padding</td>
2089   <td>ushort <i>(optional)</i> = 0</td>
2090   <td>two bytes of padding to make <code>tries</code> four-byte aligned.
2091     This element is only present if <code>tries_size</code> is non-zero
2092     and <code>insns_size</code> is odd.
2093   </td>
2094 </tr>
2095 <tr>
2096   <td>tries</td>
2097   <td>try_item[tries_size] <i>(optional)</i></td>
2098   <td>array indicating where in the code exceptions are caught and
2099     how to handle them. Elements of the array must be non-overlapping in
2100     range and in order from low to high address. This element is only
2101     present if <code>tries_size</code> is non-zero.
2102   </td>
2103 </tr>
2104 <tr>
2105   <td>handlers</td>
2106   <td>encoded_catch_handler_list <i>(optional)</i></td>
2107   <td>bytes representing a list of lists of catch types and associated
2108     handler addresses. Each <code>try_item</code> has a byte-wise offset
2109     into this structure. This element is only present if
2110     <code>tries_size</code> is non-zero.
2111   </td>
2112 </tr>
2113 </tbody>
2114 </table>
2115
2116 <h3><code>try_item</code> Format </h3>
2117
2118 <table class="format">
2119 <thead>
2120 <tr>
2121   <th>Name</th>
2122   <th>Format</th>
2123   <th>Description</th>
2124 </tr>
2125 </thead>
2126 <tbody>
2127 <tr>
2128   <td>start_addr</td>
2129   <td>uint</td>
2130   <td>start address of the block of code covered by this entry. The address
2131     is a count of 16-bit code units to the start of the first covered
2132     instruction.
2133   </td>
2134 </tr>
2135 <tr>
2136   <td>insn_count</td>
2137   <td>ushort</td>
2138   <td>number of 16-bit code units covered by this entry. The last code
2139     unit covered (inclusive) is <code>start_addr + insn_count - 1</code>.
2140   </td>
2141 </tr>
2142 <tr>
2143   <td>handler_off</td>
2144   <td>ushort</td>
2145   <td>offset in bytes from the start of the associated
2146     <code>encoded_catch_hander_list</code> to the
2147     <code>encoded_catch_handler</code> for this entry. This must be an
2148     offset to the start of an <code>encoded_catch_handler</code>.
2149   </td>
2150 </tr>
2151 </tbody>
2152 </table>
2153
2154 <h3><code>encoded_catch_handler_list</code> Format</h3>
2155
2156 <table class="format">
2157 <thead>
2158 <tr>
2159   <th>Name</th>
2160   <th>Format</th>
2161   <th>Description</th>
2162 </tr>
2163 </thead>
2164 <tbody>
2165 <tr>
2166   <td>size</td>
2167   <td>uleb128</td>
2168   <td>size of this list, in entries</td>
2169 </tr>
2170 <tr>
2171   <td>list</td>
2172   <td>encoded_catch_handler[handlers_size]</td>
2173   <td>actual list of handler lists, represented directly (not as offsets),
2174     and concatenated sequentially</td>
2175 </tr>
2176 </tbody>
2177 </table>
2178
2179 <h3><code>encoded_catch_handler</code> Format</h3>
2180
2181 <table class="format">
2182 <thead>
2183 <tr>
2184   <th>Name</th>
2185   <th>Format</th>
2186   <th>Description</th>
2187 </tr>
2188 </thead>
2189 <tbody>
2190 <tr>
2191   <td>size</td>
2192   <td>sleb128</td>
2193   <td>number of catch types in this list. If non-positive, then this is
2194     the negative of the number of catch types, and the catches are followed
2195     by a catch-all handler. For example: A <code>size</code> of <code>0</code>
2196     means that there is a catch-all but no explicitly typed catches.
2197     A <code>size</code> of <code>2</code> means that there are two explicitly
2198     typed catches and no catch-all. And a <code>size</code> of <code>-1</code>
2199     means that there is one typed catch along with a catch-all.
2200   </td>
2201 </tr>
2202 <tr>
2203   <td>handlers</td>
2204   <td>encoded_type_addr_pair[abs(size)]</td>
2205   <td>stream of <code>abs(size)</code> encoded items, one for each caught
2206     type, in the order that the types should be tested.
2207   </td>
2208 </tr>
2209 <tr>
2210   <td>catch_all_addr</td>
2211   <td>uleb128 <i>(optional)</i></td>
2212   <td>bytecode address of the catch-all handler. This element is only
2213     present if <code>size</code> is non-positive.
2214   </td>
2215 </tr>
2216 </tbody>
2217 </table>
2218
2219 <h3><code>encoded_type_addr_pair</code> Format</h3>
2220
2221 <table class="format">
2222 <thead>
2223 <tr>
2224   <th>Name</th>
2225   <th>Format</th>
2226   <th>Description</th>
2227 </tr>
2228 </thead>
2229 <tbody>
2230 <tr>
2231   <td>type_idx</td>
2232   <td>uleb128</td>
2233   <td>index into the <code>type_ids</code> list for the type of the
2234     exception to catch
2235   </td>
2236 </tr>
2237 <tr>
2238   <td>addr</td>
2239   <td>uleb128</td>
2240   <td>bytecode address of the associated exception handler</td>
2241 </tr>
2242 </tbody>
2243 </table>
2244
2245 <h2><code>debug_info_item</code></h2>
2246 <h4>referenced from <code>code_item</code></h4>
2247 <h4>appears in the <code>data</code> section</h4>
2248 <h4>alignment: none (byte-aligned)</h4>
2249
2250 <p>Each <code>debug_info_item</code> defines a DWARF3-inspired byte-coded
2251 state machine that, when interpreted, emits the positions
2252 table and (potentially) the local variable information for a
2253 <code>code_item</code>. The sequence begins with a variable-length
2254 header (the length of which depends on the number of method
2255 parameters), is followed by the state machine bytecodes, and ends
2256 with an <code>DBG_END_SEQUENCE</code> byte.</p>
2257
2258 <p>The state machine consists of five registers. The
2259 <code>address</code> register represents the instruction offset in the
2260 associated <code>insns_item</code> in 16-bit code units. The
2261 <code>address</code> register starts at <code>0</code> at the beginning of each
2262 <code>debug_info</code> sequence and must only monotonically increase.
2263 The <code>line</code> register represents what source line number
2264 should be associated with the next positions table entry emitted by
2265 the state machine. It is initialized in the sequence header, and may
2266 change in positive or negative directions but must never be less than
2267 <code>1</code>. The <code>source_file</code> register represents the
2268 source file that the line number entries refer to. It is initialized to
2269 the value of <code>source_file_idx</code> in <code>class_def_item</code>.
2270 The other two variables, <code>prologue_end</code> and
2271 <code>epilogue_begin</code>, are boolean flags (initialized to
2272 <code>false</code>) that indicate whether the next position emitted
2273 should be considered a method prologue or epilogue. The state machine
2274 must also track the name and type of the last local variable live in
2275 each register for the <code>DBG_RESTART_LOCAL</code> code.</p>
2276
2277 <p>The header is as follows:</p>
2278
2279 <table class="format">
2280 <thead>
2281 <tr>
2282   <th>Name</th>
2283   <th>Format</th>
2284   <th>Description</th>
2285 </tr>
2286 </thead>
2287 <tbody>
2288 <tr>
2289  <td>line_start</td>
2290  <td>uleb128</td>
2291  <td>the initial value for the state machine's <code>line</code> register.
2292     Does not represent an actual positions entry.
2293  </td>
2294 </tr>
2295 <tr>
2296  <td>parameters_size</td>
2297  <td>uleb128</td>
2298  <td>the number of parameter names that are encoded. There should be
2299    one per method parameter, excluding an instance method's <code>this</code>,
2300    if any.
2301  </td>
2302 </tr>
2303 <tr>
2304  <td>parameter_names</td>
2305  <td>uleb128p1[parameters_size]</td>
2306  <td>string index of the method parameter name. An encoded value of
2307    <code>NO_INDEX</code> indicates that no name
2308    is available for the associated parameter. The type descriptor
2309    and signature are implied from the method descriptor and signature.
2310  </td>
2311 </tr>
2312 </tbody>
2313 </table>
2314
2315 <p>The byte code values are as follows:</p>
2316
2317 <table class="debugByteCode">
2318 <thead>
2319 <tr>
2320   <th>Name</th>
2321   <th>Value</th>
2322   <th>Format</th>
2323   <th>Arguments</th>
2324   <th>Description</th>
2325 </tr>
2326 </thead>
2327 <tbody>
2328 <tr>
2329   <td>DBG_END_SEQUENCE</td>
2330   <td>0x00</td>
2331   <td></td>
2332   <td><i>(none)</i></td>
2333   <td>terminates a debug info sequence for a <code>code_item</code></td>
2334 </tr>
2335 <tr>
2336   <td>DBG_ADVANCE_PC</td>
2337   <td>0x01</td>
2338   <td>uleb128&nbsp;addr_diff</td>
2339   <td><code>addr_diff</code>: amount to add to address register</td>
2340   <td>advances the address register without emitting a positions entry</td>
2341 </tr>
2342 <tr>
2343   <td>DBG_ADVANCE_LINE</td>
2344   <td>0x02</td>
2345   <td>sleb128&nbsp;line_diff</td>
2346   <td><code>line_diff</code>: amount to change line register by</td>
2347   <td>advances the line register without emitting a positions entry</td>
2348 </tr>
2349 <tr>
2350   <td>DBG_START_LOCAL</td>
2351   <td>0x03</td>
2352   <td>uleb128&nbsp;register_num<br/>
2353     uleb128p1&nbsp;name_idx<br/>
2354     uleb128p1&nbsp;type_idx
2355   </td>
2356   <td><code>register_num</code>: register that will contain local<br/>
2357     <code>name_idx</code>: string index of the name<br/>
2358     <code>type_idx</code>: type index of the type
2359   </td>
2360   <td>introduces a local variable at the current address. Either
2361     <code>name_idx</code> or <code>type_idx</code> may be
2362     <code>NO_INDEX</code> to indicate that that value is unknown.
2363   </td>
2364 </tr>
2365 <tr>
2366   <td>DBG_START_LOCAL_EXTENDED</td>
2367   <td>0x04</td>
2368   <td>uleb128&nbsp;register_num<br/>
2369     uleb128p1&nbsp;name_idx<br/>
2370     uleb128p1&nbsp;type_idx<br/>
2371     uleb128p1&nbsp;sig_idx
2372   </td>
2373   <td><code>register_num</code>: register that will contain local<br/>
2374     <code>name_idx</code>: string index of the name<br/>
2375     <code>type_idx</code>: type index of the type<br/>
2376     <code>sig_idx</code>: string index of the type signature
2377   </td>
2378   <td>introduces a local with a type signature at the current address.
2379     Any of <code>name_idx</code>, <code>type_idx</code>, or
2380     <code>sig_idx</code> may be <code>NO_INDEX</code>
2381     to indicate that that value is unknown. (If <code>sig_idx</code> is
2382     <code>-1</code>, though, the same data could be represented more
2383     efficiently using the opcode <code>DBG_START_LOCAL</code>.)
2384     <p><b>Note:</b> See the discussion under
2385     "<code>dalvik.annotation.Signature</code>" below for caveats about
2386     handling signatures.</p>
2387   </td>
2388 </tr>
2389 <tr>
2390   <td>DBG_END_LOCAL</td>
2391   <td>0x05</td>
2392   <td>uleb128&nbsp;register_num</td>
2393   <td><code>register_num</code>: register that contained local</td>
2394   <td>marks a currently-live local variable as out of scope at the current
2395     address
2396   </td>
2397 </tr>
2398 <tr>
2399   <td>DBG_RESTART_LOCAL</td>
2400   <td>0x06</td>
2401   <td>uleb128&nbsp;register_num</td>
2402   <td><code>register_num</code>: register to restart</td>
2403   <td>re-introduces a local variable at the current address. The name
2404     and type are the same as the last local that was live in the specified
2405     register.
2406   </td>
2407 </tr>
2408 <tr>
2409   <td>DBG_SET_PROLOGUE_END</td>
2410   <td>0x07</td>
2411   <td></td>
2412   <td><i>(none)</i></td>
2413   <td>sets the <code>prologue_end</code> state machine register,
2414     indicating that the next position entry that is added should be
2415     considered the end of a method prologue (an appropriate place for
2416     a method breakpoint). The <code>prologue_end</code> register is
2417     cleared by any special (<code>&gt;= 0x0a</code>) opcode.
2418   </td>
2419 </tr>
2420 <tr>
2421   <td>DBG_SET_EPILOGUE_BEGIN</td>
2422   <td>0x08</td>
2423   <td></td>
2424   <td><i>(none)</i></td>
2425   <td>sets the <code>epilogue_begin</code> state machine register,
2426     indicating that the next position entry that is added should be
2427     considered the beginning of a method epilogue (an appropriate place
2428     to suspend execution before method exit).
2429     The <code>epilogue_begin</code> register is cleared by any special
2430     (<code>&gt;= 0x0a</code>) opcode.
2431   </td>
2432 </tr>
2433 <tr>
2434   <td>DBG_SET_FILE</td>
2435   <td>0x09</td>
2436   <td>uleb128p1&nbsp;name_idx</td>
2437   <td><code>name_idx</code>: string index of source file name;
2438     <code>NO_INDEX</code> if unknown
2439   </td>
2440   <td>indicates that all subsequent line number entries make reference to this
2441     source file name, instead of the default name specified in
2442     <code>code_item</code>
2443   </td>
2444 </tr>
2445 <tr>
2446   <td><i>Special Opcodes</i></td>
2447   <!-- When updating the range below, make sure to search for other
2448   instances of 0x0a in this section. -->
2449   <td>0x0a&hellip;0xff</td>
2450   <td></td>
2451   <td><i>(none)</i></td>
2452   <td>advances the <code>line</code> and <code>address</code> registers,
2453     emits a position entry, and clears <code>prologue_end</code> and
2454     <code>epilogue_begin</code>. See below for description.
2455   </td>
2456 </tr>
2457 </tbody>
2458 </table>
2459
2460 <h3>Special Opcodes</h3>
2461
2462 <p>Opcodes with values between <code>0x0a</code> and <code>0xff</code>
2463 (inclusive) move both the <code>line</code> and <code>address</code>
2464 registers by a small amount and then emit a new position table entry.
2465 The formula for the increments are as follows:</p>
2466
2467 <pre>
2468 DBG_FIRST_SPECIAL = 0x0a  // the smallest special opcode
2469 DBG_LINE_BASE   = -4      // the smallest line number increment
2470 DBG_LINE_RANGE  = 15      // the number of line increments represented
2471
2472 adjusted_opcode = opcode - DBG_FIRST_SPECIAL
2473
2474 line += DBG_LINE_BASE + (adjusted_opcode % DBG_LINE_RANGE)
2475 address += (adjusted_opcode / DBG_LINE_RANGE)
2476 </pre>
2477
2478 <h2><code>annotations_directory_item</code></h2>
2479 <h4>referenced from <code>class_def_item</code></h4>
2480 <h4>appears in the <code>data</code> section</h4>
2481 <h4>alignment: 4 bytes</h4>
2482
2483 <table class="format">
2484 <thead>
2485 <tr>
2486   <th>Name</th>
2487   <th>Format</th>
2488   <th>Description</th>
2489 </tr>
2490 </thead>
2491 <tbody>
2492 <tr>
2493   <td>class_annotations_off</td>
2494   <td>uint</td>
2495   <td>offset from the start of the file to the annotations made directly
2496     on the class, or <code>0</code> if the class has no direct annotations.
2497     The offset, if non-zero, should be to a location in the
2498     <code>data</code> section. The format of the data is specified
2499     by "<code>annotation_set_item</code>" below.
2500   </td>
2501 </tr>
2502 <tr>
2503   <td>fields_size</td>
2504   <td>uint</td>
2505   <td>count of fields annotated by this item</td>
2506 </tr>
2507 <tr>
2508   <td>annotated_methods_size</td>
2509   <td>uint</td>
2510   <td>count of methods annotated by this item</td>
2511 </tr>
2512 <tr>
2513   <td>annotated_parameters_size</td>
2514   <td>uint</td>
2515   <td>count of method parameter lists annotated by this item</td>
2516 </tr>
2517 <tr>
2518   <td>field_annotations</td>
2519   <td>field_annotation[fields_size] <i>(optional)</i></td>
2520   <td>list of associated field annotations. The elements of the list must
2521     be sorted in increasing order, by <code>field_idx</code>.
2522   </td>
2523 </tr>
2524 <tr>
2525   <td>method_annotations</td>
2526   <td>method_annotation[methods_size] <i>(optional)</i></td>
2527   <td>list of associated method annotations. The elements of the list must
2528     be sorted in increasing order, by <code>method_idx</code>.
2529   </td>
2530 </tr>
2531 <tr>
2532   <td>parameter_annotations</td>
2533   <td>parameter_annotation[parameters_size] <i>(optional)</i></td>
2534   <td>list of associated method parameter annotations. The elements of the
2535     list must be sorted in increasing order, by <code>method_idx</code>.
2536   </td>
2537 </tr>
2538 </tbody>
2539 </table>
2540
2541 <p><b>Note:</b> All elements' <code>field_id</code>s and
2542 <code>method_id</code>s must refer to the same defining class.</p>
2543
2544 <h3><code>field_annotation</code> Format</h3>
2545
2546 <table class="format">
2547 <thead>
2548 <tr>
2549   <th>Name</th>
2550   <th>Format</th>
2551   <th>Description</th>
2552 </tr>
2553 </thead>
2554 <tbody>
2555 <tr>
2556   <td>field_idx</td>
2557   <td>uint</td>
2558   <td>index into the <code>field_ids</code> list for the identity of the
2559     field being annotated
2560   </td>
2561 </tr>
2562 <tr>
2563   <td>annotations_off</td>
2564   <td>uint</td>
2565   <td>offset from the start of the file to the list of annotations for
2566     the field. The offset should be to a location in the <code>data</code>
2567     section. The format of the data is specified by
2568     "<code>annotation_set_item</code>" below.
2569   </td>
2570 </tr>
2571 </tbody>
2572 </table>
2573
2574 <h3><code>method_annotation</code> Format</h3>
2575
2576 <table class="format">
2577 <thead>
2578 <tr>
2579   <th>Name</th>
2580   <th>Format</th>
2581   <th>Description</th>
2582 </tr>
2583 </thead>
2584 <tbody>
2585 <tr>
2586   <td>method_idx</td>
2587   <td>uint</td>
2588   <td>index into the <code>method_ids</code> list for the identity of the
2589     method being annotated
2590   </td>
2591 </tr>
2592 <tr>
2593   <td>annotations_off</td>
2594   <td>uint</td>
2595   <td>offset from the start of the file to the list of annotations for
2596     the method. The offset should be to a location in the
2597     <code>data</code> section. The format of the data is specified by
2598     "<code>annotation_set_item</code>" below.
2599   </td>
2600 </tr>
2601 </tbody>
2602 </table>
2603
2604 <h3><code>parameter_annotation</code> Format</h2>
2605
2606 <table class="format">
2607 <thead>
2608 <tr>
2609   <th>Name</th>
2610   <th>Format</th>
2611   <th>Description</th>
2612 </tr>
2613 </thead>
2614 <tbody>
2615 <tr>
2616   <td>method_idx</td>
2617   <td>uint</td>
2618   <td>index into the <code>method_ids</code> list for the identity of the
2619     method whose parameters are being annotated
2620   </td>
2621 </tr>
2622 <tr>
2623   <td>annotations_off</td>
2624   <td>uint</td>
2625   <td>offset from the start of the file to the list of annotations for
2626     the method parameters. The offset should be to a location in the
2627     <code>data</code> section. The format of the data is specified by
2628     "<code>annotation_set_ref_list</code>" below.
2629   </td>
2630 </tr>
2631 </tbody>
2632 </table>
2633
2634 <h2><code>annotation_set_ref_list</code></h2>
2635 <h4>referenced from <code>parameter_annotations_item</code></h4>
2636 <h4>appears in the <code>data</code> section</h4>
2637 <h4>alignment: 4 bytes</h4>
2638
2639 <table class="format">
2640 <thead>
2641 <tr>
2642   <th>Name</th>
2643   <th>Format</th>
2644   <th>Description</th>
2645 </tr>
2646 </thead>
2647 <tbody>
2648 <tr>
2649   <td>size</td>
2650   <td>uint</td>
2651   <td>size of the list, in entries</td>
2652 </tr>
2653 <tr>
2654   <td>list</td>
2655   <td>annotation_set_ref_item[size]</td>
2656   <td>elements of the list</td>
2657 </tr>
2658 </tbody>
2659 </table>
2660
2661 <h3><code>annotation_set_ref_item</code> Format</h3>
2662
2663 <table class="format">
2664 <thead>
2665 <tr>
2666   <th>Name</th>
2667   <th>Format</th>
2668   <th>Description</th>
2669 </tr>
2670 </thead>
2671 <tbody>
2672 <tr>
2673   <td>annotations_off</td>
2674   <td>uint</td>
2675   <td>offset from the start of the file to the referenced annotation set
2676     or <code>0</code> if there are no annotations for this element.
2677     The offset, if non-zero, should be to a location in the <code>data</code>
2678     section. The format of the data is specified by
2679     "<code>annotation_set_item</code>" below.
2680   </td>
2681 </tr>
2682 </tbody>
2683 </table>
2684
2685 <h2><code>annotation_set_item</code></h2>
2686 <h4>referenced from <code>annotations_directory_item</code>,
2687 <code>field_annotations_item</code>,
2688 <code>method_annotations_item</code>, and
2689 <code>annotation_set_ref_item</code></h4>
2690 <h4>appears in the <code>data</code> section</h4>
2691 <h4>alignment: 4 bytes</h4>
2692
2693 <table class="format">
2694 <thead>
2695 <tr>
2696   <th>Name</th>
2697   <th>Format</th>
2698   <th>Description</th>
2699 </tr>
2700 </thead>
2701 <tbody>
2702 <tr>
2703   <td>size</td>
2704   <td>uint</td>
2705   <td>size of the set, in entries</td>
2706 </tr>
2707 <tr>
2708   <td>entries</td>
2709   <td>annotation_off_item[size]</td>
2710   <td>elements of the set. The elements must be sorted in increasing order,
2711     by <code>type_idx</code>.
2712   </td>
2713 </tr>
2714 </tbody>
2715 </table>
2716
2717 <h3><code>annotation_off_item</code> Format</h3>
2718
2719 <table class="format">
2720 <thead>
2721 <tr>
2722   <th>Name</th>
2723   <th>Format</th>
2724   <th>Description</th>
2725 </tr>
2726 </thead>
2727 <tbody>
2728 <tr>
2729   <td>annotation_off</td>
2730   <td>uint</td>
2731   <td>offset from the start of the file to an annotation.
2732     The offset should be to a location in the <code>data</code> section,
2733     and the format of the data at that location is specified by
2734     "<code>annotation_item</code>" below.
2735   </td>
2736 </tr>
2737 </tbody>
2738 </table>
2739
2740
2741 <h2><code>annotation_item</code></h2>
2742 <h4>referenced from <code>annotation_set_item</code></h4>
2743 <h4>appears in the <code>data</code> section</h4>
2744 <h4>alignment: none (byte-aligned)</h4>
2745
2746 <table class="format">
2747 <thead>
2748 <tr>
2749   <th>Name</th>
2750   <th>Format</th>
2751   <th>Description</th>
2752 </tr>
2753 </thead>
2754 <tbody>
2755 <tr>
2756   <td>visibility</td>
2757   <td>ubyte</td>
2758   <td>intended visibility of this annotation (see below)</td>
2759 </tr>
2760 <tr>
2761   <td>annotation</td>
2762   <td>encoded_annotation</td>
2763   <td>encoded annotation contents, in the format described by
2764     "<code>encoded_annotation</code> Format" under
2765     "<code>encoded_value</code> Encoding" above.
2766   </td>
2767 </tr>
2768 </tbody>
2769 </table>
2770
2771 <h3>Visibility values</h3>
2772
2773 <p>These are the options for the <code>visibility</code> field in an
2774 <code>annotation_item</code>:</p>
2775
2776 <table class="format">
2777 <thead>
2778 <tr>
2779   <th>Name</th>
2780   <th>Value</th>
2781   <th>Description</th>
2782 </tr>
2783 </thead>
2784 <tbody>
2785 <tr>
2786   <td>VISIBILITY_BUILD</td>
2787   <td>0x00</td>
2788   <td>intended only to be visible at build time (e.g., during compilation
2789     of other code)
2790   </td>
2791 </tr>
2792 <tr>
2793   <td>VISIBILITY_RUNTIME</td>
2794   <td>0x01</td>
2795   <td>intended to visible at runtime</td>
2796 </tr>
2797 <tr>
2798   <td>VISIBILITY_SYSTEM</td>
2799   <td>0x02</td>
2800   <td>intended to visible at runtime, but only to the underlying system
2801     (and not to regular user code)
2802   </td>
2803 </tr>
2804 </tbody>
2805 </table>
2806
2807 <h2><code>encoded_array_item</code></h2>
2808 <h4>referenced from <code>class_def_item</code></h4>
2809 <h4>appears in the <code>data</code> section</h4>
2810 <h4>alignment: none (byte-aligned)</h4>
2811
2812 <table class="format">
2813 <thead>
2814 <tr>
2815   <th>Name</th>
2816   <th>Format</th>
2817   <th>Description</th>
2818 </tr>
2819 </thead>
2820 <tbody>
2821 <tr>
2822   <td>value</td>
2823   <td>encoded_array</td>
2824   <td>bytes representing the encoded array value, in the format specified
2825     by "<code>encoded_array</code> Format" under "<code>encoded_value</code>
2826     Encoding" above.
2827   </td>
2828 </tr>
2829 </tbody>
2830 </table>
2831
2832 <h1>System Annotations</h1>
2833
2834 <p>System annotations are used to represent various pieces of reflective
2835 information about classes (and methods and fields). This information is
2836 generally only accessed indirectly by client (non-system) code.</p>
2837
2838 <p>System annotations are represented in <code>.dex</code> files as
2839 annotations with visibility set to <code>VISIBILITY_SYSTEM</code>.
2840
2841 <h2><code>dalvik.annotation.AnnotationDefault</code></h2>
2842 <h4>appears on methods in annotation interfaces</h4>
2843
2844 <p>An <code>AnnotationDefault</code> annotation is attached to each
2845 annotation interface which wishes to indicate default bindings.</p>
2846
2847 <table class="format">
2848 <thead>
2849 <tr>
2850   <th>Name</th>
2851   <th>Format</th>
2852   <th>Description</th>
2853 </tr>
2854 </thead>
2855 <tbody>
2856 <tr>
2857   <td>value</td>
2858   <td>Annotation</td>
2859   <td>the default bindings for this annotation, represented as an annotation
2860     of this type. The annotation need not include all names defined by the
2861     annotation; missing names simply do not have defaults.
2862   </td>
2863 </tr>
2864 </tbody>
2865 </table>
2866
2867 <h2><code>dalvik.annotation.EnclosingClass</code></h2>
2868 <h4>appears on classes</h4>
2869
2870 <p>An <code>EnclosingClass</code> annotation is attached to each class
2871 which is either defined as a member of another class, per se, or is
2872 anonymous but not defined within a method body (e.g., a synthetic
2873 inner class). Every class that has this annotation must also have an
2874 <code>InnerClass</code> annotation. Additionally, a class must not have
2875 both an <code>EnclosingClass</code> and an
2876 <code>EnclosingMethod</code> annotation.</p>
2877
2878 <table class="format">
2879 <thead>
2880 <tr>
2881   <th>Name</th>
2882   <th>Format</th>
2883   <th>Description</th>
2884 </tr>
2885 </thead>
2886 <tbody>
2887 <tr>
2888   <td>value</td>
2889   <td>Class</td>
2890   <td>the class which most closely lexically scopes this class</td>
2891 </tr>
2892 </tbody>
2893 </table>
2894
2895 <h2><code>dalvik.annotation.EnclosingMethod</code></h2>
2896 <h4>appears on classes</h4>
2897
2898 <p>An <code>EnclosingMethod</code> annotation is attached to each class
2899 which is defined inside a method body. Every class that has this
2900 annotation must also have an <code>InnerClass</code> annotation.
2901 Additionally, a class must not have both an <code>EnclosingClass</code>
2902 and an <code>EnclosingMethod</code> annotation.</p>
2903
2904 <table class="format">
2905 <thead>
2906 <tr>
2907   <th>Name</th>
2908   <th>Format</th>
2909   <th>Description</th>
2910 </tr>
2911 </thead>
2912 <tbody>
2913 <tr>
2914   <td>value</td>
2915   <td>Method</td>
2916   <td>the method which most closely lexically scopes this class</td>
2917 </tr>
2918 </tbody>
2919 </table>
2920
2921 <h2><code>dalvik.annotation.InnerClass</code></h2>
2922 <h4>appears on classes</h4>
2923
2924 <p>An <code>InnerClass</code> annotation is attached to each class
2925 which is defined in the lexical scope of another class's definition.
2926 Any class which has this annotation must also have <i>either</i> an
2927 <code>EnclosingClass</code> annotation <i>or</i> an
2928 <code>EnclosingMethod</code> annotation.</p>
2929
2930 <table class="format">
2931 <thead>
2932 <tr>
2933   <th>Name</th>
2934   <th>Format</th>
2935   <th>Description</th>
2936 </tr>
2937 </thead>
2938 <tbody>
2939 <tr>
2940   <td>name</td>
2941   <td>String</td>
2942   <td>the originally declared simple name of this class (not including any
2943     package prefix). If this class is anonymous, then the name is
2944     <code>null</code>.
2945   </td>
2946 </tr>
2947 <tr>
2948   <td>accessFlags</td>
2949   <td>int</td>
2950   <td>the originally declared access flags of the class (which may differ
2951     from the effective flags because of a mismatch between the execution
2952     models of the source language and target virtual machine)
2953   </td>
2954 </tr>
2955 </tbody>
2956 </table>
2957
2958 <h2><code>dalvik.annotation.MemberClasses</code></h2>
2959 <h4>appears on classes</h4>
2960
2961 <p>A <code>MemberClasses</code> annotation is attached to each class
2962 which declares member classes. (A member class is a direct inner class
2963 that has a name.)</p>
2964
2965 <table class="format">
2966 <thead>
2967 <tr>
2968   <th>Name</th>
2969   <th>Format</th>
2970   <th>Description</th>
2971 </tr>
2972 </thead>
2973 <tbody>
2974 <tr>
2975   <td>value</td>
2976   <td>Class[]</td>
2977   <td>array of the member classes</td>
2978 </tr>
2979 </tbody>
2980 </table>
2981
2982 <h2><code>dalvik.annotation.Signature</code></h2>
2983 <h4>appears on classes, fields, and methods</h4>
2984
2985 <p>A <code>Signature</code> annotation is attached to each class,
2986 field, or method which is defined in terms of a more complicated type
2987 than is representable by a <code>type_id_item</code>. The
2988 <code>.dex</code> format does not define the format for signatures; it
2989 is merely meant to be able to represent whatever signatures a source
2990 language requires for successful implementation of that language's
2991 semantics. As such, signatures are not generally parsed (or verified)
2992 by virtual machine implementations. The signatures simply get handed
2993 off to higher-level APIs and tools (such as debuggers). Any use of a
2994 signature, therefore, should be written so as not to make any
2995 assumptions about only receiving valid signatures, explicitly guarding
2996 itself against the possibility of coming across a syntactically
2997 invalid signature.</p>
2998
2999 <p>Because signature strings tend to have a lot of duplicated content,
3000 a <code>Signature</code> annotation is defined as an <i>array</i> of
3001 strings, where duplicated elements naturally refer to the same
3002 underlying data, and the signature is taken to be the concatenation of
3003 all the strings in the array. There are no rules about how to pull
3004 apart a signature into separate strings; that is entirely up to the
3005 tools that generate <code>.dex</code> files.</p>
3006
3007 <table class="format">
3008 <thead>
3009 <tr>
3010   <th>Name</th>
3011   <th>Format</th>
3012   <th>Description</th>
3013 </tr>
3014 </thead>
3015 <tbody>
3016 <tr>
3017   <td>value</td>
3018   <td>String[]</td>
3019   <td>the signature of this class or member, as an array of strings that
3020     is to be concatenated together</td>
3021 </tr>
3022 </tbody>
3023 </table>
3024
3025 <h2><code>dalvik.annotation.Throws</code></h2>
3026 <h4>appears on methods</h4>
3027
3028 <p>A <code>Throws</code> annotation is attached to each method which is
3029 declared to throw one or more exception types.</p>
3030
3031 <table class="format">
3032 <thead>
3033 <tr>
3034   <th>Name</th>
3035   <th>Format</th>
3036   <th>Description</th>
3037 </tr>
3038 </thead>
3039 <tbody>
3040 <tr>
3041   <td>value</td>
3042   <td>Class[]</td>
3043   <td>the array of exception types thrown</td>
3044 </tr>
3045 </tbody>
3046 </table>
3047
3048 </body>
3049 </html>