pdmusb.h revision 416ec3261fd37fdcbbc161c903c4bb11c95e1ae7
* This structure is owned by the USB device but provided to the PDM/VUSB layer * thru the PDMUSBREG::pfnGetDescriptorCache method. PDM/VUSB will use the * information here to map addresses to endpoints, perform SET_CONFIGURATION * requests, and optionally perform GET_DESCRIPTOR requests (see flag). * Currently, only device and configuration descriptors are cached. /** USB device descriptor */ /** USB Descriptor arrays (pDev->bNumConfigurations) */ /** Language IDs and their associated strings. * This must be sorted in ascending order by language ID as a binary lookup /** The number of entries in the array pointed to by paLanguages. */ /** Use the cached descriptors for GET_DESCRIPTOR requests. */ /** Use the cached string descriptors. */ /** Pointer to an USB descriptor cache. */ /** Pointer to a const USB descriptor cache. */ /** PDM USB Device Registration Structure, * This structure is used when registering a device from VBoxUsbRegister() in HC Ring-3. * The PDM will make use of this structure until the VM is destroyed. /** Structure version. PDM_DEVREG_VERSION defines the current version. */ /** The description of the device. The UTF-8 string pointed to shall, like this structure, * remain unchanged from registration till VM destruction. */ /** Flags, combination of the PDM_USBREG_FLAGS_* \#defines. */ /** Maximum number of instances (per VM). */ /** Size of the instance data. */ * Construct an USB device instance for a VM. * @param pUsbIns The USB device instance data. * If the registration structure is needed, it will be * accessible thru pUsbDev->pReg. * @param iInstance Instance number. Use this to figure out which registers * and such to use. The instance number is also found in * pUsbDev->iInstance, but since it's likely to be * frequently used PDM passes it as parameter. * @param pCfg Configuration node handle for the device. Use this to * obtain the configuration of the device instance. It is * also found in pUsbDev->pCfg, but since it is primary * usage will in this function it is passed as a parameter. * @param pCfgGlobal Handle to the global device configuration. Also found * in pUsbDev->pCfgGlobal. * @remarks This callback is required. * Destruct an USB device instance. * Most VM resources are freed by the VM. This callback is provided so that any non-VM * resources can be freed correctly. * This method will be called regardless of the pfnConstruc result to avoid * complicated failure paths. * @param pUsbIns The USB device instance data. * Init complete notification. * This can be done to do communication with other devices and other * initialization which requires everything to be in place. * @returns VBOX status code. * @param pUsbIns The USB device instance data. * @remarks Not called when hotplugged. * VM Power On notification. * @param pUsbIns The USB device instance data. * @param pUsbIns The USB device instance data. * VM Suspend notification. * @param pUsbIns The USB device instance data. * VM Resume notification. * @param pUsbIns The USB device instance data. * VM Power Off notification. * This is only called when the VMR3PowerOff call is made on a running VM. This * means that there is no notification if the VM was suspended before being * powered of. There will also be no callback when hot plugging devices. * @param pUsbIns The USB device instance data. * Called after the constructor when attaching a device at run time. * This can be used to do tasks normally assigned to pfnInitComplete and/or pfnVMPowerOn. * @param pUsbIns The USB device instance data. * Called before the destructor when a device is unplugged at run time. * This can be used to do tasks normally assigned to pfnVMSuspend and/or pfnVMPowerOff. * @param pUsbIns The USB device instance data. * This is called to let the USB device attach to a driver for a specified LUN * at runtime. This is not called during VM construction, the device constructor * have to attach to all the available drivers. * @returns VBox status code. * @param pUsbIns The USB device instance data. * @param iLUN The logical unit which is being detached. * Driver Detach notification. * This is called when a driver is detaching itself from a LUN of the device. * The device should adjust it's state to reflect this. * @param pUsbIns The USB device instance data. * @param iLUN The logical unit which is being detached. * Query the base interface of a logical unit. * @returns VBOX status code. * @param pUsbIns The USB device instance data. * @param iLUN The logicial unit to query. * @param ppBase Where to store the pointer to the base interface of the LUN. * Requests the USB device to reset. * @returns VBox status code. * @param pUsbIns The USB device instance. * @param fResetOnLinux A hint to the usb proxy. * Don't use this unless you're the linux proxy device. * Query device and configuration descriptors for the caching and servicing * relevant GET_DESCRIPTOR requests. * @returns Pointer to the descriptor cache (read-only). * @param pUsbIns The USB device instance. * SET_CONFIGURATION request. * @returns VBox status code. * @param pUsbIns The USB device instance. * @param bConfigurationValue The bConfigurationValue of the new configuration. * @param pvOldCfgDesc Internal - for the device proxy. * @param pvOldIfState Internal - for the device proxy. * @param pvNewCfgDesc Internal - for the device proxy. * @returns VBox status code. * @param pUsbIns The USB device instance. * @param bInterfaceNumber The interface number. * @param bAlternateSetting The alternate setting. * Clears the halted state of an endpoint. (Optional) * This called when VUSB sees a CLEAR_FEATURE(ENDPOINT_HALT) on request * @returns VBox status code. * @param pUsbIns The USB device instance. * @param uEndpoint The endpoint to clear. * This can be used to make use of shared user/kernel mode buffers. * @returns VBox status code. * @param pUsbIns The USB device instance. * @param cbData The size of the data buffer. * @param cTds The number of TDs. * @param enmType The type of URB. * @param ppUrb Where to store the allocated URB. * @remarks Not implemented yet. * Queues an URB for processing. * @returns VBox status code. * @retval VINF_SUCCESS on success. * @retval VERR_VUSB_DEVICE_NOT_ATTACHED if the device has been disconnected. * @retval VERR_VUSB_FAILED_TO_QUEUE_URB as a general failure kind of thing. * @retval TBD - document new stuff! * @param pUsbIns The USB device instance. * @param pUrb The URB to process. * @returns VBox status code. * @param pUsbIns The USB device instance. * @param pUrb The URB to cancel. * @returns A ripe URB, NULL if none. * @param pUsbIns The USB device instance. * @param cMillies How log to wait for an URB to become ripe. /** Just some init precaution. Must be set to PDM_USBREG_VERSION. */ /** Pointer to a PDM USB Device Structure. */ /** Const pointer to a PDM USB Device Structure. */ /** Current USBREG version number. */ /** PDM USB Device Flags. /** Structure version. PDM_USBHLP_VERSION defines the current version. */ * Attaches a driver (chain) to the USB device. * The first call for a LUN this will serve as a registartion of the LUN. The pBaseInterface and * the pszDesc string will be registered with that LUN and kept around for PDMR3QueryUSBDeviceLun(). * @returns VBox status code. * @param pUsbIns The USB device instance. * @param iLun The logical unit to attach. * @param pBaseInterface Pointer to the base interface for that LUN. (device side / down) * @param ppBaseInterface Where to store the pointer to the base interface. (driver side / up) * @param pszDesc Pointer to a string describing the LUN. This string must remain valid * for the live of the device instance. * Assert that the current thread is the emulation thread. * @returns True if correct. * @returns False if wrong. * @param pUsbIns The USB device instance. * @param pszFile Filename of the assertion location. * @param iLine Linenumber of the assertion location. * @param pszFunction Function of the assertion location. * Assert that the current thread is NOT the emulation thread. * @returns True if correct. * @returns False if wrong. * @param pUsbIns The USB device instance. * @param pszFile Filename of the assertion location. * @param iLine Linenumber of the assertion location. * @param pszFunction Function of the assertion location. * Stops the VM and enters the debugger to look at the guest state. * Use the PDMUsbDBGFStop() inline function with the RT_SRC_POS macro instead of * invoking this function directly. * @returns VBox status code which must be passed up to the VMM. * @param pUsbIns The USB device instance. * @param pszFile Filename of the assertion location. * @param iLine The linenumber of the assertion location. * @param pszFunction Function of the assertion location. * @param pszFormat Message. (optional) * @param va Message parameters. * Register a info handler with DBGF, * @returns VBox status code. * @param pUsbIns The USB device instance. * @param pszName The identifier of the info. * @param pszDesc The description of the info and any arguments the handler may take. * @param pfnHandler The handler function to be called to display the info. * Allocate memory which is associated with current VM instance * and automatically freed on it's destruction. * @returns Pointer to allocated memory. The memory is *NOT* zero-ed. * @param pUsbIns The USB device instance. * @param cb Number of bytes to allocate. * Allocate memory which is associated with current VM instance * and automatically freed on it's destruction. The memory is ZEROed. * @returns Pointer to allocated memory. The memory is *NOT* zero-ed. * @param pUsbIns The USB device instance. * @param cb Number of bytes to allocate. * @returns VBox status code. * @param pUsbIns The USB device instance. * @param cbItem Size a queue item. * @param cItems Number of items in the queue. * @param cMilliesInterval Number of milliseconds between polling the queue. * If 0 then the emulation thread will be notified whenever an item arrives. * @param pfnCallback The consumer function. * @param pszName The queue base name. The instance number will be * appended automatically. * @param ppQueue Where to store the queue handle on success. * @thread The emulation thread. * Register a save state data unit. * @param pUsbIns The USB device instance. * @param uVersion Data layout version number. * @param cbGuess The approximate amount of data in the unit. * Only for progress indicators. * @param pfnLivePrep Prepare live save callback, optional. * @param pfnLiveExec Execute live save callback, optional. * @param pfnLiveVote Vote live save callback, optional. * @param pfnSavePrep Prepare save callback, optional. * @param pfnSaveExec Execute save callback, optional. * @param pfnSaveDone Done save callback, optional. * @param pfnLoadPrep Prepare load callback, optional. * @param pfnLoadExec Execute load callback, optional. * @param pfnLoadDone Done load callback, optional. * Register a STAM sample. * Use the PDMUsbHlpSTAMRegister wrapper. * @param pUsbIns The USB device instance. * @param pvSample Pointer to the sample. * @param enmType Sample type. This indicates what pvSample is pointing at. * @param enmVisibility Visibility type specifying whether unused statistics should be visible or not. * @param enmUnit Sample unit. * @param pszDesc Sample description. * @param pszName The sample name format string. * @param va Arguments to the format string. * @param pUsbIns The USB device instance. * @param enmClock The clock to use on this timer. * @param pfnCallback Callback function. * @param pvUser User argument for the callback. * @param fFlags Flags, see TMTIMER_FLAGS_*. * @param pszDesc Pointer to description string which must stay around * until the timer is fully destroyed (i.e. a bit after TMTimerDestroy()). * @param ppTimer Where to store the timer on success. * Set the VM error message * @param pUsbIns The USB device instance. * @param rc VBox status code. * @param RT_SRC_POS_DECL Use RT_SRC_POS. * @param pszFormat Error message format string. * @param va Error message arguments. * Set the VM runtime error message * @returns VBox status code. * @param pUsbIns The USB device instance. * @param fFlags The action flags. See VMSETRTERR_FLAGS_*. * @param pszErrorId Error ID string. * @param pszFormat Error message format string. * @param va Error message arguments. * @param pUsbIns The USB device instance. * @thread Any thread (just keep in mind that it's volatile info). * This differs from the RTThreadCreate() API in that PDM takes care of suspending, * resuming, and destroying the thread as the VM state changes. * @returns VBox status code. * @param pDevIns The device instance. * @param ppThread Where to store the thread 'handle'. * @param pvUser The user argument to the thread function. * @param pfnThread The thread function. * @param pfnWakeup The wakup callback. This is called on the EMT * thread when a state change is pending. * @param cbStack See RTThreadCreate. * @param enmType See RTThreadCreate. * @param pszName See RTThreadCreate. * Set up asynchronous handling of a suspend, reset or power off notification. * This shall only be called when getting the notification. It must be called * @returns VBox status code. * @param pUSBIns The USB device instance. * @param pfnAsyncNotify The callback. * Notify EMT(0) that the device has completed the asynchronous notification * This can be called at any time, spurious calls will simply be ignored. * @param pUSBIns The USB device instance. /** Just a safety precaution. */ /** Pointer PDM USB Device API. */ /** Pointer const PDM USB Device API. */ /** Current USBHLP version number. */ * PDM USB Device Instance. /** Structure version. PDM_USBINS_VERSION defines the current version. */ /** USB device instance number. */ /** The base interface of the device. * The device constructor initializes this if it has any device level * interfaces to export. To obtain this interface call PDMR3QueryUSBDevice(). */ /** Pointer the PDM USB Device API. */ /** Pointer to the USB device registration structure. */ /** Configuration handle. */ /** The (device) global configuration handle. */ /** Pointer to device instance data. */ /** Pointer to the VUSB Device structure. * Internal to VUSB, don't touch. * @todo Moved this to PDMUSBINSINT. */ /** Device name for using when logging. * The constructor sets this and the destructor frees it. */ /** Padding to make achInstanceData aligned at 32 byte boundary. */ /** Device instance data. The size of this area is defined * in the PDMUSBREG::cbInstanceData field. */ /** Current USBINS version number. */ * Checks the structure versions of the USB device instance and USB device * helpers, returning if they are incompatible. * This is for use in the constructor. * @param pUsbIns The USB device instance pointer. * Quietly checks the structure versions of the USB device instance and * USB device helpers, returning if they are incompatible. * This is for use in the destructor. * @param pUsbIns The USB device instance pointer. /** Converts a pointer to the PDMUSBINS::IBase to a pointer to PDMUSBINS. */ /** @def PDMUSB_ASSERT_EMT * Assert that the current thread is the emulation thread. /** @def PDMUSB_ASSERT_OTHER * Assert that the current thread is NOT the emulation thread. /** @def PDMUSB_SET_ERROR * Set the VM error. See PDMUsbHlpVMSetError() for printf like message /** @def PDMUSB_SET_RUNTIME_ERROR * Set the VM runtime error. See PDMUsbHlpVMSetRuntimeError() for printf like * @copydoc PDMUSBHLP::pfnDriverAttach * VBOX_STRICT wrapper for pHlpR3->pfnDBGFStopV. * @returns VBox status code which must be passed up to the VMM. * @param pUsbIns Device instance. * @param RT_SRC_POS_DECL Use RT_SRC_POS. * @param pszFormat Message. (optional) * @param ... Message parameters. * @copydoc PDMUSBHLP::pfnVMState * @copydoc PDMUSBHLP::pfnThreadCreate * @copydoc PDMUSBHLP::pfnSetAsyncNotification * @copydoc PDMUSBHLP::pfnAsyncNotificationCompleted * Set the VM error message * @param pUsbIns The USB device instance. * @param rc VBox status code. * @param RT_SRC_POS_DECL Use RT_SRC_POS. * @param pszFormat Error message format string. * @param ... Error message arguments. * @copydoc PDMUSBHLP::pfnMMHeapAlloc * @copydoc PDMUSBHLP::pfnMMHeapAllocZ * Frees memory allocated by PDMUsbHlpMMHeapAlloc or PDMUsbHlpMMHeapAllocZ. * @param pUsbIns The USB device instance. * @param pv The memory to free. NULL is fine. * @copydoc PDMUSBHLP::pfnTMTimerCreate /** Pointer to callbacks provided to the VBoxUsbRegister() call. */ * Callbacks for VBoxUSBDeviceRegister(). * This is set to PDM_USBREG_CB_VERSION. */ * Registers a device with the current VM instance. * @returns VBox status code. * @param pCallbacks Pointer to the callback table. * @param pReg Pointer to the USB device registration record. * This data must be permanent and readonly. /** Current version of the PDMUSBREGCB structure. */ * The VBoxUsbRegister callback function. * PDM will invoke this function after loading a USB device module and letting * the module decide which devices to register and how to handle conflicts. * @returns VBox status code. * @param pCallbacks Pointer to the callback table. * @param u32Version VBox version number.