% 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

This plugin provides a common API for easily reading memory image files in any format
so that their contained data can then be used in Origen:

~~~ruby
# Read in an s-record
srec = OrigenMemoryImage.new("srecs/test_atd.abs.S19")

# Write it to the DUT, or otherwise work with it, however you like
srec.to_a.each do |addr, data|
  $dut.write_memory data, address: addr
end
~~~

### How To Import

##### To use in an application:

Add the following to your application's <code>Gemfile</code>:

~~~ruby
gem 'origen_memory_image', '<%= Origen.app.version %>'
~~~

##### To use in a plugin:

Add the following to your plugin's gemspec:

~~~ruby
spec.add_runtime_dependency 'origen_memory_image', '~> <%= Origen.app.version.major %>', '>= <%= Origen.app.version %>'
~~~

and require the gem in your code:

~~~ruby
require 'origen_memory_image'
~~~


### How To Use

Create a memory map object that points to a specific source file, note that
you do not need to supply the format.
Also note that the format is detected by looking at the file content and the naming
and extension of the file has no relevance (so it can be called anything).

The path to the file can be absolute or relative to <code>Origen.root</code>:

~~~ruby
my_srec = OrigenMemoryImage.new("source_files/test_atd.abs.S19")
my_hex  = OrigenMemoryImage.new("source_files/math.hex")
~~~

By default any partial data words are right justified. Change this behavior to left justified like this:

~~~ruby
my_srec = OrigenMemoryImage.new("source_files/test_atd.abs.S19", ljust_partial_data: true)
my_hex  = OrigenMemoryImage.new("source_files/math.hex", ljust_partial_data: true)
~~~

Partial data example:

~~~
0304FE

# Default interpretation into 32-bit word:
0x0003_04FE

# Left justified interpretation into 32-bit word:
0x0304_FE00
~~~

Memory images can also be created directly from a string:

~~~ruby
str = <<-END
@2D100E00
0D 15 0F 13 0E 14 10 12
00 00 04 17 04 03 05 06
END

my_hex = OrigenMemoryImage.new(str, source: String)
~~~

Every memory image object then supports a common API.

The <code>start_address</code> method returns the start (execution start) address:

~~~ruby
my_srec.start_address   # => 0x3000_F000
~~~

The <code>to_a</code> method returns the file content as an array of address/data pairs,
this method supports options to set the data width, flip the data endianness, and crop the data
between starting and ending address:

~~~ruby
my_srec.to_a                                      # => [[0x3000_F000, 0x11223344], [0x3000_F004, 0x55667788], [0x3000_F008, 0x99AABBCC], ...]

my_srec.to_a(flip_endianness: true)               # => [[0x3000_F000, 0x44332211], [0x3000_F004, 0x88776655], [0x3000_F008, 0x99AABBCC], ...]

my_srec.to_a(data_width_in_bytes: 2)              # => [[0x3000_F000, 0x1122], [0x3000_F002, 0x3344], [0x3000_F004, 0x5566], ...]

my_srec.to_a(crop: [0x3000_F004])                 # => [[0x3000_F004, 0x55667788], [0x3000_F008, 0x99AABBCC], ...]

my_srec.to_a(crop: [0x3000_F000, 0x3000_F004])    # => [[0x3000_F000, 0x11223344], [0x3000_F004, 0x55667788]]

~~~

Such an array can be iterated on like this to separate the address and data:

~~~ruby
my_srec.to_a.each do |address, data|
  # Process as required
end
~~~

### Currently Supported Formats

#### S-Records

Any valid S-record:

~~~text
S017000068656C6C6F5F776F726C645F6576622E73726563D6
S3153F00002018F09FE518F09FE518F09FE518F09FE55B
S3153F00003018F09FE500F020E314F09FE514F09FE5EC
S3113F000270F406003F102100407800003FDC
S3153F0005B05FF0FF301B4908605FF0FF301A49086063
S3093F0006F0704700000A
S7053F000410A7
~~~

#### Hex Files

The data lines can be grouped into any size:

~~~text
@18000000
1E E0 02 1C 22 40 1B E0 02 1C 22 43 18 E0 02 1C 
5A 78 0A 43 03 E0 03 4B F7 21 5A 78 0A 40 00 20 
22 E0 84 42 22 D3 1F E0 84 42 1F D9 1C E0 84 42 
@180000E0
002B20D1 03E0012A 01D1002B 1BD00223 
2340022A 02D1002B 15D103E0 032A01D1 
@180001F0
780000187C0000188200001888000018 
~~~

#### Binary Files

A binary file:

~~~text
00001101000101010000111100010011
00001110000101000001000000010010
00000000000000000000010000010111
00000100000000110000010100000110
~~~

#### Intel Hex

Any valid Intel Hex file:

~~~text
:020000040022D8
:10010000214601360121470136007EFE09D2190140
:100110002146017E17C20001FF5F16002148011928
:020000040023D7
:10012000194E79234623965778239EDA3F01B2CAA7
:100130003F0156702B5E712B722B732146013421C7
:0400000500000000F7
:00000001FF
~~~

### How To Setup a Development Environment

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

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, makes sure this passes before committing
any changes!

~~~text
origen specs
~~~

% end