4.8. CDD I2C Module

4.8.1. Acronyms and Definitions

Abbreviation/Term

Explanation

AUTOSAR

Automotive Open System Architecture

API

Application Programming Interface

BSW

Basic Software

DET

Default Error Tracer

I2C

Inter Integrated Circuit

MCAL

Micro Controller Abstraction Layer

MCU

Micro Controller Unit

OS

Operating System

4.8.2. Introduction

The I2C driver is part of complex device drivers (CDD) which provides API for the inter-integrated circuit (I2C) module. The I2C driver provides an interface to communicate to the devices connected to the I2C bus. External components attached to this 2-wire serial bus can transmit/receive data to/from the device through the I2C module.

The following figure shows where the I2C is located in the AUTOSAR architecture.

I2C Architecture

Fig. 4.40 I2C Architecture

Supported AUTOSAR Release

4.3.1

Supported Configuration Variants

Pre-Compile

Vendor ID

CDD_I2C_VENDOR_ID (44)(TEXAS INSTRUMENTS)

Module ID

CDD_I2C_MODULE_ID (255)

Supported Platform

AM263Px

4.8.3. Functional Overview

The I2C module provides an interface between the MCU and devices compliant with the NXP Semiconductors Inter-IC bus (I2C bus) specification version 2.1, and connected by way of an I2C bus. External components attached to this 2-wire serial bus can transmit/receive 1- to 8-bit data to/from the device through the I2C module.

The expected flow for utilization of the driver as per the example application is interrupt registration (only required in case of interrupt mode), I2c driver initialization using Cdd_I2c_Init(). Post initialization buffer set up linking is done to point channels to their respective buffers using Cdd_I2c_SetupEB() and for writing data to slaves Cdd_I2c_AsyncTransmit() is used in both polling as well as interrupt mode.

For reception of data from I2c slaves Cdd_I2c_AsyncTransmit() can be used in interrupt mode. If polling mode is being used, use Cdd_I2c_MainFunction() to process any sequence in the queue and update the status of the queue to real time value.

4.8.4. Hardware Features

On AM263Px platform, there are 4 I2C instances I2C0, I2C1, I2C2 and I2C3.

4.8.4.1. Hardware Features Supported

  • Controller Mode

  • Polling and Interrupt Mode (at instance level)

  • Configurable Baudrate (at instance level)

  • Configurable Own Address (at instance level)

  • 7 and 10 bit Address Schemes (at channel level)

  • Restart Mode: Stop or no stop between channels (at channel level)

  • Read or Write Operation (at channel level)

  • Configurable Target Address (at channel level)

4.8.4.2. Hardware Features Not Supported by the Driver

  • Target Mode and all related features

  • DMA Mode

  • Multi Master Mode and Arbitration Loss scenarios are not tested

4.8.4.3. Software Supported Features

  • Configurable Development Error

  • Configurable Sequence Size

  • Configurable Channel Size

  • Configurable Data Length to Transfer

  • Configurable Hardware Units

  • Configurable Channels

  • Configurable Sequences

  • Multiple Channels in a Sequence

  • Transfer Complete and Error Notification Callback

4.8.5. Source Files

📦AM263Px
┣ 📂build
┣ 📂mcal
┃ ┣ 📂I2c
┃ ┃ ┣ 📂include
┃ ┃ ┃ ┣ 📜Cdd_I2c.h : Contains the API declarations of the Cdd_I2c driver to be used by upper layers
┃ ┃ ┃ ┗ 📜Cdd_I2c_Irq.h : Contains the declarations of the ISR handlers
┃ ┃ ┣ 📂src
┃ ┃ ┃ ┣ 📜Cdd_I2c.c : Source file that contains the API relevant implementation
┃ ┃ ┃ ┣ 📜Cdd_I2c_Priv.c : Contains internal function definitions used to realize the driver
┃ ┃ ┃ ┣ 📜Cdd_I2c_Priv.h : Contains data structures and Internal function declarations
┃ ┃ ┃ ┣ 📜Cdd_I2c_Utils.c : Contains internal function definitions for queue implementation
┃ ┃ ┃ ┣ 📜Cdd_I2c_Utils.h : Contains internal function declarations for queue implementation
┃ ┃ ┃ ┗ 📜Cdd_I2c_Irq.c : Contains the ISR implementation
┃ ┃ ┣ 📂V0
┃ ┃ ┃ ┣ 📜Cdd_I2c_hw_reg.h : Contains register offsets, mask values, shift values and specific bit set reset macros
┃ ┃ ┃ ┣ 📜Cdd_I2c_Hw.c : Contains internal function definitions used to realize the driver
┃ ┃ ┃ ┗ 📜Cdd_I2c_Hw.h : Contains data structures and Internal function declarations for HW layer
┃ ┃ ┗ 📜Makefile
┣ 📂mcal_config
┣ 📂mcal_docs
┗ 📜README.txt

Description of generated files is provided below:

Plugin Files

Description

Cdd_I2c_Cfg.h

This file contains general container configuration parameters like DET error ON, Polling mode OFF, Sequence size, Queue size, Channel size etc.

Cdd_I2c_Cfg.c

Contains all channels Pre-Build Configuration parameters

The below diagram shows the files structure for the I2C driver.

I2C File Structure

Fig. 4.41 I2C File Structure

4.8.6. Module Requirements

4.8.6.1. Memory Mapping

The objects (e.g. variables, functions, constants) are declared by compiler independent definitions – the compiler abstraction definitions. Each compiler abstraction definition is assigned to a memory section. The following table contains the memory section names and the compiler abstraction definitions of the I2C and illustrates their assignment among each other.

Memory Mapping Sections

I2C_CODE

I2C_VAR_NO_INIT

I2C_VAR_INIT

I2C_CONST

I2C_CFG

I2C_APPL_CODE

I2C_APPL_DATA

CDD_I2C_START_SEC_CODE

x

CDD_I2C_STOP_SEC_CODE

x

CDD_I2C_START_SEC_ISR_CODE

x

CDD_I2C_STOP_SEC_ISR_CODE

x

CDD_I2C_START_SEC_CONFIG_DATA

x

CDD_I2C_STOP_SEC_CONFIG_DATA

x

CDD_I2C_START_SEC_CONFIG_CONST_32

x

CDD_I2C_STOP_SEC_CONFIG_CONST_32

x

CDD_I2C_START_SEC_VAR_NOINIT_UNSPECIFIED

x

CDD_I2C_STOP_SEC_VAR_NOINIT_UNSPECIFIED

x

CDD_I2C_START_SEC_VAR_INIT_UNSPECIFIED

x

CDD_I2C_STOP_SEC_VAR_INIT_UNSPECIFIED

x

Application buffers passed to I2C

x

Notification called from I2C

x

4.8.6.2. Scheduling

Schedule Function API

Description

Cdd_I2c_MainFunction

This function process the I2c transmission

4.8.6.3. Error Handling

4.8.6.3.1. Development Error Reporting

By default, development errors are reported to the DET using the service Det_ReportError(), if development error reporting is enabled (i.e. precompile parameter CDD_I2C_DEV_ERROR_DETECT==STD_ON). If another module is used for development error reporting, the function prototype for reporting the error can be configured by the integrator, but must have the same signature as the service Det_ReportError(). The reported I2C ID is 255

4.8.6.3.2. Error Codes

Type of Error

Related Error code

Value (Hex)

No errors

CDD_I2C_E_NO_ERROR

0x00

API service used without module initialization

CDD_I2C_E_UNINIT

0x01

Init service called twice without DeInit

CDD_I2C_E_ALREADY_INITIALIZED

0x02

Channel out of bounds, exceeds the maximum number of configured channels

CDD_I2C_E_PARAM_CHANNEL

0x04

Sequence out of bounds, exceeds the maximum number of configured sequences

CDD_I2C_E_PARAM_SEQUENCE

0x05

Length out of bounds – a zero length is not accepted. The total length is limited to 65535

CDD_I2C_E_PARAM_LENGTH

0x06

An invalid version info pointer has been passed (a NULL_PTR)

CDD_I2C_E_PARAM_VINFO_PTR

0x07

An invalid configuration has been passed (a non NULL_PTR)

CDD_I2C_E_PARAM_CONFIG

0x08

Two invalid transmission buffers have been passed (no NULL_PTR/ or both NULL_PTR)

CDD_I2C_E_PARAM_TRANS_BUFFER

0x09

Address out of bounds, exceeds the limit of the configured address range

CDD_I2C_E_PARAM_ADDRESS

0x0A

Buffer direction conflicts with channel direction set via EB

CDD_I2C_E_PARAM_DIRECTION

0x0B

API service called with invalid HW unit ID

CDD_I2C_E_PARAM_HWUNIT

0x16

API service called with sequence is busy

CDD_I2C_E_SEQ_BUSY

0x17

4.8.7. Used Resources

4.8.7.1. Interrupt Handling

Interrupt routines are provided by the CDD I2C driver is Cdd_I2c_Isr_Handler(). Basically, the ISR’s are in the file Cdd_I2c_Irq.c. User might edit it for adapting for the suitable OS. Interrupt handler shall be provided for each instance of the CDD I2C driver. The corresponding CDD I2C Interrupt numbers are:

Hardware Unit

ISR Handler Mapped

Interrupt Number

0

Cdd_I2c_HwUnit0_ISR

44

1

Cdd_I2c_HwUnit1_ISR

45

2

Cdd_I2c_HwUnit2_ISR

46

3

Cdd_I2c_HwUnit3_ISR

47

4.8.8. Integration Description

4.8.8.1. Dependent Modules

4.8.8.1.1. DET

The module I2C depends on the DET (by default) in order to report development errors. Detection and reporting of development errors can be enabled or disabled by the switch “Enable Development Error Detection” on the “General” container within the module I2C. The DET can be replaced optionally by an equivalent component which is responsible to recognize development errors, if no DET component is available.

4.8.8.1.2. MCU

The module MCU powers up the microcontroller’s peripherals at startup time and initializes clock source. Since the peripherals are also containing the registers for I/O functionality they have to be activated if it is intended to use them.

4.8.8.1.3. PORT

The module PORT enables the I2C lines at startup time. To operate the I2C properly, the PORT driver has to be configured. The PORT driver sets the Pins to the required values for the I2C to operate. The Pins used are SDA (serial data line) and SCL (serial clock). An open drain configuration is recommended. Some I2C drivers require the PORT for switching from I2C functionality to DIO functionality – to use the “clock free” procedure - and back.

4.8.8.1.4. SchM

If multiple AUTOSAR runnables have access to the same Data Store Memory block, the exported AUTOSAR specification enforces data consistency by using an AUTOSAR exclusive area. With this specification, the runnables have mutually exclusive access to the per-instance memory global data, which prevents data corruption. Beside the OS, the BSW Scheduler provides functions that CDD I2C module calls at begin and end of critical sections. This implementation requires 1 level of exclusive access to guard critical sections.

The data consistency mechanism that has to be applied to an ExclusiveArea might be domain, ECU or even project specific. The decision which mechanism has to be applied by RTE / Basic Software Scheduler is taken during ECU integration by setting the Exclusive Area configuration parameter RteExclusiveAreaImplMechanism. This parameter is an input for RTE generator.

For CDD_I2C Module, data consistency and exclusive access to critical sections are required for the following sections as shown in the table below:

Exclusive Area Functions used

CDD_I2C Function calling Exclusive Area

Need for Exclusive Area

Recommended Exclusive Area Mapping

CDD_I2C_EXCLUSIVE_AREA_0

Cdd_I2c_SetupEB()
Cdd_I2c_SetupEBDynamic()
Cdd_I2c_AsyncTransmit()
Cdd_I2c_Cancel()
Cdd_I2c_MainFunction()

To protect against multiple access for shared resources

OS_RESOURCE : If the I2C APIs are only called from pre-emptible task context, its recommended to use this mechanism as it takes care of resource access protection and task priority management.
None: If I2C APIs are only called from non pre-emptible task context or during init, its recommended to use this mechanism as multiple access protection to shared resource is not needed.

4.8.8.1.5. Configurable Callback Functions

4.8.8.1.5.1. Notifications

At its configurable interfaces the I2C defines notifications that can be mapped to callback functions in case completion of a sequence or failure of a sequence. The mapping is not statically defined by the I2C but can be performed at configuration time.

4.8.8.1.5.2. Cdd_I2c_SequenceEndNotification

Sequence transfer successful notification function. Can be configured in the configuration tool. Particularities and Limitations: It is advised to keep the code execution in the notification function as short as possible. Call context: Interrupt as well as polling

4.8.8.1.5.3. Cdd_I2c_SequenceErrorNotification

Sequence transfer error notification function. If the I2c detects an error, this function notifies the application about a communication failure. Can be configured in the configuration tool. Particularities and Limitations: It is advised to keep the code execution in the notification function as short as possible. Call context: Interrupt as well as polling

For the Following API’s it is possible to be called from the sequence notifications:

  1. Cdd_I2c_GetVersionInfo

  2. Cdd_I2c_SetupEB

  3. Cdd_I2c_SetupEBDynamic

  4. Cdd_I2c_GetResult

  5. Cdd_I2c_GetSequenceResult

  6. Cdd_I2c_GetStatus

4.8.8.2. Multi-core and Resource Allocator

Not Supported

4.8.9. Configuration

4.8.9.1. Migration Guide

4.8.9.2. Configuration Parameters

4.8.9.2.1. CddI2cDevErrorDetect

Item

Description

I2c Dev Error ON/OFF.

Name

CddI2cDevErrorDetect

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

true

4.8.9.2.2. CddI2cUseInterrupts

Item

Name

CddI2cUseInterrupts

Description

Switches to activate or deactivate interrupt controlled job processing(ON/OFF).

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

false

4.8.9.2.3. CddI2cVersionInfoApi

Item

Name

CddI2cVersionInfoApi

Description

Pre-processor switch to enable/disable the API to read out the modules version information.

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

true

4.8.9.2.4. CddI2cCancelCheck

Item

Name

CddI2cCancelCheck

Description

Switches to activate or deactivate the Cancel channel transmission API(ON/OFF).

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

false

4.8.9.2.5. CddI2cStatusCheck

Item

Name

CddI2cStatusCheck

Description

Type of Isr function: void functionname(void) CAT1 : interrupt void func(void) CAT2 : ISR(func)

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

CDD_I2C_ISR_VOID

Multiplicity-Configuration-Class

Pre-Compile Time

VARIANT-PRE-COMPILE

Post-build-variant-multiplicity

false

Range

CDD_I2C_ISR_VOID
CDD_I2C_ISR_CAT1
CDD_I2C_ISR_CAT2

4.8.9.2.6. CddI2cHwUnitsUsed

Item

Name

CddI2cHwUnitsUsed

Description

Maximum number of I2c hardware units used

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

1

Max-value

4

Min-value

1

4.8.9.2.7. CddI2cEnableRegisterReadbackApi

Item

Name

CddI2cEnableRegisterReadbackApi

Description

Switch to indicate that the Cdd_I2c_RegisterReadBack is supported

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

true

4.8.9.3. CddI2cHwConfig

This container contains the HW unit initialization parameters

4.8.9.3.1. CddI2cHwUnitType

Item

Name

CddI2cHwUnitType

Description

I2c HW unit to use.

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

CDD_I2C_HW_UNIT_0

Range

CDD_I2C_HW_UNIT_0
CDD_I2C_HW_UNIT_1
CDD_I2C_HW_UNIT_2
CDD_I2C_HW_UNIT_3

4.8.9.3.2. CddI2cChannelBitRate

Item

Name

CddI2cChannelBitRate

Description

Selection of Channel Bit Rate.

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

CDD_I2C_100KHZ

Range

CDD_I2C_100KHZ
CDD_I2C_400KHZ

4.8.9.3.3. CddI2cHwUnitFrequency

Item

Name

CddI2cHwUnitFrequency

Description

Frequency which the HW unit will utilize(Range = 6.7 MHz - 13.3 MHz), please note that this differs from the bus frequency used for communication

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

8000000

Max-value

13300000

Min-value

6700000

4.8.9.3.4. CddI2cClkInputSrc

Item

Name

CddI2cClkInputSrc

Description

Please ensure that the frequency used here should be the same as mcu clk settings for I2c, as this is required internally to calculate pre-scalar which is needed to set the bus frequency

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

200000000

Max-value

4294967295

Min-value

0

4.8.9.3.5. CddI2cOwnAddress

Item

Name

CddI2cOwnAddress

Description

Own address - used in both 7 and 10-bit address mode.

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

127

Max-value

1023

Min-value

0

4.8.9.4. CddI2cChannelConfig

This container contains the Channel configurations

4.8.9.4.1. CddI2cChannelDirection

Item

Name

CddI2cChannelDirection

Description

Selection of Channel direction.

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

CDD_I2C_WRITE

Range

CDD_I2C_WRITE
CDD_I2C_READ

4.8.9.4.2. CddI2cChannelSlaveAddress

Item

Name

CddI2cChannelSlaveAddress

Description

Specifies whether channel is 7 bit or 10 bit.

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

CDD_I2C_7_BIT_ADDRESS

Max-value

65535

Min-value

0

Range

CDD_I2C_7_BIT_ADDRESS
CDD_I2C_10_BIT_ADDRESS

4.8.9.5. CddI2cSequenceConfig

This container contains the Sequence configurations

4.8.9.5.1. CddI2cSequenceHwUnitType

Item

Name

CddI2cSequenceHwUnitType

Description

I2c HW unit to use.

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

CDD_I2C_HW_UNIT_0

Range

CDD_I2C_HW_UNIT_0
CDD_I2C_HW_UNIT_1
CDD_I2C_HW_UNIT_2
CDD_I2C_HW_UNIT_3

4.8.9.5.2. CddI2cNumberOfChannelsInSequence

Item

Name

CddI2cNumberOfChannelsInSequence

Description

Set the number of channels in the sequence

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

1

Max-value

255

Min-value

1

4.8.9.5.3. CddI2cSequenceCompleteNotify

Item

Name

CddI2cSequenceCompleteNotify

Description

Function pointer to callback function sequence complete notify

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

NULL_PTR

4.8.9.5.4. CddI2cSequenceErrorNotify

Item

Name

CddI2cSequenceErrorNotify

Description

Function pointer to callback function sequence complete notify

Origin

Texas Instruments

Post-Build-Variant-Value

false

Value-Configuration-Class

Pre-Compile-Time

VARIANT-PRE-COMPILE

Default-value

NULL_PTR

4.8.10. Examples

The example applications demonstrates use of I2C module, the list below identifies key steps performed in the example.

4.8.10.1. Cdd_I2c_Interrupt and Cdd_I2c_Poll

4.8.10.1.1. Overview

  • I2c Example (Interrupt and Polled Mode)

    • Initialize clock using Mcu_Init()

    • Initializes pins as I2C SDA and SCL using Port_Init()

    • Get I2C version using Cdd_I2c_GetVersionInfo()

    • Initialize I2c module using Cdd_I2c_Init()

    • Set up channels using Cdd_I2c_SetupEBDynamic()

    • Write data to target device

    • Receive and process data

    • De-initialize I2c module using Cdd_I2c_DeInit()

4.8.10.1.2. Setup Required to Run Example

  • Install Code Composer Studio(CCS) latest version

  • Install compiler as recommended

  • Connect the hardware and power up

  • Connect the uart and set up the baudrate to check the log on serial console

4.8.10.1.3. How to Run Examples

I2C example application demonstrating the MCAL I2C driver features is in folder <MCAL_ROOT>/examples/I2c. This application can be built from the root folder by giving “gmake -s i2c_app PLATFORM=am263px”.

4.8.10.1.4. Sample Log

I2C_APP: STARTS !!!

 I2C MCAL Version Info
 ---------------------
 Vendor ID           : 44
 Module ID           : 255
 SW Major Version    : 11
 SW Minor Version    : 0
 SW Patch Version    : 0

I2C_APP: EEPROM Data 0x0000: 0x02
I2C_APP: EEPROM Data 0x0001: 0x03
I2C_APP: EEPROM Data 0x0002: 0x04
I2C_APP: EEPROM Data 0x0003: 0x05
I2C_APP: EEPROM Data 0x0004: 0x06
I2C_APP: EEPROM Data 0x0005: 0x07
I2C_APP: EEPROM Data 0x0006: 0x08
I2C_APP: EEPROM Data 0x0007: 0x09
I2C_APP: EEPROM Data 0x0008: 0x0A
I2C_APP: EEPROM Data 0x0009: 0x0B
I2C_APP: EEPROM Data 0x000A: 0x0C
I2C_APP: EEPROM Data 0x000B: 0x0D
I2C_APP: EEPROM Data 0x000C: 0x0E
I2C_APP: EEPROM Data 0x000D: 0x0F
I2C_APP: EEPROM Data 0x000E: 0x10
I2C_APP: EEPROM Data 0x000F: 0x11
I2C_APP: EEPROM Data 0x0010: 0x12
I2C_APP: EEPROM Data 0x0011: 0x13
I2C_APP: EEPROM Data 0x0012: 0x14
I2C_APP: EEPROM Data 0x0013: 0x15
I2C_APP: EEPROM Data 0x0014: 0x16
I2C_APP: EEPROM Data 0x0015: 0x17
I2C_APP: EEPROM Data 0x0016: 0x18
I2C_APP: EEPROM Data 0x0017: 0x19
I2C_APP: EEPROM Data 0x0018: 0x1A
I2C_APP: EEPROM Data 0x0019: 0x1B
I2C_APP: EEPROM Data 0x001A: 0x45
I2C_APP: EEPROM Data 0x001B: 0x31
I2C_APP: EEPROM Data 0x001C: 0x1E
I2C_APP: EEPROM Data 0x001D: 0x1F
I2C_APP: EEPROM Data 0x001E: 0x20
I2C_APP: EEPROM Data 0x001F: 0x21
I2C_APP: EEPROM Program and verify page: 1 ...
I2C_APP: Temperature sensor separate write and read test ...
I2C_APP: Temperature sensor write+read with restart test ...
I2C_APP: Stack Usage: 816 bytes
I2C_APP: DONE (Passed) !!
I2C_APP: All tests have passed