Files
leonarski_fandClaude Opus 5.5 d4b1ac8852 jfjoch_fpga_stills_test: blocking at the source, paced rate sweep
FPGAImagePuller gains two options, off by default (the broker is unchanged):
- blocking: an image waits for a free slot instead of being dropped, and no
  module is given up for being behind the others; JFJochReceiverRugnuxStills
  then waits for room in the image buffer (ImagePuller::IsBlocking). The cards
  keep their frames, host_writer waits for host buffers and the stall reaches
  the internal generator through the AXI-stream back-pressure, so nothing is
  lost anywhere. The time the module threads waited for a slot is kept.
- frame_rate_hz: image i is taken from the cards no earlier than i / rate
  after the start. The firmware has no frame period for the generator, so
  this is how it is paced.
GetSlot now looks for the image again after each wait (another module may
have started it).

jfjoch_fpga_stills_test always blocks; -r runs one collection per rate and
reports delivered rate, the fraction of it the source was blocked, sustained
rate (images / wall time), analysis rate after the pre-pass, indexing rate,
and the card's cycles waiting for host buffers; a table at the end. The mock
counts its wait for host buffers as pipeline_stalls_host, like timer_host.

Tests: FPGAImagePuller_SlowConsumer_Blocking (no drop, all images in order),
FPGAImagePuller_Paced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UqXYdHHZ4cogS1mrGUtfN7
2026-11-18 09:58:03 +01:00

561 lines
21 KiB
C++

// SPDX-FileCopyrightText: 2026 Filip Leonarski, Paul Scherrer Institute <filip.leonarski@psi.ch>
// SPDX-License-Identifier: GPL-3.0-only
#include <cstring>
#include "MockAcquisitionDevice.h"
namespace {
bool MaskEmpty(const uint64_t packet_mask[8]) {
for (int i = 0; i < 8; i++) {
if (packet_mask[i] != 0)
return false;
}
return true;
}
}
MockAcquisitionDevice::MockAcquisitionDevice(uint16_t data_stream, size_t in_frame_buffer_size_modules,
uint32_t in_card_memory_bytes)
: FPGAAcquisitionDevice(data_stream),
card_memory_bytes(in_card_memory_bytes),
collected_modules(2 * MAX_MODULES_FPGA),
summation_completions(MAX_MODULES_FPGA * MAX_FPGA_SUMMATION),
summation_mask(MAX_MODULES_FPGA, std::vector<bool>(MAX_FPGA_SUMMATION)),
summation_count(MAX_MODULES_FPGA),
summation_frame_prefix(MAX_MODULES_FPGA) {
mac_addr = 0xCCAA11223344;
ipv4_addr = 0x0132010A;
max_modules = MAX_MODULES_FPGA;
internal_generator_module_frames = GeneratorModuleFrames(card_memory_bytes);
generator_frames.resize(internal_generator_module_frames);
buffers.reserve(in_frame_buffer_size_modules);
for (size_t i = 0; i < in_frame_buffer_size_modules; i++) {
buffers.push_back(std::make_unique<FrameBuffer>());
buffer_device.push_back(reinterpret_cast<DeviceOutput *>(buffers.back().get()));
}
}
MockAcquisitionDevice::~MockAcquisitionDevice() {
if (action_thread.joinable())
action_thread.join();
stop_frame_generator = true;
}
void MockAcquisitionDevice::SetOutput(uint64_t image, uint32_t module_number, const DeviceOutput &output) {
if (outputs.size() <= image)
outputs.resize(image + 1);
if (outputs[image].size() <= module_number)
outputs[image].resize(module_number + 1);
outputs[image][module_number] = std::make_unique<DeviceOutput>(output);
}
void MockAcquisitionDevice::AddPacket(const Packet &packet) {
std::unique_lock ul(packets_mutex);
packets.push_back(packet);
}
void MockAcquisitionDevice::CreateJFPacket(const DiffractionExperiment &experiment, uint64_t frame_number,
uint32_t eth_packet, uint32_t module_number, const uint16_t *data,
int8_t adjust_axis, uint8_t user) {
uint32_t half_module = ((eth_packet >= 64) ? 1 : 0);
AddPacket(Packet{
.frame_number = frame_number,
.packet_number = eth_packet % 64,
.udp_port = static_cast<uint16_t>(2 * module_number + half_module),
.column = 0,
.detector_type = SLS_DETECTOR_TYPE_JUNGFRAU,
.exptime = 0,
.bunchid = 0x1234567898765431L,
.timestamp = 0xABCDEF0000FEDCBAL,
.debug = 0,
.eth_error = (user % 2 == 1),
.len_error = (adjust_axis != 0),
.generator_slot = NoGeneratorSlot
});
}
void MockAcquisitionDevice::CreateJFPackets(const DiffractionExperiment &experiment, uint64_t frame_number_0,
uint64_t frames, uint32_t module_number, const uint16_t *data) {
for (uint64_t i = 0; i < frames; i++) {
for (int j = 0; j < 128; j++)
CreateJFPacket(experiment, frame_number_0 + i, j, module_number, nullptr, 0, 0);
}
}
void MockAcquisitionDevice::CreateEIGERPacket(const DiffractionExperiment &experiment, uint64_t frame_number,
uint32_t eth_packet, uint32_t module_number, uint32_t col,
uint32_t row, const uint16_t *data) {
AddPacket(Packet{
.frame_number = frame_number,
.packet_number = eth_packet % 128,
.udp_port = static_cast<uint16_t>(2 * module_number + row),
.column = static_cast<uint16_t>(col % 2),
.detector_type = SLS_DETECTOR_TYPE_EIGER,
.exptime = 0,
.bunchid = 0x1234567898765431L,
.timestamp = 0xABCDEF0000FEDCBAL,
.debug = 0,
.generator_slot = NoGeneratorSlot
});
}
void MockAcquisitionDevice::CreateXfelBunchIDPacket(double pulse_id, uint32_t event_code) {
Packet packet{.bunchid_packet = true, .generator_slot = NoGeneratorSlot};
memcpy(&packet.bunchid, &pulse_id, sizeof(uint64_t));
AddPacket(packet);
}
void MockAcquisitionDevice::CreateFinalPacket(const DiffractionExperiment &experiment) {
CreateJFPacket(experiment, UINT64_MAX, 0, 0, nullptr, false);
}
void MockAcquisitionDevice::HW_ReadActionRegister(DataCollectionConfig *job) {
memcpy(job, &cfg, sizeof(DataCollectionConfig));
}
void MockAcquisitionDevice::HW_WriteActionRegister(const DataCollectionConfig *job) {
memcpy(&cfg, job, sizeof(DataCollectionConfig));
}
void MockAcquisitionDevice::FPGA_StartAction(const DiffractionExperiment &experiment) {
if (action_thread.joinable())
action_thread.join();
run_counter += 1;
idle = false;
action_thread = std::thread(&MockAcquisitionDevice::DataCollectionThread, this);
}
void MockAcquisitionDevice::FPGA_EndAction() {
if (action_thread.joinable())
action_thread.join();
if (frame_generator_result != 0)
throw JFJochException(JFJochExceptionCategory::AcquisitionDeviceError,
"Internal frame generator refused its configuration, error code "
+ std::to_string(frame_generator_result));
}
bool MockAcquisitionDevice::HW_IsIdle() const {
return idle;
}
bool MockAcquisitionDevice::HW_ReadMailbox(uint32_t *values) {
return completions.Get(*values);
}
bool MockAcquisitionDevice::HW_SendWorkRequest(uint32_t handle) {
work_requests.Put(handle);
return true;
}
void MockAcquisitionDevice::Cancel() {
cancel = true;
}
// The mock does not process data: of what the host loads into the card only the frames of the internal
// generator are kept
void MockAcquisitionDevice::HW_LoadCalibration(const LoadCalibrationConfig &config) {
const DeviceOutput *input = buffer_device[config.handle];
if (input->module_statistics.load_calibration_destination != LOAD_CALIBRATION_DEST_FRAME_GEN)
return;
auto &frame = generator_frames.at(input->module_statistics.module_number);
frame.resize(RAW_MODULE_SIZE);
memcpy(frame.data(), input->pixels, RAW_MODULE_SIZE * sizeof(uint16_t));
}
void MockAcquisitionDevice::HW_SetSpotFinderParameters(const SpotFinderParameters &params) {}
void MockAcquisitionDevice::HW_RunInternalGenerator(const FrameGeneratorConfig &config) {
frame_generator_result = 0;
frame_generator_future = std::async(std::launch::async, [this, config] {
frame_generator_result = FrameGenerator(config);
// A generator that refused its configuration sends no frame: the data collection ends instead of waiting
if (frame_generator_result != 0)
cancel = true;
});
}
int MockAcquisitionDevice::FrameGenerator(FrameGeneratorConfig config) {
// frame_generator.cpp: its checks and return codes, then packet headers only
if ((config.modules > MAX_MODULES_FPGA) || (config.modules == 0))
return 1;
if ((config.detector_type != SLS_DETECTOR_TYPE_EIGER) && (config.detector_type != SLS_DETECTOR_TYPE_JUNGFRAU))
return 2;
if ((config.detector_type == SLS_DETECTOR_TYPE_EIGER)
&& (config.eiger_bit_depth != 8) && (config.eiger_bit_depth != 16) && (config.eiger_bit_depth != 32))
return 2;
if (config.frames == 0)
return 0;
// The frames for the generator have to fit in the card memory
uint32_t module_slots = config.modules * (config.images_in_memory + 1);
if ((config.detector_type == SLS_DETECTOR_TYPE_EIGER) && (config.eiger_bit_depth == 32))
module_slots *= 2;
if (module_slots >= internal_generator_module_frames)
return 3;
double pulse_id = config.pulse_id;
uint16_t data_stream_port = (config.data_stream & UINT8_MAX) << 8;
// The packets wait until the data collection takes them - only a limited number of them
auto send = [this] (const Packet &packet) {
while (!cancel && !stop_frame_generator) {
{
std::unique_lock ul(packets_mutex);
if (packets.size() < 16384) {
packets.push_back(packet);
return;
}
}
std::this_thread::sleep_for(std::chrono::microseconds(10));
}
};
// One packet with TUSER = 1, to reset the network cores on the way - it is dropped as an Ethernet error
send(Packet{.frame_number = 1, .udp_port = data_stream_port, .detector_type = SLS_DETECTOR_TYPE_JUNGFRAU,
.eth_error = true, .generator_slot = NoGeneratorSlot});
uint32_t frame_cell = 0;
for (uint32_t f = 0; f < config.frames; f++) {
if (cancel || stop_frame_generator)
break;
uint64_t bunchid;
memcpy(&bunchid, &pulse_id, sizeof(uint64_t));
for (uint32_t m = 0; m < config.modules; m++) {
if (config.detector_type == SLS_DETECTOR_TYPE_JUNGFRAU) {
for (uint32_t p = 0; p < 128; p++)
send(Packet{
.frame_number = f + 1,
.packet_number = p,
.udp_port = static_cast<uint16_t>(data_stream_port | (2 * m)),
.column = 0,
.detector_type = SLS_DETECTOR_TYPE_JUNGFRAU,
.exptime = config.exptime,
.bunchid = bunchid,
.timestamp = config.exptime * f,
.debug = config.debug,
.generator_slot = frame_cell * config.modules + m
});
} else {
uint32_t bit_depth = config.eiger_bit_depth;
for (uint32_t p = 0; p < 16 * bit_depth; p++) {
uint32_t half_module = (p >= 8 * bit_depth) ? 1 : 0;
send(Packet{
.frame_number = f + 1,
.packet_number = (p / 2) % (4 * bit_depth),
.udp_port = static_cast<uint16_t>(data_stream_port | (2 * m + half_module)),
.column = static_cast<uint16_t>(p % 2),
.detector_type = SLS_DETECTOR_TYPE_EIGER,
.exptime = config.exptime,
.bunchid = 0,
.timestamp = config.exptime * f,
.debug = config.debug,
.generator_slot = (bit_depth == 32 ? 2 : 1) * (frame_cell * config.modules + m)
});
}
}
}
pulse_id += 1.0;
frame_cell = (frame_cell == config.images_in_memory) ? 0 : frame_cell + 1;
}
return 0;
}
void MockAcquisitionDevice::DataCollectionThread() {
cancel = false;
stop_frame_generator = false;
stalls_host = 0;
for (auto &c: collected_modules)
c = ModuleCompletion{.frame_number = UINT64_MAX};
for (int m = 0; m < MAX_MODULES_FPGA; m++) {
summation_mask[m].assign(MAX_FPGA_SUMMATION, false);
summation_count[m] = 0;
summation_frame_prefix[m] = 0;
}
frames_in_group = 0;
handle_to_complete = HANDLE_START;
uint32_t data_collection_id = (cfg.mode >> 16) & UINT16_MAX;
// host_writer.cpp: work requests left from the previous data collection are returned unused
uint32_t handle;
while (work_requests.Get(handle))
completions.Put((DATA_COLLECTION_ID_PURGE << 16) | handle);
completions.Put((data_collection_id << 16) | HANDLE_START);
// data_collection_fsm.cpp: cancel is checked between packets
while (!cancel) {
Packet packet;
bool received = false;
{
std::unique_lock ul(packets_mutex);
if (!packets.empty()) {
packet = packets.front();
packets.pop_front();
received = true;
}
}
if (!received)
std::this_thread::sleep_for(std::chrono::microseconds(10));
else if (!ReceivePacket(packet))
break;
}
EndDataCollection();
// Packets after the end of the data collection are dropped
stop_frame_generator = true;
if (frame_generator_future.valid())
frame_generator_future.get();
{
std::unique_lock ul(packets_mutex);
packets.clear();
}
idle = true;
}
bool MockAcquisitionDevice::ReceivePacket(const Packet &packet) {
// udp.cpp and sls_detector.cpp
udp_packets++;
if (packet.bunchid_packet) {
current_pulse_id = packet.bunchid;
return true;
}
if (packet.eth_error || packet.len_error)
return true;
if ((((packet.udp_port >> 8) & 0xF) != (cfg.data_stream & 0xF)) || (packet.frame_number == 0))
return true;
sls_packets++;
// data_collection_fsm.cpp: a frame far enough after the last one ends the data collection
uint64_t frame_number = packet.frame_number - 1;
if (frame_number >= static_cast<uint64_t>(cfg.nframes) - 1 + DELAY_FRAMES_STOP_AND_QUIT)
return false;
// stream512to768.cpp: location of the packet in the module, in units of 32 beats = 1024 pixels
uint32_t module = (packet.udp_port >> 1) & 0x1F;
uint32_t row = packet.udp_port & 1;
uint32_t column = packet.column & 1;
uint32_t eth_packet = packet.packet_number & 0x1FF;
uint32_t packet_parts;
if (packet.detector_type == SLS_DETECTOR_TYPE_JUNGFRAU) {
packet_parts = 4;
eth_packet = (eth_packet % 128) | (row * 64);
} else if (cfg.mode & MODE_EIGER_8BIT) {
packet_parts = 4;
eth_packet = (row ? (64 + (eth_packet % 32) * 2) : (62 - (eth_packet % 32) * 2)) | column;
} else if (cfg.mode & MODE_EIGER_32BIT) {
packet_parts = 1;
uint32_t pos_of_4_line = (eth_packet % 128) / 2;
uint32_t pos_within_2_lines = eth_packet % 2;
eth_packet = (row ? (256 + pos_of_4_line * 4) : (252 - pos_of_4_line * 4)) | (2 * column) | pos_within_2_lines;
} else {
packet_parts = 2;
eth_packet = (row ? (128 + (eth_packet % 64) * 2) : (126 - (eth_packet % 64) * 2)) | column;
}
// save_to_hbm.cpp: a module is complete only when the next frame of the same parity arrives
// for that module, or at the end of the data collection
ModuleCompletion &c = collected_modules[module * 2 + frame_number % 2];
if (c.frame_number != frame_number) {
if (!MaskEmpty(c.packet_mask))
SendCompletion(c);
c = ModuleCompletion{
.frame_number = frame_number,
.exptime = packet.exptime,
.timestamp = packet.timestamp,
.bunchid = packet.bunchid,
.debug = packet.debug,
.module = module,
.detector_type = packet.detector_type,
.generator_slot = packet.generator_slot
};
}
for (uint32_t i = eth_packet * packet_parts; i < (eth_packet + 1) * packet_parts; i++)
c.packet_mask[i / 64] |= (1LU << (i % 64));
c.packet_count += packet_parts;
return true;
}
void MockAcquisitionDevice::SendCompletion(const ModuleCompletion &c) {
// frame_summation_reorder_compl.cpp: with summation, frames are grouped per module and only complete
// groups are written
uint32_t sum = cfg.nsummation & UINT8_MAX;
if (sum == 0) {
LoadModule(c);
return;
}
uint64_t frame_prefix = c.frame_number / (sum + 1);
uint32_t frame_loc = c.frame_number % (sum + 1);
uint32_t m = c.module;
if (frame_prefix > summation_frame_prefix[m]) {
SendSummationGroup(m);
summation_mask[m].assign(MAX_FPGA_SUMMATION, false);
summation_completions[m * MAX_FPGA_SUMMATION + frame_loc] = c;
summation_mask[m][frame_loc] = true;
summation_count[m] = 1;
summation_frame_prefix[m] = frame_prefix;
} else if (frame_prefix == summation_frame_prefix[m]) {
summation_completions[m * MAX_FPGA_SUMMATION + frame_loc] = c;
summation_mask[m][frame_loc] = true;
summation_count[m] += 1;
} else {
ModuleCompletion late = c;
late.ignore = true;
LoadModule(late);
}
}
void MockAcquisitionDevice::SendSummationGroup(uint32_t m) {
uint32_t sum = cfg.nsummation & UINT8_MAX;
for (int i = 0; i <= sum; i++) {
if (summation_mask[m][i]) {
ModuleCompletion c = summation_completions[m * MAX_FPGA_SUMMATION + i];
if (summation_count[m] != sum + 1)
c.ignore = true;
LoadModule(c);
}
}
}
void MockAcquisitionDevice::LoadModule(const ModuleCompletion &c) {
// load_from_hbm.cpp: an incomplete summation group is dropped
if (c.ignore)
return;
// frame_summation.cpp: one module per group, with the header of the first frame and the packets
// present in all frames
uint32_t sum = cfg.nsummation & UINT8_MAX;
if (sum == 0) {
WriteToHost(c);
return;
}
if (frames_in_group == 0) {
group_completion = c;
group_completion.frame_number = c.frame_number / (sum + 1);
} else {
for (int i = 0; i < 8; i++)
group_completion.packet_mask[i] &= c.packet_mask[i];
group_completion.packet_count += c.packet_count;
}
frames_in_group++;
if (frames_in_group == sum + 1) {
frames_in_group = 0;
WriteToHost(group_completion);
}
}
void MockAcquisitionDevice::WriteToHost(const ModuleCompletion &c) {
// host_writer.cpp: waits for a host buffer; only when the data collection is cancelled the module
// is dropped instead
uint32_t handle;
const auto t0 = std::chrono::steady_clock::now();
while (!work_requests.Get(handle)) {
if (cancel)
return;
std::this_thread::sleep_for(std::chrono::microseconds(10));
}
// timer_host: the wait in cycles of the card's 200 MHz clock
stalls_host += std::chrono::duration_cast<std::chrono::nanoseconds>(std::chrono::steady_clock::now() - t0).count() / 5;
if (handle >= buffer_device.size())
return;
DeviceOutput *output = buffer_device[handle];
const DeviceOutput *ready_output = nullptr;
if (!outputs.empty()) {
auto &image = outputs[c.frame_number % outputs.size()];
if (c.module < image.size())
ready_output = image[c.module].get();
}
if (ready_output != nullptr)
memcpy(output, ready_output, sizeof(DeviceOutput));
else {
memset(output, 0, sizeof(DeviceOutput));
if ((c.generator_slot != NoGeneratorSlot) && !generator_frames[c.generator_slot].empty())
memcpy(output->pixels, generator_frames[c.generator_slot].data(), RAW_MODULE_SIZE * sizeof(uint16_t));
}
ModuleStatistics &stats = output->module_statistics;
stats.frame_number = c.frame_number;
stats.timestamp = c.timestamp;
memcpy(&stats.pulse_id, &c.bunchid, sizeof(uint64_t));
stats.detector_type = c.detector_type;
stats.exptime = c.exptime;
stats.debug = c.debug;
stats.pedestal = 0;
stats.packet_count = c.packet_count;
stats.module_number = c.module;
stats.load_calibration_destination = 0;
memcpy(stats.packet_mask, c.packet_mask, sizeof(stats.packet_mask));
// host_writer.cpp: a module is announced to the host only when the next one is written, or at the end
uint32_t data_collection_id = (cfg.mode >> 16) & UINT16_MAX;
if (handle_to_complete != HANDLE_START)
completions.Put((data_collection_id << 16) | handle_to_complete);
handle_to_complete = handle;
}
void MockAcquisitionDevice::EndDataCollection() {
// save_to_hbm.cpp: modules still being collected, for each module the older frame first
for (int m = 0; m < MAX_MODULES_FPGA; m++) {
const ModuleCompletion &c0 = collected_modules[2 * m];
const ModuleCompletion &c1 = collected_modules[2 * m + 1];
const ModuleCompletion &first = (c0.frame_number < c1.frame_number) ? c0 : c1;
const ModuleCompletion &second = (c0.frame_number < c1.frame_number) ? c1 : c0;
if (!MaskEmpty(first.packet_mask))
SendCompletion(first);
if (!MaskEmpty(second.packet_mask))
SendCompletion(second);
}
// frame_summation_reorder_compl.cpp
if ((cfg.nsummation & UINT8_MAX) > 0) {
for (int m = 0; m < MAX_MODULES_FPGA; m++)
SendSummationGroup(m);
}
// host_writer.cpp
uint32_t data_collection_id = (cfg.mode >> 16) & UINT16_MAX;
if (handle_to_complete != HANDLE_START)
completions.Put((data_collection_id << 16) | handle_to_complete);
completions.Put((data_collection_id << 16) | HANDLE_END);
}
DataCollectionStatus MockAcquisitionDevice::GetDataCollectionStatus() const {
DataCollectionStatus status{};
uint64_t pulse_id_u64 = current_pulse_id;
double pulse_id;
memcpy(&pulse_id, &pulse_id_u64, sizeof(double));
status.ctrl_reg = idle ? (1 << 4) : 0;
status.max_modules = MAX_MODULES_FPGA;
status.hbm_size_bytes = card_memory_bytes;
status.run_counter = run_counter;
status.current_pulseid = pulse_id;
status.packets_udp = udp_packets;
status.packets_sls = sls_packets;
status.pipeline_stalls_host = stalls_host;
return status;
}
DeviceStatus MockAcquisitionDevice::GetDeviceStatus() const {
DeviceStatus status{};
strncpy(status.serial_number, "MOCK1", sizeof(status.serial_number));
strncpy(status.device_number, "Mock device", sizeof(status.device_number));
status.fpga_default_mac_addr = mac_addr;
status.eth_link_count = 1;
status.eth_link_status = 1;
status.packets_sls = sls_packets;
status.packets_udp = udp_packets;
return status;
}