From 9be855ec7bc2cd411fcbee0135556903e4c8b7b3 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 05:32:34 +0000 Subject: [PATCH] docs: audit direct lifecycle and buffer endpoints --- AI.md | 2 ++ TODO.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++--- src/nwbind.c | 19 ++++++++++++++++-- src/nwconn.c | 39 ++++++++++++++++++++++++++++--------- 4 files changed, 100 insertions(+), 14 deletions(-) diff --git a/AI.md b/AI.md index 9713368..b0f3e74 100644 --- a/AI.md +++ b/AI.md @@ -72,6 +72,8 @@ patch against the last confirmed applied patch, not against the rejected file. - 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. - Before starting the next detailed endpoint block, maintain a coverage index for SDK/WebSDK-listed `0x2222` groups that are not yet audited. Classify each group as present in code but not audited, missing a top-level handler, or likely later-generation/unclear. This index is only a planning aid: do not add active TODO work or source stubs until the specific block has been checked for handoffs and bucketed by oldest documented NetWare generation. +- Before every new endpoint-family patch, first do a missing-endpoint pass for that family: enumerate the SDK/PDF/WebSDK/include endpoint list, compare it against actual `case` labels and forwarded destination handlers, then document implemented, disabled-stub, and absent slots separately. Do this retroactively for already documented families when touching them again. +- Always document both the request handoff/parser and the reply builder. For forwarded calls, the `nwconn.c` comment should explain exactly why `return(-1)` or `return(-2)` is used; the destination handler should explain the concrete request bytes and response payload. Do not treat `return(-1)` inside disabled `#if 0` snippets in `nwbind.c` as a forwarding mechanism. - For SDK-listed groups that appear missing from `nwconn.c`, also search destination files such as `nwbind.c`, queue helpers, salvage helpers, AFP/name-space dispatchers, and any prehandler path before declaring the endpoint absent. - 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 58cf0a5..7244541 100644 --- a/TODO.md +++ b/TODO.md @@ -179,9 +179,9 @@ Present in the code but not yet fully endpoint-audited: - SDK `0x2222/26` through `0x2222/31` / wire `0x1a` through `0x1f` physical record synchronization calls are implemented in `src/nwconn.c` but have not yet received the detailed request-layout audit. -- SDK `0x2222/33` / wire `0x21` Negotiate Buffer Size and SDK `0x2222/34` / - wire `0x22` TTS calls are present in `src/nwconn.c`; their layouts still need - source comparisons. +- SDK `0x2222/34` / wire `0x22` TTS calls are present in `src/nwconn.c`; + their remaining state-changing layouts still need source comparisons beyond + the current availability/no-op note. - SDK `0x2222/35` / wire `0x23` AFP calls are present in `src/nwconn.c`; AFP has separate compatibility tests, but the NCP request-layout audit should still be completed endpoint by endpoint. @@ -522,6 +522,54 @@ Known differences / follow-up: not routed through this compatibility handler. +#### Direct connection lifecycle and buffer-size calls + +Current status: + +- Direct `NCP 0x2222/24` / wire function `0x18` End Of Job is implemented as a + paired `nwconn.c`/`nwbind.c` handoff. The PDF/WebSDK request has no payload + after FunctionCode 24 and the reply has no payload. `nwconn.c` releases + task-local handles and jobs first; `nwbind.c` closes matching print jobs and + sends the final empty success reply. +- Direct `NCP 0x2222/25` / wire function `0x19` Logout is implemented as a + paired `nwconn.c`/`nwbind.c` handoff. The PDF/WebSDK request has no payload + after FunctionCode 25 and the reply has no payload. `nwconn.c` releases local + queue/file/user state; `nwbind.c` closes remaining print jobs, writes logout + accounting state, clears bindery identity fields, and sends the final empty + success reply. +- Direct `NCP 0x2222/33` / wire function `0x21` Negotiate Buffer Size is handled + entirely in `src/nwconn.c`. The request is `ProposedBufferSize` as a Hi-Lo + word and the reply is `AcceptedBufferSize` as a Hi-Lo word. The current + parser/reply match the documented order. MARS-NWE clamps valid proposals to + `LOC_RW_BUFFERSIZE`; proposals below 512 leave the existing/default negotiated + size in force and return that value. + +Missing-endpoint check: + +- These three are direct functions, not nested subfunction groups. No additional + subfunctions are listed under SDK `24`, SDK `25`, or SDK `33` in the local + NDK/Core-Protocols PDF/WebSDK material. + + +#### Retrospective endpoint coverage rule for audited blocks + +Current status: + +- From this point on, each endpoint-family patch should first list the + SDK/PDF/WebSDK endpoints in that family, then compare that list against the + real dispatcher cases and any forwarded target handlers before documenting + individual request/reply layouts. +- Apply the same rule retroactively when touching an already-audited family: + message `0x2222/21`, directory/quota `0x2222/22`, file-server environment + `0x2222/23`, direct lifecycle `0x2222/24` and `0x2222/25`, semaphore + `0x2222/32`, and buffer negotiation `0x2222/33` should each state whether + missing endpoints were checked, and whether the family has active code, + disabled future stubs, or no top-level handler. +- A disabled `#if 0` stub is only a documentation/slot marker. Do not assign + `return(-1)` forwarding semantics to such stubs in `nwbind.c`; that special + forwarding meaning belongs to `nwconn.c`'s `handle_ncp_serv()` path. + + #### File Server Environment group 0x2222/23 Current status: diff --git a/src/nwbind.c b/src/nwbind.c index 73486ba..f26fee4 100644 --- a/src/nwbind.c +++ b/src/nwbind.c @@ -2946,11 +2946,26 @@ static void handle_fxx(int gelen, int func) break; } /* switch */ } else if (func == 0x18) { /* End of Job */ - /* Forwarded direct NCP 0x2222/24 cleanup after nwconn releases local handles. */ + /* + * Forwarded direct NCP 0x2222/24 End of Job. + * + * handle_fxx() does not consume a grouped subfunction header for this + * direct function: requestdata points at the empty post-FunctionCode + * payload. nwconn has already released task-local handles; nwbind only + * closes the matching print jobs and returns a normal empty reply. + */ if (!(entry8_flags&0x200)) /* pcz: 14-Apr-00 */ nw_close_connection_jobs(act_connection, ncprequest->task); /* close print jobs */ } else if (func == 0x19) { /* logout */ - /* Forwarded direct NCP 0x2222/25 logout cleanup after nwconn resets connection state. */ + /* + * Forwarded direct NCP 0x2222/25 Logout. + * + * handle_fxx() does not consume a grouped subfunction header for this + * direct function: requestdata points at the empty post-FunctionCode + * payload. nwconn has already released local queue/file/user state; + * nwbind closes any remaining print jobs, records logout state, clears + * bindery identity, and returns a normal empty reply. + */ nw_close_connection_jobs(act_connection, -1); /* close all print jobs */ write_utmp(0, act_connection, act_c->pid_nwconn, &(act_c->client_adr), NULL); act_c->object_id = 0; /* not LOGIN */ diff --git a/src/nwconn.c b/src/nwconn.c index 2596b46..a82627b 100644 --- a/src/nwconn.c +++ b/src/nwconn.c @@ -5569,11 +5569,14 @@ static int handle_ncp_serv(void) case 0x18 : /* End of Job */ /* - * Direct NCP 0x2222/24 End of Job has no nested payload. - * nwconn releases local file/task handles first, then - * forwards to nwbind so the bindery/queue side can close - * print jobs for this task. Document further behavior in - * nwbind.c if this endpoint is audited later. + * Direct NCP 0x2222/24 End of Job. + * + * SDK request payload: none after FunctionCode 24. There + * is no reply payload; the completion code reports success. + * + * MARS-NWE handoff: nwconn first frees task-local file and + * job resources, then returns -1 so nwbind can close the + * connection/task print jobs before sending the final reply. */ if (!(entry8_flags&0x200)) /* pcz: 14-Apr-00 */ free_connection_task_jobs(ncprequest->task); @@ -5583,10 +5586,15 @@ static int handle_ncp_serv(void) case 0x19 : /* logout, some of this call is handled in ncpserv. */ /* - * Direct NCP 0x2222/25 Logout has no nested payload. The - * connection state is cleared here and nwbind performs the - * remaining bindery/queue logout cleanup, so endpoint docs - * must cover both sides when this call is audited. + * Direct NCP 0x2222/25 Logout. + * + * SDK request payload: none after FunctionCode 25. There + * is no reply payload; the completion code reports success. + * + * MARS-NWE handoff: nwconn releases local queue/file/user + * state, then returns -1 so nwbind can close all remaining + * print jobs, clear bindery identity fields, and send the + * final reply. */ free_queue_jobs(); nw_free_handles(-1); @@ -5744,6 +5752,19 @@ static int handle_ncp_serv(void) return(-1); /* handled by nwbind */ case 0x21 : { /* Negotiate Buffer Size, Packetsize */ + /* + * Direct NCP 0x2222/33 Negotiate Buffer Size. + * + * SDK request payload: + * word ProposedBufferSize (Hi-Lo) + * SDK reply payload: + * word AcceptedBufferSize (Hi-Lo) + * + * The parser/reply match the documented Hi-Lo wire order. + * MARS-NWE clamps valid proposals to LOC_RW_BUFFERSIZE; + * a proposal below 512 is ignored and the previously + * negotiated/default rw_buffer_size is returned. + */ uint8 *getsize=responsedata; int buffer_size = (int) (GET_BE16((uint8*)requestdata)); /* Der Novell-Client der PAM's Net/E-Ethernetkarte