uartns550
Vitis Drivers API Documentation
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Overview

Data Structures

struct  XUartNs550_Config
 Contains configuration information for the device. More...
 
struct  XUartNs550Buffer
 Manages buffers for sending and receiving data in interrupt mode. More...
 
struct  XUartNs550Format
 Holds the data format settings for the device. More...
 
struct  XUartNs550Stats
 UART statistics counters. More...
 
struct  XUartNs550
 XUartNs550 driver instance data. More...
 

Macros

#define XUartNs550_UpdateStats(InstancePtr, CurrentLsr)
 Updates the status based upon a specified line status register value. More...
 
#define XUN_REG_OFFSET   0x1000
 Offset from the device base address to the IP registers. More...
 
#define XUN_FIFO_SIZE   16
 Size of the transmit and receive FIFOs combined. More...
 
#define XUN_DIVISOR_BYTE_MASK   0x000000FF
 Mask for divisor byte. More...
 
#define XUartNs550_ReadReg(BaseAddress, RegOffset)   Xil_In32((BaseAddress) + (RegOffset))
 Reads a UART register. More...
 
#define XUartNs550_WriteReg(BaseAddress, RegOffset, RegisterValue)   Xil_Out32((BaseAddress) + (RegOffset), (RegisterValue))
 Writes to a UART register. More...
 
#define XUartNs550_GetLineStatusReg(BaseAddress)   XUartNs550_ReadReg((BaseAddress), XUN_LSR_OFFSET)
 Gets the UART Line Status Register. More...
 
#define XUartNs550_GetLineControlReg(BaseAddress)   XUartNs550_ReadReg((BaseAddress), XUN_LCR_OFFSET)
 Gets the UART Line Control Register. More...
 
#define XUartNs550_SetLineControlReg(BaseAddress, RegisterValue)   XUartNs550_WriteReg((BaseAddress), XUN_LCR_OFFSET, (RegisterValue))
 Sets the UART Line Control Register. More...
 
#define XUartNs550_EnableIntr(BaseAddress)
 Enables the transmit and receive interrupts of the UART. More...
 
#define XUartNs550_DisableIntr(BaseAddress)
 Disables the transmit and receive interrupts of the UART. More...
 
#define XUartNs550_IsReceiveData(BaseAddress)   (XUartNs550_GetLineStatusReg(BaseAddress) & XUN_LSR_DATA_READY)
 Determines if there is receive data in the receiver and/or FIFO. More...
 
#define XUartNs550_IsTransmitEmpty(BaseAddress)   (XUartNs550_GetLineStatusReg(BaseAddress) & XUN_LSR_TX_BUFFER_EMPTY)
 Determines if a byte of data can be sent with the transmitter. More...
 
#define XPAR_DEFAULT_BAUD_RATE   19200
 Default baud rate. More...
 

Typedefs

typedef void(* XUartNs550_Handler )(void *CallBackRef, u32 Event, unsigned int EventData)
 Defines the handler that the application must define when using interrupt mode. More...
 

Functions

int XUartNs550_CfgInitialize (XUartNs550 *InstancePtr, XUartNs550_Config *Config, UINTPTR EffectiveAddr)
 Initializes a specific XUartNs550 instance for use. More...
 
unsigned int XUartNs550_Send (XUartNs550 *InstancePtr, u8 *BufferPtr, unsigned int NumBytes)
 Sends the specified buffer of data using the UART. More...
 
unsigned int XUartNs550_Recv (XUartNs550 *InstancePtr, u8 *BufferPtr, unsigned int NumBytes)
 Attempts to receive a specified number of bytes of data from the UART. More...
 
unsigned int XUartNs550_SendBuffer (XUartNs550 *InstancePtr)
 Sends the previously specified buffer using the instance variables. More...
 
unsigned int XUartNs550_ReceiveBuffer (XUartNs550 *InstancePtr)
 Receives a buffer previously specified by setting up the instance variables of the instance. More...
 
int XUartNs550_SetBaudRate (XUartNs550 *InstancePtr, u32 BaudRate)
 Sets the baud rate for the specified UART. More...
 
int XUartNs550_Initialize (XUartNs550 *InstancePtr, UINTPTR BaseAddress)
 Initializes a specific XUartNs550 instance for use. More...
 
XUartNs550_Config * XUartNs550_LookupConfig (UINTPTR BaseAddress)
 Looks up the device configuration based on the unique device ID or base address. More...
 
int XUartNs550_SetOptions (XUartNs550 *InstancePtr, u16 Options)
 Sets the options for the specified driver instance. More...
 
u16 XUartNs550_GetOptions (XUartNs550 *InstancePtr)
 Gets the options for the specified driver instance. More...
 
int XUartNs550_SetFifoThreshold (XUartNs550 *InstancePtr, u8 TriggerLevel)
 Sets the receive FIFO trigger level. More...
 
u8 XUartNs550_GetFifoThreshold (XUartNs550 *InstancePtr)
 Gets the receive FIFO trigger level. More...
 
int XUartNs550_IsSending (XUartNs550 *InstancePtr)
 Determines if the specified UART is sending data. More...
 
u8 XUartNs550_GetLastErrors (XUartNs550 *InstancePtr)
 Returns the last errors that have occurred in the specified UART. More...
 
u8 XUartNs550_GetModemStatus (XUartNs550 *InstancePtr)
 Gets the modem status from the specified UART. More...
 
int XUartNs550_SetDataFormat (XUartNs550 *InstancePtr, XUartNs550Format *FormatPtr)
 Sets the data format for the specified UART. More...
 
void XUartNs550_GetDataFormat (XUartNs550 *InstancePtr, XUartNs550Format *FormatPtr)
 Gets the data format for the specified UART. More...
 
void XUartNs550_SetHandler (XUartNs550 *InstancePtr, XUartNs550_Handler FuncPtr, void *CallBackRef)
 Sets the handler that the driver calls on an event (interrupt). More...
 
void XUartNs550_InterruptHandler (XUartNs550 *InstancePtr)
 Handles interrupts for the 16450/16550 UART driver. More...
 
void XUartNs550_GetStats (XUartNs550 *InstancePtr, XUartNs550Stats *StatsPtr)
 Returns a snapshot of the current statistics in the area provided. More...
 
void XUartNs550_ClearStats (XUartNs550 *InstancePtr)
 Zeros the statistics for the given instance. More...
 
int XUartNs550_SelfTest (XUartNs550 *InstancePtr)
 Runs a self-test on the driver and hardware device. More...
 
void XUartNs550_SendByte (UINTPTR BaseAddress, u8 Data)
 Sends a data byte with the UART. More...
 
u8 XUartNs550_RecvByte (UINTPTR BaseAddress)
 Receives a byte from the UART. More...
 
void XUartNs550_SetBaud (UINTPTR BaseAddress, u32 InputClockHz, u32 BaudRate)
 Sets the baud rate for the UART. More...
 

Variables

XUartNs550_Config XUartNs550_ConfigTable []
 Configuration table for UART 16550/16450 devices. More...
 
XUartNs550_Config XUartNs550_ConfigTable []
 Holds the configuration entry for each UartNs550 instance. More...
 

Baud rate error tolerance

Maximum percentage error allowed between the actual baud rate generated using the specified clock and the desired baud rate.

#define XUN_MAX_BAUD_ERROR_RATE   3
 Maximum percent error allowed. More...
 

Baud rate limits

Maximum and minimum baud rates based on testing.

The hardware is capable of other baud rates.

#define XUN_NS16550_MAX_RATE   115200
 Maximum baud rate. More...
 
#define XUN_NS16550_MIN_RATE   300
 Minimum baud rate. More...
 

Configuration options

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 function of the option when in the active state.

#define XUN_OPTION_RXLINE_INTR   0x0800
 Enable status interrupt. More...
 
#define XUN_OPTION_SET_BREAK   0x0400
 Set a break condition. More...
 
#define XUN_OPTION_LOOPBACK   0x0200
 Enable local loopback. More...
 
#define XUN_OPTION_DATA_INTR   0x0100
 Enable data interrupts. More...
 
#define XUN_OPTION_MODEM_INTR   0x0080
 Enable modem interrupts. More...
 
#define XUN_OPTION_FIFOS_ENABLE   0x0040
 Enable FIFOs. More...
 
#define XUN_OPTION_RESET_TX_FIFO   0x0020
 Reset the transmit FIFO. More...
 
#define XUN_OPTION_RESET_RX_FIFO   0x0010
 Reset the receive FIFO. More...
 
#define XUN_OPTION_ASSERT_OUT2   0x0008
 Assert out2 signal. More...
 
#define XUN_OPTION_ASSERT_OUT1   0x0004
 Assert out1 signal. More...
 
#define XUN_OPTION_ASSERT_RTS   0x0002
 Assert RTS signal. More...
 
#define XUN_OPTION_ASSERT_DTR   0x0001
 Assert DTR signal. More...
 

Data format values

These constants specify the data format that may be set or retrieved with the driver.

The data format includes the number of data bits, the number of stop bits and parity.

#define XUN_FORMAT_8_BITS   3
 8 data bits More...
 
#define XUN_FORMAT_7_BITS   2
 7 data bits More...
 
#define XUN_FORMAT_6_BITS   1
 6 data bits More...
 
#define XUN_FORMAT_5_BITS   0
 5 data bits More...
 
#define XUN_FORMAT_EVEN_PARITY   2
 Even Parity. More...
 
#define XUN_FORMAT_ODD_PARITY   1
 Odd Parity. More...
 
#define XUN_FORMAT_NO_PARITY   0
 No Parity. More...
 
#define XUN_FORMAT_2_STOP_BIT   1
 2 stop bits More...
 
#define XUN_FORMAT_1_STOP_BIT   0
 1 stop bit More...
 

FIFO trigger values

These constants specify receive FIFO trigger levels which specify the number of bytes at which a receive data event (interrupt) occurs.

#define XUN_FIFO_TRIGGER_14   0xC0
 14 byte trigger level More...
 
#define XUN_FIFO_TRIGGER_08   0x80
 8 byte trigger level More...
 
#define XUN_FIFO_TRIGGER_04   0x40
 4 byte trigger level More...
 
#define XUN_FIFO_TRIGGER_01   0x00
 1 byte trigger level More...
 

Modem status values

These constants specify the modem status that may be retrieved from the driver.

#define XUN_MODEM_DCD_DELTA_MASK   0x08
 DCD signal changed state. More...
 
#define XUN_MODEM_DSR_DELTA_MASK   0x02
 DSR signal changed state. More...
 
#define XUN_MODEM_CTS_DELTA_MASK   0x01
 CTS signal changed state. More...
 
#define XUN_MODEM_RINGING_MASK   0x40
 Ring signal is active. More...
 
#define XUN_MODEM_DSR_MASK   0x20
 Current state of DSR signal. More...
 
#define XUN_MODEM_CTS_MASK   0x10
 Current state of CTS signal. More...
 
#define XUN_MODEM_DCD_MASK   0x80
 Current state of DCD signal. More...
 
#define XUN_MODEM_RING_STOP_MASK   0x04
 Ringing has stopped. More...
 

Callback events

These constants specify the handler events that are passed to a handler from the driver.

These constants are not bit masks such that only one is passed at a time to the handler.

#define XUN_EVENT_RECV_DATA   1
 Data has been received. More...
 
#define XUN_EVENT_RECV_TIMEOUT   2
 A receive timeout occurred. More...
 
#define XUN_EVENT_SENT_DATA   3
 Data has been sent. More...
 
#define XUN_EVENT_RECV_ERROR   4
 A receive error was detected. More...
 
#define XUN_EVENT_MODEM   5
 A change in modem status. More...
 

Error values

These constants specify the errors that may be retrieved from the driver using the XUartNs550_GetLastErrors function.

All of them are bit masks, except no error, such that multiple errors may be specified.

#define XUN_ERROR_BREAK_MASK   0x10
 Break detected. More...
 
#define XUN_ERROR_FRAMING_MASK   0x08
 Receive framing error. More...
 
#define XUN_ERROR_PARITY_MASK   0x04
 Receive parity error. More...
 
#define XUN_ERROR_OVERRUN_MASK   0x02
 Receive overrun error. More...
 
#define XUN_ERROR_NONE   0x00
 No error. More...
 

Register Map

Register offsets for the 16450/16550 compatible UART device.

#define XUN_RBR_OFFSET   (XUN_REG_OFFSET)
 Receive buffer, read only. More...
 
#define XUN_THR_OFFSET   (XUN_REG_OFFSET)
 Transmit holding register. More...
 
#define XUN_IER_OFFSET   (XUN_REG_OFFSET + 0x04)
 Interrupt enable. More...
 
#define XUN_IIR_OFFSET   (XUN_REG_OFFSET + 0x08)
 Interrupt id, read only. More...
 
#define XUN_FCR_OFFSET   (XUN_REG_OFFSET + 0x08)
 Fifo control, write only. More...
 
#define XUN_LCR_OFFSET   (XUN_REG_OFFSET + 0x0C)
 Line Control Register. More...
 
#define XUN_MCR_OFFSET   (XUN_REG_OFFSET + 0x10)
 Modem Control Register. More...
 
#define XUN_LSR_OFFSET   (XUN_REG_OFFSET + 0x14)
 Line Status Register. More...
 
#define XUN_MSR_OFFSET   (XUN_REG_OFFSET + 0x18)
 Modem Status Register. More...
 
#define XUN_DLL_OFFSET   (XUN_REG_OFFSET + 0x00)
 Divisor Register LSB. More...
 
#define XUN_DLM_OFFSET   (XUN_REG_OFFSET + 0x04)
 Divisor Register MSB. More...
 
#define XUN_DRLS_OFFSET   (XUN_REG_OFFSET + 0x00)
 Divisor Register LSB. More...
 
#define XUN_DRLM_OFFSET   (XUN_REG_OFFSET + 0x04)
 Divisor Register MSB. More...
 

Interrupt Enable Register (IER) masks

#define XUN_IER_MODEM_STATUS   0x00000008
 Modem status interrupt. More...
 
#define XUN_IER_RX_LINE   0x00000004
 Receive status interrupt. More...
 
#define XUN_IER_TX_EMPTY   0x00000002
 Transmitter empty interrupt. More...
 
#define XUN_IER_RX_DATA   0x00000001
 Receiver data available. More...
 

Interrupt ID Register (INT_ID) masks

#define XUN_INT_ID_MASK   0x0000000F
 Only the interrupt ID. More...
 
#define XUN_INT_ID_FIFOS_ENABLED   0x000000C0
 Only the FIFOs enable. More...
 

FIFO Control Register masks

#define XUN_FIFO_RX_TRIG_MSB   0x00000080
 Trigger level MSB. More...
 
#define XUN_FIFO_RX_TRIG_LSB   0x00000040
 Trigger level LSB. More...
 
#define XUN_FIFO_TX_RESET   0x00000004
 Reset the transmit FIFO. More...
 
#define XUN_FIFO_RX_RESET   0x00000002
 Reset the receive FIFO. More...
 
#define XUN_FIFO_ENABLE   0x00000001
 Enable the FIFOs. More...
 
#define XUN_FIFO_RX_TRIGGER   0x000000C0
 Both trigger level bits. More...
 

Line Control Register(LCR) masks

#define XUN_LCR_DLAB   0x00000080
 Divisor latch access. More...
 
#define XUN_LCR_SET_BREAK   0x00000040
 Cause a break condition. More...
 
#define XUN_LCR_STICK_PARITY   0x00000020
 Stick Parity. More...
 
#define XUN_LCR_EVEN_PARITY   0x00000010
 1 = even, 0 = odd parity More...
 
#define XUN_LCR_ENABLE_PARITY   0x00000008
 1 = Enable, 0 = Disable parity More...
 
#define XUN_LCR_2_STOP_BITS   0x00000004
 1= 2 stop bits,0 = 1 stop bit More...
 
#define XUN_LCR_8_DATA_BITS   0x00000003
 8 Data bits selection More...
 
#define XUN_LCR_7_DATA_BITS   0x00000002
 7 Data bits selection More...
 
#define XUN_LCR_6_DATA_BITS   0x00000001
 6 Data bits selection More...
 
#define XUN_LCR_LENGTH_MASK   0x00000003
 Both length bits mask. More...
 
#define XUN_LCR_PARITY_MASK   0x00000018
 Both parity bits mask. More...
 

Mode Control Register(MCR) masks

#define XUN_MCR_LOOP   0x00000010
 Local loopback. More...
 
#define XUN_MCR_OUT_2   0x00000008
 General output 2 signal. More...
 
#define XUN_MCR_OUT_1   0x00000004
 General output 1 signal. More...
 
#define XUN_MCR_RTS   0x00000002
 RTS signal. More...
 
#define XUN_MCR_DTR   0x00000001
 DTR signal. More...
 

Line Status Register(LSR) masks

#define XUN_LSR_RX_FIFO_ERROR   0x00000080
 An errored byte is in FIFO. More...
 
#define XUN_LSR_TX_EMPTY   0x00000040
 Transmitter is empty. More...
 
#define XUN_LSR_TX_BUFFER_EMPTY   0x00000020
 Transmit holding reg empty. More...
 
#define XUN_LSR_BREAK_INT   0x00000010
 Break detected interrupt. More...
 
#define XUN_LSR_FRAMING_ERROR   0x00000008
 Framing error on current byte. More...
 
#define XUN_LSR_PARITY_ERROR   0x00000004
 Parity error on current byte. More...
 
#define XUN_LSR_OVERRUN_ERROR   0x00000002
 Overrun error on receive FIFO. More...
 
#define XUN_LSR_DATA_READY   0x00000001
 Receive data ready. More...
 
#define XUN_LSR_ERROR_BREAK   0x0000001E
 Errors except FIFO error and break detected. More...
 

Options table size

#define XUN_NUM_OPTIONS   (sizeof(OptionsTable) / sizeof(Mapping))
 Number of entries in OptionsTable. More...
 

Self-test constants

#define XUN_TOTAL_BYTES   32
 Total bytes used in loopback self-test. More...
 

Macro Definition Documentation

#define XPAR_DEFAULT_BAUD_RATE   19200

Default baud rate.

Referenced by XUartNs550_Initialize().

#define XUartNs550_DisableIntr (   BaseAddress)
Value:
XUartNs550_ReadReg((BaseAddress), XUN_IER_OFFSET) & \
#define XUartNs550_WriteReg(BaseAddress, RegOffset, RegisterValue)
Writes to a UART register.
Definition: xuartns550_l.h:242
#define XUN_IER_TX_EMPTY
Transmitter empty interrupt.
Definition: xuartns550_l.h:114
#define XUN_IER_RX_LINE
Receive status interrupt.
Definition: xuartns550_l.h:112
#define XUN_IER_OFFSET
Interrupt enable.
Definition: xuartns550_l.h:73
#define XUN_IER_RX_DATA
Receiver data available.
Definition: xuartns550_l.h:116
#define XUartNs550_ReadReg(BaseAddress, RegOffset)
Reads a UART register.
Definition: xuartns550_l.h:225

Disables the transmit and receive interrupts of the UART.

Parameters
[in]BaseAddressBase address of the device.
Note
C-Style signature: void XUartNs550_DisableIntr(u32 BaseAddress);
#define XUartNs550_EnableIntr (   BaseAddress)
Value:
XUartNs550_ReadReg((BaseAddress), XUN_IER_OFFSET) | \
#define XUartNs550_WriteReg(BaseAddress, RegOffset, RegisterValue)
Writes to a UART register.
Definition: xuartns550_l.h:242
#define XUN_IER_TX_EMPTY
Transmitter empty interrupt.
Definition: xuartns550_l.h:114
#define XUN_IER_RX_LINE
Receive status interrupt.
Definition: xuartns550_l.h:112
#define XUN_IER_OFFSET
Interrupt enable.
Definition: xuartns550_l.h:73
#define XUN_IER_RX_DATA
Receiver data available.
Definition: xuartns550_l.h:116
#define XUartNs550_ReadReg(BaseAddress, RegOffset)
Reads a UART register.
Definition: xuartns550_l.h:225

Enables the transmit and receive interrupts of the UART.

Parameters
[in]BaseAddressBase address of the device.
Note
C-Style signature: void XUartNs550_EnableIntr(u32 BaseAddress);
#define XUartNs550_GetLineControlReg (   BaseAddress)    XUartNs550_ReadReg((BaseAddress), XUN_LCR_OFFSET)

Gets the UART Line Control Register.

Parameters
[in]BaseAddressBase address of the device.
Returns
The value read from the register.
Note
C-Style signature: u32 XUartNs550_GetLineControlReg(u32 BaseAddress);

Referenced by XUartNs550_GetDataFormat(), XUartNs550_SetBaud(), XUartNs550_SetBaudRate(), and XUartNs550_SetDataFormat().

#define XUartNs550_GetLineStatusReg (   BaseAddress)    XUartNs550_ReadReg((BaseAddress), XUN_LSR_OFFSET)

Gets the UART Line Status Register.

Parameters
[in]BaseAddressBase address of the device.
Returns
The value read from the register.
Note
C-Style signature: u32 XUartNs550_GetLineStatusReg(u32 BaseAddress);

Referenced by XUartNs550_IsSending(), XUartNs550_ReceiveBuffer(), XUartNs550_SelfTest(), and XUartNs550_SendBuffer().

#define XUartNs550_IsReceiveData (   BaseAddress)    (XUartNs550_GetLineStatusReg(BaseAddress) & XUN_LSR_DATA_READY)

Determines if there is receive data in the receiver and/or FIFO.

Parameters
[in]BaseAddressBase address of the device.
Returns
TRUE if there is receive data, FALSE otherwise.
Note
C-Style signature: int XUartNs550_IsReceiveData(u32 BaseAddress);

Referenced by XUartNs550_RecvByte().

#define XUartNs550_IsTransmitEmpty (   BaseAddress)    (XUartNs550_GetLineStatusReg(BaseAddress) & XUN_LSR_TX_BUFFER_EMPTY)

Determines if a byte of data can be sent with the transmitter.

Parameters
[in]BaseAddressBase address of the device.
Returns
TRUE if a byte can be sent, FALSE otherwise.
Note
C-Style signature: int XUartNs550_IsTransmitEmpty(u32 BaseAddress);

Referenced by XUartNs550_SendByte().

#define XUartNs550_ReadReg (   BaseAddress,
  RegOffset 
)    Xil_In32((BaseAddress) + (RegOffset))

Reads a UART register.

Parameters
[in]BaseAddressBase address of the device.
[in]RegOffsetOffset from the 1st register of the device to select the specific register.
Returns
The value read from the register.
Note
C-Style signature: u32 XUartNs550_ReadReg(u32 BaseAddress, u32 RegOffset);

Referenced by XUartNs550_GetModemStatus(), XUartNs550_GetOptions(), XUartNs550_InterruptHandler(), XUartNs550_ReceiveBuffer(), XUartNs550_Recv(), XUartNs550_RecvByte(), XUartNs550_SelfTest(), XUartNs550_Send(), XUartNs550_SendBuffer(), and XUartNs550_SetOptions().

#define XUartNs550_SetLineControlReg (   BaseAddress,
  RegisterValue 
)    XUartNs550_WriteReg((BaseAddress), XUN_LCR_OFFSET, (RegisterValue))

Sets the UART Line Control Register.

Parameters
[in]BaseAddressBase address of the device.
[in]RegisterValueValue to write to the register.
Note
C-Style signature: void XUartNs550_SetLineControlReg(u32 BaseAddress, u32 RegisterValue);

Referenced by XUartNs550_CfgInitialize(), XUartNs550_LowLevelExample(), XUartNs550_SetBaud(), XUartNs550_SetBaudRate(), and XUartNs550_SetDataFormat().

#define XUartNs550_UpdateStats (   InstancePtr,
  CurrentLsr 
)
Value:
{ \
InstancePtr->LastErrors |= CurrentLsr; \
\
if (CurrentLsr & XUN_LSR_OVERRUN_ERROR) { \
InstancePtr->Stats.ReceiveOverrunErrors++; \
} \
if (CurrentLsr & XUN_LSR_PARITY_ERROR) { \
InstancePtr->Stats.ReceiveParityErrors++; \
} \
if (CurrentLsr & XUN_LSR_FRAMING_ERROR) { \
InstancePtr->Stats.ReceiveFramingErrors++; \
} \
if (CurrentLsr & XUN_LSR_BREAK_INT) { \
InstancePtr->Stats.ReceiveBreakDetected++; \
} \
}
#define XUN_LSR_FRAMING_ERROR
Framing error on current byte.
Definition: xuartns550_l.h:193
#define XUN_LSR_PARITY_ERROR
Parity error on current byte.
Definition: xuartns550_l.h:195
#define XUN_LSR_OVERRUN_ERROR
Overrun error on receive FIFO.
Definition: xuartns550_l.h:197
#define XUN_LSR_BREAK_INT
Break detected interrupt.
Definition: xuartns550_l.h:191

Updates the status based upon a specified line status register value.

The stats that are updated are based upon bits in this register. It also keeps the last errors instance variable updated. It allows common processing between the modules of the component with less overhead than a function in the required module.

Parameters
[in]InstancePtrPointer to the XUartNs550 instance.
[in]CurrentLsrLine Status Register value to be used for the update.
Note
C-Style signature: void XUartNs550_UpdateStats(XUartNs550 *InstancePtr, u8 CurrentLsr)

Referenced by XUartNs550_ReceiveBuffer().

#define XUartNs550_WriteReg (   BaseAddress,
  RegOffset,
  RegisterValue 
)    Xil_Out32((BaseAddress) + (RegOffset), (RegisterValue))

Writes to a UART register.

Parameters
[in]BaseAddressBase address of the device.
[in]RegOffsetOffset from the 1st register of the device to select the specific register.
[in]RegisterValueValue to write to the register.
Note
C-Style signature: u32 XUartNs550_WriteReg(u32 BaseAddress, u32 RegOffset, u32 RegisterValue);

Referenced by XUartNs550_CfgInitialize(), XUartNs550_LowLevelExample(), XUartNs550_Recv(), XUartNs550_SelfTest(), XUartNs550_Send(), XUartNs550_SendBuffer(), XUartNs550_SendByte(), XUartNs550_SetBaud(), XUartNs550_SetBaudRate(), XUartNs550_SetFifoThreshold(), and XUartNs550_SetOptions().

#define XUN_DIVISOR_BYTE_MASK   0x000000FF

Mask for divisor byte.

Referenced by XUartNs550_SetBaud(), and XUartNs550_SetBaudRate().

#define XUN_DLL_OFFSET   (XUN_REG_OFFSET + 0x00)

Divisor Register LSB.

Referenced by XUartNs550_SetBaud(), and XUartNs550_SetBaudRate().

#define XUN_DLM_OFFSET   (XUN_REG_OFFSET + 0x04)

Divisor Register MSB.

Referenced by XUartNs550_SetBaud(), and XUartNs550_SetBaudRate().

#define XUN_DRLM_OFFSET   (XUN_REG_OFFSET + 0x04)

Divisor Register MSB.

#define XUN_DRLS_OFFSET   (XUN_REG_OFFSET + 0x00)

Divisor Register LSB.

#define XUN_ERROR_BREAK_MASK   0x10

Break detected.

#define XUN_ERROR_FRAMING_MASK   0x08

Receive framing error.

#define XUN_ERROR_NONE   0x00

No error.

#define XUN_ERROR_OVERRUN_MASK   0x02

Receive overrun error.

#define XUN_ERROR_PARITY_MASK   0x04

Receive parity error.

#define XUN_EVENT_MODEM   5

A change in modem status.

#define XUN_EVENT_RECV_DATA   1

Data has been received.

Referenced by UartNs550IntrHandler().

#define XUN_EVENT_RECV_ERROR   4

A receive error was detected.

Referenced by UartNs550IntrHandler().

#define XUN_EVENT_RECV_TIMEOUT   2

A receive timeout occurred.

Referenced by UartNs550IntrHandler().

#define XUN_EVENT_SENT_DATA   3

Data has been sent.

Referenced by UartNs550IntrHandler().

#define XUN_FIFO_ENABLE   0x00000001
#define XUN_FIFO_RX_RESET   0x00000002

Reset the receive FIFO.

#define XUN_FIFO_RX_TRIG_LSB   0x00000040

Trigger level LSB.

#define XUN_FIFO_RX_TRIG_MSB   0x00000080

Trigger level MSB.

Referenced by XUartNs550_CfgInitialize().

#define XUN_FIFO_RX_TRIGGER   0x000000C0

Both trigger level bits.

Referenced by XUartNs550_GetFifoThreshold(), and XUartNs550_SetFifoThreshold().

#define XUN_FIFO_SIZE   16

Size of the transmit and receive FIFOs combined.

Includes the transmitter and receiver, so it is the total number of bytes that the UART can buffer.

Referenced by XUartNs550_SendBuffer().

#define XUN_FIFO_TRIGGER_01   0x00

1 byte trigger level

Referenced by XUartNs550_SetFifoThreshold().

#define XUN_FIFO_TRIGGER_04   0x40

4 byte trigger level

Referenced by XUartNs550_SetFifoThreshold().

#define XUN_FIFO_TRIGGER_08   0x80

8 byte trigger level

Referenced by XUartNs550_SetFifoThreshold().

#define XUN_FIFO_TRIGGER_14   0xC0

14 byte trigger level

Referenced by XUartNs550_SetFifoThreshold().

#define XUN_FIFO_TX_RESET   0x00000004

Reset the transmit FIFO.

#define XUN_FORMAT_1_STOP_BIT   0
#define XUN_FORMAT_2_STOP_BIT   1

2 stop bits

Referenced by XUartNs550_GetDataFormat(), and XUartNs550_SetDataFormat().

#define XUN_FORMAT_5_BITS   0

5 data bits

#define XUN_FORMAT_6_BITS   1

6 data bits

#define XUN_FORMAT_7_BITS   2

7 data bits

#define XUN_FORMAT_8_BITS   3

8 data bits

Referenced by XUartNs550_CfgInitialize(), and XUartNs550_SetDataFormat().

#define XUN_FORMAT_EVEN_PARITY   2

Even Parity.

Referenced by XUartNs550_GetDataFormat(), and XUartNs550_SetDataFormat().

#define XUN_FORMAT_NO_PARITY   0
#define XUN_FORMAT_ODD_PARITY   1

Odd Parity.

Referenced by XUartNs550_GetDataFormat().

#define XUN_IER_MODEM_STATUS   0x00000008

Modem status interrupt.

#define XUN_IER_OFFSET   (XUN_REG_OFFSET + 0x04)
#define XUN_IER_RX_DATA   0x00000001

Receiver data available.

Referenced by XUartNs550_SendBuffer().

#define XUN_IER_RX_LINE   0x00000004

Receive status interrupt.

#define XUN_IER_TX_EMPTY   0x00000002

Transmitter empty interrupt.

Referenced by XUartNs550_Send(), and XUartNs550_SendBuffer().

#define XUN_IIR_OFFSET   (XUN_REG_OFFSET + 0x08)

Interrupt id, read only.

Referenced by XUartNs550_InterruptHandler(), and XUartNs550_SendBuffer().

#define XUN_INT_ID_FIFOS_ENABLED   0x000000C0

Only the FIFOs enable.

Referenced by XUartNs550_SendBuffer().

#define XUN_INT_ID_MASK   0x0000000F

Only the interrupt ID.

Referenced by XUartNs550_InterruptHandler().

#define XUN_LCR_2_STOP_BITS   0x00000004

1= 2 stop bits,0 = 1 stop bit

Referenced by XUartNs550_GetDataFormat(), and XUartNs550_SetDataFormat().

#define XUN_LCR_6_DATA_BITS   0x00000001

6 Data bits selection

#define XUN_LCR_7_DATA_BITS   0x00000002

7 Data bits selection

#define XUN_LCR_8_DATA_BITS   0x00000003

8 Data bits selection

Referenced by XUartNs550_LowLevelExample().

#define XUN_LCR_DLAB   0x00000080

Divisor latch access.

Referenced by XUartNs550_SetBaud(), and XUartNs550_SetBaudRate().

#define XUN_LCR_ENABLE_PARITY   0x00000008

1 = Enable, 0 = Disable parity

Referenced by XUartNs550_GetDataFormat(), and XUartNs550_SetDataFormat().

#define XUN_LCR_EVEN_PARITY   0x00000010

1 = even, 0 = odd parity

Referenced by XUartNs550_GetDataFormat(), and XUartNs550_SetDataFormat().

#define XUN_LCR_LENGTH_MASK   0x00000003

Both length bits mask.

Referenced by XUartNs550_GetDataFormat(), and XUartNs550_SetDataFormat().

#define XUN_LCR_OFFSET   (XUN_REG_OFFSET + 0x0C)

Line Control Register.

#define XUN_LCR_PARITY_MASK   0x00000018

Both parity bits mask.

Referenced by XUartNs550_SetDataFormat().

#define XUN_LCR_SET_BREAK   0x00000040

Cause a break condition.

#define XUN_LCR_STICK_PARITY   0x00000020

Stick Parity.

#define XUN_LSR_BREAK_INT   0x00000010

Break detected interrupt.

Referenced by XUartNs550_ReceiveBuffer().

#define XUN_LSR_DATA_READY   0x00000001

Receive data ready.

Referenced by XUartNs550_ReceiveBuffer(), and XUartNs550_SelfTest().

#define XUN_LSR_ERROR_BREAK   0x0000001E

Errors except FIFO error and break detected.

Referenced by XUartNs550_GetLastErrors().

#define XUN_LSR_FRAMING_ERROR   0x00000008

Framing error on current byte.

#define XUN_LSR_OFFSET   (XUN_REG_OFFSET + 0x14)

Line Status Register.

#define XUN_LSR_OVERRUN_ERROR   0x00000002

Overrun error on receive FIFO.

#define XUN_LSR_PARITY_ERROR   0x00000004

Parity error on current byte.

#define XUN_LSR_RX_FIFO_ERROR   0x00000080

An errored byte is in FIFO.

#define XUN_LSR_TX_BUFFER_EMPTY   0x00000020

Transmit holding reg empty.

Referenced by XUartNs550_SendBuffer().

#define XUN_LSR_TX_EMPTY   0x00000040

Transmitter is empty.

Referenced by XUartNs550_IsSending(), and XUartNs550_SendBuffer().

#define XUN_MAX_BAUD_ERROR_RATE   3

Maximum percent error allowed.

Referenced by XUartNs550_SetBaudRate().

#define XUN_MCR_DTR   0x00000001

DTR signal.

#define XUN_MCR_LOOP   0x00000010

Local loopback.

Referenced by XUartNs550_SelfTest().

#define XUN_MCR_OFFSET   (XUN_REG_OFFSET + 0x10)

Modem Control Register.

Referenced by XUartNs550_SelfTest().

#define XUN_MCR_OUT_1   0x00000004

General output 1 signal.

#define XUN_MCR_OUT_2   0x00000008

General output 2 signal.

#define XUN_MCR_RTS   0x00000002

RTS signal.

#define XUN_MODEM_CTS_DELTA_MASK   0x01

CTS signal changed state.

#define XUN_MODEM_CTS_MASK   0x10

Current state of CTS signal.

#define XUN_MODEM_DCD_DELTA_MASK   0x08

DCD signal changed state.

#define XUN_MODEM_DCD_MASK   0x80

Current state of DCD signal.

#define XUN_MODEM_DSR_DELTA_MASK   0x02

DSR signal changed state.

#define XUN_MODEM_DSR_MASK   0x20

Current state of DSR signal.

#define XUN_MODEM_RING_STOP_MASK   0x04

Ringing has stopped.

#define XUN_MODEM_RINGING_MASK   0x40

Ring signal is active.

#define XUN_MSR_OFFSET   (XUN_REG_OFFSET + 0x18)

Modem Status Register.

Referenced by XUartNs550_GetModemStatus().

#define XUN_NS16550_MAX_RATE   115200

Maximum baud rate.

#define XUN_NS16550_MIN_RATE   300

Minimum baud rate.

#define XUN_NUM_OPTIONS   (sizeof(OptionsTable) / sizeof(Mapping))

Number of entries in OptionsTable.

Referenced by XUartNs550_GetOptions(), and XUartNs550_SetOptions().

#define XUN_OPTION_ASSERT_DTR   0x0001

Assert DTR signal.

#define XUN_OPTION_ASSERT_OUT1   0x0004

Assert out1 signal.

#define XUN_OPTION_ASSERT_OUT2   0x0008

Assert out2 signal.

#define XUN_OPTION_ASSERT_RTS   0x0002

Assert RTS signal.

#define XUN_OPTION_DATA_INTR   0x0100

Enable data interrupts.

Referenced by UartNs550IntrExample().

#define XUN_OPTION_FIFOS_ENABLE   0x0040

Enable FIFOs.

Referenced by UartNs550IntrExample(), and UartNs550PolledExample().

#define XUN_OPTION_LOOPBACK   0x0200

Enable local loopback.

Referenced by UartNs550IntrExample(), and UartNs550PolledExample().

#define XUN_OPTION_MODEM_INTR   0x0080

Enable modem interrupts.

#define XUN_OPTION_RESET_RX_FIFO   0x0010

Reset the receive FIFO.

#define XUN_OPTION_RESET_TX_FIFO   0x0020

Reset the transmit FIFO.

#define XUN_OPTION_RXLINE_INTR   0x0800

Enable status interrupt.

#define XUN_OPTION_SET_BREAK   0x0400

Set a break condition.

#define XUN_RBR_OFFSET   (XUN_REG_OFFSET)

Receive buffer, read only.

Referenced by XUartNs550_ReceiveBuffer(), and XUartNs550_RecvByte().

#define XUN_REG_OFFSET   0x1000

Offset from the device base address to the IP registers.

#define XUN_THR_OFFSET   (XUN_REG_OFFSET)

Transmit holding register.

Referenced by XUartNs550_SendBuffer(), and XUartNs550_SendByte().

#define XUN_TOTAL_BYTES   32

Total bytes used in loopback self-test.

Referenced by XUartNs550_SelfTest().

Typedef Documentation

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

Defines the handler that the application must define when using interrupt mode.

The handler is called from the driver in an interrupt context to handle application specific processing.

Parameters
[in]CallBackRefCallback reference passed in by the upper layer when setting the handler, and is passed back to the upper layer when the handler is called.
[in]EventOne of the event constants indicating why the handler is being called.
[in]EventDataNumber 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 XUartNs550_CfgInitialize ( XUartNs550 *  InstancePtr,
XUartNs550_Config *  Config,
UINTPTR  EffectiveAddr 
)

Initializes a specific XUartNs550 instance for use.

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. If the device has FIFOs (16550), they are enabled and the a receive FIFO threshold is set for 8 bytes. The default operating mode of the driver is polled mode.

Parameters
[out]InstancePtrPointer to the XUartNs550 instance.
[in]ConfigReference to a structure containing information about a specific UART 16450/16550 device. XUartNs550_Init initializes an InstancePtr object for a specific device specified by the contents of Config. XUartNs550_Init can initialize multiple instance objects with the use of multiple calls giving different Config information on each call.
[in]EffectiveAddrDevice 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 parameter, passing the physical address instead.
Returns
  • XST_SUCCESS if initialization was successful.
  • XST_UART_BAUD_ERROR if the baud rate is not possible because the input clock frequency is not divisible with an acceptable amount of error.

References XUartNs550::BaseAddress, XUartNs550_Config::DefaultBaudRate, XUartNs550::Handler, XUartNs550_Config::InputClockHz, XUartNs550::InputClockHz, XUartNs550::IsReady, XUartNs550Buffer::NextBytePtr, XUartNs550::ReceiveBuffer, XUartNs550Buffer::RemainingBytes, XUartNs550Buffer::RequestedBytes, XUartNs550::SendBuffer, XUartNs550_ClearStats(), XUartNs550_SetBaudRate(), XUartNs550_SetLineControlReg, XUartNs550_WriteReg, XUN_FCR_OFFSET, XUN_FIFO_ENABLE, XUN_FIFO_RX_TRIG_MSB, and XUN_FORMAT_8_BITS.

Referenced by XUartNs550_Initialize().

void XUartNs550_GetDataFormat ( XUartNs550 *  InstancePtr,
XUartNs550Format *  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
[in]InstancePtrPointer to the XUartNs550 instance.
[out]FormatPtrPointer to a format structure that contains the data format after this call completes.

References XUartNs550::BaseAddress, XUartNs550Format::BaudRate, XUartNs550::BaudRate, XUartNs550Format::DataBits, XUartNs550::IsReady, XUartNs550Format::Parity, XUartNs550Format::StopBits, XUartNs550_GetLineControlReg, XUN_FORMAT_1_STOP_BIT, XUN_FORMAT_2_STOP_BIT, XUN_FORMAT_EVEN_PARITY, XUN_FORMAT_NO_PARITY, XUN_FORMAT_ODD_PARITY, XUN_LCR_2_STOP_BITS, XUN_LCR_ENABLE_PARITY, XUN_LCR_EVEN_PARITY, and XUN_LCR_LENGTH_MASK.

u8 XUartNs550_GetFifoThreshold ( XUartNs550 *  InstancePtr)

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
[in]InstancePtrPointer to the XUartNs550 instance.
Returns
The current receive FIFO trigger level. Constants which define each trigger level are contained in the file xuartns550.h and named XUN_FIFO_TRIGGER_*.

References XUartNs550::BaseAddress, XUartNs550::IsReady, and XUN_FIFO_RX_TRIGGER.

u8 XUartNs550_GetLastErrors ( XUartNs550 *  InstancePtr)

Returns the last errors that have occurred in the specified UART.

It also clears the errors such that they cannot be retrieved again. The errors include parity error, receive overrun error, framing error, and break detection.

The last errors is an accumulation of the errors each time an error is discovered in the driver. A status is checked for each received byte and this status is accumulated in the last errors.

If this function is called after receiving a buffer of data, it indicates any errors that occurred for the bytes of the buffer. It does not indicate which bytes contained errors.

Parameters
[in,out]InstancePtrPointer to the XUartNs550 instance.
Returns
The last errors that occurred. The errors are bit masks that are contained in the file xuartns550.h and named XUN_ERROR_*.

References XUartNs550::LastErrors, and XUN_LSR_ERROR_BREAK.

Referenced by UartNs550IntrHandler().

u8 XUartNs550_GetModemStatus ( XUartNs550 *  InstancePtr)

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
[in]InstancePtrPointer to the XUartNs550 instance.
Returns
The modem status which are bit masks that are contained in the file xuartns550.h and named XUN_MODEM_*.
Note
The bit masks used for the modem status are the exact bits of the modem status register with no abstraction.

References XUartNs550::BaseAddress, XUartNs550_ReadReg, and XUN_MSR_OFFSET.

u16 XUartNs550_GetOptions ( XUartNs550 *  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 simultaneously.

Parameters
[in]InstancePtrPointer to the XUartNs550 instance.
Returns
The current options for the UART. The options are bit masks that are contained in the file xuartns550.h and named XUN_OPTION_*.

References XUartNs550::BaseAddress, XUartNs550::IsReady, XUartNs550_ReadReg, XUN_FCR_OFFSET, and XUN_NUM_OPTIONS.

Referenced by UartNs550IntrExample(), and UartNs550PolledExample().

void XUartNs550_GetStats ( XUartNs550 *  InstancePtr,
XUartNs550Stats *  StatsPtr 
)
int XUartNs550_Initialize ( XUartNs550 *  InstancePtr,
UINTPTR  BaseAddress 
)

Initializes a specific XUartNs550 instance for use.

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 XPAR_DEFAULT_BAUD_RATE if the symbol is defined, otherwise it is set to 19.2K baud. If the device has FIFOs (16550), they are enabled and the a receive FIFO threshold is set for 8 bytes. The default operating mode of the driver is polled mode.

Parameters
[in]InstancePtrPointer to the XUartNs550 instance.
[in]BaseAddressBase address of the device.
Returns
  • XST_SUCCESS if initialization was successful.
  • XST_DEVICE_NOT_FOUND if the device ID/BaseAddress could not be found in the configuration table.
  • XST_UART_BAUD_ERROR if the baud rate is not possible because the input clock frequency is not divisible with an acceptable amount of error.
Note
In XSCT/classic flow, DeviceId is used to look up the device configuration.

References XUartNs550_Config::BaseAddress, XUartNs550_Config::DefaultBaudRate, XPAR_DEFAULT_BAUD_RATE, XUartNs550_CfgInitialize(), and XUartNs550_LookupConfig().

Referenced by UartNs550HelloWorldExample(), UartNs550IntrExample(), UartNs550PolledExample(), and UartNs550SelfTestExample().

void XUartNs550_InterruptHandler ( XUartNs550 *  InstancePtr)

Handles interrupts for the 16450/16550 UART driver.

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

Parameters
[in]InstancePtrPointer to the instance of the UART that the interrupt is for.

References XUartNs550::BaseAddress, XUartNs550_ReadReg, XUN_IIR_OFFSET, and XUN_INT_ID_MASK.

Referenced by UartNs550IntrExample().

int XUartNs550_IsSending ( XUartNs550 *  InstancePtr)

Determines if the specified UART is sending data.

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

Parameters
[in]InstancePtrPointer to the XUartNs550 instance.
Returns
A value of TRUE if the UART is sending data, otherwise FALSE.

References XUartNs550::BaseAddress, XUartNs550_GetLineStatusReg, and XUN_LSR_TX_EMPTY.

XUartNs550_Config * XUartNs550_LookupConfig ( UINTPTR  BaseAddress)

Looks up the device configuration based on the unique device ID or base address.

The XUartNs550_ConfigTable[] contains the configuration info for each device in the system.

Parameters
[in]BaseAddressBase address of the device.
Returns
A pointer to the configuration found or NULL if the specified device ID/BaseAddress was not found. See xuartns550.h for the definition of XUartNs550_Config.
Note
In XSCT/classic flow, DeviceId is used to look up the device configuration.

References XUartNs550_Config::Name, and XUartNs550_ConfigTable.

Referenced by UartNs550IntrExample(), and XUartNs550_Initialize().

unsigned int XUartNs550_ReceiveBuffer ( XUartNs550 *  InstancePtr)

Receives a buffer previously specified by setting up the instance variables of the instance.

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

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

In a polled mode, this function only receives 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 starts receiving and then the interrupt handler of the driver continues until the buffer has been received. A callback function, as specified by the application, is called to indicate the completion of receiving the buffer or when any receive errors or timeouts occur. Interrupt mode must be enabled using the SetOptions function.

Parameters
[in,out]InstancePtrPointer to the XUartNs550 instance.
Returns
The number of bytes received.

References XUartNs550::BaseAddress, XUartNs550Stats::CharactersReceived, XUartNs550Buffer::NextBytePtr, XUartNs550::ReceiveBuffer, XUartNs550Buffer::RemainingBytes, XUartNs550::Stats, XUartNs550_GetLineStatusReg, XUartNs550_ReadReg, XUartNs550_UpdateStats, XUN_LSR_BREAK_INT, XUN_LSR_DATA_READY, and XUN_RBR_OFFSET.

Referenced by XUartNs550_Recv().

unsigned int XUartNs550_Recv ( XUartNs550 *  InstancePtr,
u8 *  BufferPtr,
unsigned int  NumBytes 
)

Attempts to receive a specified number of bytes of data from the UART.

This function stores received data into the specified buffer. It is designed for either polled or interrupt driven modes. It is non-blocking such that it returns if no data has already been received by the UART.

In a polled mode, this function only receives 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 starts receiving and then the interrupt handler of the driver continues receiving data until the buffer has been received. A callback function, as specified by the application, is called to indicate the completion of receiving the buffer or when any receive errors or timeouts occur. Interrupt mode must be enabled using the SetOptions function.

Parameters
[in,out]InstancePtrPointer to the XUartNs550 instance.
[out]BufferPtrPointer to buffer to receive data into.
[in]NumBytesNumber of bytes to receive. A value of zero stops 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 XUartNs550::BaseAddress, XUartNs550::IsReady, XUartNs550Buffer::NextBytePtr, XUartNs550::ReceiveBuffer, XUartNs550Buffer::RemainingBytes, XUartNs550Buffer::RequestedBytes, XUartNs550_ReadReg, XUartNs550_ReceiveBuffer(), XUartNs550_WriteReg, and XUN_IER_OFFSET.

Referenced by UartNs550IntrExample(), UartNs550PolledExample(), and XUartNs550_SelfTest().

u8 XUartNs550_RecvByte ( UINTPTR  BaseAddress)

Receives a byte from the UART.

It operates in a polling mode and blocks until a byte of data is received.

Parameters
[in]BaseAddressBase address of the UART.
Returns
The data byte received by the UART.

References XUartNs550_IsReceiveData, XUartNs550_ReadReg, and XUN_RBR_OFFSET.

Referenced by XUartNs550_LowLevelExample().

int XUartNs550_SelfTest ( XUartNs550 *  InstancePtr)

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 statistics are cleared at the end of the test. The time for this test to execute is proportional to the baud rate that has been set prior to calling this function.

Parameters
[in]InstancePtrPointer to the XUartNs550 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.

References XUartNs550::BaseAddress, XUartNs550::IsReady, XUartNs550_ClearStats(), XUartNs550_GetLineStatusReg, XUartNs550_ReadReg, XUartNs550_Recv(), XUartNs550_Send(), XUartNs550_WriteReg, XUN_IER_OFFSET, XUN_LSR_DATA_READY, XUN_MCR_LOOP, XUN_MCR_OFFSET, and XUN_TOTAL_BYTES.

Referenced by UartNs550IntrExample(), UartNs550PolledExample(), and UartNs550SelfTestExample().

unsigned int XUartNs550_Send ( XUartNs550 *  InstancePtr,
u8 *  BufferPtr,
unsigned int  NumBytes 
)

Sends the specified buffer of data using the UART.

This function operates in either polled or interrupt driven modes. It is non-blocking such that it returns before the data has been sent by the UART. If the UART is busy sending data, it returns and indicates zero bytes were sent.

In a polled mode, this function only sends 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 starts sending the specified buffer and then the interrupt handler of the driver continues sending data until the buffer has been sent. A callback function, as specified by the application, is called to indicate the completion of sending the buffer.

Parameters
[in,out]InstancePtrPointer to the XUartNs550 instance.
[in]BufferPtrPointer to a buffer of data to send.
[in]NumBytesNumber of bytes to send. A value of zero stops a previous send operation that is in progress in interrupt mode. Any data that was already put into the transmit FIFO is 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.

This function and the XUartNs550_SetOptions() function modify shared data such that there may be a need for mutual exclusion in a multithreaded environment and when XUartNs550_SetOptions() is called from a handler.

References XUartNs550::BaseAddress, XUartNs550::IsReady, XUartNs550Buffer::NextBytePtr, XUartNs550Buffer::RemainingBytes, XUartNs550Buffer::RequestedBytes, XUartNs550::SendBuffer, XUartNs550_ReadReg, XUartNs550_SendBuffer(), XUartNs550_WriteReg, XUN_IER_OFFSET, and XUN_IER_TX_EMPTY.

Referenced by UartNs550HelloWorldExample(), UartNs550IntrExample(), UartNs550PolledExample(), and XUartNs550_SelfTest().

unsigned int XUartNs550_SendBuffer ( XUartNs550 *  InstancePtr)

Sends the previously specified buffer using the instance variables.

This function is designed to be an internal function for the XUartNs550 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. It is non-blocking such that it returns before the data has been sent by the UART.

In a polled mode, this function only sends 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 starts sending the specified buffer and then the interrupt handler of the driver continues until the buffer has been sent. A callback function, as specified by the application, is called to indicate the completion of sending the buffer.

Parameters
[in,out]InstancePtrPointer to the XUartNs550 instance.
Returns
NumBytes is the number of bytes actually sent (put into the UART transmitter and/or FIFO).

References XUartNs550::BaseAddress, XUartNs550Stats::CharactersTransmitted, XUartNs550Buffer::NextBytePtr, XUartNs550Buffer::RemainingBytes, XUartNs550::SendBuffer, XUartNs550::Stats, XUartNs550_GetLineStatusReg, XUartNs550_ReadReg, XUartNs550_WriteReg, XUN_FIFO_SIZE, XUN_IER_OFFSET, XUN_IER_RX_DATA, XUN_IER_TX_EMPTY, XUN_IIR_OFFSET, XUN_INT_ID_FIFOS_ENABLED, XUN_LSR_TX_BUFFER_EMPTY, XUN_LSR_TX_EMPTY, and XUN_THR_OFFSET.

Referenced by XUartNs550_Send().

void XUartNs550_SendByte ( UINTPTR  BaseAddress,
u8  Data 
)

Sends a data byte with the UART.

This function operates in the polling mode and blocks until the data has been put into the UART transmit holding register.

Parameters
[in]BaseAddressBase address of the UART.
[in]DataData byte to send.

References XUartNs550_IsTransmitEmpty, XUartNs550_WriteReg, and XUN_THR_OFFSET.

Referenced by XUartNs550_LowLevelExample().

void XUartNs550_SetBaud ( UINTPTR  BaseAddress,
u32  InputClockHz,
u32  BaudRate 
)

Sets the baud rate for the UART.

Parameters
[in]BaseAddressBase address of the UART.
[in]InputClockHzFrequency of the input clock to the device in Hertz.
[in]BaudRateBaud rate to set.

References XUartNs550_GetLineControlReg, XUartNs550_SetLineControlReg, XUartNs550_WriteReg, XUN_DIVISOR_BYTE_MASK, XUN_DLL_OFFSET, XUN_DLM_OFFSET, and XUN_LCR_DLAB.

Referenced by XUartNs550_LowLevelExample().

int XUartNs550_SetBaudRate ( XUartNs550 *  InstancePtr,
u32  BaudRate 
)

Sets the baud rate for the specified UART.

Checks the input value for validity and also verifies that the requested rate can be configured to within the 3 percent error range for RS-232 communications. If the provided rate is not valid, the current setting is unchanged.

This function is designed to be an internal function only used within the XUartNs550 component. It is necessary for initialization and for the application-facing function that sets the data format.

Parameters
[in,out]InstancePtrPointer to the XUartNs550 instance.
[in]BaudRateBaud rate to set in the hardware.
Returns
  • XST_SUCCESS if everything configures as expected.
  • XST_UART_BAUD_ERROR if the requested rate is not available because there was too much error due to the input clock.

References XUartNs550::BaseAddress, XUartNs550::BaudRate, XUartNs550::InputClockHz, XUartNs550::IsReady, XUartNs550_GetLineControlReg, XUartNs550_SetLineControlReg, XUartNs550_WriteReg, XUN_DIVISOR_BYTE_MASK, XUN_DLL_OFFSET, XUN_DLM_OFFSET, XUN_LCR_DLAB, and XUN_MAX_BAUD_ERROR_RATE.

Referenced by XUartNs550_CfgInitialize(), and XUartNs550_SetDataFormat().

int XUartNs550_SetDataFormat ( XUartNs550 *  InstancePtr,
XUartNs550Format *  FormatPtr 
)

Sets the data format for the specified UART.

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
[in]InstancePtrPointer to the XUartNs550 instance.
[in]FormatPtrPointer 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 that is a bug with the GNU PowerPC compiler. The asserts in this function cause a warning if these fields are bytes.

The baud rates tested include: 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200.

References XUartNs550::BaseAddress, XUartNs550Format::BaudRate, XUartNs550Format::DataBits, XUartNs550Format::Parity, XUartNs550Format::StopBits, XUartNs550_GetLineControlReg, XUartNs550_SetBaudRate(), XUartNs550_SetLineControlReg, XUN_FORMAT_1_STOP_BIT, XUN_FORMAT_2_STOP_BIT, XUN_FORMAT_8_BITS, XUN_FORMAT_EVEN_PARITY, XUN_FORMAT_NO_PARITY, XUN_LCR_2_STOP_BITS, XUN_LCR_ENABLE_PARITY, XUN_LCR_EVEN_PARITY, XUN_LCR_LENGTH_MASK, and XUN_LCR_PARITY_MASK.

int XUartNs550_SetFifoThreshold ( XUartNs550 *  InstancePtr,
u8  TriggerLevel 
)

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. The FIFOs must be enabled to set the trigger level.

Parameters
[in]InstancePtrPointer to the XUartNs550 instance.
[in]TriggerLevelTrigger level to set. Constants which define each trigger level are contained in the file xuartns550.h and named XUN_FIFO_TRIGGER_*.
Returns
  • XST_SUCCESS if the trigger level was set.
  • XST_UART_CONFIG_ERROR if the trigger level could not be set, either the hardware does not support the FIFOs or FIFOs are not enabled.

References XUartNs550::BaseAddress, XUartNs550::IsReady, XUartNs550_WriteReg, XUN_FCR_OFFSET, XUN_FIFO_ENABLE, XUN_FIFO_RX_TRIGGER, XUN_FIFO_TRIGGER_01, XUN_FIFO_TRIGGER_04, XUN_FIFO_TRIGGER_08, and XUN_FIFO_TRIGGER_14.

void XUartNs550_SetHandler ( XUartNs550 *  InstancePtr,
XUartNs550_Handler  FuncPtr,
void *  CallBackRef 
)

Sets the handler that the driver calls on an event (interrupt).

The handler allows application-specific processing.

Parameters
[in,out]InstancePtrPointer to the XUartNs550 instance.
[in]FuncPtrPointer to the callback function.
[in]CallBackRefUpper layer callback reference passed back when the callback function is invoked.
Note
There is no assert on the CallBackRef since the driver does not know what it is (nor should it)

References XUartNs550::CallBackRef, XUartNs550::Handler, and XUartNs550::IsReady.

Referenced by UartNs550IntrExample().

int XUartNs550_SetOptions ( XUartNs550 *  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
[in]InstancePtrPointer to the XUartNs550 instance.
[in]OptionsOptions to set which are bit masks contained in the file xuartns550.h and named XUN_OPTION_*.
Returns
  • XST_SUCCESS if the options were set successfully.
  • XST_UART_CONFIG_ERROR if the options could not be set because the hardware does not support FIFOs.

References XUartNs550::BaseAddress, XUartNs550::IsReady, XUartNs550_ReadReg, XUartNs550_WriteReg, XUN_FCR_OFFSET, and XUN_NUM_OPTIONS.

Referenced by UartNs550IntrExample(), and UartNs550PolledExample().

Variable Documentation

XUartNs550_Config XUartNs550_ConfigTable[]
Initial value:
=
{
{
XPAR_UARTNS550_0_DEVICE_ID,
XPAR_UARTNS550_0_BASEADDR,
XPAR_UARTNS550_0_CLOCK_HZ
}
}

Configuration table for UART 16550/16450 devices.

Holds the configuration entry for each UartNs550 instance.

Each device in the system should have an entry in this table.

Referenced by XUartNs550_LookupConfig().

XUartNs550_Config XUartNs550_ConfigTable[]

Holds the configuration entry for each UartNs550 instance.

Holds the configuration entry for each UartNs550 instance.

Each device in the system should have an entry in this table.

Referenced by XUartNs550_LookupConfig().