Introduction

Authors: B.D.,V.S.

© 2003 Simtec Electronics

This release is primarily to merge the work that has been done on USB2.0 support for the embedded build. The merge brings the embedded and RISC OS builds into line with each other, and also removes old structure fields that where in the original releases that are no longer relevant.

All efforts have been made to keep backwards compatibility with the USB1.1 compliant releases, and old code should work as-is. It is important though that all driver code is compiled against the new library to check that old fields are not being accessed, as these have been removed and recycled in this release.

The new API code provides support for new drivers to run without the new capability on older cores, and therefore some care should be taken to ensure that any NULL returns, or errors from new calls or macros be taken to mean these features are not available, and that the original structures can be used as fallback.

USB2 compatibility

The API has been extended to allow the use of USB2 devices in the future. These changes have been designed to be backwards compatible, so that no USB1.1 device driver should need to be modified to work with either the old or new versions of the API.

The USB2 definitions are available in the new release are included in an separate include directory, and very few modifications have been made to the usb/* include files. These provide access to the extended information available to USB2 compliant devices.

32Bit RISC OS Build

The Modules are all now built with StubsG this fixes problems with loading USB and the use of the newer SharedCLibrary that some applications seem to need.

The 32bit release modules are NOT fully 32bit clean, and have not been tested on any 32bit only computer. Do not expect these to work fully in any 32bit only machine.

This release includes not only 26bit builds of the library files but also 32bit (APCS v3, 32bit) builds, include in !USBLib.lib32.

The 32bit library build is available for anyone building 32bit applications. The link files contain the same routines as their 26bit counterparts.

General Updates and bug fixes

The following updates are included in the release:

• *USBDevices has been updated to show the new high-speed configuration data supplied by USB2 devices.
• !USBLib now contains the new USB2 headers in headers/usb2.
• !USBLib.lib32 contains 32bit library build.
• USBHub module uses new registration code
• USBCore interface version updated to 200
• New SWIs USB_EndpointRegister2 and USB_DeviceRegister2 added to the system.
• Fixed bug in hub configuration causing infinite loop if device does not respond correctly.
• Fixed problem with some printing out with USBPrinters (Especialy easywriter)
• Larger printer buffer for printer
• *USBDevices now reports which request encountered an error
• HID code updated due to bug in report count field generation (also affected the reports printed by *USBDevices)
• USBISP1161 driver now re-tries to setup roothub if USBHub driver is loaded after it. This means the order of loading any modules other than the USB core is now non critical.
• usbmsg_class_module added to usb/msg.h for information on usb modules. You are encouraged to handle USBMSG_MODULE_LIST in your own driver modules. There is code in the library to help out (see usb/lib/mod-msg.h for details.
• *USBShowMod command added to list all loaded modules which reply to the usbmsg_class_module message
• Updated HID database of known usages
• USBHub fix for user reset of devices
• Debug of issues with Baildon/APDL IDE card (now logged by USBISP1161) - IDE card authors aware of issue.

Development files changes

usb/defs.h

• USB_STRUCT_DESCR_CONFIGURATION_MaxPower renamed to USB_STRUCT_DESCR_CONFIGURATION_bMaxPower.
• USB OtG descriptor added.

usb/usb.h

• Removed the following unused definitions:
  • USB_TRANSACTION_S_R_NO_FUNCTION
  • USB_TRANSACTION_S_R_HALT_PIPE
  • USB_TRANSACTION_S_R_CLEAR_PIPE
  • USB_TRANSACTION_S_R_ADDRESS
• Removed struct usb_transaction_s (no longer used)
• Added USB_EPFLAG_* definitions for new usb_endpoint_t ep_flags field
• New struct struct usb_ep_info_s which contains information from the endpoint's USB descriptor. This is added as an `cache` to avoid constant lookup of these fields from the USB descriptors. These fields are placed inside the usb_endpoint_t ep_info union, and are dependant on USB_EPFLAG_INFOVALID in ep_flags.

USB2 header files

The new USB2 header files are provided for applications that wish to take advantage of the extended information provided by the newer cores. This information may be present even if the device itself conforms to pre USB2.0 specifications, as the new system will try and use the new API calls in preference to the older USB1.1 calls.

The usb2/*.h header files can be used in preference to the older usb/*.h header files as they will include the older variants as needed. Care should be taken to ensure that the build system has the correct header dependency information.

usb2/usb.h

This is the main header file for use when accessing the USB2 extensions. This should be included before usb2/structs.h.

usb2/defs.h

Provides various definitions, including the new USB2 descriptor definitions. This is similar to usb/defs.h. The following items have been added:

• USB_DEVICE_SPEED_HIGH for 480Mbit devices
• Descriptors type code and information for:
  • Device Qualifier (USB_CONTROL_DESCRIPTOR_DEVICE_QUALIFIER)
  • Other Speed configuration (USB_CONTROL_DESCRIPTOR_OTHER_SPEED_CONFIGURATION)
  • Interface Power (USB_CONTROL_DESCRIPTOR_INTERFACE_POWER)
  • On-the-go (USB_CONTROL_DESCRIPTOR_OTG)
  • Debug (USB_CONTROL_DESCRIPTOR_DEBUG)
  • Interface Association (USB_CONTROL_DESCRIPTOR_INTERFACE_ASSOCIATION)

usb2/structs.h

Definitions of the new USB2 structures, including the extended device and endpoint structures, usb2_device_t and usb2_endpoint_t.

usb2/device.h

Support for using the extended usb2_device_t structure, including verification macros (usb_is_v2dev) and usb_dev_getver (return the USB revision number this device actually conforms to.

Since the two structures are compatible, it is possible to switch between an usb2_device_t and an usb_device_t, and macros are provided to do this. The usb_get_v2dev macro will convert a pointer to usb_device_t into an pointer to usb2_device_t, if it is an V2 structure (NULL will be returned if not.)

Note, it is possible to have an USB1.1 device registered with an USB2 structure, as these are backwards compatible, and that the newer hub driver will use the new registration functions in preference to the old interface.

usb2/endpoint.h

Currently there are no extensions for usb2_endpoint_t. This header file provides the new registration definitions.

usb2/tt.h

Definitions for the USB2 transaction translators found in USB2 hubs. Normal drivers should not need to know anything about these, these definitions are informational use at current time.

RISC OS specific changes

SWI USB_Version returns r0 = 200, to signify new interface. The new SWIs USB_EndpointRegister2 and USB_DeviceRegister2 have been added.

USB Library object changes

• usblib_register_endpoint and usblib_register_device helper functions for registering device.
• Veneer call usb_device_register2 for SWI USB_DeviceRegister2
• Veneer call usb_endpoint_register2 for SWI USB_EndpointRegister2
• The following library calls now return USB_RESULT_NOT_AVAILABLE if USB module is not loaded:
  • usb_endpoint_register
  • usb_controller_deregister
  • usb_buffer_free
  • usb_buffer_malloc

$Id: usb-201-relnotes.html 376 2003-12-10 13:03:30Z vince $