diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2022-06-05 09:12:28 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2022-06-05 09:12:28 -0700 |
commit | 2981436374177f78539b026ce5bcbab8c251818e (patch) | |
tree | d9d7c4854d4461bec86ca9c0695617a2baeb8e81 /Documentation/hte/hte.rst | |
parent | 71e80720dbf0f08c6979e54f21ddaa5735ce742d (diff) | |
parent | 5dad4eccd2b4316a84209603a28d34c6346392bb (diff) | |
download | linux-2981436374177f78539b026ce5bcbab8c251818e.tar.bz2 |
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
Diffstat (limited to 'Documentation/hte/hte.rst')
-rw-r--r-- | Documentation/hte/hte.rst | 79 |
1 files changed, 79 insertions, 0 deletions
diff --git a/Documentation/hte/hte.rst b/Documentation/hte/hte.rst new file mode 100644 index 000000000000..153f3233c100 --- /dev/null +++ b/Documentation/hte/hte.rst @@ -0,0 +1,79 @@ +.. 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>/``. |