{{+bindTo:partials.standard_nacl_article}}
NOTE:
Deprecation of the technologies described here has been announced
for platforms other than ChromeOS.
Please visit our
migration guide
for details.
This document is a reference manual for the PNaCl bitcode format. It describes the bitcode on a semantic level; the physical encoding level will be described elsewhere. For the purpose of this document, the textual form of LLVM IR is used to describe instructions and other bitcode constructs.
Since the PNaCl bitcode is based to a large extent on LLVM IR as of version 3.3, many sections in this document point to a relevant section of the LLVM language reference manual. Only the changes, restrictions and variations specific to PNaCl are described—full semantic descriptions are not duplicated from the LLVM reference manual.
A PNaCl portable executable (pexe in short) is a single LLVM IR module.
The data model for PNaCl bitcode is fixed at little-endian ILP32: pointers are
32 bits in size. 64-bit integer types are also supported natively via the i64
type (for example, a front-end can generate these from the C/C++ type
long long
).
Floating point support is fixed at IEEE 754 32-bit and 64-bit values (f32 and f64, respectively).
The linkage types supported by PNaCl bitcode are internal
and external
.
A single function in the pexe, named _start
, has the linkage type
external
. All the other functions and globals have the linkage type
internal
.
LLVM LangRef: Calling Conventions
The only calling convention supported by PNaCl bitcode is ccc
- the C
calling convention.
LLVM LangRef: Visibility Styles
PNaCl bitcode does not support visibility styles.
LLVM LangRef: Global Variables
Restrictions on global variables:
addrspace
, section
, unnamed_addr
and
externally_initialized
attributes are not supported.Every global variable must have an initializer. Each initializer must be either a SimpleElement or a CompoundElement, defined as follows.
A SimpleElement is one of the following:
zeroinitializer
:[SIZE x i8] c"DATA" [SIZE x i8] zeroinitializer
ptrtoint (TYPE* @GLOBAL to i32) add (i32 ptrtoint (TYPE* @GLOBAL to i32), i32 ADDEND)
A CompoundElement is a unnamed, packed struct containing more than one SimpleElement.
The restrictions on linkage types, calling conventions and visibility styles apply to functions. In addition, the following are not supported for functions:
gc
).align
).PNaCl bitcode does not support aliases.
While PNaCl bitcode has provisions for debugging metadata, it is not considered part of the stable ABI. It exists for tool support and should not appear in distributed pexes.
Other kinds of LLVM metadata are not supported.
LLVM LangRef: Module-Level Inline Assembly
PNaCl bitcode does not support inline assembly.
LLVM LangRef: Volatile Memory Accesses
PNaCl bitcode does not support volatile memory accesses. The
volatile
attribute on loads and stores is not supported. See the
PNaCl C/C++ Language Support for more details.
LLVM LangRef: Memory Model for Concurrent Operations
See the PNaCl C/C++ Language Support for details.
Fast-math mode is not currently supported by the PNaCl bitcode.
The LLVM types allowed in PNaCl bitcode are restricted, as follows:
The only scalar types allowed are integer, float (32-bit floating point), double (64-bit floating point) and void.
The only vector types allowed are:
Array and struct types are only allowed in global variable initializers.
Only the following pointer types are allowed:
i1
.<? x i1>
.In addition, the address space for all pointers must be 0.
A pointer is inherent when it represents the return value of an alloca
instruction, or is an address of a global value.
A pointer is normalized if it’s either:
bitcast
instruction.inttoptr
instruction.LLVM LangRef: Undefined Values
undef
is only allowed within functions, not in global variable initializers.
LLVM LangRef: Constant Expressions
Constant expressions are only allowed in global variable initializers.
LLVM LangRef: Metadata Nodes and Metadata Strings
While PNaCl bitcode has provisions for debugging metadata, it is not considered part of the stable ABI. It exists for tool support and should not appear in distributed pexes.
Other kinds of LLVM metadata are not supported.
LLVM LangRef: Intrinsic Global Variables
PNaCl bitcode does not support intrinsic global variables.
Some arithmetic instructions and intrinsics have the similar semantics to
libc math functions, but differ in the treatment of errno
. While the
libc functions may set errno
for domain errors, the instructions and
intrinsics do not. This is because the variable errno
is not special
and is not required to be part of the program.
This is a list of LLVM instructions supported by PNaCl bitcode. Where applicable, PNaCl-specific restrictions are provided.
The following attributes are disallowed for all instructions:
nsw
and nuw
exact
Only the LLVM instructions listed here are supported by PNaCl bitcode.
ret
br
switch
i1 values are disallowed for switch
.
add
, sub
, mul
, shl
, udiv
, sdiv
, urem
, srem
,
lshr
, ashr
These arithmetic operations are disallowed on values of type i1
.
Integer division (udiv
, sdiv
, urem
, srem
) by zero is
guaranteed to trap in PNaCl bitcode.
and
or
xor
fadd
fsub
fmul
fdiv
frem
The frem instruction has the semantics of the libc fmod function for
computing the floating point remainder. If the numerator is infinity, or
denominator is zero, or either are NaN, then the result is NaN.
Unlike the libc fmod function, this does not set errno
when the
result is NaN (see the instructions and errno
section).
alloca
See alloca instructions.
load
, store
The pointer argument of these instructions must be a normalized pointer (see
pointer types). The volatile
and atomic
attributes are not supported. Loads and stores of the type i1
and <? x
i1>
are not supported.
These instructions must follow the following alignment restrictions:
align 1
.float
memory accesses: align 1
or align 4
.double
memory accesses: align 1
or align 8
.<4 x i32>
must be align 4
.trunc
zext
sext
fptrunc
fpext
fptoui
fptosi
uitofp
sitofp
ptrtoint
The pointer argument of a ptrtoint
instruction must be a normalized
pointer (see pointer types) and the integer
argument must be an i32.
inttoptr
The integer argument of a inttoptr
instruction must be an i32.
bitcast
The pointer argument of a bitcast
instruction must be a inherent pointer
(see pointer types).
icmp
fcmp
phi
select
call
unreachable
insertelement
extractelement
alloca
The only allowed type for alloca
instructions in PNaCl bitcode is i8. The
size argument must be an i32. For example:
%buf = alloca i8, i32 8, align 4
LLVM LangRef: Intrinsic Functions
The only intrinsics supported by PNaCl bitcode are the following.
llvm.memcpy
llvm.memmove
llvm.memset
These intrinsics are only supported with an i32 len
argument.
llvm.bswap
The overloaded llvm.bswap
intrinsic is only supported with the following
argument types: i16, i32, i64 (the types supported by C-style GCC builtins).
llvm.ctlz
llvm.cttz
llvm.ctpop
The overloaded llvm.ctlz
, llvm.cttz
, and llvm.ctpop
intrinsics
are only supported with the i32 and i64 argument types (the types
supported by C-style GCC builtins).
llvm.fabs
The overloaded llvm.fabs
intrinsic is supported for float, double and
<4 x float>
argument types. It returns the absolute value of
the argument. Some notable points: it returns +0.0
when given -0.0
,
+inf
when given -inf
, and a positive NaN
when given any
signed NaN
.
NOTE: This intrinsic was introduced in the pepper_42 SDK.
llvm.sqrt
The overloaded llvm.sqrt
intrinsic is only supported for float
and double arguments types. This has the same semantics as the libc
sqrt function, returning NaN
for values less than -0.0
.
However, this does not set errno
when the result is NaN (see the
instructions and errno section).
llvm.stacksave
llvm.stackrestore
These intrinsics are used to implement language features like scoped automatic
variable sized arrays in C99. llvm.stacksave
returns a value that
represents the current state of the stack. This value may only be used as the
argument to llvm.stackrestore
, which restores the stack to the given
state.
llvm.trap
This intrinsic is lowered to a target dependent trap instruction, which aborts execution.
llvm.nacl.read.tp
llvm.nacl.longjmp
llvm.nacl.setjmp
See Setjmp and Longjmp.
llvm.nacl.atomic.store
llvm.nacl.atomic.load
llvm.nacl.atomic.rmw
llvm.nacl.atomic.cmpxchg
llvm.nacl.atomic.fence
llvm.nacl.atomic.fence.all
llvm.nacl.atomic.is.lock.free
See atomic intrinsics.
declare i8* @llvm.nacl.read.tp()
Returns a read-only thread pointer. The value is controlled by the embedding sandbox’s runtime.
declare void @llvm.nacl.longjmp(i8* %jmpbuf, i32) declare i32 @llvm.nacl.setjmp(i8* %jmpbuf)
These intrinsics implement the semantics of C11 setjmp
and longjmp
. The
jmpbuf
pointer must be 64-bit aligned and point to at least 1024 bytes of
allocated memory.
declare iN @llvm.nacl.atomic.load.<size>( iN* <source>, i32 <memory_order>) declare void @llvm.nacl.atomic.store.<size>( iN <operand>, iN* <destination>, i32 <memory_order>) declare iN @llvm.nacl.atomic.rmw.<size>( i32 <computation>, iN* <object>, iN <operand>, i32 <memory_order>) declare iN @llvm.nacl.atomic.cmpxchg.<size>( iN* <object>, iN <expected>, iN <desired>, i32 <memory_order_success>, i32 <memory_order_failure>) declare void @llvm.nacl.atomic.fence(i32 <memory_order>) declare void @llvm.nacl.atomic.fence.all()
Each of these intrinsics is overloaded on the iN
argument, which is
reflected through <size>
in the overload’s name. Integral types of
8, 16, 32 and 64-bit width are supported for these arguments.
The @llvm.nacl.atomic.rmw
intrinsic implements the following
read-modify-write operations, from the general and arithmetic sections
of the C11/C++11 standards:
add
sub
or
and
xor
exchange
For all of these read-modify-write operations, the returned value is
that at object
before the computation. The computation
argument
must be a compile-time constant.
All atomic intrinsics also support C11/C++11 memory orderings, which must be compile-time constants.
Integer values for these computations and memory orderings are defined
in "llvm/IR/NaClAtomicIntrinsics.h"
.
The @llvm.nacl.atomic.fence.all
intrinsic is equivalent to the
@llvm.nacl.atomic.fence
intrinsic with sequentially consistent
ordering and compiler barriers preventing most non-atomic memory
accesses from reordering around it.
declare i1 @llvm.nacl.atomic.is.lock.free(i32 <byte_size>, i8* <address>)
The llvm.nacl.atomic.is.lock.free
intrinsic is designed to
determine at translation time whether atomic operations of a certain
byte_size
(a compile-time constant), at a particular address
,
are lock-free or not. This reflects the C11 atomic_is_lock_free
function from header <stdatomic.h>
and the C++11 is_lock_free
member function in header <atomic>
. It can be used through the
__nacl_atomic_is_lock_free
builtin.