요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
Heartbeat period, counters, status
debugfs-driver-qat:12-61Userspace polling 주기에 맞춰 heartbeat update period를 설정하고 전체 query 수, 실패 수와 현재 device health를 읽습니다. Driver는 heartbeat를 자동 monitor하지 않습니다.
Power management와 verified compression errors
debugfs-driver-qat:63-83지원 device의 power management 정보와 각 Acceleration Engine의 Compress and Verify error 수 및 마지막 error type을 읽습니다.
Unrecoverable heartbeat failure injection
debugfs-driver-qat:85-109시험 목적으로 random engine arbitration과 heartbeat counter fetch를 중단해 device unresponsive 상태를 만들며, 복구하려면 device를 restart해야 합니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
What: /sys/kernel/debug/qat_<device>_<BDF>/fw_counters
Date: November 2023
KernelVersion: 6.6
Contact: [email protected]
Description: (RO) Read returns the number of requests sent to the FW and the number of responses
received from the FW for each Acceleration Engine
Reported firmware counters::
<N>: Number of requests sent from Acceleration Engine N to FW and responses
Acceleration Engine N received from FW
What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/config
Date: November 2023
KernelVersion: 6.6
Contact: [email protected]
Description: (RW) Read returns value of the Heartbeat update period.
Write to the file changes this period value.
This period should reflect planned polling interval of device
health status. High frequency Heartbeat monitoring wastes CPU cycles
but minimizes the customer’s system downtime. Also, if there are
large service requests that take some time to complete, high frequency
Heartbeat monitoring could result in false reports of unresponsiveness
and in those cases, period needs to be increased.
This parameter is effective only for c3xxx, c62x, dh895xcc devices.
4xxx has this value internally fixed to 200ms.
Default value is set to 500. Minimal allowed value is 200.
All values are expressed in milliseconds.
What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_failed
Date: November 2023
KernelVersion: 6.6
Contact: [email protected]
Description: (RO) Read returns the number of times the device became unresponsive.
Attribute returns value of the counter which is incremented when
status query results negative.
What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_sent
Date: November 2023
KernelVersion: 6.6
Contact: [email protected]
Description: (RO) Read returns the number of times the control process checked
if the device is responsive.
Attribute returns value of the counter which is incremented on
every status query.
What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/status
Date: November 2023
KernelVersion: 6.6
Contact: [email protected]
Description: (RO) Read returns the device health status.
Returns 0 when device is healthy or -1 when is unresponsive
or the query failed to send.
The driver does not monitor for Heartbeat. It is left for a user
to poll the status periodically.
What: /sys/kernel/debug/qat_<device>_<BDF>/pm_status
Date: January 2024
KernelVersion: 6.7
Contact: [email protected]
Description: (RO) Read returns power management information specific to the
QAT device.
This attribute is only available for qat_4xxx and qat_6xxx devices.
What: /sys/kernel/debug/qat_<device>_<BDF>/cnv_errors
Date: January 2024
KernelVersion: 6.7
Contact: [email protected]
Description: (RO) Read returns, for each Acceleration Engine (AE), the number
of errors and the type of the last error detected by the device
when performing verified compression.
Reported counters::
<N>: Number of Compress and Verify (CnV) errors and type
of the last CnV error detected by Acceleration
Engine N.
What: /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/inject_error
Date: March 2024
KernelVersion: 6.8
Contact: [email protected]
Description: (WO) Write to inject an error that simulates an heartbeat
failure. This is to be used for testing purposes.
After writing this file, the driver stops arbitration on a
random engine and disables the fetching of heartbeat counters.
If a workload is running on the device, a job submitted to the
accelerator might not get a response and a read of the
`heartbeat/status` attribute might report -1, i.e. device
unresponsive.
The error is unrecoverable thus the device must be restarted to
restore its functionality.
This attribute is available only when the kernel is built with
CONFIG_CRYPTO_DEV_QAT_ERROR_INJECTION=y.
A write of 1 enables error injection.
The following example shows how to enable error injection::
# cd /sys/kernel/debug/qat_<device>_<BDF>
# echo 1 > heartbeat/inject_error
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Firmware request·response counters
1-11| 항목 | 내용 |
|---|---|
| What | /sys/kernel/debug/qat_<device>_<BDF>/fw_counters |
| Date | 2023년 11월 |
| KernelVersion | 6.6 |
| Contact | [email protected] |
| 권한 | RO |
각 Acceleration Engine별로 firmware에 보낸 request 수와 firmware에서 받은 response 수를 반환합니다.
| 표시 | 의미 |
|---|---|
| <N> | Acceleration Engine N이 firmware에 보낸 requests와 firmware에서 받은 responses 수 |
Heartbeat update period
12-30| 항목 | 내용 |
|---|---|
| What | /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/config |
| Date | 2023년 11월 |
| KernelVersion | 6.6 |
| Contact | [email protected] |
| 권한 | RW |
읽으면 Heartbeat update period를 반환하고 쓰면 period를 변경합니다. 이 period는 계획한 device health status polling interval을 반영해야 합니다.
고빈도 Heartbeat monitoring은 CPU cycles를 낭비하지만 system downtime을 줄입니다. 완료하는 데 시간이 걸리는 큰 service request가 있으면 고빈도 monitoring이 unresponsive라는 false report를 만들 수 있으므로 이 경우 period를 늘려야 합니다.
| Device 또는 값 | 동작 |
|---|---|
| c3xxx, c62x, dh895xcc | 이 parameter가 적용됨 |
| 4xxx | 내부적으로 200 ms로 고정됨 |
| 기본값 | 500 ms |
| 최솟값 | 200 ms |
Heartbeat query counters와 health status
32-61| What | 설명 | 권한 |
|---|---|---|
| /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_failed | Device가 unresponsive가 된 횟수입니다. Status query 결과가 negative일 때 증가합니다. | RO |
| /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/queries_sent | Control process가 device responsiveness를 확인한 횟수입니다. 모든 status query마다 증가합니다. | RO |
| /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/status | Device health status입니다. Healthy이면 0, unresponsive이거나 query 전송에 실패하면 -1입니다. | RO |
세 항목은 모두 2023년 11월, kernel 6.6에 추가되었고 담당자는 [email protected]입니다.
Driver는 Heartbeat를 monitor하지 않습니다. 사용자가 status를 주기적으로 poll해야 합니다.
Userspace가 선택한 period로 status를 읽을 때마다 sent counter가 늘고 negative result면 failed counter가 늘어난다. 짧은 period는 탐지 시간을 줄이지만 CPU 비용과 false positive 가능성을 높인다.
Power management와 CnV errors
63-83| What | Date / KernelVersion | 설명 | 권한 |
|---|---|---|---|
| /sys/kernel/debug/qat_<device>_<BDF>/pm_status | 2024년 1월 / 6.7 | QAT device-specific power management 정보를 반환합니다. qat_4xxx와 qat_6xxx에서만 제공합니다. | RO |
| /sys/kernel/debug/qat_<device>_<BDF>/cnv_errors | 2024년 1월 / 6.7 | Verified compression 중 device가 검출한 각 Acceleration Engine별 error 수와 마지막 error type을 반환합니다. | RO |
두 항목의 담당자는 [email protected]입니다. cnv_errors에서 <N>은 Acceleration Engine N이 검출한 Compress and Verify(CnV) error 수와 마지막 CnV error type을 나타냅니다.
Heartbeat failure error injection
85-109| 항목 | 내용 |
|---|---|
| What | /sys/kernel/debug/qat_<device>_<BDF>/heartbeat/inject_error |
| Date | 2024년 3월 |
| KernelVersion | 6.8 |
| Contact | [email protected] |
| 권한 | WO |
Heartbeat failure를 흉내 내는 error를 주입하는 시험용 interface입니다. File에 쓴 뒤 driver는 무작위 engine의 arbitration을 멈추고 heartbeat counters fetch를 disable합니다.
Device에서 workload가 실행 중이면 accelerator에 제출된 job이 response를 받지 못할 수 있고 heartbeat/status가 device unresponsive를 뜻하는 -1을 보고할 수 있습니다.
이 error는 복구할 수 없으므로 기능을 되살리려면 device를 restart해야 합니다. CONFIG_CRYPTO_DEV_QAT_ERROR_INJECTION=y로 kernel을 build한 경우에만 attribute가 보입니다. 1을 쓰면 error injection을 enable합니다.
# cd /sys/kernel/debug/qat_<device>_<BDF>
# echo 1 > heartbeat/inject_error주입 후 random engine의 arbitration과 counter fetch가 중단되어 실제 workload와 health query가 응답하지 않을 수 있다. 정상 복귀 경로는 device restart뿐이다.
Acceleration Engine firmware counters
debugfs-driver-qat:1-11각 Acceleration Engine이 firmware에 보낸 requests와 firmware에서 받은 responses 수를 읽기 전용으로 보고합니다.