diff options
Diffstat (limited to 'doc/mcpu-cpp-en.md')
| -rw-r--r-- | doc/mcpu-cpp-en.md | 71 |
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 |