Loading...
Searching...
No Matches
trace.h File Reference

Tracepoint library. More...

Data Structures

struct  spdk_trace_entry
 
struct  spdk_trace_entry_buffer
 
struct  spdk_trace_owner_type
 
struct  spdk_trace_owner
 
struct  spdk_trace_object
 
struct  spdk_trace_argument
 
struct  spdk_trace_tpoint
 
struct  spdk_trace_history
 
struct  spdk_trace_file
 
struct  spdk_trace_tpoint_opts
 
struct  spdk_trace_register_fn
 

Macros

#define SPDK_TRACE_SHM_NAME_BASE   "_trace."
 
#define SPDK_DEFAULT_NUM_TRACE_ENTRIES   (32 * 1024)
 
#define SPDK_TRACE_MAX_OWNER_TYPE   (UCHAR_MAX + 1)
 
#define SPDK_TRACE_MAX_OBJECT   (UCHAR_MAX + 1)
 
#define SPDK_TRACE_THREAD_NAME_LEN   16
 
#define SPDK_TRACE_MAX_GROUP_ID   20
 
#define SPDK_TRACE_MAX_TPOINT_ID   (SPDK_TRACE_MAX_GROUP_ID * 64)
 
#define SPDK_TPOINT_ID(group, tpoint)   ((group * 64) + tpoint)
 
#define SPDK_TRACE_ARG_TYPE_INT   0
 
#define SPDK_TRACE_ARG_TYPE_PTR   1
 
#define SPDK_TRACE_ARG_TYPE_STR   2
 
#define SPDK_TRACE_MAX_ARGS_COUNT   8
 
#define SPDK_TRACE_MAX_RELATIONS   16
 
#define SPDK_TRACE_MAX_LCORE   1024
 
#define spdk_trace_tpoint_enabled(tpoint_id)
 
#define _spdk_trace_record_tsc(tsc, tpoint_id, owner_id, size, object_id, num_args, ...)
 
#define spdk_trace_num_args(...)   _spdk_trace_num_args(, ## __VA_ARGS__)
 
#define _spdk_trace_num_args(...)   __spdk_trace_num_args(__VA_ARGS__, 8, 7, 6, 5, 4, 3, 2, 1, 0)
 
#define __spdk_trace_num_args(v, a1, a2, a3, a4, a5, a6, a7, a8, count, ...)   count
 
#define spdk_trace_record_tsc(tsc, tpoint_id, owner_id, size, object_id, ...)
 Record the current trace state for tracing tpoints.
 
#define spdk_trace_record(tpoint_id, owner_id, size, object_id, ...)    spdk_trace_record_tsc(0, tpoint_id, owner_id, size, object_id, ## __VA_ARGS__)
 Record the current trace state for tracing tpoints.
 
#define OWNER_TYPE_NONE   0
 
#define OBJECT_NONE   0
 
#define SPDK_TRACE_REGISTER_FN(fn, name_str, _tgroup_id)
 

Functions

 SPDK_STATIC_ASSERT (sizeof(struct spdk_trace_entry_buffer)==sizeof(struct spdk_trace_entry), "Invalid size of trace entry buffer")
 
static uint64_t spdk_get_trace_history_size (uint64_t num_entries)
 
static uint64_t spdk_get_trace_file_size (struct spdk_trace_file *trace_file)
 
static struct spdk_trace_historyspdk_get_per_lcore_history (struct spdk_trace_file *trace_file, unsigned lcore)
 
static struct spdk_trace_ownerspdk_get_trace_owner (const struct spdk_trace_file *trace_file, uint16_t owner_id)
 
void _spdk_trace_record (uint64_t tsc, uint16_t tpoint_id, uint16_t owner_id, uint32_t size, uint64_t object_id, int num_args,...)
 
uint64_t spdk_trace_get_tpoint_mask (uint32_t group_id)
 Get the current tpoint mask of the given tpoint group.
 
void spdk_trace_set_tpoints (uint32_t group_id, uint64_t tpoint_mask)
 Add the specified tpoints to the current tpoint mask for the given tpoint group.
 
void spdk_trace_clear_tpoints (uint32_t group_id, uint64_t tpoint_mask)
 Clear the specified tpoints from the current tpoint mask for the given tpoint group.
 
uint64_t spdk_trace_get_tpoint_group_mask (void)
 Get a mask of all tracepoint groups which have at least one tracepoint enabled.
 
void spdk_trace_set_tpoint_group_mask (uint64_t tpoint_group_mask)
 For each tpoint group specified in the group mask, enable all of its tpoints.
 
void spdk_trace_clear_tpoint_group_mask (uint64_t tpoint_group_mask)
 For each tpoint group specified in the group mask, disable all of its tpoints.
 
int spdk_trace_init (const char *shm_name, uint64_t num_entries, uint32_t num_threads)
 Initialize the trace environment.
 
int spdk_trace_register_user_thread (void)
 Initialize trace environment for an user created thread.
 
int spdk_trace_unregister_user_thread (void)
 De-initialize trace environment for an user created thread.
 
void spdk_trace_cleanup (void)
 Unmap global trace memory structs.
 
void spdk_trace_register_owner_type (uint8_t type, char id_prefix)
 Register the trace owner type.
 
uint16_t spdk_trace_register_owner (uint8_t owner_type, const char *description)
 Register the trace owner.
 
void spdk_trace_owner_set_description (uint16_t owner_id, const char *description)
 Change the description for a previously registered owner.
 
void spdk_trace_owner_append_description (uint16_t owner_id, const char *description)
 Append to the description for a previously registered owner.
 
void spdk_trace_unregister_owner (uint16_t owner_id)
 Unregister a previously registered owner.
 
void spdk_trace_register_object (uint8_t type, char id_prefix)
 Register the trace object.
 
void spdk_trace_register_description (const char *name, uint16_t tpoint_id, uint8_t owner_type, uint8_t object_type, uint8_t new_object, uint8_t arg1_type, const char *arg1_name)
 Register the description for a tpoint with a single argument.
 
void spdk_trace_register_description_ext (const struct spdk_trace_tpoint_opts *opts, size_t num_opts)
 Register the description for a number of tpoints.
 
struct spdk_trace_register_fnspdk_trace_get_first_register_fn (void)
 
struct spdk_trace_register_fnspdk_trace_get_next_register_fn (struct spdk_trace_register_fn *register_fn)
 
void spdk_trace_tpoint_register_relation (uint16_t tpoint_id, uint8_t object_type, uint8_t arg_index)
 Bind trace type to a given trace object.
 
int spdk_trace_enable_tpoint_group (const char *group_name)
 Enable trace on specific tpoint group.
 
int spdk_trace_disable_tpoint_group (const char *group_name)
 Disable trace on specific tpoint group.
 
void spdk_trace_mask_usage (FILE *f, const char *tmask_arg)
 Show trace mask and its usage.
 
uint64_t spdk_trace_create_tpoint_group_mask (const char *group_name)
 Create a tracepoint group mask from tracepoint group name.
 
void spdk_trace_add_register_fn (struct spdk_trace_register_fn *reg_fn)
 Add new trace register function.
 

Variables

struct spdk_trace_fileg_trace_file
 

Detailed Description

Tracepoint library.

Macro Definition Documentation

◆ _spdk_trace_record_tsc

#define _spdk_trace_record_tsc ( tsc,
tpoint_id,
owner_id,
size,
object_id,
num_args,
... )
Value:
do { \
assert(tpoint_id < SPDK_TRACE_MAX_TPOINT_ID); \
if (!spdk_trace_tpoint_enabled(tpoint_id)) { \
break; \
} \
_spdk_trace_record(tsc, tpoint_id, owner_id, size, object_id, \
num_args, ## __VA_ARGS__); \
} while (0)

◆ spdk_trace_record

#define spdk_trace_record ( tpoint_id,
owner_id,
size,
object_id,
... )    spdk_trace_record_tsc(0, tpoint_id, owner_id, size, object_id, ## __VA_ARGS__)

Record the current trace state for tracing tpoints.

Debug tool can read the information from shared memory to post-process the tpoint entries and display in a human-readable format. This macro will call spdk_get_ticks() to get the current tsc to save in the tracepoint.

Parameters
tpoint_idTracepoint id to record.
owner_idOwner id to record.
sizeSize to record.
object_idObject id to record.
...Extra tracepoint arguments. The number, types, and order of the arguments must match the definition of the tracepoint.

◆ spdk_trace_record_tsc

#define spdk_trace_record_tsc ( tsc,
tpoint_id,
owner_id,
size,
object_id,
... )
Value:
_spdk_trace_record_tsc(tsc, tpoint_id, owner_id, size, object_id, \
spdk_trace_num_args(__VA_ARGS__), ## __VA_ARGS__)

Record the current trace state for tracing tpoints.

Debug tool can read the information from shared memory to post-process the tpoint entries and display in a human-readable format.

Parameters
tscCurrent tsc.
tpoint_idTracepoint id to record.
owner_idOwner id to record.
sizeSize to record.
object_idObject id to record.
...Extra tracepoint arguments. The number, types, and order of the arguments must match the definition of the tracepoint.

◆ SPDK_TRACE_REGISTER_FN

#define SPDK_TRACE_REGISTER_FN ( fn,
name_str,
_tgroup_id )
Value:
static void fn(void); \
struct spdk_trace_register_fn reg_ ## fn = { \
.name = name_str, \
.tgroup_id = _tgroup_id, \
.reg_fn = fn, \
.next = NULL, \
}; \
__attribute__((constructor)) static void _ ## fn(void) \
{ \
spdk_trace_add_register_fn(&reg_ ## fn); \
} \
static void fn(void)
Definition trace.h:475

◆ spdk_trace_tpoint_enabled

#define spdk_trace_tpoint_enabled ( tpoint_id)
Value:
spdk_unlikely((g_trace_file != NULL && \
((1ULL << (tpoint_id & 0x3F)) & g_trace_file->tpoint_mask[tpoint_id >> 6])))

Function Documentation

◆ spdk_trace_add_register_fn()

void spdk_trace_add_register_fn ( struct spdk_trace_register_fn * reg_fn)

Add new trace register function.

Parameters
reg_fnTrace register function to add.

◆ spdk_trace_clear_tpoint_group_mask()

void spdk_trace_clear_tpoint_group_mask ( uint64_t tpoint_group_mask)

For each tpoint group specified in the group mask, disable all of its tpoints.

Parameters
tpoint_group_maskTpoint group mask that indicates which tpoints to disable.

◆ spdk_trace_clear_tpoints()

void spdk_trace_clear_tpoints ( uint32_t group_id,
uint64_t tpoint_mask )

Clear the specified tpoints from the current tpoint mask for the given tpoint group.

Parameters
group_idTpoint group id associated with the tpoint mask.
tpoint_maskTpoint mask which indicates which tpoints to clear from the current tpoint mask.

◆ spdk_trace_create_tpoint_group_mask()

uint64_t spdk_trace_create_tpoint_group_mask ( const char * group_name)

Create a tracepoint group mask from tracepoint group name.

Parameters
group_nametracepoint group name string
Returns
tpoint group mask on success, 0 on failure

◆ spdk_trace_disable_tpoint_group()

int spdk_trace_disable_tpoint_group ( const char * group_name)

Disable trace on specific tpoint group.

Parameters
group_nameName of group to disable, "all" for disabling all groups.
Returns
0 on success, else non-zero indicates a failure.

◆ spdk_trace_enable_tpoint_group()

int spdk_trace_enable_tpoint_group ( const char * group_name)

Enable trace on specific tpoint group.

Parameters
group_nameName of group to enable, "all" for enabling all groups.
Returns
0 on success, else non-zero indicates a failure.

◆ spdk_trace_get_tpoint_group_mask()

uint64_t spdk_trace_get_tpoint_group_mask ( void )

Get a mask of all tracepoint groups which have at least one tracepoint enabled.

Returns
a mask of all tracepoint groups.

◆ spdk_trace_get_tpoint_mask()

uint64_t spdk_trace_get_tpoint_mask ( uint32_t group_id)

Get the current tpoint mask of the given tpoint group.

Parameters
group_idTpoint group id associated with the tpoint mask.
Returns
current tpoint mask.

◆ spdk_trace_init()

int spdk_trace_init ( const char * shm_name,
uint64_t num_entries,
uint32_t num_threads )

Initialize the trace environment.

Debug tool can read the information from the given shared memory to post-process the tpoint entries and display in a human-readable format.

Parameters
shm_nameName of shared memory.
num_entriesNumber of trace entries per lcore.
num_threadsNumber of user created threads.
Returns
0 on success, else non-zero indicates a failure.

◆ spdk_trace_mask_usage()

void spdk_trace_mask_usage ( FILE * f,
const char * tmask_arg )

Show trace mask and its usage.

Parameters
fFile to hold the mask's information.
tmask_argCommand line option to set the trace group mask.

◆ spdk_trace_owner_append_description()

void spdk_trace_owner_append_description ( uint16_t owner_id,
const char * description )

Append to the description for a previously registered owner.

A space will be inserted before the appended string.

This may be useful for modules that are modifying an existing description with additional information.

Callers may pass 0 safely, in this case the function will just be a nop.

Parameters
owner_idID of previously registered owner.
descriptionAdditional description for the owner

◆ spdk_trace_owner_set_description()

void spdk_trace_owner_set_description ( uint16_t owner_id,
const char * description )

Change the description for a previously registered owner.

Parameters
owner_idID of previously registered owner.
descriptionNew description for the owner.

◆ spdk_trace_register_description()

void spdk_trace_register_description ( const char * name,
uint16_t tpoint_id,
uint8_t owner_type,
uint8_t object_type,
uint8_t new_object,
uint8_t arg1_type,
const char * arg1_name )

Register the description for a tpoint with a single argument.

Parameters
nameName for the tpoint.
tpoint_idId for the tpoint.
owner_typeOwner type for the tpoint.
object_typeObject type for the tpoint.
new_objectNew object for the tpoint.
arg1_typeType of arg1.
arg1_nameName of argument.

◆ spdk_trace_register_description_ext()

void spdk_trace_register_description_ext ( const struct spdk_trace_tpoint_opts * opts,
size_t num_opts )

Register the description for a number of tpoints.

This function allows the user to register tracepoints with multiple arguments.

Parameters
optsArray of structures describing tpoints and their arguments.
num_optsNumber of tpoints to register (size of the opts array).

◆ spdk_trace_register_object()

void spdk_trace_register_object ( uint8_t type,
char id_prefix )

Register the trace object.

Parameters
typeType of the trace object.
id_prefixPrefix of id for the trace object.

◆ spdk_trace_register_owner()

uint16_t spdk_trace_register_owner ( uint8_t owner_type,
const char * description )

Register the trace owner.

Parameters
owner_typeType of the owner being registered.
descriptionTextual string describing the trace owner.
Returns
Allocated owner_id for the newly registered owner. Returns 0 if no trace_id could be allocated.

◆ spdk_trace_register_owner_type()

void spdk_trace_register_owner_type ( uint8_t type,
char id_prefix )

Register the trace owner type.

Parameters
typeType of the trace owner.
id_prefixPrefix of id for the trace owner.

◆ spdk_trace_register_user_thread()

int spdk_trace_register_user_thread ( void )

Initialize trace environment for an user created thread.

Returns
0 on success, else non-zero indicates a failure.

◆ spdk_trace_set_tpoint_group_mask()

void spdk_trace_set_tpoint_group_mask ( uint64_t tpoint_group_mask)

For each tpoint group specified in the group mask, enable all of its tpoints.

Parameters
tpoint_group_maskTpoint group mask that indicates which tpoints to enable.

◆ spdk_trace_set_tpoints()

void spdk_trace_set_tpoints ( uint32_t group_id,
uint64_t tpoint_mask )

Add the specified tpoints to the current tpoint mask for the given tpoint group.

Parameters
group_idTpoint group id associated with the tpoint mask.
tpoint_maskTpoint mask which indicates which tpoints to add to the current tpoint mask.

◆ spdk_trace_tpoint_register_relation()

void spdk_trace_tpoint_register_relation ( uint16_t tpoint_id,
uint8_t object_type,
uint8_t arg_index )

Bind trace type to a given trace object.

This allows for matching traces with the same parent trace object.

Parameters
tpoint_idType of trace to be bound
object_typeTracepoint object type to bind to
arg_indexIndex of argument containing context information

◆ spdk_trace_unregister_owner()

void spdk_trace_unregister_owner ( uint16_t owner_id)

Unregister a previously registered owner.

Callers may pass 0 safely, in this case the function will just be a nop.

Parameters
owner_idID of previously registered owner.

◆ spdk_trace_unregister_user_thread()

int spdk_trace_unregister_user_thread ( void )

De-initialize trace environment for an user created thread.

Returns
0 on success, else non-zero indicates a failure.