blob: 20063f67790f07ec626d0708f13c4697e7b86833 [file] [log] [blame]
{{+bindTo:partials.standard_nacl_article}}
<b><font color="#cc0000">
NOTE:
Deprecation of the technologies described here has been announced
for platforms other than ChromeOS.<br/>
Please visit our
<a href="/native-client/migration">migration guide</a>
for details.
</font></b>
<hr/><section id="contents-of-pnacl-bitcode-files">
<h1 id="contents-of-pnacl-bitcode-files">Contents Of PNaCl Bitcode Files</h1>
<div class="contents local" id="contents" style="display: none">
<ul class="small-gap">
<li><a class="reference internal" href="#introduction" id="id6">Introduction</a></li>
<li><a class="reference internal" href="#data-model" id="id7">Data Model</a></li>
<li><a class="reference internal" href="#pnacl-blocks" id="id8">PNaCl Blocks</a></li>
<li><a class="reference internal" href="#pnacl-records" id="id9">PNaCl Records</a></li>
<li><a class="reference internal" href="#default-abbreviations" id="id10">Default Abbreviations</a></li>
<li><a class="reference internal" href="#pnacl-identifiers" id="id11">PNaCl Identifiers</a></li>
<li><a class="reference internal" href="#conventions-for-describing-records" id="id12">Conventions For Describing Records</a></li>
<li><a class="reference internal" href="#factorial-example" id="id13">Factorial Example</a></li>
<li><a class="reference internal" href="#road-map" id="id14">Road Map</a></li>
<li><p class="first"><a class="reference internal" href="#global-state" id="id15">Global State</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#typing-functions" id="id16">Typing Functions</a></li>
<li><a class="reference internal" href="#link-to-id-counters" id="id17">ID Counters</a></li>
<li><a class="reference internal" href="#size-variables" id="id18">Size Variables</a></li>
<li><a class="reference internal" href="#other-variables" id="id19">Other Variables</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#global-records" id="id20">Global Records</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#header-record" id="id21">Header Record</a></li>
<li><a class="reference internal" href="#enter-block-record" id="id22">Enter Block Record</a></li>
<li><a class="reference internal" href="#exit-block-record" id="id23">Exit Block Record</a></li>
<li><a class="reference internal" href="#abbreviation-record" id="id24">Abbreviation Record</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#types-block" id="id25">Types Block</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#count-record" id="id26">Count Record</a></li>
<li><a class="reference internal" href="#void-type" id="id27">Void Type</a></li>
<li><a class="reference internal" href="#integer-types" id="id28">Integer Types</a></li>
<li><a class="reference internal" href="#bit-floating-point-type" id="id29">32-Bit Floating Point Type</a></li>
<li><a class="reference internal" href="#id1" id="id30">64-bit Floating Point Type</a></li>
<li><a class="reference internal" href="#vector-types" id="id31">Vector Types</a></li>
<li><a class="reference internal" href="#function-type" id="id32">Function Type</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#globals-block" id="id33">Globals Block</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#link-for-globals-count-record" id="id34">Count Record</a></li>
<li><a class="reference internal" href="#global-variable-addresses" id="id35">Global Variable Addresses</a></li>
<li><a class="reference internal" href="#global-constant-addresses" id="id36">Global Constant Addresses</a></li>
<li><a class="reference internal" href="#zerofill-initializer" id="id37">Zerofill Initializer</a></li>
<li><a class="reference internal" href="#data-initializer" id="id38">Data Initializer</a></li>
<li><a class="reference internal" href="#relocation-initializer" id="id39">Relocation Initializer</a></li>
<li><a class="reference internal" href="#subfield-relocation-initializer" id="id40">Subfield Relocation Initializer</a></li>
<li><a class="reference internal" href="#compound-initializer" id="id41">Compound Initializer</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#valuesymtab-block" id="id42">Valuesymtab Block</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#entry-record" id="id43">Entry Record</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#module-block" id="id44">Module Block</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#version-record" id="id45">Version Record</a></li>
<li><a class="reference internal" href="#function-address" id="id46">Function Address</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#constants-blocks" id="id47">Constants Blocks</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#set-type-record" id="id48">Set Type Record</a></li>
<li><a class="reference internal" href="#undefined-literal" id="id49">Undefined Literal</a></li>
<li><a class="reference internal" href="#integer-literal" id="id50">Integer Literal</a></li>
<li><a class="reference internal" href="#floating-point-literal" id="id51">Floating Point Literal</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#function-blocks" id="id52">Function Blocks</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#function-enter" id="id53">Function Enter</a></li>
<li><a class="reference internal" href="#link-for-basic-blocks-count" id="id54">Count Record</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#terminator-instructions" id="id55">Terminator Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#return-void-instruction" id="id56">Return Void Instruction</a></li>
<li><a class="reference internal" href="#return-value-instruction" id="id57">Return Value Instruction</a></li>
<li><a class="reference internal" href="#unconditional-branch-instruction" id="id58">Unconditional Branch Instruction</a></li>
<li><a class="reference internal" href="#conditional-branch-instruction" id="id59">Conditional Branch Instruction</a></li>
<li><a class="reference internal" href="#unreachable" id="id60">Unreachable</a></li>
<li><a class="reference internal" href="#switch-instruction" id="id61">Switch Instruction</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#integer-binary-instructions" id="id62">Integer Binary Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#integer-add" id="id63">Integer Add</a></li>
<li><a class="reference internal" href="#integer-subtract" id="id64">Integer Subtract</a></li>
<li><a class="reference internal" href="#integer-multiply" id="id65">Integer Multiply</a></li>
<li><a class="reference internal" href="#signed-integer-divide" id="id66">Signed Integer Divide</a></li>
<li><a class="reference internal" href="#unsigned-integer-divide" id="id67">Unsigned Integer Divide</a></li>
<li><a class="reference internal" href="#signed-integer-remainder" id="id68">Signed Integer Remainder</a></li>
<li><a class="reference internal" href="#unsigned-integer-remainder-instruction" id="id69">Unsigned Integer Remainder Instruction</a></li>
<li><a class="reference internal" href="#shift-left" id="id70">Shift Left</a></li>
<li><a class="reference internal" href="#logical-shift-right" id="id71">Logical Shift Right</a></li>
<li><a class="reference internal" href="#arithmetic-shift-right" id="id72">Arithmetic Shift Right</a></li>
<li><a class="reference internal" href="#logical-and" id="id73">Logical And</a></li>
<li><a class="reference internal" href="#logical-or" id="id74">Logical Or</a></li>
<li><a class="reference internal" href="#logical-xor" id="id75">Logical Xor</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#floating-point-binary-instructions" id="id76">Floating Point Binary Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#floating-point-add" id="id77">Floating Point Add</a></li>
<li><a class="reference internal" href="#floating-point-subtract" id="id78">Floating Point Subtract</a></li>
<li><a class="reference internal" href="#floating-point-multiply" id="id79">Floating Point Multiply</a></li>
<li><a class="reference internal" href="#floating-point-divide" id="id80">Floating Point Divide</a></li>
<li><a class="reference internal" href="#floating-point-remainder" id="id81">Floating Point Remainder</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#memory-creation-and-access-instructions" id="id82">Memory Creation and Access Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#alloca-instruction" id="id83">Alloca Instruction</a></li>
<li><a class="reference internal" href="#load-instruction" id="id84">Load Instruction</a></li>
<li><a class="reference internal" href="#store-instruction" id="id85">Store Instruction</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#conversion-instructions" id="id86">Conversion Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#integer-truncating-instruction" id="id87">Integer Truncating Instruction</a></li>
<li><a class="reference internal" href="#floating-point-truncating-instruction" id="id88">Floating Point Truncating Instruction</a></li>
<li><a class="reference internal" href="#zero-extending-instruction" id="id89">Zero Extending Instruction</a></li>
<li><a class="reference internal" href="#sign-extending-instruction" id="id90">Sign Extending Instruction</a></li>
<li><a class="reference internal" href="#floating-point-extending-instruction" id="id91">Floating Point Extending Instruction</a></li>
<li><a class="reference internal" href="#floating-point-to-unsigned-integer-instruction" id="id92">Floating Point to Unsigned Integer Instruction</a></li>
<li><a class="reference internal" href="#floating-point-to-signed-integer-instruction" id="id93">Floating Point to Signed Integer Instruction</a></li>
<li><a class="reference internal" href="#unsigned-integer-to-floating-point-instruction" id="id94">Unsigned Integer to Floating Point Instruction</a></li>
<li><a class="reference internal" href="#signed-integer-to-floating-point-instruction" id="id95">Signed Integer to Floating Point Instruction</a></li>
<li><a class="reference internal" href="#bitcast-instruction" id="id96">Bitcast Instruction</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#comparison-instructions" id="id97">Comparison Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#integer-comparison-instructions" id="id98">Integer Comparison Instructions</a></li>
<li><a class="reference internal" href="#floating-point-comparison-instructions" id="id99">Floating Point Comparison Instructions</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#vector-instructions" id="id100">Vector Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#insert-element-instruction" id="id101">Insert Element Instruction</a></li>
<li><a class="reference internal" href="#extract-element-instruction" id="id102">Extract Element Instruction</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#other-instructions" id="id103">Other Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#forward-type-declaration" id="id104">Forward Type Declaration</a></li>
<li><a class="reference internal" href="#phi-instruction" id="id105">Phi Instruction</a></li>
<li><a class="reference internal" href="#select-instruction" id="id106">Select Instruction</a></li>
<li><p class="first"><a class="reference internal" href="#call-instructions" id="id107">Call Instructions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#direct-procedure-call" id="id108">Direct Procedure Call</a></li>
<li><a class="reference internal" href="#direct-function-call" id="id109">Direct Function Call</a></li>
<li><a class="reference internal" href="#indirect-procedure-call" id="id110">Indirect Procedure Call</a></li>
<li><a class="reference internal" href="#indirect-function-call" id="id111">Indirect Function Call</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#memory-blocks-and-alignment" id="id112">Memory Blocks and Alignment</a></li>
<li><a class="reference internal" href="#intrinsic-functions" id="id113">Intrinsic Functions</a></li>
<li><p class="first"><a class="reference internal" href="#support-functions" id="id114">Support Functions</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#signrotate" id="id115">SignRotate</a></li>
<li><a class="reference internal" href="#absoluteindex" id="id116">AbsoluteIndex</a></li>
<li><a class="reference internal" href="#relativeindex" id="id117">RelativeIndex</a></li>
<li><a class="reference internal" href="#abbrevindex" id="id118">AbbrevIndex</a></li>
<li><a class="reference internal" href="#log2" id="id119">Log2</a></li>
<li><a class="reference internal" href="#bitsizeof" id="id120">BitSizeOf</a></li>
<li><a class="reference internal" href="#underlyingtype" id="id121">UnderlyingType</a></li>
<li><a class="reference internal" href="#underlyingcount" id="id122">UnderlyingCount</a></li>
<li><a class="reference internal" href="#isinteger" id="id123">IsInteger</a></li>
<li><a class="reference internal" href="#isfloat" id="id124">IsFloat</a></li>
<li><a class="reference internal" href="#isvector" id="id125">IsVector</a></li>
<li><a class="reference internal" href="#isprimitive" id="id126">IsPrimitive</a></li>
<li><a class="reference internal" href="#isfcnargtype" id="id127">IsFcnArgType</a></li>
</ul>
</li>
<li><p class="first"><a class="reference internal" href="#abbreviations" id="id128">Abbreviations</a></p>
<ul class="small-gap">
<li><a class="reference internal" href="#abbreviations-block" id="id129">Abbreviations Block</a></li>
<li><a class="reference internal" href="#todo" id="id130">TODO</a></li>
</ul>
</li>
</ul>
</div><h2 id="introduction">Introduction</h2>
<p>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 <em>PNaClAsm</em>, and defines the textual form of the bitcode
file. The textual form is then lowered to a sequence of <a class="reference internal" href="#link-for-pnacl-records"><em>PNaCl
records</em></a>. The final layer applies abbreviations that
convert each PNaCl record into a corresponding sequence of bits.</p>
<img alt="/native-client/images/PNaClBitcodeFlow.png" src="/native-client/images/PNaClBitcodeFlow.png" />
<p>PNaClAsm uses a <em>static single assignment</em> (SSA) based representation that
requires generated results to have a single (assignment) source.</p>
<p>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 <a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviations</em></a> are used to convert
PNaCl records into the sequence of bits.</p>
<p>Each construct in PNaClAsm defines a corresponding <a class="reference internal" href="#link-for-pnacl-records"><em>PNaCl
record</em></a>. 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.</p>
<p>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 <em>code</em>). PNaCl records can be nested. Nesting is defined by a
corresponding <a class="reference internal" href="#link-for-enter-block-record-section"><em>enter</em></a> and
<a class="reference internal" href="#link-for-exit-block-record-section"><em>exit</em></a> block record.</p>
<p>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.</p>
<p>The <em>PNaCl bitcode writer</em> 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.</p>
<p>For every kind of record, there is a method for converting records into bit
sequences. These methods correspond to a notion of
<a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviations</em></a>. Each abbreviation defines
a specific bit sequence conversion to be applied.</p>
<p>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.</p>
<p>Each abbreviation defines how a record is converted to a bit sequence. The
<a class="reference internal" href="/native-client/overview.html#link-for-pnacl-translator"><em>PNaCl translator</em></a> 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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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 <a class="reference internal" href="/native-client/devguide/devcycle/building.html#pnacl-compress"><em>pnacl-compress</em></a> is provided as part of the SDK to do
this job.</p>
<h2 id="data-model">Data Model</h2>
<p>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 <code>long
long</code>).</p>
<p>Integers are assumed to be modeled using two&#8217;s complement. Floating point
support is fixed at <a class="reference internal" href="/native-client/reference/pnacl-c-cpp-language-support.html#c-cpp-floating-point"><em>IEEE 754</em></a> 32-bit and 64-bit
values (float and double, respectively).</p>
<h2 id="pnacl-blocks">PNaCl Blocks</h2>
<p>Blocks are used to organize records in the bitcode file. The kinds of blocks
defined in PNaClAsm are:</p>
<dl class="docutils">
<dt>Module block</dt>
<dd>A top-level block defining the program. The <a class="reference internal" href="#link-for-module-block"><em>module
block</em></a> 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.</dd>
<dt>Types block</dt>
<dd>The <a class="reference internal" href="#link-for-types-block-section"><em>types block</em></a> 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.</dd>
<dt>Globals block</dt>
<dd>The <a class="reference internal" href="#link-for-globals-block-section"><em>globals block</em></a> 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.</dd>
<dt>Valuesymtab block</dt>
<dd>The <a class="reference internal" href="#link-for-valuesymtab-block-section"><em>valuesymtab block</em></a> defines
textual names for external function addresses.</dd>
<dt>Function block</dt>
<dd>Each function (implemented) in a program has its own <a class="reference internal" href="#link-for-function-blocks-section"><em>function
block</em></a> that defines the implementation of
the corresponding function.</dd>
<dt>Constants block</dt>
<dd>Each implemented function that uses constants in its instructions defines a
<a class="reference internal" href="#link-for-constants-block-section"><em>constants block</em></a>. Constants blocks
appear within the corresponding function block of the implemented function.</dd>
<dt>Abbreviations block</dt>
<dd>Defines global abbreviations that are used to compress PNaCl records. The
<a class="reference internal" href="#link-for-abbreviations-block-section"><em>abbreviations block</em></a> is segmented
into multiple sections, one section for each kind of block. This block appears
at the beginning of the module block.</dd>
</dl>
<p>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.</p>
<p>A PNaCl program consists of a <a class="reference internal" href="#link-for-header-record-section"><em>header
record</em></a> and a <a class="reference internal" href="#link-for-module-block"><em>module
block</em></a>. The header record defines a sequence of bytes
uniquely identifying the file as a bitcode file. The module block defines the
program to run.</p>
<p>Each block, within a bitcode file, defines values. These values are associated
with IDs. Each type of block defines different kinds of IDs. The
<a class="reference internal" href="#link-for-module-block"><em>module</em></a>,
<a class="reference internal" href="#link-for-types-block-section"><em>types</em></a>,
<a class="reference internal" href="#link-for-globals-block-section"><em>globals</em></a>, and
<a class="reference internal" href="#link-for-abbreviations-block-section"><em>abbreviations</em></a> blocks define global
identifiers, and only a single instance can appear. The
<a class="reference internal" href="#link-for-function-blocks-section"><em>function</em></a> and
<a class="reference internal" href="#link-for-constants-block-section"><em>constant</em></a> blocks define local
identifiers, and can have multiple instances (one for each implemented
function).</p>
<p>The only records in the module block that define values, are <a class="reference internal" href="#link-for-function-address-section"><em>function
address</em></a> records. Each function address
record defines a different function address, and the <a class="reference internal" href="#link-for-function-type"><em>type
signature</em></a> associated with that function address.</p>
<p>Each <a class="reference internal" href="#link-for-function-blocks-section"><em>function block</em></a> 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
<a class="reference internal" href="#link-for-constants-block-section"><em>constants block</em></a>, nested within the
corresponding function block.</p>
<p>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
<a class="reference internal" href="#link-for-function-address-section"><em>defining</em></a> (rather than declared)
function address record in the module block.</p>
<p>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.</p>
<h2 id="pnacl-records"><span id="link-for-pnacl-records"></span>PNaCl Records</h2>
<p>A PNaCl record is a non-empty sequence of unsigned, 64-bit, integers. A record
is identified by the record <em>code</em>, 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.</p>
<p>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 <a class="reference external" href="http://llvm.org/docs/BitCodeFormat.html">LLVM records</a>). For backward compatibility,
obsolete numbers have not been reused, leaving gaps in the actual record code
values used.</p>
<p>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 <a class="reference internal" href="#link-for-global-record-codes"><em>global record
codes</em></a>. 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</sup>. Note: Well-formed PNaCl bitcode files
do not have record codes &gt;= 2<sup>16</sup>.</p>
<p>A PNaCl record is denoted as follows:</p>
<pre class="prettyprint">
a: &lt;v0, v1, ... , vN&gt;
</pre>
<p>The value <code>v0</code> is the record code. The remaining values, <code>v1</code> through
<code>vN</code>, 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. <code>a</code> is the index to the abbreviation used to convert
the record to a bit sequence.</p>
<p>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.</p>
<p>The <em>PNaCl bitstream writer</em>, 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
<a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviations</em></a>. However, at the record
level, one important aspect of this appears in <a class="reference internal" href="#link-for-enter-block-record-section"><em>block
enter</em></a> records. These records must define
how many bits are required to hold abbreviation indices associated with records
of that block.</p>
<h2 id="default-abbreviations"><span id="link-for-default-abbreviations"></span>Default Abbreviations</h2>
<p>There are 4 predefined (default) abbreviation indices, used as the default
abbreviations for PNaCl records. They are:</p>
<dl class="docutils">
<dt>0</dt>
<dd>Abbreviation index for the abbreviation used to bit-encode an exit block
record.</dd>
<dt>1</dt>
<dd>Abbreviation index for the abbreviation used to bit-encode an enter block
record.</dd>
<dt>2</dt>
<dd>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.</dd>
<dt>3</dt>
<dd>Abbreviation index for the default abbreviation to bit-encode all other
records in the bitcode file.</dd>
</dl>
<p>A block may, in addition, define a list of block specific, user-defined,
abbreviations (of length <code>U</code>). The number of bits <code>B</code> specified for an enter
record must be sufficiently large such that:</p>
<pre class="prettyprint">
2**B &gt;= U + 4
</pre>
<p>In addition, the upper limit for <code>B</code> is <code>16</code>.</p>
<p>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.</p>
<h2 id="pnacl-identifiers">PNaCl Identifiers</h2>
<p>A program is defined by a <a class="reference internal" href="#link-for-module-block"><em>module block</em></a>. Blocks can
be nested within other blocks, including the module block. Each block defines a
sequence of records.</p>
<p>Most of the records, within a block, also define unique values. Each unique
value is given a corresponding unique identifier (i.e. <em>ID</em>). In PNaClAsm, each
kind of block defines its own kind of identifiers. The names of these
identifiers are defined by concatenating a prefix character (<code>'&#64;'</code> or
<code>'%'</code>), 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.</p>
<p>Identifiers are categorized into two types, <em>local</em> and <em>global</em>. 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.</p>
<p>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 <a class="reference internal" href="/native-client/overview.html#link-for-pnacl-translator"><em>PNaCl
translator</em></a> uses this separation to parallelize the
compilation of functions.</p>
<p>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.</p>
<p>Global identifiers use the prefix character <code>'&#64;'</code> while local identifiers use
the prefix character <code>'%'</code>.</p>
<p>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 <a class="reference internal" href="/native-client/overview.html#link-for-pnacl-translator"><em>PNaCl
translator</em></a>, when downloaded into Chrome.</p>
<p>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.</p>
<p>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.</p>
<p>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)
<a class="reference internal" href="#link-for-forward-type-declaration-section"><em>forward type
declarations</em></a>. 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.</p>
<p>The kinds of identifiers used in PNaClAsm are:</p>
<dl class="docutils">
<dt>&#64;a</dt>
<dd>Global abbreviation identifier.</dd>
<dt>%a</dt>
<dd>Local abbreviation identifier.</dd>
<dt>%b</dt>
<dd>Function basic block identifier.</dd>
<dt>%c</dt>
<dd>Function constant identifier.</dd>
<dt>&#64;f</dt>
<dd>Global function address identifier.</dd>
<dt>&#64;g</dt>
<dd>Global variable/constant address identifier.</dd>
<dt>%p</dt>
<dd>Function parameter identifier.</dd>
<dt>&#64;t</dt>
<dd>Global type identifier.</dd>
<dt>%v</dt>
<dd>Value generated by an instruction in a function block.</dd>
</dl>
<h2 id="conventions-for-describing-records">Conventions For Describing Records</h2>
<p>PNaClAsm is the textual representation of <a class="reference internal" href="#link-for-pnacl-records"><em>PNaCl
records</em></a>. 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 <a class="reference internal" href="#link-for-global-state-section"><em>global state</em></a>. The global
state is updated by syntax rules. The purpose of the global state is to track
positional dependencies between records.</p>
<p>For each PNaCl construct, we define multiple sections. The <strong>Syntax</strong>
section defines a syntax rule for the construct. The <strong>Record</strong> section
defines the corresponding record associated with the syntax rule. The
<strong>Semantics</strong> 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.</p>
<p>The <strong>Constraints</strong> section (if present) defines any constraints associated
with the construct, including the global state. The <strong>Updates</strong> section (if
present) defines how the global state is updated when the construct is
processed. The <strong>Examples</strong> section gives one or more examples of using the
corresponding PNaClAsm construct.</p>
<p>Some semantics sections use functions to compute values. The meaning of
functions can be found in <a class="reference internal" href="#link-for-support-functions-section"><em>support
functions</em></a>.</p>
<p>The syntax rule may include the
<a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviation</em></a> to use, when converting to a
bit-sequence. These abbreviations, if allowed, are at the end of the construct,
and enclosed in <code>&lt;</code> and <code>&gt;</code> 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.</p>
<p>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.</p>
<p>For example, consider the following syntax rule:</p>
<pre class="prettyprint">
%vN = add T O1, O2; &lt;A&gt;
</pre>
<p>This rule defines a PNaClAsm add instruction. This construct defines an
instruction that adds two values (<code>O1</code> and <code>O2</code>) to generate instruction
value <code>%vN</code>. The types of the arguments, and the result, are all of type
<code>T</code>. If abbreviation ID <code>A</code> is present, the record is encoded using that
abbreviation. Otherwise the corresponding <a class="reference internal" href="#link-for-default-abbreviations"><em>default abbreviation
index</em></a> is used.</p>
<p>To be concrete, the syntactic rule above defines the structure of the following
PNaClAsm examples:</p>
<pre class="prettyprint">
%v10 = add i32 %v1, %v2; &lt;&#64;a5&gt;
%v11 = add i32 %v10, %v3;
</pre>
<p>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.</p>
<h2 id="factorial-example">Factorial Example</h2>
<p>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.</p>
<p>In C, the factorial function can be defined as:</p>
<pre class="prettyprint">
int fact(int n) {
if (n == 1) return 1;
return n * fact(n-1);
}
</pre>
<p>Compiling this into a PNaCl bitcode file, and dumping out its contents with
utility <a class="reference internal" href="/native-client/devguide/devcycle/building.html#pnacl-bcdis"><em>pnacl-bcdis</em></a>, the corresponding output is:</p>
<pre class="prettyprint">
0:0|&lt;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&gt; |
16:0|1: &lt;65535, 8, 2&gt; |module { // BlockID = 8
24:0| 3: &lt;1, 1&gt; | version 1;
26:4| 1: &lt;65535, 0, 2&gt; | abbreviations { // BlockID = 0
36:0| 0: &lt;65534&gt; | }
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;2&gt; | &#64;t1 = void;
55:4| 3: &lt;21, 0, 0, 0&gt; | &#64;t2 = i32 (i32);
59:4| 3: &lt;7, 1&gt; | &#64;t3 = i1;
62:0| 0: &lt;65534&gt; | }
64:0| 3: &lt;8, 2, 0, 0, 0&gt; | define external i32 &#64;f0(i32);
68:6| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
76:0| 3: &lt;5, 0&gt; | count 0;
78:4| 0: &lt;65534&gt; | }
80:0| 1: &lt;65535, 14, 2&gt; | valuesymtab { // BlockID = 14
88:0| 3: &lt;1, 0, 102, 97, 99, | &#64;f0 : &quot;fact&quot;;
| 116&gt; |
96:4| 0: &lt;65534&gt; | }
100:0| 1: &lt;65535, 12, 2&gt; | function i32 &#64;f0(i32 %p0) {
| | // BlockID = 12
108:0| 3: &lt;1, 3&gt; | blocks 3;
110:4| 1: &lt;65535, 11, 2&gt; | constants { // BlockID = 11
120:0| 3: &lt;1, 0&gt; | i32:
122:4| 3: &lt;4, 2&gt; | %c0 = i32 1;
125:0| 0: &lt;65534&gt; | }
| | %b0:
128:0| 3: &lt;28, 2, 1, 32&gt; | %v0 = icmp eq i32 %p0, %c0;
132:6| 3: &lt;11, 1, 2, 1&gt; | br i1 %v0, label %b1, label %b2;
| | %b1:
136:6| 3: &lt;10, 2&gt; | ret i32 %c0;
| | %b2:
139:2| 3: &lt;2, 3, 2, 1&gt; | %v1 = sub i32 %p0, %c0;
143:2| 3: &lt;34, 0, 5, 1&gt; | %v2 = call i32 &#64;f0(i32 %v1);
148:0| 3: &lt;2, 5, 1, 2&gt; | %v3 = mul i32 %p0, %v2;
152:0| 3: &lt;10, 1&gt; | ret i32 %v3;
154:4| 0: &lt;65534&gt; | }
156:0|0: &lt;65534&gt; |}
</pre>
<p>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.</p>
<p>Bit positions are defined by a pair <code>B:N</code>. <code>B</code> is the number of bytes, while
<code>N</code> is the bit offset within the <code>B</code>-th byte. Hence, the bit position (in
bits) is:</p>
<pre class="prettyprint">
B*8 + N
</pre>
<p>Hence, the first record is at bit offset <code>0</code> (<code>0*8+0</code>). The second record is
at bit offset <code>128</code> (<code>16*8+0</code>). The third record is at bit offset <code>192</code>
(<code>24*8+0</code>). The fourth record is at bit offset <code>212</code> (<code>26*8+4</code>).</p>
<p>The <a class="reference internal" href="#link-for-header-record-section"><em>header record</em></a> 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. &#8216;PEXE&#8217;. All PEXE
bitcode files begin with these four bytes.</p>
<p>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.</p>
<p>The types block (starting at bit address <code>40:0</code>), defines 4 types: <code>i1</code>,
<code>i32</code>, <code>void</code>, and function signature <code>i32 (i32)</code>.</p>
<p>Bit address <code>64:0</code> declares the factorial function address <code>&#64;f0</code>, and its
corresponding type signature. Bit address <code>88:0</code> associates the name <code>fact</code>
with function address <code>&#64;f0</code>.</p>
<p>Bit address <code>100:0</code> defines the function block that implements function
<code>fact</code>. The entry point is <code>%b0</code> (at bit address <code>128:0</code>). It uses the
32-bit integer constant <code>1</code> (defined at bit addresses <code>122:4</code>). Bit address
<code>128:0</code> defines an equality comparison of the argument <code>%p0</code> with <code>1</code>
(constant <code>%c0</code>). Bit address <code>132:6</code> defines a conditional branch. If the
result of the previous comparison (<code>%v0</code>) is true, the program will branch to
block <code>%b1</code>. Otherwise it will branch to block <code>%b2</code>.</p>
<p>Bit address <code>136:6</code> returns constant <code>1</code> (<code>%c0</code>) when the input parameter
is 1. Instructions between bit address <code>139:2</code> and <code>154:4</code> compute and
return <code>n * fact(n-1)</code>.</p>
<h2 id="road-map">Road Map</h2>
<p>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.</p>
<p>Many records have implicit information associated with them, and must be
maintained across records. <a class="reference internal" href="#link-for-global-state-section"><em>Global state</em></a>
describes how this implicit information is modeled. In addition, there are
various <a class="reference internal" href="#link-for-support-functions-section"><em>support functions</em></a> that are
used to define the semantics of records, and how they update the global state.</p>
<p>There are just a handful of global records (records that either don&#8217;t appear in
any block, or can appear in all blocks). <a class="reference internal" href="#link-for-global-record-codes"><em>Global
records</em></a> describes these records. This includes
the block delimiter records <a class="reference internal" href="#link-for-enter-block-record-section"><em>enter</em></a>
and <a class="reference internal" href="#link-for-exit-block-record-section"><em>exit</em></a> that define block
boundaries.</p>
<p>PNaClAsm is a strongly typed language, and most block values are typed.
<a class="reference internal" href="#link-for-types-block-section"><em>types</em></a> describes the set of legal types, and
how to define types.</p>
<p>Global variables and their initializers are presented in the <a class="reference internal" href="#link-for-globals-block-section"><em>globals
block</em></a>. <a class="reference internal" href="#link-for-function-address-section"><em>Function
addresses</em></a> are part of the <a class="reference internal" href="#link-for-module-block"><em>module
block</em></a>, but must be defined before any global variables.</p>
<p>Names to be associated with global variables and function addresses, are defined
in the <a class="reference internal" href="#link-for-valuesymtab-block-section"><em>valuesymtab block</em></a>, and must
appear after the <a class="reference internal" href="#link-for-globals-block-section"><em>globals block</em></a>, but
before any <a class="reference internal" href="#link-for-function-blocks-section"><em>function definition</em></a>.</p>
<p>The <a class="reference internal" href="#link-for-module-block"><em>module block</em></a> 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.</p>
<p>Constants used within a <a class="reference internal" href="#link-for-function-blocks-section"><em>function
definition</em></a> must be defined using a
<a class="reference internal" href="#link-for-constants-block-section"><em>constants block</em></a>. Each function
definition is defined by a <a class="reference internal" href="#link-for-function-blocks-section"><em>function
block</em></a> and constant blocks can only appear
within function blocks. Constants defined within a constant block can only be
used in the enclosing function block.</p>
<p>Function definitions are defined by a sequence of instructions. There are
several types of instructions.</p>
<p>A <a class="reference internal" href="#link-for-terminator-instruction-section"><em>terminator instruction</em></a> is the
last instruction in a <a class="reference internal" href="#link-for-function-blocks-section"><em>basic block</em></a>, and
is a branch, return, or unreachable instruction.</p>
<p>There are <a class="reference internal" href="#link-for-integer-binary-instructions"><em>integer</em></a> and
<a class="reference internal" href="#link-for-floating-point-binary-instructions"><em>floating point</em></a> binary
operations. Integer binary instructions include both arithmetic and logical
operations. Floating point instructions define arithmetic operations.</p>
<p>There are also <a class="reference internal" href="#link-for-memory-creation-and-access-instructions"><em>memory
access</em></a> instructions that
allow one to load and store values. That section also includes how to define
local variables using the <a class="reference internal" href="#link-for-alloca-instruction"><em>alloca
instruction</em></a>.</p>
<p>One can also convert integer and floating point values using <a class="reference internal" href="#link-for-conversion-instructions"><em>conversion
instructions</em></a>.</p>
<p><a class="reference internal" href="#link-for-compare-instructions"><em>Comparison instructions</em></a>
allow you to compare values.</p>
<p><a class="reference internal" href="#link-for-vector-instructions"><em>Vector instructions</em></a> allow you to build and
update vectors. Corresponding <a class="reference internal" href="#link-for-intrinsic-functions-section"><em>intrinsic
functions</em></a>, as well as
<a class="reference internal" href="#link-for-integer-binary-instructions"><em>integer</em></a> and <a class="reference internal" href="#link-for-floating-point-binary-instructions"><em>floating
point</em></a> binary instructions allow
you to apply operations to vectors.</p>
<p>In addition, <a class="reference internal" href="#link-for-other-pnaclasm-instructions"><em>other instructions</em></a> are
available. This includes function and procedure calls.</p>
<p>There are also <a class="reference internal" href="#link-for-memory-blocks-and-alignment-section"><em>memory
alignment</em></a> issues that should be
considered for global and local variables, as well as load and store
instructions.</p>
<p>Finally, how to pack records is described in the
<a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviations</em></a> section.</p>
<h2 id="global-state"><span id="link-for-global-state-section"></span>Global State</h2>
<p>This section describes the global state associated with PNaClAsm. It is used to
define contextual data that is carried between records.</p>
<p>In particular, PNaClAsm is a strongly typed language, and hence, we must track
the type associated with values. Subsection <a class="reference internal" href="#link-to-typing-functions"><em>Typing Functions</em></a>
describes the functions used to maintain typing information associated with
values.</p>
<p>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 <a class="reference internal" href="#link-to-id-counters"><em>ID Counters</em></a> defines counters maintained in the global
state.</p>
<p>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 <a class="reference internal" href="/native-client/overview.html#link-for-pnacl-translator"><em>PNaCl translator</em></a> space requirements, or
a limit so that it can detect bad references to values. Subsection
<a class="reference internal" href="#link-for-size-variables"><em>Size Variables</em></a> defines variables that hold size definitions in
the corresponding records.</p>
<p>Finally, the function and constants block contain implicit context between
records in those blocks. Subsection <a class="reference internal" href="#link-to-other-variables"><em>Other Variables</em></a> defines the
variables that contain this implicit context.</p>
<h3 id="typing-functions"><span id="link-to-typing-functions"></span>Typing Functions</h3>
<p>Associated with most identifiers is a type. This type defines what type the
corresponding value has. It is defined by the (initially empty) map:</p>
<pre class="prettyprint">
TypeOf: ID -&gt; Type
</pre>
<p>For each type in the <a class="reference internal" href="#link-for-types-block-section"><em>types block</em></a>, a
corresponding inverse map:</p>
<pre class="prettyprint">
TypeID: Type -&gt; ID
</pre>
<p>is maintained to convert syntactic types to the corresponding type ID.</p>
<p>Note: This document assumes that map <code>TypeID</code> is automatically maintained
during updates to map <code>TypeOf</code> (when given a type <code>ID</code>). Hence, <em>Updates</em>
subsections will not contain assignments to this map.</p>
<p>Associated with each function identifier is its <a class="reference internal" href="#link-for-function-type"><em>type
signature</em></a>. 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).</p>
<p>Function type signatures are maintained using:</p>
<pre class="prettyprint">
TypeOfFcn: ID -&gt; Type
</pre>
<p>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:</p>
<pre class="prettyprint">
DefiningFcnIDs: set(ID)
</pre>
<h3 id="link-to-id-counters"><span id="id-counters"></span>ID Counters</h3>
<p>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:</p>
<dl class="docutils">
<dt>NumTypes</dt>
<dd>The number of types defined so far (in the <a class="reference internal" href="#link-for-types-block-section"><em>types
block</em></a>).</dd>
<dt>NumFuncAddresses</dt>
<dd>The number of function addresses defined so far (in the <a class="reference internal" href="#link-for-module-block"><em>module
block</em></a>).</dd>
<dt>NumGlobalAddresses</dt>
<dd>The number of global variable/constant addresses defined so far (in the
<a class="reference internal" href="#link-for-globals-block-section"><em>globals block</em></a>).</dd>
<dt>NumParams</dt>
<dd>The number of parameters defined for a function. Note: Unlike other counters,
this value is set once, at the beginning of the corresponding <a class="reference internal" href="#link-for-function-blocks-section"><em>function
block</em></a>, based on the type signature
associated with the function.</dd>
<dt>NumFcnConsts</dt>
<dd>The number of constants defined in a function so far (in the corresponding
nested <a class="reference internal" href="#link-for-constants-block-section"><em>constants block</em></a>).</dd>
<dt>NumBasicBlocks</dt>
<dd>The number of basic blocks defined so far (within a <a class="reference internal" href="#link-for-function-blocks-section"><em>function
block</em></a>).</dd>
<dt>NumValuedInsts</dt>
<dd>The number of instructions, generating values, defined so far (within a
<a class="reference internal" href="#link-for-function-blocks-section"><em>function block</em></a>).</dd>
</dl>
<h3 id="size-variables"><span id="link-for-size-variables"></span>Size Variables</h3>
<p>A number of blocks define expected sizes of constructs. These sizes are recorded
in the following size variables:</p>
<dl class="docutils">
<dt>ExpectedBasicBlocks</dt>
<dd>The expected <a class="reference internal" href="#link-for-basic-blocks-count"><em>number of basic blocks</em></a> within
a function implementation.</dd>
<dt>ExpectedTypes</dt>
<dd>The expected <a class="reference internal" href="#link-for-types-count-record"><em>number of types</em></a> defined in
the types block.</dd>
<dt>ExpectedGlobals</dt>
<dd>The expected <a class="reference internal" href="#link-for-globals-count-record"><em>number of global variable/constant
addresses</em></a> in the globals block.</dd>
<dt>ExpectedInitializers</dt>
<dd>The expected <a class="reference internal" href="#link-for-compound-initializer"><em>number of initializers</em></a> for
a global variable/constant address in the globals block.</dd>
</dl>
<p>It is assumed that the corresponding <a class="reference internal" href="#link-to-id-counters"><em>ID counters</em></a> are
always smaller than the corresponding size variables (except
ExpectedInitializers). That is:</p>
<pre class="prettyprint">
NumBasicBlocks &lt; ExpectedBasicBlocks
NumTypes &lt; ExpectedTypes
NumGlobalAddresses &lt; ExpectedGlobals
</pre>
<h3 id="other-variables"><span id="link-to-other-variables"></span>Other Variables</h3>
<dl class="docutils">
<dt>EnclosingFcnID</dt>
<dd>The function ID of the function block being processed.</dd>
<dt>ConstantsSetType</dt>
<dd>Holds the type associated with the last <a class="reference internal" href="#link-for-constants-set-type-record"><em>set type
record</em></a> in the constants block. Note: at
the beginning of each constants block, this variable is set to type void.</dd>
</dl>
<h2 id="global-records"><span id="link-for-global-record-codes"></span>Global Records</h2>
<p>Global records are records that can appear in any block. These records have
the same meaning in multiple kinds of blocks.</p>
<p>There are four global PNaCl records, each having its own record code. These
global records are:</p>
<dl class="docutils">
<dt>Header</dt>
<dd>The <a class="reference internal" href="#link-for-header-record-section"><em>header record</em></a> is the first record
of a PNaCl bitcode file, and identifies the file&#8217;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.</dd>
<dt>Enter</dt>
<dd>An <a class="reference internal" href="#link-for-enter-block-record-section"><em>enter record</em></a> defines the
beginning of a block. Since blocks can be nested, one can appear inside other
blocks, as well as at the top level.</dd>
<dt>Exit</dt>
<dd>An <a class="reference internal" href="#link-for-exit-block-record-section"><em>exit record</em></a> defines the end of a
block. Hence, it must appear in every block, to end the block.</dd>
<dt>Abbreviation</dt>
<dd>An <a class="reference internal" href="#link-for-abbreviation-record"><em>abbreviation record</em></a> 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.</dd>
</dl>
<p>All global records can&#8217;t have user-defined abbreviations associated with
them. The <a class="reference internal" href="#link-for-default-abbreviations"><em>default abbreviation</em></a> is always
used.</p>
<h3 id="header-record"><span id="link-for-header-record-section"></span>Header Record</h3>
<p>The header record must be the first record in the file. It is the only record in
the bitcode file that doesn&#8217;t have a corresponding construct in PNaClAsm. In
addition, no abbreviation index is associated with it.</p>
<p><strong>Syntax</strong>:</p>
<p>There is no syntax for header records in PNaClAsm.</p>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
&lt;65532, 80, 69, 88, 69, 1, 0, 8, 0, 17, 0, 4, 0, 2, 0, 0, 0&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>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.</p>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
0:0|&lt;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&gt; |
</pre>
<h3 id="enter-block-record"><span id="link-for-enter-block-record-section"></span>Enter Block Record</h3>
<p>Block records can be top-level, as well as nested in other blocks. Blocks must
begin with an <em>enter</em> record, and end with an
<a class="reference internal" href="#link-for-exit-block-record-section"><em>exit</em></a> record.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
N { &lt;B&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
1: &lt;65535, ID, B&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>Enter block records define the beginning of a block. <code>B</code>, if present, is the
number of bits needed to represent all possible abbreviation indices used within
the block. If omitted, <code>B=2</code> is assumed.</p>
<p>The block <code>ID</code> value is dependent on the name <code>N</code>. Valid names and
corresponding <code>BlockID</code> values are defined as follows:</p>
<table border="1" class="docutils">
<colgroup>
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">N</th>
<th class="head">Block ID</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>abbreviations</td>
<td>0</td>
</tr>
<tr class="row-odd"><td>constants</td>
<td>11</td>
</tr>
<tr class="row-even"><td>function</td>
<td>12</td>
</tr>
<tr class="row-odd"><td>globals</td>
<td>19</td>
</tr>
<tr class="row-even"><td>module</td>
<td>8</td>
</tr>
<tr class="row-odd"><td>types</td>
<td>17</td>
</tr>
<tr class="row-even"><td>valuesymtab</td>
<td>14</td>
</tr>
</tbody>
</table>
<p>Note: For readability, PNaClAsm defines a more readable form of a function block
enter record. See <a class="reference internal" href="#link-for-function-blocks-section"><em>function blocks</em></a> for
more details.</p>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
16:0|1: &lt;65535, 8, 2&gt; |module { // BlockID = 8
24:0| 3: &lt;1, 1&gt; | version 1;
26:4| 1: &lt;65535, 0, 2&gt; | abbreviations { // BlockID = 0
36:0| 0: &lt;65534&gt; | }
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 2&gt; | count 2;
50:4| 3: &lt;2&gt; | &#64;t0 = void;
52:2| 3: &lt;21, 0, 0&gt; | &#64;t1 = void ();
55:4| 0: &lt;65534&gt; | }
56:0| 3: &lt;8, 1, 0, 1, 0&gt; | declare external void &#64;f0();
60:6| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
68:0| 3: &lt;5, 0&gt; | count 0;
70:4| 0: &lt;65534&gt; | }
72:0|0: &lt;65534&gt; |}
</pre>
<h3 id="exit-block-record"><span id="link-for-exit-block-record-section"></span>Exit Block Record</h3>
<p>Block records can be top-level, as well as nested, records. Blocks must begin
with an <a class="reference internal" href="#link-for-enter-block-record-section"><em>enter</em></a> record, and end with
an <em>exit</em> record.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
}
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
0: &lt;65534&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>All exit records are identical, no matter what block they are ending. An exit
record defines the end of the block.</p>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
16:0|1: &lt;65535, 8, 2&gt; |module { // BlockID = 8
24:0| 3: &lt;1, 1&gt; | version 1;
26:4| 1: &lt;65535, 0, 2&gt; | abbreviations { // BlockID = 0
36:0| 0: &lt;65534&gt; | }
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 2&gt; | count 2;
50:4| 3: &lt;2&gt; | &#64;t0 = void;
52:2| 3: &lt;21, 0, 0&gt; | &#64;t1 = void ();
55:4| 0: &lt;65534&gt; | }
56:0| 3: &lt;8, 1, 0, 1, 0&gt; | declare external void &#64;f0();
60:6| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
68:0| 3: &lt;5, 0&gt; | count 0;
70:4| 0: &lt;65534&gt; | }
72:0|0: &lt;65534&gt; |}
</pre>
<h3 id="abbreviation-record"><span id="link-for-abbreviation-record"></span>Abbreviation Record</h3>
<p>Abbreviation records define abbreviations. See
<a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviations</em></a> for details on how
abbreviations should be written. This section only presents the mechanical
details for converting an abbreviation into a PNaCl record.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
A = abbrev &lt;E1, ... , EM&gt;;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
2: &lt;65533, M, EE1, ... , EEM&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>Defines an abbreviation <code>A</code> as the sequence of encodings <code>E1</code> through
<code>EM</code>. If the abbreviation appears within the <a class="reference internal" href="#link-for-abbreviations-block-section"><em>abbreviations
block</em></a>, <code>A</code> must be a global
abbreviation. Otherwise, <code>A</code> must be a local abbreviation.</p>
<p>Abbreviations within a block (or a section within the abbreviations block), must
be enumerated in order, starting at index <code>0</code>.</p>
<p>Valid encodings <code>Ei</code>, and the corresponding sequence of (unsigned) integers
<code>EEi</code>, ( for <code>1 &lt;= i &lt;= M</code>) are defined by the following table:</p>
<table border="1" class="docutils">
<colgroup>
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Ei</th>
<th class="head">EEi</th>
<th class="head">Form</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>C</td>
<td>1, C</td>
<td>Literal C in corresponding position in record.</td>
</tr>
<tr class="row-odd"><td>fixed(N)</td>
<td>0, 1, N</td>
<td>Encode value as a fixed sequence of N bits.</td>
</tr>
<tr class="row-even"><td>vbr(N)</td>
<td>0, 2, N</td>
<td>Encode value using a variable bit rate of N.</td>
</tr>
<tr class="row-odd"><td>char6</td>
<td>0, 4</td>
<td>Encode value as 6-bit char containing
characters [a-zA-Z0-9._].</td>
</tr>
<tr class="row-even"><td>array</td>
<td>0, 3</td>
<td>Allow zero or more of the succeeding abbreviation.</td>
</tr>
</tbody>
</table>
<p>Note that &#8216;array&#8217; can only appear as the second to last element in the
abbreviation. Notationally, <code>array(EM)</code> is used in place of <code>array</code> and
<code>EM</code>, the last two entries in an abbreviation.</p>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
0:0|&lt;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&gt; |
16:0|1: &lt;65535, 8, 2&gt; |module { // BlockID = 8
24:0| 3: &lt;1, 1&gt; | version 1;
26:4| 1: &lt;65535, 0, 2&gt; | abbreviations { // BlockID = 0
36:0| 1: &lt;1, 14&gt; | valuesymtab:
38:4| 2: &lt;65533, 4, 0, 1, 3, 0,| &#64;a0 = abbrev &lt;fixed(3), vbr(8),
| 2, 8, 0, 3, 0, 1, 8&gt; | array(fixed(8))&gt;;
43:2| 2: &lt;65533, 4, 1, 1, 0, 2,| &#64;a1 = abbrev &lt;1, vbr(8),
| 8, 0, 3, 0, 1, 7&gt; | array(fixed(7))&gt;;
48:0| 2: &lt;65533, 4, 1, 1, 0, 2,| &#64;a2 = abbrev &lt;1, vbr(8),
| 8, 0, 3, 0, 4&gt; | array(char6)&gt;;
52:1| 2: &lt;65533, 4, 1, 2, 0, 2,| &#64;a3 = abbrev &lt;2, vbr(8),
| 8, 0, 3, 0, 4&gt; | array(char6)&gt;;
56:2| 1: &lt;1, 11&gt; | constants:
58:6| 2: &lt;65533, 2, 1, 1, 0, 1,| &#64;a0 = abbrev &lt;1, fixed(2)&gt;;
| 2&gt; |
61:7| 2: &lt;65533, 2, 1, 4, 0, 2,| &#64;a1 = abbrev &lt;4, vbr(8)&gt;;
| 8&gt; |
65:0| 2: &lt;65533, 2, 1, 4, 1, 0&gt;| &#64;a2 = abbrev &lt;4, 0&gt;;
68:1| 2: &lt;65533, 2, 1, 6, 0, 2,| &#64;a3 = abbrev &lt;6, vbr(8)&gt;;
| 8&gt; |
71:2| 1: &lt;1, 12&gt; | function:
73:6| 2: &lt;65533, 4, 1, 20, 0, | &#64;a0 = abbrev &lt;20, vbr(6), vbr(4),
| 2, 6, 0, 2, 4, 0, 2, | vbr(4)&gt;;
| 4&gt; |
79:1| 2: &lt;65533, 4, 1, 2, 0, 2,| &#64;a1 = abbrev &lt;2, vbr(6), vbr(6),
| 6, 0, 2, 6, 0, 1, 4&gt; | fixed(4)&gt;;
84:4| 2: &lt;65533, 4, 1, 3, 0, 2,| &#64;a2 = abbrev &lt;3, vbr(6),
| 6, 0, 1, 2, 0, 1, 4&gt; | fixed(2), fixed(4)&gt;;
89:7| 2: &lt;65533, 1, 1, 10&gt; | &#64;a3 = abbrev &lt;10&gt;;
91:7| 2: &lt;65533, 2, 1, 10, 0, | &#64;a4 = abbrev &lt;10, vbr(6)&gt;;
| 2, 6&gt; |
95:0| 2: &lt;65533, 1, 1, 15&gt; | &#64;a5 = abbrev &lt;15&gt;;
97:0| 2: &lt;65533, 3, 1, 43, 0, | &#64;a6 = abbrev &lt;43, vbr(6),
| 2, 6, 0, 1, 2&gt; | fixed(2)&gt;;
101:2| 2: &lt;65533, 4, 1, 24, 0, | &#64;a7 = abbrev &lt;24, vbr(6), vbr(6),
| 2, 6, 0, 2, 6, 0, 2, | vbr(4)&gt;;
| 4&gt; |
106:5| 1: &lt;1, 19&gt; | globals:
109:1| 2: &lt;65533, 3, 1, 0, 0, 2,| &#64;a0 = abbrev &lt;0, vbr(6),
| 6, 0, 1, 1&gt; | fixed(1)&gt;;
113:3| 2: &lt;65533, 2, 1, 1, 0, 2,| &#64;a1 = abbrev &lt;1, vbr(8)&gt;;
| 8&gt; |
116:4| 2: &lt;65533, 2, 1, 2, 0, 2,| &#64;a2 = abbrev &lt;2, vbr(8)&gt;;
| 8&gt; |
119:5| 2: &lt;65533, 3, 1, 3, 0, 3,| &#64;a3 = abbrev &lt;3, array(fixed(8))&gt;
| 0, 1, 8&gt; | ;
123:2| 2: &lt;65533, 2, 1, 4, 0, 2,| &#64;a4 = abbrev &lt;4, vbr(6)&gt;;
| 6&gt; |
126:3| 2: &lt;65533, 3, 1, 4, 0, 2,| &#64;a5 = abbrev &lt;4, vbr(6), vbr(6)&gt;;
| 6, 0, 2, 6&gt; |
130:5| 0: &lt;65534&gt; | }
132:0| 1: &lt;65535, 17, 3&gt; | types { // BlockID = 17
140:0| 2: &lt;65533, 4, 1, 21, 0, | %a0 = abbrev &lt;21, fixed(1),
| 1, 1, 0, 3, 0, 1, 2&gt; | array(fixed(2))&gt;;
144:7| 3: &lt;1, 3&gt; | count 3;
147:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
150:7| 4: &lt;21, 0, 0, 0, 0&gt; | &#64;t1 = i32 (i32, i32); &lt;%a0&gt;
152:7| 3: &lt;2&gt; | &#64;t2 = void;
154:6| 0: &lt;65534&gt; | }
156:0| 3: &lt;8, 1, 0, 0, 0&gt; | define external i32 &#64;f0(i32, i32);
160:6| 1: &lt;65535, 19, 4&gt; | globals { // BlockID = 19
168:0| 3: &lt;5, 0&gt; | count 0;
170:6| 0: &lt;65534&gt; | }
172:0| 1: &lt;65535, 14, 3&gt; | valuesymtab { // BlockID = 14
180:0| 6: &lt;1, 0, 102&gt; | &#64;f0 : &quot;f&quot;; &lt;&#64;a2&gt;
182:7| 0: &lt;65534&gt; | }
184:0| 1: &lt;65535, 12, 4&gt; | function i32 &#64;f0(i32 %p0, i32 %p1) {
| | // BlockID = 12
192:0| 3: &lt;1, 1&gt; | blocks 1;
| | %b0:
194:6| 5: &lt;2, 2, 1, 0&gt; | %v0 = add i32 %p0, %p1; &lt;&#64;a1&gt;
197:2| 5: &lt;2, 3, 1, 0&gt; | %v1 = add i32 %p0, %v0; &lt;&#64;a1&gt;
199:6| 8: &lt;10, 1&gt; | ret i32 %v1; &lt;&#64;a4&gt;
201:0| 0: &lt;65534&gt; | }
204:0|0: &lt;65534&gt; |}
</pre>
<p>Note that the example above shows the standard abbreviations used by
<em>pnacl-finalize</em>.</p>
<h2 id="types-block"><span id="link-for-types-block-section"></span>Types Block</h2>
<p>The types block defines all types used in a program. It must appear in the
<a class="reference internal" href="#link-for-module-block"><em>module block</em></a>, before any <a class="reference internal" href="#link-for-function-address-section"><em>function
address</em></a> records, the <a class="reference internal" href="#link-for-globals-block-section"><em>globals
block</em></a>, the <a class="reference internal" href="#link-for-valuesymtab-block-section"><em>valuesymtab
block</em></a>, and any <a class="reference internal" href="#link-for-function-blocks-section"><em>function
blocks</em></a>.</p>
<p>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.</p>
<p>Each record in the types block defines a type used by the program. Types can be
broken into the following groups:</p>
<dl class="docutils">
<dt>Primitive value types</dt>
<dd>Defines the set of base types for values. This includes various sizes of
integer and floating point types.</dd>
<dt>Void type</dt>
<dd>A primitive type that doesn&#8217;t represent any value and has no size.</dd>
<dt>Function types</dt>
<dd>The type signatures of functions.</dd>
<dt>Vector type</dt>
<dd>Defines vectors of primitive types.</dd>
</dl>
<p>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.</p>
<p>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.</p>
<p>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&#8217;t be used in a PNaCl program.</p>
<p>The first record of a types block must be a <a class="reference internal" href="#link-for-types-count-record"><em>count
record</em></a>, 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.</p>
<p>To make this more concrete, consider the following example types block:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;3&gt; | &#64;t1 = float;
55:4| 3: &lt;2&gt; | &#64;t2 = void;
57:2| 3: &lt;21, 0, 2, 0, 1&gt; | &#64;t3 = void (i32, float);
62:0| 0: &lt;65534&gt; | }
</pre>
<p>This example defines a types block that defines four type IDs:</p>
<dl class="docutils">
<dt>&#64;t0</dt>
<dd>A 32-bit integer type.</dd>
<dt>&#64;t1</dt>
<dd>A 32-bit floating point type.</dd>
<dt>&#64;t2</dt>
<dd>The void type.</dd>
<dt>&#64;t3</dt>
<dd>A function, taking 32-bit integer and float point arguments that returns
void.</dd>
</dl>
<h3 id="count-record"><span id="link-for-types-count-record"></span>Count Record</h3>
<p>The <em>count record</em> 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.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
count N; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;1, N&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>This construct defines the number of types used by the PNaCl program. <code>N</code> is
the number of types defined in the types block. It is an error to define more
(or fewer) types than value <code>N</code>, within the enclosing types block.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
0 == NumTypes
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
ExpectedTypes = N;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;3&gt; | &#64;t1 = float;
55:4| 3: &lt;2&gt; | &#64;t2 = void;
57:2| 3: &lt;21, 0, 2, 0, 1&gt; | &#64;t3 = void (i32, float);
62:0| 0: &lt;65534&gt; | }
</pre>
<h3 id="void-type">Void Type</h3>
<p>The <em>void</em> type record defines the void type, which corresponds to the type that
doesn&#8217;t define any value, and has no size.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
&#64;tN = void; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;2&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The void type record defines the type that has no values and has no size.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
N == NumTypes
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumTypes;
TypeOf(&#64;tN) = void;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;3&gt; | &#64;t1 = float;
55:4| 3: &lt;2&gt; | &#64;t2 = void;
62:0| 0: &lt;65534&gt; | }
</pre>
<h3 id="integer-types">Integer Types</h3>
<p>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.</p>
<p>It should be noted that in PNaClAsm, all pointers are implemented as 32-bit
(unsigned) integers. There isn&#8217;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).</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
&#64;tN = iB; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;7, B&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>An integer type record defines an integer type. <code>B</code> defines the number of bits
of the integer type.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
N == NumTypes &amp;
B in {1, 8, 16, 32, 64}
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumTypes;
TypeOf(&#64;tN) = iB;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 7&gt; | count 7;
50:4| 3: &lt;7, 64&gt; | &#64;t0 = i64;
53:6| 3: &lt;7, 1&gt; | &#64;t1 = i1;
56:2| 3: &lt;7, 8&gt; | &#64;t2 = i8;
58:6| 3: &lt;7, 16&gt; | &#64;t3 = i16;
61:2| 3: &lt;7, 32&gt; | &#64;t4 = i32;
64:4| 3: &lt;21, 0, 0, 1&gt; | &#64;t5 = i64 (i1);
68:4| 3: &lt;2&gt; | &#64;t6 = void;
70:2| 0: &lt;65534&gt; | }
</pre>
<h3 id="bit-floating-point-type">32-Bit Floating Point Type</h3>
<p>PNaClAsm allows computation on 32-bit floating point values. A floating point
type record defines the 32-bit floating point type.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
&#64;tN = float; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;3&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A floating point type record defines the 32-bit floating point type.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
N == NumTypes
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumTypes;
TypeOf(&#64;tN) = float;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;4&gt; | &#64;t0 = double;
52:2| 3: &lt;3&gt; | &#64;t1 = float;
54:0| 3: &lt;21, 0, 0, 1&gt; | &#64;t2 = double (float);
58:0| 3: &lt;2&gt; | &#64;t3 = void;
59:6| 0: &lt;65534&gt; | }
</pre>
<h3 id="id1">64-bit Floating Point Type</h3>
<p>PNaClAsm allows computation on 64-bit floating point values. A 64-bit floating
type record defines the 64-bit floating point type.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
&#64;tN = double; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;4&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A double type record defines the 64-bit floating point type.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
N == NumTypes
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumTypes;
TypeOf(&#64;tN) = double;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;4&gt; | &#64;t0 = double;
52:2| 3: &lt;3&gt; | &#64;t1 = float;
54:0| 3: &lt;21, 0, 0, 1&gt; | &#64;t2 = double (float);
58:0| 3: &lt;2&gt; | &#64;t3 = void;
59:6| 0: &lt;65534&gt; | }
</pre>
<h3 id="vector-types">Vector Types</h3>
<p>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) <a class="reference internal" href="#link-for-vector-instructions"><em>vector instruction</em></a>. A
vector type requires a size (number of elements) and an underlying primitive
data type.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
&#64;tN = &lt; E x T &gt; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;12, E, TT&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The vector type defines a vector of elements. <code>T</code> is the type of each
element. <code>E</code> is the number of elements in the vector.</p>
<p>Vector types can only be defined on <code>i1</code>, <code>i8</code>, <code>i16</code>, <code>i32</code>, and
<code>float</code>. All vector types, except those on <code>i1</code>, must contain exactly 128
bits. The valid element sizes are restricted as follows:</p>
<table border="1" class="docutils">
<colgroup>
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">Type</th>
<th class="head">Valid element sizes</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>i1</td>
<td>4, 8, 16</td>
</tr>
<tr class="row-odd"><td>i8</td>
<td>16</td>
</tr>
<tr class="row-even"><td>i16</td>
<td>8</td>
</tr>
<tr class="row-odd"><td>i32</td>
<td>4</td>
</tr>
<tr class="row-even"><td>float</td>
<td>4</td>
</tr>
</tbody>
</table>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
TT == AbsoluteIndex(TypeID(T)) &amp;
N == NumTypes
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumTypes
TypeOf(&#64;tN) = &lt;E x T&gt;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 14&gt; | count 14;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;7, 1&gt; | &#64;t1 = i1;
56:2| 3: &lt;2&gt; | &#64;t2 = void;
58:0| 3: &lt;12, 4, 1&gt; | &#64;t3 = &lt;4 x i1&gt;;
61:2| 3: &lt;12, 8, 1&gt; | &#64;t4 = &lt;8 x i1&gt;;
64:4| 3: &lt;12, 16, 1&gt; | &#64;t5 = &lt;16 x i1&gt;;
67:6| 3: &lt;7, 8&gt; | &#64;t6 = i8;
70:2| 3: &lt;12, 16, 6&gt; | &#64;t7 = &lt;16 x i8&gt;;
73:4| 3: &lt;7, 16&gt; | &#64;t8 = i16;
76:0| 3: &lt;12, 8, 8&gt; | &#64;t9 = &lt;8 x i16&gt;;
79:2| 3: &lt;12, 4, 0&gt; | &#64;t10 = &lt;4 x i32&gt;;
82:4| 3: &lt;3&gt; | &#64;t11 = float;
84:2| 3: &lt;12, 4, 11&gt; | &#64;t12 = &lt;4 x float&gt;;
87:4| 3: &lt;21, 0, 2&gt; | &#64;t13 = void ();
90:6| 0: &lt;65534&gt; | }
</pre>
<h3 id="function-type"><span id="link-for-function-type"></span>Function Type</h3>
<p>The <em>function</em> type can be thought of as a function signature. It consists of a
return type, and a (possibly empty) list of formal parameter types.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
%tN = RT (T1, ... , TM) &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;21, 0, IRT, IT1, ... , ITM&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The function type defines the signature of a function. <code>RT</code> is the return type
of the function, while types <code>T1</code> through <code>TM</code> are the types of the
arguments. Indices to the corresponding type identifiers are stored in the
corresponding record.</p>
<p>The return value must either be a primitive type, type <code>void</code>, or a vector
type. Parameter types can be a primitive or vector type.</p>
<p>For ordinary functions, the only valid integer types that can be used for a
return or parameter type are <code>i32</code> and <code>i64</code>. All other integer types are
not allowed.</p>
<p>For <a class="reference internal" href="#link-for-intrinsic-functions-section"><em>intrinsic functions</em></a>, all
integer types are allowed for both return and parameter types.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
M &gt;= 0 &amp;
IRT == AbsoluteIndex(TypeID(RT)) &amp;
IT1 == AbsoluteIndex(TypeID(T1)) &amp;
...
ITM == AbsoluteIndex(TypeID(TM)) &amp;
N == NumTypes
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumTypes
TypeOf(&#64;tN) = RT (T1, ... , TM)
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 7&gt; | count 7;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;3&gt; | &#64;t1 = float;
55:4| 3: &lt;4&gt; | &#64;t2 = double;
57:2| 3: &lt;21, 0, 2, 1&gt; | &#64;t3 = double (float);
61:2| 3: &lt;2&gt; | &#64;t4 = void;
63:0| 3: &lt;21, 0, 4&gt; | &#64;t5 = void ();
66:2| 3: &lt;21, 0, 0, 0, 1, 0, 2&gt;| &#64;t6 =
| | i32 (i32, float, i32, double);
72:4| 0: &lt;65534&gt; | }
</pre>
<h2 id="globals-block"><span id="link-for-globals-block-section"></span>Globals Block</h2>
<p>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 <a class="reference internal" href="#link-for-module-block"><em>module block</em></a>. It must appear after the
<a class="reference internal" href="#link-for-types-block-section"><em>types block</em></a>, as well as after all
<a class="reference internal" href="#link-for-function-address-section"><em>function address</em></a> records. But, it must
also appear before the <a class="reference internal" href="#link-for-valuesymtab-block-section"><em>valuesymtab
block</em></a>, and any
<a class="reference internal" href="#link-for-function-blocks-section"><em>function blocks</em></a>.</p>
<p>The globals block begins with a <a class="reference internal" href="#link-for-globals-count-record"><em>count
record</em></a>, 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.</p>
<p>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 <a class="reference internal" href="#link-for-compound-initializer"><em>compound
record</em></a>, specifying a number <em>N</em>, followed by
sequence of <em>N</em> simple initializer records.</p>
<p>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.</p>
<p>For notational convenience, PNaClAsm begins a compound record with a &#8220;{&#8221;, and
inserts a &#8220;}&#8221; after the last initializer record associated with the compound
record. This latter &#8220;}&#8221; 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.</p>
<p>Explicit alignment is specified for global addresses, and must be a power of
2. See <a class="reference internal" href="#link-for-memory-blocks-and-alignment-section"><em>memory blocks and
alignment</em></a> for a more detailed
discussion on how to define alignment.</p>
<p>For example, consider the following pnacl-bcdis output snippet:</p>
<pre class="prettyprint">
52:0| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
60:0| 3: &lt;5, 2&gt; | count 2;
62:4| 3: &lt;0, 1, 1&gt; | const &#64;g0, align 1,
65:6| 3: &lt;2, 8&gt; | zerofill 8;
68:2| 3: &lt;0, 1, 0&gt; | var &#64;g1, align 1,
71:4| 3: &lt;1, 2&gt; | initializers 2 {
74:0| 3: &lt;3, 1, 2, 3, 4&gt; | { 1, 2, 3, 4}
78:6| 3: &lt;2, 2&gt; | zerofill 2;
| | }
81:2| 0: &lt;65534&gt; | }
</pre>
<p>This snippet defines the global constant <code>&#64;g0</code>, and the global variable
<code>&#64;g1</code>. <code>&#64;g0</code> is 8 bytes long, and initialized to zero. <code>&#64;g1</code> is
initialized with 6 bytes: <code>1 2 3 4 0 0</code>.</p>
<h3 id="link-for-globals-count-record"><span id="id2"></span>Count Record</h3>
<p>The count record defines the number of global addresses used by the PNaCl
program.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
count N; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;5, N&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>This record must appear first in the globals block. The count record defines
the number of global addresses used by the program.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
ExpectedGlobals = N;
ExpectedInitializers = 0;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
52:0| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
60:0| 3: &lt;5, 2&gt; | count 2;
62:4| 3: &lt;0, 1, 1&gt; | const &#64;g0, align 1,
65:6| 3: &lt;2, 8&gt; | zerofill 8;
68:2| 3: &lt;0, 1, 0&gt; | var &#64;g1, align 1,
71:4| 3: &lt;1, 2&gt; | initializers 2 {
74:0| 3: &lt;3, 1, 2, 3, 4&gt; | { 1, 2, 3, 4}
78:6| 3: &lt;2, 2&gt; | zerofill 2;
| | }
81:2| 0: &lt;65534&gt; | }
</pre>
<h3 id="global-variable-addresses"><span id="link-for-global-variable-address"></span>Global Variable Addresses</h3>
<p>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.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
var &#64;gN, align V, &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;0, VV, 0&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A global variable address record defines a global address for a global variable.
<code>V</code> is the <a class="reference internal" href="#link-for-memory-blocks-and-alignment-section"><em>memory
alignment</em></a> for the global variable
address, and is a power of 2.</p>
<p>It is assumed that the memory, referenced by the global variable address, can be
both read and written to.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
N == NumGlobalAddresses &amp;
ExpectedInitializers == 0 &amp;
VV == Log2(V+1)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumGlobalAddresses;
ExpectedInitializers = 1;
TypeOf(&#64;gN) = i32;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
52:0| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
60:0| 3: &lt;5, 2&gt; | count 2;
62:4| 3: &lt;0, 3, 0&gt; | var &#64;g0, align 4,
65:6| 3: &lt;2, 8&gt; | zerofill 8;
68:2| 3: &lt;0, 1, 0&gt; | var &#64;g1, align 1,
71:4| 3: &lt;3, 1, 2, 3, 4&gt; | { 1, 2, 3, 4}
76:2| 0: &lt;65534&gt; | }
80:0|0: &lt;65534&gt; |}
</pre>
<h3 id="global-constant-addresses"><span id="link-for-global-constant-address"></span>Global Constant Addresses</h3>
<p>A global constant address record defines an address corresponding to a global
constant that can&#8217;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.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
const &#64;gN, align V, &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;0, VV, 1&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A global constant address record defines a global address for a global constant.
<code>V</code> is the <a class="reference internal" href="#link-for-memory-blocks-and-alignment-section"><em>memory
alignment</em></a> for the global constant
address, and is a power of 2.</p>
<p>It is assumed that the memory, referenced by the global constant address, is
only read, and can&#8217;t be written to.</p>
<p>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.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
N == NumGlobalAddresses &amp;
ExpectedInitializers == 0 &amp;
VV == Log2(V+1)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumGlobalAddresses;
ExpectedInitializers = 1;
TypeOf(&#64;gN) = i32;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
52:0| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
60:0| 3: &lt;5, 2&gt; | count 2;
62:4| 3: &lt;0, 3, 1&gt; | const &#64;g0, align 4,
65:6| 3: &lt;2, 8&gt; | zerofill 8;
68:2| 3: &lt;0, 1, 1&gt; | const &#64;g1, align 1,
71:4| 3: &lt;3, 1, 2, 3, 4&gt; | { 1, 2, 3, 4}
76:2| 0: &lt;65534&gt; | }
</pre>
<h3 id="zerofill-initializer">Zerofill Initializer</h3>
<p>The zerofill initializer record initializes a sequence of bytes, associated with
a global address, with zeros.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
zerofill N; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;2, N&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A zerofill initializer record initializes a sequence of bytes, associated with a
global address, with zeros. The number of bytes initialized to zero is <code>N</code>.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
ExpectedInitializers &gt; 0
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
--ExpectedInitializers;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
52:0| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
60:0| 3: &lt;5, 2&gt; | count 2;
62:4| 3: &lt;0, 3, 1&gt; | const &#64;g0, align 4,
65:6| 3: &lt;2, 8&gt; | zerofill 8;
68:2| 3: &lt;0, 1, 0&gt; | var &#64;g1, align 1,
71:4| 3: &lt;2, 4&gt; | zerofill 4;
74:0| 0: &lt;65534&gt; | }
</pre>
<h3 id="data-initializer">Data Initializer</h3>
<p>Data records define a sequence of bytes. These bytes define the initial value of
the contents of the corresponding memory.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
{ B1 , .... , BN } &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;3, B1, ..., BN&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A data record defines a sequence of (unsigned) bytes <code>B1</code> through <code>BN</code>, that
initialize <code>N</code> bytes of memory.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
ExpectedInitializers &gt; 0
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
--ExpectedInitializers;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
56:0| 3: &lt;8, 1, 0, 1, 0&gt; | declare external void &#64;f0();
60:6| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
68:0| 3: &lt;5, 2&gt; | count 2;
70:4| 3: &lt;0, 1, 1&gt; | const &#64;g0, align 1,
73:6| 3: &lt;3, 1, 2, 97, 36, 44, | { 1, 2, 97, 36, 44, 88,
| 88, 44, 50&gt; | 44, 50}
86:0| 3: &lt;0, 1, 1&gt; | const &#64;g1, align 1,
89:2| 3: &lt;1, 3&gt; | initializers 3 {
91:6| 3: &lt;3, 1, 2, 3, 4&gt; | { 1, 2, 3, 4}
96:4| 3: &lt;4, 0&gt; | reloc &#64;f0;
99:0| 3: &lt;3, 99, 66, 22, 12&gt; | { 99, 66, 22, 12}
| | }
105:2| 0: &lt;65534&gt; | }
</pre>
<h3 id="relocation-initializer">Relocation Initializer</h3>
<p>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
<a class="reference internal" href="#link-for-function-address-section"><em>function</em></a>,
<a class="reference internal" href="#link-for-global-variable-address"><em>variable</em></a>, or
<a class="reference internal" href="#link-for-global-constant-address"><em>constant</em></a>). Since addresses are
pointers, a relocation initializer record defines 4 bytes of memory.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
reloc V; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;4, VV&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A relocation initializer record defines a 4-byte value containing the specified
global address <code>V</code>.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
VV == AbsoluteIndex(V) &amp;
VV &gt;= NumFuncAddresses &amp;
VV &lt; NumFuncAddresses + ExpectedGlobals &amp;
ExpectedInitializers &gt; 0
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
--ExpectedInitializers;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 2&gt; | count 2;
50:4| 3: &lt;2&gt; | &#64;t0 = void;
52:2| 3: &lt;21, 0, 0&gt; | &#64;t1 = void ();
55:4| 0: &lt;65534&gt; | }
56:0| 3: &lt;8, 1, 0, 1, 0&gt; | declare external void &#64;f0();
60:6| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
68:0| 3: &lt;5, 2&gt; | count 2;
70:4| 3: &lt;0, 1, 0&gt; | var &#64;g0, align 1,
73:6| 3: &lt;1, 3&gt; | initializers 3 {
76:2| 3: &lt;4, 0&gt; | reloc &#64;f0;
78:6| 3: &lt;4, 1&gt; | reloc &#64;g0;
81:2| 3: &lt;4, 2&gt; | reloc &#64;g1;
| | }
83:6| 3: &lt;0, 3, 0&gt; | var &#64;g1, align 4,
87:0| 3: &lt;2, 4&gt; | zerofill 4;
89:4| 0: &lt;65534&gt; | }
</pre>
<p>This example defines global address <code>&#64;g0</code> and <code>&#64;g1</code>. <code>&#64;g0</code> defines 12
bytes of memory, and is initialized with three addresses <code>&#64;f1</code>, <code>&#64;g0</code>, and
<code>&#64;g1</code>. Note that all global addresses can be used in a relocation
initialization record, even if it isn&#8217;t defined yet.</p>
<h3 id="subfield-relocation-initializer">Subfield Relocation Initializer</h3>
<p>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 <a class="reference internal" href="#link-for-global-variable-address"><em>variable</em></a> or
<a class="reference internal" href="#link-for-global-constant-address"><em>constant</em></a> address), plus a
constant. Since addresses are pointers, a relocation initializer record defines
4 bytes of memory.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
reloc V + X; &lt;A&gt;
reloc V - X; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;4, VV, XXX&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>A subfield relocation initializer record defines a 4-byte value containing the
specified global (non-function) address <code>V</code>, modified by the unsigned offset
<code>X</code>. <code>XX</code> is the corresponding signed offset. In the first form, <code>XX ==
X</code>. In the second form, <code>XX == -X</code>.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A)
VV == AbsoluteIndex(V)
VV &gt;= NumFuncAddresses
VV &lt; NumFuncAddresses + ExpectedGlobals
ExpectedInitializers &gt; 0
XXX == SignRotate(XX)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
--ExpectedInitializers;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 0&gt; | count 0;
50:4| 0: &lt;65534&gt; | }
52:0| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
60:0| 3: &lt;5, 3&gt; | count 3;
62:4| 3: &lt;0, 1, 0&gt; | var &#64;g0, align 1,
65:6| 3: &lt;1, 3&gt; | initializers 3 {
68:2| 3: &lt;4, 0, 1&gt; | reloc &#64;g0 + 1;
71:4| 3: &lt;4, 1, 4294967295&gt; | reloc &#64;g1 - 1;
79:2| 3: &lt;4, 2, 4&gt; | reloc &#64;g2 + 4;
| | }
82:4| 3: &lt;0, 3, 0&gt; | var &#64;g1, align 4,
85:6| 3: &lt;2, 4&gt; | zerofill 4;
88:2| 3: &lt;0, 3, 0&gt; | var &#64;g2, align 4,
91:4| 3: &lt;2, 8&gt; | zerofill 8;
94:0| 0: &lt;65534&gt; | }
</pre>
<h3 id="compound-initializer"><span id="link-for-compound-initializer"></span>Compound Initializer</h3>
<p>The compound initializer record must immediately follow a global
<a class="reference internal" href="#link-for-global-variable-address"><em>variable</em></a> or
<a class="reference internal" href="#link-for-global-constant-address"><em>constant</em></a> 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.</p>
<p>Note that a compound initializer can&#8217;t be used as a simple initializer of
another compound initializer (i.e. nested compound initializers are not
allowed).</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
initializers N { &lt;A&gt;
...
}
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;1, N&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>Defines that the next <cite>N</cite> initializers should be associated with the global
address of the previous record.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
ExpectedInitializers == 1
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
ExpectedInitializers = N;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 0&gt; | count 0;
50:4| 0: &lt;65534&gt; | }
52:0| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
60:0| 3: &lt;5, 2&gt; | count 2;
62:4| 3: &lt;0, 0, 1&gt; | const &#64;g0, align 0,
65:6| 3: &lt;1, 2&gt; | initializers 2 {
68:2| 3: &lt;2, 8&gt; | zerofill 8;
70:6| 3: &lt;3, 3, 2, 1, 0&gt; | { 3, 2, 1, 0}
| | }
75:4| 3: &lt;0, 0, 0&gt; | var &#64;g1, align 0,
78:6| 3: &lt;1, 2&gt; | initializers 2 {
81:2| 3: &lt;3, 1, 2, 3, 4&gt; | { 1, 2, 3, 4}
86:0| 3: &lt;2, 2&gt; | zerofill 2;
| | }
88:4| 0: &lt;65534&gt; | }
</pre>
<h2 id="valuesymtab-block"><span id="link-for-valuesymtab-block-section"></span>Valuesymtab Block</h2>
<p>The valuesymtab block does not define any values. Its only goal is to associate
text names with external <a class="reference internal" href="#link-for-function-address-section"><em>function
addresses</em></a>. Each association is defined by a
record in the valuesymtab block. Currently, only
<a class="reference internal" href="#link-for-intrinsic-functions-section"><em>intrinsic</em></a> function addresses and
the (external) start function (<code>_start</code>) can be named. All named function
addresses must be external. Each record in the valuesymtab block is a <em>entry</em>
record, defining a single name association.</p>
<h3 id="entry-record">Entry Record</h3>
<p>The <em>entry</em> record defines a name for a function address.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
V : &quot;NAME&quot;; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;1, B1, ... , BN&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The <em>entry</em> record defines a name <code>NAME</code> for function address <code>V</code>. <code>NAME</code>
is a sequence of ASCII characters <code>B1</code> through <code>BN</code>.</p>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
72:0| 3: &lt;8, 4, 0, 1, 0&gt; | declare external
| | void &#64;f0(i32, i32, i32, i32, i1);
76:6| 3: &lt;8, 4, 0, 1, 0&gt; | declare external
| | void &#64;f1(i32, i32, i32, i32, i1);
81:4| 3: &lt;8, 5, 0, 0, 0&gt; | define external void &#64;f2(i32);
86:2| 1: &lt;65535, 19, 2&gt; | globals { // BlockID = 19
92:0| 3: &lt;5, 0&gt; | count 0;
94:4| 0: &lt;65534&gt; | }
96:0| 1: &lt;65535, 14, 2&gt; | valuesymtab { // BlockID = 14
104:0| 3: &lt;1, 1, 108, 108, 118, | &#64;f1 : &quot;llvm.memmove.p0i8.p0i8.i32&quot;;
| 109, 46, 109, 101, |
| 109, 109, 111, 118, |
| 101, 46, 112, 48, |
| 105, 56, 46, 112, 48,|
| 105, 56, 46, 105, 51,|
| 50&gt; |
145:4| 3: &lt;1, 2, 95, 115, 116, | &#64;f2 : &quot;_start&quot;;
| 97, 114, 116&gt; |
157:0| 3: &lt;1, 0, 108, 108, 118, | &#64;f0 : &quot;llvm.memcpy.p0i8.p0i8.i32&quot;;
| 109, 46, 109, 101, |
| 109, 99, 112, 121, |
| 46, 112, 48, 105, 56,|
| 46, 112, 48, 105, 56,|
| 46, 105, 51, 50&gt; |
197:0| 0: &lt;65534&gt; | }
</pre>
<h2 id="module-block"><span id="link-for-module-block"></span>Module Block</h2>
<p>The module block, like all blocks, is enclosed in a pair of
<a class="reference internal" href="#link-for-enter-block-record-section"><em>enter</em></a> /
<a class="reference internal" href="#link-for-exit-block-record-section"><em>exit</em></a> records, using block ID 8. A
well-formed module block consists of the following records (in order):</p>
<dl class="docutils">
<dt>A version record</dt>
<dd>The <a class="reference internal" href="#link-for-version-record"><em>version record</em></a> 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.</dd>
<dt>Optional local abbreviations</dt>
<dd>Defines a list of local <a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviations</em></a>
to use for records within the module block.</dd>
<dt>An abbreviations block</dt>
<dd>The <a class="reference internal" href="#link-for-abbreviations-block-section"><em>abbreviations block</em></a> defines
user-defined, global abbreviations that are used to convert PNaCl records to
bit sequences in blocks following the abbreviations block.</dd>
<dt>A types block</dt>
<dd>The <a class="reference internal" href="#link-for-types-block-section"><em>types block</em></a> defines the set of all
types used in the program.</dd>
<dt>A non-empty sequence of function address records</dt>
<dd>Each record defines a <a class="reference internal" href="#link-for-function-address-section"><em>function
address</em></a> 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 <a class="reference internal" href="#link-for-function-blocks-section"><em>function
block</em></a> (appearing later in the module) that
defines the sequence of instructions for each defined function.</dd>
<dt>A globals block defining the global variables.</dt>
<dd>This <a class="reference internal" href="#link-for-globals-block-section"><em>block</em></a> defines the set of
global <a class="reference internal" href="#link-for-global-variable-address"><em>variable</em></a> and
<a class="reference internal" href="#link-for-global-constant-address"><em>constant</em></a> addresses used by the
program. In addition to the addresses, each global variable also defines how
the corresponding global variable is initialized.</dd>
<dt>An optional value symbol table block.</dt>
<dd>This <a class="reference internal" href="#link-for-valuesymtab-block-section"><em>block</em></a>, if defined, provides
textual names for <a class="reference internal" href="#link-for-function-address-section"><em>function
addresses</em></a> (previously defined in the
module). Note that only names for intrinsic functions and the start function
are specified.</dd>
<dt>A sequence of function blocks.</dt>
<dd>Each <a class="reference internal" href="#link-for-function-blocks-section"><em>function block</em></a> defines the
corresponding intermediate representation for each defined function. The
order of function blocks is used to associate them with <a class="reference internal" href="#link-for-function-address-section"><em>function
addresses</em></a>. The order of the defined
function blocks must follow the same order as the corresponding function
addresses defined in the module block.</dd>
</dl>
<p>Descriptions of the <a class="reference internal" href="#link-for-abbreviations-section"><em>abbreviations</em></a>,
<a class="reference internal" href="#link-for-types-block-section"><em>types</em></a>,
<a class="reference internal" href="#link-for-globals-block-section"><em>globals</em></a>, <a class="reference internal" href="#link-for-valuesymtab-block-section"><em>value symbol
table</em></a>, and
<a class="reference internal" href="#link-for-function-blocks-section"><em>function</em></a> 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.</p>
<h3 id="version-record"><span id="link-for-version-record"></span>Version Record</h3>
<p>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.</p>
<p>Note that currently, only PNaCl bitcode version 2, and version record value 1 is
defined.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
version N; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;1, N&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The version record defines which PNaCl reader/writer rules should be
followed. <code>N</code> is the version number. Currently <code>N</code> must be 1. Future
versions of PNaCl may define additional legal values.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A)
</pre>
<p><em>Examples</em>:</p>
<pre class="prettyprint">
16:0|1: &lt;65535, 8, 2&gt; |module { // BlockID = 8
24:0| 3: &lt;1, 1&gt; | version 1;
26:4| 1: &lt;65535, 0, 2&gt; | abbreviations { // BlockID = 0
36:0| 0: &lt;65534&gt; | }
</pre>
<h3 id="function-address"><span id="link-for-function-address-section"></span>Function Address</h3>
<p>A function address record describes a function address. <em>Defined</em> function
addresses define <a class="reference internal" href="#link-for-function-blocks-section"><em>implementations</em></a> while
<em>declared</em> function addresses do not.</p>
<p>Since a PNaCl program is assumed to be a complete (statically linked)
executable, All functions should be <em>defined</em> and <em>internal</em>. The exception to
this are <a class="reference internal" href="#link-for-intrinsic-functions-section"><em>intrinsic functions</em></a>, which
should only be <em>declared</em> and <em>external</em>, since intrinsic functions will be
automatically converted to appropriate code by the <a class="reference internal" href="/native-client/overview.html#link-for-pnacl-translator"><em>PNaCl
translator</em></a>.</p>
<p>The implementation of a <em>defined</em> function address is provided by a
corresponding function block, appearing later in the module block. The
association of a <em>defined</em> function address with the corresponding function
block is based on position. The <em>Nth</em> defined function address record, in the
module block, has its implementation in the <em>Nth</em> function block of that module
block.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
PN LN T0 &#64;fN ( T1 , ... , TM ); &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;8, T, C, P, L&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>Describes the function address <code>&#64;fN</code>. <code>PN</code> is the name that specifies the
prototype value <code>P</code> associated with the function. A function address is
<em>defined</em> only if <code>P == 0</code>. Otherwise, it is only <em>declared</em>. The type of the
function is <a class="reference internal" href="#link-for-function-type"><em>function type</em></a> <code>&#64;tT</code>. <code>L</code> is the
linkage specification corresponding to name <code>LN</code>. <code>C</code> is the calling
convention used by the function.</p>
<p>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 <code>void</code>,
or a vector type.</p>
<p>For ordinary functions, integer parameter and types can only be <code>i32</code> and
<code>i64</code>. All other integer types are not allowed. For intrinsic functions, all
integer types are allowed.</p>
<p>Valid prototype names <code>PN</code>, and corresponding <code>P</code> values, are:</p>
<table border="1" class="docutils">
<colgroup>
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">P</th>
<th class="head">PN</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>1</td>
<td>declare</td>
</tr>
<tr class="row-odd"><td>0</td>
<td>define</td>
</tr>
</tbody>
</table>
<p>Valid linkage names <code>LN</code>, and corresponding <code>L</code> values, are:</p>
<table border="1" class="docutils">
<colgroup>
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">L</th>
<th class="head">LN</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>3</td>
<td>internal</td>
</tr>
<tr class="row-odd"><td>0</td>
<td>external</td>
</tr>
</tbody>
</table>
<p>Currently, only one calling convention <code>C</code> is supported:</p>
<table border="1" class="docutils">
<colgroup>
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">C</th>
<th class="head">Calling Convention</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>0</td>
<td>C calling convention</td>
</tr>
</tbody>
</table>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA = AbbrevIndex(A) &amp;
T = TypeID(TypeOf(T0 ( T1 , ... , TN ))) &amp;
N = NumFuncAddresses
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumFuncAddresses;
TypeOf(&#64;fN) = TypeOf(TypeID(i32));
TypeOfFcn(&#64;fN) = TypeOf(&#64;tT);
if PN == 0:
DefiningFcnIDs += &#64;FN;
++NumDefinedFunctionAddresses;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 7&gt; | count 7;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;3&gt; | &#64;t1 = float;
55:4| 3: &lt;4&gt; | &#64;t2 = double;
57:2| 3: &lt;2&gt; | &#64;t3 = void;
59:0| 3: &lt;21, 0, 2, 1&gt; | &#64;t4 = double (float);
63:0| 3: &lt;21, 0, 0, 0, 1, 0, 2&gt;| &#64;t5 =
| | i32 (i32, float, i32, double);
69:2| 3: &lt;21, 0, 3&gt; | &#64;t6 = void ();
72:4| 0: &lt;65534&gt; | }
76:0| 3: &lt;8, 4, 0, 1, 0&gt; | declare external double &#64;f0(float);
80:6| 3: &lt;8, 5, 0, 1, 0&gt; | declare external
| | i32 &#64;f1(i32, float, i32, double);
85:4| 3: &lt;8, 6, 0, 0, 0&gt; | define external void &#64;f2();
</pre>
<h2 id="constants-blocks"><span id="link-for-constants-block-section"></span>Constants Blocks</h2>
<p>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 <a class="reference internal" href="#link-for-function-blocks-section"><em>function block</em></a>, and must appear
before any instructions in the function block.</p>
<p>Currently, only integer literals, floating point literals, and undefined vector
constants can be defined.</p>
<p>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 <a class="reference internal" href="#link-for-constants-set-type-record"><em>set type
record</em></a>, followed by a sequence of literal
constants. These literal constants all get converted to the type of the
preceding set type record.</p>
<p>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.</p>
<p>To make this more concrete, consider the following example constants block:</p>
<pre class="prettyprint">
106:4| 1: &lt;65535, 11, 2&gt; | constants { // BlockID = 11
116:0| 3: &lt;1, 0&gt; | i32:
118:4| 3: &lt;4, 2&gt; | %c0 = i32 1;
121:0| 3: &lt;4, 4&gt; | %c1 = i32 2;
123:4| 3: &lt;1, 2&gt; | i8:
126:0| 3: &lt;4, 8&gt; | %c2 = i8 4;
128:4| 3: &lt;4, 6&gt; | %c3 = i8 3;
131:0| 3: &lt;1, 1&gt; | float:
133:4| 3: &lt;6, 1065353216&gt; | %c4 = float 1;
139:6| 0: &lt;65534&gt; | }
</pre>
<h3 id="set-type-record"><span id="link-for-constants-set-type-record"></span>Set Type Record</h3>
<p>The <em>set type</em> record defines the type to use for the (immediately) succeeding
literals.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
T: &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;1, TT&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The <em>set type</em> record defines type <code>T</code> to be used to type the (immediately)
succeeding literals. <code>T</code> must be a non-void primitive value type or a vector
type.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
TT == TypeID(T)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
ConstantsSetType = T;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
106:4| 1: &lt;65535, 11, 2&gt; | constants { // BlockID = 11
116:0| 3: &lt;1, 0&gt; | i32:
118:4| 3: &lt;4, 2&gt; | %c0 = i32 1;
121:0| 3: &lt;4, 4&gt; | %c1 = i32 2;
123:4| 3: &lt;1, 2&gt; | i8:
126:0| 3: &lt;4, 8&gt; | %c2 = i8 4;
128:4| 3: &lt;4, 6&gt; | %c3 = i8 3;
131:0| 3: &lt;1, 1&gt; | float:
133:4| 3: &lt;6, 1065353216&gt; | %c4 = float 1;
139:6| 0: &lt;65534&gt; | }
</pre>
<h3 id="undefined-literal"><span id="link-for-undefined-literal"></span>Undefined Literal</h3>
<p>The <em>undefined</em> literal record creates an undefined literal for the type <em>T</em>
defined by the preceding <em>set type</em> record.</p>
<p>Note: See <a class="reference internal" href="#link-for-insert-element-instruction-section"><em>insert element
instruction</em></a> for an example of how
you would use the undefined literal with vector types.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
%cN = T undef; &lt;50&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;3&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The <em>undefined</em> literal record creates an undefined literal constant <code>%cN</code> for
type <code>T</code>. <code>T</code> must be the type defined by the preceding <em>set type</em> record,
and be a primitive value type or a vector type.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
N == NumFcnConsts &amp;
T == ConstantsSetType &amp;
IsPrimitive(T) or IsVector(T)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumFcnConsts;
TypeOf(%cN) = T;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 5&gt; | count 5;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;3&gt; | &#64;t1 = float;
55:4| 3: &lt;2&gt; | &#64;t2 = void;
57:2| 3: &lt;12, 4, 0&gt; | &#64;t3 = &lt;4 x i32&gt;;
60:4| 3: &lt;21, 0, 2&gt; | &#64;t4 = void ();
63:6| 0: &lt;65534&gt; | }
...
106:4| 1: &lt;65535, 11, 2&gt; | constants { // BlockID = 11
116:0| 3: &lt;1, 0&gt; | i32:
118:4| 3: &lt;3&gt; | %c0 = i32 undef;
120:2| 3: &lt;4, 2&gt; | %c1 = i32 1;
122:6| 3: &lt;1, 3&gt; | &lt;4 x i32&gt;:
125:2| 3: &lt;3&gt; | %c2 = &lt;4 x i32&gt; undef;
127:0| 3: &lt;1, 1&gt; | float:
129:4| 3: &lt;3&gt; | %c3 = float undef;
131:2| 0: &lt;65534&gt; | }
</pre>
<h3 id="integer-literal"><span id="link-for-integer-literal"></span>Integer Literal</h3>
<p>The <em>integer literal</em> record creates an integer literal for the integer type <em>T</em>
defined by the preceding <em>set type</em> record.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
%cN = T V; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;4, VV&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The <em>integer literal</em> record creates an integer literal constant <code>%cN</code> for
type <code>T</code>. <code>T</code> must be the type defined by the preceding <em>set type</em> record,
and an integer type. The literal <code>V</code> can be signed, but must be definable by
type <code>T</code>.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
N == NumFcnConsts &amp;
T == ConstantsSetType &amp;
VV == SignRotate(V) &amp;
IsInteger(T)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
TypeOf(%cN) = T;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 7&gt; | count 7;
50:4| 3: &lt;7, 8&gt; | &#64;t0 = i8;
53:0| 3: &lt;7, 16&gt; | &#64;t1 = i16;
55:4| 3: &lt;7, 32&gt; | &#64;t2 = i32;
58:6| 3: &lt;7, 64&gt; | &#64;t3 = i64;
62:0| 3: &lt;7, 1&gt; | &#64;t4 = i1;
64:4| 3: &lt;2&gt; | &#64;t5 = void;
66:2| 3: &lt;21, 0, 5&gt; | &#64;t6 = void ();
69:4| 0: &lt;65534&gt; | }
...
114:4| 1: &lt;65535, 11, 2&gt; | constants { // BlockID = 11
124:0| 3: &lt;1, 0&gt; | i8:
126:4| 3: &lt;4, 2&gt; | %c0 = i8 1;
129:0| 3: &lt;4, 4&gt; | %c1 = i8 2;
131:4| 3: &lt;1, 1&gt; | i16:
134:0| 3: &lt;4, 6&gt; | %c2 = i16 3;
136:4| 3: &lt;4, 8&gt; | %c3 = i16 4;
139:0| 3: &lt;1, 2&gt; | i32:
141:4| 3: &lt;4, 10&gt; | %c4 = i32 5;
144:0| 3: &lt;4, 12&gt; | %c5 = i32 6;
146:4| 3: &lt;1, 3&gt; | i64:
149:0| 3: &lt;4, 3&gt; | %c6 = i64 -1;
151:4| 3: &lt;4, 5&gt; | %c7 = i64 -2;
154:0| 3: &lt;1, 4&gt; | i1:
156:4| 3: &lt;4, 3&gt; | %c8 = i1 1;
159:0| 3: &lt;4, 0&gt; | %c9 = i1 0;
161:4| 0: &lt;65534&gt; | }
</pre>
<h3 id="floating-point-literal">Floating Point Literal</h3>
<p>The <em>floating point literal</em> record creates a floating point literal for the
floating point type <em>T</em> defined by the preceding <em>set type</em> record.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
%cN = T V; &lt;A&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;6, VV&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The <em>floating point literal</em> record creates a floating point literal constant
<code>%cN</code> for type <code>T</code>. <code>T</code> must the type type defined by the preceding <em>set
type</em> record, and be a floating point type. The literal <code>V</code> is the floating
value to be defined. The value <code>VV</code> if the corresponding IEEE unsigned integer
that defines value <code>V</code>. That is, the literal <code>VV</code> must be a valid IEEE 754
32-bit (unsigned integer) value if <code>T</code> is <code>float</code>, and a valid IEEE 754
64-bit (unsigned integer) value if <code>T</code> is <code>double</code>.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
N == NumFcnConsts
T == ConstantsSetType
IsFloat(T)
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
TypeOf(%cN) = T;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;3&gt; | &#64;t0 = float;
52:2| 3: &lt;4&gt; | &#64;t1 = double;
54:0| 3: &lt;2&gt; | &#64;t2 = void;
55:6| 3: &lt;21, 0, 2&gt; | &#64;t3 = void ();
59:0| 0: &lt;65534&gt; | }
...
102:4| 1: &lt;65535, 11, 2&gt; | constants { // BlockID = 11
112:0| 3: &lt;1, 0&gt; | float:
114:4| 3: &lt;6, 0&gt; | %c0 = float 0;
117:0| 3: &lt;6, 1065353216&gt; | %c1 = float 1;
123:2| 3: &lt;6, 1088421888&gt; | %c2 = float 7;
130:2| 3: &lt;6, 1090519040&gt; | %c3 = float 8;
137:2| 3: &lt;3&gt; | %c4 = float undef;
139:0| 3: &lt;6, 2143289344&gt; | %c5 = float nan;
146:0| 3: &lt;6, 2139095040&gt; | %c6 = float inf;
153:0| 3: &lt;6, 4286578688&gt; | %c7 = float -inf;
160:0| 3: &lt;1, 1&gt; | double:
162:4| 3: &lt;6, | %c8 = double 1;
| 4607182418800017408&gt; |
174:0| 3: &lt;6, 0&gt; | %c9 = double 0;
176:4| 3: &lt;6, | %c10 = double 5;
| 4617315517961601024&gt; |
188:0| 3: &lt;6, | %c11 = double 6;
| 4618441417868443648&gt; |
199:4| 3: &lt;6, | %c12 = double nan;
| 9221120237041090560&gt; |
211:0| 3: &lt;6, | %c13 = double inf;
| 9218868437227405312&gt; |
222:4| 3: &lt;6, | %c14 = double -inf;
| 18442240474082181120&gt;|
234:0| 0: &lt;65534&gt; | }
</pre>
<h2 id="function-blocks"><span id="link-for-function-blocks-section"></span>Function Blocks</h2>
<p>A function block defines the implementation of a defined <a class="reference internal" href="#link-for-function-address-section"><em>function
address</em></a>. 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.</p>
<p>A function implementation contains a list of basic blocks, forming the control
flow graph. Each <em>basic block</em> contains a list of instructions, and ends with a
<a class="reference internal" href="#link-for-terminator-instruction-section"><em>terminator instruction</em></a>
(e.g. branch).</p>
<p>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.</p>
<p>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&#8217;t be any branches to the entry block of a
function). Because the entry block has no predecessors, it also can&#8217;t have any
<a class="reference internal" href="#link-for-phi-instruction-section"><em>phi</em></a> instructions.</p>
<p>The parameters are implied by the type of the corresponding function
address. One parameter is defined for each argument of the function <a class="reference internal" href="#link-for-function-type"><em>type
signature</em></a> of the corresponding <a class="reference internal" href="#link-for-function-address-section"><em>function
address</em></a>.</p>
<p>The number of basic blocks is defined by the <a class="reference internal" href="#link-for-basic-blocks-count"><em>count
record</em></a>. Each <a class="reference internal" href="#link-for-terminator-instruction-section"><em>terminator
instruction</em></a> 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 <code>%bN</code>, where <code>N</code> corresponds to the position of the basic block
within the function block.</p>
<p>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.</p>
<p>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.</p>
<p>Operands of instructions are defined using an <a class="reference internal" href="#link-for-absolute-index-section"><em>absolute
index</em></a>. 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.</p>
<p>To save space in the encoded bitcode file, most operands are encoded using a
<a class="reference internal" href="#link-for-relative-index"><em>relative index</em></a> value, rather than
<a class="reference internal" href="#link-for-absolute-index-section"><em>absolute</em></a>. 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.</p>
<p>Note that instructions that can appear in a function block are defined in
sections <a class="reference internal" href="#link-for-terminator-instruction-section"><em>Terminator Instructions</em></a>,
<a class="reference internal" href="#link-for-integer-binary-instructions"><em>Integer Binary Instructions</em></a>,
<a class="reference internal" href="#link-for-floating-point-binary-instructions"><em>Floating Point Binary Instructions</em></a>,
<a class="reference internal" href="#link-for-memory-creation-and-access-instructions"><em>Memory Creation and Access Instructions</em></a>,
<a class="reference internal" href="#link-for-conversion-instructions"><em>Conversion Instructions</em></a>, <a class="reference internal" href="#link-for-compare-instructions"><em>Comparison Instructions</em></a>,
<a class="reference internal" href="#link-for-vector-instructions"><em>Vector Instructions</em></a>, and
<a class="reference internal" href="#link-for-other-pnaclasm-instructions"><em>Other Instructions</em></a>.</p>
<p>The following subsections define the remaining records that can appear in a
function block.</p>
<h3 id="function-enter">Function Enter</h3>
<p>PNaClAsm defines a function enter block construct. The corresponding record is
simply an <a class="reference internal" href="#link-for-enter-block-record-section"><em>enter block</em></a> record, with
BlockID value <code>12</code>. All context about the defining address is implicit by the
position of the function block, and the corresponding defining <a class="reference internal" href="#link-for-function-address-section"><em>function
address</em></a>. To improve readability, PNaClAsm
includes the function signature into the syntax rule.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
function TR &#64;fN ( T0 %p0, ... , TM %pM ) { &lt;B&gt;
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
1: &lt;65535, 12, B&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p><code>B</code> is the number of bits reserved for abbreviations in the block. If it is
omitted, 2 is assumed. See <a class="reference internal" href="#link-for-enter-block-record-section"><em>enter</em></a>
block records for more details.</p>
<p>The value of <code>N</code> corresponds to the positional index of the corresponding
defining function address this block is associated with. <code>M</code> is the number of
defined parameters (minus one) in the function heading.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
N == NumFcnImpls &amp;
&#64;fN in DefiningFcnIDs &amp;
TypeOfFcn(&#64;fN) == TypeOf(TypeID(TR (T0, ... , TM)))
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumFcnImpls;
EnclosingFcnID = &#64;fN;
NumBasicBlocks = 0;
ExpectedBlocks = 0;
NumParams = M;
for I in [0..M]:
TypeOf(%pI) = TypeOf(TypeID(TI));
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
40:0| 1: &lt;65535, 17, 2&gt; | types { // BlockID = 17
48:0| 3: &lt;1, 4&gt; | count 4;
50:4| 3: &lt;7, 32&gt; | &#64;t0 = i32;
53:6| 3: &lt;2&gt; | &#64;t1 = void;
55:4| 3: &lt;21, 0, 1&gt; | &#64;t2 = void ();
58:6| 3: &lt;21, 0, 0, 0&gt; | &#64;t3 = i32 (i32);
62:6| 0: &lt;65534&gt; | }
...
104:0| 1: &lt;65535, 12, 2&gt; | function void &#64;f0() {
| | // BlockID = 12
112:0| 3: &lt;1, 1&gt; | blocks 1;
| | %b0:
114:4| 3: &lt;10&gt; | ret void;
116:2| 0: &lt;65534&gt; | }
120:0| 1: &lt;65535, 12, 2&gt; | function i32 &#64;f1(i32 %p0) {
| | // BlockID = 12
128:0| 3: &lt;1, 1&gt; | blocks 1;
| | %b0:
130:4| 3: &lt;10, 1&gt; | ret i32 %p0;
133:0| 0: &lt;65534&gt; | }
</pre>
<h3 id="link-for-basic-blocks-count"><span id="id3"></span>Count Record</h3>
<p>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.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
blocks: N; &lt;A&gt;
%b0:
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;1, N&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The count record defines the number <code>N</code> of basic blocks in the implemented
function.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
ExpectedBasicBlocks == N &amp;
NumBasicBlocks == 0
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
104:0| 1: &lt;65535, 12, 2&gt; | function void &#64;f0() {
| | // BlockID = 12
112:0| 3: &lt;1, 1&gt; | blocks 1;
| | %b0:
114:4| 3: &lt;10&gt; | ret void;
116:2| 0: &lt;65534&gt; | }
120:0| 1: &lt;65535, 12, 2&gt; | function i32 &#64;f1(i32 %p0) {
| | // BlockID = 12
128:0| 3: &lt;1, 1&gt; | blocks 1;
| | %b0:
130:4| 3: &lt;10, 1&gt; | ret i32 %p0;
133:0| 0: &lt;65534&gt; | }
</pre>
<h2 id="terminator-instructions"><span id="link-for-terminator-instruction-section"></span>Terminator Instructions</h2>
<p>Terminator instructions are instructions that appear in a <a class="reference internal" href="#link-for-function-blocks-section"><em>function
block</em></a>, 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 <a class="reference internal" href="#link-for-basic-blocks-count"><em>count
record</em></a>.</p>
<p>Note that any branch instruction to label <code>%bN</code>, where <code>N &gt;=
ExpectedBasicBlocks</code>, is illegal. For ease of readability, this constraint
hasn&#8217;t been put on branch instructions. Rather it is only implied.</p>
<p>In addition, it must be the case that <code>NumBasicBlocks &lt; ExpectedBasicBlocks</code>,
and will not be listed as a constraint. Further, if <code>B = NumBasicBlocks + 1</code>
is the number associated with the next basic block. Label <cite>%bB:</cite> only appears
if:</p>
<pre class="prettyprint">
B &lt; ExpectedBasicBlocks
</pre>
<p>That is, the label is omitted only if this terminator instruction is the last
instruction in the function block.</p>
<h3 id="return-void-instruction">Return Void Instruction</h3>
<p>The return void instruction is used to return control from a function back to
the caller, without returning any value.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">
ret void; &lt;A&gt;
%bB:
</pre>
<p><strong>Record</strong>:</p>
<pre class="prettyprint">
AA: &lt;10&gt;
</pre>
<p><strong>Semantics</strong>:</p>
<p>The return void instruction returns control to the calling function.</p>
<p><strong>Constraints</strong>:</p>
<pre class="prettyprint">
AA == AbbrevIndex(A) &amp;
B == NumBasicBlocks + 1 &amp;
ReturnType(TypeOf(EnclosingFcnID)) == void
</pre>
<p><strong>Updates</strong>:</p>
<pre class="prettyprint">
++NumBasicBlocks;
</pre>
<p><strong>Examples</strong>:</p>
<pre class="prettyprint">
104:0| 1: &lt;65535, 12, 2&gt; | function void &#64;f0() {
| | // BlockID = 12
112:0| 3: &lt;1, 1&gt; | blocks 1;
| | %b0:
114:4| 3: &lt;10&gt; | ret void;
116:2| 0: &lt;65534&gt; | }
</pre>
<h3 id="return-value-instruction">Return Value Instruction</h3>
<p>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.</p>
<p><strong>Syntax</strong>:</p>
<pre class="prettyprint">