docs/ReleaseNotes.rst

   1 ======================
   2 LLVM 3.6 Release Notes
   3 ======================
   4
   5 .. contents::
   6     :local:
   7
   8
   9 Introduction
  10 ============
  11
  12 This document contains the release notes for the LLVM Compiler Infrastructure,
  13 release 3.6.  Here we describe the status of LLVM, including major improvements
  14 from the previous release, improvements in various subprojects of LLVM, and
  15 some of the current users of the code.  All LLVM releases may be downloaded
  16 from the `LLVM releases web site <http://llvm.org/releases/>`_.
  17
  18 For more information about LLVM, including information about the latest
  19 release, please check out the `main LLVM web site <http://llvm.org/>`_.  If you
  20 have questions or comments, the `LLVM Developer's Mailing List
  21 <http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev>`_ is a good place to send
  22 them.
  23
  24
  25 Non-comprehensive list of changes in this release
  26 =================================================
  27
  28 .. NOTE
  29    For small 1-3 sentence descriptions, just add an entry at the end of
  30    this list. If your description won't fit comfortably in one bullet
  31    point (e.g. maybe you would like to give an example of the
  32    functionality, or simply have a lot to talk about), see the `NOTE` below
  33    for adding a new subsection.
  34
  35 * Support for AuroraUX has been removed.
  36
  37 * Added support for a `native object file-based bitcode wrapper format
  38   <BitCodeFormat.html#native-object-file>`_.
  39
  40 * Added support for MSVC's ``__vectorcall`` calling convention as
  41   ``x86_vectorcallcc``.
  42
  43 .. NOTE
  44    If you would like to document a larger change, then you can add a
  45    subsection about it right here. You can copy the following boilerplate
  46    and un-indent it (the indentation causes it to be inside this comment).
  47
  48    Special New Feature
  49    -------------------
  50
  51    Makes programs 10x faster by doing Special New Thing.
  52
  53 Prefix data rework
  54 ------------------
  55
  56 The semantics of the ``prefix`` attribute have been changed. Users
  57 that want the previous ``prefix`` semantics should instead use
  58 ``prologue``.  To motivate this change, let's examine the primary
  59 usecases that these attributes aim to serve,
  60
  61   1. Code sanitization metadata (e.g. Clang's undefined behavior
  62      sanitizer)
  63
  64   2. Function hot-patching: Enable the user to insert ``nop`` operations
  65      at the beginning of the function which can later be safely replaced
  66      with a call to some instrumentation facility.
  67
  68   3. Language runtime metadata: Allow a compiler to insert data for
  69      use by the runtime during execution. GHC is one example of a
  70      compiler that needs this functionality for its
  71      tables-next-to-code functionality.
  72
  73 Previously ``prefix`` served cases (1) and (2) quite well by allowing the user
  74 to introduce arbitrary data at the entrypoint but before the function
  75 body. Case (3), however, was poorly handled by this approach as it
  76 required that prefix data was valid executable code.
  77
  78 In this release the concept of prefix data has been redefined to be
  79 data which occurs immediately before the function entrypoint (i.e. the
  80 symbol address). Since prefix data now occurs before the function
  81 entrypoint, there is no need for the data to be valid code.
  82
  83 The previous notion of prefix data now goes under the name "prologue
  84 data" to emphasize its duality with the function epilogue.
  85
  86 The intention here is to handle cases (1) and (2) with prologue data and
  87 case (3) with prefix data. See the language reference for further details
  88 on the semantics of these attributes.
  89
  90 This refactoring arose out of discussions_ with Reid Kleckner in
  91 response to a proposal to introduce the notion of symbol offsets to
  92 enable handling of case (3).
  93
  94 .. _discussions: http://lists.cs.uiuc.edu/pipermail/llvmdev/2014-May/073235.html
  95
  96
  97 Metadata is not a Value
  98 -----------------------
  99
 100 Metadata nodes (``!{...}``) and strings (``!"..."``) are no longer values.
 101 They have no use-lists, no type, cannot RAUW, and cannot be function-local.
 102
 103 Bridges between Value and Metadata
 104 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 105
 106 LLVM intrinsics can reference metadata using the ``metadata`` type, and
 107 metadata nodes can reference constant values.
 108
 109 Function-local metadata is limited to direct arguments to LLVM intrinsics.
 110
 111 Metadata is typeless
 112 ^^^^^^^^^^^^^^^^^^^^
 113
 114 The following old IR:
 115
 116 .. code-block:: llvm
 117
 118     @g = global i32 0
 119
 120     define void @foo(i32 %v) {
 121     entry:
 122       call void @llvm.md(metadata !{i32 %v})
 123       call void @llvm.md(metadata !{i32* @global})
 124       call void @llvm.md(metadata !0)
 125       call void @llvm.md(metadata !{metadata !"string"})
 126       call void @llvm.md(metadata !{metadata !{metadata !1, metadata !"string"}})
 127       ret void, !bar !1, !baz !2
 128     }
 129
 130     declare void @llvm.md(metadata)
 131
 132     !0 = metadata !{metadata !1, metadata !2, metadata !3, metadata !"some string"}
 133     !1 = metadata !{metadata !2, null, metadata !"other", i32* @global, i32 7}
 134     !2 = metadata !{}
 135
 136 should now be written as:
 137
 138 .. code-block:: llvm
 139
 140     @g = global i32 0
 141
 142     define void @foo(i32 %v) {
 143     entry:
 144       call void @llvm.md(metadata i32 %v) ; The only legal place for function-local
 145                                           ; metadata.
 146       call void @llvm.md(metadata i32* @global)
 147       call void @llvm.md(metadata !0)
 148       call void @llvm.md(metadata !{!"string"})
 149       call void @llvm.md(metadata !{!{!1, !"string"}})
 150       ret void, !bar !1, !baz !2
 151     }
 152
 153     declare void @llvm.md(metadata)
 154
 155     !0 = !{!1, !2, !3, !"some string"}
 156     !1 = !{!2, null, !"other", i32* @global, i32 7}
 157     !2 = !{}
 158
 159 Distinct metadata nodes
 160 ^^^^^^^^^^^^^^^^^^^^^^^
 161
 162 Metadata nodes can opt-out of uniquing, using the keyword ``distinct``.
 163 Distinct nodes are still owned by the context, but are stored in a side table,
 164 and not uniqued.
 165
 166 In LLVM 3.5, metadata nodes would drop uniquing if an operand changed to
 167 ``null`` during optimizations.  This is no longer true.  However, if an operand
 168 change causes a uniquing collision, they become ``distinct``.  Unlike LLVM 3.5,
 169 where serializing to assembly or bitcode would re-unique the nodes, they now
 170 remain ``distinct``.
 171
 172 The following IR:
 173
 174 .. code-block:: llvm
 175
 176     !named = !{!0, !1, !2, !3, !4, !5, !6, !7, !8}
 177
 178     !0 = !{}
 179     !1 = !{}
 180     !2 = distinct !{}
 181     !3 = distinct !{}
 182     !4 = !{!0}
 183     !5 = distinct !{!0}
 184     !6 = !{!4, !{}, !5}
 185     !7 = !{!{!0}, !0, !5}
 186     !8 = distinct !{!{!0}, !0, !5}
 187
 188 is equivalent to the following:
 189
 190 .. code-block:: llvm
 191
 192     !named = !{!0, !0, !1, !2, !3, !4, !5, !5, !6}
 193
 194     !0 = !{}
 195     !1 = distinct !{}
 196     !2 = distinct !{}
 197     !3 = !{!0}
 198     !4 = distinct !{!0}
 199     !5 = !{!3, !0, !4}
 200     !6 = distinct !{!3, !0, !4}
 201
 202 Constructing cyclic graphs
 203 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 204
 205 During graph construction, if a metadata node transitively references a forward
 206 declaration, the node itself is considered "unresolved" until the forward
 207 declaration resolves.  An unresolved node can RAUW itself to support uniquing.
 208 Nodes automatically resolve once all their operands have resolved.
 209
 210 However, cyclic graphs prevent the nodes from resolving.  An API client that
 211 constructs a cyclic graph must call ``resolveCycles()`` to resolve nodes in the
 212 cycle.
 213
 214 To save self-references from that burden, self-referencing nodes are implicitly
 215 ``distinct``.  So the following IR:
 216
 217 .. code-block:: llvm
 218
 219     !named = !{!0, !1, !2, !3, !4}
 220
 221     !0 = !{!0}
 222     !1 = !{!1}
 223     !2 = !{!2, !1}
 224     !3 = !{!2, !1}
 225     !4 = !{!2, !1}
 226
 227 is equivalent to:
 228
 229 .. code-block:: llvm
 230
 231     !named = !{!0, !1, !2, !3, !3}
 232
 233     !0 = distinct !{!0}
 234     !1 = distinct !{!1}
 235     !2 = distinct !{!2, !1}
 236     !3 = !{!2, !1}
 237
 238 MDLocation (aka DebugLoc aka DILocation)
 239 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 240
 241 There's a new first-class metadata construct called ``MDLocation`` (to be
 242 followed in subsequent releases by others).  It's used for the locations
 243 referenced by ``!dbg`` metadata attachments.
 244
 245 For example, if an old ``!dbg`` attachment looked like this:
 246
 247 .. code-block:: llvm
 248
 249     define i32 @foo(i32 %a, i32 %b) {
 250     entry:
 251       %add = add i32 %a, %b, !dbg !0
 252       ret %add, !dbg !1
 253     }
 254
 255     !0 = metadata !{i32 10, i32 3, metadata !2, metadata !1)
 256     !1 = metadata !{i32 20, i32 7, metadata !3)
 257     !2 = metadata !{...}
 258     !3 = metadata !{...}
 259
 260 the new attachment looks like this:
 261
 262 .. code-block:: llvm
 263
 264     define i32 @foo(i32 %a, i32 %b) {
 265     entry:
 266       %add = add i32 %a, %b, !dbg !0
 267       ret %add, !dbg !1
 268     }
 269
 270     !0 = !MDLocation(line: 10, column: 3, scope: !2, inlinedAt: !1)
 271     !1 = !MDLocation(line: 20, column: 7, scope: !3)
 272     !2 = !{...}
 273     !3 = !{...}
 274
 275 The fields are named, can be reordered, and have sane defaults if left out
 276 (although ``scope:`` is required).
 277
 278
 279 Alias syntax change
 280 -----------------------
 281
 282 The syntax for aliases is now closer to what is used for global variables
 283
 284 .. code-block:: llvm
 285
 286     @a = weak global ...
 287     @b = weak alias ...
 288
 289 The order of the ``alias`` keyword and the linkage was swapped before.
 290
 291 The old JIT has been removed
 292 ----------------------------
 293
 294 All users should transition to MCJIT.
 295
 296
 297 object::Binary doesn't own the file buffer
 298 -------------------------------------------
 299
 300 It is now just a wrapper, which simplifies using object::Binary with other
 301 users of the underlying file.
 302
 303
 304 IR in object files is now supported
 305 -----------------------------------
 306
 307 Regular object files can contain IR in a section named ``.llvmbc``.
 308
 309
 310 The gold plugin has been rewritten
 311 ----------------------------------
 312
 313 It is now implemented directly on top of lib/Linker instead of ``lib/LTO``.
 314 The API of ``lib/LTO`` is sufficiently different from gold's view of the
 315 linking process that some cases could not be conveniently implemented.
 316
 317 The new implementation is also lazier and has a ``save-temps`` option.
 318
 319
 320 Change in the representation of lazy loaded funcs
 321 -------------------------------------------------
 322
 323 Lazy loaded functions are now represented in a way that ``isDeclaration``
 324 returns the correct answer even before reading the body.
 325
 326
 327 The opt option -std-compile-opts was removed
 328 --------------------------------------------
 329
 330 It was effectively an alias of -O3.
 331
 332
 333 Python 2.7 is now required
 334 --------------------------
 335
 336 This was done to simplify compatibility with python 3.
 337
 338
 339 The leak detector has been removed
 340 ----------------------------------
 341
 342 In practice, tools like asan and valgrind were finding way more bugs than
 343 the old leak detector, so it was removed.
 344
 345
 346 New comdat syntax
 347 -----------------
 348
 349 The syntax of comdats was changed to
 350
 351 .. code-block:: llvm
 352
 353     $c = comdat any
 354     @g = global i32 0, comdat($c)
 355     @c = global i32 0, comdat
 356
 357 The version without the parentheses is a syntactic sugar for a comdat with
 358 the same name as the global.
 359
 360
 361 Added support for Win64 unwind information
 362 ------------------------------------------
 363
 364 LLVM now obeys the `Win64 prologue and epilogue conventions
 365 <https://msdn.microsoft.com/en-us/library/tawsa7cb.aspx>`_ documented by
 366 Microsoft. Unwind information is also emitted into the .xdata section.
 367
 368 As a result of the ABI-required prologue changes, it is now no longer possible
 369 to unwind the stack using a standard frame pointer walk on Win64. Instead,
 370 users should call ``CaptureStackBackTrace``, or implement equivalent
 371 functionality by consulting the unwind tables present in the binary.
 372
 373
 374 Diagnostic infrastructure used by lib/Linker and lib/Bitcode
 375 ------------------------------------------------------------
 376
 377 These libraries now use the diagnostic handler to print errors and warnings.
 378 This provides better error messages and simpler error handling.
 379
 380
 381 The PreserveSource linker mode was removed
 382 ------------------------------------------
 383
 384 It was fairly broken and was removed.
 385
 386 The mode is currently still available in the C API for source
 387 compatibility, but it doesn't have any effect.
 388
 389
 390 Garbage Collection
 391 ------------------
 392 A new experimental mechanism for describing a garbage collection safepoint was
 393 added to LLVM.  The new mechanism was not complete at the point this release
 394 was branched so it is recommended that anyone interested in using this
 395 mechanism track the ongoing development work on tip of tree.  The hope is that
 396 these intrinsics will be ready for general use by 3.7.  Documentation can be
 397 found `here <http://llvm.org/docs/Statepoints.html>`_.
 398
 399 The existing gc.root implementation is still supported and as fully featured
 400 as it ever was.  However, two features from GCStrategy will likely be removed
 401 in the 3.7 release (performCustomLowering and findCustomSafePoints).  If you
 402 have a use case for either, please mention it on llvm-dev so that it can be
 403 considered for future development.
 404
 405 We are expecting to migrate away from gc.root in the 3.8 time frame,
 406 but both mechanisms will be supported in 3.7.
 407
 408
 409 Changes to the MIPS Target
 410 --------------------------
 411
 412 During this release the MIPS target has reached a few major milestones. The
 413 compiler has gained support for MIPS-II and MIPS-III; become ABI-compatible
 414 with GCC for big and little endian O32, N32, and N64; and is now able to
 415 compile the Linux kernel for 32-bit targets. Additionally, LLD now supports
 416 microMIPS for the O32 ABI on little endian targets, and code generation for
 417 microMIPS is almost completely passing the test-suite.
 418
 419
 420 ABI
 421 ^^^
 422
 423 A large number of bugs have been fixed for big-endian MIPS targets using the
 424 N32 and N64 ABI's as well as a small number of bugs affecting other ABI's.
 425 Please note that some of these bugs will still affect LLVM-IR generated by
 426 LLVM 3.5 since correct code generation depends on appropriate usage of the
 427 ``inreg``, ``signext``, and ``zeroext`` attributes on all function arguments
 428 and returns.
 429
 430 There are far too many corrections to provide a complete list but here are a
 431 few notable ones:
 432
 433 * Big-endian N32 and N64 now interlinks successfully with GCC compiled code.
 434   Previously this didn't work for the majority of cases.
 435
 436 * The registers used to return a structure containing a single 128-bit floating
 437   point member on the N32/N64 ABI's have been changed from those specified by
 438   the ABI documentation to match those used by GCC. The documentation specifies
 439   that ``$f0`` and ``$f2`` should be used but GCC has used ``$f0`` and ``$f1``
 440   for many years.
 441
 442 * Returning a zero-byte struct no longer causes arguments to be read from the
 443   wrong registers when using the O32 ABI.
 444
 445 * The exception personality has been changed for 64-bit MIPS targets to
 446   eliminate warnings about relocations in a read-only section.
 447
 448 * Incorrect usage of odd-numbered single-precision floating point registers
 449   has been fixed when the fastcc calling convention is used with 64-bit FPU's
 450   and -mno-odd-spreg.
 451
 452
 453 LLVMLinux
 454 ^^^^^^^^^
 455
 456 It is now possible to compile the Linux kernel. This currently requires a small
 457 number of kernel patches. See the `LLVMLinux project
 458 <http://llvm.linuxfoundation.org/index.php/Main_Page>`_ for details.
 459
 460 * Added -mabicalls and -mno-abicalls. The implementation may not be complete
 461   but works sufficiently well for the Linux kernel.
 462
 463 * Fixed multiple compatibility issues between LLVM's inline assembly support
 464   and GCC's.
 465
 466 * Added support for a number of directives used by Linux to the Integrated
 467   Assembler.
 468
 469
 470 Miscellaneous
 471 ^^^^^^^^^^^^^
 472
 473 * Attempting to disassemble l[wd]c[23], s[wd]c[23], cache, and pref no longer
 474   triggers an assertion.
 475
 476 * Added -muclibc and -mglibc to support toolchains that provide both uClibC and
 477   GLibC.
 478
 479 * __SIZEOF_INT128__ is no longer defined for 64-bit targets since 128-bit
 480   integers do not work at this time for this target.
 481
 482 * Using $t4-$t7 with the N32 and N64 ABI is deprecated when ``-fintegrated-as``
 483   is in use and will be removed in LLVM 3.7. These names have never been
 484   supported by the GNU Assembler for these ABI's.
 485
 486
 487 Changes to the PowerPC Target
 488 -----------------------------
 489
 490 There are numerous improvements to the PowerPC target in this release:
 491
 492 * LLVM now generates the Vector-Scalar eXtension (VSX) instructions from
 493   version 2.06 of the Power ISA, for both big- and little-endian targets.
 494
 495 * LLVM now has a POWER8 instruction scheduling description.
 496
 497 * AddressSanitizer (ASan) support is now fully functional.
 498
 499 * Performance of simple atomic accesses has been greatly improved.
 500
 501 * Atomic fences now use light-weight syncs where possible, again providing
 502   significant performance benefit.
 503
 504 * The PowerPC target now supports PIC levels (-fPIC vs. -fpic).
 505
 506 * PPC32 SVR4 now supports small-model PIC.
 507
 508 * Experimental support for the stackmap/patchpoint intrinsics has been added.
 509
 510 * There have been many smaller bug fixes and performance improvements.
 511
 512
 513 Changes to the OCaml bindings
 514 -----------------------------
 515
 516 * The bindings now require OCaml >=4.00.0, ocamlfind,
 517   ctypes >=0.3.0 <0.4 and OUnit 2 if tests are enabled.
 518
 519 * The bindings can now be built using cmake as well as autoconf.
 520
 521 * LLVM 3.5 has, unfortunately, shipped a broken Llvm_executionengine
 522   implementation. In LLVM 3.6, the bindings now fully support MCJIT,
 523   however the interface is reworked from scratch using ctypes
 524   and is not backwards compatible.
 525
 526 * Llvm_linker.Mode was removed following the changes in LLVM.
 527   This breaks the interface of Llvm_linker.
 528
 529 * All combinations of ocamlc/ocamlc -custom/ocamlopt and shared/static
 530   builds of LLVM are now supported.
 531
 532 * Absolute paths are not embedded into the OCaml libraries anymore.
 533   Either OCaml >=4.02.2 must be used, which includes an rpath-like $ORIGIN
 534   mechanism, or META file must be updated for out-of-tree installations;
 535   see r221139.
 536
 537 * As usual, many more functions have been exposed to OCaml.
 538
 539
 540 Go bindings
 541 -----------
 542
 543 * A set of Go bindings based on `gollvm <https://github.com/go-llvm/llvm>`_
 544   was introduced in this release.
 545
 546
 547 External Open Source Projects Using LLVM 3.6
 548 ============================================
 549
 550 An exciting aspect of LLVM is that it is used as an enabling technology for
 551 a lot of other language and tools projects. This section lists some of the
 552 projects that have already been updated to work with LLVM 3.6.
 553
 554
 555 Portable Computing Language (pocl)
 556 ----------------------------------
 557
 558 In addition to producing an easily portable open source OpenCL
 559 implementation, another major goal of `pocl <http://portablecl.org/>`_
 560 is improving performance portability of OpenCL programs with
 561 compiler optimizations, reducing the need for target-dependent manual
 562 optimizations. An important part of pocl is a set of LLVM passes used to
 563 statically parallelize multiple work-items with the kernel compiler, even in
 564 the presence of work-group barriers. This enables static parallelization of
 565 the fine-grained static concurrency in the work groups in multiple ways.
 566
 567
 568 TTA-based Co-design Environment (TCE)
 569 -------------------------------------
 570
 571 `TCE <http://tce.cs.tut.fi/>`_ is a toolset for designing customized
 572 exposed datapath processors based on the Transport triggered
 573 architecture (TTA).
 574
 575 The toolset provides a complete co-design flow from C/C++
 576 programs down to synthesizable VHDL/Verilog and parallel program binaries.
 577 Processor customization points include the register files, function units,
 578 supported operations, and the interconnection network.
 579
 580 TCE uses Clang and LLVM for C/C++/OpenCL C language support, target independent
 581 optimizations and also for parts of code generation. It generates
 582 new LLVM-based code generators "on the fly" for the designed processors and
 583 loads them in to the compiler backend as runtime libraries to avoid
 584 per-target recompilation of larger parts of the compiler chain.
 585
 586
 587 Likely
 588 ------
 589
 590 `Likely <http://www.liblikely.org>`_ is an embeddable just-in-time Lisp for
 591 image recognition and heterogeneous computing. Algorithms are just-in-time
 592 compiled using LLVM's MCJIT infrastructure to execute on single or
 593 multi-threaded CPUs and potentially OpenCL SPIR or CUDA enabled GPUs.
 594 Likely seeks to explore new optimizations for statistical learning
 595 algorithms by moving them from an offline model generation step to the
 596 compile-time evaluation of a function (the learning algorithm) with constant
 597 arguments (the training data).
 598
 599
 600 LDC - the LLVM-based D compiler
 601 -------------------------------
 602
 603 `D <http://dlang.org>`_ is a language with C-like syntax and static typing. It
 604 pragmatically combines efficiency, control, and modeling power, with safety and
 605 programmer productivity. D supports powerful concepts like Compile-Time Function
 606 Execution (CTFE) and Template Meta-Programming, provides an innovative approach
 607 to concurrency and offers many classical paradigms.
 608
 609 `LDC <http://wiki.dlang.org/LDC>`_ uses the frontend from the reference compiler
 610 combined with LLVM as backend to produce efficient native code. LDC targets
 611 x86/x86_64 systems like Linux, OS X, FreeBSD and Windows and also Linux on
 612 PowerPC (32/64 bit). Ports to other architectures like ARM, AArch64 and MIPS64
 613 are underway.
 614
 615
 616 LLVMSharp & ClangSharp
 617 ----------------------
 618
 619 `LLVMSharp <http://www.llvmsharp.org>`_ and
 620 `ClangSharp <http://www.clangsharp.org>`_ are type-safe C# bindings for
 621 Microsoft.NET and Mono that Platform Invoke into the native libraries.
 622 ClangSharp is self-hosted and is used to generated LLVMSharp using the
 623 LLVM-C API.
 624
 625 `LLVMSharp Kaleidoscope Tutorials <http://www.llvmsharp.org/Kaleidoscope/>`_
 626 are instructive examples of writing a compiler in C#, with certain improvements
 627 like using the visitor pattern to generate LLVM IR.
 628
 629 `ClangSharp PInvoke Generator <http://www.clangsharp.org/PInvoke/>`_ is the
 630 self-hosting mechanism for LLVM/ClangSharp and is demonstrative of using
 631 LibClang to generate Platform Invoke (PInvoke) signatures for C APIs.
 632
 633
 634 Additional Information
 635 ======================
 636
 637 A wide variety of additional information is available on the `LLVM web page
 638 <http://llvm.org/>`_, in particular in the `documentation
 639 <http://llvm.org/docs/>`_ section.  The web page also contains versions of the
 640 API documentation which is up-to-date with the Subversion version of the source
 641 code.  You can access versions of these documents specific to this release by
 642 going into the ``llvm/docs/`` directory in the LLVM tree.
 643
 644 If you have any questions or comments about LLVM, please feel free to contact
 645 us via the `mailing lists <http://llvm.org/docs/#maillist>`_.
 646