guangzong/stm32-data
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Partially update instructions in README

Browse Source 
Some instructions were out of date, and I've updated these to the best of my understanding to date.

PS. For some reason my Markdown plugin made a bunch of whitespace changes. I can back these out if they are unwanted.
This commit is contained in:
JackN 2023-03-21 15:14:52 -04:00
parent a2333b8afb
commit e208ba72b6
1 changed files with 49 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
README.md
View File

@ -43,21 +43,27 @@ These are the data sources currently used.
In order to run the generator, you will need to install the following tools:
* `wget`
* `git`
* `jq`
* `svd` – `pip3 install svdtools`
* `xmltodict` - `pip3 install xmltodict`
- `wget`
- `git`
- `jq`
- `svd` – `pip3 install svdtools`
- `xmltodict` - `pip3 install xmltodict`
## Generating the YAMLs
## Generate the `stm32-metapac` crate
- Run `./d download-all`
- Run `cargo run --release`
This generates all the YAMLs in `data/` except those in `data/registers/`, which are manually extracted and cleaned up.
> This will download all the required data sources into `sources/`.
> 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`.
- Run `cargo run --release stm32-data-gen`
> This generates all the intermediate JSON's in `build/data/`.
>
> > Assignments of registers to peripherals is done in a [perimap](#peripheral-mapping-perimap) and fixes to registers can be done in the files located in `data/registers`.
- Run `cargo run --release stm32-metapac-gen`
> This generates the `stm32-metapac` crate into `build/stm32-metapac/`.
## Adding support for a new peripheral
@ -72,7 +78,7 @@ are only interested in one. It's easier than it looks, and doing all families at
- 2: SVD inconsistencies, like different register names for the same register
- 3: SVD mistakes (yes, there are some)
- 4: Missing stuff in SVDs, usually enums or doc descriptions.
- Identify how many actually-different (incompatible) versions of the peripheral exist, as we must *not* merge them. Name them v1, v2.. (if possible, by order of chip release date, see [here](https://docs.google.com/spreadsheets/d/1-R-AjYrMLL2_623G-AFN2A9THMf8FFMpFD4Kq-owPmI/edit#gid=1972450814).
- Identify how many actually-different (incompatible) versions of the peripheral exist, as we must _not_ merge them. Name them v1, v2.. (if possible, by order of chip release date, see [here](https://docs.google.com/spreadsheets/d/1-R-AjYrMLL2_623G-AFN2A9THMf8FFMpFD4Kq-owPmI/edit#gid=1972450814).
- For each version, pick the "best" YAML (the one that has less enums/docs missing), place them in `data/registers/lpuart_vX.yaml`
- Cleanup the register yamls (see below).
- Minimize the diff between each pair of versions. For example between `lpuart_v1.yaml` and `lpuart_v2.yaml`. If one is missing enums or descriptions, copy it from another.
@ -116,27 +122,33 @@ 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.
## Peripheral mapping (perimap)
The script has a map to match peripherals to the right version in all chips, the [perimap](https://github.com/embassy-rs/stm32-data/blob/main/src/chips.rs#L109).
The `stm32-data-gen` binary has a map to match peripherals to the right version in all chips, the [perimap](https://github.com/embassy-rs/stm32-data/blob/main/stm32-data-gen/src/chips.rs#L109).
When parsing a chip, for each peripheral a "key" string is constructed using this format: `CHIP:PERIPHERAL_NAME:IP_NAME:IP_VERSION`, where:
- `CHIP`: full chip name, for example `STM32L443CC`
- `PERIPHERAL_NAME`: peripheral name, for example `SPI3`. Corresponds to `IP.InstanceName` in the [MCU XML](https://github.com/embassy-rs/stm32-data-sources/blob/949842b4b8742e6bc70ae29a0ede14b4066db819/cubedb/mcu/STM32L443CCYx.xml#L38).
- `IP_NAME`: IP name, for example `SPI`. Corresponds to `IP.Name` in the [MCU XML](https://github.com/embassy-rs/stm32-data-sources/blob/949842b4b8742e6bc70ae29a0ede14b4066db819/cubedb/mcu/STM32L443CCYx.xml#L38).
@ -174,4 +186,5 @@ Sometimes even the same IP name+version in the same chip family has different re
```
### 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).