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;
Received-SPF: Pass (protection.outlook.com: domain of nvidia.com designates
 216.228.112.34 as permitted sender) receiver=protection.outlook.com;
 client-ip=216.228.112.34; helo=mail.nvidia.com;
Subject: Re: [RFC v2 01/11] Documentation: Add HTE subsystem guide
To:     Randy Dunlap <rdunlap@infradead.org>, <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>
 <70321686-276c-b972-302a-e649f28412de@infradead.org>
From:   Dipen Patel <dipenp@nvidia.com>
Message-ID: <fa9d2328-2b4b-fa94-f884-3980706c1ae6@nvidia.com>
Date:   Tue, 2 Nov 2021 17:36:03 -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: <70321686-276c-b972-302a-e649f28412de@infradead.org>
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit
Content-Language: en-US
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 03 Nov 2021 00:35:09.9953
 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: ca91de19-c5b1-4e7e-b9eb-08d99e61cae8
X-MS-Exchange-CrossTenant-Id: 43083d15-7273-40c1-b7db-39efd9ccc17a
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=43083d15-7273-40c1-b7db-39efd9ccc17a;Ip=[216.228.112.34];Helo=[mail.nvidia.com]
X-MS-Exchange-CrossTenant-AuthSource: BN8NAM11FT057.eop-nam11.prod.protection.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Anonymous
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: MN2PR12MB3581
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

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@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
>>
>
>