mirror of
https://github.com/torvalds/linux
synced 2024-10-05 02:44:13 +00:00
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:
parent
cbd224e0dd
commit
8ae200547a
|
@ -1,9 +1,8 @@
|
||||||
.. SPDX-License-Identifier: GPL-2.0+
|
.. 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| 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_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)
|
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
|
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.
|
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
|
Controller IOCTLs
|
||||||
=================
|
=================
|
||||||
|
@ -45,9 +78,33 @@ The following IOCTLs are provided:
|
||||||
- ``REQUEST``
|
- ``REQUEST``
|
||||||
- Perform synchronous SAM 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)``.
|
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
|
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.
|
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
|
.. kernel-doc:: include/uapi/linux/surface_aggregator/cdev.h
|
||||||
|
|
Loading…
Reference in a new issue