Using IPXACT to Generate Documentation¶
Since last year, we have seen an increasing interest from customers regarding IPXACT. Customers specifically request the external interfaces and register descriptions in the IPXACT. Recently, we had a customer who requested DITA sources as well as IPXACT. We gave early access to our DITA sources to our customers. The initial feedback on the DITA sources was disappointing. The customer wanted modifications to our register layout description to match her output. This request put us in a quandary. This customer-specific change will impact all customer documentation. And, it would also require additional verification effort. To resolve this issue, we scheduled a call with the customer to understand their justification for this change. The outcome of this call is the following use case.
Use Case: Using IPXACT to Generate Documentation¶
Actor: Integration Engineer/Automation
Industry: Semiconductor
Use Case Overview: Generate external interfaces and register documentation from IPXACT.
Basic Flow
- Vendor provides external interface and register information in IPXACT format.
- Integration engineer integrates the IPXACT into their documentation flow.
- The documentation generation flow generates DITA from IPXACT.
- The documentation publishing flow generates PDFs/HTML from DITA.
What is IPXACT?¶
“IP-XACT is an XML format that defines and describes individual, re-usable electronic circuit designs (individual pieces of intellectual property, or IPs) to facilitate their use in creating integrated circuits (i.e. microchips). IP-XACT was created by the SPIRIT Consortium as a standard to enable automated configuration and integration through tools.”
What is DITA?¶
“The Darwin Information Typing Architecture or Document Information Typing Architecture (DITA) is an XML data model for authoring and publishing. It is an open standard[1] that is defined and maintained by the OASIS DITA Technical Committee.”
https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture
How did We Resolve the Customer Request¶
As the customer requested IPXACT and DITA. We managed to convince the customer to generate the register descriptions from the IPXACT than reuse our DITA. However, this meant, that we had to restructure the document (containing register information) to consolidate the register descriptions in one Part so that customer could easily replace it with the output from IPXACT.