[clang] [BoundsSafety][Doc] Add BoundsSafetyAdoptionGuide.rst (PR #120674)
Yeoul Na via cfe-commits
cfe-commits at lists.llvm.org
Tue Jan 21 17:11:10 PST 2025
https://github.com/rapidsna updated https://github.com/llvm/llvm-project/pull/120674
>From 390d37d9706472e46a34366bcaa519d34496b888 Mon Sep 17 00:00:00 2001
From: Yeoul Na <yeoul_na at apple.com>
Date: Fri, 20 Dec 2024 12:20:03 +0900
Subject: [PATCH 1/2] [BoundsSafety][Doc] Add BoundsSafetyAdoptionGuide.rst
---
clang/docs/BoundsSafety.rst | 9 ++-
clang/docs/BoundsSafetyAdoptionGuide.rst | 87 ++++++++++++++++++++++++
clang/docs/index.rst | 1 +
3 files changed, 96 insertions(+), 1 deletion(-)
create mode 100644 clang/docs/BoundsSafetyAdoptionGuide.rst
diff --git a/clang/docs/BoundsSafety.rst b/clang/docs/BoundsSafety.rst
index 8fd655663edb00..e24c69d8c7855f 100644
--- a/clang/docs/BoundsSafety.rst
+++ b/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.
\ No newline at end of file
+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:yeoul_na at apple.com>`_.
\ No newline at end of file
diff --git a/clang/docs/BoundsSafetyAdoptionGuide.rst b/clang/docs/BoundsSafetyAdoptionGuide.rst
new file mode 100644
index 00000000000000..b19d9188fe26a2
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/clang/docs/index.rst b/clang/docs/index.rst
index cc070059eede5d..349378b1efa214 100644
--- a/clang/docs/index.rst
+++ b/clang/docs/index.rst
@@ -40,6 +40,7 @@ Using Clang as a Compiler
SanitizerStats
SanitizerSpecialCaseList
BoundsSafety
+ BoundsSafetyAdoptionGuide
BoundsSafetyImplPlans
ControlFlowIntegrity
LTOVisibility
>From 1977894b1edaa6aa63deeb3013253688c4bce875 Mon Sep 17 00:00:00 2001
From: Yeoul Na <yeoul_na at apple.com>
Date: Tue, 21 Jan 2025 17:10:56 -0800
Subject: [PATCH 2/2] Address some of Dan's comments
---
clang/docs/BoundsSafetyAdoptionGuide.rst | 15 +++++++++------
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/clang/docs/BoundsSafetyAdoptionGuide.rst b/clang/docs/BoundsSafetyAdoptionGuide.rst
index b19d9188fe26a2..d97b906394797c 100644
--- a/clang/docs/BoundsSafetyAdoptionGuide.rst
+++ b/clang/docs/BoundsSafetyAdoptionGuide.rst
@@ -46,8 +46,8 @@ 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:
+compiler warnings and errors, which guide adoption of ``-fbounds-safety``.
+Consider the following example:
.. code-block:: c
@@ -59,8 +59,9 @@ to remove unsafeness in the code. Consider the following example:
}
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
+complain about the code indexing into it (``p[i]``) as it assumes that ``p`` is
+pointing to a single ``int`` object or null. 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.
@@ -74,11 +75,13 @@ additional run-time checks as necessary.
p[i] = 0; // ok; `p` is now has a type with bounds annotation.
}
-Run unit tests to fix new run-time traps
+Run test suites 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.
+bounds safety or it has incorrect adoption. Thus, it is necessary to perform
+run-time testing of your program to gain confidence that it won't trap at
+run time.
Repeat the process for each remaining file
==========================================
More information about the cfe-commits
mailing list