AGT Input Capture Driver on r_agt

Table of Contents

• Input Capture HAL Module Introduction
  • Input Capture HAL Module Features
  • AGT Input Capture Hardware support details
• Input Capture HAL Module APIs Overview
• Input Capture HAL Module Operational Overview
  • Input Capture HAL Module Important Operational Notes and Limitations
    • Input Capture HAL Module Operational Notes
    • Input Capture HAL Module Limitations
• Including the Input Capture HAL Module in an Application
• Configuring the Input Capture HAL Module
  • Input Capture HAL Module Clock Configuration
  • Input Capture HAL Module Pin Configuration
• Using the Input Capture HAL Module in an Application

Input Capture HAL Module Introduction

The Input Capture HAL module provides an API for measuring input pulse-width, period measurement and event count measurement. The Input Capture HAL module also configures the input capture parameters to use with the AGT peripheral on the Synergy MCU. A user-defined callback can be created to acquire the value each time a new measurement is complete.

Input Capture HAL Module Features

The Input Capture HAL module configures the AGT for an input capture function.

• The Input Capture HAL allows the user to perform the following tasks:
  • Initialize the module
  • Enable input capture measurement
  • Disable input capture measurement
  • Get the status (running or not) of the measurement counter
  • Get the last captured timer/overflows counter value
  • Close the input capture operation
• The Input Capture HAL module supports:
  • Pulse-width measurement, period measurement and event count measurement
  • Rising-edge or falling-edge measurement start
  • One-shot or periodic mode
  • Callback function with the following events:
    • Measurement and overflow interrupt
    • Capture compare interrupt
• Callback structure (input_capture_callback_args_t) that provides data on the interrupting event, including which interrupt occurs and the associated counter values.

Input Capture HAL Module Block Diagram

AGT Input Capture Hardware support details

The following hardware features are, or are not, supported by SSP for AGT Input Capture.

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	Timer Mode	Pulse Output Mode	Event Counter Mode	Pulse width measurement mode
S124	⌧	⌧	✓	✓
S128	⌧	⌧	✓	✓
S1JA	⌧	⌧	✓	✓
S3A1	⌧	⌧	✓	✓
S3A3	⌧	⌧	✓	✓
S3A6	⌧	⌧	✓	✓
S3A7	⌧	⌧	✓	✓
S5D3	⌧	⌧	✓	✓
S5D5	⌧	⌧	✓	✓
S5D9	⌧	⌧	✓	✓
S7G2	⌧	⌧	✓	✓

MCU Group	Pulse period measurement mode	Event link function through ELC HAL driver	Compare/Match Function
S124	✓	⌧	⌧
S128	✓	⌧	⌧
S1JA	✓	⌧	⌧
S3A1	✓	⌧	⌧
S3A3	✓	⌧	⌧
S3A6	✓	⌧	⌧
S3A7	✓	⌧	⌧
S5D3	✓	⌧	⌧
S5D5	✓	⌧	⌧
S5D9	✓	⌧	⌧
S7G2	✓	⌧	⌧

Input Capture HAL Module APIs Overview

The Input Capture HAL module interface defines APIs for opening, closing, enabling, disabling, accessing status information, and accessing the last-capture value using the Asynchronous General-Purpose Timer (AGT) with Input Capture. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the HAL Module API Summary.

Input Capture HAL Module API Summary

Function Name	Example API Call and Description
open	g_input_capture.p_api->open(g_input_capture.p_ctrl, g_input_capture.p_cfg); Opens the Input Capture HAL and initializes configuration.
close	g_input_capture.p_api->close(g_input_capture.p_ctrl); Closes the input capture operation. Allow drive to be reconfigured, and may reduce power consumption.
enable	g_input_capture.p_api->enable(g_input_capture.p_ctrl); Enables input capture measurement.
disable	g_input_capture.p_api->disable(g_input_capture.p_ctrl); Disables input capture measurement.
infoGet	g_input_capture.p_api->infoGet(g_input_capture.p_ctrl, &input_capture_info); Gets the status (running or not) of the measurement counter.
lastCaptureGet	g_input_capture.p_api->lastCaptureGet(g_input_capture.p_ctrl, &input_capture_counter); Gets the last captured timer/overflows counter value.
versionGet	g_input_capture.p_api->versionGet(&input_capture_version); Retrieve the API version with the input_capture_version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_ASSERTION	One of the parameters is NULL. Or the channel requested in the p_cfg parameter may not be available on the device selected in r_bsp_cfg.h. Or, p_cfg->mode is invalid.
SSP_ERR_IRQ_BSP_DISABLED	A required interrupt does not exist in the vector table.
SSP_ERR_IN_USE	Attempted to open an already open device instance.
SSP_ERR_NOT_OPEN	The channel is not opened.

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

Input Capture HAL Module Operational Overview

The Input Capture HAL module controls the AGT HAL module units on a Synergy microcontroller (as configured by the user). It directly accesses the AGT hardware without using any RTOS elements and provides convenient APIs to simplify development.

When a normal measurement is complete and a callback is available (with interrupts enabled,) the Input Capture HAL module invokes the callback with the argument input_capture_callback_args_t.

The argument input_capture_callback_args_t indicates the channel, the event input_capture_event_t, the value of the timer captured when the interrupt occurred, and the number of counter overflows that occurred during this measurement.

If the interrupts are not enabled, the values read by the APIs would be the last captured timer/overflows counter value.

Input Capture HAL Module Important Operational Notes and Limitations

Input Capture HAL Module Operational Notes

AGT Input Capture Measurement and overflow

The input capture interface provides support for pulse-width, period measurement, and event count measurement. The input capture interface also provides support for one-shot measurement and periodic measurement. The AGT hardware does not natively support one-shot functionality. Code is automatically included in the interrupt service routine (ISR) to stop and clear the timer.

The AGT hardware doesn't have a hardware interrupt vector for event count measurement. Therefore, the compare match vector triggers a callback when the counter reaches the count value supplied by user.

AGT Input Capture Signal

The input capture measurement starts when the input capture signal edge (rising or falling) is detected on the input capture signal pin (AGTIO). The input could be captured in any one of the AGT input capture pin (such as AGTIO0_A, AGTIO0_B, or AGTIO0_C) as configured by user. The pin corresponding to this selection must also be configured in AGT peripheral in the configurator.xml (that is, under configuration.xml > pins > peripherals > Timer:AGT).  The details on pins to be configured are in the user manual under the AGT block diagram and in the I/O ports section. Note that in the S3 and S5 series MCUs, AGTIO0_B is P402, AGTIO0_C is P403, and all other AGTIO pins are AGTIO0_A. The S1 MCU Series have only AGTIO0_A pins.

The noise filter samples the external signal at intervals of the PCLK divided by one of the values. When three consecutive samples are at the same level (high or low), then that level is passed on as the observed state of the signal.

For event count measurement, the module can be configured to count a single or both edges. That is, if it is configured as single edge, the signal edge as input by the user is counted, and if it is configured as both edges, pulses are counted on the starting edge of the pulse (either rising or falling edge). And the module will generate a callback when the pulse count reaches the event count value set by the user.

Event count measurement uses the capture compare interrupt to compare the counter value with the user expected value (and trigger a callback when they are the same), and uses the measurement and overflow interrupt to keep track of the overflow. Hence the priority of the measurement and overflow interrupt must be set higher than the latter, as the capturing of overflow takes precedence to compare match callback.

For pulse width measurement, if the input capture module is opened in the middle of an active level input by user, the module will start capturing the width from where it opened, and hence the captured width will not be the right width of the pulse. 

Converting Measurement Counts to Time

When a measurement completes, the raw-count data and the number of overflows is returned to the user in the callback function.

If desired, the raw measurement data can be converted to logical time units in the callback or user application. To convert the raw data, the current clock frequency and its pre-scaler value, number of overflows, maximum counter value, and measurement counts should be considered. The measurement counts and the number of overflows are provided in the callback arguments input_capture_callback_args_t.

The recommended method to obtain the current clock frequency is to use the cgc_api_t::systemClockFreqGet API. The input clock frequency is the clock frequency divided by the pre-scaler value and is represented as clk_freq_hz in the following Input Capture Time Calculation table. Note that pre-scaler are only available for AGTLCLK and AGTSCLK clocks

The maximum counter value for all boards is 0xFFFF. This maximum counter value plus one (since counter starts from zero) is represented as max_counts in the following table:

Input Capture Time Calculation

Desired Time Units	Formula
Nanoseconds (ns)	time_s = ((overflows * max_counts) + counter) * 1000000000 / clk_freq_hz
Microseconds (us)	time_s = ((overflows * max_counts) + counter) * 1000000 / clk_freq_hz
Milliseconds (ms)	time_s = ((overflows * max_counts) + counter) * 1000 / clk_freq_hz
Seconds (s)	time_s = ((overflows * max_counts) + counter) / clk_freq_hz

Input Capture HAL Module Limitations

• The input capture interface does not support the limited capture with Vbatt, that is, when running on battery power (which is available only for S3 MCU Series).
• Refer to the latest SSP Release Notes for any additional operational limitations for this module.
• When the count source selected is AGTSCLK or AGTLCLK, turn on the count source using call cgc_api_t::clockStart API before calling input_capture_api_t::open.

Including the Input Capture HAL Module in an Application

This section describes how to include the Input Capture HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Input Capture Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Input Capture Driver is g_input_capture0. This name can be changed in the associated Properties window.)

Input Capture HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_input_captureInput Capture Driver on r_agt_input_capture	Threads->HAL/Common Stacks	New Stack> Driver> Timers> Input Capture Driver on r_agt_input_capture

When the Input Capture Driver on r_agt_input_capture is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

Input Capture HAL Module Stack

Configuring the Input Capture HAL Module

The Input Capture HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator. They are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the Input Capture HAL Module on r_agt_input_capture

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enable or disable the parameter error checking.
Name	g_input_capture	Module name.
Channel	0	Physical hardware channel.
Mode	Pulse Width, Period, Event count Default: Pulse Width	Measures the input signal.
Signal Edge	Rising, Falling Default: Rising	Start measurement on rising or falling edge. Measurement stops on the opposite edge.
AGTIO Pin Select	AGTIO_A, AGTIO_B, AGTIO_C Default: AGTIO_A	Captures the input signal through one of these pins.
Event Edge Polarity	Single Edge, Both Edge Default: Both Edge	Counts the pulses on single edges (that is, on either rising or falling) or on both edges (that is, on either rising or falling) is received, in the event counter mode.
Repetition	Periodic, One Shot Default: Periodic	Capture a single measurement, then disable captures (one shot) until enable is called, or capture measurements continuously (periodic).
Auto Start	True, False Default: True	Set to true to enable measurements after configuring or false to leave the measurements disabled until enable is called.
Input Signal Filter	None, PCLK/1, PCLK/8, PCLK/32. Default: None	The noise filter samples the external signal at intervals of the PCLKB divided by one of the values. When 3 consecutive samples are at the same level (high or low), that level is passed on as the observed state of the signal.
Clock source	PCLKB, PCLKB/8, PCLKB/2, AGTLCLK, AGTSCLK Default: PCLKB	Input capture clock source.
Clock Divider	PCLK/1, PCLK/2, PCLK/4, PCLK/8, PCKL/16, PCLK/32, PCLK/64, PCLK/128 Default: PCLK/1	Clock divider used to scale the measurement counter.
Callback	NULL	A user callback function must be registered in open. The callback will be called from the interrupt service routine (ISR) each time the measurement or overflow occurs. Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.
Measurement and Overflow Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Select the measurement and overflow interrupt priority.
Capture Interrupt Priority	Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Priority 12	Select the capture interrupt priority, captured interrupt is used only for event count mode.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Input Capture HAL Module Clock Configuration

The AGT HAL module uses the PCLKB, AGTLCLK and AGTSCLK as its clock source. The clock frequency is set using the SSP configurator Clocks tab prior to a build, or using the CGC Interface at run-time.

Input Capture HAL Module Pin Configuration

The AGT peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the associated pins.

Note

The operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection for the AGT HAL Module on r_agt

Resource	ISDE Tab	Pin selection Sequence
AGT	Pins	Select Peripherals > Timer: AGT> AGT0

Note

The selection sequence assumes AGT0 is the desired hardware target for the driver.

Pin Configuration Settings for the Input capture HAL Module on r_agt_input_capture

Property	Value	Description
Operation Mode	Disabled, Custom, Timer Output, Compare Match, Count Measurement, Gated Count Default: Disabled	Select timer operation mode.
AGTIO	None, P100, P402, P403 Default: None	AGTIO pin.
AGTO	None Default: None	AGTO pin.
AGTOA	None Default: None	AGTOA pin.
AGTOB	None Default: None	AGTOB pin
AGTEE	None Default: None	AGTEE pin.

Note

The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and Synergy Kits may have different available pin configuration settings.

Using the Input Capture HAL Module in an Application

The typical steps in using the Input Capture HAL module in an application are:

1. Initialize the module using the input_capture_api_t::open API.
2. The capture and overflow interrupt can be enabled and the timer started using the input_capture_api_t::enable API.
3. The status of the captured counter (running or stopped) can be queried using input_capture_api_t::infoGet API.
4. The desired value can be found either in the main loop routine using the input_capture_api_t::lastCaptureGet API or in the callback function.
5. The capture and overflow interrupt can be disabled and the timer stopped using theinput_capture_api_t::disable API.
6. The module can be closed using the input_capture_api_t::close API once done.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical Input Capture HAL Module Application