/****************************************************************************/
/*	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 "kernel.h"

/****************************************************************************/
/*					Local prototypes										*/
/****************************************************************************/

static	void	LockRelease( void *par1, void *par2 );

/****************************************************************************/
/*					Public API functions									*/
/****************************************************************************/

/** @addtogroup bx_lock */
/** @{ */

/**
*	Releases a lock.
*
*	The function can not be called from kernel or interrupt context.
*	The caller must own the lock.
*
*	@param	lock	Pointer to the lock to be released
*
*	@retval	>0				Success.
*	@retval	BX_ERR_OBJECT	The pointer does not point to a lock object.
*	@retval BX_ERR_CONTEXT	The caller is not a user thread
*	@retval	BX_ERR_NOTOWNER	The calling process does not own the lock
*
*	@attention
*		This function can only be called from user context.
*		This function does not suspend the caller but can cause a context
*		switch if a higher priority process is woken up by the call.
*/

int		BX_LockRelease( BX_LOCK *lock )
{
int		cpsr;
BX_PROC	*self;

	if ( lock->pmut.wait.type != BX_TYPE_LOCK ) return( BX_ERR_OBJECT );
	if ( ! ( self = BX_ProcSelf() ) ) return( BX_ERR_CONTEXT );

	cpsr = _bx_IrqDis();

	if ( lock->pmut.proc != self ) {

		// We don't own this lock

		_bx_IrqEnaUsr( cpsr );
		return( BX_ERR_NOTOWNER );
	}

	if ( ! lock->pmut.wait.head && ! lock->pmut.wait.ftab->rem ) {

		// Noone is waiting for the lock and it is not a
		// priority mutating one, so we just let it go.

		lock->pmut.proc = NULL;
		_bx_PmutDel( self, &lock->pmut );
		_bx_IrqRes( cpsr );
	}
	else {

		// We must go through the event queue

		_bx_QueueEvent( cpsr, LockRelease, lock, self );
	}

	return( +1 );
}

/** @} */

/****************************************************************************/
/*					Local functions											*/
/****************************************************************************/

/*
*	Releases a lock
*	~~~~~~~~~~~~~~~
*/

static	void	LockRelease( void *par1, void *par2 )
{
BX_LOCK		*lock = par1;
BX_PROC		*proc = par2;

	if ( lock->pmut.wait.ftab->rem ) {

		// The lock has removal function, call it

		(*lock->pmut.wait.ftab->rem)( lock, proc );
	}
	else {

		// We just dissociate from the lock

		lock->pmut.proc = NULL;
		_bx_PmutDel( proc, &lock->pmut );
	}

	if ( ( proc = lock->pmut.wait.head ) ) {

		// There is at least one process waiting for the lock.
		// Get it now. The lock currently has no owner, thus
		// we don't have to worry about priority issues

		(*lock->pmut.wait.ftab->del)( &lock->pmut.wait, proc );

		// Set the lock's owner to the process

		lock->pmut.proc = proc;

		// If the lock implements the 'add' function, we must add
		// the lock to the process's mutating object list. Otherwise
		// we just add it to the list.

		if ( lock->pmut.wait.ftab->add ) {

			(*lock->pmut.wait.ftab->add)( lock, proc );
		}
		else {

			lock->pmut.proc = proc;
			_bx_PmutAddTail( proc, &lock->pmut );
		}

		// If the waiting process has set up a timeout,
		// we should cancel it now

		if ( proc->timo.stat != TIMER_CANCEL &&
			 proc->timo.stat != TIMER_UNUSED ) {

			proc->timo.stat = TIMER_CANCEL;
			_bx_TimerProcess( &proc->timo, (void *) 1 );
		}

		// Indicate success for the waiting process

		proc->ramt = 1;

		// Wake up the process

		_bx_ProcRestart( proc, NULL );
	}
}

