UsbKbd.cpp revision ce8831520e5af9622747a8b5f00213378e5e0442
/* $Id$ */
/** @file
* UsbKbd - USB Human Interface Device Emulation, Keyboard.
*/
/*
* Copyright (C) 2007-2012 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*/
/*******************************************************************************
* Header Files *
*******************************************************************************/
#define LOG_GROUP LOG_GROUP_USB_KBD
#include <iprt/critsect.h>
#include <iprt/semaphore.h>
#include "VBoxDD.h"
/*******************************************************************************
* Defined Constants And Macros *
*******************************************************************************/
/** @name USB HID string IDs
* @{ */
#define USBHID_STR_ID_MANUFACTURER 1
#define USBHID_STR_ID_PRODUCT 2
/** @} */
/** @name USB HID specific descriptor types
* @{ */
#define DT_IF_HID_DESCRIPTOR 0x21
#define DT_IF_HID_REPORT 0x22
/** @} */
/** @name USB HID vendor and product IDs
* @{ */
#define VBOX_USB_VENDOR 0x80EE
#define USBHID_PID_KEYBOARD 0x0010
/** @} */
/** @name USB HID class specific requests
* @{ */
#define HID_REQ_GET_REPORT 0x01
#define HID_REQ_GET_IDLE 0x02
#define HID_REQ_SET_REPORT 0x09
#define HID_REQ_SET_IDLE 0x0A
/** @} */
/** @name USB HID additional constants
* @{ */
/** The highest USB usage code reported by the VBox emulated keyboard */
#define VBOX_USB_MAX_USAGE_CODE 0xE7
/** The size of an array needed to store all USB usage codes */
#define USBHID_USAGE_ROLL_OVER 1
/** The usage code of the first modifier key. */
#define USBHID_MODIFIER_FIRST 0xE0
/** The usage code of the last modifier key. */
#define USBHID_MODIFIER_LAST 0xE7
/** @} */
/*******************************************************************************
* Structures and Typedefs *
*******************************************************************************/
/**
* The USB HID request state.
*/
typedef enum USBHIDREQSTATE
{
/** Invalid status. */
/** Ready to receive a new read request. */
/** Have (more) data for the host. */
/** Waiting to supply status information to the host. */
/** The end of the valid states. */
/**
* Endpoint status data.
*/
typedef struct USBHIDEP
{
bool fHalted;
} USBHIDEP;
/** Pointer to the endpoint status. */
/**
* A URB queue.
*/
typedef struct USBHIDURBQUEUE
{
/** The head pointer. */
/** Where to insert the next entry. */
/** Pointer to a URB queue. */
typedef USBHIDURBQUEUE *PUSBHIDURBQUEUE;
/** Pointer to a const URB queue. */
typedef USBHIDURBQUEUE const *PCUSBHIDURBQUEUE;
/**
* The USB HID report structure for regular keys.
*/
typedef struct USBHIDK_REPORT
{
/**
* The USB HID instance data.
*/
typedef struct USBHID
{
/** Pointer back to the PDM USB Device instance structure. */
/** Critical section protecting the device state. */
/** The current configuration.
* (0 - default, 1 - the one supported configuration, i.e configured.) */
/** USB HID Idle value..
* (0 - only report state change, !=0 - report in bIdle * 4ms intervals.) */
/** Endpoint 0 is the default control pipe, 1 is the dev->host interrupt one. */
/** The state of the HID (state machine).*/
/** Pending to-host queue.
* The URBs waiting here are waiting for data to become available.
*/
/** Done queue
* The URBs stashed here are waiting to be reaped. */
/** Signalled when adding an URB to the done queue and fHaveDoneQueueWaiter
* is set. */
/** Someone is waiting on the done queue. */
bool fHaveDoneQueueWaiter;
/** If device has pending changes. */
bool fHasPendingChanges;
/** Currently depressed keys */
/**
* Keyboard port - LUN#0.
*
* @implements PDMIBASE
* @implements PDMIKEYBOARDPORT
*/
struct
{
/** The base interface for the keyboard port. */
/** The keyboard port base interface. */
/** The base interface of the attached keyboard driver. */
/** The keyboard interface of the attached keyboard driver. */
} Lun0;
} USBHID;
/** Pointer to the USB HID instance data. */
/*******************************************************************************
* Global Variables *
*******************************************************************************/
static const PDMUSBDESCCACHESTRING g_aUsbHidStrings_en_US[] =
{
{ USBHID_STR_ID_MANUFACTURER, "VirtualBox" },
{ USBHID_STR_ID_PRODUCT, "USB Keyboard" },
};
static const PDMUSBDESCCACHELANG g_aUsbHidLanguages[] =
{
};
static const VUSBDESCENDPOINTEX g_aUsbHidEndpointDescs[] =
{
{
{
/* .bLength = */ sizeof(VUSBDESCENDPOINT),
/* .bDescriptorType = */ VUSB_DT_ENDPOINT,
/* .bEndpointAddress = */ 0x81 /* ep=1, in */,
/* .bmAttributes = */ 3 /* interrupt */,
/* .wMaxPacketSize = */ 8,
/* .bInterval = */ 10,
},
/* .pvMore = */ NULL,
/* .pvClass = */ NULL,
/* .cbClass = */ 0
},
};
/** HID report descriptor. */
static const uint8_t g_UsbHidReportDesc[] =
{
/* Usage Page */ 0x05, 0x01, /* Generic Desktop */
/* Usage */ 0x09, 0x06, /* Keyboard */
/* Collection */ 0xA1, 0x01, /* Application */
/* Usage Page */ 0x05, 0x07, /* Keyboard */
/* Usage Minimum */ 0x19, 0xE0, /* Left Ctrl Key */
/* Usage Maximum */ 0x29, 0xE7, /* Right GUI Key */
/* Logical Minimum */ 0x15, 0x00, /* 0 */
/* Logical Maximum */ 0x25, 0x01, /* 1 */
/* Report Count */ 0x95, 0x08, /* 8 */
/* Report Size */ 0x75, 0x01, /* 1 */
/* Input */ 0x81, 0x02, /* Data, Value, Absolute, Bit field */
/* Report Count */ 0x95, 0x01, /* 1 */
/* Report Size */ 0x75, 0x08, /* 8 (padding bits) */
/* Input */ 0x81, 0x01, /* Constant, Array, Absolute, Bit field */
/* Report Count */ 0x95, 0x05, /* 5 */
/* Report Size */ 0x75, 0x01, /* 1 */
/* Usage Page */ 0x05, 0x08, /* LEDs */
/* Usage Minimum */ 0x19, 0x01, /* Num Lock */
/* Usage Maximum */ 0x29, 0x05, /* Kana */
/* Output */ 0x91, 0x02, /* Data, Value, Absolute, Non-volatile,Bit field */
/* Report Count */ 0x95, 0x01, /* 1 */
/* Report Size */ 0x75, 0x03, /* 3 */
/* Output */ 0x91, 0x01, /* Constant, Value, Absolute, Non-volatile, Bit field */
/* Report Count */ 0x95, 0x06, /* 6 */
/* Report Size */ 0x75, 0x08, /* 8 */
/* Logical Minimum */ 0x15, 0x00, /* 0 */
/* Logical Maximum */ 0x26, 0xFF,0x00,/* 255 */
/* Usage Page */ 0x05, 0x07, /* Keyboard */
/* Usage Minimum */ 0x19, 0x00, /* 0 */
/* Usage Maximum */ 0x29, 0xFF, /* 255 */
/* Input */ 0x81, 0x00, /* Data, Array, Absolute, Bit field */
/* End Collection */ 0xC0,
};
/** Additional HID class interface descriptor. */
static const uint8_t g_UsbHidIfHidDesc[] =
{
/* .bLength = */ 0x09,
/* .bDescriptorType = */ 0x21, /* HID */
/* .bcdHID = */ 0x10, 0x01, /* 1.1 */
/* .bCountryCode = */ 0x0D, /* International (ISO) */
/* .bNumDescriptors = */ 1,
/* .bDescriptorType = */ 0x22, /* Report */
};
static const VUSBDESCINTERFACEEX g_UsbHidInterfaceDesc =
{
{
/* .bLength = */ sizeof(VUSBDESCINTERFACE),
/* .bDescriptorType = */ VUSB_DT_INTERFACE,
/* .bInterfaceNumber = */ 0,
/* .bAlternateSetting = */ 0,
/* .bNumEndpoints = */ 1,
/* .bInterfaceClass = */ 3 /* HID */,
/* .bInterfaceSubClass = */ 1 /* Boot Interface */,
/* .bInterfaceProtocol = */ 1 /* Keyboard */,
/* .iInterface = */ 0
},
/* .pvMore = */ NULL,
/* .pvClass = */ &g_UsbHidIfHidDesc,
/* .cbClass = */ sizeof(g_UsbHidIfHidDesc),
/* .pIAD = */ NULL,
/* .cbIAD = */ 0
};
static const VUSBINTERFACE g_aUsbHidInterfaces[] =
{
};
static const VUSBDESCCONFIGEX g_UsbHidConfigDesc =
{
{
/* .bLength = */ sizeof(VUSBDESCCONFIG),
/* .bDescriptorType = */ VUSB_DT_CONFIG,
/* .wTotalLength = */ 0 /* recalculated on read */,
/* .bConfigurationValue =*/ 1,
/* .iConfiguration = */ 0,
/* .MaxPower = */ 50 /* 100mA */
},
NULL, /* pvMore */
&g_aUsbHidInterfaces[0],
NULL /* pvOriginal */
};
static const VUSBDESCDEVICE g_UsbHidDeviceDesc =
{
/* .bLength = */ sizeof(g_UsbHidDeviceDesc),
/* .bDescriptorType = */ VUSB_DT_DEVICE,
/* .bcdUsb = */ 0x110, /* 1.1 */
/* .bDeviceClass = */ 0 /* Class specified in the interface desc. */,
/* .bDeviceSubClass = */ 0 /* Subclass specified in the interface desc. */,
/* .bDeviceProtocol = */ 0 /* Protocol specified in the interface desc. */,
/* .bMaxPacketSize0 = */ 8,
/* .idVendor = */ VBOX_USB_VENDOR,
/* .idProduct = */ USBHID_PID_KEYBOARD,
/* .bcdDevice = */ 0x0100, /* 1.0 */
/* .iManufacturer = */ USBHID_STR_ID_MANUFACTURER,
/* .iProduct = */ USBHID_STR_ID_PRODUCT,
/* .iSerialNumber = */ 0,
/* .bNumConfigurations = */ 1
};
static const PDMUSBDESCCACHE g_UsbHidDescCache =
{
/* .pDevice = */ &g_UsbHidDeviceDesc,
/* .paConfigs = */ &g_UsbHidConfigDesc,
/* .paLanguages = */ g_aUsbHidLanguages,
/* .fUseCachedDescriptors = */ true,
/* .fUseCachedStringsDescriptors = */ true
};
/*******************************************************************************
* Internal Functions *
*******************************************************************************/
/**
* Initializes an URB queue.
*
* @param pQueue The URB queue.
*/
{
}
/**
* Inserts an URB at the end of the queue.
*
* @param pQueue The URB queue.
* @param pUrb The URB to insert.
*/
{
}
/**
* Unlinks the head of the queue and returns it.
*
* @returns The head entry.
* @param pQueue The URB queue.
*/
{
if (pUrb)
{
if (!pNext)
else
}
return pUrb;
}
/**
* Removes an URB from anywhere in the queue.
*
* @returns true if found, false if not.
* @param pQueue The URB queue.
* @param pUrb The URB to remove.
*/
{
else
{
while (pCur)
{
{
break;
}
}
if (!pCur)
return false;
}
return true;
}
/**
* Checks if the queue is empty or not.
*
* @returns true if it is, false if it isn't.
* @param pQueue The URB queue.
*/
{
}
/**
* Links an URB into the done queue.
*
* @param pThis The HID instance.
* @param pUrb The URB.
*/
{
if (pThis->fHaveDoneQueueWaiter)
{
}
}
/**
* Completes the URB with a stalled state, halting the pipe.
*/
{
Log(("usbHidCompleteStall/#%u: pUrb=%p:%s: %s\n", pThis->pUsbIns->iInstance, pUrb, pUrb->pszDesc, pszWhy));
/** @todo figure out if the stall is global or pipe-specific or both. */
if (pEp)
else
{
}
return VINF_SUCCESS;
}
/**
* Completes the URB with a OK state.
*/
{
Log(("usbHidCompleteOk/#%u: pUrb=%p:%s cbData=%#zx\n", pThis->pUsbIns->iInstance, pUrb, pUrb->pszDesc, cbData));
return VINF_SUCCESS;
}
/**
* Reset worker for usbHidUsbReset, usbHidUsbSetConfiguration and
* usbHidHandleDefaultPipe.
*
* @returns VBox status code.
* @param pThis The HID instance.
* @param pUrb Set when usbHidHandleDefaultPipe is the
* caller.
* @param fSetConfig Set when usbHidUsbSetConfiguration is the
* caller.
*/
{
/*
* Deactivate the keyboard.
*/
/*
* Reset the device state.
*/
pThis->fHasPendingChanges = false;
/*
* Ditch all pending URBs.
*/
{
}
if (pUrb)
return VINF_SUCCESS;
}
/**
* Returns true if the usage code corresponds to a keyboard modifier key
* (left or right ctrl, shift, alt or GUI). The usage codes for these keys
* are the range 0xe0 to 0xe7.
*/
{
}
/**
* Convert a USB HID usage code to a keyboard modifier flag. The arithmetic
* is simple: the modifier keys have usage codes from 0xe0 to 0xe7, and the
* lower nibble is the bit number of the flag.
*/
{
}
/**
* Create a USB HID keyboard report reflecting the current state of the
*/
{
unsigned iBuf = 0;
{
if (pabDepressedKeys[iKey])
{
{
/* The USB HID spec says that the entire vector should be
* set to ErrorRollOver on overflow. We don't mind if this
* path is taken several times for one report. */
for (unsigned iBuf2 = 0;
}
else
{
++iBuf;
}
}
}
}
/**
* Handles a SET_REPORT request sent to the default control pipe. Note
* that unrecognized requests are ignored without reporting an error.
*/
{
/* The LED report is the 3rd report, ID 0 (-> wValue 0x200). */
{
/* Translate LED state to PDM format and send upstream. */
if (u8LEDs & 0x01)
if (u8LEDs & 0x02)
if (u8LEDs & 0x04)
}
}
/**
* Sends a state report to the guest if there is a URB available.
*/
{
if (pUrb)
{
pThis->fHasPendingChanges = false;
}
else
{
Log2(("No available URB for USB kbd\n"));
pThis->fHasPendingChanges = true;
}
}
/**
* @interface_method_impl{PDMIBASE,pfnQueryInterface}
*/
{
return NULL;
}
/* See the PS2K device. */
/**
* Keyboard event handler.
*
* @returns VBox status code.
* @param pInterface Pointer to the keyboard port interface (KBDState::Keyboard.IPort).
* @param u32UsageCode The key usage ID.
*/
static DECLCALLBACK(int) usbHidKeyboardPutEvent(PPDMIKEYBOARDPORT pInterface, uint32_t u32UsageCode)
{
bool fKeyDown;
bool fHaveEvent = true;
int rc = VINF_SUCCESS;
/* Let's see what we got... */
/*
* Due to host key repeat, we can get key events for keys which are
* already depressed. Drop those right here.
*/
fHaveEvent = false;
/* If there is already a pending event, we won't accept a new one yet. */
{
pThis->fHasPendingChanges = true;
rc = VERR_TRY_AGAIN;
}
else if (fHaveEvent)
{
{
/* Clear all currently depressed and unreported keys. */
}
else
{
/* Regular key event - update keyboard state. */
if (fKeyDown)
else
}
/*
* Try sending a report. Note that we already decided to consume the
* event regardless of whether a URB is available or not. If it's not,
* we will simply not accept any further events.
*/
}
return rc;
}
/**
* @copydoc PDMUSBREG::pfnUrbReap
*/
{
//LogFlow(("usbHidUrbReap/#%u: cMillies=%u\n", pUsbIns->iInstance, cMillies));
{
/* Wait */
pThis->fHaveDoneQueueWaiter = true;
pThis->fHaveDoneQueueWaiter = false;
}
if (pUrb)
return pUrb;
}
/**
* @copydoc PDMUSBREG::pfnWakeup
*/
{
}
/**
* @copydoc PDMUSBREG::pfnUrbCancel
*/
{
/*
* Remove the URB from the to-host queue and move it onto the done queue.
*/
return VINF_SUCCESS;
}
/**
* Handles request sent to the inbound (device to host) interrupt pipe. This is
* rather different from bulk requests because an interrupt read URB may complete
* after arbitrarily long time.
*/
{
/*
* Stall the request if the pipe is halted.
*/
/*
* Deal with the URB according to the state.
*/
{
/*
* We've data left to transfer to the host.
*/
{
AssertFailed();
Log(("usbHidHandleIntrDevToHost: Entering STATUS\n"));
}
/*
* Status transfer.
*/
case USBHIDREQSTATE_STATUS:
{
AssertFailed();
Log(("usbHidHandleIntrDevToHost: Entering READY\n"));
}
case USBHIDREQSTATE_READY:
/* If device was not set idle, send the current report right away. */
{
/* There may be more input queued up. Ask for it now. */
}
return VINF_SUCCESS;
/*
* Bad states, stall.
*/
default:
}
}
/**
* Handles request sent to the default control pipe.
*/
{
{
{
case VUSB_REQ_GET_DESCRIPTOR:
{
switch (pSetup->bmRequestType)
{
{
{
case VUSB_DT_STRING:
break;
default:
break;
}
break;
}
{
{
case DT_IF_HID_DESCRIPTOR:
{
/* Returned data is written after the setup message. */
Log(("usbHidKbd: GET_DESCRIPTOR DT_IF_HID_DESCRIPTOR wValue=%#x wIndex=%#x cbCopy=%#x\n", pSetup->wValue, pSetup->wIndex, cbCopy));
}
case DT_IF_HID_REPORT:
{
/* Returned data is written after the setup message. */
Log(("usbHid: GET_DESCRIPTOR DT_IF_HID_REPORT wValue=%#x wIndex=%#x cbCopy=%#x\n", pSetup->wValue, pSetup->wIndex, cbCopy));
}
default:
break;
}
break;
}
default:
}
break;
}
case VUSB_REQ_GET_STATUS:
{
{
break;
}
switch (pSetup->bmRequestType)
{
{
Log(("usbHid: GET_STATUS (device)\n"));
wRet = 0; /* Not self-powered, no remote wakeup. */
}
{
{
}
else
{
}
break;
}
{
{
}
else
{
}
break;
}
default:
}
break;
}
case VUSB_REQ_CLEAR_FEATURE:
break;
}
/** @todo implement this. */
Log(("usbHid: Implement standard request: bmRequestType=%#x bRequest=%#x wValue=%#x wIndex=%#x wLength=%#x\n",
}
{
{
case HID_REQ_SET_IDLE:
{
switch (pSetup->bmRequestType)
{
{
/* Consider 24ms to mean zero for keyboards (see IOUSBHIDDriver) */
}
break;
}
break;
}
case HID_REQ_GET_IDLE:
{
switch (pSetup->bmRequestType)
{
{
Log(("usbHid: GET_IDLE wValue=%#x wIndex=%#x, returning %#x\n", pSetup->wValue, pSetup->wIndex, pThis->bIdle));
}
break;
}
break;
}
case HID_REQ_SET_REPORT:
{
switch (pSetup->bmRequestType)
{
{
Log(("usbHid: SET_REPORT wValue=%#x wIndex=%#x wLength=%#x\n", pSetup->wValue, pSetup->wIndex, pSetup->wLength));
}
break;
}
break;
}
}
Log(("usbHid: Unimplemented class request: bmRequestType=%#x bRequest=%#x wValue=%#x wIndex=%#x wLength=%#x\n",
}
else
{
Log(("usbHid: Unknown control msg: bmRequestType=%#x bRequest=%#x wValue=%#x wIndex=%#x wLength=%#x\n",
}
return VINF_SUCCESS;
}
/**
* @copydoc PDMUSBREG::pfnUrbQueue
*/
{
LogFlow(("usbHidQueue/#%u: pUrb=%p:%s EndPt=%#x\n", pUsbIns->iInstance, pUrb, pUrb->pszDesc, pUrb->EndPt));
/*
* Parse on a per end-point basis.
*/
int rc;
{
case 0:
break;
case 0x81:
AssertFailed();
case 0x01:
break;
default:
break;
}
return rc;
}
/**
* @copydoc PDMUSBREG::pfnUsbClearHaltedEndpoint
*/
{
{
}
return VINF_SUCCESS;
}
/**
* @copydoc PDMUSBREG::pfnUsbSetInterface
*/
static DECLCALLBACK(int) usbHidUsbSetInterface(PPDMUSBINS pUsbIns, uint8_t bInterfaceNumber, uint8_t bAlternateSetting)
{
LogFlow(("usbHidUsbSetInterface/#%u: bInterfaceNumber=%u bAlternateSetting=%u\n", pUsbIns->iInstance, bInterfaceNumber, bAlternateSetting));
Assert(bAlternateSetting == 0);
return VINF_SUCCESS;
}
/**
* @copydoc PDMUSBREG::pfnUsbSetConfiguration
*/
{
LogFlow(("usbHidUsbSetConfiguration/#%u: bConfigurationValue=%u\n", pUsbIns->iInstance, bConfigurationValue));
/*
* If the same config is applied more than once, it's a kind of reset.
*/
/*
* Tell the other end that the keyboard is now enabled and wants
* to receive keystrokes.
*/
return VINF_SUCCESS;
}
/**
* @copydoc PDMUSBREG::pfnUsbGetDescriptorCache
*/
{
return &g_UsbHidDescCache;
}
/**
* @copydoc PDMUSBREG::pfnUsbReset
*/
{
return rc;
}
/**
* @copydoc PDMUSBREG::pfnDestruct
*/
{
{
/* Let whoever runs in this critical section complete. */
}
{
}
}
/**
* @copydoc PDMUSBREG::pfnConstruct
*/
static DECLCALLBACK(int) usbHidConstruct(PPDMUSBINS pUsbIns, int iInstance, PCFGMNODE pCfg, PCFGMNODE pCfgGlobal)
{
/*
* Perform the basic structure initialization first so the destructor
* will not misbehave.
*/
/*
* Validate and read the configuration.
*/
if (RT_FAILURE(rc))
return rc;
/*
* Attach the keyboard driver.
*/
rc = PDMUsbHlpDriverAttach(pUsbIns, 0 /*iLun*/, &pThis->Lun0.IBase, &pThis->Lun0.pDrvBase, "Keyboard Port");
if (RT_FAILURE(rc))
return PDMUsbHlpVMSetError(pUsbIns, VERR_PDM_MISSING_INTERFACE, RT_SRC_POS, N_("HID failed to query keyboard interface"));
return VINF_SUCCESS;
}
/**
* The USB Human Interface Device (HID) Keyboard registration record.
*/
const PDMUSBREG g_UsbHidKbd =
{
/* u32Version */
/* szName */
"HidKeyboard",
/* pszDescription */
"USB HID Keyboard.",
/* fFlags */
0,
/* cMaxInstances */
~0U,
/* cbInstance */
sizeof(USBHID),
/* pfnConstruct */
/* pfnDestruct */
/* pfnVMInitComplete */
NULL,
/* pfnVMPowerOn */
NULL,
/* pfnVMReset */
NULL,
/* pfnVMSuspend */
NULL,
/* pfnVMResume */
NULL,
/* pfnVMPowerOff */
NULL,
/* pfnHotPlugged */
NULL,
/* pfnHotUnplugged */
NULL,
/* pfnDriverAttach */
NULL,
/* pfnDriverDetach */
NULL,
/* pfnQueryInterface */
NULL,
/* pfnUsbReset */
/* pfnUsbGetDescriptorCache */
/* pfnUsbSetConfiguration */
/* pfnUsbSetInterface */
/* pfnUsbClearHaltedEndpoint */
/* pfnUrbNew */
NULL/*usbHidUrbNew*/,
/* pfnUrbQueue */
/* pfnUrbCancel */
/* pfnUrbReap */
/* pfnWakeup */
/* u32TheEnd */
};