CallgraphReadmee

Introduction

Developers who are working with source code may find it difficult to track and understand the flow of execution. Visualizations can help.

The purpose of the callgraph.py script and sub-scripts is to easily generate useful call graphs and control flow graphs of important functions.

Required Tools and Setup

For all:

python : 2.7.3  (required in search path, use "python -V" to verify)

For Windows:

- SciTools Understand 5.0
    - installation steps:
        - download any 5.0 build from https://scitools.com/download/all-builds/
        - install (choose option to set PATH variables for all users)
        - open Understand.exe
        - in top menu, click Help
        - Legacy Licensing
        - Add a License
        - Specify License Server
        - Server Name: license-wan-21-sd1 (alternative: license-wan-21-sd2)
        - Port: 9000
- machine must be on Qualcomm internal network

For Linux:

- machine must be Qualcomm-managed
- machine must be on Qualcomm internal network

Command and options

Arguments:

-v, --variant

which variant to build for this target. Example: LA

-e, --verbose

verbose output

-a, --auto

running on an automated system, do not prompt user for input

Windows:

Open cmd.exe AS ADMINISTRATOR

Usage:
      python3 QcomPkg/SocPkg/<target>/callgraph.py -v/--variant VARIANT [-e/--verbose] [-a/--auto]

Linux:

Usage:
      QcomPkg/SocPkg/<target>/callgraph.py -v/--variant VARIANT [-e/--verbose] [-a/--auto]
      (NOTE: call directly as an executable. Do not use "python" prefix)

Note

If you get a message on Linux as below, you need to call directly as an executable instead of using “python” prefix.

#————————————————–

This application failed to start because it could not find or load the Qt platform plugin “xcb” in “”.

Available platform plugins are: xcb.

Reinstalling the application may fix this problem.

Aborted (core dumped)

#————————————————–

Additional information to aid maintainence

HARDCODED VARIABLES

  • QcomPkg/spy_buildex.py

    CLANG_TOOL_NAME (i.e. CLANG100)

  • QcomPkg/Tools/callgraph/und_static_analysis.py

    COMPILER_NAME (i.e. clang)

  • QcomPkg/SocPkg/<target>/callgraph.py (most of this file)

High Level Operation

Note

On Linux, when invoking python scripts from the command line, execute it directly (i.e. $callgraph.py) instead of using the python interpreter directly (i.e. $python3 callgraph.py) because some important shebang lines need to set up the environment before the python interpreter executes.

callgraph.py is the top-level script, and is target_specific. It calls the common python sub-scripts. In boot.xf, this script should first flatten any desired boot config table or entry (such as sbl1_config_table) by calling flatten_config_table.py. It will then be able to analyze it as its own special graph because function pointers can not be analyzed directly.

Note

Flatten_config_table.py is capable of flattening any boot config table or single entry based on the parameters passed to its main() function. It just needs the name of the table/entry and the path to the c file that it is located in.

The order of operations is as follows:

  • callgraph.py (top-level, target-specific)

    • flatten_config_table.py

      1. parse typedef struct of boot config table entry

      2. parse table/entry passed as parameters

      3. output flattened c file (“<table name>_flattened.c”)

    • und_static_analysis.py

      1. cleanall for component only (to ensure no compiler commands are skipped in step 2)

        • spy_buildex.py

          1. run buildex.py and extract the toolchain path that was used

      2. set up buildspy wrapper (so it can capture compiler commands)

      3. buildex for component only (to generate database)

        • spy_buildex.py

          1. run buildex.py with a spoofed toolchain path

      4. cleanall for component only (to ensure the tool path is uncached)

      5. add/remove files from database if specified in parameters

      6. analyze database

    • draw_function_graph.py

      1. search in database for function specified in parameters

      2. (on Linux) start virtual Xvfb display

      3. generate output graph image

      4. (on Linux) stop virtual Xvfb display

repeats und_static_analysis.py and draw_function_graph.py for each component and variant

Note

draw_function_graph.py can be run standalone, provided a database was already created. Simply specify what functions you want graphs for and what graph types (run draw_function_graph.py –help for usage).

These graphs can be generated on Qualcomm machines on the internal network, and automatically generated as a part of the Package Warehouse process and shipped with source.

callgraph_utils.py is the shared common file used for environment checks/setup, variable setup, and licensing check/setup. It is also called by the shebangs of callgraph.py and draw_function_graph.py to set up environment variables.

Working Directory

Build/callgraph/

Dependencies/Setup

Windows:

- python 2.7.3 (same as buildex) with "python" on search path
- python 3+ (required by SciTools Understand python API) with "python3" on search path
- 'understand' python module (part of SciTools Understand 5.0 installation)
- und.exe (part of SciTools Understand 5.0 installation)
- buildspy.exe (part of SciTools Understand 5.0 installation)

Linux:

- python 2.7.3 (same as buildex) with "python" on search path
- python 3+ (/pkg/python/3.2/bin/python3)
- 'understand' python module (/pkg/qct/software/scitools/5.0.955/bin/linux64/Python)
- und (/pkg/qct/software/scitools/5.0.955/bin/linux64)
- buildspy (/pkg/qct/software/scitools/5.0.955/bin/linux64/buildspy)
- Xvfb and Xfnts (/pkg/qct/software/Xvfb/)

Note

if the scitools licensing server goes down, callgraph_utils.py will use the backup (/pkg/qct/software/scitools/5.0.955_alternate/bin/linux64)