Jump to the first introduction of a topic, from the links below.
Download the entire library and all the examples.
Return to the Introduction.

Note that most of these items, such as pmc_lib.h, have an underscore in the name that may be obscured by a link's underline.

The library's principal data types to be understood are
 

The library's principal functions are
 

To take the tour of rabbit, start with the command-line option syntax, and select from the option descriptions as needed. Examples are included with the descriptions. For a progressively more detailed tour of the PMC library, start with pmc_lib.h, and follow the sequence of examples.

• rabbit -- run a program as a child process, sampling the hardware performance counters
• Design concepts and current implementation
• A quick example using the PMC library: rabbit.c
• Command-line options -- syntax
• Command-line arguments from 'rabbit -h' on a Pentium III:

rabbit  [-help]
      [-version]   [-processor]
      [-list]      [-codes]       [-descriptions]
      [-Input]
      [-Clean n]   [-Stats [0|1|2] ]   [-Raw [0|1|2] ]
      [-group [0|1|2|3|4|5|6|7|8|all] ]
      [-number    event_replication_factor]
      [--events   m,n]   [-Label text]
      [--duration m,n]
      [--user     m,n]
      [--os       m,n]
      [--mesi     m,n]   [--bus_agent  m,n]   [--MMX  m,n]
      [--compare  m,n]   [--invert     m,n]
      [--Enable m,n]   [--PC m,n]   [--APIC m,n]
      [-mhz       Mcycles_per_sec]
      [-sample    samples_per_sec]
      [-rotate    samples_per_rotate]
      [-flush     samples_per_flush]
      [-trim      initial_samples_to_omit]
      [-input     input_file]
      [-output    output_directory]
      [-Verbose]
      [-alignment]
      [-Measure [0|1|2] ]
      [--]  command [arg ...]

  Intel Pentium III, 84 events, 2 counters

• Exit status
• Authors, acknowledgments, disclaimers, copyright notices
• More examples
• rabbit.c  --  measure a child process by periodic sampling
• rabbit2.c  --  measure this code by periodic sampling
• rabbit3.c  --  measure this code by direct access
• rabbit4.c and driver scripts rabbit4.sh, rabbit4a.sh  -- select a test case, print "interesting" events
• rabbit5.c and driver script rabbit5.sh  -- select a test case, print "interesting" events
• rabbit6.c and driver scripts rabbit6.5.sh, rabbit6.sh  --  measure a function, print "interesting" ratios of events
• rabbit7.c and driver script rabbit7.sh  --  overhead estimation, print "interesting" events
• rabbit8.c and driver script rabbit8.sh  --  select a test case, print "interesting" events
• mem_events.c and driver script mem_events.sh  --  test memory access, print "interesting" events
• mem_test.c  and driver scripts mem_test.sh, mem_test.plot, mem_test.awk  -- processor and memory speed estimates
• integer multiply uses the floating-point unit  (driver script)
• integer divide uses the floating-point unit  (driver script)
• cpuid.c  --  inspect the results of the cpuid instruction  (for developers only)
• pmc_toggle.c  --  play with the switches (for developers only)
• pmc_lib.h
• libpmc.a
• Compiler options as configured, pmc_options
• The complete list of compiler options
• exit()
• pmc_control_t
• pmc_control_null
• pmc_control_print()
• System-dependent components, hardware control fields
• pmc_getargs()
• Select events from the command line, modify components of pmc_control_t
• pmc_event_set_t
• Select events from the program
• pmc_events.h
• pmc_event_label_t
• pmc_event_counters
• pmc_event_valid()
• pmc_event_name()
• pmc_event_description()
• Pentium Pro/II/III events
• Diagram showing the relation between events and processor/cache/memory components
• Suggested event pairs, as a rabbit input file
• Nearly complete coverage
• Data references related to other events
• Events vs. cycles for some events
• hardware registers
• pmc_uint32_t
• pmc_uint64_t
• Control Registers -- CR0, CR4, EFLAGS
• Model-Specific Registers -- TSC, PMC control, PMC counters
• Model-specific semantics
• pmc_query, pmc_test
• pmc_enable, pmc_disable
• Exclusive access
• /dev/pmc
• /proc/pmc
• pmc_open()
• pmc_close()
• pmc_load, pmc_unload
• pmc_data_t
• Hardware cycle and event counters, user interface
• pmc_cycle_t
• pmc_event_t
• pmc_cycle_bits
• pmc_event_bits
• pmc_cycle()
• pmc_event()
• pmc_second()
• pmc_seconds_per_cycle
• pmc_counter_t
• Cycle and event accumulators, user interface
• pmc_counter_init()
• pmc_counter_reset()
• pmc_counter_print()
• pmc_selector_t
• pmc_cycles_t
• pmc_events_t
• pmc_counters_t
• pmc_cycles_bits
• pmc_events_bits
• pmc_sum_cycles()
• pmc_sum_events()
• pmc_seconds()
• Computing events per second
• pmc_counter_t
• stats, level of statistical detail
• pmc_intervals_t
• pmc_stats_t, pmc_rates_t
• pmc_intervals()
• pmc_min_cycles(), also max, mean, variance
• pmc_min_events(), also max, mean, variance
• pmc_nonzero_intervals()
• pmc_min_events_per_cycle(), also max, mean, variance
• pmc_ratio_intervals(), event i / event j
• pmc_min_ratio_events(), also max, mean, variance
• Data acquisition
• pmc_start()
• pmc_select()
• pmc_read()
• pmc_accumulate()
• pmc_accumulate_counter()
• pmc_reset()
• overhead calculation
• pmc_select_clock()
• pmc_read_clock()
• pmc_accumulate_clock()
• Report generation
• Making a time-line
• pmc_print_results()
• Interrupts and signal handlers
• How to design an experiment
• Advanced topics
• pmc_configure()
• pmc_control_alloc(), pmc_control_free()
• pmc_data_alloc(), pmc_data_free()
• pmc_counter_alloc(), pmc_counter_free()
• pmc_run_command()
• pmc_begin_sampling(), pmc_end_sampling()
• A comprehensive example
• Example: the Stream benchmark
• Example: Pentium Pro micro-operations
• Installation instructions
• Intel manuals
• AMD manuals

• version 2.01, for Linux 2.[024].x kernels and GCC 3.0

• pmc_lib.h
• pmc_arch.h
• pmc_asm.h
• pmc_events.h
• pmc_sys.h
• pmc_dev.h
• pmc_private.h
• pmc_options.h

• pmc_processor.c
• pmc_control.c
• pmc_events.c
• pmc_getargs.c
• pmc_job.c
• pmc_lib.c
• pmc_dev.c
• pmc_dev_2_0.c  (Linux 2.0 kernel, Intel processors only)
• pmc_dev_2_2.c  (Linux 2.2 kernel, Intel or AMD processors)
• pmc_dev_2_4.c  (Linux 2.4 kernel, Intel or AMD processors)
• pmc_able.c
• pmc_test.c
• Makefile
• README
• Instructions
• Bug_reports

• uops, uops.awk
• cycles, cycles.awk
• stalls, stalls.awk
• mesi
• in.sample
• in.sweep
• in.duration
• in.user_os