From 98cf7e1621632ff4de854a40cafdfd6581581512 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Mon, 1 Jun 2026 21:53:38 +0000 Subject: [PATCH] docs: disambiguate ncp22 decimal and wire notation --- AI.md | 1 + TODO.md | 292 ++++++++++++++++++++++++++++++-------------------------- 2 files changed, 158 insertions(+), 135 deletions(-) diff --git a/AI.md b/AI.md index 1ac91e6..d9e3218 100644 --- a/AI.md +++ b/AI.md @@ -34,6 +34,7 @@ use, the current project status that the user pasted into the chat. - When a `0x2222` group is forwarded out of `nwconn.c`, document both layers: `nwconn.c` should explain the group handoff/header, and the destination file (for example `nwbind.c`) should document concrete subfunction request/reply layouts. - For documentation-only endpoint patches, do not change parser offsets, byte order, reply layout, or completion behavior. Always compare the code parser/reply layout against the applicable SDK/WebSDK/PDF request format and, when available, the uploaded SDK include prototypes. If the code differs from the SDK layout, document the concrete difference inline and mirror it in `TODO.md` for later testing. If it matches, say so in the patch summary so the audit trail is clear. - When an SDK/WebSDK/PDF endpoint number is written in decimal notation, convert it carefully to the wire `case` value before adding inline documentation. Example: Directory Services `0x2222/22/12` in the PDF means SubFunctionCode decimal 12, i.e. wire `case 0x0c`; it is not the existing `case 0x12` / decimal 18 Allocate Permanent Directory Handle. Place disabled stubs directly at the correct numeric slot inside the dispatcher, never appended at the end of the function. +- In `TODO.md` and endpoint summaries, avoid ambiguous mixed notation for grouped subfunctions. Write SDK/PDF numbers as decimal and include the wire byte explicitly when it differs or could be confused, for example `SDK 22/18 / wire 0x12` or `SDK 22/12 / wire 0x0c`. Do not write `22/12` for a wire `case 0x12` unless the SDK number is actually decimal 12. - Keep `TODO.md` endpoint audit notes grouped by endpoint family and NetWare generation instead of as one long flat list. - The rejected `0152-docs-note-message-control-subfunction.patch` must not be applied: it documented `0x2222/21/0x0c Connection Message Control`, which is outside the default NetWare 1.x/2.x/3.x MARS-NWE target scope. diff --git a/TODO.md b/TODO.md index a3cd2dd..c6bb0bf 100644 --- a/TODO.md +++ b/TODO.md @@ -232,158 +232,180 @@ Current status: subfunctions forwarded to `src/nwbind.c` for bindery/ObjectID prehandling. - The group header is documented inline as `SubFuncStrucLen` (Hi-Lo), `SubFunctionCode`, and subfunction payload. -- The first NetWare 1.x/2.x/3.x-compatible directory services - subfunctions now have inline SDK request/reply layout documentation: - `22/00` Set Directory Handle, `22/01` Get Directory Path, - `22/02` Scan Directory Information, `22/03` Get Effective Directory Rights, - `22/04` Modify Maximum Rights Mask, `22/05` Get Volume Number, and `22/06` - Get Volume Name. -- The old SDK PDF table for `22/00` repeats `TargetDirectoryHandle` for the - second payload byte, but the remarks describe a source handle; MARS-NWE +- Endpoint numbers in SDK/PDF/WebSDK prose are decimal unless the source + explicitly prefixes them with `0x`. The wire `case` byte is listed below + whenever decimal and hex notation can be confused. +- Already audited and inline-documented default-compatibility calls: + - SDK `22/00` / wire `0x00` Set Directory Handle + - SDK `22/01` / wire `0x01` Get Directory Path + - SDK `22/02` / wire `0x02` Scan Directory Information + - SDK `22/03` / wire `0x03` Get Effective Directory Rights + - SDK `22/04` / wire `0x04` Modify Maximum Rights Mask + - SDK `22/05` / wire `0x05` Get Volume Number + - SDK `22/06` / wire `0x06` Get Volume Name + - SDK `22/10` / wire `0x0a` Create Directory + - SDK `22/11` / wire `0x0b` Delete Directory + - SDK `22/13` / wire `0x0d` Add Trustee to Directory + - SDK `22/14` / wire `0x0e` Delete Trustee from Directory + - SDK `22/15` / wire `0x0f` Rename Directory + - SDK `22/18` / wire `0x12` Allocate Permanent Directory Handle + - SDK `22/19` / wire `0x13` Allocate Temporary Directory Handle + - SDK `22/20` / wire `0x14` Deallocate Directory Handle + - SDK `22/21` / wire `0x15` Get Volume Info with Handle + - SDK `22/22` / wire `0x16` Allocate Special Temporary Directory Handle + - SDK `22/23` / wire `0x17` Extract a Base Handle + - SDK `22/24` / wire `0x18` Restore an Extracted Base Handle + - SDK `22/25` / wire `0x19` Set Directory Information + - SDK `22/26` / wire `0x1a` Get Path Name of a Volume-Directory Number Pair + - SDK `22/27` / wire `0x1b` Scan Salvageable Files (old) + - SDK `22/28` / wire `0x1c` Recover Salvageable File (old) + - SDK `22/29` / wire `0x1d` Purge Salvageable File (old) + - SDK `22/30` / wire `0x1e` Scan a Directory + - SDK `22/31` / wire `0x1f` Get Directory Entry + - SDK `22/32` / wire `0x20` Scan Volume's User Disk Restrictions + - SDK `22/33` / wire `0x21` Add User Disk Space Restriction + - SDK `22/34` / wire `0x22` Remove User Disk Space Restrictions + - SDK `22/37` / wire `0x25` Set Directory Entry Information + - SDK `22/38` / wire `0x26` Scan File or Directory for Extended Trustees + - SDK `22/39` / wire `0x27` Add Extended Trustee to Directory or File + - SDK `22/40` / wire `0x28` Scan Directory Disk Space + - SDK `22/41` / wire `0x29` Get Object Disk Usage and Restrictions + - SDK `22/42` / wire `0x2a` Get Effective Rights for Directory Entry + - SDK `22/43` / wire `0x2b` Remove Extended Trustee from Dir or File + - SDK `22/44` / wire `0x2c` Get Volume and Purge Information + - SDK `22/45` / wire `0x2d` Get Directory Information + - SDK `22/46` / wire `0x2e` Rename Or Move (old) + - SDK `22/47` / wire `0x2f` Get Name Space Information + - SDK `22/48` / wire `0x30` Get Name Space Directory Entry +- Already audited NetWare 4.x planning-bucket calls with existing active + MARS-NWE implementations: + - SDK `22/50` / wire `0x32` Get Object Effective Rights for Directory Entry + - SDK `22/51` / wire `0x33` Get Extended Volume Information + These are not part of the default 1.x/2.x/3.x implementation TODO list, but + existing compatibility code remains active. +- The old SDK PDF table for SDK `22/00` repeats `TargetDirectoryHandle` for + the second payload byte, but the remarks describe a source handle; MARS-NWE parses the byte as `SourceDirectoryHandle`. This is documented inline but not changed. -- No NetWare 1.x/2.x/3.x SDK/PDF entries were found for direct `22/07`, +- No NetWare 1.x/2.x/3.x SDK/PDF entries were found for direct SDK `22/07`, `22/08`, or `22/09` during this audit. The next documented direct directory - calls continue at `22/0a`. -- The next WebSDK/PDF recheck found `22/12` in the old documentation, but - that number is decimal notation: the wire subfunction is `0x0c`, not the - already implemented `case 0x12` below. `22/12` / `0x0c` Scan Directory for - Trustees is documented for NetWare 2.x/3.x and has only a disabled inline - stub for now. -- `22/0a` Create Directory, `22/0b` Delete Directory, `22/0d` Add Trustee to - Directory, `22/0e` Delete Trustee from Directory, and `22/0f` Rename - Directory now have inline request-layout documentation. -- `22/0d` and `22/0e` match the SDK/PDF payload layouts. `22/0f` matches the - payload layout; the old PDF labels this call's `SubFuncStrucLen` as Lo-Hi, - but MARS-NWE dispatches the group before using that length word and the - surrounding NCP 22 group header is otherwise documented as Hi-Lo. -- `22/0a` and `22/0b` preserve the documented offset of - `DirectoryAccessMask`, but the current implementation does not use that - field when creating or deleting the directory. -- `22/12` Alloc Permanent Directory Handle, `22/13` Alloc Temporary Directory - Handle, `22/16` Alloc Special Temporary Directory Handle, `22/14` - Deallocate Directory Handle, and `22/15` Get Volume Info with Handle now - have inline request/reply layout documentation. Their current parsers match + calls continue at SDK `22/10` / wire `0x0a`. +- WebSDK/PDF recheck found SDK `22/12` / wire `0x0c` Scan Directory for + Trustees. Do not confuse this with the already implemented wire `case 0x12` + / SDK `22/18` Allocate Permanent Directory Handle. Scan Directory for + Trustees has only a disabled inline stub for now. +- WebSDK/PDF also documents SDK `22/35` / wire `0x23` Get Directory Disk Space + Restriction and SDK `22/36` / wire `0x24` Set Directory Disk Space + Restriction as NetWare 3.x-compatible directory quota calls. They are not + active cases in this dispatcher yet; disabled inline stubs now sit at their + numeric wire slots between SDK `22/34` / wire `0x22` and SDK `22/37` / wire + `0x25`. +- SDK `22/13` / wire `0x0d` and SDK `22/14` / wire `0x0e` match the SDK/PDF + payload layouts. SDK `22/15` / wire `0x0f` matches the payload layout; the + old PDF labels this call's `SubFuncStrucLen` as Lo-Hi, but MARS-NWE + dispatches the group before using that length word and the surrounding NCP 22 + group header is otherwise documented as Hi-Lo. +- SDK `22/10` / wire `0x0a` and SDK `22/11` / wire `0x0b` preserve the + documented offset of `DirectoryAccessMask`, but the current implementation + does not use that field when creating or deleting the directory. +- SDK `22/18`, `22/19`, `22/22`, `22/20`, and `22/21` request parsers match the documented NetWare 1.x/2.x/3.x payload offsets. -- `22/17` Extract a Base Handle and `22/18` Restore an Extracted Base Handle - now have inline request/reply layout documentation. The current parsers - match the actual payload fields, but the local NDK/Core Protocols PDF tables - for this older NetWare 2.x save/restore pair contain header/length wording - that does not line up cleanly with the common `0x2222/22` group header. This - is documented inline and no behavior was changed. -- `22/19` Set Directory Information, `22/1a` Get Path Name of a - Volume-Directory Number Pair, `22/1b` Scan Salvageable Files (old), `22/1c` - Recover Salvageable File (old), `22/1d` Purge Salvageable File (old), - `22/1e` Scan a Directory, `22/1f` Get Directory Entry, and `22/20` Scan - Volume's User Disk Restrictions now have inline request/reply layout - documentation. -- `22/19`, `22/1a`, `22/1b`, and `22/1d` match the documented request payload - offsets. `22/1a` uses the old 16-bit directory-entry-number form; the - WebSDK table does not spell out byte order for that word, while MARS-NWE - reads it as Hi-Lo. -- `22/1c` validates the documented old/new filename fields, but the current +- SDK `22/23` / wire `0x17` and SDK `22/24` / wire `0x18` now have inline + request/reply layout documentation. The current parsers match the actual + payload fields, but the local NDK/Core Protocols PDF tables for this older + NetWare 2.x save/restore pair contain header/length wording that does not + line up cleanly with the common `0x2222/22` group header. This is documented + inline and no behavior was changed. +- SDK `22/25`, `22/26`, `22/27`, and `22/29` match the documented request + payload offsets. SDK `22/26` uses the old 16-bit directory-entry-number + form; the WebSDK table does not spell out byte order for that word, while + MARS-NWE reads it as Hi-Lo. +- SDK `22/28` validates the documented old/new filename fields, but the current backend call recovers by directory handle and sequence only and does not pass the old/new names to the salvage backend. -- `22/1e` matches the documented offsets, but the SDK documents `Sequence` as - Lo-Hi while the current parser reads it with `GET_BE32()`. -- `22/1f` consumes the documented `DirectoryHandle`; legacy source comments - expected two extra unknown bytes after it, but the SDK request has no such - fields and the helper ignores them. -- `22/20` reads `VolumeNumber` in the normal NCP 22 payload position, but the - WebSDK/PDF table for this call shows `VolumeNumber` one byte later than the - common group-header alignment. The code also reads `Sequence` with - `GET_BE32()` although the SDK/PDF documents Lo-Hi; treat both as audit items - until verified with a direct test caller. -- `22/21` Add User Disk Space Restriction, `22/22` Remove User Disk Space - Restrictions, `22/25` Set Directory Entry Information, `22/26` Scan File or - Directory for Extended Trustees, `22/27` Add Extended Trustee to Directory or - File, `22/28` Scan Directory Disk Space, and `22/29` Get Object Disk Usage - and Restrictions now have inline request/reply layout documentation. -- WebSDK/PDF also documents `22/35` / wire `0x23` Get Directory Disk Space - Restriction and `22/36` / wire `0x24` Set Directory Disk Space Restriction - as NetWare 3.x-compatible directory quota calls. They are not active cases - in this dispatcher yet; disabled inline stubs now sit at their numeric slots - between `22/22` and `22/25`. -- `22/21` and `22/22` are forwarded to `nwbind.c` for quota prehandling; both - layers are documented. The shared `nwbind` prehandler reads ObjectID from - the documented payload position. -- `22/26`, `22/27`, and `22/29` match the documented request payload offsets. -- `22/25` matches the documented payload field order, but the current parser - reads Sequence with `GET_BE32()` although the SDK/PDF documents Lo-Hi. -- `22/21` includes a documented DiskSpaceLimit field, but the current shared - quota prehandler in `nwbind.c` does not consume it before returning the - uid/gid/permission tuple. -- `22/28` matches the documented payload offsets, but the current parser reads - Sequence with `GET_BE32()` although the SDK/PDF documents Lo-Hi; it also - returns the normal directory scan structure from `nw_scan_a_directory()` +- SDK `22/30` / wire `0x1e` matches the documented offsets, but the SDK + documents `Sequence` as Lo-Hi while the current parser reads it with + `GET_BE32()`. +- SDK `22/31` / wire `0x1f` consumes the documented `DirectoryHandle`; legacy + source comments expected two extra unknown bytes after it, but the SDK + request has no such fields and the helper ignores them. +- SDK `22/32` / wire `0x20` reads `VolumeNumber` in the normal NCP 22 payload + position, but the WebSDK/PDF table for this call shows `VolumeNumber` one + byte later than the common group-header alignment. The code also reads + `Sequence` with `GET_BE32()` although the SDK/PDF documents Lo-Hi; treat + both as audit items until verified with a direct test caller. +- SDK `22/33` and `22/34` are forwarded to `nwbind.c` for quota prehandling; + both layers are documented. The shared `nwbind` prehandler reads ObjectID + from the documented payload position. SDK `22/33` includes a documented + DiskSpaceLimit field, but the current shared prehandler does not consume it + before returning the uid/gid/permission tuple. +- SDK `22/38`, `22/39`, and `22/41` match the documented request payload + offsets. +- SDK `22/37` matches the documented payload field order, but the current + parser reads Sequence with `GET_BE32()` although the SDK/PDF documents Lo-Hi. +- SDK `22/40` matches the documented payload offsets, but the current parser + reads Sequence with `GET_BE32()` although the SDK/PDF documents Lo-Hi; it + also returns the normal directory scan structure from `nw_scan_a_directory()` rather than the full documented Scan Directory Disk Space reply. -- `22/2a` Get Effective Rights for Directory Entry, `22/2b` Remove Extended - Trustee from Dir or File, `22/2d` Get Directory Information, `22/2e` Rename - Or Move (old), and `22/2f` Get Name Space Information now have inline - request/reply layout documentation and match the NetWare 1.x/2.x/3.x SDK/PDF - payload offsets used by the current parser. -- `22/2c` Get Volume and Purge Information matches the documented request - offset, but the PDF marks `TotalBlocks` as Hi-Lo while the remaining 32-bit - counters are Lo-Hi; current code uses `U32_TO_32()` for all counters. -- `22/30` Get Name Space Directory Entry matches the documented payload offsets; - the PDF does not label the `DOSSequence` byte order, and current code reads it - with `GET_32()`. -- `22/32` Get Object Effective Rights for Directory Entry and `22/33` Get - Extended Volume Information are documented by the local NDK/Core Protocols PDF - as NetWare 4.x/5.x calls and are also covered by the uploaded WebSDK/include - material. They are not part of the default 1.x/2.x/3.x implementation TODO - list, but the existing MARS-NWE implementations remain active and are tracked - in the NetWare 4.x planning bucket above. +- SDK `22/42`, `22/43`, `22/45`, `22/46`, and `22/47` match the NetWare + 1.x/2.x/3.x SDK/PDF payload offsets used by the current parser. +- SDK `22/44` / wire `0x2c` matches the documented request offset, but the PDF + marks `TotalBlocks` as Hi-Lo while the remaining 32-bit counters are Lo-Hi; + current code uses `U32_TO_32()` for all counters. +- SDK `22/48` / wire `0x30` matches the documented payload offsets; the PDF + does not label the `DOSSequence` byte order, and current code reads it with + `GET_32()`. Follow-up: -- Implement or intentionally reject `22/12` / wire `0x0c` Scan Directory for - Trustees. Do not confuse the SDK decimal subfunction number 12 with the - already implemented wire `case 0x12` / decimal 18 directory-handle call. -- Implement or intentionally reject `22/35` / wire `0x23` Get Directory Disk - Space Restriction and `22/36` / wire `0x24` Set Directory Disk Space - Restriction. Both are NetWare 3.x-compatible, not `MARS_NWE_4` work. -- Verify the documented `22/00` source-handle interpretation against an old - requester or direct test caller before changing behavior. -- Decide whether `22/0a` and `22/0b` should apply or validate the documented - `DirectoryAccessMask` byte, or whether ignoring it is required for old - requester compatibility. -- Verify `22/17` and `22/18` against an old requester or direct test caller - before changing the conservative connection-local implementation; the SDK/PDF - tables for those two NetWare 2.x calls are less internally consistent than - the surrounding directory-handle calls. -- Verify `22/1a` directory-entry-number byte order against an old requester or - direct test caller before changing the current Hi-Lo interpretation. -- Decide whether `22/1c` should pass the documented old/new filename fields to - the salvage backend, or whether sequence-only recovery is sufficient for old - requester compatibility. -- Verify `22/1e` Sequence byte order; current code uses `GET_BE32()` although - the SDK/WebSDK documents Lo-Hi. -- Verify whether `22/1f` should continue accepting legacy callers that send the - two extra bytes described by the old source comment, even though the SDK +- Implement or intentionally reject SDK `22/12` / wire `0x0c` Scan Directory + for Trustees. Do not confuse the SDK decimal subfunction number 12 with the + already implemented wire `case 0x12` / SDK `22/18` directory-handle call. +- Implement or intentionally reject SDK `22/35` / wire `0x23` Get Directory + Disk Space Restriction and SDK `22/36` / wire `0x24` Set Directory Disk + Space Restriction. Both are NetWare 3.x-compatible, not `MARS_NWE_4` work. +- Verify the documented SDK `22/00` source-handle interpretation against an + old requester or direct test caller before changing behavior. +- Decide whether SDK `22/10` / wire `0x0a` and SDK `22/11` / wire `0x0b` + should apply or validate the documented `DirectoryAccessMask` byte, or + whether ignoring it is required for old requester compatibility. +- Verify SDK `22/23` / wire `0x17` and SDK `22/24` / wire `0x18` against an + old requester or direct test caller before changing the conservative + connection-local implementation; the SDK/PDF tables for those two NetWare + 2.x calls are less internally consistent than the surrounding + directory-handle calls. +- Verify SDK `22/26` directory-entry-number byte order against an old requester + or direct test caller before changing the current Hi-Lo interpretation. +- Decide whether SDK `22/28` should pass the documented old/new filename fields + to the salvage backend, or whether sequence-only recovery is sufficient for + old requester compatibility. +- Verify SDK `22/30` Sequence byte order; current code uses `GET_BE32()` + although the SDK/WebSDK documents Lo-Hi. +- Verify whether SDK `22/31` should continue accepting legacy callers that send + the two extra bytes described by the old source comment, even though the SDK request only contains `DirectoryHandle`. -- Verify `22/20` VolumeNumber offset and Sequence byte order against a direct - test caller; the WebSDK table appears shifted by one byte compared with the - normal NCP 22 group header, and current code uses `GET_BE32()` although the - SDK/PDF documents Lo-Hi. -- Decide whether `22/21` should pass the documented DiskSpaceLimit through the - quota prehandling path or whether the current behavior is intentionally +- Verify SDK `22/32` VolumeNumber offset and Sequence byte order against a + direct test caller; the WebSDK table appears shifted by one byte compared + with the normal NCP 22 group header, and current code uses `GET_BE32()` + although the SDK/PDF documents Lo-Hi. +- Decide whether SDK `22/33` should pass the documented DiskSpaceLimit through + the quota prehandling path or whether the current behavior is intentionally handled later in the quota backend. -- Verify `22/25` Sequence byte order; current code uses `GET_BE32()` although - the SDK/PDF documents Lo-Hi. -- Verify `22/28` Sequence byte order and reply shape; current code uses +- Verify SDK `22/37` Sequence byte order; current code uses `GET_BE32()` + although the SDK/PDF documents Lo-Hi. +- Verify SDK `22/40` Sequence byte order and reply shape; current code uses `GET_BE32()` and delegates to the normal directory scan reply rather than the documented Scan Directory Disk Space reply. -- Verify `22/2c` Volume and Purge Information reply byte order for +- Verify SDK `22/44` Volume and Purge Information reply byte order for `TotalBlocks`; the SDK/PDF marks only that field as Hi-Lo, while current code emits all 32-bit counters with `U32_TO_32()`. -- Verify `22/30` DOSSequence byte order against an old requester or direct test - caller; current code uses `GET_32()` and the PDF table does not spell out the - order for that field. +- Verify SDK `22/48` DOSSequence byte order against an old requester or direct + test caller; current code uses `GET_32()` and the PDF table does not spell + out the order for that field. - The NetWare 1.x/2.x/3.x-compatible `0x2222/22` endpoint layout pass is - covered through the documented `22/48` namespace call, with the newly found - `22/12`, `22/35`, and `22/36` gaps tracked as disabled stubs/TODO items. - Continue with the next non-4.x/OES-only group after this block. + covered through the documented SDK `22/48` namespace call, with the newly + found SDK `22/12`, `22/35`, and `22/36` gaps tracked as disabled stubs/TODO + items. Continue with the next non-4.x/OES-only group after this block. ### Extended volume information field mapping