[BoundsSafety][doc] Make it clear that the feature is work-in-progress

[rapidsna]

The -fbounds-safety feature is not available yet and the implementation is still in progress, which will be guarded by -fexperimental-bounds-safety. To avoid the confusion, we're making it more explicit that the feature is not available yet and the document only describes the model.

[llvmbot]

@llvm/pr-subscribers-clang

Author: Yeoul Na (rapidsna)

Changes

The -fbounds-safety feature is not available yet and the implementation is still in progress, which will be guarded by -fexperimental-bounds-safety. This is to make it more explicit in the document that the feature is not available yet and it only describes the model.

---

Full diff: https://github.com/llvm/llvm-project/pull/95964.diff

2 Files Affected:

• (modified) clang/docs/BoundsSafety.rst (+4-3)
• (modified) clang/docs/BoundsSafetyImplPlans.rst (+32-33)

diff --git a/clang/docs/BoundsSafety.rst b/clang/docs/BoundsSafety.rst
index f1837675ec9bf..bd891733b7754 100644
--- a/clang/docs/BoundsSafety.rst
+++ b/clang/docs/BoundsSafety.rst
@@ -8,6 +8,9 @@
 Overview
 ========
 
+**NOTE:** This is a design document and the feature is not available for users yet.
+Please find :doc:`BoundsSafetyImplPlans` for more details.
+
 ``-fbounds-safety`` is a C extension to enforce bounds safety to prevent
 out-of-bounds (OOB) memory accesses, which remain a major source of security
 vulnerabilities in C. ``-fbounds-safety`` aims to eliminate this class of bugs
@@ -55,9 +58,7 @@ adopt, offering these properties that make it widely adoptable in practice:
 * It has a relatively low adoption cost.
 
 This document discusses the key designs of ``-fbounds-safety``. The document is
-subject to be actively updated with a more detailed specification. The
-implementation plan can be found in :doc:`BoundsSafetyImplPlans`.
-
+subject to be actively updated with a more detailed specification.
 
 Programming Model
 =================
diff --git a/clang/docs/BoundsSafetyImplPlans.rst b/clang/docs/BoundsSafetyImplPlans.rst
index 4fbf87f966350..93c2ed7b43402 100644
--- a/clang/docs/BoundsSafetyImplPlans.rst
+++ b/clang/docs/BoundsSafetyImplPlans.rst
@@ -5,8 +5,31 @@ Implementation plans for ``-fbounds-safety``
 .. contents::
    :local:
 
+Gradual updates with experimental flag
+======================================
+
+The feature will be implemented as a series of smaller PRs and we will guard our
+implementation with an experimental flag ``-fexperimental-bounds-safety`` until
+the usable model is fully available. Once the model is ready for use, we will
+expose the flag ``-fbounds-safety``.
+
+Possible patch sets
+-------------------
+
+* External bounds annotations and the (late) parsing logic.
+* Internal bounds annotations (wide pointers) and their parsing logic.
+* Clang code generation for wide pointers with debug information.
+* Pointer cast semantics involving bounds annotations (this could be divided
+  into multiple sub-PRs).
+* CFG analysis for pairs of related pointer and count assignments and the likes.
+* Bounds check expressions in AST and the Clang code generation (this could also
+  be divided into multiple sub-PRs).
+
+Proposed implementation
+=======================
+
 External bounds annotations
-===========================
+---------------------------
 
 The bounds annotations are C type attributes appertaining to pointer types. If
 an attribute is added to the position of a declaration attribute, e.g., ``int
@@ -14,7 +37,7 @@ an attribute is added to the position of a declaration attribute, e.g., ``int
 type of the declaration (``int *``).
 
 New sugar types
-===============
+---------------
 
 An external bounds annotation creates a type sugar of the underlying pointer
 types. We will introduce a new sugar type, ``DynamicBoundsPointerType`` to
@@ -29,7 +52,7 @@ overloading. However, this design requires a separate logic to walk through the
 entire type hierarchy to check type compatibility of bounds annotations.
 
 Late parsing for C
-==================
+------------------
 
 A bounds annotation such as ``__counted_by(count)`` can be added to type of a
 struct field declaration where count is another field of the same struct
@@ -43,7 +66,7 @@ same logic. This requires introducing late parsing logic for C/C++ type
 attributes.
 
 Internal bounds annotations
-===========================
+---------------------------
 
 ``__indexable`` and ``__bidi_indexable`` alter pointer representations to be
 equivalent to a struct with the pointer and the corresponding bounds fields.
@@ -65,7 +88,7 @@ operations returning wide pointers. Alternatively, a new ``TEK`` and an
 expression emitter dedicated to wide pointers could be introduced.
 
 Default bounds annotations
-==========================
+--------------------------
 
 The model may implicitly add ``__bidi_indexable`` or ``__single`` depending on
 the context of the declaration that has the pointer type. ``__bidi_indexable``
@@ -79,7 +102,7 @@ This also requires the parser to reset the type of the declaration with the
 newly created type with the right default attribute.
 
 Promotion expression
-====================
+--------------------
 
 A new expression will be introduced to represent the conversion from a pointer
 with an external bounds annotation, such as ``__counted_by``, to
@@ -88,7 +111,7 @@ CastExprs because it requires an extra subexpression(s) to provide the bounds
 information necessary to create a wide pointer.
 
 Bounds check expression
-=======================
+-----------------------
 
 Bounds checks are part of semantics defined in the ``-fbounds-safety`` language
 model. Hence, exposing the bounds checks and other semantic actions in the AST
@@ -98,7 +121,7 @@ and has the additional sub-expressions that are necessary to perform the check
 according to the kind.
 
 Paired assignment check
-=======================
+-----------------------
 
 ``-fbounds-safety`` enforces that variables or fields related with the same
 external bounds annotation (e.g., ``buf`` and ``count`` related with
@@ -123,7 +146,7 @@ provides a linear view of statements within each ``CFGBlock`` (Clang
 ``CFGBlock`` represents a single basic block in a source-level CFG).
 
 Bounds check optimizations
-==========================
+--------------------------
 
 In ``-fbounds-safety``, the Clang frontend emits run-time checks for every
 memory dereference if the type system or analyses in the frontend couldn’t
@@ -229,27 +252,3 @@ solution.
 
 ``-fbounds-safety`` is not currently supported in C++, but we believe the
 general approach would be applicable for future efforts.
-
-Upstreaming plan
-================
-
-Gradual updates with experimental flag
---------------------------------------
-
-The upstreaming will take place as a series of smaller PRs and we will guard our
-implementation with an experimental flag ``-fexperimental-bounds-safety`` until
-the usable model is fully upstreamed. Once the model is ready for use, we will
-expose the flag ``-fbounds-safety``.
-
-Possible patch sets
--------------------
-
-* External bounds annotations and the (late) parsing logic.
-* Internal bounds annotations (wide pointers) and their parsing logic.
-* Clang code generation for wide pointers with debug information.
-* Pointer cast semantics involving bounds annotations (this could be divided
-  into multiple sub-PRs).
-* CFG analysis for pairs of related pointer and count assignments and the likes.
-* Bounds check expressions in AST and the Clang code generation (this could also
-  be divided into multiple sub-PRs).
-

[rapidsna]

@AaronBallman do you think we should remove the doc from the release notes because it's not ready yet?

[AaronBallman]

Thank you for updating the documentation, the changes LGTM (had one minor suggestion you can take or leave as you'd like). I think it's better for us to have the documentation than not, so I'm fine with this approach of letting people know about the current and future flags.

[rapidsna]

@AaronBallman Thanks for your prompt feedback!