{{+bindTo:partials.standard_nacl_article}}

PNaCl Bitcode Reference Manual

Introduction

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.

High Level Structure

A PNaCl portable executable (pexe in short) is a single LLVM IR module.

Data Model

The data model for PNaCl bitcode is fixed at little-endian ILP32: pointers are 32 bits in size. 64-bit integer types are also supported natively via the i64 type (for example, a front-end can generate these from the C/C++ type long long).

Floating point support is fixed at IEEE 754 32-bit and 64-bit values (f32 and f64, respectively).

Linkage Types

LLVM LangRef: Linkage Types

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.

Calling Conventions

LLVM LangRef: Calling Conventions

The only calling convention supported by PNaCl bitcode is ccc - the C calling convention.

Visibility Styles

LLVM LangRef: Visibility Styles

PNaCl bitcode does not support visibility styles.

Global Variables

LLVM LangRef: Global Variables

Restrictions on global variables:

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:

  1. An i8 array literal or zeroinitializer:
   [SIZE x i8] c"DATA"
   [SIZE x i8] zeroinitializer
  1. A reference to a GlobalValue (a function or global variable) with an optional 32-bit byte offset added to it (the addend, which may be negative):
   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.

Functions

LLVM LangRef: Functions

The restrictions on linkage types, calling conventions and visibility styles apply to functions. In addition, the following are not supported for functions:

Aliases

LLVM LangRef: Aliases

PNaCl bitcode does not support aliases.

Named Metadata

LLVM LangRef: Named Metadata

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.

Module-Level Inline Assembly

LLVM LangRef: Module-Level Inline Assembly

PNaCl bitcode does not support inline assembly.

Volatile Memory Accesses

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.

Memory Model for Concurrent Operations

LLVM LangRef: Memory Model for Concurrent Operations

See the PNaCl Developer’s Guide for more details.

Fast-Math Flags

LLVM LangRef: Fast-Math Flags

Fast-math mode is not currently supported by the PNaCl bitcode.

Type System

LLVM LangRef: Type System

The LLVM types allowed in PNaCl bitcode are restricted, as follows:

Scalar types

Vector types

The only vector types allowed are:

Array and struct types

Array and struct types are only allowed in global variable initializers.

Pointer types

Only the following pointer types are allowed:

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:

Undefined Values

LLVM LangRef: Undefined Values

undef is only allowed within functions, not in global variable initializers.

Constant Expressions

LLVM LangRef: Constant Expressions

Constant expressions are only allowed in global variable initializers.

Other Values

Metadata Nodes and Metadata Strings

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.

Intrinsic Global Variables

LLVM LangRef: Intrinsic Global Variables

PNaCl bitcode does not support intrinsic global variables.

Errno and errors in arithmetic instructions

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.

Instruction Reference

List of allowed instructions

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:

Only the LLVM instructions listed here are supported by PNaCl bitcode.

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

Intrinsic Functions

LLVM LangRef: Intrinsic Functions

List of allowed intrinsics

The only intrinsics supported by PNaCl bitcode are the following.

  declare i8* @llvm.nacl.read.tp()

Returns a read-only thread pointer. The value is controlled by the embedding sandbox’s runtime.

Setjmp and Longjmp

  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.

Atomic intrinsics

  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.

{{/partials.standard_nacl_article}}