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

docs: tighten sync fall-through selector notes

Browse Source
This commit is contained in:
Mario Fetka
2026-06-02 20:29:30 +00:00
parent 4f58e2d085
commit 6b00f1b522
3 changed files with 126 additions and 120 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
AI.md
View File

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

5
TODO.md
View File

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

221
src/nwconn.c
View File

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