Commit 29814363 authored by Linus Torvalds's avatar Linus Torvalds
Browse files

Merge tag 'hte/for-5.19-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tegra/linux 

Pull hardware timestamping subsystem from Thierry Reding:
 "This contains the new HTE (hardware timestamping engine) subsystem
  that has been in the works for a couple of months now.

  The infrastructure provided allows for drivers to register as hardware
  timestamp providers, while consumers will be able to request events
  that they are interested in (such as GPIOs and IRQs) to be timestamped
  by the hardware providers.

  Note that this currently supports only one provider, but there seems
  to be enough interest in this functionality and we expect to see more
  drivers added once this is merged"

[ Linus Walleij mentions the Intel PMC in the Elkhart and Tiger Lake
  platforms as another future timestamp provider ]

* tag 'hte/for-5.19-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/tegra/linux:
  dt-bindings: timestamp: Correct id path
  dt-bindings: Renamed hte directory to timestamp
  hte: Uninitialized variable in hte_ts_get()
  hte: Fix off by one in hte_push_ts_ns()
  hte: Fix possible use-after-free in tegra_hte_test_remove()
  hte: Remove unused including <linux/version.h>
  MAINTAINERS: Add HTE Subsystem
  hte: Add Tegra HTE test driver
  tools: gpio: Add new hardware clock type
  gpiolib: cdev: Add hardware timestamp clock type
  gpio: tegra186: Add HTE support
  gpiolib: Add HTE support
  dt-bindings: Add HTE bindings
  hte: Add Tegra194 HTE kernel provider
  drivers: Add hardware timestamp engine (HTE) subsystem
  Documentation: Add HTE subsystem guide
parents 71e80720 5dad4ecc

Documentation/devicetree/bindings/timestamp/hardware-timestamps-common.yaml

0 → 100644
+29 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

%YAML 1.2

---

$id: http://devicetree.org/schemas/timestamp/hardware-timestamps-common.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#



title: Hardware timestamp providers



maintainers:

  - Dipen Patel <dipenp@nvidia.com>



description:

  Some devices/SoCs have hardware timestamp engines (HTE) which can use

  hardware means to timestamp entity in realtime. The entity could be anything

  from GPIOs, IRQs, Bus and so on. The hardware timestamp engine present

  itself as a provider with the bindings described in this document.



properties:

  $nodename:

    pattern: "^timestamp(@.*|-[0-9a-f])?$"



  "#timestamp-cells":

    description:

      Number of cells in a HTE specifier.



required:

  - "#timestamp-cells"



additionalProperties: true

Documentation/devicetree/bindings/timestamp/hte-consumer.yaml

0 → 100644
+39 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

%YAML 1.2

---

$id: http://devicetree.org/schemas/timestamp/hte-consumer.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#



title: HTE Consumer Device Tree Bindings



maintainers:

  - Dipen Patel <dipenp@nvidia.com>



select: true



properties:

  timestamps:

    $ref: /schemas/types.yaml#/definitions/phandle-array

    description:

      The list of HTE provider phandle. The first cell must represent the

      provider phandle followed by the line identifiers. The meaning of the

      line identifier and exact number of arguments must be specified in the

      HTE provider device tree binding document.



  timestamp-names:

    $ref: /schemas/types.yaml#/definitions/string-array

    description:

      An optional string property to label each line specifier present in the

      timestamp property.



dependencies:

  timestamp-names: [ timestamps ]



additionalProperties: true



examples:

  - |

    hte_tegra_consumer {

              timestamps = <&tegra_hte_aon 0x9>, <&tegra_hte_lic 0x19>;

              timestamp-names = "hte-gpio", "hte-i2c";

    };

Documentation/devicetree/bindings/timestamp/nvidia,tegra194-hte.yaml

0 → 100644
+88 −0
Original line number Diff line number Diff line 
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)

%YAML 1.2

---

$id: http://devicetree.org/schemas/timestamp/nvidia,tegra194-hte.yaml#

$schema: http://devicetree.org/meta-schemas/core.yaml#



title: Tegra194 on chip generic hardware timestamping engine (HTE)



maintainers:

  - Dipen Patel <dipenp@nvidia.com>



description:

  Tegra SoC has two instances of generic hardware timestamping engines (GTE)

  known as GTE GPIO and GTE IRQ, which can monitor subset of GPIO and on chip

  IRQ lines for the state change respectively, upon detection it will record

  timestamp (taken from system counter) in its internal hardware FIFO. It has

  a bitmap array arranged in 32bit slices where each bit represent signal/line

  to enable or disable for the hardware timestamping. The GTE GPIO monitors

  GPIO lines from the AON (always on) GPIO controller.



properties:

  compatible:

    enum:

      - nvidia,tegra194-gte-aon

      - nvidia,tegra194-gte-lic



  reg:

    maxItems: 1



  interrupts:

    maxItems: 1



  nvidia,int-threshold:

    $ref: /schemas/types.yaml#/definitions/uint32

    description:

      HTE device generates its interrupt based on this u32 FIFO threshold

      value. The recommended value is 1.

    minimum: 1

    maximum: 256



  nvidia,slices:

    $ref: /schemas/types.yaml#/definitions/uint32

    description:

      HTE lines are arranged in 32 bit slice where each bit represents different

      line/signal that it can enable/configure for the timestamp. It is u32

      property and depends on the HTE instance in the chip. The value 3 is for

      GPIO GTE and 11 for IRQ GTE.

    enum: [3, 11]



  '#timestamp-cells':

    description:

      This represents number of line id arguments as specified by the

      consumers. For the GTE IRQ, this is IRQ number as mentioned in the

      SoC technical reference manual. For the GTE GPIO, its value is same as

      mentioned in the nvidia GPIO device tree binding document.

    const: 1



required:

  - compatible

  - reg

  - interrupts

  - nvidia,slices

  - "#timestamp-cells"



additionalProperties: false



examples:

  - |

    tegra_hte_aon: timestamp@c1e0000 {

              compatible = "nvidia,tegra194-gte-aon";

              reg = <0xc1e0000 0x10000>;

              interrupts = <0 13 0x4>;

              nvidia,int-threshold = <1>;

              nvidia,slices = <3>;

              #timestamp-cells = <1>;

    };



  - |

    tegra_hte_lic: timestamp@3aa0000 {

              compatible = "nvidia,tegra194-gte-lic";

              reg = <0x3aa0000 0x10000>;

              interrupts = <0 11 0x4>;

              nvidia,int-threshold = <1>;

              nvidia,slices = <11>;

              #timestamp-cells = <1>;

    };



...

Documentation/hte/hte.rst

0 → 100644
+79 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0+



============================================

The Linux Hardware Timestamping Engine (HTE)

============================================



:Author: Dipen Patel



Introduction

------------



Certain devices have built in hardware timestamping engines which can

monitor sets of system signals, lines, buses etc... in realtime for state

change; upon detecting the change they can automatically store the timestamp at

the moment of occurrence. Such functionality may help achieve better accuracy

in obtaining timestamps than using software counterparts i.e. ktime and

friends.



This document describes the API that can be used by hardware timestamping

engine provider and consumer drivers that want to use the hardware timestamping

engine (HTE) framework. Both consumers and providers must include

``#include <linux/hte.h>``.



The HTE framework APIs for the providers

----------------------------------------



.. kernel-doc:: drivers/hte/hte.c

   :functions: devm_hte_register_chip hte_push_ts_ns



The HTE framework APIs for the consumers

----------------------------------------



.. kernel-doc:: drivers/hte/hte.c

   :functions: hte_init_line_attr hte_ts_get hte_ts_put devm_hte_request_ts_ns hte_request_ts_ns hte_enable_ts hte_disable_ts of_hte_req_count hte_get_clk_src_info



The HTE framework public structures

-----------------------------------

.. kernel-doc:: include/linux/hte.h



More on the HTE timestamp data

------------------------------

The ``struct hte_ts_data`` is used to pass timestamp details between the

consumers and the providers. It expresses timestamp data in nanoseconds in

u64. An example of the typical timestamp data life cycle, for the GPIO line is

as follows::



 - Monitors GPIO line change.

 - Detects the state change on GPIO line.

 - Converts timestamps in nanoseconds.

 - Stores GPIO raw level in raw_level variable if the provider has that

 hardware capability.

 - Pushes this hte_ts_data object to HTE subsystem.

 - HTE subsystem increments seq counter and invokes consumer provided callback.

 Based on callback return value, the HTE core invokes secondary callback in

 the thread context.



HTE subsystem debugfs attributes

--------------------------------

HTE subsystem creates debugfs attributes at ``/sys/kernel/debug/hte/``.

It also creates line/signal-related debugfs attributes at

``/sys/kernel/debug/hte/<provider>/<label or line id>/``. Note that these

attributes are read-only.



`ts_requested`

		The total number of entities requested from the given provider,

		where entity is specified by the provider and could represent

		lines, GPIO, chip signals, buses etc...

                The attribute will be available at

		``/sys/kernel/debug/hte/<provider>/``.



`total_ts`

		The total number of entities supported by the provider.

                The attribute will be available at

		``/sys/kernel/debug/hte/<provider>/``.



`dropped_timestamps`

		The dropped timestamps for a given line.

                The attribute will be available at

		``/sys/kernel/debug/hte/<provider>/<label or line id>/``.

Documentation/hte/index.rst

0 → 100644
+22 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



============================================

The Linux Hardware Timestamping Engine (HTE)

============================================



The HTE Subsystem

=================



.. toctree::

   :maxdepth: 1



   hte



HTE Tegra Provider

==================



.. toctree::

   :maxdepth: 1



   tegra194-hte