mutex
Vitis Drivers API Documentation
 All Data Structures Files Functions Variables Macros Groups Pages
Overview

Data Structures

struct  XMutex_Config
 This typedef contains configuration information for the device. More...
 
struct  XMutex
 The XMutex driver instance data. More...
 

Functions

int XMutex_CfgInitialize (XMutex *InstancePtr, XMutex_Config *ConfigPtr, UINTPTR EffectiveAddress)
 Initializes a specific Mutex instance. More...
 
void XMutex_Lock (XMutex *InstancePtr, u8 MutexNumber)
 Locks a Mutex within a Mutex device. More...
 
int XMutex_Trylock (XMutex *InstancePtr, u8 MutexNumber)
 Tries to lock a Mutex without blocking. More...
 
int XMutex_Unlock (XMutex *InstancePtr, u8 MutexNumber)
 Unlocks a Mutex within a Mutex device. More...
 
int XMutex_IsLocked (XMutex *InstancePtr, u8 MutexNumber)
 Returns whether a Mutex is locked. More...
 
void XMutex_GetStatus (XMutex *InstancePtr, u8 MutexNumber, u32 *Locked, u32 *Owner)
 Gets the lock status and owner of a Mutex. More...
 
int XMutex_GetUser (XMutex *InstancePtr, u8 MutexNumber, u32 *User)
 Reads the USER register of a Mutex. More...
 
int XMutex_SetUser (XMutex *InstancePtr, u8 MutexNumber, u32 User)
 Writes the USER register of a Mutex. More...
 
XMutex_Config * XMutex_LookupConfig (UINTPTR BaseAddress)
 Looks up Mutex configuration by device ID or base address. More...
 
int XMutex_SelfTest (XMutex *InstancePtr)
 Runs a destructive self-test on a Mutex core. More...
 

Function Documentation

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

Initializes a specific Mutex instance.

Initializes a specific Mutex instance/driver.

Parameters
[out]InstancePtrPointer to the XMutex instance to be worked on.
[in]ConfigPtrDevice configuration structure containing required HW build data.
[in]EffectiveAddressPhysical 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.

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 lock status and owner of a Mutex.

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

Parameters
[in]InstancePtrPointer to the XMutex instance to be worked on.
[in]MutexNumberSpecific 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).
[out]LockedPointer 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.
[out]OwnerPointer 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.

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 
)

Reads the USER register of a Mutex.

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

Parameters
[in]InstancePtrPointer to the XMutex instance to be worked on.
[in]MutexNumberSpecific 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).
[out]UserPointer 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.

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

int XMutex_IsLocked ( XMutex *  InstancePtr,
u8  MutexNumber 
)

Returns whether a Mutex is locked.

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

Parameters
[in]InstancePtrPointer to the XMutex instance to be worked on.
[in]MutexNumberSpecific 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

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 Mutex within a Mutex device.

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

Parameters
[in]InstancePtrPointer to the XMutex instance to be worked on.
[in]MutexNumberSpecific 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).
Note
  • XMutex_Lock blocks until the caller gets the lock.
  • Use XMutex_Trylock for a non-blocking call. The caller 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().

XMutex_Config* XMutex_LookupConfig ( UINTPTR  BaseAddress)

Looks up Mutex configuration by device ID or base address.

Looks up the device configuration based on the unique device ID/BaseAddress. The XMutex_ConfigTable[] contains the configuration info for each device in the system.

Parameters
[in]BaseAddressContains the base address of the device.
Returns
A pointer to the configuration found or NULL if the specified device ID/BaseAddress was not found. See xmutex.h for the definition of XMutex_Config.
Note
In XSCT/classic flow, DeviceId is used to look up the device configuration.

References XMutex_Config::Name.

Referenced by MutexExample().

int XMutex_SelfTest ( XMutex *  InstancePtr)

Runs a destructive self-test on a Mutex core.

Selftest a particular Mutex hardware core.

Parameters
[in]InstancePtrPointer 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 fails 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 hangs 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 
)

Writes the USER register of a Mutex.

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

Parameters
[in]InstancePtrPointer to the XMutex instance to be worked on.
[in]MutexNumberSpecific 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).
[in]UserValue 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.

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

int XMutex_Trylock ( XMutex *  InstancePtr,
u8  MutexNumber 
)

Tries to lock a Mutex without blocking.

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

Parameters
[in]InstancePtrPointer to the XMutex instance to be worked on.
[in]MutexNumberSpecific 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 a non-blocking call. The caller gets the lock if it is available. Otherwise, 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 Mutex within a Mutex device.

Unlocks a particular Mutex lock within a Mutex device.

Parameters
[in]InstancePtrPointer to the XMutex instance to be worked on.
[in]MutexNumberSpecific 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 unlocking was successful.
  • XST_FAILURE if the Mutex was locked by process with different ID.

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().