longan_nano_chrono.hpp

Go to the documentation of this file.

/**********************************************************************************
BSD 3-Clause License
 
Copyright (c) 2020, Orso Eric
All rights reserved.
 
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
 
1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
 
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
 
3. Neither the name of the copyright holder nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.
 
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
**********************************************************************************/
 
/**********************************************************************************
**  ENVIROMENT VARIABILE
**********************************************************************************/
 
#ifndef LONGAN_NANO_CHRONO_H_
    #define LONGAN_NANO_CHRONO_H_
 
/**********************************************************************************
**  GLOBAL INCLUDES
**********************************************************************************/
 
#include <gd32vf103.h>
 
/**********************************************************************************
**  DEFINES
**********************************************************************************/
 
/**********************************************************************************
**  MACROS
**********************************************************************************/
 
/**********************************************************************************
**  NAMESPACE
**********************************************************************************/
 
namespace Longan_nano
{
 
/**********************************************************************************
**  TYPEDEFS
**********************************************************************************/
 
/**********************************************************************************
**  PROTOTYPE: STRUCTURES
**********************************************************************************/
 
/**********************************************************************************
**  PROTOTYPE: GLOBAL VARIABILES
**********************************************************************************/
 
/**********************************************************************************
**  PROTOTYPE: CLASS
**********************************************************************************/
 
/************************************************************************************/
/************************************************************************************/
/************************************************************************************/
 
class Chrono
{
    //Visible to all
    public:
        /*********************************************************************************************************************************************************
        **********************************************************************************************************************************************************
        **  PUBLIC ENUM
        **********************************************************************************************************************************************************
        *********************************************************************************************************************************************************/
 
        typedef enum _Config
        {
            PEDANTIC_CHECKS = false,                //Pedantic checks inside the functions
            SYSTICK_INVALID = 0xFFFFFFFF,   //Invalid timer value
            SYSTICK_PRE     = 4,                    //Prescaler for the systick timer
            TIME_INVALID    = -1,                   //Return time in case time is invalid
        } Config;
        typedef enum _Unit
        {
            milliseconds,
            microseconds,
        } Unit;
 
        /*********************************************************************************************************************************************************
        **********************************************************************************************************************************************************
        **  CONSTRUCTORS
        **********************************************************************************************************************************************************
        *********************************************************************************************************************************************************/
 
        //Empty Constructor
        Chrono( void );
 
        /*********************************************************************************************************************************************************
        **********************************************************************************************************************************************************
        **  DESTRUCTORS
        **********************************************************************************************************************************************************
        *********************************************************************************************************************************************************/
 
        //Empty Destructor
        ~Chrono( void );
 
        /*********************************************************************************************************************************************************
        **********************************************************************************************************************************************************
        **  PUBLIC METHOD
        **********************************************************************************************************************************************************
        *********************************************************************************************************************************************************/
        
        //Snap the start time
        void start( void );
        //Snap the start time and invalidate the stop time and accumulator
        void restart( void );
        //Snap the stop time
        void stop( void );
        //Snap the stop time and return the elapsed time
        int32_t stop( Unit unit );
        //Accumulate DeltaT
        bool accumulate( void );
        //Accumulate DeltaT and return the accumulator time
        int32_t accumulate( Unit unit );
        //Return the elapsed time
        int32_t get_elapsed( Unit unit );
        //Return the accumulator time
        int32_t get_accumulator( Unit unit );
        
        /*********************************************************************************************************************************************************
        **********************************************************************************************************************************************************
        **  PUBLIC STATIC METHOD
        **********************************************************************************************************************************************************
        *********************************************************************************************************************************************************/
 
        //Systick timer frequency
        static unsigned int get_systick_freq( void );
        //Busy wait. Blocking function
        static bool delay( Unit unit, unsigned int delay_tmp );
 
    //Visible only inside the class
    private:
        /*********************************************************************************************************************************************************
        **********************************************************************************************************************************************************
        **  PRIVATE METHODS
        **********************************************************************************************************************************************************
        *********************************************************************************************************************************************************/
 
        //Compute the number of systick counts needed to count one time unit
        static uint32_t compute_tick_per_time_unit( Unit unit );
        //use start and stop timestamp to compute the elapsed time in a given time unit
        int32_t compute_elapsed( uint64_t start, uint64_t stop, Unit unit );
        //use start and stop timestamp to compute the elapsed time in a given time unit
        int32_t compute_accumulator( uint64_t accumulator, Unit unit );
 
        /*********************************************************************************************************************************************************
        **********************************************************************************************************************************************************
        **  PRIVATE VARS
        **********************************************************************************************************************************************************
        *********************************************************************************************************************************************************/
 
        //true = accumulator mode | false = regular start stop mode
        bool g_f_accumulator_mode;
        //Systick Timestamps
        uint64_t g_systick_start;
        //Combined stop and accumulator counter
        uint64_t g_systick_stop;
};  //End Class: Chrono
 
    /*********************************************************************************************************************************************************
    **********************************************************************************************************************************************************
    **  CONSTRUCTORS
    **********************************************************************************************************************************************************
    *********************************************************************************************************************************************************/
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
Chrono::Chrono( void )
{
    //Initialize timestamps to invalid
    this -> g_systick_start = Config::SYSTICK_INVALID;
    this -> g_systick_stop = Config::SYSTICK_INVALID;
    //Regular timer mode
    this -> g_f_accumulator_mode = false;
    
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    
    return;
}   //End Constructor: Chrono | void
 
    /*********************************************************************************************************************************************************
    **********************************************************************************************************************************************************
    **  DESTRUCTORS
    **********************************************************************************************************************************************************
    *********************************************************************************************************************************************************/
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
Chrono::~Chrono( void )
{
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
 
    return;
}
 
    /*********************************************************************************************************************************************************
    **********************************************************************************************************************************************************
    **  PUBLIC METHOD
    **********************************************************************************************************************************************************
    *********************************************************************************************************************************************************/
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
void Chrono::start( void )
{
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------      
    
    //Snap timer start
    this -> g_systick_start = get_timer_value();
    
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    
    return;
}   //End method: start | void
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
void Chrono::restart( void )
{
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------      
    
    //Snap timer start
    this -> g_systick_start = get_timer_value();
    //Infalidate stop
    this -> g_systick_stop = Config::SYSTICK_INVALID;
    this -> g_f_accumulator_mode = false;
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    
    return;
}   //End method: start | void
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
void Chrono::stop( void )
{
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------      
    
    //Snap timer start
    this -> g_systick_stop = get_timer_value();
    //Regular timer mode
    this -> g_f_accumulator_mode = false;
    
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    
    return;
}   //End method: stop | void
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
int32_t Chrono::stop( Unit unit )
{
    //----------------------------------------------------------------
    //  CHECK
    //----------------------------------------------------------------
    
    //Get start time
    uint64_t start_tmp = this -> g_systick_start;
    //If: bad timestamp
    if ((Config::PEDANTIC_CHECKS == true) && (start_tmp == Config::SYSTICK_INVALID))
    {
        return Config::TIME_INVALID; //FAIL
    }
    
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------      
    
    //Snap the timestamp
    uint64_t stop_tmp = get_timer_value();
    //Record the stop timestamp inside the timer
    this -> g_systick_stop = stop_tmp;
    //Regular timer mode
    this -> g_f_accumulator_mode = false;
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    //return elapsed time
    return this -> compute_elapsed( start_tmp, stop_tmp, unit );
}   //End method: stop | Unit |
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
bool Chrono::accumulate( void )
{
    //----------------------------------------------------------------
    //  CHECK
    //----------------------------------------------------------------
    
    //Get start time
    uint64_t start_tmp = this -> g_systick_start;
    //If: bad timestamp
    if ((Config::PEDANTIC_CHECKS == true) && (start_tmp == Config::SYSTICK_INVALID))
    {
        return true; //FAIL
    }
    //Temp accumulator
    uint64_t accumulator_tmp;
    //if: Regular timer mode
    if (this -> g_f_accumulator_mode == false)
    {
        //reset the accumulator
        accumulator_tmp = 0;
        //go into accumulator mode
        this -> g_f_accumulator_mode = true;
    }
    //If: accumulator mode
    else
    {
        //Fetch the current accumulator count
        accumulator_tmp = this -> g_systick_stop;
    }
 
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------
 
    //Snap the timestamp
    uint64_t stop_tmp = get_timer_value();
    //Record the stop timestamp inside the start timestamp and invalidate the stop timestamp
    this -> g_systick_start = stop_tmp;
    //Accumulate the DeltaT inside the accumulator at full resolution
    accumulator_tmp += stop_tmp -start_tmp;
    //Store the accumulator value
    this -> g_systick_stop = accumulator_tmp;
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    
    return false; //OK
}   //End public method: accumulate | void |
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
int32_t Chrono::accumulate( Unit unit )
{
    //----------------------------------------------------------------
    //  CHECK
    //----------------------------------------------------------------
    
    //Get start time
    uint64_t start_tmp = this -> g_systick_start;
    //If: bad timestamp
    if ((Config::PEDANTIC_CHECKS == true) && (start_tmp == Config::SYSTICK_INVALID))
    {
        return true; //FAIL
    }
    //Temp accumulator
    uint64_t accumulator_tmp;
    //if: Regular timer mode
    if (this -> g_f_accumulator_mode == false)
    {
        //reset the accumulator
        accumulator_tmp = 0;
        //go into accumulator mode
        this -> g_f_accumulator_mode = true;
    }
    //If: accumulator mode
    else
    {
        //Fetch the current accumulator count
        accumulator_tmp = this -> g_systick_stop;
    }
 
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------
 
    //Snap the timestamp
    uint64_t stop_tmp = get_timer_value();
    //Record the stop timestamp inside the start timestamp and invalidate the stop timestamp
    this -> g_systick_start = stop_tmp;
    //Accumulate the DeltaT inside the accumulator at full resolution
    accumulator_tmp += stop_tmp -start_tmp;
    //Store the accumulator value
    this -> g_systick_stop = accumulator_tmp;
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    
    return this -> compute_accumulator( accumulator_tmp, unit );
}   //End public method: accumulate | void |
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
int32_t Chrono::get_elapsed( Unit unit )
{
    //----------------------------------------------------------------
    //  VARS
    //----------------------------------------------------------------
 
    //Fetch timestamps
    uint64_t start_tmp = this -> g_systick_start;
    uint64_t stop_tmp = this -> g_systick_stop;
 
    //----------------------------------------------------------------
    //  CHECKS
    //----------------------------------------------------------------
    
    //If: a timetamp is invalid
    if ((start_tmp == Config::SYSTICK_INVALID) || (stop_tmp == Config::SYSTICK_INVALID))
    {
        return Config::TIME_INVALID;    //Invalid
    }
    //If: accumulator mode
    if (this -> g_f_accumulator_mode == true)
    {
        return Config::TIME_INVALID;    //Invalid
    }
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    //return elapsed time
    return compute_elapsed( start_tmp, start_tmp, unit );
}   //End public getter: get_elapsed |  Unit |
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
inline int32_t Chrono::get_accumulator( Unit unit )
{
    //----------------------------------------------------------------
    //  CHECK
    //----------------------------------------------------------------
    //If: accumulator mode
    if (this -> g_f_accumulator_mode == false)
    {
        return Config::TIME_INVALID;    //Invalid
    }
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    //return accumulated time
    return this -> compute_accumulator( this -> g_systick_stop, unit );
}   //End public getter: get_elapsed |  Unit |
 
    /*********************************************************************************************************************************************************
    **********************************************************************************************************************************************************
    **  PUBLIC STATIC METHOD
    **********************************************************************************************************************************************************
    *********************************************************************************************************************************************************/
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
unsigned int Chrono::get_systick_freq( void )
{
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
    
    return SystemCoreClock /Config::SYSTICK_PRE;
}   //End static method: get_systick_freq | void
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
bool Chrono::delay( Unit unit, unsigned int delay_tmp )
{
    //----------------------------------------------------------------
    //  VARS
    //----------------------------------------------------------------
 
    //Temp timestamp
    uint64_t systick_tmp;
    //Compute final timestamp
    uint64_t systick_stop;
    //Ticks required to count 1mS
    uint32_t numticks = compute_tick_per_time_unit( unit );
    //If: bad unit
    if (numticks == 0)
    {
        return true; //fail
    }
 
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------
    //  Wait for the correct number of ticks
 
    //Snap start
    systick_stop = get_timer_value();
    //Compute stop time. 
    systick_stop += numticks *delay_tmp;
    //Wait an additional tick for current tick
    systick_stop++;
    //Busy wait for time to pass
    do
    {
        //Snap timestamp
        systick_tmp = get_timer_value();
    }
    while( systick_tmp < systick_stop );
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
 
    return false; //OK
}   //End public static method: delay | Unit | unsigned int |
 
    /*********************************************************************************************************************************************************
    **********************************************************************************************************************************************************
    **  PRIVATE METHODS
    **********************************************************************************************************************************************************
    *********************************************************************************************************************************************************/
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
inline uint32_t Chrono::compute_tick_per_time_unit( Unit unit )
{
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------
    //  Compute del
 
    //Switch: Time unit
    switch( unit )
    {
        case Unit::milliseconds:
        {
            return SystemCoreClock /1000 /Config::SYSTICK_PRE;
            break;
        }
        case Unit::microseconds:
        {
            return SystemCoreClock /1000000 /Config::SYSTICK_PRE;
            break;
        }
        //Unhandled time unit
        default:
        {
            return 0;   //Invalid number of systick counts. Using it will yield infinite time
        }
    };  //End switch: Time unit
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
 
    return 0;   //Invalid number of systick counts. Using it will yield infinite time
}   //End private method: compute_tick_per_time_unit | Unit |
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
inline int32_t Chrono::compute_elapsed( uint64_t start, uint64_t stop, Unit unit )
{
    //----------------------------------------------------------------
    //  VARS
    //----------------------------------------------------------------
 
    //If: causality violation
    if ((Config::PEDANTIC_CHECKS == true) && (start > stop))
    {
        //Hopefully the timestamps are wrong and the universe still works as intended
        return Config::TIME_INVALID; //FAIL
    }
    
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------      
    
    //SysTick counts in one time unit
    uint32_t numticks_time_unit = this -> compute_tick_per_time_unit( unit );
    //If: bad unit was provided
    if ((Config::PEDANTIC_CHECKS == true) && (numticks_time_unit == 0))
    {
        return TIME_INVALID;
    }
    //Compute DeltaT in system ticks as stop-start
    uint64_t deltat = stop -start;
    //Compute DeltaT in time units
    deltat /= numticks_time_unit;
    //Demote
    int32_t ret = deltat;
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
 
    return ret;
}   //End private method: compute_elapsed | uint64_t | uint64_t | Unit |
 
/***************************************************************************/
/***************************************************************************/
/***************************************************************************/
 
int32_t Chrono::compute_accumulator( uint64_t accumulator, Unit unit )
{
    //----------------------------------------------------------------
    //  VARS
    //----------------------------------------------------------------
 
    //If: accumulator
    if ((Config::PEDANTIC_CHECKS == true) && (accumulator == Config::SYSTICK_INVALID))
    {
        return TIME_INVALID;
    }
    
    //----------------------------------------------------------------
    //  BODY
    //----------------------------------------------------------------      
    
    //SysTick counts in one time unit
    uint32_t numticks_time_unit = this -> compute_tick_per_time_unit( unit );
    //If: bad unit was provided
    if ((Config::PEDANTIC_CHECKS == true) && (numticks_time_unit == 0))
    {
        return TIME_INVALID;
    }
    //Compute DeltaT in time units
    accumulator /= numticks_time_unit;
    //Demote
    int32_t ret = accumulator;
 
    //----------------------------------------------------------------
    //  RETURN
    //----------------------------------------------------------------
 
    return ret;
}   //End private method: compute_accumulator | uint64_t | Unit |
 
/**********************************************************************************
**  NAMESPACE
**********************************************************************************/
 
} //End Namespace: Longan_nano
 
#else
    #warning "Multiple inclusion of hader file LONGAN_NANO_CHRONO_H_"
#endif