X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=blobdiff_plain;f=include%2Fbabeltrace2%2Futil.h;h=8426a0adeff4c0729c2d01ee001a7adb531226d0;hp=0650d60359d02fdfff1dab1b44f2da2e28d30064;hb=HEAD;hpb=bbb7b5f044dc06e50eaa34ed3a880b34e1e7ebb8 diff --git a/include/babeltrace2/util.h b/include/babeltrace2/util.h index 0650d603..030862ae 100644 --- a/include/babeltrace2/util.h +++ b/include/babeltrace2/util.h @@ -1,28 +1,14 @@ -#ifndef BABELTRACE2_UTIL_H -#define BABELTRACE2_UTIL_H - /* - * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation - * - * Permission is hereby granted, free of charge, to any person obtaining a copy - * of this software and associated documentation files (the "Software"), to deal - * in the Software without restriction, including without limitation the rights - * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the Software is - * furnished to do so, subject to the following conditions: + * SPDX-License-Identifier: MIT * - * The above copyright notice and this permission notice shall be included in - * all copies or substantial portions of the Software. - * - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - * SOFTWARE. + * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation */ +#ifndef BABELTRACE2_UTIL_H +#define BABELTRACE2_UTIL_H + +/* IWYU pragma: private, include */ + #ifndef __BT_IN_BABELTRACE_H # error "Please include instead." #endif @@ -33,14 +19,113 @@ extern "C" { #endif -typedef enum bt_util_status { - BT_UTIL_STATUS_OK = 0, - BT_UTIL_STATUS_OVERFLOW = -75, -} bt_util_status; +/*! +@defgroup api-util General purpose utilities + +@brief + General purpose utilities. + +This API offers general purpose utilities. +*/ + +/*! @{ */ + +/*! +@brief + Status codes for bt_util_clock_cycles_to_ns_from_origin(). +*/ +typedef enum bt_util_clock_cycles_to_ns_from_origin_status { + /*! + @brief + Success. + */ + BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK = __BT_FUNC_STATUS_OK, + + /*! + @brief + Integer overflow while computing the result. + */ + BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR = __BT_FUNC_STATUS_OVERFLOW_ERROR, +} bt_util_clock_cycles_to_ns_from_origin_status; -bt_util_status bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles, +/*! +@brief + Converts the clock value \bt_p{cycles} from cycles to nanoseconds + from the clock's origin and sets \bt_p{*ns_from_origin} to the + result. + +This function considers the clock's frequency in Hz (\bt_p{frequency}), +an offset from its origin in seconds (\bt_p{offset_seconds}) which +can be negative, and an additional offset in cycles +(\bt_p{offset_cycles}). + +This function: + +-# Converts the \bt_p{offset_cycles} value to seconds using + \bt_p{frequency}. +-# Converts the \bt_p{cycles} value to seconds using \bt_p{frequency}. +-# Adds the values of 1., 2., and \bt_p{offset_seconds}. +-# Converts the value of 3. to nanoseconds and sets + \bt_p{*ns_from_origin} to this result. + +The following illustration shows the possible scenarios: + +@image html clock-terminology.png + +\bt_p{offset_seconds} can be negative. For example, considering: + +- A 1000 Hz clock. +- \bt_p{offset_seconds} set to −10 seconds. +- \bt_p{offset_cycles} set to 500 cycles + (that is, 0.5 seconds). +- \bt_p{cycles} set to 2000 cycles (that is, 2 seconds). + +The computed value is −7.5 seconds, so this function sets +\bt_p{*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. + +@param[in] cycles + Clock's value (cycles). +@param[in] frequency + Clock's frequency (Hz, or cycles/second). +@param[in] offset_seconds + Offset, in seconds, from the clock's origin to add to + \bt_p{cycles} (once converted to seconds). +@param[in] offset_cycles + Offset, in cycles, to add to \bt_p{cycles}. +@param[out] ns_from_origin + On success, \bt_p{*ns_from_origin} is \bt_p{cycles} + converted to nanoseconds from origin considering the clock's + properties. + +@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK + Success. +@retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR + Integer overflow while computing the result. + +@pre + \bt_p{frequency} is not 0. +@pre + \bt_p{frequency} is not UINT64_C(-1). +@pre + \bt_p{frequency} is greater than \bt_p{offset_cycles}. +@pre + \bt_p{offset_cycles} is less than \bt_p{frequency}. +@bt_pre_not_null{ns_from_origin} + +@sa 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. +*/ +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); + uint64_t offset_cycles, int64_t *ns_from_origin) __BT_NOEXCEPT; + +/*! @} */ #ifdef __cplusplus }