요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0+
.. |san_client_link| replace:: :c:func:`san_client_link`
.. |san_dgpu_notifier_register| replace:: :c:func:`san_dgpu_notifier_register`
.. |san_dgpu_notifier_unregister| replace:: :c:func:`san_dgpu_notifier_unregister`
===================
Surface ACPI Notify
===================
The Surface ACPI Notify (SAN) device provides the bridge between ACPI and
SAM controller. Specifically, ACPI code can execute requests and handle
battery and thermal events via this interface. In addition to this, events
relating to the discrete GPU (dGPU) of the Surface Book 2 can be sent from
ACPI code (note: the Surface Book 3 uses a different method for this). The
only currently known event sent via this interface is a dGPU power-on
notification. While this driver handles the former part internally, it only
relays the dGPU events to any other driver interested via its public API and
does not handle them.
The public interface of this driver is split into two parts: Client
registration and notifier-block registration.
A client to the SAN interface can be linked as consumer to the SAN device
via |san_client_link|. This can be used to ensure that the a client
receiving dGPU events does not miss any events due to the SAN interface not
being set up as this forces the client driver to unbind once the SAN driver
is unbound.
Notifier-blocks can be registered by any device for as long as the module is
loaded, regardless of being linked as client or not. Registration is done
with |san_dgpu_notifier_register|. If the notifier is not needed any more, it
should be unregistered via |san_dgpu_notifier_unregister|.
Consult the API documentation below for more details.
API Documentation
=================
.. kernel-doc:: include/linux/surface_acpi_notify.h
.. kernel-doc:: drivers/platform/surface/surface_acpi_notify.c
:export:
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Surface ACPI Notify 문서 머리말
1-9이 문서는 `GPL-2.0+` SPDX license를 사용하는 Surface ACPI Notify(SAN) interface 설명입니다.
머리말은 client link와 dGPU notifier 등록·해제 함수인 `san_client_link`, `san_dgpu_notifier_register`, `san_dgpu_notifier_unregister`를 교차 참조 symbol로 정의합니다.
.. SPDX-License-Identifier: GPL-2.0+
.. |san_client_link| replace:: :c:func:`san_client_link`
.. |san_dgpu_notifier_register| replace:: :c:func:`san_dgpu_notifier_register`
.. |san_dgpu_notifier_unregister| replace:: :c:func:`san_dgpu_notifier_unregister`
===================
Surface ACPI Notify
===================ACPI와 SAM controller bridge
10-22Surface ACPI Notify device는 ACPI와 SAM controller 사이의 bridge를 제공합니다. ACPI code는 이 interface를 통해 request를 실행하고 battery·thermal event를 처리할 수 있습니다.
Surface Book 2의 discrete GPU(dGPU) 관련 event도 ACPI code에서 보낼 수 있습니다. Surface Book 3은 이와 다른 방식을 사용합니다.
현재 이 interface를 통해 전달되는 것으로 알려진 유일한 event는 dGPU power-on notification입니다.
Driver는 ACPI request와 battery·thermal event 부분을 내부에서 처리하지만 dGPU event는 직접 처리하지 않습니다. Public API를 통해 관심 있는 다른 driver로 relay합니다.
Public interface는 client registration과 notifier-block registration의 두 부분으로 나뉩니다.
SAN은 ACPI 요청을 SAM controller에 연결하고 dGPU event는 consumer driver로 중계합니다.
The Surface ACPI Notify (SAN) device provides the bridge between ACPI and
SAM controller. Specifically, ACPI code can execute requests and handle
battery and thermal events via this interface. In addition to this, events
relating to the discrete GPU (dGPU) of the Surface Book 2 can be sent from
ACPI code (note: the Surface Book 3 uses a different method for this). The
only currently known event sent via this interface is a dGPU power-on
notification. While this driver handles the former part internally, it only
relays the dGPU events to any other driver interested via its public API and
does not handle them.
The public interface of this driver is split into two parts: Client
registration and notifier-block registration.Client link와 dGPU notifier
23-35SAN interface client는 `san_client_link()`를 통해 SAN device의 consumer로 연결할 수 있습니다.
이 link는 SAN interface가 설정되지 않아 dGPU event를 놓치는 일을 방지합니다. SAN driver가 unbind될 때 client driver도 unbind되도록 강제하여 ordering을 보장합니다.
Notifier block은 client link 여부와 관계없이 module이 load되어 있는 동안 어떤 device든 등록할 수 있습니다. `san_dgpu_notifier_register()`로 등록하고 더 필요하지 않으면 `san_dgpu_notifier_unregister()`로 해제해야 합니다.
A client to the SAN interface can be linked as consumer to the SAN device
via |san_client_link|. This can be used to ensure that the a client
receiving dGPU events does not miss any events due to the SAN interface not
being set up as this forces the client driver to unbind once the SAN driver
is unbound.
Notifier-blocks can be registered by any device for as long as the module is
loaded, regardless of being linked as client or not. Registration is done
with |san_dgpu_notifier_register|. If the notifier is not needed any more, it
should be unregistered via |san_dgpu_notifier_unregister|.
Consult the API documentation below for more details.SAN API kernel-doc
36-44API 세부 정보는 `include/linux/surface_acpi_notify.h` header의 kernel-doc과 `drivers/platform/surface/surface_acpi_notify.c`에서 export된 implementation API를 결합합니다.
API Documentation
=================
.. kernel-doc:: include/linux/surface_acpi_notify.h
.. kernel-doc:: drivers/platform/surface/surface_acpi_notify.c
:export:
요약과 해설
san.rst:1-44SAN은 ACPI request와 battery·thermal event를 SAM controller에 연결하고 Surface Book 2 dGPU power-on event를 consumer driver로 중계합니다. Client link는 SAN보다 client가 먼저 unbind되도록 보장하며 notifier block은 module이 load된 동안 독립적으로 등록할 수 있습니다.