From 905d23b65c07a1da4452f9a20b1891fc46533fb7 Mon Sep 17 00:00:00 2001
From: Christiaan Dirkx <christiaan@dirkx.email>
Date: Wed, 24 Feb 2021 19:16:24 +0100
Subject: [PATCH 1/2] Move `std::sys_common::alloc` to `std::sys::common`

---
 library/std/src/{sys_common => sys/common}/alloc.rs | 0
 library/std/src/sys/common/mod.rs                   | 1 +
 library/std/src/sys/mod.rs                          | 2 ++
 library/std/src/sys/unix/alloc.rs                   | 2 +-
 library/std/src/sys/windows/alloc.rs                | 2 +-
 library/std/src/sys_common/mod.rs                   | 1 -
 6 files changed, 5 insertions(+), 3 deletions(-)
 rename library/std/src/{sys_common => sys/common}/alloc.rs (100%)
 create mode 100644 library/std/src/sys/common/mod.rs

diff --git a/library/std/src/sys_common/alloc.rs b/library/std/src/sys/common/alloc.rs
similarity index 100%
rename from library/std/src/sys_common/alloc.rs
rename to library/std/src/sys/common/alloc.rs
diff --git a/library/std/src/sys/common/mod.rs b/library/std/src/sys/common/mod.rs
new file mode 100644
index 0000000000000..920965d5944d7
--- /dev/null
+++ b/library/std/src/sys/common/mod.rs
@@ -0,0 +1 @@
+pub mod alloc;
diff --git a/library/std/src/sys/mod.rs b/library/std/src/sys/mod.rs
index 9b359392cf0cd..50c2660ebcf1f 100644
--- a/library/std/src/sys/mod.rs
+++ b/library/std/src/sys/mod.rs
@@ -22,6 +22,8 @@
 
 #![allow(missing_debug_implementations)]
 
+mod common;
+
 cfg_if::cfg_if! {
     if #[cfg(target_os = "vxworks")] {
         mod vxworks;
diff --git a/library/std/src/sys/unix/alloc.rs b/library/std/src/sys/unix/alloc.rs
index 964abe8b8c9ea..1b71905aa09b7 100644
--- a/library/std/src/sys/unix/alloc.rs
+++ b/library/std/src/sys/unix/alloc.rs
@@ -1,6 +1,6 @@
 use crate::alloc::{GlobalAlloc, Layout, System};
 use crate::ptr;
-use crate::sys_common::alloc::{realloc_fallback, MIN_ALIGN};
+use crate::sys::common::alloc::{realloc_fallback, MIN_ALIGN};
 
 #[stable(feature = "alloc_system_type", since = "1.28.0")]
 unsafe impl GlobalAlloc for System {
diff --git a/library/std/src/sys/windows/alloc.rs b/library/std/src/sys/windows/alloc.rs
index af93cd7a3e27d..2fe71f9f28d5c 100644
--- a/library/std/src/sys/windows/alloc.rs
+++ b/library/std/src/sys/windows/alloc.rs
@@ -5,7 +5,7 @@ use crate::ffi::c_void;
 use crate::ptr;
 use crate::sync::atomic::{AtomicPtr, Ordering};
 use crate::sys::c;
-use crate::sys_common::alloc::{realloc_fallback, MIN_ALIGN};
+use crate::sys::common::alloc::{realloc_fallback, MIN_ALIGN};
 
 #[cfg(test)]
 mod tests;
diff --git a/library/std/src/sys_common/mod.rs b/library/std/src/sys_common/mod.rs
index 660f0e0df9732..9700d1f6daa61 100644
--- a/library/std/src/sys_common/mod.rs
+++ b/library/std/src/sys_common/mod.rs
@@ -46,7 +46,6 @@ macro_rules! rtunwrap {
     };
 }
 
-pub mod alloc;
 pub mod at_exit_imp;
 pub mod backtrace;
 pub mod bytestring;

From cac0dd63b3514569ce79480b0cdf92335c5cf9f4 Mon Sep 17 00:00:00 2001
From: Christiaan Dirkx <christiaan@dirkx.email>
Date: Wed, 14 Apr 2021 14:03:00 +0200
Subject: [PATCH 2/2] Update documentation

---
 library/std/src/sys/common/alloc.rs |  2 --
 library/std/src/sys/common/mod.rs   | 12 ++++++++++++
 library/std/src/sys_common/mod.rs   |  8 +++++---
 3 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/library/std/src/sys/common/alloc.rs b/library/std/src/sys/common/alloc.rs
index 6c1bc0d839ad3..2a54e99020e38 100644
--- a/library/std/src/sys/common/alloc.rs
+++ b/library/std/src/sys/common/alloc.rs
@@ -1,5 +1,3 @@
-#![allow(dead_code)]
-
 use crate::alloc::{GlobalAlloc, Layout, System};
 use crate::cmp;
 use crate::ptr;
diff --git a/library/std/src/sys/common/mod.rs b/library/std/src/sys/common/mod.rs
index 920965d5944d7..ff64d2aa82515 100644
--- a/library/std/src/sys/common/mod.rs
+++ b/library/std/src/sys/common/mod.rs
@@ -1 +1,13 @@
+// This module contains code that is shared between all platforms, mostly utility or fallback code.
+// This explicitly does not include code that is shared between only a few platforms,
+// such as when reusing an implementation from `unix` or `unsupported`.
+// In those cases the desired code should be included directly using the #[path] attribute,
+// not moved to this module.
+//
+// Currently `sys_common` contains a lot of code that should live in this module,
+// ideally `sys_common` would only contain platform-independent abstractions on top of `sys`.
+// Progress on this is tracked in #84187.
+
+#![allow(dead_code)]
+
 pub mod alloc;
diff --git a/library/std/src/sys_common/mod.rs b/library/std/src/sys_common/mod.rs
index 9700d1f6daa61..23a3a0e907dcf 100644
--- a/library/std/src/sys_common/mod.rs
+++ b/library/std/src/sys_common/mod.rs
@@ -8,9 +8,11 @@
 //! rest of `std` is complex, with dependencies going in all
 //! directions: `std` depending on `sys_common`, `sys_common`
 //! depending on `sys`, and `sys` depending on `sys_common` and `std`.
-//! Ideally `sys_common` would be split into two and the dependencies
-//! between them all would form a dag, facilitating the extraction of
-//! `std::sys` from the standard library.
+//! This is because `sys_common` not only contains platform-independent code,
+//! but also code that is shared between the different platforms in `sys`.
+//! Ideally all that shared code should be moved to `sys::common`,
+//! and the dependencies between `std`, `sys_common` and `sys` all would form a dag.
+//! Progress on this is tracked in #84187.
 
 #![allow(missing_docs)]
 #![allow(missing_debug_implementations)]