요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
ABI 항목의 tag
README:45-61What, Date, KernelVersion, Contact, Description, Users tag가 각각 interface의 경로, 도입 시점, 담당자, 사용법과 실제 사용자를 기록합니다.
상태 변경 규칙
README:64-85ReST와 호환되는 단순한 표기법을 사용하고, testing interface를 제거하려면 먼저 obsolete 단계를 거쳐야 합니다.
ABI가 아닌 항목
README:88-98Kconfig symbol과 kernel 내부 symbol은 존재 여부, 위치, type을 포함해 안정된 user space ABI로 간주할 수 없습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
This part of the documentation inside Documentation/ABI directory
attempts to document the ABI between the Linux kernel and
userspace, and the relative stability of these interfaces. Due to the
everchanging nature of Linux, and the differing maturity levels, these
interfaces should be used by userspace programs in different ways.
We have four different levels of ABI stability, as shown by the four
different subdirectories in this location. Interfaces may change levels
of stability according to the rules described below.
The different levels of stability are:
stable/
This directory documents the interfaces that the developer has
defined to be stable. Userspace programs are free to use these
interfaces with no restrictions, and backward compatibility for
them will be guaranteed for at least 2 years. Most interfaces
(like syscalls) are expected to never change and always be
available.
testing/
This directory documents interfaces that are felt to be stable,
as the main development of this interface has been completed.
The interface can be changed to add new features, but the
current interface will not break by doing this, unless grave
errors or security problems are found in them. Userspace
programs can start to rely on these interfaces, but they must be
aware of changes that can occur before these interfaces move to
be marked stable. Programs that use these interfaces are
strongly encouraged to add their name to the description of
these interfaces, so that the kernel developers can easily
notify them if any changes occur (see the description of the
layout of the files below for details on how to do this.)
obsolete/
This directory documents interfaces that are still remaining in
the kernel, but are marked to be removed at some later point in
time. The description of the interface will document the reason
why it is obsolete and when it can be expected to be removed.
removed/
This directory contains a list of the old interfaces that have
been removed from the kernel.
Every file in these directories will contain the following information:
What: Short description of the interface
Date: Date created
KernelVersion: (Optional) Kernel version this feature first showed up in.
Note: git history often provides more accurate version
info, so this field may be omitted.
Contact: Primary contact for this interface (may be a mailing list)
Description: Long description of the interface and how to use it.
Users: All users of this interface who wish to be notified when
it changes. This is very important for interfaces in
the "testing" stage, so that kernel developers can work
with userspace developers to ensure that things do not
break in ways that are unacceptable. It is also
important to get feedback for these interfaces to make
sure they are working in a proper way and do not need to
be changed further.
Note:
The fields should be use a simple notation, compatible with ReST markup.
Also, the file **should not** have a top-level index, like::
===
foo
===
How things move between levels:
Interfaces in stable may move to obsolete, as long as the proper
notification is given.
Interfaces may be removed from obsolete and the kernel as long as the
documented amount of time has gone by.
Interfaces in the testing state can move to the stable state when the
developers feel they are finished. They cannot be removed from the
kernel tree without going through the obsolete state first.
It's up to the developer to place their interfaces in the category they
wish for it to start out in.
Notable bits of non-ABI, which should not under any circumstances be considered
stable:
- Kconfig. Userspace should not rely on the presence or absence of any
particular Kconfig symbol, in /proc/config.gz, in the copy of .config
commonly installed to /boot, or in any invocation of the kernel build
process.
- Kernel-internal symbols. Do not rely on the presence, absence, location, or
type of any kernel symbol, either in System.map files or the kernel binary
itself. See Documentation/process/stable-api-nonsense.rst.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
ABI 안정성의 네 단계
1-43Documentation/ABI 디렉터리에 있는 이 문서 부분은 Linux kernel과 user space 사이의 ABI, 그리고 이 interface들의 상대적인 안정성을 문서화하려는 것이다. Linux는 계속 변하고 각 interface의 성숙도도 서로 다르므로, user space program은 안정성 수준에 맞는 방식으로 이 interface들을 사용해야 한다.
이 위치의 네 하위 디렉터리는 서로 다른 네 가지 ABI 안정성 수준을 나타낸다. Interface는 아래 규칙에 따라 안정성 수준이 바뀔 수 있다.
stable/
개발자가 안정적이라고 정의한 interface를 문서화하는 디렉터리다. User space program은 제한 없이 이 interface들을 사용할 수 있으며, 적어도 2년 동안 하위 호환성이 보장된다. System call과 같은 대부분의 interface는 변경되지 않고 계속 제공될 것으로 예상한다.
testing/
주요 개발이 끝나 안정적이라고 판단되는 interface를 문서화하는 디렉터리다. 새 기능을 추가하기 위해 interface를 변경할 수 있지만, 심각한 오류나 보안 문제가 발견되지 않는 한 그 과정에서 현재 interface를 깨뜨리지는 않는다.
User space program은 이 interface에 의존하기 시작할 수 있다. 다만 stable로 표시되기 전에는 변경될 수 있음을 알아야 한다. 이 interface를 사용하는 program은 interface 설명에 자신의 이름을 추가할 것을 강하게 권장한다. 그러면 변경이 생겼을 때 kernel 개발자가 사용자에게 쉽게 알릴 수 있다. 추가 방법은 아래 파일 형식 설명을 따른다.
obsolete/
아직 kernel에 남아 있지만 나중에 제거할 대상으로 표시된 interface를 문서화하는 디렉터리다. 각 설명에는 interface가 obsolete인 이유와 제거 예정 시점이 기록된다.
removed/
kernel에서 이미 제거된 옛 interface의 목록을 보관하는 디렉터리다.
ABI 파일에 기록하는 정보
45-61이 디렉터리들에 있는 모든 파일은 다음 정보를 포함한다.
| tag | 의미 |
|---|---|
| What | interface에 대한 짧은 설명 |
| Date | interface가 만들어진 날짜 |
| KernelVersion | 선택 사항. 이 기능이 처음 나타난 kernel version이다. Git history가 더 정확한 version 정보를 제공하는 경우가 많으므로 생략할 수 있다. |
| Contact | 이 interface의 주 담당 연락처다. Mailing list일 수도 있다. |
| Description | interface와 그 사용 방법에 대한 자세한 설명 |
| Users | interface가 변경될 때 통지를 받기 원하는 모든 사용자 |
Users 정보는 특히 testing 단계의 interface에서 매우 중요하다. Kernel 개발자와 user space 개발자가 함께 작업하여 받아들이기 어려운 방식으로 기존 동작이 깨지지 않게 할 수 있기 때문이다. Interface가 올바르게 동작하는지, 더 변경할 필요는 없는지 feedback을 얻는 데에도 중요하다.
문서 표기와 단계 변경 규칙
64-85각 field는 ReST markup과 호환되는 단순한 표기법을 사용해야 한다. 또한 파일에는 다음과 같은 최상위 제목을 두어서는 안 된다.
===
foo
===단계 사이의 이동
적절한 통지가 이루어졌다면 stable interface를 obsolete로 옮길 수 있다.
문서에 명시한 시간이 지난 뒤에는 obsolete interface를 obsolete 목록과 kernel에서 제거할 수 있다.
개발자가 개발이 끝났다고 판단하면 testing 상태의 interface를 stable 상태로 옮길 수 있다. Testing interface는 먼저 obsolete 상태를 거치지 않고 kernel tree에서 제거할 수 없다.
새 interface를 어느 범주에서 시작할지는 개발자가 결정한다.
안정된 ABI로 간주할 수 없는 항목
88-98다음은 주목할 만한 비 ABI 항목이며, 어떤 상황에서도 안정적이라고 간주해서는 안 된다.
Kconfig
User space는 /proc/config.gz, 일반적으로 /boot에 설치되는 .config 사본, 또는 kernel build process를 실행하는 어떤 과정에서도 특정 Kconfig symbol의 존재 여부에 의존해서는 안 된다.
Kernel 내부 symbol
System.map 파일이나 kernel binary 자체에 있는 어떤 kernel symbol도 그 존재 여부, 위치 또는 type에 의존해서는 안 된다. 자세한 내용은 Documentation/process/stable-api-nonsense.rst를 참조한다.
ABI 안정성 단계
README:1-43ABI 문서는 user space가 interface를 어느 정도 신뢰할 수 있는지 stable, testing, obsolete, removed 네 단계로 구분합니다.