diff --git a/reference/src/SUMMARY.md b/reference/src/SUMMARY.md index 45a8fea8..0a8ca777 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 on the platform's 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..843fd880 --- /dev/null +++ b/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