Generating Profiling Data

Before you can profile your application, you must set up your project to generate profiling information. To generate profiling information for your Xcode project, you must modify your target or build-style settings to include the “Generate profiling code” option. (See the Xcode Help for information on enabling target and build-style settings.)

The profiling code inside your program generates a file called gmon.out with the profiling information. (Usually, this file is placed in the current working directory.) To analyze the data in this file, copy it to the directory containing your executable prior to calling gprof, or just specify the path to gmon.out when you run gprof.

In addition to profiling your own code, you can find out how much time is spent in Carbon and Cocoa frameworks by linking against profile versions of those frameworks. To do this, add the DYLD_IMAGE_SUFFIX setting to your target or build style and set its value to _profile. The dynamic linker combines this suffix with the framework name to link against the profile version of the framework. To determine which frameworks support profiling, look at the frameworks themselves. For example, the Carbon library comes with both profile and debug versions.

Generating Order Files

An order file contains an ordered sequence of lines, each line consisting of a source file name and a symbol name, separated by a colon with no other white space. Each line represents a block to be placed in a section of the executable. If you modify the file by hand, you must follow this format exactly so the linker can process the file. If the object file name:symbol name pair is not exactly the name seen by the linker, it tries its best to match up the names with the objects being linked.

The lines in an order file for procedure reordering consist of an object filename and procedure name (function, method, or other symbol). The sequence in which procedures are listed in the order file represents the sequence in which they are linked into the __text section of the executable.

To create an order file from the profiling data generated by using a program, run gprof using the -S option (see the man page for gprof (1)). For example,

gprof -S MyApp.profile/MyApp gmon.out

The -S option produces four mutually exclusive order files:

You should try using each of these files to see which provides the largest performance improvement, if any. See Using pagestuff to Examine Pages on Disk for a discussion of how to measure the results of the ordering.

These order files contain only those procedures used during profiling. The linker keeps track of missing procedures and links them in their default order after those listed in the order file. Static names for library functions are generated in the order file only if the project directory contains a file generated by the linker’s -whatsloaded option; see Creating a Default Order File for details.

The gprof -S option doesn’t work with executables that have already been linked using an order file.

Fixing Up Your Order Files

After you generate your order files, you should look through them and make sure they are correct. There are a number of cases where you need to edit your order files manually, including the following:

• Your executable contained assembly-language files.

• You profiled a stripped executable.

• Your executable contained files compiled without the -g option.

• Your project defines internal labels (typically for goto statements).

• You want to preserve the order of routines in a particular object file.

If the definition of a symbol is located in an assembly file, a stripped executable file, or a file compiled without the -g option, gprof omits the source file name from the symbol’s entry in the order file. If your project uses such files, you must edit the order file manually and add the appropriate source filenames. Alternatively, you can delete the symbol references altogether to force the corresponding routines to be linked in default order.

If your code contains internal labels, you must remove those labels from the order files; otherwise, the function that defines the label will be split apart during the linking phase. You can prevent the inclusion of internal labels in assembly files altogether by prefixing them with the string L_. The assembler interprets symbols with this prefix as local to a particular function and strips them to prevent access by other tools such as gprof.

To preserve the order of routines in a particular object file, use the special symbol .section_all. For example, if the object file foo.o comes from assembly source and you want to link all of the routines without reordering them, delete any existing references to foo.o and insert the following line in the order file:

foo.o:.section_all

This option is useful for object files compiled from assembly source, or for which you don’t have the source.

Linking with an Order File

Once you’ve generated an order file, you can link the program using the -sectorder and -e start options:

cc -o outputFile inputFile.o … -sectorder __TEXT __text orderFile -e start

To use an order file with a Xcode project, modify the “Other Linker Flags” option in the Deployment build style of your project. Add the text -sectorder __TEXT __text orderFile to this setting to specify your order file.

If any inputFile is a library rather than an object file, you may need to edit the order file before linking to replace all references to the object file with references to the appropriate library file. Again, the linker does its best to match names in the order file with the sources it is editing.

With these options, the linker constructs the executable file outputFile so that the contents of the __TEXT segment’s __text section are constructed from blocks of the input files’ __text sections. The linker arranges the routines in the input files in the order listed in orderFile.

As the linker processes the order file, it places the procedures whose object-file and symbol-name pairs aren’t listed in the order file into the __text section of outputFile. It links these symbols in the default order. Object-file and symbol-name pairs listed more than once always generate a warning, and the first occurrence of the pair is used.

By default, the linker prints a summary of the number of symbol names in the linked objects that are not in the order file, the number of symbol names in the order file that are not in the linked objects, and the number of symbol names it tried to match that were ambiguous. To request a detailed listing of these symbols, use the -sectorder_detail option.

The linker’s -e start option preserves the executable’s entry point. The symbol start (note the lack of a leading “_”) is defined in the C runtime shared library /usr/bin/crt1.o; it represents the first text address in your program when you link normally. When you reorder your procedures, you have to use this option to fix the entry point. Another way to do this is to make the line /usr/lib/crt1.o:start or /usr/lib/crt1.o:section_all the first line of your order file.

Limitations of gprof Order Files

The .order files generated by gprof contain only those functions that were called or sampled when the executable was run. For library functions to appear correctly in the order file, a whatsloaded file produced by the linker should exist in the working directory.

The -S option does not work with executables that have already been linked with an order file.

Production of the gmon.order file can take a long time—it can be suppressed with the -x parameter.

Filenames will be missing for the following items:

• files compiled without the -g parameter

• routines generated from assembly-language source

• executables that have had their debugging symbols removed (as with the strip tool)

Reordering Procedures

Depending on the size and complexity of your application, you should pursue a strategy for ordering code that best improves the performance of your executable. Like most performance tuning, the more time you spend measuring and retuning your procedure order, the more memory you save. You can easily obtain a good first-cut ordering by running your application and sorting the routines by call frequency. The steps for this strategy are listed below and explained in more detail in the sections that follow:

1. Build a profile version of your application. This step generates an executable containing symbols used in the profiling and reordering procedures.

2. Run and use the application to create a set of profile data. Perform a series of functional tests, or have someone use the program for a test period.

3. Create order files. Order files list procedures in optimized order. The linker uses order files to reorder procedures in the executable.

4. Run the linker using the order files. This creates an executable with procedures linked into the __text section as specified in the order file.

For information on profiling your code and generating and linking an order file, see Profiling Code With gprof.

Procedure Reordering for Large Programs

For many programs, the ordering generated by the steps just described brings a substantial improvement over unordered procedures. For a simple application with few features, such an ordering represents most of the gains to be had by procedure reordering. However, larger applications and other large programs can benefit greatly from additional analysis. While order files based on call frequency or the call graph are a good start, you can use your knowledge of the structure of your application to further reduce the virtual-memory working set.

//

//  unique

//

//  A command for combining files while removing

//  duplicate lines of text. The order of other lines of text

//  in the input files is preserved.

//

//  Build using this command line:

//

//  cc -ObjC -O -o unique -framework Foundation Unique.c

//

//  Note that “unique” differs from the BSD command “uniq” in that

//  “uniq” combines duplicate adjacent lines, while “unique” does not

//  require duplicate lines to be adjacent. “unique” is also spelled

//  correctly.

//

#import <stdio.h>

#import <string.h>

#import <Foundation/NSSet.h>

#import <Foundation/NSData.h>

#define kBufferSize 8*1024

void ProcessFile(FILE *fp)

{

    char buf[ kBufferSize ];

    static id theSet = nil;

    if( theSet == nil )

    {

        theSet = [[NSMutableSet alloc] init];

    }

    while( fgets(buf, kBufferSize, fp) )

    {

        id dataForString;

        dataForString = [[NSData alloc] initWithBytes:buf length:strlen(buf)];

        if( ! [theSet containsObject:dataForString] )

        {

            [theSet addObject:dataForString];

            fputs(buf, stdout);

        }

        [dataForString release];

    }

}

int main( int argc, char *argv[] )

{

    int     i;

    FILE *  theFile;

    int     status = 0;

    if( argc > 1 )

    {

        for( i = 1; i < argc; i++ )

        {

            if( theFile = fopen( argv[i], "r" ) )

            {

                ProcessFile( theFile );

                fclose( theFile );

            }

            else

            {

                fprintf( stderr, "Could not open ‘%s’\n", argv[i] );

                status = 1;

                break;

            }

        }

    }

    else

    {

        ProcessFile( stdin );

    }

    return status;

}

unique hot.order feature1.order ... featureN.order default.order > final.order

(gdb) p vm_protect(task_self(), startpage_addr, vm_page_size, FALSE, 0);

Reordering Literal Sections

The lines in the order file for literal sections can most easily be produced with the ld and otool tools. For literal sections, otool creates a specific type of order file for each type of literal section:

• For C string literal sections, the order-file format is one literal C string per line (with ANSI C escape sequences allowed in the C string). For example, a line might look like

  Hello world\n

• For 4-byte literal sections, the order-file format is one 32-bit hex number with a leading 0x per line with the rest of the line treated as a comment. For example, a line might look like

  0x3f8ccccd (1.10000002384185790000e+00)

• For 8-byte literal sections, the order file line consists of two 32-bit hexadecimal numbers per line separated by white space each with a leading 0x, with the rest of the line treated as a comment. For example, a line might look like:

  0x3ff00000 0x00000000 (1.00000000000000000000e+00)

• For literal pointer sections, the format of the lines in the order file represents the pointers, one per line. A literal pointer is represented by the segment name, the section name of the literal pointer, and then the literal itself. These are separated by colons with no extra white space. For example, a line might look like:

  __OBJC:__selector_strs:new

• For all the literal sections, each line in the order file is simply entered into the literal section and appears in the output file in the order of the order file. No check is made to see if the literal is in the loaded objects.

To reorder a literal section, first create a “whatsloaded” file using the ld -whatsloaded option as described in section Creating a Default Order File. Then, run otool with the appropriate options, segment and section names, and filenames. The output of otool is a default order file for the specified section. For example, the following command line produces an order file listing the default load order for the __TEXT segment’s __cstring section in the file cstring_order:

otool -X -v -s __TEXT __cstring `cat whatsloaded` > cstring_order

Once you’ve created the file cstring_order, you can edit the file and rearrange its entries to optimize locality of reference. For example, you can place literal strings used most frequently by your program (such as labels that appear in your user interface) at the beginning of the file. To produce the desired load order in the executable, use the following command:

cc -o hello hello.o -sectorder __TEXT __cstring  cstring_order

Reordering Data Sections

There are currently no tools to measure code references to data symbols. However, you might know a program’s data-referencing patterns and might be able to get some savings by separating data for seldom-used features from other data. One way to approach __data section reordering is to sort the data by size so small data items end up on as few pages as possible. For example, if a larger data item is placed across two pages with two small items sharing each of these pages, the larger item must be paged in to access the smaller items. Reordering the data by size can minimize this sort of inefficiency. Because this data would normally need to be written to the virtual-memory backing store, this could be a major savings in some programs.

To reorder the __data section, first create an order file listing source files and symbols in the order in which you want them linked (order file entries are described at the beginning of Generating Order Files). Then, link the program using the -sectorder command-line option:

cc -o outputFile inputFile.o … -sectorder __DATA __data orderFile -e start

To use an order file with a Xcode project, modify the “Other Linker Flags” option in the Deployment build style of your project. Add the text -sectorder __DATA __data orderFile to this setting to specify your order file.