Commit fc00bc8a authored by Maximilian Luz's avatar Maximilian Luz Committed by Hans de Goede
Browse files

platform/surface: Add Surface ACPI Notify driver 



The Surface ACPI Notify (SAN) device provides an ACPI interface to the
Surface Aggregator EC, specifically the Surface Serial Hub interface.
This interface allows EC requests to be made from ACPI code and can
convert a subset of EC events back to ACPI notifications.

Specifically, this interface provides a GenericSerialBus operation
region ACPI code can execute a request by writing the request command
data and payload to this operation region and reading back the
corresponding response via a write-then-read operation. Furthermore,
this interface provides a _DSM method to be called when certain events
from the EC have been received, essentially turning them into ACPI
notifications.

The driver provided in this commit essentially takes care of translating
the request data written to the operation region, executing the request,
waiting for it to finish, and finally writing and translating back the
response (if the request has one). Furthermore, this driver takes care
of enabling the events handled via ACPI _DSM calls. Lastly, this driver
also exposes an interface providing discrete GPU (dGPU) power-on
notifications on the Surface Book 2, which are also received via the
operation region interface (but not handled by the SAN driver directly),
making them accessible to other drivers (such as a dGPU hot-plug driver
that may be added later on).

On 5th and 6th generation Surface devices (Surface Pro 5/2017, Pro 6,
Book 2, Laptop 1 and 2), the SAN interface provides full battery and
thermal subsystem access, as well as other EC based functionality. On
those models, battery and thermal sensor devices are implemented as
standard ACPI devices of that type, however, forward ACPI calls to the
corresponding Surface Aggregator EC request via the SAN interface and
receive corresponding notifications (e.g. battery information change)
from it. This interface is therefore required to provide said
functionality on those devices.

Signed-off-by: default avatarMaximilian Luz <luzmaximilian@gmail.com>
Reviewed-by: default avatarHans de Goede <hdegoede@redhat.com>
Link: https://lore.kernel.org/r/20201221183959.1186143-10-luzmaximilian@gmail.com


Signed-off-by: default avatarHans de Goede <hdegoede@redhat.com>
parent 178f6ab7

Documentation/driver-api/surface_aggregator/clients/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -11,6 +11,7 @@ This is the documentation for client drivers themselves. Refer to 
   :maxdepth: 1



   cdev

   san



.. only::  subproject and html

Documentation/driver-api/surface_aggregator/clients/san.rst

0 → 100644
+44 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0+



.. |san_client_link| replace:: :c:func:`san_client_link`

.. |san_dgpu_notifier_register| replace:: :c:func:`san_dgpu_notifier_register`

.. |san_dgpu_notifier_unregister| replace:: :c:func:`san_dgpu_notifier_unregister`



===================

Surface ACPI Notify

===================



The Surface ACPI Notify (SAN) device provides the bridge between ACPI and

SAM controller. Specifically, ACPI code can execute requests and handle

battery and thermal events via this interface. In addition to this, events

relating to the discrete GPU (dGPU) of the Surface Book 2 can be sent from

ACPI code (note: the Surface Book 3 uses a different method for this). The

only currently known event sent via this interface is a dGPU power-on

notification. While this driver handles the former part internally, it only

relays the dGPU events to any other driver interested via its public API and

does not handle them.



The public interface of this driver is split into two parts: Client

registration and notifier-block registration.



A client to the SAN interface can be linked as consumer to the SAN device

via |san_client_link|. This can be used to ensure that the a client

receiving dGPU events does not miss any events due to the SAN interface not

being set up as this forces the client driver to unbind once the SAN driver

is unbound.



Notifier-blocks can be registered by any device for as long as the module is

loaded, regardless of being linked as client or not. Registration is done

with |san_dgpu_notifier_register|. If the notifier is not needed any more, it

should be unregistered via |san_dgpu_notifier_unregister|.



Consult the API documentation below for more details.





API Documentation

=================



.. kernel-doc:: include/linux/surface_acpi_notify.h



.. kernel-doc:: drivers/platform/surface/surface_acpi_notify.c

    :export:

MAINTAINERS

+2 −0
Original line number Diff line number Diff line
@@ -11820,7 +11820,9 @@ W: https://github.com/linux-surface/surface-aggregator-module 
C:	irc://chat.freenode.net/##linux-surface

F:	Documentation/driver-api/surface_aggregator/

F:	drivers/platform/surface/aggregator/

F:	drivers/platform/surface/surface_acpi_notify.c

F:	drivers/platform/surface/surface_aggregator_cdev.c

F:	include/linux/surface_acpi_notify.h

F:	include/linux/surface_aggregator/

F:	include/uapi/linux/surface_aggregator/
































drivers/platform/surface/Kconfig



+19
−0






























Original line number
Diff line number
Diff line







@@ -41,6 +41,25 @@ config SURFACE_3_POWER_OPREGION







	  This driver provides support for ACPI operation









	  region of the Surface 3 battery platform driver.



















config SURFACE_ACPI_NOTIFY









	tristate "Surface ACPI Notify Driver"









	depends on SURFACE_AGGREGATOR









	help









	  Surface ACPI Notify (SAN) driver for Microsoft Surface devices.



















	  This driver provides support for the ACPI interface (called SAN) of









	  the Surface System Aggregator Module (SSAM) EC. This interface is used









	  on 5th- and 6th-generation Microsoft Surface devices (including









	  Surface Pro 5 and 6, Surface Book 2, Surface Laptops 1 and 2, and in









	  reduced functionality on the Surface Laptop 3) to execute SSAM









	  requests directly from ACPI code, as well as receive SSAM events and









	  turn them into ACPI notifications. It essentially acts as a









	  translation layer between the SSAM controller and ACPI.



















	  Specifically, this driver may be needed for battery status reporting,









	  thermal sensor access, and real-time clock information, depending on









	  the Surface device in question.



















config SURFACE_AGGREGATOR_CDEV









	tristate "Surface System Aggregator Module User-Space Interface"









	depends on SURFACE_AGGREGATOR
































drivers/platform/surface/Makefile



+1
−0






























Original line number
Diff line number
Diff line







@@ -7,6 +7,7 @@







obj-$(CONFIG_SURFACE3_WMI)		+= surface3-wmi.o









obj-$(CONFIG_SURFACE_3_BUTTON)		+= surface3_button.o









obj-$(CONFIG_SURFACE_3_POWER_OPREGION)	+= surface3_power.o









obj-$(CONFIG_SURFACE_ACPI_NOTIFY)	+= surface_acpi_notify.o









obj-$(CONFIG_SURFACE_AGGREGATOR)	+= aggregator/









obj-$(CONFIG_SURFACE_AGGREGATOR_CDEV)	+= surface_aggregator_cdev.o









obj-$(CONFIG_SURFACE_GPE)		+= surface_gpe.o