요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0-or-later
====================
Kexec Handover Usage
====================
Kexec HandOver (KHO) is a mechanism that allows Linux to preserve memory
regions, which could contain serialized system states, across kexec.
This document expects that you are familiar with the base KHO
:ref:`concepts <kho-concepts>`. If you have not read
them yet, please do so now.
Prerequisites
=============
KHO is available when the kernel is compiled with ``CONFIG_KEXEC_HANDOVER``
set to y. Every KHO producer may have its own config option that you
need to enable if you would like to preserve their respective state across
kexec.
To use KHO, please boot the kernel with the ``kho=on`` command line
parameter. You may use ``kho_scratch`` parameter to define size of the
scratch regions. For example ``kho_scratch=16M,512M,256M`` will reserve a
16 MiB low memory scratch area, a 512 MiB global scratch region, and 256 MiB
per NUMA node scratch regions on boot.
Perform a KHO kexec
===================
First, before you perform a KHO kexec, you need to move the system into
the :ref:`KHO finalization phase <kho-finalization-phase>` ::
$ echo 1 > /sys/kernel/debug/kho/out/finalize
After this command, the KHO FDT is available in
``/sys/kernel/debug/kho/out/fdt``. Other subsystems may also register
their own preserved sub FDTs under
``/sys/kernel/debug/kho/out/sub_fdts/``.
Next, load the target payload and kexec into it. It is important that you
use the ``-s`` parameter to use the in-kernel kexec file loader, as user
space kexec tooling currently has no support for KHO with the user space
based file loader ::
# kexec -l /path/to/bzImage --initrd /path/to/initrd -s
# kexec -e
The new kernel will boot up and contain some of the previous kernel's state.
For example, if you used ``reserve_mem`` command line parameter to create
an early memory reservation, the new kernel will have that memory at the
same physical address as the old kernel.
Abort a KHO exec
================
You can move the system out of KHO finalization phase again by calling ::
$ echo 0 > /sys/kernel/debug/kho/out/active
After this command, the KHO FDT is no longer available in
``/sys/kernel/debug/kho/out/fdt``.
debugfs Interfaces
==================
Currently KHO creates the following debugfs interfaces. Notice that these
interfaces may change in the future. They will be moved to sysfs once KHO is
stabilized.
``/sys/kernel/debug/kho/out/finalize``
Kexec HandOver (KHO) allows Linux to transition the state of
compatible drivers into the next kexec'ed kernel. To do so,
device drivers will instruct KHO to preserve memory regions,
which could contain serialized kernel state.
While the state is serialized, they are unable to perform
any modifications to state that was serialized, such as
handed over memory allocations.
When this file contains "1", the system is in the transition
state. When contains "0", it is not. To switch between the
two states, echo the respective number into this file.
``/sys/kernel/debug/kho/out/fdt``
When KHO state tree is finalized, the kernel exposes the
flattened device tree blob that carries its current KHO
state in this file. Kexec user space tooling can use this
as input file for the KHO payload image.
``/sys/kernel/debug/kho/out/scratch_len``
Lengths of KHO scratch regions, which are physically contiguous
memory regions that will always stay available for future kexec
allocations. Kexec user space tools can use this file to determine
where it should place its payload images.
``/sys/kernel/debug/kho/out/scratch_phys``
Physical locations of KHO scratch regions. Kexec user space tools
can use this file in conjunction to scratch_phys to determine where
it should place its payload images.
``/sys/kernel/debug/kho/out/sub_fdts/``
In the KHO finalization phase, KHO producers register their own
FDT blob under this directory.
``/sys/kernel/debug/kho/in/fdt``
When the kernel was booted with Kexec HandOver (KHO),
the state tree that carries metadata about the previous
kernel's state is in this file in the format of flattened
device tree. This file may disappear when all consumers of
it finished to interpret their metadata.
``/sys/kernel/debug/kho/in/sub_fdts/``
Similar to ``kho/out/sub_fdts/``, but contains sub FDT blobs
of KHO producers passed from the old kernel.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Kexec HandOver 개요
1-13이 문서는 GPL-2.0-or-later 라이선스를 따릅니다. Kexec HandOver(KHO)는 serialized system state를 담을 수 있는 memory region을 kexec 뒤의 새 Linux kernel까지 보존하는 mechanism입니다.
이 사용법은 KHO의 기본 `kho-concepts`를 알고 있다고 가정하므로 아직 읽지 않았다면 먼저 concept 문서를 확인해야 합니다.
build와 boot 조건
14-27Kernel은 `CONFIG_KEXEC_HANDOVER=y`로 빌드해야 합니다. 각 KHO producer가 자신의 state를 kexec 너머로 보존하려면 producer별 config option도 따로 켜야 할 수 있습니다.
Boot command line에 `kho=on`을 지정합니다. `kho_scratch`로 scratch region 크기를 정할 수 있으며 `kho_scratch=16M,512M,256M`은 low-memory scratch 16 MiB, global scratch 512 MiB, NUMA node별 scratch 256 MiB를 boot 때 reserve합니다.
KHO kexec 실행
28-54KHO kexec 전에 system을 KHO finalization phase로 전환합니다.
$ echo 1 > /sys/kernel/debug/kho/out/finalize전환 뒤 KHO FDT는 `/sys/kernel/debug/kho/out/fdt`에 나타나고 다른 subsystem은 보존한 sub-FDT를 `/sys/kernel/debug/kho/out/sub_fdts/` 아래에 등록할 수 있습니다.
다음으로 target payload를 load하고 kexec합니다. User-space file loader는 아직 KHO를 지원하지 않으므로 반드시 `-s`로 in-kernel kexec file loader를 사용해야 합니다.
# kexec -l /path/to/bzImage --initrd /path/to/initrd -s
# kexec -e새 kernel은 이전 kernel state 일부를 보존한 채 boot합니다. 예를 들어 `reserve_mem` boot parameter로 early memory reservation을 만들었다면 새 kernel에서도 같은 physical address에 그 memory가 있습니다.
KHO 실행 취소
55-64다음 명령으로 system을 finalization phase에서 다시 빼낼 수 있습니다.
$ echo 0 > /sys/kernel/debug/kho/out/active취소 후 `/sys/kernel/debug/kho/out/fdt`의 KHO FDT는 더 이상 제공되지 않습니다.
debugfs interface
65-115현재 KHO interface는 debugfs에 있고 향후 바뀔 수 있습니다. KHO가 안정화되면 sysfs로 이동할 예정입니다.
| path | 접근 | 역할 |
|---|---|---|
| /sys/kernel/debug/kho/out/finalize | RW | 1이면 finalization phase, 0이면 일반 상태로 전환 |
| /sys/kernel/debug/kho/out/fdt | RO | finalized KHO state를 담은 flattened device tree blob |
| /sys/kernel/debug/kho/out/scratch_len | RO | future kexec allocation에 유지되는 contiguous scratch region 길이 |
| /sys/kernel/debug/kho/out/scratch_phys | RO | scratch region의 physical location |
| /sys/kernel/debug/kho/out/sub_fdts/ | directory | finalization 중 producer가 등록한 sub-FDT |
| /sys/kernel/debug/kho/in/fdt | RO | 이전 kernel에서 전달된 KHO state tree |
| /sys/kernel/debug/kho/in/sub_fdts/ | directory | 이전 kernel의 producer별 sub-FDT |
`out/finalize`가 1인 transition state에서는 compatible driver가 serialized state memory를 수정할 수 없습니다. `out/fdt`의 flattened device tree blob은 KHO payload image 입력으로 사용할 수 있습니다.
`scratch_len`과 `scratch_phys`는 future kexec allocation에도 유지되는 physically contiguous scratch region의 길이와 physical location을 제공해 user-space kexec tool이 payload 배치 위치를 정하게 합니다.
원문 99행은 `scratch_phys`를 `scratch_phys`와 함께 사용한다고 적었지만 문맥상 길이 파일인 `scratch_len`과 함께 사용한다는 뜻입니다. 원문과 line anchor는 그대로 보존하고 번역은 두 파일의 역할을 구분합니다.
`out/sub_fdts/`는 현재 kernel producer의 sub-FDT를 담습니다. KHO로 boot한 새 kernel의 `in/fdt`에는 이전 kernel metadata state tree가 있고 모든 consumer가 해석을 끝내면 사라질 수 있습니다. `in/sub_fdts/`에는 이전 kernel producer가 넘긴 sub-FDT가 있습니다.
KHO 실행 순서
kho.rst:1-115KHO를 build·boot에서 활성화하고 state를 finalize한 뒤 in-kernel loader로 target kernel을 load합니다. FDT와 producer별 sub-FDT, scratch region metadata가 이전 kernel state를 전달합니다.