Metadata-Version: 2.4
Name: svdgen
Version: 0.1.0
Summary: OSS hardware description generation engine — parse CMSIS-SVD, patch, and render arbitrary text artifacts through templates.
Project-URL: Repository, https://github.com/captndo/svdgen
Project-URL: Issues, https://github.com/captndo/svdgen/issues
Author-email: Stilian Dimitrov <captndo@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cmsis,code-generation,embedded,hardware,jinja2,svd
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: >=3.10
Requires-Dist: cmsis-svd>=0.6
Requires-Dist: jinja2>=3.1.6
Requires-Dist: lxml>=6.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tomli>=2.4.1; python_version < '3.11'
Requires-Dist: typer>=0.24.1
Provides-Extra: dev
Requires-Dist: pytest>=9.0; extra == 'dev'
Requires-Dist: ruff>=0.15; extra == 'dev'
Description-Content-Type: text/markdown

# svdgen

OSS hardware description generation engine — parse CMSIS-SVD, apply declarative patches, and render arbitrary text artifacts through Jinja templates.

```
SVD file → Parse → Normalize → Patch → Render → Write
```

Typical outputs: C register headers, Markdown documentation, Rust PAC fragments — anything expressible as text.

## Installation

```bash
pip install svdgen
```

For development:

```bash
pip install -e ".[dev]"
```

## Quick Start

**1. Create `svdgen.toml` in your project:**

```toml
[project]
name = "my-bsp"

[input]
svd = "STM32F407.svd"

[output]
dir = "generated"

[[targets]]
name        = "c_headers"
template    = "c_header/peripheral.h.j2"
output_path = "include/{{ peripheral.name | lower }}.h"
scope       = "peripheral"
```

**2. Generate:**

```bash
svdgen generate
```

This parses the SVD, normalizes the model, renders one C header per peripheral, and writes them to `generated/include/`.

## CLI

| Command | Description |
|---|---|
| `svdgen generate` | Run the full pipeline and write output files |
| `svdgen validate` | Validate config, inputs, and patches without writing files |
| `svdgen inspect [PERIPH[.REG[.FIELD]]]` | Inspect the normalized device model |
| `svdgen list peripherals\|registers\|fields\|targets` | List model elements or configured targets |
| `svdgen export-model` | Export the full normalized model as JSON |

All commands accept `--config / -c` (default `svdgen.toml`), `--dry-run`, `--verbose / -v`, and `--quiet / -q`.

## Patch Files

Patches are YAML files that modify the normalized model without editing the original SVD:

```yaml
- target: "GPIOA.MODER"
  set:
    description: "GPIO port mode register (corrected)"
    reset_value: 0xFFFFFFFF

- target: "GPIOA.MODER.MODE0"
  rename: "MODER0"

- target: "GPIOB"
  disable: true
```

Selectors are dot-separated paths: `PERIPH`, `PERIPH.REG`, or `PERIPH.REG.FIELD`.

## Python API

```python
import svdgen

config = svdgen.load_config("svdgen.toml")
result = svdgen.run(config)

# or step by step:
parse_result = svdgen.parse_svd("device.svd")
device       = svdgen.normalize(parse_result)
patch_set    = svdgen.load_patches("patches/fixups.yaml")
patched      = svdgen.apply_patches(device, patch_set).device
```

## Documentation

- [User Guide](docs/guide.md) — configuration reference, CLI reference, quick start
- [Patch Files](docs/patches.md) — YAML patch format, operations, cookbook
- [Template Authoring](docs/templates.md) — Jinja context, built-in filters, scope
- [Python API Reference](docs/python-api.md) — programmatic usage

## Examples

- [`examples/svdgen.toml`](examples/svdgen.toml) — minimal config
- [`examples/stm32_project/`](examples/stm32_project/) — realistic multi-target project with patches and a custom template

## License

Apache-2.0 — see [LICENSE](LICENSE).
