| =============================== |
| Contents Of PNaCl Bitcode Files |
| =============================== |
| |
| .. contents:: |
| :local: |
| :backlinks: none |
| :depth: 3 |
| |
| |
| Introduction |
| ============ |
| |
| This document is a reference manual for the contents of PNaCl bitcode files. We |
| define bitcode files via three layers. The first layer is presented using |
| assembly language *PNaClAsm*, and defines the textual form of the bitcode |
| file. The textual form is then lowered to a sequence of :ref:`PNaCl |
| records<link_for_pnacl_records>`. The final layer applies abbreviations that |
| convert each PNaCl record into a corresponding sequence of bits. |
| |
| .. image:: /images/PNaClBitcodeFlow.png |
| |
| PNaClAsm uses a *static single assignment* (SSA) based representation that |
| requires generated results to have a single (assignment) source. |
| |
| PNaClAsm focuses on the semantic content of the file, not the bit-encoding of |
| that content. However, it does provide annotations that allow one to specify how |
| the :ref:`abbreviations<link_for_abbreviations_section>` are used to convert |
| PNaCl records into the sequence of bits. |
| |
| Each construct in PNaClAsm defines a corresponding :ref:`PNaCl |
| record<link_for_pnacl_records>`. A PNaCl bitcode file is simply a sequence of |
| PNaCl records. The goal of PNaClAsm is to make records easier to read, and not |
| to define a high-level user programming language. |
| |
| PNaCl records are an abstract encoding of structured data, similar to XML. Like |
| XML, A PNaCl record has a notion of a tag (i.e. the first element in a record, |
| called a *code*). PNaCl records can be nested. Nesting is defined by a |
| corresponding :ref:`enter<link_for_enter_block_record_section>` and |
| :ref:`exit<link_for_exit_block_record_section>` block record. |
| |
| These block records must be used like balanced parentheses to define the block |
| structure that is imposed on top of records. Each exit record must be preceded |
| by a corresponding enter record. Blocks can be nested by nesting enter/exit |
| records appropriately. |
| |
| The *PNaCl bitcode writer* takes the sequence of records, defined by a PNaClAsm |
| program, and converts each record into a (variable-length) sequence of bits. The |
| output of each bit sequence is appended together. The resulting generated |
| sequence of bits is the contents of the PNaCl bitcode file. |
| |
| For every kind of record, there is a method for converting records into bit |
| sequences. These methods correspond to a notion of |
| :ref:`abbreviations<link_for_abbreviations_section>`. Each abbreviation defines |
| a specific bit sequence conversion to be applied. |
| |
| Abbreviations can be user-defined, but there are also predefined defaults. All |
| user-specified abbreviations are included in the generated bitcode |
| file. Predefined defaults are not. |
| |
| Each abbreviation defines how a record is converted to a bit sequence. The |
| :ref:`PNaCl translator<link_for_pnacl_translator>` uses these abbreviations |
| to convert the bit sequence back to the corresponding sequence of PNaCl records. |
| As a result, all records have an abbreviation (user or default) associated with |
| them. |
| |
| Conceptually, abbreviations are used to define how to pack the contents of |
| records into bit sequences. The main reason for defining abbreviations is to |
| save space. The default abbreviations are simplistic and are intended to handle |
| all possible records. The default abbreviations do not really worry about being |
| efficient, in terms of the number of bits generated. |
| |
| By separating the concepts of PNaCl records and abbreviations, the notion of |
| data compression is cleanly separated from semantic content. This allows |
| different use cases to decide how much effort should be spent on compressing |
| records. |
| |
| For a JIT compiler that produces bitcode, little (if any) compression should be |
| applied. In fact, the API to the JIT may just be the records themselves. The |
| goal of a JIT is to perform the final translation to machine code as quickly as |
| possible. |
| |
| On the other hand, when delivering across the web, one may want to compress the |
| sequence of bits considerably, to reduce costs in delivering web pages. Note |
| that :ref:`pnacl-compress<pnacl_compress>` is provided as part of the SDK to do |
| this job. |
| |
| Data Model |
| ========== |
| |
| The data model for PNaCl bitcode is fixed at little-endian ILP32: pointers are |
| 32 bits in size. 64-bit integer types are also supported natively via the i64 |
| type (for example, a front-end can generate these from the C/C++ type ``long |
| long``). |
| |
| Integers are assumed to be modeled using two's complement. Floating point |
| support is fixed at :ref:`IEEE 754<c_cpp_floating_point>` 32-bit and 64-bit |
| values (float and double, respectively). |
| |
| PNaCl Blocks |
| ============ |
| |
| Blocks are used to organize records in the bitcode file. The kinds of blocks |
| defined in PNaClAsm are: |
| |
| Module block |
| A top-level block defining the program. The :ref:`module |
| block<link_for_module_block>` defines global information used by the program, |
| followed by function blocks defining the implementation of functions within |
| the program. All other blocks (listed below) must appear within a module |
| block. |
| |
| Types block |
| The :ref:`types block<link_for_types_block_section>` defines the set of types |
| used by the program. All types used in the program must be defined in the |
| types block. These types consist of primitive types as well as high level |
| constructs such as vectors and function signatures. |
| |
| Globals block |
| The :ref:`globals block<link_for_globals_block_section>` defines the set of |
| addresses of global variables and constants used by the program. It also |
| defines how each global (associated with the global address) is initialized. |
| |
| Valuesymtab block |
| The :ref:`valuesymtab block<link_for_valuesymtab_block_section>` defines |
| textual names for external function addresses. |
| |
| Function block |
| Each function (implemented) in a program has its own :ref:`function |
| block<link_for_function_blocks_section>` that defines the implementation of |
| the corresponding function. |
| |
| Constants block |
| Each implemented function that uses constants in its instructions defines a |
| :ref:`constants block<link_for_constants_block_section>`. Constants blocks |
| appear within the corresponding function block of the implemented function. |
| |
| Abbreviations block |
| Defines global abbreviations that are used to compress PNaCl records. The |
| :ref:`abbreviations block<link_for_abbreviations_block_section>` is segmented |
| into multiple sections, one section for each kind of block. This block appears |
| at the beginning of the module block. |
| |
| This section is only intended as a high-level discussion of blocks. Later |
| sections will dive more deeply into the constraints on how blocks must be laid |
| out. This section only presents the overall concepts of what kinds of data are |
| stored in each of the blocks. |
| |
| A PNaCl program consists of a :ref:`header |
| record<link_for_header_record_section>` and a :ref:`module |
| block<link_for_module_block>`. The header record defines a sequence of bytes |
| uniquely identifying the file as a bitcode file. The module block defines the |
| program to run. |
| |
| Each block, within a bitcode file, defines values. These values are associated |
| with IDs. Each type of block defines different kinds of IDs. The |
| :ref:`module<link_for_module_block>`, |
| :ref:`types<link_for_types_block_section>`, |
| :ref:`globals<link_for_globals_block_section>`, and |
| :ref:`abbreviations<link_for_abbreviations_block_section>` blocks define global |
| identifiers, and only a single instance can appear. The |
| :ref:`function<link_for_function_blocks_section>` and |
| :ref:`constant<link_for_constants_block_section>` blocks define local |
| identifiers, and can have multiple instances (one for each implemented |
| function). |
| |
| The only records in the module block that define values, are :ref:`function |
| address<link_for_function_address_section>` records. Each function address |
| record defines a different function address, and the :ref:`type |
| signature<link_for_function_type>` associated with that function address. |
| |
| Each :ref:`function block<link_for_function_blocks_section>` defines the |
| implementation of a single function. Each function block defines the |
| intermediate representation of the function, consisting of basic blocks and |
| instructions. If constants are used within instructions, they are defined in a |
| :ref:`constants block<link_for_constants_block_section>`, nested within the |
| corresponding function block. |
| |
| All function blocks are associated with a corresponding function address. This |
| association is positional rather than explicit. That is, the Nth function block |
| in a module block corresponds to the Nth |
| :ref:`defining<link_for_function_address_section>` (rather than declared) |
| function address record in the module block. |
| |
| Hence, within a function block, there is no explicit reference to the function |
| address the block defines. For readability, PNaClAsm uses the corresponding |
| function signature, associated with the corresponding function address record, |
| even though that data does not appear in the corresponding records. |
| |
| .. _link_for_pnacl_records: |
| |
| PNaCl Records |
| ============= |
| |
| A PNaCl record is a non-empty sequence of unsigned, 64-bit, integers. A record |
| is identified by the record *code*, which is the first element in the |
| sequence. Record codes are unique within a specific kind of block, but are not |
| necessarily unique across different kinds of blocks. The record code acts as the |
| variant discriminator (i.e. tag) within a block, to identify what kind of record |
| it is. |
| |
| Record codes that are local to a specific kind of block are small values |
| (starting from zero). In an ideal world, they would be a consecutive sequence of |
| integers, starting at zero. However, the reality is that PNaCl records evolved |
| over time (and actually started as `LLVM records |
| <http://llvm.org/docs/BitCodeFormat.html>`_). For backward compatibility, |
| obsolete numbers have not been reused, leaving gaps in the actual record code |
| values used. |
| |
| Global record codes are record codes that have the same meaning in multiple |
| kinds of blocks. To separate global record codes from local record codes, large |
| values are used. Currently there are four :ref:`global record |
| codes<link_for_global_record_codes>`. To make these cases clear, and to leave |
| ample room for future growth in PNaClAsm, these special records have record |
| codes close to the value 2\ :sup:`16`\ . Note: Well-formed PNaCl bitcode files |
| do not have record codes >= 2\ :sup:`16`\ . |
| |
| A PNaCl record is denoted as follows: :: |
| |
| a: <v0, v1, ... , vN> |
| |
| The value ``v0`` is the record code. The remaining values, ``v1`` through |
| ``vN``, are parameters that fill in additional information needed by the |
| construct it represents. All records must have a record code. Hence, empty PNaCl |
| records are not allowed. ``a`` is the index to the abbreviation used to convert |
| the record to a bit sequence. |
| |
| While most records (for a given record code) have the same length, it is not |
| true of all record codes. Some record codes can have arbitrary length. In |
| particular, function type signatures, call instructions, phi instructions, |
| switch instructions, and global variable initialization records all have |
| variable length. The expected length is predefined and part of the PNaClAsm |
| language. See the corresponding construct (associated with the record) to |
| determine the expected length. |
| |
| The *PNaCl bitstream writer*, which converts records to bit sequences, does |
| this by writing out the abbreviation index used to encode the record, followed |
| by the contents of the record. The details of this are left to the section on |
| :ref:`abbreviations<link_for_abbreviations_section>`. However, at the record |
| level, one important aspect of this appears in :ref:`block |
| enter<link_for_enter_block_record_section>` records. These records must define |
| how many bits are required to hold abbreviation indices associated with records |
| of that block. |
| |
| .. _link_for_default_abbreviations: |
| |
| Default Abbreviations |
| ===================== |
| |
| There are 4 predefined (default) abbreviation indices, used as the default |
| abbreviations for PNaCl records. They are: |
| |
| 0 |
| Abbreviation index for the abbreviation used to bit-encode an exit block |
| record. |
| |
| 1 |
| Abbreviation index for the abbreviation used to bit-encode an enter block |
| record. |
| |
| 2 |
| Abbreviation index for the abbreviation used to bit-encode a user-defined |
| abbreviation. Note: User-defined abbreviations are also encoded as records, |
| and hence need an abbreviation index to bit-encode them. |
| |
| 3 |
| Abbreviation index for the default abbreviation to bit-encode all other |
| records in the bitcode file. |
| |
| A block may, in addition, define a list of block specific, user-defined, |
| abbreviations (of length ``U``). The number of bits ``B`` specified for an enter |
| record must be sufficiently large such that:: |
| |
| 2**B >= U + 4 |
| |
| In addition, the upper limit for ``B`` is ``16``. |
| |
| PNaClAsm requires specifying the number of bits needed to read abbreviations as |
| part of the enter block record. This allows the PNaCl bitcode reader/writer to |
| use the specified number of bits to encode abbreviation indices. |
| |
| PNaCl Identifiers |
| ================= |
| |
| A program is defined by a :ref:`module block<link_for_module_block>`. Blocks can |
| be nested within other blocks, including the module block. Each block defines a |
| sequence of records. |
| |
| Most of the records, within a block, also define unique values. Each unique |
| value is given a corresponding unique identifier (i.e. *ID*). In PNaClAsm, each |
| kind of block defines its own kind of identifiers. The names of these |
| identifiers are defined by concatenating a prefix character (``'@'`` or |
| ``'%'``), the kind of block (a single character), and a suffix index. The suffix |
| index is defined by the positional location of the defined value within the |
| records of the corresponding block. The indices are all zero based, meaning that |
| the first defined value (within a block) is defined using index 0. |
| |
| Identifiers are categorized into two types, *local* and *global*. Local |
| identifiers are identifiers that are associated with the implementation of a |
| single function. In that sense, they are local to the block they appear in. |
| |
| All other identifiers are global, and can appear in multiple blocks. This split |
| is intentional. Global identifiers are used by multiple functions, and therefore |
| must be known in all function implementations. Local identifiers only apply to a |
| single function, and can be reused between functions. The :ref:`PNaCl |
| translator<link_for_pnacl_translator>` uses this separation to parallelize the |
| compilation of functions. |
| |
| Note that local abbreviation identifiers are unique to the block they appear |
| in. Global abbreviation identifiers are only unique to the block type they are |
| defined for. Different block types can reuse global abbreviation identifiers. |
| |
| Global identifiers use the prefix character ``'@'`` while local identifiers use |
| the prefix character ``'%'``. |
| |
| Note that by using positional location to define identifiers (within a block), |
| the values defined in PNaCl bitcode files need not be explicitly included in the |
| bitcode file. Rather, they are inferred by the (ordered) position of the record |
| in the block. This is also intentional. It is used to reduce the amount of data |
| that must be (explicitly) passed to the :ref:`PNaCl |
| translator<link_for_pnacl_translator>`, when downloaded into Chrome. |
| |
| In general, most of the records within blocks are assumed to be topologically |
| sorted, putting value definitions before their uses. This implies that records |
| do not need to encode data if they can deduce the corresponding information from |
| their uses. |
| |
| The most common use of this is that many instructions use the type of their |
| operands to determine the type of the instruction. Again, this is |
| intentional. It allows less information to be stored. |
| |
| However, for function blocks (which define instructions), a topological sort may |
| not exist. Loop carried value dependencies simply do not allow topologically |
| sorting. To deal with this, function blocks have a notion of (instruction value) |
| :ref:`forward type |
| declarations<link_for_forward_type_declaration_section>`. These declarations |
| must appear before any of the uses of that value, if the (instruction) value is |
| defined later in the function than its first use. |
| |
| The kinds of identifiers used in PNaClAsm are: |
| |
| @a |
| Global abbreviation identifier. |
| |
| %a |
| Local abbreviation identifier. |
| |
| %b |
| Function basic block identifier. |
| |
| %c |
| Function constant identifier. |
| |
| @f |
| Global function address identifier. |
| |
| @g |
| Global variable/constant address identifier. |
| |
| %p |
| Function parameter identifier. |
| |
| @t |
| Global type identifier. |
| |
| %v |
| Value generated by an instruction in a function block. |
| |
| |
| Conventions For Describing Records |
| ================================== |
| |
| PNaClAsm is the textual representation of :ref:`PNaCl |
| records<link_for_pnacl_records>`. Each PNaCl record is described by a |
| corresponding PNaClAsm construct. These constructs are described using syntax |
| rules, and semantics on how they are converted to records. Along with the rules, |
| is a notion of :ref:`global state<link_for_global_state_section>`. The global |
| state is updated by syntax rules. The purpose of the global state is to track |
| positional dependencies between records. |
| |
| For each PNaCl construct, we define multiple sections. The **Syntax** |
| section defines a syntax rule for the construct. The **Record** section |
| defines the corresponding record associated with the syntax rule. The |
| **Semantics** section describes the semantics associated with the record, in |
| terms of data within the global state and the corresponding syntax. It also |
| includes other high-level semantics, when appropriate. |
| |
| The **Constraints** section (if present) defines any constraints associated |
| with the construct, including the global state. The **Updates** section (if |
| present) defines how the global state is updated when the construct is |
| processed. The **Examples** section gives one or more examples of using the |
| corresponding PNaClAsm construct. |
| |
| Some semantics sections use functions to compute values. The meaning of |
| functions can be found in :ref:`support |
| functions<link_for_support_functions_section>`. |
| |
| The syntax rule may include the |
| :ref:`abbreviation<link_for_abbreviations_section>` to use, when converting to a |
| bit-sequence. These abbreviations, if allowed, are at the end of the construct, |
| and enclosed in ``<`` and ``>`` brackets. These abbreviations are optional in |
| the syntax, and can be omitted. If they are used, the abbreviation brackets are |
| part of the actual syntax of the construct. If the abbreviation is omitted, the |
| default abbreviation index is used. To make it clear that abbreviations are |
| optional, syntax rules separate abbreviations using plenty of whitespace. |
| |
| Within a syntax rule, lower case characters are literal values. Sequences of |
| upper case alphanumeric characters are named values. If we mix lower and upper |
| case letters within a name appearing in a syntax rule, the lower case letters |
| are literal while the upper case sequence of alphanumeric characters denote rule |
| specific values. The valid values for each of these names will be defined in |
| the corresponding semantics and constraints subsections. |
| |
| For example, consider the following syntax rule:: |
| |
| %vN = add T O1, O2; <A> |
| |
| This rule defines a PNaClAsm add instruction. This construct defines an |
| instruction that adds two values (``O1`` and ``O2``) to generate instruction |
| value ``%vN``. The types of the arguments, and the result, are all of type |
| ``T``. If abbreviation ID ``A`` is present, the record is encoded using that |
| abbreviation. Otherwise the corresponding :ref:`default abbreviation |
| index<link_for_default_abbreviations>` is used. |
| |
| To be concrete, the syntactic rule above defines the structure of the following |
| PNaClAsm examples:: |
| |
| %v10 = add i32 %v1, %v2; <@a5> |
| %v11 = add i32 %v10, %v3; |
| |
| In addition to specifying the syntax, each syntax rule can also also specify the |
| contents of the corresponding record in the corresponding record subsection. In |
| simple cases, the elements of the corresponding record are predefined (literal) |
| constants. Otherwise the record element is an identifier from another subsection |
| associated with the construct. |
| |
| Factorial Example |
| ================= |
| |
| This section provides a simple example of a PNaCl bitcode file. Its contents |
| describe a bitcode file that only defines a function to compute the factorial |
| value of a number. |
| |
| In C, the factorial function can be defined as:: |
| |
| int fact(int n) { |
| if (n == 1) return 1; |
| return n * fact(n-1); |
| } |
| |
| Compiling this into a PNaCl bitcode file, and dumping out its contents with |
| utility :ref:`pnacl-bcdis<pnacl-bcdis>`, the corresponding output is:: |
| |
| 0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69) |
| | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2 |
| | 0> | |
| 16:0|1: <65535, 8, 2> |module { // BlockID = 8 |
| 24:0| 3: <1, 1> | version 1; |
| 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 |
| 36:0| 0: <65534> | } |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <2> | @t1 = void; |
| 55:4| 3: <21, 0, 0, 0> | @t2 = i32 (i32); |
| 59:4| 3: <7, 1> | @t3 = i1; |
| 62:0| 0: <65534> | } |
| 64:0| 3: <8, 2, 0, 0, 0> | define external i32 @f0(i32); |
| 68:6| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 76:0| 3: <5, 0> | count 0; |
| 78:4| 0: <65534> | } |
| 80:0| 1: <65535, 14, 2> | valuesymtab { // BlockID = 14 |
| 88:0| 3: <1, 0, 102, 97, 99, | @f0 : "fact"; |
| | 116> | |
| 96:4| 0: <65534> | } |
| 100:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0) { |
| | | // BlockID = 12 |
| 108:0| 3: <1, 3> | blocks 3; |
| 110:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 120:0| 3: <1, 0> | i32: |
| 122:4| 3: <4, 2> | %c0 = i32 1; |
| 125:0| 0: <65534> | } |
| | | %b0: |
| 128:0| 3: <28, 2, 1, 32> | %v0 = icmp eq i32 %p0, %c0; |
| 132:6| 3: <11, 1, 2, 1> | br i1 %v0, label %b1, label %b2; |
| | | %b1: |
| 136:6| 3: <10, 2> | ret i32 %c0; |
| | | %b2: |
| 139:2| 3: <2, 3, 2, 1> | %v1 = sub i32 %p0, %c0; |
| 143:2| 3: <34, 0, 5, 1> | %v2 = call i32 @f0(i32 %v1); |
| 148:0| 3: <2, 5, 1, 2> | %v3 = mul i32 %p0, %v2; |
| 152:0| 3: <10, 1> | ret i32 %v3; |
| 154:4| 0: <65534> | } |
| 156:0|0: <65534> |} |
| |
| Note that there are three columns in this output. The first column contains the |
| bit positions of the records within the bitcode file. The second column contains |
| the sequence of records within the bitcode file. The third column contains the |
| corresponding PNaClAsm program. |
| |
| Bit positions are defined by a pair ``B:N``. ``B`` is the number of bytes, while |
| ``N`` is the bit offset within the ``B``-th byte. Hence, the bit position (in |
| bits) is:: |
| |
| B*8 + N |
| |
| Hence, the first record is at bit offset ``0`` (``0*8+0``). The second record is |
| at bit offset ``128`` (``16*8+0``). The third record is at bit offset ``192`` |
| (``24*8+0``). The fourth record is at bit offset ``212`` (``26*8+4``). |
| |
| The :ref:`header record<link_for_header_record_section>` is a sequence of 16 |
| bytes, defining the contents of the first 16 bytes of the bitcode file. These |
| bytes never change, and are expected for all version 2, PNaCl bitcode files. The |
| first four bytes define the magic number of the file, i.e. 'PEXE'. All PEXE |
| bitcode files begin with these four bytes. |
| |
| All but the header record has an abbreviation index associated with it. Since no |
| user-defined abbreviations are provided, all records were converted to |
| bit sequences using default abbreviations. |
| |
| The types block (starting at bit address ``40:0``), defines 4 types: ``i1``, |
| ``i32``, ``void``, and function signature ``i32 (i32)``. |
| |
| Bit address ``64:0`` declares the factorial function address ``@f0``, and its |
| corresponding type signature. Bit address ``88:0`` associates the name ``fact`` |
| with function address ``@f0``. |
| |
| Bit address ``100:0`` defines the function block that implements function |
| ``fact``. The entry point is ``%b0`` (at bit address ``128:0``). It uses the |
| 32-bit integer constant ``1`` (defined at bit addresses ``122:4``). Bit address |
| ``128:0`` defines an equality comparison of the argument ``%p0`` with ``1`` |
| (constant ``%c0``). Bit address ``132:6`` defines a conditional branch. If the |
| result of the previous comparison (``%v0``) is true, the program will branch to |
| block ``%b1``. Otherwise it will branch to block ``%b2``. |
| |
| Bit address ``136:6`` returns constant ``1`` (``%c0``) when the input parameter |
| is 1. Instructions between bit address ``139:2`` and ``154:4`` compute and |
| return ``n * fact(n-1)``. |
| |
| Road Map |
| ======== |
| |
| At this point, this document transitions from basic concepts to the details |
| of how records should be formatted. This section defines the road map to |
| the remaining sections in this document. |
| |
| Many records have implicit information associated with them, and must be |
| maintained across records. :ref:`Global state<link_for_global_state_section>` |
| describes how this implicit information is modeled. In addition, there are |
| various :ref:`support functions<link_for_support_functions_section>` that are |
| used to define the semantics of records, and how they update the global state. |
| |
| There are just a handful of global records (records that either don't appear in |
| any block, or can appear in all blocks). :ref:`Global |
| records<link_for_global_record_codes>` describes these records. This includes |
| the block delimiter records :ref:`enter<link_for_enter_block_record_section>` |
| and :ref:`exit<link_for_exit_block_record_section>` that define block |
| boundaries. |
| |
| PNaClAsm is a strongly typed language, and most block values are typed. |
| :ref:`types<link_for_types_block_section>` describes the set of legal types, and |
| how to define types. |
| |
| Global variables and their initializers are presented in the :ref:`globals |
| block<link_for_globals_block_section>`. :ref:`Function |
| addresses<link_for_function_address_section>` are part of the :ref:`module |
| block<link_for_module_block>`, but must be defined before any global variables. |
| |
| Names to be associated with global variables and function addresses, are defined |
| in the :ref:`valuesymtab block<link_for_valuesymtab_block_section>`, and must |
| appear after the :ref:`globals block<link_for_globals_block_section>`, but |
| before any :ref:`function definition<link_for_function_blocks_section>`. |
| |
| The :ref:`module block<link_for_module_block>` is the top-most block, and all |
| other blocks must appear within the module block. The module block defines the |
| executable in the bitcode file. |
| |
| Constants used within a :ref:`function |
| definition<link_for_function_blocks_section>` must be defined using a |
| :ref:`constants block<link_for_constants_block_section>`. Each function |
| definition is defined by a :ref:`function |
| block<link_for_function_blocks_section>` and constant blocks can only appear |
| within function blocks. Constants defined within a constant block can only be |
| used in the enclosing function block. |
| |
| Function definitions are defined by a sequence of instructions. There are |
| several types of instructions. |
| |
| A :ref:`terminator instruction<link_for_terminator_instruction_section>` is the |
| last instruction in a :ref:`basic block<link_for_function_blocks_section>`, and |
| is a branch, return, or unreachable instruction. |
| |
| There are :ref:`integer<link_for_integer_binary_instructions>` and |
| :ref:`floating point<link_for_floating_point_binary_instructions>` binary |
| operations. Integer binary instructions include both arithmetic and logical |
| operations. Floating point instructions define arithmetic operations. |
| |
| There are also :ref:`memory |
| access<link_for_memory_creation_and_access_instructions>` instructions that |
| allow one to load and store values. That section also includes how to define |
| local variables using the :ref:`alloca |
| instruction<link_for_alloca_instruction>`. |
| |
| One can also convert integer and floating point values using :ref:`conversion |
| instructions<link_for_conversion_instructions>`. |
| |
| :ref:`Comparison instructions<link_for_compare_instructions>` |
| allow you to compare values. |
| |
| :ref:`Vector instructions<link_for_vector_instructions>` allow you to build and |
| update vectors. Corresponding :ref:`intrinsic |
| functions<link_for_intrinsic_functions_section>`, as well as |
| :ref:`integer<link_for_integer_binary_instructions>` and :ref:`floating |
| point<link_for_floating_point_binary_instructions>` binary instructions allow |
| you to apply operations to vectors. |
| |
| In addition, :ref:`other instructions<link_for_other_pnaclasm_instructions>` are |
| available. This includes function and procedure calls. |
| |
| There are also :ref:`memory |
| alignment<link_for_memory_blocks_and_alignment_section>` issues that should be |
| considered for global and local variables, as well as load and store |
| instructions. |
| |
| Finally, how to pack records is described in the |
| :ref:`abbreviations<link_for_abbreviations_section>` section. |
| |
| .. _link_for_global_state_section: |
| |
| Global State |
| ============ |
| |
| This section describes the global state associated with PNaClAsm. It is used to |
| define contextual data that is carried between records. |
| |
| In particular, PNaClAsm is a strongly typed language, and hence, we must track |
| the type associated with values. Subsection :ref:`link_to_typing_functions` |
| describes the functions used to maintain typing information associated with |
| values. |
| |
| Values are implicitly ordered within a block, and the indices associated with |
| the values do not appear in records. Rather, ID counters are used to figure out |
| what corresponding ID name is associated with a value generating record. |
| Subsection :ref:`link_to_ID_Counters` defines counters maintained in the global |
| state. |
| |
| In several blocks, one of the first records in the block defines how many values |
| are defined in in the block. The main purpose of these counts is to communicate |
| to the :ref:`PNaCl translator<link_for_pnacl_translator>` space requirements, or |
| a limit so that it can detect bad references to values. Subsection |
| :ref:`link_for_Size_Variables` defines variables that hold size definitions in |
| the corresponding records. |
| |
| Finally, the function and constants block contain implicit context between |
| records in those blocks. Subsection :ref:`link_to_Other_Variables` defines the |
| variables that contain this implicit context. |
| |
| .. _link_to_typing_functions: |
| |
| Typing Functions |
| ---------------- |
| |
| Associated with most identifiers is a type. This type defines what type the |
| corresponding value has. It is defined by the (initially empty) map:: |
| |
| TypeOf: ID -> Type |
| |
| For each type in the :ref:`types block<link_for_types_block_section>`, a |
| corresponding inverse map:: |
| |
| TypeID: Type -> ID |
| |
| is maintained to convert syntactic types to the corresponding type ID. |
| |
| Note: This document assumes that map ``TypeID`` is automatically maintained |
| during updates to map ``TypeOf`` (when given a type ``ID``). Hence, *Updates* |
| subsections will not contain assignments to this map. |
| |
| Associated with each function identifier is its :ref:`type |
| signature<link_for_function_type>`. This is different than the type of the |
| function identifier, since function identifiers represent the function address |
| which is a pointer (and pointers are always implemented as a 32-bit integer |
| following the ILP32 data model). |
| |
| Function type signatures are maintained using:: |
| |
| TypeOfFcn: ID -> Type |
| |
| In addition, if a function address has an implementing block, there is a |
| corresponding implementation associated with the function address. To indicate |
| which function addresses have implementations, we use the set:: |
| |
| DefiningFcnIDs: set(ID) |
| |
| .. _link_to_ID_Counters: |
| |
| ID Counters |
| ----------- |
| |
| Each block defines one or more kinds of values. Value indices are generated |
| sequentially, starting at zero. To capture this, the following counters are |
| defined: |
| |
| NumTypes |
| The number of types defined so far (in the :ref:`types |
| block<link_for_types_block_section>`). |
| |
| NumFuncAddresses |
| The number of function addresses defined so far (in the :ref:`module |
| block<link_for_module_block>`). |
| |
| NumGlobalAddresses |
| The number of global variable/constant addresses defined so far (in the |
| :ref:`globals block<link_for_globals_block_section>`). |
| |
| NumParams |
| The number of parameters defined for a function. Note: Unlike other counters, |
| this value is set once, at the beginning of the corresponding :ref:`function |
| block<link_for_function_blocks_section>`, based on the type signature |
| associated with the function. |
| |
| NumFcnConsts |
| The number of constants defined in a function so far (in the corresponding |
| nested :ref:`constants block<link_for_constants_block_section>`). |
| |
| NumBasicBlocks |
| The number of basic blocks defined so far (within a :ref:`function |
| block<link_for_function_blocks_section>`). |
| |
| NumValuedInsts |
| The number of instructions, generating values, defined so far (within a |
| :ref:`function block<link_for_function_blocks_section>`). |
| |
| .. _link_for_Size_Variables: |
| |
| Size Variables |
| -------------- |
| |
| A number of blocks define expected sizes of constructs. These sizes are recorded |
| in the following size variables: |
| |
| ExpectedBasicBlocks |
| The expected :ref:`number of basic blocks<link_for_basic_blocks_count>` within |
| a function implementation. |
| |
| ExpectedTypes |
| The expected :ref:`number of types<link_for_types_count_record>` defined in |
| the types block. |
| |
| ExpectedGlobals |
| The expected :ref:`number of global variable/constant |
| addresses<link_for_globals_count_record>` in the globals block. |
| |
| ExpectedInitializers |
| The expected :ref:`number of initializers<link_for_compound_initializer>` for |
| a global variable/constant address in the globals block. |
| |
| It is assumed that the corresponding :ref:`ID counters<link_to_ID_counters>` are |
| always smaller than the corresponding size variables (except |
| ExpectedInitializers). That is:: |
| |
| NumBasicBlocks < ExpectedBasicBlocks |
| NumTypes < ExpectedTypes |
| NumGlobalAddresses < ExpectedGlobals |
| |
| .. _link_to_Other_Variables: |
| |
| Other Variables |
| --------------- |
| |
| EnclosingFcnID |
| The function ID of the function block being processed. |
| |
| ConstantsSetType |
| Holds the type associated with the last :ref:`set type |
| record<link_for_constants_set_type_record>` in the constants block. Note: at |
| the beginning of each constants block, this variable is set to type void. |
| |
| .. _link_for_global_record_codes: |
| |
| Global Records |
| ============== |
| |
| Global records are records that can appear in any block. These records have |
| the same meaning in multiple kinds of blocks. |
| |
| There are four global PNaCl records, each having its own record code. These |
| global records are: |
| |
| Header |
| The :ref:`header record<link_for_header_record_section>` is the first record |
| of a PNaCl bitcode file, and identifies the file's magic number, as well as |
| the bitcode version it uses. The record defines the sequence of bytes that |
| make up the header and uniquely identifies the file as a PNaCl bitcode file. |
| |
| Enter |
| An :ref:`enter record<link_for_enter_block_record_section>` defines the |
| beginning of a block. Since blocks can be nested, one can appear inside other |
| blocks, as well as at the top level. |
| |
| Exit |
| An :ref:`exit record<link_for_exit_block_record_section>` defines the end of a |
| block. Hence, it must appear in every block, to end the block. |
| |
| Abbreviation |
| An :ref:`abbreviation record<link_for_abbreviation_record>` defines a |
| user-defined abbreviation to be applied to records within blocks. |
| Abbreviation records appearing in the abbreviations block define global |
| abbreviations. All other abbreviations are local to the block they appear in, |
| and can only be used in that block. |
| |
| All global records can't have user-defined abbreviations associated with |
| them. The :ref:`default abbreviation<link_for_default_abbreviations>` is always |
| used. |
| |
| .. _link_for_header_record_section: |
| |
| Header Record |
| ------------- |
| |
| The header record must be the first record in the file. It is the only record in |
| the bitcode file that doesn't have a corresponding construct in PNaClAsm. In |
| addition, no abbreviation index is associated with it. |
| |
| **Syntax**: |
| |
| There is no syntax for header records in PNaClAsm. |
| |
| **Record**:: |
| |
| <65532, 80, 69, 88, 69, 1, 0, 8, 0, 17, 0, 4, 0, 2, 0, 0, 0> |
| |
| **Semantics**: |
| |
| The header record defines the initial sequence of bytes that must appear at the |
| beginning of all (PNaCl bitcode version 2) files. That sequence is the list of |
| bytes inside the record (excluding the record code). As such, it uniquely |
| identifies all PNaCl bitcode files. |
| |
| **Examples**:: |
| |
| 0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69) |
| | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2 |
| | 0> | |
| |
| .. _link_for_enter_block_record_section: |
| |
| Enter Block Record |
| ------------------ |
| |
| Block records can be top-level, as well as nested in other blocks. Blocks must |
| begin with an *enter* record, and end with an |
| :ref:`exit<link_for_exit_block_record_section>` record. |
| |
| **Syntax**:: |
| |
| N { <B> |
| |
| **Record**:: |
| |
| 1: <65535, ID, B> |
| |
| **Semantics**: |
| |
| Enter block records define the beginning of a block. ``B``, if present, is the |
| number of bits needed to represent all possible abbreviation indices used within |
| the block. If omitted, ``B=2`` is assumed. |
| |
| The block ``ID`` value is dependent on the name ``N``. Valid names and |
| corresponding ``BlockID`` values are defined as follows: |
| |
| ============= ======== |
| N Block ID |
| ============= ======== |
| abbreviations 0 |
| constants 11 |
| function 12 |
| globals 19 |
| module 8 |
| types 17 |
| valuesymtab 14 |
| ============= ======== |
| |
| Note: For readability, PNaClAsm defines a more readable form of a function block |
| enter record. See :ref:`function blocks<link_for_function_blocks_section>` for |
| more details. |
| |
| **Examples**:: |
| |
| 16:0|1: <65535, 8, 2> |module { // BlockID = 8 |
| 24:0| 3: <1, 1> | version 1; |
| 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 |
| 36:0| 0: <65534> | } |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 2> | count 2; |
| 50:4| 3: <2> | @t0 = void; |
| 52:2| 3: <21, 0, 0> | @t1 = void (); |
| 55:4| 0: <65534> | } |
| 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); |
| 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 68:0| 3: <5, 0> | count 0; |
| 70:4| 0: <65534> | } |
| 72:0|0: <65534> |} |
| |
| .. _link_for_exit_block_record_section: |
| |
| Exit Block Record |
| ----------------- |
| |
| Block records can be top-level, as well as nested, records. Blocks must begin |
| with an :ref:`enter<link_for_enter_block_record_section>` record, and end with |
| an *exit* record. |
| |
| **Syntax**:: |
| |
| } |
| |
| **Record**:: |
| |
| 0: <65534> |
| |
| **Semantics**: |
| |
| All exit records are identical, no matter what block they are ending. An exit |
| record defines the end of the block. |
| |
| **Examples**:: |
| |
| 16:0|1: <65535, 8, 2> |module { // BlockID = 8 |
| 24:0| 3: <1, 1> | version 1; |
| 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 |
| 36:0| 0: <65534> | } |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 2> | count 2; |
| 50:4| 3: <2> | @t0 = void; |
| 52:2| 3: <21, 0, 0> | @t1 = void (); |
| 55:4| 0: <65534> | } |
| 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); |
| 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 68:0| 3: <5, 0> | count 0; |
| 70:4| 0: <65534> | } |
| 72:0|0: <65534> |} |
| |
| .. _link_for_abbreviation_record: |
| |
| Abbreviation Record |
| ------------------- |
| |
| Abbreviation records define abbreviations. See |
| :ref:`abbreviations<link_for_abbreviations_section>` for details on how |
| abbreviations should be written. This section only presents the mechanical |
| details for converting an abbreviation into a PNaCl record. |
| |
| **Syntax**:: |
| |
| A = abbrev <E1, ... , EM>; |
| |
| **Record**:: |
| |
| 2: <65533, M, EE1, ... , EEM> |
| |
| **Semantics**: |
| |
| Defines an abbreviation ``A`` as the sequence of encodings ``E1`` through |
| ``EM``. If the abbreviation appears within the :ref:`abbreviations |
| block<link_for_abbreviations_block_section>`, ``A`` must be a global |
| abbreviation. Otherwise, ``A`` must be a local abbreviation. |
| |
| Abbreviations within a block (or a section within the abbreviations block), must |
| be enumerated in order, starting at index ``0``. |
| |
| Valid encodings ``Ei``, and the corresponding sequence of (unsigned) integers |
| ``EEi``, ( for ``1 <= i <= M``) are defined by the following table: |
| |
| ========= ======= ================================================== |
| Ei EEi Form |
| ========= ======= ================================================== |
| C 1, C Literal C in corresponding position in record. |
| fixed(N) 0, 1, N Encode value as a fixed sequence of N bits. |
| vbr(N) 0, 2, N Encode value using a variable bit rate of N. |
| char6 0, 4 Encode value as 6-bit char containing |
| characters [a-zA-Z0-9._]. |
| array 0, 3 Allow zero or more of the succeeding abbreviation. |
| ========= ======= ================================================== |
| |
| Note that 'array' can only appear as the second to last element in the |
| abbreviation. Notationally, ``array(EM)`` is used in place of ``array`` and |
| ``EM``, the last two entries in an abbreviation. |
| |
| **Examples**:: |
| |
| 0:0|<65532, 80, 69, 88, 69, 1, 0,|Magic Number: 'PEXE' (80, 69, 88, 69) |
| | 8, 0, 17, 0, 4, 0, 2, 0, 0, |PNaCl Version: 2 |
| | 0> | |
| 16:0|1: <65535, 8, 2> |module { // BlockID = 8 |
| 24:0| 3: <1, 1> | version 1; |
| 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 |
| 36:0| 1: <1, 14> | valuesymtab: |
| 38:4| 2: <65533, 4, 0, 1, 3, 0,| @a0 = abbrev <fixed(3), vbr(8), |
| | 2, 8, 0, 3, 0, 1, 8> | array(fixed(8))>; |
| 43:2| 2: <65533, 4, 1, 1, 0, 2,| @a1 = abbrev <1, vbr(8), |
| | 8, 0, 3, 0, 1, 7> | array(fixed(7))>; |
| 48:0| 2: <65533, 4, 1, 1, 0, 2,| @a2 = abbrev <1, vbr(8), |
| | 8, 0, 3, 0, 4> | array(char6)>; |
| 52:1| 2: <65533, 4, 1, 2, 0, 2,| @a3 = abbrev <2, vbr(8), |
| | 8, 0, 3, 0, 4> | array(char6)>; |
| 56:2| 1: <1, 11> | constants: |
| 58:6| 2: <65533, 2, 1, 1, 0, 1,| @a0 = abbrev <1, fixed(2)>; |
| | 2> | |
| 61:7| 2: <65533, 2, 1, 4, 0, 2,| @a1 = abbrev <4, vbr(8)>; |
| | 8> | |
| 65:0| 2: <65533, 2, 1, 4, 1, 0>| @a2 = abbrev <4, 0>; |
| 68:1| 2: <65533, 2, 1, 6, 0, 2,| @a3 = abbrev <6, vbr(8)>; |
| | 8> | |
| 71:2| 1: <1, 12> | function: |
| 73:6| 2: <65533, 4, 1, 20, 0, | @a0 = abbrev <20, vbr(6), vbr(4), |
| | 2, 6, 0, 2, 4, 0, 2, | vbr(4)>; |
| | 4> | |
| 79:1| 2: <65533, 4, 1, 2, 0, 2,| @a1 = abbrev <2, vbr(6), vbr(6), |
| | 6, 0, 2, 6, 0, 1, 4> | fixed(4)>; |
| 84:4| 2: <65533, 4, 1, 3, 0, 2,| @a2 = abbrev <3, vbr(6), |
| | 6, 0, 1, 2, 0, 1, 4> | fixed(2), fixed(4)>; |
| 89:7| 2: <65533, 1, 1, 10> | @a3 = abbrev <10>; |
| 91:7| 2: <65533, 2, 1, 10, 0, | @a4 = abbrev <10, vbr(6)>; |
| | 2, 6> | |
| 95:0| 2: <65533, 1, 1, 15> | @a5 = abbrev <15>; |
| 97:0| 2: <65533, 3, 1, 43, 0, | @a6 = abbrev <43, vbr(6), |
| | 2, 6, 0, 1, 2> | fixed(2)>; |
| 101:2| 2: <65533, 4, 1, 24, 0, | @a7 = abbrev <24, vbr(6), vbr(6), |
| | 2, 6, 0, 2, 6, 0, 2, | vbr(4)>; |
| | 4> | |
| 106:5| 1: <1, 19> | globals: |
| 109:1| 2: <65533, 3, 1, 0, 0, 2,| @a0 = abbrev <0, vbr(6), |
| | 6, 0, 1, 1> | fixed(1)>; |
| 113:3| 2: <65533, 2, 1, 1, 0, 2,| @a1 = abbrev <1, vbr(8)>; |
| | 8> | |
| 116:4| 2: <65533, 2, 1, 2, 0, 2,| @a2 = abbrev <2, vbr(8)>; |
| | 8> | |
| 119:5| 2: <65533, 3, 1, 3, 0, 3,| @a3 = abbrev <3, array(fixed(8))> |
| | 0, 1, 8> | ; |
| 123:2| 2: <65533, 2, 1, 4, 0, 2,| @a4 = abbrev <4, vbr(6)>; |
| | 6> | |
| 126:3| 2: <65533, 3, 1, 4, 0, 2,| @a5 = abbrev <4, vbr(6), vbr(6)>; |
| | 6, 0, 2, 6> | |
| 130:5| 0: <65534> | } |
| 132:0| 1: <65535, 17, 3> | types { // BlockID = 17 |
| 140:0| 2: <65533, 4, 1, 21, 0, | %a0 = abbrev <21, fixed(1), |
| | 1, 1, 0, 3, 0, 1, 2> | array(fixed(2))>; |
| 144:7| 3: <1, 3> | count 3; |
| 147:4| 3: <7, 32> | @t0 = i32; |
| 150:7| 4: <21, 0, 0, 0, 0> | @t1 = i32 (i32, i32); <%a0> |
| 152:7| 3: <2> | @t2 = void; |
| 154:6| 0: <65534> | } |
| 156:0| 3: <8, 1, 0, 0, 0> | define external i32 @f0(i32, i32); |
| 160:6| 1: <65535, 19, 4> | globals { // BlockID = 19 |
| 168:0| 3: <5, 0> | count 0; |
| 170:6| 0: <65534> | } |
| 172:0| 1: <65535, 14, 3> | valuesymtab { // BlockID = 14 |
| 180:0| 6: <1, 0, 102> | @f0 : "f"; <@a2> |
| 182:7| 0: <65534> | } |
| 184:0| 1: <65535, 12, 4> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 192:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 194:6| 5: <2, 2, 1, 0> | %v0 = add i32 %p0, %p1; <@a1> |
| 197:2| 5: <2, 3, 1, 0> | %v1 = add i32 %p0, %v0; <@a1> |
| 199:6| 8: <10, 1> | ret i32 %v1; <@a4> |
| 201:0| 0: <65534> | } |
| 204:0|0: <65534> |} |
| |
| Note that the example above shows the standard abbreviations used by |
| *pnacl-finalize*. |
| |
| .. _link_for_types_block_section: |
| |
| Types Block |
| =========== |
| |
| The types block defines all types used in a program. It must appear in the |
| :ref:`module block<link_for_module_block>`, before any :ref:`function |
| address<link_for_function_address_section>` records, the :ref:`globals |
| block<link_for_globals_block_section>`, the :ref:`valuesymtab |
| block<link_for_valuesymtab_block_section>`, and any :ref:`function |
| blocks<link_for_function_blocks_section>`. |
| |
| All types used in a program must be defined in the types block. Many PNaClAsm |
| constructs allow one to use explicit type names, rather than the type |
| identifiers defined by this block. However, they are internally converted to the |
| corresponding type identifier in the types block. Hence, the requirement that |
| the types block must appear early in the module block. |
| |
| Each record in the types block defines a type used by the program. Types can be |
| broken into the following groups: |
| |
| Primitive value types |
| Defines the set of base types for values. This includes various sizes of |
| integer and floating point types. |
| |
| Void type |
| A primitive type that doesn't represent any value and has no size. |
| |
| Function types |
| The type signatures of functions. |
| |
| Vector type |
| Defines vectors of primitive types. |
| |
| In addition, any type that is not defined using another type is a primitive |
| type. All other types (i.e. function and vector) are composite types. |
| |
| Types must be defined in a topological order, causing primitive types to appear |
| before the composite types that use them. Each type must be unique. There are no |
| additional restrictions on the order that types can be defined in a types block. |
| |
| The following subsections introduce each valid PNaClAsm type, and the |
| corresponding PNaClAsm construct that defines the type. Types not defined in the |
| types block, can't be used in a PNaCl program. |
| |
| The first record of a types block must be a :ref:`count |
| record<link_for_types_count_record>`, defining how many types are defined by the |
| types block. All remaining records defines a type. The following subsections |
| defines valid records within a types block. The order of type records is |
| important. The position of each defining record implicitly defines the type ID |
| that will be used to denote that type, within other PNaCl records of the bitcode |
| file. |
| |
| To make this more concrete, consider the following example types block:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <3> | @t1 = float; |
| 55:4| 3: <2> | @t2 = void; |
| 57:2| 3: <21, 0, 2, 0, 1> | @t3 = void (i32, float); |
| 62:0| 0: <65534> | } |
| |
| This example defines a types block that defines four type IDs: |
| |
| @t0 |
| A 32-bit integer type. |
| @t1 |
| A 32-bit floating point type. |
| @t2 |
| The void type. |
| @t3 |
| A function, taking 32-bit integer and float point arguments that returns |
| void. |
| |
| .. _link_for_types_count_record: |
| |
| Count Record |
| ------------ |
| |
| The *count record* defines how many types are defined in the types |
| block. Following the types count record are records that define types used by |
| the PNaCl program. |
| |
| **Syntax**:: |
| |
| count N; <A> |
| |
| **Record**:: |
| |
| AA: <1, N> |
| |
| **Semantics**: |
| |
| This construct defines the number of types used by the PNaCl program. ``N`` is |
| the number of types defined in the types block. It is an error to define more |
| (or fewer) types than value ``N``, within the enclosing types block. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| 0 == NumTypes |
| |
| **Updates**:: |
| |
| ExpectedTypes = N; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <3> | @t1 = float; |
| 55:4| 3: <2> | @t2 = void; |
| 57:2| 3: <21, 0, 2, 0, 1> | @t3 = void (i32, float); |
| 62:0| 0: <65534> | } |
| |
| Void Type |
| --------- |
| |
| The *void* type record defines the void type, which corresponds to the type that |
| doesn't define any value, and has no size. |
| |
| **Syntax**:: |
| |
| @tN = void; <A> |
| |
| **Record**:: |
| |
| AA: <2> |
| |
| **Semantics**: |
| |
| The void type record defines the type that has no values and has no size. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N == NumTypes |
| |
| **Updates**:: |
| |
| ++NumTypes; |
| TypeOf(@tN) = void; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <3> | @t1 = float; |
| 55:4| 3: <2> | @t2 = void; |
| 62:0| 0: <65534> | } |
| |
| Integer Types |
| ------------- |
| |
| PNaClAsm allows integer types for various bit sizes. Valid bit sizes are 1, 8, |
| 16, 32, and 64. Integers can be signed or unsigned, but the signed component of |
| an integer is not specified by the type. Rather, individual instructions |
| determine whether the value is assumed to be signed or unsigned. |
| |
| It should be noted that in PNaClAsm, all pointers are implemented as 32-bit |
| (unsigned) integers. There isn't a separate type for pointers. The only way to |
| tell that a 32-bit integer is a pointer, is when it is used in an instruction |
| that requires a pointer (such as load and store instructions). |
| |
| **Syntax**:: |
| |
| @tN = iB; <A> |
| |
| **Record**:: |
| |
| AA: <7, B> |
| |
| **Semantics**: |
| |
| An integer type record defines an integer type. ``B`` defines the number of bits |
| of the integer type. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N == NumTypes & |
| B in {1, 8, 16, 32, 64} |
| |
| **Updates**:: |
| |
| ++NumTypes; |
| TypeOf(@tN) = iB; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 7> | count 7; |
| 50:4| 3: <7, 64> | @t0 = i64; |
| 53:6| 3: <7, 1> | @t1 = i1; |
| 56:2| 3: <7, 8> | @t2 = i8; |
| 58:6| 3: <7, 16> | @t3 = i16; |
| 61:2| 3: <7, 32> | @t4 = i32; |
| 64:4| 3: <21, 0, 0, 1> | @t5 = i64 (i1); |
| 68:4| 3: <2> | @t6 = void; |
| 70:2| 0: <65534> | } |
| |
| 32-Bit Floating Point Type |
| -------------------------- |
| |
| PNaClAsm allows computation on 32-bit floating point values. A floating point |
| type record defines the 32-bit floating point type. |
| |
| **Syntax**:: |
| |
| @tN = float; <A> |
| |
| **Record**:: |
| |
| AA: <3> |
| |
| **Semantics**: |
| |
| A floating point type record defines the 32-bit floating point type. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N == NumTypes |
| |
| **Updates**:: |
| |
| ++NumTypes; |
| TypeOf(@tN) = float; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <4> | @t0 = double; |
| 52:2| 3: <3> | @t1 = float; |
| 54:0| 3: <21, 0, 0, 1> | @t2 = double (float); |
| 58:0| 3: <2> | @t3 = void; |
| 59:6| 0: <65534> | } |
| |
| 64-bit Floating Point Type |
| -------------------------- |
| |
| PNaClAsm allows computation on 64-bit floating point values. A 64-bit floating |
| type record defines the 64-bit floating point type. |
| |
| **Syntax**:: |
| |
| @tN = double; <A> |
| |
| **Record**:: |
| |
| AA: <4> |
| |
| **Semantics**: |
| |
| A double type record defines the 64-bit floating point type. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N == NumTypes |
| |
| **Updates**:: |
| |
| ++NumTypes; |
| TypeOf(@tN) = double; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <4> | @t0 = double; |
| 52:2| 3: <3> | @t1 = float; |
| 54:0| 3: <21, 0, 0, 1> | @t2 = double (float); |
| 58:0| 3: <2> | @t3 = void; |
| 59:6| 0: <65534> | } |
| |
| Vector Types |
| ------------ |
| |
| A vector type is a derived type that represents a vector of elements. Vector |
| types are used when multiple primitive data values are operated in parallel |
| using a single (SIMD) :ref:`vector instruction<link_for_vector_instructions>`. A |
| vector type requires a size (number of elements) and an underlying primitive |
| data type. |
| |
| **Syntax**:: |
| |
| @tN = < E x T > <A> |
| |
| **Record**:: |
| |
| AA: <12, E, TT> |
| |
| **Semantics**: |
| |
| The vector type defines a vector of elements. ``T`` is the type of each |
| element. ``E`` is the number of elements in the vector. |
| |
| Vector types can only be defined on ``i1``, ``i8``, ``i16``, ``i32``, and |
| ``float``. All vector types, except those on ``i1``, must contain exactly 128 |
| bits. The valid element sizes are restricted as follows: |
| |
| ====== =================== |
| Type Valid element sizes |
| ====== =================== |
| i1 4, 8, 16 |
| i8 16 |
| i16 8 |
| i32 4 |
| float 4 |
| ====== =================== |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TT == AbsoluteIndex(TypeID(T)) & |
| N == NumTypes |
| |
| **Updates**:: |
| |
| ++NumTypes |
| TypeOf(@tN) = <E x T> |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 14> | count 14; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <7, 1> | @t1 = i1; |
| 56:2| 3: <2> | @t2 = void; |
| 58:0| 3: <12, 4, 1> | @t3 = <4 x i1>; |
| 61:2| 3: <12, 8, 1> | @t4 = <8 x i1>; |
| 64:4| 3: <12, 16, 1> | @t5 = <16 x i1>; |
| 67:6| 3: <7, 8> | @t6 = i8; |
| 70:2| 3: <12, 16, 6> | @t7 = <16 x i8>; |
| 73:4| 3: <7, 16> | @t8 = i16; |
| 76:0| 3: <12, 8, 8> | @t9 = <8 x i16>; |
| 79:2| 3: <12, 4, 0> | @t10 = <4 x i32>; |
| 82:4| 3: <3> | @t11 = float; |
| 84:2| 3: <12, 4, 11> | @t12 = <4 x float>; |
| 87:4| 3: <21, 0, 2> | @t13 = void (); |
| 90:6| 0: <65534> | } |
| |
| .. _link_for_function_type: |
| |
| Function Type |
| ------------- |
| |
| The *function* type can be thought of as a function signature. It consists of a |
| return type, and a (possibly empty) list of formal parameter types. |
| |
| **Syntax**:: |
| |
| %tN = RT (T1, ... , TM) <A> |
| |
| **Record**:: |
| |
| AA: <21, 0, IRT, IT1, ... , ITM> |
| |
| **Semantics**: |
| |
| The function type defines the signature of a function. ``RT`` is the return type |
| of the function, while types ``T1`` through ``TM`` are the types of the |
| arguments. Indices to the corresponding type identifiers are stored in the |
| corresponding record. |
| |
| The return value must either be a primitive type, type ``void``, or a vector |
| type. Parameter types can be a primitive or vector type. |
| |
| For ordinary functions, the only valid integer types that can be used for a |
| return or parameter type are ``i32`` and ``i64``. All other integer types are |
| not allowed. |
| |
| For :ref:`intrinsic functions<link_for_intrinsic_functions_section>`, all |
| integer types are allowed for both return and parameter types. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| M >= 0 & |
| IRT == AbsoluteIndex(TypeID(RT)) & |
| IT1 == AbsoluteIndex(TypeID(T1)) & |
| ... |
| ITM == AbsoluteIndex(TypeID(TM)) & |
| N == NumTypes |
| |
| **Updates**:: |
| |
| ++NumTypes |
| TypeOf(@tN) = RT (T1, ... , TM) |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 7> | count 7; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <3> | @t1 = float; |
| 55:4| 3: <4> | @t2 = double; |
| 57:2| 3: <21, 0, 2, 1> | @t3 = double (float); |
| 61:2| 3: <2> | @t4 = void; |
| 63:0| 3: <21, 0, 4> | @t5 = void (); |
| 66:2| 3: <21, 0, 0, 0, 1, 0, 2>| @t6 = |
| | | i32 (i32, float, i32, double); |
| 72:4| 0: <65534> | } |
| |
| .. _link_for_globals_block_section: |
| |
| Globals Block |
| ============= |
| |
| The globals block defines global addresses of variables and constants, used by |
| the PNaCl program. It also defines the memory associated with the global |
| addresses, and how to initialize each global variable/constant. It must appear |
| in the :ref:`module block<link_for_module_block>`. It must appear after the |
| :ref:`types block<link_for_types_block_section>`, as well as after all |
| :ref:`function address<link_for_function_address_section>` records. But, it must |
| also appear before the :ref:`valuesymtab |
| block<link_for_valuesymtab_block_section>`, and any |
| :ref:`function blocks<link_for_function_blocks_section>`. |
| |
| The globals block begins with a :ref:`count |
| record<link_for_globals_count_record>`, defining how many global addresses are |
| defined by the PNaCl program. It is then followed by a sequence of records that |
| defines each global address, and how each global address is initialized. |
| |
| The standard sequence, for defining global addresses, begins with a global |
| address record. It is then followed by a sequence of records defining how the |
| global address is initialized. If the initializer is simple, a single record is |
| used. Otherwise, the initializer is preceded with a :ref:`compound |
| record<link_for_compound_initializer>`, specifying a number *N*, followed by |
| sequence of *N* simple initializer records. |
| |
| The size of the memory referenced by each global address is defined by its |
| initializer records. All simple initializer records define a sequence of |
| bytes. A compound initializer defines the sequence of bytes by concatenating the |
| corresponding sequence of bytes for each of its simple initializer records. |
| |
| For notational convenience, PNaClAsm begins a compound record with a "{", and |
| inserts a "}" after the last initializer record associated with the compound |
| record. This latter "}" does not correspond to any record. It is implicitly |
| assumed by the size specified in the compound record, and is added only to |
| improve readability. |
| |
| Explicit alignment is specified for global addresses, and must be a power of |
| 2. See :ref:`memory blocks and |
| alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed |
| discussion on how to define alignment. |
| |
| For example, consider the following pnacl-bcdis output snippet:: |
| |
| 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 60:0| 3: <5, 2> | count 2; |
| 62:4| 3: <0, 1, 1> | const @g0, align 1, |
| 65:6| 3: <2, 8> | zerofill 8; |
| 68:2| 3: <0, 1, 0> | var @g1, align 1, |
| 71:4| 3: <1, 2> | initializers 2 { |
| 74:0| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} |
| 78:6| 3: <2, 2> | zerofill 2; |
| | | } |
| 81:2| 0: <65534> | } |
| |
| This snippet defines the global constant ``@g0``, and the global variable |
| ``@g1``. ``@g0`` is 8 bytes long, and initialized to zero. ``@g1`` is |
| initialized with 6 bytes: ``1 2 3 4 0 0``. |
| |
| .. _link_for_globals_count_record: |
| |
| Count Record |
| ------------ |
| |
| The count record defines the number of global addresses used by the PNaCl |
| program. |
| |
| **Syntax**:: |
| |
| count N; <A> |
| |
| **Record**:: |
| |
| AA: <5, N> |
| |
| **Semantics**: |
| |
| This record must appear first in the globals block. The count record defines |
| the number of global addresses used by the program. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) |
| |
| **Updates**:: |
| |
| ExpectedGlobals = N; |
| ExpectedInitializers = 0; |
| |
| **Examples**:: |
| |
| 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 60:0| 3: <5, 2> | count 2; |
| 62:4| 3: <0, 1, 1> | const @g0, align 1, |
| 65:6| 3: <2, 8> | zerofill 8; |
| 68:2| 3: <0, 1, 0> | var @g1, align 1, |
| 71:4| 3: <1, 2> | initializers 2 { |
| 74:0| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} |
| 78:6| 3: <2, 2> | zerofill 2; |
| | | } |
| 81:2| 0: <65534> | } |
| |
| .. _link_for_global_variable_address: |
| |
| Global Variable Addresses |
| ------------------------- |
| |
| A global variable address record defines a global address to global data. The |
| global variable address record must be immediately followed by initializer |
| record(s) that define how the corresponding global variable is initialized. |
| |
| **Syntax**:: |
| |
| var @gN, align V, <A> |
| |
| **Record**:: |
| |
| AA: <0, VV, 0> |
| |
| **Semantics**: |
| |
| A global variable address record defines a global address for a global variable. |
| ``V`` is the :ref:`memory |
| alignment<link_for_memory_blocks_and_alignment_section>` for the global variable |
| address, and is a power of 2. |
| |
| It is assumed that the memory, referenced by the global variable address, can be |
| both read and written to. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N == NumGlobalAddresses & |
| ExpectedInitializers == 0 & |
| VV == Log2(V+1) |
| |
| **Updates**:: |
| |
| ++NumGlobalAddresses; |
| ExpectedInitializers = 1; |
| TypeOf(@gN) = i32; |
| |
| **Examples**:: |
| |
| 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 60:0| 3: <5, 2> | count 2; |
| 62:4| 3: <0, 3, 0> | var @g0, align 4, |
| 65:6| 3: <2, 8> | zerofill 8; |
| 68:2| 3: <0, 1, 0> | var @g1, align 1, |
| 71:4| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} |
| 76:2| 0: <65534> | } |
| 80:0|0: <65534> |} |
| |
| .. _link_for_global_constant_address: |
| |
| Global Constant Addresses |
| ------------------------- |
| |
| A global constant address record defines an address corresponding to a global |
| constant that can't be modified by the program. The global constant address |
| record must be immediately followed by initializer record(s) that define how |
| the corresponding global constant is initialized. |
| |
| **Syntax**:: |
| |
| const @gN, align V, <A> |
| |
| **Record**:: |
| |
| AA: <0, VV, 1> |
| |
| **Semantics**: |
| |
| A global constant address record defines a global address for a global constant. |
| ``V`` is the :ref:`memory |
| alignment<link_for_memory_blocks_and_alignment_section>` for the global constant |
| address, and is a power of 2. |
| |
| It is assumed that the memory, referenced by the global constant address, is |
| only read, and can't be written to. |
| |
| Note that the only difference between a global variable address and a global |
| constant address record is the third element of the record. If the value is |
| zero, it defines a global variable address. If the value is one, it defines a |
| global constant address. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N == NumGlobalAddresses & |
| ExpectedInitializers == 0 & |
| VV == Log2(V+1) |
| |
| **Updates**:: |
| |
| ++NumGlobalAddresses; |
| ExpectedInitializers = 1; |
| TypeOf(@gN) = i32; |
| |
| **Examples**:: |
| |
| 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 60:0| 3: <5, 2> | count 2; |
| 62:4| 3: <0, 3, 1> | const @g0, align 4, |
| 65:6| 3: <2, 8> | zerofill 8; |
| 68:2| 3: <0, 1, 1> | const @g1, align 1, |
| 71:4| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} |
| 76:2| 0: <65534> | } |
| |
| Zerofill Initializer |
| -------------------- |
| |
| The zerofill initializer record initializes a sequence of bytes, associated with |
| a global address, with zeros. |
| |
| **Syntax**:: |
| |
| zerofill N; <A> |
| |
| **Record**:: |
| |
| AA: <2, N> |
| |
| **Semantics**: |
| |
| A zerofill initializer record initializes a sequence of bytes, associated with a |
| global address, with zeros. The number of bytes initialized to zero is ``N``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| ExpectedInitializers > 0 |
| |
| **Updates**:: |
| |
| --ExpectedInitializers; |
| |
| **Examples**:: |
| |
| 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 60:0| 3: <5, 2> | count 2; |
| 62:4| 3: <0, 3, 1> | const @g0, align 4, |
| 65:6| 3: <2, 8> | zerofill 8; |
| 68:2| 3: <0, 1, 0> | var @g1, align 1, |
| 71:4| 3: <2, 4> | zerofill 4; |
| 74:0| 0: <65534> | } |
| |
| Data Initializer |
| ---------------- |
| |
| Data records define a sequence of bytes. These bytes define the initial value of |
| the contents of the corresponding memory. |
| |
| **Syntax**:: |
| |
| { B1 , .... , BN } <A> |
| |
| **Record**:: |
| |
| AA: <3, B1, ..., BN> |
| |
| **Semantics**: |
| |
| A data record defines a sequence of (unsigned) bytes ``B1`` through ``BN``, that |
| initialize ``N`` bytes of memory. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| ExpectedInitializers > 0 |
| |
| **Updates**:: |
| |
| --ExpectedInitializers; |
| |
| **Examples**:: |
| |
| 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); |
| 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 68:0| 3: <5, 2> | count 2; |
| 70:4| 3: <0, 1, 1> | const @g0, align 1, |
| 73:6| 3: <3, 1, 2, 97, 36, 44, | { 1, 2, 97, 36, 44, 88, |
| | 88, 44, 50> | 44, 50} |
| 86:0| 3: <0, 1, 1> | const @g1, align 1, |
| 89:2| 3: <1, 3> | initializers 3 { |
| 91:6| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} |
| 96:4| 3: <4, 0> | reloc @f0; |
| 99:0| 3: <3, 99, 66, 22, 12> | { 99, 66, 22, 12} |
| | | } |
| 105:2| 0: <65534> | } |
| |
| Relocation Initializer |
| ---------------------- |
| |
| A relocation initializer record allows one to define the initial value of a |
| global address with the value of another global address (i.e. either |
| :ref:`function<link_for_function_address_section>`, |
| :ref:`variable<link_for_global_variable_address>`, or |
| :ref:`constant<link_for_global_constant_address>`). Since addresses are |
| pointers, a relocation initializer record defines 4 bytes of memory. |
| |
| **Syntax**:: |
| |
| reloc V; <A> |
| |
| **Record**:: |
| |
| AA: <4, VV> |
| |
| **Semantics**: |
| |
| A relocation initializer record defines a 4-byte value containing the specified |
| global address ``V``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV == AbsoluteIndex(V) & |
| VV >= NumFuncAddresses & |
| VV < NumFuncAddresses + ExpectedGlobals & |
| ExpectedInitializers > 0 |
| |
| **Updates**:: |
| |
| --ExpectedInitializers; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 2> | count 2; |
| 50:4| 3: <2> | @t0 = void; |
| 52:2| 3: <21, 0, 0> | @t1 = void (); |
| 55:4| 0: <65534> | } |
| 56:0| 3: <8, 1, 0, 1, 0> | declare external void @f0(); |
| 60:6| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 68:0| 3: <5, 2> | count 2; |
| 70:4| 3: <0, 1, 0> | var @g0, align 1, |
| 73:6| 3: <1, 3> | initializers 3 { |
| 76:2| 3: <4, 0> | reloc @f0; |
| 78:6| 3: <4, 1> | reloc @g0; |
| 81:2| 3: <4, 2> | reloc @g1; |
| | | } |
| 83:6| 3: <0, 3, 0> | var @g1, align 4, |
| 87:0| 3: <2, 4> | zerofill 4; |
| 89:4| 0: <65534> | } |
| |
| This example defines global address ``@g0`` and ``@g1``. ``@g0`` defines 12 |
| bytes of memory, and is initialized with three addresses ``@f1``, ``@g0``, and |
| ``@g1``. Note that all global addresses can be used in a relocation |
| initialization record, even if it isn't defined yet. |
| |
| Subfield Relocation Initializer |
| ------------------------------- |
| |
| A subfield relocation initializer record allows one to define the initial value |
| of a global address with the value of another (non-function) global address |
| (i.e. either :ref:`variable<link_for_global_variable_address>` or |
| :ref:`constant<link_for_global_constant_address>` address), plus a |
| constant. Since addresses are pointers, a relocation initializer record defines |
| 4 bytes of memory. |
| |
| **Syntax**:: |
| |
| reloc V + X; <A> |
| reloc V - X; <A> |
| |
| **Record**:: |
| |
| AA: <4, VV, XXX> |
| |
| **Semantics**: |
| |
| A subfield relocation initializer record defines a 4-byte value containing the |
| specified global (non-function) address ``V``, modified by the unsigned offset |
| ``X``. ``XX`` is the corresponding signed offset. In the first form, ``XX == |
| X``. In the second form, ``XX == -X``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) |
| VV == AbsoluteIndex(V) |
| VV >= NumFuncAddresses |
| VV < NumFuncAddresses + ExpectedGlobals |
| ExpectedInitializers > 0 |
| XXX == SignRotate(XX) |
| |
| **Updates**:: |
| |
| --ExpectedInitializers; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 0> | count 0; |
| 50:4| 0: <65534> | } |
| 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 60:0| 3: <5, 3> | count 3; |
| 62:4| 3: <0, 1, 0> | var @g0, align 1, |
| 65:6| 3: <1, 3> | initializers 3 { |
| 68:2| 3: <4, 0, 1> | reloc @g0 + 1; |
| 71:4| 3: <4, 1, 4294967295> | reloc @g1 - 1; |
| 79:2| 3: <4, 2, 4> | reloc @g2 + 4; |
| | | } |
| 82:4| 3: <0, 3, 0> | var @g1, align 4, |
| 85:6| 3: <2, 4> | zerofill 4; |
| 88:2| 3: <0, 3, 0> | var @g2, align 4, |
| 91:4| 3: <2, 8> | zerofill 8; |
| 94:0| 0: <65534> | } |
| |
| .. _link_for_compound_initializer: |
| |
| Compound Initializer |
| -------------------- |
| |
| The compound initializer record must immediately follow a global |
| :ref:`variable<link_for_global_variable_address>` or |
| :ref:`constant<link_for_global_constant_address>` address record. It defines how |
| many simple initializer records are used to define the initializer. The size of |
| the corresponding memory is the sum of the bytes needed for each of the |
| succeeding initializers. |
| |
| Note that a compound initializer can't be used as a simple initializer of |
| another compound initializer (i.e. nested compound initializers are not |
| allowed). |
| |
| **Syntax**:: |
| |
| initializers N { <A> |
| ... |
| } |
| |
| **Record**:: |
| |
| AA: <1, N> |
| |
| **Semantics**: |
| |
| Defines that the next `N` initializers should be associated with the global |
| address of the previous record. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| ExpectedInitializers == 1 |
| |
| **Updates**:: |
| |
| ExpectedInitializers = N; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 0> | count 0; |
| 50:4| 0: <65534> | } |
| 52:0| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 60:0| 3: <5, 2> | count 2; |
| 62:4| 3: <0, 0, 1> | const @g0, align 0, |
| 65:6| 3: <1, 2> | initializers 2 { |
| 68:2| 3: <2, 8> | zerofill 8; |
| 70:6| 3: <3, 3, 2, 1, 0> | { 3, 2, 1, 0} |
| | | } |
| 75:4| 3: <0, 0, 0> | var @g1, align 0, |
| 78:6| 3: <1, 2> | initializers 2 { |
| 81:2| 3: <3, 1, 2, 3, 4> | { 1, 2, 3, 4} |
| 86:0| 3: <2, 2> | zerofill 2; |
| | | } |
| 88:4| 0: <65534> | } |
| |
| .. _link_for_valuesymtab_block_section: |
| |
| Valuesymtab Block |
| ================= |
| |
| The valuesymtab block does not define any values. Its only goal is to associate |
| text names with external :ref:`function |
| addresses<link_for_function_address_section>`. Each association is defined by a |
| record in the valuesymtab block. Currently, only |
| :ref:`intrinsic<link_for_intrinsic_functions_section>` function addresses and |
| the (external) start function (``_start``) can be named. All named function |
| addresses must be external. Each record in the valuesymtab block is a *entry* |
| record, defining a single name association. |
| |
| Entry Record |
| ------------ |
| |
| The *entry* record defines a name for a function address. |
| |
| **Syntax**:: |
| |
| V : "NAME"; <A> |
| |
| **Record**:: |
| |
| AA: <1, B1, ... , BN> |
| |
| **Semantics**: |
| |
| The *entry* record defines a name ``NAME`` for function address ``V``. ``NAME`` |
| is a sequence of ASCII characters ``B1`` through ``BN``. |
| |
| **Examples**:: |
| |
| 72:0| 3: <8, 4, 0, 1, 0> | declare external |
| | | void @f0(i32, i32, i32, i32, i1); |
| 76:6| 3: <8, 4, 0, 1, 0> | declare external |
| | | void @f1(i32, i32, i32, i32, i1); |
| 81:4| 3: <8, 5, 0, 0, 0> | define external void @f2(i32); |
| 86:2| 1: <65535, 19, 2> | globals { // BlockID = 19 |
| 92:0| 3: <5, 0> | count 0; |
| 94:4| 0: <65534> | } |
| 96:0| 1: <65535, 14, 2> | valuesymtab { // BlockID = 14 |
| 104:0| 3: <1, 1, 108, 108, 118, | @f1 : "llvm.memmove.p0i8.p0i8.i32"; |
| | 109, 46, 109, 101, | |
| | 109, 109, 111, 118, | |
| | 101, 46, 112, 48, | |
| | 105, 56, 46, 112, 48,| |
| | 105, 56, 46, 105, 51,| |
| | 50> | |
| 145:4| 3: <1, 2, 95, 115, 116, | @f2 : "_start"; |
| | 97, 114, 116> | |
| 157:0| 3: <1, 0, 108, 108, 118, | @f0 : "llvm.memcpy.p0i8.p0i8.i32"; |
| | 109, 46, 109, 101, | |
| | 109, 99, 112, 121, | |
| | 46, 112, 48, 105, 56,| |
| | 46, 112, 48, 105, 56,| |
| | 46, 105, 51, 50> | |
| 197:0| 0: <65534> | } |
| |
| .. _link_for_module_block: |
| |
| Module Block |
| ============ |
| |
| The module block, like all blocks, is enclosed in a pair of |
| :ref:`enter<link_for_enter_block_record_section>` / |
| :ref:`exit<link_for_exit_block_record_section>` records, using block ID 8. A |
| well-formed module block consists of the following records (in order): |
| |
| A version record |
| The :ref:`version record<link_for_version_record>` communicates which version |
| of the PNaCl bitcode reader/writer should be used. Note that this is |
| different than the PNaCl bitcode (ABI) version. The PNaCl bitcode (ABI) |
| version defines what is expected in records, and is defined in the header |
| record of the bitcode file. The version record defines the version of the |
| PNaCl bitcode reader/writer to use to convert records into bit sequences. |
| |
| Optional local abbreviations |
| Defines a list of local :ref:`abbreviations<link_for_abbreviations_section>` |
| to use for records within the module block. |
| |
| An abbreviations block |
| The :ref:`abbreviations block<link_for_abbreviations_block_section>` defines |
| user-defined, global abbreviations that are used to convert PNaCl records to |
| bit sequences in blocks following the abbreviations block. |
| |
| A types block |
| The :ref:`types block<link_for_types_block_section>` defines the set of all |
| types used in the program. |
| |
| A non-empty sequence of function address records |
| Each record defines a :ref:`function |
| address<link_for_function_address_section>` used by the program. Function |
| addresses must either be external, or defined internally by the program. If |
| they are defined by the program, there must be a :ref:`function |
| block<link_for_function_blocks_section>` (appearing later in the module) that |
| defines the sequence of instructions for each defined function. |
| |
| A globals block defining the global variables. |
| This :ref:`block<link_for_globals_block_section>` defines the set of |
| global :ref:`variable<link_for_global_variable_address>` and |
| :ref:`constant<link_for_global_constant_address>` addresses used by the |
| program. In addition to the addresses, each global variable also defines how |
| the corresponding global variable is initialized. |
| |
| An optional value symbol table block. |
| This :ref:`block<link_for_valuesymtab_block_section>`, if defined, provides |
| textual names for :ref:`function |
| addresses<link_for_function_address_section>` (previously defined in the |
| module). Note that only names for intrinsic functions and the start function |
| are specified. |
| |
| A sequence of function blocks. |
| Each :ref:`function block<link_for_Function_blocks_section>` defines the |
| corresponding intermediate representation for each defined function. The |
| order of function blocks is used to associate them with :ref:`function |
| addresses<link_for_function_address_section>`. The order of the defined |
| function blocks must follow the same order as the corresponding function |
| addresses defined in the module block. |
| |
| Descriptions of the :ref:`abbreviations<link_for_abbreviations_section>`, |
| :ref:`types<link_for_types_block_section>`, |
| :ref:`globals<link_for_globals_block_section>`, :ref:`value symbol |
| table<link_for_valuesymtab_block_section>`, and |
| :ref:`function<link_for_function_blocks_section>` blocks are not provided |
| here. See the appropriate reference for more details. The following subsections |
| describe each of the records that can appear in a module block. |
| |
| .. _link_for_version_record: |
| |
| Version Record |
| -------------- |
| |
| The version record defines the implementation of the PNaCl bitstream |
| reader/writer to use. That is, the implementation that converts PNaCl records to |
| bit sequences, and converts them back to PNaCl records. Note that this is |
| different than the PNaCl version of the bitcode file (encoded in the header |
| record of the bitcode file). The PNaCl version defines the valid forms of PNaCl |
| records. The version record is specific to the PNaCl version, and may have |
| different values for different PNaCl versions. |
| |
| Note that currently, only PNaCl bitcode version 2, and version record value 1 is |
| defined. |
| |
| **Syntax**:: |
| |
| version N; <A> |
| |
| **Record**:: |
| |
| AA: <1, N> |
| |
| **Semantics**: |
| |
| The version record defines which PNaCl reader/writer rules should be |
| followed. ``N`` is the version number. Currently ``N`` must be 1. Future |
| versions of PNaCl may define additional legal values. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) |
| |
| *Examples*:: |
| |
| 16:0|1: <65535, 8, 2> |module { // BlockID = 8 |
| 24:0| 3: <1, 1> | version 1; |
| 26:4| 1: <65535, 0, 2> | abbreviations { // BlockID = 0 |
| 36:0| 0: <65534> | } |
| |
| .. _link_for_function_address_section: |
| |
| Function Address |
| ---------------- |
| |
| A function address record describes a function address. *Defined* function |
| addresses define :ref:`implementations<link_for_function_blocks_section>` while |
| *declared* function addresses do not. |
| |
| Since a PNaCl program is assumed to be a complete (statically linked) |
| executable, All functions should be *defined* and *internal*. The exception to |
| this are :ref:`intrinsic functions<link_for_intrinsic_functions_section>`, which |
| should only be *declared* and *external*, since intrinsic functions will be |
| automatically converted to appropriate code by the :ref:`PNaCl |
| translator<link_for_pnacl_translator>`. |
| |
| The implementation of a *defined* function address is provided by a |
| corresponding function block, appearing later in the module block. The |
| association of a *defined* function address with the corresponding function |
| block is based on position. The *Nth* defined function address record, in the |
| module block, has its implementation in the *Nth* function block of that module |
| block. |
| |
| **Syntax**:: |
| |
| PN LN T0 @fN ( T1 , ... , TM ); <A> |
| |
| **Record**:: |
| |
| AA: <8, T, C, P, L> |
| |
| **Semantics**: |
| |
| Describes the function address ``@fN``. ``PN`` is the name that specifies the |
| prototype value ``P`` associated with the function. A function address is |
| *defined* only if ``P == 0``. Otherwise, it is only *declared*. The type of the |
| function is :ref:`function type<link_for_function_type>` ``@tT``. ``L`` is the |
| linkage specification corresponding to name ``LN``. ``C`` is the calling |
| convention used by the function. |
| |
| Note that function signature must be defined by a function type in the types |
| block. Hence, the return value must either be a primitive type, type ``void``, |
| or a vector type. |
| |
| For ordinary functions, integer parameter and types can only be ``i32`` and |
| ``i64``. All other integer types are not allowed. For intrinsic functions, all |
| integer types are allowed. |
| |
| Valid prototype names ``PN``, and corresponding ``P`` values, are: |
| |
| = ======= |
| P PN |
| = ======= |
| 1 declare |
| 0 define |
| = ======= |
| |
| Valid linkage names ``LN``, and corresponding ``L`` values, are: |
| |
| = ======== |
| L LN |
| = ======== |
| 3 internal |
| 0 external |
| = ======== |
| |
| Currently, only one calling convention ``C`` is supported: |
| |
| = ==================== |
| C Calling Convention |
| = ==================== |
| 0 C calling convention |
| = ==================== |
| |
| **Constraints**:: |
| |
| AA = AbbrevIndex(A) & |
| T = TypeID(TypeOf(T0 ( T1 , ... , TN ))) & |
| N = NumFuncAddresses |
| |
| **Updates**:: |
| |
| ++NumFuncAddresses; |
| TypeOf(@fN) = TypeOf(TypeID(i32)); |
| TypeOfFcn(@fN) = TypeOf(@tT); |
| |
| if PN == 0: |
| DefiningFcnIDs += @FN; |
| ++NumDefinedFunctionAddresses; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 7> | count 7; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <3> | @t1 = float; |
| 55:4| 3: <4> | @t2 = double; |
| 57:2| 3: <2> | @t3 = void; |
| 59:0| 3: <21, 0, 2, 1> | @t4 = double (float); |
| 63:0| 3: <21, 0, 0, 0, 1, 0, 2>| @t5 = |
| | | i32 (i32, float, i32, double); |
| 69:2| 3: <21, 0, 3> | @t6 = void (); |
| 72:4| 0: <65534> | } |
| 76:0| 3: <8, 4, 0, 1, 0> | declare external double @f0(float); |
| 80:6| 3: <8, 5, 0, 1, 0> | declare external |
| | | i32 @f1(i32, float, i32, double); |
| 85:4| 3: <8, 6, 0, 0, 0> | define external void @f2(); |
| |
| .. _link_for_constants_block_section: |
| |
| Constants Blocks |
| ================ |
| |
| Constants blocks define literal constants used within each function. Its intent |
| is to define them once, before instructions. A constants block can only appear |
| in a :ref:`function block<link_for_function_blocks_section>`, and must appear |
| before any instructions in the function block. |
| |
| Currently, only integer literals, floating point literals, and undefined vector |
| constants can be defined. |
| |
| To minimize type information put in a constants block, the type information is |
| separated from the constants. This allows a sequence of constants to be given |
| the same type. This is done by defining a :ref:`set type |
| record<link_for_constants_set_type_record>`, followed by a sequence of literal |
| constants. These literal constants all get converted to the type of the |
| preceding set type record. |
| |
| Note that constants that are used for switch case selectors should not be added |
| to the constants block, since the switch instruction contains the constants used |
| for case selectors. All other constants in the function block must be put into a |
| constants block, so that instructions can use them. |
| |
| To make this more concrete, consider the following example constants block:: |
| |
| 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 116:0| 3: <1, 0> | i32: |
| 118:4| 3: <4, 2> | %c0 = i32 1; |
| 121:0| 3: <4, 4> | %c1 = i32 2; |
| 123:4| 3: <1, 2> | i8: |
| 126:0| 3: <4, 8> | %c2 = i8 4; |
| 128:4| 3: <4, 6> | %c3 = i8 3; |
| 131:0| 3: <1, 1> | float: |
| 133:4| 3: <6, 1065353216> | %c4 = float 1; |
| 139:6| 0: <65534> | } |
| |
| .. _link_for_constants_set_type_record: |
| |
| Set Type Record |
| --------------- |
| |
| The *set type* record defines the type to use for the (immediately) succeeding |
| literals. |
| |
| **Syntax**:: |
| |
| T: <A> |
| |
| **Record**:: |
| |
| AA: <1, TT> |
| |
| **Semantics**: |
| |
| The *set type* record defines type ``T`` to be used to type the (immediately) |
| succeeding literals. ``T`` must be a non-void primitive value type or a vector |
| type. |
| |
| **Constraints**:: |
| |
| TT == TypeID(T) |
| |
| **Updates**:: |
| |
| ConstantsSetType = T; |
| |
| **Examples**:: |
| |
| 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 116:0| 3: <1, 0> | i32: |
| 118:4| 3: <4, 2> | %c0 = i32 1; |
| 121:0| 3: <4, 4> | %c1 = i32 2; |
| 123:4| 3: <1, 2> | i8: |
| 126:0| 3: <4, 8> | %c2 = i8 4; |
| 128:4| 3: <4, 6> | %c3 = i8 3; |
| 131:0| 3: <1, 1> | float: |
| 133:4| 3: <6, 1065353216> | %c4 = float 1; |
| 139:6| 0: <65534> | } |
| |
| .. _link_for_undefined_literal: |
| |
| Undefined Literal |
| ----------------- |
| |
| The *undefined* literal record creates an undefined literal for the type *T* |
| defined by the preceding *set type* record. |
| |
| Note: See :ref:`insert element |
| instruction<link_for_insert_element_instruction_section>` for an example of how |
| you would use the undefined literal with vector types. |
| |
| **Syntax**:: |
| |
| %cN = T undef; <50> |
| |
| **Record**:: |
| |
| AA: <3> |
| |
| **Semantics**: |
| |
| The *undefined* literal record creates an undefined literal constant ``%cN`` for |
| type ``T``. ``T`` must be the type defined by the preceding *set type* record, |
| and be a primitive value type or a vector type. |
| |
| **Constraints**:: |
| |
| N == NumFcnConsts & |
| T == ConstantsSetType & |
| IsPrimitive(T) or IsVector(T) |
| |
| **Updates**:: |
| |
| ++NumFcnConsts; |
| TypeOf(%cN) = T; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 5> | count 5; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <3> | @t1 = float; |
| 55:4| 3: <2> | @t2 = void; |
| 57:2| 3: <12, 4, 0> | @t3 = <4 x i32>; |
| 60:4| 3: <21, 0, 2> | @t4 = void (); |
| 63:6| 0: <65534> | } |
| ... |
| 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 116:0| 3: <1, 0> | i32: |
| 118:4| 3: <3> | %c0 = i32 undef; |
| 120:2| 3: <4, 2> | %c1 = i32 1; |
| 122:6| 3: <1, 3> | <4 x i32>: |
| 125:2| 3: <3> | %c2 = <4 x i32> undef; |
| 127:0| 3: <1, 1> | float: |
| 129:4| 3: <3> | %c3 = float undef; |
| 131:2| 0: <65534> | } |
| |
| .. _link_for_integer_literal: |
| |
| Integer Literal |
| --------------- |
| |
| The *integer literal* record creates an integer literal for the integer type *T* |
| defined by the preceding *set type* record. |
| |
| **Syntax**:: |
| |
| %cN = T V; <A> |
| |
| **Record**:: |
| |
| AA: <4, VV> |
| |
| **Semantics**: |
| |
| The *integer literal* record creates an integer literal constant ``%cN`` for |
| type ``T``. ``T`` must be the type defined by the preceding *set type* record, |
| and an integer type. The literal ``V`` can be signed, but must be definable by |
| type ``T``. |
| |
| **Constraints**:: |
| |
| N == NumFcnConsts & |
| T == ConstantsSetType & |
| VV == SignRotate(V) & |
| IsInteger(T) |
| |
| **Updates**:: |
| |
| TypeOf(%cN) = T; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 7> | count 7; |
| 50:4| 3: <7, 8> | @t0 = i8; |
| 53:0| 3: <7, 16> | @t1 = i16; |
| 55:4| 3: <7, 32> | @t2 = i32; |
| 58:6| 3: <7, 64> | @t3 = i64; |
| 62:0| 3: <7, 1> | @t4 = i1; |
| 64:4| 3: <2> | @t5 = void; |
| 66:2| 3: <21, 0, 5> | @t6 = void (); |
| 69:4| 0: <65534> | } |
| ... |
| 114:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 124:0| 3: <1, 0> | i8: |
| 126:4| 3: <4, 2> | %c0 = i8 1; |
| 129:0| 3: <4, 4> | %c1 = i8 2; |
| 131:4| 3: <1, 1> | i16: |
| 134:0| 3: <4, 6> | %c2 = i16 3; |
| 136:4| 3: <4, 8> | %c3 = i16 4; |
| 139:0| 3: <1, 2> | i32: |
| 141:4| 3: <4, 10> | %c4 = i32 5; |
| 144:0| 3: <4, 12> | %c5 = i32 6; |
| 146:4| 3: <1, 3> | i64: |
| 149:0| 3: <4, 3> | %c6 = i64 -1; |
| 151:4| 3: <4, 5> | %c7 = i64 -2; |
| 154:0| 3: <1, 4> | i1: |
| 156:4| 3: <4, 3> | %c8 = i1 1; |
| 159:0| 3: <4, 0> | %c9 = i1 0; |
| 161:4| 0: <65534> | } |
| |
| Floating Point Literal |
| ---------------------- |
| |
| The *floating point literal* record creates a floating point literal for the |
| floating point type *T* defined by the preceding *set type* record. |
| |
| **Syntax**:: |
| |
| %cN = T V; <A> |
| |
| **Record**:: |
| |
| AA: <6, VV> |
| |
| **Semantics**: |
| |
| The *floating point literal* record creates a floating point literal constant |
| ``%cN`` for type ``T``. ``T`` must the type type defined by the preceding *set |
| type* record, and be a floating point type. The literal ``V`` is the floating |
| value to be defined. The value ``VV`` if the corresponding IEEE unsigned integer |
| that defines value ``V``. That is, the literal ``VV`` must be a valid IEEE 754 |
| 32-bit (unsigned integer) value if ``T`` is ``float``, and a valid IEEE 754 |
| 64-bit (unsigned integer) value if ``T`` is ``double``. |
| |
| **Constraints**:: |
| |
| N == NumFcnConsts |
| T == ConstantsSetType |
| IsFloat(T) |
| |
| **Updates**:: |
| |
| TypeOf(%cN) = T; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <3> | @t0 = float; |
| 52:2| 3: <4> | @t1 = double; |
| 54:0| 3: <2> | @t2 = void; |
| 55:6| 3: <21, 0, 2> | @t3 = void (); |
| 59:0| 0: <65534> | } |
| ... |
| 102:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 112:0| 3: <1, 0> | float: |
| 114:4| 3: <6, 0> | %c0 = float 0; |
| 117:0| 3: <6, 1065353216> | %c1 = float 1; |
| 123:2| 3: <6, 1088421888> | %c2 = float 7; |
| 130:2| 3: <6, 1090519040> | %c3 = float 8; |
| 137:2| 3: <3> | %c4 = float undef; |
| 139:0| 3: <6, 2143289344> | %c5 = float nan; |
| 146:0| 3: <6, 2139095040> | %c6 = float inf; |
| 153:0| 3: <6, 4286578688> | %c7 = float -inf; |
| 160:0| 3: <1, 1> | double: |
| 162:4| 3: <6, | %c8 = double 1; |
| | 4607182418800017408> | |
| 174:0| 3: <6, 0> | %c9 = double 0; |
| 176:4| 3: <6, | %c10 = double 5; |
| | 4617315517961601024> | |
| 188:0| 3: <6, | %c11 = double 6; |
| | 4618441417868443648> | |
| 199:4| 3: <6, | %c12 = double nan; |
| | 9221120237041090560> | |
| 211:0| 3: <6, | %c13 = double inf; |
| | 9218868437227405312> | |
| 222:4| 3: <6, | %c14 = double -inf; |
| | 18442240474082181120>| |
| 234:0| 0: <65534> | } |
| |
| .. _link_for_function_blocks_section: |
| |
| Function Blocks |
| =============== |
| |
| A function block defines the implementation of a defined :ref:`function |
| address<link_for_function_address_section>`. The function address it defines is |
| based on the position of the corresponding defined function address. The Nth |
| defined function address always corresponds to the Nth function block in the |
| module block. |
| |
| A function implementation contains a list of basic blocks, forming the control |
| flow graph. Each *basic block* contains a list of instructions, and ends with a |
| :ref:`terminator instruction<link_for_terminator_instruction_section>` |
| (e.g. branch). |
| |
| Basic blocks are not represented by records. Rather, context is implicit. The |
| first basic block begins with the first instruction record in the function |
| block. Block boundaries are determined by terminator instructions. The |
| instruction that follows a terminator instruction begins a new basic block. |
| |
| The first basic block in a function is special in two ways: it is immediately |
| executed on entrance to the function, and it is not allowed to have predecessor |
| basic blocks (i.e. there can't be any branches to the entry block of a |
| function). Because the entry block has no predecessors, it also can't have any |
| :ref:`phi<link_for_phi_instruction_section>` instructions. |
| |
| The parameters are implied by the type of the corresponding function |
| address. One parameter is defined for each argument of the function :ref:`type |
| signature<link_for_function_type>` of the corresponding :ref:`function |
| address<link_for_function_address_section>`. |
| |
| The number of basic blocks is defined by the :ref:`count |
| record<link_for_basic_blocks_count>`. Each :ref:`terminator |
| instruction<link_for_terminator_instruction_section>` ends the current basic |
| block, and the next instruction begins a new basic block. Basic blocks are |
| numbered by the order they appear (starting with index 0). Basic block IDs have |
| the form ``%bN``, where ``N`` corresponds to the position of the basic block |
| within the function block. |
| |
| Each instruction, within a function block, corresponds to a corresponding PNaCl |
| record. The layout of a function block is the (basic block) count record, |
| followed by a sequence of instruction records. |
| |
| For readability, PNaClAsm introduces basic block IDs. These basic block IDs do |
| not correspond to PNaCl records, since basic block boundaries are defined |
| implicitly, after terminator instructions. They appear only for readability. |
| |
| Operands of instructions are defined using an :ref:`absolute |
| index<link_for_absolute_index_section>`. This absolute index implicitly encodes |
| function addresses, global addresses, parameters, constants, and instructions |
| that generate values. The encoding takes advantage of the implied ordering of |
| these values in the bitcode file, defining a contiguous sequence of indices for |
| each kind of identifier. That is, indices are ordered by putting function |
| address identifiers first, followed by global address identifiers, followed by |
| parameter identifiers, followed by constant identifiers, and lastly instruction |
| value identifiers. |
| |
| To save space in the encoded bitcode file, most operands are encoded using a |
| :ref:`relative index<link_for_relative_index>` value, rather than |
| :ref:`absolute<link_for_absolute_index_section>`. This |
| is done because most instruction operands refer to values defined earlier in the |
| (same) basic block. As a result, the relative distance (back) from the next |
| value defining instruction is frequently a small number. Small numbers tend to |
| require fewer bits when they are converted to bit sequences. |
| |
| Note that instructions that can appear in a function block are defined in |
| sections :ref:`link_for_terminator_instruction_section`, |
| :ref:`link_for_integer_binary_instructions`, |
| :ref:`link_for_floating_point_binary_instructions`, |
| :ref:`link_for_memory_creation_and_access_instructions`, |
| :ref:`link_for_conversion_instructions`, :ref:`link_for_compare_instructions`, |
| :ref:`link_for_vector_instructions`, and |
| :ref:`link_for_other_pnaclasm_instructions`. |
| |
| The following subsections define the remaining records that can appear in a |
| function block. |
| |
| Function Enter |
| -------------- |
| |
| PNaClAsm defines a function enter block construct. The corresponding record is |
| simply an :ref:`enter block<link_for_enter_block_record_section>` record, with |
| BlockID value ``12``. All context about the defining address is implicit by the |
| position of the function block, and the corresponding defining :ref:`function |
| address<link_for_function_address_section>`. To improve readability, PNaClAsm |
| includes the function signature into the syntax rule. |
| |
| **Syntax**:: |
| |
| function TR @fN ( T0 %p0, ... , TM %pM ) { <B> |
| |
| **Record**:: |
| |
| 1: <65535, 12, B> |
| |
| **Semantics**: |
| |
| ``B`` is the number of bits reserved for abbreviations in the block. If it is |
| omitted, 2 is assumed. See :ref:`enter<link_for_enter_block_record_section>` |
| block records for more details. |
| |
| The value of ``N`` corresponds to the positional index of the corresponding |
| defining function address this block is associated with. ``M`` is the number of |
| defined parameters (minus one) in the function heading. |
| |
| **Constraints**:: |
| |
| N == NumFcnImpls & |
| @fN in DefiningFcnIDs & |
| TypeOfFcn(@fN) == TypeOf(TypeID(TR (T0, ... , TM))) |
| |
| **Updates**:: |
| |
| ++NumFcnImpls; |
| EnclosingFcnID = @fN; |
| NumBasicBlocks = 0; |
| ExpectedBlocks = 0; |
| NumParams = M; |
| for I in [0..M]: |
| TypeOf(%pI) = TypeOf(TypeID(TI)); |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <2> | @t1 = void; |
| 55:4| 3: <21, 0, 1> | @t2 = void (); |
| 58:6| 3: <21, 0, 0, 0> | @t3 = i32 (i32); |
| 62:6| 0: <65534> | } |
| ... |
| 104:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 112:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 114:4| 3: <10> | ret void; |
| 116:2| 0: <65534> | } |
| 120:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { |
| | | // BlockID = 12 |
| 128:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 130:4| 3: <10, 1> | ret i32 %p0; |
| 133:0| 0: <65534> | } |
| |
| .. _link_for_basic_blocks_count: |
| |
| Count Record |
| ------------ |
| |
| The count record, within a function block, defines the number of basic blocks |
| used to define the function implementation. It must be the first record in the |
| function block. |
| |
| **Syntax**:: |
| |
| blocks: N; <A> |
| %b0: |
| |
| **Record**:: |
| |
| AA: <1, N> |
| |
| **Semantics**: |
| |
| The count record defines the number ``N`` of basic blocks in the implemented |
| function. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| ExpectedBasicBlocks == N & |
| NumBasicBlocks == 0 |
| |
| **Updates**:: |
| |
| 104:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 112:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 114:4| 3: <10> | ret void; |
| 116:2| 0: <65534> | } |
| 120:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { |
| | | // BlockID = 12 |
| 128:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 130:4| 3: <10, 1> | ret i32 %p0; |
| 133:0| 0: <65534> | } |
| |
| .. _link_for_terminator_instruction_section: |
| |
| Terminator Instructions |
| ======================= |
| |
| Terminator instructions are instructions that appear in a :ref:`function |
| block<link_for_function_blocks_section>`, and define the end of the current |
| basic block. A terminator instruction indicates which block should be executed |
| after the current block is finished. The function block is well formed only if |
| the number of terminator instructions, in the function block, corresponds to the |
| value defined by the corresponding function basic block :ref:`count |
| record<link_for_basic_blocks_count>`. |
| |
| Note that any branch instruction to label ``%bN``, where ``N >= |
| ExpectedBasicBlocks``, is illegal. For ease of readability, this constraint |
| hasn't been put on branch instructions. Rather it is only implied. |
| |
| In addition, it must be the case that ``NumBasicBlocks < ExpectedBasicBlocks``, |
| and will not be listed as a constraint. Further, if ``B = NumBasicBlocks + 1`` |
| is the number associated with the next basic block. Label `%bB:` only appears |
| if:: |
| |
| B < ExpectedBasicBlocks |
| |
| That is, the label is omitted only if this terminator instruction is the last |
| instruction in the function block. |
| |
| Return Void Instruction |
| ----------------------- |
| |
| The return void instruction is used to return control from a function back to |
| the caller, without returning any value. |
| |
| **Syntax**:: |
| |
| ret void; <A> |
| %bB: |
| |
| **Record**:: |
| |
| AA: <10> |
| |
| **Semantics**: |
| |
| The return void instruction returns control to the calling function. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| B == NumBasicBlocks + 1 & |
| ReturnType(TypeOf(EnclosingFcnID)) == void |
| |
| **Updates**:: |
| |
| ++NumBasicBlocks; |
| |
| **Examples**:: |
| |
| 104:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 112:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 114:4| 3: <10> | ret void; |
| 116:2| 0: <65534> | } |
| |
| Return Value Instruction |
| ------------------------ |
| |
| The return value instruction is used to return control from a function back to |
| the caller, including a value. The value must correspond to the return type of |
| the enclosing function. |
| |
| **Syntax**:: |
| |
| ret T V; <A> |
| %bB: |
| |
| **Record**:: |
| |
| AA: <10, VV> |
| |
| **Semantics**: |
| |
| The return value instruction returns control to the calling function, returning |
| the provided value. |
| |
| ``V`` is the value to return. Type ``T`` must be of the type returned by the |
| function. It must also be the type associated with value ``V``. |
| |
| The return type ``T`` must either be a (non-void) primitive type, or a vector |
| type. If the function block is implementing an ordinary function, and the return |
| type is an integer type, it must be either ``i32`` or ``i64``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV == RelativeIndex(V) & |
| B == NumBasicBlocks + 1 & |
| T == TypeOf(V) == ReturnType(TypeOf(EnclosingFcnID)) |
| |
| **Updates**:: |
| |
| ++NumBasicBlocks; |
| |
| **Examples**:: |
| |
| 120:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { |
| | | // BlockID = 12 |
| 128:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 130:4| 3: <10, 1> | ret i32 %p0; |
| |
| Unconditional Branch Instruction |
| -------------------------------- |
| |
| The unconditional branch instruction is used to cause control flow to transfer |
| to a different basic block of the function. |
| |
| **Syntax**:: |
| |
| br %bN; <A> |
| %bB: |
| |
| **Record**:: |
| |
| AA: <11, N> |
| |
| **Semantics**: |
| |
| The unconditional branch instruction causes control flow to transfer to basic |
| block ``N``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| B == NumBasicBlocks + 1 & |
| 0 < N & |
| N < ExpectedBasicBlocks |
| |
| **Updates**:: |
| |
| ++NumBasicBlocks; |
| |
| **Examples**:: |
| |
| 88:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 96:0| 3: <1, 5> | blocks 5; |
| | | %b0: |
| 98:4| 3: <11, 3> | br label %b3; |
| | | %b1: |
| 101:0| 3: <11, 4> | br label %b4; |
| | | %b2: |
| 103:4| 3: <11, 1> | br label %b1; |
| | | %b3: |
| 106:0| 3: <11, 2> | br label %b2; |
| | | %b4: |
| 108:4| 3: <10> | ret void; |
| 110:2| 0: <65534> | } |
| |
| Conditional Branch Instruction |
| ------------------------------ |
| |
| The conditional branch instruction is used to cause control flow to transfer to |
| a different basic block of the function, based on a boolean test condition. |
| |
| **Syntax**:: |
| |
| br i1 C, %bT, %bBF; <A> |
| %bB: |
| |
| **Record**:: |
| |
| AA: <11, T, F, CC> |
| |
| **Semantics**: |
| |
| Upon execution of a conditional branch instruction, the *i1* (boolean) argument |
| ``C`` is evaluated. If the value is ``true``, control flows to basic block |
| ``%bT``. Otherwise control flows to basic block ``%bF``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| CC == RelativeIndex(C) & |
| B == NumBasicBlocks + 1 & |
| 0 < T & |
| B1 < ExpectedBasicBlocks & |
| 0 < F & |
| B2 < ExpectedBasicBlocks & |
| TypeOf(C) == i1 |
| |
| **Updates**:: |
| |
| ++NumBasicBlocks; |
| |
| **Examples**:: |
| |
| 92:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 5> | blocks 5; |
| 102:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 112:0| 3: <1, 1> | i1: |
| 114:4| 3: <4, 3> | %c0 = i1 1; |
| 117:0| 3: <4, 0> | %c1 = i1 0; |
| 119:4| 0: <65534> | } |
| | | %b0: |
| 120:0| 3: <11, 3> | br label %b3; |
| | | %b1: |
| 122:4| 3: <11, 2, 4, 2> | br i1 %c0, label %b2, label %b4; |
| | | %b2: |
| 126:4| 3: <11, 3> | br label %b3; |
| | | %b3: |
| 129:0| 3: <10> | ret void; |
| | | %b4: |
| 130:6| 3: <11, 2, 3, 1> | br i1 %c1, label %b2, label %b3; |
| 134:6| 0: <65534> | } |
| |
| Unreachable |
| ----------- |
| |
| The unreachable instruction has no defined semantics. The instruction is used to |
| inform the :ref:`PNaCl translator<link_for_pnacl_translator>` that control |
| can't reach this instruction. |
| |
| **Syntax**:: |
| |
| unreachable; <A> |
| %bB: |
| |
| **Record**:: |
| |
| AA: <15> |
| |
| **Semantics**: |
| |
| Directive to the :ref:`PNaCl translator<link_for_pnacl_translator>` that |
| this instruction is unreachable. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) |
| B == NumBasicBlocks + 1 & |
| |
| **Updates**:: |
| |
| ++NumBasicBlocks; |
| |
| **Examples**:: |
| |
| 108:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { |
| | | // BlockID = 12 |
| 116:0| 3: <1, 5> | blocks 5; |
| 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 128:0| 3: <1, 2> | i1: |
| 130:4| 3: <4, 3> | %c0 = i1 1; |
| 133:0| 3: <4, 0> | %c1 = i1 0; |
| 135:4| 0: <65534> | } |
| | | %b0: |
| 136:0| 3: <11, 1, 2, 2> | br i1 %c0, label %b1, label %b2; |
| | | %b1: |
| 140:0| 3: <11, 3, 4, 1> | br i1 %c1, label %b3, label %b4; |
| | | %b2: |
| 144:0| 3: <15> | unreachable; |
| | | %b3: |
| 145:6| 3: <15> | unreachable; |
| | | %b4: |
| 147:4| 3: <10> | ret void; |
| 149:2| 0: <65534> | } |
| |
| Switch Instruction |
| ------------------ |
| |
| The *switch* instruction transfers control flow to one of several different |
| places, based on a selector value. It is a generalization of the conditional |
| branch instruction. |
| |
| **Syntax**:: |
| |
| switch T V0 { |
| default: br label %bB0; |
| T V1: br label %bB1; |
| ... |
| T VN: br label %bBN; |
| } <A> |
| %bB: |
| |
| **Record**:: |
| |
| AA: <12, TT, B0, N, (1, 1, VVI, BI | 1 <= i <= N)> |
| |
| **Semantics**: |
| |
| The switch instruction transfers control to a basic block in ``B0`` through |
| ``BN``. Value ``V`` is used to conditionally select which block to branch |
| to. ``T`` is the type of ``V`` and ``V1`` through ``VN``, and must be an integer |
| type. Value ``V1`` through ``VN`` are integers to compare against ``V``. If |
| selector ``V`` matches ``VI`` (for some ``I``, ``1 <= I <= N``), then the |
| instruction branches to block ``BI``. If ``V`` is not in ``V1`` through ``VN``, |
| the instruction branches to block ``B0``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| B == NumBasicBlocks + 1 & |
| TT == TypeID(T) & |
| VI == SignRotate(VI) for all I, 1 <= I <= N & |
| |
| **Updates**:: |
| |
| ++NumBasicBlocks; |
| |
| **Examples**:: |
| |
| 116:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { |
| | | // BlockID = 12 |
| 124:0| 3: <1, 6> | blocks 6; |
| | | %b0: |
| 126:4| 3: <12, 1, 1, 2, 4, 1, 1,| switch i32 %p0 { |
| | 2, 3, 1, 1, 4, 3, 1, | default: br label %b2; |
| | 1, 8, 4, 1, 1, 10, 4>| i32 1: br label %b3; |
| | | i32 2: br label %b3; |
| | | i32 4: br label %b4; |
| | | i32 5: br label %b4; |
| | | } |
| | | %b1: |
| 143:2| 3: <11, 5> | br label %b5; |
| | | %b2: |
| 145:6| 3: <11, 5> | br label %b5; |
| | | %b3: |
| 148:2| 3: <11, 5> | br label %b5; |
| | | %b4: |
| 150:6| 3: <11, 5> | br label %b5; |
| | | %b5: |
| 153:2| 3: <10> | ret void; |
| 155:0| 0: <65534> | } |
| 156:0| 1: <65535, 12, 2> | function void @f1(i64 %p0) { |
| | | // BlockID = 12 |
| 164:0| 3: <1, 6> | blocks 6; |
| | | %b0: |
| 166:4| 3: <12, 2, 1, 2, 4, 1, 1,| switch i64 %p0 { |
| | 2, 3, 1, 1, 4, 3, 1, | default: br label %b2; |
| | 1, 8, 4, 1, 1, | i64 1: br label %b3; |
| | 39777555332, 4> | i64 2: br label %b3; |
| | | i64 4: br label %b4; |
| | | i64 19888777666: br label %b4; |
| | | } |
| | | %b1: |
| 188:4| 3: <11, 5> | br label %b5; |
| | | %b2: |
| 191:0| 3: <11, 5> | br label %b5; |
| | | %b3: |
| 193:4| 3: <11, 5> | br label %b5; |
| | | %b4: |
| 196:0| 3: <11, 5> | br label %b5; |
| | | %b5: |
| 198:4| 3: <10> | ret void; |
| 200:2| 0: <65534> | } |
| |
| .. _link_for_integer_binary_instructions: |
| |
| Integer Binary Instructions |
| =========================== |
| |
| Binary instructions are used to do most of the computation in a program. This |
| section focuses on binary instructions that operator on integer values, or |
| vectors of integer values. |
| |
| All binary operations require two operands of the same type, execute an |
| operation on them, and produce a value. The value may represent multiple values |
| if the type is a vector type. The result value always has the same type as its |
| operands. |
| |
| Some integer binary operations can be applied to both signed and unsigned |
| integers. Others, the sign is significant. In general, if the sign plays a role |
| in the instruction, the sign information is encoded into the name of the |
| instruction. |
| |
| For most binary operations (except some of the logical operations), integer |
| type i1 is disallowed. |
| |
| Integer Add |
| ----------- |
| |
| The integer add instruction returns the sum of its two arguments. Both arguments |
| and the result must be of the same type. That type must be integer, or an |
| integer vector type. |
| |
| **Syntax**:: |
| |
| %vN = add T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 0> |
| |
| **Semantics**: |
| |
| The integer add instruction returns the sum of its two arguments. Arguments |
| ``V1`` and ``V2``, and the result ``%vN``, must be of type ``T``. ``T`` must be |
| an integer type, or an integer vector type. ``N`` is defined by the record |
| position, defining the corresponding value generated by the instruction. |
| |
| The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` |
| is the bit width of the integer result. |
| |
| Because integers are assumed to use a two's complement representation, |
| this instruction is appropriate for both signed and unsigned integers. |
| |
| In the add instruction, integer type ``i1`` (and a vector of integer type |
| ``i1``) is disallowed. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 0> | %v0 = add i32 %p0, %p1; |
| 110:4| 3: <2, 3, 1, 0> | %v1 = add i32 %p0, %v0; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Integer Subtract |
| ---------------- |
| |
| The integer subtract instruction returns the difference of its two arguments. |
| Both arguments and the result must be of the same type. That type must be |
| integer, or an integer vector type. |
| |
| Note: Since there isn't a negate instruction, subtraction from constant zero |
| should be used to negate values. |
| |
| **Syntax**:: |
| |
| %vN = sub T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 1> |
| |
| **Semantics**: |
| |
| The integer subtract returns the difference of its two arguments. Arguments |
| ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` must be |
| an integer type, or an integer vector type. ``N`` is defined by the record |
| position, defining the corresponding value generated by the instruction. |
| |
| The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` |
| is the bit width of the integer result. |
| |
| Because integers are assumed to use a two's complement representation, |
| this instruction is appropriate for both signed and unsigned integers. |
| |
| In the subtract instruction, integer type ``i1`` (and a vector of integer type |
| ``i1``) is disallowed. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 1> | %v0 = sub i32 %p0, %p1; |
| 110:4| 3: <2, 3, 1, 1> | %v1 = sub i32 %p0, %v0; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Integer Multiply |
| ---------------- |
| |
| The integer multiply instruction returns the product of its two arguments. Both |
| arguments and the result must be of the same type. That type must be integer, |
| or an integer based vector type. |
| |
| **Syntax**:: |
| |
| &vN = mul T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 2> |
| |
| **Semantics**: |
| |
| The integer multiply instruction returns the product of its two |
| arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type |
| ``T``. ``T`` must be an integer type, or an integer vector type. ``N`` is |
| defined by the record position, defining the corresponding value generated by |
| the instruction. |
| |
| The result returned is the mathematical result modulo 2\ :sup:`n`\ , where ``n`` |
| is the bit width of the integer result. |
| |
| Because integers are assumed to use a two's complement representation, |
| this instruction is appropriate for both signed and unsigned integers. |
| |
| In the subtract instruction, integer type ``i1`` (or a vector on integer type |
| ``i1``) is disallowed. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 2> | %v0 = mul i32 %p0, %p1; |
| 110:4| 3: <2, 1, 3, 2> | %v1 = mul i32 %v0, %p0; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Signed Integer Divide |
| --------------------- |
| |
| The signed integer divide instruction returns the quotient of its two arguments. |
| Both arguments and the result must be of the same type. That type must be |
| integer, or an integer vector type. |
| |
| **Syntax**:: |
| |
| %vN = sdiv T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 4> |
| |
| **Semantics**: |
| |
| The signed integer divide instruction returns the quotient of its two |
| arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type |
| ``T``. ``T`` must be a integer type, or an integer vector type. ``N`` is defined |
| by the record position, defining the corresponding value generated by the |
| instruction. |
| |
| Signed values are assumed. Note that signed and unsigned integer division are |
| distinct operations. For unsigned integer division use the unsigned integer |
| divide instruction (udiv). |
| |
| In the signed integer divide instruction, integer type ``i1`` (and a vector of |
| integer type ``i1``) is disallowed. Integer division by zero is guaranteed to |
| trap. |
| |
| Note that overflow can happen with this instruction when dividing the maximum |
| negative integer by ``-1``. The behavior for this case is currently undefined. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 4> | %v0 = sdiv i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 4> | %v1 = sdiv i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Unsigned Integer Divide |
| ----------------------- |
| |
| The unsigned integer divide instruction returns the quotient of its two |
| arguments. Both the arguments and the result must be of the same type. That type |
| must be integer, or an integer vector type. |
| |
| **Syntax**:: |
| |
| %vN = udiv T V1, V2; <a> |
| |
| **Record**:: |
| |
| AA: <2, A1, A2, 3> |
| |
| **Semantics**: |
| |
| The unsigned integer divide instruction returns the quotient of its two |
| arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must be of type |
| ``T``. ``T`` must be an integer type, or an integer vector type. ``N`` is |
| defined by the record position, defining the corresponding value generated by |
| the instruction. |
| |
| Unsigned integer values are assumed. Note that signed and unsigned integer |
| division are distinct operations. For signed integer division use the signed |
| integer divide instruction (sdiv). |
| |
| In the unsigned integer divide instruction, integer type ``i1`` (and a vector of |
| integer type ``i1``) is disallowed. Division by zero is guaranteed to trap. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 3> | %v0 = udiv i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 3> | %v1 = udiv i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Signed Integer Remainder |
| ------------------------ |
| |
| The signed integer remainder instruction returns the remainder of the quotient |
| of its two arguments. Both arguments and the result must be of the same |
| type. That type must be integer, or an integer based vector type. |
| |
| **Syntax**:: |
| |
| %vN = srem T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 6> |
| |
| **Semantics**: |
| |
| The signed integer remainder instruction returns the remainder of the quotient |
| of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must |
| be of type ``T``. ``T`` must be a integer type, or an integer vector type. ``N`` |
| is defined by the record position, defining the corresponding value generated by |
| the instruction. |
| |
| Signed values are assumed. Note that signed and unsigned integer division are |
| distinct operations. For unsigned integer division use the unsigned integer |
| remainder instruction (urem). |
| |
| In the signed integer remainder instruction, integer type ``i1`` (and a vector |
| of integer type ``i1``) is disallowed. Division by zero is guaranteed to trap. |
| |
| Note that overflow can happen with this instruction when dividing the maximum |
| negative integer by ``-1``. The behavior for this case is currently undefined. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 6> | %v0 = srem i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 6> | %v1 = srem i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Unsigned Integer Remainder Instruction |
| -------------------------------------- |
| |
| The unsigned integer remainder instruction returns the remainder of the quotient |
| of its two arguments. Both the arguments and the result must be of the same |
| type. The type must be integer, or an integer vector type. |
| |
| **Syntax**:: |
| |
| %vN = urem T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, A1, A2, 5> |
| |
| **Semantics**: |
| |
| The unsigned integer remainder instruction returns the remainder of the quotient |
| of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN``, must |
| be of type ``T``. ``T`` must be an integer type, or an integer vector type. |
| ``N`` is defined by the record position, defining the corresponding value |
| generated by the instruction. |
| |
| Unsigned values are assumed. Note that signed and unsigned integer division are |
| distinct operations. For signed integer division use the remainder instruction |
| (srem). |
| |
| In the unsigned integer remainder instruction, integer type ``i1`` (and a vector |
| of integer type ``i1``) is disallowed. Division by zero is guaranteed to trap. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 5> | %v0 = urem i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 5> | %v1 = urem i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Shift Left |
| ---------- |
| |
| The (integer) shift left instruction returns the first operand, shifted to the |
| left a specified number of bits with zero fill. The shifted value must be |
| integer, or an integer vector type. |
| |
| **Syntax**:: |
| |
| %vN = shl T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 7> |
| |
| **Semantics**: |
| |
| This instruction performs a shift left operation. Arguments ``V1`` and ``V2`` |
| and the result ``%vN`` must be of type ``T``. ``T`` must be an integer, or a |
| vector of integers. ``N`` is defined by the record position, defining the |
| corresponding value generated by the instruction. |
| |
| ``V2`` is assumed to be unsigned. The least significant bits of the result will |
| be filled with zero bits after the shift. If ``V2`` is (statically or |
| dynamically) negative or equal to or larger than the number of bits in |
| ``V1``, the result is undefined. If the arguments are vectors, each vector |
| element of ``V1`` is shifted by the corresponding shift amount in ``V2``. |
| |
| In the shift left instruction, integer type ``i1`` (and a vector of integer type |
| ``i1``) is disallowed. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 7> | %v0 = shl i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 7> | %v1 = shl i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Logical Shift Right |
| ------------------- |
| |
| The logical shift right instruction returns the first operand, shifted to the |
| right a specified number of bits with zero fill. |
| |
| **Syntax**:: |
| |
| %vN = lshr T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 8> |
| |
| **Semantics**: |
| |
| This instruction performs a logical shift right operation. Arguments ``V1`` and |
| ``V2`` and the result ``%vN`` must be of type ``T``. ``T`` must be an integer, |
| or a vector of integers. ``N`` is defined by the record position, defining the |
| corresponding value generated by the instruction. |
| |
| ``V2`` is assumed to be unsigned. The most significant bits of the result will |
| be filled with zero bits after the shift. If ``V2`` is (statically or |
| dynamically) negative or equal to or larger than the number of bits in ``V1``, |
| the result is undefined. If the arguments are vectors, each vector element of |
| ``V1`` is shifted by the corresponding shift amount in ``V2``. |
| |
| In the logical shift right instruction, integer type ``i1`` (and a vector of |
| integer type ``i1``) is disallowed. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 8> | %v0 = lshr i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 8> | %v1 = lshr i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Arithmetic Shift Right |
| ---------------------- |
| |
| The arithmetic shift right instruction returns the first operand, shifted to the |
| right a specified number of bits with sign extension. |
| |
| **Syntax**:: |
| |
| %vN = ashr T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VVA2, 9> |
| |
| **Semantics**: |
| |
| This instruction performs an arithmetic shift right operation. Arguments ``V1`` |
| and ``V2`` and and the result ``%vN`` must be of type ``T``. ``T`` must be an |
| integer, or a vector of integers. ``N`` is defined by the record position, |
| defining the corresponding value generated by the instruction. |
| |
| ``V2`` is assumed to be unsigned. The most significant bits of the result will |
| be filled with the sign bit of ``V1``. If ``V2`` is (statically or dynamically) |
| negative or equal to or larger than the number of bits in ``V1``, the result is |
| undefined. If the arguments are vectors, each vector element of ``V1`` is |
| shifted by the corresponding shift amount in ``V2``. |
| |
| In the arithmetic shift right instruction, integer type ``i1`` (and a vector of |
| integral type ``i1``) is disallowed. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T)) & |
| UnderlyingType(T) != i1 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 9> | %v0 = ashr i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 9> | %v1 = ashr i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Logical And |
| ----------- |
| |
| The *and* instruction returns the bitwise logical and of its two operands. |
| |
| **Syntax**:: |
| |
| %vN = and T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 10> |
| |
| **Semantics**: |
| |
| This instruction performs a bitwise logical and of its arguments. Arguments |
| ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` must be |
| an integer, or a vector of integers. ``N`` is defined by the record position, |
| defining the corresponding value generated by the instruction. ``A`` is the |
| (optional) abbreviation associated with the corresponding record. |
| |
| The truth table used for the *and* instruction is: |
| |
| ===== ===== ====== |
| Arg 1 Arg 2 Result |
| ===== ===== ====== |
| 0 0 0 |
| 0 1 0 |
| 1 0 0 |
| 1 1 1 |
| ===== ===== ====== |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T))) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 10> | %v0 = and i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 10> | %v1 = and i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Logical Or |
| ---------- |
| |
| The *or* instruction returns the bitwise logical inclusive or of its |
| two operands. |
| |
| **Syntax**:: |
| |
| %vN = or T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 11> |
| |
| **Semantics**: |
| |
| This instruction performs a bitwise logical inclusive or of its arguments. |
| Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` |
| must be an integer, or a vector of integers. ``N`` is defined by the record |
| position, defining the corresponding value generated by the instruction. |
| |
| The truth table used for the *or* instruction is: |
| |
| ===== ===== ====== |
| Arg 1 Arg 2 Result |
| ===== ===== ====== |
| 0 0 0 |
| 0 1 1 |
| 1 0 1 |
| 1 1 1 |
| ===== ===== ====== |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T))) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 11> | %v0 = or i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 11> | %v1 = or i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| Logical Xor |
| ----------- |
| |
| The *xor* instruction returns the bitwise logical exclusive or of its |
| two operands. |
| |
| **Syntax**:: |
| |
| %vN = xor T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 12> |
| |
| **Semantics**: |
| |
| This instruction performs a bitwise logical exclusive or of its arguments. |
| Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type ``T``. ``T`` |
| must be an integer, or a vector of integers. ``N`` is defined by the record |
| position, defining the corresponding value generated by the instruction. |
| |
| The truth table used for the *xor* instruction is: |
| |
| ===== ===== ====== |
| Arg 1 Arg 2 Result |
| ===== ===== ====== |
| 0 0 0 |
| 0 1 1 |
| 1 0 1 |
| 1 1 0 |
| ===== ===== ====== |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| A1 == RelativeIndex(V1) & |
| A2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsInteger(UnderlyingType(T))) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <2, 2, 1, 12> | %v0 = xor i32 %p0, %p1; |
| 110:4| 3: <2, 1, 2, 12> | %v1 = xor i32 %v0, %p1; |
| 114:4| 3: <10, 1> | ret i32 %v1; |
| 117:0| 0: <65534> | } |
| |
| .. _link_for_floating_point_binary_instructions: |
| |
| Floating Point Binary Instructions |
| ================================== |
| |
| Floating point binary instructions require two operands of the same type, |
| execute an operation on them, and produce a value. The value may represent |
| multiple values if the type is a vector type. The result value always has the |
| same type as its operands. |
| |
| Floating Point Add |
| ------------------ |
| |
| The floating point add instruction returns the sum of its two arguments. Both |
| arguments and the result must be of the same type. That type must be a floating |
| point type, or a vector of a floating point type. |
| |
| **Syntax**:: |
| |
| %vN = fadd T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 0> |
| |
| **Semantics**: |
| |
| The floating point add instruction returns the sum of its two arguments. |
| Arguments ``V1`` and ``V2`` and the result ``%vN`` must be of type ``T``. ``T`` |
| must be a floating point type, or a vector of a floating point type. ``N`` is |
| defined by the record position, defining the corresponding value generated by |
| the instruction. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsFloat(UnderlyingType(T)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 92:0| 1: <65535, 12, 2> | function |
| | | float @f0(float %p0, float %p1) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 102:4| 3: <2, 2, 1, 0> | %v0 = fadd float %p0, %p1; |
| 106:4| 3: <2, 3, 1, 0> | %v1 = fadd float %p0, %v0; |
| 110:4| 3: <10, 1> | ret float %v1; |
| 113:0| 0: <65534> | } |
| |
| Floating Point Subtract |
| ----------------------- |
| |
| The floating point subtract instruction returns the difference of its two |
| arguments. Both arguments and the result must be of the same type. That type |
| must be a floating point type, or a vector of a floating point type. |
| |
| **Syntax**:: |
| |
| %vN = fsub T V1, V2; <a> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 1> |
| |
| **Semantics**: |
| |
| The floating point subtract instruction returns the difference of its two |
| arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type |
| ``T``. ``T`` must be a floating point type, or a vector of a floating point |
| type. ``N`` is defined by the record position, defining the corresponding value |
| generated by the instruction. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsFloat(UnderlyingType(T)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 92:0| 1: <65535, 12, 2> | function |
| | | float @f0(float %p0, float %p1) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 102:4| 3: <2, 2, 1, 1> | %v0 = fsub float %p0, %p1; |
| 106:4| 3: <2, 3, 1, 1> | %v1 = fsub float %p0, %v0; |
| 110:4| 3: <10, 1> | ret float %v1; |
| 113:0| 0: <65534> | } |
| |
| Floating Point Multiply |
| ----------------------- |
| |
| The floating point multiply instruction returns the product of its two |
| arguments. Both arguments and the result must be of the same type. That type |
| must be a floating point type, or a vector of a floating point type. |
| |
| **Syntax**:: |
| |
| &vN = fmul T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 2> |
| |
| **Semantics**: |
| |
| The floating point multiply instruction returns the product of its two |
| arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type |
| ``T``. ``T`` must be a floating point type, or a vector of a floating point |
| type. ``N`` is defined by the record position, defining the corresponding value |
| generated by the instruction. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsFloat(UnderlyingType(T)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 92:0| 1: <65535, 12, 2> | function |
| | | float @f0(float %p0, float %p1) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 102:4| 3: <2, 2, 1, 2> | %v0 = fmul float %p0, %p1; |
| 106:4| 3: <2, 3, 1, 2> | %v1 = fmul float %p0, %v0; |
| 110:4| 3: <10, 1> | ret float %v1; |
| 113:0| 0: <65534> | } |
| |
| Floating Point Divide |
| --------------------- |
| |
| The floating point divide instruction returns the quotient of its two |
| arguments. Both arguments and the result must be of the same type. That type |
| must be a floating point type, or a vector of a floating point type. |
| |
| **Syntax**:: |
| |
| %vN = fdiv T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, V1, V2, 4> |
| |
| **Semantics**: |
| |
| The floating point divide instruction returns the quotient of its two |
| arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must be of type |
| ``T``. ``T`` must be a floating point type, or a vector of a floating point |
| type. ``N`` is defined by the record position, defining the corresponding value |
| generated by the instruction. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV22 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsFloat(UnderlyingType(T)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T; |
| |
| **Examples**:: |
| |
| 92:0| 1: <65535, 12, 2> | function |
| | | double |
| | | @f0(double %p0, double %p1) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 102:4| 3: <2, 2, 1, 4> | %v0 = fdiv double %p0, %p1; |
| 106:4| 3: <2, 3, 1, 4> | %v1 = fdiv double %p0, %v0; |
| 110:4| 3: <10, 1> | ret double %v1; |
| 113:0| 0: <65534> | } |
| |
| Floating Point Remainder |
| ------------------------ |
| |
| The floating point remainder instruction returns the remainder of the quotient |
| of its two arguments. Both arguments and the result must be of the same |
| type. That type must be a floating point type, or a vector of a floating point |
| type. |
| |
| **Syntax**:: |
| |
| %vN = frem T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <2, VV1, VV2, 6> |
| |
| **Semantics**: |
| |
| The floating point remainder instruction returns the remainder of the quotient |
| of its two arguments. Arguments ``V1`` and ``V2``, and the result ``%vN`` must |
| be of type ``T``. ``T`` must be a floating point type, or a vector of a floating |
| point type. ``N`` is defined by the record position, defining the corresponding |
| value generated by the instruction. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| IsFloat(UnderlyingType(T)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T |
| |
| **Examples**:: |
| |
| 92:0| 1: <65535, 12, 2> | function |
| | | double |
| | | @f0(double %p0, double %p1) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 102:4| 3: <2, 2, 1, 6> | %v0 = frem double %p0, %p1; |
| 106:4| 3: <2, 3, 1, 6> | %v1 = frem double %p0, %v0; |
| 110:4| 3: <10, 1> | ret double %v1; |
| 113:0| 0: <65534> | } |
| |
| .. _link_for_memory_creation_and_access_instructions: |
| |
| Memory Creation and Access Instructions |
| ======================================= |
| |
| A key design point of SSA-based representation is how it represents |
| memory. In PNaCl bitcode files, no memory locations are in SSA |
| form. This makes things very simple. |
| |
| .. _link_for_alloca_instruction: |
| |
| Alloca Instruction |
| ------------------ |
| |
| The *alloca* instruction allocates memory on the stack frame of the |
| currently executing function. This memory is automatically released |
| when the function returns to its caller. |
| |
| **Syntax**:: |
| |
| %vN = alloca i8, i32 S, align V; <A> |
| |
| **Record**:: |
| |
| AA: <19, SS, VV> |
| |
| **Semantics**: |
| |
| The *alloca* instruction allocates memory on the stack frame of the currently |
| executing function. The resulting value is a pointer to the allocated memory |
| (i.e. of type i32). ``S`` is the number of bytes that are allocated on the |
| stack. ``S`` must be of integer type i32. ``V`` is the alignment of the |
| generated stack address. |
| |
| Alignment must be a power of 2. See :ref:`memory blocks and |
| alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed |
| discussion on how to define alignment. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| VV == Log2(V+1) & |
| SS == RelativeIndex(S) & |
| i32 == TypeOf(S) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = i32; |
| |
| **Examples**:: |
| |
| 112:0| 1: <65535, 12, 2> | function void @f1() { |
| | | // BlockID = 12 |
| 120:0| 3: <1, 1> | blocks 1; |
| 122:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 132:0| 3: <1, 0> | i32: |
| 134:4| 3: <4, 4> | %c0 = i32 2; |
| 137:0| 3: <4, 8> | %c1 = i32 4; |
| 139:4| 3: <4, 16> | %c2 = i32 8; |
| 142:0| 0: <65534> | } |
| | | %b0: |
| 144:0| 3: <19, 3, 1> | %v0 = alloca i8, i32 %c0, align 1; |
| 147:2| 3: <19, 3, 3> | %v1 = alloca i8, i32 %c1, align 4; |
| 150:4| 3: <19, 3, 4> | %v2 = alloca i8, i32 %c2, align 8; |
| 153:6| 3: <10> | ret void; |
| 155:4| 0: <65534> | } |
| |
| Load Instruction |
| ---------------- |
| |
| The *load* instruction is used to read from memory. |
| |
| **Syntax**:: |
| |
| %vN = load T* P, align V; <A> |
| |
| **Record**:: |
| |
| AA: <20, PP, VV, TT> |
| |
| **Semantics**: |
| |
| The load instruction is used to read from memory. ``P`` is the identifier of the |
| memory address to read. The type of ``P`` must be an ``i32``. ``T`` is the type |
| of value to read. ``V`` is the alignment of the memory address. |
| |
| Type ``T`` must be a vector, integer, or floating point type. Both ``float`` and |
| ``double`` types are allowed for floating point types. All integer types except |
| i1 are allowed. |
| |
| Alignment must be a power of 2. See :ref:`memory blocks and |
| alignment<link_for_memory_blocks_and_alignment_section>` for a more detailed |
| discussion on how to define alignment. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| i32 == TypeOf(P) & |
| PP == RelativeIndex(P) & |
| VV == Log2(V+1) & |
| %tTT == TypeID(T) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <2> | @t1 = void; |
| 55:4| 3: <4> | @t2 = double; |
| 57:2| 3: <21, 0, 1, 0> | @t3 = void (i32); |
| 61:2| 0: <65534> | } |
| ... |
| 96:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <20, 1, 1, 0> | %v0 = load i32* %p0, align 1; |
| 110:4| 3: <20, 1, 4, 2> | %v1 = load double* %v0, align 8; |
| 114:4| 3: <10> | ret void; |
| 116:2| 0: <65534> | } |
| |
| Store Instruction |
| ----------------- |
| |
| The *store* instruction is used to write to memory. |
| |
| **Syntax**:: |
| |
| store T S, T* P, align V; <A> |
| |
| **Record**:: |
| |
| AA: <24, PP, SS, VV> |
| |
| **Semantics**: |
| |
| The store instruction is used to write to memory. ``P`` is the identifier of the |
| memory address to write to. The type of ``P`` must be an i32 integer. ``T`` is |
| the type of value to store. ``S`` is the value to store, and must be of type |
| ``T``. ``V`` is the alignment of the memory address. ``A`` is the (optional) |
| abbreviation index associated with the record. |
| |
| Type ``T`` must be an integer or floating point type. Both ``float`` and |
| ``double`` types are allowed for floating point types. All integer types except |
| i1 are allowed. |
| |
| Alignment must be a power of 2. See :ref:`memory blocks and |
| alignment<link_for_memory_Blocks_and_alignment_section>` for a more detailed |
| discussion on how to define alignment. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| i32 == TypeOf(P) & |
| PP == RelativeIndex(P) & |
| VV == Log2(V+1) |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <2> | @t1 = void; |
| 55:4| 3: <4> | @t2 = double; |
| 57:2| 3: <21, 0, 1, 0, 0, 0, 2>| @t3 = void (i32, i32, i32, double); |
| 63:4| 0: <65534> | } |
| ... |
| 96:0| 1: <65535, 12, 2> | function |
| | | void |
| | | @f0(i32 %p0, i32 %p1, i32 %p2, |
| | | double %p3) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 106:4| 3: <24, 4, 3, 1> | store i32 %p1, i32* %p0, align 1; |
| 110:4| 3: <24, 2, 1, 4> | store double %p3, double* %p2, |
| | | align 8; |
| 114:4| 3: <10> | ret void; |
| 116:2| 0: <65534> | } |
| |
| .. _link_for_conversion_instructions: |
| |
| Conversion Instructions |
| ======================= |
| |
| Conversion instructions all take a single operand and a type. The value is |
| converted to the corresponding type. |
| |
| Integer Truncating Instruction |
| ------------------------------ |
| |
| The integer truncating instruction takes a value to truncate, and a type |
| defining the truncated type. Both types must be integer types, or integer |
| vectors with the same number of elements. The bit size of the value must be |
| larger than the bit size of the destination type. Equal sized types are not |
| allowed. |
| |
| **Syntax**:: |
| |
| %vN = trunc T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 0> |
| |
| **Semantics**: |
| |
| The integer truncating instruction takes a value ``V``, and truncates to type |
| ``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with |
| the same number of elements. ``T1`` has to be wider than ``T2``. If the value |
| doesn't fit in in ``T2``, then the higher order bits are dropped. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 == TypeID(T2) & |
| BitSizeOf(UnderlyingType(T1)) > BitSizeOf(UnderlyingType(T2)) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsInteger(UnderlyingType(T1)) & |
| IsInteger(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 5> | count 5; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <2> | @t1 = void; |
| 55:4| 3: <7, 16> | @t2 = i16; |
| 58:0| 3: <21, 0, 1, 0> | @t3 = void (i32); |
| 62:0| 3: <7, 8> | @t4 = i8; |
| 64:4| 0: <65534> | } |
| ... |
| 100:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { |
| | | // BlockID = 12 |
| 108:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 110:4| 3: <3, 1, 2, 0> | %v0 = trunc i32 %p0 to i16; |
| 114:4| 3: <3, 1, 4, 0> | %v1 = trunc i16 %v0 to i8; |
| 118:4| 3: <10> | ret void; |
| 120:2| 0: <65534> | } |
| |
| Floating Point Truncating Instruction |
| -------------------------------------- |
| |
| The floating point truncating instruction takes a value to truncate, and a type |
| defining the truncated type. Both types must be floating point types, or |
| floating point vectors with the same number of elements. The source must be |
| ``double`` while the destination is ``float``. If the source is a vector, the |
| destination must also be vector with the same size as the source. |
| |
| **Syntax**:: |
| |
| %vN = fptrunc T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 7> |
| |
| **Semantics** |
| |
| The floating point truncating instruction takes a value ``V``, and truncates to |
| type ``T2``. Both ``T1`` and ``T2`` must be floating point types, or floating |
| point vectors with the same number of elements. ``T1`` must be defined on |
| ``double`` while ``T2`` is defined on ``float``. If the value can't fit within |
| the destination type ``T2``, the results are undefined. |
| |
| **Constraints**:: |
| |
| TypeOf(V) == T1 & |
| double == UnderlyingType(T1) & |
| float == UnderlyingType(T2) & |
| VV == RelativeIndex(V) & |
| %tTT2 == TypeID(T2) & |
| BitSizeOf(UnderlyingType(T1)) > BitSizeOf(UnderlyingType(T2)) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsFloat(UnderlyingType(T1)) & |
| IsFloat(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <3> | @t0 = float; |
| 52:2| 3: <4> | @t1 = double; |
| 54:0| 3: <21, 0, 0, 1> | @t2 = float (double); |
| 58:0| 3: <2> | @t3 = void; |
| 59:6| 0: <65534> | } |
| ... |
| 92:0| 1: <65535, 12, 2> | function float @f0(double %p0) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 102:4| 3: <3, 1, 0, 7> | %v0 = fptrunc double %p0 to float; |
| 106:4| 3: <10, 1> | ret float %v0; |
| 109:0| 0: <65534> | } |
| |
| |
| Zero Extending Instruction |
| -------------------------- |
| |
| The zero extending instruction takes a value to extend, and a type to extend it |
| to. Both types must be integer types, or integer vectors with the same number |
| of elements. The bit size of the source type must be smaller than the bit size |
| of the destination type. Equal sized types are not allowed. |
| |
| **Syntax**:: |
| |
| %vN = zext T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 1> |
| |
| |
| **Semantics**: |
| |
| The zero extending instruction takes a value ``V``, and expands it to type |
| ``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with |
| the same number of elements. ``T2`` must be wider than ``T1``. |
| |
| The instruction fills the high order bits of the value with zero bits until it |
| reaches the size of the destination type. When zero extending from i1, the |
| result will always be either 0 or 1. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 == TypeID(T2) & |
| BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsInteger(UnderlyingType(T1)) & |
| IsInteger(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 5> | count 5; |
| 50:4| 3: <7, 64> | @t0 = i64; |
| 53:6| 3: <7, 32> | @t1 = i32; |
| 57:0| 3: <21, 0, 0> | @t2 = i64 (); |
| 60:2| 3: <7, 8> | @t3 = i8; |
| 62:6| 3: <2> | @t4 = void; |
| 64:4| 0: <65534> | } |
| ... |
| 100:0| 1: <65535, 12, 2> | function i64 @f0() { // BlockID = 12 |
| 108:0| 3: <1, 1> | blocks 1; |
| 110:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 120:0| 3: <1, 3> | i8: |
| 122:4| 3: <4, 2> | %c0 = i8 1; |
| 125:0| 0: <65534> | } |
| | | %b0: |
| 128:0| 3: <3, 1, 1, 1> | %v0 = zext i8 %c0 to i32; |
| 132:0| 3: <3, 1, 0, 1> | %v1 = zext i32 %v0 to i64; |
| 136:0| 3: <10, 1> | ret i64 %v1; |
| 138:4| 0: <65534> | } |
| |
| Sign Extending Instruction |
| -------------------------- |
| |
| The sign extending instruction takes a value to cast, and a type to extend it |
| to. Both types must be integer types, or integral vectors with the same number |
| of elements. The bit size of the source type must be smaller than the bit size |
| of the destination type. Equal sized types are not allowed. |
| |
| **Syntax**:: |
| |
| %vN = sext T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 2> |
| |
| **Semantics**: |
| |
| The sign extending instruction takes a value ``V``, and expands it to type |
| ``T2``. Both ``T1`` and ``T2`` must be integer types, or integer vectors with |
| the same number of integers. ``T2`` has to be wider than ``T1``. |
| |
| When sign extending, the instruction fills the high order bits of the value with |
| the (current) high order bit of the value. When sign extending from i1, the |
| extension always results in -1 or 0. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 == TypeID(T2) & |
| BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsInteger(UnderlyingType(T1)) & |
| IsInteger(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 5> | count 5; |
| 50:4| 3: <7, 64> | @t0 = i64; |
| 53:6| 3: <7, 32> | @t1 = i32; |
| 57:0| 3: <21, 0, 0> | @t2 = i64 (); |
| 60:2| 3: <7, 8> | @t3 = i8; |
| 62:6| 3: <2> | @t4 = void; |
| 64:4| 0: <65534> | } |
| ... |
| 100:0| 1: <65535, 12, 2> | function i64 @f0() { // BlockID = 12 |
| 108:0| 3: <1, 1> | blocks 1; |
| 110:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 120:0| 3: <1, 3> | i8: |
| 122:4| 3: <4, 3> | %c0 = i8 -1; |
| 125:0| 0: <65534> | } |
| | | %b0: |
| 128:0| 3: <3, 1, 1, 2> | %v0 = sext i8 %c0 to i32; |
| 132:0| 3: <3, 1, 0, 2> | %v1 = sext i32 %v0 to i64; |
| 136:0| 3: <10, 1> | ret i64 %v1; |
| 138:4| 0: <65534> | } |
| |
| Floating Point Extending Instruction |
| ------------------------------------ |
| |
| The floating point extending instruction takes a value to extend, and a type to |
| extend it to. Both types must either be floating point types, or vectors of |
| floating point types with the same number of elements. The source value must be |
| ``float`` while the destination is ``double``. If the source is a vector, the |
| destination must also be vector with the same size as the source. |
| |
| **Syntax**:: |
| |
| %vN = fpext T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 8> |
| |
| **Semantics**: |
| |
| The floating point extending instruction converts floating point values. |
| ``V`` is the value to extend, and ``T2`` is the type to extend it |
| to. Both ``T1`` and ``T2`` must be floating point types, or floating point |
| vector types with the same number of floating point values. ``T1`` contains |
| ``float`` while ``T2`` contains ``double``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 == TypeID(T2) & |
| BitSizeOf(UnderlyingType(T1)) < BitSizeOf(UnderlyingType(T2)) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsFloat(UnderlyingType(T1)) & |
| IsFloat(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <4> | @t0 = double; |
| 52:2| 3: <3> | @t1 = float; |
| 54:0| 3: <21, 0, 0, 1> | @t2 = double (float); |
| 58:0| 3: <2> | @t3 = void; |
| 59:6| 0: <65534> | } |
| ... |
| 92:0| 1: <65535, 12, 2> | function double @f0(float %p0) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 102:4| 3: <3, 1, 0, 8> | %v0 = fpext float %p0 to double; |
| 106:4| 3: <10, 1> | ret double %v0; |
| 109:0| 0: <65534> | } |
| |
| Floating Point to Unsigned Integer Instruction |
| ---------------------------------------------- |
| |
| The floating point to unsigned integer instruction converts floating point |
| values to unsigned integers. |
| |
| **Syntax**:: |
| |
| %vN = fptoui T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 3> |
| |
| **Semantics**: |
| |
| The floating point to unsigned integer instruction converts floating point |
| value(s) in ``V`` to its unsigned integer equivalent of type ``T2``. ``T1`` must |
| be a floating point type, or a floating point vector type. ``T2`` must be an |
| integer type, or an integer vector type. If either type is a vector type, they |
| both must have the same number of elements. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 == TypeID(T2) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsFloat(UnderlyingType(T1)) & |
| IsInteger(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 6> | count 6; |
| 50:4| 3: <3> | @t0 = float; |
| 52:2| 3: <4> | @t1 = double; |
| 54:0| 3: <2> | @t2 = void; |
| 55:6| 3: <21, 0, 2, 0, 1> | @t3 = void (float, double); |
| 60:4| 3: <7, 32> | @t4 = i32; |
| 63:6| 3: <7, 16> | @t5 = i16; |
| 66:2| 0: <65534> | } |
| ... |
| 100:0| 1: <65535, 12, 2> | function |
| | | void @f0(float %p0, double %p1) { |
| | | // BlockID = 12 |
| 108:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 110:4| 3: <3, 2, 4, 3> | %v0 = fptoui float %p0 to i32; |
| 114:4| 3: <3, 2, 5, 3> | %v1 = fptoui double %p1 to i16; |
| 118:4| 3: <10> | ret void; |
| 120:2| 0: <65534> | } |
| |
| Floating Point to Signed Integer Instruction |
| -------------------------------------------- |
| |
| The floating point to signed integer instruction converts floating point |
| values to signed integers. |
| |
| **Syntax**:: |
| |
| %vN = fptosi T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 4> |
| |
| **Semantics**: |
| |
| The floating point to signed integer instruction converts floating point |
| value(s) in ``V`` to its signed integer equivalent of type ``T2``. ``T1`` must |
| be a floating point type, or a floating point vector type. ``T2`` must be an |
| integer type, or an integer vector type. If either type is a vector type, they |
| both must have the same number of elements. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 = TypeID(T2) & |
| UnderlyingCount(T1) = UnderlyingCount(T2) & |
| IsFloat(UnderlyingType(T1)) & |
| IsInteger(UnderlyingType(T2)) & |
| N = NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 6> | count 6; |
| 50:4| 3: <3> | @t0 = float; |
| 52:2| 3: <4> | @t1 = double; |
| 54:0| 3: <2> | @t2 = void; |
| 55:6| 3: <21, 0, 2, 0, 1> | @t3 = void (float, double); |
| 60:4| 3: <7, 8> | @t4 = i8; |
| 63:0| 3: <7, 16> | @t5 = i16; |
| 65:4| 0: <65534> | } |
| ... |
| 100:0| 1: <65535, 12, 2> | function |
| | | void @f0(float %p0, double %p1) { |
| | | // BlockID = 12 |
| 108:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 110:4| 3: <3, 2, 4, 4> | %v0 = fptosi float %p0 to i8; |
| 114:4| 3: <3, 2, 5, 4> | %v1 = fptosi double %p1 to i16; |
| 118:4| 3: <10> | ret void; |
| 120:2| 0: <65534> | } |
| |
| Unsigned Integer to Floating Point Instruction |
| ---------------------------------------------- |
| |
| The unsigned integer to floating point instruction converts unsigned integers to |
| floating point values. |
| |
| **Syntax**:: |
| |
| %vN = uitofp T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 5> |
| |
| **Semantics**: |
| |
| The unsigned integer to floating point instruction converts unsigned integer(s) |
| to its floating point equivalent of type ``T2``. ``T1`` must be an integer type, |
| or a integer vector type. ``T2`` must be a floating point type, or a floating |
| point vector type. If either type is a vector type, they both must have the same |
| number of elements. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 = TypeID(T2) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsInteger(UnderlyingType(T1)) & |
| IsFloat(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) == T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 7> | count 7; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <7, 64> | @t1 = i64; |
| 57:0| 3: <2> | @t2 = void; |
| 58:6| 3: <3> | @t3 = float; |
| 60:4| 3: <21, 0, 2, 0, 1> | @t4 = void (i32, i64); |
| 65:2| 3: <7, 1> | @t5 = i1; |
| 67:6| 3: <4> | @t6 = double; |
| 69:4| 0: <65534> | } |
| ... |
| 104:0| 1: <65535, 12, 2> | function void @f0(i32 %p0, i64 %p1) { |
| | | // BlockID = 12 |
| 112:0| 3: <1, 1> | blocks 1; |
| 114:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 124:0| 3: <1, 5> | i1: |
| 126:4| 3: <4, 3> | %c0 = i1 1; |
| 129:0| 0: <65534> | } |
| | | %b0: |
| 132:0| 3: <3, 1, 6, 5> | %v0 = uitofp i1 %c0 to double; |
| 136:0| 3: <3, 4, 3, 5> | %v1 = uitofp i32 %p0 to float; |
| 140:0| 3: <3, 4, 3, 5> | %v2 = uitofp i64 %p1 to float; |
| 144:0| 3: <10> | ret void; |
| 145:6| 0: <65534> | } |
| |
| Signed Integer to Floating Point Instruction |
| -------------------------------------------- |
| |
| The signed integer to floating point instruction converts signed integers to |
| floating point values. |
| |
| **Syntax**:: |
| |
| %vN = sitofp T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 6> |
| |
| **Semantics**: |
| |
| The signed integer to floating point instruction converts signed integer(s) to |
| its floating point equivalent of type ``T2``. ``T1`` must be an integer type, or |
| a integer vector type. ``T2`` must be a floating point type, or a floating point |
| vector type. If either type is a vector type, they both must have the same |
| number of elements. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV == RelativeIndex(V) & |
| %tTT2 = TypeID(T2) & |
| UnderlyingCount(T1) == UnderlyingCount(T2) & |
| IsInteger(UnderlyingType(T1)) & |
| IsFloat(UnderlyingType(T2)) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 7> | count 7; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <7, 64> | @t1 = i64; |
| 57:0| 3: <2> | @t2 = void; |
| 58:6| 3: <3> | @t3 = float; |
| 60:4| 3: <21, 0, 2, 0, 1> | @t4 = void (i32, i64); |
| 65:2| 3: <7, 8> | @t5 = i8; |
| 67:6| 3: <4> | @t6 = double; |
| 69:4| 0: <65534> | } |
| ... |
| 104:0| 1: <65535, 12, 2> | function void @f0(i32 %p0, i64 %p1) { |
| | | // BlockID = 12 |
| 112:0| 3: <1, 1> | blocks 1; |
| 114:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 124:0| 3: <1, 5> | i8: |
| 126:4| 3: <4, 3> | %c0 = i8 -1; |
| 129:0| 0: <65534> | } |
| | | %b0: |
| 132:0| 3: <3, 1, 6, 6> | %v0 = sitofp i8 %c0 to double; |
| 136:0| 3: <3, 4, 3, 6> | %v1 = sitofp i32 %p0 to float; |
| 140:0| 3: <3, 4, 3, 6> | %v2 = sitofp i64 %p1 to float; |
| 144:0| 3: <10> | ret void; |
| 145:6| 0: <65534> | } |
| |
| Bitcast Instruction |
| ------------------- |
| |
| The bitcast instruction converts the type of the value without changing the bit |
| contents of the value. The bit size of the type of the value must be the same as |
| the bit size of the cast type. |
| |
| **Syntax**:: |
| |
| %vN = bitcast T1 V to T2; <A> |
| |
| **Record**:: |
| |
| AA: <3, VV, TT2, 11> |
| |
| **Semantics**: |
| |
| The bitcast instruction converts the type of value ``V`` to type ``T2``. ``T1`` |
| and ``T2`` must be primitive types or vectors, and define the same number of |
| bits. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| TypeOf(V) == T1 & |
| VV = RelativeIndex(V) & |
| %tTT2 = TypeID(T2) & |
| BitSizeOf(T1) == BitSizeOf(T2) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T2; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 6> | count 6; |
| 50:4| 3: <3> | @t0 = float; |
| 52:2| 3: <7, 64> | @t1 = i64; |
| 55:4| 3: <2> | @t2 = void; |
| 57:2| 3: <21, 0, 2, 0, 1> | @t3 = void (float, i64); |
| 62:0| 3: <7, 32> | @t4 = i32; |
| 65:2| 3: <4> | @t5 = double; |
| 67:0| 0: <65534> | } |
| ... |
| 100:0| 1: <65535, 12, 2> | function void @f0(float %p0, i64 %p1) |
| | | { // BlockID = 12 |
| 108:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 110:4| 3: <3, 2, 4, 11> | %v0 = bitcast float %p0 to i32; |
| 114:4| 3: <3, 2, 5, 11> | %v1 = bitcast i64 %p1 to double; |
| 118:4| 3: <10> | ret void; |
| 120:2| 0: <65534> | } |
| |
| .. _link_for_compare_instructions: |
| |
| Comparison Instructions |
| ======================= |
| |
| The comparison instructions compare values and generates a boolean (i1) result |
| for each pair of compared values. There are different comparison operations for |
| integer and floating point values. |
| |
| |
| Integer Comparison Instructions |
| ------------------------------- |
| |
| The integer comparison instruction compares integer values and returns a |
| boolean (i1) result for each pair of compared values. |
| |
| **Syntax**:: |
| |
| %vN = icmp C T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <9, VV1, VV2, CC> |
| |
| **Semantics**: |
| |
| The integer comparison instruction compares integer values and returns a boolean |
| (i1) result for each pair of compared values in ``V1`` and ``V2``. ``V1`` and |
| ``V2`` must be of type ``T``. ``T`` must be an integer type, or an integer |
| vector type. Condition code ``C`` is the condition applied to all elements in |
| ``V1`` and ``V2``. Each comparison always yields an i1. If ``T`` is a primitive |
| type, the resulting type is i1. If ``T`` is a vector, then the resulting type is |
| a vector of i1 with the same size as ``T``. |
| |
| Legal test conditions are: |
| |
| === == ============================== |
| C CC Operator |
| === == ============================== |
| eq 32 equal |
| ne 33 not equal |
| ugt 34 unsigned greater than |
| uge 35 unsigned greater than or equal |
| ult 36 unsigned less than |
| ule 37 unsigned less than or equal |
| sgt 38 signed greater than |
| sge 39 signed greater than or equal |
| slt 40 signed less than |
| sle 41 signed less than or equal |
| === == ============================== |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| IsInteger(UnderlyingType(T) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| if IsVector(T) then |
| TypeOf(%vN) = <UnderlyingCount(T), i1> |
| else |
| TypeOf(%vN) = i1 |
| endif |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <7, 1> | @t1 = i1; |
| 56:2| 3: <2> | @t2 = void; |
| 58:0| 3: <21, 0, 2> | @t3 = void (); |
| 61:2| 0: <65534> | } |
| ... |
| 108:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 116:0| 3: <1, 1> | blocks 1; |
| 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 128:0| 3: <1, 0> | i32: |
| 130:4| 3: <4, 0> | %c0 = i32 0; |
| 133:0| 3: <4, 2> | %c1 = i32 1; |
| 135:4| 0: <65534> | } |
| | | %b0: |
| 136:0| 3: <28, 2, 1, 32> | %v0 = icmp eq i32 %c0, %c1; |
| 140:6| 3: <28, 3, 2, 33> | %v1 = icmp ne i32 %c0, %c1; |
| 145:4| 3: <28, 4, 3, 34> | %v2 = icmp ugt i32 %c0, %c1; |
| 150:2| 3: <28, 5, 4, 36> | %v3 = icmp ult i32 %c0, %c1; |
| 155:0| 3: <28, 6, 5, 37> | %v4 = icmp ule i32 %c0, %c1; |
| 159:6| 3: <28, 7, 6, 38> | %v5 = icmp sgt i32 %c0, %c1; |
| 164:4| 3: <28, 8, 7, 38> | %v6 = icmp sgt i32 %c0, %c1; |
| 169:2| 3: <28, 9, 8, 39> | %v7 = icmp sge i32 %c0, %c1; |
| 174:0| 3: <28, 10, 9, 40> | %v8 = icmp slt i32 %c0, %c1; |
| 178:6| 3: <28, 11, 10, 41> | %v9 = icmp sle i32 %c0, %c1; |
| 183:4| 3: <10> | ret void; |
| 185:2| 0: <65534> | } |
| |
| |
| Floating Point Comparison Instructions |
| -------------------------------------- |
| |
| The floating point comparison instruction compares floating point values and |
| returns a boolean (i1) result for each pair of compared values. |
| |
| **Syntax**:: |
| |
| %vN = fcmp C T V1, V2; <A> |
| |
| **Record**:: |
| |
| AA: <9, VV1, VV2, CC> |
| |
| **Semantics**: |
| |
| The floating point comparison instruction compares floating point values and |
| returns a boolean (i1) result for each pair of compared values in ``V1`` and |
| ``V2``. ``V1`` and ``V2`` must be of type ``T``. ``T`` must be a floating point |
| type, or a floating point vector type. Condition code ``C`` is the condition |
| applied to all elements in ``V1`` and ``V2``. Each comparison always yields an |
| i1. If ``T`` is a primitive type, the resulting type is i1. If ``T`` is a |
| vector, then the resulting type is a vector of i1 with the same size as ``T``. |
| |
| Legal test conditions are: |
| |
| ===== == ================================== |
| C CC Operator |
| ===== == ================================== |
| false 0 Always false |
| oeq 1 Ordered and equal |
| ogt 2 Ordered and greater than |
| oge 3 Ordered and greater than or equal |
| olt 4 Ordered and less than |
| ole 5 Ordered and less than or equal |
| one 6 Ordered and not equal |
| ord 7 Ordered (no NaNs) |
| uno 8 Unordered (either NaNs) |
| ueq 9 Unordered or equal |
| ugt 10 Unordered or greater than |
| uge 11 Unordered or greater than or equal |
| ult 12 Unordered or less than |
| ule 13 Unordered or less than or equal |
| une 14 Unordered or not equal |
| true 15 Always true |
| ===== == ================================== |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| IsFloat(UnderlyingType(T) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| if IsVector(T) then |
| TypeOf(%vN) = <UnderlyingCount(T), i1> |
| else |
| TypeOf(%vN) = i1 |
| endif |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <3> | @t0 = float; |
| 52:2| 3: <7, 1> | @t1 = i1; |
| 54:6| 3: <2> | @t2 = void; |
| 56:4| 3: <21, 0, 2> | @t3 = void (); |
| 59:6| 0: <65534> | } |
| ... |
| 108:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 116:0| 3: <1, 1> | blocks 1; |
| 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 128:0| 3: <1, 0> | float: |
| 130:4| 3: <6, 0> | %c0 = float 0; |
| 133:0| 3: <6, 1065353216> | %c1 = float 1; |
| 139:2| 0: <65534> | } |
| | | %b0: |
| 140:0| 3: <28, 2, 1, 0> | %v0 = fcmp false float %c0, %c1; |
| 144:0| 3: <28, 3, 2, 1> | %v1 = fcmp oeq float %c0, %c1; |
| 148:0| 3: <28, 4, 3, 2> | %v2 = fcmp ogt float %c0, %c1; |
| 152:0| 3: <28, 5, 4, 3> | %v3 = fcmp oge float %c0, %c1; |
| 156:0| 3: <28, 6, 5, 4> | %v4 = fcmp olt float %c0, %c1; |
| 160:0| 3: <28, 7, 6, 5> | %v5 = fcmp ole float %c0, %c1; |
| 164:0| 3: <28, 8, 7, 6> | %v6 = fcmp one float %c0, %c1; |
| 168:0| 3: <28, 9, 8, 7> | %v7 = fcmp ord float %c0, %c1; |
| 172:0| 3: <28, 10, 9, 9> | %v8 = fcmp ueq float %c0, %c1; |
| 176:0| 3: <28, 11, 10, 10> | %v9 = fcmp ugt float %c0, %c1; |
| 180:0| 3: <28, 12, 11, 11> | %v10 = fcmp uge float %c0, %c1; |
| 184:0| 3: <28, 13, 12, 12> | %v11 = fcmp ult float %c0, %c1; |
| 188:0| 3: <28, 14, 13, 13> | %v12 = fcmp ule float %c0, %c1; |
| 192:0| 3: <28, 15, 14, 14> | %v13 = fcmp une float %c0, %c1; |
| 196:0| 3: <28, 16, 15, 8> | %v14 = fcmp uno float %c0, %c1; |
| 200:0| 3: <28, 17, 16, 15> | %v15 = fcmp true float %c0, %c1; |
| 204:0| 3: <10> | ret void; |
| 205:6| 0: <65534> | } |
| 208:0|0: <65534> |} |
| |
| .. _link_for_vector_instructions: |
| |
| Vector Instructions |
| =================== |
| |
| PNaClAsm supports several instructions that process vectors. This includes the |
| :ref:`integer<link_for_integer_binary_instructions>` and :ref:`floating |
| point<link_for_floating_point_binary_instructions>` binary instructions as well |
| as :ref:`compare<link_for_compare_instructions>` instructions. These |
| instructions work with vectors and generate resulting (new) vectors. This |
| section introduces the instructions to construct vectors and extract results. |
| |
| .. _link_for_insert_element_instruction_section: |
| |
| Insert Element Instruction |
| -------------------------- |
| |
| The *insert element* instruction inserts a scalar value into a vector at a |
| specified index. The *insert element* instruction takes an existing vector and |
| puts a scalar value in one of the elements of the vector. |
| |
| The *insert element* instruction can be used to construct a vector, one element |
| at a time. At first glance, it may appear that one can't construct a vector, |
| since the *insert element* instruction needs a vector to insert elements into. |
| |
| The key to understanding vector construction is understand that one can create |
| an :ref:`undefined<link_for_undefined_literal>` vector literal. Using that |
| constant as a starting point, one can built up the wanted vector by a sequence |
| of *insert element* instructions. |
| |
| **Syntax**:: |
| |
| %vN = insertelement TV V, TE E, i32 I; <A> |
| |
| **Record**:: |
| |
| AA: <7, VV, EE, II> |
| |
| **Semantics**: |
| |
| The *insert element* instruction inserts scalar value ``E`` into index ``I`` of |
| vector ``V``. ``%vN`` holds the updated vector. Type ``TV`` is the type of |
| vector. It is also the type of updated vector ``%vN``. Type ``TE`` is the type |
| of scalar value ``E`` and must be the element type of vector ``V``. ``I`` must |
| be an :ref:`i32 literal<link_for_integer_literal>`. |
| |
| If ``I`` exceeds the length of ``V``, the result is undefined. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| IsVector(TV) & |
| TypeOf(V) == TV & |
| UnderlyingType(TV) == TE & |
| TypeOf(I) == i32 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = TV; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 5> | count 5; |
| 50:4| 3: <7, 1> | @t0 = i1; |
| 53:0| 3: <12, 4, 0> | @t1 = <4 x i1>; |
| 56:2| 3: <7, 32> | @t2 = i32; |
| 59:4| 3: <2> | @t3 = void; |
| 61:2| 3: <21, 0, 3> | @t4 = void (); |
| 64:4| 0: <65534> | } |
| ... |
| 116:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 124:0| 3: <1, 1> | blocks 1; |
| 126:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 136:0| 3: <1, 0> | i1: |
| 138:4| 3: <4, 0> | %c0 = i1 0; |
| 141:0| 3: <4, 3> | %c1 = i1 1; |
| 143:4| 3: <1, 1> | <4 x i1>: |
| 146:0| 3: <3> | %c2 = <4 x i1> undef; |
| 147:6| 3: <1, 2> | i32: |
| 150:2| 3: <4, 0> | %c3 = i32 0; |
| 152:6| 3: <4, 2> | %c4 = i32 1; |
| 155:2| 3: <4, 4> | %c5 = i32 2; |
| 157:6| 3: <4, 6> | %c6 = i32 3; |
| 160:2| 0: <65534> | } |
| | | %b0: |
| 164:0| 3: <7, 5, 7, 4> | %v0 = insertelement <4 x i1> %c2, |
| | | i1 %c0, i32 %c3; |
| 168:0| 3: <7, 1, 7, 4> | %v1 = insertelement <4 x i1> %v0, |
| | | i1 %c1, i32 %c4; |
| 172:0| 3: <7, 1, 9, 4> | %v2 = insertelement <4 x i1> %v1, |
| | | i1 %c0, i32 %c5; |
| 176:0| 3: <7, 1, 9, 4> | %v3 = insertelement <4 x i1> %v2, |
| | | i1 %c1, i32 %c6; |
| 180:0| 3: <10> | ret void; |
| 181:6| 0: <65534> | } |
| |
| Extract Element Instruction |
| --------------------------- |
| |
| The *extract element* instruction extracts a single scalar value from a vector |
| at a specified index. |
| |
| **Syntax**:: |
| |
| %vN = extractelement TV V, i32 I; <A> |
| |
| **Record**:: |
| |
| AA: <6, VV, II> |
| |
| **Semantics**: |
| |
| The *extract element* instruction extracts the scalar value at index ``I`` from |
| vector ``V``. The extracted value is assigned to ``%vN``. Type ``TV`` is the |
| type of vector ``V``. ``I`` must be an :ref:`i32 |
| literal<link_for_integer_literal>`. The type of ``vN`` must be the element type |
| of vector ``V``. |
| |
| If ``I`` exceeds the length of ``V``, the result is undefined. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| IsVector(TV) & |
| TypeOf(V) == TV & |
| TypeOf(I) == i32 & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = UnderlyingType(TV); |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function void @f0(<4 x i32> %p0) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 116:0| 3: <1, 0> | i32: |
| 118:4| 3: <4, 0> | %c0 = i32 0; |
| 121:0| 0: <65534> | } |
| | | %b0: |
| 124:0| 3: <6, 2, 1> | %v0 = |
| | | extractelement <4 x i32> %p0, |
| | | i32 %c0; |
| 127:2| 3: <10> | ret void; |
| 129:0| 0: <65534> | } |
| |
| .. _link_for_other_pnaclasm_instructions: |
| |
| Other Instructions |
| ================== |
| |
| This section defines miscellaneous instructions which defy better |
| classification. |
| |
| .. _link_for_forward_type_declaration_section: |
| |
| Forward Type Declaration |
| ------------------------ |
| |
| The forward type declaration exists to deal with the fact that all instruction |
| values must have a type associated with them before they are used. For some |
| simple functions one can easily topologically sort instructions so that |
| instruction values are defined before they are used. However, if the |
| implementation contains loops, the loop induced values can't be defined before |
| they are used. |
| |
| The solution is to forward declare the type of an instruction value. One could |
| forward declare the types of all instructions at the beginning of the function |
| block. However, this would make the corresponding file size considerably |
| larger. Rather, one should only generate these forward type declarations |
| sparingly and only when needed. |
| |
| **Syntax**:: |
| |
| declare T %vN; <A> |
| |
| **Record**:: |
| |
| AA: <43, N, TT> |
| |
| **Semantics**: |
| |
| The forward declare type declaration defines the type to be associated with a |
| (not yet defined) instruction value ``%vN``. ``T`` is the type of the value |
| generated by the ``Nth`` value generating instruction in the function block. |
| |
| Note: It is an error to define the type of ``%vN`` with a different type than |
| will be generated by the ``Nth`` value generating instruction in the function |
| block. |
| |
| Also note that this construct is a declaration and not considered an |
| instruction, even though it appears in the list of instruction records. Hence, |
| they may appear before and between :ref:`phi<link_for_phi_instruction_section>` |
| instructions in a basic block. |
| |
| **Constraints**:: |
| |
| AA = AbbrevIndex(A) & |
| TT = TypeID(T) |
| |
| **Updates**:: |
| |
| TypeOf(%vN) = T; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <2> | @t1 = void; |
| 55:4| 3: <7, 1> | @t2 = i1; |
| 58:0| 3: <21, 0, 1, 0> | @t3 = void (i32); |
| 62:0| 0: <65534> | } |
| ... |
| 108:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { |
| | | // BlockID = 12 |
| 116:0| 3: <1, 7> | blocks 7; |
| 118:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 128:0| 3: <1, 2> | i1: |
| 130:4| 3: <4, 3> | %c0 = i1 1; |
| 133:0| 0: <65534> | } |
| | | %b0: |
| 136:0| 3: <11, 4> | br label %b4; |
| | | %b1: |
| 138:4| 3: <43, 6, 0> | declare i32 %v3; |
| 142:4| 3: <2, 2, 4294967293, 0> | %v0 = add i32 %p0, %v3; |
| 151:0| 3: <11, 6> | br label %b6; |
| | | %b2: |
| 153:4| 3: <43, 7, 0> | declare i32 %v4; |
| 157:4| 3: <2, 3, 4294967293, 0> | %v1 = add i32 %p0, %v4; |
| 166:0| 3: <11, 6> | br label %b6; |
| | | %b3: |
| 168:4| 3: <2, 4, 4294967295, 0> | %v2 = add i32 %p0, %v3; |
| 177:0| 3: <11, 6> | br label %b6; |
| | | %b4: |
| 179:4| 3: <2, 5, 5, 0> | %v3 = add i32 %p0, %p0; |
| 183:4| 3: <11, 1, 5, 5> | br i1 %c0, label %b1, label %b5; |
| | | %b5: |
| 187:4| 3: <2, 1, 6, 0> | %v4 = add i32 %v3, %p0; |
| 191:4| 3: <11, 2, 3, 6> | br i1 %c0, label %b2, label %b3; |
| | | %b6: |
| 195:4| 3: <10> | ret void; |
| 197:2| 0: <65534> | } |
| |
| .. _link_for_phi_instruction_section: |
| |
| Phi Instruction |
| --------------- |
| |
| The *phi* instruction is used to implement phi nodes in the SSA graph |
| representing the function. Phi instructions can only appear at the beginning of |
| a basic block. There must be no non-phi instructions (other than forward type |
| declarations) between the start of the basic block and the *phi* instruction. |
| |
| To clarify the origin of each incoming value, the incoming value is associated |
| with the incoming edge from the corresponding predecessor block that the |
| incoming value comes from. |
| |
| **Syntax**:: |
| |
| %vN = phi T [V1, %bB1], ... , [VM, %bBM]; <A> |
| |
| **Record**:: |
| |
| AA: <16, TT, VV1, B1, ..., VVM, BM> |
| |
| **Semantics**: |
| |
| The phi instruction is used to implement phi nodes in the SSA graph representing |
| the function. ``%vN`` is the resulting value of the corresponding phi |
| node. ``T`` is the type of the phi node. Values ``V1`` through ``VM`` are the |
| reaching definitions for the phi node while ``%bB1`` through ``%bBM`` are the |
| corresponding predecessor blocks. Each ``VI`` reaches via the incoming |
| predecessor edge from block ``%bBI`` (for 1 <= I <= M). Type ``T`` must be the |
| type associated with each ``VI``. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| M > 1 & |
| TT == TypeID(T) & |
| T = TypeOf(VI) for all I, 1 <= I <= M & |
| BI < ExpectedBasicBlocks for all I, 1 <= I <= M & |
| VVI = SignRotate(RelativeIndex(VI)) for all I, 1 <= I <= M & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 4> | count 4; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <2> | @t1 = void; |
| 55:4| 3: <21, 0, 1> | @t2 = void (); |
| 58:6| 3: <7, 1> | @t3 = i1; |
| 61:2| 0: <65534> | } |
| ... |
| 112:0| 1: <65535, 12, 2> | function void @f0() { |
| | | // BlockID = 12 |
| 120:0| 3: <1, 4> | blocks 4; |
| 122:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 132:0| 3: <1, 0> | i32: |
| 134:4| 3: <4, 2> | %c0 = i32 1; |
| 137:0| 3: <1, 3> | i1: |
| 139:4| 3: <4, 0> | %c1 = i1 0; |
| 142:0| 0: <65534> | } |
| | | %b0: |
| 144:0| 3: <11, 1, 2, 1> | br i1 %c1, label %b1, label %b2; |
| | | %b1: |
| 148:0| 3: <2, 2, 2, 0> | %v0 = add i32 %c0, %c0; |
| 152:0| 3: <2, 3, 3, 1> | %v1 = sub i32 %c0, %c0; |
| 156:0| 3: <11, 3> | br label %b3; |
| | | %b2: |
| 158:4| 3: <2, 4, 4, 2> | %v2 = mul i32 %c0, %c0; |
| 162:4| 3: <2, 5, 5, 3> | %v3 = udiv i32 %c0, %c0; |
| 166:4| 3: <11, 3> | br label %b3; |
| | | %b3: |
| 169:0| 3: <16, 0, 8, 1, 4, 2> | %v4 = phi i32 [%v0, %b1], |
| | | [%v2, %b2]; |
| 174:4| 3: <16, 0, 8, 1, 4, 2> | %v5 = phi i32 [%v1, %b1], |
| | | [%v3, %b2]; |
| 180:0| 3: <10> | ret void; |
| 181:6| 0: <65534> | } |
| |
| Select Instruction |
| ------------------ |
| |
| The *select* instruction is used to choose between pairs of values, based on a |
| condition, without PNaClAsm-level branching. |
| |
| **Syntax**:: |
| |
| %vN = select CT C, T V1, T V2; <A> |
| |
| **Record**:: |
| |
| AA: <29, VV1, VV2, CC> |
| |
| **Semantics**: |
| |
| The *select* instruction chooses pairs of values ``V1`` and ``V2``, based on |
| condition value ``C``. The type ``CT`` of value ``C`` must either be an i1, or |
| a vector of type i1. The type of values ``V1`` and ``V2`` must be of type |
| ``T``. Type ``T`` must either be a primitive type, or a vector of a primitive |
| type. |
| |
| Both ``CT`` and ``T`` must be primitive types, or both must be vector types of |
| the same size. When the contents of ``C`` is 1, the corresponding value from |
| ``V1`` will be chosen. Otherwise the corresponding value from ``V2`` will be |
| chosen. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| CC == RelativeIndex(C) & |
| VV1 == RelativeIndex(V1) & |
| VV2 == RelativeIndex(V2) & |
| T == TypeOf(V1) == TypeOf(V2) & |
| UnderlyingType(CT) == i1 & |
| IsInteger(UnderlyingType(T)) or IsFloat(UnderlyingType(T)) & |
| UnderlyingCount(C) == UnderlyingCount(T) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = T; |
| |
| **Examples**:: |
| |
| 96:0| 1: <65535, 12, 2> | function i32 @f0(i32 %p0, i32 %p1) { |
| | | // BlockID = 12 |
| 104:0| 3: <1, 1> | blocks 1; |
| 106:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 116:0| 3: <1, 2> | i1: |
| 118:4| 3: <4, 3> | %c0 = i1 1; |
| 121:0| 0: <65534> | } |
| | | %b0: |
| 124:0| 3: <29, 3, 2, 1> | %v0 = select i1 %c0, i32 %p0, |
| | | i32 %p1; |
| 128:0| 3: <10, 1> | ret i32 %v0; |
| 130:4| 0: <65534> | } |
| |
| |
| Call Instructions |
| ----------------- |
| |
| The *call* instruction does a function call. The call instruction is used to |
| cause control flow to transfer to a specified routine, with its incoming |
| arguments bound to the specified values. When a return instruction in the called |
| function is reached, control flow continues with the instruction after the |
| function call. If the call is to a function, the returned value is the value |
| generated by the call instruction. Otherwise no result is defined by the call. |
| |
| If the *tail* flag is associated with the call instruction, then the :ref:`PNaCl |
| translator<link_for_pnacl_translator>` is free to perform tail call |
| optimization. That is, the *tail* flag is a hint that may be ignored by the |
| PNaCl translator. |
| |
| There are two kinds of calls: *direct* and *indirect*. A *direct* call calls a |
| defined :ref:`function address<link_for_function_address_section>` (i.e. a |
| reference to a bitcode ID of the form ``%fF``). All other calls are *indirect*. |
| |
| Direct Procedure Call |
| ^^^^^^^^^^^^^^^^^^^^^ |
| |
| The direct procedure call calls a defined :ref:`function |
| address<link_for_function_address_section>` whose :ref:`type |
| signature<link_for_function_type>` returns type void. |
| |
| **Syntax**:: |
| |
| TAIL call void @fF (T1 A1, ... , TN AN); <A> |
| |
| **Record**:: |
| |
| AA: <34, CC, F, AA1, ... , AAN> |
| |
| **Semantics**: |
| |
| The direct procedure call calls a define function address ``%fF`` whose type |
| signature return type is void. The arguments ``A1`` through ``AN`` are passed in |
| the order specified. The type of argument ``AI`` must be type ``TI`` (for all I, |
| 1 <=I <= N). Flag ``TAIL`` is optional. If it is included, it must be the |
| literal ``tail``. |
| |
| The types of the arguments must match the corresponding types of the function |
| signature associated with ``%fF``. The return type of ``%f`` must be void. |
| |
| TAIL is encoded into calling convention value ``CC`` as follows: |
| |
| ====== == |
| TAIL CC |
| ====== == |
| "" 0 |
| "tail" 1 |
| ====== == |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N >= 0 & |
| TypeOfFcn(%fF) == void (T1, ... , TN) & |
| TypeOf(AI) == TI for all I, 1 <= I <= N |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| |
| **Examples**:: |
| |
| 72:0| 3: <8, 3, 0, 1, 0> | declare external |
| | | void @f0(i32, i64, i32); |
| ... |
| 116:0| 1: <65535, 12, 2> | function void @f1(i32 %p0) { |
| | | // BlockID = 12 |
| 124:0| 3: <1, 1> | blocks 1; |
| 126:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 136:0| 3: <1, 2> | i64: |
| 138:4| 3: <4, 2> | %c0 = i64 1; |
| 141:0| 0: <65534> | } |
| | | %b0: |
| 144:0| 3: <34, 0, 4, 2, 1, 2> | call void |
| | | @f0(i32 %p0, i64 %c0, i32 %p0); |
| 150:2| 3: <10> | ret void; |
| 152:0| 0: <65534> | } |
| |
| Direct Function Call |
| ^^^^^^^^^^^^^^^^^^^^ |
| |
| The direct function call calls a defined function address whose type signature |
| returns a value. |
| |
| **Syntax**:: |
| |
| %vN = TAIL call RT %fF (T1 A1, ... , TM AM); <A> |
| |
| |
| **Record**:: |
| |
| AA: <34, CC, F, AA1, ... , AAM> |
| |
| **Semantics**: |
| |
| The direct function call calls a defined function address ``%fF`` whose type |
| signature returned is not type void. The arguments ``A1`` through ``AM`` are |
| passed in the order specified. The type of argument ``AI`` must be type ``TI`` |
| (for all I, 1 <= I <= N). Flag ``TAIL`` is optional. If it is included, it must |
| be the literal ``tail``. |
| |
| The types of the arguments must match the corresponding types of the function |
| signature associated with ``%fF``. The return type must match ``RT``. |
| |
| Each parameter type ``TI``, and return type ``RT``, must either be a primitive |
| type, or a vector type. If the parameter type is an integer type, it must |
| either be i32 or i64. |
| |
| TAIL is encoded into calling convention value ``CC`` as follows: |
| |
| ====== == |
| TAIL CC |
| ====== == |
| "" 0 |
| "tail" 1 |
| ====== == |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N >= 0 & |
| TypeOfFcn(%fF) == RT (T1, ... , TN) & |
| TypeOf(AI) == TI for all I, 1 <= I <= M & |
| IsFcnArgType(TI) for all I, 1 <= I <= M & |
| IsFcnArgType(RT) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = RT; |
| |
| **Examples**:: |
| |
| 72:0| 3: <8, 2, 0, 1, 0> | declare external |
| | | i32 @f0(i32, i64, i32); |
| ... |
| 116:0| 1: <65535, 12, 2> | function i32 @f1(i32 %p0) { |
| | | // BlockID = 12 |
| 124:0| 3: <1, 1> | blocks 1; |
| 126:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 136:0| 3: <1, 1> | i64: |
| 138:4| 3: <4, 2> | %c0 = i64 1; |
| 141:0| 0: <65534> | } |
| | | %b0: |
| 144:0| 3: <34, 0, 4, 2, 1, 2> | %v0 = call i32 |
| | | @f0(i32 %p0, i64 %c0, i32 %p0); |
| 150:2| 3: <34, 1, 4, 1> | %v1 = tail call i32 @f1(i32 %v0); |
| 155:0| 3: <10, 2> | ret i32 %v0; |
| 157:4| 0: <65534> | } |
| |
| Indirect Procedure Call |
| ^^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The indirect procedure call calls a function using an indirect function address, |
| and whose type signature is assumed to return type void. It is different from |
| the direct procedure call because we can't use the type signature of the |
| corresponding direct function address to type check the construct. |
| |
| **Syntax**:: |
| |
| TAIL call void V (T1 A1, ... , TN AN); <A> |
| |
| **Record**:: |
| |
| AA: <44, CC, TV, VV, AA1, ... , AAN> |
| |
| **Semantics**: |
| |
| The indirect call procedure calls a function using value ``V`` that is an |
| indirect function address, and whose type signature is assumed to return type |
| void. The arguments ``A1`` through ``AN`` are passed in the order |
| specified. The type of argument ``AI`` must be type ``TI`` (for all I, 1 <= I <= |
| N). Flag ``TAIL`` is optional. If it is included, it must be the literal |
| ``tail``. |
| |
| Each parameter type ``TI`` (1 <= I <= N) must either be a primitive type, or a |
| vector type. If the parameter type is an integer type, it must either be i32 |
| or i64. |
| |
| TAIL is encoded into calling convention value ``CC`` as follows: |
| |
| ====== == |
| TAIL CC |
| ====== == |
| "" 0 |
| "tail" 1 |
| ====== == |
| |
| The type signature of the called procedure is assumed to be:: |
| |
| void (T1, ... , TN) |
| |
| It isn't necessary to define this type in the :ref:`types |
| block<link_for_types_block_section>`, since the type is inferred rather than |
| used. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| N >= 0 & |
| TV = TypeID(void) & |
| AbsoluteIndex(V) >= NumFuncAddresses & |
| TypeOf(AI) == TI for all I, 1 <= I <= N & |
| IsFcnArgType(TI) for all I, 1 <= I <= N |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 3> | count 3; |
| 50:4| 3: <2> | @t0 = void; |
| 52:2| 3: <7, 32> | @t1 = i32; |
| 55:4| 3: <21, 0, 0, 1> | @t2 = void (i32); |
| 59:4| 0: <65534> | } |
| ... |
| 92:0| 1: <65535, 12, 2> | function void @f0(i32 %p0) { |
| | | // BlockID = 12 |
| 100:0| 3: <1, 1> | blocks 1; |
| 102:4| 1: <65535, 11, 2> | constants { // BlockID = 11 |
| 112:0| 3: <1, 1> | i32: |
| 114:4| 3: <4, 2> | %c0 = i32 1; |
| 117:0| 0: <65534> | } |
| | | %b0: |
| 120:0| 3: <44, 0, 2, 0, 1> | call void %p0(i32 %c0); |
| 125:4| 3: <10> | ret void; |
| 127:2| 0: <65534> | } |
| |
| Indirect Function Call |
| ^^^^^^^^^^^^^^^^^^^^^^ |
| |
| The indirect function call calls a function using a value that is an indirect |
| function address. It is different from the direct function call because we can't |
| use the type signature of the corresponding literal function address to type |
| check the construct. |
| |
| **Syntax**:: |
| |
| %vN = TAIL call RT V (T1 A1, ... , TM AM); <A> |
| |
| **Record**:: |
| |
| AA: <34, CC, RRT, VV, AA1, ... , AAM> |
| |
| **Semantics**: |
| |
| The indirect function call calls a function using a value ``V`` that is an |
| indirect function address, and is assumed to return type ``RT``. The arguments |
| ``A1`` through ``AM`` are passed in the order specified. The type of argument |
| ``AI`` must be type ``TI`` (for all I, 1 <= I <= N). Flag ``TAIL`` is |
| optional. If it is included, it must be the literal ``tail``. |
| |
| Each parameter type ``TI`` (1 <= I <= M), and return type ``RT``, must either be |
| a primitive type, or a vector type. If the parameter type is an integer type, |
| it must either be i32 or i64. |
| |
| TAIL is encoded into calling convention value ``CC`` as follows: |
| |
| ====== == |
| TAIL CC |
| ====== == |
| '' 0 |
| 'tail' 1 |
| ====== == |
| |
| The type signature of the called function is assumed to be:: |
| |
| RT (T1, ... , TN) |
| |
| It isn't necessary to define this type in the :ref:`types |
| block<link_for_types_block_section>`, since the type is inferred rather than |
| used. |
| |
| **Constraints**:: |
| |
| AA == AbbrevIndex(A) & |
| RRT = TypeID(RT) & |
| VV = RelativeIndex(V) & |
| M >= 0 & |
| AbsoluteIndex(V) >= NumFcnAddresses & |
| TypeOf(AI) == TI for all I, 1 <= I <= M & |
| IsFcnArgType(TI) for all I, 1 <= I <= M & |
| IsFcnArgType(RT) & |
| N == NumValuedInsts |
| |
| **Updates**:: |
| |
| ++NumValuedInsts; |
| TypeOf(%vN) = RT; |
| |
| **Examples**:: |
| |
| 40:0| 1: <65535, 17, 2> | types { // BlockID = 17 |
| 48:0| 3: <1, 6> | count 6; |
| 50:4| 3: <7, 32> | @t0 = i32; |
| 53:6| 3: <3> | @t1 = float; |
| 55:4| 3: <4> | @t2 = double; |
| 57:2| 3: <21, 0, 0, 0, 1, 2> | @t3 = i32 (i32, float, double); |
| 62:6| 3: <21, 0, 0, 1, 2> | @t4 = i32 (float, double); |
| 67:4| 3: <2> | @t5 = void; |
| 69:2| 0: <65534> | } |
| ... |
| 104:0| 1: <65535, 12, 2> | function |
| | | i32 |
| | | @f0(i32 %p0, float %p1, |
| | | double %p2) { |
| | | // BlockID = 12 |
| 112:0| 3: <1, 1> | blocks 1; |
| | | %b0: |
| 114:4| 3: <44, 0, 3, 0, 2, 1> | %v0 = call i32 |
| | | %p0(float %p1, double %p2); |
| 120:6| 3: <10, 1> | ret i32 %v0; |
| 123:2| 0: <65534> | } |
| |
| .. _link_for_memory_blocks_and_alignment_section: |
| |
| Memory Blocks and Alignment |
| =========================== |
| |
| In general, variable and heap allocated data are represented as byte addressable |
| memory blocks. Alignment is always a power of 2, and defines an expectation on |
| the memory address. That is, an alignment is met if the memory address is |
| (evenly) divisible by the alignment. Note that alignment of 0 is never allowed. |
| |
| Alignment plays a role at two points: |
| |
| * When you create a local/global variable |
| |
| * When you load/store data using a pointer. |
| |
| PNaClAsm allows most types to be placed at any address, and therefore can |
| have alignment of 1. However, many architectures can load more efficiently |
| if the data has an alignment that is larger than 1. As such, choosing a larger |
| alignment can make load/stores more efficient. |
| |
| On loads and stores, the alignment in the instruction is used to communicate |
| what assumptions the :ref:`PNaCl translator<link_for_pnacl_translator>` can |
| make when choosing the appropriate machine instructions. If the alignment is 1, |
| it can't assume anything about the memory address used by the instruction. When |
| the alignment is greater than one, it can use that information to potentially |
| chose a more efficient sequence of instructions to do the load/store. |
| |
| When laying out data within a variable, one also considers alignment. The reason |
| for this is that if you want an address to be aligned, within the bytes defining |
| the variable, you must choose an alignment for the variable that guarantees that |
| alignment. |
| |
| In PNaClAsm, the valid load/store alignments are: |
| |
| =========== ============== |
| Type Alignment |
| =========== ============== |
| i1 1 |
| i8 1 |
| i16 1 |
| i32 1 |
| i64 1 |
| Float 1, 4 |
| Double 1, 8 |
| <4 x i1> not applicable |
| <8 x i1> not applicable |
| <16 x i1> not applicable |
| <16 x i8> 1 |
| <8 x i16> 2 |
| <4 x i32> 4 |
| <4 x float> 4 |
| =========== ============== |
| |
| Note that only vectors do not have an alignment value of 1. Hence, they can't be |
| placed at an arbitrary memory address. Also, since vectors on ``i1`` can't be |
| loaded/stored, the alignment is not applicable for these types. |
| |
| .. _link_for_intrinsic_functions_section: |
| |
| Intrinsic Functions |
| =================== |
| |
| Intrinsic functions are special in PNaClAsm. They are implemented as specially |
| named (external) function calls. The purpose of these intrinsic functions is to |
| extend the PNaClAsm instruction set with additional functionality that is |
| architecture specific. Hence, they either can't be implemented within PNaClAsm, |
| or a non-architecture specific implementation may be too slow on some |
| architectures. In such cases, the :ref:`PNaCl |
| translator<link_for_pnacl_translator>` must fill in the corresponding |
| implementation, since only it knows the architecture it is compiling down to. |
| |
| Examples of intrinsic function calls are for concurrent operations, atomic |
| operations, bulk memory moves, thread pointer operations, and long jumps. |
| |
| It should be noted that calls to intrinsic functions do not have the same |
| calling type constraints as ordinary functions. That is, an intrinsic can use |
| any integer type for arguments/results, unlike ordinary functions (which |
| restrict integer types to ``i32`` and ``i64``). |
| |
| See the :doc:`PNaCl bitcode reference manual<pnacl-bitcode-abi>` for the full |
| set of intrinsic functions allowed. Note that in PNaClAsm, all pointer types to |
| an (LLVM) intrinsic function is converted to type i32. |
| |
| .. _link_for_support_functions_section: |
| |
| Support Functions |
| ================= |
| |
| Defines functions used to convert syntactic representation to values in the |
| corresponding record. |
| |
| SignRotate |
| ---------- |
| |
| The SignRotate function encodes a signed integer in an easily compressible |
| form. This is done by rotating the sign bit to the rightmost bit, rather than |
| the leftmost bit. By doing this rotation, both small positive and negative |
| integers are small (unsigned) integers. Therefore, all small integers can be |
| encoded as a small (unsigned) integers. |
| |
| The definition of SignRotate(N) is: |
| |
| ======== ============= ========= |
| Argument Value Condition |
| ======== ============= ========= |
| N abs(N)<<1 N >= 0 |
| N abs(N)<<1 + 1 N < 0 |
| ======== ============= ========= |
| |
| .. _link_for_absolute_index_section: |
| |
| AbsoluteIndex |
| ------------- |
| |
| Bitcode IDs of the forms ``@fN``, ``@gN``, ``%pN``, ``%cN``, and ``%vN``, are |
| combined into a single index space. This can be done because of the ordering |
| imposed by PNaClAsm. All function address bitcode IDs must be defined before any |
| of the other forms of bitcode IDs. All global address bitcode IDs must be |
| defined before any local bitcode IDs. Within a function block, the parameter |
| bitcode IDs must be defined before constant IDs, and constant IDs must be |
| defined before instruction value IDs. |
| |
| Hence, within a function block, it is safe to refer to all of these |
| bitcode IDs using a single *absolute* index. The absolute index for |
| each kind of bitcode ID is computed as follows: |
| |
| ========== =================================================================== |
| Bitcode ID AbsoluteIndex |
| ========== =================================================================== |
| @tN N |
| @fN N |
| @gN N + NumFcnAddresses |
| @pN N + NumFcnAddresses + NumGlobalAddresses |
| @cN N + NumFcnAddresses + NumGlobalAddresses + NumParams |
| @vN N + NumFcnAddresses + NumGlobalAddresses + NumParams + NumFcnConsts |
| ========== =================================================================== |
| |
| .. _link_for_relative_index: |
| |
| RelativeIndex |
| ------------- |
| |
| Relative indices are used to refer to values within instructions of a function. |
| The relative index of an ID is always defined in terms of the index associated |
| with the next value generating instruction. It is defined as follows:: |
| |
| RelativeIndex(J) = AbsoluteIndex(%vN) - AbsoluteIndex(J) |
| |
| where:: |
| |
| N = NumValuedInsts |
| |
| AbbrevIndex |
| ----------- |
| |
| This function converts user-defined abbreviation indices to the corresponding |
| internal abbreviation index saved in the bitcode file. It adds 4 to its |
| argument, since there are 4 predefined internal abbreviation indices (0, 1, 2, |
| and 3). |
| |
| ========= ============== |
| N AbbrevIndex(N) |
| ========= ============== |
| undefined 3 |
| %aA A + 4 |
| @aA A + 4 |
| ========= ============== |
| |
| Log2 |
| ---- |
| |
| This is the 32-bit log2 value of its argument. |
| |
| BitSizeOf |
| --------- |
| |
| Returns the number of bits needed to represent its argument (a type). |
| |
| ======= ================ |
| T BitSizeOf |
| ======= ================ |
| i1 1 |
| i8 8 |
| i16 16 |
| i32 32 |
| i64 64 |
| float 32 |
| double 64 |
| <N X T> N * BitSizeOf(T) |
| ======= ================ |
| |
| UnderlyingType |
| -------------- |
| |
| Returns the primitive type of the type construct. For primitive types, the |
| *UnderlyingType* is itself. For vector types, the base type of the vector is the |
| underlying type. |
| |
| UnderlyingCount |
| --------------- |
| |
| Returns the size of the vector if given a vector, and 0 for primitive types. |
| Note that this function is used to check if two vectors are of the same size. |
| It is also used to test if two types are either primitive (i.e. UnderlyingCount |
| returns 0 for both types) or are vectors of the same size (i.e. UnderlyingCount |
| returns the same non-zero value). |
| |
| IsInteger |
| --------- |
| |
| Returns true if the argument is in {i1, i8, i16, i32, i64}. |
| |
| IsFloat |
| ------- |
| |
| Returns true if the argument is in {``float``, ``double``}. |
| |
| IsVector |
| -------- |
| |
| Returns true if the argument is a vector type. |
| |
| IsPrimitive |
| ----------- |
| |
| Returns true if the argument is a primitive type. That is:: |
| |
| IsPrimitive(T) == IsInteger(T) or IsFloat(T) |
| |
| IsFcnArgType |
| ------------ |
| |
| Returns true if the argument is a primitive type or a vector type. Further, |
| if it is an integer type, it must be i32 or i64. That is:: |
| |
| IsFcnArgType(T) = (IsInteger(T) and (i32 = BitSizeOf(T) |
| or i64 == BitSizeOf(T))) |
| or IsFloat(T) or IsVector(T) |
| |
| .. _link_for_abbreviations_section: |
| |
| Abbreviations |
| ============= |
| |
| Abbreviations are used to convert PNaCl records to a sequence of bits. PNaCl |
| uses the same strategy as `LLVM's bitcode file format |
| <http://llvm.org/docs/BitCodeFormat.html>`_. See that document for more |
| details. |
| |
| It should be noted that we replace LLVM's header (called the *Bitcode Wrapper |
| Format*) with the bytes of the :ref:`PNaCl record |
| header<link_for_header_record_section>`. In addition, PNaCl bitcode files do |
| not allow *blob* abbreviation. |
| |
| .. _link_for_abbreviations_block_section: |
| |
| Abbreviations Block |
| ------------------- |
| |
| The abbreviations block is the first block in the module build. The |
| block is divided into sections. Each section is a sequence of records. Each |
| record in the sequence defines a user-defined abbreviation. Each section |
| defines abbreviations that can be applied to all (succeeding) blocks of a |
| particular kind. These abbreviations are denoted by the (global) ID of the form |
| *@aN*. |
| |
| In terms of `LLVM's bitcode file format |
| <http://llvm.org/docs/BitCodeFormat.html>`_, the abbreviations block is called a |
| *BLOCKINFO* block. Records *SETBID* and *DEFINE_ABBREV* are the only records |
| allowed in PNaCl's abbreviation block (i.e. it doesn't allow *BLOCKNAME* and |
| *SETRECORDNAME* records). |
| |
| TODO |
| ---- |
| |
| Extend this document to describe PNaCl's bitcode bit sequencer |
| without requiring the reader to refer to `LLVM's bitcode file |
| format <http://llvm.org/docs/BitCodeFormat.html>`_. |