Blame - docs/dex-format.html - platform/dalvik

blob: 81c0b36455d0256e42cca2199fb23f4a11f93315 [file] [log] [blame]

The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[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
				5	<head>
				6	<title>.dex — Dalvik Executable Format</title>
				7	<link rel=stylesheet href="dex-format.css">
				8	</head>
				9
				10	<body>
				11
				12	<h1 class="title"><code>.dex</code> — Dalvik Executable Format</h1>
				13	<p>Copyright © 2007 The Android Open Source Project
				14
				15	<p>This document describes the layout and contents of <code>.dex</code>
				16	files, which are used to hold a set of class definitions and their associated
				17	adjunct data.</p>
				18
				19	<h1>Guide To Types</h1>
				20
				21	<table class="guide">
				22	<thead>
				23	<tr>
				24	<th>Name</th>
				25	<th>Description</th>
				26	</tr>
				27	</thead>
				28	<tbody>
				29	<tr>
				30	<td>byte</td>
				31	<td>8-bit signed int</td>
				32	</tr>
				33	<tr>
				34	<td>ubyte</td>
				35	<td>8-bit unsigned int</td>
				36	</tr>
				37	<tr>
				38	<td>short</td>
				39	<td>16-bit signed int, little-endian</td>
				40	</tr>
				41	<tr>
				42	<td>ushort</td>
				43	<td>16-bit unsigned int, little-endian</td>
				44	</tr>
				45	<tr>
				46	<td>int</td>
				47	<td>32-bit signed int, little-endian</td>
				48	</tr>
				49	<tr>
				50	<td>uint</td>
				51	<td>32-bit unsigned int, little-endian</td>
				52	</tr>
				53	<tr>
				54	<td>long</td>
				55	<td>64-bit signed int, little-endian</td>
				56	</tr>
				57	<tr>
				58	<td>ulong</td>
				59	<td>64-bit unsigned int, little-endian</td>
				60	</tr>
				61	<tr>
				62	<td>sleb128</td>
				63	<td>signed LEB128, variable-length (see below)</td>
				64	</tr>
				65	<tr>
				66	<td>uleb128</td>
				67	<td>unsigned LEB128, variable-length (see below)</td>
				68	</tr>
				69	<tr>
				70	<td>uleb128p1</td>
				71	<td>unsigned LEB128 plus <code>1</code>, variable-length (see below)</td>
				72	</tr>
				73	</tbody>
				74	</table>
				75
				76	<h3>LEB128</h3>
				77
				78	<p>LEB128 ("<b>L</b>ittle-<b>E</b>ndian <b>B</b>ase <b>128</b>") is a
				79	variable-length encoding for
				80	arbitrary signed or unsigned integer quantities. The format was
				81	borrowed from the <a href="http://dwarfstd.org/Dwarf3Std.php">DWARF3</a>
				82	specification. In a <code>.dex</code> file, LEB128 is only ever used to
				83	encode 32-bit quantities.</p>
				84
				85	<p>Each LEB128 encoded value consists of one to five
				86	bytes, which together represent a single 32-bit value. Each
				87	byte has its most significant bit set except for the final byte in the
				88	sequence, which has its most significant bit clear. The remaining
				89	seven bits of each byte are payload, with the least significant seven
				90	bits of the quantity in the first byte, the next seven in the second
				91	byte and so on. In the case of a signed LEB128 (<code>sleb128</code>),
				92	the most significant payload bit of the final byte in the sequence is
				93	sign-extended to produce the final value. In the unsigned case
				94	(<code>uleb128</code>), any bits not explicitly represented are
				95	interpreted as <code>0</code>.
				96
				97	<table class="leb128Bits">
				98	<thead>
				99	<tr><th colspan="16">Bitwise diagram of a two-byte LEB128 value</th></tr>
				100	<tr>
				101	<th colspan="8">First byte</td>
				102	<th colspan="8">Second byte</td>
				103	</tr>
				104	</thead>
				105	<tbody>
				106	<tr>
				107	<td class="start1"><code>1</code></td>
				108	<td>bit<sub>6</sub></td>
				109	<td>bit<sub>5</sub></td>
				110	<td>bit<sub>4</sub></td>
				111	<td>bit<sub>3</sub></td>
				112	<td>bit<sub>2</sub></td>
				113	<td>bit<sub>1</sub></td>
				114	<td>bit<sub>0</sub></td>
				115	<td class="start2"><code>0</code></td>
				116	<td>bit<sub>13</sub></td>
				117	<td>bit<sub>12</sub></td>
				118	<td>bit<sub>11</sub></td>
				119	<td>bit<sub>10</sub></td>
				120	<td>bit<sub>9</sub></td>
				121	<td>bit<sub>8</sub></td>
				122	<td class="end2">bit<sub>7</sub></td>
				123	</tr>
				124	</tbody>
				125	</table>
				126
				127	<p>The variant <code>uleb128p1</code> is used to represent a signed
				128	value, where the representation is of the value <i>plus one</i> encoded
				129	as a <code>uleb128</code>. This makes the encoding of <code>-1</code>
				130	(alternatively thought of as the unsigned value <code>0xffffffff</code>)
				131	— but no other negative number — a single byte, and is
				132	useful in exactly those cases where the represented number must either
				133	be non-negative or <code>-1</code> (or <code>0xffffffff</code>),
				134	and where no other negative values are allowed (or where large unsigned
				135	values are unlikely to be needed).</p>
				136
				137	<p>Here are some examples of the formats:</p>
				138
				139	<table class="leb128">
				140	<thead>
				141	<tr>
				142	<th>Encoded Sequence</th>
				143	<th>As <code>sleb128</code></th>
				144	<th>As <code>uleb128</code></th>
				145	<th>As <code>uleb128p1</code></th>
				146	</tr>
				147	</thead>
				148	<tbody>
				149	<tr><td>00</td><td>0</td><td>0</td><td>-1</td></tr>
				150	<tr><td>01</td><td>1</td><td>1</td><td>0</td></tr>
				151	<tr><td>7f</td><td>-1</td><td>127</td><td>126</td></tr>
				152	<tr><td>80 7f</td><td>-128</td><td>16256</td><td>16255</td></tr>
				153	</tbody>
				154	</table>
				155
				156	<h1>Overall File Layout</h1>
				157
				158	<table class="format">
				159	<thead>
				160	<tr>
				161	<th>Name</th>
				162	<th>Format</th>
				163	<th>Description</th>
				164	</tr>
				165	</thead>
				166	<tbody>
				167	<tr>
				168	<td>header</td>
				169	<td>header_item</td>
				170	<td>the header</td>
				171	</tr>
				172	<tr>
				173	<td>string_ids</td>
				174	<td>string_id_item[]</td>
				175	<td>string identifiers list. These are identifiers for all the strings
				176	used by this file, either for internal naming (e.g., type descriptors)
				177	or as constant objects referred to by code. This list must be sorted
				178	by string contents, using UTF-16 code point values (not in a
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	179	locale-sensitive manner), and it must not contain any duplicate entries.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	180	</td>
				181	</tr>
				182	<tr>
				183	<td>type_ids</td>
				184	<td>type_id_item[]</td>
				185	<td>type identifiers list. These are identifiers for all types (classes,
				186	arrays, or primitive types) referred to by this file, whether defined
				187	in the file or not. This list must be sorted by <code>string_id</code>
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	188	index, and it must not contain any duplicate entries.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	189	</td>
				190	</tr>
				191	<tr>
				192	<td>proto_ids</td>
				193	<td>proto_id_item[]</td>
				194	<td>method prototype identifiers list. These are identifiers for all
				195	prototypes referred to by this file. This list must be sorted in
				196	return-type (by <code>type_id</code> index) major order, and then
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	197	by arguments (also by <code>type_id</code> index). The list must not
				198	contain any duplicate entries.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	199	</td>
				200	</tr>
				201	<tr>
				202	<td>field_ids</td>
				203	<td>field_id_item[]</td>
				204	<td>field identifiers list. These are identifiers for all fields
				205	referred to by this file, whether defined in the file or not. This
				206	list must be sorted, where the defining type (by <code>type_id</code>
				207	index) is the major order, field name (by <code>string_id</code> index)
				208	is the intermediate order, and type (by <code>type_id</code> index)
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	209	is the minor order. The list must not contain any duplicate entries.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	210	</td>
				211	</tr>
				212	<tr>
				213	<td>method_ids</td>
				214	<td>method_id_item[]</td>
				215	<td>method identifiers list. These are identifiers for all methods
				216	referred to by this file, whether defined in the file or not. This
				217	list must be sorted, where the defining type (by <code>type_id</code>
				218	index) is the major order, method name (by <code>string_id</code>
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	219	index) is the intermediate order, and method prototype (by
				220	<code>proto_id</code> index) is the minor order. The list must not
				221	contain any duplicate entries.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	222	</td>
				223	</tr>
				224	<tr>
				225	<td>class_defs</td>
				226	<td>class_def_item[]</td>
				227	<td>class definitions list. The classes must be ordered such that a given
				228	class's superclass and implemented interfaces appear in the
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	229	list earlier than the referring class. Furthermore, it is invalid for
				230	a definition for the same-named class to appear more than once in
				231	the list.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	232	</td>
				233	</tr>
				234	<tr>
				235	<td>data</td>
				236	<td>ubyte[]</td>
				237	<td>data area, containing all the support data for the tables listed above.
				238	Different items have different alignment requirements, and
				239	padding bytes are inserted before each item if necessary to achieve
				240	proper alignment.
				241	</td>
				242	</tr>
				243	<tr>
				244	<td>link_data</td>
				245	<td>ubyte[]</td>
				246	<td>data used in statically linked files. The format of the data in
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	247	this section is left unspecified by this document.
				248	This section is empty in unlinked files, and runtime implementations
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	249	may use it as they see fit.
				250	</td>
				251	</tr>
				252	</tbody>
				253	</table>
				254
				255	<h1>Bitfield, String, and Constant Definitions</h1>
				256
				257	<h2><code>DEX_FILE_MAGIC</code></h2>
				258	<h4>embedded in <code>header_item</code></h4>
				259
				260	<p>The constant array/string <code>DEX_FILE_MAGIC</code> is the list of
				261	bytes that must appear at the beginning of a <code>.dex</code> file
				262	in order for it to be recognized as such. The value intentionally
				263	contains a newline (<code>"\n"</code> or <code>0x0a</code>) and a
				264	null byte (<code>"\0"</code> or <code>0x00</code>) in order to help
				265	in the detection of certain forms of corruption. The value also
				266	encodes a format version number as three decimal digits, which is
				267	expected to increase monotonically over time as the format evolves.</p>
				268
				269	<pre>
				270	ubyte[8] DEX_FILE_MAGIC = { 0x64 0x65 0x78 0x0a 0x30 0x33 0x35 0x00 }
				271	= "dex\n035\0"
				272	</pre>
				273
				274	<p><b>Note:</b> At least a couple earlier versions of the format have
				275	been used in widely-available public software releases. For example,
				276	version <code>009</code> was used for the M3 releases of the
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	277	Android platform (November–December 2007),
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	278	and version <code>013</code> was used for the M5 releases of the Android
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	279	platform (February–March 2008). In several respects, these earlier
				280	versions of the format differ significantly from the version described in this
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	281	document.</p>
				282
				283	<h2><code>ENDIAN_CONSTANT</code> and <code>REVERSE_ENDIAN_CONSTANT</code></h2>
				284	<h4>embedded in <code>header_item</code></h4>
				285
				286	<p>The constant <code>ENDIAN_CONSTANT</code> is used to indicate the
				287	endianness of the file in which it is found. Although the standard
				288	<code>.dex</code> format is little-endian, implementations may choose
				289	to perform byte-swapping. Should an implementation come across a
				290	header whose <code>endian_tag</code> is <code>REVERSE_ENDIAN_CONSTANT</code>
				291	instead of <code>ENDIAN_CONSTANT</code>, it would know that the file
				292	has been byte-swapped from the expected form.</p>
				293
				294	<pre>
				295	uint ENDIAN_CONSTANT = 0x12345678;
				296	uint REVERSE_ENDIAN_CONSTANT = 0x78563412;
				297	</pre>
				298
				299	<h2><code>NO_INDEX</code></h2>
				300	<h4>embedded in <code>class_def_item</code> and
				301	<code>debug_info_item</code></h4>
				302
				303	<p>The constant <code>NO_INDEX</code> is used to indicate that
				304	an index value is absent.</p>
				305
				306	<p><b>Note:</b> This value isn't defined to be
				307	<code>0</code>, because that is in fact typically a valid index.</p>
				308
				309	<p><b>Also Note:</b> The chosen value for <code>NO_INDEX</code> is
				310	representable as a single byte in the <code>uleb128p1</code> encoding.</p>
				311
				312	<pre>
				313	uint NO_INDEX = 0xffffffff; // == -1 if treated as a signed int
				314	</pre>
				315
				316	<h2><code>access_flags</code> Definitions</h2>
				317	<h4>embedded in <code>class_def_item</code>,
Dan Bornstein	5cbbea3	2011-04-05 15:17:25 -0700	[diff] [blame]	318	<code>encoded_field</code>, <code>encoded_method</code>, and
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	319	<code>InnerClass</code></h4>
				320
				321	<p>Bitfields of these flags are used to indicate the accessibility and
				322	overall properties of classes and class members.</p>
				323
				324	<table class="accessFlags">
				325	<thead>
				326	<tr>
				327	<th>Name</th>
				328	<th>Value</th>
				329	<th>For Classes (and <code>InnerClass</code> annotations)</th>
				330	<th>For Fields</th>
				331	<th>For Methods</th>
				332	</tr>
				333	</thead>
				334	<tbody>
				335	<tr>
				336	<td>ACC_PUBLIC</td>
				337	<td>0x1</td>
				338	<td><code>public</code>: visible everywhere</td>
				339	<td><code>public</code>: visible everywhere</td>
				340	<td><code>public</code>: visible everywhere</td>
				341	</tr>
				342	<tr>
				343	<td>ACC_PRIVATE</td>
				344	<td>0x2</td>
				345	<td><super>*</super>
				346	<code>private</code>: only visible to defining class
				347	</td>
				348	<td><code>private</code>: only visible to defining class</td>
				349	<td><code>private</code>: only visible to defining class</td>
				350	</tr>
				351	<tr>
				352	<td>ACC_PROTECTED</td>
				353	<td>0x4</td>
				354	<td><super>*</super>
				355	<code>protected</code>: visible to package and subclasses
				356	</td>
				357	<td><code>protected</code>: visible to package and subclasses</td>
				358	<td><code>protected</code>: visible to package and subclasses</td>
				359	</tr>
				360	<tr>
				361	<td>ACC_STATIC</td>
				362	<td>0x8</td>
				363	<td><super>*</super>
				364	<code>static</code>: is not constructed with an outer
				365	<code>this</code> reference</td>
				366	<td><code>static</code>: global to defining class</td>
				367	<td><code>static</code>: does not take a <code>this</code> argument</td>
				368	</tr>
				369	<tr>
				370	<td>ACC_FINAL</td>
				371	<td>0x10</td>
				372	<td><code>final</code>: not subclassable</td>
				373	<td><code>final</code>: immutable after construction</td>
				374	<td><code>final</code>: not overridable</td>
				375	</tr>
				376	<tr>
				377	<td>ACC_SYNCHRONIZED</td>
				378	<td>0x20</td>
				379	<td> </td>
				380	<td> </td>
				381	<td><code>synchronized</code>: associated lock automatically acquired
				382	around call to this method. <b>Note:</b> This is only valid to set when
				383	<code>ACC_NATIVE</code> is also set.</td>
				384	</tr>
				385	<tr>
				386	<td>ACC_VOLATILE</td>
				387	<td>0x40</td>
				388	<td> </td>
				389	<td><code>volatile</code>: special access rules to help with thread
				390	safety</td>
				391	<td> </td>
				392	</tr>
				393	<tr>
				394	<td>ACC_BRIDGE</td>
				395	<td>0x40</td>
				396	<td> </td>
				397	<td> </td>
				398	<td>bridge method, added automatically by compiler as a type-safe
				399	bridge</td>
				400	</tr>
				401	<tr>
				402	<td>ACC_TRANSIENT</td>
				403	<td>0x80</td>
				404	<td> </td>
				405	<td><code>transient</code>: not to be saved by default serialization</td>
				406	<td> </td>
				407	</tr>
				408	<tr>
				409	<td>ACC_VARARGS</td>
				410	<td>0x80</td>
				411	<td> </td>
				412	<td> </td>
				413	<td>last argument should be treated as a "rest" argument by compiler</td>
				414	</tr>
				415	<tr>
				416	<td>ACC_NATIVE</td>
				417	<td>0x100</td>
				418	<td> </td>
				419	<td> </td>
				420	<td><code>native</code>: implemented in native code</td>
				421	</tr>
				422	<tr>
				423	<td>ACC_INTERFACE</td>
				424	<td>0x200</td>
				425	<td><code>interface</code>: multiply-implementable abstract class</td>
				426	<td> </td>
				427	<td> </td>
				428	</tr>
				429	<tr>
				430	<td>ACC_ABSTRACT</td>
				431	<td>0x400</td>
				432	<td><code>abstract</code>: not directly instantiable</td>
				433	<td> </td>
				434	<td><code>abstract</code>: unimplemented by this class</td>
				435	</tr>
				436	<tr>
				437	<td>ACC_STRICT</td>
				438	<td>0x800</td>
				439	<td> </td>
				440	<td> </td>
				441	<td><code>strictfp</code>: strict rules for floating-point arithmetic</td>
				442	</tr>
				443	<tr>
				444	<td>ACC_SYNTHETIC</td>
				445	<td>0x1000</td>
				446	<td>not directly defined in source code</td>
				447	<td>not directly defined in source code</td>
				448	<td>not directly defined in source code</td>
				449	</tr>
				450	<tr>
				451	<td>ACC_ANNOTATION</td>
				452	<td>0x2000</td>
				453	<td>declared as an annotation class</td>
				454	<td> </td>
				455	<td> </td>
				456	</tr>
				457	<tr>
				458	<td>ACC_ENUM</td>
				459	<td>0x4000</td>
				460	<td>declared as an enumerated type</td>
				461	<td>declared as an enumerated value</td>
				462	<td> </td>
				463	</tr>
				464	<tr>
				465	<td><i>(unused)</i></td>
				466	<td>0x8000</td>
				467	<td> </td>
				468	<td> </td>
				469	<td> </td>
				470	</tr>
				471	<tr>
				472	<td>ACC_CONSTRUCTOR</td>
				473	<td>0x10000</td>
				474	<td> </td>
				475	<td> </td>
				476	<td>constructor method (class or instance initializer)</td>
				477	</tr>
				478	<tr>
				479	<td>ACC_DECLARED_<br/>SYNCHRONIZED</td>
				480	<td>0x20000</td>
				481	<td> </td>
				482	<td> </td>
				483	<td>declared <code>synchronized</code>. <b>Note:</b> This has no effect on
				484	execution (other than in reflection of this flag, per se).
				485	</td>
				486	</tr>
				487	</tbody>
				488	</table>
				489
				490	<p><super>*</super> Only allowed on for <code>InnerClass</code> annotations,
				491	and must not ever be on in a <code>class_def_item</code>.</p>
				492
				493	<h2>MUTF-8 (Modified UTF-8) Encoding</h2>
				494
				495	<p>As a concession to easier legacy support, the <code>.dex</code> format
				496	encodes its string data in a de facto standard modified UTF-8 form, hereafter
				497	referred to as MUTF-8. This form is identical to standard UTF-8, except:</p>
				498
				499	<ul>
				500	<li>Only the one-, two-, and three-byte encodings are used.</li>
				501	<li>Code points in the range <code>U+10000</code> …
				502	<code>U+10ffff</code> are encoded as a surrogate pair, each of
				503	which is represented as a three-byte encoded value.</li>
				504	<li>The code point <code>U+0000</code> is encoded in two-byte form.</li>
				505	<li>A plain null byte (value <code>0</code>) indicates the end of
				506	a string, as is the standard C language interpretation.</li>
				507	</ul>
				508
				509	<p>The first two items above can be summarized as: MUTF-8
				510	is an encoding format for UTF-16, instead of being a more direct
				511	encoding format for Unicode characters.</p>
				512
				513	<p>The final two items above make it simultaneously possible to include
				514	the code point <code>U+0000</code> in a string <i>and</i> still manipulate
				515	it as a C-style null-terminated string.</p>
				516
				517	<p>However, the special encoding of <code>U+0000</code> means that, unlike
				518	normal UTF-8, the result of calling the standard C function
				519	<code>strcmp()</code> on a pair of MUTF-8 strings does not always
				520	indicate the properly signed result of comparison of <i>unequal</i> strings.
				521	When ordering (not just equality) is a concern, the most straightforward
				522	way to compare MUTF-8 strings is to decode them character by character,
				523	and compare the decoded values. (However, more clever implementations are
				524	also possible.)</p>
				525
				526	<p>Please refer to <a href="http://unicode.org">The Unicode
				527	Standard</a> for further information about character encoding.
				528	MUTF-8 is actually closer to the (relatively less well-known) encoding
				529	<a href="http://www.unicode.org/reports/tr26/">CESU-8</a> than to UTF-8
				530	per se.</p>
				531
				532	<h2><code>encoded_value</code> Encoding</h2>
				533	<h4>embedded in <code>annotation_element</code> and
				534	<code>encoded_array_item</code></h4>
				535
				536	<p>An <code>encoded_value</code> is an encoded piece of (nearly)
				537	arbitrary hierarchically structured data. The encoding is meant to
				538	be both compact and straightforward to parse.</p>
				539
				540	<table class="format">
				541	<thead>
				542	<tr>
				543	<th>Name</th>
				544	<th>Format</th>
				545	<th>Description</th>
				546	</tr>
				547	</thead>
				548	<tbody>
				549	<tr>
				550	<td>(value_arg << 5) \| value_type</td>
				551	<td>ubyte</td>
				552	<td>byte indicating the type of the immediately subsequent
				553	<code>value</code> along
				554	with an optional clarifying argument in the high-order three bits.
				555	See below for the various <code>value</code> definitions.
				556	In most cases, <code>value_arg</code> encodes the length of
				557	the immediately-subsequent <code>value</code> in bytes, as
				558	<code>(size - 1)</code>, e.g., <code>0</code> means that
				559	the value requires one byte, and <code>7</code> means it requires
				560	eight bytes; however, there are exceptions as noted below.
				561	</td>
				562	</tr>
				563	<tr>
				564	<td>value</td>
				565	<td>ubyte[]</td>
				566	<td>bytes representing the value, variable in length and interpreted
				567	differently for different <code>value_type</code> bytes, though
				568	always little-endian. See the various value definitions below for
				569	details.
				570	</td>
				571	</tr>
				572	</tbody>
				573	</table>
				574
				575	<h3>Value Formats</h3>
				576
				577	<table class="encodedValue">
				578	<thead>
				579	<tr>
				580	<th>Type Name</th>
				581	<th><code>value_type</code></th>
				582	<th><code>value_arg</code> Format</th>
				583	<th><code>value</code> Format</th>
				584	<th>Description</th>
				585	</tr>
				586	</thead>
				587	<tbody>
				588	<tr>
				589	<td>VALUE_BYTE</td>
				590	<td>0x00</td>
				591	<td><i>(none; must be <code>0</code>)</i></td>
				592	<td>ubyte[1]</td>
				593	<td>signed one-byte integer value</td>
				594	</tr>
				595	<tr>
				596	<td>VALUE_SHORT</td>
				597	<td>0x02</td>
				598	<td>size - 1 (0…1)</td>
				599	<td>ubyte[size]</td>
				600	<td>signed two-byte integer value, sign-extended</td>
				601	</tr>
				602	<tr>
				603	<td>VALUE_CHAR</td>
				604	<td>0x03</td>
				605	<td>size - 1 (0…1)</td>
				606	<td>ubyte[size]</td>
				607	<td>unsigned two-byte integer value, zero-extended</td>
				608	</tr>
				609	<tr>
				610	<td>VALUE_INT</td>
				611	<td>0x04</td>
				612	<td>size - 1 (0…3)</td>
				613	<td>ubyte[size]</td>
				614	<td>signed four-byte integer value, sign-extended</td>
				615	</tr>
				616	<tr>
				617	<td>VALUE_LONG</td>
				618	<td>0x06</td>
				619	<td>size - 1 (0…7)</td>
				620	<td>ubyte[size]</td>
				621	<td>signed eight-byte integer value, sign-extended</td>
				622	</tr>
				623	<tr>
				624	<td>VALUE_FLOAT</td>
				625	<td>0x10</td>
				626	<td>size - 1 (0…3)</td>
				627	<td>ubyte[size]</td>
				628	<td>four-byte bit pattern, zero-extended <i>to the right</i>, and
				629	interpreted as an IEEE754 32-bit floating point value
				630	</td>
				631	</tr>
				632	<tr>
				633	<td>VALUE_DOUBLE</td>
				634	<td>0x11</td>
				635	<td>size - 1 (0…7)</td>
				636	<td>ubyte[size]</td>
				637	<td>eight-byte bit pattern, zero-extended <i>to the right</i>, and
				638	interpreted as an IEEE754 64-bit floating point value
				639	</td>
				640	</tr>
				641	<tr>
				642	<td>VALUE_STRING</td>
				643	<td>0x17</td>
				644	<td>size - 1 (0…3)</td>
				645	<td>ubyte[size]</td>
				646	<td>unsigned (zero-extended) four-byte integer value,
				647	interpreted as an index into
				648	the <code>string_ids</code> section and representing a string value
				649	</td>
				650	</tr>
				651	<tr>
				652	<td>VALUE_TYPE</td>
				653	<td>0x18</td>
				654	<td>size - 1 (0…3)</td>
				655	<td>ubyte[size]</td>
				656	<td>unsigned (zero-extended) four-byte integer value,
				657	interpreted as an index into
				658	the <code>type_ids</code> section and representing a reflective
				659	type/class value
				660	</td>
				661	</tr>
				662	<tr>
				663	<td>VALUE_FIELD</td>
				664	<td>0x19</td>
				665	<td>size - 1 (0…3)</td>
				666	<td>ubyte[size]</td>
				667	<td>unsigned (zero-extended) four-byte integer value,
				668	interpreted as an index into
				669	the <code>field_ids</code> section and representing a reflective
				670	field value
				671	</td>
				672	</tr>
				673	<tr>
				674	<td>VALUE_METHOD</td>
				675	<td>0x1a</td>
				676	<td>size - 1 (0…3)</td>
				677	<td>ubyte[size]</td>
				678	<td>unsigned (zero-extended) four-byte integer value,
				679	interpreted as an index into
				680	the <code>method_ids</code> section and representing a reflective
				681	method value
				682	</td>
				683	</tr>
				684	<tr>
				685	<td>VALUE_ENUM</td>
				686	<td>0x1b</td>
				687	<td>size - 1 (0…3)</td>
				688	<td>ubyte[size]</td>
				689	<td>unsigned (zero-extended) four-byte integer value,
				690	interpreted as an index into
				691	the <code>field_ids</code> section and representing the value of
				692	an enumerated type constant
				693	</td>
				694	</tr>
				695	<tr>
				696	<td>VALUE_ARRAY</td>
				697	<td>0x1c</td>
				698	<td><i>(none; must be <code>0</code>)</i></td>
				699	<td>encoded_array</td>
				700	<td>an array of values, in the format specified by
				701	"<code>encoded_array</code> Format" below. The size
				702	of the <code>value</code> is implicit in the encoding.
				703	</td>
				704	</tr>
				705	<tr>
				706	<td>VALUE_ANNOTATION</td>
				707	<td>0x1d</td>
				708	<td><i>(none; must be <code>0</code>)</i></td>
				709	<td>encoded_annotation</td>
				710	<td>a sub-annotation, in the format specified by
				711	"<code>encoded_annotation</code> Format" below. The size
				712	of the <code>value</code> is implicit in the encoding.
				713	</td>
				714	</tr>
				715	<tr>
				716	<td>VALUE_NULL</td>
				717	<td>0x1e</td>
				718	<td><i>(none; must be <code>0</code>)</i></td>
				719	<td><i>(none)</i></td>
				720	<td><code>null</code> reference value</td>
				721	</tr>
				722	<tr>
				723	<td>VALUE_BOOLEAN</td>
				724	<td>0x1f</td>
				725	<td>boolean (0…1)</td>
				726	<td><i>(none)</i></td>
				727	<td>one-bit value; <code>0</code> for <code>false</code> and
				728	<code>1</code> for <code>true</code>. The bit is represented in the
				729	<code>value_arg</code>.
				730	</td>
				731	</tr>
				732	</tbody>
				733	</table>
				734
				735	<h3><code>encoded_array</code> Format</h3>
				736
				737	<table class="format">
				738	<thead>
				739	<tr>
				740	<th>Name</th>
				741	<th>Format</th>
				742	<th>Description</th>
				743	</tr>
				744	</thead>
				745	<tbody>
				746	<tr>
				747	<td>size</td>
				748	<td>uleb128</td>
				749	<td>number of elements in the array</td>
				750	</tr>
				751	<tr>
				752	<td>values</td>
				753	<td>encoded_value[size]</td>
				754	<td>a series of <code>size</code> <code>encoded_value</code> byte
				755	sequences in the format specified by this section, concatenated
				756	sequentially.
				757	</td>
				758	</tr>
				759	</tbody>
				760	</table>
				761
				762	<h3><code>encoded_annotation</code> Format</h3>
				763
				764	<table class="format">
				765	<thead>
				766	<tr>
				767	<th>Name</th>
				768	<th>Format</th>
				769	<th>Description</th>
				770	</tr>
				771	</thead>
				772	<tbody>
				773	<tr>
				774	<td>type_idx</td>
				775	<td>uleb128</td>
				776	<td>type of the annotation. This must be a class (not array or primitive)
				777	type.
				778	</td>
				779	</tr>
				780	<tr>
				781	<td>size</td>
				782	<td>uleb128</td>
				783	<td>number of name-value mappings in this annotation</td>
				784	</tr>
				785	<tr>
				786	<td>elements</td>
				787	<td>annotation_element[size]</td>
				788	<td>elements of the annotataion, represented directly in-line (not as
				789	offsets). Elements must be sorted in increasing order by
				790	<code>string_id</code> index.
				791	</td>
				792	</tr>
				793	</tbody>
				794	</table>
				795
				796	<h3><code>annotation_element</code> Format</h3>
				797
				798	<table class="format">
				799	<thead>
				800	<tr>
				801	<th>Name</th>
				802	<th>Format</th>
				803	<th>Description</th>
				804	</tr>
				805	</thead>
				806	<tbody>
				807	<tr>
				808	<td>name_idx</td>
				809	<td>uleb128</td>
				810	<td>element name, represented as an index into the
				811	<code>string_ids</code> section. The string must conform to the
				812	syntax for <i>MemberName</i>, defined above.
				813	</td>
				814	</tr>
				815	<tr>
				816	<td>value</td>
				817	<td>encoded_value</td>
				818	<td>element value</td>
				819	</tr>
				820	</tbody>
				821	</table>
				822
				823	<h2>String Syntax</h2>
				824
				825	<p>There are several kinds of item in a <code>.dex</code> file which
				826	ultimately refer to a string. The following BNF-style definitions
				827	indicate the acceptable syntax for these strings.</p>
				828
				829	<h3><i>SimpleName</i></h3>
				830
				831	<p>A <i>SimpleName</i> is the basis for the syntax of the names of other
				832	things. The <code>.dex</code> format allows a fair amount of latitude
				833	here (much more than most common source languages). In brief, a simple
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	834	name consists of any low-ASCII alphabetic character or digit, a few
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	835	specific low-ASCII symbols, and most non-ASCII code points that are not
				836	control, space, or special characters. Note that surrogate code points
				837	(in the range <code>U+d800</code> … <code>U+dfff</code>) are not
				838	considered valid name characters, per se, but Unicode supplemental
				839	characters <i>are</i> valid (which are represented by the final
				840	alternative of the rule for <i>SimpleNameChar</i>), and they should be
				841	represented in a file as pairs of surrogate code points in the MUTF-8
				842	encoding.</p>
				843
				844	<table class="bnf">
				845	<tr><td colspan="2" class="def"><i>SimpleName</i> →</td></tr>
				846	<tr>
				847	<td/>
				848	<td><i>SimpleNameChar</i> (<i>SimpleNameChar</i>)*</td>
				849	</tr>
				850
				851	<tr><td colspan="2" class="def"><i>SimpleNameChar</i> →</td></tr>
				852	<tr>
				853	<td/>
				854	<td><code>'A'</code> … <code>'Z'</code></td>
				855	</tr>
				856	<tr>
				857	<td class="bar">\|</td>
				858	<td><code>'a'</code> … <code>'z'</code></td>
				859	</tr>
				860	<tr>
				861	<td class="bar">\|</td>
				862	<td><code>'0'</code> … <code>'9'</code></td>
				863	</tr>
				864	<tr>
				865	<td class="bar">\|</td>
				866	<td><code>'$'</code></td>
				867	</tr>
				868	<tr>
				869	<td class="bar">\|</td>
				870	<td><code>'-'</code></td>
				871	</tr>
				872	<tr>
				873	<td class="bar">\|</td>
				874	<td><code>'_'</code></td>
				875	</tr>
				876	<tr>
				877	<td class="bar">\|</td>
				878	<td><code>U+00a1</code> … <code>U+1fff</code></td>
				879	</tr>
				880	<tr>
				881	<td class="bar">\|</td>
				882	<td><code>U+2010</code> … <code>U+2027</code></td>
				883	</tr>
				884	<tr>
				885	<td class="bar">\|</td>
				886	<td><code>U+2030</code> … <code>U+d7ff</code></td>
				887	</tr>
				888	<tr>
				889	<td class="bar">\|</td>
				890	<td><code>U+e000</code> … <code>U+ffef</code></td>
				891	</tr>
				892	<tr>
				893	<td class="bar">\|</td>
				894	<td><code>U+10000</code> … <code>U+10ffff</code></td>
				895	</tr>
				896	</table>
				897
				898	<h3><i>MemberName</i></h3>
				899	<h4>used by <code>field_id_item</code> and <code>method_id_item</code></h4>
				900
				901	<p>A <i>MemberName</i> is the name of a member of a class, members being
				902	fields, methods, and inner classes.</p>
				903
				904	<table class="bnf">
				905	<tr><td colspan="2" class="def"><i>MemberName</i> →</td></tr>
				906	<tr>
				907	<td/>
				908	<td><i>SimpleName</i></td>
				909	</tr>
				910	<tr>
				911	<td class="bar">\|</td>
				912	<td><code>'<'</code> <i>SimpleName</i> <code>'>'</code></td>
				913	</tr>
				914	</table>
				915
				916	<h3><i>FullClassName</i></h3>
				917
				918	<p>A <i>FullClassName</i> is a fully-qualified class name, including an
				919	optional package specifier followed by a required name.</p>
				920
				921	<table class="bnf">
				922	<tr><td colspan="2" class="def"><i>FullClassName</i> →</td></tr>
				923	<tr>
				924	<td/>
				925	<td><i>OptionalPackagePrefix</i> <i>SimpleName</i></td>
				926	</tr>
				927
				928	<tr><td colspan="2" class="def"><i>OptionalPackagePrefix</i> →</td></tr>
				929	<tr>
				930	<td/>
				931	<td>(<i>SimpleName</i> <code>'/'</code>)*</td>
				932	</tr>
				933	</table>
				934
				935	<h3><i>TypeDescriptor</i></h3>
				936	<h4>used by <code>type_id_item</code></h4>
				937
				938	<p>A <i>TypeDescriptor</i> is the representation of any type, including
				939	primitives, classes, arrays, and <code>void</code>. See below for
				940	the meaning of the various versions.</p>
				941
				942	<table class="bnf">
				943	<tr><td colspan="2" class="def"><i>TypeDescriptor</i> →</td></tr>
				944	<tr>
				945	<td/>
				946	<td><code>'V'</code></td>
				947	</tr>
				948	<tr>
				949	<td class="bar">\|</td>
				950	<td><i>FieldTypeDescriptor</i></td>
				951	</tr>
				952
				953	<tr><td colspan="2" class="def"><i>FieldTypeDescriptor</i> →</td></tr>
				954	<tr>
				955	<td/>
				956	<td><i>NonArrayFieldTypeDescriptor</i></td>
				957	</tr>
				958	<tr>
				959	<td class="bar">\|</td>
				960	<td>(<code>'['</code> * 1…255)
				961	<i>NonArrayFieldTypeDescriptor</i></td>
				962	</tr>
				963
				964	<tr>
				965	<td colspan="2" class="def"><i>NonArrayFieldTypeDescriptor</i>→</td>
				966	</tr>
				967	<tr>
				968	<td/>
				969	<td><code>'Z'</code></td>
				970	</tr>
				971	<tr>
				972	<td class="bar">\|</td>
				973	<td><code>'B'</code></td>
				974	</tr>
				975	<tr>
				976	<td class="bar">\|</td>
				977	<td><code>'S'</code></td>
				978	</tr>
				979	<tr>
				980	<td class="bar">\|</td>
				981	<td><code>'C'</code></td>
				982	</tr>
				983	<tr>
				984	<td class="bar">\|</td>
				985	<td><code>'I'</code></td>
				986	</tr>
				987	<tr>
				988	<td class="bar">\|</td>
				989	<td><code>'J'</code></td>
				990	</tr>
				991	<tr>
				992	<td class="bar">\|</td>
				993	<td><code>'F'</code></td>
				994	</tr>
				995	<tr>
				996	<td class="bar">\|</td>
				997	<td><code>'D'</code></td>
				998	</tr>
				999	<tr>
				1000	<td class="bar">\|</td>
				1001	<td><code>'L'</code> <i>FullClassName</i> <code>';'</code></td>
				1002	</tr>
				1003	</table>
				1004
				1005	<h3><i>ShortyDescriptor</i></h3>
				1006	<h4>used by <code>proto_id_item</code></h4>
				1007
				1008	<p>A <i>ShortyDescriptor</i> is the short form representation of a method
				1009	prototype, including return and parameter types, except that there is
				1010	no distinction between various reference (class or array) types. Instead,
				1011	all reference types are represented by a single <code>'L'</code> character.</p>
				1012
				1013	<table class="bnf">
				1014	<tr><td colspan="2" class="def"><i>ShortyDescriptor</i> →</td></tr>
				1015	<tr>
				1016	<td/>
				1017	<td><i>ShortyReturnType</i> (<i>ShortyFieldType</i>)*</td>
				1018	</tr>
				1019
				1020	<tr><td colspan="2" class="def"><i>ShortyReturnType</i> →</td></tr>
				1021	<tr>
				1022	<td/>
				1023	<td><code>'V'</code></td>
				1024	</tr>
				1025	<tr>
				1026	<td class="bar">\|</td>
				1027	<td><i>ShortyFieldType</i></td>
				1028	</tr>
				1029
				1030	<tr><td colspan="2" class="def"><i>ShortyFieldType</i> →</td></tr>
				1031	<tr>
				1032	<td/>
				1033	<td><code>'Z'</code></td>
				1034	</tr>
				1035	<tr>
				1036	<td class="bar">\|</td>
				1037	<td><code>'B'</code></td>
				1038	</tr>
				1039	<tr>
				1040	<td class="bar">\|</td>
				1041	<td><code>'S'</code></td>
				1042	</tr>
				1043	<tr>
				1044	<td class="bar">\|</td>
				1045	<td><code>'C'</code></td>
				1046	</tr>
				1047	<tr>
				1048	<td class="bar">\|</td>
				1049	<td><code>'I'</code></td>
				1050	</tr>
				1051	<tr>
				1052	<td class="bar">\|</td>
				1053	<td><code>'J'</code></td>
				1054	</tr>
				1055	<tr>
				1056	<td class="bar">\|</td>
				1057	<td><code>'F'</code></td>
				1058	</tr>
				1059	<tr>
				1060	<td class="bar">\|</td>
				1061	<td><code>'D'</code></td>
				1062	</tr>
				1063	<tr>
				1064	<td class="bar">\|</td>
				1065	<td><code>'L'</code></td>
				1066	</tr>
				1067	</table>
				1068
				1069	<h2><i>TypeDescriptor</i> Semantics</h2>
				1070
				1071	<p>This is the meaning of each of the variants of <i>TypeDescriptor</i>.</p>
				1072
				1073	<table class="descriptor">
				1074	<thead>
				1075	<tr>
				1076	<th>Syntax</th>
				1077	<th>Meaning</th>
				1078	</tr>
				1079	</thead>
				1080	<tbody>
				1081	<tr>
				1082	<td>V</td>
				1083	<td><code>void</code>; only valid for return types</td>
				1084	</tr>
				1085	<tr>
				1086	<td>Z</td>
				1087	<td><code>boolean</code></td>
				1088	</tr>
				1089	<tr>
				1090	<td>B</td>
				1091	<td><code>byte</code></td>
				1092	</tr>
				1093	<tr>
				1094	<td>S</td>
				1095	<td><code>short</code></td>
				1096	</tr>
				1097	<tr>
				1098	<td>C</td>
				1099	<td><code>char</code></td>
				1100	</tr>
				1101	<tr>
				1102	<td>I</td>
				1103	<td><code>int</code></td>
				1104	</tr>
				1105	<tr>
				1106	<td>J</td>
				1107	<td><code>long</code></td>
				1108	</tr>
				1109	<tr>
				1110	<td>F</td>
				1111	<td><code>float</code></td>
				1112	</tr>
				1113	<tr>
				1114	<td>D</td>
				1115	<td><code>double</code></td>
				1116	</tr>
				1117	<tr>
				1118	<td>L<i>fully/qualified/Name</i>;</td>
				1119	<td>the class <code><i>fully.qualified.Name</i></code></td>
				1120	</tr>
				1121	<tr>
				1122	<td>[<i>descriptor</i></td>
				1123	<td>array of <code><i>descriptor</i></code>, usable recursively for
				1124	arrays-of-arrays, though it is invalid to have more than 255
				1125	dimensions.
				1126	</td>
				1127	</tr>
				1128	</tbody>
				1129	</table>
				1130
				1131	<h1>Items and Related Structures</h1>
				1132
				1133	<p>This section includes definitions for each of the top-level items that
				1134	may appear in a <code>.dex</code> file.
				1135
				1136	<h2><code>header_item</code></h2>
				1137	<h4>appears in the <code>header</code> section</h4>
				1138	<h4>alignment: 4 bytes</h4>
				1139
				1140	<table class="format">
				1141	<thead>
				1142	<tr>
				1143	<th>Name</th>
				1144	<th>Format</th>
				1145	<th>Description</th>
				1146	</tr>
				1147	</thead>
				1148	<tbody>
				1149	<tr>
				1150	<td>magic</td>
				1151	<td>ubyte[8] = DEX_FILE_MAGIC</td>
				1152	<td>magic value. See discussion above under "<code>DEX_FILE_MAGIC</code>"
				1153	for more details.
				1154	</td>
				1155	</tr>
				1156	<tr>
				1157	<td>checksum</td>
				1158	<td>uint</td>
				1159	<td>adler32 checksum of the rest of the file (everything but
				1160	<code>magic</code> and this field); used to detect file corruption
				1161	</td>
				1162	</tr>
				1163	<tr>
				1164	<td>signature</td>
				1165	<td>ubyte[20]</td>
				1166	<td>SHA-1 signature (hash) of the rest of the file (everything but
				1167	<code>magic</code>, <code>checksum</code>, and this field); used
				1168	to uniquely identify files
				1169	</td>
				1170	</tr>
				1171	<tr>
				1172	<td>file_size</td>
				1173	<td>uint</td>
				1174	<td>size of the entire file (including the header), in bytes
				1175	</tr>
				1176	<tr>
				1177	<td>header_size</td>
				1178	<td>uint = 0x70</td>
				1179	<td>size of the header (this entire section), in bytes. This allows for at
				1180	least a limited amount of backwards/forwards compatibility without
				1181	invalidating the format.
				1182	</td>
				1183	</tr>
				1184	<tr>
				1185	<td>endian_tag</td>
				1186	<td>uint = ENDIAN_CONSTANT</td>
				1187	<td>endianness tag. See discussion above under "<code>ENDIAN_CONSTANT</code>
				1188	and <code>REVERSE_ENDIAN_CONSTANT</code>" for more details.
				1189	</td>
				1190	</tr>
				1191	<tr>
				1192	<td>link_size</td>
				1193	<td>uint</td>
				1194	<td>size of the link section, or <code>0</code> if this file isn't
				1195	statically linked</td>
				1196	</tr>
				1197	<tr>
				1198	<td>link_off</td>
				1199	<td>uint</td>
				1200	<td>offset from the start of the file to the link section, or
				1201	<code>0</code> if <code>link_size == 0</code>. The offset, if non-zero,
				1202	should be to an offset into the <code>link_data</code> section. The
				1203	format of the data pointed at is left unspecified by this document;
				1204	this header field (and the previous) are left as hooks for use by
				1205	runtime implementations.
				1206	</td>
				1207	</tr>
				1208	<tr>
				1209	<td>map_off</td>
				1210	<td>uint</td>
				1211	<td>offset from the start of the file to the map item, or
				1212	<code>0</code> if this file has no map. The offset, if non-zero,
				1213	should be to an offset into the <code>data</code> section,
				1214	and the data should be in the format specified by "<code>map_list</code>"
				1215	below.
				1216	</td>
				1217	</tr>
				1218	<tr>
				1219	<td>string_ids_size</td>
				1220	<td>uint</td>
				1221	<td>count of strings in the string identifiers list</td>
				1222	</tr>
				1223	<tr>
				1224	<td>string_ids_off</td>
				1225	<td>uint</td>
				1226	<td>offset from the start of the file to the string identifiers list, or
				1227	<code>0</code> if <code>string_ids_size == 0</code> (admittedly a
				1228	strange edge case). The offset, if non-zero,
				1229	should be to the start of the <code>string_ids</code> section.
				1230	</td>
				1231	</tr>
				1232	<tr>
				1233	<td>type_ids_size</td>
				1234	<td>uint</td>
				1235	<td>count of elements in the type identifiers list</td>
				1236	</tr>
				1237	<tr>
				1238	<td>type_ids_off</td>
				1239	<td>uint</td>
				1240	<td>offset from the start of the file to the type identifiers list, or
				1241	<code>0</code> if <code>type_ids_size == 0</code> (admittedly a
				1242	strange edge case). The offset, if non-zero,
				1243	should be to the start of the <code>type_ids</code>
				1244	section.
				1245	</td>
				1246	</tr>
				1247	<tr>
				1248	<td>proto_ids_size</td>
				1249	<td>uint</td>
				1250	<td>count of elements in the prototype identifiers list</td>
				1251	</tr>
				1252	<tr>
				1253	<td>proto_ids_off</td>
				1254	<td>uint</td>
				1255	<td>offset from the start of the file to the prototype identifiers list, or
				1256	<code>0</code> if <code>proto_ids_size == 0</code> (admittedly a
				1257	strange edge case). The offset, if non-zero,
				1258	should be to the start of the <code>proto_ids</code>
				1259	section.
				1260	</td>
				1261	</tr>
				1262	<tr>
				1263	<td>field_ids_size</td>
				1264	<td>uint</td>
				1265	<td>count of elements in the field identifiers list</td>
				1266	</tr>
				1267	<tr>
				1268	<td>field_ids_off</td>
				1269	<td>uint</td>
				1270	<td>offset from the start of the file to the field identifiers list, or
				1271	<code>0</code> if <code>field_ids_size == 0</code>. The offset, if
				1272	non-zero, should be to the start of the <code>field_ids</code>
				1273	section.</td>
				1274	</td>
				1275	</tr>
				1276	<tr>
				1277	<td>method_ids_size</td>
				1278	<td>uint</td>
				1279	<td>count of elements in the method identifiers list</td>
				1280	</tr>
				1281	<tr>
				1282	<td>method_ids_off</td>
				1283	<td>uint</td>
				1284	<td>offset from the start of the file to the method identifiers list, or
				1285	<code>0</code> if <code>method_ids_size == 0</code>. The offset, if
				1286	non-zero, should be to the start of the <code>method_ids</code>
				1287	section.</td>
				1288	</tr>
				1289	<tr>
				1290	<td>class_defs_size</td>
				1291	<td>uint</td>
				1292	<td>count of elements in the class definitions list</td>
				1293	</tr>
				1294	<tr>
				1295	<td>class_defs_off</td>
				1296	<td>uint</td>
				1297	<td>offset from the start of the file to the class definitions list, or
				1298	<code>0</code> if <code>class_defs_size == 0</code> (admittedly a
				1299	strange edge case). The offset, if non-zero,
				1300	should be to the start of the <code>class_defs</code> section.
				1301	</td>
				1302	</tr>
				1303	<tr>
				1304	<td>data_size</td>
				1305	<td>uint</td>
				1306	<td>Size of <code>data</code> section in bytes. Must be an even
				1307	multiple of sizeof(uint).</td>
				1308	</tr>
				1309	<tr>
				1310	<td>data_off</td>
				1311	<td>uint</td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	1312	<td>offset from the start of the file to the start of the
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	1313	<code>data</code> section.
				1314	</td>
				1315	</tr>
				1316	</tbody>
				1317	</table>
				1318
				1319	<h2><code>map_list</code></h2>
				1320	<h4>appears in the <code>data</code> section</h4>
				1321	<h4>referenced from <code>header_item</code></h4>
				1322	<h4>alignment: 4 bytes</h4>
				1323
				1324	<p>This is a list of the entire contents of a file, in order. It
				1325	contains some redundancy with respect to the <code>header_item</code>
				1326	but is intended to be an easy form to use to iterate over an entire
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	1327	file. A given type must appear at most once in a map, but there is no
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	1328	restriction on what order types may appear in, other than the
				1329	restrictions implied by the rest of the format (e.g., a
				1330	<code>header</code> section must appear first, followed by a
				1331	<code>string_ids</code> section, etc.). Additionally, the map entries must
				1332	be ordered by initial offset and must not overlap.</p>
				1333
				1334	<table class="format">
				1335	<thead>
				1336	<tr>
				1337	<th>Name</th>
				1338	<th>Format</th>
				1339	<th>Description</th>
				1340	</tr>
				1341	</thead>
				1342	<tbody>
				1343	<tr>
				1344	<td>size</td>
				1345	<td>uint</td>
				1346	<td>size of the list, in entries</td>
				1347	</tr>
				1348	<tr>
				1349	<td>list</td>
				1350	<td>map_item[size]</td>
				1351	<td>elements of the list</td>
				1352	</tr>
				1353	</tbody>
				1354	</table>
				1355
				1356	<h3><code>map_item</code> Format</h3>
				1357
				1358	<table class="format">
				1359	<thead>
				1360	<tr>
				1361	<th>Name</th>
				1362	<th>Format</th>
				1363	<th>Description</th>
				1364	</tr>
				1365	</thead>
				1366	<tbody>
				1367	<tr>
				1368	<td>type</td>
				1369	<td>ushort</td>
				1370	<td>type of the items; see table below</td>
				1371	</tr>
				1372	<tr>
				1373	<td>unused</td>
				1374	<td>ushort</td>
				1375	<td><i>(unused)</i></td>
				1376	</tr>
				1377	<tr>
				1378	<td>size</td>
				1379	<td>uint</td>
				1380	<td>count of the number of items to be found at the indicated offset</td>
				1381	</tr>
				1382	<tr>
				1383	<td>offset</td>
				1384	<td>uint</td>
				1385	<td>offset from the start of the file to the items in question</td>
				1386	</tr>
				1387	</tbody>
				1388	</table>
				1389
				1390
				1391	<h3>Type Codes</h3>
				1392
				1393	<table class="typeCodes">
				1394	<thead>
				1395	<tr>
				1396	<th>Item Type</th>
				1397	<th>Constant</th>
				1398	<th>Value</th>
				1399	<th>Item Size In Bytes</th>
				1400	</tr>
				1401	</thead>
				1402	<tbody>
				1403	<tr>
				1404	<td>header_item</td>
				1405	<td>TYPE_HEADER_ITEM</td>
				1406	<td>0x0000</td>
				1407	<td>0x70</td>
				1408	</tr>
				1409	<tr>
				1410	<td>string_id_item</td>
				1411	<td>TYPE_STRING_ID_ITEM</td>
				1412	<td>0x0001</td>
				1413	<td>0x04</td>
				1414	</tr>
				1415	<tr>
				1416	<td>type_id_item</td>
				1417	<td>TYPE_TYPE_ID_ITEM</td>
				1418	<td>0x0002</td>
				1419	<td>0x04</td>
				1420	</tr>
				1421	<tr>
				1422	<td>proto_id_item</td>
				1423	<td>TYPE_PROTO_ID_ITEM</td>
				1424	<td>0x0003</td>
				1425	<td>0x0c</td>
				1426	</tr>
				1427	<tr>
				1428	<td>field_id_item</td>
				1429	<td>TYPE_FIELD_ID_ITEM</td>
				1430	<td>0x0004</td>
				1431	<td>0x08</td>
				1432	</tr>
				1433	<tr>
				1434	<td>method_id_item</td>
				1435	<td>TYPE_METHOD_ID_ITEM</td>
				1436	<td>0x0005</td>
				1437	<td>0x08</td>
				1438	</tr>
				1439	<tr>
				1440	<td>class_def_item</td>
				1441	<td>TYPE_CLASS_DEF_ITEM</td>
				1442	<td>0x0006</td>
				1443	<td>0x20</td>
				1444	</tr>
				1445	<tr>
				1446	<td>map_list</td>
				1447	<td>TYPE_MAP_LIST</td>
				1448	<td>0x1000</td>
				1449	<td>4 + (item.size * 12)</td>
				1450	</tr>
				1451	<tr>
				1452	<td>type_list</td>
				1453	<td>TYPE_TYPE_LIST</td>
				1454	<td>0x1001</td>
				1455	<td>4 + (item.size * 2)</td>
				1456	</tr>
				1457	<tr>
				1458	<td>annotation_set_ref_list</td>
				1459	<td>TYPE_ANNOTATION_SET_REF_LIST</td>
				1460	<td>0x1002</td>
				1461	<td>4 + (item.size * 4)</td>
				1462	</tr>
				1463	<tr>
				1464	<td>annotation_set_item</td>
				1465	<td>TYPE_ANNOTATION_SET_ITEM</td>
				1466	<td>0x1003</td>
				1467	<td>4 + (item.size * 4)</td>
				1468	</tr>
				1469	<tr>
				1470	<td>class_data_item</td>
				1471	<td>TYPE_CLASS_DATA_ITEM</td>
				1472	<td>0x2000</td>
				1473	<td><i>implicit; must parse</i></td>
				1474	</tr>
				1475	<tr>
				1476	<td>code_item</td>
				1477	<td>TYPE_CODE_ITEM</td>
				1478	<td>0x2001</td>
				1479	<td><i>implicit; must parse</i></td>
				1480	</tr>
				1481	<tr>
				1482	<td>string_data_item</td>
				1483	<td>TYPE_STRING_DATA_ITEM</td>
				1484	<td>0x2002</td>
				1485	<td><i>implicit; must parse</i></td>
				1486	</tr>
				1487	<tr>
				1488	<td>debug_info_item</td>
				1489	<td>TYPE_DEBUG_INFO_ITEM</td>
				1490	<td>0x2003</td>
				1491	<td><i>implicit; must parse</i></td>
				1492	</tr>
				1493	<tr>
				1494	<td>annotation_item</td>
				1495	<td>TYPE_ANNOTATION_ITEM</td>
				1496	<td>0x2004</td>
				1497	<td><i>implicit; must parse</i></td>
				1498	</tr>
				1499	<tr>
				1500	<td>encoded_array_item</td>
				1501	<td>TYPE_ENCODED_ARRAY_ITEM</td>
				1502	<td>0x2005</td>
				1503	<td><i>implicit; must parse</i></td>
				1504	</tr>
				1505	<tr>
				1506	<td>annotations_directory_item</td>
				1507	<td>TYPE_ANNOTATIONS_DIRECTORY_ITEM</td>
				1508	<td>0x2006</td>
				1509	<td><i>implicit; must parse</i></td>
				1510	</tr>
				1511	</tbody>
				1512	</table>
				1513
				1514
				1515	<h2><code>string_id_item</code></h2>
				1516	<h4>appears in the <code>string_ids</code> section</h4>
				1517	<h4>alignment: 4 bytes</h4>
				1518
				1519	<table class="format">
				1520	<thead>
				1521	<tr>
				1522	<th>Name</th>
				1523	<th>Format</th>
				1524	<th>Description</th>
				1525	</tr>
				1526	</thead>
				1527	<tbody>
				1528	<tr>
				1529	<td>string_data_off</td>
				1530	<td>uint</td>
				1531	<td>offset from the start of the file to the string data for this
				1532	item. The offset should be to a location
				1533	in the <code>data</code> section, and the data should be in the
				1534	format specified by "<code>string_data_item</code>" below.
				1535	There is no alignment requirement for the offset.
				1536	</td>
				1537	</tr>
				1538	</tbody>
				1539	</table>
				1540
				1541	<h2><code>string_data_item</code></h2>
				1542	<h4>appears in the <code>data</code> section</h4>
				1543	<h4>alignment: none (byte-aligned)</h4>
				1544
				1545	<table class="format">
				1546	<thead>
				1547	<tr>
				1548	<th>Name</th>
				1549	<th>Format</th>
				1550	<th>Description</th>
				1551	</tr>
				1552	</thead>
				1553	<tbody>
				1554	<tr>
				1555	<td>utf16_size</td>
				1556	<td>uleb128</td>
				1557	<td>size of this string, in UTF-16 code units (which is the "string
				1558	length" in many systems). That is, this is the decoded length of
				1559	the string. (The encoded length is implied by the position of
				1560	the <code>0</code> byte.)</td>
				1561	</tr>
				1562	<tr>
				1563	<td>data</td>
				1564	<td>ubyte[]</td>
				1565	<td>a series of MUTF-8 code units (a.k.a. octets, a.k.a. bytes)
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	1566	followed by a byte of value <code>0</code>. See
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	1567	"MUTF-8 (Modified UTF-8) Encoding" above for details and
				1568	discussion about the data format.
				1569	<p><b>Note:</b> It is acceptable to have a string which includes
				1570	(the encoded form of) UTF-16 surrogate code units (that is,
				1571	<code>U+d800</code> … <code>U+dfff</code>)
				1572	either in isolation or out-of-order with respect to the usual
				1573	encoding of Unicode into UTF-16. It is up to higher-level uses of
				1574	strings to reject such invalid encodings, if appropriate.</p>
				1575	</td>
				1576	</tr>
				1577	</tbody>
				1578	</table>
				1579
				1580	<h2><code>type_id_item</code></h2>
				1581	<h4>appears in the <code>type_ids</code> section</h4>
				1582	<h4>alignment: 4 bytes</h4>
				1583
				1584	<table class="format">
				1585	<thead>
				1586	<tr>
				1587	<th>Name</th>
				1588	<th>Format</th>
				1589	<th>Description</th>
				1590	</tr>
				1591	</thead>
				1592	<tbody>
				1593	<tr>
				1594	<td>descriptor_idx</td>
				1595	<td>uint</td>
				1596	<td>index into the <code>string_ids</code> list for the descriptor
				1597	string of this type. The string must conform to the syntax for
				1598	<i>TypeDescriptor</i>, defined above.
				1599	</td>
				1600	</tr>
				1601	</tbody>
				1602	</table>
				1603
				1604	<h2><code>proto_id_item</code></h2>
				1605	<h4>appears in the <code>proto_ids</code> section</h4>
				1606	<h4>alignment: 4 bytes</h4>
				1607
				1608	<table class="format">
				1609	<thead>
				1610	<tr>
				1611	<th>Name</th>
				1612	<th>Format</th>
				1613	<th>Description</th>
				1614	</tr>
				1615	</thead>
				1616	<tbody>
				1617	<tr>
				1618	<td>shorty_idx</td>
				1619	<td>uint</td>
				1620	<td>index into the <code>string_ids</code> list for the short-form
				1621	descriptor string of this prototype. The string must conform to the
				1622	syntax for <i>ShortyDescriptor</i>, defined above, and must correspond
				1623	to the return type and parameters of this item.
				1624	</td>
				1625	</tr>
				1626	<tr>
				1627	<td>return_type_idx</td>
				1628	<td>uint</td>
				1629	<td>index into the <code>type_ids</code> list for the return type
				1630	of this prototype
				1631	</td>
				1632	</tr>
				1633	<tr>
				1634	<td>parameters_off</td>
				1635	<td>uint</td>
				1636	<td>offset from the start of the file to the list of parameter types
				1637	for this prototype, or <code>0</code> if this prototype has no
				1638	parameters. This offset, if non-zero, should be in the
				1639	<code>data</code> section, and the data there should be in the
				1640	format specified by <code>"type_list"</code> below. Additionally, there
				1641	should be no reference to the type <code>void</code> in the list.
				1642	</td>
				1643	</tr>
				1644	</tbody>
				1645	</table>
				1646
				1647	<h2><code>field_id_item</code></h2>
				1648	<h4>appears in the <code>field_ids</code> section</h4>
				1649	<h4>alignment: 4 bytes</h4>
				1650
				1651	<table class="format">
				1652	<thead>
				1653	<tr>
				1654	<th>Name</th>
				1655	<th>Format</th>
				1656	<th>Description</th>
				1657	</tr>
				1658	</thead>
				1659	<tbody>
				1660	<tr>
				1661	<td>class_idx</td>
				1662	<td>ushort</td>
				1663	<td>index into the <code>type_ids</code> list for the definer of this
				1664	field. This must be a class type, and not an array or primitive type.
				1665	</td>
				1666	</tr>
				1667	<tr>
				1668	<td>type_idx</td>
				1669	<td>ushort</td>
				1670	<td>index into the <code>type_ids</code> list for the type of
				1671	this field
				1672	</td>
				1673	</tr>
				1674	<tr>
				1675	<td>name_idx</td>
				1676	<td>uint</td>
				1677	<td>index into the <code>string_ids</code> list for the name of this
				1678	field. The string must conform to the syntax for <i>MemberName</i>,
				1679	defined above.
				1680	</td>
				1681	</tr>
				1682	</tbody>
				1683	</table>
				1684
				1685	<h2><code>method_id_item</code></h2>
				1686	<h4>appears in the <code>method_ids</code> section</h4>
				1687	<h4>alignment: 4 bytes</h4>
				1688
				1689	<table class="format">
				1690	<thead>
				1691	<tr>
				1692	<th>Name</th>
				1693	<th>Format</th>
				1694	<th>Description</th>
				1695	</tr>
				1696	</thead>
				1697	<tbody>
				1698	<tr>
				1699	<td>class_idx</td>
				1700	<td>ushort</td>
				1701	<td>index into the <code>type_ids</code> list for the definer of this
				1702	method. This must be a class or array type, and not a primitive type.
				1703	</td>
				1704	</tr>
				1705	<tr>
				1706	<td>proto_idx</td>
				1707	<td>ushort</td>
				1708	<td>index into the <code>proto_ids</code> list for the prototype of
				1709	this method
				1710	</td>
				1711	</tr>
				1712	<tr>
				1713	<td>name_idx</td>
				1714	<td>uint</td>
				1715	<td>index into the <code>string_ids</code> list for the name of this
				1716	method. The string must conform to the syntax for <i>MemberName</i>,
				1717	defined above.
				1718	</td>
				1719	</tr>
				1720	</tbody>
				1721	</table>
				1722
				1723	<h2><code>class_def_item</code></h2>
				1724	<h4>appears in the <code>class_defs</code> section</h4>
				1725	<h4>alignment: 4 bytes</h4>
				1726
				1727	<table class="format">
				1728	<thead>
				1729	<tr>
				1730	<th>Name</th>
				1731	<th>Format</th>
				1732	<th>Description</th>
				1733	</tr>
				1734	</thead>
				1735	<tbody>
				1736	<tr>
				1737	<td>class_idx</td>
				1738	<td>uint</td>
				1739	<td>index into the <code>type_ids</code> list for this class.
				1740	This must be a class type, and not an array or primitive type.
				1741	</td>
				1742	</tr>
				1743	<tr>
				1744	<td>access_flags</td>
				1745	<td>uint</td>
				1746	<td>access flags for the class (<code>public</code>, <code>final</code>,
				1747	etc.). See "<code>access_flags</code> Definitions" for details.
				1748	</td>
				1749	</tr>
				1750	<tr>
				1751	<td>superclass_idx</td>
				1752	<td>uint</td>
				1753	<td>index into the <code>type_ids</code> list for the superclass, or
				1754	the constant value <code>NO_INDEX</code> if this class has no
				1755	superclass (i.e., it is a root class such as <code>Object</code>).
				1756	If present, this must be a class type, and not an array or primitive type.
				1757	</td>
				1758	</tr>
				1759	<tr>
				1760	<td>interfaces_off</td>
				1761	<td>uint</td>
				1762	<td>offset from the start of the file to the list of interfaces, or
				1763	<code>0</code> if there are none. This offset
				1764	should be in the <code>data</code> section, and the data
				1765	there should be in the format specified by
				1766	"<code>type_list</code>" below. Each of the elements of the list
				1767	must be a class type (not an array or primitive type), and there
				1768	must not be any duplicates.
				1769	</td>
				1770	</tr>
				1771	<tr>
				1772	<td>source_file_idx</td>
				1773	<td>uint</td>
				1774	<td>index into the <code>string_ids</code> list for the name of the
				1775	file containing the original source for (at least most of) this class,
				1776	or the special value <code>NO_INDEX</code> to represent a lack of
				1777	this information. The <code>debug_info_item</code> of any given method
				1778	may override this source file, but the expectation is that most classes
				1779	will only come from one source file.
				1780	</td>
				1781	</tr>
				1782	<tr>
				1783	<td>annotations_off</td>
				1784	<td>uint</td>
				1785	<td>offset from the start of the file to the annotations structure
				1786	for this class, or <code>0</code> if there are no annotations on
				1787	this class. This offset, if non-zero, should be in the
				1788	<code>data</code> section, and the data there should be in
				1789	the format specified by "<code>annotations_directory_item</code>" below,
				1790	with all items referring to this class as the definer.
				1791	</td>
				1792	</tr>
				1793	<tr>
				1794	<td>class_data_off</td>
				1795	<td>uint</td>
				1796	<td>offset from the start of the file to the associated
				1797	class data for this item, or <code>0</code> if there is no class
				1798	data for this class. (This may be the case, for example, if this class
				1799	is a marker interface.) The offset, if non-zero, should be in the
				1800	<code>data</code> section, and the data there should be in the
				1801	format specified by "<code>class_data_item</code>" below, with all
				1802	items referring to this class as the definer.
				1803	</td>
				1804	</tr>
				1805	<tr>
				1806	<td>static_values_off</td>
				1807	<td>uint</td>
				1808	<td>offset from the start of the file to the list of initial
				1809	values for <code>static</code> fields, or <code>0</code> if there
				1810	are none (and all <code>static</code> fields are to be initialized with
				1811	<code>0</code> or <code>null</code>). This offset should be in the
				1812	<code>data</code> section, and the data there should be in the
				1813	format specified by "<code>encoded_array_item</code>" below. The size
				1814	of the array must be no larger than the number of <code>static</code>
				1815	fields declared by this class, and the elements correspond to the
				1816	<code>static</code> fields in the same order as declared in the
				1817	corresponding <code>field_list</code>. The type of each array
				1818	element must match the declared type of its corresponding field.
				1819	If there are fewer elements in the array than there are
				1820	<code>static</code> fields, then the leftover fields are initialized
				1821	with a type-appropriate <code>0</code> or <code>null</code>.
				1822	</td>
				1823	</tr>
				1824	</tbody>
				1825	</table>
				1826
				1827	<h2><code>class_data_item</code></h2>
				1828	<h4>referenced from <code>class_def_item</code></h4>
				1829	<h4>appears in the <code>data</code> section</h4>
				1830	<h4>alignment: none (byte-aligned)</h4>
				1831
				1832	<table class="format">
				1833	<thead>
				1834	<tr>
				1835	<th>Name</th>
				1836	<th>Format</th>
				1837	<th>Description</th>
				1838	</tr>
				1839	</thead>
				1840	<tbody>
				1841	<tr>
				1842	<td>static_fields_size</td>
				1843	<td>uleb128</td>
				1844	<td>the number of static fields defined in this item</td>
				1845	</tr>
				1846	<tr>
				1847	<td>instance_fields_size</td>
				1848	<td>uleb128</td>
				1849	<td>the number of instance fields defined in this item</td>
				1850	</tr>
				1851	<tr>
				1852	<td>direct_methods_size</td>
				1853	<td>uleb128</td>
				1854	<td>the number of direct methods defined in this item</td>
				1855	</tr>
				1856	<tr>
				1857	<td>virtual_methods_size</td>
				1858	<td>uleb128</td>
				1859	<td>the number of virtual methods defined in this item</td>
				1860	</tr>
				1861	<tr>
				1862	<td>static_fields</td>
				1863	<td>encoded_field[static_fields_size]</td>
				1864	<td>the defined static fields, represented as a sequence of
				1865	encoded elements. The fields must be sorted by
				1866	<code>field_idx</code> in increasing order.
				1867	</td>
				1868	</tr>
				1869	<tr>
				1870	<td>instance_fields</td>
				1871	<td>encoded_field[instance_fields_size]</td>
				1872	<td>the defined instance fields, represented as a sequence of
				1873	encoded elements. The fields must be sorted by
				1874	<code>field_idx</code> in increasing order.
				1875	</td>
				1876	</tr>
				1877	<tr>
				1878	<td>direct_methods</td>
				1879	<td>encoded_method[direct_methods_size]</td>
				1880	<td>the defined direct (any of <code>static</code>, <code>private</code>,
				1881	or constructor) methods, represented as a sequence of
				1882	encoded elements. The methods must be sorted by
				1883	<code>method_idx</code> in increasing order.
				1884	</td>
				1885	</tr>
				1886	<tr>
				1887	<td>virtual_methods</td>
				1888	<td>encoded_method[virtual_methods_size]</td>
				1889	<td>the defined virtual (none of <code>static</code>, <code>private</code>,
				1890	or constructor) methods, represented as a sequence of
				1891	encoded elements. This list should <i>not</i> include inherited
				1892	methods unless overridden by the class that this item represents. The
				1893	methods must be sorted by <code>method_idx</code> in increasing order.
				1894	</td>
				1895	</tr>
				1896	</tbody>
				1897	</table>
				1898
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	1899	<p><b>Note:</b> All elements' <code>field_id</code>s and
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	1900	<code>method_id</code>s must refer to the same defining class.</p>
				1901
				1902	<h3><code>encoded_field</code> Format</h3>
				1903
				1904	<table class="format">
				1905	<thead>
				1906	<tr>
				1907	<th>Name</th>
				1908	<th>Format</th>
				1909	<th>Description</th>
				1910	</tr>
				1911	</thead>
				1912	<tbody>
				1913	<tr>
				1914	<td>field_idx_diff</td>
				1915	<td>uleb128</td>
				1916	<td>index into the <code>field_ids</code> list for the identity of this
				1917	field (includes the name and descriptor), represented as a difference
				1918	from the index of previous element in the list. The index of the
				1919	first element in a list is represented directly.
				1920	</td>
				1921	</tr>
				1922	<tr>
				1923	<td>access_flags</td>
				1924	<td>uleb128</td>
				1925	<td>access flags for the field (<code>public</code>, <code>final</code>,
				1926	etc.). See "<code>access_flags</code> Definitions" for details.
				1927	</td>
				1928	</tr>
				1929	</tbody>
				1930	</table>
				1931
				1932	<h3><code>encoded_method</code> Format</h3>
				1933
				1934	<table class="format">
				1935	<thead>
				1936	<tr>
				1937	<th>Name</th>
				1938	<th>Format</th>
				1939	<th>Description</th>
				1940	</tr>
				1941	</thead>
				1942	<tbody>
				1943	<tr>
				1944	<td>method_idx_diff</td>
				1945	<td>uleb128</td>
				1946	<td>index into the <code>method_ids</code> list for the identity of this
				1947	method (includes the name and descriptor), represented as a difference
				1948	from the index of previous element in the list. The index of the
				1949	first element in a list is represented directly.
				1950	</td>
				1951	</tr>
				1952	<tr>
				1953	<td>access_flags</td>
				1954	<td>uleb128</td>
				1955	<td>access flags for the method (<code>public</code>, <code>final</code>,
				1956	etc.). See "<code>access_flags</code> Definitions" for details.
				1957	</td>
				1958	</tr>
				1959	<tr>
				1960	<td>code_off</td>
				1961	<td>uleb128</td>
				1962	<td>offset from the start of the file to the code structure for this
				1963	method, or <code>0</code> if this method is either <code>abstract</code>
				1964	or <code>native</code>. The offset should be to a location in the
				1965	<code>data</code> section. The format of the data is specified by
				1966	"<code>code_item</code>" below.
				1967	</td>
				1968	</tr>
				1969	</tbody>
				1970	</table>
				1971
				1972	<h2><code>type_list</code></h2>
				1973	<h4>referenced from <code>class_def_item</code> and
				1974	<code>proto_id_item</code></h4>
				1975	<h4>appears in the <code>data</code> section</h4>
				1976	<h4>alignment: 4 bytes</h4>
				1977
				1978	<table class="format">
				1979	<thead>
				1980	<tr>
				1981	<th>Name</th>
				1982	<th>Format</th>
				1983	<th>Description</th>
				1984	</tr>
				1985	</thead>
				1986	<tbody>
				1987	<tr>
				1988	<td>size</td>
				1989	<td>uint</td>
				1990	<td>size of the list, in entries</td>
				1991	</tr>
				1992	<tr>
				1993	<td>list</td>
				1994	<td>type_item[size]</td>
				1995	<td>elements of the list</td>
				1996	</tr>
				1997	</tbody>
				1998	</table>
				1999
				2000	<h3><code>type_item</code> Format</h3>
				2001
				2002	<table class="format">
				2003	<thead>
				2004	<tr>
				2005	<th>Name</th>
				2006	<th>Format</th>
				2007	<th>Description</th>
				2008	</tr>
				2009	</thead>
				2010	<tbody>
				2011	<tr>
				2012	<td>type_idx</td>
				2013	<td>ushort</td>
				2014	<td>index into the <code>type_ids</code> list</td>
				2015	</tr>
				2016	</tbody>
				2017	</table>
				2018
				2019	<h2><code>code_item</code></h2>
Dan Bornstein	5cbbea3	2011-04-05 15:17:25 -0700	[diff] [blame]	2020	<h4>referenced from <code>encoded_method</code></h4>
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2021	<h4>appears in the <code>data</code> section</h4>
				2022	<h4>alignment: 4 bytes</h4>
				2023
				2024	<table class="format">
				2025	<thead>
				2026	<tr>
				2027	<th>Name</th>
				2028	<th>Format</th>
				2029	<th>Description</th>
				2030	</tr>
				2031	</thead>
				2032	<tbody>
				2033	<tr>
				2034	<td>registers_size</td>
				2035	<td>ushort</td>
				2036	<td>the number of registers used by this code</td>
				2037	</tr>
				2038	<tr>
				2039	<td>ins_size</td>
				2040	<td>ushort</td>
				2041	<td>the number of words of incoming arguments to the method that this
				2042	code is for</td>
				2043	</tr>
				2044	<tr>
				2045	<td>outs_size</td>
				2046	<td>ushort</td>
				2047	<td>the number of words of outgoing argument space required by this
				2048	code for method invocation
				2049	</td>
				2050	</tr>
				2051	<tr>
				2052	<td>tries_size</td>
				2053	<td>ushort</td>
				2054	<td>the number of <code>try_item</code>s for this instance. If non-zero,
				2055	then these appear as the <code>tries</code> array just after the
				2056	<code>insns</code> in this instance.
				2057	</td>
				2058	</tr>
				2059	<tr>
				2060	<td>debug_info_off</td>
				2061	<td>uint</td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2062	<td>offset from the start of the file to the debug info (line numbers +
				2063	local variable info) sequence for this code, or <code>0</code> if
				2064	there simply is no information. The offset, if non-zero, should be
				2065	to a location in the <code>data</code> section. The format of
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2066	the data is specified by "<code>debug_info_item</code>" below.
				2067	</td>
				2068	</tr>
				2069	<tr>
				2070	<td>insns_size</td>
				2071	<td>uint</td>
				2072	<td>size of the instructions list, in 16-bit code units</td>
				2073	</tr>
				2074	<tr>
				2075	<td>insns</td>
				2076	<td>ushort[insns_size]</td>
				2077	<td>actual array of bytecode. The format of code in an <code>insns</code>
				2078	array is specified by the companion document
				2079	<a href="dalvik-bytecode.html">"Bytecode for the Dalvik VM"</a>. Note
				2080	that though this is defined as an array of <code>ushort</code>, there
				2081	are some internal structures that prefer four-byte alignment. Also,
				2082	if this happens to be in an endian-swapped file, then the swapping is
				2083	<i>only</i> done on individual <code>ushort</code>s and not on the
				2084	larger internal structures.
				2085	</td>
				2086	</tr>
				2087	<tr>
				2088	<td>padding</td>
				2089	<td>ushort <i>(optional)</i> = 0</td>
				2090	<td>two bytes of padding to make <code>tries</code> four-byte aligned.
				2091	This element is only present if <code>tries_size</code> is non-zero
				2092	and <code>insns_size</code> is odd.
				2093	</td>
				2094	</tr>
				2095	<tr>
				2096	<td>tries</td>
				2097	<td>try_item[tries_size] <i>(optional)</i></td>
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	2098	<td>array indicating where in the code exceptions are caught and
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2099	how to handle them. Elements of the array must be non-overlapping in
				2100	range and in order from low to high address. This element is only
				2101	present if <code>tries_size</code> is non-zero.
				2102	</td>
				2103	</tr>
				2104	<tr>
				2105	<td>handlers</td>
				2106	<td>encoded_catch_handler_list <i>(optional)</i></td>
				2107	<td>bytes representing a list of lists of catch types and associated
				2108	handler addresses. Each <code>try_item</code> has a byte-wise offset
				2109	into this structure. This element is only present if
				2110	<code>tries_size</code> is non-zero.
				2111	</td>
				2112	</tr>
				2113	</tbody>
				2114	</table>
				2115
				2116	<h3><code>try_item</code> Format </h3>
				2117
				2118	<table class="format">
				2119	<thead>
				2120	<tr>
				2121	<th>Name</th>
				2122	<th>Format</th>
				2123	<th>Description</th>
				2124	</tr>
				2125	</thead>
				2126	<tbody>
				2127	<tr>
				2128	<td>start_addr</td>
				2129	<td>uint</td>
				2130	<td>start address of the block of code covered by this entry. The address
				2131	is a count of 16-bit code units to the start of the first covered
				2132	instruction.
				2133	</td>
				2134	</tr>
				2135	<tr>
				2136	<td>insn_count</td>
				2137	<td>ushort</td>
				2138	<td>number of 16-bit code units covered by this entry. The last code
				2139	unit covered (inclusive) is <code>start_addr + insn_count - 1</code>.
				2140	</td>
				2141	</tr>
				2142	<tr>
				2143	<td>handler_off</td>
				2144	<td>ushort</td>
Dan Bornstein	8daf827	2010-12-01 16:28:49 -0800	[diff] [blame]	2145	<td>offset in bytes from the start of the associated
				2146	<code>encoded_catch_hander_list</code> to the
				2147	<code>encoded_catch_handler</code> for this entry. This must be an
				2148	offset to the start of an <code>encoded_catch_handler</code>.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2149	</td>
				2150	</tr>
				2151	</tbody>
				2152	</table>
				2153
				2154	<h3><code>encoded_catch_handler_list</code> Format</h3>
				2155
				2156	<table class="format">
				2157	<thead>
				2158	<tr>
				2159	<th>Name</th>
				2160	<th>Format</th>
				2161	<th>Description</th>
				2162	</tr>
				2163	</thead>
				2164	<tbody>
				2165	<tr>
				2166	<td>size</td>
				2167	<td>uleb128</td>
				2168	<td>size of this list, in entries</td>
				2169	</tr>
				2170	<tr>
				2171	<td>list</td>
				2172	<td>encoded_catch_handler[handlers_size]</td>
				2173	<td>actual list of handler lists, represented directly (not as offsets),
				2174	and concatenated sequentially</td>
				2175	</tr>
				2176	</tbody>
				2177	</table>
				2178
				2179	<h3><code>encoded_catch_handler</code> Format</h3>
				2180
				2181	<table class="format">
				2182	<thead>
				2183	<tr>
				2184	<th>Name</th>
				2185	<th>Format</th>
				2186	<th>Description</th>
				2187	</tr>
				2188	</thead>
				2189	<tbody>
				2190	<tr>
				2191	<td>size</td>
				2192	<td>sleb128</td>
				2193	<td>number of catch types in this list. If non-positive, then this is
				2194	the negative of the number of catch types, and the catches are followed
				2195	by a catch-all handler. For example: A <code>size</code> of <code>0</code>
				2196	means that there is a catch-all but no explicitly typed catches.
				2197	A <code>size</code> of <code>2</code> means that there are two explicitly
				2198	typed catches and no catch-all. And a <code>size</code> of <code>-1</code>
				2199	means that there is one typed catch along with a catch-all.
				2200	</td>
				2201	</tr>
				2202	<tr>
				2203	<td>handlers</td>
				2204	<td>encoded_type_addr_pair[abs(size)]</td>
				2205	<td>stream of <code>abs(size)</code> encoded items, one for each caught
				2206	type, in the order that the types should be tested.
				2207	</td>
				2208	</tr>
				2209	<tr>
				2210	<td>catch_all_addr</td>
				2211	<td>uleb128 <i>(optional)</i></td>
				2212	<td>bytecode address of the catch-all handler. This element is only
				2213	present if <code>size</code> is non-positive.
				2214	</td>
				2215	</tr>
				2216	</tbody>
				2217	</table>
				2218
				2219	<h3><code>encoded_type_addr_pair</code> Format</h3>
				2220
				2221	<table class="format">
				2222	<thead>
				2223	<tr>
				2224	<th>Name</th>
				2225	<th>Format</th>
				2226	<th>Description</th>
				2227	</tr>
				2228	</thead>
				2229	<tbody>
				2230	<tr>
				2231	<td>type_idx</td>
				2232	<td>uleb128</td>
				2233	<td>index into the <code>type_ids</code> list for the type of the
				2234	exception to catch
				2235	</td>
				2236	</tr>
				2237	<tr>
				2238	<td>addr</td>
				2239	<td>uleb128</td>
				2240	<td>bytecode address of the associated exception handler</td>
				2241	</tr>
				2242	</tbody>
				2243	</table>
				2244
				2245	<h2><code>debug_info_item</code></h2>
				2246	<h4>referenced from <code>code_item</code></h4>
				2247	<h4>appears in the <code>data</code> section</h4>
				2248	<h4>alignment: none (byte-aligned)</h4>
				2249
				2250	<p>Each <code>debug_info_item</code> defines a DWARF3-inspired byte-coded
				2251	state machine that, when interpreted, emits the positions
				2252	table and (potentially) the local variable information for a
				2253	<code>code_item</code>. The sequence begins with a variable-length
				2254	header (the length of which depends on the number of method
				2255	parameters), is followed by the state machine bytecodes, and ends
				2256	with an <code>DBG_END_SEQUENCE</code> byte.</p>
				2257
				2258	<p>The state machine consists of five registers. The
				2259	<code>address</code> register represents the instruction offset in the
				2260	associated <code>insns_item</code> in 16-bit code units. The
				2261	<code>address</code> register starts at <code>0</code> at the beginning of each
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	2262	<code>debug_info</code> sequence and must only monotonically increase.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2263	The <code>line</code> register represents what source line number
				2264	should be associated with the next positions table entry emitted by
				2265	the state machine. It is initialized in the sequence header, and may
				2266	change in positive or negative directions but must never be less than
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2267	<code>1</code>. The <code>source_file</code> register represents the
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2268	source file that the line number entries refer to. It is initialized to
				2269	the value of <code>source_file_idx</code> in <code>class_def_item</code>.
				2270	The other two variables, <code>prologue_end</code> and
				2271	<code>epilogue_begin</code>, are boolean flags (initialized to
				2272	<code>false</code>) that indicate whether the next position emitted
				2273	should be considered a method prologue or epilogue. The state machine
				2274	must also track the name and type of the last local variable live in
				2275	each register for the <code>DBG_RESTART_LOCAL</code> code.</p>
				2276
				2277	<p>The header is as follows:</p>
				2278
				2279	<table class="format">
				2280	<thead>
				2281	<tr>
				2282	<th>Name</th>
				2283	<th>Format</th>
				2284	<th>Description</th>
				2285	</tr>
				2286	</thead>
				2287	<tbody>
				2288	<tr>
				2289	<td>line_start</td>
				2290	<td>uleb128</td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2291	<td>the initial value for the state machine's <code>line</code> register.
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2292	Does not represent an actual positions entry.
				2293	</td>
				2294	</tr>
				2295	<tr>
				2296	<td>parameters_size</td>
				2297	<td>uleb128</td>
				2298	<td>the number of parameter names that are encoded. There should be
				2299	one per method parameter, excluding an instance method's <code>this</code>,
				2300	if any.
				2301	</td>
				2302	</tr>
				2303	<tr>
				2304	<td>parameter_names</td>
				2305	<td>uleb128p1[parameters_size]</td>
				2306	<td>string index of the method parameter name. An encoded value of
				2307	<code>NO_INDEX</code> indicates that no name
				2308	is available for the associated parameter. The type descriptor
				2309	and signature are implied from the method descriptor and signature.
				2310	</td>
				2311	</tr>
				2312	</tbody>
				2313	</table>
				2314
				2315	<p>The byte code values are as follows:</p>
				2316
				2317	<table class="debugByteCode">
				2318	<thead>
				2319	<tr>
				2320	<th>Name</th>
				2321	<th>Value</th>
				2322	<th>Format</th>
				2323	<th>Arguments</th>
				2324	<th>Description</th>
				2325	</tr>
				2326	</thead>
				2327	<tbody>
				2328	<tr>
				2329	<td>DBG_END_SEQUENCE</td>
				2330	<td>0x00</td>
				2331	<td></td>
				2332	<td><i>(none)</i></td>
				2333	<td>terminates a debug info sequence for a <code>code_item</code></td>
				2334	</tr>
				2335	<tr>
				2336	<td>DBG_ADVANCE_PC</td>
				2337	<td>0x01</td>
				2338	<td>uleb128 addr_diff</td>
				2339	<td><code>addr_diff</code>: amount to add to address register</td>
				2340	<td>advances the address register without emitting a positions entry</td>
				2341	</tr>
				2342	<tr>
				2343	<td>DBG_ADVANCE_LINE</td>
				2344	<td>0x02</td>
				2345	<td>sleb128 line_diff</td>
				2346	<td><code>line_diff</code>: amount to change line register by</td>
				2347	<td>advances the line register without emitting a positions entry</td>
				2348	</tr>
				2349	<tr>
				2350	<td>DBG_START_LOCAL</td>
				2351	<td>0x03</td>
				2352	<td>uleb128 register_num<br/>
				2353	uleb128p1 name_idx<br/>
				2354	uleb128p1 type_idx
				2355	</td>
				2356	<td><code>register_num</code>: register that will contain local<br/>
				2357	<code>name_idx</code>: string index of the name<br/>
				2358	<code>type_idx</code>: type index of the type
				2359	</td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2360	<td>introduces a local variable at the current address. Either
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2361	<code>name_idx</code> or <code>type_idx</code> may be
				2362	<code>NO_INDEX</code> to indicate that that value is unknown.
				2363	</td>
				2364	</tr>
				2365	<tr>
				2366	<td>DBG_START_LOCAL_EXTENDED</td>
				2367	<td>0x04</td>
				2368	<td>uleb128 register_num<br/>
				2369	uleb128p1 name_idx<br/>
				2370	uleb128p1 type_idx<br/>
				2371	uleb128p1 sig_idx
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2372	</td>
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2373	<td><code>register_num</code>: register that will contain local<br/>
				2374	<code>name_idx</code>: string index of the name<br/>
				2375	<code>type_idx</code>: type index of the type<br/>
				2376	<code>sig_idx</code>: string index of the type signature
				2377	</td>
				2378	<td>introduces a local with a type signature at the current address.
				2379	Any of <code>name_idx</code>, <code>type_idx</code>, or
				2380	<code>sig_idx</code> may be <code>NO_INDEX</code>
				2381	to indicate that that value is unknown. (If <code>sig_idx</code> is
				2382	<code>-1</code>, though, the same data could be represented more
				2383	efficiently using the opcode <code>DBG_START_LOCAL</code>.)
				2384	<p><b>Note:</b> See the discussion under
				2385	"<code>dalvik.annotation.Signature</code>" below for caveats about
				2386	handling signatures.</p>
				2387	</td>
				2388	</tr>
				2389	<tr>
				2390	<td>DBG_END_LOCAL</td>
				2391	<td>0x05</td>
				2392	<td>uleb128 register_num</td>
				2393	<td><code>register_num</code>: register that contained local</td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2394	<td>marks a currently-live local variable as out of scope at the current
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2395	address
				2396	</td>
				2397	</tr>
				2398	<tr>
				2399	<td>DBG_RESTART_LOCAL</td>
				2400	<td>0x06</td>
				2401	<td>uleb128 register_num</td>
				2402	<td><code>register_num</code>: register to restart</td>
				2403	<td>re-introduces a local variable at the current address. The name
				2404	and type are the same as the last local that was live in the specified
				2405	register.
				2406	</td>
				2407	</tr>
				2408	<tr>
				2409	<td>DBG_SET_PROLOGUE_END</td>
				2410	<td>0x07</td>
				2411	<td></td>
				2412	<td><i>(none)</i></td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2413	<td>sets the <code>prologue_end</code> state machine register,
				2414	indicating that the next position entry that is added should be
				2415	considered the end of a method prologue (an appropriate place for
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2416	a method breakpoint). The <code>prologue_end</code> register is
				2417	cleared by any special (<code>>= 0x0a</code>) opcode.
				2418	</td>
				2419	</tr>
				2420	<tr>
				2421	<td>DBG_SET_EPILOGUE_BEGIN</td>
				2422	<td>0x08</td>
				2423	<td></td>
				2424	<td><i>(none)</i></td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2425	<td>sets the <code>epilogue_begin</code> state machine register,
				2426	indicating that the next position entry that is added should be
				2427	considered the beginning of a method epilogue (an appropriate place
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2428	to suspend execution before method exit).
				2429	The <code>epilogue_begin</code> register is cleared by any special
				2430	(<code>>= 0x0a</code>) opcode.
				2431	</td>
				2432	</tr>
				2433	<tr>
				2434	<td>DBG_SET_FILE</td>
				2435	<td>0x09</td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2436	<td>uleb128p1 name_idx</td>
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2437	<td><code>name_idx</code>: string index of source file name;
				2438	<code>NO_INDEX</code> if unknown
				2439	</td>
				2440	<td>indicates that all subsequent line number entries make reference to this
				2441	source file name, instead of the default name specified in
				2442	<code>code_item</code>
				2443	</td>
				2444	</tr>
				2445	<tr>
				2446	<td><i>Special Opcodes</i></td>
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2447	<!-- When updating the range below, make sure to search for other
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2448	instances of 0x0a in this section. -->
				2449	<td>0x0a…0xff</td>
				2450	<td></td>
				2451	<td><i>(none)</i></td>
				2452	<td>advances the <code>line</code> and <code>address</code> registers,
				2453	emits a position entry, and clears <code>prologue_end</code> and
				2454	<code>epilogue_begin</code>. See below for description.
				2455	</td>
				2456	</tr>
				2457	</tbody>
				2458	</table>
				2459
				2460	<h3>Special Opcodes</h3>
				2461
				2462	<p>Opcodes with values between <code>0x0a</code> and <code>0xff</code>
				2463	(inclusive) move both the <code>line</code> and <code>address</code>
				2464	registers by a small amount and then emit a new position table entry.
				2465	The formula for the increments are as follows:</p>
				2466
				2467	<pre>
				2468	DBG_FIRST_SPECIAL = 0x0a // the smallest special opcode
				2469	DBG_LINE_BASE = -4 // the smallest line number increment
				2470	DBG_LINE_RANGE = 15 // the number of line increments represented
				2471
				2472	adjusted_opcode = opcode - DBG_FIRST_SPECIAL
				2473
				2474	line += DBG_LINE_BASE + (adjusted_opcode % DBG_LINE_RANGE)
				2475	address += (adjusted_opcode / DBG_LINE_RANGE)
				2476	</pre>
				2477
				2478	<h2><code>annotations_directory_item</code></h2>
				2479	<h4>referenced from <code>class_def_item</code></h4>
				2480	<h4>appears in the <code>data</code> section</h4>
				2481	<h4>alignment: 4 bytes</h4>
				2482
				2483	<table class="format">
				2484	<thead>
				2485	<tr>
				2486	<th>Name</th>
				2487	<th>Format</th>
				2488	<th>Description</th>
				2489	</tr>
				2490	</thead>
				2491	<tbody>
				2492	<tr>
				2493	<td>class_annotations_off</td>
				2494	<td>uint</td>
				2495	<td>offset from the start of the file to the annotations made directly
				2496	on the class, or <code>0</code> if the class has no direct annotations.
				2497	The offset, if non-zero, should be to a location in the
				2498	<code>data</code> section. The format of the data is specified
				2499	by "<code>annotation_set_item</code>" below.
				2500	</td>
				2501	</tr>
				2502	<tr>
				2503	<td>fields_size</td>
				2504	<td>uint</td>
				2505	<td>count of fields annotated by this item</td>
				2506	</tr>
				2507	<tr>
Ben Gruver	45313eb	2009-06-03 21:28:35 -0500	[diff] [blame]	2508	<td>annotated_methods_size</td>
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2509	<td>uint</td>
				2510	<td>count of methods annotated by this item</td>
				2511	</tr>
				2512	<tr>
Ben Gruver	45313eb	2009-06-03 21:28:35 -0500	[diff] [blame]	2513	<td>annotated_parameters_size</td>
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2514	<td>uint</td>
				2515	<td>count of method parameter lists annotated by this item</td>
				2516	</tr>
				2517	<tr>
				2518	<td>field_annotations</td>
				2519	<td>field_annotation[fields_size] <i>(optional)</i></td>
				2520	<td>list of associated field annotations. The elements of the list must
				2521	be sorted in increasing order, by <code>field_idx</code>.
				2522	</td>
				2523	</tr>
				2524	<tr>
				2525	<td>method_annotations</td>
				2526	<td>method_annotation[methods_size] <i>(optional)</i></td>
				2527	<td>list of associated method annotations. The elements of the list must
				2528	be sorted in increasing order, by <code>method_idx</code>.
				2529	</td>
				2530	</tr>
				2531	<tr>
				2532	<td>parameter_annotations</td>
				2533	<td>parameter_annotation[parameters_size] <i>(optional)</i></td>
				2534	<td>list of associated method parameter annotations. The elements of the
				2535	list must be sorted in increasing order, by <code>method_idx</code>.
				2536	</td>
				2537	</tr>
				2538	</tbody>
				2539	</table>
				2540
Carl Shapiro	de75089	2010-06-08 16:37:12 -0700	[diff] [blame]	2541	<p><b>Note:</b> All elements' <code>field_id</code>s and
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2542	<code>method_id</code>s must refer to the same defining class.</p>
				2543
				2544	<h3><code>field_annotation</code> Format</h3>
				2545
				2546	<table class="format">
				2547	<thead>
				2548	<tr>
				2549	<th>Name</th>
				2550	<th>Format</th>
				2551	<th>Description</th>
				2552	</tr>
				2553	</thead>
				2554	<tbody>
				2555	<tr>
				2556	<td>field_idx</td>
				2557	<td>uint</td>
				2558	<td>index into the <code>field_ids</code> list for the identity of the
				2559	field being annotated
				2560	</td>
				2561	</tr>
				2562	<tr>
				2563	<td>annotations_off</td>
				2564	<td>uint</td>
				2565	<td>offset from the start of the file to the list of annotations for
				2566	the field. The offset should be to a location in the <code>data</code>
				2567	section. The format of the data is specified by
				2568	"<code>annotation_set_item</code>" below.
				2569	</td>
				2570	</tr>
				2571	</tbody>
				2572	</table>
				2573
				2574	<h3><code>method_annotation</code> Format</h3>
				2575
				2576	<table class="format">
				2577	<thead>
				2578	<tr>
				2579	<th>Name</th>
				2580	<th>Format</th>
				2581	<th>Description</th>
				2582	</tr>
				2583	</thead>
				2584	<tbody>
				2585	<tr>
				2586	<td>method_idx</td>
				2587	<td>uint</td>
				2588	<td>index into the <code>method_ids</code> list for the identity of the
				2589	method being annotated
				2590	</td>
				2591	</tr>
				2592	<tr>
				2593	<td>annotations_off</td>
				2594	<td>uint</td>
				2595	<td>offset from the start of the file to the list of annotations for
				2596	the method. The offset should be to a location in the
				2597	<code>data</code> section. The format of the data is specified by
				2598	"<code>annotation_set_item</code>" below.
				2599	</td>
				2600	</tr>
				2601	</tbody>
				2602	</table>
				2603
				2604	<h3><code>parameter_annotation</code> Format</h2>
				2605
				2606	<table class="format">
				2607	<thead>
				2608	<tr>
				2609	<th>Name</th>
				2610	<th>Format</th>
				2611	<th>Description</th>
				2612	</tr>
				2613	</thead>
				2614	<tbody>
				2615	<tr>
				2616	<td>method_idx</td>
				2617	<td>uint</td>
				2618	<td>index into the <code>method_ids</code> list for the identity of the
				2619	method whose parameters are being annotated
				2620	</td>
				2621	</tr>
				2622	<tr>
				2623	<td>annotations_off</td>
				2624	<td>uint</td>
				2625	<td>offset from the start of the file to the list of annotations for
				2626	the method parameters. The offset should be to a location in the
				2627	<code>data</code> section. The format of the data is specified by
				2628	"<code>annotation_set_ref_list</code>" below.
				2629	</td>
				2630	</tr>
				2631	</tbody>
				2632	</table>
				2633
				2634	<h2><code>annotation_set_ref_list</code></h2>
				2635	<h4>referenced from <code>parameter_annotations_item</code></h4>
				2636	<h4>appears in the <code>data</code> section</h4>
				2637	<h4>alignment: 4 bytes</h4>
				2638
				2639	<table class="format">
				2640	<thead>
				2641	<tr>
				2642	<th>Name</th>
				2643	<th>Format</th>
				2644	<th>Description</th>
				2645	</tr>
				2646	</thead>
				2647	<tbody>
				2648	<tr>
				2649	<td>size</td>
				2650	<td>uint</td>
				2651	<td>size of the list, in entries</td>
				2652	</tr>
				2653	<tr>
				2654	<td>list</td>
				2655	<td>annotation_set_ref_item[size]</td>
				2656	<td>elements of the list</td>
				2657	</tr>
				2658	</tbody>
				2659	</table>
				2660
				2661	<h3><code>annotation_set_ref_item</code> Format</h3>
				2662
				2663	<table class="format">
				2664	<thead>
				2665	<tr>
				2666	<th>Name</th>
				2667	<th>Format</th>
				2668	<th>Description</th>
				2669	</tr>
				2670	</thead>
				2671	<tbody>
				2672	<tr>
				2673	<td>annotations_off</td>
				2674	<td>uint</td>
				2675	<td>offset from the start of the file to the referenced annotation set
				2676	or <code>0</code> if there are no annotations for this element.
				2677	The offset, if non-zero, should be to a location in the <code>data</code>
				2678	section. The format of the data is specified by
				2679	"<code>annotation_set_item</code>" below.
				2680	</td>
				2681	</tr>
				2682	</tbody>
				2683	</table>
				2684
				2685	<h2><code>annotation_set_item</code></h2>
				2686	<h4>referenced from <code>annotations_directory_item</code>,
				2687	<code>field_annotations_item</code>,
				2688	<code>method_annotations_item</code>, and
				2689	<code>annotation_set_ref_item</code></h4>
				2690	<h4>appears in the <code>data</code> section</h4>
				2691	<h4>alignment: 4 bytes</h4>
				2692
				2693	<table class="format">
				2694	<thead>
				2695	<tr>
				2696	<th>Name</th>
				2697	<th>Format</th>
				2698	<th>Description</th>
				2699	</tr>
				2700	</thead>
				2701	<tbody>
				2702	<tr>
				2703	<td>size</td>
				2704	<td>uint</td>
				2705	<td>size of the set, in entries</td>
				2706	</tr>
				2707	<tr>
				2708	<td>entries</td>
				2709	<td>annotation_off_item[size]</td>
				2710	<td>elements of the set. The elements must be sorted in increasing order,
				2711	by <code>type_idx</code>.
				2712	</td>
				2713	</tr>
				2714	</tbody>
				2715	</table>
				2716
				2717	<h3><code>annotation_off_item</code> Format</h3>
				2718
				2719	<table class="format">
				2720	<thead>
				2721	<tr>
				2722	<th>Name</th>
				2723	<th>Format</th>
				2724	<th>Description</th>
				2725	</tr>
				2726	</thead>
				2727	<tbody>
				2728	<tr>
				2729	<td>annotation_off</td>
				2730	<td>uint</td>
				2731	<td>offset from the start of the file to an annotation.
				2732	The offset should be to a location in the <code>data</code> section,
				2733	and the format of the data at that location is specified by
				2734	"<code>annotation_item</code>" below.
				2735	</td>
				2736	</tr>
				2737	</tbody>
				2738	</table>
				2739
				2740
				2741	<h2><code>annotation_item</code></h2>
				2742	<h4>referenced from <code>annotation_set_item</code></h4>
				2743	<h4>appears in the <code>data</code> section</h4>
				2744	<h4>alignment: none (byte-aligned)</h4>
				2745
				2746	<table class="format">
				2747	<thead>
				2748	<tr>
				2749	<th>Name</th>
				2750	<th>Format</th>
				2751	<th>Description</th>
				2752	</tr>
				2753	</thead>
				2754	<tbody>
				2755	<tr>
				2756	<td>visibility</td>
				2757	<td>ubyte</td>
				2758	<td>intended visibility of this annotation (see below)</td>
				2759	</tr>
				2760	<tr>
				2761	<td>annotation</td>
				2762	<td>encoded_annotation</td>
				2763	<td>encoded annotation contents, in the format described by
				2764	"<code>encoded_annotation</code> Format" under
				2765	"<code>encoded_value</code> Encoding" above.
				2766	</td>
				2767	</tr>
				2768	</tbody>
				2769	</table>
				2770
				2771	<h3>Visibility values</h3>
				2772
				2773	<p>These are the options for the <code>visibility</code> field in an
				2774	<code>annotation_item</code>:</p>
				2775
				2776	<table class="format">
				2777	<thead>
				2778	<tr>
				2779	<th>Name</th>
				2780	<th>Value</th>
				2781	<th>Description</th>
				2782	</tr>
				2783	</thead>
				2784	<tbody>
				2785	<tr>
				2786	<td>VISIBILITY_BUILD</td>
				2787	<td>0x00</td>
				2788	<td>intended only to be visible at build time (e.g., during compilation
				2789	of other code)
				2790	</td>
				2791	</tr>
				2792	<tr>
				2793	<td>VISIBILITY_RUNTIME</td>
				2794	<td>0x01</td>
				2795	<td>intended to visible at runtime</td>
				2796	</tr>
				2797	<tr>
				2798	<td>VISIBILITY_SYSTEM</td>
				2799	<td>0x02</td>
				2800	<td>intended to visible at runtime, but only to the underlying system
				2801	(and not to regular user code)
				2802	</td>
				2803	</tr>
				2804	</tbody>
				2805	</table>
				2806
				2807	<h2><code>encoded_array_item</code></h2>
				2808	<h4>referenced from <code>class_def_item</code></h4>
				2809	<h4>appears in the <code>data</code> section</h4>
				2810	<h4>alignment: none (byte-aligned)</h4>
				2811
				2812	<table class="format">
				2813	<thead>
				2814	<tr>
				2815	<th>Name</th>
				2816	<th>Format</th>
				2817	<th>Description</th>
				2818	</tr>
				2819	</thead>
				2820	<tbody>
				2821	<tr>
				2822	<td>value</td>
				2823	<td>encoded_array</td>
				2824	<td>bytes representing the encoded array value, in the format specified
				2825	by "<code>encoded_array</code> Format" under "<code>encoded_value</code>
				2826	Encoding" above.
				2827	</td>
				2828	</tr>
				2829	</tbody>
				2830	</table>
				2831
				2832	<h1>System Annotations</h1>
				2833
				2834	<p>System annotations are used to represent various pieces of reflective
				2835	information about classes (and methods and fields). This information is
				2836	generally only accessed indirectly by client (non-system) code.</p>
				2837
				2838	<p>System annotations are represented in <code>.dex</code> files as
				2839	annotations with visibility set to <code>VISIBILITY_SYSTEM</code>.
				2840
				2841	<h2><code>dalvik.annotation.AnnotationDefault</code></h2>
				2842	<h4>appears on methods in annotation interfaces</h4>
				2843
				2844	<p>An <code>AnnotationDefault</code> annotation is attached to each
				2845	annotation interface which wishes to indicate default bindings.</p>
				2846
				2847	<table class="format">
				2848	<thead>
				2849	<tr>
				2850	<th>Name</th>
				2851	<th>Format</th>
				2852	<th>Description</th>
				2853	</tr>
				2854	</thead>
				2855	<tbody>
				2856	<tr>
				2857	<td>value</td>
				2858	<td>Annotation</td>
				2859	<td>the default bindings for this annotation, represented as an annotation
				2860	of this type. The annotation need not include all names defined by the
				2861	annotation; missing names simply do not have defaults.
				2862	</td>
				2863	</tr>
				2864	</tbody>
				2865	</table>
				2866
				2867	<h2><code>dalvik.annotation.EnclosingClass</code></h2>
				2868	<h4>appears on classes</h4>
				2869
				2870	<p>An <code>EnclosingClass</code> annotation is attached to each class
				2871	which is either defined as a member of another class, per se, or is
				2872	anonymous but not defined within a method body (e.g., a synthetic
				2873	inner class). Every class that has this annotation must also have an
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	2874	<code>InnerClass</code> annotation. Additionally, a class must not have
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2875	both an <code>EnclosingClass</code> and an
				2876	<code>EnclosingMethod</code> annotation.</p>
				2877
				2878	<table class="format">
				2879	<thead>
				2880	<tr>
				2881	<th>Name</th>
				2882	<th>Format</th>
				2883	<th>Description</th>
				2884	</tr>
				2885	</thead>
				2886	<tbody>
				2887	<tr>
				2888	<td>value</td>
				2889	<td>Class</td>
				2890	<td>the class which most closely lexically scopes this class</td>
				2891	</tr>
				2892	</tbody>
				2893	</table>
				2894
				2895	<h2><code>dalvik.annotation.EnclosingMethod</code></h2>
				2896	<h4>appears on classes</h4>
				2897
				2898	<p>An <code>EnclosingMethod</code> annotation is attached to each class
				2899	which is defined inside a method body. Every class that has this
				2900	annotation must also have an <code>InnerClass</code> annotation.
Dan Bornstein	54db605	2011-02-17 12:47:58 -0800	[diff] [blame]	2901	Additionally, a class must not have both an <code>EnclosingClass</code>
The Android Open Source Project	2ad60cf	2008-10-21 07:00:00 -0700	[diff] [blame]	2902	and an <code>EnclosingMethod</code> annotation.</p>
				2903
				2904	<table class="format">
				2905	<thead>
				2906	<tr>
				2907	<th>Name</th>
				2908	<th>Format</th>
				2909	<th>Description</th>
				2910	</tr>
				2911	</thead>
				2912	<tbody>
				2913	<tr>
				2914	<td>value</td>
				2915	<td>Method</td>
				2916	<td>the method which most closely lexically scopes this class</td>
				2917	</tr>
				2918	</tbody>
				2919	</table>
				2920
				2921	<h2><code>dalvik.annotation.InnerClass</code></h2>
				2922	<h4>appears on classes</h4>
				2923
				2924	<p>An <code>InnerClass</code> annotation is attached to each class
				2925	which is defined in the lexical scope of another class's definition.
				2926	Any class which has this annotation must also have <i>either</i> an
				2927	<code>EnclosingClass</code> annotation <i>or</i> an
				2928	<code>EnclosingMethod</code> annotation.</p>
				2929
				2930	<table class="format">
				2931	<thead>
				2932	<tr>
				2933	<th>Name</th>
				2934	<th>Format</th>
				2935	<th>Description</th>
				2936	</tr>
				2937	</thead>
				2938	<tbody>
				2939	<tr>
				2940	<td>name</td>
				2941	<td>String</td>
				2942	<td>the originally declared simple name of this class (not including any
				2943	package prefix). If this class is anonymous, then the name is
				2944	<code>null</code>.
				2945	</td>
				2946	</tr>
				2947	<tr>
				2948	<td>accessFlags</td>
				2949	<td>int</td>
				2950	<td>the originally declared access flags of the class (which may differ
				2951	from the effective flags because of a mismatch between the execution
				2952	models of the source language and target virtual machine)
				2953	</td>
				2954	</tr>
				2955	</tbody>
				2956	</table>
				2957
				2958	<h2><code>dalvik.annotation.MemberClasses</code></h2>
				2959	<h4>appears on classes</h4>
				2960
				2961	<p>A <code>MemberClasses</code> annotation is attached to each class
				2962	which declares member classes. (A member class is a direct inner class
				2963	that has a name.)</p>
				2964
				2965	<table class="format">
				2966	<thead>
				2967	<tr>
				2968	<th>Name</th>
				2969	<th>Format</th>
				2970	<th>Description</th>
				2971	</tr>
				2972	</thead>
				2973	<tbody>
				2974	<tr>
				2975	<td>value</td>
				2976	<td>Class[]</td>
				2977	<td>array of the member classes</td>
				2978	</tr>
				2979	</tbody>
				2980	</table>
				2981
				2982	<h2><code>dalvik.annotation.Signature</code></h2>
				2983	<h4>appears on classes, fields, and methods</h4>
				2984
				2985	<p>A <code>Signature</code> annotation is attached to each class,
				2986	field, or method which is defined in terms of a more complicated type
				2987	than is representable by a <code>type_id_item</code>. The
				2988	<code>.dex</code> format does not define the format for signatures; it
				2989	is merely meant to be able to represent whatever signatures a source
				2990	language requires for successful implementation of that language's
				2991	semantics. As such, signatures are not generally parsed (or verified)
				2992	by virtual machine implementations. The signatures simply get handed
				2993	off to higher-level APIs and tools (such as debuggers). Any use of a
				2994	signature, therefore, should be written so as not to make any
				2995	assumptions about only receiving valid signatures, explicitly guarding
				2996	itself against the possibility of coming across a syntactically
				2997	invalid signature.</p>
				2998
				2999	<p>Because signature strings tend to have a lot of duplicated content,
				3000	a <code>Signature</code> annotation is defined as an <i>array</i> of
				3001	strings, where duplicated elements naturally refer to the same
				3002	underlying data, and the signature is taken to be the concatenation of
				3003	all the strings in the array. There are no rules about how to pull
				3004	apart a signature into separate strings; that is entirely up to the
				3005	tools that generate <code>.dex</code> files.</p>
				3006
				3007	<table class="format">
				3008	<thead>
				3009	<tr>
				3010	<th>Name</th>
				3011	<th>Format</th>
				3012	<th>Description</th>
				3013	</tr>
				3014	</thead>
				3015	<tbody>
				3016	<tr>
				3017	<td>value</td>
				3018	<td>String[]</td>
				3019	<td>the signature of this class or member, as an array of strings that
				3020	is to be concatenated together</td>
				3021	</tr>
				3022	</tbody>
				3023	</table>
				3024
				3025	<h2><code>dalvik.annotation.Throws</code></h2>
				3026	<h4>appears on methods</h4>
				3027
				3028	<p>A <code>Throws</code> annotation is attached to each method which is
				3029	declared to throw one or more exception types.</p>
				3030
				3031	<table class="format">
				3032	<thead>
				3033	<tr>
				3034	<th>Name</th>
				3035	<th>Format</th>
				3036	<th>Description</th>
				3037	</tr>
				3038	</thead>
				3039	<tbody>
				3040	<tr>
				3041	<td>value</td>
				3042	<td>Class[]</td>
				3043	<td>the array of exception types thrown</td>
				3044	</tr>
				3045	</tbody>
				3046	</table>
				3047
				3048	</body>
				3049	</html>