docs/ARCHITECTURE: mention src/fundamental/ and add more details

1 files changed, 46 insertions, 16 deletions

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 46d1d83d78..aaa3d86267 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -9,8 +9,8 @@ SPDX-License-Identifier: LGPL-2.1-or-later
 
 ## Code Map
 
-This section will attempt to provide a high-level overview of the various
-components of the systemd repository.
+This document provides a high-level overview of the various components of the
+systemd repository.
 
 ## Source Code
 
@@ -21,30 +21,60 @@ names are self-explanatory.
 
 ### Shared Code
 
-You might wonder what kind of common code belongs in `src/shared/` and what
-belongs in `src/basic/`. The split is like this: anything that is used to
-implement the public shared objects we provide (`sd-bus`, `sd-login`,
-`sd-id128`, `nss-systemd`, `nss-mymachines`, `nss-resolve`, `nss-myhostname`,
-`pam_systemd`), must be located in `src/basic` (those objects are not allowed
-to link to `libsystemd-shared.so`). Conversely, anything which is shared
-between multiple components and does not need to be in `src/basic/`, should be
-in `src/shared/`.
+The code that is shared between components is split into a few directories,
+each with a different purpose:
+
+- `src/basic/` and `src/fundamental/` — those directories contain code
+  primitives that are used by all other code. `src/fundamental/` is stricter,
+  because it used for EFI and user-space code, while `src/basic/` is only used
+  for user-space code. The code in `src/fundamental/` cannot depend on any
+  other code in the tree, and `src/basic/` can depend only on itself and
+  `src/fundamental/`. For user-space, a static library is built from this code
+  and linked statically in various places.
+
+- `src/libsystemd/` implements the `libsystemd.so` shared library (also
+  available as static `libsystemd.a`). This code may use anything in
+  `src/basic/` or `src/fundamental/`.
+
+- `src/shared/` provides various utilities and code shared between other
+  components that is exposed as the `libsystemd-shared-<nnn>.so` shared library.
+
+The other subdirectories implement individual components. They may depend only
+on `src/fundamental/` + `src/basic/`, or also on `src/libsystemd/`, or also on
+`src/shared/`.
+
+You might wonder what kind of code belongs where. In general, the rule is that
+code should linked as few times as possible, ideally only once. Thus code that
+is used by "higher-level" components (e.g. our binaries which are linked to
+`libsystemd-shared-<nnn>.so`), would go to a subdirectory specific to that
+component if it is only used there. If the code is to be shared between
+components, it'd go to `src/shared/`. Shared code that that is used by multiple
+components that do not link to `libsystemd-shared-<nnn>.so` may live either in
+`src/libsystemd/`, `src/basic/`, or `src/fundamental/`. Any code that is used
+only for EFI goes under `src/boot/efi/`, and `src/fundamental/` if is shared
+with non-EFI compoenents.
 
 To summarize:
 
+`src/fundamental/`
+- may be used by all code in the tree
+- may not use any code outside of `src/fundamental/`
+
 `src/basic/`
 - may be used by all code in the tree
-- may not use any code outside of `src/basic/`
+- may not use any code outside of `src/fundamental/` and `src/basic/`
 
 `src/libsystemd/`
-- may be used by all code in the tree, except for code in `src/basic/`
-- may not use any code outside of `src/basic/`, `src/libsystemd/`
+- may be used by all code in the tree that links to `libsystem.so`
+- may not use any code outside of `src/fundamental/`, `src/basic/`, and
+  `src/libsystemd/`
 
 `src/shared/`
 - may be used by all code in the tree, except for code in `src/basic/`,
-`src/libsystemd/`, `src/nss-*`, `src/login/pam_systemd.*`, and files under
-`src/journal/` that end up in `libjournal-client.a` convenience library.
-- may not use any code outside of `src/basic/`, `src/libsystemd/`, `src/shared/`
+  `src/libsystemd/`, `src/nss-*`, `src/login/pam_systemd.*`, and files under
+  `src/journal/` that end up in `libjournal-client.a` convenience library.
+- may not use any code outside of `src/fundamental/`, `src/basic/`,
+  `src/libsystemd/`, `src/shared/`
 
 ### PID 1