sos_timer.h

SOS操作系统用于无线传感器网络节点的源代码

/**
 * @note Modules can pre-allocate timers by specifying the num_timers field
 * in the module header. There is an upper limit on the maximum number of
 * timers that can be pre-allocated by a module. The limit is defined in the
 * timer_conf.h file in the /processor directory.
 */

#ifndef _TIMER0_H
#define _TIMER0_H

#include "hardware_types.h"
#include "pid.h"
#include "sos_list.h"
#include "timer_conf.h"
#include "sos_module_types.h"

enum
  {
    TIMER_REPEAT        = 0, //!< high priority, periodic
    TIMER_ONE_SHOT      = 1, //!< high priority, one shot
    SLOW_TIMER_REPEAT   = 2, //!< low priority, periodic
    SLOW_TIMER_ONE_SHOT = 3, //!< low priority, one shot
  };




#define SLOW_TIMER_MASK                  0x02
#define ONE_SHOT_TIMER_MASK              0x01




enum
  {
    TIMER_PRE_ALLOCATED = 0x02, //! Indicate Timer Block is Pre-allocated
  };

/**
 * @brief Flag helpers
 */
#define flag_timer_pre_allocated(tt)   ((tt->flag) & TIMER_PRE_ALLOCATED)



/**
 * \struct sos_timer_t
 * \brief Kernel data structure for the timer (size is 16 bytes)
 */
typedef struct {
  list_t    list;          //!< list
  uint8_t   type;          //!< timer type
  sos_pid_t pid;           //!< module id of the timer requester
  uint8_t   tid;           //!< timer instance id
  int32_t   ticks;         //!< clock ticks for a repeat timer
  int32_t   delta;         //!< current delta value
  uint8_t   flag;          //!< Timer block status flags
} sos_timer_t;



/**
 * Application timer API
 */
#ifndef _MODULE_
#include <sos_types.h>	



/**
 * @brief Initialize a timer block.
 * @param pid Module Identity
 * @param tid Timer Instance Id, only needs to be unique to the module
 * @param type Type can be {TIMER_REPEAT, TIMER_ONE_SHOT, SLOW_TIMER_REPEAT, SLOW_TIMER_ONE_SHOT
 * @return SOS_OK if a timer block is pre-allocated or already initialized or dynamically allocated
 * @return -ENOMEM if the system is unable to dynamically allocate memory
 * @return -EEXIST if the same timer is already running
 */
extern int8_t ker_timer_init(sos_pid_t pid, uint8_t tid, uint8_t type);


/**
 * @brief Start a new timer
 * @param pid module id
 * @param tid timer instance id, only need to be unique in the module
 * @param interval binary interval
 * @return SOS_OK if a timer was already initialized
 * @return -EINVAL if a timer is already running or it is not initialized
 * @return -EPERM if the timer interval is less than 5
 * @note binary interval uses following conversion
 * 1024 ticks == 1000 milliseconds
 *  512 ticks ==  500 milliseconds
 *  256 ticks ==  250 milliseconds
 *  128 ticks ==  125 milliseconds
 *
 * The interval cannot be less than 5
BY ZHOU YA JIN
NOW we use TIMER3 of CC2430
0.25MHZ and scale 1/128
1953.125 ticks == 1000 ms
 */
extern int8_t ker_timer_start(sos_pid_t pid, uint8_t tid, int32_t interval);

/**
 * @brief Restart a timer
 * @param pid Modue Id
 * @param tid Timer instance id
 * @param interval Binary Interval
 * @return SOS_OK upon success
 * @return -EINVAL if the timer is neither running nor initialized
 * @return -EPERM if the timer interval is less than 5
 * @note Refer to the ker_timer_start API for discussion on the interval
 * ker_timer_restart will:
 * 1. Either stop a running timer and restart it with the new interval
 * 2. Start an initialized timer
 * It will return an error if a timer is not initialized.
 */
extern int8_t ker_timer_restart(sos_pid_t pid, uint8_t tid, int32_t interval);

/**
 * @brief Stop a timer
 * @param pid module id
 * @param tid timer instance id to be stopped
 * @return SOS_OK upon success
 * @return -EINVAL if the timer is not running
 * @note This call will only stop the timer and it will NOT de-allocate its resources.
 * Use the ker_timer_release to deep free timer memory when a timer is no longer needed.
 */
extern int8_t ker_timer_stop(sos_pid_t pid, uint8_t tid);


/**
 * @brief Deep free of a running or initialized timer
 * @param pid Module Id
 * @param tid Timer instance ID to be released
 * @return SOS_OK Upon success
 * @return -EINVAL If no such timer exists
 * @note This call does not free UNINITIALIZED PRE-ALLOCATED timers
 */
extern int8_t ker_timer_release(sos_pid_t pid, uint8_t tid);


//------------------------------------------------------------------------
// KERNEL ACCESSIBLE FUNCTIONS
//------------------------------------------------------------------------

/**
 * @brief Init function
 */
extern void timer_init(void);


/**
 * @brief Initialize a permanent timer for the kernel.
 * @note
 * 1. The space for the timer is statically allocated.
 * 2. This API is accessible only to the statically compiled modules.
 * 3. It is used for reducing the memory consumption.
 */
extern int8_t ker_permanent_timer_init(sos_timer_t* tt, sos_pid_t pid, uint8_t tid, uint8_t type);




/**
 * @brief Remove timers of a particular pid
 */
extern int8_t timer_remove_all(sos_pid_t pid);


/**
 * @brief Pre allocate requested timers at module load time
 */
extern int8_t timer_preallocate(sos_pid_t pid, uint8_t num_timers);


/**
 * @brief Micro-reboot the timer service for the given module
 */
#ifdef FAULT_TOLERANT_SOS
extern int8_t timer_micro_reboot(sos_module_t *handle);
#endif




#endif /* _MODULE_ */

#endif /* _TIMER0_H */