Documentation/driver-api/surface_aggregator/overview.rst

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 ========
   4 Overview
   5 ========
   6
   7 The Surface/System Aggregator Module (SAM, SSAM) is an (arguably *the*)
   8 embedded controller (EC) on Microsoft Surface devices. It has been originally
   9 introduced on 4th generation devices (Surface Pro 4, Surface Book 1), but
  10 its responsibilities and feature-set have since been expanded significantly
  11 with the following generations.
  12
  13
  14 Features and Integration
  15 ========================
  16
  17 Not much is currently known about SAM on 4th generation devices (Surface Pro
  18 4, Surface Book 1), due to the use of a different communication interface
  19 between host and EC (as detailed below). On 5th (Surface Pro 2017, Surface
  20 Book 2, Surface Laptop 1) and later generation devices, SAM is responsible
  21 for providing battery information (both current status and static values,
  22 such as maximum capacity etc.), as well as an assortment of temperature
  23 sensors (e.g. skin temperature) and cooling/performance-mode setting to the
  24 host. On the Surface Book 2, specifically, it additionally provides an
  25 interface for properly handling clipboard detachment (i.e. separating the
  26 display part from the keyboard part of the device), on the Surface Laptop 1
  27 and 2 it is required for keyboard HID input. This HID subsystem has been
  28 restructured for 7th generation devices and on those, specifically Surface
  29 Laptop 3 and Surface Book 3, is responsible for all major HID input (i.e.
  30 keyboard and touchpad).
  31
  32 While features have not changed much on a coarse level since the 5th
  33 generation, internal interfaces have undergone some rather large changes. On
  34 5th and 6th generation devices, both battery and temperature information is
  35 exposed to ACPI via a shim driver (referred to as Surface ACPI Notify, or
  36 SAN), translating ACPI generic serial bus write-/read-accesses to SAM
  37 requests. On 7th generation devices, this additional layer is gone and these
  38 devices require a driver hooking directly into the SAM interface. Equally,
  39 on newer generations, less devices are declared in ACPI, making them a bit
  40 harder to discover and requiring us to hard-code a sort of device registry.
  41 Due to this, a SSAM bus and subsystem with client devices
  42 (:c:type:`struct ssam_device <ssam_device>`) has been implemented.
  43
  44
  45 Communication
  46 =============
  47
  48 The type of communication interface between host and EC depends on the
  49 generation of the Surface device. On 4th generation devices, host and EC
  50 communicate via HID, specifically using a HID-over-I2C device, whereas on
  51 5th and later generations, communication takes place via a USART serial
  52 device. In accordance to the drivers found on other operating systems, we
  53 refer to the serial device and its driver as Surface Serial Hub (SSH). When
  54 needed, we differentiate between both types of SAM by referring to them as
  55 SAM-over-SSH and SAM-over-HID.
  56
  57 Currently, this subsystem only supports SAM-over-SSH. The SSH communication
  58 interface is described in more detail below. The HID interface has not been
  59 reverse engineered yet and it is, at the moment, unclear how many (and
  60 which) concepts of the SSH interface detailed below can be transferred to
  61 it.
  62
  63 Surface Serial Hub
  64 ------------------
  65
  66 As already elaborated above, the Surface Serial Hub (SSH) is the
  67 communication interface for SAM on 5th- and all later-generation Surface
  68 devices. On the highest level, communication can be separated into two main
  69 types: Requests, messages sent from host to EC that may trigger a direct
  70 response from the EC (explicitly associated with the request), and events
  71 (sometimes also referred to as notifications), sent from EC to host without
  72 being a direct response to a previous request. We may also refer to requests
  73 without response as commands. In general, events need to be enabled via one
  74 of multiple dedicated requests before they are sent by the EC.
  75
  76 See Documentation/driver-api/surface_aggregator/ssh.rst for a
  77 more technical protocol documentation and
  78 Documentation/driver-api/surface_aggregator/internal.rst for an
  79 overview of the internal driver architecture.