Developer Guide

  • 2021.2
  • 06/11/2021
  • Public
Contents

Time-Aware GPIO (TGPIO) Samples

GPIO and TGPIO

General-Purpose I/O (GPIO) is a digital signal pin on an electronic device without a specified purpose. A GPIO pin can work as output (by switching to the high or low state) or as input (by reading whether a pin is in the high or low state).
The control of GPIOs on a system with Linux* or other OS may be less precise and produce more jitter compared to a bare-metal solution because of the OS scheduler.
To address the problem, certain Intel® processors have a hardware feature called Time-Aware GPIO (TGPIO). These processors have one or more TGPIO pins, which you can control using timestamps. You can program a specific timestamp to toggle a TGPIO pin, or capture the current timestamp when a pin is toggled. This is done by hardware, so the OS or other software do not affect the precision.
The main purpose of TGPIO is to have a precise time synchronization between devices. You can program TGPIO to generate the edge at specific timestamps and synchronize other devices with this signal, or synchronize your processor clock with an external signal.
TGPIO use-case examples:
  • Verify time synchronization between devices. For example, you can synchronize two boards with Precision Time Protocol (PTP).
    • Program both devices to generate edges at the same timestamps.
    • Compare signals with an oscilloscope or logic analyzer to see the difference between their clocks.
  • Synchronize an external device with your clock.
    • Generate Pulse per Second (PPS) at specific timestamps with TGPIO.
    • Connect to an external device that can input PPS.
  • Synchronize your clock with an external device. For example, you want your clock to be the PTP primary clock and share precise time from a GPS receiver to the network.
    • Connect a PPS device output to the TGPIO input.
    • Adjust the system clock with captured timestamps.
  • Synchronize multiple camera shutters.
  • Generate frequencies.

TGPIO Clocking Details

TGPIO is clocked by an invariant timekeeping hardware, called the Always Running Timer (ART) that runs at the core crystal clock frequency. All TGPIO timestamps (output period and start time, external input timestamps, and event counts) are relative to the ART. If you need timestamps relative to the system time (for example, CLOCK_REALTIME), convert the ART time to system time using cross-timestamping. Refer to Basic Time-Aware GPIO (TGPIO) Samples and Advanced Time-Aware GPIO (TGPIO) Sample for cross-timestamping example code.

TGPIO Interface in Linux* OS

The TGPIO interface is represented as a PTP device. It is controlled using
ioctl()
syscalls and provides the following features:
  • Getting TGPIO capabilities: number of pins, number of channels, and whether the clock supports precise system-device cross-timestamps
  • Configuring pins to the input or output
  • Generating signals with a given period, which starts at a specific timestamp
  • Reading the timestamp when the input pin’s state changes
  • Cross-timestamping the TGPIO clock with the system clock

Samples Description

The samples demonstrate output scenarios with TGPIO and GPIO.
Samples:
To demonstrate how to set up the start timestamp for periodic signal generation, the samples align time to the integer seconds by adding 2 seconds to the current timestamp and setting nanoseconds to zero as shown in the following image:
Terms:
  • Current time: Some time after the application has started. Base time: Timestamp aligned to the integer number of seconds.
  • Start time: Timestamp when signal generation starts.
  • Offset: User-specified offset between the base time and start time.

Example Pins

The sample documentation refers to hardware pins by placeholder names, such as “TGPIO pin 0” and “software GPIO pin 0.” For quick reference, this section specifies the actual pins used by the included samples. In addition, the Intel® TCC FAQ provides details about pinouts and required reworks to expose the pins on customer reference boards (CRBs) and reference validation platforms (RVPs). Contact your Intel representative for access.
Device names and numbers, such as
/dev/ptp0
or
gpio175
, depend on how the OS enumerates devices and may be changed.
In the following tables, PMC stands for Power Management Controller.
11th Gen Intel® Core™ Processors
Scenario
Device
SoC Pin Name
TGPIO
PMC TGPIO (/dev/ptp0), pin 0
GPPC_H19_TIME_SYNC_0
PMC TGPIO (/dev/ptp0), pin 1
GPPC_B14_SPKR_TIME_SYNC_1_GSPI0_CS1_N
Regular GPIO
gpio175
GPPC_B23_SML1_ALERT_N_PCHHOT_N_GSPI1_CS1_N
gpio171
GPPC_B19_GSPI1_CS0_N
Intel Atom® x6000E Series Processors
Scenario
Device
SoC Pin Name
TGPIO
PMC TGPIO (/dev/ptp0), pin 0
GPPC_H_19_DDP1_CTRLDATA_TIME_SYNC_0_OSE_TGPIO20
PMC TGPIO (/dev/ptp0), pin 1
GPPC_B_14_SPKR_TIME_SYNC_1_GSPI0_CS1B_OSE_SPI2_CSB1
Regular GPIO
gpio201
GPPC_B_4_CPU_GP_3_ESPI_ALERTB_1_OSE_TGPIO27
gpio220
GPPC_B_23_PCHHOTB_GSPI1_CS1B_OSE_SPI3_CSB1_OSE_TGPIO28

How to Calculate the GPIO Number

  1. Get the GPIO pin number from the table above. This guide uses pins 19 and 23. If you want to use different pins, you can get the pin number from
    /sys/kernel/debug/pinctrl/INT34C5\:00/pins
    .
  2. Dump GPIO ranges information from
    /sys/kernel/debug/pinctrl/INT34C5\:00/gpio-ranges
    .
  3. Search for a particular PIN range. In this example, pin 23 is 0: INT34C5:00 GPIOS [152 - 177] PINS [0 - 25].
  4. Calculate the pin offset by subtracting the beginning of the interval from the pin number. For example: 23 - 0 = 23
  5. For the GPIO number, add the offset to the beginning of the GPIO number interval. For example: 152 + 23 = 175, the GPIO number for pin 23.

Setup

To enable PMC Time-Aware GPIO, configure the following BIOS options:
  • Intel Advanced Menu > PCH IO Configuration > Enabled Timed GPIO0 [Enable]
  • Intel Advanced Menu > PCH IO Configuration > Enabled Timed GPIO1 [Enable]
To enable pins to be controlled as regular GPIO from OS for Intel Atom® x6000E Series Processors, configure the following BIOS options:
  • Intel Advanced Menu > PCH IO Configuration > Security Configuration > Force unlock on all GPIO pads > [Enabled]
  • Intel Advanced Menu > PCH IO Configuration > SerialIo Configuration > SPI2 Controller > [Disabled]
  • Intel Advanced Menu > PCH IO Configuration > PSE configuration > SPI0 > [Host owned with pin muxed]
  • Intel Advanced Menu > PCH IO Configuration > PSE configuration > GPIO/TGPIO 0 > [Host owned with pin muxed]
  • Intel Advanced Menu > PCH IO Configuration > PSE configuration > GPIO/TGPIO 0 MUX SELECTION > MID
  • Intel Advanced Menu > PCH IO Configuration > PSE configuration > GPIO/TGPIO 0 Pin Selection > Uncheck pins 28 and 27

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.