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