There are the following functions to handle USB transfer requests at client application side:

Endpoints

A device consists of one or more endpoints. This may vary depending on the configuration of the device. There are up to 16 Endpoints per device allowed at USB Specification 1.1. An endpoint can be used for input or output or both. If only used for input or output this means that you can address up to 31 endpoints in conjunction with the direction and because an endpoint is belonging to a pipe up to 31 pipes per device (31 not 32 because endpoint 0 is used for both directions see below)! The endpoints are numbered from 0 to 15. Endpoint 0 can be used for input and for output and has a special behaviour which is determined by the USB concept. In fact it is used for configuration of the device. The device specification determines the formats of the data that must be send to or can be recieved from the other endpoints.

Pipes

A pipe is a data channel on that request communication can be done between a program and an endpoint of a device. It is something similar like a file handle. A pipe can be established to an endpoint using a given direction. A pipe which is established to the endpoint 0 is called the default pipe and is bidirectional. You can establish up to two pipes to an endpoint. One for input and one for output. You can also establich one bidirectional pipe to an endpoint. Control transfers are the only valid transfer type for bidirectional pipes and can only be used on bidirectional pipes.

A pipe must be opened by a program. It then belongs to that program. No other pipe can be established to the same endpoint into the same direction. This means that transfer to or from an endpoint in a given direction can be done by exactly one program. At the end the program has to close the pipe. Pipes are blocked automatically if device has been removed. A pipe is halted if an USB error has occured. A halted pipe can be set to normal state by closing and reopening or by clearing the pipe.

There is a problem of concept inside USB-Specification. Normally a pipe shall belong to only one program. The default pipe must be used by a configuration program but it must also shared among various programs to recover pipes from transmission errors or for handshaking. USB-Specification says that the default pipe shall be claimed by the USB configuration process and a set of function must be provided by an USB interface which allows other program to sent their own reqeusts to the default pipe. In fact that is nothing other that the default pipe can be shared among several applications. So USB-Module allows a pipe opening in multi access mode. See USB_OpenPipe for more details. Sharing a resource between several programs always comes with the danger that one program is doing an action which damages/influences the activites of the others. If such an action is taking place the program which wants to do so must broadcast an according service call to inform the other programs. If this call will be claimed the calling program must not exectue its operation.

Pipe Constants

Transfer types

Control Transfer

Control transfer supports sending and recieving. At first a special block (Setup) will be sent which determines the direction of the following data. Note that this data transfer is similar to bulk transfer and may be split up into several transactions. There is an acknowledgement whether the data has been transferred correctly. If data is recieved by the host the host will not know the size of the data in every case. Therefore USB Module allows you to start subsequent Bulk transfers using the direction of the last Control transfer on pipes of Control transfer type! There is also a flag which allows a program to generate a Status Stage Transfer. This is zero length data transfer at the end of the Bulk data transfer in the opposite direction as the Bulk transfer was. The Status Stage is used for acknowledgement that a Control transfer has been processed correctly (this is a difference to only recieve the data correctly!). If there are no subsequent Bulk transfers you can let the USB module generate such a Status Stage automatically by setting the flag. Control transfers are done if there is free capacity on the USB but before Bulk transfer. Note that Control transfers can be done on devices with low or normal speed. The frame repeat number must be set to 0.

Note that there will be problems at subsequent Bulk transfers if a control pipe is shared among several applications because subsequent transfers from several sides will damage each other. Therefore you should do all operations (Setup, Data and Status Stage) in one request at shared pipes and you should not use subsequent Bulk transfers. May be that later versions of the USB module will queue the Setup Transfers and exactly one application which Setup block has been acknowldeged is allowed to do further transfer until a Status Stage is generated but this concept is not supported in the moment. At later versions of the USB module there will be also the possibility to let the USB-Module examine the Setup block which determines the action to do for the device because it may influence the behaviour of the device on the USB. If an USB standard block has been generated which is recognized by the USB module that it affects its internal data structures it will automatically update this structures. But that is also not supported by the actual version of the USB-Module so you must keep care by changing the according states/structures by your program.

Isochronous Transfer

Isochronous transfer has the highest priority at USB. If requests on it are pending it can be done every USB frame. There is no acknowledgement whether the data has been transferred correctly. An isochronous transfer cannot been split up into several transaction, so the size of the data buffer must fit exactly to the data payload size. Note that Isochronous transfers can be only done on devices with normal speed. The frame repeat number must be set to 1.

Bulk Transfer

Bulk transfers have the lowest priority at USB. It is done if free capacity at the USB is available. There is an acknowledgement whether the data has been transferred correctly. The transfer can be split up into several transactions which can be processed over a lot of frames. Note that Bulk transfers can be only done on devices with normal speed. The frame repeat number must be set to 0.

Interrupt Transfer

Interrupt Transfers are similar to Bulk transfers but they have a priority immediately beyond Isochronous Transfer at USB. An interval of frames must be given after which the next transfer can be done. In detail this is meaning that if a new request has been set generated by the host software the transfer will be first done after USB frame has reached a value which is less or equal than the value calculated from the last frame number where an interrupt transfer was done at this endpoint by adding the interval of frames. Note that it can happen that a long time distance is passing between two requests. This may be based on a device which is repsonding with NAKs if there is no data. Therefore the last frame number can't be always taken as the base of calculation. USB module must check whether the last frame number is inside an interval between actual frame number minus repeat interval size and actual frame number. This may lead to a gap in worst case of one repeating interval but this will only happen at slow devices which won't respond regulary and this can be tolerated. There is an acknowledgement whether the data has been transferred correctly. The transfer can be split up into several transactions which can be processed over a lot of frames. If the frame number has been reached where an interrupt request can be processed it should be sorted into the queue of waiting interrupt requests by the frame number of next interval start of this interrupt pipe. Note that Interrupt transfers can be done on devices with low or normal speed.

Requests

Requests are generated if a program wants to perform a data transfer on a pipe. The data to transfer is hold inside data buffers. Requests are splitted up into transactions. These are queued per endpoint. The program which generates the request can decide what should happen until the transfer has been finished. It can wait or it can continue. If it is continuing it can choose whether it wants to check the state of the transfers regulary itself or whether it wants to be notified by SWI, WIMP message or APCS, that the request has been finished.

Requests constants