General purpose utilities

Detailed Description

General purpose utilities.

This module contains general purpose utilities.

Typedefs
typedef enum bt_util_clock_cycles_to_ns_from_origin_status	bt_util_clock_cycles_to_ns_from_origin_status
	Status codes for bt_util_clock_cycles_to_ns_from_origin().

Enumerations
enum	bt_util_clock_cycles_to_ns_from_origin_status {   BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK,   BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR }
	Status codes for bt_util_clock_cycles_to_ns_from_origin(). More...

Functions
bt_util_clock_cycles_to_ns_from_origin_status	bt_util_clock_cycles_to_ns_from_origin (uint64_t cycles, uint64_t frequency, int64_t offset_seconds, uint64_t offset_cycles, int64_t *ns_from_origin)
	Converts the clock value cycles from cycles to nanoseconds from the clock's origin and sets *ns_from_origin to the result. More...

Enumeration Type Documentation

bt_util_clock_cycles_to_ns_from_origin_status

enum bt_util_clock_cycles_to_ns_from_origin_status

Status codes for bt_util_clock_cycles_to_ns_from_origin().

Enumerator
BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK	Success.
BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR	Integer overflow while computing the result.

Function Documentation

bt_util_clock_cycles_to_ns_from_origin()

bt_util_clock_cycles_to_ns_from_origin_status bt_util_clock_cycles_to_ns_from_origin	(	uint64_t	cycles,
		uint64_t	frequency,
		int64_t	offset_seconds,
		uint64_t	offset_cycles,
		int64_t *	ns_from_origin
	)

Converts the clock value cycles from cycles to nanoseconds from the clock's origin and sets *ns_from_origin to the result.

This function considers the clock's frequency in Hz (frequency), an offset from its origin in seconds (offset_seconds) which can be negative, and an additional offset in cycles (offset_cycles).

This function:

1. Converts the offset_cycles value to seconds using frequency.
2. Converts the cycles value to seconds using frequency.
3. Adds the values of 1., 2., and offset_seconds.
4. Converts the value of 3. to nanoseconds and sets *ns_from_origin to this result.

The following illustration shows the possible scenarios:

offset_seconds can be negative. For example, considering:

• A 1000 Hz clock.
• offset_seconds set to -10 seconds.
• offset_cycles set to 500 cycles (that is, 0.5 seconds).
• cycles set to 2000 cycles (that is, 2 seconds).

The computed value is -7.5 seconds, so this function sets *ns_from_origin to -7,500,000,000.

This function can fail and return the BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status code if any step of the computation process causes an integer overflow.

Parameters

[in]	cycles	Clock's value (cycles).
[in]	frequency	Clock's frequency (Hz, or cycles/second).
[in]	offset_seconds	Offset, in seconds, from the clock's origin to add to cycles (once converted to seconds).
[in]	offset_cycles	Offset, in cycles, to add to cycles.
[out]	ns_from_origin	On success, *ns_from_origin is cycles converted to nanoseconds from origin considering the clock's properties.

Return values

BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK	Success.
BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR	Integer overflow while computing the result.

Precondition

frequency is not 0.

frequency is not UINT64_C(-1).

frequency is greater than offset_cycles.

offset_cycles is less than frequency.

ns_from_origin is not NULL.

See also

bt_clock_class_cycles_to_ns_from_origin() — Converts a stream clock value from cycles to nanoseconds from the origin of a given clock class.