Documentation/driver-api/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>/``.