1*9c73e1e0SJonathan Corbet.. SPDX-License-Identifier: GPL-2.0+ 2*9c73e1e0SJonathan Corbet 3*9c73e1e0SJonathan Corbet============================================ 4*9c73e1e0SJonathan CorbetThe Linux Hardware Timestamping Engine (HTE) 5*9c73e1e0SJonathan Corbet============================================ 6*9c73e1e0SJonathan Corbet 7*9c73e1e0SJonathan Corbet:Author: Dipen Patel 8*9c73e1e0SJonathan Corbet 9*9c73e1e0SJonathan CorbetIntroduction 10*9c73e1e0SJonathan Corbet------------ 11*9c73e1e0SJonathan Corbet 12*9c73e1e0SJonathan CorbetCertain devices have built in hardware timestamping engines which can 13*9c73e1e0SJonathan Corbetmonitor sets of system signals, lines, buses etc... in realtime for state 14*9c73e1e0SJonathan Corbetchange; upon detecting the change they can automatically store the timestamp at 15*9c73e1e0SJonathan Corbetthe moment of occurrence. Such functionality may help achieve better accuracy 16*9c73e1e0SJonathan Corbetin obtaining timestamps than using software counterparts i.e. ktime and 17*9c73e1e0SJonathan Corbetfriends. 18*9c73e1e0SJonathan Corbet 19*9c73e1e0SJonathan CorbetThis document describes the API that can be used by hardware timestamping 20*9c73e1e0SJonathan Corbetengine provider and consumer drivers that want to use the hardware timestamping 21*9c73e1e0SJonathan Corbetengine (HTE) framework. Both consumers and providers must include 22*9c73e1e0SJonathan Corbet``#include <linux/hte.h>``. 23*9c73e1e0SJonathan Corbet 24*9c73e1e0SJonathan CorbetThe HTE framework APIs for the providers 25*9c73e1e0SJonathan Corbet---------------------------------------- 26*9c73e1e0SJonathan Corbet 27*9c73e1e0SJonathan Corbet.. kernel-doc:: drivers/hte/hte.c 28*9c73e1e0SJonathan Corbet :functions: devm_hte_register_chip hte_push_ts_ns 29*9c73e1e0SJonathan Corbet 30*9c73e1e0SJonathan CorbetThe HTE framework APIs for the consumers 31*9c73e1e0SJonathan Corbet---------------------------------------- 32*9c73e1e0SJonathan Corbet 33*9c73e1e0SJonathan Corbet.. kernel-doc:: drivers/hte/hte.c 34*9c73e1e0SJonathan Corbet :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*9c73e1e0SJonathan Corbet 36*9c73e1e0SJonathan CorbetThe HTE framework public structures 37*9c73e1e0SJonathan Corbet----------------------------------- 38*9c73e1e0SJonathan Corbet.. kernel-doc:: include/linux/hte.h 39*9c73e1e0SJonathan Corbet 40*9c73e1e0SJonathan CorbetMore on the HTE timestamp data 41*9c73e1e0SJonathan Corbet------------------------------ 42*9c73e1e0SJonathan CorbetThe ``struct hte_ts_data`` is used to pass timestamp details between the 43*9c73e1e0SJonathan Corbetconsumers and the providers. It expresses timestamp data in nanoseconds in 44*9c73e1e0SJonathan Corbetu64. An example of the typical timestamp data life cycle, for the GPIO line is 45*9c73e1e0SJonathan Corbetas follows:: 46*9c73e1e0SJonathan Corbet 47*9c73e1e0SJonathan Corbet - Monitors GPIO line change. 48*9c73e1e0SJonathan Corbet - Detects the state change on GPIO line. 49*9c73e1e0SJonathan Corbet - Converts timestamps in nanoseconds. 50*9c73e1e0SJonathan Corbet - Stores GPIO raw level in raw_level variable if the provider has that 51*9c73e1e0SJonathan Corbet hardware capability. 52*9c73e1e0SJonathan Corbet - Pushes this hte_ts_data object to HTE subsystem. 53*9c73e1e0SJonathan Corbet - HTE subsystem increments seq counter and invokes consumer provided callback. 54*9c73e1e0SJonathan Corbet Based on callback return value, the HTE core invokes secondary callback in 55*9c73e1e0SJonathan Corbet the thread context. 56*9c73e1e0SJonathan Corbet 57*9c73e1e0SJonathan CorbetHTE subsystem debugfs attributes 58*9c73e1e0SJonathan Corbet-------------------------------- 59*9c73e1e0SJonathan CorbetHTE subsystem creates debugfs attributes at ``/sys/kernel/debug/hte/``. 60*9c73e1e0SJonathan CorbetIt also creates line/signal-related debugfs attributes at 61*9c73e1e0SJonathan Corbet``/sys/kernel/debug/hte/<provider>/<label or line id>/``. Note that these 62*9c73e1e0SJonathan Corbetattributes are read-only. 63*9c73e1e0SJonathan Corbet 64*9c73e1e0SJonathan Corbet`ts_requested` 65*9c73e1e0SJonathan Corbet The total number of entities requested from the given provider, 66*9c73e1e0SJonathan Corbet where entity is specified by the provider and could represent 67*9c73e1e0SJonathan Corbet lines, GPIO, chip signals, buses etc... 68*9c73e1e0SJonathan Corbet The attribute will be available at 69*9c73e1e0SJonathan Corbet ``/sys/kernel/debug/hte/<provider>/``. 70*9c73e1e0SJonathan Corbet 71*9c73e1e0SJonathan Corbet`total_ts` 72*9c73e1e0SJonathan Corbet The total number of entities supported by the provider. 73*9c73e1e0SJonathan Corbet The attribute will be available at 74*9c73e1e0SJonathan Corbet ``/sys/kernel/debug/hte/<provider>/``. 75*9c73e1e0SJonathan Corbet 76*9c73e1e0SJonathan Corbet`dropped_timestamps` 77*9c73e1e0SJonathan Corbet The dropped timestamps for a given line. 78*9c73e1e0SJonathan Corbet The attribute will be available at 79*9c73e1e0SJonathan Corbet ``/sys/kernel/debug/hte/<provider>/<label or line id>/``. 80