crg-design-gen

CRG Design Generator (crg-design-gen)

Merged from crg-req-to-design + cr-tree-diag-gen.

Turn a CRG requirement table into clock/reset design tables, a PLL/architecture report, and a crg-gen-ready workbook. After review, turn design tables into Draw.io / Excalidraw topology diagrams.

This skill does not generate synthesizable CRG RTL.

Pipeline

需求表 (req)
  → crg_req_to_design          # stage 1：设计表 + PLL 报告 + crg workbook
  → [人工评审 design xlsx]
  → cr_tree_diag_gen           # stage 2：拓扑图
  → [可选] crg-gen             # 另一 skill：RTL/SDC

One-shot draft (unreviewed, exploration only):

crg_req_pipeline(req.xlsx, with_diagram=true)
  → design 表 + 报告 + 可选图（summary 标 UNREVIEWED）

MCP tools

Tool names stay stable so existing agent prompts keep working.

Tool	Purpose
crg_req_to_design	Requirements table → clock_design.xlsx / reset_design.xlsx / crg_report.txt / <design>_crg.xlsx
cr_tree_diag_gen	Design table → drawio + excalidraw
cr_tree_diag_gen_drawio	Draw.io only
cr_tree_diag_gen_excalidraw	Excalidraw only
crg_req_pipeline	stage1 + optional stage2 (default with_diagram=false）

Register the bundled stdio server:

{
  "mcpServers": {
    "crg-design-gen": {
      "command": "python3",
      "args": ["/path/to/crg-design-gen/mcp_server.py"]
    }
  }
}

Stage 1 — Requirements → Design table + crg-gen workbook

python3 crg-design-gen/scripts/design_main.py \
  path/to/req_table.xlsx [output_dir]

• Input: .xlsx / .xls / .csv
• Default output directory: output/ (CLI) or <input-stem>_design/ (MCP)

File	Purpose
<design>_crg.xlsx	Main deliverable: isomorphic with the crg-gen template, can be directly modified and then run crg-gen
clock_design.xlsx	Slim clock table for tree diagram (extracted from clk_gen)
reset_design.xlsx	Slim reset table for tree diagram
crg_report.txt	PLL/architecture description
README_CRG_HANDOFF.txt	Handover description

Requirement table columns

Column name	Alias	Description
Subsystem	subsystem, module, block	Owning subsystem (supports Excel merged cells)
IP	ip, module name	Owning IP (optional)
Clock reset requirement	signal, signal name, name, clock/reset	Signal name (e.g. core_clk）
Remark	note, frequency, freq, remark	Frequency, description, etc. (e.g. 200MHz）

<design>_crg.xlsx sheets

Sheet	Content
top_info	design name / protocol / addr / design_hier… (modifiable)
clk_gen	All columns(including Clock source / Groups / ICG_* / DIV_*…)
rst_gen	All columns(including REG_NAME / SYNC / INOUT…)
user_defined_reg	Empty header, fill in registers
user_defined_intp	Empty header
user_code	Empty header
user_sdc	Empty header

Auto-filled: pad clocks get Clock source = source get_ports {name} and default Clock Groups0; test_mode / clk_gen_rst_n boilerplate rows are added.

Domain reset outputs default to SYNC=N (CRG does source combining only; sync release is not in CRG). Do not flip this to SYNC=Y just to simplify integration.

Stage 2 — Design table → diagram

# both formats
python3 crg-design-gen/scripts/tree_main.py path/to/clock_design.xlsx

# one format
python3 crg-design-gen/scripts/tree_main.py path/to/clock_design.xlsx clock_tree.drawio
python3 crg-design-gen/scripts/tree_main.py path/to/reset_design.xlsx reset_tree.excalidraw

• Use slim clock_design.xlsx / reset_design.xlsx (same source as the PRIMARY workbook)
• Default output: <input-stem>_diagram/ (MCP) or examples/output/ (CLI when no path is given)

Table type is auto-detected: a SOFT_DFLT column means reset tree, otherwise clock tree.

Clock tree columns

Column name	Description	Example
NAME	Signal name	core_clk
ATTR	input / internal / output / na	output
SRC0	Parent clock 0	pll_mux_clk
SRC1	MUX second input	pad_src_clk
MUX_DFLT	MUX default value	0
DIV	Division ratio	2
DIV_WIDTH	Divider bit width	4
DIV_DFLT	Divider default value	1
OCC	OCC control	Y
ICG	ICG control	Y
ICG_DFLT	ICG default value	1
NOTE	Comment/frequency	1000MHz

Reset tree columns

Column name	Description	Example
NAME	Signal name	core_rst_n
ATTR	input / internal / output	output
SRC0	Parent reset 0	por_rst_n
SRC1~SRC3	Additional input (AND gate)	soft_rst_n
SOFT_DFLT	Software default value	1

File	How to open
*_tree.drawio	https://app.diagrams.net
*_tree.excalidraw	https://excalidraw.com（直接拖入）

Local CLI

Entry point	Description
scripts/design_main.py	Requirements → crg-gen workbook + slim design table
scripts/tree_main.py	slim design table → diagram
scripts/crg_config_writer.py	Library for writing the workbook

# stage 1
python3 crg-design-gen/scripts/design_main.py \
  crg-design-gen/examples/input/req_table_complex.xlsx output/

# stage 2
python3 crg-design-gen/scripts/tree_main.py output/clock_design.xlsx
python3 crg-design-gen/scripts/tree_main.py output/reset_design.xlsx

Boundary with crg-gen

Skill	Artifact
crg-design-gen	Editable crg Excel + report + optional diagram
crg-gen	Generate CRG RTL + SDC based on this Excel (not included in this repository)

Edit <design>_crg.xlsx in place, then run crg-gen on that file. Do not recopy tables.

Capabilities

• Parse Excel/CSV requirement tables with bilingual fuzzy column names
• Extract frequencies such as 200MHz, 3Mhz, 20/25MHz
• Classify clocks vs resets from suffixes (_clk, _rst_n, …)
• Recognize pad/xtal/osc sources from names or notes
• Recommend a minimal PLL set via integer-divide matching, then emit clock/reset design tables
• Write a crg-gen-compatible multi-sheet workbook
• Render clock/reset trees to Draw.io and Excalidraw with hierarchical layout, MUX nodes, and frequency notes

Dependencies

pip install pandas openpyxl

For the MCP server:

pip install mcp

Algorithm notes

PLL recommendation

1. For each internal clock, try integer divides div ∈ [1, 64] from every pad clock
2. Accept a pad source when |pad_freq / div - tgt_freq| / tgt_freq ≤ 5%
3. Otherwise try an already-created PLL (higher frequency first)
4. Otherwise create a new PLL; same-frequency clocks share it

Reset tree

• PORESETn (or the first reset) is the input root
• Debug resets such as nTRST / nSRST stay independent inputs
• Remaining subsystem resets are output with SRC0 = PORESETn

Node types (diagrams)

Type	Color	Description
source_input	Green #27ae60	External input clock
source_internal	Gray #7f8c8d	Internally generated clock
na	Orange #f39c12	Intermediate node (non-output)
output	Light blue #aed6f1	Final output clock
div	White #ffffff	Divider
occ	Purple #f5eef8	Clock Gating Controller
icg	Green #d5f5e3	Clock Gating
mux	Purple #e8daef	Multiplexer
rst_and	Yellow #fff3bf	Reset AND Gate
reg	Blue #d6eaf8	Register Node
soft	Orange #fdebd0	Software Control Node

Notes

1. Multi-frequency pads such as 20/25MHz keep the first frequency as primary; the full string stays in NOTE
2. Clocks without a frequency do not get a PLL; SRC0 is left blank
3. ICG/OCC are usually absent from requirement tables and left blank for later edit
4. Same pad names in different subsystems stay independent unless renamed/merged
5. Isolated test_mode / clk_gen_rst_n inputs with no outgoing edges are hidden in diagrams
6. Excalidraw has no arc jumpers; trapezoid MUXes render as rectangles
7. Review design tables before treating diagrams as approved or handing the workbook to crg-gen