DevPS2.cpp@ 45238

Last change on this file since 45238 was 45025, checked in by vboxsync, 12 years ago
Update PDMDEVREG initialization comment so they refer to pfnMemSetup instead of pfnIOCtl.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 53.4 KB

Line
1	/* $Id: DevPS2.cpp 45025 2013-03-13 16:45:15Z vboxsync $ */
2	/** @file
3	* DevPS2 - PS/2 keyboard & mouse controller device.
4	*/
5
6	/*
7	* Copyright (C) 2006-2012 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	* --------------------------------------------------------------------
17	*
18	* This code is based on:
19	*
20	* QEMU PC keyboard emulation (revision 1.12)
21	*
22	* Copyright (c) 2003 Fabrice Bellard
23	*
24	* Permission is hereby granted, free of charge, to any person obtaining a copy
25	* of this software and associated documentation files (the "Software"), to deal
26	* in the Software without restriction, including without limitation the rights
27	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
28	* copies of the Software, and to permit persons to whom the Software is
29	* furnished to do so, subject to the following conditions:
30	*
31	* The above copyright notice and this permission notice shall be included in
32	* all copies or substantial portions of the Software.
33	*
34	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
35	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
36	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
37	* THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
38	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
39	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
40	* THE SOFTWARE.
41	*
42	*/
43
44	/*******************************************************************************
45	* Header Files *
46	*******************************************************************************/
47	#define LOG_GROUP LOG_GROUP_DEV_KBD
48	#include "vl_vbox.h"
49	#include <VBox/vmm/pdmdev.h>
50	#include <iprt/assert.h>
51	#include <iprt/uuid.h>
52
53	#include "VBoxDD.h"
54	#include "PS2Dev.h"
55
56	#define PCKBD_SAVED_STATE_VERSION 6
57
58
59	#ifndef VBOX_DEVICE_STRUCT_TESTCASE
60	/*******************************************************************************
61	* Internal Functions *
62	*******************************************************************************/
63	RT_C_DECLS_BEGIN
64	PDMBOTHCBDECL(int) kbdIOPortDataRead(PPDMDEVINS pDevIns, void pvUser, RTIOPORT Port, uint32_t pu32, unsigned cb);
65	PDMBOTHCBDECL(int) kbdIOPortDataWrite(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t u32, unsigned cb);
66	PDMBOTHCBDECL(int) kbdIOPortStatusRead(PPDMDEVINS pDevIns, void pvUser, RTIOPORT Port, uint32_t pu32, unsigned cb);
67	PDMBOTHCBDECL(int) kbdIOPortCommandWrite(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t u32, unsigned cb);
68	RT_C_DECLS_END
69	#endif /* !VBOX_DEVICE_STRUCT_TESTCASE */
70
71	/* debug PC keyboard */
72	#define DEBUG_KBD
73
74	/* debug PC keyboard : only mouse */
75	#define DEBUG_MOUSE
76
77	/* Keyboard Controller Commands */
78	#define KBD_CCMD_READ_MODE 0x20 /* Read mode bits */
79	#define KBD_CCMD_WRITE_MODE 0x60 /* Write mode bits */
80	#define KBD_CCMD_GET_VERSION 0xA1 /* Get controller version */
81	#define KBD_CCMD_MOUSE_DISABLE 0xA7 /* Disable mouse interface */
82	#define KBD_CCMD_MOUSE_ENABLE 0xA8 /* Enable mouse interface */
83	#define KBD_CCMD_TEST_MOUSE 0xA9 /* Mouse interface test */
84	#define KBD_CCMD_SELF_TEST 0xAA /* Controller self test */
85	#define KBD_CCMD_KBD_TEST 0xAB /* Keyboard interface test */
86	#define KBD_CCMD_KBD_DISABLE 0xAD /* Keyboard interface disable */
87	#define KBD_CCMD_KBD_ENABLE 0xAE /* Keyboard interface enable */
88	#define KBD_CCMD_READ_INPORT 0xC0 /* read input port */
89	#define KBD_CCMD_READ_OUTPORT 0xD0 /* read output port */
90	#define KBD_CCMD_WRITE_OUTPORT 0xD1 /* write output port */
91	#define KBD_CCMD_WRITE_OBUF 0xD2
92	#define KBD_CCMD_WRITE_AUX_OBUF 0xD3 /* Write to output buffer as if
93	initiated by the auxiliary device */
94	#define KBD_CCMD_WRITE_MOUSE 0xD4 /* Write the following byte to the mouse */
95	#define KBD_CCMD_DISABLE_A20 0xDD /* HP vectra only ? */
96	#define KBD_CCMD_ENABLE_A20 0xDF /* HP vectra only ? */
97	#define KBD_CCMD_READ_TSTINP 0xE0 /* Read test inputs T0, T1 */
98	#define KBD_CCMD_RESET 0xFE
99
100	/* Status Register Bits */
101	#define KBD_STAT_OBF 0x01 /* Keyboard output buffer full */
102	#define KBD_STAT_IBF 0x02 /* Keyboard input buffer full */
103	#define KBD_STAT_SELFTEST 0x04 /* Self test successful */
104	#define KBD_STAT_CMD 0x08 /* Last write was a command write (0=data) */
105	#define KBD_STAT_UNLOCKED 0x10 /* Zero if keyboard locked */
106	#define KBD_STAT_MOUSE_OBF 0x20 /* Mouse output buffer full */
107	#define KBD_STAT_GTO 0x40 /* General receive/xmit timeout */
108	#define KBD_STAT_PERR 0x80 /* Parity error */
109
110	/* Controller Mode Register Bits */
111	#define KBD_MODE_KBD_INT 0x01 /* Keyboard data generate IRQ1 */
112	#define KBD_MODE_MOUSE_INT 0x02 /* Mouse data generate IRQ12 */
113	#define KBD_MODE_SYS 0x04 /* The system flag (?) */
114	#define KBD_MODE_NO_KEYLOCK 0x08 /* The keylock doesn't affect the keyboard if set */
115	#define KBD_MODE_DISABLE_KBD 0x10 /* Disable keyboard interface */
116	#define KBD_MODE_DISABLE_MOUSE 0x20 /* Disable mouse interface */
117	#define KBD_MODE_KCC 0x40 /* Scan code conversion to PC format */
118	#define KBD_MODE_RFU 0x80
119
120	/* Mouse Commands */
121	#define AUX_SET_SCALE11 0xE6 /* Set 1:1 scaling */
122	#define AUX_SET_SCALE21 0xE7 /* Set 2:1 scaling */
123	#define AUX_SET_RES 0xE8 /* Set resolution */
124	#define AUX_GET_SCALE 0xE9 /* Get scaling factor */
125	#define AUX_SET_STREAM 0xEA /* Set stream mode */
126	#define AUX_POLL 0xEB /* Poll */
127	#define AUX_RESET_WRAP 0xEC /* Reset wrap mode */
128	#define AUX_SET_WRAP 0xEE /* Set wrap mode */
129	#define AUX_SET_REMOTE 0xF0 /* Set remote mode */
130	#define AUX_GET_TYPE 0xF2 /* Get type */
131	#define AUX_SET_SAMPLE 0xF3 /* Set sample rate */
132	#define AUX_ENABLE_DEV 0xF4 /* Enable aux device */
133	#define AUX_DISABLE_DEV 0xF5 /* Disable aux device */
134	#define AUX_SET_DEFAULT 0xF6
135	#define AUX_RESET 0xFF /* Reset aux device */
136	#define AUX_ACK 0xFA /* Command byte ACK. */
137	#define AUX_NACK 0xFE /* Command byte NACK. */
138
139	#define MOUSE_STATUS_REMOTE 0x40
140	#define MOUSE_STATUS_ENABLED 0x20
141	#define MOUSE_STATUS_SCALE21 0x10
142
143	/** Supported mouse protocols */
144	enum
145	{
146	MOUSE_PROT_PS2 = 0,
147	MOUSE_PROT_IMPS2 = 3,
148	MOUSE_PROT_IMEX = 4
149	};
150
151	/** @name Mouse flags */
152	/** @{ */
153	/** IMEX horizontal scroll-wheel mode is active */
154	# define MOUSE_REPORT_HORIZONTAL 0x01
155	/** @} */
156
157	#define MOUSE_CMD_QUEUE_SIZE 8
158
159	typedef struct {
160	uint8_t data[MOUSE_CMD_QUEUE_SIZE];
161	int rptr, wptr, count;
162	} MouseCmdQueue;
163
164
165	#define MOUSE_EVENT_QUEUE_SIZE 256
166
167	typedef struct
168	{
169	uint8_t data[MOUSE_EVENT_QUEUE_SIZE];
170	int rptr;
171	int wptr;
172	int count;
173	} MouseEventQueue;
174
175	/**
176	* The keyboard controller/device state.
177	*
178	* @note We use the default critical section for serialize data access.
179	*/
180	typedef struct KBDState
181	{
182	MouseCmdQueue mouse_command_queue;
183	MouseEventQueue mouse_event_queue;
184	uint8_t write_cmd; /* if non zero, write data to port 60 is expected */
185	uint8_t status;
186	uint8_t mode;
187	uint8_t dbbout; /* data buffer byte */
188	/* keyboard state */
189	int32_t translate;
190	int32_t xlat_state;
191	/* mouse state */
192	int32_t mouse_write_cmd;
193	uint8_t mouse_status;
194	uint8_t mouse_resolution;
195	uint8_t mouse_sample_rate;
196	uint8_t mouse_wrap;
197	uint8_t mouse_type; /* MOUSE_PROT_PS2, _IMPS/2, _IMEX */
198	uint8_t mouse_detect_state;
199	int32_t mouse_dx; /* current values, needed for 'poll' mode */
200	int32_t mouse_dy;
201	int32_t mouse_dz;
202	int32_t mouse_dw;
203	int32_t mouse_flags;
204	uint8_t mouse_buttons;
205	uint8_t mouse_buttons_reported;
206
207	uint32_t Alignment0;
208
209	/** Pointer to the device instance - RC. */
210	PPDMDEVINSRC pDevInsRC;
211	/** Pointer to the device instance - R3 . */
212	PPDMDEVINSR3 pDevInsR3;
213	/** Pointer to the device instance. */
214	PPDMDEVINSR0 pDevInsR0;
215
216	/** Keyboard state (implemented in separate PS2K module). */
217	#ifdef VBOX_DEVICE_STRUCT_TESTCASE
218	uint8_t KbdFiller[PS2K_STRUCT_FILLER];
219	#else
220	PS2K Kbd;
221	#endif
222
223	/**
224	* Mouse port - LUN#1.
225	*
226	* @implements PDMIBASE
227	* @implements PDMIMOUSEPORT
228	*/
229	struct
230	{
231	/** The base interface for the mouse port. */
232	PDMIBASE IBase;
233	/** The mouse port base interface. */
234	PDMIMOUSEPORT IPort;
235
236	/** The base interface of the attached mouse driver. */
237	R3PTRTYPE(PPDMIBASE) pDrvBase;
238	/** The mouse interface of the attached mouse driver. */
239	R3PTRTYPE(PPDMIMOUSECONNECTOR) pDrv;
240	} Mouse;
241	} KBDState;
242
243	#ifndef VBOX_DEVICE_STRUCT_TESTCASE
244
245	/* update irq and KBD_STAT_[MOUSE_]OBF */
246	static void kbd_update_irq(KBDState *s)
247	{
248	MouseCmdQueue *mcq = &s->mouse_command_queue;
249	MouseEventQueue *meq = &s->mouse_event_queue;
250	int irq12_level, irq1_level;
251	uint8_t val;
252
253	irq1_level = 0;
254	irq12_level = 0;
255
256	/* Determine new OBF state, but only if OBF is clear. If OBF was already
257	* set, we cannot risk changing the event type after an ISR potentially
258	* started executing! Only kbd_read_data() clears the OBF bits.
259	*/
260	if (!(s->status & KBD_STAT_OBF)) {
261	s->status &= ~KBD_STAT_MOUSE_OBF;
262	/* Keyboard data has priority if both kbd and aux data is available. */
263	if (!(s->mode & KBD_MODE_DISABLE_KBD) && PS2KByteFromKbd(&s->Kbd, &val) == VINF_SUCCESS)
264	{
265	bool fHaveData = true;
266
267	/* If scancode translation is on (it usually is), there's more work to do. */
268	if (s->translate)
269	{
270	uint8_t xlated_val;
271
272	s->xlat_state = XlateAT2PC(s->xlat_state, val, &xlated_val);
273	val = xlated_val;
274
275	/* If the translation state is XS_BREAK, there's nothing to report
276	* and we keep going until the state changes or there's no more data.
277	*/
278	while (s->xlat_state == XS_BREAK && PS2KByteFromKbd(&s->Kbd, &val) == VINF_SUCCESS)
279	{
280	s->xlat_state = XlateAT2PC(s->xlat_state, val, &xlated_val);
281	val = xlated_val;
282	}
283	/* This can happen if the last byte in the queue is F0... */
284	if (s->xlat_state == XS_BREAK)
285	fHaveData = false;
286	}
287	if (fHaveData)
288	{
289	s->dbbout = val;
290	s->status \|= KBD_STAT_OBF;
291	}
292	}
293	else if ((mcq->count \|\| meq->count) && !(s->mode & KBD_MODE_DISABLE_MOUSE))
294	{
295	s->status \|= KBD_STAT_OBF \| KBD_STAT_MOUSE_OBF;
296	if (mcq->count)
297	{
298	s->dbbout = mcq->data[mcq->rptr];
299	if (++mcq->rptr == MOUSE_CMD_QUEUE_SIZE)
300	mcq->rptr = 0;
301	mcq->count--;
302	}
303	else
304	{
305	s->dbbout = meq->data[meq->rptr];
306	if (++meq->rptr == MOUSE_EVENT_QUEUE_SIZE)
307	meq->rptr = 0;
308	meq->count--;
309	}
310	}
311	}
312	/* Determine new IRQ state. */
313	if (s->status & KBD_STAT_OBF) {
314	if (s->status & KBD_STAT_MOUSE_OBF)
315	{
316	if (s->mode & KBD_MODE_MOUSE_INT)
317	irq12_level = 1;
318	}
319	else
320	{ /* KBD_STAT_OBF set but KBD_STAT_MOUSE_OBF isn't. */
321	if (s->mode & KBD_MODE_KBD_INT)
322	irq1_level = 1;
323	}
324	}
325	PDMDevHlpISASetIrq(s->CTX_SUFF(pDevIns), 1, irq1_level);
326	PDMDevHlpISASetIrq(s->CTX_SUFF(pDevIns), 12, irq12_level);
327	}
328
329	void KBCUpdateInterrupts(void *pKbc)
330	{
331	KBDState s = (KBDState )pKbc;
332	kbd_update_irq(s);
333	}
334
335	static void kbd_queue(KBDState *s, int b, int aux)
336	{
337	MouseCmdQueue *mcq = &s->mouse_command_queue;
338	MouseEventQueue *meq = &s->mouse_event_queue;
339
340	#if defined(DEBUG_MOUSE) \|\| defined(DEBUG_KBD)
341	if (aux == 1)
342	LogRel3(("%s: mouse command response: 0x%02x\n", __PRETTY_FUNCTION__, b));
343	else if (aux == 2)
344	LogRel3(("%s: mouse event data: 0x%02x\n", __PRETTY_FUNCTION__, b));
345	#ifdef DEBUG_KBD
346	else
347	LogRel3(("%s: kbd event: 0x%02x\n", __PRETTY_FUNCTION__, b));
348	#endif
349	#endif
350	switch (aux)
351	{
352	case 0: /* keyboard */
353	AssertMsgFailed(("kbd_queue() no longer supported for keyboard!\n"));
354	break;
355	case 1: /* mouse command response */
356	if (mcq->count >= MOUSE_CMD_QUEUE_SIZE)
357	return;
358	mcq->data[mcq->wptr] = b;
359	if (++mcq->wptr == MOUSE_CMD_QUEUE_SIZE)
360	mcq->wptr = 0;
361	mcq->count++;
362	break;
363	case 2: /* mouse event data */
364	if (meq->count >= MOUSE_EVENT_QUEUE_SIZE)
365	return;
366	meq->data[meq->wptr] = b;
367	if (++meq->wptr == MOUSE_EVENT_QUEUE_SIZE)
368	meq->wptr = 0;
369	meq->count++;
370	break;
371	default:
372	AssertMsgFailed(("aux=%d\n", aux));
373	}
374	kbd_update_irq(s);
375	}
376
377	static void kbc_dbb_out(void *opaque, uint8_t val)
378	{
379	KBDState s = (KBDState)opaque;
380
381	s->dbbout = val;
382	/* Set the OBF and raise IRQ. */
383	s->status \|= KBD_STAT_OBF;
384	if (s->mode & KBD_MODE_KBD_INT)
385	PDMDevHlpISASetIrq(s->CTX_SUFF(pDevIns), 1, 1);
386	}
387
388	static uint32_t kbd_read_status(void *opaque, uint32_t addr)
389	{
390	KBDState s = (KBDState)opaque;
391	int val = s->status;
392	NOREF(addr);
393
394	#if defined(DEBUG_KBD)
395	Log(("kbd: read status=0x%02x\n", val));
396	#endif
397	return val;
398	}
399
400	static int kbd_write_command(void *opaque, uint32_t addr, uint32_t val)
401	{
402	int rc = VINF_SUCCESS;
403	KBDState s = (KBDState)opaque;
404	NOREF(addr);
405
406	#ifdef DEBUG_KBD
407	Log(("kbd: write cmd=0x%02x\n", val));
408	#endif
409	switch(val) {
410	case KBD_CCMD_READ_MODE:
411	kbc_dbb_out(s, s->mode);
412	break;
413	case KBD_CCMD_WRITE_MODE:
414	case KBD_CCMD_WRITE_OBUF:
415	case KBD_CCMD_WRITE_AUX_OBUF:
416	case KBD_CCMD_WRITE_MOUSE:
417	case KBD_CCMD_WRITE_OUTPORT:
418	s->write_cmd = val;
419	break;
420	case KBD_CCMD_MOUSE_DISABLE:
421	s->mode \|= KBD_MODE_DISABLE_MOUSE;
422	break;
423	case KBD_CCMD_MOUSE_ENABLE:
424	s->mode &= ~KBD_MODE_DISABLE_MOUSE;
425	/* Check for queued input. */
426	kbd_update_irq(s);
427	break;
428	case KBD_CCMD_TEST_MOUSE:
429	kbc_dbb_out(s, 0x00);
430	break;
431	case KBD_CCMD_SELF_TEST:
432	/* Enable the A20 line - that is the power-on state(!). */
433	# ifndef IN_RING3
434	if (!PDMDevHlpA20IsEnabled(s->CTX_SUFF(pDevIns)))
435	{
436	rc = VINF_IOM_R3_IOPORT_WRITE;
437	break;
438	}
439	# else /* IN_RING3 */
440	PDMDevHlpA20Set(s->CTX_SUFF(pDevIns), true);
441	# endif /* IN_RING3 */
442	s->status \|= KBD_STAT_SELFTEST;
443	s->mode \|= KBD_MODE_DISABLE_KBD;
444	kbc_dbb_out(s, 0x55);
445	break;
446	case KBD_CCMD_KBD_TEST:
447	kbc_dbb_out(s, 0x00);
448	break;
449	case KBD_CCMD_KBD_DISABLE:
450	s->mode \|= KBD_MODE_DISABLE_KBD;
451	break;
452	case KBD_CCMD_KBD_ENABLE:
453	s->mode &= ~KBD_MODE_DISABLE_KBD;
454	/* Check for queued input. */
455	kbd_update_irq(s);
456	break;
457	case KBD_CCMD_READ_INPORT:
458	kbc_dbb_out(s, 0x00);
459	break;
460	case KBD_CCMD_READ_OUTPORT:
461	/* XXX: check that */
462	#ifdef TARGET_I386
463	val = 0x01 \| (PDMDevHlpA20IsEnabled(s->CTX_SUFF(pDevIns)) << 1);
464	#else
465	val = 0x01;
466	#endif
467	if (s->status & KBD_STAT_OBF)
468	val \|= 0x10;
469	if (s->status & KBD_STAT_MOUSE_OBF)
470	val \|= 0x20;
471	kbc_dbb_out(s, val);
472	break;
473	#ifdef TARGET_I386
474	case KBD_CCMD_ENABLE_A20:
475	# ifndef IN_RING3
476	if (!PDMDevHlpA20IsEnabled(s->CTX_SUFF(pDevIns)))
477	rc = VINF_IOM_R3_IOPORT_WRITE;
478	# else /* IN_RING3 */
479	PDMDevHlpA20Set(s->CTX_SUFF(pDevIns), true);
480	# endif /* IN_RING3 */
481	break;
482	case KBD_CCMD_DISABLE_A20:
483	# ifndef IN_RING3
484	if (PDMDevHlpA20IsEnabled(s->CTX_SUFF(pDevIns)))
485	rc = VINF_IOM_R3_IOPORT_WRITE;
486	# else /* IN_RING3 */
487	PDMDevHlpA20Set(s->CTX_SUFF(pDevIns), false);
488	# endif /* !IN_RING3 */
489	break;
490	#endif
491	case KBD_CCMD_READ_TSTINP:
492	/* Keyboard clock line is zero IFF keyboard is disabled */
493	val = (s->mode & KBD_MODE_DISABLE_KBD) ? 0 : 1;
494	kbc_dbb_out(s, val);
495	break;
496	case KBD_CCMD_RESET:
497	#ifndef IN_RING3
498	rc = VINF_IOM_R3_IOPORT_WRITE;
499	#else /* IN_RING3 */
500	LogRel(("Reset initiated by keyboard controller\n"));
501	rc = PDMDevHlpVMReset(s->CTX_SUFF(pDevIns));
502	#endif /* !IN_RING3 */
503	break;
504	case 0xff:
505	/* ignore that - I don't know what is its use */
506	break;
507	/* Make OS/2 happy. */
508	/* The 8042 RAM is readable using commands 0x20 thru 0x3f, and writable
509	by 0x60 thru 0x7f. Now days only the firs byte, the mode, is used.
510	We'll ignore the writes (0x61..7f) and return 0 for all the reads
511	just to make some OS/2 debug stuff a bit happier. */
512	case 0x21: case 0x22: case 0x23: case 0x24: case 0x25: case 0x26: case 0x27:
513	case 0x28: case 0x29: case 0x2a: case 0x2b: case 0x2c: case 0x2d: case 0x2e: case 0x2f:
514	case 0x30: case 0x31: case 0x32: case 0x33: case 0x34: case 0x35: case 0x36: case 0x37:
515	case 0x38: case 0x39: case 0x3a: case 0x3b: case 0x3c: case 0x3d: case 0x3e: case 0x3f:
516	kbc_dbb_out(s, 0);
517	Log(("kbd: reading non-standard RAM addr %#x\n", val & 0x1f));
518	break;
519	default:
520	Log(("kbd: unsupported keyboard cmd=0x%02x\n", val));
521	break;
522	}
523	return rc;
524	}
525
526	static uint32_t kbd_read_data(void *opaque, uint32_t addr)
527	{
528	KBDState s = (KBDState)opaque;
529	uint32_t val;
530	NOREF(addr);
531
532	/* Return the current DBB contents. */
533	val = s->dbbout;
534
535	/* Reading the DBB deasserts IRQs... */
536	if (s->status & KBD_STAT_MOUSE_OBF)
537	PDMDevHlpISASetIrq(s->CTX_SUFF(pDevIns), 12, 0);
538	else
539	PDMDevHlpISASetIrq(s->CTX_SUFF(pDevIns), 1, 0);
540	/* ...and clears the OBF bits. */
541	s->status &= ~(KBD_STAT_OBF \| KBD_STAT_MOUSE_OBF);
542
543	/* Check if more data is available. */
544	kbd_update_irq(s);
545	#ifdef DEBUG_KBD
546	Log(("kbd: read data=0x%02x\n", val));
547	#endif
548	return val;
549	}
550
551	PS2K *KBDGetPS2KFromDevIns(PPDMDEVINS pDevIns)
552	{
553	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
554	return &pThis->Kbd;
555	}
556
557	static void kbd_mouse_set_reported_buttons(KBDState *s, unsigned fButtons, unsigned fButtonMask)
558	{
559	s->mouse_buttons_reported \|= (fButtons & fButtonMask);
560	s->mouse_buttons_reported &= (fButtons \| ~fButtonMask);
561	}
562
563	/**
564	* Send a single relative packet in 3-byte PS/2 format to the PS/2 controller.
565	* @param s keyboard state object
566	* @param dx relative X value, must be between -256 and +255
567	* @param dy relative y value, must be between -256 and +255
568	* @param fButtonsLow the state of the two first mouse buttons
569	* @param fButtonsPacked the state of the upper three mouse buttons and
570	* scroll wheel movement, packed as per the
571	* MOUSE_EXT_* defines. For standard PS/2 packets
572	* only pass the value of button 3 here.
573	*/
574	static void kbd_mouse_send_rel3_packet(KBDState *s, bool fToCmdQueue)
575	{
576	int aux = fToCmdQueue ? 1 : 2;
577	int dx1 = s->mouse_dx < 0 ? RT_MAX(s->mouse_dx, -256)
578	: RT_MIN(s->mouse_dx, 255);
579	int dy1 = s->mouse_dy < 0 ? RT_MAX(s->mouse_dy, -256)
580	: RT_MIN(s->mouse_dy, 255);
581	unsigned int b;
582	unsigned fButtonsLow = s->mouse_buttons & 0x07;
583	s->mouse_dx -= dx1;
584	s->mouse_dy -= dy1;
585	kbd_mouse_set_reported_buttons(s, fButtonsLow, 0x07);
586	LogRel3(("%s: dx1=%d, dy1=%d, fButtonsLow=0x%x\n",
587	__PRETTY_FUNCTION__, dx1, dy1, fButtonsLow));
588	b = 0x08 \| ((dx1 < 0 ? 1 : 0) << 4) \| ((dy1 < 0 ? 1 : 0) << 5)
589	\| fButtonsLow;
590	kbd_queue(s, b, aux);
591	kbd_queue(s, dx1 & 0xff, aux);
592	kbd_queue(s, dy1 & 0xff, aux);
593	}
594
595	static void kbd_mouse_send_imps2_byte4(KBDState *s, bool fToCmdQueue)
596	{
597	int aux = fToCmdQueue ? 1 : 2;
598
599	int dz1 = s->mouse_dz < 0 ? RT_MAX(s->mouse_dz, -127)
600	: RT_MIN(s->mouse_dz, 127);
601	LogRel3(("%s: dz1=%d\n", __PRETTY_FUNCTION__, dz1));
602	s->mouse_dz -= dz1;
603	kbd_queue(s, dz1 & 0xff, aux);
604	}
605
606	static void kbd_mouse_send_imex_byte4(KBDState *s, bool fToCmdQueue)
607	{
608	int aux = fToCmdQueue ? 1 : 2;
609	int dz1 = 0, dw1 = 0;
610	unsigned fButtonsHigh = s->mouse_buttons & 0x18;
611
612	if (s->mouse_dw > 0)
613	dw1 = 1;
614	else if (s->mouse_dw < 0)
615	dw1 = -1;
616	else if (s->mouse_dz > 0)
617	dz1 = 1;
618	else if (s->mouse_dz < 0)
619	dz1 = -1;
620	if (s->mouse_dw && s->mouse_flags & MOUSE_REPORT_HORIZONTAL)
621	{
622	LogRel3(("%s: dw1=%d\n", __PRETTY_FUNCTION__, dw1));
623	kbd_queue(s, 0x40 \| (dw1 & 0x3f), aux);
624	}
625	else
626	{
627	LogRel3(("%s: dz1=%d, dw1=%d, fButtonsHigh=0x%x\n",
628	__PRETTY_FUNCTION__, dz1, dw1, fButtonsHigh));
629	unsigned u4Low = dw1 > 0 ? 9 /* -7 & 0xf */
630	: dw1 < 0 ? 7
631	: dz1 > 0 ? 1
632	: dz1 < 0 ? 0xf /* -1 & 0xf */
633	: 0;
634	kbd_mouse_set_reported_buttons(s, fButtonsHigh, 0x18);
635	kbd_queue(s, (fButtonsHigh << 1) \| u4Low, aux);
636	}
637	s->mouse_dz -= dz1;
638	s->mouse_dw -= dw1;
639	}
640
641	/**
642	* Send a single relative packet in (IM)PS/2 or IMEX format to the PS/2
643	* controller.
644	* @param s keyboard state object
645	* @param fToCmdQueue should this packet go to the command queue (or the
646	* event queue)?
647	*/
648	static void kbd_mouse_send_packet(KBDState *s, bool fToCmdQueue)
649	{
650	kbd_mouse_send_rel3_packet(s, fToCmdQueue);
651	if (s->mouse_type == MOUSE_PROT_IMPS2)
652	kbd_mouse_send_imps2_byte4(s, fToCmdQueue);
653	if (s->mouse_type == MOUSE_PROT_IMEX)
654	kbd_mouse_send_imex_byte4(s, fToCmdQueue);
655	}
656
657	#ifdef IN_RING3
658
659	static bool kbd_mouse_unreported(KBDState *s)
660	{
661	return s->mouse_dx
662	\|\| s->mouse_dy
663	\|\| s->mouse_dz
664	\|\| s->mouse_dw
665	\|\| s->mouse_buttons != s->mouse_buttons_reported;
666	}
667
668	static size_t kbd_mouse_event_queue_free(KBDState *s)
669	{
670	AssertReturn(s->mouse_event_queue.count <= MOUSE_EVENT_QUEUE_SIZE, 0);
671	return MOUSE_EVENT_QUEUE_SIZE - s->mouse_event_queue.count;
672	}
673
674	static void pc_kbd_mouse_event(void *opaque, int dx, int dy, int dz, int dw,
675	int buttons_state)
676	{
677	LogRel3(("%s: dx=%d, dy=%d, dz=%d, dw=%d, buttons_state=0x%x\n",
678	__PRETTY_FUNCTION__, dx, dy, dz, dw, buttons_state));
679	KBDState s = (KBDState)opaque;
680
681	/* check if deltas are recorded when disabled */
682	if (!(s->mouse_status & MOUSE_STATUS_ENABLED))
683	return;
684	AssertReturnVoid((buttons_state & ~0x1f) == 0);
685
686	s->mouse_dx += dx;
687	s->mouse_dy -= dy;
688	if ( (s->mouse_type == MOUSE_PROT_IMPS2)
689	\|\| (s->mouse_type == MOUSE_PROT_IMEX))
690	s->mouse_dz += dz;
691	if (s->mouse_type == MOUSE_PROT_IMEX)
692	s->mouse_dw += dw;
693	s->mouse_buttons = buttons_state;
694	if (!(s->mouse_status & MOUSE_STATUS_REMOTE))
695	/* if not remote, send event. Multiple events are sent if
696	too big deltas */
697	while ( kbd_mouse_unreported(s)
698	&& kbd_mouse_event_queue_free(s) > 4)
699	kbd_mouse_send_packet(s, false);
700	}
701
702	/* Report a change in status down the driver chain */
703	static void kbd_mouse_update_downstream_status(KBDState *pThis)
704	{
705	PPDMIMOUSECONNECTOR pDrv = pThis->Mouse.pDrv;
706	bool fEnabled = !!(pThis->mouse_status & MOUSE_STATUS_ENABLED);
707	pDrv->pfnReportModes(pDrv, fEnabled, false);
708	}
709
710	#endif /* IN_RING3 */
711
712	static int kbd_write_mouse(KBDState *s, int val)
713	{
714	#ifdef DEBUG_MOUSE
715	LogRelFlowFunc(("kbd: write mouse 0x%02x\n", val));
716	#endif
717	int rc = VINF_SUCCESS;
718	/* Flush the mouse command response queue. */
719	s->mouse_command_queue.count = 0;
720	s->mouse_command_queue.rptr = 0;
721	s->mouse_command_queue.wptr = 0;
722	switch(s->mouse_write_cmd) {
723	default:
724	case -1:
725	/* mouse command */
726	if (s->mouse_wrap) {
727	if (val == AUX_RESET_WRAP) {
728	s->mouse_wrap = 0;
729	kbd_queue(s, AUX_ACK, 1);
730	return VINF_SUCCESS;
731	} else if (val != AUX_RESET) {
732	kbd_queue(s, val, 1);
733	return VINF_SUCCESS;
734	}
735	}
736	switch(val) {
737	case AUX_SET_SCALE11:
738	s->mouse_status &= ~MOUSE_STATUS_SCALE21;
739	kbd_queue(s, AUX_ACK, 1);
740	break;
741	case AUX_SET_SCALE21:
742	s->mouse_status \|= MOUSE_STATUS_SCALE21;
743	kbd_queue(s, AUX_ACK, 1);
744	break;
745	case AUX_SET_STREAM:
746	s->mouse_status &= ~MOUSE_STATUS_REMOTE;
747	kbd_queue(s, AUX_ACK, 1);
748	break;
749	case AUX_SET_WRAP:
750	s->mouse_wrap = 1;
751	kbd_queue(s, AUX_ACK, 1);
752	break;
753	case AUX_SET_REMOTE:
754	s->mouse_status \|= MOUSE_STATUS_REMOTE;
755	kbd_queue(s, AUX_ACK, 1);
756	break;
757	case AUX_GET_TYPE:
758	kbd_queue(s, AUX_ACK, 1);
759	kbd_queue(s, s->mouse_type, 1);
760	break;
761	case AUX_SET_RES:
762	case AUX_SET_SAMPLE:
763	s->mouse_write_cmd = val;
764	kbd_queue(s, AUX_ACK, 1);
765	break;
766	case AUX_GET_SCALE:
767	kbd_queue(s, AUX_ACK, 1);
768	kbd_queue(s, s->mouse_status, 1);
769	kbd_queue(s, s->mouse_resolution, 1);
770	kbd_queue(s, s->mouse_sample_rate, 1);
771	break;
772	case AUX_POLL:
773	kbd_queue(s, AUX_ACK, 1);
774	kbd_mouse_send_packet(s, true);
775	break;
776	case AUX_ENABLE_DEV:
777	#ifdef IN_RING3
778	LogRelFlowFunc(("Enabling mouse device\n"));
779	s->mouse_status \|= MOUSE_STATUS_ENABLED;
780	kbd_queue(s, AUX_ACK, 1);
781	kbd_mouse_update_downstream_status(s);
782	#else
783	LogRelFlowFunc(("Enabling mouse device, R0 stub\n"));
784	rc = VINF_IOM_R3_IOPORT_WRITE;
785	#endif
786	break;
787	case AUX_DISABLE_DEV:
788	#ifdef IN_RING3
789	s->mouse_status &= ~MOUSE_STATUS_ENABLED;
790	kbd_queue(s, AUX_ACK, 1);
791	/* Flush the mouse events queue. */
792	s->mouse_event_queue.count = 0;
793	s->mouse_event_queue.rptr = 0;
794	s->mouse_event_queue.wptr = 0;
795	kbd_mouse_update_downstream_status(s);
796	#else
797	rc = VINF_IOM_R3_IOPORT_WRITE;
798	#endif
799	break;
800	case AUX_SET_DEFAULT:
801	#ifdef IN_RING3
802	s->mouse_sample_rate = 100;
803	s->mouse_resolution = 2;
804	s->mouse_status = 0;
805	kbd_queue(s, AUX_ACK, 1);
806	kbd_mouse_update_downstream_status(s);
807	#else
808	rc = VINF_IOM_R3_IOPORT_WRITE;
809	#endif
810	break;
811	case AUX_RESET:
812	#ifdef IN_RING3
813	s->mouse_sample_rate = 100;
814	s->mouse_resolution = 2;
815	s->mouse_status = 0;
816	s->mouse_type = MOUSE_PROT_PS2;
817	kbd_queue(s, AUX_ACK, 1);
818	kbd_queue(s, 0xaa, 1);
819	kbd_queue(s, s->mouse_type, 1);
820	/* Flush the mouse events queue. */
821	s->mouse_event_queue.count = 0;
822	s->mouse_event_queue.rptr = 0;
823	s->mouse_event_queue.wptr = 0;
824	kbd_mouse_update_downstream_status(s);
825	#else
826	rc = VINF_IOM_R3_IOPORT_WRITE;
827	#endif
828	break;
829	default:
830	/* NACK all commands we don't know.
831
832	The usecase for this is the OS/2 mouse driver which will try
833	read 0xE2 in order to figure out if it's a trackpoint device
834	or not. If it doesn't get a NACK (or ACK) on the command it'll
835	do several hundred thousand status reads before giving up. This
836	is slows down the OS/2 boot up considerably. (It also seems that
837	the code is somehow vulnerable while polling like this and that
838	mouse or keyboard input at this point might screw things up badly.)
839
840	From http://www.win.tue.nl/~aeb/linux/kbd/scancodes-13.html:
841
842	Every command or data byte sent to the mouse (except for the
843	resend command fe) is ACKed with fa. If the command or data
844	is invalid, it is NACKed with fe. If the next byte is again
845	invalid, the reply is ERROR: fc. */
846	/** @todo send error if we NACKed the previous command? */
847	kbd_queue(s, AUX_NACK, 1);
848	break;
849	}
850	break;
851	case AUX_SET_SAMPLE:
852	s->mouse_sample_rate = val;
853	/* detect IMPS/2 or IMEX */
854	/* And enable horizontal scrolling reporting when requested */
855	switch(s->mouse_detect_state) {
856	default:
857	case 0:
858	if (val == 200)
859	s->mouse_detect_state = 1;
860	break;
861	case 1:
862	if (val == 100)
863	s->mouse_detect_state = 2;
864	else if (val == 200)
865	s->mouse_detect_state = 3;
866	else if ((val == 80) && s->mouse_type == MOUSE_PROT_IMEX)
867	/* enable horizontal scrolling, byte two */
868	s->mouse_detect_state = 4;
869	else
870	s->mouse_detect_state = 0;
871	break;
872	case 2:
873	if (val == 80 && s->mouse_type < MOUSE_PROT_IMEX)
874	{
875	LogRelFlowFunc(("switching mouse device to IMPS/2 mode\n"));
876	s->mouse_type = MOUSE_PROT_IMPS2;
877	}
878	s->mouse_detect_state = 0;
879	break;
880	case 3:
881	if (val == 80)
882	{
883	LogRelFlowFunc(("switching mouse device to IMEX mode\n"));
884	s->mouse_type = MOUSE_PROT_IMEX;
885	}
886	s->mouse_detect_state = 0;
887	break;
888	case 4:
889	if (val == 40)
890	{
891	LogRelFlowFunc(("enabling IMEX horizontal scrolling reporting\n"));
892	s->mouse_flags \|= MOUSE_REPORT_HORIZONTAL;
893	}
894	s->mouse_detect_state = 0;
895	break;
896	}
897	kbd_queue(s, AUX_ACK, 1);
898	s->mouse_write_cmd = -1;
899	break;
900	case AUX_SET_RES:
901	if (0 <= val && val < 4)
902	{
903	s->mouse_resolution = val;
904	kbd_queue(s, AUX_ACK, 1);
905	}
906	else
907	kbd_queue(s, AUX_NACK, 1);
908	s->mouse_write_cmd = -1;
909	break;
910	}
911	return rc;
912	}
913
914	static int kbd_write_data(void *opaque, uint32_t addr, uint32_t val)
915	{
916	int rc = VINF_SUCCESS;
917	KBDState s = (KBDState)opaque;
918	NOREF(addr);
919
920	#ifdef DEBUG_KBD
921	Log(("kbd: write data=0x%02x\n", val));
922	#endif
923
924	switch(s->write_cmd) {
925	case 0:
926	/* Automatically enables keyboard interface. */
927	s->mode &= ~KBD_MODE_DISABLE_KBD;
928	rc = PS2KByteToKbd(&s->Kbd, val);
929	if (rc == VINF_SUCCESS)
930	kbd_update_irq(s);
931	break;
932	case KBD_CCMD_WRITE_MODE:
933	s->mode = val;
934	s->translate = (s->mode & KBD_MODE_KCC) == KBD_MODE_KCC;
935	kbd_update_irq(s);
936	break;
937	case KBD_CCMD_WRITE_OBUF:
938	kbc_dbb_out(s, val);
939	break;
940	case KBD_CCMD_WRITE_AUX_OBUF:
941	kbd_queue(s, val, 1);
942	break;
943	case KBD_CCMD_WRITE_OUTPORT:
944	#ifdef TARGET_I386
945	# ifndef IN_RING3
946	if (PDMDevHlpA20IsEnabled(s->CTX_SUFF(pDevIns)) != !!(val & 2))
947	rc = VINF_IOM_R3_IOPORT_WRITE;
948	# else /* IN_RING3 */
949	PDMDevHlpA20Set(s->CTX_SUFF(pDevIns), !!(val & 2));
950	# endif /* !IN_RING3 */
951	#endif
952	if (!(val & 1)) {
953	# ifndef IN_RING3
954	rc = VINF_IOM_R3_IOPORT_WRITE;
955	# else
956	rc = PDMDevHlpVMReset(s->CTX_SUFF(pDevIns));
957	# endif
958	}
959	break;
960	case KBD_CCMD_WRITE_MOUSE:
961	/* Automatically enables aux interface. */
962	s->mode &= ~KBD_MODE_DISABLE_MOUSE;
963	rc = kbd_write_mouse(s, val);
964	break;
965	default:
966	break;
967	}
968	if (rc != VINF_IOM_R3_IOPORT_WRITE)
969	s->write_cmd = 0;
970	return rc;
971	}
972
973	#ifdef IN_RING3
974
975	static void kbd_reset(void *opaque)
976	{
977	KBDState s = (KBDState)opaque;
978	MouseCmdQueue *mcq;
979	MouseEventQueue *meq;
980
981	s->mouse_write_cmd = -1;
982	s->mode = KBD_MODE_KBD_INT \| KBD_MODE_MOUSE_INT;
983	s->status = KBD_STAT_CMD \| KBD_STAT_UNLOCKED;
984	/* Resetting everything, keyword was not working right on NT4 reboot. */
985	s->write_cmd = 0;
986	s->translate = 0;
987	if (s->mouse_status)
988	{
989	s->mouse_status = 0;
990	kbd_mouse_update_downstream_status(s);
991	}
992	s->mouse_resolution = 0;
993	s->mouse_sample_rate = 0;
994	s->mouse_wrap = 0;
995	s->mouse_type = MOUSE_PROT_PS2;
996	s->mouse_detect_state = 0;
997	s->mouse_dx = 0;
998	s->mouse_dy = 0;
999	s->mouse_dz = 0;
1000	s->mouse_dw = 0;
1001	s->mouse_flags = 0;
1002	s->mouse_buttons = 0;
1003	s->mouse_buttons_reported = 0;
1004	mcq = &s->mouse_command_queue;
1005	mcq->rptr = 0;
1006	mcq->wptr = 0;
1007	mcq->count = 0;
1008	meq = &s->mouse_event_queue;
1009	meq->rptr = 0;
1010	meq->wptr = 0;
1011	meq->count = 0;
1012	}
1013
1014	static void kbd_save(QEMUFile* f, void* opaque)
1015	{
1016	uint32_t cItems;
1017	int i;
1018	KBDState s = (KBDState)opaque;
1019
1020	qemu_put_8s(f, &s->write_cmd);
1021	qemu_put_8s(f, &s->status);
1022	qemu_put_8s(f, &s->mode);
1023	qemu_put_8s(f, &s->dbbout);
1024	qemu_put_be32s(f, &s->mouse_write_cmd);
1025	qemu_put_8s(f, &s->mouse_status);
1026	qemu_put_8s(f, &s->mouse_resolution);
1027	qemu_put_8s(f, &s->mouse_sample_rate);
1028	qemu_put_8s(f, &s->mouse_wrap);
1029	qemu_put_8s(f, &s->mouse_type);
1030	qemu_put_8s(f, &s->mouse_detect_state);
1031	qemu_put_be32s(f, &s->mouse_dx);
1032	qemu_put_be32s(f, &s->mouse_dy);
1033	qemu_put_be32s(f, &s->mouse_dz);
1034	qemu_put_be32s(f, &s->mouse_dw);
1035	qemu_put_be32s(f, &s->mouse_flags);
1036	qemu_put_8s(f, &s->mouse_buttons);
1037	qemu_put_8s(f, &s->mouse_buttons_reported);
1038
1039	cItems = s->mouse_command_queue.count;
1040	SSMR3PutU32(f, cItems);
1041	for (i = s->mouse_command_queue.rptr; cItems-- > 0; i = (i + 1) % RT_ELEMENTS(s->mouse_command_queue.data))
1042	SSMR3PutU8(f, s->mouse_command_queue.data[i]);
1043	Log(("kbd_save: %d mouse command queue items stored\n", s->mouse_command_queue.count));
1044
1045	cItems = s->mouse_event_queue.count;
1046	SSMR3PutU32(f, cItems);
1047	for (i = s->mouse_event_queue.rptr; cItems-- > 0; i = (i + 1) % RT_ELEMENTS(s->mouse_event_queue.data))
1048	SSMR3PutU8(f, s->mouse_event_queue.data[i]);
1049	Log(("kbd_save: %d mouse event queue items stored\n", s->mouse_event_queue.count));
1050
1051	/* terminator */
1052	SSMR3PutU32(f, ~0);
1053	}
1054
1055	static int kbd_load(QEMUFile* f, void* opaque, int version_id)
1056	{
1057	uint32_t u32, i;
1058	uint8_t u8Dummy;
1059	uint32_t u32Dummy;
1060	int rc;
1061	KBDState s = (KBDState)opaque;
1062
1063	#if 0
1064	/** @todo enable this and remove the "if (version_id == 4)" code at some
1065	* later time */
1066	/* Version 4 was never created by any publicly released version of VBox */
1067	AssertReturn(version_id != 4, VERR_NOT_SUPPORTED);
1068	#endif
1069	if (version_id < 2 \|\| version_id > PCKBD_SAVED_STATE_VERSION)
1070	return VERR_SSM_UNSUPPORTED_DATA_UNIT_VERSION;
1071	qemu_get_8s(f, &s->write_cmd);
1072	qemu_get_8s(f, &s->status);
1073	qemu_get_8s(f, &s->mode);
1074	if (version_id <= 5)
1075	{
1076	qemu_get_be32s(f, (uint32_t *)&u32Dummy);
1077	qemu_get_be32s(f, (uint32_t *)&u32Dummy);
1078	}
1079	else
1080	{
1081	qemu_get_8s(f, &s->dbbout);
1082	}
1083	qemu_get_be32s(f, (uint32_t *)&s->mouse_write_cmd);
1084	qemu_get_8s(f, &s->mouse_status);
1085	qemu_get_8s(f, &s->mouse_resolution);
1086	qemu_get_8s(f, &s->mouse_sample_rate);
1087	qemu_get_8s(f, &s->mouse_wrap);
1088	qemu_get_8s(f, &s->mouse_type);
1089	qemu_get_8s(f, &s->mouse_detect_state);
1090	qemu_get_be32s(f, (uint32_t *)&s->mouse_dx);
1091	qemu_get_be32s(f, (uint32_t *)&s->mouse_dy);
1092	qemu_get_be32s(f, (uint32_t *)&s->mouse_dz);
1093	if (version_id > 2)
1094	{
1095	SSMR3GetS32(f, &s->mouse_dw);
1096	SSMR3GetS32(f, &s->mouse_flags);
1097	}
1098	qemu_get_8s(f, &s->mouse_buttons);
1099	if (version_id == 4)
1100	{
1101	SSMR3GetU32(f, &u32Dummy);
1102	SSMR3GetU32(f, &u32Dummy);
1103	}
1104	if (version_id > 3)
1105	SSMR3GetU8(f, &s->mouse_buttons_reported);
1106	if (version_id == 4)
1107	SSMR3GetU8(f, &u8Dummy);
1108	s->mouse_command_queue.count = 0;
1109	s->mouse_command_queue.rptr = 0;
1110	s->mouse_command_queue.wptr = 0;
1111	s->mouse_event_queue.count = 0;
1112	s->mouse_event_queue.rptr = 0;
1113	s->mouse_event_queue.wptr = 0;
1114
1115	/* Determine the translation state. */
1116	s->translate = (s->mode & KBD_MODE_KCC) == KBD_MODE_KCC;
1117
1118	/*
1119	* Load the queues
1120	*/
1121	if (version_id <= 5)
1122	{
1123	rc = SSMR3GetU32(f, &u32);
1124	if (RT_FAILURE(rc))
1125	return rc;
1126	for (i = 0; i < u32; i++)
1127	{
1128	rc = SSMR3GetU8(f, &u8Dummy);
1129	if (RT_FAILURE(rc))
1130	return rc;
1131	}
1132	Log(("kbd_load: %d keyboard queue items discarded from old saved state\n", u32));
1133	}
1134
1135	rc = SSMR3GetU32(f, &u32);
1136	if (RT_FAILURE(rc))
1137	return rc;
1138	if (u32 > RT_ELEMENTS(s->mouse_command_queue.data))
1139	{
1140	AssertMsgFailed(("u32=%#x\n", u32));
1141	return VERR_SSM_DATA_UNIT_FORMAT_CHANGED;
1142	}
1143	for (i = 0; i < u32; i++)
1144	{
1145	rc = SSMR3GetU8(f, &s->mouse_command_queue.data[i]);
1146	if (RT_FAILURE(rc))
1147	return rc;
1148	}
1149	s->mouse_command_queue.wptr = u32 % RT_ELEMENTS(s->mouse_command_queue.data);
1150	s->mouse_command_queue.count = u32;
1151	Log(("kbd_load: %d mouse command queue items loaded\n", u32));
1152
1153	rc = SSMR3GetU32(f, &u32);
1154	if (RT_FAILURE(rc))
1155	return rc;
1156	if (u32 > RT_ELEMENTS(s->mouse_event_queue.data))
1157	{
1158	AssertMsgFailed(("u32=%#x\n", u32));
1159	return VERR_SSM_DATA_UNIT_FORMAT_CHANGED;
1160	}
1161	for (i = 0; i < u32; i++)
1162	{
1163	rc = SSMR3GetU8(f, &s->mouse_event_queue.data[i]);
1164	if (RT_FAILURE(rc))
1165	return rc;
1166	}
1167	s->mouse_event_queue.wptr = u32 % RT_ELEMENTS(s->mouse_event_queue.data);
1168	s->mouse_event_queue.count = u32;
1169	Log(("kbd_load: %d mouse event queue items loaded\n", u32));
1170
1171	/* terminator */
1172	rc = SSMR3GetU32(f, &u32);
1173	if (RT_FAILURE(rc))
1174	return rc;
1175	if (u32 != ~0U)
1176	{
1177	AssertMsgFailed(("u32=%#x\n", u32));
1178	return VERR_SSM_DATA_UNIT_FORMAT_CHANGED;
1179	}
1180	/* Resend a notification to Main if the device is active */
1181	kbd_mouse_update_downstream_status(s);
1182	return 0;
1183	}
1184	#endif /* IN_RING3 */
1185
1186
1187	/* VirtualBox code start */
1188
1189	/* -=-=-=-=-=- wrappers -=-=-=-=-=- */
1190
1191	/**
1192	* Port I/O Handler for keyboard data IN operations.
1193	*
1194	* @returns VBox status code.
1195	*
1196	* @param pDevIns The device instance.
1197	* @param pvUser User argument - ignored.
1198	* @param Port Port number used for the IN operation.
1199	* @param pu32 Where to store the result.
1200	* @param cb Number of bytes read.
1201	*/
1202	PDMBOTHCBDECL(int) kbdIOPortDataRead(PPDMDEVINS pDevIns, void pvUser, RTIOPORT Port, uint32_t pu32, unsigned cb)
1203	{
1204	NOREF(pvUser);
1205	if (cb == 1)
1206	{
1207	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1208	*pu32 = kbd_read_data(pThis, Port);
1209	Log2(("kbdIOPortDataRead: Port=%#x cb=%d pu32=%#x\n", Port, cb, pu32));
1210	return VINF_SUCCESS;
1211	}
1212	AssertMsgFailed(("Port=%#x cb=%d\n", Port, cb));
1213	return VERR_IOM_IOPORT_UNUSED;
1214	}
1215
1216	/**
1217	* Port I/O Handler for keyboard data OUT operations.
1218	*
1219	* @returns VBox status code.
1220	*
1221	* @param pDevIns The device instance.
1222	* @param pvUser User argument - ignored.
1223	* @param Port Port number used for the IN operation.
1224	* @param u32 The value to output.
1225	* @param cb The value size in bytes.
1226	*/
1227	PDMBOTHCBDECL(int) kbdIOPortDataWrite(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t u32, unsigned cb)
1228	{
1229	int rc = VINF_SUCCESS;
1230	NOREF(pvUser);
1231	if (cb == 1)
1232	{
1233	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1234	rc = kbd_write_data(pThis, Port, u32);
1235	Log2(("kbdIOPortDataWrite: Port=%#x cb=%d u32=%#x\n", Port, cb, u32));
1236	}
1237	else
1238	AssertMsgFailed(("Port=%#x cb=%d\n", Port, cb));
1239	return rc;
1240	}
1241
1242	/**
1243	* Port I/O Handler for keyboard status IN operations.
1244	*
1245	* @returns VBox status code.
1246	*
1247	* @param pDevIns The device instance.
1248	* @param pvUser User argument - ignored.
1249	* @param Port Port number used for the IN operation.
1250	* @param pu32 Where to store the result.
1251	* @param cb Number of bytes read.
1252	*/
1253	PDMBOTHCBDECL(int) kbdIOPortStatusRead(PPDMDEVINS pDevIns, void pvUser, RTIOPORT Port, uint32_t pu32, unsigned cb)
1254	{
1255	NOREF(pvUser);
1256	if (cb == 1)
1257	{
1258	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1259	*pu32 = kbd_read_status(pThis, Port);
1260	Log2(("kbdIOPortStatusRead: Port=%#x cb=%d -> pu32=%#x\n", Port, cb, pu32));
1261	return VINF_SUCCESS;
1262	}
1263	AssertMsgFailed(("Port=%#x cb=%d\n", Port, cb));
1264	return VERR_IOM_IOPORT_UNUSED;
1265	}
1266
1267	/**
1268	* Port I/O Handler for keyboard command OUT operations.
1269	*
1270	* @returns VBox status code.
1271	*
1272	* @param pDevIns The device instance.
1273	* @param pvUser User argument - ignored.
1274	* @param Port Port number used for the IN operation.
1275	* @param u32 The value to output.
1276	* @param cb The value size in bytes.
1277	*/
1278	PDMBOTHCBDECL(int) kbdIOPortCommandWrite(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t u32, unsigned cb)
1279	{
1280	int rc = VINF_SUCCESS;
1281	NOREF(pvUser);
1282	if (cb == 1)
1283	{
1284	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1285	rc = kbd_write_command(pThis, Port, u32);
1286	Log2(("kbdIOPortCommandWrite: Port=%#x cb=%d u32=%#x rc=%Rrc\n", Port, cb, u32, rc));
1287	}
1288	else
1289	AssertMsgFailed(("Port=%#x cb=%d\n", Port, cb));
1290	return rc;
1291	}
1292
1293	#ifdef IN_RING3
1294
1295	/**
1296	* Saves a state of the keyboard device.
1297	*
1298	* @returns VBox status code.
1299	* @param pDevIns The device instance.
1300	* @param pSSM The handle to save the state to.
1301	*/
1302	static DECLCALLBACK(int) kbdSaveExec(PPDMDEVINS pDevIns, PSSMHANDLE pSSM)
1303	{
1304	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1305	kbd_save(pSSM, pThis);
1306	PS2KSaveState(&pThis->Kbd, pSSM);
1307	return VINF_SUCCESS;
1308	}
1309
1310
1311	/**
1312	* Loads a saved keyboard device state.
1313	*
1314	* @returns VBox status code.
1315	* @param pDevIns The device instance.
1316	* @param pSSM The handle to the saved state.
1317	* @param uVersion The data unit version number.
1318	* @param uPass The data pass.
1319	*/
1320	static DECLCALLBACK(int) kbdLoadExec(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass)
1321	{
1322	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1323	int rc;
1324
1325	Assert(uPass == SSM_PASS_FINAL); NOREF(uPass);
1326	rc = kbd_load(pSSM, pThis, uVersion);
1327	if (uVersion >= 6)
1328	rc = PS2KLoadState(&pThis->Kbd, pSSM, uVersion);
1329	return rc;
1330	}
1331
1332	/**
1333	* Reset notification.
1334	*
1335	* @returns VBox status.
1336	* @param pDevIns The device instance data.
1337	*/
1338	static DECLCALLBACK(void) kbdReset(PPDMDEVINS pDevIns)
1339	{
1340	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1341
1342	kbd_reset(pThis);
1343	PS2KReset(&pThis->Kbd);
1344	}
1345
1346
1347	/* -=-=-=-=-=- Mouse: IBase -=-=-=-=-=- */
1348
1349	/**
1350	* @interface_method_impl{PDMIBASE,pfnQueryInterface}
1351	*/
1352	static DECLCALLBACK(void ) kbdMouseQueryInterface(PPDMIBASE pInterface, const char pszIID)
1353	{
1354	KBDState *pThis = RT_FROM_MEMBER(pInterface, KBDState, Mouse.IBase);
1355	PDMIBASE_RETURN_INTERFACE(pszIID, PDMIBASE, &pThis->Mouse.IBase);
1356	PDMIBASE_RETURN_INTERFACE(pszIID, PDMIMOUSEPORT, &pThis->Mouse.IPort);
1357	return NULL;
1358	}
1359
1360
1361	/* -=-=-=-=-=- Mouse: IMousePort -=-=-=-=-=- */
1362
1363	/**
1364	* @interface_method_impl{PDMIMOUSEPORT, pfnPutEvent}
1365	*/
1366	static DECLCALLBACK(int) kbdMousePutEvent(PPDMIMOUSEPORT pInterface, int32_t iDeltaX, int32_t iDeltaY,
1367	int32_t iDeltaZ, int32_t iDeltaW, uint32_t fButtonStates)
1368	{
1369	KBDState *pThis = RT_FROM_MEMBER(pInterface, KBDState, Mouse.IPort);
1370	int rc = PDMCritSectEnter(pThis->pDevInsR3->pCritSectRoR3, VERR_SEM_BUSY);
1371	AssertReleaseRC(rc);
1372
1373	pc_kbd_mouse_event(pThis, iDeltaX, iDeltaY, iDeltaZ, iDeltaW, fButtonStates);
1374
1375	PDMCritSectLeave(pThis->pDevInsR3->pCritSectRoR3);
1376	return VINF_SUCCESS;
1377	}
1378
1379	/**
1380	* @interface_method_impl{PDMIMOUSEPORT, pfnPutEventAbs}
1381	*/
1382	static DECLCALLBACK(int) kbdMousePutEventAbs(PPDMIMOUSEPORT pInterface, uint32_t uX, uint32_t uY, int32_t iDeltaZ, int32_t iDeltaW, uint32_t fButtons)
1383	{
1384	AssertFailedReturn(VERR_NOT_SUPPORTED);
1385	NOREF(pInterface); NOREF(uX); NOREF(uY); NOREF(iDeltaZ); NOREF(iDeltaW); NOREF(fButtons);
1386	}
1387
1388
1389	/* -=-=-=-=-=- real code -=-=-=-=-=- */
1390
1391
1392	/**
1393	* Attach command.
1394	*
1395	* This is called to let the device attach to a driver for a specified LUN
1396	* during runtime. This is not called during VM construction, the device
1397	* constructor have to attach to all the available drivers.
1398	*
1399	* This is like plugging in the keyboard or mouse after turning on the PC.
1400	*
1401	* @returns VBox status code.
1402	* @param pDevIns The device instance.
1403	* @param iLUN The logical unit which is being detached.
1404	* @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
1405	* @remark The keyboard controller doesn't support this action, this is just
1406	* implemented to try out the driver<->device structure.
1407	*/
1408	static DECLCALLBACK(int) kbdAttach(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags)
1409	{
1410	int rc;
1411	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1412
1413	AssertMsgReturn(fFlags & PDM_TACH_FLAGS_NOT_HOT_PLUG,
1414	("PS/2 device does not support hotplugging\n"),
1415	VERR_INVALID_PARAMETER);
1416
1417	switch (iLUN)
1418	{
1419	/* LUN #0: keyboard */
1420	case 0:
1421	rc = PS2KAttach(&pThis->Kbd, pDevIns, iLUN, fFlags);
1422	if (RT_FAILURE(rc))
1423	return rc;
1424	break;
1425
1426	/* LUN #1: aux/mouse */
1427	case 1:
1428	rc = PDMDevHlpDriverAttach(pDevIns, iLUN, &pThis->Mouse.IBase, &pThis->Mouse.pDrvBase, "Aux (Mouse) Port");
1429	if (RT_SUCCESS(rc))
1430	{
1431	pThis->Mouse.pDrv = PDMIBASE_QUERY_INTERFACE(pThis->Mouse.pDrvBase, PDMIMOUSECONNECTOR);
1432	if (!pThis->Mouse.pDrv)
1433	{
1434	AssertLogRelMsgFailed(("LUN #1 doesn't have a mouse interface! rc=%Rrc\n", rc));
1435	rc = VERR_PDM_MISSING_INTERFACE;
1436	}
1437	}
1438	else if (rc == VERR_PDM_NO_ATTACHED_DRIVER)
1439	{
1440	Log(("%s/%d: warning: no driver attached to LUN #1!\n", pDevIns->pReg->szName, pDevIns->iInstance));
1441	rc = VINF_SUCCESS;
1442	}
1443	else
1444	AssertLogRelMsgFailed(("Failed to attach LUN #1! rc=%Rrc\n", rc));
1445	break;
1446
1447	default:
1448	AssertMsgFailed(("Invalid LUN #%d\n", iLUN));
1449	return VERR_PDM_NO_SUCH_LUN;
1450	}
1451
1452	return rc;
1453	}
1454
1455
1456	/**
1457	* Detach notification.
1458	*
1459	* This is called when a driver is detaching itself from a LUN of the device.
1460	* The device should adjust it's state to reflect this.
1461	*
1462	* This is like unplugging the network cable to use it for the laptop or
1463	* something while the PC is still running.
1464	*
1465	* @param pDevIns The device instance.
1466	* @param iLUN The logical unit which is being detached.
1467	* @param fFlags Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
1468	* @remark The keyboard controller doesn't support this action, this is just
1469	* implemented to try out the driver<->device structure.
1470	*/
1471	static DECLCALLBACK(void) kbdDetach(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags)
1472	{
1473	#if 0
1474	/*
1475	* Reset the interfaces and update the controller state.
1476	*/
1477	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1478	switch (iLUN)
1479	{
1480	/* LUN #0: keyboard */
1481	case 0:
1482	pThis->Keyboard.pDrv = NULL;
1483	pThis->Keyboard.pDrvBase = NULL;
1484	break;
1485
1486	/* LUN #1: aux/mouse */
1487	case 1:
1488	pThis->Mouse.pDrv = NULL;
1489	pThis->Mouse.pDrvBase = NULL;
1490	break;
1491
1492	default:
1493	AssertMsgFailed(("Invalid LUN #%d\n", iLUN));
1494	break;
1495	}
1496	#else
1497	NOREF(pDevIns); NOREF(iLUN); NOREF(fFlags);
1498	#endif
1499	}
1500
1501
1502	/**
1503	* @copydoc FNPDMDEVRELOCATE
1504	*/
1505	static DECLCALLBACK(void) kbdRelocate(PPDMDEVINS pDevIns, RTGCINTPTR offDelta)
1506	{
1507	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1508	pThis->pDevInsRC = PDMDEVINS_2_RCPTR(pDevIns);
1509	PS2KRelocate(&pThis->Kbd, offDelta, pDevIns);
1510	}
1511
1512
1513	/**
1514	* @interface_method_impl{PDMDEVREG,pfnConstruct}
1515	*/
1516	static DECLCALLBACK(int) kbdConstruct(PPDMDEVINS pDevIns, int iInstance, PCFGMNODE pCfg)
1517	{
1518	KBDState pThis = PDMINS_2_DATA(pDevIns, KBDState );
1519	int rc;
1520	bool fGCEnabled;
1521	bool fR0Enabled;
1522	Assert(iInstance == 0);
1523
1524	PDMDEV_CHECK_VERSIONS_RETURN(pDevIns);
1525
1526	/*
1527	* Validate and read the configuration.
1528	*/
1529	if (!CFGMR3AreValuesValid(pCfg, "GCEnabled\0R0Enabled\0"))
1530	return VERR_PDM_DEVINS_UNKNOWN_CFG_VALUES;
1531	rc = CFGMR3QueryBoolDef(pCfg, "GCEnabled", &fGCEnabled, true);
1532	if (RT_FAILURE(rc))
1533	return PDMDEV_SET_ERROR(pDevIns, rc, N_("Failed to query \"GCEnabled\" from the config"));
1534	rc = CFGMR3QueryBoolDef(pCfg, "R0Enabled", &fR0Enabled, true);
1535	if (RT_FAILURE(rc))
1536	return PDMDEV_SET_ERROR(pDevIns, rc, N_("Failed to query \"R0Enabled\" from the config"));
1537	Log(("pckbd: fGCEnabled=%RTbool fR0Enabled=%RTbool\n", fGCEnabled, fR0Enabled));
1538
1539
1540	/*
1541	* Initialize the interfaces.
1542	*/
1543	pThis->pDevInsR3 = pDevIns;
1544	pThis->pDevInsR0 = PDMDEVINS_2_R0PTR(pDevIns);
1545	pThis->pDevInsRC = PDMDEVINS_2_RCPTR(pDevIns);
1546
1547	rc = PS2KConstruct(&pThis->Kbd, pDevIns, pThis, iInstance);
1548	if (RT_FAILURE(rc))
1549	return rc;
1550
1551	pThis->Mouse.IBase.pfnQueryInterface = kbdMouseQueryInterface;
1552	pThis->Mouse.IPort.pfnPutEvent = kbdMousePutEvent;
1553	pThis->Mouse.IPort.pfnPutEventAbs = kbdMousePutEventAbs;
1554
1555	/*
1556	* Register I/O ports, save state, keyboard event handler and mouse event handlers.
1557	*/
1558	rc = PDMDevHlpIOPortRegister(pDevIns, 0x60, 1, NULL, kbdIOPortDataWrite, kbdIOPortDataRead, NULL, NULL, "PC Keyboard - Data");
1559	if (RT_FAILURE(rc))
1560	return rc;
1561	rc = PDMDevHlpIOPortRegister(pDevIns, 0x64, 1, NULL, kbdIOPortCommandWrite, kbdIOPortStatusRead, NULL, NULL, "PC Keyboard - Command / Status");
1562	if (RT_FAILURE(rc))
1563	return rc;
1564	if (fGCEnabled)
1565	{
1566	rc = PDMDevHlpIOPortRegisterRC(pDevIns, 0x60, 1, 0, "kbdIOPortDataWrite", "kbdIOPortDataRead", NULL, NULL, "PC Keyboard - Data");
1567	if (RT_FAILURE(rc))
1568	return rc;
1569	rc = PDMDevHlpIOPortRegisterRC(pDevIns, 0x64, 1, 0, "kbdIOPortCommandWrite", "kbdIOPortStatusRead", NULL, NULL, "PC Keyboard - Command / Status");
1570	if (RT_FAILURE(rc))
1571	return rc;
1572	}
1573	if (fR0Enabled)
1574	{
1575	rc = PDMDevHlpIOPortRegisterR0(pDevIns, 0x60, 1, 0, "kbdIOPortDataWrite", "kbdIOPortDataRead", NULL, NULL, "PC Keyboard - Data");
1576	if (RT_FAILURE(rc))
1577	return rc;
1578	rc = PDMDevHlpIOPortRegisterR0(pDevIns, 0x64, 1, 0, "kbdIOPortCommandWrite", "kbdIOPortStatusRead", NULL, NULL, "PC Keyboard - Command / Status");
1579	if (RT_FAILURE(rc))
1580	return rc;
1581	}
1582	rc = PDMDevHlpSSMRegister(pDevIns, PCKBD_SAVED_STATE_VERSION, sizeof(*pThis), kbdSaveExec, kbdLoadExec);
1583	if (RT_FAILURE(rc))
1584	return rc;
1585
1586	/*
1587	* Attach to the keyboard and mouse drivers.
1588	*/
1589	rc = kbdAttach(pDevIns, 0 /* keyboard LUN # */, PDM_TACH_FLAGS_NOT_HOT_PLUG);
1590	if (RT_FAILURE(rc))
1591	return rc;
1592	rc = kbdAttach(pDevIns, 1 /* aux/mouse LUN # */, PDM_TACH_FLAGS_NOT_HOT_PLUG);
1593	if (RT_FAILURE(rc))
1594	return rc;
1595
1596	/*
1597	* Initialize the device state.
1598	*/
1599	kbdReset(pDevIns);
1600
1601	return VINF_SUCCESS;
1602	}
1603
1604
1605	/**
1606	* The device registration structure.
1607	*/
1608	const PDMDEVREG g_DevicePS2KeyboardMouse =
1609	{
1610	/* u32Version */
1611	PDM_DEVREG_VERSION,
1612	/* szName */
1613	"pckbd",
1614	/* szRCMod */
1615	"VBoxDDGC.gc",
1616	/* szR0Mod */
1617	"VBoxDDR0.r0",
1618	/* pszDescription */
1619	"PS/2 Keyboard and Mouse device. Emulates both the keyboard, mouse and the keyboard controller. "
1620	"LUN #0 is the keyboard connector. "
1621	"LUN #1 is the aux/mouse connector.",
1622	/* fFlags */
1623	PDM_DEVREG_FLAGS_HOST_BITS_DEFAULT \| PDM_DEVREG_FLAGS_GUEST_BITS_32_64 \| PDM_DEVREG_FLAGS_PAE36 \| PDM_DEVREG_FLAGS_RC \| PDM_DEVREG_FLAGS_R0,
1624	/* fClass */
1625	PDM_DEVREG_CLASS_INPUT,
1626	/* cMaxInstances */
1627	1,
1628	/* cbInstance */
1629	sizeof(KBDState),
1630	/* pfnConstruct */
1631	kbdConstruct,
1632	/* pfnDestruct */
1633	NULL,
1634	/* pfnRelocate */
1635	kbdRelocate,
1636	/* pfnMemSetup */
1637	NULL,
1638	/* pfnPowerOn */
1639	NULL,
1640	/* pfnReset */
1641	kbdReset,
1642	/* pfnSuspend */
1643	NULL,
1644	/* pfnResume */
1645	NULL,
1646	/* pfnAttach */
1647	kbdAttach,
1648	/* pfnDetach */
1649	kbdDetach,
1650	/* pfnQueryInterface. */
1651	NULL,
1652	/* pfnInitComplete */
1653	NULL,
1654	/* pfnPowerOff */
1655	NULL,
1656	/* pfnSoftReset */
1657	NULL,
1658	/* u32VersionEnd */
1659	PDM_DEVREG_VERSION
1660	};
1661
1662	#endif /* IN_RING3 */
1663	#endif /* !VBOX_DEVICE_STRUCT_TESTCASE */
1664

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Devices/Input/DevPS2.cpp@ 45238

Download in other formats: