요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
How to Get Your Patch Accepted Into the Hwmon Subsystem
2
=======================================================
4
This text is a collection of suggestions for people writing patches or
5
drivers for the hwmon subsystem. Following these suggestions will greatly
6
increase the chances of your change being accepted.
9
1. General
10
----------
12
* It should be unnecessary to mention, but please read and follow:
14
- Documentation/process/submit-checklist.rst
15
- Documentation/process/submitting-patches.rst
16
- Documentation/process/coding-style.rst
18
* Please run your patch through 'checkpatch --strict'. There should be no
19
errors, no warnings, and few if any check messages. If there are any
20
messages, please be prepared to explain.
22
* Please use the standard multi-line comment style. Do not mix C and C++
23
style comments in a single driver (with the exception of the SPDX license
24
identifier).
26
* If your patch generates checkpatch errors, warnings, or check messages,
27
please refrain from explanations such as "I prefer that coding style".
28
Keep in mind that each unnecessary message helps hiding a real problem,
29
and a consistent coding style makes it easier for others to understand
30
and review the code.
32
* Please test your patch thoroughly. We are not your test group.
33
Sometimes a patch can not or not completely be tested because of missing
34
hardware. In such cases, you should test-build the code on at least one
35
architecture. If run-time testing was not achieved, it should be written
36
explicitly below the patch header.
38
* If your patch (or the driver) is affected by configuration options such as
39
CONFIG_SMP, make sure it compiles for all configuration variants.
42
2. Adding functionality to existing drivers
43
-------------------------------------------
45
* Make sure the documentation in Documentation/hwmon/<driver_name>.rst is up to
46
date.
48
* Make sure the information in Kconfig is up to date.
50
* If the added functionality requires some cleanup or structural changes, split
51
your patch into a cleanup part and the actual addition. This makes it easier
52
to review your changes, and to bisect any resulting problems.
54
* Never mix bug fixes, cleanup, and functional enhancements in a single patch.
57
3. New drivers
58
--------------
60
* Running your patch or driver file(s) through checkpatch does not mean its
61
formatting is clean. If unsure about formatting in your new driver, run it
62
through Lindent. Lindent is not perfect, and you may have to do some minor
63
cleanup, but it is a good start.
65
* Consider adding yourself to MAINTAINERS.
67
* Document the driver in Documentation/hwmon/<driver_name>.rst.
69
* Add the driver to Kconfig and Makefile in alphabetical order.
71
* Make sure that all dependencies are listed in Kconfig.
73
* Please list include files in alphabetic order.
75
* Please align continuation lines with '(' on the previous line.
77
* Avoid forward declarations if you can. Rearrange the code if necessary.
79
* Avoid macros to generate groups of sensor attributes. It not only confuses
80
checkpatch, but also makes it more difficult to review the code.
82
* Avoid calculations in macros and macro-generated functions. While such macros
83
may save a line or so in the source, it obfuscates the code and makes code
84
review more difficult. It may also result in code which is more complicated
85
than necessary. Use inline functions or just regular functions instead.
87
* Limit the number of kernel log messages. In general, your driver should not
88
generate an error message just because a runtime operation failed. Report
89
errors to user space instead, using an appropriate error code. Keep in mind
90
that kernel error log messages not only fill up the kernel log, but also are
91
printed synchronously, most likely with interrupt disabled, often to a serial
92
console. Excessive logging can seriously affect system performance.
94
* Use devres functions whenever possible to allocate resources. For rationale
95
and supported functions, please see Documentation/driver-api/driver-model/devres.rst.
96
If a function is not supported by devres, consider using devm_add_action().
98
* If the driver has a detect function, make sure it is silent. Debug messages
99
and messages printed after a successful detection are acceptable, but it
100
must not print messages such as "Chip XXX not found/supported".
102
Keep in mind that the detect function will run for all drivers supporting an
103
address if a chip is detected on that address. Unnecessary messages will just
104
pollute the kernel log and not provide any value.
106
* Provide a detect function if and only if a chip can be detected reliably.
108
* Only the following I2C addresses shall be probed: 0x18-0x1f, 0x28-0x2f,
109
0x48-0x4f, 0x58, 0x5c, 0x73 and 0x77. Probing other addresses is strongly
110
discouraged as it is known to cause trouble with other (non-hwmon) I2C
111
chips. If your chip lives at an address which can't be probed then the
112
device will have to be instantiated explicitly (which is always better
113
anyway.)
115
* Avoid writing to chip registers in the detect function. If you have to write,
116
only do it after you have already gathered enough data to be certain that the
117
detection is going to be successful.
119
Keep in mind that the chip might not be what your driver believes it is, and
120
writing to it might cause a bad misconfiguration.
122
* Make sure there are no race conditions in the probe function. Specifically,
123
completely initialize your chip and your driver first, then register with
124
the hwmon subsystem.
126
* Use devm_hwmon_device_register_with_info() or, if your driver needs a remove
127
function, hwmon_device_register_with_info() to register your driver with the
128
hwmon subsystem. Try using devm_add_action() instead of a remove function if
129
possible. Do not use any of the deprecated registration functions.
131
* Your driver should be buildable as module. If not, please be prepared to
132
explain why it has to be built into the kernel.
134
* Do not provide support for deprecated sysfs attributes.
136
* Do not create non-standard attributes unless really needed. If you have to use
137
non-standard attributes, or you believe you do, discuss it on the mailing list
138
first. Either case, provide a detailed explanation why you need the
139
non-standard attribute(s).
140
Standard attributes are specified in Documentation/hwmon/sysfs-interface.rst.
142
* When deciding which sysfs attributes to support, look at the chip's
143
capabilities. While we do not expect your driver to support everything the
144
chip may offer, it should at least support all limits and alarms.
146
* Last but not least, please check if a driver for your chip already exists
147
before starting to write a new driver. Especially for temperature sensors,
148
new chips are often variants of previously released chips. In some cases,
149
a presumably new chip may simply have been relabeled.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
일반 제출·스타일·시험 요건
1-41이 문서는 hwmon 하위 시스템용 패치나 드라이버 작성자가 변경 수락 가능성을 높이기 위해 따라야 할 제안 모음입니다.
먼저 `Documentation/process/submit-checklist.rst`, `Documentation/process/submitting-patches.rst`, `Documentation/process/coding-style.rst`를 읽고 따라야 합니다.
패치는 `checkpatch --strict`를 통과해야 하며 오류와 경고가 없어야 하고 check 메시지도 가능한 한 적어야 합니다. 메시지가 남으면 설명할 준비를 해야 합니다. 표준 여러 줄 주석 스타일을 사용하고 SPDX 식별자를 제외하면 한 드라이버에서 C와 C++ 주석을 섞지 않습니다.
checkpatch 지적에 대해 단순히 개인 스타일 선호를 이유로 들지 않습니다. 불필요한 메시지는 실제 문제를 가리고 일관된 스타일은 이해와 검토를 돕습니다.
패치는 충분히 시험해야 합니다. 하드웨어가 없어 런타임 시험이 불가능하면 최소 한 아키텍처에서 빌드 시험을 하고, 런타임 시험을 하지 못했다는 사실을 패치 헤더 아래에 명시합니다. `CONFIG_SMP` 같은 설정 옵션의 영향을 받으면 모든 설정 변형에서 빌드되는지 확인합니다.
항목요건
필독 문서submit-checklist, submitting-patches, coding-style
정적 검사checkpatch --strict, 오류·경고 0, check 최소
주석표준 여러 줄 스타일, C/C++ 혼용 금지
기능 시험충분한 런타임 시험
하드웨어 없음최소 한 아키텍처 빌드, 미시험 사실 명시
설정 변형CONFIG_SMP 등 모든 조합에서 컴파일
제출 전 필수 문서·도구·시험 범위를 정리합니다.
프로세스·스타일 문서 읽기→checkpatch --strict 실행→주석·스타일 문제 정리→런타임 또는 최소 빌드 시험→시험 범위와 미시험 사항 기록
문서 확인부터 시험 결과 기록까지 순서대로 마칩니다.
How to Get Your Patch Accepted Into the Hwmon Subsystem
=======================================================
This text is a collection of suggestions for people writing patches or
drivers for the hwmon subsystem. Following these suggestions will greatly
increase the chances of your change being accepted.
1. General
----------
* It should be unnecessary to mention, but please read and follow:
- Documentation/process/submit-checklist.rst
- Documentation/process/submitting-patches.rst
- Documentation/process/coding-style.rst
* Please run your patch through 'checkpatch --strict'. There should be no
errors, no warnings, and few if any check messages. If there are any
messages, please be prepared to explain.
* Please use the standard multi-line comment style. Do not mix C and C++
style comments in a single driver (with the exception of the SPDX license
identifier).
* If your patch generates checkpatch errors, warnings, or check messages,
please refrain from explanations such as "I prefer that coding style".
Keep in mind that each unnecessary message helps hiding a real problem,
and a consistent coding style makes it easier for others to understand
and review the code.
* Please test your patch thoroughly. We are not your test group.
Sometimes a patch can not or not completely be tested because of missing
hardware. In such cases, you should test-build the code on at least one
architecture. If run-time testing was not achieved, it should be written
explicitly below the patch header.
* If your patch (or the driver) is affected by configuration options such as
CONFIG_SMP, make sure it compiles for all configuration variants.
기존 드라이버 기능 추가
42-56기존 드라이버에 기능을 추가하면 `Documentation/hwmon/<driver_name>.rst` 문서와 Kconfig 정보를 최신 상태로 갱신해야 합니다.
추가 기능에 정리나 구조 변경이 필요하면 정리 패치와 실제 기능 추가 패치를 분리합니다. 그러면 검토가 쉬워지고 문제가 생겼을 때 이분 탐색하기도 쉽습니다.
버그 수정, 코드 정리, 기능 향상을 한 패치에 섞어서는 안 됩니다.
항목요건
hwmon 문서Documentation/hwmon/<driver_name>.rst 갱신
Kconfig정보 최신화
구조 정리기능 추가와 별도 패치
버그 수정정리·기능 향상과 혼합 금지
문서 갱신과 패치 목적별 분리 원칙입니다.
필요한 정리 범위 확인→정리 패치 작성→기능 추가 패치 작성→문서·Kconfig 갱신→패치별 독립 시험·검토
정리와 동작 변경을 독립 단계로 구성합니다.
2. Adding functionality to existing drivers
-------------------------------------------
* Make sure the documentation in Documentation/hwmon/<driver_name>.rst is up to
date.
* Make sure the information in Kconfig is up to date.
* If the added functionality requires some cleanup or structural changes, split
your patch into a cleanup part and the actual addition. This makes it easier
to review your changes, and to bisect any resulting problems.
* Never mix bug fixes, cleanup, and functional enhancements in a single patch.
새 드라이버 구조·자원·로그·탐지
57-105checkpatch 통과만으로 새 드라이버의 서식이 깨끗하다고 볼 수 없습니다. 불확실하면 Lindent를 실행하고 필요한 소규모 정리를 합니다. 자신을 MAINTAINERS에 추가하는 것도 고려합니다.
드라이버 문서는 `Documentation/hwmon/<driver_name>.rst`에 작성하고 Kconfig와 Makefile에는 알파벳순으로 추가합니다. 모든 의존성을 Kconfig에 나열하고 include 파일도 알파벳순으로 정렬합니다.
이어지는 줄은 앞줄의 `(`에 맞춰 정렬합니다. 가능한 한 전방 선언을 피하고 코드를 재배치합니다. 센서 속성 그룹을 만드는 매크로는 checkpatch와 검토를 어렵게 하므로 피합니다. 매크로나 매크로 생성 함수에서 계산하지 말고 인라인 함수나 일반 함수를 사용합니다.
커널 로그 메시지 수를 제한합니다. 런타임 작업 실패만으로 오류 로그를 남기기보다 적절한 오류 코드로 사용자 공간에 보고합니다. 커널 오류 출력은 로그를 채우고 인터럽트가 비활성화된 상태에서 직렬 콘솔에 동기 출력될 수 있어 과도하면 성능에 심각한 영향을 줍니다.
자원 할당에는 가능하면 devres 함수를 사용합니다. 지원되지 않는 함수는 `devm_add_action()` 사용을 고려합니다.
detect 함수가 있다면 조용해야 합니다. 디버그 메시지와 성공 탐지 뒤 메시지는 허용되지만 `Chip XXX not found/supported` 같은 실패 메시지는 출력하지 않습니다. 같은 주소를 지원하는 모든 드라이버의 detect가 실행될 수 있어 불필요한 로그는 가치 없이 커널 로그만 오염시킵니다.
영역권장·금지
서식checkpatch 후 필요하면 Lindent와 수동 정리
유지관리MAINTAINERS 추가 고려
등록 파일문서·Kconfig·Makefile, 알파벳순
의존성·includeKconfig에 모두 기재, include 알파벳순
코드 구조전방 선언 회피, 연속 줄 '(' 정렬
센서 속성그룹 생성 매크로 회피
계산매크로 대신 inline·일반 함수
로그런타임 오류는 오류 코드로 사용자 공간 보고
자원devres, 필요하면 devm_add_action
detect 로그실패 메시지 없이 조용하게
서식·구조·자원·로그·탐지 원칙을 묶습니다.
Lindent·checkpatch로 서식 정리→문서·Kconfig·Makefile·MAINTAINERS 갱신→매크로·전방 선언·정렬 검토→devres 자원 관리 적용→detect와 런타임 로그 최소화
자동 검사 뒤 사람이 읽기 쉬운 구조와 조용한 탐지를 확인합니다.
3. New drivers
--------------
* Running your patch or driver file(s) through checkpatch does not mean its
formatting is clean. If unsure about formatting in your new driver, run it
through Lindent. Lindent is not perfect, and you may have to do some minor
cleanup, but it is a good start.
* Consider adding yourself to MAINTAINERS.
* Document the driver in Documentation/hwmon/<driver_name>.rst.
* Add the driver to Kconfig and Makefile in alphabetical order.
* Make sure that all dependencies are listed in Kconfig.
* Please list include files in alphabetic order.
* Please align continuation lines with '(' on the previous line.
* Avoid forward declarations if you can. Rearrange the code if necessary.
* Avoid macros to generate groups of sensor attributes. It not only confuses
checkpatch, but also makes it more difficult to review the code.
* Avoid calculations in macros and macro-generated functions. While such macros
may save a line or so in the source, it obfuscates the code and makes code
review more difficult. It may also result in code which is more complicated
than necessary. Use inline functions or just regular functions instead.
* Limit the number of kernel log messages. In general, your driver should not
generate an error message just because a runtime operation failed. Report
errors to user space instead, using an appropriate error code. Keep in mind
that kernel error log messages not only fill up the kernel log, but also are
printed synchronously, most likely with interrupt disabled, often to a serial
console. Excessive logging can seriously affect system performance.
* Use devres functions whenever possible to allocate resources. For rationale
and supported functions, please see Documentation/driver-api/driver-model/devres.rst.
If a function is not supported by devres, consider using devm_add_action().
* If the driver has a detect function, make sure it is silent. Debug messages
and messages printed after a successful detection are acceptable, but it
must not print messages such as "Chip XXX not found/supported".
Keep in mind that the detect function will run for all drivers supporting an
address if a chip is detected on that address. Unnecessary messages will just
pollute the kernel log and not provide any value.
안전한 탐지·등록·sysfs 지원
106-149칩을 신뢰성 있게 식별할 수 있을 때만 detect 함수를 제공합니다.
검색이 허용되는 I2C 주소는 `0x18-0x1f`, `0x28-0x2f`, `0x48-0x4f`, `0x58`, `0x5c`, `0x73`, `0x77`뿐입니다. 다른 주소 검색은 비-hwmon 칩에 문제를 일으킬 수 있으므로 강하게 권장하지 않습니다. 검색 불가 주소의 장치는 명시적으로 생성해야 하며 이것이 항상 더 낫습니다.
detect 함수에서 칩 레지스터 쓰기를 피합니다. 꼭 써야 한다면 탐지가 성공할 것이 확실할 만큼 데이터를 모은 뒤에만 씁니다. 다른 칩을 잘못 식별한 상태에서 쓰면 심각한 오구성이 생길 수 있습니다.
probe에는 경쟁 조건이 없어야 합니다. 칩과 드라이버를 완전히 초기화한 뒤 hwmon 하위 시스템에 등록합니다.
등록에는 `devm_hwmon_device_register_with_info()`를 사용하고, remove 함수가 필요하면 `hwmon_device_register_with_info()`를 사용합니다. 가능하면 remove 대신 `devm_add_action()`을 시도하며 폐기된 등록 함수는 쓰지 않습니다.
드라이버는 모듈로 빌드 가능해야 하며 불가능하면 내장해야 하는 이유를 설명해야 합니다. 폐기된 sysfs 속성을 지원하지 않습니다.
정말 필요하지 않으면 비표준 속성을 만들지 않습니다. 필요하다고 판단하면 먼저 메일링 리스트에서 논의하고 상세한 이유를 제시합니다. 표준 속성은 `Documentation/hwmon/sysfs-interface.rst`에 정의되어 있습니다.
지원할 sysfs 속성은 칩 기능을 기준으로 결정합니다. 모든 기능을 지원할 필요는 없지만 최소한 모든 한계와 경보는 지원해야 합니다.
새 드라이버 작성 전에 해당 칩용 드라이버가 이미 있는지 확인합니다. 특히 온도 센서는 새 칩이 기존 제품의 변형이거나 단순 재라벨 제품일 수 있습니다.
항목요건
detect 제공신뢰성 있는 식별 가능할 때만
허용 I2C 검색0x18-1f, 0x28-2f, 0x48-4f, 0x58, 0x5c, 0x73, 0x77
detect 쓰기회피, 불가피하면 성공 확신 후
probe 순서완전 초기화 후 hwmon 등록
등록 APIdevm_hwmon_device_register_with_info
remove 필요hwmon_device_register_with_info 또는 devm_add_action 고려
빌드모듈 빌드 가능
sysfs폐기 속성 금지, 비표준은 사전 논의
기능 범위최소 모든 limits와 alarms
중복 확인기존·호환·재라벨 드라이버 검색
탐지 주소, 레지스터 쓰기, 등록, sysfs 요구를 요약합니다.
기존 드라이버·호환 변형 확인→신뢰 가능한 detect와 허용 주소만 사용→레지스터 쓰기 없이 식별→완전 초기화 후 표준 API로 등록→limits·alarms와 표준 sysfs 제공
오탐지와 경쟁 조건을 막은 뒤 표준 API와 속성으로 등록합니다.
* Provide a detect function if and only if a chip can be detected reliably.
* Only the following I2C addresses shall be probed: 0x18-0x1f, 0x28-0x2f,
0x48-0x4f, 0x58, 0x5c, 0x73 and 0x77. Probing other addresses is strongly
discouraged as it is known to cause trouble with other (non-hwmon) I2C
chips. If your chip lives at an address which can't be probed then the
device will have to be instantiated explicitly (which is always better
anyway.)
* Avoid writing to chip registers in the detect function. If you have to write,
only do it after you have already gathered enough data to be certain that the
detection is going to be successful.
Keep in mind that the chip might not be what your driver believes it is, and
writing to it might cause a bad misconfiguration.
* Make sure there are no race conditions in the probe function. Specifically,
completely initialize your chip and your driver first, then register with
the hwmon subsystem.
* Use devm_hwmon_device_register_with_info() or, if your driver needs a remove
function, hwmon_device_register_with_info() to register your driver with the
hwmon subsystem. Try using devm_add_action() instead of a remove function if
possible. Do not use any of the deprecated registration functions.
* Your driver should be buildable as module. If not, please be prepared to
explain why it has to be built into the kernel.
* Do not provide support for deprecated sysfs attributes.
* Do not create non-standard attributes unless really needed. If you have to use
non-standard attributes, or you believe you do, discuss it on the mailing list
first. Either case, provide a detailed explanation why you need the
non-standard attribute(s).
Standard attributes are specified in Documentation/hwmon/sysfs-interface.rst.
* When deciding which sysfs attributes to support, look at the chip's
capabilities. While we do not expect your driver to support everything the
chip may offer, it should at least support all limits and alarms.
* Last but not least, please check if a driver for your chip already exists
before starting to write a new driver. Especially for temperature sensors,
new chips are often variants of previously released chips. In some cases,
a presumably new chip may simply have been relabeled.
요약·해설
submitting-patches.rst:1-149엄격한 정적 검사와 시험, 목적별 패치 분리, 안전한 I2C 탐지, 표준 등록 API와 limits·alarms 지원을 요구합니다.
원문 분량과 핵심 구성을 정리합니다.
장치 식별부터 측정·검증까지의 핵심 순서입니다.