% 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.app.namespace %> <span style="font-size: 14px">(<%= Origen.app.version %>)</span></h1>

### Purpose

This library provides register and memory read/write and debug control capability via the ARM Debug Interface v5 Spec. 

### How To Import

In your Gemfile add:

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

or if your application is a plugin add this to your <code>.gemspec</code>

~~~ruby
spec.add_development_dependency "origen_arm_debug", ">= <%= Origen.app.version %>"
~~~

__NOTE:__ You will also need to include <code>require 'origen_arm_debug'</code> somewhere in your environment
if your app is a plugin.


### How To Use

Include the <code>OrigenARMDebug</code> module in your DUT class, then hook it up
to the Origen register API via
<code>read_register</code> and <code>write_register</code> methods.

The <code>OrigenARMDebug</code> module also provides additional methods to use the ARM Debug protocol including:
accessing device memory, accessing core and floating point registers (cortex M cores only),
entering/exiting debug mode (cortex M cores only), setting the PC (cortex M cores only)
and stepping through code (cortex M cores only).

You must also include a compatible physical driver depending on what debug
interface your device has, one of the following can be used:

* [JTAG](http://origen-sdk.org/jtag)
* [Single Wire Debug](http://origen-sdk.org/swd)

~~~ruby
class DUT
  include Origen::TopLevel
  include OrigenARMDebug

  # Also include the required physical driver, JTAG in this example
  include OrigenJTAG

  def initialize
    reg :myreg, 0x0012, size: 16 do |reg|
      reg.bits 15..8, :upper_byte
      reg.bits 7..0,  :lower_byte
    end
    
    sub_block :arm_debug, class_name: "OrigenARMDebug::DAP", mem_aps: { mem_ap: 0x00000000, mem2_ap: 0x01000000 }                           
  end

  # Hook the ARMDebug module into the register API, any register read
  # requests will use the ARM Debug protocol by default
  def read_register(reg, options={})
    arm_debug.mem_ap.read_register(reg, options)
  end

  # As above for write requests
  def write_register(reg, options={})
    arm_debug.mem_ap.write_register(reg, options)
  end
end

DUT.new.myreg.write!(0x55AA)  # => Will generate the required vectors using the ARM debug protocol
~~~

You can also access the lower-level API using conventional Origen register transactions:

~~~ruby
arm_debug.sw_dp.idcode.read!(0x2BA01477)
arm_debug.sw_dp.ctrlstat.write!(0x5000_0000)  # Power-up
arm_debug.sw_dp.ctrlstat.read!(0xF0000000)    # Verify
arm_debug.ahb_ap.idr.read!(0x24770011)
arm_debug.sw_dp.select.write!(0)              # Select AHB-AP, bank 0       

# Set the SIZE field of CSW to 0x2 (32-bit transfers) + AddrInc=1
arm_debug.ahb_ap.csw.write!(0x23000052)
~~~

### How To Setup a Development Environment

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

An instance of the OrigenARMDebug driver is hooked up to a dummy DUT
object for use in the console:

~~~
origen i

> dut.arm_debug
=> #<OrigenARMDebug::Driver:0x0000001ee48e78>
~~~

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

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

~~~
origen examples
~~~

<%= disqus_comments %>

% end