From 017547fb9bd7d00781c5ba091935ba0cf1f824a0 Mon Sep 17 00:00:00 2001 From: chick Date: Tue, 22 Jan 2019 09:31:20 -0800 Subject: [PATCH 1/3] Initial work in progress RFC to capture initial work and to document decisions made about the scope of work --- text/0000-ipxact-generation-support.md | 80 ++++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 text/0000-ipxact-generation-support.md diff --git a/text/0000-ipxact-generation-support.md b/text/0000-ipxact-generation-support.md new file mode 100644 index 0000000..59edde4 --- /dev/null +++ b/text/0000-ipxact-generation-support.md @@ -0,0 +1,80 @@ +- 0000 IP-XACT Generation Support +- Start Date: 2019-01-18 +- RFC PR: (leave this empty) +- Chisel-lang Issue: (leave this empty) + +# Summary +[summary]: #summary + +Provide a library that will enable generate IP-XACT XML collateral from an annotated Chisel circuit. +IP-XACT is defined in IEEE 1685-2014. +It provides hardware descriptions that help in combining Hardware IP from multiple sources. + +# Motivation +[motivation]: #motivation +A number of EDA vendors are able to ingest IP-XACT interface descriptions and use them to assist +in component integration and testing. Vendors have a number of IP standards such as AXI that have pre-existing tests +that can be used on a Chisel circuit that implements AXI if it can present IP-XACT. + +# Guide-level explanation +[guide-level-explanation]: #guide-level-explanation + +Chisel-lang's IP-XACT support comprises circuit, interface, and parameter annotations and Firrtl Stages and +transformation that can generate and IP-XACT XML file, that describes the following + +- Interface Port Definitions +- Bus Definitions with mapping between logical and physical ports +- Address map information for where interfaces sit on a bus +- Parameter information that describes how the circuit was generated. + +# Reference-level explanation +[reference-level-explanation]: #reference-level-explanation + +IP-XACT support will be require dsptools and rocket chip facilities. It will initially support AXI-4 and a small +number of pre-existing standards. + +An initial reference example is in this [example in dsptools](https://github.com/ucb-bar/dsptools/blob/d56eaee509d60f14a32d7a7d85952e9494d2da34/rocket/src/test/scala/ipxact/AXI4GCD.scala). + + +**TODO** + +- Additional patterns that will be supported +- Describe the annotations that will be supported +- File management that describes where generated IP will be placed. + + +# Drawbacks +[drawbacks]: #drawbacks + +IP-XACT has differing degrees of support amongst vendors and multiple versions of the standard can be found in the wild. +There may be a fair amount of hand editing in order to make the IP-XACT consumable by a particular vendor and that +work may not be transferable. +XML can be an awkward format with high overhead. + +# Rationale and alternatives +[rationale-and-alternatives]: #rationale-and-alternatives + +- Providing a library for IP-XACT generation will simplify the work required of developers +- It will help ease barriers to adoption of Chisel-lang ecosystem. +- It may provide tools for easier integration of 3rd paty IP into Chisel-lang projects. +- There no real alternative standards in this space. + +# Prior art +[prior-art]: #prior-art + +Several existing Chisel designs have generated by a small collection of project specific helpers added to the +DspTools and RocketDspTools repos. +This code needs to be standardized and moved to make it more generally accessible and applicable. +Note the occurrences of the search term ipxact on github in freechips, ucb-bar, and ucb-art projects. + +# Unresolved questions +[unresolved-questions]: #unresolved-questions + +- What is a reasonable set of annotations to implement this project +- Most of the pre-existing work relies on rocket-chip, is that too high a bar in order to generate IP-XACT + +# Future possibilities +[future-possibilities]: #future-possibilities + +- IP-XACT could be a useful tool in testing. Unit tests and circuit verification could be based on the types IP-XACT describes. +- IP-XACT could be ingested and used to build chisel-lang black boxes to aid 3rd party IP integration. \ No newline at end of file From ed34a699f46a2bdbc6faa89030ac7d022c9cd09d Mon Sep 17 00:00:00 2001 From: chick Date: Wed, 20 Feb 2019 11:49:55 -0800 Subject: [PATCH 2/3] Added a bit more content to ipxact proposal --- text/0000-ipxact-generation-support.md | 59 +++++++++++++++++--------- 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/text/0000-ipxact-generation-support.md b/text/0000-ipxact-generation-support.md index 59edde4..50a8f3e 100644 --- a/text/0000-ipxact-generation-support.md +++ b/text/0000-ipxact-generation-support.md @@ -6,21 +6,21 @@ # Summary [summary]: #summary -Provide a library that will enable generate IP-XACT XML collateral from an annotated Chisel circuit. -IP-XACT is defined in IEEE 1685-2014. +Provide a library that will enable generate **IP-XACT** XML collateral from an annotated **Chisel** circuit. +**IP-XACT** is defined in IEEE 1685-2014. It provides hardware descriptions that help in combining Hardware IP from multiple sources. # Motivation [motivation]: #motivation -A number of EDA vendors are able to ingest IP-XACT interface descriptions and use them to assist +A number of EDA vendors are able to ingest **IP-XACT** interface descriptions and use them to assist in component integration and testing. Vendors have a number of IP standards such as AXI that have pre-existing tests -that can be used on a Chisel circuit that implements AXI if it can present IP-XACT. +that can be used on a **Chisel** circuit that implements AXI if it can present **IP-XACT**. # Guide-level explanation [guide-level-explanation]: #guide-level-explanation -Chisel-lang's IP-XACT support comprises circuit, interface, and parameter annotations and Firrtl Stages and -transformation that can generate and IP-XACT XML file, that describes the following +**chisel-lang**'s **IP-XACT** support comprises circuit, interface, and parameter annotations and **Firrtl** Stages and +transformation that can generate and **IP-XACT** XML file, that describes the following - Interface Port Definitions - Bus Definitions with mapping between logical and physical ports @@ -30,9 +30,30 @@ transformation that can generate and IP-XACT XML file, that describes the follow # Reference-level explanation [reference-level-explanation]: #reference-level-explanation -IP-XACT support will be require dsptools and rocket chip facilities. It will initially support AXI-4 and a small -number of pre-existing standards. - +**IP-XACT** support will be require dsptools and rocket chip facilities. +It will initially support **AXI4** and a small number of pre-existing devices within that scope. +The xml generation will be created from an annotation sequence and an underlying **Firrtl** file. + +- Generation of **IP-XACT** will be triggered by one or more ParamsAnnotation where the paramsClassName is AXI4Bundle Parameter + - That may be a command line generated + - It may be generated by a trait mixed-in with particular modules +- For each annotation like this there will be a separate xml file container generated. +- The Sections of the file will be + - **busInterfaces** + - one or more **busInterface** describing the portmaps for for a bus + - **addressSpaces** + - more information required to construct this + - **memoryMaps** + - one or more **memoryMap** describing the individual fields of a **busInterface** + - **model** + - top level information for this file + - **fileSets** + - lists of files associated with this content + - **parameters** + - parameters used by **Chisel** to generate the module and devices + +Most of the generation of the above will be explicitly based on annotations and the **Firrtl**. +Some elements, such as the busInterface portMaps will come from hand-coded mappings between ports and established **AXI4** names. An initial reference example is in this [example in dsptools](https://github.com/ucb-bar/dsptools/blob/d56eaee509d60f14a32d7a7d85952e9494d2da34/rocket/src/test/scala/ipxact/AXI4GCD.scala). @@ -46,35 +67,35 @@ An initial reference example is in this [example in dsptools](https://github.com # Drawbacks [drawbacks]: #drawbacks -IP-XACT has differing degrees of support amongst vendors and multiple versions of the standard can be found in the wild. -There may be a fair amount of hand editing in order to make the IP-XACT consumable by a particular vendor and that +**IP-XACT** has differing degrees of support amongst vendors and multiple versions of the standard can be found in the wild. +There may be a fair amount of hand editing in order to make the **IP-XACT** consumable by a particular vendor and that work may not be transferable. XML can be an awkward format with high overhead. # Rationale and alternatives [rationale-and-alternatives]: #rationale-and-alternatives -- Providing a library for IP-XACT generation will simplify the work required of developers -- It will help ease barriers to adoption of Chisel-lang ecosystem. -- It may provide tools for easier integration of 3rd paty IP into Chisel-lang projects. +- Providing a library for **IP-XACT** generation will simplify the work required of developers +- It will help ease barriers to adoption of **chisel-lang** ecosystem. +- It may provide tools for easier integration of 3rd party IP into **chisel-lang** projects. - There no real alternative standards in this space. # Prior art [prior-art]: #prior-art -Several existing Chisel designs have generated by a small collection of project specific helpers added to the +Several existing **Chisel** designs have generated by a small collection of project specific helpers added to the DspTools and RocketDspTools repos. This code needs to be standardized and moved to make it more generally accessible and applicable. -Note the occurrences of the search term ipxact on github in freechips, ucb-bar, and ucb-art projects. +Note the occurrences of the search term ipxact on github in freechipsproject, ucb-bar, and ucb-art projects. # Unresolved questions [unresolved-questions]: #unresolved-questions - What is a reasonable set of annotations to implement this project -- Most of the pre-existing work relies on rocket-chip, is that too high a bar in order to generate IP-XACT +- Most of the pre-existing work relies on rocket-chip, is that too high a bar in order to generate **IP-XACT** # Future possibilities [future-possibilities]: #future-possibilities -- IP-XACT could be a useful tool in testing. Unit tests and circuit verification could be based on the types IP-XACT describes. -- IP-XACT could be ingested and used to build chisel-lang black boxes to aid 3rd party IP integration. \ No newline at end of file +- **IP-XACT** could be a useful tool in testing. Unit tests and circuit verification could be based on the types **IP-XACT** describes. +- **IP-XACT** could be ingested and used to build **chisel-lang** black boxes to aid 3rd party IP integration. \ No newline at end of file From c1b42e39219202af613d58fe3c24a3c1da484447 Mon Sep 17 00:00:00 2001 From: chick Date: Fri, 22 Mar 2019 14:27:28 -0700 Subject: [PATCH 3/3] Filling out RFC with details learned in Cadence chamber. --- text/0000-ipxact-generation-support.md | 38 ++++++++++++++++++++++---- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/text/0000-ipxact-generation-support.md b/text/0000-ipxact-generation-support.md index 50a8f3e..bafcff3 100644 --- a/text/0000-ipxact-generation-support.md +++ b/text/0000-ipxact-generation-support.md @@ -34,11 +34,39 @@ transformation that can generate and **IP-XACT** XML file, that describes the fo It will initially support **AXI4** and a small number of pre-existing devices within that scope. The xml generation will be created from an annotation sequence and an underlying **Firrtl** file. -- Generation of **IP-XACT** will be triggered by one or more ParamsAnnotation where the paramsClassName is AXI4Bundle Parameter - - That may be a command line generated - - It may be generated by a trait mixed-in with particular modules -- For each annotation like this there will be a separate xml file container generated. -- The Sections of the file will be +### Annotating a module that generates IP-XACT XML +A module that should have XML generated will require that the developer mark the module for generation +with the `Ipxact(moduleInstance)` command. This will add two annotations, `IpxactModuleAnnotation` and +`IpxactBundleMemoizerTrigger` that reference `IpxactGeneratorTransform` and `IpxactBundleCaptureTransform` respectively. + +### Memo-izing Bundles + +Bundles that are referenced as IP-XACT annotations need both the top level bundle name as well as all the +lower level fields. To capture and retain the top level names there is second HighForm transform named +`IpxactBundleCaptureTransform` that will identify and preserve in `IpxactBundleName` annotations the original bundle +names before they are expanded during FIRRTL lowering passes. + +### Generation of **IP-XACT** will be triggered by a set of the following annotations: + - **IpxactModuleAnnotation** + - This targets a specific module. + - Each annotation of this type will cause the creation of a separate IP-XACT .xml file. + - **RegFieldDescMappingAnnotation** + - **ParamsAnnotation**, with the following paramsClassName + - freechips.rocketchip.amba.axi4.AXI4BundleParameters + - ipxact. for example: ipxact.GCDParams + > Complexity: There can be multiple annotations initially whose `Target` components point to different bundles, + for example, consider that there are two `data_in` and `data_out`. + These annotations will be exploded into multiple annotations one per bundle field (recursive) so there will be + `data_in_field_0`, ..., `data_in_field_N` and `data_out_field_0`, ..., `data_out_field_N`. + This is good because I need to describe each of these. + But, IP-XACT output wants these fields to be nested beneath there original bundle names. + The expansion of the bundles into their fields obscures the original Bundle names. + If I had two transforms one running before and one running after the expansion I could memoize the Bundle names. + But there maybe more elegant solutions. + + - **AddressMapAnnotation** + +### The Sections of the file will be - **busInterfaces** - one or more **busInterface** describing the portmaps for for a bus - **addressSpaces**