cosmos 3.0.0

data/lib/cosmos/packets/structure.rb

@@ -0,0 +1,386 @@
+# encoding: ascii-8bit
+
+# Copyright 2014 Ball Aerospace & Technologies Corp.
+# All Rights Reserved.
+#
+# This program is free software; you can modify and/or redistribute it
+# under the terms of the GNU Lesser General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+
+require 'cosmos/packets/binary_accessor'
+require 'cosmos/packets/structure_item'
+require 'cosmos/ext/packet'
+
+module Cosmos
+
+  # Maintains knowledge of a raw binary structure. Uses structure_item to
+  # create individual structure items which are read and written by
+  # binary_accessor.
+  class Structure
+
+    # @return [Symbol] Default endianness for items in the structure. One of
+    #   {BinaryAccessor::ENDIANNESS}
+    attr_reader :default_endianness
+
+    # @return [Hash] Items that make up the structure.
+    #   Hash key is the item's name in uppercase
+    attr_reader :items
+
+    # @return [Array] Items sorted by bit_offset.
+    attr_reader :sorted_items
+
+    # @return [Integer] Defined length in bytes (not bits) of the structure
+    attr_reader :defined_length
+
+    # @return [Integer] Defined length in bits of the structure
+    attr_reader :defined_length_bits
+
+    # @return [Boolean] Flag indicating if the structure contains any variably
+    #   sized items or not.
+    attr_reader :fixed_size
+
+    # @return [Boolean] Flag indicating if giving a buffer with less than
+    #   required data size is allowed.
+    attr_accessor :short_buffer_allowed
+
+    # String providing a single 0 byte
+    # ZERO_STRING = "\000"
+    # ZERO_STRING.freeze
+
+    # Structure constructor
+    #
+    # @param default_endianness [Symbol] Must be one of
+    #   {BinaryAccessor::ENDIANNESS}. By default it uses
+    #   BinaryAccessor::HOST_ENDIANNESS to determine the endianness of the host platform.
+    # @param buffer [String] Buffer used to store the structure
+    # @param item_class [Class] Class used to instantiate new structure items.
+    #   Must be StructureItem or one of its subclasses.
+    # def initialize(default_endianness = BinaryAccessor::HOST_ENDIANNESS,
+    #               buffer = '',
+    #               item_class = StructureItem)
+
+    # Indicates if any items have been defined for this structure
+    # @return [TrueClass or FalseClass]
+    def defined?
+      @sorted_items.length > 0
+    end
+
+    # Define an item in the structure. This creates a new instance of the
+    # item_class as given in the constructor and adds it to the items hash. It
+    # also resizes the buffer to accomodate the new item.
+    #
+    # @param name [String] Name of the item. Used by the items hash to retrieve
+    #   the item.
+    # @param bit_offset [Integer] Bit offset of the item in the raw buffer
+    # @param bit_size [Integer] Bit size of the item in the raw buffer
+    # @param data_type [Symbol] Type of data contained by the item. This is
+    #   dependant on the item_class but by default see StructureItem.
+    # @param array_size [Integer] Set to a non nil value if the item is to
+    #   represented as an array.
+    # @param endianness [Symbol] Endianness of this item. By default the
+    #   endianness as set in the constructure is used.
+    # @param overflow [Symbol] How to handle value overflows. This is
+    #   dependant on the item_class but by default see StructureItem.
+    # @return [StrutureItem] The struture item defined
+    def define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
+      # Handle case-insensitive naming
+      name_upcase = name.upcase
+
+      # Create the item
+      item = @item_class.new(name_upcase, bit_offset, bit_size, data_type, endianness, array_size, overflow)
+
+      # Handle Overwriting Existing Item
+      if @items[name_upcase]
+        item_index = nil
+        @sorted_items.each_with_index do |sorted_item, index|
+          if sorted_item.name == name_upcase
+            item_index = index
+            break
+          end
+        end
+        @sorted_items.delete_at(item_index) if item_index < @sorted_items.length
+      end
+
+      # Add to Sorted Items
+      unless @sorted_items.empty?
+        last_item = @sorted_items[-1]
+        @sorted_items << item
+        # If the current item or last item have a negative offset then we have
+        # to re-sort. We also re-sort if the current item is less than the less
+        # item because we are inserting.
+        if last_item.bit_offset <= 0 or item.bit_offset <= 0 or item.bit_offset < last_item.bit_offset
+          @sorted_items = @sorted_items.sort {|item1, item2| item1 <=> item2}
+        end
+      else
+        @sorted_items << item
+      end
+
+      # Add to the overall hash of defined items
+      @items[name_upcase] = item
+      # Update fixed size knowledge
+      @fixed_size = false if ((data_type != :DERIVED and bit_size <= 0) or (array_size and array_size <= 0))
+
+      # Recalculate the overall defined length of the structure
+      update_needed = false
+      if item.bit_offset >= 0
+        if item.bit_size > 0
+          if item.array_size
+            if item.array_size >= 0
+              item_defined_length_bits = item.bit_offset + item.array_size
+            else
+              item_defined_length_bits = item.bit_offset
+            end
+          else
+            item_defined_length_bits = item.bit_offset + item.bit_size
+          end
+          if item_defined_length_bits > @pos_bit_size
+            @pos_bit_size = item_defined_length_bits
+            update_needed = true
+          end
+        else
+          if item.bit_offset > @pos_bit_size
+            @pos_bit_size = item.bit_offset
+            update_needed = true
+          end
+        end
+      else
+        if item.bit_offset.abs > @neg_bit_size
+          @neg_bit_size = item.bit_offset.abs
+          update_needed = true
+        end
+      end
+      if update_needed
+        @defined_length_bits = @pos_bit_size + @neg_bit_size
+        @defined_length = @defined_length_bits / 8
+        @defined_length += 1 if @defined_length_bits % 8 != 0
+      end
+
+      # Resize the buffer if necessary
+      resize_buffer() if @buffer
+
+      return item
+    end
+
+    # Define an item at the end of the structure. This creates a new instance of the
+    # item_class as given in the constructor and adds it to the items hash. It
+    # also resizes the buffer to accomodate the new item.
+    #
+    # @param name (see #define_item)
+    # @param bit_size (see #define_item)
+    # @param data_type (see #define_item)
+    # @param array_size (see #define_item)
+    # @param endianness (see #define_item)
+    # @param overflow (see #define_item)
+    # @return (see #define_item)
+    def append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
+      raise ArgumentError, "Can't append an item after a variably sized item" if !@fixed_size
+      return define_item(name, @defined_length_bits, bit_size, data_type, array_size, endianness, overflow)
+    end
+
+    # @param name [String] Name of the item to look up in the items Hash
+    # @return [StructureItem] StructureItem or one of its subclasses
+    def get_item(name)
+      item = @items[name.upcase]
+      raise ArgumentError, "Unknown item: #{name}" unless item
+      return item
+    end
+
+    # @param item [#name] Instance of StructureItem or one of its subclasses.
+    #   The name method will be used to look up the item and set it to the new instance.
+    def set_item(item)
+      if @items[item.name]
+        @items[item.name] = item
+      else
+        raise ArgumentError, "Unknown item: #{item.name} - Ensure item name is uppercase"
+      end
+    end
+
+    # Read an item in the structure
+    #
+    # @param item [StructureItem] Instance of StructureItem or one of its subclasses
+    # @param value_type [Symbol] Not used. Subclasses should overload this
+    #   parameter to check whether to perform conversions on the item.
+    # @param buffer [String] The binary buffer to read the item from
+    # @return Value based on the item definition. This could be a string, integer,
+    #   float, or array of values.
+    # def read_item(item, value_type = :RAW, buffer = @buffer)
+
+    # Write a value to the buffer based on the item definition
+    #
+    # @param item [StructureItem] Instance of StructureItem or one of its subclasses
+    # @param value [Object] Value based on the item definition. This could be
+    #   a string, integer, float, or array of values.
+    # @param value_type [Symbol] Not used. Subclasses should overload this
+    #   parameter to check whether to perform conversions on the item.
+    # @param buffer [String] The binary buffer to write the value to
+    def write_item(item, value, value_type = :RAW, buffer = @buffer)
+      if buffer
+        if item.array_size
+          BinaryAccessor.write_array(value, item.bit_offset, item.bit_size, item.data_type, item.array_size, buffer, item.endianness, item.overflow)
+        else
+          BinaryAccessor.write(value, item.bit_offset, item.bit_size, item.data_type, buffer, item.endianness, item.overflow)
+        end
+      else
+        raise "No buffer given to write_item"
+      end
+    end
+
+    # Read an item in the structure by name
+    #
+    # @param name [String] Name of an item to read
+    # @param value_type [Symbol] Not used. Subclasses should overload this
+    #   parameter to check whether to perform conversions on the item.
+    # @param buffer [String] The binary buffer to read the item from
+    # @return Value based on the item definition. This could be an integer,
+    #   float, or array of values.
+    def read(name, value_type = :RAW, buffer = @buffer)
+      return read_item(get_item(name), value_type, buffer)
+    end
+
+    # Write an item in the structure by name
+    #
+    # @param name [Object] Name of the item to write
+    # @param value [Object] Value based on the item definition. This could be
+    #   a string, integer, float, or array of values.
+    # @param value_type [Symbol] Not used. Subclasses should overload this
+    #   parameter to check whether to perform conversions on the item.
+    # @param buffer [String] The binary buffer to write the value to
+    def write(name, value, value_type = :RAW, buffer = @buffer)
+      write_item(get_item(name), value, value_type, buffer)
+    end
+
+    # Read all items in the structure into an array of arrays
+    #   [[item name, item value], ...]
+    #
+    # @param value_type [Symbol] Not used. Subclasses should overload this
+    #   parameter to check whether to perform conversions on the item.
+    # @param buffer [String] The binary buffer to write the value to
+    # @return [Array<Array>] Array of two element arrays containing the item
+    #   name as element 0 and item value as element 1.
+    def read_all(value_type = :RAW, buffer = @buffer)
+      item_array = []
+      @sorted_items.each {|item| item_array << [item.name, read_item(item, value_type, buffer)]}
+      return item_array
+    end
+
+    # Create a string that shows the name and value of each item in the structure
+    #
+    # @param value_type [Symbol] Not used. Subclasses should overload this
+    #   parameter to check whether to perform conversions on the item.
+    # @param indent [Integer] Amount to indent before printing the item name
+    # @param buffer [String] The binary buffer to write the value to
+    # @return [String] String formatted with all the item names and values
+    def formatted(value_type = :RAW, indent = 0, buffer = @buffer)
+      indent_string = ' ' * indent
+      string = ''
+      @sorted_items.each do |item|
+        if item.data_type != :BLOCK
+          string << "#{indent_string}#{item.name}: #{read_item(item, value_type, buffer)}\n"
+        else
+          value = read_item(item, value_type, buffer)
+          if String === value
+            string << "#{indent_string}#{item.name}:\n"
+            string << value.formatted(1, 16, ' ', indent + 2)
+          else
+            string << "#{indent_string}#{item.name}: #{value}\n"
+          end
+        end
+      end
+      return string
+    end
+
+    # Get the length of the buffer used by the structure
+    #
+    # @return [Integer] Size of the buffer in bytes
+    # def length
+
+    # Get the buffer used by the structure. The current buffer is copied and
+    # thus modifications to the returned buffer will have no effect on the
+    # structure items.
+    #
+    # @param copy [TrueClass/FalseClass] Whether to copy the buffer
+    # @return [String] Data buffer backing the structure
+    def buffer(copy = true)
+      if @buffer
+        if copy
+          return @buffer.dup
+        else
+          return @buffer
+        end
+      else
+        return nil
+      end
+    end
+
+    # Set the buffer to be used by the structure. The buffer is copied and thus
+    # further modifications to the buffer have no effect on the structure
+    # items.
+    #
+    # @param buffer [String] Buffer of data to back the stucture items
+    def buffer=(buffer)
+      synchronize() do
+        internal_buffer_equals(buffer)
+      end
+    end
+
+    # Take the structure mutex to ensure the buffer does not change while you perform activities
+    def synchronize
+      @mutex ||= Mutex.new
+      @mutex.synchronize {|| yield }
+    end
+
+    # Make a light weight clone of this structure. This only creates a new buffer
+    # of data. The defined structure items are the same.
+    #
+    # @return [Structure] A copy of the current structure with a new underlying
+    #   buffer of data
+    def clone
+      structure = super()
+      @buffer = @buffer.clone if @buffer # Deep Copy @buffer
+      return structure
+    end
+    alias dup clone
+
+    def enable_method_missing
+      extend(MethodMissing)
+    end
+
+    protected
+
+    module MethodMissing
+      # Method missing provides reading/writing item values as if they were methods to the class
+      def method_missing(name, value = nil)
+        if @buffer
+          if value
+            # Strip off the equals sign before looking up the item
+            return write(name.to_s[0..-2], value)
+          else
+            return read(name.to_s)
+          end
+        else
+          raise "No buffer available for method_missing"
+        end
+      end
+    end
+
+    # Resize the buffer at least the defined length of the structure
+    # def resize_buffer
+
+    def internal_buffer_equals(buffer)
+      raise ArgumentError, "Buffer class is #{buffer.class} but must be String" unless String === buffer
+      @buffer = buffer.dup
+      @buffer.force_encoding('ASCII-8BIT')
+      if @buffer.length != @defined_length
+        if @buffer.length < @defined_length
+          resize_buffer()
+          raise "Buffer length less than defined length" unless @short_buffer_allowed
+        elsif @fixed_size and @defined_length != 0
+          raise "Buffer length greater than defined length"
+        end
+      end
+    end
+
+  end # class Structure
+
+end # module Cosmos

data/lib/cosmos/packets/structure_item.rb

@@ -0,0 +1,233 @@
+# encoding: ascii-8bit
+
+# Copyright 2014 Ball Aerospace & Technologies Corp.
+# All Rights Reserved.
+#
+# This program is free software; you can modify and/or redistribute it
+# under the terms of the GNU Lesser General Public License
+# as published by the Free Software Foundation; version 3 with
+# attribution addendums as found in the LICENSE.txt
+
+require 'cosmos/ext/packet'
+
+module Cosmos
+
+  # Maintains knowledge of an item in a Structure. Multiple StructureItems
+  # compose a Structure.
+  class StructureItem
+    include Comparable
+
+    # Valid data types adds :DERIVED to those defined by BinaryAccessor
+    DATA_TYPES = BinaryAccessor::DATA_TYPES << :DERIVED
+
+    # Name is used by higher level classes to access the StructureItem.
+    # @return [String] Name of the item
+    attr_reader :name
+
+    # Indicates where in the binary buffer the StructureItem exists.
+    # @return [Integer] 0 based bit offset
+    attr_reader :bit_offset
+
+    # The number of bits which represent this StructureItem in the binary buffer.
+    # @return [Integer] Size in bits
+    attr_reader :bit_size
+
+    # The data type is what kind of data this StructureItem
+    # represents when extracted from the binary buffer. :INT and :UINT are
+    # turned into Integers (Ruby Fixnum). :FLOAT are turned into floating point
+    # numbers (Ruby Float). :STRING is turned into an ASCII string (Ruby
+    # String). :BLOCK is turned into a binary buffer (Ruby String). :DERIVED is
+    # interpreted by the subclass and can result in any type.
+    # @return [Symbol] {DATA_TYPES}
+    attr_reader :data_type
+
+    # Used to interpret how to read the item from the binary data buffer.
+    # @return [Symbol] {BinaryAccessor::ENDIANNESS}
+    attr_reader :endianness
+
+    # The total number of bits in the binary buffer that create the array.
+    # The array size can be set to nil to indicate the StructureItem is
+    # not represented as an array. For example, if the bit_size is 8 bits,
+    # an array_size of 16 would result in two 8 bit items.
+    # @return [Integer, nil] Array size of the item in bits
+    attr_reader :array_size
+
+    # How to handle overflow for :INT, :UINT, :STRING, and :BLOCK data types
+    # Note: Has no meaning for :FLOAT data types
+    # @return [Symbol] {BinaryAccessor::OVERFLOW_TYPES}
+    attr_reader :overflow
+
+    # A large buffer size in bits (1 Megabyte)
+    LARGE_BUFFER_SIZE_BITS = 1024 * 1024 * 8
+
+    # Create a StructureItem by setting all the attributes. It
+    # calls all the setter routines to do the attribute verification and then
+    # verifies the overall integrity.
+    #
+    # @param name [String] The item name
+    # @param bit_offset [Integer] Offset to the item starting at 0
+    # @param bit_size [Integer] Size of the items in bits
+    # @param data_type [Symbol] {DATA_TYPES}
+    # @param endianness [Symbol] {BinaryAccessor::ENDIANNESS}
+    # @param array_size [Integer, nil] Size of the array item in bits. For
+    #   example, if the bit_size is 8, an array_size of 16 holds two values.
+    def initialize(name, bit_offset, bit_size, data_type, endianness, array_size = nil, overflow = :ERROR)
+      @structure_item_constructed = false
+      # Assignment order matters due to verifications!
+      self.name = name
+      self.endianness = endianness
+      self.data_type = data_type
+      self.bit_offset = bit_offset
+      self.bit_size = bit_size
+      self.array_size = array_size
+      self.overflow = overflow
+      @structure_item_constructed = true
+      verify_overall()
+    end
+
+    def name=(name)
+      raise ArgumentError, "name must be a String but is a #{name.class}" unless String === name
+      raise ArgumentError, "name must contain at least one character" if name.empty?
+
+      @name = name.clone.freeze
+      verify_overall() if @structure_item_constructed
+    end
+
+    def endianness=(endianness)
+      raise ArgumentError, "#{@name}: endianness must be a Symbol" unless Symbol === endianness
+      unless BinaryAccessor::ENDIANNESS.include? endianness
+        raise ArgumentError, "#{@name}: unknown endianness: #{endianness} - Must be :BIG_ENDIAN or :LITTLE_ENDIAN"
+      end
+
+      @endianness = endianness
+      verify_overall() if @structure_item_constructed
+    end
+
+    def bit_offset=(bit_offset)
+      raise ArgumentError, "#{@name}: bit_offset must be a Fixnum" unless Fixnum === bit_offset
+      byte_aligned = ((bit_offset % 8) == 0)
+      if (@data_type == :FLOAT or @data_type == :STRING or @data_type == :BLOCK) and !byte_aligned
+        raise ArgumentError, "#{@name}: bit_offset for :FLOAT, :STRING, and :BLOCK items must be byte aligned"
+      end
+      if @data_type == :DERIVED and bit_offset != 0
+        raise ArgumentError, "#{@name}: DERIVED items must have bit_offset of zero"
+      end
+
+      @bit_offset = bit_offset
+      verify_overall() if @structure_item_constructed
+    end
+
+    def bit_size=(bit_size)
+      raise ArgumentError, "#{name}: bit_size must be a Fixnum" unless Fixnum === bit_size
+      byte_multiple = ((bit_size % 8) == 0)
+      if bit_size <= 0 and (@data_type == :INT or @data_type == :UINT or @data_type == :FLOAT)
+        raise ArgumentError, "#{@name}: bit_size cannot be negative or zero for :INT, :UINT, and :FLOAT items: #{bit_size}"
+      end
+      raise ArgumentError, "#{@name}: bit_size for STRING and BLOCK items must be byte multiples" if (@data_type == :STRING or @data_type == :BLOCK) and !byte_multiple
+      if @data_type == :FLOAT and bit_size != 32 and bit_size != 64
+        raise ArgumentError, "#{@name}: bit_size for FLOAT items must be 32 or 64. Given: #{bit_size}"
+      end
+      if @data_type == :DERIVED and bit_size != 0
+        raise ArgumentError, "#{@name}: DERIVED items must have bit_size of zero"
+      end
+
+      @bit_size = bit_size
+      verify_overall() if @structure_item_constructed
+    end
+
+    def data_type=(data_type)
+      raise ArgumentError, "#{@name}: data_type must be a Symbol" unless Symbol === data_type
+      case data_type
+      when *DATA_TYPES
+        # Valid data_type
+      else
+        raise ArgumentError, "#{@name}: unknown data_type: #{data_type} - Must be :INT, :UINT, :FLOAT, :STRING, :BLOCK, or :DERIVED"
+      end
+
+      @data_type = data_type
+      verify_overall() if @structure_item_constructed
+    end
+
+    def array_size=(array_size)
+      if array_size
+        raise ArgumentError, "#{@name}: array_size must be a Fixnum" unless Fixnum === array_size
+        raise ArgumentError, "#{@name}: array_size must be a multiple of bit_size" unless (@bit_size == 0 or (array_size % @bit_size == 0) or array_size < 0)
+        raise ArgumentError, "#{@name}: bit_size cannot be negative or zero for array items" if @bit_size <= 0
+      end
+      @array_size = array_size
+      verify_overall() if @structure_item_constructed
+    end
+
+    def overflow=(overflow)
+      raise ArgumentError, "#{@name}: overflow type must be a Symbol" unless Symbol === overflow
+      case overflow
+      when *BinaryAccessor::OVERFLOW_TYPES
+        # Valid overflow
+      else
+        raise ArgumentError, "#{@name}: unknown overflow type: #{overflow} - Must be :ERROR, :ERROR_ALLOW_HEX, :TRUNCATE, or :SATURATE"
+      end
+
+      @overflow = overflow
+      verify_overall() if @structure_item_constructed
+    end
+
+    # Comparison Operator based on bit_offset. This means that StructureItems
+    # with different names or bit sizes are equal if they have the same bit
+    # offset.
+    # def <=>(other_item)
+
+    # Make a light weight clone of this item
+    def clone
+      item = super()
+      item.name = self.name.clone if self.name
+      item
+    end
+    alias dup clone
+
+    def to_hash
+      hash = {}
+      hash['name'] = self.name
+      hash['bit_offset'] = self.bit_offset
+      hash['bit_size'] = self.bit_size
+      hash['data_type'] = self.data_type
+      hash['endianness'] = self.endianness
+      hash['array_size'] = self.array_size
+      hash['overflow'] = self.overflow
+      hash
+    end
+
+    protected
+
+    # Verifies overall integrity of the StructureItem by checking for correct
+    # LITTLE_ENDIAN bit fields
+    def verify_overall
+      # Verify negative bit_offset conditions
+      if @bit_offset < 0
+        raise ArgumentError, "#{@name}: Can't define an item with negative bit_size #{@bit_size} and negative bit_offset #{@bit_offset}" if @bit_size < 0
+        raise ArgumentError, "#{@name}: Can't define an item with negative array_size #{@array_size} and negative bit_offset #{@bit_offset}" if @array_size and @array_size < 0
+        if @array_size and @array_size > @bit_offset.abs
+          raise ArgumentError, "#{@name}: Can't define an item with array_size #{@array_size} greater than negative bit_offset #{@bit_offset}"
+        elsif @bit_size > @bit_offset.abs
+          raise ArgumentError, "#{@name}: Can't define an item with bit_size #{@bit_size} greater than negative bit_offset #{@bit_offset}"
+        end
+      else
+        # Check for byte alignment and byte multiple
+        byte_aligned = ((@bit_offset % 8) == 0)
+
+        # Verify little-endian bit fields
+        if @endianness == :LITTLE_ENDIAN and (@data_type == :INT or @data_type == :UINT) and !(byte_aligned and (@bit_size == 8 or @bit_size == 16 or @bit_size == 32 or @bit_size == 64))
+          # Bitoffset always refers to the most significant bit of a bitfield
+          num_bytes = (((@bit_offset % 8) + @bit_size - 1) / 8) + 1
+          upper_bound = @bit_offset / 8
+          lower_bound = upper_bound - num_bytes + 1
+
+          if lower_bound < 0
+            raise ArgumentError, "#{@name}: LITTLE_ENDIAN bitfield with bit_offset #{@bit_offset} and bit_size #{@bit_size} is invalid"
+          end
+        end
+      end
+    end
+
+  end # class StructureItem
+
+end # module Cosmos