From dfee1ba4c466c32d1817631e675ed458a18e088c Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Thu, 3 Aug 2023 14:05:18 +0200 Subject: [PATCH 1/2] document our assumptions about symbols provided by the libc --- library/core/src/lib.rs | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs index 37216d6a7210b..d8531c70a8a7b 100644 --- a/library/core/src/lib.rs +++ b/library/core/src/lib.rs @@ -20,11 +20,15 @@ // FIXME: Fill me in with more detail when the interface settles //! This library is built on the assumption of a few existing symbols: //! -//! * `memcpy`, `memcmp`, `memset`, `strlen` - These are core memory routines which are -//! often generated by LLVM. Additionally, this library can make explicit -//! calls to these functions. Their signatures are the same as found in C. -//! These functions are often provided by the system libc, but can also be -//! provided by the [compiler-builtins crate](https://crates.io/crates/compiler_builtins). +//! * `memcpy`, `memmove`, `memset`, `memcmp`, `bcmp`, `strlen` - These are core memory routines +//! which are generated by Rust codegen backends. Additionally, this library can make explicit +//! calls to `strlen`. Their signatures are the same as found in C, but there are extra +//! assumptions about their semantics: For `memcpy`, `memmove`, `memset`, `memcmp`, and `bcmp`, if +//! the `n` parameter is 0, the function is assumed to not be UB. Furthermore, for `memcpy`, if +//! source and target pointer are equal, the function is assumed to not be UB. +//! (Note that these are [standard assumptions](https://reviews.llvm.org/D86993) among compilers.) +//! These functions are often provided by the system libc, but can also be provided by the +//! [compiler-builtins crate](https://crates.io/crates/compiler_builtins). //! //! * `rust_begin_panic` - This function takes four arguments, a //! `fmt::Arguments`, a `&'static str`, and two `u32`'s. These four arguments From fb4ac63415fbf6635a59a39c078d766ba8fc4b5c Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Tue, 15 Aug 2023 13:39:46 +0200 Subject: [PATCH 2/2] clarify that these assumtpions are for us, not all Rust code --- library/core/src/lib.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs index d8531c70a8a7b..c2602fa19eb4f 100644 --- a/library/core/src/lib.rs +++ b/library/core/src/lib.rs @@ -29,6 +29,10 @@ //! (Note that these are [standard assumptions](https://reviews.llvm.org/D86993) among compilers.) //! These functions are often provided by the system libc, but can also be provided by the //! [compiler-builtins crate](https://crates.io/crates/compiler_builtins). +//! Note that the library does not guarantee that it will always make these assumptions, so Rust +//! user code directly calling the C functions should follow the C specification! The advice for +//! Rust user code is to call the functions provided by this library instead (such as +//! `ptr::copy`). //! //! * `rust_begin_panic` - This function takes four arguments, a //! `fmt::Arguments`, a `&'static str`, and two `u32`'s. These four arguments