###########################################################################
# CGM MANAGER  - External Interface
# =============================================
# 
# The functions described below are to be sourced into all TAU tools needing
# the multiple depfile management services of the CGM manager.  
# 
# This document refers to three types of source code files: 
#   1. A "program file" (abbreviated "progfile") contains primary source code, 
#      such as function definitions. Examples of progfiles are ".c, .C, or .pc"
#      files.  
#   2. A "header file" is a file that may be multiply included into progfiles,
#      usually containing function and type declarations.  Examples of header
#      files are .h files in C, C++, or pC++.  
#   3. A "depfile" is a representation of the abstract syntax tree for a
#      single progile and multiple included header files.  The depfile is
#      created by the compiler parser and read by TAU via a "CGM" program,
#      described in the document, "Interfacing to TAU".
# The functions in the CGM interface usually take progfile names, rather
# than depfile names, as parameters.
# 
# In this document names surrounded by angle brackets, "<>", are reps
# of parameters or return values.  The brackets are not used in actual code.
# Items surrounded by square brackets, "[]", are optional, and the brackets
# should not appear in actual code.  The "==>" symbol is used to indicate
# the format of the return value which follows.
#   
# Any CGM interface functions will return the string "CGM_FAILED" if the
# operation failed.
###########################################################################


###########################################################################
#
# To use CGM functions, the tool should source include
#    TAU/tools/inc/depfile.tcl
#
###########################################################################


###########################################################################
# Data Structures - these data structures are used internally by the 
#                   CGM interface module and are not to be accessed directly 
#                   by tools except.
#
#   depfiles_loaded -> list of program files for which depfiles are loaded.
#
#   funcs
#       funcs(<file>,<tag>,state)  -> Info for call-graph layout
#       funcs(<file>,<tag>,fold)   -> Info for call-graph layout
#       funcs(<file>,<tag>,name)   -> <name-str>
#       funcs(<file>,<tag>,class)  -> {<class-name> <class-type> <class-tag>}
#       funcs(<file>,<tag>,file)   -> {<line-num> <filename>}
#       funcs(<file>,<tag>,pos)    -> <pos-data>                     
#       funcs(<file>,<tag>,type)   -> {<par-or-seq> <type> <used|not>
#       funcs(<file>,<tag>,num)    -> <num-calls>
#       funcs(<file>,<tag>,calls)  -> <list-of-calls>
#       funcs(<file>,<tag>,childpos) -> <list-of-callsites>
#       funcs(<file>,<tag>,childline) -> <list-of-callsite-line-numbers>
#
#
#   classes
#       classes(<file>,<tag>,file) -> {<line-num> <filename>
#       classes(<file>,<tag>,name) -> <name-str>
#       classes(<file>,<tag>,fold) -> ???
#       classes(<file>,<tag>,coll) -> <COLL>
#       classes(<file>,<tag>,pos)  -> <pos-data>
#       classes(<file>,<tag>,typepos) -> <type-positions>
#       classes(<file>,<tag>,subs) -> <subclasses>       
#       classes(<file>,<tag>,fmempos) -> <member-functions>
#       classes(<file>,<tag>,basepos) -> <base-classes-and-postions> 
#       classes(<file>,<tag>,mem)  -> <member-func-name-str>
#
#
#   members
#       members(<file>,<tag>) -> {<member-name> <tag> <type>}
#
#
#   depfile(<file>,allftags)  - the ids of all functions
#   depfile(<file>,allctags)  - the ids of all classes
#   depfile(<file>,numfunc)   - number of functions defined in depfile
#   depfile(<file>,numused)   - number of functions used (called) in program
#   depfile(<file>,numprof)   - number of functions profiled
#   depfile(<file>,ino)       - inode of depfile
#   depfile(<file>,type)      - type/format of depfile
#
###########################################################################



###########################################################################
#
# Cgm_FuncList - Gets a list of functions defined in the given file 
#                (progfile or header allowed).
#
#    Usage:
#      Cgm_FuncList <file> 
#         ==> { <funcname> ... }


###########################################################################
#
# Cgm_MethodList - Gets a list of methods  defined in the given class
#
#    Usage:
#      Cgm_MethodList <progfile> <classname> <tag>
#         ==> { {<methlodname> <methodprogfile> <methodtag>} ... }


###########################################################################
#
# Cgm_FuncInfo - Gets function information from a depfile that has been 
#                loaded into memory with the Cgm_LoadDep or Cgm_LoadAllDeps 
#                functions.  The specified progfile MUST be loaded.  
#                Valid fields are: state, fold, name, class, file, pos,
#                type, num, calls, childpos, and childline.  
#                If the optional <newval> parameter is given, the 
#                function info is reset to a new value.
#    Usage:
#      Cgm_FuncInfo <progfile> <tag> <field> [ <newval> ]
#        ==> (See data descriptions)


###########################################################################
#
# Cgm_ClassInfo - Gets class information from a depfile that has been 
#                 loaded into memory with the Cgm_LoadDep or Cgm_LoadAllDeps 
#                 functions.  The specified progfile MUST be loaded.  
#                 Valid fields are: file, name, fold, coll, pos,
#                 typepos, subs, fmempos, basepos, and mem.
#                 If the optional <newval> parameter is given, the 
#                 class info is reset to a new value.
#    Usage:
#      Cgm_ClassInfo <progfile> <tag> <field> [ <newval> ]
#        ==> (See data descriptions)


###########################################################################
#
# Cgm_MemInfo - Gets member information from a depfile that has been 
#               loaded into memory with the Cgm_LoadDep or Cgm_LoadAllDeps 
#               functions.  The specified progfile MUST be loaded.  
#               If the optional <newval> parameter is given, the 
#               member info is reset to a new value.
#    Usage:
#      Cgm_GetMemInfo <progfile> <tag> [ <newval> ] 
#        ==> { <member-name> <tag> <type> }


###########################################################################
#
# Cgm_DepInfo - Gets general depfile information from a depfile that has been 
#               loaded into memory with the Cgm_LoadDep or Cgm_LoadAllDeps 
#               functions.  The specified progfile MUST be loaded.  
#               Valid fields are: path, file, allftags, allctags, numfunc,
#               numused, numprof, ino, and type.
#               If the optional <newval> parameter is given, the 
#               depfile info is reset to a new value.
#    Usage:
#      Cgm_DepInfo <progfile> <field> [ <newval> ] 
#        ==> (See data descriptions)


###########################################################################
#
# Cgm_IsDepLoaded - Boolean function returns 1 if the depfile associated 
#                   with the specified progfile is loaded into memory, 
#                   or 0 (zero) otherwise.
#    Usage:
#      Cgm_IsDepLoaded <progfile>
#        ==> <Boolean>


###########################################################################
#
# Cgm_LoadDep - Loads the depfile information for a given progfile with the
#               given cgm options.  Returns nothing.  See the CGM document,
#               "Interfacing with TAU" for option descriptions.
#    Usage:
#      Cgm_LoadDep <progfile> <cgm-option>


###########################################################################
#
# Cgm_LoadAllDeps - Loads the depfiles for ALL progfiles in the application
#                   with the given cgm options.  This may take a substantial
#                   ammount of time!  Returns nothing.
#    Usage:
#      Cgm_LoadAllDeps <cgm-option>


###########################################################################
#
# Cgm_RemoveDep - Removes the depfile information for a given progfile from
#                 memory.  Returns nothing.
#    Usage:
#      Cgm_RemoveDep <progfile>


