xilinx-provision 1.0.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.project

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<projectDescription>
+	<name>xilinx-provision</name>
+	<comment></comment>
+	<projects>
+	</projects>
+	<buildSpec>
+		<buildCommand>
+			<name>com.aptana.ide.core.unifiedBuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+	</buildSpec>
+	<natures>
+		<nature>com.aptana.ruby.core.rubynature</nature>
+	</natures>
+</projectDescription>

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,16 @@
+source 'http://rubygems.org'
+# Add dependencies required to use your gem here.
+# Example:
+#   gem 'activesupport', '>= 2.3.5'
+
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem 'rdoc', '>= 3.6.1'
+  gem 'rspec', '~> 2.6.0'
+  gem 'bundler', '~> 1.0.14'
+  gem 'jeweler', '~> 1.6.1'
+  gem 'rcov', '>= 0', :platform => :mri
+
+  gem 'ether_ping', '~> 0.3.1'
+end

data/Gemfile.lock

@@ -0,0 +1,36 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    ether_ping (0.3.1)
+      ethernet (>= 0.1.0)
+    ethernet (0.1.3)
+      ffi (>= 1.0.0)
+    ffi (1.0.9)
+    git (1.2.5)
+    jeweler (1.6.2)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.9.1)
+    rcov (0.9.9)
+    rdoc (3.6.1)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.3)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.0.14)
+  ether_ping (~> 0.3.1)
+  jeweler (~> 1.6.1)
+  rcov
+  rdoc (>= 3.6.1)
+  rspec (~> 2.6.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Massachusetts Institute of Technology
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,57 @@
+= xilinx-provision
+
+Automates the tasks involved in uploading a bitfile to a Xilinx FPGA board.
+
+== Disclaimer
+
+The authors are not affiliated in any way with Xilinx, Inc. We are sharing this code so that other researches won't have to duplicate the effort.
+
+== Features
+
+The gem automates the following tasks:
+* builds a recent version of the USB cable driver
+* writes udev rules for the USB cable driver
+* writes udev rules for uploading firmware to the cable
+* uploads a bitfile to a FPGA
+
+== Usage
+
+After installing the ruby gem, perform a one-time setup to get the USB cable set up.
+
+    sudo xilinx-provision-setup
+    
+Then upload a bitfile to your FPGA using
+
+    xilinx-provision path/to/bitfile
+    
+Notice that the setup command requires root access, but normal operation does not.
+
+To program FPGAs automatically, use the following Ruby code.
+
+    require 'xilinx/provision'
+    Xilinx::Provision.fpga 'path/to/bitfile'
+
+For advanced usage, see the examples in the bin/ and spec/ directories.
+
+== Dependencies
+
+Right now, the gem works in Debian-based Linux distributions. It should be easy to extend it to other Linux distributions.
+
+I have no interest in making the gem work on Windows, but I would welcome patches that do so.
+
+The gem assumes Xilinx ISE is installed. Any edition will work, including the WebPACK free edition. Download the software from:
+http://www.xilinx.com/support/download/index.htm
+
+== Contributing to xilinx-provision
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2011 Massachusetts Institute of Technology. See LICENSE.txt for further details.

data/Rakefile

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "xilinx-provision"
+  gem.homepage = "http://github.com/csail/xilinx-provision"
+  gem.license = "MIT"
+  gem.summary = %Q{Deploys bitfiles to Xilinx FPGAs}
+  gem.description = %Q{Wraps the impact CLI tool in the Xilinx ISE}
+  gem.email = "victor@costan.us"
+  gem.authors = ["Victor Costan"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "xilinx-provision #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.0

data/bin/xilinx-provision

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'xilinx/provision'
+
+if ARGV.length != 1
+  puts "Usage: #{$0} path_to_bitfile"
+  exit 1
+end
+
+Xilinx::Provision.fpga ARGV[0]

data/bin/xilinx-provision-setup

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+require 'rubygems'
+require 'xilinx/provision'
+
+if output = Xilinx::Provision::CableDriver.setup ||
+            Xilinx::Provision::CableFirmware.setup
+  print output
+  exit 1
+else
+  exit 0
+end

data/lib/xilinx/provision.rb

@@ -0,0 +1,25 @@
+# :nodoc: namespace
+module Xilinx
+
+# Documentation here.
+module Provision
+  # Programs an FPGA chip on a JTAG chain.
+  #
+  # The options argument accepts the following keys:
+  #   :cable_port:: set to :auto by default
+  #
+  # Raises an exception if programming fails, returns true otherwise.
+  def self.fpga(bitfile, options = {})
+    if output = Xilinx::Provision::Impact.program_fpga(bitfile, options)
+      raise "Failed to program device!\nCommand output:\n#{output}"
+    end
+    true
+  end
+end  # namespace Xilinx::Provision
+
+end # namespace Xilinx
+
+require 'xilinx/provision/cable_driver.rb'
+require 'xilinx/provision/cable_firmware.rb'
+require 'xilinx/provision/impact.rb'
+require 'xilinx/provision/udev.rb'

data/lib/xilinx/provision/cable_driver.rb

@@ -0,0 +1,95 @@
+require 'English'
+require 'fileutils'
+require 'tmpdir'
+
+# :nodoc namespace
+module Xilinx
+
+# :nodoc namespace
+module Provision
+
+# Drives the setup of the USB cable driver needed to talk to Xilinx boards.
+module CableDriver
+  # Performs all the setup needed for the USB cable driver.
+  #
+  # Returns a false value in case of success, or a string with error information
+  # if something goes wrong.
+  def self.setup
+    if output = build_prerequisites
+      return "Error while obtaining driver prerequisites:\n#{output}"
+    elsif output = build(path)
+      return "Error while building driver:\n#{output}"
+    elsif output = configure_udev
+      return "Error while configuring cable driver udev rules\n#{output}"
+    elsif output = Xilinx::Provision::Udev.reload_rules
+      return "Error while loading cable driver udev rules\n#{output}"
+    end
+    nil
+  end
+  
+  # Installs the packages needed to build the cable driver.
+  #
+  # Returns a false value for success, and a string containing error output if
+  # the build goes wrong.
+  def self.build_prerequisites
+    if File.exist?(`which apt-get`.strip)
+      # The literal `apt-get ...` doesn't use Kernel.` and can't be stubbed.
+      output = Kernel.`(
+          'apt-get install -y git-core libusb-dev build-essential fxload 2>&1')
+      $CHILD_STATUS.to_i == 0 ? nil : output
+    else
+      "Unsupported OS / distribution\n"
+    end
+  end
+  
+  # Builds the cable driver.
+  #
+  # Assumes the build requirements have been installed by build_prerequisites.
+  #
+  # Args:
+  #   target_path:: directory that will contain the driver
+  #
+  # Returns the command's output.
+  def self.build(target_path)
+    target_path = File.expand_path target_path
+    Dir.mktmpdir do |temp_dir|
+      Dir.chdir temp_dir do
+        output = `git clone -q #{git_url} 2>&1`
+        return output if $CHILD_STATUS.to_i != 0
+        Dir.chdir 'usb-driver' do
+          output = `make all 2>&1`
+          return output if $CHILD_STATUS.to_i != 0
+          FileUtils.cp 'libusb-driver.so', target_path
+        end
+      end 
+    end
+    nil
+  end
+
+  # Sets up the udev daemon to allow non-root access to the USB cable.
+  def self.configure_udev
+    Xilinx::Provision::Udev.add_rules udev_rules, '71-xilinx-usb-cable'
+    nil
+  end
+  
+  # Rules for the udev daemon to allow non-root access to the USB cable.
+  #
+  # Returns an array of rules to be written to a udev file.
+  def self.udev_rules
+    ['ACTION=="add", SUBSYSTEMS=="usb", ATTRS{idVendor}=="03fd", MODE="666"']
+  end
+  
+  # The path to the driver file.
+  def self.path
+    File.expand_path '../libusb-driver.so', Xilinx::Provision::Impact.path
+  end
+  
+  # The URL printed when no ISE installation is found.
+  def self.git_url
+    'git://git.zerfleddert.de/usb-driver'
+  end
+end  # namespace Xilinx::Provision::CableDriver
+
+end  # namespace Xilinx::Provision
+
+end  # namespace Xilinx

data/lib/xilinx/provision/cable_firmware.rb

@@ -0,0 +1,88 @@
+# :nodoc namespace
+module Xilinx
+
+# :nodoc namespace
+module Provision
+
+# Finds firmware files for the Xilinx USB cable and sets up automatic uploading.
+#
+# The USB cables are weird beasts. A cable contains a small FPGA that must be
+# programmed every time the cable is powered up, which happens on every
+# connection to the computer.
+#
+# Xilinx ISE ships with the firmware for all cable types, but it doesn't
+# automatically upload the firmware when needed. Udev to the rescue!
+module CableFirmware
+  # Performs all the setup needed for automated firmware upload.
+  #
+  # Returns a false value in case of success, or a string with error information
+  # if something goes wrong.
+  def self.setup
+    if output = configure_udev
+      return "Error while configuring firmware upload udev rules\n#{output}"
+    elsif output = Xilinx::Provision::Udev.reload_rules
+      return "Error while loading firmware upload udev rules\n#{output}"
+    end
+    nil
+  end
+  
+  # Sets up the udev daemon to allow non-root access to the USB cable.
+  def self.configure_udev
+    Xilinx::Provision::Udev.add_rules udev_rules,
+                                      '71-xilinx-usb-firmware-upload'
+    nil
+  end
+  
+  # Rules for the udev daemon to allow non-root access to the USB cable.
+  #
+  # Returns an array of rules to be written to a udev file.
+  def self.udev_rules
+    return nil unless path = rules_path
+    old_rules = File.read(rules_path).split("\n")
+    upgrade_rules old_rules, path
+  end
+  
+  # Returns a 
+  def self.upgrade_rules(old_rules, rules_path)
+    rules_dir = File.dirname rules_path
+    old_rules.map do |old_rule|
+      rule = old_rule.dup
+      # Update old udev syntax.
+      [['TEMPNODE', 'tempnode'], ['SYSFS', 'ATTRS'],
+       ['BUS', 'SUBSYSTEMS']].each { |from, to| rule.gsub! from, to }
+      
+      # Change firmware file references to point inside Xilinx ISE. It's very
+      # rude to copy crap straigt into /usr/share, Xilinx!
+      rule.gsub!(/ \S+\.hex /) do |filepath|
+        firmware_name = File.basename filepath.strip
+        " #{File.join(rules_dir, firmware_name)} "
+      end
+      
+      rule
+    end
+  end
+  
+  # The path to the firmware upload rules file that ships with ISE.
+  #
+  # This file is written in old-style udev, so it needs to be converted.
+  #
+  # Returns a path to the rules file, or nil if the file cannot be found.
+  def self.rules_path
+    dir_path = Xilinx::Provision::Impact.path
+    until dir_path == '/' || dir_path.empty?
+      dir_path = File.dirname dir_path
+      matches = Dir[File.join(dir_path, '**', '*.rules')]
+      next if matches.empty?
+      if matches.length > 1
+        better_matches = Dir[File.join(dir_path, '**', 'xusbdfwu.rules')]
+        matches = better_matches unless better_matches.empty?
+      end
+      return matches.sort.last
+    end
+    nil
+  end
+end  # namespace Xilinx::Provision::CableFirmware
+
+end  # namespace Xilinx::Provision
+
+end  # namespace Xilinx

data/lib/xilinx/provision/impact.rb

@@ -0,0 +1,157 @@
+require 'tmpdir'
+
+# :nodoc namespace
+module Xilinx
+
+# :nodoc namespace
+module Provision
+
+# Runs the impact tool.
+module Impact
+  # Programs an FPGA chip on a JTAG chain.
+  #
+  # The options argument accepts the following keys:
+  #   :cable_port:: set to :auto by default
+  #
+  # Returns a false value for success, or a string containing error output if
+  # something goes wrong.
+  def self.program_fpga(bitfile, options = {})
+    options = { :mode => :bscan }.merge options
+    options[:cable_port] ||= :auto
+    devices = identify_chain(options)
+    
+    bitfile = File.expand_path bitfile
+    batch = [
+      'identify',
+      "assignFile -position #{devices.length} -file #{bitfile}",
+      "program -position #{devices.length}",
+      'cleanCableLock',
+      'closeCable'
+    ]
+    options.merge! :batch => batch
+    output = run options
+    $CHILD_STATUS.to_i == 0 ? nil : output
+  end
+  
+  # Scans the JTAG chain and returns the devices on it.
+  #
+  # The options argument accepts the following keys:
+  #   :cable_port:: set to :auto by default
+  #
+  # Returns the command's output.
+  def self.identify_chain(options = {})
+    batch = ['identify', 'cleanCableLock', 'closeCable']
+    options = {:mode => :bscan, :cable_port => :auto, :batch => batch}
+    parse_identify run(options)
+  end
+  
+  # Extracts a JTAG chain from an impact identify command.
+  #
+  # Args:
+  #   output:: the impact command output, obtained from Impact#run
+  #
+  # Returns an array of hashes with the following keys:
+  #   name:: the device name, e.g. "Xilinx xc5vlx110t"
+  #   version:: number reported by impact
+  def self.parse_identify(output)
+    lines = output.split("\n").each(&:strip!)
+    lines.each_with_index do |line, index|
+      if /ident.*chain/i =~ line
+        lines = lines[index..-1]
+        break
+      end
+    end
+    
+    device_id_regexp = /'(\d+)':.*manufacturer.* id.*=([^,]+),.*version.*(\d+)/i
+    devices = []
+    device = {}
+    lines.each do |line|
+      if match = device_id_regexp.match(line)
+        device[:index] = match[1].to_i
+        device[:name] = match[2].strip
+        device[:version] = match[3].to_i
+      end
+      if /^\-+$/ =~ line && !device.empty?
+        devices << device
+        device = {}
+      end
+    end
+    devices
+  end
+  
+  # Runs the impact tool and returns the status.
+  #
+  # The options argument accepts the following keys:
+  #   :batch:: array of commands to be written to a batch file and executed
+  #   :mode:: device configuration mode (try :bscan for JTAG boundary scan)
+  #   :cable_port:: (try :auto)
+  #
+  # Returns the command's output.
+  def self.run(options = {})
+    unless command_line =
+        "LD_PRELOAD=#{Xilinx::Provision::CableDriver.path} " + path
+      raise "Xilinx ISE not found\nPlease download from #{download_url}"
+    end
+    
+    batch = options[:batch] && options[:batch].dup
+    
+    if options[:cable_port]
+      command_line << " -port #{options[:cable_port]}"
+      batch.unshift "setCable -port #{options[:cable_port]}" if batch
+    end
+    if options[:mode]
+      command_line << " -mode #{options[:mode]}"
+      batch.unshift "setMode -#{options[:mode]}" if batch
+    end
+    batch.push 'quit' if batch && batch.last != 'quit'
+    
+    output = nil
+    Dir.mktmpdir do |temp_dir|
+      Dir.chdir temp_dir do
+        if options[:batch]
+          File.open('impact_batch', 'wb') do |f|
+            f.write batch.map { |line| line + "\n" }.join
+          end
+          command_line << ' -batch impact_batch'
+        end
+        command_line << ' 2>&1'
+        output = Kernel.`(command_line)
+      end 
+    end
+    output
+  end
+  
+  # Path to the impact binary.
+  def self.path
+    @path ||= path!
+  end
+  
+  # Cached path.
+  @path = nil
+  
+  # Path to the impact binary.
+  #
+  # This method does not cache its result and is really slow.
+  def self.path!
+    paths = Dir['/opt/**/impact']
+    paths = Dir['/usr/**/impact'] if paths.empty?
+    
+    # 1 is a Fixnum which is a pointer, so its size shows 32/64-bit
+    if 1.size == 8
+      paths = paths.select { |path| path.index '64' }
+    else
+      paths = paths.reject { |path| path.index '64' }
+    end
+    
+    paths.sort.last
+  end
+  
+  # The URL printed when no ISE installation is found.
+  def self.download_url
+    'http://www.xilinx.com/support/download/index.htm'
+  end
+end  # namespace Xilinx::Provision::Impact
+
+end  # namespace Xilinx::Provision
+
+end  # namespace Xilinx

data/lib/xilinx/provision/udev.rb

@@ -0,0 +1,46 @@
+require 'English'
+
+# :nodoc namespace
+module Xilinx
+
+# :nodoc namespace
+module Provision
+
+# Runs the impact tool.
+module Udev
+  # Installs a group of udev rules.
+  def self.add_rules(rules, group_name)
+    file = File.join rules_path, group_name + '.rules'
+    File.open file, 'w' do |f|
+      f.write rules.map { |rule| rule + "\n" }.join
+    end
+  end
+
+  # Removes a group of udev rules.
+  def self.remove_rules(group_name)
+    file = File.join rules_path, group_name + '.rules'
+    File.unlink file if File.exist?(file)
+  end
+  
+  # Asks udev to reload its rules to reflect updates done by add_rules.
+  #
+  # Returns a false value for success, or a string containing error output if
+  # something goes wrong.
+  def self.reload_rules
+    output = `/etc/init.d/udev restart 2>&1`
+    $CHILD_STATUS.to_i == 0 ? nil : output
+  end
+  
+  # Directory or file containing the udev rules.
+  def self.rules_path
+    if File.exist? '/etc/udev/rules.d'
+      return '/etc/udev/rules.d'
+    else
+      raise "Unsupported OS or distribution."
+    end
+  end
+end  # module Xilinx::Provision::Udev
+
+end  # module Xilinx::Provision
+
+end  # module Xilinx

data/spec/fixtures/impact_detect

@@ -0,0 +1,75 @@
+Release 13.1 - iMPACT O.40d (lin64)
+Copyright (c) 1995-2011 Xilinx, Inc.  All rights reserved.
+Preference Table
+Name                 Setting             
+StartupClock         Auto_Correction     
+AutoSignature        False               
+KeepSVF              False               
+ConcurrentMode       False               
+UseHighz             False               
+ConfigOnFailure      Stop                
+UserLevel            Novice              
+MessageLevel         Detailed            
+svfUseTime           false               
+SpiByteSwap          Auto_Correction     
+AutoInfer            false               
+SvfPlayDisplayComments false               
+AutoDetecting cable. Please wait.
+ Using windrvr6 driver.
+Connecting to cable (Usb Port - USB21).
+Checking cable driver.
+File version of /opt/Xilinx/13.1/ISE_DS/ISE/bin/lin64/xusbdfwu.hex = 1030.
+File version of /etc/hotplug/usb/xusbdfwu.fw/xusbdfwu.hex = 1030.
+ libusb-driver.so version: 2011-03-25 19:15:17.
+ Cable PID = 0008.
+ Max current requested during enumeration is 150 mA.
+Type = 0x0005.
+ Cable Type = 3, Revision = 0.
+ Setting cable speed to 6 MHz.
+Cable connection established.
+Firmware version = 2401.
+File version of /opt/Xilinx/13.1/ISE_DS/ISE/data/xusb_xp2.hex = 2401.
+Firmware hex file version = 2401.
+PLD file version = 200Dh.
+ PLD version = 200Dh.
+Type = 0x0005.
+ESN option: 0000149C444901.
+Identifying chain contents...'0': : Manufacturer's ID = Xilinx xc5vlx110t, Version : 10
+INFO:iMPACT:1777 - 
+   Reading /opt/Xilinx/13.1/ISE_DS/ISE/virtex5/data/xc5vlx110t.bsd...
+INFO:iMPACT:501 - '1': Added Device xc5vlx110t successfully.
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+'1': : Manufacturer's ID = Xilinx xccace, Version : 0
+INFO:iMPACT:1777 - 
+   Reading /opt/Xilinx/13.1/ISE_DS/ISE/acecf/data/xccace.bsd...
+INFO:iMPACT:501 - '1': Added Device xccace successfully.
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+'2': : Manufacturer's ID = Xilinx xc95144xl, Version : 5
+INFO:iMPACT:1777 - 
+   Reading /opt/Xilinx/13.1/ISE_DS/ISE/xc9500xl/data/xc95144xl.bsd...
+INFO:iMPACT:501 - '1': Added Device xc95144xl successfully.
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+'3': : Manufacturer's ID = Xilinx xcf32p, Version : 15
+INFO:iMPACT:1777 - 
+   Reading /opt/Xilinx/13.1/ISE_DS/ISE/xcfp/data/xcf32p.bsd...
+INFO:iMPACT:501 - '1': Added Device xcf32p successfully.
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+'4': : Manufacturer's ID = Xilinx xcf32p, Version : 15
+INFO:iMPACT:501 - '1': Added Device xcf32p successfully.
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+done.
+Elapsed time =      0 sec.
+Elapsed time =      0 sec.
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+----------------------------------------------------------------------
+----------------------------------------------------------------------

data/spec/fixtures/snippet.rules

@@ -0,0 +1,3 @@
+# version 0003
+SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0008", MODE="666"
+BUS=="usb", ACTION=="add", SYSFS{idVendor}=="03fd", SYSFS{idProduct}=="0007", RUN+="/sbin/fxload -v -t fx2 -I /usr/share/xusbdfwu.hex -D $TEMPNODE"

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+require 'rspec'
+require 'xilinx/provision'
+require 'ether_ping'
+
+# Requires supporting files with custom matchers and macros, etc,
+# in ./support/ and its subdirectories.
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
+
+RSpec.configure do |config|
+  
+end

data/spec/xilinx/provision/cable_driver_spec.rb

@@ -0,0 +1,54 @@
+require File.expand_path('../../spec_helper', File.dirname(__FILE__))
+
+describe Xilinx::Provision::CableDriver do
+  describe 'build_prerequisites' do
+    before do
+      # Remove one a package without deps to validate that it reinstalls.
+      if File.exist? `which apt-get`.strip
+        `apt-get remove -y fxload 2>&1`
+      end
+    end
+    
+    it 'should install the fxload binary' do
+      Xilinx::Provision::CableDriver.build_prerequisites.should be_nil
+      File.exist?(`which fxload`.strip).should be_true
+    end
+    
+    it 'should forward build output if an error happens' do
+      Kernel.stub(:`) do
+        Kernel.system 'false'
+        'Error 42'
+      end
+      Xilinx::Provision::CableDriver.build_prerequisites.
+          should match(/Error 42/)
+    end
+  end
+  
+  describe 'build' do
+    before { Xilinx::Provision::CableDriver.build_prerequisites }
+    
+    before { @temp_dir = Dir.mktmpdir }
+    after { FileUtils.rm_rf @temp_dir }
+    
+    it 'should copy the USB driver to the given target' do
+      Xilinx::Provision::CableDriver.build(@temp_dir).should be_nil
+      Dir[File.join(@temp_dir, '*.so')].map { |entry| File.basename(entry) }.
+                                        should include('libusb-driver.so')
+    end
+    
+    it 'should forward build output if an error happens' do
+      Xilinx::Provision::CableDriver.should_receive(:git_url).and_return '::'
+      Xilinx::Provision::CableDriver.build(@temp_dir).
+          should match(/No such file or directory/i)
+    end
+  end
+  
+  describe 'path' do
+    let(:path) { Xilinx::Provision::CableDriver.path }
+    
+    it 'should point to a valid directory' do
+      File.exist?(File.dirname(path)).should be_true
+      File.directory?(File.dirname(path)).should be_true
+    end
+  end
+end

data/spec/xilinx/provision/cable_firmware_spec.rb

@@ -0,0 +1,55 @@
+require File.expand_path('../../spec_helper', File.dirname(__FILE__))
+
+describe Xilinx::Provision::CableFirmware do
+  describe 'rules_path' do
+    describe 'on the real system' do
+      let(:path) { Xilinx::Provision::CableFirmware.rules_path }
+      
+      it 'should point to a valid file' do
+        File.exist?(path).should be_true
+        File.directory?(path).should be_false
+      end
+    end
+    
+    describe 'on the mock system' do
+      before { Xilinx::Provision::Impact.stub!(:path).and_return(__FILE__) }
+      
+      it 'should find the mock rules file' do
+        Xilinx::Provision::CableFirmware.rules_path.
+            should match(/snippet.rules$/)
+      end
+    end
+  end
+  
+  describe 'udev rules' do
+    describe 'on the real system' do
+      let(:rules) { Xilinx::Provision::CableFirmware.udev_rules }
+      
+      it 'should output a non-empty array' do
+        rules.should have_at_least(1).rule
+      end
+      
+      it 'should only have strings in the array' do
+        rules.all? { |rule| rule.respond_to? :to_str }.should be_true
+      end
+    end
+    
+    describe 'on the mock system' do
+      before { Xilinx::Provision::Impact.stub!(:path).and_return(__FILE__) }
+      
+      it 'should match the golden output' do
+        Xilinx::Provision::CableFirmware.udev_rules.should == [
+          '# version 0003',
+          'ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0008", MODE="666"',
+          %Q|SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="03fd", ATTRS{idProduct}=="0007", RUN+="/sbin/fxload -v -t fx2 -I #{File.expand_path('../../../fixtures', __FILE__)}/xusbdfwu.hex -D $tempnode"|
+        ]
+      end
+    end
+  end
+  
+  describe 'configure_udev' do
+    it 'should run happily' do
+      Xilinx::Provision::CableFirmware.configure_udev.should be_nil
+    end
+  end
+end

data/spec/xilinx/provision/impact_spec.rb

@@ -0,0 +1,85 @@
+require File.expand_path('../../spec_helper', File.dirname(__FILE__))
+
+describe Xilinx::Provision::Impact do
+  describe 'path' do
+    let(:path) { Xilinx::Provision::Impact.path }
+    
+    it 'is a non-empty string' do
+      path.should be_kind_of String
+      path.should_not be_empty
+    end
+    
+    it 'can be executed, and outputs a Xilinx banner' do
+      Kernel.`(path + ' -help').should include('Xilinx')
+    end
+  end
+  
+  describe 'run' do
+    it 'should piece the impact command-line correctly' do
+      Xilinx::Provision::Impact.stub(:path).and_return('/path/to/impact')
+      Kernel.should_receive(:`).with 'LD_PRELOAD=/path/to/libusb-driver.so ' +
+          '/path/to/impact -port auto -mode bscan -batch impact_batch 2>&1'
+      lambda {
+        Xilinx::Provision::Impact.run :batch => ['identify'], :mode => :bscan,
+            :cable_port => :auto
+      }.should_not raise_error
+    end
+    
+    it 'should run an identify correctly' do
+      Xilinx::Provision::Impact.run(:batch => ['identify'], :mode => :bscan,
+          :cable_port => :auto).should match(/identifying chain/i)
+    end
+  end
+  
+  describe 'parse_identify' do
+    describe 'on mock input' do
+      let(:output) do
+        Xilinx::Provision::Impact.parse_identify(File.read(
+            File.expand_path('../../../fixtures/impact_detect', __FILE__)))
+      end
+      
+      it 'should find 5 devices' do
+        output.should have(5).devices
+      end
+      
+      it 'should show the FPGA as device 0' do
+        output[0][:name].should == 'Xilinx xc5vlx110t'
+      end
+
+      it 'should identify the FPGA version' do
+        output[0][:name].should == 'Xilinx xc5vlx110t'
+      end
+    end
+  end
+  
+  describe 'identify_chain' do
+    it 'should find at least one device' do
+      Xilinx::Provision::Impact.identify_chain.should have_at_least(1).device
+    end
+  end
+  
+  describe 'program_fpga' do
+    describe 'with the ethernet bitfile' do
+      let(:bitfile) do
+        File.expand_path('../../../fixtures/ethernet_ping.bit', __FILE__)
+      end
+      
+      let(:return_value) do
+        Xilinx::Provision::Impact.program_fpga bitfile
+      end
+      
+      let(:ethernet_device) do
+        'eth0'
+      end
+      
+      it 'should return nil for success' do
+        return_value.should be_nil
+      end
+      
+      it 'should make the FPGA respond to pings' do
+        client = EtherPing::Client.new ethernet_device, 0x88B5, '001122334455'
+        client.ping("abcd", 3).should be_kind_of(Numeric)
+      end
+    end
+  end
+end

data/spec/xilinx/provision/udev_spec.rb

@@ -0,0 +1,41 @@
+require File.expand_path('../../spec_helper', File.dirname(__FILE__))
+
+describe Xilinx::Provision::Impact do
+  let(:path) { Xilinx::Provision::Udev.rules_path }
+  
+  describe 'rules_path' do
+    it 'should point to a directory' do
+      File.directory?(path).should be_true
+    end
+  end
+  
+  describe 'add_rules' do
+    before { Xilinx::Provision::Udev.add_rules ['ab', 'cd'], '99-spec-group' }
+    after { Xilinx::Provision::Udev.remove_rules '99-spec-group' }
+    
+    let(:file_matches) { Dir[File.join(path, '99-spec-group*')] }
+    
+    it 'should create a file' do
+      file_matches.should have(1).file
+    end
+    
+    it 'should write the rules in the file' do
+      File.read(file_matches.first).should == "ab\ncd\n"
+    end
+
+    describe 'remove_rules' do
+      before { Xilinx::Provision::Udev.remove_rules '99-spec-group' }
+      
+      it 'should remove the previously added file' do
+        Dir[File.join(path, '99-spec-group*')].should be_empty
+      end
+    end
+  end
+  
+  describe 'reload_rules' do
+    it 'should execute happily' do
+      Xilinx::Provision::Udev.reload_rules
+      $CHILD_STATUS.to_i.should == 0
+    end
+  end
+end

data/spec/xilinx/provision_spec.rb

@@ -0,0 +1,26 @@
+require File.expand_path('../spec_helper', File.dirname(__FILE__))
+
+describe Xilinx::Provision do
+  describe 'fpga' do
+    it 'delegates to Impact.program_fpga' do
+      Xilinx::Provision::Impact.should_receive(:program_fpga).
+                                with('/path/to/bitfile', {}).and_return(nil)
+      Xilinx::Provision.fpga('/path/to/bitfile').should be_true
+    end
+    
+    it 'raises an exception if programming fails' do
+      Xilinx::Provision::Impact.should_receive(:program_fpga).
+                                with('/path/to/bitfile', {}).and_return("42")
+      lambda {
+        Xilinx::Provision.fpga '/path/to/bitfile'
+      }.should raise_error
+    end
+    
+    it 'works with a real bitfile' do
+      lambda {
+        bitfile = File.expand_path '../../fixtures/ethernet_ping.bit', __FILE__
+        Xilinx::Provision.fpga bitfile
+      }.should_not raise_error
+    end
+  end
+end

metadata

@@ -0,0 +1,184 @@
+--- !ruby/object:Gem::Specification 
+name: xilinx-provision
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: 
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Victor Costan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-01 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 29
+        segments: 
+        - 3
+        - 6
+        - 1
+        version: 3.6.1
+  prerelease: false
+  version_requirements: *id001
+  name: rdoc
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 23
+        segments: 
+        - 2
+        - 6
+        - 0
+        version: 2.6.0
+  prerelease: false
+  version_requirements: *id002
+  name: rspec
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 11
+        segments: 
+        - 1
+        - 0
+        - 14
+        version: 1.0.14
+  prerelease: false
+  version_requirements: *id003
+  name: bundler
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 6
+        - 1
+        version: 1.6.1
+  prerelease: false
+  version_requirements: *id004
+  name: jeweler
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  prerelease: false
+  version_requirements: *id005
+  name: rcov
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        hash: 17
+        segments: 
+        - 0
+        - 3
+        - 1
+        version: 0.3.1
+  prerelease: false
+  version_requirements: *id006
+  name: ether_ping
+description: Wraps the impact CLI tool in the Xilinx ISE
+email: victor@costan.us
+executables: 
+- xilinx-provision
+- xilinx-provision-setup
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE.txt
+- README.rdoc
+files: 
+- .document
+- .project
+- .rspec
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.rdoc
+- Rakefile
+- VERSION
+- bin/xilinx-provision
+- bin/xilinx-provision-setup
+- lib/xilinx/provision.rb
+- lib/xilinx/provision/cable_driver.rb
+- lib/xilinx/provision/cable_firmware.rb
+- lib/xilinx/provision/impact.rb
+- lib/xilinx/provision/udev.rb
+- spec/fixtures/ethernet_ping.bit
+- spec/fixtures/impact_detect
+- spec/fixtures/snippet.rules
+- spec/spec_helper.rb
+- spec/xilinx/provision/cable_driver_spec.rb
+- spec/xilinx/provision/cable_firmware_spec.rb
+- spec/xilinx/provision/impact_spec.rb
+- spec/xilinx/provision/udev_spec.rb
+- spec/xilinx/provision_spec.rb
+homepage: http://github.com/csail/xilinx-provision
+licenses: 
+- MIT
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.4
+signing_key: 
+specification_version: 3
+summary: Deploys bitfiles to Xilinx FPGAs
+test_files: []
+