Hi Randy, Thanks for the comments, will implement all your suggestions in RFC V3. On 10/1/21 5:18 PM, Randy Dunlap wrote: > 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 >> > >
