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