ruby-adept 0.0.1

data/lib/adept/low_level/library.rb

@@ -0,0 +1,173 @@
+require 'ffi'
+require 'adept/low_level'
+require 'adept/low_level/error_handler'
+
+module Adept
+  module LowLevel
+
+    #Maximum possible length of a library version string.
+    VersionMaxLength = 256
+
+    #
+    # "Base" module, which provides functionality for interfacing with 
+    # Digilent Adept low-level libraries.
+    #
+    module Library
+      include FFI::Library
+
+      #
+      # Attaches the appropriate dynamically-linked library to the calling module.
+      #
+      def wrap_adept_library(name)
+      
+        #Store the prefix for the library name, which
+        #
+        @prefix = name.capitalize
+        #Make the adept_library function local, so it can only be used in class defintions.
+        #private :wrap_adept_library
+
+        #And attach the relevant dynamic library (DLL / SO).
+        ffi_lib "lib#{name}"
+
+        #Attach the function which queries the device runtime's version.
+        attach_adept_function :GetVersion, [:pointer]
+
+      end
+
+      #
+      # Attaches an adept function, handling error checking automatically.
+      # 
+      def attach_adept_function(name, arguments) 
+
+        #Compute the name for the Digilent Adept library.
+        base_name =  @prefix + name.to_s
+
+        #Attach the library's version of the function...
+        base_function = attach_function base_name, arguments, :bool
+
+        #Make the base function protected, as not to clutter the (public) namespace.
+        private_class_method(base_name)
+
+        #And create our enhanced version of the function, 
+        #which automatically raises an exception if an error occurs.
+        define_singleton_method(name) do |*args|
+
+          #Call the base function, and throw an exception if the call fails.
+          unless base_function.call(*args)
+          
+            #Get the most recent error information as a raisable exception.
+            error = ErrorHandler.last_error
+
+            #Override the exception's backtrace so it doesn't include this anonymous singleton.
+            error.set_backtrace(caller(2))
+
+            #And raise the exception itself.
+            raise error
+
+          end
+
+        end
+      end
+
+      #Make the wrap_adept_library/attach_adept_function functions local, so they can only be used in class defintions.
+      private :wrap_adept_library
+      private :attach_adept_function
+
+      #
+      # Returns the version of the wrapped runtime, as a string.
+      #
+      def runtime_version
+        
+        #create a new buffer which will hold the runtime's version
+        version_buffer = FFI::MemoryPointer.new(VersionMaxLength) 
+
+        #get the system's version
+        GetVersion(version_buffer)
+
+        #and return the retrieved version
+        version_buffer.read_string
+
+      end
+
+
+      private
+
+      
+      #
+      # Creates a C-style byte buffer containing the given item using FFI.
+      #
+      # The buffer exists in managed memory (and thus will be garbage
+      # collected when appropriate), but is contiguous, and thus prime
+      # for passing to a C interop.
+      #
+      def to_buffer(item)
+
+        #Try to convert the item to an array, and then to a string,
+        #if it supports it. This allows us to easily get a byte string
+        #from most Ruby types.
+        #
+        #Strings _shouldn't_ support either of these methods, and thus will
+        #pass unaltered.
+        # 
+        item = item.to_a if item.respond_to?(:to_a)
+        item = item.pack("C*") if item.respond_to?(:pack)
+        
+        #Create a new buffer, and fill it with our byte string.
+        buffer = FFI::MemoryPointer.new(item.byte_size)
+        buffer.put_bytes(0, item)
+
+        #And return the filled buffer.
+        return buffer
+        
+      end
+
+
+      #
+      # Recieves a byte string via a C-style byte buffer.
+      #
+      # types: A list of types to be received, in the same format as accepted by
+      #   FFI::MemoryPointer. :int, 8, and :long are all acceptable types.
+      #
+      # Must be called with a block, which should fill the byte buffer. 
+      # Yields a c-style pointer to each of the created buffers, in the order
+      # they were specified as arguments.
+      #
+      def receive_out_arguments(*types)
+
+        #Create a pointer to each of the requested types.
+        pointers = types.map { |type| FFI::MemoryPointer.new(type) }
+
+        #Yield each of the pointers to the given block.
+        yield(*pointers)
+
+        #Read each of the byte-buffers given.  
+        results = types.zip(pointers).map do |type, pointer|
+
+          #If we've been passed a buffer type as a symbol, use the
+          #symbol name to figure out the appropriate reading method.
+          if type.kind_of?(Symbol)
+
+            #Compute the method name by adding "get_" to the device type,
+            #as the the FFI convention.
+            method_name = 'read_' + type.to_s
+
+            #And return the contents of the byte buffer.
+            next pointer.send(method_name)
+  
+          #Otherwise, return the data in raw binary.        
+          else  
+            next pointer.get_string(0, type)
+          end
+
+        end
+
+        #If we have a single-element array, return the element directly;
+        #otherwise, return the array. This format works well with multiple 
+        #assignment.
+        (results.count == 1) ? results.first : results
+
+      end
+
+    end
+  end
+end

data/lib/adept/low_level.rb

@@ -0,0 +1,4 @@
+require 'adept/low_level/device'
+require 'adept/low_level/device_manager'
+require 'adept/low_level/jtag'
+require 'adept/low_level/enhanced_parallel'

data/lib/adept/version.rb

@@ -0,0 +1,3 @@
+module Adept
+  VERSION = "0.0.1"
+end

data/lib/adept.rb

@@ -0,0 +1,11 @@
+require "adept/version"
+
+require 'adept/low_level'
+require 'adept/error'
+require 'adept/device'
+
+require 'adept/data_formats'
+require 'adept/connection_provider'
+require 'adept/jtag'
+
+require 'adept/boards'

data/spec/lib/adept/data_formats/bitstream_spec.rb

@@ -0,0 +1,95 @@
+
+require 'date'
+
+require 'adept/data_formats/bitstream'
+
+#
+# Tests for the Bitstream file reader.
+#
+describe Adept::DataFormats::Bitstream do
+
+  #A very simple string which should _technically_ be a valid implementation of the bitstream protocol.
+  ValidBitFile = "\x00\x09012345678\x00\x01a\x00\x22design_name.ncd;UserID=0x0123ABCD\x00b\x00\x0C3s250ecp132\x00c\x00\x0B2012/12/29\x00d\x00\x0922:41:50\x00e\x00\x00\x00\x100123456789ABCDEF\x00"
+  InvalidBitFile = "\x00\x09012345678\x00\x01b\x00\x0BDesignName\x00c\x00\x09PartName\x00d\x00\x05Date\x00e\x00\x05Time\x00f\x00\x00\x00\x10012345689ABCDEF\x00"
+
+  let(:bitstream_array) { "0123456789ABCDEF".bytes.collect { |b| Adept::DataFormats::Bitstream::send(:reverse_byte, b) } }
+
+  context "when provided with a valid bitstream" do
+    subject { Adept::DataFormats::Bitstream.from_string(ValidBitFile) }
+
+    it "should read the header from the start of the subject" do
+      subject.header.should == "012345678"
+    end
+
+    it "should read the design information from the second field in the file" do
+      subject.info.should == "design_name.ncd;UserID=0x0123ABCD"
+    end
+
+    it "should read the part number from the third field in the file" do
+      subject.part.should == "3s250ecp132"
+    end
+
+    it "should read the date from the fourth field of the file" do
+      subject.raw_date.should == "2012/12/29"
+    end
+
+    it "should read the time from the fifth field of the file" do 
+      subject.raw_time.should == "22:41:50"
+    end
+
+    it "should read the bitsream itself from the remainder of the file" do
+      subject.raw_bitstream.should == "0123456789ABCDEF".unpack("C*")
+    end
+
+    describe "#filename" do
+      it "should extract the filename from the design information" do
+        subject.filename.should == "design_name.ncd"
+      end
+    end
+
+    describe "#usercode" do 
+      it "should extract the usercode from the design information" do
+        subject.usercode.should == "0123ABCD"
+      end
+    end
+
+    describe "#time_created" do
+      it "should extract the time and date that the bitstream was created as a ruby DateTime" do
+        subject.time_created.should == DateTime.new(2012, 12, 29, 22, 41, 50)
+      end
+    end
+
+    describe "#to_a" do
+      it "should create a valid array equal to the bitstream's contents with each byte reversed." do
+        subject.to_a.should == bitstream_array
+      end
+    end
+
+    describe "#to_s" do
+      it "should return the binary data from the bitstream with the header removed" do
+        subject.to_s.should == bitstream_array.pack("C*")
+      end
+    end
+
+  end
+
+  context "when provided with an invalid bitstream" do
+    
+    it "should raise an exception" do
+      expect { Adept::DataFormats::Bitstream.from_string(InvalidBitFile) }.to raise_error(BinData::ValidityError)
+    end
+
+  end
+
+  describe "#reverse_byte" do
+    subject { Adept::DataFormats::Bitstream }
+
+    it "should correct reverse the bits in a single byte" do
+      subject.send(:reverse_byte, 0xF0).should == 0x0F
+      subject.send(:reverse_byte, 0xAA).should == 0x55
+      subject.send(:reverse_byte, 0xDE).should == 0x7B
+    end
+
+  end
+
+end

data/spec/lib/adept/data_formats/data_factories_spec.rb

@@ -0,0 +1,42 @@
+
+require 'adept'
+require 'adept/data_formats'
+
+#
+#Use FakeFS, so none of the calls below actually touch the filesystem.
+#
+require 'rspec/mocks'
+require 'rspec/expectations'
+require 'fakefs/spec_helpers'
+
+include Adept
+
+#
+# Tests for the DataFactories module.
+#
+describe Adept::DataFormats::DataFactories do
+  subject { Object.new.extend(Adept::DataFormats::DataFactories) }
+
+  describe "#from_file" do
+    include FakeFS::SpecHelpers
+
+    before :each do
+      File::open('test', 'w') { |x| x.write('ABCDE') }
+    end
+
+    context "when given a filename" do
+      it "should call from_string with the file's contents" do
+        subject.should_receive(:from_string).with('ABCDE')
+        subject.from_file('test')
+      end
+    end
+
+    context "when given a file object" do
+      it "should call from_string with the file's contents" do
+        subject.should_receive(:from_string).with('ABCDE')
+        File::open('test', 'r') { |file| subject.from_file(file) }
+      end
+    end
+
+  end
+end

data/spec/lib/adept/device_spec.rb

@@ -0,0 +1,88 @@
+#
+# These tests assume _one_ single connected Basys2 board!
+#
+
+require 'adept'
+
+#Pull the relevant modules into the main namespace, for convenience.
+include Adept
+
+# Specification for the Adept Device interface.
+# These tests assume _only_ one connected Basys2 board!
+#
+describe Device do
+
+  describe ".connected_devices" do
+
+    it "should be able to enumerate the connected devices", :online => true do
+
+      devices = Adept::Device.connected_devices
+
+      #We should detect only a single device; which should be our Basys2 board.
+      devices.count.should == 1
+      devices.first[:name].should == 'Basys2'
+      devices.first[:path].should include('usb')
+
+    end
+
+  end
+
+  describe ".open" do
+
+    it "should be able to connect to a board by path", :online => true do
+
+      #Get the path of a connected device.
+      path = Adept::Device.connected_devices.first[:path]
+
+      #And open the device.
+      device = Adept::Device.open(path)
+
+      #The connected handle should be non-zero.
+      device.handle.should_not == 0
+
+      #Close the device afterwards
+      device.close
+
+    end
+  end
+
+  describe ".by_name" do
+
+    it "should be able to connect to a device by name", :online => true do
+
+      #Try to connect to a Basys board...
+      device = Adept::Device.by_name('Basys2')
+
+      #Ensure we got a valid handle.
+      device.handle.should_not == 0
+
+      #Close the device afterwards
+      device.close
+
+    end
+
+  end
+
+  describe "post-connection tasks", :online => true do
+
+    before :each do
+      @device = Adept::Device.by_name('Basys2')
+    end
+
+    after :each do
+      @device.close
+    end
+
+
+    it "should be able to determine the supported connections for a Basys2 board" do
+
+      #We should support JTAG
+      @device.supported_connections.should include(JTAG::Connection)
+
+    end
+
+  end
+
+  #TODO: ensure that the device-list is free'd afterwards
+
+end