0001 .. SPDX-License-Identifier: GPL-2.0+
0002
0003 ============================================
0004 The Linux Hardware Timestamping Engine (HTE)
0005 ============================================
0006
0007 :Author: Dipen Patel
0008
0009 Introduction
0010 ------------
0011
0012 Certain devices have built in hardware timestamping engines which can
0013 monitor sets of system signals, lines, buses etc... in realtime for state
0014 change; upon detecting the change they can automatically store the timestamp at
0015 the moment of occurrence. Such functionality may help achieve better accuracy
0016 in obtaining timestamps than using software counterparts i.e. ktime and
0017 friends.
0018
0019 This document describes the API that can be used by hardware timestamping
0020 engine provider and consumer drivers that want to use the hardware timestamping
0021 engine (HTE) framework. Both consumers and providers must include
0022 ``#include <linux/hte.h>``.
0023
0024 The HTE framework APIs for the providers
0025 ----------------------------------------
0026
0027 .. kernel-doc:: drivers/hte/hte.c
0028 :functions: devm_hte_register_chip hte_push_ts_ns
0029
0030 The HTE framework APIs for the consumers
0031 ----------------------------------------
0032
0033 .. kernel-doc:: drivers/hte/hte.c
0034 :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
0035
0036 The HTE framework public structures
0037 -----------------------------------
0038 .. kernel-doc:: include/linux/hte.h
0039
0040 More on the HTE timestamp data
0041 ------------------------------
0042 The ``struct hte_ts_data`` is used to pass timestamp details between the
0043 consumers and the providers. It expresses timestamp data in nanoseconds in
0044 u64. An example of the typical timestamp data life cycle, for the GPIO line is
0045 as follows::
0046
0047 - Monitors GPIO line change.
0048 - Detects the state change on GPIO line.
0049 - Converts timestamps in nanoseconds.
0050 - Stores GPIO raw level in raw_level variable if the provider has that
0051 hardware capability.
0052 - Pushes this hte_ts_data object to HTE subsystem.
0053 - HTE subsystem increments seq counter and invokes consumer provided callback.
0054 Based on callback return value, the HTE core invokes secondary callback in
0055 the thread context.
0056
0057 HTE subsystem debugfs attributes
0058 --------------------------------
0059 HTE subsystem creates debugfs attributes at ``/sys/kernel/debug/hte/``.
0060 It also creates line/signal-related debugfs attributes at
0061 ``/sys/kernel/debug/hte/<provider>/<label or line id>/``. Note that these
0062 attributes are read-only.
0063
0064 `ts_requested`
0065 The total number of entities requested from the given provider,
0066 where entity is specified by the provider and could represent
0067 lines, GPIO, chip signals, buses etc...
0068 The attribute will be available at
0069 ``/sys/kernel/debug/hte/<provider>/``.
0070
0071 `total_ts`
0072 The total number of entities supported by the provider.
0073 The attribute will be available at
0074 ``/sys/kernel/debug/hte/<provider>/``.
0075
0076 `dropped_timestamps`
0077 The dropped timestamps for a given line.
0078 The attribute will be available at
0079 ``/sys/kernel/debug/hte/<provider>/<label or line id>/``.
