Merge pull request #69 from Wassasin/metapac-extract

Move towards clap-based CLI tool with explicit metapac extract and generate commands

Author: Wassasin

Cargo.lock

@@ -8,16 +8,38 @@ If you want to regenerate the pac, you need to clone with `--recursive`.
 
 If you forgot this, you can use `git submodule update --checkout --init` to fetch the submodules.
 
+## PAC vs MetaPAC
+
+This crate is in transition from generating the PAC from the NXP provided SVD files, to a metapac approach where the SVD is only used to extract general peripheral definition files.
+A metapac definition file then specifies which peripherals are included in the chip.
+This is very useful when a vendor has used similar peripheral IPs across their portfolio.
+This allows HAL authors to write drivers for these peripheral IPs, instead of having to copy-paste them for each supported chipset.
+
+Because the crate is in transition, some of them use the PAC method, and some of them are part of the metapac.
+
+## Supported chips
+
+| Chip | Type |
+|------|------|
+| MIMXRT1011 | PAC |
+| MIMXRT1062 | PAC |
+| MIMXRT1064 | PAC |
+| MIMXRT685S | PAC |
+| LPC55S16 | PAC |
+| LPC55S69 | PAC |
+| MCXN947 | PAC |
+| MCXA256 | MetaPAC |
+| MCXA577 | MetaPAC |
+
 ## Tour
 
-The `data` directory contains the SVD files, board metadata, and chiptool transformations needed to
+The [`data`](/data) directory contains the SVD files, board metadata, and chiptool transformations needed to
 generate the nxp-pac crate. This data is used by the code generation tool.
 
-The `generator` directory contains the code generation tool for generating the code in the `nxp-pac` crate.
-If you want change the way the `nxp-pac` crate is generated please see this directory.
-Run it using `cargo run -p generator -- <CHIP>`.
+The [`generator`](/generator) directory contains the code generation tool for generating the code in the [`nxp-pac`](/nxp-pac) crate.
+If you want change the way the [`nxp-pac`](/nxp-pac) crate is generated please see this directory.
 
-The `nxp-pac` directory contains the nxp-pac crate. If you are looking for a peripheral access crate for
+The [`nxp-pac`](/nxp-pac) directory contains the nxp-pac crate. If you are looking for a peripheral access crate for
 an NXP microcontroller, please see this directory. You should never need to manually edit the source
 code in this directory. The metadata will need to be updated to support new microcontrollers.
 

README.md

@@ -1,13 +1,33 @@
-The generator will put transformed SVD data into the `raw` folder.
-This is not used for anything later on, but serves for debugging purposes.
+# Metapac peripherals
+This directory contains the register and type definitions for peripheral IPs that are included in NXP chipsets.
+
+NXP does not give us the internal name of these peripheral IPs. (for example: Synopsis USB-OTG rev. 2)
+It's up to us to create some sort of consistency there.
+
+These files are manually curated and considered to be the 'source of truth' when generating the metapac Rust source code.
+Even though they are assembled by hand, they are derived from the SVD files provided by the vendor.
+
+This derivation ideally happens through chiptool transforms, but manual changes to these files are also allowed.
+When adding manual changes, please note them with appropriate comments in the YAML files.
+
+
+
+## Updating
+The generator when using the `extract` command will put transformed SVD data into the `raw` folder.
+Anything in this folder is not used directly, but can be used by you as a start to define metapac peripherals and chips.
+
 This is per device:
 
-- A YAML per peripheral, directly from the SVD
-- A `_debug_ir.yaml` that represents the non-metapac version of the pac. It's the result of running the SVD through the transforms.
-  This is a good source when porting over a pac to the metapac.
+- A YAML per peripheral, with transforms applied and namespaces stripped. These files are suitable to base your metapac peripheral definition files on.
+- Everything in the `raw/original` folder, which are the same files but without the namespaces stripped. These files are the direct output of the transforms, and thus useful when developing the transforms.
 - `_addresses.json`: A list of all peripherals and their addresses, taken from the SVD. Handy for adding it to the metadata.
 - `_interrupts.json`: A list of all interrupts and their numbers, taken from the SVD. Handy for adding it to the metadata.
 
-The other folders contain the manually curated YAMLs of the peripherals.
-The exact names are not prescribed. NXP doesn't give us names, so it's up to us to create some sort of consistency there.
-The metadata points to those YAMLs.
+Thus the workflow to add or change a peripheral is as follows: (change MCXA577 to your chipset)
+* Run `cargo run -p generator -- extract MCXA577`
+* Open `/data/metadata/peripherals/raw/MCXA577/<peripheral>.yaml`
+* Check if it is correct, if not change the transforms in `/data/transforms` and re-run `extract` until it is.
+* Copy the file over, and check the changes compared to what was already committed when relevant.
+* It is also allowed to change the file by hand at this point, but please use comments to denote what and why you changed (and why you didn't use a transform).
+* Generate the new nxp-pac code by running `cargo run -p generator -- generate MCXA577`
+* Check the code changes and commit both the nxp-pac code and the metadata definitions.

data/metadata/peripherals/README.md

@@ -111,7 +111,7 @@ block/Trng:
     description: Statistical Check Run Length 6+ Count Register.
     byte_offset: 56
     access: Read
-    fieldset: SCr6pc
+    fieldset: Scr6pc
   - name: scr6pl
     description: Statistical Check Run Length 6+ Limit Register.
     byte_offset: 56

data/metadata/peripherals/mcxa/TRNG.yaml

@@ -3,46 +3,46 @@ transforms:
     from: hsadc::(.*)
     to: adc::$1
     type: All
-  
+
   - !Rename
     from: adc::Hsadc
     to: adc::Adc
     type: Block
 
   - !MergeEnums
-    from: adc::vals::Cmdl(\d+)(.+)
-    to: adc::vals::$2
+    from: adc::Cmdl(\d+)(.+)
+    to: adc::$2
 
   - !MergeFieldsets
-    from: adc::regs::Cmdl(\d+)
-    to: adc::regs::Cmdl
+    from: adc::Cmdl(\d+)
+    to: adc::Cmdl
 
   - !MakeRegisterArray
     blocks: adc::Adc
     from: cmdl(\d+)
     to: cmdl
 
   - !MergeEnums
-    from: adc::vals::Cmdh(\d+)(.+)
-    to: adc::vals::$2
+    from: adc::Cmdh(\d+)(.+)
+    to: adc::$2
 
   - !MergeFieldsets
-    from: adc::regs::Cmdh(\d+)
-    to: adc::regs::Cmdh
-  
+    from: adc::Cmdh(\d+)
+    to: adc::Cmdh
+
   - !MakeRegisterArray
     blocks: adc::Adc
     from: cmdh(\d+)
     to: cmdh
 
   - !DeleteEnums
-    from: adc::vals::Swt(\d+)
+    from: adc::Swt(\d+)
 
   # ADC channel select is not correct at all, better use bare u8.
   - !DeleteEnums
-    from: adc::vals::Adch
+    from: adc::Adch
 
   - !MakeFieldArray
-    fieldsets: adc::regs::Swtrig
+    fieldsets: adc::Swtrig
     from: swt(\d+)
     to: swt

data/transforms/mcxa/adc.yaml

@@ -1,23 +1,23 @@
 transforms:
   - !MergeFieldsets
-    from: can::regs::(Cs|Id)(\d+)
-    to: can::regs::$1
+    from: can::(Cs|Id)(\d+)
+    to: can::$1
 
   - !MergeFieldsets
-    from: can::regs::Mb(\d+)b(Cs|Id)
-    to: can::regs::Mbb$2
+    from: can::Mb(\d+)b(Cs|Id)
+    to: can::Mbb$2
 
   - !DeleteFieldsets
-    from: can::regs::Mb(\d+)bWord(\d+)
-  
+    from: can::Mb(\d+)bWord(\d+)
+
   - !DeleteFieldsets
-    from: can::regs::Word(\d+)
+    from: can::Word(\d+)
 
   - !MakeRegisterArray
     blocks: can::Can
     from: word(0|1)(\d+)
     to: word$1
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: id(\d+)
@@ -27,22 +27,22 @@ transforms:
     blocks: can::Can
     from: cs(\d+)
     to: cs
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: mb(\d+)_8b_cs
     to: mb_8b_cs
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: mb(\d+)_16b_cs
     to: mb_16b_cs
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: mb(\d+)_32b_cs
     to: mb_32b_cs
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: mb(\d+)_64b_cs
@@ -52,22 +52,22 @@ transforms:
     blocks: can::Can
     from: mb(\d+)_8b_id
     to: mb_8b_id
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: mb(\d+)_16b_id
     to: mb_16b_id
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: mb(\d+)_32b_id
     to: mb_32b_id
-  
+
   - !MakeRegisterArray
     blocks: can::Can
     from: mb(\d+)_64b_id
     to: mb_64b_id
-  
+
   # For now delete all extra word registers.
   # Can be re-added when needed for HAL implementation.
   - !DeleteRegisters

data/transforms/mcxa/can.yaml

@@ -1,4 +1,4 @@
 transforms:
   - !MergeEnums
-    from: cdog::vals::(Timeout|Miscompare|Sequence|State|Address)Ctrl
-    to: cdog::vals::Ctrl
+    from: cdog::(Timeout|Miscompare|Sequence|State|Address)Ctrl
+    to: cdog::Ctrl

data/transforms/mcxa/cdog.yaml

@@ -1,50 +1,50 @@
 transforms:
   - !RenameEnumVariants
-    enum: ctimer::vals::([A-Za-z]+)(\d+)(.+)
+    enum: ctimer::([A-Za-z]+)(\d+)(.+)
     from: ([A-Z]+)[0-9O]([A-Z]+)_([0-9])
     to: $1$2$3
 
   - !RenameEnumVariants
-    enum: ctimer::vals::Mr[0-9]s
+    enum: ctimer::Mr[0-9]s
     from: ([A-Z_]+)([0-9])
     to: MRS$2
 
   - !MergeEnums
-    from: ctimer::vals::Cap(\d+)(.+)
-    to: ctimer::vals::Cap$2
+    from: ctimer::Cap(\d+)(.+)
+    to: ctimer::Cap$2
     skip_unmergeable: false
 
   - !MergeEnums
-    from: ctimer::vals::Em(\d+)
-    to: ctimer::vals::Em
+    from: ctimer::Em(\d+)
+    to: ctimer::Em
     skip_unmergeable: false
 
   - !MergeEnums
-    from: ctimer::vals::Emc(\d+)
-    to: ctimer::vals::Emc
+    from: ctimer::Emc(\d+)
+    to: ctimer::Emc
     skip_unmergeable: false
 
   - !MergeEnums
-    from: ctimer::vals::Mr(\d+)i
-    to: ctimer::vals::Mri
+    from: ctimer::Mr(\d+)i
+    to: ctimer::Mri
     skip_unmergeable: false
 
   - !MergeEnums
-    from: ctimer::vals::Mr(\d+)r
-    to: ctimer::vals::Mrr
+    from: ctimer::Mr(\d+)r
+    to: ctimer::Mrr
     skip_unmergeable: false
 
   - !MergeEnums
-    from: ctimer::vals::Mr(\d+)rl
-    to: ctimer::vals::Mrrl
+    from: ctimer::Mr(\d+)rl
+    to: ctimer::Mrrl
     skip_unmergeable: false
 
   - !MergeEnums
-    from: ctimer::vals::Mr(\d+)s
-    to: ctimer::vals::Mrs
+    from: ctimer::Mr(\d+)s
+    to: ctimer::Mrs
     skip_unmergeable: false
 
   - !MergeEnums
-    from: ctimer::vals::Pwmen(\d+)
-    to: ctimer::vals::Pwmen
+    from: ctimer::Pwmen(\d+)
+    to: ctimer::Pwmen
     skip_unmergeable: false

data/transforms/mcxa/ctimer.yaml

@@ -2,26 +2,26 @@ transforms:
   - !RenamePeripherals
     from: EDMA0_TCD0
     to: EDMA_0_TCD0
-    
+
   - !Rename
     from: edma0_tcd0::(.*)
     to: edma_0_tcd0::$1
     type: All
 
   - !Rename
-    from: edma_0_tcd0::vals::Ssize
-    to: edma_0_tcd0::vals::Size
+    from: edma_0_tcd0::Ssize
+    to: edma_0_tcd0::Size
 
   - !ModifyFieldsEnum
-    fieldset: edma_0_tcd0::regs::TcdAttr
+    fieldset: edma_0_tcd0::TcdAttr
     field: dsize
-    enum: edma_0_tcd0::vals::Size
+    enum: edma_0_tcd0::Size
 
   - !DeleteEnums
-    from: edma_0_tcd0::vals::Int
+    from: edma_0_tcd0::Int
 
   - !DeleteEnums
-    from: edma_0_tcd0::vals::(S|D)mod
+    from: edma_0_tcd0::(S|D)mod
 
   - !RenameInterrupts
     from: DMA0_CH([0-9]+)