Xilinx Processor IP Library

Software Drivers

xmbox.c File Reference

Detailed Description

Contains required functions for the XMbox driver.

 MODIFICATION HISTORY:

 Ver   Who  Date     Changes
 ----- ---- -------- -----------------------------------------------
 1.00a va            First release
 1.00a ecm  06/01/07 Cleanup, new coding standard, check into XCS
 1.01a ecm  08/19/08 Fixed the receive routine, FSL leg, was using SendID
			instead of the correct RecvID.
 			Fixed CRs 466320, 466322, 476535, 476242, 476243
					  new rev
 2.00a hm   04/09/09 Added support for mailbox v2.0, which has interrupts;
			Fixed CR 502464, which removed extra
			definitions that are not associated with
			the interface.
			Fixed the canonical definition so that each
			interface is considered as a device instance.
 3.00a hbm  10/19/09   Migrated to HAL phase 1 to use xil_io.
			Removed _m from the function names.
			Renamed _mIsEmpty to _IsEmptyHw and _mIsFull
			to _IsFullHw.
 3.02a bss  08/18/12   Added XMbox_GetStatus API for CR 676187

#include <string.h>
#include "xmbox.h"
#include "xil_assert.h"

Functions

int XMbox_CfgInitialize (XMbox *InstancePtr, XMbox_Config *ConfigPtr, u32 EffectiveAddress)
int XMbox_Read (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes, u32 *BytesRecvdPtr)
void XMbox_ReadBlocking (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes)
int XMbox_Write (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes, u32 *BytesSentPtr)
void XMbox_WriteBlocking (XMbox *InstancePtr, u32 *BufferPtr, u32 RequestedBytes)
u32 XMbox_IsEmpty (XMbox *InstancePtr)
u32 XMbox_IsFull (XMbox *InstancePtr)
int XMbox_Flush (XMbox *InstancePtr)
void XMbox_SetInterruptEnable (XMbox *InstancePtr, u32 Mask)
u32 XMbox_GetInterruptEnable (XMbox *InstancePtr)
u32 XMbox_GetInterruptStatus (XMbox *InstancePtr)
void XMbox_ClearInterrupt (XMbox *InstancePtr, u32 Mask)
void XMbox_SetSendThreshold (XMbox *InstancePtr, u32 Value)
void XMbox_SetReceiveThreshold (XMbox *InstancePtr, u32 Value)
u32 XMbox_GetStatus (XMbox *InstancePtr)

Function Documentation

int XMbox_CfgInitialize (  XMbox *  InstancePtr,
XMbox_Config *  ConfigPtr,
u32  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.

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.

int XMbox_Flush (  XMbox *  InstancePtr  ) 
 

Resets the mailbox FIFOs by empting 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.
Copyright @ 1995-2014 Xilinx, Inc. All rights reserved.