linux/surface_aggregator/dtx.h

0001 /* SPDX-License-Identifier: GPL-2.0+ WITH Linux-syscall-note */
0002 /*
0003  * Surface DTX (clipboard detachment system driver) user-space interface.
0004  *
0005  * Definitions, structs, and IOCTLs for the /dev/surface/dtx misc device. This
0006  * device allows user-space to control the clipboard detachment process on
0007  * Surface Book series devices.
0008  *
0009  * Copyright (C) 2020-2021 Maximilian Luz <luzmaximilian@gmail.com>
0010  */
0011
0012 #ifndef _UAPI_LINUX_SURFACE_AGGREGATOR_DTX_H
0013 #define _UAPI_LINUX_SURFACE_AGGREGATOR_DTX_H
0014
0015 #include <linux/ioctl.h>
0016 #include <linux/types.h>
0017
0018 /* Status/error categories */
0019 #define SDTX_CATEGORY_STATUS        0x0000
0020 #define SDTX_CATEGORY_RUNTIME_ERROR 0x1000
0021 #define SDTX_CATEGORY_HARDWARE_ERROR    0x2000
0022 #define SDTX_CATEGORY_UNKNOWN       0xf000
0023
0024 #define SDTX_CATEGORY_MASK      0xf000
0025 #define SDTX_CATEGORY(value)        ((value) & SDTX_CATEGORY_MASK)
0026
0027 #define SDTX_STATUS(code)       ((code) | SDTX_CATEGORY_STATUS)
0028 #define SDTX_ERR_RT(code)       ((code) | SDTX_CATEGORY_RUNTIME_ERROR)
0029 #define SDTX_ERR_HW(code)       ((code) | SDTX_CATEGORY_HARDWARE_ERROR)
0030 #define SDTX_UNKNOWN(code)      ((code) | SDTX_CATEGORY_UNKNOWN)
0031
0032 #define SDTX_SUCCESS(value)     (SDTX_CATEGORY(value) == SDTX_CATEGORY_STATUS)
0033
0034 /* Latch status values */
0035 #define SDTX_LATCH_CLOSED       SDTX_STATUS(0x00)
0036 #define SDTX_LATCH_OPENED       SDTX_STATUS(0x01)
0037
0038 /* Base state values */
0039 #define SDTX_BASE_DETACHED      SDTX_STATUS(0x00)
0040 #define SDTX_BASE_ATTACHED      SDTX_STATUS(0x01)
0041
0042 /* Runtime errors (non-critical) */
0043 #define SDTX_DETACH_NOT_FEASIBLE    SDTX_ERR_RT(0x01)
0044 #define SDTX_DETACH_TIMEDOUT        SDTX_ERR_RT(0x02)
0045
0046 /* Hardware errors (critical) */
0047 #define SDTX_ERR_FAILED_TO_OPEN     SDTX_ERR_HW(0x01)
0048 #define SDTX_ERR_FAILED_TO_REMAIN_OPEN  SDTX_ERR_HW(0x02)
0049 #define SDTX_ERR_FAILED_TO_CLOSE    SDTX_ERR_HW(0x03)
0050
0051 /* Base types */
0052 #define SDTX_DEVICE_TYPE_HID        0x0100
0053 #define SDTX_DEVICE_TYPE_SSH        0x0200
0054
0055 #define SDTX_DEVICE_TYPE_MASK       0x0f00
0056 #define SDTX_DEVICE_TYPE(value)     ((value) & SDTX_DEVICE_TYPE_MASK)
0057
0058 #define SDTX_BASE_TYPE_HID(id)      ((id) | SDTX_DEVICE_TYPE_HID)
0059 #define SDTX_BASE_TYPE_SSH(id)      ((id) | SDTX_DEVICE_TYPE_SSH)
0060
0061 /**
0062  * enum sdtx_device_mode - Mode describing how (and if) the clipboard is
0063  * attached to the base of the device.
0064  * @SDTX_DEVICE_MODE_TABLET: The clipboard is detached from the base and the
0065  *                           device operates as tablet.
0066  * @SDTX_DEVICE_MODE_LAPTOP: The clipboard is attached normally to the base
0067  *                           and the device operates as laptop.
0068  * @SDTX_DEVICE_MODE_STUDIO: The clipboard is attached to the base in reverse.
0069  *                           The device operates as tablet with keyboard and
0070  *                           touchpad deactivated, however, the base battery
0071  *                           and, if present in the specific device model, dGPU
0072  *                           are available to the system.
0073  */
0074 enum sdtx_device_mode {
0075     SDTX_DEVICE_MODE_TABLET     = 0x00,
0076     SDTX_DEVICE_MODE_LAPTOP     = 0x01,
0077     SDTX_DEVICE_MODE_STUDIO     = 0x02,
0078 };
0079
0080 /**
0081  * struct sdtx_event - Event provided by reading from the DTX device file.
0082  * @length: Length of the event payload, in bytes.
0083  * @code:   Event code, detailing what type of event this is.
0084  * @data:   Payload of the event, containing @length bytes.
0085  *
0086  * See &enum sdtx_event_code for currently valid event codes.
0087  */
0088 struct sdtx_event {
0089     __u16 length;
0090     __u16 code;
0091     __u8 data[];
0092 } __attribute__((__packed__));
0093
0094 /**
0095  * enum sdtx_event_code - Code describing the type of an event.
0096  * @SDTX_EVENT_REQUEST:         Detachment request event type.
0097  * @SDTX_EVENT_CANCEL:          Cancel detachment process event type.
0098  * @SDTX_EVENT_BASE_CONNECTION: Base/clipboard connection change event type.
0099  * @SDTX_EVENT_LATCH_STATUS:    Latch status change event type.
0100  * @SDTX_EVENT_DEVICE_MODE:     Device mode change event type.
0101  *
0102  * Used in &struct sdtx_event to describe the type of the event. Further event
0103  * codes are reserved for future use. Any event parser should be able to
0104  * gracefully handle unknown events, i.e. by simply skipping them.
0105  *
0106  * Consult the DTX user-space interface documentation for details regarding
0107  * the individual event types.
0108  */
0109 enum sdtx_event_code {
0110     SDTX_EVENT_REQUEST      = 1,
0111     SDTX_EVENT_CANCEL       = 2,
0112     SDTX_EVENT_BASE_CONNECTION  = 3,
0113     SDTX_EVENT_LATCH_STATUS     = 4,
0114     SDTX_EVENT_DEVICE_MODE      = 5,
0115 };
0116
0117 /**
0118  * struct sdtx_base_info - Describes if and what type of base is connected.
0119  * @state:   The state of the connection. Valid values are %SDTX_BASE_DETACHED,
0120  *           %SDTX_BASE_ATTACHED, and %SDTX_DETACH_NOT_FEASIBLE (in case a base
0121  *           is attached but low clipboard battery prevents detachment). Other
0122  *           values are currently reserved.
0123  * @base_id: The type of base connected. Zero if no base is connected.
0124  */
0125 struct sdtx_base_info {
0126     __u16 state;
0127     __u16 base_id;
0128 } __attribute__((__packed__));
0129
0130 /* IOCTLs */
0131 #define SDTX_IOCTL_EVENTS_ENABLE    _IO(0xa5, 0x21)
0132 #define SDTX_IOCTL_EVENTS_DISABLE   _IO(0xa5, 0x22)
0133
0134 #define SDTX_IOCTL_LATCH_LOCK       _IO(0xa5, 0x23)
0135 #define SDTX_IOCTL_LATCH_UNLOCK     _IO(0xa5, 0x24)
0136
0137 #define SDTX_IOCTL_LATCH_REQUEST    _IO(0xa5, 0x25)
0138 #define SDTX_IOCTL_LATCH_CONFIRM    _IO(0xa5, 0x26)
0139 #define SDTX_IOCTL_LATCH_HEARTBEAT  _IO(0xa5, 0x27)
0140 #define SDTX_IOCTL_LATCH_CANCEL     _IO(0xa5, 0x28)
0141
0142 #define SDTX_IOCTL_GET_BASE_INFO    _IOR(0xa5, 0x29, struct sdtx_base_info)
0143 #define SDTX_IOCTL_GET_DEVICE_MODE  _IOR(0xa5, 0x2a, __u16)
0144 #define SDTX_IOCTL_GET_LATCH_STATUS _IOR(0xa5, 0x2b, __u16)
0145
0146 #endif /* _UAPI_LINUX_SURFACE_AGGREGATOR_DTX_H */