From 6ddb0fb9dec340db809ddc826b4866e314e07d70 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Sat, 13 Jun 2026 16:13:32 +0000 Subject: [PATCH] 0483 nwfs: document NSS namespace bottom-up dependency order --- AI.md | 31 ++++----- doc/NSS_NAMESPACE_AUDIT.md | 69 +++++++++++++++++++ ...wfs_nss_namespace_import_layout_test.sh.in | 10 +++ 3 files changed, 94 insertions(+), 16 deletions(-) diff --git a/AI.md b/AI.md index 52f8e05..f3be3cc 100644 --- a/AI.md +++ b/AI.md @@ -47,7 +47,7 @@ unfinished work out of `TODO.md` merely because its architecture is documented. Latest patch marker expected in an up-to-date bundle: -- `0482 nwfs: drop artificial namespace model` +- `0483 nwfs: document NSS namespace bottom-up dependency order` When a later chat receives a new `mars-nwe-master` bundle, compare `git log -1` with this marker. If the uploaded bundle already contains this commit subject, @@ -67,24 +67,23 @@ The active line is expected to include: Last generated patch: -- `0482 nwfs: drop artificial namespace model` +- `0483 nwfs: document NSS namespace bottom-up dependency order` Purpose of that patch: -- Remove the artificial `nameSpaceModel` layer and its CTest because it is not Novell/NSS code and does not prove the namespace import. -- Move `lsaPrivate.h` out of `src/nwfs` into `include/nwfs` like the other NWFS headers. -- Keep legacy namespace reply helpers in `src/namspace.c` until the real NSS dependency chain is imported bottom-up. -- Correct the initial DOS namespace import by removing the temporary reduced - headers and `nssNamespaceCompat.c` compile shim. -- Move the imported DOS namespace header to `include/nwfs/` and import only the - required NSS headers flat as `include/nwfs/.h`; use `include/core` for - headers already owned by core instead of duplicating them. -- Keep `src/nwfs/dosNSpace.c` as the unwrapped NSS source, but do not compile it - into libnwfs until the real bottom-up dependencies (`nameSpace.c`, beast/admin - volume/common-layer pieces and any lower libraries they require) are imported. -- Add `nwfs.nss.namespace-import-layout` so future patches cannot accidentally - reintroduce local namespace shims or build DOS before its real NSS dependency - chain exists. +- Record the bottom-up dependency order for the real NSS namespace import. +- Keep `dosNSpace.c` imported but not built until `nameSpace.c` and its real + beast/admin-volume/runtime dependencies are present. +- Identify the next code work as the smallest real NSS runtime base below + `comnBeasts.h`: `latch.h`, `xCache.h`, FSM/scheduler/cache headers and their + source owners, while reusing existing `include/core` headers instead of + duplicating them under `include/nwfs`. +- Preserve the `_ADMIN` volume policy for the later admin-volume import: + `SYS` is volume ID `0`, `_ADMIN` is volume ID `1`, and normal volumes start + at `2`; `_ADMIN` may be built before NCP exposure but must remain hidden until + the runtime path is ready. +- Extend the namespace import-layout test so it fails if future patches skip the + documented runtime/latch/cache/beast/admin-volume order or reintroduce shims. Directory/NDS work order before any FLAIM storage conversion: diff --git a/doc/NSS_NAMESPACE_AUDIT.md b/doc/NSS_NAMESPACE_AUDIT.md index 7520ca6..ae4988d 100644 --- a/doc/NSS_NAMESPACE_AUDIT.md +++ b/doc/NSS_NAMESPACE_AUDIT.md @@ -133,6 +133,75 @@ public_core/comn/authsys/* That code references bindery/auth/common-layer internals and should become a future `libnwbind` or `libnwauth` block, not a core namespace import. +## Bottom-up namespace dependency order + +The namespace import is now intentionally ordered from the lowest reusable NSS +state upward. Do not make `dosNSpace.c` compile by adding local shim functions +or reduced replacement headers. If an imported file needs another NSS symbol, +find the source/header that owns that symbol, check whether the corresponding +primitive already exists in `include/core`, and import the missing layer first. + +Current dependency walk from the imported DOS namespace source: + +```text +dosNSpace.c + -> DOSNS_Startup() + -> COMN_RegisterNameSpace() + -> public_core/comn/namespace/nameSpace.c + -> comnBeastClass.h / comnBeasts.h / adminVolume.h / pssStartup.h + -> latch.h + xCache.h + NSS MPK/OS abstraction headers +``` + +`comnBeasts.h` is the first blocker, not the DOS namespace code itself. It +includes `latch.h` and `xCache.h`; `xCache.h` then pulls the scheduler/FSM/cache +header family (`alarm.h`, `control.h`, `fsm.h`, `asyncio.h`), and `latch.h` pulls +`pssmpk.h`, `pssDebug.h`, `fsm.h` and `parse.h`. These are NSS runtime +abstractions, so the next import must start below beast/namespace with the +smallest real buildable support layer rather than with `nameSpace.c`. + +Core-owned headers must not be duplicated under `include/nwfs`. The following +are already supplied by the existing core layer and should be found through the +`mars_nwe::core` dependency or the explicit core include path: + +```text +include/core/bit.h +include/core/guid.h +include/core/omni.h +include/core/que.h +include/core/utc.h +include/core/xError.h +include/core/xUnicode.h +include/core/zOmni.h +``` + +Headers that are genuinely NSS/NWFS-specific are imported flat as +`include/nwfs/
.h`; do not keep them under `include/nwfs/nss/...`, and do +not add private copies under `src/nwfs/`. + +The planned code order is therefore: + +1. `nwfs-nss-runtime-base`: the smallest real subset of NSS MPK/scheduler/FSM + headers and sources needed by `latch.h`/`xCache.h`, with Linux-kernel-only or + NDPS/DDS-only includes removed or guarded only when the filesystem path does + not use them. +2. `nwfs-latch-cache-base`: direct imports for `latch`/cache types required by + beast structures. +3. `nwfs-beast-base`: beast class and root-beast structure support. +4. `nwfs-admin-volume`: build the `_ADMIN` virtual volume model, but do not + expose it through NCP until the runtime path is ready. +5. `nwfs-namespace-registry`: `nameSpace.c` and registration state. +6. DOS namespace activation: build `dosNSpace.c` only after the registry and its + real dependencies are present. + +The `_ADMIN` volume ID policy for that later import is fixed even while the +volume is hidden from NCP: + +```text +SYS => volume ID 0 +_ADMIN => volume ID 1 +other volumes start at ID 2 +``` + ## `_ADMIN` virtual volume NSS also carries the `_ADMIN` management volume model. It is storage/filesystem diff --git a/tests/nwfs/nwfs_nss_namespace_import_layout_test.sh.in b/tests/nwfs/nwfs_nss_namespace_import_layout_test.sh.in index 0e91d1c..208322d 100644 --- a/tests/nwfs/nwfs_nss_namespace_import_layout_test.sh.in +++ b/tests/nwfs/nwfs_nss_namespace_import_layout_test.sh.in @@ -53,4 +53,14 @@ fi grep -q 'DOSNS_Startup' "$SRC/src/nwfs/dosNSpace.c" || fail "DOS namespace source is not the NSS implementation" grep -q 'COMN_RegisterNameSpace' "$SRC/src/nwfs/dosNSpace.c" || fail "DOS namespace source no longer depends on the real NSS namespace registry" +DOC="$SRC/doc/NSS_NAMESPACE_AUDIT.md" +test -f "$DOC" || fail "missing NSS namespace audit document" +grep -q 'dosNSpace.c' "$DOC" || fail "dependency order must start from imported DOS namespace source" +grep -q 'nameSpace.c' "$DOC" || fail "dependency order must record the namespace registry source" +grep -q 'comnBeasts.h' "$DOC" || fail "dependency order must record the beast base header" +grep -q 'latch.h' "$DOC" || fail "dependency order must record the latch dependency" +grep -q 'xCache.h' "$DOC" || fail "dependency order must record the cache dependency" +grep -q 'SYS => volume ID 0' "$DOC" || fail "audit must reserve SYS as volume ID 0" +grep -q '_ADMIN => volume ID 1' "$DOC" || fail "audit must reserve _ADMIN as volume ID 1" + exit 0