RE: [dita-sidsc] IEEE P1685 purpose and scope

["Jeremy Ralph [DITA SIDSC]" <jralph-sidsc@productive-eda.com>]

Hi All,

My thinking is that IP-XACT and DITA have two distinct and separate
purposes.  

IP-XACT defines how to store SoC data for use by tools to automate the
development process.  This is at a static, architectural level defining the
IP libraries, the IP interfaces, the IP file locations, the design's IP
instantiations, and the interconnection thereof. This does not capture the
features and intent of the application specific logic that may be packaged
within IP-XACT. Such features and intent are generally captured into
programming languages like SystemC, SystemVerilog, Verilog, VHDL, C, etc.

In my view, DITA serves as a generic way to represent information in a
domain specialized topic-oriented fashion for the purpose of presentation to
humans.  One benefit with DITA is the ecosystem of authoring and publishing
tools.  With DITA you specify how the content is presented in tables and
bullets etc, and how topics are related for the purpose of human readable
presentation. IP-XACT is structured data that is essentially code for
development tools and does not define how the content is presented.

SPIRIT IP-XACT defines a model for the register content.  Most (if not all)
of the data that is required to construct register-map documentation is
available in IP-XACT and what is not can be added. By keeping the IP-XACT
separate from DITA we separate concerns in a nice way.  DITA has
presentation information, IP-XACT does not. To move forward I think we need
to define a way to represent register info in DITA so that it can be
processed with off-the-shelf DITA tools.  By mixing schemas using <foreign>
elements to reference IP-XACT content we will lose the ability to use
generic off-the-shelf DITA tools to process memory-map/register data as DITA
topics. SVG and MathML, which have been cited as examples of <foreign>
content are a little different than IP-XACT since their purpose is for
providing something that is presented to humans and can not easily be
represented in DITA.  

To me it makes a lot of sense to derive the DITA topics from IP-XACT and
hide details so that only the important technical publication information is
represented in DITA. This separation of concerns simplifies things for the
tech pubs teams so they don't need to learn the complexities of IP-XACT.
There are various ways to parse IP-XACT and convert/transform this into DITA
topics so I don't think we should impose any particular processing language
or way of doing this. With the IP-XACT schema and a DITA specialization the
transformation is essentially defined and I think our time as a group is
better spent  defining the structure of a DITA specialization rather than
implementing this transformation.

As for other standards, SPIRIT is working to sync up with OSCI TLM 2.0, so
maybe this is a standard we would want to look at too.  I agree with
Seraphim that there is other standards that should guide DITA-SIDSC. I also
agree that we should make the IP standards and the documentation standards
as interoperable as possible.

Anyhow, that's just my two cents, for what it's worth...

Cheers,
  Jeremy

--
Jeremy Ralph
PDTi      :: http://www.productive-eda.com
SpectaReg :: http://www.productive-eda.com/SpectaReg
Spec-down code and doc generation for register maps
 

> -----Original Message-----
> From: Larsen, Seraphim L [mailto:seraphim.l.larsen@intel.com] 
> Sent: Wednesday, August 22, 2007 11:54 AM
> To: bob.beims@freescale.com; dita-sidsc@lists.oasis-open.org
> Cc: gspencer@altera.com; cgettinger@astoriasoftware.com; 
> jmf@cadence.com; carriem@cadence.com; 
> Chona_Shumate@cymer.com; gillman@denali.com; mhall@ghs.com; 
> rmr@ghs.com; andrey@ghs.com; tomrz@ghs.com; 
> ian.mckenzie@infineon.com; 
> PacheeryNarayanan.Kutty@infineon.com; Ballard, Stephen R; 
> Shepton, Peter; trent.poltronetti@ip-extreme.com; 
> pierre-xavier.thomas@ip-extreme.com; Jolene.Jernberg@lsi.com; 
> Alex.Price@lsi.com; Stan.Relf@lsi.com; dc@ltx.com; 
> denise.fischer@luminarymicro.com; 
> Cathy.Riely@luminarymicro.com; dslevie@marvell.com; 
> sticer@marvell.com; bill_chown@mentor.com; 
> chenley@micron.com; bob.yencha@nsc.com; andrew.black@nxp.com; 
> addie.dijkstra@nxp.com; alfred.elkerbout@nxp.com; 
> constant.gordon@nxp.com; ralph.von.vignau@nxp.com; 
> bob_murray@pmc-sierra.com; gunnar.krause@qimonda.com; 
> sherryd@qualcomm.com; t_sself@qualcomm.com; 
> pmeador@austin.rr.com; alexandru.bejan@st.com; 
> sheila.dannunzio@st.com; jean@tensilica.com
> Subject: RE: [dita-sidsc] IEEE P1685 purpose and scope
> 
> Regardless of how it's phrased on that web page, I don't 
> think IP-XACT is a "metadata standard" in the sense that we 
> use the term "metadata"
> when working with XML.   The IP-XACT user guide says 
> 
>     The IP-XACT v1.2 specifications release is intended to 
> comprehensively address
>     Register Transfer Level (RTL) design, including packaging 
> configuration and SoC
>     integration.
> 
> I think when they mean "metadata", they mean metadata about 
> the design, not metadata in the way we mean in XML.  The 
> IP-XACT user guide illustrates each block of IP as having an 
> attached block of IP-XACT "metadata", but in the description 
> about how it really works, that IP-XACT metadata isn't just 
> additional data external to the IP, but rather contains all 
> the same information as the original IP, just in the IP-XACT format.  
> 
> So, perhaps "metadata" is just a case of poor usage of terminology?  
> 
> 
> In any case, here are some additional thoughts. 
> 
> IP-XACT is focused on RTL design information for SOCs.  RTL 
> mainly describes functional characteristics.  That's only a 
> subset of the kinds of information types that we need to 
> document in semiconductor documentation.  So, I'd agree that 
> IP-XACT can only be *one* of the standards that guides 
> development of DITA specializations for semiconductors.
> 
> You're right, it's not a technical documentation standard -- 
> it's an IP standard.  But since there is such an overlap 
> between the IP on one hand, and the things that go into the 
> documentation on the other hand, why not make the IP 
> standards and the documentation standards as interoperable as 
> possible?
> 
> Registers (as always) are a good example of this.  IP-XACT 
> seems to have a pretty comprehensive set of element tags to 
> describe register functionality, including most (or all) of 
> what you might want to put into a document describing those 
> registers (probably as register tables or diagrams).  So, if 
> we can create a specialization of some kind, that matches 
> very closely to the IP-XACT standard, won't that make it 
> easier to interchange data between the two standards?
> 
> Maybe (as Seth has suggested in another forum) it might be 
> possible to pull in the entire IP-XACT schemas, in the same 
> way that DITA 1.1 allows you to use the <foreign> element to 
> pull in SVG and MathML?  Or maybe we can pull in subsets?  I 
> don't really know how that works or what it would entail, but 
> maybe we could look into it some more.
> 
> For our immediate Phase 1 work, maybe we should look more 
> closely to see whether our register examples could actually 
> be described by the IP-XACT structures.  If yes, why not try 
> to duplicate them?  If no, what are the exceptions?
> 
> 
> Anyway, good discussion, thanks for raising the topic!
> 
> 
> Seraphim Larsen
> Intel Corporation * ECG TechComm
> Chandler, AZ * (480) 552-6504
> My opinions only; I don't speak for Intel. 
> 
>  
> 
> -----Original Message-----
> From: bob.beims@freescale.com [mailto:bob.beims@freescale.com]
> Sent: Wednesday, August 22, 2007 10:41 AM
> To: dita-sidsc@lists.oasis-open.org
> Subject: [dita-sidsc] IEEE P1685 purpose and scope
> 
> DITA SIDSC participants;
> 
> As a follow up to today's teleconference, I was reviewing 
> some IP-XACT information and ran across this web page:
> 
> http://www.eda-stds.org/spirit-p1685/
> 
> I'm wondering if the use of the term "documents" in the 
> phrase "... for meta-data that documents the characteristics 
> ..." might not be causing confusion.
> 
> From the perspective of an end-user of semiconductor devices, 
> the meta-data captured in an IP-XACT file is *far* from what 
> they would consider "documentation". IP-XACT files hold a 
> basic *description*, yes, but nothing close to what an 
> end-user needs in the way of procedural and functional 
> *documentation* in order to use the device. At least that's 
> my perspective.
> 
> This leads me to the conclusion that within the SIDSC we 
> should definitely use the IP-XACT schema as *one of* the 
> sources to guide our development of DITA elements. But we 
> should be very careful to understand that IP-XACT is *not* a 
> technical documentation standard, but is rather a *meda-data* 
> standard.
> 
> A subtle difference, but an important one, in my opinion.
> 
> Thoughts?
> Bob
>