[v5,01/11] Documentation: Add HTE subsystem guide

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@nvidia.com>
---
Changes in v2:
- Removed explanation, instead added kernel-doc references.

Changes in v3:
- Addressed grammatical errors.

Changes in v4:
- Added new API hte_req_ts_by_linedata_ns description.
- Removed hte_req_ts_by_hte_name.

 Documentation/hte/hte.rst | 83 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 Documentation/hte/hte.rst

On 29/03/22 12.45, Dipen Patel wrote:
> +============================================
> +The Linux Hardware Timestamping Engine (HTE)
> +============================================
> +
> +:Author: Dipen Patel
> +

Please learn how to convey semantics with rst format, see further comments
below.

> +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
> +#include <linux/hte.h>.
> +

Maybe it's better to write as `... 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_ns hte_req_ts_by_linedata_ns 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 nanoseconds in u64 data
> +type. For now all the HTE APIs using struct hte_ts_data require tsc to be in
> +nanoseconds. An example of the typical hte_ts_data data life cycle, for the
> +GPIO line is as follows::
> +

When we talk about name terms found in actual code (like keywords or variable
names), it is customary to enclose them inside inline code (for example,
``struct what`` or ``u64 what``).

> + - Monitors GPIO line change.
> + - Detects the state change on GPIO line.
> + - Converts timestamps in nanoseconds and stores it in tsc.
> + - Stores GPIO raw level in raw_level 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 core 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 specified by the provider and could represent
> +		lines, GPIO, chip signals, buses etc...
> +                The attribute will be available at
> +		``/sys/kernel/debug/hte/<provider>/``.
> +
> +		Read-only value
> +
> +`total_ts`
> +		The total number of entities supported by the provider.
> +                The attribute will be available at
> +		``/sys/kernel/debug/hte/<provider>/``.
> +
> +		Read-only value
> +
> +`dropped_timestamps`
> +		The dropped timestamps for a given line.
> +                The attribute will be available at
> +		``/sys/kernel/debug/hte/<provider>/<label or line id>/``.
> +
> +		Read-only value

Since all these debugfs variables are read-only, we can say "Note that all
these values are read-only".

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> On 29/03/22 12.45, Dipen Patel wrote:
>> +============================================
>> +The Linux Hardware Timestamping Engine (HTE)
>> +============================================
>> +
>> +:Author: Dipen Patel
>> +
>
> Please learn how to convey semantics with rst format, see further comments
> below.

That is the Sphinx "field list" syntax; it's pretty heavily used
throughout the kernel documentation and doesn't seem to merit that sort
of response...?

[...]

>> +The struct hte_ts_data is used to pass timestamp details between the consumers
>> +and the providers. It expresses timestamp data in nanoseconds in u64 data
>> +type. For now all the HTE APIs using struct hte_ts_data require tsc to be in
>> +nanoseconds. An example of the typical hte_ts_data data life cycle, for the
>> +GPIO line is as follows::
>> +
>
> When we talk about name terms found in actual code (like keywords or variable
> names), it is customary to enclose them inside inline code (for example,
> ``struct what`` or ``u64 what``).

It's also customary to minimize markup.  In the case of "struct
whatever" the markup is actively harmful since it interferes with the
automatic recognition and cross-referencing of the type.

jon

Hi Sanjaya,

I will address your comments in next patch version.  Thanks for the comment.

Best,

Dipen Patel

On 3/29/22 6:16 AM, Bagas Sanjaya wrote:
> On 29/03/22 12.45, Dipen Patel wrote:
>> +============================================
>> +The Linux Hardware Timestamping Engine (HTE)
>> +============================================
>> +
>> +:Author: Dipen Patel
>> +
>
> Please learn how to convey semantics with rst format, see further comments
> below.
>
>> +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
>> +#include <linux/hte.h>.
>> +
>
> Maybe it's better to write as `... 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_ns hte_req_ts_by_linedata_ns 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 nanoseconds in u64 data
>> +type. For now all the HTE APIs using struct hte_ts_data require tsc to be in
>> +nanoseconds. An example of the typical hte_ts_data data life cycle, for the
>> +GPIO line is as follows::
>> +
>
> When we talk about name terms found in actual code (like keywords or variable
> names), it is customary to enclose them inside inline code (for example,
> ``struct what`` or ``u64 what``).
>
>> + - Monitors GPIO line change.
>> + - Detects the state change on GPIO line.
>> + - Converts timestamps in nanoseconds and stores it in tsc.
>> + - Stores GPIO raw level in raw_level 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 core 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 specified by the provider and could represent
>> +        lines, GPIO, chip signals, buses etc...
>> +                The attribute will be available at
>> +        ``/sys/kernel/debug/hte/<provider>/``.
>> +
>> +        Read-only value
>> +
>> +`total_ts`
>> +        The total number of entities supported by the provider.
>> +                The attribute will be available at
>> +        ``/sys/kernel/debug/hte/<provider>/``.
>> +
>> +        Read-only value
>> +
>> +`dropped_timestamps`
>> +        The dropped timestamps for a given line.
>> +                The attribute will be available at
>> +        ``/sys/kernel/debug/hte/<provider>/<label or line id>/``.
>> +
>> +        Read-only value
>
> Since all these debugfs variables are read-only, we can say "Note that all
> these values are read-only".
>

Hi,

On 3/29/22 8:27 AM, Jonathan Corbet wrote:
> Bagas Sanjaya <bagasdotme@gmail.com> writes:
>
>> On 29/03/22 12.45, Dipen Patel wrote:
>>> +============================================
>>> +The Linux Hardware Timestamping Engine (HTE)
>>> +============================================
>>> +
>>> +:Author: Dipen Patel
>>> +
>> Please learn how to convey semantics with rst format, see further comments
>> below.
> That is the Sphinx "field list" syntax; it's pretty heavily used
> throughout the kernel documentation and doesn't seem to merit that sort
> of response...?
>
> [...]
>
>>> +The struct hte_ts_data is used to pass timestamp details between the consumers
>>> +and the providers. It expresses timestamp data in nanoseconds in u64 data
>>> +type. For now all the HTE APIs using struct hte_ts_data require tsc to be in
>>> +nanoseconds. An example of the typical hte_ts_data data life cycle, for the
>>> +GPIO line is as follows::
>>> +
>> When we talk about name terms found in actual code (like keywords or variable
>> names), it is customary to enclose them inside inline code (for example,
>> ``struct what`` or ``u64 what``).
> It's also customary to minimize markup.  In the case of "struct
> whatever" the markup is actively harmful since it interferes with the
> automatic recognition and cross-referencing of the type.
I agree, I will keep only necessary reference in this section.
>
> jon