| mutex Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

Data Structures | Macros | Functions
Overview

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