HOST machine-dependent predefined macros

1 files changed, 49 insertions, 22 deletions

diff --git a/doc/mcpu-cpp-en.md b/doc/mcpu-cpp-en.md
index 18633ae..9afaa0e 100644
--- a/doc/mcpu-cpp-en.md
+++ b/doc/mcpu-cpp-en.md
@@ -1265,7 +1265,10 @@ will not be mixed with the version of the standalone preprocessor.
 the established LibMPU/LibMPUIO `acsite.m4` approach: GCC predefined macros
 describe native type sizes, byte/word order, and machine-register width, while
 the installed `<libmpu.h>` is the final source of truth for LibMPU
-configuration.
+configuration. These GCC and LibMPU checks describe the HOST build environment,
+not the MCPU target ABI. The MCPU ABI is defined by the LibMCPU architecture
+and its ABI contracts; HOST-derived predefined macros must not be used to
+infer or change target type widths, pointer representation, or calling rules.
 
 In particular, the following values are captured and checked:
 
@@ -1348,7 +1351,7 @@ future MCPU language has no `float` type.
 LibMPU/MCPU environment parameters are published in the MCPU namespace:
 
 ```text
-__MCPU_MACHINE_REGISTER_WIDTH__
+__MCPU_HOST_MACHINE_REGISTER_WIDTH__
 __MCPU_REAL_IO_LIMIT__
 __MCPU_MATH_FN_LIMIT__
 __MCPU_INT_MAX_WIDTH__
@@ -1357,36 +1360,60 @@ __MCPU_COMPLEX_MAX_WIDTH__
 ```
 
 `__MCPU_INT_MAX_WIDTH__` is `NB_I_MAX * 8`; the Real/Complex maximum width is
-the configured `MPU_REAL_IO_LIMIT`. `__MCPU_MACHINE_REGISTER_WIDTH__` is the
-`BITS_PER_MACHINE_REGISTER` value of the installed LibMPU. Real I/O and math
+the configured `MPU_REAL_IO_LIMIT`. `__MCPU_HOST_MACHINE_REGISTER_WIDTH__` is the
+`BITS_PER_MACHINE_REGISTER` value of the installed LibMPU and reports a HOST
+characteristic, not an MCPU architectural register width. Real I/O and math
 limits are deliberately kept separate: `MPU_REAL_IO_LIMIT` controls existence
 of Real/Complex type families and text conversion, while `MPU_MATH_FN_LIMIT`
 controls availability of mathematical functions at a given width.
 
-### 8.6. MCPU size/ssize, `ptrdiff`, and pointers
+### 8.6. HOST machine size/ssize hints, `ptrdiff`, and pointers
 
 The future language does not inherit variable-width C names such as `short`,
-`int`, and `long`, and it does not use the C-style name `size_t` as part of its
-own ABI. The unsigned LibMPU size type and signed byte-count/error type are
-published symmetrically in the MCPU namespace. For a 64-bit configured profile,
-for example:
+`int`, and `long`, and the HOST C types `size_t` and `ssize_t` do not define
+the MCPU target ABI. The following nine predefined macros report the HOST
+machine characteristics of the environment in which the virtual MCPU runs:
 
 ```text
-#define __MCPU_SIZE_TYPE__ uint64
-#define __MCPU_SIZE_WIDTH__ 64
-#define __MCPU_SIZEOF_SIZE__ 8
-#define __MCPU_SIZE_MAX__ 0xffffffffffffffff
+__MCPU_HOST_MACHINE_REGISTER_WIDTH__
+__MCPU_HOST_MACHINE_SIZEOF_SIZE__
+__MCPU_HOST_MACHINE_SIZEOF_SSIZE__
+__MCPU_HOST_MACHINE_SIZE_MAX__
+__MCPU_HOST_MACHINE_SIZE_TYPE__
+__MCPU_HOST_MACHINE_SIZE_WIDTH__
+__MCPU_HOST_MACHINE_SSIZE_MAX__
+__MCPU_HOST_MACHINE_SSIZE_TYPE__
+__MCPU_HOST_MACHINE_SSIZE_WIDTH__
+```
+
+They are **not the source of truth for the MCPU ABI**. They are optional
+information available to guest programs, for example when a high-level
+programmer deliberately wants an MCPU integer type whose signedness and width
+match the HOST `size_t` or `ssize_t`. Using such a type is an explicit program
+choice; it does not make the guest pointer, integer, memory, or calling ABI
+HOST-dependent.
+
+For a HOST with 32-bit `size_t` and `ssize_t`, these size hints include:
+
+```text
+#define __MCPU_HOST_MACHINE_SIZE_TYPE__ uint32
+#define __MCPU_HOST_MACHINE_SIZE_WIDTH__ 32
+#define __MCPU_HOST_MACHINE_SIZEOF_SIZE__ 4
+#define __MCPU_HOST_MACHINE_SIZE_MAX__ 0xffffffff
 
-#define __MCPU_SSIZE_TYPE__ int64
-#define __MCPU_SSIZE_WIDTH__ 64
-#define __MCPU_SIZEOF_SSIZE__ 8
-#define __MCPU_SSIZE_MAX__ 0x7fffffffffffffff
+#define __MCPU_HOST_MACHINE_SSIZE_TYPE__ int32
+#define __MCPU_HOST_MACHINE_SSIZE_WIDTH__ 32
+#define __MCPU_HOST_MACHINE_SIZEOF_SSIZE__ 4
+#define __MCPU_HOST_MACHINE_SSIZE_MAX__ 0x7fffffff
 ```
 
-This is an MCPU-specific family, not an attempt to invent a nonexistent GNU CPP
-`__SSIZE_*` contract.
+For a HOST with 64-bit `size_t` and `ssize_t`, the same names instead report
+`uint64`/`int64`, widths of `64`, sizes of `8`, and the corresponding maxima
+`0xffffffffffffffff`/`0x7fffffffffffffff`. Register width is reported
+independently; it is not derived from `size_t`.
 
-The MCPU pointer ABI is independent of the host: PTR64 is always 64 bits wide:
+The MCPU pointer ABI is **HOST-independent**: PTR64 is always 64 bits wide,
+including when the HOST and its `size_t` are 32-bit:
 
 ```text
 #define __INTPTR_TYPE__ int64
@@ -1399,8 +1426,8 @@ The MCPU pointer ABI is independent of the host: PTR64 is always 64 bits wide:
 #define __MCPU_POINTER_WIDTH__ 64
 ```
 
-The difference between two MCPU pointers is signed and also fixed independently
-of the host:
+The difference between two MCPU pointers is signed and likewise fixed
+independently of the HOST:
 
 ```text
 #define __PTRDIFF_TYPE__ int64