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

  Copyright 2008 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.

  $Date::            $
  $Rev$
  $Author$
 *---------------------------------------------------------------------------*/
#ifndef BROM_OS_ALARM_H_
#define BROM_OS_ALARM_H_

#include <brom/misc.h>
#include <brom/types.h>
#include <brom/os/common/thread.h>
#include <brom/os/common/tick.h>

#ifdef __cplusplus
extern "C" {
#endif

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


//---- struct of Alarm
//typedef struct OSiAlarm OSAlarm;   // this is decleared in thread.h
struct OSiAlarm
{
    OSAlarmHandler handler;
    void   *arg;

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

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

//---- Alarm resource
typedef struct OSAlarmResource
{
	int num;
}
OSAlarmResource;

//--------------------------------------------------------------------------------
/*---------------------------------------------------------------------------*
  Name:         osInitAlarm

  Description:  initalize alarm system

  Arguments:    None.

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


/*---------------------------------------------------------------------------*
  Name:         osEndAlarm

  Description:  end alarm system

  Arguments:    None

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


/*---------------------------------------------------------------------------*
  Name:         osIsAlarmAvailable

  Description:  check alarm system is available

  Arguments:    None

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


/*---------------------------------------------------------------------------*
  Name:         osCreateAlarm

  Description:  Create alarm

  Arguments:    alarm       pointer to alarm to be initialized

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


/*---------------------------------------------------------------------------*
  Name:         osSetAlarm

  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    osSetAlarm(OSAlarm *alarm, OSTick tick, OSAlarmHandler handler, void *arg);


/*---------------------------------------------------------------------------*
  Name:         osSetPeriodicAlarm

  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    osSetPeriodicAlarm(OSAlarm *alarm, OSTick start, OSTick period, OSAlarmHandler handler,
                            void *arg);


/*---------------------------------------------------------------------------*
  Name:         osSetAlarmTag

  Description:  set tag which is used osCancelAlarms

  Arguments:    alarm        alarm to be set tag
                tag          tagNo

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


/*---------------------------------------------------------------------------*
  Name:         osCancelAlarm

  Description:  Cancel alarm

  Arguments:    alarm       pointer to alarm to be canceled

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


/*---------------------------------------------------------------------------*
  Name:         osCancelAlarms

  Description:  cancel alarms which have specified tag

  Arguments:    tag          tagNo. to be cancelled. not 0

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


/*---------------------------------------------------------------------------*
  Name:         osCancelAllAlarms

  Description:  cancel all alarms

  Arguments:    None

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


//================================================================================
//        FOR DEBUG
//================================================================================
/*---------------------------------------------------------------------------*
  Name:         osGetNumberOfAlarm

  Description:  get number of alarm

  Arguments:    None

  Returns:      number of alarm
 *---------------------------------------------------------------------------*/
int     osGetNumberOfAlarm(void);

/*---------------------------------------------------------------------------*
  Name:         osGetAlarmResource

  Description:  store resources of alarm to specified pointer

  Arguments:    resource       pointer to store alarm resources

  Returns:      TRUE  ... success (always return this now)
                FALSE ... fail
 *---------------------------------------------------------------------------*/
BOOL    osGetAlarmResource(OSAlarmResource *resource);


//================================================================================
//  The following definitions or declarations are for internal use.
//  Don't call these from use program.
struct OSiAlarmQueue
{
    OSAlarm *head;
    OSAlarm *tail;
};
struct OSiAlarmQueue *i_osGetAlarmQueue(void);


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

/* BROM_OS_ALARM_H_ */
#endif