diff options
Diffstat (limited to 'Documentation/driver-api')
| -rw-r--r-- | Documentation/driver-api/driver-model/devres.rst | 3 | ||||
| -rw-r--r-- | Documentation/driver-api/iio/buffers.rst | 15 | ||||
| -rw-r--r-- | Documentation/driver-api/serial/cyclades_z.rst | 11 | ||||
| -rw-r--r-- | Documentation/driver-api/serial/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/driver-api/serial/rocket.rst | 185 | ||||
| -rw-r--r-- | Documentation/driver-api/surface_aggregator/client.rst | 4 | ||||
| -rw-r--r-- | Documentation/driver-api/surface_aggregator/clients/dtx.rst | 718 | ||||
| -rw-r--r-- | Documentation/driver-api/surface_aggregator/clients/index.rst | 1 |
8 files changed, 731 insertions, 207 deletions
diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index cd8b6e657b94..5f8c6c303ff2 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -285,7 +285,8 @@ I2C IIO devm_iio_device_alloc() devm_iio_device_register() - devm_iio_kfifo_allocate() + devm_iio_dmaengine_buffer_setup() + devm_iio_kfifo_buffer_setup() devm_iio_triggered_buffer_setup() devm_iio_trigger_alloc() devm_iio_trigger_register() diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst index 3ddebddc02ca..e83026aebe97 100644 --- a/Documentation/driver-api/iio/buffers.rst +++ b/Documentation/driver-api/iio/buffers.rst @@ -28,24 +28,26 @@ IIO buffer setup The meta information associated with a channel reading placed in a buffer is called a scan element. The important bits configuring scan elements are exposed to userspace applications via the -:file:`/sys/bus/iio/iio:device{X}/scan_elements/*` directory. This file contains +:file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains attributes of the following form: * :file:`enable`, used for enabling a channel. If and only if its attribute is non *zero*, then a triggered capture will contain data samples for this channel. +* :file:`index`, the scan_index of the channel. * :file:`type`, description of the scan element data storage within the buffer and hence the form in which it is read from user space. - Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] . + Format is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift] . + * *be* or *le*, specifies big or little endian. * *s* or *u*, specifies if signed (2's complement) or unsigned. * *bits*, is the number of valid data bits. * *storagebits*, is the number of bits (after padding) that it occupies in the - buffer. - * *shift*, if specified, is the shift that needs to be applied prior to - masking out unused bits. + buffer. * *repeat*, specifies the number of bits/storagebits repetitions. When the - repeat element is 0 or 1, then the repeat value is omitted. + repeat element is 0 or 1, then the repeat value is omitted. + * *shift*, if specified, is the shift that needs to be applied prior to + masking out unused bits. For example, a driver for a 3-axis accelerometer with 12 bit resolution where data is stored in two 8-bits registers as follows:: @@ -122,4 +124,3 @@ More details .. kernel-doc:: include/linux/iio/buffer.h .. kernel-doc:: drivers/iio/industrialio-buffer.c :export: - diff --git a/Documentation/driver-api/serial/cyclades_z.rst b/Documentation/driver-api/serial/cyclades_z.rst deleted file mode 100644 index 532ff67e2f1c..000000000000 --- a/Documentation/driver-api/serial/cyclades_z.rst +++ /dev/null @@ -1,11 +0,0 @@ -================ -Cyclades-Z notes -================ - -The Cyclades-Z must have firmware loaded onto the card before it will -operate. This operation should be performed during system startup, - -The firmware, loader program and the latest device driver code are -available from Cyclades at - - ftp://ftp.cyclades.com/pub/cyclades/cyclades-z/linux/ diff --git a/Documentation/driver-api/serial/index.rst b/Documentation/driver-api/serial/index.rst index 33ad10d05b26..21351b8c95a4 100644 --- a/Documentation/driver-api/serial/index.rst +++ b/Documentation/driver-api/serial/index.rst @@ -17,7 +17,6 @@ Serial drivers .. toctree:: :maxdepth: 1 - cyclades_z moxa-smartio n_gsm rocket diff --git a/Documentation/driver-api/serial/rocket.rst b/Documentation/driver-api/serial/rocket.rst deleted file mode 100644 index 23761eae4282..000000000000 --- a/Documentation/driver-api/serial/rocket.rst +++ /dev/null @@ -1,185 +0,0 @@ -================================================ -Comtrol(tm) RocketPort(R)/RocketModem(TM) Series -================================================ - -Device Driver for the Linux Operating System -============================================ - -Product overview ----------------- - -This driver provides a loadable kernel driver for the Comtrol RocketPort -and RocketModem PCI boards. These boards provide, 2, 4, 8, 16, or 32 -high-speed serial ports or modems. This driver supports up to a combination -of four RocketPort or RocketModems boards in one machine simultaneously. -This file assumes that you are using the RocketPort driver which is -integrated into the kernel sources. - -The driver can also be installed as an external module using the usual -"make;make install" routine. This external module driver, obtainable -from the Comtrol website listed below, is useful for updating the driver -or installing it into kernels which do not have the driver configured -into them. Installations instructions for the external module -are in the included README and HW_INSTALL files. - -RocketPort ISA and RocketModem II PCI boards currently are only supported by -this driver in module form. - -The RocketPort ISA board requires I/O ports to be configured by the DIP -switches on the board. See the section "ISA Rocketport Boards" below for -information on how to set the DIP switches. - -You pass the I/O port to the driver using the following module parameters: - -board1: - I/O port for the first ISA board -board2: - I/O port for the second ISA board -board3: - I/O port for the third ISA board -board4: - I/O port for the fourth ISA board - -There is a set of utilities and scripts provided with the external driver -(downloadable from http://www.comtrol.com) that ease the configuration and -setup of the ISA cards. - -The RocketModem II PCI boards require firmware to be loaded into the card -before it will function. The driver has only been tested as a module for this -board. - -Installation Procedures ------------------------ - -RocketPort/RocketModem PCI cards require no driver configuration, they are -automatically detected and configured. - -The RocketPort driver can be installed as a module (recommended) or built -into the kernel. This is selected, as for other drivers, through the `make config` -command from the root of the Linux source tree during the kernel build process. - -The RocketPort/RocketModem serial ports installed by this driver are assigned -device major number 46, and will be named /dev/ttyRx, where x is the port number -starting at zero (ex. /dev/ttyR0, /devttyR1, ...). If you have multiple cards -installed in the system, the mapping of port names to serial ports is displayed -in the system log at /var/log/messages. - -If installed as a module, the module must be loaded. This can be done -manually by entering "modprobe rocket". To have the module loaded automatically -upon system boot, edit a `/etc/modprobe.d/*.conf` file and add the line -"alias char-major-46 rocket". - -In order to use the ports, their device names (nodes) must be created with mknod. -This is only required once, the system will retain the names once created. To -create the RocketPort/RocketModem device names, use the command -"mknod /dev/ttyRx c 46 x" where x is the port number starting at zero. - -For example:: - - > mknod /dev/ttyR0 c 46 0 - > mknod /dev/ttyR1 c 46 1 - > mknod /dev/ttyR2 c 46 2 - -The Linux script MAKEDEV will create the first 16 ttyRx device names (nodes) -for you:: - - >/dev/MAKEDEV ttyR - -ISA Rocketport Boards ---------------------- - -You must assign and configure the I/O addresses used by the ISA Rocketport -card before installing and using it. This is done by setting a set of DIP -switches on the Rocketport board. - - -Setting the I/O address ------------------------ - -Before installing RocketPort(R) or RocketPort RA boards, you must find -a range of I/O addresses for it to use. The first RocketPort card -requires a 68-byte contiguous block of I/O addresses, starting at one -of the following: 0x100h, 0x140h, 0x180h, 0x200h, 0x240h, 0x280h, -0x300h, 0x340h, 0x380h. This I/O address must be reflected in the DIP -switches of *all* of the Rocketport cards. - -The second, third, and fourth RocketPort cards require a 64-byte -contiguous block of I/O addresses, starting at one of the following -I/O addresses: 0x100h, 0x140h, 0x180h, 0x1C0h, 0x200h, 0x240h, 0x280h, -0x2C0h, 0x300h, 0x340h, 0x380h, 0x3C0h. The I/O address used by the -second, third, and fourth Rocketport cards (if present) are set via -software control. The DIP switch settings for the I/O address must be -set to the value of the first Rocketport cards. - -In order to distinguish each of the card from the others, each card -must have a unique board ID set on the dip switches. The first -Rocketport board must be set with the DIP switches corresponding to -the first board, the second board must be set with the DIP switches -corresponding to the second board, etc. IMPORTANT: The board ID is -the only place where the DIP switch settings should differ between the -various Rocketport boards in a system. - -The I/O address range used by any of the RocketPort cards must not -conflict with any other cards in the system, including other -RocketPort cards. Below, you will find a list of commonly used I/O -address ranges which may be in use by other devices in your system. -On a Linux system, "cat /proc/ioports" will also be helpful in -identifying what I/O addresses are being used by devices on your -system. - -Remember, the FIRST RocketPort uses 68 I/O addresses. So, if you set it -for 0x100, it will occupy 0x100 to 0x143. This would mean that you -CAN NOT set the second, third or fourth board for address 0x140 since -the first 4 bytes of that range are used by the first board. You would -need to set the second, third, or fourth board to one of the next available -blocks such as 0x180. - -RocketPort and RocketPort RA SW1 Settings:: - - +-------------------------------+ - | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | - +-------+-------+---------------+ - | Unused| Card | I/O Port Block| - +-------------------------------+ - - DIP Switches DIP Switches - 7 8 6 5 - =================== =================== - On On UNUSED, MUST BE ON. On On First Card <==== Default - On Off Second Card - Off On Third Card - Off Off Fourth Card - - DIP Switches I/O Address Range - 4 3 2 1 Used by the First Card - ===================================== - On Off On Off 100-143 - On Off Off On 140-183 - On Off Off Off 180-1C3 <==== Default - Off On On Off 200-243 - Off On Off On 240-283 - Off On Off Off 280-2C3 - Off Off On Off 300-343 - Off Off Off On 340-383 - Off Off Off Off 380-3C3 - -Reporting Bugs --------------- - -For technical support, please provide the following -information: Driver version, kernel release, distribution of -kernel, and type of board you are using. Error messages and log -printouts port configuration details are especially helpful. - -USA: - :Phone: (612) 494-4100 - :FAX: (612) 494-4199 - :email: support@comtrol.com - -Comtrol Europe: - :Phone: +44 (0) 1 869 323-220 - :FAX: +44 (0) 1 869 323-211 - :email: support@comtrol.co.uk - -Web: http://www.comtrol.com -FTP: ftp.comtrol.com diff --git a/Documentation/driver-api/surface_aggregator/client.rst b/Documentation/driver-api/surface_aggregator/client.rst index 26d13085a117..e519d374c378 100644 --- a/Documentation/driver-api/surface_aggregator/client.rst +++ b/Documentation/driver-api/surface_aggregator/client.rst @@ -248,7 +248,7 @@ This example defines a function .. code-block:: c - int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg); + static int __ssam_tmp_perf_mode_set(struct ssam_controller *ctrl, const __le32 *arg); executing the specified request, with the controller passed in when calling said function. In this example, the argument is provided via the ``arg`` @@ -296,7 +296,7 @@ This invocation of the macro defines a function .. code-block:: c - int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret); + static int ssam_bat_get_sta(struct ssam_device *sdev, __le32 *ret); executing the specified request, using the device IDs and controller given in the client device. The full list of such macros for client devices is: diff --git a/Documentation/driver-api/surface_aggregator/clients/dtx.rst b/Documentation/driver-api/surface_aggregator/clients/dtx.rst new file mode 100644 index 000000000000..e7e7c20007f0 --- /dev/null +++ b/Documentation/driver-api/surface_aggregator/clients/dtx.rst @@ -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. diff --git a/Documentation/driver-api/surface_aggregator/clients/index.rst b/Documentation/driver-api/surface_aggregator/clients/index.rst index 3ccabce23271..98ea9946b8a2 100644 --- a/Documentation/driver-api/surface_aggregator/clients/index.rst +++ b/Documentation/driver-api/surface_aggregator/clients/index.rst @@ -11,6 +11,7 @@ This is the documentation for client drivers themselves. Refer to :maxdepth: 1 cdev + dtx san .. only:: subproject and html |