/*

* 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 shared part.

    @version 0.4.0

    Some Non-kernel USB code will also use structure defined in this

    header.  Since usb_peripheral_shai.h always need to include

    <kern_priv.h> which is not visible to non-kernel layers, a

    separated header is needed.

    This header is the one that defined all common structures used by

    kernel & non-kernel layers software.

    The file is versioned for the sake of the human reader and follows

    the version of the USB Peripheral SHAI header

    usb_peripheral_shai.h.

    Peripheral SHAI header always include this header automatically.

    @publishedDeviceAbstraction

*/

#ifndef USB_PERIPHERAL_SHAI_SHARED_H

#define USB_PERIPHERAL_SHAI_SHARED_H

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

// repeated here

namespace UsbShai

    {

    /** 

     * Bitmaps for TUsbPeripheralEndpointCaps.iSupportedTypesAndDir.

     * Endpoint supports Control transfer type.

     */

    const TUint KUsbEpTypeControl     = 0x00000001;

    const TUint KUsbEpTypeIsochronous = 0x00000002;

    const TUint KUsbEpTypeBulk        = 0x00000004;

    const TUint KUsbEpTypeInterrupt   = 0x00000008;

    /** Endpoint supports IN transfers. */

    const TUint KUsbEpDirIn           = 0x80000000;

    /** Endpoint supports OUT transfers. */

    const TUint KUsbEpDirOut          = 0x40000000;

    /** Endpoint supports bidirectional (Control) transfers only.*/

    const TUint KUsbEpDirBidirect     = 0x20000000;

    /**

     * Indicates that whether DMA is preferred to be applied for this endpoint.

     *

     * Upper application will declare whether DMA is expected to be used for

     * this endpoint if there is one available (PSL knows about it) when setup

     * an interface.

     * 

     * PSL can ignore this request if NO DMA is available.

     *

     * PIL may query whether a DMA is really applied via interface 

     * MPeripheralControllerIf::QueryEndpointResource() later.

     *

     * @see TUsbPeripheralEndpointInfo::iFeatureWord1.

     */

    const TUint KUsbEndpointInfoFeatureWord1_DMA             = 0x00000001;

    /**

     * Indicates that whether double buffering is preferred to be applied for 

     * this endpoint. 

     *

     * Upper application will declare whether double buffering is expected to 

     * be used for this endpoint if there is one available (PSL knows about it)

     * when setup an interface.

     * 

     * PSL can ignore this request if NO double buffering is possible.

     * 

     * PIL may query whether a double buffering is really applied via interface 

     * MPeripheralControllerIf::QueryEndpointResource() later.

     *

     * @see TUsbPeripheralEndpointInfo::iFeatureWord1.

     */

    const TUint KUsbEndpointInfoFeatureWord1_DoubleBuffering = 0x00000002;

    /** 

     * These are states that are described in the USB standard.

     */

    enum TUsbPeripheralState

        {

        EUsbPeripheralStateUndefined,  // 0

        EUsbPeripheralStateAttached,   // 1

        EUsbPeripheralStatePowered,    // 2

        EUsbPeripheralStateDefault,    // 3

        EUsbPeripheralStateAddress,    // 4

        EUsbPeripheralStateConfigured, // 5

        EUsbPeripheralStateSuspended,  // 6

        EUsbPeripheralNoState = 0xff   // 255 (used as a place holder)

        };

    /** 

     * Endpoint capabilities as reported by the PSL driver.

     */

    class TUsbPeripheralEndpointCaps

        {

        public:

        /** The supported maximum packet sizes. */

        TUint iSizes;

        /** 

         * The supported endpoint types and directions.

         * see the bitmap definition for type and dir inside this header.

         */

        TUint iTypesAndDir;

        /** set it to ETrue if it is a 'high-speed, high bandwidth' endpoint. */

        TBool iHighBandwidth;

        /** 

         * Reserved for future use. 

         * PSL must set those reserved ram to zero to keep binary compatibility

         * with new (in furture) PIL binary which may utilize some of the 

         * reserved space.

         */

        TUint32 iReserved[2];

        };

    /**

     * The desired endpoint capabilities.

     * @see MPeripheralControllerIf::ConfigureEndpoint.

     */

    class TUsbPeripheralEndpointInfo

        {

        public:

        /** 

         * Endpoint type.

         *(mask: UsbShai::KUsbEpTypeControl, etc., but used as value).

         */

        TUint iType;

        /** Direction (mask: UsbShai::KUsbEpDirIn, etc., but used as value). */

        TUint iDir;

        /** Maximum packet size (literal, no mask). */

        TInt iSize;

        /** 

         * Interval for polling full-speed interrupt and isochronous endpoints.

         * Expressed either directly in milliseconds with a valid range 1..255

         * (interrupt), or for use as 'value' in the expression of 

         * interval=2^(value-1) with a valid range 1..16 (isochronous).

         */

        TInt iInterval;

        /** 

         * Interval for polling high-speed interrupt and isochronous endpoints,

         * or to specify the NAK rate for high-speed control and bulk OUT

         * endpoints. Expressed either for use as 'value' in the expression

         * interval=2^(value-1) with a valid range 1..16 (interrupt and 

         * isochronous), or directly as the maximum NAK rate with a valid range

         * 0..255 (control and bulk).

         */

        TInt iInterval_Hs;

        /**

         * The number of additional transactions per frame to be scheduled(0..2)

         * (A value greater than zero is only valid for high-speed high bandwidth

         * interrupt and isochronous endpoints. Also note that there are endpoint

         * size restrictions associated with additional transactions - see 9.6.6.).

         */

        TInt iTransactions;

        /** 

         * The number of extra bytes that the standard endpoint descriptor

         * should be extended by. In almost all cases, this should be 0 (zero).

         */    

        TInt iExtra;

        /** 

         * 32 flag bits indicating miscellaneous endpoint features.

         * Currently defined are:

         * - KUsbEndpointInfoFeatureWord1_DMA which means apply DMA to this 

         *   endpoint if available.

         * - KUsbEndpointInfoFeatureWord1_DoubleBuffering which means apply 

         *   double buffering to this endpoint if available.

         */

        TUint32 iFeatureWord1;

        /** Reserved for future use. */

        TUint32 iReserved;

        };

    }

#endif //USB_PERIPHERAL_SHAI_SHARED_H

// End of files