요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
Kconfig 조합을 사고 실험한다
submit-checklist.rst:28-39새 CONFIG와 변경한 CONFIG가 menu 구조를 망가뜨리지 않아야 하며 Kconfig language가 정한 예외가 아니면 default off로 둔다. 모든 새 option에는 help text가 필요하다.
Dependency, select, imply, tristate 조합은 test만으로 전부 열거하기 어렵다. =y·m·n 전이와 parent menu visibility를 논리적으로 검토해 불가능하거나 순환하는 configuration을 막는다.
외부에 보이는 변경을 문서화한다
submit-checklist.rst:41-61- Global kernel API는 kernel-doc으로 설명한다.
- 새 /proc entry는 Documentation 아래에 기록한다.
- 새 boot parameter는 admin-guide/kernel-parameters.rst에 추가한다.
- 새 module parameter는 MODULE_PARM_DESC()로 설명한다.
- 새 userspace interface는 Documentation/ABI에 기록하고 [email protected]를 Cc한다.
- 새 ioctl number는 userspace-api/ioctl/ioctl-number.rst에 반영한다.
자동 분석 도구를 실행한다
submit-checklist.rst:63-76- scripts/checkpatch.pl로 trivial style violation을 찾고 남은 항목은 각각 정당화할 수 있어야 한다.
- sparse를 warning 없이 통과시켜 address-space, bitwise type와 annotation 문제를 찾는다.
- make checkstack을 실행하고 function stack 사용량이 512 byte를 넘으면 축소 후보로 검토한다.
Configuration과 architecture를 바꿔 build한다
submit-checklist.rst:78-114- 관련 CONFIG를 =y, =m, =n으로 각각 build하고 compiler·linker warning을 남기지 않는다.
- allnoconfig와 allmodconfig를 통과한다.
- O=builddir out-of-tree build를 확인한다.
- Documentation 변경은 make htmldocs 또는 make pdfdocs로 warning 없이 build한다.
- 32·64비트와 big·little endian architecture를 cross build해 range, alignment와 byte-order 가정을 찾는다.
- 새 code는 make KCFLAGS=-W로 추가 warning을 확인한다.
- SMP, SYSFS, PROC_FS, INPUT, PCI, BLOCK, PM, MAGIC_SYSRQ, NET, INET 같은 관련 option을 여러 조합으로 끄거나 module로 build한다.
Debug option과 failure injection으로 실행 검증한다
submit-checklist.rst:116-137PREEMPT, DEBUG_PREEMPT, SLUB_DEBUG, DEBUG_PAGEALLOC, DEBUG_MUTEXES, DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, PROVE_RCU와 DEBUG_OBJECTS_RCU_HEAD를 함께 켜고 test한다. SMP와 PREEMPT는 켠 경우와 끈 경우 모두 build·runtime test한다.
Lockdep 기능을 모두 켜고 모든 code path를 실행하며 slab·page allocation failure를 injection해 error cleanup을 검증한다. 큰 기능이라면 subsystem 전용 fault injection point를 추가한다. 마지막으로 최신 linux-next에서 다른 queue 변경과 결합해 VM, VFS와 subsystem integration regression이 없는지 확인한다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. _submitchecklist:
3
=======================================
4
Linux Kernel patch submission checklist
5
=======================================
7
Here are some basic things that developers should do if they want to see their
8
kernel patch submissions accepted more quickly.
10
These are all above and beyond the documentation that is provided in
11
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
12
and elsewhere regarding submitting Linux kernel patches.
14
Review your code
15
================
17
1) If you use a facility then #include the file that defines/declares
18
that facility. Don't depend on other header files pulling in ones
19
that you use.
21
2) Check your patch for general style as detailed in
22
:ref:`Documentation/process/coding-style.rst <codingstyle>`.
24
3) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a
25
comment in the source code that explains the logic of what they are doing
26
and why.
28
Review Kconfig changes
29
======================
31
1) Any new or modified ``CONFIG`` options do not muck up the config menu and
32
default to off unless they meet the exception criteria documented in
33
``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value.
35
2) All new ``Kconfig`` options have help text.
37
3) Has been carefully reviewed with respect to relevant ``Kconfig``
38
combinations. This is very hard to get right with testing---brainpower
39
pays off here.
41
Provide documentation
42
=====================
44
1) Include :ref:`kernel-doc <kernel_doc>` to document global kernel APIs.
45
(Not required for static functions, but OK there also.)
47
2) All new ``/proc`` entries are documented under ``Documentation/``
49
3) All new kernel boot parameters are documented in
50
``Documentation/admin-guide/kernel-parameters.rst``.
52
4) All new module parameters are documented with ``MODULE_PARM_DESC()``
54
5) All new userspace interfaces are documented in ``Documentation/ABI/``.
55
See Documentation/admin-guide/abi.rst (or ``Documentation/ABI/README``)
56
for more information.
57
Patches that change userspace interfaces should be CCed to
60
6) If any ioctl's are added by the patch, then also update
61
``Documentation/userspace-api/ioctl/ioctl-number.rst``.
63
Check your code with tools
64
==========================
66
1) Check for trivial violations with the patch style checker prior to
67
submission (``scripts/checkpatch.pl``).
68
You should be able to justify all violations that remain in
69
your patch.
71
2) Check cleanly with sparse.
73
3) Use ``make checkstack`` and fix any problems that it finds.
74
Note that ``checkstack`` does not point out problems explicitly,
75
but any one function that uses more than 512 bytes on the stack is a
76
candidate for change.
78
Build your code
79
===============
81
1) Builds cleanly:
83
a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and
84
``=n``. No ``gcc`` warnings/errors, no linker warnings/errors.
86
b) Passes ``allnoconfig``, ``allmodconfig``
88
c) Builds successfully when using ``O=builddir``
90
d) Any Documentation/ changes build successfully without new warnings/errors.
91
Use ``make htmldocs`` or ``make pdfdocs`` to check the build and
92
fix any issues.
94
2) Builds on multiple CPU architectures by using local cross-compile tools
95
or some other build farm.
96
Note that testing against architectures of different word sizes
97
(32- and 64-bit) and different endianness (big- and little-) is effective
98
in catching various portability issues due to false assumptions on
99
representable quantity range, data alignment, or endianness, among
100
others.
102
3) Newly-added code has been compiled with ``gcc -W`` (use
103
``make KCFLAGS=-W``). This will generate lots of noise, but is good
104
for finding bugs like "warning: comparison between signed and unsigned".
106
4) If your modified source code depends on or uses any of the kernel
107
APIs or features that are related to the following ``Kconfig`` symbols,
108
then test multiple builds with the related ``Kconfig`` symbols disabled
109
and/or ``=m`` (if that option is available) [not all of these at the
110
same time, just various/random combinations of them]:
112
``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``,
113
``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``,
114
``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``).
116
Test your code
117
==============
119
1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``,
120
``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``,
121
``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``,
122
``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all
123
simultaneously enabled.
125
2) Has been build- and runtime tested with and without ``CONFIG_SMP`` and
126
``CONFIG_PREEMPT.``
128
3) All codepaths have been exercised with all lockdep features enabled.
130
4) Has been checked with injection of at least slab and page-allocation
131
failures. See ``Documentation/fault-injection/``.
132
If the new code is substantial, addition of subsystem-specific fault
133
injection might be appropriate.
135
5) Tested with the most recent tag of linux-next to make sure that it still
136
works with all of the other queued patches and various changes in the VM,
137
VFS, and other subsystems.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Patch 제출 전 확인할 항목
1-12Kernel patch가 더 빨리 accept되기를 원하는 developer가 수행해야 할 기본 점검 항목이다. Documentation/process/submitting-patches.rst와 다른 patch 제출 문서의 요구 사항에 더해 이 목록도 확인해야 한다.
Code 검토
14-26- 어떤 기능을 사용한다면 그 기능을 정의하거나 선언하는 header file을 직접 #include한다. 다른 header가 우연히 필요한 header를 포함해 주는 관계에 의존하지 않는다.
- Documentation/process/coding-style.rst의 일반 coding style에 따라 patch를 검사한다.
- barrier(), rmb(), wmb() 같은 모든 memory barrier에는 무엇을 하고 왜 필요한지 logic을 설명하는 source comment를 붙인다.
Kconfig 변경 검토
28-39- 새 CONFIG option과 수정한 CONFIG option이 config menu를 어지럽히지 않는지 확인한다. Documentation/kbuild/kconfig-language.rst의 default value 예외 기준을 충족하지 않으면 기본값은 off여야 한다.
- 모든 새 Kconfig option에 help text를 작성한다.
- 관련 Kconfig 조합을 세심하게 검토한다. 모든 조합을 test만으로 올바르게 확인하기는 매우 어려우므로 설계 단계의 면밀한 사고가 중요하다.
문서 제공
41-61- Global kernel API는 kernel-doc으로 문서화한다. Static function에는 필수가 아니지만 작성해도 된다.
- 새 /proc entry는 Documentation/ 아래에 문서화한다.
- 새 kernel boot parameter는 Documentation/admin-guide/kernel-parameters.rst에 문서화한다.
- 새 module parameter는 MODULE_PARM_DESC()로 설명한다.
- 새 userspace interface는 Documentation/ABI/에 문서화한다. 자세한 내용은 Documentation/admin-guide/abi.rst 또는 Documentation/ABI/README를 참고하고, userspace interface를 바꾸는 patch는 [email protected]를 Cc한다.
- Patch가 ioctl을 추가한다면 Documentation/userspace-api/ioctl/ioctl-number.rst도 갱신한다.
도구를 이용한 검사
63-76- 제출 전에 scripts/checkpatch.pl로 단순한 style 위반을 검사한다. 남아 있는 모든 위반에는 타당한 이유를 제시할 수 있어야 한다.
- Sparse 검사를 오류 없이 통과한다.
- make checkstack을 실행하고 발견된 문제를 고친다. checkstack은 문제라고 직접 판정하지 않지만 stack을 512 byte보다 많이 사용하는 function은 변경 후보로 본다.
Build 검증
78-114- 관련되거나 수정한 CONFIG option을 =y, =m, =n으로 각각 설정해 compiler와 linker warning 또는 error 없이 build한다.
- allnoconfig와 allmodconfig build를 통과한다.
- O=builddir을 사용하는 out-of-tree build에 성공한다.
- Documentation/ 변경은 make htmldocs 또는 make pdfdocs로 새 warning과 error 없이 build한다.
- Local cross compiler 또는 build farm을 사용해 여러 CPU architecture에서 build한다. 32/64-bit word size와 big/little endian을 바꾸면 표현 가능한 값의 범위, data alignment, endian에 대한 잘못된 가정으로 생기는 portability 문제를 찾는 데 효과적이다.
- 새 code를 gcc -W, 즉 make KCFLAGS=-W로 compile한다. 출력이 많지만 signed와 unsigned 비교 같은 bug를 찾는 데 유용하다.
- 수정한 source가 관련 API나 기능에 의존한다면 CONFIG_SMP, CONFIG_SYSFS, CONFIG_PROC_FS, CONFIG_INPUT, CONFIG_PCI, CONFIG_BLOCK, CONFIG_PM, CONFIG_MAGIC_SYSRQ, CONFIG_NET, CONFIG_INET 조합을 일부 disable하거나 가능한 경우 =m으로 바꾸어 여러 build를 시험한다. 모든 option을 한 번에 바꾸기보다 다양한 조합을 사용한다.
Runtime test
116-137- CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, CONFIG_SLUB_DEBUG, CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, CONFIG_DEBUG_SPINLOCK, CONFIG_DEBUG_ATOMIC_SLEEP, CONFIG_PROVE_RCU, CONFIG_DEBUG_OBJECTS_RCU_HEAD를 동시에 enable한 상태로 시험한다.
- CONFIG_SMP와 CONFIG_PREEMPT를 각각 켠 경우와 끈 경우 모두 build와 runtime test를 수행한다.
- 모든 lockdep 기능을 enable하고 모든 code path를 실행한다.
- 최소한 slab allocation failure와 page allocation failure를 injection해 검사한다. Documentation/fault-injection/을 참고하며 새 code의 규모가 크다면 subsystem 전용 fault injection 추가도 고려한다.
- 가장 최근 linux-next tag에서 시험해 queue에 대기 중인 다른 patch와 VM, VFS, 그 밖의 subsystem 변경을 함께 적용해도 동작하는지 확인한다.
Code 자체를 다시 검토한다
submit-checklist.rst:4-26