[llvm] [BOLT] Rework user-facing documentation of BOLT gadget scanner (PR #176446)

[Anatoly Trosinenko via llvm-commits]

================
@@ -61,126 +64,680 @@ The security scanners implemented in `llvm-bolt-binary-analysis` aim to enable
 the testing of security hardening in arbitrary programs and not just specific
 examples.
 
+### Pointer Authentication
+
+[Pointer Authentication](https://clang.llvm.org/docs/PointerAuthentication.html)
+is intended to make it harder for an attacker to replace pointers at run time.
+This is achieved by making it possible for the compiler or the programmer to
+produce a *signed* pointer from a raw one, and then to probabilistically
+*authenticate the signature* at another site in the program.
+On AArch64 this is achieved by injecting a cryptographic hash, called a
+["Pointer Authentication Code" (PAC)](https://llsoftsec.github.io/llsoftsecbook/#sec:pointer-authentication),
+to the upper bits of the pointer.
+While this approach can be applied to any pointers in the program, the most
+frequent use case, at least in C and C++, is protecting the code pointers.
+The language rules for such pointers are more restrictive, thus allowing the
+compiler to implement various hardenings transparently to the programmer.
+
+Probably the most simple variant of hardening based on Pointer Authentication is
+[`pac-ret`](https://llsoftsec.github.io/llsoftsecbook/#sec:pac-ret), a security
+hardening scheme implemented in compilers such as GCC and Clang, using the
+command line option `-mbranch-protection=pac-ret`. This option is enabled by
+default on most widely used Linux distributions. The hardening scheme mitigates
+[Return-Oriented Programming (ROP)](https://llsoftsec.github.io/llsoftsecbook/#return-oriented-programming)
+attacks by making sure that return addresses are only ever stored to memory
+in a signed form. This makes it substantially harder for attackers to divert
+control flow by overwriting a return address with a different value.
+
+It is possible to link object files with different pac-ret hardening modes together,
+as each particular function is responsible for signing the LR value in the prologue
+and authenticating it in the epilogue. Other hardening variants exist that break
+ABI compatibility, see the description of
+[PAuth ABI Extensions](https://github.com/ARM-software/abi-aa/blob/main/pauthabielf64/pauthabielf64.rst)
+for details. While pac-ret hardens (signs and authenticates) return addresses,
+PAuth ABI may harden most other code pointers as well, such as function pointers
+and labels used as the destination of computed goto.
+
+The approach to validation of Pointer Authentication hardening implemented in
+`llvm-bolt-binary-analysis` is tracking register properties using dataflow analysis.
+At each program point it is computed whether the particular register can be
+controlled and whether it can be inspected by an attacker under the
+[Pointer Authentication threat model](https://clang.llvm.org/docs/PointerAuthentication.html#theory-of-operation).
+Then, for a number of sensitive instruction kinds (such as function calls and
+pointer signing instructions), the properties of input or output operands are
+inspected to check if the particular instruction is emitted in a safe manner.
+For example, for a return instruction this usually means that either the link
+register (x30) was never clobbered in the function or that it was authenticated
----------------
atrosinenko wrote:

It would not probably be a flawless solution to replace all uses of x30 with LR throughout the document, as according to the [Arm ARM](https://developer.arm.com/documentation/ddi0487/mb/-Part-C-The-AArch64-Instruction-Set/-Chapter-C1-The-A64-Instruction-Set/-C1-2-Structure-of-the-A64-assembler-language/-C1-2-6-Register-names?lang=en), 

> The architecture does not define a specific name for general-purpose register R30 to reflect its role as the link register on procedure calls. However, an A64 assembler must always use W30 and X30 for this purpose, and additional software names might be defined as part of the Procedure Call Standard, see Procedure Call Standard for the Arm 64-bit Architecture.

Thus, I kept x30 but added an explanation: "`x30`, which is also referred to as LR on AArch64".

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