### Xilinx Processor IP Library

<hl>Software Drivers</hl>

Main Page | Data Structures | File List | Data Fields | Globals

# xuartns550.h File Reference

## Detailed Description

## Data Structures

struct | XUartNs550_Config
struct | XUartNs550Buffer
struct | XUartNs550Format
struct | XUartNs550Stats
struct | XUartNs550

## Configuration options

#define | XUN_OPTION_RXLINE_INTR
#define | XUN_OPTION_SET_BREAK
#define | XUN_OPTION_LOOPBACK
#define | XUN_OPTION_DATA_INTR
#define | XUN_OPTION_MODEM_INTR
#define | XUN_OPTION_FIFOS_ENABLE
#define | XUN_OPTION_RESET_TX_FIFO
#define | XUN_OPTION_RESET_RX_FIFO
#define | XUN_OPTION_ASSERT_OUT2
#define | XUN_OPTION_ASSERT_OUT1
#define | XUN_OPTION_ASSERT_RTS
#define | XUN_OPTION_ASSERT_DTR

## Data format values

#define | XUN_FORMAT_8_BITS
#define | XUN_FORMAT_7_BITS
#define | XUN_FORMAT_6_BITS
#define | XUN_FORMAT_5_BITS
#define | XUN_FORMAT_EVEN_PARITY
#define | XUN_FORMAT_ODD_PARITY
#define | XUN_FORMAT_NO_PARITY
#define | XUN_FORMAT_2_STOP_BIT
#define | XUN_FORMAT_1_STOP_BIT

## FIFO trigger values

#define | XUN_FIFO_TRIGGER_14
#define | XUN_FIFO_TRIGGER_08
#define | XUN_FIFO_TRIGGER_04
#define | XUN_FIFO_TRIGGER_01

## Modem status values

#define | XUN_MODEM_DCD_DELTA_MASK
#define | XUN_MODEM_DSR_DELTA_MASK
#define | XUN_MODEM_CTS_DELTA_MASK
#define | XUN_MODEM_RINGING_MASK
#define | XUN_MODEM_DSR_MASK
#define | XUN_MODEM_CTS_MASK
#define | XUN_MODEM_DCD_MASK
#define | XUN_MODEM_RING_STOP_MASK

## Callback events

#define | XUN_EVENT_RECV_DATA
#define | XUN_EVENT_RECV_TIMEOUT
#define | XUN_EVENT_SENT_DATA
#define | XUN_EVENT_RECV_ERROR
#define | XUN_EVENT_MODEM

## Error values

#define | XUN_ERROR_BREAK_MASK
#define | XUN_ERROR_FRAMING_MASK
#define | XUN_ERROR_PARITY_MASK
#define | XUN_ERROR_OVERRUN_MASK
#define | XUN_ERROR_NONE

## Typedefs

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

## Functions

int | XUartNs550_Initialize (XUartNs550 *InstancePtr, u16 DeviceId)
XUartNs550_Config * | XUartNs550_LookupConfig (u16 DeviceId)
int | XUartNs550_CfgInitialize (XUartNs550 *InstancePtr, XUartNs550_Config *Config, u32 EffectiveAddr)
unsigned int | XUartNs550_Send (XUartNs550 *InstancePtr, u8 *BufferPtr, unsigned int NumBytes)
unsigned int | XUartNs550_Recv (XUartNs550 *InstancePtr, u8 *BufferPtr, unsigned int NumBytes)
int | XUartNs550_SetOptions (XUartNs550 *InstancePtr, u16 Options)
u16 | XUartNs550_GetOptions (XUartNs550 *InstancePtr)
int | XUartNs550_SetFifoThreshold (XUartNs550 *InstancePtr, u8 TriggerLevel)
u8 | XUartNs550_GetFifoThreshold (XUartNs550 *InstancePtr)
int | XUartNs550_IsSending (XUartNs550 *InstancePtr)
u8 | XUartNs550_GetLastErrors (XUartNs550 *InstancePtr)
u8 | XUartNs550_GetModemStatus (XUartNs550 *InstancePtr)
int | XUartNs550_SetDataFormat (XUartNs550 *InstancePtr, XUartNs550Format *Format)
void | XUartNs550_GetDataFormat (XUartNs550 *InstancePtr, XUartNs550Format *Format)
void | XUartNs550_SetHandler (XUartNs550 *InstancePtr, XUartNs550_Handler FuncPtr, void *CallBackRef)
void | XUartNs550_InterruptHandler (XUartNs550 *InstancePtr)
void | XUartNs550_GetStats (XUartNs550 *InstancePtr, XUartNs550Stats *StatsPtr)
void | XUartNs550_ClearStats (XUartNs550 *InstancePtr)
int | XUartNs550_SelfTest (XUartNs550 *InstancePtr)

## Define Documentation

#define XUN_ERROR_BREAK_MASK

| Break detected

#define XUN_ERROR_FRAMING_MASK

| Receive framing error

#define XUN_ERROR_NONE

| No error

#define XUN_ERROR_OVERRUN_MASK

| Receive overrun error

#define XUN_ERROR_PARITY_MASK

| Receive parity error

#define XUN_EVENT_MODEM

| A change in modem status

#define XUN_EVENT_RECV_DATA

| Data has been received

#define XUN_EVENT_RECV_ERROR

| A receive error was detected

#define XUN_EVENT_RECV_TIMEOUT

| A receive timeout occurred

#define XUN_EVENT_SENT_DATA

| Data has been sent

#define XUN_FIFO_TRIGGER_01

| 1 byte trigger level

#define XUN_FIFO_TRIGGER_04

| 4 byte trigger level

#define XUN_FIFO_TRIGGER_08

| 8 byte trigger level

#define XUN_FIFO_TRIGGER_14

| 14 byte trigger level

#define XUN_FORMAT_1_STOP_BIT

| 1 stop bit

#define XUN_FORMAT_2_STOP_BIT

| 2 stop bits

#define XUN_FORMAT_5_BITS

| 5 data bits

#define XUN_FORMAT_6_BITS

| 6 data bits

#define XUN_FORMAT_7_BITS

| 7 data bits

#define XUN_FORMAT_8_BITS

| 8 data bits

#define XUN_FORMAT_EVEN_PARITY

| Even Parity

#define XUN_FORMAT_NO_PARITY

| No Parity

#define XUN_FORMAT_ODD_PARITY

| Odd Parity

#define XUN_MODEM_CTS_DELTA_MASK

| CTS signal changed state

#define XUN_MODEM_CTS_MASK

| Current state of CTS signal

#define XUN_MODEM_DCD_DELTA_MASK

| DCD signal changed state

#define XUN_MODEM_DCD_MASK

| Current state of DCD signal

#define XUN_MODEM_DSR_DELTA_MASK

| DSR signal changed state

#define XUN_MODEM_DSR_MASK

| Current state of DSR signal

#define XUN_MODEM_RING_STOP_MASK

| Ringing has stopped

#define XUN_MODEM_RINGING_MASK

| Ring signal is active

#define XUN_OPTION_ASSERT_DTR

| Assert DTR signal

#define XUN_OPTION_ASSERT_OUT1

| Assert out1 signal

#define XUN_OPTION_ASSERT_OUT2

| Assert out2 signal

#define XUN_OPTION_ASSERT_RTS

| Assert RTS signal

#define XUN_OPTION_DATA_INTR

| Enable data interrupts

#define XUN_OPTION_FIFOS_ENABLE

| Enable FIFOs

#define XUN_OPTION_LOOPBACK

| Enable local loopback

#define XUN_OPTION_MODEM_INTR

| Enable modem interrupts

#define XUN_OPTION_RESET_RX_FIFO

| Reset the receive FIFO

#define XUN_OPTION_RESET_TX_FIFO

| Reset the transmit FIFO

#define XUN_OPTION_RXLINE_INTR

| Enable status interrupt

#define XUN_OPTION_SET_BREAK

| Set a break condition

## Typedef Documentation

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

This data type defines a handler which the application must define when using interrupt mode. The handler will be called from the driver in an interrupt context to handle application specific processing.

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.
  | Event | contains one of the event constants indicating why the handler is being called.
  | 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 XUartNs550_CfgInitialize | ( | XUartNs550 * | InstancePtr,
|  | XUartNs550_Config * | Config,
|  | u32 | EffectiveAddr
| ) |

Initializes a specific XUartNs550 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. 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:

  | InstancePtr | is a pointer to the XUartNs550 instance.
  | Config | is a reference 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 f Config. XUartNs550_Init can initialize multiple instance objects with the use of multiple calls giving different Config information on each call.

  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, use Config->BaseAddress for this parameters, 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

Note:
  None.

void XUartNs550_ClearStats | ( | XUartNs550 * | InstancePtr | ) |

This function zeros the statistics for the given instance.

Parameters:

  | InstancePtr | is a pointer to the XUartNs550 instance.

Returns:
  None.

Note:
  None.

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:

  | InstancePtr | is a pointer to the XUartNs550 instance .
  | FormatPtr | is a pointer to a format structure that will contain the data format after this call completes.

Returns:
  None.

Note:
  None.

u8 XUartNs550_GetFifoThreshold | ( | XUartNs550 * | 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 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_*.

Note:
  None.

u8 XUartNs550_GetLastErrors | ( | XUartNs550 * | InstancePtr | ) |

This function 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 will indicate any errors that occurred for the bytes of the buffer. It does not indicate which bytes contained errors.

Parameters:

  | InstancePtr | is a pointer 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_*.

Note:
  None.

u8 XUartNs550_GetModemStatus | ( | XUartNs550 * | 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 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.

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 simulataneously.

Parameters:

  | InstancePtr | is a pointer to the XUartNs550 instance.

Returns:
  The current options for the UART. The optionss are bit masks that are contained in the file xuartns550.h and named XUN_OPTION_*.

Note:
  None.

void XUartNs550_GetStats | ( | XUartNs550 * | InstancePtr,
|  | XUartNs550Stats * | StatsPtr
| ) |

This functions returns a snapshot of the current statistics in the area provided.

Parameters:

  | InstancePtr | is a pointer to the XUartNs550 instance.
  | StatsPtr | is a pointer to a XUartNs550Stats structure to where the statistics are to be copied to.

Returns:
  None.

Note:
  None.

int XUartNs550_Initialize | ( | XUartNs550 * | InstancePtr,
|  | u16 | DeviceId
| ) |

Initializes a specific XUartNs550 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 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:

  | InstancePtr | is a pointer to the XUartNs550 instance .
  | DeviceId | is the unique id of the device controlled by this XUartNs550 instance. Passing in a device id associates the generic XUartNs550 instance to a specific device, as chosen by the caller or application developer.

Returns:

- XST_SUCCESS if initialization was successful
- XST_DEVICE_NOT_FOUND if the device ID 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:
  None.

void XUartNs550_InterruptHandler | ( | XUartNs550 * | InstancePtr | ) |

This function is the interrupt handler for the 16450/16550 UART driver. It must be connected to an interrupt system by the user 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 user must ensure this occurs.

Parameters:

  | InstancePtr | contains a pointer to the instance of the UART that the interrupt is for.

Returns:
  None.

Note:
  None.

int XUartNs550_IsSending | ( | XUartNs550 * | InstancePtr | ) |

This function determines if the specified UART is sending data. If the transmitter register is not empty, it is sending data.

Parameters:

  | InstancePtr | is a pointer to the XUartNs550 instance.

Returns:
  A value of TRUE if the UART is sending data, otherwise FALSE.

Note:
  None.

XUartNs550_Config* XUartNs550_LookupConfig | ( | u16 | DeviceId | ) |

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

Parameters:

  | DeviceId | contains the ID of the device to look up the configuration for.

Returns:
  A pointer to the configuration found or NULL if the specified device ID was not found.

Note:
  None.

unsigned int XUartNs550_Recv | ( | XUartNs550 * | InstancePtr,
|  | u8 * | BufferPtr,
|  | 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, 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 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. Interrupt mode must be enabled using the SetOptions function.

Parameters:

  | InstancePtr | is a pointer to the XUartNs550 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 XUartNs550_SelfTest | ( | XUartNs550 * | InstancePtr | ) |

This functions 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:

  | InstancePtr | is a pointer 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.

unsigned int XUartNs550_Send | ( | XUartNs550 * | InstancePtr,
|  | u8 * | BufferPtr,
|  | 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, 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 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:

  | InstancePtr | is a pointer to the XUartNs550 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.
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 if XUartNs550_SetOptions() if called from a handler.

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:

  | InstancePtr | is a pointer to the XUartNs550 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 that is a bug with the GNU PowerPC compiler. The asserts in this function will cause a warning if these fields are bytes.
The baud rates tested include: 1200, 2400, 4800, 9600, 19200, 38400, 57600 and 115200.

int XUartNs550_SetFifoThreshold | ( | XUartNs550 * | 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. The FIFOs must be enabled to set the trigger level.

Parameters:

  | InstancePtr | is a pointer to the XUartNs550 instance .
  | TriggerLevel | contains the trigger 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

Note:
  None.

void XUartNs550_SetHandler | ( | XUartNs550 * | InstancePtr,
|  | XUartNs550_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:

  | InstancePtr | is a pointer to the XUartNs550 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.

There is no assert on the CallBackRef since the driver doesn't know what it is (nor should it)

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:

  | InstancePtr | is a pointer to the XUartNs550 instance.
  | Options | contains the options to be 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

Note:
  None.

Copyright © 1995-2009 Xilinx, Inc. All rights reserved.