# DigitalDownConverter — Pipeline

## Architecture

```{mermaid}
graph TD
    recv["mkrecv\n(SPEAD2 capture)"]
    ibuf["Input DADA\nring buffer"]
    ddc["ddc_processing\n(GPU kernel)"]
    obuf["Output DADA\nring buffer"]
    mksend["mksend\n(SPEAD2 sender)"]
    diskwriter["disk writer"]

    recv -->|"time-domain heaps"| ibuf
    ibuf --> ddc
    ddc -->|"subband data"| obuf
    obuf --> mksend
    obuf --> diskwriter
```

<!-- AI-GENERATED:START name="pipeline_description" -->
The pipeline uses three processes sharing two PSRDADA ring buffers pinned to GPU-local NUMA
memory:

1. **mkrecv** captures SPEAD2 heaps from the network and writes them into the input ring
   buffer. It is assigned to cores on the NIC's NUMA node.
2. **ddc_processing** reads blocks from the input buffer, applies the polyphase filter bank
   and digital down-conversion on GPU, and writes interleaved lower/upper sideband output
   into the output ring buffer. Up/downsampling factors are computed from the ratio of input
   to output sample rate.
3. **mksend** (one instance per `output_type: network` entry) reads from the output buffer
   and transmits SPEAD2 multicast streams. A disk writer handles `output_type: disk`.

Buffer slot sizes are derived from the `DDCProcessorDataModel` properties
(`input_buffer_size`, `output_buffer_size`) and must satisfy alignment constraints for the
resampling filter.
<!-- AI-GENERATED:END -->

## KATCP State Machine

```{mermaid}
stateDiagram-v2
    [*] --> idle
    idle --> configuring : configure
    configuring --> configured : success
    configuring --> error : failure
    configured --> capturing : capture_start
    capturing --> running : internal
    running --> capturing : capture_stop
    capturing --> configured : stop
    configured --> idle : deconfigure
    error --> idle : reset
```

## Configuration

```{include} ../generated/ddc_processor/config_table.md
```

### Notes

- `f_lo` determines the number of output channels: each entry produces two streams (lower
  and upper sideband), so `len(output_data_streams)` must equal `2 × len(f_lo)`.
- `output_samplerate` must be a valid subband rate (2e6, 4e6, …, 512e6 Hz).
- `dada_nslots` controls ring buffer depth; reduce if host memory is limited.
- `output_type` accepts `"network"`, `"disk"`, or both as a list.

## KATCP Sensors

| Sensor | Type | Description |
|---|---|---|
| `pipeline-status` | string | State machine state (nominal / error / panic) |
| `current-config` | string | Active configuration as JSON |
| `pipeline-version` | string | Package version |
| `edd-core-version` | string | edd-core package version |
| `output-rate` | float | Output data rate [Gbps] |