ipxact-ruby 0.11.1 → 0.11.2

data/README.html

@@ -10,35 +10,30 @@
 
 <p><strong>IPXACT-Ruby</strong> is a ruby library for extracting data from an <strong>IPXACT</strong> platform description. It was developed at <a href='http://tima-sls.imag.fr'>TIMA Laboratory</a>, France, for simplifying recurring platform parsing tasks. As such, this gem relies heavily on Aaron Patterson&#8217;s <a href='http://nokogiri.org'>Nokogiri gem</a> for parsing the XML data. This gem also provides methods for computing values that cannot be explicitly defined using the <strong>IPXACT</strong> format, such as component base addresses, relative to other components. Finally, please note that, in its current state, the <strong>IPXACT-Ruby</strong> gem does not handle all the aspects of the <strong>IPXACT</strong> format, but focuses on its <strong>Component</strong> and <strong>Design</strong> concepts .</p>
 
-<h2 id='history'>History</h2>
-
-<p>XXX Latest changes</p>
-
 <h2 id='ipxact_format'>IPXACT format</h2>
 
 <p><strong>IPXACT</strong> 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 <a href='http://www.accelera.org'>Accelera</a>. Additionally, the <strong>IPXACT</strong> format is now an IEEE standard, under the reference <a href='http://standards.ieee.org/getieee/1685/index.html'>IEEE-1685</a>. Its full specification may be downloaded <a href='http://www.accellera.org/pressroom/2010/Get_1685_01Jun10.pdf'>here</a>.</p>
 
 <h2 id='basic_usage'>Basic Usage</h2>
 
-<p>An IPXACT platform is basically composed of two types of elements:</p>
+<p>Platforms built with the <strong>IPXACT-Ruby</strong> gem are basically composed of two types of elements:</p>
 
 <ul>
-<li>
-<p>Component files, which describe the structure of an IPXACT component</p>
-
-<p>component_docs = IPXACT::load_components(COMPONENT_PATH) design_docs = IPXACT::load_designs(DESIGN_PATH)</p>
-</li>
+<li>Component files, which describe the structure of an <strong>IPXACT</strong> component. Components may include references to design files.</li>
 
-<li>
-<p>Design files</p>
-</li>
+<li>Design files, which may instantiate variable values subcomponent instances.</li>
 </ul>
 
-<p>The whole platform will then be parsed by the IPXACT gem:</p>
+<p>Most uses of this library should start with loading the <strong>IPXACT</strong> components and designs.</p>
+
+<pre><code>component_docs = IPXACT::load_components(COMPONENT_PATH)
+design_docs = IPXACT::load_designs(DESIGN_PATH)</code></pre>
+
+<p>The whole platform should then be fed to the parser:</p>
 
 <pre><code>platform = IPXACT::Parser::PlatformData.parse_platform(&lt;platform_name&gt;, component_docs, design_docs)</code></pre>
 
-<p>Or if you&#8217;d rather specify the platform&#8217;s version that should be loaded:</p>
+<p>Or if you&#8217;d rather specify the platform&#8217;s version that should be used:</p>
 
 <pre><code>platform = IPXACT::Parser::PlatformData.parse_platform([&lt;platform_name&gt;, &lt;platform_version&gt;], \
                                                         component_docs, design_docs)</code></pre>
@@ -53,37 +48,46 @@
 
 <p>Additionally, the same approach may be used for setting parsing constraints, which are passed as a final argument (<code>Array</code>) to the <code>parse_platform</code> method.</p>
 
-<p>When builder the platform object, IPXACT will combine component and design descriptions, identify hierarchical components and parse subcomponents when possible. In fact, in platform should be considered as a component except for a basic method aliasing (the <code>subcomponents</code> and <code>subcomponents=</code> methods are respectively aliased to <code>components</code> and <code>components=</code>, for the sake of DSL legibility). Thus, a component is composed of:</p>
+<p>When builder the platform object, <strong>IPXACT-Ruby</strong> 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 <code>subcomponents</code> and <code>subcomponents=</code> methods are respectively aliased to <code>components</code> and <code>components=</code>, for the sake of semantics). Thus, a component is composed of:</p>
 
 <ul>
 <li><code>subcomponents</code></li>
 
-<li><code>ports</code></li>
+<li><code>ports</code>, which may include register maps or remaps, depending on the port type.</li>
 
 <li><code>interconnections</code>, which define how its subcomponents are connected with one another.</li>
 
 <li><code>hierconnections</code>, which correspond the components&#8217; connections between its ports and its subcomponents.</li>
 </ul>
 
-<p>For more information, please refer to the specs provided with the gem.</p>
+<p>While the subcomponents are <code>IPXACT::Component</code> instances, <code>ports</code>, <code>interconnections</code> and <code>hierconnections</code> are plain Ruby hashes that store data from the IPXACT model, without any post-processing.</p>
+
+<p>For more information, please refer the gem&#8217;s YARD documentation (every method is extensively documented) and to the specs provided with the gem.</p>
+
+<h2 id='component_address_resolution'>Component address resolution</h2>
+
+<p><strong>IPXACT-Ruby</strong> also provides methods for resolving a component&#8217;s base address, relative to another component. The first method <code>resolve_data_path</code> 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 <code>master</code> port and a <code>mirrored_master</code>, between a <code>mirrored_slave</code> and a <code>slave</code>, between a <code>master</code> and a <code>slave</code> or between an <code>int_master</code> and an <code>int_slave</code>). The second method <code>resolve_base_address</code> deduces a memory address from the data path issued by the first method.</p>
+
+<pre><code>data_path = platform.resolve_data_path(&#39;i_proc&#39;, &#39;i_block_device&#39;)
+base_address = platform.resolve_base_address(data_path)</code></pre>
 
 <h2 id='installation'>Installation</h2>
 
 <p>Standard gem install command:</p>
 
-<pre><code>gem install ipxact</code></pre>
+<pre><code>gem install ipxact-ruby</code></pre>
 
 <h2 id='support'>Support</h2>
 
 <ul>
-<li>guillaume (dot) godetbar (at) gmail (dot) com</li>
+<li>email guillaume (dot) godetbar (at) gmail (dot) com</li>
 </ul>
 
 <h2 id='license'>License</h2>
 
-<p>Copyright (C) 2010 TIMA Laboratory</p>
+<p class='license'>Copyright (C) 2010 TIMA Laboratory</p>
 
-<p>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.</p>
+<p class='license'>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.</p>
 
-<p>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.</p>
+<p class='license'>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.</p>
 </body></html>

data/README.mdown

@@ -4,64 +4,99 @@ CSS: style.css
 IPXACT-Ruby
 ===========
 
-**IPXACT-Ruby** is a ruby library for extracting data from an **IPXACT** platform description. It was developed at [TIMA Laboratory](http://tima-sls.imag.fr), France, for simplifying recurring platform parsing tasks. As such, this gem relies heavily on Aaron Patterson's [Nokogiri gem](http://nokogiri.org) 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 .
-
-
-History
--------
-
-XXX Latest changes
+**IPXACT-Ruby** is a ruby library for extracting data from an **IPXACT**
+platform description. It was developed at 
+[TIMA Laboratory](http://tima-sls.imag.fr), France, for simplifying recurring
+platform parsing tasks. As such, this gem relies heavily on Aaron Patterson's
+[Nokogiri gem](http://nokogiri.org) 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](http://www.accelera.org). Additionally, the **IPXACT** format is now an IEEE standard, under the reference [IEEE-1685](http://standards.ieee.org/getieee/1685/index.html). Its full specification may be downloaded [here](http://www.accellera.org/pressroom/2010/Get_1685_01Jun10.pdf).
+**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 [Accellera](http://www.accellera.org). Additionally, the
+**IPXACT** format is now an IEEE standard, under the reference
+[IEEE-1685](http://standards.ieee.org/getieee/1685/index.html). Its full
+specification may be downloaded
+[here](http://www.accellera.org/pressroom/2010/Get_1685_01Jun10.pdf).
 
 
 Basic Usage
 -----------
-An IPXACT platform is basically composed of two types of elements:
-
-* Component files, which describe the structure of an IPXACT component
+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)
 
-* Design files
-
-The whole platform will then be parsed by the IPXACT gem:
+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 loaded:
+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:
+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 will combine component and design
-descriptions, identify hierarchical components 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 DSL
-legibility). Thus, a component is composed of:
+* `[<component_name>, <component_version>]` will 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`
+* `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.
+* `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.
+
 
-For more information, please refer 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
 ------------
@@ -73,19 +108,22 @@ Standard gem install command:
 Support
 -------
 
-* guillaume (dot) godetbar (at) gmail (dot) com
+* email guillaume (dot) godetbar (at) gmail (dot) com
 
 License
 -------
 
 Copyright (C) 2010 TIMA Laboratory
+{: .license}
 
 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.
+{: .license}
 
 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.
+{: .license}

data/Rakefile

@@ -20,7 +20,7 @@ begin
     gemspec.name = "ipxact-ruby"
     gemspec.summary = "Ruby library for parsing IPXACT specifications and extracting relevant information."
     gemspec.email = "guillaume.godetbar@gmail.com "
-    gemspec.homepage = "http://tima-sls.imag.fr"
+    gemspec.homepage = "http://tima-sls.imag.fr/www/research/ipxact/"
     gemspec.authors = ["Guillaume Godet-Bar"]
     gemspec.files = FileList["{spec,schemas,autotest}/**/*", "lib/ipxact.rb", "lib/ipxact/*", "lib/ipxact/parser/*", "lib/ipxact/pathfinder/graph_pathfinder.rb", ".autotest", ".gitignore", "Rakefile", "VERSION"]
     gemspec.add_dependency 'nokogiri'

data/VERSION

@@ -1 +1 @@
-0.11.1
+0.11.2

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 11
-  - 1
-  version: 0.11.1
+  - 2
+  version: 0.11.2
 platform: ruby
 authors: 
 - Guillaume Godet-Bar
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-10-13 00:00:00 +02:00
+date: 2010-10-14 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -182,7 +182,7 @@ files:
 - README.html
 - README.mdown
 has_rdoc: true
-homepage: http://tima-sls.imag.fr
+homepage: http://tima-sls.imag.fr/www/research/ipxact/
 licenses: []
 
 post_install_message: