MCUSW
Loading...
Searching...
No Matches
Adc User Guide

Table of Contents

Introduction

This document details AUTOSAR BSW ADC module implementation

  • Supported AUTOSAR Release : 4.3.1
  • Supported Configuration Variants : Post-build, Pre-Compile
  • Vendor ID : ADC_VENDOR_ID (44)
  • Module ID : ADC_MODULE_ID (123)

The ADC module initializes, configures and controls the ADC hardware as detailed in AUTOSAR BSW ADC Driver Specification. Following section highlights key aspects of this implementation, which would be interest for integrator.

Note: This module is applicable only for AM275x device.

Adc Driver Architecture/Design

Please refer the ADC design, which is part of CSP.

Functional Description

Clock Source to adc

Programming of clock source for the adc, is beyond the scope of this document. The driver expects user of this module has programmed required clock source. The example application demonstrates configuring clock sources for the adc.

Back To Top

Adc Sample output

Minimum sampling clock source given as input to the ADC is 25 MHZ and it is observed that ADC hardware samples data faster than CPU reads it. Adc sampled output is inconsistent because of this. So it is reccommended to increase delay parameters AdcChannelAveragingMode, AdcChannelOpenDelay and AdcChannelSampleDelay according to the requirement.

Adc has 4 MSPS rate with a 60 MHz Sampling clock.

Back To Top

Adc Instance, Adc Hw Unit ID mapping and ISR mapping

1 adc instance is supported on AM275X. The following table lists the mapping between instance of hardware and AdcHwUnitId of the configurator

AdcHwUnitId Adc Instance Associated ISR (if notification is enabled)
0 MAIN INSTANCE 0 Adc_IrqUnit0

Back To Top

Configuration

The Adc Driver implementation supports multiple configuration variants (refer section Introduction), the driver expects generated Adc_Cfg.h to be present as (File Structure). Please refer (Build) to specify path to the generated configuration. The associated adc configuration generated files Adc_Cfg.c and Adc_PBcfg.c to be present as shown (File Structure)

The generated configuration files should not be modified manually. The config tool Elektrobit Tresos should be used to modify the configuration files.

Note: For detailed descriptions of all configurable parameters, refer to the design document provided in the CSP package. The document is located at: "$(MCAL_INSTALL_PATH)/mcusw/csp"

The following section details on the un-supported features and additional features added.

Variance / Deviation from the specification

AdcClockReference

To configure the clock source for Adc, one would have to access/configure common registers. It’s recommended that clock sources for the Adc hardware are done in SBL / Start up code.

AdcTimeoutDuration

The timeout value parameter AdcTimeoutDuration to be configured in the configurator plugin should be purely based on R5F core frequency. Driver internally uses MCAL_SW_DELAY() is a SW delay of 9 CPU cycles per iteration.

Note: ADC Hardware Trigger & ADC Power state APIs are not supported.

Implementation Specific Configurations

This driver implementation introduces below listed configurable options.

Please refer the ADC design section NON Standard configurable parameters (Refer to Design Document provided in CSP).

Compile Time Configurations for Performance

  1. ADC_DEV_ERROR_DETECT Control checks of configurations and parameters. Turn OFF to improve performance.
  2. ADC_GROUP_LOG Control checks of group logging. Turn OFF to improve performance.
  3. ADC_FIFO_ERR_LOG Control checks of fifo error logging. Turn OFF to improve performance.

Non Standard Service APIs

Adc_RegisterReadback

As noted from the previous MCAL implementation, some of the critical configuration registers could potentially be corrupted by other entities (s/w or h/w). One of the recommended detection methods would be to periodically read-back the configuration and confirm configuration is consistent. The service API defined below shall be implemented to enable this detection

Service Name Adc_RegisterReadback
Syntax Std_ReturnType Adc_RegisterReadback (Adc_HWUnitType HWUnit, Adc_RegisterReadbackType *RegRbPtr)
Service ID[hex] 0x0F
Sync/Async Synchronous
Reentrancy Non Reentrant
Parameters (in) HWUnit : ADC Hardware microcontroller peripheral unit ID
Parameters (out) RegRbPtr : A pointer of type Adc_RegisterReadbackType, which holds the read back values
Return Value E_OK: Register read back has been done
E_NOT_OK: Register read back failed (in case of Adc not initialized or RegRbPtr is NULL_PTR)
Description Reads the important registers of the hardware unit and returns the value in the structure.

Immediate Register Readback After Write

In addition to the periodic register readback provided by the Adc_RegisterReadback API, an immediate readback-after-write mechanism has been implemented inside the ADC driver (currently supported on j784s4 and j721s2 SOCs). This mechanism ensures that each critical ADC configuration register is verified immediately after being written, allowing early detection of any accidental corruption.

To enable this feature, the configuration flag ADC_REGISTER_READBACK_API must be set.

When ADC_REGISTER_READBACK_API is defined as STD_ON, the ADC driver includes the readback verification macros shown below.

Readback Verification Macros

Two macros are used to perform immediate register verification:

  • HW_RB_CHECK_REG32(regAddr, refVal, errRbFunc) Verifies the full 32-bit register value after a write.
    • regAddr – address of the hardware register
    • refVal – expected value
    • errRbFunc – callback function invoked if verification fails
  • HW_RB_CHECK_FIELD32_VAL(regAddr, REG_FIELD, val, errRbFunc) Verifies only a specific bit-field within a 32-bit register. Used when only part of a register is being updated.

If verification fails, the error callback receives both the expected and actual values.

Registers Covered by Immediate Readback

The following registers are checked immediately after each write:

  • DMAENABLE_SET
  • CONTROL
  • RANGE
  • STEPENABLE
  • FIFO0THRESHOLD
  • FIFO0DMAREQ
  • FIFO1THRESHOLD
  • FIFO1DMAREQ
  • IRQ_ENABLE_SET
  • STEPCONTROL_config_j
  • STEPCONTROL_delay_j

In addition to full-register checks, writes to individual fields within these registers are also verified using the field-verification macro.

Integration Into the ADC Driver

This readback-after-write functionality is built directly into the ADC driver. The implementation is located in the following files:

  • Adc.c
  • Adc_Priv.c

Whenever the driver writes a configuration value:

  1. The value is written to the hardware register.
  2. The corresponding readback macro is executed.
  3. The read value is compared with the expected value.
  4. If a mismatch is detected, the provided error-handling function is called.

Make sure to enable ADC_REGISTER_READBACK_API by setting it to 'STD_ON'.

The file Adc_Priv.h contains a weak declaration of the ADC readback error callback:

void Adc_RdbckErrCbk(uint32 expVal, uint32 readVal) __attribute__((weak));

If your application requires custom handling when a register readback mismatch occurs, provide your own implementation of Adc_RdbckErrCbk() in your project.

Use Case Examples

1. Verifying a specific field within a register

/* Set range value */
HW_WR_FIELD32(
baseAddr + ADC_REGISTER,
BIT_MASK,
bitValue);
/* Verify that the correct field value was written */
HW_RB_CHECK_FIELD32_VAL(
baseAddr + ADC_REGISTER,
BIT_MASK,
bitValue,
Adc_RdbckErrCbk);

1. Verifying a full 32-bit register

/* Write to the register */
HW_WR_REG32(baseAddr + ADC_REGISTER, registerValue);
/* Verify the entire register value */
HW_RB_CHECK_REG32(
baseAddr + ADC_REGISTER,
registerValue,
Adc_RdbckErrCbk);

Back To Top

Interrupt Configuration

The Driver doesn’t register any interrupts handler (ISR), it’s expected that consumer of this driver registers the required interrupt handler.

For every Adc hardwarebunit with notification enabled, an ISR requires to be registered. The Interrupt number associated with instance of the Adc is detailed in TRM (also, please refer the demo application). Please refer AdcApp_InterruptConfig () in Adc demo application.

Refer section (Adc Instance, Adc Hw Unit ID mapping and ISR mapping), for association between hw unit ID and ISR

Back To Top

Power-up

The driver doesn't configure the functional clock and power for the adc modules. Its expected that SBL power-up the required modules. Please refer SBL documentation.

Back To Top

Build and Running the Example Application

Please follow steps detailed in section (Build) to build library or example

Back To Top

Example Application

  • Support both Post Build and Pre Compile Configuration Variants
  • For each Configured hardware unit id, with default configuration provided in the release
    • Configured 2 groups, one with One shot mode and HW Unit assigned is ADC_0
    • Second group with Continuous mode assigned to ADC_1.

Back To Top

Steps to run example application

Please refer (Running Examples)

Back To Top

Memory Mapping

Various objects of this implementation (e.g. variables, functions, constants) are defined under different sections. The linker command file at (Examples Linker File (Select memory location to hold example binary)) defines separate section for these objects. When the driver is integrated, its expected that these sections are created and placed in appropriate memory locations. (Locations of these objects depend on the system design and performance needs)

Section ADC_CODE ADC_VAR ADC_VAR_NOINIT ADC_CONST ADC_CONFIG
ADC_DATA_NO_INIT_UNSPECIFIED_SECTION USED
ADC_DATA_INIT_32_SECTION USED
ADC_TEXT_SECTION USED
ADC_DATA_INIT_UNSPECIFIED_SECTION USED
ADC_CONST_32_SECTION USED
ADC_ISR_TEXT_SECTION USED
ADC_CONFIG_SECTION USED

Back To Top

Cache

This driver implementation has been validated with cache enabled. For optimal performance it’s recommended to place (Memory Mapping) sections in cache enabled memory area.

Back To Top

Dependencies on SW Modules

DET

This implementation depends on the DET in order to report development errors and can be turned OFF. Refer section (Development Error Reporting) for detailed error codes.

Back To Top

SchM

This implementation requires 1 level of exclusive access to guard critical sections. Invokes SchM_Enter_Adc_ADC_EXCLUSIVE_AREA_0 (), SchM_Exit_Adc_ADC_EXCLUSIVE_AREA_0 () to enter critical section and exit.

In the example implementation (File Structure SchM_Adc.c) , all the interrupts on CPU are disabled. However, disabling of the enabled Adc interrupt should suffice.

Back To Top

File Structure

Detailed Directory Structure
  1. Driver implemented by : Adc.h, Adc_Irq.h, Adc.c, Adc_Utils.c, Adc_Irq.c, Adc_Priv.c and Adc_Priv.h
  2. Example Configuration by : Adc_Cfg.h, Adc_Cfg.c and Adc_PBcfg.c
  3. Example Application by : AdcApp.c and AdcApp.h

Back To Top

Error Handling

Development Error Reporting

Development errors are reported to the DET using the service Det_ReportError(), when enabled. The driver interface (Adc.h File Structure) lists the SID

Back To Top

Error codes

Type of Error Related Error code Value (Hex)
API service called without module initialization ADC_E_UINIT 0x0A
API service called when adc group conversion ongoing ADC_E_BUSY 0x0B
API service for initialization is called when already initialized ADC_E_ALREADY_INITIALIZED 0x0D
API parameter checking: invalid config ADC_E_PARAM_CONFIG 0xE
API parameter checking: invalid pointer ADC_E_PARAM_POINTER 0x14
API parameter checking: invalid group id ADC_E_PARAM_GROUP 0x15
API parameter checking: invalid conversion mode ADC_E_WRONG_CONV_MODE 0x16
API parameter checking: invalid trigger source ADC_E_WRONG_TRIGG_SRC 0x17
API parameter checking: No notification configured ADC_E_NOTIF_CAPABILITY 0x18
API parameter checking: Result Buffer not initialized ADC_E_BUFFER_UNINIT 0x19
API parameter checking: Group/Channel not in idle state ADC_E_NOT_DISENGAGED 0x1A
API parameter checking: Unsupported power state request ADC_E_POWER_STATE_NOT_SUPPORTED 0x1B
API parameter checking: Requested power state can not be reached directly. ADC_E_TRANSITION_NOT_POSSIBLE 0x1C
API parameter checking: ADC not prepared for target power state. ADC_E_PERIPHERAL_NOT_PREPARED 0x1D

Back To Top

Production Code Error Reporting

Production error are reported to DEM via the service DEM_SetEventStatus(). In addition to standard errors, this implementation reports "ADC_E_HARDWARE_ERROR" when ADC HW calibration/FSM state fails.

Back To Top

Safety Diagnostic Features

ADC1A - Converter Self-Test

ADC supports a "self-test" mode where the input is tested against known reference voltages with an expected output. A full scale value is expected when the internal reference is REFP (Vref), and half-scale when connected to VMID (Vref).

ADC1B - Converter Calibration Test

ADC supports a "self-test" mode where the input is tested against known reference voltages with an expected output. A full scale value is expected when the internal reference is REFP (Vref), and half-scale when connected to VMID (Vref).

ADC4 - Software Readback of Written Configuration / ADC5 - Periodic Software Readback of Static Configuration Registers

Software Readback of Written Configuration ensures that the configuration register are written with the expected value. Periodic readback of configuration registers can provide a diagnostic for inadvertent writes to these registers.

The ADC MCAL driver provides the API - Adc_RegisterReadback() to readback static and written configuration registers to implement this diagnostic feature.

Back To Top

API Description

  • All Api's particular to enabling and disabling hardware trigger of hardware triggered channel groups and management of hardware low-power states are not supported.

Refer API Documentation for details

Back To Top

Example Application

The example application demonstrates use of Adc module, the list below identifies key steps performed the example. The configuration file is present at (File Structure)

  • Initializes “Result Status Flag”
  • AdcApp_Startup ()
    • Builds interrupt list and registers ISR for enabled Adc instance
  • AdcApp_PowerAndClkSrc ()
    • Sets up clock sources for the adc modules
  • AdcApp_mainTest ()
    • For each enabled instance
      • Initialize Adc driver with configured conversion modes
      • Set Up Result Buffer
      • Enable group notification if notify capability is ON
      • Start ADC Conversion
      • Wait for conversion to get complete
      • Disable group notification if notify capability is ON
      • Stop ADC Conversion(Explicitly only in case of continuous mode)
      • Prints Conversion Results
      • De-Initialize Adc driver
  • Checks for error status and stack corruption.

Back To Top

Example Log

    ADC_APP: Sample Application - STARTS !!!
    ADC_APP: Variant - Post Build being used !!!
    ADC_APP: GROUPs 2: HWUNIT 2: LOOP COUNT 5: NUM STREAMS 1:!!!

    ADC_APP:  ADC MCAL Version Info
    ADC_APP: ---------------------
    ADC_APP:  Vendor ID           : 44
    ADC_APP:  Module ID           : 123
    ADC_APP:  SW Major Version    : 0
    ADC_APP:  SW Minor Version    : 1
    ADC_APP:  SW Patch Version    : 0


     Result Buffer Content
     ---------------------
     ADC Group 0 Log:
     ----------------
     Channel    Stream    HW_CH       ADC Value    Volt
     ----------------------------------------------------
     0          0         ADC_IN0     0x00000da7  1536 mV
     ADC Group 1 Log:
     ----------------
     Channel    Stream    HW_CH       ADC Value    Volt
     ADC Group 0 Log:
     ----------------
     Channel    Set Idx   HW_CH       ADC Value    Volt
     ----------------------------------------------------
     0          0         ADC_IN0     0x00000d99  1530 mV
     0          1         ADC_IN0     0x00000dae  1539 mV
     0          2         ADC_IN0     0x00000db0  1540 mV
     0          3         ADC_IN0     0x00000da8  1536 mV
     0          4         ADC_IN0     0x00000da7  1536 mV
     ADC Group 1 Log:
     ----------------
     Channel    Set Idx   HW_CH       ADC Value    Volt
     ----------------------------------------------------
     0          0         ADC_IN0     0x00000dbe  1546 mV
     0          1         ADC_IN0     0x00000f1a  1699 mV
     0          2         ADC_IN0     0x00000f20  1701 mV
     0          3         ADC_IN0     0x00000f20  1701 mV
     0          4         ADC_IN0     0x00000f20  1701 mV
     Warning: ADC Group 1 values are out of range!!
    ADC_APP: ADC Stack Usage: 816 bytes
    ADC_APP: ADC Test Passed!!!
    ADC_APP: Sample Application - DONE !!!

Back To Top

Log for AM275x device

    ADC_APP: Sample Application - STARTS !!!
    MCU Initialized!
    Module clock frequency set. Module = 98 , Freq = 60000000 !!!
    ADC_APP: Variant - Post Build being used !!!

    ADC_APP: GROUPs 1: HWUNIT 1: LOOP COUNT 5: NUM STREAMS 1:!!!

    ADC_APP:  ADC MCAL Version Info
    ADC_APP: ---------------------
    ADC_APP:  Vendor ID           : 44
    ADC_APP:  Module ID           : 123
    ADC_APP:  SW Major Version    : 9
    ADC_APP:  SW Minor Version    : 1
    ADC_APP:  SW Patch Version    : 0

    ADC_APP: ADC INTERNAL DIAGNOSTIC DEBUG MODE Test
    ADC_APP: ADC_UNIT_0 Internal Diagnostic Debug Mode - Enabled

    Result Buffer Content
    ---------------------
    ADC Group 0 Log:
    ----------------
    Channel    Stream    HW_CH       ADC Value    Volt
    ----------------------------------------------------
    0          0         ADC_IN0     0x00000ff4  1795 mV
    1          0         ADC_IN1     0x00000ff4  1795 mV
    2          0         ADC_IN2     0x00000ff4  1795 mV
    3          0         ADC_IN3     0x00000ff3  1794 mV
    4          0         ADC_IN4     0x00000ff4  1795 mV
    5          0         ADC_IN5     0x00000ff4  1795 mV
    6          0         ADC_IN6     0x00000ff5  1795 mV
    7          0         ADC_IN7     0x00000ff4  1795 mV

    Read Buffer Content
    -------------------
    ADC Group 0 Log:
    ----------------
    Channel    Set Idx   HW_CH       ADC Value    Volt
    ----------------------------------------------------
    0          0         ADC_IN0     0x00000ff3  1794 mV
    0          1         ADC_IN0     0x00000ff4  1795 mV
    0          2         ADC_IN0     0x00000ff4  1795 mV
    0          3         ADC_IN0     0x00000ff4  1795 mV
    0          4         ADC_IN0     0x00000ff4  1795 mV
    1          0         ADC_IN1     0x00000ff4  1795 mV
    1          1         ADC_IN1     0x00000ff4  1795 mV
    1          2         ADC_IN1     0x00000ff4  1795 mV
    1          3         ADC_IN1     0x00000ff4  1795 mV
    1          4         ADC_IN1     0x00000ff4  1795 mV
    2          0         ADC_IN2     0x00000ff3  1794 mV
    2          1         ADC_IN2     0x00000ff4  1795 mV
    2          2         ADC_IN2     0x00000ff4  1795 mV
    2          3         ADC_IN2     0x00000ff4  1795 mV
    2          4         ADC_IN2     0x00000ff4  1795 mV
    3          0         ADC_IN3     0x00000ff4  1795 mV
    3          1         ADC_IN3     0x00000ff4  1795 mV
    3          2         ADC_IN3     0x00000ff4  1795 mV
    3          3         ADC_IN3     0x00000ff4  1795 mV
    3          4         ADC_IN3     0x00000ff3  1794 mV
    4          0         ADC_IN4     0x00000ff4  1795 mV
    4          1         ADC_IN4     0x00000ff3  1794 mV
    4          2         ADC_IN4     0x00000ff4  1795 mV
    4          3         ADC_IN4     0x00000ff4  1795 mV
    4          4         ADC_IN4     0x00000ff4  1795 mV
    5          0         ADC_IN5     0x00000ff3  1794 mV
    5          1         ADC_IN5     0x00000ff4  1795 mV
    5          2         ADC_IN5     0x00000ff4  1795 mV
    5          3         ADC_IN5     0x00000ff4  1795 mV
    5          4         ADC_IN5     0x00000ff4  1795 mV
    6          0         ADC_IN6     0x00000ff4  1795 mV
    6          1         ADC_IN6     0x00000ff3  1794 mV
    6          2         ADC_IN6     0x00000ff4  1795 mV
    6          3         ADC_IN6     0x00000ff4  1795 mV
    6          4         ADC_IN6     0x00000ff5  1795 mV
    7          0         ADC_IN7     0x00000ff4  1795 mV
    7          1         ADC_IN7     0x00000ff4  1795 mV
    7          2         ADC_IN7     0x00000ff4  1795 mV
    7          3         ADC_IN7     0x00000ff4  1795 mV
    7          4         ADC_IN7     0x00000ff4  1795 mV

    ADC_APP: ADC_UNIT_0 Internal Diagnostic Debug Mode - Disabled

    ADC_APP: ADC Functional Operation Test

    Result Buffer Content
    ---------------------
    ADC Group 0 Log:
    ----------------
    Channel    Stream    HW_CH       ADC Value    Volt
    ----------------------------------------------------
    0          0         ADC_IN0     0x00000ffa  1797 mV
    1          0         ADC_IN1     0x00000ffc  1798 mV
    2          0         ADC_IN2     0x00000ffc  1798 mV
    3          0         ADC_IN3     0x00000ffe  1799 mV
    4          0         ADC_IN4     0x00000ffb  1798 mV
    5          0         ADC_IN5     0x00000ffa  1797 mV
    6          0         ADC_IN6     0x00000ffb  1798 mV
    7          0         ADC_IN7     0x00000ffd  1799 mV

    Read Buffer Content
    -------------------
    ADC Group 0 Log:
    ----------------
    Channel    Set Idx   HW_CH       ADC Value    Volt
    ----------------------------------------------------
    0          0         ADC_IN0     0x00000ffb  1798 mV
    0          1         ADC_IN0     0x00000ffc  1798 mV
    0          2         ADC_IN0     0x00000ffc  1798 mV
    0          3         ADC_IN0     0x00000ffb  1798 mV
    0          4         ADC_IN0     0x00000ffa  1797 mV
    1          0         ADC_IN1     0x00000ffc  1798 mV
    1          1         ADC_IN1     0x00000ffe  1799 mV
    1          2         ADC_IN1     0x00000ffd  1799 mV
    1          3         ADC_IN1     0x00000ffd  1799 mV
    1          4         ADC_IN1     0x00000ffc  1798 mV
    2          0         ADC_IN2     0x00000ffc  1798 mV
    2          1         ADC_IN2     0x00000ffd  1799 mV
    2          2         ADC_IN2     0x00000ffd  1799 mV
    2          3         ADC_IN2     0x00000ffc  1798 mV
    2          4         ADC_IN2     0x00000ffc  1798 mV
    3          0         ADC_IN3     0x00000ffe  1799 mV
    3          1         ADC_IN3     0x00000ffd  1799 mV
    3          2         ADC_IN3     0x00000ffe  1799 mV
    3          3         ADC_IN3     0x00000ffe  1799 mV
    3          4         ADC_IN3     0x00000ffe  1799 mV
    4          0         ADC_IN4     0x00000ffa  1797 mV
    4          1         ADC_IN4     0x00000ffb  1798 mV
    4          2         ADC_IN4     0x00000ffc  1798 mV
    4          3         ADC_IN4     0x00000ffb  1798 mV
    4          4         ADC_IN4     0x00000ffb  1798 mV
    5          0         ADC_IN5     0x00000ffa  1797 mV
    5          1         ADC_IN5     0x00000ffb  1798 mV
    5          2         ADC_IN5     0x00000ffc  1798 mV
    5          3         ADC_IN5     0x00000ffa  1797 mV
    5          4         ADC_IN5     0x00000ffa  1797 mV
    6          0         ADC_IN6     0x00000ffb  1798 mV
    6          1         ADC_IN6     0x00000ffc  1798 mV
    6          2         ADC_IN6     0x00000ffc  1798 mV
    6          3         ADC_IN6     0x00000ffa  1797 mV
    6          4         ADC_IN6     0x00000ffb  1798 mV
    7          0         ADC_IN7     0x00000ffc  1798 mV
    7          1         ADC_IN7     0x00000ffd  1799 mV
    7          2         ADC_IN7     0x00000ffc  1798 mV
    7          3         ADC_IN7     0x00000ffa  1797 mV
    7          4         ADC_IN7     0x00000ffd  1799 mV

    ADC_APP: ADC Stack Usage: 2940 bytes
    ADC_APP: All tests have passed!!!
    ADC_APP: Sample Application - DONE !!!

Back To Top

References

Back To Top