name: "Direct-Mapped Write-Through Cache"
category: "Soft Processors & Memory"
complexity: "Medium"
description: >
  Implement a direct-mapped cache controller.
  
  CACHE CONFIGURATION:
  - 256 entries (8-bit index).
  - 32-bit data words.
  - Write-through policy.
  
  ADDRESS MAPPING:
  - Address is 32-bit byte address.
  - Bits [31:10]: Tag
  - Bits [9:2]: Index
  - Bits [1:0]: Offset (Ignored, we handle full words)

  INTERFACES:
  1. CPU Interface (Blocking):
     - `cpu_req_valid`: Assertion of a request.
     - `cpu_req_ready`: Cache is ready to accept. Handshake happens when invalid writes valid && ready.
     - `cpu_req_rw`: 0 = Read, 1 = Write.
     - `cpu_resp_valid`: Asserted for one cycle when read data is ready.
  
  2. Memory Interface:
     - `mem_req_valid`: Cache requesting memory access.
     - `mem_req_rw`: 0 = Read, 1 = Write.
     - `mem_req_ready`: Memory is ready to accept request. (Assume always 1 for this problem or use valid/ready).
     - `mem_resp_valid`: Memory returning data.
  
  BEHAVIOR:
  - Hit: Respond with data immediately (1 cycle latency).
  - Miss: Read from memory, update cache, then respond.
  - Write: Always write to memory. Update cache if hit.
  
  RESET:
  - Synchronous active-high reset. Clears all cache entries.

interface:
  module_name: "cache_direct_mapped"
  clocked: true
  ports:
    - name: "clk"
      type: "input"
      width: "1"
      description: "Clock"
    - name: "rst"
      type: "input"
      width: "1"
      description: "Reset"
    - name: "cpu_req_valid"
      type: "input"
      width: "1"
      description: "CPU Request Valid"
    - name: "cpu_req_rw"
      type: "input"
      width: "1"
      description: "0: Read, 1: Write"
    - name: "cpu_req_addr"
      type: "input"
      width: "32"
      description: "CPU Address"
    - name: "cpu_req_data"
      type: "input"
      width: "32"
      description: "CPU Write Data"
    - name: "cpu_req_ready"
      type: "output"
      width: "1"
      description: "Cache Ready"
    - name: "cpu_resp_valid"
      type: "output"
      width: "1"
      description: "CPU Response Valid"
    - name: "cpu_resp_data"
      type: "output"
      width: "32"
      description: "CPU Response Data"
    - name: "mem_req_valid"
      type: "output"
      width: "1"
      description: "Memory Request Valid"
    - name: "mem_req_rw"
      type: "output"
      width: "1"
      description: "Memory Request Read/Write"
    - name: "mem_req_addr"
      type: "output"
      width: "32"
      description: "Memory Request Address"
    - name: "mem_req_data"
      type: "output"
      width: "32"
      description: "Memory Request Data"
    - name: "mem_req_ready"
      type: "input"
      width: "1"
      description: "Memory Ready"
    - name: "mem_resp_valid"
      type: "input"
      width: "1"
      description: "Memory Response Valid"
    - name: "mem_resp_data"
      type: "input"
      width: "32"
      description: "Memory Response Data"

target_platform:
  device_family: "AMD Xilinx Zynq-7000"

tasks:
  - name: "Direct Mapped Cache Controller"
    constraints:
      max_lut: 500
      max_registers: 10000
    objective:
      goal: "minimise"
      target: "LUT"
