From 6f58e4ab8d90166cac4e4da269a77c5134f12f1e Mon Sep 17 00:00:00 2001
From: Miquel Sabaté Solà <mssola@mssola.com>
Date: Thu, 9 Jul 2026 22:07:47 +0200
Subject: Add support for the asan:fixed-segments comment
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This magic comment allows for the definition of segments that are fixed
and for which references are always safe. This goes in tandem with the
asan:safe comment, which can then be used more sporadically.

Signed-off-by: Miquel Sabaté Solà <mssola@mssola.com>
---
 crates/nasm/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

(limited to 'crates/nasm/README.md')

diff --git a/crates/nasm/README.md b/crates/nasm/README.md
index 2d24011..2675bfb 100644
--- a/crates/nasm/README.md
+++ b/crates/nasm/README.md
@@ -312,6 +312,48 @@ now be written like so:
 jsr foo      ; check:safe
 ```
 
+Moreover, you can define whole segments as "fixed" ones with the
+`asan:fixed-segments` (or `check:fixed-segments`) comments. This way, you
+express to the assembler that references to addresses of these segments are
+guaranteed to always be valid. Consider the following example:
+
+```asm
+;;; asan:fixed-segments ONE, OTHER
+
+.segment "ONE"
+
+.proc foo
+    rts
+.endproc
+
+.segment "OTHER"
+
+.proc bar
+    rts
+.endproc
+
+.segment "FIXED"
+
+jsr foo
+jsr bar
+```
+
+In the code above, we state that both 'ONE' and 'OTHER' are guaranteed to have a
+stable address space (they are fixed, never to be re-mapped). Hence, the
+assembler won't spit any warning at the final two 'jsr' instructions. Also note
+that you can define this comment multiple times. So the code below achieves the
+same thing:
+
+```asm
+;;; asan:fixed-segments ONE
+.segment "ONE"
+;; bla bla
+
+;;; asan:fixed-segments OTHER
+.segment "OTHER"
+;; rest
+```
+
 ## Address sanitizer
 
 This assembler comes with a set of tools that builds up an "address
-- 
cgit v1.2.3