Subversion Repositories openrisc_me

SA11X0 USB Device Driver

SA11X0 USB Device Driver

SA11X0 USB Support

SA11X0 USB Support

Device driver for the on-chip SA11X0 USB device

Device driver for the on-chip SA11X0 USB device

The Intel StrongARM SA11x0 family of processors is supplied with an

The Intel StrongARM SA11x0 family of processors is supplied with an

on-chip USB slave device, the UDC (USB Device Controller). This

on-chip USB slave device, the UDC (USB Device Controller). This

supports three endpoints. Endpoint 0 can only be used for control

supports three endpoints. Endpoint 0 can only be used for control

messages. Endpoint 1 can only be used for bulk transfers from host to

messages. Endpoint 1 can only be used for bulk transfers from host to

peripheral. Endpoint 2 can only be used for bulk transfers from

peripheral. Endpoint 2 can only be used for bulk transfers from

peripheral to host. Isochronous and interrupt transfers are not

peripheral to host. Isochronous and interrupt transfers are not

supported.

supported.

Different revisions of the SA11x0 silicon have had various problems

Different revisions of the SA11x0 silicon have had various problems

with the USB support. The device driver has been tested primarily

with the USB support. The device driver has been tested primarily

against stepping B4 of the SA1110 processor, and may not function as

against stepping B4 of the SA1110 processor, and may not function as

expected with other revisions. Application developers should obtain

expected with other revisions. Application developers should obtain

the manufacturer's current errata sheets and specification updates.

the manufacturer's current errata sheets and specification updates.

The B4 stepping still has a number of problems, but the device driver

The B4 stepping still has a number of problems, but the device driver

can work around these. However there is a penalty in terms of extra

can work around these. However there is a penalty in terms of extra

code, extra cpu cycles, and increased dispatch latency because extra

code, extra cpu cycles, and increased dispatch latency because extra

processing is needed at DSR level. Interrupt latency should not be

processing is needed at DSR level. Interrupt latency should not be

affected.

affected.

There is one specific problem inherent in the UDC design of which

There is one specific problem inherent in the UDC design of which

application developers should be aware: the hardware cannot fully

application developers should be aware: the hardware cannot fully

implement the USB standard for bulk transfers. A bulk transfer

implement the USB standard for bulk transfers. A bulk transfer

typically consists of some number of full-size 64-byte packets and is

typically consists of some number of full-size 64-byte packets and is

terminated by a packet less than the full size. If the amount of data

terminated by a packet less than the full size. If the amount of data

transferred is an exact multiple of 64 bytes then this requires a

transferred is an exact multiple of 64 bytes then this requires a

terminating packet of 0 bytes of data (plus header and checksum). The

terminating packet of 0 bytes of data (plus header and checksum). The

SA11x0 USB hardware does not allow a 0-byte packet to be transmitted,

SA11x0 USB hardware does not allow a 0-byte packet to be transmitted,

so the device driver is forced to substitute a 1-byte packet and the

so the device driver is forced to substitute a 1-byte packet and the

host receives more data than expected. Protocol support is needed so

host receives more data than expected. Protocol support is needed so

that the appropriate host-side device driver can allow buffer space

that the appropriate host-side device driver can allow buffer space

for the extra byte, detect when it gets sent, and discard it.

for the extra byte, detect when it gets sent, and discard it.

Consequently certain standard USB class protocols cannot be

Consequently certain standard USB class protocols cannot be

implemented using the SA11x0, and therefore custom host-side device

implemented using the SA11x0, and therefore custom host-side device

drivers will generally have to be provided, rather than re-using

drivers will generally have to be provided, rather than re-using

existing ones that understand the standard protocol.

existing ones that understand the standard protocol.

The SA11x0 USB device driver can provide up to three data structures

The SA11x0 USB device driver can provide up to three data structures

corresponding to the three endpoints: a

corresponding to the three endpoints: a

usbs_control_endpoint structure

usbs_control_endpoint structure

usbs_sa11x0_ep0; a

usbs_sa11x0_ep0; a

usbs_rx_endpoint

usbs_rx_endpoint

usbs_sa11x0_ep1; and a

usbs_sa11x0_ep1; and a

usbs_tx_endpoint

usbs_tx_endpoint

usbs_sa11x0_ep2. The header file

usbs_sa11x0_ep2. The header file

cyg/io/usb/usbs_sa11x0.h

cyg/io/usb/usbs_sa11x0.h

provides declarations for these.

provides declarations for these.

Not all applications will require support for all the endpoints. For

Not all applications will require support for all the endpoints. For

example, if the intended use of the UDC only involves peripheral to

example, if the intended use of the UDC only involves peripheral to

host transfers then usbs_sa11x0_ep1 is redundant.

host transfers then usbs_sa11x0_ep1 is redundant.

The device driver provides configuration options to control the

The device driver provides configuration options to control the

presence of each endpoint:

presence of each endpoint:

Endpoint 0 is controlled by

Endpoint 0 is controlled by

CYGFUN_DEVS_USB_SA11X0_EP0. This defaults to

CYGFUN_DEVS_USB_SA11X0_EP0. This defaults to

enabled if there are any higher-level packages that require USB

enabled if there are any higher-level packages that require USB

hardware or if the global preference

hardware or if the global preference

CYGGLO_IO_USB_SLAVE_APPLICATION is enabled,

CYGGLO_IO_USB_SLAVE_APPLICATION is enabled,

otherwise it is disabled. Usually this has the desired effect. It may

otherwise it is disabled. Usually this has the desired effect. It may

be necessary to override this in special circumstances, for example if

be necessary to override this in special circumstances, for example if

the target board uses an external USB chip in preference to the UDC

the target board uses an external USB chip in preference to the UDC

and it is that external chip's device driver that should be used

and it is that external chip's device driver that should be used

rather than the on-chip UDC. It is not possible to disable endpoint 0

rather than the on-chip UDC. It is not possible to disable endpoint 0

and at the same time enable one or both of the other endpoints, since

and at the same time enable one or both of the other endpoints, since

a USB device is only usable if it can process the standard control

a USB device is only usable if it can process the standard control

messages.

messages.

Endpoint 1 is controlled by

Endpoint 1 is controlled by

CYGPKG_DEVS_USB_SA11X0_EP1. By default it is

CYGPKG_DEVS_USB_SA11X0_EP1. By default it is

enabled whenever endpoint 0 is enabled, but it can be disabled

enabled whenever endpoint 0 is enabled, but it can be disabled

manually when not required.

manually when not required.

Similarly endpoint 2 is controlled by

Similarly endpoint 2 is controlled by

CYGPKG_DEVS_USB_SA11X0_EP2. This is also enabled by

CYGPKG_DEVS_USB_SA11X0_EP2. This is also enabled by

default whenever endpoint 0 is enabled, but it can be disabled manually.

default whenever endpoint 0 is enabled, but it can be disabled manually.

The SA11X0 USB device driver implements the interface specified by the

The SA11X0 USB device driver implements the interface specified by the

common eCos USB Slave Support package. The documentation for that

common eCos USB Slave Support package. The documentation for that

package should be consulted for further details. There is only one

package should be consulted for further details. There is only one

major deviation: when there is a peripheral to host transfer on

major deviation: when there is a peripheral to host transfer on

endpoint 2 which is an exact multiple of the bulk transfer packet size

endpoint 2 which is an exact multiple of the bulk transfer packet size

(usually 64 bytes) the device driver has to pad the transfer with one

(usually 64 bytes) the device driver has to pad the transfer with one

extra byte. This is because of a hardware limitation: the UDC is

extra byte. This is because of a hardware limitation: the UDC is

incapable of transmitting 0-byte packets as required by the USB

incapable of transmitting 0-byte packets as required by the USB

specification. Higher-level code, including the host-side device

specification. Higher-level code, including the host-side device

driver, needs to be aware of this and adapt accordingly.

driver, needs to be aware of this and adapt accordingly.

The device driver assumes a bulk packet size of 64 bytes, so this

The device driver assumes a bulk packet size of 64 bytes, so this

value should be used in the endpoint descriptors in the enumeration

value should be used in the endpoint descriptors in the enumeration

data provided by application code. There is experimental code

data provided by application code. There is experimental code

for running with DMA disabled,

for running with DMA disabled,

in which case the packet size will be 16 bytes rather than 64.

in which case the packet size will be 16 bytes rather than 64.

In addition to the endpoint data structures the SA11X0 USB device

In addition to the endpoint data structures the SA11X0 USB device

driver can also provide devtab entries for each endpoint. This allows

driver can also provide devtab entries for each endpoint. This allows

higher-level code to use traditional I/O operations such as

higher-level code to use traditional I/O operations such as

open/read/write

open/read/write

rather than the USB-specific non-blocking functions like

rather than the USB-specific non-blocking functions like

usbs_start_rx_buffer. These devtab entries are

usbs_start_rx_buffer. These devtab entries are

optional since they are not always required. The relevant

optional since they are not always required. The relevant

configuration options are

configuration options are

CYGVAR_DEVS_USB_SA11X0_EP0_DEVTAB_ENTRY,

CYGVAR_DEVS_USB_SA11X0_EP0_DEVTAB_ENTRY,

CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY and

CYGVAR_DEVS_USB_SA11X0_EP1_DEVTAB_ENTRY and

CYGVAR_DEVS_USB_SA11X0_EP2_DEVTAB_ENTRY. By default

CYGVAR_DEVS_USB_SA11X0_EP2_DEVTAB_ENTRY. By default

these devtab entries are provided if the global preference

these devtab entries are provided if the global preference

CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES is enabled,

CYGGLO_USB_SLAVE_PROVIDE_DEVTAB_ENTRIES is enabled,

which is usually the case. Obviously a devtab entry for a given

which is usually the case. Obviously a devtab entry for a given

endpoint will only be provided if the underlying endpoint is enabled.

endpoint will only be provided if the underlying endpoint is enabled.

For example, there will not be a devtab entry for endpoint 1 if

For example, there will not be a devtab entry for endpoint 1 if

CYGPKG_DEVS_USB_SA11X0_EP1 is disabled.

CYGPKG_DEVS_USB_SA11X0_EP1 is disabled.

The names for the three devtab entries are determined by using a

The names for the three devtab entries are determined by using a

configurable base name and appending 0c,

configurable base name and appending 0c,

1r or 2w. The base name is

1r or 2w. The base name is

determined by the configuration option

determined by the configuration option

CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME and has a

CYGDAT_DEVS_USB_SA11X0_DEVTAB_BASENAME and has a

default value of /dev/usbs, so the devtab entry for

default value of /dev/usbs, so the devtab entry for

endpoint 1 would default to /dev/usbs1r. If the

endpoint 1 would default to /dev/usbs1r. If the

target hardware involves multiple USB devices then application

target hardware involves multiple USB devices then application

developers may have to change the base name to prevent a name clash.

developers may have to change the base name to prevent a name clash.

The SA11X0 UDC provides only limited fifos for bulk transfers on

The SA11X0 UDC provides only limited fifos for bulk transfers on

endpoints 1 and 2; smaller than the normal 64-byte bulk packet size.

endpoints 1 and 2; smaller than the normal 64-byte bulk packet size.

Therefore a typical transfer requires the use of DMA engines. The

Therefore a typical transfer requires the use of DMA engines. The

SA11x0 provides six DMA engines that can be used for this, and the

SA11x0 provides six DMA engines that can be used for this, and the

endpoints require one each (assuming both endpoints are enabled). At

endpoints require one each (assuming both endpoints are enabled). At

the time of writing there is no arbitration mechanism to control

the time of writing there is no arbitration mechanism to control

access to the DMA engines. By default the device driver will use

access to the DMA engines. By default the device driver will use

DMA engine 4 for endpoint 1 and DMA engine 5 for endpoint 2, and it

DMA engine 4 for endpoint 1 and DMA engine 5 for endpoint 2, and it

assumes that no other code uses these particular engines.

assumes that no other code uses these particular engines.

The exact DMA engines that will be used are determined by the

The exact DMA engines that will be used are determined by the

configuration options

configuration options

CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL and

CYGNUM_DEVS_USB_SA11X0_EP1_DMA_CHANNEL and

CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL. These

CYGNUM_DEVS_USB_SA11X0_EP2_DMA_CHANNEL. These

options have the booldata flavor, allowing the use of DMA to be

options have the booldata flavor, allowing the use of DMA to be

disabled completely in addition to controlling which DMA engines are

disabled completely in addition to controlling which DMA engines are

used. If DMA is disabled then the device driver will attempt to

used. If DMA is disabled then the device driver will attempt to

work purely using the fifos, and the packet size will be limited to

work purely using the fifos, and the packet size will be limited to

only 16 bytes. This limit should be reflected in the appropriate

only 16 bytes. This limit should be reflected in the appropriate

endpoint descriptors in the enumeration data. The code for driving the

endpoint descriptors in the enumeration data. The code for driving the

endpoints without DMA should be considered experimental. At best it

endpoints without DMA should be considered experimental. At best it

will be suitable only for applications where the amount of data

will be suitable only for applications where the amount of data

transferred is relatively small, because four times as many interrupts

transferred is relatively small, because four times as many interrupts

will be raised and performance will suffer accordingly.

will be raised and performance will suffer accordingly.