.. _SD.Kernel.GenericTimestampEngine:

.. include:: /content/swdocs.rsts

.. spelling::
   gcc
   unexport

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(r)| |Jetson(tm)| 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 <#kernel>`__
for details.


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

1. 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 :ref:`Obtaining the Kernel Sources with Git <SD.Kernel.KernelCustomization-ObtainingTheKernelSourcesWithGit>` in the topic :ref:`Kernel <SD.Kernel>`.

2. 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.

3. Ensure that the proper cross-compiler toolchain is set up. See the topic :ref:`Kernel <SD.Kernel>` for more information.

4. Set up the environment and build the kernel. See the topic :ref:`Kernel <SD.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.

5. 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 :ref:`Building the Kernel <SD.Kernel.KernelCustomization-BuildingTheKernel>` in the topic :ref:`Kernel <SD.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
#################################

1. 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 <#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.

2. Enter this command to enable kernel debug messages::

      $ dmesg -n8

3. 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.

4. 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

5. Enter this command to test LIC IRQ by reading the EEPROM and generating I2C interrupts::

      $ i2cdump -y 0 0x50

6. 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.

7. Enter this command to disable GTE GPIO monitoring::

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

8. 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
############################################

1. If gcc is not already installed on the Jetson device, enter this
   command on the Jetson device to install it::

      $ apt install -y gcc

2. From the host, copy ``<kernel_source>/nvidia/include/uapi/linux/tegra-gte-ioctl.h`` to the directory ``/usr/include/linux/`` on the Jetson device.

3. From the host, copy ``<kernel_source>/nvidia/tools/tegra-gte/tegra_gte_mon.c`` to a directory of your choice on the Jetson device.

4. Compile ``tegra_gte_mon.c``::

      $ gcc tegra_gte_mon.c -o gte_mon

5. 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

6. 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.

7. 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

8. 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

9. To close the sample application, enter this command::

   $ fg

   Then press Ctrl+C.

10. Enter this command to unexport (release) GPIO pin 313::

      $ echo 313 >/sys/class/gpio/unexport

To display GTE device and GTE event statistics
##############################################

1. To display the event numbers registered to each GTE device, enter this command::

      $ cat /sys/devices/platform/*.gte/events_registered

2. 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.

3. 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