unavlab
215 lines
8.8 KiB
Markdown
215 lines
8.8 KiB
Markdown
# MCU Database Schema Reference
|
||
|
||
## Schema Definition
|
||
|
||
```python
|
||
MCU_DB: dict[str, dict[str, dict]] = {
|
||
"<vendor>": {
|
||
"<family_id>": {
|
||
"description": str, # Human-readable family description
|
||
"core": str, # CPU core (e.g. "Cortex-M4F", "Xtensa LX7")
|
||
"voltage_profiles": [
|
||
{
|
||
"id": str, # e.g. "3v3_only", "1v8_core_3v3_io"
|
||
"vcore": float, # Core supply voltage
|
||
"vio": float, # I/O supply voltage
|
||
"vbat_supported": bool,
|
||
},
|
||
],
|
||
"packages": {
|
||
"<package_id>": {
|
||
"description": str, # e.g. "LQFP64, 10x10mm, 0.5mm pitch"
|
||
"pin_count": int,
|
||
"thermal_pad": bool, # QFN/DFN exposed pad
|
||
"pinmap": {
|
||
# int pin_number or str pin_name → pin definition
|
||
1: {
|
||
"signal": str, # Primary signal name
|
||
"roles": list[str], # ["power", "ground", "reset", "boot", "gpio", "analog"]
|
||
"af": list[str], # Alternate functions (optional)
|
||
},
|
||
},
|
||
"capabilities": {
|
||
"has_usb_fs": bool,
|
||
"has_usb_hs": bool,
|
||
"has_eth_mac": bool,
|
||
"has_can": bool,
|
||
"has_sdio": bool,
|
||
"uart_count": int,
|
||
"i2c_count": int,
|
||
"spi_count": int,
|
||
"adc_channels": int,
|
||
"dac_channels": int,
|
||
"timer_count": int,
|
||
"dma_channels": int,
|
||
# extensible — add any capability flags needed
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
## Key Design Decisions
|
||
|
||
- **Vendor as top-level key**: Allows unambiguous lookup when family names overlap.
|
||
- **Roles list, not single role**: A pin can be both "gpio" and "analog" (e.g. PA0 on STM32).
|
||
- **Alternate functions (af)**: Matches STM32 AF model; for ESP32, use GPIO matrix mapping.
|
||
- **thermal_pad flag**: Reminds the generator to add GND connection for QFN/DFN pads.
|
||
- **Capabilities are flat**: Easier to query than nested structures. Add custom keys freely.
|
||
|
||
## Example: ST / STM32F4 / LQFP64
|
||
|
||
```python
|
||
MCU_DB = {
|
||
"ST": {
|
||
"STM32F4": {
|
||
"description": "High-performance Cortex-M4F, up to 180 MHz, FPU, DSP",
|
||
"core": "Cortex-M4F",
|
||
"voltage_profiles": [
|
||
{"id": "3v3_only", "vcore": 3.3, "vio": 3.3, "vbat_supported": True},
|
||
{"id": "1v8_core_3v3_io", "vcore": 1.8, "vio": 3.3, "vbat_supported": True},
|
||
],
|
||
"packages": {
|
||
"LQFP64": {
|
||
"description": "LQFP64, 10x10mm, 0.5mm pitch",
|
||
"pin_count": 64,
|
||
"thermal_pad": False,
|
||
"pinmap": {
|
||
1: {"signal": "VBAT", "roles": ["power"]},
|
||
2: {"signal": "PC13", "roles": ["gpio"], "af": ["RTC_AF1"]},
|
||
7: {"signal": "NRST", "roles": ["reset"]},
|
||
60: {"signal": "BOOT0", "roles": ["boot"]},
|
||
14: {"signal": "PA0", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_IN0", "TIM2_CH1", "USART2_CTS"]},
|
||
15: {"signal": "PA1", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_IN1", "TIM2_CH2", "USART2_RTS"]},
|
||
16: {"signal": "PA2", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_IN2", "TIM2_CH3", "USART2_TX"]},
|
||
17: {"signal": "PA3", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_IN3", "TIM2_CH4", "USART2_RX"]},
|
||
# ... fill from datasheet DS9716 Table 8
|
||
19: {"signal": "VSS", "roles": ["ground"]},
|
||
20: {"signal": "VDD", "roles": ["power"]},
|
||
},
|
||
"capabilities": {
|
||
"has_usb_fs": True,
|
||
"has_usb_hs": False,
|
||
"has_eth_mac": False,
|
||
"has_can": True,
|
||
"has_sdio": True,
|
||
"uart_count": 4,
|
||
"i2c_count": 3,
|
||
"spi_count": 3,
|
||
"adc_channels": 16,
|
||
"dac_channels": 2,
|
||
"timer_count": 14,
|
||
"dma_channels": 16,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
|
||
"Espressif": {
|
||
"ESP32-S3": {
|
||
"description": "Dual-core Xtensa LX7, WiFi + BLE 5, AI acceleration",
|
||
"core": "Xtensa LX7 (dual)",
|
||
"voltage_profiles": [
|
||
{"id": "3v3_only", "vcore": 3.3, "vio": 3.3, "vbat_supported": False},
|
||
],
|
||
"packages": {
|
||
"ESP32-S3-MINI-1": {
|
||
"description": "Module, 15.4x20.5mm, castellated pads",
|
||
"pin_count": 55,
|
||
"thermal_pad": True,
|
||
"pinmap": {
|
||
1: {"signal": "GND", "roles": ["ground"]},
|
||
2: {"signal": "3V3", "roles": ["power"]},
|
||
3: {"signal": "EN", "roles": ["reset"]},
|
||
4: {"signal": "IO4", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_CH3", "TOUCH4"]},
|
||
5: {"signal": "IO5", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_CH4", "TOUCH5"]},
|
||
6: {"signal": "IO6", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_CH5", "TOUCH6"]},
|
||
7: {"signal": "IO7", "roles": ["gpio", "analog"],
|
||
"af": ["ADC1_CH6", "TOUCH7"]},
|
||
# ESP32 uses GPIO matrix — any GPIO can map to any peripheral
|
||
# af list shows default/recommended assignments
|
||
# ... fill from ESP32-S3-MINI-1 datasheet
|
||
},
|
||
"capabilities": {
|
||
"has_usb_fs": True, # USB-OTG
|
||
"has_usb_hs": False,
|
||
"has_eth_mac": False,
|
||
"has_can": True, # TWAI (CAN 2.0)
|
||
"has_sdio": True,
|
||
"has_wifi": True,
|
||
"has_ble": True,
|
||
"uart_count": 3,
|
||
"i2c_count": 2,
|
||
"spi_count": 3, # SPI0/SPI1 for flash; SPI2/SPI3 general
|
||
"adc_channels": 20,
|
||
"dac_channels": 0, # S3 has no DAC (S2 did)
|
||
"timer_count": 4, # General-purpose timers
|
||
"dma_channels": 5, # GDMA channels
|
||
"gpio_matrix": True, # Any GPIO → any peripheral
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
## Blank Template
|
||
|
||
Copy this to add a new MCU family:
|
||
|
||
```python
|
||
"<Vendor>": {
|
||
"<FAMILY>": {
|
||
"description": "",
|
||
"core": "",
|
||
"voltage_profiles": [
|
||
{"id": "3v3_only", "vcore": 3.3, "vio": 3.3, "vbat_supported": False},
|
||
],
|
||
"packages": {
|
||
"<PACKAGE_ID>": {
|
||
"description": "",
|
||
"pin_count": 0,
|
||
"thermal_pad": False,
|
||
"pinmap": {
|
||
# Fill from datasheet pinout table
|
||
},
|
||
"capabilities": {
|
||
"has_usb_fs": False,
|
||
"has_usb_hs": False,
|
||
"has_eth_mac": False,
|
||
"has_can": False,
|
||
"has_sdio": False,
|
||
"uart_count": 0,
|
||
"i2c_count": 0,
|
||
"spi_count": 0,
|
||
"adc_channels": 0,
|
||
"dac_channels": 0,
|
||
"timer_count": 0,
|
||
"dma_channels": 0,
|
||
},
|
||
},
|
||
},
|
||
},
|
||
},
|
||
```
|
||
|
||
## Validation
|
||
|
||
Run `scripts/validate_mcu_db.py` to check:
|
||
- All required keys present
|
||
- Pin numbers are unique within a package
|
||
- Every package has at least one "power" and one "ground" pin
|
||
- Capability counts are non-negative integers
|
||
- Voltage profiles have valid voltage ranges (0.5V–5.5V)
|