Home

MCF5272 USB SW Developer Manual. Stand

1. in print in If TRUE print out information of IN transfers out print in If TRUE print out information of OUT transfers Returns No value returns Description This function prints out to terminal the contents of arrays that hold information of test transfer completion Code example print transfer status TRUE TRUE M Appendix 2 Audio Application 10 19 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 8 process data Call s void process data uint8 dpb Arguments Table 10 3 process data arguments dpb inout Pointer to the data to be processed Returns No value returns Description This function reduces amplitude of each sample in the buffer by multiplying it by volume value If not all expected data was received function clears whole buffer or end of buffer Code example process data data processing buffer M Appendix 2 Audio Application 10 20 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 9 test case1 handler Call s void test casel handler void Arguments No arguments Returns No value returns Description This function performs 5 tests OUT transfers each takes 5 frames places received data to SRAM prints out the received data and transfers statu
2. Description This function halts a non zero endpoint It causes the endpoint to return STALL handshake when polled by either an IN or OUT token by the USB Host controller Returns No value returns Code example usb ep stall 1 M USB Device Driver Function Specification 7 7 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 8 usb ep wait Call s uint32 usb ep wait uint32 epnum Arguments Table 7 7 usb ep wait arguments Number of tested endpoint for being busy Description This function does not return control while endpoint is busy the function waits for the endpoint The endpoint is still busy while a non zero value is assigned to the ep epnum buffer start field Returns Table 7 8 usb ep wait returned values USB DEVICE RESET USB EP IS FREE Endpoint is free Code example uintl6 status usb ep wait INTERRUPT usb tx data INTERRUPT uint8 amp status 2 M USB Device Driver Function Specification 7 8 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 9 usb fifo init Call s void usb fifo init void Arguments No arguments Description This function initializes the FIFO for current configuration It calculates the start address and the length of FIFO buffer for each en
3. Finish transfer Restore saved IMR Is there EOT interrupt yes Finish transfer Fig 3 3 Algorithm of usb in service function Control Bulk Interrupt Data Transfer 3 8 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 3 1 3 Completion of Data IN Transfer The Driver sends data to the Host in largest size packets possible The rest of data are sent in one short packet The Driver handles the end of transfer in different ways depending upon the exact situation The Table 3 1 summarizes the conditions and the Device s actions according those conditions Table 3 1 The variants of transfer completion N Condition 1 The length of transferred buffer was not a multiple to the maximum size of packet Driver s actions Driver clears EPNCTL IN DONE bit to send one short length data packet EOT interrupt will occur Driver clears the ep epnum buffer Structure and sets up EPNCTL IN DONE bit in EOT interrupt handler Host received all the data it 2 expected The length of transferred buffer was a multiple to the maximum size of packet Host did not receive all the data it 3 expected The length of transferred buffer was a multiple of the maximum size of packet Clears the ep epnum buffer Structure after the last packet was successfully sent to Host
4. To distinguish between spurious and normal EOP the endpoint data present register must be tested In the case of a spurious interrupt the register contains non zero value the next packet is already written to the FIFO by usb_isochronous_transfer_service and is otherwise cleared M Isochronous Data Transfer 4 5 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Case 2 Next to last packet was not sent to the Host packet 4 ep epnum buffer position iso ep epnum packet position Packet 1 Packet 2 Packet 3 Packet 4 Packet 5 SOF1 EOPI SOF2 EOP2 SOF3 EOP3 J SOF4 SOFS EOPS Lol gno cuu c c _ When SOFS interrupt occurs usb isochronous transfer service determines that packet 4 was not sent to the Host EOP4 interrupt did not occur It removes all data from the FIFO buffer there is data from packet 4 there only In fact packet 5 must now be placed into the FIFO but the token for the fifth packet is missed by this time by the Device which is the situation like that one described in section 4 1 remark 2 Thus the transfer of this buffer must be completed The Function assigns a DEFAULT value to the internal state field This means that usb tx data must start transferring the next buffer from the first packet iso ep epnum state DEFAULT usb isochronous transfer service completes the current transfer usb ep tx
5. USB CONFIG DESC pCfgDesc Get pointer to active Configuration descriptor pCfgDesc USB CONFIG DESC usb get desc new config 1 1 1 M USB Device Driver Function Specification 7 10 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 11 usb get frame number Implemented in CBI amp Isochronous Driver only Call s uint16 usb get frame number void Arguments No arguments Description and returned value Function returns the contents of FNR Frame Number Register This value is in the range 0 to 2047 Code example uinti6 start frame number start frame number usb get frame number 70 if start frame number 2047 start frame number 2048 M USB Device Driver Function Specification 7 11 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 12 usb init Call s void usb init DESC INFO descriptor info Arguments Table 7 10 usb init arguments descriptor info in Pointer to the structure that contains pointers to Device descriptor and string descriptors and size of Device descriptor Description This function initialize the USB Device Driver It stores initial values to global variables initializes interrupts loads descriptors to configuration memory and initializes the FIFO buf
6. In this case the Device sends zero length packet to the Host to indicate the end of transfer Driver clears EPNCTL IN DONE bit EOT interrupt will occur Driver clears the ep epnum buffer structure and sets up EPNCTL IN DONE bit in EOT interrupt handler If the length of a transferred buffer was less than or equal to the size of the FIFO buffer for the used endpoint the usb tx data function completes the transfer If the last packet is maximum size it will be sent by the USB module automatically If the last packet is short IN DONE bit must be cleared and as a result the USB module will send to the bus all the data it has and will not wait to form a maximum size packet In both cases the usb in service handler will be called and will complete the transfer if i ep epnum buffer length This is all of the data to be sent if i ep epnum packet size 0 Send short packet Clear the IN DONE bit MCF5272 WR USB EPCTL imm epnum MCF5272 RD USB EPCTL imm epnum amp MCF5272 USB EPNCTL IN DONE M Control Bulk Interrupt Data Transfer 3 9 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc usb in service finishes the transfer in two different places in the handler of EOP and in the handler of the EOT event a If all the data is placed in the FIFO buffer and the amount of tha
7. passing a pointer to DEVICE COMMAND structure as a parameter The definition of this structure is shown below Structure for Request typedef struct uint8 bmRequestType uint8 bRequest uint16 wValue uinti6 wIndex uintl6 wLength REQUEST M Vendor Request Handling 5 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Structure for Command Buffer for Client typedef struct uint8 cbuffer Pointer to command block buffer REQUEST request Request from Host DEVICE COMMAND REQUEST Structure contains request parameters the cbuffer field points to the start of the command block The length of the command block is equal to the request wLength field cbuffer field is used only if a request has a data stage and the direction of data transfer is from Host to Device Otherwise cbuffer is not initialized A more detailed description of request handling is given in following subsections 5 2 Data OUT request handling The direction of data transfer is determined by the bmRequest Type D7 parameter 1 If that bit is cleared bmRequest Type 128 and there is a data stage in a request it is a case of Data OUT command if bmRequestType lt 128 amp amp wLength gt 0 Allocate memory for a new command There is a data stage in this request and direction of data transfer is from Host to Devi
8. sends a string to the Host simultaneously with executing the main task data processing and transferring in both directions However the main taskx function knows nothing about this no extra code is written in the main task function to recognize a request for a string descriptor Another case is when the execution of some tasks may take a long time The time to receive a reply with status in the status stage of the command transfer is limited by the USB 1 1 specification this is the case when execution of the previous command is in progress and a new command is received Finally there is the case where the Driver calls the usb accept command function from the interrupt handler for endpoint number zero When the Driver receives control from the usb accept command function it sends status in the status stage of the command transfer to the Host Therefore this function must return control but no command must be executed as soon as possible M Appendix 2 Audio Application 10 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Also the Client program uses usb ep rx done usb ep tx done and usb devcfg notice functions defined by the Driver but implemented in the program to control data transfers The role of these functions is described in following sections 10 2 4 USB AUDIO START command execution When the Device
9. the Driver stores request parameters into the structure NewC gt request Then the usb vendreq service function calls the usb accept command callback function passing a pointer to the request as a parameter The Client application may accept or reject a command execute it immediately or put into the Queue for later execution In any case the callback function must return a status which indicates whether the Client program accepts the request or not The Driver calls the usb vendreq done function to complete a command transfer passing the status M Vendor Request Handling 5 5 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc status usb accept command NewC if wLength 0 The request has no data stage so it can be completed usb_vendreq_done status M Vendor Request Handling PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 5 6 Freescale Semiconductor Inc 6 Miscellaneous Operations This chapter describes how the Driver handles port reset change configuration halt unhalt endpoint events and how it notifies the Client application 6 1 Port Reset Handling When a reset event occurs the Driver calls usb bus state chg service function from the interrupt handler for endpoint number zero passing the RESET value as a parameter int
10. Appendix 2 Audio Application eeeeeeeeeeessee 10 1 10 1 Jltncersnire ico E 10 1 LOSI Shs gt Importdnt NOS oes nene etse egeat iv ibd scia s e a EN SERI DE 10 1 10 1 2 Capabilities of Audio Application eese eene eren 10 1 0 1 3 Related Elle8 a 5 sessio t RO E EO RE MESSER SERE a FN bids Do teas Exe dR 10 1 10 2 Implementation of USB Audio Application eene 10 2 M iv PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc I0 USB SASS oiseau dis en E side it se deci iade ere 10 2 10 22 Inraalhizmg the DEer oor Cero casia denied ee 10 2 10 2 3 Program Execution FOW seas erai e nre Ide to Rear exe ede 10 3 10 2 4 USB AUDIO START command execution esee 10 4 10 2 5 USB AUDIO STOP command execution essere 10 6 10 2 6 USB AUDIO SET VOLUME command execution esee 10 6 10 2 7 START TEST OUT TRANSFER command execution 10 7 10 2 8 START TEST IN TRANSFER command execution sese 10 7 10 2 9 START TEST INOUT TRANSFER command execution 10 8 10 2 10 Request for string descriptor handling eese 10 8 10 2 10 1 Memory layout for string descriptors eese eene 10 9 10 2 10 2 Sending the string descri
11. Handler usb_vendreq_done status free NewC NewC NULL To access a command the Client application must use the cbuffer field defined in DEVICE_COMMAND structure The program may check if it supports that command it may execute it immediately or put it into the Queue for later execution In any event usb accept command must return a status that indicates whether the Client application accepts a command or not This is not a status of command execution but is rather a status of accepting a command and it will be sent in the status stage of command transfer The Client program must return status as soon as possible the time for sending status of accepting a command in status stage is limited by USB 1 1 specification Having that status the Driver calls usb vendreg done function from usb out service to complete a command transfer If status is not zero usb vendreq done sends a STALL response M Vendor Request Handling 5 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 5 3 Data IN request handling If the direction of data transfer is from Device to Host the Driver allocates memory for DEVICE COMMAND structure only Direction of data transfer is from Device to Host or no data stage ny NewC DEVICE COMMAND malloc sizeof DEVICE COMMAND If the Driver is unable to allocate memory for any reason it sen
12. IN final frame number M USB Device Driver Function Specification 7 21 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 22 usb set start frame number Implemented in CBI amp Isochronous Driver only Call s void usb set start frame number uint32 epnum uint16 frame num Arguments Table 7 20 usb set start frame number arguments epnum frame num in Number of endpoint in Number of frame in which stream will be started Description This function sets a frame in which a data stream will be started It permits the start of data transfer synchronously with the Host Returns No value returns Code example uinti6 start frame number start frame number usb get frame number 70 if start frame number 2047 start frame number 2048 usb set start frame number ISO IN final frame number M USB Device Driver Function Specification 7 22 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 23 usb sort ep array Call s void usb sort ep array USB EP STATE list int n Arguments Table 7 21 usb sort ep array arguments list inout Pointer to the array of UsB EP STATE elements Number of elements in the array pointed by list Description This function sorts elements in
13. TRUE It provokes the sending of a zero length packet to indicate the end of transfer if the last packet of the transfer is of maximum size If the last packet is short a call to this function has no effect The ep epnum senazrP filed is cleared by the Driver at the end of each transfer regardless of the previous contents of the field Returns No value returns Code example usb sendZLP M USB Device Driver Function Specification 7 20 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 21 usb set final frame number Implemented in CBI amp Isochronous Driver only Call s void usb set final frame number uint32 epnum uint16 frame num Arguments Table 7 19 usb set final frame number arguments epnum frame num in Number of endpoint in Number of frame in which stream will be closed Description This function sets a frame in which a data stream will be closed When the data stream is closed the Driver does not monitor either the Host s w activity or the Device side application The function also permits the correct start synchronously with the Host of a new data stream Returns No value returns Code example uinti6 final frame number final frame number usb get frame number 11 if final frame number 2047 final frame number 2048 usb set final frame number ISO
14. accepts a USB AUDIO START command it must start a loopback task The program determines the number of start frame and sends that number to the Host Also the usb set start frame number function is called for isochronous IN and OUT endpoints to inform the Driver from which frame it must start the data stream usb accept command then sets the start main task variable to start executing this task in the main function after the usb accept command returns control The main function examines the start main task variable and calls the main task function if that variable is set To implement a loopback task with data processing the program needs three buffers The first one for receiving data from the Host the second for sending processed data to the Host and finally the third one for data processing while data IN and OUT transfers are in progress The program allocates these buffers in SRAM module for the best performance bufferl receive data buffer uint8 mcf5272 rambar buffer2 data processing buffer uint8 mcf5272 rambar 882 buffer3 transmit data buffer uint8 mcf5272 rambar 1764 It should be noted that the program performs a loopback task for both 8 kHz and 44 1 kHz sample rates For the 8 kHz rate the size of each buffer must be 160 bytes 10 packets in a buffer 16 bytes packet size 16 bit mono while for 44 1 kHz the buffer size must be 882 bytes 9 packets 90 bytes pac
15. addition the Client program implements callback functions required by Driver usb reset notice it deletes the command queue and sets the variable Device reset to TRUE This variable is used by the most of command handlers to properly complete their task if the Device was reset usb devcfg notice clears the variable Device reset and permits execution of new commands from the Host The Client application implements the rest of the callback functions usb_ep_rx_done usb_ep_tx_done usb_ep_halt usb_ep_unhalt but they in fact do not do anything The following subsections describe in detail how the Client program executes each command 9 3 3 1 UFTP_READ command execution In the first instance the UFTP_READ command handler tries to find a given file If the file does not exist it reports an error to the Host on an interrupt endpoint Otherwise it allocates intermediate buffers M Appendix 1 File Transfer Application 9 9 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc To transfer a file from Device to Host two intermediate buffers are used detailed description of their purpose is described below In order to increase the execution speed of the program during file transfers these buffers must both be 4 byte aligned The first buffer is always 4 byte aligned regardless of whether it was dynamically allocated in
16. and pouT by fifo lengthin descending order usb sort ep array pIN nIN usb sort ep array pOUT nOUT This must be done in order to eliminate fragmentation of the FIFO buffer when allocating space for each active endpoint Thus addresses in the FIFO buffer for endpoints can be calculated in a simple way INpos 0 OUTpos 0 for i 0 i lt nIN i pIN i gt in_fifo_start INpos M Driver Initialization 2 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc INpos pIN i fifo length for i 0 i lt nOUT i pOUT i out fifo start OUTpos OUTpos pOUT i fifo length Finally the maximum length of packet the size of FIFO buffer and the address of FIFO buffer for each endpoint should be stored in the appropriate configuration register In the first instance this is done for endpoint number zero Initialize Endpoint 0 IN FIFO MCF5272 WR USB IEPOCFG imm O0 ep 0 packet size lt lt 22 ep 0 fifo length lt lt 11 ep 0 in fifo start Initialize Endpoint 0 OUT FIFO MCF5272 WR USB OEPOCFG imm 0 ep 0 packet size lt lt 22 ep 0 fifo length lt lt 11 ep 0 out fifo start then for the remaining endpoints for i 1 i lt NUM ENDPOINTS i if ep i ttype DISABLED if ep i dir IN Initialize Endpoint i FIFO MCF5272 WR USB E
17. automatically GET DESCRIPTOR requests for string descriptors are passed as a vendor specific request The string descriptors must be stored in external memory and not in the configuration RAM The memory layout for string descriptors is shown in Fig 5 1 below String descriptors are stored in the array of descriptors An element of that array is a structure defined in the usb audio h file Definitions for USB String Descriptors Zdefine NUM STRING DESC 4 define NUM LANGUAGES 2 typedef struct uint8 bLength uint8 bDescriptorType uint8 bString 256 STR DESC typedef STR DESC USB STRING DESC NUM STRING DESC NUM LANGUAGES 1 Client application allocates the USB STRING DESC NUM STRING DESC NUM LANGUAGES 1 array The first element in the array an element with index zero is a string descriptor that contains an array of two byte LANGID codes supported by the Device 0x409 and 0x407 IDs The next NUM STRING DESC descriptors are string descriptors written using a language with 0x409 ID the succeeding NUM STRING DESC descriptors with 0x407 language ID The position of string descriptors must correspond to the order of language IDs that are contained in the string descriptor having index zero Therefore if the first language ID is 0x409 then the first four NUM STRING DESC descriptors having indices 1 2 3 and 4 in the array must be written using a language having ID 0x409 The next four descriptors must be
18. command execution Execution of the UFTP GET DIR command handler starts from counting the length of the buffer total fname len variable is used needed to hold the name of files and size of name of files In addition it counts the number of files 11es count variable After this is completed the function reorders the values with reversed byte order each value independently for the PC Host it reads them as DWORD and stores them into the info buffer Having the size memory can be allocated dynamically for the buffer M Appendix 1 File Transfer Application 9 14 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Allocate buffer to store length of file name and file name for each file in it dir buffer uint8 malloc total fname len The program then sends status to the Host upon an interrupt endpoint If the status was UFTP SUCCESS the handler starts to fill the directory buffer with length of file name and name of file for each file It then sends info buffer to the Host upon a BULK IN endpoint If the buffer that contains the list of files is not empty the program sends it to the Host upon a BULK IN endpoint As a further remark concerning the execution of the UFTP GET DIR command the Host has no way to obtain the list of files from the Device if the Device is not able to allocate the buffer Changing the length of tran
19. ep epnum status NOT SENT PACKET M Isochronous Data Transfer 4 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc If a data packet was not sent to the Host the FIFO buffer must be cleared in order to send the next portion of data not unsent packet in the next frame In such a case the Device is still being synchronized with the USB clock After that it assigns NOT SENT PACKET status to the transfer and this status will be passed to usb tx done function after completion of the buffer transfer As the next step the Driver moves internal pointers on to the next packet There are three cases here all of which must be handled differently Assuming that the Client application sends data to the Host in buffers using five packets Case 1 Any packet except for the last and the next to last was not sent to Host assume it was packet 2 ep epnum buffer position iso ep epnum packet position SOFI EOPI SOF2 SOF3 EOP3 SOF4 EOP4 SOFS EOPS When SOF3 interrupt occurs usb isochronous transfer service determines that packet 2 was not sent to the Host EOP2 interrupt did not occur It removes all data from the FIFO buffer there is data from packet 2 there only In fact packet 3 must now be placed into the FIFO however the token for the third packet is missed by this time by the Device similar s
20. read arguments combuf in Pointer to the buffer that contains a command Description This function is a UFTP READ command handler Sends a given file to the Host Returns No value returns Code example case UFTP READ ifdef DEBUG printf Command UFTP_READ has been recognized by Client n fendif do_command_read command cbuffer break M Appendix 1 File Transfer Application 9 23 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 5 do command set transfer length Call s void do command set transfer length uint8 combuf Arguments Table 9 13 do command set transfer length arguments combuf in Pointer to the buffer that contains a command Description This function is a UFTP SET TRANSFER LENGTH command handler Sets a given by Host length of transfer Returns No value returns Code example case UFTP READ ifdef DEBUG printf Command UFTP READ has been recognized by Client n fendif do command read command cbuffer break M Appendix 1 File Transfer Application 9 24 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 6 do command wrrite Call s void do command write uint8 combuf Arguments Table 9 14 do command write arguments combuf in Pointer to the buffer that cont
21. s Default Control Pipe These requests are made using control transfers The request and the request s parameters are sent to the Device in the Setup packet VEND REQ interrupt is used to notify the Device about accepting a request When the Driver detects assertion of VEND_REO interrupt it calls the usb vendreqg service function from the interrupt handler for endpoint number zero usb vendreq service uint8 MCF5272 RD USB DRRi imm amp OxFF uint8 MCF5272 RD USB DRRi imm gt gt 8 uint16 MCF5272 RD USB DRR1 imm gt gt 16 uint16 MCF5272 RD USB DRR2 imm amp OxFFFF uint16 MCF5272 RD USB DRR2 imm gt gt 16 Device request data registers are used to notify that a standard class specific or vendor specific request has been received and to pass the request type and its parameters The interrupt handler for endpoint number zero reads bmRequestType bRequest and wValue parameters from register DRRI and wIndex wLengtn parameters from register DRR2 and passes them to usb vendreq service The usb vendreq service function determines the type of request data IN command data OUT command no data stage and handles it appropriately The Callback usb accept command function is used to pass a request and command block to the Client application This function is defined by the Driver but must be implemented in the Client program Upon receiving a new command the Driver calls that function
22. state field of each endpoint to the USB DEVICE RESET value This prevents the Client application from starting new transfers on an unconfigured Device It does not extend to endpoint number zero according to 1 transfers to endpoint number zero are permitted for an unconfigured Device M Miscellaneous Operations 6 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Functions usb tx data usb rx data usb ep wait and usb ep is busy examine the state field if they are called for a non zero endpoint If the Device is reset but not yet configured they return the USB DEVICE RESET value 6 2 Change of Configuration Handling A DEV CFG interrupt may occur at any time during execution of usb tx data usb rx data usb in service Or usb out service To ensure each routine is completed properly this interrupt must be disabled before starting working with buffers and restored after data copying is finished Otherwise the set configuration event handler may be called during data copying which clears the pointer to an intermediate buffer and then the interrupted function will read write from to zero address To handle the set configuration event dev_cfg interrupt the Driver calls the usb devcfg service function This function clears the ep epnum buffer structure for all endpoints This prevents usb in servi
23. t pha Made Ride wie 5 2 3 3 Data IN request handling cec t retenta borea ea thsoantacapeactoanedeae 5 4 5 4 No data request handling oio cre dee ettet PP e Lett ut ances eue uss QUOS ERN EER SR 5 5 6 Miscellaneous Operations eeeeeeeeeeeeeeeeeeeneeeen nnn 6 1 6 1 Port Reset Handling a isse e tb eS RU A Due e ie eda PY xe E Ve Ded VE 6 1 6 2 Change of Configuration Handling sio cei ettet ated teri de ia 6 2 6 3 Halt Unhalt Endpoint Handling i idein p epa feda made 6 2 7 USB Device Driver Function Specification 7 1 dele J sb Dus stale cBg SerVIGO o eie s tiec tulit a Y ONT addi iia a 7 1 Tale wusb devcofg Serviee iiec es e a Re AS bRRS S A RSS EN T EE E A 7 2 doe BSDoendporBtD 38E soie om eU d aes tol eb Ra acad 7 3 TAn USD CMG OLE UST wiles E 7 4 4 5 USD SP Hfo init esnseno eai ne p e ce e A E QR RUA T epee ARE aee 7 5 BiG SD Be 18 DUS Ye oe OR e item stadi ae EO MEOS UR UR LO det E aiis 7 6 quer usb epsstallisase eddie mde eedem telam esp at e EU 7 7 do ASE SEIN Welle aces eee ti De E ek Le e i 7 8 MED UBBoDHO mitens iadsein Gel has efti Etfi Gea chaste laces play sei toads Ged 7 9 7 10 NANI E 7 10 7 11 sb get frame Umbe eot es ERO Et Mieten Ia rr 7 11 T3412 Bs THE hich de ntvu o dioe udtef obla duet dens fatti dei dd cat an Def dac nefas 7 12 7 13 USD i o ES a A CO EEEE UU Peto auto ees 7 13 7 14
24. task function When the Host sends a command it will still be sending out data during the next 60 frames However the main task function completes the current IN and OUT transfers this will not take more than 10 frames and calls the usb set final frame number function passing the number of the next frame as a parameter into it final frame number usb get frame number 1 amp 2047 Tell Driver from what number of frame stop data IN OUT streams usb set final frame number ISO IN final frame number usb set final frame number ISO OUT final frame number It is correct to stop monitoring in the next frame after a frame in which the last packet was sent received or at least not earlier The handler of that frame checks sending receiving of the last IN OUT packet and stops monitoring transfers The Host continues sending data in the following 60 frames but the Driver clears the FIFO upon receipt of a packet and no Client notification is provided transfer monitoring is already stopped and no buffer is allocated The Device in turn does not send data to the Host All internal structures of the Driver are in the default state Control returns to the main function 10 2 6 USB AUDIO SET VOLUME command execution When the Client program receives the UsB AUDIO SET VOLUME command it sets the volume variable The value was sent by the Host in the data stage of the command transfer volume uintl
25. the Device must receive from the Host It has three parameters length of file length of file name and name of file The length of file name field is used to properly fetch the name of the file from the command The name of the file is not a NULL terminated string UFTP WRITE data Upon receiving this command the Device sends status to the Host and if that status was UFTP SUCCESS it receives the data from the Host on Bulk Out endpoint 9 2 3 3 UFTP GET FILE INFO command 03h The Host sends the UFTP GET FILE INFO command to get a size for a given file Table 9 4 UFTP GET FILE INFO command Byte Description of value 0 Operation code 03h 1 Length of file name 2 3 Name of file m not NULL terminated string length of file name 1 M Appendix 1 File Transfer Application 9 4 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc The command specifies a file the size of which the Device must send to Host It has two parameters length of file name and name of file The length of the file name field is used to properly fetch the name of the file from the command The name of the file is not a NULL terminated string UFTP GET FILE INFO data Upon receiving this command the Device sends status to the Host and if that status was UFTP_SUCCESS Device sends the length of the given file to the Host LSB fi
26. the corresponding request M Appendix 2 Audio Application 10 12 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 USB Audio Application Function Specification This section describes functions implemented in the USB Client program Function arguments for each routine are described as either in or inout An in argument means that the parameter value is an input only to the function An inout argument means that a parameter is an input to the function but the same parameter is also an output from the function Inout parameters are typically input pointer variables in which the caller passes the address of a pre allocated data structure to a function The function stores the result within that data structure The actual value of the inout pointer parameter does not changed 10 3 1 buffer init1 Call s void buffer initl void Arguments No arguments Returns No value returns Description This function clears SRAM memory Code example buffer initl M Appendix 2 Audio Application 10 13 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 2 buffer init2 Call s void buffer init2 void Arguments No arguments Returns No value returns Description This function initializes the first 160 bytes i
27. the packet size Therefore to send each packet a FIFO level interrupt must be used So in each frame the Driver places only one packet into the FIFO or initial bytes of packet if it is larger than the FIFO buffer and when FIFO level interrupt occurs the Driver places the rest of the current packet to the FIFO When the last packet of transfer is sent to the Host Driver received EOP interrupt and FIFO is empty the Driver notifies the Client application about completion of transfer by calling its usb ep tx done function and passing a status of transfer to it see next section After this it frees up the ep epnum buffer structure The Client program may M Isochronous Data Transfer 4 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc track the end of transfer either by using the usb ep tx done notification or by calling the usb ep wait usb ep is busy function The Client program may call usb tx data With the next buffer In order to work in a real time the Client program must call usb tx data every time before the next SOF interrupt occurs Two remarks are necessary concerning the sending of data to the Host 1 The Driver sends buffers to the Host in maximum size packets while this is possible If the last packet of the buffer is short the Driver sends short packet it does not fill it with data from the next buffe
28. usb rx data before a FIFO level or EOP interrupt for the following packet occurs If usb rx frame Or usb rx data returns control it does not mean that all frames data are received To know when the transfer is completed the Client application must use the usb rx done notification or the usb ep wait usb ep is busy function 4 5 Monitoring the Host Software During OUT Transfers There is a wide class of audio Devices which steadily consume sink Devices a fixed amount of data e g headphones The DAC of a headphone supplies a fixed amount of digital samples during some period of time Therefore the Device has to receive all of this data during a given time period or at least a buffer in which data is placed must be freed by the end of that period Let s assume that the Device must receive 5 packets of 16 bytes from the Host and then output the received data to headphones during 5 ms If the Host missed a frame in some frames did not send a packet the Device needs more than 5 ms to receive the 5 packets but the data must be output to headphones exactly after a given period The Driver is able to address this problem The Driver guaranties that the buffer will be freed after a required time even if the Host missed packets If the Host did not send some the packets the Client application will know about it by means of the notification usb ep rx done function and may interpolate missed samples or mute the output I
29. 6 dc gt cbuffer Swap the bytes in multiplication factor volume volume lt lt 8 volume gt gt 8 M Appendix 2 Audio Application 10 6 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc The Host sends this value with reversed byte order so bytes must be swapped over The volume variable is used in the process data function while modifying the amplitude of samples 10 2 7 START TEST OUT TRANSFER command execution Upon reception of this command the program determines the number of the frame in which test data OUT transfer will be started and of the frame in which it will be completed The Device sends the number of the start frame to the Host The Client application calls usb set start frame number usb set final frame number functions to check the test transfer for missed packets usb accept command then sets start isotest out stream variable and the main function calls test casel handler test casel handler sets the test mode variable the usb ep rx done function must accumulate transfer information during test OUT transfer Then it clears arrays that will hold the transfer information by calling the init test structures function The buffer initi1 function is then called to clear the space where the received data will be stored The Client program makes 5 OUT transfers by 5 packe
30. B Usage The UFTP Device and Host support USB requests and use the USB for the transport of command blocks data and status information as defined by the CBI Transport specification but including the following restrictions e A UFTP Device implements an Interrupt endpoint and uses that interrupt endpoint to indicate a possibility of command execution e The Host uses a Control endpoint endpoint number 0 to send a command block to the Device e A UFIP Device implements a Bulk In endpoint to transfer data to the Host and a Bulk Out endpoint to receive data from the Host M Appendix 1 File Transfer Application 9 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 2 2 Status Values The following status values are defined by UFTP protocol Table 9 1 Status values defined by UFTP protocol Status Value Description UFTP SUCCESS 0000h The command can be completed successfully UFTP FILE DOES NOT EXIST 0011h Required file does not exist on Device UFTP MEMORY ALLOCATION FAIL 0021h Not enough memory for intermediate buffers allocation No free position in the array of file structures UFTP NO POSITION FOR NEW FILE 0031h UFTP NOT ENOUGH SPACE FOR FILE 0041h Not enough memory for a new file 9 2 3 UFTP Command Descriptions Commands that are used in the UFTP protocol do not have a fixed length
31. BULK IN Alternatively the Driver calls usb ep tx done and usb ep rx done functions when it completes the corresponding transfer so it is a matter for the Client application which mechanism it will use M Introduction 1 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc The Driver also calls the usb accept command function which has to be implemented in Client application when it receives a command from the Host Examples of using other functions are given in Appendices 9 and 10 M Introduction 1 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 2 Driver Initialization This section describes step by step the initialization of the Driver The initialization is combined into one function usb init Different parts of this function are described in separate subsections 2 1 Initialization of Descriptor Pointers and Variables Initialization of the Driver starts from initialization of its global variable Newc refer to Chapter 5 DEVICE COMMAND NewC NULL To start work with the Driver the Client application must call the usb init function The only argument this routine has is the pointer to the structure that holds an address and size of Device descriptor usb init fetches the addresses from the structure an
32. CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 8 8 Freescale Semiconductor Inc 9 Appendix 1 File Transfer Application 9 1 Introduction This appendix describes a Device side USB File Transfer Application This program is used only for demonstration purposes The program illustrates some useful techniques see section 1 2 and gives an example of working with the USB Device Driver 9 1 1 Important Notes The stand alone version of the Client application works in much the same way as the uCLinux Client application The only difference lies in the file system The stand alone version allocates a structure for each file and uses read_file write_file functions to access the file This is done in order to easily remake the application for uCLinux Therefore under the OS the fread function is used instead of read file and the fwrite function is used instead of write file In addition the Linux file system is used instead of structures for files In other words the stand alone version emulates the work with files in the same way the OS does The Client application descriptors and program is designed to mostly support the CBI Transport specification From this the following may be inferred a Endpoints are used according the CBI Transport specification see section 2 1 b Descriptors are defined according the CBI Transport specification c The Interrupt data block is defined ac
33. Call s void init test structures void Arguments No arguments Returns No value returns Description This function clears arrays intended to hold information of test transfers completion Code example init test structures M Appendix 2 Audio Application 10 16 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 5 main task Call s void main task void Arguments No arguments Returns No value returns Description This function performs loopback task Code example main task M Appendix 2 Audio Application 10 17 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 6 print buffer contents Call s void print buffer contents void Arguments No arguments Returns No value returns Description This function prints out to terminal the contents of SRAM memory received bytes Code example print buffer contents M Appendix 2 Audio Application 10 18 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 7 print transfer status Call s void print transfer status uint32 in print uint32 out print Arguments Table 10 2 print transfer status arguments
34. Driver only Call s uint32 usb rx frame uint32 epnum uint8 start uint32 frames Arguments Table 7 16 usb rx frame arguments epnum in Number of endpoint through which data will be received from Host start inout Pointer to buffer where Driver will place received data from Host frames in Number of frames to read Description This function initializes the ep epnum buffer start field with the value start It sets the ep epnum buffer length value to 1 the Client program must take care of the buffer length to prevent overflow Also it sets up a corresponding read mode and the number of frames to read Assembler version is also provided Returns Table 7 17 usb_rx_frame returned values USB_DEVICE_RESET Device is reset USB_EP_IS_BUSY Endpoint is busy USB COMMAND FAIL Parameters passed to function are not properly initialized or given endpoint is not ready to receive new data USB COMMAND SUCCESS The function completed successfully Code example usb rx frame ISO OUT rx db 5 M USB Device Driver Function Specification 7 19 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 20 usb sendZLP Call s void usb sendZLP uint32 epnum Arguments Table 7 18 usb sendZLP arguments epnum in Number of endpoint Description This function sets ep epnum sendzLP filed to
35. EOPS interrupt did not occur thus the transfer of that buffer was not completed yet It removes all data from the FIFO buffer there is data from packet 5 there only usb isochronous transfer service completes the transfer of that buffer usb ep tx done epnum iso ep epnum status ep epnum buffer length ep epnum buffer start 0 ep epnum buffer length 0 ep epnum buffer position 0 iso ep epnum status SUCCESS iso ep epnum packet position 0 Following this the Client application is able to call usb tx data to transfer a new buffer SOF6 occurred therefore no data will be sent in this frame similar situation to the one described in section 4 1 remark 2 Thus usb tx data must step over the first packet in a new buffer and start placing a second packet into the FIFO This second packet will be sent in the seventh frame usb isochronous transfer service function sets the appropriate status for the usb tx data iso ep epnum state STEPOVER FIRST PACKET So if the Host misses several frames it does not receive data in these frames and does not receive data in the next frame either even if it issued an IN token In the next frame the Host may receive a few bytes of garbage bytes that were sent before starting to clear the FIFO Thus EOPI interrupt may occur but it will be a spurious interrupt If this interrupt occurs it occurs immediately following the SOF6 interrupt However usb tx data ha
36. Freescale Semiconductor Inc 7 3 usb endpointO isr Call s void usb endpoint isr void Arguments No arguments Description This function handles all interrupts that occur for endpoint number zero Returns No value returns Code example interrupt void usb endpointO0 handler void Call handler in USB Driver usb endpointO0 isr M USB Device Driver Function Specification PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 7 3 Freescale Semiconductor Inc 7 4 usb endpoint isr Call s void usb endpoint isr uint32 epnum Arguments Table 7 2 usb endpoint isr arguments epnum in Number of endpoint on which an interrupt occurred Description This function handles all interrupts for all endpoints available in the current configuration except for endpoint number zero Returns No value returns Code example interrupt _ void usb endpointi1 handler void Call handler in USB Driver usb endpoint isr 1 M USB Device Driver Function Specification 7 4 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 5 usb ep fifo init Call s void usb ep fifo init uint32 epnum Arguments Table 7 3 usb ep fifo init arguments epnum in Number of endpoint whose FIFO buffer must be reinitialized Descripti
37. Freescale Semiconductor Inc MCF5272 USB SW Developer Manual Stand Alone Device Driver for CBI amp Isochronous Transfers M5272 USB SDD CBII Rev 0 3 05 2002 Digital DNA m PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc CONTENTS Paragraph Title Page Ty INFOGUCHON aio eileen LII DII DEDI D 1 1 kls Driver eapabilitiessiosscosebotestoni p asc a situada em iia sions 1 1 12 MIRC Tats Dali tos an Ais rea ale reticere uUo ida beue 1 2 13 Quick start Guide e ete annii dirsa ecu aers nEaN niia eb tna dia 1 2 2 Driver IMAI ZAM OM as sssini estonia ec np dd inc oa ra xr epe eal NECS gn RA ET FEE EUN IRR US 2 1 2 Initialization of Descriptor Pointers and Variables ssseeses 2 1 2 2 Initialization of Endpoints ies easiest tatit eerte sndceueasecventesdesecsesnaseets 2 1 2 3 Initialization of the Configuration RAM seen nennen 2 2 2 4 Initialization of the FIFO Module oe ode IEEE acaea eu en Ep ex Oe ges dE 2 2 2 5 Ambtialization of InterT pts ioa ee tacos dte eot e aca dero tutae aba ide 2 5 3 Control Bulk Interrupt Data Transfer 3 1 3 1 Device to Host Data Transfer ne reti desc cee 3 1 3 1 1 Initiating the Data IN Transfer c0 aho tee es ot tuin 3 4 3 1 2 Continuation of the Data IN Transfer 0 ccceeeccece
38. HANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc CLEAR FEATURE request with the endpoint halt feature selector set A USB reset signal A SET CONFIGURATION or SET INTERFACE request On control endpoint a SETUP token for the next request When the endpoint is halted the Client program should abort the current transfer and reinitialize the FIFO for the endpoint by calling the usb ep fifo init function When an endpoint is halted the Driver notifies the Client application about it by calling the usb ep halt function And the Driver calls the usb ep unha1t function when the halt is cleared The Driver defines the prototypes of these functions however the Client application must implement them to do program specific work M Miscellaneous Operations 6 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc T USB Device Driver Function Specification This chapter describes functions implemented in the USB Device Driver Function arguments for each routine are described as in inout An in argument means that the parameter value is an input only to the function An inout argument means that the parameter is an input to the function but the same parameter is also an output from the function Inout parameters are typically input pointer variables in which the caller passes th
39. IFO only Then it makes sure there is data to send examines parameters start and length Finally the function ensures that the desired endpoint is an IN endpoint and the endpoint is not halted EOP EOT interrupts should be disabled in order to prevent damage of ep epnum buffer structure by the usb_in_service handler RESET and DEV_CFG interrupts must also be disabled in order to properly terminate the transfer usb_tx_data sets up the ep buffer structure ep epnum buffer start start ep epnum buffer length length ep epnum buffer position 0 Then the amount of data that can be placed into the FIFO buffer is determined free space ep epnum fifo length length parameter amount of data to be sent can be less than the size of FIFO the buffer for epnum thus additional modification must be made If the amount of data to be sent less than free space modify free space if intl16 free space gt length free space length Now usb tx data starts to write data to the FIFO buffer four bytes at a time while it is possible and the rest of data by one byte After that it sets the ep epnum buffer position field to the number of written bytes If this is all the data that has to be sent usb tx data finishes the transfer refer to Chapter 3 1 3 It does not clear the ep epnum buffer structure The usb tx data function placed data for at least one packet so EOP interrupt will occur
40. IMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 8 5 usb ep tx done Call s void usb ep tx done uint32 argl uint32 arg2 uint32 arg3 Arguments argl number of endpoint on which data transfer is completed arg2 status of completed data transfer arg3 number of sent bytes The value of arg2 parameter is always equal to SUCCESS Returns No value returns Description Driver calls this function when Device to Host IN transfer is completed M Application Specific Function Prototypes PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 8 6 Freescale Semiconductor Inc 8 6 usb ep unhalt Call s void usb ep unhalt uint32 arg1 Arguments arg1 number of unhalted endpoint Returns No value returns Description Driver calls this function when an endpoint is unhalted M Application Specific Function Prototypes PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 8 7 Freescale Semiconductor Inc 8 7 usb reset notice Call s void usb reset notice void Arguments No arguments Returns No value returns Description Driver calls this function when Device is reset port reset occurred M Application Specific Function Prototypes PRELIMINARY SUBJECT TO
41. IN transmit data buffer transfer size usb rx frame ISO OUT receive data buffer 10 When usb rx frame returns control no transmission reception is started The Driver initializes internal structures placing a first packet into the FIFO buffer for IN transfer and returning control Moreover no data monitoring is started When the Driver receives a frame having a number that was passed to the usb set start frame function only then can it start monitoring the transfers Actual data transmission reception must be started by the Host if it starts sending earlier it is the fault of the Host The application then enters a loop and waits until data transfers will be completed by polling out transfer finished and in transfer finished variables The variables new data received and 1ast data transmitted are cleared by default so no data processing is performed immediately When an OUT transfer is complete the Driver calls the usb ep rx done function The Client program sets the out transfer finished variable there Hence the program may change buffers when the OUT transfer completes not only the receive_data_buffer pointer changes but the data_processing_buffer as well The next OUT transfer is then started Finally the new_data_received variable is set Data processing cannot be started straightaway it may take a relatively long time during which the IN transfer can be completed IN and OUT transfers will be completed in t
42. NSFER LENGTH command Description of value Operation code 05h LSB Length of transfer MSB Upon receiving this command the Device sends UFTP SUCCESS status to the Host The length of the transfer is used during execution of UFTP READ and UFTP WRITE commands Files are sent between Host and Device by blocks The length of each block is equal to the length of a transfer Thus a given command sets up the length of the block on which transferred file will be divided up M Appendix 1 File Transfer Application 9 6 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 2 3 6 UFTP DELETE command 06h The Host sends the UFTP DELETE command to delete a required file on the Device Table 9 9 UFTP DELETE command Byte Description of value 0 Operation code 06h 1 Length of file name 2 3 Name of file m not NULL terminated string length of file name 1 Upon receiving this command the Device sends either UFTP FILE DOES NOT EXIST or UFTP SUCCESS status to the Host The command specifies a file which must be deleted by the Device It has two parameters length of file name and name of file The length of the file name field is used to properly fetch the name of the file from the command The name of the file is not a NULL terminated string M Appendix 1 File Transfer Appli
43. PCFG imm i O ep il packet size lt lt 22 ep il fifo length lt lt 11 ep il in fifo start else Initialize Endpoint i FIFO MCF5272 WR USB EPCFG imm i 0 ep il packet size lt lt 22 ep il fifo length lt lt 11 ep il out fifo start M Driver Initialization 2 4 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 2 5 Initialization of Interrupts The initialization of interrupts is combined into one function usb isr init First it clears any pending interrupts in all endpoints MCF5272 WR USB EPOISR imm OxOO001FFFF MCF5272 WR USB EPiISR imm OxOO1F MCF5272 WR USB EP2ISR imm OxOO1F Then the function enables the desired interrupts for all endpoints MCF5272 WR USB EPOIMR imm O0 MCF5272 USB EPOIMR DEV CFG EN MCF5272 USB EPOIMR VEND REQ EN MCF5272 USB EPOIMR WAKE CHG EN MCF5272 USB EPOIMR RESUME EN MCF5272 USB EPOIMR SUSPEND EN MCF5272 USB EPOIMR RESET EN MCF5272 USB EPOIMR OUT EOT EN MCF5272 USB EPOIMR OUT EOP EN MCF5272 USB EPOIMR IN EOT EN MCF5272 USB EPOIMR IN EOP EN MCF5272 USB EPOIMR UNHALT EN MCF5272 USB EPOIMR HALT EN MCF5272 USB EPOIMR OUT LVL EN MCF5272 USB EPOIMR IN LVL EN m eX ee Se eli ep eU IL Enable EOT EOP UNHALT and HALT interrupts disable FIFO LVL MCF5272 WR USB EPI1IMR imm 0x001E MCF5272 WR USB EP21MR imm 0x001E Finally it sets u
44. RAMES mode It increments the counter in the usb isochronous transfer service function if iso ep epnum transfer monitoring started TRUE iso ep epnum sent packet watch It must be 1 now and clears it in the usb out service if an EOP interrupt occurred iso ep epnum sent packet watch 0 If an EOP interrupt did not occur during the frame the Driver sets the corresponding bit in the status next call to usb isochronous transfer service function if iso ep epnum sent packet watch 1 Reset the counter iso ep epnum sent packet watch 1 Set up corresponding status for Client program iso ep epnum status NOT RECEIVED PACKET If the Host misses frames in the OUT transfers the Driver does not make gaps in the buffer i e it does not know the size of the expected packet If it does not suit the Client application the last one may call the usb rx frame function for each frame passing 1 into its frames parameter M Isochronous Data Transfer 4 10 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 4 6 Monitoring the Device side Application During OUT Transfers The Driver also monitors whether the Client program is working in real time or not If the FIFO level or EOP interrupt occurred but no buffer is allocated the Driver sets the appropriate status in usb out service functi
45. This document describes a Device side USB Driver developed for MCF5272 processor The document is divided logically into two parts The first part describes functionality of the Driver It covers data transferring to from the Host accepting vendor specific commands and describes how the Driver notifies the Client application about such events as completion of transfer reset changing of configuration and halt unhalt endpoint Each chapter in the first part describes in full detail all routines which perform some concrete functionality global structures and variables explains how they work together as a whole and why it works in this way The second part Chapter 7 is a specification of each function of the Driver It gives a short description of each function it s arguments and returned values Also an example is shown of the calling of each routine Appendix 1 describes a File Transfer Application example and Appendix 2 describes an Audio Application example 1 1 Driver capabilities e Passes a command having data IN stage data OUT stage or without data stage to the Client application in real time e Notifies Client application about completion of transfer reset changing of configuration and halt unhalt endpoint in real time e In Out data transferring is highly optimized using hand made assembler code e Simultaneous data transferring on different endpoints Thus if transfers require different endpoints the Driver will hand
46. ains a command Description This function is a UFTP WRITE command handler Receives a file from Host Returns No value returns Code example case UFTP WRITE ifdef DEBUG printf Command UFTP_WRITE has been recognized by Client n fendif do_command_write command cbuffer break M Appendix 1 File Transfer Application 9 25 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 7 fetch command Call s uint32 fetch command uint8 dcb Arguments Table 9 15 fetch command arguments dcb inout Pointer to the buffer where to place command Description This function copies command into the given buffer and deletes request with a command from the Queue Returns Function returns status Status NO NEW COMMAND means that command queue is empty so buffer pointed by acb is not initialized with a command Status COMMAND SUCCESS indicates that buffer pointed by dc contains a new command Code example if fetch command command block COMMAND SUCCESS switch command block 0 M Appendix 1 File Transfer Application 9 26 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 8 get string descriptor Call s uint32 get string descriptor uint8 desc index uint16 languageID uint16 length Argument
47. am must call the usb rx frame function to get data from M Isochronous Data Transfer 4 8 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc a given number of frames refer to Chapter 7 for detailed description of this function The Client program knows the time it passes the frame number i e number of milliseconds to the Driver and the Driver fills the buffer with data that it received from the Host during a given period It frees up the ep epnum buffer structure when a given number of frames not an amount of data is received the Client application must take care of buffer s lengths the safest way is to anticipate all packets to be of maximum size By means of this the data rate can be easily determined If the data rate does not suit the Client program the application may send feedback to the Host asking for a desired sample rate or implement a sample rate conversion Client dependant The use of this method of reading data is strongly recommended for isochronous transfers Regardless of the method chosen by the program the Driver notifies the Client application by calling it s usb ep rx done function passing a status of reading see next section and the number of read bytes to it Following this the Driver frees up the ep epnum buffer structure In order to work in real time the Client program must call usb rx frame Or
48. and usb in service Will either continue or finish the transfer properly The saved interrupt mask register must be restored The function then returns control M Control Bulk Interrupt Data Transfer 3 6 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 3 1 2 Continuation of the Data IN Transfer If the Host successfully receives a data packet it sends acknowledge to the Device and the USB module generates EOP interrupt At this moment there is a free space in the FIFO buffer for at least one data packet Thus placing a new portion of data into the FIFO buffer will continue the transfer usb in service is responsible for continuation of the transfer Its algorithm is shown in Fig 3 3 This function accepts two parameters epnum number of endpoint on which interrupt has occurred event the kind of interrupt s occurred First usb in service tests event for EOP interrupt If an interrupt occurred the function saves IMR and disables RESET and DEV_CFG interrupts If there is data to send it determines the amount of data that can be placed into the FIFO buffer The data present register for endpoint number zero monitors only the OUT FIFO so it cannot be used to determine the free space in the FIFO buffer for that endpoint Thus if epnum is zero only one packet can be safely placed in the FIFO from usb in service Free s
49. are while FIFO LVL is in service so it does not occur immediately usb out service reads out whole packet and then frees up the ep epnum buffer structure Then an EOP interrupt occurs ep epnum buffer start is cleared and MISSED PACKET is assigned to the status if fi fo_data is not tested for being equal to zero The Driver assigns MISSED PACKET status only if it performs transfer monitoring Using this status the Client application may check the speed for development and debugging purposes M Isochronous Data Transfer 4 11 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Isochronous Data Transfer PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 4 12 Freescale Semiconductor Inc 5 Vendor Request Handling For most of the standard Device requests the MCF5272 USB module handles them automatically GET DESCRIPTOR string descriptors only and SYNC FRAME requests are passed to the user Driver as a vendor specific request and in those cases the Driver handles them like any other vendor specific request This chapter describes how the Driver accepts different types of request data IN data OUT and NO data stage from the Host and passes them to the Client application 5 1 Accepting a request from the Host The Driver responds to requests from the Host on the Device
50. cation 9 7 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 3 Implementation of File Transfer Application This section explains how the Client application implements the file system and executes commands from the Host 9 3 1 Implementation of File System Each file is represented by a structure which holds the name of file size of file and pointer to the data define FILE NAME LENGTH 256 typedef struct uint8 file_name FILE_NAME_LENGTH name of file uint32 file length length of file uint8 file data pointer to data FILE SYSTEM ITEM The file itself the data contained in a file has a flat memory model it is a buffer in memory The memory for the structure and file data is allocated dynamically upon receipt of a new file A file system is a static array of pointers to the structure It has a fixed length and is limited by the Ax FILES COUNT constant define MAX FILES COUNT 512 Array of pointers to files FILE SYSTEM ITEM pfiles MAX FILES COUNT NULL can be between elements in the array 9 3 2 Initializing the Driver To start working with the Driver the Client application must first initialize it Before calling the usb init function which initializes the Driver the Client application needs to fill the DESC_INFO structure defined in usb h file exte
51. ce NewC DEVICE_COMMAND x5 malloc sizeof DEVICE COMMAND wLength Store the address where new command will be placed NewC gt cbuffer uint8 NewC sizeof DEVICE_COMMAND The Driver allocates memory for the request itself and for the command that will be received in the data stage the length of the command is determined by wLength If the Driver is unable to allocate memory it sends a STALL response to the Host by calling the usb vendreq done function if NewC NULL usb vendreq done MALLOC ERROR After allocating memory the Driver stores request parameters into the structure NewC gt request M Vendor Request Handling 5 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Finally the usb vendreg service function initializes the ep 0 buffer structure to accept a command in the data stage When data command block occurs on endpoint number zero the usb out service function will be called and receive a command When a command is received the Driver calls usb accept command callback function implemented in the Client program to notify the Client application about the new command and passes a pointer to that command request and command block if i ep epnum buffer length if epnum 0 amp amp NewC status usb_accept_command NewC Call the Rx
52. ce and usb out service from operating with data a way to terminate current data transfers The function then sets ep epnum state field to USB CONFIGURED So new transfers will be permitted for all endpoints from then on Next the Driver calls the usb devcfg notice function to notify the Client application that a new configuration interface alternate setting is set up passing the number of the configuration into its first parameter and number of interface alternate setting into the second refer to Chapter 6 for the specification of this function usb devcfg notice new config MCF5272 RD USB ASR imm The Driver defines the prototype of this routine but it must be implemented in the Client application to properly handle those events in Client specific manner 6 3 Halt Unhalt Endpoint Handling USB has the ability to halt endpoints when errors occur An endpoint can be halted for a variety of reasons e SET FEATURE request with the endpoint halt feature selector set usb ep stall Was called by the Client application This function should be called only when there is a critical error on the endpoint e On control endpoint an error processing a request Driver stalls endpoint number zero if it is unable to allocate memory for the request or when usb accept command returned a non zero value An endpoint can be cleared unhalted in several different ways M Miscellaneous Operations 6 2 PRELIMINARY SUBJECT TO C
53. cording the CBI Transport specification d The Host uses Accept Device Specific Command ADSC request for a Control endpoint endpoint number 0 to send a command block to the Device as defined by the CBI Transport specification However the Client application does not support any standard command set such as UFI RBC etc and so a simple UFTP command set was designed and used to achieve this goal The UFTP command set represents a very close fit for the file transport task It works on a file level in file system section 3 1 and not on a level of blocks of data Hence the Client application does not need to construct a file from blocks numbers of which it receives from the Host of data as in the case with UFI RBC and other standard command sets The program gets the name of a file using the UFTP protocol and requests the OS do the routine work access required sector block etc to access the required data In this way the Client application is simplified and makes for transparent communication with the Driver 9 1 2 Capabilities of File Transfer Application Some useful techniques are highlighted below which the program uses during file transfers e Simultaneous data transfer and data processing The Client application processes data reads writes data from to the file during transfer reception of the previous M Appendix 1 File Transfer Application 9 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Informat
54. d initializes global pointers usb Device descriptor pointer to Device descriptor usb Device descriptor descriptor info gt pDescriptor Then it initializes its local variables PConfigRam pointer to hardware on chip Configuration memory pDevDesc pointer to Device descriptor and DescSize size of Device descriptor The value of DescSize must be incremented by 3 refer to Chapter 2 3 2 2 Initialization of Endpoints Initialization of endpoints starts from initialization of endpoint number zero The type of transfer for that endpoint should be set to CoNTROL 0 The size of packet is taken from the Device descriptor ep 0 packet size USB DEVICE DESC pDevDesc bMaxPacketSize0 Length of the FIFO buffer for this endpoint is equal to four maximum size packets FIFO_DEPTH is equal to 4 ep 0 fifo length uint16 ep 0 packet_size FIFO DEPTH No buffer is allocated for endpoint number zero as yet so field start length and position should be cleared The state of the endpoint is USB_CONFIGURED according to USB 1 1 specification any transfers can be performed with an unconfigured Device via endpoint zero It is not the same as the state of Device such as de ault addressed Or M Driver Initialization 2 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc configured This field indicates whether eit
55. done epnum iso ep epnum status ep epnum buffer length ep epnum buffer start 0 ep epnum buffer length 0 ep epnum buffer position OF iso ep epnum status SUCCESS iso_ep epnum packet_position 0 So if the Host misses one frame it does not receive data that had to be sent in that frame and it does not receive data in the next frame either even if it issued IN token Then in the next frame the Host may receive a few bytes of garbage bytes that were sent before starting to clear the FIFO Thus an EOPS interrupt may occur however this is a spurious interrupt If this interrupt occurs it will occur immediately following the SOF5 interrupt Next the usb tx data has not been called yet so usb in service properly handles this situation the ep epnum buffer structure is cleared Even if EOP5 occurs after the call to usb tx data this situation will also be handled see case 1 M Isochronous Data Transfer 4 6 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Case 3 Last packet was not sent to the Host packet 5 ep epnum buffer position iso ep epnum packet position Paketi Pake2 SOF3 EOP3 SOF4 EOP4 SOF5 SOF6 EOP SOF7 EOP2 When SOF6 interrupt occurs usb isochronous transfer service determines that packet 5 of the previous buffer was not sent to the Host
56. dpoint and stores these values into a corresponding configuration register Returns No value returns Code example usb fifo init M USB Device Driver Function Specification 7 9 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 10 usb get desc Call s uint8 usb get desc int8 config int8 iface int8 setting int8 ep Arguments Table 7 9 usb get desc arguments config in Number of configuration iface in Number of interface setting in Number of alternate settings ep in Endpoint number Description This function returns a pointer to the required descriptor If config parameter is equal to 1 it returns a pointer to the Device descriptor If iface and setting are equal to 1 but config contains the number of the configuration it returns a pointer to the configuration descriptor of the configuration having number config If ep is equal to 1 but all previous parameters are properly initialized the function returns a pointer to the corresponding interface descriptor for given configuration If all parameters are initialized by a non 1 value then usb get desc returns a pointer to the endpoint descriptor for the given configuration interface and alternate setting The ep parameter is the offset and not the physical endpoint number Returns Pointer to required descriptor Code example
57. ds a zero length packet to indicate end of transfer no data will be provided and STALL handshake to the Host if NewC NULL if wLength 0 amp amp bmRequestType gt 127 The direction of data transfer is from Device to Host send zero length packet to indicate no data will be provided MCF5272 WR USB EPOCTL imm MCF5272 RD USB EPOCTL imm amp MCF5272 USB EPOCTL IN DONE usb vendreq done MALLOC ERROR After allocating memory the Driver stores request parameters into the structure NewC gt request Then the Driver calls the usb accept command function passing a pointer to the request as a parameter The Client application must decide if it either accepts a command or not If it does not accept a command the usb accept command function must return a non zero status As a result the Driver will send a zero length packet and a single STALL handshake to the Host indicating that no data will be provided and that the command failed status usb accept command NewC if status 0 The direction of command block transfer is from Device to Host but Client application does not accept a request no data is provided MCF5272 WR USB EPOCTL imm MCF5272 RD USB EPOCTL imm amp MCF5272 USB EPOCTL IN DONE usb vendreq done status M Vendor Request Handling 5 4 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale c
58. e 3 13 Fig 3 5 Algorithm of usb rx data function eee 3 15 Fig 3 6 Algorithm of usb out service function eeeeeeenene 3 18 Fig 9 1 Memory layout for string descriptors eicere tete eren eet 9 16 Fig 10 1 Memory layout for string descriptors seen 10 10 M vi PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc About this document This document describes initialization and functionality of USB Device Driver CBI amp Isochronous transfer types and how to use it in user s applications Audience This document targets software developers using MCF5272 processor Suggested reading 1 Universal Serial Bus 1 1 Specification 2 MCF5272 ColdFire Integrated Microprocessor User s manual Chapter 12 Definitions Acronyms and Abbreviations The following list defines the acronyms and abbreviations used in this document CBI Control Bulk Interrupt EOP End of Packet EOT End of Transfer FIFO Hardware on chip First In First Out buffer IMR Interrupt Mask Register RAM Random Access Memory SOF Start of Frame UFTP USB File Transfer Protocol USB Universal Serial Bus ZLP Zero Length Packet M vii PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 1 Introduction
59. e address of a pre allocated data structure to a function The function stores its result within that data structure The actual value of the inout pointer parameter is not changed 7 1 usb bus state chg service Call s void usb bus state chg service uint32 event Arguments Table 7 1 usb bus state chg service arguments event in Occurred event such as RESET SUSPEND etc Description This function handles RESUME SUSPEND and RESET interrupts Is called from the interrupt handler for endpoint number zero usb_endpoint0_isr function Returns No value returns Code example if event amp MCF5272_USB_EPOISR_RESET usb_bus_state_chg_service RESET M USB Device Driver Function Specification 7 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 2 usb devcfg service Call s void usb devcfg service void Arguments No arguments Description This function handles DEV_CFG interrupt It is called from the nterrupt handler for endpoint number zero usb endpoint0 isr function when the Host sets or changes the configuration Returns No value returns Code example if event amp MCF5272 USB EPOISR DEV CFG usb devcfg service M USB Device Driver Function Specification 7 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com
60. e buffer pointed to by buffer1 must first be allocated If the length of the transfer is less than or equal to 2048 bytes and the variable place buffers to sramis TRUE the buffers will be allocated in the SRAM module otherwise the memory for these buffers will be allocated dynamically If the length of the file is less than or equal to the length of the transfer only one write operation from the temporary buffer to the file will be performed and the second buffer will not be used In this case memory must be allocated for the first intermediate buffer only if transfer length lt INT SRAM SIZE gt gt 1 amp amp place buffers to sram TRUE bufferl uint8 mcf5272 rambar M Appendix 1 File Transfer Application 9 12 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc else if flength transfer length bufferl uint8 malloc flength else bufferl uint8 malloc 2 transfer_length padded_bytes Then handler attempts to allocate memory for the file structure and the file data Try to allocate memory for the new file ptemp_file FILE_SYSTEM_ITEM malloc sizeof FILE_SYSTEM_ITEM flength The function sends status to the Host If the status was UFTP_SUCCESS the Host can start to transfer the file Memory will now be allocated for a new file therefore if the file with the given na
61. e last is smaller sendzrP must be setup to TRUE If the Client application is able to send all the requested data it does not need to call usb sendZzLP function senazrP field is cleared by Driver after last transfer The EOP handler completes the transfer in this case see the source code above For more information refer to Chapter 6 17 EOT interrupt occurs if a short length or zero length packet was sent It completes the transfer and sets EPNCTL IN DONE bit to send data for the next transfer by maximum size packets previously that bit was cleared 3 1 4 Notifying Client Application about Completion of Data IN Transfer When the transfer is completed all the data is received by Host Driver calls usb ep tx done function either from EOP or EOT event handler to notify Client application about termination of transfer The Driver defines the prototype of that function but it must be implemented in the Client application to handle properly that event in a Client specific manner usb ep tx done must return control as soon as possible and it is not intended for initiating a new data transfer directly by calling the usb tx data function ep epnum buffer structure is still busy and usb tx data will return control with error status The best way to accomplish this is when usb ep tx done is used to change some control and or status variables structures which in turn will be examined in the main program M Control Bulk Int
62. ength 0 ep epnum buffer position 0 M Control Bulk Interrupt Data Transfer 3 10 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc ep epnum sendZLP FALSE EOT will occur in such a case and its handler completes the transfer If the length of a transferred buffer was a multiple of the maximum size of packet one of two variants is possible either the Host received all the data it expected or not Field sendZLP is used to distinguish these cases The Client application knows the amount of data requested by the Host If that amount is larger than the Client application is going to send there is a possibility to send the last packet with the maximum size To properly handle the end of transfer in this case the Client application must call the usb sendZLP function with a required endpoint as a parameter The function sets up the sendzLP field to TRUE The Driver tests this field and only if the last packet is maximum size does it send zero length packet The Client application does not need to calculate the remainder of a division to find the size of the last packet before calling usb tx data since the Driver makes the calculation by itself The only thing the Client application must do is to compare the size of requested data by Host with the amount of data that the Client application is going to send before each transfer If th
63. er endpoint with the same direction To meet these restrictions usb fifo init allocates two arrays of pointers to endpoints one for IN endpoints and the other for ouT endpoints USB_EP_STATE pIN NUM_ENDPOINTS USB EP STATE pOUT NUM ENDPOINTS M Driver Initialization 2 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Endpoint number zero is always present and bi directional Thus its address should be stored in both arrays PIN O amp ep 0 pOUT 0 amp ep 0 nIN nOUT 1 Then the function sorts the endpoints by direction and allocates them into two arrays for i 1 i lt NUM ENDPOINTS i if ep i ttype DISABLED if ep i dir IN PIN nIN amp epl i else pOUT nOUT amp ep i For the first call of usb fifo init from usb init all these endpoints are disabled Thus arrays pIN and pOUT contain the address of endpoint number zero only Then it calls usb_make_power_of_two passing the length of the FIFO buffer for each endpoint for i 0 i lt nIN i usb make power of two amp pIN i fifo length for i 0 i lt nOUT i usb make power of two amp pOUT i fifo length usb make power of two finds the nearest higher power of 2 and stores it into fifo length usb fifo init then sorts endpoints their addresses in arrays pIN
64. er information by calling the init test structures function The buffer init2 function is then called to initialize the buffer with data The Client program sends 5 buffers by 5 packets to the Host When each transfer completes the usb ep tx done function stores status of the transfer and the amount of bytes sent it will always be 800 bytes to the corresponding tx status and tx size arrays Also the out transfer finished variable set which is being polled in test casel handler When all transfers are completed test case2 handler prints the data which was sent to the Host and prints information status and the amount of received data for each transfer 10 2 9 START TEST INOUT TRANSFER command execution Upon receiving this command the program determines the number of the frames in which test data IN and data OUT transfers will be started and of the frame in which these transfers will be completed The Device sends the number of the start frame to the Host The Client application calls usb set start frame number and usb set final frame number functions for both endpoints to check the test transfers for missed packets usb accept command then sets start isotest inout stream variable and the main function calls test_case3_handler test case3 handler sets the test mode variable usb ep rx done and usb ep tx done functions must accumulate transfer information during test transfers Arrays that will
65. errupt Data Transfer 3 11 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc When the Driver receives control from usb ep tx done it clears ep epnum buffer structure and a new transfer can be started 3 2 Host to Device Data Transfer Assuming that the OUT transfer starts from the moment when function usb rx data is called if there is data in the FIFO buffer but the Client buffer is not allocated yet the transfer will not be started EOP interrupts will occur while FIFO buffer is able to accept data and usb out service function will properly handle this situation But for the Client program transfer is not started yet usb rx data accepts three parameters epnum number of endpoint through which data will be transferred to Device start pointer to the buffer where data will copied from FIFO buffer length number of bytes that will be received This function initializes the fields of global structure ep buffer It sets the field ep epnum buffer start to the beginning of data buffer where it will place the data ep epnum buffer length to the size of expected data and ep epnum buffer positionto 0 no data read yet Then the function determines the number of bytes in the FIFO buffer and copies that amount of data from FIFO to destination buffer After that it modifies the ep epnum buffer position field e
66. fer Returns No value returns Code example DESC INFO Device desc Device desc pDescriptor uint8 amp Descriptors Device desc DescSize usb get desc size usb init amp Device desc M USB Device Driver Function Specification 7 12 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 13 usb in service Call s void usb in service uint32 epnum uint32 event Arguments Table 7 11 usb in service arguments epnum in Number of endpoint event in Events occurred for epnum endpoint Description This function handles FIFO LVL EOP and EOT interrupts for all IN endpoints in the current configuration Assembler version is also provided Returns No value returns Code example if event amp MCF5272 USB EPNISR EOT MCF5272 USB EPNISR EOP MCF5272 USB EPNISR FIFO LVL IN Endpoint if MCF5272 RD USB EPISR imm epnum amp MCF5272 USB EPNISR DIR usb in service epnum event M USB Device Driver Function Specification 7 13 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 14 usb isochronous transfer service Implemented in CBI amp Isochronous Driver only Call s void usb isochronous transfer service void Arguments No arguments Description This function is used to pro
67. ffer start ep epnum buffer start ep epnum buffer position ep epnum buffer length Received Data Data already Free space read from FIFO EOP interrupt occurred usb out service is called and reads from FIFO ep epnum buffer start ep epnum buffer start eplepnum buffer start ep epnum buffer position ep epnum buffer length Received Data Data already Free space read from FIFO Fig 3 4 Stages of receiving data by the Driver M Control Bulk Interrupt Data Transfer 3 13 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc When usb rx data returns control the Client application may process another portion of data or execute some algorithm This activity will be interrupted from time to time by EOP interrupts and usb out service will be called When the Client application finishes execution of its algorithms and is ready to receive other data from the Host it may call usb ep is busy function to test if desired endpoint is free or usb ep wait to wait while desired endpoint is busy For more detailed information about these functions refer to Chapter 8 The different stages of data transfer from Host to Device are shown in Fig 3 4 3 2 1 Initiating the Data OUT Transfer usb rx data function is used to start receiving the data from the Host The algorithm of this function is shown
68. from the Host The Client program implements this function sets start main task start isotest out stream start isotest in stream and start isotest inout stream Variables determines the number of frame in which data transfers must be started sends that number to the Host and asks the Driver to start monitoring transfers from that frame But it does not execute a command directly Only a request for a string descriptor Client application handles immediately The main function polls these variables in an infinite loop If one of the variables is set the program finds and executes the appropriate function to perform the corresponding task This is one of the best ways to recognize a new command from the Host and execute it The main advantage of this method compared to executing the command directly in the usb accept command function 1s described below The program may execute permanently some task such as process and transfer data etc The Host during the execution of that task by the Device manipulates the Device gets sets attributes of bass control mixer control volume control etc for example Hence this method permits these requests to be handled in real time by interrupting the main process and without the necessity of writing any extra code in the main task handler to see whether the Device received a new command from the Host or not Handling a request for a string descriptor may serve as an example The Client program
69. h data processing The Client application processes data reduces the amplitude of each sample while performing IN and OUT data transfers e Using the SRAM module for allocating intermediate buffers which makes for a faster execution speed of the program during IN OUT data transfers 10 1 3 Related Files The following files are relevant to the Client Program usb audio h Client application types and constant definitions usb audio c main program executes commands from Host performs data transferring e usb audio desc c contains Device configuration interface endpoint and string descriptors M Appendix 2 Audio Application 10 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc The Client application also requires the printf c file in test mode the program calls the printf function to print out data transfer test information The rest of the files in the init group are used to initialize the board and processor 10 2 Implementation of USB Audio Application The following section explains how the Client application performs isochronous transfers and executes commands from the Host 10 2 1 USB Usage The Host uses Control endpoint endpoint number 0 to send commands to the Device The USB Audio Device implements an Isochronous In endpoint to transfer data to the Host and an Isochronous Out endpoint t
70. han the 5 ms allowed Hence buffer overlapping may Occur in such cases The Driver is able to address this problem by moving the internal pointer in the buffer like it sends data to the Host even if the Host does not issue an IN token In effect the Driver guarantees that the buffer will be freed in a given time thus assuring deterministic behavior of the system Moreover when the Host resumes sending the tokens it will receive not old data that ought to have been sent in the previous frames but actual data If the Client application wants the Driver to perform transfer monitoring it must call the usb set start frame number function The Driver starts analyzing transfer from a given frame the number of which was passed as a parameter to that function It must be M Isochronous Data Transfer 4 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc the number of a frame in which the first data packet is to be sent to the Host AII the transfers after this frame will then be monitored When the last transfer is completed data monitoring must be stopped in order to properly start new one or properly continue data transfer without monitoring To stop monitoring the Client program must call the usb set final frame number function passing the number of the frame in which data monitoring must be stopped It must be in a frame following t
71. he ep epnum buffer position field by the number of written bytes For more detailed information about usb in service refer to Chapter 3 1 2 When usb tx data returns control the Client application may process another portion of data or execute an algorithm This activity will be interrupted from time to time by EOP EOT interrupts and usb in service will then be called When the Client application finishes execution of its algorithms and is ready to send another data buffer to USB it may call the usb ep is busy function to test 1f desired endpoint is free or M Control Bulk Interrupt Data Transfer 3 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc usb ep wait to wait while the desired endpoint is busy For more detailed information about these functions refer to Chapter 7 The different stages of data transfer from Device to Host are represented in Fig 3 1 below M Control Bulk Interrupt Data Transfer PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 3 2 Freescale Semiconductor Inc Initial state ep epnum buffer start 0 ep epnum buffer position 0 ep epnum buffer length 0 Call to usb tx data ep epnum buffer start ep epnum buffer start ep epnum buffer position 0 ep epnum buffer length t y Data Buffer to be sent u
72. he frame in which the last data packet was sent to the Host or at least not earlier the SOF interrupt handler of the next frame checks missed EOP interrupts in previous frame In such a case the Driver can correctly handle the situation when the last packet was not sent to the Host The Driver monitors whether the Host s w is working in real time while accepting data from the Device using the following mechanism A data packet i e EOP interrupt occurs once per USB frame SOF interrupt also occurs once per frame it is a start of frame interrupt If the Host s w misses some frames does not send IN tokens to Device EOP interrupt will not occur during those frames The Driver increments counter in usb isochronous transfer service function if iso ep epnum transfer monitoring started TRUE iso ep epnum sent packet watch It must be 1 now and clear it in usb in service handler if EOP interrupt occurred iso ep epnum sent packet watch 0 When the next SOF interrupt occurs usb isochronous transfer service tests iso ep epnum sent packet watch field to determine whether EOP interrupt occurred during the previous frame if iso ep epnum sent packet watch 1 Remove unsent packet from FIFO buffer MCF5272 WR USB EPCFG imm epnum MCF5272 RD USB EPCFG imm epnum Reset the counter iso ep epnum sent packet watch 0 Set up corresponding status for Client program iso
73. he same frame however the USB is a serial bus so there is some delay between them Hence to start data processing with received data both transfers IN and OUT must be finished and new transfers must be started But starting a new transfer IN or OUT must be done separately in order to increase the performance of the program If the first to finish is an IN transfer then the next usb tx data function can be called to place the first packet or part of it into the FIFO buffer while data from the OUT transfer is being sent over the bus When the IN transfer is complete the Driver calls the usb ep tx done function The Client program sets the in transfer finished variable So the program changes the buffer transmit data buffer pointer and starts the next IN transfer The last data transmitted variable is then set M Appendix 2 Audio Application 10 5 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc When both transfers have completed and the next transfers started the received data can be processed The program performs this task iteratively while the stop main task variable is cleared see the following section 10 2 5 USB AUDIO STOP command execution On receiving the USB AUDIO STOP command from the Host the Device must stop the loopback task The usb accept command sets the stop main task variable to stop the loop in the main
74. her endpoint is able to transmit receive data or not The rest of the endpoints must be disabled for i 1 i lt NUM ENDPOINTS i DISABLED USB_DEVICE_RESET ep i ttype ep i state 2 3 Initialization of the Configuration RAM To access the configuration RAM of the USB module that memory must first be disabled otherwise an access error results The Driver clears the CFG RAM Var bit of USB Endpoint 0 Control Register EPOCIL and disables the USB module MCF5272 WR USB EPOCTL imm 0 Then the configuration RAM is loaded with the descriptors for i 0 i lt DescSize 4 itt pConfigRam i pDevDesc i The configuration RAM is long word accessible only The compiler performs division by 4 as a right shift by 2 In order not to decrease the actual size of descriptors 3 was added to DescSize refer to Chapter 2 1 Descriptors can be stored in configuration RAM in a 4 byte format 2 4 Initialization of the FIFO Module The initialization of the FIFO module is combined into one function usb fifo init This function is called from usb_devcfg_service routine also According the documentation for MCF5272 USB Module the following restrictions apply e EPnCFG FIFO_SIZE must be a power of 2 e EPnCFG FIFO ADDR must be aligned to a boundary defined by the EPnCFG FIFO_SIZE field e The FIFO space for an endpoint defined by FIFO_SIZE and FIFO_ADDR must not overlap with the FIFO space for any oth
75. hold the transfer information are then cleared by calling the init test structures function After that the bu fer init2 function is called to initialize the buffer with data The Client program makes 5 OUT transfers by 5 packets frames from the Host and sends 5 buffers by 5 packets to the Host simultaneously When each transfer completes usb ep tx done and usb ep rx done functions store the status of the corresponding transfers and the amount of sent received bytes into info structures When all transfers are completed test case3 handler prints transfer completion information 10 2 10 Request for string descriptor handling When the Client program receives a request for a string descriptor usb accept command starts handling it immediately by calling the M Appendix 2 Audio Application 10 8 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc get string descriptor function The status which this function returns will be passed to the Driver and sent to the Host in the status stage of the command transfer This following section illustrates the memory layout for string descriptors and describes how the Client application sends a given descriptor to the Host 10 2 10 1 Memory layout for string descriptors According to the documentation of the USB module the request processor does not handle requests for string descriptors
76. if desc index i NUM STRING DESC i desc index stdesc uint8 amp usb string descriptor i else stdesc uint8 amp usb_string_descriptor 0 and gets the size of that descriptor size stdesc If the descriptor is longer than the number of requested bytes it modifies the size if size gt length size length else usb_sendZLP 0 If the Host requested more bytes than the length of the descriptor a situation may occur where the Driver must indicate an end of transfer by sending a zero length packet this happens when the length of the descriptor is a multiple of the maximum size of the packet for endpoint number zero Therefore the usb sendzLiP function must be called in such a case with zero endpoint as a parameter a string will be sent on endpoint number zero This does not mean that a zero length packet will necessarily be sent If the last packet is short but not zero length a zero length packet will not be sent M Appendix 2 Audio Application 10 11 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Then the get string descriptor function initiates a transfer of the descriptor to the Host usb tx data 0 stdesc size Finally the success value is returned to the usb accept command function and that function returns the same value to the Driver The Driver completes
77. in Fig 3 5 yes yes Are transfers allowed for this endpoint yes yes Is there buffer allocated no Is this an OUT endpoint M Control Bulk Interrupt Data Transfer 3 14 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Is endpoint halted Save the current IMR Disable EOP EOT RESET DEV_CFG interrupts Set up EP buffer structure Determine number of bytes in FIFO buffer Read data from FIFO buffer Modify position Is it all the data to be received Finish transfer Restore saved IMR Fig 3 5 Algorithm of usb rx data function Control Bulk Interrupt Data Transfer 3 15 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc usb rx data accepts three parameters see Chapter 3 2 First it checks whether the Device 1s reset for data transfers with non zero endpoint Endpoint number zero transfers are permitted even if the Device is not configured Then it checks that the epnum parameter does not exceed the maximum number of endpoints 7 After that usb rx data tests that the given endpoint is not busy See if the EP is currently busy if ep epnum buffer start return 1 It checks the ep epnum b
78. int8 x amp usb string descriptor i else stdesc uint8 amp usb string descriptor 0 and gets the size of that descriptor size stdesc If the descriptor is longer than the number of requested bytes it modifies the size if size gt length size length else usb sendZLP 0 If the Host requested more bytes than the length of the descriptor the situation may arise where the Driver must indicate an end of transfer by sending zero length packet this happens when the length of descriptor is a multiple of the maximum size of packet for endpoint number zero Thus the usb sendzLP function must be called in such a case with zero endpoint as a parameter string will be sent on endpoint number zero This does not mean that a zero length packet will necessarily be sent If the last packet is short but not zero length a zero length packet will not in fact be sent Then the get string descriptor function initiates transfer of the descriptor to the Host usb tx data 0 stdesc size Finally it returns a success value to the usb accept command function and that function returns this value to the Driver The Driver completes the corresponding request 9 4 USB File Transfer Application Function Specification This section describes the functions implemented in the USB Client program Function arguments for each routine are described as in inout An in argument implies that the parameter va
79. ion usb ep rx done function is not called in such a case The Driver defines this function also however the Client program must implement it The Driver passes a pointer to the just received command as a parameter to usb accept command For more detailed description refer to Chapter 4 2 When the Driver receives control from usb ep rx done Or usb accept command it clears the ep epnum buffer structure and a new transfer can be started M Control Bulk Interrupt Data Transfer 3 20 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 4 isochronous Data Transfer for CBI amp Isochronous Driver only This chapter explains how the Driver controls isochronous IN OUT transfers It describes how to open isochronous IN and OUT data streams and how to close them correctly Also this chapter describes how the Driver performs per frame monitoring of Host side software and Device side Client application when they are working in real time 4 1 Device to Host Data Transfer This subsection describes the concepts of isochronous IN transfer tells how the Driver opens a data stream continues it etc The following two sections describe how the Driver monitors whether the Host software and Device side Client application are working in real time It also describes how the Driver sustains sample rate if the Host s w misses frames Some remarks t
80. ion On This Product Go to www freescale com Freescale Semiconductor Inc next portion of data It uses two intermediate buffers first to transfer receive the data and second to read write the next portion of data When the first buffer becomes empty full the buffers switch places e Using the SRAM module for allocating intermediate buffers makes for a faster execution speed of the program during transfer or reception of a file 9 1 3 Related Files The following files are relevant to the Client Program e cbi h Client application types and global constant definitions e cbi c main program executes commands from the Host hold files cbi_desc c contains Device configuration interface endpoint and string descriptors e uftp_def h operation code and status values definitions for UFTP protocol The Client application requires the following files alloc c program uses dynamic memory allocation so the module containing ma11oc and free functions is needed e printf c in debug mode the program calls the printf function to output debug information e stdlib c the program works with strings and calls some related functions The rest of the files in the init group are used to initialize the board and the processor 9 2 UFTP Protocol Description This section describes USB usage by the UFTP protocol and specifies the structure of commands that the Host sends to the Device 9 2 1 US
81. is larger than 256 then 256 is assigned to the result value No value returns Code example Make sure FIFO size is a power of 2 if not make it so for i 0 i lt nIN i usb make power of two amp pIN i gt fifo_length USB Device Driver Function Specification 7 16 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 17 usb out service Call s void usb out service uint32 epnum uint32 event Arguments Table 7 13 usb out service arguments epnum in Number of endpoint event in Events occurred for epnum endpoint Description This function handles FIFO LVL EOP and EOT interrupts for all OUT endpoints in the current configuration The assembler version is also provided The assembler version of this function does not test the buffer for overflow The buffer may be overflowed because of an error in the Host software not on the Device side Hence in the C version this test is done only as an aid in Host software development Returns No value returns Code example if event amp MCF5272 USB EPNISR EOT MCF5272 USB EPNISR EOP MCF5272 USB EPNISR FIFO LVL IN Endpoint if MCF5272 RD USB EPISR imm epnum amp MCF5272 USB EPNISR DIR usb in service epnum event OUT Endpoint else usb out service epnum event M USB Device Driver Function Specificatio
82. ituations are described in section 4 1 remark 2 Thus data from packet 4 must be placed into the FIFO instead and that packet will be sent to the Host in the fourth frame Therefore the usb isochronous transfer service function points ep epnum buffer position to the beginning of fourth packet ep epnum buffer position iso ep epnum packet position T ep epnum packet size and points iso ep epnum packet positionto the end of fourth packet iso ep epnum packet position ep epnum packet size lt lt 1 if iso ep epnum packet position gt ep epnum buffer TERIEN iso ep epnum packet position ep epnum buffer length M Isochronous Data Transfer 4 4 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Following this the function places packet 4 into the FIFO If the packet is larger than the FIFO the copying will be continued by usb in service after mising a FIFO level interrupt Therefore if the Host misses one frame it does not receive the data that had to be sent in that frame and it does not receive data in the next frame either even if it issued IN token In the next frame Host may receive only a few bytes of garbage bytes that were sent before starting to clear the FIFO Thus EOP3 interrupt may occur but this is a spurious interrupt iso ep epnum packet position should not be modified in usb in service
83. ket size 1 packet 72 bytes packet size Thus the maximum buffer offset is chosen bufferl buffer2 and buffer3 variables constantly point to the corresponding buffers receive data buffer data processing buffer and transmit data buffer will switch places To send receive data with the required rate the Device uses different packet sizes the same configuration the same interface but different alternate settings The Host chooses the desired rate by setting an appropriate alternate setting The Driver catches it on the DEV CFG interrupt and calls the usb devc g notice function passing the number of the new configuration and the number of the interface alternate setting in order to notify the Client application of this The Client program sets the transfer size variable in that function depending upon the required rate alternate setting if altsetting 1 transfer size 160 if altsetting 2 M Appendix 2 Audio Application 10 4 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc transfer size 882 The Client program requests the Driver to send transfer size bytes to the Host Regardless of the transfer size value 160 bytes or 882 bytes any IN transfer will take 10 frames the maximum packet size changes accordingly And at once the Client program requests the Driver to read data from 10 frames usb tx data ISO
84. le Semiconductor Inc 9 4 2 do command get dir Call s void do command get dir void Arguments No arguments Description This function is a UFTP_GET_DIR command handler Sends a list of files to the Host Returns No value returns Code example case UFTP_GET_DIR ifdef DEBUG printf Command UFTP_GET_DIR has been recognized by Client n endif do_command_get_dir break M Appendix 1 File Transfer Application 9 21 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 3 do command get file info Call s void do command get file info uint8 combuf Arguments Table 9 11 do command get file info arguments Combuf in Pointer to the buffer that contains a command Description This function is a UFTP GET FILE INFO command handler Sends a size of given file to the Host Returns No value returns Code example case UFTP GET FILE INFO ifdef DEBUG printf Command UFTP_GET_FILE_INFO has been recognized by Client n fendif do command get file info command cbuffer break M Appendix 1 File Transfer Application 9 22 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 4 do command read Call s void do command read uint8 combuf Arguments Table 9 12 do command
85. le these transfers independently and simultaneously Driver does not wait until the transfer for some other endpoint finishes if required endpoint is free it starts a new transfer immediately e Transfer data in both directions on endpoint number zero in the same way as for other endpoints The Driver ONLY dedicates an endpoint number zero in order to accept commands from the Host The usual data transfers from the Host to the Device and from the Device to the Host are available on endpoint number Zero e During Isochronous IN OUT transfers the Driver can perform if Device side Client application needs it per frame monitoring of Host side software and Device side Client application when they are working in real time If the Host s w is not working in real time i e misses frames in some frames does not send IN OUT tokens the Driver sustains the sample rate relative to the Device it emulates sending of data to the Host and notifies the Device side Client application about missed frames by the Host s w Therefore when Driver Device side s w is still being synchronized with USB and when sending of tokens is resumed the Device will send not the old data but the actual data for IN transfers M Introduction 1 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc If the Device side Client application is not working in real time i e it passes
86. lue is an input only to the function An inout argument implies that a parameter is an input to the function but the same parameter is also an M Appendix 1 File Transfer Application 9 18 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc output from the function znout parameters are typically input pointer variables in which the caller passes the address of a pre allocated data structure to a function The function stores the result within that data structure The actual value of the inout pointer parameter is not changed M Appendix 1 File Transfer Application 9 19 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 1 do command delete Call s void do command delete uint8 combuf Arguments Table 9 10 do command delete arguments Combuf in Pointer to the buffer that contains a command Description This function is a UFTP DELETE command handler Deletes a given file Returns No value returns Code example case UFTP DELETE ifdef DEBUG printf Command UFTP_DELETE has been recognized by Client n fendif do_command_delete command cbuffer break M Appendix 1 File Transfer Application 9 20 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freesca
87. me exists on Device it can now be removed if file_exists free pfiles fpos Then the handler initializes a structure for the file A file is received from the Host according the following algorithm The program waits while the required endpoint is busy after that it starts receiving data from the Host by calling the usb rx data function This function reads data from the FIFO buffer into the current buffer If not all expected data for this transfer not file was sent the rest of the data will be received using an EOP interrupt 4 When usb rx data returns control the writing of data from the second buffer previously received data to the file can be started Thus the actions of receiving the data into current buffer and writing data from the previous buffer into the file are occurring simultaneously A more detailed description is provided below The function then enters the loop waiting until the required BULK OUT endpoint becomes free Following this it calls the usb rx data function to start receiving the file if int32 flength pos size transfer length size transfer length else size flength pos size usb_rx_data BULK_OUT bufptr size M Appendix 1 File Transfer Application 9 13 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc bufptr points to the current intermediate buffer while size c
88. n 7 17 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 18 usb rx data Call s uint32 usb rx data uint32 epnum uint8 start uint32 length Arguments Table 7 14 usb_rx_data arguments epnum in Number of endpoint through which data will be received from Host start inout Pointer to buffer where Driver will place received data from Host length in Number of bytes to receive Description This function initializes the ep epnum buffer structure with values start and length It then copies the contents of the FIFO buffer for endpoint epnum to the destination buffer pointed to by start If all the expected data was sent it clears the ep epnum buffer structure Assembler version is also provided Returns Table 7 15 usb_rx_data returned values USB_DEVICE_RESET Device is reset USB EP IS BUSY Endpoint is busy USB COMMAND FAIL Parameters passed to function are not properly initialized or given endpoint is not ready to receive new data USB COMMAND SUCCESS The function completed successfully Code example usb rx data BULK OUT bufptr size M USB Device Driver Function Specification 7 18 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 19 usb rx frame Implemented in CBI amp Isochronous
89. n SRAM memory with 100 next 160 bytes with 101 value etc Code example buffer init2 M Appendix 2 Audio Application 10 14 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 3 get string descriptor Call s uint32 get string descriptor uint8 desc index uint16 languageID uint16 length Arguments Table 10 1 get string descriptor arguments desc index in Index of required descriptor languageID in Language ID length in Number of bytes to send Description This function sends string descriptor to Host having given index and written on a language having given ID Returns Function returns status Status NOT SUPPORTED COMMAND means that program does not support requested descriptor Status SUCCESS indicates that required descriptor was sent to Host Code example if dc gt request bmRequestType 0x80 amp amp dc gt request bRequest GET DESCRIPTOR amp amp dc gt request wValue gt gt 8 STRING status get string descriptor dc gt request wValue amp OxFF dc gt request wIndex dc 2request wLength return status M Appendix 2 Audio Application 10 15 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 4 init test structures
90. n This Product Go to www freescale com Freescale Semiconductor Inc 10 Appendix 2 Audio Application 10 1 Introduction This appendix describes a Device side USB Audio Application This program is used only for demonstration purposes It illustrates some useful techniques see section 1 2 and gives an example of working with the USB Device Driver 10 1 1 Important Notes The Client application does not support any standard class i e USB Audio class etc A simple vendor specific command set was designed and used to demonstrate Isochronous IN OUT data transfer and acceptng execution of commands from the Host simultaneously with transfers Also this program demonstrates the behavior of the Device side USB Driver when the Host s w does not work in real time while performing the test transfers misses frames 10 1 2 Capabilities of Audio Application The Audio application receives 16 bit mono PCM samples from the Host with 8 kHz and 44 1 kHz rates reduces their amplitude the multiplication factor is set by the Host using a command and sends processed data back to the Host In addition the Client program performs test transfers IN OUT and simultaneously IN and OUT both when the Host software works in normal mode and when the Host emulates real time failure Some useful techniques are highlighted below which the program utilizes during file transfers e Simultaneous data transfer on IN and OUT endpoints wit
91. n any case the program may synthesize the required amount of samples and output them to the headphones in the required time M Isochronous Data Transfer 4 9 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc If the Client application requests the Driver to perform transfer monitoring it must first call the usb set start frame number function The Driver starts analyzing the transfer from a given frame the number of which was passed as a parameter to that function It must be the number of the frame in which the first data packet has to be received from the Host All the transfers after this frame will be monitored When the last transfer is completed data monitoring must be stopped in order to correctly start a new one or to properly continue data transfer without monitoring In order to stop monitoring the Client program must call the usb set final frame number function passing the number of the frame in which data monitoring must be stopped This must be done in the frame following the one in which the last data packet has to be sent by the Host or at least not earlier The SOF interrupt handler of the next frame checks missed EOP interrupt in the previous frame In such a case the Driver can properly handle the situation when the last packet was not received by the Device The Driver monitors Host s w activity only in the READ F
92. n copies length bytes from a file having index fnum to the buffer pointed by the dest parameter A reading from file starts from position Offset Assembler version is also provided Returns Number of read bytes Code example Copy next portion of data from file into the buffer size read file fpos bufptr transfer length pos M Appendix 1 File Transfer Application 9 28 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 10 write file Call s uint32 write file uint32 fnum uint8 dest int32 length int32 position Arguments Table 9 18 write file arguments fnum in Index of file in which data must be written dest inout Pointer to buffer from where data must be read length in Number of bytes to be written position in Offset in a given file It is a position in a file from which function must start placing the data in it Description Returns This function copies length bytes from the buffer pointed by dest parameter to a file having index fnum A writing to file starts from position Offset Assembler version is also provided Number of written bytes Code example Write data from previous buffer into the file write file fpos bufptr buf size pos Appendix 1 File Transfer Application 9 29 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information O
93. nd of transfer if the descriptor is shorter than the length parameter or only the initial bytes of the descriptor if it is longer This function finds the array index variable i is used of the desired language ID for non zero indexed string language ID 0x409 has index zero in a string with index zero language ID 0x407 has index 1 in that string It reorders bytes in the languageID parameter to prepare it for comparison since IDs in the array are stored with reversed byte order If the string descriptor with the required index or given language ID is not supported the function returns NOT SUPPORTED COMMAND value usb accept command function returns this value to the Driver and the Driver completes the corresponding request Otherwise it starts to prepare data for Host If the desc index parameter is zero the Driver returns a string descriptor that contains an array of two byte LANGID codes supported by the Device regardless of the languageID parameter This string descriptor has index zero in the array Otherwise the string with the appropriate index and language ID will be found The get string descriptor function points the stdesc variable to the required descriptor if desc index M Appendix 1 File Transfer Application 9 17 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc i NUM STRING DESC i desc index stdesc u
94. ndpoint on which data will be transferred start pointer to data buffer that will be transferred length number of bytes to transfer transfer length This function initializes the fields of global structure ep buffer It sets the field ep epnum buffer start to the beginning of the data buffer to be sent ep epnum buffer length to the length of buffer and ep epnum buffer position to 0 no data sent yet Then it determines the number of bytes that can be placed into the FIFO buffer and copies that amount of data from the source buffer to the FIFO After that it modifies ep epnum buffer position field ep epnum buffer position will be set to the number of bytes written usb tx data then returns control For more detailed information about usb tx data refer to Chapter 3 1 1 The USB module sends that data to the Host in packets If the Host successfully receives a packet it sends an acknowledge to the Device Following this the USB module generates EOP end of packet interrupt Using this interrupt a new portion of data can be placed into the FIFO buffer The usb in service handler is used for this purpose usb in service checks if there is any data to send examines ep epnum buffer position and ep epnum buffer length If there is data to be sent it determines the amount of data that can be placed into the FIFO buffer Then usb in service copies that amount of data to the FIFO buffer and increases t
95. nsfer 3 4 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Is endpoint halted Save the current IMR Disable EOP EOT RESET DEV CFG interrupts structure Determine number of bytes to Set up EP buffer place into FIFO Place data to FIFO buffer Modify position Is it all the data to be sent Complete transfer Restore saved IMR Fig 3 2 Algorithm of usb tx data function usb tx data accepts three parameters see Chapter 3 1 Firstly it checks whether the Device has been reset for data transfers on non zero endpoint For endpoint number zero M Control Bulk Interrupt Data Transfer 3 5 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc transfers are permitted even if the Device is not configured Then it checks that the epnum parameter does not exceed the maximum number of endpoints 7 Then usb tx data tests whether the given endpoint is busy See if the EP is currently busy if ep epnum buffer start epnum amp amp MCF5272 RD USB EPDPR imm epnum return 1 It checks the ep epnum buffer start field it should not point to any buffer and checks that the FIFO buffer is empty for non zero endpoints because EPODPR monitors OUT F
96. o it The reset event handler clears the ep epnum buffer structure for all endpoints sets the state of each endpoint to USB DEVICE RESET and deletes a command if Newc variable points to it It then calls the usb reset notice function to notify the Client application about the reset event This function is defined by the Driver but it must be implemented in the Client application The Client program may delete it s queue reset structures variables or do some other Client specific work A reset event may occur at any time during execution of usb tx data usb rx data usb in service Of usb out service To ensure each routine will be completed properly RESET interrupt must be disabled before starting to work with buffers and restored after data copying is completed Otherwise the RESET event handler may be called during data copying In this case it clears the pointer to an intermediate buffer and then the interrupted function will read write from to zero address The reset event handler clears the ep epnum buf fer structure for i 0 i lt NUM ENDPOINTS i ep i buffer start 0 ep i buffer length 0 ep i buffer position 0 ep i state USB DEVICE RESET The global structure must be set up to its default value no buffers allocated This prevents usb in service and usb out service from copying data a way to terminate transfers that are in progress The reset event handler sets the
97. o receive data from the Host The USB Audio Device implements four alternate settings Alternate setting 0 no bandwidth Alternate setting 1 packet size of Isochronous IN OUT endpoints is 16 bytes Alternate setting 2 packet size of Isochronous IN OUT endpoints is 90 bytes Alternate setting 3 packet size of Isochronous IN OUT endpoints is 160 bytes 10 2 2 Initializing the Driver To start working with the Driver the Client application must first initialize it Before calling the usb init function which initializes the Driver the Client application needs to fill the DEsc_InFo structure defined in the usb n file extern USB DEVICE DESC Descriptors DESC INFO Device desc Device desc pDescriptor uint8 amp Descriptors Device desc DescSize usb get desc size The variable Descriptors is allocated in the usb audio desc c file The Client application then initializes the Driver usb init amp Device desc M Appendix 2 Audio Application 10 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 2 3 Program Execution Flow The Client program consists of two important parts usb accept command function and main function The Driver defines the prototype of the usb accept command function and requires the Client program to implement it The Driver calls this function every time it receives a command
98. of command block argl gt cbuffer is a pointer to command block Returns Function must return status to Driver that indicates either that the Client program accepts a command or not If the usb accept command function returns SUCCESS zero value it means that the Client accepts a command For any other non zero value the Driver considers as an error and sends a STALL response to the Host in the status stage of command transfer Description The Driver calls this function when it completes receiving a command from the Host The Client application must determine if it either supports a command or not and return the corresponding status to the Driver as soon as possible The Client program may execute a command immediately or put the command to the Queue for later execution M Application Specific Function Prototypes 8 2 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 8 2 usb devcfg notice Call s void usb devcfg notice uint32 arg1 uint32 arg2 Arguments arg number of configuration arg2 number of interface alternate setting arg contains configuration number set by the Host arg2 parameter contains interface number and number of alternate setting for every active interface In fact the Driver passes the contents of the ASR register in this parameter For detailed description of this register refer to 2 Re
99. om Freescale Semiconductor Inc If the Client program accepts a command status is equal to zero it may answer with data immediately call usb tx data 0 function from the usb accept command function endpoint number zero is now free or put it into the Queue for later execution In any case the Client application must call the usb tx data function passing 0 into its first parameter endpoint number zero to transfer data upon request Also the Client program must do it as soon as possible the time for sending a command in the data stage from Device to Host is limited by the USB 1 1 specification Sending data will invoke the calling the usb in service function which completes command transfer if epnum 0 amp amp ep epnum buffer start amp amp NewC usb_vendreq_done SUCCESS A user notification is provided about completion of the command transfer started by usb tx data 0 by calling the usb ep tx done function 5 4 No data request handling If there is no data stage in a request the Driver allocates memory for DEVICE COMMAND structure only Direction of data transfer is from Device to Host or no data stage NewC DEVICE COMMAND malloc sizeof DEVICE COMMAND If the Driver is unable to allocate memory it sends a STALL response to the Host by calling usb vendreq done function if NewC NULL usb vendreq done MALLOC ERROR After allocating memory
100. on if ep epnum ttype ISOCHRONOUS amp amp ep epnum buffer start 0 Ll iso ep epnum state MISS PACKET Clear FIFO buffer MCF5272 WR USB EPCFG imm epnum MCF5272 RD USB EPCFG imm epnum X fifo data f 0 amp amp iso ep epnum transfer monitoring started TRUE iso ep epnum status MISSED PACKET if event amp MCF5272 USB EPNISR FIFO LVL iso ep epnum state MISS PACKET if event amp MCF5272 USB EPNISR EOP iso ep epnum state DEFAULT read permitted FALSE If a FIFO level interrupt occurs the Driver clears the FIFO buffer and sets the state field to MISS PACKET This done where the Client program may call the usb rx xxxx function before FIFO level end EOP interrupts In the case of the RzAD FRAMES mode the function cannot receive only half of packet Moreover the first sample in the FIFO buffer can be damaged after previous clearing Thus the whole packet must be read out Before assigning a MISSED PACKET value to status fifo data it must first be tested to ensure it is not equal to zero In the case of the READ_DATA mode the following situation can happen The FIFO module accepts data from the USB and generates a FIFO level interrupt Assuming that one or two bytes remain to receive the whole packet Until the Driver reaches the place where it determines the number of bytes in the FIFO buffer the FIFO module receives the rest of bytes EOP is masked by the hardw
101. on This function initializes reinitializes the FIFO buffer for a given endpoint It causes the loss of data if they are in the FIFO buffer for a selected endpoint only Returns No value returns Code example usb ep fifo init 1 M USB Device Driver Function Specification 7 5 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 6 usb ep is busy Call s uint32 usb ep is busy uint32 epnum Arguments Table 7 4 usb ep is busy arguments epnum in Number of tested endpoint for being busy Description This function tests an endpoint for being busy The endpoint is still being busy while a non zero value is assigned to ep epnum buffer start field Returns Table 7 5 usb ep is busy returned values USB DEVICE RESET Device is reset USB EP IS BUSY Endpoint is busy USB EP IS FREE Endpoint is free Code example uint32 ep status ep status usb ep is busy 1 if ep status USB EP IS FREE Endpoint is free New transfer can be started M USB Device Driver Function Specification 7 6 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 7 usb ep stall Call s void usb ep stall uint32 epnum Arguments Table 7 6 usb ep stall arguments epnum in Number of endpoint to be halted
102. ontains the amount of bytes to be received Then the buffers change places Change pointer to previous buffer if bufptr bufferl bufptr buffer2 else bufptr bufferl Now the EOP interrupt handler copies the data to the first buffer and data from the second buffer pointed now by bu ptr can be written to the file Write data from previous buffer into the file write file fpos bufptr buf size pos The bu size variable contains the number of bytes written to the previous buffer while size is a number of bytes to be written into the current buffer pos in an offset position where to start to write a new portion of data Then pos is increased by buf size and the size value is stored into the bu size variable The same operations but with new buffers will be performed on a new iteration of the loop if all the expected data was not received The Device reset variable is tested for TRUE value If a port reset occurred on a Device the program finishes all operations and returns control to the main function 9 3 3 3 UFTP GET FILE INFO command execution To begin with the UFTP GET FILE INFO command handler tries to find a given file following which it sends status to the Host If the status sent was UFTP SUCCESS the program sorts bytes of file length in reversed order PC Host will read it as DWORD Then it sends the value obtained to the Host on a BULK IN endpoint 9 3 3 4 UFTP GET DIR
103. or OUT transfers alike for IN the following is true 1 Isochronous packets are guaranteed to occur once per USB frame and they are never resent 2 Isochronous endpoints support packet sizes up to 1023 bytes Which means that the FIFO size can be less than twice the packet size Thus during packet reception a FIFO level interrupt can occur Using this interrupt the Driver reads the initial bytes of a packet Then using the FIFO level interrupt again or EOP interrupt it reads the rest of the packet Data on isochronous endpoints is generally streaming data So it can be assumed that all such transfers on each isochronous endpoint belongs to a corresponding stream that was started much earlier and will never finish When data arrives at a USB module the FIFO level or and EOP interrupts occur At this moment the Client program should allocate a buffer for data by calling the usb xx data or usb rx frame function The USB Driver operates using two different methods for isochronous OUT transfer 1 The first is similar to CBI transfers As for this method the Client application must call usb rx data The Driver does not return control until all the data is received But this method of reading is not synchronized with USB timing Thus using this method READ DATA2 the Client program may have a problem to determine the USB data rate 2 The second method READ FRAMES is synchronized with the USB clock In this mode the Client progr
104. or given endpoint the Driver starts to read data from the FIFO buffer four bytes at a time while this is possible and the rest of data one byte at a time M Control Bulk Interrupt Data Transfer 3 17 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Does EOP no interrupt occured yes Disable RESET and DEV_CFG interrupts save current IMR Determine the amount of data in FIFO buffer condition is occurred Terminate transfer if overflow Is buffer allocated fo no given endpoint Read data from FIFO buffer yes Is it all the data to be received Finish transfer Fig 3 6 Algorithm of usb out service function Control Bulk Interrupt Data Transfer PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 3 18 Freescale Semiconductor Inc Control Bulk Interrupt Data Transfer PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 3 19 Freescale Semiconductor Inc 3 2 3 Completion of the Data OUT Transfer For OUT transfers both functions usb rx data and usb out service may complete the transfer If usb rx data reads all the required data from the FIFO buffer it clears the ep epnum buffer structure beca
105. owards terminology must be made Isochronous data IN stream means uninterruptible sending of data to the Host It includes an infinite while Device is powered number of calls to the usb tx data function Sending a buffer passed to each usb tx data is a transfer Each transfer consists of limited number of packets the last packet may be short in order to setup the required sample rate Data on isochronous endpoints is generally streaming data Therefore it can be assumed that all transfers on each isochronous endpoint belong to corresponding stream that was started much earlier on and never finishes To start write to the stream the Client program must call the usb tx data function every time it wants to transfer a data buffer This function initializes the ep epnum buffer structure and places data to the FIFO buffer When this function returns control to the Client program no data is sent yet the earliest an IN token can be received is in the next frame hence the first packet will only be sent in the next frame The mechanism of sending a data buffer with an isochronous endpoint is mostly similar to CBI transfers but there are some distinctions 1 Data is sent in packets which is also common with CBI However isochronous packets are guaranteed to be sent once per USB frame and they are never resent 2 Isochronous endpoints support packet sizes up to 1023 bytes Which means that the FIFO size can be less than twice
106. p OxFFFF uint16 MCF5272 RD USB DRR2 imm gt gt 16 M USB Device Driver Function Specification 7 26 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 8 Application Specific Function Prototypes This chapter provides a specification of the functions that must be implemented in the Client application The Driver assumes that the Client program implements these functions according the given specification and calls them at the appropriate times All function arguments for each routine are described as in meaning that the parameter value is an input only to the function The Driver does not define names of function arguments This specification uses arg1 arg2 etc names for convenience M Application Specific Function Prototypes 8 1 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 8 1 usb accept command Call s uint32 usb accept command DEVICE COMMAND argl Arguments argl is a pointer to command Client program may extract some useful parameters using following fields Bit number 7 of argl gt requestbmRequestType field determines the data transfer direction if bit 7 is set the direction is from Device to Host if bit 7 is cleared from Host to Device argl gt request wLength field contains the length
107. p an interrupt priority level for each endpoint by initializing the corresponding Interrupt Control Registers MCF5272 WR SIM ICR2 imm 0 0x00008888 USB EPO LEVEL lt lt 12 USB EP1 LEVEL lt lt 8 USB EP2 LEVEL 4 USB EP3 LEVEL 0 MCF5272 WR SIM ICR3 imm 0 0x88880000 USB EP4 LEVEL 28 USB EP5 LEVEL 24 USB EP6 LEVEL 20 USB EP7 LEVEL 16 usb init then enables the USB controller and Configuration RAM MCF5272 WR USB EPOCTL imm O0 MCF5272 USB EPOCTL USB EN MCF5272 USB EPOCTL CFG RAM VAL M Driver Initialization 2 5 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Now transfers are permitted for endpoint number zero only To enable other endpoints the Host must first set up the configuration M Driver Initialization 2 6 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 3 Control Bulk Interrupt Data Transfer This chapter describes how the Driver supports Control Bulk and Interrupt transfer types describing how to initiate a transfer and how complete it correctly 3 1 Device to Host Data Transfer To transfer data from the Device to the Host the usb tx data function must be called It accepts three parameters epnum number of e
108. p epnum buffer position will be set to the number of copied bytes usb rx data returns control For more detailed information about usb rx data refer to Chapter 3 2 1 The Host sends data in packets If the USB module successfully receives a packet it generates EOP end of packet interrupt Using this interrupt a new portion of data can be read from the FIFO buffer The usb out service handler is used for this purpose It determines the amount of data in the FIFO buffer and copies the data to a destination buffer ep epnum buffer start points to it For more detailed information about usb out service refer to Section 3 2 2 M Control Bulk Interrupt Data Transfer 3 12 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Initial state ep epnum buffer start 0 ep epnum buffer position 0 ep epnum buffer length 0 Call to usb_rx_dataQ ep epnum buffer start ep epnum buffer start ep epnum buffer position 0 ep epnum buffer length y Destination Data Buffer empty usb rx data reads data from FIFO buffer ep epnum buffer start ep epnum buffer start ep epnum buffer start ep epnum buffer position ep epnum buffer length y Data already Free space placed from FIFO EOP interrupt occurred usb out service is called and reads from FIFO ep epnum buffer start ep epnum bu
109. pace for the rest of the endpoints can be calculated by subtracting the amount of data in the FIFO buffer from the length of the FIFO buffer for that endpoint if epnum 0 free_space ep 0 packet_size else free_space uint16 ep epnum fifo length MCF5272 RD USB EPDPR imm epnum If the amount of data to be sent is less than the free space in the FIFO buffer variable free space must be modified if free space length p epnum buffer position free space length p epnum buffer position Then usb in service writes data to the FIFO four bytes at a time while it is possible and the rest of data one byte at a time It increases the position field by the number of written bytes If this is all the data to be sent usb in service completes the transfer The saved interrupt mask register must be restored Finally usb in service tests event for EOT interrupt If the interrupt occurred the function completes the transfer refer to Chapter 3 1 3 M Control Bulk Interrupt Data Transfer 3 7 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Does EOP interrupt occur Disable RESET and DEV_CFG interrupts save current IMR Is there data to no send Determine amount of data that can be placed to FIFO Place data to FIFO Is it all the data to be sent
110. perly start and stop an IN OUT isochronous data stream It also performs monitoring of the Host s w and the Device side Client application to determine if they are working in real time Returns No value returns Code example if event amp MCF5272_USB_EPOISR_SOF Clear this interrupt bit MCF5272_WR_USB_EPOISR imm MCF5272_USB_EPOISR_SOF usb isochronous transfer service M USB Device Driver Function Specification 7 14 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 15 usb isr init Call s void usb isr init void Arguments No arguments Description This function initializes interrupts for the USB module Returns No value returns Code example usb isr init M USB Device Driver Function Specification PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 7 15 7 16 Call s Freescale Semiconductor Inc usb make power of two void usb make power of two uint32 size Arguments Table 7 12 usb make power of two arguments size inout Pointer to the value that must be power of two Description Returns This function makes a power of two of the value pointed by the size parameter If the pointed value is not a power of two the function increases it to the nearest available power of two If the result
111. ptor to Host essent 10 10 10 3 USB Audio Application Function Specification seeeeeese 10 13 WO Shee buff er mit Tos ooi actis sii uma tuna Shea Melee MM DEED D iar DUI UE 10 13 10 5 2 puffer mitt2 uoce tre ee ro e ee e resort SEE eue 10 14 LOSS Bet SINS JescEIDEOE ode ra served ap ene e t ia 10 15 10 3 4 init test structures cccccccccccccceceeeessnsecececeeeceessssesecececcesenensnseaeeeeeeseeenes 10 16 I0 3 5 main 3sK a e oce n Gen ENTRO IR ISI PUE ER 10 17 10 3 6 print buffer contents cei Eee erasa eR ERU een cea e eae NU PR Ee ed eR tens 10 18 10 37 sprint transfer status cose n e aaa eae erae diee d ester de oe eei tua Edad 10 19 103 8 process Sat ails atin need dg cai dads e EO ed Bg dtd ous ee Cues 10 20 10 3 9 stest caset handler 45 ec eoe eii T ED USE 10 21 10 3 10 test case2 handle 3 tette etico ivo dide niens 10 22 10 3 11 test case3 handler dete iecit e eS 10 23 M V PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc ILLUSTRATIONS Figure Title Page Figure 3 1 Data Transfer Stages by the Driver seesseeeeeneeenreren 3 3 Fig 3 2 Algorithm of usb tx data function sse 3 5 Fig 3 3 Algorithm of usb in service function esee 3 8 Fig 3 4 Stages of receiving data by the Driver ss
112. r If the Client application must supply data with a varying adaptive rate it may call usb tx data passing a buffer to it that contains only one short packet the length of which may vary from one transfer to the next 2 If usb tx data is called in the current frame data placed in FIFO buffer can be sent to the Host not earlier than in the next frame This function can be called only after occurrences of the SOF interrupt And delay between SOF interrupt and receipt of an IN token is less than the time needed for calling usb tx data and reaching the point in this function in which it starts placing data to the FIFO buffer 4 2 Monitoring Host Software During IN Transfers There is a wide class of audio Devices which steadily produce source Devices a fixed amount of data Devices such as a microphone serve as an excellent example The ADC of a microphone produces a fixed amount of samples per some period of time Hence the Device has to send all of this data during a given time period or at least the buffer must be freed by the end of that period Assuming the example that the Device tries to send a buffer of 5 packets to the Host The buffer must be freed after 5 milliseconds since the ADC produces new data for the next 5 packets that must be sent during the next 5 milliseconds If Host does not issue IN tokens because of problems with real time which can arise sometimes for example the transfer buffer will require more t
113. rd 9 0 9 3 3 1 UFTP READ command execution esee netten eene enne nnne 9 9 9 3 3 2 UFTP WRITE command execution esee enne nnne nnnenenne nnne tente tentes nnn n 9 12 9 3 3 3 UFTP GET FILE INFO command execution sese nennen 9 14 9 3 3 4 UFTP GET DIR command execution eese eene nnne nnne nenne nennen nennen 9 14 9 3 3 5 UFTP_SET_TRANSFER_LENGTH command execution esses 9 15 9 3 3 6 UFTP DELETE command execution eene tte 9 15 9 3 3 7 Request for string descriptor handling essent 9 15 9 4 USB File Transfer Application Function Specification usus 9 18 9 4 1 d command deletes osse maia sad edt casa vee omen ve UD S ud 9 20 9 4 2 d command get dir d0escotasq di sena enia tescatade aa ea uA DM senan 9 2 9 4 3 do command et TE THEO o oi oes ecran S Teig etd PES PERUENIRE EE gR 9 22 9 4 4 do command fead S 9 23 9 4 5 do_command_set_transfer_length sseesssessesesesesseeesseessessersseessseesssees 9 24 9 4 6 docommand 2 SV TUBS us do ead sua said sind aks ca a eau a 9 25 9 4 7 Tetchi cominand ases od trece SI S REIR RUR ats doses ea Uie Pr ace andes 9 26 9 4 8 get strina deSCEIDIOL scite qeu aa suena UR OR ETRAS BR RUPEE TRUE ioii 9 27 9 4 0 read che oos catia ace dat e atotetu id osos pans da t oed etas tenis nea e e Mtaf nes 9 28 PAETOS VIALS TUG etc tSt pne mat EE o cd dra 9 29 10
114. rn USB DEVICE DESC Descriptors DESC INFO Device desc Device desc pDescriptor uint8 amp Descriptors Device desc DescSize usb get desc size The variable Descriptors is allocated in the cbi_desc c file M Appendix 1 File Transfer Application 9 8 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Following this action the Client application initializes the Driver usb init amp Device desc 9 3 3 Program Execution The Client program consists of two important parts usb accept command function and the main function The usb accept command is called by the Driver every time the Driver receives a command from the Host If it is a request for a string descriptor the Client executes that request immediately refer to Chapter 3 3 7 If the Client program does not support the received command it returns NOT SUPPORTED COMMAND non zero value to the Driver Otherwise the Client application puts a command into the Queue and returns a SUCCESS zero value to the Driver In the main function the Client program calls the etch command routine passing the address of the buffer to get a new command fetch next command from the Queue If the Queue was not empty fetch command returned COMMAND SUCCESS the program finds the appropriate handler for that command using switch operator and calls it In
115. rst 9 2 3 4 UFTP_GET_DIR command 04h The Host sends the UFTP_GET_DIR command to receive the names of all files held on a given Device Table 9 5 UFTP_GET_DIR command Byte Description of value 0 Operation code 04h The command has no parameters UFTP_GET_DIR data Upon receiving this command the Device sends status to the Host and if that status was UFTP_SUCCESS it sends two buffers to the Host The first buffer contains information about the directory length of the buffer that holds the list of files length of second buffer and the number of files Table 9 6 Buffer containing information about directory Description of value Length of buffer that contains list of files Number of files The second buffer contains a list of files M Appendix 1 File Transfer Application 9 5 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Table 9 7 Buffer containing list of files Description of value Length of filel name Name of file1 not NULL terminated string length_of_filel_name length of filel name Length of file2 name length of filel name Name of file2 not NULL terminated string length of file2 name 1 9 2 3 5 UFTP SET TRANSFER LENGTH command 05h The Host sends the UFTP SET TRANSFER LENGTH command to set the length of transfer Table 9 8 UFTP SET TRA
116. s Table 9 16 get string descriptor arguments desc index in Index of required descriptor languageID in Language ID Length in Number of bytes to send Description This function sends string descriptor to Host having given index and written with a language having given ID Returns Function returns status Status NOT SUPPORTED COMMAND means that program does not support required descriptor Status SUCCESS indicates that required descriptor was sent to Host Code example if dc gt request bmRequestType 0x80 amp amp dc gt request bRequest GET DESCRIPTOR amp amp dc gt request wValue gt gt 8 STRING status get string descriptor dc gt request wValue amp OxFF dc gt request wIndex dc 2request wLength return status M Appendix 1 File Transfer Application 9 27 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 9 4 9 read file Call s uint32 read file uint32 fnum uint8 dest int32 length int32 position Arguments Table 9 17 read file arguments Fnum in Index of file from which data must be read Dest inout Pointer to buffer where place read data Length in Number of bytes to be read position in Offset in a given file It is a position in a file from which function must start copying the data Description This functio
117. s information Code example test casel handler M Appendix 2 Audio Application 10 21 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 10 test case2 handler Call s void test case2 handler void Arguments No arguments Returns No value returns Description This function performs 5 test IN transfers by 5 packets prints out sent data and transfers status information Code example test case2 handler M Appendix 2 Audio Application 10 22 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 10 3 11 test case3 handler Call s void test case3 handler void Arguments No arguments Returns No value returns Description This function performs 5 test IN transfers by 5 packets and simultaneously 5 test OUT transfer each takes 5 frames prints out transfers status information Code example test case3 handler M Appendix 2 Audio Application 10 23 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com
118. s not been called yet so usb in service properly handles this situation ep epnum buffer structure is cleared Even if EOPI occurs after the call to usb tx data this situation will be handled properly as well see case 1 If the Host misses only two frames and misses them one after the other it does not receive garbage bytes and the Device does not overstep the third packet this takes place in all cases M Isochronous Data Transfer 4 7 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 4 3 Monitoring the Device side Application During IN Transfers In addition to other functions the Driver monitors whether the Device side Client program is working in real time If the SOF interrupt occurred but no buffer is allocated the Driver sets the appropriate status in usb isochronous transfer service function if ep epnum buffer start 0 iso ep epnum status MISSED FRAME By using this status the Client application may check in the development and debugging stage how fast the transfer is 4 4 Host to Device Data Transfer This subsection describes the concepts of isochronous OUT transfer The following two sections describe how the Driver monitors whether Host software and Device side the Client application are working in real time It also describes how the Driver sustains sample rate if the Host s w misses frames F
119. sb tx data places data to FIFO buffer ep epnum buffer start ep epnum buffer start ep epnum buffer start ep epnum buffer position ep epnum buffer length y Data already Data Buffer to be sent placed to FIFO EOP interrupt occurred usb_in service is_ called and places data to FIFO ep epnum buffer start ep epnum buffer start ep epnum buffer start ep epnum buffer position ep epnum buffer length Sent Data Data already Data Buffer to be sent placed to FIFO EOP interrupt occurred usb_in_service is called and places data to FIFO ep epnum buffer start ep epnum buffer start ep epnum buffer start ep epnum buffer position ep epnum buffer length Sent Data Data already Data Buffer placed to FIFO to be sent Figure 3 1 Data Transfer Stages by the Driver M Control Bulk Interrupt Data Transfer 3 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 3 1 1 Initiating the Data IN Transfer The usb tx data function is used to initiate each data transfer from Device to Host The algorithm of this function is shown in Fig 3 2 yes yes Are transfers allowed for this endpoint no Exit yes yes Exit yes Exit Is there data to send a Exit Is this an no IN endpoint Exit rt M Control Bulk Interrupt Data Tra
120. sececeeececeeeeeeneeeeeneeeeees 3 7 3 1 3 Completion of Data IN Transfer eder ie Sa 3 9 3 1 4 Notifying Client Application about Completion of Data IN Transfer 3 11 3 2 Host 0 Device Data Transfer aui enter rece ie otia eerte 3 12 3 2 1 Initiating the Data OUT Eransfet uunc Dott eae IR Met etes ap Rara 3 14 9 22 Continuation of the Data OUT Transfer esee 3 17 3 2 3 Completion of the Data OUT Transfer eee 3 20 3 2 4 Notifying Client Application about Completion of Data OUT Transfer 3 20 4 Isochronous Data Transtfer eeeeeeeeeeeeeeeeeeeeee nennen 4 1 4 1 Device to Host Data Transfer ue ede die aie 4 4 20 Monitoring Host Software During IN Transfers 4 2 4 3 Monitoring the Device side Application During IN Transfers 4 8 44 Host to Device Data Transfer Loc adios tius aditu eco tupe ct o e Ma Eden 4 8 4 5 Monitoring the Host Software During OUT Transfers s es 4 0 4 6 Monitoring the Device side Application During OUT Transfers 4 11 5 Vendor Request Handling ccceeseeeeeeeeeeeeneeeeeeeeeeeeneeseeneeseeeneeseens 5 1 M ii PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 5 1 Accepting a request from the Host ood e eec poesi Ge 5 1 52 Data QUT request handli g oo te eub oe
121. sfer has no affect upon this The situation may be considered as a limitation but it is done consciously in order not to over complicate the Client application The main purpose is after all demonstration only In the above case the Device must be restarted 9 3 3 5 UFTP SET TRANSFER LENGTH command execution The UFIP SET TRANSFER LENGTH command handler sends UFTP SUCCESS status to the Host indicating that it started to process the command Then it a fetches new length of transfer from the command buffer and assigns it to the transfer length variable This variable is used while transferring a file between Host and Device 9 3 3 6 UFTP DELETE command execution Once execution of this command starts the UFTP DELETE command handler tries to find a given file If the file exists the program deletes it Then the function sends status to the Host 9 3 3 7 Request for string descriptor handling This section provides a memory layout for string descriptors and describes how the Client application sends a given descriptor to the Host 9 3 3 7 1 Memory layout for string descriptors According to the documentation of the USB module the request processor does not handle requests for string descriptors automatically GET_DESCRIPTOR requests for string descriptors are passed as a vendor specific request The string descriptors must be stored in external memory and not in the configuration RAM The memory layout for string descriptors is sho
122. structure Only the first field is common for all commands Operation Code The rest of the fields depend upon the command 9 2 3 1 UFTP READ command 01h The Host sends the UFTP READ command to get a required file from the Device Table 9 2 UFTP READ command Byte Description of value 0 Operation code 01h 1 Length of file name Name of file Sea eee not NULL terminated string The command specifies a file which the Device must send to the Host It has two parameters length of file name and name of file The length of the file name field is used to properly fetch the name of the file from the command The name of a file is not a NULL terminated string M Appendix 1 File Transfer Application 9 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc UFTP READ data Upon receiving this command the Device sends status to the Host and if that status was UFTP SUCCESS sends the contents of given file to the Host on Bulk In endpoint 9 2 3 2 UFTP WRITE command 02h The Host sends the UFTP READ command to send a required file to the Device Table 9 3 UFTP WRITE command Byte Description of value 0 Operation code 02h 1 LSB 2 Length of file 3 4 MSB 5 Length of file name 6 E Name of file length of file name 1 not NULL terminated string The command specifies a file which
123. t data was a multiple of the maximum size of packet an EOP interrupt will occur usb in service completes the transfer in EOP event handler b If all the data is placed in the FIFO buffer but the size of data was not a multiple of the maximum size of packet the last packet short may stay in the FIFO buffer In this case the EPNCTL IN DONE bit must be cleared to send a short packet EOT interrupt will occur usb in service completes the transfer in EOT event handler usb in service checks in the EOP handler if all the data was written to the FIFO If it was usb in service tests if the length of transfer is multiple to maximum size of packet and clears the EPNCTL IN DONE bit to send the last short packet if the length of the buffer is not a multiple of the maximum packet size if ep epnum buffer start amp amp ep epnum buffer position ep epnum buffer length remainder i ep epnum packet size This all of the data to be sent if remainder Q0 remainder 0 amp amp ep epnum sendZLP All don gt Clear the IN DONE bit MCF5272_WR_USB_EPCTL imm epnum MCF5272 RD USB EPCTL imm epnum amp MCF5272 USB EPNCTL IN DONE else if MCF5272 RD USB EPDPR imm epnum 0 if epnum 0 amp amp NewC usb_vendreq done SUCCESS free NewC NewC NULL usb ep tx done epnum SUCCESS i ep epnum buffer start 0 ep epnum buffer l
124. th 0x409 ID following NUM STRING DESC descriptors with 0x407 language ID The position of string descriptors must correspond to the order of language IDs that are contained in the string descriptor having index zero Thus if the first language ID is 0x409 then the first four NUM STRING DESC descriptors having indices 1 2 3 and 4 in the array must be written with a language having ID 0x409 M Appendix 1 File Transfer Application 9 16 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc Then the four descriptors must be written with a language having ID 0x407 Language IDs not required to be sorted Bytes in each Language ID are reverse ordered The variable string desc points to the array containing string descriptors 9 3 3 7 2 Sending the string descriptor to the Host When the usb accept command function is called it tests the request If it is a request for a string descriptor the function calls the get string descriptor routine status get string descriptor dc gt request wValue amp OxFF dc gt request wIndex dc 2request wLength The get string descriptor function accepts three parameters desc index index of string descriptor languageID language ID length number of bytes to send According to the USB 1 1 specification the Driver must send a short or zero length packet to indicate the e
125. the array pointed by list in descending order Returns No value returns Code example Sort the endpoints by FIFO length decending usb sort ep array pIN nIN M USB Device Driver Function Specification 7 23 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 7 24 usb tx data Call s uint32 usb tx data uint32 epnum uint8 start uint32 length Arguments Table 7 22 usb tx data arguments epnum in Number of endpoints through which data will be transferred to Host start inout Pointer to buffer from where Driver will place data to FIFO buffer length in Number of bytes to send Description This function initializes the ep epnum buffer structure with values start and length It also copies the contents of the source buffer to the FIFO buffer Assembler version is also provided Returns Table 7 23 usb tx data returned values USB DEVICE RESET Device is reset USB EP IS BUSY Endpoint is busy USB COMMAND FAIL Parameters passed to function are not properly initialized or given endpoint is not ready to receive new data USB COMMAND SUCCESS The function completed successfully Code example usb tx data INTERRUPT uint8 amp status 2 M USB Device Driver Function Specification 7 24 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to w
126. the data buffer to the Driver for transmitting receiving but not in time Driver receives token but no buffer is allocated the Driver notifies the Client program 1 2 Related files The following files are relevant to Driver usb h Drivers function prototypes global structures definition Driver s constant definitions usb c implementation of Driver s functions e int handlers c interrupt service routines for USB module are called from this file descriptors h types definition for Device configuration interface and endpoint descriptors The Driver requires the following files e alloc c Driver uses dynamic memory allocation so the module containing malloc and free function is needed e printf c in debug mode Driver calls printf function to output debug information e stdlib c Driver calls memcpy function The rest of files in the init group are used to initialize the board and processor 1 3 Quick start Guide To start working with the Driver the Client application must call the usb init function usb init amp Device desc After that is done the Client application may call usb tx data and usb rx data functions to send data to the Host and receive data from the Host respectively usb tx data BULK IN bufptr size usb rx data BULK OUT bufptr size To wait until the transfer is completed the Client program may call the usb ep wait function usb ep wait
127. this case ma11oc will return a 4 byte aligned address or allocated in SRAM a start address of SRAM module is always 4 byte aligned To find the nearest 4 byte aligned address for the second buffer some calculations are necessary The handler calculates the remainder of the division of transfer length the length of each intermediate buffer by 4 Then the function finds the number of bytes which need to be padded padded bytes transfer length amp 0x3 if padded bytes 0 padded bytes 4 padded bytes Thus the address of the second intermediate buffer will be equal to the sum of the transfer length and the number of padded bytes added to the start address of the first buffer buffer2 bufferl transfer length padded bytes However at first the first intermediate buffer pointed by buffer1 must be allocated If the length of the transfer is less than or equal to 2048 bytes and the variable place buffers to sram is TRUE the buffers will be allocated in SRAM module otherwise the memory for these buffers will be allocated dynamically d transfer length lt INT SRAM SIZE gt gt 1 amp amp place buffers to sram TRUE bufferl uint8 mcf5272 rambar else bufferl uint8 malloc 2 transfer length padded_bytes As the next step the handler sends the status to the Host on an interrupt endpoint If there was enough memory for the buffers in the case that it was allocated dynamicall
128. tion In the first instance the UFTP WRITE command handler tries to find a given file If the file does not exist it finds the first free position in the array of pointers to the file If there is no free position in the array it reports an error to the Host on an interrupt endpoint Then it begins to allocate intermediate buffers To transfer a file from Host to Device two intermediate buffers are used a detailed description of their purpose is given below In order to the increase execution speed of the program during file transfers these buffers must both be 4 byte aligned The first buffer is always 4 byte aligned regardless of whether it was dynamically allocated in this case malloc Will return a 4 byte aligned address or allocated in SRAM a start address of SRAM module is always 4 byte aligned To find the nearest 4 byte aligned address for the second buffer some calculations are necessary The handler calculates the remainder of division of the transfer length the length of each intermediate buffer by 4 Then the function finds the number of bytes to be padded padded bytes transfer length amp 0x3 if padded bytes 0 padded bytes 4 padded bytes Thus an address of the second intermediate buffer will be equal to the sum of the transfer length and the number of padded bytes added to the start address of the first buffer buffer2 bufferl transfer length padded bytes However the first intermediat
129. ts frames from the Host When each transfer completes the usb ep rx done function stores the status of the transfer and the amount of bytes received to rx status and rx size arrays correspondingly Also it sets the out transfer finished variable which is being polled in test casel handler When all transfers are completed 25 frames starting from a given frame read test casel handler prints the data received from the Host and prints information status and the amount of received data concerning each transfer 10 2 8 START TEST IN TRANSFER command execution Upon receiving this command the program determines the number of the frames in which test data IN transfers will be started and of the frame in which it will be completed The Device sends the number of the start frame to the Host The Client application calls usb set start frame number and usb set final frame number functions to check the test transfer for missed packets usb accept command then sets the start isotest in stream variable and the main function calls test_case2_handler M Appendix 2 Audio Application 10 7 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc test case2 handler sets the test mode variable the usb ep tx done function must accumulate transfer information during test IN transfers It then clears arrays that will hold transf
130. turns No value returns Description The Driver calls this function when the Host sets a new configuration or interface alternate setting M Application Specific Function Prototypes 8 3 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc 8 3 usb ep halt Call s void usb ep halt uint32 arg1 Arguments arg number of halted endpoint Returns No value returns Description Driver calls this function when endpoint is halted M Application Specific Function Prototypes PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 8 4 Freescale Semiconductor Inc 8 4 usb ep rx done Call s void usb ep rx done uint32 arg1 uint32 arg2 uint32 arg3 Arguments arg1 number of endpoint on which data transfer is completed arg2 status of completed data transfer arg3 number of received bytes Driver passes OVERFLOW ERROR in arg2 parameter if the Host sent more data than the Client application expected if the emount of received data is larger than Client program passes in the length parameter to usb rx data function Otherwise the value of arg2 parameter is equal to SUCCESS Returns No value returns Description Driver calls this function when a Host to Device OUT transfer is completed M Application Specific Function Prototypes 8 5 PREL
131. u eid rein 8 7 Bolo USD reset DOll Ceo ec ete ad te da ede ea uode Mu pau Cre o 8 8 9 Appendix 1 File Transfer Application eeeeseeeeese 9 1 9 REMIS Lore alo Lo RR cn 9 OX Important NOES oco eode E E te d oe dip eeu eee 9 1 9 1 2 Capabilities of File Transfer Application 9 9 1 3 Bel ACA BHO e ondetu ot baise OR Nutt deu Het OMNIS A aes E i e dts 9 2 925 UETP Protocol Descriptio pasena a tune a aar endi eee 9 2 9 2 1 MESES BET EP rM 9 2 9 2 2 Stat s Value o ea e ta ae ai ieaiai 9 3 9 2 3 UFTP Command Descriptions nete eere tette Iesus 9 3 9 2 3 1 UFTP READ command Olh eeeseseseseeeeeenenenenne tnter nnne ener ener 9 3 9 2 3 2 UFTP WRITE command O2h esee nennen nnne nnne enne tntennn sete eres nee 9 4 9 2 3 3 UFIP GET FILE INFO command O3h a nnne nennen nennen 9 4 9 2 3 4 UFTP GET DIR command O4h E 9 5 9 2 3 5 UFTP SET TRANSFER LENGTH command O5h eere 9 6 9 2 3 6 UFTP DELETE command 06h cece cecccscscessescesccsesccssssessscessscsssscsessscsssessscessscsssseses 9 7 9 3 Implementation of File Transfer Application eere 9 8 9 3 1 Implementation of Pile System 1s ces wesesssassacesacdsiensssceaeeceastaneaoeatsalecarenceesdes 9 8 9 3 2 Initializing th Dri Ver iss uices eee n iea ea Ea E ESE K Et 9 8 9 3 3 Program Execute acs vaca redit es om eure A O ede aa i
132. uffer start field which should not point to any buffer Then it makes sure there is a target data buffer examines parameters start and length Finally the function ensures that the desired endpoint is an OUT endpoint and that the endpoint is not halted EOP EOT interrupts should be disabled in order to prevent damage to the ep epnum buffer structure by the usb out service handler RESET and DEV_CFG interrupts must also be disabled in order to properly terminate the transfer usb rx data sets up the ep buffer structure ep epnum buffer start start ep epnum buffer length length ep epnum buffer position 0 Then determines the amount of data in the FIFO buffer Read the Data Present register fifo data MCF5272 RD USB EPDPR imm epnum length parameter amount of data to be received can be less than the amount of data in the FIFO buffer for epnum thus additional modification must be made if fifo data length fifo data length Now usb rx data starts to read data from the FIFO buffer four bytes at a time while this is possible and the rest of data one byte at a time If this is all the data to be received usb rx data finishes the transfer refer to Chapter 3 2 3 The saved interrupt mask register must be restored The function returns control M Control Bulk Interrupt Data Transfer 3 16 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to
133. usb 3sochrono s transfer Service seio catesise este ie eet ttv dest 7 14 7 15 DEI NL IMPi MN T TCR 7 15 7 16 sb make power of DWOS s cesi phis odi e id pa decade haa 7 16 7 17 USB OUt SEVICE e A A E E E sce EEEa 7 17 7 18 sb rx data oie ritas ed AE aa a aasa dai cete ipe Eua 7 18 7 19 USDA TANG eS oe ee eee tuat ve E AAE ea EA 7 19 7 20 usb Send LP sce Racer somete qaae dete eat a Kidd des 7 20 7 21 usb set final frames number iue qnte ER Uere aeta 7 21 PDE usb set start frame MUM Detect Qa ee istituti meat tats ine 7 22 7 23 TIS De SOLL 8 D attayna destes egenus E nest tau n eti ee tea edu dos e aed Oe 7 23 7 24 WS 215s abd sous e tpa ee e neue odes 7 24 7 25 Usb vendret donemone eto drole a EE E E E 7 25 7 26 sb ven dr q SeFYICe ss dettes GRANT REIR ae I CU E COLE PAS a Fo QR ee 7 26 8 Application Specific Function Prototypes uus 8 1 Sale USB accept command xo Eee each Baise ea dod te dias 8 2 8 2 Usb develte NOME usce lide ce b ph eb ipo asit isi ft eesti 8 3 9s MISS sci coset ats stn cates hie tay a ated ati t Meta mise tut ier M t ct 8 4 8 4 usb eporx done ooo ese eo pn ese EEEE UNTER HER DEE SERA 8 5 SO usb epocbo dole see esu sento Re eee EN 8 6 M iii PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc BD AUSECCEDE UBBOLE s Gets oo as cies a O tesi ta suse s
134. use other OUT EOP interrupts may not occur If all the data are received in the EOP handler usb out service checks if the received data is a command if i ep epnum buffer length if epnum 0 amp amp NewC status usb accept command NewC The Driver notifies the Client application about the completion of data transfer and command transfer in different ways Following which it clears the ep epnum buffer structure 3 2 4 Notifying Client Application about Completion of Data OUT Transfer When all expected data is received for data transfers not command the Driver calls the usb ep rx done function The Driver itself defines the prototype of this function but it should be implemented in the Client program to handle completion of transfer in a Client specific manner usb ep rx done must return control as soon as possible and it is not intended to be used to initiate a new data transfer directly by calling the usb rx data function the ep epnum buffer structure is still busy and usb rx data Would return control with an error status under these circumstances The best way to accomplish this is when usb ep rx done is used to change some control and or status variables structures which in turn will be examined in the main program When a whole command is received data stage of command transfer is completed the Driver notifies the Client program by calling the usb accept command funct
135. wn in Fig 5 1 below M Appendix 1 File Transfer Application 9 15 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc String descriptors are stored in an array of descriptors Each element of this array is a structure defined in the cbi n file Definitions for USB String Descriptors define NUM STRING DESC 4 define NUM LANGUAGES 2 typedef struct uint8 bLength uint8 bDescriptorType uint8 bString 256 STR DESC typedef STR DESC USB STRING DESC NUM STRING DESC NUM LANGUAGES 1 string desc NUM STRING DESC NUM STRING DESC a ET os UE N 6 18 54 26 88 18 54 26 88 bLength 3 3 3 3 3 bDescriptorType 0x09 S S S S S S S S 409 language ID 0x04 i i i i i l i 407 language ID 0x07 v r r r k r 1 0x04 1 1 1 1 1 1 1 1 bString 256 n n n n n n n n 8 g g 8 g g g 8 1 2 3 4 1 2 3 4 Strings written on language Strings written on language having 0x409 ID having 0x407 ID Ss m NUM_LANGUAGES Fig 9 1 Memory layout for string descriptors The Client application allocates USB_STRING_DESC NUM_STRING_DESC NUM_LANGUAGES 1 array The first element in the array an element with index zero is a string descriptor that contains an array of two byte LANGID codes supported by the Device 0x409 and 0x407 IDs Next NUM STRING DESC descriptors are string descriptors written using language wi
136. written using a language having ID 0x407 Language IDs are not required to be sorted Bytes in each Language ID are reverse ordered M Appendix 2 Audio Application 10 9 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc string desc NUM STRING DESC NUM STRING DESC 6 18 54 26 88 18 54 26 88 bLength 3 3 3 3 3 3 3 3 3 bDescriptorType 0x09 S S S S S S S S Seer a N S psi Meses Is cee ets Wake es 407 language ID Ox07 Tr r r r r x n n n n n n n n g g g g g g g g 1 2 3 4 1 2 3 4 Strings written onlanguage Strings written on language having 0x409 ID having 0x407 ID M V NUM LANGUAGES Fig 10 1 Memory layout for string descriptors The string desc variable points to the array that contains string descriptors 10 2 10 2 Sending the string descriptor to Host When the usb accept command function is called it tests the request If it is a request for a string descriptor the function calls the get string descriptor routine status get string descriptor dc gt request wValue amp OxFF dc gt request wIndex dc request wLength The get string descriptor function accepts three parameters desc index index of string descriptor languageID language ID length number of bytes to send According to the USB 1 1 specification the Driver must send a short or a
137. ww freescale com 7 25 Call s Freescale Semiconductor Inc usb vendreq done void usb vendreq done uint32 error Arguments Table 7 24 usb vendreq done arguments error in Status of command completion Description Controls the status stage response for vendor and class specific requests This function sets the EPOCTL CMD OVER bit if error is zero and EPOCTL CMD OVER EPOCTL CMD ERR bits if error contains a Returns non zero value No value returns Code example status usb accept command NewC usb_vendreq_done status USB Device Driver Function Specification PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com 7 25 Freescale Semiconductor Inc 7 26 usb vendreq service Call s void usb vendreq service uint8 bmRequestType uint8 bRequest uintl6 wValue uint16 wIndex uint16 wLength Arguments Table 7 25 usb vendreq service arguments Standard request parameters For more information refer to USB 1 1 specification Chapter 9 3 in Description This function receives a request from the Host and allocates memory for the request Returns No value returns Code example usb vendreq service uint8 MCF5272 RD USB DRRi imm amp OxFF uint8 MCF5272 RD USB DRRi imm gt gt 8 uint16 MCF5272 RD USB DRRi imm gt gt 16 uint16 MCF5272 RD USB DRR2 imm am
138. www freescale com Freescale Semiconductor Inc 3 2 2 Continuation of the Data OUT Transfer If the USB module successfully receives a data packet it generates EOP interrupt At this moment there is data in the FIFO buffer Thus reading a new portion of data from the FIFO module will continue the transfer usb out service is responsible for continuation of the transfer Its algorithm is shown in Diagram 3 6 This function accepts two parameters epnum number of endpoint for the interrupt that occurred event the kind of interrupt s that occurred First usb out service tests event for EOP interrupts If that interrupt occurred function saves IMR and disables RESET and DEV_CFG interrupts Then it determines the amount of data in the FIFO buffer Read the Data Present register fifo data MCF5272 RD USB EPDPR imm epnum The function also checks that the overflow condition does not occur If that were to happen then the function would complete the data transfer with an error status This is done to help in debugging the Host software only Normally this event should not occur in practice If data is received on the endpoint but no buffer is allocated the USB module will be accepting the data from the Host while there is free space in the FIFO buffer Following this occurrence data transmission will be stopped until such time as the Client application allocates a target buffer If a buffer is allocated f
139. y not in SRAM module the function starts to send data to the Host The bufptr variable is used to point to the current intermediate buffer The size variable will contain the number of bytes that was copied from the file to the current intermediate buffer read_file function returns this amount Now it is set up to transfer lengthin order to enter the loop M Appendix 1 File Transfer Application 9 10 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc A file is sent to the Host according the following algorithm The handler reads the required portion of the data from the file into the current temporary buffer then waits while the required endpoint is busy Then it starts transferring data to the Host by calling the usb tx data function This function places in the FIFO buffer only the initial 256 bytes and then returns control The rest of the data from this transfer not the file will be sent using an EOP interrupt handler 4 When usb tx data returns control a new portion of data can be copied from the file but now into the second intermediate buffer thus data processing copying of next portion of data and transferring data from the first buffer is occurring in parallel A more detailed description of this is provided below The handler attempts to read transfer lengtn bytes from the file into the intermediate buffer pointed to b
140. y the bufptr variable size read file fpos bufptr transfer length pos The fpos variable contains an index of the file it was found earlier during testing that is provided the required file exists pos is an offset in the file the position of the next data to be read The function returns the number of read bytes from the file If the number of read bytes is less than transfer length it indicates that the end of the file is reached and the function must then complete the operation Then it increments pos for the number of read bytes Before transferring this data to the Host the program must wait until the required endpoint BULK IN becomes free if Device reset usb ep wait BULK IN A transfer is then initiated if Device reset usb tx data BULK IN bufptr size Finally the buffers switch places if bufptr bufferl bufptr buffer2 else bufptr bufferl The same operations but with new buffers will be performed on a new iteration of the loop if the end of file is not reached M Appendix 1 File Transfer Application 9 11 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc The Device reset variable is tested for a TRUE value If port reset occurred on a particular Device in this case the program finishes all operations and returns control to the main function 9 3 3 2 UFTP WRITE command execu
141. zero length packet to indicate the end of transfer if the descriptor is shorter than the length parameter or only the initial bytes of the descriptor if the descriptor is longer M Appendix 2 Audio Application 10 10 PRELIMINARY SUBJECT TO CHANGE WITHOUT NOTICE For More Information On This Product Go to www freescale com Freescale Semiconductor Inc The function finds the index in the array variable i is used of the desired language ID for a non zero indexed string language ID 0x409 has index zero in a string with index zero language ID 0x407 has index in the same string It reorders the bytes in the languageID parameter to prepare it for comparison because IDs in the array are stored in reverse byte order If a string descriptor with the required index or the given language ID is not supported the function returns a NOT SUPPORTED COMMAND value The usb accept command function returns this value to the Driver and the Driver completes the corresponding request In other cases it starts to prepare data for the Host If the desc index parameter is zero the Driver returns a string descriptor that contains an array of two byte LANGID codes supported by the Device regardless of languageID parameter This string descriptor has index zero in the array Otherwise the string with the appropriate index and language ID will be found The get string descriptor function points the stdesc variable to the required descriptor

MCF5272 USB SW Developer Manual. Stand

Contents

Download Pdf Manuals

Related Search

Related Contents