Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: Add HTE subsystem guide
Adding hte document which can help understand various APIs implemented
in HTE framework for the HTE producers and the consumers.
Signed-off-by: Dipen Patel <dipenp@nvidia.com>
Signed-off-by: Thierry Reding <treding@nvidia.com>
authored by
Dipen Patel
and committed by
Thierry Reding
6406ac63
31231092
+79
+79
Documentation/hte/hte.rst
+79
Documentation/hte/hte.rst
···
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>/``.