uartlite
Xilinx Vitis Drivers API Documentation
Uartlite_v3_6

Data Structures

struct  XUartLite_Stats
 Statistics for the XUartLite driver. More...
 
struct  XUartLite_Buffer
 The following data type is used to manage the buffers that are handled when sending and receiving data in the interrupt mode. More...
 
struct  XUartLite_Config
 This typedef contains configuration information for the device. More...
 
struct  XUartLite
 The XUartLite driver instance data. More...
 

Macros

#define XUartLite_WriteReg(BaseAddress, RegOffset, Data)   XUartLite_Out32((BaseAddress) + (RegOffset), (u32)(Data))
 Write a value to a UartLite register. More...
 
#define XUartLite_ReadReg(BaseAddress, RegOffset)   XUartLite_In32((BaseAddress) + (RegOffset))
 Read a value from a UartLite register. More...
 
#define XUartLite_SetControlReg(BaseAddress, Mask)   XUartLite_WriteReg((BaseAddress), XUL_CONTROL_REG_OFFSET, (Mask))
 Set the contents of the control register. More...
 
#define XUartLite_GetStatusReg(BaseAddress)   XUartLite_ReadReg((BaseAddress), XUL_STATUS_REG_OFFSET)
 Get the contents of the status register. More...
 
#define XUartLite_IsReceiveEmpty(BaseAddress)
 Check to see if the receiver has data. More...
 
#define XUartLite_IsTransmitFull(BaseAddress)
 Check to see if the transmitter is full. More...
 
#define XUartLite_IsIntrEnabled(BaseAddress)
 Check to see if the interrupt is enabled. More...
 
#define XUartLite_EnableIntr(BaseAddress)   XUartLite_SetControlReg((BaseAddress), XUL_CR_ENABLE_INTR)
 Enable the device interrupt. More...
 
#define XUartLite_DisableIntr(BaseAddress)   XUartLite_SetControlReg((BaseAddress), 0)
 Disable the device interrupt. More...
 

Typedefs

typedef void(* XUartLite_Handler )(void *CallBackRef, unsigned int ByteCount)
 Callback function. More...
 

Functions

int XUartLite_CfgInitialize (XUartLite *InstancePtr, XUartLite_Config *Config, UINTPTR EffectiveAddr)
 Initialize a XUartLite instance. More...
 
unsigned int XUartLite_Send (XUartLite *InstancePtr, u8 *DataBufferPtr, unsigned int NumBytes)
 This functions sends the specified buffer of data using the UART in either polled or interrupt driven modes. More...
 
unsigned int XUartLite_Recv (XUartLite *InstancePtr, u8 *DataBufferPtr, unsigned int NumBytes)
 This function will attempt to receive a specified number of bytes of data from the UART and store it into the specified buffer. More...
 
void XUartLite_ResetFifos (XUartLite *InstancePtr)
 This function resets the FIFOs, both transmit and receive, of the UART such that they are emptied. More...
 
int XUartLite_IsSending (XUartLite *InstancePtr)
 This function determines if the specified UART is sending data. More...
 
unsigned int XUartLite_SendBuffer (XUartLite *InstancePtr)
 This function sends a buffer that has been previously specified by setting up the instance variables of the instance. More...
 
unsigned int XUartLite_ReceiveBuffer (XUartLite *InstancePtr)
 This function receives a buffer that has been previously specified by setting up the instance variables of the instance. More...
 
u8 XUartLite_GetSR (XUartLite *InstancePtr)
 This function reads the status register and updates the error stats, before returning the status register value. More...
 
int XUartLite_Initialize (XUartLite *InstancePtr, u16 DeviceId)
 Initialize a XUartLite instance. More...
 
void XUartLite_GetStats (XUartLite *InstancePtr, XUartLite_Stats *StatsPtr)
 Returns a snapshot of the current statistics in the structure specified. More...
 
void XUartLite_ClearStats (XUartLite *InstancePtr)
 This function zeros the statistics for the given instance. More...
 
int XUartLite_SelfTest (XUartLite *InstancePtr)
 Runs a self-test on the device hardware. More...
 
void XUartLite_EnableInterrupt (XUartLite *InstancePtr)
 This function enables the UART interrupt such that an interrupt will occur when data is received or data has been transmitted. More...
 
void XUartLite_DisableInterrupt (XUartLite *InstancePtr)
 This function disables the UART interrupt. More...
 
void XUartLite_SetRecvHandler (XUartLite *InstancePtr, XUartLite_Handler FuncPtr, void *CallBackRef)
 This function sets the handler that will be called when an event (interrupt) occurs in the driver. More...
 
void XUartLite_SetSendHandler (XUartLite *InstancePtr, XUartLite_Handler FuncPtr, void *CallBackRef)
 This function sets the handler that will be called when an event (interrupt) occurs in the driver. More...
 
void XUartLite_InterruptHandler (XUartLite *InstancePtr)
 This function is the interrupt handler for the UART lite driver. More...
 
void XUartLite_SendByte (UINTPTR BaseAddress, u8 Data)
 This functions sends a single byte using the UART. More...
 
u8 XUartLite_RecvByte (UINTPTR BaseAddress)
 This functions receives a single byte using the UART. More...
 

Variables

XUartLite_Config XUartLite_ConfigTable [XPAR_XUARTLITE_NUM_INSTANCES]
 The configuration table for UART Lite devices. More...
 
XUartLite_Config XUartLite_ConfigTable []
 The configuration table for UART Lite devices. More...
 

Macro Definition Documentation

#define XUartLite_DisableIntr (   BaseAddress)    XUartLite_SetControlReg((BaseAddress), 0)

Disable the device interrupt.

We cannot read the control register, so we just clear all bits. Since the only other ones are the FIFO reset bits, this works without side effects.

Parameters
BaseAddressis the base address of the device
Returns
None.
Note
C-style Signature: void XUartLite_DisableIntr(u32 BaseAddress);
#define XUartLite_EnableIntr (   BaseAddress)    XUartLite_SetControlReg((BaseAddress), XUL_CR_ENABLE_INTR)

Enable the device interrupt.

We cannot read the control register, so we just write the enable interrupt bit and clear all others. Since the only other ones are the FIFO reset bits, this works without side effects.

Parameters
BaseAddressis the base address of the device
Returns
None.
Note
C-style Signature: void XUartLite_EnableIntr(u32 BaseAddress);
#define XUartLite_GetStatusReg (   BaseAddress)    XUartLite_ReadReg((BaseAddress), XUL_STATUS_REG_OFFSET)

Get the contents of the status register.

Use the XUL_SR_* constants defined above to interpret the bit-mask returned.

Parameters
BaseAddressis the base address of the device
Returns
A 32-bit value representing the contents of the status register.
Note
C-style Signature: u32 XUartLite_GetStatusReg(u32 BaseAddress);

Referenced by XUartLite_GetSR().

#define XUartLite_IsIntrEnabled (   BaseAddress)
Value:
((XUartLite_GetStatusReg((BaseAddress)) & XUL_SR_INTR_ENABLED) == \
XUL_SR_INTR_ENABLED)
#define XUartLite_GetStatusReg(BaseAddress)
Get the contents of the status register.
Definition: xuartlite_l.h:203

Check to see if the interrupt is enabled.

Parameters
BaseAddressis the base address of the device
Returns
TRUE if the interrupt is enabled, FALSE otherwise.
Note
C-style Signature: int XUartLite_IsIntrEnabled(u32 BaseAddress);
#define XUartLite_IsReceiveEmpty (   BaseAddress)
Value:
((XUartLite_GetStatusReg((BaseAddress)) & XUL_SR_RX_FIFO_VALID_DATA) != \
XUL_SR_RX_FIFO_VALID_DATA)
#define XUartLite_GetStatusReg(BaseAddress)
Get the contents of the status register.
Definition: xuartlite_l.h:203

Check to see if the receiver has data.

Parameters
BaseAddressis the base address of the device
Returns
TRUE if the receiver is empty, FALSE if there is data present.
Note
C-style Signature: int XUartLite_IsReceiveEmpty(u32 BaseAddress);

Referenced by XUartLite_RecvByte().

#define XUartLite_IsTransmitFull (   BaseAddress)
Value:
((XUartLite_GetStatusReg((BaseAddress)) & XUL_SR_TX_FIFO_FULL) == \
XUL_SR_TX_FIFO_FULL)
#define XUartLite_GetStatusReg(BaseAddress)
Get the contents of the status register.
Definition: xuartlite_l.h:203

Check to see if the transmitter is full.

Parameters
BaseAddressis the base address of the device
Returns
TRUE if the transmitter is full, FALSE otherwise.
Note
C-style Signature: int XUartLite_IsTransmitFull(u32 BaseAddress);

Referenced by XUartLite_SendByte().

#define XUartLite_ReadReg (   BaseAddress,
  RegOffset 
)    XUartLite_In32((BaseAddress) + (RegOffset))

Read a value from a UartLite register.

A 32 bit read is performed.

Parameters
BaseAddressis the base address of the UartLite device.
RegOffsetis the register offset from the base to read from.
Returns
Data read from the register.
Note
C-style signature: u32 XUartLite_ReadReg(u32 BaseAddress, u32 RegOffset)

Referenced by XUartLite_InterruptHandler(), XUartLite_IsSending(), XUartLite_ReceiveBuffer(), XUartLite_RecvByte(), XUartLite_ResetFifos(), and XUartLite_SelfTest().

#define XUartLite_SetControlReg (   BaseAddress,
  Mask 
)    XUartLite_WriteReg((BaseAddress), XUL_CONTROL_REG_OFFSET, (Mask))

Set the contents of the control register.

Use the XUL_CR_* constants defined above to create the bit-mask to be written to the register.

Parameters
BaseAddressis the base address of the device
Maskis the 32-bit value to write to the control register
Returns
None.
Note
C-style Signature: void XUartLite_SetControlReg(u32 BaseAddress, u32 Mask);
#define XUartLite_WriteReg (   BaseAddress,
  RegOffset,
  Data 
)    XUartLite_Out32((BaseAddress) + (RegOffset), (u32)(Data))

Write a value to a UartLite register.

A 32 bit write is performed.

Parameters
BaseAddressis the base address of the UartLite device.
RegOffsetis the register offset from the base to write to.
Datais the data written to the register.
Returns
None.
Note
C-style signature: void XUartLite_WriteReg(u32 BaseAddress, u32 RegOffset, u32 Data)

Referenced by XUartLite_CfgInitialize(), XUartLite_DisableInterrupt(), XUartLite_EnableInterrupt(), XUartLite_ReceiveBuffer(), XUartLite_Recv(), XUartLite_ResetFifos(), XUartLite_Send(), XUartLite_SendBuffer(), and XUartLite_SendByte().

Typedef Documentation

typedef void(* XUartLite_Handler)(void *CallBackRef, unsigned int ByteCount)

Callback function.

The first argument is a callback reference passed in by the upper layer when setting the callback functions, and passed back to the upper layer when the callback is invoked. The second argument is the ByteCount which is the number of bytes that actually moved from/to the buffer provided in the _Send/_Receive call.

Function Documentation

int XUartLite_CfgInitialize ( XUartLite InstancePtr,
XUartLite_Config Config,
UINTPTR  EffectiveAddr 
)

Initialize a XUartLite instance.

The receive and transmit FIFOs of the UART are not flushed, so the user may want to flush them. The hardware device does not have any way to disable the receiver such that any valid data may be present in the receive FIFO. This function disables the UART interrupt. The baudrate and format of the data are fixed in the hardware at hardware build time.

Parameters
InstancePtris a pointer to the XUartLite instance.
Configis a reference to a structure containing information about a specific UART Lite device. This function initializes an InstancePtr object for a specific device specified by the contents of Config. This function can initialize multiple instance objects with the use of multiple calls giving different Config information on each call.
EffectiveAddris the device base address in the virtual memory address space. The caller is responsible for keeping the address mapping from EffectiveAddr to the device physical base address unchanged once this function is invoked. Unexpected errors may occur if the address mapping changes after this function is called. If address translation is not used, use Config->BaseAddress for this parameters, passing the physical address instead.
Returns
  • XST_SUCCESS if everything starts up as expected.
Note
The Config pointer argument is not used by this function, but is provided to keep the function signature consistent with other drivers.

References XUartLite_ClearStats(), and XUartLite_WriteReg.

Referenced by XUartLite_Initialize().

void XUartLite_ClearStats ( XUartLite InstancePtr)
void XUartLite_DisableInterrupt ( XUartLite InstancePtr)

This function disables the UART interrupt.

After calling this function, data may still be received by the UART but no interrupt will be generated since the hardware device has no way to disable the receiver.

Parameters
InstancePtris a pointer to the XUartLite instance.
Returns
None.
Note
None.

References XUartLite_WriteReg.

void XUartLite_EnableInterrupt ( XUartLite InstancePtr)

This function enables the UART interrupt such that an interrupt will occur when data is received or data has been transmitted.

The device contains 16 byte receive and transmit FIFOs such that an interrupt is generated anytime there is data in the receive FIFO and when the transmit FIFO transitions from not empty to empty.

Parameters
InstancePtris a pointer to the XUartLite instance.
Returns
None.
Note
None.

References XUartLite_WriteReg.

Referenced by UartLiteIntrExample().

u8 XUartLite_GetSR ( XUartLite InstancePtr)

This function reads the status register and updates the error stats, before returning the status register value.

The status register is a clear on read register, so the errors if occurred have to be recorded everytime status register is read. This function is designed to be an internal function for the XUartLite component such that it may be called from wherever the status register needs to be read from the other driver functions.

Parameters
InstancePtris a pointer to the XUartLite instance.
Returns
The value of status register.
Note
None.

References XUartLite_GetStatusReg.

Referenced by XUartLite_ReceiveBuffer(), XUartLite_Recv(), XUartLite_Send(), and XUartLite_SendBuffer().

void XUartLite_GetStats ( XUartLite InstancePtr,
XUartLite_Stats StatsPtr 
)

Returns a snapshot of the current statistics in the structure specified.

Parameters
InstancePtris a pointer to the XUartLite instance.
StatsPtris a pointer to a XUartLiteStats structure to where the statistics are to be copied.
Returns
None.
Note
None.

References XUartLite_Stats::CharactersReceived, XUartLite_Stats::CharactersTransmitted, XUartLite_Stats::ReceiveFramingErrors, XUartLite_Stats::ReceiveInterrupts, XUartLite_Stats::ReceiveOverrunErrors, XUartLite_Stats::ReceiveParityErrors, and XUartLite_Stats::TransmitInterrupts.

int XUartLite_Initialize ( XUartLite InstancePtr,
u16  DeviceId 
)

Initialize a XUartLite instance.

The receive and transmit FIFOs of the UART are not flushed, so the user may want to flush them. The hardware device does not have any way to disable the receiver such that any valid data may be present in the receive FIFO. This function disables the UART interrupt. The baudrate and format of the data are fixed in the hardware at hardware build time.

Parameters
InstancePtris a pointer to the XUartLite instance.
DeviceIdis the unique id of the device controlled by this XUartLite instance. Passing in a device id associates the generic XUartLite instance to a specific device, as chosen by the caller or application developer.
Returns
  • XST_SUCCESS if everything starts up as expected.
  • XST_DEVICE_NOT_FOUND if the device is not found in the configuration table.
Note
None.

References XUartLite_Config::RegBaseAddr, and XUartLite_CfgInitialize().

Referenced by UartLiteIntrExample(), UartLitePolledExample(), and UartLiteSelfTestExample().

void XUartLite_InterruptHandler ( XUartLite InstancePtr)

This function is the interrupt handler for the UART lite driver.

It must be connected to an interrupt system by the user such that it is called when an interrupt for any UART lite occurs. This function does not save or restore the processor context such that the user must ensure this occurs.

Parameters
InstancePtrcontains a pointer to the instance of the UART that the interrupt is for.
Returns
None.
Note
None.

References XUartLite_ReadReg.

Referenced by SetupInterruptSystem().

int XUartLite_IsSending ( XUartLite InstancePtr)

This function determines if the specified UART is sending data.

If the transmitter register is not empty, it is sending data.

Parameters
InstancePtris a pointer to the XUartLite instance.
Returns
A value of TRUE if the UART is sending data, otherwise FALSE.
Note
None.

References XUartLite_ReadReg.

unsigned int XUartLite_ReceiveBuffer ( XUartLite InstancePtr)

This function receives a buffer that has been previously specified by setting up the instance variables of the instance.

This function is designed to be an internal function for the XUartLite component such that it may be called from a shell function that sets up the buffer or from an interrupt handler.

This function will attempt to receive a specified number of bytes of data from the UART and store it into the specified buffer. This function is designed for either polled or interrupt driven modes. It is non-blocking such that it will return if there is no data has already received by the UART.

In a polled mode, this function will only receive as much data as the UART can buffer, either in the receiver or in the FIFO if present and enabled. The application may need to call it repeatedly to receive a buffer. Polled mode is the default mode of operation for the driver.

In interrupt mode, this function will start receiving and then the interrupt handler of the driver will continue until the buffer has been received. A callback function, as specified by the application, will be called to indicate the completion of receiving the buffer or when any receive errors or timeouts occur.

Parameters
InstancePtris a pointer to the XUartLite instance.
Returns
The number of bytes received.
Note
None.

References XUartLite_Stats::CharactersReceived, XUartLite_GetSR(), XUartLite_ReadReg, and XUartLite_WriteReg.

Referenced by XUartLite_Recv().

unsigned int XUartLite_Recv ( XUartLite InstancePtr,
u8 *  DataBufferPtr,
unsigned int  NumBytes 
)

This function will attempt to receive a specified number of bytes of data from the UART and store it into the specified buffer.

This function is designed for either polled or interrupt driven modes. It is non-blocking such that it will return if no data has already received by the UART.

In a polled mode, this function will only receive as much data as the UART can buffer in the FIFO. The application may need to call it repeatedly to receive a buffer. Polled mode is the default mode of operation for the driver.

In interrupt mode, this function will start receiving and then the interrupt handler of the driver will continue receiving data until the buffer has been received. A callback function, as specified by the application, will be called to indicate the completion of receiving the buffer or when any receive errors or timeouts occur.

Parameters
InstancePtris a pointer to the XUartLite instance.
DataBufferPtris pointer to buffer for data to be received into.
NumBytesis the number of bytes to be received. A value of zero will stop a previous receive operation that is in progress in interrupt mode.
Returns
The number of bytes received.
Note
The number of bytes is not asserted so that this function may be called with a value of zero to stop an operation that is already in progress.

References XUartLite_GetSR(), XUartLite_ReceiveBuffer(), and XUartLite_WriteReg.

Referenced by UartLiteIntrExample(), and UartLitePolledExample().

u8 XUartLite_RecvByte ( UINTPTR  BaseAddress)

This functions receives a single byte using the UART.

It is blocking in that it waits for the receiver to become non-empty before it reads from the receive register.

Parameters
BaseAddressis the base address of the device
Returns
The byte of data received.
Note
None.

References XUartLite_IsReceiveEmpty, and XUartLite_ReadReg.

Referenced by UartLiteLowLevelExample().

void XUartLite_ResetFifos ( XUartLite InstancePtr)

This function resets the FIFOs, both transmit and receive, of the UART such that they are emptied.

Since the UART does not have any way to disable it from receiving data, it may be necessary for the application to reset the FIFOs to get rid of any unwanted data.

Parameters
InstancePtris a pointer to the XUartLite instance .
Returns
None.
Note
None.

References XUartLite_ReadReg, and XUartLite_WriteReg.

Referenced by XUartLite_SelfTest().

int XUartLite_SelfTest ( XUartLite InstancePtr)

Runs a self-test on the device hardware.

Since there is no way to perform a loopback in the hardware, this test can only check the state of the status register to verify it is correct. This test assumes that the hardware device is still in its reset state, but has been initialized with the Initialize function.

Parameters
InstancePtris a pointer to the XUartLite instance.
Returns
  • XST_SUCCESS if the self-test was successful.
  • XST_FAILURE if the self-test failed, the status register value was not correct
Note
None.

References XUartLite_ReadReg, and XUartLite_ResetFifos().

Referenced by UartLiteIntrExample(), UartLitePolledExample(), and UartLiteSelfTestExample().

unsigned int XUartLite_Send ( XUartLite InstancePtr,
u8 *  DataBufferPtr,
unsigned int  NumBytes 
)

This functions sends the specified buffer of data using the UART in either polled or interrupt driven modes.

This function is non-blocking such that it will return before the data has been sent by the UART. If the UART is busy sending data, it will return and indicate zero bytes were sent.

In a polled mode, this function will only send as much data as the UART can buffer in the FIFO. The application may need to call it repeatedly to send a buffer.

In interrupt mode, this function will start sending the specified buffer and then the interrupt handler of the driver will continue sending data until the buffer has been sent. A callback function, as specified by the application, will be called to indicate the completion of sending the buffer.

Parameters
InstancePtris a pointer to the XUartLite instance.
DataBufferPtris pointer to a buffer of data to be sent.
NumBytescontains the number of bytes to be sent. A value of zero will stop a previous send operation that is in progress in interrupt mode. Any data that was already put into the transmit FIFO will be sent.
Returns
The number of bytes actually sent.
Note
The number of bytes is not asserted so that this function may be called with a value of zero to stop an operation that is already in progress.

References XUartLite_GetSR(), XUartLite_SendBuffer(), and XUartLite_WriteReg.

Referenced by UartLiteIntrExample(), and UartLitePolledExample().

unsigned int XUartLite_SendBuffer ( XUartLite InstancePtr)

This function sends a buffer that has been previously specified by setting up the instance variables of the instance.

This function is designed to be an internal function for the XUartLite component such that it may be called from a shell function that sets up the buffer or from an interrupt handler.

This function sends the specified buffer of data to the UART in either polled or interrupt driven modes. This function is non-blocking such that it will return before the data has been sent by the UART.

In a polled mode, this function will only send as much data as the UART can buffer, either in the transmitter or in the FIFO if present and enabled. The application may need to call it repeatedly to send a buffer.

In interrupt mode, this function will start sending the specified buffer and then the interrupt handler of the driver will continue until the buffer has been sent. A callback function, as specified by the application, will be called to indicate the completion of sending the buffer.

Parameters
InstancePtris a pointer to the XUartLite instance.
Returns
NumBytes is the number of bytes actually sent (put into the UART transmitter and/or FIFO).
Note
None.

References XUartLite_Stats::CharactersTransmitted, XUartLite_GetSR(), and XUartLite_WriteReg.

Referenced by XUartLite_Send().

void XUartLite_SendByte ( UINTPTR  BaseAddress,
u8  Data 
)

This functions sends a single byte using the UART.

It is blocking in that it waits for the transmitter to become non-full before it writes the byte to the transmit register.

Parameters
BaseAddressis the base address of the device
Datais the byte of data to send
Returns
None.
Note
None.

References XUartLite_IsTransmitFull, and XUartLite_WriteReg.

Referenced by UartLiteLowLevelExample().

void XUartLite_SetRecvHandler ( XUartLite InstancePtr,
XUartLite_Handler  FuncPtr,
void *  CallBackRef 
)

This function sets the handler that will be called when an event (interrupt) occurs in the driver.

The purpose of the handler is to allow application specific processing to be performed.

Parameters
InstancePtris a pointer to the XUartLite instance.
FuncPtris the pointer to the callback function.
CallBackRefis the upper layer callback reference passed back when the callback function is invoked.
Returns
None.
Note
There is no assert on the CallBackRef since the driver doesn't know what it is (nor should it)

Referenced by UartLiteIntrExample().

void XUartLite_SetSendHandler ( XUartLite InstancePtr,
XUartLite_Handler  FuncPtr,
void *  CallBackRef 
)

This function sets the handler that will be called when an event (interrupt) occurs in the driver.

The purpose of the handler is to allow application specific processing to be performed.

Parameters
InstancePtris a pointer to the XUartLite instance .
FuncPtris the pointer to the callback function.
CallBackRefis the upper layer callback reference passed back when the callback function is invoked.
Returns
None.
Note
There is no assert on the CallBackRef since the driver doesn't know what it is (nor should it)

Referenced by UartLiteIntrExample().

Variable Documentation

XUartLite_Config XUartLite_ConfigTable[XPAR_XUARTLITE_NUM_INSTANCES]
Initial value:
=
{
{
XPAR_UARTLITE_0_DEVICE_ID,
XPAR_UARTLITE_0_BASEADDR,
XPAR_UARTLITE_0_BAUDRATE,
XPAR_UARTLITE_0_USE_PARITY,
XPAR_UARTLITE_0_ODD_PARITY,
XPAR_UARTLITE_0_DATA_BITS
},
}

The configuration table for UART Lite devices.

XUartLite_Config XUartLite_ConfigTable[]

The configuration table for UART Lite devices.