Note Non-Interoperable Macros and Types

[lenary]

These are sometimes documented by specific toolchains and compilers, but I thought it would be good to have a RISC-V specific document noting they are unstable.

Because they are non-interoperable, I didn't want to put them in the psABI document -- I thought this document would be a better place.

[aswaterman]

I had no idea that int_fastN_t was not of a fixed size for a given ABI. (Well, I guess we could choose to fix the size in our ABI if we so chose.)

I think [u]intmax_t need similar handling.

[kito-cheng]

Maybe we should mention std::hardware_destructive_interference_size and std::hardware_constructive_interference_size as well, the main user of __GCC_CONSTRUCTIVE_SIZE/__GCC_DESTRUCTIVE_SIZE

[cmuellner]

I'm not a native speaker, but is "unstable" really the proper word here?
Wouldn't "non-interoperable" or "machine-specific" be more precise?

When I hear "unstable type," I imagine a type that might disappear in future releases. But since all listed types are standard C/C++ types (incl. hardware_constructive_interference_size and hardware_destructive_interference_size as mentioned by Kito), they won't disappear and are stable in the sense that future compilation will work fine.

I'm not sure about adding __GCC_CONSTRUCTIVE_SIZE and __GCC_DESTRUCTIVE_SIZE here, as this seems to be a compiler implementation detail, which should not be exposed as public RISC-V API (the public API is hardware_constructive_interference_size and hardware_destructive_interference_size). Note that these identifiers are not even mentioned in the GCC documentation.

[lenary]

I had no idea that int_fastN_t was not of a fixed size for a given ABI. (Well, I guess we could choose to fix the size in our ABI if we so chose.)

Part of the reason for documenting this is because we haven't put these in the ABI -- and indeed clang/gcc disagree: https://godbolt.org/z/TYzaGaE4e

And also that iirc, different clang options can give you different sizes for these. I thought that -ffreestanding was a problem for clang but it doesn't look like it on CE, but that is probably down to the base c library also being wrong? Certainly fixing clang's stdint.h (only used when not hosted or there's no include_next) looked like a nightmare last time I investigated it.

I think [u]intmax_t need similar handling.

Maybe. I recall there is something effectively ABI in some of the max types. Quick googling turns up this as relevant https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2425.pdf - which tells me [u]intmax_t need to go in the ABI instead.

The ABI does define the alignment of maxalign_t (16), which is definitely ABI-breaking.

Maybe we should mention std::hardware_destructive_interference_size and std::hardware_constructive_interference_size as well, the main user of __GCC_CONSTRUCTIVE_SIZE/__GCC_DESTRUCTIVE_SIZE

I wanted to stick to the C preprocessor names, as those are what came up in the clang review review and this is a C API doc, but I can instead document the more public names.

I'm not a native speaker, but is "unstable" really the proper word here? Wouldn't "non-interoperable" or "machine-specific" be more precise?

When I hear "unstable type," I imagine a type that might disappear in future releases. But since all listed types are standard C/C++ types (incl. hardware_constructive_interference_size and hardware_destructive_interference_size as mentioned by Kito), they won't disappear and are stable in the sense that future compilation will work fine.

Non-interoperable might be better as an adjective, hitting the core problem, without saying these might go away.

I guess my feeling about "unstable" is that it means "the definition could change in ways that break your assumptions". This is mostly through being opposite to "stable" in the ABI world meaning "we'll try not to change this in a way that will break your assumptions".

I think "compilation will work fine" is a low bar for a specification, I would hope we are writing these documents so that execution does something reasonable.

I'm not sure about adding __GCC_CONSTRUCTIVE_SIZE and __GCC_DESTRUCTIVE_SIZE here, as this seems to be a compiler implementation detail, which should not be exposed as public RISC-V API (the public API is hardware_constructive_interference_size and hardware_destructive_interference_size). Note that these identifiers are not even mentioned in the GCC documentation.

They are mentioned in the Clang documentation though: https://clang.llvm.org/docs/LanguageExtensions.html#gcc-destructive-size-and-gcc-constructive-size , and used directly by a few users: https://github.com/search?type=code&q=__GCC_CONSTRUCTIVE_SIZE (though references in moc_predefs.h can be disregarded as some kind of qmake thing).

---

I will update this PR with the following:

• Use non-interoperable over unstable.
• Use the C++ constants for constructive/destructive size - potentially in addition to the gcc constant names.
• Move the preprocessor table to a different section called non-interoperable constants
• Move the types table to be with the non-interoperable constants table.
• Open a PR against the psABI to document [u]intmax_t sizes/alignments.