/****************************************************************************/
/*	Copyright (c) 2009, Bendor Research Pty. Ltd. All rights reserved.		*/
/*	This software is released under the GNU General Public License, version	*/
/*	3, with the exemptions that 1) the header files installed by this 	 	*/
/*	package can be included in closed-source code and 2) the libraries		*/
/*	built by this package can be statically linked into a closed-source 	*/
/*	binary. See the file LICENSE for the details.							*/
/*	This software is provided "AS IS", without any warranty or guarantee.	*/
/*	By using this software you acknowledge that neither Bendor Research nor	*/
/*	any of its personnel or affiliates can be held liable for any damages,	*/
/*	including, but not limited to, loss of business, loss of money, loss of */
/*	life, loss of reputation, arising out of this software being faulty or	*/
/*	not performing as advertised, even if Bendor Research was aware of such	*/
/*	faults in the software. You use this software at your own risk, any and */
/*	all liabilities that arise out of your using this software are strictly	*/
/*	yours.																	*/
/****************************************************************************/

#include "coop.h"

/** @addtogroup coop_sema */
/** @{ */

/**
*	Initialises a semaphore before use.
*
*	@param	sema	Pointer to the semaphore to initialise
*
*	@param	howmany	The initial value of the semaphore
*/

void	BZ_SemaInit( BZ_SEMA *sema, unsigned howmany )
{
	*sema = howmany;
}

/**
*	Get the given number of objects from a semaphore.
*
*	This function takes the requested number of objects from the semaphore.
*	If there are not enough objects, it will suspend the caller until the
*	necessary amount of objects are delivered by one or more BZ_SemaPut()
*	calls.
*
*	@param	sema	Pointer to the semaphore
*
*	@param	howmany	The number of resources to get
*
*	@attention
*		This function must not be called from an interrupt. It you do
*		that, the system will crash.
*/

void	BZ_SemaGet( BZ_SEMA *sema, unsigned howmany )
{
	while ( ! BZ_SemaTry( sema, howmany ) ) BZ_EventWait( BZ_EVENT_SEMA );
}

/**
*	Tries to get the given number of objects from a semaphore.
*
*	The function checks if the given semaphore holds as many objects as
*	requested. If yes, then it takes the given number and returns, reporting
*	success. If the semaphore does not have onogh resources, then the function
*	leaves the semaphore unchanged and returns immediately, reporting failure.
*	This function never suspends the caller and is safe to call from an
*	interrupt routine.
*
*	@param	sema	Pointer to the semaphore
*
*	@param	howmany	The number of resources to get
*
*	@retval	1		Success, the requested amount of resources were taken
*	@retval	0		Failure, the semaphore does not have enough resources
*/

int		BZ_SemaTry( BZ_SEMA *sema, unsigned howmany )
{
int		stat;

	stat = BZ_IrqDisable( 1 );

	if ( *sema >= howmany ) {

		*sema -= howmany;
		BZ_IrqDisable( stat );
		return( 1 );
	}
	else {

		BZ_IrqDisable( stat );
		return( 0 );
	}
}

/**
*	Return resources to a semaphore.
*
*	The function adds resources to a semaphore. The resource count is a 32-bit
*	unsigned number and is <b>not</b> protected against overflow.
*	The function does not suspend the caller and is safe to call from an
*	interrupt routine.
*
*	@param	sema	Pointer to the semaphore
*
*	@param	howmany	The number of resources to put to the semaphore
*/
void	BZ_SemaPut( BZ_SEMA *sema, unsigned howmany )
{
	*sema += howmany;
	_bz_EventPost( BZ_PID_BCAST, BZ_EVENT_SEMA );
}

/** @} */

