/sodacat-soc-database

Name

sodacat-soc-database

Description

>

# sodaCat SoC Data Catalog

sodaCat is a hardware description database for microcontrollers and SoCs,
stored as normalized YAML models. The repo lives at
`https://github.com/s13n/sodaCat`.

## Step 1: Ensure the repo is available

```bash
if [ -d "$HOME/sodaCat" ]; then
  cd "$HOME/sodaCat" && git pull
else
  cd "$HOME" && git clone https://github.com/s13n/sodaCat.git
fi
```

If cloning fails due to network restrictions, check whether the repo already
exists at `/home/claude/sodaCat` (it may have been cloned in a prior turn).

## Step 2: Read the architecture reference

Before doing anything else, read `CLAUDE.md` in the repo root:

```bash
cat "$HOME/sodaCat/CLAUDE.md"
```

This file is the definitive reference for the repository layout, directory
roles, build commands, model organization (four-tier), the extraction pipeline
(SVD → YAML → C++), the transformation framework, CMake integration, and all
key conventions. Follow its guidance for any task.

## Step 3: Work with the database

The YAML models in `models/` are the primary artifact. Common tasks:

- **Look up peripherals for a chip**: Read the chip-level YAML in its
  subfamily directory (e.g. `models/ST/H7/H73x/STM32H735.yaml`).
- **Inspect a peripheral's registers**: Read the block YAML at the family
  level (e.g. `models/ST/H7/CRYP.yaml`).
- **Check which variants have a peripheral**: Grep chip-level YAMLs for
  the block's model name.
- **Compare peripherals**: Use `tools/compare_peripherals.py`.
- **Extract new models**: Use `extractors/generate_stm32_models.py` for
  STM32, or per-chip scripts in `extractors/` for other vendors.
- **Generate C++ headers**: Use scripts in `generators/cxx/`.

## Important notes

- Always `cd` into the sodaCat directory before running scripts.
- Python dependencies: `ruamel.yaml` and `PyYAML`
  (`pip install -r requirements-dev.txt --break-system-packages`).
- Cross-family shared blocks (e.g. `WWDG.yaml`) live directly in `models/ST/`.
- Some blocks exist only in specific subfamilies; check subfamily directories
  if not found at the family level.
- The `tasks/` directory contains AI agent task descriptions for writing
  parsers and generators.