UTS6710/aps/include/gsl/gl_flag.h

/*! \addtogroup GSL
 * @{
 */
/*!
*
* @file		gl_flag.h
*
* @brief	This file specifies the Flag APIs
*
* @note		Copyright (c) 2009 Sunplus Technology Co., Ltd. \n
*			All rights reserved.
*
* @author
*
******************************************************************************/
#ifndef __GSL_FLAG_H__
#define __GSL_FLAG_H__

/*!
 * @defgroup GL_Flag GSL Flag APIs
 * @brief GSL Flag APIs
 * @{
*/
#include "gl_types.h"

/******************************************************************************/
/*!
 * @brief	Create and initialize a flag object for use.
 *
 * @param	szName string identifier for the interrupt. Up to 16 characters.
 * @param	pFlagId Flag object identifier returned by the API (on success)
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_FlagCreate(char *szName, GL_Flag_t * pFlagId);

/******************************************************************************/
/*!
 * @brief	Used to delete a Flag. Regarding tasks waiting on a deleted Flag, the behavior depends on the underlying OS; the GSL does not guarantee a default behavior (hence, applications should avoid this scenario). Typically, an error is returned to the waiting tasks.
 *
 * @param	pFlagId Flag object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_FlagDelete(GL_Flag_t pFlagId);

/******************************************************************************/
/*!
 * @brief	This sets bits (conditions) to true in a flag. Any bit in "value" that is set to true (1) will set the equivalent bit in the flag. This may wake threads waiting on this flag as a result.
 *
 * @param	pFlagId Flag object identifier
 * @param	value_i Indefined which bit of flag should be set
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_FlagSetbits(GL_Flag_t pFlagId,GL_UINT32 value_i);

/******************************************************************************/
/*!
 * @brief	This causes the calling thread to wait on a set of bits (conditions) to be set in a given flag. The "mode" indicates how the pattern will be interpreted: About the wait mode, there's three selection: \n
 *	1) GL_FLAG_WAITMODE_AND :return match if all conditions in the pattern are set in the flag.\n
 *	2) GL_FLAG_WAITMODE_OR :return match if any of the conditions in the pattern are set in the flag.\n
 *	3) GL_FLAG_WAITMODE_CLR :automatically clear the conditions that caused the calling
 *	thread to return a match, IF there was a match.\n
 *  @a GL_FLAG_WAITMODE_CLR can be combined with other two, to clear the bit wait for.\n
 *
 * @param	pFlagId Flag object identifier
 * @param	value_i Pattern to wait for
 * @param	mode_i Wait mode
 * @param	sdTimeout timeout time
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Do not use it in ISR.
 *******************************************************************************/
GL_UINT32 GL_FlagWait(GL_Flag_t pFlagId, GL_UINT32 value_i, GL_UINT8 mode_i,GL_INT32 sdTimeout);

/*!
 * @enum GL_FLAG_WAITMODE
*/
#define CYG_FLAG_WAITMODE_AND 	0	 /* all bits must be set */
#define CYG_FLAG_WAITMODE_OR  	2	 /* any bit must be set  */
#define CYG_FLAG_WAITMODE_CLR 	1	/* clear when satisfied */

enum GL_FLAG_WAITMODE
{
	GL_FLAG_WAITMODE_AND	= 0,	/**< All events should happen to trigger flag */
	GL_FLAG_WAITMODE_CLR	= 1,	/**< Clear the flag bits when triggering */
	GL_FLAG_WAITMODE_OR		= 2	/**< One event can trigger the flag */
};

/******************************************************************************/
/*!
 * @brief	This returns the current bits (conditions) that are set in a given flag.
 *
 * @param	pFlagId Flag object identifier
 * @param	value_o container of the value peek from GL_Flag_t
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_FlagPeek(GL_Flag_t pFlagId, GL_UINT32 * value_o);

#ifdef GL_OBJECT_LIST_FLAG
/******************************************************************************/
/*!
 * @brief	To know if it is a duplicated name in current gsl flag objects
 *
 * @param	name a name
 *
 * @return	@a 0 if not duplicated. @a 1 if duplicated.
 *
 * @note	It blocks scheduler while searching.
 *******************************************************************************/
UINT8 GL_FlagIsDupName(const char *name);

/******************************************************************************/
/**
 * @brief	Used to dump the list of existing flag objects. This helps associate the flag name with the flag object address. Depending on OS support, the list may also display a snapshot of the flag state.The function is used for direct invocation from the IDE shell (if available).The macro is used for invocation from source code. The macro automatically gets compiled out for non-debug builds.
 *
 * @param	wChannel the pre-defined unique ID denoting the output channel to which  messages will be printed
 *
 * @return	void
 *
 * @note	Available only in debug builds. Cannot be used from ISR/DSR.
 *******************************************************************************/
void GL_FlagDumpList(UINT16 wChannel);
#else
#define GL_FLAG_DUMP_LIST(wChannel) GL_FlagDumpList(wChannel)
#endif

/*! @} end of defgroup GL_Flag */
#endif // __GL_FLAG_H__

/*! @} end of addtogroup GSL */