% 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 tester models to drive bench debuggers such as the Segger J-Link or PE Micro.

### How To Import

##### To use in an application:

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

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

##### To use in a plugin:

Add the following to your plugin's gemspec:

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

and require the gem in your code:

~~~ruby
require 'origen_debuggers'
~~~

### How To Use

For JTAG based protocols all that should be required is to change the application target
to instantiate one of the debuggers that support JTAG, such as J-Link or P&E:

~~~ruby
$tester = OrigenDebuggers::JLink.new
#  or
#$tester = OrigenDebuggers::PEmircro.new
~~~

Patterns should now generate a debugger command file without any additional application
modifications.

For non-JTAG-based protocols, all debuggers support a common API for the protocol to
interface with, for example:

~~~ruby
# Sleep for 40ms
$tester.wait(:time_in_ms => 40)

# Sleep for 20 cycles
$tester.wait(:cycles => 20)

$tester.write_byte(0x55, address: 0x12)

$tester.write_word(0xAA55, address: 0x34)

$tester.write_longword(0x1122_AA55, address: 0x5678)

$tester.read(10, address: 0x0001234, size: 8)
~~~

See the API for details on all available methods: [Common_API](<%= path "api/OrigenDebuggers/JLink/Common_API.html" %>)

Finally all debuggers support a direct write method that should be used as a last resort
to drive debugger-specific functionality that is not otherwise exposed via an official API:

~~~ruby
$tester.dw "hwinfo"
$tester.dw "mem 0x1234, 10"
~~~

### How To Setup a Development Environment

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

Some patterns can be found in the pattern directory to exercise the debuggers.

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!

~~~
origen examples
~~~

% end