name: "64-Bin Streaming Histogram Engine"
category: "AI/ML Accelerators"
complexity: "Medium"
description: |
  Implement a synchronous accelerator that computes the exact histogram of one
  frame of unsigned 6-bit samples.

  FRAME INPUTS:
  - Each frame consists of exactly 256 accepted samples.
  - A sample is accepted on each rising edge of `clk` for which `rst=0` and
    `in_valid=1`.
  - The accepted samples of a frame are numbered `s0` through `s255` in
    acceptance order.
  - Idle cycles with `in_valid=0` may appear before the frame is complete and
    do not advance the accepted-sample count.
  - `sample_in` is an unsigned 6-bit value in the range 0 to 63.
  - Histogram bin `k` counts how many accepted samples in the frame had value
    exactly `k`.
  - The module must correctly handle back-to-back accepted samples, including
    long runs of the same value on consecutive cycles.

  ACCUMULATION THROUGHPUT:
  - During the input phase of a frame, the module must be able to accept one
    sample on every clock cycle.
  - There is no backpressure or ready signal. If `in_valid=1`, the sample for
    that cycle is part of the frame and must be counted.
  - The evaluator may drive all 256 samples on 256 consecutive cycles with
    `in_valid=1` throughout.

  OUTPUT SEQUENCE:
  - The module must not assert `out_valid` until a full 256-sample frame has
    been accepted.
  - After the 256th sample of a frame is accepted, the module must output the
    64 histogram bins on the next 64 clock cycles, with no gaps while the
    sequence is in progress.
  - If the 256th sample is accepted on cycle N, then on cycle N+1 `out_valid`
    must be high, `bin_index` must be 0, and `bin_count` must equal the count
    for value 0 from that completed frame.
  - On successive cycles while `out_valid` is high, `bin_index` must advance in
    order 1, 2, ..., 63 and `bin_count` must present the corresponding exact
    count for each bin from the same completed frame.
  - Each reported `bin_count` is a 16-bit unsigned value. For this benchmark,
    the exact count range is 0 to 256 inclusive.
  - The sum of the 64 reported `bin_count` values for a frame must be exactly
    256.
  - After the count for `bin_index=63` has been reported, `out_valid` must be
    low on the next cycle.

  FRAME BOUNDARIES:
  - After the output sequence for one frame completes, the next accepted sample
    begins a new empty histogram for the next frame. No counts may carry over
    between frames.
  - The evaluator will not present new input samples while `out_valid=1`.

  RESET:
  - `rst` is synchronous and active-high.
  - While `rst=1`, discard any partially collected frame, cancel any pending or
    active output sequence, and drive `out_valid=0`, `bin_index=0`, and
    `bin_count=0`.
  - A cycle with `rst=1` does not accept an input sample.
  - After reset is deasserted, the next accepted sample becomes `s0` of a new
    frame.

  OUTPUTS WHEN NOT READING:
  - Whenever `out_valid=0`, both `bin_index` and `bin_count` must be 0.
  - In particular, during reset, during frame accumulation, between frames, and
    after the readout of bin 63 completes, the outputs must be
    `out_valid=0`, `bin_index=0`, and `bin_count=0`.

interface:
  module_name: "streaming_histogram64"
  clocked: true
  ports:
    - name: "clk"
      type: "input"
      width: "1"
      description: "System clock"
    - name: "rst"
      type: "input"
      width: "1"
      description: "Synchronous active-high reset"
    - name: "in_valid"
      type: "input"
      width: "1"
      description: "High when `sample_in` is a valid input sample to be accepted this cycle"
    - name: "sample_in"
      type: "input"
      width: "6"
      description: "Unsigned 6-bit sample value in the range 0 to 63"
    - name: "out_valid"
      type: "output"
      width: "1"
      description: "High when `bin_index` and `bin_count` present a valid histogram output bin"
    - name: "bin_index"
      type: "output"
      width: "6"
      description: "Histogram bin number being reported, from 0 to 63"
    - name: "bin_count"
      type: "output"
      width: "16"
      description: "Exact unsigned count for the reported histogram bin in the completed 256-sample frame"

target_platform:
  device_family: "AMD Xilinx Zynq-7000"

tasks:
  - name: "High-Performance 64-Bin Histogram"
    constraints:
      max_lut: 320
      max_ff: 256
      max_bram: 2
      max_dsp: 0
      min_frequency: 250
    objective:
      goal: "maximise"
      target: "Fmax"
