2.1 includes mostly new features and a few (hidden to you) API changes.  Changes include:

• end of test objection mechanism
• component callbacks
• new field macros for more types

As usual – I have the updated OVM docs posted here:

http://www.intelligentdv.com/documents/index.html#ovmdox

If you find a bug in the doxygen documentation, then please let me know.

Enjoy!

1.2 is an all new architecture. Changes include:

• update of support classes to parametrized classes (generators, channel, etc.)
• hierarchical structure like OVM — everything from vmm_object base; testbench components from vmm_unit
• hierarchical phasing: phasing built into the unit –> implicit phasing in unit children (so now its built into the xactor)
• class factory – replace components / objects from the testcase
• component interconnect with TLM2.0
• hierarchical configuration

As usual – I have the updated VMM docs posted here:

http://www.intelligentdv.com/documents/index.html#vmmdox

If you find a bug in the doxygen documentation, then please let me know.

New!

Finally!  Released what has been sitting in trunk for months now…

This release includes:

• bugfix: SystemVerilog interfaces with parameters not supported (#47)
• change: improved routine for processing parameterizations

You can pick up the release from the downloads page here:

http://intelligentdv.com/downloads/index.html#doxygentools

Or – you can grab it directly from the subversion repository with your svn client (or using the WebSVN site here).

TIP! These blog announcements (like this one) often lag the actual release by several weeks…  so I recommend subscribing to the RSS feed for the Doxygen tags on the WebSVN site to keep up-to-date.

A Reminder: the doxygen filter is not a grammar — it, like the doxygen tool, is a lexical parser. So – you will find bugs.  And when you do – please file them to the bug tracker here:

http://intelligentdv.com/bugs/

Your tickets in the tracker are what pushes the filter improvements.

-improved!

2.0.3 includes mostly bug fixes with a few performance improvements.  Changes include:

• addition of messaging/logging macros to improve performance
• promotion of convert2string() from ovm_transaction to ovm_object – replacing the do_sprint() method.
• improved configuration performance
• and a bunch of bug fixes

As usual – I have the updated OVM docs posted here:

http://www.intelligentdv.com/documents/index.html#ovmdox

If you find a bug in the doxygen documentation, then please let me know.

-fix

As usual – documentation is posted here:

http://www.intelligentdv.com/documents/index.html#vmmdox

If you find a bug in the doxygen documentation, then please let me know.

-Interop

Shows how to:

• build a modern randomized SystemVerilog verification component / transaction in a generic fashion
• integrate a generic transaction / component into the VMM
• write a VMM transaction / transactor driver / transactor monitor
• build a VMM environment and signal layer
• connect a DUT to a class based testbench using interfaces with modport, clocking blocks and virtual interfaces
• use SystemVerilog constraints to get a desired result
• implement functional coverage
• use VMM callbacks to collect functional coverage
• create (and run) tests in the VMM style (vmm_test) – by instantiating and constraining the environment

Can be used to:

• drive one (or more) active high or low reset(s)
• drive a sync/async assert/deassert reset
• drive reset for a specific or random range duration
• assert / deassert asynchronously randomly within the clock period
• monitor existing reset(s) for coverage
• can be driven with transactions or with direct method calls of the bfm methods

All of the SystemVerilog library source code including the code required to document and run the environment are available to download here:

http://www.intelligentdv.com/downloads/index.html#svreset

The library is fully documented with doxygen and that documentation is available here:

http://www.intelligentdv.com/documents/index.html#resetdox

The complete details of what the library includes are after the break.

The library includes:

• A Base Library that includes:
  • Reset Transaction Class – idv_rst_trans – describes the DUT reset. The properties allow description of:
    • assertion clock relationship (async/sync)
    • deassertion clock relationship (async/sync)
    • number of cycles that reset is active
    • number of cycles to wait prior to assertion
    • number of cycles to wait after reset (prior to returning from the reset task)
    • for async assert: time from rising edge to assert
    • for async deassert: time from rising edge to deassert
  • Reset Transaction Defaults Class – idv_rst_trans_default – constrains the DUT reset. This class can be extended with the user overriding the constraints or used as an example to be reimplemented with user defined constraints.
  • Reset Bus Functional Model (BFM) Transactor Class – idv_rst_bfm – generates a reset based on the passed reset description
    • do_reset method does the reset based on passed in reset transaction (idv_rst_trans)
    • on construction handle to virtual interface (idv_rst_if) passed in
    • on construction definition of active high/low reset – BFM can generate active high or low reset
  • Reset Bus Functional Monitor Transactor Class – idv_rst_mon – generates a reset transaction (description) based on the monitored interface
    • do_reset method waits for reset to occur on interface and outputs a populated reset transaction object
    • on construction handle to virtual interface (idv_rst_if) passed in
    • on construction definition of active high/low reset – can monitor active high or low reset
    • implementation of monitor is limited to monitoring reset duration; other transaction properties are not populated
  • Reset Interface – idv_rst_if – SystemVerilog Interface
    • module ports (modport) defined for BFM, Monitor, and DUT perspectives
    • clocking block defined for BFM and Monitor – for synchronous activity
• A VMM implementation of the library that includes:
  • VMM Data Transaction Class – idv_rst_data – a vmm_data extended wrapper around the idv_rst_trans class. Includes implementation of the required vmm_data methods. File also includes macro calls to create the vmm_channel IPC channel and vmm_atomic_gen atomic generator.
  • VMM Xactor BFM Class – idv_rst_bfm_xactor – a vmm_xactor extended wrapper around the idv_rst_bfm class. Includes implementation of the required vmm_xactor methods. Input interconnect with generator uses vmm_channel.
  • VMM Xactor Monitor Class – idv_rst_mon_xactor – a vmm_xactor extended wrapper around the idv_rst_mon class. Includes implementation of the required vmm_xactor methods. Output interconnect with sink uses vmm_channel.
  • VMM Xactor Callbacks Class – idv_rst_xactor_callbacks – a vmm_xactor_callbacks extension with pure virutual pre and post transaction callback methods. Can be appended to either the reset bfm or monitor transactor.
  • VMM Xactor Coverage Callback Class – idv_rst_cov_callback – an implementation of reset coverage – can be appended to either the reset bfm or monitor xactor.
• A complete VMM environment to test the library, and to serve as an example VMM environment, that includes:
  • TestBench Top – tb_top – the signal layer top – instantiates the DUT, interfaces, and clock generator
  • Environment – env – the environment top – configures and instantiates the generators and transactors; drives the testbench sequence
  • Tests – testXXX – the testcases; each constrains a combination of the environment configuration and/or environment transactions to acheive a goal
  • Testcases – example testcases to drive specific scenarios

-reset

This release includes:

• bugfix: macros with `” aren’t properly handled (stringize issue) (#39)
• bugfix: protected keyword does not play well with multi-line enums and member variables (#45)
• bugfix: import package should be ignored (#40)
• feature: add support for SV Packages (#20)
• workaround: Does not handle nested OVM macros (doxygen issue) (#43)
• change: comments are no longer filtered from source (doxyfile delta change)
• change: added language switch for sv/svh extension — C++

You can pick up the release from the downloads page here:

http://intelligentdv.com/downloads/index.html#doxygentools

Or – you can grab it directly from the subversion repository with your svn client (or using the WebSVN site here).

TIP! These blog announcements (like this one) often lag the actual release by several weeks…  so I recommend subscribing to the RSS feed for the Doxygen tags on the WebSVN site to keep up-to-date.

A Reminder: the doxygen filter is not a grammar — it, like the doxygen tool, is a lexical parser. So – you will find bugs.  And when you do – please file them to the bug tracker here:

http://intelligentdv.com/bugs/

Your tickets in the tracker are what pushes the filter improvements.

-another fix

This includes syntax files for:
- Kate (KDE Linux Editor)
- Crimson (Windows Editor)
- SciTE (Windows Editor – with syntax color RTF copy support)
and
- GeSHi (PHP based Syntax Highlighter)

So what’s GeSHi? Awesomeness!

GeSHi is how I have color coded SystemVerilog code posted on my blog (using WordPress with the WP-Syntax plugin) — like here in this blog post.

And GeSHi is how I have color coded code posted in my WebSVN repository – like here in the SVtimers repository.

Yeah – GeSHi is pretty cool.
I’ve sent my syntax file to the GeSHi team – hopefully they’ll accept it in their release.

You can download this release here:

http://intelligentdv.com/downloads/index.html#syntaxfiles

-Syntax-2009-d8

Without any special comments doxygen will parse your code and generate documentation that will show you all of your:

• files
• classes
• programs
• interfaces
• modules
• macros (defines)
• functions
• tasks
• variables

Additionally – the tool will show you the class member variables, member functions, inheritance hierarchy and usage (collaboration).

Unfortunately the tool can’t document what each is.  For example: doxygen can ’see’ that you’ve written a classA that extends classB — but it can’t tell you what the classA is for or how to use it. This is where the addition of doxygen comments come in. You can augment the automatic documentation with comments that disccuss the details of how to use a given class or method, the intent of a variable, etc.

Every doxygen comment is essentially broken into a three parts:

1. the doxygen trigger comment – an augmented comment so that doxygen knows that it needs to parse the contents for markup (we use /** and ///< ); NOTE: the brief must be terminated with a period (.)
2. the brief comment – the title for the comment; this one is used in lists — for example, the brief class comment appears in th elist of classes alongside the class name
3. the full comment – this is where you put your full description and can include doxygen tags as well as any HTML tags

The typical doxygen comment – in JAVADOC style – looks like this:

/**
 * Brief Comment with a period to terminate.
 * Full comment:
 *  the full comment can continue on multiple lines
 * <em>use HTML tags</em>
 * @note And use doxygen tags
 *
 */

An important note worth reiterating – the brief comment can continue over multiple lines and must be terminated with the period ‘.’ or the brief comment won’t be so brief.

I recommend using the JAVADOC style of comment. In addition to doxygen a number of documentation tools also support this format. That, and it’s a good looking format for comments.

I recommend using HTML tags only when there isn’t a corresponding doxygen tag that accomplishes the same.

A starter guide from the doxygen folks is here:
http://www.doxygen.org/docblocks.html

And all of the available doxygen markup is found on the doyxgen site here:
http://www.doxygen.org/commands.html

But no need to look at that just yet – After the break I’ll give you some cut-n-paste code that should cover most of your needs for:

• file
• class
• function/task/module/interface/program/constraint/coveragegroup
• variable
• enum

I recommend to comment – at a minimum – all files, classes, public members of those classes (including variables, tasks, functions, constraints, and coveragegroups), and any frequently used define macros.
After the break I’ll provide examples.

The Examples
All of these examples are copied directly from the test.sv file that is used to test each release of the filter.

At the top of every file have a comment that looks like this:

/**
 * Test - brief comment.
 * This file is a test of the doxygen filter script.
 * This contains a semi-complete set of the SystemVerilog constructs
 * that the filter script can handle
 *
 *
 * @par Download the most recent version here:
 * http://intelligentdv.com/downloads/
 *
 * @par File Bugs Here:
 * http://bugs.intelligentdv.com/
 * Project:  DoxygenFilter
 *
 * @file test.sv
 * @author Author O'Author
 * @par Contact:
 * http://intelligentdv.com/contact/
 * @par Company:
 *
 *
 * @version
 * $LastChangedRevision$
 * @par Last Change Date:
 * $LastChangedDate$
 * @par Last Change By:
 * $LastChangedBy$
 *
 */

Note that I leave the copyright header as a separate header in a non doxygen block comment.  This keeps the documentation from getting clogged up with a redundant (and typically large) comment.

This generates documentation that looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/test_8sv.html#_details
And note that the file list has the brief comment that we used above:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/files.html

Above every class declaration have a comment that looks like this:

/**
 *  Test Class - Basic.
 *  Just a basic class declaration.
 *  "String in Quotes in a comment"
 *
 *  @class test_class_basic
 *
 */
class test_class_basic;
...

This generates documentation that looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#_details
And note that the class list has the brief comment that we defined above:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/annotated.html

Above every task / function should have a comment that looks like this:

   /**
    *  Pure Virtual Function.
    *  Test pure virtual specifier
    *
    *  @param A int - description of parameter A
    *  @param B int - description of parameter B
    *  @return int
    *
    */
   pure virtual function int mypurevirtualfunction(int A,
                                                   int B);

Note the use of the @param tag for method parameters and @return for the method’s return value.

The function’s documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#e51c4c3ae2938b96369ca9658f423b19

Note that the brief description defined in the comment is used in the class’ list of member functions here:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html
(scroll down a bit…)

A typedef enum should be commented like this:

   typedef enum  {A, ///< A State
                  B, ///< B State
                  C, ///< C State
                  D  ///< D State
                 } alpha_enum_t;  ///< Alpha State Enum Type

Note the use of the ‘to the right’ pointer inline comment. We comment both the type name and the enumerations.

The enum documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#a78fb021ca5776b90837c0efd1e1fde0

Similar to enums, class member variables should be commented like this:

local rand int     m_local_int;      ///< Private Int

And their documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html
(Scroll to the documented private member variables).

Both constraint and covergroup members should be commented like this:

   /**
    * Word Align Constraint.
    * Constrain m_public_bitvector to word align
    *
    */
   constraint word_align {
   ...

And the constraint’s documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/classtest__class__basic.html#dfaa7175af783be066a8d308b3b23fd7

Programs, modules, and interfaces are commented just like functions and tasks.

/**
 * BusB interface Block.
 * An interface with two lines of I/O
 *
 *  @param clk bit - description of parameter clk
 *  @param foo logic - description of parameter foo
 *
 */
interface bus_B (input bit clk,
                 output logic foo);
      logic [8:1] cmd;
     ...

And the interface documentation looks like this:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/group__SVinterface.html#g979a28dcc7a63b6015d4413c0c132c5e

And again, note how the brief tag is used in the list of interfaces:
http://intelligentdv.com/documents/doxygen/test_doc-2.4.0/group__SVinterface.html

There’s a bit more that you can accomplish using doxygin, but this should be enough to get you started.
You can find more examples in the aforementioned test.sv file here – the same test.sv that’s included in the Doxygen tools distribution here:
http://intelligentdv.com/downloads/index.html#doxygentools

Questions? Ask in the comments.

Issues? File a bug!

-/** Start Documenting. */

The biggest difference that I see (other than bugfixes) is the move to inline (in source) generated documentation using NaturalDocs. While I still prefer Doxygen, I’m a huge fan of comment generated documentation – it helps to ensure that the docs stay up-to-date with the code.

And look for a post from me soon(ish) comparing NaturalDocs to Doxygen to v2html for hardware verification documentation. They all have their merits.

And I still don’t get email notifications of new releases from the ovmworld site – which is why this post always lags the OVM release.

As usual – I have the updated OVM docs posted here:

http://www.intelligentdv.com/documents/index.html#ovmdox

If you find a bug in the doxygen, then please let me know.

Enjoy!