docs: document logical record sync request layouts

TODO.md

@@ -116,6 +116,13 @@ Current status:
 - `NCP 0x06 Release File Set` and `NCP 0x08 Clear File 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.
+- `NCP 0x09 Log Logical Record (old)`, `NCP 0x0a Lock Logical Record Set
+  (old)`, `NCP 0x0b Clear Logical Record`, and `NCP 0x0c Release Logical
+  Record` have inline SDK request-layout documentation now.
+- `NCP 0x0d Release Logical Record Set` and `NCP 0x0e Clear Logical Record
+  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.
 
 Follow-up:
 
@@ -129,6 +136,11 @@ Follow-up:
   documented Lo-Hi after direct requester evidence is available.
 - Decide whether `0x06` and `0x08` should consume or ignore the documented
   `LockFlag` byte after direct requester evidence is available.
+- Decide whether `0x0a` should keep the current big-endian timeout read or
+  special-case the documented old Lo-Hi byte order after direct requester
+  evidence is available.
+- Decide whether `0x0d` and `0x0e` should consume or ignore the documented
+  `LockFlag` byte after direct requester evidence is available.
 - Verify the implemented file/logical-record/physical-record calls against the
   Novell SDK request/reply layouts and a real DOS requester or direct test
   caller.

src/nwconn.c

@@ -2941,6 +2941,27 @@ static int handle_ncp_serv(void)
       break;
       
       case 0x9 :  { /* Log Logical Record */
+        /*
+         * NCP 0x2222/09 Log Logical Record (old) logs one synchronization
+         * string in the caller's logical-record table.  The string can be
+         * up to 128 characters long.
+         *
+         * SDK request layout:
+         *
+         *   byte  LockFlag: bit 0 asks the server to lock immediately
+         *   word  LockTimeout, in units of 1/18 second
+         *   byte  SynchNameLen
+         *   bytes SynchName
+         *
+         * SDK reply: no reply data.
+         * SDK completion: 0x00 success, 0x96 server out of memory,
+         * 0xfe timeout, 0xff lock error.
+         *
+         * The current INPUT layout matches the documented old request
+         * header offsets: FunctionCode at offset 6, LockFlag at offset 7,
+         * LockTimeout at offset 8, SynchNameLen at offset 10, and
+         * SynchName at offset 11.
+         */
         struct INPUT {
           uint8   header[7];       /* Requestheader      */
           uint8   lock_flag;       /* 0 = log            */ 
@@ -2960,6 +2981,24 @@ static int handle_ncp_serv(void)
       break;
 
       case 0xa :  { /* Log Logical Record Set */
+        /*
+         * NCP 0x2222/10 Lock Logical Record Set (old) locks all logical
+         * records previously logged by this client.  This direct old call
+         * is the compatibility form of NCP 0x2222/108.
+         *
+         * SDK request layout:
+         *
+         *   byte  LockFlag
+         *   word  LockTimeout, in units of 1/18 second
+         *
+         * SDK reply: no reply data.
+         * SDK completion: 0x00 success, 0xfe timeout, 0xff lock error.
+         *
+         * The old SDK page documents LockTimeout as word (Lo-Hi), while
+         * the newer 0x6c/108 call documents word (Hi-Lo).  The existing
+         * code reads the field with GET_BE16().  This comment records the
+         * parser difference only; endpoint behaviour is unchanged here.
+         */
         struct INPUT {
           uint8   header[7];       /* Requestheader       */
           uint8   lock_flag;       /* 0 = log             */
@@ -2982,10 +3021,14 @@ static int handle_ncp_serv(void)
          * 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.  The request
-         * is a one-byte Synch Name Length followed by the Synch Name
-         * (up to 128 bytes), returns no reply data, and reports success or
-         * Unlock Error through the completion code.
+         * 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.
          *
          * Important semantic difference: Release Logical Record leaves the
          * string in the caller's synchronization string table so a later
@@ -3010,6 +3053,24 @@ static int handle_ncp_serv(void)
 
       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.
+         */
         int result = share_handle_lock_sets(
                                       2,   /* Logical Record Set */
                                (function==0xe)