bcm68620_release/release/host_reference/time_measurement/bcmolt_time_measurement.h

/*
<:copyright-BRCM:2014:proprietary:standard
 
   Copyright (c) 2014 Broadcom Corporation
   All Rights Reserved
 
This program is the proprietary software of Broadcom Corporation and/or its
licensors, and may only be used, duplicated, modified or distributed pursuant
to the terms and conditions of a separate, written license agreement executed
between you and Broadcom (an "Authorized License").  Except as set forth in
an Authorized License, Broadcom grants no license (express or implied), right
to use, or waiver of any kind with respect to the Software, and Broadcom
expressly reserves all rights in and to the Software and all intellectual
property rights therein.  IF YOU HAVE NO AUTHORIZED LICENSE, THEN YOU HAVE
NO RIGHT TO USE THIS SOFTWARE IN ANY WAY, AND SHOULD IMMEDIATELY NOTIFY
BROADCOM AND DISCONTINUE ALL USE OF THE SOFTWARE.
 
Except as expressly set forth in the Authorized License,
 
1. This program, including its structure, sequence and organization,
    constitutes the valuable trade secrets of Broadcom, and you shall use
    all reasonable efforts to protect the confidentiality thereof, and to
    use this information only in connection with your use of Broadcom
    integrated circuit products.
 
2. TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE SOFTWARE IS PROVIDED "AS IS"
    AND WITH ALL FAULTS AND BROADCOM MAKES NO PROMISES, REPRESENTATIONS OR
    WARRANTIES, EITHER EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE, WITH
    RESPECT TO THE SOFTWARE.  BROADCOM SPECIFICALLY DISCLAIMS ANY AND
    ALL IMPLIED WARRANTIES OF TITLE, MERCHANTABILITY, NONINFRINGEMENT,
    FITNESS FOR A PARTICULAR PURPOSE, LACK OF VIRUSES, ACCURACY OR
    COMPLETENESS, QUIET ENJOYMENT, QUIET POSSESSION OR CORRESPONDENCE
    TO DESCRIPTION. YOU ASSUME THE ENTIRE RISK ARISING OUT OF USE OR
    PERFORMANCE OF THE SOFTWARE.
 
3. TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL BROADCOM OR
    ITS LICENSORS BE LIABLE FOR (i) CONSEQUENTIAL, INCIDENTAL, SPECIAL,
    INDIRECT, OR EXEMPLARY DAMAGES WHATSOEVER ARISING OUT OF OR IN ANY
    WAY RELATING TO YOUR USE OF OR INABILITY TO USE THE SOFTWARE EVEN
    IF BROADCOM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES;
    OR (ii) ANY AMOUNT IN EXCESS OF THE AMOUNT ACTUALLY PAID FOR THE
    SOFTWARE ITSELF OR U.S. $1, WHICHEVER IS GREATER. THESE LIMITATIONS
    SHALL APPLY NOTWITHSTANDING ANY FAILURE OF ESSENTIAL PURPOSE OF ANY
    LIMITED REMEDY.
:>
*/
#ifndef _BCMOLT_TIME_MEASUREMENT_H_
#define _BCMOLT_TIME_MEASUREMENT_H_

#include <bcmos_common.h>
#include <bcm_dev_log.h>

/* How to use the time measurement library:
 * 
 * Before including bcmolt_time_measurement.h, you must define BCMOLT_TIME_MEASUREMENT_TIMESTAMP.  This macro must be
 * defined in such a way that this is legal: "uint32_t timestamp_in_ticks = BCMOLT_TIME_MEASUREMENT_TIMESTAMP()".  We
 * use a macro instead of a function to optimize for time (we want to avoid the overhead of a function call).
 *
 * You can have as many named measurement categories as desired.  For each category, you need to call either:
 * - BCMOLT_TIME_MEASUREMENT_SAMPLE_DECL_STATIC() - if the measurements are all taken in the same file
 * or:
 * - BCMOLT_TIME_MEASUREMENT_SAMPLE_DECL() + BCMOLT_TIME_MEASUREMENT_SAMPLE_DECL_EXTERN()
 *
 * At init time, you must call bcmolt_time_measurement_init().
 *
 * For the actual measurements, you must surround the code you're trying to measure with 
 * BCMOLT_TIME_MEASUREMENTS_SAMPLE_BEFORE() and BCMOLT_TIME_MEASUREMENTS_SAMPLE_AFTER().  At the end of a full
 * measurement cycle, you must call BCMOLT_TIME_MEASUREMENTS_SAMPLE_END() for each named measurement category, then
 * finally call BCMOLT_TIME_MEASUREMENTS_CYCLE_END().
 */

typedef uint64_t (*F_bcmolt_time_measurement_ticks_to_ns)(uint64_t ticks);
typedef void (*F_bcmolt_time_measurement_avg_done)(void);

/** Called for each measurement category at compile time (see how-to at top of file). */
#define BCMOLT_TIME_MEASUREMENT_SAMPLE_DECL_STATIC(measurement_name) \
    static uint32_t measurement_name ## _start_tick; \
    static uint64_t measurement_name ## _total_ticks; \
    static uint32_t measurement_name ## _num_of_samples;

/** Called for each measurement category at compile time (see how-to at top of file). */
#define BCMOLT_TIME_MEASUREMENT_SAMPLE_DECL(measurement_name) \
    uint32_t measurement_name ## _start_tick; \
    uint64_t measurement_name ## _total_ticks; \
    uint32_t measurement_name ## _num_of_samples;

/** Called for each measurement category at compile time (see how-to at top of file). */
#define BCMOLT_TIME_MEASUREMENT_SAMPLE_DECL_EXTERN(measurement_name) \
    extern uint32_t measurement_name ## _start_tick; \
    extern uint64_t measurement_name ## _total_ticks; \
    extern uint32_t measurement_name ## _num_of_samples;

/** Called before each block of code that needs to be timed (see how-to at top of file). */
#define BCMOLT_TIME_MEASUREMENTS_SAMPLE_BEFORE(measurement_name) \
    do \
    { \
        measurement_name ## _start_tick = BCMOLT_TIME_MEASUREMENT_TIMESTAMP(); \
    } \
    while (0)

/** Called after each block of code that needs to be timed (see how-to at top of file). */
#define BCMOLT_TIME_MEASUREMENTS_SAMPLE_AFTER(measurement_name) \
    do \
    { \
        /* Even if timestamp overflows we are still ok - unsigned arithmetic will still be valid. */ \
        measurement_name ## _total_ticks += BCMOLT_TIME_MEASUREMENT_TIMESTAMP() - measurement_name ## _start_tick; \
        ++measurement_name ## _num_of_samples; \
    } \
    while (0)

/** Called for each measurement category at the end of a cycle (see how-to at top of file). */
#define BCMOLT_TIME_MEASUREMENTS_SAMPLE_END(measurement_name) \
    do \
    { \
        bcmolt_time_measurement_sample_end( \
            &measurement_name ## _total_ticks, \
            &measurement_name ## _num_of_samples, \
            # measurement_name); \
    } \
    while (0)

/** Called when the entire measurement cycle is complete (see how-to at top of file). */
#define BCMOLT_TIME_MEASUREMENTS_CYCLE_END() bcmolt_time_measurement_cycle_end()

/** Must be called at init time to initialize the time measurement library.
 * \param log_id                 Log ID to use for displaying data (will use 'DEBUG' log level).
 * \param num_cycles_for_average Number of measurement cycles to run before calculating and logging averages.
 * \param ticks_to_ns            Function that translates timestamp resolution (ticks) into nanoseconds.
 * \param avg_done               Function to call after averages have been computed (e.g. to log a custom header).
 */
void bcmolt_time_measurement_init(
    dev_log_id log_id,
    uint32_t num_cycles_for_average,
    F_bcmolt_time_measurement_ticks_to_ns ticks_to_ns,
    F_bcmolt_time_measurement_avg_done avg_done);

/** Do not call this directly - call BCMOLT_TIME_MEASUREMENTS_SAMPLE_END() instead. */
void bcmolt_time_measurement_sample_end(uint64_t *total_ticks, uint32_t *num_of_samples, const char *measurement_name);

/** Do not call this directly - call BCMOLT_TIME_MEASUREMENTS_CYCLE_END() instead. */
void bcmolt_time_measurement_cycle_end(void);

#endif /* _BCMOLT_TIME_MEASUREMENT_H_ */