/*

* Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

/** @file

    @brief USB Peripheral SHAI header

    @version 0.4.0

    Abstract interface for USB Peripheral Controller.

    @publishedDeviceAbstraction

 */

#ifndef USB_PERIPHERAL_SHAI_H

#define USB_PERIPHERAL_SHAI_H

// System includes

#include <kern_priv.h>

#include <usb/usb_common_shai.h> // Common types shared between the USB SHAIs

#include <usb/usb_peripheral_shai_shared.h> // Common types shared with upper layers

/**

 * This macro specifies the version of the USB Peripheral SHAI header

 * in binary coded decimal format. This allows the PSL layer to

 * confirm a certain definition is available, if needed. This can for

 * example make it possible for a new PSL to support compilation in an

 * older environment with old USB SHAI version that is missing some

 * new definitions.

 */

#define USB_PERIPHERAL_SHAI_VERSION 0x040

// The namespace is documented in file usb_common_shai.h, so it is not

// repeated here

namespace UsbShai

    {

    /** 

     * Masks defined for TUsbPeripheralEndpointCaps.iSizes.

     *

     * Zero means this endpoint is not available (= no size).

     */

    const TUint KUsbEpNotAvailable = 0x00000000;

    /**    

     * Max packet size is continuously variable up to some size specified.

     * (Interrupt and Isochronous endpoints only.)

     */

    const TUint KUsbEpSizeCont     = 0x00000001;

    /** Max packet size 8 bytes is supported */

    const TUint KUsbEpSize8        = 0x00000008;

    /** Max packet size 16 bytes is supported */

    const TUint KUsbEpSize16       = 0x00000010;

    /** Max packet size 32 bytes is supported */

    const TUint KUsbEpSize32       = 0x00000020;

    /** Max packet size 64 bytes is supported */

    const TUint KUsbEpSize64       = 0x00000040;

    /** Max packet size 128 bytes is supported */

    const TUint KUsbEpSize128      = 0x00000080;

    /** Max packet size 256 bytes is supported */

    const TUint KUsbEpSize256      = 0x00000100;

    /** Max packet size 512 bytes is supported */

    const TUint KUsbEpSize512      = 0x00000200;

    /** Max packet size 1023 bytes is supported */

    const TUint KUsbEpSize1023     = 0x00000400;

    /** Max packet size 1024 bytes is supported */

    const TUint KUsbEpSize1024     = 0x00000800;

    /** 

     * Test Mode Selectors (Set/ClearFeature)

     * Refer to usb specification 2.0, Chapter 9.4.9, table 9-7

     */

    enum TUsbTestModeSelector

        {

        EUsbTestSelector_Test_J = 0x01,

        EUsbTestSelector_Test_K,

        EUsbTestSelector_Test_SE0_NAK,

        EUsbTestSelector_Test_Packet,

        EUsbTestSelector_Test_Force_Enable

        };

    /** 

     * Transfer direction of a USB transfer request.

     * @see TUsbPeripheralRequest

     */

    enum TTransferDirection 

        {

        EControllerNone,        

        EControllerRead,

        EControllerWrite

        };

    /** 

     * Enumeration listing the event codes that are passed from PSL to

     * PIL to indicate peripheral events

     */

    enum TUsbPeripheralEvent

        {

        /** The USB Suspend bus state has been detected.

         *

         * When the Peripheral Controller PSL is part of an

         * OTG-capable port, the PSL shall report this event also when

         * operating as the A-peripheral, in which case this final

         * suspend event starts the HNP role switch back to A-host.

         */

        EUsbEventSuspend,

        /** USB Resume signaling has been detected. */

        EUsbEventResume,

        /** A USB Reset condition has been detected. */

        EUsbEventReset,

        /**

         * VBUS level has risen above the B-session valid threshold. This

         * is only relevant for a stand-alone peripheral controllers

         * (those not associated with an OTG port). For an OTG port, the

         * VBUS state is reported to PIL layer by the OTG Controller PSL.

         */

        EUsbEventVbusRisen,

        /**

         * VBUS level has fallen below the B-session valid threshold. This

         * is only relevant for a stand-alone peripheral controllers

         * (those not associated with an OTG port). For an OTG port, the

         * VBUS state is reported to PIL layer by the OTG Controller PSL.

         */

        EUsbEventVbusFallen

        };   

    typedef TUint32 TUsbPeripheralPacketArray;

    /** 

     * @brief  A USB transfer request.

     * 

     * This class will be constructed in PIL or upper layer, and be

     * passed down to PSL. After the request was done, PSL layer will

     * modify corresponding members (like data length, packet info

     * etc.) and re-pass it back to PIL via interface

     * MUsbPeripheralPilCallbackIf::EndpointRequestComplete().

     * 

     */

    NONSHARABLE_CLASS(TUsbPeripheralRequest)

        {

    public:    

        /**

         * This class doesn't need a destructor because it has nothing to be

         * freed, closed, destroyed. It 'owns' nothing.

         */

        IMPORT_C TUsbPeripheralRequest(TInt aRealEpNum);

    public:

        /** The 'real' endpoint number this request to be bind to. */

        TInt iRealEpNum;

        /** 

         * Start address of this buffer. Filled-in by PIL.

         *

         * PSL needs to put received data in this buffer if it's a read request.

         * PSL needs to get data from this buffer if it is a write request.

         */

        TUint8* iBufferStart;

        /** Physical address of buffer start (used for DMA). */

        TUintPtr iBufferAddr;

        /** Length in bytes to be read/write. Filled-in by PIL. */

        TInt iLength;

        /** 

         * Number of bytes transmitted (if it is a write);

         * This value need to be updated by PSL. 

         */

        TUint iTxBytes;

        /** 

         * Number of packets received (if it is a read); 

         * This value need to be updated by PSL.

         */

        TUint iRxPackets;

        /** 

         * This is a re-interpretation of what's inside in buffer iBufferStart.

         * It is designed to be that the first packet always contains all the

         * bytes received. So only the following scenario are possible:

         *

         * 1. Nothing, iRxPackets is zero, no packet received.

         * 

         * 2. 1 data Packet, iRxPackets is one.

         *    iPacketIndex[0] is the offset against iBufferStart of where the

         *    first byte of received data begins.

         *    iPacketSize[0] is the size (in bytes) of the received data.

         * 

         * 3. 1 data packet, and one ZLP packet, iRxPackets is two.

         *    iPacketIndex[0] is the offset against iBufferStart of where the

         *    first byte of received data begins.

         *    iPacketSize[0] is the size (in bytes) of the data packet.

         *    

         *    iPacketIndex[1] is the offset of the ZLP packet.

         *    iPacketSize[1] is always set to zero since ZLP contains no data.

         * 

         */

        TUsbPeripheralPacketArray* iPacketIndex;

        /** Array of packet sizes. Details see iPacketIndex */

        TUsbPeripheralPacketArray* iPacketSize;

        /**

         * Indicates the transfer direction of this request.

         * Note, SetupEndpointRead/Write likewise functions already point out 

         * the transfer direction, PSL may select to use it or not.

         */

        TTransferDirection iTransferDir;

        /** 

         * For EControllerWrite (IN) transfers, it is used to Indicates that if 

         * a Zero Length Packet is required at the end of this transfer.

         * It will be set to ETrue if ZLP is needed, EFalse otherwise.

         */

        TBool iZlpReqd;

        /** 

         * The error code upon completion of the request;

         * PSL need to set it to KErrNone if no errors, Set it to other 

         * system error codes otherwise.

         */

        TInt iError;

        };

    /** 

     * Peripheral controller capabilities.

     * 

     * PSL should use those values to fill in data member iControllerCaps in

     * structure TPeripheralControllerProperties.

     *

     * @see TPeripheralControllerProperties.

     */

    typedef TUint32 TDeviceCaps;

    /**

     * Indicates whether peripheral controller hardware supports USB High-speed.

     * This capability affects driver functionality and behavior throughout the 

     * implementation.

     * 

     * Set this bit if this peripheral controller supports USB High-speed;

     * Clear it otherwise.

     */

    const TDeviceCaps KDevCapHighSpeed = 0x00000001;

    /** 

     * Indicates whether the peripheral controller supports hardware acceleration

     * for setting the device address, i.e. automatically setting device address

     * on conclusion of status phase of SET_ADDRESS.

     *

     * If this capability is supported PIL will call SetDeviceAddress() before

     * sending a zero byte status packet.

     *

     * Set this bit if hardware acceleration is supported.

     * Clear it otherwise.

     */

    const TDeviceCaps KDevCapSetAddressAcceleration = 0x00000002;

    /**

     * Indicates whether controller support Session Request Protocol.

     *

     * Set this bit if SRP is supported.

     * Clear it otherwise.

     */

    const TDeviceCaps KDevCapSrpSupport = 0x00000004;

    /**

     * Indicates whether controller support Host Negotiation Protocol.

     *

     * Set this bit if HNP is supported.

     * Clear it otherwise.

     */

    const TDeviceCaps KDevCapHnpSupport = 0x00000008;

    /**

     * Indicates whether controller support Remote wakeup

     * 

     * Set this bit if remote wakeup is supported.

     * Clear it otherwise.

     */

    const TDeviceCaps KDevCapRemoteWakeupSupport = 0x00000010;

    /** 

     * Configuration data from PSL to PIL when register a controller through

     * interface UsbPeripheralPil::RegisterPeripheralController().

     */

    NONSHARABLE_CLASS(TPeripheralControllerProperties)

        {

        public:

        TPeripheralControllerProperties();

        public: // Data

        /**

         * A bitmap used to Indicates the capabilities of this controller.

         * PSL should set the corresponding bit to '1' if one capability is

         * supported by this controller.

         */

        TDeviceCaps iControllerCaps;

        /**

         * Pointer to a DFC queue that will be used for DFCs of this controller.

         *

         * A stand-alone (one not associated with an OTG-port) peripheral PSL 

         * implementation must supply a pointer to a dedicated DFC queue that 

         * has been created for this controller. Both the PSL itself and the PIL

         * layer must queue their DFCs for this controller in this DFC queue to

         * ensure the code is running in the same context.

         *

         * A peripheral PSL that is part of an OTG port will be registered by 

         * the OTG PSL. In this case, the DFC queue supplied here must be the 

         * same DFC queue as the one supplied in the properties of the OTG 

         * Controller.

         */

        TDfcQue* iDfcQueue;

        /** 

         * Describe the capabilities of all endpoint owned by this controller.

         *

         * Note that there might be gaps in the array, because the endpoints 

         * must be numbered by using the 'real endpoint' numbering scheme.

         *

         * An example of end point capability array:

         *

         * @code

         * static const TUsbPeripheralEndpointCaps DevEndpointCaps[KTotalEps] =

         * {

         * // MaxSize mask  ,   Types&Dir                      , High  ,Reserved

         *                                                       speed?

         * {KEp0MaxPktSzMask,(KUsbEpTypeControl | KUsbEpDirOut), ETrue ,0 , 0},

         * {KEp0MaxPktSzMask,(KUsbEpTypeControl | KUsbEpDirIn ), ETrue ,0 , 0},

         *      

         * {KUsbEpNotAvailable,KUsbEpNotAvailable              , ETrue ,0 , 0},

         *      

         * {KBlkMaxPktSzMask,(KUsbEpTypeBulk | KUsbEpDirIn )   , ETrue ,0 , 0},

         * {KBlkMaxPktSzMask,(KUsbEpTypeBulk | KUsbEpDirOut)   , ETrue ,0 , 0}

         * };

         * @endcode

         *

         * For endpoint maxinum packet size on USB2.0 High-speed, PSL should

         * provide the overlaid values for both full speed and high speed, as 

         * PIL can deduce the appropriate values for either speed.

         *

         */

        const TUsbPeripheralEndpointCaps* iDeviceEndpointCaps;

        /** 

         * Set by the PSL to indicate the number of entries in 

         * iDeviceEndpointCaps array.

         * Be noted that this value include the ones that are marked as 

         * KUsbEpNotAvailable in table iDeviceEndpointCaps.

         */

        TInt iDeviceTotalEndpoints;

        /** 

         * Maximum size of ep0 packet.

         * @see USB spec 2.0, chapter 9, table 9-8.

         */

        TUint8  iMaxEp0Size;

        /** 

         * Device Release number in binary-coded decimal.

         * @see USB spec 2.0, chapter 9, table 9-8.

         */

        TUint16  iDeviceRelease;

        };

    /** 

     * Enumeration of stages within a control transfer

     * 

     * Possible stages defined in USB spec include:

     * 1. setup -> status in

     * 2. setup -> data in -> status out

     * 3. setup -> data out -> status in

     */

    enum TControlStage

        {

        /** 

         * Control transfer always start with a setup stage in which a setup

         * packet is expected.         

         */

        EControlTransferStageSetup,

        /** The stage that a data packet is expected from be received */

        EControlTransferStageDataOut,

        /**

         * Status in stage can either following a Setup stage (if no data stage)

         * or following a data out stage.

         */

        EControlTransferStageStatusIn,

        /** 

         * Depends on the request type of a setup packet, a data in stage maybe 

         * followed after a setup packet.

         *

         * Within this stage we expect upper/ourself to send some data to host.

         */

        EControlTransferStageDataIn,

        /**

         * This is an optional stage, some controller will silently swallow

         * Status out packet and not able to report it.

         * PIL has consider this situation when control transfer state machine

         * is introduced.

         */

        EControlTransferStageStatusOut,

        EControlTransferStageMax

        };

    /** 

     * Packet types in control transfers.

     * 

     * PSL need to tell PIL about the types of each packet it received.

     * @see MUsbPeripheralPilCallbackIf::Ep0RequestComplete().

     */

    enum TControlPacketType

        {

        /** Indicates a setup packet */

        EControlPacketTypeSetup,

        /** Indicates a data out packet */

        EControlPacketTypeDataOut,

        /** 

         * Indicates a status in packet.

         * optional, PSL can select not to complete this packet.

         */

        EControlPacketTypeStatusIn,

        /** Indicates a data in packet */

        EControlPacketTypeDataIn,

        /** 

         * Indicates that a status out packet.

         * optional, PSL can select not to complete this packet.

         */

        EControlPacketTypeStatusOut,

        };

    /** 

     * @brief Interface for PSL to do callback to PIL

     * 

     * This is the interface that a PSL need talk with PIL in order to:

     * 1. Pass device event (reset/suspend/resume/vbus high/vbus low etc) to PIL.

     * 2. Complete a read/write request to PIL.

     * 3. Query control transfer stage from PIL.

     * 3. Other functions like SetAdress/Handle HNP/Get remote wake up etc.

     *

     * This interface already been implemented and exported via library 

     * usbperipheralpil.lib. PSL need to add this library as a dependency in 

     * you PSL .mmp file.

     *

     * @lib  usbperipheralpil.lib

     */

    NONSHARABLE_CLASS(MUsbPeripheralPilCallbackIf)

        {

        public:

        /** 

         * Used to synchronize the Ep0 Stage machine between PSL and PIL.

         * Accepts a SETUP packet and returns the next Ep0 Stage.

         *

         * This function will NOT lead anything to be changed at PIL, it is 

         * functioning by parsing the supplied buffer only.

         *

         * @param aSetupBuf The SETUP packet received by PSL.

         * @return The next Ep0 Stage at PIL if PIL receive this setup packet.

         *

         */

        virtual TControlStage EnquireEp0NextStage(const TUint8* aSetupBuf) const = 0;

        /** 

         * This function gets called by PSL upon completion of a pending 

         * endpoint zero data transfer request.

         *

         * @param aRealEndpoint Either 0 for Ep0 OUT (= Read)

         *                      or 1 for Ep0 IN (= Write).

         * @param aCount The number of bytes received or transmitted.

         * @param aError The error code of the completed transfer request. 

         *               KErrNone if no error.

         *               KErrCancel if transfer was cancelled.

         *               KErrPrematureEnd if a premature end was encountered.

         * @param aPktType The type of the packet that being completed.

         * 

         * @return KErrNone if no error during transfer completion processing;

         *  KErrGeneral if request was a read & a Setup packet was received &

         *  the recipient for that packet couldn't be found (invalid packet: Ep0

         *  has been stalled); KErrNotFound if the request was a read & the 

         *  recipient for that packet (Setup or data) _was_ * found - however no

         *  read had been set up by that recipient (this case should be used by 

         *  PSL to disable Ep0 interrupt at that point and give the upper layer 

         *  software time to set up a new Ep0 read; once the 'missing' read was 

         *  set up either Ep0DataReceiveProceed or Ep0ReadSetupPktProceed of 

         *  MPeripheralControllerIf class  will be called by PIL).

         */

        virtual TInt Ep0RequestComplete(TInt aRealEndpoint, 

                                        TInt aCount, 

                                        TInt aError, 

                                        TControlPacketType aPktType) = 0;

        /**