AM263Px MCU+ SDK: APIs for UART

| AM263Px MCU+ SDK 26.00.00 |

Files | Data Structures | Functions | Typedefs
APIs for UART
APIs for SOC Specific Device Drivers

## Introduction

This module contains APIs to program and use the UART.

## Files
file | uart/v0/uart.h
| This file contains the prototype of UART driver APIs.

## Data Structures
struct | UART_Params
| UART Parameters. More...
struct | UART_Attrs
| UART instance attributes - used during init time. More...
struct | UART_Object
| UART driver object. More...
struct | UART_Config
| UART global configuration array. More...

## Functions
void | UART_init (void)
| This function initializes the UART module. More...
void | UART_deinit (void)
| This function de-initializes the UART module. More...
UART_Handle | UART_open (uint32_t index, const UART_Params *prms)
| This function opens a given UART peripheral. More...
void | UART_close (UART_Handle handle)
| Function to close a UART peripheral specified by the UART handle. More...
int32_t | UART_write (UART_Handle handle, UART_Transaction *trans)
| Function to perform UART write operation. More...
int32_t | UART_read (UART_Handle handle, UART_Transaction *trans)
| Function to perform UART read operation. More...
int32_t | UART_writeCancel (UART_Handle handle, UART_Transaction *trans)
| Function to perform UART canceling of current write transaction. More...
int32_t | UART_readCancel (UART_Handle handle, UART_Transaction *trans)
| Function to perform UART canceling of current read transaction. More...
UART_Handle | UART_getHandle (uint32_t index)
| Function to return a open'ed UART handle given a UART instance index. More...
void | UART_flushTxFifo (UART_Handle handle)
| Function to flush a TX FIFO of peripheral specified by the UART handle. More...
uint32_t | UART_getBaseAddr (UART_Handle handle)
| Function to get base address of UART instance of a particular handle. More...
void | UART_Transaction_init (UART_Transaction *trans)
| Function to initialize the UART_Transaction struct to its defaults. More...
void | UART_Params_init (UART_Params *prms)
| Function to initialize the UART_Params struct to its defaults. More...

## Typedefs
typedef struct UART_Config_s * | UART_Handle
typedef void(* | UART_CallbackFxn) (UART_Handle handle, UART_Transaction *transaction)
| The definition of a callback function used by the UART driver when used in UART_TRANSFER_MODE_CALLBACK. More...

## Transfer Mode
This determines whether the driver operates synchronously or asynchronously In UART_TRANSFER_MODE_BLOCKING mode UART_read() and UART_write() blocks code execution until the transaction has completed In UART_TRANSFER_MODE_CALLBACK UART_read() and UART_write() does not block code execution and instead calls a UART_CallbackFxn callback function when the transaction has completed
#define | UART_TRANSFER_MODE_BLOCKING (0U)
| UART read/write APIs blocks execution. This mode can only be used when called within a Task context. More...
#define | UART_TRANSFER_MODE_CALLBACK (1U)
| UART read/write APIs does not block code execution and will call a UART_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context. More...

## Macro Definition Documentation

## ◆ UART_TRANSFER_MODE_BLOCKING

#define UART_TRANSFER_MODE_BLOCKING (0U)

UART read/write APIs blocks execution. This mode can only be used when called within a Task context.

## ◆ UART_TRANSFER_MODE_CALLBACK

#define UART_TRANSFER_MODE_CALLBACK (1U)

UART read/write APIs does not block code execution and will call a UART_CallbackFxn. This mode can be used in a Task, Swi, or Hwi context.

## Typedef Documentation

## ◆ UART_Handle

typedef struct UART_Config_s* UART_Handle

## ◆ UART_CallbackFxn

typedef void(* UART_CallbackFxn) (UART_Handle handle, UART_Transaction *transaction)

The definition of a callback function used by the UART driver when used in UART_TRANSFER_MODE_CALLBACK.

Parameters

  transaction* | Pointer to a UART_Transaction

## Function Documentation

## ◆ UART_init()

void UART_init | ( | void |  | ) |

This function initializes the UART module.

## ◆ UART_deinit()

void UART_deinit | ( | void |  | ) |

This function de-initializes the UART module.

## ◆ UART_open()

UART_Handle UART_open | ( | uint32_t | index,
|  | const UART_Params * | prms
| ) |  |

This function opens a given UART peripheral.

Precondition
  UART controller has been initialized using UART_init()

Parameters

  index | Index of config to use in the UART_Config array
  prms | Pointer to open parameters. If NULL is passed, then default values will be used

Returns
  A UART_Config on success or a NULL on an error or if it has been opened already

See also
  UART_init()
  UART_close()
  UART_Params_init

## ◆ UART_close()

void UART_close | ( | UART_Handle | handle | ) |

Function to close a UART peripheral specified by the UART handle.

Precondition
  UART_open() has to be called first

Parameters

  handle | UART_Config returned from UART_open()

See also
  UART_open()

## ◆ UART_write()

int32_t UART_write | ( | UART_Handle | handle,
|  | UART_Transaction * | trans
| ) |  |

Function to perform UART write operation.

In UART_TRANSFER_MODE_BLOCKING, UART_write() will block task execution until the transaction has completed or a timeout has occurred.

In UART_TRANSFER_MODE_CALLBACK, UART_write() does not block task execution, but calls a UART_CallbackFxn once the transfer has finished. This makes UART_write() safe to be used within a Task, software or hardware interrupt context.

In interrupt mode, UART_write() does not wait until tx fifo is empty. Application needs to call UART_flushTxFifo() to ensure write is completed. i.e. data is out from the FIFO and shift registers.

From calling UART_write() until transfer completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

  handle | UART_Config returned from UART_open()
  trans | Pointer to a UART_Transaction. All of the fields within transaction except UART_Transaction.count and UART_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns
  SystemP_SUCCESS if started successfully; else error on failure

See also
  UART_open

## ◆ UART_read()

int32_t UART_read | ( | UART_Handle | handle,
|  | UART_Transaction * | trans
| ) |  |

Function to perform UART read operation.

In UART_TRANSFER_MODE_BLOCKING, UART_read() will block task execution until the transaction has completed or a timeout has occurred.

In UART_TRANSFER_MODE_CALLBACK, UART_read() does not block task execution, but calls a UART_CallbackFxn once the transfer has finished. This makes UART_read() safe to be used within a Task, software or hardware interrupt context.

From calling UART_read() until transfer completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

  handle | UART_Config returned from UART_open()
  trans | Pointer to a UART_Transaction. All of the fields within transaction except UART_Transaction.count and UART_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns
  SystemP_SUCCESS if started successfully; else error on failure

See also
  UART_open

## ◆ UART_writeCancel()

int32_t UART_writeCancel | ( | UART_Handle | handle,
|  | UART_Transaction * | trans
| ) |  |

Function to perform UART canceling of current write transaction.

In UART_TRANSFER_MODE_CALLBACK, UART_writeCancel() does not block task execution, but calls a UART_CallbackFxn once the cancel has finished. This makes UART_writeCancel() safe to be used within a Task, software or hardware interrupt context.

From calling UART_writeCancel() until cancel completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

  handle | UART_Config returned from UART_open()
  trans | Pointer to a UART_Transaction. All of the fields within transaction except UART_Transaction.count and UART_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns
  SystemP_SUCCESS if started successfully; else error on failure

See also
  UART_open

## ◆ UART_readCancel()

int32_t UART_readCancel | ( | UART_Handle | handle,
|  | UART_Transaction * | trans
| ) |  |

Function to perform UART canceling of current read transaction.

In UART_TRANSFER_MODE_CALLBACK, UART_readCancel() does not block task execution, but calls a UART_CallbackFxn once the cancel has finished. This makes UART_writeCancel() safe to be used within a Task, software or hardware interrupt context.

From calling UART_readCancel() until cancel completion, the UART_Transaction structure must stay persistent and must not be altered by application code. It is also forbidden to modify the content of the UART_Transaction.buf during a transaction, even though the physical transfer might not have started yet. Doing this can result in data corruption.

Parameters

  handle | UART_Config returned from UART_open()
  trans | Pointer to a UART_Transaction. All of the fields within transaction except UART_Transaction.count and UART_Transaction.status are WO (write-only) unless otherwise noted in the driver implementations. If a transaction timeout has occurred, UART_Transaction.count will contain the number of bytes that were transferred. Neither is it allowed to modify the transaction object nor the content of UART_Transaction.buf until the transfer has completed

Returns
  SystemP_SUCCESS if started successfully; else error on failure

See also
  UART_open

## ◆ UART_getHandle()

UART_Handle UART_getHandle | ( | uint32_t | index | ) |

Function to return a open'ed UART handle given a UART instance index.

Parameters

  index | Index of config to use in the UART_Config array

Returns
  A UART_Config on success or a NULL on an error or if the instance index has NOT been opened yet

## ◆ UART_flushTxFifo()

void UART_flushTxFifo | ( | UART_Handle | handle | ) |

Function to flush a TX FIFO of peripheral specified by the UART handle.

Precondition
  UART_open() has to be called first

Parameters

  handle | UART_Config returned from UART_open()

See also
  UART_open()

## ◆ UART_getBaseAddr()

uint32_t UART_getBaseAddr | ( | UART_Handle | handle | ) |

Function to get base address of UART instance of a particular handle.

Parameters

  handle | UART_Config returned from UART_open()

See also
  UART_open

## ◆ UART_Transaction_init()

void UART_Transaction_init | ( | UART_Transaction * | trans | ) |

Function to initialize the UART_Transaction struct to its defaults.

Parameters

  trans | Pointer to UART_Transaction structure for initialization

## ◆ UART_Params_init()

void UART_Params_init | ( | UART_Params * | prms | ) |

Function to initialize the UART_Params struct to its defaults.

Parameters

  prms | Pointer to UART_Params structure for initialization

## Variable Documentation

## ◆ gUartConfig

UART_Config gUartConfig[]
| extern

Externally defined driver configuration array.

## ◆ gUartConfigNum

uint32_t gUartConfigNum
| extern

Externally defined driver configuration array size.