719 lines
21 KiB
ReStructuredText
719 lines
21 KiB
ReStructuredText
.. 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.
|