How to use USB driver

*****************************************************************
1. Introducation
*****************************************************************
ADSP21535 has one USB Device Controller (UDC) which supports four
types of USB transfers (Control, Bulk, Interrupt, ISO).
The USB driver makes it possible for the applications in user
mode to access the UDC. The USB driver processes USB enumeration
automatically and provides the interface for USB to transfer
information to the application.
With the USB driver, the user application will be able to
communicate with USB Host (PC) via three types of transfer:
Bulk, Interrupt, ISO. The Control transfer will be processed by
USB driver internally, no related interface will be visible to
user application.
*****************************************************************
2. System interface
*****************************************************************
The USB driver register itself is a standard character device
driver.
The Major number of USB driver is 221. The device name is /dev/adi_usb
So the standard file operations can be used to access the USB
driver:
1) open()
open("/dev/adi_usb",...) will return the fd of USB driver
The USB driver can be accessed by multi-process at the same time.
2) close()
3) read()
USB driver does *NOT* support this operation
4) write()
USB driver does *NOT* support this operation
5) ioctl()
Following ioctl commands are supported
CMD_USB_BULK_INTR_READ:
Read from USB BULK pipe.
The argument points to structure of 'usb_bulk_intr_ioctl' show as below.

typedef struct
{
unsigned char * buf;
int len;
int flag;
} usb_bulk_intr_ioctl;
The 'buf' is the buffer to receive data.
The 'len' is the count of data to receive.
The 'flag' must be 1 means read from BULK pipe
The number of received data will be returned
CMD_USB_BULK_INTR_WRITE:
Write to USB BULK/INTERRUPT pipe.
The argument points to structure of usb_bulk_intr_ioctl.
The 'buf' points to the buffer to send.
The 'len' is the count of data to send.
The 'flag' is 1 means write to BULK pipe
The 'flag' is 2 means write to INTERRUPT pipe
The number of data sent out will be returned
CMD_USB_ISO_READ:
Read from USB ISO pipe.
The argument points to structure of 'usb_iso_data' show as below.
typedef struct
{
unsigned short len;
char * data_buf;
} usb_iso_frame;

typedef struct
{
unsigned long frame_num;
usb_iso_frame frame[1];
} usb_iso_data;
The 'frame_num" is the number of frames to receive.
The 'frame' points to each ISO frames.
The 'frame_num' will be set with the number of frames actually received
when return. The 'len' of each ISO frame will also be set to the length
of the frame data. The data of each ISO frame will be copied to buffer
pointed by 'data_buf' of the frame.
CMD_USB_ISO_WRITE:
Write USB ISO pipe.
The argument points to structure of 'usb_iso_data'.
The 'frame_num" is the number of frames to be transmitted.
The 'frame' points to each ISO frames.
The 'frame_num' shall be set with the number of frames to send.
The 'len' of each ISO frame shall also be set to the length
of the frame data. The 'data_buf' of each ISO frame shall point
to the data buffer of the frame.
The 'frame_num' will be set with the number of frames actually transmitted
when return.
NOTE:
A set of user space APIs are available to simplify programming.


*****************************************************************
3. User API for USB driver
*****************************************************************
1) usb_pipe_open()
Syntax:
usb_pipe_handle usb_pipe_open (int pipe_type)
Description:
Open one of the pipes of the UDC. One pipe consists of two endpoints
that have the same type (Bulk, Interrupt or Isochronous)
The specific pipe will NOT be accessible until it has been opened.
NOTE:
When Interrupt pipe type is specified, the returned pipe handle can NOT
be used to call usb_pipe_read(). Since only USB Interrupt IN
(data to USB Host) is supported by USB kernel driver and USB Host.
Parameters:
pipe_type The type of the pipe to be opened
1: Bulk pipe
2: Interrupt pipe
3: Isochronous pipe
Return:
The handle of the opened endpoint will be returned if succeed,
otherwise negative error number will returned.

2) usb_pipe_close()
Syntax:
void usb_pipe_close (usb_pipe_handle pipe)
Description:
Close the pipe that had been opened
Parameters:
pipe The handle returned by usb_pipe_open()

3) usb_pipe_write()
Syntax:
int usb_pipe_write (usb_pipe_handle pipe, char * buf, int len)
Description:
Send data to USB Host through the specific pipe. The data will be stored
into internal buffer first, and will be written into the FIFO of the
specific endpoint of UDC whenever the room of FIFO is available.
Eventually, the data will be sent to USB Host.
Parameters:
pipe The handle returned by usb_pipe_open()
buf The pointer of the buffer for data to be sent
len The length of data.

Return:
The bytes of the data sent out will be returned if success, otherwise
negative error number will be returned
4) usb_pipe_read()
Syntax:
int usb_pipe_read (usb_pipe_handle pipe, char * buf, int len)
Description:
Get data sent by USB Host via specific USB endpoint.
Whenever the data from USB Host are received, they will be stored
into internal buffer first. Then the data will be returned to the caller
whenever this function is called.
Parameters:
pipe The handle returned by usb_pipe_open()
buf The pointer of the buffer for data to be sent
len The length of data
Return:
The bytes of the data sent out will be returned if success, otherwise
negative error number will be returned

5) usb_pipe_iso_write()
Syntax:
int usb_pipe_iso_write (usb_pipe_handle pipe, usb_iso_data * iso_data)
Description:
Send Isochronous data to USB Host.
Parameters:
pipe The handle returned by usb_pipe_open()
iso_data ISO frames descriptor
Return:
The bytes of the data sent out will be returned if success, otherwise
negative error number will be returned
6) usb_pipe_iso_read()
Syntax:
int usb_pipe_iso_read (usb_pipe_handle pipe, usb_iso_data * iso_data)
Description:
Get Isochronous data sent by USB Host.
Parameters:
pipe The handle returned by usb_pipe_open()
iso_data ISO frames descriptor
Return:
The bytes of the data sent out will be returned if success, otherwise

negative error number will be returned
*****************************************************************
4. Usage of USB driver
*****************************************************************
1) Read/Write from/to USB BULK/INTERRUPT pipe
a) Call usb_pipe_open() to open pipe
b) Call usb_pipe_read()/write() to read/write
c) Call usb_pipe_close() to close pipe
2) Read from USB ISO pipe
a) Call usb_pipe_open() to open ISO pipe
b) Allocate 'usb_iso_data' structure
iso_data = (usb_iso_data *) malloc(sizeof(usb_iso_data) +
(frame_num - 1) * sizeof(usb_iso_frame));
c) Set the 'frame_num'of usb_iso_data structure with number frames
you want to read.
iso_data->frame_num = frame_num;
d) Setup buffer for each frame
for (i = 0; i < frame_num; i++)
iso_data->frame[i].data_buf = malloc(...);

NOTE: Sufficient memory shall be allocated for each frame.
Buffer of each frame shall be able to hold at least 8-byte data.
e) Call usb_pipe_iso_read() to read ISO frames
f) Check 'iso_data->frame_num' to determine the number received frames.
g) Check each frame's length and data
for (i = 0; i < iso_data->frame_num; i++)
{
len = iso_data->frame[i].len;
memcpy(buf, iso_data->frame[i].data_buf, len);
......
}
h) Call usb_pipe_close() to close the ISO pipe
3) Write to USB ISO pipe
a) Call usb_pipe_open() to open ISO pipe
b) Allocate 'usb_iso_data' structure
iso_data = (usb_iso_data *) malloc(sizeof(usb_iso_data) +
(frame_num - 1) * sizeof(usb_iso_frame));
c) Set the 'frame_num'of usb_iso_data structure with number frames
you want to write.

iso_data->frame_num = frame_num;
d) Setup buffer and length for each frame
for(i=0;i<frame_num; i++)
{
iso_data->frame[i].data_buf = malloc(len);
memcpy(iso_data->frame[i].data_buf, ...);
iso_dat->frame[i].len = len;
}
NOTE: Lenght of each frame shall NOT exceed 8-byte data.
e) Call usb_pipe_iso_write() to write ISO frames
f) Check 'iso_data->frame_num' to determine the number of frames transmitted.
g) Call usb_pipe_close() to close the ISO pipe
For detail information for usage for USB drive, pls refer to usb_test.c
*****************************************************************
5. NOTE
*****************************************************************
1) Read from Interrupt pipe is NOT supported.
2) The length of each ISO frames sent to USB Host must be same as
the maximum packet size of ISO IN endpoint. It is set to 8
bytes now.
3) Don't try to write more than 63 bytes to the Bulk OUT endpoint
from USB Host(PC) each time. The size of Bulk OUT DMA buffer
is only 63-bytes. Sending 64-byte packet will be NAKed
forever!
The root cause of this issue is a UDC hardware bug. The bug
will prevent us from getting a correct data length for the Bulk
OUT transfer unless we make the size of DMA buffer less than
max packet size (64-bytes).