4.3. CDD_I2C

4.3.1. Introduction

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

Supported AUTOSAR Release:

4.3.1

Supported Configuration Variants:

Pre-Compile

Vendor ID:

I2C_VENDOR_ID (44) (TEXAS INSTRUMENTS)

Module ID:

CDD_IPC_MODULE_ID (255)

Supported Platform:

AM273x

The I2C component is a proprietary extension of AUTOSAR BSW. The I2C driver was designed similar to the SPI driver specifications and is compatible to AUTOSAR 4.3.1.

4.3.2. I2C Driver Architecture

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

../_images/i2c_architecture.png

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_PollingModeProcessing() and after these functional calls call Cdd_I2c_MainFunction to process any sequence in the queue and update the status of the queue to real time value.

4.3.3. Functional Description

4.3.3.1. Features and Additions/Extensions

On AM273x platform, there are 4 I2C instances I2C0, I2C1, I2C2 and I2C3 each consisting of 25 registers for control, data transmission and reception.

Supported

Not Supported

Configurable Development error (Software supported)

Multi master mode (Software limitation)

Configurable No acknowledgement error check (Software supported)

DMA mode (Software limitation)

Configurable Arbitration loss error check (Software supported)

Polling mode (Software supported)

Interrupt mode (Software supported)

Configurable multiple sequence in queue check (Software supported)

Configurable arbitration loss parameter (Software supported)

Configurable timeouts for reception, arbitration loss and queue (Software supported)

Configurable queue size (Software supported)

Configurable sequence size (Software supported)

Configurable channel size (Software supported)

Configurable data length (Software supported)

Configurable Hardware units (Hardware supported)

Configurable Channels (Software supported)

Configurable Sequences (Software supported)

Shareable channels (Software supported)

Channel in use checks (Software supported)

Sequence in use checks (Software supported)

Hardware unit in use checks (Software supported)

7 and 10 bit address schemes (Hardware supported)

4.3.3.1.1. Configurable Development Error

  1. User configurable error check to report development errors.

  2. Blocking error

4.3.3.1.2. Configurable No Acknowledgement Error Check

  1. User configurable check to treat a no acknowledgement condition as a development error

  2. Applicable only when AM273x is in master receiving mode

4.3.3.1.3. Configurable Arbitration Loss Error Check

  1. User configurable check to treat an arbitration loss condition as a development error.

  2. Applicable in both master receive and master transmit mode for AM273x

4.3.3.1.4. Configurable Multiple Sequences in Queue Check

  1. User configurable check to process the same sequence multiple times or only once inside the queue

4.3.3.1.5. Configurable Arbitration Loss Parameter

  1. User configurable parameter to deal with arbitration loss condition

  2. Possible parameters

    • CDD_I2C_BURST_MODE

      I2c driver detaches from the bus without any recovery attempts.

    • CDD_I2C_RECURRENT_MODE

      I2c driver sends multiple stop signals on the bus in an attempt to free the bus and recover control.

../_images/i2c_config.png

4.3.3.1.6. Configurable Timeouts

  1. User configurable timeout for queue, reception in polling mode and arbitration loss

  2. All the timeout periods are in ticks

  3. It is user responsibility to initialize and start the timer in the application for timeouts to take effect

4.3.3.1.7. Configurable Queue, Sequence and Channel Size

  1. User configurable maximum size for Sequence, Queue and Channel

4.3.3.1.8. Configurable Hardware Units

  1. User configurable parameter to define how many Hardware Units (Instances) to use out of a maximum of 4

  2. User configurable parameter to specify which Hardware Unit to use

  3. User configurable parameter to specify Serial clock frequency (Channel bit rate)

  4. User configurable parameter to specify the frequency at which the Hardware Unit will operate internally

  5. User configurable input frequency to I2c module which will be used to set channel bit rate and I2c internal operational frequency. Please note that this frequency should be the same as the clock source selected in MCU module, this has to be maintained by the user.

../_images/i2c_confighw.png

4.3.3.1.9. Configurable Channels

  1. User configurable parameter to define channel direction (read or write), I2c Slave address, address scheme (7 bit slave address or 10 bit slave address) and chained channel implementation.

  2. A channel is the actual unit which contains the data to be transmitted along with direction(read/write) and slave address.

  3. The number of channels configured can not exceed the maximum number of channels defined in the general container.

  4. Data buffer is linked to channels in the application by provided API’s

  5. Same channels can be used by multiple sequences

../_images/i2c_configchannel.png

4.3.3.1.10. Configurable Sequences

  1. User configurable parameter to define which Hardware unit to use, number of channels present in the sequence, sequence complete callback function and sequence error notify callback function

  2. Sequences are accessible to the user and are passed as function parameters for transmission and reception

../_images/i2c_configseq.png

4.3.3.1.11. Channel in Use Checks

  1. Channels in free state, i.e. not currently being transmitted by another sequence or the same sequence are available for transmission/reception

4.3.3.1.12. Sequence in Use Checks

  1. Sequence not in transmission currently are available for use.

4.3.3.1.13. Hardware Unit in Use Checks

  1. Hardware not in use, i.e. currently not transmitting/receiving any sequence is available for use.

4.3.3.2. Features Provided Beyond the AUTOSAR Standard

  1. Hardware configuration unit container to handle different hardware units

  2. Hardware configuration unit container to handle transfer speeds and hardware unit mapping. Parallel sequence and channel processing on different hardware units. Configure acknowledge and no acknowledge handling (ACK, NACK). Configurable addressing for standard (7bit) and extended (10bit) addresses.

  3. I2C chain channel feature.

  4. I2C sequence queuing feature.

  5. I2C support for parallel handling of hardware units if more than one is available.

  6. I2C improved error handling like:

    • Handling for SDA stuck scenario

    • Handling for SCL low held scenario

    • Handling for general communication timeout

4.3.3.3. Initialization

The driver I2C is initialized by calling Cdd_I2c_Init () with a null pointer passed as argument. To re-initialize the driver call I2c_DeInit () and then I2c_Init () again. Only pre-compile variant is supported for the driver, hence all configuration related parameters are provided through the GUI. The service for de-initialization is provided with the function Cdd_I2c_DeInit ().

4.3.3.4. I2C maintains states for:

  1. Driver

    • CDD_I2C_UNINIT

      1. Driver is uninitialized

      2. Cdd_I2c_Init () has not been called or Cdd_I2c_DeInit () has been called after initialization

    • CDD_I2C_IDLE

      1. Driver is currently free, not in the middle of any transmission/reception process

    • CDD_I2C_BUSY

      1. Driver is currently in use, transmission/reception in process

    The state for I2c driver is returned with Cdd_I2c_GetStaus() function call.

  2. Channels:-

    • CDD_I2C_CH_RESULT_OK

      1. Channel transmission/reception not yet started

      2. Channel transmission/reception successful

    • CDD_I2C_CH_RESULT_IN_PROGRESS

      1. Channel transmission/reception currently in progress

    • CDD_I2C_CH_RESULT_BUS_FAIL

      1. Channel transmission/reception failed due to bus fault

    • CDD_I2C_CH_RESULT_ARBFAIL

      1. Channel transmission/reception failed due to arbitration loss

    • CDD_I2C_CH_RESULT_NACKFAIL

      1. Channel transmission/reception failed due to no acknowledge

    The channel status is returned with Cdd_I2c_GetResult() function call. In case incorrect channel ID is passed a DET error occur

  3. Sequences:-

    • CDD_I2C_SEQ_OK

      1. Sequence transmission/reception not yet started

      2. Sequence transmission/reception successful

    • CDD_I2C_SEQ_PENDING

      1. Sequence transmission/reception in progress

    • CDD_I2C_SEQ_QUEUED

      1. Sequence queued

    • CDD_I2C_SEQ_NACK

      1. Sequence failed due to no acknowledge

    • CDD_I2C_SEQ_FAILED

      1. Sequence transmission/reception failed

    • CDD_I2C_SEQ_CANCELLED

      1. Sequence cancelled

    The sequence status is returned with Cdd_I2c_GetSequenceResult

  4. Hardware Units:-

    • CDD_I2C_HW_UNIT_FREE

      1. Hardware Unit not in use

    • CDD_I2C_HW_UNIT_BUSY

      1. Hardware Unit busy

4.3.4. File Structure

The delivery of the I2C contains the files which are described in the chapters 4.10.4.1 and 4.10.4.2:

4.3.4.1. Static files

Cdd_I2c.c

Source file that contains the API relevant implementation

Cdd_I2c.h

Header file that contains all API relevant declarations

Cdd_I2c_Irq.c

Contains the ISR implementation

Cdd_I2c_Irq.h

Contains the declarations of the ISR handlers

Cdd_I2c_Priv.h

Contains internal function declarations used to realize the driver

Cdd_I2c_Priv.c

Contains internal function definitions used to realize the driver

Cdd_I2c_hw_reg.h

Contains register offsets, mask values, shift values and specific bit set/reset macros

4.3.4.2. Dynamic files

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

This file contains the configured sequence, channel and hardware configurations, along with I2c instance base address.
../_images/i2c_filestructure.png

4.3.5. 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_VAR1

I2C_VAR_NO_INIT

I2C_VAR_INIT

CDD_VAR_ZERO_INIT

I2C_CONST

I2C_PBCFG

I2C_APPL_CODE

I2C_APPL_DATA

I2C_START_SEC_CODE I2C_STOP_SEC_CODE

●

I2C_START_SEC_CODE_ISR I2C_STOP_SEC_CODE_ISR

●

I2C_START_SEC_PBCFG_ROOT I2C_STOP_SEC_PBCFG_ROOT

●

I2C_START_SEC_PBCFG I2C_STOP_SEC_PBCFG

●

I2C_START_SEC_CONST_32BIT I2C_STOP_SEC_CONST_32BIT

●

I2C_START_SEC_CONST_UNSPECIFIED I2C_STOP_SEC_CONST_UNSPECIFIED

●

I2C_START_SEC_VAR_NOINIT_UNSPECIFIED I2C_STOP_SEC_VAR_NOINIT_UNSPECIFIED

●

I2C_START_SEC_VAR_INIT_UNSPECIFIED I2C_STOP_SEC_VAR_INIT_UNSPECIFIED

●

I2C_START_SEC_VAR_ZERO_INIT_UNSPECIFIED I2C_STOP_SEC_VAR_ZERO_INIT_UNSPECIFIED

●

Application buffers passed to I2C

●

Notification called from I2C

●

4.3.6. Services used by I2C driver

Service ID

Service

0x00

CDD_I2C_Init

0x01

CDD_I2c_DeInit

0x02

CDD_I2c_GetVersionInfo

0x03

CDD_I2c_SetupEB

0x04

CDD_I2c_SetupEBDynamic

0x05

CDD_I2c_AsyncTransmit

0x06

CDD_I2c_Cancel

0x07

CDD_I2c_GetResult

0x08

CDD_I2c_GetSequenceResult

0x09

CDD_I2c_MainFunction

0x0A

CDD_2c_PollingModeProcessing

0x0B

Cdd_I2c_SetHandling

4.3.7. Dependencies on SW modules

4.3.7.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.3.7.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.3.7.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.3.7.4. SchM (Optional)

Beside the OSEK / AUTOSAR OS the Schedule Manager provides functions that module I2C calls at begin and end of critical sections.

4.3.8. API Description

All below mentioned API’s are user accessible and can be found in Cdd_I2c.c file

4.3.8.1. Supported API’s

4.3.8.1.1. void Cdd_I2c_Init( Cdd_I2c_ConfigPtrType* configPtr)

  1. Argument passed to the function in NULL_PTR

  2. Function returns void

  3. Function is used to initialize all configured hardware units at specified frequencies

  4. Function initializes queue to default values

4.3.8.1.2. Std_ReturnType Cdd_I2c_DeInit(void)

  1. Function used to de-initialize all initialized I2c Hardware Units

  2. Returns success upon successful initialization

  3. Function can not be called in case driver is uninitialized

4.3.8.1.3. void Cdd_I2c_GetVersionInfo(Cdd_I2c_VersionInfoPtrType * versionInfoPtr)

  1. Argument passed to the function is a valid pointer of type Cdd_I2c_VersionInfoPtrType

  2. Function stores Version information in pointer

  3. Function returns void

4.3.8.1.4. Std_ReturnType Cdd_I2c_SetupEB(I2c_ChannelType channelId, Cdd_I2c_DataPtrType txDataBufferPtr, Cdd_I2c_DataPtrType rxDataBufferPtr, Cdd_I2c_DataLengthType length)

  1. Function sets up buffer for reception or transmission based on preconfigured channel ID’s passed as argument

  2. Buffer pointer to store data for transmission/reception passed as argument

  3. Length of message to read or write to slave device passed as argument

  4. Both buffers can not be passed as NULL_PTR

  5. Both buffers can not be passed as valid pointers

  6. Pre-configured direction of the channel set up in the GUI should be maintained here as well to avoid development errors

  7. Function returns success or failure

4.3.8.1.5. Std_ReturnType Cdd_I2c_SetupEBDynamic(I2c_ChannelType channelId, Cdd_I2c_AddressType address, Cdd_I2c_DataPtrType txDataBufferPtr, Cdd_I2c_DataPtrType rxDataBufferPtr, Cdd_I2c_DataLengthType length)

  1. Function to set up buffer for reception or transmission of channel based on pre- configured channel ID’s passed as argument with a re-configurable slave address at run time

  2. Buffer pointer to store data for transmission/reception passed as argument

  3. Both Buffers can not be passed as NULL_PTR

  4. Both buffers can not be passed as valid pointers

  5. Valid slave address to be passed as an argument

  6. Pre-configured direction of the channel set up in the GUI should be maintained here as well to avoid development errors

  7. Function returns success or failure

4.3.8.1.6. Std_ReturnType Cdd_I2c_AsyncTransmit(I2c_SequenceType sequenceId)

  1. Function use to transmit a sequence to receive/transmit data on the I2c bus

  2. Sequence ID passed as parameter to the function

  3. Transmission through this function can take place in both polling mode as well as interrupt mode

  4. Reception through this function can only take place in interrupt mode

  5. In case a sequence is not completed due to some reason, it is queued

  6. Function returns success or failure

4.3.8.1.7. Std_ReturnType Cdd_I2c_Cancel(I2c_SequenceType sequenceId)

  1. Function used to deque a sequence in queue

  2. Sequence ID passed as argument

  3. An ongoing sequence in transmission from queue can not be cancelled

  4. Function returns success or failure

4.3.8.1.8. Cdd_I2c_ChannelResultType Cdd_I2c_GetResult(I2c_ChannelType channelId)

  1. Function returns the channel result upon call, results depends on completion, failure or processing of a channel

  2. Channel ID passed as a parameter

  3. For return values check section 3.4->2

4.3.8.1.9. Cdd_I2c_SeqResultType Cdd_I2c_GetSequenceResult(I2c_SequenceType sequenceId)

  1. Function returns the sequence result, result depends upon completion, failure or processing of a sequence

  2. Sequence ID passed as a parameter

  3. For return values check section 3.4->3

4.3.8.1.10. void Cdd_I2c_MainFunction(void)

  1. Function used to process all the sequences in Queue and update sequence status accordingly

  2. Function returns void

  3. Function should be called periodically at the end

4.3.8.1.11. void Cdd_I2c_PollingModeProcessing(void)

  1. Function used to receive data from the I2c bus in polling mode

  2. Function returns void

  3. Function process all sequences and receives data for all channels configured for read in one call

  4. Only to be used in polling mode

4.3.8.1.12. void Cdd_I2c_SetHandling(Cdd_I2c_HandlingType handling)

  1. Function used to handle arbitration loss condition

  2. Handling parameter configured through GUI passed as argument

  3. Function can either attempt to recover the bus control or detach from the bus after de-initializing the driver depending on the argument passed

  4. See section 3.1->5 for possible values of input parameter for function

4.3.8.1.13. Cdd_I2c_ComponentStatusType Cdd_I2c_GetStatus(void)

  1. Function used to return driver status

  2. Requires no argument to be passed

  3. See section 3.4->1 for possible return values

4.3.8.2. Type definitions

The external visible and usable types defined by the I2C are described in this chapter.

TypeName

C-Type

Description

Value Range

Cdd_I2c_ComponentStatusType

enum

States of the I2C driver

I2C_UNINIT, driver is not initialized. I2C_IDLE, driver is initialized and ready. I2C_BUSY, driver is processing at least one sequence’s transmission process.

Cdd_I2c_ChannelResultType

enum

The result of a channel

I2C_CH_RESULT_OK, channel has finished successfully. I2C_CH_RESULT_BUSFAIL, bus failure detected. I2C_CH_RESULT_ARBFAIL, arbitration failure detected. I2C_CH_RESULT_NACKFAIL, nack failure detected

Cdd_I2c_HW_cfg

Enum

Structure for CDD_I2C which contains Hw unit initialization parameters

System clock frequency being used by the I2C instance

Cdd_I2c_SeqResultType

Enum

States of the sequence.

I2C_SEQ_OK, sequence finished normal. I2C_SEQ_PENDING, a sequence is in progress or queued. I2C_SEQ_QUEUED, sequence is queued. I2C_SEQ_NACK, sequence encountered a NACK signal. I2C_SEQ_FAILED, sequence failed due to error. I2C_SEQ_CANCELLED, sequence was cancelled by request.

Cdd_I2c_HandlingType

enum

Variants of timeout handling

I2C_BURST, no timeout observation. I2C_RECURRENT, perform countermeasure in case of timeout.

Cdd_I2c_AddressType

uint16

Address for bus clients.

16 bits

Cdd_I2c_DataType

uint8

Data format of the I2c used for transmission and reception

8 bits

Cdd_I2c_DataLengthType

uint16

Type for any length Parameter

16 bits.

Cdd_I2c_DataPtrType

uint8 *

Pointer type for general buffer handling.

32 bits.

Cdd_I2c_DataConstPtrType

const uint8 *

Pointer type for TX buffer handling

32 bits

Cdd_I2c_SequenceType

uint8

Type for sequence identifier

8 bits

Cdd_I2c_ChannelType

uint8

Type for channel identifier

8 bits

4.3.9. Configurable callback functions

4.3.9.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.3.9.2. I2c_SequenceCompleteNotification

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.3.9.3. 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_DeInit

  2. Cdd_I2c_GetVersionInfo

  3. Cdd_I2c_SetupEB

  4. Cdd_I2c_SetupEBDynamic

  5. Cdd_I2c_AsyncTransmit

  6. CDD_I2c_Cancel

  7. Cdd_I2c_GetResult

  8. Cdd_I2c_GetSequenceResult

  9. Cdd_I2c_MainFunction

  10. Cdd_I2c_PollingModeProcessing

  11. Cdd_I2c_SetHandling

  12. Cdd_I2c_GetStatus

4.3.10. Error Handling

  • 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.3.11. Example Application

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=am273”. The details of running the application and the setup required is part of the MCAL User Guide present in <MCAL_ROOT>/mcal_docs/User guide/MCAL_UserGuide.pdf.

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