From 6b00f1b5222f2dcb084da62e0e638558aa4783ce Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 20:29:30 +0000 Subject: [PATCH] docs: tighten sync fall-through selector notes --- AI.md | 20 ++++- TODO.md | 5 ++ src/nwconn.c | 221 ++++++++++++++++++++++++--------------------------- 3 files changed, 126 insertions(+), 120 deletions(-) diff --git a/AI.md b/AI.md index c318ea8..d1ce6e4 100644 --- a/AI.md +++ b/AI.md @@ -1239,4 +1239,22 @@ Next patch number should be `0253`. lock allocation, async wait-node lifetime, and correct completion-code mapping. -Next patch number should be `0259`. +## 2026-06-02 - Patch 0259 fall-through synchronization selector notes + +- Continued NDK-first after the direct async synchronization stubs by tightening + the implemented old file/logical synchronization fall-through handlers in + `src/nwconn.c`: + - `04` Lock File Set (old) and `106` Lock File Set + - `05` Release File (old) and `07` Clear File (old) + - `06` Release File Set and `08` Clear File Set + - `11` Clear Logical Record and `12` Release Logical Record + - `14` Clear Logical Record Set and `13` Release Logical Record Set +- This is documentation-only. The active fall-through control flow remains + unchanged: shared parser/handler branches stay shared, but each wire `case` + label now has its own nearby `Request:` and `Response:` notes. +- Keep the parser audit items unchanged: old `04` documents Lo-Hi timeout while + the shared handler uses `GET_BE16()`, and the set release/clear handlers for + file and logical records still ignore the documented `LockFlag` byte until + direct requester traces justify changing behavior. + +Next patch number should be `0260`. diff --git a/TODO.md b/TODO.md index 57ba05c..7fc9645 100644 --- a/TODO.md +++ b/TODO.md @@ -373,6 +373,11 @@ Current status: - Patch `0256` tightens the implemented physical-record family without changing control flow: shared fall-through handlers stay shared, but each adjacent case label now has its own Request/Response notes. +- Patch `0259` applies the same no-control-flow-split documentation rule to + the implemented old file and logical-record fall-through handlers: SDK `04` + with `106`, SDK `05` with `07`, SDK `06` with `08`, SDK `11` with `12`, and + SDK `14` with `13` keep their shared parser branches while each label gets + its own Request/Response notes. - `NCP 0x1a Log Physical Record (old)`, `0x1c Release Physical Record`, and `0x1e Clear Physical Record` are implemented and now have inline request layout documentation. The parser matches the documented 6-byte handle diff --git a/src/nwconn.c b/src/nwconn.c index 611fbde..cc84985 100644 --- a/src/nwconn.c +++ b/src/nwconn.c @@ -2838,34 +2838,29 @@ static int handle_ncp_serv(void) } break; - case 0x4 : /* Lock File Set (old) */ - case 0x6a : { /* Lock File Set */ - /* - * NCP 0x2222/04 Lock File Set (old) and NCP 0x2222/106 Lock - * File Set lock all files logged by the calling client's current - * task. - * - * SDK request: - * - * 0x04 old: word LockTimeout, documented as Lo-Hi. - * 0x6a new: word LockTimeout, documented as Hi-Lo. - * - * SDK reply: no reply data. - * SDK completion: 0x00 success; old 0x04 documents 0xfe timeout - * and 0xff lock error, while newer 0x6a also documents - * 0x7f ERR_LOCK_WAITING. - * - * The newer 0x6a call replaces the old 0x04 call for later - * clients. MARS-NWE currently handles both calls in one branch - * and reads the timeout with GET_BE16(). That matches the 0x6a - * Hi-Lo SDK layout; the old 0x04 SDK page documents Lo-Hi. This - * comment records the wire-layout difference only; the parser is - * intentionally left unchanged in this documentation pass. - * - * MARS-NWE records file-set members through Log File (0x03), then - * uses the shared set handler for Lock/Release/Clear File Set - * operations. - */ + case 0x4 : /* SDK 04 Lock File Set (old) */ + /* + * Request: LockTimeout word, documented Lo-Hi in the + * old NDK page. + * Response: no reply payload; Completion reports success, + * timeout, or lock error. + */ + case 0x6a : { /* SDK 106 Lock File Set */ + /* + * Request: LockTimeout word, documented Hi-Lo. + * Response: no reply payload; Completion reports success, + * ERR_LOCK_WAITING, timeout, or lock error. + * + * Parser comparison: the active fall-through handler reads + * both old 0x04 and newer 0x6a LockTimeout with + * GET_BE16(). That matches SDK 106 but not the old SDK 04 + * Lo-Hi note; keep behavior unchanged until requester + * traces justify a parser split. + * + * MARS-NWE records file-set members through Log File + * (0x03), then uses the shared set handler for + * Lock/Release/Clear File Set operations. + */ struct INPUT { uint8 header[7]; /* Requestheader */ uint8 timeout[2]; /* HI LO */ @@ -2878,31 +2873,27 @@ static int handle_ncp_serv(void) } break; - case 0x5 : /* Release File */ - case 0x7 : { /* Clear File, removes file from logset */ - /* - * NCP 0x2222/05 Release File (old) releases one previously - * locked file but leaves it in the client's logged file table. - * NCP 0x2222/07 Clear File (old) removes one file from that - * table; if it is locked/open, the server releases/closes it. - * - * SDK request for both calls: - * - * byte DirectoryHandle - * byte FileNameLen - * bytes FileName - * - * SDK reply: no reply data. - * SDK completion for 0x05: 0x00 success, 0x9c invalid path, - * 0xff unlock error. - * SDK completion for 0x07 additionally documents 0x96 server out - * of memory, 0x98 disk map error, 0x9b bad directory handle, - * 0xa1 directory I/O error, and 0xfd bad station number. - * - * The current INPUT layout matches the documented old request - * header offsets: FunctionCode at offset 6, DirectoryHandle at - * offset 7, FileNameLen at offset 8, and FileName at offset 9. - */ + case 0x5 : /* SDK 05 Release File (old) */ + /* + * Request: DirectoryHandle, FileNameLen, FileName. + * Response: no reply payload; Completion reports success, + * invalid path, or unlock error. + * Semantics: release/unlock the named file but keep it in + * the caller's logged file table. + */ + case 0x7 : { /* SDK 07 Clear File (old) */ + /* + * Request: DirectoryHandle, FileNameLen, FileName. + * Response: no reply payload; Completion reports success, + * path/handle/server-resource errors, or unlock error. + * Semantics: release the named file and remove it from the + * caller's logged file table. + * + * Parser comparison: the shared INPUT layout matches the + * documented old request offsets: FunctionCode at offset 6, + * DirectoryHandle at offset 7, FileNameLen at offset 8, + * and FileName at offset 9. + */ struct INPUT { uint8 header[7]; /* Requestheader */ uint8 dir_handle; @@ -2920,27 +2911,25 @@ static int handle_ncp_serv(void) } break; - case 0x6 : /* Release File Set */ - case 0x8 : { /* Clear File Set */ - /* - * NCP 0x2222/06 Release File Set releases all currently logged - * or locked files, but keeps the file-log table entries. - * NCP 0x2222/08 Clear File Set releases/removes all logged files; - * open server-side file handles are invalidated by the NetWare - * semantics described in the SDK. - * - * SDK request for both calls: - * - * byte LockFlag - * - * SDK reply: no reply data. - * SDK completion: 0x00 success. - * - * MARS-NWE currently does not read the documented LockFlag byte - * and forwards the operation directly to share_handle_lock_sets(). - * This documentation patch records that parser difference only; - * endpoint behaviour is intentionally unchanged here. - */ + case 0x6 : /* SDK 06 Release File Set */ + /* + * Request: LockFlag byte. + * Response: no reply payload; Completion reports success. + * Semantics: release currently logged/locked files while + * retaining the file-log table entries. + */ + case 0x8 : { /* SDK 08 Clear File Set */ + /* + * Request: LockFlag byte. + * Response: no reply payload; Completion reports success. + * Semantics: release and remove all logged files; NetWare + * semantics also invalidate related open server handles. + * + * Parser comparison: the active shared handler does not + * read the documented LockFlag byte and selects release or + * clear solely from FunctionCode. Keep behavior unchanged + * until requester traces justify consuming LockFlag. + */ int result = share_handle_lock_sets( 1, /* File Set */ (function==0x8) @@ -3026,31 +3015,26 @@ static int handle_ncp_serv(void) } break; - case 0xb : /* Clear Logical Record */ - case 0xc : { /* Release Logical Record */ - /* - * SDK: NCP 0x2222/11 Clear Logical Record removes one logical - * record from the calling task's synchronization table. - * - * SDK: NCP 0x2222/12 Release Logical Record releases/unlocks one - * synchronization string held by the calling client. Both requests - * use the old direct layout: - * - * byte SynchNameLen - * bytes SynchName - * - * They return no reply data and report success or Unlock Error - * through the completion code. - * - * Compared against the SDK/PDF: the current INPUT layout matches - * the documented old request offsets: FunctionCode at offset 6, - * SynchNameLen at offset 7, and SynchName at offset 8. - * - * Important semantic difference: Release Logical Record leaves the - * string in the caller's synchronization string table so a later - * Lock Logical Record Set can relock it. Clear Logical Record - * unlocks and removes it from the table. - */ + case 0xb : /* SDK 11 Clear Logical Record */ + /* + * Request: SynchNameLen, SynchName. + * Response: no reply payload; Completion reports success + * or unlock error. + * Semantics: unlock and remove the synchronization string + * from the caller's logical-record table. + */ + case 0xc : { /* SDK 12 Release Logical Record */ + /* + * Request: SynchNameLen, SynchName. + * Response: no reply payload; Completion reports success + * or unlock error. + * Semantics: release/unlock the synchronization string but + * keep it logged so Lock Logical Record Set can relock it. + * + * Parser comparison: the shared INPUT layout matches the + * documented old offsets: FunctionCode at offset 6, + * SynchNameLen at offset 7, and SynchName at offset 8. + */ struct INPUT { uint8 header[7]; /* Requestheader */ uint8 len; /* synch name len */ @@ -3067,26 +3051,25 @@ static int handle_ncp_serv(void) } break; - case 0xe : /* Clear Logical Record Set */ - case 0xd : { /* Release Logical Record Set */ - /* - * NCP 0x2222/13 Release Logical Record Set releases all currently - * locked logical records but keeps the synchronization-string table. - * NCP 0x2222/14 Clear Logical Record Set releases all logical - * records and clears that table. - * - * SDK request for both calls: - * - * byte LockFlag - * - * SDK reply: no reply data. - * SDK completion: 0x00 success. - * - * MARS-NWE currently does not read the documented LockFlag byte - * and forwards the operation directly to share_handle_lock_sets(). - * This documentation patch records that parser difference only; - * endpoint behaviour is intentionally unchanged here. - */ + case 0xe : /* SDK 14 Clear Logical Record Set */ + /* + * Request: LockFlag byte. + * Response: no reply payload; Completion reports success. + * Semantics: release all locked logical records and clear + * the synchronization-string table. + */ + case 0xd : { /* SDK 13 Release Logical Record Set */ + /* + * Request: LockFlag byte. + * Response: no reply payload; Completion reports success. + * Semantics: release all currently locked logical records + * but keep the synchronization-string table. + * + * Parser comparison: the active shared handler does not + * read the documented LockFlag byte and selects release or + * clear solely from FunctionCode. Keep behavior unchanged + * until requester traces justify consuming LockFlag. + */ int result = share_handle_lock_sets( 2, /* Logical Record Set */ (function==0xe)