Partially update instructions in README

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.
2023-03-21 15:14:52 -04:00 · 2023-03-21 15:14:52 -04:00 · e208ba72b6
commit e208ba72b6
parent a2333b8afb
1 changed files with 49 additions and 36 deletions
--- a/README.md
+++ b/README.md
@ -4,8 +4,8 @@
 families, including:

 - :heavy_check_mark: Base chip information
-    - RAM, flash
-    - Packages
+  - 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)
@ -22,20 +22,20 @@ families, including:
 These are the data sources currently used.

 - STM32Cube database:
-    - List of all MCUs
-    - Peripheral versions
-    - Flash, RAM size
-    - GPIO AF mappings
-    - Interrupt mappings (which signals from which peripherals are OR'd into a NVIC interrupt line)
-    - DMA channel request mappings
-    - Packages and package pinouts (TODO)
+  - List of all MCUs
+  - Peripheral versions
+  - Flash, RAM size
+  - GPIO AF mappings
+  - Interrupt mappings (which signals from which peripherals are OR'd into a NVIC interrupt line)
+  - DMA channel request mappings
+  - Packages and package pinouts (TODO)
 - STM32Cubeprog database
-    - Flash, RAM size
+  - Flash, RAM size
 - STM32 mcufinder:
-    - Links to documentation PDFs (reference manuals, datasheets...)
+  - Links to documentation PDFs (reference manuals, datasheets...)
 - STM32 HAL headers:
-    - interrupt number, name
-    - peripheral addresses
+  - interrupt number, name
+  - peripheral addresses
 - stm32-rs SVDs: register blocks. YAMLs are intially extracted from SVDs, manually cleaned up and
  committed. From this point on, they're manually maintained (we don't maintain "patches" for registers)

@ -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

@ -68,14 +74,14 @@ are only interested in one. It's easier than it looks, and doing all families at
 - Install chiptool with `./d install-chiptool`
 - Run `./d extract-all LPUART1`. This'll output a bunch of yamls in `tmp/LPUART1`. NOTE sometimes peripherals have a number sometimes not (`LPUART1` vs `LPUART`). You might want to try both and merge the outputted YAMLs into a single directory.
 - Diff them between themselves, to identify differences. The differences can either be:
-   - 1: Legitimate differences between families, because there are different LPUART versions. For example, added registers/fields.
-   - 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).
+  - 1: Legitimate differences between families, because there are different LPUART versions. For example, added registers/fields.
+  - 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).
 - 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. 
+- 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.
 - Make sure the block
 - Add entries to [`perimap`](https://github.com/embassy-rs/stm32-data/blob/main/stm32data/__main__.py#L84), see below.
 - Regen, check `data/chips/*.yaml` has the right `block: lpuart_vX/LPUART` fields
@ -88,11 +94,11 @@ SVDs have some widespread annoyances that should be fixed when adding register Y

 - Remove "useless prefixes". For example if all regs in the `RNG` peripheral are named `RNG_FOO`, `RNG_BAR`, the `RNG_` peripheral is not conveying any useful information at all, and must go.
 - Remove "useless enums". Useless enums is one of the biggest cause of slow compilation times in STM32 PACs.
-    - 0=disabled, 1=enabled. Common in `xxEN` and `xxIE` fields. If a field says "enable foo" and is one bit, it's obvious "true" means enabled and "false" means disabled.
-    - "Write 0/1 to clear" enums, common in `xxIF` fields.
-    - Check out the `DeleteEnums` chiptool transforms.
- Convert repeated registers or fields (like `FOO0 FOO1, FOO2, FOO3`) to arrays `FOO[n]`. 
-    - Check out the `MakeRegisterArray`, `MakeFieldArray` chiptool transforms.
+  - 0=disabled, 1=enabled. Common in `xxEN` and `xxIE` fields. If a field says "enable foo" and is one bit, it's obvious "true" means enabled and "false" means disabled.
+  - "Write 0/1 to clear" enums, common in `xxIF` fields.
+  - Check out the `DeleteEnums` chiptool transforms.
+- Convert repeated registers or fields (like `FOO0 FOO1, FOO2, FOO3`) to arrays `FOO[n]`.
+  - Check out the `MakeRegisterArray`, `MakeFieldArray` chiptool transforms.

 ## Adding support for a new family (RCC)

@ -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).
@ -144,7 +156,7 @@ When parsing a chip, for each peripheral a "key" string is constructed using thi

 `perimap` entries are regexes matching on the above "key" string. First regex that matches wins.

-The IP version is particularly useful. It is an ST-internal "IP version" that's incremented every time changes are made to the peripheral, so it 
+The IP version is particularly useful. It is an ST-internal "IP version" that's incremented every time changes are made to the peripheral, so it
 correlates very well to changes in the peripheral's register interface.

 You should prefer matching peripherals by IP version whenever possible. For example:
@ -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).