Data Structures
struct	XMutex_Config
	This typedef contains configuration information for the device. More...

struct	XMutex
	The XMutex driver instance data. More...

Macros
#define	XMutex_ReadReg(BaseAddress, MutexNumber, RegOffset) Xil_In32((BaseAddress) + XMutex_Offset(MutexNumber) + (RegOffset))
	Read one of the Mutex registers. More...

#define	XMutex_WriteReg(BaseAddress, MutexNumber, RegOffset, ValueToWrite)
	Write a specified value to a register of a Mutex. More...

Functions
int	XMutex_CfgInitialize (XMutex InstancePtr, XMutex_Config ConfigPtr, UINTPTR EffectiveAddress)
	Initializes a specific Mutex instance/driver. More...

void	XMutex_Lock (XMutex *InstancePtr, u8 MutexNumber)
	Locks a particular Mutex lock within a Mutex device. More...

int	XMutex_Trylock (XMutex *InstancePtr, u8 MutexNumber)
	Locks a particular Mutex lock within a Mutex device. More...

int	XMutex_Unlock (XMutex *InstancePtr, u8 MutexNumber)
	Unlocks a particular Mutex lock within a Mutex device. More...

int	XMutex_IsLocked (XMutex *InstancePtr, u8 MutexNumber)
	Gets the current lock state of a Mutex lock within a Mutex device. More...

void	XMutex_GetStatus (XMutex InstancePtr, u8 MutexNumber, u32 Locked, u32 *Owner)
	Gets the current status of a Mutex lock within a Mutex device. More...

int	XMutex_GetUser (XMutex InstancePtr, u8 MutexNumber, u32 User)
	Gets the USER register of a Mutex lock within a Mutex device. More...

int	XMutex_SetUser (XMutex *InstancePtr, u8 MutexNumber, u32 User)
	Sets the USER register of a Mutex lock within a Mutex device. More...

int	XMutex_SelfTest (XMutex *InstancePtr)
	Selftest a particular Mutex hardware core. More...

Register Offset Definitions
Register offsets within a Mutex, there are multiple Mutexes within a single device
#define	XMU_MUTEX_REG_OFFSET 0
	Mutex register. More...

#define	XMU_USER_REG_OFFSET 4
	User register. More...

Mutex Register Bit Definitions
#define	LOCKED_BIT 0x00000001
	This is the Lock bit. More...

#define	OWNER_MASK 0x000001FE
	This is CPU_ID Mask. More...

#define	OWNER_SHIFT 0x00000001
	This is CPU_ID Shift. More...

Macro Definition Documentation

#define LOCKED_BIT 0x00000001

This is the Lock bit.

Set to 1 indicates that the lock is currently owned by the processor ID specified by the CPU_ID (OWNER_MASK) in this register. Set to 0 indicates that the lock is free.

Referenced by XMutex_GetStatus(), XMutex_IsLocked(), XMutex_Lock(), XMutex_SelfTest(), and XMutex_Trylock().

#define OWNER_MASK 0x000001FE

This is CPU_ID Mask.

CPU_ID indicates the ID the processor holding the lock.

Referenced by XMutex_GetStatus(), and XMutex_Unlock().

#define OWNER_SHIFT 0x00000001

This is CPU_ID Shift.

Referenced by XMutex_GetStatus(), XMutex_Lock(), XMutex_Trylock(), and XMutex_Unlock().

#define XMU_MUTEX_REG_OFFSET 0

Mutex register.

Referenced by XMutex_GetStatus(), XMutex_IsLocked(), XMutex_Lock(), XMutex_Trylock(), and XMutex_Unlock().

#define XMU_USER_REG_OFFSET 4

User register.

Referenced by XMutex_GetUser(), and XMutex_SetUser().

#define XMutex_ReadReg	(	BaseAddress,
		MutexNumber,
		RegOffset
	)	Xil_In32((BaseAddress) + XMutex_Offset(MutexNumber) + (RegOffset))

Read one of the Mutex registers.

Parameters

BaseAddress	contains the base address of the Mutex device.
MutexNumber	contains the specific Mutex within the device, a zero based number, 0 - (NumMutexConfigured in HW - 1).
RegOffset	contains the offset from the 1st register of the Mutex to select the specific register of the Mutex.

Returns: The 32 bit value read from the register.

Note: C-style signature: u32 XMutex_ReadReg(u32 BaseAddress, u8 MutexNumber, unsigned RegOffset)

Referenced by XMutex_GetStatus(), XMutex_GetUser(), XMutex_IsLocked(), XMutex_Lock(), XMutex_Trylock(), and XMutex_Unlock().

#define XMutex_WriteReg	(	BaseAddress,
		MutexNumber,
		RegOffset,
		ValueToWrite
	)

Value:

Xil_Out32(((BaseAddress) + XMutex_Offset(MutexNumber) + \

(RegOffset)), (ValueToWrite))

Write a specified value to a register of a Mutex.

Parameters

BaseAddress	is the base address of the Mutex device.
MutexNumber	is the specific Mutex within the device, a zero based number, 0 - (NumMutexConfigured in HW - 1).
RegOffset	contain the offset from the 1st register of the Mutex to select the specific register of the Mutex.
ValueToWrite	is the 32 bit value to be written to the register.

Returns: C-style signature: void XMutex_WriteReg(u32 BaseAddress, u8 MutexNumber, unsigned RegOffset, u32 ValueToWrite)

Referenced by XMutex_Lock(), XMutex_SetUser(), XMutex_Trylock(), and XMutex_Unlock().

Function Documentation

int XMutex_CfgInitialize	(	XMutex *	InstancePtr,
		XMutex_Config *	ConfigPtr,
		UINTPTR	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.

References XMutex_Config::BaseAddress, XMutex::Config, XMutex::IsReady, XMutex_Config::NumMutex, and XMutex_Unlock().

Referenced by MutexExample().

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.

References XMutex_Config::BaseAddress, XMutex::Config, LOCKED_BIT, OWNER_MASK, OWNER_SHIFT, XMU_MUTEX_REG_OFFSET, and XMutex_ReadReg.

Referenced by XMutex_SelfTest().

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.

References XMutex_Config::BaseAddress, XMutex::Config, XMutex_Config::UserReg, XMU_USER_REG_OFFSET, and XMutex_ReadReg.

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.

References XMutex_Config::BaseAddress, XMutex::Config, LOCKED_BIT, XMU_MUTEX_REG_OFFSET, and XMutex_ReadReg.

Referenced by XMutex_SelfTest().

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.

References XMutex_Config::BaseAddress, XMutex::Config, LOCKED_BIT, OWNER_SHIFT, XMU_MUTEX_REG_OFFSET, XMutex_ReadReg, and XMutex_WriteReg.

Referenced by MutexExample(), and XMutex_SelfTest().

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.

References XMutex::Config, LOCKED_BIT, XMutex_Config::NumMutex, XMutex_GetStatus(), XMutex_IsLocked(), XMutex_Lock(), and XMutex_Unlock().

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.

References XMutex_Config::BaseAddress, XMutex::Config, XMutex_Config::UserReg, XMU_USER_REG_OFFSET, and XMutex_WriteReg.

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.

References XMutex_Config::BaseAddress, XMutex::Config, LOCKED_BIT, OWNER_SHIFT, XMU_MUTEX_REG_OFFSET, XMutex_ReadReg, and XMutex_WriteReg.

Referenced by MutexExample().

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.

References XMutex_Config::BaseAddress, XMutex::Config, OWNER_MASK, OWNER_SHIFT, XMU_MUTEX_REG_OFFSET, XMutex_ReadReg, and XMutex_WriteReg.

Referenced by MutexExample(), XMutex_CfgInitialize(), and XMutex_SelfTest().

Data Structures

Macros

Functions

Register Offset Definitions

Mutex Register Bit Definitions

Macro Definition Documentation

Function Documentation