From 8556989bd6dec0acb2f93a02feeff385ae04bfc9 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Sun, 14 Jun 2026 09:48:34 +0000 Subject: [PATCH] 0527 doc: define NSS userspace adaptation boundary --- doc/NSS_USERSPACE_ADAPTATION.md | 79 +++++++++++++++++++++++++++++++++ doc/librarys/README.md | 6 +++ doc/librarys/nwfs/README.md | 10 +++++ 3 files changed, 95 insertions(+) create mode 100644 doc/NSS_USERSPACE_ADAPTATION.md diff --git a/doc/NSS_USERSPACE_ADAPTATION.md b/doc/NSS_USERSPACE_ADAPTATION.md new file mode 100644 index 0000000..d20f485 --- /dev/null +++ b/doc/NSS_USERSPACE_ADAPTATION.md @@ -0,0 +1,79 @@ +# NSS userspace adaptation boundary + +The NSS import is a source and behaviour reference for Mars NWE. The goal is +not to recreate the Novell NSS filesystem or its Linux kernel modules in +userspace. The goal is to reuse the useful NSS semantics as libraries that Mars +NWE can call. + +## Target semantics + +The useful exported behaviour is primarily: + +- namespace handling for DOS, LONG/OS2 and later MAC/UNIX/DataStream/EA; +- trustee and rights-management semantics; +- effective-rights calculation; +- extended-attribute and metadata semantics; +- the `_ADMIN`/AdminVolume view as a Mars-provided in-memory/config-backed + userspace volume; +- salvage/compression/repair-related helpers where they expose useful NetWare + semantics. + +These pieces should become library code owned by Mars NWE integration points, +not a standalone NSS volume implementation. + +## Storage and persistence boundary + +NSS code may contain logic for writing metadata, names, trustees or xattrs into +an NSS volume. In Mars NWE, that storage backend is different: + +- metadata and xattrs should be mapped to the underlying host filesystem, using + the existing or future Mars/NWFS xattr layer; +- AdminVolume data should be generated from Mars configuration/runtime state, + not stored in a fake NSS disk format; +- namespace and rights functions should operate on Mars volume/file abstractions + once the dependency chain is available; +- no Linux kernel module, NSS disk format or hidden NSS volume should become a + runtime requirement. + +During initial imports, keep NSS files as close to original as practical so the +real dependencies are visible. Later integration patches may replace NSS storage +hooks with Mars userspace hooks, but those replacements should be explicit and +well documented. + +## Makefile and module-list audit + +The NSS `Makefile`, `*Modules.mk` and buildtool files are useful as dependency +maps. They should be used to identify which sources belong to features such as +AdminVolume, namespace, common Beast objects, LSA, cache/runtime support and +rights handling. + +They are not a build target for Mars NWE. Mars should import only the source +files and headers required to expose the desired library behaviour, then wire +those pieces into the CMake library targets. + +## Import strategy + +1. Import bottom-up runtime dependencies with original filenames and directory + shape where practical. +2. Prefer real NSS implementation files over invented wrappers. +3. Keep public include roots as `include/core` and `include/nwfs`; keep NSS + subdirectories in include names. +4. Add small CTests for each imported runtime group. +5. When NSS code reaches filesystem persistence, replace that boundary with Mars + userspace adapters instead of carrying NSS kernel/disk assumptions forward. +6. Audit already-imported or rewritten Mars files, especially `nwfs/lsa`, before + building higher-level namespace/AdminVolume features on top of them. + +## AdminVolume direction + +`_ADMIN` should be represented as a Mars NWE userspace/admin library view. The +NSS sources should provide the semantics and object layout clues, while Mars +provides the backing data. The initial integration should keep `_ADMIN` internal +and not expose it over NCP until namespace, metadata, rights and generated-file +behaviour are reliable. + +Volume numbering remains: + +- `SYS = 0` +- `_ADMIN = 1` +- further configured volumes start at `2` diff --git a/doc/librarys/README.md b/doc/librarys/README.md index f5c64b2..ccbdfdb 100644 --- a/doc/librarys/README.md +++ b/doc/librarys/README.md @@ -34,3 +34,9 @@ standalone public page. For example, iniparser and Unicode tables are internal The directory names use the `nw...` prefix for documentation even when the underlying CMake target or upstream project keeps its original name. This keeps Mars-specific documentation grouped and avoids collisions with upstream docs. + +## NSS userspace adaptation boundary + +See `../NSS_USERSPACE_ADAPTATION.md` for the rule that NSS imports provide +semantics and dependency provenance, while Mars NWE provides the userspace +storage, xattr, AdminVolume and integration backends. diff --git a/doc/librarys/nwfs/README.md b/doc/librarys/nwfs/README.md index f746220..6b18321 100644 --- a/doc/librarys/nwfs/README.md +++ b/doc/librarys/nwfs/README.md @@ -31,3 +31,13 @@ all active yet. Mars code should prefer the active `nwfs` public headers for metadata and quota operations. NSS namespace internals should remain internal until the full Namespace, Beast and AdminVolume dependency chain is available. + +## NSS adaptation boundary + +`nwfs` should expose NetWare/NSS semantics to Mars NWE, not embed a fake NSS +filesystem. NSS xattr, metadata, namespace and rights code may be imported as +provenance-preserving library code, but persistence must be mapped onto Mars +userspace storage: host filesystem xattrs, Mars metadata files, and generated +AdminVolume state. + +See `doc/NSS_USERSPACE_ADAPTATION.md` for the project-wide boundary.