90 lines · plain
1======================================2Adoption Guide for ``-fbounds-safety``3======================================4 5.. contents::6 :local:7 8Where to get ``-fbounds-safety``9================================10 11The open sourcing to llvm.org's ``llvm-project`` is still on going and the12feature is not available yet. In the mean time, the preview implementation is13available14`here <https://github.com/swiftlang/llvm-project/tree/stable/20240723>`_ in a15fork of ``llvm-project``. Please follow16`Building LLVM with CMake <https://llvm.org/docs/CMake.html>`_ to build the17compiler.18 19Feature flag20============21 22Pass ``-fbounds-safety`` as a Clang compilation flag for the C file that you23want to adopt. We recommend adopting the model file by file, because adoption24requires some effort to add bounds annotations and fix compiler diagnostics.25 26Include ``ptrcheck.h``27======================28 29``ptrcheck.h`` is a Clang toolchain header to provide definition of the bounds30annotations such as ``__counted_by``, ``__counted_by_or_null``, ``__sized_by``,31etc. In the LLVM source tree, the header is located in32``llvm-project/clang/lib/Headers/ptrcheck.h``.33 34 35Add bounds annotations on pointers as necessary36===============================================37 38Annotate pointers on struct fields and function parameters if they are pointing39to an array of object, with appropriate bounds annotations. Please see40:doc:`BoundsSafety` to learn what kind of bounds annotations are available and41their semantics. Note that local pointer variables typically don't need bounds42annotations because they are implicitly a wide pointer (``__bidi_indexable``)43that automatically carries the bounds information.44 45Address compiler diagnostics46============================47 48Once you pass ``-fbounds-safety`` to compile a C file, you will see some new49compiler warnings and errors, which guide adoption of ``-fbounds-safety``.50Consider the following example:51 52.. code-block:: c53 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 bounds59 }60 61The parameter ``int *p`` doesn't have a bounds annotation, so the compiler will62complain about the code indexing into it (``p[i]``) as it assumes that ``p`` is63pointing to a single ``int`` object or null. To address the diagnostics, you64should add a bounds annotation on ``int *p`` so that the compiler can reason65about the safety of the array subscript. In the following example, ``p`` is now66``int *__counted_by(n)``, so the compiler will allow the array subscript with67additional run-time checks as necessary.68 69.. code-block:: c70 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 78Run test suites to fix new run-time traps79=========================================80 81Adopting ``-fbounds-safety`` may cause your program to trap if it violates82bounds safety or it has incorrect adoption. Thus, it is necessary to perform83run-time testing of your program to gain confidence that it won't trap at84run time.85 86Repeat the process for each remaining file87==========================================88 89Once you've done with adopting a single C file, please repeat the same process90for each remaining C file that you want to adopt.