// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute // SPDX-License-Identifier: GPL-3.0-only #include "FPGAImagePuller.h" #include #include FPGAImagePuller::FPGAImagePuller(const DiffractionExperiment &in_experiment, const PixelMask &mask, const JFCalibration *calibration, AcquisitionDeviceGroup &in_devices, Logger &in_logger, int64_t compression_threads, size_t in_max_slots) : ImagePuller(in_max_slots + 2), // every slot, the start and the end message: Put never finds it full experiment(in_experiment), logger(in_logger), devices(in_devices), max_slots(in_max_slots), image_dropped(experiment.GetImageNum(), 0) { const int ndatastreams = experiment.GetDataStreamsNum(); if (devices.size() < ndatastreams) throw JFJochException(JFJochExceptionCategory::InputParameterInvalid, "Number of acquisition devices has to match data streams"); for (int m = 0; m < experiment.GetModulesNum(); m++) adu_histogram.emplace_back(std::make_unique()); for (int d = 0; d < ndatastreams; d++) { devices[d].PrepareAction(experiment); expected_packets_per_image += devices[d].Counters().GetExpectedPacketsPerImage(); } if (experiment.GetDetectorType() != DetectorType::JUNGFRAU) calibration = nullptr; // Making a slot is slow, under the lock all modules go through: the first ones are ready when the frames start for (size_t i = 0; i < std::min(max_slots, InitialSlots); i++) { free_slots.push_back(std::make_shared(experiment)); slots_created++; } // The receiver's own start message is built from its experiment; this one only says the run has begun. StartMessage start{}; experiment.FillMessage(start); outside_fifo.Put({.cbor = std::make_shared(start), .received = std::chrono::steady_clock::now()}); for (int i = 0; i < compression_threads; i++) compress_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::CompressThread, this)); for (int d = 0; d < ndatastreams; d++) for (int m = 0; m < experiment.GetModulesNum(d); m++) module_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::ModuleThread, this, d, m)); std::latch ready(ndatastreams); for (int d = 0; d < ndatastreams; d++) acquire_futures.emplace_back(std::async(std::launch::async, &FPGAImagePuller::AcquireThread, this, static_cast(d), std::cref(mask), calibration, std::ref(ready))); ready.wait(); finish_future = std::async(std::launch::async, &FPGAImagePuller::FinalizeMeasurement, this); if (failed) { try { Stop(); } catch (...) { outside_fifo.Clear(); // the destructor does not run throw; } } } FPGAImagePuller::~FPGAImagePuller() { try { Stop(); } catch (const std::exception &e) { logger.Error("FPGA image puller teardown failed: {}", e.what()); } // These hold slots, which go back to this object outside_fifo.Clear(); } void FPGAImagePuller::SetError(std::exception_ptr e) { std::unique_lock ul(error_mutex); if (!error) error = e; failed = true; } void FPGAImagePuller::Cancel() { for (int d = 0; d < experiment.GetDataStreamsNum(); d++) devices[d].Cancel(); } void FPGAImagePuller::Stop() { Cancel(); std::call_once(finish_once, [this] { finish_future.get(); }); std::unique_lock ul(error_mutex); if (error) std::rethrow_exception(std::exchange(error, nullptr)); } void FPGAImagePuller::AcquireThread(uint16_t data_stream, const PixelMask &mask, const JFCalibration *calibration, std::latch &ready) { auto &device = devices[data_stream]; try { // Only what the card needs for the pixels: its analysis results are not read. if (calibration != nullptr) device.InitializeCalibration(experiment, *calibration); device.InitializePixelMask(experiment, mask); device.StartAction(experiment); } catch (...) { SetError(std::current_exception()); Cancel(); // the module threads of the other cards have to come out as well ready.count_down(); return; } ready.count_down(); try { device.WaitForActionComplete(); } catch (...) { SetError(std::current_exception()); Cancel(); } } int64_t FPGAImagePuller::FastestFrame() const { int64_t ret = 0; for (int d = 0; d < experiment.GetDataStreamsNum(); d++) ret = std::max(ret, static_cast(devices[d].Counters().GetFastestFrameNumber())); return ret; } // Polled: a dead card has to be noticed from the other cards' frames void FPGAImagePuller::WaitForFrame(uint16_t data_stream, uint16_t module_number, int64_t frame) const { const auto &counters = devices[data_stream].Counters(); // A frame is complete once the module is two further on, as in JFJochReceiverFPGA while ((static_cast(counters.GetCurrFrameNumber(module_number)) < frame + 2) && !counters.IsAcquisitionFinished() && !failed && (FastestFrame() < frame + 2 + MissingAfterFrames)) std::this_thread::sleep_for(std::chrono::milliseconds(1)); } // The last frame any card got; waits for all cards, so every module stops at the same image int64_t FPGAImagePuller::LastFrame() const { for (int d = 0; d < experiment.GetDataStreamsNum(); d++) while (!devices[d].Counters().IsAcquisitionFinished() && !failed) std::this_thread::sleep_for(std::chrono::milliseconds(1)); return FastestFrame(); } std::shared_ptr FPGAImagePuller::GetSlot(int64_t image_number) { std::unique_lock ul(images_mutex); if (image_dropped[image_number]) return nullptr; if (const auto it = images_in_progress.find(image_number); it != images_in_progress.end()) return it->second; std::shared_ptr slot; if (!free_slots.empty()) { slot = free_slots.back(); free_slots.pop_back(); } else if (slots_created < max_slots) { slots_created++; slot = std::make_shared(experiment); } else { image_dropped[image_number] = 1; dropped_images++; Emit(image_number, std::nullopt); return nullptr; } slot->image_number = image_number; slot->metadata = std::make_unique(experiment); slot->modules_left = static_cast(experiment.GetModulesNum()); images_in_progress[image_number] = slot; return slot; } void FPGAImagePuller::ReturnSlot(const std::shared_ptr &slot) { std::unique_lock ul(images_mutex); free_slots.push_back(slot); } void FPGAImagePuller::ModuleThread(uint16_t data_stream, uint16_t module_number) { try { auto &device = devices[data_stream]; const auto &counters = device.Counters(); const size_t module_abs = experiment.GetFirstModuleOfDataStream(data_stream) + module_number; int64_t oldest_held = 0; for (int64_t image = 0; image < experiment.GetImageNum(); image++) { WaitForFrame(data_stream, module_number, image); if (failed) break; if (counters.IsAcquisitionFinished() && (image > static_cast(counters.GetFastestFrameNumber())) && (image > LastFrame())) break; // A frame given up on can still arrive, late: its buffer goes back to the card. while ((oldest_held < image) && (oldest_held < static_cast(counters.GetCurrFrameNumber(module_number)))) device.FrameBufferRelease(oldest_held++, module_number); const bool collected = counters.IsAnyPacketCollected(image, module_number); if (const auto slot = GetSlot(image)) { if (collected) { const DeviceOutput *output = device.GetDeviceOutput(image, module_number); slot->metadata->Process(output); adu_histogram[module_abs]->Add(*output); slot->transformation.ProcessModule(output, data_stream); } else slot->transformation.FillNotCollectedModule(module_number, data_stream); if (--slot->modules_left == 0) { { std::unique_lock ul(images_mutex); images_in_progress.erase(image); } images_to_compress.Put(slot); } } if (collected) device.FrameBufferRelease(image, module_number); } } catch (...) { SetError(std::current_exception()); Cancel(); } } void FPGAImagePuller::CompressThread() { while (const auto slot = images_to_compress.GetBlocking()) { const int64_t image_number = slot->image_number; try { DataMessage message{}; message.number = image_number; message.original_number = image_number; slot->metadata->Export(message, expected_packets_per_image); // The card's spot finder and ROI map were not set up for this run; the receiver reports its own. message.strong_pixel_count.reset(); message.roi.clear(); if (message.image_collection_efficiency == 0.0f) { // no module of it came ReturnSlot(slot); Emit(image_number, std::nullopt); continue; } message.image = slot->transformation.GetCompressedImage(); ImagePullerOutput output; output.cbor = std::make_shared(message); // The image lives in the slot: it goes back when the last copy of this output is gone. output.raw = std::shared_ptr( new ReceiveBufferRegion{const_cast(message.image.GetCompressed()), message.image.GetCompressedSize()}, [this, slot](ReceiveBufferRegion *region) { delete region; ReturnSlot(slot); }); Emit(image_number, std::move(output)); } catch (...) { SetError(std::current_exception()); Cancel(); ReturnSlot(slot); Emit(image_number, std::nullopt); } } } // Whichever thread finishes the image next in line lets it, and those waiting behind it, out. void FPGAImagePuller::Emit(int64_t image_number, std::optional output) { std::unique_lock ul(order_mutex); images_done.emplace(image_number, std::move(output)); for (auto it = images_done.begin(); (it != images_done.end()) && (it->first == next_image); it = images_done.erase(it), next_image++) { if (it->second) { it->second->received = std::chrono::steady_clock::now(); outside_fifo.Put(std::move(*it->second)); } } } void FPGAImagePuller::FinalizeMeasurement() { for (auto &f: module_futures) f.get(); for (size_t i = 0; i < compress_futures.size(); i++) images_to_compress.Put(nullptr); for (auto &f: compress_futures) f.get(); Cancel(); for (auto &f: acquire_futures) f.get(); // Only an error leaves images unfinished, holding back those behind them { std::unique_lock ul(order_mutex); for (auto &[n, output]: images_done) if (output) outside_fifo.Put(std::move(*output)); images_done.clear(); } if (dropped_images > 0) logger.Warning("FPGA image puller: {} images dropped, no free slot", dropped_images.load()); EndMessage end{}; for (size_t i = 0; i < adu_histogram.size(); i++) end.adu_histogram["module" + std::to_string(i)] = adu_histogram[i]->GetHistogram(); outside_fifo.Put({.cbor = std::make_shared(end), .received = std::chrono::steady_clock::now()}); }