4.7. CDD_UART

4.7.1. Introduction

This document describes the functionality, API and configuration of the AUTOSAR BSW module UART.

Supported AUTOSAR Release:

4.3.1

Supported Configuration Variants:

Pre-compile, Post-Build

Vendor ID:

UART_VENDOR_ID (44)

Module ID:

UART_MODULE_ID (255)

Supported Platform:

AM263x

The UART complex device driver provides data read and write transfer using the module unit channels in the device board. The driver is configurable for parameters such as baud rate, word length, parity, stop bits, IO mode, clock frequency, transfer and receival buffer threshold, and operating mode. Depending upon the IO Mode selected, the driver allows for both synchronous as well as asynchronous mode of data transfer.

The UART Driver provides services for reading and writing to/from

1. UART Channels

2. UART Ports / Serial Device

4.7.2. UART Driver Architecture

The UART driver has architecture as shown in below figure from the AM263 Technical Reference Manual

Fig. 4.4 UART interface

UART comes under the Complex Driver Design section under the AUTOSAR Classic Platform Architecture

Fig. 4.5 AUTOSAR CDDs

4.7.3. Functional Description

4.7.3.1. Features Supported and Not Supported

Supported	Not Supported
Interrupt, Polling And DMA Mode For DMA mode, only trigger level 1 is supported	MODEM control functions
Write, Read and Cancel Operation	Hardware Flow Control
Read Return Full & Partial Mode	Partial Mode is only supported in interrupt mode and returns FIFO level chars
Receiver line error status like overrun, framing	IrDA and CIR Features

4.7.3.2. Initialization

Cdd_Uart_Init() is the function responsible for initializing driver peripheral and opening its configured instances for transmission

4.7.3.3. States

UART driver maintains these below states as per the driver source condition:

1. CDD_UART_UNINIT

2. CDD_UART_INIT

4.7.3.4. Main Functions

1. Cdd_Uart_Read() - This API is used for reading data using a given channel ID upto a specified length

2. Cdd_Uart_Write() - This API is used for writing data using a given channel ID upto a specified data count

3. Cdd_Uart_Cancel() - This API is used for cancelling an ongoing data transfer using a given channel ID in the given direction

4. Cdd_Uart_GetRemainingWords() - This API is used for checking the remaining words count for an ongoing Interrupt or DMA mode data transfer

4.7.4. File Structure

The files structure for the UART driver is silimar to other drivers. The source is divided into headers under include/ and driver source within src/ directory under Uart driver path in MCAL. Cdd_Uart.c and Cdd_Uart.h are the 2 files that contain the provided driver API’s.

• Cdd_Uart.h : Shall specify the interface provided by the driver.

• Cdd_Uart.c, Cdd_Uart_Priv.h : Shall implement the driver functionality.

• uart_dma_edma.c : Contains functions that support the Enhanced DMA mode for use with UART channels in DMA mode as IO mode.

• Cdd_Uart_Irq.h and Cdd_Uart_Irq.c : contain interrupt service routines

4.7.5. Memory mapping

Memory Mapping Sections	CDD_UART_CODE	CDD_UART_CODE_ISR	CDD_UART_VAR_NO_INIT	CDD_UART_VAR_ZERO_INIT	CDD_UART_PBCFG	CDD_UART_PBCFG_ROOT
CDD_UART_START_SEC_VAR_INIT_UNSPECIFIED(.bss) CDD_UART_STOP_SEC_VAR_INIT_UNSPECIFIED				x
CDD_UART_START_SEC_CODE_APPL(.text) CDD_UART_STOP_SEC_CODE_APPL		x
CDD_UART_START_SEC_VAR_UNSPECIFIED(.data) CDD_UART_STOP_SEC_VAR_UNSPECIFIED			x
CDD_UART_START_SEC_CODE(.text) CDD_UART_START_SEC_CODE	x
CDD_UART_START_SEC_PBCFG(.data) CDD_UART_STOP_SEC_PBCFG					x
CDD_UART_START_SEC_PBCFG_ROOT(.const) CDD_UART_STOP_SEC_PBCFG_ROOT						x

4.7.6. Services used by UART Driver

4.7.6.1. Cdd_Uart Callback Functions

The UART driver provides read, write and error call back functions supported for all channels targeted from UART Configurator Plugin

4.7.6.2. Dependencies on SW modules

4.7.6.2.1. DET

The module UART depends on the DET (by default) in order to report development errors. Detection and reporting of development errors, DET shall be enabled or disabled by the switch CDD_UART_DEV_ERROR_DETECT = STD_ON in Cdd_Uart_Cfg.h, generated by using appropriate option check within the configurator plugin. The DET can be replaced optionally by an equivalent component which is responsible to recognize development errors, if no DET component is available.

4.7.6.2.2. MCU

The Cdd_Uart Modules expects the MCU modules to enable the GPIO registers used used by configuring the PRCM correctly. MCU module is responsible for setting up clock configuration for the driver, the hardware clock available on the board.

4.7.6.2.3. PORT

The Cdd_Uart Modules expects that PinMux is set correctly to configure the GPIO pins for appropriate UART channel ports. The pin direction shall also be set by the PORT driver

4.7.6.2.4. SchM (Optional)

Beside the OS the BSW Scheduler provides functions that module UART calls at begin and end of critical sections.

There is only one kind of critical sections in this driver. Within these sections all read / modify / write accesses to internal UART status variables must be performed. This is defined in the application and used to handle in the UART driver by invoking SchM_Enter_Cdd_Uart_UART_EXCLUSIVE_AREA_0() and SchM_Exit_Cdd_Uart_UART_EXCLUSIVE_AREA_0() functions

4.7.7. API Definition

Refer the MCAL_ApiGuide for API documentation and Type definition

Service ID	Service
0x01	Cdd_Uart_Init
0x02	Cdd_Uart_GetVersionInfo
0x03	Cdd_Uart_DeInit
0x04	Cdd_Uart_Write
0x05	Cdd_Uart_Read
0x06	Cdd_Uart_Cancel
0x07	Cdd_Uart_GetRemainingWords
0x08	Cdd_Uart_RegisterReadback

4.7.7.1. Supported APIs

1. Cdd_Uart_Init

2. Cdd_Uart_DeInit

3. Cdd_Uart_Write

4. Cdd_Uart_Read

5. Cdd_Uart_Cancel

6. Cdd_Uart_GetRemainingWords

7. Cdd_Uart_GetVersionInfo

8. Cdd_Uart_RegisterReadback

4.7.7.2. Interrupt Service Routines

Following Interrupt Service Routines are present in UART:

1. Cdd_Uart_ChannelIsr - The Channel-based Interrupt Subroutine calls handler function based on the selected channel.

2. CDD_EDMA_lld_transferCompletionMasterIsrFxn - The common-channel DMA-based Interrupt Subroutine calls handler function available for transfer completion.

4.7.8. Error Handling

• Development error reporting. The Cdd_UartDriver will report development errors on enabling UART_DEV_ERROR_DETECT == STD_ON in Cdd_Uart_Cfg.h

  Refer API documentation for list of development errors reported by UART Driver

• Parameter checking AUTOSAR requires that API functions check the validity of their parameters. The checks are described in spec and are done as internal parameter checks of the API functions. These checks are for development error reporting and can be en-/disabled separately. Refer to the configuration chapter where the en-/disabling of the checks is described. En-/disabling of single checks is an addition to the AUTOSAR standard which requires to en-/disable the complete parameter checking via the parameter UART_DEV_ERROR_DETECT

• Production Code Error Reporting By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus().

4.7.9. Configuration

UART driver supports Pre-Compile and Post-Build variant and doesn’t support Link-Time configuration.

4.7.9.1. Configurable Parameters

Cdd_Uart_TI_AM263X configurator plugin for the driver supports below configurable parameters:

1. uartHwUnitID - UART Hardware Unit Instance number

2. uartClockFrequency - Clock Frequency

3. uartBaudRate - Baud Rate for signal transfer

4. uartIOMode - IO Mode for signal transfer

5. uartTXTriggerLevel - Trigger level for Transmission of signal

6. uartRXTriggerLevel - Trigger level for Receival of signal

7. uartHwFlowControlThreshold - Trigger threshold for signal flow control

8. uartWordLength - Word Length for packets

9. uartParity - Parity for data

10. uartReadReturnMode - Read return mode

11. uartOperatingMode - Mode of Operation

12. uartStopBits - Amount of stop bits per packet

13. edmaXbarRxHandleID - UART Receival EDMA Handle ID

14. edmaXbarTxHandleID - UART Transmittal EDMA Handle ID

15. uartNotificationHandlers - Notification Callback Handles for read, write completion or in case of data transfer error detection

For using UART with DMA mode, take additional care with these configuration value with CDD DMA configuration:

• separate DMA configuration shall be done for Tx and/or Rx of each UART instance configured for DMA IO mode using the CDD DMA configurator plugin. Make sure to set CddDmaInterruptEnable option provided there as UART peripheral shall make use of enhanced DMA with interrupt enabled.

• UART Tx makes use of two parameters for Tx and Dummy param sets to service a dummy transfer request at the end as expected from HW IP. So make sure to have corresponding two parameter sets registered in a channel group on configurator plugin.

4.7.10. Example Application

CDD UART DMA example application demonstrating the CDD UART driver features is present in Uart/uart_echo_dma_app under /examples folder.

The UART example app used to verify the data transmission and receival through a selected channel ID 0 of the available UART Hardware Units.

This application can be built from the build folder by running gmake –s uart_echo_dma_app PLATFORM=am263.

The details of running the application and the setup required is part of the MCAL User Guide.

4.7.11. Document Revision History

Version #	Date	Revision History	Status
MCAL_AM263x_08.06.02_ENG	30 June 2023	Initial draft	Approved
2.0	12 Dec 2023	Updates to reflect DMA changes	Approved

4.7.12. TI Disclaimer

Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.

TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.

Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.

TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.

Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.

Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm

Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265