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

platform/surface: Add Surface Aggregator user-space interface 

Add a misc-device providing user-space access to the Surface Aggregator
EC, mainly intended for debugging, testing, and reverse-engineering.
This interface gives user-space applications the ability to send
requests to the EC and receive the corresponding responses.

The device-file is managed by a pseudo platform-device and corresponding
driver to avoid dependence on the dedicated bus, allowing it to be
loaded in a minimal configuration.

A python library and scripts to access this device can be found at [1].

[1]: https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam



Signed-off-by: default avatarMaximilian Luz <luzmaximilian@gmail.com>
Link: https://lore.kernel.org/r/20201221183959.1186143-9-luzmaximilian@gmail.com


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

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

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



.. |u8| replace:: :c:type:`u8 <u8>`

.. |u16| replace:: :c:type:`u16 <u16>`

.. |ssam_cdev_request| replace:: :c:type:`struct ssam_cdev_request <ssam_cdev_request>`

.. |ssam_cdev_request_flags| replace:: :c:type:`enum ssam_cdev_request_flags <ssam_cdev_request_flags>`



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

User-Space EC Interface (cdev)

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



The ``surface_aggregator_cdev`` module provides a misc-device for the SSAM

controller to allow for a (more or less) direct connection from user-space to

the SAM EC. It is intended to be used for development and debugging, and

therefore should not be used or relied upon in any other way. Note that this

module is not loaded automatically, but instead must be loaded manually.



The provided interface is accessible through the ``/dev/surface/aggregator``

device-file. All functionality of this interface is provided via IOCTLs.

These IOCTLs and their respective input/output parameter structs are defined in

``include/uapi/linux/surface_aggregator/cdev.h``.



A small python library and scripts for accessing this interface can be found

at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam.





Controller IOCTLs

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



The following IOCTLs are provided:



.. flat-table:: Controller IOCTLs

   :widths: 1 1 1 1 4

   :header-rows: 1



   * - Type

     - Number

     - Direction

     - Name

     - Description



   * - ``0xA5``

     - ``1``

     - ``WR``

     - ``REQUEST``

     - Perform synchronous SAM request.





``REQUEST``

-----------



Defined as ``_IOWR(0xA5, 1, struct ssam_cdev_request)``.



Executes a synchronous SAM request. The request specification is passed in

as argument of type |ssam_cdev_request|, which is then written to/modified

by the IOCTL to return status and result of the request.



Request payload data must be allocated separately and is passed in via the

``payload.data`` and ``payload.length`` members. If a response is required,

the response buffer must be allocated by the caller and passed in via the

``response.data`` member. The ``response.length`` member must be set to the

capacity of this buffer, or if no response is required, zero. Upon

completion of the request, the call will write the response to the response

buffer (if its capacity allows it) and overwrite the length field with the

actual size of the response, in bytes.



Additionally, if the request has a response, this must be indicated via the

request flags, as is done with in-kernel requests. Request flags can be set

via the ``flags`` member and the values correspond to the values found in

|ssam_cdev_request_flags|.



Finally, the status of the request itself is returned in the ``status``

member (a negative errno value indicating failure). Note that failure

indication of the IOCTL is separated from failure indication of the request:

The IOCTL returns a negative status code if anything failed during setup of

the request (``-EFAULT``) or if the provided argument or any of its fields

are invalid (``-EINVAL``). In this case, the status value of the request

argument may be set, providing more detail on what went wrong (e.g.

``-ENOMEM`` for out-of-memory), but this value may also be zero. The IOCTL

will return with a zero status code in case the request has been set up,

submitted, and completed (i.e. handed back to user-space) successfully from

inside the IOCTL, but the request ``status`` member may still be negative in

case the actual execution of the request failed after it has been submitted.



A full definition of the argument struct is provided below:



.. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h

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

+11 −1
Original line number Diff line number Diff line
@@ -7,4 +7,14 @@ Client Driver Documentation 
This is the documentation for client drivers themselves. Refer to

:doc:`../client` for documentation on how to write client drivers.



.. Place documentation for individual client drivers here.
 
.. toctree::

   :maxdepth: 1



   cdev



.. only::  subproject and html



   Indices

   =======



   * :ref:`genindex`

Documentation/userspace-api/ioctl/ioctl-number.rst

+2 −0
Original line number Diff line number Diff line
@@ -324,6 +324,8 @@ Code Seq# Include File Comments 
0xA3  90-9F  linux/dtlk.h

0xA4  00-1F  uapi/linux/tee.h                                        Generic TEE subsystem

0xA4  00-1F  uapi/asm/sgx.h                                          <mailto:linux-sgx@vger.kernel.org>

0xA5  01     linux/surface_aggregator/cdev.h                         Microsoft Surface Platform System Aggregator

                                                                     <mailto:luzmaximilian@gmail.com>

0xAA  00-3F  linux/uapi/linux/userfaultfd.h

0xAB  00-1F  linux/nbd.h

0xAC  00-1F  linux/raw.h

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_aggregator_cdev.c

F:	include/linux/surface_aggregator/

F:	include/uapi/linux/surface_aggregator/









MICROTEK X6 SCANNER









M:	Oliver Neukum <oliver@neukum.org>
































drivers/platform/surface/Kconfig



+17
−0






























Original line number
Diff line number
Diff line







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







	  This driver provides support for ACPI operation









	  region of the Surface 3 battery platform driver.



















config SURFACE_AGGREGATOR_CDEV









	tristate "Surface System Aggregator Module User-Space Interface"









	depends on SURFACE_AGGREGATOR









	help









	  Provides a misc-device interface to the Surface System Aggregator









	  Module (SSAM) controller.



















	  This option provides a module (called surface_aggregator_cdev), that,









	  when loaded, will add a client device (and its respective driver) to









	  the SSAM controller. Said client device manages a misc-device









	  interface (/dev/surface/aggregator), which can be used by user-space









	  tools to directly communicate with the SSAM EC by sending requests and









	  receiving the corresponding responses.



















	  The provided interface is intended for debugging and development only,









	  and should not be used otherwise.



















config SURFACE_GPE









	tristate "Surface GPE/Lid Support Driver"









	depends on DMI