0001 .. SPDX-License-Identifier: GPL-2.0+
0002
0003 ========
0004 Overview
0005 ========
0006
0007 The Surface/System Aggregator Module (SAM, SSAM) is an (arguably *the*)
0008 embedded controller (EC) on Microsoft Surface devices. It has been originally
0009 introduced on 4th generation devices (Surface Pro 4, Surface Book 1), but
0010 its responsibilities and feature-set have since been expanded significantly
0011 with the following generations.
0012
0013
0014 Features and Integration
0015 ========================
0016
0017 Not much is currently known about SAM on 4th generation devices (Surface Pro
0018 4, Surface Book 1), due to the use of a different communication interface
0019 between host and EC (as detailed below). On 5th (Surface Pro 2017, Surface
0020 Book 2, Surface Laptop 1) and later generation devices, SAM is responsible
0021 for providing battery information (both current status and static values,
0022 such as maximum capacity etc.), as well as an assortment of temperature
0023 sensors (e.g. skin temperature) and cooling/performance-mode setting to the
0024 host. On the Surface Book 2, specifically, it additionally provides an
0025 interface for properly handling clipboard detachment (i.e. separating the
0026 display part from the keyboard part of the device), on the Surface Laptop 1
0027 and 2 it is required for keyboard HID input. This HID subsystem has been
0028 restructured for 7th generation devices and on those, specifically Surface
0029 Laptop 3 and Surface Book 3, is responsible for all major HID input (i.e.
0030 keyboard and touchpad).
0031
0032 While features have not changed much on a coarse level since the 5th
0033 generation, internal interfaces have undergone some rather large changes. On
0034 5th and 6th generation devices, both battery and temperature information is
0035 exposed to ACPI via a shim driver (referred to as Surface ACPI Notify, or
0036 SAN), translating ACPI generic serial bus write-/read-accesses to SAM
0037 requests. On 7th generation devices, this additional layer is gone and these
0038 devices require a driver hooking directly into the SAM interface. Equally,
0039 on newer generations, less devices are declared in ACPI, making them a bit
0040 harder to discover and requiring us to hard-code a sort of device registry.
0041 Due to this, a SSAM bus and subsystem with client devices
0042 (:c:type:`struct ssam_device <ssam_device>`) has been implemented.
0043
0044
0045 Communication
0046 =============
0047
0048 The type of communication interface between host and EC depends on the
0049 generation of the Surface device. On 4th generation devices, host and EC
0050 communicate via HID, specifically using a HID-over-I2C device, whereas on
0051 5th and later generations, communication takes place via a USART serial
0052 device. In accordance to the drivers found on other operating systems, we
0053 refer to the serial device and its driver as Surface Serial Hub (SSH). When
0054 needed, we differentiate between both types of SAM by referring to them as
0055 SAM-over-SSH and SAM-over-HID.
0056
0057 Currently, this subsystem only supports SAM-over-SSH. The SSH communication
0058 interface is described in more detail below. The HID interface has not been
0059 reverse engineered yet and it is, at the moment, unclear how many (and
0060 which) concepts of the SSH interface detailed below can be transferred to
0061 it.
0062
0063 Surface Serial Hub
0064 ------------------
0065
0066 As already elaborated above, the Surface Serial Hub (SSH) is the
0067 communication interface for SAM on 5th- and all later-generation Surface
0068 devices. On the highest level, communication can be separated into two main
0069 types: Requests, messages sent from host to EC that may trigger a direct
0070 response from the EC (explicitly associated with the request), and events
0071 (sometimes also referred to as notifications), sent from EC to host without
0072 being a direct response to a previous request. We may also refer to requests
0073 without response as commands. In general, events need to be enabled via one
0074 of multiple dedicated requests before they are sent by the EC.
0075
0076 See Documentation/driver-api/surface_aggregator/ssh.rst for a
0077 more technical protocol documentation and
0078 Documentation/driver-api/surface_aggregator/internal.rst for an
0079 overview of the internal driver architecture.
