요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
1
.. SPDX-License-Identifier: BSD-3-Clause
3
==============================
4
Netlink spec C code generation
5
==============================
7
This document describes how Netlink specifications are used to render
8
C code (uAPI, policies etc.). It also defines the additional properties
9
allowed in older families by the ``genetlink-c`` protocol level,
10
to control the naming.
12
For brevity this document refers to ``name`` properties of various
13
objects by the object type. For example ``$attr`` is the value
14
of ``name`` in an attribute, and ``$family`` is the name of the
15
family (the global ``name`` property).
17
The upper case is used to denote literal values, e.g. ``$family-CMD``
18
means the concatenation of ``$family``, a dash character, and the literal
19
``CMD``.
21
The names of ``#defines`` and enum values are always converted to upper case,
22
and with dashes (``-``) replaced by underscores (``_``).
24
If the constructed name is a C keyword, an extra underscore is
25
appended (``do`` -> ``do_``).
27
Globals
28
=======
30
``c-family-name`` controls the name of the ``#define`` for the family
31
name, default is ``$family-FAMILY-NAME``.
33
``c-version-name`` controls the name of the ``#define`` for the version
34
of the family, default is ``$family-FAMILY-VERSION``.
36
``max-by-define`` selects if max values for enums are defined as a
37
``#define`` rather than inside the enum.
39
Definitions
40
===========
42
Constants
43
---------
45
Every constant is rendered as a ``#define``.
46
The name of the constant is ``$family-$constant`` and the value
47
is rendered as a string or integer according to its type in the spec.
49
Enums and flags
50
---------------
52
Enums are named ``$family-$enum``. The full name can be set directly
53
or suppressed by specifying the ``enum-name`` property.
54
Default entry name is ``$family-$enum-$entry``.
55
If ``name-prefix`` is specified it replaces the ``$family-$enum``
56
portion of the entry name.
58
Boolean ``render-max`` controls creation of the max values
59
(which are enabled by default for attribute enums). These max
60
values are named ``__$pfx-MAX`` and ``$pfx-MAX``. The name
61
of the first value can be overridden via ``enum-cnt-name`` property.
63
Attributes
64
==========
66
Each attribute set (excluding fractional sets) is rendered as an enum.
68
Attribute enums are traditionally unnamed in netlink headers.
69
If naming is desired ``enum-name`` can be used to specify the name.
71
The default attribute name prefix is ``$family-A`` if the name of the set
72
is the same as the name of the family and ``$family-A-$set`` if the names
73
differ. The prefix can be overridden by the ``name-prefix`` property of a set.
74
The rest of the section will refer to the prefix as ``$pfx``.
76
Attributes are named ``$pfx-$attribute``.
78
Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX``
79
which are used for sizing attribute tables.
80
These two names can be specified directly with the ``attr-cnt-name``
81
and ``attr-max-name`` properties respectively.
83
If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name``
84
will be specified as a ``#define`` rather than an enum value.
86
Operations
87
==========
89
Operations are named ``$family-CMD-$operation``.
90
If ``name-prefix`` is specified it replaces the ``$family-CMD``
91
portion of the name.
93
Similarly to attribute enums operation enums end with special count and max
94
attributes. For operations those attributes can be renamed with
95
``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define``
96
is ``true``.
98
Multicast groups
99
================
101
Each multicast group gets a define rendered into the kernel uAPI header.
102
The name of the define is ``$family-MCGRP-$group``, and can be overwritten
103
with the ``c-define-name`` property.
105
Code generation
106
===============
108
uAPI header is assumed to come from ``<linux/$family.h>`` in the default header
109
search path. It can be changed using the ``uapi-header`` global property.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
코드 생성과 이름 표기 모델
1-26Netlink 명세는 C uAPI와 정책 등의 코드를 생성하는 데 사용됩니다. 이 문서는 오래된 family에서 `genetlink-c` protocol level이 허용하는 추가 속성과, 생성되는 C 식별자의 이름을 제어하는 방법을 정의합니다.
간결한 표기를 위해 `$attr`은 attribute 객체의 `name`, `$family`는 전역 `name`인 family 이름을 뜻합니다. 대문자로 적은 부분은 리터럴이므로 `$family-CMD`는 family 이름, 하이픈, 문자열 `CMD`를 이어 붙인 값입니다.
입력 또는 조건출력 규칙
`#define` 및 enum 값항상 대문자로 변환
하이픈 `-`밑줄 `_`로 치환
생성 이름이 C keyword끝에 밑줄 추가, 예: `do` -> `do_`
명세 이름을 헤더 식별자로 옮길 때 공통으로 적용합니다.
.. SPDX-License-Identifier: BSD-3-Clause
==============================
Netlink spec C code generation
==============================
This document describes how Netlink specifications are used to render
C code (uAPI, policies etc.). It also defines the additional properties
allowed in older families by the ``genetlink-c`` protocol level,
to control the naming.
For brevity this document refers to ``name`` properties of various
objects by the object type. For example ``$attr`` is the value
of ``name`` in an attribute, and ``$family`` is the name of the
family (the global ``name`` property).
The upper case is used to denote literal values, e.g. ``$family-CMD``
means the concatenation of ``$family``, a dash character, and the literal
``CMD``.
The names of ``#defines`` and enum values are always converted to upper case,
and with dashes (``-``) replaced by underscores (``_``).
If the constructed name is a C keyword, an extra underscore is
appended (``do`` -> ``do_``).
전역 코드 생성 속성
27-38속성기본값 또는 동작
`c-family-name`family 이름 `#define`; 기본 `$family-FAMILY-NAME`
`c-version-name`family 버전 `#define`; 기본 `$family-FAMILY-VERSION`
`max-by-define`enum 내부 값 대신 `#define`으로 max 값을 생성할지 선택
family 헤더의 이름과 max 표현 방식을 제어합니다.
Globals
=======
``c-family-name`` controls the name of the ``#define`` for the family
name, default is ``$family-FAMILY-NAME``.
``c-version-name`` controls the name of the ``#define`` for the version
of the family, default is ``$family-FAMILY-VERSION``.
``max-by-define`` selects if max values for enums are defined as a
``#define`` rather than inside the enum.
상수, enum, flags
39-62모든 constant는 `#define`으로 렌더링됩니다. 이름은 `$family-$constant`이고, 값은 명세의 자료형에 따라 문자열 또는 정수로 출력됩니다.
enum 이름의 기본형은 `$family-$enum`입니다. `enum-name`으로 전체 이름을 직접 지정하거나 이름 생성을 억제할 수 있습니다. 항목 이름은 기본적으로 `$family-$enum-$entry`이며, `name-prefix`가 있으면 앞의 `$family-$enum` 부분을 대체합니다.
속성 또는 이름의미
`render-max`max 값 생성 여부. attribute enum에서는 기본 활성화
`__$pfx-MAX`첫 번째 특수 값인 count 경계
`$pfx-MAX`공개 max 값
`enum-cnt-name`첫 번째 특수 값 이름 재정의
크기 계산용 count와 max 식별자의 생성 및 이름 변경 규칙입니다.
Definitions
===========
Constants
---------
Every constant is rendered as a ``#define``.
The name of the constant is ``$family-$constant`` and the value
is rendered as a string or integer according to its type in the spec.
Enums and flags
---------------
Enums are named ``$family-$enum``. The full name can be set directly
or suppressed by specifying the ``enum-name`` property.
Default entry name is ``$family-$enum-$entry``.
If ``name-prefix`` is specified it replaces the ``$family-$enum``
portion of the entry name.
Boolean ``render-max`` controls creation of the max values
(which are enabled by default for attribute enums). These max
values are named ``__$pfx-MAX`` and ``$pfx-MAX``. The name
of the first value can be overridden via ``enum-cnt-name`` property.
attribute enum 생성
63-85fractional set을 제외한 각 attribute set은 enum으로 렌더링됩니다. Netlink 헤더의 attribute enum은 전통적으로 이름이 없지만, 이름이 필요하면 `enum-name`으로 지정할 수 있습니다.
항목생성 규칙
family와 set 이름이 같음기본 prefix `$family-A`
family와 set 이름이 다름기본 prefix `$family-A-$set`
set의 `name-prefix`기본 prefix를 직접 대체
개별 attribute`$pfx-$attribute`
set 이름과 family 이름의 관계에 따라 기본 prefix가 달라집니다.
attribute enum 끝에는 테이블 크기 계산에 쓰는 `__$pfx-MAX`와 `$pfx-MAX`가 붙습니다. 각각 `attr-cnt-name`과 `attr-max-name`으로 이름을 직접 지정할 수 있습니다. 전역 `max-by-define`이 `true`이면 `attr-max-name`은 enum 값이 아니라 `#define`으로 생성됩니다.
Attributes
==========
Each attribute set (excluding fractional sets) is rendered as an enum.
Attribute enums are traditionally unnamed in netlink headers.
If naming is desired ``enum-name`` can be used to specify the name.
The default attribute name prefix is ``$family-A`` if the name of the set
is the same as the name of the family and ``$family-A-$set`` if the names
differ. The prefix can be overridden by the ``name-prefix`` property of a set.
The rest of the section will refer to the prefix as ``$pfx``.
Attributes are named ``$pfx-$attribute``.
Attribute enums end with two special values ``__$pfx-MAX`` and ``$pfx-MAX``
which are used for sizing attribute tables.
These two names can be specified directly with the ``attr-cnt-name``
and ``attr-max-name`` properties respectively.
If ``max-by-define`` is set to ``true`` at the global level ``attr-max-name``
will be specified as a ``#define`` rather than an enum value.
operation 명령 이름
86-97operation은 기본적으로 `$family-CMD-$operation`으로 이름 붙입니다. `name-prefix`를 지정하면 `$family-CMD` 부분을 대체합니다.
속성동작
`cmd-cnt-name`operation count 특수 항목 이름 변경
`cmd-max-name`operation max 특수 항목 이름 변경
`max-by-define: true`max를 enum 값이 아닌 define으로 생성
attribute enum과 같은 count/max 패턴을 operation에 적용합니다.
Operations
==========
Operations are named ``$family-CMD-$operation``.
If ``name-prefix`` is specified it replaces the ``$family-CMD``
portion of the name.
Similarly to attribute enums operation enums end with special count and max
attributes. For operations those attributes can be renamed with
``cmd-cnt-name`` and ``cmd-max-name``. Max will be a define if ``max-by-define``
is ``true``.
multicast group define
98-104각 multicast group은 커널 uAPI 헤더에 하나의 define으로 렌더링됩니다. 기본 이름은 `$family-MCGRP-$group`이며, `c-define-name` 속성으로 덮어쓸 수 있습니다.
Multicast groups
================
Each multicast group gets a define rendered into the kernel uAPI header.
The name of the define is ``$family-MCGRP-$group``, and can be overwritten
with the ``c-define-name`` property.
uAPI 헤더 선택
105-109기본적으로 uAPI 헤더는 표준 헤더 검색 경로의 `<linux/$family.h>`에서 온다고 가정합니다. 다른 위치나 이름을 써야 하면 전역 `uapi-header` 속성으로 변경합니다.
family, definitions, attribute sets, operations, multicast groups 읽기→각 객체의 기본 prefix 또는 명시적 이름 속성 적용→대문자 변환, 하이픈 치환, C keyword 회피 수행→max-by-define 정책에 따라 enum 또는 #define 선택→uapi-header 또는 기본 <linux/$family.h>로 헤더 연결
이름 속성과 전역 정책이 최종 C 식별자와 include 경로를 결정합니다.
Code generation
===============
uAPI header is assumed to come from ``<linux/$family.h>`` in the default header
search path. It can be changed using the ``uapi-header`` global property.
요약·해설
c-code-gen.rst:1-109생성 이름은 family와 객체 이름을 조합한 뒤 공통 C 정규화를 거칩니다. ABI 이름을 기존 헤더와 정확히 맞춰야 할 때만 객체별 override 속성을 사용하고, count/max가 enum인지 define인지도 전역 정책과 함께 검토해야 합니다.