katcp 0.0.2 → 0.0.3

data/lib/katcp/client/roach.rb

@@ -4,12 +4,132 @@ require 'katcp/client'
 module KATCP
 
   # Facilitates talking to <tt>tcpborphserver2</tt>, a KATCP server
-  # implementation that runs on ROACH boards.  Mostly just adds convenience
-  # methods for tab completion in irb.
+  # implementation that runs on ROACH boards.  In addition to providing
+  # convenience wrappers around <tt>tcpborphserver2</tt> requests, it also adds
+  # the following features:
   #
-  #   TODO: Add conveneince methods for converting binary payload data.
+  # * Hash-like access to read and write gateware devices (e.g. software
+  #   registers, shared BRAM, etc.) via methods #[] and #[]=.
+  #
+  # * Each RoachClient instance dynamically adds (and removes) reader and
+  #   writer attributes (i.e. methods) for gateware devices as the FPGA is
+  #   programmed (or de-programmed).  This not only provides for very clean and
+  #   readable code, it also provides convenient tab completion in irb for
+  #   gateware specific device names.
+  #
+  # * Word based instead of byte based data offsets and counts.  KATCP::Client
+  #   data transfer methods #read and #write deal with byte based offsets and
+  #   counts.  These methods in KATCP::RoachClient deal with word based offsets
+  #   and counts since ROACH transfers (currently) require word alignment in
+  #   both offsets and counts.  To use byte based offsets and counts
+  #   explicitly, use <tt>request(:read, ...)</tt> instead of
+  #   <tt>read(...)</tt> etc.
   class RoachClient < Client
 
+    # Returns an Array of Strings representing the device names from the
+    # current design.  The Array will be empty if the currently programmed
+    # gateware has no devices (very rare, if even possible) or if no gateware
+    # is currently programmed.
+    attr_reader :devices
+
+    # Creates a RoachClient that connects to a KATCP server at +remote_host+ on
+    # +remote_port+.  If +local_host+ and +local_port+ are specified, then
+    # those parameters are used on the local end to establish the connection.
+    def initialize(remote_host, remote_port=7147, local_host=nil, local_port=nil)
+      super(remote_host, remote_port, local_host, local_port)
+      # List of all devices
+      @devices = [];
+      # List of dynamically defined device attrs (readers only, writers implied)
+      @device_attrs = [];
+      define_device_attrs
+    end
+
+    # Dynamically define attributes (i.e. methods) for gateware devices, if
+    # currently programmed.
+    def define_device_attrs # :nodoc
+      # First undefine existing device attrs
+      undefine_device_attrs
+      # Define nothing if FPGA not programmed
+      return unless programmed?
+      # Dynamically define accessors for all devices (i.e. registers, BRAMs,
+      # etc.) except those whose names conflict with existing methods.
+      @devices = listdev.lines[0..-2].map {|l| l[1]}
+      @devices.sort!
+      @devices.each do |dev|
+        # TODO sanitize dev in case it is invalid method name
+
+        # Define methods unless they conflict with existing methods
+        if ! respond_to?(dev) && ! respond_to?("#{dev}=")
+          # Save attr name
+          @device_attrs << dev
+          # Dynamically define methods
+          instance_eval <<-"_end"
+            def #{dev}(*args)
+              read('#{dev}', *args)
+            end
+            def #{dev}=(*args)
+              write('#{dev}', 0, *args)
+            end
+          _end
+        end
+      end
+      self
+    end
+
+    protected :define_device_attrs
+
+    # Undefine any attributes (i.e. methods) that were previously defined
+    # dynamically.
+    def undefine_device_attrs # :nodoc
+      @device_attrs.each do |dev|
+        instance_eval <<-"_end"
+          class << self
+            remove_method '#{dev}'
+            remove_method '#{dev}='
+          end
+        _end
+      end
+      @device_attrs.clear
+      @devices.clear
+      self
+    end
+
+    protected :undefine_device_attrs
+
+    # Returns +true+ if the current design has a device named +device+.
+    def has_device?(device)
+      @devices.include?(device.to_s)
+    end
+
+    # Provides Hash-like querying for a device named +device+.
+    alias has_key? has_device?
+
+    # call-seq:
+    #   bulkread(register_name) -> Integer
+    #   bulkread(register_name, word_offset) -> Integer
+    #   bulkread(register_name, word_offset, word_count) -> NArray.int(word_count)
+    #
+    # Reads a +word_count+ words starting at +word_offset+ offset from
+    # register (or block RAM) named by +register_name+.  Returns an Integer
+    # unless +word_count+ is given in which case it returns an
+    # NArray.int(word_count).
+    #
+    # Equivalent to #read, but uses a bulkread request rather than a read
+    # request.
+    def bulkread(register_name, *args)
+      byte_offset = 4 * (args[0] || 0)
+      byte_count  = 4 * (args[1] || 1)
+      raise 'word count must be non-negative' if byte_count < 0
+      resp = request(:bulkread, register_name, byte_offset, byte_count)
+      raise resp.to_s unless resp.ok?
+      data = resp.lines[0..-2].map{|l| l[1]}.join
+      if args.length <= 1
+        data.unpack('N')[0]
+      else
+        data.to_na(NArray::INT).ntoh
+      end
+    end
+
     # call-seq:
     #  delbof(image_file) -> KATCP::Response
     #
@@ -48,22 +168,56 @@ module KATCP
     #
     # Programs a gateware image specified by +image_file+.  If +image_file+ is
     # omitted, de-programs the FPGA.
+    #
+    # Whenever the FPGA is programmed, reader and writer attributes (i.e.
+    # methods) are defined for every device listed by #listdev except for
+    # device names that conflict with an already existing method names.
+    #
+    # Whenever the FPGA is de-programmed (or re-programmed), existing
+    # attributes that were dynamically defined for the previous design are
+    # removed.
     def progdev(*args)
       request(:progdev, *args)
+      define_device_attrs
+    end
+
+    # Returns true if currently programmed (specifically, it is equivalent to
+    # <tt>status.ok?</tt>).
+    def programmed?
+      status.ok?
     end
 
     # call-seq:
-    #   read(register_name) -> KATCP::Response
-    #   read(register_name, register_offset) -> KATCP::Response
-    #   read(register_name, register_offset, byte_count) -> KATCP::Response
+    #   read(register_name) -> Integer
+    #   read(register_name, word_offset) -> Integer
+    #   read(register_name, word_offset, word_count) -> NArray.int(word_count)
+    #
+    # Reads one or +word_count+ words starting at +word_offset+ offset from
+    # register (or block RAM) named by +register_name+.  Returns an Integer
+    # unless +word_count+ is given in which case it returns an
+    # NArray.int(word_count).
     #
-    # Reads a +byte_count+ bytes starting at +register_offset+ offset from
-    # register (or block RAM) named by +register_name+.  Binary data can be
-    # obtained from the Response via the Response#payload method.
+    # Note that KATCP::Client#read deals with byte based offsets and counts,
+    # but all reads on the ROACH must be word aligned and an integer number of
+    # words long, so KATCP::RoachClient#read deals with word based offsets and
+    # counts.
     def read(register_name, *args)
-      request(:read, register_name, *args)
+      byte_offset = 4 * (args[0] || 0)
+      byte_count  = 4 * (args[1] || 1)
+      raise 'word count must be non-negative' if byte_count < 0
+      resp = request(:read, register_name, byte_offset, byte_count)
+      raise resp.to_s unless resp.ok?
+      data = resp.payload
+      if args.length <= 1
+        data.unpack('N')[0]
+      else
+        data.to_na(NArray::INT).ntoh
+      end
     end
 
+    alias wordread read
+    alias [] read
+
     # call-seq:
     #  status -> KATCP::Response
     #
@@ -97,7 +251,7 @@ module KATCP
     #
     # Stop a tgtap instance.
     def tap_stop(register_name)
-      reqest(:tap_stop, register_name)
+      request(:tap_stop, register_name)
     end
 
     # call-seq:
@@ -112,30 +266,39 @@ module KATCP
     end
 
     # call-seq:
-    #   wordread(register_name) -> KATCP::Response
-    #   wordread(register_name, word_offset) -> KATCP::Response
-    #   wordread(register_name, word_offset, length) -> KATCP::Response
-    #
-    # Reads word(s) from +register_name+.
-    def wordread(register_name, *args)
-      request(:wordread, register_name, *args)
-    end
-
-    # call-seq:
-    #   wordwrite(register_name, word_offset, payload[, ...]) -> KATCP::Response
+    #   write(register_name, data) -> self
+    #   write(register_name, word_offset, data) -> self
     #
-    # Writes one or more words to a register (or block RAM).
-    def wordwrite(register_name, word_offset, *args)
-      request(:wordwrite, register_name, word_offset, *args)
+    # Write +data+ to +word_offset+ (0 if not given) in register named
+    # +register_name+.  The +data+ argument can be a String containing raw
+    # bytes (byte length must be multiple of 4), NArray.int, Array of integer
+    # values, or other object that responds to #to_i.
+    def write(register_name, *args)
+      word_offset = (args.length > 1) ? args.shift : 0
+      byte_offset = 4 * word_offset
+      args.flatten!
+      args.map! do |a|
+        case a
+        when String; a
+        when NArray; a.hton.to_s
+        when Array; a.pack('N*')
+        else [a.to_i].pack('N*')
+        end
+      end
+      data = args.join
+      byte_count = data.length
+      if byte_count % 4 != 0
+        raise "data length of #{byte_count} bytes is not a multiple of 4 bytes"
+      elsif byte_count == 0
+        warn "writing 0 bytes to #{register_name}"
+      end
+      resp = request(:write, register_name, register_offset, data)
+      raise resp.to_s unless resp.ok?
+      self
     end
 
-    # call-seq:
-    # write(register_name, register_offset, data_payload) -> KATCP::Response
-    #
-    # Write a given payload to an offset in a register.
-    def write(register_name, register_offset, data_payload)
-      request(:write, register_name, register_offset, data_payload)
-    end
+    alias wordwrite write
+    alias []= write
 
   end # class RoachClient
 end # module KATCP

data/lib/katcp/client.rb

@@ -45,7 +45,7 @@ module KATCP
         # "\n".
         while line = @socket.gets("\n") do
           # Split line into words and unescape each word
-          words = line.split.map! {|w| w.katcp_unescape!}
+          words = line.chomp.split(/[ \t]+/).map! {|w| w.katcp_unescape!}
           # Handle requests, replies, and informs based on first character of
           # first word.
           case words[0][0,1]

data/lib/katcp/response.rb

@@ -162,26 +162,13 @@ module KATCP
     end
 
     # call-seq:
-    #   payload -> String or nil
-    #   payload(:to_i) -> Integer or nil
-    #   payload(:unpack, 'N*') -> Array_of_Integers or nil
-    #   payload(:to_na, NArray::INT) -> NArray_of_ints or nil
-    #   etc...
+    #   payload -> String
     #
     # Returns contents of reply line ("words" joined by spaces) after status
-    # word if <tt>ok?</tt> returns true.  Returns +nil+ if <tt>ok?</tt> is
-    # false or no payload exists.  If +args+ are given, they are sent to the
-    # payload String (via String#send) and the results are returned.
-    #
-    # For example, passing <tt>:to_i</tt> will result in conversion of payload
-    # String to Integer via String#to_i.  The String class can be
-    # monkey-patched as needed for additional conversion options.
-    def payload(*args)
-      if ok?
-        s = @lines[-1][2..-1].join(' ')
-        return s if args.empty?
-        s.send(*args)
-      end
+    # word if <tt>ok?</tt> returns true.  Returns an empty string if
+    # <tt>ok?</tt> is false or no payload exists.
+    def payload
+      ok? ? @lines[-1][2..-1].join(' ') : ''
     end
 
     # call-seq:

data/lib/katcp/util.rb

@@ -8,7 +8,7 @@ class String
   def katcp_escape!
     empty? ? self[0..-1] = '\@' : self.gsub!(/[\\ \0\n\r\e\t]/) do |s|
       case s
-      when "\\": '\\'
+      when "\\": '\\\\'
       when " " : '\_'
       when "\0": '\0'
       when "\n": '\n'
@@ -29,7 +29,7 @@ class String
   def katcp_unescape!
     self == '\@' ? self[0..-1] = '' : self.gsub!(/\\[\\_0nret]/) do |s|
       case s
-      when '\\': "\\"
+      when '\\\\': "\\"
       when '\_': " "
       when '\0': "\0"
       when '\n': "\n"
@@ -48,26 +48,10 @@ class String
 
   # call-seq:
   #   to_na(typecode) -> NArray
-  #   to_na(typecode, byteswap) -> NArray
-  #   to_na(typecode,size[, ...]) -> NArray
-  #   to_na(typecode,size[, ...], byteswap) -> NArray
+  #   to_na(typecode, size[, ...]) -> NArray
   #
-  # Convert String to NArray accoring to +typecode+ and call byte swap method
-  # given by Symbol +byteswap+.  Pass +nil+ for +byteswap+ to skip the byte
-  # swap conversion.
-  #
-  # Because, as of this writing, KATCP servers typically run on big endian
-  # systems which return binary payload data in network byte order, the default
-  # +byteswap+ is <tt>:ntoh</tt>, which converts from network byte order to
-  # host (i.e. native) order.
+  # Convert String to NArray accoring to +typecode+.
   def to_na(typecode, *args)
-    # Default to :ntoh
-    byteswap = :ntoh
-    if !args.empty? && (Symbol === args[-1] || args[-1].nil?)
-      byteswap = args.pop
-    end
-    na = NArray.to_na(self, typecode, *args)
-    na = na.send(byteswap) if byteswap
-    na
+    NArray.to_na(self, typecode, *args)
   end
 end

data/lib/katcp/version.rb

@@ -3,5 +3,5 @@
 #++
 
 module KATCP
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - David MacMahon
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-07-20 00:00:00 -07:00
+date: 2010-10-21 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -59,7 +59,7 @@ rdoc_options:
 - -m
 - README
 - --title
-- Ruby/KATCP 0.0.2 Documentation
+- Ruby/KATCP 0.0.3 Documentation
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement