Add DSLogic capture, signal conversion and DSView decoders
This commit is contained in:
173
tools/dsview/README.md
Normal file
173
tools/dsview/README.md
Normal file
@@ -0,0 +1,173 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user