[clang] [BoundsSafety][Doc] Add BoundsSafetyAdoptionGuide.rst (PR #120674)

[Dan Liew via cfe-commits]

================
@@ -0,0 +1,87 @@
+======================================
+Adoption Guide for ``-fbounds-safety``
+======================================
+
+.. contents::
+   :local:
+
+Where to get ``-fbounds-safety``
+================================
+
+The open sourcing to llvm.org's ``llvm-project`` is still on going and the
+feature is not available yet. In the mean time, the preview implementation is
+available
+`here <https://github.com/swiftlang/llvm-project/tree/stable/20240723>`_ in a
+fork of ``llvm-project``. Please follow
+`Building LLVM with CMake <https://llvm.org/docs/CMake.html>`_ to build the
+compiler.
+
+Feature flag
+============
+
+Pass ``-fbounds-safety`` as a Clang compilation flag for the C file that you
+want to adopt. We recommend adopting the model file by file, because adoption
+requires some effort to add bounds annotations and fix compiler diagnostics.
+
+Include ``ptrcheck.h``
+======================
+
+``ptrcheck.h`` is a Clang toolchain header to provide definition of the bounds
+annotations such as ``__counted_by``, ``__counted_by_or_null``, ``__sized_by``,
+etc. In the LLVM source tree, the header is located in
+``llvm-project/clang/lib/Headers/ptrcheck.h``.
+
+
+Add bounds annotations on pointers as necessary
+===============================================
+
+Annotate pointers on struct fields and function parameters if they are pointing
+to an array of object, with appropriate bounds annotations. Please see
+:doc:`BoundsSafety` to learn what kind of bounds annotations are available and
+their semantics. Note that local pointer variables typically don't need bounds
+annotations because they are implicitely a wide pointer (``__bidi_indexable``)
+that automatically carries the bounds information.
+
+Address compiler diagnostics
+============================
+
+Once you pass ``-fbounds-safety`` to compiler a C file, you will see some new
+compiler warnings and errors, which will lead you to adopt the feature and
+to remove unsafeness in the code. Consider the following example:
+
+.. code-block:: c
+
+   #include <ptrcheck.h>
+
+   void init_buf(int *p, int n) {
+      for (int i = 0; i < n; ++i)
+         p[i] = 0; // error: array subscript on single pointer 'p' must use a constant index of 0 to be in bounds
+   }
+
+The parameter ``int *p`` doesn't have a bounds annotation, so the compiler will
+complain about the code indexing into it (``p[i]``). To address the diagnostics,
+you should add a bounds annotation on ``int *p`` so that the compiler can reason
+about the safety of the array subscript. In the following example, ``p`` is now
+``int *__counted_by(n)``, so the compiler will allow the array subscript with
+additional run-time checks as necessary.
+
+.. code-block:: c
+
+   #include <ptrcheck.h>
+
+   void init_buf(int *__counted_by(n) p, int n) {
+      for (int i = 0; i < n; ++i)
+         p[i] = 0; // ok; `p` is now has a type with bounds annotation.
+   }
+
+Run unit tests to fix new run-time traps
----------------
delcypher wrote:

```suggestion
Run test suites to fix new run-time traps
```

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