Requirements on the target platform C implementation

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 on the platform's C ABI](./representation/c_abi.md)
 - [Optimizations](./optimizations.md)
   - [Optimizing immutable memory](./optimizations/immutable_memory.md) 
+

reference/src/representation/c_abi.md

@@ -0,0 +1,79 @@
+# Layout requirements on the platform's 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
+requirements.
+
+## Integer and floating point requirements
+
+* `CHAR_BITS == 8`
+* `sizeof(_Bool) == 1`
+* `true = 1` and `false = 0`
+* two's complement integers
+
+## 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
+
+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`.
+
+* **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