platform/surface: Add Surface Aggregator subsystem
Add Surface System Aggregator Module core and Surface Serial Hub driver,
required for the embedded controller found on Microsoft Surface devices.
The Surface System Aggregator Module (SSAM, SAM or Surface Aggregator)
is an embedded controller (EC) found on 4th and later generation
Microsoft Surface devices, with the exception of the Surface Go series.
This EC provides various functionality, depending on the device in
question. This can include battery status and thermal reporting (5th and
later generations), but also HID keyboard (6th+) and touchpad input
(7th+) on Surface Laptop and Surface Book 3 series devices.
This patch provides the basic necessities for communication with the SAM
EC on 5th and later generation devices. On these devices, the EC
provides an interface that acts as serial device, called the Surface
Serial Hub (SSH). 4th generation devices, on which the EC interface is
provided via an HID-over-I2C device, are not supported by this patch.
Specifically, this patch adds a driver for the SSH device (device HID
MSHW0084 in ACPI), as well as a controller structure and associated API.
This represents the functional core of the Surface Aggregator kernel
subsystem, introduced with this patch, and will be expanded upon in
subsequent commits.
The SSH driver acts as the main attachment point for this subsystem and
sets-up and manages the controller structure. The controller in turn
provides a basic communication interface, allowing to send requests from
host to EC and receiving the corresponding responses, as well as
managing and receiving events, sent from EC to host. It is structured
into multiple layers, with the top layer presenting the API used by
other kernel drivers and the lower layers modeled after the serial
protocol used for communication.
Said other drivers are then responsible for providing the (Surface model
specific) functionality accessible through the EC (e.g. battery status
reporting, thermal information, ...) via said controller structure and
API, and will be added in future commits.
Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20201221183959.1186143-2-luzmaximilian@gmail.com
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2020-12-21 18:39:51 +00:00
|
|
|
# SPDX-License-Identifier: GPL-2.0+
|
2022-06-24 20:58:00 +00:00
|
|
|
# Copyright (C) 2019-2022 Maximilian Luz <luzmaximilian@gmail.com>
|
platform/surface: Add Surface Aggregator subsystem
Add Surface System Aggregator Module core and Surface Serial Hub driver,
required for the embedded controller found on Microsoft Surface devices.
The Surface System Aggregator Module (SSAM, SAM or Surface Aggregator)
is an embedded controller (EC) found on 4th and later generation
Microsoft Surface devices, with the exception of the Surface Go series.
This EC provides various functionality, depending on the device in
question. This can include battery status and thermal reporting (5th and
later generations), but also HID keyboard (6th+) and touchpad input
(7th+) on Surface Laptop and Surface Book 3 series devices.
This patch provides the basic necessities for communication with the SAM
EC on 5th and later generation devices. On these devices, the EC
provides an interface that acts as serial device, called the Surface
Serial Hub (SSH). 4th generation devices, on which the EC interface is
provided via an HID-over-I2C device, are not supported by this patch.
Specifically, this patch adds a driver for the SSH device (device HID
MSHW0084 in ACPI), as well as a controller structure and associated API.
This represents the functional core of the Surface Aggregator kernel
subsystem, introduced with this patch, and will be expanded upon in
subsequent commits.
The SSH driver acts as the main attachment point for this subsystem and
sets-up and manages the controller structure. The controller in turn
provides a basic communication interface, allowing to send requests from
host to EC and receiving the corresponding responses, as well as
managing and receiving events, sent from EC to host. It is structured
into multiple layers, with the top layer presenting the API used by
other kernel drivers and the lower layers modeled after the serial
protocol used for communication.
Said other drivers are then responsible for providing the (Surface model
specific) functionality accessible through the EC (e.g. battery status
reporting, thermal information, ...) via said controller structure and
API, and will be added in future commits.
Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20201221183959.1186143-2-luzmaximilian@gmail.com
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2020-12-21 18:39:51 +00:00
|
|
|
|
|
|
|
|
menuconfig SURFACE_AGGREGATOR
|
|
|
|
|
tristate "Microsoft Surface System Aggregator Module Subsystem and Drivers"
|
|
|
|
|
depends on SERIAL_DEV_BUS
|
2023-05-15 05:49:09 +00:00
|
|
|
depends on ACPI && !RISCV
|
2023-12-19 13:11:54 +00:00
|
|
|
select CRC_ITU_T
|
platform/surface: Add Surface Aggregator subsystem
Add Surface System Aggregator Module core and Surface Serial Hub driver,
required for the embedded controller found on Microsoft Surface devices.
The Surface System Aggregator Module (SSAM, SAM or Surface Aggregator)
is an embedded controller (EC) found on 4th and later generation
Microsoft Surface devices, with the exception of the Surface Go series.
This EC provides various functionality, depending on the device in
question. This can include battery status and thermal reporting (5th and
later generations), but also HID keyboard (6th+) and touchpad input
(7th+) on Surface Laptop and Surface Book 3 series devices.
This patch provides the basic necessities for communication with the SAM
EC on 5th and later generation devices. On these devices, the EC
provides an interface that acts as serial device, called the Surface
Serial Hub (SSH). 4th generation devices, on which the EC interface is
provided via an HID-over-I2C device, are not supported by this patch.
Specifically, this patch adds a driver for the SSH device (device HID
MSHW0084 in ACPI), as well as a controller structure and associated API.
This represents the functional core of the Surface Aggregator kernel
subsystem, introduced with this patch, and will be expanded upon in
subsequent commits.
The SSH driver acts as the main attachment point for this subsystem and
sets-up and manages the controller structure. The controller in turn
provides a basic communication interface, allowing to send requests from
host to EC and receiving the corresponding responses, as well as
managing and receiving events, sent from EC to host. It is structured
into multiple layers, with the top layer presenting the API used by
other kernel drivers and the lower layers modeled after the serial
protocol used for communication.
Said other drivers are then responsible for providing the (Surface model
specific) functionality accessible through the EC (e.g. battery status
reporting, thermal information, ...) via said controller structure and
API, and will be added in future commits.
Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20201221183959.1186143-2-luzmaximilian@gmail.com
Signed-off-by: Hans de Goede <hdegoede@redhat.com>
2020-12-21 18:39:51 +00:00
|
|
|
help
|
|
|
|
|
The Surface System Aggregator Module (Surface SAM or SSAM) is an
|
|
|
|
|
embedded controller (EC) found on 5th- and later-generation Microsoft
|
|
|
|
|
Surface devices (i.e. Surface Pro 5, Surface Book 2, Surface Laptop,
|
|
|
|
|
and newer, with exception of Surface Go series devices).
|
|
|
|
|
|
|
|
|
|
Depending on the device in question, this EC provides varying
|
|
|
|
|
functionality, including:
|
|
|
|
|
- EC access from ACPI via Surface ACPI Notify (5th- and 6th-generation)
|
|
|
|
|
- battery status information (all devices)
|
|
|
|
|
- thermal sensor access (all devices)
|
|
|
|
|
- performance mode / cooling mode control (all devices)
|
|
|
|
|
- clipboard detachment system control (Surface Book 2 and 3)
|
|
|
|
|
- HID / keyboard input (Surface Laptops, Surface Book 3)
|
|
|
|
|
|
|
|
|
|
This option controls whether the Surface SAM subsystem core will be
|
|
|
|
|
built. This includes a driver for the Surface Serial Hub (SSH), which
|
|
|
|
|
is the device responsible for the communication with the EC, and a
|
|
|
|
|
basic kernel interface exposing the EC functionality to other client
|
|
|
|
|
drivers, i.e. allowing them to make requests to the EC and receive
|
|
|
|
|
events from it. Selecting this option alone will not provide any
|
|
|
|
|
client drivers and therefore no functionality beyond the in-kernel
|
|
|
|
|
interface. Said functionality is the responsibility of the respective
|
|
|
|
|
client drivers.
|
|
|
|
|
|
|
|
|
|
Note: While 4th-generation Surface devices also make use of a SAM EC,
|
|
|
|
|
due to a difference in the communication interface of the controller,
|
|
|
|
|
only 5th and later generations are currently supported. Specifically,
|
|
|
|
|
devices using SAM-over-SSH are supported, whereas devices using
|
|
|
|
|
SAM-over-HID, which is used on the 4th generation, are currently not
|
|
|
|
|
supported.
|
|
|
|
|
|
|
|
|
|
Choose m if you want to build the SAM subsystem core and SSH driver as
|
|
|
|
|
module, y if you want to build it into the kernel and n if you don't
|
|
|
|
|
want it at all.
|
2020-12-21 18:39:55 +00:00
|
|
|
|
2020-12-21 18:39:56 +00:00
|
|
|
config SURFACE_AGGREGATOR_BUS
|
|
|
|
|
bool "Surface System Aggregator Module Bus"
|
|
|
|
|
depends on SURFACE_AGGREGATOR
|
|
|
|
|
default y
|
|
|
|
|
help
|
|
|
|
|
Expands the Surface System Aggregator Module (SSAM) core driver by
|
|
|
|
|
providing a dedicated bus and client-device type.
|
|
|
|
|
|
|
|
|
|
This bus and device type are intended to provide and simplify support
|
|
|
|
|
for non-platform and non-ACPI SSAM devices, i.e. SSAM devices that are
|
|
|
|
|
not auto-detectable via the conventional means (e.g. ACPI).
|
|
|
|
|
|
2020-12-21 18:39:55 +00:00
|
|
|
config SURFACE_AGGREGATOR_ERROR_INJECTION
|
|
|
|
|
bool "Surface System Aggregator Module Error Injection Capabilities"
|
|
|
|
|
depends on SURFACE_AGGREGATOR
|
|
|
|
|
depends on FUNCTION_ERROR_INJECTION
|
|
|
|
|
help
|
|
|
|
|
Provides error-injection capabilities for the Surface System
|
|
|
|
|
Aggregator Module subsystem and Surface Serial Hub driver.
|
|
|
|
|
|
|
|
|
|
Specifically, exports error injection hooks to be used with the
|
|
|
|
|
kernel's function error injection capabilities to simulate underlying
|
|
|
|
|
transport and communication problems, such as invalid data sent to or
|
|
|
|
|
received from the EC, dropped data, and communication timeouts.
|
|
|
|
|
Intended for development and debugging.
|