mcu/service/mertos/include/mer_service_timer.h

/*****************************************************************************
*  Copyright Statement:
*  --------------------
*  This software is protected by Copyright and the information contained
*  herein is confidential. The software may not be copied and the information
*  contained herein may not be used or disclosed except with the written
*  permission of MediaTek Inc. (C) 2018
*
*  BY OPENING THIS FILE, BUYER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES
*  THAT THE SOFTWARE/FIRMWARE AND ITS DOCUMENTATIONS ("MEDIATEK SOFTWARE")
*  RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES ARE PROVIDED TO BUYER ON
*  AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES,
*  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
*  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.
*  NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE
*  SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR
*  SUPPLIED WITH THE MEDIATEK SOFTWARE, AND BUYER AGREES TO LOOK ONLY TO SUCH
*  THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. MEDIATEK SHALL ALSO
*  NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO BUYER'S
*  SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM.
*
*  BUYER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND CUMULATIVE
*  LIABILITY WITH RESPECT TO THE MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE,
*  AT MEDIATEK'S OPTION, TO REVISE OR REPLACE THE MEDIATEK SOFTWARE AT ISSUE,
*  OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY BUYER TO
*  MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.
*
*  THE TRANSACTION CONTEMPLATED HEREUNDER SHALL BE CONSTRUED IN ACCORDANCE
*  WITH THE LAWS OF THE STATE OF CALIFORNIA, USA, EXCLUDING ITS CONFLICT OF
*  LAWS PRINCIPLES.  ANY DISPUTES, CONTROVERSIES OR CLAIMS ARISING THEREOF AND
*  RELATED THERETO SHALL BE SETTLED BY ARBITRATION IN SAN FRANCISCO, CA, UNDER
*  THE RULES OF THE INTERNATIONAL CHAMBER OF COMMERCE (ICC).
*
*****************************************************************************/

/*****************************************************************************
*
* Filename:
* ---------
*   mer_service_timer.h
*
* Project:
* --------
*   MERTOS
*
* Description:
* ------------
*   Declare data structures and functions for timer.
*
* Author:
* -------
 * -------
*
*****************************************************************************/

#ifndef _MER_SERVICE_TIMER_H_
#define _MER_SERVICE_TIMER_H_

#include "mer_service_types.h"
#include "mer_service_task.h"
#include "mer_kernel_timer.h"
#include "mer_kernel_lock_target_mips.h"

///////////////////////////////////////////////////////////////////////////////
// enum
///////////////////////////////////////////////////////////////////////////////
typedef enum {
    MER_SERVICE_TIMER_ENABLE = 0,
    MER_SERVICE_TIMER_DISABLE = 1
} mer_service_timer_state;

typedef enum{
    MER_SERVICE_TIMER_TYPE_CB = 0,
    MER_SERVICE_TIMER_TYPE_SUSPEND = 1
} mer_service_timer_type;

#define MER_SERVICE_TIMER_MAX (0xFFFFFFFF)
// the following pattern is just for debug, and can be stripted in the future for better performance
#define MER_SERVICE_ALIGNED_TIMER (0xcbcb)
#define MER_SERVICE_UNALIGNED_TIMER (0xbcbc)

///////////////////////////////////////////////////////////////////////////////
// Structure
///////////////////////////////////////////////////////////////////////////////
typedef struct _mer_service_timer
{
    mer_kernel_timer_tick_info kernel_timer_cb;
    mer_service_timer_type  type;
    mer_service_timer_state state;      // for easy debugging 
    mer_uint32              expiration;
    mer_char                name[16];   // for easy debugging
    void                (*cb)(void *);
    void                *param;
    mer_uint32          reschedule;
    mer_uint32          delay;
    mer_uint32          max_delay;
} mer_service_timer;
typedef mer_service_timer *mer_service_timer_id;

///////////////////////////////////////////////////////////////////////////////
/**
 * Create an call back timer
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] tid suspend timer control block address 
 * @param[in] name call back timer name, for debugging
 *
 */
MER_STATUS mer_service_timer_create(
    mer_service_timer_id tid, 
    const mer_char *name
);

/**
 * start an call back timer with given parameters 
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] tid call back timer control block address 
 * @param[in] name call back timer name, for debugging
 *
 */
MER_STATUS mer_service_timer_set(
    mer_service_timer_id tid,
    void (*cb)(void *),
    void *param,
    mer_uint32 init_delay,
    mer_uint32 reschedule
    );

/**
 * let suspend suspend with timeout
 * note that if it is used for getting resource, this function may early return
 * upper layer users must check by themself if the return is due to timeout or 
 * the resource is seccessifully gotten by the suspend
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] task_id timer control block address 
 * @param[in] timeout timeout of the suspend
 * @param[in] state reason of calling this function 
 * @param[in] lock_to_release the lock to release if any 
 *
 */
MER_STATUS mer_service_timer_suspend_task_with_timeout(
        mer_service_task_id task_id,
        mer_uint32 timeout,
        mer_service_task_state state,
        mer_kernel_lock_id *lock_to_release
    );


/**
 * cancel a timer 
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] tid timer control block address 
 *
 */
MER_STATUS mer_service_timer_stop(mer_service_timer_id);

/**
 * set the max delay of a timer, only valid for call back timer
 * note that this function will not start a timer
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] tid timer control block address 
 *
 */
MER_STATUS mer_service_timer_set_max_delay(mer_service_timer_id tid, mer_uint16 delay);

/**
 * cancel the max delay of a timer
 * note that this function will not start a timer
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] tid timer control block address 
 * @param[in] dealy maximum allowable delay for this timer 
 *
 */
MER_STATUS mer_service_timer_cancel_max_delay(mer_service_timer_id tid);

/**
 * set the max delay for task suspend timer, 
 * note that this function will not start a timer
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] tid timer control block address 
 *
 */

MER_STATUS mer_service_timer_set_suspend_max_delay(mer_uint16 delay);
/**
 * cancel the max delay for task suspend timer, 
 * note that this function will not start a timer
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 * @param[in] task_id task to set 
 * @param[in] dealy maximum allowable delay for this timer 
 *
 */
MER_STATUS mer_service_timer_cancel_suspend_max_delay();

/**
 * get the remaining time of the timer 
 * if the timer is not running or expired, it will return 0
 *
 * @param[out] MER_UINT32 remaining time, 0 if the timer is not running or expired 
 * @param[in] task_id task to cancel 
 *
 */

mer_uint32 mer_service_timer_get_remaining_time(mer_service_timer_id tid);

/**
 * handle the timers in dpc 
 * -1 will be returned if creation fails
 *
 * @param[out] MER_STATUS Success = 0, Fail = -1.
 *
 */
MER_STATUS mer_service_timer_expiration();

static inline mer_bool mer_service_timer_is_expired(mer_service_timer_id tid)
{
    mer_uint32 now = mer_kernel_timer_get_current_tick();
    mer_uint32 start_time = tid->expiration - tid->delay;
    mer_bool is_wrap = (tid->expiration < start_time);

    if((!is_wrap && !(now >= start_time && now < tid->expiration)) ||
       (is_wrap && now >= tid->expiration && now < start_time)) {
        return MER_TRUE;
    }
    else {
        return MER_FALSE;
    }
}

/*#define MER_SERVICE_TIMER_DEBUG*/

// we do not have many tasks, 256 should be enough
#ifdef MER_SERVICE_TIMER_DEBUG

#define MER_SERVICE_TIMER_GLOBAL_COUNT (256)
#define MER_SERVICE_TIMER_GLOBAL_GUARD_PATTERN (0x5566dead)
/*global timer*/
/*global timer*/
/*global timer*/
typedef struct _mer_service_timer_global
{
    mer_uint32 guard_front;
    mer_service_task_id owner;
    mer_uint32 working;
    mer_service_timer timer;
    mer_uint32 guard_back;
} mer_service_timer_global;

typedef mer_service_timer_global *mer_service_timer_global_id;

mer_service_timer_id get_mer_service_timer_cb_global(mer_service_task_id task_id);
void check_mer_service_timer_cb_global(mer_service_timer_id tid);
void release_mer_service_timer_cb_global(mer_service_timer_id tid);

typedef enum {
    MER_SERVICE_TIMER_TRACE_OP_SET = 0,
    MER_SERVICE_TIMER_TRACE_OP_STOP = 1,
    MER_SERVICE_TIMER_TRACE_OP_SUSPEND = 2, 
} mer_service_timer_trace_op;

typedef struct _mer_service_timer_trace {
    mer_service_timer_id tid;
    kal_uint32 now;
    kal_uint32 expiration;
    kal_uint32 reschedule;
    kal_uint32 max_delay;
    kal_uint32 lr;
    mer_service_timer_trace_op op;
} mer_service_timer_trace;

void mer_service_timer_set_trace(mer_service_timer_id tid, 
        kal_uint32 delay, 
        kal_uint32 reschedule,
        kal_uint32 lr, mer_service_timer_trace_op op);

#endif /* MER_SERVICE_TIMER_DEBUG */

#endif /* _MER_SERVICE_TIMER_H */