1page.title=Constraints 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 20 21<div id="qv-wrapper"> 22<div id="qv"> 23 <h2 id="Contents">In this document</h2> 24 <ol id="auto-toc"> 25 </ol> 26</div> 27</div> 28 29<p>A <code>.dex</code> file is the transport format for Dalvik Bytecode. There are certain 30syntactical and semantical constraints for a file to be a valid <code>.dex</code> file, and 31a runtime is required to support only valid .dex files.</p> 32 33 <h2 id="gen-constraints">General .dex integrity constraints</h2> 34 35 <p>General integrity constraints are concerned with the larger structure of a 36 <code>.dex</code> file, as described in detail in <a href="dex-format.html"><code>.dex</code> 37 format</a>.</p> 38 39 <table> 40 <tr> 41 <th> 42 Identifier 43 </th> 44 45 <th> 46 Description 47 </th> 48 </tr> 49 50 <tr> 51 <td> 52 G1 53 </td> 54 55 <td> 56 The <code>magic</code> number of the <code>.dex</code> file must be 57 <code>dex\n035\0</code> or <code>dex\n037\0</code>. 58 </td> 59 </tr> 60 61 <tr> 62 <td> 63 G2 64 </td> 65 66 <td> 67 The checksum must be an Adler-32 checksum of the whole file contents 68 except <code>magic</code> and <code>checksum</code> field. 69 </td> 70 </tr> 71 72 <tr> 73 <td> 74 G3 75 </td> 76 77 <td> 78 The signature must be a SHA-1 hash of the whole file contents except <code>magic</code>, 79 <code>checksum</code>, and <code>signature</code>. 80 </td> 81 </tr> 82 83 <tr> 84 <td> 85 G4 86 </td> 87 88 <td> 89 The <code>file_size</code> must match the actual file size in bytes. 90 </td> 91 </tr> 92 93 94 <tr> 95 <td> 96 G5 97 </td> 98 99 <td> 100 The <code>header_size</code> must have the value: <code>0x70</code> 101 </td> 102 </tr> 103 104 <tr> 105 <td> 106 G6 107 </td> 108 109 <td> 110 The <code>endian_tag</code> must have either the value: 111 <code>ENDIAN_CONSTANT</code> or <code>REVERSE_ENDIAN_CONSTANT</code> 112 </td> 113 </tr> 114 115 <tr> 116 <td> 117 G7 118 </td> 119 120 <td> 121 For each of the <code>link</code>, <code>string_ids</code>, 122 <code>type_ids</code>, <code>proto_ids</code>, 123 <code>field_ids</code>, <code>method_ids</code>, <code>class_defs</code>, and 124 <code>data</code> sections, the <code>offset</code> and <code>size</code> fields must be 125 either both zero or both non-zero. In the latter case, the offset must be 126 four-byte-aligned. 127 </td> 128 </tr> 129 130 <tr> 131 <td> 132 G8 133 </td> 134 135 <td> 136 All offset fields in the header except <code>map_off</code> must be four-byte-aligned. 137 </td> 138 </tr> 139 140 <tr> 141 <td> 142 G9 143 </td> 144 145 <td> 146 The <code>map_off</code> field must be either zero or point into the 147 data section. In the latter case, the <code>data</code> section must exist. 148 </td> 149 </tr> 150 151 <tr> 152 <td> 153 G10 154 </td> 155 156 <td> 157 None of the <code>link</code>, <code>string_ids</code>, 158 <code>type_ids</code>, <code>proto_ids</code>, <code>field_ids</code>, 159 <code>method_ids</code>, <code>class_defs</code> and <code>data</code> sections 160 must overlap each other or the header. 161 </td> 162 </tr> 163 164 <tr> 165 <td> 166 G11 167 </td> 168 169 <td> 170 If a map exists, then each map entry must have a valid type. Each type may appear at most once. 171 </td> 172 </tr> 173 174 <tr> 175 <td> 176 G12 177 </td> 178 179 <td> 180 If a map exists, then each map entry must have a non-zero offset and 181 size. The offset must point into the corresponding section of the file (i.e. a 182 <code>string_id_item</code> must point into the <code>string_ids</code> section) and the explicit or 183 implicit size of the item must match the actual contents and size of the 184 section. 185 </td> 186 </tr> 187 188 <tr> 189 <td> 190 G13 191 </td> 192 193 <td> 194 If a map exists, then the offset of map entry <code>n+1</code> must be greater or 195 equal to the offset of map entry <code>n plus than size of map entry n</code>. This implies 196 non-overlapping entries and low-to-high ordering. 197 </td> 198 </tr> 199 200 <tr> 201 <td> 202 G14 203 </td> 204 205 <td> 206 The following types of entries must have an offset that is 207 four-byte-aligned: <code>string_id_item</code>, 208 <code>type_id_item</code>, <code>proto_id_item</code>, 209 <code>field_id_item</code>, 210 <code>method_id_item</code>, <code>class_def_item</code>, 211 <code>type_list</code>, <code>code_item</code>, 212 <code>annotations_directory_item</code>. 213 </td> 214 </tr> 215 216 <tr> 217 <td> 218 G15 219 </td> 220 221 <td> 222 For each <code>string_id_item</code>, the <code>string_data_off</code> field must contain a 223 valid reference into the <code>data</code> section. For the referenced <code>string_data_item</code>, the 224 <code>data</code> field must contain a valid MUTF-8 string, and the <code>utf16_size</code> must match 225 the decoded length of the string. 226 </td> 227 </tr> 228 229 <tr> 230 <td> 231 G16 232 </td> 233 234 <td> 235 For each <code>type_id_item</code>, the <code>descriptor_idx</code> field must contain a valid 236 reference into the <code>string_ids</code> list. The referenced string must be a valid type 237 descriptor. 238 </td> 239 </tr> 240 241 <tr> 242 <td> 243 G17 244 </td> 245 246 <td> 247 For each <code>proto_id_item</code>, the <code>shorty_idx</code> field must contain a valid 248 reference into the <code>string_ids</code> list. The referenced string must be a valid 249 shorty descriptor. Also, the <code>return_type_idx</code> field must be a valid index into 250 the <code>type_ids</code> section, and the <code>parameters_off</code> field must be either zero or a 251 valid offset pointing into the <code>data</code> section. If non-zero, the parameter list 252 must not contain any void entries. 253 </td> 254 </tr> 255 256 <tr> 257 <td> 258 G18 259 </td> 260 261 <td> 262 For each <code>field_id_item</code>, both the <code>class_idx</code> and <code>type_idx</code> fields must 263 be valid indices into the <code>type_ids</code> list. The entry referenced by <code>class_idx</code> 264 must be a non-array reference type. In addition, the <code>name_idx</code> field must be a 265 valid reference into the <code>string_ids</code> section, and the contents of the referenced 266 entry must conform to the <code>MemberName</code> specification. 267 </td> 268 </tr> 269 270 <tr> 271 <td> 272 G19 273 </td> 274 275 <td> 276 For each <code>method_id_item</code>, the <code>class_idx</code> field must be a valid index 277 into the <code>type_ids</code> section, and the referenced entry must be a non-array 278 reference type. The <code>proto_id</code> field must be a valid reference into the <code>proto_ids</code> 279 list. The <code>name_idx</code> field must be a valid reference into the <code>string_ids</code> section, 280 and the contents of the referenced entry must conform to the <code>MemberName</code> 281 specification. 282 </td> 283 </tr> 284 285 <tr> 286 <td> 287 G20 288 </td> 289 290 <td> 291 For each <code>field_id_item</code>, the <code>class_idx</code> field must be a valid index 292 into the <code>type_ids</code> list. The referenced entry must be a non-array reference 293 type. 294 </td> 295 </tr> 296 297</table> 298 299<h2 id="static-constraints"> 300 Static bytecode constraints 301 </h2> 302 303 <p> 304 Static constraints are constraints on individual elements of the bytecode. 305 They usually can be checked without employing control or data-flow analysis 306 techniques. 307 </p> 308 309 <table> 310 <tr> 311 <th> 312 Identifier 313 </th> 314 315 <th> 316 Description 317 </th> 318 </tr> 319 320 <tr> 321 <td> 322 A1 323 </td> 324 325 <td> 326 The <code>insns</code> array must not be empty. 327 </td> 328 </tr> 329 330 <tr> 331 <td> 332 A2 333 </td> 334 335 <td> 336 The first opcode in the <code>insns</code> array must have index zero. 337 </td> 338 </tr> 339 340 <tr> 341 <td> 342 A3 343 </td> 344 345 <td> 346 The <code>insns</code> array must contain only valid Dalvik opcodes. 347 </td> 348 </tr> 349 350 <tr> 351 <td> 352 A4 353 </td> 354 355 <td> 356 The index of instruction <code>n+1</code> must equal the index of 357 instruction <code>n</code> plus the length of instruction 358 <code>n</code>, taking into account possible operands. 359 </td> 360 </tr> 361 362 <tr> 363 <td> 364 A5 365 </td> 366 367 <td> 368 The last instruction in the <code>insns</code> array must end at index 369 <code>insns_size-1</code>. 370 </td> 371 </tr> 372 373 <tr> 374 <td> 375 A6 376 </td> 377 378 <td> 379 All <code>goto</code> and <code>if-<kind></code> targets must 380 be opcodes within the same method. 381 </td> 382 </tr> 383 384 <tr> 385 <td> 386 A7 387 </td> 388 389 <td> 390 All targets of a <code>packed-switch</code> instruction must be 391 opcodes within the same method. The size and the list of targets 392 must be consistent. 393 </td> 394 </tr> 395 396 <tr> 397 <td> 398 A8 399 </td> 400 401 <td> 402 All targets of a <code>sparse-switch</code> instruction must be 403 opcodes within the same method. The corresponding table must be 404 consistent and sorted low-to-high. 405 </td> 406 </tr> 407 408 <tr> 409 <td> 410 A9 411 </td> 412 413 <td> 414 The <code>B</code> operand of the <code>const-string</code> and 415 <code>const-string/jumbo</code> instructions must be a valid index 416 into the string constant pool. 417 </td> 418 </tr> 419 420 <tr> 421 <td> 422 A10 423 </td> 424 425 <td> 426 The <code>C</code> operand of the <code>iget<kind></code> and 427 <code>iput<kind></code> instructions must be a valid index into 428 the field constant pool. The referenced entry must represent an 429 instance field. 430 </td> 431 </tr> 432 433 <tr> 434 <td> 435 A11 436 </td> 437 438 <td> 439 The <code>C</code> operand of the <code>sget<kind></code> and 440 <code>sput<kind></code> instructions must be a valid index into 441 the field constant pool. The referenced entry must represent a static 442 field. 443 </td> 444 </tr> 445 446 <tr> 447 <td> 448 A12 449 </td> 450 451 <td> 452 The <code>C</code> operand of the <code>invoke-virtual</code>, 453 <code>invoke-super</code>, <code>invoke-direct</code> and 454 <code>invoke-static</code> instructions must be a valid index into the 455 method constant pool. 456 </td> 457 </tr> 458 459 <tr> 460 <td> 461 A13 462 </td> 463 464 <td> 465 The <code>B</code> operand of the <code>invoke-virtual/range</code>, 466 <code>invoke-super/range</code>, <code>invoke-direct/range</code>, and 467 <code>invoke-static/range</code> instructions must be a valid index 468 into the method constant pool. 469 </td> 470 </tr> 471 472 <tr> 473 <td> 474 A14 475 </td> 476 477 <td> 478 A method the name of which starts with a '<' must only be invoked 479 implicitly by the VM, not by code originating from a <code>.dex</code> file. The 480 only exception is the instance initializer, which may be invoked by 481 <code>invoke-direct</code>. 482 </td> 483 </tr> 484 485 <tr> 486 <td> 487 A15 488 </td> 489 490 <td> 491 The <code>C</code> operand of the <code>invoke-interface</code> 492 instruction must be a valid index into the method constant pool. The 493 referenced <code>method_id</code> must belong to an interface (not a 494 class). 495 </td> 496 </tr> 497 498 <tr> 499 <td> 500 A16 501 </td> 502 503 <td> 504 The <code>B</code> operand of the <code>invoke-interface/range</code> 505 instruction must be a valid index into the method constant pool. 506 The referenced <code>method_id</code> must belong to an interface (not 507 a class). 508 </td> 509 </tr> 510 511 <tr> 512 <td> 513 A17 514 </td> 515 516 <td> 517 The <code>B</code> operand of the <code>const-class</code>, 518 <code>check-cast</code>, <code>new-instance</code>, and 519 <code>filled-new-array/range</code> instructions must be a valid index 520 into the type constant pool. 521 </td> 522 </tr> 523 524 <tr> 525 <td> 526 A18 527 </td> 528 529 <td> 530 The <code>C</code> operand of the <code>instance-of</code>, 531 <code>new-array</code>, and <code>filled-new-array</code> 532 instructions must be a valid index into the type constant pool. 533 </td> 534 </tr> 535 536 <tr> 537 <td> 538 A19 539 </td> 540 541 <td> 542 The dimensions of an array created by a <code>new-array</code> 543 instruction must be less than <code>256</code>. 544 </td> 545 </tr> 546 547 <tr> 548 <td> 549 A20 550 </td> 551 552 <td> 553 The <code>new</code> instruction must not refer to array classes, 554 interfaces, or abstract classes. 555 </td> 556 </tr> 557 558 <tr> 559 <td> 560 A21 561 </td> 562 563 <td> 564 The type referred to by a <code>new-array</code> instruction must be 565 a valid, non-reference type. 566 </td> 567 </tr> 568 569 <tr> 570 <td> 571 A22 572 </td> 573 574 <td> 575 All registers referred to by an instruction in a single-width 576 (non-pair) fashion must be valid for the current method. That is, 577 their indices must be non-negative and smaller than 578 <code>registers_size</code>. 579 </td> 580 </tr> 581 582 <tr> 583 <td> 584 A23 585 </td> 586 587 <td> 588 All registers referred to by an instruction in a double-width (pair) 589 fashion must be valid for the current method. That is, their indices 590 must be non-negative and smaller than <code>registers_size-1</code>. 591 </td> 592 </tr> 593 <tr> 594 <td> 595 A24 596 </td> 597 598 <td> 599 The <code>method_id</code> operand of the <code>invoke-virtual</code> 600 and <code>invoke-direct</code> instructions must belong to a class 601 (not an interface). In Dex files prior to version <code>037</code> 602 the same must be true of <code>invoke-super</code> and 603 <code>invoke-static</code> instructions. 604 </td> 605 </tr> 606 607 <tr> 608 <td> 609 A25 610 </td> 611 612 <td> 613 The <code>method_id</code> operand of the 614 <code>invoke-virtual/range</code> and 615 <code>invoke-direct/range</code> instructions must belong to a class 616 (not an interface). In Dex files prior to version <code>037</code> 617 the same must be true of <code>invoke-super/range</code> and 618 <code>invoke-static/range</code> instructions. 619 </td> 620 </tr> 621 </table> 622 623 <h2 id="struct-constraints"> 624 Structural bytecode constraints 625 </h2> 626 627 <p> 628 Structural constraints are constraints on relationships between several 629 elements of the bytecode. They usually can't be checked without employing 630 control or data-flow analysis techniques. 631 </p> 632 633 <table> 634 <tr> 635 <th> 636 Identifier 637 </th> 638 639 <th> 640 Description 641 </th> 642 </tr> 643 644 <tr> 645 <td> 646 B1 647 </td> 648 649 <td> 650 The number and types of arguments (registers and immediate values) 651 must always match the instruction. 652 </td> 653 </tr> 654 655 <tr> 656 <td> 657 B2 658 </td> 659 660 <td> 661 Register pairs must never be broken up. 662 </td> 663 </tr> 664 665 <tr> 666 <td> 667 B3 668 </td> 669 670 <td> 671 A register (or pair) has to be assigned first before it can be 672 read. 673 </td> 674 </tr> 675 676 <tr> 677 <td> 678 B4 679 </td> 680 681 <td> 682 An <code>invoke-direct</code> instruction must invoke an instance 683 initializer or a method only in the current class or one of its 684 superclasses. 685 </td> 686 </tr> 687 688 <tr> 689 <td> 690 B5 691 </td> 692 693 <td> 694 An instance initializer must be invoked only on an uninitialized 695 instance. 696 </td> 697 </tr> 698 699 <tr> 700 <td> 701 B6 702 </td> 703 704 <td> 705 Instance methods may be invoked only on and instance fields may only 706 be accessed on already initialized instances. 707 </td> 708 </tr> 709 710 <tr> 711 <td> 712 B7 713 </td> 714 715 <td> 716 A register that holds the result of a <code>new-instance</code> 717 instruction must not be used if the same 718 <code>new-instance</code> instruction is again executed before 719 the instance is initialized. 720 </td> 721 </tr> 722 723 <tr> 724 <td> 725 B8 726 </td> 727 728 <td> 729 An instance initializer must call another instance initializer (same 730 class or superclass) before any instance members can be accessed. 731 Exceptions are non-inherited instance fields, which can be assigned 732 before calling another initializer, and the <code>Object</code> class 733 in general. 734 </td> 735 </tr> 736 737 <tr> 738 <td> 739 B9 740 </td> 741 742 <td> 743 All actual method arguments must be assignment-compatible with their 744 respective formal arguments. 745 </td> 746 </tr> 747 748 <tr> 749 <td> 750 B10 751 </td> 752 753 <td> 754 For each instance method invocation, the actual instance must be 755 assignment-compatible with the class or interface specified in the 756 instruction. 757 </td> 758 </tr> 759 760 <tr> 761 <td> 762 B11 763 </td> 764 765 <td> 766 A <code>return<kind></code> instruction must match its 767 method's return type. 768 </td> 769 </tr> 770 771 <tr> 772 <td> 773 B12 774 </td> 775 776 <td> 777 When accessing protected members of a superclass, the actual type of 778 the instance being accessed must be either the current class or one 779 of its subclasses. 780 </td> 781 </tr> 782 783 <tr> 784 <td> 785 B13 786 </td> 787 788 <td> 789 The type of a value stored into a static field must be 790 assignment-compatible with or convertible to the field's type. 791 </td> 792 </tr> 793 794 <tr> 795 <td> 796 B14 797 </td> 798 799 <td> 800 The type of a value stored into a field must be assignment-compatible 801 with or convertible to the field's type. 802 </td> 803 </tr> 804 805 <tr> 806 <td> 807 B15 808 </td> 809 810 <td> 811 The type of every value stored into an array must be 812 assignment-compatible with the array's component type. 813 </td> 814 </tr> 815 816 <tr> 817 <td> 818 B16 819 </td> 820 821 <td> 822 The <code>A</code> operand of a <code>throw</code> instruction must 823 be assignment-compatible with <code>java.lang.Throwable</code>. 824 </td> 825 </tr> 826 827 <tr> 828 <td> 829 B17 830 </td> 831 832 <td> 833 The last reachable instruction of a method must either be a backwards 834 <code>goto</code> or branch, a <code>return</code>, or a 835 <code>throw</code> instruction. It must not be possible to leave the 836 <code>insns</code> array at the bottom. 837 </td> 838 </tr> 839 840 <tr> 841 <td> 842 B18 843 </td> 844 845 <td> 846 The unassigned half of a former register pair may not be read (is 847 considered invalid) until it has been re-assigned by some other 848 instruction. 849 </td> 850 </tr> 851 852 <tr> 853 <td> 854 B19 855 </td> 856 857 <td> 858 A <code>move-result<kind></code> instruction must be immediately 859 preceded (in the <code>insns</code> array) by an 860 <code>invoke-<kind></code> instruction. The only exception is 861 the <code>move-result-object</code> instruction, which may also be 862 preceded by a <code>filled-new-array</code> instruction. 863 </td> 864 </tr> 865 866 <tr> 867 <td> 868 B20 869 </td> 870 871 <td> 872 A <code>move-result<kind></code> instruction must be immediately 873 preceded (in actual control flow) by a matching 874 <code>return-<kind></code> instruction (it must not be jumped 875 to). The only exception is the <code>move-result-object</code> 876 instruction, which may also be preceded by a 877 <code>filled-new-array</code> instruction. 878 </td> 879 </tr> 880 881 <tr> 882 <td> 883 B21 884 </td> 885 886 <td> 887 A <code>move-exception</code> instruction must appear only as the 888 first instruction in an exception handler. 889 </td> 890 </tr> 891 892 <tr> 893 <td> 894 B22 895 </td> 896 897 <td> 898 The <code>packed-switch-data</code>, <code>sparse-switch-data</code>, 899 and <code>fill-array-data</code> pseudo-instructions must not be 900 reachable by control flow. 901 </td> 902 </tr> 903 </table> 904