xmutex.c File Reference

#include <string.h>
#include "xmutex.h"
#include "xparameters.h"
#include "xil_types.h"
#include "xil_assert.h"

Functions
int	XMutex_CfgInitialize (XMutex *InstancePtr, XMutex_Config *ConfigPtr, u32 EffectiveAddress)
void	XMutex_Lock (XMutex *InstancePtr, u8 MutexNumber)
int	XMutex_Trylock (XMutex *InstancePtr, u8 MutexNumber)
int	XMutex_Unlock (XMutex *InstancePtr, u8 MutexNumber)
int	XMutex_IsLocked (XMutex *InstancePtr, u8 MutexNumber)
void	XMutex_GetStatus (XMutex *InstancePtr, u8 MutexNumber, u32 *Locked, u32 *Owner)
int	XMutex_GetUser (XMutex *InstancePtr, u8 MutexNumber, u32 *User)
int	XMutex_SetUser (XMutex *InstancePtr, u8 MutexNumber, u32 User)

---

Detailed Description

Contains required functions for the XMutex driver.

 MODIFICATION HISTORY:

 Ver   Who  Date     Changes
 ----- ---- -------- -----------------------------------------------
 1.00a va            First release
 1.00b ecm  06/01/07 Cleanup, new coding standard, check into XCS
 2.00a hm   04/14/09 Fixed CR 466322, removed extra definitions
			Also fixed canonical definitions treating an interface
			as an device instance.
 3.00a hbm  10/15/09 Migrated to HAL phase 1 to use xil_io, xil_types,
			and xil_assert.
 4.00a bss  03/05/14 Modified XMutex_CfgInitialize to fix CR# 770096
 

---

Function Documentation

int XMutex_CfgInitialize	(	XMutex *	InstancePtr,
		XMutex_Config *	ConfigPtr,
		u32	EffectiveAddress
	)

Initializes a specific Mutex instance/driver.

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	ConfigPtr	is the device configuration structure containing required HW build data.
	EffectiveAddress	is the Physical address of the hardware in a Virtual Memory operating system environment. It is the Base Address in a stand alone environment.

Returns:

• XST_SUCCESS if initialization was successful

Note:

None.

void XMutex_GetStatus	(	XMutex *	InstancePtr,
		u8	MutexNumber,
		u32 *	Locked,
		u32 *	Owner
	)

Gets the current status of a Mutex lock within a Mutex device.

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	MutexNumber	is the specific Mutex lock within the device to operate on. Each device may contain multiple Mutex locks. The Mutex number is a zero based number with a range of 0 - (InstancePtr->Config.NumMutex - 1).
	Locked	is a pointer where the current lock status is stored. Sets memory pointed to by 'Locked' to 1 if the Mutex is locked and 0 if it is unlocked.
	Owner	is a pointer where the current owner status is stored. . If the Mutex is locked, the memory pointed to by 'Owner' is updated to reflect the CPU ID that has currently locked this Mutex.

Returns:

None.

Note:

None.

int XMutex_GetUser	(	XMutex *	InstancePtr,
		u8	MutexNumber,
		u32 *	User
	)

Gets the USER register of a Mutex lock within a Mutex device.

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	MutexNumber	is the specific Mutex lock within the device to operate on. Each device may contain multiple Mutex locks. The Mutex number is a zero based number with a range of 0 - (InstancePtr->Config.NumMutex - 1).
	User	is a pointer to an u32 where the current user register value is stored by this function.

Returns:

• XST_SUCCESS if successful. Memory pointed to by User is updated to reflect the contents of the user register.
• XST_NO_FEATURE if the Mutex was not configured with a USER register.

Note:

None.

int XMutex_IsLocked	(	XMutex *	InstancePtr,
		u8	MutexNumber
	)

Gets the current lock state of a Mutex lock within a Mutex device.

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	MutexNumber	is the specific Mutex lock within the device to operate on. Each device may contain multiple Mutex locks. The Mutex number is a zero based number with a range of 0 - (InstancePtr->Config.NumMutex - 1).

Returns:

• TRUE if locked
• FALSE if unlocked

Note:

None.

void XMutex_Lock	(	XMutex *	InstancePtr,
		u8	MutexNumber
	)

Locks a particular Mutex lock within a Mutex device. Call blocks till the Mutex is locked.

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	MutexNumber	is the specific Mutex lock within the device to operate on. Each device may contain multiple Mutex locks. The Mutex number is a zero based number with a range of 0 - (InstancePtr->Config.NumMutex - 1).

Returns:

None

Note:

• XMutex_Trylock is a blocking call. This call blocks until the user gets the lock.
• Use XMutex_Trylock for a Non-Blocking call. The user gets the lock if it is available and returns immediately if the lock is not available.

int XMutex_SetUser	(	XMutex *	InstancePtr,
		u8	MutexNumber,
		u32	User
	)

Sets the USER register of a Mutex lock within a Mutex device.

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	MutexNumber	is the specific Mutex lock within the device to operate on. Each device may contain multiple Mutex locks. The Mutex number is a zero based number with a range of 0 - (InstancePtr->Config.NumMutex - 1).
	User	is the value to update the USER register with.

Returns:

• XST_SUCCESS if the USER register is written with the given value .
• XST_NO_FEATURE if the Mutex was not configured with a USER register.

Note:

None.

int XMutex_Trylock	(	XMutex *	InstancePtr,
		u8	MutexNumber
	)

Locks a particular Mutex lock within a Mutex device. Call returns immediately if the Mutex is already locked (This is Non-Blocking call).

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	MutexNumber	is the specific Mutex lock within the device to operate on. Each device may contain multiple Mutex locks. The Mutex number is a zero based number with a range of 0 - (InstancePtr->Config.NumMutex - 1).

Returns:

• XST_SUCCESS if locking was successful.
• XST_DEVICE_BUSY if the Mutex was found to be already locked

Note:

• This is Non-Blocking call, the user gets the lock if it is available else XST_DEVICE_BUSY is returned.
• Use XMutex_Lock if you need to block until a lock is obtained.

int XMutex_Unlock	(	XMutex *	InstancePtr,
		u8	MutexNumber
	)

Unlocks a particular Mutex lock within a Mutex device.

Parameters:

	InstancePtr	is a pointer to the XMutex instance to be worked on.
	MutexNumber	is the specific Mutex lock within the device to operate on. Each device may contain multiple Mutex locks. The Mutex number is a zero based number with a range of 0 - (InstancePtr->Config.NumMutex - 1).

Returns:

• XST_SUCCESS if locking was successful.
• XST_FAILURE if the Mutex was locked by process with different ID.

Note:

None.