diff --git a/text/0000-ipxact-generation-support.md b/text/0000-ipxact-generation-support.md new file mode 100644 index 0000000..bafcff3 --- /dev/null +++ b/text/0000-ipxact-generation-support.md @@ -0,0 +1,129 @@ +- 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 **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. + +### 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** + - 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). + + +**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 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 +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 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** + +# 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