aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorOleksandr Andrushchenko <oleksandr_andrushchenko@epam.com>2017-04-10 02:25:26 -0400
committerJuergen Gross <jgross@suse.com>2017-05-02 05:12:50 -0400
commit8ec9dd0e69cfaab05649ed7ab3838eb4eea96081 (patch)
tree324017f585d7b43c7477d6155538e0e2f1b43c14
parent7f25483a88291ed6b2cbe761ee2a30a69674b131 (diff)
xen/kbdif: update protocol description
The patch clarifies the protocol that is used by the PV keyboard drivers. Signed-off-by: Oleksandr Andrushchenko <oleksandr_andrushchenko@epam.com> Acked-by: Juergen Gross <jgross@suse.com> Signed-off-by: Juergen Gross <jgross@suse.com>
Diffstat
-rw-r--r--include/xen/interface/io/kbdif.h248
1 files changed, 221 insertions, 27 deletions
diff --git a/include/xen/interface/io/kbdif.h b/include/xen/interface/io/kbdif.h
index 8066c7849fbe..7adfb15fec9d 100644
--- a/include/xen/interface/io/kbdif.h
+++ b/include/xen/interface/io/kbdif.h
@@ -26,43 +26,223 @@
26#ifndef __XEN_PUBLIC_IO_KBDIF_H__ 26#ifndef __XEN_PUBLIC_IO_KBDIF_H__
27#define __XEN_PUBLIC_IO_KBDIF_H__ 27#define __XEN_PUBLIC_IO_KBDIF_H__
28 28
29/* In events (backend -> frontend) */ 29/*
30 *****************************************************************************
31 * Feature and Parameter Negotiation
32 *****************************************************************************
33 *
34 * The two halves of a para-virtual driver utilize nodes within
35 * XenStore to communicate capabilities and to negotiate operating parameters.
36 * This section enumerates these nodes which reside in the respective front and
37 * backend portions of XenStore, following XenBus convention.
38 *
39 * All data in XenStore is stored as strings. Nodes specifying numeric
40 * values are encoded in decimal. Integer value ranges listed below are
41 * expressed as fixed sized integer types capable of storing the conversion
42 * of a properly formated node string, without loss of information.
43 *
44 *****************************************************************************
45 * Backend XenBus Nodes
46 *****************************************************************************
47 *
48 *---------------------------- Features supported ----------------------------
49 *
50 * Capable backend advertises supported features by publishing
51 * corresponding entries in XenStore and puts 1 as the value of the entry.
52 * If a feature is not supported then 0 must be set or feature entry omitted.
53 *
54 * feature-abs-pointer
55 * Values: <uint>
56 *
57 * Backends, which support reporting of absolute coordinates for pointer
58 * device should set this to 1.
59 *
60 *------------------------- Pointer Device Parameters ------------------------
61 *
62 * width
63 * Values: <uint>
64 *
65 * Maximum X coordinate (width) to be used by the frontend
66 * while reporting input events, pixels, [0; UINT32_MAX].
67 *
68 * height
69 * Values: <uint>
70 *
71 * Maximum Y coordinate (height) to be used by the frontend
72 * while reporting input events, pixels, [0; UINT32_MAX].
73 *
74 *****************************************************************************
75 * Frontend XenBus Nodes
76 *****************************************************************************
77 *
78 *------------------------------ Feature request -----------------------------
79 *
80 * Capable frontend requests features from backend via setting corresponding
81 * entries to 1 in XenStore. Requests for features not advertised as supported
82 * by the backend have no effect.
83 *
84 * request-abs-pointer
85 * Values: <uint>
86 *
87 * Request backend to report absolute pointer coordinates
88 * (XENKBD_TYPE_POS) instead of relative ones (XENKBD_TYPE_MOTION).
89 *
90 *----------------------- Request Transport Parameters -----------------------
91 *
92 * event-channel
93 * Values: <uint>
94 *
95 * The identifier of the Xen event channel used to signal activity
96 * in the ring buffer.
97 *
98 * page-gref
99 * Values: <uint>
100 *
101 * The Xen grant reference granting permission for the backend to map
102 * a sole page in a single page sized event ring buffer.
103 *
104 * page-ref
105 * Values: <uint>
106 *
107 * OBSOLETE, not recommended for use.
108 * PFN of the shared page.
109 */
30 110
31/* 111/*
32 * Frontends should ignore unknown in events. 112 * EVENT CODES.
33 */ 113 */
34 114
35/* Pointer movement event */ 115#define XENKBD_TYPE_MOTION 1
36#define XENKBD_TYPE_MOTION 1 116#define XENKBD_TYPE_RESERVED 2
37/* Event type 2 currently not used */ 117#define XENKBD_TYPE_KEY 3
38/* Key event (includes pointer buttons) */ 118#define XENKBD_TYPE_POS 4
39#define XENKBD_TYPE_KEY 3 119
40/* 120/*
41 * Pointer position event 121 * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS.
42 * Capable backend sets feature-abs-pointer in xenstore. 122 */
43 * Frontend requests ot instead of XENKBD_TYPE_MOTION by setting 123
44 * request-abs-update in xenstore. 124#define XENKBD_DRIVER_NAME "vkbd"
125
126#define XENKBD_FIELD_FEAT_ABS_POINTER "feature-abs-pointer"
127#define XENKBD_FIELD_REQ_ABS_POINTER "request-abs-pointer"
128#define XENKBD_FIELD_RING_GREF "page-gref"
129#define XENKBD_FIELD_EVT_CHANNEL "event-channel"
130#define XENKBD_FIELD_WIDTH "width"
131#define XENKBD_FIELD_HEIGHT "height"
132
133/* OBSOLETE, not recommended for use */
134#define XENKBD_FIELD_RING_REF "page-ref"
135
136/*
137 *****************************************************************************
138 * Description of the protocol between frontend and backend driver.
139 *****************************************************************************
140 *
141 * The two halves of a Para-virtual driver communicate with
142 * each other using a shared page and an event channel.
143 * Shared page contains a ring with event structures.
144 *
145 * All reserved fields in the structures below must be 0.
146 *
147 *****************************************************************************
148 * Backend to frontend events
149 *****************************************************************************
150 *
151 * Frontends should ignore unknown in events.
152 * All event packets have the same length (40 octets)
153 * All event packets have common header:
154 *
155 * 0 octet
156 * +-----------------+
157 * | type |
158 * +-----------------+
159 * type - uint8_t, event code, XENKBD_TYPE_???
160 *
161 *
162 * Pointer relative movement event
163 * 0 1 2 3 octet
164 * +----------------+----------------+----------------+----------------+
165 * | _TYPE_MOTION | reserved | 4
166 * +----------------+----------------+----------------+----------------+
167 * | rel_x | 8
168 * +----------------+----------------+----------------+----------------+
169 * | rel_y | 12
170 * +----------------+----------------+----------------+----------------+
171 * | rel_z | 16
172 * +----------------+----------------+----------------+----------------+
173 * | reserved | 20
174 * +----------------+----------------+----------------+----------------+
175 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
176 * +----------------+----------------+----------------+----------------+
177 * | reserved | 40
178 * +----------------+----------------+----------------+----------------+
179 *
180 * rel_x - int32_t, relative X motion
181 * rel_y - int32_t, relative Y motion
182 * rel_z - int32_t, relative Z motion (wheel)
45 */ 183 */
46#define XENKBD_TYPE_POS 4
47 184
48struct xenkbd_motion { 185struct xenkbd_motion {
49 uint8_t type; /* XENKBD_TYPE_MOTION */ 186 uint8_t type;
50 int32_t rel_x; /* relative X motion */ 187 int32_t rel_x;
51 int32_t rel_y; /* relative Y motion */ 188 int32_t rel_y;
52 int32_t rel_z; /* relative Z motion (wheel) */ 189 int32_t rel_z;
53}; 190};
54 191
192/*
193 * Key event (includes pointer buttons)
194 * 0 1 2 3 octet
195 * +----------------+----------------+----------------+----------------+
196 * | _TYPE_KEY | pressed | reserved | 4
197 * +----------------+----------------+----------------+----------------+
198 * | keycode | 8
199 * +----------------+----------------+----------------+----------------+
200 * | reserved | 12
201 * +----------------+----------------+----------------+----------------+
202 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
203 * +----------------+----------------+----------------+----------------+
204 * | reserved | 40
205 * +----------------+----------------+----------------+----------------+
206 *
207 * pressed - uint8_t, 1 if pressed; 0 otherwise
208 * keycode - uint32_t, KEY_* from linux/input.h
209 */
210
55struct xenkbd_key { 211struct xenkbd_key {
56 uint8_t type; /* XENKBD_TYPE_KEY */ 212 uint8_t type;
57 uint8_t pressed; /* 1 if pressed; 0 otherwise */ 213 uint8_t pressed;
58 uint32_t keycode; /* KEY_* from linux/input.h */ 214 uint32_t keycode;
59}; 215};
60 216
217/*
218 * Pointer absolute position event
219 * 0 1 2 3 octet
220 * +----------------+----------------+----------------+----------------+
221 * | _TYPE_POS | reserved | 4
222 * +----------------+----------------+----------------+----------------+
223 * | abs_x | 8
224 * +----------------+----------------+----------------+----------------+
225 * | abs_y | 12
226 * +----------------+----------------+----------------+----------------+
227 * | rel_z | 16
228 * +----------------+----------------+----------------+----------------+
229 * | reserved | 20
230 * +----------------+----------------+----------------+----------------+
231 * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
232 * +----------------+----------------+----------------+----------------+
233 * | reserved | 40
234 * +----------------+----------------+----------------+----------------+
235 *
236 * abs_x - int32_t, absolute X position (in FB pixels)
237 * abs_y - int32_t, absolute Y position (in FB pixels)
238 * rel_z - int32_t, relative Z motion (wheel)
239 */
240
61struct xenkbd_position { 241struct xenkbd_position {
62 uint8_t type; /* XENKBD_TYPE_POS */ 242 uint8_t type;
63 int32_t abs_x; /* absolute X position (in FB pixels) */ 243 int32_t abs_x;
64 int32_t abs_y; /* absolute Y position (in FB pixels) */ 244 int32_t abs_y;
65 int32_t rel_z; /* relative Z motion (wheel) */ 245 int32_t rel_z;
66}; 246};
67 247
68#define XENKBD_IN_EVENT_SIZE 40 248#define XENKBD_IN_EVENT_SIZE 40
@@ -75,12 +255,22 @@ union xenkbd_in_event {
75 char pad[XENKBD_IN_EVENT_SIZE]; 255 char pad[XENKBD_IN_EVENT_SIZE];
76}; 256};
77 257
78/* Out events (frontend -> backend) */
79
80/* 258/*
259 *****************************************************************************
260 * Frontend to backend events
261 *****************************************************************************
262 *
81 * Out events may be sent only when requested by backend, and receipt 263 * Out events may be sent only when requested by backend, and receipt
82 * of an unknown out event is an error. 264 * of an unknown out event is an error.
83 * No out events currently defined. 265 * No out events currently defined.
266
267 * All event packets have the same length (40 octets)
268 * All event packets have common header:
269 * 0 octet
270 * +-----------------+
271 * | type |
272 * +-----------------+
273 * type - uint8_t, event code
84 */ 274 */
85 275
86#define XENKBD_OUT_EVENT_SIZE 40 276#define XENKBD_OUT_EVENT_SIZE 40
@@ -90,7 +280,11 @@ union xenkbd_out_event {
90 char pad[XENKBD_OUT_EVENT_SIZE]; 280 char pad[XENKBD_OUT_EVENT_SIZE];
91}; 281};
92 282
93/* shared page */ 283/*
284 *****************************************************************************
285 * Shared page
286 *****************************************************************************
287 */
94 288
95#define XENKBD_IN_RING_SIZE 2048 289#define XENKBD_IN_RING_SIZE 2048
96#define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE) 290#define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE)
@@ -113,4 +307,4 @@ struct xenkbd_page {
113 uint32_t out_cons, out_prod; 307 uint32_t out_cons, out_prod;
114}; 308};
115 309
116#endif 310#endif /* __XEN_PUBLIC_IO_KBDIF_H__ */
generated by cgit v1.2.2 (git 2.25.0) at 2025-08-23 05:42:35 -0400