Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" |
| 2 | "http://www.w3.org/TR/html4/strict.dtd"> |
| 3 | <html> |
| 4 | <head> |
| 5 | <title>LLVM Bytecode File Format</title> |
| 6 | <link rel="stylesheet" href="llvm.css" type="text/css"> |
Reid Spencer | 6f1d699 | 2004-05-23 17:12:45 +0000 | [diff] [blame] | 7 | <style type="css"> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 8 | table, tr, td { border: 2px solid gray } |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 9 | th { border: 2px solid gray; font-weight: bold; } |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 10 | table { border-collapse: collapse; margin-top: 1em margin-bottom: 1em } |
| 11 | </style> |
| 12 | </head> |
| 13 | <body> |
| 14 | <div class="doc_title"> LLVM Bytecode File Format </div> |
| 15 | <ol> |
| 16 | <li><a href="#abstract">Abstract</a></li> |
Reid Spencer | 6f1d699 | 2004-05-23 17:12:45 +0000 | [diff] [blame] | 17 | <li><a href="#general">General Concepts</a> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 18 | <ol> |
| 19 | <li><a href="#blocks">Blocks</a></li> |
| 20 | <li><a href="#lists">Lists</a></li> |
| 21 | <li><a href="#fields">Fields</a></li> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 22 | <li><a href="#encoding">Encoding Rules</a></li> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 23 | <li><a href="#align">Alignment</a></li> |
| 24 | </ol> |
Reid Spencer | 6f1d699 | 2004-05-23 17:12:45 +0000 | [diff] [blame] | 25 | </li> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 26 | <li><a href="#details">Detailed Layout</a> |
| 27 | <ol> |
| 28 | <li><a href="#notation">Notation</a></li> |
| 29 | <li><a href="#blocktypes">Blocks Types</a></li> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 30 | <li><a href="#signature">Signature Block</a></li> |
| 31 | <li><a href="#module">Module Block</a></li> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 32 | <li><a href="#typeool">Global Type Pool</a></li> |
| 33 | <li><a href="#modinfo">Module Info Block</a></li> |
| 34 | <li><a href="#constants">Global Constant Pool</a></li> |
Chris Lattner | 2ca1fd1 | 2004-05-24 04:55:32 +0000 | [diff] [blame] | 35 | <li><a href="#functions">Function Blocks</a></li> |
| 36 | <li><a href="#symtab">Module Symbol Table</a></li> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 37 | </ol> |
| 38 | </li> |
| 39 | </ol> |
| 40 | <div class="doc_text"> |
| 41 | <p><b>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a> |
| 42 | and <a href="mailto:sabre@nondot.org">Chris Lattner</a></b></p> |
| 43 | <p> </p> |
| 44 | </div> |
| 45 | <!-- *********************************************************************** --> |
| 46 | <div class="doc_section"> <a name="abstract">Abstract </a></div> |
| 47 | <!-- *********************************************************************** --> |
| 48 | <div class="doc_text"> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 49 | <p>This document describes the LLVM bytecode |
| 50 | file format. It specifies the binary encoding rules of the bytecode file format |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 51 | so that equivalent systems can encode bytecode files correctly. The LLVM |
| 52 | bytecode representation is used to store the intermediate representation on |
| 53 | disk in compacted form. |
| 54 | </p> |
| 55 | </div> |
| 56 | <!-- *********************************************************************** --> |
| 57 | <div class="doc_section"> <a name="general">General Concepts</a> </div> |
| 58 | <!-- *********************************************************************** --> |
| 59 | <div class="doc_text"> |
| 60 | <p>This section describes the general concepts of the bytecode file format |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 61 | without getting into bit and byte level specifics. Note that the LLVM bytecode |
| 62 | format may change in the future, but will always be backwards compatible with |
| 63 | older formats. This document only describes the most current version of the |
| 64 | bytecode format.</p> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 65 | </div> |
| 66 | <!-- _______________________________________________________________________ --> |
| 67 | <div class="doc_subsection"><a name="blocks">Blocks</a> </div> |
| 68 | <div class="doc_text"> |
| 69 | <p>LLVM bytecode files consist simply of a sequence of blocks of bytes. |
| 70 | Each block begins with an identification value that determines the type of |
| 71 | the next block. The possible types of blocks are described below in the section |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 72 | <a href="#blocktypes">Block Types</a>. The block identifier is used because |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 73 | it is possible for entire blocks to be omitted from the file if they are |
| 74 | empty. The block identifier helps the reader determine which kind of block is |
| 75 | next in the file.</p> |
Reid Spencer | 939290f | 2004-05-22 05:56:41 +0000 | [diff] [blame] | 76 | <p>The following block identifiers are currently in use |
| 77 | (from llvm/Bytecode/Format.h):</p> |
| 78 | <ol> |
| 79 | <li><b>Module (0x01)</b>.</li> |
| 80 | <li><b>Function (0x11)</b>.</li> |
| 81 | <li><b>ConstantPool (0x12)</b>.</li> |
| 82 | <li><b>SymbolTable (0x13)</b>.</li> |
| 83 | <li><b>ModuleGlobalInfo (0x14)</b>.</li> |
| 84 | <li><b>GlobalTypePlane (0x15)</b>.</li> |
| 85 | <li><b>BasicBlock (0x31)</b>.</li> |
| 86 | <li><b>InstructionList (0x32)</b>.</li> |
| 87 | <li><b>CompactionTable (0x33)</b>.</li> |
| 88 | </ol> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 89 | <p> All blocks are variable length, and the block header specifies the size of |
| 90 | the block. All blocks are rounded aligned to even 32-bit boundaries, so they |
| 91 | always start and end of this boundary. Each block begins with an integer |
| 92 | identifier and the length of the block, which does not include the padding |
| 93 | bytes needed for alignment.</p> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 94 | </div> |
| 95 | <!-- _______________________________________________________________________ --> |
| 96 | <div class="doc_subsection"><a name="lists">Lists</a> </div> |
| 97 | <div class="doc_text"> |
| 98 | <p>Most blocks are constructed of lists of information. Lists can be constructed |
| 99 | of other lists, etc. This decomposition of information follows the containment |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 100 | hierarchy of the LLVM Intermediate Representation. For example, a function |
| 101 | contains a list of instructions (the terminator instructions implicitly define |
| 102 | the end of the basic blocks).</p> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 103 | <p>A list is encoded into the file simply by encoding the number of entries as |
| 104 | an integer followed by each of the entries. The reader knows when the list is |
| 105 | done because it will have filled the list with the required numbe of entries. |
| 106 | </p> |
| 107 | </div> |
| 108 | <!-- _______________________________________________________________________ --> |
| 109 | <div class="doc_subsection"><a name="fields">Fields</a> </div> |
| 110 | <div class="doc_text"> |
| 111 | <p>Fields are units of information that LLVM knows how to write atomically. |
| 112 | Most fields have a uniform length or some kind of length indication built into |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 113 | their encoding. For example, a constant string (array of bytes) is |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 114 | written simply as the length followed by the characters. Although this is |
| 115 | similar to a list, constant strings are treated atomically and are thus |
| 116 | fields.</p> |
| 117 | <p>Fields use a condensed bit format specific to the type of information |
| 118 | they must contain. As few bits as possible are written for each field. The |
| 119 | sections that follow will provide the details on how these fields are |
| 120 | written and how the bits are to be interpreted.</p> |
| 121 | </div> |
| 122 | <!-- _______________________________________________________________________ --> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 123 | <div class="doc_subsection"><a name="encoding">Encoding Primitives</a> </div> |
| 124 | <div class="doc_text"> |
| 125 | <p>Each field that can be put out is encoded into the file using a small set |
| 126 | of primitives. The rules for these primitives are described below.</p> |
| 127 | <h3>Variable Bit Rate Encoding</h3> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 128 | <p>Most of the values written to LLVM bytecode files are small integers. To |
| 129 | minimize the number of bytes written for these quantities, an encoding |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 130 | scheme similar to UTF-8 is used to write integer data. The scheme is known as |
| 131 | variable bit rate (vbr) encoding. In this encoding, the high bit of each |
| 132 | byte is used to indicate if more bytes follow. If (byte & 0x80) is non-zero |
| 133 | in any given byte, it means there is another byte immediately following that |
| 134 | also contributes to the value. For the final byte (byte & 0x80) is false |
| 135 | (the high bit is not set). In each byte only the low seven bits contribute to |
| 136 | the value. Consequently 32-bit quantities can take from one to <em>five</em> |
| 137 | bytes to encode. In general, smaller quantities will encode in fewer bytes, |
| 138 | as follows:</p> |
| 139 | <table class="doc_table_nw"> |
| 140 | <tr> |
| 141 | <th>Byte #</th> |
| 142 | <th>Significant Bits</th> |
| 143 | <th>Maximum Value</th> |
| 144 | </tr> |
| 145 | <tr><td>1</td><td>0-6</td><td>127</td></tr> |
| 146 | <tr><td>2</td><td>7-13</td><td>16,383</td></tr> |
| 147 | <tr><td>3</td><td>14-20</td><td>2,097,151</td></tr> |
| 148 | <tr><td>4</td><td>21-27</td><td>268,435,455</td></tr> |
| 149 | <tr><td>5</td><td>28-34</td><td>34,359,738,367</td></tr> |
| 150 | <tr><td>6</td><td>35-41</td><td>4,398,046,511,103</td></tr> |
| 151 | <tr><td>7</td><td>42-48</td><td>562,949,953,421,311</td></tr> |
| 152 | <tr><td>8</td><td>49-55</td><td>72,057,594,037,927,935</td></tr> |
| 153 | <tr><td>9</td><td>56-62</td><td>9,223,372,036,854,775,807</td></tr> |
| 154 | <tr><td>10</td><td>63-69</td><td>1,180,591,620,717,411,303,423</td></tr> |
| 155 | </table> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 156 | <p>Note that in practice, the tenth byte could only encode bit 63 |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 157 | since the maximum quantity to use this encoding is a 64-bit integer.</p> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 158 | |
| 159 | <p><em>Signed</em> VBR values are encoded with the standard vbr encoding, but |
| 160 | with the sign bit as the low order bit instead of the high order bit. This |
| 161 | allows small negative quantities to be encoded efficiently. For example, -3 |
| 162 | is encoded as "((3 << 1) | 1)" and 3 is encoded as "(3 << 1) | |
| 163 | 0)", emitted with the standard vbr encoding above.</p> |
| 164 | |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 165 | <p>The table below defines the encoding rules for type names used in the |
| 166 | descriptions of blocks and fields in the next section. Any type name with |
| 167 | the suffix <em>_vbr</em> indicate a quantity that is encoded using |
| 168 | variable bit rate encoding as described above.</p> |
| 169 | <table class="doc_table" > |
| 170 | <tr> |
| 171 | <th><b>Type</b></th> |
| 172 | <th align="left"><b>Rule</b></th> |
| 173 | </tr> |
| 174 | <tr> |
| 175 | <td>unsigned</td> |
| 176 | <td align="left">A 32-bit unsigned integer that always occupies four |
| 177 | consecutive bytes. The unsigned integer is encoded using LSB first |
| 178 | ordering. That is bits 2<sup>0</sup> through 2<sup>7</sup> are in the |
| 179 | byte with the lowest file offset (little endian).</td> |
| 180 | </tr><tr> |
| 181 | <td>uint_vbr</td> |
| 182 | <td align="left">A 32-bit unsigned integer that occupies from one to five |
| 183 | bytes using variable bit rate encoding.</td> |
| 184 | </tr><tr> |
| 185 | <td>uint64_vbr</td> |
| 186 | <td align="left">A 64-bit unsigned integer that occupies from one to ten |
| 187 | bytes using variable bit rate encoding.</td> |
| 188 | </tr><tr> |
| 189 | <td>int64_vbr</td> |
| 190 | <td align="left">A 64-bit signed integer that occupies from one to ten |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 191 | bytes using the signed variable bit rate encoding.</td> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 192 | </tr><tr> |
| 193 | <td>char</td> |
| 194 | <td align="left">A single unsigned character encoded into one byte</td> |
| 195 | </tr><tr> |
| 196 | <td>bit</td> |
| 197 | <td align="left">A single bit within a byte.</td> |
| 198 | </tr><tr> |
| 199 | <td>string</td> |
| 200 | <td align="left">A uint_vbr indicating the length of the character string |
| 201 | immediately followed by the characters of the string. There is no |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 202 | terminating null byte in the string.</td> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 203 | </tr><tr> |
| 204 | <td>data</td> |
| 205 | <td align="left">An arbitrarily long segment of data to which no |
| 206 | interpretation is implied. This is used for float, double, and constant |
| 207 | initializers.</td> |
| 208 | </tr> |
| 209 | </table> |
| 210 | </div> |
| 211 | <!-- _______________________________________________________________________ --> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 212 | <div class="doc_subsection"><a name="align">Alignment</a> </div> |
| 213 | <div class="doc_text"> |
| 214 | <p>To support cross-platform differences, the bytecode file is aligned on |
| 215 | certain boundaries. This means that a small amount of padding (at most 3 bytes) |
| 216 | will be added to ensure that the next entry is aligned to a 32-bit boundary. |
| 217 | </p> |
| 218 | </div> |
| 219 | <!-- *********************************************************************** --> |
| 220 | <div class="doc_section"> <a name="details">Detailed Layout</a> </div> |
| 221 | <!-- *********************************************************************** --> |
| 222 | <div class="doc_text"> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 223 | <p>This section provides the detailed layout of the LLVM bytecode file format. |
| 224 | bit and byte level specifics.</p> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 225 | </div> |
| 226 | <!-- _______________________________________________________________________ --> |
| 227 | <div class="doc_subsection"><a name="notation">Notation</a></div> |
| 228 | <div class="doc_text"> |
| 229 | <p>The descriptions of the bytecode format that follow describe the bit |
| 230 | fields in detail. These descriptions are provided in tabular form. Each table |
| 231 | has four columns that specify:</p> |
| 232 | <ol> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 233 | <li><b>Byte(s)</b>: The offset in bytes of the field from the start of |
Reid Spencer | 6f1d699 | 2004-05-23 17:12:45 +0000 | [diff] [blame] | 234 | its container (block, list, other field).</li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 235 | <li><b>Bit(s)</b>: The offset in bits of the field from the start of |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 236 | the byte field. Bits are always little endian. That is, bit addresses with |
Reid Spencer | 6f1d699 | 2004-05-23 17:12:45 +0000 | [diff] [blame] | 237 | smaller values have smaller address (i.e. 2<sup>0</sup> is at bit 0, |
| 238 | 2<sup>1</sup> at 1, etc.) |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 239 | </li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 240 | <li><b>Align?</b>: Indicates if this field is aligned to 32 bits or not. |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 241 | This indicates where the <em>next</em> field starts, always on a 32 bit |
| 242 | boundary.</li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 243 | <li><b>Type</b>: The basic type of information contained in the field.</li> |
| 244 | <li><b>Description</b>: Describes the contents of the field.</li> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 245 | </ol> |
| 246 | </div> |
| 247 | <!-- _______________________________________________________________________ --> |
| 248 | <div class="doc_subsection"><a name="blocktypes">Block Types</a></div> |
| 249 | <div class="doc_text"> |
| 250 | <p>The bytecode format encodes the intermediate representation into groups |
| 251 | of bytes known as blocks. The blocks are written sequentially to the file in |
| 252 | the following order:</p> |
| 253 | <ol> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 254 | <li><a href="#signature">Signature</a>: This contains the file signature |
| 255 | (magic number) that identifies the file as LLVM bytecode and the bytecode |
| 256 | version number.</li> |
| 257 | <li><a href="#module">Module Block</a>: This is the top level block in a |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 258 | bytecode file. It contains all the other blocks.</li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 259 | <li><a href="#gtypepool">Global Type Pool</a>: This block contains all the |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 260 | global (module) level types.</li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 261 | <li><a href="#modinfo">Module Info</a>: This block contains the types of the |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 262 | global variables and functions in the module as well as the constant |
| 263 | initializers for the global variables</li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 264 | <li><a href="#constants">Constants</a>: This block contains all the global |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 265 | constants except function arguments, global values and constant strings.</li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 266 | <li><a href="#functions">Functions</a>: One function block is written for |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 267 | each function in the module. </li> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 268 | <li><a href="$symtab">Symbol Table</a>: The module level symbol table that |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 269 | provides names for the various other entries in the file is the final block |
| 270 | written.</li> |
| 271 | </ol> |
| 272 | </div> |
| 273 | <!-- _______________________________________________________________________ --> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 274 | <div class="doc_subsection"><a name="signature">Signature Block</a> </div> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 275 | <div class="doc_text"> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 276 | <p>The signature occurs in every LLVM bytecode file and is always first. |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 277 | It simply provides a few bytes of data to identify the file as being an LLVM |
| 278 | bytecode file. This block is always four bytes in length and differs from the |
| 279 | other blocks because there is no identifier and no block length at the start |
| 280 | of the block. Essentially, this block is just the "magic number" for the file. |
| 281 | <table class="doc_table_nw" > |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 282 | <tr> |
| 283 | <th><b>Byte(s)</b></th> |
| 284 | <th><b>Bit(s)</b></th> |
| 285 | <th><b>Align?</b></th> |
Reid Spencer | 939290f | 2004-05-22 05:56:41 +0000 | [diff] [blame] | 286 | <th><b>Type</b></th> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 287 | <th align="left"><b>Field Description</b></th> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 288 | </tr><tr> |
| 289 | <td>00</td><td>-</td><td>No</td><td>char</td> |
Reid Spencer | 939290f | 2004-05-22 05:56:41 +0000 | [diff] [blame] | 290 | <td align="left">Constant "l" (0x6C)</td> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 291 | </tr><tr> |
| 292 | <td>01</td><td>-</td><td>No</td><td>char</td> |
Reid Spencer | 939290f | 2004-05-22 05:56:41 +0000 | [diff] [blame] | 293 | <td align="left">Constant "l" (0x6C)</td> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 294 | </tr><tr> |
| 295 | <td>02</td><td>-</td><td>No</td><td>char</td> |
Reid Spencer | 939290f | 2004-05-22 05:56:41 +0000 | [diff] [blame] | 296 | <td align="left">Constant "v" (0x76)</td> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 297 | </tr><tr> |
| 298 | <td>03</td><td>-</td><td>No</td><td>char</td> |
Reid Spencer | 939290f | 2004-05-22 05:56:41 +0000 | [diff] [blame] | 299 | <td align="left">Constant "m" (0x6D)</td> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 300 | </tr> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 301 | </table> |
| 302 | </div> |
| 303 | <!-- _______________________________________________________________________ --> |
| 304 | <div class="doc_subsection"><a name="module">Module Block</a> </div> |
| 305 | <div class="doc_text"> |
| 306 | <p>The module block contains a small pre-amble and all the other blocks in |
| 307 | the file. Of particular note, the bytecode format number is simply a 28-bit |
| 308 | monotonically increase integer that identifiers the version of the bytecode |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 309 | format (which is not directly related to the LLVM release number). The |
| 310 | bytecode versions defined so far are (note that this document only describes |
| 311 | the latest version): </p> |
| 312 | |
| 313 | <ul> |
| 314 | <li>#0: LLVM 1.0 & 1.1</li> |
| 315 | <li>#1: LLVM 1.2</li> |
| 316 | <li>#2: LLVM 1.3</li> |
| 317 | </ul> |
| 318 | |
| 319 | <p>The table below shows the format of the module block header. It is defined |
| 320 | by blocks described in other sections.</p> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 321 | <table class="doc_table_nw" > |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 322 | <tr> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 323 | <th><b>Byte(s)</b></th> |
| 324 | <th><b>Bit(s)</b></th> |
| 325 | <th><b>Align?</b></th> |
| 326 | <th><b>Type</b></th> |
| 327 | <th align="left"><b>Field Description</b></th> |
| 328 | </tr><tr> |
| 329 | <td>04-07</td><td>-</td><td>No</td><td>unsigned</td> |
| 330 | <td align="left">Module Identifier (0x01)</td> |
| 331 | </tr><tr> |
| 332 | <td>08-11</td><td>-</td><td>No</td><td>unsigned</td> |
| 333 | <td align="left">Size of the module block in bytes</td> |
| 334 | </tr><tr> |
| 335 | <td>12-15</td><td>00</td><td>Yes</td><td>uint32_vbr</td> |
| 336 | <td align="left">Format Information</td> |
| 337 | </tr><tr> |
| 338 | <td>''</td><td>0</td><td>-</td><td>bit</td> |
| 339 | <td align="left">Big Endian?</td> |
| 340 | </tr><tr> |
| 341 | <td>''</td><td>1</td><td>-</td><td>bit</td> |
| 342 | <td align="left">Pointers Are 64-bit?</td> |
| 343 | </tr><tr> |
| 344 | <td>''</td><td>2</td><td>-</td><td>bit</td> |
| 345 | <td align="left">Has No Endianess?</td> |
| 346 | </tr><tr> |
| 347 | <td>''</td><td>3</td><td>-</td><td>bit</td> |
| 348 | <td align="left">Has No Pointer Size?</td> |
| 349 | </tr><tr> |
| 350 | <td>''</td><td>4-31</td><td>-</td><td>bit</td> |
| 351 | <td align="left">Bytecode Format Version</td> |
| 352 | </tr><tr> |
| 353 | <td>16-end</td><td>-</td><td>-</td><td>blocks</td> |
| 354 | <td align="left">The remaining bytes in the block consist |
| 355 | solely of other block types in sequence.</td> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 356 | </tr> |
| 357 | </table> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 358 | |
| 359 | <p>Note that we plan to eventually expand the target description capabilities |
| 360 | of bytecode files to <a href="http://llvm.cs.uiuc.edu/PR263">target |
| 361 | triples</a>.</p> |
| 362 | |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 363 | </div> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 364 | |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 365 | <!-- _______________________________________________________________________ --> |
| 366 | <div class="doc_subsection"><a name="gtypepool">Global Type Pool</a> </div> |
| 367 | <div class="doc_text"> |
Chris Lattner | 2b90565 | 2004-05-24 05:35:17 +0000 | [diff] [blame^] | 368 | <p>The global type pool consists of type definitions. Their order of appearance |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 369 | in the file determines their slot number (0 based). Slot numbers are used to |
| 370 | replace pointers in the intermediate representation. Each slot number uniquely |
| 371 | identifies one entry in a type plane (a collection of values of the same type). |
| 372 | Since all values have types and are associated with the order in which the type |
| 373 | pool is written, the global type pool <em>must</em> be written as the first |
| 374 | block of a module. If it is not, attempts to read the file will fail because |
| 375 | both forward and backward type resolution will not be possible.</p> |
| 376 | <p>The type pool is simply a list of types definitions, as shown in the table |
| 377 | below.</p> |
| 378 | <table class="doc_table_nw" > |
| 379 | <tr> |
| 380 | <th><b>Byte(s)</b></th> |
| 381 | <th><b>Bit(s)</b></th> |
| 382 | <th><b>Align?</b></th> |
| 383 | <th><b>Type</b></th> |
| 384 | <th align="left"><b>Field Description</b></th> |
| 385 | </tr><tr> |
| 386 | <td>00-03</td><td>-</td><td>No</td><td>unsigned</td> |
| 387 | <td align="left">Type Pool Identifier (0x13)</td> |
| 388 | </tr><tr> |
| 389 | <td>04-07</td><td>-</td><td>No</td><td>unsigned</td> |
| 390 | <td align="left">Size in bytes of the symbol table block.</td> |
| 391 | </tr><tr> |
| 392 | <td>08-11<sup>1</sup></td><td>-</td><td>No</td><td>uint32_vbr</td> |
| 393 | <td align="left">Number of entries in type plane</td> |
| 394 | </tr><tr> |
| 395 | <td>12-15<sup>1</sup></td><td>-</td><td>No</td><td>uint32_vbr</td> |
| 396 | <td align="left">Type plane index for following entries</td> |
| 397 | </tr><tr> |
| 398 | <td>16-end<sup>1,2</sup></td><td>-</td><td>No</td><td>type</td> |
| 399 | <td align="left">Each of the type definitions.</td> |
| 400 | </tr><tr> |
| 401 | <td align="left" colspan="5"><sup>1</sup>Maximum length shown, |
| 402 | may be smaller<br><sup>2</sup>Repeated field. |
| 403 | </tr> |
| 404 | </table> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 405 | </div> |
| 406 | <!-- _______________________________________________________________________ --> |
| 407 | <div class="doc_subsection"><a name="modinfo">Module Info</a> </div> |
| 408 | <div class="doc_text"> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 409 | <p>To be determined.</p> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 410 | </div> |
| 411 | <!-- _______________________________________________________________________ --> |
| 412 | <div class="doc_subsection"><a name="constants">Constants</a> </div> |
| 413 | <div class="doc_text"> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 414 | <p>To be determined.</p> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 415 | </div> |
| 416 | <!-- _______________________________________________________________________ --> |
| 417 | <div class="doc_subsection"><a name="functions">Functions</a> </div> |
| 418 | <div class="doc_text"> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 419 | <p>To be determined.</p> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 420 | </div> |
| 421 | <!-- _______________________________________________________________________ --> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 422 | <div class="doc_subsection"><a name="symtab">Symbol Table</a> </div> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 423 | <div class="doc_text"> |
Reid Spencer | b39021b | 2004-05-23 17:05:09 +0000 | [diff] [blame] | 424 | <p>A symbol table can be put out in conjunction with a module or a function. |
| 425 | A symbol table is a list of type planes. Each type plane starts with the number |
| 426 | of entries in the plane and the type plane's slot number (so the type can be |
| 427 | looked up in the global type pool). For each entry in a type plane, the slot |
| 428 | number of the value and the name associated with that value are written. The |
| 429 | format is given in the table below. </p> |
| 430 | <table class="doc_table_nw" > |
| 431 | <tr> |
| 432 | <th><b>Byte(s)</b></th> |
| 433 | <th><b>Bit(s)</b></th> |
| 434 | <th><b>Align?</b></th> |
| 435 | <th><b>Type</b></th> |
| 436 | <th align="left"><b>Field Description</b></th> |
| 437 | </tr><tr> |
| 438 | <td>00-03</td><td>-</td><td>No</td><td>unsigned</td> |
| 439 | <td align="left">Symbol Table Identifier (0x13)</td> |
| 440 | </tr><tr> |
| 441 | <td>04-07</td><td>-</td><td>No</td><td>unsigned</td> |
| 442 | <td align="left">Size in bytes of the symbol table block.</td> |
| 443 | </tr><tr> |
| 444 | <td>08-11<sup>1</sup></td><td>-</td><td>No</td><td>uint32_vbr</td> |
| 445 | <td align="left">Number of entries in type plane</td> |
| 446 | </tr><tr> |
| 447 | <td>12-15<sup>1</sup></td><td>-</td><td>No</td><td>uint32_vbr</td> |
| 448 | <td align="left">Type plane index for following entries</td> |
| 449 | </tr><tr> |
| 450 | <td>16-19<sup>1,2</sup></td><td>-</td><td>No</td><td>uint32_vbr</td> |
| 451 | <td align="left">Slot number of a value.</td> |
| 452 | </tr><tr> |
| 453 | <td>variable<sup>1,2</sup></td><td>-</td><td>No</td><td>string</td> |
| 454 | <td align="left">Name of the value in the symbol table.</td> |
| 455 | </tr> |
| 456 | <tr> |
| 457 | <td align="left" colspan="5"><sup>1</sup>Maximum length shown, |
| 458 | may be smaller<br><sup>2</sup>Repeated field. |
| 459 | </tr> |
| 460 | </table> |
Reid Spencer | 5002661 | 2004-05-22 02:28:36 +0000 | [diff] [blame] | 461 | </div> |
| 462 | |
| 463 | <!-- *********************************************************************** --> |
| 464 | <hr> |
| 465 | <address> |
| 466 | <a href="http://jigsaw.w3.org/css-validator/check/referer"><img |
| 467 | src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a> |
| 468 | <a href="http://validator.w3.org/check/referer"><img |
| 469 | src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a> |
| 470 | |
| 471 | <a href="mailto:rspencer@x10sys.com">Reid Spencer</a> and |
| 472 | <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> |
| 473 | <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br> |
| 474 | Last modified: $Date$ |
| 475 | </address> |
| 476 | </body> |
| 477 | </html> |
| 478 | <!-- vim: sw=2 |
| 479 | --> |