trace.h File Reference

Tracepoint library. More...

Data Structures

struct  spdk_trace_entry
 
struct  spdk_trace_entry_buffer
 
struct  spdk_trace_owner
 
struct  spdk_trace_object
 
struct  spdk_trace_argument
 
struct  spdk_trace_tpoint
 
struct  spdk_trace_history
 
struct  spdk_trace_flags
 
struct  spdk_trace_histories
 
struct  spdk_trace_tpoint_opts
 
struct  spdk_trace_register_fn
 

Macros

#define SPDK_DEFAULT_NUM_TRACE_ENTRIES   (32 * 1024)
 
#define SPDK_TRACE_MAX_OWNER   (UCHAR_MAX + 1)
 
#define SPDK_TRACE_MAX_OBJECT   (UCHAR_MAX + 1)
 
#define SPDK_TRACE_MAX_GROUP_ID   16
 
#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   5
 
#define SPDK_TRACE_MAX_RELATIONS   16
 
#define SPDK_TRACE_MAX_LCORE   128
 
#define _spdk_trace_record_tsc(tsc, tpoint_id, poller_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, poller_id, size, object_id, ...)
 Record the current trace state for tracing tpoints. More...
 
#define spdk_trace_record(tpoint_id, poller_id, size, object_id, ...)    spdk_trace_record_tsc(0, tpoint_id, poller_id, size, object_id, ## __VA_ARGS__)
 Record the current trace state for tracing tpoints. More...
 
#define OWNER_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_histories_size (struct spdk_trace_histories *trace_histories)
 
static struct spdk_trace_historyspdk_get_per_lcore_history (struct spdk_trace_histories *trace_histories, unsigned lcore)
 
void _spdk_trace_record (uint64_t tsc, uint16_t tpoint_id, uint16_t poller_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. More...
 
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. More...
 
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. More...
 
uint64_t spdk_trace_get_tpoint_group_mask (void)
 Get a mask of all tracepoint groups which have at least one tracepoint enabled. More...
 
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. More...
 
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. More...
 
int spdk_trace_init (const char *shm_name, uint64_t num_entries)
 Initialize the trace environment. More...
 
void spdk_trace_cleanup (void)
 Unmap global trace memory structs.
 
void spdk_trace_flags_init (void)
 Initialize trace flags.
 
void spdk_trace_register_owner (uint8_t type, char id_prefix)
 Register the trace owner. More...
 
void spdk_trace_register_object (uint8_t type, char id_prefix)
 Register the trace object. More...
 
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. More...
 
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. More...
 
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. More...
 
int spdk_trace_enable_tpoint_group (const char *group_name)
 Enable trace on specific tpoint group. More...
 
int spdk_trace_disable_tpoint_group (const char *group_name)
 Disable trace on specific tpoint group. More...
 
void spdk_trace_mask_usage (FILE *f, const char *tmask_arg)
 Show trace mask and its usage. More...
 
uint64_t spdk_trace_create_tpoint_group_mask (const char *group_name)
 Create a tracepoint group mask from tracepoint group name. More...
 
void spdk_trace_add_register_fn (struct spdk_trace_register_fn *reg_fn)
 Add new trace register function. More...
 

Variables

struct spdk_trace_flagsg_trace_flags
 
struct spdk_trace_historiesg_trace_histories
 

Detailed Description

Tracepoint library.

Macro Definition Documentation

◆ _spdk_trace_record_tsc

#define _spdk_trace_record_tsc (   tsc,
  tpoint_id,
  poller_id,
  size,
  object_id,
  num_args,
  ... 
)
Value:
do { \
assert(tpoint_id < SPDK_TRACE_MAX_TPOINT_ID); \
if (g_trace_histories == NULL || \
!((1ULL << (tpoint_id & 0x3F)) & \
g_trace_histories->flags.tpoint_mask[tpoint_id >> 6])) { \
break; \
} \
_spdk_trace_record(tsc, tpoint_id, poller_id, size, object_id, \
num_args, ## __VA_ARGS__); \
} while (0)

◆ spdk_trace_record

#define spdk_trace_record (   tpoint_id,
  poller_id,
  size,
  object_id,
  ... 
)     spdk_trace_record_tsc(0, tpoint_id, poller_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.
poller_idPoller 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,
  poller_id,
  size,
  object_id,
  ... 
)
Value:
_spdk_trace_record_tsc(tsc, tpoint_id, poller_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.
poller_idPoller 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:399

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 
)

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.
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_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 (up to 5).

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()

void spdk_trace_register_owner ( uint8_t  type,
char  id_prefix 
)

Register the trace owner.

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

◆ 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