ruby-adept 0.0.1

data/lib/adept/jtag/devices/fpga.rb

@@ -0,0 +1,162 @@
+#
+# FPGA JTAG Target
+#
+
+require 'adept/jtag'
+
+module Adept
+  module JTAG
+    module Devices
+
+      #
+      # Base module for JTAG devices.
+      #
+      class FPGA < Device
+       
+        #Basic device definitions.
+        InstructionWidth = 6
+        supports_idcode "X1c1a093", "X1c10093"
+
+        #Supported boundary-scan instructions.
+        Instructions = \
+        {
+          :extest      => 0b001111,
+          :sample      => 0b000001,
+          :preload     => 0b000001,  # Same as :sample
+          :user1       => 0b000010,  # Not available until after configuration
+          :user2       => 0b000011,  # Not available until after configuration
+          :cfg_out     => 0b000100,  # Not available during configuration with another mode.
+          :cfg_in      => 0b000101,  # Not available during configuration with another mode.
+          :intest      => 0b000111,                                                         
+          :usercode    => 0b001000,                                                         
+          :idcode      => 0b001001,                                                         
+          :highz       => 0b001010,                                                         
+          :jprogram    => 0b001011,  # Not available during configuration with another mode.
+          :jstart      => 0b001100,  # Not available during configuration with another mode.
+          :jshutdown   => 0b001101,  # Not available during configuration with another mode.
+          :bypass      => 0b111111,
+          :isc_enable  => 0b010000,
+          :isc_program => 0b010001,
+          :isc_noop    => 0b010101,
+          :isc_disable => 0b010110
+        }
+
+        #Database which maps IDCodes to bit-file part numbers.
+        #Used to validate 
+        PartIdcodes = \
+        {
+          '3s100ecp132' => 'X1c10093',
+          '3s250ecp132' => 'X1c1a093'
+        }
+
+        ConfigurationStartup = 14_000
+        FPGAStartup = 100
+
+        #
+        # Verifies the device's IDcode using the explicit IDCode instruction.
+        #
+        def verify_idcode
+
+          #Put the device into IDCode retrival mode.
+          self.instruction = :idcode
+
+          #And attempt to retrieve the 32-bit IDcode.
+          id_code = receive_data(32).reverse
+
+          #If the two IDcodes don't match, raise an error.
+          raise JTAG::Error, "IDCode verification failed! Expected: #{@idcode.unpack("H*")}, receieved #{id_code.unpack("H*")}. " unless id_code == @idcode
+
+        end
+
+        #
+        # Returns the "user code", an ID number which identifies the configuration of the FPGA.
+        #
+        def usercode
+          
+          #Put the device into IDCode retrival mode.
+          self.instruction = :usercode
+
+          #And attempt to retrieve the 32-bit IDcode.
+          usercode_packed = receive_data(32).reverse
+
+          #Return the usercode as a hex string.
+          usercode_packed.unpack("H*").first.upcase
+
+        end
+
+        #
+        # Configures (programs) the given FPGA.
+        #
+        def configure(bitstream)
+
+          validate_bitstream(bitstream)
+
+          #Send the bitstream to the FPGA.
+          initialize_configuration
+          transmit_data(bitstream.to_s)
+          finalize_configuration
+
+          #And verify that the programming succeeded. 
+          unless bitstream.usercode == usercode || bitstrea.usercode.nil?
+            raise ProgrammingError, "Programming failed; expected a usercode of #{bitstream.usercode}, recieved #{usercode}." 
+          end
+
+        end
+
+        def part_name
+          connected_part, _ = PartIdcodes.find { |part, mask| self.class.idcode_matches_mask(mask, @idcode) }
+          connected_part
+        end
+
+        #
+        # Returns true iff the provided bitstream is intended for this FPGA.
+        #
+        def supports_bitstream?(bitstream)
+          self.class.idcode_matches_mask(PartIdcodes[bitstream.part], @idcode)
+        end
+
+
+        private
+
+        #
+        # Check to ensure that the provided bit-stream is intended for this part.
+        #
+        def validate_bitstream(bitstream)
+          unless supports_bitstream?(bitstream)
+            raise ProgrammingError, "The provided bitstream was intended for an '#{bitstream.part}', but a '#{part_name}' is connected."
+          end
+        end
+
+        #
+        # Performs the initial steps which ready the FPGA for configuration.
+        #
+        def initialize_configuration
+
+          #Pulse the Program pin via JTAG.
+          self.instruction = :jprogram
+
+          #Put the device into configuration mode, and give it 14,000 cycles to start up.
+          self.instruction = :cfg_in
+          run_test(ConfigurationStartup)
+
+        end
+
+        #
+        # Performs the final steps which start up a configured program.
+        #
+        def finalize_configuration
+
+          #Put the FPGA into startup mode...
+          self.instruction = :jstart
+
+          #And then allow the FPGA to run normally.
+          run_test(FPGAStartup)
+
+        end
+
+
+
+      end
+    end
+  end
+end

data/lib/adept/jtag/devices/platform_flash.rb

@@ -0,0 +1,23 @@
+#
+# FPGA Configuration Platform Flash
+#
+
+require 'adept/jtag'
+
+module Adept
+  module JTAG
+    module Devices
+
+      #
+      # Base module for JTAG devices.
+      #
+      class PlatformFlash < Device
+
+        InstructionWidth = 8
+        supports_idcode "X5045093"
+
+      end
+
+    end
+  end
+end

data/lib/adept/jtag/devices.rb

@@ -0,0 +1,2 @@
+require 'require_all'
+require_rel 'devices'

data/lib/adept/jtag/error.rb

@@ -0,0 +1,8 @@
+require 'adept/error'
+
+module Adept
+  module JTAG
+    class Error < Adept::Error; end
+    class ProgrammingError < Error; end
+  end
+end

data/lib/adept/jtag/tap_state.rb

@@ -0,0 +1,67 @@
+
+module Adept
+  module JTAG
+    module TAPStates
+
+      #
+      # Base for all Test Access Port states.
+      #
+      module TAPState
+      
+        #
+        # Returns the successor to the current state, given an input value.
+        #
+        def next_state(value)
+
+          #Get the name of the module which describes the successor state...
+          state = self::NextState[value]
+
+          #... and get a reference to the module itself.
+          TAPStates.const_get(state)
+
+        end
+
+        #
+        # Determines the next value which should be present on the mode-set line
+        # to get to the given state.
+        #
+        def next_hop_towards(state)
+
+          #Get a refrence to the state module indicated by the TowardsZeroIfStateIs metaconstant.
+          towards_zero = TAPStates.const_get(self::NextState[0])
+          towards_one  = TAPStates.const_get(self::NextState[1])
+
+          #Determine if a next-hop of one would cause us to get stuck in a loop.
+          towards_one_would_cause_loop = (towards_one == self || self::NextState[1] == :Reset)
+
+          #If the next state would be achievable by providing a hop of zero, 
+          #or a hop of one would cause a loop, then the next hop should be zero.
+          #
+          #Otherwise, the next hop should be '1'.
+          ((state == towards_zero) || towards_one_would_cause_loop) ? [0, towards_zero] : [1, towards_one]
+        end
+
+      end
+
+      #
+      # Dynamically create a new TAPState module.
+      #
+      def self.tap_state(name, next_state)
+
+        #Create a new Module for the new TAP state...
+        mod = Module.new
+
+        #... and assign it the given name.
+        self.const_set(name, mod)
+
+        #Add the TAPState methods to the new module...
+        mod.extend(TAPState)
+
+        #And set the module's NextState constant, as given.
+        mod.const_set(:NextState, next_state)
+
+      end
+    
+    end
+  end
+end

data/lib/adept/jtag/tap_states.rb

@@ -0,0 +1,52 @@
+
+require 'adept/jtag/tap_state'
+
+module Adept
+  module JTAG
+    module TAPStates
+
+      #
+      # JTAG Test Access Port Finite State Machine
+      #
+      
+      tap_state :Reset,     0 => :Idle,       1 => :Reset
+      tap_state :Idle,      0 => :Idle,       1 => :SelectDR
+
+      #Data Register Access States
+      tap_state :SelectDR,  0 => :CaptureDR,  1 => :SelectIR
+      tap_state :CaptureDR, 0 => :ShiftDR,    1 => :Exit1DR
+      tap_state :ShiftDR,   0 => :ShiftDR,    1 => :Exit1DR
+      tap_state :Exit1DR,   0 => :PauseDR,    1 => :UpdateDR
+      tap_state :PauseDR,   0 => :PauseDR,    1 => :Exit2DR
+      tap_state :Exit2DR,   0 => :ShiftDR,    1 => :UpdateDR
+      tap_state :UpdateDR,  0 => :Idle,       1 => :SelectDR
+
+      #Instruction Register Access States
+      tap_state :SelectIR,  0 => :CaptureIR,  1 => :Reset
+      tap_state :CaptureIR, 0 => :ShiftIR,    1 => :Exit1IR
+      tap_state :ShiftIR,   0 => :ShiftIR,    1 => :Exit1IR
+      tap_state :Exit1IR,   0 => :PauseIR,    1 => :UpdateIR
+      tap_state :PauseIR,   0 => :PauseIR,    1 => :Exit2IR
+      tap_state :Exit2IR,   0 => :ShiftIR,    1 => :UpdateIR
+      tap_state :UpdateIR,  0 => :Idle,       1 => :SelectDR
+
+
+      #
+      # Override the FSM's base behavior in the SelectDR state, as that state
+      # is the "branch point" between the instruction register and the data-register columns.
+      #
+      module SelectDR
+
+        #
+        # Override the heuristic for path-finding within the TAP finite state machine;
+        # move to the appropriate column depending on if we're looking for an Data Register
+        # or Instruction Register access.
+        #
+        def self.next_hop_towards(state)
+          #If we're looking for an instruction state, continue to the next column.
+          (state.name =~ /IR$/) ? 1 : 0
+        end
+      end
+    end
+  end
+end

data/lib/adept/jtag.rb

@@ -0,0 +1,11 @@
+
+require 'adept/jtag/error'
+
+#Basic components.
+require 'adept/jtag/tap_states'
+require 'adept/jtag/connection'
+require 'adept/jtag/device'
+
+#Load each of the defined JTAG devices
+require 'adept/jtag/devices'
+

data/lib/adept/low_level/connection.rb

@@ -0,0 +1,59 @@
+
+require 'ffi'
+
+module Adept
+  module LowLevel
+
+    #
+    # Module mix-in which adds the basic functionality for 
+    #
+    module Connection
+
+      #
+      # Hook which runs whenever a module extends AdeptConnection.
+      #
+      def self.extended(base)
+
+        #Attach each of the relevant functions to the extending class.
+        base.module_eval do
+        
+          #Returns the amount of connections the given port provides.
+          attach_adept_function :GetPortCount, [:ulong, :pointer]
+
+          #Enable the JTAG port with the given number. Only one JTAG device can be active at a time!
+          attach_adept_function :EnableEx, [:ulong, :int32]
+
+          #Disable the currently active JTAG port.
+          attach_adept_function :Disable, [:ulong]
+
+        end
+      end
+
+      #
+      # Returns the number of JTAG ports the given device offers.
+      #
+      def port_count(device)
+
+        #Create a pointer to a new Int32 in memory...
+        count_pointer = FFI::MemoryPointer.new(:int32)
+
+        #... and fill it with the number of available JTAG ports.
+        GetPortCount(device, count_pointer)
+
+        #Return the acquired count as a ruby integer.
+        count_pointer.get_int32(0)
+
+      end
+
+      #
+      # Returns a true-like value if the given device supports JTAG,
+      # or nil if it does not.
+      #
+      def supported?(device)
+        port_count(device).nonzero?
+      end
+
+    end
+
+  end
+end

data/lib/adept/low_level/device.rb

@@ -0,0 +1,43 @@
+require 'ffi'
+require 'adept/low_level/device_manager'
+
+module Adept
+  module LowLevel
+
+    #Maximum length for an Adept device's name, including a null terminator.
+    NameMaxLength = 64
+
+    #Maximum length for an Adept device path, including a null terminator.
+    PathMaxLength = 260 + 1
+
+    #
+    # Structure used by the Adept SDK to represent an adept device.
+    #
+    class Device < FFI::Struct
+
+      #Set up the structure's layout.
+      layout  :name,        [:char, NameMaxLength], #char[NameMaxLength]
+              :path,        [:char, PathMaxLength], #char[PathMaxLength]
+              :transport,   :ulong
+
+      #
+      #Convert the given device record into a ruby hash.
+      #
+      def to_h
+        result = Hash[members.zip(values)]
+
+        #Convert the internal character arrays to ruby strings.
+        result[:name] = result[:name].to_s
+        result[:path] = result[:path].to_s
+
+        #And convert the device's transport to a string.
+        result[:transport] = DeviceManager::get_transport_name(result[:transport])
+
+        #return the resultant hash
+        result
+      end
+
+    end
+
+  end
+end

data/lib/adept/low_level/device_error.rb

@@ -0,0 +1,22 @@
+
+module Adept
+  module LowLevel
+
+    #
+    # Wrapper for Digilent Device Manager errors, which allows
+    # errors raised from the low-level SDK to be handled like ruby exceptions.
+    #
+    class DeviceError < StandardError
+
+      attr_accessor :short_name
+      attr_accessor :code
+
+      def initialize(message, short_name, code=nil)
+        @short_name = short_name
+        @code = code
+        super(message)
+      end
+
+    end
+  end
+end

data/lib/adept/low_level/device_manager.rb

@@ -0,0 +1,142 @@
+require 'ffi'
+require 'adept/low_level/device'
+require 'adept/low_level/library'
+
+module Adept
+  module LowLevel
+
+    #Stores the maximum length of a transport string, will terminating null.
+    TransportMaxLength = 16
+
+    #
+    # DeviceManager (DMGR)
+    # Wrapper for the low-level Adept device management functionality.
+    #
+    module DeviceManager
+      extend LowLevel::Library
+
+      #Wrap the device manager library, libDMGR
+      wrap_adept_library 'dmgr'
+
+
+      #
+      # Enumeration functions.
+      #
+
+      #Get the list of all detected Adept devices; should be followed by the accompanying FreeDvcEnum call.
+      attach_adept_function :EnumDevices, [:pointer]
+
+      #Free the internal list of connected devices.
+      attach_adept_function :FreeDvcEnum, []
+
+
+      #
+      # Populate the internal list of connected devices.
+      # Returns the total amount of devices enumerated.
+      #
+      def self.populate_device_list
+
+        #Create a pointer to a new C integer.
+        count_pointer = FFI::MemoryPointer.new(:int)
+        
+        #Enumerate all of the connected devices, and retrieve the amount of enumerated devices.
+        EnumDevices(count_pointer)
+
+        #Dereference the count pointer, extracting the number of devices present.
+        count_pointer.get_int(0)
+
+      end
+
+      #
+      # Free the internal list of connected devices.
+      #
+      def self.free_device_list
+        FreeDvcEnum()
+      end
+
+
+      #
+      # Device Information-Query Functions
+      #
+      
+      #Get all enumeration information regarding the current device.
+      attach_adept_function :GetDvc, [:int, :pointer]
+
+      #Get a string describing the transport 
+      attach_adept_function :GetDtpString, [:ulong, :pointer]
+
+      #
+      # Returns a single record from the internal device enumeration list.
+      # This record contains low-level information about how to connect to the device.
+      #
+      def self.get_device_info(device_number)
+
+        #Create a new, empty low-level device structure.
+        device = Device.new
+
+        #Get the device's information from the internal enumeration table.
+        GetDvc(device_number, device.pointer)
+
+        #And return the newly-fetched device object as a ruby hash.
+        device.to_h
+
+      end
+
+      #
+      # Returns the transport name for a given transport ID ("DTP").
+      #
+      def self.get_transport_name(transport_id)
+
+        #Create a string buffer for the transport's name...
+        string_pointer = FFI::MemoryPointer.new(TransportMaxLength) 
+
+        #... and fill it with the relevant transport's description.
+        GetDtpString(transport_id, string_pointer)
+
+        #Return the retrieved string.
+        string_pointer.read_string
+
+      end
+
+      #
+      # Device Open/Close Functions
+      #
+      
+      #Open the device at the specified path.
+      attach_adept_function :Open, [:pointer, :string]
+
+      #Close the device with the specified handle.
+      attach_adept_function :Close, [:ulong]
+
+      #
+      # Opens the device at the given path, and returns an interface handle.
+      #
+      def self.open_device(path)
+
+        #Create a pointer to a new C long.
+        handle_pointer = FFI::MemoryPointer.new(:ulong)
+
+        #Open the device at the given path, retrieving the newly-created device handle.
+        Open(handle_pointer, path)
+
+        #Dereference the handle pointer, retrieving the handle itself.
+        handle = handle_pointer.get_ulong(0)
+
+        #If we recieved a handle of zero (C's NULL), convert that to nil;
+        #otherwise, return the handle directly.
+        handle.zero?() ? nil : handle
+
+      end
+
+      #
+      # Closes the device which is referenced by the given interface handle.
+      #
+      def self.close_device(handle)
+        Close(handle)
+      end
+
+
+    end
+
+  end
+end