coda-usr

CODA (CEBAF Online Data Acquisition) user environment for experimental data acquisition, component orchestration, and configuration management.

Overview

This repository contains the complete CODA user environment including:

• Startup and control scripts for component orchestration
• Configuration files (base templates and auto-generated)
• Readout lists (ROLs) for hardware control
• CODA COOL database for run configuration
• Firmware images for FADC and VTP hardware
• Runtime logs and diagnostic outputs

Directory Structure

coda-usr/
├── coda_scripts/       # Startup, control, and orchestration scripts
├── config/             # Configuration files (base + auto-generated)
├── coda_tmp_log/       # Runtime logs (auto-created)
├── db/                 # CODA COOL database files
├── firmware/           # Hardware firmware images
└── rol/                # Readout lists (compiled to .so)
    ├── vme/            # VME ROC readout lists
    ├── vtp/            # VTP library source
    └── vtp_rol/        # VTP ROC readout lists + binaries

Directory Details

coda_scripts/

Purpose: CODA component orchestration and system control scripts

Key Scripts:

• startCoda - Main component launcher with file-based configuration
• kcoda - Component killer (cleanup script)
• Pedestal generation helpers
• Configuration file generators
• Environment setup utilities

Responsibilities:

• Parse component definition files
• Launch CODA components (ROC, FPGA/VTP, PEB, ER, etc.) on remote hosts
• Generate per-host VME and VTP configuration files from base templates
• Run pedestal measurements and integrate results into configs
• Start CODA platform (rcPlatform) and run control GUI (rcGUI)
• Manage component lifecycle (startup sequencing, process monitoring)

Key Features:

• File-based component launching (--file components.txt)
• Automatic config generation mode (--config flag)
• Pedestal measurement integration
• Remote execution via remote_vme SSH wrapper
• Xterm window management for interactive component shells

Documentation: See coda_scripts/README.md for detailed usage, examples, and troubleshooting.

Workflow Integration:

• Normal startup: Launches components using existing config files
• Config mode: Runs pedestal measurements → generates configs → launches components

---

config/

Purpose: Configuration file storage (both user-edited and auto-generated)

File Types:

User-Edited (Base Templates)

• base.cnf - Master configuration template containing:
  • VME configuration (FADC parameters)
  • VTP configuration (firmware, network, streaming)
  • MAC/IP address mapping table for VTP hosts
• run.cnf - Component definition file (hostname, type, name, options)

Auto-Generated (By startCoda --config)

• vme_<hostname>.cnf - Per-ROC VME configuration
  • VME section from base.cnf
  • Appended pedestal data from <hostname>.peds
• vtp_<hostname>.cnf - Per-ROC VTP configuration
  • VTP section from base.cnf
  • Host-specific MAC and IP addresses
  • Computed VTP_PAYLOAD_EN based on FADC slots

Pedestal Files

• <hostname>.peds - FADC pedestal measurement output
  • Generated by fadc250peds during config mode
  • Contains baseline offsets for ADC channels
  • Used to compute VTP payload enable mask

Interaction:

1. Config Generation: startCoda --config reads base.cnf + pedestal files → writes vme_*.cnf and vtp_*.cnf
2. Component Startup: ROL code reads vme_<hostname>.cnf or vtp_<hostname>.cnf during Download/Prestart

Important: This directory is both:

• User-managed: Edit base.cnf and run.cnf to define system configuration
• Auto-managed: vme_*.cnf, vtp_*.cnf, and *.peds are generated automatically

---

coda_tmp_log/

Purpose: Runtime log file storage (auto-created)

Contents:

• <hostname>_<component>_lastsession.log - Component session logs
  • Captures stdout/stderr from remote component shells
  • Example: test2_ROC1_lastsession.log, test2vtp_FPGA1_lastsession.log
• platform_output_*.log - Platform startup logs (realtime capture)
• Pedestal measurement output
• Startup stage diagnostics

Lifecycle:

• Created: Automatically by startCoda on first run
• Updated: Each component launch overwrites previous session log
• Cleanup: May be deleted between runs (not version controlled)

Use Case: Troubleshooting component failures, verifying pedestal measurements, debugging startup issues

---

db/

Purpose: CODA COOL database storage

Contents:

• CODA COOL database files
• Run type definitions
• Session configurations
• Run control document storage

Usage:

• Read/written by rcPlatform and rcGUI
• Stores run configuration metadata
• Manages session state and run types

Important:

• Do not manually edit database files unless performing database maintenance
• Database corruption can cause run control failures
• Backup before any manual modifications

---

firmware/

Purpose: Hardware firmware image storage

Contents:

• FADC firmware images (.bin files)
• VTP FPGA firmware images:
  • Z7 (Zynq-7000) firmware files
  • V7 (Virtex-7) firmware files

Usage:

• Referenced by VTP configuration (VTP_FIRMWARE_Z7, VTP_FIRMWARE_V7 in config files)
• Loaded during VTP Download transition via vtpZ7CfgLoad() and vtpV7CfgLoad()
• Must match expected firmware versions defined in vtp_<hostname>.cnf

Configuration:

• Firmware directory: $CODA_FIRMWARE (or $CODA/firmware fallback)
• Filenames defined in config files (e.g., fe_vtp_z7_streamingv3_ejfat_v5.bin)

Versioning: Firmware files are typically specific to hardware revisions and experiment requirements.

---

rol/

Purpose: Readout List (ROL) source code and compiled shared objects

ROLs are C programs that control hardware during CODA transitions (Download, Prestart, Go, End). They are compiled into shared objects (.so) and loaded by CODA run control.

Subdirectories

rol/vme/ - VME ROC Readout Lists

• Source code for VME-based readout controllers
• Controls FADC modules via VME bus
• Compiled to .so files loaded during Download

rol/vtp/ - VTP Library Source (if present)

• VTP hardware library source code
• May contain libvtp.so and related utilities
• Typically compiled separately and linked by VTP ROLs

rol/vtp_rol/ - VTP ROC Readout Lists

• vtp_sro_1udp.c - Main VTP streaming readout list (single UDP connection)
• VTP_source.h - VTP-specific CODA macros
• Makefile - Build system
• vtp_sro_1udp.so - Compiled shared object (loaded by CODA)

Configuration:

• VTP ROL reads $CODA_CONFIG/vtp_<hostname>.cnf during Download/Prestart
• VME ROL reads $CODA_CONFIG/vme_<hostname>.cnf

Build Process:

cd rol/vtp_rol
make clean
make vtp_sro_1udp.so

Deployment:

• Shared objects (.so) are loaded by CODA run control during Download transition
• ROL functions (rocDownload, rocPrestart, rocGo, rocEnd, rocTrigger) control hardware lifecycle

Documentation: See rol/vtp_rol/README.md for VTP ROL configuration and build instructions.

---

System Workflows

Normal Startup (Without Config Generation)

startCoda --file config/run.cnf

Sequence:

1. startCoda reads config/run.cnf (component definitions)
2. Launches components on remote hosts via remote_vme
   • ROC: Starts coda_roc (loads rol/vtp_rol/vtp_sro_1udp.so)
   • FPGA: Starts VTP component
   • PEB, ER, etc.: Start respective processes
3. Starts rcPlatform in background
4. Waits for AFECS container registration
5. Starts rcGUI (final step)

Config Usage:

• ROL code reads existing vme_<hostname>.cnf and vtp_<hostname>.cnf from config/
• No config generation occurs

Logs: Component sessions logged to coda_tmp_log/

---

Config Mode Startup (With Pedestal Measurement)

startCoda --file config/run.cnf --config

Sequence:

1. startCoda reads config/run.cnf (component definitions)
2. Pedestal Measurement Phase:
   • ROC components execute fadc250peds on remote hosts
   • Pedestal data written to $CODA_CONFIG/<hostname>.peds
   • Waits for file closure (3 consecutive identical size readings)
3. Config Generation Phase:
   • Reads config/base.cnf (VME and VTP template sections)
   • Parses <hostname>.peds to extract FADC slot list
   • Generates config/vme_<hostname>.cnf:
     • VME section from base.cnf
     • Appended pedestal data from <hostname>.peds
   • Generates config/vtp_<hostname>.cnf:
     • VTP section from base.cnf
     • MAC/IP from base.cnf mapping table
     • Computed VTP_PAYLOAD_EN from FADC slots
4. Component Startup Phase:
   • ROC components start coda_roc (using newly generated configs)
   • Other components start normally
5. Starts rcPlatform in background
6. Waits for AFECS container registration
7. Starts rcGUI (final step)

Directory Interaction:

config/base.cnf ──┐
config/*.peds ────┼──> coda_scripts/startCoda ──> config/vme_*.cnf
                  │                             └─> config/vtp_*.cnf
                  │
                  └──> firmware/*.bin (referenced by VTP config)

rol/vtp_rol/vtp_sro_1udp.so ──> Reads config/vtp_*.cnf at Download

Logs: Pedestal measurements and component sessions logged to coda_tmp_log/

---

Environment Variables

Required environment variables (set in setupCODA3.bash or equivalent):

Variable	Description	Example
CODA	CODA installation directory	/site/coda/3.10_devel
CODA_SCRIPTS	Path to coda_scripts/ directory	/path/to/coda-usr/coda_scripts
CODA_CONFIG	Path to config/ directory	/path/to/coda-usr/config
CODA_FIRMWARE	Path to firmware/ directory	/path/to/coda-usr/firmware (or $CODA/firmware)
SESSION	CODA session name (optional)	session
EXPID	Experiment ID (optional)	hallb

Note: CODA_COMPONENT_TABLE is set internally by startCoda from --file argument. Do not set manually.

---

Quick Start

1. Setup Environment

source /path/to/setupCODA3.bash

2. Normal Startup

cd $CODA_SCRIPTS
./startCoda --file config/run.cnf

3. Config Generation + Startup

cd $CODA_SCRIPTS
./startCoda --file config/run.cnf --config

4. Shutdown

cd $CODA_SCRIPTS
./kcoda --file config/run.cnf

---

Documentation

• Startup Scripts: coda_scripts/README.md - Detailed startCoda usage and troubleshooting
• VTP ROL: rol/vtp_rol/README.md - VTP configuration, firmware, and build instructions
• Stage Documentation: coda_scripts/*.md - Implementation notes for each development stage

---

Troubleshooting

Component Won't Start

1. Check coda_tmp_log/<hostname>_<component>_lastsession.log
2. Verify environment variables are set (echo $CODA, echo $CODA_CONFIG)
3. Ensure config files exist: ls -l config/vtp_*.cnf config/vme_*.cnf

Config Generation Fails

1. Verify config/base.cnf exists and contains VME/VTP sections
2. Check pedestal files were generated: ls -l $CODA_CONFIG/*.peds
3. Review config generation output in console
4. Check MAC/IP mapping exists in base.cnf for all ROC hosts

ROL Undefined Symbol Errors

cd rol/vtp_rol
git pull
make clean
make vtp_sro_1udp.so

Platform Won't Start

1. Check coda_tmp_log/platform_output_*.log
2. Verify CODA database is intact: ls -l db/
3. Ensure port 20000 (or configured port) is available
4. Check AFECS container registration in platform log

---

Contributing

When modifying this repository:

1. Scripts: Update coda_scripts/README.md if changing startup behavior
2. ROLs: Update rol/vtp_rol/README.md if changing VTP configuration
3. Config: Document config key changes in both READMEs
4. Testing: Run test scripts in coda_scripts/test_*.sh

---

Repository: https://github.com/JeffersonLab/coda-usr Author: Vardan Gyurjyan