origen_arm_debug 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5dd246d4525d4ced61bb06b8bccca56084e3ed9
-  data.tar.gz: ef1eaa8501694c28aa03227326a2da6cf2e3c9b2
+  metadata.gz: e947a1abfa51a87475064a20b02b28a7e51dd720
+  data.tar.gz: 47840a0bc06b60f0dce4f030a6ae23c9d020e0ce
 SHA512:
-  metadata.gz: 3d194a9455d7c34f0dfa0bf366f1aaa31e094f0eb470d3c209557faa4651a7edd70d8e1293630984c4a7d9b6eb73588410c80a446bc9532dad04c272d30e54af
-  data.tar.gz: cec545de10b7f3bbe7f2c93b7f1c6053b074c583e3b42f24f8ca38c197decfd4e0b71e50fb407359ee6c317d267225138fedce4cb29f5eaaa550ee30cd158285
+  metadata.gz: d8679bb32de39d88f9fded1871c9bb47eec607dc8ab3c0f498a7f99d7d05d64719c831fc28df450806814fcc28277a8d3433cca5d931e8dbd50f42d8e1b8115f
+  data.tar.gz: cba98e60b245a3113719b7baec378482f5677307bb9a6e0685d1b9d1dccfc0c372d8cc9f1c41355e1db4c54ab40ae31af2c438d78315b95e936bb10fc782b9f4

data/config/commands.rb

@@ -30,6 +30,8 @@ when "examples"    # , "test"
   load "#{Origen.top}/lib/origen/commands/generate.rb"
   ARGV = %w(workout -t swd -e j750 -r approved)
   load "#{Origen.top}/lib/origen/commands/generate.rb"
+  ARGV = %w(workout -t config_test -e j750 -r approved/config_test)
+  load "#{Origen.top}/lib/origen/commands/generate.rb"
     
   if Origen.app.stats.changed_files == 0 &&
      Origen.app.stats.new_files == 0 &&

data/config/version.rb

@@ -1,7 +1,7 @@
 module OrigenARMDebug
   MAJOR = 1
-  MINOR = 0
-  BUGFIX = 2
+  MINOR = 1
+  BUGFIX = 0
   DEV = nil
 
   VERSION = [MAJOR, MINOR, BUGFIX].join(".") + (DEV ? ".pre#{DEV}" : '')

data/lib/origen_arm_debug/dap.rb

@@ -20,7 +20,8 @@ module OrigenARMDebug
       end
 
       if options[:jtag] || parent.respond_to?(:jtag)
-        dps << sub_block(:jtag_dp, class_name: 'JTAG_DP')
+        options[:class_name] = 'JTAG_DP'
+        dps << sub_block(:jtag_dp, options)
       end
 
       Array(options[:mem_aps]).each do |name, base_address|

data/lib/origen_arm_debug/jtag_dp.rb

@@ -2,8 +2,19 @@ module OrigenARMDebug
   class JTAG_DP
     include Origen::Model
 
+    attr_reader :dpacc_select, :apacc_select
+
     def initialize(options = {})
-      add_reg :ir, 0, size: 4
+      options = {
+        ir_size:       4,
+        idcode_select: 0b1110,
+        abort_select:  0b1000,
+        dpacc_select:  0b1010,
+        apacc_select:  0b1011
+      }.merge(options)
+      @dpacc_select = options[:dpacc_select]
+      @apacc_select = options[:apacc_select]
+      add_reg :ir, 0, size: options[:ir_size]
 
       # Virtual reg used to represent all of the various 35-bit scan chains
       reg :dr, 0, size: 35 do |reg|
@@ -12,7 +23,7 @@ module OrigenARMDebug
         reg.bit 0, :rnw
       end
 
-      reg :idcode, 0b1110, access: :ro do |reg|
+      reg :idcode, options[:idcode_select], access: :ro do |reg|
         reg.bit 31..28, :version
         reg.bit 27..12, :partno
         reg.bit 11..1, :designer
@@ -42,7 +53,7 @@ module OrigenARMDebug
 
       add_reg :rdbuff, 0xC, access: :ro, reset: 0
 
-      reg :abort, 0b1000, access: :wo do |reg|
+      reg :abort, options[:abort_select], access: :wo do |reg|
         reg.bit 0, :dapabort
       end
     end

data/lib/origen_arm_debug/jtag_dp_controller.rb

@@ -33,7 +33,7 @@ module OrigenARMDebug
               dr[0].write(0)
               dr[2..1].write(reg.offset >> 2)
               dr[34..3].copy_all(reg)
-              ir.write!(0b1010)
+              ir.write!(dpacc_select)
               dut.jtag.write_dr(dr)
 
             else
@@ -55,7 +55,7 @@ module OrigenARMDebug
         dr[0].write(0)
         dr[2..1].write(reg.offset >> 2)
         dr[34..3].copy_all(reg)
-        ir.write!(0b1011)
+        ir.write!(apacc_select)
         dut.jtag.write_dr(dr, options)
       end
     end
@@ -86,7 +86,7 @@ module OrigenARMDebug
               dr[0].write(1)
               dr[2..1].write(reg.offset >> 2)
               dr[34..3].write(0)
-              ir.write!(0b1010)
+              ir.write!(dpacc_select)
               dut.jtag.write_dr(dr)
 
               # Part 2 - Now read real data from RDBUFF (DP-Reg)
@@ -117,7 +117,7 @@ module OrigenARMDebug
         dr[0].write(1)
         dr[2..1].write(reg.offset >> 2)
         dr[34..3].write(0)
-        ir.write!(0b1011)
+        ir.write!(apacc_select)
         dut.jtag.write_dr(dr)
 
         # Calling AP should provide any delay parameter for wait states between AP read request
@@ -133,7 +133,7 @@ module OrigenARMDebug
         dr[2..1].write(rdbuff.offset >> 2)
         dr[34..3].copy_all(reg)
         options[:mask] = options[:mask] << 3 unless options[:mask].nil?
-        ir.write!(0b1010)
+        ir.write!(dpacc_select)
         dut.jtag.read_dr(dr, options)
       end
     end

data/lib/origen_arm_debug_dev/dut.rb

@@ -13,7 +13,7 @@ module OrigenARMDebugDev
     # @example
     #   $dut = OrigenARMDebugDev::DUT.new
     #
-    def initialize
+    def initialize(options = {})
       add_reg :test, 0
 
       reg :test2, 0 do |reg|

data/lib/origen_arm_debug_dev/dut_jtag.rb

@@ -5,7 +5,7 @@ module OrigenARMDebugDev
 
     # Adds jtag-required pins to the simple dut model
     # Returns nothing.
-    def initialize
+    def initialize(options = {})
       super
       add_pin :tclk
       add_pin :tdi
@@ -15,18 +15,19 @@ module OrigenARMDebugDev
       add_pin :swd_clk
       add_pin :swd_dio
 
+      options[:class_name] = 'OrigenARMDebug::DAP'
+      options[:mem_aps] = {
+        mem_ap: {
+          base_address:      0x00000000,
+          latency:           16,
+          apreg_access_wait: 8,
+          apmem_access_wait: 8,
+          csw_reset:         0x23000040
+        },
+        mdm_ap: 0x01000000
+      }
       # Specify (customize) ARM Debug implementation details
-      sub_block :arm_debug, class_name: 'OrigenARMDebug::DAP',
-                            mem_aps:    {
-                              mem_ap: {
-                                base_address:      0x00000000,
-                                latency:           16,
-                                apreg_access_wait: 8,
-                                apmem_access_wait: 8,
-                                csw_reset:         0x23000040
-                              },
-                              mdm_ap: 0x01000000
-                            }
+      sub_block :arm_debug, options
     end
   end
 end

data/templates/web/index.md.erb

@@ -28,11 +28,10 @@ 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
+The most common way to use the Arm Debugger plugin is through the Origen register API via
 <code>read_register</code> and <code>write_register</code> methods.
 
-You must also include a compatible physical driver depending on what debug
+You must 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)
@@ -41,9 +40,8 @@ interface your device has, one of the following can be used:
 ~~~ruby
 class DUT
   include Origen::TopLevel
-  include OrigenARMDebug
 
-  # Also include the required physical driver, JTAG in this example
+  # Include the required physical driver, JTAG in this example
   include OrigenJTAG
 
   def initialize
@@ -55,7 +53,11 @@ class DUT
     # Simple example using default wait-states and latency:
     #   mem_ap:  APSEL = 0x00 (base_address[31:24])
     #   mem2_ap: APSEL = 0x01 (base_address[31:24])
-    sub_block :arm_debug, class_name: 'OrigenARMDebug::DAP', mem_aps: { mem_ap: 0x00000000, mem2_ap: 0x01000000 }                           
+    mem_aps = {
+      mem_ap: { base_address: 0x00000000 }
+      mem2_ap: { base_address: 0x10000000 }
+    }
+    sub_block :arm_debug, class_name: 'OrigenARMDebug::DAP', mem_aps: mem_aps                           
   end
 
   # Hook the ARMDebug module into the register API, any register read
@@ -97,6 +99,41 @@ You can also adjust the intermediate wait-states and latency parameters:
 dut.arm_debug.ahb_ap.apmem_access_wait = 16
 dut.arm_debug.ahb_ap.apreg_access_wait = 12
 dut.arm_debug.ahb_ap.latency = 8
+
+# You can define these at instantiation as well
+mem_aps = {
+  mem_ap: { base_address: 0x00000000, latency: 8, apreg_access_wait: 12, apmem_access_wait: 16 }
+  mem2_ap: { base_address: 0x10000000, latency: 8, apreg_access_wait: 12, apmem_access_wait: 16 }
+}
+sub_block :arm_debug, class_name: 'OrigenARMDebug::DAP', mem_aps: mem_aps
+~~~
+
+When used with the JTAG physical driver the default IR size is 4 and the default register select values are:
+
+~~~
+idcode_select = 0b1110
+abort_select  = 0b1000
+dpacc_select  = 0b1010
+apacc_select  = 0b1011
+~~~
+
+You can set non-default values at instantiation like this:
+
+~~~ruby
+mem_aps = {
+  mem_ap: { base_address: 0x00000000 }
+  mem2_ap: { base_address: 0x10000000 }
+}
+instantiation_options[:class_name] = 'OrigenARMDebug::DAP'
+instantiation_options[:mem_aps] = mem_aps
+
+instantiation_options[:ir_size] = 8
+instantiation_options[:idcode_select] = 0xFE
+instantiation_options[:abort_select] = 0xF8
+instantiation_options[:dpacc_select] = 0xFA
+instantiation_options[:apacc_select] = 0xFB
+
+sub_block :arm_debug, instantiation_options
 ~~~
 
 ### Company Customization

data/templates/web/index.md.erb~

@@ -0,0 +1,238 @@
+% 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
+
+The most common way to use the Arm Debugger plugin is through the Origen register API via
+<code>read_register</code> and <code>write_register</code> methods.
+
+You must 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 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
+    
+    # Simple example using default wait-states and latency:
+    #   mem_ap:  APSEL = 0x00 (base_address[31:24])
+    #   mem2_ap: APSEL = 0x01 (base_address[31:24])
+    mem_aps = {
+      mem_ap: { base_address: 0x00000000 }
+      mem2_ap: { base_address: 0x10000000 }
+    }
+    sub_block :arm_debug, class_name: 'OrigenARMDebug::DAP', mem_aps: mem_aps                           
+  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 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)
+~~~
+
+You can also adjust the intermediate wait-states and latency parameters:
+
+* [AP.apreg_access_wait](http://origen-sdk.org/arm_debug/api/OrigenARMDebug/AP.html#apreg_access_wait-instance_method)
+* [MemAP.apmem_access_wait](http://origen-sdk.org/arm_debug/api/OrigenARMDebug/MemAP.html#apmem_access_wait-instance_method)
+* [MemAP.latency](http://origen-sdk.org/arm_debug/api/OrigenARMDebug/MemAP.html#latency-instance_method)
+
+~~~ruby
+# Assuming ahb_ap has been previously defined
+dut.arm_debug.ahb_ap.apmem_access_wait = 16
+dut.arm_debug.ahb_ap.apreg_access_wait = 12
+dut.arm_debug.ahb_ap.latency = 8
+
+# You can define these at instantiation as well
+mem_aps = {
+  mem_ap: { base_address: 0x00000000, latency: 8, apreg_access_wait: 12, apmem_access_wait: 16 }
+  mem2_ap: { base_address: 0x10000000, latency: 8, apreg_access_wait: 12, apmem_access_wait: 16 }
+}
+sub_block :arm_debug, class_name: 'OrigenARMDebug::DAP', mem_aps: mem_aps
+~~~
+
+When used with the JTAG physical driver these are the default IR size 4 and the default register select values are:
+
+~~~
+idcode_select = 0b1110
+abort_select  = 0b1000
+dpacc_select  = 0b1010
+apacc_select  = 0b1011
+~~~
+
+You can set non-default values at instantiation like this:
+
+~~~ruby
+mem_aps = {
+  mem_ap: { base_address: 0x00000000 }
+  mem2_ap: { base_address: 0x10000000 }
+}
+instantiation_options[:class_name] = 'OrigenARMDebug::DAP'
+instantiation_options[:mem_aps] = mem_aps
+
+instantiation_options[:ir_size] = 8
+instantiation_options[:idcode_select] = 0xFE
+instantiation_options[:abort_select] = 0xF8
+instantiation_options[:dpacc_select] = 0xFA
+instantiation_options[:apacc_select] = 0xFB
+
+sub_block :arm_debug, instantiation_options
+~~~
+
+### Company Customization
+
+It may be the case that your application needs additional, customized Access Ports (AP) which are allowed but
+not defined by the standard ARM Debug Interface.  The following example shows how you can use the generic AP
+class as a starting point and add extra registers as defined by your specific implementation.
+
+~~~ruby
+require 'origen_arm_debug'
+module ARMDebugCOMPANY
+  # New AP class inherited from generic AP class provided by origen_arm_debug
+  class CustomAP < OrigenARMDebug::AP
+    # Initialize AP parameters and registers
+    def initialize(options = {})
+      super
+
+      instantiate_registers(options)
+
+      # Standard AP-register latency for most devices.  Can be overriden by
+      #   top-level if necessary
+      @apreg_access_wait = 8
+    end
+
+    # Add example registers associated with CustomAP.
+    # 
+    # Custom registers can also be added by ARMDebug owner with add_reg or
+    #   overloading entire instantiate_registers methd
+    #
+    #   Ex:  arm_debug.company_ap.add_reg(:custom_reg_3, 0x08)
+    def instantiate_registers(options = {})
+      add_reg :custom_reg_1, 0x00
+      add_reg :custom_reg_2, 0x04
+    end
+  end
+end
+
+
+class DUT
+  include Origen::TopLevel
+  include ARMDebugCOMPANY
+
+  # 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
+    
+    # Some standard AP parameters values
+    std_memap_config = { latency: 16, apreg_access_wait: 8, apmem_access_wait: 8, csw_reset: 0x23000040 }  
+
+    # 2 MemAPs using standard parameters (above)
+    mem_aps = {
+      mem_ap_0: { base_address: 0x00000000 }.merge(std_memap_config),    # AP Select = 0x00
+      mem_ap_1: { base_address: 0x01000000 }.merge(std_memap_config),    # AP Select = 0x01
+    }
+
+    # Add Company-Customized AP class @ APSEL = 0x04
+    custom_ap = {
+      company_ap:  { class_name: 'ARMDebugCOMPANY::CustomAP', base_address: 0x04000000, apreg_access_wait: 8 }
+    }
+
+    sub_block :arm_debug, class_name: 'OrigenARMDebug::DAP',
+                          base_address: 0,
+                          mem_aps: mem_aps,
+                          aps: custom_ap
+  end
+end
+DUT.new.arm_debug.company_ap.custom_reg_1.write!(0x55AA)
+~~~
+
+### 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_arm_debug
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Ronnie Lajaunie
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-11-16 00:00:00.000000000 Z
+date: 2018-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
@@ -101,6 +101,7 @@ files:
 - lib/origen_arm_debug_dev/dut_swd.rb
 - pattern/workout.rb
 - templates/web/index.md.erb
+- templates/web/index.md.erb~
 - templates/web/layouts/_basic.html.erb
 - templates/web/partials/_navbar.html.erb
 - templates/web/release_notes.md.erb
@@ -130,3 +131,4 @@ specification_version: 4
 summary: Provides an Origen API to perform register read and write operations via
   the ARM_DEBUG protocol.
 test_files: []
+has_rdoc: