요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
=============================
Suspend/Hibernation Notifiers
=============================
:Copyright: |copy| 2016 Intel Corporation
:Author: Rafael J. Wysocki <[email protected]>
There are some operations that subsystems or drivers may want to carry out
before hibernation/suspend or after restore/resume, but they require the system
to be fully functional, so the drivers' and subsystems' ``->suspend()`` and
``->resume()`` or even ``->prepare()`` and ``->complete()`` callbacks are not
suitable for this purpose.
For example, device drivers may want to upload firmware to their devices after
resume/restore, but they cannot do it by calling :c:func:`request_firmware()`
from their ``->resume()`` or ``->complete()`` callback routines (user land
processes are frozen at these points). The solution may be to load the firmware
into memory before processes are frozen and upload it from there in the
``->resume()`` routine. A suspend/hibernation notifier may be used for that.
Subsystems or drivers having such needs can register suspend notifiers that
will be called upon the following events by the PM core:
``PM_HIBERNATION_PREPARE``
The system is going to hibernate, tasks will be frozen immediately. This
is different from ``PM_SUSPEND_PREPARE`` below, because in this case
additional work is done between the notifiers and the invocation of PM
callbacks for the "freeze" transition.
``PM_POST_HIBERNATION``
The system memory state has been restored from a hibernation image or an
error occurred during hibernation. Device restore callbacks have been
executed and tasks have been thawed.
``PM_RESTORE_PREPARE``
The system is going to restore a hibernation image. If all goes well,
the restored image kernel will issue a ``PM_POST_HIBERNATION``
notification.
``PM_POST_RESTORE``
An error occurred during restore from hibernation. Device restore
callbacks have been executed and tasks have been thawed.
``PM_SUSPEND_PREPARE``
The system is preparing for suspend.
``PM_POST_SUSPEND``
The system has just resumed or an error occurred during suspend. Device
resume callbacks have been executed and tasks have been thawed.
It is generally assumed that whatever the notifiers do for
``PM_HIBERNATION_PREPARE``, should be undone for ``PM_POST_HIBERNATION``.
Analogously, operations carried out for ``PM_SUSPEND_PREPARE`` should be
reversed for ``PM_POST_SUSPEND``.
Moreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or
``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that
event will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``,
respectively.
The hibernation and suspend notifiers are called with :c:data:`pm_mutex` held.
They are defined in the usual way, but their last argument is meaningless (it is
always NULL).
To register and/or unregister a suspend notifier use
:c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`,
respectively (both defined in :file:`include/linux/suspend.h`). If you don't
need to unregister the notifier, you can also use the :c:func:`pm_notifier()`
macro defined in :file:`include/linux/suspend.h`.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
suspend·hibernation notifier가 필요한 시점
1-24Rafael J. Wysocki가 설명한 suspend/hibernation notifier는 system이 완전히 동작하는 상태에서만 가능한 작업을 PM transition 전후에 수행하기 위한 interface입니다. driver의 `suspend`, `resume`, 심지어 `prepare`, `complete` callback 시점에는 user-space task가 freeze되어 있거나 필요한 service가 아직 없어 이런 작업에 적합하지 않을 수 있습니다.
예를 들어 resume/restore 뒤 device에 firmware를 upload해야 해도 `resume`이나 `complete`에서 `request_firmware()`를 호출할 수 없습니다. 이 시점에는 user-land process가 frozen이기 때문입니다. 해결 방법은 process freeze 전에 firmware를 memory에 load해 두고 resume routine에서 upload하는 것이며, 준비 동작을 notifier에서 수행할 수 있습니다.
user space가 살아 있을 때 firmware를 확보하고 device resume callback은 memory copy를 사용합니다.
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
=============================
Suspend/Hibernation Notifiers
=============================
:Copyright: |copy| 2016 Intel Corporation
:Author: Rafael J. Wysocki <[email protected]>
There are some operations that subsystems or drivers may want to carry out
before hibernation/suspend or after restore/resume, but they require the system
to be fully functional, so the drivers' and subsystems' ``->suspend()`` and
``->resume()`` or even ``->prepare()`` and ``->complete()`` callbacks are not
suitable for this purpose.
For example, device drivers may want to upload firmware to their devices after
resume/restore, but they cannot do it by calling :c:func:`request_firmware()`
from their ``->resume()`` or ``->complete()`` callback routines (user land
processes are frozen at these points). The solution may be to load the firmware
into memory before processes are frozen and upload it from there in the
``->resume()`` routine. A suspend/hibernation notifier may be used for that.PM notifier event 의미
25-54subsystem과 driver가 등록한 suspend notifier는 PM core가 여섯 event에 맞춰 호출합니다. `PM_HIBERNATION_PREPARE`는 hibernation 직전이며 task가 곧 freeze됩니다. `PM_SUSPEND_PREPARE`와 달리 notifier 뒤 freeze transition의 device callback 전까지 추가 작업이 있습니다.
`PM_POST_HIBERNATION`은 hibernation image에서 memory state를 복원했거나 hibernation 중 error가 난 뒤 발생하며 device restore callback이 끝나고 task도 thaw된 상태입니다. `PM_RESTORE_PREPARE`는 image restore를 시작하기 전이고 성공하면 복원된 image kernel이 `PM_POST_HIBERNATION`을 알립니다. `PM_POST_RESTORE`는 restore error 뒤 device restore와 task thaw가 끝난 시점입니다.
`PM_SUSPEND_PREPARE`는 system suspend 준비 시점이고 `PM_POST_SUSPEND`는 정상 resume 또는 suspend error 뒤 device resume callback과 task thaw가 완료된 시점입니다.
Subsystems or drivers having such needs can register suspend notifiers that
will be called upon the following events by the PM core:
``PM_HIBERNATION_PREPARE``
The system is going to hibernate, tasks will be frozen immediately. This
is different from ``PM_SUSPEND_PREPARE`` below, because in this case
additional work is done between the notifiers and the invocation of PM
callbacks for the "freeze" transition.
``PM_POST_HIBERNATION``
The system memory state has been restored from a hibernation image or an
error occurred during hibernation. Device restore callbacks have been
executed and tasks have been thawed.
``PM_RESTORE_PREPARE``
The system is going to restore a hibernation image. If all goes well,
the restored image kernel will issue a ``PM_POST_HIBERNATION``
notification.
``PM_POST_RESTORE``
An error occurred during restore from hibernation. Device restore
callbacks have been executed and tasks have been thawed.
``PM_SUSPEND_PREPARE``
The system is preparing for suspend.
``PM_POST_SUSPEND``
The system has just resumed or an error occurred during suspend. Device
resume callbacks have been executed and tasks have been thawed.notifier rollback, locking, 등록 API
55-74`PM_HIBERNATION_PREPARE`에서 수행한 작업은 `PM_POST_HIBERNATION`에서 되돌리고, `PM_SUSPEND_PREPARE`의 작업은 `PM_POST_SUSPEND`에서 역으로 처리하는 것이 기본 계약입니다.
prepare event를 처리하는 notifier 하나가 실패하면 PM core는 같은 event에서 이미 성공한 notifier들을 대응 post event로 호출합니다. 따라서 정상 복귀뿐 아니라 partial prepare failure에서도 cleanup이 실행됩니다.
hibernation·suspend notifier는 `pm_mutex`를 보유한 상태에서 호출되며 일반 notifier 방식으로 정의하지만 마지막 argument는 항상 `NULL`이라 의미가 없습니다. `include/linux/suspend.h`의 `register_pm_notifier()`와 `unregister_pm_notifier()`로 등록·해제하고, 해제할 필요가 없으면 같은 header의 `pm_notifier()` macro를 사용할 수 있습니다.
성공한 notifier만 post event로 역호출해 준비 작업을 정리합니다.
It is generally assumed that whatever the notifiers do for
``PM_HIBERNATION_PREPARE``, should be undone for ``PM_POST_HIBERNATION``.
Analogously, operations carried out for ``PM_SUSPEND_PREPARE`` should be
reversed for ``PM_POST_SUSPEND``.
Moreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or
``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that
event will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``,
respectively.
The hibernation and suspend notifiers are called with :c:data:`pm_mutex` held.
They are defined in the usual way, but their last argument is meaningless (it is
always NULL).
To register and/or unregister a suspend notifier use
:c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`,
respectively (both defined in :file:`include/linux/suspend.h`). If you don't
need to unregister the notifier, you can also use the :c:func:`pm_notifier()`
macro defined in :file:`include/linux/suspend.h`.
요약과 해설
notifiers.rst:1-74PM notifier는 user space가 필요한 작업을 task freeze 전과 thaw 후에 수행합니다. prepare event의 작업은 대응 post event에서 되돌리며, partial failure 때도 이미 성공한 notifier에 post event를 보내 rollback합니다.