Documentation for lib_footprint.pl

NAME

lib_footprint.pl

SYNOPSIS

Perl script that reads in an XML file representation of a linker map file and reports how much memory each library occupies.

USAGE

   lib_footprint.pl [options] <xml file>

OPTIONS

 --sect_classes=<file> : Configuration file that classifies sections
 --cg_xml_version      : Print out the version of the cg_xml package in use

HOW TO CREATE THE XML FILE

Generate the XML version of the map file with the linker option --xml_link_info=<file>

You must use a relatively recent linker which supports the --xml_link_info option. However, there is NO requirement as to which version of the tools were used to create the libraries being linked in. In other words, this script will work even if some of the libraries were built with old compiler tools.

NOTES ON THE OUTPUT

STACK AND HEAP SIZES

Gets fooled on overall stack and heap (used by malloc) sizes. That is not defined in input sections where all the size information is gathered. Those sizes are assigned directly by the linker to the output section.

DIFFERENT RESULTS VS. OTHER METHODS

Other methods for measuring the size of a library may get a different result than this script. This script only measures the size of library modules actually used by the application. If a library module is never referenced, the linker does not bring it in, this script does not see that module, and it does not count when summing up the size of the library. Other methods for measuring a library typically add up the the size of every module in the library with no consideration for the possibibility one or more modules may not be linked in.

HOLES ARE NOT COUNTED

This script considers the size of each section as it is pulled out of library, before it is combined with other input sections to form a larger output section. It is possible for holes to occur between input sections. Such holes are not counted by this script.

Consider the following example:

This script will say that example.lib contributes 100 bytes to the final link. Measuring the size of the output section .example_text with other methods (such as using sectti.pl from the OFD directory) will show that the section .example_text is 114 bytes. Why the difference?

A hole of 64 - 50 = 14 bytes, in the section .example_text, lies between the code sections from the two files in example.lib. That hole is not counted by this script.

It is, in general, impossible for such holes to be counted by this script. They can occur anywhere, for nearly any reason. They can occur when input sections from libraries (which are counted by this script) are combined together with input sections from normal object files (which are not counted by this script). In practice, size of such holes is rarely a factor.

NOTE ON LINKING WITH -CR

If you link with -cr, use --sect_classes to mark .cinit as a section to IGNORE (details below).

HOW SECTIONS ARE CLASSIFIED

The final report shows how much code, data, and uninitialized data each library contributes to overall code size. This is achieved by classifying each output section as one of CODE, DATA, or UDATA. The classification scheme is a simple one based on the names of the sections. The default scheme is illustrated in the subroutine "default_sect_classes". This should cover many common cases. Since not all cases are covered, the option "--sect_classes=file" is provided to give you the ability to change the section classification (file syntax below). This script should be accompanied by the example section classification file "classes.txt". It defines the section classifications equivalent to the script default. Thus, it serves as a good starting point for additions or modifications.

Note you can also mark sections as IGNORE. As the name implies, such sections are ignored.

If -cr (instead of -c) is used on the link, then the .cinit section should be marked IGNORE. This script cannot tell the difference between a .cinit section that is loaded in memory (linked with -c) and one that is only a copy section (linked with -cr) the loader reads to perform the global variable initialization at load time.

SYNTAX OF SECTION CLASSIFICATION CONFIGURATION FILE

   <section name> <space or ',' or '='> <CODE|DATA|UDATA|IGNORE>

Each section specification must be contained on a single line

Optional space can surround the section name or classification

Blank lines are ignored

'#' is for comments. Anything on a line after '#' is ignored.

PERL VERSION REQUIRED

This script was written using Perl version 5.8.3. It may not work with earlier revisions of Perl.

 Documentation for lib_footprint.pl