Tracepoint library. More...

Data Structures
struct	spdk_trace_entry

struct	spdk_trace_entry_buffer

struct	spdk_trace_owner_type

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 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 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, 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_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)

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, uint32_t num_threads)
	Initialize the trace environment. More...

int	spdk_trace_register_user_thread (void)
	Initialize trace environment for an user created thread. More...

int	spdk_trace_unregister_user_thread (void)
	De-initialize trace environment for an user created thread. More...

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. 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_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. 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_file *	g_trace_file

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 (!spdk_trace_tpoint_enabled(tpoint_id)) {                                    \
                        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_id	Tracepoint id to record.
poller_id	Poller 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,
		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

tsc	Current tsc.
tpoint_id	Tracepoint id to record.
poller_id	Poller 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);        \
        }                                                       \
        static void fn(void)

◆ 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_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_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_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.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ _spdk_trace_record_tsc

◆ spdk_trace_record

◆ spdk_trace_record_tsc

◆ SPDK_TRACE_REGISTER_FN

◆ spdk_trace_tpoint_enabled

Function Documentation

◆ spdk_trace_add_register_fn()

◆ spdk_trace_clear_tpoint_group_mask()

◆ spdk_trace_clear_tpoints()

◆ spdk_trace_create_tpoint_group_mask()

◆ spdk_trace_disable_tpoint_group()

◆ spdk_trace_enable_tpoint_group()

◆ spdk_trace_get_tpoint_group_mask()

◆ spdk_trace_get_tpoint_mask()

◆ spdk_trace_init()

◆ spdk_trace_mask_usage()

◆ spdk_trace_register_description()

◆ spdk_trace_register_description_ext()

◆ spdk_trace_register_object()

◆ spdk_trace_register_owner_type()

◆ spdk_trace_register_user_thread()

◆ spdk_trace_set_tpoint_group_mask()

◆ spdk_trace_set_tpoints()

◆ spdk_trace_tpoint_register_relation()

◆ spdk_trace_unregister_user_thread()