# timer_soft

Copyright (c) 2003 Atmel

## Library Usage

### Package Description

#### Overview

This file contains all functions to manage temporizations and soft time out. The functions use optimized modulo algorithms 8/16bit.

    Typical use of:
    Type:  Timer setup:     Accuracy:    Advised Timeout:
    bits_t Min/Advised/Max  Logical/Phy  Std   / required
    __16s  0ms/32s/65s      1ms / tick   33s   /  > sched_rollover_time
    __16l  0s/2h20/4h40     256ms        2h20  / >> sched_rollover_time
    __8s   0ms/127ms/255ms  1ms / tick   127ms /  > sched_rollover_time
    __8l   0ms/32s/65s      256ms        33s   /  > sched_rollover_time

#### Configuration

Near plug & play, if Timer0 is free.

Available defines:

* I_HAVE_SETUP_SOFT_TIMER_TICK (optional) for advanced purpose, for most applications: do not define this value.

* FOSC (required) FOSC must be setup to relevant value: Ex.: 11059 for 11.059MHz Crystal Do not care of X2 mode in most of cases.

### Package Summary

#### Constants

#### Global Variables

    gl_soft_timer_tick

#### Macros

    set_timerxy

#### Functions

    init_soft_timers
    reload_TH0
    tempo
    Timer0_interrupt

### Files List

- timer_soft.c

This file controls the temporizations of the application. The tempo value is a define symbol in c51_time.h file. The oscillator value is a parameter in c51_time.h file.

- timer_soft.h

Macro definition for soft timers. Note that the standard unit for time is the millisecond (ms). Typical use of: Type: Timer setup: Accuracy: Advised Timeout: bits_t Min/Advised/Max Logical/Phy Std / required __16s 0ms/32s/65s 1ms / tick 33s / > sched_rollover_time __16l 0s/2h20/4h40 256ms 2h20 / >> sched_rollover_time __8s 0ms/127ms/255ms 1ms / tick 127ms / > sched_rollover_time __8l 0ms/32s/65s 256ms 33s / > sched_rollover_time

### Included Files

- config.h
- timer_soft.h

## Types Description

- Timer

    Uint16

- Timer8

    Uint8

- Timer8l

    Uint8

- Timer8s

    Uint8

- Timer16

    Uint16

- Timer16l

    Uint16

- Timer16s

    Uint16

## Constant Macros

## Global Variables

### gl_soft_timer_tick

    volatile Uint32 data gl_soft_timer_tick

Number of ms since mcu reset. This variable is used by soft timers, it must be updated periodically (usually by timer interrupt routine).

## Function Macros

### set_timerxy

    #define set_timer16s ( delay )   (  ( Uint16 )  ( delay ) + ( Uint16 ) gl_soft_timer_tick )
    #define set_timer16l ( delay )   (  ( Uint16 )  (  ( delay ) >>8 ) + ( Uint16 )  ( gl_soft_timer_tick>>8 ) +1 )
    #define set_timer8s ( delay )    (  ( Uint8 )   ( delay ) + ( Uint8 )  gl_soft_timer_tick )
    #define set_timer8l ( delay )    (  ( Uint8 )   (  ( delay ) >>8 ) + ( Uint8 )   ( gl_soft_timer_tick>>8 ) + ( Uint8 ) 1 )
    #define set_timer ( delay )     set_timer16s ( delay )
    #define set_timer16 ( delay )   set_timer16s ( delay )
    #define set_timer8 ( delay )    set_timer8s ( delay )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: timeoutxy
     * ----------------------------------------------------------------------------
     *  PARAMS:
     *  timer:    variable used for timer ,  type xy
     *  delay:    delay in ms
     *  return:   TRUE if timeout ,  FALSE anyelse.
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  Test if a timeout occurs on a timer.
     *  x=8 or 16 or nothing for default  ( number of bits of the variable ,  default=16 )
     *  y=s for short or l for long or nothing for default  ( default=short )
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     *  if  ( timeout ( my_timer , TIMER_1_S )  )  // action
     *  else // wait
     * ----------------------------------------------------------------------------
     *  NOTE:
     *  Use  ( x-1 )  bits value for a correct usage of soft timers.
     *  Be careful that scheduler roll over must be shortest than 2^ ( x-1 )  ms.
     *
     *  This function is more accurate than std_timeoutxy but the speed is lower.
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  The gl_soft_timer_tick must be updated correctly ,  according crystal & x2 mode
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define timeout16s ( timer , delay )   (  (  (  ( Uint16 )  ( timer ) - ( Uint16 ) gl_soft_timer_tick ) <= ( Uint16 )  ( delay )  ) ?FALSE:TRUE )
    #define timeout16l ( timer , delay )   (  (  (  ( Uint16 )  ( timer ) - ( Uint16 )  ( gl_soft_timer_tick>>8 )  ) <= ( Uint16 )  (  ( delay ) >>8 )  ) ?FALSE:TRUE )
    #define timeout8s ( timer , delay )    (  (  (  ( Uint8 )  ( timer ) - ( Uint8 ) gl_soft_timer_tick ) <= ( Uint8 )  ( delay )  ) ?FALSE:TRUE )
    #define timeout8l ( timer , delay )    (  (  (  ( Uint8 )  ( timer ) - ( Uint8 )  ( gl_soft_timer_tick>>8 )  ) <= ( Uint8 )  (  ( delay ) >>8 )  ) ?FALSE:TRUE )
    #define timeout ( timer , delay )     timeout16s ( timer , delay )
    #define timeout16 ( timer , delay )   timeout16s ( timer , delay )
    #define timeout8 ( timer , delay )    timeout8s ( timer , delay )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: std_timeoutxy
     * ----------------------------------------------------------------------------
     *  PARAMS:
     *  timer:    variable used for timer ,  type xy
     *  return:   TRUE if timeout ,  FALSE anyelse.
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  Test if a timeout occurs on a timer.
     *  x=8 or 16 or nothing for default  ( number of bits of the variable ,  default=16 )
     *  y=s for short or l for long or nothing for default  ( default=short )
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     *  if  ( std_timeout ( my_timer )  )  // action
     *  else // wait
     * ----------------------------------------------------------------------------
     *  NOTE:
     *  Use  ( x-1 )  bits value for a correct usage of soft timers.
     *  Be careful that scheduler roll over must be shortest than 2^ ( x-1 )  ms.
     *
     *  This function is less accurate than timeoutxy but the speed is faster.
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  The gl_soft_timer_tick must be updated correctly ,  according crystal & x2 mode
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define std_timeout16s ( timer )     (  (  (  ( Uint16 )  ( timer ) - ( Uint16 ) gl_soft_timer_tick ) <= ( Uint16 ) 32767 ) ?FALSE:TRUE )
    #define std_timeout16l ( timer )     (  (  (  ( Uint16 )  ( timer ) - ( Uint16 )  ( gl_soft_timer_tick>>8 )  ) <= ( Uint16 ) 32767 ) ?FALSE:TRUE )
    #define std_timeout8s ( timer )      (  (  (  ( Uint8 )  ( timer ) - ( Uint8 ) gl_soft_timer_tick ) <= ( Uint8 ) 127 ) ?FALSE:TRUE )
    #define std_timeout8l ( timer )      (  (  (  ( Uint8 )  ( timer ) - ( Uint8 )  ( gl_soft_timer_tick>>8 )  ) <= ( Uint8 ) 127 ) ?FALSE:TRUE )
    #define std_timeout ( timer )       std_timeout16s ( timer )
    #define std_timeout16 ( timer )     std_timeout16s ( timer )
    #define std_timeout8 ( timer )      std_timeout8s ( timer )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: reset_timerxy
     * ----------------------------------------------------------------------------
     *  PARAMS:
     *  timer:    timer to reset
     *  return:   the new value of timer
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  Force a timeout on timer.
     *  x=8 or 16 or nothing for default  ( number of bits of the variable ,  default=16 )
     *  y=s for short or l for long or nothing for default  ( default=short )
     * ----------------------------------------------------------------------------
     *  EXAMPLE:
     *  my_timer=set_timer ( TIMER_1_S ) ;
     *  reset_timer ( my_timer ) ;
     *  if  ( timeout ( my_timer )  )  ... // Always true due to reset_timer
     * ----------------------------------------------------------------------------
     *  NOTE:
     *  Use  ( x-1 )  bits value for a correct usage of soft timers.
     *  Be careful that scheduler roll over must be shortest than 2^ ( x-1 )  ms.
     * ----------------------------------------------------------------------------
     *  REQUIREMENTS:
     *  The gl_soft_timer_tick must be updated correctly ,  according crystal & x2 mode
     *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  * /
    #define reset_timer16s ( timer )     (  ( timer ) = ( Uint16 ) gl_soft_timer_tick-1 )
    #define reset_timer16l ( timer )     (  ( timer ) = ( Uint16 )  ( gl_soft_timer_tick>>8 ) -1 )
    #define reset_timer8s ( timer )      (  ( timer ) = ( Uint8 ) gl_soft_timer_tick- ( Uint8 ) 1 )
    #define reset_timer8l ( timer )      (  ( timer ) = ( Uint8 )  ( gl_soft_timer_tick>>8 ) - ( Uint8 ) 1 )
    #define reset_timer ( timer )       reset_timer16s ( timer )
    #define reset_timer16 ( timer )     reset_timer16s ( timer )
    #define reset_timer8 ( timer )      reset_timer8s ( timer )
    / * M *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
     *  NAME: update_timerxy
     * ----------------------------------------------------------------------------
     *  PARAMS:
     *  timer:    variable used for timer ,  type xy
     *  delay:    delay in ms
     *  return:   the new value of timer
     * ----------------------------------------------------------------------------
     *  PURPOSE:
     *  Update a timer ,
     *  when a timeout occurs ,  to keep accuracy
     *  when an event occurs ,  to delay a timeout keeping time past
     *
     *  x=8 or 16 or nothing for default  ( number of bits of the variable ,  default=16 )
     *  y=s for short or l for long or nothing for default  ( default=short )
     * ----------------------------------------------------------------------------
     *  EXAMPLE:

Set a timer variable. x=8 or 16 or nothing for default (number of bits of the variable, default=16) y=s for short or l for long or nothing for default (default=short)

    delay: delay in ms before timeout
    return:   value to store in the timer variable (x bits)

#### Example

    my_timer=set_timer(TIMER_4_S); // <=> my_timer=set_timer16s(4000);

#### Note

Use (x-1) bits value for a correct usage of soft timers. Be careful that scheduler roll over must be shortest than (x-1) ms.

## Functions

### init_soft_timers

    void init_soft_timers  ( void )

This function initialise the soft timer library.

    return:   none

#### Example

    init_soft_timer();

### reload_TH0

    Byte reload_TH0 ( void )

This function calculate the value to load in TH0 when FOSC is custom (FOSC is not a precomputed value). This function update REMINDER_INC_MS to keep accuracy of timers.

    return:   value to load on TH0

### tempo

    void tempo ( Uint16 delay )

This function manages the temporization.

    delay: tempo value in ms
    return:   none

#### Example

    tempo(TIMER_1_S); // Wait 1 sec.

### Timer0_interrupt

    Interrupt  ( void Timer0_interrupt ( void )  , IRQ_T0 )

This function is the interrupt program for the timer 0.

    return:   none