From 36fd33ef5f96964bf91222aaccc8fe29769e5bb6 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Sun, 11 Nov 2018 14:28:56 +0100 Subject: [PATCH 01/14] requirements on the platform C implementation --- reference/src/SUMMARY.md | 2 ++ reference/src/representation/c_abi.md | 31 +++++++++++++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 reference/src/representation/c_abi.md diff --git a/reference/src/SUMMARY.md b/reference/src/SUMMARY.md index 45a8fea8..45aa43f0 100644 --- a/reference/src/SUMMARY.md +++ b/reference/src/SUMMARY.md @@ -15,5 +15,7 @@ - [Uninitialized memory](./active_discussion/uninitialized_memory.md) - [Data representation](./representation.md) - [Structs and tuples](./representation/structs-and-tuples.md) + - [Layout requirements of the C ABI](./representation/c_abi.md) - [Optimizations](./optimizations.md) - [Optimizing immutable memory](./optimizations/immutable_memory.md) + diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md new file mode 100644 index 00000000..3b68362b --- /dev/null +++ b/reference/src/representation/c_abi.md @@ -0,0 +1,31 @@ +# Layout requirements of the C ABI + +**Disclaimer:** This chapter is a minimal summary of issue [#44] about Rust's +current layout requirements of the platforms' C ABI. + +These requirements apply to all C ABIs that Rust programs interface with, e.g., +via `extern "C"`. That is, for Rust to be able to target a platform, this +platform does not have to provide a C implementation, but then all Rust programs +attempting to interface with one are illegal. + +The platform's C implementation is required to conform to the [latest version of +the C standard]. The following are extra requirements that Rust imposes on top +of the latest version of the C standard, e.g., on implementation-defined or +unspecified behavior: + +* `CHAR_BITS == 8` +* `sizeof(Bool_) == 1` +* two's complement integers +* have, at least, one pointer value that is never dereferenceable + +## Unresolved questions + +* Shall Rust require that the C's platform pointer size must be at lest, e.g., + 16-bits wide? +* Does the pointer with representation `intptr_t(0)` have to never be + dereferenceable? +* Are `float` and `double` optional? What should we require of these types + layout-wise? See [#9]. +* Is atomics support optional? + +[latest_c_std]: http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf From 7fc7f856ef2ee9bdb61d3a15a38c7ed5e94d1ab6 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Sun, 11 Nov 2018 16:16:53 +0100 Subject: [PATCH 02/14] add representation of bool true/false --- reference/src/representation/c_abi.md | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 3b68362b..db4c5691 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -15,6 +15,7 @@ unspecified behavior: * `CHAR_BITS == 8` * `sizeof(Bool_) == 1` +* `true = 1` and `false = 0` * two's complement integers * have, at least, one pointer value that is never dereferenceable From df2e23632d1ad27875052a8177e19c044019eb1d Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Sun, 11 Nov 2018 16:18:30 +0100 Subject: [PATCH 03/14] amend float unresolved question --- reference/src/representation/c_abi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index db4c5691..5b8a45b9 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -26,7 +26,7 @@ unspecified behavior: * Does the pointer with representation `intptr_t(0)` have to never be dereferenceable? * Are `float` and `double` optional? What should we require of these types - layout-wise? See [#9]. + (IEEE754:2018 compatibility?)? See [#9]. * Is atomics support optional? [latest_c_std]: http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf From 8e009a187bf22d08a83854639b50ccc1e48be093 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Sun, 11 Nov 2018 19:35:54 +0100 Subject: [PATCH 04/14] fix typo: _Bool instead of Bool_ --- reference/src/representation/c_abi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 5b8a45b9..dee5e4dc 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -14,7 +14,7 @@ of the latest version of the C standard, e.g., on implementation-defined or unspecified behavior: * `CHAR_BITS == 8` -* `sizeof(Bool_) == 1` +* `sizeof(_Bool) == 1` * `true = 1` and `false = 0` * two's complement integers * have, at least, one pointer value that is never dereferenceable From 07f7021d1e42fa1cfeff7247cd64100686010b08 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Sun, 11 Nov 2018 19:58:42 +0100 Subject: [PATCH 05/14] remove non-dereferenceable pointer requirement --- reference/src/representation/c_abi.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index dee5e4dc..2a344008 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -17,7 +17,6 @@ unspecified behavior: * `sizeof(_Bool) == 1` * `true = 1` and `false = 0` * two's complement integers -* have, at least, one pointer value that is never dereferenceable ## Unresolved questions @@ -28,5 +27,14 @@ unspecified behavior: * Are `float` and `double` optional? What should we require of these types (IEEE754:2018 compatibility?)? See [#9]. * Is atomics support optional? + + * Once we start discussing validity, the bit pattern representing the `None` + value of `Option<&T>` has to be specified. In particular, we want to require + that this bitpattern matches that of a C pointer for which `ptr == NULL` + returns `true`, to ensure that C pointers passed to Rust via FFI that are + null also result in null pointers in Rust, `Option<&T>::None`, etc. + + If we decide that this null bit-pattern can only be `0x0`, then we'd have to + add this requirement to this document in the future. [latest_c_std]: http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf From aadac80d0637cbcce55c1edd19c5b84e050864e8 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 11:31:35 +0100 Subject: [PATCH 06/14] differentiate platforms w/o NULL --- reference/src/representation/c_abi.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 2a344008..9fc15bb0 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -20,10 +20,20 @@ unspecified behavior: ## Unresolved questions +Please open an issue to discuss any of these as required. I'll update this +document to link to the appropriate issues as they are opened. + * Shall Rust require that the C's platform pointer size must be at lest, e.g., 16-bits wide? * Does the pointer with representation `intptr_t(0)` have to never be - dereferenceable? + dereferenceable? @ralfj mentioned that there are two different platform that + we have to consider here: + * platforms that do not have a `NULL` pointer (e.g. Linux kernel), where all + addresses are available (is this allowed by the C standard ?). Is this + allowed by the C standard? + * platforms that do have a `NULL` pointer, in which case we might only want + to support those platforms where it's run-time address is `0x0`, instead + of a platform specific one. * Are `float` and `double` optional? What should we require of these types (IEEE754:2018 compatibility?)? See [#9]. * Is atomics support optional? From 2e0d82f081e2a622e262779d935b2a65fc6d52da Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 12:38:00 +0100 Subject: [PATCH 07/14] clean up unresolved questions --- reference/src/representation/c_abi.md | 71 +++++++++++++++++---------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 9fc15bb0..d39dec48 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -20,31 +20,50 @@ unspecified behavior: ## Unresolved questions -Please open an issue to discuss any of these as required. I'll update this -document to link to the appropriate issues as they are opened. - -* Shall Rust require that the C's platform pointer size must be at lest, e.g., - 16-bits wide? -* Does the pointer with representation `intptr_t(0)` have to never be - dereferenceable? @ralfj mentioned that there are two different platform that - we have to consider here: - * platforms that do not have a `NULL` pointer (e.g. Linux kernel), where all - addresses are available (is this allowed by the C standard ?). Is this - allowed by the C standard? - * platforms that do have a `NULL` pointer, in which case we might only want - to support those platforms where it's run-time address is `0x0`, instead - of a platform specific one. -* Are `float` and `double` optional? What should we require of these types - (IEEE754:2018 compatibility?)? See [#9]. -* Is atomics support optional? - - * Once we start discussing validity, the bit pattern representing the `None` - value of `Option<&T>` has to be specified. In particular, we want to require - that this bitpattern matches that of a C pointer for which `ptr == NULL` - returns `true`, to ensure that C pointers passed to Rust via FFI that are - null also result in null pointers in Rust, `Option<&T>::None`, etc. - - If we decide that this null bit-pattern can only be `0x0`, then we'd have to - add this requirement to this document in the future. +The unresolved questions that don't contain a link to an issue have no issue +open yet. This document shall be updated as issues are resolved and new issues +are opened: + +* **minimum platform pointer size**: should Rust require that the C's platform + pointer size must be at lest, e.g., 16-bits wide? + +* **float types** (32 and 64-bit wide only for now): see [#9] + + * Are these optional? + + * Should we require anything about them beyond what the C standard requires? + + * These probably need to be IEEE754:2018 compliant and we should specify their + binary representation. + + * Do we need to specify anything else on top of IEEE754:2018, e.g., with + respect to implementation-defined behavior? + +* **atomics**: + + * Are these optional? + + * Should we require anything about them beyond what the C standard requires? + +* **`NULL` pointer bitpattern**: + + * Does the C standard allow platforms without a run-time `NULL` representation? + + * Some platforms do not have any pointer value that compares equal to `NULL`. + Should we support these platforms? For example, an OS kernel like Linux that + wants to use the `0x0` address. Rust is used for these platforms already. + + * Some platforms have pointer values that compare equal to `NULL` but whose + bit representation is not `0x0`. Should we support these platforms? + * That is, should we only support C platforms where the only pointer + representation that compares equal to `NULL` is `(void*)intptr_t(0)` ? + + * This interacts which the bit-patterns: + + * for which `&T` and `&mut T` have niches, and therefore `Option<&T>` is + `None` + * `<*[mut,const] T>::is_null(self)` returns `true` - note that `NonNull` + does not convey any information about the exact representation of its + niche, that is, it is different from `NonZero`. [latest_c_std]: http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf From fcfb9c8bef5144eede6928f555a2b66573b76f62 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 12:49:25 +0100 Subject: [PATCH 08/14] cleanup requirements --- reference/src/representation/c_abi.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index d39dec48..ec5ecb82 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -3,14 +3,19 @@ **Disclaimer:** This chapter is a minimal summary of issue [#44] about Rust's current layout requirements of the platforms' C ABI. -These requirements apply to all C ABIs that Rust programs interface with, e.g., -via `extern "C"`. That is, for Rust to be able to target a platform, this -platform does not have to provide a C implementation, but then all Rust programs -attempting to interface with one are illegal. - -The platform's C implementation is required to conform to the [latest version of -the C standard]. The following are extra requirements that Rust imposes on top -of the latest version of the C standard, e.g., on implementation-defined or +Rust programs can target platforms that do not have a C implementation. However, +when targeting these platforms, attempting to interface with C, e.g., via +`extern "C"` is illegal, since there is no C ABI to interface with. + +Interfacing with C is allowed in platforms that have a C implementation that +satisfies all requirements specified in this document. + +## Requirements on the C implementation + +If the platform has a C implementation that can be interfaced with via C FFI, +this implementation is required to conform to the [latest version of the C +standard]. The following are extra requirements that Rust imposes on top of the +latest version of the C standard, e.g., on implementation-defined and/or unspecified behavior: * `CHAR_BITS == 8` From 612f003549887a4d8b005638b0889a7d00bb4afd Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 22:42:47 +0100 Subject: [PATCH 09/14] add unresolved questions about targets without conforming C implementations --- reference/src/representation/c_abi.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index ec5ecb82..6598a08b 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -71,4 +71,12 @@ are opened: does not convey any information about the exact representation of its niche, that is, it is different from `NonZero`. +* **targets "without C"**: + + * What should we do about targets whose C implementation is not standard + conforming? Do we require full standard conformance? Or only conformance of + some specific aspects that are required for FFI ? + + * What should we do about targets that do not have a C implementation at all? + [latest_c_std]: http://www.open-std.org/jtc1/sc22/wg14/www/abq/c17_updated_proposed_fdis.pdf From f89431da5cdaa551113df6555241b10a6d760919 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 22:45:14 +0100 Subject: [PATCH 10/14] assume that the platform has a C implementation --- reference/src/representation/c_abi.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 6598a08b..2ced9834 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -12,11 +12,11 @@ satisfies all requirements specified in this document. ## Requirements on the C implementation -If the platform has a C implementation that can be interfaced with via C FFI, -this implementation is required to conform to the [latest version of the C -standard]. The following are extra requirements that Rust imposes on top of the -latest version of the C standard, e.g., on implementation-defined and/or -unspecified behavior: +These requirement assume that the platform has a C implementation that can be +interfaced with. This implementation is required to conform to the [latest +version of the C standard]. The following are extra requirements that Rust +imposes on top of the latest version of the C standard, e.g., on +implementation-defined and/or unspecified behavior: * `CHAR_BITS == 8` * `sizeof(_Bool) == 1` From 25097ac72941d92db598764de8afefd706886297 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 23:10:33 +0100 Subject: [PATCH 11/14] clarify the behavior if the C implementation does not satisfy our requirements --- reference/src/representation/c_abi.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 2ced9834..9e9185fc 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -23,6 +23,9 @@ implementation-defined and/or unspecified behavior: * `true = 1` and `false = 0` * two's complement integers +If the C implementation does not satisfy these requirements, the behavior is +undefined. + ## Unresolved questions The unresolved questions that don't contain a link to an issue have no issue From 36d3fb3f36dd4388a8a3b47453697cb1b4bacf95 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 23:25:47 +0100 Subject: [PATCH 12/14] reword this all --- reference/src/representation/c_abi.md | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 9e9185fc..7d7f347e 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -1,30 +1,24 @@ # Layout requirements of the C ABI -**Disclaimer:** This chapter is a minimal summary of issue [#44] about Rust's +**Disclaimer:** This chapter summarizes the current consensus about Rust's current layout requirements of the platforms' C ABI. -Rust programs can target platforms that do not have a C implementation. However, -when targeting these platforms, attempting to interface with C, e.g., via -`extern "C"` is illegal, since there is no C ABI to interface with. - -Interfacing with C is allowed in platforms that have a C implementation that -satisfies all requirements specified in this document. - -## Requirements on the C implementation - These requirement assume that the platform has a C implementation that can be -interfaced with. This implementation is required to conform to the [latest -version of the C standard]. The following are extra requirements that Rust -imposes on top of the latest version of the C standard, e.g., on -implementation-defined and/or unspecified behavior: +interfaced with. This C implementation is required to satisfy the following +requirements. + +## Integer and floating point requirements * `CHAR_BITS == 8` * `sizeof(_Bool) == 1` * `true = 1` and `false = 0` * two's complement integers -If the C implementation does not satisfy these requirements, the behavior is -undefined. +## Layout of structs + +See the [C-compatible layout ("repr C")][c_struct] section. + +[c_struct]: https://github.com/rust-rfcs/unsafe-code-guidelines/blob/master/reference/src/representation/structs-and-tuples.md#c-compatible-layout-repr-c ## Unresolved questions From c508026e289d476c213ccc79a878e4ffda570699 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 23:27:48 +0100 Subject: [PATCH 13/14] typos --- reference/src/representation/c_abi.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/reference/src/representation/c_abi.md b/reference/src/representation/c_abi.md index 7d7f347e..843fd880 100644 --- a/reference/src/representation/c_abi.md +++ b/reference/src/representation/c_abi.md @@ -1,7 +1,7 @@ -# Layout requirements of the C ABI +# Layout requirements on the platform's C ABI -**Disclaimer:** This chapter summarizes the current consensus about Rust's -current layout requirements of the platforms' C ABI. +**Disclaimer:** This chapter summarizes the consensus about Rust's layout +requirements on the platforms' C ABI. These requirement assume that the platform has a C implementation that can be interfaced with. This C implementation is required to satisfy the following From e9dbb11410902e81b2b439883290233038b351b3 Mon Sep 17 00:00:00 2001 From: gnzlbg Date: Mon, 12 Nov 2018 23:29:36 +0100 Subject: [PATCH 14/14] fix section name in summary --- reference/src/SUMMARY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/src/SUMMARY.md b/reference/src/SUMMARY.md index 45aa43f0..0a8ca777 100644 --- a/reference/src/SUMMARY.md +++ b/reference/src/SUMMARY.md @@ -15,7 +15,7 @@ - [Uninitialized memory](./active_discussion/uninitialized_memory.md) - [Data representation](./representation.md) - [Structs and tuples](./representation/structs-and-tuples.md) - - [Layout requirements of the C ABI](./representation/c_abi.md) + - [Layout requirements on the platform's C ABI](./representation/c_abi.md) - [Optimizations](./optimizations.md) - [Optimizing immutable memory](./optimizations/immutable_memory.md)