MAC + HDLC: practical docs, on-demand HTTP server case study, and RE tooling - #11
Open
retrogcom wants to merge 3 commits into
Open
MAC + HDLC: practical docs, on-demand HTTP server case study, and RE tooling#11retrogcom wants to merge 3 commits into
retrogcom wants to merge 3 commits into
Conversation
… tooling Empirically-verified docs from building/running real MAC programs (an HTTP server over HDLC) on SINTRAN III VSX/500 L under nd100x. Additive; follows the repo's evidence-tag and See-Also conventions; cross-linked throughout. New docs: - Developer/Languages/System/MAC-COOKBOOK.md - @MAC source encoding, )9ASSM->NRL build, addressing deref ladder, P-relative/literal-pool rules, monitor-call skip-on-success ABI + verified MON table, a "File system access from MAC" section, gotcha catalogue, debugging methodology. - SINTRAN/Devices/HDLC/implementation/Buffer-Pool-and-Emulator-Usage.md - buffer-pool setup (CHANGE-BUFFER-SIZE via SINTRAN-SERVICE + RESTART-SYSTEM, per COSMOS guide Example 61), D-I-W/D-O-W sizing and status=4, the receive-arm-size trap, running HDLC under the nd100x --hdlc tap, and the transmitter-restart-after-idle requirement (reload DCB + retrigger). - Developer/Workflow/CROSS-DEVELOPMENT-WITH-ND100X.md - host-driven build loop (encode -> stage into SMD image -> drive @MAC/@NRL over telnet). - Developer/Case-Studies/HTTP-Server-over-HDLC.md (+ README) - end-to-end worked example tying the above together. - Developer/Reverse-Engineering/ (README + Disassembling-a-PROG.md + ND-100-Instruction-Decoding.md) - disassembly workflow + the word->mnemonic decode reference, confidence-tagged [V]/[B]. - scripts/nd100_disasm.py + scripts/nd100_brf.py - the disassembler the RE docs describe. Fix to existing doc: - MAC-DEVELOPER-GUIDE.md Hello World used MONITOR 43 / MONITOR 3; per the repo's own MON reference those are CloseFile and the No-Wait switch. Corrected to OutString (MON 162B) and ExitFromProgram (MON 0). All technical claims cross-checked against the repo's own MON reference, ND-60.096 §2.3 (instruction repertoire incl. JAF=non-zero), and the COSMOS Operator Guide (CHANGE-BUFFER-SIZE Example 61). Index/cross-link updates: System README, MAC-DEVELOPER-GUIDE See Also, HDLC README + raw-guide See Also, Workflow README, Developer README doc map. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The request/response server (not just broadcast) now works end-to-end on nd100x: a browser fetches the page byte-exact, with the ND reading one disk block on demand instead of caching every file. Update the case study and the buffer-pool RX->TX section with the verified recipe — transmit the just-received DCB keeping its RX-set size, drain each send with an output-side FRCV, pace requests ~120 ms, MON 117 block reads per request — and link the XSSDATA transmit deep-dive for the underlying DMA descriptor (LKEY/LBYTC). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Resolved two open items from the on-demand server work: - MON 76 SetBlockSize is register-based on ND-100 (T=file number, A=block size in WORDS, skip-on-success) -- not a parameter list. The earlier param-list form returned error 133. With it fixed, MON 117 reads one chunk per call so the server needs only a single ~60-word chunk buffer (no page cache). - The request pacing floor is ~2 ms, not ~120 ms; ~10 ms is a safe margin (~0.1 s/page). Keeping 2+ RX DCBs armed (double-buffering, as XMSG does) removes pacing entirely -- a fast follow-up frame is dropped only because no empty RX DCB is loaded during the drain/re-arm window. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three commits adding empirically-verified MAC and HDLC documentation, built from getting a real HTTP server running over HDLC on SINTRAN III VSX/500 L under nd100x:
MAC cookbook + cross-dev workflow + RE tooling —
MAC-COOKBOOK.mdcovers source encoding, the)9ASSM→ NRL build, the addressing-deref ladder, P-relative + literal-pool rules, and the monitor-call skip-on-success ABI with a verified MON table.Buffer-Pool-and-Emulator-Usage.mddocuments the HDLC buffer-pool setup (CHANGE-BUFFER-SIZEper COSMOS guide Example 61), D-I-W/D-O-W sizing, the receive-arm-size trap, running under--hdlc, and the transmitter-restart-after-idle requirement.CROSS-DEVELOPMENT-WITH-ND100X.mddocuments the host-driven build loop. AddsDeveloper/Reverse-Engineering/with the disassembly workflow + word→mnemonic decode reference, plus thescripts/nd100_disasm.py+scripts/nd100_brf.pyit references. Includes a small fix toMAC-DEVELOPER-GUIDE.mdHello World (was calling MON 43/3 — CloseFile/No-Wait — now correctly uses MON 162B / MON 0).End-to-end case study —
Developer/Case-Studies/HTTP-Server-over-HDLC.mdties the cookbook + buffer-pool docs into a worked example: request/response server (not broadcast), browser fetches byte-exact, ND reads one disk block on demand instead of caching, transmit reuses the just-received DCB at its RX-set size, drain each send with an output-side FRCV, MON 117 block reads per request.MON 76 ABI + pacing correction — Resolved two follow-ups:
MON 76 SetBlockSizeis register-based (T=file, A=words, skip-on-success), not a parameter list (the earlier form returned error 133); with it fixed, MON 117 reads one chunk per call so the server needs only one ~60-word buffer (no page cache). The request pacing floor is ~2 ms not ~120 ms; ~10 ms is a safe margin (~0.1 s/page). Note that keeping 2+ RX DCBs armed (XMSG-style double-buffering) removes pacing entirely.All technical claims cross-checked against the repo's own MON reference, ND-60.096 §2.3, and the COSMOS Operator Guide. Index/cross-link updates throughout: System README, MAC-DEVELOPER-GUIDE See Also, HDLC README + raw-guide See Also, Workflow README, Developer README doc map. Additive; follows the repo's evidence-tag and See-Also conventions.
Test plan
MAC-COOKBOOKclaims (encoding,)9ASSM, MONs) verified end-to-end by the case study program assembling, loading, and running on nd100xCHANGE-BUFFER-SIZE 1360/1361,INPUT/OUTPUT,400,Y,Yand a working request/response loopnd100_disasm.py,nd100_brf.py) exercised on the built:BRFto confirm the decode referenceMAC-DEVELOPER-GUIDEHello World fix verified by running the corrected version