Checkpatch

Checkpatch 소개

SPDX 라이선스 식별자: GPL-2.0-only

Checkpatch

Checkpatch(`scripts/checkpatch.pl`)는 patch의 사소한 style 위반을 검사하고 선택적으로 고치는 Perl script입니다. file context에서도 실행할 수 있고 kernel tree 없이도 사용할 수 있습니다.

Checkpatch가 항상 옳은 것은 아닙니다. checkpatch message보다 개발자의 판단이 우선합니다. 위반을 그대로 두었을 때 code가 더 나아 보인다면 그대로 두는 편이 좋을 수 있습니다.

option: 기본 실행과 입력 형식

Option

이 절에서는 checkpatch를 실행할 때 사용할 수 있는 option을 설명합니다.

사용법:

./scripts/checkpatch.pl [OPTION]... [FILE]...

사용 가능한 option은 다음과 같습니다.

`-q`, `--quiet`: quiet mode를 활성화합니다.

`-v`, `--verbose`: verbose mode를 활성화합니다. 특정 message가 표시되는 이유를 알 수 있도록 추가 test 설명을 출력합니다.

`--no-tree`: kernel tree 없이 checkpatch를 실행합니다.

`--no-signoff`: `Signed-off-by` line 검사를 비활성화합니다. sign-off는 patch 설명 끝에 넣는 간단한 line으로, 작성자가 직접 썼거나 open-source patch로 전달할 권리가 있음을 인증합니다.

예:

Signed-off-by: Random J Developer <random@developer.example.org>

이 flag를 설정하면 patch context에서 signed-off-by line이 없다는 message가 나오지 않습니다.

`--patch`: `FILE`을 patch로 취급합니다. 기본 option이므로 명시할 필요가 없습니다.

`--emacs`: 출력을 Emacs compile window format으로 설정합니다. Emacs 사용자는 compile window의 error에서 patch의 문제 line으로 바로 이동할 수 있습니다.

option: 출력과 message type 필터

`--terse`: report마다 한 line만 출력합니다.

`--showfile`: 입력 file 위치 대신 diff 대상 file의 위치를 표시합니다.

`-g`, `--git`: `FILE`을 단일 commit 또는 Git revision range로 취급합니다.

단일 commit 형식:

• `<rev>`
• `<rev>^`
• `<rev>~n`

여러 commit 형식:

• `<rev1>..<rev2>`
• `<rev1>...<rev2>`
• `<rev>-<count>`

`-f`, `--file`: `FILE`을 일반 source file로 취급합니다. kernel source file에 checkpatch를 실행할 때 반드시 사용해야 합니다.

`--subjective`, `--strict`: 더 엄격한 checkpatch test를 활성화합니다. 기본적으로 CHECK로 출력되는 test는 활성화되지 않으며 이 flag로 켭니다.

`--list-types`: checkpatch가 출력하는 모든 message에는 연관된 TYPE이 있습니다. 이 flag는 모든 type을 표시합니다. 활성화하면 입력 `FILE`을 읽지 않고 message도 출력하지 않으며 type 목록만 출력합니다.

`--types TYPE(,TYPE2...)`: 지정한 type의 message만 표시합니다.

예:

./scripts/checkpatch.pl mypatch.patch --types EMAIL_SUBJECT,BRACES

`--ignore TYPE(,TYPE2...)`: 지정한 type에 대해서는 checkpatch message를 출력하지 않습니다.

예:

./scripts/checkpatch.pl mypatch.patch --ignore EMAIL_SUBJECT,BRACES

`--show-types`: 기본적으로 checkpatch는 message에 연결된 type을 표시하지 않습니다. 이 flag를 설정하면 출력에 message type을 표시합니다.

option: 제한, 경로, 요약과 debug

`--max-line-length=n`: 최대 line 길이를 설정합니다. 기본값은 100이며 지정 길이를 넘으면 LONG_LINE message를 출력합니다.

message level은 patch context와 file context에서 다릅니다. patch에는 WARNING을 출력하지만 file에는 더 약한 CHECK를 출력합니다. 따라서 file context에서는 `--strict`도 활성화해야 합니다.

`--min-conf-desc-length=n`: Kconfig entry의 최소 description 길이를 설정하고 더 짧으면 경고합니다.

`--tab-size=n`: tab을 구성하는 space 수를 설정합니다. 기본값은 8입니다.

`--root=PATH`: kernel tree root의 `PATH`를 지정합니다.

kernel root 밖에서 checkpatch를 호출할 때는 이 option을 반드시 지정해야 합니다.

`--no-summary`: file별 summary를 표시하지 않습니다.

`--mailback`: Warning 또는 Error가 있을 때만 report를 생성하고 더 약한 Check는 제외합니다.

`--summary-file`: summary에 filename을 포함합니다.

`--debug KEY=[0|1]`: `KEY`의 debugging을 켜거나 끕니다. `KEY`는 `values`, `possible`, `type`, `attr` 중 하나이며 기본적으로 모두 꺼져 있습니다.

option: 자동 수정과 보조 검사

`--fix`: 실험적 기능입니다. 고칠 수 있는 error가 있으면 자동 수정된 `<inputfile>.EXPERIMENTAL-checkpatch-fixes` file을 만듭니다.

`--fix-inplace`: `--fix`와 비슷한 실험적 기능이지만 입력 file을 수정 내용으로 덮어씁니다. 확실히 이해하고 backup을 마련한 경우가 아니면 사용하지 마십시오.

`--ignore-perl-version`: Perl version 검사를 무시합니다. 최소 version을 충족하지 못하면 이 flag를 켠 뒤 runtime error가 발생할 수 있습니다.

`--codespell`: spelling error 검사에 codespell dictionary를 사용합니다.

`--codespellfile`: 지정한 codespell file을 사용합니다.

기본값은 `/usr/share/codespell/dictionary.txt`입니다.

`--typedefsfile`: 이 file에서 추가 type을 읽습니다.

`--color[=WHEN]`: color를 `always`, `never`, terminal 출력일 때만 사용하는 `auto` 중 하나로 설정합니다. 기본값은 `auto`입니다.

`--kconfig-prefix=WORD`: Kconfig symbol의 prefix로 `WORD`를 사용합니다. 기본값은 `CONFIG_`입니다.

`-h`, `--help`, `--version`: help text를 표시합니다.

message level과 allocation style type

Message Level

checkpatch message는 error의 심각도를 나타내는 세 level로 나뉩니다.

• ERROR: 가장 엄격한 level입니다. 잘못되었을 가능성이 매우 높은 항목을 뜻하므로 반드시 심각하게 다뤄야 합니다.
• WARNING: 다음으로 엄격한 level입니다. ERROR보다는 약하지만 더 세심한 review가 필요합니다.
• CHECK: 가장 약한 level이며 검토와 판단이 필요할 수 있는 항목입니다.

Type 설명

이 절은 checkpatch의 모든 message type을 설명합니다. 이 절의 type은 checkpatch 자체에서도 parsing하며 용도에 따라 subsection으로 묶습니다.

Allocation style

`ALLOC_ARRAY_ARGS`: `kcalloc` 또는 `kmalloc_array`의 첫 번째 인자는 element 수여야 합니다. 첫 번째 인자에 `sizeof()`를 쓰는 것은 일반적으로 잘못입니다.

참조: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html

`ALLOC_SIZEOF_STRUCT`: allocation style이 잘못되었습니다. 일반적으로 `sizeof()`로 memory 크기를 구하는 allocation 함수 계열에서 다음 형태는

p = alloc(sizeof(struct foo), ...)

다음과 같이 작성해야 합니다.

p = alloc(sizeof(*p), ...)

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#allocating-memory

`ALLOC_WITH_MULTIPLY`: `sizeof` 곱셈을 사용하는 `kmalloc`/`kzalloc`보다 `kmalloc_array`/`kcalloc`을 사용하십시오.

참조: https://www.kernel.org/doc/html/latest/core-api/memory-allocation.html

API usage message type

API usage

`ARCH_DEFINES`: 가능하면 architecture-specific define을 사용하지 않아야 합니다.

`ARCH_INCLUDE_LINUX`: `asm/file.h`를 include하고 `linux/file.h`가 존재하며 후자가 전자를 include한다면 `linux/file.h`로 바꿀 수 있습니다. 하지만 항상 가능한 것은 아니며 `signal.h`가 예외입니다. 이 type은 `arch/` 아래의 include에 대해서만 출력합니다.

`AVOID_BUG`: `BUG()`와 `BUG_ON()`은 사용하지 않아야 합니다. 대신 `WARN()`과 `WARN_ON()`을 사용하고 "불가능한" error condition을 가능한 한 정상적으로 처리하십시오.

참조: https://www.kernel.org/doc/html/latest/process/deprecated.html#bug-and-bug-on

`CONSIDER_KSTRTO`: `simple_strtol()`, `simple_strtoll()`, `simple_strtoul()`, `simple_strtoull()`은 overflow를 명시적으로 무시해 caller에서 예상하지 못한 결과를 만들 수 있습니다. 각각 `kstrtol()`, `kstrtoll()`, `kstrtoul()`, `kstrtoull()`로 바꾸는 것이 대체로 올바릅니다.

참조: https://www.kernel.org/doc/html/latest/process/deprecated.html#simple-strtol-simple-strtoll-simple-strtoul-simple-strtoull

`CONSTANT_CONVERSION`: 다음 함수에서 `__constant_<foo>` 형태를 사용하는 것을 권장하지 않습니다.

__constant_cpu_to_be[x]
__constant_cpu_to_le[x]
__constant_be[x]_to_cpu
__constant_le[x]_to_cpu
__constant_htons
__constant_ntohs

constant 인자에 대해서는 `__constant_`가 없는 함수도 동일하므로 `include/uapi/` 밖에서 이 형태를 사용하지 않는 편이 좋습니다.

big-endian system에서는 `__constant_cpu_to_be32(x)`와 `cpu_to_be32(x)` 같은 macro가 같은 expression으로 확장됩니다.

#define __constant_cpu_to_be32(x) ((__force __be32)(__u32)(x))
#define __cpu_to_be32(x)          ((__force __be32)(__u32)(x))

little-endian system에서는 두 macro가 각각 `__constant_swab32`와 `__swab32`로 확장됩니다. `__swab32`에는 `__builtin_constant_p` 검사가 있습니다.

#define __swab32(x)                                \
  (__builtin_constant_p((__u32)(x)) ?        \
  ___constant_swab32(x) :                        \
  __fswab32(x))

결국 constant에 대한 special case가 존재하며 목록의 다른 macro도 같습니다. 따라서 `__constant_...` 형태는 불필요하게 장황하고 `include/uapi` 밖에서는 권장하지 않습니다.

참조: https://lore.kernel.org/lkml/1400106425.12666.6.camel@joe-AO725/

`DEPRECATED_API`: deprecated RCU API 사용을 탐지합니다. 이전 flavour-specific RCU API를 새 vanilla-RCU 대응 API로 교체하는 것이 좋습니다.

사용 가능한 RCU API 전체 목록은 kernel 문서에서 볼 수 있습니다.

참조: https://www.kernel.org/doc/html/latest/RCU/whatisRCU.html#full-list-of-rcu-apis

`DEVICE_ATTR_FUNCTIONS`: `DEVICE_ATTR`에 사용한 함수 이름이 일반적이지 않습니다. 보통 store와 show 함수는 device의 attribute 변수 이름인 `<attr>`을 사용해 `<attr>_store`, `<attr>_show`로 작성합니다.

다음 예를 참고하십시오.

static DEVICE_ATTR(type, 0444, type_show, NULL);
static DEVICE_ATTR(power, 0644, power_show, power_store);

함수 이름은 가급적 위 pattern을 따라야 합니다.

참조: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes

`DEVICE_ATTR_RO`: `DEVICE_ATTR(name, 0444, name_show, NULL)` 대신 `DEVICE_ATTR_RO(name)` helper macro를 사용할 수 있습니다. macro가 show method에 쓸 `_show`를 device attribute 변수 이름에 자동으로 붙입니다.

참조: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes

`DEVICE_ATTR_RW`: `DEVICE_ATTR(name, 0644, name_show, name_store)` 대신 `DEVICE_ATTR_RW(name)` helper macro를 사용할 수 있습니다. macro가 show 및 store method에 쓸 `_show`와 `_store`를 자동으로 붙입니다.

참조: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes

`DEVICE_ATTR_WO`: `DEVICE_ATTR(name, 0200, NULL, name_store)` 대신 source에 표시된 `DEVICE_AATR_WO(name)` helper macro를 사용할 수 있습니다. macro가 store method에 쓸 `_store`를 자동으로 붙입니다.

참조: https://www.kernel.org/doc/html/latest/driver-api/driver-model/device.html#attributes

`DUPLICATED_SYSCTL_CONST`: commit `d91bff3011cf`("proc/sysctl: add shared variables for range check")는 각 source file의 local copy 대신 사용할 shared const 변수를 추가했습니다. sysctl range 검사 값을 `include/linux/sysctl.h`의 shared 값으로 바꾸는 방안을 고려하십시오.

&zero     ->  SYSCTL_ZERO
&one      ->  SYSCTL_ONE
&int_max  ->  SYSCTL_INT_MAX

참조:

1. https://lore.kernel.org/lkml/20190430180111.10688-1-mcroce@redhat.com/

2. https://lore.kernel.org/lkml/20190531131422.14970-1-mcroce@redhat.com/

`ENOSYS`: `ENOSYS`는 존재하지 않는 system call을 호출했다는 뜻입니다. 과거에는 유효한 syscall에 대한 잘못된 연산 같은 경우에도 잘못 사용했으나 새 code에서는 피해야 합니다.

참조: https://lore.kernel.org/lkml/5eb299021dec23c1a48fa7d9f2c8b794e967766d.1408730669.git.luto@amacapital.net/

`ENOTSUPP`: `ENOTSUPP`는 표준 error code가 아니므로 새 patch에서 사용하지 말고 `EOPNOTSUPP`를 사용해야 합니다.

참조: https://lore.kernel.org/netdev/20200510182252.GA411829@lunn.ch/

`EXPORT_SYMBOL`: `EXPORT_SYMBOL`은 export할 symbol 바로 뒤에 와야 합니다.

`IN_ATOMIC`: `in_atomic()`은 driver용이 아니므로 driver에서 사용하면 ERROR로 보고합니다. sleeping 허용 여부를 판단하는 데 자주 쓰이지만 이 방식에서는 신뢰할 수 없으므로 사용을 강하게 권장하지 않습니다. core kernel에서는 사용할 수 있습니다.

참조: https://lore.kernel.org/lkml/20080320201723.b87b3732.akpm@linux-foundation.org/

`LOCKDEP`: `lockdep_no_validate` class는 `device->sem`을 `device->mutex`로 바꾸는 동안 warning을 막기 위한 임시 조치로 추가되었습니다. 다른 목적으로 사용하면 안 됩니다.

참조: https://lore.kernel.org/lkml/1268959062.9440.467.camel@laptop/

`MALFORMED_INCLUDE`: `#include` statement의 path가 잘못되었습니다. 작성자가 pathname에 double slash "//"를 실수로 넣었을 때 발생합니다.

`USE_LOCKDEP`: `spin_is_locked()` 기반 assertion보다 `lockdep_assert_held()` annotation을 우선 사용해야 합니다.

참조: https://www.kernel.org/doc/html/latest/locking/lockdep-design.html#annotations

`UAPI_INCLUDE`: `include/uapi` 아래의 `#include` statement에서는 `uapi/` path를 사용하면 안 됩니다.

`USLEEP_RANGE`: `udelay()`보다 `usleep_range()`를 우선 사용해야 합니다. 올바른 사용법은 kernel 문서에 설명되어 있습니다.

comment 관련 message type

Comment

`BLOCK_COMMENT_STYLE`: comment style이 잘못되었습니다. multi-line comment의 권장 style은 다음과 같습니다.

/*
* This is the preferred style
* for multi line comments.
*/

networking comment style은 첫 line이 비어 있지 않다는 점에서 조금 다릅니다.

/* This is the preferred comment style
* for files in net/ and drivers/net/
*/

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting

`C99_COMMENTS`: C99 style single-line comment(`//`)를 사용하지 말고 block comment style을 우선 사용하십시오.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#commenting

`DATA_RACE`: `data_race()` 적용부에는 이를 안전하다고 판단한 근거를 기록하는 comment가 있어야 합니다.

참조: https://lore.kernel.org/lkml/20200401101714.44781-1-elver@google.com/

`FSF_MAILING_ADDRESS`: FSF가 과거에 이전했고 다시 이전할 수 있으므로 kernel maintainer는 GPL 사본을 받기 위해 FSF에 편지를 쓰라고 안내하는 새 GPL boilerplate paragraph를 거부합니다. Free Software Foundation mailing address로 편지를 보내라는 paragraph를 작성하지 마십시오.

참조: https://lore.kernel.org/lkml/20131006222342.GT19510@leaf/

`UNCOMMENTED_RGMII_MODE`: Device Tree의 RGMII PHY mode는 역사적으로 board 설명이 아니라 PHY 쪽 delay 사용을 가리키는 등 일관되지 않게 사용되었습니다. "rgmii", "rgmii-rxid", "rgmii-txid" mode는 PCB에서 clock signal을 지연해야 하므로 이 특이한 구성을 comment로 설명해야 합니다. delay가 MAC 또는 PHY 내부에서 구현되어 PCB 지연이 아니라면 올바른 PHY mode는 "rgmii-id"입니다.

commit message 관련 type

Commit message

`BAD_SIGN_OFF`: signed-off-by line이 community가 정한 표준을 따르지 않습니다.

참조: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1

`BAD_STABLE_ADDRESS_STYLE`: stable 대상 email format이 잘못되었습니다. 유효한 stable address는 다음과 같습니다.

1. stable@vger.kernel.org
2. stable@kernel.org

version 정보를 추가하려면 다음 comment style을 사용합니다.

stable@vger.kernel.org # version info

`COMMIT_COMMENT_SYMBOL`: `#`으로 시작하는 commit log line은 Git이 comment로 무시합니다. log line 앞에 space 하나를 추가하면 해결됩니다.

`COMMIT_MESSAGE`: patch에 commit description이 없습니다. patch가 만든 변경을 간략히 설명해야 합니다.

참조: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes

`EMAIL_SUBJECT`: 문제를 찾은 도구 이름을 subject line에 넣는 것은 별로 유용하지 않습니다. 좋은 subject line은 patch가 가져오는 변경을 요약합니다.

참조: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes

`FROM_SIGN_OFF_MISMATCH`: 작성자의 email이 `Signed-off-by:` line과 일치하지 않습니다. email client 설정이 잘못되어 발생할 수도 있습니다. 다음 중 하나가 원인입니다.

- The email names do not match.
- The email addresses do not match.
- The email subaddresses do not match.
- The email comments do not match.

`MISSING_SIGN_OFF`: patch에 `Signed-off-by` line이 없습니다. Developer's Certificate of Origin에 따라 이 line을 추가해야 합니다.

참조: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin

`NO_AUTHOR_SIGN_OFF`: patch 작성자가 sign-off하지 않았습니다. patch 설명 끝에는 작성자가 직접 썼거나 open-source patch로 전달할 권리가 있음을 나타내는 간단한 sign-off line이 있어야 합니다.

참조: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin

`DIFF_IN_COMMIT_MSG`: commit message에 diff 내용을 넣지 마십시오. changelog와 diff가 함께 든 file을 적용할 때 `patch(1)`이 changelog에서 찾은 diff까지 적용하려 해 문제가 됩니다.

참조: https://lore.kernel.org/lkml/20150611134006.9df79a893e3636019ad2759e@linux-foundation.org/

`GERRIT_CHANGE_ID`: Gerrit이 commit을 선택할 수 있도록 commit message footer에 다음과 같은 `Change-Id`가 있을 수 있습니다.

Change-Id: Ic8aaa0728a43936cd4c6e1ed590e01ba8f0fbf5b
Signed-off-by: A. U. Thor <author@example.com>

제출 전에는 `Change-Id` line을 제거해야 합니다.

`GIT_COMMIT_ID`: commit id의 올바른 참조 형식은 `commit <12자 이상의 sha1> ("<title line>")`입니다. 예:

Commit e21d2170f36602ae2708 ("video: remove unnecessary
platform_set_drvdata()") removed the unnecessary
platform_set_drvdata(), but left the variable "dev" unused,
delete it.

참조: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes

`BAD_FIXES_TAG`: `Fixes:` tag가 잘못되었거나 community 관례를 따르지 않습니다. word wrapping을 켠 email program에 붙여 넣을 때처럼 tag가 여러 line으로 나뉘면 발생할 수 있습니다.

참조: https://www.kernel.org/doc/html/latest/process/submitting-patches.html#describe-your-changes

comparison style type

Comparison style

`ASSIGN_IN_IF`: if condition 안에서 assignment를 사용하지 마십시오. 예:

if ((foo = bar(...)) < BAZ) {

다음과 같이 작성해야 합니다.

foo = bar(...);
if (foo < BAZ) {

`BOOL_COMPARISON`: A를 `true` 또는 `false`와 비교하기보다 각각 A와 `!A`로 작성하는 편이 좋습니다.

참조: https://lore.kernel.org/lkml/1365563834.27174.12.camel@joe-AO722/

`COMPARISON_TO_NULL`: `(foo == NULL)` 또는 `(foo != NULL)` 형태보다 각각 `(!foo)`와 `(foo)`로 작성하는 편이 좋습니다.

`CONSTANT_COMPARISON`: test의 왼쪽에 constant 또는 upper-case identifier를 두는 비교는 피해야 합니다.

indentation과 line break type

Indentation and Line Breaks

`CODE_INDENT`: code indentation에는 space 대신 tab을 사용해야 합니다. comment, documentation, Kconfig 밖에서는 indentation에 space를 사용하지 않습니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation

`DEEP_INDENTATION`: tab 6개 이상의 indentation은 대체로 code가 지나치게 깊다는 뜻입니다. `if`/`else`/`for`/`do`/`while`/`switch` statement의 과도한 indentation을 refactor하는 것이 좋습니다.

참조: https://lore.kernel.org/lkml/1328311239.21255.24.camel@joe2Laptop/

`SWITCH_CASE_INDENT_LEVEL`: `switch`와 `case`는 같은 indentation level에 있어야 합니다. 예:

switch (suffix) {
case 'G':
case 'g':
        mem <<= 30;
        break;
case 'M':
case 'm':
        mem <<= 20;
        break;
case 'K':
case 'k':
        mem <<= 10;
        fallthrough;
default:
        break;
}

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#indentation

`LONG_LINE`: line이 지정된 최대 길이를 넘었습니다. 다른 길이를 쓰려면 checkpatch 호출에 `--max-line-length=n` option을 추가합니다. 이전 기본값은 80 column이었으나 commit `bdc48fa11e46`("checkpatch/coding-style: deprecate 80-column warning")에서 100 column으로 늘었습니다. 이 또한 hard limit은 아니며 가능하면 80 column 안에 두는 것이 좋습니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings

`LONG_LINE_STRING`: string이 최대 line 길이 전에 시작하지만 그 너머까지 이어집니다. 다른 최대 길이를 쓰려면 `--max-line-length=n`을 추가합니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings

`LONG_LINE_COMMENT`: comment가 최대 line 길이 전에 시작하지만 그 너머까지 이어집니다. 다른 최대 길이를 쓰려면 `--max-line-length=n`을 추가합니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#breaking-long-lines-and-strings

`SPLIT_STRING`: user space에 message로 표시되고 grep할 수 있는 quoted string은 여러 line으로 나누지 않아야 합니다.

참조: https://lore.kernel.org/lkml/20120203052727.GA15035@leaf/

`MULTILINE_DEREFERENCE`: 하나의 dereference identifier를 다음처럼 여러 line에 걸쳐 쓰면 대체로 따라가기 어렵고 typo와 bug에 취약해집니다.

struct_identifier->member[index].
member = <foo>;

한 line으로 고치면 80 column을 넘는 경우 code를 더 단순하게 다시 쓰십시오. dereference 시작 부분이 같고 여러 위치에서 사용된다면 그 부분을 temporary variable에 저장하고 모든 위치에서 그 변수를 사용합니다. 예를 들어 다음 두 identifier가 있다면

member1->member2->member3.foo1;
member1->member2->member3.foo2;

`member1->member2->member3` 부분을 temporary variable에 저장합니다. 80 column 위반을 피할 뿐 아니라 불필요한 dereference를 제거해 program 크기도 줄입니다. 어느 방법도 통하지 않는다면 여러 line보다 한 line dereference가 읽기 쉬우므로 80 column 위반을 무시하십시오.

`TRAILING_STATEMENTS`: conditional 뒤 같은 곳에 붙은 statement는 다음 line에 써야 합니다. 다음 형태는

if (x == y) break;

다음처럼 작성해야 합니다.

if (x == y)
        break;

macro, attribute와 symbol type

Macros, Attributes and Symbols

`ARRAY_SIZE`: array의 element 수를 구할 때 `sizeof(foo)/sizeof(foo[0])`보다 `ARRAY_SIZE(foo)` macro를 우선 사용해야 합니다. 이 macro는 `include/linux/kernel.h`에 다음과 같이 정의됩니다.

#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))

`AVOID_EXTERNS`: `.h` file의 함수 prototype에 `extern`을 선언할 필요가 없습니다. compiler가 이를 가정하므로 불필요합니다.

`AVOID_L_PREFIX`: `.L` prefix가 붙은 local symbol 이름은 assembler에서 특별한 의미를 가지며 symbol table에 entry가 나오지 않으므로 피해야 합니다. 이로 인해 `objtool`이 올바른 unwind info를 만들지 못할 수 있습니다.

`STB_LOCAL` binding의 symbol은 사용할 수 있고 함수 안에서는 `.L` prefix local symbol도 대체로 사용할 수 있습니다. 하지만 `.L` prefix 이름을 `SYM_CODE_START_LOCAL`/`SYM_CODE_END`를 통한 code region 시작이나 끝 표시에 사용하면 안 됩니다.

`BIT_MACRO`: `1 << <digit>` 같은 define은 `BIT(digit)`로 작성할 수 있습니다. `BIT()` macro는 `include/linux/bits.h`에 다음과 같이 정의됩니다.

#define BIT(nr)         (1UL << (nr))

`CONST_READ_MOSTLY`: 변수에 `__read_mostly` annotation을 붙이면 대부분 read하고 드물게, 하지만 전혀 없지는 않게 write한다는 사실을 compiler에 알립니다. const data는 이미 read-only이므로 `const __read_mostly`는 의미가 없고 annotation을 제거해야 합니다.

`DATE_TIME`: 같은 source code를 같은 tool set으로 build하면 항상 같은 output을 내도록 reproducible하게 만드는 것이 일반적으로 바람직합니다. kernel은 비결정적 build를 만들 수 있는 `__DATE__`와 `__TIME__` macro를 사용하지 않으며, 사용하면 warning을 활성화합니다.

참조: https://www.kernel.org/doc/html/latest/kbuild/reproducible-builds.html#timestamps

`DEFINE_ARCH_HAS`: `ARCH_HAS_xyz`와 `ARCH_HAVE_xyz` pattern은 잘못되었습니다. 큰 개념적 기능에는 Kconfig symbol을 사용하십시오. compatibility fallback 함수가 있으면서 architecture가 최적화 구현으로 override해야 하는 작은 기능에는 적절한 경우 weak 함수 또는 실제 보호에 쓰는 것과 같은 symbol을 사용해야 합니다.

참조: https://lore.kernel.org/lkml/CA+55aFycQ9XJvEOsiM3txHL5bjUc8CeKWJNR_H+MiicaddB42Q@mail.gmail.com/

`DO_WHILE_MACRO_WITH_TRAILING_SEMICOLON`: `do {} while(0)` macro 끝에는 semicolon을 붙이지 않아야 합니다.

`INIT_ATTRIBUTE`: const init definition은 `__initdata` 대신 `__initconst`를 사용해야 합니다. 마찬가지로 const가 아닌 init definition에는 const를 별도로 사용해야 합니다.

`INLINE_LOCATION`: `inline` keyword는 storage class와 type 사이에 와야 합니다. 다음 code는

inline static int example_function(void)
{
        ...
}

다음처럼 작성해야 합니다.

static inline int example_function(void)
{
        ...
}

`MISPLACED_INIT`: 변수의 section marker를 GCC가 이해하지 못하거나 개발자의 의도와 다르게 이해하는 위치에 둘 수 있습니다. 예:

static struct __initdata samsung_pll_clock exynos4_plls[nr_plls] = {

이 코드는 `exynos4_plls`를 `.initdata` section에 넣지 않습니다. `__initdata` marker는 `struct` 바로 뒤를 제외하면 거의 어디에나 둘 수 있습니다. 권장 위치는 `=`가 있으면 그 앞이고, 없으면 마지막 `;` 앞입니다.

참조: https://lore.kernel.org/lkml/1377655732.3619.19.camel@joe-AO722/

`MULTISTATEMENT_MACRO_USE_DO_WHILE`: 여러 statement를 가진 macro는 `do-while` block으로 감싸야 합니다. logic defect를 피하기 위해 `if`로 시작하는 macro도 마찬가지입니다.

#define macrofun(a, b, c)                 \
  do {                                    \
          if (a == 5)                     \
                  do_this(b, c);          \
  } while (0)

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl

`PREFER_FALLTHROUGH`: `/* fallthrough */` 같은 comment 대신 `fallthrough;` pseudo keyword를 사용하십시오.

`TRAILING_SEMICOLON`: macro definition은 semicolon으로 끝나지 않아야 하며 호출 style은 함수 호출과 일관되어야 합니다. 그래야 예상하지 못한 code path를 막을 수 있습니다.

#define MAC do_something;

이 macro를 다음 if-else statement 안에서 사용하면

if (some_condition)
        MAC;

else
        do_something;

macro 확장 시 trailing semicolon이 두 개가 되어 `else` branch가 고립되므로 compile error가 발생합니다.

참조: https://lore.kernel.org/lkml/1399671106.2912.21.camel@joe-AO725/

`MACRO_ARG_UNUSED`: function-like macro가 parameter를 사용하지 않으면 build warning이 생길 수 있으므로 이런 macro를 static inline 함수로 바꾸는 것이 좋습니다. 예:

#define test(a) do { } while (0)

다음과 같은 warning이 발생합니다.

WARNING: Argument 'a' is not used in function-like macro.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#macros-enums-and-rtl

`SINGLE_STATEMENT_DO_WHILE_MACRO`: multi-statement macro에서는 예측하지 못한 code path를 피하고 여러 statement를 하나로 묶기 위해 `do-while` loop가 필요합니다. 그러나 single-statement macro에서는 문법상 맞더라도 불필요하므로 `do-while` loop를 제거하십시오.

`WEAK_DECLARATION`: `__attribute__((weak))` 또는 `__weak` 같은 weak declaration은 의도하지 않은 link defect를 만들 수 있으므로 피하십시오.

함수와 변수 type

Functions and Variables

`CAMELCASE`: CamelCase identifier를 사용하지 마십시오.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#naming

`CONST_CONST`: `const <type> const *`는 일반적으로 `const <type> * const`를 의미합니다.

`CONST_STRUCT`: const 사용은 일반적으로 바람직합니다. Checkpatch는 항상 또는 거의 항상 constant인 자주 쓰는 struct 목록을 읽습니다. 현재 목록은 `scripts/const_structs.checkpatch`에서 볼 수 있습니다.

참조: https://lore.kernel.org/lkml/alpine.DEB.2.10.1608281509480.3321@hadrien/

`EMBEDDED_FUNCTION_NAME`: refactoring으로 함수 이름이 바뀔 수 있으므로 embedded function name은 사용하기에 적절하지 않습니다. 이름을 직접 넣기보다 `"%s", __func__`를 사용하십시오. 이 검사는 함수 이름을 제공하는 patch context에 의존하므로 `-f`(`--file`) option에서는 동작하지 않습니다.

`FUNCTION_ARGUMENTS`: 다음 이유 중 하나로 warning을 출력합니다. 첫째, 함수 declaration의 argument가 identifier 이름 뒤에 오지 않는 경우입니다. 예:

void foo
(int bar, int baz)

다음처럼 고쳐야 합니다.

void foo(int bar, int baz)

둘째, 함수 definition의 일부 argument에 identifier 이름이 없는 경우입니다. 예:

void foo(int)

모든 argument에 identifier 이름이 있어야 합니다.

`FUNCTION_WITHOUT_ARGS`: argument가 없는 함수 declaration을 다음처럼 작성했다면

int foo()

다음처럼 작성해야 합니다.

int foo(void)

`GLOBAL_INITIALISERS`: global variable을 0, NULL, false 등으로 명시적으로 초기화하지 않아야 합니다. 관련 section을 0으로 채우는 compiler, 더 정확히는 loader가 자동으로 처리합니다.

`INITIALISED_STATIC`: static variable을 0으로 명시적으로 초기화하지 않아야 합니다. compiler 또는 loader가 자동으로 처리합니다.

`MULTIPLE_ASSIGNMENTS`: 한 line의 여러 assignment는 code를 불필요하게 복잡하게 만듭니다. 한 line에서는 변수 하나에만 값을 할당하면 가독성이 좋아지고 typo를 피하는 데 도움이 됩니다.

`RETURN_PARENTHESES`: `return`은 함수가 아니므로 parenthesis가 필요하지 않습니다. 다음 code는

return (bar);

간단히 다음처럼 쓸 수 있습니다.

return bar;

permission 관련 type

Permissions

`DEVICE_ATTR_PERMS`: `DEVICE_ATTR`에 사용한 permission이 일반적이지 않습니다. 보통 0644(RW), 0444(RO), 0200(WO) 세 가지만 사용합니다.

참조: https://www.kernel.org/doc/html/latest/filesystems/sysfs.html#attributes

`EXECUTE_PERMISSIONS`: source file이 executable일 이유가 없으므로 executable bit를 안전하게 제거할 수 있습니다.

`EXPORTED_WORLD_WRITABLE`: 누구나 쓸 수 있는 sysfs/debugfs file을 export하는 것은 대체로 좋지 않으며 임의로 사용하면 심각한 security bug를 만들 수 있습니다. 과거 일부 debugfs vulnerability는 local user가 device register에 임의 값을 쓰는 것처럼 보이는 상황을 허용했습니다.

참조: https://lore.kernel.org/linux-arm-kernel/cover.1296818921.git.segoon@openwall.com/

`NON_OCTAL_PERMISSIONS`: permission bit는 0700이나 0444 같은 네 자리 octal로 작성해야 하며 decimal 등 다른 base를 사용하지 마십시오.

`SYMBOLIC_PERMS`: 많은 command-line 도구가 octal notation을 사용하고 숙련된 kernel 개발자가 수십 년간 전통적인 Unix permission bit를 사용해 왔으므로 symbolic 표현보다 octal 표현이 읽고 이해하기 쉽습니다. 예를 들어 `S_IWUSR|S_IRUGO`는 0644보다 읽기 어려워 개발자의 의도를 명확하게 하기보다 가립니다.

참조: https://lore.kernel.org/lkml/CA+55aFw5v23T-zvDZp-MmD_EYxF8WbafwwB59934FV7g21uMGQ@mail.gmail.com/

spacing과 bracket 관련 type

Spacing and Brackets

`ASSIGNMENT_CONTINUATIONS`: assignment operator를 line 시작에 두지 말고 이전 line의 operand 뒤에 두어야 합니다.

`BRACES`: brace 위치가 style에 맞지 않습니다. opening brace는 line 끝에, closing brace는 line 시작에 두는 것이 권장됩니다.

if (x is true) {
        we do y
}

이는 함수가 아닌 모든 block에 적용됩니다. 함수는 예외로 opening brace를 다음 line 시작에 둡니다.

int function(int x)
{
        body of function
}

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces

`BRACKET_SPACE`: opening bracket `[` 앞에는 whitespace를 둘 수 없습니다. 예외는 세 가지입니다. 첫째, 왼쪽에 type이 있는 경우:

int [] a;

둘째, slice initializer에서 line 시작에 오는 경우:

[0...10] = 5,

셋째, curly brace 안에 있는 경우:

= { [0...10] = 5 }

`CONCATENATED_STRING`: 이어 붙이는 element 사이에는 space가 있어야 합니다. 다음 code는

printk(KERN_INFO"bar");

다음처럼 작성해야 합니다.

printk(KERN_INFO "bar");

`ELSE_AFTER_BRACE`: `else {`는 closing block `}` 뒤 같은 line에 와야 합니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces

`LINE_SPACING`: editor window가 표시할 수 있는 line 수는 제한되어 있으므로 여러 blank line을 쓰면 vertical space가 낭비됩니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces

`OPEN_BRACE`: 함수 definition의 opening brace는 다음 line에 와야 합니다. 함수가 아닌 block에서는 마지막 construct와 같은 line에 있어야 합니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces

`POINTER_LOCATION`: pointer data 또는 pointer type을 반환하는 함수에서 `*`는 type 이름이 아니라 data 이름 또는 함수 이름에 붙이는 것이 권장됩니다. 예:

char *linux_banner;
unsigned long long memparse(char *ptr, char **retptr);
char *match_strdup(substring_t *s);

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces

`SPACING`: kernel source에서 사용하는 whitespace style은 kernel 문서에 설명되어 있습니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces

`TRAILING_WHITESPACE`: trailing whitespace는 항상 제거해야 합니다. 일부 editor가 이를 강조해 file 편집 중 시각적 방해를 만들기도 합니다.

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#spaces

`UNNECESSARY_PARENTHESES`: 다음 경우에는 parenthesis가 필요하지 않습니다. 첫째, function pointer 사용에서 다음 code는

(foo->bar)();

다음처럼 쓸 수 있습니다.

foo->bar();

둘째, if 안의 비교에서 다음 code는

if ((foo->bar) && (foo->baz))
if ((foo == bar))

다음처럼 쓸 수 있습니다.

if (foo->bar && foo->baz)
if (foo == bar)

셋째, 단일 lvalue의 address-of 또는 dereference에서 다음 code는

&(foo->bar)
*(foo->bar)

다음처럼 쓸 수 있습니다.

&foo->bar
*foo->bar

`WHILE_AFTER_BRACE`: `while`은 closing bracket 뒤 같은 line에 와야 합니다.

do {
        ...
} while(something);

참조: https://www.kernel.org/doc/html/latest/process/coding-style.html#placing-braces-and-spaces

기타 message type

Others

`CONFIG_DESCRIPTION`: Kconfig symbol에는 이를 완전히 설명하는 help text가 있어야 합니다.

`CORRUPTED_PATCH`: patch가 손상되었거나 line이 wrapping된 것으로 보입니다. maintainer에게 보내기 전에 patch file을 다시 생성하십시오.

`CVS_KEYWORD`: Linux가 Git으로 이동한 뒤 CVS marker는 더 이상 사용하지 않으므로 `$Id$`, `$Revision$`, `$Log$` 같은 CVS style keyword를 추가하면 안 됩니다.

`DEFAULT_NO_BREAK`: switch default case를 때때로 "default:;"로 작성하는데, default 아래에 새 case를 추가하면 결함이 생길 수 있습니다. 원치 않는 fallthrough를 막으려면 빈 default statement 뒤에 `break;`를 추가해야 합니다.

`DOS_LINE_ENDINGS`: DOS format patch는 line 끝에 여분의 `^M` symbol이 있으므로 제거해야 합니다.

`DT_SCHEMA_BINDING_PATCH`: DT binding은 freeform text 대신 JSON Schema 기반 format으로 이동했습니다.

참조: https://www.kernel.org/doc/html/latest/devicetree/bindings/writing-schema.html

`DT_SPLIT_BINDING_PATCH`: Devicetree binding은 별도 patch여야 합니다. binding은 driver 구현과 논리적으로 독립적이고 maintainer도 다르며, 같은 tree를 통해 적용되는 경우가 많더라도 `git-filter-branch`로 만든 DT 전용 tree의 history가 더 깔끔해집니다.

참조: https://www.kernel.org/doc/html/latest/devicetree/bindings/submitting-patches.html#i-for-patch-submitters

`EMBEDDED_FILENAME`: path는 자주 이동해 잘못될 수 있으므로 file 안에 완전한 filename path를 넣는 것은 특별히 유용하지 않습니다.

`FILE_PATH_CHANGES`: file을 추가, 이동, 삭제하면 `MAINTAINERS` file pattern이 맞지 않거나 오래된 상태가 될 수 있으므로 `MAINTAINERS`도 갱신해야 할 수 있습니다.

`MEMSET`: `memset` 사용이 잘못된 것으로 보입니다. parameter 순서가 잘못되었을 수 있으므로 다시 확인하십시오.

`NOT_UNIFIED_DIFF`: patch file이 unified-diff format이 아닌 것으로 보입니다. maintainer에게 보내기 전에 다시 생성하십시오.

`PRINTF_0XDECIMAL`: decimal output 앞에 `0x`를 붙이는 것은 잘못이므로 고쳐야 합니다.

`SPDX_LICENSE_TAG`: source file에 SPDX identifier tag가 없거나 잘못되었습니다. Linux kernel은 모든 source file에 정확한 SPDX identifier를 요구하며 kernel 문서에 자세히 설명되어 있습니다.

참조: https://www.kernel.org/doc/html/latest/process/license-rules.html

`TYPO_SPELLING`: 일부 단어의 spelling이 틀렸을 수 있으므로 검토하십시오.