Re: [oc] Automatic Core Metrics and Documentation

[Tom Hawkins <tom1@launchbird.com>]

On Friday 09 May 2003 05:07 pm, Niclas Hedhman wrote:
> On Thursday 08 May 2003 05:09 am, Tom Hawkins wrote:
> > This is a great idea and I think it could be, at least at some
> > extent, automated.
>
> Yes, once you get going, there is so many things one can do. The
> problem,as always, is how to get started.
>
> > I think XML based docs are important.  It would help enforce a
> > common standard, so all docs look and feel the same.  Plus, you
> > wouldn't have to waste time with formatting and layout.  We could
> > take it so far as to specify tags to automatically draw
> > waveforms, and maybe even block diagrams.
>
> Regarding documentation, I would recommend DocBook format, as it is
> a proven format for technical documention, and there are plenty of
> tools surrounding it in the OSS arena, incl (RUDI!) OpenOffice can
> export to it directly (so I have read but not tested).
>
> Apache Cocoon is about web publishing, and Apache Forrest is a
> application of Cocoon, that does complete skinned websites from
> mainly DocBook documents, including PDF generation and much more. I
> can help out to set all of that up, it is not that hard once you
> have done it. But where is the infrastructure? I don't think my own
> servers are suitable, since they are subjected to a fair amount of
> downtime, and access speed is not that great (high latency).
>

We use DocBook for Confluence documentation and it works well, but 
only after we got it working.  The DocBook tool chain is broken in 
spots and was a pain to get up and running.  I think we finally 
settled on OpenJade for pdf gen and xsltproc for the HTML.  I'll have 
to check out Apache Cocoon, however, we didn't have success with 
Apache JOP -- not sure how these 2 are related.

I wouldn't recommend DocBook for OC for one reason:  DocBook is much 
too general.  The whole point of XML was to be able to custom build 
tags for specific document types.  We don't need the generality and 
complexity of DocBook.  But what we do need are specific tags for 
core documentation, such as specifying a core's interface:

<interface>
  <input name="clock" width="1"/>
  <input name="data" width="8"/>
  <inout name="bus" width="16"/>
  <output name="result" width="24"/>
</interface>  

It would also be very cool to use XML to automatically generate 
waveform diagrams:

<waveform_diagram>
  <waveform name="clock" type="bin">0 1 0 1 0 1</waveform>
  <waveform name="result" type="hex">00 34 34 XX XX ZZ</waveform>
</waveform_diagram>

> Another novel concept that seems to work very well is Wiki. Wiki
> allows ANY user to modify a web page, or add new ones, without any
> special access rights. Since it is backed by CVS, if a vandal comes
> by, you just unwind the CVS to before the "attack". And hackers
> like the challange, not the damage.
>
> Niclas

Wiki is a cool idea, but I'm not sure this type of freedom is good for 
OC.  The biggest problem to OC not gaining industrial acceptance is 
the lack of structure.  In a open software community, structure and 
process are not critical.  But for hardware, no high profile 
semiconductor firm will consider using an open core unless they are 
confident it has been developed under a strict set of standards -- 
there is no room for ad hoc: not in the core, nor in the 
presentation.

Therefore, I propose the following:  OC projects enter ALL information 
into an XML document that must adhere to the OcProject.DTD.  This 
includes:
  - General Information
  - Project News
  - Core(s) Documentation
  - Module Information and Compile/Build Constraints
  - Testbench Information

>From this one document (which can be spread across multiple files), OC 
will automatically generate the following:
  - The Project Webpage
  - Documentation (HTML and PDF)
  - Links to CVS
  - Metric table of compilation results (warnings, errors, size, 
speed, etc).

This will give each project the same look and feel derived from the 
common standard, and hence, convince industry and OC is not an ad hoc 
organization.

Regards,
Tom 

-- 
Tom Hawkins
Launchbird Design Systems, Inc.
952-200-3790
tom1@launchbird.com
http://www.launchbird.com/


--
To unsubscribe from cores mailing list please visit http://www.opencores.org/mailinglists.shtml