% render "layouts/basic.html" do

%# HTML tags can be embedded in mark down files if you want to do specific custom
%# formatting like this, but in most cases that is not required.
<h1><%= Origen.config.name %> <span style="font-size: 14px">(<%= Origen.app.version %>)</span></h1>

### Purpose

In an ideal world everyone would use Origen, but in reality there are many different
'standards' used to represent design data. This plugin
provides APIs and templates to import and export data to formats supported by 3rd
party tools.

### How To Import

In your Gemfile add:

~~~ruby
gem "<%= Origen.app.name %>", ">= <%= Origen.app.version %>"
~~~

or if your application is a plugin add this to your .gemspec

~~~ruby
spec.add_runtime_dependency "<%= Origen.app.name %>", ">= <%= Origen.app.version %>"
~~~

### How To Use

#### Supported Formats

Currently the following formats are supported:

* IP-XACT - Import and Export registers and hierarchy
* CMSIS-SVD - Import registers and hierarchy
* RALF (Synopsys format) - Export registers

See the [examples](<%= path "examples" %>) for format specific documentation, but
most formats should follow this basic structure...

#### Data Import  

When the <code>CrossOrigen</code> module is included in a class it gets access
to a <code>cr_import</code> method.
This will automatically detect the type of the given file and select the appropriate
import rules.

The file to be imported must exist locally or it can be pulled automatically from
a 3rd party repository in which case the file will be fetched the first time Origen
is invoked and then cached locally for future invocations.
Supported repositories are shown in the example below.

~~~ruby
class MyDevice

  include CrossOrigen

  def initialize
    # Import from a local file
    cr_import(path: "#{Origen.root}/imports/test-annex-Block-registers.xml")
    # Import from Design Sync
    cr_import(vault: "sync://sync-15040:15040/Projects/nvm_c90tfsn2w/ftf2/rtl_v/kx2_4m/.regs", version: "ftf2_kx2_4096k2_256_128k_64_4k.00.00.01.00") 
  end
end
~~~

The given file(s) will be parsed the first time the model is instantiated, which could take some time
depending on the amount of data being imported.

During the import process, the data from the files will be converted to Origen native format and stored
to the application's `vendor` directory. You should check these generated files into your revision control
system, although you should refrain from modifying them by hand since edits will be lost if the import
process is repeated in future.

On subsequent model instantiations, the `cr_import` method will recognize that the data has already been
imported and it will load directly from the `vendor` dir. Generally speaking, this will make the model
instantiation time instant, regardless of how much data was originally imported.

If you obtain a new version of the 3rd party source file, it can be re-imported by passing a
`refresh` option to `cr_import`:

~~~ruby
cr_import(path: "#{Origen.root}/imports/test-annex-Block-registers.xml", refresh: true)
~~~

Or, a global refresh (meaning every `cr_import` that is encountered with a given Origen command) can be
invoked by passing the `--refresh` option to any Origen command which will instantiate the model you
wish to refresh.

#### Data Export

The <code>CrossOrigen</code> module adds some methods to export the given object
as a string in the given format, for example a <code>to_ip_xact</code> method is available
to generate an IP-XACT XML representation of an object.

To create an actual XML file a simple template would be setup as shown below
and then compiled through Origen:

~~~eruby
<%= "<" + "%= $dut.to_ip_xact %" + ">" %>
~~~

In future support may be added to export directly to a 3rd party tool if
it provides such an API.

### How To Setup a Development Environment

[Clone the repository from Github](https://github.com/Origen-SDK/cross_origen).

Follow the instructions here if you want to make a 3rd party app
workspace use your development copy of the <%= Origen.app.config.initials %> plugin:
[Setting up a Plugin Development Environment](http://origen-sdk.org/origen/latest/guides/plugins)

This plugin also contains a test suite, make sure this passes before committing
any changes!

~~~text
origen test
~~~

% end