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

Data Structures

Macros

Functions

Register Offset Definitions

Status register bit definitions

Interrupt Registers(s) bits definitions.

Error bits definition.

Control register bits definition.

Macro Definition Documentation

Function Documentation