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

   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 ==============================
   8 User-Space EC Interface (cdev)
   9 ==============================
  10
  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
  13 the SAM EC. It is intended to be used for development and debugging, and
  14 therefore should not be used or relied upon in any other way. Note that this
  15 module is not loaded automatically, but instead must be loaded manually.
  16
  17 The provided interface is accessible through the ``/dev/surface/aggregator``
  18 device-file. All functionality of this interface is provided via IOCTLs.
  19 These IOCTLs and their respective input/output parameter structs are defined in
  20 ``include/uapi/linux/surface_aggregator/cdev.h``.
  21
  22 A small python library and scripts for accessing this interface can be found
  23 at https://github.com/linux-surface/surface-aggregator-module/tree/master/scripts/ssam.
  24
  25 .. contents::
  26
  27
  28 Receiving Events
  29 ================
  30
  31 Events can be received by reading from the device-file. The are represented by
  32 the |ssam_cdev_event| datatype.
  33
  34 Before events are available to be read, however, the desired notifiers must be
  35 registered via the ``SSAM_CDEV_NOTIF_REGISTER`` IOCTL. Notifiers are, in
  36 essence, callbacks, called when the EC sends an event. They are, in this
  37 interface, associated with a specific target category and device-file-instance.
  38 They forward any event of this category to the buffer of the corresponding
  39 instance, from which it can then be read.
  40
  41 Notifiers themselves do not enable events on the EC. Thus, it may additionally
  42 be necessary to enable events via the ``SSAM_CDEV_EVENT_ENABLE`` IOCTL. While
  43 notifiers work per-client (i.e. per-device-file-instance), events are enabled
  44 globally, for the EC and all of its clients (regardless of userspace or
  45 non-userspace). The ``SSAM_CDEV_EVENT_ENABLE`` and ``SSAM_CDEV_EVENT_DISABLE``
  46 IOCTLs take care of reference counting the events, such that an event is
  47 enabled as long as there is a client that has requested it.
  48
  49 Note that enabled events are not automatically disabled once the client
  50 instance is closed. Therefore any client process (or group of processes) should
  51 balance their event enable calls with the corresponding event disable calls. It
  52 is, however, perfectly valid to enable and disable events on different client
  53 instances. For example, it is valid to set up notifiers and read events on
  54 client instance ``A``, enable those events on instance ``B`` (note that these
  55 will also be received by A since events are enabled/disabled globally), and
  56 after no more events are desired, disable the previously enabled events via
  57 instance ``C``.
  58
  59
  60 Controller IOCTLs
  61 =================
  62
  63 The 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
 109 Defined as ``_IOWR(0xA5, 1, struct ssam_cdev_request)``.
 110
 111 Executes a synchronous SAM request. The request specification is passed in
 112 as argument of type |ssam_cdev_request|, which is then written to/modified
 113 by the IOCTL to return status and result of the request.
 114
 115 Request payload data must be allocated separately and is passed in via the
 116 ``payload.data`` and ``payload.length`` members. If a response is required,
 117 the 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
 119 capacity of this buffer, or if no response is required, zero. Upon
 120 completion of the request, the call will write the response to the response
 121 buffer (if its capacity allows it) and overwrite the length field with the
 122 actual size of the response, in bytes.
 123
 124 Additionally, if the request has a response, this must be indicated via the
 125 request flags, as is done with in-kernel requests. Request flags can be set
 126 via the ``flags`` member and the values correspond to the values found in
 127 |ssam_cdev_request_flags|.
 128
 129 Finally, the status of the request itself is returned in the ``status``
 130 member (a negative errno value indicating failure). Note that failure
 131 indication of the IOCTL is separated from failure indication of the request:
 132 The IOCTL returns a negative status code if anything failed during setup of
 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
 135 argument 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
 137 will return with a zero status code in case the request has been set up,
 138 submitted, and completed (i.e. handed back to user-space) successfully from
 139 inside the IOCTL, but the request ``status`` member may still be negative in
 140 case the actual execution of the request failed after it has been submitted.
 141
 142 A full definition of the argument struct is provided below.
 143
 144 ``SSAM_CDEV_NOTIF_REGISTER``
 145 ----------------------------
 146
 147 Defined as ``_IOW(0xA5, 2, struct ssam_cdev_notifier_desc)``.
 148
 149 Register a notifier for the event target category specified in the given
 150 notifier description with the specified priority. Notifiers registration is
 151 required to receive events, but does not enable events themselves. After a
 152 notifier for a specific target category has been registered, all events of that
 153 category will be forwarded to the userspace client and can then be read from
 154 the 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
 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``.
 159
 160 Notifiers will automatically be removed when the device file instance is
 161 closed.
 162
 163 ``SSAM_CDEV_NOTIF_UNREGISTER``
 164 ------------------------------
 165
 166 Defined as ``_IOW(0xA5, 3, struct ssam_cdev_notifier_desc)``.
 167
 168 Unregisters the notifier associated with the specified target category. The
 169 priority field will be ignored by this IOCTL. If no notifier has been
 170 registered for this client instance and the given category, this IOCTL will
 171 fail with ``-ENOENT``.
 172
 173 ``SSAM_CDEV_EVENT_ENABLE``
 174 --------------------------
 175
 176 Defined as ``_IOW(0xA5, 4, struct ssam_cdev_event_desc)``.
 177
 178 Enable the event associated with the given event descriptor.
 179
 180 Note that this call will not register a notifier itself, it will only enable
 181 events on the controller. If you want to receive events by reading from the
 182 device file, you will need to register the corresponding notifier(s) on that
 183 instance.
 184
 185 Events are not automatically disabled when the device file is closed. This must
 186 be done manually, via a call to the ``SSAM_CDEV_EVENT_DISABLE`` IOCTL.
 187
 188 ``SSAM_CDEV_EVENT_DISABLE``
 189 ---------------------------
 190
 191 Defined as ``_IOW(0xA5, 5, struct ssam_cdev_event_desc)``.
 192
 193 Disable the event associated with the given event descriptor.
 194
 195 Note that this will not unregister any notifiers. Events may still be received
 196 and forwarded to user-space after this call. The only safe way of stopping
 197 events from being received is unregistering all previously registered
 198 notifiers.
 199
 200
 201 Structures and Enums
 202 ====================
 203
 204 .. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h