mars_nwe/mars-nwe
1
0
Fork 0
Code Issues Pull Requests Actions Projects Releases 2 Wiki Activity

docs: disambiguate ncp22 decimal and wire notation

Browse Source
This commit is contained in:
Mario Fetka
2026-06-01 21:53:38 +00:00
parent 21c30e8277
commit 98cf7e1621
2 changed files with 158 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
AI.md
View File

@@ -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.

292
TODO.md
View File

@@ -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