================ @@ -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 _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
