include/rtems/counter.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSAPICounter
0007  *
0008  * @brief This header file defines the Free-Running Counter and Busy Wait Delay
0009  *   API.
0010  */
0011
0012 /*
0013  * Copyright (C) 2014, 2018 embedded brains GmbH & Co. KG
0014  *
0015  * Redistribution and use in source and binary forms, with or without
0016  * modification, are permitted provided that the following conditions
0017  * are met:
0018  * 1. Redistributions of source code must retain the above copyright
0019  *    notice, this list of conditions and the following disclaimer.
0020  * 2. Redistributions in binary form must reproduce the above copyright
0021  *    notice, this list of conditions and the following disclaimer in the
0022  *    documentation and/or other materials provided with the distribution.
0023  *
0024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0025  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0026  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0027  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0028  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0029  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0030  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0031  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0032  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0033  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0034  * POSSIBILITY OF SUCH DAMAGE.
0035  */
0036
0037 #ifndef _RTEMS_SAPI_COUNTER_H
0038 #define _RTEMS_SAPI_COUNTER_H
0039
0040 #include <rtems/score/cpu.h>
0041
0042 #ifdef __cplusplus
0043 extern "C" {
0044 #endif /* __cplusplus */
0045
0046 /**
0047  * @defgroup RTEMSAPICounter Free-Running Counter and Busy Wait Delay
0048  *
0049  * @ingroup RTEMSAPI
0050  *
0051  * @brief Free-running counter and busy wait delay functions.
0052  *
0053  * The RTEMS counter is some free-running counter.  It ticks usually with a
0054  * frequency close to the CPU or system bus clock.
0055  *
0056  * The counter can be used in case the overhead of the
0057  * rtems_clock_get_uptime_nanoseconds() is too high.  The step from counter
0058  * ticks to/from nanoseconds is explicit in this API unlike to
0059  * rtems_clock_get_uptime_nanoseconds() which performs the conversion on each
0060  * invocation.
0061  *
0062  * This counter works without a clock driver and during system initialization.
0063  *
0064  * The counter can be used to profile low-level operations like SMP locks or
0065  * interrupt disabled critical sections.  The counter can act also as an
0066  * entropy source for a random number generator.
0067  *
0068  * The period of the counter depends on the actual hardware.
0069  *
0070  * @{
0071  */
0072
0073 /**
0074  * @brief Unsigned integer type for counter values.
0075  */
0076 typedef CPU_Counter_ticks rtems_counter_ticks;
0077
0078 /**
0079  * @brief Returns the current counter frequency in Hz.
0080  *
0081  * @return The current counter frequency in Hz.
0082  */
0083 static inline uint32_t rtems_counter_frequency( void )
0084 {
0085   return _CPU_Counter_frequency();
0086 }
0087
0088 /**
0089  * @brief Reads the current counter value.
0090  *
0091  * @return The current counter value.
0092  */
0093 static inline rtems_counter_ticks rtems_counter_read( void )
0094 {
0095   return _CPU_Counter_read();
0096 }
0097
0098 /**
0099  * @brief Returns the difference between the second and first CPU counter
0100  * value.
0101  *
0102  * This function is provided for backward compatibility.
0103  * You may use "second - first" directly in the code.
0104  *
0105  * @param[in] second The second CPU counter value.
0106  * @param[in] first The first CPU counter value.
0107  *
0108  * @return Returns second minus first.
0109  */
0110 static inline rtems_counter_ticks rtems_counter_difference(
0111   rtems_counter_ticks second,
0112   rtems_counter_ticks first
0113 )
0114 {
0115   return second - first;
0116 }
0117
0118 /**
0119  * @brief Converts counter ticks into nanoseconds.
0120  *
0121  * @param[in] ticks The counter ticks value to convert.
0122  *
0123  * @return The nanoseconds value corresponding to the counter ticks.  The value
0124  * is rounded up.
0125  */
0126 uint64_t rtems_counter_ticks_to_nanoseconds(
0127   rtems_counter_ticks ticks
0128 );
0129
0130 /**
0131  * @brief Converts nanoseconds into counter ticks.
0132  *
0133  * @param[in] nanoseconds The nanoseconds value to convert.
0134  *
0135  * @return The counter ticks value corresponding to the nanoseconds value.  The
0136  * value is rounded up.
0137  */
0138 rtems_counter_ticks rtems_counter_nanoseconds_to_ticks(
0139   uint32_t nanoseconds
0140 );
0141
0142 /**
0143  * @brief Converts counter ticks into signed binary time (sbintime_t).
0144  *
0145  * @param[in] ticks The counter ticks value to convert.
0146  *
0147  * @return The signed binary time value corresponding to the counter ticks
0148  * value.  The value is rounded up.
0149  */
0150 int64_t rtems_counter_ticks_to_sbintime( rtems_counter_ticks ticks );
0151
0152 /**
0153  * @brief Converts signed binary time (sbintime_t) into counter ticks.
0154  *
0155  * @param[in] sbt The signed binary time value to convert.
0156  *
0157  * @return The counter ticks value corresponding to the nanoseconds value.  The
0158  * value is rounded up.
0159  */
0160 rtems_counter_ticks rtems_counter_sbintime_to_ticks( int64_t sbt );
0161
0162 /**
0163  * @brief Initializes the counter ticks to/from nanoseconds converter functions.
0164  *
0165  * This function must be used to initialize the
0166  * rtems_counter_ticks_to_nanoseconds() and
0167  * rtems_counter_nanoseconds_to_ticks() functions.  It should be called during
0168  * system initialization by the board support package.
0169  *
0170  * @param[in] frequency The current counter frequency in Hz.
0171  */
0172 void rtems_counter_initialize_converter( uint32_t frequency );
0173
0174 /**
0175  * @brief Busy wait for some counter ticks.
0176  *
0177  * This function does not disable interrupts.  Thus task switches and
0178  * interrupts can interfere with this busy wait may prolong the delay.  This
0179  * function busy waits at least the specified time.  Due to some overhead the
0180  * actual delay may be longer.
0181  *
0182  * @param[in] ticks The minimum busy wait time in counter ticks.
0183  */
0184 void rtems_counter_delay_ticks( rtems_counter_ticks ticks );
0185
0186 /**
0187  * @brief Busy wait for some nanoseconds.
0188  *
0189  * This function does not disable interrupts.  Thus task switches and
0190  * interrupts can interfere with this busy wait may prolong the delay.  This
0191  * function busy waits at least the specified time.  Due to some overhead the
0192  * actual delay may be longer.
0193  *
0194  * @param[in] nanoseconds The minimum busy wait time in nanoseconds.
0195  */
0196 void rtems_counter_delay_nanoseconds( uint32_t nanoseconds );
0197
0198 /** @} */
0199
0200 #ifdef __cplusplus
0201 }
0202 #endif /* __cplusplus */
0203
0204 #endif /* _RTEMS_SAPI_COUNTER_H */