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__ */ 311