release: prepare R1-8-0

README.md

@@ -2,7 +2,7 @@
 
 **ADServal** is the unified EPICS areaDetector driver for ASI pixel detectors on **Serval** — **TimePix3**, **Medipix3** ([R1-7-0](RELEASE.md)); **TimePix4** planned. It is shipped from this repository under the legacy module name **ADTimePix3** (`$(ADTIMEPIX)`, `libADTimePix`). See [documentation/NAMING.md](documentation/NAMING.md) for naming and migration.
 
-The driver provides detector configuration and control via Serval and on-IOC data processing over HTTP/JSON REST and high-rate TCP streams (raw events, images, histograms). It supports real-time preview and **image accumulation** (running sum, sum of last N frames), **Time-of-Flight (ToF) histogram** processing and accumulation, pixel masking (Binary Pixel Configuration files, rectangular/circular masks, hot-pixel tools), health and status monitoring, and integration with standard areaDetector plugins for file saving and analysis. Support is included for real detectors (single-chip, 2×2 quad, and **eight-chip / dual-SPIDR** layouts with IOC and driver hooks described in [documentation/8chip-migration.md](documentation/8chip-migration.md)) and the TimePix3 emulator. The driver is developed for Linux 64-bit (tested on Ubuntu and RHEL). Published in [DOE CODE](https://www.osti.gov/doecode/biblio/176778).
+The driver provides detector configuration and control via Serval and on-IOC data processing over HTTP/JSON REST and high-rate TCP streams (raw events, images, histograms). It supports real-time preview and **image accumulation** (running sum, sum of last N frames), **Time-of-Flight (ToF) histogram** processing and accumulation, pixel masking (Binary Pixel Configuration files, rectangular/circular masks, hot-pixel tools), health and status monitoring, and integration with standard areaDetector plugins for file saving and analysis. Established support includes single-chip and 2×2 quad detectors. The **eight-chip / dual-SPIDR** 4×2 path described in [documentation/8chip-migration.md](documentation/8chip-migration.md) is software- and emulator-qualified with the release-specific limits below. The driver is developed for Linux 64-bit (tested on Ubuntu and RHEL). Published in [DOE CODE](https://www.osti.gov/doecode/biblio/176778).
 
 Additional information:
 * [Documentation](https://areadetector.github.io/areaDetector/ADTimePix3/ADTimePix3.html)
@@ -25,18 +25,38 @@ Notes:
 * ADCore, ADSupport, and other EPICS module versions are supplied by the surrounding EPICS release configuration (`configure/RELEASE_LIBS_INCLUDE` and local overrides); this repository does not lock them independently.
 * **Preview Images**: Uses TCP streaming (jsonimage format) for preview images. GraphicsMagick HTTP method has been removed. For backward compatibility, the GraphicsMagick implementation is preserved in the `preserve/graphicsmagick-preview` branch.
 * This has only been developed/tested on ubuntu 22.04, 20.04, 18.04, RHEL 7.9, RHEL 9.6 Linux 64-bit machines.
-* Layout support in driver and OPI is most complete for **1 chip** and **2×2 quad**; **8-chip** (a 4×2 mosaic assembled from two quads) has IOC/DB/driver support documented in [documentation/8chip-migration.md](documentation/8chip-migration.md)—validate BPC/mask mapping and screens on your hardware. The single-board full-rate SpidrTurbo layout remains a distinct, unqualified mapping.
+* Layout support in driver and OPI is most complete for **1 chip** and **2×2 quad**, including their established rotation and mirror mappings. For the **8-chip** 4×2 mosaic assembled from two quads, coordinate-dependent mask/BPC comparison, PixelConfig-difference, and masked-pixel export are supported for detector orientation **UP** only and require two distinct TPX3 quad-board IDs (`41...`). This restriction does not remove general acquisition-orientation support from the established one-chip and quad paths. The single-board full-rate SpidrTurbo (`84...`) layout has a different mapping and fails closed.
 * **Serval versions**: The master branch supports both Serval 4.x.x and 3.x.x and is recommended (no need to use the 3.3.2 branch). The "dual image" issue was resolved in Serval 4.1.5; **Serval 4.1.5 remains the recommended stable version** for 4.x. R1-7-4 acquisition-lifecycle qualification also passed with **Serval 4.1.6-EXPERIMENTAL build 1760** on the TPX3 and MPX3 emulators. Serval and emulator versions must match. Data replay has been tested and is currently supported only with older Serval (3.3.2). Serval 2.x.y is in a separate branch and is not under active development.
 * The driver has been developed using the TimePix3 Emulator and real detectors (quad-chip and single-chip).
 
+R1-8-0 qualification boundary
+-----------------------------
+
+R1-8-0 is a software- and emulator-qualified release. It does not make a new
+physical-detector qualification claim, and physical testing is not a release
+gate. Site-specific hardware results remain valuable follow-up evidence and
+will be addressed if they expose behavior not represented by the emulators.
+
+| Configuration | R1-8-0 status |
+|---|---|
+| TPX3 single chip and 2×2 quad | Established support retained, including existing detector rotations and mirrored orientations. |
+| TPX3 two-quad 4×2 | Emulator-qualified at 1024×512. Coordinate-dependent mask/BPC/difference/export mapping is supported for **UP** with two distinct `41...` quad boards. |
+| TPX3 single-board SpidrTurbo 4×2 | Not supported; its distinct `84...` mapping fails closed. |
+| MPX3 | Existing software/emulator support retained; R1-8-0 makes no new physical post-equalization claim. |
+| Generic geometry and Timepix4 | Deferred. Timepix4 must support independent chip width and height (448×512 pixels per ASIC) before geometry is generalized. |
+
+Interactive per-pixel editing and any expansion of per-pixel observability are
+future-release work. Existing BPC upload, PixelConfig refresh, comparison, and
+diagnostic paths remain available as documented.
+
 Driver logging (asyn)
 ---------------------
 
 Internal `ERR` / `WARN` / `LOG` / `FLOW` helpers (**`ADTimePixLog.h`**, used across `tpx3App/src/*.cpp`) use **`ADTPX3_FUNC`** in the log prefix: on **GCC/Clang** it defaults to **`__PRETTY_FUNCTION__`** (signature-rich); on other compilers it uses **`__func__`**.
 
 * **Shorter prefixes**: define **`ADTPX3_LOG_SHORT`** when building the driver library so prefixes use **`__func__` only** (see commented `USR_CPPFLAGS` line in `tpx3App/src/Makefile`).
 * **`WARN` visibility**: by default **`WARN` / `WARN_ARGS`** use **`ASYN_TRACE_WARNING`**. The port’s asyn **trace mask** must include the **warning** bit for those lines to appear. If your site only enables **ERROR**-level trace and you need the old behavior, build with **`ADTPX3_WARN_AS_ERROR`** so `WARN*` is emitted at **`ASYN_TRACE_ERROR`** (commented example in the same `Makefile`).
-* **Release detail**: see [RELEASE.md](RELEASE.md) (**R1-7-4**, September 27, 2026; **R1-7-3**; **R1-7-2**; **R1-7-1**; **R1-7-0**).
+* **Release detail**: see [RELEASE.md](RELEASE.md) (**R1-8-0**, October 6, 2026; **R1-7-4**; **R1-7-3**; **R1-7-2**; **R1-7-1**; **R1-7-0**).
 
 TCP Image Streaming
 --------------------
@@ -409,7 +429,7 @@ ADDriver(portName, NDARRAY_MAX_ADDR, NUM_TIMEPIX_PARAMS, maxBuffers, maxMemory,
 
 #### 10. Release history
 
-Current release: **R1-7-4** (driver **1.7.4**). See [RELEASE.md](RELEASE.md) for the complete current notes and upgrade guidance.
+Current release: **R1-8-0** (driver **1.8.0**, October 6, 2026). See [RELEASE.md](RELEASE.md) for the complete current notes, qualification boundary, and upgrade guidance.
 
 Historical milestone — version R1-3:
 

RELEASE.md

@@ -20,10 +20,55 @@ The master branch supports Serval 4.x.x and 3.x.x. **Serval 4.1.5** remains the
 
 From **R1-7-0**, one driver module (**ADServal**; shipped as **ADTimePix3**) supports both **TimePix3 (TPX3)** and **Medipix3 (MPX3)** via Serval: family is detected at runtime (`DetectorFamily_RBV`, capability PVs) and IOC startup selects the TPX3 or MPX3 profile.
 
-Driver depends on Serval versions, at this time. Latest **tagged** release is **R1-7-4** (September 27, 2026, driver **1.7.4**). Tested with stable Serval **4.1.5**, Serval **4.1.6-EXPERIMENTAL build 1760** on the TPX3 and MPX3 emulators, other 4.1.x versions, and 3.0.0-3.3.2.
-
-R1-8-0 (in progress)
---------------------
+Driver depends on Serval versions, at this time. Latest release is **R1-8-0** (October 6, 2026, driver **1.8.0**). Tested with stable Serval **4.1.5**, Serval **4.1.6-EXPERIMENTAL build 1760** on the TPX3 and MPX3 emulators, other 4.1.x versions, and 3.0.0-3.3.2.
+
+R1-8-0 (October 6, 2026)
+------------------------
+
+Driver / user-visible version **1.8.0** (see `ADTIMEPIX_*` in
+`ADTimePix.h`).
+
+### Qualification and support matrix
+
+R1-8-0 is a software- and emulator-qualified release. It makes no new
+physical-detector qualification claim, and physical testing is not a release
+gate. Site-specific physical results remain useful follow-up evidence and will
+be addressed if they expose behavior not represented by the emulators.
+
+| Configuration | R1-8-0 support and qualification |
+|---|---|
+| TPX3 single chip and 2×2 quad | Established support retained, including existing rotation and mirror mappings. |
+| TPX3 two-quad 4×2 | Emulator-qualified at 1024×512. Coordinate-dependent mask/BPC comparison, PixelConfig-difference, and masked-pixel export support **UP** only and require two distinct `41...` quad-board IDs. This restriction does not imply that established one-chip or quad acquisition orientations are absent. |
+| TPX3 single-board SpidrTurbo 4×2 | Not supported. Its distinct `84...` mapping is not inferred from the two-quad layout and fails closed. |
+| MPX3 | Existing software/emulator support retained; no new physical post-equalization qualification is claimed. |
+| Generic geometry and Timepix4 | Deferred. Geometry generalization must first represent independent ASIC width and height, including the 448×512-pixel Timepix4 matrix. |
+
+Interactive per-pixel editing and any expansion of per-pixel observability are
+deferred to a future release. Existing BPC upload, PixelConfig refresh,
+comparison, and diagnostic paths remain in scope.
+
+### Release scope and traceability
+
+The feature-content range `R1-7-4..7c0fbd8` contains 29 commits delivered by
+14 consecutively merged pull requests. The release-preparation pull request
+adds version, release-status, and final-assurance updates to this baseline.
+
+| PR | Scope |
+|---|---|
+| #51 | Bounded rolling accumulation |
+| #52 | Preview-rate semantics |
+| #53 | Accumulator numeric-range contract |
+| #54 | Calibration-path containment |
+| #55 | Removal of stray BOB text |
+| #56 | Release-assurance CI |
+| #57 | Image-accumulation screen stability |
+| #58 | AddressSanitizer and UndefinedBehaviorSanitizer CI |
+| #59 | Dependency/version evidence |
+| #60 | Size-aware mask and histogram displays |
+| #61 | Eight-chip profile and waveform capacity |
+| #62 | Phoebus screen refresh |
+| #63 | Phoebus prefix-macro synchronization |
+| #64 | TPX3 two-quad 4×2 mask and calibration support |
 
 ### Phoebus screen refresh
 
@@ -59,6 +104,12 @@ R1-8-0 (in progress)
   embedding timestamps or local filesystem paths. Generation fails if a
   declared dependency ref does not match the branch or tag actually checked
   out for the build.
+* The R1-8-0 hosted CI matrix uses Ubuntu 24.04, GCC, C++17, and EPICS Base
+  7.0. It runs default, AddressSanitizer, and UndefinedBehaviorSanitizer
+  configurations. The default job prepares asyn and ADCore from their selected
+  `master` refs; its retained dependency artifact records the exact resolved
+  commits, the pinned ci-scripts commit, bundled CPR 1.14.2 and nlohmann/json
+  3.12.0, and the ADCore configuration-hook digest.
 
 ### Image accumulation display stability
 
@@ -80,7 +131,8 @@ R1-8-0 (in progress)
   arrive. No histogram data, axis PV, or acquisition behavior changes.
 * SNS Phoebus qualification passes for 256x256 and 512x512 mask displays and
   preview-histogram accumulation. The 1024x512 mask display also passes with
-  the two-quad TPX3 emulator; physical-detector qualification remains pending.
+  the two-quad TPX3 emulator. No new physical-detector qualification is claimed
+  for R1-8-0.
 
 ### Eight-chip IOC waveform capacity
 
@@ -116,9 +168,10 @@ R1-8-0 (in progress)
   mismatches; and a rectangular mask propagated through the 1024x512 mask
   preview and masked-pixel JSON export. The 1024x512 image-accumulation and
   histogram views continued to operate during the same qualification.
-* Physical 1024x512 mask qualification and detector-specific eight-chip
-  equalization remain pending; the checked-in calibration is explicitly
-  synthetic and must not be used as qualified hardware calibration.
+* The checked-in calibration is explicitly synthetic and must not be used as
+  detector equalization or as evidence of hardware qualification. Physical
+  1024x512 mask testing and detector-specific eight-chip equalization are
+  optional post-release site work, not R1-8-0 release gates.
 
 ### Bounded rolling accumulation
 
@@ -206,7 +259,7 @@ R1-8-0 (in progress)
 * Coordinate-map validation passed for 13 implemented cases; five planned
   physical SpIDR 4x2 cases remain deferred.
 * All Phoebus BOB files passed XML validation.
-* REUSE validation passed for 398/398 files.
+* REUSE validation passed for 396/396 files with REUSE 3.0.
 * TPX3 emulator runtime qualification passed at 10 Hz for Img and PrvHst
   windows of 10 and 100 frames: requested capacity equaled current fill, memory
   plateaued at the expected bounded values, per-frame publication operated, and
@@ -234,7 +287,15 @@ R1-8-0 (in progress)
   readbacks agreed on calibration root `/`, calibration policy `Permissive: /`,
   destination allowlist `file:/*,tcp://*,http://*`, and destination policy
   `Permissive`.
-* Physical-hardware qualification remains pending.
+* The established TPX3 2×2 quad path passed regression checks for BPC and DACS
+  uploads, four 65536-byte PixelConfig matches, asymmetric mask placement,
+  mask reset, whole-detector counts, and image accumulation.
+* Final release-candidate smoke testing confirmed that a cleanly rebuilt
+  single-chip TPX3 emulator IOC reported driver version 1.8.0 and completed a
+  short acquisition with image accumulation and histogram display operating.
+  TPX3 and MPX3 quad emulator acquisitions also completed successfully in the
+  immediately preceding qualification run.
+* No new physical-hardware qualification is claimed or required for R1-8-0.
 
 
 R1-7-4 (September 27, 2026)

documentation/8chip-migration.md

@@ -68,19 +68,22 @@ HTTP 200. All eight PixelConfig responses decoded to 65536 bytes and matched
 their BPC slices with zero mismatches. A rectangular mask propagated through
 the 1024x512 mask preview and the masked-pixel JSON export. The geometry and
 deterministic two-quad composition prerequisites are also covered by compiled
-and portable tests, but physical-detector mask qualification remains pending.
+and portable tests. R1-8-0 is software- and emulator-qualified and makes no
+new physical-detector qualification claim; physical testing is optional
+post-release evidence rather than a release gate.
 
 The checked-in 4x2 BPC repeats the four source chip blocks for chips 4-7. The
 DACS file repeats each source chip's values under a unique destination section
 name. These files verify file sizing, upload selection, per-chip offsets, and
 software/emulator behavior only. Real calibration files are hardware-specific
 and should remain site-local unless redistribution is explicitly appropriate.
 
-Do not claim the eight-chip mask, BPC comparison, or PixelConfig-difference
-path as hardware-qualified until a detector-specific BPC/DACS pair and an
-asymmetric mask have confirmed all eight chip placements.
+Do not describe the eight-chip mask, BPC comparison, or PixelConfig-difference
+path as hardware-qualified without a detector-specific BPC/DACS pair and an
+asymmetric mask confirming all eight chip placements. This hardware-specific
+claim is outside the R1-8-0 release scope.
 
-## Verify on hardware
+## Optional hardware follow-up
 
 - **BPC ↔ image mapping:** The implemented 8-chip path is specifically the
   **two-quad** placement `2,1,4,7 / 3,0,5,6`. **Full-rate SpidrTurbo 4×2**

documentation/COORDINATE_MAP.md

@@ -293,7 +293,9 @@ chip assignment shown above.
 for each module and applies the module-level 180-degree rotation on the right.
 `pelIndex` and `bpc2ImgIndex` use the same checked helper, and compact compiled
 tests round-trip every pixel. Other global orientations remain unimplemented
-(`WARN`, returns `-1`).
+for this new eight-chip coordinate-dependent mask/BPC/difference/export path
+(`WARN`, returns `-1`). This does not limit the established detector-orientation
+support for one-chip and 2×2 quad acquisition and mask workflows.
 
 ### Full-rate SpidrTurbo 4×2 — **planned** (not in `mask_io.cpp` yet)
 

tpx3App/src/ADTimePix.h

@@ -18,8 +18,8 @@
 
 // version numbers
 #define ADTIMEPIX_VERSION      1
-#define ADTIMEPIX_REVISION     7
-#define ADTIMEPIX_MODIFICATION 4
+#define ADTIMEPIX_REVISION     8
+#define ADTIMEPIX_MODIFICATION 0
 
 
 #include "ADDriver.h"