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