Difference between revisions of "PythonXMLCrawler"

From Genesis2
Jump to: navigation, search
(Traversal related methods)
 
(8 intermediate revisions by the same user not shown)
Line 21: Line 21:
  
 
Now we create an object and init it with the XML file:
 
Now we create an object and init it with the XML file:
 
+
<pre>
 
c = XMLCrawler()
 
c = XMLCrawler()
 
c.read_xml('FPGen.xml')
 
c.read_xml('FPGen.xml')
 +
</pre>
 +
'c' in this notation stands for crawler and is always pointing to the hierarchical equivalent of a design instance. It starts at the top. From here on, we can use the following API which is almost identical to the Genesis2 compiler API ([[Genesis2#Special_Built-in_Methods|as described here]]).
 +
 +
===  Traversal related methods ===
 +
;  def get_parent(self) : returns the instance's parent or None if this is top
 +
 +
;  def get_top(self) : returns the top of the hierarchy
 +
 +
;  def iname(self):  instance name
 +
 +
;  def mname(self):  module name (after uniquification)
 +
 +
;  def bname(self):  base module name (i.e., template name, before uniquification)
 +
 +
;  def sname(self):  Source module name (i.e., before synonyms were applied; also the name of the source file)
 +
 +
;  def exists_subinst(self, name): check if a subinst named name exists
 +
 +
;  def get_subinst(self, name): returns a crawler  object pointing to subinst by name name
 +
 +
;  def get_subinst_array(self,pattern='.*'): returns an array of crawler objects pointing to subinsts that matched pattern
 +
 +
;  def get_instance_path(self): returns the full path to this instance
 +
 +
;  def search_subinst(self, options = dict())  <span style="color:red">('PathRegex', 'HasParamRegex', and 'ApplyMap' are NOT yet implemented)</span>
 +
:  API method for searching the entire design hierarchy or portions of it according to user defined criteria(s)
 +
:  All criteria are optional. The returned value is a list of objects that matched ALL specified criteria.
 +
:;  From: Either pointer or text path to an instance work here (default is the design top)
 +
:;  Depth: How deep in the hierarchy should we search? (default is 10000 ;-)
 +
:;  PathRegex: Return only instances who's path matches some regular expression (e.g., '.*\.ahb0\..*')
 +
:;  INameRegex: Return only instances who's instance name matches a regular expression
 +
:;  MNameRegex: Return only instances who's finalized module name matches a regular expression
 +
:;  BNameRegex: Return only instances who's base module name (before uniquification) matches a regular expression
 +
:; SNameRegex: Return only instances who's source file name matches a regular expression
 +
:; HasParamRegex: Return only instances that has a parameter who's name matches the regular
 +
:: expression. The HasParamRegex arg can be either a string (e.g., 'Width')
 +
:: or a string array ref (e.g., ['Width', 'Radix']). Note that in the string
 +
:: array case, we search for instances that has a param that matchs regex1 AND
 +
:: a param that matches regex2 AND...
 +
:; ApplyMap: If you have some complex way of determining if an instance should be returned,
 +
:: you can create your own function that accept/reject an objects. Your function
 +
:: must return False/True. E.g., def func(node): return (node.iname() == 'ofer')
 +
:; Reverse: Search hierarchy in DFS or in Reverse DFS order (True/False)
 +
 +
=== Parameter extraction methods ===
 +
; def list_params(self): Return a list of all the names of all parameters in self.
 +
; def exists_param(self, prmName): Returns True/False if a parameter prmName exists in the calling object
 +
; def get_param_doc(self, prmName): Returns the documentation of parameter prmName
 +
; def get_param_val(self, prmName): Returns the value of parameter prmName
  
'c' stands for crawler and is always pointing to the hierarchical equivalent of a design instance. It starts at the top. From here on, we can use the following API which is almost identical to the Genesis2 compiler API:
+
== Example ==
  Traversal related methods
 
  def get_parent(self) -- returns the instance's parent or None if this is top
 
  def get_top(self) -- returns the top of the hierarchy
 
  def iname(self): -- instance name
 
  def mname(self): -- module name (after uniquification)
 
  def bname(self):  -- base module name (i.e., template name, before uniquification)
 
  def sname(self):  -- Source module name (i.e., before synonyms were applied; also the name of the source file)
 
  def exists_subinst(self, name): -- check if a subinst named name exists
 
  def get_subinst(self, name): -- returns a crawler  object pointing to subinst by name name
 
  def get_subinst_array(self,pattern='.*'): -- returns an array of crawler objects pointing to subinsts that matched pattern
 
  def get_instance_path(self): -- returns the full path to this instance
 
  def search_subinst(self, options = dict()):  (Only 'From', 'Depth' and 'Reverse' currently implemented)
 
        # API method for searching the entire design hierarchy or portions of it according to user defined criteria(s)
 
        # All criteria are optional. The returned value is a list of objects that matched ALL specified criteria.
 
        # From - Either pointer or text path to an instance work here (default is the design top)
 
        # Depth - How deep in the hierarchy should we search? (default is 10000 ;-)
 
        # PathRegex - Return only instances who's path matches some regular expression (e.g., '.*\.ahb0\..*')
 
        # INameRegex - Return only instances who's instance name matches a regular expression
 
        # MNameRegex - Return only instances who's finalized module name matches a regular expression
 
        # BNameRegex - Return only instances who's base module name (before uniquification) matches a regular expression
 
        # SNameRegex - Return only instances who's source file name matches a regular expression
 
        # HasParamRegex - Return only instances that has a parameter who's name matches the regular
 
        #                expression. The HasParamRegex arg can be either a string (e.g., 'Width')
 
        #                or a string array ref (e.g., ['Width', 'Radix']). Note that in the string
 
        #                array case, we search for instances that has a param that matchs regex1 AND
 
        #                a param that matches regex2 AND...
 
        # ApplyMap - If you have some complex way of determining if an instance should be returned,
 
        #            you can create your own function that accept/reject an objects. Your function
 
        #            must return False/True. E.g., def func(node): return (node.iname() == 'ofer')
 
        # Reverse - Search hierarchy in DFS or in Reverse DFS order (True/False)
 
 
 
Parameter extraction methods
 
  def exists_param(self, name):
 
  def get_param_doc(self, name):
 
  def get_param_val(self, name):
 
   
 
  
Example script and xml file are attached here.
+
With your Genesis package, comes a small starter Python script and a test XML file from our Stanford FPGen project. You can fins them and try them as follows:
 +
<pre>
 +
# create a local test directory
 +
mkdir my_XMLCrawler_test_dir
 +
cd my_XMLCrawler_test_dir
  
 +
# copy relevant files over
 +
cp $GENESIS_HOME/PythonLibs/Genesis2/Test/HelloXML.py .
 +
cp $GENESIS_HOME/PythonLibs/Genesis2/Test/FPGen.xml .
 +
chmod +x HelloXML.py
  
Best,
+
# run the test script
Ofer.
+
./HelloXML.py
 +
</pre>

Latest revision as of 16:55, 11 June 2013

Genesis2.CMLCrawler Python Library

As you may remember, Genesis2 outputs all its hierarchy structure and for each module all its parameters (final binding) into an XML structure (more information here, XML schema page here). The idea is that this information is useful for creating drivers, backend flows and more. To make your life easier in traversing the XML, we provide a small Python module called Genesis2.XMLCrawler that provides navigation and search methods. This page describes how to use it.

System Requirements and Setup

Genesis2.XMLCrawler requires Python 2.5 or above.

If you have not done so thus far, you may need to add $GENESIS_HOME/PythonLibs to your path. See here for setting up Genesis2 environment. Or, if all you need is this python module, add the following line to your setup file:

setenv PYTHONPATH "$GENESIS_HOME/PythonLibs:$PYTHONPATH"

How to Use The Module

Say we want to create a script that extract info from the XML, I'll call it HelloXML.py. Start it with:

#!/usr/bin/python
from Genesis2.XMLCrawler import XMLCrawler

Now we create an object and init it with the XML file:

c = XMLCrawler()
c.read_xml('FPGen.xml')

'c' in this notation stands for crawler and is always pointing to the hierarchical equivalent of a design instance. It starts at the top. From here on, we can use the following API which is almost identical to the Genesis2 compiler API (as described here).

Traversal related methods

def get_parent(self) 
returns the instance's parent or None if this is top
def get_top(self) 
returns the top of the hierarchy
def iname(self)
instance name
def mname(self)
module name (after uniquification)
def bname(self)
base module name (i.e., template name, before uniquification)
def sname(self)
Source module name (i.e., before synonyms were applied; also the name of the source file)
def exists_subinst(self, name)
check if a subinst named name exists
def get_subinst(self, name)
returns a crawler object pointing to subinst by name name
def get_subinst_array(self,pattern='.*')
returns an array of crawler objects pointing to subinsts that matched pattern
def get_instance_path(self)
returns the full path to this instance
def search_subinst(self, options = dict()) ('PathRegex', 'HasParamRegex', and 'ApplyMap' are NOT yet implemented)
API method for searching the entire design hierarchy or portions of it according to user defined criteria(s)
All criteria are optional. The returned value is a list of objects that matched ALL specified criteria.
From
Either pointer or text path to an instance work here (default is the design top)
Depth
How deep in the hierarchy should we search? (default is 10000 ;-)
PathRegex
Return only instances who's path matches some regular expression (e.g., '.*\.ahb0\..*')
INameRegex
Return only instances who's instance name matches a regular expression
MNameRegex
Return only instances who's finalized module name matches a regular expression
BNameRegex
Return only instances who's base module name (before uniquification) matches a regular expression
SNameRegex
Return only instances who's source file name matches a regular expression
HasParamRegex
Return only instances that has a parameter who's name matches the regular
expression. The HasParamRegex arg can be either a string (e.g., 'Width')
or a string array ref (e.g., ['Width', 'Radix']). Note that in the string
array case, we search for instances that has a param that matchs regex1 AND
a param that matches regex2 AND...
ApplyMap
If you have some complex way of determining if an instance should be returned,
you can create your own function that accept/reject an objects. Your function
must return False/True. E.g., def func(node): return (node.iname() == 'ofer')
Reverse
Search hierarchy in DFS or in Reverse DFS order (True/False)

Parameter extraction methods

def list_params(self)
Return a list of all the names of all parameters in self.
def exists_param(self, prmName)
Returns True/False if a parameter prmName exists in the calling object
def get_param_doc(self, prmName)
Returns the documentation of parameter prmName
def get_param_val(self, prmName)
Returns the value of parameter prmName

Example

With your Genesis package, comes a small starter Python script and a test XML file from our Stanford FPGen project. You can fins them and try them as follows:

# create a local test directory
mkdir my_XMLCrawler_test_dir
cd my_XMLCrawler_test_dir

# copy relevant files over
cp $GENESIS_HOME/PythonLibs/Genesis2/Test/HelloXML.py .
cp $GENESIS_HOME/PythonLibs/Genesis2/Test/FPGen.xml .
chmod +x HelloXML.py

# run the test script
./HelloXML.py