clang/docs/BoundsSafetyAdoptionGuide.rst

   1 ======================================
   2 Adoption Guide for ``-fbounds-safety``
   3 ======================================
   4
   5 .. contents::
   6    :local:
   7
   8 Where to get ``-fbounds-safety``
   9 ================================
  10
  11 The open sourcing to llvm.org's ``llvm-project`` is still on going and the
  12 feature is not available yet. In the mean time, the preview implementation is
  13 available
  14 `here <https://github.com/swiftlang/llvm-project/tree/stable/20240723>`_ in a
  15 fork of ``llvm-project``. Please follow
  16 `Building LLVM with CMake <https://llvm.org/docs/CMake.html>`_ to build the
  17 compiler.
  18
  19 Feature flag
  20 ============
  21
  22 Pass ``-fbounds-safety`` as a Clang compilation flag for the C file that you
  23 want to adopt. We recommend adopting the model file by file, because adoption
  24 requires some effort to add bounds annotations and fix compiler diagnostics.
  25
  26 Include ``ptrcheck.h``
  27 ======================
  28
  29 ``ptrcheck.h`` is a Clang toolchain header to provide definition of the bounds
  30 annotations such as ``__counted_by``, ``__counted_by_or_null``, ``__sized_by``,
  31 etc. In the LLVM source tree, the header is located in
  32 ``llvm-project/clang/lib/Headers/ptrcheck.h``.
  33
  34
  35 Add bounds annotations on pointers as necessary
  36 ===============================================
  37
  38 Annotate pointers on struct fields and function parameters if they are pointing
  39 to an array of object, with appropriate bounds annotations. Please see
  40 :doc:`BoundsSafety` to learn what kind of bounds annotations are available and
  41 their semantics. Note that local pointer variables typically don't need bounds
  42 annotations because they are implicitely a wide pointer (``__bidi_indexable``)
  43 that automatically carries the bounds information.
  44
  45 Address compiler diagnostics
  46 ============================
  47
  48 Once you pass ``-fbounds-safety`` to compiler a C file, you will see some new
  49 compiler warnings and errors, which guide adoption of ``-fbounds-safety``.
  50 Consider the following example:
  51
  52 .. code-block:: c
  53
  54    #include <ptrcheck.h>
  55
  56    void init_buf(int *p, int n) {
  57       for (int i = 0; i < n; ++i)
  58          p[i] = 0; // error: array subscript on single pointer 'p' must use a constant index of 0 to be in bounds
  59    }
  60
  61 The parameter ``int *p`` doesn't have a bounds annotation, so the compiler will
  62 complain about the code indexing into it (``p[i]``) as it assumes that ``p`` is
  63 pointing to a single ``int`` object or null. To address the diagnostics, you
  64 should add a bounds annotation on ``int *p`` so that the compiler can reason
  65 about the safety of the array subscript. In the following example, ``p`` is now
  66 ``int *__counted_by(n)``, so the compiler will allow the array subscript with
  67 additional run-time checks as necessary.
  68
  69 .. code-block:: c
  70
  71    #include <ptrcheck.h>
  72
  73    void init_buf(int *__counted_by(n) p, int n) {
  74       for (int i = 0; i < n; ++i)
  75          p[i] = 0; // ok; `p` is now has a type with bounds annotation.
  76    }
  77
  78 Run test suites to fix new run-time traps
  79 =========================================
  80
  81 Adopting ``-fbounds-safety`` may cause your program to trap if it violates
  82 bounds safety or it has incorrect adoption. Thus, it is necessary to perform
  83 run-time testing of your program to gain confidence that it won't trap at
  84 run time.
  85
  86 Repeat the process for each remaining file
  87 ==========================================
  88
  89 Once you've done with adopting a single C file, please repeat the same process
  90 for each remaining C file that you want to adopt.