Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Subject: Re: [RFC v2 01/11] Documentation: Add HTE subsystem guide
To:     Dipen Patel <dipenp@nvidia.com>, thierry.reding@gmail.com,
        jonathanh@nvidia.com, linux-kernel@vger.kernel.org,
        linux-tegra@vger.kernel.org, linux-gpio@vger.kernel.org,
        linus.walleij@linaro.org, bgolaszewski@baylibre.com,
        warthog618@gmail.com, devicetree@vger.kernel.org,
        linux-doc@vger.kernel.org, robh+dt@kernel.org
References: <20210930232617.6396-1-dipenp@nvidia.com>
 <20210930232617.6396-2-dipenp@nvidia.com>
From:   Randy Dunlap <rdunlap@infradead.org>
Message-ID: <70321686-276c-b972-302a-e649f28412de@infradead.org>
Date:   Fri, 1 Oct 2021 17:18:39 -0700
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101
 Thunderbird/78.13.0
MIME-Version: 1.0
In-Reply-To: <20210930232617.6396-2-dipenp@nvidia.com>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-US
Content-Transfer-Encoding: 7bit
Precedence: bulk

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@nvidia.com>
> ---
> 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