xen/kbdif: update protocol description
[muen/linux.git] / include / xen / interface / io / kbdif.h
1 /*
2  * kbdif.h -- Xen virtual keyboard/mouse
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
20  * DEALINGS IN THE SOFTWARE.
21  *
22  * Copyright (C) 2005 Anthony Liguori <aliguori@us.ibm.com>
23  * Copyright (C) 2006 Red Hat, Inc., Markus Armbruster <armbru@redhat.com>
24  */
25
26 #ifndef __XEN_PUBLIC_IO_KBDIF_H__
27 #define __XEN_PUBLIC_IO_KBDIF_H__
28
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  */
110
111 /*
112  * EVENT CODES.
113  */
114
115 #define XENKBD_TYPE_MOTION              1
116 #define XENKBD_TYPE_RESERVED            2
117 #define XENKBD_TYPE_KEY                 3
118 #define XENKBD_TYPE_POS                 4
119
120 /*
121  * CONSTANTS, XENSTORE FIELD AND PATH NAME STRINGS, HELPERS.
122  */
123
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)
183  */
184
185 struct xenkbd_motion {
186         uint8_t type;
187         int32_t rel_x;
188         int32_t rel_y;
189         int32_t rel_z;
190 };
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
211 struct xenkbd_key {
212         uint8_t type;
213         uint8_t pressed;
214         uint32_t keycode;
215 };
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
241 struct xenkbd_position {
242         uint8_t type;
243         int32_t abs_x;
244         int32_t abs_y;
245         int32_t rel_z;
246 };
247
248 #define XENKBD_IN_EVENT_SIZE 40
249
250 union xenkbd_in_event {
251         uint8_t type;
252         struct xenkbd_motion motion;
253         struct xenkbd_key key;
254         struct xenkbd_position pos;
255         char pad[XENKBD_IN_EVENT_SIZE];
256 };
257
258 /*
259  *****************************************************************************
260  *                            Frontend to backend events
261  *****************************************************************************
262  *
263  * Out events may be sent only when requested by backend, and receipt
264  * of an unknown out event is an error.
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
274  */
275
276 #define XENKBD_OUT_EVENT_SIZE 40
277
278 union xenkbd_out_event {
279         uint8_t type;
280         char pad[XENKBD_OUT_EVENT_SIZE];
281 };
282
283 /*
284  *****************************************************************************
285  *                            Shared page
286  *****************************************************************************
287  */
288
289 #define XENKBD_IN_RING_SIZE 2048
290 #define XENKBD_IN_RING_LEN (XENKBD_IN_RING_SIZE / XENKBD_IN_EVENT_SIZE)
291 #define XENKBD_IN_RING_OFFS 1024
292 #define XENKBD_IN_RING(page) \
293         ((union xenkbd_in_event *)((char *)(page) + XENKBD_IN_RING_OFFS))
294 #define XENKBD_IN_RING_REF(page, idx) \
295         (XENKBD_IN_RING((page))[(idx) % XENKBD_IN_RING_LEN])
296
297 #define XENKBD_OUT_RING_SIZE 1024
298 #define XENKBD_OUT_RING_LEN (XENKBD_OUT_RING_SIZE / XENKBD_OUT_EVENT_SIZE)
299 #define XENKBD_OUT_RING_OFFS (XENKBD_IN_RING_OFFS + XENKBD_IN_RING_SIZE)
300 #define XENKBD_OUT_RING(page) \
301         ((union xenkbd_out_event *)((char *)(page) + XENKBD_OUT_RING_OFFS))
302 #define XENKBD_OUT_RING_REF(page, idx) \
303         (XENKBD_OUT_RING((page))[(idx) % XENKBD_OUT_RING_LEN])
304
305 struct xenkbd_page {
306         uint32_t in_cons, in_prod;
307         uint32_t out_cons, out_prod;
308 };
309
310 #endif /* __XEN_PUBLIC_IO_KBDIF_H__ */