utrace::Tracebuffer Class Reference

Tracebuffer abstraction. More...

#include <utrace>

Collaboration diagram for utrace::Tracebuffer:

Data Structures
struct	Index_desc
	Mapping of the dynamic tracebuffer log indexes to names. More...

Public Member Functions
size_t	items () const
	Get the capacity (in items) of the tracebuffer ring buffer.
size_t	dequeue (Item *items, size_t capacity, size_t burst, Drop_policy policy, Sequence *drops=nullptr)
	Dequeue items from the tracebuffer.

Static Public Member Functions
static void	validate ()
	Check that the base debugger (JDB) capability is valid and accessible.
static unsigned	version ()
	Get the tracebuffer format version supported by this class.
static std::endian	endianness ()
	Get the endianness supported by this class.
static std::optional< Index_desc >	index (unsigned idx)
	Map a dynamic tracebuffer log index to names.
static std::vector< Index_desc >	indexes ()
	Get all mappings of dynamic tracebuffer log indexes to names.
static Tracebuffer &	instance ()
	Get the singleton instance of this class.
static std::optional< Id >	ptr_to_id (void *const ptr)
	Convert kernel object pointer to global kernel object ID.
static std::optional< std::string >	id_to_name (Id const id)
	Convert global kernel object ID to object name.

Detailed Description

Tracebuffer abstraction.

Since there is only a single global tracebuffer available in the current implementation, this is a singleton class.

Definition at line 50 of file utrace.

Member Function Documentation

dequeue()

size_t utrace::Tracebuffer::dequeue	(	Item *	items,
		size_t	capacity,
		size_t	burst,
		Drop_policy	policy,
		Sequence *	drops = nullptr )

Dequeue items from the tracebuffer.

Dequeue multiple items from the tracebuffer. The goal is to dequeue as many items as available from the tracebuffer in a single call to avoid overhead. This operation blocks until at least burst items have been dequeued (but returns immediately if an item is dropped).

Parameters

[out]	items	Array to dequeue the next items from the tracebuffer into (as copies).
	capacity	Capacity of items (in items).
	burst	Minimal number of items that should be collected before returning in case of waiting for items.
	policy	Item drop policy.
[out]	drops	Pointer to store the number of items that have been dropped. Can be nullptr.

Returns

Number of items dequeued and stored into items.

References items().

Here is the call graph for this function:

id_to_name()

std::optional< std::string > utrace::Tracebuffer::id_to_name ( Id const id )

static

Convert global kernel object ID to object name.

Some tracebuffer items contain global kernel object IDs that can be associated with human-readable object names.

Parameters

id	Global kernel object ID.

Returns

Object name.

Return values

std::nullopt

No object name was found.

References items().

Here is the call graph for this function:

index()

std::optional< Index_desc > utrace::Tracebuffer::index ( unsigned idx )

static

Map a dynamic tracebuffer log index to names.

Parameters

idx	Dynamic tracebuffer log index to map.

Returns

Mapping of the dynamic tracebuffer index to names.

Return values

std::nullopt

The dynamic tracebuffer log index is not defined.

indexes()

std::vector< Index_desc > utrace::Tracebuffer::indexes ( )

static

Get all mappings of dynamic tracebuffer log indexes to names.

Returns

Generator (if available) or a vector of all defined mappings of dynamic tracebuffer log indexes to names.

ptr_to_id()

std::optional< Id > utrace::Tracebuffer::ptr_to_id ( void *const ptr )

static

Convert kernel object pointer to global kernel object ID.

Some tracebuffer items contain kernel object pointers that can be converted to global kernel object IDs.

Parameters

ptr	Kernel object pointer.

Returns

Global kernel object ID.

Return values

std::nullopt

No mapping to global kernel object ID was found.

validate()

void utrace::Tracebuffer::validate ( )

static

Check that the base debugger (JDB) capability is valid and accessible.

The base debugger (JDB) capability is used to access the single global tracebuffer in the current implementation.

Exceptions

std::invalid_argument

If the base debugger (JDB) capability is invalid or inaccessible.

---

The documentation for this class was generated from the following file:

• l4/utrace/utrace