surface_aggregator/clients/cdev.rst

1 .. SPDX-License-Identifier: GPL-2.0+
8 User-Space EC Interface (cdev)
11 The ``surface_aggregator_cdev`` module provides a misc-device for the SSAM
12 controller to allow for a (more or less) direct connection from user-space to
15 module is not loaded automatically, but instead must be loaded manually.
18 device-file. All functionality of this interface is provided via IOCTLs.
23 at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam.
31 Events can be received by reading from the device-file. The are represented by
37 interface, associated with a specific target category and device-file-instance.
39 instance, from which it can then be read.
43 notifiers work per-client (i.e. per-device-file-instance), events are enabled
45 non-userspace). The ``SSAM_CDEV_EVENT_ENABLE`` and ``SSAM_CDEV_EVENT_DISABLE``
50 instance is closed. Therefore any client process (or group of processes) should
54 client instance ``A``, enable those events on instance ``B`` (note that these
57 instance ``C``.
65 .. flat-table:: Controller IOCTLs
67    :header-rows: 1
69    * - Type
70      - Number
71      - Direction
72      - Name
73      - Description
75    * - ``0xA5``
76      - ``1``
77      - ``WR``
78      - ``REQUEST``
79      - Perform synchronous SAM request.
81    * - ``0xA5``
82      - ``2``
83      - ``W``
84      - ``NOTIF_REGISTER``
85      - Register event notifier.
87    * - ``0xA5``
88      - ``3``
89      - ``W``
90      - ``NOTIF_UNREGISTER``
91      - Unregister event notifier.
93    * - ``0xA5``
94      - ``4``
95      - ``W``
96      - ``EVENT_ENABLE``
97      - Enable event source.
99    * - ``0xA5``
100      - ``5``
101      - ``W``
102      - ``EVENT_DISABLE``
103      - Disable event source.
107 ---------------------
125 request flags, as is done with in-kernel requests. Request flags can be set
133 the request (``-EFAULT``) or if the provided argument or any of its fields
134 are invalid (``-EINVAL``). In this case, the status value of the request
136 ``-ENOMEM`` for out-of-memory), but this value may also be zero. The IOCTL
138 submitted, and completed (i.e. handed back to user-space) successfully from
145 ----------------------------
154 the device file instance. Note that events may have to be enabled, e.g. via the
157 Only one notifier can be registered per target category and client instance. If
158 a notifier has already been registered, this IOCTL will fail with ``-EEXIST``.
160 Notifiers will automatically be removed when the device file instance is
164 ------------------------------
170 registered for this client instance and the given category, this IOCTL will
171 fail with ``-ENOENT``.
174 --------------------------
183 instance.
189 ---------------------------
196 and forwarded to user-space after this call. The only safe way of stopping
204 .. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h