/*********************************************************************

  *

  *                Microchip USB C18 Firmware Version 1.0

  *

  *********************************************************************

  * FileName:        usbctrltrf.c

  * Dependencies:    See INCLUDES section below

  * Processor:       PIC18

  * Compiler:        C18 2.30.01+

  * Company:         Microchip Technology, Inc.

  *

  * Software License Agreement

  *

  * The software supplied herewith by Microchip Technology Incorporated

  * (the “Company”) for its PICmicro® Microcontroller is intended and

  * supplied to you, the Company’s customer, for use solely and

  * exclusively on Microchip PICmicro Microcontroller products. The

  * software is owned by the Company and/or its supplier, and is

  * protected under applicable copyright laws. All rights are reserved.

  * Any use in violation of the foregoing restrictions may subject the

  * user to criminal sanctions under applicable laws, as well as to

  * civil liability for the breach of the terms and conditions of this

  * license.

  *

  * THIS SOFTWARE IS PROVIDED IN AN “AS IS” CONDITION. NO WARRANTIES,

  * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING, BUT NOT LIMITED

  * TO, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A

  * PARTICULAR PURPOSE APPLY TO THIS SOFTWARE. THE COMPANY SHALL NOT,

  * IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL OR

  * CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.

  *

  * Author               Date        Comment

  *~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  * Rawin Rojvanit       11/19/04    Original.

  ********************************************************************/

 /** I N C L U D E S **********************************************************/

 #include <p18cxxx.h>

 #include "typedefs.h"

 #include "usb.h"

 /** V A R I A B L E S ********************************************************/

 #pragma udata

 byte ctrl_trf_state;                // Control Transfer State

 byte ctrl_trf_session_owner;        // Current transfer session owner

 POINTER pSrc;                       // Data source pointer

 POINTER pDst;                       // Data destination pointer

 WORD wCount;                        // Data counter

 /** P R I V A T E  P R O T O T Y P E S ***************************************/

 void USBCtrlTrfSetupHandler(void);

 void USBCtrlTrfOutHandler(void);

 void USBCtrlTrfInHandler(void);

 /** D E C L A R A T I O N S **************************************************/

 #pragma code

 /******************************************************************************

  * Function:        void USBCtrlEPService(void)

  *

  * PreCondition:    USTAT is loaded with a valid endpoint address.

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        USBCtrlEPService checks for three transaction types that

  *                  it knows how to service and services them:

  *                  1. EP0 SETUP

  *                  2. EP0 OUT

  *                  3. EP0 IN

  *                  It ignores all other types (i.e. EP1, EP2, etc.)

  *

  * Note:            None

  *****************************************************************************/

 void USBCtrlEPService(void)

 {   

     if(USTAT == EP00_OUT)

     {

         if(ep0Bo.Stat.PID == SETUP_TOKEN)           // EP0 SETUP

             USBCtrlTrfSetupHandler();

         else                                        // EP0 OUT

             USBCtrlTrfOutHandler();

     }

     else if(USTAT == EP00_IN)                       // EP0 IN

         USBCtrlTrfInHandler();

 }//end USBCtrlEPService

 /******************************************************************************

  * Function:        void USBCtrlTrfSetupHandler(void)

  *

  * PreCondition:    SetupPkt buffer is loaded with valid USB Setup Data

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        This routine is a task dispatcher and has 3 stages.

  *                  1. It initializes the control transfer state machine.

  *                  2. It calls on each of the module that may know how to

  *                     service the Setup Request from the host.

  *                     Module Example: USB9, HID, CDC, MSD, ...

  *                     As new classes are added, ClassReqHandler table in

  *                     usbdsc.c should be updated to call all available

  *                     class handlers.

  *                  3. Once each of the modules has had a chance to check if

  *                     it is responsible for servicing the request, stage 3

  *                     then checks direction of the transfer to determine how

  *                     to prepare EP0 for the control transfer.

  *                     Refer to USBCtrlEPServiceComplete() for more details.

  *

  * Note:            Microchip USB Firmware has three different states for

  *                  the control transfer state machine:

  *                  1. WAIT_SETUP

  *                  2. CTRL_TRF_TX

  *                  3. CTRL_TRF_RX

  *                  Refer to firmware manual to find out how one state

  *                  is transitioned to another.

  *

  *                  A Control Transfer is composed of many USB transactions.

  *                  When transferring data over multiple transactions,

  *                  it is important to keep track of data source, data

  *                  destination, and data count. These three parameters are

  *                  stored in pSrc,pDst, and wCount. A flag is used to

  *                  note if the data source is from ROM or RAM.

  *

  *****************************************************************************/

 void USBCtrlTrfSetupHandler(void)

 {

     byte i;

     /* Stage 1 */

     ctrl_trf_state = WAIT_SETUP;

     ctrl_trf_session_owner = MUID_NULL;     // Set owner to NULL

     wCount._word = 0;

     /* Stage 2 */

     USBCheckStdRequest();                   // See system\usb9\usb9.c

     for(i=0;i < (sizeof(ClassReqHandler)/sizeof(pFunc));i++)

     {

         if(ctrl_trf_session_owner != MUID_NULL)break;

         ClassReqHandler[i]();               // See autofiles\usbdsc.c

     }//end while

     /* Stage 3 */

     USBCtrlEPServiceComplete();

 }//end USBCtrlTrfSetupHandler

 /******************************************************************************

  * Function:        void USBCtrlTrfOutHandler(void)

  *

  * PreCondition:    None

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        This routine handles an OUT transaction according to

  *                  which control transfer state is currently active.

  *

  * Note:            Note that if the the control transfer was from

  *                  host to device, the session owner should be notified

  *                  at the end of each OUT transaction to service the

  *                  received data.

  *

  *****************************************************************************/

 void USBCtrlTrfOutHandler(void)

 {

     if(ctrl_trf_state == CTRL_TRF_RX)

     {

         USBCtrlTrfRxService();

         /*

          * Don't have to worry about overwriting _KEEP bit

          * because if _KEEP was set, TRNIF would not have been

          * generated in the first place.

          */

         if(ep0Bo.Stat.DTS == 0)

             ep0Bo.Stat._byte = _USIE|_DAT1|_DTSEN;

         else

             ep0Bo.Stat._byte = _USIE|_DAT0|_DTSEN;

     }

     else    // CTRL_TRF_TX

         USBPrepareForNextSetupTrf();

 }//end USBCtrlTrfOutHandler

 /******************************************************************************

  * Function:        void USBCtrlTrfInHandler(void)

  *

  * PreCondition:    None

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        This routine handles an IN transaction according to

  *                  which control transfer state is currently active.

  *

  *

  * Note:            A Set Address Request must not change the acutal address

  *                  of the device until the completion of the control

  *                  transfer. The end of the control transfer for Set Address

  *                  Request is an IN transaction. Therefore it is necessary

  *                  to service this unique situation when the condition is

  *                  right. Macro mUSBCheckAdrPendingState is defined in

  *                  usb9.h and its function is to specifically service this

  *                  event.

  *****************************************************************************/

 void USBCtrlTrfInHandler(void)

 {

     mUSBCheckAdrPendingState();         // Must check if in ADR_PENDING_STATE

     if(ctrl_trf_state == CTRL_TRF_TX)

     {

         USBCtrlTrfTxService();

         if(ep0Bi.Stat.DTS == 0)

             ep0Bi.Stat._byte = _USIE|_DAT1|_DTSEN;

         else

             ep0Bi.Stat._byte = _USIE|_DAT0|_DTSEN;

     }

     else // CTRL_TRF_RX

         USBPrepareForNextSetupTrf();

 }//end USBCtrlTrfInHandler

 /******************************************************************************

  * Function:        void USBCtrlTrfTxService(void)

  *

  * PreCondition:    pSrc, wCount, and usb_stat.ctrl_trf_mem are setup properly.

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        This routine should be called from only two places.

  *                  One from USBCtrlEPServiceComplete() and one from

  *                  USBCtrlTrfInHandler(). It takes care of managing a

  *                  transfer over multiple USB transactions.

  *

  * Note:            This routine works with isochronous endpoint larger than

  *                  256 bytes and is shown here as an example of how to deal

  *                  with BC9 and BC8. In reality, a control endpoint can never

  *                  be larger than 64 bytes.

  *****************************************************************************/

 void USBCtrlTrfTxService(void)

 {    

     WORD byte_to_send;

     /*

      * First, have to figure out how many byte of data to send.

      */

     if(wCount._word < EP0_BUFF_SIZE)

         byte_to_send._word = wCount._word;

     else

         byte_to_send._word = EP0_BUFF_SIZE;

     /*

      * Next, load the number of bytes to send to BC9..0 in buffer descriptor

      */

     ep0Bi.Stat.BC9 = 0;

     ep0Bi.Stat.BC8 = 0;

     ep0Bi.Stat._byte |= MSB(byte_to_send);

     ep0Bi.Cnt = LSB(byte_to_send);

     /*

      * Subtract the number of bytes just about to be sent from the total.

      */

     wCount._word = wCount._word - byte_to_send._word;

     pDst.bRam = (byte*)&CtrlTrfData;        // Set destination pointer

     if(usb_stat.ctrl_trf_mem == _ROM)       // Determine type of memory source

     {

         while(byte_to_send._word)

         {

             *pDst.bRam = *pSrc.bRom;

             pDst.bRam++;

             pSrc.bRom++;

             byte_to_send._word--;

         }//end while(byte_to_send._word)

     }

     else // RAM

     {

         while(byte_to_send._word)

         {

             *pDst.bRam = *pSrc.bRam;

             pDst.bRam++;

             pSrc.bRam++;

             byte_to_send._word--;

         }//end while(byte_to_send._word)

     }//end if(usb_stat.ctrl_trf_mem == _ROM)

 }//end USBCtrlTrfTxService

 /******************************************************************************

  * Function:        void USBCtrlTrfRxService(void)

  *

  * PreCondition:    pDst and wCount are setup properly.

  *                  pSrc is always &CtrlTrfData

  *                  usb_stat.ctrl_trf_mem is always _RAM.

  *                  wCount should be set to 0 at the start of each control

  *                  transfer.

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        *** This routine is only partially complete. Check for

  *                  new version of the firmware.

  *

  * Note:            None

  *****************************************************************************/

 void USBCtrlTrfRxService(void)

 {

     WORD byte_to_read;

     MSB(byte_to_read) = 0x03 & ep0Bo.Stat._byte;    // Filter out last 2 bits

     LSB(byte_to_read) = ep0Bo.Cnt;

     /*

      * Accumulate total number of bytes read

      */

     wCount._word = wCount._word + byte_to_read._word;

     pSrc.bRam = (byte*)&CtrlTrfData;

     while(byte_to_read._word)

     {

         *pDst.bRam = *pSrc.bRam;

         pDst.bRam++;

         pSrc.bRam++;

         byte_to_read._word--;

     }//end while(byte_to_read._word)    

 }//end USBCtrlTrfRxService

 /******************************************************************************

  * Function:        void USBCtrlEPServiceComplete(void)

  *

  * PreCondition:    None

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        This routine wrap up the ramaining tasks in servicing

  *                  a Setup Request. Its main task is to set the endpoint

  *                  controls appropriately for a given situation. See code

  *                  below.

  *                  There are three main scenarios:

  *                  a) There was no handler for the Request, in this case

  *                     a STALL should be sent out.

  *                  b) The host has requested a read control transfer,

  *                     endpoints are required to be setup in a specific way.

  *                  c) The host has requested a write control transfer, or

  *                     a control data stage is not required, endpoints are

  *                     required to be setup in a specific way.

  *

  *                  Packet processing is resumed by clearing PKTDIS bit.

  *

  * Note:            None

  *****************************************************************************/

 void USBCtrlEPServiceComplete(void)

 {

     if(ctrl_trf_session_owner == MUID_NULL)

     {

         /*

          * If no one knows how to service this request then stall.

          * Must also prepare EP0 to receive the next SETUP transaction.

          */

         ep0Bo.Cnt = EP0_BUFF_SIZE;

         ep0Bo.ADR = (byte*)&SetupPkt;

         ep0Bo.Stat._byte = _USIE|_BSTALL;

         ep0Bi.Stat._byte = _USIE|_BSTALL;

     }

     else    // A module has claimed ownership of the control transfer session.

     {

         if(SetupPkt.DataDir == DEV_TO_HOST)

         {

             if(SetupPkt.wLength < wCount._word)

                 wCount._word = SetupPkt.wLength;

             USBCtrlTrfTxService();

             ctrl_trf_state = CTRL_TRF_TX;

             /*

              * Control Read:

              * <SETUP[0]><IN[1]><IN[0]>...<OUT[1]> | <SETUP[0]>

              * 1. Prepare OUT EP to respond to early termination

              *

              * NOTE:

              * If something went wrong during the control transfer,

              * the last status stage may not be sent by the host.

              * When this happens, two different things could happen

              * depending on the host.

              * a) The host could send out a RESET.

              * b) The host could send out a new SETUP transaction

              *    without sending a RESET first.

              * To properly handle case (b), the OUT EP must be setup

              * to receive either a zero length OUT transaction, or a

              * new SETUP transaction.

              *

              * Since the SETUP transaction requires the DTS bit to be

              * DAT0 while the zero length OUT status requires the DTS

              * bit to be DAT1, the DTS bit check by the hardware should

              * be disabled. This way the SIE could accept either of

              * the two transactions.

              *

              * Furthermore, the Cnt byte should be set to prepare for

              * the SETUP data (8-byte or more), and the buffer address

              * should be pointed to SetupPkt.

              */

             ep0Bo.Cnt = EP0_BUFF_SIZE;

             ep0Bo.ADR = (byte*)&SetupPkt;            

             ep0Bo.Stat._byte = _USIE;           // Note: DTSEN is 0!

             /*

              * 2. Prepare IN EP to transfer data, Cnt should have

              *    been initialized by responsible request owner.

              */

             ep0Bi.ADR = (byte*)&CtrlTrfData;

             ep0Bi.Stat._byte = _USIE|_DAT1|_DTSEN;

         }

         else    // (SetupPkt.DataDir == HOST_TO_DEV)

         {

             ctrl_trf_state = CTRL_TRF_RX;

             /*

              * Control Write:

              * <SETUP[0]><OUT[1]><OUT[0]>...<IN[1]> | <SETUP[0]>

              *

              * 1. Prepare IN EP to respond to early termination

              *

              *    This is the same as a Zero Length Packet Response

              *    for control transfer without a data stage

              */

             ep0Bi.Cnt = 0;

             ep0Bi.Stat._byte = _USIE|_DAT1|_DTSEN;

             /*

              * 2. Prepare OUT EP to receive data.

              */

             ep0Bo.Cnt = EP0_BUFF_SIZE;

             ep0Bo.ADR = (byte*)&CtrlTrfData;

             ep0Bo.Stat._byte = _USIE|_DAT1|_DTSEN;

         }//end if(SetupPkt.DataDir == DEV_TO_HOST)

     }//end if(ctrl_trf_session_owner == MUID_NULL)

     /*

      * PKTDIS bit is set when a Setup Transaction is received.

      * Clear to resume packet processing.

      */

     UCONbits.PKTDIS = 0;

 }//end USBCtrlEPServiceComplete

 /******************************************************************************

  * Function:        void USBPrepareForNextSetupTrf(void)

  *

  * PreCondition:    None

  *

  * Input:           None

  *

  * Output:          None

  *

  * Side Effects:    None

  *

  * Overview:        The routine forces EP0 OUT to be ready for a new Setup

  *                  transaction, and forces EP0 IN to be owned by CPU.

  *

  * Note:            None

  *****************************************************************************/

 void USBPrepareForNextSetupTrf(void)

 {

     ctrl_trf_state = WAIT_SETUP;            // See usbctrltrf.h

     ep0Bo.Cnt = EP0_BUFF_SIZE;              // Defined in usbcfg.h

     ep0Bo.ADR = (byte*)&SetupPkt;

     ep0Bo.Stat._byte = _USIE|_DAT0|_DTSEN;  // EP0 buff dsc init, see usbmmap.h

     ep0Bi.Stat._byte = _UCPU;               // EP0 IN buffer initialization

 }//end USBPrepareForNextSetupTrf

 /** EOF usbctrltrf.c *********************************************************/