docs: driver-api: Update Surface Aggregator user-space interface documentation
Update the controller-device user-space interface (cdev) documentation for the newly introduced IOCTLs and event interface. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Reviewed-by: Hans de Goede <hdegoede@redhat.com> Link: https://lore.kernel.org/r/20210604134755.535590-8-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
This commit is contained in:
Maximilian Luz
Hans de Goede
parent
cbd224e0dd
commit
8ae200547a
|
|
@ -1,9 +1,8 @@
|
|||
.. 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>`
|
||||
.. |ssam_cdev_event| replace:: :c:type:`struct ssam_cdev_event <ssam_cdev_event>`
|
||||
|
||||
==============================
|
||||
User-Space EC Interface (cdev)
|
||||
|
|
@ -23,6 +22,40 @@ These IOCTLs and their respective input/output parameter structs are defined in
|
|||
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.
|
||||
|
||||
.. contents::
|
||||
|
||||
|
||||
Receiving Events
|
||||
================
|
||||
|
||||
Events can be received by reading from the device-file. The are represented by
|
||||
the |ssam_cdev_event| datatype.
|
||||
|
||||
Before events are available to be read, however, the desired notifiers must be
|
||||
registered via the ``SSAM_CDEV_NOTIF_REGISTER`` IOCTL. Notifiers are, in
|
||||
essence, callbacks, called when the EC sends an event. They are, in this
|
||||
interface, associated with a specific target category and device-file-instance.
|
||||
They forward any event of this category to the buffer of the corresponding
|
||||
instance, from which it can then be read.
|
||||
|
||||
Notifiers themselves do not enable events on the EC. Thus, it may additionally
|
||||
be necessary to enable events via the ``SSAM_CDEV_EVENT_ENABLE`` IOCTL. While
|
||||
notifiers work per-client (i.e. per-device-file-instance), events are enabled
|
||||
globally, for the EC and all of its clients (regardless of userspace or
|
||||
non-userspace). The ``SSAM_CDEV_EVENT_ENABLE`` and ``SSAM_CDEV_EVENT_DISABLE``
|
||||
IOCTLs take care of reference counting the events, such that an event is
|
||||
enabled as long as there is a client that has requested it.
|
||||
|
||||
Note that enabled events are not automatically disabled once the client
|
||||
instance is closed. Therefore any client process (or group of processes) should
|
||||
balance their event enable calls with the corresponding event disable calls. It
|
||||
is, however, perfectly valid to enable and disable events on different client
|
||||
instances. For example, it is valid to set up notifiers and read events on
|
||||
client instance ``A``, enable those events on instance ``B`` (note that these
|
||||
will also be received by A since events are enabled/disabled globally), and
|
||||
after no more events are desired, disable the previously enabled events via
|
||||
instance ``C``.
|
||||
|
||||
|
||||
Controller IOCTLs
|
||||
=================
|
||||
|
|
@ -45,9 +78,33 @@ The following IOCTLs are provided:
|
|||
- ``REQUEST``
|
||||
- Perform synchronous SAM request.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``2``
|
||||
- ``W``
|
||||
- ``NOTIF_REGISTER``
|
||||
- Register event notifier.
|
||||
|
||||
``REQUEST``
|
||||
-----------
|
||||
* - ``0xA5``
|
||||
- ``3``
|
||||
- ``W``
|
||||
- ``NOTIF_UNREGISTER``
|
||||
- Unregister event notifier.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``4``
|
||||
- ``W``
|
||||
- ``EVENT_ENABLE``
|
||||
- Enable event source.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``5``
|
||||
- ``W``
|
||||
- ``EVENT_DISABLE``
|
||||
- Disable event source.
|
||||
|
||||
|
||||
``SSAM_CDEV_REQUEST``
|
||||
---------------------
|
||||
|
||||
Defined as ``_IOWR(0xA5, 1, struct ssam_cdev_request)``.
|
||||
|
||||
|
|
@ -82,6 +139,66 @@ 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:
|
||||
A full definition of the argument struct is provided below.
|
||||
|
||||
``SSAM_CDEV_NOTIF_REGISTER``
|
||||
----------------------------
|
||||
|
||||
Defined as ``_IOW(0xA5, 2, struct ssam_cdev_notifier_desc)``.
|
||||
|
||||
Register a notifier for the event target category specified in the given
|
||||
notifier description with the specified priority. Notifiers registration is
|
||||
required to receive events, but does not enable events themselves. After a
|
||||
notifier for a specific target category has been registered, all events of that
|
||||
category will be forwarded to the userspace client and can then be read from
|
||||
the device file instance. Note that events may have to be enabled, e.g. via the
|
||||
``SSAM_CDEV_EVENT_ENABLE`` IOCTL, before the EC will send them.
|
||||
|
||||
Only one notifier can be registered per target category and client instance. If
|
||||
a notifier has already been registered, this IOCTL will fail with ``-EEXIST``.
|
||||
|
||||
Notifiers will automatically be removed when the device file instance is
|
||||
closed.
|
||||
|
||||
``SSAM_CDEV_NOTIF_UNREGISTER``
|
||||
------------------------------
|
||||
|
||||
Defined as ``_IOW(0xA5, 3, struct ssam_cdev_notifier_desc)``.
|
||||
|
||||
Unregisters the notifier associated with the specified target category. The
|
||||
priority field will be ignored by this IOCTL. If no notifier has been
|
||||
registered for this client instance and the given category, this IOCTL will
|
||||
fail with ``-ENOENT``.
|
||||
|
||||
``SSAM_CDEV_EVENT_ENABLE``
|
||||
--------------------------
|
||||
|
||||
Defined as ``_IOW(0xA5, 4, struct ssam_cdev_event_desc)``.
|
||||
|
||||
Enable the event associated with the given event descriptor.
|
||||
|
||||
Note that this call will not register a notifier itself, it will only enable
|
||||
events on the controller. If you want to receive events by reading from the
|
||||
device file, you will need to register the corresponding notifier(s) on that
|
||||
instance.
|
||||
|
||||
Events are not automatically disabled when the device file is closed. This must
|
||||
be done manually, via a call to the ``SSAM_CDEV_EVENT_DISABLE`` IOCTL.
|
||||
|
||||
``SSAM_CDEV_EVENT_DISABLE``
|
||||
---------------------------
|
||||
|
||||
Defined as ``_IOW(0xA5, 5, struct ssam_cdev_event_desc)``.
|
||||
|
||||
Disable the event associated with the given event descriptor.
|
||||
|
||||
Note that this will not unregister any notifiers. Events may still be received
|
||||
and forwarded to user-space after this call. The only safe way of stopping
|
||||
events from being received is unregistering all previously registered
|
||||
notifiers.
|
||||
|
||||
|
||||
Structures and Enums
|
||||
====================
|
||||
|
||||
.. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h
|
||||
|
|
|
|||
Loading…
Reference in New Issue