mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2025-01-07 13:43:51 +00:00
docs: driver-api: Add Surface DTX driver documentation
Add documentation for the user-space interface of the Surface DTX (detachment system) driver, used on Microsoft Surface Book series devices. Signed-off-by: Maximilian Luz <luzmaximilian@gmail.com> Link: https://lore.kernel.org/r/20210308184819.437438-4-luzmaximilian@gmail.com Signed-off-by: Hans de Goede <hdegoede@redhat.com>
This commit is contained in:
Maximilian Luz
Hans de Goede
parent
e893d45f11
commit
f614a1e23a
718
Documentation/driver-api/surface_aggregator/clients/dtx.rst
Normal file
718
Documentation/driver-api/surface_aggregator/clients/dtx.rst
Normal file
@ -0,0 +1,718 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0+
|
||||
|
||||
.. |__u16| replace:: :c:type:`__u16 <__u16>`
|
||||
.. |sdtx_event| replace:: :c:type:`struct sdtx_event <sdtx_event>`
|
||||
.. |sdtx_event_code| replace:: :c:type:`enum sdtx_event_code <sdtx_event_code>`
|
||||
.. |sdtx_base_info| replace:: :c:type:`struct sdtx_base_info <sdtx_base_info>`
|
||||
.. |sdtx_device_mode| replace:: :c:type:`struct sdtx_device_mode <sdtx_device_mode>`
|
||||
|
||||
======================================================
|
||||
User-Space DTX (Clipboard Detachment System) Interface
|
||||
======================================================
|
||||
|
||||
The ``surface_dtx`` driver is responsible for proper clipboard detachment
|
||||
and re-attachment handling. To this end, it provides the ``/dev/surface/dtx``
|
||||
device file, through which it can interface with a user-space daemon. This
|
||||
daemon is then ultimately responsible for determining and taking necessary
|
||||
actions, such as unmounting devices attached to the base,
|
||||
unloading/reloading the graphics-driver, user-notifications, etc.
|
||||
|
||||
There are two basic communication principles used in this driver: Commands
|
||||
(in other parts of the documentation also referred to as requests) and
|
||||
events. Commands are sent to the EC and may have a different implications in
|
||||
different contexts. Events are sent by the EC upon some internal state
|
||||
change. Commands are always driver-initiated, whereas events are always
|
||||
initiated by the EC.
|
||||
|
||||
.. contents::
|
||||
|
||||
Nomenclature
|
||||
============
|
||||
|
||||
* **Clipboard:**
|
||||
The detachable upper part of the Surface Book, housing the screen and CPU.
|
||||
|
||||
* **Base:**
|
||||
The lower part of the Surface Book from which the clipboard can be
|
||||
detached, optionally (model dependent) housing the discrete GPU (dGPU).
|
||||
|
||||
* **Latch:**
|
||||
The mechanism keeping the clipboard attached to the base in normal
|
||||
operation and allowing it to be detached when requested.
|
||||
|
||||
* **Silently ignored commands:**
|
||||
The command is accepted by the EC as a valid command and acknowledged
|
||||
(following the standard communication protocol), but the EC does not act
|
||||
upon it, i.e. ignores it.e upper part of the
|
||||
|
||||
|
||||
Detachment Process
|
||||
==================
|
||||
|
||||
Warning: This part of the documentation is based on reverse engineering and
|
||||
testing and thus may contain errors or be incomplete.
|
||||
|
||||
Latch States
|
||||
------------
|
||||
|
||||
The latch mechanism has two major states: *open* and *closed*. In the
|
||||
*closed* state (default), the clipboard is secured to the base, whereas in
|
||||
the *open* state, the clipboard can be removed by a user.
|
||||
|
||||
The latch can additionally be locked and, correspondingly, unlocked, which
|
||||
can influence the detachment procedure. Specifically, this locking mechanism
|
||||
is intended to prevent the dGPU, positioned in the base of the device, from
|
||||
being hot-unplugged while in use. More details can be found in the
|
||||
documentation for the detachment procedure below. By default, the latch is
|
||||
unlocked.
|
||||
|
||||
Detachment Procedure
|
||||
--------------------
|
||||
|
||||
Note that the detachment process is governed fully by the EC. The
|
||||
``surface_dtx`` driver only relays events from the EC to user-space and
|
||||
commands from user-space to the EC, i.e. it does not influence this process.
|
||||
|
||||
The detachment process is started with the user pressing the *detach* button
|
||||
on the base of the device or executing the ``SDTX_IOCTL_LATCH_REQUEST`` IOCTL.
|
||||
Following that:
|
||||
|
||||
1. The EC turns on the indicator led on the detach-button, sends a
|
||||
*detach-request* event (``SDTX_EVENT_REQUEST``), and awaits further
|
||||
instructions/commands. In case the latch is unlocked, the led will flash
|
||||
green. If the latch has been locked, the led will be solid red
|
||||
|
||||
2. The event is, via the ``surface_dtx`` driver, relayed to user-space, where
|
||||
an appropriate user-space daemon can handle it and send instructions back
|
||||
to the EC via IOCTLs provided by this driver.
|
||||
|
||||
3. The EC waits for instructions from user-space and acts according to them.
|
||||
If the EC does not receive any instructions in a given period, it will
|
||||
time out and continue as follows:
|
||||
|
||||
- If the latch is unlocked, the EC will open the latch and the clipboard
|
||||
can be detached from the base. This is the exact behavior as without
|
||||
this driver or any user-space daemon. See the ``SDTX_IOCTL_LATCH_CONFIRM``
|
||||
description below for more details on the follow-up behavior of the EC.
|
||||
|
||||
- If the latch is locked, the EC will *not* open the latch, meaning the
|
||||
clipboard cannot be detached from the base. Furthermore, the EC sends
|
||||
an cancel event (``SDTX_EVENT_CANCEL``) detailing this with the cancel
|
||||
reason ``SDTX_DETACH_TIMEDOUT`` (see :ref:`events` for details).
|
||||
|
||||
Valid responses by a user-space daemon to a detachment request event are:
|
||||
|
||||
- Execute ``SDTX_IOCTL_LATCH_REQUEST``. This will immediately abort the
|
||||
detachment process. Furthermore, the EC will send a detach-request event,
|
||||
similar to the user pressing the detach-button to cancel said process (see
|
||||
below).
|
||||
|
||||
- Execute ``SDTX_IOCTL_LATCH_CONFIRM``. This will cause the EC to open the
|
||||
latch, after which the user can separate clipboard and base.
|
||||
|
||||
As this changes the latch state, a *latch-status* event
|
||||
(``SDTX_EVENT_LATCH_STATUS``) will be sent once the latch has been opened
|
||||
successfully. If the EC fails to open the latch, e.g. due to hardware
|
||||
error or low battery, a latch-cancel event (``SDTX_EVENT_CANCEL``) will be
|
||||
sent with the cancel reason indicating the specific failure.
|
||||
|
||||
If the latch is currently locked, the latch will automatically be
|
||||
unlocked before it is opened.
|
||||
|
||||
- Execute ``SDTX_IOCTL_LATCH_HEARTBEAT``. This will reset the internal timeout.
|
||||
No other actions will be performed, i.e. the detachment process will neither
|
||||
be completed nor canceled, and the EC will still be waiting for further
|
||||
responses.
|
||||
|
||||
- Execute ``SDTX_IOCTL_LATCH_CANCEL``. This will abort the detachment process,
|
||||
similar to ``SDTX_IOCTL_LATCH_REQUEST``, described above, or the button
|
||||
press, described below. A *generic request* event (``SDTX_EVENT_REQUEST``)
|
||||
is send in response to this. In contrast to those, however, this command
|
||||
does not trigger a new detachment process if none is currently in
|
||||
progress.
|
||||
|
||||
- Do nothing. The detachment process eventually times out as described in
|
||||
point 3.
|
||||
|
||||
See :ref:`ioctls` for more details on these responses.
|
||||
|
||||
It is important to note that, if the user presses the detach button at any
|
||||
point when a detachment operation is in progress (i.e. after the EC has sent
|
||||
the initial *detach-request* event (``SDTX_EVENT_REQUEST``) and before it
|
||||
received the corresponding response concluding the process), the detachment
|
||||
process is canceled on the EC-level and an identical event is being sent.
|
||||
Thus a *detach-request* event, by itself, does not signal the start of the
|
||||
detachment process.
|
||||
|
||||
The detachment process may further be canceled by the EC due to hardware
|
||||
failures or a low clipboard battery. This is done via a cancel event
|
||||
(``SDTX_EVENT_CANCEL``) with the corresponding cancel reason.
|
||||
|
||||
|
||||
User-Space Interface Documentation
|
||||
==================================
|
||||
|
||||
Error Codes and Status Values
|
||||
-----------------------------
|
||||
|
||||
Error and status codes are divided into different categories, which can be
|
||||
used to determine if the status code is an error, and, if it is, the
|
||||
severity and type of that error. The current categories are:
|
||||
|
||||
.. flat-table:: Overview of Status/Error Categories.
|
||||
:widths: 2 1 3
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Value
|
||||
- Short Description
|
||||
|
||||
* - ``STATUS``
|
||||
- ``0x0000``
|
||||
- Non-error status codes.
|
||||
|
||||
* - ``RUNTIME_ERROR``
|
||||
- ``0x1000``
|
||||
- Non-critical runtime errors.
|
||||
|
||||
* - ``HARDWARE_ERROR``
|
||||
- ``0x2000``
|
||||
- Critical hardware failures.
|
||||
|
||||
* - ``UNKNOWN``
|
||||
- ``0xF000``
|
||||
- Unknown error codes.
|
||||
|
||||
Other categories are reserved for future use. The ``SDTX_CATEGORY()`` macro
|
||||
can be used to determine the category of any status value. The
|
||||
``SDTX_SUCCESS()`` macro can be used to check if the status value is a
|
||||
success value (``SDTX_CATEGORY_STATUS``) or if it indicates a failure.
|
||||
|
||||
Unknown status or error codes sent by the EC are assigned to the ``UNKNOWN``
|
||||
category by the driver and may be implemented via their own code in the
|
||||
future.
|
||||
|
||||
Currently used error codes are:
|
||||
|
||||
.. flat-table:: Overview of Error Codes.
|
||||
:widths: 2 1 1 3
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Category
|
||||
- Value
|
||||
- Short Description
|
||||
|
||||
* - ``SDTX_DETACH_NOT_FEASIBLE``
|
||||
- ``RUNTIME``
|
||||
- ``0x1001``
|
||||
- Detachment not feasible due to low clipboard battery.
|
||||
|
||||
* - ``SDTX_DETACH_TIMEDOUT``
|
||||
- ``RUNTIME``
|
||||
- ``0x1002``
|
||||
- Detachment process timed out while the latch was locked.
|
||||
|
||||
* - ``SDTX_ERR_FAILED_TO_OPEN``
|
||||
- ``HARDWARE``
|
||||
- ``0x2001``
|
||||
- Failed to open latch.
|
||||
|
||||
* - ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``
|
||||
- ``HARDWARE``
|
||||
- ``0x2002``
|
||||
- Failed to keep latch open.
|
||||
|
||||
* - ``SDTX_ERR_FAILED_TO_CLOSE``
|
||||
- ``HARDWARE``
|
||||
- ``0x2003``
|
||||
- Failed to close latch.
|
||||
|
||||
Other error codes are reserved for future use. Non-error status codes may
|
||||
overlap and are generally only unique within their use-case:
|
||||
|
||||
.. flat-table:: Latch Status Codes.
|
||||
:widths: 2 1 1 3
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Category
|
||||
- Value
|
||||
- Short Description
|
||||
|
||||
* - ``SDTX_LATCH_CLOSED``
|
||||
- ``STATUS``
|
||||
- ``0x0000``
|
||||
- Latch is closed/has been closed.
|
||||
|
||||
* - ``SDTX_LATCH_OPENED``
|
||||
- ``STATUS``
|
||||
- ``0x0001``
|
||||
- Latch is open/has been opened.
|
||||
|
||||
.. flat-table:: Base State Codes.
|
||||
:widths: 2 1 1 3
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Category
|
||||
- Value
|
||||
- Short Description
|
||||
|
||||
* - ``SDTX_BASE_DETACHED``
|
||||
- ``STATUS``
|
||||
- ``0x0000``
|
||||
- Base has been detached/is not present.
|
||||
|
||||
* - ``SDTX_BASE_ATTACHED``
|
||||
- ``STATUS``
|
||||
- ``0x0001``
|
||||
- Base has been attached/is present.
|
||||
|
||||
Again, other codes are reserved for future use.
|
||||
|
||||
.. _events:
|
||||
|
||||
Events
|
||||
------
|
||||
|
||||
Events can be received by reading from the device file. They are disabled by
|
||||
default and have to be enabled by executing ``SDTX_IOCTL_EVENTS_ENABLE``
|
||||
first. All events follow the layout prescribed by |sdtx_event|. Specific
|
||||
event types can be identified by their event code, described in
|
||||
|sdtx_event_code|. Note that other event codes are reserved for future use,
|
||||
thus an event parser must be able to handle any unknown/unsupported event
|
||||
types gracefully, by relying on the payload length given in the event header.
|
||||
|
||||
Currently provided event types are:
|
||||
|
||||
.. flat-table:: Overview of DTX events.
|
||||
:widths: 2 1 1 3
|
||||
:header-rows: 1
|
||||
|
||||
* - Name
|
||||
- Code
|
||||
- Payload
|
||||
- Short Description
|
||||
|
||||
* - ``SDTX_EVENT_REQUEST``
|
||||
- ``1``
|
||||
- ``0`` bytes
|
||||
- Detachment process initiated/aborted.
|
||||
|
||||
* - ``SDTX_EVENT_CANCEL``
|
||||
- ``2``
|
||||
- ``2`` bytes
|
||||
- EC canceled detachment process.
|
||||
|
||||
* - ``SDTX_EVENT_BASE_CONNECTION``
|
||||
- ``3``
|
||||
- ``4`` bytes
|
||||
- Base connection state changed.
|
||||
|
||||
* - ``SDTX_EVENT_LATCH_STATUS``
|
||||
- ``4``
|
||||
- ``2`` bytes
|
||||
- Latch status changed.
|
||||
|
||||
* - ``SDTX_EVENT_DEVICE_MODE``
|
||||
- ``5``
|
||||
- ``2`` bytes
|
||||
- Device mode changed.
|
||||
|
||||
Individual events in more detail:
|
||||
|
||||
``SDTX_EVENT_REQUEST``
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sent when a detachment process is started or, if in progress, aborted by the
|
||||
user, either via a detach button press or a detach request
|
||||
(``SDTX_IOCTL_LATCH_REQUEST``) being sent from user-space.
|
||||
|
||||
Does not have any payload.
|
||||
|
||||
``SDTX_EVENT_CANCEL``
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sent when a detachment process is canceled by the EC due to unfulfilled
|
||||
preconditions (e.g. clipboard battery too low to detach) or hardware
|
||||
failure. The reason for cancellation is given in the event payload detailed
|
||||
below and can be one of
|
||||
|
||||
* ``SDTX_DETACH_TIMEDOUT``: Detachment timed out while the latch was locked.
|
||||
The latch has neither been opened nor unlocked.
|
||||
|
||||
* ``SDTX_DETACH_NOT_FEASIBLE``: Detachment not feasible due to low clipboard
|
||||
battery.
|
||||
|
||||
* ``SDTX_ERR_FAILED_TO_OPEN``: Could not open the latch (hardware failure).
|
||||
|
||||
* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``: Could not keep the latch open (hardware
|
||||
failure).
|
||||
|
||||
* ``SDTX_ERR_FAILED_TO_CLOSE``: Could not close the latch (hardware failure).
|
||||
|
||||
Other error codes in this context are reserved for future use.
|
||||
|
||||
These codes can be classified via the ``SDTX_CATEGORY()`` macro to discern
|
||||
between critical hardware errors (``SDTX_CATEGORY_HARDWARE_ERROR``) or
|
||||
runtime errors (``SDTX_CATEGORY_RUNTIME_ERROR``), the latter of which may
|
||||
happen during normal operation if certain preconditions for detachment are
|
||||
not given.
|
||||
|
||||
.. flat-table:: Detachment Cancel Event Payload
|
||||
:widths: 1 1 4
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Type
|
||||
- Description
|
||||
|
||||
* - ``reason``
|
||||
- |__u16|
|
||||
- Reason for cancellation.
|
||||
|
||||
``SDTX_EVENT_BASE_CONNECTION``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sent when the base connection state has changed, i.e. when the base has been
|
||||
attached, detached, or detachment has become infeasible due to low clipboard
|
||||
battery. The new state and, if a base is connected, ID of the base is
|
||||
provided as payload of type |sdtx_base_info| with its layout presented
|
||||
below:
|
||||
|
||||
.. flat-table:: Base-Connection-Change Event Payload
|
||||
:widths: 1 1 4
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Type
|
||||
- Description
|
||||
|
||||
* - ``state``
|
||||
- |__u16|
|
||||
- Base connection state.
|
||||
|
||||
* - ``base_id``
|
||||
- |__u16|
|
||||
- Type of base connected (zero if none).
|
||||
|
||||
Possible values for ``state`` are:
|
||||
|
||||
* ``SDTX_BASE_DETACHED``,
|
||||
* ``SDTX_BASE_ATTACHED``, and
|
||||
* ``SDTX_DETACH_NOT_FEASIBLE``.
|
||||
|
||||
Other values are reserved for future use.
|
||||
|
||||
``SDTX_EVENT_LATCH_STATUS``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sent when the latch status has changed, i.e. when the latch has been opened,
|
||||
closed, or an error occurred. The current status is provided as payload:
|
||||
|
||||
.. flat-table:: Latch-Status-Change Event Payload
|
||||
:widths: 1 1 4
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Type
|
||||
- Description
|
||||
|
||||
* - ``status``
|
||||
- |__u16|
|
||||
- Latch status.
|
||||
|
||||
Possible values for ``status`` are:
|
||||
|
||||
* ``SDTX_LATCH_CLOSED``,
|
||||
* ``SDTX_LATCH_OPENED``,
|
||||
* ``SDTX_ERR_FAILED_TO_OPEN``,
|
||||
* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and
|
||||
* ``SDTX_ERR_FAILED_TO_CLOSE``.
|
||||
|
||||
Other values are reserved for future use.
|
||||
|
||||
``SDTX_EVENT_DEVICE_MODE``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Sent when the device mode has changed. The new device mode is provided as
|
||||
payload:
|
||||
|
||||
.. flat-table:: Device-Mode-Change Event Payload
|
||||
:widths: 1 1 4
|
||||
:header-rows: 1
|
||||
|
||||
* - Field
|
||||
- Type
|
||||
- Description
|
||||
|
||||
* - ``mode``
|
||||
- |__u16|
|
||||
- Device operation mode.
|
||||
|
||||
Possible values for ``mode`` are:
|
||||
|
||||
* ``SDTX_DEVICE_MODE_TABLET``,
|
||||
* ``SDTX_DEVICE_MODE_LAPTOP``, and
|
||||
* ``SDTX_DEVICE_MODE_STUDIO``.
|
||||
|
||||
Other values are reserved for future use.
|
||||
|
||||
.. _ioctls:
|
||||
|
||||
IOCTLs
|
||||
------
|
||||
|
||||
The following IOCTLs are provided:
|
||||
|
||||
.. flat-table:: Overview of DTX IOCTLs
|
||||
:widths: 1 1 1 1 4
|
||||
:header-rows: 1
|
||||
|
||||
* - Type
|
||||
- Number
|
||||
- Direction
|
||||
- Name
|
||||
- Description
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x21``
|
||||
- ``-``
|
||||
- ``EVENTS_ENABLE``
|
||||
- Enable events for the current file descriptor.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x22``
|
||||
- ``-``
|
||||
- ``EVENTS_DISABLE``
|
||||
- Disable events for the current file descriptor.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x23``
|
||||
- ``-``
|
||||
- ``LATCH_LOCK``
|
||||
- Lock the latch.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x24``
|
||||
- ``-``
|
||||
- ``LATCH_UNLOCK``
|
||||
- Unlock the latch.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x25``
|
||||
- ``-``
|
||||
- ``LATCH_REQUEST``
|
||||
- Request clipboard detachment.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x26``
|
||||
- ``-``
|
||||
- ``LATCH_CONFIRM``
|
||||
- Confirm clipboard detachment request.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x27``
|
||||
- ``-``
|
||||
- ``LATCH_HEARTBEAT``
|
||||
- Send heartbeat signal to EC.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x28``
|
||||
- ``-``
|
||||
- ``LATCH_CANCEL``
|
||||
- Cancel detachment process.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x29``
|
||||
- ``R``
|
||||
- ``GET_BASE_INFO``
|
||||
- Get current base/connection information.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x2A``
|
||||
- ``R``
|
||||
- ``GET_DEVICE_MODE``
|
||||
- Get current device operation mode.
|
||||
|
||||
* - ``0xA5``
|
||||
- ``0x2B``
|
||||
- ``R``
|
||||
- ``GET_LATCH_STATUS``
|
||||
- Get current device latch status.
|
||||
|
||||
``SDTX_IOCTL_EVENTS_ENABLE``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x22)``.
|
||||
|
||||
Enable events for the current file descriptor. Events can be obtained by
|
||||
reading from the device, if enabled. Events are disabled by default.
|
||||
|
||||
``SDTX_IOCTL_EVENTS_DISABLE``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x22)``.
|
||||
|
||||
Disable events for the current file descriptor. Events can be obtained by
|
||||
reading from the device, if enabled. Events are disabled by default.
|
||||
|
||||
``SDTX_IOCTL_LATCH_LOCK``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x23)``.
|
||||
|
||||
Locks the latch, causing the detachment procedure to abort without opening
|
||||
the latch on timeout. The latch is unlocked by default. This command will be
|
||||
silently ignored if the latch is already locked.
|
||||
|
||||
``SDTX_IOCTL_LATCH_UNLOCK``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x24)``.
|
||||
|
||||
Unlocks the latch, causing the detachment procedure to open the latch on
|
||||
timeout. The latch is unlocked by default. This command will not open the
|
||||
latch when sent during an ongoing detachment process. It will be silently
|
||||
ignored if the latch is already unlocked.
|
||||
|
||||
``SDTX_IOCTL_LATCH_REQUEST``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x25)``.
|
||||
|
||||
Generic latch request. Behavior depends on the context: If no
|
||||
detachment-process is active, detachment is requested. Otherwise the
|
||||
currently active detachment-process will be aborted.
|
||||
|
||||
If a detachment process is canceled by this operation, a generic detachment
|
||||
request event (``SDTX_EVENT_REQUEST``) will be sent.
|
||||
|
||||
This essentially behaves the same as a detachment button press.
|
||||
|
||||
``SDTX_IOCTL_LATCH_CONFIRM``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x26)``.
|
||||
|
||||
Acknowledges and confirms a latch request. If sent during an ongoing
|
||||
detachment process, this command causes the latch to be opened immediately.
|
||||
The latch will also be opened if it has been locked. In this case, the latch
|
||||
lock is reset to the unlocked state.
|
||||
|
||||
This command will be silently ignored if there is currently no detachment
|
||||
procedure in progress.
|
||||
|
||||
``SDTX_IOCTL_LATCH_HEARTBEAT``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x27)``.
|
||||
|
||||
Sends a heartbeat, essentially resetting the detachment timeout. This
|
||||
command can be used to keep the detachment process alive while work required
|
||||
for the detachment to succeed is still in progress.
|
||||
|
||||
This command will be silently ignored if there is currently no detachment
|
||||
procedure in progress.
|
||||
|
||||
``SDTX_IOCTL_LATCH_CANCEL``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IO(0xA5, 0x28)``.
|
||||
|
||||
Cancels detachment in progress (if any). If a detachment process is canceled
|
||||
by this operation, a generic detachment request event
|
||||
(``SDTX_EVENT_REQUEST``) will be sent.
|
||||
|
||||
This command will be silently ignored if there is currently no detachment
|
||||
procedure in progress.
|
||||
|
||||
``SDTX_IOCTL_GET_BASE_INFO``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IOR(0xA5, 0x29, struct sdtx_base_info)``.
|
||||
|
||||
Get the current base connection state (i.e. attached/detached) and the type
|
||||
of the base connected to the clipboard. This is command essentially provides
|
||||
a way to query the information provided by the base connection change event
|
||||
(``SDTX_EVENT_BASE_CONNECTION``).
|
||||
|
||||
Possible values for ``struct sdtx_base_info.state`` are:
|
||||
|
||||
* ``SDTX_BASE_DETACHED``,
|
||||
* ``SDTX_BASE_ATTACHED``, and
|
||||
* ``SDTX_DETACH_NOT_FEASIBLE``.
|
||||
|
||||
Other values are reserved for future use.
|
||||
|
||||
``SDTX_IOCTL_GET_DEVICE_MODE``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IOR(0xA5, 0x2A, __u16)``.
|
||||
|
||||
Returns the device operation mode, indicating if and how the base is
|
||||
attached to the clipboard. This is command essentially provides a way to
|
||||
query the information provided by the device mode change event
|
||||
(``SDTX_EVENT_DEVICE_MODE``).
|
||||
|
||||
Returned values are:
|
||||
|
||||
* ``SDTX_DEVICE_MODE_LAPTOP``
|
||||
* ``SDTX_DEVICE_MODE_TABLET``
|
||||
* ``SDTX_DEVICE_MODE_STUDIO``
|
||||
|
||||
See |sdtx_device_mode| for details. Other values are reserved for future
|
||||
use.
|
||||
|
||||
|
||||
``SDTX_IOCTL_GET_LATCH_STATUS``
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Defined as ``_IOR(0xA5, 0x2B, __u16)``.
|
||||
|
||||
Get the current latch status or (presumably) the last error encountered when
|
||||
trying to open/close the latch. This is command essentially provides a way
|
||||
to query the information provided by the latch status change event
|
||||
(``SDTX_EVENT_LATCH_STATUS``).
|
||||
|
||||
Returned values are:
|
||||
|
||||
* ``SDTX_LATCH_CLOSED``,
|
||||
* ``SDTX_LATCH_OPENED``,
|
||||
* ``SDTX_ERR_FAILED_TO_OPEN``,
|
||||
* ``SDTX_ERR_FAILED_TO_REMAIN_OPEN``, and
|
||||
* ``SDTX_ERR_FAILED_TO_CLOSE``.
|
||||
|
||||
Other values are reserved for future use.
|
||||
|
||||
A Note on Base IDs
|
||||
------------------
|
||||
|
||||
Base types/IDs provided via ``SDTX_EVENT_BASE_CONNECTION`` or
|
||||
``SDTX_IOCTL_GET_BASE_INFO`` are directly forwarded from the EC in the lower
|
||||
byte of the combined |__u16| value, with the driver storing the EC type from
|
||||
which this ID comes in the high byte (without this, base IDs over different
|
||||
types of ECs may be overlapping).
|
||||
|
||||
The ``SDTX_DEVICE_TYPE()`` macro can be used to determine the EC device
|
||||
type. This can be one of
|
||||
|
||||
* ``SDTX_DEVICE_TYPE_HID``, for Surface Aggregator Module over HID, and
|
||||
|
||||
* ``SDTX_DEVICE_TYPE_SSH``, for Surface Aggregator Module over Surface Serial
|
||||
Hub.
|
||||
|
||||
Note that currently only the ``SSH`` type EC is supported, however ``HID``
|
||||
type is reserved for future use.
|
||||
|
||||
Structures and Enums
|
||||
--------------------
|
||||
|
||||
.. kernel-doc:: include/uapi/linux/surface_aggregator/dtx.h
|
||||
|
||||
API Users
|
||||
=========
|
||||
|
||||
A user-space daemon utilizing this API can be found at
|
||||
https://github.com/linux-surface/surface-dtx-daemon.
|
||||
@ -11,6 +11,7 @@ This is the documentation for client drivers themselves. Refer to
|
||||
:maxdepth: 1
|
||||
|
||||
cdev
|
||||
dtx
|
||||
san
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
@ -11865,6 +11865,7 @@ MICROSOFT SURFACE DTX DRIVER
|
||||
M: Maximilian Luz <luzmaximilian@gmail.com>
|
||||
L: platform-driver-x86@vger.kernel.org
|
||||
S: Maintained
|
||||
F: Documentation/driver-api/surface_aggregator/clients/dtx.rst
|
||||
F: drivers/platform/surface/surface_dtx.c
|
||||
F: include/uapi/linux/surface_aggregator/dtx.h
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user