Creating branches/google/stable and tags/google/stable/2019-05-14 from r360103

git-svn-id: https://llvm.org/svn/llvm-project/llvm/branches/google/stable@360714 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/.clang-tidy b/.clang-tidy
index 2cfcc2a..3f407e0 100644
--- a/.clang-tidy
+++ b/.clang-tidy
@@ -1,4 +1,4 @@
-Checks: '-*,clang-diagnostic-*,llvm-*,misc-*,-misc-unused-parameters,readability-identifier-naming'
+Checks: '-*,clang-diagnostic-*,llvm-*,misc-*,-misc-unused-parameters,-misc-non-private-member-variables-in-classes,readability-identifier-naming'
 CheckOptions:
   - key:             readability-identifier-naming.ClassCase
     value:           CamelCase
diff --git a/.gitignore b/.gitignore
index 0aa0a8a..be58944c9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -72,6 +72,8 @@
 # VS2017 and VSCode config files.
 .vscode
 .vs
+# clangd index
+.clangd
 
 #==============================================================================#
 # Files created in tree by the Go bindings.
diff --git a/CMakeLists.txt b/CMakeLists.txt
index b144be5..0164d3e 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -12,7 +12,7 @@
 endif()
 
 if(NOT DEFINED LLVM_VERSION_MAJOR)
-  set(LLVM_VERSION_MAJOR 8)
+  set(LLVM_VERSION_MAJOR 9)
 endif()
 if(NOT DEFINED LLVM_VERSION_MINOR)
   set(LLVM_VERSION_MINOR 0)
@@ -104,27 +104,60 @@
 # LLVM_EXTERNAL_${project}_SOURCE_DIR using LLVM_ALL_PROJECTS
 # This allows an easy way of setting up a build directory for llvm and another
 # one for llvm+clang+... using the same sources.
-set(LLVM_ALL_PROJECTS "clang;libcxx;libcxxabi;libunwind;lldb;compiler-rt;lld;polly;debuginfo-tests")
+set(LLVM_ALL_PROJECTS "clang;clang-tools-extra;compiler-rt;debuginfo-tests;libclc;libcxx;libcxxabi;libunwind;lld;lldb;llgo;openmp;parallel-libs;polly;pstl")
 set(LLVM_ENABLE_PROJECTS "" CACHE STRING
 	"Semicolon-separated list of projects to build (${LLVM_ALL_PROJECTS}), or \"all\".")
 if( LLVM_ENABLE_PROJECTS STREQUAL "all" )
   set( LLVM_ENABLE_PROJECTS ${LLVM_ALL_PROJECTS})
 endif()
-foreach(proj ${LLVM_ENABLE_PROJECTS})
-  set(PROJ_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../${proj}")
-  if(NOT EXISTS "${PROJ_DIR}" OR NOT IS_DIRECTORY "${PROJ_DIR}")
-    message(FATAL_ERROR "LLVM_ENABLE_PROJECTS requests ${proj} but directory not found: ${PROJ_DIR}")
-  endif()
-  string(TOUPPER "${proj}" upper_proj)
-  STRING(REGEX REPLACE "-" "_" upper_proj ${upper_proj})
-  set(LLVM_EXTERNAL_${upper_proj}_SOURCE_DIR   "${CMAKE_CURRENT_SOURCE_DIR}/../${proj}")
-  # There is a widely spread opinion that clang-tools-extra should be merged
-  # into clang. The following simulates it by always enabling clang-tools-extra
-  # when enabling clang.
-  if (proj STREQUAL "clang")
-    set(LLVM_EXTERNAL_CLANG_TOOLS_EXTRA_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../clang-tools-extra")
-  endif()
-endforeach()
+
+# LLVM_ENABLE_PROJECTS_USED is `ON` if the user has ever used the
+# `LLVM_ENABLE_PROJECTS` CMake cache variable.  This exists for
+# several reasons:
+#
+# * As an indicator that the `LLVM_ENABLE_PROJECTS` list is now the single
+# source of truth for which projects to build. This means we will ignore user
+# supplied `LLVM_TOOL_<project>_BUILD` CMake cache variables and overwrite
+# them.
+#
+# * The case where the user previously had `LLVM_ENABLE_PROJECTS` set to a
+# non-empty list but now the user wishes to disable building all other projects
+# by setting `LLVM_ENABLE_PROJECTS` to an empty string. In that case we still
+# need to set the `LLVM_TOOL_${upper_proj}_BUILD` variables so that we disable
+# building all the projects that were previously enabled.
+set(LLVM_ENABLE_PROJECTS_USED OFF CACHE BOOL "")
+mark_as_advanced(LLVM_ENABLE_PROJECTS_USED)
+
+if (LLVM_ENABLE_PROJECTS_USED OR NOT LLVM_ENABLE_PROJECTS STREQUAL "")
+  set(LLVM_ENABLE_PROJECTS_USED ON CACHE BOOL "" FORCE)
+  foreach(proj ${LLVM_ALL_PROJECTS} ${LLVM_EXTERNAL_PROJECTS})
+    string(TOUPPER "${proj}" upper_proj)
+    string(REGEX REPLACE "-" "_" upper_proj ${upper_proj})
+    if ("${proj}" IN_LIST LLVM_ENABLE_PROJECTS)
+      message(STATUS "${proj} project is enabled")
+      set(SHOULD_ENABLE_PROJECT TRUE)
+      set(PROJ_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../${proj}")
+      if(NOT EXISTS "${PROJ_DIR}" OR NOT IS_DIRECTORY "${PROJ_DIR}")
+        message(FATAL_ERROR "LLVM_ENABLE_PROJECTS requests ${proj} but directory not found: ${PROJ_DIR}")
+      endif()
+      set(LLVM_EXTERNAL_${upper_proj}_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../${proj}" CACHE STRING "")
+    else()
+      message(STATUS "${proj} project is disabled")
+      set(SHOULD_ENABLE_PROJECT FALSE)
+    endif()
+    # Force `LLVM_TOOL_${upper_proj}_BUILD` variables to have values that
+    # corresponds with `LLVM_ENABLE_PROJECTS`. This prevents the user setting
+    # `LLVM_TOOL_${upper_proj}_BUILD` variables externally. At some point
+    # we should deprecate allowing users to set these variables by turning them
+    # into normal CMake variables rather than cache variables.
+    set(LLVM_TOOL_${upper_proj}_BUILD
+      ${SHOULD_ENABLE_PROJECT}
+      CACHE
+      BOOL "Whether to build ${upper_proj} as part of LLVM" FORCE
+    )
+  endforeach()
+endif()
+unset(SHOULD_ENABLE_PROJECT)
 
 # Build llvm with ccache if the package is present
 set(LLVM_CCACHE_BUILD OFF CACHE BOOL "Set to ON for a ccache enabled build")
@@ -200,7 +233,7 @@
 include(VersionFromVCS)
 
 option(LLVM_APPEND_VC_REV
-  "Embed the version control system revision id in LLVM" ON)
+  "Embed the version control system revision in LLVM" ON)
 
 set(PACKAGE_NAME LLVM)
 set(PACKAGE_STRING "${PACKAGE_NAME} ${PACKAGE_VERSION}")
@@ -318,6 +351,8 @@
   set(ENABLE_BACKTRACES 1)
 endif()
 
+option(LLVM_ENABLE_UNWIND_TABLES "Emit unwind tables for the libraries" ON)
+
 option(LLVM_ENABLE_CRASH_OVERRIDES "Enable crash overrides." ON)
 if(LLVM_ENABLE_CRASH_OVERRIDES)
   set(ENABLE_CRASH_OVERRIDES 1)
@@ -344,6 +379,31 @@
 
 option(LLVM_ENABLE_ZLIB "Use zlib for compression/decompression if available." ON)
 
+set(LLVM_Z3_INSTALL_DIR "" CACHE STRING "Install directory of the Z3 solver.")
+
+find_package(Z3 4.7.1)
+
+if (LLVM_Z3_INSTALL_DIR)
+  if (NOT Z3_FOUND)
+    message(FATAL_ERROR "Z3 >= 4.7.1 has not been found in LLVM_Z3_INSTALL_DIR: ${LLVM_Z3_INSTALL_DIR}.")
+  endif()
+endif()
+
+set(LLVM_ENABLE_Z3_SOLVER_DEFAULT "${Z3_FOUND}")
+
+option(LLVM_ENABLE_Z3_SOLVER
+  "Enable Support for the Z3 constraint solver in LLVM."
+  ${LLVM_ENABLE_Z3_SOLVER_DEFAULT}
+)
+
+if (LLVM_ENABLE_Z3_SOLVER)
+  if (NOT Z3_FOUND)
+    message(FATAL_ERROR "LLVM_ENABLE_Z3_SOLVER cannot be enabled when Z3 is not available.")
+  endif()
+
+  set(LLVM_WITH_Z3 1)
+endif()
+
 if( LLVM_TARGETS_TO_BUILD STREQUAL "all" )
   set( LLVM_TARGETS_TO_BUILD ${LLVM_ALL_TARGETS} )
 endif()
@@ -363,8 +423,6 @@
   option(LLVM_ENABLE_MODULE_DEBUGGING "Compile with -gmodules." OFF)
   option(LLVM_ENABLE_LOCAL_SUBMODULE_VISIBILITY "Compile with -fmodules-local-submodule-visibility." ON)
 endif()
-option(LLVM_ENABLE_CXX1Y "Compile with C++1y enabled." OFF)
-option(LLVM_ENABLE_CXX1Z "Compile with C++1z enabled." OFF)
 option(LLVM_ENABLE_LIBCXX "Use libc++ if available." OFF)
 option(LLVM_ENABLE_LLD "Use lld as C and C++ linker." OFF)
 option(LLVM_ENABLE_PEDANTIC "Compile with pedantic enabled." ON)
@@ -383,9 +441,12 @@
 set(LLVM_ABI_BREAKING_CHECKS "WITH_ASSERTS" CACHE STRING
   "Enable abi-breaking checks.  Can be WITH_ASSERTS, FORCE_ON or FORCE_OFF.")
 
-option(LLVM_FORCE_USE_OLD_HOST_TOOLCHAIN
+option(LLVM_FORCE_USE_OLD_TOOLCHAIN
        "Set to ON to force using an old, unsupported host toolchain." OFF)
 
+option(LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN
+       "Set to ON to only warn when using a toolchain which is about to be deprecated, instead of emitting an error." OFF)
+
 option(LLVM_USE_INTEL_JITEVENTS
   "Use Intel JIT API to inform Intel(R) VTune(TM) Amplifier XE 2011 about JIT code"
   OFF)
@@ -534,7 +595,7 @@
 endif()
 option(LLVM_LINK_LLVM_DYLIB "Link tools against the libllvm dynamic library" OFF)
 if(MSVC)
-  option(LLVM_BUILD_LLVM_C_DYLIB "Build LLVM-C.dll (Windows only)" OFF)
+  option(LLVM_BUILD_LLVM_C_DYLIB "Build LLVM-C.dll (Windows only)" ON)
 else()
   option(LLVM_BUILD_LLVM_C_DYLIB "Build libllvm-c re-export library (Darwin only)" OFF)
 endif()
@@ -568,6 +629,12 @@
     endif()
 		file(TO_NATIVE_PATH "${LLVM_PROFILE_DATA_DIR}/%${LLVM_PROFILE_MERGE_POOL_SIZE}m.profraw" LLVM_PROFILE_FILE_PATTERN)
   endif()
+  if(NOT LLVM_CSPROFILE_FILE_PATTERN)
+    if(NOT LLVM_CSPROFILE_DATA_DIR)
+      file(TO_NATIVE_PATH "${LLVM_BINARY_DIR}/csprofiles" LLVM_CSPROFILE_DATA_DIR)
+    endif()
+    file(TO_NATIVE_PATH "${LLVM_CSPROFILE_DATA_DIR}/%${LLVM_PROFILE_MERGE_POOL_SIZE}m.profraw" LLVM_CSPROFILE_FILE_PATTERN)
+  endif()
 endif()
 
 if (LLVM_BUILD_STATIC)
@@ -752,13 +819,12 @@
 set(LLVM_SRPM_BINARY_SPECFILE ${CMAKE_CURRENT_BINARY_DIR}/llvm.spec)
 set(LLVM_SRPM_DIR "${CMAKE_CURRENT_BINARY_DIR}/srpm")
 
-# SVN_REVISION and GIT_COMMIT get set by the call to add_version_info_from_vcs.
-# DUMMY_VAR contains a version string which we don't care about.
-add_version_info_from_vcs(DUMMY_VAR)
-if ( SVN_REVISION )
-  set(LLVM_RPM_SPEC_REVISION "r${SVN_REVISION}")
-elseif ( GIT_COMMIT )
-  set (LLVM_RPM_SPEC_REVISION "g${GIT_COMMIT}")
+get_source_info(${CMAKE_CURRENT_SOURCE_DIR} revision repository)
+string(LENGTH "${revision}" revision_length)
+if(revision MATCHES "^[0-9]+$" AND revision_length LESS 40)
+  set(LLVM_RPM_SPEC_REVISION "r${revision}")
+else()
+  set(LLVM_RPM_SPEC_REVISION "${revision}")
 endif()
 
 configure_file(
diff --git a/CREDITS.TXT b/CREDITS.TXT
index 0a8154c..527229d 100644
--- a/CREDITS.TXT
+++ b/CREDITS.TXT
@@ -1,5 +1,5 @@
 This file is a partial list of people who have contributed to the LLVM
-project.  If you have contributed a patch or made some other contribution to
+project. If you have contributed a patch or made some other contribution to
 LLVM, please submit a patch to this file to add yourself, and it will be
 done!
 
@@ -132,7 +132,7 @@
 
 N: Eric Fiselier
 E: eric@efcs.ca
-D: LIT patches and documentation.
+D: LIT patches and documentation
 
 N: Ryan Flynn
 E: pizza@parseerror.com
@@ -167,6 +167,17 @@
 D: Miscellaneous bug fixes
 D: WebAssembly Backend
 
+N: Renato Golin
+E: rengolin@systemcall.eu
+E: renato.golin@linaro.org
+E: rengolin@gmail.com
+D: ARM/AArch64 back-end improvements
+D: Loop Vectorizer improvements
+D: Regression and Test Suite improvements
+D: Linux compatibility (GNU, musl, etc)
+D: Initial Linux kernel / Android support effort
+I: rengolin
+
 N: David Goodwin
 E: david@goodwinz.net
 D: Thumb-2 code generator
@@ -514,3 +525,11 @@
 N: Kang Zhang
 E: shkzhang@cn.ibm.com
 D: PowerPC Backend Developer
+
+N: Zheng Chen
+E: czhengsz@cn.ibm.com
+D: PowerPC Backend Developer
+
+N: Qiu Chaofan
+E: qiucf@cn.ibm.com
+D: PowerPC Backend Developer
diff --git a/LICENSE.TXT b/LICENSE.TXT
index e4d67d1..fa6ac54 100644
--- a/LICENSE.TXT
+++ b/LICENSE.TXT
@@ -1,5 +1,240 @@
 ==============================================================================
-LLVM Release License
+The LLVM Project is under the Apache License v2.0 with LLVM Exceptions:
+==============================================================================
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+    1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+    2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+    3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+    4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+    5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+    6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+    7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+    8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+    9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+    END OF TERMS AND CONDITIONS
+
+    APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+    Copyright [yyyy] [name of copyright owner]
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+
+
+---- LLVM Exceptions to the Apache 2.0 License ----
+
+As an exception, if, as a result of your compiling your source code, portions
+of this Software are embedded into an Object form of such source code, you
+may redistribute such embedded portions in such Object form without complying
+with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+In addition, if you combine or link compiled forms of this Software with
+software that is licensed under the GPLv2 ("Combined Software") and if a
+court of competent jurisdiction determines that the patent provision (Section
+3), the indemnity provision (Section 9) or other Section of the License
+conflicts with the conditions of the GPLv2, you may retroactively and
+prospectively choose to deem waived or otherwise exclude such Section(s) of
+the License, but only in their entirety and only with respect to the Combined
+Software.
+
+==============================================================================
+Software from third parties included in the LLVM Project:
+==============================================================================
+The LLVM Project contains third party software which is under different license
+terms. All such code will be identified clearly using at least one of two
+mechanisms:
+1) It will be in a separate directory tree with its own `LICENSE.txt` or
+   `LICENSE` file at the top containing the specific license and restrictions
+   which apply to that software, or
+2) It will contain specific license and restriction terms at the top of every
+   file.
+
+==============================================================================
+Legacy LLVM License (https://llvm.org/docs/DeveloperPolicy.html#legacy):
 ==============================================================================
 University of Illinois/NCSA
 Open Source License
@@ -42,27 +277,3 @@
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS WITH THE
 SOFTWARE.
 
-==============================================================================
-Copyrights and Licenses for Third Party Software Distributed with LLVM:
-==============================================================================
-The LLVM software contains code written by third parties.  Such software will
-have its own individual LICENSE.TXT file in the directory in which it appears.
-This file will describe the copyrights, license, and restrictions which apply
-to that code.
-
-The disclaimer of warranty in the University of Illinois Open Source License
-applies to all code in the LLVM Distribution, and nothing in any of the
-other licenses gives permission to use the names of the LLVM Team or the
-University of Illinois to endorse or promote products derived from this
-Software.
-
-The following pieces of software have additional or alternate copyrights,
-licenses, and/or restrictions:
-
-Program             Directory
--------             ---------
-Google Test         llvm/utils/unittest/googletest
-OpenBSD regex       llvm/lib/Support/{reg*, COPYRIGHT.regex}
-pyyaml tests        llvm/test/YAMLParser/{*.data, LICENSE.TXT}
-ARM contributions   llvm/lib/Target/ARM/LICENSE.TXT
-md5 contributions   llvm/lib/Support/MD5.cpp llvm/include/llvm/Support/MD5.h
diff --git a/LLVMBuild.txt b/LLVMBuild.txt
index 9cee303..4cc65f2 100644
--- a/LLVMBuild.txt
+++ b/LLVMBuild.txt
@@ -1,9 +1,8 @@
 ;===- ./LLVMBuild.txt ------------------------------------------*- Conf -*--===;
 ;
-;                     The LLVM Compiler Infrastructure
-;
-; This file is distributed under the University of Illinois Open Source
-; License. See LICENSE.TXT for details.
+; Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+; See https://llvm.org/LICENSE.txt for license information.
+; SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ;
 ;===------------------------------------------------------------------------===;
 ;
diff --git a/README.txt b/README.txt
index ebbd50f..b9b71a3 100644
--- a/README.txt
+++ b/README.txt
@@ -15,4 +15,3 @@
 
 If you are writing a package for LLVM, see docs/Packaging.rst for our
 suggestions.
-
diff --git a/bindings/LLVMBuild.txt b/bindings/LLVMBuild.txt
index 241ac09..9e54226 100644
--- a/bindings/LLVMBuild.txt
+++ b/bindings/LLVMBuild.txt
@@ -1,9 +1,8 @@
 ;===- ./bindings/LLVMBuild.txt ---------------------------------*- Conf -*--===;
 ;
-;                     The LLVM Compiler Infrastructure
-;
-; This file is distributed under the University of Illinois Open Source
-; License. See LICENSE.TXT for details.
+; Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+; See https://llvm.org/LICENSE.txt for license information.
+; SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ;
 ;===------------------------------------------------------------------------===;
 ;
diff --git a/bindings/go/llvm/IRBindings.cpp b/bindings/go/llvm/IRBindings.cpp
index b8e3063..5b84f48 100644
--- a/bindings/go/llvm/IRBindings.cpp
+++ b/bindings/go/llvm/IRBindings.cpp
@@ -1,9 +1,8 @@
 //===- IRBindings.cpp - Additional bindings for ir ------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
@@ -51,7 +50,7 @@
   unwrap<Instruction>(Inst)->setMetadata(KindID, N);
 }
 
-void LLVMSetCurrentDebugLocation2(LLVMBuilderRef Bref, unsigned Line,
+void LLVMGoSetCurrentDebugLocation(LLVMBuilderRef Bref, unsigned Line,
                                   unsigned Col, LLVMMetadataRef Scope,
                                   LLVMMetadataRef InlinedAt) {
   unwrap(Bref)->SetCurrentDebugLocation(
@@ -59,7 +58,7 @@
                     InlinedAt ? unwrap<MDNode>(InlinedAt) : nullptr));
 }
 
-LLVMDebugLocMetadata LLVMGetCurrentDebugLocation2(LLVMBuilderRef Bref) {
+LLVMDebugLocMetadata LLVMGoGetCurrentDebugLocation(LLVMBuilderRef Bref) {
   const auto& Loc = unwrap(Bref)->getCurrentDebugLocation();
   const auto* InlinedAt = Loc.getInlinedAt();
   const LLVMDebugLocMetadata md{
diff --git a/bindings/go/llvm/IRBindings.h b/bindings/go/llvm/IRBindings.h
index 66b328c..778b0d2 100644
--- a/bindings/go/llvm/IRBindings.h
+++ b/bindings/go/llvm/IRBindings.h
@@ -1,9 +1,8 @@
 //===- IRBindings.h - Additional bindings for IR ----------------*- C++ -*-===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
@@ -44,11 +43,11 @@
                                   LLVMMetadataRef Val);
 void LLVMSetMetadata2(LLVMValueRef Inst, unsigned KindID, LLVMMetadataRef MD);
 
-void LLVMSetCurrentDebugLocation2(LLVMBuilderRef Bref, unsigned Line,
+void LLVMGoSetCurrentDebugLocation(LLVMBuilderRef Bref, unsigned Line,
                                   unsigned Col, LLVMMetadataRef Scope,
                                   LLVMMetadataRef InlinedAt);
 
-struct LLVMDebugLocMetadata LLVMGetCurrentDebugLocation2(LLVMBuilderRef Bref);
+struct LLVMDebugLocMetadata LLVMGoGetCurrentDebugLocation(LLVMBuilderRef Bref);
 
 #ifdef __cplusplus
 }
diff --git a/bindings/go/llvm/InstrumentationBindings.cpp b/bindings/go/llvm/InstrumentationBindings.cpp
index c3b4f2e..794657f 100644
--- a/bindings/go/llvm/InstrumentationBindings.cpp
+++ b/bindings/go/llvm/InstrumentationBindings.cpp
@@ -1,9 +1,8 @@
 //===- InstrumentationBindings.cpp - instrumentation bindings -------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
@@ -16,6 +15,7 @@
 #include "llvm/IR/LegacyPassManager.h"
 #include "llvm/IR/Module.h"
 #include "llvm/Transforms/Instrumentation.h"
+#include "llvm/Transforms/Instrumentation/AddressSanitizer.h"
 #include "llvm/Transforms/Instrumentation/MemorySanitizer.h"
 #include "llvm/Transforms/Instrumentation/ThreadSanitizer.h"
 
@@ -26,7 +26,7 @@
 }
 
 void LLVMAddAddressSanitizerModulePass(LLVMPassManagerRef PM) {
-  unwrap(PM)->add(createAddressSanitizerModulePass());
+  unwrap(PM)->add(createModuleAddressSanitizerLegacyPassPass());
 }
 
 void LLVMAddThreadSanitizerPass(LLVMPassManagerRef PM) {
diff --git a/bindings/go/llvm/InstrumentationBindings.h b/bindings/go/llvm/InstrumentationBindings.h
index 5d448fc..143086c 100644
--- a/bindings/go/llvm/InstrumentationBindings.h
+++ b/bindings/go/llvm/InstrumentationBindings.h
@@ -1,9 +1,8 @@
 //===- InstrumentationBindings.h - instrumentation bindings -----*- C++ -*-===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/SupportBindings.cpp b/bindings/go/llvm/SupportBindings.cpp
index 5e251b7..aac69a7 100644
--- a/bindings/go/llvm/SupportBindings.cpp
+++ b/bindings/go/llvm/SupportBindings.cpp
@@ -1,9 +1,8 @@
 //===- SupportBindings.cpp - Additional bindings for support --------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/SupportBindings.h b/bindings/go/llvm/SupportBindings.h
index efcd667..db83e91 100644
--- a/bindings/go/llvm/SupportBindings.h
+++ b/bindings/go/llvm/SupportBindings.h
@@ -1,9 +1,8 @@
 //===- SupportBindings.h - Additional bindings for Support ------*- C++ -*-===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/analysis.go b/bindings/go/llvm/analysis.go
index 3ae4b71..3a1c9d3 100644
--- a/bindings/go/llvm/analysis.go
+++ b/bindings/go/llvm/analysis.go
@@ -1,9 +1,8 @@
 //===- analysis.go - Bindings for analysis --------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/bitreader.go b/bindings/go/llvm/bitreader.go
index c3bf07a..1954916 100644
--- a/bindings/go/llvm/bitreader.go
+++ b/bindings/go/llvm/bitreader.go
@@ -1,9 +1,8 @@
 //===- bitreader.go - Bindings for bitreader ------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/bitwriter.go b/bindings/go/llvm/bitwriter.go
index e03699c..83780fc 100644
--- a/bindings/go/llvm/bitwriter.go
+++ b/bindings/go/llvm/bitwriter.go
@@ -1,9 +1,8 @@
 //===- bitwriter.go - Bindings for bitwriter ------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/dibuilder.go b/bindings/go/llvm/dibuilder.go
index 1a98c07..69d5b91 100644
--- a/bindings/go/llvm/dibuilder.go
+++ b/bindings/go/llvm/dibuilder.go
@@ -1,9 +1,8 @@
 //===- dibuilder.go - Bindings for DIBuilder ------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/executionengine.go b/bindings/go/llvm/executionengine.go
index 91f8366..5fa8204 100644
--- a/bindings/go/llvm/executionengine.go
+++ b/bindings/go/llvm/executionengine.go
@@ -1,9 +1,8 @@
 //===- executionengine.go - Bindings for executionengine ------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/executionengine_test.go b/bindings/go/llvm/executionengine_test.go
index 3ca36d0..4462f8f 100644
--- a/bindings/go/llvm/executionengine_test.go
+++ b/bindings/go/llvm/executionengine_test.go
@@ -1,9 +1,8 @@
 //===- executionengine_test.go - Tests for executionengine ----------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/ir.go b/bindings/go/llvm/ir.go
index 1872a2f..555055f 100644
--- a/bindings/go/llvm/ir.go
+++ b/bindings/go/llvm/ir.go
@@ -1,9 +1,8 @@
 //===- ir.go - Bindings for ir --------------------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
@@ -1263,7 +1262,7 @@
 	num := C.LLVMGetNumIndices(v.C)
 	indicesPtr := C.LLVMGetIndices(v.C)
 	// https://github.com/golang/go/wiki/cgo#turning-c-arrays-into-go-slices
-	rawIndices := (*[1 << 30]C.uint)(unsafe.Pointer(indicesPtr))[:num:num]
+	rawIndices := (*[1 << 20]C.uint)(unsafe.Pointer(indicesPtr))[:num:num]
 	indices := make([]uint32, num)
 	for i := range indices {
 		indices[i] = uint32(rawIndices[i])
@@ -1302,11 +1301,11 @@
 	InlinedAt      Metadata
 }
 func (b Builder) SetCurrentDebugLocation(line, col uint, scope, inlinedAt Metadata) {
-	C.LLVMSetCurrentDebugLocation2(b.C, C.unsigned(line), C.unsigned(col), scope.C, inlinedAt.C)
+	C.LLVMGoSetCurrentDebugLocation(b.C, C.unsigned(line), C.unsigned(col), scope.C, inlinedAt.C)
 }
 // Get current debug location. Please do not call this function until setting debug location with SetCurrentDebugLocation()
 func (b Builder) GetCurrentDebugLocation() (loc DebugLoc) {
-	md := C.LLVMGetCurrentDebugLocation2(b.C)
+	md := C.LLVMGoGetCurrentDebugLocation(b.C)
 	loc.Line = uint(md.Line)
 	loc.Col = uint(md.Col)
 	loc.Scope = Metadata{C: md.Scope}
diff --git a/bindings/go/llvm/ir_test.go b/bindings/go/llvm/ir_test.go
index 10f4968..5dd0598 100644
--- a/bindings/go/llvm/ir_test.go
+++ b/bindings/go/llvm/ir_test.go
@@ -1,9 +1,8 @@
 //===- ir_test.go - Tests for ir ------------------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
@@ -31,7 +30,7 @@
 	fn.AddFunctionAttr(attr)
 	newattr := fn.GetEnumFunctionAttribute(kind)
 	if attr != newattr {
-		t.Errorf("got attribute mask %d, want %d", newattr, attr)
+		t.Errorf("got attribute %p, want %p", newattr.C, attr.C)
 	}
 
 	text := mod.String()
@@ -42,7 +41,7 @@
 	fn.RemoveEnumFunctionAttribute(kind)
 	newattr = fn.GetEnumFunctionAttribute(kind)
 	if !newattr.IsNil() {
-		t.Errorf("got attribute mask %d, want 0", newattr)
+		t.Errorf("got attribute %p, want 0", newattr.C)
 	}
 }
 
diff --git a/bindings/go/llvm/linker.go b/bindings/go/llvm/linker.go
index ca16f76..8e2e953 100644
--- a/bindings/go/llvm/linker.go
+++ b/bindings/go/llvm/linker.go
@@ -1,9 +1,8 @@
 //===- linker.go - Bindings for linker ------------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/llvm_dep.go b/bindings/go/llvm/llvm_dep.go
index 39b4675..9484e6d 100644
--- a/bindings/go/llvm/llvm_dep.go
+++ b/bindings/go/llvm/llvm_dep.go
@@ -1,9 +1,8 @@
 //===- llvm_dep.go - creates LLVM dependency ------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/string.go b/bindings/go/llvm/string.go
index bfe869d..bd48d4b 100644
--- a/bindings/go/llvm/string.go
+++ b/bindings/go/llvm/string.go
@@ -1,9 +1,8 @@
 //===- string.go - Stringer implementation for Type -----------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/string_test.go b/bindings/go/llvm/string_test.go
index 3008f3e..56cbc9f 100644
--- a/bindings/go/llvm/string_test.go
+++ b/bindings/go/llvm/string_test.go
@@ -1,9 +1,8 @@
 //===- string_test.go - test Stringer implementation for Type -------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/support.go b/bindings/go/llvm/support.go
index 6f20086..8a663fe 100644
--- a/bindings/go/llvm/support.go
+++ b/bindings/go/llvm/support.go
@@ -1,9 +1,8 @@
 //===- support.go - Bindings for support ----------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/target.go b/bindings/go/llvm/target.go
index 5333397..cdd0fa3 100644
--- a/bindings/go/llvm/target.go
+++ b/bindings/go/llvm/target.go
@@ -1,9 +1,8 @@
 //===- target.go - Bindings for target ------------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/transforms_coroutines.go b/bindings/go/llvm/transforms_coroutines.go
index 9486fcb..d0af76d 100644
--- a/bindings/go/llvm/transforms_coroutines.go
+++ b/bindings/go/llvm/transforms_coroutines.go
@@ -1,9 +1,8 @@
 //===- transforms_coroutines.go - Bindings for coroutines -----------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/transforms_instrumentation.go b/bindings/go/llvm/transforms_instrumentation.go
index 73d093a..68e0ed6 100644
--- a/bindings/go/llvm/transforms_instrumentation.go
+++ b/bindings/go/llvm/transforms_instrumentation.go
@@ -1,9 +1,8 @@
 //===- transforms_instrumentation.go - Bindings for instrumentation -------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/transforms_ipo.go b/bindings/go/llvm/transforms_ipo.go
index 12d972b..1dcb2af 100644
--- a/bindings/go/llvm/transforms_ipo.go
+++ b/bindings/go/llvm/transforms_ipo.go
@@ -1,9 +1,8 @@
 //===- transforms_ipo.go - Bindings for ipo -------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/transforms_pmbuilder.go b/bindings/go/llvm/transforms_pmbuilder.go
index b164e58..f6b92ed 100644
--- a/bindings/go/llvm/transforms_pmbuilder.go
+++ b/bindings/go/llvm/transforms_pmbuilder.go
@@ -1,9 +1,8 @@
 //===- transforms_pmbuilder.go - Bindings for PassManagerBuilder ----------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/transforms_scalar.go b/bindings/go/llvm/transforms_scalar.go
index cb46f68..36fc13e 100644
--- a/bindings/go/llvm/transforms_scalar.go
+++ b/bindings/go/llvm/transforms_scalar.go
@@ -1,9 +1,8 @@
 //===- transforms_scalar.go - Bindings for scalaropts ---------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/go/llvm/version.go b/bindings/go/llvm/version.go
index d0623be..1183fe4 100644
--- a/bindings/go/llvm/version.go
+++ b/bindings/go/llvm/version.go
@@ -1,9 +1,8 @@
 //===- version.go - LLVM version info -------------------------------------===//
 //
-//                     The LLVM Compiler Infrastructure
-//
-// This file is distributed under the University of Illinois Open Source
-// License. See LICENSE.TXT for details.
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
diff --git a/bindings/ocaml/all_backends/all_backends_ocaml.c b/bindings/ocaml/all_backends/all_backends_ocaml.c
index 8fe7d9b..ae4b496 100644
--- a/bindings/ocaml/all_backends/all_backends_ocaml.c
+++ b/bindings/ocaml/all_backends/all_backends_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- all_backends_ocaml.c - LLVM OCaml Glue ------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/all_backends/llvm_all_backends.ml b/bindings/ocaml/all_backends/llvm_all_backends.ml
index f4f4725..b4df7cd 100644
--- a/bindings/ocaml/all_backends/llvm_all_backends.ml
+++ b/bindings/ocaml/all_backends/llvm_all_backends.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_all_backends.ml - LLVM OCaml Interface -----------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/all_backends/llvm_all_backends.mli b/bindings/ocaml/all_backends/llvm_all_backends.mli
index 1808544..62a515b 100644
--- a/bindings/ocaml/all_backends/llvm_all_backends.mli
+++ b/bindings/ocaml/all_backends/llvm_all_backends.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_all_backends.mli - LLVM OCaml Interface ----------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/analysis/analysis_ocaml.c b/bindings/ocaml/analysis/analysis_ocaml.c
index 8b8263d..af98e65 100644
--- a/bindings/ocaml/analysis/analysis_ocaml.c
+++ b/bindings/ocaml/analysis/analysis_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- analysis_ocaml.c - LLVM OCaml Glue ----------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/analysis/llvm_analysis.ml b/bindings/ocaml/analysis/llvm_analysis.ml
index 8c11a63..a8e5f4e 100644
--- a/bindings/ocaml/analysis/llvm_analysis.ml
+++ b/bindings/ocaml/analysis/llvm_analysis.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_analysis.ml - LLVM OCaml Interface ---------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/analysis/llvm_analysis.mli b/bindings/ocaml/analysis/llvm_analysis.mli
index 03197cd..cf323b5 100644
--- a/bindings/ocaml/analysis/llvm_analysis.mli
+++ b/bindings/ocaml/analysis/llvm_analysis.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_analysis.mli - LLVM OCaml Interface --------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/backends/backend_ocaml.c b/bindings/ocaml/backends/backend_ocaml.c
index 3e1a438..16e68c5 100644
--- a/bindings/ocaml/backends/backend_ocaml.c
+++ b/bindings/ocaml/backends/backend_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- backend_ocaml.c - LLVM OCaml Glue -----------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/backends/llvm_backend.ml.in b/bindings/ocaml/backends/llvm_backend.ml.in
index bd1e586..b80cc75 100644
--- a/bindings/ocaml/backends/llvm_backend.ml.in
+++ b/bindings/ocaml/backends/llvm_backend.ml.in
@@ -1,9 +1,8 @@
 (*===-- llvm_backend.ml.in - LLVM OCaml Interface -------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/backends/llvm_backend.mli.in b/bindings/ocaml/backends/llvm_backend.mli.in
index 9506789..25b0f89 100644
--- a/bindings/ocaml/backends/llvm_backend.mli.in
+++ b/bindings/ocaml/backends/llvm_backend.mli.in
@@ -1,9 +1,8 @@
 (*===-- llvm_backend.mli.in - LLVM OCaml Interface ------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/bitreader/bitreader_ocaml.c b/bindings/ocaml/bitreader/bitreader_ocaml.c
index 6d95776..1af554e 100644
--- a/bindings/ocaml/bitreader/bitreader_ocaml.c
+++ b/bindings/ocaml/bitreader/bitreader_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- bitwriter_ocaml.c - LLVM OCaml Glue ---------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/bitreader/llvm_bitreader.ml b/bindings/ocaml/bitreader/llvm_bitreader.ml
index b26efdd..601089f 100644
--- a/bindings/ocaml/bitreader/llvm_bitreader.ml
+++ b/bindings/ocaml/bitreader/llvm_bitreader.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_bitreader.ml - LLVM OCaml Interface --------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/bitreader/llvm_bitreader.mli b/bindings/ocaml/bitreader/llvm_bitreader.mli
index 4351343..def8b84 100644
--- a/bindings/ocaml/bitreader/llvm_bitreader.mli
+++ b/bindings/ocaml/bitreader/llvm_bitreader.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_bitreader.mli - LLVM OCaml Interface -------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/bitwriter/bitwriter_ocaml.c b/bindings/ocaml/bitwriter/bitwriter_ocaml.c
index 04fd619..6856d75 100644
--- a/bindings/ocaml/bitwriter/bitwriter_ocaml.c
+++ b/bindings/ocaml/bitwriter/bitwriter_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- bitwriter_ocaml.c - LLVM OCaml Glue ---------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/bitwriter/llvm_bitwriter.ml b/bindings/ocaml/bitwriter/llvm_bitwriter.ml
index fca6efa..3750a02 100644
--- a/bindings/ocaml/bitwriter/llvm_bitwriter.ml
+++ b/bindings/ocaml/bitwriter/llvm_bitwriter.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_bitwriter.ml - LLVM OCaml Interface --------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===
  *
diff --git a/bindings/ocaml/bitwriter/llvm_bitwriter.mli b/bindings/ocaml/bitwriter/llvm_bitwriter.mli
index 3d0f780..b8cc59c 100644
--- a/bindings/ocaml/bitwriter/llvm_bitwriter.mli
+++ b/bindings/ocaml/bitwriter/llvm_bitwriter.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_bitwriter.mli - LLVM OCaml Interface -------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/executionengine/executionengine_ocaml.c b/bindings/ocaml/executionengine/executionengine_ocaml.c
index a5e62ac..c83a8ca 100644
--- a/bindings/ocaml/executionengine/executionengine_ocaml.c
+++ b/bindings/ocaml/executionengine/executionengine_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- executionengine_ocaml.c - LLVM OCaml Glue ---------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/executionengine/llvm_executionengine.ml b/bindings/ocaml/executionengine/llvm_executionengine.ml
index 3f37e0c..5b202e2 100644
--- a/bindings/ocaml/executionengine/llvm_executionengine.ml
+++ b/bindings/ocaml/executionengine/llvm_executionengine.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_executionengine.ml - LLVM OCaml Interface --------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/executionengine/llvm_executionengine.mli b/bindings/ocaml/executionengine/llvm_executionengine.mli
index bc076be..3c5a1c0 100644
--- a/bindings/ocaml/executionengine/llvm_executionengine.mli
+++ b/bindings/ocaml/executionengine/llvm_executionengine.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_executionengine.mli - LLVM OCaml Interface -------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/irreader/irreader_ocaml.c b/bindings/ocaml/irreader/irreader_ocaml.c
index ce593db..63a339e 100644
--- a/bindings/ocaml/irreader/irreader_ocaml.c
+++ b/bindings/ocaml/irreader/irreader_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- irreader_ocaml.c - LLVM OCaml Glue ----------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/irreader/llvm_irreader.ml b/bindings/ocaml/irreader/llvm_irreader.ml
index f757d62..a8ece43 100644
--- a/bindings/ocaml/irreader/llvm_irreader.ml
+++ b/bindings/ocaml/irreader/llvm_irreader.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_irreader.ml - LLVM OCaml Interface ---------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/irreader/llvm_irreader.mli b/bindings/ocaml/irreader/llvm_irreader.mli
index 2b11473..bdb7d04 100644
--- a/bindings/ocaml/irreader/llvm_irreader.mli
+++ b/bindings/ocaml/irreader/llvm_irreader.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_irreader.mli - LLVM OCaml Interface --------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/linker/linker_ocaml.c b/bindings/ocaml/linker/linker_ocaml.c
index 08737bd..75723d9 100644
--- a/bindings/ocaml/linker/linker_ocaml.c
+++ b/bindings/ocaml/linker/linker_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- linker_ocaml.c - LLVM OCaml Glue ------------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/linker/llvm_linker.ml b/bindings/ocaml/linker/llvm_linker.ml
index f2b64ee..e61e8fc 100644
--- a/bindings/ocaml/linker/llvm_linker.ml
+++ b/bindings/ocaml/linker/llvm_linker.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_linker.ml - LLVM OCaml Interface ------------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/linker/llvm_linker.mli b/bindings/ocaml/linker/llvm_linker.mli
index 5f558ff..ed8f0b3 100644
--- a/bindings/ocaml/linker/llvm_linker.mli
+++ b/bindings/ocaml/linker/llvm_linker.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_linker.mli - LLVM OCaml Interface -----------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/llvm/llvm.ml b/bindings/ocaml/llvm/llvm.ml
index 5612fae..f3ff600 100644
--- a/bindings/ocaml/llvm/llvm.ml
+++ b/bindings/ocaml/llvm/llvm.ml
@@ -1,9 +1,8 @@
 (*===-- llvm/llvm.ml - LLVM OCaml Interface -------------------------------===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
@@ -245,6 +244,8 @@
   | CatchPad
   | CleanupPad
   | CatchSwitch
+  | FNeg
+  | CallBr
 end
 
 module LandingPadClauseTy = struct
diff --git a/bindings/ocaml/llvm/llvm.mli b/bindings/ocaml/llvm/llvm.mli
index f12eb6e..6e145fa 100644
--- a/bindings/ocaml/llvm/llvm.mli
+++ b/bindings/ocaml/llvm/llvm.mli
@@ -1,9 +1,8 @@
 (*===-- llvm/llvm.mli - LLVM OCaml Interface ------------------------------===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
@@ -267,6 +266,8 @@
   | CatchPad
   | CleanupPad
   | CatchSwitch
+  | FNeg
+  | CallBr
 end
 
 (** The type of a clause of a [landingpad] instruction.
diff --git a/bindings/ocaml/llvm/llvm_ocaml.c b/bindings/ocaml/llvm/llvm_ocaml.c
index cdf6c6a..6af34bd 100644
--- a/bindings/ocaml/llvm/llvm_ocaml.c
+++ b/bindings/ocaml/llvm/llvm_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- llvm_ocaml.c - LLVM OCaml Glue --------------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
@@ -1534,7 +1534,7 @@
   if (!LLVMIsAInstruction(Inst))
       failwith("Not an instruction");
   o = LLVMGetInstructionOpcode(Inst);
-  assert (o <= LLVMCatchSwitch);
+  assert (o <= LLVMCallBr);
   return Val_int(o);
 }
 
diff --git a/bindings/ocaml/target/llvm_target.ml b/bindings/ocaml/target/llvm_target.ml
index 9e6b706..0922ebe 100644
--- a/bindings/ocaml/target/llvm_target.ml
+++ b/bindings/ocaml/target/llvm_target.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_target.ml - LLVM OCaml Interface ------------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/target/llvm_target.mli b/bindings/ocaml/target/llvm_target.mli
index c59308c..8d31079 100644
--- a/bindings/ocaml/target/llvm_target.mli
+++ b/bindings/ocaml/target/llvm_target.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_target.mli - LLVM OCaml Interface -----------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/target/target_ocaml.c b/bindings/ocaml/target/target_ocaml.c
index 8872f42..cf48fbe 100644
--- a/bindings/ocaml/target/target_ocaml.c
+++ b/bindings/ocaml/target/target_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- target_ocaml.c - LLVM OCaml Glue ------------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/transforms/ipo/ipo_ocaml.c b/bindings/ocaml/transforms/ipo/ipo_ocaml.c
index 9d8fb1e..e4226d8 100644
--- a/bindings/ocaml/transforms/ipo/ipo_ocaml.c
+++ b/bindings/ocaml/transforms/ipo/ipo_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- ipo_ocaml.c - LLVM OCaml Glue ---------------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/transforms/ipo/llvm_ipo.ml b/bindings/ocaml/transforms/ipo/llvm_ipo.ml
index 1af7d67..cc6b050 100644
--- a/bindings/ocaml/transforms/ipo/llvm_ipo.ml
+++ b/bindings/ocaml/transforms/ipo/llvm_ipo.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_ipo.ml - LLVM OCaml Interface --------------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/ipo/llvm_ipo.mli b/bindings/ocaml/transforms/ipo/llvm_ipo.mli
index 09a4860..4ae988d 100644
--- a/bindings/ocaml/transforms/ipo/llvm_ipo.mli
+++ b/bindings/ocaml/transforms/ipo/llvm_ipo.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_ipo.mli - LLVM OCaml Interface -------------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.ml b/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.ml
index 60df446..f143eaf 100644
--- a/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.ml
+++ b/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_passmgr_builder.ml - LLVM OCaml Interface --------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.mli b/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.mli
index ce162b1..8bb1005 100644
--- a/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.mli
+++ b/bindings/ocaml/transforms/passmgr_builder/llvm_passmgr_builder.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_passmgr_builder.mli - LLVM OCaml Interface -------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/passmgr_builder/passmgr_builder_ocaml.c b/bindings/ocaml/transforms/passmgr_builder/passmgr_builder_ocaml.c
index a43863c..6d1f72e 100644
--- a/bindings/ocaml/transforms/passmgr_builder/passmgr_builder_ocaml.c
+++ b/bindings/ocaml/transforms/passmgr_builder/passmgr_builder_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- passmgr_builder_ocaml.c - LLVM OCaml Glue ---------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.ml b/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.ml
index dcaf7e5..0c99b0f 100644
--- a/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.ml
+++ b/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_scalar_opts.ml - LLVM OCaml Interface ------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.mli b/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.mli
index 6767c00..76d86dd 100644
--- a/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.mli
+++ b/bindings/ocaml/transforms/scalar_opts/llvm_scalar_opts.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_scalar_opts.mli - LLVM OCaml Interface -----------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/scalar_opts/scalar_opts_ocaml.c b/bindings/ocaml/transforms/scalar_opts/scalar_opts_ocaml.c
index 0b52f36..cb3d50d 100644
--- a/bindings/ocaml/transforms/scalar_opts/scalar_opts_ocaml.c
+++ b/bindings/ocaml/transforms/scalar_opts/scalar_opts_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- scalar_opts_ocaml.c - LLVM OCaml Glue -------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/transforms/utils/llvm_transform_utils.ml b/bindings/ocaml/transforms/utils/llvm_transform_utils.ml
index 135efe2..20a50b1 100644
--- a/bindings/ocaml/transforms/utils/llvm_transform_utils.ml
+++ b/bindings/ocaml/transforms/utils/llvm_transform_utils.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_transform_utils.ml - LLVM OCaml Interface --------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/utils/llvm_transform_utils.mli b/bindings/ocaml/transforms/utils/llvm_transform_utils.mli
index 1c2b07c..536f41d 100644
--- a/bindings/ocaml/transforms/utils/llvm_transform_utils.mli
+++ b/bindings/ocaml/transforms/utils/llvm_transform_utils.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_transform_utils.mli - LLVM OCaml Interface -------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/utils/transform_utils_ocaml.c b/bindings/ocaml/transforms/utils/transform_utils_ocaml.c
index f2c50d9..918eec1 100644
--- a/bindings/ocaml/transforms/utils/transform_utils_ocaml.c
+++ b/bindings/ocaml/transforms/utils/transform_utils_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- transform_utils_ocaml.c - LLVM OCaml Glue ---------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/ocaml/transforms/vectorize/llvm_vectorize.ml b/bindings/ocaml/transforms/vectorize/llvm_vectorize.ml
index f9f6be2..a2e280e 100644
--- a/bindings/ocaml/transforms/vectorize/llvm_vectorize.ml
+++ b/bindings/ocaml/transforms/vectorize/llvm_vectorize.ml
@@ -1,9 +1,8 @@
 (*===-- llvm_vectorize.ml - LLVM OCaml Interface --------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/vectorize/llvm_vectorize.mli b/bindings/ocaml/transforms/vectorize/llvm_vectorize.mli
index f9b4ce5..7376d9e 100644
--- a/bindings/ocaml/transforms/vectorize/llvm_vectorize.mli
+++ b/bindings/ocaml/transforms/vectorize/llvm_vectorize.mli
@@ -1,9 +1,8 @@
 (*===-- llvm_vectorize.mli - LLVM OCaml Interface -------------*- OCaml -*-===*
  *
- *                     The LLVM Compiler Infrastructure
- *
- * This file is distributed under the University of Illinois Open Source
- * License. See LICENSE.TXT for details.
+ * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+ * See https://llvm.org/LICENSE.txt for license information.
+ * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  *===----------------------------------------------------------------------===*)
 
diff --git a/bindings/ocaml/transforms/vectorize/vectorize_ocaml.c b/bindings/ocaml/transforms/vectorize/vectorize_ocaml.c
index dcd9231..ba9c132 100644
--- a/bindings/ocaml/transforms/vectorize/vectorize_ocaml.c
+++ b/bindings/ocaml/transforms/vectorize/vectorize_ocaml.c
@@ -1,9 +1,9 @@
 /*===-- vectorize_ocaml.c - LLVM OCaml Glue ---------------------*- C++ -*-===*\
 |*                                                                            *|
-|*                     The LLVM Compiler Infrastructure                       *|
-|*                                                                            *|
-|* This file is distributed under the University of Illinois Open Source      *|
-|* License. See LICENSE.TXT for details.                                      *|
+|* Part of the LLVM Project, under the Apache License v2.0 with LLVM          *|
+|* Exceptions.                                                                *|
+|* See https://llvm.org/LICENSE.txt for license information.                  *|
+|* SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception                    *|
 |*                                                                            *|
 |*===----------------------------------------------------------------------===*|
 |*                                                                            *|
diff --git a/bindings/python/llvm/common.py b/bindings/python/llvm/common.py
index b177f7f..c29c5ee 100644
--- a/bindings/python/llvm/common.py
+++ b/bindings/python/llvm/common.py
@@ -1,9 +1,8 @@
 #===- common.py - Python LLVM Bindings -----------------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
diff --git a/bindings/python/llvm/core.py b/bindings/python/llvm/core.py
index 81e354a..4d90f86 100644
--- a/bindings/python/llvm/core.py
+++ b/bindings/python/llvm/core.py
@@ -1,9 +1,8 @@
 #===- core.py - Python LLVM Bindings -------------------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 from __future__ import print_function
diff --git a/bindings/python/llvm/disassembler.py b/bindings/python/llvm/disassembler.py
index f2df275..7562558 100644
--- a/bindings/python/llvm/disassembler.py
+++ b/bindings/python/llvm/disassembler.py
@@ -1,9 +1,8 @@
 #===- disassembler.py - Python LLVM Bindings -----------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
diff --git a/bindings/python/llvm/enumerations.py b/bindings/python/llvm/enumerations.py
index f49d2fa..ebb39a4 100644
--- a/bindings/python/llvm/enumerations.py
+++ b/bindings/python/llvm/enumerations.py
@@ -1,9 +1,8 @@
 #===- enumerations.py - Python LLVM Enumerations -------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
diff --git a/bindings/python/llvm/object.py b/bindings/python/llvm/object.py
index b427113..e8841b6 100644
--- a/bindings/python/llvm/object.py
+++ b/bindings/python/llvm/object.py
@@ -1,9 +1,8 @@
 #===- object.py - Python Object Bindings --------------------*- python -*--===#
 #
-#                     The LLVM Compiler Infrastructure
-#
-# This file is distributed under the University of Illinois Open Source
-# License. See LICENSE.TXT for details.
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 #===------------------------------------------------------------------------===#
 
diff --git a/cmake/config-ix.cmake b/cmake/config-ix.cmake
index 900c35e..5bf301f 100644
--- a/cmake/config-ix.cmake
+++ b/cmake/config-ix.cmake
@@ -28,7 +28,6 @@
 check_include_file(errno.h HAVE_ERRNO_H)
 check_include_file(fcntl.h HAVE_FCNTL_H)
 check_include_file(link.h HAVE_LINK_H)
-check_include_file(malloc.h HAVE_MALLOC_H)
 check_include_file(malloc/malloc.h HAVE_MALLOC_MALLOC_H)
 if( NOT PURE_WINDOWS )
   check_include_file(pthread.h HAVE_PTHREAD_H)
@@ -208,7 +207,6 @@
 check_symbol_exists(getrlimit "sys/types.h;sys/time.h;sys/resource.h" HAVE_GETRLIMIT)
 check_symbol_exists(posix_spawn spawn.h HAVE_POSIX_SPAWN)
 check_symbol_exists(pread unistd.h HAVE_PREAD)
-check_symbol_exists(realpath stdlib.h HAVE_REALPATH)
 check_symbol_exists(sbrk unistd.h HAVE_SBRK)
 check_symbol_exists(strerror string.h HAVE_STRERROR)
 check_symbol_exists(strerror_r string.h HAVE_STRERROR_R)
@@ -325,6 +323,15 @@
   unset(HAVE_FFI_CALL CACHE)
 endif( LLVM_ENABLE_FFI )
 
+# Whether we can use std::is_trivially_copyable to verify llvm::is_trivially_copyable.
+CHECK_CXX_SOURCE_COMPILES("
+#include <type_traits>
+struct T { int val; };
+static_assert(std::is_trivially_copyable<T>::value, \"ok\");
+int main() { return 0;}
+" HAVE_STD_IS_TRIVIALLY_COPYABLE)
+
+
 # Define LLVM_HAS_ATOMICS if gcc or MSVC atomic builtins are supported.
 include(CheckAtomic)
 
@@ -386,12 +393,16 @@
   set(LLVM_NATIVE_ARCH Sparc)
 elseif (LLVM_NATIVE_ARCH MATCHES "powerpc")
   set(LLVM_NATIVE_ARCH PowerPC)
+elseif (LLVM_NATIVE_ARCH MATCHES "ppc64le")
+  set(LLVM_NATIVE_ARCH PowerPC)
 elseif (LLVM_NATIVE_ARCH MATCHES "aarch64")
   set(LLVM_NATIVE_ARCH AArch64)
 elseif (LLVM_NATIVE_ARCH MATCHES "arm64")
   set(LLVM_NATIVE_ARCH AArch64)
 elseif (LLVM_NATIVE_ARCH MATCHES "arm")
   set(LLVM_NATIVE_ARCH ARM)
+elseif (LLVM_NATIVE_ARCH MATCHES "avr")
+  set(LLVM_NATIVE_ARCH AVR)
 elseif (LLVM_NATIVE_ARCH MATCHES "mips")
   set(LLVM_NATIVE_ARCH Mips)
 elseif (LLVM_NATIVE_ARCH MATCHES "xcore")
diff --git a/cmake/modules/AddLLVM.cmake b/cmake/modules/AddLLVM.cmake
index 4dbc0dd..d10831f 100644
--- a/cmake/modules/AddLLVM.cmake
+++ b/cmake/modules/AddLLVM.cmake
@@ -21,6 +21,10 @@
   else()
     if(LLVM_COMPILER_IS_GCC_COMPATIBLE)
       list(APPEND LLVM_COMPILE_FLAGS "-fno-exceptions")
+      if(NOT LLVM_ENABLE_UNWIND_TABLES)
+        list(APPEND LLVM_COMPILE_FLAGS "-fno-unwind-tables")
+        list(APPEND LLVM_COMPILE_FLAGS "-fno-asynchronous-unwind-tables")
+      endif()
     elseif(MSVC)
       list(APPEND LLVM_COMPILE_DEFINITIONS _HAS_EXCEPTIONS=0)
       list(APPEND LLVM_COMPILE_FLAGS "/EHs-c-")
@@ -221,7 +225,8 @@
       elseif(${CMAKE_SYSTEM_NAME} MATCHES "SunOS")
         set_property(TARGET ${target_name} APPEND_STRING PROPERTY
                      LINK_FLAGS " -Wl,-z -Wl,discard-unused=sections")
-      elseif(NOT WIN32 AND NOT LLVM_LINKER_IS_GOLD AND NOT ${CMAKE_SYSTEM_NAME} MATCHES "OpenBSD")
+      elseif(NOT WIN32 AND NOT LLVM_LINKER_IS_GOLD AND
+             NOT ${CMAKE_SYSTEM_NAME} MATCHES "OpenBSD|AIX")
         # Object files are compiled with -ffunction-data-sections.
         # Versions of bfd ld < 2.23.1 have a bug in --gc-sections that breaks
         # tools that use plugins. Always pass --gc-sections once we require
@@ -229,6 +234,11 @@
         set_property(TARGET ${target_name} APPEND_STRING PROPERTY
                      LINK_FLAGS " -Wl,--gc-sections")
       endif()
+    else() #LLVM_NO_DEAD_STRIP
+      if(${CMAKE_SYSTEM_NAME} MATCHES "AIX")
+        set_property(TARGET ${target_name} APPEND_STRING PROPERTY
+                     LINK_FLAGS " -Wl,-bnogc")
+      endif()
     endif()
   endif()
 endfunction(add_link_opts)
@@ -380,7 +390,7 @@
 function(llvm_add_library name)
   cmake_parse_arguments(ARG
     "MODULE;SHARED;STATIC;OBJECT;DISABLE_LLVM_LINK_LLVM_DYLIB;SONAME;NO_INSTALL_RPATH"
-    "OUTPUT_NAME;PLUGIN_TOOL"
+    "OUTPUT_NAME;PLUGIN_TOOL;ENTITLEMENTS"
     "ADDITIONAL_HEADERS;DEPENDS;LINK_COMPONENTS;LINK_LIBS;OBJLIBS"
     ${ARGN})
   list(APPEND LLVM_COMMON_DEPENDS ${ARG_DEPENDS})
@@ -584,7 +594,7 @@
 
   if(ARG_SHARED OR ARG_MODULE)
     llvm_externalize_debuginfo(${name})
-    llvm_codesign(${name})
+    llvm_codesign(${name} ENTITLEMENTS ${ARG_ENTITLEMENTS})
   endif()
 endfunction()
 
@@ -597,21 +607,35 @@
     set(prefix_option -DCMAKE_INSTALL_PREFIX="${ARG_PREFIX}")
   endif()
 
+  set(file_dependencies)
+  set(target_dependencies)
+  foreach(dependency ${ARG_DEPENDS})
+    if(TARGET ${dependency})
+      list(APPEND target_dependencies ${dependency})
+    else()
+      list(APPEND file_dependencies ${dependency})
+    endif()
+  endforeach()
+
   add_custom_target(${target}
-                    DEPENDS ${ARG_DEPENDS}
+                    DEPENDS ${file_dependencies}
                     COMMAND "${CMAKE_COMMAND}"
                             ${component_option}
                             ${prefix_option}
                             -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
                     USES_TERMINAL)
   add_custom_target(${target}-stripped
-                    DEPENDS ${ARG_DEPENDS}
+                    DEPENDS ${file_dependencies}
                     COMMAND "${CMAKE_COMMAND}"
                             ${component_option}
                             ${prefix_option}
                             -DCMAKE_INSTALL_DO_STRIP=1
                             -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
                     USES_TERMINAL)
+  if(target_dependencies)
+    add_dependencies(${target} ${target_dependencies})
+    add_dependencies(${target}-stripped ${target_dependencies})
+  endif()
 endfunction()
 
 macro(add_llvm_library name)
@@ -633,6 +657,7 @@
   # config file.
   if (NOT ARG_BUILDTREE_ONLY AND NOT ARG_MODULE)
     set_property( GLOBAL APPEND PROPERTY LLVM_LIBS ${name} )
+    set(in_llvm_libs YES)
   endif()
 
   if (ARG_MODULE AND NOT TARGET ${name})
@@ -644,7 +669,7 @@
     set_property(GLOBAL APPEND PROPERTY LLVM_EXPORTS_BUILDTREE_ONLY ${name})
   else()
     if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY OR ${name} STREQUAL "LTO" OR
-        ${name} STREQUAL "OptRemarks" OR
+        ${name} STREQUAL "Remarks" OR
         (LLVM_LINK_LLVM_DYLIB AND ${name} STREQUAL "LLVM"))
       set(install_dir lib${LLVM_LIBDIR_SUFFIX})
       if(ARG_MODULE OR ARG_SHARED OR BUILD_SHARED_LIBS)
@@ -662,7 +687,9 @@
         set(install_type LIBRARY)
       endif()
 
+      set(export_to_llvmexports)
       if(${name} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
+          (in_llvm_libs AND "llvm-libraries" IN_LIST LLVM_DISTRIBUTION_COMPONENTS) OR
           NOT LLVM_DISTRIBUTION_COMPONENTS)
         set(export_to_llvmexports EXPORT LLVMExports)
         set_property(GLOBAL PROPERTY LLVM_HAS_EXPORTS True)
@@ -855,6 +882,7 @@
     llvm-lib
     llvm-objdump
     llvm-rc
+    llvm-profdata
     )
 endif()
 
@@ -866,6 +894,7 @@
 
   if ( ${name} IN_LIST LLVM_TOOLCHAIN_TOOLS OR NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
     if( LLVM_BUILD_TOOLS )
+      set(export_to_llvmexports)
       if(${name} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
           NOT LLVM_DISTRIBUTION_COMPONENTS)
         set(export_to_llvmexports EXPORT LLVMExports)
@@ -911,18 +940,29 @@
 
   add_llvm_executable(${name} DISABLE_LLVM_LINK_LLVM_DYLIB ${ARGN})
   set_target_properties(${name} PROPERTIES FOLDER "Utils")
-  if( LLVM_INSTALL_UTILS AND LLVM_BUILD_UTILS )
-    install (TARGETS ${name}
-      RUNTIME DESTINATION ${LLVM_UTILS_INSTALL_DIR}
-      COMPONENT ${name})
-    if (NOT LLVM_ENABLE_IDE)
-      add_llvm_install_targets(install-${name}
-                               DEPENDS ${name}
-                               COMPONENT ${name})
+  if (NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
+    if (LLVM_INSTALL_UTILS AND LLVM_BUILD_UTILS)
+      set(export_to_llvmexports)
+      if (${name} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
+          NOT LLVM_DISTRIBUTION_COMPONENTS)
+        set(export_to_llvmexports EXPORT LLVMExports)
+        set_property(GLOBAL PROPERTY LLVM_HAS_EXPORTS True)
+      endif()
+
+      install(TARGETS ${name}
+              ${export_to_llvmexports}
+              RUNTIME DESTINATION ${LLVM_UTILS_INSTALL_DIR}
+              COMPONENT ${name})
+
+      if (NOT LLVM_ENABLE_IDE)
+        add_llvm_install_targets(install-${name}
+                                 DEPENDS ${name}
+                                 COMPONENT ${name})
+      endif()
+      set_property(GLOBAL APPEND PROPERTY LLVM_EXPORTS ${name})
+    elseif(LLVM_BUILD_UTILS)
+      set_property(GLOBAL APPEND PROPERTY LLVM_EXPORTS_BUILDTREE_ONLY ${name})
     endif()
-    set_property(GLOBAL APPEND PROPERTY LLVM_EXPORTS ${name})
-  elseif( LLVM_BUILD_UTILS )
-    set_property(GLOBAL APPEND PROPERTY LLVM_EXPORTS_BUILDTREE_ONLY ${name})
   endif()
 endmacro(add_llvm_utility name)
 
@@ -1280,7 +1320,6 @@
   cmake_parse_arguments(ARG "ALLOW_EXTERNAL" "" "" ${ARGN})
 
   if (ARG_ALLOW_EXTERNAL)
-    set(LLVM_DEFAULT_EXTERNAL_LIT "${LLVM_EXTERNAL_LIT}")
     set (LLVM_EXTERNAL_LIT "" CACHE STRING "Command used to spawn lit")
     if ("${LLVM_EXTERNAL_LIT}" STREQUAL "")
       set(LLVM_EXTERNAL_LIT "${LLVM_DEFAULT_EXTERNAL_LIT}")
@@ -1294,7 +1333,7 @@
         set(${base_dir} ${LIT_BASE_DIR} PARENT_SCOPE)
         return()
       else()
-        message(WARN "LLVM_EXTERNAL_LIT set to ${LLVM_EXTERNAL_LIT}, but the path does not exist.")
+        message(WARNING "LLVM_EXTERNAL_LIT set to ${LLVM_EXTERNAL_LIT}, but the path does not exist.")
       endif()
     endif()
   endif()
@@ -1584,14 +1623,21 @@
     endif()
   endif()
 
-  if(LLVM_EXTERNALIZE_DEBUGINFO_OUTPUT_DIR)
-    if(APPLE)
-      set(output_name "$<TARGET_FILE_NAME:${name}>.dSYM")
-      set(output_path "-o=${LLVM_EXTERNALIZE_DEBUGINFO_OUTPUT_DIR}/${output_name}")
-    endif()
-  endif()
-
   if(APPLE)
+    if(LLVM_EXTERNALIZE_DEBUGINFO_EXTENSION)
+      set(file_ext ${LLVM_EXTERNALIZE_DEBUGINFO_EXTENSION})
+    else()
+      set(file_ext dSYM)
+    endif()
+
+    set(output_name "$<TARGET_FILE_NAME:${name}>.${file_ext}")
+
+    if(LLVM_EXTERNALIZE_DEBUGINFO_OUTPUT_DIR)
+      set(output_path "-o=${LLVM_EXTERNALIZE_DEBUGINFO_OUTPUT_DIR}/${output_name}")
+    else()
+      set(output_path "-o=${output_name}")
+    endif()
+
     if(CMAKE_CXX_FLAGS MATCHES "-flto"
       OR CMAKE_CXX_FLAGS_${uppercase_CMAKE_BUILD_TYPE} MATCHES "-flto")
 
@@ -1708,35 +1754,38 @@
   set_target_properties(${name} PROPERTIES RULE_LAUNCH_COMPILE ${sandbox_command})
 endfunction()
 
-# Figure out if we can track VC revisions.
-function(find_first_existing_file out_var)
-  foreach(file ${ARGN})
-    if(EXISTS "${file}")
-      set(${out_var} "${file}" PARENT_SCOPE)
-      return()
-    endif()
-  endforeach()
-endfunction()
-
-macro(find_first_existing_vc_file out_var path)
-    find_program(git_executable NAMES git git.exe git.cmd)
-    # Run from a subdirectory to force git to print an absolute path.
-    execute_process(COMMAND ${git_executable} rev-parse --git-dir
-      WORKING_DIRECTORY ${path}/cmake
-      RESULT_VARIABLE git_result
-      OUTPUT_VARIABLE git_dir
-      ERROR_QUIET)
-    if(git_result EQUAL 0)
-      string(STRIP "${git_dir}" git_dir)
-      set(${out_var} "${git_dir}/logs/HEAD")
-      # some branchless cases (e.g. 'repo') may not yet have .git/logs/HEAD
-      if (NOT EXISTS "${git_dir}/logs/HEAD")
-        file(WRITE "${git_dir}/logs/HEAD" "")
+function(find_first_existing_vc_file path out_var)
+  if(NOT EXISTS "${path}")
+    return()
+  endif()
+  if(EXISTS "${path}/.svn")
+    set(svn_files
+      "${path}/.svn/wc.db"   # SVN 1.7
+      "${path}/.svn/entries" # SVN 1.6
+    )
+    foreach(file IN LISTS svn_files)
+      if(EXISTS "${file}")
+        set(${out_var} "${file}" PARENT_SCOPE)
+        return()
       endif()
-    else()
-      find_first_existing_file(${out_var}
-        "${path}/.svn/wc.db"   # SVN 1.7
-        "${path}/.svn/entries" # SVN 1.6
-      )
+    endforeach()
+  else()
+    find_package(Git)
+    if(GIT_FOUND)
+      execute_process(COMMAND ${GIT_EXECUTABLE} rev-parse --git-dir
+        WORKING_DIRECTORY ${path}
+        RESULT_VARIABLE git_result
+        OUTPUT_VARIABLE git_output
+        ERROR_QUIET)
+      if(git_result EQUAL 0)
+        string(STRIP "${git_output}" git_output)
+        get_filename_component(git_dir ${git_output} ABSOLUTE BASE_DIR ${path})
+        # Some branchless cases (e.g. 'repo') may not yet have .git/logs/HEAD
+        if (NOT EXISTS "${git_dir}/logs/HEAD")
+          file(WRITE "${git_dir}/logs/HEAD" "")
+        endif()
+        set(${out_var} "${git_dir}/logs/HEAD" PARENT_SCOPE)
+      endif()
     endif()
-endmacro()
+  endif()
+endfunction()
diff --git a/cmake/modules/CMakeLists.txt b/cmake/modules/CMakeLists.txt
index f5cc000..9cf22b4 100644
--- a/cmake/modules/CMakeLists.txt
+++ b/cmake/modules/CMakeLists.txt
@@ -41,6 +41,12 @@
   "${LLVM_MAIN_INCLUDE_DIR}"
   "${LLVM_INCLUDE_DIR}"
   )
+set(LLVM_CONFIG_INCLUDE_DIR
+  "${LLVM_INCLUDE_DIR}"
+  )
+set(LLVM_CONFIG_MAIN_INCLUDE_DIR
+  "${LLVM_MAIN_INCLUDE_DIR}"
+  )
 set(LLVM_CONFIG_LIBRARY_DIRS
   "${LLVM_LIBRARY_DIR}"
   )
@@ -91,6 +97,8 @@
 get_filename_component(LLVM_INSTALL_PREFIX \"\${LLVM_INSTALL_PREFIX}\" PATH)")
 endforeach(p)
 set(LLVM_CONFIG_INCLUDE_DIRS "\${LLVM_INSTALL_PREFIX}/include")
+set(LLVM_CONFIG_INCLUDE_DIR "${LLVM_CONFIG_INCLUDE_DIRS}")
+set(LLVM_CONFIG_MAIN_INCLUDE_DIR "${LLVM_CONFIG_INCLUDE_DIRS}")
 set(LLVM_CONFIG_LIBRARY_DIRS "\${LLVM_INSTALL_PREFIX}/lib\${LLVM_LIBDIR_SUFFIX}")
 set(LLVM_CONFIG_CMAKE_DIR "\${LLVM_INSTALL_PREFIX}/${LLVM_INSTALL_PACKAGE_DIR}")
 set(LLVM_CONFIG_BINARY_DIR "\${LLVM_INSTALL_PREFIX}")
diff --git a/cmake/modules/CheckCompilerVersion.cmake b/cmake/modules/CheckCompilerVersion.cmake
index adf500a..1ee7832 100644
--- a/cmake/modules/CheckCompilerVersion.cmake
+++ b/cmake/modules/CheckCompilerVersion.cmake
@@ -1,52 +1,108 @@
-# Check if the host compiler is new enough. LLVM requires at least GCC 4.8,
-# MSVC 2015 (Update 3), or Clang 3.1.
+# Check if the host compiler is new enough.
+# These versions are updated based on the following policy:
+#   llvm.org/docs/DeveloperPolicy.html#toolchain
 
 include(CheckCXXSourceCompiles)
 
-if(NOT DEFINED LLVM_COMPILER_CHECKED)
-  set(LLVM_COMPILER_CHECKED ON)
+set(GCC_MIN 4.8)
+set(GCC_SOFT_ERROR 5.1)
+set(CLANG_MIN 3.1)
+set(CLANG_SOFT_ERROR 3.5)
+set(APPLECLANG_MIN 3.1)
+set(APPLECLANG_SOFT_ERROR 6.0)
+set(MSVC_MIN 19.00.24213.1)
+set(MSVC_SOFT_ERROR 19.1)
 
-  if(NOT LLVM_FORCE_USE_OLD_TOOLCHAIN)
-    if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 4.8)
-        message(FATAL_ERROR "Host GCC version must be at least 4.8!")
-      endif()
-    elseif(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
-      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 3.1)
-        message(FATAL_ERROR "Host Clang version must be at least 3.1!")
-      endif()
+# Map the above GCC versions to dates: https://gcc.gnu.org/develop.html#timeline
+set(GCC_MIN_DATE 20130322)
+set(GCC_SOFT_ERROR_DATE 20150422)
 
-      if (CMAKE_CXX_SIMULATE_ID MATCHES "MSVC")
-        if (CMAKE_CXX_SIMULATE_VERSION VERSION_LESS 19.0)
-          message(FATAL_ERROR "Host Clang must have at least -fms-compatibility-version=19.0")
-        endif()
-        set(CLANG_CL 1)
-      elseif(NOT LLVM_ENABLE_LIBCXX)
-        # Otherwise, test that we aren't using too old of a version of libstdc++
-        # with the Clang compiler. This is tricky as there is no real way to
-        # check the version of libstdc++ directly. Instead we test for a known
-        # bug in libstdc++4.6 that is fixed in libstdc++4.7.
-        set(OLD_CMAKE_REQUIRED_FLAGS ${CMAKE_REQUIRED_FLAGS})
-        set(OLD_CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
-        set(CMAKE_REQUIRED_FLAGS "${CMAKE_REQUIRED_FLAGS} -std=c++0x")
-        check_cxx_source_compiles("
-#include <atomic>
-std::atomic<float> x(0.0f);
-int main() { return (float)x; }"
-          LLVM_NO_OLD_LIBSTDCXX)
-        if(NOT LLVM_NO_OLD_LIBSTDCXX)
-          message(FATAL_ERROR "Host Clang must be able to find libstdc++4.8 or newer!")
-        endif()
-        set(CMAKE_REQUIRED_FLAGS ${OLD_CMAKE_REQUIRED_FLAGS})
-        set(CMAKE_REQUIRED_LIBRARIES ${OLD_CMAKE_REQUIRED_LIBRARIES})
-      endif()
-    elseif(CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
-      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.0)
-        message(FATAL_ERROR "Host Visual Studio must be at least 2015")
-      elseif(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 19.00.24213.1)
-        message(WARNING "Host Visual Studio should at least be 2015 Update 3 (MSVC 19.00.24213.1)"
-          "  due to miscompiles from earlier versions")
+
+if(DEFINED LLVM_COMPILER_CHECKED)
+  return()
+endif()
+set(LLVM_COMPILER_CHECKED ON)
+
+if(LLVM_FORCE_USE_OLD_TOOLCHAIN)
+  return()
+endif()
+
+function(check_compiler_version NAME NICE_NAME MINIMUM_VERSION SOFT_ERROR_VERSION)
+  if(NOT CMAKE_CXX_COMPILER_ID STREQUAL NAME)
+    return()
+  endif()
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS MINIMUM_VERSION)
+    message(FATAL_ERROR "Host ${NICE_NAME} version must be at least ${MINIMUM_VERSION}, your version is ${CMAKE_CXX_COMPILER_VERSION}.")
+  elseif(CMAKE_CXX_COMPILER_VERSION VERSION_LESS SOFT_ERROR_VERSION)
+    if(LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN)
+      message(WARNING "Host ${NICE_NAME} version should be at least ${SOFT_ERROR_VERSION} because LLVM will soon use new C++ features which your toolchain version doesn't support. Your version is ${CMAKE_CXX_COMPILER_VERSION}. Ignoring because you've set LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
+    else()
+      message(FATAL_ERROR "Host ${NICE_NAME} version should be at least ${SOFT_ERROR_VERSION} because LLVM will soon use new C++ features which your toolchain version doesn't support. Your version is ${CMAKE_CXX_COMPILER_VERSION}. You can temporarily opt out using LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
+    endif()
+  endif()
+endfunction(check_compiler_version)
+
+check_compiler_version("GNU" "GCC" ${GCC_MIN} ${GCC_SOFT_ERROR})
+check_compiler_version("Clang" "Clang" ${CLANG_MIN} ${CLANG_SOFT_ERROR})
+check_compiler_version("AppleClang" "Apple Clang" ${APPLECLANG_MIN} ${APPLECLANG_SOFT_ERROR})
+check_compiler_version("MSVC" "Visual Studio" ${MSVC_MIN} ${MSVC_SOFT_ERROR})
+
+if(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
+  if (CMAKE_CXX_SIMULATE_ID MATCHES "MSVC")
+    if (CMAKE_CXX_SIMULATE_VERSION VERSION_LESS MSVC_MIN)
+      message(FATAL_ERROR "Host Clang must have at least -fms-compatibility-version=${MSVC_MIN}, your version is ${CMAKE_CXX_SIMULATE_VERSION}.")
+    endif()
+    set(CLANG_CL 1)
+  elseif(NOT LLVM_ENABLE_LIBCXX)
+    # Test that we aren't using too old of a version of libstdc++.
+    set(OLD_CMAKE_REQUIRED_FLAGS ${CMAKE_REQUIRED_FLAGS})
+    set(OLD_CMAKE_REQUIRED_LIBRARIES ${CMAKE_REQUIRED_LIBRARIES})
+    set(CMAKE_REQUIRED_FLAGS "${CMAKE_REQUIRED_FLAGS} -std=c++0x")
+    # Test for libstdc++ version of at least 4.8 by checking for _ZNKSt17bad_function_call4whatEv.
+    # Note: We should check _GLIBCXX_RELEASE when possible (i.e., for GCC 7.1 and up).
+    check_cxx_source_compiles("
+#include <iosfwd>
+#if defined(__GLIBCXX__)
+#if __GLIBCXX__ < ${GCC_MIN_DATE}
+#error Unsupported libstdc++ version
+#endif
+#endif
+#if defined(__GLIBCXX__)
+extern const char _ZNKSt17bad_function_call4whatEv[];
+const char *chk = _ZNKSt17bad_function_call4whatEv;
+#else
+const char *chk = \"\";
+#endif
+int main() { ++chk; return 0; }
+"
+      LLVM_LIBSTDCXX_MIN)
+    if(NOT LLVM_LIBSTDCXX_MIN)
+      message(FATAL_ERROR "libstdc++ version must be at least ${GCC_MIN}.")
+    endif()
+    # Test for libstdc++ version of at least 5.1 by checking for std::iostream_category().
+    # Note: We should check _GLIBCXX_RELEASE when possible (i.e., for GCC 7.1 and up).
+    check_cxx_source_compiles("
+#include <iosfwd>
+#if defined(__GLIBCXX__)
+#if __GLIBCXX__ < ${GCC_SOFT_ERROR_DATE}
+#error Unsupported libstdc++ version
+#endif
+#endif
+#if defined(__GLIBCXX__)
+#include <ios>
+void foo(void) { (void) std::iostream_category(); }
+#endif
+int main() { return 0; }
+"
+      LLVM_LIBSTDCXX_SOFT_ERROR)
+    if(NOT LLVM_LIBSTDCXX_SOFT_ERROR)
+      if(LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN)
+        message(WARNING "libstdc++ version should be at least ${GCC_SOFT_ERROR} because LLVM will soon use new C++ features which your toolchain version doesn't support. Ignoring because you've set LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
+      else()
+        message(FATAL_ERROR "libstdc++ version should be at least ${GCC_SOFT_ERROR} because LLVM will soon use new C++ features which your toolchain version doesn't support. You can temporarily opt out using LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN, but very soon your toolchain won't be supported.")
       endif()
     endif()
+    set(CMAKE_REQUIRED_FLAGS ${OLD_CMAKE_REQUIRED_FLAGS})
+    set(CMAKE_REQUIRED_LIBRARIES ${OLD_CMAKE_REQUIRED_LIBRARIES})
   endif()
 endif()
diff --git a/cmake/modules/CrossCompile.cmake b/cmake/modules/CrossCompile.cmake
index b239816..d6b4161 100644
--- a/cmake/modules/CrossCompile.cmake
+++ b/cmake/modules/CrossCompile.cmake
@@ -1,3 +1,5 @@
+include(LLVMExternalProjectUtils)
+
 function(llvm_create_cross_target_internal target_name toolchain buildtype)
 
   if(NOT DEFINED LLVM_${target_name}_BUILD)
@@ -43,6 +45,11 @@
   string(REPLACE ";" "$<SEMICOLON>" experimental_targets_to_build_arg
          "${LLVM_EXPERIMENTAL_TARGETS_TO_BUILD}")
 
+  string(REPLACE ";" "$<SEMICOLON>" llvm_enable_projects_arg
+         "${LLVM_ENABLE_PROJECTS}")
+  string(REPLACE ";" "$<SEMICOLON>" llvm_external_projects_arg
+         "${LLVM_EXTERNAL_PROJECTS}")
+
   add_custom_command(OUTPUT ${LLVM_${target_name}_BUILD}/CMakeCache.txt
     COMMAND ${CMAKE_COMMAND} -G "${CMAKE_GENERATOR}"
         -DCMAKE_MAKE_PROGRAM="${CMAKE_MAKE_PROGRAM}"
@@ -52,6 +59,9 @@
         -DLLVM_EXPERIMENTAL_TARGETS_TO_BUILD="${experimental_targets_to_build_arg}"
         -DLLVM_DEFAULT_TARGET_TRIPLE="${TARGET_TRIPLE}"
         -DLLVM_TARGET_ARCH="${LLVM_TARGET_ARCH}"
+        -DLLVM_ENABLE_PROJECTS="${llvm_enable_projects_arg}"
+        -DLLVM_EXTERNAL_PROJECTS="${llvm_external_projects_arg}"
+        -DLLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN="${LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN}"
         ${build_type_flags} ${linker_flag} ${external_clang_dir}
     WORKING_DIRECTORY ${LLVM_${target_name}_BUILD}
     DEPENDS CREATE_LLVM_${target_name}
@@ -66,4 +76,29 @@
   llvm_create_cross_target_internal(${target_name} ${sysroot} ${CMAKE_BUILD_TYPE})
 endfunction()
 
+# Sets up a native build for a tool, used e.g. for cross-compilation and
+# LLVM_OPTIMIZED_TABLEGEN. Always builds in Release.
+# - target: The target to build natively
+# - output_path_var: A variable name which receives the path to the built target
+# - DEPENDS: Any additional dependencies for the target
+function(build_native_tool target output_path_var)
+  cmake_parse_arguments(ARG "" "" "DEPENDS" ${ARGN})
+
+  if(CMAKE_CONFIGURATION_TYPES)
+    set(output_path "${LLVM_NATIVE_BUILD}/Release/bin/${target}")
+  else()
+    set(output_path "${LLVM_NATIVE_BUILD}/bin/${target}")
+  endif()
+
+  llvm_ExternalProject_BuildCmd(build_cmd ${target} ${LLVM_NATIVE_BUILD}
+                                CONFIGURATION Release)
+  add_custom_command(OUTPUT "${output_path}"
+                     COMMAND ${build_cmd}
+                     DEPENDS CONFIGURE_LLVM_NATIVE ${ARG_DEPENDS}
+                     WORKING_DIRECTORY "${LLVM_NATIVE_BUILD}"
+                     COMMENT "Building native ${target}..."
+                     USES_TERMINAL)
+  set(${output_path_var} "${output_path}" PARENT_SCOPE)
+endfunction()
+
 llvm_create_cross_target_internal(NATIVE "" Release)
diff --git a/cmake/modules/FindZ3.cmake b/cmake/modules/FindZ3.cmake
new file mode 100644
index 0000000..0429427
--- /dev/null
+++ b/cmake/modules/FindZ3.cmake
@@ -0,0 +1,110 @@
+INCLUDE(CheckCXXSourceRuns)
+
+# Function to check Z3's version
+function(check_z3_version z3_include z3_lib)
+  # The program that will be executed to print Z3's version.
+  file(WRITE ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/testz3.c
+       "#include <assert.h>
+        #include <z3.h>
+        int main() {
+          unsigned int major, minor, build, rev;
+          Z3_get_version(&major, &minor, &build, &rev);
+          printf(\"%u.%u.%u\", major, minor, build);
+          return 0;
+       }")
+
+  # Get lib path
+  get_filename_component(z3_lib_path ${z3_lib} PATH)
+
+  try_run(
+    Z3_RETURNCODE
+    Z3_COMPILED
+    ${CMAKE_BINARY_DIR}
+    ${CMAKE_BINARY_DIR}${CMAKE_FILES_DIRECTORY}/CMakeTmp/testz3.c
+    COMPILE_DEFINITIONS -I"${z3_include}"
+    LINK_LIBRARIES -L${z3_lib_path} -lz3
+    RUN_OUTPUT_VARIABLE SRC_OUTPUT
+  )
+
+  if(Z3_COMPILED)
+    string(REGEX REPLACE "([0-9]*\\.[0-9]*\\.[0-9]*\\.[0-9]*)" "\\1"
+           z3_version "${SRC_OUTPUT}")
+    set(Z3_VERSION_STRING ${z3_version} PARENT_SCOPE)
+  endif()
+endfunction(check_z3_version)
+
+# Looking for Z3 in LLVM_Z3_INSTALL_DIR
+find_path(Z3_INCLUDE_DIR NAMES z3.h
+  NO_DEFAULT_PATH
+  PATHS ${LLVM_Z3_INSTALL_DIR}/include
+  PATH_SUFFIXES libz3 z3
+  )
+
+find_library(Z3_LIBRARIES NAMES z3 libz3
+  NO_DEFAULT_PATH
+  PATHS ${LLVM_Z3_INSTALL_DIR}
+  PATH_SUFFIXES lib bin
+  )
+
+# If Z3 has not been found in LLVM_Z3_INSTALL_DIR look in the default directories
+find_path(Z3_INCLUDE_DIR NAMES z3.h
+  PATH_SUFFIXES libz3 z3
+  )
+
+find_library(Z3_LIBRARIES NAMES z3 libz3
+  PATH_SUFFIXES lib bin
+  )
+
+# Searching for the version of the Z3 library is a best-effort task
+unset(Z3_VERSION_STRING)
+
+# First, try to check it dynamically, by compiling a small program that
+# prints Z3's version
+if(Z3_INCLUDE_DIR AND Z3_LIBRARIES)
+  # We do not have the Z3 binary to query for a version. Try to use
+  # a small C++ program to detect it via the Z3_get_version() API call.
+  check_z3_version(${Z3_INCLUDE_DIR} ${Z3_LIBRARIES})
+endif()
+
+# If the dynamic check fails, we might be cross compiling: if that's the case,
+# check the version in the headers, otherwise, fail with a message
+if(NOT Z3_VERSION_STRING AND (CMAKE_CROSSCOMPILING AND
+                              Z3_INCLUDE_DIR AND
+                              EXISTS "${Z3_INCLUDE_DIR}/z3_version.h"))
+  # TODO: print message warning that we couldn't find a compatible lib?
+
+  # Z3 4.8.1+ has the version is in a public header.
+  file(STRINGS "${Z3_INCLUDE_DIR}/z3_version.h"
+       z3_version_str REGEX "^#define[\t ]+Z3_MAJOR_VERSION[\t ]+.*")
+  string(REGEX REPLACE "^.*Z3_MAJOR_VERSION[\t ]+([0-9]).*$" "\\1"
+         Z3_MAJOR "${z3_version_str}")
+
+  file(STRINGS "${Z3_INCLUDE_DIR}/z3_version.h"
+       z3_version_str REGEX "^#define[\t ]+Z3_MINOR_VERSION[\t ]+.*")
+  string(REGEX REPLACE "^.*Z3_MINOR_VERSION[\t ]+([0-9]).*$" "\\1"
+         Z3_MINOR "${z3_version_str}")
+
+  file(STRINGS "${Z3_INCLUDE_DIR}/z3_version.h"
+       z3_version_str REGEX "^#define[\t ]+Z3_BUILD_NUMBER[\t ]+.*")
+  string(REGEX REPLACE "^.*Z3_BUILD_VERSION[\t ]+([0-9]).*$" "\\1"
+         Z3_BUILD "${z3_version_str}")
+
+  set(Z3_VERSION_STRING ${Z3_MAJOR}.${Z3_MINOR}.${Z3_BUILD})
+  unset(z3_version_str)
+endif()
+
+if(NOT Z3_VERSION_STRING)
+  # Give up: we are unable to obtain a version of the Z3 library. Be
+  # conservative and force the found version to 0.0.0 to make version
+  # checks always fail.
+  set(Z3_VERSION_STRING "0.0.0")
+endif()
+
+# handle the QUIETLY and REQUIRED arguments and set Z3_FOUND to TRUE if
+# all listed variables are TRUE
+include(FindPackageHandleStandardArgs)
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(Z3
+                                  REQUIRED_VARS Z3_LIBRARIES Z3_INCLUDE_DIR
+                                  VERSION_VAR Z3_VERSION_STRING)
+
+mark_as_advanced(Z3_INCLUDE_DIR Z3_LIBRARIES)
diff --git a/cmake/modules/GenerateVersionFromCVS.cmake b/cmake/modules/GenerateVersionFromCVS.cmake
deleted file mode 100644
index 6b1c719..0000000
--- a/cmake/modules/GenerateVersionFromCVS.cmake
+++ /dev/null
@@ -1,39 +0,0 @@
-# CMake project that writes Subversion revision information to a header.
-#
-# Input variables:
-#   SRC               - Source directory
-#   HEADER_FILE       - The header file to write
-#
-# The output header will contain macros FIRST_REPOSITORY and FIRST_REVISION,
-# and SECOND_REPOSITORY and SECOND_REVISION if requested, where "FIRST" and
-# "SECOND" are substituted with the names specified in the input variables.
-
-
-
-# Chop off cmake/modules/GetSVN.cmake
-get_filename_component(LLVM_DIR "${CMAKE_SCRIPT_MODE_FILE}" PATH)
-get_filename_component(LLVM_DIR "${LLVM_DIR}" PATH)
-get_filename_component(LLVM_DIR "${LLVM_DIR}" PATH)
-
-set(CMAKE_MODULE_PATH
-  ${CMAKE_MODULE_PATH}
-  "${LLVM_DIR}/cmake/modules")
-include(VersionFromVCS)
-
-# Handle strange terminals
-set(ENV{TERM} "dumb")
-
-function(append_info name path)
-  add_version_info_from_vcs(REVISION ${path})
-  string(STRIP "${REVISION}" REVISION)
-  file(APPEND "${HEADER_FILE}.txt"
-    "#define ${name} \"${REVISION}\"\n")
-endfunction()
-
-append_info(${NAME} "${SOURCE_DIR}")
-
-# Copy the file only if it has changed.
-execute_process(COMMAND ${CMAKE_COMMAND} -E copy_if_different
-  "${HEADER_FILE}.txt" "${HEADER_FILE}")
-file(REMOVE "${HEADER_FILE}.txt")
-
diff --git a/cmake/modules/GenerateVersionFromVCS.cmake b/cmake/modules/GenerateVersionFromVCS.cmake
new file mode 100644
index 0000000..d8ec54d
--- /dev/null
+++ b/cmake/modules/GenerateVersionFromVCS.cmake
@@ -0,0 +1,51 @@
+# CMake script that writes version control information to a header.
+#
+# Input variables:
+#   NAMES             - A list of names for each of the source directories.
+#   <NAME>_SOURCE_DIR - A path to source directory for each name in NAMES.
+#   HEADER_FILE       - The header file to write
+#
+# The output header will contain macros <NAME>_REPOSITORY and <NAME>_REVISION,
+# where "<NAME>" is substituted with the names specified in the input variables,
+# for each of the <NAME>_SOURCE_DIR given.
+
+get_filename_component(LLVM_CMAKE_DIR "${CMAKE_SCRIPT_MODE_FILE}" PATH)
+
+list(APPEND CMAKE_MODULE_PATH "${LLVM_CMAKE_DIR}")
+
+include(VersionFromVCS)
+
+# Handle strange terminals
+set(ENV{TERM} "dumb")
+
+function(append_info name path)
+  if(path)
+    get_source_info("${path}" revision repository)
+  endif()
+  if(revision)
+    file(APPEND "${HEADER_FILE}.tmp"
+      "#define ${name}_REVISION \"${revision}\"\n")
+  else()
+    file(APPEND "${HEADER_FILE}.tmp"
+      "#undef ${name}_REVISION\n")
+  endif()
+  if(repository)
+    file(APPEND "${HEADER_FILE}.tmp"
+      "#define ${name}_REPOSITORY \"${repository}\"\n")
+  else()
+    file(APPEND "${HEADER_FILE}.tmp"
+      "#undef ${name}_REPOSITORY\n")
+  endif()
+endfunction()
+
+foreach(name IN LISTS NAMES)
+  if(NOT DEFINED ${name}_SOURCE_DIR)
+    message(FATAL_ERROR "${name}_SOURCE_DIR is not defined")
+  endif()
+  append_info(${name} "${${name}_SOURCE_DIR}")
+endforeach()
+
+# Copy the file only if it has changed.
+execute_process(COMMAND ${CMAKE_COMMAND} -E copy_if_different
+  "${HEADER_FILE}.tmp" "${HEADER_FILE}")
+file(REMOVE "${HEADER_FILE}.tmp")
diff --git a/cmake/modules/GetHostTriple.cmake b/cmake/modules/GetHostTriple.cmake
index 7b84245..9a74ad6 100644
--- a/cmake/modules/GetHostTriple.cmake
+++ b/cmake/modules/GetHostTriple.cmake
@@ -23,7 +23,8 @@
     if( NOT TT_RV EQUAL 0 )
       message(FATAL_ERROR "Failed to execute ${config_guess}")
     endif( NOT TT_RV EQUAL 0 )
-    set( value ${TT_OUT} )
+    # Defer to dynamic detection of the host AIX version.
+    string(REGEX REPLACE "-aix[0-9][^-]*" "-aix" value ${TT_OUT})
   endif( MSVC )
   set( ${var} ${value} PARENT_SCOPE )
 endfunction( get_host_triple var )
diff --git a/cmake/modules/GetSVN.cmake b/cmake/modules/GetSVN.cmake
deleted file mode 100644
index f729395..0000000
--- a/cmake/modules/GetSVN.cmake
+++ /dev/null
@@ -1,141 +0,0 @@
-# CMake project that writes Subversion revision information to a header.
-#
-# Input variables:
-#   SOURCE_DIRS - A list of source directories.
-#   NAMES       - A list of macro prefixes for each of the source directories.
-#   HEADER_FILE - The header file to write
-#
-# The output header will contain macros <NAME>_REPOSITORY and <NAME>_REVISION,
-# where "<NAME>" and is substituted with the names specified in the input
-# variables, for each of the SOURCE_DIRS given.
-
-# Chop off cmake/modules/GetSVN.cmake
-get_filename_component(LLVM_DIR "${CMAKE_SCRIPT_MODE_FILE}" PATH)
-get_filename_component(LLVM_DIR "${LLVM_DIR}" PATH)
-get_filename_component(LLVM_DIR "${LLVM_DIR}" PATH)
-
-# Handle strange terminals
-set(ENV{TERM} "dumb")
-
-macro(get_source_info_svn path revision repository)
-  # If svn is a bat file, find_program(Subversion) doesn't find it.
-  # Explicitly search for that here; Subversion_SVN_EXECUTABLE will override
-  # the find_program call in FindSubversion.cmake.
-  find_program(Subversion_SVN_EXECUTABLE NAMES svn svn.bat)
-
-  # FindSubversion does not work with symlinks. See PR 8437
-  if (NOT IS_SYMLINK "${path}")
-    find_package(Subversion)
-  endif()
-  if (Subversion_FOUND)
-    subversion_wc_info( ${path} Project )
-    if (Project_WC_REVISION)
-      set(${revision} ${Project_WC_REVISION} PARENT_SCOPE)
-    endif()
-    if (Project_WC_URL)
-      set(${repository} ${Project_WC_URL} PARENT_SCOPE)
-    endif()
-  endif()
-endmacro()
-
-macro(get_source_info_git_svn path revision repository)
-  find_program(git_executable NAMES git git.exe git.cmd)
-  if (git_executable)
-    execute_process(COMMAND ${git_executable} svn info
-      WORKING_DIRECTORY ${path}
-      TIMEOUT 5
-      RESULT_VARIABLE git_result
-      OUTPUT_VARIABLE git_output)
-    if (git_result EQUAL 0)
-      string(REGEX REPLACE "^(.*\n)?Revision: ([^\n]+).*"
-        "\\2" git_svn_rev "${git_output}")
-      set(${revision} ${git_svn_rev} PARENT_SCOPE)
-      string(REGEX REPLACE "^(.*\n)?URL: ([^\n]+).*"
-        "\\2" git_url "${git_output}")
-      set(${repository} ${git_url} PARENT_SCOPE)
-    endif()
-  endif()
-endmacro()
-
-macro(get_source_info_git path revision repository)
-  find_program(git_executable NAMES git git.exe git.cmd)
-  if (git_executable)
-    execute_process(COMMAND ${git_executable} log -1 --pretty=format:%H
-      WORKING_DIRECTORY ${path}
-      TIMEOUT 5
-      RESULT_VARIABLE git_result
-      OUTPUT_VARIABLE git_output)
-    if (git_result EQUAL 0)
-      set(${revision} ${git_output} PARENT_SCOPE)
-    endif()
-    execute_process(COMMAND ${git_executable} remote -v
-      WORKING_DIRECTORY ${path}
-      TIMEOUT 5
-      RESULT_VARIABLE git_result
-      OUTPUT_VARIABLE git_output)
-    if (git_result EQUAL 0)
-      string(REGEX REPLACE "^(.*\n)?[^ \t]+[ \t]+([^ \t\n]+)[ \t]+\\(fetch\\).*"
-        "\\2" git_url "${git_output}")
-      set(${repository} "${git_url}" PARENT_SCOPE)
-    endif()
-  endif()
-endmacro()
-
-function(get_source_info path revision repository)
-  if (EXISTS "${path}/.svn")
-    get_source_info_svn("${path}" revision repository)
-  elseif (EXISTS "${path}/.git/svn/refs")
-    get_source_info_git_svn("${path}" revision repository)
-  elseif (EXISTS "${path}/.git")
-    get_source_info_git("${path}" revision repository)
-  endif()
-endfunction()
-
-function(append_info name path)
-  get_source_info("${path}" revision repository)
-  string(STRIP "${revision}" revision)
-  string(STRIP "${repository}" repository)
-  file(APPEND "${HEADER_FILE}.txt"
-    "#define ${name}_REVISION \"${revision}\"\n")
-  file(APPEND "${HEADER_FILE}.txt"
-    "#define ${name}_REPOSITORY \"${repository}\"\n")
-endfunction()
-
-function(validate_inputs source_dirs names)
-  list(LENGTH source_dirs source_dirs_length)
-  list(LENGTH names names_length)
-  if (NOT source_dirs_length EQUAL names_length)
-    message(FATAL_ERROR
-            "GetSVN.cmake takes two arguments: a list of source directories, "
-            "and a list of names. Expected two lists must be of equal length, "
-            "but got ${source_dirs_length} source directories and "
-            "${names_length} names.")
-  endif()
-endfunction()
-
-if (DEFINED SOURCE_DIRS AND DEFINED NAMES)
-  validate_inputs("${SOURCE_DIRS}" "${NAMES}")
-
-  list(LENGTH SOURCE_DIRS source_dirs_length)
-  math(EXPR source_dirs_max_index ${source_dirs_length}-1)
-  foreach(index RANGE ${source_dirs_max_index})
-    list(GET SOURCE_DIRS ${index} source_dir)
-    list(GET NAMES ${index} name)
-    append_info(${name} ${source_dir})
-  endforeach()
-endif()
-
-# Allow -DFIRST_SOURCE_DIR arguments until Clang migrates to the new
-# -DSOURCE_DIRS argument.
-if(DEFINED FIRST_SOURCE_DIR)
-  append_info(${FIRST_NAME} "${FIRST_SOURCE_DIR}")
-  if(DEFINED SECOND_SOURCE_DIR)
-    append_info(${SECOND_NAME} "${SECOND_SOURCE_DIR}")
-  endif()
-endif()
-
-# Copy the file only if it has changed.
-execute_process(COMMAND ${CMAKE_COMMAND} -E copy_if_different
-  "${HEADER_FILE}.txt" "${HEADER_FILE}")
-file(REMOVE "${HEADER_FILE}.txt")
-
diff --git a/cmake/modules/HandleLLVMOptions.cmake b/cmake/modules/HandleLLVMOptions.cmake
index 49db308..76ecfbe 100644
--- a/cmake/modules/HandleLLVMOptions.cmake
+++ b/cmake/modules/HandleLLVMOptions.cmake
@@ -10,13 +10,24 @@
 include(HandleLLVMStdlib)
 include(CheckCCompilerFlag)
 include(CheckCXXCompilerFlag)
+include(CheckSymbolExists)
 
-if(CMAKE_LINKER MATCHES "lld-link\.exe" OR (WIN32 AND LLVM_USE_LINKER STREQUAL "lld") OR LLVM_ENABLE_LLD)
+if(CMAKE_LINKER MATCHES "lld-link\\.exe" OR (WIN32 AND LLVM_USE_LINKER STREQUAL "lld") OR LLVM_ENABLE_LLD)
   set(LINKER_IS_LLD_LINK TRUE)
 else()
   set(LINKER_IS_LLD_LINK FALSE)
 endif()
 
+set(LLVM_CXX_STD_default "c++11")
+# Preserve behaviour of legacy cache variables
+if (LLVM_ENABLE_CXX1Y)
+  set(LLVM_CXX_STD_default "c++1y")
+elseif (LLVM_ENABLE_CXX1Z)
+  set(LLVM_CXX_STD_default "c++1z")
+endif()
+set(LLVM_CXX_STD ${LLVM_CXX_STD_default}
+    CACHE STRING "C++ standard to use for compilation.")
+
 set(LLVM_ENABLE_LTO OFF CACHE STRING "Build LLVM with LTO. May be specified as Thin or Full to use a particular kind of LTO")
 string(TOUPPER "${LLVM_ENABLE_LTO}" uppercase_LLVM_ENABLE_LTO)
 
@@ -134,12 +145,32 @@
   set(CMAKE_MODULE_LINKER_FLAGS "${CMAKE_MODULE_LINKER_FLAGS} -Wl,-flat_namespace -Wl,-undefined -Wl,suppress")
 endif()
 
+if(${CMAKE_SYSTEM_NAME} MATCHES "AIX")
+  if(NOT LLVM_BUILD_32_BITS)
+    if (CMAKE_CXX_COMPILER_ID MATCHES "XL")
+      append("-q64" CMAKE_CXX_FLAGS CMAKE_C_FLAGS)
+    else()
+      append("-maix64" CMAKE_CXX_FLAGS CMAKE_C_FLAGS)
+    endif()
+    set(CMAKE_CXX_ARCHIVE_CREATE "<CMAKE_AR> -X64 qc <TARGET> <LINK_FLAGS> <OBJECTS>")
+    set(CMAKE_CXX_ARCHIVE_APPEND "<CMAKE_AR> -X64 q  <TARGET> <LINK_FLAGS> <OBJECTS>")
+    set(CMAKE_C_ARCHIVE_FINISH "<CMAKE_RANLIB> -X64 <TARGET>")
+    set(CMAKE_CXX_ARCHIVE_FINISH "<CMAKE_RANLIB> -X64 <TARGET>")
+  endif()
+  # -fPIC does not enable the large code model for GCC on AIX but does for XL.
+  if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+    append("-mcmodel=large" CMAKE_CXX_FLAGS CMAKE_C_FLAGS)
+  elseif(CMAKE_CXX_COMPILER_ID MATCHES "XL")
+    # XL generates a small number of relocations not of the large model, -bbigtoc is needed.
+    append("-Wl,-bbigtoc"
+           CMAKE_EXE_LINKER_FLAGS CMAKE_MODULE_LINKER_FLAGS CMAKE_SHARED_LINKER_FLAGS)
+  endif()
+endif()
+
 # Pass -Wl,-z,defs. This makes sure all symbols are defined. Otherwise a DSO
 # build might work on ELF but fail on MachO/COFF.
-if(NOT (${CMAKE_SYSTEM_NAME} MATCHES "Darwin" OR WIN32 OR CYGWIN OR
-        ${CMAKE_SYSTEM_NAME} MATCHES "FreeBSD" OR
-	${CMAKE_SYSTEM_NAME} MATCHES "OpenBSD" OR
-	${CMAKE_SYSTEM_NAME} MATCHES "DragonFly") AND
+if(NOT (${CMAKE_SYSTEM_NAME} MATCHES "Darwin|FreeBSD|OpenBSD|DragonFly|AIX" OR
+        WIN32 OR CYGWIN) AND
    NOT LLVM_USE_SANITIZER)
   set(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} -Wl,-z,defs")
 endif()
@@ -217,10 +248,16 @@
   else()
     add_flag_or_print_warning("-fPIC" FPIC)
   endif()
+  # GCC for MIPS can miscompile LLVM due to PR37701.
+  if(CMAKE_COMPILER_IS_GNUCXX AND LLVM_NATIVE_ARCH STREQUAL "Mips" AND
+         NOT Uppercase_CMAKE_BUILD_TYPE STREQUAL "DEBUG")
+    add_flag_or_print_warning("-fno-shrink-wrap" FNO_SHRINK_WRAP)
+  endif()
 endif()
 
-if(NOT WIN32 AND NOT CYGWIN)
+if(NOT WIN32 AND NOT CYGWIN AND NOT (${CMAKE_SYSTEM_NAME} MATCHES "AIX" AND CMAKE_CXX_COMPILER_ID STREQUAL "GNU"))
   # MinGW warns if -fvisibility-inlines-hidden is used.
+  # GCC on AIX warns if -fvisibility-inlines-hidden is used.
   check_cxx_compiler_flag("-fvisibility-inlines-hidden" SUPPORTS_FVISIBILITY_INLINES_HIDDEN_FLAG)
   append_if(SUPPORTS_FVISIBILITY_INLINES_HIDDEN_FLAG "-fvisibility-inlines-hidden" CMAKE_CXX_FLAGS)
 endif()
@@ -415,25 +452,18 @@
   append_if(LLVM_ENABLE_WERROR "-Wno-error" CMAKE_REQUIRED_FLAGS)
   add_flag_if_supported("-Werror=date-time" WERROR_DATE_TIME)
   add_flag_if_supported("-Werror=unguarded-availability-new" WERROR_UNGUARDED_AVAILABILITY_NEW)
-  if (LLVM_ENABLE_CXX1Y)
-    check_cxx_compiler_flag("-std=c++1y" CXX_SUPPORTS_CXX1Y)
-    append_if(CXX_SUPPORTS_CXX1Y "-std=c++1y" CMAKE_CXX_FLAGS)
-  elseif(LLVM_ENABLE_CXX1Z)
-    check_cxx_compiler_flag("-std=c++1z" CXX_SUPPORTS_CXX1Z)
-    append_if(CXX_SUPPORTS_CXX1Z "-std=c++1z" CMAKE_CXX_FLAGS)
-  else()
-    check_cxx_compiler_flag("-std=c++11" CXX_SUPPORTS_CXX11)
-    if (CXX_SUPPORTS_CXX11)
-      if (CYGWIN OR MINGW)
-        # MinGW and Cygwin are a bit stricter and lack things like
-        # 'strdup', 'stricmp', etc in c++11 mode.
-        append("-std=gnu++11" CMAKE_CXX_FLAGS)
-      else()
-        append("-std=c++11" CMAKE_CXX_FLAGS)
-      endif()
+  check_cxx_compiler_flag("-std=${LLVM_CXX_STD}" CXX_SUPPORTS_CXX_STD)
+  if (CXX_SUPPORTS_CXX_STD)
+   if (CYGWIN OR MINGW)
+      # MinGW and Cygwin are a bit stricter and lack things like
+      # 'strdup', 'stricmp', etc in c++11 mode.
+      string(REPLACE "c++" "gnu++" gnu_LLVM_CXX_STD "${LLVM_CXX_STD}")
+      append("-std=${gnu_LLVM_CXX_STD}" CMAKE_CXX_FLAGS)
     else()
-      message(FATAL_ERROR "LLVM requires C++11 support but the '-std=c++11' flag isn't supported.")
+      append("-std=${LLVM_CXX_STD}" CMAKE_CXX_FLAGS)
     endif()
+  else()
+    message(FATAL_ERROR "The host compiler does not support '-std=${LLVM_CXX_STD}'.")
   endif()
   if (LLVM_ENABLE_MODULES)
     set(OLD_CMAKE_REQUIRED_FLAGS ${CMAKE_REQUIRED_FLAGS})
@@ -784,6 +814,16 @@
   message(FATAL_ERROR "Exception handling requires RTTI. You must set LLVM_ENABLE_RTTI to ON")
 endif()
 
+option(LLVM_USE_NEWPM "Build LLVM using the experimental new pass manager" Off)
+mark_as_advanced(LLVM_USE_NEWPM)
+if (LLVM_USE_NEWPM)
+  append("-fexperimental-new-pass-manager"
+    CMAKE_CXX_FLAGS
+    CMAKE_C_FLAGS
+    CMAKE_EXE_LINKER_FLAGS
+    CMAKE_SHARED_LINKER_FLAGS)
+endif()
+
 option(LLVM_ENABLE_IR_PGO "Build LLVM and tools with IR PGO instrumentation (deprecated)" Off)
 mark_as_advanced(LLVM_ENABLE_IR_PGO)
 
@@ -798,6 +838,12 @@
       CMAKE_C_FLAGS
       CMAKE_EXE_LINKER_FLAGS
       CMAKE_SHARED_LINKER_FLAGS)
+  elseif(uppercase_LLVM_BUILD_INSTRUMENTED STREQUAL "CSIR")
+    append("-fcs-profile-generate='${LLVM_CSPROFILE_DATA_DIR}'"
+      CMAKE_CXX_FLAGS
+      CMAKE_C_FLAGS
+      CMAKE_EXE_LINKER_FLAGS
+      CMAKE_SHARED_LINKER_FLAGS)
   else()
     append("-fprofile-instr-generate='${LLVM_PROFILE_FILE_PATTERN}'"
       CMAKE_CXX_FLAGS
@@ -807,6 +853,14 @@
   endif()
 endif()
 
+# Need to pass -fprofile-instr-use to linker for context-sensitive PGO
+# compilation.
+if(LLVM_PROFDATA_FILE AND EXISTS ${LLVM_PROFDATA_FILE})
+    append("-fprofile-instr-use='${LLVM_PROFDATA_FILE}'"
+      CMAKE_EXE_LINKER_FLAGS
+      CMAKE_SHARED_LINKER_FLAGS)
+endif()
+
 option(LLVM_BUILD_INSTRUMENTED_COVERAGE "Build LLVM and tools with Code Coverage instrumentation" Off)
 mark_as_advanced(LLVM_BUILD_INSTRUMENTED_COVERAGE)
 append_if(LLVM_BUILD_INSTRUMENTED_COVERAGE "-fprofile-instr-generate='${LLVM_PROFILE_FILE_PATTERN}' -fcoverage-mapping"
@@ -906,3 +960,32 @@
 get_compile_definitions()
 
 option(LLVM_FORCE_ENABLE_STATS "Enable statistics collection for builds that wouldn't normally enable it" OFF)
+
+check_symbol_exists(os_signpost_interval_begin "os/signpost.h" macos_signposts_available)
+if(macos_signposts_available)
+  check_cxx_source_compiles(
+    "#include <os/signpost.h>
+    int main() { os_signpost_interval_begin(nullptr, 0, \"\", \"\"); return 0; }"
+    macos_signposts_usable)
+  if(macos_signposts_usable)
+    set(LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS "WITH_ASSERTS" CACHE STRING
+        "Enable support for Xcode signposts. Can be WITH_ASSERTS, FORCE_ON, FORCE_OFF")
+    string(TOUPPER "${LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS}"
+                   uppercase_LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS)
+    if( uppercase_LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS STREQUAL "WITH_ASSERTS" )
+      if( LLVM_ENABLE_ASSERTIONS )
+        set( LLVM_SUPPORT_XCODE_SIGNPOSTS 1 )
+      endif()
+    elseif( uppercase_LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS STREQUAL "FORCE_ON" )
+      set( LLVM_SUPPORT_XCODE_SIGNPOSTS 1 )
+    elseif( uppercase_LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS STREQUAL "FORCE_OFF" )
+      # We don't need to do anything special to turn off signposts.
+    elseif( NOT DEFINED LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS )
+      # Treat LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS like "FORCE_OFF" when it has not been
+      # defined.
+    else()
+      message(FATAL_ERROR "Unknown value for LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS:"
+                          " \"${LLVM_ENABLE_SUPPORT_XCODE_SIGNPOSTS}\"!")
+    endif()
+  endif()
+endif()
diff --git a/cmake/modules/HandleLLVMStdlib.cmake b/cmake/modules/HandleLLVMStdlib.cmake
index a0706d8..f0e22d1 100644
--- a/cmake/modules/HandleLLVMStdlib.cmake
+++ b/cmake/modules/HandleLLVMStdlib.cmake
@@ -14,6 +14,7 @@
 
   include(CheckCXXCompilerFlag)
   include(CheckLinkerFlag)
+  set(LLVM_LIBCXX_USED 0)
   if(LLVM_ENABLE_LIBCXX)
     if(LLVM_COMPILER_IS_GCC_COMPATIBLE)
       check_cxx_compiler_flag("-stdlib=libc++" CXX_COMPILER_SUPPORTS_STDLIB)
@@ -22,6 +23,7 @@
         append("-stdlib=libc++"
           CMAKE_CXX_FLAGS CMAKE_EXE_LINKER_FLAGS CMAKE_SHARED_LINKER_FLAGS
           CMAKE_MODULE_LINKER_FLAGS)
+        set(LLVM_LIBCXX_USED 1)
       else()
         message(WARNING "Can't specify libc++ with '-stdlib='")
       endif()
diff --git a/cmake/modules/LLVMConfig.cmake.in b/cmake/modules/LLVMConfig.cmake.in
index 7ca0638..df97c72 100644
--- a/cmake/modules/LLVMConfig.cmake.in
+++ b/cmake/modules/LLVMConfig.cmake.in
@@ -44,6 +44,8 @@
 
 set(LLVM_LIBXML2_ENABLED @LLVM_LIBXML2_ENABLED@)
 
+set(LLVM_WITH_Z3 @LLVM_WITH_Z3@)
+
 set(LLVM_ENABLE_DIA_SDK @LLVM_ENABLE_DIA_SDK@)
 
 set(LLVM_NATIVE_ARCH @LLVM_NATIVE_ARCH@)
@@ -67,10 +69,12 @@
 set(LLVM_INCLUDE_DIRS "@LLVM_CONFIG_INCLUDE_DIRS@")
 set(LLVM_LIBRARY_DIRS "@LLVM_CONFIG_LIBRARY_DIRS@")
 
-# These variables are duplicated, but they must match the LLVM variables of the
-# same name. The variables ending in "S" could some day become lists, and are
-# preserved for convention and compatibility.
-set(LLVM_INCLUDE_DIR "@LLVM_CONFIG_INCLUDE_DIRS@")
+# These variables are duplicated for install tree but they have different
+# values for build tree.  LLVM_INCLUDE_DIRS contains both source
+# and generated include directories while the following variables have
+# them split.
+set(LLVM_INCLUDE_DIR "@LLVM_CONFIG_INCLUDE_DIR@")
+set(LLVM_MAIN_INCLUDE_DIR "@LLVM_CONFIG_MAIN_INCLUDE_DIR@")
 set(LLVM_LIBRARY_DIR "@LLVM_CONFIG_LIBRARY_DIRS@")
 
 set(LLVM_DEFINITIONS "@LLVM_DEFINITIONS@")
diff --git a/cmake/modules/LLVMExternalProjectUtils.cmake b/cmake/modules/LLVMExternalProjectUtils.cmake
index 4d26a30..0cf6e0d 100644
--- a/cmake/modules/LLVMExternalProjectUtils.cmake
+++ b/cmake/modules/LLVMExternalProjectUtils.cmake
@@ -5,7 +5,7 @@
 function(llvm_ExternalProject_BuildCmd out_var target bin_dir)
   cmake_parse_arguments(ARG "" "CONFIGURATION" "" ${ARGN})
   if(NOT ARG_CONFIGURATION)
-    set(ARG_CONFIGURATION "$<CONFIGURATION>")
+    set(ARG_CONFIGURATION "$<CONFIG>")
   endif()
   if (CMAKE_GENERATOR MATCHES "Make")
     # Use special command for Makefiles to support parallelism.
@@ -35,12 +35,14 @@
 #     Extra targets in the subproject to generate targets for
 #   PASSTHROUGH_PREFIXES prefix...
 #     Extra variable prefixes (name is always included) to pass down
+#   STRIP_TOOL path
+#     Use provided strip tool instead of the default one.
 #   )
 function(llvm_ExternalProject_Add name source_dir)
   cmake_parse_arguments(ARG
     "USE_TOOLCHAIN;EXCLUDE_FROM_ALL;NO_INSTALL;ALWAYS_CLEAN"
     "SOURCE_DIR"
-    "CMAKE_ARGS;TOOLCHAIN_TOOLS;RUNTIME_LIBRARIES;DEPENDS;EXTRA_TARGETS;PASSTHROUGH_PREFIXES"
+    "CMAKE_ARGS;TOOLCHAIN_TOOLS;RUNTIME_LIBRARIES;DEPENDS;EXTRA_TARGETS;PASSTHROUGH_PREFIXES;STRIP_TOOL"
     ${ARGN})
   canonicalize_tool_name(${name} nameCanon)
   if(NOT ARG_TOOLCHAIN_TOOLS)
@@ -125,12 +127,16 @@
     if(llvm-objcopy IN_LIST TOOLCHAIN_TOOLS)
       list(APPEND compiler_args -DCMAKE_OBJCOPY=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-objcopy)
     endif()
-    if(llvm-strip IN_LIST TOOLCHAIN_TOOLS)
+    if(llvm-strip IN_LIST TOOLCHAIN_TOOLS AND NOT ARG_STRIP_TOOL)
       list(APPEND compiler_args -DCMAKE_STRIP=${LLVM_RUNTIME_OUTPUT_INTDIR}/llvm-strip)
     endif()
     list(APPEND ARG_DEPENDS ${TOOLCHAIN_TOOLS})
   endif()
 
+  if(ARG_STRIP_TOOL)
+    list(APPEND compiler_args -DCMAKE_STRIP=${ARG_STRIP_TOOL})
+  endif()
+
   add_custom_command(
     OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/${name}-clobber-stamp
     DEPENDS ${ARG_DEPENDS}
diff --git a/cmake/modules/LLVMProcessSources.cmake b/cmake/modules/LLVMProcessSources.cmake
index 7cbd286..d0be0e8 100644
--- a/cmake/modules/LLVMProcessSources.cmake
+++ b/cmake/modules/LLVMProcessSources.cmake
@@ -30,7 +30,15 @@
 
 function(add_header_files_for_glob hdrs_out glob)
   file(GLOB hds ${glob})
-  set(${hdrs_out} ${hds} PARENT_SCOPE)
+  set(filtered)
+  foreach(file ${hds})
+    # Explicit existence check is necessary to filter dangling symlinks
+    # out.  See https://bugs.gentoo.org/674662.
+    if(EXISTS ${file})
+      list(APPEND filtered ${file})
+    endif()
+  endforeach()
+  set(${hdrs_out} ${filtered} PARENT_SCOPE)
 endfunction(add_header_files_for_glob)
 
 function(find_all_header_files hdrs_out additional_headerdirs)
diff --git a/cmake/modules/TableGen.cmake b/cmake/modules/TableGen.cmake
index 3c84ae7..4bd7dd8 100644
--- a/cmake/modules/TableGen.cmake
+++ b/cmake/modules/TableGen.cmake
@@ -2,8 +2,6 @@
 # Extra parameters for `tblgen' may come after `ofn' parameter.
 # Adds the name of the generated file to TABLEGEN_OUTPUT.
 
-include(LLVMExternalProjectUtils)
-
 if(LLVM_MAIN_INCLUDE_DIR)
   set(LLVM_TABLEGEN_FLAGS -I ${LLVM_MAIN_INCLUDE_DIR})
 endif()
@@ -121,49 +119,30 @@
   set(${project}_TABLEGEN "${target}" CACHE
       STRING "Native TableGen executable. Saves building one when cross-compiling.")
 
-  # Upgrade existing LLVM_TABLEGEN setting.
-  if(${project} STREQUAL LLVM)
-    if(${LLVM_TABLEGEN} STREQUAL tblgen)
-      set(LLVM_TABLEGEN "${target}" CACHE
-          STRING "Native TableGen executable. Saves building one when cross-compiling."
-          FORCE)
-    endif()
-  endif()
-
   # Effective tblgen executable to be used:
   set(${project}_TABLEGEN_EXE ${${project}_TABLEGEN} PARENT_SCOPE)
   set(${project}_TABLEGEN_TARGET ${${project}_TABLEGEN} PARENT_SCOPE)
 
   if(LLVM_USE_HOST_TOOLS)
     if( ${${project}_TABLEGEN} STREQUAL "${target}" )
-      if (NOT CMAKE_CONFIGURATION_TYPES)
-        set(${project}_TABLEGEN_EXE "${LLVM_NATIVE_BUILD}/bin/${target}")
-      else()
-        set(${project}_TABLEGEN_EXE "${LLVM_NATIVE_BUILD}/Release/bin/${target}")
-      endif()
+      build_native_tool(${target} ${project}_TABLEGEN_EXE DEPENDS ${target})
       set(${project}_TABLEGEN_EXE ${${project}_TABLEGEN_EXE} PARENT_SCOPE)
 
-      llvm_ExternalProject_BuildCmd(tblgen_build_cmd ${target}
-                                    ${LLVM_NATIVE_BUILD}
-                                    CONFIGURATION Release)
+      add_custom_target(${project}-tablegen-host DEPENDS ${${project}_TABLEGEN_EXE})
+      set(${project}_TABLEGEN_TARGET ${project}-tablegen-host PARENT_SCOPE)
+
       # Create an artificial dependency between tablegen projects, because they
       # compile the same dependencies, thus using the same build folders.
       # FIXME: A proper fix requires sequentially chaining tablegens.
-      if (NOT ${project} STREQUAL LLVM AND TARGET ${project}-tablegen-host)
+      if (NOT ${project} STREQUAL LLVM AND TARGET ${project}-tablegen-host AND
+          TARGET LLVM-tablegen-host)
         add_dependencies(${project}-tablegen-host LLVM-tablegen-host)
       endif()
-      add_custom_command(OUTPUT ${${project}_TABLEGEN_EXE}
-        COMMAND ${tblgen_build_cmd}
-        DEPENDS CONFIGURE_LLVM_NATIVE ${target}
-        WORKING_DIRECTORY ${LLVM_NATIVE_BUILD}
-        COMMENT "Building native TableGen..."
-        USES_TERMINAL)
-      add_custom_target(${project}-tablegen-host DEPENDS ${${project}_TABLEGEN_EXE})
-      set(${project}_TABLEGEN_TARGET ${project}-tablegen-host PARENT_SCOPE)
     endif()
   endif()
 
   if (${project} STREQUAL LLVM AND NOT LLVM_INSTALL_TOOLCHAIN_ONLY)
+    set(export_to_llvmexports)
     if(${target} IN_LIST LLVM_DISTRIBUTION_COMPONENTS OR
         NOT LLVM_DISTRIBUTION_COMPONENTS)
       set(export_to_llvmexports EXPORT LLVMExports)
diff --git a/cmake/modules/VersionFromVCS.cmake b/cmake/modules/VersionFromVCS.cmake
index 552fe77..56331a3 100644
--- a/cmake/modules/VersionFromVCS.cmake
+++ b/cmake/modules/VersionFromVCS.cmake
@@ -3,90 +3,92 @@
 # existence of certain subdirectories under SOURCE_DIR (if provided as an
 # extra argument, otherwise uses CMAKE_CURRENT_SOURCE_DIR).
 
-function(add_version_info_from_vcs VERS)
-  SET(SOURCE_DIR ${ARGV1})
-  if("${SOURCE_DIR}" STREQUAL "")
-      SET(SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR})
+function(get_source_info_svn path revision repository)
+  # If svn is a bat file, find_program(Subversion) doesn't find it.
+  # Explicitly search for that here; Subversion_SVN_EXECUTABLE will override
+  # the find_program call in FindSubversion.cmake.
+  find_program(Subversion_SVN_EXECUTABLE NAMES svn svn.bat)
+  find_package(Subversion)
+
+  # Subversion module does not work with symlinks, see PR8437.
+  get_filename_component(realpath ${path} REALPATH)
+  if(Subversion_FOUND)
+    subversion_wc_info(${realpath} Project)
+    if(Project_WC_REVISION)
+      set(${revision} ${Project_WC_REVISION} PARENT_SCOPE)
+    endif()
+    if(Project_WC_URL)
+      set(${repository} ${Project_WC_URL} PARENT_SCOPE)
+    endif()
   endif()
-  string(REPLACE "svn" "" result "${${VERS}}")
-  if( EXISTS "${SOURCE_DIR}/.svn" )
-    set(result "${result}svn")
-    # FindSubversion does not work with symlinks. See PR 8437
-    if( NOT IS_SYMLINK "${SOURCE_DIR}" )
-      find_package(Subversion)
-    endif()
-    if( Subversion_FOUND )
-      subversion_wc_info( ${SOURCE_DIR} Project )
-      if( Project_WC_REVISION )
-        set(SVN_REVISION ${Project_WC_REVISION} PARENT_SCOPE)
-        set(result "${result}-r${Project_WC_REVISION}")
-      endif()
-      if( Project_WC_URL )
-        set(LLVM_REPOSITORY ${Project_WC_URL} PARENT_SCOPE)
-      endif()
-    endif()
-  else()
-    find_program(git_executable NAMES git git.exe git.cmd)
+endfunction()
 
-    if( git_executable )
-      # Run from a subdirectory to force git to print an absoute path.
-      execute_process(COMMAND ${git_executable} rev-parse --git-dir
-        WORKING_DIRECTORY ${SOURCE_DIR}/cmake
-        RESULT_VARIABLE git_result
-        OUTPUT_VARIABLE git_dir
-        ERROR_QUIET)
-      if(git_result EQUAL 0)
-        # Try to get a ref-id
-        string(STRIP "${git_dir}" git_dir)
-        set(result "${result}git")
-        if( EXISTS ${git_dir}/svn )
-          # Get the repository URL
-          execute_process(COMMAND
-            ${git_executable} svn info
-            WORKING_DIRECTORY ${SOURCE_DIR}
-            TIMEOUT 5
-            RESULT_VARIABLE git_result
-            OUTPUT_VARIABLE git_output
-            ERROR_QUIET)
-          if( git_result EQUAL 0 )
-            string(REGEX MATCH "URL: ([^ \n]*)" svn_url ${git_output})
-            if(svn_url)
-              set(LLVM_REPOSITORY ${CMAKE_MATCH_1} PARENT_SCOPE)
-            endif()
-          endif()
-
-          # Get the svn revision number for this git commit if one exists.
-          execute_process(COMMAND ${git_executable} svn find-rev HEAD
-            WORKING_DIRECTORY ${SOURCE_DIR}
-            TIMEOUT 5
-            RESULT_VARIABLE git_result
-            OUTPUT_VARIABLE git_head_svn_rev_number
-            OUTPUT_STRIP_TRAILING_WHITESPACE)
-          if( git_result EQUAL 0 AND git_output)
-            set(SVN_REVISION ${git_head_svn_rev_number} PARENT_SCOPE)
-            set(git_svn_rev "-svn-${git_head_svn_rev_number}")
-          else()
-            set(git_svn_rev "")
-          endif()
-        endif()
-
-        # Get the git ref id
-        execute_process(COMMAND
-          ${git_executable} rev-parse --short HEAD
-          WORKING_DIRECTORY ${SOURCE_DIR}
-          TIMEOUT 5
+function(get_source_info_git path revision repository)
+  find_package(Git)
+  if(GIT_FOUND)
+    execute_process(COMMAND ${GIT_EXECUTABLE} rev-parse --git-dir
+      WORKING_DIRECTORY ${path}
+      RESULT_VARIABLE git_result
+      OUTPUT_VARIABLE git_output
+      ERROR_QUIET)
+    if(git_result EQUAL 0)
+      string(STRIP "${git_output}" git_output)
+      get_filename_component(git_dir ${git_output} ABSOLUTE BASE_DIR ${path})
+      if(EXISTS "${git_dir}/svn/refs")
+        execute_process(COMMAND ${GIT_EXECUTABLE} svn info
+          WORKING_DIRECTORY ${path}
           RESULT_VARIABLE git_result
-          OUTPUT_VARIABLE git_ref_id
-          OUTPUT_STRIP_TRAILING_WHITESPACE)
-
-        if( git_result EQUAL 0 )
-          set(GIT_COMMIT ${git_ref_id} PARENT_SCOPE)
-          set(result "${result}${git_svn_rev}-${git_ref_id}")
+          OUTPUT_VARIABLE git_output)
+        if(git_result EQUAL 0)
+          string(REGEX REPLACE "^(.*\n)?Revision: ([^\n]+).*"
+            "\\2" git_svn_rev "${git_output}")
+          set(${revision} ${git_svn_rev} PARENT_SCOPE)
+          string(REGEX REPLACE "^(.*\n)?URL: ([^\n]+).*"
+            "\\2" git_url "${git_output}")
+          set(${repository} ${git_url} PARENT_SCOPE)
+        endif()
+      else()
+        execute_process(COMMAND ${GIT_EXECUTABLE} rev-parse HEAD
+          WORKING_DIRECTORY ${path}
+          RESULT_VARIABLE git_result
+          OUTPUT_VARIABLE git_output)
+        if(git_result EQUAL 0)
+          string(STRIP "${git_output}" git_output)
+          set(${revision} ${git_output} PARENT_SCOPE)
+        endif()
+        execute_process(COMMAND ${GIT_EXECUTABLE} rev-parse --abbrev-ref --symbolic-full-name @{upstream}
+          WORKING_DIRECTORY ${path}
+          RESULT_VARIABLE git_result
+          OUTPUT_VARIABLE git_output
+          ERROR_QUIET)
+        if(git_result EQUAL 0)
+          string(REPLACE "/" ";" branch ${git_output})
+          list(GET branch 0 remote)
         else()
-          set(result "${result}${git_svn_rev}")
+          set(remote "origin")
+        endif()
+        execute_process(COMMAND ${GIT_EXECUTABLE} remote get-url ${remote}
+          WORKING_DIRECTORY ${path}
+          RESULT_VARIABLE git_result
+          OUTPUT_VARIABLE git_output
+          ERROR_QUIET)
+        if(git_result EQUAL 0)
+          string(STRIP "${git_output}" git_output)
+          set(${repository} ${git_output} PARENT_SCOPE)
+        else()
+          set(${repository} ${path} PARENT_SCOPE)
         endif()
       endif()
     endif()
   endif()
-  set(${VERS} ${result} PARENT_SCOPE)
-endfunction(add_version_info_from_vcs)
+endfunction()
+
+function(get_source_info path revision repository)
+  if(EXISTS "${path}/.svn")
+    get_source_info_svn("${path}" revision_info repository_info)
+  else()
+    get_source_info_git("${path}" revision_info repository_info)
+  endif()
+  set(${repository} "${repository_info}" PARENT_SCOPE)
+  set(${revision} "${revision_info}" PARENT_SCOPE)
+endfunction()
diff --git a/cmake/platforms/WinMsvc.cmake b/cmake/platforms/WinMsvc.cmake
index f625d0e..d038df9 100644
--- a/cmake/platforms/WinMsvc.cmake
+++ b/cmake/platforms/WinMsvc.cmake
@@ -92,7 +92,9 @@
 # won't see the value of any arguments the user passed via -D.  Since these are
 # necessary to properly configure MSVC in both the top-level configuration as well as
 # all feature-test invocations, we set environment variables with the values so that
-# these environments get inherited by child invocations.
+# these environments get inherited by child invocations. We can switch to
+# CMAKE_TRY_COMPILE_PLATFORM_VARIABLES once our minimum supported CMake version
+# is 3.6 or greater.
 function(init_user_prop prop)
   if(${prop})
     set(ENV{_${prop}} "${${prop}}")
diff --git a/cmake/platforms/iOS.cmake b/cmake/platforms/iOS.cmake
index 69f8479..ccb0653 100644
--- a/cmake/platforms/iOS.cmake
+++ b/cmake/platforms/iOS.cmake
@@ -25,7 +25,7 @@
    OUTPUT_VARIABLE CMAKE_C_COMPILER
    ERROR_QUIET
    OUTPUT_STRIP_TRAILING_WHITESPACE)
-  message(STATUS "Using c compiler ${CMAKE_C_COMPILER}")
+  message(STATUS "Using C compiler ${CMAKE_C_COMPILER}")
 ENDIF()
 
 IF(NOT CMAKE_CXX_COMPILER)
@@ -33,7 +33,7 @@
    OUTPUT_VARIABLE CMAKE_CXX_COMPILER
    ERROR_QUIET
    OUTPUT_STRIP_TRAILING_WHITESPACE)
-  message(STATUS "Using c compiler ${CMAKE_CXX_COMPILER}")
+  message(STATUS "Using C++ compiler ${CMAKE_CXX_COMPILER}")
 ENDIF()
 
 IF(NOT CMAKE_AR)
diff --git a/docs/AMDGPUOperandSyntax.rst b/docs/AMDGPUOperandSyntax.rst
index 51e477a..8713c72 100644
--- a/docs/AMDGPUOperandSyntax.rst
+++ b/docs/AMDGPUOperandSyntax.rst
@@ -523,22 +523,22 @@
 :ref:`expected operand type<amdgpu_syn_instruction_type>`
 as described :ref:`here<amdgpu_synid_fp_const_conv>`.
 
-    ================================== ===================================================== ==================
-    Value                              Note                                                  Availability
-    ================================== ===================================================== ==================
-    0.0                                The same as integer constant 0.                       All GPUs
-    0.5                                Floating-point constant 0.5                           All GPUs
-    1.0                                Floating-point constant 1.0                           All GPUs
-    2.0                                Floating-point constant 2.0                           All GPUs
-    4.0                                Floating-point constant 4.0                           All GPUs
-    -0.5                               Floating-point constant -0.5                          All GPUs
-    -1.0                               Floating-point constant -1.0                          All GPUs
-    -2.0                               Floating-point constant -2.0                          All GPUs
-    -4.0                               Floating-point constant -4.0                          All GPUs
-    0.1592                             1.0/(2.0*pi). Use only for 16-bit operands.           GFX8, GFX9
-    0.15915494                         1.0/(2.0*pi). Use only for 16- and 32-bit operands.   GFX8, GFX9
-    0.159154943091895317852646485335   1.0/(2.0*pi).                                         GFX8, GFX9
-    ================================== ===================================================== ==================
+    ===================== ===================================================== ==================
+    Value                 Note                                                  Availability
+    ===================== ===================================================== ==================
+    0.0                   The same as integer constant 0.                       All GPUs
+    0.5                   Floating-point constant 0.5                           All GPUs
+    1.0                   Floating-point constant 1.0                           All GPUs
+    2.0                   Floating-point constant 2.0                           All GPUs
+    4.0                   Floating-point constant 4.0                           All GPUs
+    -0.5                  Floating-point constant -0.5                          All GPUs
+    -1.0                  Floating-point constant -1.0                          All GPUs
+    -2.0                  Floating-point constant -2.0                          All GPUs
+    -4.0                  Floating-point constant -4.0                          All GPUs
+    0.1592                1.0/(2.0*pi). Use only for 16-bit operands.           GFX8, GFX9
+    0.15915494            1.0/(2.0*pi). Use only for 16- and 32-bit operands.   GFX8, GFX9
+    0.15915494309189532   1.0/(2.0*pi).                                         GFX8, GFX9
+    ===================== ===================================================== ==================
 
 .. WARNING:: GFX7 does not support inline constants for *f16* operands.
 
diff --git a/docs/AMDGPUUsage.rst b/docs/AMDGPUUsage.rst
index c60d60a..38a8cbf 100644
--- a/docs/AMDGPUUsage.rst
+++ b/docs/AMDGPUUsage.rst
@@ -207,8 +207,6 @@
                                                                           names.
      ``gfx906``                  ``amdgcn``   dGPU  - xnack            - Radeon Instinct MI50
                                                       [off]            - Radeon Instinct MI60
-                                                      sram-ecc
-                                                      [on]
      ``gfx909``                  ``amdgcn``   APU   - xnack            *TBA* (Raven Ridge 2)
                                                       [on]
                                                                        .. TODO
@@ -281,9 +279,9 @@
   .. table:: Address Space Mapping
      :name: amdgpu-address-space-mapping-table
 
-     ================== =================
+     ================== =================================
      LLVM Address Space Memory Space
-     ================== =================
+     ================== =================================
      0                  Generic (Flat)
      1                  Global
      2                  Region (GDS)
@@ -291,7 +289,15 @@
      4                  Constant
      5                  Private (Scratch)
      6                  Constant 32-bit
-     ================== =================
+     7                  Buffer Fat Pointer (experimental)
+     ================== =================================
+
+The buffer fat pointer is an experimental address space that is currently
+unsupported in the backend. It exposes a non-integral pointer that is in future
+intended to support the modelling of 128-bit buffer descriptors + a 32-bit
+offset into the buffer descriptor (in total encapsulating a 160-bit 'pointer'),
+allowing us to use normal LLVM load/store/atomic operations to model the buffer
+descriptors used heavily in graphics workloads targeting the backend.
 
 .. _amdgpu-memory-scopes:
 
@@ -315,62 +321,80 @@
   .. table:: AMDHSA LLVM Sync Scopes
      :name: amdgpu-amdhsa-llvm-sync-scopes-table
 
-     ================ ==========================================================
-     LLVM Sync Scope  Description
-     ================ ==========================================================
-     *none*           The default: ``system``.
+     ======================= ===================================================
+     LLVM Sync Scope         Description
+     ======================= ===================================================
+     *none*                  The default: ``system``.
 
-                      Synchronizes with, and participates in modification and
-                      seq_cst total orderings with, other operations (except
-                      image operations) for all address spaces (except private,
-                      or generic that accesses private) provided the other
-                      operation's sync scope is:
+                             Synchronizes with, and participates in modification
+                             and seq_cst total orderings with, other operations
+                             (except image operations) for all address spaces
+                             (except private, or generic that accesses private)
+                             provided the other operation's sync scope is:
 
-                      - ``system``.
-                      - ``agent`` and executed by a thread on the same agent.
-                      - ``workgroup`` and executed by a thread in the same
-                        workgroup.
-                      - ``wavefront`` and executed by a thread in the same
-                        wavefront.
+                             - ``system``.
+                             - ``agent`` and executed by a thread on the same
+                               agent.
+                             - ``workgroup`` and executed by a thread in the
+                               same workgroup.
+                             - ``wavefront`` and executed by a thread in the
+                               same wavefront.
 
-     ``agent``        Synchronizes with, and participates in modification and
-                      seq_cst total orderings with, other operations (except
-                      image operations) for all address spaces (except private,
-                      or generic that accesses private) provided the other
-                      operation's sync scope is:
+     ``agent``               Synchronizes with, and participates in modification
+                             and seq_cst total orderings with, other operations
+                             (except image operations) for all address spaces
+                             (except private, or generic that accesses private)
+                             provided the other operation's sync scope is:
 
-                      - ``system`` or ``agent`` and executed by a thread on the
-                        same agent.
-                      - ``workgroup`` and executed by a thread in the same
-                        workgroup.
-                      - ``wavefront`` and executed by a thread in the same
-                        wavefront.
+                             - ``system`` or ``agent`` and executed by a thread
+                               on the same agent.
+                             - ``workgroup`` and executed by a thread in the
+                               same workgroup.
+                             - ``wavefront`` and executed by a thread in the
+                               same wavefront.
 
-     ``workgroup``    Synchronizes with, and participates in modification and
-                      seq_cst total orderings with, other operations (except
-                      image operations) for all address spaces (except private,
-                      or generic that accesses private) provided the other
-                      operation's sync scope is:
+     ``workgroup``           Synchronizes with, and participates in modification
+                             and seq_cst total orderings with, other operations
+                             (except image operations) for all address spaces
+                             (except private, or generic that accesses private)
+                             provided the other operation's sync scope is:
 
-                      - ``system``, ``agent`` or ``workgroup`` and executed by a
-                        thread in the same workgroup.
-                      - ``wavefront`` and executed by a thread in the same
-                        wavefront.
+                             - ``system``, ``agent`` or ``workgroup`` and
+                               executed by a thread in the same workgroup.
+                             - ``wavefront`` and executed by a thread in the
+                               same wavefront.
 
-     ``wavefront``    Synchronizes with, and participates in modification and
-                      seq_cst total orderings with, other operations (except
-                      image operations) for all address spaces (except private,
-                      or generic that accesses private) provided the other
-                      operation's sync scope is:
+     ``wavefront``           Synchronizes with, and participates in modification
+                             and seq_cst total orderings with, other operations
+                             (except image operations) for all address spaces
+                             (except private, or generic that accesses private)
+                             provided the other operation's sync scope is:
 
-                      - ``system``, ``agent``, ``workgroup`` or ``wavefront``
-                        and executed by a thread in the same wavefront.
+                             - ``system``, ``agent``, ``workgroup`` or
+                               ``wavefront`` and executed by a thread in the
+                               same wavefront.
 
-     ``singlethread`` Only synchronizes with, and participates in modification
-                      and seq_cst total orderings with, other operations (except
-                      image operations) running in the same thread for all
-                      address spaces (for example, in signal handlers).
-     ================ ==========================================================
+     ``singlethread``        Only synchronizes with, and participates in
+                             modification and seq_cst total orderings with,
+                             other operations (except image operations) running
+                             in the same thread for all address spaces (for
+                             example, in signal handlers).
+
+     ``one-as``              Same as ``system`` but only synchronizes with other
+                             operations within the same address space.
+
+     ``agent-one-as``        Same as ``agent`` but only synchronizes with other
+                             operations within the same address space.
+
+     ``workgroup-one-as``    Same as ``workgroup`` but only synchronizes with
+                             other operations within the same address space.
+
+     ``wavefront-one-as``    Same as ``wavefront`` but only synchronizes with
+                             other operations within the same address space.
+
+     ``singlethread-one-as`` Same as ``singlethread`` but only synchronizes with
+                             other operations within the same address space.
+     ======================= ===================================================
 
 AMDGPU Intrinsics
 -----------------
@@ -409,6 +433,12 @@
      "amdgpu-waves-per-eu"="m,n"             Specify the minimum and maximum number of waves per
                                              execution unit. Generated by the ``amdgpu_waves_per_eu``
                                              CLANG attribute [CLANG-ATTR]_.
+     "amdgpu-ieee" true/false.               Specify whether the function expects the IEEE field of the
+                                             mode register to be set on entry. Overrides the default for
+                                             the calling convention.
+     "amdgpu-dx10-clamp" true/false.         Specify whether the function expects the DX10_CLAMP field of
+                                             the mode register to be set on entry. Overrides the default
+                                             for the calling convention.
      ======================================= ==========================================================
 
 Code Object
@@ -673,21 +703,32 @@
 Note Records
 ------------
 
-As required by ``ELFCLASS32`` and ``ELFCLASS64``, minimal zero byte padding must
-be generated after the ``name`` field to ensure the ``desc`` field is 4 byte
-aligned. In addition, minimal zero byte padding must be generated to ensure the
-``desc`` field size is a multiple of 4 bytes. The ``sh_addralign`` field of the
-``.note`` section must be at least 4 to indicate at least 8 byte alignment.
+The AMDGPU backend code object contains ELF note records in the ``.note``
+section. The set of generated notes and their semantics depend on the code
+object version; see :ref:`amdgpu-note-records-v2` and
+:ref:`amdgpu-note-records-v3`.
+
+As required by ``ELFCLASS32`` and ``ELFCLASS64``, minimal zero byte padding
+must be generated after the ``name`` field to ensure the ``desc`` field is 4
+byte aligned. In addition, minimal zero byte padding must be generated to
+ensure the ``desc`` field size is a multiple of 4 bytes. The ``sh_addralign``
+field of the ``.note`` section must be at least 4 to indicate at least 8 byte
+alignment.
 
 .. _amdgpu-note-records-v2:
 
 Code Object V2 Note Records (-mattr=-code-object-v3)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The AMDGPU backend code object uses the following ELF note record in the
-``.note`` section.
+.. warning:: Code Object V2 is not the default code object version emitted by
+  this version of LLVM. For a description of the notes generated with the
+  default configuration (Code Object V3) see :ref:`amdgpu-note-records-v3`.
 
-Additional note records can be present.
+The AMDGPU backend code object uses the following ELF note record in the
+``.note`` section when compiling for Code Object V2 (-mattr=-code-object-v3).
+
+Additional note records may be present, but any which are not documented here
+are deprecated and should not be used.
 
   .. table:: AMDGPU Code Object V2 ELF Note Records
      :name: amdgpu-elf-note-records-table-v2
@@ -724,9 +765,10 @@
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The AMDGPU backend code object uses the following ELF note record in the
-``.note`` section.
+``.note`` section when compiling for Code Object V3 (-mattr=+code-object-v3).
 
-Additional note records can be present.
+Additional note records may be present, but any which are not documented here
+are deprecated and should not be used.
 
   .. table:: AMDGPU Code Object V3 ELF Note Records
      :name: amdgpu-elf-note-records-table-v3
@@ -1048,19 +1090,28 @@
 
 The code object metadata specifies extensible metadata associated with the code
 objects executed on HSA [HSA]_ compatible runtimes such as AMD's ROCm
-[AMD-ROCm]_. It is specified in a note record (see :ref:`amdgpu-note-records`)
-and is required when the target triple OS is ``amdhsa`` (see
-:ref:`amdgpu-target-triples`). It must contain the minimum information
-necessary to support the ROCM kernel queries. For example, the segment sizes
-needed in a dispatch packet. In addition, a high level language runtime may
-require other information to be included. For example, the AMD OpenCL runtime
-records kernel argument information.
+[AMD-ROCm]_. The encoding and semantics of this metadata depends on the code
+object version; see :ref:`amdgpu-amdhsa-code-object-metadata-v2` and
+:ref:`amdgpu-amdhsa-code-object-metadata-v3`.
+
+Code object metadata is specified in a note record (see
+:ref:`amdgpu-note-records`) and is required when the target triple OS is
+``amdhsa`` (see :ref:`amdgpu-target-triples`). It must contain the minimum
+information necessary to support the ROCM kernel queries. For example, the
+segment sizes needed in a dispatch packet. In addition, a high level language
+runtime may require other information to be included. For example, the AMD
+OpenCL runtime records kernel argument information.
 
 .. _amdgpu-amdhsa-code-object-metadata-v2:
 
 Code Object V2 Metadata (-mattr=-code-object-v3)
 ++++++++++++++++++++++++++++++++++++++++++++++++
 
+.. warning:: Code Object V2 is not the default code object version emitted by
+  this version of LLVM. For a description of the metadata generated with the
+  default configuration (Code Object V3) see
+  :ref:`amdgpu-amdhsa-code-object-metadata-v3`.
+
 Code object V2 metadata is specified by the ``NT_AMD_AMDGPU_METADATA`` note
 record (see :ref:`amdgpu-note-records-v2`).
 
@@ -4774,8 +4825,72 @@
 .. TODO
    Remove once we switch to code object v3 by default.
 
-HSA Code Object Directives
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _amdgpu-amdhsa-assembler-predefined-symbols-v2:
+
+Code Object V2 Predefined Symbols (-mattr=-code-object-v3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning:: Code Object V2 is not the default code object version emitted by
+  this version of LLVM. For a description of the predefined symbols available
+  with the default configuration (Code Object V3) see
+  :ref:`amdgpu-amdhsa-assembler-predefined-symbols-v3`.
+
+The AMDGPU assembler defines and updates some symbols automatically. These
+symbols do not affect code generation.
+
+.option.machine_version_major
++++++++++++++++++++++++++++++
+
+Set to the GFX major generation number of the target being assembled for. For
+example, when assembling for a "GFX9" target this will be set to the integer
+value "9". The possible GFX major generation numbers are presented in
+:ref:`amdgpu-processors`.
+
+.option.machine_version_minor
++++++++++++++++++++++++++++++
+
+Set to the GFX minor generation number of the target being assembled for. For
+example, when assembling for a "GFX810" target this will be set to the integer
+value "1". The possible GFX minor generation numbers are presented in
+:ref:`amdgpu-processors`.
+
+.option.machine_version_stepping
+++++++++++++++++++++++++++++++++
+
+Set to the GFX stepping generation number of the target being assembled for.
+For example, when assembling for a "GFX704" target this will be set to the
+integer value "4". The possible GFX stepping generation numbers are presented
+in :ref:`amdgpu-processors`.
+
+.kernel.vgpr_count
+++++++++++++++++++
+
+Set to zero each time a
+:ref:`amdgpu-amdhsa-assembler-directive-amdgpu_hsa_kernel` directive is
+encountered. At each instruction, if the current value of this symbol is less
+than or equal to the maximum VPGR number explicitly referenced within that
+instruction then the symbol value is updated to equal that VGPR number plus
+one.
+
+.kernel.sgpr_count
+++++++++++++++++++
+
+Set to zero each time a
+:ref:`amdgpu-amdhsa-assembler-directive-amdgpu_hsa_kernel` directive is
+encountered. At each instruction, if the current value of this symbol is less
+than or equal to the maximum VPGR number explicitly referenced within that
+instruction then the symbol value is updated to equal that SGPR number plus
+one.
+
+.. _amdgpu-amdhsa-assembler-directives-v2:
+
+Code Object V2 Directives (-mattr=-code-object-v3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning:: Code Object V2 is not the default code object version emitted by
+  this version of LLVM. For a description of the directives supported with
+  the default configuration (Code Object V3) see
+  :ref:`amdgpu-amdhsa-assembler-directives-v3`.
 
 AMDGPU ABI defines auxiliary data in output code object. In assembly source,
 one can specify them with assembler directives.
@@ -4799,6 +4914,8 @@
 By default, the assembler will derive the ISA version, *vendor*, and *arch*
 from the value of the -mcpu option that is passed to the assembler.
 
+.. _amdgpu-amdhsa-assembler-directive-amdgpu_hsa_kernel:
+
 .amdgpu_hsa_kernel (name)
 +++++++++++++++++++++++++
 
@@ -4831,7 +4948,17 @@
 For a full list of amd_kernel_code_t keys, refer to AMDGPU ABI document,
 comments in lib/Target/AMDGPU/AmdKernelCodeT.h and test/CodeGen/AMDGPU/hsa.s.
 
-Here is an example of a minimal amd_kernel_code_t specification:
+.. _amdgpu-amdhsa-assembler-example-v2:
+
+Code Object V2 Example Source Code (-mattr=-code-object-v3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning:: Code Object V2 is not the default code object version emitted by
+  this version of LLVM. For a description of the directives supported with
+  the default configuration (Code Object V3) see
+  :ref:`amdgpu-amdhsa-assembler-example-v3`.
+
+Here is an example of a minimal assembly source file, defining one HSA kernel:
 
 .. code-block:: none
 
@@ -4866,8 +4993,10 @@
    .Lfunc_end0:
         .size   hello_world, .Lfunc_end0-hello_world
 
-Predefined Symbols (-mattr=+code-object-v3)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _amdgpu-amdhsa-assembler-predefined-symbols-v3:
+
+Code Object V3 Predefined Symbols (-mattr=+code-object-v3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The AMDGPU assembler defines and updates some symbols automatically. These
 symbols do not affect code generation.
@@ -4875,11 +5004,29 @@
 .amdgcn.gfx_generation_number
 +++++++++++++++++++++++++++++
 
-Set to the GFX generation number of the target being assembled for. For
+Set to the GFX major generation number of the target being assembled for. For
 example, when assembling for a "GFX9" target this will be set to the integer
-value "9". The possible GFX generation numbers are presented in
+value "9". The possible GFX major generation numbers are presented in
 :ref:`amdgpu-processors`.
 
+.amdgcn.gfx_generation_minor
+++++++++++++++++++++++++++++
+
+Set to the GFX minor generation number of the target being assembled for. For
+example, when assembling for a "GFX810" target this will be set to the integer
+value "1". The possible GFX minor generation numbers are presented in
+:ref:`amdgpu-processors`.
+
+.amdgcn.gfx_generation_stepping
++++++++++++++++++++++++++++++++
+
+Set to the GFX stepping generation number of the target being assembled for.
+For example, when assembling for a "GFX704" target this will be set to the
+integer value "4". The possible GFX stepping generation numbers are presented
+in :ref:`amdgpu-processors`.
+
+.. _amdgpu-amdhsa-assembler-symbol-next_free_vgpr:
+
 .amdgcn.next_free_vgpr
 ++++++++++++++++++++++
 
@@ -4893,6 +5040,8 @@
 
 May be set at any time, e.g. manually set to zero at the start of each kernel.
 
+.. _amdgpu-amdhsa-assembler-symbol-next_free_sgpr:
+
 .amdgcn.next_free_sgpr
 ++++++++++++++++++++++
 
@@ -4906,8 +5055,10 @@
 
 May be set at any time, e.g. manually set to zero at the start of each kernel.
 
-Code Object Directives (-mattr=+code-object-v3)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _amdgpu-amdhsa-assembler-directives-v3:
+
+Code Object V3 Directives (-mattr=+code-object-v3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Directives which begin with ``.amdgcn`` are valid for all ``amdgcn``
 architecture processors, and are not OS-specific. Directives which begin with
@@ -5047,8 +5198,10 @@
 
 This directive is terminated by an ``.end_amdgpu_metadata`` directive.
 
-Example HSA Source Code (-mattr=+code-object-v3)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _amdgpu-amdhsa-assembler-example-v3:
+
+Code Object V3 Example Source Code (-mattr=+code-object-v3)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Here is an example of a minimal assembly source file, defining one HSA kernel:
 
@@ -5098,6 +5251,80 @@
   ...
   .end_amdgpu_metadata
 
+If an assembly source file contains multiple kernels and/or functions, the
+:ref:`amdgpu-amdhsa-assembler-symbol-next_free_vgpr` and
+:ref:`amdgpu-amdhsa-assembler-symbol-next_free_sgpr` symbols may be reset using
+the ``.set <symbol>, <expression>`` directive. For example, in the case of two
+kernels, where ``function1`` is only called from ``kernel1`` it is sufficient
+to group the function with the kernel that calls it and reset the symbols
+between the two connected components:
+
+.. code-block:: none
+
+  .amdgcn_target "amdgcn-amd-amdhsa--gfx900+xnack" // optional
+
+  // gpr tracking symbols are implicitly set to zero
+
+  .text
+  .globl kern0
+  .p2align 8
+  .type kern0,@function
+  kern0:
+    // ...
+    s_endpgm
+  .Lkern0_end:
+    .size   kern0, .Lkern0_end-kern0
+
+  .rodata
+  .p2align 6
+  .amdhsa_kernel kern0
+    // ...
+    .amdhsa_next_free_vgpr .amdgcn.next_free_vgpr
+    .amdhsa_next_free_sgpr .amdgcn.next_free_sgpr
+  .end_amdhsa_kernel
+
+  // reset symbols to begin tracking usage in func1 and kern1
+  .set .amdgcn.next_free_vgpr, 0
+  .set .amdgcn.next_free_sgpr, 0
+
+  .text
+  .hidden func1
+  .global func1
+  .p2align 2
+  .type func1,@function
+  func1:
+    // ...
+    s_setpc_b64 s[30:31]
+  .Lfunc1_end:
+  .size func1, .Lfunc1_end-func1
+
+  .globl kern1
+  .p2align 8
+  .type kern1,@function
+  kern1:
+    // ...
+    s_getpc_b64 s[4:5]
+    s_add_u32 s4, s4, func1@rel32@lo+4
+    s_addc_u32 s5, s5, func1@rel32@lo+4
+    s_swappc_b64 s[30:31], s[4:5]
+    // ...
+    s_endpgm
+  .Lkern1_end:
+    .size   kern1, .Lkern1_end-kern1
+
+  .rodata
+  .p2align 6
+  .amdhsa_kernel kern1
+    // ...
+    .amdhsa_next_free_vgpr .amdgcn.next_free_vgpr
+    .amdhsa_next_free_sgpr .amdgcn.next_free_sgpr
+  .end_amdhsa_kernel
+
+These symbols cannot identify connected components in order to automatically
+track the usage for each kernel. However, in some cases careful organization of
+the kernels and functions in the source file means there is minimal additional
+effort required to accurately calculate GPR usage.
+
 Additional Documentation
 ========================
 
diff --git a/docs/AddingConstrainedIntrinsics.rst b/docs/AddingConstrainedIntrinsics.rst
new file mode 100644
index 0000000..672ce31
--- /dev/null
+++ b/docs/AddingConstrainedIntrinsics.rst
@@ -0,0 +1,94 @@
+==================================================
+How To Add A Constrained Floating-Point Intrinsic
+==================================================
+
+.. contents::
+   :local:
+
+.. warning::
+  This is a work in progress.
+
+Add the intrinsic
+=================
+
+Multiple files need to be updated when adding a new constrained intrinsic.
+
+Add the new intrinsic to the table of intrinsics.::
+
+  include/llvm/IR/Intrinsics.td
+
+Update class ConstrainedFPIntrinsic to know about the intrinsics.::
+
+  include/llvm/IR/IntrinsicInst.h
+
+Functions like ConstrainedFPIntrinsic::isUnaryOp() or
+ConstrainedFPIntrinsic::isTernaryOp() may need to know about the new
+intrinsic.::
+
+  lib/IR/IntrinsicInst.cpp
+
+Update the IR verifier::
+
+  lib/IR/Verifier.cpp
+
+Add SelectionDAG node types
+===========================
+
+Add the new STRICT version of the node type to the ISD::NodeType enum.::
+
+  include/llvm/CodeGen/ISDOpcodes.h
+
+In class SDNode update isStrictFPOpcode()::
+
+  include/llvm/CodeGen/SelectionDAGNodes.h
+
+A mapping from the STRICT SDnode type to the non-STRICT is done in
+TargetLoweringBase::getStrictFPOperationAction(). This allows STRICT
+nodes to be legalized similarly to the non-STRICT node type.::
+
+  include/llvm/CodeGen/TargetLowering.h
+
+Building the SelectionDAG
+-------------------------
+
+The switch statement in SelectionDAGBuilder::visitIntrinsicCall() needs
+to be updated to call SelectionDAGBuilder::visitConstrainedFPIntrinsic().
+That function, in turn, needs to be updated to know how to create the
+SDNode for the intrinsic. The new STRICT node will eventually be converted
+to the matching non-STRICT node. For this reason it should have the same
+operands and values as the non-STRICT version but should also use the chain.
+This makes subsequent sharing of code for STRICT and non-STRICT code paths
+easier.::
+
+  lib/CodeGen/SelectionDAG/SelectionDAGBuilder.cpp
+
+Most of the STRICT nodes get legalized the same as their matching non-STRICT
+counterparts. A new STRICT node with this property must get added to the
+switch in SelectionDAGLegalize::LegalizeOp().::
+
+  lib/CodeGen/SelectionDAG/LegalizeDAG.cpp
+
+Other parts of the legalizer may need to be updated as well. Look for
+places where the non-STRICT counterpart is legalized and update as needed.
+Be careful of the chain since STRICT nodes use it but their counterparts
+often don't.
+
+The code to do the conversion or mutation of the STRICT node to a non-STRICT
+version of the node happens in SelectionDAG::mutateStrictFPToFP(). Be
+careful updating this function since some nodes have the same return type
+as their input operand, but some are different. Both of these cases must
+be properly handled.::
+
+  lib/CodeGen/SelectionDAG/SelectionDAG.cpp
+
+To make debug logs readable it is helpful to update the SelectionDAG's
+debug logger:::
+
+  lib/CodeGen/SelectionDAG/SelectionDAGDumper.cpp
+
+Add documentation and tests
+===========================
+
+::
+
+  docs/LangRef.rst
diff --git a/docs/CMake.rst b/docs/CMake.rst
index a5a574e..92e7b9c 100644
--- a/docs/CMake.rst
+++ b/docs/CMake.rst
@@ -266,8 +266,12 @@
 **LLVM_ENABLE_THREADS**:BOOL
   Build with threads support, if available. Defaults to ON.
 
-**LLVM_ENABLE_CXX1Y**:BOOL
-  Build in C++1y mode, if available. Defaults to OFF.
+**LLVM_ENABLE_UNWIND_TABLES**:BOOL
+  Enable unwind tables in the binary.  Disabling unwind tables can reduce the
+  size of the libraries.  Defaults to ON.
+
+**LLVM_CXX_STD**:STRING
+  Build with the specified C++ standard. Defaults to "c++11".
 
 **LLVM_ENABLE_ASSERTIONS**:BOOL
   Enables code assertions. Defaults to ON if and only if ``CMAKE_BUILD_TYPE``
@@ -281,6 +285,15 @@
 **LLVM_ENABLE_EXPENSIVE_CHECKS**:BOOL
   Enable additional time/memory expensive checking. Defaults to OFF.
 
+**LLVM_ENABLE_IDE**:BOOL
+  Tell the build system that an IDE is being used. This in turn disables the
+  creation of certain convenience build system targets, such as the various
+  ``install-*`` and ``check-*`` targets, since IDEs don't always deal well with
+  a large number of targets. This is usually autodetected, but it can be
+  configured manually to explicitly control the generation of those targets. One
+  scenario where a manual override may be desirable is when using Visual Studio
+  2017's CMake integration, which would not be detected as an IDE otherwise.
+
 **LLVM_ENABLE_PIC**:BOOL
   Add the ``-fPIC`` flag to the compiler command-line, if the compiler supports
   this flag. Some systems, like Windows, do not need this flag. Defaults to ON.
@@ -573,6 +586,18 @@
   options, which are passed to the CCACHE_MAXSIZE and CCACHE_DIR environment
   variables, respectively.
 
+**LLVM_FORCE_USE_OLD_TOOLCHAIN**:BOOL
+  If enabled, the compiler and standard library versions won't be checked. LLVM
+  may not compile at all, or might fail at runtime due to known bugs in these
+  toolchains.
+
+**LLVM_TEMPORARILY_ALLOW_OLD_TOOLCHAIN**:BOOL
+  If enabled, the compiler version check will only warn when using a toolchain
+  which is about to be deprecated, instead of emitting an error.
+
+**LLVM_USE_NEWPM**:BOOL
+  If enabled, use the experimental new pass manager.
+
 CMake Caches
 ============
 
diff --git a/docs/CodeGenerator.rst b/docs/CodeGenerator.rst
index c0e3d53..e7f96e8 100644
--- a/docs/CodeGenerator.rst
+++ b/docs/CodeGenerator.rst
@@ -1589,6 +1589,20 @@
 allocated in the function prologue. Functions with dynamic stack allocations are
 not included.
 
+Emitting remark diagnostics in the object file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A section containing metadata on remark diagnostics will be emitted when
+-remarks-section is passed. The section contains:
+
+* a magic number: "REMARKS\\0"
+* the version number: a little-endian uint64_t
+* the total size of the string table (the size itself excluded):
+  little-endian uint64_t
+* a list of null-terminated strings
+* the absolute file path to the serialized remark diagnostics: a
+  null-terminated string.
+
 VLIW Packetizer
 ---------------
 
@@ -2513,8 +2527,8 @@
 
 ::
 
-  BPF_X     0x0  use src_reg register as source operand
-  BPF_K     0x1  use 32 bit immediate as source operand
+  BPF_X     0x1  use src_reg register as source operand
+  BPF_K     0x0  use 32 bit immediate as source operand
 
 and four MSB bits store operation code
 
diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst
index 88d8ff8..781b6bd 100644
--- a/docs/CodingStandards.rst
+++ b/docs/CodingStandards.rst
@@ -233,10 +233,9 @@
 
   //===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
   //
-  //                     The LLVM Compiler Infrastructure
-  //
-  // This file is distributed under the University of Illinois Open Source
-  // License. See LICENSE.TXT for details.
+  // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+  // See https://llvm.org/LICENSE.txt for license information.
+  // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   //
   //===----------------------------------------------------------------------===//
   ///
diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst
index 721d2c2..778f6bb 100644
--- a/docs/CommandGuide/FileCheck.rst
+++ b/docs/CommandGuide/FileCheck.rst
@@ -102,8 +102,8 @@
 
 .. option:: -D<VAR=VALUE>
 
-  Sets a filecheck variable ``VAR`` with value ``VALUE`` that can be used in
-  ``CHECK:`` lines.
+  Sets a filecheck pattern variable ``VAR`` with value ``VALUE`` that can be
+  used in ``CHECK:`` lines.
 
 .. option:: -version
 
@@ -111,13 +111,16 @@
 
 .. option:: -v
 
-  Print directive pattern matches.
+  Print good directive pattern matches.  However, if ``-input-dump=fail`` or
+  ``-input-dump=always``, add those matches as input annotations instead.
 
 .. option:: -vv
 
   Print information helpful in diagnosing internal FileCheck issues, such as
   discarded overlapping ``CHECK-DAG:`` matches, implicit EOF pattern matches,
   and ``CHECK-NOT:`` patterns that do not have matches.  Implies ``-v``.
+  However, if ``-input-dump=fail`` or ``-input-dump=always``, just add that
+  information as input annotations instead.
 
 .. option:: --allow-deprecated-dag-overlap
 
@@ -517,14 +520,14 @@
 braces explicitly from the input, you can use something ugly like
 ``{{[{][{]}}`` as your pattern.
 
-FileCheck Variables
-~~~~~~~~~~~~~~~~~~~
+FileCheck Pattern Expressions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It is often useful to match a pattern and then verify that it occurs again
 later in the file.  For codegen tests, this can be useful to allow any register,
 but verify that that register is used consistently later.  To do this,
-:program:`FileCheck` allows named variables to be defined and substituted into
-patterns.  Here is a simple example:
+:program:`FileCheck` supports pattern expressions that allow pattern variables
+to be defined and substituted into patterns.  Here is a simple example:
 
 .. code-block:: llvm
 
@@ -557,31 +560,38 @@
 This makes it easier to ensure that individual tests are not affected
 by variables set in preceding tests.
 
-FileCheck Expressions
-~~~~~~~~~~~~~~~~~~~~~
+FileCheck Numeric Expressions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Sometimes there's a need to verify output which refers line numbers of the
+Sometimes there's a need to verify output that contains line numbers of the
 match file, e.g. when testing compiler diagnostics.  This introduces a certain
 fragility of the match file structure, as "``CHECK:``" lines contain absolute
 line numbers in the same file, which have to be updated whenever line numbers
 change due to text addition or deletion.
 
-To support this case, FileCheck allows using ``[[@LINE]]``,
-``[[@LINE+<offset>]]``, ``[[@LINE-<offset>]]`` expressions in patterns. These
-expressions expand to a number of the line where a pattern is located (with an
-optional integer offset).
+To support this case, FileCheck allows using ``[[#@LINE]]``,
+``[[#@LINE+<offset>]]`` and ``[[#@LINE-<offset>]]`` numeric expressions in
+patterns, with an arbitrary number of spaces between each element of the
+expression. These expressions expand to the number of the line where a pattern
+is located (with an optional integer offset).
 
 This way match patterns can be put near the relevant test lines and include
 relative line number references, for example:
 
 .. code-block:: c++
 
-   // CHECK: test.cpp:[[@LINE+4]]:6: error: expected ';' after top level declarator
+   // CHECK: test.cpp:[[# @LINE + 4]]:6: error: expected ';' after top level declarator
    // CHECK-NEXT: {{^int a}}
    // CHECK-NEXT: {{^     \^}}
    // CHECK-NEXT: {{^     ;}}
    int a
 
+To support legacy uses of ``@LINE`` as a special pattern variable,
+:program:`FileCheck` also accepts the following uses of ``@LINE`` with pattern
+variable syntax: ``[[@LINE]]``, ``[[@LINE+<offset>]]`` and
+``[[@LINE-<offset>]]`` without any spaces inside the brackets and where
+``offset`` is an integer.
+
 Matching Newline Characters
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/CommandGuide/index.rst b/docs/CommandGuide/index.rst
index 9108ae6..8a6edf5 100644
--- a/docs/CommandGuide/index.rst
+++ b/docs/CommandGuide/index.rst
@@ -31,6 +31,7 @@
    llvm-profdata
    llvm-stress
    llvm-symbolizer
+   llvm-addr2line
    llvm-dwarfdump
    dsymutil
    llvm-mca
diff --git a/docs/CommandGuide/llc.rst b/docs/CommandGuide/llc.rst
index da096f1..aaf7e2e 100644
--- a/docs/CommandGuide/llc.rst
+++ b/docs/CommandGuide/llc.rst
@@ -140,6 +140,10 @@
  in the function prologue. Functions with dynamic stack allocations are not
  included.
 
+.. option:: -remarks-section
+
+ Emit the .remarks (ELF) / __remarks (MachO) section which contains metadata
+ about remark diagnostics.
 
 Tuning/Configuration Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/CommandGuide/llvm-addr2line.md b/docs/CommandGuide/llvm-addr2line.md
new file mode 100644
index 0000000..03224c4
--- /dev/null
+++ b/docs/CommandGuide/llvm-addr2line.md
@@ -0,0 +1,28 @@
+# llvm-addr2line - a drop-in replacement for addr2line
+
+## SYNOPSIS
+
+**llvm-addr2line** [*options*]
+
+## DESCRIPTION
+
+**llvm-addr2line** is an alias for the [llvm-symbolizer](llvm-symbolizer) tool
+with different defaults. The goal is to make it a drop-in replacement for
+GNU's **addr2line**.
+
+Here are some of those differences:
+
+* Defaults not to print function names. Use [-f](llvm-symbolizer-opt-f)
+  to enable that.
+
+* Defaults not to demangle function names. Use [-C](llvm-symbolizer-opt-C)
+  to switch the demangling on.
+
+* Defaults not to print inlined frames. Use [-i](llvm-symbolizer-opt-i)
+  to show inlined frames for a source code location in an inlined function.
+
+* Uses [--output-style=GNU](llvm-symbolizer-opt-output-style) by default.
+
+## SEE ALSO
+
+Refer to [llvm-symbolizer](llvm-symbolizer) for additional information.
diff --git a/docs/CommandGuide/llvm-cov.rst b/docs/CommandGuide/llvm-cov.rst
index 71924e9..7cc7d3f 100644
--- a/docs/CommandGuide/llvm-cov.rst
+++ b/docs/CommandGuide/llvm-cov.rst
@@ -150,6 +150,11 @@
 
  Display the version of llvm-cov.
 
+.. option:: -x, --hash-filenames
+
+ Use md5 hash of file name when naming the coverage output files. The source
+ file name will be suffixed by ``##`` followed by MD5 hash calculated for it.
+
 EXIT STATUS
 ^^^^^^^^^^^
 
@@ -414,3 +419,16 @@
 .. option:: -ignore-filename-regex=<PATTERN>
 
  Skip source code files with file paths that match the given regular expression.
+
+ .. option:: -skip-expansions
+
+ Skip exporting macro expansion coverage data.
+
+ .. option:: -skip-functions
+
+ Skip exporting per-function coverage data.
+
+ .. option:: -num-threads=N, -j=N
+
+ Use N threads to export coverage data. When N=0, llvm-cov auto-detects an
+ appropriate number of threads to use. This is the default.
diff --git a/docs/CommandGuide/llvm-exegesis.rst b/docs/CommandGuide/llvm-exegesis.rst
index f27db9e..cbb9009 100644
--- a/docs/CommandGuide/llvm-exegesis.rst
+++ b/docs/CommandGuide/llvm-exegesis.rst
@@ -10,13 +10,13 @@
 -----------
 
 :program:`llvm-exegesis` is a benchmarking tool that uses information available
-in LLVM to measure host machine instruction characteristics like latency or port
-decomposition.
+in LLVM to measure host machine instruction characteristics like latency,
+throughput, or port decomposition.
 
 Given an LLVM opcode name and a benchmarking mode, :program:`llvm-exegesis`
 generates a code snippet that makes execution as serial (resp. as parallel) as
-possible so that we can measure the latency (resp. uop decomposition) of the
-instruction.
+possible so that we can measure the latency (resp. inverse throughput/uop decomposition)
+of the instruction.
 The code snippet is jitted and executed on the host subtarget. The time taken
 (resp. resource usage) is measured using hardware performance counters. The
 result is printed out as YAML to the standard output.
@@ -37,11 +37,13 @@
 
     $ llvm-exegesis -mode=latency -opcode-name=ADD64rr
 
-Measuring the uop decomposition of an instruction works similarly:
+Measuring the uop decomposition or inverse throughput of an instruction works similarly:
 
 .. code-block:: bash
 
     $ llvm-exegesis -mode=uops -opcode-name=ADD64rr
+    $ llvm-exegesis -mode=inverse_throughput -opcode-name=ADD64rr
+
 
 The output is a YAML document (the default is to write to stdout, but you can
 redirect the output to a file using `-benchmarks-file`):
@@ -186,9 +188,11 @@
   Specify the custom code snippet to measure. See example 2 for details.
   Either `opcode-index`, `opcode-name` or `snippets-file` must be set.
 
-.. option:: -mode=[latency|uops|analysis]
+.. option:: -mode=[latency|uops|inverse_throughput|analysis]
 
- Specify the run mode.
+ Specify the run mode. Note that if you pick `analysis` mode, you also need
+ to specify at least one of the `-analysis-clusters-output-file=` and
+ `-analysis-inconsistencies-output-file=`.
 
 .. option:: -num-repetitions=<Number of repetition>
 
@@ -197,37 +201,62 @@
 
 .. option:: -benchmarks-file=</path/to/file>
 
- File to read (`analysis` mode) or write (`latency`/`uops` modes) benchmark
- results. "-" uses stdin/stdout.
+ File to read (`analysis` mode) or write (`latency`/`uops`/`inverse_throughput`
+ modes) benchmark results. "-" uses stdin/stdout.
 
 .. option:: -analysis-clusters-output-file=</path/to/file>
 
  If provided, write the analysis clusters as CSV to this file. "-" prints to
- stdout.
+ stdout. By default, this analysis is not run.
 
 .. option:: -analysis-inconsistencies-output-file=</path/to/file>
 
  If non-empty, write inconsistencies found during analysis to this file. `-`
- prints to stdout.
+ prints to stdout. By default, this analysis is not run.
+
+.. option:: -analysis-clustering=[dbscan,naive]
+
+ Specify the clustering algorithm to use. By default DBSCAN will be used.
+ Naive clustering algorithm is better for doing further work on the
+ `-analysis-inconsistencies-output-file=` output, it will create one cluster
+ per opcode, and check that the cluster is stable (all points are neighbours).
 
 .. option:: -analysis-numpoints=<dbscan numPoints parameter>
 
  Specify the numPoints parameters to be used for DBSCAN clustering
+ (`analysis` mode, DBSCAN only).
+
+.. option:: -analysis-clustering-epsilon=<dbscan epsilon parameter>
+
+ Specify the epsilon parameter used for clustering of benchmark points
  (`analysis` mode).
 
-.. option:: -analysis-espilon=<dbscan epsilon parameter>
+.. option:: -analysis-inconsistency-epsilon=<epsilon>
 
- Specify the numPoints parameters to be used for DBSCAN clustering
- (`analysis` mode).
+ Specify the epsilon parameter used for detection of when the cluster
+ is different from the LLVM schedule profile values (`analysis` mode).
+
+.. option:: -analysis-display-unstable-clusters
+
+ If there is more than one benchmark for an opcode, said benchmarks may end up
+ not being clustered into the same cluster if the measured performance
+ characteristics are different. by default all such opcodes are filtered out.
+ This flag will instead show only such unstable opcodes.
 
 .. option:: -ignore-invalid-sched-class=false
 
  If set, ignore instructions that do not have a sched class (class idx = 0).
 
- .. option:: -mcpu=<cpu name>
+.. option:: -mcpu=<cpu name>
 
-  If set, measure the cpu characteristics using the counters for this CPU. This
-  is useful when creating new sched models (the host CPU is unknown to LLVM).
+ If set, measure the cpu characteristics using the counters for this CPU. This
+ is useful when creating new sched models (the host CPU is unknown to LLVM).
+
+.. option:: --dump-object-to-disk=true
+
+ By default, llvm-exegesis will dump the generated code to a temporary file to
+ enable code inspection. You may disable it to speed up the execution and save
+ disk space.
 
 EXIT STATUS
 -----------
diff --git a/docs/CommandGuide/llvm-mca.rst b/docs/CommandGuide/llvm-mca.rst
index bc50794..5d504a9 100644
--- a/docs/CommandGuide/llvm-mca.rst
+++ b/docs/CommandGuide/llvm-mca.rst
@@ -169,6 +169,12 @@
   the theoretical uniform distribution of resource pressure for every
   instruction in sequence.
 
+.. option:: -bottleneck-analysis
+
+  Print information about bottlenecks that affect the throughput. This analysis
+  can be expensive, and it is disabled by default.  Bottlenecks are highlighted
+  in the summary view.
+
 
 EXIT STATUS
 -----------
@@ -492,7 +498,7 @@
    2,              314  (51.5%)
 
 
-  Schedulers - number of cycles where we saw N instructions issued:
+  Schedulers - number of cycles where we saw N micro opcodes issued:
   [# issued], [# cycles]
    0,          7  (1.1%)
    1,          306  (50.2%)
@@ -546,9 +552,9 @@
 ``-all-stats`` or ``-dispatch-stats``.
 
 The next table, *Schedulers*, presents a histogram displaying a count,
-representing the number of instructions issued on some number of cycles.  In
-this case, of the 610 simulated cycles, single instructions were issued 306
-times (50.2%) and there were 7 cycles where no instructions were issued.
+representing the number of micro opcodes issued on some number of cycles. In
+this case, of the 610 simulated cycles, single opcodes were issued 306 times
+(50.2%) and there were 7 cycles where no opcodes were issued.
 
 The *Scheduler's queue usage* table shows that the average and maximum number of
 buffer entries (i.e., scheduler queue entries) used at runtime.  Resource JFPU01
diff --git a/docs/CommandGuide/llvm-profdata.rst b/docs/CommandGuide/llvm-profdata.rst
index f66fb49..7f5887a 100644
--- a/docs/CommandGuide/llvm-profdata.rst
+++ b/docs/CommandGuide/llvm-profdata.rst
@@ -17,6 +17,7 @@
 
 * :ref:`merge <profdata-merge>`
 * :ref:`show <profdata-show>`
+* :ref:`overlap <profdata-overlap>`
 
 .. program:: llvm-profdata merge
 
@@ -226,6 +227,77 @@
  Only output names of functions whose max count value are below the cutoff
  value.
 
+.. option:: -showcs
+
+ Only show context sensitive profile counts. The default is to filter all
+ context sensitive profile counts.
+
+.. program:: llvm-profdata overlap
+
+.. _profdata-overlap:
+
+OVERLAP
+-------
+
+SYNOPSIS
+^^^^^^^^
+
+:program:`llvm-profdata overlap` [*options*] [*base profile file*] [*test profile file*]
+
+DESCRIPTION
+^^^^^^^^^^^
+
+:program:`llvm-profdata overlap` takes two profile data files and displays the
+*overlap* of counter distribution between the whole files and between any of the
+specified functions.
+
+In this command, *overlap* is defined as follows:
+Suppose *base profile file* has the following counts:
+{c1_1, c1_2, ..., c1_n, c1_u_1, c2_u_2, ..., c2_u_s},
+and *test profile file* has
+{c2_1, c2_2, ..., c2_n, c2_v_1, c2_v_2, ..., c2_v_t}.
+Here c{1|2}_i (i = 1 .. n) are matched counters and c1_u_i (i = 1 .. s) and
+c2_v_i (i = 1 .. v) are unmatched counters (or counters only existing in)
+*base profile file* and *test profile file*, respectively.
+Let sum_1 = c1_1 + c1_2 +  ... + c1_n +  c1_u_1 + c2_u_2 + ... + c2_u_s, and
+sum_2 = c2_1 + c2_2 + ... + c2_n + c2_v_1 + c2_v_2 + ... + c2_v_t.
+*overlap* = min(c1_1/sum_1, c2_1/sum_2) + min(c1_2/sum_1, c2_2/sum_2) + ...
++ min(c1_n/sum_1, c2_n/sum_2).
+
+The result overlap distribution is a percentage number, ranging from 0.0% to
+100.0%, where 0.0% means there is no overlap and 100.0% means a perfect
+overlap.
+
+Here is an example, if *base profile file* has counts of {400, 600}, and
+*test profile file* has matched counts of {60000, 40000}. The *overlap* is 80%.
+
+
+OPTIONS
+^^^^^^^
+
+.. option:: -function=string
+
+ Print details for a function if the function's name contains the given string.
+
+.. option:: -help
+
+ Print a summary of command line options.
+
+.. option:: -o=output or -o output
+
+ Specify the output file name.  If *output* is ``-`` or it isn't specified,
+ then the output is sent to standard output.
+
+.. option:: -value-cutoff=n
+
+ Show only those functions whose max count values are greater or equal to ``n``.
+ By default, the value-cutoff is set to max of unsigned long long.
+
+.. option:: -cs
+
+ Only show overlap for the context sensitive profile counts. The default is to show
+ non-context sensitive profile counts.
+
 EXIT STATUS
 -----------
 
diff --git a/docs/CommandGuide/llvm-readobj.rst b/docs/CommandGuide/llvm-readobj.rst
index 417fcd0..7d4679f 100644
--- a/docs/CommandGuide/llvm-readobj.rst
+++ b/docs/CommandGuide/llvm-readobj.rst
@@ -84,6 +84,10 @@
 
  Display section groups (only for ELF object files).
 
+.. option:: -demangle, -C
+
+ Print demangled symbol names in the output.
+
 EXIT STATUS
 -----------
 
diff --git a/docs/CommandGuide/llvm-symbolizer.rst b/docs/CommandGuide/llvm-symbolizer.rst
index 3c7a26e..b9368f5 100644
--- a/docs/CommandGuide/llvm-symbolizer.rst
+++ b/docs/CommandGuide/llvm-symbolizer.rst
@@ -72,22 +72,34 @@
 
   Path to object file to be symbolized.
 
-.. option:: -functions=[none|short|linkage]
+.. _llvm-symbolizer-opt-f:
+
+.. option:: -functions[=<none|short|linkage>], -f
 
   Specify the way function names are printed (omit function name,
   print short function name, or print full linkage name, respectively).
   Defaults to ``linkage``.
 
+.. _llvm-symbolizer-opt-use-symbol-table:
+
 .. option:: -use-symbol-table
 
  Prefer function names stored in symbol table to function names
  in debug info sections. Defaults to true.
 
+.. _llvm-symbolizer-opt-C:
+
 .. option:: -demangle, -C
 
  Print demangled function names. Defaults to true.
 
-.. option:: -inlining 
+.. option:: -no-demangle
+
+ Don't print demangled function names.
+
+.. _llvm-symbolizer-opt-i:
+
+.. option:: -inlining, -inlines, -i
 
  If a source code location is in an inlined function, prints all the
  inlnied frames. Defaults to true.
@@ -115,6 +127,48 @@
  Print human readable output. If ``-inlining`` is specified, enclosing scope is
  prefixed by (inlined by). Refer to listed examples.
 
+.. option:: -basenames, -s
+
+ Strip directories when printing the file path.
+
+.. option:: -adjust-vma=<offset>
+
+ Add the specified offset to object file addresses when performing lookups. This
+ can be used to perform lookups as if the object were relocated by the offset.
+
+.. _llvm-symbolizer-opt-output-style:
+
+.. option:: -output-style=<LLVM|GNU>
+
+  Specify the preferred output style. Defaults to ``LLVM``. When the output
+  style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
+  The differences from the ``LLVM`` style are:
+  
+  * Does not print column of a source code location.
+
+  * Does not add an empty line after the report for an address.
+
+  * Does not replace the name of an inlined function with the name of the
+    topmost caller when inlined frames are not shown and ``-use-symbol-table``
+    is on.
+
+  .. code-block:: console
+
+    $ llvm-symbolizer -p -e=addr.exe 0x40054d 0x400568
+    inc at /tmp/x.c:3:3
+     (inlined by) main at /tmp/x.c:14:0
+
+    main at /tmp/x.c:14:3
+
+    $ llvm-symbolizer --output-style=LLVM -p -i=0 -e=addr.exe 0x40054d 0x400568
+    main at /tmp/x.c:3:3
+
+    main at /tmp/x.c:14:3
+
+    $ llvm-symbolizer --output-style=GNU -p -i=0 -e=addr.exe 0x40054d 0x400568
+    inc at /tmp/x.c:3
+    main at /tmp/x.c:14
+
 EXIT STATUS
 -----------
 
diff --git a/docs/CommandLine.rst b/docs/CommandLine.rst
index 9a6a196..34bee93 100644
--- a/docs/CommandLine.rst
+++ b/docs/CommandLine.rst
@@ -128,6 +128,7 @@
   USAGE: compiler [options]
 
   OPTIONS:
+    -h                - Alias for -help
     -help             - display available options (-help-hidden for more)
     -o <filename>     - Specify output filename
 
@@ -194,6 +195,7 @@
   USAGE: compiler [options] <input file>
 
   OPTIONS:
+    -h                - Alias for -help
     -help             - display available options (-help-hidden for more)
     -o <filename>     - Specify output filename
 
@@ -1168,11 +1170,18 @@
 .. _grouping:
 .. _cl::Grouping:
 
-* The **cl::Grouping** modifier is used to implement Unix-style tools (like
-  ``ls``) that have lots of single letter arguments, but only require a single
-  dash.  For example, the '``ls -labF``' command actually enables four different
-  options, all of which are single letters.  Note that **cl::Grouping** options
-  cannot have values.
+Controlling options grouping
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The **cl::Grouping** modifier can be combined with any formatting types except
+for `cl::Positional`_.  It is used to implement Unix-style tools (like ``ls``)
+that have lots of single letter arguments, but only require a single dash.
+For example, the '``ls -labF``' command actually enables four different options,
+all of which are single letters.
+
+Note that **cl::Grouping** options can have values only if they are used
+separately or at the end of the groups.  For `cl::ValueRequired`_, it is
+a runtime error if such an option is used elsewhere in the group.
 
 The CommandLine library does not restrict how you use the **cl::Prefix** or
 **cl::Grouping** modifiers, but it is possible to specify ambiguous argument
@@ -1187,19 +1196,24 @@
 
   parse(string OrigInput) {
 
-  1. string input = OrigInput;
-  2. if (isOption(input)) return getOption(input).parse();  // Normal option
-  3. while (!isOption(input) && !input.empty()) input.pop_back();  // Remove the last letter
-  4. if (input.empty()) return error();  // No matching option
-  5. if (getOption(input).isPrefix())
-       return getOption(input).parse(input);
-  6. while (!input.empty()) {  // Must be grouping options
-       getOption(input).parse();
-       OrigInput.erase(OrigInput.begin(), OrigInput.begin()+input.length());
-       input = OrigInput;
-       while (!isOption(input) && !input.empty()) input.pop_back();
+  1. string Input = OrigInput;
+  2. if (isOption(Input)) return getOption(Input).parse();  // Normal option
+  3. while (!Input.empty() && !isOption(Input)) Input.pop_back();  // Remove the last letter
+  4. while (!Input.empty()) {
+       string MaybeValue = OrigInput.substr(Input.length())
+       if (getOption(Input).isPrefix())
+         return getOption(Input).parse(MaybeValue)
+       if (!MaybeValue.empty() && MaybeValue[0] == '=')
+         return getOption(Input).parse(MaybeValue.substr(1))
+       if (!getOption(Input).isGrouping())
+         return error()
+       getOption(Input).parse()
+       Input = OrigInput = MaybeValue
+       while (!Input.empty() && !isOption(Input)) Input.pop_back();
+       if (!Input.empty() && !getOption(Input).isGrouping())
+         return error()
      }
-  7. if (!OrigInput.empty()) error();
+  5. if (!OrigInput.empty()) error();
 
   }
 
@@ -1220,6 +1234,14 @@
   option is allowed to accept one or more values (i.e. it is a `cl::list`_
   option).
 
+.. _cl::DefaultOption:
+
+* The **cl::DefaultOption** modifier is used to specify that the option is a
+  default that can be overridden by application specific parsers. For example,
+  the ``-help`` alias, ``-h``, is registered this way, so it can be overridden
+  by applications that need to use the ``-h`` option for another purpose,
+  either as a regular option or an alias for another option.
+
 .. _cl::PositionalEatsArgs:
 
 * The **cl::PositionalEatsArgs** modifier (which only applies to positional
@@ -1239,8 +1261,6 @@
   with ``cl::CommaSeparated``, this modifier only makes sense with a `cl::list`_
   option.
 
-So far, these are the only three miscellaneous option modifiers.
-
 .. _response files:
 
 Response files
diff --git a/docs/CompileCudaWithLLVM.rst b/docs/CompileCudaWithLLVM.rst
index 95d6b0d..6e181c8 100644
--- a/docs/CompileCudaWithLLVM.rst
+++ b/docs/CompileCudaWithLLVM.rst
@@ -143,9 +143,9 @@
 ----------------------------
 
 In clang, ``math.h`` and ``cmath`` are available and `pass
-<https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/math_h.cu>`_
+<https://github.com/llvm/llvm-test-suite/blob/master/External/CUDA/math_h.cu>`_
 `tests
-<https://github.com/llvm-mirror/test-suite/blob/master/External/CUDA/cmath.cu>`_
+<https://github.com/llvm/llvm-test-suite/blob/master/External/CUDA/cmath.cu>`_
 adapted from libc++'s test suite.
 
 In nvcc ``math.h`` and ``cmath`` are mostly available.  Versions of ``::foof``
diff --git a/docs/CompilerWriterInfo.rst b/docs/CompilerWriterInfo.rst
index 838c36a..731d24a 100644
--- a/docs/CompilerWriterInfo.rst
+++ b/docs/CompilerWriterInfo.rst
@@ -16,16 +16,24 @@
 AArch64 & ARM
 -------------
 
-* `ARMv8-A Architecture Reference Manual <http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0487a.h/index.html>`_ (authentication required, free sign-up). This document covers both AArch64 and ARM instructions
+* `ARMv8-A Architecture Reference Manual <https://developer.arm.com/docs/ddi0487/latest>`_ This document covers both AArch64 and ARM instructions
 
-* `ARMv7-M Architecture Reference Manual <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0403e.b/index.html>`_ (authentication required, free sign-up). This covers the Thumb2-only microcontrollers
+* `ARMv7-A Architecture Reference Manual <https://developer.arm.com/docs/ddi0406/latest>`_ This has some useful info on what is supported by older architecture versions.
 
-* `ARMv6-M Architecture Reference Manual <http://infocenter.arm.com/help/topic/com.arm.doc.ddi0419c/index.html>`_ (authentication required, free sign-up). This covers the Thumb1-only microcontrollers
+* `ARMv7-M Architecture Reference Manual <https://developer.arm.com/docs/ddi0403/latest>`_ This covers the Thumb2-only microcontrollers
+
+* `ARMv6-M Architecture Reference Manual <https://developer.arm.com/docs/ddi0419/latest>`_ This covers the Thumb1-only microcontrollers
 
 * `ARM C Language Extensions <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_
 
+* `ARM NEON Intrinsics Reference <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0073b/IHI0073B_arm_neon_intrinsics_ref.pdf>`_
+
 * AArch32 `ABI Addenda and Errata <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0045d/IHI0045D_ABI_addenda.pdf>`_
 
+* `Cortex-A57 Software Optimization Guide <http://infocenter.arm.com/help/topic/com.arm.doc.uan0015b/Cortex_A57_Software_Optimization_Guide_external.pdf>`_
+
+* `Run-time ABI for the ARM Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0043d/IHI0043D_rtabi.pdf>`_ This documents the __aeabi_* helper functions.
+
 Itanium (ia64)
 --------------
 
@@ -119,7 +127,7 @@
 ===
 
 * `System V Application Binary Interface <http://www.sco.com/developers/gabi/latest/contents.html>`_
-* `Itanium C++ ABI <http://itanium-cxx-abi.github.io/cxx-abi/>`_
+* `Itanium C++ ABI <http://itanium-cxx-abi.github.io/cxx-abi/>`_ (This is used for all non-Windows targets.)
 
 Linux
 -----
@@ -127,6 +135,7 @@
 * `Linux extensions to gabi <https://github.com/hjl-tools/linux-abi/wiki/Linux-Extensions-to-gABI>`_
 * `PowerPC 64-bit ELF ABI Supplement <http://www.linuxbase.org/spec/ELF/ppc64/>`_
 * `Procedure Call Standard for the AArch64 Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055a/IHI0055A_aapcs64.pdf>`_
+* `Procedure Call Standard for the ARM Architecture <https://developer.arm.com/docs/ihi0042/latest>`_
 * `ELF for the ARM Architecture <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0044e/IHI0044E_aaelf.pdf>`_
 * `ELF for the ARM 64-bit Architecture (AArch64) <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0056a/IHI0056A_aaelf64.pdf>`_
 * `System z ELF ABI Supplement <http://legacy.redhat.com/pub/redhat/linux/7.1/es/os/s390x/doc/lzsabi0.pdf>`_
@@ -136,11 +145,16 @@
 
 * `Mach-O Runtime Architecture <http://developer.apple.com/documentation/Darwin/RuntimeArchitecture-date.html>`_
 * `Notes on Mach-O ABI <http://www.unsanity.org/archives/000044.php>`_
+* `ARM64 Function Calling Conventions <https://developer.apple.com/library/archive/documentation/Xcode/Conceptual/iPhoneOSABIReference/Articles/ARM64FunctionCallingConventions.html>`_
 
 Windows
 -------
 
 * `Microsoft PE/COFF Specification <http://www.microsoft.com/whdc/system/platform/firmware/pecoff.mspx>`_
+* `ARM64 exception handling <https://docs.microsoft.com/en-us/cpp/build/arm64-exception-handling>`_
+* `ARM exception handling <https://docs.microsoft.com/en-us/cpp/build/arm-exception-handling>`_
+* `Overview of ARM64 ABI conventions <https://docs.microsoft.com/en-us/cpp/build/arm64-windows-abi-conventions>`_
+* `Overview of ARM32 ABI Conventions <https://docs.microsoft.com/en-us/cpp/build/overview-of-arm-abi-conventions>`_
 
 NVPTX
 =====
diff --git a/docs/DeveloperPolicy.rst b/docs/DeveloperPolicy.rst
index 0991294..003f75f 100644
--- a/docs/DeveloperPolicy.rst
+++ b/docs/DeveloperPolicy.rst
@@ -22,7 +22,7 @@
 
 #. Make life as simple and easy for contributors as possible.
 
-#. Keep the tip of tree as stable as possible.
+#. Keep the top of tree as stable as possible.
 
 #. Establish awareness of the project's :ref:`copyright, license, and patent
    policies <copyright-license-patents>` with contributors to the project.
@@ -113,8 +113,8 @@
 program.
 
 When submitting patches, please do not add confidentiality or non-disclosure
-notices to the patches themselves.  These notices conflict with the `LLVM
-License`_ and may result in your contribution being excluded.
+notices to the patches themselves.  These notices conflict with the LLVM
+licensing terms and may result in your contribution being excluded.
 
 .. _code review:
 
@@ -638,6 +638,50 @@
 status, but also markers to define bit-rot, and will be used to clean up the
 tree from unmaintained targets.
 
+.. _toolchain:
+
+Updating Toolchain Requirements
+-------------------------------
+
+We intend to require newer toolchains as time goes by. This means LLVM's
+codebase can use newer versions of C++ as they get standardized. Requiring newer
+toolchains to build LLVM can be painful for those building LLVM; therefore, it
+will only be done through the following process:
+
+  * Generally, try to support LLVM and GCC versions from the last 3 years at a
+    minimum. This time-based guideline is not strict: we may support much older
+    compilers, or decide to support fewer versions.
+
+  * An RFC is sent to the `llvm-dev mailing list <http://lists.llvm.org/mailman/listinfo/llvm-dev>`_
+
+    - Detail upsides of the version increase (e.g. which newer C++ language or
+      library features LLVM should use; avoid miscompiles in particular compiler
+      versions, etc).
+    - Detail downsides on important platforms (e.g. Ubuntu LTS status).
+
+  * Once the RFC reaches consensus, update the CMake toolchain version checks as
+    well as the :doc:`getting started<GettingStarted>` guide. We want to
+    soft-error when developers compile LLVM. We say "soft-error" because the
+    error can be turned into a warning using a CMake flag. This is an important
+    step: LLVM still doesn't have code which requires the new toolchains, but it
+    soon will. If you compile LLVM but don't read the mailing list, we should
+    tell you!
+
+  * Ensure that at least one LLVM release has had this soft-error. Not all
+    developers compile LLVM top-of-tree. These release-bound developers should
+    also be told about upcoming changes.
+
+  * Turn the soft-error into a hard-error after said LLVM release has branched.
+
+  * Update the :doc:`coding standards<CodingStandards>` to allow the new
+    features we've explicitly approved in the RFC.
+
+  * Start using the new features in LLVM's codebase.
+
+Here's a `sample RFC
+<http://lists.llvm.org/pipermail/llvm-dev/2019-January/129452.html>`_ and the
+`corresponding change <https://reviews.llvm.org/D57264>`_.
+
 .. _copyright-license-patents:
 
 Copyright, License, and Patents
@@ -646,44 +690,227 @@
 .. note::
 
    This section deals with legal matters but does not provide legal advice.  We
-   are not lawyers --- please seek legal counsel from an attorney.
+   are not lawyers --- please seek legal counsel from a licensed attorney.
 
 This section addresses the issues of copyright, license and patents for the LLVM
-project.  The copyright for the code is held by the individual contributors of
-the code and the terms of its license to LLVM users and developers is the
-`University of Illinois/NCSA Open Source License
-<http://www.opensource.org/licenses/UoI-NCSA.php>`_ (with portions dual licensed
-under the `MIT License <http://www.opensource.org/licenses/mit-license.php>`_,
-see below).  As contributor to the LLVM project, you agree to allow any
-contributions to the project to licensed under these terms.
+project.  The copyright for the code is held by the contributors of
+the code.  The code is licensed under permissive `open source licensing terms`_,
+namely the Apache 2 license, which includes a copyright and `patent license`_.
+When you contribute code to the LLVM project, you license it under these terms.
+
+If you have questions or comments about these topics, please contact the
+`LLVM Developer's Mailing List <mailto:llvm-dev@lists.llvm.org>`_.  However,
+please realize that most compiler developers are not lawyers, and therefore you
+will not be getting official legal advice.
 
 Copyright
 ---------
 
-The LLVM project does not require copyright assignments, which means that the
-copyright for the code in the project is held by its respective contributors who
-have each agreed to release their contributed code under the terms of the `LLVM
-License`_.
+The LLVM project does not collect copyright assignments, which means that the
+copyright for the code in the project is held by the respective contributors.
+Because you (or your company)
+retain ownership of the code you contribute, you know it may only be used under
+the terms of the open source license you contributed it under: the license for
+your contributions cannot be changed in the future without your approval.
 
-An implication of this is that the LLVM license is unlikely to ever change:
-changing it would require tracking down all the contributors to LLVM and getting
-them to agree that a license change is acceptable for their contribution.  Since
-there are no plans to change the license, this is not a cause for concern.
+Because the LLVM project does not require copyright assignments, changing the
+LLVM license requires tracking down the
+contributors to LLVM and getting them to agree that a license change is
+acceptable for their contributions.  We feel that a high burden for relicensing
+is good for the project, because contributors do not have to fear that their
+code will be used in a way with which they disagree.
 
-As a contributor to the project, this means that you (or your company) retain
-ownership of the code you contribute, that it cannot be used in a way that
-contradicts the license (which is a liberal BSD-style license), and that the
-license for your contributions won't change without your approval in the
-future.
+Relicensing
+-----------
 
-.. _LLVM License:
+The last paragraph notwithstanding, the LLVM Project is in the middle of a large
+effort to change licenses, which aims to solve several problems:
 
-License
+* The old licenses made it difficult to move code from (e.g.) the compiler to
+  runtime libraries, because runtime libraries used a different license from the
+  rest of the compiler.
+* Some contributions were not submitted to LLVM due to concerns that
+  the patent grant required by the project was overly broad.
+* The patent grant was unique to the LLVM Project, not written by a lawyer, and
+  was difficult to determine what was protection was provided (if any).
+
+The scope of relicensing is all code that is considered part of the LLVM
+project, including the main LLVM repository, runtime libraries (compiler_rt,
+OpenMP, etc), Polly, and all other subprojects.  There are a few exceptions:
+
+* Code imported from other projects (e.g. Google Test, Autoconf, etc) will
+  remain as it is.  This code isn't developed as part of the LLVM project, it
+  is used by LLVM.
+* Some subprojects are impractical or uninteresting to relicense (e.g. llvm-gcc
+  and dragonegg). These will be split off from the LLVM project (e.g. to
+  separate Github projects), allowing interested people to continue their
+  development elsewhere.
+
+To relicense LLVM, we will be seeking approval from all of the copyright holders
+of code in the repository, or potentially remove/rewrite code if we cannot.
+This is a large
+and challenging project which will take a significant amount of time to
+complete.  In the interim, **all contributions to the project will be made under
+the terms of both the new license and the legacy license scheme** (each of which
+is described below).  The exception to this is the legacy patent grant, which
+will not be required for new contributions.
+
+When all of the code in the project has been converted to the new license or
+removed, we will drop the requirement to contribute under the legacy license.
+This will achieve the goal of having
+a single standardized license for the entire codebase.
+
+If you are a prior contributor to LLVM and have not done so already, please do
+*TODO* to allow us to use your code. *Add a link to a separate page here, which
+is probably a click through web form or something like that.  Details to be
+determined later*.
+
+
+.. _open source licensing terms:
+
+New LLVM Project License Framework
+----------------------------------
+
+Contributions to LLVM are licensed under the `Apache License, Version 2.0
+<https://www.apache.org/licenses/LICENSE-2.0>`_, with two limited
+exceptions intended to ensure that LLVM is very permissively licensed.
+Collectively, the name of this license is "Apache 2.0 License with LLVM
+exceptions".  The exceptions read:
+
+::
+
+   ---- LLVM Exceptions to the Apache 2.0 License ----
+
+   As an exception, if, as a result of your compiling your source code, portions
+   of this Software are embedded into an Object form of such source code, you
+   may redistribute such embedded portions in such Object form without complying
+   with the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+   In addition, if you combine or link compiled forms of this Software with
+   software that is licensed under the GPLv2 ("Combined Software") and if a
+   court of competent jurisdiction determines that the patent provision (Section
+   3), the indemnity provision (Section 9) or other Section of the License
+   conflicts with the conditions of the GPLv2, you may retroactively and
+   prospectively choose to deem waived or otherwise exclude such Section(s) of
+   the License, but only in their entirety and only with respect to the Combined
+   Software.
+
+
+We intend to keep LLVM perpetually open source and available under a permissive
+license - this fosters the widest adoption of LLVM by
+**allowing commercial products to be derived from LLVM** with few restrictions
+and without a requirement for making any derived works also open source.  In
+particular, LLVM's license is not a "copyleft" license like the GPL.
+
+The "Apache 2.0 License with LLVM exceptions" allows you to:
+
+* freely download and use LLVM (in whole or in part) for personal, internal, or
+  commercial purposes.
+* include LLVM in packages or distributions you create.
+* combine LLVM with code licensed under every other major open source
+  license (including BSD, MIT, GPLv2, GPLv3...).
+* make changes to LLVM code without being required to contribute it back
+  to the project - contributions are appreciated though!
+
+However, it imposes these limitations on you:
+
+* You must retain the copyright notice if you redistribute LLVM: You cannot
+  strip the copyright headers off or replace them with your own.
+* Binaries that include LLVM must reproduce the copyright notice (e.g. in an
+  included README file or in an "About" box), unless the LLVM code was added as
+  a by-product of compilation.  For example, if an LLVM runtime library like
+  compiler_rt or libc++ was automatically included into your application by the
+  compiler, you do not need to attribute it.
+* You can't use our names to promote your products (LLVM derived or not) -
+  though you can make truthful statements about your use of the LLVM code,
+  without implying our sponsorship.
+* There's no warranty on LLVM at all.
+
+We want LLVM code to be widely used, and believe that this provides a model that
+is great for contributors and users of the project.  For more information about
+the Apache 2.0 License, please see the `Apache License FAQ
+<http://www.apache.org/foundation/license-faq.html>`_, maintained by the
+Apache Project.
+
+
+.. note::
+
+   The LLVM Project includes some really old subprojects (dragonegg,
+   llvm-gcc-4.0, and llvm-gcc-4.2), which are licensed under **GPL
+   licenses**.  This code is not actively maintained - it does not even
+   build successfully.  This code is cleanly separated into distinct SVN
+   repositories from the rest of LLVM, and the LICENSE.txt files specifically
+   indicate that they contain GPL code.  When LLVM transitions from SVN to Git,
+   we plan to drop these code bases from the new repository structure.
+
+
+.. _patent license:
+
+Patents
 -------
 
-We intend to keep LLVM perpetually open source and to use a liberal open source
-license. **As a contributor to the project, you agree that any contributions be
-licensed under the terms of the corresponding subproject.** All of the code in
+Section 3 of the Apache 2.0 license is a patent grant under which
+contributors of code to the project contribute the rights to use any of
+their patents that would otherwise be infringed by that code contribution
+(protecting uses of that code).  Further, the patent grant is revoked
+from anyone who files a patent lawsuit about code in LLVM - this protects the
+community by providing a "patent commons" for the code base and reducing the
+odds of patent lawsuits in general.
+
+The license specifically scopes which patents are included with code
+contributions.  To help explain this, the `Apache License FAQ
+<http://www.apache.org/foundation/license-faq.html>`_ explains this scope using
+some questions and answers, which we reproduce here for your convenience (for
+reference, the "ASF" is the Apache Software Foundation, the guidance still
+holds though)::
+
+   Q1: If I own a patent and contribute to a Work, and, at the time my
+   contribution is included in that Work, none of my patent's claims are subject
+   to Apache's Grant of Patent License, is there a way any of those claims would
+   later become subject to the Grant of Patent License solely due to subsequent
+   contributions by other parties who are not licensees of that patent.
+
+   A1: No.
+
+   Q2: If at any time after my contribution, I am able to license other patent
+   claims that would have been subject to Apache's Grant of Patent License if
+   they were licenseable by me at the time of my contribution, do those other
+   claims become subject to the Grant of Patent License?
+
+   A2: Yes.
+
+   Q3: If I own or control a licensable patent and contribute code to a specific
+   Apache product, which of my patent claims are subject to Apache's Grant of
+   Patent License?
+
+   A3:  The only patent claims that are licensed to the ASF are those you own or
+   have the right to license that read on your contribution or on the
+   combination of your contribution with the specific Apache product to which
+   you contributed as it existed at the time of your contribution. No additional
+   patent claims become licensed as a result of subsequent combinations of your
+   contribution with any other software. Note, however, that licensable patent
+   claims include those that you acquire in the future, as long as they read on
+   your original contribution as made at the original time. Once a patent claim
+   is subject to Apache's Grant of Patent License, it is licensed under the
+   terms of that Grant to the ASF and to recipients of any software distributed
+   by the ASF for any Apache software product whatsoever.
+
+.. _legacy:
+
+Legacy License Structure
+------------------------
+
+.. note::
+   The code base was previously licensed under the Terms described here.
+   We are in the middle of relicensing to a new approach (described above), but
+   until this effort is complete, the code is also still available under these
+   terms.  Once we finish the relicensing project, new versions of the code will
+   not be available under these terms.  However, nothing takes away your right
+   to use old versions under the licensing terms under which they were
+   originally released.
+
+We intend to keep LLVM perpetually open source and to use a permissive open
+source license.  The code in
 LLVM is available under the `University of Illinois/NCSA Open Source License
 <http://www.opensource.org/licenses/UoI-NCSA.php>`_, which boils down to
 this:
@@ -691,13 +918,13 @@
 * You can freely distribute LLVM.
 * You must retain the copyright notice if you redistribute LLVM.
 * Binaries derived from LLVM must reproduce the copyright notice (e.g. in an
-  included readme file).
+  included README file).
 * You can't use our names to promote your LLVM derived products.
 * There's no warranty on LLVM at all.
 
 We believe this fosters the widest adoption of LLVM because it **allows
 commercial products to be derived from LLVM** with few restrictions and without
-a requirement for making any derived works also open source (i.e.  LLVM's
+a requirement for making any derived works also open source (i.e. LLVM's
 license is not a "copyleft" license like the GPL). We suggest that you read the
 `License <http://www.opensource.org/licenses/UoI-NCSA.php>`_ if further
 clarification is needed.
@@ -715,30 +942,3 @@
 to move code from (e.g.)  libc++ to the LLVM core without concern, but that code
 cannot be moved from the LLVM core to libc++ without the copyright owner's
 permission.
-
-Note that the LLVM Project does distribute dragonegg, **which is
-GPL.** This means that anything "linked" into dragonegg must itself be compatible
-with the GPL, and must be releasable under the terms of the GPL.  This implies
-that **any code linked into dragonegg and distributed to others may be subject to
-the viral aspects of the GPL** (for example, a proprietary code generator linked
-into dragonegg must be made available under the GPL).  This is not a problem for
-code already distributed under a more liberal license (like the UIUC license),
-and GPL-containing subprojects are kept in separate SVN repositories whose
-LICENSE.txt files specifically indicate that they contain GPL code.
-
-Patents
--------
-
-To the best of our knowledge, LLVM does not infringe on any patents (we have
-actually removed code from LLVM in the past that was found to infringe).  Having
-code in LLVM that infringes on patents would violate an important goal of the
-project by making it hard or impossible to reuse the code for arbitrary purposes
-(including commercial use).
-
-When contributing code, we expect contributors to notify us of any potential for
-patent-related trouble with their changes (including from third parties).  If
-you or your employer own the rights to a patent and would like to contribute
-code to LLVM that relies on it, we require that the copyright owner sign an
-agreement that allows any other user of LLVM to freely use your patent.  Please
-contact the `LLVM Foundation Board of Directors <mailto:board@llvm.org>`_ for more
-details.
diff --git a/docs/Docker.rst b/docs/Docker.rst
index 7862c5a..5a42cbe 100644
--- a/docs/Docker.rst
+++ b/docs/Docker.rst
@@ -79,7 +79,7 @@
     ./llvm/utils/docker/build_docker_image.sh \
 	--source debian8 \
 	--docker-repository clang-debian8 --docker-tag "staging" \
-	-p clang -i install-clang -i install-clang-headers \
+	-p clang -i install-clang -i install-clang-resource-headers \
 	-- \
 	-DCMAKE_BUILD_TYPE=Release
 
@@ -95,11 +95,11 @@
     ./build_docker_image.sh \
 	--source debian8 \
 	--docker-repository clang-debian8 --docker-tag "staging" \
-	-p clang -i stage2-install-clang -i stage2-install-clang-headers \
+	-p clang -i stage2-install-clang -i stage2-install-clang-resource-headers \
 	-- \
 	-DLLVM_TARGETS_TO_BUILD=Native -DCMAKE_BUILD_TYPE=Release \
 	-DBOOTSTRAP_CMAKE_BUILD_TYPE=Release \
-	-DCLANG_ENABLE_BOOTSTRAP=ON -DCLANG_BOOTSTRAP_TARGETS="install-clang;install-clang-headers"
+	-DCLANG_ENABLE_BOOTSTRAP=ON -DCLANG_BOOTSTRAP_TARGETS="install-clang;install-clang-resource-headers"
 	
 This will produce a new image ``clang-debian8:staging`` from the latest
 upstream revision.
@@ -165,7 +165,7 @@
     ./llvm/utils/docker/build_docker_image.sh \
 	-s debian8 --d clang-debian8 -t "staging" \
 	--branch branches/google/stable \
-	-p clang -i install-clang -i install-clang-headers \
+	-p clang -i install-clang -i install-clang-resource-headers \
 	-- \
 	-DCMAKE_BUILD_TYPE=Release
 
diff --git a/docs/ExtendingLLVM.rst b/docs/ExtendingLLVM.rst
index 389dfad..53daf5c 100644
--- a/docs/ExtendingLLVM.rst
+++ b/docs/ExtendingLLVM.rst
@@ -47,11 +47,13 @@
 
 #. ``llvm/include/llvm/IR/Intrinsics*.td``:
 
-   Add an entry for your intrinsic.  Describe its memory access characteristics
-   for optimization (this controls whether it will be DCE'd, CSE'd, etc). Note
-   that any intrinsic using one of the ``llvm_any*_ty`` types for an argument or
-   return type will be deemed by ``tblgen`` as overloaded and the corresponding
-   suffix will be required on the intrinsic's name.
+   Add an entry for your intrinsic.  Describe its memory access
+   characteristics for optimization (this controls whether it will be
+   DCE'd, CSE'd, etc). If any arguments need to be immediates, these
+   must be indicated with the ImmArg property. Note that any intrinsic
+   using one of the ``llvm_any*_ty`` types for an argument or return
+   type will be deemed by ``tblgen`` as overloaded and the
+   corresponding suffix will be required on the intrinsic's name.
 
 #. ``llvm/lib/Analysis/ConstantFolding.cpp``:
 
diff --git a/docs/GettingStarted.rst b/docs/GettingStarted.rst
index b714cc6..f10bcd3 100644
--- a/docs/GettingStarted.rst
+++ b/docs/GettingStarted.rst
@@ -64,8 +64,8 @@
 
      * ``-DLLVM_ENABLE_PROJECTS='...'`` --- semicolon-separated list of the LLVM
        subprojects you'd like to additionally build. Can include any of: clang,
-       libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld, polly, or
-       debuginfo-tests.
+       clang-tools-extra, libcxx, libcxxabi, libunwind, lldb, compiler-rt, lld,
+       polly, or debuginfo-tests.
 
        For example, to build LLVM, Clang, libcxx, and libcxxabi, use
        ``-DLLVM_ENABLE_PROJECTS="clang;libcxx;libcxxabi"``.
@@ -170,7 +170,7 @@
 Package                                                     Version      Notes
 =========================================================== ============ ==========================================
 `GNU Make <http://savannah.gnu.org/projects/make>`_         3.79, 3.79.1 Makefile/build processor
-`GCC <http://gcc.gnu.org/>`_                                >=4.8.0      C/C++ compiler\ :sup:`1`
+`GCC <http://gcc.gnu.org/>`_                                >=5.1.0      C/C++ compiler\ :sup:`1`
 `python <http://www.python.org/>`_                          >=2.7        Automated test suite\ :sup:`2`
 `zlib <http://zlib.net>`_                                   >=1.2.3.4    Compression library\ :sup:`3`
 =========================================================== ============ ==========================================
@@ -220,15 +220,25 @@
 ------------------------------------------------------
 
 LLVM is very demanding of the host C++ compiler, and as such tends to expose
-bugs in the compiler. We are also planning to follow improvements and
-developments in the C++ language and library reasonably closely. As such, we
-require a modern host C++ toolchain, both compiler and standard library, in
-order to build LLVM.
+bugs in the compiler. We also attempt to follow improvements and developments in
+the C++ language and library reasonably closely. As such, we require a modern
+host C++ toolchain, both compiler and standard library, in order to build LLVM.
 
-For the most popular host toolchains we check for specific minimum versions in
-our build systems:
+LLVM is written using the subset of C++ documented in :doc:`coding
+standards<CodingStandards>`. To enforce this language version, we check the most
+popular host toolchains for specific minimum versions in our build systems:
+
+* Clang 3.5
+* Apple Clang 6.0
+* GCC 5.1
+* Visual Studio 2017
+
+The below versions currently soft-error as we transition to the new compiler
+versions listed above. The LLVM codebase is currently known to compile correctly
+with the following compilers, though this will change in the near future:
 
 * Clang 3.1
+* Apple Clang 3.1
 * GCC 4.8
 * Visual Studio 2015 (Update 3)
 
@@ -282,33 +292,36 @@
 distribution on which users have struggled with the version requirements is
 Ubuntu Precise, 12.04 LTS. For this distribution, one easy option is to install
 the `toolchain testing PPA`_ and use it to install a modern GCC. There is
-a really nice discussions of this on the `ask ubuntu stack exchange`_. However,
-not all users can use PPAs and there are many other distributions, so it may be
-necessary (or just useful, if you're here you *are* doing compiler development
-after all) to build and install GCC from source. It is also quite easy to do
-these days.
+a really nice discussions of this on the `ask ubuntu stack exchange`_ and a
+`github gist`_ with updated commands. However, not all users can use PPAs and
+there are many other distributions, so it may be necessary (or just useful, if
+you're here you *are* doing compiler development after all) to build and install
+GCC from source. It is also quite easy to do these days.
 
 .. _toolchain testing PPA:
   https://launchpad.net/~ubuntu-toolchain-r/+archive/test
 .. _ask ubuntu stack exchange:
-  http://askubuntu.com/questions/271388/how-to-install-gcc-4-8-in-ubuntu-12-04-from-the-terminal
+  https://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu/581497#58149
+.. _github gist:
+  https://gist.github.com/application2000/73fd6f4bf1be6600a2cf9f56315a2d91
 
-Easy steps for installing GCC 4.8.2:
+Easy steps for installing GCC 5.1.0:
 
 .. code-block:: console
 
-  % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2
-  % wget https://ftp.gnu.org/gnu/gcc/gcc-4.8.2/gcc-4.8.2.tar.bz2.sig
+  % gcc_version=5.1.0
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2
+  % wget https://ftp.gnu.org/gnu/gcc/gcc-${gcc_version}/gcc-${gcc_version}.tar.bz2.sig
   % wget https://ftp.gnu.org/gnu/gnu-keyring.gpg
-  % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-4.8.2.tar.bz2.sig`
+  % signature_invalid=`gpg --verify --no-default-keyring --keyring ./gnu-keyring.gpg gcc-${gcc_version}.tar.bz2.sig`
   % if [ $signature_invalid ]; then echo "Invalid signature" ; exit 1 ; fi
-  % tar -xvjf gcc-4.8.2.tar.bz2
-  % cd gcc-4.8.2
+  % tar -xvjf gcc-${gcc_version}.tar.bz2
+  % cd gcc-${gcc_version}
   % ./contrib/download_prerequisites
   % cd ..
-  % mkdir gcc-4.8.2-build
-  % cd gcc-4.8.2-build
-  % $PWD/../gcc-4.8.2/configure --prefix=$HOME/toolchains --enable-languages=c,c++
+  % mkdir gcc-${gcc_version}-build
+  % cd gcc-${gcc_version}-build
+  % $PWD/../gcc-${gcc_version}/configure --prefix=$HOME/toolchains --enable-languages=c,c++
   % make -j$(nproc)
   % make install
 
@@ -316,7 +329,7 @@
 of this information from.
 
 .. _GCC wiki entry:
-  http://gcc.gnu.org/wiki/InstallingGCC
+  https://gcc.gnu.org/wiki/InstallingGCC
 
 Once you have a GCC toolchain, configure your build of LLVM to use the new
 toolchain for your host compiler and C++ standard library. Because the new
@@ -336,7 +349,7 @@
 from the loader similar to ``libstdc++.so.6: version `GLIBCXX_3.4.20' not
 found``. This means you need to tweak the -rpath linker flag.
 
-When you build Clang, you will need to give *it* access to modern C++11
+When you build Clang, you will need to give *it* access to modern C++
 standard library in order to use it as your new host in part of a bootstrap.
 There are two easy ways to do this, either build (and install) libc++ along
 with Clang and then use it with the ``-stdlib=libc++`` compile and link flag,
@@ -415,7 +428,7 @@
 
 .. code-block:: console
 
-  % git clone https://github.com/llvm/llvm-project.git`
+  % git clone https://github.com/llvm/llvm-project.git
 
 or on Windows,
 
diff --git a/docs/GlobalISel.rst b/docs/GlobalISel.rst
index 8746685..f6a2bfc 100644
--- a/docs/GlobalISel.rst
+++ b/docs/GlobalISel.rst
@@ -318,37 +318,207 @@
 If any remain, they are expected to always be selectable, using loads and stores
 if necessary.
 
+The legality of an instruction may only depend on the instruction itself and
+must not depend on any context in which the instruction is used. However, after
+deciding that an instruction is not legal, using the context of the instruction
+to decide how to legalize the instruction is permitted. As an example, if we
+have a ``G_FOO`` instruction of the form::
+
+  %1:_(s32) = G_CONSTANT i32 1
+  %2:_(s32) = G_FOO %0:_(s32), %1:_(s32)
+
+it's impossible to say that G_FOO is legal iff %1 is a ``G_CONSTANT`` with
+value ``1``. However, the following::
+
+  %2:_(s32) = G_FOO %0:_(s32), i32 1
+
+can say that it's legal iff operand 2 is an immediate with value ``1`` because
+that information is entirely contained within the single instruction.
+
 .. _api-legalizerinfo:
 
 API: LegalizerInfo
 ^^^^^^^^^^^^^^^^^^
 
-Currently the API is broadly similar to SelectionDAG/TargetLowering, but
-extended in two ways:
+The recommended [#legalizer-legacy-footnote]_ API looks like this::
 
-* The set of available actions is wider, avoiding the currently very
-  overloaded ``Expand`` (which can cover everything from libcalls to
-  scalarization depending on the node's opcode).
+  getActionDefinitionsBuilder({G_ADD, G_SUB, G_MUL, G_AND, G_OR, G_XOR, G_SHL})
+      .legalFor({s32, s64, v2s32, v4s32, v2s64})
+      .clampScalar(0, s32, s64)
+      .widenScalarToNextPow2(0)
+      .clampNumElements(0, v2s32, v4s32)
+      .clampNumElements(0, v2s64, v2s64)
+      .moreElementsToNextPow2(0);
 
-* Since there's no separate type legalization, independently varying
-  types on an instruction can have independent actions. For example a
-  ``G_ICMP`` has 2 independent types: the result and the inputs; we need
-  to be able to say that comparing 2 s32s is OK, but the s1 result
-  must be dealt with in another way.
+and describes a set of rules by which we can either declare an instruction legal
+or decide which action to take to make it more legal.
 
-As such, the primary key when deciding what to do is the ``InstrAspect``,
-essentially a tuple consisting of ``(Opcode, TypeIdx, Type)`` and mapping to a
-suggested course of action.
+At the core of this ruleset is the ``LegalityQuery`` which describes the
+instruction. We use a description rather than the instruction to both allow other
+passes to determine legality without having to create an instruction and also to
+limit the information available to the predicates to that which is safe to rely
+on. Currently, the information available to the predicates that determine
+legality contains:
 
-An example use might be:
+* The opcode for the instruction
 
-  .. code-block:: c++
+* The type of each type index (see ``type0``, ``type1``, etc.)
 
-    // The CPU can't deal with an s1 result, do something about it.
-    setAction({G_ICMP, 0, s1}, WidenScalar);
-    // An s32 input (the second type) is fine though.
-    setAction({G_ICMP, 1, s32}, Legal);
+* The size in bytes and atomic ordering for each MachineMemOperand
 
+Rule Processing and Declaring Rules
+"""""""""""""""""""""""""""""""""""
+
+The ``getActionDefinitionsBuilder`` function generates a ruleset for the given
+opcode(s) that rules can be added to. If multiple opcodes are given, they are
+all permanently bound to the same ruleset. The rules in a ruleset are executed
+from top to bottom and will start again from the top if an instruction is
+legalized as a result of the rules. If the ruleset is exhausted without
+satisfying any rule, then it is considered unsupported.
+
+When it doesn't declare the instruction legal, each pass over the rules may
+request that one type changes to another type. Sometimes this can cause multiple
+types to change but we avoid this as much as possible as making multiple changes
+can make it difficult to avoid infinite loops where, for example, narrowing one
+type causes another to be too small and widening that type causes the first one
+to be too big.
+
+In general, it's advisable to declare instructions legal as close to the top of
+the rule as possible and to place any expensive rules as low as possible. This
+helps with performance as testing for legality happens more often than
+legalization and legalization can require multiple passes over the rules.
+
+As a concrete example, consider the rule::
+
+  getActionDefinitionsBuilder({G_ADD, G_SUB, G_MUL, G_AND, G_OR, G_XOR, G_SHL})
+      .legalFor({s32, s64, v2s32, v4s32, v2s64})
+      .clampScalar(0, s32, s64)
+      .widenScalarToNextPow2(0);
+
+and the instruction::
+
+  %2:_(s7) = G_ADD %0:_(s7), %1:_(s7)
+
+this doesn't meet the predicate for the :ref:`.legalFor() <legalfor>` as ``s7``
+is not one of the listed types so it falls through to the
+:ref:`.clampScalar() <clampscalar>`. It does meet the predicate for this rule
+as the type is smaller than the ``s32`` and this rule instructs the legalizer
+to change type 0 to ``s32``. It then restarts from the top. This time it does
+satisfy ``.legalFor()`` and the resulting output is::
+
+  %3:_(s32) = G_ANYEXT %0:_(s7)
+  %4:_(s32) = G_ANYEXT %1:_(s7)
+  %5:_(s32) = G_ADD %3:_(s32), %4:_(s32)
+  %2:_(s7) = G_TRUNC %5:_(s32)
+
+where the ``G_ADD`` is legal and the other instructions are scheduled for
+processing by the legalizer.
+
+Rule Actions
+""""""""""""
+
+There are various rule factories that append rules to a ruleset but they have a
+few actions in common:
+
+.. _legalfor:
+
+* ``legalIf()``, ``legalFor()``, etc. declare an instruction to be legal if the
+  predicate is satisfied.
+
+* ``narrowScalarIf()``, ``narrowScalarFor()``, etc. declare an instruction to be illegal
+  if the predicate is satisfied and indicates that narrowing the scalars in one
+  of the types to a specific type would make it more legal. This action supports
+  both scalars and vectors.
+
+* ``widenScalarIf()``, ``widenScalarFor()``, etc. declare an instruction to be illegal
+  if the predicate is satisfied and indicates that widening the scalars in one
+  of the types to a specific type would make it more legal. This action supports
+  both scalars and vectors.
+
+* ``fewerElementsIf()``, ``fewerElementsFor()``, etc. declare an instruction to be
+  illegal if the predicate is satisfied and indicates reducing the number of
+  vector elements in one of the types to a specific type would make it more
+  legal. This action supports vectors.
+
+* ``moreElementsIf()``, ``moreElementsFor()``, etc. declare an instruction to be illegal
+  if the predicate is satisfied and indicates increasing the number of vector
+  elements in one of the types to a specific type would make it more legal.
+  This action supports vectors.
+
+* ``lowerIf()``, ``lowerFor()``, etc. declare an instruction to be illegal if the
+  predicate is satisfied and indicates that replacing it with equivalent
+  instruction(s) would make it more legal. Support for this action differs for
+  each opcode.
+
+* ``libcallIf()``, ``libcallFor()``, etc. declare an instruction to be illegal if the
+  predicate is satisfied and indicates that replacing it with a libcall would
+  make it more legal. Support for this action differs for
+  each opcode.
+
+* ``customIf()``, ``customFor()``, etc. declare an instruction to be illegal if the
+  predicate is satisfied and indicates that the backend developer will supply
+  a means of making it more legal.
+
+* ``unsupportedIf()``, ``unsupportedFor()``, etc. declare an instruction to be illegal
+  if the predicate is satisfied and indicates that there is no way to make it
+  legal and the compiler should fail.
+
+* ``fallback()`` falls back on an older API and should only be used while porting
+  existing code from that API.
+
+Rule Predicates
+"""""""""""""""
+
+The rule factories also have predicates in common:
+
+* ``legal()``, ``lower()``, etc. are always satisfied.
+
+* ``legalIf()``, ``narrowScalarIf()``, etc. are satisfied if the user-supplied
+  ``LegalityPredicate`` function returns true. This predicate has access to the
+  information in the ``LegalityQuery`` to make its decision.
+  User-supplied predicates can also be combined using ``all(P0, P1, ...)``.
+
+* ``legalFor()``, ``narrowScalarFor()``, etc. are satisfied if the type matches one in
+  a given set of types. For example ``.legalFor({s16, s32})`` declares the
+  instruction legal if type 0 is either s16 or s32. Additional versions for two
+  and three type indices are generally available. For these, all the type
+  indices considered together must match all the types in one of the tuples. So
+  ``.legalFor({{s16, s32}, {s32, s64}})`` will only accept ``{s16, s32}``, or
+  ``{s32, s64}`` but will not accept ``{s16, s64}``.
+
+* ``legalForTypesWithMemSize()``, ``narrowScalarForTypesWithMemSize()``, etc. are
+  similar to ``legalFor()``, ``narrowScalarFor()``, etc. but additionally require a
+  MachineMemOperand to have a given size in each tuple.
+
+* ``legalForCartesianProduct()``, ``narrowScalarForCartesianProduct()``, etc. are
+  satisfied if each type index matches one element in each of the independent
+  sets. So ``.legalForCartesianProduct({s16, s32}, {s32, s64})`` will accept
+  ``{s16, s32}``, ``{s16, s64}``, ``{s32, s32}``, and ``{s32, s64}``.
+
+Composite Rules
+"""""""""""""""
+
+There are some composite rules for common situations built out of the above facilities:
+
+* ``widenScalarToNextPow2()`` is like ``widenScalarIf()`` but is satisfied iff the type
+  size in bits is not a power of 2 and selects a target type that is the next
+  largest power of 2. 
+
+.. _clampscalar:
+
+* ``minScalar()`` is like ``widenScalarIf()`` but is satisfied iff the type
+  size in bits is smaller than the given minimum and selects the minimum as the
+  target type. Similarly, there is also a ``maxScalar()`` for the maximum and a
+  ``clampScalar()`` to do both at once. 
+
+* ``minScalarSameAs()`` is like ``minScalar()`` but the minimum is taken from another
+  type index.
+
+* ``moreElementsToNextMultiple()`` is like ``moreElementsToNextPow2()`` but is based on
+  multiples of X rather than powers of 2.
+
+Other Information
+"""""""""""""""""
 
 ``TODO``:
 An alternative worth investigating is to generalize the API to represent
@@ -361,41 +531,11 @@
 Expanding that to describe legalization actions is a much larger but
 potentially useful project.
 
-.. _milegalizer-non-power-of-2:
+.. rubric:: Footnotes
 
-Non-power of 2 types
-^^^^^^^^^^^^^^^^^^^^
-
-``TODO``:
-Types which have a size that isn't a power of 2 aren't currently supported.
-The setAction API will probably require changes to support them.
-Even notionally explicitly specified operations only make suggestions
-like "Widen" or "Narrow". The eventual type is still unspecified and a
-search is performed by repeated doubling/halving of the type's
-size.
-This is incorrect for types that aren't a power of 2.  It's reasonable to
-expect we could construct an efficient set of side-tables for more general
-lookups though, encoding a map from the integers (i.e. the size of the current
-type) to types (the legal size).
-
-.. _milegalizer-vector:
-
-Vector types
-^^^^^^^^^^^^
-
-Vectors first get their element type legalized: ``<A x sB>`` becomes
-``<A x sC>`` such that at least one operation is legal with ``sC``.
-
-This is currently specified by the function ``setScalarInVectorAction``, called
-for example as:
-
-    setScalarInVectorAction(G_ICMP, s1, WidenScalar);
-
-Next the number of elements is chosen so that the entire operation is
-legal. This aspect is not controllable at the moment, but probably
-should be (you could imagine disagreements on whether a ``<2 x s8>``
-operation should be scalarized or extended to ``<8 x s8>``).
-
+.. [#legalizer-legacy-footnote] An API is broadly similar to
+   SelectionDAG/TargetLowering is available but is not recommended as a more
+   powerful API is available.
 
 .. _regbankselect:
 
@@ -544,7 +684,7 @@
 Custom SDNodes should be mapped to Target Pseudos using ``GINodeEquiv``. This
 will cause the instruction selector to import them but you will also need to
 ensure the target pseudo is introduced to the MIR before the instruction
-selector. Any preceeding pass is suitable but the legalizer will be a
+selector. Any preceding pass is suitable but the legalizer will be a
 particularly common choice.
 
 ComplexPatterns
diff --git a/docs/HowToSubmitABug.rst b/docs/HowToSubmitABug.rst
index 7881a6e..d276ee8 100644
--- a/docs/HowToSubmitABug.rst
+++ b/docs/HowToSubmitABug.rst
@@ -84,8 +84,8 @@
 ------------------------------
 
 If you find that a bug crashes in the optimizer, compile your test-case to a
-``.bc`` file by passing "``-emit-llvm -O0 -c -o foo.bc``".
-Then run:
+``.bc`` file by passing "``-emit-llvm -O1 -Xclang -disable-llvm-passes -c -o
+foo.bc``".  Then run:
 
 .. code-block:: bash
 
diff --git a/docs/LLVMBuild.txt b/docs/LLVMBuild.txt
index d5aea86..00d82f6 100644
--- a/docs/LLVMBuild.txt
+++ b/docs/LLVMBuild.txt
@@ -1,9 +1,8 @@
 ;===- ./docs/LLVMBuild.txt -------------------------------------*- Conf -*--===;
 ;
-;                     The LLVM Compiler Infrastructure
-;
-; This file is distributed under the University of Illinois Open Source
-; License. See LICENSE.TXT for details.
+; Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+; See https://llvm.org/LICENSE.txt for license information.
+; SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 ;
 ;===------------------------------------------------------------------------===;
 ;
diff --git a/docs/LangRef.rst b/docs/LangRef.rst
index 496a0f7..66490b8 100644
--- a/docs/LangRef.rst
+++ b/docs/LangRef.rst
@@ -741,11 +741,13 @@
 Flow Graph) for the function. Each basic block may optionally start with a label
 (giving the basic block a symbol table entry), contains a list of instructions,
 and ends with a :ref:`terminator <terminators>` instruction (such as a branch or
-function return). If an explicit label is not provided, a block is assigned an
-implicit numbered label, using the next value from the same counter as used for
-unnamed temporaries (:ref:`see above<identifiers>`). For example, if a function
-entry block does not have an explicit label, it will be assigned label "%0",
-then the first unnamed temporary in that block will be "%1", etc.
+function return). If an explicit label name is not provided, a block is assigned
+an implicit numbered label, using the next value from the same counter as used
+for unnamed temporaries (:ref:`see above<identifiers>`). For example, if a
+function entry block does not have an explicit label, it will be assigned label
+"%0", then the first unnamed temporary in that block will be "%1", etc. If a
+numeric label is explicitly specified, it must match the numeric label that
+would be used implicitly.
 
 The first basic block in a function is special in two ways: it is
 immediately executed on entrance to the function, and it is not allowed
@@ -1071,10 +1073,11 @@
 
 ``align <n>``
     This indicates that the pointer value may be assumed by the optimizer to
-    have the specified alignment.
+    have the specified alignment.  If the pointer value does not have the
+    specified alignment, behavior is undefined.
 
     Note that this attribute has additional semantics when combined with the
-    ``byval`` attribute.
+    ``byval`` attribute, which are documented there.
 
 .. _noalias:
 
@@ -1177,6 +1180,13 @@
     does not alias any other memory visible within a function and that a
     ``swifterror`` alloca passed as an argument does not escape.
 
+``immarg``
+    This indicates the parameter is required to be an immediate
+    value. This must be a trivial immediate integer or floating-point
+    constant. Undef or constant expressions are not valid. This is
+    only valid on intrinsic declarations and cannot be applied to a
+    call site or arbitrary function.
+
 .. _gc:
 
 Garbage Collector Strategy Names
@@ -2003,6 +2013,14 @@
     targets.
 ``a:<abi>:<pref>``
     This specifies the alignment for an object of aggregate type.
+``F<type><abi>``
+    This specifies the alignment for function pointers.
+    The options for ``<type>`` are:
+
+    * ``i``: The alignment of function pointers is independent of the alignment
+      of functions, and is a multiple of ``<abi>``.
+    * ``n``: The alignment of function pointers is a multiple of the explicit
+      alignment specified on the function, and is a multiple of ``<abi>``.
 ``m:<mangling>``
     If present, specifies that llvm names are mangled in the output. Symbols
     prefixed with the mangling escape character ``\01`` are passed through
@@ -2181,6 +2199,24 @@
 operations relative to non-volatile operations. This is not Java's
 "volatile" and has no cross-thread synchronization behavior.
 
+A volatile load or store may have additional target-specific semantics.
+Any volatile operation can have side effects, and any volatile operation
+can read and/or modify state which is not accessible via a regular load
+or store in this module. Volatile operations may use addresses which do
+not point to memory (like MMIO registers). This means the compiler may
+not use a volatile operation to prove a non-volatile access to that
+address has defined behavior.
+
+The allowed side-effects for volatile accesses are limited.  If a
+non-volatile store to a given address would be legal, a volatile
+operation may modify the memory at that address. A volatile operation
+may not modify any other memory accessible by the module being compiled.
+A volatile operation may not call any code in the current module.
+
+The compiler may assume execution will continue after a volatile operation,
+so operations which modify memory or may have undefined behavior can be
+hoisted past a volatile operation.
+
 IR-level volatile loads and stores cannot safely be optimized into
 llvm.memcpy or llvm.memmove intrinsics even when those intrinsics are
 flagged volatile. Likewise, the backend should never split or merge
@@ -3275,14 +3311,14 @@
 Taking the address of the entry block is illegal.
 
 This value only has defined behavior when used as an operand to the
-':ref:`indirectbr <i_indirectbr>`' instruction, or for comparisons
-against null. Pointer equality tests between labels addresses results in
-undefined behavior --- though, again, comparison against null is ok, and
-no label is equal to the null pointer. This may be passed around as an
+':ref:`indirectbr <i_indirectbr>`' or ':ref:`callbr <i_callbr>`'instruction, or
+for comparisons against null. Pointer equality tests between labels addresses
+results in undefined behavior --- though, again, comparison against null is ok,
+and no label is equal to the null pointer. This may be passed around as an
 opaque pointer sized value as long as the bits are not inspected. This
 allows ``ptrtoint`` and arithmetic to be performed on these values so
-long as the original value is reconstituted before the ``indirectbr``
-instruction.
+long as the original value is reconstituted before the ``indirectbr`` or
+``callbr`` instruction.
 
 Finally, some targets may provide defined semantics when using the value
 as the operand to an inline assembly, but that is target specific.
@@ -4493,13 +4529,36 @@
 
 .. code-block:: text
 
-    !0 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !1,
-                           file: !2, line: 7, type: !3, isLocal: true,
-                           isDefinition: false, variable: i32* @foo,
-                           declaration: !4)
+    @foo = global i32, !dbg !0
+    !0 = !DIGlobalVariableExpression(var: !1, expr: !DIExpression())
+    !1 = !DIGlobalVariable(name: "foo", linkageName: "foo", scope: !2,
+                           file: !3, line: 7, type: !4, isLocal: true,
+                           isDefinition: false, declaration: !5)
 
-All global variables should be referenced by the `globals:` field of a
-:ref:`compile unit <DICompileUnit>`.
+
+DIGlobalVariableExpression
+""""""""""""""""""""""""""
+
+``DIGlobalVariableExpression`` nodes tie a :ref:`DIGlobalVariable` together
+with a :ref:`DIExpression`.
+
+.. code-block:: text
+
+    @lower = global i32, !dbg !0
+    @upper = global i32, !dbg !1
+    !0 = !DIGlobalVariableExpression(
+             var: !2,
+             expr: !DIExpression(DW_OP_LLVM_fragment, 0, 32)
+             )
+    !1 = !DIGlobalVariableExpression(
+             var: !2,
+             expr: !DIExpression(DW_OP_LLVM_fragment, 32, 32)
+             )
+    !2 = !DIGlobalVariable(name: "split64", linkageName: "split64", scope: !3,
+                           file: !4, line: 8, type: !5, declaration: !6)
+
+All global variable expressions should be referenced by the `globals:` field of
+a :ref:`compile unit <DICompileUnit>`.
 
 .. _DISubprogram:
 
@@ -4599,6 +4658,8 @@
                           type: !3)
     !2 = !DILocalVariable(name: "y", scope: !5, file: !2, line: 7, type: !3)
 
+.. _DIExpression:
+
 DIExpression
 """"""""""""
 
@@ -4623,6 +4684,10 @@
   here, respectively) of the variable fragment from the working expression. Note
   that contrary to DW_OP_bit_piece, the offset is describing the location
   within the described source variable.
+- ``DW_OP_LLVM_convert, 16, DW_ATE_signed`` specifies a bit size and encoding
+  (``16`` and ``DW_ATE_signed`` here, respectively) to which the top of the
+  expression stack is to be converted. Maps into a ``DW_OP_convert`` operation
+  that references a base type constructed from the supplied values.
 - ``DW_OP_swap`` swaps top two stack entries.
 - ``DW_OP_xderef`` provides extended dereference mechanism. The entry at the top
   of the stack is treated as an address. The second stack entry is treated as an
@@ -5066,6 +5131,80 @@
     ...
     !0 = !{i64 (i64, i64)* @add, i64 (i64, i64)* @sub}
 
+'``callback``' Metadata
+^^^^^^^^^^^^^^^^^^^^^^^
+
+``callback`` metadata may be attached to a function declaration, or definition.
+(Call sites are excluded only due to the lack of a use case.) For ease of
+exposition, we'll refer to the function annotated w/ metadata as a broker
+function. The metadata describes how the arguments of a call to the broker are
+in turn passed to the callback function specified by the metadata. Thus, the
+``callback`` metadata provides a partial description of a call site inside the
+broker function with regards to the arguments of a call to the broker. The only
+semantic restriction on the broker function itself is that it is not allowed to
+inspect or modify arguments referenced in the ``callback`` metadata as
+pass-through to the callback function.
+
+The broker is not required to actually invoke the callback function at runtime.
+However, the assumptions about not inspecting or modifying arguments that would
+be passed to the specified callback function still hold, even if the callback
+function is not dynamically invoked. The broker is allowed to invoke the
+callback function more than once per invocation of the broker. The broker is
+also allowed to invoke (directly or indirectly) the function passed as a
+callback through another use. Finally, the broker is also allowed to relay the
+callback callee invocation to a different thread.
+
+The metadata is structured as follows: At the outer level, ``callback``
+metadata is a list of ``callback`` encodings. Each encoding starts with a
+constant ``i64`` which describes the argument position of the callback function
+in the call to the broker. The following elements, except the last, describe
+what arguments are passed to the callback function. Each element is again an
+``i64`` constant identifying the argument of the broker that is passed through,
+or ``i64 -1`` to indicate an unknown or inspected argument. The order in which
+they are listed has to be the same in which they are passed to the callback
+callee. The last element of the encoding is a boolean which specifies how
+variadic arguments of the broker are handled. If it is true, all variadic
+arguments of the broker are passed through to the callback function *after* the
+arguments encoded explicitly before.
+
+In the code below, the ``pthread_create`` function is marked as a broker
+through the ``!callback !1`` metadata. In the example, there is only one
+callback encoding, namely ``!2``, associated with the broker. This encoding
+identifies the callback function as the second argument of the broker (``i64
+2``) and the sole argument of the callback function as the third one of the
+broker function (``i64 3``).
+
+.. FIXME why does the llvm-sphinx-docs builder give a highlighting
+   error if the below is set to highlight as 'llvm', despite that we
+   have misc.highlighting_failure set?
+
+.. code-block:: text
+
+    declare !callback !1 dso_local i32 @pthread_create(i64*, %union.pthread_attr_t*, i8* (i8*)*, i8*)
+
+    ...
+    !2 = !{i64 2, i64 3, i1 false}
+    !1 = !{!2}
+
+Another example is shown below. The callback callee is the second argument of
+the ``__kmpc_fork_call`` function (``i64 2``). The callee is given two unknown
+values (each identified by a ``i64 -1``) and afterwards all
+variadic arguments that are passed to the ``__kmpc_fork_call`` call (due to the
+final ``i1 true``).
+
+.. FIXME why does the llvm-sphinx-docs builder give a highlighting
+   error if the below is set to highlight as 'llvm', despite that we
+   have misc.highlighting_failure set?
+
+.. code-block:: text
+
+    declare !callback !0 dso_local void @__kmpc_fork_call(%struct.ident_t*, i32, void (i32*, i32*, ...)*, ...)
+
+    ...
+    !1 = !{i64 2, i64 -1, i64 -1, i1 true}
+    !0 = !{!1}
+
+
 '``unpredictable``' Metadata
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -6396,6 +6535,7 @@
 The terminator instructions are: ':ref:`ret <i_ret>`',
 ':ref:`br <i_br>`', ':ref:`switch <i_switch>`',
 ':ref:`indirectbr <i_indirectbr>`', ':ref:`invoke <i_invoke>`',
+':ref:`callbr <i_callbr>`'
 ':ref:`resume <i_resume>`', ':ref:`catchswitch <i_catchswitch>`',
 ':ref:`catchret <i_catchret>`',
 ':ref:`cleanupret <i_cleanupret>`',
@@ -6431,7 +6571,7 @@
 return value. The type of the return value must be a ':ref:`first
 class <t_firstclass>`' type.
 
-A function is not :ref:`well formed <wellformed>` if it it has a non-void
+A function is not :ref:`well formed <wellformed>` if it has a non-void
 return type and contains a '``ret``' instruction with no return value or
 a return value with a type that does not match its type, or if it has a
 void return type and contains a '``ret``' instruction with a return
@@ -6720,6 +6860,85 @@
       %retval = invoke coldcc i32 %Testfnptr(i32 15) to label %Continue
                   unwind label %TestCleanup              ; i32:retval set
 
+.. _i_callbr:
+
+'``callbr``' Instruction
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax:
+"""""""
+
+::
+
+      <result> = callbr [cconv] [ret attrs] [addrspace(<num>)] [<ty>|<fnty> <fnptrval>(<function args>) [fn attrs]
+                    [operand bundles] to label <normal label> or jump [other labels]
+
+Overview:
+"""""""""
+
+The '``callbr``' instruction causes control to transfer to a specified
+function, with the possibility of control flow transfer to either the
+'``normal``' label or one of the '``other``' labels.
+
+This instruction should only be used to implement the "goto" feature of gcc
+style inline assembly. Any other usage is an error in the IR verifier.
+
+Arguments:
+""""""""""
+
+This instruction requires several arguments:
+
+#. The optional "cconv" marker indicates which :ref:`calling
+   convention <callingconv>` the call should use. If none is
+   specified, the call defaults to using C calling conventions.
+#. The optional :ref:`Parameter Attributes <paramattrs>` list for return
+   values. Only '``zeroext``', '``signext``', and '``inreg``' attributes
+   are valid here.
+#. The optional addrspace attribute can be used to indicate the address space
+   of the called function. If it is not specified, the program address space
+   from the :ref:`datalayout string<langref_datalayout>` will be used.
+#. '``ty``': the type of the call instruction itself which is also the
+   type of the return value. Functions that return no value are marked
+   ``void``.
+#. '``fnty``': shall be the signature of the function being called. The
+   argument types must match the types implied by this signature. This
+   type can be omitted if the function is not varargs.
+#. '``fnptrval``': An LLVM value containing a pointer to a function to
+   be called. In most cases, this is a direct function call, but
+   indirect ``callbr``'s are just as possible, calling an arbitrary pointer
+   to function value.
+#. '``function args``': argument list whose types match the function
+   signature argument types and parameter attributes. All arguments must
+   be of :ref:`first class <t_firstclass>` type. If the function signature
+   indicates the function accepts a variable number of arguments, the
+   extra arguments can be specified.
+#. '``normal label``': the label reached when the called function
+   executes a '``ret``' instruction.
+#. '``other labels``': the labels reached when a callee transfers control
+   to a location other than the normal '``normal label``'
+#. The optional :ref:`function attributes <fnattrs>` list.
+#. The optional :ref:`operand bundles <opbundles>` list.
+
+Semantics:
+""""""""""
+
+This instruction is designed to operate as a standard '``call``'
+instruction in most regards. The primary difference is that it
+establishes an association with additional labels to define where control
+flow goes after the call.
+
+The only use of this today is to implement the "goto" feature of gcc inline
+assembly where additional labels can be provided as locations for the inline
+assembly to jump to.
+
+Example:
+""""""""
+
+.. code-block:: text
+
+      callbr void asm "", "r,x"(i32 %x, i8 *blockaddress(@foo, %fail))
+                  to label %normal or jump [label %fail]
+
 .. _i_resume:
 
 '``resume``' Instruction
@@ -8167,15 +8386,16 @@
 Semantics:
 """"""""""
 
-Memory is allocated; a pointer is returned. The operation is undefined
-if there is insufficient stack space for the allocation. '``alloca``'d
-memory is automatically released when the function returns. The
-'``alloca``' instruction is commonly used to represent automatic
-variables that must have an address available. When the function returns
-(either with the ``ret`` or ``resume`` instructions), the memory is
-reclaimed. Allocating zero bytes is legal, but the returned pointer may not
-be unique. The order in which memory is allocated (ie., which way the stack
-grows) is not specified.
+Memory is allocated; a pointer is returned. The allocated memory is
+uninitialized, and loading from uninitialized memory produces an undefined
+value. The operation itself is undefined if there is insufficient stack
+space for the allocation.'``alloca``'d memory is automatically released
+when the function returns. The '``alloca``' instruction is commonly used
+to represent automatic variables that must have an address available. When
+the function returns (either with the ``ret`` or ``resume`` instructions),
+the memory is reclaimed. Allocating zero bytes is legal, but the returned
+pointer may not be unique. The order in which memory is allocated (ie.,
+which way the stack grows) is not specified.
 
 Example:
 """"""""
@@ -8583,14 +8803,18 @@
 -  min
 -  umax
 -  umin
+-  fadd
+-  fsub
 
-The type of '<value>' must be an integer type whose bit width is a power
-of two greater than or equal to eight and less than or equal to a
-target-specific size limit. The type of the '``<pointer>``' operand must
-be a pointer to that type. If the ``atomicrmw`` is marked as
-``volatile``, then the optimizer is not allowed to modify the number or
-order of execution of this ``atomicrmw`` with other :ref:`volatile
-operations <volatile>`.
+For most of these operations, the type of '<value>' must be an integer
+type whose bit width is a power of two greater than or equal to eight
+and less than or equal to a target-specific size limit. For xchg, this
+may also be a floating point type with the same size constraints as
+integers.  For fadd/fsub, this must be a floating point type.  The
+type of the '``<pointer>``' operand must be a pointer to that type. If
+the ``atomicrmw`` is marked as ``volatile``, then the optimizer is not
+allowed to modify the number or order of execution of this
+``atomicrmw`` with other :ref:`volatile operations <volatile>`.
 
 A ``atomicrmw`` instruction can also take an optional
 ":ref:`syncscope <syncscope>`" argument.
@@ -8616,6 +8840,8 @@
    comparison)
 -  umin: ``*ptr = *ptr < val ? *ptr : val`` (using an unsigned
    comparison)
+- fadd: ``*ptr = *ptr + val`` (using floating point arithmetic)
+- fsub: ``*ptr = *ptr - val`` (using floating point arithmetic)
 
 Example:
 """"""""
@@ -11121,8 +11347,11 @@
 The '``llvm.memcpy.*``' intrinsics copy a block of memory from the
 source location to the destination location, which are not allowed to
 overlap. It copies "len" bytes of memory over. If the argument is known
-to be aligned to some boundary, this can be specified as the fourth
-argument, otherwise it should be set to 0 or 1 (both meaning no alignment).
+to be aligned to some boundary, this can be specified as an attribute on
+the argument.
+
+If "len" is 0, the pointers may be NULL or dangling. However, they must still
+be appropriately aligned.
 
 .. _int_memmove:
 
@@ -11176,8 +11405,11 @@
 The '``llvm.memmove.*``' intrinsics copy a block of memory from the
 source location to the destination location, which may overlap. It
 copies "len" bytes of memory over. If the argument is known to be
-aligned to some boundary, this can be specified as the fourth argument,
-otherwise it should be set to 0 or 1 (both meaning no alignment).
+aligned to some boundary, this can be specified as an attribute on
+the argument.
+
+If "len" is 0, the pointers may be NULL or dangling. However, they must still
+be appropriately aligned.
 
 .. _int_memset:
 
@@ -11227,7 +11459,12 @@
 """"""""""
 
 The '``llvm.memset.*``' intrinsics fill "len" bytes of memory starting
-at the destination location.
+at the destination location. If the argument is known to be
+aligned to some boundary, this can be specified as an attribute on
+the argument.
+
+If "len" is 0, the pointers may be NULL or dangling. However, they must still
+be appropriately aligned.
 
 '``llvm.sqrt.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -12127,19 +12364,22 @@
       declare i16 @llvm.bitreverse.i16(i16 <id>)
       declare i32 @llvm.bitreverse.i32(i32 <id>)
       declare i64 @llvm.bitreverse.i64(i64 <id>)
+      declare <4 x i32> @llvm.bitreverse.v4i32(<4 x i32> <id>)
 
 Overview:
 """""""""
 
 The '``llvm.bitreverse``' family of intrinsics is used to reverse the
-bitpattern of an integer value; for example ``0b10110110`` becomes
-``0b01101101``.
+bitpattern of an integer value or vector of integer values; for example
+``0b10110110`` becomes ``0b01101101``.
 
 Semantics:
 """"""""""
 
 The ``llvm.bitreverse.iN`` intrinsic returns an iN value that has bit
-``M`` in the input moved to bit ``N-M`` in the output.
+``M`` in the input moved to bit ``N-M`` in the output. The vector
+intrinsics, such as ``llvm.bitreverse.v4i32``, operate on a per-element
+basis and the element order is not affected.
 
 '``llvm.bswap.*``' Intrinsics
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -12155,14 +12395,14 @@
       declare i16 @llvm.bswap.i16(i16 <id>)
       declare i32 @llvm.bswap.i32(i32 <id>)
       declare i64 @llvm.bswap.i64(i64 <id>)
+      declare <4 x i32> @llvm.bswap.v4i32(<4 x i32> <id>)
 
 Overview:
 """""""""
 
-The '``llvm.bswap``' family of intrinsics is used to byte swap integer
-values with an even number of bytes (positive multiple of 16 bits).
-These are useful for performing operations on data that is not in the
-target's native byte order.
+The '``llvm.bswap``' family of intrinsics is used to byte swap an integer
+value or vector of integer values with an even number of bytes (positive
+multiple of 16 bits).
 
 Semantics:
 """"""""""
@@ -12174,7 +12414,8 @@
 returned i32 will have its bytes in 3, 2, 1, 0 order. The
 ``llvm.bswap.i48``, ``llvm.bswap.i64`` and other intrinsics extend this
 concept to additional even-byte lengths (6 bytes, 8 bytes and more,
-respectively).
+respectively). The vector intrinsics, such as ``llvm.bswap.v4i32``,
+operate on a per-element basis and the element order is not affected.
 
 '``llvm.ctpop.*``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -12433,13 +12674,14 @@
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.sadd.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 
 ::
 
       declare {i16, i1} @llvm.sadd.with.overflow.i16(i16 %a, i16 %b)
       declare {i32, i1} @llvm.sadd.with.overflow.i32(i32 %a, i32 %b)
       declare {i64, i1} @llvm.sadd.with.overflow.i64(i64 %a, i64 %b)
+      declare {<4 x i32>, <4 x i1>} @llvm.sadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 
 Overview:
 """""""""
@@ -12483,13 +12725,14 @@
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.uadd.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 
 ::
 
       declare {i16, i1} @llvm.uadd.with.overflow.i16(i16 %a, i16 %b)
       declare {i32, i1} @llvm.uadd.with.overflow.i32(i32 %a, i32 %b)
       declare {i64, i1} @llvm.uadd.with.overflow.i64(i64 %a, i64 %b)
+      declare {<4 x i32>, <4 x i1>} @llvm.uadd.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 
 Overview:
 """""""""
@@ -12532,13 +12775,14 @@
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.ssub.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 
 ::
 
       declare {i16, i1} @llvm.ssub.with.overflow.i16(i16 %a, i16 %b)
       declare {i32, i1} @llvm.ssub.with.overflow.i32(i32 %a, i32 %b)
       declare {i64, i1} @llvm.ssub.with.overflow.i64(i64 %a, i64 %b)
+      declare {<4 x i32>, <4 x i1>} @llvm.ssub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 
 Overview:
 """""""""
@@ -12582,13 +12826,14 @@
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.usub.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 
 ::
 
       declare {i16, i1} @llvm.usub.with.overflow.i16(i16 %a, i16 %b)
       declare {i32, i1} @llvm.usub.with.overflow.i32(i32 %a, i32 %b)
       declare {i64, i1} @llvm.usub.with.overflow.i64(i64 %a, i64 %b)
+      declare {<4 x i32>, <4 x i1>} @llvm.usub.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 
 Overview:
 """""""""
@@ -12632,13 +12877,14 @@
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.smul.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 
 ::
 
       declare {i16, i1} @llvm.smul.with.overflow.i16(i16 %a, i16 %b)
       declare {i32, i1} @llvm.smul.with.overflow.i32(i32 %a, i32 %b)
       declare {i64, i1} @llvm.smul.with.overflow.i64(i64 %a, i64 %b)
+      declare {<4 x i32>, <4 x i1>} @llvm.smul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 
 Overview:
 """""""""
@@ -12682,13 +12928,14 @@
 """""""
 
 This is an overloaded intrinsic. You can use ``llvm.umul.with.overflow``
-on any integer bit width.
+on any integer bit width or vectors of integers.
 
 ::
 
       declare {i16, i1} @llvm.umul.with.overflow.i16(i16 %a, i16 %b)
       declare {i32, i1} @llvm.umul.with.overflow.i32(i32 %a, i32 %b)
       declare {i64, i1} @llvm.umul.with.overflow.i64(i64 %a, i64 %b)
+      declare {<4 x i32>, <4 x i1>} @llvm.umul.with.overflow.v4i32(<4 x i32> %a, <4 x i32> %b)
 
 Overview:
 """""""""
@@ -12962,7 +13209,8 @@
 """"""""""
 
 The arguments (%a and %b) and the result may be of integer types of any bit
-width, but they must have the same bit width. ``%a`` and ``%b`` are the two
+width, but they must have the same bit width. The arguments may also work with
+int vectors of the same length and int size. ``%a`` and ``%b`` are the two
 values that will undergo signed fixed point multiplication. The argument
 ``%scale`` represents the scale of both operands, and must be a constant
 integer.
@@ -12978,7 +13226,7 @@
 value is rounded up or down to the closest representable value. The rounding
 direction is unspecified.
 
-It is undefined behavior if the source value does not fit within the range of
+It is undefined behavior if the result value does not fit within the range of
 the fixed point type.
 
 
@@ -12995,6 +13243,65 @@
       %res = call i4 @llvm.smul.fix.i4(i4 3, i4 -3, i32 1)  ; %res = -5 (or -4) (1.5 x -1.5 = -2.25)
 
 
+'``llvm.umul.fix.*``' Intrinsics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Syntax
+"""""""
+
+This is an overloaded intrinsic. You can use ``llvm.umul.fix``
+on any integer bit width or vectors of integers.
+
+::
+
+      declare i16 @llvm.umul.fix.i16(i16 %a, i16 %b, i32 %scale)
+      declare i32 @llvm.umul.fix.i32(i32 %a, i32 %b, i32 %scale)
+      declare i64 @llvm.umul.fix.i64(i64 %a, i64 %b, i32 %scale)
+      declare <4 x i32> @llvm.umul.fix.v4i32(<4 x i32> %a, <4 x i32> %b, i32 %scale)
+
+Overview
+"""""""""
+
+The '``llvm.umul.fix``' family of intrinsic functions perform unsigned
+fixed point multiplication on 2 arguments of the same scale.
+
+Arguments
+""""""""""
+
+The arguments (%a and %b) and the result may be of integer types of any bit
+width, but they must have the same bit width. The arguments may also work with
+int vectors of the same length and int size. ``%a`` and ``%b`` are the two
+values that will undergo unsigned fixed point multiplication. The argument
+``%scale`` represents the scale of both operands, and must be a constant
+integer.
+
+Semantics:
+""""""""""
+
+This operation performs unsigned fixed point multiplication on the 2 arguments of a
+specified scale. The result will also be returned in the same scale specified
+in the third argument.
+
+If the result value cannot be precisely represented in the given scale, the
+value is rounded up or down to the closest representable value. The rounding
+direction is unspecified.
+
+It is undefined behavior if the result value does not fit within the range of
+the fixed point type.
+
+
+Examples
+"""""""""
+
+.. code-block:: llvm
+
+      %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 0)  ; %res = 6 (2 x 3 = 6)
+      %res = call i4 @llvm.umul.fix.i4(i4 3, i4 2, i32 1)  ; %res = 3 (1.5 x 1 = 1.5)
+
+      ; The result in the following could be rounded down to 3.5 or up to 4
+      %res = call i4 @llvm.umul.fix.i4(i4 15, i4 1, i32 1)  ; %res = 7 (or 8) (7.5 x 0.5 = 3.75)
+
+
 Specialised Arithmetic Intrinsics
 ---------------------------------
 
@@ -15458,40 +15765,40 @@
 
 ::
 
-      declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>, i1 <nullunknown>)
-      declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>, i1 <nullunknown>)
+      declare i32 @llvm.objectsize.i32(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>)
+      declare i64 @llvm.objectsize.i64(i8* <object>, i1 <min>, i1 <nullunknown>, i1 <dynamic>)
 
 Overview:
 """""""""
 
-The ``llvm.objectsize`` intrinsic is designed to provide information to
-the optimizers to determine at compile time whether a) an operation
-(like memcpy) will overflow a buffer that corresponds to an object, or
-b) that a runtime check for overflow isn't necessary. An object in this
-context means an allocation of a specific class, structure, array, or
-other object.
+The ``llvm.objectsize`` intrinsic is designed to provide information to the
+optimizer to determine whether a) an operation (like memcpy) will overflow a
+buffer that corresponds to an object, or b) that a runtime check for overflow
+isn't necessary. An object in this context means an allocation of a specific
+class, structure, array, or other object.
 
 Arguments:
 """"""""""
 
-The ``llvm.objectsize`` intrinsic takes three arguments. The first argument is
-a pointer to or into the ``object``. The second argument determines whether
-``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size
-is unknown. The third argument controls how ``llvm.objectsize`` acts when
-``null`` in address space 0 is used as its pointer argument. If it's ``false``,
+The ``llvm.objectsize`` intrinsic takes four arguments. The first argument is a
+pointer to or into the ``object``. The second argument determines whether
+``llvm.objectsize`` returns 0 (if true) or -1 (if false) when the object size is
+unknown. The third argument controls how ``llvm.objectsize`` acts when ``null``
+in address space 0 is used as its pointer argument. If it's ``false``,
 ``llvm.objectsize`` reports 0 bytes available when given ``null``. Otherwise, if
 the ``null`` is in a non-zero address space or if ``true`` is given for the
-third argument of ``llvm.objectsize``, we assume its size is unknown.
+third argument of ``llvm.objectsize``, we assume its size is unknown. The fourth
+argument to ``llvm.objectsize`` determines if the value should be evaluated at
+runtime.
 
-The second and third arguments only accept constants.
+The second, third, and fourth arguments only accept constants.
 
 Semantics:
 """"""""""
 
-The ``llvm.objectsize`` intrinsic is lowered to a constant representing
-the size of the object concerned. If the size cannot be determined at
-compile time, ``llvm.objectsize`` returns ``i32/i64 -1 or 0`` (depending
-on the ``min`` argument).
+The ``llvm.objectsize`` intrinsic is lowered to a value representing the size of
+the object concerned. If the size cannot be determined, ``llvm.objectsize``
+returns ``i32/i64 -1 or 0`` (depending on the ``min`` argument).
 
 '``llvm.expect``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -15518,8 +15825,7 @@
 """"""""""
 
 The ``llvm.expect`` intrinsic takes two arguments. The first argument is
-a value. The second argument is an expected value, this needs to be a
-constant value, variables are not allowed.
+a value. The second argument is an expected value.
 
 Semantics:
 """"""""""
diff --git a/docs/LibFuzzer.rst b/docs/LibFuzzer.rst
index 0737fbb..49f72f6 100644
--- a/docs/LibFuzzer.rst
+++ b/docs/LibFuzzer.rst
@@ -178,6 +178,29 @@
 running with ``-jobs=30`` on a 12-core machine would run 6 workers by default,
 with each worker averaging 5 bugs by completion of the entire process.
 
+Fork mode
+---------
+
+**Experimental** mode ``-fork=N`` (where ``N`` is the number of parallel jobs)
+enables oom-, timeout-, and crash-resistant
+fuzzing with separate processes (using ``fork-exec``, not just ``fork``).
+
+The top libFuzzer process will not do any fuzzing itself, but will
+spawn up to ``N`` concurrent child processes providing them
+small random subsets of the corpus. After a child exits, the top process
+merges the corpus generated by the child back to the main corpus.
+
+Related flags:
+
+``-ignore_ooms``
+  True by default. If an OOM happens during fuzzing in one of the child processes,
+  the reproducer is saved on disk, and fuzzing continues.
+``-ignore_timeouts``
+  True by default, same as ``-ignore_ooms``, but for timeouts.
+``-ignore_crashes``
+  False by default, same as ``-ignore_ooms``, but for all other crashes.
+
+The plan is to eventually replace ``-jobs=N`` and ``-workers=N`` with ``-fork=N``.
 
 Resuming merge
 --------------
@@ -235,6 +258,10 @@
 ``-max_len``
   Maximum length of a test input. If 0 (the default), libFuzzer tries to guess
   a good value based on the corpus (and reports it).
+``len_control``
+  Try generating small inputs first, then try larger inputs over time.
+  Specifies the rate at which the length limit is increased (smaller == faster).
+  Default is 100. If 0, immediately try inputs with size up to max_len.
 ``-timeout``
   Timeout in seconds, default 1200. If an input takes longer than this timeout,
   the process is treated as a failure case.
@@ -414,8 +441,8 @@
     return 0;
   }
   EOF
-  # Build test_fuzzer.cc with asan and link against libFuzzer.a
-  clang++ -fsanitize=address -fsanitize-coverage=trace-pc-guard test_fuzzer.cc libFuzzer.a
+  # Build test_fuzzer.cc with asan and link against libFuzzer.
+  clang++ -fsanitize=address,fuzzer test_fuzzer.cc
   # Run the fuzzer with no corpus.
   ./a.out
 
@@ -483,7 +510,7 @@
 Value Profile
 -------------
 
-With  ``-fsanitize-coverage=trace-cmp``
+With  ``-fsanitize-coverage=trace-cmp`` (default with ``-fsanitize=fuzzer``)
 and extra run-time flag ``-use_value_profile=1`` the fuzzer will
 collect value profiles for the parameters of compare instructions
 and treat some new values as new coverage.
@@ -544,7 +571,7 @@
 Currently, there is no simple way to run both fuzzing engines in parallel while sharing the same corpus dir.
 
 You may also use AFL on your target function ``LLVMFuzzerTestOneInput``:
-see an example `here <https://github.com/llvm-mirror/compiler-rt/tree/master/lib/fuzzer/afl>`__.
+see an example `here <https://github.com/llvm/llvm-project/tree/master/compiler-rt/lib/fuzzer/afl>`__.
 
 How good is my fuzzer?
 ----------------------
@@ -562,8 +589,9 @@
 User-supplied mutators
 ----------------------
 
-LibFuzzer allows to use custom (user-supplied) mutators,
-see FuzzerInterface.h_
+LibFuzzer allows to use custom (user-supplied) mutators, see
+`Structure-Aware Fuzzing <https://github.com/google/fuzzer-test-suite/blob/master/tutorial/structure-aware-fuzzing.md>`_
+for more details.
 
 Startup initialization
 ----------------------
@@ -645,10 +673,20 @@
 using more external dependencies we will slow down the fuzzer while the main
 reason for it to exist is extreme speed.
 
-Q. What about Windows then? The fuzzer contains code that does not build on Windows.
+Q. Does libFuzzer Support Windows?
 ------------------------------------------------------------------------------------
 
-Volunteers are welcome.
+Yes, libFuzzer now supports Windows. Initial support was added in r341082.
+Any build of Clang 9 supports it. You can download a build of Clang for Windows
+that has libFuzzer from
+`LLVM Snapshot Builds <https://llvm.org/builds/>`_.
+
+Using libFuzzer on Windows without ASAN is unsupported. Building fuzzers with the
+``/MD`` (dynamic runtime library) compile option is unsupported. Support for these
+may be added in the future. Linking fuzzers with the ``/INCREMENTAL`` link option
+(or the ``/DEBUG`` option which implies it) is also unsupported.
+
+Send any questions or comments to the mailing list: libfuzzer(#)googlegroups.com
 
 Q. When libFuzzer is not a good solution for a problem?
 ---------------------------------------------------------
@@ -680,6 +718,13 @@
 Examples: regular expression matchers, text or binary format parsers, compression,
 network, crypto.
 
+Q. LibFuzzer crashes on my complicated fuzz target (but works fine for me on smaller targets).
+----------------------------------------------------------------------------------------------
+
+Check if your fuzz target uses ``dlclose``.
+Currently, libFuzzer doesn't support targets that call ``dlclose``,
+this may be fixed in future.
+
 
 Trophies
 ========
@@ -741,7 +786,7 @@
 .. _AddressSanitizer: http://clang.llvm.org/docs/AddressSanitizer.html
 .. _LeakSanitizer: http://clang.llvm.org/docs/LeakSanitizer.html
 .. _Heartbleed: http://en.wikipedia.org/wiki/Heartbleed
-.. _FuzzerInterface.h: https://github.com/llvm-mirror/compiler-rt/blob/master/lib/fuzzer/FuzzerInterface.h
+.. _FuzzerInterface.h: https://github.com/llvm/llvm-project/blob/master/compiler-rt/lib/fuzzer/FuzzerInterface.h
 .. _3.7.0: http://llvm.org/releases/3.7.0/docs/LibFuzzer.html
 .. _building Clang from trunk: http://clang.llvm.org/get_started.html
 .. _MemorySanitizer: http://clang.llvm.org/docs/MemorySanitizer.html
diff --git a/docs/PDB/CodeViewSymbols.rst b/docs/PDB/CodeViewSymbols.rst
index 8b2133c..b056b80 100644
--- a/docs/PDB/CodeViewSymbols.rst
+++ b/docs/PDB/CodeViewSymbols.rst
@@ -1,4 +1,272 @@
-=====================================

-CodeView Symbol Records

-=====================================

-

+=====================================
+CodeView Symbol Records
+=====================================
+
+
+.. contents::
+   :local:
+
+.. _symbols_intro:
+
+Introduction
+============
+
+This document describes the usage and serialization format of the various
+CodeView symbol records that LLVM understands.  Like
+:doc:`CodeView Type Records <CodeViewTypes>`, we describe only the important
+types which are generated by modern C++ toolchains.
+
+Record Categories
+=================
+
+Symbol records share one major similarity with :doc:`type records <CodeViewTypes>`:
+They start with the same :ref:`record prefix <leaf_types>`, which we will not describe
+again (refer to the previous link for a description).  As a result of this, a sequence
+of symbol records can be processed with largely the same code as that which processes
+type records.  There are several important differences between symbol and type records:
+
+* Symbol records only appear in the :doc:`PublicStream`, :doc:`GlobalStream`, and
+  :doc:`Module Info Streams <ModiStream>`.
+* Type records only appear in the :doc:`TPI & IPI streams <TpiStream>`.
+* While types are referenced from other CodeView records via :ref:`type indices <type_indices>`,
+  symbol records are referenced by the byte offset of the record in the stream that it appears
+  in.
+* Types can reference types (via type indices), and symbols can reference both types (via type
+  indices) and symbols (via offsets), but types can never reference symbols.
+* There is no notion of :ref:`Leaf Records <leaf_types>` and :ref:`Member Records <member_types>`
+  as there are with types.  Every symbol record describes is own length.
+* Certain special symbol records begin a "scope".  For these records, all following records
+  up until the next ``S_END`` record are "children" of this symbol record.  For example,
+  given a symbol record which describes a certain function, all local variables of this
+  function would appear following the function up until the corresponding ``S_END`` record.
+
+Finally, there are three general categories of symbol record, grouped by where they are legal
+to appear in a PDB file.  Public Symbols (which appear only in the
+:doc:`publics stream <PublicStream>`), Global Symbols (which appear only in the
+:doc:`globals stream <GlobalStream>`) and module symbols (which appear in the
+:doc:`module info stream <ModiStream>`).
+
+
+.. _public_symbols:
+
+Public Symbols
+--------------
+
+Public symbols are the CodeView equivalent of DWARF ``.debug_pubnames``.  There
+is one public symbol record for every function or variable in the program that
+has a mangled name.  The :doc:`Publics Stream <PublicStream>`, which contains these
+records, additionally contains a hash table that allows one to quickly locate a
+record by mangled name.
+
+S_PUB32 (0x110e)
+^^^^^^^^^^^^^^^^
+
+There is only type of public symbol, an ``S_PUB32`` which describes a mangled
+name, a flag indicating what kind of symbol it is (e.g. function, variable), and
+the symbol's address.  The :ref:`dbi_section_map_substream` of the
+:doc:`DBI Stream <DbiStream>` can be consulted to determine what module this address
+corresponds to, and from there that module's :doc:`module debug stream <ModiStream>`
+can be consulted to locate full information for the symbol with the given address.
+
+.. _global_symbols:
+
+Global Symbols
+--------------
+
+While there is one :ref:`public symbol <public_symbols>` for every symbol in the
+program with `external` linkage, there is one global symbol for every symbol in the
+program with linkage (including internal linkage).  As a result, global symbols do
+not describe a mangled name *or* an address, since symbols with internal linkage
+need not have any mangling at all, and also may not have an address.  Thus, all
+global symbols simply refer directly to the full symbol record via a module/offset
+combination.
+
+Similarly to :ref:`public symbols <public_symbols>`, all global symbols are contained
+in a single :doc:`Globals Stream <GlobalStream>`, which contains a hash table mapping
+fully qualified name to the corresponding record in the globals stream (which as
+mentioned, then contains information allowing one to locate the full record in the
+corresponding module symbol stream).
+
+Note that a consequence and limitation of this design is that program-wide lookup
+by anything other than an exact textually matching fully-qualified name of whatever
+the compiler decided to emit is impractical.  This differs from DWARF, where even
+though we don't necessarily have O(1) lookup by basename within a given scope (including
+O(1) scope, we at least have O(n) access within a given scope).
+
+.. important::

+   Program-wide lookup of names by anything other than an exact textually matching fully

+   qualified name is not possible.

+
+
+S_GDATA32
+^^^^^^^^^^
+
+S_GTHREAD32 (0x1113)
+^^^^^^^^^^^^^^^^^^^^
+
+S_PROCREF (0x1125)
+^^^^^^^^^^^^^^^^^^
+
+S_LPROCREF (0x1127)
+^^^^^^^^^^^^^^^^^^^
+
+S_GMANDATA (0x111d)
+^^^^^^^^^^^^^^^^^^^
+
+.. _module_symbols:
+
+Module Symbols
+--------------
+
+S_END (0x0006)
+^^^^^^^^^^^^^^
+
+S_FRAMEPROC (0x1012)
+^^^^^^^^^^^^^^^^^^^^
+
+S_OBJNAME (0x1101)
+^^^^^^^^^^^^^^^^^^
+
+S_THUNK32 (0x1102)
+^^^^^^^^^^^^^^^^^^
+
+S_BLOCK32 (0x1103)
+^^^^^^^^^^^^^^^^^^
+
+S_LABEL32 (0x1105)
+^^^^^^^^^^^^^^^^^^
+
+S_REGISTER (0x1106)
+^^^^^^^^^^^^^^^^^^^
+
+S_BPREL32 (0x110b)
+^^^^^^^^^^^^^^^^^^
+
+S_LPROC32 (0x110f)
+^^^^^^^^^^^^^^^^^^
+
+S_GPROC32 (0x1110)
+^^^^^^^^^^^^^^^^^^
+
+S_REGREL32 (0x1111)
+^^^^^^^^^^^^^^^^^^^
+
+S_COMPILE2 (0x1116)
+^^^^^^^^^^^^^^^^^^^
+
+S_UNAMESPACE (0x1124)
+^^^^^^^^^^^^^^^^^^^^^
+
+S_TRAMPOLINE (0x112c)
+^^^^^^^^^^^^^^^^^^^^^
+
+S_SECTION (0x1136)
+^^^^^^^^^^^^^^^^^^
+
+S_COFFGROUP (0x1137)
+^^^^^^^^^^^^^^^^^^^^
+
+S_EXPORT (0x1138)
+^^^^^^^^^^^^^^^^^
+
+S_CALLSITEINFO (0x1139)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+S_FRAMECOOKIE (0x113a)
+^^^^^^^^^^^^^^^^^^^^^^
+
+S_COMPILE3 (0x113c)
+^^^^^^^^^^^^^^^^^^^
+
+S_ENVBLOCK (0x113d)
+^^^^^^^^^^^^^^^^^^^
+
+S_LOCAL (0x113e)
+^^^^^^^^^^^^^^^^
+
+S_DEFRANGE (0x113f)
+^^^^^^^^^^^^^^^^^^^
+
+S_DEFRANGE_SUBFIELD (0x1140)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_DEFRANGE_REGISTER (0x1141)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_DEFRANGE_FRAMEPOINTER_REL (0x1142)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_DEFRANGE_SUBFIELD_REGISTER (0x1143)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_DEFRANGE_FRAMEPOINTER_REL_FULL_SCOPE (0x1144)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_DEFRANGE_REGISTER_REL (0x1145)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_LPROC32_ID (0x1146)
+^^^^^^^^^^^^^^^^^^^^^
+
+S_GPROC32_ID (0x1147)
+^^^^^^^^^^^^^^^^^^^^^
+
+S_BUILDINFO (0x114c)
+^^^^^^^^^^^^^^^^^^^^
+
+S_INLINESITE (0x114d)
+^^^^^^^^^^^^^^^^^^^^^
+
+S_INLINESITE_END (0x114e)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_PROC_ID_END (0x114f)
+^^^^^^^^^^^^^^^^^^^^^^
+
+S_FILESTATIC (0x1153)
+^^^^^^^^^^^^^^^^^^^^^
+
+S_LPROC32_DPC (0x1155)
+^^^^^^^^^^^^^^^^^^^^^^
+
+S_LPROC32_DPC_ID (0x1156)
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_CALLEES (0x115a)
+^^^^^^^^^^^^^^^^^^
+
+S_CALLERS (0x115b)
+^^^^^^^^^^^^^^^^^^
+
+S_HEAPALLOCSITE (0x115e)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+S_FASTLINK (0x1167)
+^^^^^^^^^^^^^^^^^^^
+
+S_INLINEES (0x1168)
+^^^^^^^^^^^^^^^^^^^
+
+.. _module_and_global_symbols:
+
+Symbols which can go in either/both of the module info stream & global stream
+-----------------------------------------------------------------------------
+
+S_CONSTANT (0x1107)
+^^^^^^^^^^^^^^^^^^^
+
+S_UDT (0x1108)
+^^^^^^^^^^^^^^
+
+S_LDATA32 (0x110c)
+^^^^^^^^^^^^^^^^^^
+
+S_LTHREAD32 (0x1112)
+^^^^^^^^^^^^^^^^^^^^
+
+S_LMANDATA (0x111c)
+^^^^^^^^^^^^^^^^^^^
+
+S_MANCONSTANT (0x112d)
+^^^^^^^^^^^^^^^^^^^^^^
+
diff --git a/docs/PDB/CodeViewTypes.rst b/docs/PDB/CodeViewTypes.rst
index ad806a7..99c05e9 100644
--- a/docs/PDB/CodeViewTypes.rst
+++ b/docs/PDB/CodeViewTypes.rst
@@ -1,4 +1,261 @@
-=====================================

-CodeView Type Records

-=====================================

-

+=====================================
+CodeView Type Records
+=====================================
+
+
+.. contents::
+   :local:
+
+.. _types_intro:
+
+Introduction
+============
+
+This document describes the usage and serialization format of the various
+CodeView type records that LLVM understands.  This document does not describe
+every single CodeView type record that is defined.  In some cases, this is
+because the records are clearly deprecated and can only appear in very old
+software (e.g. the 16-bit types).  On other cases, it is because the records
+have never been observed in practice.  This could be because they are only
+generated for non-C++ code (e.g. Visual Basic, C#), or because they have been
+made obsolete by newer records, or any number of other reasons.  However, the
+records we describe here should cover 99% of type records that one can expect
+to encounter when dealing with modern C++ toolchains.
+
+Record Categories
+=================
+
+We can think of a sequence of CodeView type records as an array of variable length
+`leaf records`.  Each such record describes its own length as part of a fixed-size
+header, as well as the kind of record it is.  Leaf records are either padded to 4
+bytes (if this type stream appears in a TPI/IPI stream of a PDB) or not padded at
+all (if this type stream appears in the ``.debug$T`` section of an object file).
+Padding is implemented by inserting a decreasing sequence of `<_padding_records>`
+that terminates with ``LF_PAD0``.
+
+The final category of record is a ``member record``.  One particular leaf type -- 
+``LF_FIELDLIST`` -- contains a series of embedded records.  While the outer
+``LF_FIELDLIST`` describes its length (like any other leaf record), the embedded
+records -- called ``member records`` do not.
+
+.. _leaf_types:
+
+Leaf Records
+------------
+
+All leaf records begin with the following 4 byte prefix:
+
+.. code-block:: c++
+
+  struct RecordHeader {
+    uint16_t RecordLen;  // Record length, not including this 2 byte field.
+    uint16_t RecordKind; // Record kind enum.
+  };
+
+LF_POINTER (0x1002)
+^^^^^^^^^^^^^^^^^^^
+
+**Usage:** Describes a pointer to another type.
+
+**Layout:**
+
+.. code-block:: none
+
+  .--------------------.-- +0
+  |    Referent Type   |
+  .--------------------.-- +4
+  |     Attributes     |
+  .--------------------.-- +8
+  |  Member Ptr Info   |       Only present if |Attributes| indicates this is a member pointer.
+  .--------------------.-- +E
+
+Attributes is a bitfield with the following layout:
+
+.. code-block:: none
+
+    .-----------------------------------------------------------------------------------------------------.
+    |     Unused                   |  Flags  |       Size       |   Modifiers   |  Mode   |      Kind     |
+    .-----------------------------------------------------------------------------------------------------.
+    |                              |         |                  |               |         |               |
+   0x100                         +0x16     +0x13               +0xD            +0x8      +0x5            +0x0
+
+where the various fields are defined by the following enums:
+
+.. code-block:: c++
+
+  enum class PointerKind : uint8_t {
+    Near16 = 0x00,                // 16 bit pointer
+    Far16 = 0x01,                 // 16:16 far pointer
+    Huge16 = 0x02,                // 16:16 huge pointer
+    BasedOnSegment = 0x03,        // based on segment
+    BasedOnValue = 0x04,          // based on value of base
+    BasedOnSegmentValue = 0x05,   // based on segment value of base
+    BasedOnAddress = 0x06,        // based on address of base
+    BasedOnSegmentAddress = 0x07, // based on segment address of base
+    BasedOnType = 0x08,           // based on type
+    BasedOnSelf = 0x09,           // based on self
+    Near32 = 0x0a,                // 32 bit pointer
+    Far32 = 0x0b,                 // 16:32 pointer
+    Near64 = 0x0c                 // 64 bit pointer
+  };
+  enum class PointerMode : uint8_t {
+    Pointer = 0x00,                 // "normal" pointer
+    LValueReference = 0x01,         // "old" reference
+    PointerToDataMember = 0x02,     // pointer to data member
+    PointerToMemberFunction = 0x03, // pointer to member function
+    RValueReference = 0x04          // r-value reference
+  };
+  enum class PointerModifiers : uint8_t {
+    None = 0x00,                    // "normal" pointer
+    Flat32 = 0x01,                  // "flat" pointer
+    Volatile = 0x02,                // pointer is marked volatile
+    Const = 0x04,                   // pointer is marked const
+    Unaligned = 0x08,               // pointer is marked unaligned
+    Restrict = 0x10,                // pointer is marked restrict
+  };
+  enum class PointerFlags : uint8_t {
+    WinRTSmartPointer = 0x01,       // pointer is a WinRT smart pointer
+    LValueRefThisPointer = 0x02,    // pointer is a 'this' pointer of a member function with ref qualifier (e.g. void X::foo() &)
+    RValueRefThisPointer = 0x04     // pointer is a 'this' pointer of a member function with ref qualifier (e.g. void X::foo() &&)
+  };
+
+The ``Size`` field of the Attributes bitmask is a 1-byte value indicating the
+pointer size.  For example, a `void*` would have a size of either 4 or 8 depending
+on the target architecture.  On the other hand, if ``Mode`` indicates that this is
+a pointer to member function or pointer to data member, then the size can be any
+implementation defined number.
+
+The ``Member Ptr Info`` field of the ``LF_POINTER`` record is only present if the
+attributes indicate that this is a pointer to member.
+
+Note that "plain" pointers to primitive types are not represented by ``LF_POINTER``
+records, they are indicated by special reserved :ref:`TypeIndex values <type_indices>`.
+
+
+
+LF_MODIFIER (0x1001)
+^^^^^^^^^^^^^^^^^^^^
+
+LF_PROCEDURE (0x1008)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_MFUNCTION (0x1009)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_LABEL (0x000e)
+^^^^^^^^^^^^^^^^^
+
+LF_ARGLIST (0x1201)
+^^^^^^^^^^^^^^^^^^^
+
+LF_FIELDLIST (0x1203)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_ARRAY (0x1503)
+^^^^^^^^^^^^^^^^^
+
+LF_CLASS (0x1504)
+^^^^^^^^^^^^^^^^^
+
+LF_STRUCTURE (0x1505)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_INTERFACE (0x1519)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_UNION (0x1506)
+^^^^^^^^^^^^^^^^^
+
+LF_ENUM (0x1507)
+^^^^^^^^^^^^^^^^
+
+LF_TYPESERVER2 (0x1515)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+LF_VFTABLE (0x151d)
+^^^^^^^^^^^^^^^^^^^
+
+LF_VTSHAPE (0x000a)
+^^^^^^^^^^^^^^^^^^^
+
+LF_BITFIELD (0x1205)
+^^^^^^^^^^^^^^^^^^^^
+
+LF_FUNC_ID (0x1601)
+^^^^^^^^^^^^^^^^^^^
+
+LF_MFUNC_ID (0x1602)
+^^^^^^^^^^^^^^^^^^^^
+
+LF_BUILDINFO (0x1603)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_SUBSTR_LIST (0x1604)
+^^^^^^^^^^^^^^^^^^^^^^^
+
+LF_STRING_ID (0x1605)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_UDT_SRC_LINE (0x1606)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+LF_UDT_MOD_SRC_LINE (0x1607)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+LF_METHODLIST (0x1206)
+^^^^^^^^^^^^^^^^^^^^^^
+
+LF_PRECOMP (0x1509)
+^^^^^^^^^^^^^^^^^^^
+
+LF_ENDPRECOMP (0x0014)
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. _member_types:
+
+Member Records
+--------------
+
+LF_BCLASS (0x1400)
+^^^^^^^^^^^^^^^^^^
+
+LF_BINTERFACE (0x151a)
+^^^^^^^^^^^^^^^^^^^^^^
+
+LF_VBCLASS (0x1401)
+^^^^^^^^^^^^^^^^^^^
+
+LF_IVBCLASS (0x1402)
+^^^^^^^^^^^^^^^^^^^^
+
+LF_VFUNCTAB (0x1409)
+^^^^^^^^^^^^^^^^^^^^
+
+LF_STMEMBER (0x150e)
+^^^^^^^^^^^^^^^^^^^^
+
+LF_METHOD (0x150f)
+^^^^^^^^^^^^^^^^^^
+
+LF_MEMBER (0x150d)
+^^^^^^^^^^^^^^^^^^
+
+LF_NESTTYPE (0x1510)
+^^^^^^^^^^^^^^^^^^^^
+
+LF_ONEMETHOD (0x1511)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_ENUMERATE (0x1502)
+^^^^^^^^^^^^^^^^^^^^^
+
+LF_INDEX (0x1404)
+^^^^^^^^^^^^^^^^^
+
+.. _padding_records:
+
+Padding Records
+---------------
+
+LF_PADn (0xf0 + n)
+^^^^^^^^^^^^^^^^^^
diff --git a/docs/PDB/DbiStream.rst b/docs/PDB/DbiStream.rst
index fec0e29..bdb5b56 100644
--- a/docs/PDB/DbiStream.rst
+++ b/docs/PDB/DbiStream.rst
@@ -43,7 +43,7 @@
     int32_t SectionContributionSize;
     int32_t SectionMapSize;
     int32_t SourceInfoSize;
-    int32_t TypeServerSize;
+    int32_t TypeServerMapSize;
     uint32_t MFCTypeServerIndex;
     int32_t OptionalDbgHeaderSize;
     int32_t ECSubstreamSize;
@@ -105,7 +105,8 @@
   
 - **PdbDllRbld** - Unknown
 
-- **MFCTypeServerIndex** - The length of the :ref:dbi_mfc_type_server_substream
+- **MFCTypeServerIndex** - The index of the MFC type server in the
+  :ref:`dbi_type_server_map_substream`.
 
 - **Flags** - A bitfield with the following layout, containing various
   information about how the program was built:
@@ -141,7 +142,7 @@
 
 - **SourceInfoSize** - The length of the :ref:`dbi_file_info_substream`.
 
-- **TypeServerSize** - The length of the :ref:`dbi_type_server_substream`. 
+- **TypeServerMapSize** - The length of the :ref:`dbi_type_server_map_substream`.
 
 - **OptionalDbgHeaderSize** - The length of the :ref:`dbi_optional_dbg_stream`.
 
@@ -164,28 +165,19 @@
   
 .. code-block:: c++
 
-  struct SectionContribEntry {
-    uint16_t Section;
-    char Padding1[2];
-    int32_t Offset;
-    int32_t Size;
-    uint32_t Characteristics;
-    uint16_t ModuleIndex;
-    char Padding2[2];
-    uint32_t DataCrc;
-    uint32_t RelocCrc;
-  };
-  
-While most of these are self-explanatory, the ``Characteristics`` field
-warrants some elaboration.  It corresponds to the ``Characteristics``
-field of the `IMAGE_SECTION_HEADER <https://msdn.microsoft.com/en-us/library/windows/desktop/ms680341(v=vs.85).aspx>`__
-structure.
-  
-.. code-block:: c++
-
   struct ModInfo {
     uint32_t Unused1;
-    SectionContribEntry SectionContr;
+    struct SectionContribEntry {
+      uint16_t Section;
+      char Padding1[2];
+      int32_t Offset;
+      int32_t Size;
+      uint32_t Characteristics;
+      uint16_t ModuleIndex;
+      char Padding2[2];
+      uint32_t DataCrc;
+      uint32_t RelocCrc;
+    } SectionContr;
     uint16_t Flags;
     uint16_t ModuleSymStream;
     uint32_t SymByteSize;
@@ -203,19 +195,35 @@
 - **SectionContr** - Describes the properties of the section in the final binary
   which contain the code and data from this module.
 
+  ``SectionContr.Characteristics`` corresponds to the ``Characteristics`` field
+  of the `IMAGE_SECTION_HEADER <https://msdn.microsoft.com/en-us/library/windows/desktop/ms680341(v=vs.85).aspx>`__
+  structure.
+  
+
 - **Flags** - A bitfield with the following format:
   
 .. code-block:: c++
 
-  uint16_t Dirty : 1;  // ``true`` if this ModInfo has been written since reading the PDB.
-  uint16_t EC : 1;     // ``true`` if EC information is present for this module. It is unknown what EC actually is.
+  // ``true`` if this ModInfo has been written since reading the PDB.  This is
+  // likely used to support incremental linking, so that the linker can decide
+  // if it needs to commit changes to disk.
+  uint16_t Dirty : 1;
+  // ``true`` if EC information is present for this module. EC is presumed to
+  // stand for "Edit & Continue", which LLVM does not support.  So this flag
+  // will always be be false.
+  uint16_t EC : 1;
   uint16_t Unused : 6;
-  uint16_t TSM : 8;    // Type Server Index for this module.  It is unknown what this is used for, but it is not used by LLVM.
+  // Type Server Index for this module.  This is assumed to be related to /Zi,
+  // but as LLVM treats /Zi as /Z7, this field will always be invalid for LLVM
+  // generated PDBs.
+  uint16_t TSM : 8;
   
 
 - **ModuleSymStream** - The index of the stream that contains symbol information
   for this module.  This includes CodeView symbol information as well as source
-  and line information.
+  and line information.  If this field is -1, then no additional debug info will
+  be present for this module (for example, this is what happens when you strip
+  private symbols from a PDB).
 
 - **SymByteSize** - The number of bytes of data from the stream identified by
   ``ModuleSymStream`` that represent CodeView symbol records.
@@ -225,7 +233,8 @@
 
 - **C13ByteSize** - The number of bytes of data from the stream identified by
   ``ModuleSymStream`` that represent C13-style CodeView line information.  At
-  most one of ``C11ByteSize`` and ``C13ByteSize`` will be non-zero.
+  most one of ``C11ByteSize`` and ``C13ByteSize`` will be non-zero.  Modern PDBs
+  always use C13 instead of C11.
 
 - **SourceFileCount** - The number of source files that contributed to this
   module during compilation.
@@ -263,10 +272,10 @@
   };
   
 ``Ver60`` is the only value which has been observed in a PDB so far.  Following
-this ``4`` byte field is an array of fixed-length structures.  If the version
-is ``Ver60``, it is an array of ``SectionContribEntry`` structures.  If the
-version is ``V2``, it is an array of ``SectionContribEntry2`` structures,
-defined as follows:
+this is an array of fixed-length structures.  If the version is ``Ver60``,
+it is an array of ``SectionContribEntry`` structures (this is the nested structure
+from the ``ModInfo`` type.  If the version is ``V2``, it is an array of
+``SectionContribEntry2`` structures, defined as follows:
   
 .. code-block:: c++
 
@@ -275,7 +284,9 @@
     uint32_t ISectCoff;
   };
   
-The purpose of the second field is not well understood.
+The purpose of the second field is not well understood.  The name implies that
+is the index of the COFF section, but this also describes the existing field
+``SectionContribEntry::Section``.
   
 
 .. _dbi_section_map_substream:
@@ -283,7 +294,7 @@
 Section Map Substream
 ^^^^^^^^^^^^^^^^^^^^^
 Begins at offset ``0`` immediately after the :ref:`dbi_sec_contr_substream` ends,
-and consumes ``Header->SectionMapSize`` bytes.  This substream begins with an ``8``
+and consumes ``Header->SectionMapSize`` bytes.  This substream begins with an ``4``
 byte header followed by an array of fixed-length records.  The header and records
 have the following layout:
   
@@ -371,22 +382,25 @@
 **NamesBuffer** - An array of null terminated strings containing the actual source
 file names.
 
-.. _dbi_type_server_substream:
+.. _dbi_type_server_map_substream:
 
-Type Server Substream
-^^^^^^^^^^^^^^^^^^^^^
-Begins at offset ``0`` immediately after the :ref:`dbi_file_info_substream` ends,
-and consumes ``Header->TypeServerSize`` bytes.  Neither the purpose nor the layout
-of this substream is understood, although it is assumed to related somehow to the
-usage of ``/Zi`` and ``mspdbsrv.exe``.  This substream will not be discussed further.
+Type Server Map Substream
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Begins at offset ``0`` immediately after the :ref:`dbi_file_info_substream`
+ends, and consumes ``Header->TypeServerMapSize`` bytes.  Neither the purpose
+nor the layout of this substream is understood, although it is assumed to
+related somehow to the usage of ``/Zi`` and ``mspdbsrv.exe``.  This substream
+will not be discussed further.
 
 .. _dbi_ec_substream:
 
 EC Substream
 ^^^^^^^^^^^^
-Begins at offset ``0`` immediately after the :ref:`dbi_type_server_substream` ends,
-and consumes ``Header->ECSubstreamSize`` bytes.  Neither the purpose nor the layout
-of this substream is understood, and it will not be discussed further.
+Begins at offset ``0`` immediately after the
+:ref:`dbi_type_server_map_substream` ends, and consumes
+``Header->ECSubstreamSize`` bytes.  This is presumed to be related to Edit &
+Continue support in MSVC.  LLVM does not support Edit & Continue, so this
+stream will not be discussed further.
 
 .. _dbi_optional_dbg_stream:
 
@@ -402,9 +416,12 @@
 layout of each stream generally corresponds exactly to a particular type
 of debug data directory from the PE/COFF file.  The format of these fields
 can be found in the `Microsoft PE/COFF Specification <https://www.microsoft.com/en-us/download/details.aspx?id=19509>`__.
+If any of these fields is -1, it means the corresponding type of debug info is
+not present in the PDB.
 
-**FPO Data** - ``DbgStreamArray[0]``.  The data in the referenced stream is a
-debug data directory of type ``IMAGE_DEBUG_TYPE_FPO``
+**FPO Data** - ``DbgStreamArray[0]``.  The data in the referenced stream is an
+array of ``FPO_DATA`` structures.  This contains the relocated contents of
+any ``.debug$F`` section from any of the linker inputs.
 
 **Exception Data** - ``DbgStreamArray[1]``.  The data in the referenced stream
 is a debug data directory of type ``IMAGE_DEBUG_TYPE_EXCEPTION``.
@@ -437,9 +454,12 @@
 understood.
 
 **New FPO Data** - ``DbgStreamArray[9]``.  The data in the referenced stream is a
-debug data directory of type ``IMAGE_DEBUG_TYPE_FPO``.  It is not clear how this
-differs from ``DbgStreamArray[0]``, but in practice all observed PDB files have
-used the "new" format rather than the "old" format.
+debug data directory of type ``IMAGE_DEBUG_TYPE_FPO``.  Note that this is different
+from ``DbgStreamArray[0]`` in that ``.debug$F`` sections are only emitted by MASM.
+Thus, it is possible for both to appear in the same PDB if both MASM object files
+and cl object files are linked into the same program.
 
-**Original Section Header Data** - ``DbgStreamArray[10]``.  Assumed to be similar
-to ``DbgStreamArray[5]``, but has not been observed in practice.
+**Original Section Header Data** - ``DbgStreamArray[10]``.  Similar to 
+``DbgStreamArray[5]``, but contains the section headers before any binary translation
+has been performed.  This can be used in conjunction with ``DebugStreamArray[3]``
+and ``DbgStreamArray[4]`` to map instrumented and uninstrumented addresses.
diff --git a/docs/PDB/GlobalStream.rst b/docs/PDB/GlobalStream.rst
index 314b9f0..dcc99ae 100644
--- a/docs/PDB/GlobalStream.rst
+++ b/docs/PDB/GlobalStream.rst
@@ -1,3 +1,3 @@
-=====================================

-The PDB Global Symbol Stream

-=====================================

+=====================================
+The PDB Global Symbol Stream
+=====================================
diff --git a/docs/PDB/HashStream.rst b/docs/PDB/HashStream.rst
deleted file mode 100644
index a758db4..0000000
--- a/docs/PDB/HashStream.rst
+++ /dev/null
@@ -1,3 +0,0 @@
-=====================================

-The TPI & IPI Hash Streams

-=====================================

diff --git a/docs/PDB/HashTable.rst b/docs/PDB/HashTable.rst
new file mode 100644
index 0000000..eb7abbd
--- /dev/null
+++ b/docs/PDB/HashTable.rst
@@ -0,0 +1,103 @@
+The PDB Serialized Hash Table Format
+====================================
+
+.. contents::
+   :local:
+
+.. _hash_intro:
+
+Introduction
+============
+
+One of the design goals of the PDB format is to provide accelerated access to
+debug information, and for this reason there are several occasions where hash
+tables are serialized and embedded directly to the file, rather than requiring
+a consumer to read a list of values and reconstruct the hash table on the fly.
+
+The serialization format supports hash tables of arbitrarily large size and
+capacity, as well as value types and hash functions.  The only supported key
+value type is a uint32.  The only requirement is that the producer and consumer
+agree on the hash function.  As such, the hash function can is not discussed
+further in this document, it is assumed that for a particular instance of a PDB
+file hash table, the appropriate hash function is being used.
+
+On-Disk Format
+==============
+
+.. code-block:: none
+
+  .--------------------.-- +0
+  |        Size        |
+  .--------------------.-- +4
+  |      Capacity      |
+  .--------------------.-- +8
+  | Present Bit Vector |
+  .--------------------.-- +N
+  | Deleted Bit Vector |
+  .--------------------.-- +M                  ─╮
+  |        Key         |                        │
+  .--------------------.-- +M+4                 │
+  |       Value        |                        │
+  .--------------------.-- +M+4+sizeof(Value)   │
+           ...                                  ├─ |Capacity| Bucket entries
+  .--------------------.                        │
+  |        Key         |                        │
+  .--------------------.                        │
+  |       Value        |                        │
+  .--------------------.                       ─╯
+
+- **Size** - The number of values contained in the hash table.
+  
+- **Capacity** - The number of buckets in the hash table.  Producers should
+  maintain a load factor of no greater than ``2/3*Capacity+1``.
+  
+- **Present Bit Vector** - A serialized bit vector which contains information
+  about which buckets have valid values.  If the bucket has a value, the
+  corresponding bit will be set, and if the bucket doesn't have a value (either
+  because the bucket is empty or because the value is a tombstone value) the bit
+  will be unset.
+  
+- **Deleted Bit Vector** - A serialized bit vector which contains information
+  about which buckets have tombstone values.  If the entry in this bucket is
+  deleted, the bit will be set, otherwise it will be unset.
+
+- **Keys and Values** - A list of ``Capacity`` hash buckets, where the first
+  entry is the key (always a uint32), and the second entry is the value.  The
+  state of each bucket (valid, empty, deleted) can be determined by examining
+  the present and deleted bit vectors.
+
+
+.. _hash_bit_vectors:
+
+Present and Deleted Bit Vectors
+===============================
+
+The bit vectors indicating the status of each bucket are serialized as follows:
+
+.. code-block:: none
+
+  .--------------------.-- +0
+  |     Word Count     |
+  .--------------------.-- +4
+  |        Word_0      |        ─╮
+  .--------------------.-- +8    │
+  |        Word_1      |         │
+  .--------------------.-- +12   ├─ |Word Count| values
+           ...                   │
+  .--------------------.         │
+  |       Word_N       |         │
+  .--------------------.        ─╯
+
+The words, when viewed as a contiguous block of bytes, represent a bit vector with
+the following layout:
+
+.. code-block:: none
+
+    .------------.         .------------.------------.
+    |   Word_N   |   ...   |   Word_1   |   Word_0   |
+    .------------.         .------------.------------.
+    |            |         |            |            |
+  +N*32      +(N-1)*32    +64          +32          +0
+
+where the k'th bit of this bit vector represents the status of the k'th bucket
+in the hash table.
diff --git a/docs/PDB/ModiStream.rst b/docs/PDB/ModiStream.rst
index 7e500bd..8104c53 100644
--- a/docs/PDB/ModiStream.rst
+++ b/docs/PDB/ModiStream.rst
@@ -1,80 +1,80 @@
-=====================================

-The Module Information Stream

-=====================================

-

-.. contents::

-   :local:

-

-.. _modi_stream_intro:

-

-Introduction

-============

-

-The Module Info Stream (henceforth referred to as the Modi stream) contains

-information about a single module (object file, import library, etc that

-contributes to the binary this PDB contains debug information about.  There

-is one modi stream for each module, and the mapping between modi stream index

-and module is contained in the :doc:`DBI Stream <DbiStream>`.  The modi stream

-for a single module contains line information for the compiland, as well as

-all CodeView information for the symbols defined in the compiland.  Finally,

-there is a "global refs" substream which is not well understood.

-

-.. _modi_stream_layout:

-

-Stream Layout

-=============

-

-A modi stream is laid out as follows:

-

-

-.. code-block:: c++

-

-  struct ModiStream {

-    uint32_t Signature;

-    uint8_t Symbols[SymbolSize-4];

-    uint8_t C11LineInfo[C11Size];

-    uint8_t C13LineInfo[C13Size];

-    

-    uint32_t GlobalRefsSize;

-    uint8_t GlobalRefs[GlobalRefsSize];

-  };

-

-- **Signature** - Unknown.  In practice only the value of ``4`` has been

-  observed.  It is hypothesized that this value corresponds to the set of

-  ``CV_SIGNATURE_xx`` defines in ``cvinfo.h``, with the value of ``4``

-  meaning that this module has C13 line information (as opposed to C11 line

-  information).  A corollary of this is that we expect to only ever see

-  C13 line info, and that we do not understand the format of C11 line info.

-  

-- **Symbols** - The :ref:`CodeView Symbol Substream <modi_symbol_substream>`.

-  ``SymbolSize`` is equal to the value of ``SymByteSize`` for the

-  corresponding module's entry in the :ref:`Module Info Substream <dbi_mod_info_substream>`

-  of the :doc:`DBI Stream <DbiStream>`.

-

-- **C11LineInfo** - A block containing CodeView line information in C11

-  format.  ``C11Size`` is equal to the value of ``C11ByteSize`` from the

-  :ref:`Module Info Substream <dbi_mod_info_substream>` of the

-  :doc:`DBI Stream <DbiStream>`.  If this value is ``0``, then C11 line

-  information is not present.  As mentioned previously, the format of

-  C11 line info is not understood and we assume all line in modern PDBs

-  to be in C13 format.

-  

-- **C13LineInfo** - A block containing CodeView line information in C13

-  format.  ``C13Size`` is equal to the value of ``C13ByteSize`` from the

-  :ref:`Module Info Substream <dbi_mod_info_substream>` of the

-  :doc:`DBI Stream <DbiStream>`.  If this value is ``0``, then C13 line

-  information is not present.

-  

-- **GlobalRefs** - The meaning of this substream is not understood.

-

-.. _modi_symbol_substream:

-

-The CodeView Symbol Substream

-=============================

-

-The CodeView Symbol Substream.  This is an array of variable length

-records describing the functions, variables, inlining information,

-and other symbols defined in the compiland.  The entire array consumes

-``SymbolSize-4`` bytes.  The format of a CodeView Symbol Record (and

-thusly, an array of CodeView Symbol Records) is described in

-:doc:`CodeViewSymbols`.

+=====================================
+The Module Information Stream
+=====================================
+
+.. contents::
+   :local:
+
+.. _modi_stream_intro:
+
+Introduction
+============
+
+The Module Info Stream (henceforth referred to as the Modi stream) contains
+information about a single module (object file, import library, etc that
+contributes to the binary this PDB contains debug information about.  There
+is one modi stream for each module, and the mapping between modi stream index
+and module is contained in the :doc:`DBI Stream <DbiStream>`.  The modi stream
+for a single module contains line information for the compiland, as well as
+all CodeView information for the symbols defined in the compiland.  Finally,
+there is a "global refs" substream which is not well understood.
+
+.. _modi_stream_layout:
+
+Stream Layout
+=============
+
+A modi stream is laid out as follows:
+
+
+.. code-block:: c++
+
+  struct ModiStream {
+    uint32_t Signature;
+    uint8_t Symbols[SymbolSize-4];
+    uint8_t C11LineInfo[C11Size];
+    uint8_t C13LineInfo[C13Size];
+    
+    uint32_t GlobalRefsSize;
+    uint8_t GlobalRefs[GlobalRefsSize];
+  };
+
+- **Signature** - Unknown.  In practice only the value of ``4`` has been
+  observed.  It is hypothesized that this value corresponds to the set of
+  ``CV_SIGNATURE_xx`` defines in ``cvinfo.h``, with the value of ``4``
+  meaning that this module has C13 line information (as opposed to C11 line
+  information).  A corollary of this is that we expect to only ever see
+  C13 line info, and that we do not understand the format of C11 line info.
+  
+- **Symbols** - The :ref:`CodeView Symbol Substream <modi_symbol_substream>`.
+  ``SymbolSize`` is equal to the value of ``SymByteSize`` for the
+  corresponding module's entry in the :ref:`Module Info Substream <dbi_mod_info_substream>`
+  of the :doc:`DBI Stream <DbiStream>`.
+
+- **C11LineInfo** - A block containing CodeView line information in C11
+  format.  ``C11Size`` is equal to the value of ``C11ByteSize`` from the
+  :ref:`Module Info Substream <dbi_mod_info_substream>` of the
+  :doc:`DBI Stream <DbiStream>`.  If this value is ``0``, then C11 line
+  information is not present.  As mentioned previously, the format of
+  C11 line info is not understood and we assume all line in modern PDBs
+  to be in C13 format.
+  
+- **C13LineInfo** - A block containing CodeView line information in C13
+  format.  ``C13Size`` is equal to the value of ``C13ByteSize`` from the
+  :ref:`Module Info Substream <dbi_mod_info_substream>` of the
+  :doc:`DBI Stream <DbiStream>`.  If this value is ``0``, then C13 line
+  information is not present.
+  
+- **GlobalRefs** - The meaning of this substream is not understood.
+
+.. _modi_symbol_substream:
+
+The CodeView Symbol Substream
+=============================
+
+The CodeView Symbol Substream.  This is an array of variable length
+records describing the functions, variables, inlining information,
+and other symbols defined in the compiland.  The entire array consumes
+``SymbolSize-4`` bytes.  The format of a CodeView Symbol Record (and
+thusly, an array of CodeView Symbol Records) is described in
+:doc:`CodeViewSymbols`.
diff --git a/docs/PDB/MsfFile.rst b/docs/PDB/MsfFile.rst
index dfbbf9d..a53ebe3 100644
--- a/docs/PDB/MsfFile.rst
+++ b/docs/PDB/MsfFile.rst
@@ -1,179 +1,179 @@
-=====================================

-The MSF File Format

-=====================================

-

-.. contents::

-   :local:

-

-.. _msf_layout:

-

-File Layout

-===========

-

-The MSF file format consists of the following components:

-

-1. :ref:`msf_superblock`

-2. :ref:`msf_freeblockmap` (also know as Free Page Map, or FPM)

-3. Data

-

-Each component is stored as an indexed block, the length of which is specified

-in ``SuperBlock::BlockSize``. The file consists of 1 or more iterations of the

-following pattern (sometimes referred to as an "interval"):

-

-1. 1 block of data

-2. Free Block Map 1 (corresponds to ``SuperBlock::FreeBlockMapBlock`` 1)

-3. Free Block Map 2 (corresponds to ``SuperBlock::FreeBlockMapBlock`` 2)

-4. ``SuperBlock::BlockSize - 3`` blocks of data

-

-In the first interval, the first data block is used to store

-:ref:`msf_superblock`.

-

-The following diagram demonstrates the general layout of the file (\| denotes

-the end of an interval, and is for visualization purposes only):

-

-+-------------+-----------------------+------------------+------------------+----------+----+------+------+------+-------------+----+-----+

-| Block Index | 0                     | 1                | 2                | 3 - 4095 | \| | 4096 | 4097 | 4098 | 4099 - 8191 | \| | ... |

-+=============+=======================+==================+==================+==========+====+======+======+======+=============+====+=====+

-| Meaning     | :ref:`msf_superblock` | Free Block Map 1 | Free Block Map 2 | Data     | \| | Data | FPM1 | FPM2 | Data        | \| | ... |

-+-------------+-----------------------+------------------+------------------+----------+----+------+------+------+-------------+----+-----+

-

-The file may end after any block, including immediately after a FPM1.

-

-.. note::

-  LLVM only supports 4096 byte blocks (sometimes referred to as the "BigMsf"

-  variant), so the rest of this document will assume a block size of 4096.

-

-.. _msf_superblock:

-

-The Superblock

-==============

-At file offset 0 in an MSF file is the MSF *SuperBlock*, which is laid out as

-follows:

-

-.. code-block:: c++

-

-  struct SuperBlock {

-    char FileMagic[sizeof(Magic)];

-    ulittle32_t BlockSize;

-    ulittle32_t FreeBlockMapBlock;

-    ulittle32_t NumBlocks;

-    ulittle32_t NumDirectoryBytes;

-    ulittle32_t Unknown;

-    ulittle32_t BlockMapAddr;

-  };

-

-- **FileMagic** - Must be equal to ``"Microsoft C / C++ MSF 7.00\\r\\n"``

-  followed by the bytes ``1A 44 53 00 00 00``.

-- **BlockSize** - The block size of the internal file system.  Valid values are

-  512, 1024, 2048, and 4096 bytes.  Certain aspects of the MSF file layout vary

-  depending on the block sizes.  For the purposes of LLVM, we handle only block

-  sizes of 4KiB, and all further discussion assumes a block size of 4KiB.

-- **FreeBlockMapBlock** - The index of a block within the file, at which begins

-  a bitfield representing the set of all blocks within the file which are "free"

-  (i.e. the data within that block is not used).  See :ref:`msf_freeblockmap` for

-  more information.

-  **Important**: ``FreeBlockMapBlock`` can only be ``1`` or ``2``!

-- **NumBlocks** - The total number of blocks in the file.  ``NumBlocks * BlockSize``

-  should equal the size of the file on disk.

-- **NumDirectoryBytes** - The size of the stream directory, in bytes.  The stream

-  directory contains information about each stream's size and the set of blocks

-  that it occupies.  It will be described in more detail later.

-- **BlockMapAddr** - The index of a block within the MSF file.  At this block is

-  an array of ``ulittle32_t``'s listing the blocks that the stream directory

-  resides on.  For large MSF files, the stream directory (which describes the

-  block layout of each stream) may not fit entirely on a single block.  As a

-  result, this extra layer of indirection is introduced, whereby this block

-  contains the list of blocks that the stream directory occupies, and the stream

-  directory itself can be stitched together accordingly.  The number of

-  ``ulittle32_t``'s in this array is given by ``ceil(NumDirectoryBytes / BlockSize)``.

-

-.. _msf_freeblockmap:

-

-The Free Block Map

-==================

-

-The Free Block Map (sometimes referred to as the Free Page Map, or FPM) is a

-series of blocks which contains a bit flag for every block in the file. The

-flag will be set to 0 if the block is in use, and 1 if the block is unused.

-

-Each file contains two FPMs, one of which is active at any given time. This

-feature is designed to support incremental and atomic updates of the underlying

-MSF file. While writing to an MSF file, if the active FPM is FPM1, you can

-write your new modified bitfield to FPM2, and vice versa. Only when you commit

-the file to disk do you need to swap the value in the SuperBlock to point to

-the new ``FreeBlockMapBlock``.

-

-The Free Block Maps are stored as a series of single blocks thoughout the file

-at intervals of BlockSize. Because each FPM block is of size ``BlockSize``

-bytes, it contains 8 times as many bits as an interval has blocks. This means

-that the first block of each FPM refers to the first 8 intervals of the file

-(the first 32768 blocks), the second block of each FPM refers to the next 8

-blocks, and so on. This results in far more FPM blocks being present than are

-required, but in order to maintain backwards compatibility the format must stay

-this way.

-

-The Stream Directory

-====================

-The Stream Directory is the root of all access to the other streams in an MSF

-file.  Beginning at byte 0 of the stream directory is the following structure:

-

-.. code-block:: c++

-

-  struct StreamDirectory {

-    ulittle32_t NumStreams;

-    ulittle32_t StreamSizes[NumStreams];

-    ulittle32_t StreamBlocks[NumStreams][];

-  };

-

-And this structure occupies exactly ``SuperBlock->NumDirectoryBytes`` bytes.

-Note that each of the last two arrays is of variable length, and in particular

-that the second array is jagged.

-

-**Example:** Suppose a hypothetical PDB file with a 4KiB block size, and 4

-streams of lengths {1000 bytes, 8000 bytes, 16000 bytes, 9000 bytes}.

-

-Stream 0: ceil(1000 / 4096) = 1 block

-

-Stream 1: ceil(8000 / 4096) = 2 blocks

-

-Stream 2: ceil(16000 / 4096) = 4 blocks

-

-Stream 3: ceil(9000 / 4096) = 3 blocks

-

-In total, 10 blocks are used.  Let's see what the stream directory might look

-like:

-

-.. code-block:: c++

-

-  struct StreamDirectory {

-    ulittle32_t NumStreams = 4;

-    ulittle32_t StreamSizes[] = {1000, 8000, 16000, 9000};

-    ulittle32_t StreamBlocks[][] = {

-      {4},

-      {5, 6},

-      {11, 9, 7, 8},

-      {10, 15, 12}

-    };

-  };

-

-In total, this occupies ``15 * 4 = 60`` bytes, so ``SuperBlock->NumDirectoryBytes``

-would equal ``60``, and ``SuperBlock->BlockMapAddr`` would be an array of one

-``ulittle32_t``, since ``60 <= SuperBlock->BlockSize``.

-

-Note also that the streams are discontiguous, and that part of stream 3 is in the

-middle of part of stream 2.  You cannot assume anything about the layout of the

-blocks!

-

-Alignment and Block Boundaries

-==============================

-As may be clear by now, it is possible for a single field (whether it be a high

-level record, a long string field, or even a single ``uint16``) to begin and

-end in separate blocks.  For example, if the block size is 4096 bytes, and a

-``uint16`` field begins at the last byte of the current block, then it would

-need to end on the first byte of the next block.  Since blocks are not

-necessarily contiguously laid out in the file, this means that both the consumer

-and the producer of an MSF file must be prepared to split data apart

-accordingly.  In the aforementioned example, the high byte of the ``uint16``

-would be written to the last byte of block N, and the low byte would be written

-to the first byte of block N+1, which could be tens of thousands of bytes later

-(or even earlier!) in the file, depending on what the stream directory says.

+=====================================
+The MSF File Format
+=====================================
+
+.. contents::
+   :local:
+
+.. _msf_layout:
+
+File Layout
+===========
+
+The MSF file format consists of the following components:
+
+1. :ref:`msf_superblock`
+2. :ref:`msf_freeblockmap` (also know as Free Page Map, or FPM)
+3. Data
+
+Each component is stored as an indexed block, the length of which is specified
+in ``SuperBlock::BlockSize``. The file consists of 1 or more iterations of the
+following pattern (sometimes referred to as an "interval"):
+
+1. 1 block of data
+2. Free Block Map 1 (corresponds to ``SuperBlock::FreeBlockMapBlock`` 1)
+3. Free Block Map 2 (corresponds to ``SuperBlock::FreeBlockMapBlock`` 2)
+4. ``SuperBlock::BlockSize - 3`` blocks of data
+
+In the first interval, the first data block is used to store
+:ref:`msf_superblock`.
+
+The following diagram demonstrates the general layout of the file (\| denotes
+the end of an interval, and is for visualization purposes only):
+
++-------------+-----------------------+------------------+------------------+----------+----+------+------+------+-------------+----+-----+
+| Block Index | 0                     | 1                | 2                | 3 - 4095 | \| | 4096 | 4097 | 4098 | 4099 - 8191 | \| | ... |
++=============+=======================+==================+==================+==========+====+======+======+======+=============+====+=====+
+| Meaning     | :ref:`msf_superblock` | Free Block Map 1 | Free Block Map 2 | Data     | \| | Data | FPM1 | FPM2 | Data        | \| | ... |
++-------------+-----------------------+------------------+------------------+----------+----+------+------+------+-------------+----+-----+
+
+The file may end after any block, including immediately after a FPM1.
+
+.. note::
+  LLVM only supports 4096 byte blocks (sometimes referred to as the "BigMsf"
+  variant), so the rest of this document will assume a block size of 4096.
+
+.. _msf_superblock:
+
+The Superblock
+==============
+At file offset 0 in an MSF file is the MSF *SuperBlock*, which is laid out as
+follows:
+
+.. code-block:: c++
+
+  struct SuperBlock {
+    char FileMagic[sizeof(Magic)];
+    ulittle32_t BlockSize;
+    ulittle32_t FreeBlockMapBlock;
+    ulittle32_t NumBlocks;
+    ulittle32_t NumDirectoryBytes;
+    ulittle32_t Unknown;
+    ulittle32_t BlockMapAddr;
+  };
+
+- **FileMagic** - Must be equal to ``"Microsoft C / C++ MSF 7.00\\r\\n"``
+  followed by the bytes ``1A 44 53 00 00 00``.
+- **BlockSize** - The block size of the internal file system.  Valid values are
+  512, 1024, 2048, and 4096 bytes.  Certain aspects of the MSF file layout vary
+  depending on the block sizes.  For the purposes of LLVM, we handle only block
+  sizes of 4KiB, and all further discussion assumes a block size of 4KiB.
+- **FreeBlockMapBlock** - The index of a block within the file, at which begins
+  a bitfield representing the set of all blocks within the file which are "free"
+  (i.e. the data within that block is not used).  See :ref:`msf_freeblockmap` for
+  more information.
+  **Important**: ``FreeBlockMapBlock`` can only be ``1`` or ``2``!
+- **NumBlocks** - The total number of blocks in the file.  ``NumBlocks * BlockSize``
+  should equal the size of the file on disk.
+- **NumDirectoryBytes** - The size of the stream directory, in bytes.  The stream
+  directory contains information about each stream's size and the set of blocks
+  that it occupies.  It will be described in more detail later.
+- **BlockMapAddr** - The index of a block within the MSF file.  At this block is
+  an array of ``ulittle32_t``'s listing the blocks that the stream directory
+  resides on.  For large MSF files, the stream directory (which describes the
+  block layout of each stream) may not fit entirely on a single block.  As a
+  result, this extra layer of indirection is introduced, whereby this block
+  contains the list of blocks that the stream directory occupies, and the stream
+  directory itself can be stitched together accordingly.  The number of
+  ``ulittle32_t``'s in this array is given by ``ceil(NumDirectoryBytes / BlockSize)``.
+
+.. _msf_freeblockmap:
+
+The Free Block Map
+==================
+
+The Free Block Map (sometimes referred to as the Free Page Map, or FPM) is a
+series of blocks which contains a bit flag for every block in the file. The
+flag will be set to 0 if the block is in use, and 1 if the block is unused.
+
+Each file contains two FPMs, one of which is active at any given time. This
+feature is designed to support incremental and atomic updates of the underlying
+MSF file. While writing to an MSF file, if the active FPM is FPM1, you can
+write your new modified bitfield to FPM2, and vice versa. Only when you commit
+the file to disk do you need to swap the value in the SuperBlock to point to
+the new ``FreeBlockMapBlock``.
+
+The Free Block Maps are stored as a series of single blocks thoughout the file
+at intervals of BlockSize. Because each FPM block is of size ``BlockSize``
+bytes, it contains 8 times as many bits as an interval has blocks. This means
+that the first block of each FPM refers to the first 8 intervals of the file
+(the first 32768 blocks), the second block of each FPM refers to the next 8
+blocks, and so on. This results in far more FPM blocks being present than are
+required, but in order to maintain backwards compatibility the format must stay
+this way.
+
+The Stream Directory
+====================
+The Stream Directory is the root of all access to the other streams in an MSF
+file.  Beginning at byte 0 of the stream directory is the following structure:
+
+.. code-block:: c++
+
+  struct StreamDirectory {
+    ulittle32_t NumStreams;
+    ulittle32_t StreamSizes[NumStreams];
+    ulittle32_t StreamBlocks[NumStreams][];
+  };
+
+And this structure occupies exactly ``SuperBlock->NumDirectoryBytes`` bytes.
+Note that each of the last two arrays is of variable length, and in particular
+that the second array is jagged.
+
+**Example:** Suppose a hypothetical PDB file with a 4KiB block size, and 4
+streams of lengths {1000 bytes, 8000 bytes, 16000 bytes, 9000 bytes}.
+
+Stream 0: ceil(1000 / 4096) = 1 block
+
+Stream 1: ceil(8000 / 4096) = 2 blocks
+
+Stream 2: ceil(16000 / 4096) = 4 blocks
+
+Stream 3: ceil(9000 / 4096) = 3 blocks
+
+In total, 10 blocks are used.  Let's see what the stream directory might look
+like:
+
+.. code-block:: c++
+
+  struct StreamDirectory {
+    ulittle32_t NumStreams = 4;
+    ulittle32_t StreamSizes[] = {1000, 8000, 16000, 9000};
+    ulittle32_t StreamBlocks[][] = {
+      {4},
+      {5, 6},
+      {11, 9, 7, 8},
+      {10, 15, 12}
+    };
+  };
+
+In total, this occupies ``15 * 4 = 60`` bytes, so ``SuperBlock->NumDirectoryBytes``
+would equal ``60``, and ``SuperBlock->BlockMapAddr`` would be an array of one
+``ulittle32_t``, since ``60 <= SuperBlock->BlockSize``.
+
+Note also that the streams are discontiguous, and that part of stream 3 is in the
+middle of part of stream 2.  You cannot assume anything about the layout of the
+blocks!
+
+Alignment and Block Boundaries
+==============================
+As may be clear by now, it is possible for a single field (whether it be a high
+level record, a long string field, or even a single ``uint16``) to begin and
+end in separate blocks.  For example, if the block size is 4096 bytes, and a
+``uint16`` field begins at the last byte of the current block, then it would
+need to end on the first byte of the next block.  Since blocks are not
+necessarily contiguously laid out in the file, this means that both the consumer
+and the producer of an MSF file must be prepared to split data apart
+accordingly.  In the aforementioned example, the high byte of the ``uint16``
+would be written to the last byte of block N, and the low byte would be written
+to the first byte of block N+1, which could be tens of thousands of bytes later
+(or even earlier!) in the file, depending on what the stream directory says.
diff --git a/docs/PDB/PdbStream.rst b/docs/PDB/PdbStream.rst
index 0f9e071..40de9b7 100644
--- a/docs/PDB/PdbStream.rst
+++ b/docs/PDB/PdbStream.rst
@@ -58,6 +58,80 @@
   `UuidCreate <https://msdn.microsoft.com/en-us/library/windows/desktop/aa379205(v=vs.85).aspx>`__,
   although LLVM cannot rely on that, as it must work on non-Windows platforms.
   
+.. _pdb_named_stream_map:
+
+Named Stream Map
+================
+
+Following the header is a serialized hash table whose key type is a string, and
+whose value type is an integer.  The existence of a mapping ``X -> Y`` means
+that the stream with the name ``X`` has stream index ``Y`` in the underlying MSF
+file.  Note that not all streams are named (for example, the 
+:doc:`TPI Stream <TpiStream>` has a fixed index and as such there is no need to
+look up its index by name).  In practice, there are usually only a small number
+of named streams and these are enumerated in the table of streams in :doc:`index`.
+A corollary of this is if a stream does have a name (and as such is in the named
+stream map) then consulting the Named Stream Map is likely to be the only way to
+discover the stream's MSF stream index.  Several important streams (such as the
+global string table, which is called ``/names``) can only be located this way, and
+so it is important to both produce and consume this correctly as tools will not
+function correctly without it.
+
+.. important::
+   Some streams are located by fixed indices (e.g TPI Stream has index 2), but
+   other streams are located by fixed names (e.g. the string table is called
+   ``/names``) and can only be located by consulting the Named Stream Map.
+
+The on-disk layout of the Named Stream Map consists of 2 components.  The first is
+a buffer of string data prefixed by a 32-bit length.  The second is a serialized
+hash table whose key and value types are both ``uint32_t``.  The key is the offset
+of a null-terminated string in the string data buffer specifying the name of the
+stream, and the value is the MSF stream index of the stream with said name. 
+Note that although the key is an integer, the hash function used to find the right
+bucket hashes the string at the corresponding offset in the string data buffer.
+
+The on-disk layout of the serialized hash table is described at :doc:`HashTable`.
+
+Note that the entire Named Stream Map is not length-prefixed, so the only way to
+get to the data following it is to de-serialize it in its entirety.
+
+  
+.. _pdb_stream_features:
+
+PDB Feature Codes
+=================
+Following the Named Stream Map, and consuming all remaining bytes of the PDB
+Stream is a list of values from the following enumeration:
+
+.. code-block:: c++
+
+  enum class PdbRaw_FeatureSig : uint32_t {
+    VC110 = 20091201,
+    VC140 = 20140508,
+    NoTypeMerge = 0x4D544F4E,
+    MinimalDebugInfo = 0x494E494D,
+  };
+  
+The meaning of these values is summarized by the following table:
+
++------------------+-------------------------------------------------+
+| Flag             | Meaning                                         |
++==================+=================================================+
+| VC110            | - No other features flags are present           |
+|                  | - PDB contains an :doc:`IPI Stream <TpiStream>` |
++------------------+-------------------------------------------------+
+| VC140            | - Other feature flags may be present            |
+|                  | - PDB contains an :doc:`IPI Stream <TpiStream>` |
++------------------+-------------------------------------------------+
+| NoTypeMerge      | - Presumably duplicate types can appear in the  |
+|                  |   TPI Stream, although it's unclear why this    |
+|                  |   might happen.                                 |
++------------------+-------------------------------------------------+
+| MinimalDebugInfo | - Program was linked with /DEBUG:FASTLINK       |
+|                  | - There is no TPI / IPI stream, all type info   |
+|                  |   is contained in the original object files.    |
++------------------+-------------------------------------------------+
+  
 Matching a PDB to its executable
 ================================
 The linker is responsible for writing both the PDB and the final executable, and
diff --git a/docs/PDB/PublicStream.rst b/docs/PDB/PublicStream.rst
index 5b413cf..7c860c2 100644
--- a/docs/PDB/PublicStream.rst
+++ b/docs/PDB/PublicStream.rst
@@ -1,3 +1,3 @@
-=====================================

-The PDB Public Symbol Stream

-=====================================

+=====================================
+The PDB Public Symbol Stream
+=====================================
diff --git a/docs/PDB/TpiStream.rst b/docs/PDB/TpiStream.rst
index 1e3297e..8f6fd12 100644
--- a/docs/PDB/TpiStream.rst
+++ b/docs/PDB/TpiStream.rst
@@ -1,3 +1,312 @@
-=====================================

-The PDB TPI Stream

-=====================================

+=====================================
+The PDB TPI and IPI Streams
+=====================================
+
+.. contents::
+   :local:
+
+.. _tpi_intro:
+
+Introduction
+============
+
+The PDB TPI Stream (Index 2) and IPI Stream (Index 4) contain information about
+all types used in the program.  It is organized as a :ref:`header <tpi_header>`
+followed by a list of :doc:`CodeView Type Records <CodeViewTypes>`.  Types are
+referenced from various streams and records throughout the PDB by their
+:ref:`type index <type_indices>`.  In general, the sequence of type records
+following the :ref:`header <tpi_header>` forms a topologically sorted DAG
+(directed acyclic graph), which means that a type record B can only refer to
+the type A if ``A.TypeIndex < B.TypeIndex``.  While there are rare cases where
+this property will not hold (particularly when dealing with object files
+compiled with MASM), an implementation should try very hard to make this
+property hold, as it means the entire type graph can be constructed in a single
+pass.
+
+.. important::
+   Type records form a topologically sorted DAG (directed acyclic graph).
+   
+.. _tpi_ipi:
+
+TPI vs IPI Stream
+=================
+
+Recent versions of the PDB format (aka all versions covered by this document)
+have 2 streams with identical layout, henceforth referred to as the TPI stream
+and IPI stream.  Subsequent contents of this document describing the on-disk
+format apply equally whether it is for the TPI Stream or the IPI Stream.  The
+only difference between the two is in *which* CodeView records are allowed to
+appear in each one, summarized by the following table:
+
++----------------------+---------------------+
+|    TPI Stream        |    IPI Stream       |
++======================+=====================+
+|  LF_POINTER          | LF_FUNC_ID          |
++----------------------+---------------------+
+|  LF_MODIFIER         | LF_MFUNC_ID         |
++----------------------+---------------------+
+|  LF_PROCEDURE        | LF_BUILDINFO        |
++----------------------+---------------------+
+|  LF_MFUNCTION        | LF_SUBSTR_LIST      |
++----------------------+---------------------+
+|  LF_LABEL            | LF_STRING_ID        |
++----------------------+---------------------+
+|  LF_ARGLIST          | LF_UDT_SRC_LINE     |
++----------------------+---------------------+
+|  LF_FIELDLIST        | LF_UDT_MOD_SRC_LINE |
++----------------------+---------------------+
+|  LF_ARRAY            |                     |
++----------------------+---------------------+
+|  LF_CLASS            |                     |
++----------------------+---------------------+
+|  LF_STRUCTURE        |                     |
++----------------------+---------------------+
+|  LF_INTERFACE        |                     |
++----------------------+---------------------+
+|  LF_UNION            |                     |
++----------------------+---------------------+
+|  LF_ENUM             |                     |
++----------------------+---------------------+
+|  LF_TYPESERVER2      |                     |
++----------------------+---------------------+
+|  LF_VFTABLE          |                     |
++----------------------+---------------------+
+|  LF_VTSHAPE          |                     |
++----------------------+---------------------+
+|  LF_BITFIELD         |                     |
++----------------------+---------------------+
+|  LF_METHODLIST       |                     |
++----------------------+---------------------+
+|  LF_PRECOMP          |                     |
++----------------------+---------------------+
+|  LF_ENDPRECOMP       |                     |
++----------------------+---------------------+
+
+The usage of these records is described in more detail in
+:doc:`CodeView Type Records <CodeViewTypes>`.
+
+.. _type_indices:
+
+Type Indices
+============
+
+A type index is a 32-bit integer that uniquely identifies a type inside of an
+object file's ``.debug$T`` section or a PDB file's TPI or IPI stream.  The
+value of the type index for the first type record from the TPI stream is given
+by the ``TypeIndexBegin`` member of the :ref:`TPI Stream Header <tpi_header>`
+although in practice this value is always equal to 0x1000 (4096).
+
+Any type index with a high bit set is considered to come from the IPI stream,
+although this appears to be more of a hack, and LLVM does not generate type
+indices of this nature.  They can, however, be observed in Microsoft PDBs
+occasionally, so one should be prepared to handle them.  Note that having the
+high bit set is not a necessary condition to determine whether a type index
+comes from the IPI stream, it is only sufficient.
+
+Once the high bit is cleared, any type index >= ``TypeIndexBegin`` is presumed
+to come from the appropriate stream, and any type index less than this is a
+bitmask which can be decomposed as follows:
+
+.. code-block:: none
+
+  .---------------------------.------.----------.
+  |           Unused          | Mode |   Kind   |
+  '---------------------------'------'----------'
+  |+32                        |+12   |+8        |+0
+
+
+- **Kind** - A value from the following enum:
+
+.. code-block:: c++
+
+  enum class SimpleTypeKind : uint32_t {
+    None = 0x0000,          // uncharacterized type (no type)
+    Void = 0x0003,          // void
+    NotTranslated = 0x0007, // type not translated by cvpack
+    HResult = 0x0008,       // OLE/COM HRESULT
+
+    SignedCharacter = 0x0010,   // 8 bit signed
+    UnsignedCharacter = 0x0020, // 8 bit unsigned
+    NarrowCharacter = 0x0070,   // really a char
+    WideCharacter = 0x0071,     // wide char
+    Character16 = 0x007a,       // char16_t
+    Character32 = 0x007b,       // char32_t
+
+    SByte = 0x0068,       // 8 bit signed int
+    Byte = 0x0069,        // 8 bit unsigned int
+    Int16Short = 0x0011,  // 16 bit signed
+    UInt16Short = 0x0021, // 16 bit unsigned
+    Int16 = 0x0072,       // 16 bit signed int
+    UInt16 = 0x0073,      // 16 bit unsigned int
+    Int32Long = 0x0012,   // 32 bit signed
+    UInt32Long = 0x0022,  // 32 bit unsigned
+    Int32 = 0x0074,       // 32 bit signed int
+    UInt32 = 0x0075,      // 32 bit unsigned int
+    Int64Quad = 0x0013,   // 64 bit signed
+    UInt64Quad = 0x0023,  // 64 bit unsigned
+    Int64 = 0x0076,       // 64 bit signed int
+    UInt64 = 0x0077,      // 64 bit unsigned int
+    Int128Oct = 0x0014,   // 128 bit signed int
+    UInt128Oct = 0x0024,  // 128 bit unsigned int
+    Int128 = 0x0078,      // 128 bit signed int
+    UInt128 = 0x0079,     // 128 bit unsigned int
+
+    Float16 = 0x0046,                 // 16 bit real
+    Float32 = 0x0040,                 // 32 bit real
+    Float32PartialPrecision = 0x0045, // 32 bit PP real
+    Float48 = 0x0044,                 // 48 bit real
+    Float64 = 0x0041,                 // 64 bit real
+    Float80 = 0x0042,                 // 80 bit real
+    Float128 = 0x0043,                // 128 bit real
+
+    Complex16 = 0x0056,                 // 16 bit complex
+    Complex32 = 0x0050,                 // 32 bit complex
+    Complex32PartialPrecision = 0x0055, // 32 bit PP complex
+    Complex48 = 0x0054,                 // 48 bit complex
+    Complex64 = 0x0051,                 // 64 bit complex
+    Complex80 = 0x0052,                 // 80 bit complex
+    Complex128 = 0x0053,                // 128 bit complex
+
+    Boolean8 = 0x0030,   // 8 bit boolean
+    Boolean16 = 0x0031,  // 16 bit boolean
+    Boolean32 = 0x0032,  // 32 bit boolean
+    Boolean64 = 0x0033,  // 64 bit boolean
+    Boolean128 = 0x0034, // 128 bit boolean
+  };
+
+- **Mode** - A value from the following enum:
+
+.. code-block:: c++
+
+  enum class SimpleTypeMode : uint32_t {
+    Direct = 0,        // Not a pointer
+    NearPointer = 1,   // Near pointer
+    FarPointer = 2,    // Far pointer
+    HugePointer = 3,   // Huge pointer
+    NearPointer32 = 4, // 32 bit near pointer
+    FarPointer32 = 5,  // 32 bit far pointer
+    NearPointer64 = 6, // 64 bit near pointer
+    NearPointer128 = 7 // 128 bit near pointer
+  };
+  
+Note that for pointers, the bitness is represented in the mode.  So a ``void*``
+would have a type index with ``Mode=NearPointer32, Kind=Void`` if built for 32-bits
+but a type index with ``Mode=NearPointer64, Kind=Void`` if built for 64-bits.
+
+By convention, the type index for ``std::nullptr_t`` is constructed the same way
+as the type index for ``void*``, but using the bitless enumeration value
+``NearPointer``.
+
+
+
+.. _tpi_header:
+
+Stream Header
+=============
+At offset 0 of the TPI Stream is a header with the following layout:
+
+
+.. code-block:: c++
+
+  struct TpiStreamHeader {
+    uint32_t Version;
+    uint32_t HeaderSize;
+    uint32_t TypeIndexBegin;
+    uint32_t TypeIndexEnd;
+    uint32_t TypeRecordBytes;
+
+    uint16_t HashStreamIndex;
+    uint16_t HashAuxStreamIndex;
+    uint32_t HashKeySize;
+    uint32_t NumHashBuckets;
+
+    int32_t HashValueBufferOffset;
+    uint32_t HashValueBufferLength;
+    
+    int32_t IndexOffsetBufferOffset;
+    uint32_t IndexOffsetBufferLength;
+
+    int32_t HashAdjBufferOffset;
+    uint32_t HashAdjBufferLength;
+  };
+  
+- **Version** - A value from the following enum.
+
+.. code-block:: c++
+
+  enum class TpiStreamVersion : uint32_t {
+    V40 = 19950410,
+    V41 = 19951122,
+    V50 = 19961031,
+    V70 = 19990903,
+    V80 = 20040203,
+  };
+
+Similar to the :doc:`PDB Stream <PdbStream>`, this value always appears to be
+``V80``, and no other values have been observed.  It is assumed that should
+another value be observed, the layout described by this document may not be
+accurate.
+
+- **HeaderSize** - ``sizeof(TpiStreamHeader)``
+  
+- **TypeIndexBegin** - The numeric value of the type index representing the
+  first type record in the TPI stream.  This is usually the value 0x1000 as type
+  indices lower than this are reserved (see :ref:`Type Indices <type_indices>` for
+  a discussion of reserved type indices).
+  
+- **TypeIndexEnd** - One greater than the numeric value of the type index
+  representing the last type record in the TPI stream.  The total number of type
+  records in the TPI stream can be computed as ``TypeIndexEnd - TypeIndexBegin``.
+  
+- **TypeRecordBytes** - The number of bytes of type record data following the header.
+  
+- **HashStreamIndex** - The index of a stream which contains a list of hashes for
+  every type record.  This value may be -1, indicating that hash information is not
+  present.  In practice a valid stream index is always observed, so any producer
+  implementation should be prepared to emit this stream to ensure compatibility with
+  tools which may expect it to be present.
+  
+- **HashAuxStreamIndex** - Presumably the index of a stream which contains a separate
+  hash table, although this has not been observed in practice and it's unclear what it
+  might be used for.
+  
+- **HashKeySize** - The size of a hash value (usually 4 bytes).
+
+- **NumHashBuckets** - The number of buckets used to generate the hash values in the
+  aforementioned hash streams.
+
+- **HashValueBufferOffset / HashValueBufferLength** - The offset and size within
+  the TPI Hash Stream of the list of hash values.  It should be assumed that there
+  are either 0 hash values, or a number equal to the number of type records in the
+  TPI stream (``TypeIndexEnd - TypeEndBegin``).  Thus, if ``HashBufferLength`` is
+  not equal to ``(TypeIndexEnd - TypeEndBegin) * HashKeySize`` we can consider the
+  PDB malformed.
+
+- **IndexOffsetBufferOffset / IndexOffsetBufferLength** - The offset and size
+  within the TPI Hash Stream of the Type Index Offsets Buffer.  This is a list of
+  pairs of uint32_t's where the first value is a :ref:`Type Index <type_indices>`
+  and the second value is the offset in the type record data of the type with this
+  index.  This can be used to do a binary search followed by a linear search to
+  get O(log n) lookup by type index.
+
+- **HashAdjBufferOffset / HashAdjBufferLength** - The offset and size within
+  the TPI hash stream of a serialized hash table whose keys are the hash values
+  in the hash value buffer and whose values are type indices.  This appears to
+  be useful in incremental linking scenarios, so that if a type is modified an
+  entry can be created mapping the old hash value to the new type index so that
+  a PDB file consumer can always have the most up to date version of the type
+  without forcing the incremental linker to garbage collect and update
+  references that point to the old version to now point to the new version.
+  The layout of this hash table is described in :doc:`HashTable`.
+
+.. _tpi_records:
+
+CodeView Type Record List
+=========================
+Following the header, there are ``TypeRecordBytes`` bytes of data that represent a
+variable length array of :doc:`CodeView type records <CodeViewTypes>`.  The number
+of such records (e.g. the length of the array) can be determined by computing the
+value ``Header.TypeIndexEnd - Header.TypeIndexBegin``.
+
+O(log(n)) access is provided by way of the Type Index Offsets array (if
+present) described previously.
diff --git a/docs/PDB/index.rst b/docs/PDB/index.rst
index 5300588..8425b29 100644
--- a/docs/PDB/index.rst
+++ b/docs/PDB/index.rst
@@ -1,167 +1,167 @@
-=====================================

-The PDB File Format

-=====================================

-

-.. contents::

-   :local:

-

-.. _pdb_intro:

-

-Introduction

-============

-

-PDB (Program Database) is a file format invented by Microsoft and which contains

-debug information that can be consumed by debuggers and other tools.  Since

-officially supported APIs exist on Windows for querying debug information from

-PDBs even without the user understanding the internals of the file format, a

-large ecosystem of tools has been built for Windows to consume this format.  In

-order for Clang to be able to generate programs that can interoperate with these

-tools, it is necessary for us to generate PDB files ourselves.

-

-At the same time, LLVM has a long history of being able to cross-compile from

-any platform to any platform, and we wish for the same to be true here.  So it

-is necessary for us to understand the PDB file format at the byte-level so that

-we can generate PDB files entirely on our own.

-

-This manual describes what we know about the PDB file format today.  The layout

-of the file, the various streams contained within, the format of individual

-records within, and more.

-

-We would like to extend our heartfelt gratitude to Microsoft, without whom we

-would not be where we are today.  Much of the knowledge contained within this

-manual was learned through reading code published by Microsoft on their `GitHub

-repo <https://github.com/Microsoft/microsoft-pdb>`__.

-

-.. _pdb_layout:

-

-File Layout

-===========

-

-.. important::

-   Unless otherwise specified, all numeric values are encoded in little endian.

-   If you see a type such as ``uint16_t`` or ``uint64_t`` going forward, always

-   assume it is little endian!

-

-.. toctree::

-   :hidden:

-   

-   MsfFile

-   PdbStream

-   TpiStream

-   DbiStream

-   ModiStream

-   PublicStream

-   GlobalStream

-   HashStream

-   CodeViewSymbols

-   CodeViewTypes

-

-.. _msf:

-

-The MSF Container

------------------

-A PDB file is really just a special case of an MSF (Multi-Stream Format) file.

-An MSF file is actually a miniature "file system within a file".  It contains

-multiple streams (aka files) which can represent arbitrary data, and these

-streams are divided into blocks which may not necessarily be contiguously

-laid out within the file (aka fragmented).  Additionally, the MSF contains a

-stream directory (aka MFT) which describes how the streams (files) are laid

-out within the MSF.

-

-For more information about the MSF container format, stream directory, and

-block layout, see :doc:`MsfFile`.

-

-.. _streams:

-

-Streams

--------

-The PDB format contains a number of streams which describe various information

-such as the types, symbols, source files, and compilands (e.g. object files)

-of a program, as well as some additional streams containing hash tables that are

-used by debuggers and other tools to provide fast lookup of records and types

-by name, and various other information about how the program was compiled such

-as the specific toolchain used, and more.  A summary of streams contained in a

-PDB file is as follows:

-

-+--------------------+------------------------------+-------------------------------------------+

-| Name               | Stream Index                 | Contents                                  |

-+====================+==============================+===========================================+

-| Old Directory      | - Fixed Stream Index 0       | - Previous MSF Stream Directory           |

-+--------------------+------------------------------+-------------------------------------------+

-| PDB Stream         | - Fixed Stream Index 1       | - Basic File Information                  |

-|                    |                              | - Fields to match EXE to this PDB         |

-|                    |                              | - Map of named streams to stream indices  |

-+--------------------+------------------------------+-------------------------------------------+

-| TPI Stream         | - Fixed Stream Index 2       | - CodeView Type Records                   |

-|                    |                              | - Index of TPI Hash Stream                |

-+--------------------+------------------------------+-------------------------------------------+

-| DBI Stream         | - Fixed Stream Index 3       | - Module/Compiland Information            |

-|                    |                              | - Indices of individual module streams    |

-|                    |                              | - Indices of public / global streams      |

-|                    |                              | - Section Contribution Information        |

-|                    |                              | - Source File Information                 |

-|                    |                              | - FPO / PGO Data                          |

-+--------------------+------------------------------+-------------------------------------------+

-| IPI Stream         | - Fixed Stream Index 4       | - CodeView Type Records                   |

-|                    |                              | - Index of IPI Hash Stream                |

-+--------------------+------------------------------+-------------------------------------------+

-| /LinkInfo          | - Contained in PDB Stream    | - Unknown                                 |

-|                    |   Named Stream map           |                                           |

-+--------------------+------------------------------+-------------------------------------------+

-| /src/headerblock   | - Contained in PDB Stream    | - Unknown                                 |

-|                    |   Named Stream map           |                                           |

-+--------------------+------------------------------+-------------------------------------------+

-| /names             | - Contained in PDB Stream    | - PDB-wide global string table used for   |

-|                    |   Named Stream map           |   string de-duplication                   |

-+--------------------+------------------------------+-------------------------------------------+

-| Module Info Stream | - Contained in DBI Stream    | - CodeView Symbol Records for this module |

-|                    | - One for each compiland     | - Line Number Information                 |

-+--------------------+------------------------------+-------------------------------------------+

-| Public Stream      | - Contained in DBI Stream    | - Public (Exported) Symbol Records        |

-|                    |                              | - Index of Public Hash Stream             |

-+--------------------+------------------------------+-------------------------------------------+

-| Global Stream      | - Contained in DBI Stream    | - Global Symbol Records                   |

-|                    |                              | - Index of Global Hash Stream             |

-+--------------------+------------------------------+-------------------------------------------+

-| TPI Hash Stream    | - Contained in TPI Stream    | - Hash table for looking up TPI records   |

-|                    |                              |   by name                                 |

-+--------------------+------------------------------+-------------------------------------------+

-| IPI Hash Stream    | - Contained in IPI Stream    | - Hash table for looking up IPI records   |

-|                    |                              |   by name                                 |

-+--------------------+------------------------------+-------------------------------------------+

-

-More information about the structure of each of these can be found on the

-following pages:

-   

-:doc:`PdbStream`

-   Information about the PDB Info Stream and how it is used to match PDBs to EXEs.

-

-:doc:`TpiStream`

-   Information about the TPI stream and the CodeView records contained within.

-

-:doc:`DbiStream`

-   Information about the DBI stream and relevant substreams including the Module Substreams,

-   source file information, and CodeView symbol records contained within.

-

-:doc:`ModiStream`

-   Information about the Module Information Stream, of which there is one for each compilation

-   unit and the format of symbols contained within.

-

-:doc:`PublicStream`

-   Information about the Public Symbol Stream.

-

-:doc:`GlobalStream`

-   Information about the Global Symbol Stream.

-

-:doc:`HashStream`

-   Information about the Hash Table stream, and how it can be used to quickly look up records

-   by name.

-

-CodeView

-========

-CodeView is another format which comes into the picture.  While MSF defines

-the structure of the overall file, and PDB defines the set of streams that

-appear within the MSF file and the format of those streams, CodeView defines

-the format of **symbol and type records** that appear within specific streams.

-Refer to the pages on :doc:`CodeViewSymbols` and :doc:`CodeViewTypes` for

-more information about the CodeView format.

+=====================================
+The PDB File Format
+=====================================
+
+.. contents::
+   :local:
+
+.. _pdb_intro:
+
+Introduction
+============
+
+PDB (Program Database) is a file format invented by Microsoft and which contains
+debug information that can be consumed by debuggers and other tools.  Since
+officially supported APIs exist on Windows for querying debug information from
+PDBs even without the user understanding the internals of the file format, a
+large ecosystem of tools has been built for Windows to consume this format.  In
+order for Clang to be able to generate programs that can interoperate with these
+tools, it is necessary for us to generate PDB files ourselves.
+
+At the same time, LLVM has a long history of being able to cross-compile from
+any platform to any platform, and we wish for the same to be true here.  So it
+is necessary for us to understand the PDB file format at the byte-level so that
+we can generate PDB files entirely on our own.
+
+This manual describes what we know about the PDB file format today.  The layout
+of the file, the various streams contained within, the format of individual
+records within, and more.
+
+We would like to extend our heartfelt gratitude to Microsoft, without whom we
+would not be where we are today.  Much of the knowledge contained within this
+manual was learned through reading code published by Microsoft on their `GitHub
+repo <https://github.com/Microsoft/microsoft-pdb>`__.
+
+.. _pdb_layout:
+
+File Layout
+===========
+
+.. important::
+   Unless otherwise specified, all numeric values are encoded in little endian.
+   If you see a type such as ``uint16_t`` or ``uint64_t`` going forward, always
+   assume it is little endian!
+
+.. toctree::
+   :hidden:
+   
+   MsfFile
+   PdbStream
+   TpiStream
+   DbiStream
+   ModiStream
+   PublicStream
+   GlobalStream
+   HashTable
+   CodeViewSymbols
+   CodeViewTypes
+
+.. _msf:
+
+The MSF Container
+-----------------
+A PDB file is an MSF (Multi-Stream Format) file.  An MSF file is a "file system
+within a file".  It contains multiple streams (aka files) which can represent
+arbitrary data, and these streams are divided into blocks which may not
+necessarily be contiguously laid out within the MSF container file.
+Additionally, the MSF contains a stream directory (aka MFT) which describes how
+the streams (files) are laid out within the MSF.
+
+For more information about the MSF container format, stream directory, and
+block layout, see :doc:`MsfFile`.
+
+.. _streams:
+
+Streams
+-------
+The PDB format contains a number of streams which describe various information
+such as the types, symbols, source files, and compilands (e.g. object files)
+of a program, as well as some additional streams containing hash tables that are
+used by debuggers and other tools to provide fast lookup of records and types
+by name, and various other information about how the program was compiled such
+as the specific toolchain used, and more.  A summary of streams contained in a
+PDB file is as follows:
+
++--------------------+------------------------------+-------------------------------------------+
+| Name               | Stream Index                 | Contents                                  |
++====================+==============================+===========================================+
+| Old Directory      | - Fixed Stream Index 0       | - Previous MSF Stream Directory           |
++--------------------+------------------------------+-------------------------------------------+
+| PDB Stream         | - Fixed Stream Index 1       | - Basic File Information                  |
+|                    |                              | - Fields to match EXE to this PDB         |
+|                    |                              | - Map of named streams to stream indices  |
++--------------------+------------------------------+-------------------------------------------+
+| TPI Stream         | - Fixed Stream Index 2       | - CodeView Type Records                   |
+|                    |                              | - Index of TPI Hash Stream                |
++--------------------+------------------------------+-------------------------------------------+
+| DBI Stream         | - Fixed Stream Index 3       | - Module/Compiland Information            |
+|                    |                              | - Indices of individual module streams    |
+|                    |                              | - Indices of public / global streams      |
+|                    |                              | - Section Contribution Information        |
+|                    |                              | - Source File Information                 |
+|                    |                              | - References to streams containing        |
+|                    |                              |   FPO / PGO Data                          |
++--------------------+------------------------------+-------------------------------------------+
+| IPI Stream         | - Fixed Stream Index 4       | - CodeView Type Records                   |
+|                    |                              | - Index of IPI Hash Stream                |
++--------------------+------------------------------+-------------------------------------------+
+| /LinkInfo          | - Contained in PDB Stream    | - Unknown                                 |
+|                    |   Named Stream map           |                                           |
++--------------------+------------------------------+-------------------------------------------+
+| /src/headerblock   | - Contained in PDB Stream    | - Summary of embedded source file content |
+|                    |   Named Stream map           |   (e.g. natvis files)                     |
++--------------------+------------------------------+-------------------------------------------+
+| /names             | - Contained in PDB Stream    | - PDB-wide global string table used for   |
+|                    |   Named Stream map           |   string de-duplication                   |
++--------------------+------------------------------+-------------------------------------------+
+| Module Info Stream | - Contained in DBI Stream    | - CodeView Symbol Records for this module |
+|                    | - One for each compiland     | - Line Number Information                 |
++--------------------+------------------------------+-------------------------------------------+
+| Public Stream      | - Contained in DBI Stream    | - Public (Exported) Symbol Records        |
+|                    |                              | - Index of Public Hash Stream             |
++--------------------+------------------------------+-------------------------------------------+
+| Global Stream      | - Contained in DBI Stream    | - Single combined master symbol-table     |
+|                    |                              | - Index of Global Hash Stream             |
++--------------------+------------------------------+-------------------------------------------+
+| TPI Hash Stream    | - Contained in TPI Stream    | - Hash table for looking up TPI records   |
+|                    |                              |   by name                                 |
++--------------------+------------------------------+-------------------------------------------+
+| IPI Hash Stream    | - Contained in IPI Stream    | - Hash table for looking up IPI records   |
+|                    |                              |   by name                                 |
++--------------------+------------------------------+-------------------------------------------+
+
+More information about the structure of each of these can be found on the
+following pages:
+   
+:doc:`PdbStream`
+   Information about the PDB Info Stream and how it is used to match PDBs to EXEs.
+
+:doc:`TpiStream`
+   Information about the TPI stream and the CodeView records contained within.
+
+:doc:`DbiStream`
+   Information about the DBI stream and relevant substreams including the Module Substreams,
+   source file information, and CodeView symbol records contained within.
+
+:doc:`ModiStream`
+   Information about the Module Information Stream, of which there is one for each compilation
+   unit and the format of symbols contained within.
+
+:doc:`PublicStream`
+   Information about the Public Symbol Stream.
+
+:doc:`GlobalStream`
+   Information about the Global Symbol Stream.
+
+:doc:`HashTable`
+   Information about the serialized hash table format used internally to represent things such
+   as the Named Stream Map and the Hash Adjusters in the :doc:`TPI/IPI Stream <TpiStream>`.
+
+CodeView
+========
+CodeView is another format which comes into the picture.  While MSF defines
+the structure of the overall file, and PDB defines the set of streams that
+appear within the MSF file and the format of those streams, CodeView defines
+the format of **symbol and type records** that appear within specific streams.
+Refer to the pages on :doc:`CodeViewSymbols` and :doc:`CodeViewTypes` for
+more information about the CodeView format.
diff --git a/docs/ProgrammersManual.rst b/docs/ProgrammersManual.rst
index 0903a22..75b6239 100644
--- a/docs/ProgrammersManual.rst
+++ b/docs/ProgrammersManual.rst
@@ -164,6 +164,12 @@
   efficient to use the ``InstVisitor`` class to dispatch over the instruction
   type directly.
 
+``isa_and_nonnull<>``:
+  The ``isa_and_nonnull<>`` operator works just like the ``isa<>`` operator,
+  except that it allows for a null pointer as an argument (which it then
+  returns false).  This can sometimes be useful, allowing you to combine several
+  null checks into one.
+
 ``cast_or_null<>``:
   The ``cast_or_null<>`` operator works just like the ``cast<>`` operator,
   except that it allows for a null pointer as an argument (which it then
@@ -656,19 +662,21 @@
 environment. In this case representing the error as a string makes perfect
 sense. LLVM provides the ``StringError`` class for this purpose. It takes two
 arguments: A string error message, and an equivalent ``std::error_code`` for
-interoperability:
+interoperability. It also provides a ``createStringError`` function to simplify
+common usage of this class:
 
 .. code-block:: c++
 
-  make_error<StringError>("Bad executable",
-                          make_error_code(errc::executable_format_error"));
+  // These two lines of code are equivalent:
+  make_error<StringError>("Bad executable", errc::executable_format_error);
+  createStringError(errc::executable_format_error, "Bad executable");
 
 If you're certain that the error you're building will never need to be converted
 to a ``std::error_code`` you can use the ``inconvertibleErrorCode()`` function:
 
 .. code-block:: c++
 
-  make_error<StringError>("Bad executable", inconvertibleErrorCode());
+  createStringError(inconvertibleErrorCode(), "Bad executable");
 
 This should be done only after careful consideration. If any attempt is made to
 convert this error to a ``std::error_code`` it will trigger immediate program
@@ -677,6 +685,14 @@
 can convert to, and even (as painful as it is) consider introducing a new one as
 a stopgap measure.
 
+``createStringError`` can take ``printf`` style format specifiers to provide a
+formatted message:
+
+.. code-block:: c++
+
+  createStringError(errc::executable_format_error,
+                    "Bad executable: %s", FileName);
+
 Interoperability with std::error_code and ErrorOr
 """""""""""""""""""""""""""""""""""""""""""""""""
 
@@ -925,28 +941,86 @@
 
 The archive walking examples above retrieve archive members by index, however
 this requires considerable boiler-plate for iteration and error checking. We can
-clean this up by using ``Error`` with the "fallible iterator" pattern. The usual
-C++ iterator patterns do not allow for failure on increment, but we can
-incorporate support for it by having iterators hold an Error reference through
-which they can report failure. In this pattern, if an increment operation fails
-the failure is recorded via the Error reference and the iterator value is set to
-the end of the range in order to terminate the loop. This ensures that the
-dereference operation is safe anywhere that an ordinary iterator dereference
-would be safe (i.e. when the iterator is not equal to end). Where this pattern
-is followed (as in the ``llvm::object::Archive`` class) the result is much
-cleaner iteration idiom:
+clean this up by using the "fallible iterator" pattern, which supports the
+following natural iteration idiom for fallible containers like Archive:
 
 .. code-block:: c++
 
   Error Err;
   for (auto &Child : Ar->children(Err)) {
-    // Use Child - we only enter the loop when it's valid
+    // Use Child - only enter the loop when it's valid
+
+    // Allow early exit from the loop body, since we know that Err is success
+    // when we're inside the loop.
+    if (BailOutOn(Child))
+      return;
+
     ...
   }
   // Check Err after the loop to ensure it didn't break due to an error.
   if (Err)
     return Err;
 
+To enable this idiom, iterators over fallible containers are written in a
+natural style, with their ``++`` and ``--`` operators replaced with fallible
+``Error inc()`` and ``Error dec()`` functions. E.g.:
+
+.. code-block:: c++
+
+  class FallibleChildIterator {
+  public:
+    FallibleChildIterator(Archive &A, unsigned ChildIdx);
+    Archive::Child &operator*();
+    friend bool operator==(const ArchiveIterator &LHS,
+                           const ArchiveIterator &RHS);
+
+    // operator++/operator-- replaced with fallible increment / decrement:
+    Error inc() {
+      if (!A.childValid(ChildIdx + 1))
+        return make_error<BadArchiveMember>(...);
+      ++ChildIdx;
+      return Error::success();
+    }
+
+    Error dec() { ... }
+  };
+
+Instances of this kind of fallible iterator interface are then wrapped with the
+fallible_iterator utility which provides ``operator++`` and ``operator--``,
+returning any errors via a reference passed in to the wrapper at construction
+time. The fallible_iterator wrapper takes care of (a) jumping to the end of the
+range on error, and (b) marking the error as checked whenever an iterator is
+compared to ``end`` and found to be inequal (in particular: this marks the
+error as checked throughout the body of a range-based for loop), enabling early
+exit from the loop without redundant error checking.
+
+Instances of the fallible iterator interface (e.g. FallibleChildIterator above)
+are wrapped using the ``make_fallible_itr`` and ``make_fallible_end``
+functions. E.g.:
+
+.. code-block:: c++
+
+  class Archive {
+  public:
+    using child_iterator = fallible_iterator<FallibleChildIterator>;
+
+    child_iterator child_begin(Error &Err) {
+      return make_fallible_itr(FallibleChildIterator(*this, 0), Err);
+    }
+
+    child_iterator child_end() {
+      return make_fallible_end(FallibleChildIterator(*this, size()));
+    }
+
+    iterator_range<child_iterator> children(Error &Err) {
+      return make_range(child_begin(Err), child_end());
+    }
+  };
+
+Using the fallible_iterator utility allows for both natural construction of
+fallible iterators (using failing ``inc`` and ``dec`` operations) and
+relatively natural use of c++ iterator/loop idioms.
+
 .. _function_apis:
 
 More information on Error and its related utilities can be found in the
@@ -1456,7 +1530,7 @@
 #. std::vector is exception-safe, and some implementations have pessimizations
    that copy elements when SmallVector would move them.
 
-#. SmallVector understands ``isPodLike<Type>`` and uses realloc aggressively.
+#. SmallVector understands ``llvm::is_trivially_copyable<Type>`` and uses realloc aggressively.
 
 #. Many LLVM APIs take a SmallVectorImpl as an out parameter (see the note
    below).
@@ -2591,7 +2665,7 @@
 
 Frequently, we might have an instance of the ``Value`` class (`doxygen
 <http://llvm.org/doxygen/classllvm_1_1Value.html>`__) and we want to determine
-which ``User`` s use the ``Value``.  The list of all ``User``\ s of a particular
+which ``User``\ s use the ``Value``.  The list of all ``User``\ s of a particular
 ``Value`` is called a *def-use* chain.  For example, let's say we have a
 ``Function*`` named ``F`` to a particular function ``foo``.  Finding all of the
 instructions that *use* ``foo`` is as simple as iterating over the *def-use*
@@ -3491,11 +3565,17 @@
   Look up the specified function in the ``Module`` SymbolTable_.  If it does not
   exist, return ``null``.
 
-* ``Function *getOrInsertFunction(const std::string &Name, const FunctionType
-  *T)``
+* ``FunctionCallee getOrInsertFunction(const std::string &Name,
+  const FunctionType *T)``
 
-  Look up the specified function in the ``Module`` SymbolTable_.  If it does not
-  exist, add an external declaration for the function and return it.
+  Look up the specified function in the ``Module`` SymbolTable_.  If
+  it does not exist, add an external declaration for the function and
+  return it. Note that the function signature already present may not
+  match the requested signature. Thus, in order to enable the common
+  usage of passing the result directly to EmitCall, the return type is
+  a struct of ``{FunctionType *T, Constant *FunctionPtr}``, rather
+  than simply the ``Function*`` with potentially an unexpected
+  signature.
 
 * ``std::string getTypeName(const Type *Ty)``
 
diff --git a/docs/Proposals/GitHubMove.rst b/docs/Proposals/GitHubMove.rst
index f120775..83d2286 100644
--- a/docs/Proposals/GitHubMove.rst
+++ b/docs/Proposals/GitHubMove.rst
@@ -105,8 +105,7 @@
 all LLVM sub-projects.
 
 Git does not use sequential integer revision number but instead uses a hash to
-identify each commit. (Linus mentioned that the lack of such revision number
-is "the only real design mistake" in Git [TorvaldRevNum]_.)
+identify each commit.
 
 The loss of a sequential integer revision number has been a sticking point in
 past discussions about Git:
@@ -561,7 +560,7 @@
 This checks out only compiler-rt and provides commit access using "svn commit",
 in the same way as it would do today.
 
-**Using a Subproject Git Nirror**
+**Using a Subproject Git Mirror**
 
 You can use *git-svn* and one of the sub-project mirrors::
 
@@ -853,6 +852,540 @@
 less like to encounter a build failure where a commit change an API in LLVM and
 another later one "fixes" the build in clang.
 
+Moving Local Branches to the Monorepo
+=====================================
+
+Suppose you have been developing against the existing LLVM git
+mirrors.  You have one or more git branches that you want to migrate
+to the "final monorepo".
+
+The simplest way to migrate such branches is with the
+``migrate-downstream-fork.py`` tool at
+https://github.com/jyknight/llvm-git-migration.
+
+Basic migration
+---------------
+
+Basic instructions for ``migrate-downstream-fork.py`` are in the
+Python script and are expanded on below to a more general recipe::
+
+  # Make a repository which will become your final local mirror of the
+  # monorepo.
+  mkdir my-monorepo
+  git -C my-monorepo init
+
+  # Add a remote to the monorepo.
+  git -C my-monorepo remote add upstream/monorepo https://github.com/llvm/llvm-project.git
+
+  # Add remotes for each git mirror you use, from upstream as well as
+  # your local mirror.  All projects are listed here but you need only
+  # import those for which you have local branches.
+  my_projects=( clang
+                clang-tools-extra
+                compiler-rt
+                debuginfo-tests
+                libcxx
+                libcxxabi
+                libunwind
+                lld
+                lldb
+                llvm
+                openmp
+                polly )
+  for p in ${my_projects[@]}; do
+    git -C my-monorepo remote add upstream/split/${p} https://github.com/llvm-mirror/${p}.git
+    git -C my-monorepo remote add local/split/${p} https://my.local.mirror.org/${p}.git
+  done
+
+  # Pull in all the commits.
+  git -C my-monorepo fetch --all
+
+  # Run migrate-downstream-fork to rewrite local branches on top of
+  # the upstream monorepo.
+  (
+     cd my-monorepo
+     migrate-downstream-fork.py \
+       refs/remotes/local \
+       refs/tags \
+       --new-repo-prefix=refs/remotes/upstream/monorepo \
+       --old-repo-prefix=refs/remotes/upstream/split \
+       --source-kind=split \
+       --revmap-out=monorepo-map.txt
+  )
+
+  # Octopus-merge the resulting local split histories to unify them.
+
+  # Assumes local work on local split mirrors is on master (and
+  # upstream is presumably represented by some other branch like
+  # upstream/master).
+  my_local_branch="master"
+
+  git -C my-monorepo branch --no-track local/octopus/master \
+    $(git -C my-monorepo merge-base refs/remotes/upstream/monorepo/master \
+                                    refs/remotes/local/split/llvm/${my_local_branch})
+  git -C my-monorepo checkout local/octopus/${my_local_branch}
+
+  subproject_branches=()
+  for p in ${my_projects[@]}; do
+    subproject_branch=${p}/local/monorepo/${my_local_branch}
+    git -C my-monorepo branch ${subproject_branch} \
+      refs/remotes/local/split/${p}/${my_local_branch}
+    if [[ "${p}" != "llvm" ]]; then
+      subproject_branches+=( ${subproject_branch} )
+    fi
+  done
+
+  git -C my-monorepo merge ${subproject_branches[@]}
+
+  for p in ${my_projects[@]}; do
+    subproject_branch=${p}/local/monorepo/${my_local_branch}
+    git -C my-monorepo branch -d ${subproject_branch}
+  done
+
+  # Create local branches for upstream monorepo branches.
+  for ref in $(git -C my-monorepo for-each-ref --format="%(refname)" \
+                   refs/remotes/upstream/monorepo); do
+    upstream_branch=${ref#refs/remotes/upstream/monorepo/}
+    git -C my-monorepo branch upstream/${upstream_branch} ${ref}
+  done
+
+The above gets you to a state like the following::
+
+  U1 - U2 - U3 <- upstream/master
+    \   \    \
+     \   \    - Llld1 - Llld2 -
+      \   \                    \
+       \   - Lclang1 - Lclang2-- Lmerge <- local/octopus/master
+        \                      /
+         - Lllvm1 - Lllvm2-----
+
+Each branched component has its branch rewritten on top of the
+monorepo and all components are unified by a giant octopus merge.
+
+If additional active local branches need to be preserved, the above
+operations following the assignment to ``my_local_branch`` should be
+done for each branch.  Ref paths will need to be updated to map the
+local branch to the corresponding upstream branch.  If local branches
+have no corresponding upstream branch, then the creation of
+``local/octopus/<local branch>`` need not use ``git-merge-base`` to
+pinpont its root commit; it may simply be branched from the
+appropriate component branch (say, ``llvm/local_release_X``).
+
+Zipping local history
+---------------------
+
+The octopus merge is suboptimal for many cases, because walking back
+through the history of one component leaves the other components fixed
+at a history that likely makes things unbuildable.
+
+Some downstream users track the order commits were made to subprojects
+with some kind of "umbrella" project that imports the project git
+mirrors as submodules, similar to the multirepo umbrella proposed
+above.  Such an umbrella repository looks something like this::
+
+   UM1 ---- UM2 -- UM3 -- UM4 ---- UM5 ---- UM6 ---- UM7 ---- UM8 <- master
+   |        |             |        |        |        |        |
+  Lllvm1   Llld1         Lclang1  Lclang2  Lllvm2   Llld2     Lmyproj1
+
+The vertical bars represent submodule updates to a particular local
+commit in the project mirror.  ``UM3`` in this case is a commit of
+some local umbrella repository state that is not a submodule update,
+perhaps a ``README`` or project build script update.  Commit ``UM8``
+updates a submodule of local project ``myproj``.
+
+The tool ``zip-downstream-fork.py`` at
+https://github.com/greened/llvm-git-migration/tree/zip can be used to
+convert the umbrella history into a monorepo-based history with
+commits in the order implied by submodule updates::
+
+  U1 - U2 - U3 <- upstream/master
+   \    \    \
+    \    -----\---------------                                    local/zip--.
+     \         \              \                                               |
+    - Lllvm1 - Llld1 - UM3 -  Lclang1 - Lclang2 - Lllvm2 - Llld2 - Lmyproj1 <-'
+
+
+The ``U*`` commits represent upstream commits to the monorepo master
+branch.  Each submodule update in the local ``UM*`` commits brought in
+a subproject tree at some local commit.  The trees in the ``L*1``
+commits represent merges from upstream.  These result in edges from
+the ``U*`` commits to their corresponding rewritten ``L*1`` commits.
+The ``L*2`` commits did not do any merges from upstream.
+
+Note that the merge from ``U2`` to ``Lclang1`` appears redundant, but
+if, say, ``U3`` changed some files in upstream clang, the ``Lclang1``
+commit appearing after the ``Llld1`` commit would actually represent a
+clang tree *earlier* in the upstream clang history.  We want the
+``local/zip`` branch to accurately represent the state of our umbrella
+history and so the edge ``U2 -> Lclang1`` is a visual reminder of what
+clang's tree actually looks like in ``Lclang1``.
+
+Even so, the edge ``U3 -> Llld1`` could be problematic for future
+merges from upstream.  git will think that we've already merged from
+``U3``, and we have, except for the state of the clang tree.  One
+possible migitation strategy is to manually diff clang between ``U2``
+and ``U3`` and apply those updates to ``local/zip``.  Another,
+possibly simpler strategy is to freeze local work on downstream
+branches and merge all submodules from the latest upstream before
+running ``zip-downstream-fork.py``.  If downstream merged each project
+from upstream in lockstep without any intervening local commits, then
+things should be fine without any special action.  We anticipate this
+to be the common case.
+
+The tree for ``Lclang1`` outside of clang will represent the state of
+things at ``U3`` since all of the upstream projects not participating
+in the umbrella history should be in a state respecting the commit
+``U3``.  The trees for llvm and lld should correctly represent commits
+``Lllvm1`` and ``Llld1``, respectively.
+
+Commit ``UM3`` changed files not related to submodules and we need
+somewhere to put them.  It is not safe in general to put them in the
+monorepo root directory because they may conflict with files in the
+monorepo.  Let's assume we want them in a directory ``local`` in the
+monorepo.
+
+**Example 1: Umbrella looks like the monorepo**
+
+For this example, we'll assume that each subproject appears in its own
+top-level directory in the umbrella, just as they do in the monorepo .
+Let's also assume that we want the files in directory ``myproj`` to
+appear in ``local/myproj``.
+
+Given the above run of ``migrate-downstream-fork.py``, a recipe to
+create the zipped history is below::
+
+  # Import any non-LLVM repositories the umbrella references.
+  git -C my-monorepo remote add localrepo \
+                                https://my.local.mirror.org/localrepo.git
+  git fetch localrepo
+
+  subprojects=( clang clang-tools-extra compiler-rt debuginfo-tests libclc
+                libcxx libcxxabi libunwind lld lldb llgo llvm openmp
+                parallel-libs polly pstl )
+
+  # Import histories for upstream split projects (this was probably
+  # already done for the ``migrate-downstream-fork.py`` run).
+  for project in ${subprojects[@]}; do
+    git remote add upstream/split/${project} \
+                   https://github.com/llvm-mirror/${subproject}.git
+    git fetch umbrella/split/${project}
+  done
+
+  # Import histories for downstream split projects (this was probably
+  # already done for the ``migrate-downstream-fork.py`` run).
+  for project in ${subprojects[@]}; do
+    git remote add local/split/${project} \
+                   https://my.local.mirror.org/${subproject}.git
+    git fetch local/split/${project}
+  done
+
+  # Import umbrella history.
+  git -C my-monorepo remote add umbrella \
+                                https://my.local.mirror.org/umbrella.git
+  git fetch umbrella
+
+  # Put myproj in local/myproj
+  echo "myproj local/myproj" > my-monorepo/submodule-map.txt
+
+  # Rewrite history
+  (
+    cd my-monorepo
+    zip-downstream-fork.py \
+      refs/remotes/umbrella \
+      --new-repo-prefix=refs/remotes/upstream/monorepo \
+      --old-repo-prefix=refs/remotes/upstream/split \
+      --revmap-in=monorepo-map.txt \
+      --revmap-out=zip-map.txt \
+      --subdir=local \
+      --submodule-map=submodule-map.txt \
+      --update-tags
+   )
+
+   # Create the zip branch (assuming umbrella master is wanted).
+   git -C my-monorepo branch --no-track local/zip/master refs/remotes/umbrella/master
+
+Note that if the umbrella has submodules to non-LLVM repositories,
+``zip-downstream-fork.py`` needs to know about them to be able to
+rewrite commits.  That is why the first step above is to fetch commits
+from such repositories.
+
+With ``--update-tags`` the tool will migrate annotated tags pointing
+to submodule commits that were inlined into the zipped history.  If
+the umbrella pulled in an upstream commit that happened to have a tag
+pointing to it, that tag will be migrated, which is almost certainly
+not what is wanted.  The tag can always be moved back to its original
+commit after rewriting, or the ``--update-tags`` option may be
+discarded and any local tags would then be migrated manually.
+
+**Example 2: Nested sources layout**
+
+The tool handles nested submodules (e.g. llvm is a submodule in
+umbrella and clang is a submodule in llvm).  The file
+``submodule-map.txt`` is a list of pairs, one per line.  The first
+pair item describes the path to a submodule in the umbrella
+repository.  The second pair item secribes the path where trees for
+that submodule should be written in the zipped history.  
+
+Let's say your umbrella repository is actually the llvm repository and
+it has submodules in the "nested sources" layout (clang in
+tools/clang, etc.).  Let's also say ``projects/myproj`` is a submodule
+pointing to some downstream repository.  The submodule map file should
+look like this (we still want myproj mapped the same way as
+previously)::
+
+  tools/clang clang
+  tools/clang/tools/extra clang-tools-extra
+  projects/compiler-rt compiler-rt
+  projects/debuginfo-tests debuginfo-tests
+  projects/libclc libclc
+  projects/libcxx libcxx
+  projects/libcxxabi libcxxabi
+  projects/libunwind libunwind
+  tools/lld lld
+  tools/lldb lldb
+  projects/openmp openmp
+  tools/polly polly
+  projects/myproj local/myproj
+
+If a submodule path does not appear in the map, the tools assumes it
+should be placed in the same place in the monorepo.  That means if you
+use the "nested sources" layout in your umrella, you *must* provide
+map entries for all of the projects in your umbrella (except llvm).
+Otherwise trees from submodule updates will appear underneath llvm in
+the zippped history.
+
+Because llvm is itself the umbrella, we use --subdir to write its
+content into ``llvm`` in the zippped history::
+
+  # Import any non-LLVM repositories the umbrella references.
+  git -C my-monorepo remote add localrepo \
+                                https://my.local.mirror.org/localrepo.git
+  git fetch localrepo
+
+  subprojects=( clang clang-tools-extra compiler-rt debuginfo-tests libclc
+                libcxx libcxxabi libunwind lld lldb llgo llvm openmp
+                parallel-libs polly pstl )
+
+  # Import histories for upstream split projects (this was probably
+  # already done for the ``migrate-downstream-fork.py`` run).
+  for project in ${subprojects[@]}; do
+    git remote add upstream/split/${project} \
+                   https://github.com/llvm-mirror/${subproject}.git
+    git fetch umbrella/split/${project}
+  done
+
+  # Import histories for downstream split projects (this was probably
+  # already done for the ``migrate-downstream-fork.py`` run).
+  for project in ${subprojects[@]}; do
+    git remote add local/split/${project} \
+                   https://my.local.mirror.org/${subproject}.git
+    git fetch local/split/${project}
+  done
+
+  # Import umbrella history.  We want this under a different refspec
+  # so zip-downstream-fork.py knows what it is.
+  git -C my-monorepo remote add umbrella \
+                                 https://my.local.mirror.org/llvm.git
+  git fetch umbrella
+
+  # Create the submodule map.
+  echo "tools/clang clang" > my-monorepo/submodule-map.txt
+  echo "tools/clang/tools/extra clang-tools-extra" >> my-monorepo/submodule-map.txt
+  echo "projects/compiler-rt compiler-rt" >> my-monorepo/submodule-map.txt
+  echo "projects/debuginfo-tests debuginfo-tests" >> my-monorepo/submodule-map.txt
+  echo "projects/libclc libclc" >> my-monorepo/submodule-map.txt
+  echo "projects/libcxx libcxx" >> my-monorepo/submodule-map.txt
+  echo "projects/libcxxabi libcxxabi" >> my-monorepo/submodule-map.txt
+  echo "projects/libunwind libunwind" >> my-monorepo/submodule-map.txt
+  echo "tools/lld lld" >> my-monorepo/submodule-map.txt
+  echo "tools/lldb lldb" >> my-monorepo/submodule-map.txt
+  echo "projects/openmp openmp" >> my-monorepo/submodule-map.txt
+  echo "tools/polly polly" >> my-monorepo/submodule-map.txt
+  echo "projects/myproj local/myproj" >> my-monorepo/submodule-map.txt
+
+  # Rewrite history
+  (
+    cd my-monorepo
+    zip-downstream-fork.py \
+      refs/remotes/umbrella \
+      --new-repo-prefix=refs/remotes/upstream/monorepo \
+      --old-repo-prefix=refs/remotes/upstream/split \
+      --revmap-in=monorepo-map.txt \
+      --revmap-out=zip-map.txt \
+      --subdir=llvm \
+      --submodule-map=submodule-map.txt \
+      --update-tags
+   )
+
+   # Create the zip branch (assuming umbrella master is wanted).
+   git -C my-monorepo branch --no-track local/zip/master refs/remotes/umbrella/master
+
+
+Comments at the top of ``zip-downstream-fork.py`` describe in more
+detail how the tool works and various implications of its operation.
+
+Importing local repositories
+----------------------------
+
+You may have additional repositories that integrate with the LLVM
+ecosystem, essentially extending it with new tools.  If such
+repositories are tightly coupled with LLVM, it may make sense to
+import them into your local mirror of the monorepo.
+
+If such repositores participated in the umbrella repository used
+during the zipping process above, they will automatically be added to
+the monorepo.  For downstream repositories that don't participate in
+an umbrella setup, the ``import-downstream-repo.py`` tool at
+https://github.com/greened/llvm-git-migration/tree/import can help with
+getting them into the monorepo.  A recipe follows::
+
+  # Import downstream repo history into the monorepo.
+  git -C my-monorepo remote add myrepo https://my.local.mirror.org/myrepo.git
+  git fetch myrepo
+
+  my_local_tags=( refs/tags/release
+                  refs/tags/hotfix )
+
+  (
+    cd my-monorepo
+    import-downstream-repo.py \
+      refs/remotes/myrepo \
+      ${my_local_tags[@]} \
+      --new-repo-prefix=refs/remotes/upstream/monorepo \
+      --subdir=myrepo \
+      --tag-prefix="myrepo-"
+   )
+
+   # Preserve release braches.
+   for ref in $(git -C my-monorepo for-each-ref --format="%(refname)" \
+                  refs/remotes/myrepo/release); do
+     branch=${ref#refs/remotes/myrepo/}
+     git -C my-monorepo branch --no-track myrepo/${branch} ${ref}
+   done
+
+   # Preserve master.
+   git -C my-monorepo branch --no-track myrepo/master refs/remotes/myrepo/master
+
+   # Merge master.
+   git -C my-monorepo checkout local/zip/master  # Or local/octopus/master
+   git -C my-monorepo merge myrepo/master
+
+You may want to merge other corresponding branches, for example
+``myrepo`` release branches if they were in lockstep with LLVM project
+releases.
+
+``--tag-prefix`` tells ``import-downstream-repo.py`` to rename
+annotated tags with the given prefix.  Due to limitations with
+``fast_filter_branch.py``, unannotated tags cannot be renamed
+(``fast_filter_branch.py`` considers them branches, not tags).  Since
+the upstream monorepo had its tags rewritten with an "llvmorg-"
+prefix, name conflicts should not be an issue.  ``--tag-prefix`` can
+be used to more clearly indicate which tags correspond to various
+imported repositories.
+
+Given this repository history::
+
+  R1 - R2 - R3 <- master
+       ^
+       |
+    release/1
+
+The above recipe results in a history like this::
+
+  U1 - U2 - U3 <- upstream/master
+   \    \    \
+    \    -----\---------------                                         local/zip--.
+     \         \              \                                                    |
+    - Lllvm1 - Llld1 - UM3 -  Lclang1 - Lclang2 - Lllvm2 - Llld2 - Lmyproj1 - M1 <-'
+                                                                             /
+                                                                 R1 - R2 - R3  <-.
+                                                                      ^           |
+                                                                      |           |
+                                                               myrepo-release/1   |
+                                                                                  |
+                                                                   myrepo/master--'
+
+Commits ``R1``, ``R2`` and ``R3`` have trees that *only* contain blobs
+from ``myrepo``.  If you require commits from ``myrepo`` to be
+interleaved with commits on local project branches (for example,
+interleaved with ``llvm1``, ``llvm2``, etc. above) and myrepo doesn't
+appear in an umbrella repository, a new tool will need to be
+developed.  Creating such a tool would involve:
+
+1. Modifying ``fast_filter_branch.py`` to optionally take a
+   revlist directly rather than generating it itself
+
+2. Creating a tool to generate an interleaved ordering of local
+   commits based on some criteria (``zip-downstream-fork.py`` uses the
+   umbrella history as its criterion)
+
+3. Generating such an ordering and feeding it to
+   ``fast_filter_branch.py`` as a revlist
+
+Some care will also likely need to be taken to handle merge commits,
+to ensure the parents of such commits migrate correctly.
+
+Scrubbing the Local Monorepo
+----------------------------
+
+Once all of the migrating, zipping and importing is done, it's time to
+clean up.  The python tools use ``git-fast-import`` which leaves a lot
+of cruft around and we want to shrink our new monorepo mirror as much
+as possible.  Here is one way to do it::
+
+  git -C my-monorepo checkout master
+
+  # Delete branches we no longer need.  Do this for any other branches
+  # you merged above.
+  git -C my-monorepo branch -D local/zip/master || true
+  git -C my-monorepo branch -D local/octopus/master || true
+
+  # Remove remotes.
+  git -C my-monorepo remote remove upstream/monorepo
+
+  for p in ${my_projects[@]}; do
+    git -C my-monorepo remote remove upstream/split/${p}
+    git -C my-monorepo remote remove local/split/${p}
+  done
+
+  git -C my-monorepo remote remove localrepo
+  git -C my-monorepo remote remove umbrella
+  git -C my-monorepo remote remove myrepo
+
+  # Add anything else here you don't need.  refs/tags/release is
+  # listed below assuming tags have been rewritten with a local prefix.
+  # If not, remove it from this list.
+  refs_to_clean=(
+    refs/original
+    refs/remotes
+    refs/tags/backups
+    refs/tags/release
+  )
+
+  git -C my-monorepo for-each-ref --format="%(refname)" ${refs_to_clean[@]} |
+    xargs -n1 --no-run-if-empty git -C my-monorepo update-ref -d
+
+  git -C my-monorepo reflog expire --all --expire=now
+
+  # fast_filter_branch.py might have gc running in the background.
+  while ! git -C my-monorepo \
+    -c gc.reflogExpire=0 \
+    -c gc.reflogExpireUnreachable=0 \
+    -c gc.rerereresolved=0 \
+    -c gc.rerereunresolved=0 \
+    -c gc.pruneExpire=now \
+    gc --prune=now; do
+    continue
+  done
+
+  # Takes a LOOOONG time!
+  git -C my-monorepo repack -A -d -f --depth=250 --window=250
+
+  git -C my-monorepo prune-packed
+  git -C my-monorepo prune
+
+You should now have a trim monorepo.  Upload it to your git server and
+happy hacking!
 
 References
 ==========
@@ -860,7 +1393,6 @@
 .. [LattnerRevNum] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2011-July/041739.html
 .. [TrickRevNum] Andrew Trick, http://lists.llvm.org/pipermail/llvm-dev/2011-July/041721.html
 .. [JSonnRevNum] Joerg Sonnenberg, http://lists.llvm.org/pipermail/llvm-dev/2011-July/041688.html
-.. [TorvaldRevNum] Linus Torvald, http://git.661346.n2.nabble.com/Git-commit-generation-numbers-td6584414.html
 .. [MatthewsRevNum] Chris Matthews, http://lists.llvm.org/pipermail/cfe-dev/2016-July/049886.html
 .. [submodules] Git submodules, https://git-scm.com/book/en/v2/Git-Tools-Submodules)
 .. [statuschecks] GitHub status-checks, https://help.github.com/articles/about-required-status-checks/
diff --git a/docs/Proposals/VariableNames.rst b/docs/Proposals/VariableNames.rst
new file mode 100644
index 0000000..29aee95
--- /dev/null
+++ b/docs/Proposals/VariableNames.rst
@@ -0,0 +1,399 @@
+===================
+Variable Names Plan
+===================
+
+.. contents::
+   :local:
+
+This plan is *provisional*. It is not agreed upon. It is written with the
+intention of capturing the desires and concerns of the LLVM community, and
+forming them into a plan that can be agreed upon.
+The original author is somewhat naïve in the ways of LLVM so there will
+inevitably be some details that are flawed. You can help - you can edit this
+page (preferably with a Phabricator review for larger changes) or reply to the
+`Request For Comments thread
+<http://lists.llvm.org/pipermail/llvm-dev/2019-February/130083.html>`_.
+
+Too Long; Didn't Read
+=====================
+
+Improve the readability of LLVM code.
+
+Introduction
+============
+
+The current `variable naming rule
+<../CodingStandards.html#name-types-functions-variables-and-enumerators-properly>`_
+states:
+
+  Variable names should be nouns (as they represent state). The name should be
+  camel case, and start with an upper case letter (e.g. Leader or Boats).
+
+This rule is the same as that for type names. This is a problem because the
+type name cannot be reused for a variable name [*]_. LLVM developers tend to
+work around this by either prepending ``The`` to the type name::
+
+  Triple TheTriple;
+
+... or more commonly use an acronym, despite the coding standard stating "Avoid
+abbreviations unless they are well known"::
+
+  Triple T;
+
+The proliferation of acronyms leads to hard-to-read code such as `this
+<https://github.com/llvm/llvm-project/blob/0a8bc14ad7f3209fe702d18e250194cd90188596/llvm/lib/Transforms/Vectorize/LoopVectorize.cpp#L7445>`_::
+
+  InnerLoopVectorizer LB(L, PSE, LI, DT, TLI, TTI, AC, ORE, VF.Width, IC,
+                         &LVL, &CM);
+
+Many other coding guidelines [LLDB]_ [Google]_ [WebKit]_ [Qt]_ [Rust]_ [Swift]_
+[Python]_ require that variable names begin with a lower case letter in contrast
+to class names which begin with a capital letter. This convention means that the
+most readable variable name also requires the least thought::
+
+  Triple triple;
+
+There is some agreement that the current rule is broken [LattnerAgree]_
+[ArsenaultAgree]_ [RobinsonAgree]_ and that acronyms are an obstacle to reading
+new code [MalyutinDistinguish]_ [CarruthAcronym]_ [PicusAcronym]_. There are
+some opposing views [ParzyszekAcronym2]_ [RicciAcronyms]_.
+
+This work-in-progress proposal is to change the coding standard for variable
+names to require that they start with a lower case letter.
+
+.. [*] In `some cases
+   <https://github.com/llvm/llvm-project/blob/8b72080d4d7b13072f371712eed333f987b7a18e/llvm/lib/CodeGen/SelectionDAG/SelectionDAG.cpp#L2727>`_
+   the type name *is* reused as a variable name, but this shadows the type name
+   and confuses many debuggers [DenisovCamelBack]_.
+
+Variable Names Coding Standard Options
+======================================
+
+There are two main options for variable names that begin with a lower case
+letter: ``camelBack`` and ``lower_case``. (These are also known by other names
+but here we use the terminology from clang-tidy).
+
+``camelBack`` is consistent with [WebKit]_, [Qt]_ and [Swift]_ while
+``lower_case`` is consistent with [LLDB]_, [Google]_, [Rust]_ and [Python]_.
+
+``camelBack`` is already used for function names, which may be considered an
+advantage [LattnerFunction]_ or a disadvantage [CarruthFunction]_.
+
+Approval for ``camelBack`` was expressed by [DenisovCamelBack]_
+[LattnerFunction]_ [IvanovicDistinguish]_.
+Opposition to ``camelBack`` was expressed by [CarruthCamelBack]_
+[TurnerCamelBack]_.
+Approval for ``lower_case`` was expressed by [CarruthLower]_
+[CarruthCamelBack]_ [TurnerLLDB]_.
+Opposition to ``lower_case`` was expressed by [LattnerLower]_.
+
+Differentiating variable kinds
+------------------------------
+
+An additional requested change is to distinguish between different kinds of
+variables [RobinsonDistinguish]_ [RobinsonDistinguish2]_ [JonesDistinguish]_
+[IvanovicDistinguish]_ [CarruthDistinguish]_ [MalyutinDistinguish]_.
+
+Others oppose this idea [HähnleDistinguish]_ [GreeneDistinguish]_
+[HendersonPrefix]_.
+
+A possibility is for member variables to be prefixed with ``m_`` and for global
+variables to be prefixed with ``g_`` to distinguish them from local variables.
+This is consistent with [LLDB]_. The ``m_`` prefix is consistent with [WebKit]_.
+
+A variation is for member variables to be prefixed with ``m``
+[IvanovicDistinguish]_ [BeylsDistinguish]_. This is consistent with [Mozilla]_.
+
+Another option is for member variables to be suffixed with ``_`` which is
+consistent with [Google]_ and similar to [Python]_. Opposed by
+[ParzyszekDistinguish]_.
+
+Reducing the number of acronyms
+===============================
+
+While switching coding standard will make it easier to use non-acronym names for
+new code, it doesn't improve the existing large body of code that uses acronyms
+extensively to the detriment of its readability. Further, it is natural and
+generally encouraged that new code be written in the style of the surrounding
+code. Therefore it is likely that much newly written code will also use
+acronyms despite what the coding standard says, much as it is today.
+
+As well as changing the case of variable names, they could also be expanded to
+their non-acronym form e.g. ``Triple T`` → ``Triple triple``.
+
+There is support for expanding many acronyms [CarruthAcronym]_ [PicusAcronym]_
+but there is a preference that expanding acronyms be deferred
+[ParzyszekAcronym]_ [CarruthAcronym]_.
+
+The consensus within the community seems to be that at least some acronyms are
+valuable [ParzyszekAcronym]_ [LattnerAcronym]_. The most commonly cited acronym
+is ``TLI`` however that is used to refer to both ``TargetLowering`` and
+``TargetLibraryInfo`` [GreeneDistinguish]_.
+
+The following is a list of acronyms considered sufficiently useful that the
+benefit of using them outweighs the cost of learning them. Acronyms that are
+either not on the list or are used to refer to a different type should be
+expanded.
+
+============================ =============
+Class name                   Variable name
+============================ =============
+DeterministicFiniteAutomaton dfa
+DominatorTree                dt
+LoopInfo                     li
+MachineFunction              mf
+MachineInstr                 mi
+MachineRegisterInfo          mri
+ScalarEvolution              se
+TargetInstrInfo              tii
+TargetLibraryInfo            tli
+TargetRegisterInfo           tri
+============================ =============
+
+In some cases renaming acronyms to the full type name will result in overly
+verbose code. Unlike most classes, a variable's scope is limited and therefore
+some of its purpose can implied from that scope, meaning that fewer words are
+necessary to give it a clear name. For example, in an optization pass the reader
+can assume that a variable's purpose relates to optimization and therefore an
+``OptimizationRemarkEmitter`` variable could be given the name ``remarkEmitter``
+or even ``remarker``.
+
+The following is a list of longer class names and the associated shorter
+variable name.
+
+========================= =============
+Class name                Variable name
+========================= =============
+BasicBlock                block
+ConstantExpr              expr
+ExecutionEngine           engine
+MachineOperand            operand
+OptimizationRemarkEmitter remarker
+PreservedAnalyses         analyses
+PreservedAnalysesChecker  checker
+TargetLowering            lowering
+TargetMachine             machine
+========================= =============
+
+Transition Options
+==================
+
+There are three main options for transitioning:
+
+1. Keep the current coding standard
+2. Laissez faire
+3. Big bang
+
+Keep the current coding standard
+--------------------------------
+
+Proponents of keeping the current coding standard (i.e. not transitioning at
+all) question whether the cost of transition outweighs the benefit
+[EmersonConcern]_ [ReamesConcern]_ [BradburyConcern]_.
+The costs are that ``git blame`` will become less usable; and that merging the
+changes will be costly for downstream maintainers. See `Big bang`_ for potential
+mitigations.
+
+Laissez faire
+-------------
+
+The coding standard could allow both ``CamelCase`` and ``camelBack`` styles for
+variable names [LattnerTransition]_.
+
+A code review to implement this is at https://reviews.llvm.org/D57896.
+
+Advantages
+**********
+
+ * Very easy to implement initially.
+
+Disadvantages
+*************
+
+ * Leads to inconsistency [BradburyConcern]_ [AminiInconsistent]_.
+ * Inconsistency means it will be hard to know at a guess what name a variable
+   will have [DasInconsistent]_ [CarruthInconsistent]_.
+ * Some large-scale renaming may happen anyway, leading to its disadvantages
+   without any mitigations.
+
+Big bang
+--------
+
+With this approach, variables will be renamed by an automated script in a series
+of large commits.
+
+The principle advantage of this approach is that it minimises the cost of
+inconsistency [BradburyTransition]_ [RobinsonTransition]_.
+
+It goes against a policy of avoiding large-scale reformatting of existing code
+[GreeneDistinguish]_.
+
+It has been suggested that LLD would be a good starter project for the renaming
+[Ueyama]_.
+
+Keeping git blame usable
+************************
+
+``git blame`` (or ``git annotate``) permits quickly identifying the commit that
+changed a given line in a file. After renaming variables, many lines will show
+as being changed by that one commit, requiring a further invocation of ``git
+blame`` to identify prior, more interesting commits [GreeneGitBlame]_
+[RicciAcronyms]_.
+
+**Mitigation**: `git-hyper-blame
+<https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/git-hyper-blame.html>`_
+can ignore or "look through" a given set of commits.
+A ``.git-blame-ignore-revs`` file identifying the variable renaming commits
+could be added to the LLVM git repository root directory.
+It is being `investigated
+<https://public-inbox.org/git/20190324235020.49706-1-michael@platin.gs/>`_
+whether similar functionality could be added to ``git blame`` itself.
+
+Minimising cost of downstream merges
+************************************
+
+There are many forks of LLVM with downstream changes. Merging a large-scale
+renaming change could be difficult for the fork maintainers.
+
+**Mitigation**: A large-scale renaming would be automated. A fork maintainer can
+merge from the commit immediately before the renaming, then apply the renaming
+script to their own branch. They can then merge again from the renaming commit,
+resolving all conflicts by choosing their own version. This could be tested on
+the [SVE]_ fork.
+
+Provisional Plan
+================
+
+This is a provisional plan for the `Big bang`_ approach. It has not been agreed.
+
+#. Investigate improving ``git blame``. The extent to which it can be made to
+   "look through" commits may impact how big a change can be made.
+
+#. Write a script to expand acronyms.
+
+#. Experiment and perform dry runs of the various refactoring options.
+   Results can be published in forks of the LLVM Git repository.
+
+#. Consider the evidence and agree on the new policy.
+
+#. Agree & announce a date for the renaming of the starter project (LLD).
+
+#. Update the `policy page <../CodingStandards.html>`_. This will explain the
+   old and new rules and which projects each applies to.
+
+#. Refactor the starter project in two commits:
+
+   1. Add or change the project's .clang-tidy to reflect the agreed rules.
+      (This is in a separate commit to enable the merging process described in
+      `Minimising cost of downstream merges`_).
+      Also update the project list on the policy page.
+   2. Apply ``clang-tidy`` to the project's files, with only the
+      ``readability-identifier-naming`` rules enabled. ``clang-tidy`` will also
+      reformat the affected lines according to the rules in ``.clang-format``.
+      It is anticipated that this will be a good dog-fooding opportunity for
+      clang-tidy, and bugs should be fixed in the process, likely including:
+
+        * `readability-identifier-naming incorrectly fixes lambda capture
+          <https://bugs.llvm.org/show_bug.cgi?id=41119>`_.
+        * `readability-identifier-naming incorrectly fixes variables which
+          become keywords <https://bugs.llvm.org/show_bug.cgi?id=41120>`_.
+        * `readability-identifier-naming misses fixing member variables in
+          destructor <https://bugs.llvm.org/show_bug.cgi?id=41122>`_.
+
+#. Gather feedback and refine the process as appropriate.
+
+#. Apply the process to the following projects, with a suitable delay between
+   each (at least 4 weeks after the first change, at least 2 weeks subsequently)
+   to allow gathering further feedback.
+   This list should exclude projects that must adhere to an externally defined
+   standard e.g. libcxx.
+   The list is roughly in chronological order of renaming.
+   Some items may not make sense to rename individually - it is expected that
+   this list will change following experimentation:
+
+   * TableGen
+   * llvm/tools
+   * clang-tools-extra
+   * clang
+   * ARM backend
+   * AArch64 backend
+   * AMDGPU backend
+   * ARC backend
+   * AVR backend
+   * BPF backend
+   * Hexagon backend
+   * Lanai backend
+   * MIPS backend
+   * NVPTX backend
+   * PowerPC backend
+   * RISC-V backend
+   * Sparc backend
+   * SystemZ backend
+   * WebAssembly backend
+   * X86 backend
+   * XCore backend
+   * libLTO
+   * Debug Information
+   * Remainder of llvm
+   * compiler-rt
+   * libunwind
+   * openmp
+   * parallel-libs
+   * polly
+   * lldb
+
+#. Remove the old variable name rule from the policy page.
+
+#. Repeat many of the steps in the sequence, using a script to expand acronyms.
+
+References
+==========
+
+.. [LLDB] LLDB Coding Conventions https://llvm.org/svn/llvm-project/lldb/branches/release_39/www/lldb-coding-conventions.html
+.. [Google] Google C++ Style Guide https://google.github.io/styleguide/cppguide.html#Variable_Names
+.. [WebKit] WebKit Code Style Guidelines https://webkit.org/code-style-guidelines/#names
+.. [Qt] Qt Coding Style https://wiki.qt.io/Qt_Coding_Style#Declaring_variables
+.. [Rust] Rust naming conventions https://doc.rust-lang.org/1.0.0/style/style/naming/README.html
+.. [Swift] Swift API Design Guidelines https://swift.org/documentation/api-design-guidelines/#general-conventions
+.. [Python] Style Guide for Python Code https://www.python.org/dev/peps/pep-0008/#function-and-variable-names
+.. [Mozilla] Mozilla Coding style: Prefixes https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Coding_Style#Prefixes
+.. [SVE] LLVM with support for SVE https://github.com/ARM-software/LLVM-SVE
+.. [AminiInconsistent] Mehdi Amini, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130329.html
+.. [ArsenaultAgree] Matt Arsenault, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129934.html
+.. [BeylsDistinguish] Kristof Beyls, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130292.html
+.. [BradburyConcern] Alex Bradbury, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130266.html
+.. [BradburyTransition] Alex Bradbury, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130388.html
+.. [CarruthAcronym] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130313.html
+.. [CarruthCamelBack] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130214.html
+.. [CarruthDistinguish] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130310.html
+.. [CarruthFunction] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130309.html
+.. [CarruthInconsistent] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130312.html
+.. [CarruthLower] Chandler Carruth, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130430.html
+.. [DasInconsistent] Sanjoy Das, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130304.html
+.. [DenisovCamelBack] Alex Denisov, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130179.html
+.. [EmersonConcern] Amara Emerson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129894.html
+.. [GreeneDistinguish] David Greene, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130425.html
+.. [GreeneGitBlame] David Greene, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130228.html
+.. [HendersonPrefix] James Henderson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130465.html
+.. [HähnleDistinguish] Nicolai Hähnle, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129923.html
+.. [IvanovicDistinguish] Nemanja Ivanovic, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130249.html
+.. [JonesDistinguish] JD Jones, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129926.html
+.. [LattnerAcronym] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130353.html
+.. [LattnerAgree] Chris Latter, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129907.html
+.. [LattnerFunction] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130630.html
+.. [LattnerLower] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130629.html
+.. [LattnerTransition] Chris Lattner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130355.html
+.. [MalyutinDistinguish] Danila Malyutin, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130320.html
+.. [ParzyszekAcronym] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130306.html
+.. [ParzyszekAcronym2] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130323.html
+.. [ParzyszekDistinguish] Krzysztof Parzyszek, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129941.html
+.. [PicusAcronym] Diana Picus, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130318.html
+.. [ReamesConcern] Philip Reames, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130181.html
+.. [RicciAcronyms] Bruno Ricci, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130328.html
+.. [RobinsonAgree] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130111.html
+.. [RobinsonDistinguish] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/129920.html
+.. [RobinsonDistinguish2] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130229.html
+.. [RobinsonTransition] Paul Robinson, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130415.html
+.. [TurnerCamelBack] Zachary Turner, https://reviews.llvm.org/D57896#1402264
+.. [TurnerLLDB] Zachary Turner, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130213.html
+.. [Ueyama] Rui Ueyama, http://lists.llvm.org/pipermail/llvm-dev/2019-February/130435.html
diff --git a/docs/ReleaseNotes.rst b/docs/ReleaseNotes.rst
index db9cf51..60058fd 100644
--- a/docs/ReleaseNotes.rst
+++ b/docs/ReleaseNotes.rst
@@ -1,12 +1,12 @@
 ========================
-LLVM 8.0.0 Release Notes
+LLVM 9.0.0 Release Notes
 ========================
 
 .. contents::
     :local:
 
 .. warning::
-   These are in-progress notes for the upcoming LLVM 8 release.
+   These are in-progress notes for the upcoming LLVM 9 release.
    Release notes for previous releases can be found on
    `the Download Page <https://releases.llvm.org/download.html>`_.
 
@@ -15,7 +15,7 @@
 ============
 
 This document contains the release notes for the LLVM Compiler Infrastructure,
-release 8.0.0.  Here we describe the status of LLVM, including major improvements
+release 9.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 <https://llvm.org/releases/>`_.
@@ -40,13 +40,10 @@
    functionality, or simply have a lot to talk about), see the `NOTE` below
    for adding a new subsection.
 
-* The **llvm-cov** tool can now export lcov trace files using the
-  `-format=lcov` option of the `export` command.
-
-* The add_llvm_loadable_module CMake macro has been removed.  The
-  add_llvm_library macro with the MODULE argument now provides the same
-  functionality.  See `Writing an LLVM Pass
-  <WritingAnLLVMPass.html#setting-up-the-build-environment>`_.
+* The optimizer will now convert calls to ``memcmp`` into a calls to ``bcmp`` in
+  some circumstances. Users who are building freestanding code (not depending on
+  the platform's libc) without specifying ``-ffreestanding`` may need to either
+  pass ``-fno-builtin-bcmp``, or provide a ``bcmp`` function.
 
 .. NOTE
    If you would like to document a larger change, then you can add a
@@ -61,6 +58,10 @@
 Changes to the LLVM IR
 ----------------------
 
+* Added ``immarg`` parameter attribute. This indicates an intrinsic
+  parameter is required to be a simple constant. This annotation must
+  be accurate to avoid possible miscompiles.
+
 
 Changes to the ARM Backend
 --------------------------
@@ -82,8 +83,7 @@
 Changes to the X86 Target
 -------------------------
 
-* Machine model for AMD bdver2 (Piledriver) CPU was added. It is used to support
-  instruction scheduling and other instruction cost heuristics.
+ During this release ...
 
 Changes to the AMDGPU Target
 -----------------------------
@@ -98,14 +98,7 @@
 Changes to the WebAssembly Target
 ---------------------------------
 
-The WebAssembly target is no longer "experimental"! It's now built by default,
-rather than needing to be enabled with LLVM_EXPERIMENTAL_TARGETS_TO_BUILD.
-
-The object file format and core C ABI are now considered stable. That said,
-the object file format has an ABI versioning capability, and one anticipated
-use for it will be to add support for returning small structs as multiple
-return values, once the underlying WebAssembly platform itself supports it.
-Additionally, multithreading support is not yet included in the stable ABI.
+ During this release ...
 
 
 Changes to the OCaml bindings
@@ -120,7 +113,7 @@
 Changes to the DAG infrastructure
 ---------------------------------
 
-External Open Source Projects Using LLVM 8
+External Open Source Projects Using LLVM 9
 ==========================================
 
 * A project...
diff --git a/docs/ScudoHardenedAllocator.rst b/docs/ScudoHardenedAllocator.rst
index fcd5cef..185c28f 100644
--- a/docs/ScudoHardenedAllocator.rst
+++ b/docs/ScudoHardenedAllocator.rst
@@ -108,7 +108,7 @@
 
 You may also build Scudo like this: 
 
-.. code::
+.. code:: console
 
   cd $LLVM/projects/compiler-rt/lib
   clang++ -fPIC -std=c++11 -msse4.2 -O2 -I. scudo/*.cpp \
@@ -117,7 +117,7 @@
 
 and then use it with existing binaries as follows:
 
-.. code::
+.. code:: console
 
   LD_PRELOAD=`pwd`/libscudo.so ./a.out
 
@@ -151,7 +151,7 @@
 
 For example, using the environment variable:
 
-.. code::
+.. code:: console
 
   SCUDO_OPTIONS="DeleteSizeMismatch=1:QuarantineSizeKb=64" ./a.out
 
@@ -201,3 +201,53 @@
 options, such as ``allocator_may_return_null`` or ``abort_on_error``. A detailed
 list including those can be found here:
 https://github.com/google/sanitizers/wiki/SanitizerCommonFlags.
+
+Error Types
+===========
+
+The allocator will output an error message, and potentially terminate the
+process, when an unexpected behavior is detected. The output usually starts with
+``"Scudo ERROR:"`` followed by a short summary of the problem that occurred as
+well as the pointer(s) involved. Once again, Scudo is meant to be a mitigation,
+and might not be the most useful of tools to help you root-cause the issue,
+please consider `ASan <https://github.com/google/sanitizers/wiki/AddressSanitizer>`_
+for this purpose.
+
+Here is a list of the current error messages and their potential cause:
+
+- ``"corrupted chunk header"``: the checksum verification of the chunk header
+  has failed. This is likely due to one of two things: the header was
+  overwritten (partially or totally), or the pointer passed to the function is
+  not a chunk at all;
+
+- ``"race on chunk header"``: two different threads are attempting to manipulate
+  the same header at the same time. This is usually symptomatic of a
+  race-condition or general lack of locking when performing operations on that
+  chunk;
+
+- ``"invalid chunk state"``: the chunk is not in the expected state for a given
+  operation, eg: it is not allocated when trying to free it, or it's not
+  quarantined when trying to recycle it, etc. A double-free is the typical
+  reason this error would occur;
+
+- ``"misaligned pointer"``: we strongly enforce basic alignment requirements, 8
+  bytes on 32-bit platforms, 16 bytes on 64-bit platforms. If a pointer passed
+  to our functions does not fit those, something is definitely wrong.
+
+- ``"allocation type mismatch"``: when the optional deallocation type mismatch
+  check is enabled, a deallocation function called on a chunk has to match the
+  type of function that was called to allocate it. Security implications of such
+  a mismatch are not necessarily obvious but situational at best;
+
+- ``"invalid sized delete"``: when the C++14 sized delete operator is used, and
+  the optional check enabled, this indicates that the size passed when
+  deallocating a chunk is not congruent with the one requested when allocating
+  it. This is likely to be a `compiler issue <https://software.intel.com/en-us/forums/intel-c-compiler/topic/783942>`_,
+  as was the case with Intel C++ Compiler, or some type confusion on the object
+  being deallocated;
+
+- ``"RSS limit exhausted"``: the maximum RSS optionally specified has been
+  exceeded;
+
+Several other error messages relate to parameter checking on the libc allocation
+APIs and are fairly straightforward to understand.
diff --git a/docs/SourceLevelDebugging.rst b/docs/SourceLevelDebugging.rst
index 1a5ed2f..e7f8b13 100644
--- a/docs/SourceLevelDebugging.rst
+++ b/docs/SourceLevelDebugging.rst
@@ -391,6 +391,441 @@
 The scope information attached with each instruction provides a straightforward
 way to find instructions covered by a scope.
 
+Object lifetime in optimized code
+=================================
+
+In the example above, every variable assignment uniquely corresponds to a
+memory store to the variable's position on the stack. However in heavily
+optimized code LLVM promotes most variables into SSA values, which can
+eventually be placed in physical registers or memory locations. To track SSA
+values through compilation, when objects are promoted to SSA values an
+``llvm.dbg.value`` intrinsic is created for each assignment, recording the
+variable's new location. Compared with the ``llvm.dbg.declare`` intrinsic:
+
+* A dbg.value terminates the effect of any preceeding dbg.values for (any
+  overlapping fragments of) the specified variable.
+* The dbg.value's position in the IR defines where in the instruction stream
+  the variable's value changes.
+* Operands can be constants, indicating the variable is assigned a
+  constant value.
+
+Care must be taken to update ``llvm.dbg.value`` intrinsics when optimization
+passes alter or move instructions and blocks -- the developer could observe such
+changes reflected in the value of variables when debugging the program. For any
+execution of the optimized program, the set of variable values presented to the
+developer by the debugger should not show a state that would never have existed
+in the execution of the unoptimized program, given the same input. Doing so
+risks misleading the developer by reporting a state that does not exist,
+damaging their understanding of the optimized program and undermining their
+trust in the debugger.
+
+Sometimes perfectly preserving variable locations is not possible, often when a
+redundant calculation is optimized out. In such cases, a ``llvm.dbg.value``
+with operand ``undef`` should be used, to terminate earlier variable locations
+and let the debugger present ``optimized out`` to the developer. Withholding
+these potentially stale variable values from the developer diminishes the
+amount of available debug information, but increases the reliability of the
+remaining information.
+ 
+To illustrate some potential issues, consider the following example:
+
+.. code-block:: llvm
+
+  define i32 @foo(i32 %bar, i1 %cond) {
+  entry:
+    call @llvm.dbg.value(metadata i32 0, metadata !1, metadata !2)
+    br i1 %cond, label %truebr, label %falsebr
+  truebr:
+    %tval = add i32 %bar, 1
+    call @llvm.dbg.value(metadata i32 %tval, metadata !1, metadata !2)
+    %g1 = call i32 @gazonk()
+    br label %exit
+  falsebr:
+    %fval = add i32 %bar, 2
+    call @llvm.dbg.value(metadata i32 %fval, metadata !1, metadata !2)
+    %g2 = call i32 @gazonk()
+    br label %exit
+  exit:
+    %merge = phi [ %tval, %truebr ], [ %fval, %falsebr ]
+    %g = phi [ %g1, %truebr ], [ %g2, %falsebr ]
+    call @llvm.dbg.value(metadata i32 %merge, metadata !1, metadata !2)
+    call @llvm.dbg.value(metadata i32 %g, metadata !3, metadata !2)
+    %plusten = add i32 %merge, 10
+    %toret = add i32 %plusten, %g
+    call @llvm.dbg.value(metadata i32 %toret, metadata !1, metadata !2)
+    ret i32 %toret
+  }
+
+Containing two source-level variables in ``!1`` and ``!3``. The function could,
+perhaps, be optimized into the following code:
+
+.. code-block:: llvm
+
+  define i32 @foo(i32 %bar, i1 %cond) {
+  entry:
+    %g = call i32 @gazonk()
+    %addoper = select i1 %cond, i32 11, i32 12
+    %plusten = add i32 %bar, %addoper
+    %toret = add i32 %plusten, %g
+    ret i32 %toret
+  }
+
+What ``llvm.dbg.value`` intrinsics should be placed to represent the original variable
+locations in this code? Unfortunately the the second, third and fourth
+dbg.values for ``!1`` in the source function have had their operands
+(%tval, %fval, %merge) optimized out. Assuming we cannot recover them, we
+might consider this placement of dbg.values:
+
+.. code-block:: llvm
+
+  define i32 @foo(i32 %bar, i1 %cond) {
+  entry:
+    call @llvm.dbg.value(metadata i32 0, metadata !1, metadata !2)
+    %g = call i32 @gazonk()
+    call @llvm.dbg.value(metadata i32 %g, metadata !3, metadata !2)
+    %addoper = select i1 %cond, i32 11, i32 12
+    %plusten = add i32 %bar, %addoper
+    %toret = add i32 %plusten, %g
+    call @llvm.dbg.value(metadata i32 %toret, metadata !1, metadata !2)
+    ret i32 %toret
+  }
+
+However, this will cause ``!3`` to have the return value of ``@gazonk()`` at
+the same time as ``!1`` has the constant value zero -- a pair of assignments
+that never occurred in the unoptimized program. To avoid this, we must terminate
+the range that ``!1`` has the constant value assignment by inserting an undef
+dbg.value before the dbg.value for ``!3``:
+
+.. code-block:: llvm
+
+  define i32 @foo(i32 %bar, i1 %cond) {
+  entry:
+    call @llvm.dbg.value(metadata i32 0, metadata !1, metadata !2)
+    %g = call i32 @gazonk()
+    call @llvm.dbg.value(metadata i32 undef, metadata !1, metadata !2)
+    call @llvm.dbg.value(metadata i32 %g, metadata !3, metadata !2)
+    %addoper = select i1 %cond, i32 11, i32 12
+    %plusten = add i32 %bar, %addoper
+    %toret = add i32 %plusten, %g
+    call @llvm.dbg.value(metadata i32 %toret, metadata !1, metadata !2)
+    ret i32 %toret
+  }
+
+In general, if any dbg.value has its operand optimized out and cannot be
+recovered, then an undef dbg.value is necessary to terminate earlier variable
+locations. Additional undef dbg.values may be necessary when the debugger can
+observe re-ordering of assignments.
+
+How variable location metadata is transformed during CodeGen
+============================================================
+
+LLVM preserves debug information throughout mid-level and backend passes,
+ultimately producing a mapping between source-level information and
+instruction ranges. This
+is relatively straightforwards for line number information, as mapping
+instructions to line numbers is a simple association. For variable locations
+however the story is more complex. As each ``llvm.dbg.value`` intrinsic
+represents a source-level assignment of a value to a source variable, the
+variable location intrinsics effectively embed a small imperative program
+within the LLVM IR. By the end of CodeGen, this becomes a mapping from each
+variable to their machine locations over ranges of instructions.
+From IR to object emission, the major transformations which affect variable
+location fidelity are:
+1. Instruction Selection
+2. Register allocation
+3. Block layout
+
+each of which are discussed below. In addition, instruction scheduling can
+significantly change the ordering of the program, and occurs in a number of
+different passes.
+
+Variable locations in Instruction Selection and MIR
+---------------------------------------------------
+
+Instruction selection creates a MIR function from an IR function, and just as
+it transforms ``intermediate`` instructions into machine instructions, so must
+``intermediate`` variable locations become machine variable locations.
+Within IR, variable locations are always identified by a Value, but in MIR
+there can be different types of variable locations. In addition, some IR
+locations become unavailable, for example if the operation of multiple IR
+instructions are combined into one machine instruction (such as
+multiply-and-accumulate) then intermediate Values are lost. To track variable
+locations through instruction selection, they are first separated into
+locations that do not depend on code generation (constants, stack locations,
+allocated virtual registers) and those that do. For those that do, debug
+metadata is attached to SDNodes in SelectionDAGs. After instruction selection
+has occurred and a MIR function is created, if the SDNode associated with debug
+metadata is allocated a virtual register, that virtual register is used as the
+variable location. If the SDNode is folded into a machine instruction or
+otherwise transformed into a non-register, the variable location becomes
+unavailable.
+
+Locations that are unavailable are treated as if they have been optimized out:
+in IR the location would be assigned ``undef`` by a debug intrinsic, and in MIR
+the equivalent location is used.
+
+After MIR locations are assigned to each variable, machine pseudo-instructions
+corresponding to each ``llvm.dbg.value`` and ``llvm.dbg.addr`` intrinsic are
+inserted. These ``DBG_VALUE`` instructions appear thus:
+
+.. code-block:: text
+
+  DBG_VALUE %1, $noreg, !123, !DIExpression()
+
+And have the following operands:
+ * The first operand can record the variable location as a register, an
+   immediate, or the base address register if the original debug intrinsic
+   referred to memory. ``$noreg`` indicates the variable location is undefined,
+   equivalent to an ``undef`` dbg.value operand.
+ * The type of the second operand indicates whether the variable location is
+   directly referred to by the DBG_VALUE, or whether it is indirect. The
+   ``$noreg`` register signifies the former, an immediate operand (0) the
+   latter.
+ * Operand 3 is the Variable field of the original debug intrinsic.
+ * Operand 4 is the Expression field of the original debug intrinsic.
+
+The position at which the DBG_VALUEs are inserted should correspond to the
+positions of their matching ``llvm.dbg.value`` intrinsics in the IR block.  As
+with optimization, LLVM aims to preserve the order in which variable
+assignments occurred in the source program. However SelectionDAG performs some
+instruction scheduling, which can reorder assignments (discussed below).
+Function parameter locations are moved to the beginning of the function if
+they're not already, to ensure they're immediately available on function entry.
+
+To demonstrate variable locations during instruction selection, consider
+the following example:
+
+.. code-block:: llvm
+
+  define i32 @foo(i32* %addr) {
+  entry:
+    call void @llvm.dbg.value(metadata i32 0, metadata !3, metadata !DIExpression()), !dbg !5
+    br label %bb1, !dbg !5
+
+  bb1:                                              ; preds = %bb1, %entry
+    %bar.0 = phi i32 [ 0, %entry ], [ %add, %bb1 ]
+    call void @llvm.dbg.value(metadata i32 %bar.0, metadata !3, metadata !DIExpression()), !dbg !5
+    %addr1 = getelementptr i32, i32 *%addr, i32 1, !dbg !5
+    call void @llvm.dbg.value(metadata i32 *%addr1, metadata !3, metadata !DIExpression()), !dbg !5
+    %loaded1 = load i32, i32* %addr1, !dbg !5
+    %addr2 = getelementptr i32, i32 *%addr, i32 %bar.0, !dbg !5
+    call void @llvm.dbg.value(metadata i32 *%addr2, metadata !3, metadata !DIExpression()), !dbg !5
+    %loaded2 = load i32, i32* %addr2, !dbg !5
+    %add = add i32 %bar.0, 1, !dbg !5
+    call void @llvm.dbg.value(metadata i32 %add, metadata !3, metadata !DIExpression()), !dbg !5
+    %added = add i32 %loaded1, %loaded2
+    %cond = icmp ult i32 %added, %bar.0, !dbg !5
+    br i1 %cond, label %bb1, label %bb2, !dbg !5
+
+  bb2:                                              ; preds = %bb1
+    ret i32 0, !dbg !5
+  }
+
+If one compiles this IR with ``llc -o - -start-after=codegen-prepare -stop-after=expand-isel-pseudos -mtriple=x86_64--``, the following MIR is produced:
+
+.. code-block:: text
+
+  bb.0.entry:
+    successors: %bb.1(0x80000000)
+    liveins: $rdi
+
+    %2:gr64 = COPY $rdi
+    %3:gr32 = MOV32r0 implicit-def dead $eflags
+    DBG_VALUE 0, $noreg, !3, !DIExpression(), debug-location !5
+
+  bb.1.bb1:
+    successors: %bb.1(0x7c000000), %bb.2(0x04000000)
+
+    %0:gr32 = PHI %3, %bb.0, %1, %bb.1
+    DBG_VALUE %0, $noreg, !3, !DIExpression(), debug-location !5
+    DBG_VALUE %2, $noreg, !3, !DIExpression(DW_OP_plus_uconst, 4, DW_OP_stack_value), debug-location !5
+    %4:gr32 = MOV32rm %2, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)
+    %5:gr64_nosp = MOVSX64rr32 %0, debug-location !5
+    DBG_VALUE $noreg, $noreg, !3, !DIExpression(), debug-location !5
+    %1:gr32 = INC32r %0, implicit-def dead $eflags, debug-location !5
+    DBG_VALUE %1, $noreg, !3, !DIExpression(), debug-location !5
+    %6:gr32 = ADD32rm %4, %2, 4, killed %5, 0, $noreg, implicit-def dead $eflags :: (load 4 from %ir.addr2)
+    %7:gr32 = SUB32rr %6, %0, implicit-def $eflags, debug-location !5
+    JB_1 %bb.1, implicit $eflags, debug-location !5
+    JMP_1 %bb.2, debug-location !5
+
+  bb.2.bb2:
+    %8:gr32 = MOV32r0 implicit-def dead $eflags
+    $eax = COPY %8, debug-location !5
+    RET 0, $eax, debug-location !5
+
+Observe first that there is a DBG_VALUE instruction for every ``llvm.dbg.value``
+intrinsic in the source IR, ensuring no source level assignments go missing.
+Then consider the different ways in which variable locations have been recorded:
+
+* For the first dbg.value an immediate operand is used to record a zero value.
+* The dbg.value of the PHI instruction leads to a DBG_VALUE of virtual register
+  ``%0``.
+* The first GEP has its effect folded into the first load instruction
+  (as a 4-byte offset), but the variable location is salvaged by folding
+  the GEPs effect into the DIExpression.
+* The second GEP is also folded into the corresponding load. However, it is
+  insufficiently simple to be salvaged, and is emitted as a ``$noreg``
+  DBG_VALUE, indicating that the variable takes on an undefined location.
+* The final dbg.value has its Value placed in virtual register ``%1``.
+
+Instruction Scheduling
+----------------------
+
+A number of passes can reschedule instructions, notably instruction selection
+and the pre-and-post RA machine schedulers. Instruction scheduling can
+significantly change the nature of the program -- in the (very unlikely) worst
+case the instruction sequence could be completely reversed. In such
+circumstances LLVM follows the principle applied to optimizations, that it is
+better for the debugger not to display any state than a misleading state.
+Thus, whenever instructions are advanced in order of execution, any
+corresponding DBG_VALUE is kept in its original position, and if an instruction
+is delayed then the variable is given an undefined location for the duration
+of the delay. To illustrate, consider this pseudo-MIR:
+
+.. code-block:: text
+
+  %1:gr32 = MOV32rm %0, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)
+  DBG_VALUE %1, $noreg, !1, !2
+  %4:gr32 = ADD32rr %3, %2, implicit-def dead $eflags
+  DBG_VALUE %4, $noreg, !3, !4
+  %7:gr32 = SUB32rr %6, %5, implicit-def dead $eflags
+  DBG_VALUE %7, $noreg, !5, !6
+
+Imagine that the SUB32rr were moved forward to give us the following MIR:
+
+.. code-block:: text
+
+  %7:gr32 = SUB32rr %6, %5, implicit-def dead $eflags
+  %1:gr32 = MOV32rm %0, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)
+  DBG_VALUE %1, $noreg, !1, !2
+  %4:gr32 = ADD32rr %3, %2, implicit-def dead $eflags
+  DBG_VALUE %4, $noreg, !3, !4
+  DBG_VALUE %7, $noreg, !5, !6
+
+In this circumstance LLVM would leave the MIR as shown above. Were we to move
+the DBG_VALUE of virtual register %7 upwards with the SUB32rr, we would re-order
+assignments and introduce a new state of the program. Wheras with the solution
+above, the debugger will see one fewer combination of variable values, because
+``!3`` and ``!5`` will change value at the same time. This is preferred over
+misrepresenting the original program.
+
+In comparison, if one sunk the MOV32rm, LLVM would produce the following:
+
+.. code-block:: text
+
+  DBG_VALUE $noreg, $noreg, !1, !2
+  %4:gr32 = ADD32rr %3, %2, implicit-def dead $eflags
+  DBG_VALUE %4, $noreg, !3, !4
+  %7:gr32 = SUB32rr %6, %5, implicit-def dead $eflags
+  DBG_VALUE %7, $noreg, !5, !6
+  %1:gr32 = MOV32rm %0, 1, $noreg, 4, $noreg, debug-location !5 :: (load 4 from %ir.addr1)
+  DBG_VALUE %1, $noreg, !1, !2
+
+Here, to avoid presenting a state in which the first assignment to ``!1``
+disappears, the DBG_VALUE at the top of the block assigns the variable the
+undefined location, until its value is available at the end of the block where
+an additional DBG_VALUE is added. Were any other DBG_VALUE for ``!1`` to occur
+in the instructions that the MOV32rm was sunk past, the DBG_VALUE for ``%1``
+would be dropped and the debugger would never observe it in the variable. This
+accurately reflects that the value is not available during the corresponding
+portion of the original program.
+
+Variable locations during Register Allocation
+---------------------------------------------
+
+To avoid debug instructions interfering with the register allocator, the
+LiveDebugVariables pass extracts variable locations from a MIR function and
+deletes the corresponding DBG_VALUE instructions. Some localized copy
+propagation is performed within blocks. After register allocation, the
+VirtRegRewriter pass re-inserts DBG_VALUE instructions in their orignal
+positions, translating virtual register references into their physical
+machine locations. To avoid encoding incorrect variable locations, in this
+pass any DBG_VALUE of a virtual register that is not live, is replaced by
+the undefined location.
+
+LiveDebugValues expansion of variable locations
+-----------------------------------------------
+
+After all optimizations have run and shortly before emission, the
+LiveDebugValues pass runs to achieve two aims:
+
+* To propagate the location of variables through copies and register spills,
+* For every block, to record every valid variable location in that block.
+
+After this pass the DBG_VALUE instruction changes meaning: rather than
+corresponding to a source-level assignment where the variable may change value,
+it asserts the location of a variable in a block, and loses effect outside the
+block. Propagating variable locations through copies and spills is
+straightforwards: determining the variable location in every basic block
+requries the consideraton of control flow. Consider the following IR, which
+presents several difficulties:
+
+.. code-block:: text
+
+  define dso_local i32 @foo(i1 %cond, i32 %input) !dbg !12 {
+  entry:
+    br i1 %cond, label %truebr, label %falsebr
+
+  bb1: 
+    %value = phi i32 [ %value1, %truebr ], [ %value2, %falsebr ]
+    br label %exit, !dbg !26
+
+  truebr:
+    call void @llvm.dbg.value(metadata i32 %input, metadata !30, metadata !DIExpression()), !dbg !24
+    call void @llvm.dbg.value(metadata i32 1, metadata !23, metadata !DIExpression()), !dbg !24
+    %value1 = add i32 %input, 1
+    br label %bb1
+
+  falsebr:
+    call void @llvm.dbg.value(metadata i32 %input, metadata !30, metadata !DIExpression()), !dbg !24
+    call void @llvm.dbg.value(metadata i32 2, metadata !23, metadata !DIExpression()), !dbg !24
+    %value = add i32 %input, 2
+    br label %bb1
+
+  exit: 
+    ret i32 %value, !dbg !30
+  }
+
+Here the difficulties are:
+
+* The control flow is roughly the opposite of basic block order
+* The value of the ``!23`` variable merges into ``%bb1``, but there is no PHI
+  node
+
+As mentioned above, the ``llvm.dbg.value`` intrinsics essentially form an
+imperative program embedded in the IR, with each intrinsic defining a variable
+location. This *could* be converted to an SSA form by mem2reg, in the same way
+that it uses use-def chains to identify control flow merges and insert phi
+nodes for IR Values. However, because debug variable locations are defined for
+every machine instruction, in effect every IR instruction uses every variable
+location, which would lead to a large number of debugging intrinsics being
+generated.
+
+Examining the example above, variable ``!30`` is assigned ``%input`` on both
+conditional paths through the function, while ``!23`` is assigned differing
+constant values on either path. Where control flow merges in ``%bb1`` we would
+want ``!30`` to keep its location (``%input``), but ``!23`` to become undefined
+as we cannot determine at runtime what value it should have in %bb1 without
+inserting a PHI node. mem2reg does not insert the PHI node to avoid changing
+codegen when debugging is enabled, and does not insert the other dbg.values
+to avoid adding very large numbers of intrinsics.
+
+Instead, LiveDebugValues determines variable locations when control
+flow merges. A dataflow analysis is used to propagate locations between blocks:
+when control flow merges, if a variable has the same location in all
+predecessors then that location is propagated into the successor. If the
+predecessor locations disagree, the location becomes undefined.
+
+Once LiveDebugValues has run, every block should have all valid variable
+locations described by DBG_VALUE instructions within the block. Very little
+effort is then required by supporting classes (such as
+DbgEntityHistoryCalculator) to build a map of each instruction to every
+valid variable location, without the need to consider control flow. From
+the example above, it is otherwise difficult to determine that the location
+of variable ``!30`` should flow "up" into block ``%bb1``, but that the location
+of variable ``!23`` should not flow "down" into the ``%exit`` block.
+
 .. _ccxx_frontend:
 
 C/C++ front-end specific debug information
@@ -545,6 +980,37 @@
   ...
   }
 
+Fortran specific debug information
+==================================
+
+Fortran function information
+----------------------------
+
+There are a few DWARF attributes defined to support client debugging of Fortran programs.  LLVM can generate (or omit) the appropriate DWARF attributes for the prefix-specs of ELEMENTAL, PURE, IMPURE, RECURSIVE, and NON_RECURSIVE.  This is done by using the spFlags values: DISPFlagElemental, DISPFlagPure, and DISPFlagRecursive.
+
+.. code-block:: fortran
+
+  elemental function elem_func(a)
+
+a Fortran front-end would generate the following descriptors:
+
+.. code-block:: text
+
+  !11 = distinct !DISubprogram(name: "subroutine2", scope: !1, file: !1,
+          line: 5, type: !8, scopeLine: 6,
+          spFlags: DISPFlagDefinition | DISPFlagElemental, unit: !0,
+          retainedNodes: !2)
+
+and this will materialize an additional DWARF attribute as:
+
+.. code-block:: text
+
+  DW_TAG_subprogram [3]  
+     DW_AT_low_pc [DW_FORM_addr]     (0x0000000000000010 ".text")
+     DW_AT_high_pc [DW_FORM_data4]   (0x00000001)
+     ...
+     DW_AT_elemental [DW_FORM_flag_present]  (true)
+
 Debugging information format
 ============================
 
@@ -1466,7 +1932,7 @@
 * Testing MSVC's output::
 
     $ cl -c -Z7 foo.cpp # Use /Z7 to keep types in the object file
-    $ llvm-readobj -codeview foo.obj
+    $ llvm-readobj --codeview foo.obj
 
 * Getting LLVM IR debug info out of Clang::
 
@@ -1477,7 +1943,7 @@
 * Generate and dump CodeView from LLVM IR metadata::
 
     $ llc foo.ll -filetype=obj -o foo.obj
-    $ llvm-readobj -codeview foo.obj > foo.txt
+    $ llvm-readobj --codeview foo.obj > foo.txt
 
   Use this pattern in lit test cases and FileCheck the output of llvm-readobj
 
diff --git a/docs/SpeculativeLoadHardening.md b/docs/SpeculativeLoadHardening.md
index 0911b7c..de6dc01 100644
--- a/docs/SpeculativeLoadHardening.md
+++ b/docs/SpeculativeLoadHardening.md
@@ -255,7 +255,7 @@
   memcpy(local_buffer, untrusted_data_from_caller,
          untrusted_size_from_caller);
   // The stack has now been smashed, writing an attacker-controlled
-  // address over the return adress.
+  // address over the return address.
   minor_processing(local_buffer);
   return;
   // Control will speculate to the attacker-written address.
diff --git a/docs/TableGen/LangIntro.rst b/docs/TableGen/LangIntro.rst
index ea46550..45104ac 100644
--- a/docs/TableGen/LangIntro.rst
+++ b/docs/TableGen/LangIntro.rst
@@ -189,6 +189,10 @@
     More than two arguments are accepted with the result being the concatenation
     of all the lists given.
 
+``!listsplat(a, size)``
+    A list value that contains the value ``a`` ``size`` times.
+    Example: ``!listsplat(0, 2)`` results in ``[0, 0]``.
+
 ``!strconcat(a, b, ...)``
     A string value that is the result of concatenating the 'a' and 'b' strings.
     More than two arguments are accepted with the result being the concatenation
@@ -258,6 +262,16 @@
 ``!if(a,b,c)``
   'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
 
+``!cond(condition_1 : val1, condition_2 : val2, ..., condition_n : valn)``
+    Instead of embedding !if inside !if which can get cumbersome,
+    one can use !cond. !cond returns 'val1' if the result of 'int' or 'bit'
+    operator 'condition1' is nonzero. Otherwise, it checks 'condition2'.
+    If 'condition2' is nonzero, returns 'val2', and so on.
+    If all conditions are zero, it reports an error.  
+
+    For example, to convert an integer 'x' into a string:
+      !cond(!lt(x,0) : "negative", !eq(x,0) : "zero", 1 : "positive")
+
 ``!eq(a,b)``
     'bit 1' if string a is equal to string b, 0 otherwise.  This only operates
     on string, int and bit objects.  Use !cast<string> to compare other types of
@@ -274,7 +288,7 @@
     The usual shift operators. Operations are on 64-bit integers, the result
     is undefined for shift counts outside [0, 63].
 
-``!add(a,b,...)`` ``!and(a,b,...)`` ``!or(a,b,...)``
+``!add(a,b,...)`` ``!mul(a,b,...)`` ``!and(a,b,...)`` ``!or(a,b,...)``
     The usual arithmetic and binary operators.
 
 Note that all of the values have rules specifying how they convert to values
diff --git a/docs/TableGen/LangRef.rst b/docs/TableGen/LangRef.rst
index 2efee12..195106a 100644
--- a/docs/TableGen/LangRef.rst
+++ b/docs/TableGen/LangRef.rst
@@ -100,7 +100,13 @@
                :!or     !empty   !subst   !foreach   !strconcat
                :!cast   !listconcat       !size      !foldl
                :!isa    !dag     !le      !lt        !ge
-               :!gt     !ne
+               :!gt     !ne      !mul     !listsplat
+
+TableGen also has !cond operator that needs a slightly different
+syntax compared to other "bang operators":
+
+.. productionlist::
+   CondOperator: !cond
 
 
 Syntax
@@ -140,7 +146,7 @@
 #. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.
 #. The :token:`BaseClassList` in the :token:`ObjectBody` is present.
 
-You can declare an empty class by giving and empty :token:`TemplateArgList`
+You can declare an empty class by giving an empty :token:`TemplateArgList`
 and an empty :token:`ObjectBody`. This can serve as a restricted form of
 forward declaration: note that records deriving from the forward-declared
 class will inherit no fields from it since the record expansion is done
@@ -315,6 +321,8 @@
 
 .. productionlist::
    SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
+              :| `CondOperator` "(" `CondVal` ("," `CondVal`)* ")"
+   CondVal: `Value` ":" `Value`
 
 Bodies
 ------
diff --git a/docs/TestSuiteGuide.md b/docs/TestSuiteGuide.md
index 0d9bbac..d23b383 100644
--- a/docs/TestSuiteGuide.md
+++ b/docs/TestSuiteGuide.md
@@ -27,7 +27,7 @@
 2. Check out the `test-suite` module with:
 
    ```bash
-   % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
+   % git clone https://github.com/llvm/llvm-test-suite.git test-suite
    ```
 
 3. Create a build directory and use CMake to configure the suite. Use the
diff --git a/docs/TestSuiteMakefileGuide.rst b/docs/TestSuiteMakefileGuide.rst
index dfd12d7..246da55 100644
--- a/docs/TestSuiteMakefileGuide.rst
+++ b/docs/TestSuiteMakefileGuide.rst
@@ -14,14 +14,14 @@
 
 To run the test suite, you need to use the following steps:
 
-#. ``cd`` into the ``llvm/projects`` directory in your source tree.
 #. Check out the ``test-suite`` module with:
 
    .. code-block:: bash
 
-       % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
+       % git clone https://github.com/llvm/llvm-test-suite.git test-suite
 
-   This will get the test suite into ``llvm/projects/test-suite``.
+#. FIXME: these directions are outdated and won't work. Figure out
+   what the correct thing to do is, and write it down here.
 
 #. Configure and build ``llvm``.
 
diff --git a/docs/TestingGuide.rst b/docs/TestingGuide.rst
index e3db60d..949fecf 100644
--- a/docs/TestingGuide.rst
+++ b/docs/TestingGuide.rst
@@ -29,10 +29,11 @@
 LLVM Testing Infrastructure Organization
 ========================================
 
-The LLVM testing infrastructure contains two major categories of tests:
-regression tests and whole programs. The regression tests are contained
-inside the LLVM repository itself under ``llvm/test`` and are expected
-to always pass -- they should be run before every commit.
+The LLVM testing infrastructure contains three major categories of tests:
+unit tests, regression tests and whole programs. The unit tests and regression
+tests are contained inside the LLVM repository itself under ``llvm/unittests``
+and ``llvm/test`` respectively and are expected to always pass -- they should be
+run before every commit.
 
 The whole programs tests are referred to as the "LLVM test suite" (or
 "test-suite") and are in the ``test-suite`` module in subversion. For
@@ -40,6 +41,13 @@
 tests" in places, which is less ambiguous than "test-suite" and remains
 in use although we run them much more often than nightly.
 
+Unit tests
+----------
+
+Unit tests are written using `Google Test <https://github.com/google/googletest/blob/master/googletest/docs/primer.md>`_
+and `Google Mock <https://github.com/google/googletest/blob/master/googlemock/docs/ForDummies.md>`_
+and are located in the ``llvm/unittests`` directory.
+
 Regression tests
 ----------------
 
@@ -90,16 +98,23 @@
 Quick start
 ===========
 
-The tests are located in two separate Subversion modules. The
-regressions tests are in the main "llvm" module under the directory
-``llvm/test`` (so you get these tests for free with the main LLVM tree).
-Use ``make check-all`` to run the regression tests after building LLVM.
+The tests are located in two separate Subversion modules. The unit and
+regression tests are in the main "llvm" module under the directories
+``llvm/unittests`` and ``llvm/test`` (so you get these tests for free with the
+main LLVM tree). Use ``make check-all`` to run the unit and regression tests
+after building LLVM.
 
 The ``test-suite`` module contains more comprehensive tests including whole C
 and C++ programs. See the :doc:`TestSuiteGuide` for details.
 
-Regression tests
-----------------
+Unit and Regression tests
+-------------------------
+
+To run all of the LLVM unit tests use the check-llvm-unit target:
+
+.. code-block:: bash
+
+    % make check-llvm-unit
 
 To run all of the LLVM regression tests use the check-llvm target:
 
@@ -107,6 +122,13 @@
 
     % make check-llvm
 
+In order to get reasonable testing performance, build LLVM and subprojects
+in release mode, i.e.
+
+.. code-block:: bash
+
+    % cmake -DCMAKE_BUILD_TYPE="Release" -DLLVM_ENABLE_ASSERTIONS=On
+
 If you have `Clang <http://clang.llvm.org/>`_ checked out and built, you
 can run the LLVM and Clang tests simultaneously using:
 
@@ -143,15 +165,9 @@
 Debugging Information tests
 ---------------------------
 
-To run debugging information tests simply checkout the tests inside
-clang/test directory.
-
-.. code-block:: bash
-
-    % cd clang/test
-    % svn co http://llvm.org/svn/llvm-project/debuginfo-tests/trunk debuginfo-tests
-
-These tests are already set up to run as part of clang regression tests.
+To run debugging information tests simply add the ``debuginfo-tests``
+project to your ``LLVM_ENABLE_PROJECTS`` define on the cmake
+command-line.
 
 Regression test structure
 =========================
diff --git a/docs/XRayExample.rst b/docs/XRayExample.rst
index ca24324..5acf90f 100644
--- a/docs/XRayExample.rst
+++ b/docs/XRayExample.rst
@@ -266,7 +266,7 @@
 ::
 
   $ llvm-xray convert -symbolize -instr_map=./bin/llc \
-    -output_format=trace_event xray-log.llc.5rqxkU \
+    -output-format=trace_event xray-log.llc.5rqxkU \
       | gzip > llc-trace.txt.gz
 
 From a Chrome browser, navigating to ``chrome:///tracing`` allows us to load
diff --git a/docs/conf.py b/docs/conf.py
index 7fdcb3d..4a52df8 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -11,7 +11,7 @@
 # serve to show the default.
 from __future__ import print_function
 
-import sys, os
+import sys, os, re
 from datetime import date
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -51,9 +51,9 @@
 # built documents.
 #
 # The short version.
-version = '8'
+version = '9'
 # The full version, including alpha/beta/rc tags.
-release = '8'
+release = '9'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -223,32 +223,50 @@
 man_page_authors = "Maintained by the LLVM Team (https://llvm.org/)."
 command_guide_subpath = 'CommandGuide'
 command_guide_path = os.path.join(basedir, command_guide_subpath)
-for name in os.listdir(command_guide_path):
-    # Ignore non-ReST files and the index page.
-    if not name.endswith('.rst') or name in ('index.rst',):
-        continue
 
-    # Otherwise, automatically extract the description.
+
+def process_md(name):
+    file_subpath = os.path.join(command_guide_subpath, name)
+    with open(os.path.join(command_guide_path, name)) as f:
+        title = f.readline().rstrip('\n')
+
+        m = re.match(r'^# (\S+) - (.+)$', title)
+        if m is None:
+            print("error: invalid title in %r "
+                  "(expected '# <name> - <description>')" % file_subpath,
+                  file=sys.stderr)
+        else:
+            man_pages.append((file_subpath.replace('.md',''), m.group(1),
+                              m.group(2), man_page_authors, 1))
+
+
+def process_rst(name):
     file_subpath = os.path.join(command_guide_subpath, name)
     with open(os.path.join(command_guide_path, name)) as f:
         title = f.readline().rstrip('\n')
         header = f.readline().rstrip('\n')
 
         if len(header) != len(title):
-            print((
-                "error: invalid header in %r (does not match title)" % (
-                    file_subpath,)), file=sys.stderr)
+            print('error: invalid header in %r (does not match title)' %
+                  file_subpath, file=sys.stderr)
         if ' - ' not in title:
-            print((
-                ("error: invalid title in %r "
-                 "(expected '<name> - <description>')") % (
-                    file_subpath,)), file=sys.stderr)
-
+            print("error: invalid title in %r "
+                  "(expected '<name> - <description>')" % file_subpath,
+                  file=sys.stderr)
         # Split the name out of the title.
         name,description = title.split(' - ', 1)
         man_pages.append((file_subpath.replace('.rst',''), name,
                           description, man_page_authors, 1))
 
+
+for name in os.listdir(command_guide_path):
+    # Process Markdown files
+    if name.endswith('.md'):
+        process_md(name)
+    # Process ReST files apart from the index page.
+    elif name.endswith('.rst') and name != 'index.rst':
+        process_rst(name)
+
 # If true, show URL addresses after external links.
 #man_show_urls = False
 
diff --git a/docs/index.rst b/docs/index.rst
index 4527fe5..b03e6b7 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -55,11 +55,10 @@
 
 For those new to the LLVM system.
 
-NOTE: If you are a user who is only interested in using LLVM-based
-compilers, you should look into `Clang <http://clang.llvm.org>`_ or
-`DragonEgg <http://dragonegg.llvm.org>`_ instead. The documentation here is
-intended for users who have a need to work with the intermediate LLVM
-representation.
+NOTE: If you are a user who is only interested in using an LLVM-based compiler,
+you should look into `Clang <http://clang.llvm.org>`_ instead. The
+documentation here is intended for users who have a need to work with the
+intermediate LLVM representation.
 
 .. toctree::
    :hidden:
@@ -268,6 +267,7 @@
    Bugpoint
    CodeGenerator
    ExceptionHandling
+   AddingConstrainedIntrinsics
    LinkTimeOptimization
    SegmentedStacks
    TableGenFundamentals
@@ -346,6 +346,10 @@
    This document describes the design and implementation of exception handling
    in LLVM.
 
+:doc:`AddingConstrainedIntrinsics`
+   Gives the steps necessary when adding a new constrained math intrinsic
+   to LLVM.
+
 :doc:`Bugpoint`
    Automatic bug finder and test-case reducer description and usage
    information.
@@ -554,7 +558,6 @@
 
   * llvmbb - Bot for the main LLVM buildbot master.
     http://lab.llvm.org:8011/console
-  * bb-chapuni - An individually run buildbot master. http://bb.pgr.jp/console
   * smooshlab - Apple's internal buildbot master.
 
 * robot - Bugzilla linker. %bug <number>
@@ -574,6 +577,7 @@
    CodeOfConduct
    Proposals/GitHubMove
    Proposals/TestSuite
+   Proposals/VariableNames
    Proposals/VectorizationPlan
 
 :doc:`CodeOfConduct`
@@ -586,6 +590,9 @@
 :doc:`Proposals/TestSuite`
    Proposals for additional benchmarks/programs for llvm's test-suite.
 
+:doc:`Proposals/VariableNames`
+   Proposal to change the variable names coding standard.
+
 :doc:`Proposals/VectorizationPlan`
    Proposal to model the process and upgrade the infrastructure of LLVM's Loop Vectorizer.
 
diff --git a/docs/llvm-objdump.1 b/docs/llvm-objdump.1
index 72d1b93..85c40d7 100644
--- a/docs/llvm-objdump.1
+++ b/docs/llvm-objdump.1
@@ -1,5 +1,6 @@
-.\" This file is distributed under the University of Illinois Open Source
-.\" License. See LICENSE.TXT for details.
+.\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+.\" See https://llvm.org/LICENSE.txt for license information.
+.\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 .\"
 .Dd December 19, 2018
 .Dt LLVM-OBJDUMP 1
diff --git a/docs/tutorial/LangImpl03.rst b/docs/tutorial/LangImpl03.rst
index 1f2d20f..da465ef 100644
--- a/docs/tutorial/LangImpl03.rst
+++ b/docs/tutorial/LangImpl03.rst
@@ -275,7 +275,7 @@
         FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
 
       Function *F =
-        Function::Create(FT, Function::ExternalLinkage, Name, TheModule);
+        Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
 
 This code packs a lot of power into a few lines. Note first that this
 function returns a "Function\*" instead of a "Value\*". Because a
diff --git a/docs/tutorial/LangImpl04.rst b/docs/tutorial/LangImpl04.rst
index 8927a91..bdd21d6 100644
--- a/docs/tutorial/LangImpl04.rst
+++ b/docs/tutorial/LangImpl04.rst
@@ -94,6 +94,14 @@
 LLVM Optimization Passes
 ========================
 
+.. warning::
+
+   Due to the transition to the new PassManager infrastructure this tutorial
+   is based on ``llvm::legacy::FunctionPassManager`` which can be found in
+   `LegacyPassManager.h <http://llvm.org/doxygen/classllvm_1_1legacy_1_1FunctionPassManager.html>`_.
+   For the purpose of the this tutorial the above should be used until
+   the pass manager transition is complete.
+
 LLVM provides many optimization passes, which do many different sorts of
 things and have different tradeoffs. Unlike other systems, LLVM doesn't
 hold to the mistaken notion that one set of optimizations is right for
diff --git a/docs/tutorial/LangImpl08.rst b/docs/tutorial/LangImpl08.rst
index da4e60f..4f28a2a 100644
--- a/docs/tutorial/LangImpl08.rst
+++ b/docs/tutorial/LangImpl08.rst
@@ -157,7 +157,7 @@
   legacy::PassManager pass;
   auto FileType = TargetMachine::CGFT_ObjectFile;
 
-  if (TargetMachine->addPassesToEmitFile(pass, dest, FileType)) {
+  if (TargetMachine->addPassesToEmitFile(pass, dest, nullptr, FileType)) {
     errs() << "TargetMachine can't emit a file of this type";
     return 1;
   }
diff --git a/docs/tutorial/LangImpl10.rst b/docs/tutorial/LangImpl10.rst
index 5799c99..b1d19c2 100644
--- a/docs/tutorial/LangImpl10.rst
+++ b/docs/tutorial/LangImpl10.rst
@@ -174,15 +174,10 @@
 -------------------------------
 
 One thing about LLVM that turns off many people is that it does not
-solve all the world's problems in one system (sorry 'world hunger',
-someone else will have to solve you some other day). One specific
+solve all the world's problems in one system.  One specific
 complaint is that people perceive LLVM as being incapable of performing
 high-level language-specific optimization: LLVM "loses too much
-information".
-
-Unfortunately, this is really not the place to give you a full and
-unified version of "Chris Lattner's theory of compiler design". Instead,
-I'll make a few observations:
+information".  Here are a few observations about this:
 
 First, you're right that LLVM does lose information. For example, as of
 this writing, there is no way to distinguish in the LLVM IR whether an
diff --git a/docs/tutorial/MyFirstLanguageFrontend/LangImpl01.rst b/docs/tutorial/MyFirstLanguageFrontend/LangImpl01.rst
new file mode 100644
index 0000000..8cf01c8
--- /dev/null
+++ b/docs/tutorial/MyFirstLanguageFrontend/LangImpl01.rst
@@ -0,0 +1,196 @@
+:orphan:
+
+=====================================================
+Kaleidoscope: Kaleidoscope Introduction and the Lexer
+=====================================================
+
+.. contents::
+   :local:
+
+The Kaleidoscope Language
+=========================
+
+This tutorial is illustrated with a toy language called
+"`Kaleidoscope <http://en.wikipedia.org/wiki/Kaleidoscope>`_" (derived
+from "meaning beautiful, form, and view"). Kaleidoscope is a procedural
+language that allows you to define functions, use conditionals, math,
+etc. Over the course of the tutorial, we'll extend Kaleidoscope to
+support the if/then/else construct, a for loop, user defined operators,
+JIT compilation with a simple command line interface, debug info, etc.
+
+We want to keep things simple, so the only datatype in Kaleidoscope
+is a 64-bit floating point type (aka 'double' in C parlance). As such,
+all values are implicitly double precision and the language doesn't
+require type declarations. This gives the language a very nice and
+simple syntax. For example, the following simple example computes
+`Fibonacci numbers: <http://en.wikipedia.org/wiki/Fibonacci_number>`_
+
+::
+
+    # Compute the x'th fibonacci number.
+    def fib(x)
+      if x < 3 then
+        1
+      else
+        fib(x-1)+fib(x-2)
+
+    # This expression will compute the 40th number.
+    fib(40)
+
+We also allow Kaleidoscope to call into standard library functions - the
+LLVM JIT makes this really easy. This means that you can use the
+'extern' keyword to define a function before you use it (this is also
+useful for mutually recursive functions).  For example:
+
+::
+
+    extern sin(arg);
+    extern cos(arg);
+    extern atan2(arg1 arg2);
+
+    atan2(sin(.4), cos(42))
+
+A more interesting example is included in Chapter 6 where we write a
+little Kaleidoscope application that `displays a Mandelbrot
+Set <LangImpl06.html#kicking-the-tires>`_ at various levels of magnification.
+
+Let's dive into the implementation of this language!
+
+The Lexer
+=========
+
+When it comes to implementing a language, the first thing needed is the
+ability to process a text file and recognize what it says. The
+traditional way to do this is to use a
+"`lexer <http://en.wikipedia.org/wiki/Lexical_analysis>`_" (aka
+'scanner') to break the input up into "tokens". Each token returned by
+the lexer includes a token code and potentially some metadata (e.g. the
+numeric value of a number). First, we define the possibilities:
+
+.. code-block:: c++
+
+    // The lexer returns tokens [0-255] if it is an unknown character, otherwise one
+    // of these for known things.
+    enum Token {
+      tok_eof = -1,
+
+      // commands
+      tok_def = -2,
+      tok_extern = -3,
+
+      // primary
+      tok_identifier = -4,
+      tok_number = -5,
+    };
+
+    static std::string IdentifierStr; // Filled in if tok_identifier
+    static double NumVal;             // Filled in if tok_number
+
+Each token returned by our lexer will either be one of the Token enum
+values or it will be an 'unknown' character like '+', which is returned
+as its ASCII value. If the current token is an identifier, the
+``IdentifierStr`` global variable holds the name of the identifier. If
+the current token is a numeric literal (like 1.0), ``NumVal`` holds its
+value. We use global variables for simplicity, but this is not the
+best choice for a real language implementation :).
+
+The actual implementation of the lexer is a single function named
+``gettok``. The ``gettok`` function is called to return the next token
+from standard input. Its definition starts as:
+
+.. code-block:: c++
+
+    /// gettok - Return the next token from standard input.
+    static int gettok() {
+      static int LastChar = ' ';
+
+      // Skip any whitespace.
+      while (isspace(LastChar))
+        LastChar = getchar();
+
+``gettok`` works by calling the C ``getchar()`` function to read
+characters one at a time from standard input. It eats them as it
+recognizes them and stores the last character read, but not processed,
+in LastChar. The first thing that it has to do is ignore whitespace
+between tokens. This is accomplished with the loop above.
+
+The next thing ``gettok`` needs to do is recognize identifiers and
+specific keywords like "def". Kaleidoscope does this with this simple
+loop:
+
+.. code-block:: c++
+
+      if (isalpha(LastChar)) { // identifier: [a-zA-Z][a-zA-Z0-9]*
+        IdentifierStr = LastChar;
+        while (isalnum((LastChar = getchar())))
+          IdentifierStr += LastChar;
+
+        if (IdentifierStr == "def")
+          return tok_def;
+        if (IdentifierStr == "extern")
+          return tok_extern;
+        return tok_identifier;
+      }
+
+Note that this code sets the '``IdentifierStr``' global whenever it
+lexes an identifier. Also, since language keywords are matched by the
+same loop, we handle them here inline. Numeric values are similar:
+
+.. code-block:: c++
+
+      if (isdigit(LastChar) || LastChar == '.') {   // Number: [0-9.]+
+        std::string NumStr;
+        do {
+          NumStr += LastChar;
+          LastChar = getchar();
+        } while (isdigit(LastChar) || LastChar == '.');
+
+        NumVal = strtod(NumStr.c_str(), 0);
+        return tok_number;
+      }
+
+This is all pretty straightforward code for processing input. When
+reading a numeric value from input, we use the C ``strtod`` function to
+convert it to a numeric value that we store in ``NumVal``. Note that
+this isn't doing sufficient error checking: it will incorrectly read
+"1.23.45.67" and handle it as if you typed in "1.23". Feel free to
+extend it!  Next we handle comments:
+
+.. code-block:: c++
+
+      if (LastChar == '#') {
+        // Comment until end of line.
+        do
+          LastChar = getchar();
+        while (LastChar != EOF && LastChar != '\n' && LastChar != '\r');
+
+        if (LastChar != EOF)
+          return gettok();
+      }
+
+We handle comments by skipping to the end of the line and then return
+the next token. Finally, if the input doesn't match one of the above
+cases, it is either an operator character like '+' or the end of the
+file. These are handled with this code:
+
+.. code-block:: c++
+
+      // Check for end of file.  Don't eat the EOF.
+      if (LastChar == EOF)
+        return tok_eof;
+
+      // Otherwise, just return the character as its ascii value.
+      int ThisChar = LastChar;
+      LastChar = getchar();
+      return ThisChar;
+    }
+
+With this, we have the complete lexer for the basic Kaleidoscope
+language (the `full code listing <LangImpl02.html#full-code-listing>`_ for the Lexer
+is available in the `next chapter <LangImpl02.html>`_ of the tutorial).
+Next we'll `build a simple parser that uses this to build an Abstract
+Syntax Tree <LangImpl02.html>`_. When we have that, we'll include a
+driver so that you can use the lexer and parser together.
+
+`Next: Implementing a Parser and AST <LangImpl02.html>`_
+
diff --git a/docs/tutorial/MyFirstLanguageFrontend/LangImpl02.rst b/docs/tutorial/MyFirstLanguageFrontend/LangImpl02.rst
new file mode 100644
index 0000000..3a26800
--- /dev/null
+++ b/docs/tutorial/MyFirstLanguageFrontend/LangImpl02.rst
@@ -0,0 +1,739 @@
+:orphan:
+
+===========================================
+Kaleidoscope: Implementing a Parser and AST
+===========================================
+
+.. contents::
+   :local:
+
+Chapter 2 Introduction
+======================
+
+Welcome to Chapter 2 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. This chapter shows you how to use the
+lexer, built in `Chapter 1 <LangImpl01.html>`_, to build a full
+`parser <http://en.wikipedia.org/wiki/Parsing>`_ for our Kaleidoscope
+language. Once we have a parser, we'll define and build an `Abstract
+Syntax Tree <http://en.wikipedia.org/wiki/Abstract_syntax_tree>`_ (AST).
+
+The parser we will build uses a combination of `Recursive Descent
+Parsing <http://en.wikipedia.org/wiki/Recursive_descent_parser>`_ and
+`Operator-Precedence
+Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_ to
+parse the Kaleidoscope language (the latter for binary expressions and
+the former for everything else). Before we get to parsing though, let's
+talk about the output of the parser: the Abstract Syntax Tree.
+
+The Abstract Syntax Tree (AST)
+==============================
+
+The AST for a program captures its behavior in such a way that it is
+easy for later stages of the compiler (e.g. code generation) to
+interpret. We basically want one object for each construct in the
+language, and the AST should closely model the language. In
+Kaleidoscope, we have expressions, a prototype, and a function object.
+We'll start with expressions first:
+
+.. code-block:: c++
+
+    /// ExprAST - Base class for all expression nodes.
+    class ExprAST {
+    public:
+      virtual ~ExprAST() {}
+    };
+
+    /// NumberExprAST - Expression class for numeric literals like "1.0".
+    class NumberExprAST : public ExprAST {
+      double Val;
+
+    public:
+      NumberExprAST(double Val) : Val(Val) {}
+    };
+
+The code above shows the definition of the base ExprAST class and one
+subclass which we use for numeric literals. The important thing to note
+about this code is that the NumberExprAST class captures the numeric
+value of the literal as an instance variable. This allows later phases
+of the compiler to know what the stored numeric value is.
+
+Right now we only create the AST, so there are no useful accessor
+methods on them. It would be very easy to add a virtual method to pretty
+print the code, for example. Here are the other expression AST node
+definitions that we'll use in the basic form of the Kaleidoscope
+language:
+
+.. code-block:: c++
+
+    /// VariableExprAST - Expression class for referencing a variable, like "a".
+    class VariableExprAST : public ExprAST {
+      std::string Name;
+
+    public:
+      VariableExprAST(const std::string &Name) : Name(Name) {}
+    };
+
+    /// BinaryExprAST - Expression class for a binary operator.
+    class BinaryExprAST : public ExprAST {
+      char Op;
+      std::unique_ptr<ExprAST> LHS, RHS;
+
+    public:
+      BinaryExprAST(char op, std::unique_ptr<ExprAST> LHS,
+                    std::unique_ptr<ExprAST> RHS)
+        : Op(op), LHS(std::move(LHS)), RHS(std::move(RHS)) {}
+    };
+
+    /// CallExprAST - Expression class for function calls.
+    class CallExprAST : public ExprAST {
+      std::string Callee;
+      std::vector<std::unique_ptr<ExprAST>> Args;
+
+    public:
+      CallExprAST(const std::string &Callee,
+                  std::vector<std::unique_ptr<ExprAST>> Args)
+        : Callee(Callee), Args(std::move(Args)) {}
+    };
+
+This is all (intentionally) rather straight-forward: variables capture
+the variable name, binary operators capture their opcode (e.g. '+'), and
+calls capture a function name as well as a list of any argument
+expressions. One thing that is nice about our AST is that it captures
+the language features without talking about the syntax of the language.
+Note that there is no discussion about precedence of binary operators,
+lexical structure, etc.
+
+For our basic language, these are all of the expression nodes we'll
+define. Because it doesn't have conditional control flow, it isn't
+Turing-complete; we'll fix that in a later installment. The two things
+we need next are a way to talk about the interface to a function, and a
+way to talk about functions themselves:
+
+.. code-block:: c++
+
+    /// PrototypeAST - This class represents the "prototype" for a function,
+    /// which captures its name, and its argument names (thus implicitly the number
+    /// of arguments the function takes).
+    class PrototypeAST {
+      std::string Name;
+      std::vector<std::string> Args;
+
+    public:
+      PrototypeAST(const std::string &name, std::vector<std::string> Args)
+        : Name(name), Args(std::move(Args)) {}
+
+      const std::string &getName() const { return Name; }
+    };
+
+    /// FunctionAST - This class represents a function definition itself.
+    class FunctionAST {
+      std::unique_ptr<PrototypeAST> Proto;
+      std::unique_ptr<ExprAST> Body;
+
+    public:
+      FunctionAST(std::unique_ptr<PrototypeAST> Proto,
+                  std::unique_ptr<ExprAST> Body)
+        : Proto(std::move(Proto)), Body(std::move(Body)) {}
+    };
+
+In Kaleidoscope, functions are typed with just a count of their
+arguments. Since all values are double precision floating point, the
+type of each argument doesn't need to be stored anywhere. In a more
+aggressive and realistic language, the "ExprAST" class would probably
+have a type field.
+
+With this scaffolding, we can now talk about parsing expressions and
+function bodies in Kaleidoscope.
+
+Parser Basics
+=============
+
+Now that we have an AST to build, we need to define the parser code to
+build it. The idea here is that we want to parse something like "x+y"
+(which is returned as three tokens by the lexer) into an AST that could
+be generated with calls like this:
+
+.. code-block:: c++
+
+      auto LHS = llvm::make_unique<VariableExprAST>("x");
+      auto RHS = llvm::make_unique<VariableExprAST>("y");
+      auto Result = std::make_unique<BinaryExprAST>('+', std::move(LHS),
+                                                    std::move(RHS));
+
+In order to do this, we'll start by defining some basic helper routines:
+
+.. code-block:: c++
+
+    /// CurTok/getNextToken - Provide a simple token buffer.  CurTok is the current
+    /// token the parser is looking at.  getNextToken reads another token from the
+    /// lexer and updates CurTok with its results.
+    static int CurTok;
+    static int getNextToken() {
+      return CurTok = gettok();
+    }
+
+This implements a simple token buffer around the lexer. This allows us
+to look one token ahead at what the lexer is returning. Every function
+in our parser will assume that CurTok is the current token that needs to
+be parsed.
+
+.. code-block:: c++
+
+
+    /// LogError* - These are little helper functions for error handling.
+    std::unique_ptr<ExprAST> LogError(const char *Str) {
+      fprintf(stderr, "LogError: %s\n", Str);
+      return nullptr;
+    }
+    std::unique_ptr<PrototypeAST> LogErrorP(const char *Str) {
+      LogError(Str);
+      return nullptr;
+    }
+
+The ``LogError`` routines are simple helper routines that our parser will
+use to handle errors. The error recovery in our parser will not be the
+best and is not particular user-friendly, but it will be enough for our
+tutorial. These routines make it easier to handle errors in routines
+that have various return types: they always return null.
+
+With these basic helper functions, we can implement the first piece of
+our grammar: numeric literals.
+
+Basic Expression Parsing
+========================
+
+We start with numeric literals, because they are the simplest to
+process. For each production in our grammar, we'll define a function
+which parses that production. For numeric literals, we have:
+
+.. code-block:: c++
+
+    /// numberexpr ::= number
+    static std::unique_ptr<ExprAST> ParseNumberExpr() {
+      auto Result = llvm::make_unique<NumberExprAST>(NumVal);
+      getNextToken(); // consume the number
+      return std::move(Result);
+    }
+
+This routine is very simple: it expects to be called when the current
+token is a ``tok_number`` token. It takes the current number value,
+creates a ``NumberExprAST`` node, advances the lexer to the next token,
+and finally returns.
+
+There are some interesting aspects to this. The most important one is
+that this routine eats all of the tokens that correspond to the
+production and returns the lexer buffer with the next token (which is
+not part of the grammar production) ready to go. This is a fairly
+standard way to go for recursive descent parsers. For a better example,
+the parenthesis operator is defined like this:
+
+.. code-block:: c++
+
+    /// parenexpr ::= '(' expression ')'
+    static std::unique_ptr<ExprAST> ParseParenExpr() {
+      getNextToken(); // eat (.
+      auto V = ParseExpression();
+      if (!V)
+        return nullptr;
+
+      if (CurTok != ')')
+        return LogError("expected ')'");
+      getNextToken(); // eat ).
+      return V;
+    }
+
+This function illustrates a number of interesting things about the
+parser:
+
+1) It shows how we use the LogError routines. When called, this function
+expects that the current token is a '(' token, but after parsing the
+subexpression, it is possible that there is no ')' waiting. For example,
+if the user types in "(4 x" instead of "(4)", the parser should emit an
+error. Because errors can occur, the parser needs a way to indicate that
+they happened: in our parser, we return null on an error.
+
+2) Another interesting aspect of this function is that it uses recursion
+by calling ``ParseExpression`` (we will soon see that
+``ParseExpression`` can call ``ParseParenExpr``). This is powerful
+because it allows us to handle recursive grammars, and keeps each
+production very simple. Note that parentheses do not cause construction
+of AST nodes themselves. While we could do it this way, the most
+important role of parentheses are to guide the parser and provide
+grouping. Once the parser constructs the AST, parentheses are not
+needed.
+
+The next simple production is for handling variable references and
+function calls:
+
+.. code-block:: c++
+
+    /// identifierexpr
+    ///   ::= identifier
+    ///   ::= identifier '(' expression* ')'
+    static std::unique_ptr<ExprAST> ParseIdentifierExpr() {
+      std::string IdName = IdentifierStr;
+
+      getNextToken();  // eat identifier.
+
+      if (CurTok != '(') // Simple variable ref.
+        return llvm::make_unique<VariableExprAST>(IdName);
+
+      // Call.
+      getNextToken();  // eat (
+      std::vector<std::unique_ptr<ExprAST>> Args;
+      if (CurTok != ')') {
+        while (1) {
+          if (auto Arg = ParseExpression())
+            Args.push_back(std::move(Arg));
+          else
+            return nullptr;
+
+          if (CurTok == ')')
+            break;
+
+          if (CurTok != ',')
+            return LogError("Expected ')' or ',' in argument list");
+          getNextToken();
+        }
+      }
+
+      // Eat the ')'.
+      getNextToken();
+
+      return llvm::make_unique<CallExprAST>(IdName, std::move(Args));
+    }
+
+This routine follows the same style as the other routines. (It expects
+to be called if the current token is a ``tok_identifier`` token). It
+also has recursion and error handling. One interesting aspect of this is
+that it uses *look-ahead* to determine if the current identifier is a
+stand alone variable reference or if it is a function call expression.
+It handles this by checking to see if the token after the identifier is
+a '(' token, constructing either a ``VariableExprAST`` or
+``CallExprAST`` node as appropriate.
+
+Now that we have all of our simple expression-parsing logic in place, we
+can define a helper function to wrap it together into one entry point.
+We call this class of expressions "primary" expressions, for reasons
+that will become more clear `later in the
+tutorial <LangImpl6.html#user-defined-unary-operators>`_. In order to parse an arbitrary
+primary expression, we need to determine what sort of expression it is:
+
+.. code-block:: c++
+
+    /// primary
+    ///   ::= identifierexpr
+    ///   ::= numberexpr
+    ///   ::= parenexpr
+    static std::unique_ptr<ExprAST> ParsePrimary() {
+      switch (CurTok) {
+      default:
+        return LogError("unknown token when expecting an expression");
+      case tok_identifier:
+        return ParseIdentifierExpr();
+      case tok_number:
+        return ParseNumberExpr();
+      case '(':
+        return ParseParenExpr();
+      }
+    }
+
+Now that you see the definition of this function, it is more obvious why
+we can assume the state of CurTok in the various functions. This uses
+look-ahead to determine which sort of expression is being inspected, and
+then parses it with a function call.
+
+Now that basic expressions are handled, we need to handle binary
+expressions. They are a bit more complex.
+
+Binary Expression Parsing
+=========================
+
+Binary expressions are significantly harder to parse because they are
+often ambiguous. For example, when given the string "x+y\*z", the parser
+can choose to parse it as either "(x+y)\*z" or "x+(y\*z)". With common
+definitions from mathematics, we expect the later parse, because "\*"
+(multiplication) has higher *precedence* than "+" (addition).
+
+There are many ways to handle this, but an elegant and efficient way is
+to use `Operator-Precedence
+Parsing <http://en.wikipedia.org/wiki/Operator-precedence_parser>`_.
+This parsing technique uses the precedence of binary operators to guide
+recursion. To start with, we need a table of precedences:
+
+.. code-block:: c++
+
+    /// BinopPrecedence - This holds the precedence for each binary operator that is
+    /// defined.
+    static std::map<char, int> BinopPrecedence;
+
+    /// GetTokPrecedence - Get the precedence of the pending binary operator token.
+    static int GetTokPrecedence() {
+      if (!isascii(CurTok))
+        return -1;
+
+      // Make sure it's a declared binop.
+      int TokPrec = BinopPrecedence[CurTok];
+      if (TokPrec <= 0) return -1;
+      return TokPrec;
+    }
+
+    int main() {
+      // Install standard binary operators.
+      // 1 is lowest precedence.
+      BinopPrecedence['<'] = 10;
+      BinopPrecedence['+'] = 20;
+      BinopPrecedence['-'] = 20;
+      BinopPrecedence['*'] = 40;  // highest.
+      ...
+    }
+
+For the basic form of Kaleidoscope, we will only support 4 binary
+operators (this can obviously be extended by you, our brave and intrepid
+reader). The ``GetTokPrecedence`` function returns the precedence for
+the current token, or -1 if the token is not a binary operator. Having a
+map makes it easy to add new operators and makes it clear that the
+algorithm doesn't depend on the specific operators involved, but it
+would be easy enough to eliminate the map and do the comparisons in the
+``GetTokPrecedence`` function. (Or just use a fixed-size array).
+
+With the helper above defined, we can now start parsing binary
+expressions. The basic idea of operator precedence parsing is to break
+down an expression with potentially ambiguous binary operators into
+pieces. Consider, for example, the expression "a+b+(c+d)\*e\*f+g".
+Operator precedence parsing considers this as a stream of primary
+expressions separated by binary operators. As such, it will first parse
+the leading primary expression "a", then it will see the pairs [+, b]
+[+, (c+d)] [\*, e] [\*, f] and [+, g]. Note that because parentheses are
+primary expressions, the binary expression parser doesn't need to worry
+about nested subexpressions like (c+d) at all.
+
+To start, an expression is a primary expression potentially followed by
+a sequence of [binop,primaryexpr] pairs:
+
+.. code-block:: c++
+
+    /// expression
+    ///   ::= primary binoprhs
+    ///
+    static std::unique_ptr<ExprAST> ParseExpression() {
+      auto LHS = ParsePrimary();
+      if (!LHS)
+        return nullptr;
+
+      return ParseBinOpRHS(0, std::move(LHS));
+    }
+
+``ParseBinOpRHS`` is the function that parses the sequence of pairs for
+us. It takes a precedence and a pointer to an expression for the part
+that has been parsed so far. Note that "x" is a perfectly valid
+expression: As such, "binoprhs" is allowed to be empty, in which case it
+returns the expression that is passed into it. In our example above, the
+code passes the expression for "a" into ``ParseBinOpRHS`` and the
+current token is "+".
+
+The precedence value passed into ``ParseBinOpRHS`` indicates the
+*minimal operator precedence* that the function is allowed to eat. For
+example, if the current pair stream is [+, x] and ``ParseBinOpRHS`` is
+passed in a precedence of 40, it will not consume any tokens (because
+the precedence of '+' is only 20). With this in mind, ``ParseBinOpRHS``
+starts with:
+
+.. code-block:: c++
+
+    /// binoprhs
+    ///   ::= ('+' primary)*
+    static std::unique_ptr<ExprAST> ParseBinOpRHS(int ExprPrec,
+                                                  std::unique_ptr<ExprAST> LHS) {
+      // If this is a binop, find its precedence.
+      while (1) {
+        int TokPrec = GetTokPrecedence();
+
+        // If this is a binop that binds at least as tightly as the current binop,
+        // consume it, otherwise we are done.
+        if (TokPrec < ExprPrec)
+          return LHS;
+
+This code gets the precedence of the current token and checks to see if
+if is too low. Because we defined invalid tokens to have a precedence of
+-1, this check implicitly knows that the pair-stream ends when the token
+stream runs out of binary operators. If this check succeeds, we know
+that the token is a binary operator and that it will be included in this
+expression:
+
+.. code-block:: c++
+
+        // Okay, we know this is a binop.
+        int BinOp = CurTok;
+        getNextToken();  // eat binop
+
+        // Parse the primary expression after the binary operator.
+        auto RHS = ParsePrimary();
+        if (!RHS)
+          return nullptr;
+
+As such, this code eats (and remembers) the binary operator and then
+parses the primary expression that follows. This builds up the whole
+pair, the first of which is [+, b] for the running example.
+
+Now that we parsed the left-hand side of an expression and one pair of
+the RHS sequence, we have to decide which way the expression associates.
+In particular, we could have "(a+b) binop unparsed" or "a + (b binop
+unparsed)". To determine this, we look ahead at "binop" to determine its
+precedence and compare it to BinOp's precedence (which is '+' in this
+case):
+
+.. code-block:: c++
+
+        // If BinOp binds less tightly with RHS than the operator after RHS, let
+        // the pending operator take RHS as its LHS.
+        int NextPrec = GetTokPrecedence();
+        if (TokPrec < NextPrec) {
+
+If the precedence of the binop to the right of "RHS" is lower or equal
+to the precedence of our current operator, then we know that the
+parentheses associate as "(a+b) binop ...". In our example, the current
+operator is "+" and the next operator is "+", we know that they have the
+same precedence. In this case we'll create the AST node for "a+b", and
+then continue parsing:
+
+.. code-block:: c++
+
+          ... if body omitted ...
+        }
+
+        // Merge LHS/RHS.
+        LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
+                                               std::move(RHS));
+      }  // loop around to the top of the while loop.
+    }
+
+In our example above, this will turn "a+b+" into "(a+b)" and execute the
+next iteration of the loop, with "+" as the current token. The code
+above will eat, remember, and parse "(c+d)" as the primary expression,
+which makes the current pair equal to [+, (c+d)]. It will then evaluate
+the 'if' conditional above with "\*" as the binop to the right of the
+primary. In this case, the precedence of "\*" is higher than the
+precedence of "+" so the if condition will be entered.
+
+The critical question left here is "how can the if condition parse the
+right hand side in full"? In particular, to build the AST correctly for
+our example, it needs to get all of "(c+d)\*e\*f" as the RHS expression
+variable. The code to do this is surprisingly simple (code from the
+above two blocks duplicated for context):
+
+.. code-block:: c++
+
+        // If BinOp binds less tightly with RHS than the operator after RHS, let
+        // the pending operator take RHS as its LHS.
+        int NextPrec = GetTokPrecedence();
+        if (TokPrec < NextPrec) {
+          RHS = ParseBinOpRHS(TokPrec+1, std::move(RHS));
+          if (!RHS)
+            return nullptr;
+        }
+        // Merge LHS/RHS.
+        LHS = llvm::make_unique<BinaryExprAST>(BinOp, std::move(LHS),
+                                               std::move(RHS));
+      }  // loop around to the top of the while loop.
+    }
+
+At this point, we know that the binary operator to the RHS of our
+primary has higher precedence than the binop we are currently parsing.
+As such, we know that any sequence of pairs whose operators are all
+higher precedence than "+" should be parsed together and returned as
+"RHS". To do this, we recursively invoke the ``ParseBinOpRHS`` function
+specifying "TokPrec+1" as the minimum precedence required for it to
+continue. In our example above, this will cause it to return the AST
+node for "(c+d)\*e\*f" as RHS, which is then set as the RHS of the '+'
+expression.
+
+Finally, on the next iteration of the while loop, the "+g" piece is
+parsed and added to the AST. With this little bit of code (14
+non-trivial lines), we correctly handle fully general binary expression
+parsing in a very elegant way. This was a whirlwind tour of this code,
+and it is somewhat subtle. I recommend running through it with a few
+tough examples to see how it works.
+
+This wraps up handling of expressions. At this point, we can point the
+parser at an arbitrary token stream and build an expression from it,
+stopping at the first token that is not part of the expression. Next up
+we need to handle function definitions, etc.
+
+Parsing the Rest
+================
+
+The next thing missing is handling of function prototypes. In
+Kaleidoscope, these are used both for 'extern' function declarations as
+well as function body definitions. The code to do this is
+straight-forward and not very interesting (once you've survived
+expressions):
+
+.. code-block:: c++
+
+    /// prototype
+    ///   ::= id '(' id* ')'
+    static std::unique_ptr<PrototypeAST> ParsePrototype() {
+      if (CurTok != tok_identifier)
+        return LogErrorP("Expected function name in prototype");
+
+      std::string FnName = IdentifierStr;
+      getNextToken();
+
+      if (CurTok != '(')
+        return LogErrorP("Expected '(' in prototype");
+
+      // Read the list of argument names.
+      std::vector<std::string> ArgNames;
+      while (getNextToken() == tok_identifier)
+        ArgNames.push_back(IdentifierStr);
+      if (CurTok != ')')
+        return LogErrorP("Expected ')' in prototype");
+
+      // success.
+      getNextToken();  // eat ')'.
+
+      return llvm::make_unique<PrototypeAST>(FnName, std::move(ArgNames));
+    }
+
+Given this, a function definition is very simple, just a prototype plus
+an expression to implement the body:
+
+.. code-block:: c++
+
+    /// definition ::= 'def' prototype expression
+    static std::unique_ptr<FunctionAST> ParseDefinition() {
+      getNextToken();  // eat def.
+      auto Proto = ParsePrototype();
+      if (!Proto) return nullptr;
+
+      if (auto E = ParseExpression())
+        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
+      return nullptr;
+    }
+
+In addition, we support 'extern' to declare functions like 'sin' and
+'cos' as well as to support forward declaration of user functions. These
+'extern's are just prototypes with no body:
+
+.. code-block:: c++
+
+    /// external ::= 'extern' prototype
+    static std::unique_ptr<PrototypeAST> ParseExtern() {
+      getNextToken();  // eat extern.
+      return ParsePrototype();
+    }
+
+Finally, we'll also let the user type in arbitrary top-level expressions
+and evaluate them on the fly. We will handle this by defining anonymous
+nullary (zero argument) functions for them:
+
+.. code-block:: c++
+
+    /// toplevelexpr ::= expression
+    static std::unique_ptr<FunctionAST> ParseTopLevelExpr() {
+      if (auto E = ParseExpression()) {
+        // Make an anonymous proto.
+        auto Proto = llvm::make_unique<PrototypeAST>("", std::vector<std::string>());
+        return llvm::make_unique<FunctionAST>(std::move(Proto), std::move(E));
+      }
+      return nullptr;
+    }
+
+Now that we have all the pieces, let's build a little driver that will
+let us actually *execute* this code we've built!
+
+The Driver
+==========
+
+The driver for this simply invokes all of the parsing pieces with a
+top-level dispatch loop. There isn't much interesting here, so I'll just
+include the top-level loop. See `below <#full-code-listing>`_ for full code in the
+"Top-Level Parsing" section.
+
+.. code-block:: c++
+
+    /// top ::= definition | external | expression | ';'
+    static void MainLoop() {
+      while (1) {
+        fprintf(stderr, "ready> ");
+        switch (CurTok) {
+        case tok_eof:
+          return;
+        case ';': // ignore top-level semicolons.
+          getNextToken();
+          break;
+        case tok_def:
+          HandleDefinition();
+          break;
+        case tok_extern:
+          HandleExtern();
+          break;
+        default:
+          HandleTopLevelExpression();
+          break;
+        }
+      }
+    }
+
+The most interesting part of this is that we ignore top-level
+semicolons. Why is this, you ask? The basic reason is that if you type
+"4 + 5" at the command line, the parser doesn't know whether that is the
+end of what you will type or not. For example, on the next line you
+could type "def foo..." in which case 4+5 is the end of a top-level
+expression. Alternatively you could type "\* 6", which would continue
+the expression. Having top-level semicolons allows you to type "4+5;",
+and the parser will know you are done.
+
+Conclusions
+===========
+
+With just under 400 lines of commented code (240 lines of non-comment,
+non-blank code), we fully defined our minimal language, including a
+lexer, parser, and AST builder. With this done, the executable will
+validate Kaleidoscope code and tell us if it is grammatically invalid.
+For example, here is a sample interaction:
+
+.. code-block:: bash
+
+    $ ./a.out
+    ready> def foo(x y) x+foo(y, 4.0);
+    Parsed a function definition.
+    ready> def foo(x y) x+y y;
+    Parsed a function definition.
+    Parsed a top-level expr
+    ready> def foo(x y) x+y );
+    Parsed a function definition.
+    Error: unknown token when expecting an expression
+    ready> extern sin(a);
+    ready> Parsed an extern
+    ready> ^D
+    $
+
+There is a lot of room for extension here. You can define new AST nodes,
+extend the language in many ways, etc. In the `next
+installment <LangImpl03.html>`_, we will describe how to generate LLVM
+Intermediate Representation (IR) from the AST.
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example. Because this
+uses the LLVM libraries, we need to link them in. To do this, we use the
+`llvm-config <http://llvm.org/cmds/llvm-config.html>`_ tool to inform
+our makefile/command line about which options to use:
+
+.. code-block:: bash
+
+    # Compile
+    clang++ -g -O3 toy.cpp `llvm-config --cxxflags`
+    # Run
+    ./a.out
+
+Here is the code:
+
+.. literalinclude:: ../../../examples/Kaleidoscope/Chapter2/toy.cpp
+   :language: c++
+
+`Next: Implementing Code Generation to LLVM IR <LangImpl03.html>`_
+
diff --git a/docs/tutorial/MyFirstLanguageFrontend/LangImpl03.rst b/docs/tutorial/MyFirstLanguageFrontend/LangImpl03.rst
new file mode 100644
index 0000000..7b4e24d
--- /dev/null
+++ b/docs/tutorial/MyFirstLanguageFrontend/LangImpl03.rst
@@ -0,0 +1,570 @@
+:orphan:
+
+========================================
+Kaleidoscope: Code generation to LLVM IR
+========================================
+
+.. contents::
+   :local:
+
+Chapter 3 Introduction
+======================
+
+Welcome to Chapter 3 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. This chapter shows you how to transform
+the `Abstract Syntax Tree <LangImpl02.html>`_, built in Chapter 2, into
+LLVM IR. This will teach you a little bit about how LLVM does things, as
+well as demonstrate how easy it is to use. It's much more work to build
+a lexer and parser than it is to generate LLVM IR code. :)
+
+**Please note**: the code in this chapter and later require LLVM 3.7 or
+later. LLVM 3.6 and before will not work with it. Also note that you
+need to use a version of this tutorial that matches your LLVM release:
+If you are using an official LLVM release, use the version of the
+documentation included with your release or on the `llvm.org releases
+page <http://llvm.org/releases/>`_.
+
+Code Generation Setup
+=====================
+
+In order to generate LLVM IR, we want some simple setup to get started.
+First we define virtual code generation (codegen) methods in each AST
+class:
+
+.. code-block:: c++
+
+    /// ExprAST - Base class for all expression nodes.
+    class ExprAST {
+    public:
+      virtual ~ExprAST() {}
+      virtual Value *codegen() = 0;
+    };
+
+    /// NumberExprAST - Expression class for numeric literals like "1.0".
+    class NumberExprAST : public ExprAST {
+      double Val;
+
+    public:
+      NumberExprAST(double Val) : Val(Val) {}
+      virtual Value *codegen();
+    };
+    ...
+
+The codegen() method says to emit IR for that AST node along with all
+the things it depends on, and they all return an LLVM Value object.
+"Value" is the class used to represent a "`Static Single Assignment
+(SSA) <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
+register" or "SSA value" in LLVM. The most distinct aspect of SSA values
+is that their value is computed as the related instruction executes, and
+it does not get a new value until (and if) the instruction re-executes.
+In other words, there is no way to "change" an SSA value. For more
+information, please read up on `Static Single
+Assignment <http://en.wikipedia.org/wiki/Static_single_assignment_form>`_
+- the concepts are really quite natural once you grok them.
+
+Note that instead of adding virtual methods to the ExprAST class
+hierarchy, it could also make sense to use a `visitor
+pattern <http://en.wikipedia.org/wiki/Visitor_pattern>`_ or some other
+way to model this. Again, this tutorial won't dwell on good software
+engineering practices: for our purposes, adding a virtual method is
+simplest.
+
+The second thing we want is an "LogError" method like we used for the
+parser, which will be used to report errors found during code generation
+(for example, use of an undeclared parameter):
+
+.. code-block:: c++
+
+    static LLVMContext TheContext;
+    static IRBuilder<> Builder(TheContext);
+    static std::unique_ptr<Module> TheModule;
+    static std::map<std::string, Value *> NamedValues;
+
+    Value *LogErrorV(const char *Str) {
+      LogError(Str);
+      return nullptr;
+    }
+
+The static variables will be used during code generation. ``TheContext``
+is an opaque object that owns a lot of core LLVM data structures, such as
+the type and constant value tables. We don't need to understand it in
+detail, we just need a single instance to pass into APIs that require it.
+
+The ``Builder`` object is a helper object that makes it easy to generate
+LLVM instructions. Instances of the
+`IRBuilder <http://llvm.org/doxygen/IRBuilder_8h-source.html>`_
+class template keep track of the current place to insert instructions
+and has methods to create new instructions.
+
+``TheModule`` is an LLVM construct that contains functions and global
+variables. In many ways, it is the top-level structure that the LLVM IR
+uses to contain code. It will own the memory for all of the IR that we
+generate, which is why the codegen() method returns a raw Value\*,
+rather than a unique_ptr<Value>.
+
+The ``NamedValues`` map keeps track of which values are defined in the
+current scope and what their LLVM representation is. (In other words, it
+is a symbol table for the code). In this form of Kaleidoscope, the only
+things that can be referenced are function parameters. As such, function
+parameters will be in this map when generating code for their function
+body.
+
+With these basics in place, we can start talking about how to generate
+code for each expression. Note that this assumes that the ``Builder``
+has been set up to generate code *into* something. For now, we'll assume
+that this has already been done, and we'll just use it to emit code.
+
+Expression Code Generation
+==========================
+
+Generating LLVM code for expression nodes is very straightforward: less
+than 45 lines of commented code for all four of our expression nodes.
+First we'll do numeric literals:
+
+.. code-block:: c++
+
+    Value *NumberExprAST::codegen() {
+      return ConstantFP::get(TheContext, APFloat(Val));
+    }
+
+In the LLVM IR, numeric constants are represented with the
+``ConstantFP`` class, which holds the numeric value in an ``APFloat``
+internally (``APFloat`` has the capability of holding floating point
+constants of Arbitrary Precision). This code basically just creates
+and returns a ``ConstantFP``. Note that in the LLVM IR that constants
+are all uniqued together and shared. For this reason, the API uses the
+"foo::get(...)" idiom instead of "new foo(..)" or "foo::Create(..)".
+
+.. code-block:: c++
+
+    Value *VariableExprAST::codegen() {
+      // Look this variable up in the function.
+      Value *V = NamedValues[Name];
+      if (!V)
+        LogErrorV("Unknown variable name");
+      return V;
+    }
+
+References to variables are also quite simple using LLVM. In the simple
+version of Kaleidoscope, we assume that the variable has already been
+emitted somewhere and its value is available. In practice, the only
+values that can be in the ``NamedValues`` map are function arguments.
+This code simply checks to see that the specified name is in the map (if
+not, an unknown variable is being referenced) and returns the value for
+it. In future chapters, we'll add support for `loop induction
+variables <LangImpl5.html#for-loop-expression>`_ in the symbol table, and for `local
+variables <LangImpl7.html#user-defined-local-variables>`_.
+
+.. code-block:: c++
+
+    Value *BinaryExprAST::codegen() {
+      Value *L = LHS->codegen();
+      Value *R = RHS->codegen();
+      if (!L || !R)
+        return nullptr;
+
+      switch (Op) {
+      case '+':
+        return Builder.CreateFAdd(L, R, "addtmp");
+      case '-':
+        return Builder.CreateFSub(L, R, "subtmp");
+      case '*':
+        return Builder.CreateFMul(L, R, "multmp");
+      case '<':
+        L = Builder.CreateFCmpULT(L, R, "cmptmp");
+        // Convert bool 0/1 to double 0.0 or 1.0
+        return Builder.CreateUIToFP(L, Type::getDoubleTy(TheContext),
+                                    "booltmp");
+      default:
+        return LogErrorV("invalid binary operator");
+      }
+    }
+
+Binary operators start to get more interesting. The basic idea here is
+that we recursively emit code for the left-hand side of the expression,
+then the right-hand side, then we compute the result of the binary
+expression. In this code, we do a simple switch on the opcode to create
+the right LLVM instruction.
+
+In the example above, the LLVM builder class is starting to show its
+value. IRBuilder knows where to insert the newly created instruction,
+all you have to do is specify what instruction to create (e.g. with
+``CreateFAdd``), which operands to use (``L`` and ``R`` here) and
+optionally provide a name for the generated instruction.
+
+One nice thing about LLVM is that the name is just a hint. For instance,
+if the code above emits multiple "addtmp" variables, LLVM will
+automatically provide each one with an increasing, unique numeric
+suffix. Local value names for instructions are purely optional, but it
+makes it much easier to read the IR dumps.
+
+`LLVM instructions <../LangRef.html#instruction-reference>`_ are constrained by strict
+rules: for example, the Left and Right operators of an `add
+instruction <../LangRef.html#add-instruction>`_ must have the same type, and the
+result type of the add must match the operand types. Because all values
+in Kaleidoscope are doubles, this makes for very simple code for add,
+sub and mul.
+
+On the other hand, LLVM specifies that the `fcmp
+instruction <../LangRef.html#fcmp-instruction>`_ always returns an 'i1' value (a
+one bit integer). The problem with this is that Kaleidoscope wants the
+value to be a 0.0 or 1.0 value. In order to get these semantics, we
+combine the fcmp instruction with a `uitofp
+instruction <../LangRef.html#uitofp-to-instruction>`_. This instruction converts its
+input integer into a floating point value by treating the input as an
+unsigned value. In contrast, if we used the `sitofp
+instruction <../LangRef.html#sitofp-to-instruction>`_, the Kaleidoscope '<' operator
+would return 0.0 and -1.0, depending on the input value.
+
+.. code-block:: c++
+
+    Value *CallExprAST::codegen() {
+      // Look up the name in the global module table.
+      Function *CalleeF = TheModule->getFunction(Callee);
+      if (!CalleeF)
+        return LogErrorV("Unknown function referenced");
+
+      // If argument mismatch error.
+      if (CalleeF->arg_size() != Args.size())
+        return LogErrorV("Incorrect # arguments passed");
+
+      std::vector<Value *> ArgsV;
+      for (unsigned i = 0, e = Args.size(); i != e; ++i) {
+        ArgsV.push_back(Args[i]->codegen());
+        if (!ArgsV.back())
+          return nullptr;
+      }
+
+      return Builder.CreateCall(CalleeF, ArgsV, "calltmp");
+    }
+
+Code generation for function calls is quite straightforward with LLVM. The code
+above initially does a function name lookup in the LLVM Module's symbol table.
+Recall that the LLVM Module is the container that holds the functions we are
+JIT'ing. By giving each function the same name as what the user specifies, we
+can use the LLVM symbol table to resolve function names for us.
+
+Once we have the function to call, we recursively codegen each argument
+that is to be passed in, and create an LLVM `call
+instruction <../LangRef.html#call-instruction>`_. Note that LLVM uses the native C
+calling conventions by default, allowing these calls to also call into
+standard library functions like "sin" and "cos", with no additional
+effort.
+
+This wraps up our handling of the four basic expressions that we have so
+far in Kaleidoscope. Feel free to go in and add some more. For example,
+by browsing the `LLVM language reference <../LangRef.html>`_ you'll find
+several other interesting instructions that are really easy to plug into
+our basic framework.
+
+Function Code Generation
+========================
+
+Code generation for prototypes and functions must handle a number of
+details, which make their code less beautiful than expression code
+generation, but allows us to illustrate some important points. First,
+let's talk about code generation for prototypes: they are used both for
+function bodies and external function declarations. The code starts
+with:
+
+.. code-block:: c++
+
+    Function *PrototypeAST::codegen() {
+      // Make the function type:  double(double,double) etc.
+      std::vector<Type*> Doubles(Args.size(),
+                                 Type::getDoubleTy(TheContext));
+      FunctionType *FT =
+        FunctionType::get(Type::getDoubleTy(TheContext), Doubles, false);
+
+      Function *F =
+        Function::Create(FT, Function::ExternalLinkage, Name, TheModule.get());
+
+This code packs a lot of power into a few lines. Note first that this
+function returns a "Function\*" instead of a "Value\*". Because a
+"prototype" really talks about the external interface for a function
+(not the value computed by an expression), it makes sense for it to
+return the LLVM Function it corresponds to when codegen'd.
+
+The call to ``FunctionType::get`` creates the ``FunctionType`` that
+should be used for a given Prototype. Since all function arguments in
+Kaleidoscope are of type double, the first line creates a vector of "N"
+LLVM double types. It then uses the ``Functiontype::get`` method to
+create a function type that takes "N" doubles as arguments, returns one
+double as a result, and that is not vararg (the false parameter
+indicates this). Note that Types in LLVM are uniqued just like Constants
+are, so you don't "new" a type, you "get" it.
+
+The final line above actually creates the IR Function corresponding to
+the Prototype. This indicates the type, linkage and name to use, as
+well as which module to insert into. "`external
+linkage <../LangRef.html#linkage>`_" means that the function may be
+defined outside the current module and/or that it is callable by
+functions outside the module. The Name passed in is the name the user
+specified: since "``TheModule``" is specified, this name is registered
+in "``TheModule``"s symbol table.
+
+.. code-block:: c++
+
+  // Set names for all arguments.
+  unsigned Idx = 0;
+  for (auto &Arg : F->args())
+    Arg.setName(Args[Idx++]);
+
+  return F;
+
+Finally, we set the name of each of the function's arguments according to the
+names given in the Prototype. This step isn't strictly necessary, but keeping
+the names consistent makes the IR more readable, and allows subsequent code to
+refer directly to the arguments for their names, rather than having to look up
+them up in the Prototype AST.
+
+At this point we have a function prototype with no body. This is how LLVM IR
+represents function declarations. For extern statements in Kaleidoscope, this
+is as far as we need to go. For function definitions however, we need to
+codegen and attach a function body.
+
+.. code-block:: c++
+
+  Function *FunctionAST::codegen() {
+      // First, check for an existing function from a previous 'extern' declaration.
+    Function *TheFunction = TheModule->getFunction(Proto->getName());
+
+    if (!TheFunction)
+      TheFunction = Proto->codegen();
+
+    if (!TheFunction)
+      return nullptr;
+
+    if (!TheFunction->empty())
+      return (Function*)LogErrorV("Function cannot be redefined.");
+
+
+For function definitions, we start by searching TheModule's symbol table for an
+existing version of this function, in case one has already been created using an
+'extern' statement. If Module::getFunction returns null then no previous version
+exists, so we'll codegen one from the Prototype. In either case, we want to
+assert that the function is empty (i.e. has no body yet) before we start.
+
+.. code-block:: c++
+
+  // Create a new basic block to start insertion into.
+  BasicBlock *BB = BasicBlock::Create(TheContext, "entry", TheFunction);
+  Builder.SetInsertPoint(BB);
+
+  // Record the function arguments in the NamedValues map.
+  NamedValues.clear();
+  for (auto &Arg : TheFunction->args())
+    NamedValues[Arg.getName()] = &Arg;
+
+Now we get to the point where the ``Builder`` is set up. The first line
+creates a new `basic block <http://en.wikipedia.org/wiki/Basic_block>`_
+(named "entry"), which is inserted into ``TheFunction``. The second line
+then tells the builder that new instructions should be inserted into the
+end of the new basic block. Basic blocks in LLVM are an important part
+of functions that define the `Control Flow
+Graph <http://en.wikipedia.org/wiki/Control_flow_graph>`_. Since we
+don't have any control flow, our functions will only contain one block
+at this point. We'll fix this in `Chapter 5 <LangImpl05.html>`_ :).
+
+Next we add the function arguments to the NamedValues map (after first clearing
+it out) so that they're accessible to ``VariableExprAST`` nodes.
+
+.. code-block:: c++
+
+      if (Value *RetVal = Body->codegen()) {
+        // Finish off the function.
+        Builder.CreateRet(RetVal);
+
+        // Validate the generated code, checking for consistency.
+        verifyFunction(*TheFunction);
+
+        return TheFunction;
+      }
+
+Once the insertion point has been set up and the NamedValues map populated,
+we call the ``codegen()`` method for the root expression of the function. If no
+error happens, this emits code to compute the expression into the entry block
+and returns the value that was computed. Assuming no error, we then create an
+LLVM `ret instruction <../LangRef.html#ret-instruction>`_, which completes the function.
+Once the function is built, we call ``verifyFunction``, which is
+provided by LLVM. This function does a variety of consistency checks on
+the generated code, to determine if our compiler is doing everything
+right. Using this is important: it can catch a lot of bugs. Once the
+function is finished and validated, we return it.
+
+.. code-block:: c++
+
+      // Error reading body, remove function.
+      TheFunction->eraseFromParent();
+      return nullptr;
+    }
+
+The only piece left here is handling of the error case. For simplicity,
+we handle this by merely deleting the function we produced with the
+``eraseFromParent`` method. This allows the user to redefine a function
+that they incorrectly typed in before: if we didn't delete it, it would
+live in the symbol table, with a body, preventing future redefinition.
+
+This code does have a bug, though: If the ``FunctionAST::codegen()`` method
+finds an existing IR Function, it does not validate its signature against the
+definition's own prototype. This means that an earlier 'extern' declaration will
+take precedence over the function definition's signature, which can cause
+codegen to fail, for instance if the function arguments are named differently.
+There are a number of ways to fix this bug, see what you can come up with! Here
+is a testcase:
+
+::
+
+    extern foo(a);     # ok, defines foo.
+    def foo(b) b;      # Error: Unknown variable name. (decl using 'a' takes precedence).
+
+Driver Changes and Closing Thoughts
+===================================
+
+For now, code generation to LLVM doesn't really get us much, except that
+we can look at the pretty IR calls. The sample code inserts calls to
+codegen into the "``HandleDefinition``", "``HandleExtern``" etc
+functions, and then dumps out the LLVM IR. This gives a nice way to look
+at the LLVM IR for simple functions. For example:
+
+::
+
+    ready> 4+5;
+    Read top-level expression:
+    define double @0() {
+    entry:
+      ret double 9.000000e+00
+    }
+
+Note how the parser turns the top-level expression into anonymous
+functions for us. This will be handy when we add `JIT
+support <LangImpl4.html#adding-a-jit-compiler>`_ in the next chapter. Also note that the
+code is very literally transcribed, no optimizations are being performed
+except simple constant folding done by IRBuilder. We will `add
+optimizations <LangImpl4.html#trivial-constant-folding>`_ explicitly in the next
+chapter.
+
+::
+
+    ready> def foo(a b) a*a + 2*a*b + b*b;
+    Read function definition:
+    define double @foo(double %a, double %b) {
+    entry:
+      %multmp = fmul double %a, %a
+      %multmp1 = fmul double 2.000000e+00, %a
+      %multmp2 = fmul double %multmp1, %b
+      %addtmp = fadd double %multmp, %multmp2
+      %multmp3 = fmul double %b, %b
+      %addtmp4 = fadd double %addtmp, %multmp3
+      ret double %addtmp4
+    }
+
+This shows some simple arithmetic. Notice the striking similarity to the
+LLVM builder calls that we use to create the instructions.
+
+::
+
+    ready> def bar(a) foo(a, 4.0) + bar(31337);
+    Read function definition:
+    define double @bar(double %a) {
+    entry:
+      %calltmp = call double @foo(double %a, double 4.000000e+00)
+      %calltmp1 = call double @bar(double 3.133700e+04)
+      %addtmp = fadd double %calltmp, %calltmp1
+      ret double %addtmp
+    }
+
+This shows some function calls. Note that this function will take a long
+time to execute if you call it. In the future we'll add conditional
+control flow to actually make recursion useful :).
+
+::
+
+    ready> extern cos(x);
+    Read extern:
+    declare double @cos(double)
+
+    ready> cos(1.234);
+    Read top-level expression:
+    define double @1() {
+    entry:
+      %calltmp = call double @cos(double 1.234000e+00)
+      ret double %calltmp
+    }
+
+This shows an extern for the libm "cos" function, and a call to it.
+
+.. TODO:: Abandon Pygments' horrible `llvm` lexer. It just totally gives up
+   on highlighting this due to the first line.
+
+::
+
+    ready> ^D
+    ; ModuleID = 'my cool jit'
+
+    define double @0() {
+    entry:
+      %addtmp = fadd double 4.000000e+00, 5.000000e+00
+      ret double %addtmp
+    }
+
+    define double @foo(double %a, double %b) {
+    entry:
+      %multmp = fmul double %a, %a
+      %multmp1 = fmul double 2.000000e+00, %a
+      %multmp2 = fmul double %multmp1, %b
+      %addtmp = fadd double %multmp, %multmp2
+      %multmp3 = fmul double %b, %b
+      %addtmp4 = fadd double %addtmp, %multmp3
+      ret double %addtmp4
+    }
+
+    define double @bar(double %a) {
+    entry:
+      %calltmp = call double @foo(double %a, double 4.000000e+00)
+      %calltmp1 = call double @bar(double 3.133700e+04)
+      %addtmp = fadd double %calltmp, %calltmp1
+      ret double %addtmp
+    }
+
+    declare double @cos(double)
+
+    define double @1() {
+    entry:
+      %calltmp = call double @cos(double 1.234000e+00)
+      ret double %calltmp
+    }
+
+When you quit the current demo (by sending an EOF via CTRL+D on Linux
+or CTRL+Z and ENTER on Windows), it dumps out the IR for the entire
+module generated. Here you can see the big picture with all the
+functions referencing each other.
+
+This wraps up the third chapter of the Kaleidoscope tutorial. Up next,
+we'll describe how to `add JIT codegen and optimizer
+support <LangImpl04.html>`_ to this so we can actually start running
+code!
+
+Full Code Listing
+=================
+
+Here is the complete code listing for our running example, enhanced with
+the LLVM code generator. Because this uses the LLVM libraries, we need
+to link them in. To do this, we use the
+`llvm-config <http://llvm.org/cmds/llvm-config.html>`_ tool to inform
+our makefile/command line about which options to use:
+
+.. code-block:: bash
+
+    # Compile
+    clang++ -g -O3 toy.cpp `llvm-config --cxxflags --ldflags --system-libs --libs core` -o toy
+    # Run
+    ./toy
+
+Here is the code:
+
+.. literalinclude:: ../../../examples/Kaleidoscope/Chapter3/toy.cpp
+   :language: c++
+
+`Next: Adding JIT and Optimizer Support <LangImpl04.html>`_
+
diff --git a/docs/tutorial/MyFirstLanguageFrontend/LangImpl04.rst b/docs/tutorial/MyFirstLanguageFrontend/LangImpl04.rst
new file mode 100644
index 0000000..773ce55
--- /dev/null
+++ b/docs/tutorial/MyFirstLanguageFrontend/LangImpl04.rst
@@ -0,0 +1,661 @@
+:orphan:
+
+==============================================
+Kaleidoscope: Adding JIT and Optimizer Support
+==============================================
+
+.. contents::
+   :local:
+
+Chapter 4 Introduction
+======================
+
+Welcome to Chapter 4 of the "`Implementing a language with
+LLVM <index.html>`_" tutorial. Chapters 1-3 described the implementation
+of a simple language and added support for generating LLVM IR. This
+chapter describes two new techniques: adding optimizer support to your
+language, and adding JIT compiler support. These additions will
+demonstrate how to get nice, efficient code for the Kaleidoscope
+language.
+
+Trivial Constant Folding
+========================
+
+Our demonstration for Chapter 3 is elegant and easy to extend.
+Unfortunately, it does not produce wonderful code. The IRBuilder,
+however, does give us obvious optimizations when compiling simple code:
+
+::
+
+    ready> def test(x) 1+2+x;
+    Read function definition:
+    define double @test(double %x) {
+    entry:
+            %addtmp = fadd double 3.000000e+00, %x
+            ret double %addtmp
+    }
+
+This code is not a literal transcription of the AST built by parsing the
+input. That would be:
+
+::
+
+    ready> def test(x) 1+2+x;
+    Read function definition:
+    define double @test(double %x) {
+    entry:
+            %addtmp = fadd double 2.000000e+00, 1.000000e+00
+            %addtmp1 = fadd double %addtmp, %x
+            ret double %addtmp1
+    }
+
+Constant folding, as seen above, in particular, is a very common and
+very important optimization: so much so that many language implementors
+implement constant folding support in their AST representation.
+
+With LLVM, you don't need this support in the AST. Since all calls to
+build LLVM IR go through the LLVM IR builder, the builder itself checked
+to see if there was a constant folding opportunity when you call it. If
+so, it just does the constant fold and return the constant instead of
+creating an instruction.
+
+Well, that was easy :). In practice, we recommend always using
+``IRBuilder`` when generating code like this. It has no "syntactic
+overhead" for its use (you don't have to uglify your compiler with
+constant checks everywhere) and it can dramatically reduce the amount of
+LLVM IR that is generated in some cases (particular for languages with a
+macro preprocessor or that use a lot of constants).
+
+On the other hand, the ``IRBuilder`` is limited by the fact that it does
+all of its analysis inline with the code as it is built. If you take a
+slightly more complex example:
+
+::
+
+    ready> def test(x) (1+2+x)*(x+(1+2));
+    ready> Read function definition:
+    define double @test(double %x) {
+    entry:
+            %addtmp = fadd double 3.000000e+00, %x
+            %addtmp1 = fadd double %x, 3.000000e+00
+            %multmp = fmul double %addtmp, %addtmp1
+            ret double %multmp
+    }
+
+In this case, the LHS and RHS of the multiplication are the same value.
+We'd really like to see this generate "``tmp = x+3; result = tmp*tmp;``"
+instead of computing "``x+3``" twice.
+
+Unfortunately, no amount of local analysis will be able to detect and
+correct this. This requires two transformations: reassociation of
+expressions (to make the add's lexically identical) and Common
+Subexpression Elimination (CSE) to delete the redundant add instruction.
+Fortunately, LLVM provides a broad range of optimizations that you can
+use, in the form of "passes".
+
+LLVM Optimization Passes
+========================
+
+.. warning::
+
+   Due to the transition to the new PassManager infrastructure this tutorial
+   is based on ``llvm::legacy::FunctionPassManager`` which can be found in
+   `LegacyPassManager.h <http://llvm.org/doxygen/classllvm_1_1legacy_1_1FunctionPassManager.html>`_.
+   For the purpose of the this tutorial the above should be used until
+   the pass manager transition is complete.
+
+LLVM provides many optimization passes, which do many different sorts of
+things and have different tradeoffs. Unlike other systems, LLVM doesn't
+hold to the mistaken notion that one set of optimizations is right for
+all languages and for all situations. LLVM allows a compiler implementor
+to make complete decisions about what optimizations to use, in which
+order, and in what situation.
+
+As a concrete example, LLVM supports both "whole module" passes, which
+look across as large of body of code as they can (often a whole file,
+but if run at link time, this can be a substantial portion of the whole
+program). It also supports and includes "per-function" passes which just
+operate on a single function at a time, without looking at other
+functions. For more information on passes and how they are run, see the
+`How to Write a Pass <../WritingAnLLVMPass.html>`_ document and the
+`List of LLVM Passes <../Passes.html>`_.
+
+For Kaleidoscope, we are currently generating functions on the fly, one
+at a time, as the user types them in. We aren't shooting for the
+ultimate optimization experience in this setting, but we also want to
+catch the easy and quick stuff where possible. As such, we will choose
+to run a few per-function optimizations as the user types the function
+in. If we wanted to make a "static Kaleidoscope compiler", we would use
+exactly the code we have now, except that we would defer running the
+optimizer until the entire file has been parsed.
+
+In order to get per-function optimizations going, we need to set up a
+`FunctionPassManager <../WritingAnLLVMPass.html#what-passmanager-doesr>`_ to hold
+and organize the LLVM optimizations that we want to run. Once we have
+that, we can add a set of optimizations to run. We'll need a new
+FunctionPassManager for each module that we want to optimize, so we'll
+write a function to create a