https://github.com/rapidsna created
https://github.com/llvm/llvm-project/pull/95964
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.
>From 6ed8ac33952bc8f9a9b672740d45f25872ae1dbb Mon Sep 17 00:00:00 2001
From: Yeoul Na <yeoul...@apple.com>
Date: Tue, 18 Jun 2024 11:05:17 -0700
Subject: [PATCH] [BoundsSafety][doc] Make it clear that the feature is
work-in-progress
---
clang/docs/BoundsSafety.rst | 7 +--
clang/docs/BoundsSafetyImplPlans.rst | 65 ++++++++++++++--------------
2 files changed, 36 insertions(+), 36 deletions(-)
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).
-
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
