From b6e653c96a41b1fe0b394e6ef7a593b5ebc7797c Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 20:09:34 +0000 Subject: [PATCH] docs: tighten physical record selector notes --- AI.md | 30 +++++++++++++++-- TODO.md | 24 +++++++++++++- src/nwconn.c | 93 ++++++++++++++++++++++++++-------------------------- 3 files changed, 97 insertions(+), 50 deletions(-) diff --git a/AI.md b/AI.md index 0026187..268bae6 100644 --- a/AI.md +++ b/AI.md @@ -913,8 +913,12 @@ Endpoint audit formatting requirement from patch 0244: - Disabled source stubs for audited NDK endpoints must not group multiple selectors under one shared explanatory block. Each `switch` `case` must be documented as its own case. -- Each audited disabled case comment must include a concise `Request:` summary - and a concise `Response:` summary from NDK/PDF/WebSDK/include sources. +- Active fall-through handlers do not need control-flow rewrites only for + documentation. It is acceptable to keep adjacent `case` labels sharing one + handler, as long as each label has its own adjacent concise `Request:` and + `Response:` summary before the shared implementation block. +- Each audited case comment must include a concise `Request:` summary and a + concise `Response:` summary from NDK/PDF/WebSDK/include sources. - Keep provider ownership and "do not fake" constraints in the same case block when relevant, so future implementers do not need to infer requirements from a surrounding grouped comment. @@ -1180,5 +1184,25 @@ Next patch number should be `0253`. - Keep `nwserv` as control-plane supervisor/registry only; do not route these RPC payloads through `nwserv` as a generic data-plane broker. -Next patch number should be `0256`. +## 2026-06-02 - Patch 0256 Physical-record selector notes without control-flow split +- Continued NDK-first after RPC/server-control with the implemented physical + record lock family in `src/nwconn.c`: + - `26` Log Physical Record (old) + - `27` Lock Physical Record Set (old) + - `28` Release Physical Record + - `29` Release Physical Record Set + - `30` Clear Physical Record + - `31` Clear Physical Record Set + - `110` Lock Physical Record Set +- Patch `0256` is documentation-only and intentionally keeps the existing + fall-through handler structure. Adjacent cases may remain adjacent when they + share parser/handler logic; the requirement is that each wire case has its + own nearby `Request:` and `Response:` notes, not that active control flow be + split for documentation. +- Keep the known parser audit notes unchanged: old `27` is documented as Lo-Hi + timeout while the shared handler reads Hi-Lo, and the current LockFlag mapping + differs from the NDK/Core-Protocols text until real requester traces justify a + behavior change. + +Next patch number should be `0257`. diff --git a/TODO.md b/TODO.md index 550a7f1..0e6cf54 100644 --- a/TODO.md +++ b/TODO.md @@ -370,6 +370,9 @@ Current status: Set` are implemented, but the SDK request contains a `LockFlag` byte that the current code does not read. This parser difference is documented inline but not changed yet. +- 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. - `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 @@ -1812,6 +1815,25 @@ Current status: Follow-up: - Continue NDK-first with the next documented NetWare 1.x/2.x/3.x endpoint or - planned 4.x endpoint after RPC/server-control, keeping one case-local + planned 4.x endpoint after the physical-record family, keeping one adjacent Request/Response comment per selector and skipping 5.x-only endpoints. +### Physical-record selector documentation 26..31 plus 110 + +Current status: + +- Patch `0256` revisits the implemented physical-record lock family in + `src/nwconn.c`. It keeps the existing fall-through implementation structure + and adds per-label Request/Response notes for `26`, `27`, `28`, `29`, `30`, + `31`, and `110`. +- Runtime behavior is unchanged. The known parser compatibility notes remain: + old `27` is documented with Lo-Hi timeout while the shared handler reads + Hi-Lo, and the LockFlag mapping differs from the NDK text until client traces + justify changing behavior. + +Follow-up: + +- Continue NDK-first with the next documented NetWare 1.x/2.x/3.x endpoint or + planned 4.x endpoint after the physical-record family. Do not split active + fall-through code only for documentation; place per-case Request/Response + notes adjacent to the labels when a shared handler is intentional. diff --git a/src/nwconn.c b/src/nwconn.c index 63ce3da..01d45ed 100644 --- a/src/nwconn.c +++ b/src/nwconn.c @@ -5764,32 +5764,32 @@ static int handle_ncp_serv(void) return(-1); /* nwbind must do a little rest */ break; - case 0x1a : /* Log Physical Record */ - case 0x1c : /* Release Physical Record */ - case 0x1e : /* Clear Physical Record */ + case 0x1a : /* SDK 26 Log Physical Record (old) */ + /* + * Request: LockFlag, 6-byte NetWare file handle, + * LockAreaStartOffset (Hi-Lo), LockAreaLen (Hi-Lo), + * and LockTimeout (Hi-Lo). LockFlag 0 logs for future + * use, 1 locks exclusive/read-write, and 3 locks + * shareable/read-only. + * Response: no reply payload; completion reports the + * log/lock result. + */ + case 0x1c : /* SDK 28 Release Physical Record */ + /* + * Request: reserved byte, 6-byte NetWare file handle, + * Start Offset (Hi-Lo), and Record Length (Hi-Lo). + * Response: no reply payload; completion reports success + * or Unlock Error. The range stays in the logged table. + */ + case 0x1e : /* SDK 30 Clear Physical Record */ + /* + * Request: same layout as Release Physical Record. + * Response: no reply payload; completion reports success + * or Unlock Error. The range is removed from the logged + * table after any successful unlock. + */ { /* - * SDK: NCP 0x2222/26 Log Physical Record (old) records - * one byte range in the caller's logged data block table. - * The request is LockFlag, a 6-byte NetWare file handle, - * LockAreaStartOffset (Hi-Lo), LockAreaLen (Hi-Lo), and - * LockTimeout (Hi-Lo). LockFlag 0 logs for future use, - * 1 locks exclusive/read-write, and 3 locks - * shareable/read-only. - * - * SDK: NCP 0x2222/28 Release Physical Record releases - * one locked byte range but leaves it in the logged - * table so a later Lock Physical Record Set can relock - * it. The request carries a reserved byte, a 6-byte - * NetWare file handle, Start Offset (Hi-Lo), and Record - * Length (Hi-Lo); it returns no reply data and reports - * Unlock Error through the completion code. - * - * SDK: NCP 0x2222/30 Clear Physical Record has the same - * request layout as Release Physical Record. It releases - * the range if it is locked and removes it from the logged - * table. - * * Parser comparison: current code matches the documented * 6-byte handle position by ignoring the two high/reserved * bytes and using the low 4-byte handle. It reads offsets, @@ -5853,18 +5853,19 @@ static int handle_ncp_serv(void) } break; - case 0x1b : /* Lock Physical Record Set (old) */ - case 0x6e : { /* Lock Physical Record Set */ + case 0x1b : /* SDK 27 Lock Physical Record Set (old) */ /* - * SDK: NCP 0x2222/27 Lock Physical Record Set (old) - * and NCP 0x2222/110 Lock Physical Record Set lock all - * byte ranges logged by the calling client. - * - * SDK request: one-byte LockFlag followed by a 2-byte - * LockTimeout in 1/18 second units. The old 27 form is - * documented as Lo-Hi, while the newer 110 form is - * documented as Hi-Lo. The reply carries no data and - * completion reports success, timeout, or lock error. + * Request: LockFlag and LockTimeout (Lo-Hi) in 1/18 + * second units. + * Response: no reply payload; completion reports success, + * timeout, or lock error. + */ + case 0x6e : { /* SDK 110 Lock Physical Record Set */ + /* + * Request: LockFlag and LockTimeout (Hi-Lo) in 1/18 + * second units. + * Response: no reply payload; completion reports success, + * timeout, or lock error. * * Parser comparison: both wire functions currently share * this handler and read LockTimeout as Hi-Lo. The current @@ -5892,18 +5893,18 @@ static int handle_ncp_serv(void) } break; - case 0x1d : /* Release Physical Record Set */ - case 0x1f : { /* Clear Physical Record Set */ + case 0x1d : /* SDK 29 Release Physical Record Set */ /* - * SDK: NCP 0x2222/29 Release Physical Record Set - * releases all byte ranges locked by the calling client - * but leaves them in the client's data byte range table - * for future Lock Physical Record Set calls. - * - * SDK: NCP 0x2222/31 Clear Physical Record Set releases - * all locked ranges and clears the caller's data byte - * range table. Both requests contain a one-byte LockFlags - * field and have no reply data. + * Request: one-byte LockFlags. + * Response: no reply payload; completion reports the + * release result. Logged ranges are retained for future + * Lock Physical Record Set calls. + */ + case 0x1f : { /* SDK 31 Clear Physical Record Set */ + /* + * Request: one-byte LockFlags. + * Response: no reply payload; completion reports the + * clear result. Logged ranges are removed after unlock. * * Parser comparison: current code intentionally ignores * LockFlags for both set operations and selects release or