From 34ad8335aebc20259f6a38d8b626307b33433ad1 Mon Sep 17 00:00:00 2001 From: Sam Elliott Date: Wed, 15 Oct 2025 13:48:12 -0700 Subject: [PATCH 1/2] Note Unstable Macros and Types 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 unstable, I didn't want to put them in the psABI document -- I thought this document would be a better place. --- src/c-api.adoc | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/src/c-api.adoc b/src/c-api.adoc index 7b6c0b9..c880a40 100644 --- a/src/c-api.adoc +++ b/src/c-api.adoc @@ -152,6 +152,31 @@ For example: |`+__riscv_cmodel_large+` |1 |Defined if using `large` code model. |=== +[id=unstable_preprocessor_definitions] +=== Unstable Preprocessor Definitions + +The following preprocessor definitions should be treated as unstable, and not +relied upon by the public interfaces in your code. They may be changed by new +compiler versions, compiler options, or on a per-processor basis. + +.Unstable Preprocessor Definitions +[cols="30,~"] +|=== +|*Name* |*Description* +|`+__GCC_CONSTRUCTIVE_SIZE+` |The maximum recommended size of contiguous memory occupied by two objects accessed with temporal locality by concurrent threads. +|`+__GCC_DESTRUCTIVE_SIZE+` |The minimum recommended offset between two concurrently-accessed objects to avoid additional performance degradation due to contention introduced by the implementation. +|`+INT_FASTN_WIDTH+` |Bit width of an object of type `+int_fastN_t+` +|`+INT_FASTN_MIN+` |Minimum value of an object of type `+int_fastN_t+` +|`+INT_FASTN_MAX+` |Maximum value of an object of type `+int_fastN_t+` +|`+INT_LEASTN_WIDTH+` |Bit width of an object of type `+int_leastN_t+` +|`+INT_LEASTN_MIN+` |Minimum value of an object of type `+int_leastN_t+` +|`+INT_LEASTN_MAX+` |Maximum value of an object of type `+int_leastN_t+` +|`+UINT_FASTN_WIDTH+` |Bit width of an object of type `+uint_fastN_t+` +|`+UINT_FASTN_MAX+` |Maximum value of an object of type `+uint_fastN_t+` +|`+UINT_LEASTN_WIDTH+` |Bit width of an object of type `+uint_leastN_t+` +|`+UINT_LEASTN_MAX+` |Maximum value of an object of type `+uint_leastN_t+` +|=== + === Deprecated Preprocessor Definitions .fn-1: footnote:[Not all compilers provide `-mno-div` and `-mno-fdiv` option.] @@ -170,6 +195,28 @@ For example: |`+__riscv_compressed+` |1 |`C` extension is available. | `+__riscv_c+` |=== +== C Types + +Most C type sizes and alignments are defined by the ABI. + +=== Unstable C Type Sizes and Alignments + +The following type sizes and alignments should be treated as unstable, and not +relied upon by the public interfaces in your code. They may be changed by new +compiler versions, compiler options, or on a per-processor basis. + +.Unstable Type Sizes and Alignments +[cols="30,~"] +|=== +|*Type* |*Description* +|`+int_fastN_t+` |Fastest signed integer types with widths of at least `+N+` bits. +|`+int_leastN_t+` |Smallest signed integer types with widths of at least `+N+` bits. +|`+uint_fastN_t+` |Fastest unsigned integer types with widths of at least `+N+` bits. +|`+uint_leastN_t+` |Smallest unsigned integer types with widths of at least `+N+` bits. +|=== + +The corresponding Macro constants are also unstable (see <>). + == Function Attributes === `+__attribute__((naked))+` From 57dc4cd49dae3bb78a2e6c47e7ad5ecbd251f3e7 Mon Sep 17 00:00:00 2001 From: Sam Elliott Date: Thu, 16 Oct 2025 22:00:37 -0700 Subject: [PATCH 2/2] Address Feedback --- src/c-api.adoc | 64 ++++++++++++++++++++++++-------------------------- 1 file changed, 31 insertions(+), 33 deletions(-) diff --git a/src/c-api.adoc b/src/c-api.adoc index c880a40..cce4d48 100644 --- a/src/c-api.adoc +++ b/src/c-api.adoc @@ -152,31 +152,6 @@ For example: |`+__riscv_cmodel_large+` |1 |Defined if using `large` code model. |=== -[id=unstable_preprocessor_definitions] -=== Unstable Preprocessor Definitions - -The following preprocessor definitions should be treated as unstable, and not -relied upon by the public interfaces in your code. They may be changed by new -compiler versions, compiler options, or on a per-processor basis. - -.Unstable Preprocessor Definitions -[cols="30,~"] -|=== -|*Name* |*Description* -|`+__GCC_CONSTRUCTIVE_SIZE+` |The maximum recommended size of contiguous memory occupied by two objects accessed with temporal locality by concurrent threads. -|`+__GCC_DESTRUCTIVE_SIZE+` |The minimum recommended offset between two concurrently-accessed objects to avoid additional performance degradation due to contention introduced by the implementation. -|`+INT_FASTN_WIDTH+` |Bit width of an object of type `+int_fastN_t+` -|`+INT_FASTN_MIN+` |Minimum value of an object of type `+int_fastN_t+` -|`+INT_FASTN_MAX+` |Maximum value of an object of type `+int_fastN_t+` -|`+INT_LEASTN_WIDTH+` |Bit width of an object of type `+int_leastN_t+` -|`+INT_LEASTN_MIN+` |Minimum value of an object of type `+int_leastN_t+` -|`+INT_LEASTN_MAX+` |Maximum value of an object of type `+int_leastN_t+` -|`+UINT_FASTN_WIDTH+` |Bit width of an object of type `+uint_fastN_t+` -|`+UINT_FASTN_MAX+` |Maximum value of an object of type `+uint_fastN_t+` -|`+UINT_LEASTN_WIDTH+` |Bit width of an object of type `+uint_leastN_t+` -|`+UINT_LEASTN_MAX+` |Maximum value of an object of type `+uint_leastN_t+` -|=== - === Deprecated Preprocessor Definitions .fn-1: footnote:[Not all compilers provide `-mno-div` and `-mno-fdiv` option.] @@ -195,17 +170,40 @@ compiler versions, compiler options, or on a per-processor basis. |`+__riscv_compressed+` |1 |`C` extension is available. | `+__riscv_c+` |=== -== C Types +== Non-Interoperable Types and Definitions + +There are several implementation-defined C/C++ types and constants that are +usually implemented in RISC-V implementations. The types and constants in this +section should not be relied upon by public interfaces in your code. Their +definitions may be changed by new compiler versions, compiler options, or on a +per-processor basis. -Most C type sizes and alignments are defined by the ABI. +[id=non_interoperable_constants] +.Non-Interoperable C/C++ Constants +[cols="30,~"] +|=== +|*Name* |*Description* +|`+std::hardware_constructive_interference_size+` |The maximum recommended size of contiguous memory occupied by two objects accessed with temporal locality by concurrent threads. +|`+std::hardware_destructive_interference_size+` |The minimum recommended offset between two concurrently-accessed objects to avoid additional performance degradation due to contention introduced by the implementation. +|`+INT_FASTN_WIDTH+` |Bit width of an object of type `+int_fastN_t+` +|`+INT_FASTN_MIN+` |Minimum value of an object of type `+int_fastN_t+` +|`+INT_FASTN_MAX+` |Maximum value of an object of type `+int_fastN_t+` +|`+INT_LEASTN_WIDTH+` |Bit width of an object of type `+int_leastN_t+` +|`+INT_LEASTN_MIN+` |Minimum value of an object of type `+int_leastN_t+` +|`+INT_LEASTN_MAX+` |Maximum value of an object of type `+int_leastN_t+` +|`+UINT_FASTN_WIDTH+` |Bit width of an object of type `+uint_fastN_t+` +|`+UINT_FASTN_MAX+` |Maximum value of an object of type `+uint_fastN_t+` +|`+UINT_LEASTN_WIDTH+` |Bit width of an object of type `+uint_leastN_t+` +|`+UINT_LEASTN_MAX+` |Maximum value of an object of type `+uint_leastN_t+` +|=== -=== Unstable C Type Sizes and Alignments +=== Non-Interoperable Types -The following type sizes and alignments should be treated as unstable, and not -relied upon by the public interfaces in your code. They may be changed by new -compiler versions, compiler options, or on a per-processor basis. +Most C type sizes and alignments are defined by the ABI. The following types +should not be relied upon by public interfaces in your code. Their sizes and +alignments are not fixed. -.Unstable Type Sizes and Alignments +.Non-Interoperable Types [cols="30,~"] |=== |*Type* |*Description* @@ -215,7 +213,7 @@ compiler versions, compiler options, or on a per-processor basis. |`+uint_leastN_t+` |Smallest unsigned integer types with widths of at least `+N+` bits. |=== -The corresponding Macro constants are also unstable (see <>). +The corresponding constants are also unstable (see <>). == Function Attributes