Software Drivers

xuartps.h File Reference

#include "xil_types.h"
#include "xil_assert.h"
#include "xstatus.h"
#include "xuartps_hw.h"

Classes

struct  XUartPs_Config
struct  XUartPsBuffer
struct  XUartPsFormat
struct  XUartPs

Defines

#define XUARTPS_H
#define XUARTPS_MAX_RATE   921600
#define XUARTPS_MIN_RATE   110
#define XUARTPS_DFT_BAUDRATE   115200
#define XUartPs_GetChannelStatus(InstancePtr)   Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_SR_OFFSET)
#define XUartPs_GetModeControl(InstancePtr)   Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_CR_OFFSET)
#define XUartPs_SetModeControl(InstancePtr, RegisterValue)
#define XUartPs_EnableUart(InstancePtr)
#define XUartPs_DisableUart(InstancePtr)
#define XUartPs_IsTransmitEmpty(InstancePtr)
Configuration options



#define XUARTPS_OPTION_SET_BREAK   0x0080
#define XUARTPS_OPTION_STOP_BREAK   0x0040
#define XUARTPS_OPTION_RESET_TMOUT   0x0020
#define XUARTPS_OPTION_RESET_TX   0x0010
#define XUARTPS_OPTION_RESET_RX   0x0008
#define XUARTPS_OPTION_ASSERT_RTS   0x0004
#define XUARTPS_OPTION_ASSERT_DTR   0x0002
#define XUARTPS_OPTION_SET_FCM   0x0001
Channel Operational Mode

The UART can operate in one of four modes: Normal, Local Loopback, Remote Loopback, or automatic echo.



#define XUARTPS_OPER_MODE_NORMAL   0x00
#define XUARTPS_OPER_MODE_AUTO_ECHO   0x01
#define XUARTPS_OPER_MODE_LOCAL_LOOP   0x02
#define XUARTPS_OPER_MODE_REMOTE_LOOP   0x03
Data format values

These constants specify the data format that the driver supports. The data format includes the number of data bits, the number of stop bits and parity.



#define XUARTPS_FORMAT_8_BITS   0
#define XUARTPS_FORMAT_7_BITS   2
#define XUARTPS_FORMAT_6_BITS   3
#define XUARTPS_FORMAT_NO_PARITY   4
#define XUARTPS_FORMAT_MARK_PARITY   3
#define XUARTPS_FORMAT_SPACE_PARITY   2
#define XUARTPS_FORMAT_ODD_PARITY   1
#define XUARTPS_FORMAT_EVEN_PARITY   0
#define XUARTPS_FORMAT_2_STOP_BIT   2
#define XUARTPS_FORMAT_1_5_STOP_BIT   1
#define XUARTPS_FORMAT_1_STOP_BIT   0
Callback events

These constants specify the handler events that an application can handle using its specific handler function. Note that these constants are not bit mask, so only one event can be passed to an application at a time.



#define XUARTPS_EVENT_RECV_DATA   1
#define XUARTPS_EVENT_RECV_TOUT   2
#define XUARTPS_EVENT_SENT_DATA   3
#define XUARTPS_EVENT_RECV_ERROR   4
#define XUARTPS_EVENT_MODEM   5

Typedefs

typedef void(* XUartPs_Handler )(void *CallBackRef, u32 Event, unsigned int EventData)

Functions

XUartPs_ConfigXUartPs_LookupConfig (u16 DeviceId)
int XUartPs_CfgInitialize (XUartPs *InstancePtr, XUartPs_Config *Config, u32 EffectiveAddr)
unsigned int XUartPs_Send (XUartPs *InstancePtr, u8 *BufferPtr, unsigned int NumBytes)
unsigned int XUartPs_Recv (XUartPs *InstancePtr, u8 *BufferPtr, unsigned int NumBytes)
int XUartPs_SetBaudRate (XUartPs *InstancePtr, u32 BaudRate)
void XUartPs_SetOptions (XUartPs *InstancePtr, u16 Options)
u16 XUartPs_GetOptions (XUartPs *InstancePtr)
void XUartPs_SetFifoThreshold (XUartPs *InstancePtr, u8 TriggerLevel)
u8 XUartPs_GetFifoThreshold (XUartPs *InstancePtr)
u16 XUartPs_GetModemStatus (XUartPs *InstancePtr)
u32 XUartPs_IsSending (XUartPs *InstancePtr)
u8 XUartPs_GetOperMode (XUartPs *InstancePtr)
void XUartPs_SetOperMode (XUartPs *InstancePtr, u8 OperationMode)
u8 XUartPs_GetFlowDelay (XUartPs *InstancePtr)
void XUartPs_SetFlowDelay (XUartPs *InstancePtr, u8 FlowDelayValue)
u8 XUartPs_GetRecvTimeout (XUartPs *InstancePtr)
void XUartPs_SetRecvTimeout (XUartPs *InstancePtr, u8 RecvTimeout)
int XUartPs_SetDataFormat (XUartPs *InstancePtr, XUartPsFormat *Format)
void XUartPs_GetDataFormat (XUartPs *InstancePtr, XUartPsFormat *Format)
u32 XUartPs_GetInterruptMask (XUartPs *InstancePtr)
void XUartPs_SetInterruptMask (XUartPs *InstancePtr, u32 Mask)
void XUartPs_InterruptHandler (XUartPs *InstancePtr)
void XUartPs_SetHandler (XUartPs *InstancePtr, XUartPs_Handler FuncPtr, void *CallBackRef)
int XUartPs_SelfTest (XUartPs *InstancePtr)

Detailed Description


Define Documentation

#define XUARTPS_DFT_BAUDRATE   115200
#define XUartPs_DisableUart ( InstancePtr   ) 
Value:
Xil_Out32(((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET), \
          (((Xil_In32((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET)) & \
          ~XUARTPS_CR_EN_DIS_MASK) | (XUARTPS_CR_RX_DIS | XUARTPS_CR_TX_DIS)))

Disable the transmitter and receiver of the UART.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
None.
Note:
C-Style signature: void XUartPs_DisableUart(XUartPs *InstancePtr)
#define XUartPs_EnableUart ( InstancePtr   ) 
Value:
Xil_Out32(((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET), \
          ((Xil_In32((InstancePtr)->Config.BaseAddress + XUARTPS_CR_OFFSET) & \
          ~XUARTPS_CR_EN_DIS_MASK) | (XUARTPS_CR_RX_EN | XUARTPS_CR_TX_EN)))

Enable the transmitter and receiver of the UART.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
None.
Note:
C-Style signature: void XUartPs_EnableUart(XUartPs *InstancePtr)
#define XUARTPS_EVENT_MODEM   5

Modem status changed

#define XUARTPS_EVENT_RECV_DATA   1

Data receiving done

#define XUARTPS_EVENT_RECV_ERROR   4

A receive error detected

#define XUARTPS_EVENT_RECV_TOUT   2

A receive timeout occurred

#define XUARTPS_EVENT_SENT_DATA   3

Data transmission done

#define XUARTPS_FORMAT_1_5_STOP_BIT   1

1.5 stop bits

#define XUARTPS_FORMAT_1_STOP_BIT   0

1 stop bit

#define XUARTPS_FORMAT_2_STOP_BIT   2

2 stop bits

#define XUARTPS_FORMAT_6_BITS   3

6 data bits

#define XUARTPS_FORMAT_7_BITS   2

7 data bits

#define XUARTPS_FORMAT_8_BITS   0

8 data bits

#define XUARTPS_FORMAT_EVEN_PARITY   0

Even parity

#define XUARTPS_FORMAT_MARK_PARITY   3

Mark parity

#define XUARTPS_FORMAT_NO_PARITY   4

No parity

#define XUARTPS_FORMAT_ODD_PARITY   1

Odd parity

#define XUARTPS_FORMAT_SPACE_PARITY   2

parity

#define XUartPs_GetChannelStatus ( InstancePtr   )     Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_SR_OFFSET)

Get the UART Channel Status Register.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
The value read from the register.
Note:
C-Style signature: u16 XUartPs_GetChannelStatus(XUartPs *InstancePtr)
#define XUartPs_GetModeControl ( InstancePtr   )     Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_CR_OFFSET)

Get the UART Mode Control Register.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
The value read from the register.
Note:
C-Style signature: u32 XUartPs_GetControl(XUartPs *InstancePtr)
#define XUARTPS_H
#define XUartPs_IsTransmitEmpty ( InstancePtr   ) 
Value:
((Xil_In32(((InstancePtr)->Config.BaseAddress) + XUARTPS_SR_OFFSET) & \
         XUARTPS_SR_TXEMPTY) == XUARTPS_SR_TXEMPTY)

Determine if the transmitter FIFO is empty.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
  • TRUE if a byte can be sent
  • FALSE if the Transmitter Fifo is not empty
Note:
C-Style signature: u32 XUartPs_IsTransmitEmpty(XUartPs InstancePtr)
#define XUARTPS_MAX_RATE   921600
#define XUARTPS_MIN_RATE   110
#define XUARTPS_OPER_MODE_AUTO_ECHO   0x01

Auto Echo Mode

#define XUARTPS_OPER_MODE_LOCAL_LOOP   0x02

Local Loopback Mode

#define XUARTPS_OPER_MODE_NORMAL   0x00

Normal Mode

#define XUARTPS_OPER_MODE_REMOTE_LOOP   0x03

Remote Loopback Mode

#define XUARTPS_OPTION_ASSERT_DTR   0x0002

Assert the DTR bit

#define XUARTPS_OPTION_ASSERT_RTS   0x0004

Assert the RTS bit

#define XUARTPS_OPTION_RESET_RX   0x0008

Reset the receiver

#define XUARTPS_OPTION_RESET_TMOUT   0x0020

Reset the receive timeout

#define XUARTPS_OPTION_RESET_TX   0x0010

Reset the transmitter

#define XUARTPS_OPTION_SET_BREAK   0x0080

These constants specify the options that may be set or retrieved with the driver, each is a unique bit mask such that multiple options may be specified. These constants indicate the available options in active state. Starts break transmission

#define XUARTPS_OPTION_SET_FCM   0x0001

Turn on flow control mode

#define XUARTPS_OPTION_STOP_BREAK   0x0040

Stops break transmission

#define XUartPs_SetModeControl ( InstancePtr,
RegisterValue   ) 
Value:
Xil_Out32(((InstancePtr)->Config.BaseAddress) + XUARTPS_CR_OFFSET, \
                        (RegisterValue))

Set the UART Mode Control Register.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
RegisterValue is the value to be written to the register.
Returns:
None.
Note:
C-Style signature: void XUartPs_SetModeControl(XUartPs *InstancePtr, u16 RegisterValue)

Typedef Documentation

typedef void(* XUartPs_Handler)(void *CallBackRef, u32 Event, unsigned int EventData)

This data type defines a handler that an application defines to communicate with interrupt system to retrieve state information about an application.

Parameters:
CallBackRef is a callback reference passed in by the upper layer when setting the handler, and is passed back to the upper layer when the handler is called. It is used to find the device driver instance.
Event contains one of the event constants indicating events that have occurred.
EventData contains the number of bytes sent or received at the time of the call for send and receive events and contains the modem status for modem events.

Function Documentation

int XUartPs_CfgInitialize ( XUartPs InstancePtr,
XUartPs_Config Config,
u32  EffectiveAddr 
)

Initializes a specific XUartPs instance such that it is ready to be used. The data format of the device is setup for 8 data bits, 1 stop bit, and no parity by default. The baud rate is set to a default value specified by Config->DefaultBaudRate if set, otherwise it is set to 19.2K baud. The receive FIFO threshold is set for 8 bytes. The default operating mode of the driver is polled mode.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Config is a reference to a structure containing information about a specific XUartPs driver.
EffectiveAddr is 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, pass in the physical address instead.
Returns:
  • XST_SUCCESS if initialization was successful
  • XST_UART_BAUD_ERROR if the baud rate is not possible because the inputclock frequency is not divisible with an acceptable amount of error
Note:

The default configuration for the UART after initialization is:

  • 19,200 bps or XPAR_DFT_BAUDRATE if defined
  • 8 data bits
  • 1 stop bit
  • no parity
  • FIFO's are enabled with a receive threshold of 8 bytes
  • The RX timeout is enabled with a timeout of 1 (4 char times)

All interrupts are disabled.

void XUartPs_GetDataFormat ( XUartPs InstancePtr,
XUartPsFormat FormatPtr 
)

Gets the data format for the specified UART. The data format includes the baud rate, number of data bits, number of stop bits, and parity.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
FormatPtr is a pointer to a format structure that will contain the data format after this call completes.
Returns:
None.
Note:
None.
u8 XUartPs_GetFifoThreshold ( XUartPs InstancePtr  ) 

This function gets the receive FIFO trigger level. The receive trigger level indicates the number of bytes in the receive FIFO that cause a receive data event (interrupt) to be generated.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
The current receive FIFO trigger level. This is a value from 0-31.
Note:
None.
u8 XUartPs_GetFlowDelay ( XUartPs InstancePtr  ) 

This function sets the Flow Delay. 0 - 3: Flow delay inactive 4 - 32: If Flow Control mode is enabled, UART_rtsN is deactivated when the receive FIFO fills to this level.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:

The Flow Delay is specified by constants defined in xuartps_hw.h. The constants are named XUARTPS_FLOWDEL*

Note:
None.
u32 XUartPs_GetInterruptMask ( XUartPs InstancePtr  ) 

This function gets the interrupt mask

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
The current interrupt mask. The mask indicates which interupts are enabled.
Note:
None.
u16 XUartPs_GetModemStatus ( XUartPs InstancePtr  ) 

This function gets the modem status from the specified UART. The modem status indicates any changes of the modem signals. This function allows the modem status to be read in a polled mode. The modem status is updated whenever it is read such that reading it twice may not yield the same results.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:

The modem status which are bit masks that are contained in the file xuartps.h and named XUARTPS_MODEM_*.

Note:

The bit masks used for the modem status are the exact bits of the modem status register with no abstraction.

u8 XUartPs_GetOperMode ( XUartPs InstancePtr  ) 

This function gets the operational mode of the UART. The UART can operate in one of four modes: Normal, Local Loopback, Remote Loopback, or automatic echo.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:

The operational mode is specified by constants defined in xuartps.h. The constants are named XUARTPS_OPER_MODE_*

Note:
None.
u16 XUartPs_GetOptions ( XUartPs InstancePtr  ) 

Gets the options for the specified driver instance. The options are implemented as bit masks such that multiple options may be enabled or disabled simulataneously.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:

The current options for the UART. The optionss are bit masks that are contained in the file xuartps.h and named XUARTPS_OPTION_*.

Note:
None.
u8 XUartPs_GetRecvTimeout ( XUartPs InstancePtr  ) 

This function gets the Receive Timeout of the UART.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
The current setting for receive time out.
Note:
None.
void XUartPs_InterruptHandler ( XUartPs InstancePtr  ) 

This function is the interrupt handler for the driver. It must be connected to an interrupt system by the application such that it can be called when an interrupt occurs.

Parameters:
InstancePtr contains a pointer to the driver instance
Returns:
None.
Note:
None.
u32 XUartPs_IsSending ( XUartPs InstancePtr  ) 

This function determines if the specified UART is sending data.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Returns:
  • TRUE if the UART is sending data
  • FALSE if UART is not sending data
Note:
None.
XUartPs_Config* XUartPs_LookupConfig ( u16  DeviceId  ) 

Looks up the device configuration based on the unique device ID. The table contains the configuration info for each device in the system.

Parameters:
DeviceId contains the ID of the device
Returns:
A pointer to the configuration structure or NULL if the specified device is not in the system.
Note:
None.
unsigned int XUartPs_Recv ( XUartPs InstancePtr,
u8 *  BufferPtr,
unsigned int  NumBytes 
)

This function attempts to receive a specified number of bytes of data from the device and store it into the specified buffer. This function works for both polled or interrupt driven modes. It is non-blocking.

In a polled mode, this function will only receive the data already in the RX FIFO. The application may need to call it repeatedly to receive the entire buffer. Polled mode is the default mode of operation for the device.

In interrupt mode, this function will start the receiving, if not the entire buffer has been received, the interrupt handler will continue receiving data until the entire buffer has been received. A callback function, as specified by the application, will be called to indicate the completion of the receiving or error conditions.

Parameters:
InstancePtr is a pointer to the XUartPs instance
BufferPtr is pointer to buffer for data to be received into
NumBytes is 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.

int XUartPs_SelfTest ( XUartPs InstancePtr  ) 

This function runs a self-test on the driver and hardware device. This self test performs a local loopback and verifies data can be sent and received.

The time for this test is proportional to the baud rate that has been set prior to calling this function.

The mode and control registers are restored before return.

Parameters:
InstancePtr is a pointer to the XUartPs instance
Returns:
  • XST_SUCCESS if the test was successful
  • XST_UART_TEST_FAIL if the test failed looping back the data
Note:

This function can hang if the hardware is not functioning properly.

unsigned int XUartPs_Send ( XUartPs InstancePtr,
u8 *  BufferPtr,
unsigned int  NumBytes 
)

This functions sends the specified buffer using the device in either polled or interrupt driven mode. This function is non-blocking, if the device is busy sending data, it will return and indicate zero bytes were sent. Otherwise, it fills the TX FIFO as much as it can, and return the number of bytes sent.

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

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

Parameters:
InstancePtr is a pointer to the XUartPs instance.
BufferPtr is pointer to a buffer of data to be sent.
NumBytes contains 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.

int XUartPs_SetBaudRate ( XUartPs InstancePtr,
u32  BaudRate 
)

Sets the baud rate for the device. Checks the input value for validity and also verifies that the requested rate can be configured to within the maximum error range specified by XUARTPS_MAX_BAUD_ERROR_RATE. If the provided rate is not possible, the current setting is unchanged.

Parameters:
InstancePtr is a pointer to the XUartPs instance
BaudRate to be set
Returns:
  • XST_SUCCESS if everything configured as expected
  • XST_UART_BAUD_ERROR if the requested rate is not available because there was too much error
Note:
None.
int XUartPs_SetDataFormat ( XUartPs InstancePtr,
XUartPsFormat FormatPtr 
)

Sets the data format for the device. The data format includes the baud rate, number of data bits, number of stop bits, and parity. It is the caller's responsibility to ensure that the UART is not sending or receiving data when this function is called.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
FormatPtr is a pointer to a format structure containing the data format to be set.
Returns:
  • XST_SUCCESS if the data format was successfully set.
  • XST_UART_BAUD_ERROR indicates the baud rate could not be set because of the amount of error with the baud rate and the input clock frequency.
  • XST_INVALID_PARAM if one of the parameters was not valid.
Note:

The data types in the format type, data bits and parity, are 32 bit fields to prevent a compiler warning. The asserts in this function will cause a warning if these fields are bytes.

void XUartPs_SetFifoThreshold ( XUartPs InstancePtr,
u8  TriggerLevel 
)

This functions sets the receive FIFO trigger level. The receive trigger level specifies the number of bytes in the receive FIFO that cause a receive data event (interrupt) to be generated.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
TriggerLevel contains the trigger level to set.
Returns:
None
Note:
None.
void XUartPs_SetFlowDelay ( XUartPs InstancePtr,
u8  FlowDelayValue 
)

This function sets the Flow Delay. 0 - 3: Flow delay inactive 4 - 63: If Flow Control mode is enabled, UART_rtsN is deactivated when the receive FIFO fills to this level.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
FlowDelayValue is the Setting for the flow delay.
Returns:
None.
Note:
None.
void XUartPs_SetHandler ( XUartPs InstancePtr,
XUartPs_Handler  FuncPtr,
void *  CallBackRef 
)

This function sets the handler that will be called when an event (interrupt) occurs that needs application's attention.

Parameters:
InstancePtr is a pointer to the XUartPs instance
FuncPtr is the pointer to the callback function.
CallBackRef is 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)

void XUartPs_SetInterruptMask ( XUartPs InstancePtr,
u32  Mask 
)

This function sets the interrupt mask.

Parameters:
InstancePtr is a pointer to the XUartPs instance
Mask contains the interrupts to be enabled or disabled. A '1' enables an interupt, and a '0' disables.
Returns:
None.
Note:
None.
void XUartPs_SetOperMode ( XUartPs InstancePtr,
u8  OperationMode 
)

This function sets the operational mode of the UART. The UART can operate in one of four modes: Normal, Local Loopback, Remote Loopback, or automatic echo.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
OperationMode is the mode of the UART.
Returns:
None.
Note:
None.
void XUartPs_SetOptions ( XUartPs InstancePtr,
u16  Options 
)

Sets the options for the specified driver instance. The options are implemented as bit masks such that multiple options may be enabled or disabled simultaneously.

The GetOptions function may be called to retrieve the currently enabled options. The result is ORed in the desired new settings to be enabled and ANDed with the inverse to clear the settings to be disabled. The resulting value is then used as the options for the SetOption function call.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
Options contains the options to be set which are bit masks contained in the file xuartps.h and named XUARTPS_OPTION_*.
Returns:
None.
Note:
None.
void XUartPs_SetRecvTimeout ( XUartPs InstancePtr,
u8  RecvTimeout 
)

This function sets the Receive Timeout of the UART.

Parameters:
InstancePtr is a pointer to the XUartPs instance.
RecvTimeout setting allows the UART to detect an idle connection on the reciever data line. Timeout duration = RecvTimeout x 4 x Bit Period. 0 disables the timeout function.
Returns:
None.
Note:
None.