/*

* 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 Host SHAI header

    @version 0.2.0

    This header specifies the USB host SHAI.

    @publishedDeviceAbstraction

*/

#ifndef USB_HOST_SHAI_H

#define USB_HOST_SHAI_H

// System includes

#include <kern_priv.h>

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

/**

 * This macro specifies the version of the USB Host 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_HOST_SHAI_VERSION 0x020

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

// repeated here

namespace UsbShai

    {

    // Forward declarations

    class MHostControllerIf;

    class MHostTransferCallbackIf;

    class MRootHubCallbackIf;

    class MRootHubIf;

    // Data types

    /**

     * An enumeration listing the host role electrical test modes

     * supported. These correspond to the test modes specified in

     * Section "6.4.1.1 Test Modes" of the "On-The-Go and Embedded

     * Host Supplement to the USB Revision 2.0 Specification" Revision

     * 2.0 (a.k.a. USB OTG 2.0).

     *

     * @see MHostControllerIf::EnterHostTestMode()

     */

    enum THostTestMode

        {

        /**

         * Drive SE0 until host controller is reset. The call returns

         * immediately after enabling the test mode.

         */

        ETestModeTestSE0NAK = 0,

        /**

         * Drive high-speed J until host controller is reset. The call

         * returns immediately after enabling the test mode.

         */

        ETestModeTestJ,

        /**

         * Drive high-speed K until host controller is reset. The call

         * returns immediately after enabling the test mode.

         */

        ETestModeTestK,

        /**

         * Send test packets until host controller is reset. The

         * format of the required test packet is specified in Section

         * "7.1.20 Test Mode Support" of the USB 2.0 specification.

         *

         * The call returns immediately after enabling the test

         * mode.

         */

        ETestModeTestPacket,

        /**

         * Suspend and resume the port with 15 second delays to allow

         * the operator to adjust test tool settings. The Host

         * Controller PSL must perform the following test steps:

         *

         * 1. Allow SOFs to continue for 15 seconds.

         *

         * 2. Suspend the port under test.

         *

         * 3. Wait for 15 seconds.

         *

         * 4. Resume the port under test.

         *

         * This test mode is synchronous, i.e. the call returns after

         * the test has been completed.

         */

        ETestModeHsHostPortSuspendResume,

        /**

         * Perform a single-step GetDescriptor(Device) transfer.  This

         * is called after the USB Host Stack has enumerated a device

         * with VID=0x1A0A and PID=0x0107. The Host Controller PSL

         * must perform the following test steps:

         *

         * 1. Allow SOFs to continue for 15 seconds.

         *

         * 2. Send a complete GetDescriptor(Device) transfer

         *

         * This test mode is synchronous, i.e. the call returns after

         * the test has been completed.

         */

        ETestModeSingleStepGetDeviceDescriptor,

        /**

         * Perform a single-step GetDescriptor(Device) transfer with a

         * delayed data phase. This is called after the USB Host Stack

         * has enumerated a device with VID=0x1A0A and PID=0x0108. The

         * Host Controller PSL must perform the following test steps:

         *

         * 1. Send the SETUP packet for GetDescriptor(Device). The

         *    device ACKs the packet as usual.

         *

         * 2. Allow SOFs to continue for 15 seconds.

         *

         * 3. Send the IN token for the data phase of

         *    GetDescriptor(Device). The device responds with

         *    the data.

         *

         * 4. Send the acknowledgement (zero-length OUT data) in

         *    response to the data.

         *

         * This test mode is synchronous, i.e. the call returns after

         * the test has been completed.

         */

        ETestModeSingleStepGetDeviceDescriptorData

        };

    // Class declaration

    /**

     * This class specifies a memory block that is used for USB

     * transfers. The memory pointers and the buffer length are filled

     * by the USB Host stack before issuing the transfer to the Host

     * Controller PSL.

     */

    NONSHARABLE_CLASS( TUsbMemoryBlock )

        {

        public:

        /**

         * Linear (virtual) start address of the memory buffer. This

         * address is always provided.

         */

        TLinAddr iLinAddr;

        /**

         * Physical start address of the memory buffer. This address

         * is always provided, but it is the responsibility of the

         * Host Controller PSL to guarantee that the memory is

         * physically contiguous, if contiguous memory is needed. The

         * PSL can guarantee this by implementing

         * MHostControllerIf::ChunkCreate() to allocate physically

         * contiguous memory.

         *

         * @see MHostControllerIf::ChunkCreate()

         */

        TPhysAddr iPhysAddr;

        /**

         * Pointer to an array of physical addresses each pointing to

         * one physical page of the memory block. This address is

         * always provided.

         *

         * The size of each page matches the size reported in

         * THostControllerProperties::iControllerPageSize by the Host

         * Controller PSL when it registered to the PIL.

         */

        TPhysAddr* iPhysPages;

        /** The length of the memory buffer in bytes */

        TUint iLength;

        };

    /**

     * This class specifies the enumerated types for different endpoint

     * configuration items and specifies the structure of the endpoint

     * configuration. Instances of this class are used to specify the

     * endpoint information when opening a pipe.

     *

     * @see MHostControllerIf::OpenPipe()

     */

    NONSHARABLE_CLASS( THostPipe )

        {

        public:

        // These are flag constants that specify the values that can

        // be bitwise OR'ed to the endpoint flags field iEndpointFlags

        // to indicate some boolean parameters of the endpoint

        /**

         * This flag specifies whether the targeted endpoint is behind

         * a hub that is performing transaction translation. This

         * occurs when the attached device is a low/full-speed device

         * attached to a high-speed hub.

         *

         * When this flag is set, the iHubAddr and iHubPort members

         * specify the hub address and the port to which the targeted

         * device is connected, and the iEndpointFlags flag

         * KHubHasMultipleTTs specifies whether the hub has been

         * configured to use multiple transaction translators.

         */

        static const TUint32 KHubTranslates = 0x00000001;

        /**

         * When the iEndpointFlags flag KHubTranslates is set, this

         * flag is set if the hub has multiple transaction

         * translators.

         */

        static const TUint32 KHubHasMultipleTTs = 0x00000002;

        public: // Data

        /**

         * The type of the endpoint (control, bulk, interrupt,

         * isochronous)

         */

        TEndpointType iType;

        /** Maximum packet size to be used on this endpoint */

        TUint iMaxPacketSize;

        /** Flags specifying some boolean parameters of the endpoint */

        TUint32 iEndpointFlags;

        /**

         * The speed (low, full, high) to use for this endpoint. This

         * may differ from the current speed of the local port if the

         * targeted device is a low-speed or full-speed device

         * connected to a high-speed hub.

         */

        TSpeed iSpeed;

        /**

         * The polling interval specified as number of frames or

         * microframes, depending on the speed. This is used for

         * interrupt and isochronous endpoints only.

         */

        TUint iPollingInterval;

        /**

         * The USB address of the remote device that we are

         * communicating with

         */

        TUint8 iRemoteAddr;

        /**

         * The remote endpoint number that we are communicating

         * with. This is the physical endpoint number in the USB 2.0

         * descriptor format, i.e. the most significant bit indicates

         * the direction (1 for IN, 0 for OUT), and the least

         * significant bits indicate the endpoint number.

         */

        TUint8 iRemoteEpNum;

        /**

         * For cases where the attached device is a low/full-speed

         * device attached to a high-speed hub that does the necessary

         * transaction translation, this member records the address of

         * the hub doing the translation.

         */

        TUint8 iHubAddr;

        /**

         * For cases where the attached device is a low/full-speed

         * device attached to a high-speed hub that does the necessary

         * transaction translation, this member records the number of

         * the port where the device is connected on the hub that does

         * the transaction translation.

         */

        TUint8 iHubPort;

        };

    /**

     * This class specifies the structure of the endpoint transfer

     * requests. The USB Host Stack passes the Host Controller PSL a

     * reference to an object of this class when setting up a new transfer

     * with MHostPipeIf::StartTransfer().

     */

    NONSHARABLE_CLASS( THostTransfer )

        {

        public:

        // These are public constants that specify the values that can

        // be bitwise OR'ed to the request flags field iRequestFlags

        // to indicate some boolean parameters of the transfer

        /**

         * When set, specifies that the transfer direction is IN,

         * i.e. the host is reading from the connected device. This is

         * needed for endpoint zero, which is bi-directional and

         * cannot implicitly know the direction of the transfer.

         *

         * This bit is set or cleared by the USB Host stack before

         * issuing a new transfer.

         */

        static const TUint32 KTransferDirIsIN = 0x00000001;

        /**

         * For OUT endpoint transfers, indicates whether the Host

         * Controller PSL is required to force a short packet at the

         * end of the transfer.

         *

         * When the bit is set, the Host Controller PSL must send a

         * ZLP (Zero-Length Packet) after the last packet of the

         * transfer, if and only if the last packet was a full packet,

         * i.e. had the same size as the maximum packet size for the

         * endpoint.

         *

         * This bit is set or cleared by the USB Host stack before

         * issuing a new transfer.

         */

        static const TUint32 KOutForceShortPacket = 0x00000002;

        /**

         * For IN endpoint transfers, indicates whether the transfer

         * was terminated with a ZLP (Zero-Length Packet).

         *

         * This bit is set by the Host Controller PSL before

         * completing the transfer if the transfer ended due to a

         * ZLP. Otherwise the bit is cleared by the Host Controller

         * PSL.

         */

        static const TUint32 KInZlpReceived = 0x00000004;

        /**

         * Enumeration specifying the packet status values to be used

         * for isochronous transfers.

         */

        enum TIsocPacketStatus

            {

            /** No error has occurred, transfer succesful */

            ESuccess = 0,

            /**

             * Data error has occurred in a data transfer, i.e. the

             * CRC did not match

             */

            EDataError,

            /** Overrun has occurred */

            EOverrun,

            /** Underrun has occurred */

            EUnderrun,

            };

        public: // Data

        /**

         * Pointer to the information of the pipe that this transfer

         * is being made on. This is the same information that was

         * used when opening the pipe that the transfer is being made

         * on.

         */

        THostPipe* iPipeInfo;

        /**

         * A pointer to the callback interface to be used for

         * indicating the completion of the transfer. This is set by

         * the USB Host Stack before making a transfer request.

         */

        MHostTransferCallbackIf* iTransferCbIf;

        /**

         * Request flags specifying some boolean parameters for the

         * transfer.

         */

        TUint32 iRequestFlags;

        /**

         * Memory block specifying the memory buffer used for the data

         * transfer. This is filled by the USB Host Stack before

         * making a transfer request.

         *

         * The memory block used here will be part of a chunk

         * previously created by a call to

         * MHostControllerIf::ChunkCreate() and the block will

         * fullfill the alignment requirements reported by the call to

         * MHostControllerIf::GetSizeAndAlignment().

         *

         * For control transfers, this specifies the buffer for the

         * data stage and has zero length and NULL pointers if the

         * transaction does not include a data stage.

         */

        TUsbMemoryBlock iDataBuffer;

        /**

         * For control transfers, this memory block specifies the

         * contents of the setup packet to be sent. For other than

         * control transfers, it is not used, and it has zero length

         * and NULL pointers.

         */

        TUsbMemoryBlock iSetupBuffer;

        /**

         * For isochronous transfers, this sets the number of

         * isochronous packets to send/receive. This is set by the

         * USB Host Stack before making a transfer request.

         */

        TInt iNumIsocPackets;

        /**

         * The number of bytes successfully transferred during the

         * data transfer. This is set by the Host Controller PSL

         * before completing the transfer.

         */

        TUint iTransferLength;

        /**

         * The status code of a completed transfer. This is set by the

         * Host Controller PSL before completing the request to the

         * transfer callback interface.

         */

        TInt iStatus;

        /**

         * For isochronous transfers, a pointer to an array of

         * iNumIsoPackets entries that specify the length of each

         * packet in the transfer. For OUT transfers, the array is

         * filled by the USB Host Stack and is read by the Host

         * Controller PSL to decide the length for each packet. For IN

         * transfers, the array is filled by the Host Controller PSL

         * to record to length of each received packet.

         */

        TUint16* iIsocPacketLengths;

        /**

         * For isochronous transfers, a pointer to an array of

         * iNumIsoPackets entries that specify the status of each

         * packet in the transfer. The array is filled by the Host

         * Controller PSL to record to success or failure of each

         * received packet.

         */

        TIsocPacketStatus* iIsocPacketStatuses;

        };

    /**

     * This class specifies the structure and contents of root hub

     * information that is filled by the adaptation to let the USB Host

     * Stack hub driver learn the capabilities of the root hub.

     *

     * @see MHostControllerIf::OpenRootHub

     */

    NONSHARABLE_CLASS( TRootHubInfo )

        {

        public: // Types and constants

        /**

         * A bitmask type used to indicate the static capabilities of

         * the root hub.

         */

        typedef TUint32 TRootHubCaps;

        /**

         * Capability bit to indicate whether the root hub supports

         * user-visible port indications such as LEDs.

         *

         * If the root hub supports this feature, the PSL shall set

         * the corresponding bit in iCapabilities (by bitwise OR'ing

         * this value). Otherwise the PSL shall clear the

         * corresponding bit in iCapabilities.

         */

        static const TRootHubCaps KRootHubCapPortIndication = 0x00000001;

        public: // Data

        /**

         * A bitmask specifying the static capabilities of this root

         * hub. The PSL fills this field by bitwise OR'ing the

         * TRootHubCaps capability bits corresponding to supported

         * features.

         */

        TRootHubCaps iCapabilities;

        /** Number of ports in this root hub */

        TUint iNumberOfPorts;

        /**

         * Maximum number of milliamps of current that this root hub

         * can supply to VBUS.

         */

        TUint iMaxSuppliedVbusCurrentMA;

        /**

         * Time taken by this root hub between starting to power up a

         * port and power being good on that port. This is expressed

         * in units of one millisecond.

         */

        TUint iTimePowerOnToPowerGoodMs;

        /**

         * The maximum speed supported by the root hub.

         */

        TSpeed iMaxSpeed;

        /** Pointer to the root hub interface */

        MRootHubIf* iRootHubIf;

        };

    /**

     * An interface class used by the USB Host Stack to perform data

     * transfers on a USB pipe. The Host Controller PSL must implement

     * this interface and provide a pointer to a pipe-specific

     * instance when the USB Host Stack creates the pipe by calling

     * MHostControllerIf::OpenPipe().