Tornado API Reference : Project Database Library
dataDocLib - TCL library for the project facilities dataDoc engine
docWalk - walk a document
mxrDataDocCreate - create a module xref document
mxrTcGet - get the toolchain associated with an MxrDoc
mxrSupertree - recursively, what modules call a given set of modules
mxrSubtree - recursively, what modules are called by a given set of modules
mxrSizeGet - return the size of a set of modules
mxrDocValidate - test for duplicate symbol names and other bugs
cxrDataDocCreate - create a component xref document from .cdf files
cxrSupertree - what components require a given set of components
cxrSubtree - what components are required by a given set of components
cxrSubfolders - find everything under a given folder recursivly
cxrSizeGet - get the size of a set of components
modAnalyze - analyze archives and/or object modules
modTrace - trace module dependencies
modSubtree - find (recursivley) all modules called by a set of modules
modSupertree - find (recursivley) all modules that call a set of modules
modCalledBy - find all modules that call a given set of modules
modCalls - find all modules that are called by a given set of modules
modInfo - get info about module relationships
This library contains the TCL API for accessing the configuration engine's dependency database. To use the procedures in this libary, you must first "source cmpScriptLib.tcl" into the wtxtcl interpreter. At the lowest level, the database is an in-memory object database. Each object is identified by a string name, which must be unique within the dataBase. Each object can have a set of properties and a set of associations with other objects. The set of allowed object types, properties, and associations are defined by a schema.
There are two schemas supported; MxrDoc (Module xref), and CxrDoc (Component xref). More schemas can be added later. The MxrDoc schema is quite simple. It supports only two types of objects; Module and Symbol. The associations are also quite simple, a Module can have an association with a symbol of type "imports", "exports", or "declares" (that last is for common block symbols). A symbol can have the corresponding association with a module of type "importedBy", "exportedBy", or "declaredBy". The properties of a module are it's textSize, dataSize, and bssSize. The properties of a symbol are it's size, which is only valid if the symbol is a common block symbol. The "import" command imports the output of "nm" to populate the database. The "importSize" command imports the output of "size" to finish populating the database. The CxrDoc schema is more complicated, and not covered here. The Tornado API guide has a section on component creation which describes the CxrDoc schema in more detail.
This library provides a set of high-level routines for each schema. These routines can compute, for example, the modules called by a given module. These high-level routines are built on top of lower level routines. The simplest API to module xref information is provided by the mod* routines in this library. If you are just looking for a simple way to analyze module dependencies, then you don't need to read or understand the rest of the discussion below - just skip to the mod* library manual pages. To use any other procedure in the library, you'll first need to understand the low-level dataDoc interface described below.
The low-level interface for dataDoc's does not depend on the schema. It allows one to ask; given a set of objects, what are it's properties and with what other objects is it associated? Before describing the interface, lets define some more terminology. A DataDoc is a database (MxrDoc or CxrDoc). A DataSet is a collection of objects in the database. DataDoc's and DataSet's can be created, deleted, and queried using the following API:
docCreate SchemaName -> DataDocument
Creates a data document object that utilizes the specified schema. The document will support the object types, attributes, and relations described by the schema. For example, to create an MxrDoc database, one could do "set d [docCreate MxrDoc]".
DataDocument import FileName
Reads an ASCII file containing descriptions of Data Objects. All Data Object instances, and their attribute/association properties, will be created and placed in the data document. For example, "$d import FileName".
DataDocument types -> {DObject TypeNames}
Returns a tcl a list of names of all the types of objects supported by the data document.
DataDocument instances [TypeName] -> {DObject Instance Names}
Returns a tcl list of object "id names" for all the instances, of the specified type, contained within the document. If a TypeName was not specified then the "id names" for all instances will be returned.
DataDocument setCreate -> DObjectSet
Creates a set object, and associates with the given document. A set object can be used to perform queries on any object in the document that it is associated with.
A DObjectSet can handle the following method calls from TCL.
DObjectSet = {DObject Instances Names}
Assigns objects to the set. Queries can then be performed on those objects using the other methods for DObjectSet.
A DObjectSet can also be used in TCL as a set. Tcl lists can be assigned to the set, removing duplicates from the list. Set do not perserve any order to their elements.
DObjectSet instances [type] -> {DObject Names}
Returns a TCL list of all the items that are in the set that are names of objects in the document.
DObjectSet contents -> {Object Names}
Returns a TCL list of the contents of the set. Names will appear in the list regardless of whether they are or are not the names of objects in the document.
DObjectSet properties -> {Property Names}
Returns a TCL list of all property names for all the objects contained in the set. Duplicate property names are not eliminated from the list (a SET can be used to eliminate duplicates).
DObjectSet get propertyName -> {Property Values}
Returns a TCL list of the value of a given property for all the objects in the set that support that property.
DObjectSet types -> {DObject Type Names}
Returns list of the type name for every object that is in the set. Duplicate of a type name will appear when their is more than one object of that type in the set.
DObjectSet setCreate -> DObjectSet
Creates an empty DObjectSet that is bound to the same data document as the original set.
The syntax is DObjectSet BinaryOp Tcl List -> Tcl List
DObjectSet - {Object Names} -> {List} Set difference
DObjectSet + {Object Names} -> {List} Set union
DObjectSet & {Object Names} -> {List} Set intersection
DObjectSet ^ {Object Names} -> {List} Set symmetric difference (XOR)
suppose I have a file called "foo.nm", which is the output of "nm" on an archive. To find all symbols defined in the archive:
set d [docCreate MxrDoc] ;# create an empty database $d import foo.nm ;# import nm output set s [$d setCreate] ;# create a set $s = [$d instances Module] ;# $s = all modules in database $s = "[$s get exports] [$s get declares]" ;# all exported and ;# common block symbols puts "exported symbols = [$s instances]" ;# print result $s delete ;# delete the setSuppose I want to find all undefined symbols in a set of modules:set s [$d setCreate] ;# create a set $s = \<some set of modules\> set defined "[$s get exports] [$s get declares]" ;# all exported syms $s = [$s get imports] ;# all imported syms $s = [$s - $defined] ;# remove all exported syms puts "undefined symbols = [$s instances]" ;# print result $s delete ;# delete the setOf course lots of other examples can be found by reading the source code for the TCL routines provided by this library.
docWalk - walk a document
Recall that all dataDoc's contain objects and associations between them. This forms a graph. This routine walks the object graph starting with an initial set of nodes and visits the next set of nodes according to the TCL proc query. It continues visiting new nodes until such a time as no new nodes are visited.
This is really a support routine for other high-level recursive queries. For example, if you want to know "what modules will be dragged in by dependancy if I drag in fooLib.o", then you want to perform a recursive walk of the MxrDoc. In fact, the routines modSubtree and mxrSubtree are built on top of docWalk (for the recursion), and mxrUses (for the walk).
The routine query should must be a TCL proc that takes as input a DataSet and a 2nd optional argument which is proc-specific. It should return a list of node-names that are to be vistied next.
inputSet - DataSet of objects query - TCL proc that performs the graph walk arg - (optional) argument to pass to query
the set of node visited during the graph walk
mxrDataDocCreate - create a module xref document
This routine creates an mxrDoc from a set of object modules and archives. It runs the "nm" and "size" commands corresponding to the toolchain specified, and imports these into a new MxrDoc. This routine will fail if the object files and archives are not compatible with the given toolchain. The toolchain must be of the form ::tc_CPUTOOL (e.g., ::tc_PPC604gnu).
Note: If you source cmpScriptLib.tcl, you can call "mxrDocCreate $hProj" to get the MxrDoc associated with a given project handle. mxrDocCreate is actually built on top of mxrDataDocCreate.
toolchain - toolchain of the form ::tc_CPUTOOL fileList - list of object files and archives
an MxrDoc
dataDocLib, cmpScriptLib, cmpProjHandleGet
mxrTcGet - get the toolchain associated with an MxrDoc
This routine only works on MxrDoc's created by mxrDataDocCreate.
mxrDoc - MxrDoc
toolchain associated with this MxrDoc
mxrSupertree - recursively, what modules call a given set of modules
Suppose module1 calls module2, and module2 calls module3. Then the supertree of module3 would contain both module2 and module1. This routine is just like modSupertree, but taks a DataSet as input instead of a list of module names.
modSet - DataSet of modules
list of modules in the supertree of the input set
mxrSubtree - recursively, what modules are called by a given set of modules
Suppose module1 calls module2, and module2 calls module3. Then the subtree of module1 would contain both module2 and module3. This routine is just like modSubtree, but taks a DataSet as input instead of a list of module names.
modSet - DataSet of modules
list of modules in the subtree of the input set
mxrSizeGet - return the size of a set of modules
modSet - DataSet of modules
a list of three elements: text, data, bss sizes.
mxrDocValidate - test for duplicate symbol names and other bugs
This routine checks for bugs in an MxrDoc, and prints any errors found to stdout. The only errors currently tested for are symbols exported by more than one module.
mxrDoc : MxrDoc to test
N/A
cxrDataDocCreate - create a component xref document from .cdf files
This routine takes a path to look for .cdf files, and returns a the corresponding CxrDoc. A toolchain must be specified of the form ::tc_CPUTOOL (e.g., ::tc_PPC604gnu). Before importing the .cdf files into a CxrDoc, the toolchain's preprocessor is run on the .cdf files with -DCPU=CPU. This allows CPU-specific overrides of the component descriptors to be made in the .cdf files.
Note: If you source cmpScriptLib.tcl, you can call "cxrDocCreate $hProj" to get the CxrDoc associated with a given project handle. cxrDocCreate is actually built on top of cxrDataDocCreate.
cdfPath - path to search for .cdf files toolchain - toolchain of the form ::tc_CPUTOOL
a CxrDoc
dataDocLib, cmpScriptLib, cmpProjHandleGet
cxrSupertree - what components require a given set of components
If a user wants to exclude a set of components, this routine can be used to tell what other components also need to be excluded by dependency. Because component dependencies are built on top of module dependencies, this routine also requires an MxrDoc containing information about the component's modules. The config engine uses this routine with parameter mxrDoc as the return value of "mxrDocCreate $hProj".
cmpSet - DataSet of components mxrDoc - MxrDoc
the list of all components that require components in cmpSet
dataDocLib, mxrDataDocCreate
cxrSubtree - what components are required by a given set of components
If a user wants to include a set of components, this routine can be used to tell what other components also need to be included by dependecy. Because component dependencies are built on top of module dependencies, this routine also requires an MxrDoc containing information about the component's modules. The config engine uses this routine with parameter mxrDoc as the return value of "mxrDocCreate $hProj".
cmpSet - DataSet of components mxrDoc - MxrDoc
the list of all components that are required by components in cmpSet
dataDocLib, mxrDataDocCreate
cxrSubfolders - find everything under a given folder recursivly
Components are grouped into folders. This routine returns the set of componenents and folders (recursively) under a given folder.
cmpSet - DataSet of component Folder objects.
the list of components and subfolders of the given folder
cxrSizeGet - get the size of a set of components
This routine returns the appoximate size of the smallest kernel that contains the given set of components. The size is always an underestimate, because it only takes into account the size of the .o's in the vxWorks archive - and not the size of the BSP and configuration files. The config engine uses this routine with parameter mxrDoc as the return value of "mxrDocCreate $hProj".
cmpSet - DataSet of components mxrDoc - DataDoc corresponding the the vxWorks archive
three sizes; text, data, and bss
dataDocLib, mxrDataDocCreate
modAnalyze - analyze archives and/or object modules
Create an MxrDoc corresponding to a set of object modules and archives. This routine is just like mxrDataDocCreate, but the toolchain parameter does not require a "tc_" prepended.
fileList - list of object moduless and archives to analyze toolchain - toolchain used to build the objects (e.g., PPC604gnu)
an MxrDoc handle
dataDocLib, mxrDataDocCreate
modTrace - trace module dependencies
Given two object modules within an archive, find the shortest path between them. The result is printed to stdout in the form "fromMod mod1 mod2 ... toMod". In verbose mode it also prints the reason for the dependencies by inserting a list of symbols between each module dependecy. That way you can find out what symbols caused the dependencies between, for example, mod1 and mod2.
This routine can be useful when tracking scalability bugs. For example, if you look at the output of "modSubtree" on a given object module, and find it contains many more module dependencies than you expected, then this routine can show you why those dependencies occured.
modDataDoc - MxrDoc handle returned from modAnalyze fromMod - module to trace from toMod - module to trace to verbose - (optional) set to verbose to print sym info
N/A
modSubtree - find (recursivley) all modules called by a set of modules
This routine is a recusive version of modCalls. It lets you know what modules are required by a given set of modules. Suppose module1 calls module2, and module2 calls module3. Then the subtree of module1 would contain both module2 and module3.
modDataDoc - return value of modAnalyze mods - list of module
list of modules called by mods (recursive)
modSupertree - find (recursivley) all modules that call a set of modules
This routine is a recusive version of modCalledBy. It lets you know what modules require a given set of modules. Suppose module1 calls module2, and module2 calls module3. Then the supertree of module3 would contain both module2 and module1.
modDataDoc - return value of modAnalyze mods - list of module
list of modules that call mods (recursive)
modCalledBy - find all modules that call a given set of modules
modDataDoc - return value of modAnalyze mods - list of module
list of modules that call mods
modCalls - find all modules that are called by a given set of modules
modDataDoc - return value of modAnalyze mods - list of module
list of modules that mod calls
modInfo - get info about module relationships
This routine can be used to get any other information associated with a set of modules, according to the MxrDoc schema.
modDataDoc - return value of modAnalyze mods - list of module (typically just one) info - info to get (e.g., exports, imports, declares, textSize, ...)
list of modules that mod calls