Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / dalvik / f6c387128427e121477c1b32ad35cdcaa5101ba3 / . / docs / dalvik-constraints.html
blob: 105225a7b7a5cfe7df103a5ce3b2addead2702c8 [file] [log] [blame]
The Android Open Source Projectf6c38712009-03-03 19:28:47 -0800[diff] [blame^]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
49The signature must be a SHA-1 hash of the whole file contents except magic,
50checksum, and signature.
51
52The file_size must match the actual file size in bytes.
53
54The header_size must have the value 0x70.
55
56The endian_tag must have either the value ENDIAN_CONSTANT or
57REVERSE_ENDIAN_CONSTANT.
58
59For each of the link, string_ids, type_ids, proto_ids, field_ids, method_ids, class_defs
60and data sections, the offset and size fields must be either both zero or both
61non-zero. In the latter case, the offset must be four-byte-aligned.
62
63All offset fields in the header except map_off must be four-byte-aligned.
64
65The map_off field must be either zero or point into the data section. In the
66latter case, the data section must exist.
67
68None of the link, string_ids, type_ids, proto_ids, field_ids, method_ids, class_defs
69and data sections must overlap each other or the header.
70
71If a map exists, then each map entry must have a valid type. Each type may
72appear at most once.
73
74If a map exists, then each map entry must have a nonzero offset and size. The
75offset must point into the corresponding section of the file (i.e. a
76string_id_item must point into the string_ids section) and the explicit or
77implicit size of the item must match the actual contents and size of the
78section.
79
80If a map exists, then the offset of map entry n+1 must be greater or equal to
81the offset of map entry n plus then size of map entry n. This implies
82non-overlapping entries and low-to-high ordering.
83
84The following types of entries must have an offset that is
85four-byte-aligned: string_id_item, type_id_item, proto_id_item, field_id_item,
86method_id_item, class_def_item, type_list, code_item,
87annotations_directory_item.
88
89For each string_id_item, the string_data_off field must contain a valid
90reference into the data section. For the referenced string_data_item, the data
91field must contain a valid MUTF-8 string, and the utf16_size must match the
92decoded length of the string.
93
94For each type_id_item, the desciptor_idx field must contain a valid reference
95into the string_ids list. The referenced string must be a valid type descriptor.
96
97For each proto_id_item, the shorty_idx field must contain a valid reference
98into the string_ids list. The referenced string must be a valid shorty descriptor.
99Also, the return_type_idx field must be a valid index into the type_ids section,
100and the parameters_off field must be either zero or a valid offset pointing
101into the data section. If nonzero, the parameter list must not contain any void
102entries.
103
104For each field_id_item, both the class_idx and type_idx fields must be a valid
105 indices into the
106type_ids list. The entry referenced by class_idx must be a non-array reference type.
107In addition, the name_idx field must be a valid reference into the string_ids
108section, and the contents of the referenced entry must conform to the MemberName
109specification.
110
111For each method_id_item, the class_idx field must be a valid index into the
112type_ids section, and the
113referenced entry must be a non-array reference type. The proto_id field must
114be a valid reference into the proto_ids list. The name_idx field must be a
115valid reference into the string_ids
116section, and the contents of the referenced entry must conform to the MemberName
117specification.
118
119For each class_def_item, ...
120
121For each field_id_item, the class_idx field must be a valid index into the
122type_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>