Previous

Next

Structure RTUSBConfig

RTUSBConfig is a global structure of type RTUSB32Config containing configuration data for RTUSB-32:

typedef struct { 
   DWORD Version; 
   DWORD Flags; 
   int   MaxHandles; 
   int   HubTaskPriority; 
   int   HubTaskStackSize; 
   int   HubQSize; 
   int   UHCIHubPoll; 
   int   ControlTimeout; 
   int   IsoDelay; 
   int   MaxIsoBandwidth; 
   int   MaxIsoBandwidth2; 
   int   RootHubPortPower; 
   int   ExtHubPortPower; 
   int   EHCIMaxPollBulk; 
   int   RetryDelay; 
} RTUSB32Config;

A default version of this structure is included in the RTUSB-32 library. If you want to define your own configuration, include this structure in your program or modify selected fields before RTUSB-32 is initialized.

Example (using RTUSB-32's defaults):

#include <rtusb.h> 

RTUSB32Config RTUSBConfig = 
{ 
           RTUSB_VER,   // Version 
  RTU_HALT_IDLE_UHCI,   // Flags 
                 256,   // MaxHandles 
                   0,   // HubTaskPriority 
                4096,   // HubTaskStackSize 
                  32,   // HubQSize 
                 300,   // UHCIHubPoll 
                1000,   // ControlTimeout 
                   4,   // IsoDelay 
                1200,   // MaxIsoBandwidth 
                6000,   // MaxIsoBandwidth2 
                 500,   // RootHubPortPower 
                 500,   // ExtHubPortPower 
                 512,   // EHCIMaxPollBulk 
                5000,   // RetryDelay 

};

RTUSBConfig Members

Version

The RTUSB-32 version number.

Flags

Flags which can control the behavior of RTUSB-32. The following values are currently defined:

MaxHandles

Maximum number of pipe handles which can be open at any given time. This value may not be greater than or equal to 2¹⁶. This value is used to allocate an array of MaxHandles * 4 bytes size at program initialization. Note that most USB devices need only about 2 to 5 pipes, so 256 is enough for at least 50 devices being connected and operating at the same time.

HubTaskPriority

Thread priority for the hub class driver's thread. This thread needs very little CPU time and has no real-time requirements. The hub class driver's thread is responsible for detecting and handling attachment and detachment events. Value 0 will cause the default priority to be assigned to the hub task.

HubTaskStackSize

Stack size for the hub class driver's thread. Note that this thread calls attachment and detachment callbacks. All callbacks included with RTUSB-32 need less than 4k stack space.

HubQSize

Number of message buffers the hub class driver's message queue can buffer. This value should be as large as the number of hubs which must be supported simultaneously. Increase this value if you get "queue full" error messages.

UHCIHubPoll

UHCI controllers cannot notify the USB stack by interrupt when a device is attached or detached to/from the root hub. RTUSB-32's hub thread polls the UHCI root hub status registers every UHCIHubPoll milliseconds.

ControlTimeout

Default number of milliseconds to wait on Control transactions using RTUSendSetup before a non-completing transaction is canceled. For each pipe, this values can be overridden with RTUSetPipeOption.

IsoDelay

Number of milliseconds to wait until a new Isochronous transaction is started after the first call to RTUStartIO. This value may not be set too low as the stack needs some time to setup and initialize a transaction.

MaxIsoBandwidth

Maximum bandwidth for Isochronous endpoints in bytes per frame that RTUSB-32 will allow to be scheduled on a version 1.1 USB. Note that each Isochronous endpoint needs 9 bytes in addition to its maximum packet size for protocol overhead.

MaxIsoBandwidth2

Maximum bandwidth for Isochronous endpoints in bytes per microframe that RTUSB-32 will allow to be scheduled on a version 2.0 USB. Note that each Isochronous endpoint needs 38 bytes in addition to its maximum packet size for protocol overhead.

RootHubPortPower

The amount of power the root hub can supply per port in milliamperes. 500 is the minimum required by the USB spec, but many host controllers can supply more.

ExtHubPortPower

The amount of power that external, self-powered hubs can supply per port in milliamperes. Again, many hubs are able to supply more than the required 500 mA minimum.

EHCIMaxPollBulk

This value only applies to High-Speed Bulk transfers. Unless RTUSetPipeOption(..., RTUAsynch, 1) has been called, transactions with EHCIMaxPollBulk bytes or less will be polled up to 2 microframes for completion. For all other transactions, completion is detected by interrupt. Since EHCI controllers have a high interrupt latency, polling for small transfers can improve performance significantly. This feature is a tradeoff between high throughput and high CPU load. Setting this value to 0 disables this feature and processes all transactions by interrupt. RTUSetPipeOption(..., RTUAsynch, 1) disables it for a particular pipe only.

RetryDelay

Number of microseconds to wait between retries to connect a new USB device. RTUSB-32 will make 10 attempts to initialize a newly connected device before giving up.

Initialization

Function RTURegisterCallback