Developer Guide

  • 2021.2
  • 06/11/2021
  • Public
Contents

Basic Time-Aware GPIO (TGPIO) Samples

Samples demonstrate how to write code using certain features. They are not performance benchmarks. The output examples shown here are for illustration only. Your output may vary.
The following basic samples demonstrate how to start working with Time-Aware GPIO (TGPIO):
The names “TGPIO pin 0” and “TGPIO pin 1” used in the following samples are placeholders. For information about pins specific to your hardware, see Example Pins.

Info Sample

The info sample (
tcc_tgpio_info
) is a self-contained example program demonstrating how to get a report of available TGPIO capabilities for a specified device.
Source Files
File
Description
src/tgpio_info.c
Main file containing the TGPIO sample.
../../common/include/tgpio_defs.h
Definitions for extended PTP-interface functions used by the TGPIO driver interface
Command-Line Options
usage: tcc_tgpio_info [--device <device_name>]
Argument
Description
--device <device_name>
Specify the TGPIO device. Default: “/dev/ptp0”.
Command Example
tcc_tgpio_info
Output Example
The output shows the following information:
  • Pins: Indicates the number of physical pins.
  • Input function - External timestamp channels: Indicates the number of pins that you can configure as input.
  • Output function - Programmable periodic signals: Indicates the number of pins that you can configure as output.
  • Precise system-device cross-timestamps: Indicates whether the device supports hardware cross-timestamping. TGPIO devices always support cross-timestamping.
  • Index: Indicates the index number of this pin. Used to select the pin you are working with in PTP ioctls. This index is used to identify the pin in the other TGPIO samples (for example, in the
    --pin
    option and signal file).
  • Used function: Indicates the function assigned to this pin. Corresponds to the functions listed in “Available capabilities” shown as follows.
  • Channel: Indicates the channel assigned to this pin. Channels are used for compatibility with other PTP devices. For TGPIO devices, the channel must be equal to the pin index.
Available capabilities: Pins: 2 Input function - External timestamp channels: 2 Output function - Programmable periodic signals: 2 Precise system-device cross-timestamps: Supported ======================================================= Available TGPIO pins: | Pin Name | Index | Used Function | Channel | -------------------------------------------------------------------- | intel-pmc-tgpio-pin01 | 0 | None | 0 | -------------------------------------------------------------------- | intel-pmc-tgpio-pin02 | 1 | None | 1 |

Basic Oneshot Output Sample

The basic oneshot output sample (
tcc_tgpio_basic_oneshot_output
) is a self-contained example program demonstrating a TGPIO single-shot output scenario. The sample demonstrates how to trigger a TGPIO pin at the specific timestamp. In this sample, this timestamp is specified as an offset from the
Base time
. For more information, see Samples Description.
File
Description
src/tgpio_basic_oneshot_output.c
Main file containing the TGPIO sample.
../../common/include/tgpio_defs.h
Definitions for extended PTP-interface functions used by TGPIO driver interface
Sample Command-Line Options
Usage: tcc_tgpio_basic_oneshot_output [--pin N] [--channel N] [--device <device_name>] [--start N]
Argument
Description
--pin N
Specify the output pin index. Default: 0.
--channel N
Specify the channel for the output pin. Default: 0.
--device <device_name>
Specify the TGPIO device. Default: “/dev/ptp0”.
--start N
Specify the edge delay in nanoseconds. Default: 1000000000 (1 second).
Option A: Run the Sample with a Logic Analyzer or Oscilloscope
If you have a measurement device, such as a logic analyzer or oscilloscope, you can use it to check whether TGPIO works. Connect the TGPIO pin and ground to a logic analyzer or oscilloscope.
Connection example:
This sample does not set the initial state of the pin. Consider setting edge triggers to both. If you are working with triggers instead of a live capture, you can compare the system with logic analyzer timestamps or launch the sample multiple times with different start intervals set.
Command example:
tcc_tgpio_basic_oneshot_output
Output example:
The following figure shows the logic analyzer screen capture on channel 0 for about 2 seconds just before the sample was launched (T1). The output transition appears after 1 second (T2) with default sample parameters.
In the case shown here, the initial state of the pin was low.
Option B: Connect Two TGPIO Pins Together
If you do not have a measurement device, you can connect one TGPIO pin to the other TGPIO pin and then use
tcc_tgpio_basic_input
to check whether TGPIO works.
Example:
  1. Connect TGPIO pin 0 to TGPIO pin 1 with a wire:
  2. Open two terminal windows.
  3. In the first terminal window, run the input sample to read the values from the other TGPIO pin:
    tcc_tgpio_basic_input --pin 1 --channel 1
  4. In the second terminal window, run the sample:
    tcc_tgpio_basic_oneshot_output
Output example:
The script reads the values from the other TGPIO pin. The output shows the timestamp of the registered change. Format: hh:mm:ss.nanoseconds. You can expect to see a single edge. You can run
tcc_tgpio_basic_oneshot_output
multiple times to see that an edge is generated every time the sample is run.
Start input sample. Pin 1, channel 1 To interrupt, use Ctrl+C Detected edge on channel 1 at 16:41:32.000000000

Basic Periodic Output Sample

The basic periodic output sample (
tcc_tgpio_basic_periodic_output
) is a self-contained example program demonstrating how to set a TGPIO pin to periodic output mode. The sample generates a signal based on the specified period (1 second, for example). The sample generates a voltage change on the output pin at the specific timestamp. For more information, see Samples Description.
Source Files
File
Description
src/tgpio_basic_periodic_output.c
Main file containing the TGPIO sample.
../../common/include/tgpio_defs.h
Definitions for extended PTP-interface functions used by TGPIO driver interface
Sample Command-Line Options
Usage: tcc_tgpio_basic_periodic_output [--pin N] [--channel N] [--device <device_name>] [--period N]
Argument
Description
--pin N
Specify the output pin index. Default: 0.
--channel N
Specify the channel for the output pin. Default: 0.
--device <device_name>
Specify the TGPIO device. Default: “/dev/ptp0”.
--period N
Specify the output period in nanoseconds. Default: 1000000000 (1 second).
Option A: Run the Sample with a Logic Analyzer or Oscilloscope
If you have a measurement device, such as a logic analyzer or oscilloscope, you can use it to check whether TGPIO works. Connect the TGPIO pin and ground to a logic analyzer or oscilloscope.
Connection example:
Command example:
tcc_tgpio_basic_periodic_output
Output example:
You can expect to see a square wave with a one-second period.
Option B: Connect Two TGPIO Pins Together
If you do not have a measurement device, you can connect one TGPIO pin to the other TGPIO pin and then use
tcc_tgpio_basic_input
to check whether TGPIO works.
Example:
  1. Connect TGPIO pin 0 to TGPIO pin 1 with a wire:
  2. Open two terminal windows.
  3. In the first terminal window, run the sample:
    tcc_tgpio_basic_periodic_output
  4. In the second terminal window, run the input sample to read the values from the other TGPIO pin:
    tcc_tgpio_basic_input --pin 1 --channel 1
Output example:
The script reads the values from the software GPIO. The output shows the timestamp of the registered change. Format: hh:mm:ss.nanoseconds.
Start input sample. Pin 1, channel 1 To interrupt, use Ctrl+C Detected edge on channel 1 at 16:41:32.000000000 Detected edge on channel 1 at 16:41:32.500000000 Detected edge on channel 1 at 16:41:33.000000000 Detected edge on channel 1 at 16:41:33.500000000 Detected edge on channel 1 at 16:41:34.000000000

Basic Input Sample

The basic input sample (
tcc_tgpio_basic_input
) is a self-contained example program that prints a timestamp when an edge is detected, indicating a change in the TGPIO input pin state.
Source Files
File
Description
src/tgpio_basic_input.c
Main file containing the TGPIO sample.
../../common/include/tgpio_defs.h
Definitions for extended PTP-interface functions used by TGPIO driver interface
Command-Line Options
Usage: tcc_tgpio_basic_input [--pin N] [--channel N] [--device <device_name>]
Argument
Description
--pin N
Specify input pin index. Default pin is 0.
--channel N
Specify channel for input pin. Default channel is 0.
--device <device_name>
Specify Precision Time Protocol (PTP) device. Default device is “/dev/ptp0”.
Option A: Run the Sample with an External Signal Generator
If you have a signal generator to generate square waves with appropriate electrical characteristics, you can connect it to the TGPIO pin to run the input sample. Connect the TGPIO pin and ground to the signal generator.
Command example:
tcc_tgpio_basic_input
Output example:
The output shows the timestamp of the registered change. Format: hh:mm:ss.nanoseconds.
Start input sample. Pin 0, channel 0 To interrupt, use Ctrl+C Detected edge on channel 0 at 19:37:43.836201899 Detected edge on channel 0 at 19:37:44.836203857 Detected edge on channel 0 at 19:37:45.836258579
Option B: Manually Connect Pin to the GND or VCC
If you do not have a signal generator, you can connect the TGPIO pin to the GND pin or the VCC pin on the board to run the input sample.
Example:
  1. Connect the TGPIO input pin to the GND pin with a wire. This will set the logic to “0” on the input pin.
  2. Run the sample.
    tcc_tgpio_basic_input
  3. Disconnect the wire from the GND pin, and connect it to the VCC pin. This will set the logic to “1” on the input pin.
Output example:
The output shows the timestamp of the registered change. Format: hh:mm:ss.nanoseconds.
Start input sample. Pin 0, channel 0 To interrupt, use Ctrl+C Detected edge on channel 0 at 19:37:43.836201899

Product and Performance Information

1

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