document our assumptions about symbols provided by the libc

library/core/src/lib.rs

@@ -20,11 +20,19 @@
 // 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).
+//!   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