git:20261108.9a075f0 to git:20261108.53407f2

9 added, 9 removed. Audit B to B.

---

name: vlsit-asic-ip-microspec

description: Discuss and write an ASIC IP micro-architecture specification in the VLSIT template as Markdown with TeX math; optionally export DOCX and PDF with Pandoc. Includes protocol-grounded Q&A, evidence-based reference-IP research, a CSR workbook, a draw.io block diagram, a complete port table, and user-confirmed waveforms. Use when the user wants to define or document an ASIC IP.

compatibility: Python 3.8 or later. Standard library for most scripts; openpyxl and PyMuPDF (AGPL-3.0) are optional. Pandoc is used for DOCX export; Typst is the recommended PDF engine. Install external tools or packages only after the user agrees. LaTeX is optional only for the TikZ diagram fallback. Network access is used only for reference research and approved downloads.

---

# ASIC IP micro-specification

Guides the user from an idea to a complete ASIC IP design specification in the VLSIT template. The authoritative specification is Markdown; equations use TeX math, figures use relative Markdown image links, and Pandoc can create optional DOCX and PDF deliverables. The workflow asks questions with options and examples, grounds protocol statements in converted standards, studies only silicon- or FPGA-proven reference IP, fills the CSR workbook, describes every signal, and draws the block diagram and user-confirmed waveforms. It does not write RTL.

Reply to the user in the language the user writes; write the specification in English (rule R-005).

If instructions differ, follow them in this order: [rule.md](rule.md) first, then this file, then the files in `reference/`.

## Workflow

### 1. Read the rules

Read [rule.md](rule.md) completely before doing anything else. Every rule in it is mandatory.

### 2. Find Python and check the environment

Every script in `scripts/` is Python 3. Locate a working Python before running any of them:

```powershell

powershell -NoProfile -ExecutionPolicy Bypass -File "<skill folder>\scripts\vlsit_find_python.ps1"

```

On Linux or macOS run the twin script:

```sh

sh "<skill folder>/scripts/vlsit_find_python.sh"

```

It prints the full path of a working Python 3 (called `<python>` below) and exits 0, or prints `NOT FOUND` and exits 3. Do not continue without Python and do not guess a path. Tell the user that Python 3 is needed and let them choose: install it themselves from python.org, or let you install it with `vlsit_find_python.ps1 -Install` (uses winget). Run the install only after they agree, then run the locator again.

Then run `<python> "<skill folder>\scripts\vlsit_spec_tool.py" env`. It reports openpyxl, PyMuPDF, Pandoc, Typst and the optional LaTeX diagram toolchain. DOCX export needs Pandoc; PDF export needs Pandoc and a PDF engine (Typst is the default). Install nothing without the user's yes (rule R-009); say which feature is unavailable until then.

### 3. Fix the naming rule

- Before any name is written, ask the user which naming rule the specification follows (rule R-026), with the question format of R-003: A, the default naming rule of the skill `vlsit-rtl-generator` (section 2 of `VLSIT_RTL_Design_Rule.md` v2, recommended: the RTL generator checks the same rule); B, the user's own rule file or document (ask for the path and read it completely); C, other. If the user gives no rule, use A. Record the rule, its path and its version in section 2 of the specification. Apply it to every module, port, signal, parameter, state and instance name, in the text, the tables, the diagrams and the waveforms; if the user types a name that the rule does not allow, write the allowed form and tell the user (for example `i_sw_reset_n` becomes `i_rst_n_sw` under the default rule: NAM-08 writes "rst", and an active-low reset input is `i_rst_n_<domain>`).

+ Before any name is written, ask the user which naming rule the specification follows (R-026), using the question format of R-003: A, the default naming rule of `vlsit-rtl-generator` section 2, `VLSIT_RTL_Design_Rule.md` v2; B, the user's own rule file or document (ask for its path and read it completely); C, other. If the user gives no rule, use A and record the rule, path and version in section 2 (R-054). Apply the selected rule to every module, port, signal, parameter, state and instance name in the text, tables, diagrams and waveforms (R-055); if the user supplies a forbidden name, use the allowed form and explain the clause (R-056).

### 4. Understand the IP

- Ask the user what the IP does, its protocols, configurations, performance goals and constraints, and the real-world application of each main feature (rule R-041: which product or system uses it, what number the application fixes, what fails without it; for a PWM generator, for example, the dead-time feature serves the three-phase inverter of a brushless motor drive). Use the question style of [reference/vlsit_question_bank.md](reference/vlsit_question_bank.md): at most four questions per message, each with options, explanations, an example and an open choice (rule R-003). Record every "you decide" as an assumption (rule R-004).

+ Ask the user what the IP does, its protocols, configurations, performance goals and constraints, and the real-world application of each main feature (R-041, R-046 to R-048): which concrete product or system uses it, what measurable need it has, and what fails without it. Use the question style of [reference/vlsit_question_bank.md](reference/vlsit_question_bank.md): at most four questions per message, each with options, explanations, an example and an open choice (R-003). Record every "you decide" as an assumption (R-004).

### 5. Ground the protocols

For each protocol, confirm the revision and role with the user, then read the relevant section with `vlsit_protocol_docs.py` (see [reference/vlsit_protocol_catalog.md](reference/vlsit_protocol_catalog.md) and [reference/md_doc/vlsit_INDEX.md](reference/md_doc/vlsit_INDEX.md)). If the standard is not in `reference/md_doc/`, ask the user to supply it or to approve a download (rules R-006, R-009), then convert it with `vlsit_doc_to_md.py` or `vlsit_pdf_to_md.py` (rules R-007, R-008).

### 6. Research reference IP

Search GitHub and Gitee with `vlsit_ip_search.py`, and read Chinese-language pages in depth (rule R-011). Apply the evidence filter of rule R-010 and show the user a short table of qualified and excluded IP with the evidence links. Criteria and the research log format are in [reference/vlsit_ip_reference_criteria.md](reference/vlsit_ip_reference_criteria.md). Download only what the user approves (rule R-009); for OpenCores projects the skill `vlsit-opencore-ip-downloader` can be used.

### 7. Discuss the specification section by section

Walk through the template sections with the user in groups, using [reference/vlsit_spec_writing_guide.md](reference/vlsit_spec_writing_guide.md) for the content of each section and the question bank for the questions. When the user says a section is not needed, record it with `vlsit_spec_tool.py mark-not-required` (rule R-014).

For section 6.2, describe every input and output with its function, its clock domain and its signal type: level, pulse (with the width in cycles), clock, reset, data (with the qualifier that makes it valid) or static (rule R-025). Ask the user about each port whose type or clock domain is not clear; the signal-type questions are in the question bank.

- For section 11.2, agree on the ordinary programming/use sequence and any optional mode paths. The flowchart and matching step table are required by rule R-043 even when the IP has no CSR; in that case identify the non-CSR interface and explain why the CSR column is N/A. Do not mark a step optional unless its condition and alternate path are clear.

+ For section 11.2, agree on the ordinary programming/use sequence and any optional mode paths. The flowchart and matching step table are required by R-043 and R-060 to R-065 even when the IP has no CSR; in that case identify the non-CSR interface and explain why the CSR column is N/A. Do not mark a step optional unless its condition and alternate path are clear.

### 8. Write the specification

```powershell

<python> "<skill folder>\scripts\vlsit_spec_tool.py" init "<IP name>" --out "VLSIT_<DESIGN_FUNCTION>_HDS.md"

```

`init` also adds the `Signal type` column to the port table of 6.2 and the waveform plan table to 10.3. Fill every section (rule R-013) with REQ-IDs, a verification method and a traceability row for each requirement (rule R-015). Do not copy reference code (rule R-012). A complete worked example is in [example/apb_tlul_bridge/](example/apb_tlul_bridge/README.md).

Keep this Markdown file as the authoritative specification. Write inline equations as TeX `$...$`, display equations as `$$...$$`, and link figures with relative Markdown image paths under `figures/`. Use [reference/vlsit_document_formats.md](reference/vlsit_document_formats.md) for syntax examples and export behavior (rules R-044 and R-045).

### 9. Registers

- If the IP has software-visible registers, the register RTL will be built by APB-CSR-Generator from the workbook (the RTL skill runs it), so plan the registers for what that generator can build. Read [reference/vlsit_csr_generator.md](reference/vlsit_csr_generator.md) first. Ask the questions of the question bank (Registers, rule R-030): for each function of the IP the settings (`rw`), values that software writes but must not read back (`wo`), the hardware clear source for every `wo` field (including zeroize), the actions that software starts and hardware finishes (`rwi`), the live state (`ro`), the sticky events (`w1c`), the reset values, the software sequences and whether the register clock differs from the APB clock. Describe the answer in JSON, validate it, fill the workbook, and print the module ports for the specification; section 11 points to the workbook and states the connection and the APB behavior (rules R-016, R-031). Details in [reference/vlsit_csr_workbook.md](reference/vlsit_csr_workbook.md).

+ If the IP has software-visible registers, the register RTL will be built by APB-CSR-Generator from the workbook (the RTL skill runs it), so plan the registers for what that generator can build. Read [reference/vlsit_csr_generator.md](reference/vlsit_csr_generator.md) first. Ask the question-bank items (Registers, R-030): for each function, identify `rw`, `wo`, `rwi`, `ro` and `w1c` fields, reset values, software sequences and whether the register clock differs from APB. Describe the answer in JSON, validate it, fill the workbook and print module ports for the specification; section 11 records the workbook, the generator's behavior (R-031), and any unsupported behavior with the user's decision (R-049 to R-050). Details in [reference/vlsit_csr_workbook.md](reference/vlsit_csr_workbook.md).

```powershell

<python> "<skill folder>\scripts\vlsit_csr_tool.py" validate regs.json

<python> "<skill folder>\scripts\vlsit_csr_tool.py" fill regs.json --out "<IP>_CSR.xlsx" --auto-reserved

<python> "<skill folder>\scripts\vlsit_csr_tool.py" ports regs.json

```

- Use the module name of the project naming rule (rule R-026) in the JSON. Ask the user for the design prefix of the register names (question bank 25) and write every register and field name and description as rules R-032 to R-034 and R-037 require: `<prefix>_<function>` register names, fields of at most 20 characters, a one-line register description and a field description with `Usage: `, a `Values:` block of hexadecimal value lines (rule R-037), `Unit: ` and `Limits: ` (question 26); `validate` checks these. Fill sections 11.1, 11.3 and 11.4 of the template from the `ports` output and the generator reference; ask the user for the source of `i_protect_en` and `i_slverr_en`, for the connection of each field to the design, and for the decision on every limit of the generator that the IP meets (rule R-031). Then write the 11.2 Mermaid programming/use flowchart and its six-column step table from the agreed sequence (rule R-043); if the IP has no software-visible CSR, state why in the CSR column and document its actual usage interface.

+ Use the module name required by the selected project naming rule (R-026, R-054 to R-056) in the JSON. Ask for the design prefix of register names (question bank 25) and follow R-032 to R-034, R-037 and R-051 for naming and field descriptions: `<prefix>_<function>` registers, fields of at most 20 characters, a one-line register description and a field description with `Usage: `, a hexadecimal `Values:` block, `Unit: ` and `Limits: `; `validate` checks these. Fill sections 11.1, 11.3 and 11.4 from the `ports` output and generator reference; ask the user about `i_protect_en`, `i_slverr_en`, field connections and each applicable generator limit (R-031, R-049 and R-050). Then write the 11.2 Mermaid programming/use flowchart and six-column step table under R-043 and R-060 to R-065; if there is no software-visible CSR, state why the CSR column is N/A and document the actual usage interface.

### 10. Waveform plan, block diagram and waveforms

1. **Agree the waveform plan first (rule R-024).** From sections 6.3 and 10.2 build a list with an ID (WF-001, ...), the function or operation, the scenario (success, error or corner case) and the signals shown. It must cover every operation of 10.2, the success and the error case of every interface, and the special cases of this IP (reset, backpressure, back-to-back, boundary, timeout). Show the list to the user and ask which waveforms are the minimum, with the question format of R-003: for example A, the proposed list (recommended); B, only one success and one error per interface; C, the proposed list plus extra corner cases; D, the user's own list. Record the answer in the table of section 10.3 with the date; a waveform the user declines gets a dated Not required line in its Figure cell. Draw nothing before the answer.

2. Draw the block diagram with draw.io (rules R-018 to R-020, R-027 to R-029): fill a diagram spec JSON from sections 5, 6 and 14.2 (`vlsit_spec_diagram.py template` or `from-spec`), run `vlsit_spec_diagram.py check`, `build` (draw.io, library validation, geometry check, SVG) and `insert` (section 5.2); the rules are in [reference/drawio/vlsit_diagram_rules.md](reference/drawio/vlsit_diagram_rules.md). LaTeX (`vlsit_block_diagram.py`) is the fallback.

- 3. Describe each waveform of the plan as WaveJSON and render it to SVG (rule R-017); link the image in the Figure cell of the plan. Formats and commands are in [reference/vlsit_diagrams_and_waveforms.md](reference/vlsit_diagrams_and_waveforms.md). Waveforms need no LaTeX; the block diagram of step 10.2 is draw.io by default (rules R-018 to R-020; the library and reference diagram are in [reference/drawio/](reference/drawio/README.md)).

+ 3. Describe each waveform of the plan as WaveJSON and render it to SVG (R-017 and R-057 to R-058); link the image in the Figure cell of the plan. Formats and commands are in [reference/vlsit_diagrams_and_waveforms.md](reference/vlsit_diagrams_and_waveforms.md). Waveforms need no LaTeX; the block diagram of step 10.2 is draw.io by default (rules R-018 to R-020; the library and reference diagram are in [reference/drawio/](reference/drawio/README.md)).

### 11. Check and review

Run `vlsit_spec_tool.py check` (add `--naming user` when the user supplied their own naming rule, and then check the names by hand against that rule) and fix every error. Review the open items (section 20) with the user and ask which are resolved. When a step recurred without a script, propose a new script (rule R-021).

### 12. Export the selected deliverables

If the user has not specified output formats, ask them to choose: A, Markdown only (small and easy to diff in Git; drawback: no Word/PDF review copy; example: commit the `.md` and `figures/` folder); B, Markdown and DOCX (reviewers can edit and comment in Word; drawback: page layout can reflow and company styles need a reference DOCX; example: send DOCX to the design-review team); C, Markdown and PDF (fixed layout for sharing; drawback: not directly editable; example: attach the PDF to a review package); D, all three (recommended when the project needs Git history, Word review and stable sharing; drawback: regenerate DOCX/PDF after source edits; example: keep `.md` in Git and distribute the DOCX/PDF); E, another combination. Explain that the `.md` remains the source in every option. Give a short reason and example for each option, then use the user's choice. Do not ask again when the requested formats are already clear.

Generate DOCX and/or PDF from the Markdown source with `scripts/vlsit_spec_export.py`; never edit the generated files as the source. Use `--reference-doc` only when the user supplies or selects a Word style template. PDF uses Pandoc with Typst by default; an installed alternative engine may be selected. If the selected engine is missing, report the dependency and do not install it without approval. Read [reference/vlsit_document_formats.md](reference/vlsit_document_formats.md) before exporting. Confirm that each requested file exists and has nonzero size (rule R-045).

### 13. Verify against the rules

- Check the result against every rule ID in [rule.md](rule.md): R-013, R-014, R-015, R-016, R-019, R-020, R-024, R-025, R-026, R-031, R-041, R-043, R-044 and R-045 by the script outputs where supported and otherwise by inspection of the conversation and files. Report which rules were verified and how, and say plainly what could not be verified.

+ Check the result against every rule ID in [rule.md](rule.md), using script outputs where supported and otherwise inspecting the conversation and files. Include every applicable rule from R-046 to R-065 in this review. Report which rules were verified and how, and say plainly what could not be verified.

## Reference

Read a file only when the step needs it.

| File | Read it when |

|---|---|

| [reference/vlsit_question_bank.md](reference/vlsit_question_bank.md) | Steps 3, 4 and 7: wording of questions with options and examples |

| [reference/vlsit_protocol_catalog.md](reference/vlsit_protocol_catalog.md) | Step 5: which protocols and revisions to look for, where to get them, licences |

| [reference/md_doc/vlsit_INDEX.md](reference/md_doc/vlsit_INDEX.md) | Step 5: the converted standards available now |

| [reference/vlsit_ip_reference_criteria.md](reference/vlsit_ip_reference_criteria.md) | Step 6: evidence filter and research log format |

- | [reference/vlsit_spec_writing_guide.md](reference/vlsit_spec_writing_guide.md) | Steps 7 and 8: what each template section must contain, including the required programming/use flow in 11.2 (R-043) |

+ | [reference/vlsit_spec_writing_guide.md](reference/vlsit_spec_writing_guide.md) | Steps 7 and 8: what each template section must contain, including applications (R-041, R-046 to R-048) and the programming/use flow in 11.2 (R-043, R-060 to R-065) |

| [reference/vlsit_document_formats.md](reference/vlsit_document_formats.md) | Steps 8 and 12: Markdown/TeX syntax, Pandoc DOCX/PDF export, PDF engine requirements and optional Word reference styles |

| [reference/vlsit_csr_workbook.md](reference/vlsit_csr_workbook.md) | Step 9: workbook layout and JSON format |

| [reference/vlsit_csr_generator.md](reference/vlsit_csr_generator.md) | Step 9: what APB-CSR-Generator builds, its limits, field types, APB behavior, what section 11 must state |

| [reference/vlsit_diagrams_and_waveforms.md](reference/vlsit_diagrams_and_waveforms.md) | Step 10: diagram and waveform formats |

| [reference/drawio/README.md](reference/drawio/README.md) | Step 10 with draw.io: the library and the reference diagram |

| [reference/templates/VLSIT_ASIC_IP_Design_Specification_Template.md](reference/templates/VLSIT_ASIC_IP_Design_Specification_Template.md) | Step 8: the template (copied by `vlsit_spec_tool.py init`) |

- | [reference/templates/VLSIT_RTL_Design_Rule.md](reference/templates/VLSIT_RTL_Design_Rule.md) | Steps 3, 7 and 8: naming and coding rules the specification must follow (the default naming rule, R-026) |

+ | [reference/templates/VLSIT_RTL_Design_Rule.md](reference/templates/VLSIT_RTL_Design_Rule.md) | Steps 3, 7 and 8: naming and coding rules the specification must follow (R-026 and R-054 to R-056) |

| [reference/templates/README.md](reference/templates/README.md) | Step 8: the original README of the spec_template folder (the three template files here are exact copies; the draw.io library is in `reference/drawio/`) |

| [reference/templates/VLSIT_CSR_Specification_Template.xlsx](reference/templates/VLSIT_CSR_Specification_Template.xlsx) | Step 9: the workbook template (copied by `vlsit_csr_tool.py fill`) |

| [reference/org_doc/README.md](reference/org_doc/README.md) | Step 5: where original documents are kept and why |

| [example/apb_tlul_bridge/README.md](example/apb_tlul_bridge/README.md) | Step 8: a finished specification with block diagram and waveforms |

## Scripts

Run each script as `<python> "<skill folder>\scripts\<script>.py" <action>`.

| Script | Run it when |

|---|---|

| `scripts/vlsit_find_python.ps1` (Windows), `scripts/vlsit_find_python.sh` (Linux, macOS) | Before the first Python script, and again after Python was installed |

| `scripts/vlsit_spec_tool.py` | Steps 2, 8, and 11: `env`, `init` (adds the signal-type column and the waveform plan table), `check` (also checks the port table and the waveform plan), `sections`, `mark-not-required` |

| `scripts/vlsit_spec_export.py` | Step 12: export the Markdown source to selected DOCX/PDF formats with Pandoc |

| `scripts/vlsit_protocol_docs.py` | Step 5: `list`, `toc`, `section`, `search`, `index`, `fetch` (only with approval) |

| `scripts/vlsit_doc_to_md.py` | Step 5: convert DOCX, HTML, Markdown or text standards; `verify` the result |

| `scripts/vlsit_pdf_to_md.py` | Step 5: convert PDF standards (needs PyMuPDF); `verify` the result |

| `scripts/vlsit_pdf_render.py` | Step 10: turn a compiled PDF diagram into SVG or PNG (needs PyMuPDF) |

| `scripts/vlsit_ip_search.py` | Step 6: `search` GitHub or Gitee, `evaluate` one page |

| `scripts/vlsit_csr_tool.py` | Step 9: `validate`, `fill`, `dump` the CSR workbook and `ports` (the module ports that the generator builds) (needs openpyxl) |

| `scripts/vlsit_spec_diagram.py` | Step 10: `template`, `from-spec`, `check`, `build`, `insert` (draw.io block diagram, with `vlsit_drawio_frame_diagram.py`, `vlsit_drawio_geometry_check.py`, `vlsit_drawio_to_svg.py`, `vlsit_layout_search.py`) |

| `scripts/vlsit_block_diagram.py` | Step 10 fallback: `check`, `tex`, `build`, `drawio` |

| `scripts/vlsit_waveform_svg.py` | Step 10: render WaveJSON to SVG |

| `scripts/vlsit_library_symbols.py` | Step 10 with draw.io: `validate` a .drawio file against the VLSIT library |

| `scripts/vlsit_approved_packages.txt` | Not run: the record of the third-party packages the user approved (openpyxl, PyMuPDF; rule R-022); `vlsit_skillkit.py validate` reads it |

## Output

Save the authoritative specification as `VLSIT_<DESIGN_FUNCTION>_HDS.md` (uppercase function name, spaces and hyphens replaced by underscores; rule R-042) with a `figures/` folder (diagram, waveform sources and images) and, when registers exist, the CSR workbook beside it, in the folder the user names; ask when no folder was named. Save only the DOCX/PDF formats the user selected. Report the paths, the `vlsit_spec_tool.py check` result, the open items of section 20, the rules verified, and what is untested.