4.9. CDD UART Module

4.9.1. Acronyms and Definitions

Abbreviation/Term

Explanation

AUTOSAR

Automotive Open System Architecture

BSW

Basic Software

DET

Default Error Tracer

CDD

Complex Device Driver

DMA

Direct Memory Access

ISR

Interrupt Service Routine

INT

Interrupt

HW

Hardware

SW

Software

MCU

Micro Controller Unit

OS

Operating System

API

Application Programming Interface

UART

Universal Asynchronous Receiver Transmitter

4.9.2. Introduction

This document describes the functionality and configuration of the Cdd_Uart module.

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

AM263Px

The UART complex device driver provides data read and write transfer using the module unit channels in the device board.

4.9.3. Functional Overview

The driver is configurable for parameters such as baud rate, word length, parity, stop bits, IO mode, clock frequency, transmission and reception 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.9.3.1. Driver Architecture

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

UART Module Pins

Fig. 4.51 UART interface

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

CDD in AUTOSAR 4.3.1 layers

Fig. 4.52 AUTOSAR CDDs

4.9.3.2. Initialization

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

4.9.3.3. States

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

  1. CDD_UART_UNINIT

  2. CDD_UART_INIT

4.9.3.4. Assumptions

For using DMA feature, driver assumes that cache initialization is done in application only and not done by the driver.

4.9.3.5. Limitations

None

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

Note: Timeout Value parameter in Cdd_Uart_Read() and Cdd_Uart_Write() should be passed as number of ticks according to clock frequency. The clock source have changed from RTI timers which used 200MHz clock frequency to R5f timers which uses 400MHz clock frequency, so the timeout values need to be passed accordingly.

4.9.3.7. Design overview

Will be updated in future release

4.9.4. Hardware Features

4.9.4.1. IP Supported Features

  • Interrupt, Polling And DMA Mode. For DMA mode, only trigger level 1 is supported

  • Write, Read and Cancel Operation.

  • Read Return Full & Partial Mode.

  • Receiver line error status like overrun, framing.

4.9.4.2. Not supported Features

  • MODEM control functions.

  • Hardware Flow Control.

  • Partial Mode is only supported in interrupt mode and returns FIFO level chars.

  • IrDA and CIR Features.

4.9.4.3. Non compliance

4.9.4.3.1. Deviations to requirements (Requirement Traceability)

4.9.4.3.1.1. Deviation of requirements against AUTOSAR specification requirements

None

4.9.5. Source files

The files structure for the UART driver is similar 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.

Static source C Files are defined below

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂Uart
┃ ┃ ┣ 📂include
┃ ┃ ┃ ┣ 📜Cdd_Uart.h : Shall specify the interface provided by the driver.
┃ ┃ ┃ ┣ 📜Cdd_Uart_Irq.h : contain interrupt service routines.
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📜Cdd_Uart.c : Shall implement the CDD Uart driver functionality.
┃ ┃ ┃ ┣ 📜Cdd_Uart_Irq.c : contain interrupt service routines.
┃ ┃ ┣ 📂V0
┃ ┃ ┃ ┗ 📜Cdd_Uart_Priv.c : Shall implement the private functions.
┃ ┃ ┃ ┣ 📜Cdd_Uart_Priv.h : Contains device specific function declarations.
┃ ┃ ┃ ┣ 📜uart.c : Contains the UART driver implementations.
┃ ┃ ┃ ┣ 📜Uart.h : Contains Internal functions declarations for Uart driver.
┃ ┃ ┃ ┗ 📜uart_dma.h : Contains DMA related function declarations.
┃ ┃ ┃ ┣ 📜uart_dma_edma.c : Contains functions that support the Enhanced DMA mode for use with UART channels in DMA mode as IO mode.
┃ ┃ ┗ 📜Makefile
┃ 📂mcal_config
┃ 📂mcal_docs
┃ 📜README.txt

Plugin files are defined below in the table.

Plugin Files

Description

Cdd_Uart_Cfg.h

Contains the Precompile switches and Symbolic names

Cdd_Uart_Cfg.c

Contains all Pre-Compile Configured parameters

Cdd_Uart_PBcfg.c

Contains all Post-Build Configured parameters

4.9.6. Module requirements

Please refer Software Product Specification document provided as part of CSP.

4.9.6.1. 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)

x

CDD_UART_STOP_SEC_VAR_INIT_UNSPECIFIED

x

CDD_UART_START_SEC_CODE_APPL(.text)

x

CDD_UART_STOP_SEC_CODE_APPL

x

CDD_UART_START_SEC_VAR_UNSPECIFIED(.data)

x

CDD_UART_STOP_SEC_VAR_UNSPECIFIED

x

CDD_UART_START_SEC_CODE(.text)

x

CDD_UART_STOP_SEC_CODE

x

CDD_UART_START_SEC_PBCFG(.data)

x

CDD_UART_STOP_SEC_PBCFG

x

CDD_UART_START_SEC_PBCFG_ROOT(.const)

x

CDD_UART_STOP_SEC_PBCFG_ROOT

x

4.9.6.2. Scheduling

4.9.6.2.1. SchM (Optional)

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

4.9.6.2.2. 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.9.6.3. Error handling

4.9.6.3.1. Development Error Reporting (DET)

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

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

4.9.6.3.3. Production Code Error Reporting

By default, production code related errors are reported to the DEM using the service DEM_ReportErrorStatus().

4.9.7. Used resources

4.9.7.1. Interrupt Handling

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.9.8. Integration description

4.9.8.1. Dependent modules

4.9.8.1.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.9.8.1.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.9.8.1.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.9.8.1.4. Callback Functions

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

4.9.8.2. Multi-core and Resource allocator

Will be updated in the next release

4.9.9. Configuration

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

Variants

Configured Files

PostBuild

Cdd_Uart_PBcfg.c , Cdd_Uart_Cfg.h

Pre-Compile

Cdd_Uart_Cfg.c , Cdd_Uart_Cfg.h

4.9.9.1. Parameter Description

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 Reception 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 Receiver EDMA Handle ID

  14. edmaXbarTxHandleID - UART Transmitter 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.9.9.2. Configuration rules and constraints to enable plausibility checks

Will be updated in next release

4.9.10. Examples

4.9.10.1. Overview

Will be updated in the next release

4.9.10.2. Hardware Software Setup and Tools

None

4.9.10.3. Steps to build and run example

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 reception 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=am263px.

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

4.9.10.4. Example Logs

Will be updated in next release

4.9.10.5. File Structure

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂examples
┃ ┃ ┣ 📂Uart
┃ ┃ ┃ ┣ 📂uart_echo_dma_app
┃ ┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┃ ┣ 📜Makefile
┃ ┃ ┃ ┃ ┣ 📜UartEchoDma.c : Contains UART Echo DMA test example.
┃ ┃ ┃ ┃ ┣ 📜UartEchoDma.h : Contains UART Echo DMA test example header.
┃ ┣ 📂examples_config
┃ ┃ ┣ 📂Uart_Demo_Cfg
┃ ┃ ┃ ┣ 📂soc
┃ ┃ ┃ ┃ ┣ 📂am263px
┃ ┃ ┃ ┃ ┃ ┣ 📂r5f0_0
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂include
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜Cdd_Uart_Cfg.h : Contains the Precompile switches, Symbolic names.
┃ ┃ ┃ ┃ ┃ ┃ ┣ 📂src
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜Cdd_Uart_Cfg.c : Contains all Pre-Compile Configured parameters
┃ ┃ ┃ ┃ ┃ ┃ ┃ ┣ 📜Cdd_Uart_PBcfg.c : Contains all Post-Build Configured parameters
┃ 📂mcal_config
┃ 📂mcal_docs
┣ 📜README.txt

4.9.11. FAQ’s

None

4.9.12. Test Report

Please refer AM26x CDD UART Driver Test Case Report as part of CSP provided in the release package.

4.9.13. References

Technical Reference Manual