Autosar MCAL layer ADC Driver API’s and data types explanation

Blog
_ _ Kunal Gupta_ 0 Comments
API name: Adc_Init() 
void Adc_Init (const Adc_ConfigType* ConfigPtr)
  • Role: Adc_Init() API initializes the ADC peripheral of the microcontroller. This API is universal and used across all automotive MCUs for initializing the ADC peripheral of the corresponding MCU. This API initializes the registers of ADC peripherals internally. So function definition of Adc_Init () would be different for different SoCs. But in applications across all automotive MCUs, this API name and syntax would be used to initialize the ADC peripheral according to the Adc_ConfigType structure.
  • Working of this API:  This API calls the low-level functions that configure the ADC clock, prescaler, and trigger mode. This API initializes all the ADC instances, according to their configurations for ADC Hardware Unit. This API does not configure the pins of the MCU to analog pins. That part has to be done by the Port or MCU driver.
  • Parameter passed: The parameter that is passed to this API is of Adc_ConfigType data type. Adc_ConfigType is a structure that contains the set of configuration parameters for initializing the ADC Driver and ADC HW units. The object of this data type is generated and defined by the configurator tool. We users don’t have to initialize this object. It is automatically configured based on the configuration we do on the GUI. We just have to send the object of Adc_ConfigType with ampersand (&) to this API.
  • Chronology to use this API: This API is used in the beginning of main(). Just after the system clock and ADC pins are configured by their respective APIs.
  • Return value: This function does not return anything. As it only initializes the internal peripheral registers. But just to check and verify the function, you can observe the changes in ADC HW unit registers just after executing this function.
  • Syntax to use this API: 
 Adc_Init(&Adc_Config_VS_0);

ADC Peripheral Registers affected by This API, with respect to S32K144 MCU using ElecronicsV3 Board:

  1.  

 

 

 

 

API Name: Adc_EnableGroupNotification 

void Adc_EnableGroupNotification(Adc_GroupType Group)
  • Role: This API, enables the notification feature when conversion of all channels of the ADC group is successfully converted. 
  • Working of this API: After starting the ADC conversion either by software trigger or hardware trigger, the group notification function will be called only if its group notification is enabled. And that thing is done by this API. That’s why, in this API we just send one parameter, Group Number. 

    The ADC Group Notification callback function is called from the IRQ handler of ADC. ADC MCAL layer has a defined IRQ notification callback function, that is called when the IRQ handler of ADC is invoked upon successful conversion of ADC channels. And IRQ Notification callback function calls the group-specific notification callback and updates the Group Status to ADC Completed/ADC Stream Completed.

    For a single ADC hardware unit in a microcontroller, ADC IRQ is the same for all channels. So upon successful conversion of ADC of a channel IRQ handler notification is called, into which analysis is done that which channel of which group is completed and corresponding to that group notification callback is invoked.
  • Parameter passed: The parameter that is passed to this API is of Adc_GroupType data type. Adc_GroupType is a typedef of uint16. It is just a numeric ID ( 1,2,3,4 etc), denoting the ADC group number. The values of Group IDs are generated and initialized by the code configurator tool. We users don’t have to initialize the group ID number. The group IDs are automatically macro-defined based on the GUI configuration tool. We just have to send the macro-defined group name in this API.
  • Prerequisite: ADC should be used with Interrupts capability. If no interrupts are used, no notification capability will be invoked. The ADC Notification capability checkbox has to be checked in the AdcGeneral section of the ADC configurator tool. If this is not checked, the notification capability will not work. Make sure that we have configured the ADC Group Notification function in the configurator tool while configuring the ADC groups.

    // photo

    The name that would be written over here, the function of that name only will be created in generated files and we can define the function in the application code on how to use it and what to do.

  • Chronology: This API is used just after the Adc_init () and before calling the application loop that involves the use of ADC conversion.
  • Return value: This function does not return anything. As it only initializes the internal state to enable the notifications.
  • Syntax to use this API:
 Adc_EnableGroupNotification(AdcGroup_0);

API Name: Adc_StartGroupConversion() 

void Adc_StartGroupConversion(Adc_GroupType Group)
  • Role: This API initializes the conversion of channels of the group which is triggered by software. This API starts the conversion of the ADC group which is configured to get triggered via a Software Trigger. Hardware Trigger ADC groups are not started via this API. After the usage of this API, the ADC conversion of channels that are referred by a single group would begin, and we can expect corresponding group notifications to be called. And to see the results of ADC conversion we can use the Adc_ReadGroup().
  • Working: This API initializes the internal ADC peripheral register of ADC channels of the group which has to be converted. It also writes on those peripheral registers which starts the ADC conversion by Software trigger.
  • Parameters: The parameter that is passed to this API is of Adc_GroupType data type. Adc_GroupType is a typedef of uint16. It is just a numeric ID ( 1,2,3,4 etc), denoting the ADC group number. The values of Group IDs are generated and initialized by the configurator tool. We users don’t have to initialize the group ID number. The group IDs are automatically macro-defined based on the GUI configuration tool. We just have to send the macro-defined group name in this API.
  • Prerequisite: The ADC module should be initialized with Adc_Init() API and ADC notifications of the group should be enabled.

Syntax to this API:

 Adc_StartGroupConversion(AdcGroup_0);

API Name: Adc_EnableHardwareTrigger() 

void Adc_EnableHardwareTrigger(Adc_GroupType Group)
  • Role: This API initializes the conversion of channels of the group which has to be triggered by hardware. Upon receiving the configured hardware signal, ADC conversion starts for those channels. After ADC conversion for those channels is completed, Adc Group notification of the group is called. After the usage of this API, the ADC channels which have to be converted upon some hardware trigger signal would be initialized. As and when the Hardware signal is received by the MCU, the corresponding ADC group notification will be invoked upon completion.
  • Working: This API initializes and configures the extra peripherals of the MCU which are responsible for handling the hardware trigger events. And configures hardware trigger events that will invoke the conversion.
  • Parameter: The parameter that is passed to this API is of Adc_GroupType data type. Adc_GroupType is a typedef of uint16. It is just a numeric ID ( 1,2,3,4 etc), denoting the ADC group number. The values of Group IDs are generated and initialized by the configurator tool. We users don’t have to initialize the group ID number. The group IDs are automatically macro-defined based on the GUI configuration tool. We just have to send the macro-defined group name in this API.
  • Prerequisite: The ADC module should be initialized with Adc_Init() API and ADC notifications of the group should be enabled.
  • Syntax:
 Adc_EnableHardwareTrigger(AdcGroup_5_HW_WI_OS_PDB_B2B);

API Name: Adc_StopGroupConversion() 

void Adc_StopGroupConversion(Adc_GroupType Group)
  • Role: This API, is the opposite of Adc_StartGroupConversion(). This API stops the ADC conversion of the requested ADC channel group. This API stops the ADC conversion of groups which are triggered via software. After the usage of this API, ADC group status would be reset to ADC IDLE mode.
  • Working of this API: This API stops the ADC conversion of channels of the groups that are configured to trigger via Software. All groups that are started by Adc_StartGroupConversion() and are software triggers should be stopped with Adc_StopGroupConversion() before they are started again to reset the group status to ADC_IDLE. This API also automatically disables the group notification for the requested group.
  • Parameter: The parameter that is passed to this API is of Adc_GroupType data type. Adc_GroupType is a typedef of uint16. It is just a numeric ID ( 1,2,3,4 etc), denoting the ADC group number. The values of Group IDs are generated and initialized by the configurator tool. We users don’t have to initialize the group ID number. The group IDs are automatically macro-defined based on the GUI configuration tool. We just have to send the macro-defined group name in this API.
  • Syntax of this API:
 Adc_StopGroupConversion(AdcGroup_4_WI_Back2Back_Continous);

API Name: Adc_DisableGroupNotification

API Name: Adc_DisableHardwareTrigger

API Name: Adc_GetGroupStatus() 

Adc_StatusType Adc_GetGroupStatus(Adc_GroupType Group)
  • Role: This API returns the status of the requested ADC channel group.
  • Working: This API checks the conversion status of the group. There are 4 possible status options:
    1. ADC IDLE
    2. ADC BUSY
    3. ADC COMPLETED
    4. ADC STREAM COMPLETED
  • Parameter: The parameter that is passed to this API is of Adc_GroupType data type. Adc_GroupType is a typedef of uint16. It is just a numeric ID ( 1,2,3,4, etc), denoting the ADC group number. The values of Group IDs are generated and initialized by the configurator tool. We users don’t have to initialize the group ID number. The group IDs are automatically macro-defined based on the GUI configuration tool. We just have to send the macro-defined group name in this API.
  • Return values: This function returns the conversion status of the requested group according to Adc_StatusType data type.
  • Syntax:
 while(Adc_GetGroupStatus(AdcGroup_5_HW_WI_OS_PDB_B2B ) == ADC_BUSY);

API Name: Adc_ReadGroup() 

Std_ReturnType Adc_ReadGroup(Adc_GroupType Group, Adc_ValueGroupType* DataBufferPtr)
  • Role: This API reads the ADC conversion result of the requested group and stores the data of all channels of that group in the DataBufferPtr pointer. Also, this API will update the group status after reading the ADC conversions. Group status values can be ADC STREAM Completed/ADC_Completed, ADC_BUSY, and ADC_IDLE.
  • Working: This API reads the latest ADC conversions of the ADC channels of the requested group. The pointer that we send DataBufferPtr, should be long enough to hold the ADC result of all channels of that group. Say if in group 1 we have 5 channels, so Group1_result[5]. If we have a group 2 of 3 channels, so Group2_result[3]. Also, this API will check the ADC control and status register bits to check whether ADC conversion has taken place or not, if yes then this API will call a low-level function that will read the ADC data register of that peripheral. It is recommended to call this API from the notification callback function. This API will check the group status value before reading the ADC conversions. And group status is updated to ADC_COMPLETED or ADC_STREAM_COMPLETED in IRQ handlers.
  • Parameter: There are 2 parameters passed to this API:
    1. The first is of Adc_GroupType data type. Adc_GroupType is a typedef of uint16. It is just a numeric ID ( 1,2,3,4, etc), denoting the ADC group number. The values of Group IDs are generated and initialized by the configurator tool. We users don’t have to initialize the group ID number. The group IDs are automatically macro-defined based on the GUI configuration tool. We just have to send the macro-defined group name in this API.
    2. The second is a pointer to an array of indexes equal to channel numbers in that group to store the ADC conversion result.
  • Prerequisite: Make sure before calling this API, that ADC conversion has started and is also triggered either by a hardware trigger signal or software trigger. And also ADC group status should be either ADC_STREAM_COMPLETED or ADC_COMPLETED, so that correct ADC readings can be taken. For the first point make sure, you have called the APIs Adc_Init(), Adc_EnableGRoupNotification(), and Adc_StartGroupConversion() / Adc_Enable HardwareTrigger() before calling this API.
    For the second point make sure you have configured ADC via Interrupts and configurations have to be done in a that the IRQ handler is invoked after ADC conversion is done. As in the IRQ handler, the system default IRQ notification callback would be called that will update the ADC group status to said values and then invoke the group notification callback.

API Name: Adc_SetupResultBuffer() 

Std_ReturnType Adc_SetupResultBuffer(Adc_GroupType Group, Adc_ValueGroupType* DataBufferPtr)

Role: This API initializes the result buffers for the group at the time of initializing the ADC driver. The result buffer is where conversion results will be stored at first when ADC conversion is done. It’s like an internal buffer pointer that is maintained within various function calls to keep track of ADC results. The usage of this API is at the time of Adc_Init(), before the application loop.

  • Parameters send to this API:
    1. The parameter that is passed to this API is of Adc_GroupType data type. Adc_GroupType is a typedef of uint16. It is just a numeric ID ( 1,2,3,4, etc), denoting the ADC group number. The values of Group IDs are generated and initialized by the configurator tool. We users don’t have to initialize the group ID number. The group IDs are automatically macro-defined based on the GUI configuration tool. We just have to send the macro-defined group name in this API.
    2. The second is a pointer to an array of indexes equal to channel numbers in that group to store the ADC conversion results. This is not generated by the configurator tool. We at the application will define and initialize this variable. And then pass that variable address to this API as its parameter.
  • The result buffer parameter that we passed to Adc_ReadGroup() is different from this API. Though their initialization and size are of the same type. The result buffer of Adc_ReadGroup is the total application end variable where ADC conversion results would be stored. The result buffer of Adc_SetupResultBuffer is a variable to store ADC results. It’s like an internal buffer pointer that is maintained within various function calls to keep track of ADC results.
  • Syntax of this API:
 Adc_SetupResultBuffer(AdcGroup_4_WI_Back2Back_Continous, ResultBuffer);

Okay so now we have got overview and understanding of basic Adc Driver API’s of Autosar MCAL layer. Now lets move into Configurator tool GUI understanding and demo codes creation. So as to put the things into action instead of just theory.

For Autosar Configurator tools like EbTresos/DaVinci and etc industry standard tools are used. But using these tools are very expensive and comes with lots of challenges. But the configuration GUI sections, and concept is same across all configurator tools. Whether you are using EBtresos or DaVinci. Learning on how to do the GUI onfigurations on any tool will make us enough capable to know how to use idustry standard tools.

We are going to use the ElecronicsV3 Development Board which has NXP S32K144 Microcontroller in it. It is a automotive microcontroller with Full Autsoar MCAL layer availaablity for free. And It is integarted with S32 Design Studio IDE. Which is a opensource and freely avaialble IDE by NXP semiconductors on which we can do MCAL layer configurations and generate the MCAL code also.

We will be understanding on Configuration GUI, by creating DIY projects:

Now, we have got the understanding of Autosar ADC Driver concepts and API’s understanding. Now lets move to creating Demo DIY projects using ADC driver of MCAL layer to understand how to use ADC driver and we will also learn how to do the GUI configurations while doing so.

We will create 4 projects and while creating those 4 projects, will understand how to use the GUI configurations and API’s.

Broadly in high level for any ADC peripheral, we will have following 4 major features in ADC driver of MCAL layer. These features are universal and general in all ADC peripherals of the Microcontroller. Though their implementation or dependent modules might varry, but broadly these are functional features of any ADC peripheral of MCU.

  1. ADC Transfer Type: Interrupt/DMA
  2. ADC Conversion Start: Software Trigger/Harwdare Trigger
  3. ADC Conversion Mode: One Shot Mode/ Continous Mode
  4. ADC Conversion Data Access Mode: Single Access Mode or Streaming Mode

For now, we will do Handson and demo DIY for features marked in Bold only. Rest features demo projects we will explore in advance version course of ADC Driver of MCAL.

Next exercises we will do by problemts. We will create 9 example projects with ADC MCAL driver, in which each example project would be having below mentioned problem statements.

  1. Single Channel Single Group via software trigger
  2. multiple channel single group via software trigger
  3. multiple different channel multiple group via software trigger
  4. multiple same channels multiple group via software trigger.
  5. Single Channel Single Group via hardware trigger
  6. multiple channel single group via hardware trigger
  7. multiple different channel multiple groups via hardware trigger
  8. multiple same channels multiple groups via hardware trigger.
  9. single channel with group limit checking single group.

Now, we use 

 

Now we for creating the MCAL layer projects

Kunal Gupta
Author: Kunal Gupta

♥30

Author

Kunal Gupta

Leave a comment

Stay Updated With Us

Error: Contact form not found.

      Blog