Re: [RFC v2 01/11] Documentation: Add HTE subsystem guide

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On 9/30/21 4:26 PM, Dipen Patel wrote:
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@xxxxxxxxxx>
---
Changes in v2:
- Removed explanation, instead added kernel-doc references.

  Documentation/hte/hte.rst | 83 +++++++++++++++++++++++++++++++++++++++
  1 file changed, 83 insertions(+)
  create mode 100644 Documentation/hte/hte.rst

diff --git a/Documentation/hte/hte.rst b/Documentation/hte/hte.rst
new file mode 100644
index 000000000000..c9b1badae601
--- /dev/null
+++ b/Documentation/hte/hte.rst
@@ -0,0 +1,83 @@
+============================================
+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 timestamp than using software counterparts i.e. ktime and friends.

                timestamps

+
+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 <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: devm_of_hte_request_ts hte_req_ts_by_hte_name hte_release_ts hte_enable_ts hte_disable_ts 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 nano second in u64 data

                                                     nanosesconds
                                             possibly:           in a __u64 data

+type. For now all the HTE APIs using struct hte_ts_data requires tsc to be in

                                                           require tsc to be in

+nano seconds. An example of the typical hte_ts_data data life cycle, for the

   nanoseconds.

+GPIO line is as follows::
+
+ - Monitors GPIO line change.
+ - Detects the state change on GPIO line.
+ - Converts timestamps in nano seconds and stores it in tsc.

                             nanoseconds

+ - Stores GPIO direction in dir 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 starts kernel thread and invokes

                                            starts a kernel thread

+ 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

                        signal-related

+``/sys/kernel/debug/hte/<provider>/<label or line id>/``.
+
+`ts_requested`
+		The total number of entities requested from the given provider,
+		where entity is the provider specific and could represent

		             is specified by the provider and could
(just guessing here; I could not parse it.)

+		lines, GPIO, chip signals, buses etc...
+                The attribute will be availble at

		                         available

+		``/sys/kernel/debug/hte/<provider>/``.
+
+		Read only value

		Read-only value

+
+`total_ts`
+		The total number of entities supported by the provider.
+                The attribute will be availble at

		                         available

+		``/sys/kernel/debug/hte/<provider>/``.
+
+		Read only value

		Read-only value

+
+`dropped_timestamps`
+		The dropped timestamps for a given line.
+                The attribute will be availble at

		                         available

+		``/sys/kernel/debug/hte/<provider>/<label or line id>/``.
+
+		Read only value

		Read-only value



--
~Randy



[Index of Archives]     [Linux SPI]     [Linux Kernel]     [Linux ARM (vger)]     [Linux ARM MSM]     [Linux Omap]     [Linux Arm]     [Linux Tegra]     [Fedora ARM]     [Linux for Samsung SOC]     [eCos]     [Linux Fastboot]     [Gcc Help]     [Git]     [DCCP]     [IETF Announce]     [Security]     [Linux MIPS]     [Yosemite Campsites]

  Powered by Linux