1.. include:: /migration/deprecation.inc 2 3=============================== 4Contents Of PNaCl Bitcode Files 5=============================== 6 7.. contents:: 8 :local: 9 :backlinks: none 10 :depth: 3 11 12 13Introduction 14============ 15 16This document is a reference manual for the contents of PNaCl bitcode files. We 17define bitcode files via three layers. The first layer is presented using 18assembly language *PNaClAsm*, and defines the textual form of the bitcode 19file. The textual form is then lowered to a sequence of :ref:`PNaCl 20records<link_for_pnacl_records>`. The final layer applies abbreviations that 21convert each PNaCl record into a corresponding sequence of bits. 22 23.. image:: /images/PNaClBitcodeFlow.png 24 25PNaClAsm uses a *static single assignment* (SSA) based representation that 26requires generated results to have a single (assignment) source. 27 28PNaClAsm focuses on the semantic content of the file, not the bit-encoding of 29that content. However, it does provide annotations that allow one to specify how 30the :ref:`abbreviations<link_for_abbreviations_section>` are used to convert 31PNaCl records into the sequence of bits. 32 33Each construct in PNaClAsm defines a corresponding :ref:`PNaCl 34record<link_for_pnacl_records>`. A PNaCl bitcode file is simply a sequence of 35PNaCl records. The goal of PNaClAsm is to make records easier to read, and not 36to define a high-level user programming language. 37 38PNaCl records are an abstract encoding of structured data, similar to XML. Like 39XML, A PNaCl record has a notion of a tag (i.e. the first element in a record, 40called a *code*). PNaCl records can be nested. Nesting is defined by a 41corresponding :ref:`enter<link_for_enter_block_record_section>` and 42:ref:`exit<link_for_exit_block_record_section>` block record. 43 44These block records must be used like balanced parentheses to define the block 45structure that is imposed on top of records. Each exit record must be preceded 46by a corresponding enter record. Blocks can be nested by nesting enter/exit 47records appropriately. 48 49The *PNaCl bitcode writer* takes the sequence of records, defined by a PNaClAsm 50program, and converts each record into a (variable-length) sequence of bits. The 51output of each bit sequence is appended together. The resulting generated 52sequence of bits is the contents of the PNaCl bitcode file. 53 54For every kind of record, there is a method for converting records into bit 55sequences. These methods correspond to a notion of 56:ref:`abbreviations<link_for_abbreviations_section>`. Each abbreviation defines 57a specific bit sequence conversion to be applied. 58 59Abbreviations can be user-defined, but there are also predefined defaults. All 60user-specified abbreviations are included in the generated bitcode 61file. Predefined defaults are not. 62 63Each abbreviation defines how a record is converted to a bit sequence. The 64:ref:`PNaCl translator<link_for_pnacl_translator>` uses these abbreviations 65to convert the bit sequence back to the corresponding sequence of PNaCl records. 66As a result, all records have an abbreviation (user or default) associated with 67them. 68 69Conceptually, abbreviations are used to define how to pack the contents of 70records into bit sequences. The main reason for defining abbreviations is to 71save space. The default abbreviations are simplistic and are intended to handle 72all possible records. The default abbreviations do not really worry about being 73efficient, in terms of the number of bits generated. 74 75By separating the concepts of PNaCl records and abbreviations, the notion of 76data compression is cleanly separated from semantic content. This allows 77different use cases to decide how much effort should be spent on compressing 78records. 79 80For a JIT compiler that produces bitcode, little (if any) compression should be 81applied. In fact, the API to the JIT may just be the records themselves. The 82goal of a JIT is to perform the final translation to machine code as quickly as 83possible. 84 85On the other hand, when delivering across the web, one may want to compress the 86sequence of bits considerably, to reduce costs in delivering web pages. Note 87that :ref:`pnacl-compress<pnacl_compress>` is provided as part of the SDK to do 88this job. 89 90Data Model 91========== 92 93The data model for PNaCl bitcode is fixed at little-endian ILP32: pointers are 9432 bits in size. 64-bit integer types are also supported natively via the i64 95type (for example, a front-end can generate these from the C/C++ type ``long 96long``). 97 98Integers are assumed to be modeled using two's complement. Floating point 99support is fixed at :ref:`IEEE 754<c_cpp_floating_point>` 32-bit and 64-bit 100values (float and double, respectively). 101 102PNaCl Blocks 103============ 104 105Blocks are used to organize records in the bitcode file. The kinds of blocks 106defined in PNaClAsm are: 107 108Module block 109 A top-level block defining the program. The :ref:`module 110 block<link_for_module_block>` defines global information used by the program, 111 followed by function blocks defining the implementation of functions within 112 the program. All other blocks (listed below) must appear within a module 113 block. 114 115Types block 116 The :ref:`types block<link_for_types_block_section>` defines the set of types 117 used by the program. All types used in the program must be defined in the 118 types block. These types consist of primitive types as well as high level 119 constructs such as vectors and function signatures. 120 121Globals block 122 The :ref:`globals block<link_for_globals_block_section>` defines the set of 123 addresses of global variables and constants used by the program. It also 124 defines how each global (associated with the global address) is initialized. 125 126Valuesymtab block 127 The :ref:`valuesymtab block<link_for_valuesymtab_block_section>` defines 128 textual names for external function addresses. 129 130Function block 131 Each function (implemented) in a program has its own :ref:`function 132 block<link_for_function_blocks_section>` that defines the implementation of 133 the corresponding function. 134 135Constants block 136 Each implemented function that uses constants in its instructions defines a 137 :ref:`constants block<link_for_constants_block_section>`. Constants blocks 138 appear within the corresponding function block of the implemented function. 139 140Abbreviations block 141 Defines global abbreviations that are used to compress PNaCl records. The 142 :ref:`abbreviations block<link_for_abbreviations_block_section>` is segmented 143 into multiple sections, one section for each kind of block. This block appears 144 at the beginning of the module block. 145 146This section is only intended as a high-level discussion of blocks. Later 147sections will dive more deeply into the constraints on how blocks must be laid 148out. This section only presents the overall concepts of what kinds of data are 149stored in each of the blocks. 150 151A PNaCl program consists of a :ref:`header 152record<link_for_header_record_section>` and a :ref:`module 153block<link_for_module_block>`. The header record defines a sequence of bytes 154uniquely identifying the file as a bitcode file. The module block defines the 155program to run. 156 157Each block, within a bitcode file, defines values. These values are associated 158with IDs. Each type of block defines different kinds of IDs. The 159:ref:`module<link_for_module_block>`, 160:ref:`types<link_for_types_block_section>`, 161:ref:`globals<link_for_globals_block_section>`, and 162:ref:`abbreviations<link_for_abbreviations_block_section>` blocks define global 163identifiers, and only a single instance can appear. The 164:ref:`function<link_for_function_blocks_section>` and 165:ref:`constant<link_for_constants_block_section>` blocks define local 166identifiers, and can have multiple instances (one for each implemented 167function). 168 169The only records in the module block that define values, are :ref:`function 170address<link_for_function_address_section>` records. Each function address 171record defines a different function address, and the :ref:`type 172signature<link_for_function_type>` associated with that function address. 173 174Each :ref:`function block<link_for_function_blocks_section>` defines the 175implementation of a single function. Each function block defines the 176intermediate representation of the function, consisting of basic blocks and 177instructions. If constants are used within instructions, they are defined in a 178:ref:`constants block<link_for_constants_block_section>`, nested within the 179corresponding function block. 180 181All function blocks are associated with a corresponding function address. This 182association is positional rather than explicit. That is, the Nth function block 183in a module block corresponds to the Nth 184:ref:`defining<link_for_function_address_section>` (rather than declared) 185function address record in the module block. 186 187Hence, within a function block, there is no explicit reference to the function 188address the block defines. For readability, PNaClAsm uses the corresponding 189function signature, associated with the corresponding function address record, 190even though that data does not appear in the corresponding records. 191 192.. _link_for_pnacl_records: 193 194PNaCl Records 195============= 196 197A PNaCl record is a non-empty sequence of unsigned, 64-bit, integers. A record 198is identified by the record *code*, which is the first element in the 199sequence. Record codes are unique within a specific kind of block, but are not 200necessarily unique across different kinds of blocks. The record code acts as the 201variant discriminator (i.e. tag) within a block, to identify what kind of record 202it is. 203 204Record codes that are local to a specific kind of block are small values 205(starting from zero). In an ideal world, they would be a consecutive sequence of 206integers, starting at zero. However, the reality is that PNaCl records evolved 207over time (and actually started as `LLVM records 208<http://llvm.org/docs/BitCodeFormat.html>`_). For backward compatibility, 209obsolete numbers have not been reused, leaving gaps in the actual record code 210values used. 211 212Global record codes are record codes that have the same meaning in multiple 213kinds of blocks. To separate global record codes from local record codes, large 214values are used. Currently there are four :ref:`global record 215codes<link_for_global_record_codes>`. To make these cases clear, and to leave 216ample room for future growth in PNaClAsm, these special records have record 217codes close to the value 2\ :sup:`16`\ . Note: Well-formed PNaCl bitcode files 218do not have record codes >= 2\ :sup:`16`\ . 219 220A PNaCl record is denoted as follows: :: 221 222 a: <v0, v1, ... , vN> 223 224The value ``v0`` is the record code. The remaining values, ``v1`` through 225``vN``, are parameters that fill in additional information needed by the 226construct it represents. All records must have a record code. Hence, empty PNaCl 227records are not allowed. ``a`` is the index to the abbreviation used to convert 228the record to a bit sequence. 229 230While most records (for a given record code) have the same length, it is not 231true of all record codes. Some record codes can have arbitrary length. In 232particular, function type signatures, call instructions, phi instructions, 233switch instructions, and global variable initialization records all have 234variable length. The expected length is predefined and part of the PNaClAsm 235language. See the corresponding construct (associated with the record) to 236determine the expected length. 237 238The *PNaCl bitstream writer*, which converts records to bit sequences, does 239this by writing out the abbreviation index used to encode the record, followed 240by the contents of the record. The details of this are left to the section on 241:ref:`abbreviations<link_for_abbreviations_section>`. However, at the record 242level, one important aspect of this appears in :ref:`block 243enter<link_for_enter_block_record_section>` records. These records must define 244how many bits are required to hold abbreviation indices associated with records 245of that block. 246 247.. _link_for_default_abbreviations: 248 249Default Abbreviations 250===================== 251 252There are 4 predefined (default) abbreviation indices, used as the default 253abbreviations for PNaCl records. They are: 254 2550 256 Abbreviation index for the abbreviation used to bit-encode an exit block 257 record. 258 2591 260 Abbreviation index for the abbreviation used to bit-encode an enter block 261 record. 262 2632 264 Abbreviation index for the abbreviation used to bit-encode a user-defined 265 abbreviation. Note: User-defined abbreviations are also encoded as records, 266 and hence need an abbreviation index to bit-encode them. 267 2683 269 Abbreviation index for the default abbreviation to bit-encode all other 270 records in the bitcode file. 271 272A block may, in addition, define a list of block specific, user-defined, 273abbreviations (of length ``U``). The number of bits ``B`` specified for an enter 274record must be sufficiently large such that:: 275 276 2**B >= U + 4 277 278In addition, the upper limit for ``B`` is ``16``. 279 280PNaClAsm requires specifying the number of bits needed to read abbreviations as 281part of the enter block record. This allows the PNaCl bitcode reader/writer to 282use the specified number of bits to encode abbreviation indices. 283 284PNaCl Identifiers 285================= 286 287A program is defined by a :ref:`module block<link_for_module_block>`. Blocks can 288be nested within other blocks, including the module block. Each block defines a 289sequence of records. 290 291Most of the records, within a block, also define unique values. Each unique 292value is given a corresponding unique identifier (i.e. *ID*). In PNaClAsm, each 293kind of block defines its own kind of identifiers. The names of these 294identifiers are defined by concatenating a prefix character (``'@'`` or 295``'%'``), the kind of block (a single character), and a suffix index. The suffix 296index is defined by the positional location of the defined value within the 297records of the corresponding block. The indices are all zero based, meaning that 298the first defined value (within a block) is defined using index 0. 299 300Identifiers are categorized into two types, *local* and *global*. Local 301identifiers are identifiers that are associated with the implementation of a 302single function. In that sense, they are local to the block they appear in. 303 304All other identifiers are global, and can appear in multiple blocks. This split 305is intentional. Global identifiers are used by multiple functions, and therefore 306must be known in all function implementations. Local identifiers only apply to a 307single function, and can be reused between functions. The :ref:`PNaCl 308translator<link_for_pnacl_translator>` uses this separation to parallelize the 309compilation of functions. 310 311Note that local abbreviation identifiers are unique to the block they appear 312in. Global abbreviation identifiers are only unique to the block type they are 313defined for. Different block types can reuse global abbreviation identifiers. 314 315Global identifiers use the prefix character ``'@'`` while local identifiers use 316the prefix character ``'%'``. 317 318Note that by using positional location to define identifiers (within a block), 319the values defined in PNaCl bitcode files need not be explicitly included in the 320bitcode file. Rather, they are inferred by the (ordered) position of the record 321in the block. This is also intentional. It is used to reduce the amount of data 322that must be (explicitly) passed to the :ref:`PNaCl 323translator<link_for_pnacl_translator>`, when downloaded into Chrome. 324 325In general, most of the records within blocks are assumed to be topologically 326sorted, putting value definitions before their uses. This implies that records 327do not need to encode data if they can deduce the corresponding information from 328their uses. 329 330The most common use of this is that many instructions use the type of their 331operands to determine the type of the instruction. Again, this is 332intentional. It allows less information to be stored. 333 334However, for function blocks (which define instructions), a topological sort may 335not exist. Loop carried value dependencies simply do not allow topologically 336sorting. To deal with this, function blocks have a notion of (instruction value) 337:ref:`forward type 338declarations<link_for_forward_type_declaration_section>`. These declarations 339must appear before any of the uses of that value, if the (instruction) value is 340defined later in the function than its first use. 341 342The kinds of identifiers used in PNaClAsm are: 343 344@a 345 Global abbreviation identifier. 346 347%a 348 Local abbreviation identifier. 349 350%b 351 Function basic block identifier. 352 353%c 354 Function constant identifier. 355 356@f 357 Global function address identifier. 358 359@g 360 Global variable/constant address identifier. 361 362%p 363 Function parameter identifier. 364 365@t 366 Global type identifier. 367 368%v 369 Value generated by an instruction in a function block. 370 371 372Conventions For Describing Records 373================================== 374 375PNaClAsm is the textual representation of :ref:`PNaCl 376records<link_for_pnacl_records>`. Each PNaCl record is described by a 377corresponding PNaClAsm construct. These constructs are described using syntax 378rules, and semantics on how they are converted to records. Along with the rules, 379is a notion of :ref:`global state<link_for_global_state_section>`. The global 380state is updated by syntax rules. The purpose of the global state is to track 381positional dependencies between records. 382 383For each PNaCl construct, we define multiple sections. The **Syntax** 384section defines a syntax rule for the construct. The **Record** section 385defines the corresponding record associated with the syntax rule. The 386**Semantics** section describes the semantics associated with the record, in 387terms of data within the global state and the corresponding syntax. It also 388includes other high-level semantics, when appropriate. 389 390The **Constraints** section (if present) defines any constraints associated 391with the construct, including the global state. The **Updates** section (if 392present) defines how the global state is updated when the construct is 393processed. The **Examples** section gives one or more examples of using the 394corresponding PNaClAsm construct. 395 396Some semantics sections use functions to compute values. The meaning of 397functions can be found in :ref:`support 398functions<link_for_support_functions_section>`. 399 400The syntax rule may include the 401:ref:`abbreviation<link_for_abbreviations_section>` to use, when converting to a 402bit-sequence. These abbreviations, if allowed, are at the end of the construct, 403and enclosed in ``<`` and ``>`` brackets. These abbreviations are optional in 404the syntax, and can be omitted. If they are used, the abbreviation brackets are 405part of the actual syntax of the construct. If the abbreviation is omitted, the 406default abbreviation index is used. To make it clear that abbreviations are 407optional, syntax rules separate abbreviations using plenty of whitespace. 408 409Within a syntax rule, lower case characters are literal values. Sequences of 410upper case alphanumeric characters are named values. If we mix lower and upper 411case letters within a name appearing in a syntax rule, the lower case letters 412are literal while the upper case sequence of alphanumeric characters denote rule 413specific values. The valid values for each of these names will be defined in 414the corresponding semantics and constraints subsections. 415 416For example, consider the following syntax rule:: 417 418 %vN = add T O1, O2; <A> 419 420This rule defines a PNaClAsm add instruction. This construct defines an 421instruction that adds two values (``O1`` and ``O2``) to generate instruction 422value ``%vN``. The types of the arguments, and the result, are all of type 423``T``. If abbreviation ID ``A`` is present, the record is encoded using that 424abbreviation. Otherwise the corresponding :ref:`default abbreviation 425index<link_for_default_abbreviations>` is used. 426 427To be concrete, the syntactic rule above defines the structure of the following 428PNaClAsm examples:: 429 430 %v10 = add i32 %v1, %v2; <@a5> 431 %v11 = add i32 %v10, %v3; 432 433In addition to specifying the syntax, each syntax rule can also also specify the 434contents of the corresponding record in the corresponding record subsection. In 435simple cases, the elements of the corresponding record are predefined (literal) 436constants. Otherwise the record element is an identifier from another subsection 437associated with the construct. 438 439Factorial Example 440================= 441 442This section provides a simple example of a PNaCl bitcode file. Its contents 443describe a bitcode file that only defines a function to compute the factorial 444value of a number. 445 446In C, the factorial function can be defined as:: 447 448 int fact(int n) { 449 if (n == 1) return 1; 450 return n * fact(n-1); 451 } 452 453Compiling this into a PNaCl bitcode file, and dumping out its contents with 454utility :ref:`pnacl-bcdis<pnacl-bcdis>`, the corresponding output is:: 455 456 0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69) 457 | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2 458 | 0> | 459 16:0|1: <65535, 8, 2> |module { // BlockID = 8 460 24:0| 3: <1, 1> | version 1; 461 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 462 36:0| 0: <65534> | } 463 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 464 48:0| 3: <1, 4> | count 4; 465 50:4| 3: <7, 32> | @t0 = i32; 466 53:6| 3: <2> | @t1 = void; 467 55:4| 3: <21, 0, 0, 0> | @t2 = i32 (i32); 468 59:4| 3: <7, 1> | @t3 = i1; 469 62:0| 0: <65534> | } 470 64:0| 3: <8, 2, 0, 0, 0> | define external i32 @f0(i32); 471 68:6| 1: <65535, 19, 2> | globals { // BlockID = 19 472 76:0| 3: <5, 0> | count 0; 473 78:4| 0: <65534> | } 474 80:0| 1: <65535, 14, 2> | valuesymtab { // BlockID = 14 475 88:0| 3: <1, 0, 102, 97, 99, | @f0 : "fact"; 476 | 116> | 477 96:4| 0: <65534> | } 478 100:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0) { 479 | | // BlockID = 12 480 108:0| 3: <1, 3> | blocks 3; 481 110:4| 1: <65535, 11, 2> | constants { // BlockID = 11 482 120:0| 3: <1, 0> | i32: 483 122:4| 3: <4, 2> | %c0 = i32 1; 484 125:0| 0: <65534> | } 485 | | %b0: 486 128:0| 3: <28, 2, 1, 32> | %v0 = icmp eq i32 %p0, %c0; 487 132:6| 3: <11, 1, 2, 1> | br i1 %v0, label %b1, label %b2; 488 | | %b1: 489 136:6| 3: <10, 2> | ret i32 %c0; 490 | | %b2: 491 139:2| 3: <2, 3, 2, 1> | %v1 = sub i32 %p0, %c0; 492 143:2| 3: <34, 0, 5, 1> | %v2 = call i32 @f0(i32 %v1); 493 148:0| 3: <2, 5, 1, 2> | %v3 = mul i32 %p0, %v2; 494 152:0| 3: <10, 1> | ret i32 %v3; 495 154:4| 0: <65534> | } 496 156:0|0: <65534> |} 497 498Note that there are three columns in this output. The first column contains the 499bit positions of the records within the bitcode file. The second column contains 500the sequence of records within the bitcode file. The third column contains the 501corresponding PNaClAsm program. 502 503Bit positions are defined by a pair ``B:N``. ``B`` is the number of bytes, while 504``N`` is the bit offset within the ``B``-th byte. Hence, the bit position (in 505bits) is:: 506 507 B*8 + N 508 509Hence, the first record is at bit offset ``0`` (``0*8+0``). The second record is 510at bit offset ``128`` (``16*8+0``). The third record is at bit offset ``192`` 511(``24*8+0``). The fourth record is at bit offset ``212`` (``26*8+4``). 512 513The :ref:`header record<link_for_header_record_section>` is a sequence of 16 514bytes, defining the contents of the first 16 bytes of the bitcode file. These 515bytes never change, and are expected for all version 2, PNaCl bitcode files. The 516first four bytes define the magic number of the file, i.e. 'PEXE'. All PEXE 517bitcode files begin with these four bytes. 518 519All but the header record has an abbreviation index associated with it. Since no 520user-defined abbreviations are provided, all records were converted to 521bit sequences using default abbreviations. 522 523The types block (starting at bit address ``40:0``), defines 4 types: ``i1``, 524``i32``, ``void``, and function signature ``i32 (i32)``. 525 526Bit address ``64:0`` declares the factorial function address ``@f0``, and its 527corresponding type signature. Bit address ``88:0`` associates the name ``fact`` 528with function address ``@f0``. 529 530Bit address ``100:0`` defines the function block that implements function 531``fact``. The entry point is ``%b0`` (at bit address ``128:0``). It uses the 53232-bit integer constant ``1`` (defined at bit addresses ``122:4``). Bit address 533``128:0`` defines an equality comparison of the argument ``%p0`` with ``1`` 534(constant ``%c0``). Bit address ``132:6`` defines a conditional branch. If the 535result of the previous comparison (``%v0``) is true, the program will branch to 536block ``%b1``. Otherwise it will branch to block ``%b2``. 537 538Bit address ``136:6`` returns constant ``1`` (``%c0``) when the input parameter 539is 1. Instructions between bit address ``139:2`` and ``154:4`` compute and 540return ``n * fact(n-1)``. 541 542Road Map 543======== 544 545At this point, this document transitions from basic concepts to the details 546of how records should be formatted. This section defines the road map to 547the remaining sections in this document. 548 549Many records have implicit information associated with them, and must be 550maintained across records. :ref:`Global state<link_for_global_state_section>` 551describes how this implicit information is modeled. In addition, there are 552various :ref:`support functions<link_for_support_functions_section>` that are 553used to define the semantics of records, and how they update the global state. 554 555There are just a handful of global records (records that either don't appear in 556any block, or can appear in all blocks). :ref:`Global 557records<link_for_global_record_codes>` describes these records. This includes 558the block delimiter records :ref:`enter<link_for_enter_block_record_section>` 559and :ref:`exit<link_for_exit_block_record_section>` that define block 560boundaries. 561 562PNaClAsm is a strongly typed language, and most block values are typed. 563:ref:`types<link_for_types_block_section>` describes the set of legal types, and 564how to define types. 565 566Global variables and their initializers are presented in the :ref:`globals 567block<link_for_globals_block_section>`. :ref:`Function 568addresses<link_for_function_address_section>` are part of the :ref:`module 569block<link_for_module_block>`, but must be defined before any global variables. 570 571Names to be associated with global variables and function addresses, are defined 572in the :ref:`valuesymtab block<link_for_valuesymtab_block_section>`, and must 573appear after the :ref:`globals block<link_for_globals_block_section>`, but 574before any :ref:`function definition<link_for_function_blocks_section>`. 575 576The :ref:`module block<link_for_module_block>` is the top-most block, and all 577other blocks must appear within the module block. The module block defines the 578executable in the bitcode file. 579 580Constants used within a :ref:`function 581definition<link_for_function_blocks_section>` must be defined using a 582:ref:`constants block<link_for_constants_block_section>`. Each function 583definition is defined by a :ref:`function 584block<link_for_function_blocks_section>` and constant blocks can only appear 585within function blocks. Constants defined within a constant block can only be 586used in the enclosing function block. 587 588Function definitions are defined by a sequence of instructions. There are 589several types of instructions. 590 591A :ref:`terminator instruction<link_for_terminator_instruction_section>` is the 592last instruction in a :ref:`basic block<link_for_function_blocks_section>`, and 593is a branch, return, or unreachable instruction. 594 595There are :ref:`integer<link_for_integer_binary_instructions>` and 596:ref:`floating point<link_for_floating_point_binary_instructions>` binary 597operations. Integer binary instructions include both arithmetic and logical 598operations. Floating point instructions define arithmetic operations. 599 600There are also :ref:`memory 601access<link_for_memory_creation_and_access_instructions>` instructions that 602allow one to load and store values. That section also includes how to define 603local variables using the :ref:`alloca 604instruction<link_for_alloca_instruction>`. 605 606One can also convert integer and floating point values using :ref:`conversion 607instructions<link_for_conversion_instructions>`. 608 609:ref:`Comparison instructions<link_for_compare_instructions>` 610allow you to compare values. 611 612:ref:`Vector instructions<link_for_vector_instructions>` allow you to build and 613update vectors. Corresponding :ref:`intrinsic 614functions<link_for_intrinsic_functions_section>`, as well as 615:ref:`integer<link_for_integer_binary_instructions>` and :ref:`floating 616point<link_for_floating_point_binary_instructions>` binary instructions allow 617you to apply operations to vectors. 618 619In addition, :ref:`other instructions<link_for_other_pnaclasm_instructions>` are 620available. This includes function and procedure calls. 621 622There are also :ref:`memory 623alignment<link_for_memory_blocks_and_alignment_section>` issues that should be 624considered for global and local variables, as well as load and store 625instructions. 626 627Finally, how to pack records is described in the 628:ref:`abbreviations<link_for_abbreviations_section>` section. 629 630.. _link_for_global_state_section: 631 632Global State 633============ 634 635This section describes the global state associated with PNaClAsm. It is used to 636define contextual data that is carried between records. 637 638In particular, PNaClAsm is a strongly typed language, and hence, we must track 639the type associated with values. Subsection :ref:`link_to_typing_functions` 640describes the functions used to maintain typing information associated with 641values. 642 643Values are implicitly ordered within a block, and the indices associated with 644the values do not appear in records. Rather, ID counters are used to figure out 645what corresponding ID name is associated with a value generating record. 646Subsection :ref:`link_to_ID_Counters` defines counters maintained in the global 647state. 648 649In several blocks, one of the first records in the block defines how many values 650are defined in in the block. The main purpose of these counts is to communicate 651to the :ref:`PNaCl translator<link_for_pnacl_translator>` space requirements, or 652a limit so that it can detect bad references to values. Subsection 653:ref:`link_for_Size_Variables` defines variables that hold size definitions in 654the corresponding records. 655 656Finally, the function and constants block contain implicit context between 657records in those blocks. Subsection :ref:`link_to_Other_Variables` defines the 658variables that contain this implicit context. 659 660.. _link_to_typing_functions: 661 662Typing Functions 663---------------- 664 665Associated with most identifiers is a type. This type defines what type the 666corresponding value has. It is defined by the (initially empty) map:: 667 668 TypeOf: ID -> Type 669 670For each type in the :ref:`types block<link_for_types_block_section>`, a 671corresponding inverse map:: 672 673 TypeID: Type -> ID 674 675is maintained to convert syntactic types to the corresponding type ID. 676 677Note: This document assumes that map ``TypeID`` is automatically maintained 678during updates to map ``TypeOf`` (when given a type ``ID``). Hence, *Updates* 679subsections will not contain assignments to this map. 680 681Associated with each function identifier is its :ref:`type 682signature<link_for_function_type>`. This is different than the type of the 683function identifier, since function identifiers represent the function address 684which is a pointer (and pointers are always implemented as a 32-bit integer 685following the ILP32 data model). 686 687Function type signatures are maintained using:: 688 689 TypeOfFcn: ID -> Type 690 691In addition, if a function address has an implementing block, there is a 692corresponding implementation associated with the function address. To indicate 693which function addresses have implementations, we use the set:: 694 695 DefiningFcnIDs: set(ID) 696 697.. _link_to_ID_Counters: 698 699ID Counters 700----------- 701 702Each block defines one or more kinds of values. Value indices are generated 703sequentially, starting at zero. To capture this, the following counters are 704defined: 705 706NumTypes 707 The number of types defined so far (in the :ref:`types 708 block<link_for_types_block_section>`). 709 710NumFuncAddresses 711 The number of function addresses defined so far (in the :ref:`module 712 block<link_for_module_block>`). 713 714NumGlobalAddresses 715 The number of global variable/constant addresses defined so far (in the 716 :ref:`globals block<link_for_globals_block_section>`). 717 718NumParams 719 The number of parameters defined for a function. Note: Unlike other counters, 720 this value is set once, at the beginning of the corresponding :ref:`function 721 block<link_for_function_blocks_section>`, based on the type signature 722 associated with the function. 723 724NumFcnConsts 725 The number of constants defined in a function so far (in the corresponding 726 nested :ref:`constants block<link_for_constants_block_section>`). 727 728NumBasicBlocks 729 The number of basic blocks defined so far (within a :ref:`function 730 block<link_for_function_blocks_section>`). 731 732NumValuedInsts 733 The number of instructions, generating values, defined so far (within a 734 :ref:`function block<link_for_function_blocks_section>`). 735 736.. _link_for_Size_Variables: 737 738Size Variables 739-------------- 740 741A number of blocks define expected sizes of constructs. These sizes are recorded 742in the following size variables: 743 744ExpectedBasicBlocks 745 The expected :ref:`number of basic blocks<link_for_basic_blocks_count>` within 746 a function implementation. 747 748ExpectedTypes 749 The expected :ref:`number of types<link_for_types_count_record>` defined in 750 the types block. 751 752ExpectedGlobals 753 The expected :ref:`number of global variable/constant 754 addresses<link_for_globals_count_record>` in the globals block. 755 756ExpectedInitializers 757 The expected :ref:`number of initializers<link_for_compound_initializer>` for 758 a global variable/constant address in the globals block. 759 760It is assumed that the corresponding :ref:`ID counters<link_to_ID_counters>` are 761always smaller than the corresponding size variables (except 762ExpectedInitializers). That is:: 763 764 NumBasicBlocks < ExpectedBasicBlocks 765 NumTypes < ExpectedTypes 766 NumGlobalAddresses < ExpectedGlobals 767 768.. _link_to_Other_Variables: 769 770Other Variables 771--------------- 772 773EnclosingFcnID 774 The function ID of the function block being processed. 775 776ConstantsSetType 777 Holds the type associated with the last :ref:`set type 778 record<link_for_constants_set_type_record>` in the constants block. Note: at 779 the beginning of each constants block, this variable is set to type void. 780 781.. _link_for_global_record_codes: 782 783Global Records 784============== 785 786Global records are records that can appear in any block. These records have 787the same meaning in multiple kinds of blocks. 788 789There are four global PNaCl records, each having its own record code. These 790global records are: 791 792Header 793 The :ref:`header record<link_for_header_record_section>` is the first record 794 of a PNaCl bitcode file, and identifies the file's magic number, as well as 795 the bitcode version it uses. The record defines the sequence of bytes that 796 make up the header and uniquely identifies the file as a PNaCl bitcode file. 797 798Enter 799 An :ref:`enter record<link_for_enter_block_record_section>` defines the 800 beginning of a block. Since blocks can be nested, one can appear inside other 801 blocks, as well as at the top level. 802 803Exit 804 An :ref:`exit record<link_for_exit_block_record_section>` defines the end of a 805 block. Hence, it must appear in every block, to end the block. 806 807Abbreviation 808 An :ref:`abbreviation record<link_for_abbreviation_record>` defines a 809 user-defined abbreviation to be applied to records within blocks. 810 Abbreviation records appearing in the abbreviations block define global 811 abbreviations. All other abbreviations are local to the block they appear in, 812 and can only be used in that block. 813 814All global records can't have user-defined abbreviations associated with 815them. The :ref:`default abbreviation<link_for_default_abbreviations>` is always 816used. 817 818.. _link_for_header_record_section: 819 820Header Record 821------------- 822 823The header record must be the first record in the file. It is the only record in 824the bitcode file that doesn't have a corresponding construct in PNaClAsm. In 825addition, no abbreviation index is associated with it. 826 827**Syntax**: 828 829There is no syntax for header records in PNaClAsm. 830 831**Record**:: 832 833 <65532, 80, 69, 88, 69, 1, 0, 8, 0, 17, 0, 4, 0, 2, 0, 0, 0> 834 835**Semantics**: 836 837The header record defines the initial sequence of bytes that must appear at the 838beginning of all (PNaCl bitcode version 2) files. That sequence is the list of 839bytes inside the record (excluding the record code). As such, it uniquely 840identifies all PNaCl bitcode files. 841 842**Examples**:: 843 844 0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69) 845 | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2 846 | 0> | 847 848.. _link_for_enter_block_record_section: 849 850Enter Block Record 851------------------ 852 853Block records can be top-level, as well as nested in other blocks. Blocks must 854begin with an *enter* record, and end with an 855:ref:`exit<link_for_exit_block_record_section>` record. 856 857**Syntax**:: 858 859 N { <B> 860 861**Record**:: 862 863 1: <65535, ID, B> 864 865**Semantics**: 866 867Enter block records define the beginning of a block. ``B``, if present, is the 868number of bits needed to represent all possible abbreviation indices used within 869the block. If omitted, ``B=2`` is assumed. 870 871The block ``ID`` value is dependent on the name ``N``. Valid names and 872corresponding ``BlockID`` values are defined as follows: 873 874============= ======== 875N Block ID 876============= ======== 877abbreviations 0 878constants 11 879function 12 880globals 19 881module 8 882types 17 883valuesymtab 14 884============= ======== 885 886Note: For readability, PNaClAsm defines a more readable form of a function block 887enter record. See :ref:`function blocks<link_for_function_blocks_section>` for 888more details. 889 890**Examples**:: 891 892 16:0|1: <65535, 8, 2> |module { // BlockID = 8 893 24:0| 3: <1, 1> | version 1; 894 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 895 36:0| 0: <65534> | } 896 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 897 48:0| 3: <1, 2> | count 2; 898 50:4| 3: <2> | @t0 = void; 899 52:2| 3: <21, 0, 0> | @t1 = void (); 900 55:4| 0: <65534> | } 901 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); 902 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 903 68:0| 3: <5, 0> | count 0; 904 70:4| 0: <65534> | } 905 72:0|0: <65534> |} 906 907.. _link_for_exit_block_record_section: 908 909Exit Block Record 910----------------- 911 912Block records can be top-level, as well as nested, records. Blocks must begin 913with an :ref:`enter<link_for_enter_block_record_section>` record, and end with 914an *exit* record. 915 916**Syntax**:: 917 918 } 919 920**Record**:: 921 922 0: <65534> 923 924**Semantics**: 925 926All exit records are identical, no matter what block they are ending. An exit 927record defines the end of the block. 928 929**Examples**:: 930 931 16:0|1: <65535, 8, 2> |module { // BlockID = 8 932 24:0| 3: <1, 1> | version 1; 933 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 934 36:0| 0: <65534> | } 935 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 936 48:0| 3: <1, 2> | count 2; 937 50:4| 3: <2> | @t0 = void; 938 52:2| 3: <21, 0, 0> | @t1 = void (); 939 55:4| 0: <65534> | } 940 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); 941 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 942 68:0| 3: <5, 0> | count 0; 943 70:4| 0: <65534> | } 944 72:0|0: <65534> |} 945 946.. _link_for_abbreviation_record: 947 948Abbreviation Record 949------------------- 950 951Abbreviation records define abbreviations. See 952:ref:`abbreviations<link_for_abbreviations_section>` for details on how 953abbreviations should be written. This section only presents the mechanical 954details for converting an abbreviation into a PNaCl record. 955 956**Syntax**:: 957 958 A = abbrev <E1, ... , EM>; 959 960**Record**:: 961 962 2: <65533, M, EE1, ... , EEM> 963 964**Semantics**: 965 966Defines an abbreviation ``A`` as the sequence of encodings ``E1`` through 967``EM``. If the abbreviation appears within the :ref:`abbreviations 968block<link_for_abbreviations_block_section>`, ``A`` must be a global 969abbreviation. Otherwise, ``A`` must be a local abbreviation. 970 971Abbreviations within a block (or a section within the abbreviations block), must 972be enumerated in order, starting at index ``0``. 973 974Valid encodings ``Ei``, and the corresponding sequence of (unsigned) integers 975``EEi``, ( for ``1 <= i <= M``) are defined by the following table: 976 977========= ======= ================================================== 978Ei EEi Form 979========= ======= ================================================== 980C 1, C Literal C in corresponding position in record. 981fixed(N) 0, 1, N Encode value as a fixed sequence of N bits. 982vbr(N) 0, 2, N Encode value using a variable bit rate of N. 983char6 0, 4 Encode value as 6-bit char containing 984 characters [a-zA-Z0-9._]. 985array 0, 3 Allow zero or more of the succeeding abbreviation. 986========= ======= ================================================== 987 988Note that 'array' can only appear as the second to last element in the 989abbreviation. Notationally, ``array(EM)`` is used in place of ``array`` and 990``EM``, the last two entries in an abbreviation. 991 992**Examples**:: 993 994 0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69) 995 | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2 996 | 0> | 997 16:0|1: <65535, 8, 2> |module { // BlockID = 8 998 24:0| 3: <1, 1> | version 1; 999 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 1000 36:0| 1: <1, 14> | valuesymtab: 1001 38:4| 2: <65533, 4, 0, 1, 3, 0,| @a0 = abbrev <fixed(3), vbr(8), 1002 | 2, 8, 0, 3, 0, 1, 8> | array(fixed(8))>; 1003 43:2| 2: <65533, 4, 1, 1, 0, 2,| @a1 = abbrev <1, vbr(8), 1004 | 8, 0, 3, 0, 1, 7> | array(fixed(7))>; 1005 48:0| 2: <65533, 4, 1, 1, 0, 2,| @a2 = abbrev <1, vbr(8), 1006 | 8, 0, 3, 0, 4> | array(char6)>; 1007 52:1| 2: <65533, 4, 1, 2, 0, 2,| @a3 = abbrev <2, vbr(8), 1008 | 8, 0, 3, 0, 4> | array(char6)>; 1009 56:2| 1: <1, 11> | constants: 1010 58:6| 2: <65533, 2, 1, 1, 0, 1,| @a0 = abbrev <1, fixed(2)>; 1011 | 2> | 1012 61:7| 2: <65533, 2, 1, 4, 0, 2,| @a1 = abbrev <4, vbr(8)>; 1013 | 8> | 1014 65:0| 2: <65533, 2, 1, 4, 1, 0>| @a2 = abbrev <4, 0>; 1015 68:1| 2: <65533, 2, 1, 6, 0, 2,| @a3 = abbrev <6, vbr(8)>; 1016 | 8> | 1017 71:2| 1: <1, 12> | function: 1018 73:6| 2: <65533, 4, 1, 20, 0, | @a0 = abbrev <20, vbr(6), vbr(4), 1019 | 2, 6, 0, 2, 4, 0, 2, | vbr(4)>; 1020 | 4> | 1021 79:1| 2: <65533, 4, 1, 2, 0, 2,| @a1 = abbrev <2, vbr(6), vbr(6), 1022 | 6, 0, 2, 6, 0, 1, 4> | fixed(4)>; 1023 84:4| 2: <65533, 4, 1, 3, 0, 2,| @a2 = abbrev <3, vbr(6), 1024 | 6, 0, 1, 2, 0, 1, 4> | fixed(2), fixed(4)>; 1025 89:7| 2: <65533, 1, 1, 10> | @a3 = abbrev <10>; 1026 91:7| 2: <65533, 2, 1, 10, 0, | @a4 = abbrev <10, vbr(6)>; 1027 | 2, 6> | 1028 95:0| 2: <65533, 1, 1, 15> | @a5 = abbrev <15>; 1029 97:0| 2: <65533, 3, 1, 43, 0, | @a6 = abbrev <43, vbr(6), 1030 | 2, 6, 0, 1, 2> | fixed(2)>; 1031 101:2| 2: <65533, 4, 1, 24, 0, | @a7 = abbrev <24, vbr(6), vbr(6), 1032 | 2, 6, 0, 2, 6, 0, 2, | vbr(4)>; 1033 | 4> | 1034 106:5| 1: <1, 19> | globals: 1035 109:1| 2: <65533, 3, 1, 0, 0, 2,| @a0 = abbrev <0, vbr(6), 1036 | 6, 0, 1, 1> | fixed(1)>; 1037 113:3| 2: <65533, 2, 1, 1, 0, 2,| @a1 = abbrev <1, vbr(8)>; 1038 | 8> | 1039 116:4| 2: <65533, 2, 1, 2, 0, 2,| @a2 = abbrev <2, vbr(8)>; 1040 | 8> | 1041 119:5| 2: <65533, 3, 1, 3, 0, 3,| @a3 = abbrev <3, array(fixed(8))> 1042 | 0, 1, 8> | ; 1043 123:2| 2: <65533, 2, 1, 4, 0, 2,| @a4 = abbrev <4, vbr(6)>; 1044 | 6> | 1045 126:3| 2: <65533, 3, 1, 4, 0, 2,| @a5 = abbrev <4, vbr(6), vbr(6)>; 1046 | 6, 0, 2, 6> | 1047 130:5| 0: <65534> | } 1048 132:0| 1: <65535, 17, 3> | types { // BlockID = 17 1049 140:0| 2: <65533, 4, 1, 21, 0, | %a0 = abbrev <21, fixed(1), 1050 | 1, 1, 0, 3, 0, 1, 2> | array(fixed(2))>; 1051 144:7| 3: <1, 3> | count 3; 1052 147:4| 3: <7, 32> | @t0 = i32; 1053 150:7| 4: <21, 0, 0, 0, 0> | @t1 = i32 (i32, i32); <%a0> 1054 152:7| 3: <2> | @t2 = void; 1055 154:6| 0: <65534> | } 1056 156:0| 3: <8, 1, 0, 0, 0> | define external i32 @f0(i32, i32); 1057 160:6| 1: <65535, 19, 4> | globals { // BlockID = 19 1058 168:0| 3: <5, 0> | count 0; 1059 170:6| 0: <65534> | } 1060 172:0| 1: <65535, 14, 3> | valuesymtab { // BlockID = 14 1061 180:0| 6: <1, 0, 102> | @f0 : "f"; <@a2> 1062 182:7| 0: <65534> | } 1063 184:0| 1: <65535, 12, 4> | function i32 @f0(i32 %p0, i32 %p1) { 1064 | | // BlockID = 12 1065 192:0| 3: <1, 1> | blocks 1; 1066 | | %b0: 1067 194:6| 5: <2, 2, 1, 0> | %v0 = add i32 %p0, %p1; <@a1> 1068 197:2| 5: <2, 3, 1, 0> | %v1 = add i32 %p0, %v0; <@a1> 1069 199:6| 8: <10, 1> | ret i32 %v1; <@a4> 1070 201:0| 0: <65534> | } 1071 204:0|0: <65534> |} 1072 1073Note that the example above shows the standard abbreviations used by 1074*pnacl-finalize*. 1075 1076.. _link_for_types_block_section: 1077 1078Types Block 1079=========== 1080 1081The types block defines all types used in a program. It must appear in the 1082:ref:`module block<link_for_module_block>`, before any :ref:`function 1083address<link_for_function_address_section>` records, the :ref:`globals 1084block<link_for_globals_block_section>`, the :ref:`valuesymtab 1085block<link_for_valuesymtab_block_section>`, and any :ref:`function 1086blocks<link_for_function_blocks_section>`. 1087 1088All types used in a program must be defined in the types block. Many PNaClAsm 1089constructs allow one to use explicit type names, rather than the type 1090identifiers defined by this block. However, they are internally converted to the 1091corresponding type identifier in the types block. Hence, the requirement that 1092the types block must appear early in the module block. 1093 1094Each record in the types block defines a type used by the program. Types can be 1095broken into the following groups: 1096 1097Primitive value types 1098 Defines the set of base types for values. This includes various sizes of 1099 integer and floating point types. 1100 1101Void type 1102 A primitive type that doesn't represent any value and has no size. 1103 1104Function types 1105 The type signatures of functions. 1106 1107Vector type 1108 Defines vectors of primitive types. 1109 1110In addition, any type that is not defined using another type is a primitive 1111type. All other types (i.e. function and vector) are composite types. 1112 1113Types must be defined in a topological order, causing primitive types to appear 1114before the composite types that use them. Each type must be unique. There are no 1115additional restrictions on the order that types can be defined in a types block. 1116 1117The following subsections introduce each valid PNaClAsm type, and the 1118corresponding PNaClAsm construct that defines the type. Types not defined in the 1119types block, can't be used in a PNaCl program. 1120 1121The first record of a types block must be a :ref:`count 1122record<link_for_types_count_record>`, defining how many types are defined by the 1123types block. All remaining records defines a type. The following subsections 1124defines valid records within a types block. The order of type records is 1125important. The position of each defining record implicitly defines the type ID 1126that will be used to denote that type, within other PNaCl records of the bitcode 1127file. 1128 1129To make this more concrete, consider the following example types block:: 1130 1131 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1132 48:0| 3: <1, 4> | count 4; 1133 50:4| 3: <7, 32> | @t0 = i32; 1134 53:6| 3: <3> | @t1 = float; 1135 55:4| 3: <2> | @t2 = void; 1136 57:2| 3: <21, 0, 2, 0, 1> | @t3 = void (i32, float); 1137 62:0| 0: <65534> | } 1138 1139This example defines a types block that defines four type IDs: 1140 1141@t0 1142 A 32-bit integer type. 1143@t1 1144 A 32-bit floating point type. 1145@t2 1146 The void type. 1147@t3 1148 A function, taking 32-bit integer and float point arguments that returns 1149 void. 1150 1151.. _link_for_types_count_record: 1152 1153Count Record 1154------------ 1155 1156The *count record* defines how many types are defined in the types 1157block. Following the types count record are records that define types used by 1158the PNaCl program. 1159 1160**Syntax**:: 1161 1162 count N; <A> 1163 1164**Record**:: 1165 1166 AA: <1, N> 1167 1168**Semantics**: 1169 1170This construct defines the number of types used by the PNaCl program. ``N`` is 1171the number of types defined in the types block. It is an error to define more 1172(or fewer) types than value ``N``, within the enclosing types block. 1173 1174**Constraints**:: 1175 1176 AA == AbbrevIndex(A) & 1177 0 == NumTypes 1178 1179**Updates**:: 1180 1181 ExpectedTypes = N; 1182 1183**Examples**:: 1184 1185 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1186 48:0| 3: <1, 4> | count 4; 1187 50:4| 3: <7, 32> | @t0 = i32; 1188 53:6| 3: <3> | @t1 = float; 1189 55:4| 3: <2> | @t2 = void; 1190 57:2| 3: <21, 0, 2, 0, 1> | @t3 = void (i32, float); 1191 62:0| 0: <65534> | } 1192 1193Void Type 1194--------- 1195 1196The *void* type record defines the void type, which corresponds to the type that 1197doesn't define any value, and has no size. 1198 1199**Syntax**:: 1200 1201 @tN = void; <A> 1202 1203**Record**:: 1204 1205 AA: <2> 1206 1207**Semantics**: 1208 1209The void type record defines the type that has no values and has no size. 1210 1211**Constraints**:: 1212 1213 AA == AbbrevIndex(A) & 1214 N == NumTypes 1215 1216**Updates**:: 1217 1218 ++NumTypes; 1219 TypeOf(@tN) = void; 1220 1221**Examples**:: 1222 1223 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1224 48:0| 3: <1, 4> | count 4; 1225 50:4| 3: <7, 32> | @t0 = i32; 1226 53:6| 3: <3> | @t1 = float; 1227 55:4| 3: <2> | @t2 = void; 1228 62:0| 0: <65534> | } 1229 1230Integer Types 1231------------- 1232 1233PNaClAsm allows integer types for various bit sizes. Valid bit sizes are 1, 8, 123416, 32, and 64. Integers can be signed or unsigned, but the signed component of 1235an integer is not specified by the type. Rather, individual instructions 1236determine whether the value is assumed to be signed or unsigned. 1237 1238It should be noted that in PNaClAsm, all pointers are implemented as 32-bit 1239(unsigned) integers. There isn't a separate type for pointers. The only way to 1240tell that a 32-bit integer is a pointer, is when it is used in an instruction 1241that requires a pointer (such as load and store instructions). 1242 1243**Syntax**:: 1244 1245 @tN = iB; <A> 1246 1247**Record**:: 1248 1249 AA: <7, B> 1250 1251**Semantics**: 1252 1253An integer type record defines an integer type. ``B`` defines the number of bits 1254of the integer type. 1255 1256**Constraints**:: 1257 1258 AA == AbbrevIndex(A) & 1259 N == NumTypes & 1260 B in {1, 8, 16, 32, 64} 1261 1262**Updates**:: 1263 1264 ++NumTypes; 1265 TypeOf(@tN) = iB; 1266 1267**Examples**:: 1268 1269 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1270 48:0| 3: <1, 7> | count 7; 1271 50:4| 3: <7, 64> | @t0 = i64; 1272 53:6| 3: <7, 1> | @t1 = i1; 1273 56:2| 3: <7, 8> | @t2 = i8; 1274 58:6| 3: <7, 16> | @t3 = i16; 1275 61:2| 3: <7, 32> | @t4 = i32; 1276 64:4| 3: <21, 0, 0, 1> | @t5 = i64 (i1); 1277 68:4| 3: <2> | @t6 = void; 1278 70:2| 0: <65534> | } 1279 128032-Bit Floating Point Type 1281-------------------------- 1282 1283PNaClAsm allows computation on 32-bit floating point values. A floating point 1284type record defines the 32-bit floating point type. 1285 1286**Syntax**:: 1287 1288 @tN = float; <A> 1289 1290**Record**:: 1291 1292 AA: <3> 1293 1294**Semantics**: 1295 1296A floating point type record defines the 32-bit floating point type. 1297 1298**Constraints**:: 1299 1300 AA == AbbrevIndex(A) & 1301 N == NumTypes 1302 1303**Updates**:: 1304 1305 ++NumTypes; 1306 TypeOf(@tN) = float; 1307 1308**Examples**:: 1309 1310 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1311 48:0| 3: <1, 4> | count 4; 1312 50:4| 3: <4> | @t0 = double; 1313 52:2| 3: <3> | @t1 = float; 1314 54:0| 3: <21, 0, 0, 1> | @t2 = double (float); 1315 58:0| 3: <2> | @t3 = void; 1316 59:6| 0: <65534> | } 1317 131864-bit Floating Point Type 1319-------------------------- 1320 1321PNaClAsm allows computation on 64-bit floating point values. A 64-bit floating 1322type record defines the 64-bit floating point type. 1323 1324**Syntax**:: 1325 1326 @tN = double; <A> 1327 1328**Record**:: 1329 1330 AA: <4> 1331 1332**Semantics**: 1333 1334A double type record defines the 64-bit floating point type. 1335 1336**Constraints**:: 1337 1338 AA == AbbrevIndex(A) & 1339 N == NumTypes 1340 1341**Updates**:: 1342 1343 ++NumTypes; 1344 TypeOf(@tN) = double; 1345 1346**Examples**:: 1347 1348 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1349 48:0| 3: <1, 4> | count 4; 1350 50:4| 3: <4> | @t0 = double; 1351 52:2| 3: <3> | @t1 = float; 1352 54:0| 3: <21, 0, 0, 1> | @t2 = double (float); 1353 58:0| 3: <2> | @t3 = void; 1354 59:6| 0: <65534> | } 1355 1356Vector Types 1357------------ 1358 1359A vector type is a derived type that represents a vector of elements. Vector 1360types are used when multiple primitive data values are operated in parallel 1361using a single (SIMD) :ref:`vector instruction<link_for_vector_instructions>`. A 1362vector type requires a size (number of elements) and an underlying primitive 1363data type. 1364 1365**Syntax**:: 1366 1367 @tN = < E x T > <A> 1368 1369**Record**:: 1370 1371 AA: <12, E, TT> 1372 1373**Semantics**: 1374 1375The vector type defines a vector of elements. ``T`` is the type of each 1376element. ``E`` is the number of elements in the vector. 1377 1378Vector types can only be defined on ``i1``, ``i8``, ``i16``, ``i32``, and 1379``float``. All vector types, except those on ``i1``, must contain exactly 128 1380bits. The valid element sizes are restricted as follows: 1381 1382====== =================== 1383Type Valid element sizes 1384====== =================== 1385i1 4, 8, 16 1386i8 16 1387i16 8 1388i32 4 1389float 4 1390====== =================== 1391 1392**Constraints**:: 1393 1394 AA == AbbrevIndex(A) & 1395 TT == AbsoluteIndex(TypeID(T)) & 1396 N == NumTypes 1397 1398**Updates**:: 1399 1400 ++NumTypes 1401 TypeOf(@tN) = <E x T> 1402 1403**Examples**:: 1404 1405 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1406 48:0| 3: <1, 14> | count 14; 1407 50:4| 3: <7, 32> | @t0 = i32; 1408 53:6| 3: <7, 1> | @t1 = i1; 1409 56:2| 3: <2> | @t2 = void; 1410 58:0| 3: <12, 4, 1> | @t3 = <4 x i1>; 1411 61:2| 3: <12, 8, 1> | @t4 = <8 x i1>; 1412 64:4| 3: <12, 16, 1> | @t5 = <16 x i1>; 1413 67:6| 3: <7, 8> | @t6 = i8; 1414 70:2| 3: <12, 16, 6> | @t7 = <16 x i8>; 1415 73:4| 3: <7, 16> | @t8 = i16; 1416 76:0| 3: <12, 8, 8> | @t9 = <8 x i16>; 1417 79:2| 3: <12, 4, 0> | @t10 = <4 x i32>; 1418 82:4| 3: <3> | @t11 = float; 1419 84:2| 3: <12, 4, 11> | @t12 = <4 x float>; 1420 87:4| 3: <21, 0, 2> | @t13 = void (); 1421 90:6| 0: <65534> | } 1422 1423.. _link_for_function_type: 1424 1425Function Type 1426------------- 1427 1428The *function* type can be thought of as a function signature. It consists of a 1429return type, and a (possibly empty) list of formal parameter types. 1430 1431**Syntax**:: 1432 1433 %tN = RT (T1, ... , TM) <A> 1434 1435**Record**:: 1436 1437 AA: <21, 0, IRT, IT1, ... , ITM> 1438 1439**Semantics**: 1440 1441The function type defines the signature of a function. ``RT`` is the return type 1442of the function, while types ``T1`` through ``TM`` are the types of the 1443arguments. Indices to the corresponding type identifiers are stored in the 1444corresponding record. 1445 1446The return value must either be a primitive type, type ``void``, or a vector 1447type. Parameter types can be a primitive or vector type. 1448 1449For ordinary functions, the only valid integer types that can be used for a 1450return or parameter type are ``i32`` and ``i64``. All other integer types are 1451not allowed. 1452 1453For :ref:`intrinsic functions<link_for_intrinsic_functions_section>`, all 1454integer types are allowed for both return and parameter types. 1455 1456**Constraints**:: 1457 1458 AA == AbbrevIndex(A) & 1459 M >= 0 & 1460 IRT == AbsoluteIndex(TypeID(RT)) & 1461 IT1 == AbsoluteIndex(TypeID(T1)) & 1462 ... 1463 ITM == AbsoluteIndex(TypeID(TM)) & 1464 N == NumTypes 1465 1466**Updates**:: 1467 1468 ++NumTypes 1469 TypeOf(@tN) = RT (T1, ... , TM) 1470 1471**Examples**:: 1472 1473 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1474 48:0| 3: <1, 7> | count 7; 1475 50:4| 3: <7, 32> | @t0 = i32; 1476 53:6| 3: <3> | @t1 = float; 1477 55:4| 3: <4> | @t2 = double; 1478 57:2| 3: <21, 0, 2, 1> | @t3 = double (float); 1479 61:2| 3: <2> | @t4 = void; 1480 63:0| 3: <21, 0, 4> | @t5 = void (); 1481 66:2| 3: <21, 0, 0, 0, 1, 0, 2>| @t6 = 1482 | | i32 (i32, float, i32, double); 1483 72:4| 0: <65534> | } 1484 1485.. _link_for_globals_block_section: 1486 1487Globals Block 1488============= 1489 1490The globals block defines global addresses of variables and constants, used by 1491the PNaCl program. It also defines the memory associated with the global 1492addresses, and how to initialize each global variable/constant. It must appear 1493in the :ref:`module block<link_for_module_block>`. It must appear after the 1494:ref:`types block<link_for_types_block_section>`, as well as after all 1495:ref:`function address<link_for_function_address_section>` records. But, it must 1496also appear before the :ref:`valuesymtab 1497block<link_for_valuesymtab_block_section>`, and any 1498:ref:`function blocks<link_for_function_blocks_section>`. 1499 1500The globals block begins with a :ref:`count 1501record<link_for_globals_count_record>`, defining how many global addresses are 1502defined by the PNaCl program. It is then followed by a sequence of records that 1503defines each global address, and how each global address is initialized. 1504 1505The standard sequence, for defining global addresses, begins with a global 1506address record. It is then followed by a sequence of records defining how the 1507global address is initialized. If the initializer is simple, a single record is 1508used. Otherwise, the initializer is preceded with a :ref:`compound 1509record<link_for_compound_initializer>`, specifying a number *N*, followed by 1510sequence of *N* simple initializer records. 1511 1512The size of the memory referenced by each global address is defined by its 1513initializer records. All simple initializer records define a sequence of 1514bytes. A compound initializer defines the sequence of bytes by concatenating the 1515corresponding sequence of bytes for each of its simple initializer records. 1516 1517For notational convenience, PNaClAsm begins a compound record with a "{", and 1518inserts a "}" after the last initializer record associated with the compound 1519record. This latter "}" does not correspond to any record. It is implicitly 1520assumed by the size specified in the compound record, and is added only to 1521improve readability. 1522 1523Explicit alignment is specified for global addresses, and must be a power of 15242. See :ref:`memory blocks and 1525alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed 1526discussion on how to define alignment. 1527 1528For example, consider the following pnacl-bcdis output snippet:: 1529 1530 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 1531 60:0| 3: <5, 2> | count 2; 1532 62:4| 3: <0, 1, 1> | const @g0, align 1, 1533 65:6| 3: <2, 8> | zerofill 8; 1534 68:2| 3: <0, 1, 0> | var @g1, align 1, 1535 71:4| 3: <1, 2> | initializers 2 { 1536 74:0| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} 1537 78:6| 3: <2, 2> | zerofill 2; 1538 | | } 1539 81:2| 0: <65534> | } 1540 1541This snippet defines the global constant ``@g0``, and the global variable 1542``@g1``. ``@g0`` is 8 bytes long, and initialized to zero. ``@g1`` is 1543initialized with 6 bytes: ``1 2 3 4 0 0``. 1544 1545.. _link_for_globals_count_record: 1546 1547Count Record 1548------------ 1549 1550The count record defines the number of global addresses used by the PNaCl 1551program. 1552 1553**Syntax**:: 1554 1555 count N; <A> 1556 1557**Record**:: 1558 1559 AA: <5, N> 1560 1561**Semantics**: 1562 1563This record must appear first in the globals block. The count record defines 1564the number of global addresses used by the program. 1565 1566**Constraints**:: 1567 1568 AA == AbbrevIndex(A) 1569 1570**Updates**:: 1571 1572 ExpectedGlobals = N; 1573 ExpectedInitializers = 0; 1574 1575**Examples**:: 1576 1577 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 1578 60:0| 3: <5, 2> | count 2; 1579 62:4| 3: <0, 1, 1> | const @g0, align 1, 1580 65:6| 3: <2, 8> | zerofill 8; 1581 68:2| 3: <0, 1, 0> | var @g1, align 1, 1582 71:4| 3: <1, 2> | initializers 2 { 1583 74:0| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} 1584 78:6| 3: <2, 2> | zerofill 2; 1585 | | } 1586 81:2| 0: <65534> | } 1587 1588.. _link_for_global_variable_address: 1589 1590Global Variable Addresses 1591------------------------- 1592 1593A global variable address record defines a global address to global data. The 1594global variable address record must be immediately followed by initializer 1595record(s) that define how the corresponding global variable is initialized. 1596 1597**Syntax**:: 1598 1599 var @gN, align V, <A> 1600 1601**Record**:: 1602 1603 AA: <0, VV, 0> 1604 1605**Semantics**: 1606 1607A global variable address record defines a global address for a global variable. 1608``V`` is the :ref:`memory 1609alignment<link_for_memory_blocks_and_alignment_section>` for the global variable 1610address, and is a power of 2. 1611 1612It is assumed that the memory, referenced by the global variable address, can be 1613both read and written to. 1614 1615**Constraints**:: 1616 1617 AA == AbbrevIndex(A) & 1618 N == NumGlobalAddresses & 1619 ExpectedInitializers == 0 & 1620 VV == Log2(V+1) 1621 1622**Updates**:: 1623 1624 ++NumGlobalAddresses; 1625 ExpectedInitializers = 1; 1626 TypeOf(@gN) = i32; 1627 1628**Examples**:: 1629 1630 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 1631 60:0| 3: <5, 2> | count 2; 1632 62:4| 3: <0, 3, 0> | var @g0, align 4, 1633 65:6| 3: <2, 8> | zerofill 8; 1634 68:2| 3: <0, 1, 0> | var @g1, align 1, 1635 71:4| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} 1636 76:2| 0: <65534> | } 1637 80:0|0: <65534> |} 1638 1639.. _link_for_global_constant_address: 1640 1641Global Constant Addresses 1642------------------------- 1643 1644A global constant address record defines an address corresponding to a global 1645constant that can't be modified by the program. The global constant address 1646record must be immediately followed by initializer record(s) that define how 1647the corresponding global constant is initialized. 1648 1649**Syntax**:: 1650 1651 const @gN, align V, <A> 1652 1653**Record**:: 1654 1655 AA: <0, VV, 1> 1656 1657**Semantics**: 1658 1659A global constant address record defines a global address for a global constant. 1660``V`` is the :ref:`memory 1661alignment<link_for_memory_blocks_and_alignment_section>` for the global constant 1662address, and is a power of 2. 1663 1664It is assumed that the memory, referenced by the global constant address, is 1665only read, and can't be written to. 1666 1667Note that the only difference between a global variable address and a global 1668constant address record is the third element of the record. If the value is 1669zero, it defines a global variable address. If the value is one, it defines a 1670global constant address. 1671 1672**Constraints**:: 1673 1674 AA == AbbrevIndex(A) & 1675 N == NumGlobalAddresses & 1676 ExpectedInitializers == 0 & 1677 VV == Log2(V+1) 1678 1679**Updates**:: 1680 1681 ++NumGlobalAddresses; 1682 ExpectedInitializers = 1; 1683 TypeOf(@gN) = i32; 1684 1685**Examples**:: 1686 1687 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 1688 60:0| 3: <5, 2> | count 2; 1689 62:4| 3: <0, 3, 1> | const @g0, align 4, 1690 65:6| 3: <2, 8> | zerofill 8; 1691 68:2| 3: <0, 1, 1> | const @g1, align 1, 1692 71:4| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} 1693 76:2| 0: <65534> | } 1694 1695Zerofill Initializer 1696-------------------- 1697 1698The zerofill initializer record initializes a sequence of bytes, associated with 1699a global address, with zeros. 1700 1701**Syntax**:: 1702 1703 zerofill N; <A> 1704 1705**Record**:: 1706 1707 AA: <2, N> 1708 1709**Semantics**: 1710 1711A zerofill initializer record initializes a sequence of bytes, associated with a 1712global address, with zeros. The number of bytes initialized to zero is ``N``. 1713 1714**Constraints**:: 1715 1716 AA == AbbrevIndex(A) & 1717 ExpectedInitializers > 0 1718 1719**Updates**:: 1720 1721 --ExpectedInitializers; 1722 1723**Examples**:: 1724 1725 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 1726 60:0| 3: <5, 2> | count 2; 1727 62:4| 3: <0, 3, 1> | const @g0, align 4, 1728 65:6| 3: <2, 8> | zerofill 8; 1729 68:2| 3: <0, 1, 0> | var @g1, align 1, 1730 71:4| 3: <2, 4> | zerofill 4; 1731 74:0| 0: <65534> | } 1732 1733Data Initializer 1734---------------- 1735 1736Data records define a sequence of bytes. These bytes define the initial value of 1737the contents of the corresponding memory. 1738 1739**Syntax**:: 1740 1741 { B1 , .... , BN } <A> 1742 1743**Record**:: 1744 1745 AA: <3, B1, ..., BN> 1746 1747**Semantics**: 1748 1749A data record defines a sequence of (unsigned) bytes ``B1`` through ``BN``, that 1750initialize ``N`` bytes of memory. 1751 1752**Constraints**:: 1753 1754 AA == AbbrevIndex(A) & 1755 ExpectedInitializers > 0 1756 1757**Updates**:: 1758 1759 --ExpectedInitializers; 1760 1761**Examples**:: 1762 1763 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); 1764 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 1765 68:0| 3: <5, 2> | count 2; 1766 70:4| 3: <0, 1, 1> | const @g0, align 1, 1767 73:6| 3: <3, 1, 2, 97, 36, 44, | { 1, 2, 97, 36, 44, 88, 1768 | 88, 44, 50> | 44, 50} 1769 86:0| 3: <0, 1, 1> | const @g1, align 1, 1770 89:2| 3: <1, 3> | initializers 3 { 1771 91:6| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} 1772 96:4| 3: <4, 0> | reloc @f0; 1773 99:0| 3: <3, 99, 66, 22, 12> | { 99, 66, 22, 12} 1774 | | } 1775 105:2| 0: <65534> | } 1776 1777Relocation Initializer 1778---------------------- 1779 1780A relocation initializer record allows one to define the initial value of a 1781global address with the value of another global address (i.e. either 1782:ref:`function<link_for_function_address_section>`, 1783:ref:`variable<link_for_global_variable_address>`, or 1784:ref:`constant<link_for_global_constant_address>`). Since addresses are 1785pointers, a relocation initializer record defines 4 bytes of memory. 1786 1787**Syntax**:: 1788 1789 reloc V; <A> 1790 1791**Record**:: 1792 1793 AA: <4, VV> 1794 1795**Semantics**: 1796 1797A relocation initializer record defines a 4-byte value containing the specified 1798global address ``V``. 1799 1800**Constraints**:: 1801 1802 AA == AbbrevIndex(A) & 1803 VV == AbsoluteIndex(V) & 1804 VV >= NumFuncAddresses & 1805 VV < NumFuncAddresses + ExpectedGlobals & 1806 ExpectedInitializers > 0 1807 1808**Updates**:: 1809 1810 --ExpectedInitializers; 1811 1812**Examples**:: 1813 1814 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1815 48:0| 3: <1, 2> | count 2; 1816 50:4| 3: <2> | @t0 = void; 1817 52:2| 3: <21, 0, 0> | @t1 = void (); 1818 55:4| 0: <65534> | } 1819 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); 1820 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 1821 68:0| 3: <5, 2> | count 2; 1822 70:4| 3: <0, 1, 0> | var @g0, align 1, 1823 73:6| 3: <1, 3> | initializers 3 { 1824 76:2| 3: <4, 0> | reloc @f0; 1825 78:6| 3: <4, 1> | reloc @g0; 1826 81:2| 3: <4, 2> | reloc @g1; 1827 | | } 1828 83:6| 3: <0, 3, 0> | var @g1, align 4, 1829 87:0| 3: <2, 4> | zerofill 4; 1830 89:4| 0: <65534> | } 1831 1832This example defines global address ``@g0`` and ``@g1``. ``@g0`` defines 12 1833bytes of memory, and is initialized with three addresses ``@f1``, ``@g0``, and 1834``@g1``. Note that all global addresses can be used in a relocation 1835initialization record, even if it isn't defined yet. 1836 1837Subfield Relocation Initializer 1838------------------------------- 1839 1840A subfield relocation initializer record allows one to define the initial value 1841of a global address with the value of another (non-function) global address 1842(i.e. either :ref:`variable<link_for_global_variable_address>` or 1843:ref:`constant<link_for_global_constant_address>` address), plus a 1844constant. Since addresses are pointers, a relocation initializer record defines 18454 bytes of memory. 1846 1847**Syntax**:: 1848 1849 reloc V + X; <A> 1850 reloc V - X; <A> 1851 1852**Record**:: 1853 1854 AA: <4, VV, XXX> 1855 1856**Semantics**: 1857 1858A subfield relocation initializer record defines a 4-byte value containing the 1859specified global (non-function) address ``V``, modified by the unsigned offset 1860``X``. ``XX`` is the corresponding signed offset. In the first form, ``XX == 1861X``. In the second form, ``XX == -X``. 1862 1863**Constraints**:: 1864 1865 AA == AbbrevIndex(A) 1866 VV == AbsoluteIndex(V) 1867 VV >= NumFuncAddresses 1868 VV < NumFuncAddresses + ExpectedGlobals 1869 ExpectedInitializers > 0 1870 XXX == SignRotate(XX) 1871 1872**Updates**:: 1873 1874 --ExpectedInitializers; 1875 1876**Examples**:: 1877 1878 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1879 48:0| 3: <1, 0> | count 0; 1880 50:4| 0: <65534> | } 1881 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 1882 60:0| 3: <5, 3> | count 3; 1883 62:4| 3: <0, 1, 0> | var @g0, align 1, 1884 65:6| 3: <1, 3> | initializers 3 { 1885 68:2| 3: <4, 0, 1> | reloc @g0 + 1; 1886 71:4| 3: <4, 1, 4294967295> | reloc @g1 - 1; 1887 79:2| 3: <4, 2, 4> | reloc @g2 + 4; 1888 | | } 1889 82:4| 3: <0, 3, 0> | var @g1, align 4, 1890 85:6| 3: <2, 4> | zerofill 4; 1891 88:2| 3: <0, 3, 0> | var @g2, align 4, 1892 91:4| 3: <2, 8> | zerofill 8; 1893 94:0| 0: <65534> | } 1894 1895.. _link_for_compound_initializer: 1896 1897Compound Initializer 1898-------------------- 1899 1900The compound initializer record must immediately follow a global 1901:ref:`variable<link_for_global_variable_address>` or 1902:ref:`constant<link_for_global_constant_address>` address record. It defines how 1903many simple initializer records are used to define the initializer. The size of 1904the corresponding memory is the sum of the bytes needed for each of the 1905succeeding initializers. 1906 1907Note that a compound initializer can't be used as a simple initializer of 1908another compound initializer (i.e. nested compound initializers are not 1909allowed). 1910 1911**Syntax**:: 1912 1913 initializers N { <A> 1914 ... 1915 } 1916 1917**Record**:: 1918 1919 AA: <1, N> 1920 1921**Semantics**: 1922 1923Defines that the next `N` initializers should be associated with the global 1924address of the previous record. 1925 1926**Constraints**:: 1927 1928 AA == AbbrevIndex(A) & 1929 ExpectedInitializers == 1 1930 1931**Updates**:: 1932 1933 ExpectedInitializers = N; 1934 1935**Examples**:: 1936 1937 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 1938 48:0| 3: <1, 0> | count 0; 1939 50:4| 0: <65534> | } 1940 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 1941 60:0| 3: <5, 2> | count 2; 1942 62:4| 3: <0, 0, 1> | const @g0, align 0, 1943 65:6| 3: <1, 2> | initializers 2 { 1944 68:2| 3: <2, 8> | zerofill 8; 1945 70:6| 3: <3, 3, 2, 1, 0> | { 3, 2, 1, 0} 1946 | | } 1947 75:4| 3: <0, 0, 0> | var @g1, align 0, 1948 78:6| 3: <1, 2> | initializers 2 { 1949 81:2| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} 1950 86:0| 3: <2, 2> | zerofill 2; 1951 | | } 1952 88:4| 0: <65534> | } 1953 1954.. _link_for_valuesymtab_block_section: 1955 1956Valuesymtab Block 1957================= 1958 1959The valuesymtab block does not define any values. Its only goal is to associate 1960text names with external :ref:`function 1961addresses<link_for_function_address_section>`. Each association is defined by a 1962record in the valuesymtab block. Currently, only 1963:ref:`intrinsic<link_for_intrinsic_functions_section>` function addresses and 1964the (external) start function (``_start``) can be named. All named function 1965addresses must be external. Each record in the valuesymtab block is a *entry* 1966record, defining a single name association. 1967 1968Entry Record 1969------------ 1970 1971The *entry* record defines a name for a function address. 1972 1973**Syntax**:: 1974 1975 V : "NAME"; <A> 1976 1977**Record**:: 1978 1979 AA: <1, B1, ... , BN> 1980 1981**Semantics**: 1982 1983The *entry* record defines a name ``NAME`` for function address ``V``. ``NAME`` 1984is a sequence of ASCII characters ``B1`` through ``BN``. 1985 1986**Examples**:: 1987 1988 72:0| 3: <8, 4, 0, 1, 0> | declare external 1989 | | void @f0(i32, i32, i32, i32, i1); 1990 76:6| 3: <8, 4, 0, 1, 0> | declare external 1991 | | void @f1(i32, i32, i32, i32, i1); 1992 81:4| 3: <8, 5, 0, 0, 0> | define external void @f2(i32); 1993 86:2| 1: <65535, 19, 2> | globals { // BlockID = 19 1994 92:0| 3: <5, 0> | count 0; 1995 94:4| 0: <65534> | } 1996 96:0| 1: <65535, 14, 2> | valuesymtab { // BlockID = 14 1997 104:0| 3: <1, 1, 108, 108, 118, | @f1 : "llvm.memmove.p0i8.p0i8.i32"; 1998 | 109, 46, 109, 101, | 1999 | 109, 109, 111, 118, | 2000 | 101, 46, 112, 48, | 2001 | 105, 56, 46, 112, 48,| 2002 | 105, 56, 46, 105, 51,| 2003 | 50> | 2004 145:4| 3: <1, 2, 95, 115, 116, | @f2 : "_start"; 2005 | 97, 114, 116> | 2006 157:0| 3: <1, 0, 108, 108, 118, | @f0 : "llvm.memcpy.p0i8.p0i8.i32"; 2007 | 109, 46, 109, 101, | 2008 | 109, 99, 112, 121, | 2009 | 46, 112, 48, 105, 56,| 2010 | 46, 112, 48, 105, 56,| 2011 | 46, 105, 51, 50> | 2012 197:0| 0: <65534> | } 2013 2014.. _link_for_module_block: 2015 2016Module Block 2017============ 2018 2019The module block, like all blocks, is enclosed in a pair of 2020:ref:`enter<link_for_enter_block_record_section>` / 2021:ref:`exit<link_for_exit_block_record_section>` records, using block ID 8. A 2022well-formed module block consists of the following records (in order): 2023 2024A version record 2025 The :ref:`version record<link_for_version_record>` communicates which version 2026 of the PNaCl bitcode reader/writer should be used. Note that this is 2027 different than the PNaCl bitcode (ABI) version. The PNaCl bitcode (ABI) 2028 version defines what is expected in records, and is defined in the header 2029 record of the bitcode file. The version record defines the version of the 2030 PNaCl bitcode reader/writer to use to convert records into bit sequences. 2031 2032Optional local abbreviations 2033 Defines a list of local :ref:`abbreviations<link_for_abbreviations_section>` 2034 to use for records within the module block. 2035 2036An abbreviations block 2037 The :ref:`abbreviations block<link_for_abbreviations_block_section>` defines 2038 user-defined, global abbreviations that are used to convert PNaCl records to 2039 bit sequences in blocks following the abbreviations block. 2040 2041A types block 2042 The :ref:`types block<link_for_types_block_section>` defines the set of all 2043 types used in the program. 2044 2045A non-empty sequence of function address records 2046 Each record defines a :ref:`function 2047 address<link_for_function_address_section>` used by the program. Function 2048 addresses must either be external, or defined internally by the program. If 2049 they are defined by the program, there must be a :ref:`function 2050 block<link_for_function_blocks_section>` (appearing later in the module) that 2051 defines the sequence of instructions for each defined function. 2052 2053A globals block defining the global variables. 2054 This :ref:`block<link_for_globals_block_section>` defines the set of 2055 global :ref:`variable<link_for_global_variable_address>` and 2056 :ref:`constant<link_for_global_constant_address>` addresses used by the 2057 program. In addition to the addresses, each global variable also defines how 2058 the corresponding global variable is initialized. 2059 2060An optional value symbol table block. 2061 This :ref:`block<link_for_valuesymtab_block_section>`, if defined, provides 2062 textual names for :ref:`function 2063 addresses<link_for_function_address_section>` (previously defined in the 2064 module). Note that only names for intrinsic functions and the start function 2065 are specified. 2066 2067A sequence of function blocks. 2068 Each :ref:`function block<link_for_Function_blocks_section>` defines the 2069 corresponding intermediate representation for each defined function. The 2070 order of function blocks is used to associate them with :ref:`function 2071 addresses<link_for_function_address_section>`. The order of the defined 2072 function blocks must follow the same order as the corresponding function 2073 addresses defined in the module block. 2074 2075Descriptions of the :ref:`abbreviations<link_for_abbreviations_section>`, 2076:ref:`types<link_for_types_block_section>`, 2077:ref:`globals<link_for_globals_block_section>`, :ref:`value symbol 2078table<link_for_valuesymtab_block_section>`, and 2079:ref:`function<link_for_function_blocks_section>` blocks are not provided 2080here. See the appropriate reference for more details. The following subsections 2081describe each of the records that can appear in a module block. 2082 2083.. _link_for_version_record: 2084 2085Version Record 2086-------------- 2087 2088The version record defines the implementation of the PNaCl bitstream 2089reader/writer to use. That is, the implementation that converts PNaCl records to 2090bit sequences, and converts them back to PNaCl records. Note that this is 2091different than the PNaCl version of the bitcode file (encoded in the header 2092record of the bitcode file). The PNaCl version defines the valid forms of PNaCl 2093records. The version record is specific to the PNaCl version, and may have 2094different values for different PNaCl versions. 2095 2096Note that currently, only PNaCl bitcode version 2, and version record value 1 is 2097defined. 2098 2099**Syntax**:: 2100 2101 version N; <A> 2102 2103**Record**:: 2104 2105 AA: <1, N> 2106 2107**Semantics**: 2108 2109The version record defines which PNaCl reader/writer rules should be 2110followed. ``N`` is the version number. Currently ``N`` must be 1. Future 2111versions of PNaCl may define additional legal values. 2112 2113**Constraints**:: 2114 2115 AA == AbbrevIndex(A) 2116 2117*Examples*:: 2118 2119 16:0|1: <65535, 8, 2> |module { // BlockID = 8 2120 24:0| 3: <1, 1> | version 1; 2121 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 2122 36:0| 0: <65534> | } 2123 2124.. _link_for_function_address_section: 2125 2126Function Address 2127---------------- 2128 2129A function address record describes a function address. *Defined* function 2130addresses define :ref:`implementations<link_for_function_blocks_section>` while 2131*declared* function addresses do not. 2132 2133Since a PNaCl program is assumed to be a complete (statically linked) 2134executable, All functions should be *defined* and *internal*. The exception to 2135this are :ref:`intrinsic functions<link_for_intrinsic_functions_section>`, which 2136should only be *declared* and *external*, since intrinsic functions will be 2137automatically converted to appropriate code by the :ref:`PNaCl 2138translator<link_for_pnacl_translator>`. 2139 2140The implementation of a *defined* function address is provided by a 2141corresponding function block, appearing later in the module block. The 2142association of a *defined* function address with the corresponding function 2143block is based on position. The *Nth* defined function address record, in the 2144module block, has its implementation in the *Nth* function block of that module 2145block. 2146 2147**Syntax**:: 2148 2149 PN LN T0 @fN ( T1 , ... , TM ); <A> 2150 2151**Record**:: 2152 2153 AA: <8, T, C, P, L> 2154 2155**Semantics**: 2156 2157Describes the function address ``@fN``. ``PN`` is the name that specifies the 2158prototype value ``P`` associated with the function. A function address is 2159*defined* only if ``P == 0``. Otherwise, it is only *declared*. The type of the 2160function is :ref:`function type<link_for_function_type>` ``@tT``. ``L`` is the 2161linkage specification corresponding to name ``LN``. ``C`` is the calling 2162convention used by the function. 2163 2164Note that function signature must be defined by a function type in the types 2165block. Hence, the return value must either be a primitive type, type ``void``, 2166or a vector type. 2167 2168For ordinary functions, integer parameter and types can only be ``i32`` and 2169``i64``. All other integer types are not allowed. For intrinsic functions, all 2170integer types are allowed. 2171 2172Valid prototype names ``PN``, and corresponding ``P`` values, are: 2173 2174= ======= 2175P PN 2176= ======= 21771 declare 21780 define 2179= ======= 2180 2181Valid linkage names ``LN``, and corresponding ``L`` values, are: 2182 2183= ======== 2184L LN 2185= ======== 21863 internal 21870 external 2188= ======== 2189 2190Currently, only one calling convention ``C`` is supported: 2191 2192= ==================== 2193C Calling Convention 2194= ==================== 21950 C calling convention 2196= ==================== 2197 2198**Constraints**:: 2199 2200 AA = AbbrevIndex(A) & 2201 T = TypeID(TypeOf(T0 ( T1 , ... , TN ))) & 2202 N = NumFuncAddresses 2203 2204**Updates**:: 2205 2206 ++NumFuncAddresses; 2207 TypeOf(@fN) = TypeOf(TypeID(i32)); 2208 TypeOfFcn(@fN) = TypeOf(@tT); 2209 2210 if PN == 0: 2211 DefiningFcnIDs += @FN; 2212 ++NumDefinedFunctionAddresses; 2213 2214**Examples**:: 2215 2216 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 2217 48:0| 3: <1, 7> | count 7; 2218 50:4| 3: <7, 32> | @t0 = i32; 2219 53:6| 3: <3> | @t1 = float; 2220 55:4| 3: <4> | @t2 = double; 2221 57:2| 3: <2> | @t3 = void; 2222 59:0| 3: <21, 0, 2, 1> | @t4 = double (float); 2223 63:0| 3: <21, 0, 0, 0, 1, 0, 2>| @t5 = 2224 | | i32 (i32, float, i32, double); 2225 69:2| 3: <21, 0, 3> | @t6 = void (); 2226 72:4| 0: <65534> | } 2227 76:0| 3: <8, 4, 0, 1, 0> | declare external double @f0(float); 2228 80:6| 3: <8, 5, 0, 1, 0> | declare external 2229 | | i32 @f1(i32, float, i32, double); 2230 85:4| 3: <8, 6, 0, 0, 0> | define external void @f2(); 2231 2232.. _link_for_constants_block_section: 2233 2234Constants Blocks 2235================ 2236 2237Constants blocks define literal constants used within each function. Its intent 2238is to define them once, before instructions. A constants block can only appear 2239in a :ref:`function block<link_for_function_blocks_section>`, and must appear 2240before any instructions in the function block. 2241 2242Currently, only integer literals, floating point literals, and undefined vector 2243constants can be defined. 2244 2245To minimize type information put in a constants block, the type information is 2246separated from the constants. This allows a sequence of constants to be given 2247the same type. This is done by defining a :ref:`set type 2248record<link_for_constants_set_type_record>`, followed by a sequence of literal 2249constants. These literal constants all get converted to the type of the 2250preceding set type record. 2251 2252Note that constants that are used for switch case selectors should not be added 2253to the constants block, since the switch instruction contains the constants used 2254for case selectors. All other constants in the function block must be put into a 2255constants block, so that instructions can use them. 2256 2257To make this more concrete, consider the following example constants block:: 2258 2259 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 2260 116:0| 3: <1, 0> | i32: 2261 118:4| 3: <4, 2> | %c0 = i32 1; 2262 121:0| 3: <4, 4> | %c1 = i32 2; 2263 123:4| 3: <1, 2> | i8: 2264 126:0| 3: <4, 8> | %c2 = i8 4; 2265 128:4| 3: <4, 6> | %c3 = i8 3; 2266 131:0| 3: <1, 1> | float: 2267 133:4| 3: <6, 1065353216> | %c4 = float 1; 2268 139:6| 0: <65534> | } 2269 2270.. _link_for_constants_set_type_record: 2271 2272Set Type Record 2273--------------- 2274 2275The *set type* record defines the type to use for the (immediately) succeeding 2276literals. 2277 2278**Syntax**:: 2279 2280 T: <A> 2281 2282**Record**:: 2283 2284 AA: <1, TT> 2285 2286**Semantics**: 2287 2288The *set type* record defines type ``T`` to be used to type the (immediately) 2289succeeding literals. ``T`` must be a non-void primitive value type or a vector 2290type. 2291 2292**Constraints**:: 2293 2294 TT == TypeID(T) 2295 2296**Updates**:: 2297 2298 ConstantsSetType = T; 2299 2300**Examples**:: 2301 2302 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 2303 116:0| 3: <1, 0> | i32: 2304 118:4| 3: <4, 2> | %c0 = i32 1; 2305 121:0| 3: <4, 4> | %c1 = i32 2; 2306 123:4| 3: <1, 2> | i8: 2307 126:0| 3: <4, 8> | %c2 = i8 4; 2308 128:4| 3: <4, 6> | %c3 = i8 3; 2309 131:0| 3: <1, 1> | float: 2310 133:4| 3: <6, 1065353216> | %c4 = float 1; 2311 139:6| 0: <65534> | } 2312 2313.. _link_for_undefined_literal: 2314 2315Undefined Literal 2316----------------- 2317 2318The *undefined* literal record creates an undefined literal for the type *T* 2319defined by the preceding *set type* record. 2320 2321Note: See :ref:`insert element 2322instruction<link_for_insert_element_instruction_section>` for an example of how 2323you would use the undefined literal with vector types. 2324 2325**Syntax**:: 2326 2327 %cN = T undef; <50> 2328 2329**Record**:: 2330 2331 AA: <3> 2332 2333**Semantics**: 2334 2335The *undefined* literal record creates an undefined literal constant ``%cN`` for 2336type ``T``. ``T`` must be the type defined by the preceding *set type* record, 2337and be a primitive value type or a vector type. 2338 2339**Constraints**:: 2340 2341 N == NumFcnConsts & 2342 T == ConstantsSetType & 2343 IsPrimitive(T) or IsVector(T) 2344 2345**Updates**:: 2346 2347 ++NumFcnConsts; 2348 TypeOf(%cN) = T; 2349 2350**Examples**:: 2351 2352 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 2353 48:0| 3: <1, 5> | count 5; 2354 50:4| 3: <7, 32> | @t0 = i32; 2355 53:6| 3: <3> | @t1 = float; 2356 55:4| 3: <2> | @t2 = void; 2357 57:2| 3: <12, 4, 0> | @t3 = <4 x i32>; 2358 60:4| 3: <21, 0, 2> | @t4 = void (); 2359 63:6| 0: <65534> | } 2360 ... 2361 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 2362 116:0| 3: <1, 0> | i32: 2363 118:4| 3: <3> | %c0 = i32 undef; 2364 120:2| 3: <4, 2> | %c1 = i32 1; 2365 122:6| 3: <1, 3> | <4 x i32>: 2366 125:2| 3: <3> | %c2 = <4 x i32> undef; 2367 127:0| 3: <1, 1> | float: 2368 129:4| 3: <3> | %c3 = float undef; 2369 131:2| 0: <65534> | } 2370 2371.. _link_for_integer_literal: 2372 2373Integer Literal 2374--------------- 2375 2376The *integer literal* record creates an integer literal for the integer type *T* 2377defined by the preceding *set type* record. 2378 2379**Syntax**:: 2380 2381 %cN = T V; <A> 2382 2383**Record**:: 2384 2385 AA: <4, VV> 2386 2387**Semantics**: 2388 2389The *integer literal* record creates an integer literal constant ``%cN`` for 2390type ``T``. ``T`` must be the type defined by the preceding *set type* record, 2391and an integer type. The literal ``V`` can be signed, but must be definable by 2392type ``T``. 2393 2394**Constraints**:: 2395 2396 N == NumFcnConsts & 2397 T == ConstantsSetType & 2398 VV == SignRotate(V) & 2399 IsInteger(T) 2400 2401**Updates**:: 2402 2403 TypeOf(%cN) = T; 2404 2405**Examples**:: 2406 2407 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 2408 48:0| 3: <1, 7> | count 7; 2409 50:4| 3: <7, 8> | @t0 = i8; 2410 53:0| 3: <7, 16> | @t1 = i16; 2411 55:4| 3: <7, 32> | @t2 = i32; 2412 58:6| 3: <7, 64> | @t3 = i64; 2413 62:0| 3: <7, 1> | @t4 = i1; 2414 64:4| 3: <2> | @t5 = void; 2415 66:2| 3: <21, 0, 5> | @t6 = void (); 2416 69:4| 0: <65534> | } 2417 ... 2418 114:4| 1: <65535, 11, 2> | constants { // BlockID = 11 2419 124:0| 3: <1, 0> | i8: 2420 126:4| 3: <4, 2> | %c0 = i8 1; 2421 129:0| 3: <4, 4> | %c1 = i8 2; 2422 131:4| 3: <1, 1> | i16: 2423 134:0| 3: <4, 6> | %c2 = i16 3; 2424 136:4| 3: <4, 8> | %c3 = i16 4; 2425 139:0| 3: <1, 2> | i32: 2426 141:4| 3: <4, 10> | %c4 = i32 5; 2427 144:0| 3: <4, 12> | %c5 = i32 6; 2428 146:4| 3: <1, 3> | i64: 2429 149:0| 3: <4, 3> | %c6 = i64 -1; 2430 151:4| 3: <4, 5> | %c7 = i64 -2; 2431 154:0| 3: <1, 4> | i1: 2432 156:4| 3: <4, 3> | %c8 = i1 1; 2433 159:0| 3: <4, 0> | %c9 = i1 0; 2434 161:4| 0: <65534> | } 2435 2436Floating Point Literal 2437---------------------- 2438 2439The *floating point literal* record creates a floating point literal for the 2440floating point type *T* defined by the preceding *set type* record. 2441 2442**Syntax**:: 2443 2444 %cN = T V; <A> 2445 2446**Record**:: 2447 2448 AA: <6, VV> 2449 2450**Semantics**: 2451 2452The *floating point literal* record creates a floating point literal constant 2453``%cN`` for type ``T``. ``T`` must the type type defined by the preceding *set 2454type* record, and be a floating point type. The literal ``V`` is the floating 2455value to be defined. The value ``VV`` if the corresponding IEEE unsigned integer 2456that defines value ``V``. That is, the literal ``VV`` must be a valid IEEE 754 245732-bit (unsigned integer) value if ``T`` is ``float``, and a valid IEEE 754 245864-bit (unsigned integer) value if ``T`` is ``double``. 2459 2460**Constraints**:: 2461 2462 N == NumFcnConsts 2463 T == ConstantsSetType 2464 IsFloat(T) 2465 2466**Updates**:: 2467 2468 TypeOf(%cN) = T; 2469 2470**Examples**:: 2471 2472 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 2473 48:0| 3: <1, 4> | count 4; 2474 50:4| 3: <3> | @t0 = float; 2475 52:2| 3: <4> | @t1 = double; 2476 54:0| 3: <2> | @t2 = void; 2477 55:6| 3: <21, 0, 2> | @t3 = void (); 2478 59:0| 0: <65534> | } 2479 ... 2480 102:4| 1: <65535, 11, 2> | constants { // BlockID = 11 2481 112:0| 3: <1, 0> | float: 2482 114:4| 3: <6, 0> | %c0 = float 0; 2483 117:0| 3: <6, 1065353216> | %c1 = float 1; 2484 123:2| 3: <6, 1088421888> | %c2 = float 7; 2485 130:2| 3: <6, 1090519040> | %c3 = float 8; 2486 137:2| 3: <3> | %c4 = float undef; 2487 139:0| 3: <6, 2143289344> | %c5 = float nan; 2488 146:0| 3: <6, 2139095040> | %c6 = float inf; 2489 153:0| 3: <6, 4286578688> | %c7 = float -inf; 2490 160:0| 3: <1, 1> | double: 2491 162:4| 3: <6, | %c8 = double 1; 2492 | 4607182418800017408> | 2493 174:0| 3: <6, 0> | %c9 = double 0; 2494 176:4| 3: <6, | %c10 = double 5; 2495 | 4617315517961601024> | 2496 188:0| 3: <6, | %c11 = double 6; 2497 | 4618441417868443648> | 2498 199:4| 3: <6, | %c12 = double nan; 2499 | 9221120237041090560> | 2500 211:0| 3: <6, | %c13 = double inf; 2501 | 9218868437227405312> | 2502 222:4| 3: <6, | %c14 = double -inf; 2503 | 18442240474082181120>| 2504 234:0| 0: <65534> | } 2505 2506.. _link_for_function_blocks_section: 2507 2508Function Blocks 2509=============== 2510 2511A function block defines the implementation of a defined :ref:`function 2512address<link_for_function_address_section>`. The function address it defines is 2513based on the position of the corresponding defined function address. The Nth 2514defined function address always corresponds to the Nth function block in the 2515module block. 2516 2517A function implementation contains a list of basic blocks, forming the control 2518flow graph. Each *basic block* contains a list of instructions, and ends with a 2519:ref:`terminator instruction<link_for_terminator_instruction_section>` 2520(e.g. branch). 2521 2522Basic blocks are not represented by records. Rather, context is implicit. The 2523first basic block begins with the first instruction record in the function 2524block. Block boundaries are determined by terminator instructions. The 2525instruction that follows a terminator instruction begins a new basic block. 2526 2527The first basic block in a function is special in two ways: it is immediately 2528executed on entrance to the function, and it is not allowed to have predecessor 2529basic blocks (i.e. there can't be any branches to the entry block of a 2530function). Because the entry block has no predecessors, it also can't have any 2531:ref:`phi<link_for_phi_instruction_section>` instructions. 2532 2533The parameters are implied by the type of the corresponding function 2534address. One parameter is defined for each argument of the function :ref:`type 2535signature<link_for_function_type>` of the corresponding :ref:`function 2536address<link_for_function_address_section>`. 2537 2538The number of basic blocks is defined by the :ref:`count 2539record<link_for_basic_blocks_count>`. Each :ref:`terminator 2540instruction<link_for_terminator_instruction_section>` ends the current basic 2541block, and the next instruction begins a new basic block. Basic blocks are 2542numbered by the order they appear (starting with index 0). Basic block IDs have 2543the form ``%bN``, where ``N`` corresponds to the position of the basic block 2544within the function block. 2545 2546Each instruction, within a function block, corresponds to a corresponding PNaCl 2547record. The layout of a function block is the (basic block) count record, 2548followed by a sequence of instruction records. 2549 2550For readability, PNaClAsm introduces basic block IDs. These basic block IDs do 2551not correspond to PNaCl records, since basic block boundaries are defined 2552implicitly, after terminator instructions. They appear only for readability. 2553 2554Operands of instructions are defined using an :ref:`absolute 2555index<link_for_absolute_index_section>`. This absolute index implicitly encodes 2556function addresses, global addresses, parameters, constants, and instructions 2557that generate values. The encoding takes advantage of the implied ordering of 2558these values in the bitcode file, defining a contiguous sequence of indices for 2559each kind of identifier. That is, indices are ordered by putting function 2560address identifiers first, followed by global address identifiers, followed by 2561parameter identifiers, followed by constant identifiers, and lastly instruction 2562value identifiers. 2563 2564To save space in the encoded bitcode file, most operands are encoded using a 2565:ref:`relative index<link_for_relative_index>` value, rather than 2566:ref:`absolute<link_for_absolute_index_section>`. This 2567is done because most instruction operands refer to values defined earlier in the 2568(same) basic block. As a result, the relative distance (back) from the next 2569value defining instruction is frequently a small number. Small numbers tend to 2570require fewer bits when they are converted to bit sequences. 2571 2572Note that instructions that can appear in a function block are defined in 2573sections :ref:`link_for_terminator_instruction_section`, 2574:ref:`link_for_integer_binary_instructions`, 2575:ref:`link_for_floating_point_binary_instructions`, 2576:ref:`link_for_memory_creation_and_access_instructions`, 2577:ref:`link_for_conversion_instructions`, :ref:`link_for_compare_instructions`, 2578:ref:`link_for_vector_instructions`, and 2579:ref:`link_for_other_pnaclasm_instructions`. 2580 2581The following subsections define the remaining records that can appear in a 2582function block. 2583 2584Function Enter 2585-------------- 2586 2587PNaClAsm defines a function enter block construct. The corresponding record is 2588simply an :ref:`enter block<link_for_enter_block_record_section>` record, with 2589BlockID value ``12``. All context about the defining address is implicit by the 2590position of the function block, and the corresponding defining :ref:`function 2591address<link_for_function_address_section>`. To improve readability, PNaClAsm 2592includes the function signature into the syntax rule. 2593 2594**Syntax**:: 2595 2596 function TR @fN ( T0 %p0, ... , TM %pM ) { <B> 2597 2598**Record**:: 2599 2600 1: <65535, 12, B> 2601 2602**Semantics**: 2603 2604``B`` is the number of bits reserved for abbreviations in the block. If it is 2605omitted, 2 is assumed. See :ref:`enter<link_for_enter_block_record_section>` 2606block records for more details. 2607 2608The value of ``N`` corresponds to the positional index of the corresponding 2609defining function address this block is associated with. ``M`` is the number of 2610defined parameters (minus one) in the function heading. 2611 2612**Constraints**:: 2613 2614 N == NumFcnImpls & 2615 @fN in DefiningFcnIDs & 2616 TypeOfFcn(@fN) == TypeOf(TypeID(TR (T0, ... , TM))) 2617 2618**Updates**:: 2619 2620 ++NumFcnImpls; 2621 EnclosingFcnID = @fN; 2622 NumBasicBlocks = 0; 2623 ExpectedBlocks = 0; 2624 NumParams = M; 2625 for I in [0..M]: 2626 TypeOf(%pI) = TypeOf(TypeID(TI)); 2627 2628**Examples**:: 2629 2630 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 2631 48:0| 3: <1, 4> | count 4; 2632 50:4| 3: <7, 32> | @t0 = i32; 2633 53:6| 3: <2> | @t1 = void; 2634 55:4| 3: <21, 0, 1> | @t2 = void (); 2635 58:6| 3: <21, 0, 0, 0> | @t3 = i32 (i32); 2636 62:6| 0: <65534> | } 2637 ... 2638 104:0| 1: <65535, 12, 2> | function void @f0() { 2639 | | // BlockID = 12 2640 112:0| 3: <1, 1> | blocks 1; 2641 | | %b0: 2642 114:4| 3: <10> | ret void; 2643 116:2| 0: <65534> | } 2644 120:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { 2645 | | // BlockID = 12 2646 128:0| 3: <1, 1> | blocks 1; 2647 | | %b0: 2648 130:4| 3: <10, 1> | ret i32 %p0; 2649 133:0| 0: <65534> | } 2650 2651.. _link_for_basic_blocks_count: 2652 2653Count Record 2654------------ 2655 2656The count record, within a function block, defines the number of basic blocks 2657used to define the function implementation. It must be the first record in the 2658function block. 2659 2660**Syntax**:: 2661 2662 blocks: N; <A> 2663 %b0: 2664 2665**Record**:: 2666 2667 AA: <1, N> 2668 2669**Semantics**: 2670 2671The count record defines the number ``N`` of basic blocks in the implemented 2672function. 2673 2674**Constraints**:: 2675 2676 AA == AbbrevIndex(A) & 2677 ExpectedBasicBlocks == N & 2678 NumBasicBlocks == 0 2679 2680**Updates**:: 2681 2682 104:0| 1: <65535, 12, 2> | function void @f0() { 2683 | | // BlockID = 12 2684 112:0| 3: <1, 1> | blocks 1; 2685 | | %b0: 2686 114:4| 3: <10> | ret void; 2687 116:2| 0: <65534> | } 2688 120:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { 2689 | | // BlockID = 12 2690 128:0| 3: <1, 1> | blocks 1; 2691 | | %b0: 2692 130:4| 3: <10, 1> | ret i32 %p0; 2693 133:0| 0: <65534> | } 2694 2695.. _link_for_terminator_instruction_section: 2696 2697Terminator Instructions 2698======================= 2699 2700Terminator instructions are instructions that appear in a :ref:`function 2701block<link_for_function_blocks_section>`, and define the end of the current 2702basic block. A terminator instruction indicates which block should be executed 2703after the current block is finished. The function block is well formed only if 2704the number of terminator instructions, in the function block, corresponds to the 2705value defined by the corresponding function basic block :ref:`count 2706record<link_for_basic_blocks_count>`. 2707 2708Note that any branch instruction to label ``%bN``, where ``N >= 2709ExpectedBasicBlocks``, is illegal. For ease of readability, this constraint 2710hasn't been put on branch instructions. Rather it is only implied. 2711 2712In addition, it must be the case that ``NumBasicBlocks < ExpectedBasicBlocks``, 2713and will not be listed as a constraint. Further, if ``B = NumBasicBlocks + 1`` 2714is the number associated with the next basic block. Label `%bB:` only appears 2715if:: 2716 2717 B < ExpectedBasicBlocks 2718 2719That is, the label is omitted only if this terminator instruction is the last 2720instruction in the function block. 2721 2722Return Void Instruction 2723----------------------- 2724 2725The return void instruction is used to return control from a function back to 2726the caller, without returning any value. 2727 2728**Syntax**:: 2729 2730 ret void; <A> 2731 %bB: 2732 2733**Record**:: 2734 2735 AA: <10> 2736 2737**Semantics**: 2738 2739The return void instruction returns control to the calling function. 2740 2741**Constraints**:: 2742 2743 AA == AbbrevIndex(A) & 2744 B == NumBasicBlocks + 1 & 2745 ReturnType(TypeOf(EnclosingFcnID)) == void 2746 2747**Updates**:: 2748 2749 ++NumBasicBlocks; 2750 2751**Examples**:: 2752 2753 104:0| 1: <65535, 12, 2> | function void @f0() { 2754 | | // BlockID = 12 2755 112:0| 3: <1, 1> | blocks 1; 2756 | | %b0: 2757 114:4| 3: <10> | ret void; 2758 116:2| 0: <65534> | } 2759 2760Return Value Instruction 2761------------------------ 2762 2763The return value instruction is used to return control from a function back to 2764the caller, including a value. The value must correspond to the return type of 2765the enclosing function. 2766 2767**Syntax**:: 2768 2769 ret T V; <A> 2770 %bB: 2771 2772**Record**:: 2773 2774 AA: <10, VV> 2775 2776**Semantics**: 2777 2778The return value instruction returns control to the calling function, returning 2779the provided value. 2780 2781``V`` is the value to return. Type ``T`` must be of the type returned by the 2782function. It must also be the type associated with value ``V``. 2783 2784The return type ``T`` must either be a (non-void) primitive type, or a vector 2785type. If the function block is implementing an ordinary function, and the return 2786type is an integer type, it must be either ``i32`` or ``i64``. 2787 2788**Constraints**:: 2789 2790 AA == AbbrevIndex(A) & 2791 VV == RelativeIndex(V) & 2792 B == NumBasicBlocks + 1 & 2793 T == TypeOf(V) == ReturnType(TypeOf(EnclosingFcnID)) 2794 2795**Updates**:: 2796 2797 ++NumBasicBlocks; 2798 2799**Examples**:: 2800 2801 120:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { 2802 | | // BlockID = 12 2803 128:0| 3: <1, 1> | blocks 1; 2804 | | %b0: 2805 130:4| 3: <10, 1> | ret i32 %p0; 2806 2807Unconditional Branch Instruction 2808-------------------------------- 2809 2810The unconditional branch instruction is used to cause control flow to transfer 2811to a different basic block of the function. 2812 2813**Syntax**:: 2814 2815 br %bN; <A> 2816 %bB: 2817 2818**Record**:: 2819 2820 AA: <11, N> 2821 2822**Semantics**: 2823 2824The unconditional branch instruction causes control flow to transfer to basic 2825block ``N``. 2826 2827**Constraints**:: 2828 2829 AA == AbbrevIndex(A) & 2830 B == NumBasicBlocks + 1 & 2831 0 < N & 2832 N < ExpectedBasicBlocks 2833 2834**Updates**:: 2835 2836 ++NumBasicBlocks; 2837 2838**Examples**:: 2839 2840 88:0| 1: <65535, 12, 2> | function void @f0() { 2841 | | // BlockID = 12 2842 96:0| 3: <1, 5> | blocks 5; 2843 | | %b0: 2844 98:4| 3: <11, 3> | br label %b3; 2845 | | %b1: 2846 101:0| 3: <11, 4> | br label %b4; 2847 | | %b2: 2848 103:4| 3: <11, 1> | br label %b1; 2849 | | %b3: 2850 106:0| 3: <11, 2> | br label %b2; 2851 | | %b4: 2852 108:4| 3: <10> | ret void; 2853 110:2| 0: <65534> | } 2854 2855Conditional Branch Instruction 2856------------------------------ 2857 2858The conditional branch instruction is used to cause control flow to transfer to 2859a different basic block of the function, based on a boolean test condition. 2860 2861**Syntax**:: 2862 2863 br i1 C, %bT, %bBF; <A> 2864 %bB: 2865 2866**Record**:: 2867 2868 AA: <11, T, F, CC> 2869 2870**Semantics**: 2871 2872Upon execution of a conditional branch instruction, the *i1* (boolean) argument 2873``C`` is evaluated. If the value is ``true``, control flows to basic block 2874``%bT``. Otherwise control flows to basic block ``%bF``. 2875 2876**Constraints**:: 2877 2878 AA == AbbrevIndex(A) & 2879 CC == RelativeIndex(C) & 2880 B == NumBasicBlocks + 1 & 2881 0 < T & 2882 B1 < ExpectedBasicBlocks & 2883 0 < F & 2884 B2 < ExpectedBasicBlocks & 2885 TypeOf(C) == i1 2886 2887**Updates**:: 2888 2889 ++NumBasicBlocks; 2890 2891**Examples**:: 2892 2893 92:0| 1: <65535, 12, 2> | function void @f0() { 2894 | | // BlockID = 12 2895 100:0| 3: <1, 5> | blocks 5; 2896 102:4| 1: <65535, 11, 2> | constants { // BlockID = 11 2897 112:0| 3: <1, 1> | i1: 2898 114:4| 3: <4, 3> | %c0 = i1 1; 2899 117:0| 3: <4, 0> | %c1 = i1 0; 2900 119:4| 0: <65534> | } 2901 | | %b0: 2902 120:0| 3: <11, 3> | br label %b3; 2903 | | %b1: 2904 122:4| 3: <11, 2, 4, 2> | br i1 %c0, label %b2, label %b4; 2905 | | %b2: 2906 126:4| 3: <11, 3> | br label %b3; 2907 | | %b3: 2908 129:0| 3: <10> | ret void; 2909 | | %b4: 2910 130:6| 3: <11, 2, 3, 1> | br i1 %c1, label %b2, label %b3; 2911 134:6| 0: <65534> | } 2912 2913Unreachable 2914----------- 2915 2916The unreachable instruction has no defined semantics. The instruction is used to 2917inform the :ref:`PNaCl translator<link_for_pnacl_translator>` that control 2918can't reach this instruction. 2919 2920**Syntax**:: 2921 2922 unreachable; <A> 2923 %bB: 2924 2925**Record**:: 2926 2927 AA: <15> 2928 2929**Semantics**: 2930 2931Directive to the :ref:`PNaCl translator<link_for_pnacl_translator>` that 2932this instruction is unreachable. 2933 2934**Constraints**:: 2935 2936 AA == AbbrevIndex(A) 2937 B == NumBasicBlocks + 1 & 2938 2939**Updates**:: 2940 2941 ++NumBasicBlocks; 2942 2943**Examples**:: 2944 2945 108:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { 2946 | | // BlockID = 12 2947 116:0| 3: <1, 5> | blocks 5; 2948 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 2949 128:0| 3: <1, 2> | i1: 2950 130:4| 3: <4, 3> | %c0 = i1 1; 2951 133:0| 3: <4, 0> | %c1 = i1 0; 2952 135:4| 0: <65534> | } 2953 | | %b0: 2954 136:0| 3: <11, 1, 2, 2> | br i1 %c0, label %b1, label %b2; 2955 | | %b1: 2956 140:0| 3: <11, 3, 4, 1> | br i1 %c1, label %b3, label %b4; 2957 | | %b2: 2958 144:0| 3: <15> | unreachable; 2959 | | %b3: 2960 145:6| 3: <15> | unreachable; 2961 | | %b4: 2962 147:4| 3: <10> | ret void; 2963 149:2| 0: <65534> | } 2964 2965Switch Instruction 2966------------------ 2967 2968The *switch* instruction transfers control flow to one of several different 2969places, based on a selector value. It is a generalization of the conditional 2970branch instruction. 2971 2972**Syntax**:: 2973 2974 switch T V0 { 2975 default: br label %bB0; 2976 T V1: br label %bB1; 2977 ... 2978 T VN: br label %bBN; 2979 } <A> 2980 %bB: 2981 2982**Record**:: 2983 2984 AA: <12, TT, B0, N, (1, 1, VVI, BI | 1 <= i <= N)> 2985 2986**Semantics**: 2987 2988The switch instruction transfers control to a basic block in ``B0`` through 2989``BN``. Value ``V`` is used to conditionally select which block to branch 2990to. ``T`` is the type of ``V`` and ``V1`` through ``VN``, and must be an integer 2991type. Value ``V1`` through ``VN`` are integers to compare against ``V``. If 2992selector ``V`` matches ``VI`` (for some ``I``, ``1 <= I <= N``), then the 2993instruction branches to block ``BI``. If ``V`` is not in ``V1`` through ``VN``, 2994the instruction branches to block ``B0``. 2995 2996**Constraints**:: 2997 2998 AA == AbbrevIndex(A) & 2999 B == NumBasicBlocks + 1 & 3000 TT == TypeID(T) & 3001 VI == SignRotate(VI) for all I, 1 <= I <= N & 3002 3003**Updates**:: 3004 3005 ++NumBasicBlocks; 3006 3007**Examples**:: 3008 3009 116:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { 3010 | | // BlockID = 12 3011 124:0| 3: <1, 6> | blocks 6; 3012 | | %b0: 3013 126:4| 3: <12, 1, 1, 2, 4, 1, 1,| switch i32 %p0 { 3014 | 2, 3, 1, 1, 4, 3, 1, | default: br label %b2; 3015 | 1, 8, 4, 1, 1, 10, 4>| i32 1: br label %b3; 3016 | | i32 2: br label %b3; 3017 | | i32 4: br label %b4; 3018 | | i32 5: br label %b4; 3019 | | } 3020 | | %b1: 3021 143:2| 3: <11, 5> | br label %b5; 3022 | | %b2: 3023 145:6| 3: <11, 5> | br label %b5; 3024 | | %b3: 3025 148:2| 3: <11, 5> | br label %b5; 3026 | | %b4: 3027 150:6| 3: <11, 5> | br label %b5; 3028 | | %b5: 3029 153:2| 3: <10> | ret void; 3030 155:0| 0: <65534> | } 3031 156:0| 1: <65535, 12, 2> | function void @f1(i64 %p0) { 3032 | | // BlockID = 12 3033 164:0| 3: <1, 6> | blocks 6; 3034 | | %b0: 3035 166:4| 3: <12, 2, 1, 2, 4, 1, 1,| switch i64 %p0 { 3036 | 2, 3, 1, 1, 4, 3, 1, | default: br label %b2; 3037 | 1, 8, 4, 1, 1, | i64 1: br label %b3; 3038 | 39777555332, 4> | i64 2: br label %b3; 3039 | | i64 4: br label %b4; 3040 | | i64 19888777666: br label %b4; 3041 | | } 3042 | | %b1: 3043 188:4| 3: <11, 5> | br label %b5; 3044 | | %b2: 3045 191:0| 3: <11, 5> | br label %b5; 3046 | | %b3: 3047 193:4| 3: <11, 5> | br label %b5; 3048 | | %b4: 3049 196:0| 3: <11, 5> | br label %b5; 3050 | | %b5: 3051 198:4| 3: <10> | ret void; 3052 200:2| 0: <65534> | } 3053 3054.. _link_for_integer_binary_instructions: 3055 3056Integer Binary Instructions 3057=========================== 3058 3059Binary instructions are used to do most of the computation in a program. This 3060section focuses on binary instructions that operator on integer values, or 3061vectors of integer values. 3062 3063All binary operations require two operands of the same type, execute an 3064operation on them, and produce a value. The value may represent multiple values 3065if the type is a vector type. The result value always has the same type as its 3066operands. 3067 3068Some integer binary operations can be applied to both signed and unsigned 3069integers. Others, the sign is significant. In general, if the sign plays a role 3070in the instruction, the sign information is encoded into the name of the 3071instruction. 3072 3073For most binary operations (except some of the logical operations), integer 3074type i1 is disallowed. 3075 3076Integer Add 3077----------- 3078 3079The integer add instruction returns the sum of its two arguments. Both arguments 3080and the result must be of the same type. That type must be integer, or an 3081integer vector type. 3082 3083**Syntax**:: 3084 3085 %vN = add T V1, V2; <A> 3086 3087**Record**:: 3088 3089 AA: <2, VV1, VV2, 0> 3090 3091**Semantics**: 3092 3093The integer add instruction returns the sum of its two arguments. Arguments 3094``V1`` and ``V2``, and the result ``%vN``, must be of type ``T``. ``T`` must be 3095an integer type, or an integer vector type. ``N`` is defined by the record 3096position, defining the corresponding value generated by the instruction. 3097 3098The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` 3099is the bit width of the integer result. 3100 3101Because integers are assumed to use a two's complement representation, 3102this instruction is appropriate for both signed and unsigned integers. 3103 3104In the add instruction, integer type ``i1`` (and a vector of integer type 3105``i1``) is disallowed. 3106 3107**Constraints**:: 3108 3109 AA == AbbrevIndex(A) & 3110 VV1 == RelativeIndex(V1) & 3111 VV2 == RelativeIndex(V2) & 3112 T == TypeOf(V1) == TypeOf(V2) & 3113 IsInteger(UnderlyingType(T)) & 3114 UnderlyingType(T) != i1 & 3115 N == NumValuedInsts 3116 3117**Updates**:: 3118 3119 ++NumValuedInsts; 3120 TypeOf(%vN) = T 3121 3122**Examples**:: 3123 3124 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3125 | | // BlockID = 12 3126 104:0| 3: <1, 1> | blocks 1; 3127 | | %b0: 3128 106:4| 3: <2, 2, 1, 0> | %v0 = add i32 %p0, %p1; 3129 110:4| 3: <2, 3, 1, 0> | %v1 = add i32 %p0, %v0; 3130 114:4| 3: <10, 1> | ret i32 %v1; 3131 117:0| 0: <65534> | } 3132 3133Integer Subtract 3134---------------- 3135 3136The integer subtract instruction returns the difference of its two arguments. 3137Both arguments and the result must be of the same type. That type must be 3138integer, or an integer vector type. 3139 3140Note: Since there isn't a negate instruction, subtraction from constant zero 3141should be used to negate values. 3142 3143**Syntax**:: 3144 3145 %vN = sub T V1, V2; <A> 3146 3147**Record**:: 3148 3149 AA: <2, VV1, VV2, 1> 3150 3151**Semantics**: 3152 3153The integer subtract returns the difference of its two arguments. Arguments 3154``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` must be 3155an integer type, or an integer vector type. ``N`` is defined by the record 3156position, defining the corresponding value generated by the instruction. 3157 3158The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` 3159is the bit width of the integer result. 3160 3161Because integers are assumed to use a two's complement representation, 3162this instruction is appropriate for both signed and unsigned integers. 3163 3164In the subtract instruction, integer type ``i1`` (and a vector of integer type 3165``i1``) is disallowed. 3166 3167**Constraints**:: 3168 3169 AA == AbbrevIndex(A) & 3170 VV1 == RelativeIndex(V1) & 3171 VV2 == RelativeIndex(V2) & 3172 T == TypeOf(V1) == TypeOf(V2) & 3173 IsInteger(UnderlyingType(T)) & 3174 UnderlyingType(T) != i1 & 3175 N == NumValuedInsts 3176 3177**Updates**:: 3178 3179 ++NumValuedInsts; 3180 TypeOf(%vN) = T 3181 3182**Examples**:: 3183 3184 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3185 | | // BlockID = 12 3186 104:0| 3: <1, 1> | blocks 1; 3187 | | %b0: 3188 106:4| 3: <2, 2, 1, 1> | %v0 = sub i32 %p0, %p1; 3189 110:4| 3: <2, 3, 1, 1> | %v1 = sub i32 %p0, %v0; 3190 114:4| 3: <10, 1> | ret i32 %v1; 3191 117:0| 0: <65534> | } 3192 3193Integer Multiply 3194---------------- 3195 3196The integer multiply instruction returns the product of its two arguments. Both 3197arguments and the result must be of the same type. That type must be integer, 3198or an integer based vector type. 3199 3200**Syntax**:: 3201 3202 &vN = mul T V1, V2; <A> 3203 3204**Record**:: 3205 3206 AA: <2, VV1, VV2, 2> 3207 3208**Semantics**: 3209 3210The integer multiply instruction returns the product of its two 3211arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type 3212``T``. ``T`` must be an integer type, or an integer vector type. ``N`` is 3213defined by the record position, defining the corresponding value generated by 3214the instruction. 3215 3216The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` 3217is the bit width of the integer result. 3218 3219Because integers are assumed to use a two's complement representation, 3220this instruction is appropriate for both signed and unsigned integers. 3221 3222In the subtract instruction, integer type ``i1`` (or a vector on integer type 3223``i1``) is disallowed. 3224 3225**Constraints**:: 3226 3227 AA == AbbrevIndex(A) & 3228 VV1 == RelativeIndex(V1) & 3229 VV2 == RelativeIndex(V2) & 3230 T == TypeOf(V1) == TypeOf(V2) & 3231 IsInteger(UnderlyingType(T)) & 3232 UnderlyingType(T) != i1 & 3233 N == NumValuedInsts 3234 3235**Updates**:: 3236 3237 ++NumValuedInsts; 3238 TypeOf(%vN) = T 3239 3240**Examples**:: 3241 3242 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3243 | | // BlockID = 12 3244 104:0| 3: <1, 1> | blocks 1; 3245 | | %b0: 3246 106:4| 3: <2, 2, 1, 2> | %v0 = mul i32 %p0, %p1; 3247 110:4| 3: <2, 1, 3, 2> | %v1 = mul i32 %v0, %p0; 3248 114:4| 3: <10, 1> | ret i32 %v1; 3249 117:0| 0: <65534> | } 3250 3251Signed Integer Divide 3252--------------------- 3253 3254The signed integer divide instruction returns the quotient of its two arguments. 3255Both arguments and the result must be of the same type. That type must be 3256integer, or an integer vector type. 3257 3258**Syntax**:: 3259 3260 %vN = sdiv T V1, V2; <A> 3261 3262**Record**:: 3263 3264 AA: <2, VV1, VV2, 4> 3265 3266**Semantics**: 3267 3268The signed integer divide instruction returns the quotient of its two 3269arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type 3270``T``. ``T`` must be a integer type, or an integer vector type. ``N`` is defined 3271by the record position, defining the corresponding value generated by the 3272instruction. 3273 3274Signed values are assumed. Note that signed and unsigned integer division are 3275distinct operations. For unsigned integer division use the unsigned integer 3276divide instruction (udiv). 3277 3278In the signed integer divide instruction, integer type ``i1`` (and a vector of 3279integer type ``i1``) is disallowed. Integer division by zero is guaranteed to 3280trap. 3281 3282Note that overflow can happen with this instruction when dividing the maximum 3283negative integer by ``-1``. The behavior for this case is currently undefined. 3284 3285**Constraints**:: 3286 3287 AA == AbbrevIndex(A) & 3288 VV1 == RelativeIndex(V1) & 3289 VV2 == RelativeIndex(V2) & 3290 T == TypeOf(V1) == TypeOf(V2) & 3291 IsInteger(UnderlyingType(T)) & 3292 UnderlyingType(T) != i1 & 3293 N == NumValuedInsts 3294 3295**Updates**:: 3296 3297 ++NumValuedInsts; 3298 TypeOf(%vN) = T 3299 3300**Examples**:: 3301 3302 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3303 | | // BlockID = 12 3304 104:0| 3: <1, 1> | blocks 1; 3305 | | %b0: 3306 106:4| 3: <2, 2, 1, 4> | %v0 = sdiv i32 %p0, %p1; 3307 110:4| 3: <2, 1, 2, 4> | %v1 = sdiv i32 %v0, %p1; 3308 114:4| 3: <10, 1> | ret i32 %v1; 3309 117:0| 0: <65534> | } 3310 3311Unsigned Integer Divide 3312----------------------- 3313 3314The unsigned integer divide instruction returns the quotient of its two 3315arguments. Both the arguments and the result must be of the same type. That type 3316must be integer, or an integer vector type. 3317 3318**Syntax**:: 3319 3320 %vN = udiv T V1, V2; <a> 3321 3322**Record**:: 3323 3324 AA: <2, A1, A2, 3> 3325 3326**Semantics**: 3327 3328The unsigned integer divide instruction returns the quotient of its two 3329arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type 3330``T``. ``T`` must be an integer type, or an integer vector type. ``N`` is 3331defined by the record position, defining the corresponding value generated by 3332the instruction. 3333 3334Unsigned integer values are assumed. Note that signed and unsigned integer 3335division are distinct operations. For signed integer division use the signed 3336integer divide instruction (sdiv). 3337 3338In the unsigned integer divide instruction, integer type ``i1`` (and a vector of 3339integer type ``i1``) is disallowed. Division by zero is guaranteed to trap. 3340 3341**Constraints**:: 3342 3343 AA == AbbrevIndex(A) & 3344 VV1 == RelativeIndex(V1) & 3345 VV2 == RelativeIndex(V2) & 3346 T == TypeOf(V1) == TypeOf(V2) & 3347 IsInteger(UnderlyingType(T)) & 3348 UnderlyingType(T) != i1 & 3349 N == NumValuedInsts 3350 3351**Updates**:: 3352 3353 ++NumValuedInsts; 3354 TypeOf(%vN) = T 3355 3356**Examples**:: 3357 3358 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3359 | | // BlockID = 12 3360 104:0| 3: <1, 1> | blocks 1; 3361 | | %b0: 3362 106:4| 3: <2, 2, 1, 3> | %v0 = udiv i32 %p0, %p1; 3363 110:4| 3: <2, 1, 2, 3> | %v1 = udiv i32 %v0, %p1; 3364 114:4| 3: <10, 1> | ret i32 %v1; 3365 117:0| 0: <65534> | } 3366 3367Signed Integer Remainder 3368------------------------ 3369 3370The signed integer remainder instruction returns the remainder of the quotient 3371of its two arguments. Both arguments and the result must be of the same 3372type. That type must be integer, or an integer based vector type. 3373 3374**Syntax**:: 3375 3376 %vN = srem T V1, V2; <A> 3377 3378**Record**:: 3379 3380 AA: <2, VV1, VV2, 6> 3381 3382**Semantics**: 3383 3384The signed integer remainder instruction returns the remainder of the quotient 3385of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must 3386be of type ``T``. ``T`` must be a integer type, or an integer vector type. ``N`` 3387is defined by the record position, defining the corresponding value generated by 3388the instruction. 3389 3390Signed values are assumed. Note that signed and unsigned integer division are 3391distinct operations. For unsigned integer division use the unsigned integer 3392remainder instruction (urem). 3393 3394In the signed integer remainder instruction, integer type ``i1`` (and a vector 3395of integer type ``i1``) is disallowed. Division by zero is guaranteed to trap. 3396 3397Note that overflow can happen with this instruction when dividing the maximum 3398negative integer by ``-1``. The behavior for this case is currently undefined. 3399 3400**Constraints**:: 3401 3402 AA == AbbrevIndex(A) & 3403 VV1 == RelativeIndex(V1) & 3404 VV2 == RelativeIndex(V2) & 3405 T == TypeOf(V1) == TypeOf(V2) & 3406 IsInteger(UnderlyingType(T)) & 3407 UnderlyingType(T) != i1 & 3408 N == NumValuedInsts 3409 3410**Updates**:: 3411 3412 ++NumValuedInsts; 3413 TypeOf(%vN) = T 3414 3415**Examples**:: 3416 3417 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3418 | | // BlockID = 12 3419 104:0| 3: <1, 1> | blocks 1; 3420 | | %b0: 3421 106:4| 3: <2, 2, 1, 6> | %v0 = srem i32 %p0, %p1; 3422 110:4| 3: <2, 1, 2, 6> | %v1 = srem i32 %v0, %p1; 3423 114:4| 3: <10, 1> | ret i32 %v1; 3424 117:0| 0: <65534> | } 3425 3426Unsigned Integer Remainder Instruction 3427-------------------------------------- 3428 3429The unsigned integer remainder instruction returns the remainder of the quotient 3430of its two arguments. Both the arguments and the result must be of the same 3431type. The type must be integer, or an integer vector type. 3432 3433**Syntax**:: 3434 3435 %vN = urem T V1, V2; <A> 3436 3437**Record**:: 3438 3439 AA: <2, A1, A2, 5> 3440 3441**Semantics**: 3442 3443The unsigned integer remainder instruction returns the remainder of the quotient 3444of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must 3445be of type ``T``. ``T`` must be an integer type, or an integer vector type. 3446``N`` is defined by the record position, defining the corresponding value 3447generated by the instruction. 3448 3449Unsigned values are assumed. Note that signed and unsigned integer division are 3450distinct operations. For signed integer division use the remainder instruction 3451(srem). 3452 3453In the unsigned integer remainder instruction, integer type ``i1`` (and a vector 3454of integer type ``i1``) is disallowed. Division by zero is guaranteed to trap. 3455 3456**Constraints**:: 3457 3458 AA == AbbrevIndex(A) & 3459 VV1 == RelativeIndex(V1) & 3460 VV2 == RelativeIndex(V2) & 3461 T == TypeOf(V1) == TypeOf(V2) & 3462 IsInteger(UnderlyingType(T)) & 3463 UnderlyingType(T) != i1 & 3464 N == NumValuedInsts 3465 3466**Updates**:: 3467 3468 ++NumValuedInsts; 3469 TypeOf(%vN) = T 3470 3471**Examples**:: 3472 3473 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3474 | | // BlockID = 12 3475 104:0| 3: <1, 1> | blocks 1; 3476 | | %b0: 3477 106:4| 3: <2, 2, 1, 5> | %v0 = urem i32 %p0, %p1; 3478 110:4| 3: <2, 1, 2, 5> | %v1 = urem i32 %v0, %p1; 3479 114:4| 3: <10, 1> | ret i32 %v1; 3480 117:0| 0: <65534> | } 3481 3482Shift Left 3483---------- 3484 3485The (integer) shift left instruction returns the first operand, shifted to the 3486left a specified number of bits with zero fill. The shifted value must be 3487integer, or an integer vector type. 3488 3489**Syntax**:: 3490 3491 %vN = shl T V1, V2; <A> 3492 3493**Record**:: 3494 3495 AA: <2, VV1, VV2, 7> 3496 3497**Semantics**: 3498 3499This instruction performs a shift left operation. Arguments ``V1`` and ``V2`` 3500and the result ``%vN`` must be of type ``T``. ``T`` must be an integer, or a 3501vector of integers. ``N`` is defined by the record position, defining the 3502corresponding value generated by the instruction. 3503 3504``V2`` is assumed to be unsigned. The least significant bits of the result will 3505be filled with zero bits after the shift. If ``V2`` is (statically or 3506dynamically) negative or equal to or larger than the number of bits in 3507``V1``, the result is undefined. If the arguments are vectors, each vector 3508element of ``V1`` is shifted by the corresponding shift amount in ``V2``. 3509 3510In the shift left instruction, integer type ``i1`` (and a vector of integer type 3511``i1``) is disallowed. 3512 3513**Constraints**:: 3514 3515 AA == AbbrevIndex(A) & 3516 VV1 == RelativeIndex(V1) & 3517 VV2 == RelativeIndex(V2) & 3518 T == TypeOf(V1) == TypeOf(V2) & 3519 IsInteger(UnderlyingType(T)) & 3520 UnderlyingType(T) != i1 & 3521 N == NumValuedInsts 3522 3523**Updates**:: 3524 3525 ++NumValuedInsts; 3526 TypeOf(%vN) = T 3527 3528**Examples**:: 3529 3530 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3531 | | // BlockID = 12 3532 104:0| 3: <1, 1> | blocks 1; 3533 | | %b0: 3534 106:4| 3: <2, 2, 1, 7> | %v0 = shl i32 %p0, %p1; 3535 110:4| 3: <2, 1, 2, 7> | %v1 = shl i32 %v0, %p1; 3536 114:4| 3: <10, 1> | ret i32 %v1; 3537 117:0| 0: <65534> | } 3538 3539Logical Shift Right 3540------------------- 3541 3542The logical shift right instruction returns the first operand, shifted to the 3543right a specified number of bits with zero fill. 3544 3545**Syntax**:: 3546 3547 %vN = lshr T V1, V2; <A> 3548 3549**Record**:: 3550 3551 AA: <2, VV1, VV2, 8> 3552 3553**Semantics**: 3554 3555This instruction performs a logical shift right operation. Arguments ``V1`` and 3556``V2`` and the result ``%vN`` must be of type ``T``. ``T`` must be an integer, 3557or a vector of integers. ``N`` is defined by the record position, defining the 3558corresponding value generated by the instruction. 3559 3560``V2`` is assumed to be unsigned. The most significant bits of the result will 3561be filled with zero bits after the shift. If ``V2`` is (statically or 3562dynamically) negative or equal to or larger than the number of bits in ``V1``, 3563the result is undefined. If the arguments are vectors, each vector element of 3564``V1`` is shifted by the corresponding shift amount in ``V2``. 3565 3566In the logical shift right instruction, integer type ``i1`` (and a vector of 3567integer type ``i1``) is disallowed. 3568 3569**Constraints**:: 3570 3571 AA == AbbrevIndex(A) & 3572 VV1 == RelativeIndex(V1) & 3573 VV2 == RelativeIndex(V2) & 3574 T == TypeOf(V1) == TypeOf(V2) & 3575 IsInteger(UnderlyingType(T)) & 3576 UnderlyingType(T) != i1 & 3577 N == NumValuedInsts 3578 3579**Updates**:: 3580 3581 ++NumValuedInsts; 3582 TypeOf(%vN) = T 3583 3584**Examples**:: 3585 3586 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3587 | | // BlockID = 12 3588 104:0| 3: <1, 1> | blocks 1; 3589 | | %b0: 3590 106:4| 3: <2, 2, 1, 8> | %v0 = lshr i32 %p0, %p1; 3591 110:4| 3: <2, 1, 2, 8> | %v1 = lshr i32 %v0, %p1; 3592 114:4| 3: <10, 1> | ret i32 %v1; 3593 117:0| 0: <65534> | } 3594 3595Arithmetic Shift Right 3596---------------------- 3597 3598The arithmetic shift right instruction returns the first operand, shifted to the 3599right a specified number of bits with sign extension. 3600 3601**Syntax**:: 3602 3603 %vN = ashr T V1, V2; <A> 3604 3605**Record**:: 3606 3607 AA: <2, VV1, VVA2, 9> 3608 3609**Semantics**: 3610 3611This instruction performs an arithmetic shift right operation. Arguments ``V1`` 3612and ``V2`` and and the result ``%vN`` must be of type ``T``. ``T`` must be an 3613integer, or a vector of integers. ``N`` is defined by the record position, 3614defining the corresponding value generated by the instruction. 3615 3616``V2`` is assumed to be unsigned. The most significant bits of the result will 3617be filled with the sign bit of ``V1``. If ``V2`` is (statically or dynamically) 3618negative or equal to or larger than the number of bits in ``V1``, the result is 3619undefined. If the arguments are vectors, each vector element of ``V1`` is 3620shifted by the corresponding shift amount in ``V2``. 3621 3622In the arithmetic shift right instruction, integer type ``i1`` (and a vector of 3623integral type ``i1``) is disallowed. 3624 3625**Constraints**:: 3626 3627 AA == AbbrevIndex(A) & 3628 VV1 == RelativeIndex(V1) & 3629 VV2 == RelativeIndex(V2) & 3630 T == TypeOf(V1) == TypeOf(V2) & 3631 IsInteger(UnderlyingType(T)) & 3632 UnderlyingType(T) != i1 & 3633 N == NumValuedInsts 3634 3635**Updates**:: 3636 3637 ++NumValuedInsts; 3638 TypeOf(%vN) = T 3639 3640**Examples**:: 3641 3642 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3643 | | // BlockID = 12 3644 104:0| 3: <1, 1> | blocks 1; 3645 | | %b0: 3646 106:4| 3: <2, 2, 1, 9> | %v0 = ashr i32 %p0, %p1; 3647 110:4| 3: <2, 1, 2, 9> | %v1 = ashr i32 %v0, %p1; 3648 114:4| 3: <10, 1> | ret i32 %v1; 3649 117:0| 0: <65534> | } 3650 3651Logical And 3652----------- 3653 3654The *and* instruction returns the bitwise logical and of its two operands. 3655 3656**Syntax**:: 3657 3658 %vN = and T V1, V2; <A> 3659 3660**Record**:: 3661 3662 AA: <2, VV1, VV2, 10> 3663 3664**Semantics**: 3665 3666This instruction performs a bitwise logical and of its arguments. Arguments 3667``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` must be 3668an integer, or a vector of integers. ``N`` is defined by the record position, 3669defining the corresponding value generated by the instruction. ``A`` is the 3670(optional) abbreviation associated with the corresponding record. 3671 3672The truth table used for the *and* instruction is: 3673 3674===== ===== ====== 3675Arg 1 Arg 2 Result 3676===== ===== ====== 36770 0 0 36780 1 0 36791 0 0 36801 1 1 3681===== ===== ====== 3682 3683**Constraints**:: 3684 3685 AA == AbbrevIndex(A) & 3686 VV1 == RelativeIndex(V1) & 3687 VV2 == RelativeIndex(V2) & 3688 T == TypeOf(V1) == TypeOf(V2) & 3689 IsInteger(UnderlyingType(T))) & 3690 N == NumValuedInsts 3691 3692**Updates**:: 3693 3694 ++NumValuedInsts; 3695 TypeOf(%vN) = T 3696 3697**Examples**:: 3698 3699 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3700 | | // BlockID = 12 3701 104:0| 3: <1, 1> | blocks 1; 3702 | | %b0: 3703 106:4| 3: <2, 2, 1, 10> | %v0 = and i32 %p0, %p1; 3704 110:4| 3: <2, 1, 2, 10> | %v1 = and i32 %v0, %p1; 3705 114:4| 3: <10, 1> | ret i32 %v1; 3706 117:0| 0: <65534> | } 3707 3708Logical Or 3709---------- 3710 3711The *or* instruction returns the bitwise logical inclusive or of its 3712two operands. 3713 3714**Syntax**:: 3715 3716 %vN = or T V1, V2; <A> 3717 3718**Record**:: 3719 3720 AA: <2, VV1, VV2, 11> 3721 3722**Semantics**: 3723 3724This instruction performs a bitwise logical inclusive or of its arguments. 3725Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` 3726must be an integer, or a vector of integers. ``N`` is defined by the record 3727position, defining the corresponding value generated by the instruction. 3728 3729The truth table used for the *or* instruction is: 3730 3731===== ===== ====== 3732Arg 1 Arg 2 Result 3733===== ===== ====== 37340 0 0 37350 1 1 37361 0 1 37371 1 1 3738===== ===== ====== 3739 3740**Constraints**:: 3741 3742 AA == AbbrevIndex(A) & 3743 VV1 == RelativeIndex(V1) & 3744 VV2 == RelativeIndex(V2) & 3745 T == TypeOf(V1) == TypeOf(V2) & 3746 IsInteger(UnderlyingType(T))) & 3747 N == NumValuedInsts 3748 3749**Updates**:: 3750 3751 ++NumValuedInsts; 3752 TypeOf(%vN) = T 3753 3754**Examples**:: 3755 3756 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3757 | | // BlockID = 12 3758 104:0| 3: <1, 1> | blocks 1; 3759 | | %b0: 3760 106:4| 3: <2, 2, 1, 11> | %v0 = or i32 %p0, %p1; 3761 110:4| 3: <2, 1, 2, 11> | %v1 = or i32 %v0, %p1; 3762 114:4| 3: <10, 1> | ret i32 %v1; 3763 117:0| 0: <65534> | } 3764 3765Logical Xor 3766----------- 3767 3768The *xor* instruction returns the bitwise logical exclusive or of its 3769two operands. 3770 3771**Syntax**:: 3772 3773 %vN = xor T V1, V2; <A> 3774 3775**Record**:: 3776 3777 AA: <2, VV1, VV2, 12> 3778 3779**Semantics**: 3780 3781This instruction performs a bitwise logical exclusive or of its arguments. 3782Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` 3783must be an integer, or a vector of integers. ``N`` is defined by the record 3784position, defining the corresponding value generated by the instruction. 3785 3786The truth table used for the *xor* instruction is: 3787 3788===== ===== ====== 3789Arg 1 Arg 2 Result 3790===== ===== ====== 37910 0 0 37920 1 1 37931 0 1 37941 1 0 3795===== ===== ====== 3796 3797**Constraints**:: 3798 3799 AA == AbbrevIndex(A) & 3800 A1 == RelativeIndex(V1) & 3801 A2 == RelativeIndex(V2) & 3802 T == TypeOf(V1) == TypeOf(V2) & 3803 IsInteger(UnderlyingType(T))) & 3804 N == NumValuedInsts 3805 3806**Updates**:: 3807 3808 ++NumValuedInsts; 3809 TypeOf(%vN) = T 3810 3811**Examples**:: 3812 3813 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 3814 | | // BlockID = 12 3815 104:0| 3: <1, 1> | blocks 1; 3816 | | %b0: 3817 106:4| 3: <2, 2, 1, 12> | %v0 = xor i32 %p0, %p1; 3818 110:4| 3: <2, 1, 2, 12> | %v1 = xor i32 %v0, %p1; 3819 114:4| 3: <10, 1> | ret i32 %v1; 3820 117:0| 0: <65534> | } 3821 3822.. _link_for_floating_point_binary_instructions: 3823 3824Floating Point Binary Instructions 3825================================== 3826 3827Floating point binary instructions require two operands of the same type, 3828execute an operation on them, and produce a value. The value may represent 3829multiple values if the type is a vector type. The result value always has the 3830same type as its operands. 3831 3832Floating Point Add 3833------------------ 3834 3835The floating point add instruction returns the sum of its two arguments. Both 3836arguments and the result must be of the same type. That type must be a floating 3837point type, or a vector of a floating point type. 3838 3839**Syntax**:: 3840 3841 %vN = fadd T V1, V2; <A> 3842 3843**Record**:: 3844 3845 AA: <2, VV1, VV2, 0> 3846 3847**Semantics**: 3848 3849The floating point add instruction returns the sum of its two arguments. 3850Arguments ``V1`` and ``V2`` and the result ``%vN`` must be of type ``T``. ``T`` 3851must be a floating point type, or a vector of a floating point type. ``N`` is 3852defined by the record position, defining the corresponding value generated by 3853the instruction. 3854 3855**Constraints**:: 3856 3857 AA == AbbrevIndex(A) & 3858 VV1 == RelativeIndex(V1) & 3859 VV2 == RelativeIndex(V2) & 3860 T == TypeOf(V1) == TypeOf(V2) & 3861 IsFloat(UnderlyingType(T)) & 3862 N == NumValuedInsts 3863 3864**Updates**:: 3865 3866 ++NumValuedInsts; 3867 TypeOf(%vN) = T 3868 3869**Examples**:: 3870 3871 92:0| 1: <65535, 12, 2> | function 3872 | | float @f0(float %p0, float %p1) { 3873 | | // BlockID = 12 3874 100:0| 3: <1, 1> | blocks 1; 3875 | | %b0: 3876 102:4| 3: <2, 2, 1, 0> | %v0 = fadd float %p0, %p1; 3877 106:4| 3: <2, 3, 1, 0> | %v1 = fadd float %p0, %v0; 3878 110:4| 3: <10, 1> | ret float %v1; 3879 113:0| 0: <65534> | } 3880 3881Floating Point Subtract 3882----------------------- 3883 3884The floating point subtract instruction returns the difference of its two 3885arguments. Both arguments and the result must be of the same type. That type 3886must be a floating point type, or a vector of a floating point type. 3887 3888**Syntax**:: 3889 3890 %vN = fsub T V1, V2; <a> 3891 3892**Record**:: 3893 3894 AA: <2, VV1, VV2, 1> 3895 3896**Semantics**: 3897 3898The floating point subtract instruction returns the difference of its two 3899arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type 3900``T``. ``T`` must be a floating point type, or a vector of a floating point 3901type. ``N`` is defined by the record position, defining the corresponding value 3902generated by the instruction. 3903 3904**Constraints**:: 3905 3906 AA == AbbrevIndex(A) & 3907 VV1 == RelativeIndex(V1) & 3908 VV2 == RelativeIndex(V2) & 3909 T == TypeOf(V1) == TypeOf(V2) & 3910 IsFloat(UnderlyingType(T)) & 3911 N == NumValuedInsts 3912 3913**Updates**:: 3914 3915 ++NumValuedInsts; 3916 TypeOf(%vN) = T 3917 3918**Examples**:: 3919 3920 92:0| 1: <65535, 12, 2> | function 3921 | | float @f0(float %p0, float %p1) { 3922 | | // BlockID = 12 3923 100:0| 3: <1, 1> | blocks 1; 3924 | | %b0: 3925 102:4| 3: <2, 2, 1, 1> | %v0 = fsub float %p0, %p1; 3926 106:4| 3: <2, 3, 1, 1> | %v1 = fsub float %p0, %v0; 3927 110:4| 3: <10, 1> | ret float %v1; 3928 113:0| 0: <65534> | } 3929 3930Floating Point Multiply 3931----------------------- 3932 3933The floating point multiply instruction returns the product of its two 3934arguments. Both arguments and the result must be of the same type. That type 3935must be a floating point type, or a vector of a floating point type. 3936 3937**Syntax**:: 3938 3939 &vN = fmul T V1, V2; <A> 3940 3941**Record**:: 3942 3943 AA: <2, VV1, VV2, 2> 3944 3945**Semantics**: 3946 3947The floating point multiply instruction returns the product of its two 3948arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type 3949``T``. ``T`` must be a floating point type, or a vector of a floating point 3950type. ``N`` is defined by the record position, defining the corresponding value 3951generated by the instruction. 3952 3953**Constraints**:: 3954 3955 AA == AbbrevIndex(A) & 3956 VV1 == RelativeIndex(V1) & 3957 VV2 == RelativeIndex(V2) & 3958 T == TypeOf(V1) == TypeOf(V2) & 3959 IsFloat(UnderlyingType(T)) & 3960 N == NumValuedInsts 3961 3962**Updates**:: 3963 3964 ++NumValuedInsts; 3965 TypeOf(%vN) = T 3966 3967**Examples**:: 3968 3969 92:0| 1: <65535, 12, 2> | function 3970 | | float @f0(float %p0, float %p1) { 3971 | | // BlockID = 12 3972 100:0| 3: <1, 1> | blocks 1; 3973 | | %b0: 3974 102:4| 3: <2, 2, 1, 2> | %v0 = fmul float %p0, %p1; 3975 106:4| 3: <2, 3, 1, 2> | %v1 = fmul float %p0, %v0; 3976 110:4| 3: <10, 1> | ret float %v1; 3977 113:0| 0: <65534> | } 3978 3979Floating Point Divide 3980--------------------- 3981 3982The floating point divide instruction returns the quotient of its two 3983arguments. Both arguments and the result must be of the same type. That type 3984must be a floating point type, or a vector of a floating point type. 3985 3986**Syntax**:: 3987 3988 %vN = fdiv T V1, V2; <A> 3989 3990**Record**:: 3991 3992 AA: <2, V1, V2, 4> 3993 3994**Semantics**: 3995 3996The floating point divide instruction returns the quotient of its two 3997arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type 3998``T``. ``T`` must be a floating point type, or a vector of a floating point 3999type. ``N`` is defined by the record position, defining the corresponding value 4000generated by the instruction. 4001 4002**Constraints**:: 4003 4004 AA == AbbrevIndex(A) & 4005 VV1 == RelativeIndex(V1) & 4006 VV22 == RelativeIndex(V2) & 4007 T == TypeOf(V1) == TypeOf(V2) & 4008 IsFloat(UnderlyingType(T)) & 4009 N == NumValuedInsts 4010 4011**Updates**:: 4012 4013 ++NumValuedInsts; 4014 TypeOf(%vN) = T; 4015 4016**Examples**:: 4017 4018 92:0| 1: <65535, 12, 2> | function 4019 | | double 4020 | | @f0(double %p0, double %p1) { 4021 | | // BlockID = 12 4022 100:0| 3: <1, 1> | blocks 1; 4023 | | %b0: 4024 102:4| 3: <2, 2, 1, 4> | %v0 = fdiv double %p0, %p1; 4025 106:4| 3: <2, 3, 1, 4> | %v1 = fdiv double %p0, %v0; 4026 110:4| 3: <10, 1> | ret double %v1; 4027 113:0| 0: <65534> | } 4028 4029Floating Point Remainder 4030------------------------ 4031 4032The floating point remainder instruction returns the remainder of the quotient 4033of its two arguments. Both arguments and the result must be of the same 4034type. That type must be a floating point type, or a vector of a floating point 4035type. 4036 4037**Syntax**:: 4038 4039 %vN = frem T V1, V2; <A> 4040 4041**Record**:: 4042 4043 AA: <2, VV1, VV2, 6> 4044 4045**Semantics**: 4046 4047The floating point remainder instruction returns the remainder of the quotient 4048of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must 4049be of type ``T``. ``T`` must be a floating point type, or a vector of a floating 4050point type. ``N`` is defined by the record position, defining the corresponding 4051value generated by the instruction. 4052 4053**Constraints**:: 4054 4055 AA == AbbrevIndex(A) & 4056 VV1 == RelativeIndex(V1) & 4057 VV2 == RelativeIndex(V2) & 4058 T == TypeOf(V1) == TypeOf(V2) & 4059 IsFloat(UnderlyingType(T)) & 4060 N == NumValuedInsts 4061 4062**Updates**:: 4063 4064 ++NumValuedInsts; 4065 TypeOf(%vN) = T 4066 4067**Examples**:: 4068 4069 92:0| 1: <65535, 12, 2> | function 4070 | | double 4071 | | @f0(double %p0, double %p1) { 4072 | | // BlockID = 12 4073 100:0| 3: <1, 1> | blocks 1; 4074 | | %b0: 4075 102:4| 3: <2, 2, 1, 6> | %v0 = frem double %p0, %p1; 4076 106:4| 3: <2, 3, 1, 6> | %v1 = frem double %p0, %v0; 4077 110:4| 3: <10, 1> | ret double %v1; 4078 113:0| 0: <65534> | } 4079 4080.. _link_for_memory_creation_and_access_instructions: 4081 4082Memory Creation and Access Instructions 4083======================================= 4084 4085A key design point of SSA-based representation is how it represents 4086memory. In PNaCl bitcode files, no memory locations are in SSA 4087form. This makes things very simple. 4088 4089.. _link_for_alloca_instruction: 4090 4091Alloca Instruction 4092------------------ 4093 4094The *alloca* instruction allocates memory on the stack frame of the 4095currently executing function. This memory is automatically released 4096when the function returns to its caller. 4097 4098**Syntax**:: 4099 4100 %vN = alloca i8, i32 S, align V; <A> 4101 4102**Record**:: 4103 4104 AA: <19, SS, VV> 4105 4106**Semantics**: 4107 4108The *alloca* instruction allocates memory on the stack frame of the currently 4109executing function. The resulting value is a pointer to the allocated memory 4110(i.e. of type i32). ``S`` is the number of bytes that are allocated on the 4111stack. ``S`` must be of integer type i32. ``V`` is the alignment of the 4112generated stack address. 4113 4114Alignment must be a power of 2. See :ref:`memory blocks and 4115alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed 4116discussion on how to define alignment. 4117 4118**Constraints**:: 4119 4120 AA == AbbrevIndex(A) & 4121 VV == Log2(V+1) & 4122 SS == RelativeIndex(S) & 4123 i32 == TypeOf(S) & 4124 N == NumValuedInsts 4125 4126**Updates**:: 4127 4128 ++NumValuedInsts; 4129 TypeOf(%vN) = i32; 4130 4131**Examples**:: 4132 4133 112:0| 1: <65535, 12, 2> | function void @f1() { 4134 | | // BlockID = 12 4135 120:0| 3: <1, 1> | blocks 1; 4136 122:4| 1: <65535, 11, 2> | constants { // BlockID = 11 4137 132:0| 3: <1, 0> | i32: 4138 134:4| 3: <4, 4> | %c0 = i32 2; 4139 137:0| 3: <4, 8> | %c1 = i32 4; 4140 139:4| 3: <4, 16> | %c2 = i32 8; 4141 142:0| 0: <65534> | } 4142 | | %b0: 4143 144:0| 3: <19, 3, 1> | %v0 = alloca i8, i32 %c0, align 1; 4144 147:2| 3: <19, 3, 3> | %v1 = alloca i8, i32 %c1, align 4; 4145 150:4| 3: <19, 3, 4> | %v2 = alloca i8, i32 %c2, align 8; 4146 153:6| 3: <10> | ret void; 4147 155:4| 0: <65534> | } 4148 4149Load Instruction 4150---------------- 4151 4152The *load* instruction is used to read from memory. 4153 4154**Syntax**:: 4155 4156 %vN = load T* P, align V; <A> 4157 4158**Record**:: 4159 4160 AA: <20, PP, VV, TT> 4161 4162**Semantics**: 4163 4164The load instruction is used to read from memory. ``P`` is the identifier of the 4165memory address to read. The type of ``P`` must be an ``i32``. ``T`` is the type 4166of value to read. ``V`` is the alignment of the memory address. 4167 4168Type ``T`` must be a vector, integer, or floating point type. Both ``float`` and 4169``double`` types are allowed for floating point types. All integer types except 4170i1 are allowed. 4171 4172Alignment must be a power of 2. See :ref:`memory blocks and 4173alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed 4174discussion on how to define alignment. 4175 4176**Constraints**:: 4177 4178 AA == AbbrevIndex(A) & 4179 i32 == TypeOf(P) & 4180 PP == RelativeIndex(P) & 4181 VV == Log2(V+1) & 4182 %tTT == TypeID(T) & 4183 N == NumValuedInsts 4184 4185**Updates**:: 4186 4187 ++NumValuedInsts; 4188 TypeOf(%vN) = T; 4189 4190**Examples**:: 4191 4192 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4193 48:0| 3: <1, 4> | count 4; 4194 50:4| 3: <7, 32> | @t0 = i32; 4195 53:6| 3: <2> | @t1 = void; 4196 55:4| 3: <4> | @t2 = double; 4197 57:2| 3: <21, 0, 1, 0> | @t3 = void (i32); 4198 61:2| 0: <65534> | } 4199 ... 4200 96:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { 4201 | | // BlockID = 12 4202 104:0| 3: <1, 1> | blocks 1; 4203 | | %b0: 4204 106:4| 3: <20, 1, 1, 0> | %v0 = load i32* %p0, align 1; 4205 110:4| 3: <20, 1, 4, 2> | %v1 = load double* %v0, align 8; 4206 114:4| 3: <10> | ret void; 4207 116:2| 0: <65534> | } 4208 4209Store Instruction 4210----------------- 4211 4212The *store* instruction is used to write to memory. 4213 4214**Syntax**:: 4215 4216 store T S, T* P, align V; <A> 4217 4218**Record**:: 4219 4220 AA: <24, PP, SS, VV> 4221 4222**Semantics**: 4223 4224The store instruction is used to write to memory. ``P`` is the identifier of the 4225memory address to write to. The type of ``P`` must be an i32 integer. ``T`` is 4226the type of value to store. ``S`` is the value to store, and must be of type 4227``T``. ``V`` is the alignment of the memory address. ``A`` is the (optional) 4228abbreviation index associated with the record. 4229 4230Type ``T`` must be an integer or floating point type. Both ``float`` and 4231``double`` types are allowed for floating point types. All integer types except 4232i1 are allowed. 4233 4234Alignment must be a power of 2. See :ref:`memory blocks and 4235alignment<link_for_memory_Blocks_and_alignment_section>` for a more detailed 4236discussion on how to define alignment. 4237 4238**Constraints**:: 4239 4240 AA == AbbrevIndex(A) & 4241 i32 == TypeOf(P) & 4242 PP == RelativeIndex(P) & 4243 VV == Log2(V+1) 4244 4245**Examples**:: 4246 4247 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4248 48:0| 3: <1, 4> | count 4; 4249 50:4| 3: <7, 32> | @t0 = i32; 4250 53:6| 3: <2> | @t1 = void; 4251 55:4| 3: <4> | @t2 = double; 4252 57:2| 3: <21, 0, 1, 0, 0, 0, 2>| @t3 = void (i32, i32, i32, double); 4253 63:4| 0: <65534> | } 4254 ... 4255 96:0| 1: <65535, 12, 2> | function 4256 | | void 4257 | | @f0(i32 %p0, i32 %p1, i32 %p2, 4258 | | double %p3) { 4259 | | // BlockID = 12 4260 104:0| 3: <1, 1> | blocks 1; 4261 | | %b0: 4262 106:4| 3: <24, 4, 3, 1> | store i32 %p1, i32* %p0, align 1; 4263 110:4| 3: <24, 2, 1, 4> | store double %p3, double* %p2, 4264 | | align 8; 4265 114:4| 3: <10> | ret void; 4266 116:2| 0: <65534> | } 4267 4268.. _link_for_conversion_instructions: 4269 4270Conversion Instructions 4271======================= 4272 4273Conversion instructions all take a single operand and a type. The value is 4274converted to the corresponding type. 4275 4276Integer Truncating Instruction 4277------------------------------ 4278 4279The integer truncating instruction takes a value to truncate, and a type 4280defining the truncated type. Both types must be integer types, or integer 4281vectors with the same number of elements. The bit size of the value must be 4282larger than the bit size of the destination type. Equal sized types are not 4283allowed. 4284 4285**Syntax**:: 4286 4287 %vN = trunc T1 V to T2; <A> 4288 4289**Record**:: 4290 4291 AA: <3, VV, TT2, 0> 4292 4293**Semantics**: 4294 4295The integer truncating instruction takes a value ``V``, and truncates to type 4296``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with 4297the same number of elements. ``T1`` has to be wider than ``T2``. If the value 4298doesn't fit in in ``T2``, then the higher order bits are dropped. 4299 4300**Constraints**:: 4301 4302 AA == AbbrevIndex(A) & 4303 TypeOf(V) == T1 & 4304 VV == RelativeIndex(V) & 4305 %tTT2 == TypeID(T2) & 4306 BitSizeOf(UnderlyingType(T1)) > BitSizeOf(UnderlyingType(T2)) & 4307 UnderlyingCount(T1) == UnderlyingCount(T2) & 4308 IsInteger(UnderlyingType(T1)) & 4309 IsInteger(UnderlyingType(T2)) & 4310 N == NumValuedInsts 4311 4312**Updates**:: 4313 4314 ++NumValuedInsts; 4315 TypeOf(%vN) = T2; 4316 4317**Examples**:: 4318 4319 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4320 48:0| 3: <1, 5> | count 5; 4321 50:4| 3: <7, 32> | @t0 = i32; 4322 53:6| 3: <2> | @t1 = void; 4323 55:4| 3: <7, 16> | @t2 = i16; 4324 58:0| 3: <21, 0, 1, 0> | @t3 = void (i32); 4325 62:0| 3: <7, 8> | @t4 = i8; 4326 64:4| 0: <65534> | } 4327 ... 4328 100:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { 4329 | | // BlockID = 12 4330 108:0| 3: <1, 1> | blocks 1; 4331 | | %b0: 4332 110:4| 3: <3, 1, 2, 0> | %v0 = trunc i32 %p0 to i16; 4333 114:4| 3: <3, 1, 4, 0> | %v1 = trunc i16 %v0 to i8; 4334 118:4| 3: <10> | ret void; 4335 120:2| 0: <65534> | } 4336 4337Floating Point Truncating Instruction 4338-------------------------------------- 4339 4340The floating point truncating instruction takes a value to truncate, and a type 4341defining the truncated type. Both types must be floating point types, or 4342floating point vectors with the same number of elements. The source must be 4343``double`` while the destination is ``float``. If the source is a vector, the 4344destination must also be vector with the same size as the source. 4345 4346**Syntax**:: 4347 4348 %vN = fptrunc T1 V to T2; <A> 4349 4350**Record**:: 4351 4352 AA: <3, VV, TT2, 7> 4353 4354**Semantics** 4355 4356The floating point truncating instruction takes a value ``V``, and truncates to 4357type ``T2``. Both ``T1`` and ``T2`` must be floating point types, or floating 4358point vectors with the same number of elements. ``T1`` must be defined on 4359``double`` while ``T2`` is defined on ``float``. If the value can't fit within 4360the destination type ``T2``, the results are undefined. 4361 4362**Constraints**:: 4363 4364 TypeOf(V) == T1 & 4365 double == UnderlyingType(T1) & 4366 float == UnderlyingType(T2) & 4367 VV == RelativeIndex(V) & 4368 %tTT2 == TypeID(T2) & 4369 BitSizeOf(UnderlyingType(T1)) > BitSizeOf(UnderlyingType(T2)) & 4370 UnderlyingCount(T1) == UnderlyingCount(T2) & 4371 IsFloat(UnderlyingType(T1)) & 4372 IsFloat(UnderlyingType(T2)) & 4373 N == NumValuedInsts 4374 4375**Updates**:: 4376 4377 ++NumValuedInsts; 4378 TypeOf(%vN) = T2; 4379 4380**Examples**:: 4381 4382 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4383 48:0| 3: <1, 4> | count 4; 4384 50:4| 3: <3> | @t0 = float; 4385 52:2| 3: <4> | @t1 = double; 4386 54:0| 3: <21, 0, 0, 1> | @t2 = float (double); 4387 58:0| 3: <2> | @t3 = void; 4388 59:6| 0: <65534> | } 4389 ... 4390 92:0| 1: <65535, 12, 2> | function float @f0(double %p0) { 4391 | | // BlockID = 12 4392 100:0| 3: <1, 1> | blocks 1; 4393 | | %b0: 4394 102:4| 3: <3, 1, 0, 7> | %v0 = fptrunc double %p0 to float; 4395 106:4| 3: <10, 1> | ret float %v0; 4396 109:0| 0: <65534> | } 4397 4398 4399Zero Extending Instruction 4400-------------------------- 4401 4402The zero extending instruction takes a value to extend, and a type to extend it 4403to. Both types must be integer types, or integer vectors with the same number 4404of elements. The bit size of the source type must be smaller than the bit size 4405of the destination type. Equal sized types are not allowed. 4406 4407**Syntax**:: 4408 4409 %vN = zext T1 V to T2; <A> 4410 4411**Record**:: 4412 4413 AA: <3, VV, TT2, 1> 4414 4415 4416**Semantics**: 4417 4418The zero extending instruction takes a value ``V``, and expands it to type 4419``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with 4420the same number of elements. ``T2`` must be wider than ``T1``. 4421 4422The instruction fills the high order bits of the value with zero bits until it 4423reaches the size of the destination type. When zero extending from i1, the 4424result will always be either 0 or 1. 4425 4426**Constraints**:: 4427 4428 AA == AbbrevIndex(A) & 4429 TypeOf(V) == T1 & 4430 VV == RelativeIndex(V) & 4431 %tTT2 == TypeID(T2) & 4432 BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) & 4433 UnderlyingCount(T1) == UnderlyingCount(T2) & 4434 IsInteger(UnderlyingType(T1)) & 4435 IsInteger(UnderlyingType(T2)) & 4436 N == NumValuedInsts 4437 4438**Updates**:: 4439 4440 ++NumValuedInsts; 4441 TypeOf(%vN) = T2; 4442 4443**Examples**:: 4444 4445 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4446 48:0| 3: <1, 5> | count 5; 4447 50:4| 3: <7, 64> | @t0 = i64; 4448 53:6| 3: <7, 32> | @t1 = i32; 4449 57:0| 3: <21, 0, 0> | @t2 = i64 (); 4450 60:2| 3: <7, 8> | @t3 = i8; 4451 62:6| 3: <2> | @t4 = void; 4452 64:4| 0: <65534> | } 4453 ... 4454 100:0| 1: <65535, 12, 2> | function i64 @f0() { // BlockID = 12 4455 108:0| 3: <1, 1> | blocks 1; 4456 110:4| 1: <65535, 11, 2> | constants { // BlockID = 11 4457 120:0| 3: <1, 3> | i8: 4458 122:4| 3: <4, 2> | %c0 = i8 1; 4459 125:0| 0: <65534> | } 4460 | | %b0: 4461 128:0| 3: <3, 1, 1, 1> | %v0 = zext i8 %c0 to i32; 4462 132:0| 3: <3, 1, 0, 1> | %v1 = zext i32 %v0 to i64; 4463 136:0| 3: <10, 1> | ret i64 %v1; 4464 138:4| 0: <65534> | } 4465 4466Sign Extending Instruction 4467-------------------------- 4468 4469The sign extending instruction takes a value to cast, and a type to extend it 4470to. Both types must be integer types, or integral vectors with the same number 4471of elements. The bit size of the source type must be smaller than the bit size 4472of the destination type. Equal sized types are not allowed. 4473 4474**Syntax**:: 4475 4476 %vN = sext T1 V to T2; <A> 4477 4478**Record**:: 4479 4480 AA: <3, VV, TT2, 2> 4481 4482**Semantics**: 4483 4484The sign extending instruction takes a value ``V``, and expands it to type 4485``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with 4486the same number of integers. ``T2`` has to be wider than ``T1``. 4487 4488When sign extending, the instruction fills the high order bits of the value with 4489the (current) high order bit of the value. When sign extending from i1, the 4490extension always results in -1 or 0. 4491 4492**Constraints**:: 4493 4494 AA == AbbrevIndex(A) & 4495 TypeOf(V) == T1 & 4496 VV == RelativeIndex(V) & 4497 %tTT2 == TypeID(T2) & 4498 BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) & 4499 UnderlyingCount(T1) == UnderlyingCount(T2) & 4500 IsInteger(UnderlyingType(T1)) & 4501 IsInteger(UnderlyingType(T2)) & 4502 N == NumValuedInsts 4503 4504**Updates**:: 4505 4506 ++NumValuedInsts; 4507 TypeOf(%vN) = T2; 4508 4509**Examples**:: 4510 4511 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4512 48:0| 3: <1, 5> | count 5; 4513 50:4| 3: <7, 64> | @t0 = i64; 4514 53:6| 3: <7, 32> | @t1 = i32; 4515 57:0| 3: <21, 0, 0> | @t2 = i64 (); 4516 60:2| 3: <7, 8> | @t3 = i8; 4517 62:6| 3: <2> | @t4 = void; 4518 64:4| 0: <65534> | } 4519 ... 4520 100:0| 1: <65535, 12, 2> | function i64 @f0() { // BlockID = 12 4521 108:0| 3: <1, 1> | blocks 1; 4522 110:4| 1: <65535, 11, 2> | constants { // BlockID = 11 4523 120:0| 3: <1, 3> | i8: 4524 122:4| 3: <4, 3> | %c0 = i8 -1; 4525 125:0| 0: <65534> | } 4526 | | %b0: 4527 128:0| 3: <3, 1, 1, 2> | %v0 = sext i8 %c0 to i32; 4528 132:0| 3: <3, 1, 0, 2> | %v1 = sext i32 %v0 to i64; 4529 136:0| 3: <10, 1> | ret i64 %v1; 4530 138:4| 0: <65534> | } 4531 4532Floating Point Extending Instruction 4533------------------------------------ 4534 4535The floating point extending instruction takes a value to extend, and a type to 4536extend it to. Both types must either be floating point types, or vectors of 4537floating point types with the same number of elements. The source value must be 4538``float`` while the destination is ``double``. If the source is a vector, the 4539destination must also be vector with the same size as the source. 4540 4541**Syntax**:: 4542 4543 %vN = fpext T1 V to T2; <A> 4544 4545**Record**:: 4546 4547 AA: <3, VV, TT2, 8> 4548 4549**Semantics**: 4550 4551The floating point extending instruction converts floating point values. 4552``V`` is the value to extend, and ``T2`` is the type to extend it 4553to. Both ``T1`` and ``T2`` must be floating point types, or floating point 4554vector types with the same number of floating point values. ``T1`` contains 4555``float`` while ``T2`` contains ``double``. 4556 4557**Constraints**:: 4558 4559 AA == AbbrevIndex(A) & 4560 TypeOf(V) == T1 & 4561 VV == RelativeIndex(V) & 4562 %tTT2 == TypeID(T2) & 4563 BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) & 4564 UnderlyingCount(T1) == UnderlyingCount(T2) & 4565 IsFloat(UnderlyingType(T1)) & 4566 IsFloat(UnderlyingType(T2)) & 4567 N == NumValuedInsts 4568 4569**Updates**:: 4570 4571 ++NumValuedInsts; 4572 TypeOf(%vN) = T2; 4573 4574**Examples**:: 4575 4576 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4577 48:0| 3: <1, 4> | count 4; 4578 50:4| 3: <4> | @t0 = double; 4579 52:2| 3: <3> | @t1 = float; 4580 54:0| 3: <21, 0, 0, 1> | @t2 = double (float); 4581 58:0| 3: <2> | @t3 = void; 4582 59:6| 0: <65534> | } 4583 ... 4584 92:0| 1: <65535, 12, 2> | function double @f0(float %p0) { 4585 | | // BlockID = 12 4586 100:0| 3: <1, 1> | blocks 1; 4587 | | %b0: 4588 102:4| 3: <3, 1, 0, 8> | %v0 = fpext float %p0 to double; 4589 106:4| 3: <10, 1> | ret double %v0; 4590 109:0| 0: <65534> | } 4591 4592Floating Point to Unsigned Integer Instruction 4593---------------------------------------------- 4594 4595The floating point to unsigned integer instruction converts floating point 4596values to unsigned integers. 4597 4598**Syntax**:: 4599 4600 %vN = fptoui T1 V to T2; <A> 4601 4602**Record**:: 4603 4604 AA: <3, VV, TT2, 3> 4605 4606**Semantics**: 4607 4608The floating point to unsigned integer instruction converts floating point 4609value(s) in ``V`` to its unsigned integer equivalent of type ``T2``. ``T1`` must 4610be a floating point type, or a floating point vector type. ``T2`` must be an 4611integer type, or an integer vector type. If either type is a vector type, they 4612both must have the same number of elements. 4613 4614**Constraints**:: 4615 4616 AA == AbbrevIndex(A) & 4617 TypeOf(V) == T1 & 4618 VV == RelativeIndex(V) & 4619 %tTT2 == TypeID(T2) & 4620 UnderlyingCount(T1) == UnderlyingCount(T2) & 4621 IsFloat(UnderlyingType(T1)) & 4622 IsInteger(UnderlyingType(T2)) & 4623 N == NumValuedInsts 4624 4625**Updates**:: 4626 4627 ++NumValuedInsts; 4628 TypeOf(%vN) = T2; 4629 4630**Examples**:: 4631 4632 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4633 48:0| 3: <1, 6> | count 6; 4634 50:4| 3: <3> | @t0 = float; 4635 52:2| 3: <4> | @t1 = double; 4636 54:0| 3: <2> | @t2 = void; 4637 55:6| 3: <21, 0, 2, 0, 1> | @t3 = void (float, double); 4638 60:4| 3: <7, 32> | @t4 = i32; 4639 63:6| 3: <7, 16> | @t5 = i16; 4640 66:2| 0: <65534> | } 4641 ... 4642 100:0| 1: <65535, 12, 2> | function 4643 | | void @f0(float %p0, double %p1) { 4644 | | // BlockID = 12 4645 108:0| 3: <1, 1> | blocks 1; 4646 | | %b0: 4647 110:4| 3: <3, 2, 4, 3> | %v0 = fptoui float %p0 to i32; 4648 114:4| 3: <3, 2, 5, 3> | %v1 = fptoui double %p1 to i16; 4649 118:4| 3: <10> | ret void; 4650 120:2| 0: <65534> | } 4651 4652Floating Point to Signed Integer Instruction 4653-------------------------------------------- 4654 4655The floating point to signed integer instruction converts floating point 4656values to signed integers. 4657 4658**Syntax**:: 4659 4660 %vN = fptosi T1 V to T2; <A> 4661 4662**Record**:: 4663 4664 AA: <3, VV, TT2, 4> 4665 4666**Semantics**: 4667 4668The floating point to signed integer instruction converts floating point 4669value(s) in ``V`` to its signed integer equivalent of type ``T2``. ``T1`` must 4670be a floating point type, or a floating point vector type. ``T2`` must be an 4671integer type, or an integer vector type. If either type is a vector type, they 4672both must have the same number of elements. 4673 4674**Constraints**:: 4675 4676 AA == AbbrevIndex(A) & 4677 TypeOf(V) == T1 & 4678 VV == RelativeIndex(V) & 4679 %tTT2 = TypeID(T2) & 4680 UnderlyingCount(T1) = UnderlyingCount(T2) & 4681 IsFloat(UnderlyingType(T1)) & 4682 IsInteger(UnderlyingType(T2)) & 4683 N = NumValuedInsts 4684 4685**Updates**:: 4686 4687 ++NumValuedInsts; 4688 TypeOf(%vN) = T2; 4689 4690**Examples**:: 4691 4692 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4693 48:0| 3: <1, 6> | count 6; 4694 50:4| 3: <3> | @t0 = float; 4695 52:2| 3: <4> | @t1 = double; 4696 54:0| 3: <2> | @t2 = void; 4697 55:6| 3: <21, 0, 2, 0, 1> | @t3 = void (float, double); 4698 60:4| 3: <7, 8> | @t4 = i8; 4699 63:0| 3: <7, 16> | @t5 = i16; 4700 65:4| 0: <65534> | } 4701 ... 4702 100:0| 1: <65535, 12, 2> | function 4703 | | void @f0(float %p0, double %p1) { 4704 | | // BlockID = 12 4705 108:0| 3: <1, 1> | blocks 1; 4706 | | %b0: 4707 110:4| 3: <3, 2, 4, 4> | %v0 = fptosi float %p0 to i8; 4708 114:4| 3: <3, 2, 5, 4> | %v1 = fptosi double %p1 to i16; 4709 118:4| 3: <10> | ret void; 4710 120:2| 0: <65534> | } 4711 4712Unsigned Integer to Floating Point Instruction 4713---------------------------------------------- 4714 4715The unsigned integer to floating point instruction converts unsigned integers to 4716floating point values. 4717 4718**Syntax**:: 4719 4720 %vN = uitofp T1 V to T2; <A> 4721 4722**Record**:: 4723 4724 AA: <3, VV, TT2, 5> 4725 4726**Semantics**: 4727 4728The unsigned integer to floating point instruction converts unsigned integer(s) 4729to its floating point equivalent of type ``T2``. ``T1`` must be an integer type, 4730or a integer vector type. ``T2`` must be a floating point type, or a floating 4731point vector type. If either type is a vector type, they both must have the same 4732number of elements. 4733 4734**Constraints**:: 4735 4736 AA == AbbrevIndex(A) & 4737 TypeOf(V) == T1 & 4738 VV == RelativeIndex(V) & 4739 %tTT2 = TypeID(T2) & 4740 UnderlyingCount(T1) == UnderlyingCount(T2) & 4741 IsInteger(UnderlyingType(T1)) & 4742 IsFloat(UnderlyingType(T2)) & 4743 N == NumValuedInsts 4744 4745**Updates**:: 4746 4747 ++NumValuedInsts; 4748 TypeOf(%vN) == T2; 4749 4750**Examples**:: 4751 4752 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4753 48:0| 3: <1, 7> | count 7; 4754 50:4| 3: <7, 32> | @t0 = i32; 4755 53:6| 3: <7, 64> | @t1 = i64; 4756 57:0| 3: <2> | @t2 = void; 4757 58:6| 3: <3> | @t3 = float; 4758 60:4| 3: <21, 0, 2, 0, 1> | @t4 = void (i32, i64); 4759 65:2| 3: <7, 1> | @t5 = i1; 4760 67:6| 3: <4> | @t6 = double; 4761 69:4| 0: <65534> | } 4762 ... 4763 104:0| 1: <65535, 12, 2> | function void @f0(i32 %p0, i64 %p1) { 4764 | | // BlockID = 12 4765 112:0| 3: <1, 1> | blocks 1; 4766 114:4| 1: <65535, 11, 2> | constants { // BlockID = 11 4767 124:0| 3: <1, 5> | i1: 4768 126:4| 3: <4, 3> | %c0 = i1 1; 4769 129:0| 0: <65534> | } 4770 | | %b0: 4771 132:0| 3: <3, 1, 6, 5> | %v0 = uitofp i1 %c0 to double; 4772 136:0| 3: <3, 4, 3, 5> | %v1 = uitofp i32 %p0 to float; 4773 140:0| 3: <3, 4, 3, 5> | %v2 = uitofp i64 %p1 to float; 4774 144:0| 3: <10> | ret void; 4775 145:6| 0: <65534> | } 4776 4777Signed Integer to Floating Point Instruction 4778-------------------------------------------- 4779 4780The signed integer to floating point instruction converts signed integers to 4781floating point values. 4782 4783**Syntax**:: 4784 4785 %vN = sitofp T1 V to T2; <A> 4786 4787**Record**:: 4788 4789 AA: <3, VV, TT2, 6> 4790 4791**Semantics**: 4792 4793The signed integer to floating point instruction converts signed integer(s) to 4794its floating point equivalent of type ``T2``. ``T1`` must be an integer type, or 4795a integer vector type. ``T2`` must be a floating point type, or a floating point 4796vector type. If either type is a vector type, they both must have the same 4797number of elements. 4798 4799**Constraints**:: 4800 4801 AA == AbbrevIndex(A) & 4802 TypeOf(V) == T1 & 4803 VV == RelativeIndex(V) & 4804 %tTT2 = TypeID(T2) & 4805 UnderlyingCount(T1) == UnderlyingCount(T2) & 4806 IsInteger(UnderlyingType(T1)) & 4807 IsFloat(UnderlyingType(T2)) & 4808 N == NumValuedInsts 4809 4810**Updates**:: 4811 4812 ++NumValuedInsts; 4813 TypeOf(%vN) = T2; 4814 4815**Examples**:: 4816 4817 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4818 48:0| 3: <1, 7> | count 7; 4819 50:4| 3: <7, 32> | @t0 = i32; 4820 53:6| 3: <7, 64> | @t1 = i64; 4821 57:0| 3: <2> | @t2 = void; 4822 58:6| 3: <3> | @t3 = float; 4823 60:4| 3: <21, 0, 2, 0, 1> | @t4 = void (i32, i64); 4824 65:2| 3: <7, 8> | @t5 = i8; 4825 67:6| 3: <4> | @t6 = double; 4826 69:4| 0: <65534> | } 4827 ... 4828 104:0| 1: <65535, 12, 2> | function void @f0(i32 %p0, i64 %p1) { 4829 | | // BlockID = 12 4830 112:0| 3: <1, 1> | blocks 1; 4831 114:4| 1: <65535, 11, 2> | constants { // BlockID = 11 4832 124:0| 3: <1, 5> | i8: 4833 126:4| 3: <4, 3> | %c0 = i8 -1; 4834 129:0| 0: <65534> | } 4835 | | %b0: 4836 132:0| 3: <3, 1, 6, 6> | %v0 = sitofp i8 %c0 to double; 4837 136:0| 3: <3, 4, 3, 6> | %v1 = sitofp i32 %p0 to float; 4838 140:0| 3: <3, 4, 3, 6> | %v2 = sitofp i64 %p1 to float; 4839 144:0| 3: <10> | ret void; 4840 145:6| 0: <65534> | } 4841 4842Bitcast Instruction 4843------------------- 4844 4845The bitcast instruction converts the type of the value without changing the bit 4846contents of the value. The bit size of the type of the value must be the same as 4847the bit size of the cast type. 4848 4849**Syntax**:: 4850 4851 %vN = bitcast T1 V to T2; <A> 4852 4853**Record**:: 4854 4855 AA: <3, VV, TT2, 11> 4856 4857**Semantics**: 4858 4859The bitcast instruction converts the type of value ``V`` to type ``T2``. ``T1`` 4860and ``T2`` must be primitive types or vectors, and define the same number of 4861bits. 4862 4863**Constraints**:: 4864 4865 AA == AbbrevIndex(A) & 4866 TypeOf(V) == T1 & 4867 VV = RelativeIndex(V) & 4868 %tTT2 = TypeID(T2) & 4869 BitSizeOf(T1) == BitSizeOf(T2) & 4870 N == NumValuedInsts 4871 4872**Updates**:: 4873 4874 ++NumValuedInsts; 4875 TypeOf(%vN) = T2; 4876 4877**Examples**:: 4878 4879 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4880 48:0| 3: <1, 6> | count 6; 4881 50:4| 3: <3> | @t0 = float; 4882 52:2| 3: <7, 64> | @t1 = i64; 4883 55:4| 3: <2> | @t2 = void; 4884 57:2| 3: <21, 0, 2, 0, 1> | @t3 = void (float, i64); 4885 62:0| 3: <7, 32> | @t4 = i32; 4886 65:2| 3: <4> | @t5 = double; 4887 67:0| 0: <65534> | } 4888 ... 4889 100:0| 1: <65535, 12, 2> | function void @f0(float %p0, i64 %p1) 4890 | | { // BlockID = 12 4891 108:0| 3: <1, 1> | blocks 1; 4892 | | %b0: 4893 110:4| 3: <3, 2, 4, 11> | %v0 = bitcast float %p0 to i32; 4894 114:4| 3: <3, 2, 5, 11> | %v1 = bitcast i64 %p1 to double; 4895 118:4| 3: <10> | ret void; 4896 120:2| 0: <65534> | } 4897 4898.. _link_for_compare_instructions: 4899 4900Comparison Instructions 4901======================= 4902 4903The comparison instructions compare values and generates a boolean (i1) result 4904for each pair of compared values. There are different comparison operations for 4905integer and floating point values. 4906 4907 4908Integer Comparison Instructions 4909------------------------------- 4910 4911The integer comparison instruction compares integer values and returns a 4912boolean (i1) result for each pair of compared values. 4913 4914**Syntax**:: 4915 4916 %vN = icmp C T V1, V2; <A> 4917 4918**Record**:: 4919 4920 AA: <9, VV1, VV2, CC> 4921 4922**Semantics**: 4923 4924The integer comparison instruction compares integer values and returns a boolean 4925(i1) result for each pair of compared values in ``V1`` and ``V2``. ``V1`` and 4926``V2`` must be of type ``T``. ``T`` must be an integer type, or an integer 4927vector type. Condition code ``C`` is the condition applied to all elements in 4928``V1`` and ``V2``. Each comparison always yields an i1. If ``T`` is a primitive 4929type, the resulting type is i1. If ``T`` is a vector, then the resulting type is 4930a vector of i1 with the same size as ``T``. 4931 4932Legal test conditions are: 4933 4934=== == ============================== 4935C CC Operator 4936=== == ============================== 4937eq 32 equal 4938ne 33 not equal 4939ugt 34 unsigned greater than 4940uge 35 unsigned greater than or equal 4941ult 36 unsigned less than 4942ule 37 unsigned less than or equal 4943sgt 38 signed greater than 4944sge 39 signed greater than or equal 4945slt 40 signed less than 4946sle 41 signed less than or equal 4947=== == ============================== 4948 4949**Constraints**:: 4950 4951 AA == AbbrevIndex(A) & 4952 IsInteger(UnderlyingType(T) & 4953 T == TypeOf(V1) == TypeOf(V2) & 4954 N == NumValuedInsts 4955 4956**Updates**:: 4957 4958 ++NumValuedInsts; 4959 if IsVector(T) then 4960 TypeOf(%vN) = <UnderlyingCount(T), i1> 4961 else 4962 TypeOf(%vN) = i1 4963 endif 4964 4965**Examples**:: 4966 4967 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 4968 48:0| 3: <1, 4> | count 4; 4969 50:4| 3: <7, 32> | @t0 = i32; 4970 53:6| 3: <7, 1> | @t1 = i1; 4971 56:2| 3: <2> | @t2 = void; 4972 58:0| 3: <21, 0, 2> | @t3 = void (); 4973 61:2| 0: <65534> | } 4974 ... 4975 108:0| 1: <65535, 12, 2> | function void @f0() { 4976 | | // BlockID = 12 4977 116:0| 3: <1, 1> | blocks 1; 4978 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 4979 128:0| 3: <1, 0> | i32: 4980 130:4| 3: <4, 0> | %c0 = i32 0; 4981 133:0| 3: <4, 2> | %c1 = i32 1; 4982 135:4| 0: <65534> | } 4983 | | %b0: 4984 136:0| 3: <28, 2, 1, 32> | %v0 = icmp eq i32 %c0, %c1; 4985 140:6| 3: <28, 3, 2, 33> | %v1 = icmp ne i32 %c0, %c1; 4986 145:4| 3: <28, 4, 3, 34> | %v2 = icmp ugt i32 %c0, %c1; 4987 150:2| 3: <28, 5, 4, 36> | %v3 = icmp ult i32 %c0, %c1; 4988 155:0| 3: <28, 6, 5, 37> | %v4 = icmp ule i32 %c0, %c1; 4989 159:6| 3: <28, 7, 6, 38> | %v5 = icmp sgt i32 %c0, %c1; 4990 164:4| 3: <28, 8, 7, 38> | %v6 = icmp sgt i32 %c0, %c1; 4991 169:2| 3: <28, 9, 8, 39> | %v7 = icmp sge i32 %c0, %c1; 4992 174:0| 3: <28, 10, 9, 40> | %v8 = icmp slt i32 %c0, %c1; 4993 178:6| 3: <28, 11, 10, 41> | %v9 = icmp sle i32 %c0, %c1; 4994 183:4| 3: <10> | ret void; 4995 185:2| 0: <65534> | } 4996 4997 4998Floating Point Comparison Instructions 4999-------------------------------------- 5000 5001The floating point comparison instruction compares floating point values and 5002returns a boolean (i1) result for each pair of compared values. 5003 5004**Syntax**:: 5005 5006 %vN = fcmp C T V1, V2; <A> 5007 5008**Record**:: 5009 5010 AA: <9, VV1, VV2, CC> 5011 5012**Semantics**: 5013 5014The floating point comparison instruction compares floating point values and 5015returns a boolean (i1) result for each pair of compared values in ``V1`` and 5016``V2``. ``V1`` and ``V2`` must be of type ``T``. ``T`` must be a floating point 5017type, or a floating point vector type. Condition code ``C`` is the condition 5018applied to all elements in ``V1`` and ``V2``. Each comparison always yields an 5019i1. If ``T`` is a primitive type, the resulting type is i1. If ``T`` is a 5020vector, then the resulting type is a vector of i1 with the same size as ``T``. 5021 5022Legal test conditions are: 5023 5024===== == ================================== 5025C CC Operator 5026===== == ================================== 5027false 0 Always false 5028oeq 1 Ordered and equal 5029ogt 2 Ordered and greater than 5030oge 3 Ordered and greater than or equal 5031olt 4 Ordered and less than 5032ole 5 Ordered and less than or equal 5033one 6 Ordered and not equal 5034ord 7 Ordered (no NaNs) 5035uno 8 Unordered (either NaNs) 5036ueq 9 Unordered or equal 5037ugt 10 Unordered or greater than 5038uge 11 Unordered or greater than or equal 5039ult 12 Unordered or less than 5040ule 13 Unordered or less than or equal 5041une 14 Unordered or not equal 5042true 15 Always true 5043===== == ================================== 5044 5045**Constraints**:: 5046 5047 AA == AbbrevIndex(A) & 5048 IsFloat(UnderlyingType(T) & 5049 T == TypeOf(V1) == TypeOf(V2) & 5050 N == NumValuedInsts 5051 5052**Updates**:: 5053 5054 ++NumValuedInsts; 5055 if IsVector(T) then 5056 TypeOf(%vN) = <UnderlyingCount(T), i1> 5057 else 5058 TypeOf(%vN) = i1 5059 endif 5060 5061**Examples**:: 5062 5063 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 5064 48:0| 3: <1, 4> | count 4; 5065 50:4| 3: <3> | @t0 = float; 5066 52:2| 3: <7, 1> | @t1 = i1; 5067 54:6| 3: <2> | @t2 = void; 5068 56:4| 3: <21, 0, 2> | @t3 = void (); 5069 59:6| 0: <65534> | } 5070 ... 5071 108:0| 1: <65535, 12, 2> | function void @f0() { 5072 | | // BlockID = 12 5073 116:0| 3: <1, 1> | blocks 1; 5074 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5075 128:0| 3: <1, 0> | float: 5076 130:4| 3: <6, 0> | %c0 = float 0; 5077 133:0| 3: <6, 1065353216> | %c1 = float 1; 5078 139:2| 0: <65534> | } 5079 | | %b0: 5080 140:0| 3: <28, 2, 1, 0> | %v0 = fcmp false float %c0, %c1; 5081 144:0| 3: <28, 3, 2, 1> | %v1 = fcmp oeq float %c0, %c1; 5082 148:0| 3: <28, 4, 3, 2> | %v2 = fcmp ogt float %c0, %c1; 5083 152:0| 3: <28, 5, 4, 3> | %v3 = fcmp oge float %c0, %c1; 5084 156:0| 3: <28, 6, 5, 4> | %v4 = fcmp olt float %c0, %c1; 5085 160:0| 3: <28, 7, 6, 5> | %v5 = fcmp ole float %c0, %c1; 5086 164:0| 3: <28, 8, 7, 6> | %v6 = fcmp one float %c0, %c1; 5087 168:0| 3: <28, 9, 8, 7> | %v7 = fcmp ord float %c0, %c1; 5088 172:0| 3: <28, 10, 9, 9> | %v8 = fcmp ueq float %c0, %c1; 5089 176:0| 3: <28, 11, 10, 10> | %v9 = fcmp ugt float %c0, %c1; 5090 180:0| 3: <28, 12, 11, 11> | %v10 = fcmp uge float %c0, %c1; 5091 184:0| 3: <28, 13, 12, 12> | %v11 = fcmp ult float %c0, %c1; 5092 188:0| 3: <28, 14, 13, 13> | %v12 = fcmp ule float %c0, %c1; 5093 192:0| 3: <28, 15, 14, 14> | %v13 = fcmp une float %c0, %c1; 5094 196:0| 3: <28, 16, 15, 8> | %v14 = fcmp uno float %c0, %c1; 5095 200:0| 3: <28, 17, 16, 15> | %v15 = fcmp true float %c0, %c1; 5096 204:0| 3: <10> | ret void; 5097 205:6| 0: <65534> | } 5098 208:0|0: <65534> |} 5099 5100.. _link_for_vector_instructions: 5101 5102Vector Instructions 5103=================== 5104 5105PNaClAsm supports several instructions that process vectors. This includes the 5106:ref:`integer<link_for_integer_binary_instructions>` and :ref:`floating 5107point<link_for_floating_point_binary_instructions>` binary instructions as well 5108as :ref:`compare<link_for_compare_instructions>` instructions. These 5109instructions work with vectors and generate resulting (new) vectors. This 5110section introduces the instructions to construct vectors and extract results. 5111 5112.. _link_for_insert_element_instruction_section: 5113 5114Insert Element Instruction 5115-------------------------- 5116 5117The *insert element* instruction inserts a scalar value into a vector at a 5118specified index. The *insert element* instruction takes an existing vector and 5119puts a scalar value in one of the elements of the vector. 5120 5121The *insert element* instruction can be used to construct a vector, one element 5122at a time. At first glance, it may appear that one can't construct a vector, 5123since the *insert element* instruction needs a vector to insert elements into. 5124 5125The key to understanding vector construction is understand that one can create 5126an :ref:`undefined<link_for_undefined_literal>` vector literal. Using that 5127constant as a starting point, one can built up the wanted vector by a sequence 5128of *insert element* instructions. 5129 5130**Syntax**:: 5131 5132 %vN = insertelement TV V, TE E, i32 I; <A> 5133 5134**Record**:: 5135 5136 AA: <7, VV, EE, II> 5137 5138**Semantics**: 5139 5140The *insert element* instruction inserts scalar value ``E`` into index ``I`` of 5141vector ``V``. ``%vN`` holds the updated vector. Type ``TV`` is the type of 5142vector. It is also the type of updated vector ``%vN``. Type ``TE`` is the type 5143of scalar value ``E`` and must be the element type of vector ``V``. ``I`` must 5144be an :ref:`i32 literal<link_for_integer_literal>`. 5145 5146If ``I`` exceeds the length of ``V``, the result is undefined. 5147 5148**Constraints**:: 5149 5150 AA == AbbrevIndex(A) & 5151 IsVector(TV) & 5152 TypeOf(V) == TV & 5153 UnderlyingType(TV) == TE & 5154 TypeOf(I) == i32 & 5155 N == NumValuedInsts 5156 5157**Updates**:: 5158 5159 ++NumValuedInsts; 5160 TypeOf(%vN) = TV; 5161 5162**Examples**:: 5163 5164 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 5165 48:0| 3: <1, 5> | count 5; 5166 50:4| 3: <7, 1> | @t0 = i1; 5167 53:0| 3: <12, 4, 0> | @t1 = <4 x i1>; 5168 56:2| 3: <7, 32> | @t2 = i32; 5169 59:4| 3: <2> | @t3 = void; 5170 61:2| 3: <21, 0, 3> | @t4 = void (); 5171 64:4| 0: <65534> | } 5172 ... 5173 116:0| 1: <65535, 12, 2> | function void @f0() { 5174 | | // BlockID = 12 5175 124:0| 3: <1, 1> | blocks 1; 5176 126:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5177 136:0| 3: <1, 0> | i1: 5178 138:4| 3: <4, 0> | %c0 = i1 0; 5179 141:0| 3: <4, 3> | %c1 = i1 1; 5180 143:4| 3: <1, 1> | <4 x i1>: 5181 146:0| 3: <3> | %c2 = <4 x i1> undef; 5182 147:6| 3: <1, 2> | i32: 5183 150:2| 3: <4, 0> | %c3 = i32 0; 5184 152:6| 3: <4, 2> | %c4 = i32 1; 5185 155:2| 3: <4, 4> | %c5 = i32 2; 5186 157:6| 3: <4, 6> | %c6 = i32 3; 5187 160:2| 0: <65534> | } 5188 | | %b0: 5189 164:0| 3: <7, 5, 7, 4> | %v0 = insertelement <4 x i1> %c2, 5190 | | i1 %c0, i32 %c3; 5191 168:0| 3: <7, 1, 7, 4> | %v1 = insertelement <4 x i1> %v0, 5192 | | i1 %c1, i32 %c4; 5193 172:0| 3: <7, 1, 9, 4> | %v2 = insertelement <4 x i1> %v1, 5194 | | i1 %c0, i32 %c5; 5195 176:0| 3: <7, 1, 9, 4> | %v3 = insertelement <4 x i1> %v2, 5196 | | i1 %c1, i32 %c6; 5197 180:0| 3: <10> | ret void; 5198 181:6| 0: <65534> | } 5199 5200Extract Element Instruction 5201--------------------------- 5202 5203The *extract element* instruction extracts a single scalar value from a vector 5204at a specified index. 5205 5206**Syntax**:: 5207 5208 %vN = extractelement TV V, i32 I; <A> 5209 5210**Record**:: 5211 5212 AA: <6, VV, II> 5213 5214**Semantics**: 5215 5216The *extract element* instruction extracts the scalar value at index ``I`` from 5217vector ``V``. The extracted value is assigned to ``%vN``. Type ``TV`` is the 5218type of vector ``V``. ``I`` must be an :ref:`i32 5219literal<link_for_integer_literal>`. The type of ``vN`` must be the element type 5220of vector ``V``. 5221 5222If ``I`` exceeds the length of ``V``, the result is undefined. 5223 5224**Constraints**:: 5225 5226 AA == AbbrevIndex(A) & 5227 IsVector(TV) & 5228 TypeOf(V) == TV & 5229 TypeOf(I) == i32 & 5230 N == NumValuedInsts 5231 5232**Updates**:: 5233 5234 ++NumValuedInsts; 5235 TypeOf(%vN) = UnderlyingType(TV); 5236 5237**Examples**:: 5238 5239 96:0| 1: <65535, 12, 2> | function void @f0(<4 x i32> %p0) { 5240 | | // BlockID = 12 5241 104:0| 3: <1, 1> | blocks 1; 5242 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5243 116:0| 3: <1, 0> | i32: 5244 118:4| 3: <4, 0> | %c0 = i32 0; 5245 121:0| 0: <65534> | } 5246 | | %b0: 5247 124:0| 3: <6, 2, 1> | %v0 = 5248 | | extractelement <4 x i32> %p0, 5249 | | i32 %c0; 5250 127:2| 3: <10> | ret void; 5251 129:0| 0: <65534> | } 5252 5253.. _link_for_other_pnaclasm_instructions: 5254 5255Other Instructions 5256================== 5257 5258This section defines miscellaneous instructions which defy better 5259classification. 5260 5261.. _link_for_forward_type_declaration_section: 5262 5263Forward Type Declaration 5264------------------------ 5265 5266The forward type declaration exists to deal with the fact that all instruction 5267values must have a type associated with them before they are used. For some 5268simple functions one can easily topologically sort instructions so that 5269instruction values are defined before they are used. However, if the 5270implementation contains loops, the loop induced values can't be defined before 5271they are used. 5272 5273The solution is to forward declare the type of an instruction value. One could 5274forward declare the types of all instructions at the beginning of the function 5275block. However, this would make the corresponding file size considerably 5276larger. Rather, one should only generate these forward type declarations 5277sparingly and only when needed. 5278 5279**Syntax**:: 5280 5281 declare T %vN; <A> 5282 5283**Record**:: 5284 5285 AA: <43, N, TT> 5286 5287**Semantics**: 5288 5289The forward declare type declaration defines the type to be associated with a 5290(not yet defined) instruction value ``%vN``. ``T`` is the type of the value 5291generated by the ``Nth`` value generating instruction in the function block. 5292 5293Note: It is an error to define the type of ``%vN`` with a different type than 5294will be generated by the ``Nth`` value generating instruction in the function 5295block. 5296 5297Also note that this construct is a declaration and not considered an 5298instruction, even though it appears in the list of instruction records. Hence, 5299they may appear before and between :ref:`phi<link_for_phi_instruction_section>` 5300instructions in a basic block. 5301 5302**Constraints**:: 5303 5304 AA = AbbrevIndex(A) & 5305 TT = TypeID(T) 5306 5307**Updates**:: 5308 5309 TypeOf(%vN) = T; 5310 5311**Examples**:: 5312 5313 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 5314 48:0| 3: <1, 4> | count 4; 5315 50:4| 3: <7, 32> | @t0 = i32; 5316 53:6| 3: <2> | @t1 = void; 5317 55:4| 3: <7, 1> | @t2 = i1; 5318 58:0| 3: <21, 0, 1, 0> | @t3 = void (i32); 5319 62:0| 0: <65534> | } 5320 ... 5321 108:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { 5322 | | // BlockID = 12 5323 116:0| 3: <1, 7> | blocks 7; 5324 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5325 128:0| 3: <1, 2> | i1: 5326 130:4| 3: <4, 3> | %c0 = i1 1; 5327 133:0| 0: <65534> | } 5328 | | %b0: 5329 136:0| 3: <11, 4> | br label %b4; 5330 | | %b1: 5331 138:4| 3: <43, 6, 0> | declare i32 %v3; 5332 142:4| 3: <2, 2, 4294967293, 0> | %v0 = add i32 %p0, %v3; 5333 151:0| 3: <11, 6> | br label %b6; 5334 | | %b2: 5335 153:4| 3: <43, 7, 0> | declare i32 %v4; 5336 157:4| 3: <2, 3, 4294967293, 0> | %v1 = add i32 %p0, %v4; 5337 166:0| 3: <11, 6> | br label %b6; 5338 | | %b3: 5339 168:4| 3: <2, 4, 4294967295, 0> | %v2 = add i32 %p0, %v3; 5340 177:0| 3: <11, 6> | br label %b6; 5341 | | %b4: 5342 179:4| 3: <2, 5, 5, 0> | %v3 = add i32 %p0, %p0; 5343 183:4| 3: <11, 1, 5, 5> | br i1 %c0, label %b1, label %b5; 5344 | | %b5: 5345 187:4| 3: <2, 1, 6, 0> | %v4 = add i32 %v3, %p0; 5346 191:4| 3: <11, 2, 3, 6> | br i1 %c0, label %b2, label %b3; 5347 | | %b6: 5348 195:4| 3: <10> | ret void; 5349 197:2| 0: <65534> | } 5350 5351.. _link_for_phi_instruction_section: 5352 5353Phi Instruction 5354--------------- 5355 5356The *phi* instruction is used to implement phi nodes in the SSA graph 5357representing the function. Phi instructions can only appear at the beginning of 5358a basic block. There must be no non-phi instructions (other than forward type 5359declarations) between the start of the basic block and the *phi* instruction. 5360 5361To clarify the origin of each incoming value, the incoming value is associated 5362with the incoming edge from the corresponding predecessor block that the 5363incoming value comes from. 5364 5365**Syntax**:: 5366 5367 %vN = phi T [V1, %bB1], ... , [VM, %bBM]; <A> 5368 5369**Record**:: 5370 5371 AA: <16, TT, VV1, B1, ..., VVM, BM> 5372 5373**Semantics**: 5374 5375The phi instruction is used to implement phi nodes in the SSA graph representing 5376the function. ``%vN`` is the resulting value of the corresponding phi 5377node. ``T`` is the type of the phi node. Values ``V1`` through ``VM`` are the 5378reaching definitions for the phi node while ``%bB1`` through ``%bBM`` are the 5379corresponding predecessor blocks. Each ``VI`` reaches via the incoming 5380predecessor edge from block ``%bBI`` (for 1 <= I <= M). Type ``T`` must be the 5381type associated with each ``VI``. 5382 5383**Constraints**:: 5384 5385 AA == AbbrevIndex(A) & 5386 M > 1 & 5387 TT == TypeID(T) & 5388 T = TypeOf(VI) for all I, 1 <= I <= M & 5389 BI < ExpectedBasicBlocks for all I, 1 <= I <= M & 5390 VVI = SignRotate(RelativeIndex(VI)) for all I, 1 <= I <= M & 5391 N == NumValuedInsts 5392 5393**Updates**:: 5394 5395 ++NumValuedInsts; 5396 TypeOf(%vN) = T; 5397 5398**Examples**:: 5399 5400 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 5401 48:0| 3: <1, 4> | count 4; 5402 50:4| 3: <7, 32> | @t0 = i32; 5403 53:6| 3: <2> | @t1 = void; 5404 55:4| 3: <21, 0, 1> | @t2 = void (); 5405 58:6| 3: <7, 1> | @t3 = i1; 5406 61:2| 0: <65534> | } 5407 ... 5408 112:0| 1: <65535, 12, 2> | function void @f0() { 5409 | | // BlockID = 12 5410 120:0| 3: <1, 4> | blocks 4; 5411 122:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5412 132:0| 3: <1, 0> | i32: 5413 134:4| 3: <4, 2> | %c0 = i32 1; 5414 137:0| 3: <1, 3> | i1: 5415 139:4| 3: <4, 0> | %c1 = i1 0; 5416 142:0| 0: <65534> | } 5417 | | %b0: 5418 144:0| 3: <11, 1, 2, 1> | br i1 %c1, label %b1, label %b2; 5419 | | %b1: 5420 148:0| 3: <2, 2, 2, 0> | %v0 = add i32 %c0, %c0; 5421 152:0| 3: <2, 3, 3, 1> | %v1 = sub i32 %c0, %c0; 5422 156:0| 3: <11, 3> | br label %b3; 5423 | | %b2: 5424 158:4| 3: <2, 4, 4, 2> | %v2 = mul i32 %c0, %c0; 5425 162:4| 3: <2, 5, 5, 3> | %v3 = udiv i32 %c0, %c0; 5426 166:4| 3: <11, 3> | br label %b3; 5427 | | %b3: 5428 169:0| 3: <16, 0, 8, 1, 4, 2> | %v4 = phi i32 [%v0, %b1], 5429 | | [%v2, %b2]; 5430 174:4| 3: <16, 0, 8, 1, 4, 2> | %v5 = phi i32 [%v1, %b1], 5431 | | [%v3, %b2]; 5432 180:0| 3: <10> | ret void; 5433 181:6| 0: <65534> | } 5434 5435Select Instruction 5436------------------ 5437 5438The *select* instruction is used to choose between pairs of values, based on a 5439condition, without PNaClAsm-level branching. 5440 5441**Syntax**:: 5442 5443 %vN = select CT C, T V1, T V2; <A> 5444 5445**Record**:: 5446 5447 AA: <29, VV1, VV2, CC> 5448 5449**Semantics**: 5450 5451The *select* instruction chooses pairs of values ``V1`` and ``V2``, based on 5452condition value ``C``. The type ``CT`` of value ``C`` must either be an i1, or 5453a vector of type i1. The type of values ``V1`` and ``V2`` must be of type 5454``T``. Type ``T`` must either be a primitive type, or a vector of a primitive 5455type. 5456 5457Both ``CT`` and ``T`` must be primitive types, or both must be vector types of 5458the same size. When the contents of ``C`` is 1, the corresponding value from 5459``V1`` will be chosen. Otherwise the corresponding value from ``V2`` will be 5460chosen. 5461 5462**Constraints**:: 5463 5464 AA == AbbrevIndex(A) & 5465 CC == RelativeIndex(C) & 5466 VV1 == RelativeIndex(V1) & 5467 VV2 == RelativeIndex(V2) & 5468 T == TypeOf(V1) == TypeOf(V2) & 5469 UnderlyingType(CT) == i1 & 5470 IsInteger(UnderlyingType(T)) or IsFloat(UnderlyingType(T)) & 5471 UnderlyingCount(C) == UnderlyingCount(T) & 5472 N == NumValuedInsts 5473 5474**Updates**:: 5475 5476 ++NumValuedInsts; 5477 TypeOf(%vN) = T; 5478 5479**Examples**:: 5480 5481 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { 5482 | | // BlockID = 12 5483 104:0| 3: <1, 1> | blocks 1; 5484 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5485 116:0| 3: <1, 2> | i1: 5486 118:4| 3: <4, 3> | %c0 = i1 1; 5487 121:0| 0: <65534> | } 5488 | | %b0: 5489 124:0| 3: <29, 3, 2, 1> | %v0 = select i1 %c0, i32 %p0, 5490 | | i32 %p1; 5491 128:0| 3: <10, 1> | ret i32 %v0; 5492 130:4| 0: <65534> | } 5493 5494 5495Call Instructions 5496----------------- 5497 5498The *call* instruction does a function call. The call instruction is used to 5499cause control flow to transfer to a specified routine, with its incoming 5500arguments bound to the specified values. When a return instruction in the called 5501function is reached, control flow continues with the instruction after the 5502function call. If the call is to a function, the returned value is the value 5503generated by the call instruction. Otherwise no result is defined by the call. 5504 5505If the *tail* flag is associated with the call instruction, then the :ref:`PNaCl 5506translator<link_for_pnacl_translator>` is free to perform tail call 5507optimization. That is, the *tail* flag is a hint that may be ignored by the 5508PNaCl translator. 5509 5510There are two kinds of calls: *direct* and *indirect*. A *direct* call calls a 5511defined :ref:`function address<link_for_function_address_section>` (i.e. a 5512reference to a bitcode ID of the form ``%fF``). All other calls are *indirect*. 5513 5514Direct Procedure Call 5515^^^^^^^^^^^^^^^^^^^^^ 5516 5517The direct procedure call calls a defined :ref:`function 5518address<link_for_function_address_section>` whose :ref:`type 5519signature<link_for_function_type>` returns type void. 5520 5521**Syntax**:: 5522 5523 TAIL call void @fF (T1 A1, ... , TN AN); <A> 5524 5525**Record**:: 5526 5527 AA: <34, CC, F, AA1, ... , AAN> 5528 5529**Semantics**: 5530 5531The direct procedure call calls a define function address ``%fF`` whose type 5532signature return type is void. The arguments ``A1`` through ``AN`` are passed in 5533the order specified. The type of argument ``AI`` must be type ``TI`` (for all I, 55341 <=I <= N). Flag ``TAIL`` is optional. If it is included, it must be the 5535literal ``tail``. 5536 5537The types of the arguments must match the corresponding types of the function 5538signature associated with ``%fF``. The return type of ``%f`` must be void. 5539 5540TAIL is encoded into calling convention value ``CC`` as follows: 5541 5542====== == 5543TAIL CC 5544====== == 5545"" 0 5546"tail" 1 5547====== == 5548 5549**Constraints**:: 5550 5551 AA == AbbrevIndex(A) & 5552 N >= 0 & 5553 TypeOfFcn(%fF) == void (T1, ... , TN) & 5554 TypeOf(AI) == TI for all I, 1 <= I <= N 5555 5556**Updates**:: 5557 5558 ++NumValuedInsts; 5559 5560**Examples**:: 5561 5562 72:0| 3: <8, 3, 0, 1, 0> | declare external 5563 | | void @f0(i32, i64, i32); 5564 ... 5565 116:0| 1: <65535, 12, 2> | function void @f1(i32 %p0) { 5566 | | // BlockID = 12 5567 124:0| 3: <1, 1> | blocks 1; 5568 126:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5569 136:0| 3: <1, 2> | i64: 5570 138:4| 3: <4, 2> | %c0 = i64 1; 5571 141:0| 0: <65534> | } 5572 | | %b0: 5573 144:0| 3: <34, 0, 4, 2, 1, 2> | call void 5574 | | @f0(i32 %p0, i64 %c0, i32 %p0); 5575 150:2| 3: <10> | ret void; 5576 152:0| 0: <65534> | } 5577 5578Direct Function Call 5579^^^^^^^^^^^^^^^^^^^^ 5580 5581The direct function call calls a defined function address whose type signature 5582returns a value. 5583 5584**Syntax**:: 5585 5586 %vN = TAIL call RT %fF (T1 A1, ... , TM AM); <A> 5587 5588 5589**Record**:: 5590 5591 AA: <34, CC, F, AA1, ... , AAM> 5592 5593**Semantics**: 5594 5595The direct function call calls a defined function address ``%fF`` whose type 5596signature returned is not type void. The arguments ``A1`` through ``AM`` are 5597passed in the order specified. The type of argument ``AI`` must be type ``TI`` 5598(for all I, 1 <= I <= N). Flag ``TAIL`` is optional. If it is included, it must 5599be the literal ``tail``. 5600 5601The types of the arguments must match the corresponding types of the function 5602signature associated with ``%fF``. The return type must match ``RT``. 5603 5604Each parameter type ``TI``, and return type ``RT``, must either be a primitive 5605type, or a vector type. If the parameter type is an integer type, it must 5606either be i32 or i64. 5607 5608TAIL is encoded into calling convention value ``CC`` as follows: 5609 5610====== == 5611TAIL CC 5612====== == 5613"" 0 5614"tail" 1 5615====== == 5616 5617**Constraints**:: 5618 5619 AA == AbbrevIndex(A) & 5620 N >= 0 & 5621 TypeOfFcn(%fF) == RT (T1, ... , TN) & 5622 TypeOf(AI) == TI for all I, 1 <= I <= M & 5623 IsFcnArgType(TI) for all I, 1 <= I <= M & 5624 IsFcnArgType(RT) & 5625 N == NumValuedInsts 5626 5627**Updates**:: 5628 5629 ++NumValuedInsts; 5630 TypeOf(%vN) = RT; 5631 5632**Examples**:: 5633 5634 72:0| 3: <8, 2, 0, 1, 0> | declare external 5635 | | i32 @f0(i32, i64, i32); 5636 ... 5637 116:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { 5638 | | // BlockID = 12 5639 124:0| 3: <1, 1> | blocks 1; 5640 126:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5641 136:0| 3: <1, 1> | i64: 5642 138:4| 3: <4, 2> | %c0 = i64 1; 5643 141:0| 0: <65534> | } 5644 | | %b0: 5645 144:0| 3: <34, 0, 4, 2, 1, 2> | %v0 = call i32 5646 | | @f0(i32 %p0, i64 %c0, i32 %p0); 5647 150:2| 3: <34, 1, 4, 1> | %v1 = tail call i32 @f1(i32 %v0); 5648 155:0| 3: <10, 2> | ret i32 %v0; 5649 157:4| 0: <65534> | } 5650 5651Indirect Procedure Call 5652^^^^^^^^^^^^^^^^^^^^^^^ 5653 5654The indirect procedure call calls a function using an indirect function address, 5655and whose type signature is assumed to return type void. It is different from 5656the direct procedure call because we can't use the type signature of the 5657corresponding direct function address to type check the construct. 5658 5659**Syntax**:: 5660 5661 TAIL call void V (T1 A1, ... , TN AN); <A> 5662 5663**Record**:: 5664 5665 AA: <44, CC, TV, VV, AA1, ... , AAN> 5666 5667**Semantics**: 5668 5669The indirect call procedure calls a function using value ``V`` that is an 5670indirect function address, and whose type signature is assumed to return type 5671void. The arguments ``A1`` through ``AN`` are passed in the order 5672specified. The type of argument ``AI`` must be type ``TI`` (for all I, 1 <= I <= 5673N). Flag ``TAIL`` is optional. If it is included, it must be the literal 5674``tail``. 5675 5676Each parameter type ``TI`` (1 <= I <= N) must either be a primitive type, or a 5677vector type. If the parameter type is an integer type, it must either be i32 5678or i64. 5679 5680TAIL is encoded into calling convention value ``CC`` as follows: 5681 5682====== == 5683TAIL CC 5684====== == 5685"" 0 5686"tail" 1 5687====== == 5688 5689The type signature of the called procedure is assumed to be:: 5690 5691 void (T1, ... , TN) 5692 5693It isn't necessary to define this type in the :ref:`types 5694block<link_for_types_block_section>`, since the type is inferred rather than 5695used. 5696 5697**Constraints**:: 5698 5699 AA == AbbrevIndex(A) & 5700 N >= 0 & 5701 TV = TypeID(void) & 5702 AbsoluteIndex(V) >= NumFuncAddresses & 5703 TypeOf(AI) == TI for all I, 1 <= I <= N & 5704 IsFcnArgType(TI) for all I, 1 <= I <= N 5705 5706**Updates**:: 5707 5708 ++NumValuedInsts; 5709 5710**Examples**:: 5711 5712 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 5713 48:0| 3: <1, 3> | count 3; 5714 50:4| 3: <2> | @t0 = void; 5715 52:2| 3: <7, 32> | @t1 = i32; 5716 55:4| 3: <21, 0, 0, 1> | @t2 = void (i32); 5717 59:4| 0: <65534> | } 5718 ... 5719 92:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { 5720 | | // BlockID = 12 5721 100:0| 3: <1, 1> | blocks 1; 5722 102:4| 1: <65535, 11, 2> | constants { // BlockID = 11 5723 112:0| 3: <1, 1> | i32: 5724 114:4| 3: <4, 2> | %c0 = i32 1; 5725 117:0| 0: <65534> | } 5726 | | %b0: 5727 120:0| 3: <44, 0, 2, 0, 1> | call void %p0(i32 %c0); 5728 125:4| 3: <10> | ret void; 5729 127:2| 0: <65534> | } 5730 5731Indirect Function Call 5732^^^^^^^^^^^^^^^^^^^^^^ 5733 5734The indirect function call calls a function using a value that is an indirect 5735function address. It is different from the direct function call because we can't 5736use the type signature of the corresponding literal function address to type 5737check the construct. 5738 5739**Syntax**:: 5740 5741 %vN = TAIL call RT V (T1 A1, ... , TM AM); <A> 5742 5743**Record**:: 5744 5745 AA: <34, CC, RRT, VV, AA1, ... , AAM> 5746 5747**Semantics**: 5748 5749The indirect function call calls a function using a value ``V`` that is an 5750indirect function address, and is assumed to return type ``RT``. The arguments 5751``A1`` through ``AM`` are passed in the order specified. The type of argument 5752``AI`` must be type ``TI`` (for all I, 1 <= I <= N). Flag ``TAIL`` is 5753optional. If it is included, it must be the literal ``tail``. 5754 5755Each parameter type ``TI`` (1 <= I <= M), and return type ``RT``, must either be 5756a primitive type, or a vector type. If the parameter type is an integer type, 5757it must either be i32 or i64. 5758 5759TAIL is encoded into calling convention value ``CC`` as follows: 5760 5761====== == 5762TAIL CC 5763====== == 5764'' 0 5765'tail' 1 5766====== == 5767 5768The type signature of the called function is assumed to be:: 5769 5770 RT (T1, ... , TN) 5771 5772It isn't necessary to define this type in the :ref:`types 5773block<link_for_types_block_section>`, since the type is inferred rather than 5774used. 5775 5776**Constraints**:: 5777 5778 AA == AbbrevIndex(A) & 5779 RRT = TypeID(RT) & 5780 VV = RelativeIndex(V) & 5781 M >= 0 & 5782 AbsoluteIndex(V) >= NumFcnAddresses & 5783 TypeOf(AI) == TI for all I, 1 <= I <= M & 5784 IsFcnArgType(TI) for all I, 1 <= I <= M & 5785 IsFcnArgType(RT) & 5786 N == NumValuedInsts 5787 5788**Updates**:: 5789 5790 ++NumValuedInsts; 5791 TypeOf(%vN) = RT; 5792 5793**Examples**:: 5794 5795 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 5796 48:0| 3: <1, 6> | count 6; 5797 50:4| 3: <7, 32> | @t0 = i32; 5798 53:6| 3: <3> | @t1 = float; 5799 55:4| 3: <4> | @t2 = double; 5800 57:2| 3: <21, 0, 0, 0, 1, 2> | @t3 = i32 (i32, float, double); 5801 62:6| 3: <21, 0, 0, 1, 2> | @t4 = i32 (float, double); 5802 67:4| 3: <2> | @t5 = void; 5803 69:2| 0: <65534> | } 5804 ... 5805 104:0| 1: <65535, 12, 2> | function 5806 | | i32 5807 | | @f0(i32 %p0, float %p1, 5808 | | double %p2) { 5809 | | // BlockID = 12 5810 112:0| 3: <1, 1> | blocks 1; 5811 | | %b0: 5812 114:4| 3: <44, 0, 3, 0, 2, 1> | %v0 = call i32 5813 | | %p0(float %p1, double %p2); 5814 120:6| 3: <10, 1> | ret i32 %v0; 5815 123:2| 0: <65534> | } 5816 5817.. _link_for_memory_blocks_and_alignment_section: 5818 5819Memory Blocks and Alignment 5820=========================== 5821 5822In general, variable and heap allocated data are represented as byte addressable 5823memory blocks. Alignment is always a power of 2, and defines an expectation on 5824the memory address. That is, an alignment is met if the memory address is 5825(evenly) divisible by the alignment. Note that alignment of 0 is never allowed. 5826 5827 Alignment plays a role at two points: 5828 5829* When you create a local/global variable 5830 5831* When you load/store data using a pointer. 5832 5833PNaClAsm allows most types to be placed at any address, and therefore can 5834have alignment of 1. However, many architectures can load more efficiently 5835if the data has an alignment that is larger than 1. As such, choosing a larger 5836alignment can make load/stores more efficient. 5837 5838On loads and stores, the alignment in the instruction is used to communicate 5839what assumptions the :ref:`PNaCl translator<link_for_pnacl_translator>` can 5840make when choosing the appropriate machine instructions. If the alignment is 1, 5841it can't assume anything about the memory address used by the instruction. When 5842the alignment is greater than one, it can use that information to potentially 5843chose a more efficient sequence of instructions to do the load/store. 5844 5845When laying out data within a variable, one also considers alignment. The reason 5846for this is that if you want an address to be aligned, within the bytes defining 5847the variable, you must choose an alignment for the variable that guarantees that 5848alignment. 5849 5850In PNaClAsm, the valid load/store alignments are: 5851 5852=========== ============== 5853Type Alignment 5854=========== ============== 5855i1 1 5856i8 1 5857i16 1 5858i32 1 5859i64 1 5860Float 1, 4 5861Double 1, 8 5862<4 x i1> not applicable 5863<8 x i1> not applicable 5864<16 x i1> not applicable 5865<16 x i8> 1 5866<8 x i16> 2 5867<4 x i32> 4 5868<4 x float> 4 5869=========== ============== 5870 5871Note that only vectors do not have an alignment value of 1. Hence, they can't be 5872placed at an arbitrary memory address. Also, since vectors on ``i1`` can't be 5873loaded/stored, the alignment is not applicable for these types. 5874 5875.. _link_for_intrinsic_functions_section: 5876 5877Intrinsic Functions 5878=================== 5879 5880Intrinsic functions are special in PNaClAsm. They are implemented as specially 5881named (external) function calls. The purpose of these intrinsic functions is to 5882extend the PNaClAsm instruction set with additional functionality that is 5883architecture specific. Hence, they either can't be implemented within PNaClAsm, 5884or a non-architecture specific implementation may be too slow on some 5885architectures. In such cases, the :ref:`PNaCl 5886translator<link_for_pnacl_translator>` must fill in the corresponding 5887implementation, since only it knows the architecture it is compiling down to. 5888 5889Examples of intrinsic function calls are for concurrent operations, atomic 5890operations, bulk memory moves, thread pointer operations, and long jumps. 5891 5892It should be noted that calls to intrinsic functions do not have the same 5893calling type constraints as ordinary functions. That is, an intrinsic can use 5894any integer type for arguments/results, unlike ordinary functions (which 5895restrict integer types to ``i32`` and ``i64``). 5896 5897See the :doc:`PNaCl bitcode reference manual<pnacl-bitcode-abi>` for the full 5898set of intrinsic functions allowed. Note that in PNaClAsm, all pointer types to 5899an (LLVM) intrinsic function is converted to type i32. 5900 5901.. _link_for_support_functions_section: 5902 5903Support Functions 5904================= 5905 5906Defines functions used to convert syntactic representation to values in the 5907corresponding record. 5908 5909SignRotate 5910---------- 5911 5912The SignRotate function encodes a signed integer in an easily compressible 5913form. This is done by rotating the sign bit to the rightmost bit, rather than 5914the leftmost bit. By doing this rotation, both small positive and negative 5915integers are small (unsigned) integers. Therefore, all small integers can be 5916encoded as a small (unsigned) integers. 5917 5918The definition of SignRotate(N) is: 5919 5920======== ============= ========= 5921Argument Value Condition 5922======== ============= ========= 5923N abs(N)<<1 N >= 0 5924N abs(N)<<1 + 1 N < 0 5925======== ============= ========= 5926 5927.. _link_for_absolute_index_section: 5928 5929AbsoluteIndex 5930------------- 5931 5932Bitcode IDs of the forms ``@fN``, ``@gN``, ``%pN``, ``%cN``, and ``%vN``, are 5933combined into a single index space. This can be done because of the ordering 5934imposed by PNaClAsm. All function address bitcode IDs must be defined before any 5935of the other forms of bitcode IDs. All global address bitcode IDs must be 5936defined before any local bitcode IDs. Within a function block, the parameter 5937bitcode IDs must be defined before constant IDs, and constant IDs must be 5938defined before instruction value IDs. 5939 5940Hence, within a function block, it is safe to refer to all of these 5941bitcode IDs using a single *absolute* index. The absolute index for 5942each kind of bitcode ID is computed as follows: 5943 5944========== =================================================================== 5945Bitcode ID AbsoluteIndex 5946========== =================================================================== 5947@tN N 5948@fN N 5949@gN N + NumFcnAddresses 5950@pN N + NumFcnAddresses + NumGlobalAddresses 5951@cN N + NumFcnAddresses + NumGlobalAddresses + NumParams 5952@vN N + NumFcnAddresses + NumGlobalAddresses + NumParams + NumFcnConsts 5953========== =================================================================== 5954 5955.. _link_for_relative_index: 5956 5957RelativeIndex 5958------------- 5959 5960Relative indices are used to refer to values within instructions of a function. 5961The relative index of an ID is always defined in terms of the index associated 5962with the next value generating instruction. It is defined as follows:: 5963 5964 RelativeIndex(J) = AbsoluteIndex(%vN) - AbsoluteIndex(J) 5965 5966where:: 5967 5968 N = NumValuedInsts 5969 5970AbbrevIndex 5971----------- 5972 5973This function converts user-defined abbreviation indices to the corresponding 5974internal abbreviation index saved in the bitcode file. It adds 4 to its 5975argument, since there are 4 predefined internal abbreviation indices (0, 1, 2, 5976and 3). 5977 5978========= ============== 5979N AbbrevIndex(N) 5980========= ============== 5981undefined 3 5982%aA A + 4 5983@aA A + 4 5984========= ============== 5985 5986Log2 5987---- 5988 5989This is the 32-bit log2 value of its argument. 5990 5991BitSizeOf 5992--------- 5993 5994Returns the number of bits needed to represent its argument (a type). 5995 5996======= ================ 5997T BitSizeOf 5998======= ================ 5999i1 1 6000i8 8 6001i16 16 6002i32 32 6003i64 64 6004float 32 6005double 64 6006<N X T> N * BitSizeOf(T) 6007======= ================ 6008 6009UnderlyingType 6010-------------- 6011 6012Returns the primitive type of the type construct. For primitive types, the 6013*UnderlyingType* is itself. For vector types, the base type of the vector is the 6014underlying type. 6015 6016UnderlyingCount 6017--------------- 6018 6019Returns the size of the vector if given a vector, and 0 for primitive types. 6020Note that this function is used to check if two vectors are of the same size. 6021It is also used to test if two types are either primitive (i.e. UnderlyingCount 6022returns 0 for both types) or are vectors of the same size (i.e. UnderlyingCount 6023returns the same non-zero value). 6024 6025IsInteger 6026--------- 6027 6028Returns true if the argument is in {i1, i8, i16, i32, i64}. 6029 6030IsFloat 6031------- 6032 6033Returns true if the argument is in {``float``, ``double``}. 6034 6035IsVector 6036-------- 6037 6038Returns true if the argument is a vector type. 6039 6040IsPrimitive 6041----------- 6042 6043Returns true if the argument is a primitive type. That is:: 6044 6045 IsPrimitive(T) == IsInteger(T) or IsFloat(T) 6046 6047IsFcnArgType 6048------------ 6049 6050Returns true if the argument is a primitive type or a vector type. Further, 6051if it is an integer type, it must be i32 or i64. That is:: 6052 6053 IsFcnArgType(T) = (IsInteger(T) and (i32 = BitSizeOf(T) 6054 or i64 == BitSizeOf(T))) 6055 or IsFloat(T) or IsVector(T) 6056 6057.. _link_for_abbreviations_section: 6058 6059Abbreviations 6060============= 6061 6062Abbreviations are used to convert PNaCl records to a sequence of bits. PNaCl 6063uses the same strategy as `LLVM's bitcode file format 6064<http://llvm.org/docs/BitCodeFormat.html>`_. See that document for more 6065details. 6066 6067It should be noted that we replace LLVM's header (called the *Bitcode Wrapper 6068Format*) with the bytes of the :ref:`PNaCl record 6069header<link_for_header_record_section>`. In addition, PNaCl bitcode files do 6070not allow *blob* abbreviation. 6071 6072.. _link_for_abbreviations_block_section: 6073 6074Abbreviations Block 6075------------------- 6076 6077The abbreviations block is the first block in the module build. The 6078block is divided into sections. Each section is a sequence of records. Each 6079record in the sequence defines a user-defined abbreviation. Each section 6080defines abbreviations that can be applied to all (succeeding) blocks of a 6081particular kind. These abbreviations are denoted by the (global) ID of the form 6082*@aN*. 6083 6084In terms of `LLVM's bitcode file format 6085<http://llvm.org/docs/BitCodeFormat.html>`_, the abbreviations block is called a 6086*BLOCKINFO* block. Records *SETBID* and *DEFINE_ABBREV* are the only records 6087allowed in PNaCl's abbreviation block (i.e. it doesn't allow *BLOCKNAME* and 6088*SETRECORDNAME* records). 6089 6090TODO 6091---- 6092 6093Extend this document to describe PNaCl's bitcode bit sequencer 6094without requiring the reader to refer to `LLVM's bitcode file 6095format <http://llvm.org/docs/BitCodeFormat.html>`_. 6096
