Skip to content

Add dslcap, a headless capture command-line tool - #920

Open
nullifyr wants to merge 1 commit into
DreamSourceLab:masterfrom
LANScapes:up/dslcap
Open

Add dslcap, a headless capture command-line tool#920
nullifyr wants to merge 1 commit into
DreamSourceLab:masterfrom
LANScapes:up/dslcap

Conversation

@nullifyr

@nullifyr nullifyr commented Oct 1, 2026 •
edited
Loading

Copy link
Copy Markdown

dslcap is a small command-line tool that runs a DSLogic capture through libsigrok4DSL without the GUI, for scripts, test benches and automation:

dslcap --list
dslcap --channels 0,1 --samplerate 10000000 --samples 1000000 \
       [--vth 1.6] [--mode buffer|stream] [--trigger CH[:R|F|C|1|0]] \
       [--trigpos PERCENT] [--timeout SEC] [--res DIR] --out /path/base

It writes <base>.bin (each enabled channel's samples packed LSB-first) and prints one JSON object describing the capture. Every failure prints a JSON object with an "error" key and exits non-zero (1 runtime/I/O, 2 invalid argument or unavailable setting, 3 failed capture).

Design points:

  • All options are validated before the library is initialised.
  • Only samplerates the device reports are accepted, and a channel mode that supports the rate and channel count is selected.
  • Every configuration call is checked and the samplerate, sample limit and threshold are read back. The threshold voltage is only set on devices that list SR_CONF_VTH.
  • A capture that times out, ends by error or detach, reports a packet/data error, overflows, or returns fewer samples than requested is reported as failed and publishes no file.
  • Data is spooled to disk during the capture (long and streaming captures need not fit in memory) and published atomically without replacing an existing file.
  • Library callbacks touch shared state under a mutex; the capture waits for the collect task's final event against a monotonic deadline.
  • The target is built and installed on non-Windows platforms only (it uses POSIX file and path calls); Windows builds are unchanged.

tools/dslcap/test_spool.c checks argument validation, packet/event status handling, the de-interleave path and large-file offsets without hardware; its header has macOS and Linux build commands.

Tested on a DSLogic Plus (macOS, Apple silicon): --list; buffer capture of 2 channels at 1 MHz and stream capture of 4 channels at 10 MHz (files of exactly the expected size); explicit --vth 1.2 applied and read back; a rising-edge trigger that never fired timed out with exit 3 and no file.

Also: builds on macOS (Apple Clang, Qt 6) and Ubuntu 24.04 on aarch64 and x86_64 (GCC 13, Qt 5); the standalone test passes on both; a mocked-library harness covering normal, failed, timed-out, legacy-threshold and malformed-argument captures passes, including under ThreadSanitizer. I have not run it on Windows (excluded) or on a 32-bit platform.

🤖 Generated with Claude Code

https://claude.ai/code/session_01S6AB69CNtvrecQVn1nyvL1

nullifyr added a commit to LANScapes/logic-analyze that referenced this pull request Oct 1, 2026
@nullifyr @claude
Take dslcap and the maximized start from the upstream pull requests
8915a8e 
The same code as DreamSourceLab/DSView#920 and #918:
- dslcap: strict argument validation, every configuration call checked
  (threshold voltage only where the device has one), failed captures
  exit 3 and publish nothing, mutex-guarded callback state, monotonic
  deadline, 64-bit file offsets, checked stdout, install rule, built on
  non-Windows only, with its own link list.
- macOS: a window that starts maximized is shown at its saved normal
  region and then zoomed, so un-maximizing returns it there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S6AB69CNtvrecQVn1nyvL1
@nullifyr @claude
Add dslcap, a headless capture command-line tool
d54bec2 
dslcap drives a DSLogic through libsigrok4DSL without the GUI, for
scripted and automated captures:

  dslcap --list
  dslcap --channels 0,1 --samplerate 10000000 --samples 1000000 \
         [--vth 1.6] [--mode buffer|stream] [--trigger CH[:R|F|C|1|0]] \
         [--trigpos PERCENT] [--timeout SEC] [--res DIR] --out /path/base

It writes <base>.bin (each enabled channel's samples packed LSB-first)
and prints one JSON object describing the capture on stdout. Every
failure prints a JSON object with an "error" key and exits non-zero
(1 runtime/I/O error, 2 invalid argument or unavailable setting,
3 failed capture).

- Validates all options before the library is initialised: whole-string
  numeric parses with range checks, finite --vth (0-5 V) and --timeout,
  positive rate and sample count, channel lists of plain indexes without
  duplicates, --mode exactly buffer or stream, --trigpos 0-100 (and
  small enough that its share of the sample limit fits the driver's
  32-bit trigger position), and a trigger type of exactly one of
  R F C 1 0.
- Accepts only the samplerates the device reports, and picks a channel
  mode that supports the requested rate and channel count; triggers must
  be on an enabled channel.
- Checks every configuration call (operation mode, threshold voltage,
  samplerate, sample limit, trigger) and reads back the samplerate,
  sample limit and threshold, reporting the values the device holds.
  The threshold voltage is set only on devices that list SR_CONF_VTH;
  on older models with only the 3.3 V / 5 V threshold setting, "vth" is
  reported as null and an explicit --vth is rejected.
- A failure to list devices is reported as an error, not as an empty
  device list.
- Library callbacks update shared state under a mutex. The capture
  waits, against a monotonic deadline, for the collect task's final
  end event rather than SR_DF_END or the device-stopped event.
- A capture that timed out, ended by error or detach, reported a packet
  or logic data error, overflowed, or returned fewer samples than
  requested is reported as failed and no <base>.bin is created.
- Spools the logic data to disk while capturing, so long or streaming
  captures do not have to fit in memory, then de-interleaves it in
  bounded chunks; the target is built with 64-bit file offsets and
  output offsets are range-checked.
- Checks every write, including the JSON on stdout, and publishes the
  output file atomically without replacing an existing one; the output
  name is allocated to full length.
- Finds the firmware next to the executable (build tree, app bundle or
  installed ../share/DSView/res), in the configured install prefix, or
  in --res / $DSLCAP_RES.
- Built and installed (to the configured bindir) on non-Windows
  platforms, with its own link list including libm; Windows builds are
  unchanged.

tools/dslcap/test_spool.c is a standalone check, needing no hardware,
of argument validation, packet/event status handling, the de-interleave
path and large-file offsets; its header gives macOS and Linux build
commands.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S6AB69CNtvrecQVn1nyvL1
nullifyr added a commit to LANScapes/logic-analyze that referenced this pull request Oct 1, 2026
@nullifyr @claude
dslcap: keep the trigger position within the driver's 32-bit range
8c79776 
Same change as DreamSourceLab/DSView#920: reject a --trigpos whose share
of the sample limit would overflow the driver's 32-bit trigger position.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S6AB69CNtvrecQVn1nyvL1
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@nullifyr