IPXACT-Ruby

IPXACT-Ruby

IPXACT-Ruby is a ruby library for extracting data from an IPXACT platform description. It was developed at TIMA Laboratory, France, for simplifying recurring platform parsing tasks. As such, this gem relies heavily on Aaron Patterson’s Nokogiri gem for parsing the XML data. This gem also provides methods for computing values that cannot be explicitly defined using the IPXACT format, such as component base addresses, relative to other components. Finally, please note that, in its current state, the IPXACT-Ruby gem does not handle all the aspects of the IPXACT format, but focuses on its Component and Design concepts .

IPXACT format

IPXACT is an XML format for describing electronic components and their designs. First managed by the SPIRIT Consortium, the evolution of the format is now supervised by Accelera. Additionally, the IPXACT format is now an IEEE standard, under the reference IEEE-1685. Its full specification may be downloaded here.

Basic Usage

Platforms built with the IPXACT-Ruby gem are basically composed of two types of elements:

  • Component files, which describe the structure of an IPXACT component. Components may include references to design files.
  • Design files, which may instantiate variable values subcomponent instances.

Most uses of this library should start with loading the IPXACT components and designs.

component_docs = IPXACT::load_components(COMPONENT_PATH)
design_docs = IPXACT::load_designs(DESIGN_PATH)

The whole platform should then be fed to the parser:

platform = IPXACT::Parser::PlatformData.parse_platform(<platform_name>, component_docs, design_docs)

Or if you’d rather specify the platform’s version that should be used:

platform = IPXACT::Parser::PlatformData.parse_platform([<platform_name>, <platform_version>], \
                                                        component_docs, design_docs)

In most cases, when methods require identifying a component you may use either specification:

  • <component_name> will fetch the most recent component.
  • [<component_name, <component_version>] wil get the component with the specified version, thus allowing different component versions to coexist in the same path.

Additionally, the same approach may be used for setting parsing constraints, which are passed as a final argument (Array) to the parse_platform method.

When builder the platform object, IPXACT-Ruby will combine component and design descriptions, identify hierarchical components, assign variable values (defined in design files) and parse subcomponents when possible. In fact, in platform should be considered as a component except for a basic method aliasing (the subcomponents and subcomponents= methods are respectively aliased to components and components=, for the sake of semantics). Thus, a component is composed of:

  • subcomponents
  • ports, which may include register maps or remaps, depending on the port type.
  • interconnections, which define how its subcomponents are connected with one another.
  • hierconnections, which correspond the components’ connections between its ports and its subcomponents.

While the subcomponents are IPXACT::Component instances, ports, interconnections and hierconnections are plain Ruby hashes that store data from the IPXACT model, without any post-processing.

For more information, please refer the gem’s YARD documentation (every method is extensively documented) and to the specs provided with the gem.

Component address resolution

IPXACT-Ruby also provides methods for resolving a component’s base address, relative to another component. The first method resolve_data_path computes an optimal path between the two component instances that are passed as parameters. In the context of this library, an optimal path should be understood as the shortest path between two components, considering compatible port connections (i.e., between a master port and a mirrored_master, between a mirrored_slave and a slave, between a master and a slave or between an int_master and an int_slave). The second method resolve_base_address deduces a memory address from the data path issued by the first method.

data_path = platform.resolve_data_path('i_proc', 'i_block_device')
base_address = platform.resolve_base_address(data_path)

Installation

Standard gem install command:

gem install ipxact-ruby

Support

  • email guillaume (dot) godetbar (at) gmail (dot) com

License

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.