xmutex.h File Reference

#include "xstatus.h"
#include "xmutex_hw.h"
#include "xil_types.h"

Classes
struct	XMutex_Config
struct	XMutex
Defines
#define	XMUTEX_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)
XMutex_Config *	XMutex_LookupConfig (u16 DeviceId)
int	XMutex_SelfTest (XMutex *InstancePtr)

---

Detailed Description

---

Define Documentation

#define XMUTEX_H

---

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.

XMutex_Config* XMutex_LookupConfig

(

u16

DeviceId

)

int XMutex_SelfTest

(

XMutex *

InstancePtr

)

Selftest a particular Mutex hardware core.

Parameters:

InstancePtr

is a pointer to the XMutex instance to be worked on.

Returns:

• XST_SUCCESS if test was successful.
• XST_FAILURE if test was not successful.

Note:

This test is destructive. It will fail if the Mutex is currently being used. This is also a blocking call, if there is another process which has the Mutex, the first _lock will hand the test until the other process releases it.

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.