[llvm] [docs] Add guide for Undefined Behavior (PR #119220)

[Nikita Popov via llvm-commits]

================
@@ -0,0 +1,368 @@
+======================================
+LLVM IR Undefined Behavior (UB) Manual
+======================================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Abstract
+========
+This document describes the undefined behavior (UB) in LLVM's IR, including
+undef and poison values, as well as the ``freeze`` instruction.
+We also provide guidelines on when to use each form of UB.
+
+
+Introduction
+============
+Undefined behavior is used to specify the behavior of corner cases for which we
+don't wish to specify the concrete results.
----------------
nikic wrote:

This is only one use case for UB (mostly immediate UB) -- the other big use case is to provide additional constraints to the optimizer (all the poison generating flags).

https://github.com/llvm/llvm-project/pull/119220