docs/java-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>Java bytecode constraints</title>
   6     <link rel=stylesheet href="java-constraints.css">
   7   </head>
   8
   9   <body>
  10     <h1>
  11       Bytecode constraints
  12     </h1>
  13
  14     <p>
  15       From the point of view of a piece of code written in the Java
  16       programming language or targeted in the same way to <code>.class</code>
  17       files, the Dalvik VM aims to behave in a way
  18       that is fully consistent with the language's definition.
  19       That is, the code running in Dalvik will behave the same as it
  20       would have running in any other virtual machine. This includes
  21       verification failures.
  22       The Dx/Dalvik system will check roughly the same
  23       constraints that any other VM would, except as noted in the file
  24       <a href="verifier.html">verifier.html</a>. The following table briefly
  25       lists all Dx/Dalvik verification constraints together their analogs
  26       from the book <i>The Java<super>TM</super> Language Specification</i>,
  27       second edition. In the numbering scheme, the first three
  28       elements refer to the specification chapter, the fourth one to the
  29       bullet inside that chapter. The failure mode specifies whether the
  30       constraint will fail during the Dx conversion or during verification in
  31       the VM itself.
  32     </p>
  33
  34     <h2>
  35       Static constraints
  36     </h2>
  37
  38     <p>
  39     Static constraints are constraints on individual elements of the bytecode.
  40     They usually can be checked without employing control or data-flow analysis
  41     techniques.
  42     </p>
  43
  44     <table>
  45       <tr>
  46         <th>
  47           Identifier
  48         </th>
  49
  50         <th>
  51           Description
  52         </th>
  53
  54         <th>
  55           Spec equivalent
  56         </th>
  57
  58         <th>
  59           Failure mode
  60         </th>
  61       </tr>
  62
  63       <tr>
  64         <td>
  65           A1
  66         </td>
  67
  68         <td>
  69           The <code>code</code> array must not be empty.
  70         </td>
  71
  72         <td>
  73           4.8.1.1
  74         </td>
  75
  76         <td>
  77           DX
  78         </td>
  79       </tr>
  80
  81       <tr>
  82         <td>
  83           A2
  84         </td>
  85
  86         <td>
  87           The <code>code</code> array must not be larger than 65535 bytes.
  88         </td>
  89
  90         <td>
  91           4.8.1.2
  92         </td>
  93
  94         <td>
  95           DX
  96         </td>
  97       </tr>
  98
  99       <tr>
 100         <td>
 101           A3
 102         </td>
 103
 104         <td>
 105           The first opcode in <code>code</code> array must have index
 106           <code>0</code>.
 107         </td>
 108
 109         <td>
 110           4.8.1.3
 111         </td>
 112
 113         <td>
 114           DX
 115         </td>
 116       </tr>
 117
 118       <tr>
 119         <td>
 120           A4
 121         </td>
 122
 123         <td>
 124           The <code>code</code> array must only contain valid opcodes.
 125         </td>
 126
 127         <td>
 128           4.8.1.4
 129         </td>
 130
 131         <td>
 132           DX
 133         </td>
 134       </tr>
 135
 136       <tr>
 137         <td>
 138           A5
 139         </td>
 140
 141         <td>
 142           The index of instruction <code>n+1</code> must equal the index of
 143           instruction <code>n</code> plus the length of instruction
 144           <code>n</code>, taking into account a possible <code>wide</code>
 145           instruction. Opcodes modified by a <code>wide</code> instruction must
 146           not be directly reachable.
 147         </td>
 148
 149         <td>
 150           4.8.1.5
 151         </td>
 152
 153         <td>
 154           DX
 155         </td>
 156       </tr>
 157
 158       <tr>
 159         <td>
 160           A6
 161         </td>
 162
 163         <td>
 164           The last instruction in <code>code</code> array must end at index
 165           <code>code_length-1</code>.
 166         </td>
 167
 168         <td>
 169           4.8.1.6
 170         </td>
 171
 172         <td>
 173           DX
 174         </td>
 175       </tr>
 176
 177       <tr>
 178         <td>
 179           A7
 180         </td>
 181
 182         <td>
 183           All jump and branch targets must be opcodes within the same method.
 184           Opcodes modified by a <code>wide</code> instruction must not be
 185           directly reachable via a jump or branch instruction.
 186         </td>
 187
 188         <td>
 189           4.8.1.7
 190         </td>
 191
 192         <td>
 193           DX
 194         </td>
 195       </tr>
 196
 197       <tr>
 198         <td>
 199           A8
 200         </td>
 201
 202         <td>
 203           All targets of a <code>tableswitch</code> instruction must be opcodes
 204           within the same method. Upper and lower bounds must be consistent.
 205           Opcodes modified by a <code>wide</code> instruction must not be
 206           directly reachable via a <code>tableswitch</code> instruction.
 207         </td>
 208
 209         <td>
 210           4.8.1.8
 211         </td>
 212
 213         <td>
 214           DX
 215         </td>
 216       </tr>
 217
 218       <tr>
 219         <td>
 220           A9
 221         </td>
 222
 223         <td>
 224           All targets of a <code>lookupswitch</code> instruction must be opcodes
 225           within the same method. Its table must be consistent and sorted
 226           low-to-high. Opcodes modified by a <code>wide</code> instruction must
 227           not be directly reachable via a <code>lookupswitch</code> instruction.
 228         </td>
 229
 230         <td>
 231           4.8.1.9
 232         </td>
 233
 234         <td>
 235           DX
 236         </td>
 237       </tr>
 238
 239       <tr>
 240         <td>
 241           A10
 242         </td>
 243
 244         <td>
 245           The operands of <code>ldc</code> and <code>ldc_w</code> instructions
 246           must be valid indices into the constant pool. The respective entries
 247           must be of type <code>CONSTANT_Integer</code>,
 248           <code>CONSTANT_Float</code>, or <code>CONSTANT_String</code>.
 249         </td>
 250
 251         <td>
 252           4.8.1.10
 253         </td>
 254
 255         <td>
 256           DX
 257         </td>
 258       </tr>
 259
 260       <tr>
 261         <td>
 262           A11
 263         </td>
 264
 265         <td>
 266           The operands of <code>ldc2_w</code> instructions must be valid indices
 267           into the constant pool. The respective entries must be of type
 268           <code>CONSTANT_Long</code> or <code>CONSTANT_Double</code>. The
 269           subsequent constant pool entry must be valid and remain unused.
 270         </td>
 271
 272         <td>
 273           4.8.1.11
 274         </td>
 275
 276         <td>
 277           DX
 278         </td>
 279       </tr>
 280
 281       <tr>
 282         <td>
 283           A12
 284         </td>
 285
 286         <td>
 287           The Operands of <code>get&lt;kind&gt;</code> and
 288           <code>put&lt;kind&gt;</code> instructions must be valid indices into
 289           constant pool. The respective entries must be of type
 290           <code>CONSTANT_Fieldref</code>.
 291         </td>
 292
 293         <td>
 294           4.8.1.12
 295         </td>
 296
 297         <td>
 298           DX
 299         </td>
 300       </tr>
 301
 302       <tr>
 303         <td>
 304           A13
 305         </td>
 306
 307         <td>
 308           The first two operands of <code>invokevirtual</code>,
 309           <code>invokespecial</code>, and <code>invokestatic</code> must form a
 310           valid 16-bit index into the constant pool. The respective entries must
 311           be of type <code>CONSTANT_Methodref</code>.
 312         </td>
 313
 314         <td>
 315           4.8.1.13
 316         </td>
 317
 318         <td>
 319           DX
 320         </td>
 321       </tr>
 322
 323       <tr>
 324         <td>
 325           A14
 326         </td>
 327
 328         <td>
 329           Methods whose names start with '<' must only be invoked implicitly by
 330           the VM, not by class file code. The only exception is the instance
 331           initializer, which may be invoked by <code>invokespecial</code>.
 332         </td>
 333
 334         <td>
 335           4.8.1.14
 336         </td>
 337
 338         <td>
 339           DX
 340         </td>
 341       </tr>
 342
 343       <tr>
 344         <td>
 345           A15
 346         </td>
 347
 348         <td>
 349           The first two operands of <code>invokeinterface</code> must form a
 350           valid 16-bit index into the constant pool. The entry must be of type
 351           <code>CONSTANT_Interface_Methodref</code>. The third operand must
 352           specify number of local variables and the fourth operand must always
 353           be zero.
 354         </td>
 355
 356         <td>
 357           4.8.1.15
 358         </td>
 359
 360         <td>
 361           DX
 362         </td>
 363       </tr>
 364
 365       <tr>
 366         <td>
 367           A16
 368         </td>
 369
 370         <td>
 371           The operands of <code>instanceof</code>, <code>checkcast</code>,
 372           <code>new</code>, and <code>anewarray</code> instructions must
 373           be a valid index into the constant pool. The first two operands of
 374           <code>multianewarray</code> instruction must form a valid 16-bit index
 375           into the constant pool. All respective entries must be of type
 376           <code>CONSTANT_Class</code>.
 377         </td>
 378
 379         <td>
 380           4.8.1.16
 381         </td>
 382
 383         <td>
 384           DX
 385         </td>
 386       </tr>
 387
 388      <tr>
 389         <td>
 390           A17
 391         </td>
 392
 393         <td>
 394           The dimensions of an array created by <code>anewarray</code>
 395           instructions must be less than <code>256</code>.
 396         </td>
 397
 398         <td>
 399           4.8.1.17
 400         </td>
 401
 402         <td>
 403           DX
 404         </td>
 405       </tr>
 406
 407       <tr>
 408         <td>
 409           A18
 410         </td>
 411
 412         <td>
 413           The <code>new</code> instruction must not reference array classes,
 414           interfaces, or abstract classes.
 415         </td>
 416
 417         <td>
 418           4.8.1.18
 419         </td>
 420
 421         <td>
 422           DX
 423         </td>
 424       </tr>
 425
 426       <tr>
 427         <td>
 428           A19
 429         </td>
 430
 431         <td>
 432           The type referenced by a <code>multinewarray</code> instruction must
 433           have at least as many dimensions as specified in the instruction. The
 434           dimensions operand must not be <code>0</code>
 435         </td>
 436
 437         <td>
 438           4.8.1.19
 439         </td>
 440
 441         <td>
 442           DX
 443         </td>
 444       </tr>
 445
 446       <tr>
 447         <td>
 448           A20
 449         </td>
 450
 451         <td>
 452           The type referenced by a <code>newarray</code> instruction must be a
 453           valid, non-reference type.
 454         </td>
 455
 456         <td>
 457           4.8.1.20
 458         </td>
 459
 460         <td>
 461           DX
 462         </td>
 463       </tr>
 464
 465       <tr>
 466         <td>
 467           A21
 468         </td>
 469
 470         <td>
 471           The index operand of instructions explicitly referencing single-width
 472           local variables must be non-negative and smaller than
 473           <code>max_locals</code>.
 474         </td>
 475
 476         <td>
 477           4.8.1.21
 478         </td>
 479
 480         <td>
 481           DX
 482         </td>
 483       </tr>
 484
 485       <tr>
 486         <td>
 487           A22
 488         </td>
 489
 490         <td>
 491           The index operand of instructions implicitly referencing single-width
 492           local variables must be non-negative and smaller than
 493           <code>max_locals</code>.
 494         </td>
 495
 496         <td>
 497           4.8.1.22
 498         </td>
 499
 500         <td>
 501           DX
 502         </td>
 503       </tr>
 504
 505       <tr>
 506         <td>
 507           A23
 508         </td>
 509
 510         <td>
 511           The index operand of instructions explicitly referencing double-width
 512           local variables must be non-negative and smaller than
 513           <code>max_locals-1</code>.
 514         </td>
 515
 516         <td>
 517           4.8.1.23
 518         </td>
 519
 520         <td>
 521           DX
 522         </td>
 523       </tr>
 524
 525       <tr>
 526         <td>
 527           A24
 528         </td>
 529
 530         <td>
 531           The index operand of instructions implicitly referencing double-width
 532           local variables must be non-negative and smaller than
 533           <code>max_locals-1</code>.
 534         </td>
 535
 536         <td>
 537           4.8.1.24
 538         </td>
 539
 540         <td>
 541           DX
 542         </td>
 543       </tr>
 544
 545       <tr>
 546         <td>
 547           A25
 548         </td>
 549
 550         <td>
 551           The index operand of <code>wide</code> instructions explicitly
 552           referencing single-width local variables must be non-negative and
 553           smaller than <code>max_locals</code>.
 554         </td>
 555
 556         <td>
 557           4.8.1.25
 558         </td>
 559
 560         <td>
 561           DX
 562         </td>
 563       </tr>
 564
 565       <tr>
 566         <td>
 567           A26
 568         </td>
 569
 570         <td>
 571           The index operand of <code>wide</code> instructions explicitly
 572           referencing double-width local variables must be non-negative and
 573           smaller than <code>max_locals-1</code>.
 574         </td>
 575
 576         <td>
 577           4.8.1.25
 578         </td>
 579
 580         <td>
 581           DX
 582         </td>
 583       </tr>
 584     </table>
 585
 586     <h2>
 587       Structural constraints
 588     </h2>
 589
 590     <p>
 591     Structural constraints are constraints on relationships between several
 592     elements of the bytecode. They usually can't be checked without employing
 593     control or data-flow analysis techniques.
 594     </p>
 595
 596     <table>
 597       <tr>
 598         <th>
 599           Identifier
 600         </th>
 601
 602         <th>
 603           Description
 604         </th>
 605
 606         <th>
 607           Spec equivalent
 608         </th>
 609
 610         <th>
 611           Failure mode
 612         </th>
 613       </tr>
 614
 615       <tr>
 616         <td>
 617           B1
 618         </td>
 619
 620         <td>
 621           The number and types of arguments (operands and local variables) must
 622           always match the instruction.
 623         </td>
 624
 625         <td>
 626           4.8.2.1
 627         </td>
 628
 629         <td>
 630           DX
 631         </td>
 632       </tr>
 633
 634       <tr>
 635         <td>
 636           B2
 637         </td>
 638
 639         <td>
 640           The operand stack must have the same depth for all executions paths
 641           leading to an instruction.
 642         </td>
 643
 644         <td>
 645           4.8.2.2
 646         </td>
 647
 648         <td>
 649           DX
 650         </td>
 651       </tr>
 652
 653       <tr>
 654         <td>
 655           B3
 656         </td>
 657
 658         <td>
 659           Local variable pairs must never be broken up.
 660         </td>
 661
 662         <td>
 663           4.8.2.3
 664         </td>
 665
 666         <td>
 667           DX
 668         </td>
 669       </tr>
 670
 671       <tr>
 672         <td>
 673           B4
 674         </td>
 675
 676         <td>
 677           A local variable (or pair) has to be assigned first before it can be
 678           read.
 679         </td>
 680
 681         <td>
 682           4.8.2.4
 683         </td>
 684
 685         <td>
 686           DX
 687         </td>
 688       </tr>
 689
 690       <tr>
 691         <td>
 692           B5
 693         </td>
 694
 695         <td>
 696           The operand stack must never grow beyond <code>max_stack</code>.
 697         </td>
 698
 699         <td>
 700           4.8.2.5
 701         </td>
 702
 703         <td>
 704           DX
 705         </td>
 706       </tr>
 707
 708       <tr>
 709         <td>
 710           B6
 711         </td>
 712
 713         <td>
 714           The operand stack must never underflow.
 715         </td>
 716
 717         <td>
 718           4.8.2.6
 719         </td>
 720
 721         <td>
 722           DX
 723         </td>
 724       </tr>
 725
 726       <tr>
 727         <td>
 728           B7
 729         </td>
 730
 731         <td>
 732           An <code>invokespecial</code> instruction must only invoke an instance
 733           initializer or a method in the current class or one of its
 734           superclasses.
 735         </td>
 736
 737         <td>
 738           4.8.2.7
 739         </td>
 740
 741         <td>
 742           VM
 743         </td>
 744       </tr>
 745
 746       <tr>
 747         <td>
 748           B8
 749         </td>
 750
 751         <td>
 752           An instance initializer must only be invoked on an uninitialized
 753           instance residing on the operand stack.
 754         </td>
 755
 756         <td>
 757           4.8.2.8
 758         </td>
 759
 760         <td>
 761           VM
 762         </td>
 763       </tr>
 764
 765       <tr>
 766         <td>
 767           B9
 768         </td>
 769
 770         <td>
 771           Instance methods may only be invoked on and instance fields may only
 772           be accessed on already initialized instances.
 773         </td>
 774
 775         <td>
 776           4.8.2.9
 777         </td>
 778
 779         <td>
 780           VM
 781         </td>
 782       </tr>
 783
 784       <tr>
 785         <td>
 786           B10
 787         </td>
 788
 789         <td>
 790            The must be no backwards branches with uninitialized instances on the
 791            operand stack or in local variables. There must be no code protected
 792            by an exception handler that contains local variables with
 793            uninitialized instances.
 794         </td>
 795
 796         <td>
 797           4.8.2.10
 798         </td>
 799
 800         <td>
 801           DX
 802         </td>
 803       </tr>
 804
 805       <tr>
 806         <td>
 807           B11
 808         </td>
 809
 810         <td>
 811            An instance initializer must call another instance initializer (same
 812            class or superclass) before any instance members can be accessed.
 813            Exceptions are non-inherited instance fields, which can be assigned
 814            before calling another initializer, and the <code>Object</code> class
 815            in general.
 816         </td>
 817
 818         <td>
 819           4.8.2.11
 820         </td>
 821
 822         <td>
 823           VM
 824         </td>
 825       </tr>
 826
 827       <tr>
 828         <td>
 829           B12
 830         </td>
 831
 832         <td>
 833            All actual method arguments must be assignment-compatible with formal
 834            arguments.
 835         </td>
 836
 837         <td>
 838           4.8.2.12
 839         </td>
 840
 841         <td>
 842           VM
 843         </td>
 844       </tr>
 845
 846       <tr>
 847         <td>
 848           B13
 849         </td>
 850
 851         <td>
 852            For each instance method invocation, the actual instance must be
 853            assignment-compatible with the class or interface specified in the
 854            instruction.
 855         </td>
 856
 857         <td>
 858           4.8.2.13
 859         </td>
 860
 861         <td>
 862           VM
 863         </td>
 864       </tr>
 865
 866       <tr>
 867         <td>
 868           B14
 869         </td>
 870
 871         <td>
 872            A returns instruction must match its method's return type.
 873         </td>
 874
 875         <td>
 876           4.8.2.14
 877         </td>
 878
 879         <td>
 880           VM
 881         </td>
 882       </tr>
 883
 884       <tr>
 885         <td>
 886           B15
 887         </td>
 888
 889         <td>
 890            When accessing protected members of a superclass, the actual type of
 891            the instance being accessed must be either the current class or one
 892            of its subclasses.
 893         </td>
 894
 895         <td>
 896           4.8.2.15
 897         </td>
 898
 899         <td>
 900           VM
 901         </td>
 902       </tr>
 903
 904      <tr>
 905         <td>
 906           B16
 907         </td>
 908
 909         <td>
 910            The type of a value stored into a static field must be
 911            assignment-compatible with or convertible to the field's type.
 912         </td>
 913
 914         <td>
 915           4.8.2.16
 916         </td>
 917
 918         <td>
 919           VM
 920         </td>
 921       </tr>
 922
 923       <tr>
 924         <td>
 925           B17
 926         </td>
 927
 928         <td>
 929            The type of a value stored into a field must be assignment-compatible
 930            with or convertible to the field's type.
 931         </td>
 932
 933         <td>
 934           4.8.2.17
 935         </td>
 936
 937         <td>
 938           VM
 939         </td>
 940       </tr>
 941
 942       <tr>
 943         <td>
 944           B18
 945         </td>
 946
 947         <td>
 948            The type of every value stored into an array must be
 949            assignment-compatible with the array's component type.
 950         </td>
 951
 952         <td>
 953           4.8.2.18
 954         </td>
 955
 956         <td>
 957           VM
 958         </td>
 959       </tr>
 960
 961       <tr>
 962         <td>
 963           B19
 964         </td>
 965
 966         <td>
 967            The operand of an <code>athrow</code> instruction must be
 968            assignment-compatible with <code>java.lang.Throwable</code>.
 969         </td>
 970
 971         <td>
 972           4.8.2.19
 973         </td>
 974
 975         <td>
 976           VM
 977         </td>
 978       </tr>
 979
 980       <tr>
 981         <td>
 982           B20
 983         </td>
 984
 985         <td>
 986            The last reachable instruction of a method must either be a backwards
 987            jump or branch, a return, or an <code>athrow</code> instruction. It
 988            must not be possible to leave the <code>code</code> array at the
 989            bottom.
 990         </td>
 991
 992         <td>
 993           4.8.2.20
 994         </td>
 995
 996         <td>
 997           VM
 998         </td>
 999       </tr>
1000
1001       <tr>
1002         <td>
1003           B21
1004         </td>
1005
1006         <td>
1007            Local variable values must not be used as return addresses.
1008         </td>
1009
1010         <td>
1011           4.8.2.21
1012         </td>
1013
1014         <td>
1015           VM
1016         </td>
1017       </tr>
1018
1019       <tr>
1020         <td>
1021           B22
1022         </td>
1023
1024         <td>
1025           There must be a single, uniquely determined return instruction per
1026           subroutine call.
1027         </td>
1028
1029         <td>
1030           4.8.2.22
1031         </td>
1032
1033         <td>
1034           VM
1035         </td>
1036       </tr>
1037
1038       <tr>
1039         <td>
1040           B23
1041         </td>
1042
1043         <td>
1044           Subroutine calls must not be directly or indirectly self-recursive.
1045         </td>
1046
1047         <td>
1048           4.8.2.23
1049         </td>
1050
1051         <td>
1052           DX
1053         </td>
1054       </tr>
1055
1056       <tr>
1057         <td>
1058           B24
1059         </td>
1060
1061         <td>
1062            <code>ReturnAddress</code> instances must not be reused. If a
1063            subroutine returns to a <code>ReturnAddress</code> further up the
1064            stack than where its original call instruction is located, then all
1065            <code>ReturnAddress</code> instances further down the stack must
1066            never be used.
1067         </td>
1068
1069         <td>
1070           4.8.2.24
1071         </td>
1072
1073         <td>
1074           DX
1075         </td>
1076       </tr>
1077
1078     </table>
1079   </body>
1080 </html>