layout: true class: typo, typo-selection --- count: false class: nord-dark, middle, center # π Liberty (.lib) β JSON ### From EDA Cell Libraries to Structured Data @luk036 π¨βπ» Β· 2026 π Β· netlistx π¬ --- ### π Agenda .pull-left[ **Part 1: Liberty Format** ποΈ - What is a .lib file? π - File Structure: Recursive Groups π³ **Part 2: The Parser Challenge** π - liberty-parser API Quirks π³οΈ - The Data Model 𧩠**Part 3: JSON Conversion** π οΈ - Custom JSON Serialization π§ - JSON Output Structure π - JSON Schema Validation β ] .pull-right[ **Part 4: Verilog β Liberty** π€ - Generating Liberty from Verilog π - Sphere Netlist Case Study π― - FIR Filter Case Study π― **Part 5: Agent Skills & Lessons** π‘ - Agent Skills: Package the Knowledge π¦ - Common Pitfalls π³οΈ - End-to-End Pipeline π **Part 6: Summary & Resources** π - Summary β - Resources π ] --- class: nord-light, middle, center ## Part 1: Liberty Format ποΈ --- ### ποΈ What is the Liberty (.lib) Format? **Synopsys Liberty** is the industry-standard ASCII format for semiconductor cell library characterization .pull-left[ .font-sm[ | Feature | Description | |---------|-------------| | **Timing** | Cell delays, transition times via lookup tables | | **Power** | Internal, leakage, switching consumption | | **Signal Integrity** | Noise, crosstalk immunity | | **Test** | DFT information | ] ] .pull-right[ .mermaid[ <pre> graph TD subgraph "Liberty .lib File" L[Library] --> H[Header: technology, units, PVT] L --> OC["operating_conditions (typical)"] L --> T["lu_table_template (delay_2x2)"] L --> C1["cell (AND2_X1) π’"] L --> C2["cell (DFF_X1) π΅"] L --> C3["cell (INV_X1) π "] C1 --> P1["pin (A) β‘οΈ"] C1 --> P2["pin (B) β‘οΈ"] C1 --> P3["pin (Z) β¬ οΈ"] P3 --> T1["timing ()"] T1 --> CR["cell_rise (table)"] T1 --> RT["rise_transition (table)"] end style L fill:#e8eaf6,stroke:#283593,color:#2e3440,stroke-width:3px style H fill:#e8eaf6,stroke:#283593,color:#2e3440,stroke-width:3px style C1 fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px style C2 fill:#e3f2fd,stroke:#1565c0,color:#2e3440,stroke-width:3px style C3 fill:#fff3e0,stroke:#e65100,color:#2e3440,stroke-width:3px </pre> ] ] All major EDA vendors (Synopsys, Cadence, Siemens) use it across PVT corners. --- ### π Liberty File Structure: Recursive Groups Every Liberty file is a **tree of groups** β each with a type, arguments, attributes, and nested subgroups: .pull-left[ .font-sm[ ``` library (example_minimal) { technology ("cmos") ; time_unit : "1ns" ; delay_model : "table_lookup" ; cell (AND2_X1) { area : 5.0 ; pin (Z) { direction : output ; function : "(A & B)" ; timing () { related_pin : "A" ; timing_sense : positive_unate ; cell_rise (delay_template_2x2) { values ("0.12, 0.24", "0.38, 0.52") ; } } } } } ``` ] ] .pull-right[ Key syntax: - **Attributes**: `key : value ;` β simple key-value pairs - **Groups**: `type (name) { ... }` β recursive containers - **Subgroups**: groups nested inside groups (e.g., `cell` inside `library`, `pin` inside `cell`, `timing` inside `pin`) ] --- class: nord-light, middle, center ## Part 2: The Parser Challenge π --- ### π The liberty-parser API: Hidden Traps When using `liberty-parser` v0.0.29, several API surfaces are **non-obvious**: .font-sm[ | β What the docs say | β What actually works | |---------------------|----------------------| | `group.name` | `group.group_name` β no `.name` property | | `dict(group.attributes)` | `group.attributes` is a **list** of `Attribute` objects, not a dict | | `'cell_rise' in timing` | `cell_rise` is a **subgroup**, not an attribute | | `timing.get_array('cell_rise')` | `timing.get_groups('cell_rise')[0].get_array('values')` | | `str(escaped_string)` β double-quotes the value | `.value.strip('"')` β clean string | ] These traps cost hours of debugging. The API is powerful but has a steep learning curve. --- ### 𧩠Why These Traps Exist: The Data Model liberty-parser faithfully models the Liberty **AST** β not a simplified key-value view: .mermaid[ <pre> graph LR subgraph "Liberty Parser Data Model" direction LR G[Group] --> GN["group_name: str"] G --> GA["args: list[str]"] G --> GAT["attributes: list[Attribute]"] G --> GG["groups: list[Group] β recursive!"] GAT --> AT1["Attribute: name + value"] AT1 --> AT1V["value: EscapedString | list | float | int"] end subgraph "Timing Table Access" direction LR T["timing() group"] --> TG["get_groups('cell_rise')"] TG --> CR["cell_rise subgroup"] CR --> V["get_array('values')"] V --> NP["NumPy ndarray β "] end style G fill:#e8eaf6,stroke:#283593,color:#2e3440,stroke-width:3px style GN fill:#e8eaf6,stroke:#283593,color:#2e3440,stroke-width:3px style GA fill:#e8eaf6,stroke:#283593,color:#2e3440,stroke-width:3px style GAT fill:#e8eaf6,stroke:#283593,color:#2e3440,stroke-width:3px style GG fill:#fff3e0,stroke:#e65100,color:#2e3440,stroke-width:3px style T fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px style CR fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px style V fill:#e3f2fd,stroke:#1565c0,color:#2e3440,stroke-width:3px style NP fill:#ffcdd2,stroke:#c62828,color:#2e3440,stroke-width:3px </pre> ] **Key insight**: `cell_rise`, `cell_fall`, `rise_transition` are all **subgroups** inside `timing()`, not attributes. This is because they have their own sub-structure (index ranges + values). --- class: nord-light, middle, center ## Part 3: JSON Conversion π οΈ --- ### π§ Method 2: Custom JSON Serialization (The Right Way) The most general approach: **recursively** convert the Liberty group tree to JSON: .font-sm[ ```python from liberty.types import EscapedString def _json_safe(value): """Handle EscapedString, NumPy arrays, nested lists.""" if isinstance(value, EscapedString): return value.value.strip('"') if isinstance(value, list): return [_json_safe(v) for v in value] if hasattr(value, "tolist"): # NumPy return value.tolist() return value def liberty_to_dict(group): result = { "type": group.group_name, # NOT group.name! "args": list(group.args), } attrs = {} for a in group.attributes: # NOT dict(group.attributes)! attrs[a.name] = _json_safe(a.value) if attrs: result["attributes"] = attrs if group.groups: result["groups"] = [liberty_to_dict(g) for g in group.groups] return result ``` ] Every Liberty group becomes a JSON object with `type`, `args`, `attributes`, and optional `groups`. --- ### π JSON Output Structure ```json { "type": "library", "args": ["example_minimal"], "attributes": { "time_unit": "1ns", "delay_model": "table_lookup" }, "groups": [ { "type": "cell", "args": ["AND2_X1"], "attributes": { "area": 5.0 }, "groups": [ { "type": "pin", "args": ["Z"], "attributes": { "direction": "output", "function": "(A & B)" }, "groups": [ { "type": "timing", "attributes": { "related_pin": "A", "timing_sense": "positive_unate" }, "groups": [ { "type": "cell_rise", "args": ["delay_template_2x2"], "attributes": { "values": ["0.12, 0.24", "0.38, 0.52"] } } ``` **Recursive**: 7 levels of nesting from library β ... β cell_rise values. --- ### β JSON Schema: Structured Validation for Liberty No official schema exists β so we built one: - **Draft-07 JSON Schema** at `liberty_json_schema.json` π― - Covers **10 Liberty group types** with specific constraints - Permissive fallback via `anyOf` + `any_group` catch-all - Validates **EscapedString**, **NumPy arrays**, nested groups .font-sm[ .pull-left[ ```python import jsonschema with open("library.json") as f: data = json.load(f) with open("liberty_json_schema.json") as f: schema = json.load(f) try: jsonschema.validate(instance=data, schema=schema) print("β VALID β Liberty structure preserved") except jsonschema.ValidationError as e: print(f"β INVALID: {e.message}") ``` ] .pull-right[ | Group Type | Validated Fields | |---|---| | `library` | technology, units, delay_model, PVT | | `cell` | area, ff, is_macro + arbitrary params | | `pin` | direction, capacitance, clock, function | | `timing` | related_pin, timing_sense, timing_type | | `cell_rise` / `cell_fall` / ... | index_1, index_2, values | ] ] --- class: nord-light, middle, center ## Part 4: Verilog β Liberty π€ --- ### π€ Generating Liberty from Verilog The `lib-for-verilog` AI skill creates Liberty files from RTL: .mermaid[ <pre> flowchart LR V["Verilog (.v)"] --> Y["Yosys\n synthesis"] Y --> J["JSON\n netlist"] J --> E["Cell type\n extraction"] E --> L["Liberty\n .lib file"] L --> C["convert-lib-to-json\nskill"] C --> J2["JSON + Schema\n validation β "] style V fill:#fff3e0,stroke:#e65100,color:#2e3440,stroke-width:3px style Y fill:#e3f2fd,stroke:#1565c0,color:#2e3440,stroke-width:3px style J fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px style E fill:#f3e5f5,stroke:#7b1fa2,color:#2e3440,stroke-width:3px style L fill:#ffcdd2,stroke:#c62828,color:#2e3440,stroke-width:3px style C fill:#e3f2fd,stroke:#1565c0,color:#2e3440,stroke-width:3px style J2 fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px </pre> ] **Known for 100+ Yosys cell types** β both pre-techmap (`\$add`, `\$mux`, `\$adff`) and post-techmap (`\$_AND_`, `\$_DFF_P_`, `\$_MUX_`). ```bash python lib_for_verilog.py my_design.v --top my_top --output cells.lib --json --validate ``` Cell name sanitization: `$` β `_dollar_` (Liberty identifiers can't contain a dollar sign) --- ### π¬ Case Study: Sphere Netlist (CORDIC Engine) ```bash # From Verilog β Liberty β JSON (one command) python lib_for_verilog.py sphere_netlist.v --top circle_fsm_32bit_simple_fixed --json --validate ``` **Key find**: Post-`techmap` `opt` pass zeroed the design β had to use `techmap; clean` instead. .font-sm[ .pull-left[ **Pre-techmap** β 9 cell types from Yosys internal cells: | Cell Type | Count | |-----------|-------| | `\$eq` | 64 | | `\$adff` | 40 | | `\$mux` | 26 | | `\$add` | 2 | | `\$mul` | 1 | ] .pull-right[ **Post-techmap** β 8 primitive types (7,308 cells total): | Liberty Cell | Primitive | |---|---| | `_dollar__AND_` | `\$_AND_` | | `_dollar__DFF_P_` | `\$_DFF_P_` π΅ | | `_dollar__DFF_N_` | `\$_DFF_N_` π΅ | | `_dollar__DLATCH_P_` | `\$_DLATCH_P_` | | `_dollar__MUX_` | `\$_MUX_` | | `_dollar__XOR_` | `\$_XOR_` | ] ] --- ### π¬ Case Study: 32-Tap FIR Filter ```bash python lib_for_verilog.py fir_filter_simple_flat.v --top fir_filter --json --validate ``` .pull-left[ **Design stats:** - 32-tap shift register (unrolled for Yosys compat) π¦ - Sequential MAC accumulator π - 7 unique primitive cell types - 7,308 total cells after techmap - Schema validation: β **PASS** **Yosys 0.9 quirk**: procedural `for (integer i = ...)` loops rejected by parser. Pre-unrolling to explicit assignments required. ] .pull-right[ .font-sm[ | Liberty Cell | Yosys Primitive | |---|---| | `_dollar__AND_` | `\$_AND_` π’ | | `_dollar__DFF_PN0_` | `\$_DFF_PN0_` π΅ | | `_dollar__DFF_P_` | `\$_DFF_P_` π΅ | | `_dollar__MUX_` | `\$_MUX_` π | | `_dollar__NOT_` | `\$_NOT_` | | `_dollar__OR_` | `\$_OR_` π’ | | `_dollar__XOR_` | `\$_XOR_` π£ | ] ] **DFF_PN0**: posedge DFF with active-low async reset β common in real designs with `negedge rst_n`. --- class: nord-light, middle, center ## Part 5: Agent Skills & Lessons π‘ --- ### π― Agent Skills: Package the Knowledge Two AI agent skills created during this session: .pull-left[ **π§ `convert-lib-to-json`** ```bash python convert_lib_to_json.py in.lib out.json ``` - Parses .lib β Method 2 JSON - Prints cell summary with area & FF markers - Validates against JSON Schema - Exit code: 0 β / 2 β - Bundled `liberty_json_schema.json` ] .pull-right[ **βοΈ `lib-for-verilog`** ```bash python lib_for_verilog.py in.v --top T --out.lib --json ``` - Runs Yosys synthesis - Extracts 100+ known cell types - Generates Liberty with stub timing - Sanitizes dollar β `_dollar_` names - Filters hierarchical modules ] Both skills available at `~/.config/opencode/skills/` β load via `load_skills=[...]` --- ### π³οΈ Common Pitfalls β What We Learned .font-sm[ | π₯ Issue | π‘ Solution | |----------|-------------| | `group.name` doesn't exist | Use `group.group_name` | | `dict(attributes)` fails | Iterate list; each has `.name` / `.value` | | Timing tables return empty | They're **subgroups** β `get_groups("cell_rise")` first | | `EscapedString` breaks JSON | `value.value.strip('"')` β see `_json_safe()` | | dollar in Liberty cell names | Reserved char β rename to `_dollar_` prefix | | Yosys `opt` after techmap kills cells | Use `techmap; clean` instead of `techmap; opt` | | Yosys rejects `for(integer i...)` in blocks | Pre-unroll loops or use `genvar` | | `read_liberty -lib` name conflicts | Hierarchical modules conflict with Verilog β exclude non-dollar cells | ] --- ### π End-to-End Pipeline .mermaid[ <pre> flowchart LR RTL["RTL Verilog\nmy_design.v"] --> YO["Yosys\nsynth"] YO --> LIB["lib-for-verilog\nskill"] LIB --> LIBFILE["cells.lib\nLiberty library"] LIBFILE --> CONV["convert-lib-to-json\nskill"] CONV --> JSONFILE["cells.json\nStructured JSON"] JSONFILE --> SCHEMA["liberty_json_schema.json\nSchema validation"] SCHEMA --> VALID["β Validated output"] JSONFILE --> ANAL["Python analysis\npandas, numpy, etc."] style RTL fill:#fff3e0,stroke:#e65100,color:#2e3440,stroke-width:3px style YO fill:#e3f2fd,stroke:#1565c0,color:#2e3440,stroke-width:3px style LIB fill:#f3e5f5,stroke:#7b1fa2,color:#2e3440,stroke-width:3px style LIBFILE fill:#ffcdd2,stroke:#c62828,color:#2e3440,stroke-width:3px style CONV fill:#e3f2fd,stroke:#1565c0,color:#2e3440,stroke-width:3px style JSONFILE fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px style SCHEMA fill:#fff3e0,stroke:#e65100,color:#2e3440,stroke-width:3px style VALID fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px style ANAL fill:#eceff1,stroke:#455a64,color:#2e3440,stroke-width:3px </pre> ] **One-command pipeline:** ```bash python lib_for_verilog.py my_design.v --top top --json --validate ``` Single command: **Verilog β Yosys synthesis β cell extraction β Liberty β JSON β schema validation** π --- class: nord-light, middle, center ## Part 6: Summary & Resources π --- ### π Summary What we accomplished in this session: .pull-left[ **ποΈ Infrastructure** - β Correct `liberty-parser` API usage - β Method 2 JSON converter with `EscapedString` handling - β `liberty_json_schema.json` (Draft-07, 10 group types) - β `lib-for-verilog` agent skill - β `convert-lib-to-json` agent skill ] .pull-right[ **π¬ Validated on real designs** - β `example_minimal.lib` β 3 cells (hand-crafted) - β `sphere_netlist` β 7308 cells (CORDIC/VDC engine) - β `fir_filter` β 32-tap filter (7 primitive types) - β All outputs validated against JSON Schema ] **Key equation**: The cost of a Liberty workflow failure is proportional to how deep in the EDA flow it's caught. Early validation with JSON Schema catches structural errors **before** they reach timing analysis. --- ### π Resources .font-sm[ | Resource | Location | |----------|----------| | Tutorial (EN) | `netlistx/lib.md` π | | Tutorial (δΈζ) | `netlistx/lib-cn.md` π | | Liberty Example | `netlistx/example_minimal.lib` π | | JSON Schema | `netlistx/liberty_json_schema.json` π | | YosysβLiberty | `netlistx/yosys_to_liberty.py` π | | FIR Filter Liberty | `netlistx/yosys_testcases/fir_filter.lib` π | | Sphere Tech Liberty | `netlistx/yosys_sphere_tech.lib` π | | Skill: convert-lib-to-json | `~/.config/opencode/skills/convert-lib-to-json/` π€ | | Skill: lib-for-verilog | `~/.config/opencode/skills/lib-for-verilog/` π€ | ] **Paper reference**: Liberty Technical Advisory Board (LTAB), "Liberty Reference Manual" **Tool**: [liberty-parser](https://pypi.org/project/liberty-parser/), [Yosys](https://yosyshq.net/yosis/) --- count: false class: nord-dark, middle, center # π Q&A ### Questions? Discussion? π¬ --- count: false class: nord-dark, middle, center # π Thank You **Liberty β JSON: From EDA Cell Libraries to Structured Data** .mermaid[ <pre> graph LR LIB["Liberty .lib"] --- JSON["JSON"] JSON --- SCHEMA["Schema\nβ "] SCHEMA --- CONFIDENCE["Confidence\nπ"] CONFIDENCE --- LIB style LIB fill:#ffcdd2,stroke:#c62828,color:#2e3440,stroke-width:3px style JSON fill:#e3f2fd,stroke:#1565c0,color:#2e3440,stroke-width:3px style SCHEMA fill:#c8e6c9,stroke:#2e7d32,color:#2e3440,stroke-width:3px style CONFIDENCE fill:#fff3e0,stroke:#e65100,color:#2e3440,stroke-width:3px </pre> ] Slides built with Remark.js π | KaTeX π | Mermaid 𧩠| Nord Theme π