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

   1 .. SPDX-License-Identifier: GPL-2.0+
   2
   3 .. |san_client_link| replace:: :c:func:`san_client_link`
   4 .. |san_dgpu_notifier_register| replace:: :c:func:`san_dgpu_notifier_register`
   5 .. |san_dgpu_notifier_unregister| replace:: :c:func:`san_dgpu_notifier_unregister`
   6
   7 ===================
   8 Surface ACPI Notify
   9 ===================
  10
  11 The Surface ACPI Notify (SAN) device provides the bridge between ACPI and
  12 SAM controller. Specifically, ACPI code can execute requests and handle
  13 battery and thermal events via this interface. In addition to this, events
  14 relating to the discrete GPU (dGPU) of the Surface Book 2 can be sent from
  15 ACPI code (note: the Surface Book 3 uses a different method for this). The
  16 only currently known event sent via this interface is a dGPU power-on
  17 notification. While this driver handles the former part internally, it only
  18 relays the dGPU events to any other driver interested via its public API and
  19 does not handle them.
  20
  21 The public interface of this driver is split into two parts: Client
  22 registration and notifier-block registration.
  23
  24 A client to the SAN interface can be linked as consumer to the SAN device
  25 via |san_client_link|. This can be used to ensure that the a client
  26 receiving dGPU events does not miss any events due to the SAN interface not
  27 being set up as this forces the client driver to unbind once the SAN driver
  28 is unbound.
  29
  30 Notifier-blocks can be registered by any device for as long as the module is
  31 loaded, regardless of being linked as client or not. Registration is done
  32 with |san_dgpu_notifier_register|. If the notifier is not needed any more, it
  33 should be unregistered via |san_dgpu_notifier_unregister|.
  34
  35 Consult the API documentation below for more details.
  36
  37
  38 API Documentation
  39 =================
  40
  41 .. kernel-doc:: include/linux/surface_acpi_notify.h
  42
  43 .. kernel-doc:: drivers/platform/surface/surface_acpi_notify.c
  44     :export: