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

[Antonio Frighetto via llvm-commits]

================
@@ -0,0 +1,351 @@
+======================================
+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. UB is also used to provide
+additional constraints to the optimizers (e.g., assumptions that the frontend
+guarantees through the language type system or the runtime).
+For example, we could specify the result of division by zero as zero, but
+since we are not really interested in the result, we say it is UB.
+
+There are two forms of UB in LLVM: immediate UB and deferred UB (undef and
+poison values).
+The lattice of values in LLVM is:
+immediate UB > poison > undef > freeze > concrete value.
----------------
antoniofrighetto wrote:

We haven't introduced freeze yet, would probably make sense to move this at the end while summarizing, but we are referring to the lattice again before elaborating on freeze. Maybe worth explaining why the lattice is defined as such, or at the very least, we can move all the lattice part at the end?

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