요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0+
========
Overview
========
The Surface/System Aggregator Module (SAM, SSAM) is an (arguably *the*)
embedded controller (EC) on Microsoft Surface devices. It has been originally
introduced on 4th generation devices (Surface Pro 4, Surface Book 1), but
its responsibilities and feature-set have since been expanded significantly
with the following generations.
Features and Integration
========================
Not much is currently known about SAM on 4th generation devices (Surface Pro
4, Surface Book 1), due to the use of a different communication interface
between host and EC (as detailed below). On 5th (Surface Pro 2017, Surface
Book 2, Surface Laptop 1) and later generation devices, SAM is responsible
for providing battery information (both current status and static values,
such as maximum capacity etc.), as well as an assortment of temperature
sensors (e.g. skin temperature) and cooling/performance-mode setting to the
host. On the Surface Book 2, specifically, it additionally provides an
interface for properly handling clipboard detachment (i.e. separating the
display part from the keyboard part of the device), on the Surface Laptop 1
and 2 it is required for keyboard HID input. This HID subsystem has been
restructured for 7th generation devices and on those, specifically Surface
Laptop 3 and Surface Book 3, is responsible for all major HID input (i.e.
keyboard and touchpad).
While features have not changed much on a coarse level since the 5th
generation, internal interfaces have undergone some rather large changes. On
5th and 6th generation devices, both battery and temperature information is
exposed to ACPI via a shim driver (referred to as Surface ACPI Notify, or
SAN), translating ACPI generic serial bus write-/read-accesses to SAM
requests. On 7th generation devices, this additional layer is gone and these
devices require a driver hooking directly into the SAM interface. Equally,
on newer generations, less devices are declared in ACPI, making them a bit
harder to discover and requiring us to hard-code a sort of device registry.
Due to this, a SSAM bus and subsystem with client devices
(:c:type:`struct ssam_device <ssam_device>`) has been implemented.
Communication
=============
The type of communication interface between host and EC depends on the
generation of the Surface device. On 4th generation devices, host and EC
communicate via HID, specifically using a HID-over-I2C device, whereas on
5th and later generations, communication takes place via a USART serial
device. In accordance to the drivers found on other operating systems, we
refer to the serial device and its driver as Surface Serial Hub (SSH). When
needed, we differentiate between both types of SAM by referring to them as
SAM-over-SSH and SAM-over-HID.
Currently, this subsystem only supports SAM-over-SSH. The SSH communication
interface is described in more detail below. The HID interface has not been
reverse engineered yet and it is, at the moment, unclear how many (and
which) concepts of the SSH interface detailed below can be transferred to
it.
Surface Serial Hub
------------------
As already elaborated above, the Surface Serial Hub (SSH) is the
communication interface for SAM on 5th- and all later-generation Surface
devices. On the highest level, communication can be separated into two main
types: Requests, messages sent from host to EC that may trigger a direct
response from the EC (explicitly associated with the request), and events
(sometimes also referred to as notifications), sent from EC to host without
being a direct response to a previous request. We may also refer to requests
without response as commands. In general, events need to be enabled via one
of multiple dedicated requests before they are sent by the EC.
See Documentation/driver-api/surface_aggregator/ssh.rst for a
more technical protocol documentation and
Documentation/driver-api/surface_aggregator/internal.rst for an
overview of the internal driver architecture.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
Surface/System Aggregator Module 개요
1-13이 문서는 `GPL-2.0+` SPDX license를 사용합니다.
Surface/System Aggregator Module(SAM, SSAM)은 Microsoft Surface device에 탑재된 embedded controller(EC)이며, 사실상 핵심 EC라고 할 수 있습니다.
SAM은 4세대 device인 Surface Pro 4와 Surface Book 1에서 처음 도입됐고, 이후 세대를 거치면서 책임과 기능 범위가 크게 확장됐습니다.
.. SPDX-License-Identifier: GPL-2.0+
========
Overview
========
The Surface/System Aggregator Module (SAM, SSAM) is an (arguably *the*)
embedded controller (EC) on Microsoft Surface devices. It has been originally
introduced on 4th generation devices (Surface Pro 4, Surface Book 1), but
its responsibilities and feature-set have since been expanded significantly
with the following generations.
기능과 system integration
14-444세대 Surface Pro 4와 Surface Book 1의 SAM은 host와 EC 사이에 다른 communication interface를 사용하기 때문에 현재 알려진 내용이 많지 않습니다.
5세대 Surface Pro 2017, Surface Book 2, Surface Laptop 1과 이후 device에서 SAM은 현재 상태와 최대 용량 같은 정적 값을 포함한 battery 정보, skin temperature 같은 여러 temperature sensor, cooling·performance mode 설정을 host에 제공합니다.
Surface Book 2에서는 display 부분을 keyboard 부분에서 분리하는 clipboard detachment를 올바르게 처리하는 interface도 제공합니다. Surface Laptop 1과 2에서는 keyboard HID input에 SAM이 필요합니다.
이 HID subsystem은 7세대에서 재구성됐습니다. 특히 Surface Laptop 3와 Surface Book 3에서는 keyboard와 touchpad를 포함한 주요 HID input을 모두 담당합니다.
5세대 이후 큰 기능 범주는 크게 바뀌지 않았지만 내부 interface는 상당히 달라졌습니다. 5·6세대에서는 Surface ACPI Notify(SAN)라는 shim driver가 ACPI generic serial bus write/read access를 SAM request로 변환하여 battery와 temperature 정보를 ACPI에 노출합니다.
7세대에서는 SAN 추가 계층이 사라져 device가 SAM interface에 직접 연결하는 driver를 필요로 합니다. 새 세대일수록 ACPI에 선언되는 device도 줄어 discovery가 어려워졌고, 일종의 device registry를 hard-code해야 합니다.
이 때문에 `struct ssam_device` client device를 제공하는 SSAM bus와 subsystem이 구현됐습니다.
Features and Integration
========================
Not much is currently known about SAM on 4th generation devices (Surface Pro
4, Surface Book 1), due to the use of a different communication interface
between host and EC (as detailed below). On 5th (Surface Pro 2017, Surface
Book 2, Surface Laptop 1) and later generation devices, SAM is responsible
for providing battery information (both current status and static values,
such as maximum capacity etc.), as well as an assortment of temperature
sensors (e.g. skin temperature) and cooling/performance-mode setting to the
host. On the Surface Book 2, specifically, it additionally provides an
interface for properly handling clipboard detachment (i.e. separating the
display part from the keyboard part of the device), on the Surface Laptop 1
and 2 it is required for keyboard HID input. This HID subsystem has been
restructured for 7th generation devices and on those, specifically Surface
Laptop 3 and Surface Book 3, is responsible for all major HID input (i.e.
keyboard and touchpad).
While features have not changed much on a coarse level since the 5th
generation, internal interfaces have undergone some rather large changes. On
5th and 6th generation devices, both battery and temperature information is
exposed to ACPI via a shim driver (referred to as Surface ACPI Notify, or
SAN), translating ACPI generic serial bus write-/read-accesses to SAM
requests. On 7th generation devices, this additional layer is gone and these
devices require a driver hooking directly into the SAM interface. Equally,
on newer generations, less devices are declared in ACPI, making them a bit
harder to discover and requiring us to hard-code a sort of device registry.
Due to this, a SSAM bus and subsystem with client devices
(:c:type:`struct ssam_device <ssam_device>`) has been implemented.
세대별 communication interface
45-62Host와 EC 사이의 communication interface 유형은 Surface device 세대에 따라 다릅니다.
4세대는 HID-over-I2C device를 사용하는 HID로 통신하지만, 5세대 이후는 USART serial device로 통신합니다. 다른 operating system의 driver 명칭을 따라 이 serial device와 driver를 Surface Serial Hub(SSH)라고 부릅니다.
두 유형을 구분해야 할 때는 각각 `SAM-over-SSH`와 `SAM-over-HID`라고 부릅니다.
현재 이 subsystem은 `SAM-over-SSH`만 지원합니다. SSH interface는 뒤에서 더 자세히 설명합니다. HID interface는 아직 reverse engineering되지 않아, 아래 SSH 개념 가운데 몇 개를 어떤 방식으로 옮길 수 있는지는 현재 불분명합니다.
4세대 HID 경로와 5세대 이후 serial 경로를 구분합니다.
Communication
=============
The type of communication interface between host and EC depends on the
generation of the Surface device. On 4th generation devices, host and EC
communicate via HID, specifically using a HID-over-I2C device, whereas on
5th and later generations, communication takes place via a USART serial
device. In accordance to the drivers found on other operating systems, we
refer to the serial device and its driver as Surface Serial Hub (SSH). When
needed, we differentiate between both types of SAM by referring to them as
SAM-over-SSH and SAM-over-HID.
Currently, this subsystem only supports SAM-over-SSH. The SSH communication
interface is described in more detail below. The HID interface has not been
reverse engineered yet and it is, at the moment, unclear how many (and
which) concepts of the SSH interface detailed below can be transferred to
it.
Surface Serial Hub message 유형
63-79Surface Serial Hub(SSH)는 5세대와 그 이후 모든 Surface device에서 SAM이 사용하는 communication interface입니다.
가장 높은 수준에서 communication은 request와 event의 두 유형으로 나눌 수 있습니다. Request는 host가 EC로 보내며 EC의 직접 response를 유발할 수 있고, 그 response는 해당 request와 명시적으로 연결됩니다.
Event는 notification이라고도 하며 이전 request에 대한 직접 response가 아닌 상태로 EC에서 host로 전송됩니다. Response가 없는 request를 command라고 부르기도 합니다.
일반적으로 event는 EC가 보내기 전에 여러 전용 request 중 하나로 먼저 enable해야 합니다.
더 기술적인 protocol 설명은 `Documentation/driver-api/surface_aggregator/ssh.rst`를, 내부 driver architecture 개요는 `Documentation/driver-api/surface_aggregator/internal.rst`를 참조합니다.
Host가 시작하는 request와 EC가 비동기로 보내는 event를 구분합니다.
Surface Serial Hub
------------------
As already elaborated above, the Surface Serial Hub (SSH) is the
communication interface for SAM on 5th- and all later-generation Surface
devices. On the highest level, communication can be separated into two main
types: Requests, messages sent from host to EC that may trigger a direct
response from the EC (explicitly associated with the request), and events
(sometimes also referred to as notifications), sent from EC to host without
being a direct response to a previous request. We may also refer to requests
without response as commands. In general, events need to be enabled via one
of multiple dedicated requests before they are sent by the EC.
See Documentation/driver-api/surface_aggregator/ssh.rst for a
more technical protocol documentation and
Documentation/driver-api/surface_aggregator/internal.rst for an
overview of the internal driver architecture.
요약과 해설
overview.rst:1-79SAM은 Surface 4세대에서 도입된 embedded controller로, 5세대 이후 battery·thermal·performance·HID·detachment 기능을 맡았습니다. Linux subsystem은 현재 USART 기반 SAM-over-SSH를 지원하며, SSAM bus로 ACPI에 나타나지 않는 client device를 관리합니다.