ipxact-ruby 0.11.1

data/lib/ipxact/component.rb

@@ -0,0 +1,235 @@
+# 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::Component} is what an {IPXACT::Platform} is essentially made of.
+# This class behaves like a Hash for general attributes (such as
+# +:instance_name+, +:vendor+, +:name+ and +:version+). This class also defines
+# 4 fixed attributes, that is: {#subcomponents}, {#interconnections},
+# {#hierconnections} and {#ports}. While interconnections, hierconnections and
+# ports are mostly used by the {IPXACT::GraphPathFinder} class, the
+# subcomponents are what most users will be querying. Subcomponents may be
+# terminal or non-terminal, i.e. composed of other subcomponents.
+#
+# @author Guillaume Godet-Bar
+#
+class IPXACT::Component < Hash
+  
+  # @return [Array<Component>] the list of subcomponents
+  attr_accessor :subcomponents 
+
+  # @return [Array<Hash>] the list of interconnections
+  attr_accessor :interconnections
+ 
+  # @return [Array<Hash>] the list of hierconnections
+  attr_accessor :hierconnections
+  
+  # @return [Array<Hash>] the list of ports
+  attr_accessor :ports
+  
+  # Creates a new {IPXACT::Component} instance
+  #
+  # @param [String] instance_name The name that will be used for identifying
+  #                 this specific component instance component.
+  # @param [String] name The name of the component type.
+  # @param [String] vendor The name of the component's vendor.
+  # @param [String] version The version of the component, following the typical
+  #                 relaxed semantic versioning convention +X(.Y(.Z)?)?+
+  #
+  def initialize(instance_name, name, vendor, version)
+    @subcomponents = {}
+    @interconnections = {}
+    @hierconnections = {}
+    @ports = []
+    self.merge!({:instance_name => instance_name,
+                 :version => version,
+                 :vendor => vendor,
+                 :name => name})
+  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 [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 resolve_data_path(subcomponent_start, subcomponent_end)
+    nodes, connections = rec_prepare_pathfinder_connections([], [])
+
+    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::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 [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 resolve_base_address(data_path, initial_value = 0)
+    base_address = initial_value
+    data_path.each do |connection|
+      connection.each do |connection_step|
+        subcomponent = 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
+
+  # Get the component's register map, if any.
+  #
+  # @return [Array] +nil+ if no register map could be found, or else an Array
+  #   of registers (Hash) structured as follows:
+  #   +:name+ the register's name;
+  #   +:offset+ the register's offset (from the memory map's base address,
+  #   expressed as a hex String value);
+  #   +:size+ the register's size (in bits, expressed as a String);
+  #   +:access+ the register's access (read-write, read-only, write-only etc.),
+  #   expressed as a String.
+  #
+  def register_map
+    return nil \
+      unless ports.any?{|port| port[:type] == :slave} ||
+             ports.any?{|port| port[:port_data][:registers]}
+
+      ports.select{|port| port[:type] == :slave && port[:port_data][:registers]} \
+           .first[:port_data][:registers]
+  end
+
+  # Commodity method for getting a component instance called +instance_name+,
+  # either from the direct subcomponents of the component, or from the
+  # subcomponents hierarchy.
+  #
+  # @param [String] instance_name the name of the subcomponent instance.
+  # 
+  # @return [Component] the subcomponent instance or nil if none could be found.
+  #
+  def rec_get_subcomponent(instance_name)
+    if subcomponents.has_key?(instance_name)
+      subcomponents[instance_name]
+    elsif subcomponents.empty?
+      nil
+    else
+      subcomponents.collect{|sub_name, sub| sub.rec_get_subcomponent(instance_name)} \
+                   .compact.first
+    end
+  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.
+  #
+  # @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::GraphPathFinder#initialize} method for more details on
+  #   the structure of these elements (both Hashes).
+  #
+  def rec_prepare_pathfinder_connections(current_nodes, current_interconnections)
+    if subcomponents.empty?
+      [current_nodes << self[:instance_name], current_interconnections]
+    else
+      subcomponents.each do |sub_name, subcomponent|
+        formatted_interconnections = interconnections.values.collect do |interconnect|
+          [reformat_connector(interconnect[0]), reformat_connector(interconnect[1])]
+        end
+        current_nodes, current_interconnections = \
+          subcomponent.rec_prepare_pathfinder_connections(current_nodes, current_interconnections + formatted_interconnections)
+      end
+      [current_nodes, current_interconnections]
+    end
+  end
+
+  # Executes the actual replacement of an hierarchical component's outside port
+  # with the attached subcomponent port.
+  #
+  # @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 reformat_connector(connector)
+    instance = 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
+
+end

data/lib/ipxact/parser.rb

@@ -0,0 +1,27 @@
+# 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/>.
+#
+
+# Root module for the parser submodules.
+#
+# @author Guillaume Godet-Bar
+#
+module IPXACT::Parser
+end
+
+require File.join File.dirname(__FILE__), 'parser/bus_data_parser'
+require File.join File.dirname(__FILE__), 'parser/component_data_parser'
+require File.join File.dirname(__FILE__), 'parser/platform_data_parser'
+

data/lib/ipxact/parser/bus_data_parser.rb

@@ -0,0 +1,229 @@
+# 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/>.
+#
+
+# Module for parsing IPXACT bus XML data.
+# 
+# @author Guillaume Godet-Bar
+#
+module IPXACT::Parser::BusData
+
+  # Parses the bus_doc bus interface data.
+  #
+  # @param [Nokogiri::Node] bus_doc the bus interface's IPXACT excerpt.
+  # @param [Nokogiri::Node] host_component the bus interface's host component
+  #                         IPXACT excerpt.
+  # @param [Array] variables the list of variables that are associated to the host
+  #                          component instance.
+  #
+  # @return [Hash] a Hash that describes the bus interface element. This Hash is
+  #   composed of:
+  #     :name       - The name of the port.
+  #     :type       - The port type (i.e., :master, :mirrored_master, :slave or
+  #                   :mirrored_slave)
+  #     :bus_type   - The bus interface type (i.e., its generic name).
+  #     :library    - The library in which the bus interface is defined.
+  #     :port_data  - Specific port data, depending on the port type.
+  #
+  def self.parse_bus(bus_doc, host_component, variables)
+      port_type, port_data = extract_bus_data(bus_doc, host_component, variables)
+
+      {
+        :name => bus_doc.xpath("./spirit:name").first.text,
+        :type => port_type,
+        :bus_type => bus_doc.xpath("./spirit:busType").first['name'],
+        :library => bus_doc.xpath("./spirit:busType").first['library'],
+        :port_data => port_data
+      }
+  end
+
+  # Extracts any relevant data from the bus_doc bus interface.
+  #
+  # @param [Nokogiri::Node] bus_doc the bus interface's IPXACT excerpt.
+  # @param [Nokogiri::Node] host_component the bus interface's host component
+  #                         IPXACT excerpt (i.e., Nokogiri Node).
+  # @param [Array<Hash>]    variables the list of variables that are associated
+  #                         to the host component instance.
+  #
+  # @return [Array<Symbol, Object>] an Array with the first element being the
+  #     port type (i.e., +:master+, +:mirrored_master+, +:slave+ or
+  #     +:mirrored_slave+), and the second element being +nil+, a Hash, or an
+  #     Array of Hashes, depending on the bus interface's type.
+  #
+  def self.extract_bus_data(bus_doc, host_component, variables)
+    if bus_doc.xpath("./spirit:mirroredMaster").size > 0
+      [:mirrored_master, extract_mirrored_master_data]
+    elsif bus_doc.xpath("./spirit:mirroredSlave").size > 0
+      [:mirrored_slave, extract_mirrored_slave_data(bus_doc, host_component, variables)]
+    elsif bus_doc.xpath("./spirit:slave").size > 0
+      [:slave, extract_slave_data(bus_doc, host_component)]
+    elsif bus_doc.xpath("./spirit:master").size > 0
+      [:master, extract_master_data(bus_doc, host_component)]
+    end
+  end
+
+
+private
+
+  # Extracts all relevant data from a master bus interface (i.e., the address
+  # space's range and width, if any).
+  # 
+  # @param [Nokogiri::Node] bus_doc the bus interface's IPXACT excerpt.
+  # @param [Nokogiri::Node] host_component the bus interface's host component
+  #                         IPXACT excerpt (i.e., Nokogiri Node).
+  #
+  # @return +nil+ if no address space can be found or else a Hash 
+  #   composed of:
+  #     :address_space_name - The address space's name.
+  #     :range              - The address space's range.
+  #     :width              - The address space's width.
+  #
+  def self.extract_master_data(bus_doc, host_component)
+    address_space_ref = bus_doc.xpath("./spirit:master/spirit:addressSpaceRef")
+    if address_space_ref.size > 0
+      address_space = host_component.xpath(".//spirit:addressSpace") \
+                                   .select do |as|
+                                     as.xpath("./spirit:name").first.text \
+                                     == address_space_ref.first['addressSpaceRef']
+                                   end.first
+      address_space_data = {
+        :address_space_name => address_space_ref.first['addressSpaceRef'],
+        :range => address_space.xpath("./spirit:range").first.text,
+        :width => address_space.xpath("./spirit:width").first.text
+      }
+    end
+    address_space_data
+  end
+
+  # Extracts all relevant data from a mirrored master bus interface.
+  #
+  # @return +nil+
+  #
+  def self.extract_mirrored_master_data
+    nil
+  end
+
+  # Extracts all relevant data from a mirrored slave interface (i.e., remap
+  # address and range), and applies any relevant variable value on the
+  # extracted bus data.
+  #
+  # @param [Nokogiri::Node] bus_doc the bus interface's IPXACT excerpt.
+  # @param [Nokogiri::Node] host_component the bus interface's host component
+  #                         IPXACT excerpt (i.e., Nokogiri Node).
+  # @param [Array<Hash>] variables the list of variables that are associated to
+  #                      the host component instance.
+  #
+  # @return [Hash] a Hash constructed as 
+  #   follows:
+  #     :remap  - A Hash composed of the remap address value (+:address+), and its
+  #             associated identifier (for variable application).
+  #     :range  - A Hash composed of the address range value (+:value+), and its
+  #             associated identifier (for variable application).
+  #
+  def self.extract_mirrored_slave_data(bus_doc, host_component, variables)
+    component_name = host_component.xpath("./spirit:component/spirit:name").first.text
+
+    base_addresses = bus_doc.xpath("./spirit:mirroredSlave/spirit:baseAddresses")
+    if base_addresses.size > 0
+
+      bus_data = {
+        :remap => {
+          :address => base_addresses.first.xpath("./spirit:remapAddress").first.text,
+          :id => base_addresses.first.xpath("./spirit:remapAddress").first['id']
+        },
+        :range => {
+          :value => base_addresses.first.xpath("./spirit:range").first.text,
+          :id => base_addresses.first.xpath("./spirit:range").first['id']
+        }
+      }
+
+      unless variables.empty?
+        variables.each do |var_key, var_value|
+          if bus_data[:remap][:id] == var_key
+            bus_data[:remap][:address] = var_value
+          elsif bus_data[:range][:id] == var_key
+            bus_data[:range][:value] = var_value
+          end
+        end
+      end
+
+      bus_data
+    end
+  end
+
+  # Extracts all relevant data from a slave bus interface (i.e., its first
+  # memory map, and associated address block data, such as the block's base
+  # address, range, etc., and its register map).
+  #
+  # @param [Nokogiri::Node] bus_doc the bus interface's IPXACT excerpt.
+  # @param [Nokogiri:: Node] host_component the bus interface's host component
+  #                          IPXACT excerpt (i.e., Nokogiri Node).
+  #
+  # @return [Hash] a Hash representing the bus interface's memory map, composed as
+  #   follows:
+  #     :memory_map_name  - The memory map's name String.
+  #     :base_address     - The memory map's base address (if any) hex String.
+  #     :range            - The memory map's range (if any) decimal String.
+  #     :width            - The memory map's width (if any) decimal String.
+  #     :registers        - The memory map's registers (if any), which are 
+  #                       composed of:
+  #                       :name   - The register's name.
+  #                       :offset - The register's offset (from the memory
+  #                                 map's base address, expressed as a hex
+  #                                 String value).
+  #                       :size   - The register's size (in bits, expressed as
+  #                                 a String).
+  #                       :access - The register's access (read-write,
+  #                                 read-only, write-only etc.), expressed as
+  #                                 a String.
+  #
+  def self.extract_slave_data(bus_doc, host_component)
+    memory_map_ref = bus_doc.xpath("./spirit:slave/spirit:memoryMapRef")
+    unless memory_map_ref.empty?
+      memory_map = host_component.xpath(".//spirit:memoryMap") \
+                                .select do |mm|
+                                  mm.xpath("./spirit:name").text \
+                                  == memory_map_ref.first['memoryMapRef']
+                                end.first
+
+      address_block = memory_map.xpath("./spirit:addressBlock[1]")
+      unless address_block.empty?
+        
+        registers_doc = address_block.xpath("./spirit:register")
+        registers = registers_doc.collect do |register_doc|
+          {
+            :name => register_doc.xpath("./spirit:name").text,
+            :offset => register_doc.xpath("./spirit:addressOffset").text,
+            :size => register_doc.xpath("./spirit:size").text,
+            :access => register_doc.xpath("./spirit:access").text
+          }
+        end
+
+        address_block_data = {
+          :base_address => address_block.xpath("./spirit:baseAddress").text,
+          :range => address_block.xpath("./spirit:range").text,
+          :width => address_block.xpath("./spirit:width").text,
+          :registers => registers
+        }
+      end
+      memory_map_data = {
+        :memory_map_name => memory_map.xpath("./spirit:name").text
+      }
+    end
+    memory_map_data.merge!(address_block_data || {}) unless memory_map_data.nil?
+
+    memory_map_data
+  end
+end