IEEE 1801 UPF Toolkit

Complete offline VS Code extension for IEEE Std 1801 Unified Power Format files. Provides authoring, navigation, validation, visualization, and inline preview — all in your editor, all offline, no dependencies.

Features at a glance

1. Syntax highlighting

.upf files are colorized using a dedicated TextMate grammar covering:

• Commands — create_power_domain, set_isolation, add_power_state, and 40+ others
• Options — -domain, -applies_to, -clamp_value, etc.
• Constants — FULL_ON, PARTIAL_ON, OFF, posedge, TRUE, direction/location keywords
• Voltage tuples — `{FULL_ON, 0.90} as a distinct scope
• Comments — both # and // styles
• Strings, numbers, operators, variables ($var)
• Line continuations — trailing \ gets its own scope

2. Semantic highlighting

Beyond static syntax rules, the extension applies context-aware coloring based on parsed meaning. Each user-defined name is colored by its kind:

• Power domains → class color
• Supply nets / logic nets → variable color
• Supply / logic ports → parameter color
• Supply sets → struct color
• Strategies (isolation, level-shifter, retention) → event color
• Power switches → method color
• PSTs and state groups → enum color
• Power states → enumMember color
• VCTs → macro color

Definitions get a declaration modifier; references get readonly. Deprecated commands get the deprecated modifier (usually rendered strikethrough).

Enable semantic highlighting (if your theme doesn't already):

"editor.semanticHighlighting.enabled": true

3. Snippets

Type any prefix and press Tab to expand a fully-populated template with dropdown-choice placeholders for enumerated options.

Categories: Setup, Domains, Supply network, Switches, States, Isolation, Level shifters, Retention, Attributes/VCTs, and full-design Skeletons (upf_skeleton_min, upf_skeleton_2pd).

4. Formatter

Shift+Alt+F or Format Document. Cleans and column-aligns UPF code.

Preview all styles side-by-side before choosing: Command Palette → UPF: Preview Formatter Styles. Opens a panel that shows the same sample formatted in each style with an Apply button for each — one click to save any style as your default.

On single-line commands — trims whitespace and collapses runs of spaces to a single space.

On multi-line commands (joined by \) — full column alignment:

• All option names (-foo) are padded to the width of the widest option, so their values line up
• If every value is a { ... } brace group, the inner brace contents are padded so all closing } line up
• Every trailing \ is padded to a common column so continuations form a clean right edge
• The header line's \ aligns too

Example — before formatting:

create_power_switch PSW_C1B2 \
  -input_supply_port { VDD_in VDD_channel1 } \
  -output_supply_port { VDD_out VDD_channel1_block2 } \
  -control_port { DISABLE channel1_block2_power_controls[2] } \
  -on_state { PS_channel1_block2_on in_port {!ctrl_port} } \

After (indent = 2 spaces):

create_power_switch PSW_C1B2                                         \
  -input_supply_port  { VDD_in VDD_channel1                        } \
  -output_supply_port { VDD_out VDD_channel1_block2                } \
  -control_port       { DISABLE channel1_block2_power_controls[2]  } \
  -on_state           { PS_channel1_block2_on in_port {!ctrl_port} } \

Non-brace values also align:

set_isolation ISO_core            \
    -domain               PD_core \
    -applies_to           outputs \
    -clamp_value          0       \
    -isolation_power_net  VDD     \
    -isolation_ground_net VSS     \
    -location             parent

Preserves whitespace inside "..." strings and `{...} voltage tuples so semantics don't change. Blank lines and comments are preserved (trailing whitespace trimmed). Respects editor.tabSize and editor.insertSpaces.

Enable format-on-save for UPF only:

"[upf]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "quyetdv.upf-lang-by-quyetdv"
}

5. Diagnostics

Live problems in the Problems panel (Ctrl+Shift+M) and as squiggles in the editor:

• Unknown reference — a -domain PD_x where PD_x was never defined (Warning)
• Duplicate definition — same symbol declared twice (Warning)
• Unknown command — command not recognized as IEEE 1801 (Info; useful for spotting vendor extensions)
• Version mismatch — using a UPF 2.1+ command in a upf_version 1.0 file (Warning)
• Deprecated command — legacy commands in a modern file (Hint, strikethrough)

Checked kinds: power domains, supply nets, logic nets, and strategies. HDL objects (-elements, -ports, -lib_cells) are not validated because they live outside UPF.

6. Hover documentation

Hover over any UPF command to see its category, version, description, syntax, all options with descriptions, and a copy-pasteable example.

Hover over any option (e.g. -domain, -applies_to, -clamp_value) to see what it does in the enclosing command, plus its list of valid values if it's an enumerated option:

-applies_to
option of `set_isolation`

Which ports to isolate (inputs, outputs, or both)

Valid values
- inputs
- outputs
- both

Hover over a user-defined symbol (domain, net, strategy) to see its kind and where it was defined.

7. Auto-completion

Context-aware. Trigger with Ctrl+Space or by typing:

• At start of line — command list, with descriptions and version tags
• After typing - — options for the enclosing command
• After -applies_to — inputs, outputs, both (enum dropdown)
• After -clamp_value — 0, 1, latch, any, Z
• After -location — parent, self, fanout, automatic, sibling
• After -rule — low_to_high, high_to_low, both
• After -hdl_type — vhdl, sv, verilog
• After -direction — in, out, inout
• After -isolation_sense — high, low
• After -domain — all power domains defined in the file
• After -primary_power_net (and similar) — all supply nets defined in the file
• Inside -supply_expr { ... } — power, ground, nwell, pwell

8. Go to Definition & Find All References

F12 or Ctrl+Click on any symbol reference jumps to its create_* or set_* definition. Shift+F12 shows every place a symbol is used across the file.

9. Symbol outline

Outline sidebar and Ctrl+Shift+O show all UPF symbols grouped by kind — Power Domains, Supply Nets, Isolation Strategies, Power States, etc. Click any entry to jump to it.

10. Inline voltage preview

Every -state inside add_power_state gets an inline decoration on the same line showing the derived voltage and logic condition:

    -state RUN { -supply_expr { power == `{FULL_ON, 0.90} } -logic_expr { !sleep } }
                                                                                    ↑
                                                            → power=FULL_ON 0.90V | when: !sleep

Updates as you type. Uses italic gray text in your theme's code-lens color so it never overwhelms the actual code.

Recognized voltage forms:

• `{FULL_ON, 0.90} → shows FULL_ON 0.90V
• `{PARTIAL_ON, 0.72} → shows PARTIAL_ON 0.72V
• `{OFF} → shows OFF

11. Power intent report (Markdown)

Trigger the report in any of five ways:

• Click the ⚡ button in the editor title bar (top-right of the editor pane)
• Click the ⚡ Generate Power Intent Report code lens at the top of the file
• Right-click in a .upf file → UPF: Generate Power Intent Report
• Command Palette (Ctrl+Shift+P) → UPF: Generate Power Intent Report
• Keyboard shortcut: Ctrl+Alt+R (Windows/Linux) or Cmd+Alt+R (macOS)

A single self-contained panel opens beside the editor with the report already rendered — no unsaved markdown file is created and left lying around. The panel has a toolbar with two buttons:

• 💾 Save as <basename>.md — opens a save dialog pre-filled with the source .upf filename with the extension swapped to .md, defaulting to the same folder. You can rename or relocate before confirming.
• 📋 Copy Markdown — copies the raw Markdown source to your clipboard for pasting into another tool (GitHub, Confluence, an email, etc.)

Both buttons flash a confirmation toast in the top-right corner. The panel styling automatically matches your VS Code theme (light, dark, or high-contrast) via VS Code's built-in theme variables.

The report contains:

• Overview — design top, UPF version, counts of every element category
• Domain Hierarchy — ASCII-art tree showing top-level and child domains with all attached strategies, switches, isolation, retention, and level shifters
• Power States — table of every add_power_state and every PST row, with power/ground voltages and logic conditions
• Power Domain Details — per-domain breakdown listing elements, attached strategies, and switches
• Supply Network — tables of supply ports, supply nets, and supply sets (with power/ground/well mappings)
• Power Switches — per-switch input/output/control ports and on/off conditions
• Isolation Strategies — table with domain, applies-to, clamp value, location, iso power/ground, and enable signal
• Level Shifter Strategies — table with rule, applies-to, location, threshold
• Retention Strategies — table with retention power/ground and save/restore signals
• Power Intent Summary — plain-English narrative describing the design's power behavior: which domains are always-on, which are switchable, how isolation and retention protect the design, and what legal power states exist

Because the underlying report is Markdown, saving gives you a file that works with GitHub, GitLab, Confluence, Obsidian, or any Markdown renderer. Great for design reviews, documentation, or code-review deliverables.

Sample output snippet:

## Domain Hierarchy

📦 top
├── ⚡ PD_top  (always-on scope)
│   └── 🔀 switch PSW_core → VDD_SW
└── 🔋 PD_core  (elements: u_core)
    ├── 🔒 isolation ISO_core (outputs)
    ├── 📶 level-shifter LS_core (low_to_high)
    └── 💾 retention RET_core

Requirements

VS Code 1.50 or newer. No network access, no dependencies — fully offline.

Settings

All settings are under IEEE 1801 UPF Toolkit in VS Code's settings UI (Ctrl+, → search "upf"), or in your settings.json:

Formatter

Diagnostics

Voltage preview

Hover

Report

Settings apply immediately — no reload needed. If you turn diagnostics off then back on, all open UPF files re-lint automatically.

Example settings.json for a minimal, distraction-free setup:

{
    "upf.formatter.style": "compact",
    "upf.voltagePreview.enabled": false,
    "upf.diagnostics.deprecatedCommands": false,
    "upf.hover.showExamples": false
}

Or a strict style with everything on:

{
    "upf.formatter.style": "aligned",
    "upf.formatter.alignClosingBraces": true,
    "upf.diagnostics.enabled": true,
    "[upf]": {
        "editor.formatOnSave": true,
        "editor.defaultFormatter": "quyetdv.upf-lang-by-quyetdv"
    }
}

Extension Contents

upf-lang-by-quyetdv/
├── package.json
├── language-configuration.json
├── extension.js                    # main entry point + all providers
├── icon.png / icon.svg
├── LICENSE
├── README.md
├── lib/
│   ├── upf-data.js                 # command metadata + option values
│   ├── parser.js                   # tokenizer + symbol extractor
│   ├── formatter.js                # formatter logic
│   ├── report.js                   # Markdown report generator
│   └── markdown-render.js          # Markdown → HTML for the report panel
├── syntaxes/
│   └── upf.tmLanguage.json         # syntax highlighting grammar
└── snippets/
    └── upf.code-snippets           # IEEE 1801 snippet library

UPF Version Coverage

Snippets, grammar, hover docs, and diagnostics follow IEEE Std 1801-2018 (UPF 3.0) by default. Legacy constructs (create_pst / add_pst_state, set_domain_supply_net) get deprecation hints in UPF 3.0+ files. Modern constructs (add_power_state, create_supply_set) get version-mismatch warnings in older files.

Release Notes

0.0.1

• Syntax highlighting (TextMate grammar, 40+ commands)
• Snippet library with placeholders and dropdown choices
• Document formatter
• Diagnostics: unknown references, duplicates, unknown commands, version mismatches, deprecations
• Hover documentation for commands and user-defined symbols
• Context-aware auto-completion (commands, options, option values, symbol references)
• Go to Definition, Find All References
• Symbol outline grouped by kind
• Semantic highlighting with declaration/readonly/deprecated modifiers
• Inline voltage preview for add_power_state blocks
• Markdown power intent report — opens in a self-contained webview panel with Save and Copy Markdown buttons, styled to match your VS Code theme
• Report entry points: editor title bar button (⚡), code lens, right-click menu, command palette, and Ctrl+Alt+R keyboard shortcut

License

MIT License — see LICENSE. Free for commercial and private use.