174 lines
9.2 KiB
Markdown
174 lines
9.2 KiB
Markdown
# DSView as an embedded Windows instrument panel
|
|
|
|
Upstream: https://github.com/DreamSourceLab/DSView, revision `2e9e2c8e`.
|
|
The GPL-3.0-or-later application and its private Qt 5/Python runtime stay in
|
|
a separate process. `setgui-host.patch` adds the Windows host protocol and
|
|
fixes the missing Windows CMake inputs. No DSView DLL is loaded into Qt 6.
|
|
|
|
`python/logic_analyzer/dsview_host.py` contains the reusable environment,
|
|
process/window ownership and close-message helpers. The consuming GUI owns
|
|
the stylesheet, window surface and lifecycle.
|
|
|
|
## Build
|
|
|
|
MSYS2 UCRT64 packages (install with `pacman -S --needed`):
|
|
|
|
```text
|
|
mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-cmake
|
|
mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-pkgconf
|
|
mingw-w64-ucrt-x86_64-qt5-base mingw-w64-ucrt-x86_64-qt5-svg
|
|
mingw-w64-ucrt-x86_64-qt5-winextras mingw-w64-ucrt-x86_64-glib2
|
|
mingw-w64-ucrt-x86_64-libusb mingw-w64-ucrt-x86_64-fftw
|
|
mingw-w64-ucrt-x86_64-boost mingw-w64-ucrt-x86_64-python
|
|
```
|
|
|
|
```powershell
|
|
python tools/dsview/build.py --source C:/path/to/DSView --output C:/path/to/runtime --msys-root C:/msys64
|
|
```
|
|
|
|
The builder checks the revision, applies the patch only after `git apply
|
|
--check`, and accepts an already applied patch. It never resets the source
|
|
checkout. Close the built DSView before rebuilding.
|
|
|
|
Successful builds write `host-build.json`, recording the recipe digest (patch,
|
|
packager, adapters and shared cores) and the native EXE digest. Consumers can
|
|
call `runtime_is_current(output)` before packaging to detect an old component
|
|
even if the host-protocol version is unchanged. SETGUI's normal EXE builder
|
|
automatically rebuilds an installed stale runtime and refuses to package it if
|
|
the update fails. A runtime built before this stamp was added is rebuilt once.
|
|
|
|
## Host protocol 1
|
|
|
|
- Create a native child surface owned by the host process.
|
|
- Start `DSView.exe --embed-parent <decimal HWND>` with its private runtime
|
|
as working directory and a sanitized environment.
|
|
- `DSVIEW_HOST_STYLE` points to the UTF-8 Qt stylesheet; `DSVIEW_CAPTURE_DIR`
|
|
supplies the initial open/save/export directory.
|
|
- Wait for `DSVIEW_READY <HWND>` on stdout, then validate both the window PID
|
|
and its parent before accepting it.
|
|
- The child fits the surface, inherits visibility, and exits if the parent
|
|
window disappears. It uses separate settings under `SET/SETGUI-DSView`.
|
|
- Write `CLOSE\n` to the child's stdin to close normally. Keep the host
|
|
alive while DSView's save dialog is open. Forced termination is only a
|
|
fallback for host shutdown or a failed start.
|
|
- Write `ADD_DECODER <id>\n` to open the normal decoder configuration dialog.
|
|
The host must be ready, in digital mode and not capturing. Stacked decoders
|
|
automatically include the matching UART/CAN base decoder.
|
|
- New hosts announce `DSVIEW_CAPABILITIES OPEN_FILE` after the ready message.
|
|
`OPEN_FILE <base64 UTF-8 path>\n` opens a DSL recording without restarting
|
|
the child. It returns `DSVIEW_FILE_RESULT ok|busy|save|error`. A capture,
|
|
save operation or modal dialog prevents replacement. Unsaved hardware data
|
|
retains the normal save prompt.
|
|
- In embedded mode File в†’ Open accepts CSV and emits
|
|
`DSVIEW_IMPORT_CSV <base64 UTF-8 path>` for conversion by SETGUI. The shared
|
|
`python/logic_analyzer/csv_import.py` streams CSV into temporary DSL v3
|
|
blocks in two passes, with progress/cancellation and bounded memory.
|
|
Times are read as decimal picoseconds; front-to-front intervals are exact.
|
|
The initial state may extend by less than one sample to align the grid;
|
|
the final state pads to 64 samples. Original offset metadata is retained.
|
|
- Embedded mode disables Qt's quit-on-last-window policy: the child is a
|
|
`Qt::Tool`, so accepting/rejecting a modal dialog must not quit the process.
|
|
- `--host-version` returns `DSView host protocol 1`. An optional
|
|
`DSVIEW_HOST_SCREENSHOT` environment variable saves one render artifact
|
|
after startup for native integration tests.
|
|
|
|
Tested SDK: GCC 16.2, Qt 5.15.19, Python 3.14.7, Windows x64. This runtime
|
|
requires Windows 10/11; it does not add Windows 7 support.
|
|
|
|
## SET decoders
|
|
|
|
`decoders/` contains the sigrok front ends for `gate_driver_timing` (1SP0635 /
|
|
1SD536F2), `set_uart` (SET v1/v2, ProtoCAN bridge), `set_can` (ProtoCAN, SET v2,
|
|
Balsam), and `pm35_uart` (TMS320F28335 MODBUS 03/06).
|
|
Their parsing cores are maintained only in `python/logic_analyzer/decoders`.
|
|
The builder copies those files verbatim to `decoders/common/setgui_decoders`
|
|
inside the runtime. No GUI imports or external Python installation are needed.
|
|
The adapters originate from `DSLogic_Logic_2/dslogic_script/dsview_decoders`.
|
|
|
|
IGBT offers `ORPHAN minimum pulse width (ns, 0 = off)` for all profiles.
|
|
Only uncorrelated pulses strictly shorter than this duration are omitted from
|
|
annotations; zero preserves the original behavior. ACK measurements/errors,
|
|
FAULT and lone edges with unknown pulse duration remain visible. This does
|
|
not modify the captured signal or debounce Vin1/Vstat.
|
|
|
|
The independent **Transistor pair** decoder measures mintime, OFF time,
|
|
deadtime in both directions, overlap, frequency and duty. It requires only
|
|
Vin1/Vin2. **IGBT 1SP/1SD** retains Vin1/Vstat ACK and full-cycle checks.
|
|
See [pair settings](decoders/transistor_pair/README.md) and
|
|
[driver settings](decoders/gate_driver_timing/README.md).
|
|
|
|
Run `python -m unittest discover -s tools/dsview/tests` for packet, CRC,
|
|
segmentation, timing-profile and sigrok API boundary tests. SETGUI's
|
|
`--check-dsview` sets `DSVIEW_HOST_CHECK` to a report file and exercises native
|
|
decoder dialogs, single/all removal with Yes/No, stacking and child lifetime.
|
|
The check saves decoder dialog screenshots alongside the report.
|
|
|
|
## Annotation search
|
|
|
|
The patch searches every enabled result column of the selected decoder and
|
|
every annotation label, including short waveform labels such as `ORPHAN`.
|
|
Matching is case insensitive; warning columns are enabled by default. Explicitly
|
|
hidden columns remain excluded until enabled in Decoding Results settings.
|
|
Enter (including the Windows popup editor), the magnifier and the next arrow
|
|
navigate forward; the previous arrow navigates backward. Matches are counted
|
|
per annotation, ordered by sample time, and wrap around. Tooltips show all
|
|
label variants. A nonempty query displays a compact match-only table: one
|
|
annotation per row, with its row title and matching label. Clearing the query
|
|
restores the source table; a query with no matches displays an empty list.
|
|
Click/arrow navigation maps each result back to the original annotation.
|
|
Numeric `AA-BB-CC` sequences are still supported; other hyphens
|
|
are literal. Search runs in short GUI-thread timer steps, invalidates indices
|
|
on model resets, and refreshes when decoding reaches 100 percent.
|
|
|
|
After rebuilding, verify with an IGBT recording containing an uncorrelated
|
|
Vstat pulse: search `ORPHAN`, `orphan`, and `Unexpected Vstat`; each should
|
|
select the same warning and show its waveform region. Also check Enter from
|
|
the popup editor, magnifier/arrow wraparound, a missing query, clearing/changing
|
|
the query during a long search, changing columns/decoders, and removing the
|
|
decoder while searching. Confirm numeric sequences and literal `CAN-FD` labels
|
|
still work. Source syntax checks do not replace this native GUI check.
|
|
|
|
## Install analyzers into standalone DSView (Windows)
|
|
|
|
The adapters in `tools/dsview/decoders` and portable cores in
|
|
`python/logic_analyzer/decoders` are shared with the embedded build.
|
|
No analyzer implementation is maintained in the consuming GUI.
|
|
|
|
```powershell
|
|
.\tools\dsview\install_decoders.ps1 -DsViewPath 'C:\Program Files\DSView'
|
|
```
|
|
|
|
Close DSView first. An elevated PowerShell is needed if the installation
|
|
folder is protected. Add `-CheckOnly` to validate source files and the target
|
|
layout without writing. Python/MSYS2 and a DSView rebuild are not required.
|
|
The target must contain DSView.exe and decoders/common.
|
|
|
|
Installs gate_driver_timing, set_uart, set_can and pm35_uart, with unchanged
|
|
cores under decoders/common/setgui_decoders. Existing unrelated files are
|
|
preserved. Replaced files are backed up under set-decoder-backups next to
|
|
DSView.exe; failed copies trigger rollback. Keep backups for manual recovery.
|
|
To restore, close DSView and copy the backup contents over decoders.
|
|
|
|
Restart DSView, add the UART or CAN base decoder and stack SET/PM35 on top.
|
|
Gate timing consumes logic channels directly. This installs decoders only;
|
|
it does not install the SETGUI host patch, menus or CSV import.
|
|
|
|
Installer tests run under Windows PowerShell against temporary targets and
|
|
check isolated imports, updates, backups, copy-failure rollback and validation:
|
|
|
|
```powershell
|
|
python -m unittest discover -s tools/dsview/tests -p test_install_decoders.py -v
|
|
```
|
|
|
|
## Decoder panel and selector
|
|
|
|
Embedded DSView does not restore standalone toolbar/dock layout. The Decoders
|
|
panel can extend to the top row of the DSView controls; its upper splitter
|
|
still allows reducing its height. SETGUI's own folder and tab rows remain
|
|
outside the native component.
|
|
|
|
The decoder selector starts with **Пользовательские**: IGBT 1SP/1SD,
|
|
Transistor pair, SET UART, SET CAN and PM35 UART. **Стандартные** contains the remaining
|
|
decoders. Search matches names and IDs in both sections and hides empty
|
|
section headings. The changes are packaged in `decoder-panel.patch`.
|