/****************************************************************************/
/*	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"

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

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

/**
*	Initialises a mutual exclusivity lock.
*
*	@param	lock		Pointer to the lock to initialise
*	@param	policy		The process queueing policy of the lock. It must be
*						one of BX_POLICY_FIFO, BX_POLICY_PRIO, BX_POLICY_PPCL,
*						BX_POLICY_PPIN, BX_POLICY_FPCL or BX_POLICY_FPIN.
*	@param	ceilprio	The priority of the lock if it implements
*						priority ceiling. For all other policies
*						this argument is ignored.
*
*	@retval	>0				Success
*	@retval	BX_ERR_PARAM	A lock doesn't support the given policy
*
*	@note
*		If the lock uses priority ceiling or priority inheritance policy,
*		quite a lot of code (and runtime) is needed to maintain the
*		priorities through inheritance chains. Of course, if you do not
*		use such policies, the relevant routines will not be called thus
*		the runtime penalty associated with dynamic priorities will not
*		hit you. The code size is a different issue. The kernel is a library,
*		therefore only what is used will be linked into your code. If you
*		statically initialise all your locks, and none of the uses the
*		above mentioned policies, then the dynamic policy code will not
*		be linked into your application. If, however, you call LockInit(),
*		it can not know at compile time if you will pass it a policy that
*		requires that code or not, therefore it will be linked into your
*		code, even if you will never use it. It is a few KBs, so if you
*		are a bit low on code space, you might be better off using static
*		inits than calling LockInit().
*
*	@attention
*		This function does not suspend the caller.
*		This function should not be called from an ISR or delayed ISR.
*		Note, however, that the function does not check this criteria,
*		to allow initialisation of locks before the kernel is started
*		(which must happen in IRQ context). In addition, during the
*		initialisation interrupts are not disabled, therefore you
*		must make sure that nothing will touch the lock while this
*		function is running.
*/

int		BX_LockInit( BX_LOCK *lock, BX_POLICY policy, unsigned ceilprio )
{
	if ( ceilprio > BX_PRIO_MAX ) ceilprio = BX_PRIO_MAX;

	switch ( policy ) {

		case BX_POLICY_FIFO:

			lock->pmut.wait.ftab = (struct _bx_poli *) &_bx_poli_fifo;
			break;

		case BX_POLICY_PRIO:

			lock->pmut.wait.ftab = (struct _bx_poli *) &_bx_poli_prio;
			break;

		case BX_POLICY_PPCL:

			lock->pmut.wait.ftab = (struct _bx_poli *) &_bx_poli_ppcl;
			break;

		case BX_POLICY_PPIN:

			lock->pmut.wait.ftab = (struct _bx_poli *) &_bx_poli_ppin;
			break;

		case BX_POLICY_FPCL:

			lock->pmut.wait.ftab = (struct _bx_poli *) &_bx_poli_fpcl;
			break;

		case BX_POLICY_FPIN:

			lock->pmut.wait.ftab = (struct _bx_poli *) &_bx_poli_fpin;
			break;

		default:

			lock->pmut.wait.type = 0;
			return( BX_ERR_PARAM );
	}

	lock->pmut.wait.type = BX_TYPE_LOCK;
	lock->pmut.wait.head = NULL;
	lock->pmut.wait.tail = NULL;
	lock->pmut.ceil = ceilprio;
	lock->pmut.next = NULL;
	lock->pmut.prev = NULL;
	lock->pmut.proc = NULL;
	lock->pmut.prio = 0;

	return( +1 );
}

/** @} */

