
Section: OVM-VMM Interoperability Kit


This kit contains an OVM/VMM interoperability library that meets and exceeds
the requirements recently approved by the Accellera VIP-TSC.
It includes a growing collection of adapters and utilities that enable easy
and flexible reuse of existing IP in both OVM and VMM environments. Both
library's use models are fully preserved, and no modifications to existing
IP are needed.

All examples are fully documented with diagrams, explanations, and code
in hyperlinked HTML. Together they show you step-by-step how to integrate
existing IP in either an OVM or VMM-based environment.


--------------------------------------------------------------------------------

Group: Navigating the Documentation

--------------------------------------------------------------------------------

The documentation is densely hyperlinked throughout for convenient
navigation to related topics and more detailed descriptions of a
particular class method or variable.

Click a major heading on the navigation bar at left to expand or collapse the
list of items under that heading.  

Each page in a major topic or adaptor class is summarized in a box
like the one on this page. Each heading or method has a one-line summary 
description for easy reference. Clicking on the heading or method
name will take you to more detailed information.

Hovering above a linked class type
name or method produces a pop-up showing you the class or method
prototype and a one-sentence summary. Clicking on the link will
send you to its complete description. Clicking on the title bar
of any page will take you to the actual source file, if available.


--------------------------------------------------------------------------------

Group: Interop Library Setup

--------------------------------------------------------------------------------

The OVM-VMM interop kit consists of  a set of <Adapters> and supporting
<Examples>. The examples show how the adapters can be used to integrate
OVM and VMM IP in a mixed environment-- without modifying the existing IP.

Minimum requirements:

Setting up requires making sure you have installed and are pointing
to qualified versions of simulators, libraries, and utilities.

  OVM           - 2.0.2 or later
  VMM           - 1.1.1  (1.2 not tested)

  Mentor Questa - 6.4b or later
  Cadence IUS   - 8.2-p001 or later
  Synopsys VCS  - VCS0906-1 or later

  make          - GNU make v3.80 or later
  
The latest version of OVM can be downloaded from http://www.ovmworld.org.

The latest version of VMM that can be run on Questa and IUS can also
be downloaded from http://www.ovmworld.org.

The latest version of VMM that can be run on VCS can be downloaded from 
http://www.vmmcentral.org

Platform supports:

The following platforms are supported.

  linux     - Intel and AMD x86-based architectures;
              SUSE Linux Enterprise Server 9.0, 9.1, 10; 
              Red Hat Enterprise Linux 3, 4, 5; 32- and 64-bit;
  
  sunos5    - v8, 9, and 10, 32-bit only
  
  sunos5x86 - v10, 32- and 64-bit
   
  Windows   - (Questa only) XP and Vista, 32-bit only (tested on XP)
 

Environment variables:

The following environment variables must be set before running the
examples using the included Makefiles.

  OVM_HOME    - the OVM library install location

  VMM_HOME    - the VMM library install location

  VMM_DPI_DIR - the pre-compiled DPI library location, which is
                platform dependent. This path should start with 
                ~$VMM_HOME/shared~. The default value is set for
                64-bit Linux platforms.

Windows cygwin users must follow special requirements for setting
these environment variables. See instructions toward the bottom of this
README file.


Compilation:

This kit adds two new master include files in ~$INTEROP_HOME_HOME/src~.

  ovm_vmm_pkg.sv - Includes and imports both the OVM and VMM packages (with
                   +define+VMM_IN_PACKAGE) and defines OVM_INTEROP.
                   Most of the <Examples> in this kit use this as the
                   master include file.

  ovm_vmm.svh    - Includes OVM and VMM libraries in the current scope. No
                   packages are used. It is a common mistake to include
                   the libraries more than once in different scopes,
                   which lead to many problems that can be hard to
                   debug. For this reason it is recommended to always
                   use a package import-based appoach.
   
~If you do not use either of these master include files, you must set the
following define on your simulator's command line~

| +define+VMM_OVM_INTEROP

This enables minor yet essential modifications to the VMM standard library
that make the interoperability library work. Details on what changes were
made can be obtained by grepping for OVM_INTEROP on the files in VMM's
~std_lib~ directory.


--------------------------------------------------------------------------------

Group: Adapters

--------------------------------------------------------------------------------

The adapters in this kit enable independently developed OVM and VMM components
to communicate without modification.

Topic: avt_channel2tlm adapter
------------------------------

A <avt_channel2tlm> adapter is used to connect any VMM producer using
a ~vmm_channel~ to any OVM consumer using TLM ports or exports.

(see avt_channel2tlm.gif)

See <avt_channel2tlm> for the adapter definition and API.

See <avt_channel2tlm example> and <avt_channel2tlm seq_item example>
for typical usage.


Topic: avt_tlm2channel adapter
------------------------------

A <avt_tlm2channel> adapter is used to connect any OVM producer using
TLM ports or exports to any VMM consumer using a ~vmm_channel~.

(see avt_tlm2channel.gif)

See <avt_tlm2channel> for the adapter definition and API.

See <avt_tlm2channel example> and <avt_tlm2channel seq_item example>
for typical usage.


Topic: avt_analaysis_channel adapter
------------------------------------

A <avt_analysis_channel> isi used to connect an OVM component with an analysis 
port or export to any VMM component that uses a vmm_channel to communicate.

(see avt_analysis_channel.gif)

See <avt_analysis_channel> for the adapter definition and API.

See <avt_analysis_channel example> for typical usage.


Topic: avt_notify2analysis adapter
----------------------------------

A <avt_notify2analysis> is used to connect a VMM component supplying
transactions via vmm_nofity event notification to an OVM component with
an analysis export.

(see avt_notify2analysis.gif)

See <avt_notify2analysis> for the adapter definition and API.

See <avt_notify2analysis example> for typical usage.


Topic: avt_analysis2notify adapter
----------------------------------

An <avt_analysis2notify> is used to connect an OVM component
broadcasting transactions via an analysis port to any VMM component receiving
transaction via a vmm_nofity event notification.

(see avt_analysis2notify.gif)

See <avt_analysis2notify> for the adapter definition and API.

See <avt_analysis2notify example> for typical usage.



Topic: Common type parameters
-----------------------------

Each adapter possesses a common set of type parameters that allow them to
be used for any transaction type. 

OVM - The OVM transaction type.

VMM - The VMM transaction type.

OVM2VMM - The converter class to go from OVM to VMM. The converter class
must implement a single static method having the prototype,
~static function VMM convert(OVM in, VMM to=null)~. 
If the ~to~ argument is provided, the VMM transaction contents are
copied into the existing ~to~ OVM transaction. Otherwise, a new OVM
transaction is allocated, copied into, and returned.

VMM2OVM - The converter class to go from OVM to OVM. The converter class
must implement a single static method having the prototype,
~static function OVM convert(VMM in, OVM to=null)~.
If the ~to~ argument is provided, the OVM transaction contents are
copied into the existing ~to~ VMM transaction. Otherwise, a new VMM
transaction is allocated, copied into, and returned.

Bidirectional adapters, such as <avt_channel2tlm>, possess an additional
set of the above 4 parameters for the response types and converters.
Type-parameters representing the request transaction
type are prefixed with ~REQ_~, and those representing the optional
response transaction are prefixed with ~RSP_~.  This architecture allows
the response transaction type to differ from the request transaction type,
which can be common in split-transaction protocols.


--------------------------------------------------------------------------------

Group: Examples

--------------------------------------------------------------------------------

This section describes how to run the examples included in this kit.

The kit provides documented examples using each of the supplied
adapters. All examples can be found at ~$INTEROP_HOME/examples~.

  Adapters - Provides a usage example for each adapter in this kit.

  Integration - Demonstrates basic phasing synchronization between otherwise
  independent VMM and OVM components.  Shows OVM-on-top and VMM-on-top
  environments as well as examples that integrate foreign IP. Finally,
  demonstrates how progressive integrations of OVM and VMM IP can result
  in mixed, or sandwiched, OVM and VMM hierarchies. 

All examples can be found at ~.../ovm_vmm_interop/examples~.

Before attempting to run the examples, review <Interop Library Setup> to check
that your environment meets minimum requirements and that the appropriate
environment variables have been set.

VCS users should refer to .../ovm_vmm_interop/examples/README for special
instructions.


Running individual examples:

To run an individual example, ~cd~ into the examples directory
of your choice.

  | prompt> cd .../ovm_vmm_interop/examples/01_adapters 

Then run one of the following commands.

  | prompt> ./run_questa.sh 03_channel2tlm.sv    Questa
  | prompt> make -f Makefile.ius 03_channel2tlm  IUS

This runs just the example defined in ~03_channel2tlm.sv~.


Running all examples in a leaf-level directory:

To run all examples residing in a leaf-level directory, first ~cd~ to the
directory.

  | prompt> cd .../ovm_vmm_interop/examples/01_adapters

Then type one of the following commands, depending on your simulator.

  | prompt> ./run_questa.sh             Questa
  | prompt> make -f Makefile.ius        IUS
  | prompt> ./run_vcs.sh                VCS

To clean the examples directory of files from previous runs, type one
of the following commands.

  | prompt> ./run_questa.sh clean       Questa
  | prompt> make -f Makefile.ius clean  IUS
  | prompt> ./run_vcs.sh clean          VCS


Running all examples:

To run all the examples, ~cd~ to the top-level examples
directory and execute the appropriate command for your simulator

  | prompt> cd .../ovm_vmm_interop/examples

then

  | prompt> ./run_questa.sh
  | prompt> ./run_vcs.sh


To clean all examples of run-time files, type

  | prompt> ./run_questa.sh clean


--------------------------------------------------------------------------------

Group: Windows Users

--------------------------------------------------------------------------------

  Windows users running on cygwin must take care to specify paths in env
  variables to work around the different filepath formats used between
  Windows OS and cygwin.

  Setting OVM_HOME and VMM_HOME:

  These env variables must start with C: and use backslashes as the delimiter.

  | setenv OVM_HOME 'C:\cygwin\installs\ovm_2.0.1'
  | setenv VMM_HOME 'C:\cygwin\installs\vmm_1.1b'

  We enclose the path in tick quotes to prevent the cygwin shell from
  interpreting the backslashes.


  Setting PATH:

  You need to augment your PATH env variable so that Windows can
  find dependent DLLs when loading.

  | setenv PATH "$VMM_HOME\\shared\\bin\\win32:$PATH"

  The double quotes are used in case your existing PATH contains spaces.
  We must preceed each backslash in the path with the escape character,
  which also happens to be a backslash.


  Setting VMM_DPI_DIR:

  The VMM_DPI_DIR must be set in a particular way to work around the different
  filepath specs between cygwin and ~vsim~. With VMM_HOME set as above,
  the VMM_DPI_DIR should be set as follows

  | setenv VMM_DPI_DIR \\cygwin/installs/vmm_1.1b/shared/bin/win32
  
  Note that the path starts with a backslash and omits the drive letter.
  Thereafter, the path is a normal Unix path with forward-slash as the
  delimiter.



--------------------------------------------------------------------------------

Group: License

--------------------------------------------------------------------------------

   Copyright 2008-2009 Mentor Graphics Corporation
   All Rights Reserved Worldwide
   
   Licensed under the Apache License, Version 2.0 (the "License"); you may
   not use this file except in compliance with the License.  You may obtain
   a copy of the License at
   
          http://www.apache.org/licenses/LICENSE-2.0
   
   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
   License for the specific language governing permissions and limitations
   under the License.

