| mbox Vitis Drivers API Documentation

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

Data Structures | Macros | Functions
Overview

## Data Structures
struct | XMbox_Config
| This typedef contains configuration information for the device. More...
struct | XMbox
| The XMbox driver instance data. More...

## Macros
#define | XMbox_ReadReg(BaseAddress, RegOffset) Xil_In32((BaseAddress) + (RegOffset))
| Read one of the mbox registers. More...
#define | XMbox_WriteReg(BaseAddress, RegOffset, ValueToWrite) Xil_Out32(((BaseAddress) + (RegOffset)), (ValueToWrite))
| Write a specified value to a register of a mbox. More...
#define | XMbox_WriteMBox(BaseAddress, ValueToWrite) XMbox_WriteReg (BaseAddress, XMB_WRITE_REG_OFFSET, ValueToWrite)
| Write the mbox write register. More...
#define | XMbox_ReadMBox(BaseAddress) XMbox_ReadReg (BaseAddress, XMB_READ_REG_OFFSET)
| Read the mbox read FIFO. More...
#define | XMbox_IsEmptyHw(BaseAddress) ((XMbox_ReadReg (BaseAddress, XMB_STATUS_REG_OFFSET) & XMB_STATUS_FIFO_EMPTY))
| Checks if the Read FIFO is Empty. More...
#define | XMbox_IsFullHw(BaseAddress) ((XMbox_ReadReg (BaseAddress, XMB_STATUS_REG_OFFSET) & XMB_STATUS_FIFO_FULL))
| Checks if there is room in the Write FIFO. More...

## Functions
int | XMbox_CfgInitialize (XMbox *InstancePtr, XMbox_Config *ConfigPtr, UINTPTR EffectiveAddress)
| Initializes a specific mailbox. More...
int | XMbox_Read (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes, u32 *BytesRecvdPtr)
| Reads requested bytes from the mailbox referenced by InstancePtr,into the buffer pointed to by the provided pointer. More...
void | XMbox_ReadBlocking (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes)
| Reads requested bytes from the mailbox referenced by InstancePtr,into the buffer pointed to by the provided pointer. More...
int | XMbox_Write (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes, u32 *BytesSentPtr)
| Writes the requested bytes from the buffer pointed to by the provided pointer into the mailbox referenced by InstancePtr.The number of bytes must be a multiple of 4 (bytes). More...
void | XMbox_WriteBlocking (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes)
| Writes the requested bytes from the buffer pointed to by the provided pointer into the mailbox referenced by InstancePtr. More...
u32 | XMbox_IsEmpty (XMbox *InstancePtr)
| Checks to see if there is data available to be read. More...
u32 | XMbox_IsFull (XMbox *InstancePtr)
| Checks to see if there is room in the write FIFO. More...
int | XMbox_Flush (XMbox *InstancePtr)
| Resets the mailbox FIFOs by emptying the READ FIFO and making sure the Error Status is zero. More...
void | XMbox_ResetFifos (XMbox *InstancePtr)
| Resets the mailbox FIFOs by clearing the READ and WRITE FIFOs using the hardware control register for memory mapped IO. More...
void | XMbox_SetInterruptEnable (XMbox *InstancePtr, u32 Mask)
| Sets the interrupt enable register for this mailbox. More...
u32 | XMbox_GetInterruptEnable (XMbox *InstancePtr)
| Retrieves the interrupt enable for the mailbox. More...
u32 | XMbox_GetInterruptStatus (XMbox *InstancePtr)
| Retrieve the interrupt status for the mailbox. More...
void | XMbox_ClearInterrupt (XMbox *InstancePtr, u32 Mask)
| Clears pending interrupts with the provided mask. More...
void | XMbox_SetSendThreshold (XMbox *InstancePtr, u32 Value)
| Sets the Send Interrupt Threshold. More...
void | XMbox_SetReceiveThreshold (XMbox *InstancePtr, u32 Value)
| Set the Receive Interrupt Threshold. More...
u32 | XMbox_GetStatus (XMbox *InstancePtr)
| Returns Status register contents. More...

## Register Offset Definitions
Register offsets within a mbox.
#define | XMB_WRITE_REG_OFFSET 0x00
| Mbox write register. More...
#define | XMB_READ_REG_OFFSET 0x08
| Mbox read register. More...
#define | XMB_STATUS_REG_OFFSET 0x10
| Mbox status reg. More...
#define | XMB_ERROR_REG_OFFSET 0x14
| Mbox Error reg. More...
#define | XMB_SIT_REG_OFFSET 0x18
| Mbox send interrupt threshold register. More...
#define | XMB_RIT_REG_OFFSET 0x1C
| Mbox receive interrupt threshold register. More...
#define | XMB_IS_REG_OFFSET 0x20
| Mbox interrupt status register. More...
#define | XMB_IE_REG_OFFSET 0x24
| Mbox interrupt enable register. More...
#define | XMB_IP_REG_OFFSET 0x28
| Mbox interrupt pending register. More...
#define | XMB_CTRL_REG_OFFSET 0x2C
| Mbox control register. More...

## Status register bit definitions
These status bits are used to poll the FIFOs
#define | XMB_STATUS_FIFO_EMPTY 0x00000001
| Receive FIFO is Empty. More...
#define | XMB_STATUS_FIFO_FULL 0x00000002
| Send FIFO is Full. More...
#define | XMB_STATUS_STA 0x00000004
| Send FIFO Threshold Status. More...
#define | XMB_STATUS_RTA 0x00000008
| Receive FIFO Threshold Status. More...

## Interrupt Registers(s) bits definitions.
The IS, IE, and IP registers all have the same bit definition.
#define | XMB_IX_STA 0x01
| Send Threshold Active, when the number of Send FIFO entries is less than and equal to Send Interrupt Threshold. More...
#define | XMB_IX_RTA 0x02
| Receive Threshold Active, when the number of Receive FIFO entries is greater than Receive Interrupt Threshold. More...
#define | XMB_IX_ERR 0x04
| Mailbox Error, when read on empty or write on full. More...

## Error bits definition.
#define | XMB_ERROR_FIFO_EMPTY 0x00000001
| Receive FIFO is Empty. More...
#define | XMB_ERROR_FIFO_FULL 0x00000002
| Send FIFO is Full. More...

## Control register bits definition.
#define | XMB_CTRL_RESET_SEND_FIFO 0x00000001
| Clear Send FIFO. More...
#define | XMB_CTRL_RESET_RECV_FIFO 0x00000002
| Clear Receive FIFO. More...

## Macro Definition Documentation

#define XMB_CTRL_REG_OFFSET 0x2C

Mbox control register.

Referenced by XMbox_ResetFifos().

#define XMB_CTRL_RESET_RECV_FIFO 0x00000002

Clear Receive FIFO.

Referenced by XMbox_ResetFifos().

#define XMB_CTRL_RESET_SEND_FIFO 0x00000001

Clear Send FIFO.

Referenced by XMbox_ResetFifos().

#define XMB_ERROR_FIFO_EMPTY 0x00000001

Receive FIFO is Empty.

#define XMB_ERROR_FIFO_FULL 0x00000002

Send FIFO is Full.

#define XMB_ERROR_REG_OFFSET 0x14

Mbox Error reg.

#define XMB_IE_REG_OFFSET 0x24

Mbox interrupt enable register.

Referenced by XMbox_GetInterruptEnable(), and XMbox_SetInterruptEnable().

#define XMB_IP_REG_OFFSET 0x28

Mbox interrupt pending register.

#define XMB_IS_REG_OFFSET 0x20

Mbox interrupt status register.

Referenced by XMbox_ClearInterrupt(), and XMbox_GetInterruptStatus().

#define XMB_IX_ERR 0x04

Mailbox Error, when read on empty or write on full.

#define XMB_IX_RTA 0x02

Receive Threshold Active, when the number of Receive FIFO entries is greater than Receive Interrupt Threshold.

#define XMB_IX_STA 0x01

Send Threshold Active, when the number of Send FIFO entries is less than and equal to Send Interrupt Threshold.

#define XMB_READ_REG_OFFSET 0x08

Mbox read register.

#define XMB_RIT_REG_OFFSET 0x1C

Mbox receive interrupt threshold register.

Referenced by XMbox_SetReceiveThreshold().

#define XMB_SIT_REG_OFFSET 0x18

Mbox send interrupt threshold register.

Referenced by XMbox_SetSendThreshold().

#define XMB_STATUS_FIFO_EMPTY 0x00000001

Receive FIFO is Empty.

#define XMB_STATUS_FIFO_FULL 0x00000002

Send FIFO is Full.

#define XMB_STATUS_REG_OFFSET 0x10

Mbox status reg.

Referenced by XMbox_GetStatus().

#define XMB_STATUS_RTA 0x00000008

Receive FIFO Threshold Status.

#define XMB_STATUS_STA 0x00000004

Send FIFO Threshold Status.

#define XMB_WRITE_REG_OFFSET 0x00

Mbox write register.

#define XMbox_IsEmptyHw | ( |  | BaseAddress | ) | ((XMbox_ReadReg (BaseAddress, XMB_STATUS_REG_OFFSET) & XMB_STATUS_FIFO_EMPTY))

Checks if the Read FIFO is Empty.

Parameters

  BaseAddress | contains the base address of the mbox device.

Returns
  - TRUE if the FIFO is empty.
  - FALSE if there is data to be read from the FIFO.

Note
  C-style signature: u32 XMbox_IsEmptyHw(u32 BaseAddress);

Referenced by XMbox_Flush(), XMbox_IsEmpty(), XMbox_Read(), and XMbox_ReadBlocking().

#define XMbox_IsFullHw | ( |  | BaseAddress | ) | ((XMbox_ReadReg (BaseAddress, XMB_STATUS_REG_OFFSET) & XMB_STATUS_FIFO_FULL))

Checks if there is room in the Write FIFO.

Parameters

  BaseAddress | contains the base address of the mbox device.

Returns
  - FALSE if there is room in FIFO,
  - TRUE if there is no room in the FIFO

Note
  C-style signature: u32 XMbox_IsFullHw(u32 BaseAddress);

Referenced by XMbox_IsFull(), XMbox_Write(), and XMbox_WriteBlocking().

#define XMbox_ReadMBox | ( |  | BaseAddress | ) | XMbox_ReadReg (BaseAddress, XMB_READ_REG_OFFSET)

Read the mbox read FIFO.

Parameters

  BaseAddress | contains the base address of the mbox device.

Returns
  The value read from the register, a 32 bit value.

Note
  C-style signature: u32 XMbox_ReadMBox(u32 BaseAddress);

Referenced by XMbox_Flush(), XMbox_Read(), and XMbox_ReadBlocking().

#define XMbox_ReadReg | ( |  | BaseAddress,
|  |  | RegOffset
| ) |  | Xil_In32((BaseAddress) + (RegOffset))

Read one of the mbox registers.

Parameters

  BaseAddress | contains the base address of the mbox device.
  RegOffset | contains the offset from the 1st register of the mbox to select the specific register of the mbox.

Returns
  The value read from the register, a 32 bit value.

Note
  C-style signature: u32 XMbox_ReadReg(u32 BaseAddress, unsigned RegOffset);

Referenced by XMbox_GetInterruptEnable(), XMbox_GetInterruptStatus(), and XMbox_GetStatus().

#define XMbox_WriteMBox | ( |  | BaseAddress,
|  |  | ValueToWrite
| ) |  | XMbox_WriteReg (BaseAddress, XMB_WRITE_REG_OFFSET, ValueToWrite)

Write the mbox write register.

Parameters

  BaseAddress | contains the base address of the mbox device.
  ValueToWrite | contains the value to be written.

Returns
  None.

Note
  C-style signature: u32 XMbox_WriteMBox(u32 BaseAddress, u32 ValueToWrite);

Referenced by XMbox_Write(), and XMbox_WriteBlocking().

#define XMbox_WriteReg | ( |  | BaseAddress,
|  |  | RegOffset,
|  |  | ValueToWrite
| ) |  | Xil_Out32(((BaseAddress) + (RegOffset)), (ValueToWrite))

Write a specified value to a register of a mbox.

Parameters

  BaseAddress | is the base address of the mbox device.
  RegOffset | contain the offset from the 1st register of the mbox to select the specific register of the mbox.
  ValueToWrite | is the 32 bit value to be written to the register.

Returns
  None

Note
  C-style signature: void XMbox_WriteReg(u32 BaseAddress, unsigned RegOffset, u32 ValueToWrite);

Referenced by XMbox_ClearInterrupt(), XMbox_ResetFifos(), XMbox_SetInterruptEnable(), XMbox_SetReceiveThreshold(), and XMbox_SetSendThreshold().

## Function Documentation

int XMbox_CfgInitialize | ( | XMbox * | InstancePtr,
|  | XMbox_Config * | ConfigPtr,
|  | UINTPTR | EffectiveAddress
| ) |  |

Initializes a specific mailbox.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.
  CfgPtr | is the device configuration structure containing required HW build data.
  EffectiveAddr | 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 XMbox_Config::BaseAddress, XMbox::Config, and XMbox::IsReady.

Referenced by MailboxExample(), and ProdCon().

void XMbox_ClearInterrupt | ( | XMbox * | InstancePtr,
|  | u32 | Mask
| ) |  |

Clears pending interrupts with the provided mask.

This function should be called after the software has serviced the interrupts that are pending. This function clears the corresponding bits of the Interrupt Status Register. This function can only be used for Non-FSL interface. If not, the function will fail in an assert.

Parameters

  InstancePtr | is a pointer to the instance to be worked on.
  Mask | is a logical OR of XMB_IX_* constants found in xmbox_hw.h.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_IS_REG_OFFSET, and XMbox_WriteReg.

int XMbox_Flush | ( | XMbox * | InstancePtr | ) |

Resets the mailbox FIFOs by emptying the READ FIFO and making sure the Error Status is zero.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.

Returns
  - XST_SUCCESS on success.
  - XST_FAILURE if there are any outstanding errors.

Note
  Data from read FIFO is thrown away.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::RecvID, XMbox_Config::UseFSL, XMbox_IsEmptyHw, and XMbox_ReadMBox.

u32 XMbox_GetInterruptEnable | ( | XMbox * | InstancePtr | ) |

Retrieves the interrupt enable for the mailbox.

AND the result of this function with XMB_IX_* to determine which interrupts of this mailbox are enabled. This function can only be used for Non-FSL interface. If not, the function will fail in an assert.

Parameters

  InstancePtr | is a pointer to the instance to be worked on.

Returns
  Mask of interrupt bits made up of XMB_IX_* constants found in xmbox_hw.h.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_IE_REG_OFFSET, and XMbox_ReadReg.

u32 XMbox_GetInterruptStatus | ( | XMbox * | InstancePtr | ) |

Retrieve the interrupt status for the mailbox.

AND the results of this function with XMB_IX_* to determine which interrupts are currently pending to the processor. This function can only be used for Non-FSL interface. If not, the function will fail in an assert.

Parameters

  InstancePtr | is a pointer to the instance to be worked on.

Returns
  Mask of interrupt bits made up of XMB_IX_* constants found in xmbox_hw.h.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_IS_REG_OFFSET, and XMbox_ReadReg.

u32 XMbox_GetStatus | ( | XMbox * | InstancePtr | ) |

Returns Status register contents.

This function can only be used for Non-FSL interface. If not, the function will fail in an assert.

Parameters

  InstancePtr | is a pointer to the instance to be worked on.

Returns
  Value returns Status Register contents.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_STATUS_REG_OFFSET, and XMbox_ReadReg.

u32 XMbox_IsEmpty | ( | XMbox * | InstancePtr | ) |

Checks to see if there is data available to be read.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.

Returns
  - FALSE if there is data to be read.
  - TRUE is there no data to be read.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::RecvID, XMbox_Config::UseFSL, and XMbox_IsEmptyHw.

u32 XMbox_IsFull | ( | XMbox * | InstancePtr | ) |

Checks to see if there is room in the write FIFO.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.

Returns
  - FALSE if there is room in write FIFO.
  - TRUE if there is room in write FIFO.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::SendID, XMbox_Config::UseFSL, and XMbox_IsFullHw.

int XMbox_Read | ( | XMbox * | InstancePtr,
|  | u32 * | BufferPtr,
|  | u32 | RequestedBytes,
|  | u32 * | BytesRecvdPtr
| ) |  |

Reads requested bytes from the mailbox referenced by InstancePtr,into the buffer pointed to by the provided pointer.

The number of bytes must be a multiple of 4 (bytes). If not, the call will fail in an assert.

This function is non blocking.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.
  BufferPtr | is the buffer to read the mailbox contents into, aligned to a word boundary.
  RequestedBytes | is the number of bytes of data requested.
  BytesRecvdPtr | is the memory that is updated with the number of bytes of data actually read.

Returns
  - XST_SUCCESS on success.
  - XST_NO_DATA ifthere was no data in the mailbox.

On success, the number of bytes read is returned through the pointer. The call may return with fewer bytes placed in the buffer than requested (not including zero). This is not necessarily an error condition and indicates the amount of data that was currently available in the mailbox.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::RecvID, XMbox_Config::UseFSL, XMbox_IsEmptyHw, and XMbox_ReadMBox.

Referenced by MailboxExample_Receive().

void XMbox_ReadBlocking | ( | XMbox * | InstancePtr,
|  | u32 * | BufferPtr,
|  | u32 | RequestedBytes
| ) |  |

Reads requested bytes from the mailbox referenced by InstancePtr,into the buffer pointed to by the provided pointer.

The number of bytes must be a multiple of 4 (bytes). If not, the call will fail in an assert.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.
  BufferPtr | is the buffer to read the mailbox contents into, aligned to a word boundary.
  RequestedBytes | is the number of bytes of data requested.

Returns
  None.

Note
  The call blocks until the number of bytes requested are available.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::RecvID, XMbox_Config::UseFSL, XMbox_IsEmptyHw, and XMbox_ReadMBox.

Referenced by MailboxExample_Receive(), and ProdCon().

void XMbox_ResetFifos | ( | XMbox * | InstancePtr | ) |

Resets the mailbox FIFOs by clearing the READ and WRITE FIFOs using the hardware control register for memory mapped IO.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.

Returns
  None.

Note
  Use XMbox_Flush instead for FSL based access.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_CTRL_REG_OFFSET, XMB_CTRL_RESET_RECV_FIFO, XMB_CTRL_RESET_SEND_FIFO, and XMbox_WriteReg.

void XMbox_SetInterruptEnable | ( | XMbox * | InstancePtr,
|  | u32 | Mask
| ) |  |

Sets the interrupt enable register for this mailbox.

This function can only be used for Non-FSL interface. If not, the function will fail in an assert.

Parameters

  InstancePtr | is a pointer to the instance to be worked on.
  Mask | is a logical OR of XMB_IX_* constants found in xmbox_hw.h.

Returns
  None.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_IE_REG_OFFSET, and XMbox_WriteReg.

void XMbox_SetReceiveThreshold | ( | XMbox * | InstancePtr,
|  | u32 | Value
| ) |  |

Set the Receive Interrupt Threshold.

This function can only be used for Non-FSL interface. If not, the function will fail in an assert.

Parameters

  InstancePtr | is a pointer to the instance to be worked on.
  Value | is a value to set for the RIT. Only lower Log2(FIFO Depth) bits are used.

Returns
  None.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_RIT_REG_OFFSET, and XMbox_WriteReg.

void XMbox_SetSendThreshold | ( | XMbox * | InstancePtr,
|  | u32 | Value
| ) |  |

Sets the Send Interrupt Threshold.

This function can only be used for Non-FSL interface. If not, the function will fail in an assert.

Parameters

  InstancePtr | is a pointer to the instance to be worked on.
  Value | is a value to set for the SIT. Only lower Log2(FIFO Depth) bits are used.

Returns
  None.

Note
  None.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::UseFSL, XMB_SIT_REG_OFFSET, and XMbox_WriteReg.

int XMbox_Write | ( | XMbox * | InstancePtr,
|  | u32 * | BufferPtr,
|  | u32 | RequestedBytes,
|  | u32 * | BytesSentPtr
| ) |  |

Writes the requested bytes from the buffer pointed to by the provided pointer into the mailbox referenced by InstancePtr.The number of bytes must be a multiple of 4 (bytes).

If not, the call will fail in an assert.

This function is non blocking.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.
  BufferPtr | is the source data buffer, aligned to a word boundary.
  RequestedBytes | is the number of bytes requested to be written.
  BytesRecvdPtr | points to memory which is updated with the actual number of bytes written, return value.

Returns

          - XST_SUCCESS on success.
          - XST_FIFO_NO_ROOM if the fifo was full.

On success, the number of bytes successfully written into the destination mailbox is returned in the provided pointer. The call may return with zero. This is not necessarily an error condition and indicates that the mailbox is currently full.

Note
  The provided buffer pointed to by BufferPtr must be aligned to a word boundary.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::SendID, XMbox_Config::UseFSL, XMbox_IsFullHw, and XMbox_WriteMBox.

Referenced by MailboxExample_Send().

void XMbox_WriteBlocking | ( | XMbox * | InstancePtr,
|  | u32 * | BufferPtr,
|  | u32 | RequestedBytes
| ) |  |

Writes the requested bytes from the buffer pointed to by the provided pointer into the mailbox referenced by InstancePtr.

The number of bytes must be a multiple of 4 (bytes). If not, the call will fail in an assert.

Parameters

  InstancePtr | is a pointer to the XMbox instance to be worked on.
  BufferPtr | is the source data buffer, aligned to a word boundary.
  RequestedBytes | is the number of bytes requested to be written.

Returns
  None.

Note
  The call blocks until the number of bytes requested are written. The provided buffer pointed to by BufferPtr must be aligned to a word boundary.

References XMbox_Config::BaseAddress, XMbox::Config, XMbox_Config::SendID, XMbox_Config::UseFSL, XMbox_IsFullHw, and XMbox_WriteMBox.

Referenced by MailboxExample_Send(), and ProdCon().