readme

linux下的多线程调试工具

==============================================================================

            NPTL Trace Tool (PTT - POSIX Thread Trace Toolkit)

==============================================================================

  1) installing
  2) collecting the information
  3) displaying the trace
  4) measuring contention
  5) supported architectures
  6) support and troubleshooting
  7) note to distribution maintainers
  
==============================================================================
  1) installing
==============================================================================

There are 2 steps in the installation process:
* Patching and building the glibc so that you can use it with PTT
* Building PTT tools

First, you have to download glibc source from http://ftp.gnu.org/gnu/glibc.
You need at least glibc 2.3.4 to use PTT. If it is available, download the
same version as the one already installed on your Linux system.

Go to the patch_glibc directory and run the install_glibc.sh script with the
following arguments:
* directory where you want to build the glibc
* glibc source directory
* patch to apply to the glibc (possible patches are in the patch_glibc
  directory. Choose the one which corresponds to your glibc version).

This can take a long time because the glibc needs to be compiled twice !

Note: in no case your original glibc installed on your system will be affected
by this process. PTT works with a copy of a glibc subset (libpthread) that
doesn't need to be installed in a system directory.

Then, return to the main directory of PTT to build PTT tools. This is done by
running:
$ ./configure
$ make
$ make install

The most commonly used option for configure is --prefix=install_directory.

See INSTALL for more information about the installation process.

==============================================================================
  2) collecting the information
==============================================================================

We now assume that $DIR is your installation directory (specified in the
--prefix option).

Tracing an application is pretty simple. First, compile your multithreaded
application. You can now run it without tracing, because it uses your standard
glibc.

To trace your application, use the following command:
$ DIR/bin/ptt_trace my_program

ptt_trace uses the patched libpthread. An external daemon attend to collect
information generated by the traced library. Data is stored in a compact
format in a binary file named trace_[time]_[pid].bin. Use the -n option to
change the prefix of the binary file.

On some (rare) systems, dynamic linkage to libpthread don't work fine, even
with the same original and patched glibc version. In this case, you need to
link your application to the instrumented glibc previously built. The file
patch_glibc/flags.txt created when building the glibc contains gcc flags to
use for your system. Then, you can trace your application as before:
$ DIR/bin/ptt_trace my_program

Note: don't remove the built glibc if you have to link applications as
described above.

Read the manual for the complete documentation.

==============================================================================
  3) displaying the trace
==============================================================================

To visualize the trace stored in the binary file trace_[time]_[pid].bin 
in a textual format use the ptt_view command:
$ DIR/bin/ptt_view [options] trace_[time]_[pid].bin

The most useful options are:
* -t: output the trace in a readable textual format
* -r: output the trace in raw format useful for parsing
* -a alias_file: this is discussed later

For example:
$ DIR/bin/ptt_view -t trace_[pid].bin

There are also ptt_paje for a graphical format and ptt_stat for displaying 
information on the trace. Read the manual for the complete documentation.

When displaying the trace, threads and NPTL objects (mutex, sem, cond_var,
barrier) are identified by their address. If you have many of them in one
output file, the result may become difficult to read and understand. Aliases
are names you give to replace threads and objects addresses. An aliases file
is created by including alias.h in your program source (alias.h is installed
in $DIR/include) and using the following three macros: alias_init,
new_thread_alias and new_object_alias.

For example, at runtime, the following program (my_program.c) will create a
file called 'alias' with aliases for the two threads and the mutex:

    #include <alias.h>
    #include <stdio.h>
    #include <pthread.h>

    pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
    FILE *fd;

    void *func () {
        new_thread_alias (fd, "func");
        pthread_mutex_lock (&mutex);
        pthread_mutex_unlock (&mutex);
        return NULL;
    }

    int main () {
        pthread_t thread;
        int ret;

        fd = alias_init ("alias");
        new_thread_alias (fd, "main");
        new_object_alias (fd, &mutex, "my_mutex");

        if (ret = pthread_create (&thread, NULL, func, NULL))
            printf("Thread creation failed: %d\n", ret);

        pthread_join (thread, NULL);
        return 0;
    }

$ gcc -I $DIR/include -lpthread -o my_program my_program.c
$ ptt_trace -n trace my_program

You can now compare the outputs of the two following commands:
$ ptt_view -t trace.bin
$ ptt_view -t -a alias trace.bin

==============================================================================
  4) measuring contention
==============================================================================

PTT provides three kinds of information to measure contention in your
application:
* elapsed time: difference between the last and first trace point timestamps
  in the binary file
* contention time per thread: waiting time for each thread
* contention time per NPTL object: waiting time for each mutex, barrier,
  cond_var and semaphores.

Use the ptt_contention command. The most useful option is -a alias_file, which
behaves in the same way than ptt_view -a option. For example:
$ ptt_contention -a alias trace.bin

Percentages displayed show the impact of each thread or NPTL object in the
contention. For threads, percentage of waiting time in relation to the elapsed
time is also given.

Read the manual for the complete documentation.

==============================================================================
  5) supported architectures
==============================================================================

PTT aims to support different 32 and 64 bits architectures:
* Intel 32 bits (ia32)
* Intel 64 bits (ia64)
* IntelEM64T and AMD64 (x86_64)
* PowerPC 32 and 64 bits (ppc) 

Problems can occur on x86_64 and ppc (PTT has not been fully tested on these
architectures). Please, report them on the project mailing list.

Note: traces can be collected on a machine and visualized on an other,
provided that they have the same architecture size (32 or 64 bits).

==============================================================================
  6) support and troubleshooting
==============================================================================

You can find additionnal support on the
[e-mail] mailing list.
See http://sourceforge.net/projects/nptltracetool for more information.

Any questions or suggestions are welcome...

==============================================================================
  7) note to distribution maintainers
==============================================================================

Thanks to a large amount of effort to integrate PTT into the glibc, the glibc
can be easily built with both traditional NPTL and NPTL with PTT support. See
doc/glibc_with_ptt for the detailed process of how to do that.