src/native_client_sdk/src/doc/reference/pnacl-bitcode-abi.rst

   1 ==============================
   2 PNaCl Bitcode Reference Manual
   3 ==============================
   4
   5 .. contents::
   6    :local:
   7    :backlinks: none
   8    :depth: 3
   9
  10 Introduction
  11 ============
  12
  13 This document is a reference manual for the PNaCl bitcode format. It describes
  14 the bitcode on a *semantic* level; the physical encoding level will be described
  15 elsewhere. For the purpose of this document, the textual form of LLVM IR is
  16 used to describe instructions and other bitcode constructs.
  17
  18 Since the PNaCl bitcode is based to a large extent on LLVM IR, many sections
  19 in this document point to a relevant section of the LLVM language reference
  20 manual. Only the changes, restrictions and variations specific to PNaCl are
  21 described---full semantic descriptions are not duplicated from the LLVM
  22 reference manual.
  23
  24 High Level Structure
  25 ====================
  26
  27 A PNaCl portable executable (**pexe** in short) is a single LLVM IR module.
  28
  29 Data Model
  30 ----------
  31
  32 The data model for PNaCl bitcode is fixed at little-endian ILP32: pointers are
  33 32 bits in size. 64-bit integer types are also supported natively via the i64
  34 type (for example, a front-end can generate these from the C/C++ type
  35 ``long long``).
  36
  37 Floating point support is fixed at IEEE 754 32-bit and 64-bit values (f32 and
  38 f64, respectively).
  39
  40 .. _bitcode_linkagetypes:
  41
  42 Linkage Types
  43 -------------
  44
  45 `LLVM LangRef: Linkage Types
  46 <http://llvm.org/releases/3.3/docs/LangRef.html#linkage>`_
  47
  48 The linkage types supported by PNaCl bitcode are ``internal`` and ``external``.
  49 A single function in the pexe, named ``_start``, has the linkage type
  50 ``external``. All the other functions and globals have the linkage type
  51 ``internal``.
  52
  53 Calling Conventions
  54 -------------------
  55
  56 `LLVM LangRef: Calling Conventions
  57 <http://llvm.org/releases/3.3/docs/LangRef.html#callingconv>`_
  58
  59 The only calling convention supported by PNaCl bitcode is ``ccc`` - the C
  60 calling convention.
  61
  62 Visibility Styles
  63 -----------------
  64
  65 `LLVM LangRef: Visibility Styles
  66 <http://llvm.org/releases/3.3/docs/LangRef.html#visibility-styles>`_
  67
  68 PNaCl bitcode does not support visibility styles.
  69
  70 .. _bitcode_globalvariables:
  71
  72 Global Variables
  73 ----------------
  74
  75 `LLVM LangRef: Global Variables
  76 <http://llvm.org/releases/3.3/docs/LangRef.html#globalvars>`_
  77
  78 Restrictions on global variables:
  79
  80 * PNaCl bitcode does not support LLVM IR TLS models. See
  81   :ref:`language_support_threading` for more details.
  82 * Restrictions on :ref:`linkage types <bitcode_linkagetypes>`.
  83 * The ``addrspace``, ``section``, ``unnamed_addr`` and
  84   ``externally_initialized`` attributes are not supported.
  85
  86 Every global variable must have an initializer. Each initializer must be
  87 either a *SimpleElement* or a *CompoundElement*, defined as follows.
  88
  89 A *SimpleElement* is one of the following:
  90
  91 1) An i8 array literal or ``zeroinitializer``:
  92
  93 .. naclcode::
  94   :prettyprint: 0
  95
  96      [SIZE x i8] c"DATA"
  97      [SIZE x i8] zeroinitializer
  98
  99 2) A reference to a *GlobalValue* (a function or global variable) with an
 100    optional 32-bit byte offset added to it (the addend, which may be
 101    negative):
 102
 103 .. naclcode::
 104   :prettyprint: 0
 105
 106      ptrtoint (TYPE* @GLOBAL to i32)
 107      add (i32 ptrtoint (TYPE* @GLOBAL to i32), i32 ADDEND)
 108
 109 A *CompoundElement* is a unnamed, packed struct containing more than one
 110 *SimpleElement*.
 111
 112 Functions
 113 ---------
 114
 115 `LLVM LangRef: Functions
 116 <http://llvm.org/releases/3.3/docs/LangRef.html#functionstructure>`_
 117
 118 The restrictions on :ref:`linkage types <bitcode_linkagetypes>`, calling
 119 conventions and visibility styles apply to functions. In addition, the following
 120 are not supported for functions:
 121
 122 * Function attributes (either for the the function itself, its parameters or its
 123   return type).
 124 * Garbage collector name (``gc``).
 125 * Functions with a variable number of arguments (*vararg*).
 126 * Alignment (``align``).
 127
 128 Aliases
 129 -------
 130
 131 `LLVM LangRef: Aliases
 132 <http://llvm.org/releases/3.3/docs/LangRef.html#aliases>`_
 133
 134 PNaCl bitcode does not support aliases.
 135
 136 Named Metadata
 137 --------------
 138
 139 `LLVM LangRef: Named Metadata
 140 <http://llvm.org/releases/3.3/docs/LangRef.html#namedmetadatastructure>`_
 141
 142 While PNaCl bitcode has provisions for debugging metadata, it is not considered
 143 part of the stable ABI. It exists for tool support and should not appear in
 144 distributed pexes.
 145
 146 Other kinds of LLVM metadata are not supported.
 147
 148 Module-Level Inline Assembly
 149 ----------------------------
 150
 151 `LLVM LangRef: Module-Level Inline Assembly
 152 <http://llvm.org/releases/3.3/docs/LangRef.html#moduleasm>`_
 153
 154 PNaCl bitcode does not support inline assembly.
 155
 156 Volatile Memory Accesses
 157 ------------------------
 158
 159 `LLVM LangRef: Volatile Memory Accesses
 160 <http://llvm.org/releases/3.3/docs/LangRef.html#volatile>`_
 161
 162 PNaCl bitcode does not support volatile memory accesses. The
 163 ``volatile`` attribute on loads and stores is not supported. See the
 164 :doc:`pnacl-c-cpp-language-support` for more details.
 165
 166 Memory Model for Concurrent Operations
 167 --------------------------------------
 168
 169 `LLVM LangRef: Memory Model for Concurrent Operations
 170 <http://llvm.org/releases/3.3/docs/LangRef.html#memmodel>`_
 171
 172 See the `PNaCl Developer's Guide <PNaClDeveloperGuide.html>`_ for more
 173 details.
 174
 175 Fast-Math Flags
 176 ---------------
 177
 178 `LLVM LangRef: Fast-Math Flags
 179 <http://llvm.org/releases/3.3/docs/LangRef.html#fastmath>`_
 180
 181 Fast-math mode is not currently supported by the PNaCl bitcode.
 182
 183 Type System
 184 ===========
 185
 186 `LLVM LangRef: Type System
 187 <http://llvm.org/releases/3.3/docs/LangRef.html#typesystem>`_
 188
 189 The LLVM types allowed in PNaCl bitcode are restricted, as follows:
 190
 191 Scalar types
 192 ------------
 193
 194 * The only scalar types allowed are integer, float (32-bit floating point),
 195   double (64-bit floating point) and void.
 196
 197   * The only integer sizes allowed are i1, i8, i16, i32 and i64.
 198   * The only integer sizes allowed for function arguments and function return
 199     values are i32 and i64.
 200
 201 Array and struct types
 202 ----------------------
 203
 204 Array and struct types are only allowed in
 205 :ref:`global variable initializers <bitcode_globalvariables>`.
 206
 207 .. _bitcode_pointertypes:
 208
 209 Pointer types
 210 -------------
 211
 212 Only the following pointer types are allowed:
 213
 214 * Pointers to valid PNaCl bitcode scalar types, as specified above.
 215 * Pointers to functions.
 216
 217 In addition, the address space for all pointers must be 0.
 218
 219 A pointer is *inherent* when it represents the return value of an ``alloca``
 220 instruction, or is an address of a global value.
 221
 222 A pointer is *normalized* if it's either:
 223
 224 * *inherent*
 225 * Is the return value of a ``bitcast`` instruction.
 226 * Is the return value of a ``inttoptr`` instruction.
 227
 228 Undefined Values
 229 ----------------
 230
 231 `LLVM LangRef: Undefined Values
 232 <http://llvm.org/releases/3.3/docs/LangRef.html#undefvalues>`_
 233
 234 ``undef`` is only allowed within functions, not in global variable initializers.
 235
 236 Constant Expressions
 237 --------------------
 238
 239 `LLVM LangRef: Constant Expressions
 240 <http://llvm.org/releases/3.3/docs/LangRef.html#constant-expressions>`_
 241
 242 Constant expressions are only allowed in
 243 :ref:`global variable initializers <bitcode_globalvariables>`.
 244
 245 Other Values
 246 ============
 247
 248 Metadata Nodes and Metadata Strings
 249 -----------------------------------
 250
 251 `LLVM LangRef: Metadata Nodes and Metadata Strings
 252 <http://llvm.org/releases/3.3/docs/LangRef.html#metadata>`_
 253
 254 While PNaCl bitcode has provisions for debugging metadata, it is not considered
 255 part of the stable ABI. It exists for tool support and should not appear in
 256 distributed pexes.
 257
 258 Other kinds of LLVM metadata are not supported.
 259
 260 Intrinsic Global Variables
 261 ==========================
 262
 263 `LLVM LangRef: Intrinsic Global Variables
 264 <http://llvm.org/releases/3.3/docs/LangRef.html#intrinsic-global-variables>`_
 265
 266 PNaCl bitcode does not support intrinsic global variables.
 267
 268 Instruction Reference
 269 =====================
 270
 271 List of allowed instructions
 272 ----------------------------
 273
 274 This is a list of LLVM instructions supported by PNaCl bitcode. Where
 275 applicable, PNaCl-specific restrictions are provided.
 276
 277 .. TODO: explain instructions or link in the future
 278
 279 The following attributes are disallowed for all instructions:
 280
 281 * ``nsw`` and ``nuw``
 282 * ``exact``
 283
 284 Only the LLVM instructions listed here are supported by PNaCl bitcode.
 285
 286 * ``ret``
 287 * ``br``
 288 * ``switch``
 289
 290   i1 values are disallowed for ``switch``.
 291
 292 * ``add``, ``sub``, ``mul``, ``shl``,  ``udiv``, ``sdiv``, ``urem``, ``srem``,
 293   ``lshr``, ``ashr``
 294
 295   These arithmetic operations are disallowed on values of type ``i1``.
 296
 297   Integer division (``udiv``, ``sdiv``, ``urem``, ``srem``) by zero is
 298   guaranteed to trap in PNaCl bitcode.
 299
 300 * ``and``
 301 * ``or``
 302 * ``xor``
 303 * ``fadd``
 304 * ``fsub``
 305 * ``fmul``
 306 * ``fdiv``
 307 * ``frem``
 308 * ``alloca``
 309
 310   See :ref:`alloca instructions <bitcode_allocainst>`.
 311
 312 * ``load``, ``store``
 313
 314   The pointer argument of these instructions must be a *normalized* pointer (see
 315   :ref:`pointer types <bitcode_pointertypes>`). The ``volatile`` and ``atomic``
 316   attributes are not supported. Loads and stores of the type ``i1`` are not
 317   supported.
 318
 319   These instructions must use ``align 1`` on integer memory accesses, ``align 4``
 320   for ``float`` accesses and ``align 8`` for ``double`` accesses.
 321
 322 * ``trunc``
 323 * ``zext``
 324 * ``sext``
 325 * ``fptrunc``
 326 * ``fpext``
 327 * ``fptoui``
 328 * ``fptosi``
 329 * ``uitofp``
 330 * ``sitofp``
 331
 332 * ``ptrtoint``
 333
 334   The pointer argument of a ``ptrtoint`` instruction must be a *normalized*
 335   pointer (see :ref:`pointer types <bitcode_pointertypes>`) and the integer
 336   argument must be an i32.
 337
 338 * ``inttoptr``
 339
 340   The integer argument of a ``inttoptr`` instruction must be an i32.
 341
 342 * ``bitcast``
 343
 344   The pointer argument of a ``bitcast`` instruction must be a *inherent* pointer
 345   (see :ref:`pointer types <bitcode_pointertypes>`).
 346
 347 * ``icmp``
 348 * ``fcmp``
 349 * ``phi``
 350 * ``select``
 351 * ``call``
 352
 353 .. _bitcode_allocainst:
 354
 355 ``alloca``
 356 ----------
 357
 358 The only allowed type for ``alloca`` instructions in PNaCl bitcode is i8. The
 359 size argument must be an i32. For example:
 360
 361 .. naclcode::
 362   :prettyprint: 0
 363
 364     %buf = alloca i8, i32 8, align 4
 365
 366 Intrinsic Functions
 367 ===================
 368
 369 `LLVM LangRef: Intrinsic Functions
 370 <http://llvm.org/releases/3.3/docs/LangRef.html#intrinsics>`_
 371
 372 List of allowed intrinsics
 373 --------------------------
 374
 375 The only intrinsics supported by PNaCl bitcode are the following.
 376
 377 * ``llvm.memcpy``
 378 * ``llvm.memmove``
 379 * ``llvm.memset``
 380
 381   These intrinsics are only supported with an i32 ``len`` argument.
 382
 383 * ``llvm.bswap``
 384
 385   The overloaded ``llvm.bswap`` intrinsic is only supported with the following
 386   argument types: i16, i32, i64 (the types supported by C-style GCC builtins).
 387
 388 * ``llvm.ctlz``
 389 * ``llvm.cttz``
 390 * ``llvm.ctpop``
 391
 392   The overloaded llvm.ctlz, llvm.cttz, and llvm.ctpop intrinsics are only
 393   supported with the i32 and i64 argument types (the types supported by
 394   C-style GCC builtins).
 395
 396 * ``llvm.sqrt``
 397
 398   The overloaded ``llvm.sqrt`` intrinsic is only supported for float
 399   and double arguments types. Unlike the standard LLVM intrinsic,
 400   PNaCl guarantees that llvm.sqrt returns a QNaN for values less than -0.0.
 401
 402 * ``llvm.stacksave``
 403 * ``llvm.stackrestore``
 404
 405   These intrinsics are used to implement language features like scoped automatic
 406   variable sized arrays in C99. ``llvm.stacksave`` returns a value that
 407   represents the current state of the stack. This value may only be used as the
 408   argument to ``llvm.stackrestore``, which restores the stack to the given
 409   state.
 410
 411 * ``llvm.trap``
 412
 413   This intrinsic is lowered to a target dependent trap instruction, which aborts
 414   execution.
 415
 416 * ``llvm.nacl.read.tp``
 417
 418   See :ref:`thread pointer related intrinsics
 419   <bitcode_threadpointerintrinsics>`.
 420
 421 * ``llvm.nacl.longjmp``
 422 * ``llvm.nacl.setjmp``
 423
 424   See :ref:`Setjmp and Longjmp <bitcode_setjmplongjmp>`.
 425
 426 * ``llvm.nacl.atomic.store``
 427 * ``llvm.nacl.atomic.load``
 428 * ``llvm.nacl.atomic.rmw``
 429 * ``llvm.nacl.atomic.cmpxchg``
 430 * ``llvm.nacl.atomic.fence``
 431 * ``llvm.nacl.atomic.fence.all``
 432 * ``llvm.nacl.atomic.is.lock.free``
 433
 434   See :ref:`atomic intrinsics <bitcode_atomicintrinsics>`.
 435
 436 .. _bitcode_threadpointerintrinsics:
 437
 438 Thread pointer related intrinsics
 439 ---------------------------------
 440
 441 .. naclcode::
 442   :prettyprint: 0
 443
 444     declare i8* @llvm.nacl.read.tp()
 445
 446 Returns a read-only thread pointer. The value is controlled by the embedding
 447 sandbox's runtime.
 448
 449 .. _bitcode_setjmplongjmp:
 450
 451 Setjmp and Longjmp
 452 ------------------
 453
 454 .. naclcode::
 455   :prettyprint: 0
 456
 457     declare void @llvm.nacl.longjmp(i8* %jmpbuf, i32)
 458     declare i32 @llvm.nacl.setjmp(i8* %jmpbuf)
 459
 460 These intrinsics implement the semantics of C11 ``setjmp`` and ``longjmp``. The
 461 ``jmpbuf`` pointer must be 64-bit aligned and point to at least 1024 bytes of
 462 allocated memory.
 463
 464 .. _bitcode_atomicintrinsics:
 465
 466 Atomic intrinsics
 467 -----------------
 468
 469 .. naclcode::
 470   :prettyprint: 0
 471
 472     declare iN @llvm.nacl.atomic.load.<size>(
 473             iN* <source>, i32 <memory_order>)
 474     declare void @llvm.nacl.atomic.store.<size>(
 475             iN <operand>, iN* <destination>, i32 <memory_order>)
 476     declare iN @llvm.nacl.atomic.rmw.<size>(
 477             i32 <computation>, iN* <object>, iN <operand>, i32 <memory_order>)
 478     declare iN @llvm.nacl.atomic.cmpxchg.<size>(
 479             iN* <object>, iN <expected>, iN <desired>,
 480             i32 <memory_order_success>, i32 <memory_order_failure>)
 481     declare void @llvm.nacl.atomic.fence(i32 <memory_order>)
 482     declare void @llvm.nacl.atomic.fence.all()
 483
 484 Each of these intrinsics is overloaded on the ``iN`` argument, which is
 485 reflected through ``<size>`` in the overload's name. Integral types of
 486 8, 16, 32 and 64-bit width are supported for these arguments.
 487
 488 The ``@llvm.nacl.atomic.rmw`` intrinsic implements the following
 489 read-modify-write operations, from the general and arithmetic sections
 490 of the C11/C++11 standards:
 491
 492  - ``add``
 493  - ``sub``
 494  - ``or``
 495  - ``and``
 496  - ``xor``
 497  - ``exchange``
 498
 499 For all of these read-modify-write operations, the returned value is
 500 that at ``object`` before the computation. The ``computation`` argument
 501 must be a compile-time constant.
 502
 503 All atomic intrinsics also support C11/C++11 memory orderings, which
 504 must be compile-time constants.
 505
 506 Integer values for these computations and memory orderings are defined
 507 in ``"llvm/IR/NaClAtomicIntrinsics.h"``.
 508
 509 The ``@llvm.nacl.atomic.fence.all`` intrinsic is equivalent to the
 510 ``@llvm.nacl.atomic.fence`` intrinsic with sequentially consistent
 511 ordering and compiler barriers preventing most non-atomic memory
 512 accesses from reordering around it.
 513
 514 .. Note::
 515   :class: note
 516
 517     These intrinsics allow PNaCl to support C11/C++11 style atomic
 518     operations as well as some legacy GCC-style ``__sync_*`` builtins
 519     while remaining stable as the LLVM codebase changes. The user isn't
 520     expected to use these intrinsics directly.
 521
 522 .. naclcode::
 523   :prettyprint: 0
 524
 525     declare i1 @llvm.nacl.atomic.is.lock.free(i32 <byte_size>, i8* <address>)
 526
 527 The ``llvm.nacl.atomic.is.lock.free`` intrinsic is designed to
 528 determine at translation time whether atomic operations of a certain
 529 ``byte_size`` (a compile-time constant), at a particular ``address``,
 530 are lock-free or not. This reflects the C11 ``atomic_is_lock_free``
 531 function from header ``<stdatomic.h>`` and the C++11 ``is_lock_free``
 532 member function in header ``<atomic>``. It can be used through the
 533 ``__nacl_atomic_is_lock_free`` builtin.