Subversion Repositories openrisc

Introduction

Introduction

eCos support for USB slave devices

The eCos USB slave support allows developers to produce USB

peripherals. It consists of a number of different eCos packages:

Device drivers for specific implementations of USB slave hardware, for

example the on-chip USB Device Controller provided by the Intel SA1110

processor. A typical USB peripheral will only provide one USB slave

port and therefore only one such device driver package will be needed.

Usually the device driver package will be loaded automatically when

you create an eCos configuration for target hardware that has a USB

slave device. If you select a target which does have a USB slave

device but no USB device driver is loaded, this implies that no such

device driver is currently available.

The common USB slave package. This serves two purposes. It defines the

API that specific device drivers should implement. It also provides

various utilities that will be needed by most USB device drivers and

applications, such as handlers for standard control messages.

Usually this package will be loaded automatically at the same time as

the USB device driver.

The common USB package. This merely provides some information common

to both the host and slave sides of USB, such as details of the

control protocol. It is also used to place the other USB-related

packages appropriately in the overall configuration hierarchy. Usually

this package will be loaded at the same time as the USB device driver.

Class-specific USB support packages. These make it easier to develop

specific classes of USB peripheral, such as a USB-ethernet device. If

no suitable package is available for a given class of peripheral then

the USB device driver can instead be accessed directly from

application code. Such packages will never be loaded automatically

since the configuration system has no way of knowing what class of USB

peripheral is being developed. Instead developers have to add the

appropriate package or packages explicitly.

These packages only provide support for developing USB peripherals,

not USB hosts.

Information about USB can be obtained from a number of sources

including the USB Implementers Forum

web site. Only a brief summary is provided here.

A USB network is asymmetrical: it consists of a single host, one or

more slave devices, and possibly some number of intermediate hubs. The

host side is significantly more complicated than the slave side.

Essentially, all operations are initiated by the host. For example, if

the host needs to receive some data from a particular USB peripheral

then it will send an IN token to that peripheral; the latter should

respond with either a NAK or with appropriate data. Similarly, when

the host wants to transmit data to a peripheral it will send an OUT

token followed by the data; the peripheral will return a NAK if it is

currently unable to receive more data or if there was corruption,

otherwise it will return an ACK. All transfers are check-summed and

there is a clearly-defined error recovery process. USB peripherals can

only interact with the host, not with each other.

USB supports four different types of communication: control messages,

interrupt transfers, isochronous transfers, and bulk transfers.

Control messages are further subdivided into four categories:

standard, class, vendor and a reserved category. All USB peripherals

must respond to certain standard control messages, and usually this

will be handled by the common USB slave package (for complicated

peripherals, application support will be needed). Class and vendor

control messages may be handled by an class-specific USB support

package, for example the USB-ethernet package will handle control

messages such as getting the MAC address or enabling/disabling

promiscuous mode. Alternatively, some or all of these messages will

have to be handled by application code.

Interrupt transfers are used for devices which need to be polled

regularly. For example, a USB keyboard might be polled once every

millisecond. The host will not poll the device more frequently than

this, so interrupt transfers are best suited to peripherals that

involve a relatively small amount of data. Isochronous transfers are

intended for multimedia-related peripherals where typically a large

amount of video or audio data needs to be exchanged continuously.

Given appropriate host support a USB peripheral can reserve some of

the available bandwidth. Isochronous transfers are not reliable; if a

particular packet is corrupted then it will just be discarded and

software is expected to recover from this. Bulk transfers are used for

everything else: after taking care of any pending control, isochronous

and interrupt transfers the host will use whatever bandwidth remains

for bulk transfers. Bulk transfers are reliable.

Transfers are organized into USB packets, with the details depending

on the transfer type. Control messages always involve an initial

8-byte packet from host to peripheral, optionally followed by some

additional packets; in theory these additional packets can be up to 64

bytes, but hardware may limit it to 8 bytes. Interrupt transfers

involve a single packet of up to 64 bytes. Isochronous transfers

involve a single packet of up to 1024 bytes. Bulk transfers involve

multiple packets. There will be some number, possibly zero, of 64-byte

packets. The transfer is terminated by a single packet of less than 64

bytes. If the transfer involves an exact multiple of 64 bytes than the

final packet will be 0 bytes, consisting of just a header and checksum

which typically will be generated by the hardware. There is no

pre-defined limit on the size of a bulk transfer. Instead higher-level

protocols are expected to handle this, so for a USB-ethernet

peripheral the protocol could impose a limit of 1514 bytes of data

plus maybe some additional protocol overhead.

Transfers from the host to a peripheral are addressed not just to that

peripheral but to a specific endpoint within that peripheral.

Similarly, the host requests incoming data from a specific endpoint

rather than from the peripheral as a whole. For example, a combined

keyboard/touchpad device could provide the keyboard events on endpoint

1 and the mouse events on endpoint 2. A given USB peripheral can have

up to 16 endpoints for incoming data and another 16 for outgoing data.

However, given the comparatively high speed of USB I/O this endpoint

addressing is typically implemented in hardware rather than software,

and the hardware will only implement a small number of endpoints.

Endpoint 0 is generally used only for control messages.

In practice, many of these details are irrelevant to application code

or to class packages. Instead, such higher-level code usually just

performs blocking read and

write, or non-blocking USB-specific calls, to

transfer data between host and target via a specific endpoint. Control

messages are more complicated but are usually handled by existing

code.

When a USB peripheral is plugged into the host there is an initial

enumeration and configuration process. The peripheral provides

information such as its class of device (audio, video, etc.), a

vendor id, which endpoints should be used for what kind of data, and

so on. The host OS uses this information to identify a suitable host

device driver. This could be a generic driver for a class of

peripherals, or it could be a vendor-specific driver. Assuming a

suitable driver is installed the host will then activate the USB

peripheral and perform additional application-specific initialisation.

For example for a USB-ethernet device this would involve obtaining an

ethernet MAC address. Most USB peripherals will be fairly simple, but

it is possible to build multifunction peripherals with multiple

configurations, interfaces, and alternate interface settings.

It is not possible for any of the eCos packages to generate all the

enumeration data automatically. Some of the required information such

as the vendor id cannot be supplied by generic packages; only by the

application developer. Class support code such as the USB-ethernet

package could in theory supply some of the information automatically,

but there are also hardware dependencies such as which endpoints get

used for incoming and outgoing ethernet frames. Instead it is the

responsibility of the application developer to provide all the

enumeration data and perform some additional initialisation. In

addition, the common USB slave package can handle all the standard

control messages for a simple USB peripheral, but for something like a

multifunction peripheral additional application support is needed.

The initial implementation of the eCos USB slave packages involved

hardware that only supported control and bulk transfers, not

isochronous or interrupt. There may be future changes to the USB

code and API to allow for isochronous and interrupt transfers,

especially the former. Other changes may be required to support

different USB devices. At present there is no support for USB remote

wakeups, since again it is not supported by the hardware.

For protocols other than control messages, eCos provides two ways of

performing USB I/O. The first involves device table or devtab entries such

as /dev/usb1r,

with one entry per endpoint per USB device. It is possible to

open these devices and use conventional blocking

I/O functions such as read and

write to exchange data between host and

peripheral.

There is also a lower-level USB-specific API, consisting of functions

such as 

linkend="usbs-start-rx">usbs_start_rx_buffer.

A USB device driver will supply a data structure for each endpoint,

for example a 

linkend="usbs-data">usbs_rx_endpoint

structure for every receive endpoint. The first argument to

usbs_start_rx_buffer should be a pointer to such

a data structure. The USB-specific API is non-blocking: the initial

call merely starts the transfer; some time later, once the transfer

has completed or has been aborted, the device driver will invoke a

completion function.

Control messages are different. With four different categories of

control messages including application and vendor specific ones, the

conventional

open/read/write

model of I/O cannot easily be applied. Instead, a USB device driver

will supply a 

linkend="usbs-control">usbs_control_endpoint

data structure which can be manipulated appropriately. In practice the

standard control messages will usually be handled by the common USB

slave package, and other control messages will be handled by

class-specific code such as the USB-ethernet package. Typically,

application code remains responsible for supplying the 

linkend="usbs-enum">enumeration data and for actually 

linkend="usbs-start">starting up the USB device.

If the target hardware contains a USB slave device then the

appropriate USB device driver and the common packages will typically

be loaded into the configuration automatically when that target is

selected (assuming a suitable device driver exists). However, the

driver will not necessarily be active. For example a processor might

have an on-chip USB device, but not all applications using that

processor will want to use USB functionality. Hence by default the USB

device is disabled, ensuring that applications do not suffer any

memory or other penalties for functionality that is not required.

If the application developer explicitly adds a class support package

such as the USB-ethernet one then this implies that the USB device is

actually needed, and the device will be enabled automatically.

However, if no suitable class package is available and the USB device

will instead be accessed by application code, it is necessary to

enable the USB device manually. Usually the easiest way to do this is

to enable the configuration option

CYGGLO_IO_USB_SLAVE_APPLICATION, and the USB device

driver and related packages will adjust accordingly. Alternatively,

the device driver may provide some configuration options to provide

more fine-grained control.

USB Enumeration Data

Enumeration Data

The USB enumeration data structures

#include <cyg/io/usb/usb.h>

#include <cyg/io/usb/usbs.h>

typedef struct usb_device_descriptor {

    …

} usb_device_descriptor __attribute__((packed));

typedef struct usb_configuration_descriptor {

    …

} usb_configuration_descriptor __attribute__((packed));

typedef struct usb_interface_descriptor {

    …

} usb_interface_descriptor __attribute__((packed));

typedef struct usb_endpoint_descriptor {

    …

} usb_endpoint_descriptor;

typedef struct usbs_enumeration_data {

    usb_device_descriptor               device;

    int                                 total_number_interfaces;

    int                                 total_number_endpoints;

    int                                 total_number_strings;

    const usb_configuration_descriptor* configurations;

    const usb_interface_descriptor*     interfaces;

    const usb_endpoint_descriptor*      endpoints;

    const unsigned char**               strings;

} usbs_enumeration_data;

When a USB host detects that a peripheral has been plugged in or

powered up, one of the first steps is to ask the peripheral to

describe itself by supplying enumeration data. Some of this data

depends on the class of peripheral. Other fields are vendor-specific.

There is also a dependency on the hardware, specifically which

endpoints are available should be used. In general it is not possible

for generic code to provide this information, so it is the

responsibility of application code to provide a suitable

usbs_enumeration_data data structure and

install it in the endpoint 0 data structure during initialization.

This must happen before the USB device is enabled by a call to

usbs_start, for example:

const usbs_enumeration_data usb_enum_data = {

    …

};

int

main(int argc, char** argv)

{

    usbs_sa11x0_ep0.enumeration_data = &usb_enum_data;

    …

    usbs_start(&usbs_sa11x0_ep0);

    …

}

For most applications the enumeration data will be static, although

the usbs_enumeration_data structure can be

filled in at run-time if necessary. Full details of the enumeration

data can be found in the Universal Serial Bus specification obtainable

from the USB Implementers Forum web

site, although the meaning of most fields is fairly obvious.

The various data structures and utility macros are defined in the

header files cyg/io/usb/usb.h

and cyg/io/usb/usbs.h. Note

that the example code below makes use of the gcc labelled element

extension.

The main information about a USB peripheral comes from a single

usb_device_descriptor structure, which is

embedded in the usbs_enumeration_data

structure. A typical example might look like this:

const usbs_enumeration_data usb_enum_data = {

    {

        length:                 USB_DEVICE_DESCRIPTOR_LENGTH,

        type:                   USB_DEVICE_DESCRIPTOR_TYPE,

        usb_spec_lo:            USB_DEVICE_DESCRIPTOR_USB11_LO,

        usb_spec_hi:            USB_DEVICE_DESCRIPTOR_USB11_HI,

        device_class:           USB_DEVICE_DESCRIPTOR_CLASS_VENDOR,

        device_subclass:        USB_DEVICE_DESCRIPTOR_SUBCLASS_VENDOR,

        device_protocol:        USB_DEVICE_DESCRIPTOR_PROTOCOL_VENDOR,

        max_packet_size:        8,

        vendor_lo:              0x42,

        vendor_hi:              0x42,

        product_lo:             0x42,

        product_hi:             0x42,

        device_lo:              0x00,

        device_hi:              0x01,

        manufacturer_str:       1,

        product_str:            2,

        serial_number_str:      0,

        number_configurations:  1

    },

    …

};

The length and type fields are specified by the USB standard. The

usb_spec_lo and

usb_spec_hi fields identify the particular

revision of the standard that the peripheral implements, for example

revision 1.1.

The device class, subclass, and protocol fields are used by generic

host-side USB software to determine which host-side device driver

should be loaded to interact with the peripheral. A number of standard

classes are defined, for example mass-storage devices and

human-interface devices. If a peripheral implements one of the

standard classes then a standard existing host-side device driver may

exist, eliminating the need to write a custom driver. The value

0xFF (VENDOR) is reserved for

peripherals that implement a vendor-specific protocol rather than a

standard one. Such peripherals will require a custom host-side device

driver. The value 0x00

(INTERFACE) is reserved and indicates that the

protocol used by the peripheral is defined at the interface level

rather than for the peripheral as a whole.

The max_package_size field specifies the

maximum length of a control message. There is a lower bound of eight

bytes, and typical hardware will not support anything larger because

control messages are usually small and not performance-critical.

The vendor_lo and

vendor_hi fields specify a vendor id, which

must be obtained from the USB Implementor's Forum. The numbers used in

the code fragment above are examples only and must not be used in real

USB peripherals. The product identifier is determined by the vendor,

and different USB peripherals should use different identifiers. The

device identifier field should indicate a release number in

binary-coded decimal.

The above fields are all numerical in nature. A USB peripheral can

also provide a number of strings as described 

linkend="usbs-enum-strings">below, for example the name of the

vendor can be provided. The various _str

fields act as indices into an array of strings, with index 0

indicating that no string is available.

A typical USB peripheral involves just a single configuration. However

more complicated peripherals can support multiple configurations. Only

one configuration will be active at any one time, and the host will

switch between them as appropriate. If a peripheral does involve

multiple configurations then typically it will be the responsibility

of application code to 

linkend="usbs-control-standard">handle the standard

set-configuration control message.

A USB peripheral involves at least one and possible several different

configurations. The usbs_enumeration_data

structure requires a pointer to an array, possibly of length 1, of

usb_configuration_descriptor structures.

Usually a single structure suffices:

const usb_configuration_descriptor usb_configuration = {

    length:             USB_CONFIGURATION_DESCRIPTOR_LENGTH,

    type:               USB_CONFIGURATION_DESCRIPTOR_TYPE,

    total_length_lo:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_LO(1, 2),

    total_length_hi:    USB_CONFIGURATION_DESCRIPTOR_TOTAL_LENGTH_HI(1, 2),

    number_interfaces:  1,

    configuration_id:   1,

    configuration_str:  0,

    attributes:         USB_CONFIGURATION_DESCRIPTOR_ATTR_REQUIRED |

                        USB_CONFIGURATION_DESCRIPTOR_ATTR_SELF_POWERED,

    max_power:          50

};

const usbs_enumeration_data usb_enum_data = {

    …

    configurations:             &usb_configuration,

    …

};

The values for the length and

type fields are determined by the standard.

The total_length field depends on the

number of interfaces and endpoints used by this configuration, and

convenience macros are provided to calculate this: the first argument

to the macros specify the number of interfaces, the second the number

of endpoints. The number_interfaces field

is self-explanatory. If the peripheral involves multiple

configurations then each one must have a unique id, and this will be

used in the set-configuration control message. The id

0 is reserved, and a set-configuration control

message that uses this id indicates that the peripheral should be

inactive. Configurations can have a string description if required.

The attributes field must have the

REQUIRED bit set; the

SELF_POWERED bit informs the host that the

peripheral has its own power supply and will not draw any power over

the bus, leaving more bus power available to other peripherals; the

REMOTE_WAKEUP bit is used if the peripheral can

interrupt the host when the latter is in power-saving mode. For

peripherals that are not self-powered, the

max_power field specifies the power

requirements in units of 2mA.

A USB configuration involves one or more interfaces, typically

corresponding to different streams of data. For example, one interface

might involve video data while another interface is for audio.

Multiple interfaces in a single configuration will be active at the

same time.

const usb_interface_descriptor usb_interface = {

    length:             USB_INTERFACE_DESCRIPTOR_LENGTH,

    type:               USB_INTERFACE_DESCRIPTOR_TYPE,

    interface_id:       0,

    alternate_setting:  0,

    number_endpoints:   2,

    interface_class:    USB_INTERFACE_DESCRIPTOR_CLASS_VENDOR,

    interface_subclass: USB_INTERFACE_DESCRIPTOR_SUBCLASS_VENDOR,

    interface_protocol: USB_INTERFACE_DESCRIPTOR_PROTOCOL_VENDOR,

    interface_str:      0

};

const usbs_enumeration_data usb_enum_data = {

    …

    total_number_interfaces:    1,

    interfaces:                 &usb_interface,

    …

};

Again, the length and

type fields are specified by the standard.

Each interface within a configuration requires its own id. However, a

given interface may have several alternate settings, in other words

entries in the interfaces array with the same id but different

alternate_setting fields. For example,

there might be one setting which requires a bandwidth of 100K/s and

another setting that only needs 50K/s. The host can use the standard

set-interface control message to choose the most appropriate setting.

The handling of this request is the responsibility of higher-level

code, so the application may have to 

linkend="usbs-control-standard">install its own handler.

The number of endpoints used by an interface is specified in the

number_endpoints field. Exact details of

which endpoints are used is held in a separate array of endpoint

descriptors. The class, subclass and protocol fields are used by

host-side code to determine which host-side device driver should

handle this specific interface. Usually this is determined on a

per-peripheral basis in the

usb_device_descriptor structure, but that can

defer the details to individual interfaces. A per-interface string

is allowed as well.

For USB peripherals involving multiple configurations, the array of

usb_interface_descriptor structures should

first contain all the interfaces for the first configuration, then all

the interfaces for the second configuration, and so on.

The host also needs information about which endpoint should be used

for what. This involves an array of endpoint descriptors:

const usb_endpoint_descriptor usb_endpoints[] = {

    {

        length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,

        type:           USB_ENDPOINT_DESCRIPTOR_TYPE,

        endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT | 1,

        attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,

        max_packet_lo:  64,

        max_packet_hi:  0,

        interval:       0

    },

    {

        length:         USB_ENDPOINT_DESCRIPTOR_LENGTH,

        type:           USB_ENDPOINT_DESCRIPTOR_TYPE,

        endpoint:       USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN | 2,

        attributes:     USB_ENDPOINT_DESCRIPTOR_ATTR_BULK,

        max_packet_lo:  64,

        max_packet_hi:  0,

        interval:       0

    }

};

const usbs_enumeration_data usb_enum_data = {

    …

    total_number_endpoints:     2,

    endpoints:                  usb_endpoints,

    …

};

As usual the values for the length and

type fields are specified by the standard.

The endpoint field gives both the endpoint

number and the direction, so in the above example endpoint 1 is used

for OUT (host to peripheral) transfers and endpoint 2 is used for IN

(peripheral to host) transfers. The

attributes field indicates the USB protocol

that should be used on this endpoint: CONTROL,

ISOCHRONOUS, BULK or

INTERRUPT. The

max_packet field specifies the maximum size

of a single USB packet. For bulk transfers this will typically be 64

bytes. For isochronous transfers this can be up to 1023 bytes. For

interrupt transfers it can be up to 64 bytes, although usually a

smaller value will be used. The interval

field is ignored for control and bulk transfers. For isochronous

transfers it should be set to 1. For interrupt transfers it can be a

value between 1 and 255, and indicates the number of milliseconds

between successive polling operations.

For USB peripherals involving multiple configurations or interfaces

the array of endpoint descriptors should be organized sequentially:

first the endpoints corresponding to the first interface of the first

configuration, then the second interface in that configuration, and so

on; then all the endpoints for all the interfaces in the second

configuration; etc.

The enumeration data can contain a number of strings with additional

information. Unicode encoding is used for the strings, and it is

possible for a peripheral to supply a given string in multiple

languages using the appropriate characters. The first two bytes of

each string give a length and type field. The first string is special;

after the two bytes header it consists of an array of 2-byte language

id codes, indicating the supported languages. The language code

0x0409 corresponds to English (United States).

const unsigned char* usb_strings[] = {

    "\004\003\011\004",

    "\020\003R\000e\000d\000 \000H\000a\000t\000"

};

const usbs_enumeration_data usb_enum_data = {

    …

    total_number_strings:       2,

    strings:                    usb_strings,

    …

};

The default handler for standard control messages assumes that the

peripheral only uses a single language. If this is not the case then

higher-level code will have to handle the standard get-descriptor

control messages when a string descriptor is requested.

The usbs_enumeration_data data structure

collects together all the various descriptors that make up the

enumeration data. It is the responsibility of application code to

supply a suitable data structure and install it in the control

endpoints's enumeration_data field before

the USB device is started.

Starting up a USB Device

usbs_start

Starting up a USB Device

#include <cyg/io/usb/usbs.h>

void usbs_start

usbs_control_endpoint* ep0

Initializing a USB device requires some support from higher-level

code, typically the application, in the form of enumeration data.

Hence it is not possible for the low-level USB driver to activate a

USB device itself. Instead the higher-level code has to take care of

this by invoking usbs_start. This function takes

a pointer to a USB control endpoint data structure. USB device drivers

should provide exactly one such data structure for every USB device,

so the pointer uniquely identifies the device.

const usbs_enumeration_data usb_enum_data = {

    …

};

int

main(int argc, char** argv)

{

    usbs_sa11x0_ep0.enumeration_data = &usb_enum_data;

    …

    usbs_start(&usbs_sa11x0_ep0);

    …

}

The exact behaviour of usbs_start depends on the

USB hardware and the device driver. A typical implementation would

change the USB data pins from tristated to active. If the peripheral

is already plugged into a host then the latter should detect this

change and start interacting with the peripheral, including requesting

the enumeration data. Some of this may happen before

usbs_start returns, but given that multiple

interactions between USB host and peripheral are required it is likely

that the function will return before the peripheral is fully

configured. Control endpoints provide a 

linkend="usbs-control-state">mechanism for informing

higher-level code of USB state changes.

usbs_start will return even if the peripheral is

not currently connected to a host: it will not block until the

connection is established.

usbs_start should only be called once for a given

USB device. There are no defined error conditions. Note that the

function affects the entire USB device and not just the control

endpoint: there is no need to start any data endpoints as well.

Devtab Entries

Devtab Entries

Data endpoint data structure

/dev/usb0c

/dev/usb1r

/dev/usb2w

USB device drivers provide two ways of transferring data between host

and peripheral. The first involves USB-specific functionality such as

linkend="usbs-start-rx">usbs_start_rx_buffer.

This provides non-blocking I/O: a transfer is started, and some time

later the device driver will call a supplied completion function. The

second uses the conventional I/O model: there are entries in the

device table corresponding to the various endpoints. Standard calls

such as open can then be used to get a suitable

handle. Actual I/O happens via blocking read and

write calls. In practice the blocking operations

are simply implemented using the underlying non-blocking

functionality.

Each endpoint will have its own devtab entry. The exact names are

controlled by the device driver package, but typically the root will

be /dev/usb. This is followed by one or more

decimal digits giving the endpoint number, followed by

c for a control endpoint, r for

a receive endpoint (host to peripheral), and w for

a transmit endpoint (peripheral to host). If the target hardware

involves more than one USB device then different roots should be used,

for example /dev/usb0c and

/dev/usb1_0c. This may require explicit

manipulation of device driver configuration options by the application

developer.

At present the devtab entry for a control endpoint does not support

any I/O operations.

cyg_io_write and similar functions in

higher-level packages can be used to perform a transfer from

peripheral to host. Successive write operations will not be coalesced.

For example, when doing a 1000 byte write to an endpoint that uses the

bulk transfer protocol this will involve 15 full-size 64-byte packets

and a terminating 40-byte packet. USB device drivers are not expected

to do any locking, and if higher-level code performs multiple

concurrent write operations on a single endpoint then the resulting

behaviour is undefined.

A USB write operation will never transfer less

data than specified. It is the responsibility of higher-level code to

ensure that the amount of data being transferred is acceptable to the

host-side code. Usually this will be defined by a higher-level

protocol. If an attempt is made to transfer more data than the host

expects then the resulting behaviour is undefined.

There are two likely error conditions. EPIPE

indicates that the connection between host and target has been broken.

EAGAIN indicates that the endpoint has been

stalled, either at the request of the host or by other activity

inside the peripheral.

cyg_io_read and similar functions in higher-level

packages can be used to perform a transfer from host to peripheral.

This should be a complete transfer: higher-level protocols should

define an upper bound on the amount of data being transferred, and the

read operation should involve at least this

amount of data. The return value will indicate the actual transfer

size, which may be less than requested.

Some device drivers may support partial reads, but USB device drivers

are not expected to perform any buffering because that involves both

memory and code overheads. One technique that may work for bulk

transfers is to exploit the fact that such transfers happen in 64-byte

packets. It is possible to read an initial 64

bytes, corresponding to the first packet in the transfer. These 64

bytes can then be examined to determine the total transfer size, and