1.. SPDX-License-Identifier: GPL-2.0+
2
3.. |u8| replace:: :c:type:`u8 <u8>`
4.. |u16| replace:: :c:type:`u16 <u16>`
5.. |ssam_cdev_request| replace:: :c:type:`struct ssam_cdev_request <ssam_cdev_request>`
6.. |ssam_cdev_request_flags| replace:: :c:type:`enum ssam_cdev_request_flags <ssam_cdev_request_flags>`
7
8==============================
9User-Space EC Interface (cdev)
10==============================
11
12The ``surface_aggregator_cdev`` module provides a misc-device for the SSAM
13controller to allow for a (more or less) direct connection from user-space to
14the SAM EC. It is intended to be used for development and debugging, and
15therefore should not be used or relied upon in any other way. Note that this
16module is not loaded automatically, but instead must be loaded manually.
17
18The provided interface is accessible through the ``/dev/surface/aggregator``
19device-file. All functionality of this interface is provided via IOCTLs.
20These IOCTLs and their respective input/output parameter structs are defined in
21``include/uapi/linux/surface_aggregator/cdev.h``.
22
23A small python library and scripts for accessing this interface can be found
24at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam.
25
26
27Controller IOCTLs
28=================
29
30The following IOCTLs are provided:
31
32.. flat-table:: Controller IOCTLs
33   :widths: 1 1 1 1 4
34   :header-rows: 1
35
36   * - Type
37     - Number
38     - Direction
39     - Name
40     - Description
41
42   * - ``0xA5``
43     - ``1``
44     - ``WR``
45     - ``REQUEST``
46     - Perform synchronous SAM request.
47
48
49``REQUEST``
50-----------
51
52Defined as ``_IOWR(0xA5, 1, struct ssam_cdev_request)``.
53
54Executes a synchronous SAM request. The request specification is passed in
55as argument of type |ssam_cdev_request|, which is then written to/modified
56by the IOCTL to return status and result of the request.
57
58Request payload data must be allocated separately and is passed in via the
59``payload.data`` and ``payload.length`` members. If a response is required,
60the response buffer must be allocated by the caller and passed in via the
61``response.data`` member. The ``response.length`` member must be set to the
62capacity of this buffer, or if no response is required, zero. Upon
63completion of the request, the call will write the response to the response
64buffer (if its capacity allows it) and overwrite the length field with the
65actual size of the response, in bytes.
66
67Additionally, if the request has a response, this must be indicated via the
68request flags, as is done with in-kernel requests. Request flags can be set
69via the ``flags`` member and the values correspond to the values found in
70|ssam_cdev_request_flags|.
71
72Finally, the status of the request itself is returned in the ``status``
73member (a negative errno value indicating failure). Note that failure
74indication of the IOCTL is separated from failure indication of the request:
75The IOCTL returns a negative status code if anything failed during setup of
76the request (``-EFAULT``) or if the provided argument or any of its fields
77are invalid (``-EINVAL``). In this case, the status value of the request
78argument may be set, providing more detail on what went wrong (e.g.
79``-ENOMEM`` for out-of-memory), but this value may also be zero. The IOCTL
80will return with a zero status code in case the request has been set up,
81submitted, and completed (i.e. handed back to user-space) successfully from
82inside the IOCTL, but the request ``status`` member may still be negative in
83case the actual execution of the request failed after it has been submitted.
84
85A full definition of the argument struct is provided below:
86
87.. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h
88