# 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.

Summary

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.
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.
Interop Library Setup | The OVM-VMM interop kit consists of a set of Adapters and supporting Examples.
Adapters | The adapters in this kit enable independently developed OVM and VMM components to communicate without modification.
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.
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.
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.
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.
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.
Common type parameters | Each adapter possesses a common set of type parameters that allow them to be used for any transaction type.
Examples | This section describes how to run the examples included in this kit.
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.
License | Copyright 2008-2009 Mentor Graphics Corporation All Rights Reserved Worldwide

### 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.

### 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.

### Adapters

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

### 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 for the adapter definition and API.

See avt_channel2tlm example and avt_channel2tlm seq_item example for typical usage.

### 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 for the adapter definition and API.

See avt_tlm2channel example and avt_tlm2channel seq_item example for typical usage.

### 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 for the adapter definition and API.

See avt_analysis_channel example for typical usage.

### 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 for the adapter definition and API.

See avt_notify2analysis example for typical usage.

### 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 for the adapter definition and API.

See avt_analysis2notify example for typical usage.

### 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.

### 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

### 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.

### 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.

The adapters in this kit enable independently developed OVM and VMM components to communicate without modification.
This section describes how to run the examples included in this kit.

> class avt_channel2tlm #(
> | type | VMM_REQ | = | int,
> |  | OVM_REQ | = | int,
> |  | VMM2OVM_REQ | = | int,
> |  | OVM_RSP | = | OVM_REQ,
> |  | VMM_RSP | = | VMM_REQ,
> |  | OVM2VMM_RSP | = | avt_converter #(OVM_RSP,VMM_RSP),
> |  | OVM_MATCH_REQ_RSP | = | avt_match_ovm_id
> ) extends ovm_component

Use this class to connect a VMM producer to an OVM consumer.

> class avt_tlm2channel #( | type | OVM_REQ | = | int,
> |  | VMM_REQ | = | int,
> |  | OVM2VMM_REQ | = | int,
> |  | VMM_RSP | = | VMM_REQ,
> |  | OVM_RSP | = | OVM_REQ,
> |  | VMM2OVM_RSP | = | avt_converter #(VMM_RSP,OVM_RSP) | ) extends ovm_component

Use this class to connect an OVM sequencer to a VMM driver via vmm_channel.

> class avt_analysis_channel #( | type | OVM | = | int,
> |  | VMM | = | int,
> |  | OVM2VMM | = | avt_converter #(OVM,VMM),
> |  | VMM2OVM | = | avt_converter #(VMM,OVM) | ) extends ovm_component

The avt_analysis_channel is used to connect any OVM component with an analysis port or export to any VMM component via a vmm_channel.

> class avt_notify2analysis #( | type | VMM | = | int,
> |  | OVM | = | int,
> |  | VMM2OVM | = | int | ) extends ovm_component

The avt_notify2analysis adapter receives VMM data supplied by a vmm_notify event notification, converts it to OVM, then broadcasts it to all components connected to its analysis_port

> class avt_analysis2notify #( | type | OVM | = | int,
> |  | VMM | = | int,
> |  | OVM2VMM | = | int | ) extends ovm_component

The avt_analysis2notify adapter receives OVM data from its analysis_export, converts it to VMM, then indicates the configured event notification, passing the converted data as vmm_data-based status.
This example uses an avt_channel2tlm to connect an VMM producer (generator) to an OVM consumer.
This example uses the avt_channel2tlm adapter to connect an VMM producer to an OVM sequence item driver.
This example uses an avt_notify2analysis and an avt_tlm2channel adapter to connect a vmm_notifier_consumer and an ovm_passive_producer.
This example uses the avt_tlm2channel adapter to connect an OVM sequencer to a VMM driver type.
This example shows how to use the vmm_analysis_adapter to connect VMM xactors to OVM components with analysis ports and exports.
This example shows how to use the avt_notify2analysis adapter to connect a VMM xactor that passes transactions via event notifications to an OVM analysis subscriber.
This example shows how to use the avt_analysis2notify adapter to connect an OVM publisher to a VMM xactor that receives data via vmm_notify event notifications.
The OVM-VMM interop kit consists of a set of Adapters and supporting Examples.