Generic Timestamp Engine¶

Applies to: Jetson AGX Orin and Jetson AGX Xavier series

Note

This driver is experimental, and is not promised to be stable.

The API is subject to change in future releases, and is not enabled by default.

GPIO direction change falling and rising information is not reliable using GTE, but GTE monitoring LIC IRQ can convey that information correctly.

The Jetson Generic Timestamp Engine (GTE) provides hardware timestamping for state changes of specific signals, including LIC (Legacy Interrupt Controller) interrupt lines and AON (Always On) domain GPIOs. GPIOs to be monitored must be configured as input and as GPIO IRQ. The GTE kernel device driver provides various APIs for clients to register, retrieve and unregister specific signals. This guide provides the details on how to enable and use GTE kernel driver.

Once the GTE kernel driver is enabled, it creates two GTE instances and a device node:

/sys/devices/platform/3aa0000.gte/ (for LIC IRQ monitoring)
/sys/devices/platform/c1e0000.gte/ (for AON GPIO monitoring)

cle0000.gte in turn creates one device node: /dev/gtechip0 (for use by a user space utility to monitor AON GPIO from user space).

The GTE kernel driver is accompanied by a kernel sample test driver which demonstrates how to monitor a LIC interrupt line and AON GPIO for state changes. When a monitored line’s state changes, the GTE hardware on the NVIDIA^® Jetson™ device timestamps the change. A client program can use the GTE kernel driver API to retrieve the timestamp for the configured signal.

The GTE kernel driver is also accompanied by a user space sample application which demonstrates how to monitor AON GPIO from user space.

Enabling the GTE Driver¶

To enable the GTE kernel driver, you must modify the device tree, set GTE-related configuration options for the kernel, rebuild the kernel and device tree, and reflash the rebuilt kernel and device tree to the Jetson device. The following steps accomplish these things.

Note

You must ensure that GPIOs are not being used by any other kernel drivers or user space applications, and are programmed with appropriate pinmux configurations.

To enable the GTE device tree nodes¶

On the host, add the following lines to tegra234-p3737-0000-a00.dtsi for Jetson AGX Orin, or to tegra194-p2822-0000-a00.dtsi for Jetson AGX Xavier series:
```
gte@3aa0000 {
    status = "okay";
};

gte@c1e0000 {
    status = "okay";
};

gpio@c2f0000 {
    /delete-property/ use-timestamp;
};
```

After you modify the .dtsi file, follow instructions on how to compile and flash the device tree .dtb file. See the topic Kernel for details.

To enable and compile the GTE kernel driver and test driver¶

Locate the source code for the GTE kernel device driver and its test kernel driver on the host. The source code should be in this directory:
```
<kernel_source>/drivers/staging/platform/tegra/
```
Where <kernel_source> is the directory you have chosen to hold kernel source code.

If the source code is not there, download it. See Obtaining the Kernel Sources with Git in the topic Kernel.
Set the following kernel configuration options in the file tegra_defconfig:
```
CONFIG_TEGRA_GTE_TEST=m
CONFIG_TEGRA_HTS_GTE=y
```
These options control the GTE kernel and kernel test driver.
Ensure that the proper cross-compiler toolchain is set up. See the topic Kernel for more information.
Set up the environment and build the kernel. See the topic Kernel for more information. The GTE driver is built into the kernel, and is set by default, i.e. CONFIG_TEGRA_HTS_GTE=y is set. The GTE test driver is disabled, and can be enabled by following step 2 above, after which the kernel module must be compiled.
Copy the built files to the Jetson device, (This applies only to the GTE test driver.)
1. Go to the host’s output directory. (See Building the Kernel in the topic Kernel.) Locate the file tegra194_gte_test.ko.
2. Copy tegra194_gte_test.ko to a directory of your choice on the Jetson device. This is the GTE sample kernel test driver.

Running Sample GTE Tests¶

Running tests is described for the GTE feature’s default setup. If you modify the setup, change the test procedures appropriately.

To run sample GTE tests, you must short pins 32 and 16 on the carrier board’s 40-pin header, where pin 32 is AON GPIO BB-1 configured as input, and pin 16 is AON GPIO BB-0 configured as output.

You must log in to the Jetson device as root to run any of the sample GTE tests.

To run the GTE test kernel driver¶

Enter this command:
```
$ insmod tegra194_gte_test.ko lic_irq=25 gpio_in=314 gpio_out=313
```
In this example:
- tegra194_gte_test.ko refers to the copy of that file which you made on the Jetson device in step 5.2 of To enable and compile the GTE kernel driver and test driver.
- lic_irq specifies the physical LIC (Legacy Interrupt Controller) IRQ number for 3160000.i2c device.
- gpio_in and gpio_out, for GPIO pins BB1 and BB0 respectively, can be derived from reading the file /sys/kernel/debug/gpio. The GPIO number differs between supported devices.
The parameter values shown are suggested as starting points. You may change any of them.
Enter this command to enable kernel debug messages:
```
$ dmesg -n8
```
Enter this command to enable GTE monitoring of GPIO 314:
```
$ echo 1 >/sys/kernel/tegra_gte_test/gpio_en_dis
```
If GTE monitoring is successfully enabled, the Jetson device’s console prints this message:
```
GPIO HW Timestamp: raw xxxx, ns yyyy
```
Where xxxx represents the GTE timestamp in raw form, and yyyy represents the timestamp in nanoseconds.
Enter this command to enable GTE monitoring of LIC IRQ line 25 (the I2C0 controller interrupt line):
```
$ echo 1 >/sys/kernel/tegra_gte_test/lic_irq_en_dis
```
Enter this command to test LIC IRQ by reading the EEPROM and generating I2C interrupts:
```
$ i2cdump -y 0 0x50
```
Enter this command to read the LIC IRQ timestamp:
```
$ cat /sys/kernel/tegra_gte_test/lic_irq_ts
```
If the timestamp is read successfully, the Jetson device’s console prints this message:
```
ts_raw: xxxx, ts_ns: yyyy
```
Where xxxx represents the GTE timestamp in raw form, and yyyy represents the timestamp in nanoseconds.

Enter this command to disable GTE GPIO monitoring:

$ echo 0 >/sys/kernel/tegra_gte_test/gpio_en_dis

Enter this command to disable GTE LIC IRQ monitoring:

$ echo 0 >/sys/kernel/tegra_gte_test/lic_irq_en_dis

To run the GTE user space sample application¶

If gcc is not already installed on the Jetson device, enter this command on the Jetson device to install it:
```
$ apt install -y gcc
```
From the host, copy <kernel_source>/nvidia/include/uapi/linux/tegra-gte-ioctl.h to the directory /usr/include/linux/ on the Jetson device.
From the host, copy <kernel_source>/nvidia/tools/tegra-gte/tegra_gte_mon.c to a directory of your choice on the Jetson device.
Compile tegra_gte_mon.c:
```
$ gcc tegra_gte_mon.c -o gte_mon
```
Enter this command to start the sample application and thus start timestamping events:
```
$ ./gte_mon -d gtechip0 -g 314 -r -f &
```

-g 314 specifies the AON (Always On) BB 1 GPIO pin. You may change this value to use gte_mon on different pins.

-r and -f specify timestamping events on rising and falling edges.

-d gtechip0 specifies GTE chip device 0, which internally maps to GTE instance for monitoring AON events.

Note

This command prints a description of the application’s usage:

$ ./gte_mon -h

Start toggling GPIO 313 to generate observable events:
```
$ echo 313 >/sys/class/gpio/export
$ echo out >/sys/class/gpio/PBB.00/direction
```
GPIO 313 maps to the BB 0 port of the AON, and out specifies the direction, i.e. it configures GPIO 313 as output.
Enter this command to set GPIO 313 (i.e. change its value to 1):
```
$ echo 1 >/sys/class/gpio/PBB.00/value
```
The sample application prints this message:
```
HW timestamp GPIO EVENT xxxx
```
Enter this command to clear GPIO 313 (i.e. change its value to 0):
```
$ echo 0 >/sys/class/gpio/PBB.00/value
```
The sample application prints this message:
```
HW timestamp GPIO EVENT yyyy
```
To close the sample application, enter this command:
```
$ fg
```
Then press Ctrl+C.
Enter this command to unexport (release) GPIO pin 313:
```
$ echo 313 >/sys/class/gpio/unexport
```

To display GTE device and GTE event statistics¶

To display the event numbers registered to each GTE device, enter this command:
```
$ cat /sys/devices/platform/*.gte/events_registered
```
To display the number of dropped events due to software FIFO overrun for each registered type of event, enter this command:
```
$ cat /sys/devices/platform/<gte device>/event<n>/num_dropped_events
```
Where <n> is the event number of the event to be queried.
To display the number of available events for each registered type of event, enter this command:
```
$ cat /sys/devices/platform/<gte_device>/event<n>/num_events_avail
```