1.. SPDX-License-Identifier: GPL-2.0+
2
3.. |ssam_cdev_request| replace:: :c:type:`struct ssam_cdev_request <ssam_cdev_request>`
4.. |ssam_cdev_request_flags| replace:: :c:type:`enum ssam_cdev_request_flags <ssam_cdev_request_flags>`
5.. |ssam_cdev_event| replace:: :c:type:`struct ssam_cdev_event <ssam_cdev_event>`
6
7==============================
8User-Space EC Interface (cdev)
9==============================
10
11The ``surface_aggregator_cdev`` module provides a misc-device for the SSAM
12controller to allow for a (more or less) direct connection from user-space to
13the SAM EC. It is intended to be used for development and debugging, and
14therefore should not be used or relied upon in any other way. Note that this
15module is not loaded automatically, but instead must be loaded manually.
16
17The provided interface is accessible through the ``/dev/surface/aggregator``
18device-file. All functionality of this interface is provided via IOCTLs.
19These IOCTLs and their respective input/output parameter structs are defined in
20``include/uapi/linux/surface_aggregator/cdev.h``.
21
22A small python library and scripts for accessing this interface can be found
23at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam.
24
25.. contents::
26
27
28Receiving Events
29================
30
31Events can be received by reading from the device-file. The are represented by
32the |ssam_cdev_event| datatype.
33
34Before events are available to be read, however, the desired notifiers must be
35registered via the ``SSAM_CDEV_NOTIF_REGISTER`` IOCTL. Notifiers are, in
36essence, callbacks, called when the EC sends an event. They are, in this
37interface, associated with a specific target category and device-file-instance.
38They forward any event of this category to the buffer of the corresponding
39instance, from which it can then be read.
40
41Notifiers themselves do not enable events on the EC. Thus, it may additionally
42be necessary to enable events via the ``SSAM_CDEV_EVENT_ENABLE`` IOCTL. While
43notifiers work per-client (i.e. per-device-file-instance), events are enabled
44globally, for the EC and all of its clients (regardless of userspace or
45non-userspace). The ``SSAM_CDEV_EVENT_ENABLE`` and ``SSAM_CDEV_EVENT_DISABLE``
46IOCTLs take care of reference counting the events, such that an event is
47enabled as long as there is a client that has requested it.
48
49Note that enabled events are not automatically disabled once the client
50instance is closed. Therefore any client process (or group of processes) should
51balance their event enable calls with the corresponding event disable calls. It
52is, however, perfectly valid to enable and disable events on different client
53instances. For example, it is valid to set up notifiers and read events on
54client instance ``A``, enable those events on instance ``B`` (note that these
55will also be received by A since events are enabled/disabled globally), and
56after no more events are desired, disable the previously enabled events via
57instance ``C``.
58
59
60Controller IOCTLs
61=================
62
63The following IOCTLs are provided:
64
65.. flat-table:: Controller IOCTLs
66   :widths: 1 1 1 1 4
67   :header-rows: 1
68
69   * - Type
70     - Number
71     - Direction
72     - Name
73     - Description
74
75   * - ``0xA5``
76     - ``1``
77     - ``WR``
78     - ``REQUEST``
79     - Perform synchronous SAM request.
80
81   * - ``0xA5``
82     - ``2``
83     - ``W``
84     - ``NOTIF_REGISTER``
85     - Register event notifier.
86
87   * - ``0xA5``
88     - ``3``
89     - ``W``
90     - ``NOTIF_UNREGISTER``
91     - Unregister event notifier.
92
93   * - ``0xA5``
94     - ``4``
95     - ``W``
96     - ``EVENT_ENABLE``
97     - Enable event source.
98
99   * - ``0xA5``
100     - ``5``
101     - ``W``
102     - ``EVENT_DISABLE``
103     - Disable event source.
104
105
106``SSAM_CDEV_REQUEST``
107---------------------
108
109Defined as ``_IOWR(0xA5, 1, struct ssam_cdev_request)``.
110
111Executes a synchronous SAM request. The request specification is passed in
112as argument of type |ssam_cdev_request|, which is then written to/modified
113by the IOCTL to return status and result of the request.
114
115Request payload data must be allocated separately and is passed in via the
116``payload.data`` and ``payload.length`` members. If a response is required,
117the response buffer must be allocated by the caller and passed in via the
118``response.data`` member. The ``response.length`` member must be set to the
119capacity of this buffer, or if no response is required, zero. Upon
120completion of the request, the call will write the response to the response
121buffer (if its capacity allows it) and overwrite the length field with the
122actual size of the response, in bytes.
123
124Additionally, if the request has a response, this must be indicated via the
125request flags, as is done with in-kernel requests. Request flags can be set
126via the ``flags`` member and the values correspond to the values found in
127|ssam_cdev_request_flags|.
128
129Finally, the status of the request itself is returned in the ``status``
130member (a negative errno value indicating failure). Note that failure
131indication of the IOCTL is separated from failure indication of the request:
132The IOCTL returns a negative status code if anything failed during setup of
133the request (``-EFAULT``) or if the provided argument or any of its fields
134are invalid (``-EINVAL``). In this case, the status value of the request
135argument may be set, providing more detail on what went wrong (e.g.
136``-ENOMEM`` for out-of-memory), but this value may also be zero. The IOCTL
137will return with a zero status code in case the request has been set up,
138submitted, and completed (i.e. handed back to user-space) successfully from
139inside the IOCTL, but the request ``status`` member may still be negative in
140case the actual execution of the request failed after it has been submitted.
141
142A full definition of the argument struct is provided below.
143
144``SSAM_CDEV_NOTIF_REGISTER``
145----------------------------
146
147Defined as ``_IOW(0xA5, 2, struct ssam_cdev_notifier_desc)``.
148
149Register a notifier for the event target category specified in the given
150notifier description with the specified priority. Notifiers registration is
151required to receive events, but does not enable events themselves. After a
152notifier for a specific target category has been registered, all events of that
153category will be forwarded to the userspace client and can then be read from
154the device file instance. Note that events may have to be enabled, e.g. via the
155``SSAM_CDEV_EVENT_ENABLE`` IOCTL, before the EC will send them.
156
157Only one notifier can be registered per target category and client instance. If
158a notifier has already been registered, this IOCTL will fail with ``-EEXIST``.
159
160Notifiers will automatically be removed when the device file instance is
161closed.
162
163``SSAM_CDEV_NOTIF_UNREGISTER``
164------------------------------
165
166Defined as ``_IOW(0xA5, 3, struct ssam_cdev_notifier_desc)``.
167
168Unregisters the notifier associated with the specified target category. The
169priority field will be ignored by this IOCTL. If no notifier has been
170registered for this client instance and the given category, this IOCTL will
171fail with ``-ENOENT``.
172
173``SSAM_CDEV_EVENT_ENABLE``
174--------------------------
175
176Defined as ``_IOW(0xA5, 4, struct ssam_cdev_event_desc)``.
177
178Enable the event associated with the given event descriptor.
179
180Note that this call will not register a notifier itself, it will only enable
181events on the controller. If you want to receive events by reading from the
182device file, you will need to register the corresponding notifier(s) on that
183instance.
184
185Events are not automatically disabled when the device file is closed. This must
186be done manually, via a call to the ``SSAM_CDEV_EVENT_DISABLE`` IOCTL.
187
188``SSAM_CDEV_EVENT_DISABLE``
189---------------------------
190
191Defined as ``_IOW(0xA5, 5, struct ssam_cdev_event_desc)``.
192
193Disable the event associated with the given event descriptor.
194
195Note that this will not unregister any notifiers. Events may still be received
196and forwarded to user-space after this call. The only safe way of stopping
197events from being received is unregistering all previously registered
198notifiers.
199
200
201Structures and Enums
202====================
203
204.. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h
205