Synergy Software Package User's Manual
GPT Input Capture on r_gpt Driver

Table of Contents

GPT Input Capture HAL Module Introduction

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

GPT Input Capture HAL Module Features

The Input Capture HAL module configures the GPT 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 and pulse-period measurement
    • Rising-edge or falling-edge measurement start
    • One-shot or periodic mode
    • Hardware-enable signals to enable captures (low enable/high enable)
    • Callback function with the following events:
      • Counter overflow
      • Input capture occur
    • Callback structure (input_capture_callback_args_t) that provides data on the interrupting event, including which interrupt occurs and the associated counter values.
GPT_Input_Capture_BD.png
Input Capture HAL Module Block Diagram

GPT Input Capture Hardware support details

The following hardware features are, or are not, supported by SSP for GPT_INPUT_CAPTURE.

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU Group Saw
Waves 		Triangle
Waves * 		PWM waveform
for controlling
brushless DC
motors 		Compare
match output
for Low, High,
and Toggle 		Input
capture
function 		Automatic
addition of
dead time
S124 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S128 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S1JA ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S3A1 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S3A3 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S3A6 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S3A7 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S5D3 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S5D5 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S5D9 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
S7G2 ⌧ ⌧ ⌧ ⌧ ✓ ⌧
MCU Group PWM Mode Phase Count
Function 		Event link function
through ELC HAL
driver 		Noise filtering
function
S124 ⌧ ⌧ ⌧ ✓
S128 ⌧ ⌧ ⌧ ✓
S1JA ⌧ ⌧ ⌧ ✓
S3A1 ⌧ ⌧ ⌧ ✓
S3A3 ⌧ ⌧ ⌧ ✓
S3A6 ⌧ ⌧ ⌧ ✓
S3A7 ⌧ ⌧ ⌧ ✓
S5D3 ⌧ ⌧ ⌧ ✓
S5D5 ⌧ ⌧ ⌧ ✓
S5D9 ⌧ ⌧ ⌧ ✓
S7G2 ⌧ ⌧ ⌧ ✓

GPT Input Capture HAL Module APIs Overview

The Input Capture HAL module interface defines APIs for opening, closing, enabling, disabling, accessing status information and last-capture value accessing using the General PWM Timer (GPT) 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_INVALID_ARGUMENT Parameter has invalid value or ISR is not enabled.
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.

GPT Input Capture HAL Module Operational Overview

The Input Capture HAL module controls the GPT HAL module units on a Synergy microcontroller (as configured by the user). It directly accesses the GPT 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.

GPT Input Capture HAL Module Important Operational Notes and Limitations

GPT Input Capture HAL Module Operational Notes

GPT Input Capture Measurement Mode

The input capture interface provides support for one-shot measurement and periodic measurement. The GPT hardware does not natively support one-shot functionality. Code is automatically included in the interrupt service routine (ISR) to stop and clear the timer. For this reason, ISRs must be enabled for one-shot mode, even when the callback is unused.

GPT 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 (GTIOCA/GTIOCB) and the enable condition is met. The enable condition is defined by the enable level and can be disabled (none), or a specified low or high level on the input capture enable pin (GTIOCA/GTIOCB). The input capture enable pin is the pin not used as the input capture signal pin.

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 PCLKD 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 PCLKD frequency is to use the cgc_api_t::systemClockFreqGet API. The input clock frequency is the PCLKD frequency divided by the pre-scalar value and is represented as clk_freq_hz in the following Input Capture Time Calculation table.

The maximum counter value on the S7G2 (all channels), S3A7 (all channels), and S124 (channel 0) is 0xFFFFFFFF. The maximum counter value for S124 (channels 1 - 6) 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_ns = ((overflows * max_counts) + counter) * 1000000000 / clk_freq_hz
Microseconds (us) time_ns = ((overflows * max_counts) + counter) * 1000000 / clk_freq_hz
Milliseconds (ms) time_ns = ((overflows * max_counts) + counter) * 1000 / clk_freq_hz
Seconds (s) time_ns = ((overflows * max_counts) + counter) / clk_freq_hz

GPT Input Capture HAL Module Limitations

  • Currently, the Input Capture HAL module supports only pulse-width measurement and pulse-period measurement.
  • Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the GPT 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_gpt_input_capture Threads>
HAL/Common Stacks 		New Stack> Driver> Timers > Input Capture Driver on r_gpt_input_capture

When the Input Capture Driver on r_gpt_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.

GPT_Input_Capture_MS.png
Input Capture HAL Module Stack

Configuring the GPT 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 and 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_gpt_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

Default: Pulse Width 		Measures inputs from the Signal edge until the opposite edge.
Signal Edge Rising, Falling

Default: Rising 		Start measurement on rising or falling edge. Measurement stops on the opposite edge.
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.
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 timer period elapses.

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.
Input Capture Signal Pin GTIOCA, GTIOCB

Default: GTIOCA 		Select the input pin used to trigger the start of a measurement.
GTIOCx Signal Filter PCLK/1, PCLK/4, PCLK/16, PCLK/64

Default: PCLK/1 		The noise filter samples the external signal at intervals of the PCLK 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 Divider PCLK/1, PCLK/4, PCLK/16, PCLK/64, PCKL/256, PCLK/1024

Default: PCLK/1 		Clock divider used to scale the measurement counter.
Input Capture Enable Level None, Low, High

Default: None 		Each GPT channel has 2 I/O pins (GTIOCA and GTIOCB). One must be selected as the Input Capture Signal Pin. The other GPT I/O pin can be used as a hardware enable signal to enable captures. Select None and captures are always enabled, select low and captures are enabled only while the enable input pin is low, select high and captures are enabled only while the enable input pin is high.
Input Capture Enable Filter Enable, Disable

Default: Disable (No filtering) 		Enable/Disable the input noise filter for input on GTIOCx pin
 
Capture Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Capture interrupt priority selection.
Overflow Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Overflow interrupt priority selection.
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.

GPT Input Capture HAL Module Clock Configuration

The GPT HAL module uses the PCLKD as its clock source. The PCLKD frequency is set using the SSP configurator clocks tab prior to a build, or using the CGC Interface at run-time.

GPT Input Capture HAL Module Pin Configuration

To access a particular channel and pin, the GTIOCx pins must be set in the Pins tab of the ISDE. The following table provides the method for selecting the pins within the SSP configuration window and the subsequent table provides an example selection for GTIOCx pins.

Pin Selection for the Input Capture HAL Module on r_gpt_input_capture

Resource ISDE Tab Pin selection Sequence
GPT Input Capture Pins Select Peripherals> Timer: GPT> GPT0
Note
The selection sequence assumes GPT0 is the desired hardware target for the driver.

Pin Configuration Settings for the Input Capture HAL Module on r_kint

Property Value Description
Pin Group Selection Mixed, _A Only, _B Only

Default: Mixed 		Pin grouping selection.
Operation Mode Disabled, GTIOCA or GTIOCB, GTIOCA and GTIOCB

Default: Disable 		Select GTIOCA or GTIOCB as the Operation Mode for Input Capture on GPT.
GTIOCA None, P300, P512

Default: None 		GTIOCA Pin.
GTIOCB None, P108, P511

Default: None 		GTIOCB 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 GPT 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 desired value can be found either in the main loop routine using the input_capture_api_t::lastCaptureGet API or in the callback function.
  3. The capture and overflow interrupt can be disabled and the timer stopped using theinput_capture_api_t::disable API.
  4. The capture and overflow interrupt can be enabled and the timer started using the input_capture_api_t::enable API.
  5. The status of the captured counter (running or stopped) can be queried using input_capture_api_t::infoGet 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:

GPT_Input_Capture_TA.png
Flow Diagram of a Typical Input Capture HAL Module Application