avsysevent.h

来自「AMLOGIC DPF source code」· C头文件 代码 · 共 156 行

/*******************************************************************
 * 
 *  Copyright C 2005 by Amlogic, Inc. All Rights Reserved.
 *
 *  Description: 
 *
 *  Author: Amlogic Software
 *  Created: 1/17/2006 11:17AM
 *
 *******************************************************************/
#ifndef __AVSYSEVENT_H_
#define __AVSYSEVENT_H_

/** @defgroup OS_API_Sysevent General System Event functions */
/** @ingroup OS_API */
/** @addtogroup OS_API_Sysevent */
/*@{*/

typedef unsigned int AVSysEvent_t;
/**
 * System Event callback type.
 */
typedef void (*SysEventCb_t)(unsigned arg);

typedef struct AVSysEventSubscriber_s EventSubscriber_t;

/**
 * Create an empty system event list so that system event can be registered.
 * @note This function should be executed only once.
 * @return 0    Initialization succeeded.
 * @return -1   Initialization failed.
 */
int AVSysEvent_Init(void);

/**
 * Find an unused event ID for customer usage.
 * @return 0    The registration failed.
 * @return !0   User event ID.
 */
AVSysEvent_t AVSysEvent_Register();

/**
 * Unregister a system event.
 * @param[in]   event    ID of the event.
 */
void AVSysEvent_UnRegister(AVSysEvent_t event);

/**
 * Post an event. If there are any event subscribers(listener) hooked on this event,
 * the subscriber's event wait is finished and the event can be processed by their 
 * pre-defined event handlers by AVSysEvent_Process().
 * @param[in] event    The event handler.
 * @note This function can be called in interrupt.
 */
void AVSysEvent_Post(AVSysEvent_t event);

/**
 * Create a system event subscriber. A subscriber will be associated with some system event
 * by AVSysEventSubscriber_AddEvent(). Once any event that the subscriber listen to is post, 
 * AVSysEvent_Wait() to this subscriber will stop pending and AVSysEvent_Process() 
 * will process the active event by their pre-defined event handlers.
 * @return  The event subscriber/listener handler.
 */
EventSubscriber_t *AVSysEventSubscriber_Create(void);

/**
 * Remove a system event subscriber
 * @param[in] listener the handler of event subscriber.
 */
void AVSysEventSubscriber_Destroy(EventSubscriber_t *listener);

/**
 * Make the subscriber listen on one events.
 * @param[in] listener  Handle of the subscriber.
 * @param[in] event     The ID of the event.
 * @param[in] cb        The event handler as a callback function which will be executed in
 *                      the context of AVSysEvent_Process().
 * @param[in] arg       The argument to the event handlers along with 'cb'.
 */
void AVSysEventSubscriber_AddEvent(EventSubscriber_t *listener, AVSysEvent_t event, SysEventCb_t cb, unsigned arg);

/**
 * Unlink a subscriber with an event.
 * @param[in]   listener The handler of the event subscriber.
 * @param[in]   event The event id.
 */
void AVSysEventSubscriber_RemoveEvent(EventSubscriber_t *listener, AVSysEvent_t event);

/**
 * Clear all events post to the subscriber. Use this function call before AVSysEvent_Wait()
 * to initilize the subscriber if needed.
 * @param[in]   listener The handler of the event subscriber.
 * @param[in]   event The event id.
 */
void AVSysEventSubscriber_ClearEvent(EventSubscriber_t *listener);

/**
 * Check if an event is active to the event subscriber
 * @param[in]   listener The handler of the event subscriber.
 * @param[in]   event The event id.
 * @return  0   The event is active.
 * @retirn -1   The event is not active.
 */
int AVSysEvent_CheckEvent(EventSubscriber_t *listener, AVSysEvent_t event);

/**
 * Process the event loop for the subscribler. If there are any events active and listened by
 * the subscriber, their event handler will be called by this function.
 * @param[in]   listener Handle of the event subscriber.
 */
void AVSysEvent_Process(EventSubscriber_t *listener);

/**
 * This function will block the running thread if there is no listened event posted.
 * When the function returns, then either the waiting is timeout, which means there
 * is no event happen during the specified time, or there are some event happened and
 * the task can call AVSysEvent_Process() to do event processing.
 * @param[in] listened  Handler of the event subscriber.
 * @param[in] timeout   A timeout value in system ticks unit. If 0 is specified, then
 *  The function will not return until there are some events the subscriber listen to
 *  is active.
 * @return  0   The waiting is finished and there are some event happened.
 * @return  1   The waiting is timeout.
 * @return -1   The subscriber's event pending failed.
 * @note
 * Following example code is the typical way to use the system event machnism
 * to make one task be event driven, or do different processing based on different events.
 * \code
 *
 *  AVSysEvent ev1_id;            // event1's id
 *  AVSysEvent ev2_id;            // event2's id
 *  EventSubscriber_t *sub;     // the event listener
 * 
 *  ev1_id = AVSysEvent_Register();
 *  ev1_id = AVSysEvent_Register();
 *  sub = AVSysEventSubscriber_Create();
 *  AVSysEventSubscriber_AddEvent(sub, ev1_id, event_handle1, arg1);
 *  AVSysEventSubscriber_AddEvent(sub, ev2_id, event_handle2, arg2);
 *  while (!end_task) {
 *      // the task is event driven and the event is processed by their handlers
 *      AVSysEvent_Wait(sub, 0);
 *      AVSysEvent_Process(sub);
 *  }
 *  AVSysEventSubscriber_RemoveEvent(sub, ev1_id);
 *  AVSysEventSubscriber_RemoveEvent(sub, ev2_id);
 *  AVSysEventSubscriber_Destroy(sub);
 *  AVSysEvent_UnRegister(ev1_id);
 *  AVSysEvent_UnRegister(ev2_id);
 *      
 * \endcode
 */
int  AVSysEvent_Wait(EventSubscriber_t *listener, INT16U timeout);

/*@}*/
#endif /* __AVSYSEVENT_H_ */