classify_addr.h: explain the no_naked_pointers value model (#9684)

We are planning to support two configurations (with or without
naked pointers) in the runtime for at least a couple years, so I think
it is useful to explain their value models and corresponding runtime
functions/macros. This should help runtime developers reason about the
code written to support both modes.

1 files changed, 40 insertions, 0 deletions

diff --git a/runtime/caml/address_class.h b/runtime/caml/address_class.h
index 45e5410e32..b51ebbe32a 100644
--- a/runtime/caml/address_class.h
+++ b/runtime/caml/address_class.h
@@ -15,6 +15,46 @@
 
 /* Classification of addresses for GC and runtime purposes. */
 
+/* The current runtime supports two different configurations that
+   correspond to two different value models, depending on whether
+   "naked pointers", that do not point to a well-formed OCaml block,
+   are allowed (considered valid values).
+
+   In "classic mode", naked pointers are allowed, and the
+   implementation uses a page table. A valid value is then either:
+   - a tagged integer (Is_long or !Is_block from mlvalues.h)
+   - a pointer to the minor heap (Is_young)
+   - a pointer to the major heap (Is_in_heap)
+   - a pointer to a constant block statically-allocated by OCaml code
+     or the OCaml runtime (Is_in_static_data)
+   - a "foreign" pointer, which is none of the above; the destination
+     of those pointers may be a well-formed OCaml blocks, but it may
+     also be a naked pointer.
+
+   The macros and functions below give access to a global page table
+   to classify addresses to be able to implement Is_in_heap,
+   In_static_data (or their disjunction Is_in_value_area) and thus
+   detect values which may be naked pointers. The runtime
+   conservatively assumes that all foreign pointers may be naked
+   pointers, and uses the page table to not dereference/follow them.
+
+   In "no naked pointers" mode (when NO_NAKED_POINTERS is defined),
+   naked pointers are illegal, so pointers that are values can always
+   be assumed to point to well-formed blocks.
+
+   To support an implementation without a global page table, runtime
+   code should not rely on Is_in_heap and Is_in_static_data. This
+   corresponds to a simpler model where a valid value is either:
+   - a tagged integer (Is_long)
+   - a pointer to the minor heap (Is_young)
+   - a pointer to a well-formed block outside the minor heap
+     (it may be in the major heap, or static, or a foreign pointer,
+      without a check to distinguish the various cases).
+
+   (To create a well-formed block outside the heap that the GC will
+   not scan, one can use the Caml_out_of_heap_header from mlvalues.h.)
+*/
+
 #ifndef CAML_ADDRESS_CLASS_H
 #define CAML_ADDRESS_CLASS_H