origen_jtag 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8857b553c5de44e4b7b8d5a36bb6dc071b8d6d3b85a7bbe270b87ead73e4c537
-  data.tar.gz: 2d09587fee678bc00d6ba8c75e38d42811a0753c1c2791dee457706c678b2f5b
+  metadata.gz: b15086a4ad3545ea9f62a1dfd03cbd478ba289d81cbe417ccbf6f66f0abb7741
+  data.tar.gz: d92e037cdc87ad03eb50cb0b480b1f2c0ea3ad658b2c5a8a607feace42f2f61a
 SHA512:
-  metadata.gz: 5410a3a6c9c4c250341a6840979908819ad5326baf8529fef0936d92029e4f910660ac9859b8dd010832013894ea8eeba830cbbb3cd0e8e7c9ec303fa91d572b
-  data.tar.gz: d54393fceeeb9dc965c513300c7042bd550d1c1b14962b1f523e768dafe5c0c05c6ee26dd0c98428db33e39b046af7d75af09dad7a9f1caddfbc70d52f1a4aa8
+  metadata.gz: 7cea430f01d68431304365ea7a47c08e76ecb12d4292828b01c9e4407570fba2ce5c4d344f6e58466258d24ae9d140441b4b3fa8e7e10db3a3436f1f19852273
+  data.tar.gz: fd389e11272f958e1c930ffd99a974fdad3f405ae5fb24fb8bd2da4a7d5d3f445917daca8e84e3af9f0e258cf84ec461873468faf57ff749269352071634af66

data/config/commands.rb

@@ -93,6 +93,9 @@ when "examples", "test"
   ARGV = %w(jtag_workout -t new_P4 -e v93k -r approved)
   load "#{Origen.top}/lib/origen/commands/generate.rb"
 
+  ARGV = %w(jtag_workout -t serial_P1 -e v93k -r approved)
+  load "#{Origen.top}/lib/origen/commands/generate.rb"
+
   if Origen.app.stats.changed_files == 0 &&
      Origen.app.stats.new_files == 0 &&
      Origen.app.stats.changed_patterns == 0 &&

data/config/version.rb

@@ -1,6 +1,6 @@
 module OrigenJTAG
   MAJOR = 0
-  MINOR = 20
+  MINOR = 21
   BUGFIX = 0
   DEV = nil
 

data/lib/origen_jtag/driver.rb

@@ -6,12 +6,12 @@ module OrigenJTAG
   # state machine via the TAPController module.
   #
   # To use this driver the parent model must define the following pins (an alias is fine):
-  #   :tclk
+  #   :tck
   #   :tdi
   #   :tdo
   #   :tms
   class Driver
-    REQUIRED_PINS = [:tclk, :tdi, :tdo, :tms]
+    REQUIRED_PINS = [:tck, :tdi, :tdo, :tms]
 
     include Origen::Model
     include TAPController
@@ -23,10 +23,20 @@ module OrigenJTAG
     # Returns the current value in the instruction register
     attr_reader :ir_value
 
-    # Returns the tclk multiple
-    attr_reader :tclk_multiple
+    # The number of cycles for one clock pulse, assumes 50% duty cycle. Uses tester non-return format to spread TCK across multiple cycles.
+    #    e.g. @tck_multiple = 2, @tck_format = :rh, means one cycle with Tck low (non-return), one with Tck high (NR)
+    #         @tck_multiple = 4, @tck_format = :rl, means 2 cycles with Tck high (NR), 2 with Tck low (NR)
+    attr_accessor :tck_multiple
+    alias_method :tclk_multiple, :tck_multiple
+    alias_method :tclk_multiple=, :tck_multiple=
+
+    # Wave/timing format of the JTAG clock:  :rh (ReturnHigh) or :rl (ReturnLo), :rh is the default
+    attr_accessor :tck_format
+    alias_method :tclk_format, :tck_format
+    alias_method :tclk_format=, :tck_format=
+
+    attr_reader :tdo_strobe
 
-    attr_accessor :tclk_format
     # Set true to print out debug comments about all state transitions
     attr_accessor :verbose
     alias_method :verbose?, :verbose
@@ -41,24 +51,17 @@ module OrigenJTAG
       else
         @owner = owner
       end
-      validate_pins(options)
-
       # The parent can configure JTAG settings by defining this constant
       if defined?(owner.class::JTAG_CONFIG)
         options = owner.class::JTAG_CONFIG.merge(options)
       end
 
+      @cycle_callback = options[:cycle_callback]
+      validate_pins(options) unless @cycle_callback
+
       # Fallback defaults
       options = {
         verbose:         false,
-        tclk_format:     :rh,                # format of JTAG clock used:  ReturnHigh (:rh), ReturnLo (:rl)
-        tclk_multiple:   1,                  # number of cycles for one clock pulse, assumes 50% duty cycle. Uses tester non-return format to spread TCK across multiple cycles.
-        #    e.g. @tclk_multiple = 2, @tclk_format = :rh, means one cycle with Tck low (non-return), one with Tck high (NR)
-        #         @tclk_multiple = 4, @tclk_format = :rl, means 2 cycles with Tck high (NR), 2 with Tck low (NR)
-        tdo_strobe:      :tclk_high,            # when using multiple cycles for TCK, when to strobe for TDO, options include:
-        #     :tclk_high   - strobe TDO only when TCK is high
-        #     :tclk_low    - strobe TDO only when TCK is low
-        #     :tclk_all    - strobe TDO throughout TCK cycle
         tdo_store_cycle: 0,                # store vector cycle within TCK (i.e. when to indicate to tester to store vector within TCK cycle.  0 is first vector, 1 is second, etc.)
         # NOTE: only when user indicates to store TDO, which will mean we don't care the 1 or 0 value on TDO (overriding effectively :tdo_strobe option above)
         init_state:      :unknown
@@ -68,18 +71,46 @@ module OrigenJTAG
 
       @verbose = options[:verbose]
       @ir_value = :unknown
-      @tclk_format = options[:tclk_format]
-      @tclk_multiple = options[:tclk_multiple]
-      @tdo_strobe = options[:tdo_strobe]
+      @tck_format = options[:tck_format] || options[:tclk_format] || :rh
+      @tck_multiple = options[:tck_multiple] || options[:tclk_multiple] || 1
+      self.tdo_strobe = options[:tdo_strobe] || :tck_high
       @tdo_store_cycle = options[:tdo_store_cycle]
       @state = options[:init_state]
       @log_state_changes = options[:log_state_changes] || false
-      if options[:tclk_vals]
-        @tclk_vals = options[:tclk_vals]
-        unless @tclk_vals.is_a?(Hash) && @tclk_vals.key?(:on) && @tclk_vals.key?(:off)
-          fail "When specifying TCLK values, you must supply a hash with both :on and :off keys, e.g. tclk_vals: { on: 'P', off: 0 }"
+      if options[:tck_vals] || options[:tclk_vals]
+        @tck_vals = options[:tck_vals] || options[:tclk_vals]
+        unless @tck_vals.is_a?(Hash) && @tck_vals.key?(:on) && @tck_vals.key?(:off)
+          fail "When specifying TCK values, you must supply a hash with both :on and :off keys, e.g. tck_vals: { on: 'P', off: 0 }"
         end
       end
+      if @cycle_callback && @tck_multiple != 1
+        fail 'A cycle_callback can only be used with a tck_multiple setting of 1'
+      end
+    end
+
+    # when using multiple cycles for TCK, set when to strobe for TDO, options include:
+    #     :tck_high   - strobe TDO only when TCK is high (Default)
+    #     :tck_low    - strobe TDO only when TCK is low
+    #     :tck_all    - strobe TDO throughout TCK cycle
+    def tdo_strobe=(val)
+      case val
+      when :tck_high, :tclk_high
+        @tdo_strobe = :tck_high
+      when :tck_low, :tclk_low
+        @tdo_strobe = :tck_low
+      when :tck_all, :tclk_all
+        @tdo_strobe = :tck_all
+      else
+        fail 'tdo_strobe must be set to one of: :tck_high, :tck_low or :tck_all'
+      end
+    end
+
+    # When true it means that the application is dealing with how to handle the 4 JTAG signals for each JTAG cycle.
+    # In that case this driver calculates what state the 4 pins should be in each signal and then calls back to the
+    # application with that information and it is up to the application to decide what to do with that information
+    # and when/if to generate tester cycles.
+    def cycle_callback?
+      !!@cycle_callback
     end
 
     # Shift data into the TDI pin or out of the TDO pin.
@@ -155,32 +186,32 @@ module OrigenJTAG
       # loop through each data bit
       last_overlay_label = ''
       size.times do |i|
-        store_tdo_this_tclk = false
+        store_tdo_this_tck = false
 
-        # Set up pin actions for bit transaction (tclk cycle)
+        # Set up pin actions for bit transaction (tck cycle)
 
         # TDI
-        @tdi_pin.drive(tdi_reg[i])
+        action :tdi, :drive, tdi_reg[i]
 
         # TDO
-        @tdo_pin.dont_care                               # default setting
+        action :tdo, :dont_care                                 # default setting
         if tdo_reg[i]
           if tdo_reg[i].is_to_be_stored?                        # store
-            store_tdo_this_tclk = true
-            @tdo_pin.dont_care if Origen.tester.j750?
+            store_tdo_this_tck = true
+            action :tdo, :dont_care if Origen.tester.j750?
           elsif tdo_reg[i].is_to_be_read?                       # compare/assert
-            @tdo_pin.assert(tdo_reg[i], meta: { position: i })
+            action :tdo, :assert, tdo_reg[i], meta: { position: i }
           end
         end
 
         # TMS
-        @tms_pin.drive(0)
+        action :tms, :drive, 0
 
         # let tester handle overlay if implemented
         overlay_options = {}
-        if tester.respond_to?(:source_memory)
+        if tester.respond_to?(:source_memory) && !cycle_callback?
           if ovl_reg[i] && ovl_reg[i].has_overlay? && !Origen.mode.simulation?
-            overlay_options[:pins] = @tdi_pin
+            overlay_options[:pins] = @pins[:tdi]
             if global_ovl
               overlay_options[:overlay_str] = global_ovl
             else
@@ -194,8 +225,8 @@ module OrigenJTAG
               end
             end
             tester_subr_overlay = !(options[:no_subr] || global_ovl) && tester.overlay_style == :subroutine
-            @tdi_pin.drive(0) if tester_subr_overlay
-            @tdo_pin.assert(tdo_reg[i], meta: { position: i }) if options[:read] unless tester_subr_overlay
+            action :tdi, :drive, 0 if tester_subr_overlay
+            action :tdo, :assert, tdo_reg[i], meta: { position: i } if options[:read] unless tester_subr_overlay
             # Force the last bit to be shifted from this method if overlay requested on the last bit
             options[:cycle_last] = true if i == size - 1
           end
@@ -208,18 +239,18 @@ module OrigenJTAG
                 $tester.label(ovl_reg[i].overlay_str)
                 last_overlay_label = ovl_reg[i].overlay_str
               end
-              @tdo_pin.assert(tdo_reg[i], meta: { position: i }) if options[:read]
+              action :tdo, :assert, tdo_reg[i], meta: { position: i } if options[:read]
             else
-              @tdi_pin.drive(0)
+              action :tdi, :drive, 0
               call_subroutine = ovl_reg[i].overlay_str
             end
           end
         end # of let tester handle overlay
 
-        # With JTAG pin actions queued up, use block call to tclk_cycle to
-        #   execute a single TCLK period.  Special handling of subroutines,
+        # With JTAG pin actions queued up, use block call to tck_cycle to
+        #   execute a single TCK period.  Special handling of subroutines,
         #   case of last bit in shift, and store vector (within a multi-cycle
-        #   tclk config).
+        #   tck config).
         if call_subroutine || tester_subr_overlay
           @last_data_vector_shifted = true
         else
@@ -234,25 +265,25 @@ module OrigenJTAG
           if i != size - 1 || options[:cycle_last]
             if i == size - 1 && options[:includes_last_bit]
               unless tester_subr_overlay
-                @tms_pin.drive(1)
+                action :tms, :drive, 1
                 @last_data_vector_shifted = true
               end
             end
-            tclk_cycle do
-              if store_tdo_this_tclk && @next_data_vector_to_be_stored
-                Origen.tester.store_next_cycle(@tdo_pin)
+            tck_cycle do
+              if store_tdo_this_tck && @next_data_vector_to_be_stored
+                action :store
               end
-              if overlay_options[:pins].nil?
-                Origen.tester.cycle
+              if overlay_options[:pins].nil? || cycle_callback?
+                cycle
               else
-                Origen.tester.cycle overlay: overlay_options
+                cycle overlay: overlay_options
                 overlay_options[:change_data] = false			# data change only on first cycle if overlay
               end
             end
-            @tdo_pin.dont_care
+            @pins[:tdo].dont_care unless cycle_callback?
           else
             @deferred_compare = true
-            @deferred_store = true if store_tdo_this_tclk
+            @deferred_store = true if store_tdo_this_tck
           end
         end
       end
@@ -264,101 +295,100 @@ module OrigenJTAG
       Origen.tester.dont_compress = false if compression_on
     end
 
-    # Cycles the tester through one TCLK cycle
-    # Adjusts for the TCLK format and cycle span
+    # Cycles the tester through one TCK cycle
+    # Adjusts for the TCK format and cycle span
     # Assumes caller will drive pattern to tester
     # via .drive or similar
-    def tclk_cycle
-      case @tclk_format
-        when :rh
-          tclk_val = 0
-        when :rl
-          tclk_val = 1
-        else
-          fail 'ERROR: Invalid Tclk timing format!'
-      end
-
-      # determine whether to mask TDO on first half cycle
-      mask_tdo_half0 =  ((@tclk_format == :rl) && (@tdo_strobe == :tclk_low) && (@tclk_multiple > 1)) ||
-                        ((@tclk_format == :rh) && (@tdo_strobe == :tclk_high) && (@tclk_multiple > 1))
+    def tck_cycle
+      if cycle_callback?
+        @next_data_vector_to_be_stored = @tdo_store_cycle
+        yield
+      else
+        case @tck_format
+          when :rh
+            tck_val = 0
+          when :rl
+            tck_val = 1
+          else
+            fail 'ERROR: Invalid Tclk timing format!'
+        end
 
-      # determine whether to mask TDO on second half cycle
-      mask_tdo_half1 =  ((@tclk_format == :rl) && (@tdo_strobe == :tclk_high) && (@tclk_multiple > 1)) ||
-                        ((@tclk_format == :rh) && (@tdo_strobe == :tclk_low) && (@tclk_multiple > 1))
+        # determine whether to mask TDO on first half cycle
+        mask_tdo_half0 =  ((@tck_format == :rl) && (@tdo_strobe == :tck_low) && (@tck_multiple > 1)) ||
+                          ((@tck_format == :rh) && (@tdo_strobe == :tck_high) && (@tck_multiple > 1))
 
-      # determine whether TDO is set to capture for this TCLK cycle
-      tdo_to_be_captured = @tdo_pin.to_be_captured?
+        # determine whether to mask TDO on second half cycle
+        mask_tdo_half1 =  ((@tck_format == :rl) && (@tdo_strobe == :tck_high) && (@tck_multiple > 1)) ||
+                          ((@tck_format == :rh) && (@tdo_strobe == :tck_low) && (@tck_multiple > 1))
 
-      # If TDO is already suspended (by an application) then don't do the
-      # suspends below since the resume will clear the application's suspend
-      tdo_already_suspended = @tdo_pin.suspended? && !@tdo_suspended_by_driver
+        # If TDO is already suspended (by an application) then don't do the
+        # suspends below since the resume will clear the application's suspend
+        tdo_already_suspended = !cycle_callback? && @pins[:tdo].suspended? && !@tdo_suspended_by_driver
 
-      @tclk_multiple.times do |i|
-        # 50% duty cycle if @tclk_multiple is even, otherwise slightly off
+        @tck_multiple.times do |i|
+          # 50% duty cycle if @tck_multiple is even, otherwise slightly off
 
-        @next_data_vector_to_be_stored = @tdo_store_cycle == i ? true : false
+          @next_data_vector_to_be_stored = @tdo_store_cycle == i ? true : false
 
-        if i < (@tclk_multiple + 1) / 2
-          # first half of cycle
-          @tck_pin.drive(@tclk_vals ? @tclk_vals[:on] : tclk_val)
-          unless tdo_already_suspended
-            unless tdo_to_be_captured
+          if i < (@tck_multiple + 1) / 2
+            # first half of cycle
+            @pins[:tck].drive(@tck_vals ? @tck_vals[:on] : tck_val)
+            unless tdo_already_suspended
               if mask_tdo_half0
                 @tdo_suspended_by_driver = true
-                @tdo_pin.suspend
+                @pins[:tdo].suspend
               else
                 @tdo_suspended_by_driver = false
-                @tdo_pin.resume
+                @pins[:tdo].resume
               end
             end
-          end
-        else
-          # second half of cycle
-          @tck_pin.drive(@tclk_vals ? @tclk_vals[:off] : (1 - tclk_val))
-          unless tdo_already_suspended
-            unless tdo_to_be_captured
+          else
+            # second half of cycle
+            @pins[:tck].drive(@tck_vals ? @tck_vals[:off] : (1 - tck_val))
+            unless tdo_already_suspended
               if mask_tdo_half1
                 @tdo_suspended_by_driver = true
-                @tdo_pin.suspend
+                @pins[:tdo].suspend
               else
                 @tdo_suspended_by_driver = false
-                @tdo_pin.resume
+                @pins[:tdo].resume
               end
             end
           end
+          yield
+        end
+        if @tdo_suspended_by_driver
+          @tdo_suspended_by_driver = false
+          @pins[:tdo].resume
         end
-        yield
-      end
-      if @tdo_suspended_by_driver
-        @tdo_pin.resume
-        @tdo_suspended_by_driver = false
       end
     end
 
     # Applies the given value to the TMS pin and then
-    # cycles the tester for one TCLK
+    # cycles the tester for one TCK
     #
     # @param [Integer] val Value to drive on the TMS pin, 0 or 1
     def tms!(val)
       if @deferred_compare
         @deferred_compare = nil
       else
-        @tdo_pin.dont_care
+        action :tdo, :dont_care
       end
 
       if @deferred_store
         @deferred_store = nil
-        store_tdo_this_tclk = true
+        store_tdo_this_tck = true
       else
-        store_tdo_this_tclk = false
+        store_tdo_this_tck = false
       end
       @next_data_vector_to_be_stored = false
 
-      tclk_cycle do
-        if store_tdo_this_tclk && @next_data_vector_to_be_stored
-          Origen.tester.store_next_cycle(@tdo_pin)
+      tck_cycle do
+        if store_tdo_this_tck && @next_data_vector_to_be_stored
+          action :store
         end
-        @tms_pin.drive!(val)
+        action :tms, :drive, val
+        cycle
       end
     end
 
@@ -493,8 +523,44 @@ module OrigenJTAG
       end
     end
 
+    def apply_action(pin, actions)
+      actions.each do |operation|
+        method = operation.shift
+        pin.send(method, *operation) if method
+      end
+    end
+
     private
 
+    def action(pin_id, *operations)
+      @actions ||= clear_actions
+      if pin_id == :store
+        @actions[:store] = true
+      else
+        fail "Unkown JTAG pin ID: #{pin_id}" unless @actions[pin_id]
+        @actions[pin_id] << operations
+      end
+    end
+
+    def cycle(options = {})
+      if @actions
+        if cycle_callback?
+          @owner.send(@cycle_callback, @actions, options)
+        else
+          apply_action(@pins[:tms], @actions[:tms])
+          apply_action(@pins[:tdi], @actions[:tdi])
+          apply_action(@pins[:tdo], @actions[:tdo])
+          tester.store_next_cycle(@pins[:tdo]) if @actions[:store]
+          tester.cycle(options)
+        end
+        clear_actions
+      end
+    end
+
+    def clear_actions
+      @actions = { tdi: [], tms: [], tdo: [], store: false }
+    end
+
     # Return size of transaction.  Options[:size] has priority and need not match the
     #   register size.  Any mismatch will be handled by the api.
     def extract_size(reg_or_val, options = {})
@@ -601,15 +667,19 @@ module OrigenJTAG
     # Validates that the parent object (the owner) has defined the necessary
     # pins to implement the JTAG
     def validate_pins(options)
-      @tck_pin = options[:tck_pin] if options[:tck_pin]
-      @tdi_pin = options[:tdi_pin] if options[:tdi_pin]
-      @tdo_pin = options[:tdo_pin] if options[:tdo_pin]
-      @tms_pin = options[:tms_pin] if options[:tms_pin]
-
-      @tck_pin = @owner.pin(:tclk) if @tck_pin.nil?
-      @tdi_pin = @owner.pin(:tdi) if @tdi_pin.nil?
-      @tdo_pin = @owner.pin(:tdo) if @tdo_pin.nil?
-      @tms_pin = @owner.pin(:tms) if @tms_pin.nil?
+      @pins = {}
+      @pins[:tck] = options[:tck_pin]
+      @pins[:tdi] = options[:tdi_pin]
+      @pins[:tdo] = options[:tdo_pin]
+      @pins[:tms] = options[:tms_pin]
+
+      # Support legacy implementation where tck was incorrectly called tclk, in case of both being
+      # defined then :tck has priority
+      @pins[:tck] ||= @owner.pin(:tck) if @owner.has_pin?(:tck)
+      @pins[:tck] ||= @owner.pin(:tclk)
+      @pins[:tdi] ||= @owner.pin(:tdi)
+      @pins[:tdo] ||= @owner.pin(:tdo)
+      @pins[:tms] ||= @owner.pin(:tms)
     rescue
       puts 'Missing JTAG pins!'
       puts "In order to use the JTAG driver your #{owner.class} class must either define"
@@ -617,7 +687,7 @@ module OrigenJTAG
       puts REQUIRED_PINS
       puts '-- or --'
       puts 'Pass the pins in the initialization options:'
-      puts "sub_block :jtag, class_name: 'OrigenJTAG::Driver', tck_pin: dut.pin(:tclk), tdi_pin: dut.pin(:tdi), tdo_pin: dut.pin(:tdo), tms_pin: dut.pin(:tms)"
+      puts "sub_block :jtag, class_name: 'OrigenJTAG::Driver', tck_pin: dut.pin(:tck), tdi_pin: dut.pin(:tdi), tdo_pin: dut.pin(:tdo), tms_pin: dut.pin(:tms)"
       raise 'JTAG driver error!'
     end
   end

data/lib/origen_jtag_dev/new_style.rb

@@ -24,6 +24,7 @@ module OrigenJTAGDev
       @jtag_config[:tdo_store_cycle] = options[:tdo_store_cycle] if options[:tdo_store_cycle]
       @jtag_config[:init_state] = options[:init_state] if options[:init_state]
       @jtag_config[:tclk_vals] = options[:tclk_vals] if options[:tclk_vals]
+      @jtag_config[:cycle_callback] = options[:cycle_callback] if options[:cycle_callback]
 
       instantiate_registers(options)
       instantiate_pins(options)
@@ -50,12 +51,10 @@ module OrigenJTAGDev
     end
 
     def instantiate_pins(options = {})
-      if options[:invalid_pins]
-        add_pin :tck
-      else
-        add_pin :tclk
+      add_pin :tclk
+      unless options[:invalid_pins]
+        add_pin :tdi
       end
-      add_pin :tdi
       add_pin :tdo
       add_pin :tms
 
@@ -101,7 +100,7 @@ module OrigenJTAGDev
       @jtag_config[:init_state]
     end
 
-    # Wouldn't want to do this in reality, but allows some flexibility duing gem testing
+    # Wouldn't want to do this in reality, but allows some flexibility during gem testing
     def update_jtag_config(cfg, val)
       if @jtag_config.key?(cfg)
         @jtag_config[cfg] = val

data/lib/origen_jtag_dev/serial.rb

@@ -0,0 +1,24 @@
+module OrigenJTAGDev
+  # This is a dummy DUT model which is used
+  # to instantiate and test the JTAG locally
+  # during development.
+  #
+  # It is not included when this library is imported.
+  class Serial < NewStyle
+    def instantiate_pins(options = {})
+      add_pin :tck
+      add_pin :tio
+    end
+
+    def jtag_cycle(actions, options = {})
+      pin(:tck).drive(1)
+      jtag.apply_action(pin(:tio), actions[:tdi])
+      tester.cycle(options)
+      jtag.apply_action(pin(:tio), actions[:tms])
+      tester.cycle(options)
+      jtag.apply_action(pin(:tio), actions[:tdo])
+      tester.store_next_cycle(pin(:tio)) if actions[:store]
+      tester.cycle(options)
+    end
+  end
+end

data/pattern/jtag_workout.rb

@@ -1,5 +1,6 @@
 pat_name = "jtag_workout_#{$dut.tclk_format.upcase}#{$dut.tclk_multiple}"
 pat_name = pat_name + "_#{dut.tdo_store_cycle}" if dut.tdo_store_cycle != 0
+pat_name += "_serial" if dut.is_a?(OrigenJTAGDev::Serial)
 pat_name += "_tclk_vals" if dut.try(:tclk_vals)
 
 Pattern.create(options = { name: pat_name }) do
@@ -196,15 +197,17 @@ Pattern.create(options = { name: pat_name }) do
   test 'Reset'
   jtag.reset
 
-  test 'Suspend of compare on TDO works'
-  cc 'TDO should be H'
-  jtag.read_dr 0xFFFF, size: 16, msg: 'Read value out of DR'
-  tester.ignore_fails($dut.pin(:tdo)) do
-    cc 'TDO should be X'
+  if dut.has_pin?(:tdo)
+    test 'Suspend of compare on TDO works'
+    cc 'TDO should be H'
+    jtag.read_dr 0xFFFF, size: 16, msg: 'Read value out of DR'
+    tester.ignore_fails($dut.pin(:tdo)) do
+      cc 'TDO should be X'
+      jtag.read_dr 0xFFFF, size: 16, msg: 'Read value out of DR'
+    end
+    cc 'TDO should be H'
     jtag.read_dr 0xFFFF, size: 16, msg: 'Read value out of DR'
   end
-  cc 'TDO should be H'
-  jtag.read_dr 0xFFFF, size: 16, msg: 'Read value out of DR'
 
   test 'Mask option for read_dr works'
   cc 'TDO should be H'

data/templates/web/index.md.erb

@@ -26,24 +26,42 @@ or if your application is a plugin add this to your <code>.gemspec</code>
 spec.add_development_dependency "origen_jtag", ">= <%= Origen.app.version %>"
 ~~~
 
-__NOTE:__ You will also need to include <code>require 'origen_jtag'</code> somewhere in your environment.  This can be done in <code>config/environment.rb</code> for example.
+__NOTE:__ You will also need to include <code>require 'origen_jtag'</code> somewhere in your environment.
+This can be done in <code>config/environment.rb</code> for example.
 
 ### How To Use
 
-#### New Style Example
+#### Integration
 
-The driver no longer requires specific pin names (or aliases), supports sub_block instantiation and DUTs with multiple JTAG ports.
- You are no longer required to include "OrigenJTAG" in your DUT class.
-
-Here is an example integration:
+This plugin provides a JTAG driver that should be instantiated by the top-level DUT model as shown in this
+basic integration example:
 
 ~~~ruby
-class Pioneer
+class MyApp::MyDUT
+  include Origen::TopLevel
+
+  def initialize(options = {})
+    # The JTAG driver will use these pins by default if they are defined (or aliases)
+    add_pin :tck
+    add_pin :tdi
+    add_pin :tdo
+    add_pin :tms
+
+    sub_block :jtag, class_name: 'OrigenJTAG::Driver'
+  end
+end
+~~~
+
+Multiple JTAG blocks can be instantiated if the DUT has multiple JTAG ports, and each one can be individually
+customized as shown in this more complex example:
 
+~~~ruby
+class MyApp::MyDUT
   include Origen::TopLevel
 
   def initialize
-    add_pin :tclk
+    # The JTAG driver will use these pins by default if they are defined (or aliases)
+    add_pin :tck
     add_pin :tdi
     add_pin :tdo
     add_pin :tms
@@ -58,92 +76,48 @@ class Pioneer
     # 2 high then 2 low for each effective TCK pulse.
     # Strobe TDO only when TCK high.  Only store TDO on last cycle (3)
 
-    # several pluggins use dut.jtag, your default port driver should be named jtag for compatibility
+    # Several plugins use dut.jtag, your default port driver should be named jtag for compatibility
     sub_block :jtag, class_name: 'OrigenJTAG::Driver',
-                     tclk_format:       :rl,
-                     tclk_multiple:     4,
-                     tdo_strobe:        :tclk_high,
-                     tdo_store_cycle:   3,
-                     tck_pin:           pin(:tclk),
-                     tdi_pin:           pin(:tdi),
-                     tdo_pin:           pin(:tdo),
-                     tms_pin:           pin(:tms)
-
-    # create a driver for a 2nd port like this
-    # note different configuration settings can be used
+                     tck_format:        :rl,
+                     tck_multiple:      4,
+                     tdo_strobe:        :tck_high,
+                     tdo_store_cycle:   3
+
+    # Create a driver for a 2nd port like this, note different configuration settings can be used
     sub_block :jtag_port2, class_name: 'OrigenJTAG::Driver',
-                     tclk_format:       :rh,
-                     tclk_multiple:     2,
-                     tdo_strobe:        :tclk_high,
+                     tck_format:        :rh,
+                     tck_multiple:      2,
+                     tdo_strobe:        :tck_high,
                      tdo_store_cycle:   1,
                      tck_pin:           pin(:tck2),
                      tdi_pin:           pin(:tdi2),
                      tdo_pin:           pin(:tdo2),
                      tms_pin:           pin(:tms2)
   end
-
 end
 
-dut.jtag                # => jtag driver for the first port (tclk, tdi, tdo, tms)
+dut.jtag                # => jtag driver for the first port (tck, tdi, tdo, tms)
 dut.jtag_port2          # => jtag driver for the second port (tck2, tdi2, tdo2, tms2)
 ~~~
 
+Here are some of the most common configuration options:
+
+* **tck_format** - TCK timing format,  Return High (:rh) or Return Low (:rl). Default is :rh.
+* **tck_multiple** - Number of cycles for a single TCK pulse to cover, to support cases where TCK needs to be a fraction of another clock period. Assumes 50% duty cycle, specify only even numbers if > 1. Default is :r1.
+* **tdo_strobe** - When using multiple cycles for TCK, which state of TCK to strobe for TDO, :tck_high or :tck_low or :tck_all. Default :tck_high.
+* **tdo_store_cycle** - When using multiple cycles for TCK, which cycle of TCK to store for TDO if store requested (0 to number of tck_multiple-1). Default 0
+
 By default, the driver will apply the conventional '1' and '0' drive values on the TCK pin to turn
 the clock on and off, however
-this can be overridden by supplying the `:tclk_vals` option as shown in the example below:
+this can be overridden by supplying the `:tck_vals` option as shown in the example below:
 
 ~~~ruby
 # My V93K timing setup uses 'P' to enable a clock pulse instead of '1'
-tclk_vals: { on: 'P', off: 0 }
+tck_vals: { on: 'P', off: 0 }
 ~~~
 
-
-#### Legacy Example
-
-Include the <code>OrigenJTAG</code> module to add a JTAG driver to your class and
-define the required pins.
-Normally the pins would be an alias to existing DUT pins and therefore the
-JTAG driver module cannot assume them.
-
-Including the module adds a <code>jtag</code> method which will return an instance of
-[<code>OrigenJTAG::Driver</code>](<%= path "api/OrigenJTAG/Driver.html" %>).
-
-The following attributes can be customized by defining a <code>JTAG_CONFIG</code>
-hash:
-
-* **tclk_format** - TCLK timing format,  Return High (:rh) or Return Low (:rl). Default is :rh.
-* **tclk_multiple** - Number of cycles for a single TCLK pulse to cover, to support cases where TCLK needs to be a fraction of another clock period. Assumes 50% duty cycle, specify only even numbers if > 1. Default is :r1.
-* **tdo_strobe** - When using multiple cycles for TCK, which state of TCK to strobe for TDO, :tclk_high or :tclk_low or :tclk_all. Default :tclk_high.
-* **tdo_store_cycle** - When using multiple cycles for TCK, which cycle of TCK to store for TDO if store requested (0 to number of tclk_multiple-1). Default 0
-
-Here is an example integration:
-
-~~~ruby
-class Pioneer
-
-  include OrigenJTAG
-  include Origen::Pins
-
-  # TCK covers 4 tester cycles, 2 high then 2 low for each effective TCK pulse
-  # Strobe TDO only when TCK high.  Only store TDO on last cycle (3)
-  JTAG_CONFIG = {
-    :tclk_format => :rl,
-    :tclk_multiple => 4,
-    :tdo_strobe => :tclk_high,
-    :tdo_store_cycle => 3,
-  }
-
-  def initialize
-    add_pin :tclk
-    add_pin :tdi
-    add_pin :tdo
-    add_pin :tms
-  end
-
-end
-
-Pioneer.new.jtag  # => An instance of OrigenJTAG::Driver
-~~~
+A [legacy integration is also supported](<%= path "legacy" %>), but not recommended for new projects
+as it may be deprecated in future.
 
 #### APIs
 
@@ -203,6 +177,57 @@ def on_jtag_state_change(new_state)
 end
 ~~~
 
+#### Custom JTAG Cycle Protocols
+
+This plugin also allows applications to define how a JTAG cycle should be implemented at the
+pin-level, providing the flexibility to handle hybrid JTAG protocols.
+An example would be an ultra-low pincount device where the JTAG signals are multiplexed down a
+single wire.
+
+To implement a custom protocol, a `:cycle_callback` option should be supplied when instantiating the
+driver to specify the name of the DUT method that will implement the cycle.
+**Note that most other configuration options are meaningless in this context (and some non-default
+values will raise an error) because the application
+is now taking full responsibility for how a JTAG cycle is implemented.**
+Similarly, there is no requirement for the conventional JTAG pins to be present or specified when this
+option is given since the driver is no longer responsible for the vector generation.
+
+The given method should accept two arguments:
+
+* **actions** - A hash containing the actions that should be applied to the `:tdi`, `:tms` and `:tdo`,
+  pins and a boolean flag called `:store` which indicates if TDO should be stored/captured on this cycle
+* **options** - Any options that should be passed to the tester when calling `tester.cycle`
+
+The JTAG driver provides a method called `apply_action` which accepts a pin object and the pin-specific
+actions from the actions hash, e.g.
+
+~~~ruby
+jtag.apply_action(pin(:my_pin), actions[:tms])
+~~~
+
+Here is a complete example which would serialize TDI, TMS and TDO on a single pin:
+
+~~~ruby
+class MyApp::MyDUT
+  def initialize(options = {})
+    add_pin :tck
+    add_pin :tio
+
+    sub_block :jtag, class_name: 'OrigenJTAG::Driver', cycle_callback: :jtag_cycle
+  end
+
+  def jtag_cycle(actions, options = {})
+    pin(:tck).drive(1)
+    jtag.apply_action(pin(:tio), actions[:tdi])
+    tester.cycle(options)
+    jtag.apply_action(pin(:tio), actions[:tms])
+    tester.cycle(options)
+    jtag.apply_action(pin(:tio), actions[:tdo])
+    tester.store_next_cycle(pin(:tio)) if actions[:store]
+    tester.cycle(options)
+  end
+end
+~~~
 
 ### How To Setup a Development Environment
 

data/templates/web/legacy.md.erb

@@ -0,0 +1,43 @@
+% render "layouts/basic.html" do
+
+### Legacy Integration
+
+The following approach to adding an JTAG driver is still supported, however new projects
+should use the new style integration as described [on the home page](<%= path "/" %>).
+
+Include the <code>OrigenJTAG</code> module to add a JTAG driver to your class and
+define the required pins.
+Normally the pins would be an alias to existing DUT pins and therefore the
+JTAG driver module cannot assume them.
+
+Including the module adds a <code>jtag</code> method which will return an instance of
+[<code>OrigenJTAG::Driver</code>](<%= path "api/OrigenJTAG/Driver.html" %>).
+
+Here is an example integration:
+
+~~~ruby
+class MyApp::MyDUT
+  include Origen::TopLevel
+  include OrigenJTAG
+
+  # TCK covers 4 tester cycles, 2 high then 2 low for each effective TCK pulse
+  # Strobe TDO only when TCK high.  Only store TDO on last cycle (3)
+  JTAG_CONFIG = {
+    :tck_format => :rl,
+    :tck_multiple => 4,
+    :tdo_strobe => :tck_high,
+    :tdo_store_cycle => 3,
+  }
+
+  def initialize
+    add_pin :tck
+    add_pin :tdi
+    add_pin :tdo
+    add_pin :tms
+  end
+end
+
+MyApp::MyDUT.new.jtag  # => An instance of OrigenJTAG::Driver
+~~~
+
+% end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: origen_jtag
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.0
 platform: ruby
 authors:
 - Stephen McGinty
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-07 00:00:00.000000000 Z
+date: 2019-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: origen
@@ -59,6 +59,7 @@ files:
 - lib/origen_jtag/driver.rb
 - lib/origen_jtag/tap_controller.rb
 - lib/origen_jtag_dev/new_style.rb
+- lib/origen_jtag_dev/serial.rb
 - lib/origen_jtag_dev/top_level.rb
 - pattern/full_reg_ovly_cap.rb
 - pattern/global_label_test.rb
@@ -67,6 +68,7 @@ files:
 - pattern/two_port.rb
 - templates/web/index.md.erb
 - templates/web/layouts/_basic.html.erb
+- templates/web/legacy.md.erb
 - templates/web/partials/_navbar.html.erb
 - templates/web/release_notes.md.erb
 homepage: http://origen-sdk.org/jtag