ZZZ Digital Lab

Back to WaitLens

Follow a QNX 8.0 message from SEND to REPLY with WaitLens

Authored: 2026-11-13, during the hackathon submission period. Status: draft awaiting real SDP/target output.

Build a small native QNX workload, collect two observations, and explain why a client moved from waiting for receipt to waiting for a reply. You will finish with a local HTML comparison, original captures, a build receipt and a checked evidence bundle. You do not need target hardware or an IDE for this exercise.

This English step-by-step codelab targets the Best Codelab/Tutorial bonus, which requires an eligible main entry and a tutorial URL in the designated field. The rules specify no mandatory article template. This draft is not ready to publish while output slots remain. The bonus is $3,500; completing the exercise does not guarantee it.

1. Before you start — 5 minutes

Audience: a developer comfortable running Python and reading basic C. Allow 45–60 minutes after toolchain, licence and VM setup. You need:

Keep qconn confined to the owner's private development VM: its documented remote execution privileges are unsuitable for a deployed customer system. See the qconn reference. No step changes the host proxy, VPN, DNS, firewall or VM network configuration. No SDK, key, licensed image or target executable belongs in the public repository.

Success means an actual QNX build, completed exchange, matching client TID and server PID across both states, matching binary hashes and a generated report. Caller-provided provenance and a successful consistency check cannot authenticate an operating system independently. Preserve original records and screen footage.

2. Warm up on the host — 5 minutes

The following commands are WaitLens commands, not QNX utilities:

python -m waitlens analyze fixtures/public-doc.txt --provenance documentation-excerpt
python -m waitlens compare fixtures/send.txt fixtures/reply.txt --provenance synthetic --out build/practice
python -m waitlens analyze fixtures/cycle.txt --provenance synthetic --out build/cycle

Open build/practice.html locally. The original synthetic example contains one changed client, PID:TID 101:1, moving SEND to REPLY with destination PID 100. These numbers belong to the fixture, not a QNX run. Read the observation banner, then the before/after rows and source line columns. Expand All parsed threads. The documentation excerpt and synthetic files have separate provenance; see fixtures/README.md.

Open build/cycle.html. Explain why its RECEIVE row contributes no edge even though it has a numeric blocked value. Keep your answer for the knowledge check.

3. Understand the native experiment — 5 minutes

QNX messages use channels and connections. A channel belongs to a process, and receiving threads can share it; a client connection does not choose a particular server worker. See channels and connections.

Client thread                 Server process / channel
    | --- MsgSend ----------> |  six-second visible delay before receive
    |       SEND              |
    |                         |  MsgReceive accepts request
    |       REPLY             |  six-second visible delay before reply
    | <--- reply bytes ------ |  MsgReply
    | resumes                 |

If no receiving thread is ready, MsgSend blocks the client in SEND. After MsgReceive accepts the request, that client waits in REPLY until MsgReply releases it. A server blocked in RECEIVE is awaiting a message on a local channel; its blocked number is a channel ID, not the next process in a chain.

Read target/waitlens_probe.c. These are the key calls and official references:

Code Purpose and QNX 8.0 reference
ChannelCreate(0) / ChannelDestroy Create and remove the server channel: create, destroy
fork() Create the client process: fork
ConnectAttach(0, server, chid, _NTO_SIDE_CHANNEL, 0) / ConnectDetach Connect to the server channel, then detach: attach, detach
TimerTimeout(...) immediately before a blocking call Bound SEND/REPLY/RECEIVE waits: TimerTimeout
alarm(...), sleep(6), waitpid(...) Bound process failures, expose phases and reap the child: alarm, sleep, waitpid

The phase delays are a teaching device, not a latency benchmark. Scheduling may cause a sample to miss a phase. Host execution is single-process; the workload's QNX-native fork runs on the target, not under the restricted Windows token.

4. Initialize the real SDP and VM — 10 minutes after installation

Follow the official command-line Quick Start to initialize the installed SDK. In Windows Command Prompt, with your actual installation directory:

call "C:\qnx800\qnxsdp-env.bat"

For an owner-managed Ubuntu host instead:

. /path/to/qnx800/qnxsdp-env.sh

Use an already prepared VM, or create one once in a fresh project directory:

mkdir build/vm-vbox
cd build/vm-vbox
mkqnximage --type=vbox --arch=x86_64
mkqnximage --run
mkqnximage --getip
cd ../..

Use --type=vmware in its own directory for Windows/VMware, or --type=qemu in its own directory on supported Ubuntu. Generation, run and IP discovery are documented in mkqnximage. Do not reuse an unknown VM directory. The pipeline assumes this VM is running; it never creates, reconfigures, starts or shuts down virtualization software.

The owner confirms the private VM's debugger endpoint, shell location and qconn/pdebug plus devc-pty availability using the debugging setup. Default endpoint port is 8000. If this service is absent, stop and have the owner prepare it; do not substitute SSH, read keys or change security policy.

Actual installed SDP update, VM version and captured compiler version:

[[REAL OUTPUT REQUIRED: SETUP]]

5. Build, deploy and capture with one command — 10 minutes

From the project root in that initialized command window, replace the example IP and setup note with your VM's endpoint and reviewed installed version identifiers:

python scripts/post_sdp.py --target 192.168.56.101:8000 --setup-note "SDP 8.0 update <installed update>; VirtualBox <installed version>; x86-64"

On Ubuntu use python3 and record QEMU's actual version in the note. If your target shell is elsewhere, supply --target-shell /actual/path/sh. The QNX sh reference defines the shell used to execute the capture script.

The command performs these inspectable stages:

  1. Compile the original source with qcc -Vgcc_ntox86_64 -nopipe -D_QNX_SOURCE -std=c11 -Wall -Wextra -Werror. It checks the 64-bit ELF architecture and saves source/binary SHA-256 values and compiler exit code. qcc --version is captured separately. See qcc for variant selection, version and -nopipe. The source requires __QNX__ == 800: QNX manifest constants.
  2. Start ntox86_64-gdb without saved initialization or auto-loading. Its generated transfer.gdb uses target qnx, set nto-inherit-env 1, set nto-executable, set nto-cwd, file, run, upload and download. See the official QNX GDB extensions. It creates a unique /tmp/waitlens-... directory and sends only the workload and capture script. It first retrieves the target shell into the ignored local run directory and loads its ELF with file so debugger architecture/symbols match the remote control process. This private runtime copy is never published. No credential file or saved host profile is used.
  3. Use the target shell to run capture.sh. Its actual operations include:

sh uname -s > platform.txt uname -r >> platform.txt ./waitlens_probe > probe.log 2>&1 & sleep 2 pidin -p waitlens_probe -F "%a %b %60n %p %J %B" > send.txt sleep 6 pidin -p waitlens_probe -F "%a %b %60n %p %J %B" > reply.txt

The script also waits for successful completion, cleans up on failure and writes a per-run completion nonce. References: uname, sleep utility, pidin, shell redirection, jobs, wait and traps, mkdir, chmod, kill. 4. Retrieve original text files, the target copy of the workload and the completion nonce. Verify them, generate comparison HTML/JSON, and fill these output slots in a new tutorial-filled.md. The draft and project submission status remain unchanged. Failed runs retain their artifacts and stop with exit code 2.

Actual build receipt:

[[REAL OUTPUT REQUIRED: BUILD]]

Actual target platform (two original lines from platform.txt):

[[REAL OUTPUT REQUIRED: PLATFORM]]

Actual probe completion and process identities:

[[REAL OUTPUT REQUIRED: PROBE]]

Actual first observation, copied without editing from send.txt:

[[REAL OUTPUT REQUIRED: SEND]]

Actual second observation, copied without editing from reply.txt:

[[REAL OUTPUT REQUIRED: REPLY]]

Read the PIDs from your own log. They need not match the fixture numbers. Verify that a client TID appears in both samples, first SEND then REPLY to that logged server PID, and that the server is present. A completed log alone is insufficient.

6. Check and interpret — 10 minutes

The pipeline prints its new evidence/local/run-... directory. Call it RUN below; substitute that printed path. To repeat the host checks independently:

python scripts/check_evidence.py --build-dir RUN/build --capture-dir RUN/capture --out RUN/recheck.json
python -m waitlens compare RUN/capture/send.txt RUN/capture/reply.txt --provenance target-capture --out RUN/recomparison

These are project commands; the checks run on the host. Open RUN/comparison.html. The checker requires current source/build hashes, the same returned executable, QNX 8.0 platform text, a completed exchange and a shared client TID in both phases. This is a local consistency gate, not independent attestation.

Actual checker output:

[[REAL OUTPUT REQUIRED: CHECK]]

Actual observed changes from the captured comparison:

[[REAL OUTPUT REQUIRED: COMPARISON]]

Use the report in this order:

  1. Read What this observation shows. A SEND-to-REPLY observation means the request was accepted between observations if the process identity is stable. It does not establish how long either state lasted.
  2. Find the client's row under Observed changes. Follow its before/after source line numbers back to the original files. Confirm the destination process stayed the same; do not infer a particular destination worker thread.
  3. Inspect destination coverage and All parsed threads. An absent server may reflect filtering, permissions or exit. A capture is incomplete for that edge; absence is not a diagnosis of a crashed or deadlocked service.
  4. Read cycle candidates cautiously. Another server thread may still be able to progress. Collection visits processes in turn and is not atomic, as described in pidin's implementation notes. PID/TID reuse can make two separate lifetimes look like a transition.

For a suspected persistent problem, collect an appropriate event trace using the QNX System Profiler. Two sampled states cannot prove continuous blocking, deadlock or real-time latency.

7. Troubleshooting and recovery

Symptom Meaning and action
QNX_HOST is unset, or missing compiler/debugger Initialize the installed SDP in this window; confirm x86-64 tools using the installation guide. Do not install mock headers or remove the QNX guard.
Compiler/licensing diagnostic Stop; the owner resolves installation or activation. The failed build receipt replaces success for that run. Keep the compiler diagnostic local.
Debugger connection timeout Check the existing VM console and owner-provided endpoint. Confirm qconn/pdebug and devc-pty setup. The pipeline never falls back to SSH/login. Rerun only after resolving setup.
Remote shell missing Set --target-shell to the shell's actual absolute target path. Inspect transport.log locally.
Unsupported row, duplicate thread, unknown state Read the named input and line. Capture one non-verbose invocation with the six-column format above; do not concatenate loop output or use pidin threads as a substitute.
Empty/permission-denied capture An empty file is not proof of a healthy system. Have the owner provide an appropriately authorized target session; do not change security policies automatically.
Expected SEND/REPLY pair absent A visible phase was missed or capture coverage is insufficient. Rerun into a fresh directory. Never edit raw captures to satisfy the checker.
Source or returned-binary hash mismatch Old artifacts or a changed build. Rebuild and recapture together with the one command. Do not combine receipts from different runs.
Tutorial slot contract changed Update the filler/template together and rerun the host tests. A failed fill cannot claim a completed tutorial.

The host parser accepts UTF-8 (including BOM), CRLF and LF. GBK or UTF-16 files must be deliberately re-exported as UTF-8; preserve originals. Use a single host test process: python -m unittest discover -s tests -v.

8. Knowledge check and extension — 5 minutes

  1. What does RECEIVE's blocked value identify? A local channel, so it creates no process-to-process edge.
  2. Does a cycle prove deadlock? No. Multiple workers and non-atomic observations permit progress even when the process graph contains a cycle.
  3. Can these samples measure wait duration? No. They show two observations; use event timestamps and the relevant trace to investigate timing.
  4. What if the client PID was reused? Identity may be ambiguous. Preserve the workload log and acquisition context; do not assert one continuous wait.

Optional extension: change only the workload's visible-phase delays, rebuild and recapture, and explain which state the new sampling schedule misses. Preserve a new receipt for that source. Alternatively, use original synthetic rows to model a second server worker and a missing destination, then explain the uncertainty. Neither exercise establishes a performance improvement.

9. Finish and prepare the public tutorial

Keep the checked run's originals privately. Review tutorial-filled.md and comparison.html, reproduce these instructions on the real setup, and record continuous footage of the target capture and corresponding report. Verify the installed setup note against the owner's version record. The pipeline inserts outputs; it cannot assess screenshot quality, eligibility or publication rights.

For public material, make a reviewed copy containing original project code, appropriate text captures, sanitized version notes, receipts, checksums and the finished article. Review process names, paths and logs for private information. Exclude executables, runtime images, SDK files and keys. Preserve original hashes and disclose any redactions; recheck sanitized data without changing state/PID semantics. Refer to docs/human-steps.md for final publication steps.

After the owner publishes the reviewed article at a readable URL, place that URL in the tutorial bonus field alongside an eligible entry. The main video must be public on YouTube and under three minutes, as required by the official submission rules. No publication is performed by the local workflow.