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:
- Basic Time-Aware GPIO (TGPIO) Samples: A set of small and easy samples that report system information and demonstrate basic I/O for TGPIO.
- Advanced Time-Aware GPIO (TGPIO) Sample: A sample that demonstrates the advantages of using TGPIO over using normal software-controlled GPIO.
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 |
|---|---|---|
PMC 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 | |
PSE TGPIO | PSE TGPIO (/dev/ptp1), pin 17 | GPPC_B_23_PCHHOTB_GSPI1_CS1B_OSE_SPI3_CSB1_OSE_TGPIO28 |
PSE TGPIO (/dev/ptp1), pin 18 | GPPC_B_4_CPU_GP_3_ESPI_ALERTB_1_OSE_TGPIO27 | |
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 |
Intel® Xeon® W-11000E Series Processors
Scenario | Device | SoC Pin Name |
|---|---|---|
TGPIO | PMC TGPIO (/dev/ptp0), pin 0 | GPP_H_23_TIME_SYNC_0 |
PMC TGPIO (/dev/ptp0), pin 1 | GPP_B_1_GSPI1_CS1B_TIME_SYNC_1 | |
Regular GPIO | gpio424 | GPP_H_23_TIME_SYNC_0 |
gpio114 | GPP_B_1_GSPI1_CS1B_TIME_SYNC_1 |
How to Calculate the GPIO Number
- 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.
- Dump GPIO ranges information from/sys/kernel/debug/pinctrl/INT34C5\:00/gpio-ranges.
- Search for a particular PIN range. In this example, pin 23 is 0: INT34C5:00 GPIOS [152 - 177] PINS [0 - 25].
- Calculate the pin offset by subtracting the beginning of the interval from the pin number. For example: 23 - 0 = 23
- 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 PSE Time-Aware GPIO, 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 > Check pins 28 and 27
For Intel Atom® x6000E Series Processors, the same pins are used for TGPIO and regular GPIO. To switch to regular GPIO, disable PSE Time-Aware GPIO pins in the BIOS:
- Intel Advanced Menu > PCH IO Configuration > PSE configuration > GPIO/TGPIO 0 Pin Selection > Uncheck pins 28 and 27
For Intel® Xeon® W-11000E Series Processors, the same pins are used for TGPIO and regular GPIO. To switch to regular GPIO, disable PMC Time-Aware GPIO in the BIOS:
- Intel Advanced Menu > PCH IO Configuration > Enabled Timed GPIO0 [Disable]
- Intel Advanced Menu > PCH IO Configuration > Enabled Timed GPIO1 [Disable]