C Programmer's Toolbox/PC
Kenji Hino
Kenji Hino is a member of The C Users' Group technical staff. He holds a B.S.C.S. from McPherson College and an undergraduate degree in metalurgy from a Japanese university. He is currently working toward an M.S.C.S at the University of Kansas.
Unlike UNIX, MS-DOS has no standard utility programs to support C programmers in program development or maintenance. In the past, C programmers have developed their own tools from scratch or ported tools from other operating systems to MS-DOS. UNIX tools have been ported most, simply because they are the "right" tools to improve programmer productivity. This report looks at a collection of UNIX-like tools, C Programmer's Toolbox/PC revision 2.0 by MMC AD Systems.
Component
The Toolbox/PC consists of Volumes I and II, which are available separately or together. I recommend getting both. Each volume includes two IBM 360K disks and costs $99.95; both volumes together go for $175. The manual (in a binder) describes both volumes, regardless of whether you purchase Volume I, II, or both. The C Programmer's Toolbox is available from MMC AD Systems, Box 360845 Milpitas, CA 95035, phone (408) 263-0781. Although the Toolbox/PC runs on PC/MS-DOS, MMC AD Systems also distributes versions of the Toolbox for the Macintosh MPW and the Sun UNIX system.
The installation of the Toolbox on either a floppy disk or hard disk system is straightforward; just copy all files from the distribution to your disk. If you install the Toolbox on hard disk systems, be sure that the path is set correctly.
The Tools
The Toolbox includes 21 tools (see Table 1) . All the tools are command-line driven. The corresponding UNIX tools are also listed in the same table. The tools help analyze the structure, format and execution of programs, manipulate and/or modify program input/output data, or verify program input/output data (see Figure 1) .
Covering all 21 tools in a report this size is impractical and undesirable. Thus, I will focus on the analytical tools, CFlow, PMon and CritPath. These tools are mainly used to understand a program's structure and to analyze the performance of your application program for the enhancement.
CFlow
Whether developing or maintaining a program, as the program becomes larger, you tend to lose sight of the overall program structure. Discerning the inter-relationships between modules becomes harder as the program grows. Even worse, you may have to study code written by somebody else.
CFlow is a tool for studying code. It scans one or more C source files to generate reports that describe the hierarchy of both defined and invoked functions (external or library functions).
Figure 2 shows a program flow tree, one of the reports produced by CFlow. (The analyzed source code is shown in Listing 1 and is adapted from a program in the CUG PD Library. The original author is Richard Threlkeld.) The line indentation indicates the level of function invocations. If the same function is referenced more than once, the line number of the last reference is attached to the beginning of the line. An asterisk (*) indicates whether the function is an external or run-time library function. Within the parentheses following a function name is the source filename and a starting line number of the function definition.
In order to obtain the desired result, you must specify the dash/slash options appropriately. For example, function names at each level of a CFlow tree are displayed in alphabetical order by default. If you want function names displayed as they are encountered, use the -e option. In addition, when using multiple input files, the -f option is useful to display the location of each function.
In this version 2.0, many improvements were made over the previous version. CFlow now reports a function pointer (such as (*a) ()) or function address (such as f(); a = f;). It also has a virtual memory system that handles programs of unlimited size (true for some of the other tools, too).
The biggest improvement is that CFlow now automatically preprocesses your source code. That is, it recognizes #if directives to read and process the appropriate portions of your code. This, however, creates one problem. If a function is a macro, it is expanded and replaced with some system-level function, surprising you with some unfamiliar function name in the report, such as _filbuf() instead of getc(). This can be solved by turning off the preprocessor with the p switch, thereby sacrificing all the preprocessor benefits.
Along with the CFlow Tree, CFlow generates a Master Define Function List (a list of caller and callee), an Undefined Function List (a list of external or library functions) and Function Called by List (a list of callee and caller) when you specify the proper dash/slash options.
Using CFlow, the programmer can easily and quickly understand how a program is structured and which module is invoked by which module. To understand visually, you can draw the structure diagram as in Figure 3, based on the Program Flow Tree. In Figure 3 for example, if a portion of the code in crc_update() is modified, you know from the reports which other functions will be affected (in this case, crc() and crc_finish()).
PMon And CritPath
The execution profiler PMon is a tool which analyzes a program. It determines how much execution time is spent on each symbol (functions or BIOS/DOS calls) or program area.
During program execution, PMon resides in memory with the target program, intercepts the program at regular intervals and examines the CS: IP register of the target program to determine which section of code is currently being executed. PMon tracks this information for each intercept and, using the information from the .MAP file (symbol entries), generates a set of reports.
I tested PMon using the CRCK (Cyclic Redundancy ChecK) program CRC15.EXE. The program listing of CRC15 is in Listing 1; it must be compiled and linked to generate a .MAP file. The .MAP file is then processed by MapVar and placed into PMon with the target executable program. Figure 4 shows two reports resulting from monitoring CRC15.
The first report is the program execution summary, which gives the complete synopsis of the program's execution. Descriptions for certain summary headings are:
- Total execution clicks. The total number of clock ticks recorded in the program initiation, execution, and termination.
- Total monitored hits. The actual number of clock ticks recorded during program execution.
- Total symbol entries. The total number of symbols (function names) used in the program.
- Number of symbols hit. The number of symbols detected in the execution.
- Total symbols hits. The total number of times PMon found the program executing as opposed to BIOS, DOS, or other resident programs.
- Time in program. The total time spent in the program vs. BIOS/DOS functions and other activities (Time below/above).
- Time in BIOS/DOS. The total time spent in BIOS/DOS functions.
The second report, the Symbol execution Summary, shows where a monitored program is executing within itself, excluding DOS calls.
Abs Adr — the starting address (segment:offset) of asymbol.
Hits — the total number of times PMon found the execution of a symbol.
Loc% — the percentage of activity of a symbol when compared with the total execution excluding DOS calls.
Tot% — the percentage of activity of a symbol when compared with the total execution including DOS calls.
Entry Name — Symbol name.
In this example, PMon detected that function crc_update(), whose starting address is 0:011e, executed 50 times and took 63.5% of total execution time excluding DOS calls and 54.3% of total execution including DOS calls.
In addition, PMon generates a BIOS Interrupt Summary, a DOS Function Call Execution Summary Report and DOS Function Call Execution Detail Report showing the statistics of BIOS/DOS operations performed in the program execution such as Character input/output, File input/output, etc.
Although these reports provide a good amount of information about software performance, further analysis can be done with CritPath command.
CritPath determines the critical path of a program by analyzing the reports generated by CFlow and PMon commands. A program's critical path is the sequence of functions called from main() that consumes more execution time than any other sequence.
Figure 5 shows a Critical Path Report generated by CritPath. The report provides the primary information necessary to improve a program's performance. The report shows a list of the 20 functions that used the most execution time (Top 20 Functions in Actual Time), a list of the 20 functions that by themselves and through other functions that they called used the most execution time (Top 20 Functions in Cumulative Time). Finally, the reports provide a list of the functions that comprise the critical path of the program. In this example, the critical path is the sequence of functions crc() and crc_update(). CritPath also generates both a Function Summary Report that evaluates the performance of all functions and system calls in the program and a Weighted Hierarchical Program Flow Tree.
Using the statistics produced by PMon and CritPath, programmers can spot places where performance could be improved. However, these tools only identify weak spots in the program and don't come up with the method to improve the performance. Such information might be obtained from books such as Supercharging C With Assembley Language by Harry Chesley, Mitchell Waite, The Waite Group.
Conclusion
Overall, compared to UNIX tools, the Toolbox tools have more options and provide more detailed information, helping the programmer to take more control over program output. On the other hand, he or she must read the manual very carefully and specify the appropriate options that will generate the desired result. Furthermore, the input source code for some tools should be not only syntactically correct but done in good programming style, even if the program compiled fine. Otherwise, the output information might come out confusing. For example, the inappropriate choice of options and poor programming style (such as Listing 1) cause CFlow to report an identifier, crc as a function address, not as a variable (crc is used for a function name and variable name. This can be detected by CXref.). CFlow also doesn't distinguish between function invocation and function declaration inside a function.
For beginners, the Toolbox can be a good starting point for using tools to improve productivity since the commands are very uniform and the manual is well written. In the manual, each tool is uniformly explained using sample results. In particular, observations and suggestions about the reports generated are honest and good advice for users.
For advanced programmers, the combination of CFlow, PMon and CritPath can give them clues for fine tuning or improving software performance either after the program has been developed or when it is about to be updated. CFlow, CPrint, CXref and CLint can be used to study existing programs and will greatly reduce maintenance cost.
