요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0+
============================================
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: hte_init_line_attr hte_ts_get hte_ts_put devm_hte_request_ts_ns hte_request_ts_ns hte_enable_ts hte_disable_ts of_hte_req_count 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. An example of the typical timestamp 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.
- 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>/``. Note that these
attributes are read-only.
`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>/``.
`total_ts`
The total number of entities supported by the provider.
The attribute will be available at
``/sys/kernel/debug/hte/<provider>/``.
`dropped_timestamps`
The dropped timestamps for a given line.
The attribute will be available at
``/sys/kernel/debug/hte/<provider>/<label or line id>/``.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Hardware Timestamping Engine 소개
1-23문서 제목은 `The Linux Hardware Timestamping Engine (HTE)`이며 저자는 Dipen Patel입니다.
일부 device에는 system signal, line, bus 등의 state change를 real time으로 감시하고 변화가 감지된 바로 그 순간의 timestamp를 자동 저장하는 hardware timestamping engine이 내장되어 있습니다.
이 기능은 `ktime` 계열 같은 software 방식보다 정확한 timestamp를 얻는 데 도움이 됩니다.
문서는 HTE framework를 사용하는 hardware timestamp engine provider·consumer driver용 API를 설명합니다. Consumer와 provider 모두 `#include <linux/hte.h>`를 include해야 합니다.
Signal 변화에서 nanosecond timestamp 전달까지의 큰 흐름입니다.
Provider·consumer API와 public structure
24-39Provider framework API는 `drivers/hte/hte.c`의 `devm_hte_register_chip`, `hte_push_ts_ns`입니다.
.. kernel-doc:: drivers/hte/hte.c
:functions: devm_hte_register_chip hte_push_ts_nsConsumer API는 같은 source의 `hte_init_line_attr`, `hte_ts_get`, `hte_ts_put`, managed·unmanaged request, enable·disable, Device Tree request count와 clock-source 정보 function입니다.
.. kernel-doc:: drivers/hte/hte.c
:functions: hte_init_line_attr hte_ts_get hte_ts_put devm_hte_request_ts_ns hte_request_ts_ns hte_enable_ts hte_disable_ts of_hte_req_count hte_get_clk_src_infoPublic structure의 kernel-doc source는 `include/linux/hte.h`입니다.
.. kernel-doc:: include/linux/hte.hProvider와 consumer가 호출하는 핵심 API를 구분합니다.
struct hte_ts_data lifecycle
40-56`struct hte_ts_data`는 consumer와 provider 사이에서 timestamp detail을 전달하며 nanosecond timestamp를 `u64`로 표현합니다.
GPIO line의 전형적인 lifecycle은 line change 감시, state change 감지, timestamp를 nanosecond로 변환, provider hardware가 지원하면 `raw_level`에 GPIO raw level 저장, `hte_ts_data`를 HTE subsystem으로 push하는 순서입니다.
HTE subsystem은 sequence counter를 증가시키고 consumer가 제공한 callback을 호출합니다. Callback return value에 따라 HTE core가 thread context의 secondary callback을 호출합니다.
원문의 GPIO timestamp 처리 단계를 구조화했습니다.
HTE debugfs attribute
57-79HTE subsystem은 `/sys/kernel/debug/hte/`에 debugfs attribute를 만듭니다. Line·signal별 read-only attribute는 `/sys/kernel/debug/hte/<provider>/<label or line id>/`에 생성됩니다.
`ts_requested`는 provider에서 요청된 entity의 총수입니다. Entity의 의미는 provider가 정하며 line, GPIO, chip signal, bus 등이 될 수 있습니다. 위치는 `/sys/kernel/debug/hte/<provider>/`입니다.
`total_ts`는 provider가 지원하는 entity 총수이며 같은 provider directory에 있습니다.
`dropped_timestamps`는 특정 line에서 누락된 timestamp 수이며 line·label directory에 있습니다.
Read-only statistic의 의미와 위치입니다.
요약과 해설
hte.rst:1-79HTE는 signal 변화 순간을 hardware에서 capture해 software timestamp보다 높은 정확도를 제공합니다. Provider는 nanosecond timestamp를 push하고 core는 sequence를 관리하며 consumer callback과 optional threaded callback을 호출합니다.