/*---------------------------------------------------------------------------*
  Project:  NitroSDK - OS - include
  File:     alarm.h

  Copyright 2003-2004 Nintendo.  All rights reserved.

  These coded instructions, statements, and computer programs contain
  proprietary information of Nintendo of America Inc. and/or Nintendo
  Company Ltd., and are protected by Federal copyright law.  They may
  not be disclosed to third parties or copied or duplicated in any form,
  in whole or in part, without the prior written consent of Nintendo.

  $Log: alarm.h,v $
  Revision 1.8  2004/11/02 09:58:57  yada
  just fix comment

  Revision 1.7  2004/04/07 02:03:17  yada
  fixed header comment

  Revision 1.6  2004/02/25 11:28:44  yada
  made changes in accordance with systemClock ->Tick

  Revision 1.5  2004/02/24 10:50:47  yada
  added alarm counter and actual time conversion definition

  Revision 1.4  2004/02/19 08:43:36  yada
  only added comment

  Revision 1.3  2004/02/05 07:09:03  yasu
  changed SDK prefix iris -> nitro

  Revision 1.2  2004/02/04 07:31:46  yada
  added OS_IsAlarmAvailable(), OS_EndAlarm()

  Revision 1.1  2004/02/03 11:18:58  yada
  first release

  Revision 1.1  2003/12/22 01:35:16  yada
  made init.h in accordance with OS_Init() installation


  $NoKeywords: $
 *---------------------------------------------------------------------------*/

#ifndef NITRO_OS_ALARM_H_
#define NITRO_OS_ALARM_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <nitro/misc.h>
#include <nitro/types.h>


//--------------------------------------------------------------------------------
//---- Alarm Handler
typedef void          (*OSAlarmHandler)( void*);


//---- struct of Alarm
typedef struct OSiAlarm  OSAlarm;
struct OSiAlarm
{
        OSAlarmHandler  handler;
        void*           arg;

        u32             tag;
        OSTick          fire;
        OSAlarm*        prev;
        OSAlarm*        next;

        //---- for periodic alarm
        OSTick          period;
        OSTick          start;
};

//--------------------------------------------------------------------------------
/*---------------------------------------------------------------------------*
  Name:         OS_InitAlarm

  Description:  initalize alarm system

  Arguments:    None.

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_InitAlarm( void );


/*---------------------------------------------------------------------------*
  Name:         OS_EndAlarm

  Description:  end alarm system

  Arguments:    None

  Returns:      None
 *---------------------------------------------------------------------------*/
void OS_EndAlarm( void );


/*---------------------------------------------------------------------------*
  Name:         OS_IsAlarmAvailable

  Description:  check alarm system is available

  Arguments:    None

  Returns:      if available, TRUE.
 *---------------------------------------------------------------------------*/
BOOL OS_IsAlarmAvailable( void );


/*---------------------------------------------------------------------------*
  Name:         OS_CreateAlarm

  Description:  Create alarm

  Arguments:    alarm       pointer to alarm to be initialized

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_CreateAlarm( OSAlarm* alarm );


/*---------------------------------------------------------------------------*
  Name:         OS_SetAlarm

  Description:  Set alarm as a relative time

  Arguments:    alarm       pointer to alarm to be set
                tick        ticks to count before firing
                handler     alarm handler to be called
                arg         argument of handler

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_SetAlarm( OSAlarm* alarm, OSTick tick, OSAlarmHandler handler, void* arg );


/*---------------------------------------------------------------------------*
  Name:         OS_SetPeriodicAlarm

  Description:  set periodic alarm 

  Arguments:    alarm          pointer to alarm to be set
                start          origin of the period in absolute time
                period         ticks to count for each period
                handler        alarm handler to be called
                arg            argument of handler

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_SetPeriodicAlarm( OSAlarm* alarm, OSTick start, OSTick period, OSAlarmHandler handler, void* arg );


/*---------------------------------------------------------------------------*
  Name:         OS_SetAlarmTag

  Description:  set tag which is used OS_CancelAlarms

  Arguments:    alarm        alarm to be set tag
                tag          tagNo

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_SetAlarmTag( OSAlarm* alarm, u32 tag );


/*---------------------------------------------------------------------------*
  Name:         OS_CancelAlarm

  Description:  Cancel alarm

  Arguments:    alarm       pointer to alarm to be canceled

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_CancelAlarm( OSAlarm* alarm );


/*---------------------------------------------------------------------------*
  Name:         OS_CancelAlarms

  Description:  cancel alarms which have specified tag

  Arguments:    tag          tagNo. to be cancelled. not 0

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_CancelAlarms( u32 tag );


/*---------------------------------------------------------------------------*
  Name:         OS_CancelAllAlarms

  Description:  cancel all alarms

  Arguments:    None

  Returns:      None.
 *---------------------------------------------------------------------------*/
void OS_CancelAllAlarms( void );


#ifdef __cplusplus
} /* extern "C" */
#endif

/* NITRO_OS_ALARM_H_ */
#endif

