llvm/docs/ReleaseNotes.rst

========================
LLVM 4.0.0 Release Notes
========================

.. contents::
    :local:

.. warning::
   These are in-progress notes for the upcoming LLVM 4.0.0 release.  You may
   prefer the `LLVM 3.9 Release Notes <http://llvm.org/releases/3.9.0/docs
   /ReleaseNotes.html>`_.


Introduction
============

This document contains the release notes for the LLVM Compiler Infrastructure,
release 4.0.0.  Here we describe the status of LLVM, including major improvements
from the previous release, improvements in various subprojects of LLVM, and
some of the current users of the code.  All LLVM releases may be downloaded
from the `LLVM releases web site <http://llvm.org/releases/>`_.

For more information about LLVM, including information about the latest
release, please check out the `main LLVM web site <http://llvm.org/>`_.  If you
have questions or comments, the `LLVM Developer's Mailing List
<http://lists.llvm.org/mailman/listinfo/llvm-dev>`_ is a good place to send
them.

Non-comprehensive list of changes in this release
=================================================
* The C API functions LLVMAddFunctionAttr, LLVMGetFunctionAttr,
  LLVMRemoveFunctionAttr, LLVMAddAttribute, LLVMRemoveAttribute,
  LLVMGetAttribute, LLVMAddInstrAttribute and
  LLVMRemoveInstrAttribute have been removed.

* The C API enum LLVMAttribute has been deleted.

.. NOTE
   For small 1-3 sentence descriptions, just add an entry at the end of
   this list. If your description won't fit comfortably in one bullet
   point (e.g. maybe you would like to give an example of the
   functionality, or simply have a lot to talk about), see the `NOTE` below
   for adding a new subsection.

* The definition and uses of LLVM_ATRIBUTE_UNUSED_RESULT in the LLVM source
  were replaced with LLVM_NODISCARD, which matches the C++17 [[nodiscard]]
  semantics rather than gcc's __attribute__((warn_unused_result)).

* Minimum compiler version to build has been raised to GCC 4.8 and VS 2015.

* The Timer related APIs now expect a Name and Description. When upgrading code
  the previously used names should become descriptions and a short name in the
  style of a programming language identifier should be added.

* LLVM now handles invariant.group across different basic blocks, which makes
  it possible to devirtualize virtual calls inside loops.

* ... next change ...

.. NOTE
   If you would like to document a larger change, then you can add a
   subsection about it right here. You can copy the following boilerplate
   and un-indent it (the indentation causes it to be inside this comment).

   Special New Feature
   -------------------

   Makes programs 10x faster by doing Special New Thing.

   Improvements to ThinLTO (-flto=thin)
   ------------------------------------
   * Integration with profile data (PGO). When available, profile data
     enables more accurate function importing decisions, as well as
     cross-module indirect call promotion.
   * Significant build-time and binary-size improvements when compiling with
     debug info (-g).

Intrusive list API overhaul
---------------------------

The intrusive list infrastructure was substantially rewritten over the last
couple of releases, primarily to excise undefined behaviour.  The biggest
changes landed in this release.

* ``simple_ilist<T>`` is a lower-level intrusive list that never takes
  ownership of its nodes.  New intrusive-list clients should consider using it
  instead of ``ilist<T>``.

  * ``ilist_tag<class>`` allows a single data type to be inserted into two
    parallel intrusive lists.  A type can inherit twice from ``ilist_node``,
    first using ``ilist_node<T,ilist_tag<A>>`` (enabling insertion into
    ``simple_ilist<T,ilist_tag<A>>``) and second using
    ``ilist_node<T,ilist_tag<B>>`` (enabling insertion into
    ``simple_ilist<T,ilist_tag<B>>``), where ``A`` and ``B`` are arbitrary
    types.

  * ``ilist_sentinel_tracking<bool>`` controls whether an iterator knows
    whether it's pointing at the sentinel (``end()``).  By default, sentinel
    tracking is on when ABI-breaking checks are enabled, and off otherwise;
    this is used for an assertion when dereferencing ``end()`` (this assertion
    triggered often in practice, and many backend bugs were fixed).  Explicitly
    turning on sentinel tracking also enables ``iterator::isEnd()``.  This is
    used by ``MachineInstrBundleIterator`` to iterate over bundles.

* ``ilist<T>`` is built on top of ``simple_ilist<T>``, and supports the same
  configuration options.  As before (and unlike ``simple_ilist<T>``),
  ``ilist<T>`` takes ownership of its nodes.  However, it no longer supports
  *allocating* nodes, and is now equivalent to ``iplist<T>``.  ``iplist<T>``
  will likely be removed in the future.

  * ``ilist<T>`` now always uses ``ilist_traits<T>``.  Instead of passing a
    custom traits class in via a template parameter, clients that want to
    customize the traits should specialize ``ilist_traits<T>``.  Clients that
    want to avoid ownership can specialize ``ilist_alloc_traits<T>`` to inherit
    from ``ilist_noalloc_traits<T>`` (or to do something funky); clients that
    need callbacks can specialize ``ilist_callback_traits<T>`` directly.

* The underlying data structure is now a simple recursive linked list.  The
  sentinel node contains only a "next" (``begin()``) and "prev" (``rbegin()``)
  pointer and is stored in the same allocation as ``simple_ilist<T>``.
  Previously, it was malloc-allocated on-demand by default, although the
  now-defunct ``ilist_sentinel_traits<T>`` was sometimes specialized to avoid
  this.

* The ``reverse_iterator`` class no longer uses ``std::reverse_iterator``.
  Instead, it now has a handle to the same node that it dereferences to.
  Reverse iterators now have the same iterator invalidation semantics as
  forward iterators.

  * ``iterator`` and ``reverse_iterator`` have explicit conversion constructors
    that match ``std::reverse_iterator``'s off-by-one semantics, so that
    reversing the end points of an iterator range results in the same range
    (albeit in reverse).  I.e., ``reverse_iterator(begin())`` equals
    ``rend()``.

  * ``iterator::getReverse()`` and ``reverse_iterator::getReverse()`` return an
    iterator that dereferences to the *same* node.  I.e.,
    ``begin().getReverse()`` equals ``--rend()``.

  * ``ilist_node<T>::getIterator()`` and
    ``ilist_node<T>::getReverseIterator()`` return the forward and reverse
    iterators that dereference to the current node.  I.e.,
    ``begin()->getIterator()`` equals ``begin()`` and
    ``rbegin()->getReverseIterator()`` equals ``rbegin()``.

* ``iterator`` now stores an ``ilist_node_base*`` instead of a ``T*``.  The
  implicit conversions between ``ilist<T>::iterator`` and ``T*`` have been
  removed.  Clients may use ``N->getIterator()`` (if not ``nullptr``) or
  ``&*I`` (if not ``end()``); alternatively, clients may refactor to use
  references for known-good nodes.

Changes to the LLVM IR
----------------------

Changes to the ARM Targets
--------------------------

**During this release the AArch64 target has:**

* Gained support for ILP32 relocations.
* Gained support for XRay.
* Made even more progress on GlobalISel. There is still some work left before
  it is production-ready though.
* Refined the support for Qualcomm's Falkor and Samsung's Exynos CPUs.
* Learned a few new tricks for lowering multiplications by constants, folding
  spilled/refilled copies etc.

**During this release the ARM target has:**

* Gained support for ROPI (read-only position independence) and RWPI
  (read-write position independence), which can be used to remove the need for
  a dynamic linker.
* Gained support for execute-only code, which is placed in pages without read
  permissions.
* Gained a machine scheduler for Cortex-R52.
* Gained support for XRay.
* Gained Thumb1 implementations for several compiler-rt builtins. It also
  has some support for building the builtins for HF targets.
* Started using the generic bitreverse intrinsic instead of rbit.
* Gained very basic support for GlobalISel.

A lot of work has also been done in LLD for ARM, which now supports more
relocations and TLS.


Changes to the MIPS Target
--------------------------

 During this release ...


Changes to the PowerPC Target
-----------------------------

 During this release ...

Changes to the X86 Target
-------------------------

 During this release ...

Changes to the AMDGPU Target
-----------------------------

 During this release ...

Changes to the AVR Target
-----------------------------

* The entire backend has been merged in-tree with all tests passing. All of
  the instruction selection code and the machine code backend has landed
  recently and is fully usable.

Changes to the OCaml bindings
-----------------------------

* The attribute API was completely overhauled, following the changes
  to the C API.


External Open Source Projects Using LLVM 4.0.0
==============================================

* A project...


Additional Information
======================

A wide variety of additional information is available on the `LLVM web page
<http://llvm.org/>`_, in particular in the `documentation
<http://llvm.org/docs/>`_ section.  The web page also contains versions of the
API documentation which is up-to-date with the Subversion version of the source
code.  You can access versions of these documents specific to this release by
going into the ``llvm/docs/`` directory in the LLVM tree.

If you have any questions or comments about LLVM, please feel free to contact
us via the `mailing lists <http://llvm.org/docs/#maillist>`_.