================
@@ -0,0 +1,362 @@
+==================================================
+``-fbounds-safety``: Enforcing bounds safety for C
+==================================================
+
+.. contents::
+ :local:
+
+Overview
+========
+
+``-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
by turning OOB accesses into deterministic traps.
+
+The ``-fbounds-safety`` extension offers bounds annotations that programmers
can use to attach bounds to pointers. For example, programmers can add the
``__counted_by(N)`` annotation to parameter ``ptr``, indicating that the
pointer has ``N`` valid elements:
+
+.. code-block:: c
+
+ void foo(int *__counted_by(N) ptr, size_t N);
+
+Using this bounds information, the compiler inserts bounds checks on every
pointer dereference, ensuring that the program does not access memory outside
the specified bounds. The compiler requires programmers to provide enough
bounds information so that the accesses can be checked at either run time or
compile time — and it rejects code if it cannot.
+
+The most important contribution of ``-fbounds-safety`` is how it reduces the
programmer’s annotation burden by reconciling bounds annotations at ABI
boundaries with the use of implicit wide pointers (a.k.a. “fat” pointers) that
carry bounds information on local variables without the need for annotations.
We designed this model so that it preserves ABI compatibility with C while
minimizing adoption effort.
+
+The ``-fbounds-safety`` extension has been adopted on millions of lines of
production C code and proven to work in a consumer operating system setting.
The extension was designed to enable incremental adoption — a key requirement
in real-world settings where modifying an entire project and its dependencies
all at once is often not possible. It also addresses multiple of other
practical challenges that have made existing approaches to safer C dialects
difficult to adopt, offering these properties that make it widely adoptable in
practice:
+
+* It is designed to preserve the Application Binary Interface (ABI).
+* It interoperates well with plain C code.
+* It can be adopted partially and incrementally while still providing safety
benefits.
+* It is syntactically and semantically compatible with C.
+* Consequently, source code that adopts the extension can continue to be
compiled by toolchains that do not support the extension.
+* It has a relatively low adoption cost.
+* It can be implemented on top of Clang.
+
+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 `Implementation plans for -fbounds-safety
<BoundsSafetyImplPlans.rst>`_.
+
+Programming Model
+=================
+
+Overview
+--------
+
+``-fbounds-safety`` ensures that pointers are not used to access memory beyond
their bounds by performing bounds checking. If a bounds check fails, the
program will deterministically trap before out-of-bounds memory is accessed.
+
+In our model, every pointer has an explicit or implicit bounds attribute that
determines its bounds and ensures guaranteed bounds checking. Consider the
example below where the ``__counted_by(count)`` annotation indicates that
parameter ``p`` points to a buffer of integers containing ``count`` elements.
An off-by-one error is present in the loop condition, leading to ``p[i]`` being
out-of-bounds access during the loop’s final iteration. The compiler inserts a
bounds check before ``p`` is dereferenced to ensure that the access remains
within the specified bounds.
+
+.. code-block:: c
+
+ void fill_array_with_indices(int *__counted_by(count) p, unsigned count) {
+ // off-by-one error (i < count)
+ for (unsigned i = 0; i <= count; ++i) {
+ // bounds check inserted:
+ // if (i >= count) trap();
+ p[i] = i;
+ }
+ }
+
+A bounds annotation defines an invariant for the pointer type, and the model
ensures that this invariant remains true. In the example below, pointer ``p``
annotated with ``__counted_by(count)`` must always point to a memory buffer
containing at least ``count`` elements of the pointee type. Increasing the
value of ``count``, like in the example below, would violate this invariant and
permit out-of-bounds access to the pointer. To avoid this, the compiler emits
either a compile-time error or a run-time trap. Section `Maintaining
correctness of bounds annotations`_ provides more details about the programming
model.
----------------
rapidsna wrote:
Good point. The compiler still insert run-time checks even when `count` seems
to be decreasing because `count` may be underflow or wrap. I tweaked the text
and added more examples.
https://github.com/llvm/llvm-project/pull/70749
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
