include/rtems/btimer.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @brief RTEMS Benchmark Timer API for all Boards
0007  */
0008
0009 /*
0010  *  COPYRIGHT (c) 2011 Ralf Corsépius Ulm/Germany
0011  *
0012  *  Derived from libcsupport/include/timerdrv.h:
0013  *
0014  *  COPYRIGHT (c) 1989-1999.
0015  *  On-Line Applications Research Corporation (OAR).
0016  *
0017  * Redistribution and use in source and binary forms, with or without
0018  * modification, are permitted provided that the following conditions
0019  * are met:
0020  * 1. Redistributions of source code must retain the above copyright
0021  *    notice, this list of conditions and the following disclaimer.
0022  * 2. Redistributions in binary form must reproduce the above copyright
0023  *    notice, this list of conditions and the following disclaimer in the
0024  *    documentation and/or other materials provided with the distribution.
0025  *
0026  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0027  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0028  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0029  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0030  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0031  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0032  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0033  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0034  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0035  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0036  * POSSIBILITY OF SUCH DAMAGE.
0037  */
0038
0039 /*
0040  * All the functions declared as extern after this comment
0041  * MUST be implemented in each BSP.
0042  */
0043
0044 #ifndef _RTEMS_BTIMER_H
0045 #define _RTEMS_BTIMER_H
0046
0047 #include <stdbool.h>
0048 #include <stdint.h>
0049 #include <rtems/rtems/status.h>
0050
0051 #ifdef __cplusplus
0052 extern "C" {
0053 #endif
0054
0055 /**
0056  * @defgroup BenchmarkTimer Benchmark Timer Driver Interface
0057  *
0058  * @ingroup RTEMSLegacyBenchmarkDrivers
0059  *
0060  * This module defines the interface for the Benchmark Timer Driver.
0061  *
0062  * The following methods in this module must be provided by each BSP:
0063  *
0064  *   - benchmark_timer_initialize
0065  *   - benchmark_timer_read
0066  *   - benchmark_timer_disable_subtracting_average_overhead
0067  *
0068  * The units measured are BSP specific but should be at the highest
0069  * granularity possible.
0070  *
0071  * The Benchmark Timer may use the same hardware as the Clock Driver.
0072  * No RTEMS Timing Tests will use both drivers at the same time.
0073  */
0074
0075 /**
0076  * @brief This type is used to return a Benchmark Timer value.
0077  *
0078  * This type is used to contain benchmark times. The units are BSP specific.
0079  */
0080 typedef uint32_t benchmark_timer_t;
0081
0082 /**
0083  * @brief Initialize the Benchmark Timer
0084  *
0085  * This method initializes the benchmark timer and resets it to begin
0086  * counting.
0087  */
0088 extern void benchmark_timer_initialize( void );
0089
0090 /**
0091  * @brief Read the Benchmark Timer
0092  *
0093  * This method stops the benchmark timer and returns the number of
0094  * units that have passed since @a benchmark_timer_initialize was invoked.
0095  *
0096  * @return This method returns the number of units with the average overhead
0097  *          removed. If the value is below the minimum trusted value, zero
0098  *          is returned.
0099  */
0100 extern benchmark_timer_t benchmark_timer_read( void );
0101
0102 /**
0103  * @brief Benchmark Timer Empty Function
0104  *
0105  * This method is used to determine loop overhead.
0106  */
0107 extern rtems_status_code benchmark_timer_empty_function( void );
0108
0109 /**
0110  * @brief Disable Average Overhead Removal from the Benchmark Timer
0111  *
0112  * This method places the benchmark timer in a "raw" mode where it
0113  * returns the actual number of units which have passed between
0114  * calls to @a benchmark_timer_initialize and @a benchmark_timer_read
0115  * counting.
0116  *
0117  * @param[in] find_flag indicates to enable or disable the mode
0118  */
0119 extern void benchmark_timer_disable_subtracting_average_overhead(
0120   bool find_flag
0121 );
0122
0123 /**@}*/
0124
0125 #ifdef __cplusplus
0126 }
0127 #endif
0128
0129 #endif