doca_telemetry_dpa.h

Go to the documentation of this file.

/*
 * Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES, ALL RIGHTS RESERVED.
 *
 * This software product is a proprietary product of NVIDIA CORPORATION &
 * AFFILIATES (the "Company") and all right, title, and interest in and to the
 * software product, including all associated intellectual property rights, are
 * and shall remain exclusively with the Company.
 *
 * This software product is governed by the End User License Agreement
 * provided with the software product.
 *
 */
 
#ifndef DOCA_TELEMETRY_DPA_H_
#define DOCA_TELEMETRY_DPA_H_
 
#include <doca_error.h>
#include <doca_types.h>
 
#define DOCA_TELEMETRY_DPA_PROCESS_NAME_SIZE (17) 
#define DOCA_TELEMETRY_DPA_THREAD_NAME_SIZE (17)  
#ifdef __cplusplus
extern "C" {
#endif
 
/**********************************************************************************************************************
 * DOCA core opaque types
 *********************************************************************************************************************/
struct doca_dev;
struct doca_devinfo;
 
/*********************************************************************************************************************
 * DOCA Telemetry DPA Context
 *********************************************************************************************************************/
 
struct doca_telemetry_dpa;
 
enum doca_telemetry_dpa_counter_state {
    DOCA_TELEMETRY_DPA_COUNTER_STATE_ACTIVE = 0x1,
    DOCA_TELEMETRY_DPA_COUNTER_STATE_INACTIVE = 0x2,
    DOCA_TELEMETRY_DPA_COUNTER_STATE_RESET = 0x3
};
 
enum doca_telemetry_dpa_counter_type {
    DOCA_TELEMETRY_DPA_COUNTER_TYPE_CUMULATIVE_EVENT = 0x0, 
    DOCA_TELEMETRY_DPA_COUNTER_TYPE_EVENT_TRACER = 0x1  
};
 
enum doca_telemetry_dpa_event_sample_type {
    DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_EMPTY_SAMPLE = 0x0,
    DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_SCHEDULE_IN = 0x1,
    DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_SCHEDULE_OUT = 0x2,
    DOCA_TELEMETRY_DPA_EVENT_SAMPLE_TYPE_BUFFER_FULL = 0xff
};
 
typedef struct doca_telemetry_dpa_process_info {
    uint32_t dpa_process_id;                 
    uint32_t num_of_threads;                 
    char process_name[DOCA_TELEMETRY_DPA_PROCESS_NAME_SIZE]; 
} doca_telemetry_dpa_process_info_t;
 
typedef struct doca_telemetry_dpa_thread_info {
    uint32_t dpa_process_id;                   
    uint32_t dpa_thread_id;                    
    char thread_name[DOCA_TELEMETRY_DPA_THREAD_NAME_SIZE]; 
} doca_telemetry_dpa_thread_info_t;
 
typedef struct doca_telemetry_dpa_cumul_info {
    uint32_t dpa_process_id; 
    uint32_t dpa_thread_id;  
    uint64_t time;       
    uint64_t cycles;     
    uint64_t instructions;   
    uint64_t num_executions; 
} doca_telemetry_dpa_cumul_info_t;
 
typedef struct doca_telemetry_dpa_event_sample {
    uint64_t timestamp;             
    uint64_t cycles;                
    uint32_t instructions;              
    uint32_t dpa_thread_id;             
    uint16_t eu_id;                 
    uint16_t sample_id_in_eu;           
    enum doca_telemetry_dpa_event_sample_type type; 
} doca_telemetry_dpa_event_sample_t;
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_cap_is_supported(const struct doca_devinfo *devinfo);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_create(struct doca_dev *dev, struct doca_telemetry_dpa **dpa);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_destroy(struct doca_telemetry_dpa *dpa);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_start(struct doca_telemetry_dpa *dpa);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_stop(struct doca_telemetry_dpa *dpa);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_read_processes_list(struct doca_telemetry_dpa *dpa,
                            uint32_t process_id,
                            uint32_t *dpa_process_num,
                            doca_telemetry_dpa_process_info_t *process_list);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_read_thread_list(struct doca_telemetry_dpa *dpa,
                         uint32_t process_id,
                         uint32_t thread_id,
                         uint32_t *dpa_threads_num,
                         doca_telemetry_dpa_thread_info_t *thread_list);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_counter_start(struct doca_telemetry_dpa *dpa,
                          uint32_t process_id,
                          enum doca_telemetry_dpa_counter_type type);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_counter_restart(struct doca_telemetry_dpa *dpa,
                        uint32_t process_id,
                        enum doca_telemetry_dpa_counter_type type);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_counter_stop(struct doca_telemetry_dpa *dpa,
                         uint32_t process_id,
                         enum doca_telemetry_dpa_counter_type type);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_read_cumul_info_list(struct doca_telemetry_dpa *dpa,
                             uint32_t process_id,
                             uint32_t thread_id,
                             uint32_t *cumul_samples_num,
                             doca_telemetry_dpa_cumul_info_t *cumul_info_list);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_read_perf_event_list(struct doca_telemetry_dpa *dpa,
                             uint32_t process_id,
                             uint32_t thread_id,
                             uint32_t *perf_event_samples_num,
                             doca_telemetry_dpa_event_sample_t *perf_event_list);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_dpa_timer_freq(struct doca_telemetry_dpa *dpa, uint32_t *dpa_timer_freq);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_process_list_size(struct doca_telemetry_dpa *dpa,
                              uint32_t process_id,
                              uint32_t *dpa_process_list_size);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_thread_list_size(struct doca_telemetry_dpa *dpa,
                             uint32_t process_id,
                             uint32_t thread_id,
                             uint32_t *dpa_thread_list_size);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_cumul_samples_size(struct doca_telemetry_dpa *dpa,
                               uint32_t process_id,
                               uint32_t thread_id,
                               uint32_t *dpa_cumul_samples_size);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_set_max_perf_event_samples(struct doca_telemetry_dpa *dpa,
                               uint32_t dpa_max_perf_event_samples);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_max_perf_event_samples(struct doca_telemetry_dpa *dpa,
                               uint32_t *dpa_max_perf_event_samples);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_perf_event_samples_size(struct doca_telemetry_dpa *dpa,
                                uint32_t *dpa_perf_event_samples_size);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_counter_state(struct doca_telemetry_dpa *dpa,
                          uint32_t process_id,
                          enum doca_telemetry_dpa_counter_state *state);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_counter_type(struct doca_telemetry_dpa *dpa,
                         uint32_t process_id,
                         enum doca_telemetry_dpa_counter_type *type);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_all_process_id(const struct doca_devinfo *devinfo, uint32_t *all_process_id);
 
DOCA_EXPERIMENTAL
doca_error_t doca_telemetry_dpa_get_all_thread_id(const struct doca_devinfo *devinfo, uint32_t *all_thread_id);
 
#ifdef __cplusplus
} /* extern "C" */
#endif
 
#endif /* DOCA_TELEMETRY_DPA_H_ */