Difference between revisions of "USB Stack"

Revision as of 07:59, 29 December 2019

The USB stack is the component that provides the communication between USB devices and their respective drivers and applications. It consists of multiple files, each with a distinct function. The USB stack in ReactOS is currently limited. This page documents the development of the new USB stack. Development work on a USB 3 stack is in progress.

NOTE: There is a known issue with booting ReactOS from the internal HDD with a USB storage device connected which causes ROS to lose the boot device. Until this problem is fixed or a workaround is developed, please unplug any USB storage devices during boot!

Overview

The goal is to develop a USB stack which:

is USB 1.1 – 2.0 compliant
uses WDM (NT 5) API
is compatible with all USB devices and drivers (which adhere to the standard)

The entire stack will be fully documented and the implementation progress detailed on this page.

Goals

Primary Goal: USBHID (human input devices) and storage functionality working (Alpha).
Secondary Goal: Audio and other support added.
Beyond: testing and debugging.

Due to the complexity and size, no release dates will be provided as of now.

Status

USB Core Status

There are 2 USB specifications for the USB 1.1 standard. Devices that are used in this standard are mice, keyboards, etc.
- OHCI (Open Host Controller Interface Standard) – All transfers types are implemented (bulk, iso, control, interrupt)
- UHCI (Universal Host Controller Interface Standard) – Totally missing. Though it should be do-able to use OHCI driver as a base and use Haiku driver
EHCI (Enhanced Host Controller Interface) – Implemented transfer types: bulk & control. Interrupt & Isochronous transfers are not implemented. Due to the missing transfer types, devices who utilize those transfer types will not be available.
USBHUB – driver for managing port and hubs – Implementation state is unknown – Michel Martin has more information on that

USB Mass Storage Support Status

USB Mass Storage is implemented in USBSTOR driver and is fully working. Tested in WinXP + USBEHCI + USBSTOR. Mass storage support requires bulk and control transfers, which are implemented in USBEHCI.

HID Status

The HID framework is built on 5 drivers

HIDUSB – this is the interface driver for the USB bus. Currently supported devices are mice. Basic keyboard support should also work currently.
HIDCLASS – this is the class driver for HIDUSB and others. Functionality for mice & keyboard is implemented, though support for sending output reports is not implemented.
MOUHID – mouse function driver for USB hid standard – Fully implemented and working.
KBDHID – keyboard function driver for the hid standard – 90% implemented, needs KbdHid_InsertScanCodes implemented for keyboard scan code dispatching to kbdclass and led status indicator support (which requires sending output reports).
HIDPARSE – driver for parsing report descriptors – functionality implemented for mice, keyboard support needs HidParser_TranslateUsage fully implemented for modifier state (caps lock, num lock, scroll lock).

What already works

Mouse support has been tested in WinXP with ReactOS USBOHCI + HIDUSB + HIDCLASS + MOUHID + HIDPARSE and is working. The USB + HID stack also works in ReactOS.
Basic Keyboard support is nearly ready.
USB Mass storage support – Needs mountmgr / partmgr driver implemented. Will also need mountvol and other missing PnP stuff. - needs a few more issues to be resolved

References

USB.org specifications
XEN PV USB Drivers
Roadmap for Developing USB Drivers
Windows Driver Kit (Driver Development Kit)
USB Driver Stack for Windows XP and later
USB Device Stack for Windows XP and later
USB 3.0 xHCI specifications

@@ Line 1: / Line 1: @@
-The USB stack is the component which provides the communication between USB devices and their respective drivers and applications. It consists of multiple files, each with a distinct function. The USB stack in ReactOS is currently extremely limited. This page documents the development of the new USB stack. Development work on a USB 3 stack is not planned until around 2010 as hardware won't be available for it in sufficient quantities until then.
+The [[USB]] stack is the component that provides the communication between [[USB]] devices and their respective drivers and applications. It consists of multiple files, each with a distinct function. The [[USB]] stack in [[ReactOS]] is currently limited. This page documents the development of the new [[USB]] stack. Development work on a [[USB]] 3 stack is in progress.
+'''NOTE: There is a known issue with booting [[ReactOS]] from the internal HDD with a [[USB]] storage device connected which causes ROS to lose the boot device. Until this problem is fixed or a workaround is developed, please unplug any [[USB]] storage devices during boot!'''
 == Overview ==
+The goal is to develop a [[USB]] stack which:
-The goal is to develop a USB stack which:
+* is USB 1.1 – 2.0 compliant
-* is USB 1.1 - 2.0 compliant
 * uses WDM (NT 5) API
 * is compatible with all USB devices and drivers (which adhere to the standard)
 The entire stack will be fully documented and the implementation progress detailed on this page.
 == Goals ==
+* Primary Goal: USBHID (human input devices) and storage functionality working (Alpha).
-* Primary Goal: USB HID (human input devices) and storage functionality working (Alpha).
 * Secondary Goal: Audio and other support added.
 * Beyond: testing and debugging.
-Release dates will be provided at some point in the near future.
+Due to the complexity and size, no release dates will be provided as of now.
 == Status ==
+=== USB Core Status ===
+* There are 2 USB specifications for the USB 1.1 standard. Devices that are used in this standard are mice, keyboards, etc.
+** [[OHCI]] (Open Host Controller Interface Standard) – All transfers types are implemented (bulk, iso, control, interrupt)
+** [[UHCI]] (Universal Host Controller Interface Standard) – Totally missing. Though it should be do-able to use OHCI driver as a base and use [http://cgit.haiku-os.org/haiku/tree/src/add-ons/kernel/busses/usb/uhci.cpp Haiku driver]
+* [[EHCI]] (Enhanced Host Controller Interface) – Implemented transfer types: bulk & control. Interrupt & Isochronous transfers are not implemented. Due to the missing transfer types, devices who utilize those transfer types will not be available.
+* USBHUB – driver for managing port and hubs – Implementation state is unknown – Michel Martin has more information on that
-'''2009/03/22''' - Goals updated. The new deadline is 'When it's done'. As a part reaches usability stage, this will be announced. The CFI wiki page now reflects 1,000 Euro & 8 weeks required, which may be somewhat accurate. We'll see.
+=== USB Mass Storage Support Status ===
+[http://www.eltima.com/share-usb-drive-over-network/ USB Mass Storage] is implemented in [[USBSTOR]] driver and is fully working. Tested in WinXP + [[EHCI|USBEHCI]] + [[USBSTOR]]. Mass storage support requires bulk and control transfers, which are implemented in [[EHCI|USBEHCI]].
-'''2009/01/26''' - Due to lack of time and the diffuse nature of the available information on the Windows USB stack, progress has been slow. A delay of a month has been introduced. For those who would like to see faster progress, I can only say that for around 500 Euro a month, work on the USB stack could be full-time (5 days/week).
+=== HID Status ===
+The HID framework is built on 5 drivers
-'''2008/12/03''' - The ROS USB stack specification is being written. The first draft will be ready in a few weeks.
+* HIDUSB – this is the interface driver for the USB bus. Currently supported devices are mice. Basic keyboard support should also work currently.
+* HIDCLASS – this is the class driver for HIDUSB and others. Functionality for mice & keyboard is implemented, though support for sending output reports is not implemented.
+* [[MOUHID]] – mouse function driver for USB hid standard – Fully implemented and working.
+* [[KBDHID]] – keyboard function driver for the hid standard – 90% implemented, needs KbdHid_InsertScanCodes implemented for keyboard scan code dispatching to kbdclass and led status indicator support (which requires sending output reports).
+* HIDPARSE – driver for parsing report descriptors – functionality implemented for mice, keyboard support needs HidParser_TranslateUsage fully implemented for modifier state (caps lock, num lock, scroll lock).
-== References ==
+=== What already works ===
+* Mouse support has been tested in WinXP with ReactOS [[OHCI|USBOHCI]] + HIDUSB + HIDCLASS + [[MOUHID]] + HIDPARSE and is working. The USB + HID stack also works in ReactOS.
+* Basic Keyboard support is nearly ready.
+* USB Mass storage support – Needs mountmgr / partmgr driver implemented. Will also need mountvol and other missing PnP stuff. - needs a few more issues to be resolved
-* USB.org's USB 2 specification.
+== See Also ==
-* Windows Driver Kit (Driver Development Kit).
-* various books and sites on the WDM model, to be expanded later.
+*[[Supported USB Devices]]
-== Historical (outdated) information ==
+*[[USB Todo]] List
-The information here is largely outdated and irrelevant to current development. It is shown here for historical purposes, later it may be moved to its own page or removed.
-'''Roadmap of USB development for ReactOS'''
-After some thinking and talking to X-Box guys, I decided to try implementing part of ReactOS USB Stack with help of a Linux USB Stack, but in a very special flavour - which is abstracted from Linux kernel, and from hardware also (this implementation is used in [[Cromwell]]).
-So now we have two concurrent tasks going on:
-* Porting Cromwell usb stuff to ReactOS (I already make it compiling into usbcore.sys and ohci.sys - this all is placed at reactos/drivers/usb/cromwell/, but hardware interface needs to be changed to use HAL)
-* Creating compatible interface to higher level of USB drivers (e.g. Class drivers, etc) - so we can have compatibility with Windows XP here. This involves creating a usbport.sys driver, which have all IRPs and IOCTLs stubbed, and then we can fill it with calls to the ported usbcore.sys and ohci.sys.
-* Creating [[driver]]s for other host controllers (currently only OpenHCI is done in Cromwell's usb drivers). Universal HCD would be a very nice thing to do, I think the best way is to get uhci hcd from linux stack, and adapt it to ReactOS.
-* Creating class drivers and other higher-level stuff -- we can test our lower level drivers with class drivers from WinXP.
-'''Current Status'''
-As there seems to be some interest in the current status of USB support
-on ReactOS, I'm going to keep a current status section on this wiki page.
-  '''Oct 19 2005'''
-* Both OHCI and UHCI USB controllers work: they are detected, initialized and they detect connected devices, which are reported to Plug-and-play manager.
-* Basic drivers for USB mice and keyboards are provided (but *disabled* due to a conflict with [[i8042prt|I8042prt]] driver)
-* USB stack is fully PnP compliant, so it should work on every hardware without the need to add some registry entries as previously.
-* About source files: They now live in reactos/drivers/usb/. OHCI and UHCI are in reactos/drivers/usb/miniport/xHCI and share most of their code.
-* Work in progress: [[Aleksey Bragin|Fireball]] is now changing the code from a polled mode to an interrupt mode, to consume less CPU resources.
-  '''Aug 3 2005'''
-* OHCI Drivers from Cromwell/Linux work under Microsoft Virtual PC. They initialize the hardware controller and the main hub, and they detect connected devices, and URBs can be transfered. On Xbox (which also has USB with OHCI controllers), connected devices are not reported. It may be due to the fact that Xbox has 2 USB controllers. The problem is under investigation.
-* UHCI Drivers still don't work at the moment. The hardware controller and the main hub are initialized, but no connected device is detected.
-* In both cases (OHCI and UHCI), main hub is reported to ReactOS plug-and-play manager. Connected devices are still not reported.
-  '''Feb 20 2005'''
-* Initial working implementation of UsbCore+OHCI Drivers from Cromwell/Linux. They do everything needed, two things left:
-) make them running better (in fact currently there are an active waiting inside a thread - this wastes resources greatly - should be changed by WaitForSingleObject, and second - implement stubs for spinlocks - I think they are needed)
-) Understand public interface of Microsoft's usbport.sys/usbhub.sys, and implement it in usbcore/Xhci.
-* I'm working on porting uhci from Linux now also. Since OHCI seems to be a rare controller, very few people can test it. But it isn't that straightforward (dma, etc), but I hope I can do it.
-  '''Feb 2 2005'''
-* Started implementing the basics of USBPORT.SYS.  It now keeps the large struct passed in from a miniport in a driver extention.  This happens when the miniport registers itself with USBPORT.SYS.
-* Added stubbed implementations for AddDevice, DispatchCreateClose, DispatchDeviceControl, and Unload.  Still more to do to make these things actually work.
-* Started stubbing out the IOCTLs for USB.
-  '''TO DO LIST'''
-* NOTE: None of this work has been committed yet.  I'm just keeping up with my promise to keep this status basically up to date.
-* We need to implement USBD.SYS since that is mainly a library (in the XP stack) with utility routines for processing URBs.  This would be a nice simple project for some one to do if they want to get started helping with the USB stack.
-* We need to port uhci support from Linux to the Cromwell framework.  VMWare on Windows does not have an ohci controller (the controller we currently have ported) so any testing in VMWare (and on lots of hardware platforms) will be useless without uhci.
-* We need to port ehci support from Linux to the Cromwell framework.  This will give us support for USB 2.0 hubs and devices.... well eventually anyway...
-So any complaints about the slow pace of USB stack implementation can be sent to /dev/null.  Any help would be welcome.
-  '''Jan 27 2005'''
-* Committed initial port of Cromwell's USB stack. Need to port all hw calls to HAL.
-  '''Jan 17 2005'''
-* USB stubs are committed to SVN with the paths listed on this page. Actually this happend earlier, but I figure that I might as well start this list somewhere.
-* Building the headers for the ROS ddk to spec in the USBHUB.SYS -> USBPORT.SYS interface.  This interface is not documented super well, but much of the needed information can be gathered online.
-* Adding usb to the main ROS build.
-* Adding the usbuhci startup registry entries to hivesys.inf.  After this we can see USBUHCI.SYS and USBPORT.SYS actually load.  They won't do anything, but at least they will load.   Well... it's a start.
-'''Directory Layout'''
-  /reactos/
-  /reactos/drivers/
-  /reactos/drivers/usb
-  /reactos/drivers/usb/usbport
-  /reactos/drivers/usb/miniport/usbuhci
-  /reactos/drivers/usb/miniport/usbehci
-  /reactos/drivers/usb/miniport/usbohci
-  /reactos/drivers/usb/usbhub
-  /reactos/drivers/usb/usbd
-  /reactos/drivers/cromwell/...
-'''USBPORT.SYS'''
-This driver is the main port driver for USB host controllers.  In a nutshell, it receives all IRPs and IOCTLs, and translates them into information that is useful for miniports.  It is responsible for managing all the host controllers on the system. Each host controller type is managed by a miniport driver.
-The interface between the port driver and its miniports is not published or documented anywhere.  This means that we are relatively free to implement this any way we choose.  The plan is to try to leverage the host controller driver implementation from the Linux kernel (at least as a reference), and define our own protocol.
-USBPORT.SYS does provide a public interface, and it understands a known list of IOCTLs.  We must make sure that our version of USBPORT.SYS manages its public interface in a manner consistent with the USB stack on Windows XP.
-'''USBUHCI.SYS'''
-This is the miniport for UHCI USB controllers.
-'''USBEHCI.SYS'''
-This is the miniport for EHCI (USB 2.0) controllers.
-'''USBOHCI.SYS'''
-This the miniport for OpenHCI USB controllers (this one is needed for XBOX-ReactOS project).
-'''USBHUB.SYS'''
-This is the USB hub driver.
-'''USBD.SYS'''
-This is a legacy USB bus driver from the Windows 2K system.  In Windows XP it simply delegates all its methods to USBHUB.SYS and USBPORT.SYS.  We will do the same thing in ReactOS (aiming WinXP was discussed many times, and considered finally a good choice than targeting old usb architecture of Win2k).
-'''Windows XP (and ReactOS) USB Stack Startup'''
-  --thoughtfully provided by Ryan O'Connor (Polonium)
+== References ==
+* [http://www.usb.org/developers/docs/ USB.org specifications]
+* [http://xenbits.xensource.com/ext/win-pvdrivers.hg XEN PV USB Drivers]
+* [http://msdn.microsoft.com/en-us/library/ff537858.aspx Roadmap for Developing USB Drivers]
+* Windows Driver Kit (Driver Development Kit)
+* [http://www.microsoft.com/whdc/archive/USB2support.mspx?pf=true USB Driver Stack for Windows XP and later]
+* [http://msdn.microsoft.com/en-us/library/ff539301.aspx USB Device Stack for Windows XP and later]
+* [http://www.intel.com/technology/USB/download/xHCI_Specification_for_USB.pdf USB 3.0 xHCI specifications]
-[[Category:Hardware]]
 [[Category:Documentation]]
+[[Category:ReactOS Components]]

Difference between revisions of "USB Stack"

Revision as of 07:59, 29 December 2019

Contents

Overview

Goals

Status

USB Core Status

USB Mass Storage Support Status

HID Status

What already works

See Also

References

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools