michele
312057b6d3
PE-SI-009 no longer treats ESP32 CHIP_PU/EN RC as a USB series R. USB without a library Z number stays PE-SI-010 measurement-only. Pintable skill 1.13.0 requires net_class on SI kinds (usb2/usb3/MDI/RGMII/DDR3).
183 lines
8.2 KiB
Markdown
183 lines
8.2 KiB
Markdown
---
|
||
skill_name: extract-pintable
|
||
description: Extract pin table, package info, absolute-maximum ratings, layout_rules, and component subtype from an IC datasheet PDF. Returns structured data via the save_pintable tool.
|
||
---
|
||
|
||
# Extract Pin Table & Variant Info
|
||
|
||
Extract structured data from an IC datasheet and return it via the `save_pintable` tool.
|
||
|
||
**Priority order:** (1) complete pin table for the MPN package, (2) `layout_rules` from PCB / typical-application pages, (3) package + abs-max + subtype.
|
||
|
||
## Steps
|
||
|
||
### 1. Read the datasheet PDF
|
||
|
||
Focus on these sections (figures count as evidence):
|
||
- **Pin configuration / pin assignment table** — primary target
|
||
- **Ordering information / part number decoder**
|
||
- **Package information**
|
||
- **PCB layout / layout guidelines / land pattern notes**
|
||
- **Typical application / reference design** (placement callouts near caps, vias, keepouts)
|
||
- **Absolute maximum ratings**
|
||
|
||
### 2. Extract the pin table
|
||
|
||
For every pin:
|
||
- `number` (int or str) — pin number, or BGA ball like `"A3"`
|
||
- `name` (str) — verbatim from the datasheet (e.g. `"VDD"`, `"PA0/SPI0_CLK"`)
|
||
- `description` (str or null)
|
||
- `functions` (list[str] or null) — alternate/mux functions
|
||
|
||
Rules:
|
||
- Include ALL pins — power, ground, NC, exposed pad / EP
|
||
- Names verbatim — do not rename or normalize
|
||
- Multiplexed pins: primary in `name`, alternates in `functions`
|
||
- If the datasheet has per-package tables, use the package matching the MPN
|
||
- Off-by-one pin numbers break everything downstream — double-check
|
||
|
||
**Modules vs bare die (critical).** MPNs containing `WROOM`, `WROVER`, `MODULE`, `MOD-`, or `SIP` are *modules*. Extract the **module landing-pad table** (schematic pins). Do **not** extract the SoC/QFN ball map from a nested chip chapter.
|
||
- Espressif WROOM: pin 1 is GND. Pin 1 named `ANT`, `CHIP_PU`, or `XTAL_*` means you grabbed the die table — invalid.
|
||
- Crystal, RF antenna, and flash on a WROOM module are **inside the can**; they must not appear as schematic pin numbers.
|
||
|
||
Optional extras (omit if absent):
|
||
- `internal_features.pullup_pins` / `esd_clamp_pins` / `analog_switch` from the **block diagram** only.
|
||
|
||
### 3. Extract layout_rules (required scan — empty OK)
|
||
|
||
You **must** look for layout guidance. Emit `layout_rules` as a list. Use `[]` only after scanning layout / application / thermal pages and finding no placement guidance.
|
||
|
||
#### Where to look
|
||
- Headings: “PCB Layout”, “Layout Guidelines”, “Layout Considerations”, “Board Layout”, “Land Pattern”
|
||
- “Typical Application”, “Application Circuit”, “Reference Design”
|
||
- Thermal / EP / exposed-pad via recommendations
|
||
- Callouts on application figures (“place CIN within 2 mm of VIN”)
|
||
|
||
#### Allowed `kind` (closed set)
|
||
| kind | Use when |
|
||
| --- | --- |
|
||
| `decoupling_proximity` | Bypass / decoupling / input / output cap near a supply or pin |
|
||
| `thermal_via` | Vias under exposed pad / thermal pad / EP |
|
||
| `keepout` | Keep foreign nets, digital return, or copper out of a region |
|
||
| `length_match` | Intra-pair skew / matched length limit in mm |
|
||
| `impedance` | Single-ended `z0_ohm` or differential `zdiff_ohm` (plus `tolerance_pct` or `z_min_ohm`/`z_max_ohm`) |
|
||
| `max_length` | Maximum routed length in mm |
|
||
| `spacing` | Intra-pair / coupling gap (`min_spacing_mm`) |
|
||
| `ref_plane` | Required reference plane (`ref_plane`, `topology`) |
|
||
| `si_via` | Min/max vias on the HS net |
|
||
| `layer` | Required copper layer / topology |
|
||
| `series_resistor` | Series R on the HS net (`value_ohms`) |
|
||
| `return_path` | GND return via next to the pair |
|
||
| `emi` / `common_mode` / `shield` | Common-mode choke, ferrite bead, shield, or EMI filter **quoted from this datasheet** (no IEC 61000 invention) |
|
||
|
||
Do **not** emit impedance/50 Ω rules for I2C, GPIO, EN, analog REGN, or USB CC. Do **not** invent USB 90 Ω unless **this** datasheet states a number.
|
||
|
||
`net_class` is **required** for every SI kind (`impedance`, `length_match`, `max_length`, `spacing`, `ref_plane`, `si_via`, `layer`, `series_resistor`, `return_path`, `si`). Use one of: `usb2`, `usb3`, `eth_mdi`, `rgmii`, `sgmii`, `ddr3`, `hdmi`, `pcie`, `lvds`. PCB review will not map a rule onto another bus.
|
||
|
||
`series_resistor` is a termination / series R **on that HS net** (e.g. USB 22 Ω, RGMII 22 Ω). It is **not** CHIP_PU / EN / RESET RC (10 kΩ + 1 µF), ILIM, or a strap divider — omit those or use `decoupling_proximity` / leave them to timing checks.
|
||
|
||
#### Fields
|
||
- `pin` — number or name as printed (`"5"`, `"VIN"`, `"VDD"`, `"EP"`)
|
||
- `cap_value_hint` — only if shown (`"100nF"`, `"10µF"`)
|
||
- `max_distance_mm` — **number only if the PDF states millimetres**
|
||
- OK: “within 2 mm”, “< 5 mm”, “no more than 3 mm from the pin” → `2` / `5` / `3`
|
||
- NOT OK as a number: “as close as possible”, “close to the pin”, “adjacent”, “nearby” → set `max_distance_mm: null` and keep the rule with a `note`
|
||
- **Never invent** JEDEC, USB, IPC, or “standard 3 mm / 5 mm” distances
|
||
- `same_layer` — `true`/`false` only if text says same side / opposite side of the board; else null
|
||
- `min_via_count` — integer only if stated (“at least 4 vias”)
|
||
- `net_class` — **required for SI kinds**: `usb2` | `usb3` | `eth_mdi` | `rgmii` | `sgmii` | `ddr3` | `hdmi` | `pcie` | `lvds`. Must match the quoted bus (PHY+RJ45 = `eth_mdi`, MAC–PHY = `rgmii`/`sgmii`, USB-C SuperSpeed = `usb3`, USB D+/D− = `usb2`). Never leave SI `net_class` empty.
|
||
- `note` — short quote of the guidance
|
||
- `source_page` — 1-based page of the guidance (required when you emit a rule)
|
||
|
||
#### Examples
|
||
|
||
Numeric proximity (copy the millimetre from the PDF):
|
||
|
||
```json
|
||
{
|
||
"kind": "decoupling_proximity",
|
||
"pin": "VIN",
|
||
"cap_value_hint": "10uF",
|
||
"max_distance_mm": 2.0,
|
||
"same_layer": true,
|
||
"note": "Place CIN within 2 mm of VIN",
|
||
"source_page": 14
|
||
}
|
||
```
|
||
|
||
Proximity without a millimetre (still emit the rule):
|
||
|
||
```json
|
||
{
|
||
"kind": "decoupling_proximity",
|
||
"pin": "VDD",
|
||
"cap_value_hint": "100nF",
|
||
"max_distance_mm": null,
|
||
"note": "Place decoupling capacitor as close as possible to VDD",
|
||
"source_page": 22
|
||
}
|
||
```
|
||
|
||
Thermal vias:
|
||
|
||
```json
|
||
{
|
||
"kind": "thermal_via",
|
||
"pin": "EP",
|
||
"min_via_count": 4,
|
||
"note": "Use at least 4 thermal vias in the exposed pad",
|
||
"source_page": 18
|
||
}
|
||
```
|
||
|
||
#### Hard negatives
|
||
- Do not invent land-pattern pad sizes from the mechanical drawing alone
|
||
- Do not emit `length_match` or `impedance` for USB/HDMI/PCIe unless **this** datasheet states a skew/Z number
|
||
- Do not treat I2C, GPIO, EN, analog, or USB-CC as 50 Ω / 90 Ω pairs
|
||
- Do not emit `series_resistor` for EN / CHIP_PU / RESET RC, ILIM, or strap networks
|
||
- Do not emit an SI kind without `net_class` naming the quoted bus
|
||
- Do not use kinds outside the closed set
|
||
- One rule per distinct pin/guidance; prefer supply pins that show caps in the application figure
|
||
|
||
### 4. Extract package info
|
||
|
||
- `base_family` — e.g. `"MSPM0G3507"` from `"MSPM0G3507SPTR"`
|
||
- `package` — e.g. `"LQFP-48"`, `"SOT-23-5"`
|
||
- `pin_count` (int)
|
||
- `description` — human-readable MPN decode
|
||
|
||
Prefer “Ordering Information” / “Device Information” tables.
|
||
|
||
### 5. Extract absolute maximum ratings
|
||
|
||
Copy the **Absolute Maximum Ratings** table (not Recommended Operating Conditions):
|
||
|
||
- `parameter`, `min` / `max`, `unit`, `source_page` (1-based)
|
||
|
||
Include supply voltages, pin/input voltages, input current, temperature. Skip HBM/IEC kV ESD rows unless they are the only voltage limit. Do not invent numbers.
|
||
|
||
**ESD / TVS (`ic.protection.esd` and similar):** also from Electrical Characteristics:
|
||
- Vrwm / operating voltage as signed min/max in volts
|
||
- One row for polarity/topology as printed (`bidirectional`, …), `unit: "—"`
|
||
|
||
### 6. Assign component subtype
|
||
|
||
Pick the best dotted subtype from `EXISTING IC TAXONOMY SUBTYPES` (e.g. `ic.mcu`, `ic.power.ldo`). If none fit, propose `ic.{category}.{specific}`.
|
||
|
||
### 7. Quality checks
|
||
|
||
Before output:
|
||
- Pin count matches the package for this MPN
|
||
- No duplicate / missing pin numbers
|
||
- `layout_rules` scanned (list present; `[]` only if truly no guidance)
|
||
- Every emitted rule has a valid `kind`; every numeric `max_distance_mm` comes from the PDF text/figure
|
||
- Pin names are not OCR garbage
|
||
|
||
### 8. Validate and output
|
||
|
||
```bash
|
||
python3 /skills/extract-pintable/validate.py '<your JSON here>'
|
||
```
|
||
|
||
If validation passes, call `save_pintable`. Do NOT write files to disk — use the tool.
|