80 lines · plain
1.. SPDX-License-Identifier: GPL-2.0+2 3========4Overview5========6 7The Surface/System Aggregator Module (SAM, SSAM) is an (arguably *the*)8embedded controller (EC) on Microsoft Surface devices. It has been originally9introduced on 4th generation devices (Surface Pro 4, Surface Book 1), but10its responsibilities and feature-set have since been expanded significantly11with the following generations.12 13 14Features and Integration15========================16 17Not much is currently known about SAM on 4th generation devices (Surface Pro184, Surface Book 1), due to the use of a different communication interface19between host and EC (as detailed below). On 5th (Surface Pro 2017, Surface20Book 2, Surface Laptop 1) and later generation devices, SAM is responsible21for providing battery information (both current status and static values,22such as maximum capacity etc.), as well as an assortment of temperature23sensors (e.g. skin temperature) and cooling/performance-mode setting to the24host. On the Surface Book 2, specifically, it additionally provides an25interface for properly handling clipboard detachment (i.e. separating the26display part from the keyboard part of the device), on the Surface Laptop 127and 2 it is required for keyboard HID input. This HID subsystem has been28restructured for 7th generation devices and on those, specifically Surface29Laptop 3 and Surface Book 3, is responsible for all major HID input (i.e.30keyboard and touchpad).31 32While features have not changed much on a coarse level since the 5th33generation, internal interfaces have undergone some rather large changes. On345th and 6th generation devices, both battery and temperature information is35exposed to ACPI via a shim driver (referred to as Surface ACPI Notify, or36SAN), translating ACPI generic serial bus write-/read-accesses to SAM37requests. On 7th generation devices, this additional layer is gone and these38devices require a driver hooking directly into the SAM interface. Equally,39on newer generations, less devices are declared in ACPI, making them a bit40harder to discover and requiring us to hard-code a sort of device registry.41Due to this, a SSAM bus and subsystem with client devices42(:c:type:`struct ssam_device <ssam_device>`) has been implemented.43 44 45Communication46=============47 48The type of communication interface between host and EC depends on the49generation of the Surface device. On 4th generation devices, host and EC50communicate via HID, specifically using a HID-over-I2C device, whereas on515th and later generations, communication takes place via a USART serial52device. In accordance to the drivers found on other operating systems, we53refer to the serial device and its driver as Surface Serial Hub (SSH). When54needed, we differentiate between both types of SAM by referring to them as55SAM-over-SSH and SAM-over-HID.56 57Currently, this subsystem only supports SAM-over-SSH. The SSH communication58interface is described in more detail below. The HID interface has not been59reverse engineered yet and it is, at the moment, unclear how many (and60which) concepts of the SSH interface detailed below can be transferred to61it.62 63Surface Serial Hub64------------------65 66As already elaborated above, the Surface Serial Hub (SSH) is the67communication interface for SAM on 5th- and all later-generation Surface68devices. On the highest level, communication can be separated into two main69types: Requests, messages sent from host to EC that may trigger a direct70response from the EC (explicitly associated with the request), and events71(sometimes also referred to as notifications), sent from EC to host without72being a direct response to a previous request. We may also refer to requests73without response as commands. In general, events need to be enabled via one74of multiple dedicated requests before they are sent by the EC.75 76See Documentation/driver-api/surface_aggregator/ssh.rst for a77more technical protocol documentation and78Documentation/driver-api/surface_aggregator/internal.rst for an79overview of the internal driver architecture.80