Use TERM_PRIMARY_* and TERM_IMMED* macros, following erl_term.h

Erlang/OTP's erl_term.h defines several macros to encode terms and
distinguishes `TAG_PRIMARY_*` for the two lowest bits, `_TAG_IMMED1*` for
the lowest four bits and `_TAG_IMMED2*` for the lowest six bits.

AtomVM term.h uses `TERM_BOXED_*` for the first word of boxed items.
It used magic number `0x2` or `TERM_BOXED_VALUE_TAG` instead of what
erl_term.h calls `TAG_PRIMARY_BOXED`, which is confusing as it's not related
to the first word of boxed item but to the (lowest two bits of the) term itself.

This change introduces `TERM_PRIMARY_*` macros following Erlang/OTP erl_term.h's
`TAG_PRIMARY_*` macros, and replaces all matching magic numbers with these
macros.

It also introduces `TERM_IMMED2_*` macros and uses them instead of magic
numbers.

`TERM_BOXED_VALUE_TAG` is marked as deprecated but kept.

No macro called `TERM_IMMED1_*` is introduced as AtomVM already uses
non-confusing macros `TERM_PID_TAG`, `TERM_PORT_TAG` and `TERM_INTEGER_TAG`.

Signed-off-by: Paul Guyot <pguyot@kallisys.net>

Author: pguyot

src/libAtomVM/memory.c

@@ -393,7 +393,7 @@ static enum MemoryGCResult memory_shrink(Context *ctx, size_t new_size, size_t n
         term *boxed_ptr = term_to_term_ptr(head);
         term *new_boxed_ptr = memory_rewrite_pointer(boxed_ptr, old_heap_root, old_end, delta);
         if (boxed_ptr != new_boxed_ptr) {
-            new_list_ptr[1] = ((term) new_boxed_ptr) | TERM_BOXED_VALUE_TAG;
+            new_list_ptr[1] = ((term) new_boxed_ptr) | TERM_PRIMARY_BOXED;
         }
         // Loop with tail.
         mso_ptr = new_list_ptr;
@@ -660,7 +660,7 @@ static void memory_scan_and_copy(HeapFragment *old_fragment, term *mem_start, co
 
                 case TERM_BOXED_REFC_BINARY: {
                     TRACE("- Found refc binary.\n");
-                    term ref = ((term) ptr) | TERM_BOXED_VALUE_TAG;
+                    term ref = ((term) ptr) | TERM_PRIMARY_BOXED;
                     if (!term_refc_binary_is_const(ref)) {
                         *mso_list = term_list_init_prepend(ptr + REFC_BINARY_CONS_OFFSET, ref, *mso_list);
                         refc_binary_increment_refcount((struct RefcBinary *) term_refc_binary_ptr(ref));
@@ -748,7 +748,7 @@ static void memory_scan_and_rewrite(size_t count, term *terms, const term *old_s
                     term *boxed_ptr = term_to_term_ptr(binary_or_state);
                     term *new_boxed_ptr = memory_rewrite_pointer(boxed_ptr, old_start, old_end, delta);
                     if (boxed_ptr != new_boxed_ptr) {
-                        *ptr = ((term) new_boxed_ptr) | TERM_BOXED_VALUE_TAG;
+                        *ptr = ((term) new_boxed_ptr) | TERM_PRIMARY_BOXED;
                     }
                     ptr += term_get_size_from_boxed_header(t);
                     break;
@@ -815,7 +815,7 @@ static void memory_scan_and_rewrite(size_t count, term *terms, const term *old_s
             term *boxed_ptr = term_to_term_ptr(t);
             term *new_boxed_ptr = memory_rewrite_pointer(boxed_ptr, old_start, old_end, delta);
             if (boxed_ptr != new_boxed_ptr) {
-                ptr[-1] = ((term) new_boxed_ptr) | TERM_BOXED_VALUE_TAG;
+                ptr[-1] = ((term) new_boxed_ptr) | TERM_PRIMARY_BOXED;
             }
         }
     }
@@ -876,7 +876,7 @@ HOT_FUNC static term memory_shallow_copy_term(HeapFragment *old_fragment, term t
         // However it is also required to avoid boxed terms duplication.
         // So instead all empty tuples will reference the same boxed term.
         if (boxed_size == 1) {
-            return ((term) &empty_tuple) | TERM_BOXED_VALUE_TAG;
+            return ((term) &empty_tuple) | TERM_PRIMARY_BOXED;
         }
 
         term *dest = *new_heap;
@@ -885,7 +885,7 @@ HOT_FUNC static term memory_shallow_copy_term(HeapFragment *old_fragment, term t
         }
         *new_heap += boxed_size;
 
-        term new_term = ((term) dest) | TERM_BOXED_VALUE_TAG;
+        term new_term = ((term) dest) | TERM_PRIMARY_BOXED;
 
         if (move) {
             memory_replace_with_moved_marker(boxed_value, new_term);

src/libAtomVM/opcodesswitch.h

@@ -1692,7 +1692,7 @@ term make_fun(Context *ctx, const Module *mod, int fun_index, term argv[])
         boxed_func[i] = *ext_reg;
     }
 
-    return ((term) boxed_func) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_func) | TERM_PRIMARY_BOXED;
 }
 
 static bool maybe_call_native(Context *ctx, AtomString module_name, AtomString function_name, int arity,
@@ -6626,7 +6626,7 @@ HOT_FUNC int scheduler_entry_point(GlobalContext *glb)
                 }
 
                 #ifdef IMPL_EXECUTE_LOOP
-                    term fun = ((term) boxed_func) | TERM_BOXED_VALUE_TAG;
+                    term fun = ((term) boxed_func) | TERM_PRIMARY_BOXED;
                     WRITE_REGISTER(dreg, fun);
                 #endif
                 break;

src/libAtomVM/term.c

@@ -869,7 +869,7 @@ term term_alloc_refc_binary(size_t size, bool is_const, Heap *heap, GlobalContex
     boxed_value[0] = ((TERM_BOXED_REFC_BINARY_SIZE - 1) << 6) | TERM_BOXED_REFC_BINARY;
     boxed_value[1] = (term) size;
     boxed_value[2] = (term) is_const ? RefcBinaryIsConst : RefcNoFlags;
-    term ret = ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    term ret = ((term) boxed_value) | TERM_PRIMARY_BOXED;
     if (is_const) {
         boxed_value[3] = (term) NULL;
         // TODO Consider making const refc binaries 4 words instead of 6
@@ -913,7 +913,7 @@ term term_alloc_sub_binary(term binary_or_state, size_t offset, size_t len, Heap
     boxed[2] = (term) offset;
     boxed[3] = binary;
 
-    return ((term) boxed) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed) | TERM_PRIMARY_BOXED;
 }
 
 term term_get_map_assoc(term map, term key, GlobalContext *glb)

src/libAtomVM/term.h

@@ -47,7 +47,13 @@
 extern "C" {
 #endif
 
-#define TERM_BOXED_VALUE_TAG 0x2
+#define TERM_PRIMARY_MASK 0x3
+#define TERM_PRIMARY_CP 0x0
+#define TERM_PRIMARY_LIST 0x1
+#define TERM_PRIMARY_BOXED 0x2
+// #define TERM_PRIMARY_IMMED 0x3
+
+#define TERM_BOXED_VALUE_TAG _Pragma ("TERM_BOXED_VALUE_TAG is deprecated, use TERM_PRIMARY_BOXED instead") TERM_PRIMARY_BOXED
 
 #define TERM_IMMED_TAG_MASK 0xF
 #define TERM_PID_TAG 0x3
@@ -61,7 +67,6 @@ extern "C" {
 #define TERM_BOXED_REF 0x10
 #define TERM_BOXED_FUN 0x14
 #define TERM_BOXED_FLOAT 0x18
-#define TERM_CATCH_TAG 0x1B
 #define TERM_BOXED_REFC_BINARY 0x20
 #define TERM_BOXED_HEAP_BINARY 0x24
 #define TERM_BOXED_SUB_BINARY 0x28
@@ -71,6 +76,12 @@ extern "C" {
 #define TERM_BOXED_EXTERNAL_PORT 0x34
 #define TERM_BOXED_EXTERNAL_REF 0x38
 
+#define TERM_IMMED2_TAG_MASK 0x3F
+#define TERM_IMMED2_TAG_SIZE 6
+#define TERM_IMMED2_ATOM 0xB
+#define TERM_IMMED2_CATCH 0x1B
+#define TERM_NIL 0x3B
+
 #define TERM_UNUSED 0x2B
 #define TERM_RESERVED_MARKER(x) ((x << 6) | TERM_UNUSED)
 
@@ -137,7 +148,7 @@ extern "C" {
 
 #define TERM_DEBUG_ASSERT(...)
 
-#define TERM_FROM_ATOM_INDEX(atom_index) ((atom_index << 6) | 0xB)
+#define TERM_FROM_ATOM_INDEX(atom_index) ((atom_index << TERM_IMMED2_TAG_SIZE) | TERM_IMMED2_ATOM)
 
 // Local ref is at most 30 bytes:
 // 2^32-1 = 4294967295 (10 chars)
@@ -293,7 +304,7 @@ static inline const term *term_to_const_term_ptr(term t)
 static inline bool term_is_atom(term t)
 {
     /* atom: | atom index | 00 10 11 */
-    return ((t & TERM_BOXED_TAG_MASK) == 0xB);
+    return ((t & TERM_IMMED2_TAG_MASK) == TERM_IMMED2_ATOM);
 }
 
 /**
@@ -318,7 +329,7 @@ static inline bool term_is_invalid_term(term t)
 static inline bool term_is_nil(term t)
 {
     /* nil: 11 10 11 */
-    return ((t & TERM_BOXED_TAG_MASK) == 0x3B);
+    return ((t & TERM_IMMED2_TAG_MASK) == TERM_NIL);
 }
 
 /**
@@ -331,7 +342,7 @@ static inline bool term_is_nil(term t)
 static inline bool term_is_nonempty_list(term t)
 {
     /* list: 01 */
-    return ((t & 0x3) == 0x1);
+    return ((t & TERM_PRIMARY_MASK) == TERM_PRIMARY_LIST);
 }
 
 /**
@@ -357,7 +368,7 @@ static inline bool term_is_list(term t)
 static inline bool term_is_boxed(term t)
 {
     /* boxed: 10 */
-    return ((t & 0x3) == 0x2);
+    return ((t & TERM_PRIMARY_MASK) == TERM_PRIMARY_BOXED);
 }
 
 /**
@@ -383,7 +394,7 @@ static inline size_t term_get_size_from_boxed_header(term header)
 static inline size_t term_boxed_size(term t)
 {
     /* boxed: 10 */
-    TERM_DEBUG_ASSERT((t & 0x3) == 0x2);
+    TERM_DEBUG_ASSERT((t & TERM_PRIMARY_MASK) == TERM_PRIMARY_BOXED);
 
     const term *boxed_value = term_to_const_term_ptr(t);
     return term_get_size_from_boxed_header(*boxed_value);
@@ -399,7 +410,7 @@ static inline size_t term_boxed_size(term t)
 static inline bool term_is_binary(term t)
 {
     /* boxed: 10 */
-    if ((t & 0x3) == 0x2) {
+    if ((t & TERM_PRIMARY_MASK) == TERM_PRIMARY_BOXED) {
         const term *boxed_value = term_to_const_term_ptr(t);
         int masked_value = boxed_value[0] & TERM_BOXED_TAG_MASK;
         switch (masked_value) {
@@ -521,7 +532,7 @@ static inline bool term_is_any_integer(term t)
 
 static inline bool term_is_catch_label(term t)
 {
-    return (t & TERM_BOXED_TAG_MASK) == TERM_CATCH_TAG;
+    return (t & TERM_IMMED2_TAG_MASK) == TERM_IMMED2_CATCH;
 }
 
 /**
@@ -774,7 +785,7 @@ static inline bool term_is_external_fun(term t)
  */
 static inline bool term_is_cp(term t)
 {
-    return ((t & 0x3) == 0);
+    return ((t & TERM_PRIMARY_MASK) == TERM_PRIMARY_CP);
 }
 
 /**
@@ -796,7 +807,7 @@ static inline term term_invalid_term()
  */
 static inline term term_nil()
 {
-    return 0x3B;
+    return TERM_NIL;
 }
 
 /**
@@ -1022,7 +1033,7 @@ static inline term term_make_boxed_int(avm_int_t value, Heap *heap)
     term *boxed_int = memory_heap_alloc(heap, 1 + BOXED_TERMS_REQUIRED_FOR_INT);
     boxed_int[0] = (BOXED_TERMS_REQUIRED_FOR_INT << 6) | TERM_BOXED_POSITIVE_INTEGER; // OR sign bit
     boxed_int[1] = value;
-    return ((term) boxed_int) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_int) | TERM_PRIMARY_BOXED;
 }
 
 static inline term term_make_boxed_int64(avm_int64_t large_int64, Heap *heap)
@@ -1044,7 +1055,7 @@ static inline term term_make_boxed_int64(avm_int64_t large_int64, Heap *heap)
     #else
         #error "unsupported configuration."
     #endif
-    return ((term) boxed_int) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_int) | TERM_PRIMARY_BOXED;
 }
 
 static inline term term_make_maybe_boxed_int64(avm_int64_t value, Heap *heap)
@@ -1079,7 +1090,7 @@ static inline size_t term_boxed_integer_size(avm_int64_t value)
 
 static inline term term_from_catch_label(unsigned int module_index, unsigned int label)
 {
-    return (term) ((module_index << 24) | (label << 6) | TERM_CATCH_TAG);
+    return (term) ((module_index << 24) | (label << 6) | TERM_IMMED2_CATCH);
 }
 
 /**
@@ -1228,7 +1239,7 @@ static inline term term_create_uninitialized_binary(size_t size, Heap *heap, Glo
         boxed_value[0] = (size_in_terms << 6) | TERM_BOXED_HEAP_BINARY;
         boxed_value[1] = size;
 
-        return ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+        return ((term) boxed_value) | TERM_PRIMARY_BOXED;
     } else {
         return term_alloc_refc_binary(size, false, heap, glb);
     }
@@ -1416,7 +1427,7 @@ static inline term term_from_ref_ticks(uint64_t ref_ticks, Heap *heap)
         #error "terms must be either 32 or 64 bit wide"
     #endif
 
-    return ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_value) | TERM_PRIMARY_BOXED;
 }
 
 static inline uint64_t term_to_ref_ticks(term rt)
@@ -1460,7 +1471,7 @@ static inline term term_make_external_process_id(term node, uint32_t process_id,
     external_thing_words[2] = process_id;
     external_thing_words[3] = serial;
 
-    return ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_value) | TERM_PRIMARY_BOXED;
 }
 
 /**
@@ -1484,7 +1495,7 @@ static inline term term_make_external_port_number(term node, uint64_t number, ui
     external_thing_words[2] = number >> 32;
     external_thing_words[3] = (uint32_t) number;
 
-    return ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_value) | TERM_PRIMARY_BOXED;
 }
 
 /**
@@ -1600,7 +1611,7 @@ static inline term term_make_external_reference(term node, uint16_t len, uint32_
         #error "terms must be either 32 or 64 bit wide"
     #endif
 
-    return ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_value) | TERM_PRIMARY_BOXED;
 }
 
 /**
@@ -1666,7 +1677,7 @@ static inline term term_alloc_tuple(uint32_t size, Heap *heap)
     term *boxed_value = memory_heap_alloc(heap, 1 + size);
     boxed_value[0] = (size << 6); //tuple
 
-    return ((term) boxed_value) | 0x2;
+    return ((term) boxed_value) | TERM_PRIMARY_BOXED;
 }
 
 /**
@@ -1740,7 +1751,7 @@ static inline term term_from_string(const uint8_t *data, uint16_t size, Heap *he
         list_cells[i] = (term) &list_cells[i + 2] | 0x1;
         list_cells[i + 1] = term_from_int11(data[i / 2]);
     }
-    list_cells[size * 2 - 2] = 0x3B;
+    list_cells[size * 2 - 2] = TERM_NIL;
 
     return ((term) list_cells) | 0x1;
 }
@@ -1876,7 +1887,7 @@ static inline term term_from_float(avm_float_t f, Heap *heap)
     float_term_t *boxed_float = (float_term_t *) (boxed_value + 1);
     boxed_float->f = f;
 
-    return ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_value) | TERM_PRIMARY_BOXED;
 }
 
 static inline avm_float_t term_to_float(term t)
@@ -1985,7 +1996,7 @@ static inline term term_make_function_reference(term m, term f, term a, Heap *he
     boxed_func[2] = f;
     boxed_func[3] = a;
 
-    return ((term) boxed_func) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_func) | TERM_PRIMARY_BOXED;
 }
 
 static inline bool term_is_match_state(term t)
@@ -2066,7 +2077,7 @@ static inline term term_alloc_bin_match_state(term binary_or_state, int slots, H
         }
     }
 
-    return ((term) boxed_match_state) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_match_state) | TERM_PRIMARY_BOXED;
 }
 
 /**
@@ -2080,7 +2091,7 @@ static inline term term_alloc_bin_match_state(term binary_or_state, int slots, H
 static inline void term_truncate_boxed(term boxed, size_t new_size, Heap *heap)
 {
     /* boxed: 10 */
-    TERM_DEBUG_ASSERT((t & 0x3) == 0x2);
+    TERM_DEBUG_ASSERT((t & TERM_PRIMARY_MASK) == TERM_PRIMARY_BOXED);
 
     term *boxed_value = term_to_term_ptr(boxed);
     int size_diff = (boxed_value[0] >> 6) - new_size;
@@ -2127,7 +2138,7 @@ static inline term term_alloc_map_maybe_shared(avm_uint_t size, term keys, Heap
     boxed_value[0] = ((1 + size) << 6) | TERM_BOXED_MAP;
     boxed_value[term_get_map_keys_offset()] = keys;
 
-    return ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    return ((term) boxed_value) | TERM_PRIMARY_BOXED;
 }
 
 static inline term term_alloc_map(avm_uint_t size, Heap *heap)
@@ -2229,7 +2240,7 @@ static inline term term_from_resource(void *resource, Heap *heap)
     boxed_value[0] = ((TERM_BOXED_REFC_BINARY_SIZE - 1) << 6) | TERM_BOXED_REFC_BINARY;
     boxed_value[1] = (term) 0; // binary size, this is pre ERTS 9.0 (OTP-20.0) behavior
     boxed_value[2] = (term) RefcNoFlags;
-    term ret = ((term) boxed_value) | TERM_BOXED_VALUE_TAG;
+    term ret = ((term) boxed_value) | TERM_PRIMARY_BOXED;
     boxed_value[3] = (term) refc;
     // Add the resource to the mso list
     refc->ref_count++;