docs/dalvik-constraints.html

   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           <code>invoke-direct</code>.
 369         </td>
 370
 371         <td>
 372           4.8.1.14
 373         </td>
 374       </tr>
 375
 376       <tr>
 377         <td>
 378           A15
 379         </td>
 380
 381         <td>
 382           The <code>C</code> operand of the <code>invoke-interface</code>
 383           instruction must be a valid index into the method constant pool. The
 384           referenced <code>method_id</code> must belong to an interface (not a
 385           class).
 386         </td>
 387
 388         <td>
 389           4.8.1.15
 390         </td>
 391       </tr>
 392
 393       <tr>
 394         <td>
 395           A16
 396         </td>
 397
 398         <td>
 399           The <code>B</code> operand of the <code>invoke-interface/range</code>
 400           instruction must be a valid index into the method constant pool.
 401           The referenced <code>method_id</code> must belong to an interface (not
 402           a class).
 403         </td>
 404
 405         <td>
 406           4.8.1.15
 407         </td>
 408       </tr>
 409
 410       <tr>
 411         <td>
 412           A17
 413         </td>
 414
 415         <td>
 416           The <code>B</code> operand of the <code>const-class</code>,
 417           <code>check-cast</code>, <code>new-instance</code>, and
 418           <code>filled-new-array/range</code> instructions must be a valid index
 419           into the type constant pool.
 420         </td>
 421
 422         <td>
 423           4.8.1.16
 424         </td>
 425       </tr>
 426
 427       <tr>
 428         <td>
 429           A18
 430         </td>
 431
 432         <td>
 433           The <code>C</code> operand of the <code>instance-of</code>,
 434           <code>new-array</code>, and <code>filled-new-array</code>
 435           instructions must be a valid index into the type constant pool.
 436         </td>
 437
 438         <td>
 439           4.8.1.16
 440         </td>
 441       </tr>
 442
 443      <tr>
 444         <td>
 445           A19
 446         </td>
 447
 448         <td>
 449           The dimensions of an array created by a <code>new-array</code>
 450           instruction must be less than <code>256</code>.
 451         </td>
 452
 453         <td>
 454           4.8.1.17
 455         </td>
 456       </tr>
 457
 458       <tr>
 459         <td>
 460           A20
 461         </td>
 462
 463         <td>
 464           The <code>new</code> instruction must not refer to array classes,
 465           interfaces, or abstract classes.
 466         </td>
 467
 468         <td>
 469           4.8.1.18
 470         </td>
 471       </tr>
 472
 473       <tr>
 474         <td>
 475           A21
 476         </td>
 477
 478         <td>
 479           The type referred to by a <code>new-array</code> instruction must be
 480           a valid, non-reference type.
 481         </td>
 482
 483         <td>
 484           4.8.1.20
 485         </td>
 486       </tr>
 487
 488       <tr>
 489         <td>
 490           A22
 491         </td>
 492
 493         <td>
 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           <code>registers_size</code>.
 498         </td>
 499
 500         <td>
 501           4.8.1.21
 502         </td>
 503       </tr>
 504
 505       <tr>
 506         <td>
 507           A23
 508         </td>
 509
 510         <td>
 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 <code>registers_size-1</code>.
 514         </td>
 515
 516         <td>
 517           4.8.1.23
 518         </td>
 519       </tr>
 520     </table>
 521
 522     <h2>
 523       Structural constraints
 524     </h2>
 525
 526     <p>
 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>