[BoundsSafety][Doc] Add BoundsSafetyAdoptionGuide.rst

Author: rapidsna

clang/docs/BoundsSafety.rst

@@ -996,4 +996,11 @@ and the soundness of the type system. This may incur significant code size
 overhead in unoptimized builds and leaving some of the adoption mistakes to be
 caught only at run time. This is not a fundamental limitation, however, because
 incrementally adding necessary static analysis will allow us to catch issues
-early on and remove unnecessary bounds checks in unoptimized builds.
+early on and remove unnecessary bounds checks in unoptimized builds.
+
+Try it out
+==========
+
+Your feedback on the programming model is valuable. You may want to follow the
+instruction in :doc:`BoundsSafetyAdoptionGuide` to play with ``-fbounds-safety``
+and please send your feedback to `Yeoul Na <mailto:[email protected]>`_.

clang/docs/BoundsSafetyAdoptionGuide.rst

@@ -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
+========================================
+
+Adopting ``-fbounds-safety`` may cause your program to trap if it violates
+bounds safety or it has incorrect adoption.
+
+Repeat the process for each remaining file
+==========================================
+
+Once you've done with adopting a single C file, please repeat the same process
+for each remaining C file that you want to adopt.

clang/docs/index.rst

@@ -40,6 +40,7 @@ Using Clang as a Compiler
    SanitizerStats
    SanitizerSpecialCaseList
    BoundsSafety
+   BoundsSafetyAdoptionGuide
    BoundsSafetyImplPlans
    ControlFlowIntegrity
    LTOVisibility