Oprofile API Proposal

Data Types
op_t An opaque data type which represents an instance of Oprofile API.
 
Function Summary
void op_create_instance()

Creates a new instance of the API.
void op_set_sep(op_t * op_pt, unsigned int sep_option)

Sets the separation options of op_pt.
void  op_clear_all_spec(op_t * op_pt)
         
Clear all profile spec of op_pt.
void  op_add_image_spec(op_t * op_pt, const char * image_name)

Add image_name to the profile spec of op_pt.  image_name is a full path of any binary.  Samples that follows the criteria of profile spec will be returned.
void  op_remove_image_spec(op_t * op_pt, const char * image_name)

Remove image_name from profile spec of op_pt.
void  op_clear_image_spec(op_t * op_pt)

Clear all image from profile spec of op_pt.
void  op_add_session_spec(op_t * op_pt, const char * session)

Add session to profile spec of op_pt.  session is a valid session name received from iterate_sessions(...)
void  op_remove_session_spec(op_t * op_pt, const char * session)

Remove session from profile spec of op_pt.
void  op_clear_session_spec(op_t * op_pt)

Clear all session from profile spec of op_pt.
void  op_add_cpu_spec(op_t * op_pt, unsigned int cpu)

Add cpu to profile spec of op_pt.  CPU is a valid number between 0 to number of cpu - 1.
void  op_remove_cpu_spec(op_t * op_pt, unsigned int cpu)

Remove cpu from profile spec of op_pt.
void  op_clear_cpu_spec(op_t * op_pt)

Clear all cpu from profile spec of op_pt.
void  op_add_tgid_spec(op_t * op_pt, pid_t tgid)

Add tgid to profile spec of op_pt.  tgid is a valid tgid that exists during the profiling duration
void  op_remove_tgid_spec(op_t * op_pt, pid_t tgid)

Remove tgid from profile spec of op_pt.
void  op_clear_tgid_spec(op_t * op_pt)

Clear all tgid from profile spec of op_pt.
void  op_add_tid_spec(op_t * op_pt, pid_t tid)

Add tid to profile spec of op_pt.  tid is a valid tid that exists during the profiling duration.
void  op_remove_tid_spec(op_t * op_pt, pid_t tid)

Remove tid from profile spec of op_pt.
void  op_clear_tid(op_t * op_pt)

Clear all tid from profile spec of op_pt.
void  op_add_event_spec(op_t * op_pt, const char * event_name)

Add event_name to profile spec of op_pt.  event_name is a valid event name returned from iterate_events(...)
void  op_remove_event_spec(op_t * op_pt, const char * event_name)

Remove event_name from profile spec of op_pt.
void  op_clear_event_spec(op_t * op_pt)

Clear all events from profile spec of op_pt.
void  op_iterate_profile_class(op_pt * op_pt,
    unsigned int (*callback)
    (const char * name, const char *event,
     const char * count, const char unitmask,
     const char * cpu, const char tgid,
     const char tid))

Iterate each profile class and call the callback with its members as parameters.
void  op_iterate_sessions(op_pt * op_pt,
    unsigned int (*callback) (const char * name))

Iterate each session and call the callback with its name.
void  op_iterate_events(op_pt * op_pt,
    unsigned int (*callback) (const char * name))

Iterate each event  and call the callback with its name.
void  op_iterate_summary(op_t * op_pt,
    unsigned int(*callback)
    (const char * image_name, unsigned int count_size,
     unsigned int [] count_array)

Iterate each summary and call the callback with its members as parameters.
void  op_iterate_summary_deps(op_t * op_pt, const char * image_name,
    unsigned int(*callback)
    (const char * image_name, const char * dep_image_name,
     unsigned int count_size, unsigned int [] count_array));

Iterate each dependents of image_name and call the callback with its members as parameters.
void  op_iterate_symbol(op_t * op_pt,
    unsigned int (*callback)
    (const char * symbol_name, unsigned int symbol_size,
     unsigned long vma, const char * app_name,
     const char * image_path, unsigned int count_size,
     unsigned int [] count_array)

Iterate each symbol call the callback with its members as parameters.
void  op_iterate_symbol_sample(op_t * op_pt,
    char * symbol_name, char * image_path,
    unsigned int(*callback)
    (const char * symbol_name, const char * image_path,
     const char * filename, unsigned int linenr,
     unsigned long vma, unsigned int count_size,
     unsigned int [] count_array)

Iterate each symbol sample of symbol with symbol_name in image image_path and call the callback with its members as parameters.
const char * op_demangle(op_t * op_pt, char * symbol_name)

Demangle mangled symbol name.

Method Detail

op_create_instance

     Create an instance of the opaque data type and return to the caller.        
     Returns:
The newly created instance.

op_set_sep

      Sets the separation of the returned samples.       
     Parameters:
op_pt - Instance to act up.
sep_options - Bitmask of separate options.  Valid bitmasks are combinations of SEP_CPU,  SEP_LIB, SEP_TID, SEP_TGID, SEP_UNITMASK.  
        If no separate options is set, all data are merged by default.
     Returns:
The newly created instance of op_t.

op_clear_all_spec

      Clear all previously saved profile specs.      
     Parameters:
op_pt - Instance to act upon.

op_add_image_spec

      Add image to profile spec.      
     Parameters:
op_pt - Instance to act upon.
        image_name - The absolute path of the image name to be included.  If no
        image name is set, samples of all images will be returned.

op_remove_image_spec

      Remove image name from profile spec.    
     Parameters:
op_pt - Instance to act upon.
        image_name - The absolute path of the image name to be removed.  

op_clear_image_spec

      Clear all previously saved image paths of profile specs.      
     Parameters:
op_pt - Instance to act upon.

op_add_session_spec

      Add session name to profile spec.      
     Parameters:
op_pt - Instance to act upon.
        session - Session name of the session to be included in the results.  
        If no session name is set, samples of current session is returned.  By
        default, current session has path of /var/lib/oprofile/samples/current

op_remove_session_spec

      Remove session name from profile spec    
     Parameters:
op_pt - Instance to act upon.
        session - Session name to be removed.

op_clear_session_spec

      Clear all previously saved session names.      
     Parameters:
op_pt - Instance to act upon.

op_add_cpu_spec

      Add a particular cpu to profile spec.      
     Parameters:
op_pt - Instance to act upon.
        cpu - CPU number.  If added, only samples generated from added cpu
are returned.  If no CPU is set, samples from all cpu are returned.

op_remove_cpu_spec

      Remove a particular cpu from profile spec.      
     Parameters:
op_pt - Instance to act upon.
        cpu - CPU number to be removed.

op_clear_cpu_spec

      Clear all previously saved cpu number.      
     Parameters:
op_pt - Instance to act upon.

op_add_tgid_spec

      Add a particular tgid to profile spec.      
     Parameters:
op_pt - Instance to act upon.
        tgid - tgid, if added, only samples from this particular thread group
is returned.  If no tgid is set, samples from all thread groups are returned.

op_remove_tgid_spec

      Remove a particular tgid from profile spec.      
     Parameters:
op_pt - Instance to act upon.
        tgid - tgid to be removed. 

op_clear_tgid_spec

      Clear all previously saved tgid.      
     Parameters:
op_pt - Instance to act upon.

op_add_tid_spec

      Add a particular tid to profile spec.      
     Parameters:
op_pt - Instance to act upon.
        tid - tid, if added, only samples from this particular thread
is returned.  If no tid is set, samples from all threads are returned.

op_remove_tid_spec

      Remove a particular tid from profile spec.      
     Parameters:
op_pt - Instance to act upon.
        tid - tid to be removed.

op_clear_tid_spec

      Clear all previously saved tid.      
     Parameters:
op_pt - Instance to act upon.

op_add_event_spec

      Add a particular event to profile spec.      
     Parameters:
op_pt - Instance to act upon.
        event - event name, if added, only samples of this particular event
is returned.  If no event is set, samples of all events are returned.  Available can be discovered by calling iterate_events(...)

op_remove_event_spec

      Remove a particular event from profile spec.      
     Parameters:
op_pt - Instance to act upon.
        event - event to be removed.

op_clear_event_spec

      Clear all previously saved event.      
     Parameters:
op_pt - Instance to act upon.

op_iterate_profile_class

      A profile_class describes the entries in count array of summary, symbol,
      and symbol sample.  The length of count array is always equal to
      the number profile_class.
     Parameters:
op_pt - Instance to act upon.
        callback - callback provided by the user.  Relevant information is              
        passed to the callback.  If the particular field is merged.  Meaning that 
        it does not apply, a NULL pointer is passed to the callback as the 
        parameter.  The callback is required to have the following type: 
unsigned int (*callback)
    (const char * name, const char *event,
     const char * count, const char unitmask,
     const char * cpu, const char tgid,
     const char tid)    
     name - Human readable name of profile class.
             event - Event name of profile class.
       count - Performance counter count.
               unitmask - Performance counter unit mask.
     cpu - CPU number.
               tgid - Thread group ID.
       tid - Thread ID

op_iterate_sessions

      For each available session, op_iterate_sessions will call the callback
      supplied by user for each session.
     Parameters:
op_pt - Instance to act upon.
        callback - callback provided by the user to be call by the API for each 
        session.  The callback is required to have the following type: 
unsigned int (*callback)
    (const char * name)    
     name - Session name.

op_iterate_events

      For each event in sessions, op_iterate_events will call the callback supplied
      by user for each event.  op_iterate_events will check multiple sessions if
      profile spec contains multiple session
     Parameters:
op_pt - Instance to act upon.
        callback - callback provided by the user to be call by the API for each 
        event.  The callback is required to have the following type: 
unsigned int (*callback)
    (const char * name)    
     name - Event name.

op_iterate_summary

      A summary is consisted of absolute path of image, list of dependent
      images, and count array.  op_iterate_summary provides a way to pass profile
      results to users.  op_iterate_summary_deps must be used to access the
      dependent list, if there are any.  A summary will contain dependents
      only when the profile is separated by lib (see SEP_TID).
     Parameters:
op_pt - Instance to act upon.
        callback - callback provided by the user.  Relevant information is              
        passed to the callback.  The callback is required to have the 
        following type: 
unsigned int (*callback)
(const char * image_name, unsigned int dep_size,
unsigned int count_size, unsigned int [] count_array)   
     image_name - Absolute path of the image.
               dep_size - Number of dependent this summary has.
             count_size - size of count_array.
       count_array - Sample count array.

op_iterate_summary_deps

      Iterate dependents of a summary and call the user supplied callback.
     Parameters:
op_pt - Instance to act upon.
      summary_name - Image name of the summary.
        callback - callback provided by the user.  Relevant information is              
        passed to the callback.  The callback is required to have the 
        following type: 
unsigned int (*callback)
      (const char * image_name, const char * dep_image_name, 
       unsigned int count_size, unsigned int [] count_array)
     image_name - Absolute path of the image name which depends on this        dependent.
     dep_image_name - Absolute path of the dependent image.
             count_size - size of count_array.
       count_array - Sample count array.

op_iterate_symbol

      A symbol is consisted of symbol name, symbol size, vma, absolute path  
      of application name, symbol samples, absolute path of image path, and
      count array.  op_iterate_symbol allows user to iterate through symbols that
      meets the criteria set in profile spec.
     Parameters:
op_pt - Instance to act upon.
        callback - callback provided by the user.  Relevant information is              
        passed to the callback.  The callback is required to have the 
        following type: 
unsigned int (*callback)
     (const char * symbol_name, unsigned int symbol_size,
      unsigned long vma, const char * app_name,
      const char * image_path, unsigned int count_size,
      unsigned int [] count_array)
     symbol_name - Mangled symbol name.
             symbol_size- size of symbol.
     vma - vma of the symbol.
           app_name - Full path of application.
     image_path - Full path of image containing the symbol.
             count_size - size of count_array.
       count_array - Sample count array.

op_iterate_symbol_sample

      A symbol is consisted of symbol name, symbol size, vma, absolute path  
      of application name, symbol samples, absolute path of image path, and
      count array.  op_iterate_symbol allows user to iterate through symbols that
      meets the criteria set in profile spec.
     Parameters:
op_pt - Instance to act upon.
        callback - callback provided by the user.  Relevant information is              
        passed to the callback.  The callback is required to have the 
        following type: 
unsigned int (*callback)
     (const char * symbol_name, const char * image_path,
      const char * filename, unsigned int linenr,
      unsigned long vma, unsigned int count_size,
      unsigned int [] count_array)
     symbol_name - Mangled symbol name containing the symbol sample.
             image_path - Full path of image containing the symbol sample.
     filename - Filename of the symbol.  NULL if image does not contain          debug info.
           linenr - Line number of the symbol sample.
           vma - vma of the symbol sample.
             count_size - size of count_array.
       count_array - Sample count array.

op_demangle

      Returns demangled name of symbol.
     Parameters:
op_pt - Instance to act upon.
      symbol_name - Mangled name to be demangled.