/*---------------------------------------------------------------------------*
  Project:  OS Alarm API
  File:     OSAlarm.h

  Copyright 1998-2011 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.

 *---------------------------------------------------------------------------*/

#ifndef __OSALARM_H__
#define __OSALARM_H__

#include <types.h>
#include <cafe/os/OSContext.h>
#include <cafe/os/OSEvent.h>
#include <cafe/os/OSThread.h>

#ifdef __cplusplus
extern "C" {
#endif

typedef struct OSAlarmQueue OSAlarmQueue;
typedef unsigned long OSAlarmHandle;
typedef unsigned long OSAlarmState;
typedef void (*OSAlarmHandler)(OSAlarm* alarm, OSContext* context);

enum
{
    OS_ALARM_BLOCK,
    OS_ALARM_NOBLOCK
};

#define OSALARMQUEUE_TXT_TAG 0x614C6d51  // 'aLmQ' 0x614C6D51

struct OSAlarmQueue
{
    u32      txtTag;                // 'aLmQ' 0x614C6D51
    char *   name;                  // debug name or NULL
    u32      os_reserved1;
         
    OSThreadQueue queue;
    OSAlarm* head;
    OSAlarm* tail;
};

#define OSALARM_TXT_TAG 0x614C724D

struct OSAlarm
{
    u32             txtTag;         // 'aLrM' 0x614C724D
    char *          name;           // debug name or NULL
    u32             os_reserved1;

    OSAlarmHandler  handler;
    u32             tag;
    OSTime          nextFire;

    OSAlarm*        prev;
    OSAlarm*        next;

    // Periodic alarm
    OSTime          period;
    OSTime          tbrStart;

    // User data
    void*           userData;

    // Alarm state: idle or running or before callback
    OSAlarmState    state;

    OSThreadQueue   waitQueue;

    OSAlarmQueue*   alarmQueue;
    // Context of interrupted thread
    OSContext*      context;
};

void OSCreateAlarm           ( OSAlarm* alarm );
void OSCreateAlarmEx         ( OSAlarm* alarm, char * name );

BOOL OSSetAlarm              ( OSAlarm*       alarm, 
                               OSTime         tick, 
                               OSAlarmHandler handler);

BOOL OSSetPeriodicAlarm      ( OSAlarm*       alarm, 
                               OSTime         start, 
                               OSTime         period,
                               OSAlarmHandler handler);

void  OSSetAlarmTag          ( OSAlarm* alarm, u32 tag );
void  OSSetAlarmUserData     ( OSAlarm* alarm, void* data );
void* OSGetAlarmUserData     ( const OSAlarm* alarm );

BOOL OSCancelAlarm           ( OSAlarm* alarm );
void OSCancelAlarms          ( u32 tag );
BOOL OSWaitAlarm             ( OSAlarm* alarm );

#ifdef __cplusplus
}
#endif

#endif  // __OSALARM_H__