Skip to content

Commit 2981436

Browse files
torvaldstorvalds
committed
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
2 parents 71e8072 + 5dad4ec commit 2981436

24 files changed

+2930
-37
lines changed

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2+
%YAML 1.2
3+
---
4+
$id: http://devicetree.org/schemas/timestamp/hardware-timestamps-common.yaml#
5+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6+
7+
title: Hardware timestamp providers
8+
9+
maintainers:
10+
- Dipen Patel <[email protected]>
11+
12+
description:
13+
Some devices/SoCs have hardware timestamp engines (HTE) which can use
14+
hardware means to timestamp entity in realtime. The entity could be anything
15+
from GPIOs, IRQs, Bus and so on. The hardware timestamp engine present
16+
itself as a provider with the bindings described in this document.
17+
18+
properties:
19+
$nodename:
20+
pattern: "^timestamp(@.*|-[0-9a-f])?$"
21+
22+
"#timestamp-cells":
23+
description:
24+
Number of cells in a HTE specifier.
25+
26+
required:
27+
- "#timestamp-cells"
28+
29+
additionalProperties: true

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

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2+
%YAML 1.2
3+
---
4+
$id: http://devicetree.org/schemas/timestamp/hte-consumer.yaml#
5+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6+
7+
title: HTE Consumer Device Tree Bindings
8+
9+
maintainers:
10+
- Dipen Patel <[email protected]>
11+
12+
select: true
13+
14+
properties:
15+
timestamps:
16+
$ref: /schemas/types.yaml#/definitions/phandle-array
17+
description:
18+
The list of HTE provider phandle. The first cell must represent the
19+
provider phandle followed by the line identifiers. The meaning of the
20+
line identifier and exact number of arguments must be specified in the
21+
HTE provider device tree binding document.
22+
23+
timestamp-names:
24+
$ref: /schemas/types.yaml#/definitions/string-array
25+
description:
26+
An optional string property to label each line specifier present in the
27+
timestamp property.
28+
29+
dependencies:
30+
timestamp-names: [ timestamps ]
31+
32+
additionalProperties: true
33+
34+
examples:
35+
- |
36+
hte_tegra_consumer {
37+
timestamps = <&tegra_hte_aon 0x9>, <&tegra_hte_lic 0x19>;
38+
timestamp-names = "hte-gpio", "hte-i2c";
39+
};

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2+
%YAML 1.2
3+
---
4+
$id: http://devicetree.org/schemas/timestamp/nvidia,tegra194-hte.yaml#
5+
$schema: http://devicetree.org/meta-schemas/core.yaml#
6+
7+
title: Tegra194 on chip generic hardware timestamping engine (HTE)
8+
9+
maintainers:
10+
- Dipen Patel <[email protected]>
11+
12+
description:
13+
Tegra SoC has two instances of generic hardware timestamping engines (GTE)
14+
known as GTE GPIO and GTE IRQ, which can monitor subset of GPIO and on chip
15+
IRQ lines for the state change respectively, upon detection it will record
16+
timestamp (taken from system counter) in its internal hardware FIFO. It has
17+
a bitmap array arranged in 32bit slices where each bit represent signal/line
18+
to enable or disable for the hardware timestamping. The GTE GPIO monitors
19+
GPIO lines from the AON (always on) GPIO controller.
20+
21+
properties:
22+
compatible:
23+
enum:
24+
- nvidia,tegra194-gte-aon
25+
- nvidia,tegra194-gte-lic
26+
27+
reg:
28+
maxItems: 1
29+
30+
interrupts:
31+
maxItems: 1
32+
33+
nvidia,int-threshold:
34+
$ref: /schemas/types.yaml#/definitions/uint32
35+
description:
36+
HTE device generates its interrupt based on this u32 FIFO threshold
37+
value. The recommended value is 1.
38+
minimum: 1
39+
maximum: 256
40+
41+
nvidia,slices:
42+
$ref: /schemas/types.yaml#/definitions/uint32
43+
description:
44+
HTE lines are arranged in 32 bit slice where each bit represents different
45+
line/signal that it can enable/configure for the timestamp. It is u32
46+
property and depends on the HTE instance in the chip. The value 3 is for
47+
GPIO GTE and 11 for IRQ GTE.
48+
enum: [3, 11]
49+
50+
'#timestamp-cells':
51+
description:
52+
This represents number of line id arguments as specified by the
53+
consumers. For the GTE IRQ, this is IRQ number as mentioned in the
54+
SoC technical reference manual. For the GTE GPIO, its value is same as
55+
mentioned in the nvidia GPIO device tree binding document.
56+
const: 1
57+
58+
required:
59+
- compatible
60+
- reg
61+
- interrupts
62+
- nvidia,slices
63+
- "#timestamp-cells"
64+
65+
additionalProperties: false
66+
67+
examples:
68+
- |
69+
tegra_hte_aon: timestamp@c1e0000 {
70+
compatible = "nvidia,tegra194-gte-aon";
71+
reg = <0xc1e0000 0x10000>;
72+
interrupts = <0 13 0x4>;
73+
nvidia,int-threshold = <1>;
74+
nvidia,slices = <3>;
75+
#timestamp-cells = <1>;
76+
};
77+
78+
- |
79+
tegra_hte_lic: timestamp@3aa0000 {
80+
compatible = "nvidia,tegra194-gte-lic";
81+
reg = <0x3aa0000 0x10000>;
82+
interrupts = <0 11 0x4>;
83+
nvidia,int-threshold = <1>;
84+
nvidia,slices = <11>;
85+
#timestamp-cells = <1>;
86+
};
87+
88+
...

‎Documentation/hte/hte.rst

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
.. SPDX-License-Identifier: GPL-2.0+
2+
3+
============================================
4+
The Linux Hardware Timestamping Engine (HTE)
5+
============================================
6+
7+
:Author: Dipen Patel
8+
9+
Introduction
10+
------------
11+
12+
Certain devices have built in hardware timestamping engines which can
13+
monitor sets of system signals, lines, buses etc... in realtime for state
14+
change; upon detecting the change they can automatically store the timestamp at
15+
the moment of occurrence. Such functionality may help achieve better accuracy
16+
in obtaining timestamps than using software counterparts i.e. ktime and
17+
friends.
18+
19+
This document describes the API that can be used by hardware timestamping
20+
engine provider and consumer drivers that want to use the hardware timestamping
21+
engine (HTE) framework. Both consumers and providers must include
22+
``#include <linux/hte.h>``.
23+
24+
The HTE framework APIs for the providers
25+
----------------------------------------
26+
27+
.. kernel-doc:: drivers/hte/hte.c
28+
:functions: devm_hte_register_chip hte_push_ts_ns
29+
30+
The HTE framework APIs for the consumers
31+
----------------------------------------
32+
33+
.. kernel-doc:: drivers/hte/hte.c
34+
: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
35+
36+
The HTE framework public structures
37+
-----------------------------------
38+
.. kernel-doc:: include/linux/hte.h
39+
40+
More on the HTE timestamp data
41+
------------------------------
42+
The ``struct hte_ts_data`` is used to pass timestamp details between the
43+
consumers and the providers. It expresses timestamp data in nanoseconds in
44+
u64. An example of the typical timestamp data life cycle, for the GPIO line is
45+
as follows::
46+
47+
- Monitors GPIO line change.
48+
- Detects the state change on GPIO line.
49+
- Converts timestamps in nanoseconds.
50+
- Stores GPIO raw level in raw_level variable if the provider has that
51+
hardware capability.
52+
- Pushes this hte_ts_data object to HTE subsystem.
53+
- HTE subsystem increments seq counter and invokes consumer provided callback.
54+
Based on callback return value, the HTE core invokes secondary callback in
55+
the thread context.
56+
57+
HTE subsystem debugfs attributes
58+
--------------------------------
59+
HTE subsystem creates debugfs attributes at ``/sys/kernel/debug/hte/``.
60+
It also creates line/signal-related debugfs attributes at
61+
``/sys/kernel/debug/hte/<provider>/<label or line id>/``. Note that these
62+
attributes are read-only.
63+
64+
`ts_requested`
65+
The total number of entities requested from the given provider,
66+
where entity is specified by the provider and could represent
67+
lines, GPIO, chip signals, buses etc...
68+
The attribute will be available at
69+
``/sys/kernel/debug/hte/<provider>/``.
70+
71+
`total_ts`
72+
The total number of entities supported by the provider.
73+
The attribute will be available at
74+
``/sys/kernel/debug/hte/<provider>/``.
75+
76+
`dropped_timestamps`
77+
The dropped timestamps for a given line.
78+
The attribute will be available at
79+
``/sys/kernel/debug/hte/<provider>/<label or line id>/``.

‎Documentation/hte/index.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
============================================
4+
The Linux Hardware Timestamping Engine (HTE)
5+
============================================
6+
7+
The HTE Subsystem
8+
=================
9+
10+
.. toctree::
11+
:maxdepth: 1
12+
13+
hte
14+
15+
HTE Tegra Provider
16+
==================
17+
18+
.. toctree::
19+
:maxdepth: 1
20+
21+
tegra194-hte
22+

‎Documentation/hte/tegra194-hte.rst

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
.. SPDX-License-Identifier: GPL-2.0+
2+
3+
HTE Kernel provider driver
4+
==========================
5+
6+
Description
7+
-----------
8+
The Nvidia tegra194 HTE provider driver implements two GTE
9+
(Generic Timestamping Engine) instances: 1) GPIO GTE and 2) LIC
10+
(Legacy Interrupt Controller) IRQ GTE. Both GTE instances get the
11+
timestamp from the system counter TSC which has 31.25MHz clock rate, and the
12+
driver converts clock tick rate to nanoseconds before storing it as timestamp
13+
value.
14+
15+
GPIO GTE
16+
--------
17+
18+
This GTE instance timestamps GPIO in real time. For that to happen GPIO
19+
needs to be configured as input. The always on (AON) GPIO controller instance
20+
supports timestamping GPIOs in real time and it has 39 GPIO lines. The GPIO GTE
21+
and AON GPIO controller are tightly coupled as it requires very specific bits
22+
to be set in GPIO config register before GPIO GTE can be used, for that GPIOLIB
23+
adds two optional APIs as below. The GPIO GTE code supports both kernel
24+
and userspace consumers. The kernel space consumers can directly talk to HTE
25+
subsystem while userspace consumers timestamp requests go through GPIOLIB CDEV
26+
framework to HTE subsystem.
27+
28+
.. kernel-doc:: drivers/gpio/gpiolib.c
29+
:functions: gpiod_enable_hw_timestamp_ns gpiod_disable_hw_timestamp_ns
30+
31+
For userspace consumers, GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE flag must be
32+
specified during IOCTL calls. Refer to ``tools/gpio/gpio-event-mon.c``, which
33+
returns the timestamp in nanoseconds.
34+
35+
LIC (Legacy Interrupt Controller) IRQ GTE
36+
-----------------------------------------
37+
38+
This GTE instance timestamps LIC IRQ lines in real time. There are 352 IRQ
39+
lines which this instance can add timestamps to in real time. The hte
40+
devicetree binding described at ``Documentation/devicetree/bindings/hte/``
41+
provides an example of how a consumer can request an IRQ line. Since it is a
42+
one-to-one mapping with IRQ GTE provider, consumers can simply specify the IRQ
43+
number that they are interested in. There is no userspace consumer support for
44+
this GTE instance in the HTE framework.
45+
46+
The provider source code of both IRQ and GPIO GTE instances is located at
47+
``drivers/hte/hte-tegra194.c``. The test driver
48+
``drivers/hte/hte-tegra194-test.c`` demonstrates HTE API usage for both IRQ
49+
and GPIO GTE.

‎Documentation/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,7 @@ needed).
137137
scheduler/index
138138
mhi/index
139139
peci/index
140+
hte/index
140141

141142
Architecture-agnostic documentation
142143
-----------------------------------

‎MAINTAINERS

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9077,6 +9077,14 @@ L: [email protected]
90779077
S: Maintained
90789078
F: drivers/input/touchscreen/htcpen.c
90799079

9080+
HTE SUBSYSTEM
9081+
M: Dipen Patel <[email protected]>
9082+
S: Maintained
9083+
F: Documentation/devicetree/bindings/timestamp/
9084+
F: Documentation/hte/
9085+
F: drivers/hte/
9086+
F: include/linux/hte.h
9087+
90809088
HTS221 TEMPERATURE-HUMIDITY IIO DRIVER
90819089
M: Lorenzo Bianconi <[email protected]>
90829090
L: [email protected]

‎drivers/Kconfig

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,4 +237,6 @@ source "drivers/most/Kconfig"
237237

238238
source "drivers/peci/Kconfig"
239239

240+
source "drivers/hte/Kconfig"
241+
240242
endmenu

‎drivers/Makefile

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,3 +187,4 @@ obj-$(CONFIG_INTERCONNECT) += interconnect/
187187
obj-$(CONFIG_COUNTER) += counter/
188188
obj-$(CONFIG_MOST) += most/
189189
obj-$(CONFIG_PECI) += peci/
190+
obj-$(CONFIG_HTE) += hte/

0 commit comments

Comments
 (0)