Home | History | Annotate | Download | only in docs
      1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
      2 
      3 <html>
      4   <head>
      5     <title>Dalvik bytecode constraints</title>
      6     <link rel=stylesheet href="dalvik-constraints.css">
      7   </head>
      8 
      9   <body>
     10 
     11     <h1>Dalvik bytecode constraints</h1>
     12 
     13 <!--
     14     <h1>General integrity constraints</h1>
     15 
     16     <table>
     17       <tr>
     18         <th>
     19           Identifier
     20         </th>
     21 
     22         <th>
     23           Description
     24         </th>
     25       </tr>
     26 
     27       <tr>
     28         <td>
     29           A1
     30         </td>
     31 
     32         <td>
     33           The magic number of the DEX file must be "dex\n035\0".
     34         </td>
     35       </tr>
     36 
     37       <tr>
     38         <td>
     39           A1
     40         </td>
     41 
     42         <td>
     43           The checksum must be an Adler-32 checksum of the whole file contents
     44           except magic and checksum field.
     45         </td>
     46       </tr>
     47 
     48 
     49 The signature must be a SHA-1 hash of the whole file contents except magic,
     50 checksum, and signature.
     51 
     52 The file_size must match the actual file size in bytes.
     53 
     54 The header_size must have the value 0x70.
     55 
     56 The endian_tag must have either the value ENDIAN_CONSTANT or
     57 REVERSE_ENDIAN_CONSTANT.
     58 
     59 For each of the link, string_ids, type_ids, proto_ids, field_ids, method_ids, class_defs
     60 and data sections, the offset and size fields must be either both zero or both
     61 non-zero. In the latter case, the offset must be four-byte-aligned.
     62 
     63 All offset fields in the header except map_off must be four-byte-aligned.
     64 
     65 The map_off field must be either zero or point into the data section. In the
     66 latter case, the data section must exist.
     67 
     68 None of the link, string_ids, type_ids, proto_ids, field_ids, method_ids, class_defs
     69 and data sections must overlap each other or the header.
     70 
     71 If a map exists, then each map entry must have a valid type. Each type may
     72 appear at most once.
     73 
     74 If a map exists, then each map entry must have a nonzero offset and size. The
     75 offset must point into the corresponding section of the file (i.e. a
     76 string_id_item must point into the string_ids section) and the explicit or
     77 implicit size of the item must match the actual contents and size of the
     78 section.
     79 
     80 If a map exists, then the offset of map entry n+1 must be greater or equal to
     81 the offset of map entry n plus then size of map entry n. This implies
     82 non-overlapping entries and low-to-high ordering.
     83 
     84 The following types of entries must have an offset that is
     85 four-byte-aligned: string_id_item, type_id_item, proto_id_item, field_id_item,
     86 method_id_item, class_def_item, type_list, code_item,
     87 annotations_directory_item.
     88 
     89 For each string_id_item, the string_data_off field must contain a valid
     90 reference into the data section. For the referenced string_data_item, the data
     91 field must contain a valid MUTF-8 string, and the utf16_size must match the
     92 decoded length of the string.
     93 
     94 For each type_id_item, the desciptor_idx field must contain a valid reference
     95 into the string_ids list. The referenced string must be a valid type descriptor.
     96 
     97 For each proto_id_item, the shorty_idx field must contain a valid reference
     98 into the string_ids list. The referenced string must be a valid shorty descriptor.
     99 Also, the return_type_idx field must be a valid index into the type_ids section,
    100 and the parameters_off field must be either zero or a valid offset pointing
    101 into the data section. If nonzero, the parameter list must not contain any void
    102 entries.
    103 
    104 For each field_id_item, both the class_idx and type_idx fields must be a valid
    105  indices into the
    106 type_ids list. The entry referenced by class_idx must be a non-array reference type.
    107 In addition, the name_idx field must be a valid reference into the string_ids
    108 section, and the contents of the referenced entry must conform to the MemberName
    109 specification.
    110 
    111 For each method_id_item, the class_idx field must be a valid index into the
    112 type_ids section, and the
    113 referenced entry must be a non-array reference type. The proto_id field must
    114 be a valid reference into the proto_ids list. The name_idx field must be a
    115 valid reference into the string_ids
    116 section, and the contents of the referenced entry must conform to the MemberName
    117 specification.
    118 
    119 For each class_def_item, ...
    120 
    121 For each field_id_item, the class_idx field must be a valid index into the
    122 type_ids list. The referenced entry must be a non-array reference type.
    123 
    124 ...
    125 
    126 -->
    127 
    128     <h2>
    129       Static constraints
    130     </h2>
    131 
    132     <p>
    133     Static constraints are constraints on individual elements of the bytecode.
    134     They usually can be checked without employing control or data-flow analysis
    135     techniques.
    136     </p>
    137 
    138     <table>
    139       <tr>
    140         <th>
    141           Identifier
    142         </th>
    143 
    144         <th>
    145           Description
    146         </th>
    147 
    148         <th>
    149           Spec equivalent
    150         </th>
    151       </tr>
    152 
    153       <tr>
    154         <td>
    155           A1
    156         </td>
    157 
    158         <td>
    159           The <code>insns</code> array must not be empty.
    160         </td>
    161 
    162         <td>
    163           4.8.1.1
    164         </td>
    165       </tr>
    166 
    167       <tr>
    168         <td>
    169           A2
    170         </td>
    171 
    172         <td>
    173           The first opcode in the <code>insns</code> array must have index zero.
    174         </td>
    175 
    176         <td>
    177           4.8.1.3
    178         </td>
    179       </tr>
    180 
    181       <tr>
    182         <td>
    183           A3
    184         </td>
    185 
    186         <td>
    187           The <code>insns</code> array must only contain valid Dalvik opcodes.
    188         </td>
    189 
    190         <td>
    191           4.8.1.4
    192         </td>
    193       </tr>
    194 
    195       <tr>
    196         <td>
    197           A4
    198         </td>
    199 
    200         <td>
    201           The index of instruction <code>n+1</code> must equal the index of
    202           instruction <code>n</code> plus the length of instruction
    203           <code>n</code>, taking into account possible operands.
    204         </td>
    205 
    206         <td>
    207           4.8.1.5
    208         </td>
    209       </tr>
    210 
    211       <tr>
    212         <td>
    213           A5
    214         </td>
    215 
    216         <td>
    217           The last instruction in the <code>insns</code> array must end at index
    218           <code>insns_size-1</code>.
    219         </td>
    220 
    221         <td>
    222           4.8.1.6
    223         </td>
    224       </tr>
    225 
    226       <tr>
    227         <td>
    228           A6
    229         </td>
    230 
    231         <td>
    232           All <code>goto</code> and <code>if-&lt;kind&gt;</code> targets must
    233           be opcodes within in the same method.
    234         </td>
    235 
    236         <td>
    237           4.8.1.7
    238         </td>
    239       </tr>
    240 
    241       <tr>
    242         <td>
    243           A7
    244         </td>
    245 
    246         <td>
    247           All targets of a <code>packed-switch</code> instruction must be
    248           opcodes within in the same method. The size and the list of targets
    249           must be consistent.
    250         </td>
    251 
    252         <td>
    253           4.8.1.8
    254         </td>
    255       </tr>
    256 
    257       <tr>
    258         <td>
    259           A8
    260         </td>
    261 
    262         <td>
    263           All targets of a <code>sparse-switch</code> instruction must be
    264           opcodes within in the same method. The corresponding table must be
    265           consistent and sorted low-to-high.
    266         </td>
    267 
    268         <td>
    269           4.8.1.9
    270         </td>
    271       </tr>
    272 
    273       <tr>
    274         <td>
    275           A9
    276         </td>
    277 
    278         <td>
    279           The <code>B</code> operand of the <code>const-string</code> and
    280           <code>const-string/jumbo</code> instructions must be a valid index
    281           into the string constant pool.
    282         </td>
    283 
    284         <td>
    285           4.8.1.10
    286         </td>
    287       </tr>
    288 
    289       <tr>
    290         <td>
    291           A10
    292         </td>
    293 
    294         <td>
    295           The <code>C</code> operand of the <code>iget&lt;kind&gt;</code> and
    296           <code>iput&lt;kind&gt;</code> instructions must be a valid index into
    297           the field constant pool. The referenced entry must represent an
    298           instance field.
    299         </td>
    300 
    301         <td>
    302           4.8.1.12
    303         </td>
    304       </tr>
    305 
    306       <tr>
    307         <td>
    308           A11
    309         </td>
    310 
    311         <td>
    312           The <code>C</code> operand of the <code>sget&lt;kind&gt;</code> and
    313           <code>sput&lt;kind&gt;</code> instructions must be a valid index into
    314           the field constant pool. The referenced entry must represent a static
    315           field.
    316         </td>
    317 
    318         <td>
    319           4.8.1.12
    320         </td>
    321       </tr>
    322 
    323       <tr>
    324         <td>
    325           A12
    326         </td>
    327 
    328         <td>
    329           The <code>C</code> operand of the <code>invoke-virtual</code>,
    330           <code>invoke-super</code>, <code<invoke-direct</code> and
    331           <code>invoke-static</code> instructions must be a valid index into the
    332           method constant pool. In all cases, the referenced
    333           <code>method_id</code> must belong to a class (not an interface).
    334         </td>
    335 
    336         <td>
    337           4.8.1.13
    338         </td>
    339       </tr>
    340 
    341       <tr>
    342         <td>
    343           A13
    344         </td>
    345 
    346         <td>
    347           The <code>B</code> operand of the <code>invoke-virtual/range</code>,
    348           <code>invoke-super/range</code>, <code>invoke-direct/range</code>, and
    349           <code>invoke-static/range</code> instructions must be a valid index
    350           into the method constant pool. In all cases, the referenced
    351           <code>method_id</code> must belong to a class (not an interface).
    352         </td>
    353 
    354         <td>
    355           4.8.1.13
    356         </td>
    357       </tr>
    358 
    359       <tr>
    360         <td>
    361           A14
    362         </td>
    363 
    364         <td>
    365           A method the name of which starts with a '<' must only be invoked
    366           implicitly by the VM, not by code originating from a Dex file. The
    367           only exception is the instance initializer, which may be invoked by
    368           invoke-direct.
    369         
    370 
    371         
    372           4.8.1.14
    373         
    374       
    375 
    376       
    377         
    378           A15
    379         
    380 
    381         
    382           The C operand of the invoke-interface
    383           instruction must be a valid index into the method constant pool. The
    384           referenced method_id must belong to an interface (not a
    385           class).
    386         
    387 
    388         
    389           4.8.1.15
    390         
    391       
    392 
    393       
    394         
    395           A16
    396         
    397 
    398         
    399           The B operand of the invoke-interface/range
    400           instruction must be a valid index into the method constant pool.
    401           The referenced method_id must belong to an interface (not
    402           a class).
    403         
    404 
    405         
    406           4.8.1.15
    407         
    408       
    409 
    410       
    411         
    412           A17
    413         
    414 
    415         
    416           The B operand of the const-class,
    417           check-cast, new-instance, and
    418           filled-new-array/range instructions must be a valid index
    419           into the type constant pool.
    420         
    421 
    422         
    423           4.8.1.16
    424         
    425       
    426 
    427       
    428         
    429           A18
    430         
    431 
    432         
    433           The C operand of the instance-of,
    434           new-array, and filled-new-array
    435           instructions must be a valid index into the type constant pool.
    436         
    437 
    438         
    439           4.8.1.16
    440         
    441       
    442 
    443      
    444         
    445           A19
    446         
    447 
    448         
    449           The dimensions of an array created by a new-array
    450           instruction must be less than 256.
    451         
    452 
    453         
    454           4.8.1.17
    455         
    456       
    457 
    458       
    459         
    460           A20
    461         
    462 
    463         
    464           The new instruction must not refer to array classes,
    465           interfaces, or abstract classes.
    466         
    467 
    468         
    469           4.8.1.18
    470         
    471       
    472 
    473       
    474         
    475           A21
    476         
    477 
    478         
    479           The type referred to by a new-array instruction must be
    480           a valid, non-reference type.
    481         
    482 
    483         
    484           4.8.1.20
    485         
    486       
    487 
    488       
    489         
    490           A22
    491         
    492 
    493         
    494           All registers referred to by an instruction in a single-width
    495           (non-pair) fashion must be valid for the current method. That is,
    496           their indices must be non-negative and smaller than
    497           registers_size.
    498         
    499 
    500         
    501           4.8.1.21
    502         
    503       
    504 
    505       
    506         
    507           A23
    508         
    509 
    510         
    511           All registers referred to by an instruction in a double-width (pair)
    512           fashion must be valid for the current method. That is, their indices
    513           must be non-negative and smaller than registers_size-1.
    514         
    515 
    516         
    517           4.8.1.23
    518         
    519       
    520     
    521 
    522     

523 Structural constraints 524

525 526

527 Structural constraints are constraints on relationships between several 528 elements of the bytecode. They usually can't be checked without employing 529 control or data-flow analysis techniques. 530 </p> 531 532 <table> 533 <tr> 534 <th> 535 Identifier 536 </th> 537 538 <th> 539 Description 540 </th> 541 542 <th> 543 Spec equivalent 544 </th> 545 </tr> 546 547 <tr> 548 <td> 549 B1 550 </td> 551 552 <td> 553 The number and types of arguments (registers and immediate values) 554 must always match the instruction. 555 </td> 556 557 <td> 558 4.8.2.1 559 </td> 560 </tr> 561 562 <tr> 563 <td> 564 B2 565 </td> 566 567 <td> 568 Register pairs must never be broken up. 569 </td> 570 571 <td> 572 4.8.2.3 573 </td> 574 </tr> 575 576 <tr> 577 <td> 578 B3 579 </td> 580 581 <td> 582 A register (or pair) has to be assigned first before it can be 583 read. 584 </td> 585 586 <td> 587 4.8.2.4 588 </td> 589 </tr> 590 591 <tr> 592 <td> 593 B4 594 </td> 595 596 <td> 597 An <code>invoke-direct</code> instruction must only invoke an instance 598 initializer or a method in the current class or one of its 599 superclasses. 600 </td> 601 602 <td> 603 4.8.2.7 604 </td> 605 </tr> 606 607 <tr> 608 <td> 609 B5 610 </td> 611 612 <td> 613 An instance initializer must only be invoked on an uninitialized 614 instance. 615 </td> 616 617 <td> 618 4.8.2.8 619 </td> 620 </tr> 621 622 <tr> 623 <td> 624 B6 625 </td> 626 627 <td> 628 Instance methods may only be invoked on and instance fields may only 629 be accessed on already initialized instances. 630 </td> 631 632 <td> 633 4.8.2.9 634 </td> 635 </tr> 636 637 <tr> 638 <td> 639 B7 640 </td> 641 642 <td> 643 A register which holds the result of a <code>new-instance</code>code> 644 instruction must not be used if the same 645 <code>new-instance</code>code> instruction is again executed before 646 the instance is initialized. 647 </td> 648 649 <td> 650 4.8.2.10 651 </td> 652 </tr> 653 654 <tr> 655 <td> 656 B8 657 </td> 658 659 <td> 660 An instance initializer must call another instance initializer (same 661 class or superclass) before any instance members can be accessed. 662 Exceptions are non-inherited instance fields, which can be assigned 663 before calling another initializer, and the <code>Object</code> class 664 in general. 665 </td> 666 667 <td> 668 4.8.2.11 669 </td> 670 </tr> 671 672 <tr> 673 <td> 674 B9 675 </td> 676 677 <td> 678 All actual method arguments must be assignment-compatible with their 679 respective formal arguments. 680 </td> 681 682 <td> 683 4.8.2.12 684 </td> 685 </tr> 686 687 <tr> 688 <td> 689 B10 690 </td> 691 692 <td> 693 For each instance method invocation, the actual instance must be 694 assignment-compatible with the class or interface specified in the 695 instruction. 696 </td> 697 698 <td> 699 4.8.2.13 700 </td> 701 </tr> 702 703 <tr> 704 <td> 705 B11 706 </td> 707 708 <td> 709 A <code>return&lt;kind&gt;</code> instruction must match its 710 method's return type. 711 </td> 712 713 <td> 714 4.8.2.14 715 </td> 716 </tr> 717 718 <tr> 719 <td> 720 B12 721 </td> 722 723 <td> 724 When accessing protected members of a superclass, the actual type of 725 the instance being accessed must be either the current class or one 726 of its subclasses. 727 </td> 728 729 <td> 730 4.8.2.15 731 </td> 732 </tr> 733 734 <tr> 735 <td> 736 B13 737 </td> 738 739 <td> 740 The type of a value stored into a static field must be 741 assignment-compatible with or convertible to the field's type. 742 </td> 743 744 <td> 745 4.8.2.16 746 </td> 747 </tr> 748 749 <tr> 750 <td> 751 B14 752 </td> 753 754 <td> 755 The type of a value stored into a field must be assignment-compatible 756 with or convertible to the field's type. 757 </td> 758 759 <td> 760 4.8.2.17 761 </td> 762 </tr> 763 764 <tr> 765 <td> 766 B15 767 </td> 768 769 <td> 770 The type of every value stored into an array must be 771 assignment-compatible with the array's component type. 772 </td> 773 774 <td> 775 4.8.2.18 776 </td> 777 </tr> 778 779 <tr> 780 <td> 781 B16 782 </td> 783 784 <td> 785 The <code>A</code> operand of a <code>throw</code> instruction must 786 be assignment-compatible with <code>java.lang.Throwable</code>. 787 </td> 788 789 <td> 790 4.8.2.19 791 </td> 792 </tr> 793 794 <tr> 795 <td> 796 B17 797 </td> 798 799 <td> 800 The last reachable instruction of a method must either be a backwards 801 <code>goto</code> or branch, a <code>return</code>, or a 802 <code>throw</code> instruction. It must not be possible to leave the 803 <code>insns</code> array at the bottom. 804 </td> 805 806 <td> 807 4.8.2.20 808 </td> 809 </tr> 810 811 <tr> 812 <td> 813 B18 814 </td> 815 816 <td> 817 The unassigned half of a former register pair may not be read (is 818 considered invalid) until it has been re-assigned by some other 819 instruction. 820 </td> 821 822 <td> 823 4.8.2.3, 4.8.2.4 824 </td> 825 </tr> 826 827 <tr> 828 <td> 829 B19 830 </td> 831 832 <td> 833 A <code>move-result&lt;kind&gt;</code> instruction must be immediately 834 preceded (in the <code>insns</code> array) by an 835 <code>&lt;invoke-kind&gt;</code> instruction. The only exception is 836 the <code>move-result-object</code> instruction, which may also be 837 preceded by a <code>filled-new-array</code> instruction. 838 </td> 839 840 <td> 841 - 842 </td> 843 </tr> 844 845 <tr> 846 <td> 847 B20 848 </td> 849 850 <td> 851 A <code>move-result&lt;kind&gt;</code> instruction must be immediately 852 preceded (in actual control flow) by a matching 853 <code>return-&lt;kind&gt;</code> instruction (it must not be jumped 854 to). The only exception is the <code>move-result-object</code> 855 instruction, which may also be preceded by a 856 <code>filled-new-array</code> instruction. 857 </td> 858 859 <td> 860 - 861 </td> 862 </tr> 863 864 <tr> 865 <td> 866 B21 867 </td> 868 869 <td> 870 A <code>move-exception</code> instruction must only appear as the 871 first instruction in an exception handler. 872 </td> 873 874 <td> 875 - 876 </td> 877 </tr> 878 879 <tr> 880 <td> 881 B22 882 </td> 883 884 <td> 885 The <code>packed-switch-data</code>, <code>sparse-switch-data</code>, 886 and <code>fill-array-data</code> pseudo-instructions must not be 887 reachable by control flow. 888 </td> 889 890 <td> 891 - 892 </td> 893 </tr> 894 </table> 895 896 </body> 897 </html> 898