Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

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
··· 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>/``.