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_history *	spdk_get_per_lcore_history (struct spdk_trace_file *trace_file, unsigned lcore)
static struct spdk_trace_owner *	spdk_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_fn *	spdk_trace_get_first_register_fn (void)
struct spdk_trace_register_fn *	spdk_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_file *	g_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_id	Tracepoint id to record.
owner_id	Owner id to record.
size	Size to record.
object_id	Object 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

tsc	Current tsc.
tpoint_id	Tracepoint id to record.
owner_id	Owner id to record.
size	Size to record.
object_id	Object 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);        \
        }

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_fn

Trace 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_mask

Tpoint 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_id	Tpoint group id associated with the tpoint mask.
tpoint_mask	Tpoint 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_name

tracepoint 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_name

Name 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_name

Name 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_id

Tpoint 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_name	Name of shared memory.
num_entries	Number of trace entries per lcore.
num_threads	Number 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

f	File to hold the mask's information.
tmask_arg	Command 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_id	ID of previously registered owner.
description	Additional 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_id	ID of previously registered owner.
description	New 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

name	Name for the tpoint.
tpoint_id	Id for the tpoint.
owner_type	Owner type for the tpoint.
object_type	Object type for the tpoint.
new_object	New object for the tpoint.
arg1_type	Type of arg1.
arg1_name	Name 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

opts	Array of structures describing tpoints and their arguments.
num_opts	Number 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

type	Type of the trace object.
id_prefix	Prefix 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_type	Type of the owner being registered.
description	Textual 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

type	Type of the trace owner.
id_prefix	Prefix 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_mask

Tpoint 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_id	Tpoint group id associated with the tpoint mask.
tpoint_mask	Tpoint 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_id	Type of trace to be bound
object_type	Tracepoint object type to bind to
arg_index	Index 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_id

ID 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.