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 <[email protected]>
---
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.
+
+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
+type. For now all the HTE APIs using struct hte_ts_data requires tsc to be in
+nano seconds. An example of the typical hte_ts_data data life cycle, for the
+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.
+ - 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
+ 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
+``/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
+ lines, GPIO, chip signals, buses etc...
+ The attribute will be availble at
+ ``/sys/kernel/debug/hte/<provider>/``.
+
+ Read only value
+
+`total_ts`
+ The total number of entities supported by the provider.
+ The attribute will be availble at
+ ``/sys/kernel/debug/hte/<provider>/``.
+
+ Read only value
+
+`dropped_timestamps`
+ The dropped timestamps for a given line.
+ The attribute will be availble at
+ ``/sys/kernel/debug/hte/<provider>/<label or line id>/``.
+
+ Read only value
--
2.17.1
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 <[email protected]>
> ---
> 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
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 <[email protected]>
>> ---
>> 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
>>
>
>