Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <db81d120-039d-f49f-9a48-c91e96777a61@gmail.com>
Date:   Tue, 29 Mar 2022 20:16:42 +0700
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.7.0
Subject: Re: [PATCH v5 01/11] Documentation: Add HTE subsystem guide
Content-Language: en-US
To:     Dipen Patel <dipenp@nvidia.com>, thierry.reding@gmail.com,
        jonathanh@nvidia.com, smangipudi@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: <20220329054521.14420-1-dipenp@nvidia.com>
 <20220329054521.14420-2-dipenp@nvidia.com>
From:   Bagas Sanjaya <bagasdotme@gmail.com>
In-Reply-To: <20220329054521.14420-2-dipenp@nvidia.com>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Precedence: bulk

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".

-- 
An old man doll... just what I always wanted! - Clara