| Message ID | 20220118002214.18271-2-dipenp@nvidia.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [RFC,v4,01/11] Documentation: Add HTE subsystem guide | expand |
Dipen Patel <dipenp@nvidia.com> 于2022年1月18日周二 11:06写道： > > 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 +++++++++++++++++++++++++++++++++++++++ Hi Dipen A document build warning will be introduced，Need to add it to the index: 1) Create Documentation/hte/index.rst 2) Add hte/index.rst into Documentation/index.rst 3) Add hte.rst into Documentation/hte/index.rst Thanks, Yanteng
Hi Teng, I believe I added in patch 0003. Before sending this patch series, I did make htmldocs and did compile successfully. Let me know in case I am missing something. On 1/19/22 6:03 PM, teng sterling wrote: > Dipen Patel <dipenp@nvidia.com> 于2022年1月18日周二 11:06写道： >> 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 +++++++++++++++++++++++++++++++++++++++ > Hi Dipen > > A document build warning will be introduced，Need to add it to the index: > > 1) Create Documentation/hte/index.rst > 2) Add hte/index.rst into Documentation/index.rst > 3) Add hte.rst into Documentation/hte/index.rst > > Thanks, > Yanteng
Dipen Patel <dipenp@nvidia.com> 于2022年1月20日周四 12:21写道： > > Hi Teng, > > I believe I added in patch 0003. Before sending this patch series, I did make htmldocs and did compile successfully. Let me know in case I am missing something. Sorry I didn't read through your patch carefully. I'll be happy to translate fresh documentation into Chinese, please let me know if these are applied, Thank you! >_< Thanks, Yanteng > > On 1/19/22 6:03 PM, teng sterling wrote: > > Dipen Patel <dipenp@nvidia.com> 于2022年1月18日周二 11:06写道： > >> 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 +++++++++++++++++++++++++++++++++++++++ > > Hi Dipen > > > > A document build warning will be introduced，Need to add it to the index: > > > > 1) Create Documentation/hte/index.rst > > 2) Add hte/index.rst into Documentation/index.rst > > 3) Add hte.rst into Documentation/hte/index.rst > > > > Thanks, > > Yanteng
diff --git a/Documentation/hte/hte.rst b/Documentation/hte/hte.rst new file mode 100644 index 000000000000..f82113e540b8 --- /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 timestamps 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 +#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:: + + - 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 starts a 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 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
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