// Mini SoC architecture overview.
// Render with: dot -Tsvg docs/mini-soc-block-diagram.dot -o docs/mini-soc-block-diagram.svg
// Sources of truth: rtl/mini/top/{retrosoc_asic,retrosoc,bus}.sv and
// rtl/mini/integration/{soc_topology,user_extensions,clock_reset_domains}.json.
digraph mini_soc_block_diagram {
  graph [
    bgcolor="transparent",
    compound=true,
    fontname="Arial",
    fontsize=18,
    label="retroSoC Mini SoC Architecture",
    labelloc="t",
    labeljust="l",
    newrank=true,
    nodesep=0.38,
    rankdir=TB,
    ranksep=0.62,
    splines=polyline
  ];

  node [
    color="#4B5563",
    fontcolor="#111827",
    fontname="Arial",
    fontsize=10,
    margin="0.12,0.08",
    penwidth=1.1,
    shape=box,
    style="rounded,filled"
  ];
  edge [
    arrowsize=0.7,
    color="#4B5563",
    fontcolor="#374151",
    fontname="Arial",
    fontsize=8,
    penwidth=1.2
  ];

  ext_clock [
    fillcolor="#F3F4F6",
    label="External clocks and reset\next_clk, aud_clk, reset"
  ];
  ext_io [
    fillcolor="#F3F4F6",
    label="External I/O and memory\nGPIO, UART0, XPI Flash, SDRAM, PSRAM\nSD card, I2C, I2S, DVP and WS2812"
  ];
  ext_jtag [
    fillcolor="#F3F4F6",
    label="Management JTAG\nTCK, TMS, TDI, TRST_n, TDO"
  ];

  subgraph cluster_asic {
    color="#111827";
    fontcolor="#111827";
    fontname="Arial";
    fontsize=14;
    label="retrosoc_asic";
    margin=18;
    style="rounded";

    rcu [
      fillcolor="#EDE9FE",
      label="RCU\nclock buffering and reset synchronization\nPLL CDC and fixed 1 MHz timebase"
    ];

    subgraph cluster_soc {
      color="#94A3B8";
      fontcolor="#334155";
      fontname="Arial";
      fontsize=12;
      label="retrosoc";
      margin=16;
      style="rounded,dashed";

      mgmt_core [
        fillcolor="#DDF2E3",
        label="Management core\nFixed Hazard3, branch predictor\nJTAG Debug Module always present"
      ];
      jtag_dtm [
        fillcolor="#E5E7EB",
        label="Hazard3 JTAG DTM\n10 MHz asynchronous TCK domain"
      ];
      debug_module [
        fillcolor="#FCE7F3",
        label="Hazard3 Debug Module\nabstract commands, no SBA\nmanagement-hart-only reset"
      ];
      mgmt_adapter [
        fillcolor="#E5E7EB",
        label="RIBP2RIB"
      ];
      user_core [
        fillcolor="#DDF2E3",
        label="Selected user core\nC0-C5, one active\nPicoRV32 at C5"
      ];
      dma [
        fillcolor="#DDF2E3",
        label="DMA\nRIB master and RIBP target"
      ];
      fabric [
        fillcolor="#DCECF8",
        label="RIB fabric\n3-master round-robin arbitration\nINCR1 / INCR4, access policy, fault reporting",
        shape=hexagon
      ];
      fault [
        fillcolor="#FCE7F3",
        label="Error slave\naccess and protocol faults"
      ];
      sram [
        fillcolor="#FFF3C9",
        label="On-chip SRAM\noptional RIB2RAM path"
      ];
      ribp_adapter [
        fillcolor="#E5E7EB",
        label="RIB2RIBP"
      ];
      apb_adapter [
        fillcolor="#E5E7EB",
        label="RIB2APB\ndirect APB bridge"
      ];
      sysctrl [
        fillcolor="#F9E1E7",
        label="SYSCTRL\nPLL, user-core select/reset/bus enable\nfault and performance control"
      ];
      clint [
        fillcolor="#F9E1E7",
        label="CLINT\nstandard 64 KiB register map\nmtime, mtimecmp and MSIP"
      ];
      ribp_targets [
        fillcolor="#F9E1E7",
        label="RIBP target wrapper\nXPI/Flash, SDRAM, PSRAM, SPI-SD and DVP\nI2S"
      ];
      uart0 [
        fillcolor="#F9E1E7",
        label="UART0 V2\n64-byte TX/RX FIFOs, fractional baud\nframing/errors, IRQ2, DMA-paced"
      ];
      i2c_controllers [
        fillcolor="#F9E1E7",
        label="I2C0 / I2C1 V2\n16-entry command/RX FIFOs, Sm/Fm/Fm+\n7/10-bit, IRQ7/19, DMA-paced"
      ];
      gpio_controller [
        fillcolor="#F9E1E7",
        label="GPIO V2\nuser + management RIBP windows\natomic I/O, filter, locks, IRQ18"
      ];
      timers [
        fillcolor="#F9E1E7",
        label="General timers 0/1\n32-bit counter, 16-bit prescaler\nperiodic / one-shot, compare, debug freeze"
      ];
      ws2812 [
        fillcolor="#F9E1E7",
        label="WS2812 TX\n24-bit MSB-first serializer\n16-word FIFO, IRQ17, DMA-fed"
      ];
      apb_targets [
        fillcolor="#E6F4EA",
        label="APB target wrapper\nRNG, UART1, PWM, PS/2, RTC\nwatchdog, CRC, advanced timer and user IP"
      ];
      archinfo [
        fillcolor="#E6F4EA",
        label="ARCHINFO V2\nread-only build, topology and technology identity\nlifecycle-gated 128-bit device ID"
      ];
      gpio_bridge [
        fillcolor="#E5E7EB",
        label="GPIO pad bridge\nPDK capability-adapted controls"
      ];
      irq [
        fillcolor="#FCE7F3",
        label="Interrupt aggregation\nRIBP and APB target IRQs to management core"
      ];
    }
  }

  { rank=same; jtag_dtm; debug_module; mgmt_core; }
  { rank=same; user_core; dma; }
  { rank=same; fault; fabric; sram; }
  { rank=same; ribp_adapter; apb_adapter; }
  { rank=same; sysctrl; clint; ribp_targets; uart0; i2c_controllers; gpio_controller; timers; ws2812; archinfo; apb_targets; }
  { rank=same; gpio_bridge; irq; }

  ext_clock -> rcu [label="clock / reset"];
  ext_jtag -> jtag_dtm [label="JTAG pads"];
  rcu -> fabric [label="system clock / reset", style=dashed];

  jtag_dtm -> debug_module [label="DMI, asynchronous CDC"];
  debug_module -> mgmt_core [label="halt, resume, abstract commands"];
  debug_module -> mgmt_adapter [label="reset after bridge idle", style=dashed];
  debug_module -> timers [label="halted", style=dashed];
  rcu -> clint [label="1 MHz tick", style=dashed];

  mgmt_core -> mgmt_adapter [label="RIBP"];
  mgmt_adapter -> fabric [label="RIB"];
  user_core -> fabric [label="RIB"];
  dma -> fabric [label="RIB"];

  fabric -> fault [label="invalid / denied", dir=both];
  fabric -> sram [label="RIB"];
  fabric -> ribp_adapter [label="RIB"];
  fabric -> apb_adapter [label="RIB"];
  ribp_adapter -> sysctrl [label="RIBP"];
  ribp_adapter -> clint [label="RIBP"];
  ribp_adapter -> ribp_targets [label="RIBP"];
  ribp_adapter -> uart0 [label="RIBP"];
  ribp_adapter -> i2c_controllers [label="RIBP"];
  ribp_adapter -> gpio_controller [label="RIBP\nuser/admin"];
  ribp_adapter -> timers [label="RIBP"];
  ribp_adapter -> ws2812 [label="RIBP"];
  apb_adapter -> archinfo [label="APB"];
  apb_adapter -> apb_targets [label="APB"];

  ribp_targets -> gpio_controller [label="alternate functions"];
  gpio_controller -> gpio_bridge [label="pad control"];
  gpio_controller -> irq [label="IRQ18"];
  timers -> irq [label="IRQ3 / IRQ4"];
  clint -> irq [label="machine IRQ0 / IRQ1"];
  ws2812 -> gpio_bridge [label="GPIO2 ALT1"];
  dma -> ws2812 [label="TXDATA writes", style=dashed];
  ws2812 -> irq [label="IRQ17"];
  dma -> uart0 [label="TX/RX data", style=dashed];
  uart0 -> irq [label="IRQ2"];
  i2c_controllers -> gpio_controller [label="GPIO3/4 ALT1\nGPIO7/8 ALT0"];
  dma -> i2c_controllers [label="DATA_CMD / RXDATA", style=dashed];
  i2c_controllers -> irq [label="IRQ7 / IRQ19"];
  apb_targets -> gpio_controller [label="user_gpio"];
  ribp_targets -> ext_io [dir=both, label="device interfaces"];
  uart0 -> ext_io [dir=both, label="UART pads"];
  gpio_bridge -> ext_io [dir=both, label="pad control"];
}