name: "Complementary PWM Generator with Dead-Time"
category: "Embedded Control & I/O"
complexity: "Medium"
description: |
  Implement a synchronous PWM (Pulse-Width Modulation) generator with
  complementary outputs and configurable dead-time insertion, suitable
  for driving a half-bridge power stage.

  All outputs (`pwm_high`, `pwm_low`) must be registered — updated
  synchronously on the rising edge of `clk`. They must not be driven
  by combinational logic.

  PWM COUNTER:
  - When `enable` is HIGH, an internal 8-bit counter runs
    0, 1, 2, ..., `period - 1`, 0, ...
  - `period` is guaranteed to be in the range 1 to 255.
  - On each rising clock edge, the module evaluates the raw PWM state
    from the current counter value and determines outputs, then
    advances the counter for the next cycle.
  - The raw PWM state is HIGH when the counter value is strictly less
    than `duty`, and LOW otherwise.
  - If `duty` is 0, the raw PWM state is always LOW.
  - If `duty >= period`, the raw PWM state is always HIGH.

  OUTPUT BEHAVIOUR:
  - Outside the dead-time interval:
      raw PWM = HIGH -> `pwm_high` = 1, `pwm_low` = 0
      raw PWM = LOW  -> `pwm_high` = 0, `pwm_low` = 1
  - Whenever the running raw PWM state changes while `enable` is HIGH,
    both outputs must be driven LOW for exactly `dead_time` full clock
    cycles before the new complementary state appears.
  - During dead-time, the counter continues to run normally.
  - If `dead_time` is 0, the outputs switch with no all-low gap.

  ENABLE AND RESET:
  - `rst` is synchronous and active-high.
  - On reset, clear the counter, clear any pending dead-time, and drive
    both outputs LOW.
  - When `enable` is LOW, hold the counter at 0, clear any pending
    dead-time, and drive both outputs LOW.
  - When `enable` becomes HIGH, operation restarts from counter value 0.
    No state from an earlier enabled interval is retained.
  - Asserting `enable` is not itself treated as a PWM transition for
    dead-time purposes; only transitions of the running raw PWM state
    insert dead-time.
  - On the first clock cycle after `enable` becomes HIGH, the outputs
    must reflect the raw PWM state evaluated at counter value 0
    immediately, with no startup dead-time.

interface:
  module_name: "pwm_deadtime"
  clocked: true
  ports:
    - name: "clk"
      type: "input"
      width: "1"
      description: "Clock signal"
    - name: "rst"
      type: "input"
      width: "1"
      description: "Synchronous active-high reset"
    - name: "enable"
      type: "input"
      width: "1"
      description: "Module enable; when low, outputs are forced low and counter is held at 0"
    - name: "period"
      type: "input"
      width: "8"
      description: "PWM period in clock cycles (counter counts from 0 to period-1)"
    - name: "duty"
      type: "input"
      width: "8"
      description: "Duty cycle value; raw PWM is high when counter < duty"
    - name: "dead_time"
      type: "input"
      width: "4"
      description: "Dead-time duration in clock cycles (0 means no dead-time)"
    - name: "pwm_high"
      type: "output"
      width: "1"
      description: "High-side PWM output"
    - name: "pwm_low"
      type: "output"
      width: "1"
      description: "Low-side PWM output (complementary to pwm_high, with dead-time gaps)"

target_platform:
  device_family: "AMD Xilinx Zynq-7000"

tasks:
  - name: "Area-Efficient PWM with Dead-Time"
    constraints:
      max_lut: 80
      max_ff: 40
      max_bram: 0
      max_dsp: 0
      min_frequency: 100
    objective:
      goal: "minimise"
      target: "LUT"
