katcp 0.1.8 → 0.1.10

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b2ff660c3d5dc7a953d33929f927b4db105090e1
+  data.tar.gz: 260e11b31ab6bdffa5be4e1a0ce0038027a793da
+SHA512:
+  metadata.gz: ced30aa287a9971789e7c387a2b5f8f294891c318fe9d3a28e806a12450a44adc3baf20e91a7d589611d3a136260bd46dae20a99390f55611bdba2fc4a8b218d
+  data.tar.gz: 618cba5da5aa45443a093ff558f03f14ae3bf936815c69985c4d326007fb45db068a65fa84d72903a94ee4c2a1f83fb6996f8d1f418253b3c9784944e869ac27

data/bin/katcpcmd.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+require 'optparse'
+require 'katcp'
+
+OPTS = {
+  :verbose => false
+}
+
+ARGV.options do |op|
+  op.program_name = File.basename($0)
+
+  op.banner = "Usage: #{op.program_name} [OPTIONS] HOST[:PORT] [CMD [ARGS]]"
+  op.separator('')
+  op.separator('Runs KATCP command CMD with (optional) arguments ARGS on HOST.')
+  op.separator('If CMD is not given, just connect and print inform messages.')
+  op.separator('Non-standard port can be given as HOST:PORT.')
+  op.separator('')
+  op.separator("Example: #{op.program_name} roach2 progdev my_design.bof")
+  op.separator('')
+  op.separator 'Options:'
+  op.on_tail("-v", "--[no-]verbose", "Prints inform messages") do |o|
+    OPTS[:verbose] = o
+  end
+  op.on_tail("-h", "--help", "Show this message") do
+    puts op
+    exit 1
+  end
+  op.parse!
+end
+
+if ARGV.empty?
+  puts ARGV.options
+  exit 1
+end
+
+host, port = ARGV.shift.split(':')
+port ||= ENV['KATCP_PORT'] || '7147'
+port = Integer(port) rescue 7147
+
+cmd = ARGV.shift
+
+exit_status = 0
+
+r = KATCP::RoachClient.new(host, port)
+
+if cmd
+  informs = r.informs(true)
+  puts informs if OPTS[:verbose]
+
+  resp = r.respond_to?(cmd) ? r.send(cmd, *ARGV) : r.request(cmd, *ARGV)
+
+  case resp
+  when KATCP::Response
+    puts resp
+    exit_status = resp.ok? ? 0 : 1
+  when KATCP::Client
+    # Print log informs
+    puts resp.informs(true).grep(/^#log/)
+  # Handle programmed? and other true/false operations
+  when true
+    puts resp if OPTS[:verbose]
+    exit_status = 0
+  when false
+    puts resp if OPTS[:verbose]
+    exit_status = 1
+  else
+    puts "got a #{resp.class}: #{resp.inspect}"
+  end
+
+  puts r.informs(true) if OPTS[:verbose]
+else
+  puts r.informs(true)
+end
+
+r.close
+
+exit exit_status

data/lib/katcp/client.rb

@@ -383,7 +383,7 @@ module KATCP
     # call-seq:
     #   sensor_dump(*args) -> KATCP::Response
     #
-    # Dumps the sensor tree.
+    # Dumps the sensor tree. [obsolete?]
     def sensor_dump(*args)
       request(:sensor_dump, *args)
     end

data/lib/katcp/client/roach.rb

@@ -68,6 +68,8 @@ module KATCP
     # Returns xaui status word.  Bits 2 through 5 are lane sync, bit 6 is
     # channel bonding status.
     def xaui_status; get(9); end
+    # Returns true if all four lanes are sync'd and bonded.
+    def xaui_status_ok?; (get(9) & 0b01111100) == 0b01111100; end
     # Four least significant bits represent sync status for each lane.
     #   1 bit = lane sync OK
     #   0 bit = lane sync BAD
@@ -77,7 +79,7 @@ module KATCP
     # Returns true if #xaui_sync returns 15
     def xaui_sync_ok?; xaui_sync == 0b1111; end
     # Returns true if all four XAUI lanes are bonded
-    def xaui_bonded?; (get(9) >> 6) & 1; end
+    def xaui_bonded?; ((get(9) >> 6) & 1) == 1; end
 
     # Get current value of rx_eq_mix parameter.
     def rx_eq_mix   ; (get(10) >> 24) & 0xff; end
@@ -97,6 +99,69 @@ module KATCP
     def []=(idx, mac)
       write64(0xc00+2*idx, mac)
     end
+  end # class TenGE
+
+  # Class used to access CASPER Snapshot blocks.  +device_name+ must be used
+  # with the bram or dram device in the snapshot block.  Other devices in the
+  # snapshot block may be hidden/ignored with :skip in the device_typemap or
+  # may be exposed/used if desired.  Currently this class only uses the memory
+  # element and the "trig" register; it does not directly use the "status"
+  # register or the optional "trig_offset" or "tr_en_cnt" registers.
+  class Snapshot < Bram
+    def initialize(katcp_client, device_name)
+      super
+      @ctrl_name = device_name.sub(/_[bd]ram$/, '_ctrl')
+    end
+
+    # Validate and massage method name
+    def self.method_name(name)
+      if name !~ /_[bd]ram$/
+        raise "invalid name '#{name}' for #{self.name}"
+      end
+      name.sub!(/_[bd]ram$/, '')
+    end
+
+    # Trigger a new snapshot.  +opts+ can be used to control the trigger type
+    # using the :trigger key and the write enable using the :wren key:
+    #
+    #   :trigger => :internal means trigger right away
+    #   :trigger => :external means trigger on the block's trigger input
+    #   :wren => :internal means to capture every FPGA clock cycle
+    #   :wren => :external means to capture when the block's we input is high
+    #
+    # The default behavior is :internal for both.
+    def trigger(opts={})
+      # Assume internal for both
+      trigval = 6
+      # Turn off bits if external
+      trigval ^= 2 if /^ext/ =~ (opts[:trigger]||opts[:trig])
+      trigval ^= 4 if /^ext/ =~  opts[:wren]
+      @katcp_client.write(@ctrl_name, trigval)
+      @katcp_client.write(@ctrl_name, trigval|1)
+      @katcp_client.write(@ctrl_name, trigval)
+    end
+  end # class Snapshot
+
+  # Class used to access QDR controller cores
+  class QdrCtrl < Bram
+    # Resets the QDR controller (re-calibrates)
+    def reset
+      self[0] = 0
+      self[1] = 0xffff_ffff
+      self[0] = 0
+    end
+
+    # Returns state of cal_fail bit
+    def cal_fail?
+      # Bit 8
+      (self[1] & (1<<8)) != 0
+    end
+
+    # Returns state of phy_rdy bit (
+    def phy_rdy?
+      # Bit 0
+      (self[1] & (1<<0)) != 0
+    end
   end
 
   # Facilitates talking to <tt>tcpborphserver2</tt>, a KATCP server
@@ -146,9 +211,12 @@ module KATCP
     #   :local_port     Specifies local port to bind to (default nil)
     #   :socket_timeout Specifies timeout for socket operations
     #                   (default DEFAULT_SOCKET_TIMEOUT)
-    #   :typemap        Provides a default device typemap (default {}).
-    #                   See #device_typemap for details.
+    #   :typemap        Provides a way to override the default device typemap
+    #                   (default {}).  See #device_typemap for details.
     def initialize(*args)
+      # If final arg is a Hash, pop it off
+      @opts = (Hash === args[-1]) ? args.pop : {}
+
       # List of all devices
       @devices = [];
       # List of dynamically defined device attrs (readers only, writers implied)
@@ -156,7 +224,11 @@ module KATCP
       # @device objects is a Hash of created device objects: key is Class,
       # value is a Hash mapping device name to instance of Class.
       @device_objects = {}
-      # Call super *after* initializing subclass instance variables
+      # Merge @opts[:typemap] (if given) into device_typemap.
+      # This must be done *before* calling super.
+      device_typemap.merge!(@opts[:typemap]) if @opts[:typemap]
+      # Call super *after* initializing instance variables and possibly
+      # updating typemap.
       super(*args)
     end
 
@@ -206,14 +278,20 @@ module KATCP
           type, *aliases = typemap[dev] || typemap[dev.to_sym]
           next if type == :skip
           # Dynamically define methods and aliases
-          case type
-          when Class;  device_object(type,  dev, *aliases)
-          when :bram;  device_object(Bram,  dev, *aliases)
-          when :tenge; device_object(TenGE, dev, *aliases)
-          when :roreg; roreg(dev, *aliases)
-          # else :rwreg or nil (or anything else for that matter) so treat it
-          # as R/W register.
-          else rwreg(dev, *aliases)
+          begin
+            case type
+            when Class;    device_object(type,  dev, *aliases)
+            when :bram;    device_object(Bram,  dev, *aliases)
+            when :tenge;   device_object(TenGE, dev, *aliases)
+            when :snap;    device_object(Snapshot, dev, *aliases)
+            when :qdrctrl; device_object(QdrCtrl, dev, *aliases)
+            when :roreg;   roreg(dev, *aliases)
+            # else :rwreg or nil (or anything else for that matter) so treat it
+            # as R/W register.
+            else rwreg(dev, *aliases)
+            end
+          rescue => e
+            STDERR.puts e
           end
         end
       end
@@ -237,6 +315,45 @@ module KATCP
 
     protected :undefine_device_attrs
 
+    # This is the default (empty) typemap.  It exists here so that subclasses
+    # (and their subclasses) have the option of using the following idiom to
+    # create their own custom typemap that includes their superclass's typemap:
+    #
+    #   class SomeClass < KATCP::RoachClient
+    #     DEVICE_TYPEMAP = superclass::DEVICE_TYPEMAP.merge({
+    #       :some_device => :rwreg
+    #     })
+    #     ...
+    #   end
+    #
+    #   class MyClass < SomeClass
+    #     DEVICE_TYPEMAP = superclass::DEVICE_TYPEMAP.merge({
+    #       :switch_gbe_status => :roreg,
+    #       :switch_gbe        => :tenge,
+    #       :adc_rms_levels    => :bram
+    #     })
+    #     ...
+    #   end
+    #
+    # As defined above, MyClass::DEVICE_TYPEMAP will be:
+    #
+    #   {
+    #     :some_device       => :rwreg,
+    #     :switch_gbe_status => :roreg,
+    #     :switch_gbe        => :tenge,
+    #     :adc_rms_levels    => :bram
+    #   }
+    #
+    # Because the superclass of SomeClass is KATCP::RoachClient, the
+    # "superclass::DEVICE_TYPEMAP.merge" part is optional in SomeClass, but it
+    # is still recommended since future versions of KATCP::RoachClient may have
+    # a non-empty typemap.
+    DEVICE_TYPEMAP = {}
+
+    # Returns the default device typemap Hash (either the one passed to the
+    # constructor or an empty Hash).  Design specific subclasses can override
+    # this method to return a design specific device typemap.
+    #
     # This method's return value controls how methods and aliases are
     # dynamically generated for devices within the ROACH gateware.  If
     # #device_typemap returns +nil+ or an empty Hash, all devices will be
@@ -259,7 +376,36 @@ module KATCP
     #                                will be created.  The returned TenGE object
     #                                provides convenient ways to read and write
     #                                to the TenGE device.
+    #   :snap (Snapshot)             A reader method returning a Snapshot object
+    #                                will be created.  The returned Snapshot
+    #                                object provides a trigger method and acts
+    #                                like a Bram object for the Snapshot's
+    #                                memory element.  Must be used with the
+    #                                snapshot block's BRAM (or DRAM) device.
+    #   :qdrctrl (QDR controller)    A reader method returning a QdrCtrl object
+    #                                will be created.  The returned QdrCtrl
+    #                                object provides methods to reset the QDR
+    #                                controller and check its cal_fail and
+    #                                phy_rdy status bits.
     #   :skip (unwanted device)      No method will be created.
+    #   A class name (custom)        A user-supplied class can be given to
+    #                                allow for customized device access.
+    #
+    # If a class name is specified, the method defined for the corresponding
+    # device will return an instance of the given class.  The constructor will
+    # be passed the KATCP::Client instance and a String specifying the device
+    # name.  Here is an example of a suitable class definition:
+    #
+    #   class MyDevice
+    #     def initialize(katcp_client, device_name)
+    #       # Save client and device name for future use
+    #       @katcp_client = katcp_client
+    #       @device_name  = device_name
+    #     end
+    #
+    #     # Other functionality defined here
+    #
+    #   end # class MyDevice
     #
     # Methods are only created for devices that actually exist on the device.
     # If no device exists for a given key, no methods will be created for that
@@ -267,9 +413,9 @@ module KATCP
     # created unless they are backed by an actual device.  Both reader and
     # writer methods are created for devices for which no key is present.
     #
-    # The value can also be an Array whose first element is a Symbol from the
-    # list above.  The remaining elements specify aliases to be created for the
-    # given attribute methods.
+    # The value can also be an Array whose first element is a Symbol (or class
+    # name) from the list above.  The remaining elements specify aliases to be
+    # created for the given attribute methods.
     #
     # RoachClient#device_typemap returns on empty Hash so all devices are
     # treated as read/write registers by default.  Gateware specific subclasses
@@ -278,29 +424,33 @@ module KATCP
     #
     # Example: The following would lead to the creation of the following
     # methods and aliases: "input_selector", "input_selector=", "insel",
-    # "insel=", "switch_gbe_status", "switch_gbe", "adc_rms_levels" (assuming
-    # the named devices all exist!).  No methods would be created for the
-    # device named "unwanted_reg" even if it exists.
+    # "insel=", "switch_gbe_status", "switch_gbe", "adc_rms_levels", and
+    # "my_device" (assuming the named devices all exist!).  No methods would be
+    # created for the device named "unwanted_reg" even if it exists.
     #
     #   class MyRoachDesign < RoachClient
-    #     DEVICE_TYPEMAP = {
+    #     DEVICE_TYPEMAP = superclass::DEVICE_TYPEMAP.merge({
     #       :input_selector    => [:rwreg, :insel],
     #       :switch_gbe_status => :roreg,
     #       :switch_gbe        => :tenge,
     #       :adc_rms_levels    => :bram,
+    #       :my_device         => MyDevice,
     #       :unwanted_reg      => :skip
-    #     }
+    #     })
     #
     #     def device_typemap
-    #       DEVICE_TYPEMAP
+    #       @device_typemap ||= DEVICE_TYPEMAP.dup
     #     end
     #   end
     #
-    # Returns the default device typemap Hash (either the one passed to the
-    # constructor or an empty Hash).  Design specific subclasses can override
-    # this method to return a design specific device typemap.
+    # If the user passes a typemap Hash to the constructor, that Hash is merged
+    # into the Hash returned by device_typemap.  This can have side effects
+    # that might be unwanted if device_typemap returns a Hash that is
+    # referenced by a class constant.  To avoid that, it is recommended that
+    # device_typemap return the instance variable @device_typemap that is
+    # lazily initialized with a copy of the class constant as shown above.
     def device_typemap
-      (@opts && @opts[:typemap]) || {}
+      @device_typemap ||= DEVICE_TYPEMAP.dup
     end
 
     # Allow subclasses to create read accessor method (with optional aliases)
@@ -355,6 +505,9 @@ module KATCP
     def device_object(clazz, name, *aliases) # :nodoc:
       name = name.to_s
       method_name = name.gsub('/', '_')
+      if clazz.respond_to?(:method_name)
+        method_name = clazz.method_name(method_name)
+      end
       instance_eval <<-"_end"
         class << self
           def #{method_name}()
@@ -463,15 +616,21 @@ module KATCP
     # attributes that were dynamically defined for the previous design are
     # removed.
     def progdev(*args)
+      # Clear args (i.e. remove all elements) if first element is nil.
+      # This also clears args if it is empty, but that is OK since it is
+      # essentially a no-op.  Any time saved by not clearing an empty args
+      # would be lost by checking whether args is already empty! :-)
+      args.clear if args[0].nil?
       prev_socket_timeout = @socket_timeout
       begin
         # Adjust @socket_timeout if programming a bitstream
         @socket_timeout = PROGDEV_SOCKET_TIMEOUT if args[0]
-        request(:progdev, *args)
+        resp = request(:progdev, *args)
       ensure
         @socket_timeout = prev_socket_timeout
       end
       define_device_attrs
+      resp
     end
 
     # Returns true if currently programmed (specifically, it is equivalent to

data/lib/katcp/version.rb

@@ -3,5 +3,5 @@
 #++
 
 module KATCP
-  VERSION = "0.1.8"
+  VERSION = "0.1.10"
 end

metadata

@@ -1,48 +1,41 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: katcp
-version: !ruby/object:Gem::Version 
-  hash: 11
-  prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 8
-  version: 0.1.8
+version: !ruby/object:Gem::Version
+  version: 0.1.10
 platform: ruby
-authors: 
+authors:
 - David MacMahon
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2013-04-29 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-08-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: narray
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 25
-        segments: 
-        - 0
-        - 5
-        - 9
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
         version: 0.5.9
   type: :runtime
-  version_requirements: *id001
-description: "    Provides KATCP client library for Ruby.  KATCP is the Karoo Array Telescope\n    Control Protocol.\n"
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 0.5.9
+description: |2
+      Provides KATCP client library for Ruby.  KATCP is the Karoo Array Telescope
+      Control Protocol.
 email: davidm@astro.berkeley.edu
-executables: []
-
+executables:
+- katcpcmd.rb
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README
-files: 
+files:
 - README
+- bin/katcpcmd.rb
 - lib/katcp.rb
 - lib/katcp/client.rb
 - lib/katcp/client/roach.rb
@@ -53,41 +46,29 @@ files:
 - examples/listdev.rb
 homepage: http://rb-katcp.rubyforge.org/
 licenses: []
-
+metadata: {}
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - -m
 - README
 - --title
-- Ruby/KATCP 0.1.8 Documentation
-require_paths: 
+- Ruby/KATCP 0.1.10 Documentation
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 53
-      segments: 
-      - 1
-      - 8
-      - 1
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
       version: 1.8.1
-required_rubygems_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
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: rb-katcp
-rubygems_version: 1.8.24
+rubygems_version: 2.0.2
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: KATCP library for Ruby
 test_files: []
-