103 lines
3.5 KiB
Markdown
103 lines
3.5 KiB
Markdown
# stm32-data
|
||
|
||
`stm32-data` is a project aiming to produce clean machine-readable data about the STM32 microcontroller
|
||
families, including:
|
||
|
||
- :heavy_check_mark: Base chip information
|
||
- RAM, flash
|
||
- Packages
|
||
- :heavy_check_mark: Peripheral addresses and interrupts
|
||
- :heavy_check_mark: Interrupts
|
||
- :heavy_check_mark: GPIO AlternateFunction mappings (for all families except F1)
|
||
- :x: GPIO mappings for F1
|
||
- :construction: Register blocks for all peripherals
|
||
- :heavy_check_mark: DMA stream mappings
|
||
- :x: Per-package pinouts
|
||
- :heavy_check_mark: Links to applicable reference manuals, datasheets, appnotes PDFs.
|
||
|
||
:heavy_check_mark: = done, :construction: = work in progress, :x: = to do
|
||
|
||
## Data sources
|
||
|
||
These are the data sources currently used.
|
||
|
||
- STM32Cube database: describes all MCUs, with useful stuff like GPIO AF mappings, DMA stream mappings, pinouts...
|
||
- stm32-rs SVDs: register blocks. YAMLs are extracted and manually cleaned up.
|
||
|
||
## Install pre-requisites
|
||
|
||
In order to run the generator, you will need to install the following tools:
|
||
|
||
* `wget`
|
||
* `git`
|
||
* `jq`
|
||
* `svd` – `pip3 install svdtools`
|
||
|
||
## Generating the YAMLs
|
||
|
||
- Run `./d download-all`
|
||
- Run `python3 -m stm32data`
|
||
|
||
This generates all the YAMLs in `data/` except those in `data/registers/`, which are manually extracted and cleaned up.
|
||
|
||
> Do not manually edit the files in `data/chips`, contents of these files are autogenerated.
|
||
> Assignments of registers to peripherals is done in the file `parse.py` and fixes to registers can be done in the files located in `data/registers`.
|
||
|
||
## Extracting new register blocks
|
||
|
||
For instance, to add support for the G0 series first download all the source
|
||
SVDs:
|
||
```
|
||
$ ./d download-all
|
||
```
|
||
Now extract the RCC peripheral registers:
|
||
```
|
||
./d install-chiptool
|
||
./d extract-all RCC --transform ./transform-RCC.yaml
|
||
```
|
||
Note that we have used a transform to mechanically clean up some of the RCC
|
||
definitions. This will produce a YAML file for each chip model in `./tmp/RCC`.
|
||
|
||
Sometimes the peripheral name will not match the name defined in the SVD files, check the SVD file for the correct peripheral name.
|
||
|
||
At this point we need to choose the model with the largest peripheral set (e.g.
|
||
the STM32G081) and compare its YAML against each of the other models' to verify
|
||
that they are all mutually consistent.
|
||
|
||
Finally, we can merge
|
||
```
|
||
./merge_regs.py tmp/RCC/g0*.yaml
|
||
```
|
||
This will produce `regs_merged.yaml`, which we can copy into its final resting
|
||
place:
|
||
```
|
||
mv regs_merged.yaml data/registers/rcc_g0.yaml
|
||
```
|
||
|
||
To assign these newly generated registers to peripherals, utilize the mapping done in `parse.py`.
|
||
An example mapping can be seen in the following snippet
|
||
```
|
||
('STM32G0.*:RCC:.*', 'rcc_g0/RCC'),
|
||
```
|
||
such mapping assignes the `rcc_g0/RCC` register block to the `RCC` peripheral in every device from the `STM32G0` family.
|
||
|
||
The pattern for matching is as follows:
|
||
```
|
||
CHIP:PERIPHERAL:PERIPHERAL_KIND
|
||
```
|
||
Thanks to this, you can for example match peripherals with the same name, but different versions.
|
||
```
|
||
('.*:SPI:spi2s1_v2_2', 'spi_v1/SPI'),
|
||
('.*:SPI:spi2s1_v3_2', 'spi_v2/SPI'),
|
||
```
|
||
|
||
When matching the peripherals using the pattern, the first defined pattern is applied if more of the patterns would match.
|
||
```
|
||
('STM32F7.*:TIM1:.*', 'timer_v1/TIM_ADV'),
|
||
('STM32F7.*:TIM8:.*', 'timer_v1/TIM_ADV'),
|
||
('.*TIM\d.*:gptimer.*', 'timer_v1/TIM_GP16'),
|
||
```
|
||
|
||
### Peripheral versions
|
||
The versions of peripherals can be found in the table [here](https://docs.google.com/spreadsheets/d/1-R-AjYrMLL2_623G-AFN2A9THMf8FFMpFD4Kq-owPmI/edit#gid=0).
|