ruby-adept 0.0.1

data/firmware/epp_stream/tests/fifo_testbench.vhdl

@@ -0,0 +1,164 @@
+----------------------------------------------------------------------------------
+-- Simple Synchronous FIFO
+--
+-- Author: Kyle J. Temkin, <ktemkin@binghamton.edu>
+-- Copyright (c) Kyle J. Temkin,  2013 Binghamton University
+--
+-- This program is free software: you can redistribute it and/or modify
+-- it under the terms of the GNU General Public License as published by
+-- the Free Software Foundation, either version 3 of the License, or
+-- (at your option) any later version.
+--
+-- This program is distributed in the hope that it will be useful,
+-- but WITHOUT ANY WARRANTY; without even the implied warranty of
+-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+-- GNU General Public License for more details.
+--
+-- You should have received a copy of the GNU General Public License
+-- along with this program.  If not, see <http://www.gnu.org/licenses/>.-
+--
+----------------------------------------------------------------------------------
+
+library ieee;
+use ieee.std_logic_1164.all;
+use ieee.numeric_std.all;
+ 
+entity fifo_testbench is
+end fifo_testbench;
+ 
+architecture behavior of fifo_testbench is 
+
+  -- component declaration for the unit under test (uut)
+
+  component fifo
+  generic(
+    count_bits : integer;
+    element_width : integer
+  );
+  port(
+       clk : in  std_logic;
+       reset : in  std_logic;
+       data_in : in  std_logic_vector(7 downto 0);
+       data_out : out  std_logic_vector(7 downto 0);
+       count : out  std_logic_vector(4 downto 0);
+       enqueue : in  std_logic;
+       dequeue : in  std_logic;
+       empty : out  std_logic;
+       full : out  std_logic
+  );
+  end component;
+
+  --
+  -- Convenience function which waits until juster the rising edge.
+  -- 
+  procedure wait_until_after_rising_edge(signal clk : in std_logic) is
+  begin
+    wait until rising_edge(clk);
+    wait for 1 ps;
+  end procedure wait_until_after_rising_edge;
+
+  --inputs
+  signal clk : std_logic := '0';
+  signal reset : std_logic := '1';
+  signal data_in : std_logic_vector(7 downto 0) := (others => '0');
+  signal enqueue : std_logic := '0';
+  signal dequeue : std_logic := '0';
+
+  --outputs
+  signal data_out : std_logic_vector(7 downto 0);
+  signal count : std_logic_vector(4 downto 0);
+  signal empty : std_logic;
+  signal full : std_logic;
+
+  -- clock period definitions
+  constant clk_period : time := 10 ns;
+
+  constant delta_delay : time := 1 ps;
+
+begin
+
+  -- instantiate the unit under test (uut)
+  uut: fifo 
+  generic map(
+    count_bits => 5,
+    element_width => 8
+  )
+  port map (
+    clk => clk,
+    reset => reset,
+    data_in => data_in,
+    data_out => data_out,
+    count => count,
+    enqueue => enqueue,
+    dequeue => dequeue,
+    empty => empty,
+    full => full
+  );
+
+  --Generate the system clock.
+  clk <= not clk after clk_period / 2;
+
+  -- stimulus process
+  stim_proc: process
+  begin		
+
+    -- assert reset for 100ns;
+    wait for 100 ns;	
+    reset <= '0';
+
+    --Assert conditions after reset.
+    assert data_out = x"00" report "Data_out should be zero after clear.";
+    assert count = "00000" report "Count should be zero after clear.";
+    assert empty = '1' report "Empty should be one after clear.";
+   
+    --Add 31 elements to the FIFO.
+    enqueue <= '1';
+    dequeue <= '0';
+    for i in 1 to 31 loop
+
+      --Ensure that we're counting the values properly. 
+      assert count = std_logic_vector(to_unsigned(i - 1, 5)) report "Count should be equal to the amount of elements enqueued.";
+
+      --Set up the FIFO to add a new, numbered element.
+      data_in <= std_logic_vector(to_unsigned(i, 8));
+
+      --Wait until just after the next rising-edge of the clock.
+      wait_until_after_rising_edge(clk);
+    
+      --Check to see that our enqueue is behaving properly.
+      assert empty = '0' report "Empty should not be one while there are elements in the FIFO.";
+      assert data_out = x"01" report "Data out should show the first element enqueued until a dequeue is performed.";
+
+    end loop;
+
+    --Check to see that the FIFO is full.
+    assert full = '1' report "After adding 31 elements to the FIFO, it should be full.";
+
+    --Verify that we can perform simultaneous read/writes, even when the FIFO is full.
+    enqueue <= '1';
+    dequeue <= '1';
+    data_in <= x"20";
+    wait_until_after_rising_edge(clk);
+
+    --Check to ensure that the simultaneous enqueue/dequeue does not affect the count.
+    assert data_out = x"02" report "After a dequeue, the next value in the FIFO should be exposed.";
+    assert count = "11111" report "A simultaneous enqueue/dequeue should not affect the count.";
+
+    --Remove each of the elements from the FIFO.
+    enqueue <= '0';
+    dequeue <= '1';
+    for i in 2 to 32 loop 
+      assert data_out = std_logic_vector(to_unsigned(i, 8)) report "Elements should be dequeued in the same ordered they were entered.";
+      assert count = std_logic_vector(to_unsigned(33 - i, 5)) report "Count should decrease as elements are dequeued.";
+      wait_until_after_rising_edge(clk);
+    end loop;
+
+    --Check to ensure that the FIFO is empty after all elements have been dequeued.
+    assert count = "00000" report "After all elements are dequeued, the count should be zero.";
+    assert empty = '1' report "After all elements are dequeued, the queue should be empty.";
+
+  report "Test complete.";
+  wait;
+  end process;
+
+end;

data/lib/adept/boards/basys2.rb

@@ -0,0 +1,84 @@
+
+require 'adept'
+
+module Adept
+  module Boards
+
+    #
+    # Basys2 System Board
+    # 
+    class Basys2 < Adept::Device
+   
+      DEVICE_NAME = 'Basys2'
+
+      #
+      # Creates a new Basys2 board instance given the device's path.
+      # If no path is provided, the first connected Basys 2 board is used.
+      #
+      def initialize(path=nil)
+
+        #If no path was provided, use the path to the first device found.
+        path ||= Device.path_to(DEVICE_NAME) 
+
+        #Delegate the connection tasks to the base class.
+        super(path)
+
+      end
+
+      #
+      # Creates a new Basys2 board instance, using the same syntax as new,
+      # but accepts an optional block. If a block is given, the device will
+      # be automatically closed after the block is complete.
+      #
+      # Yields and returns the newly-created device.
+      #
+      def self.open(path=nil)
+
+        #Create a new Basys2 device.
+        device = new(path)
+
+        #If we were provided with a block, yield the device to it, 
+        #and then close the device afterwards
+        if block_given?
+          begin
+            yield device
+          ensure
+            device.close
+          end
+        end
+
+        #Return the newly created device.
+        device
+
+      end
+
+      #
+      # Configures the Basys2 board's on-board FPGA.
+      # Requires use of the board's JTAG port, and thus cannot be used when its JTAG
+      # port is open. (The JTAG device API provides an alternative method for device
+      # configuration.)
+      #
+      # bitstream: The bitstream to be programmed, as a Bitstream object or byte-string
+      #   (without headers).
+      #
+      def configure_fpga(bitstream)
+
+        begin
+
+          #Create a new JTAG connection to the board's FPGA.
+          jtag = JTAG::Connection.new(self)
+          fpga = jtag.connected_devices.first
+
+          #Configure the FPGA.
+          fpga.configure(bitstream)
+
+        ensure
+          jtag.close
+        end
+
+      end
+
+    end
+
+  end
+end

data/lib/adept/boards.rb

@@ -0,0 +1,2 @@
+
+require 'adept/boards/basys2'

data/lib/adept/connection_provider.rb

@@ -0,0 +1,30 @@
+
+module Adept
+
+  #
+  # Base for Adept connections.
+  # 
+  module ConnectionProvider
+
+    # An internal list of connection types which are provided by this library.
+    # Each time a new Conneciton type is loaded, it is added to this array.
+    @supported_connections = []
+
+    #
+    # Triggered each time a target class extends this basic connection.
+    # Stores a list of all classes that extend ConnectionBase.
+    #
+    def self.extended(connection)
+      @supported_connections << connection
+    end
+
+    #
+    # Returns the list of all supported connection providers.
+    #
+    def self.providers
+      @supported_connections
+    end
+
+  end
+
+end

data/lib/adept/data_formats/bitstream.rb

@@ -0,0 +1,116 @@
+
+require 'date'
+require 'bindata'
+
+require 'adept/data_formats/data_factories'
+
+module Adept
+  module DataFormats
+
+    #
+    # Class for the Xilinx bitstream file format.
+    #
+    # Format used was described at 
+    # <http://www.fpga-faq.com/FAQ_Pages/0026_Tell_me_about_bit_files.htm>
+    #
+    class Bitstream < BinData::Record
+      extend DataFactories
+
+      #Data is stored in the bitstream in big endian format.
+      endian :big
+ 
+      #Bit-file header.
+      uint16 :header_length
+      string :header,           :read_length => :header_length
+      skip   :length => 2
+
+      #Design information.
+      uint8  :a,                :check_value => 'a'.ord
+      uint16 :info_length
+      string :info,             :read_length => :info_length, :trim_padding => true
+
+      #Part information
+      uint8  :b,                :check_value => 'b'.ord
+      uint16 :part_length
+      string :part,             :read_length => :part_length, :trim_padding => true
+
+      #Date of creation.
+      uint8  :c,                :check_value => 'c'.ord
+      uint16 :date_length
+      string :raw_date,         :read_length => :date_length, :trim_padding => true
+
+      #Time of creation.
+      uint8  :d,                :check_value => 'd'.ord
+      uint16 :time_length
+      string :raw_time,         :read_length => :time_length, :trim_padding => true
+
+      #Raw binary configuration information
+      uint8  :e,                :check_value => 'e'.ord
+      uint32 :bitstream_length
+      array  :raw_bitstream,        :type => :uint8, :initial_length => :bitstream_length
+
+      UsercodeFormat= /UserID=0x([0-9A-Fa-f]+)/
+      
+      #
+      # Parses the given string as a Xilinx BitStream file.
+      #
+      def self.from_string(string)
+        read(string)
+      end
+
+      #
+      # Returns the routed logic ("ncd") filename from which this bitstream was created.
+      #
+      def filename
+        info.split(';').first
+      end
+
+      #
+      # Returns the usercode for the given design.
+      #
+      def usercode
+        UsercodeFormat.match(info)[1]
+      end
+
+      #
+      # Returns the time at which the bitfile was created.
+      #
+      def time_created
+        DateTime.parse("#{raw_date} #{raw_time}")
+      end
+
+      #
+      # Returns the length of the bitsream, in bits.
+      #
+      def bit_length
+        bitstream_length * 8
+      end
+
+      #
+      # Returns the bitstream as an arran array.
+      #
+      def to_a
+        raw_bitstream.to_a.map { |b| self.class.reverse_byte(b) }
+      end
+
+      #
+      # Returns the bitstream as a bit string.
+      #
+      def to_s
+        to_a.pack("C*")
+      end
+
+      private 
+
+      #
+      # Reverses the bit order of a given byte, using a fast algorithm from the
+      # following page: http://graphics.stanford.edu/~seander/bithacks.html
+      #
+      def self.reverse_byte(byte)
+         (((byte * 0x0802 & 0x22110) | (byte * 0x8020 & 0x88440)) * 0x10101 >> 16) % 0x100;
+      end
+
+    end
+
+  end
+end

data/lib/adept/data_formats/data_factories.rb

@@ -0,0 +1,33 @@
+
+module Adept
+  module DataFormats
+
+    #
+    # Mixin which supports creating instances of data-storage containers
+    # from files. Classes which extend this mix-in should have a "from_string" 
+    # class method.
+    #
+    module DataFactories
+
+        #
+        # Creates a new instance of the target class from a file or filename.
+        #
+        def from_file(file)
+
+          #If we have a file object, read it into memory.
+          if file.respond_to?(:read)
+            file = file.read
+          #Otherwise, assume we have a filename.
+          else
+            file = File::read(file)
+          end
+
+          #Create a new instance of the extending class from the given file.
+          from_string(file)
+
+        end
+
+    end
+
+  end
+end

data/lib/adept/data_formats.rb

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

data/lib/adept/device.rb

@@ -0,0 +1,127 @@
+
+require 'adept/low_level'
+
+require 'adept/connection_provider'
+require 'adept/jtag'
+
+module Adept
+
+  #
+  # Basic interface to a Digilent Adept device.
+  # 
+  class Device
+
+    #Get an easy reference to the adept Device Manager API.
+    DeviceManager = LowLevel::DeviceManager
+
+    #Allow Device connections to be created with an open function,
+    #like Ruby I/O objects.
+    class << self
+      alias :open :new
+    end
+
+    #Allow access to the device's handle, for now.
+    attr_reader :handle
+    
+    #
+    # Factory method which returns a connection to the device with the given name,
+    # or nil if no devices with that name could be found.
+    #
+    def self.by_name(name)
+
+      #Find path to the first device with the given name.
+      path = path_to(name)
+
+      #Return a new connection to the target device, or nil if no path was found.
+      path ? self.new(path) : nil
+
+    end
+
+    #
+    # Returns the path to first device with the given name, 
+    # or nil if no devices with that name could be found.
+    #
+    def self.path_to(name)
+
+      #Find the first device with the given name.
+      target_device = connected_devices.find { |device| device[:name] == name }
+
+      #Return the path to the target device.
+      target_device ? target_device[:path] : nil
+
+    end
+
+
+    #
+    #Creates a new connection to a Digilent adept device.
+    #
+    def initialize(path)
+
+      #Open the device, and store its handle.
+      @handle = DeviceManager::open_device(path) 
+
+      #If we didn't get a valid handle, raise the relevant exception.
+      if @handle.nil?
+        raise DeviceManager::last_error
+      end
+
+    end
+
+
+    #
+    # Closes the given device.
+    #
+    def close
+      ensure_handle_is_valid
+      DeviceManager::close_device(@handle)
+    end
+
+    #
+    # TODO: throw an exception of our handle is nil
+    #
+    def ensure_handle_is_valid
+
+    end
+
+    #
+    # Returns a list of connection methods supported by the current device.
+    #
+    def supported_connections
+      ConnectionProvider.providers.select { |connection| connection.supported_by?(@handle) }
+    end
+
+    #
+    # Returns an array of information regarding connected devices.
+    # Each array member is a hash, with three members:
+    #  -:name, the device's shortname
+    #  -:connection, the device's connection
+    #  -:transport, a code indicating the method by which we're connecting to the device
+    #
+    def self.connected_devices
+     
+      #Populate the internal device list, retrieving the amount of connected devices.
+      count = DeviceManager::populate_device_list
+
+      #Get the device information for each of the given devices.
+      devices = (0...count).map { |index| DeviceManager::get_device_info(index) }
+
+      #Free the internal device list.
+      DeviceManager::free_device_list
+
+      #and return the list of connected devices
+      devices
+
+    end
+
+    #
+    # Returns a new connection to the first connected device.
+    #
+    def self.open_first_connected_device
+      device = connected_devices.first
+      new(device[:path])
+    end
+
+  end
+
+end
+

data/lib/adept/error.rb

@@ -0,0 +1,4 @@
+module Adept
+  class Error < StandardError; end
+  class CommunicationError < Error; end
+end