ipxact-tools 0.2.0

data/config/detector.yml

@@ -0,0 +1,63 @@
+---
+:bus_name_regex:
+  - 
+    - /INT_/i
+    - 0.7
+  -
+    - /INT/i
+    - 0.5
+  -
+    - /INTERRUPT/i
+    - 0.8
+  -
+    - /IRQ/i
+    - 0.8
+  -
+    - /FIQ/i
+    - 0.4
+  -
+    - /IRL_/i
+    - 0.4
+  -
+    - /IRL/i
+    - 0.3
+
+:bus_library_regex:
+  - 
+    - /INT_/i
+    - 0.7
+  -
+    - /INT/i
+    - 0.5
+  -
+    - /INTERRUPT/i
+    - 0.8
+  -
+    - /IRQ/i
+    - 0.8
+  -
+    - /FIQ/i
+    - 0.4
+  -
+    - /IRL_/i
+    - 0.4
+  -
+    - /IRL/i
+    - 0.3
+
+:transition_matrix:
+  :not_int:
+    :not_int: 0.958904109589041
+    :int:     0.0410958904109589
+  :int:
+    :not_int: 0.5333333333333333
+    :int:     0.4666666666666667
+
+:initial_state:
+  :not_int:   0.5042735042735043
+  :int:       0.49572649572649574
+
+:states:
+  - :not_int
+  - :int
+

data/lib/ipxact_tools.rb

@@ -0,0 +1,287 @@
+# Copyright (C) 2011 TIMA Laboratory
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+require 'ipxact'
+
+# The {IPXACT::Tools} module provides analysis tools for extracting or
+# deducing relevant data from IP-Xact platforms. Three functionality are
+# currently handled by the module:
+# - It computes the shortest path between two component instances of a
+#   valid {IPXACT::Platform} instance.
+# - It validates the data path by verifying that it does not contain any
+#   interrupt line, and emits a warning if several CPUs may contend for
+#   an access to the target component.
+# - It deduces the target component's base address from the data path
+#   (handling all address remaps and IP-Xact variables).
+#
+# Because the IP-Xact standard does not include (yet) any formal way to
+# distinguish interrupt lines from other communication channels, we try
+# to identify those interrupt lines based on the different terms used
+# for describing them. As a result, if the platform uses standard
+# conventions for naming the interrupt line elements (esp. ports), such
+# as 'INT_xxx', 'INTERRUPT_xxx', 'IRQ', 'IRL' etc., there is a high
+# probability that our algorithm will be able to detect it.
+#
+# *NOTE* Unfortunately, there is currently no way to select an alternate
+# data path if the one provided by the pathfinding algorithm happens to
+# be invalid. If this is a strong requirement, drop me a mail (guillaume
+# dot godetbar at gmail dot com) and I will
+# try to include it ASAP.
+#
+# @author Guillaume Godet-Bar
+#
+module IPXACT
+  module Tools
+
+    # A simple structure for handling diagnosis messages.
+    #
+    class ValidationMessage < Struct.new(:reason, :cause_element)
+      def initialize(hash)
+        entry = hash.entries[0]
+        self.reason = entry[0]
+        self.cause_element = entry[1]
+      end
+    end
+
+    # Structure for handling validation errors.
+    #
+    class ValidationError < ValidationMessage ; end
+
+    # Structure for handling warning messages.
+    #
+    class ValidationWarning < ValidationMessage ; end
+
+    # Commodity class for handling errors and warnings produced by
+    # the {#validate_data_path method}.
+    #
+    class Diagnosis < Struct.new(:errors, :warnings)
+      def initialize
+        super
+        self.errors = []
+        self.warnings = []
+      end
+    end
+
+    # Validates the given data path. In particular, the method verifies
+    # that no interrupt line is present in the data path.
+    #
+    # @param [IPXACT::Platform] platform The reference platform
+    # @param [Array]            data_path The data path to validate
+    #
+    # @return [Array<IPXACT::Tools::ValidationMessage>] a list of errors
+    #   of errors and warnings, or an empty list if the data path is
+    #   valid.
+    #
+    def self.validate_data_path(platform, data_path)
+      diagnosis = Diagnosis.new
+      path_ports = data_path.collect do |el|
+        platform.rec_get_subcomponent(el[0][:component_instance]).ports.select{|p|
+          p[:name] == el[0][:port_name]
+        }.first
+      end
+
+      if path_ports.first[:type] == :master
+
+        # Interrupt line detection
+        detector = IPXACT::Tools::InterruptLineDetector.new
+        stack = detector.viterbi(path_ports)
+        rendered_stack = detector.render_seq(stack)
+
+        interrupt_line_index = rendered_stack.find_index{|el| el == :int}
+        unless interrupt_line_index.nil?
+          diagnosis.errors << ValidationError.new(:probable_interrupt_line => data_path[interrupt_line_index])
+        end
+
+        # Concurrent access check
+        target_component_name = data_path.last[1][:component_instance]
+        target_component = platform.rec_get_subcomponent(target_component_name)
+        components = platform.rec_get_subcomponents.reject{|el| el == target_component}
+
+        cpu_instances = []
+        components.each do |instance_name, component|
+          if component.has_cpu?
+            cpu_instances << instance_name
+          end
+        end
+
+        if cpu_instances.size >= 2
+          diagnosis.warnings << ValidationWarning.new(:cpu_nb_causes_concurrent_access_risk => cpu_instances)
+        end
+      else
+        diagnosis.errors << ValidationError.new(:first_element_not_a_master => data_path.first)
+      end
+
+      return diagnosis
+    end
+
+    # Calculates an optimal path in the subcomponent graph between
+    # +subcomponent_start+ and +subcomponent_end+. This computation takes into
+    # account hierarchical subcomponents, and identifies optimal sub-paths in
+    # these elements as well, using hierconnections. This method is in fact the
+    # facade for the {IPXACT::GraphPathFinder} class. It handles the creation of
+    # the connection Hash, and translates the result in a IPXACT-specific format.
+    #
+    # @param [IPXACT::Platform] platform The reference platform
+    # @param [String] subcomponent_start The name of the component instance that
+    #                 should be the source of the data path.
+    # @param [String] subcomponent_end The name of the component instance that
+    #                 should be the target of the data path.
+    #
+    # @return [Array<Array<Hash>>] an Array of Arrays of Hashes that summarizes
+    #   the component instances and the ports on the data path. Note that this
+    #   data path may be used for calculating the target component's base
+    #   address. The Arrays of Hashes are composed of 2 elements, the first
+    #   element being the source of a connection step and the second element
+    #   being the target of the connection step. Each element is a Hash, built as
+    #   follows:
+    #   +:component_instance+ the String name of the component instance that is
+    #   traversed by the data path;
+    #   +:port_name+ the String name of the port of the component instance that
+    #   is being traversed.
+    # @raise several exceptions. Please refer to {IPXACT::GraphPathFinder} class
+    #   for more details.
+    #
+    def self.resolve_data_path(platform, subcomponent_start, subcomponent_end)
+      nodes, connections = prepare_pathfinder_connections(platform)
+
+      pathfinder_connections = connections.collect do |connection|
+        {
+          :link => [nodes.index(connection[0][:component_instance]),
+                    nodes.index(connection[1][:component_instance])],
+          :ports => [connection[0][:port_name], connection[1][:port_name]]
+        }
+      end
+
+      pathfinder_interconnect = {:nodes => nodes, :connections => pathfinder_connections}
+      pathfinder = IPXACT::Tools::GraphPathFinder.new(pathfinder_interconnect)
+      finder_result = pathfinder.resolve(subcomponent_start, subcomponent_end)
+
+      formatted_result = finder_result.collect do |res|
+        pathfinder_interconnect[:connections][res]
+      end.collect do |connection|
+        [
+          {
+            :component_instance => pathfinder_interconnect[:nodes][connection[:link][0]],
+            :port_name => connection[:ports][0]
+          },
+          {
+            :component_instance => pathfinder_interconnect[:nodes][connection[:link][1]],
+            :port_name => connection[:ports][1]
+          }
+        ]
+      end
+    end
+
+
+    # Computes a the base address of the last component instance mentionned in
+    # the +data_path+. The latter should be calculated using the
+    # {#resolve_data_path} method. Additionally, this method takes into account
+    # all subcomponents from the +data_path+, and basically adds up mirrored slave
+    # ports' remap addresses.
+    #
+    # @param [IPXACT::Platform] platform The reference platform
+    # @param [Arrray] data_path the data path from which the base address should be
+    #                 calculated. Please refer to the documentation of
+    #                 {#resolve_data_path} for more details on the structure of
+    #                 this argument.
+    # @param [Integer] initial_value the value that should be added to the base
+    #                 address computed by the method.
+    #
+    # Returns the base address of the target component, as an Integer.
+    #
+    def self.resolve_base_address(platform, data_path, initial_value = 0)
+      base_address = initial_value
+      data_path.each do |connection|
+        connection.each do |connection_step|
+          subcomponent = platform.rec_get_subcomponent(connection_step[:component_instance])
+          port = subcomponent.ports \
+                    .select{|port| port[:name] == connection_step[:port_name]} \
+                    .first
+          if port[:type] == :mirrored_slave && !port[:port_data].nil?
+            base_address += port[:port_data][:remap][:address].to_i(16)
+          end
+        end
+      end
+      base_address
+    end
+
+private
+
+    # Executes the actual replacement of an hierarchical component's outside port
+    # with the attached subcomponent port.
+    #
+    # @param [IPXACT::Platform] platform The reference platform
+    # @param [Hash] connector The connector on which the
+    #                         replacement should be performed.
+    # @return [Hash] the flattened connector, i.e., a Hash built as follows:
+    #   +:component_instance+ the String name of the component instance that is
+    #   traversed by the data path;
+    #   +:port_name+ the String name of the port of the component
+    #   instance that is being traversed.
+    #
+    def self.reformat_connector(platform, connector)
+      instance = platform.subcomponents[connector[:component_instance]]
+      if instance.subcomponents.empty?
+        new_connector = connector
+      else
+        port = connector[:port_name]
+        new_connector = instance.hierconnections[port]
+      end
+      new_connector
+    end
+
+
+    # Prepares the connection structure for the {IPXACT::GraphPathFinder} class.
+    # Traverses the hierarchy of subcomponents in order to create a flattened
+    # representation of the subcomponents graph. In particular, the method
+    # considers hierconnections, and replaces the wrapper's interface port with
+    # the subcomponent's port that it is attached to.
+    #
+    # @param [IPXACT::Component] component root component from which to
+    #                                      to start the formatting.
+    # 
+    # @return [Array<Array,Array<Hash>>] an Array of 2 elements, composed of a
+    #   list of nodes and a list of connections. Please refer to the
+    #   {IPXACT::Tools::GraphPathFinder#initialize} method for more details on
+    #   the structure of these elements (both Hashes).
+    #
+    def self.prepare_pathfinder_connections(component)
+      rec_prepare_pathfinder_connections(component, [], [])
+    end
+
+    # Recursive function for {#prepare_pathfinder_connections}.
+    #
+    def self.rec_prepare_pathfinder_connections(component, current_nodes, current_interconnections)
+      if component.subcomponents.empty?
+        [current_nodes << component.instance_name, current_interconnections]
+      else
+        component.subcomponents.each do |sub_name, subcomponent|
+          formatted_interconnections = component.interconnections.values.collect do |interconnect|
+            [reformat_connector(component, interconnect[0]), reformat_connector(component, interconnect[1])]
+          end
+          current_nodes, current_interconnections = \
+            rec_prepare_pathfinder_connections(subcomponent, current_nodes,
+                                                            current_interconnections + 
+                                                              formatted_interconnections)
+        end
+        [current_nodes, current_interconnections]
+      end
+    end
+  end
+end
+
+require File.join File.dirname(__FILE__), 'ipxact_tools/graph_pathfinder'
+require File.join File.dirname(__FILE__), 'ipxact_tools/interrupt_line_detector'

data/lib/ipxact_tools/graph_pathfinder.rb

@@ -0,0 +1,191 @@
+# Copyright (C) 2010 TIMA Laboratory
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+# {IPXACT::Tools::GraphPathFinder} instances handle graph-based
+# pathfinding requests within a given IPXACT architecture. It is
+# responsible for translating the IPXACT architecture into a list of
+# connections and transition weights, which may then be queried for
+# optimal paths between two nodes from the connection graph. As such,
+# even though the path finder is pretty generic, it should not be used
+# directly for IPXACT-related work.
+#
+# @example
+#   @pathfinder = IPXACT::Tools::GraphPathFinder.new({
+#     :nodes => ['component_a', 'component_b', 'component_c']
+#     :connections =>
+#       [
+#         {:link => [0,1]},
+#         {:link => [1,2], :cost => 2},
+#         {:link => [2,0]}
+#       ]
+#   })
+#   @data_path = @pathfinder.resolve('component_a', 'component_b')
+#
+# @author Guillaume Godet-Bar
+#
+class IPXACT::Tools::GraphPathFinder
+
+  # The initializer is essentially used for passing a structured connection
+  # Hash.
+  #
+  # @param [Hash] hash the connection Hash, which should be structured as follows:
+  #
+  #         :nodes        - An Array of node names (String).
+  #
+  #         :connections  - An Array of connection elements, which are defined as
+  #                         :link - A 2-element Array, which describes an oriented
+  #                                 connection between two nodes. The nodes are
+  #                                 expressed using their index in the :nodes
+  #                                 Array.
+  #                         :cost - A positive Integer expressing the cost of
+  #                                 the transition (in the sense of a
+  #                                 Branch-And-Bound algorithm) (optional,
+  #                                 default: 1).
+  #
+  def initialize(hash)
+    @hash = hash
+  end
+
+  # Searches an optimal path between the start and _end elements, which
+  # should be defined in the Hash structured used for instanciating the
+  # {IPXACT::GraphPathFinder} instance. Optimal should be understood as "the
+  # cheapest path given the cost of each connection". Additionally, validates
+  # the latter Hash structure before executing the search algorithm.
+  #
+  # @param [String] start a String that corresponds to an element that was
+  #         registered when the pathfinder was created. The latter will be used
+  #         as the start node by the pathfinder algorithm.
+  # @param [String] _end a String that corresponds to an element that was
+  #         registered when the pathfinder was created. The latter will be used
+  #         as the target node by the pathfinder algorithm.
+  #
+  # @return [Array<Integer>] an Array of Integers corresponding to connection
+  #   indices for the optimal data path between the +start+ and +_end+
+  #   elements, or an empty Array if the +start+ and +_end+ elements are
+  #   identical.
+  # 
+  # @raise an exception if the Hash structure for the connections is empty.
+  # @raise an exception unless all the node names are unique.
+  # @raise an exception if the start or end element does not exist.
+  # @raise an exception if no optimal data path could be found.
+  #
+  def resolve(start, _end)
+    raise "Empty connection table!" if @hash.empty?
+    return [] if start == _end
+    raise "Duplicate connection node found!" if @hash[:nodes].uniq.size != @hash[:nodes].size
+    raise "The source or target node does not exist!" unless @hash[:nodes].include?(start) && @hash[:nodes].include?(_end)
+
+    @interconnect_table = (0..@hash[:nodes].size - 1).collect do |i|
+      (0..@hash[:nodes].size - 1).collect do |j|
+        result_hash = { 
+          :connection =>
+            @hash[:connections].any?{|connection| connection[:link] == [j,i]},
+          :total => Float::INFINITY,
+          :previous => nil
+        }
+        if @hash[:connections].any?{|connection| connection[:link] == [j,i]}
+          result = @hash[:connections].select{|connection| connection[:link] == [j,i]}.first[:cost] || 1
+          result_hash.merge!({:cost => result})
+        end
+
+        result_hash
+      end
+    end
+
+    start_index = @hash[:nodes].index(start)
+    end_index = @hash[:nodes].index(_end)
+    @interconnect_table[start_index][start_index][:total] = 0
+
+
+    rec_resolve([start_index, start_index], end_index, 0)
+
+    last_writer_index = nil
+    @interconnect_table[end_index].each_with_index do |el, i|
+      last_writer_index = i if el[:total] < Float::INFINITY
+    end
+    raise "Destination could not be reached!" if last_writer_index.nil?
+    
+    
+    dump_trajectory(end_index).reverse
+
+  end
+
+private
+
+  # Recursive function for the pathfinder search algorithm.
+  # 
+  # @param [Array] current the current node that is being traversed by the 
+  #                algorithm.
+  # @param [Integer] _end the index of the target node.
+  # @param [Integer] current_total current Integer cost of the trajectory that
+  # is being explored by this branch of the algorithm.
+  # 
+  def rec_resolve(current, _end, current_total)
+    current_writer_index = current[0]
+    (0..@interconnect_table.size - 1).each do |i|
+      if @interconnect_table[i][current_writer_index][:connection]
+        new_total = current_total + (@interconnect_table[i][current_writer_index][:cost] || 1)
+
+        if @interconnect_table[i][current_writer_index][:total] > new_total
+          @interconnect_table[i][current_writer_index] = {:total => new_total, :connection => true, :previous => current.reverse}
+
+          unless @interconnect_table[_end].any?{|el| el[:total] < new_total}
+            rec_resolve([i, current_writer_index], _end, new_total)
+          end
+        end
+      end
+    end
+  end
+
+  # Scans the interconnect table, starting with the end_index, and traces a
+  # trajectory back to its source, using the traceback references in each cell
+  # from the interconnect table. The source cell is considered as the cell for
+  # which there is no traceback reference.
+  #
+  # @param [Integer] end_index an Integer that corresponds to the last
+  #             element (from the original Hash structure) for which there
+  #             should be a trajectory calculated by the search algorithm.
+  #
+  # @return [Array<Integer>] the connection indices from the original Hash
+  #   structure.
+  #
+  def dump_trajectory(end_index)
+    result = []
+    
+    # Get the path with the cheapest result
+    min_element = @interconnect_table[end_index].min{|a,b| a[:total] <=> b[:total]}
+    min_index = @interconnect_table[end_index].index(min_element)
+
+    previous = [min_index, end_index]
+    begin
+      connection_index = @hash[:connections].index(@hash[:connections].detect{|el| el[:link] == previous})
+      result << connection_index unless connection_index.nil?
+      previous = @interconnect_table[previous[1]][previous[0]][:previous]
+    end while not previous.nil?
+
+    result
+  end
+
+  # Commodity method for printing the interconnect table during the execution of the search algorigthm.
+  #
+  def dump_table
+    @interconnect_table.inject('') do |row_acc, row|
+      row_acc + "\n" + row.inject('') do |col_acc, col|
+        col_acc + (col[:total] == Float::INFINITY ? 'I' : col[:total].to_s) + " | "
+      end
+    end
+  end
+end