--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/usb_plat/usb_shai_api/inc/usb_host_shai.h Tue Aug 31 17:01:47 2010 +0300
@@ -0,0 +1,1290 @@
+/*
+* 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().
+ *
+ * The USB Host Stack will call the functions of this interface
+ * from a DFC queued on the DFC queue supplied by the Host
+ * Controller in THostControllerProperties::iControllerDfcQueue when the
+ * Host Controller PSL registered.
+ *
+ * @see MHostControllerIf::OpenPipe()
+ */
+ NONSHARABLE_CLASS( MHostPipeIf )
+ {
+ public:
+ /**
+ * Close the USB pipe. This is called by the USB Host Stack
+ * when the pipe is no longer used and the Host Controller PSL
+ * may release any resources that were allocated for this
+ * instance, including deleting the object itself.
+ *
+ * @param aPipeInfo Information describing the target endpoint
+ * of the pipe. This is the same information passed to
+ * MHostControllerIf::OpenPipe() when creating the
+ * pipe.
+ *
+ * @post After calling the function, the USB Host stack will
+ * consider the invoked instance to have been deleted and will
+ * no longer call any of the functions.
+ */
+ virtual void ClosePipeD( const THostPipe& aPipeInfo ) = 0;
+
+ /**
+ * Clear the data toggle bit of this pipe. This is used for
+ * interrupt and bulk pipes when the host stack needs to
+ * guarantee that the host controller will start the next
+ * interrupt or bulk transfer with data toggle value zero.
+ *
+ * @param aPipeInfo Information describing the target endpoint
+ * of the pipe. This is the same information passed to
+ * MHostControllerIf::OpenPipe() when creating the
+ * pipe.
+ */
+ virtual void ClearDataToggle( const THostPipe& aPipeInfo ) = 0;
+
+ /**
+ * Start a transfer on this pipe.
+ *
+ * When the transfer is considered completed, the Host
+ * Controller PSL must update the transfer information object
+ * with the actual length and status of the transfer and then
+ * complete it to the callback interface by calling
+ * MHostTransferCallbackIf::CompleteTransfer(). The pointer to
+ * the callback interface is provided in the member
+ * THostTransfer::iTransferCbIf of the supplied aTransferInfo.
+ *
+ * The following rules shall be used by the Host Controller
+ * PSL to assess the completeness of a transfer:
+ *
+ * 1. A read or write transfer on a control pipe is completed
+ * when all the stages (two or three) of the control transfer
+ * have been completed successfully, or when an error
+ * occurs. It is the responsibility of the upper layers to
+ * guarantee that there is sufficient buffer space for a read
+ * request, so the buffer should not run out.
+ *
+ * 2. A read or write transfer on an isochronous pipe is
+ * completed when the number of isochronous packets specified
+ * in the member THostTransfer::iNumIsocPackets of the
+ * supplied aTransferInfo have been sent or received
+ * successfully, or if a fatal error occurs. It is the
+ * responsibility of the upper layers to guarantee that there
+ * is sufficient buffer space for a read request, so the
+ * buffer should not run out.
+ *
+ * 3. A read transfer on a bulk or interrupt pipe is completed
+ * when the buffer space is exhausted, a short packet (a
+ * packet smaller than the maximum packet size of the pipe) is
+ * received, or an error occurs.
+ *
+ * 4. A write transfer on a bulk or interrupt pipe is
+ * completed when the requested buffer has been fully sent, or
+ * an error occurs.
+ *
+ * @param aTransferInfo Information specifying the transfer to perform
+ *
+ * @return KErrNone if the transfer was started successfully,
+ * otherwise a system-wide error code
+ */
+ virtual TInt StartTransfer( THostTransfer& aTransferInfo ) = 0;
+
+ /**
+ * Cancel a transfer that was previously started with
+ * StartTransfer(). The Host Controller PSL must flush any
+ * pending data (either received or about to be sent) and
+ * discard the transfer. The PSL must not attempt to complete
+ * the canceled transfer by calling
+ * MHostTransferCallbackIf::CompleteTransfer().
+ *
+ * @param aTransferInfo Information specifying the transfer to
+ * cancel. This is the same information passed to
+ * StartTransfer() when the transfer as started.
+ */
+ virtual void CancelTransfer( THostTransfer& aTransferInfo ) = 0;
+ };
+
+
+ /**
+ * An interface class used by the USB Host Stack hub driver to
+ * operate on the root hub ports. The Host Controller PSL must
+ * implement this interface and provide a pointer when the USB
+ * Host Stack opens the root hub by calling
+ * MHostControllerIf::OpenRootHub().
+ *
+ * The USB Host Stack will call the functions of this interface
+ * from a DFC queued on the DFC queue supplied by the Host
+ * Controller in THostControllerProperties::iControllerDfcQueue
+ * when the Host Controller PSL registered.
+ *
+ * @see MHostControllerIf::OpenRootHub()
+ */
+ NONSHARABLE_CLASS( MRootHubIf )
+ {
+ public:
+ /**
+ * Close the connection to the root hub. This is called by the
+ * USB Host Stack when the Host Controller is about to be
+ * deleted and the root hub is no longer used. The Host
+ * Controller PSL may release any resources that were
+ * allocated for this instance, including deleting the object
+ * itself.
+ *
+ * @post After calling the function, the USB Host stack will
+ * consider the invoked instance to have been deleted and will
+ * no longer call any of the functions.
+ */
+ virtual void CloseRootHubD() = 0;
+
+ /**
+ * Enable the power supply, i.e. raise VBUS, on the specified
+ * root hub port.
+ *
+ * If there are problems raising VBUS, the Host Controller PSL
+ * must report a VBUS error by notifying the root hub callback
+ * interface MRootHubCallbackIf of an over-current condition
+ * on the port.
+ *
+ * @param aPort The number of the root hub port to operate
+ * on. For a root hub with N ports, the port numbers are in
+ * range [1..N].
+ *
+ * @see MRootHubCallbackIf::OverCurrentDetected()
+ */
+ virtual void PowerOnPort( TUint aPort ) = 0;
+
+ /**
+ * Stop session (A-device only).
+ *
+ * @param aPort The number of the root hub port to operate
+ * on. For a root hub with N ports, the port numbers are in
+ * range [1..N].
+ */
+ virtual void PowerOffPort( TUint aPort ) = 0;
+
+ /**
+ * Reset the specified root hub port. The total reset length
+ * has to be at least 50 milliseconds and the reset signalling
+ * must follow the requirements specified in USB 2.0
+ * Specification Section 7.1.7.5 Reset Signaling.
+ *
+ * This function is synchronous and should return when the
+ * reset signalling on the port has completed.
+ *
+ * @param aPort The number of the root hub port to operate
+ * on. For a root hub with N ports, the port numbers are in
+ * range [1..N].
+ */
+ virtual void ResetPort( TUint aPort ) = 0;
+
+ /**
+ * Place the specified root hub port to the USB suspend state
+ * where it does not send SOF packets to the connected device.
+ *
+ * When all ports of the root hub have been suspended, the USB
+ * Host Stack will suspend the entire host controller by
+ * calling MHostControllerIf::SuspendController().
+ *
+ * When the root hub only has one port and SOFs cannot be
+ * gated on the port without suspending the whole controller,
+ * the Host Controller PSL should ignore the port-specific
+ * suspend and resume calls and instead suspend/resume the
+ * controller based on the controller-specific suspend and
+ * resume calls in MHostControllerIf.
+ *
+ * @param aPort The number of the root hub port to operate
+ * on. For a root hub with N ports, the port numbers are in
+ * range [1..N].
+ */
+ virtual void SuspendPort( TUint aPort ) = 0;
+
+ /**
+ * Resume the specified root hub port from the USB suspend
+ * state by driving the resume signalling on the port. The
+ * signalling must last at least 20 milliseconds and follow
+ * the requirements specified in USB 2.0 Specification Section
+ * 7.1.7.7 Resume Signaling. After the resume signalling has
+ * completed, the port must allow SOFs to be sent to the
+ * connected device again.
+ *
+ * Before resuming the first port of a completely suspended
+ * controller, the USB Host Stack will first resume the entire
+ * host controller by calling
+ * MHostControllerIf::ResumeController().
+ *
+ * When the root hub only has one port and SOFs cannot be
+ * gated on the port without suspending the whole controller,
+ * the Host Controller PSL should ignore the port-specific
+ * suspend and resume calls and instead suspend/resume the
+ * controller based on the controller-specific suspend and
+ * resume calls in MHostControllerIf.
+ *
+ * @param aPort The number of the root hub port to operate
+ * on. For a root hub with N ports, the port numbers are in
+ * range [1..N].
+ */
+ virtual void ResumePort( TUint aPort ) = 0;
+
+ /**
+ * Query whether a device (a hub or a function) is currently
+ * connected to the specified root hub port, and what speed it
+ * is.
+ *
+ * @param aPort The number of the root hub port to check for a
+ * connected device on. For a root hub with N ports, the port
+ * numbers are in range [1..N].
+ *
+ * @param aSpeed Variable to fill with the speed, if connected
+ *
+ * @return ETrue if a device is currently connected and aSpeed
+ * has been set to the speed of the connected device. EFalse
+ * otherwise.
+ */
+ virtual TBool IsDeviceConnected( TUint aPort,
+ TSpeed& aSpeed ) = 0;
+ };
+
+
+ /**
+ * An interface class that needs to be implemented by each Host
+ * Controller PSL that registers to the USB stack.
+ *
+ * This interface is used by the USB Host Stack to do controller level
+ * operations like suspending and resuming the host controller. It is
+ * also used to open the root hub interface upon creating the SHAI
+ * Host Controller, and to open USB pipes to connected devices.
+ *
+ * The USB Host Stack will call the functions of this interface
+ * from a DFC queued on the DFC queue supplied by the Host
+ * Controller in THostControllerProperties::iControllerDfcQueue when the
+ * Host Controller PSL registered.
+ */
+ NONSHARABLE_CLASS( MHostControllerIf )
+ {
+ public:
+ /**
+ * Open a pipe to an endpoint on a remote USB peripheral.
+ *
+ * This function is called by the USB host stack when it wants
+ * to communicate with a certain endpoint on a discovered USB
+ * peripheral. The opened pipe is then used to read or write
+ * from/to the peripheral until the pipe is later closed by
+ * MHostPipeIf::ClosePipeD().
+ *
+ * @param aPipeInfo Information describing the target endpoint
+ * that the USB host stack wants to create a pipe to. The
+ * ownership of the info object remains with the USB host
+ * stack and the Host Controller PSL must not refer to data
+ * inside this after the function has returned. All
+ * MHostPipeIf functions that operate on the pipe will be
+ * passed the same pipe information so that the Host
+ * Controller PSL does not necessarily need to take a copy.
+ *
+ * @param aPipe Upon success, set by the Host Controller PSL
+ * to point to an instance that implements the SHAI pipe
+ * interface for the opened pipe. This interface will then be
+ * used by the USB Host Stack to perform transfers until the
+ * pipe is eventually closed by the USB Host Stack calling
+ * MHostPipeIf::ClosePipeD().
+ *
+ * @return KErrNone if successful, otherwise a system error code
+ */
+ virtual TInt OpenPipe( const THostPipe& aPipeInfo,
+ MHostPipeIf*& aPipe ) = 0;
+
+ /**
+ * Open the root hub for the Host Controller.
+ *
+ * This is called by the USB Host Stack after creating the
+ * Host Controller PSL to learn the capabilities of the
+ * respective root hub and to establish the communication
+ * between the hub driver in the USB Host Stack and the root
+ * hub ports controlled by the Host Controller PSL.
+ *
+ * @param aRootHubInfo Reference to a root hub information
+ * object to be filled by the adaptation.
+ *
+ * @param aRootHubCbIf Reference to the callback interface of
+ * the root hub driver in the USB stack. The root hub
+ * implementation of the Host Controller PSL shall use this
+ * interface to report events of this root hub.
+ *
+ * @return KErrNone if successful, otherwise a system error code
+ */
+ virtual TInt OpenRootHub( TRootHubInfo& aRootHubInfo,
+ MRootHubCallbackIf& aRootHubCbIf ) = 0;
+
+ /**
+ * Start and enable the host controller. This is called prior
+ * to powering up any port of the root hub to allow to Host
+ * Controller PSL to perform any preparation that may be
+ * necessary to activate the controller. This may include
+ * actions such as enabling clocks or power to the host
+ * controller HW.
+ *
+ * This function is also used in an OTG environment when the
+ * host stack becomes enabled and the controller needs to be
+ * started and enabled for host use. If the HW platform shares
+ * resources such as clocks and power between the host and
+ * peripheral HW, it is probably easiest for the PSL to handle
+ * the role switch based on the
+ * MOtgControllerIf::SetControllerRole() call to the OTG
+ * Controller interface.
+ *
+ * @return KErrNone if the host controller was successfully started,
+ * otherwise a system-wide error code.
+ *
+ * @see usb_otg_shai.h, MOtgControllerIf::SetControllerRole()
+ */
+ virtual TInt StartHostController() = 0;
+
+ /**
+ * Disable and stop the host controller. This is called after
+ * powering down all ports of the root hub to allow to Host
+ * Controller PSL to release any HW resources needed by the
+ * controller. This may include actions such as disabling
+ * clocks or power to the host controller HW.
+ *
+ * This function is also used in an OTG environment when the
+ * host stack becomes disabled and the host HW resources can
+ * be released. If the HW platform shares resources such as
+ * clocks and power between the host and peripheral HW, it is
+ * probably easiest for the PSL to handle the role switch
+ * based on the MOtgControllerIf::SetControllerRole() call to
+ * the OTG Controller interface.
+ *
+ * @return KErrNone if the host controller was successfully started,
+ * otherwise a system-wide error code.
+ *
+ * @see usb_otg_shai.h, MOtgControllerIf::SetControllerRole()
+ */
+ virtual TInt StopHostController() = 0;
+
+ /**
+ * Place the host controller to the USB suspend state where it
+ * does not send SOF packets.
+ */
+ virtual void SuspendController() = 0;
+
+ /**
+ * Resume the host controller from the USB suspend state by
+ * driving the resume signalling towards the root hub. The
+ * signalling must last at least 20 milliseconds and follow
+ * the requirements specified in USB 2.0 Specification Section
+ * 7.1.7.7 Resume Signaling. After the resume signalling has
+ * completed, the controller must allow SOFs to be sent to the
+ * connected device again.
+ */
+ virtual void ResumeController() = 0;
+
+ /**
+ * Force the controller into a specific high-speed host test
+ * mode. This function needs to be implemented only by Host
+ * Controller PSLs for high-speed capable controllers. The
+ * function will only be called when the controller is
+ * operating in high-speed mode and a special test device has
+ * been enumerated.
+ *
+ * When called, the Host Controller PSL shall synchronously
+ * run the selected test as specified for each tests in the
+ * documentation of THostTestMode.
+ *
+ * @param aTestMode Specifies the test mode to enter
+ *
+ * @param aDefaultPipe Information of the default pipe (the
+ * control pipe to endpoint zero) of the connected test
+ * device.
+ *
+ * @return KErrNone if the specified test mode was entered
+ * successfully, otherwise a system-wide error
+ */
+ virtual TInt EnterHostTestMode( THostTestMode aTestMode,
+ const THostPipe& aDefaultPipe ) = 0;
+
+ /**
+ * Get the size and alignment requirements for the Host
+ * Controller. The reference parameters are both input and
+ * output. Upon input, they describe the values requested by
+ * the client, but they may be increased by this function if
+ * the Host Controller requires additional memory or has some
+ * alignment requirements.
+ *
+ * @param aType The type of the endpoint that the memory will
+ * be used for.
+ *
+ * @param aAlignment Output for required alignment in bytes
+ *
+ * @param aSize Input/output for buffer size (may be increased
+ * in this function)
+ *
+ * @param aMaxPackets Input/output for maximum number of
+ * packets in the transfer (may be increased in this function)
+ *
+ * @return KErrNone if successful, otherwise a system-wide
+ * error code
+ */
+ virtual TInt GetSizeAndAlignment( TEndpointType aType,
+ TUint& aAlignment,
+ TInt& aSize,
+ TInt& aMaxPackets ) = 0;
+
+ /**
+ * Creates a shared chunk and commits memory to it. The memory
+ * allocated with this function will later be used when making
+ * data transfers with this Host Controller (see
+ * THostTransfer::iDataBuffer).
+ *
+ * The adaptation shall create a chunk by calling
+ * Kern::ChunkCreate(), and then commit memory to it with one
+ * of the Commit functions Kern::ChunkCommit(),
+ * Kern::ChunkCommitContiguous(), and Kern::ChunkCommitPhysical().
+ *
+ * This task is delegated to the adaptation so that it can
+ * allocate the correct type of memory. For example, if the
+ * Host Controller requires the memory to be physically
+ * contiguous, the implementation of this function must commit
+ * contiguous memory to the chunk.
+ *
+ * @param aChunk Output handle to the chunk that was created.
+ * The adaptation must pass this value as the aChunk argument
+ * to the Kern::ChunkCreate() call.
+ *
+ * @param aOffset The offset (in bytes) from start of chunk,
+ * which indicates the start of the memory region to be
+ * committed. This will be a multiple of the MMU page
+ * size. The adaptation must pass this value as the aOffset
+ * argument to the used Commit call.
+ *
+ * @param aSize Number of bytes to commit. This will be a
+ * multiple of the MMU page size. The adaptation must pass
+ * this value as the aSize argument to the used Commit call.
+ *
+ * @param aInfo At input, specifies the chunk properties
+ * requested by the upper layers. The adaptation is allowed
+ * to change the attributes in aInfo.iMapAttr to match the
+ * requirements of the Host Controller. The adaptation must
+ * pass this value as the aInfo argument to the
+ * Kern::ChunkCreate() call. If the adaptation commits
+ * cached memory, it is the responsibility of the adaptation
+ * to deal with cache synchronization when making data
+ * transfers. If the adaptation needs special cleanup when
+ * the chunk is deleted, the adaptation can set a cleanup
+ * DFC pointer in aInfo.iDestroyedDfc.
+ *
+ * @param aPhysicalAddress On success, will be set to the
+ * physical address of the chunk as referenced by the HC
+ *
+ * @return KErrNone if successful, otherwise a system-wide
+ * error code
+ *
+ * @see System documentation for Kern::ChunkCreate(),
+ * Kern::ChunkCommit(), Kern::ChunkCommitContiguous(), and
+ * Kern::ChunkCommitPhysical()
+ */
+ virtual TInt ChunkCreate( DChunk*& aChunk,
+ TUint aOffset,
+ TUint aSize,
+ TChunkCreateInfo& aInfo,
+ TPhysAddr& aPhysicalAddress ) = 0;
+
+ /**
+ * Maps virtual to physical addresses. If the memory addresses
+ * used by the host controller are different to the ones of
+ * the main memory bus (e.g. due to memory mapping or use of
+ * different address spaces), this method is used to translate
+ * from kernel physical addresses to host controller physical
+ * addresses.
+ *
+ * @param aPhysicalAddressList On entering, the list of
+ * physical addresses as used kernel-side, on successful
+ * return it contains the list of physical addresses as
+ * referenced by the HC
+ *
+ * @param aPhysicalAddressListSize Number of elements in
+ * aPhysicalAddressList
+ *
+ * @return KErrNone if successful, otherwise a system-wide
+ * error code
+ */
+ virtual TInt MapPhysicalAddresses( TPhysAddr*& aPhysicalAddressList,
+ TInt aPhysicalAddressListSize ) = 0;
+ };
+
+
+ /**
+ * An interface class implemented by the USB stack to allow the
+ * host controller to report events to the root hub. This includes
+ * notifications of a device being connected or disconnected on a
+ * port, and other port conditions such as seeing a remote wakeup
+ * signalling, an error on the port (such as babble from a
+ * peripheral), or VBUS over-current.
+ *
+ * It is required that the Host Controller PSL calls these
+ * functions in the context of the DFC queue supplied by the Host
+ * Controller PSL in
+ * THostControllerProperties::iControllerDfcQueue when the Host
+ * Controller PSL registered.
+ */
+ NONSHARABLE_CLASS( MRootHubCallbackIf )
+ {
+ public:
+ /**
+ * A constant to specify an unknown port. In those port
+ * notifications where this is explicitly specified to be OK,
+ * this value is allowed to be used as the port number where
+ * the real port number is unknown.
+ */
+ static const TUint KPortUnknown = 0;
+
+ /**
+ * Informs the root hub that a device (a hub or function) has
+ * been connected to the specified root hub port.
+ *
+ * The Host Controller PSL uses this function to inform device
+ * connection also during HNP role switch when the remote
+ * device connects in peripheral role.
+ *
+ * @param aPort The number of the root hub port that the event
+ * occurred on. For a root hub with N ports, the port numbers
+ * are in range [1..N].
+ */
+ virtual void DeviceConnected( TUint aPort ) = 0;
+
+ /**
+ * Informs the root hub that a device (a hub or function) has
+ * been disconnected from the specified root hub port.
+ *
+ * The Host Controller PSL uses this function to inform device
+ * disconnection also during HNP role switch when the remote
+ * peripheral disconnects to start the role switch.
+ *
+ * The Host Controller PSL must report device disconnection by
+ * calling this function even if the port is currently
+ * suspended. A disconnection that is part of an HNP role
+ * switch will always occur in suspended state, and even a
+ * normal peripheral may be physically disconnected at any
+ * time.
+ *
+ * @param aPort The number of the root hub port that the event
+ * occurred on. For a root hub with N ports, the port numbers
+ * are in range [1..N].
+ */
+ virtual void DeviceDisconnected( TUint aPort ) = 0;
+
+ /**
+ * Informs the root hub that a device connected to the
+ * specified root hub port has requested remote wakeup.
+ *
+ * @param aPort The number of the root hub port that the event
+ * occurred on. For a root hub with N ports, the port numbers
+ * are in range [1..N].
+ */
+ virtual void RemoteWakeupRequested( TUint aPort ) = 0;
+
+ /**
+ * Informs the root hub that a port error (such as babble) has
+ * been detected on the specified root hub port. The
+ * adaptation is expected to disable the port that has caused
+ * the error condition.
+ *
+ * @param aPort The number of the root hub port that the event
+ * occurred on. For a root hub with N ports, the port numbers
+ * are in range [1..N].
+ */
+ virtual void PortErrorDetected( TUint aPort ) = 0;
+
+ /**
+ * Informs the root hub that an over-current condition has
+ * been detected on the specified port.
+ *
+ * It may not always be possible to see which port out of
+ * several caused the overcurrent. In this case the Host
+ * Controller PSL may use the port number
+ * MRootHubCallbackIf::KPortUnknown.
+ *
+ * @param aPort The number of the root hub port that the event
+ * occurred on, if known. For a root hub with N ports, the
+ * port numbers are in range [1..N]. If the exact port is
+ * not known, the Host Controller PSL root hub may report
+ * the port number MRootHubCallbackIf::KPortUnknown.
+ */
+ virtual void OverCurrentDetected( TUint aPort ) = 0;
+ };
+
+
+ /**
+ * An interface class implemented by the USB Host Stack to allow the
+ * host controller to complete transfers to the USB Host Stack.
+ *
+ * It is required that the Host Controller PSL calls these
+ * functions in the context of the DFC queue supplied by the Host
+ * Controller PSL in THostControllerProperties::iControllerDfcQueue when
+ * the Host Controller PSL registered.
+ */
+ NONSHARABLE_CLASS( MHostTransferCallbackIf )
+ {
+ public:
+ /**
+ * Complete a transfer request that had been set up with
+ * MHostPipeIf::StartTransfer().
+ *
+ * @param aTransferInfo The transfer information that
+ * identifies the transfer that has completed
+ */
+ virtual void CompleteTransfer( const THostTransfer& aTransferInfo ) = 0;
+ };
+
+
+ /**
+ * This class specifies the static information provided by a Host
+ * Controller PSL when registering to the USB Host stack.
+ *
+ * The PSL should prepare for the possibility that members may be
+ * added to the end of this class in later SHAI versions if new
+ * information is needed to support new features. The PSL should
+ * not use this class as a direct member in an object that is not
+ * allowed to grow in size due to binary compatibility reasons.
+ *
+ * @see UsbHostPil::RegisterHostController()
+ */
+ NONSHARABLE_CLASS( THostControllerProperties )
+ {
+ public: // Types and constants
+ /**
+ * A bitmask type used to indicate the static capabilities of
+ * the Host Controller.
+ */
+ typedef TUint32 THostCaps;
+
+ public:
+ /**
+ * Inline constructor for the Host Controller properties
+ * object. This is inline rather than an exported function to
+ * prevent a binary break in a case where an older PSL binary
+ * might provide the constructor a smaller object due to the
+ * PSL being compiled against an older version of the SHAI
+ * header. When it's inline, the function is always in sync
+ * with the object size.
+ *
+ * We slightly violate the coding conventions which say that
+ * inline functions should be in their own file. We don't want
+ * to double the number of USB SHAI headers just for sake of a
+ * trivial constructor.
+ */
+ inline THostControllerProperties() :
+ iCapabilities(0),
+ iControllerDfcQueue(NULL),
+ iControllerPageSize(0)
+ {
+ };
+
+ public: // Data
+ /**
+ * A bitmask specifying the static capabilities of this Host
+ * Controller. No capabilities are specified at the moment and
+ * the PSL shall fill this field with a zero value.
+ *
+ * The field is added for sake of future proofing the binary
+ * compatibility of the Host SHAI. By having a field reserved
+ * for capability bits, we can later specify bits to indicate
+ * added virtual functions or extension to this controller
+ * properties structure. The PIL layer can then at runtime
+ * confirm the existence of the new functions or fields and
+ * safely support an older binary, if we choose to.
+ */
+ THostCaps iCapabilities;
+
+ /**
+ * Pointer to a DFC queue that will be used for DFCs of this
+ * controller.
+ *
+ * A stand-alone (one not associated with an OTG-port) Host
+ * Controller PSL 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 Host Controller 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* iControllerDfcQueue;
+
+ /**
+ * The page size used by this Host Controller. The host stack
+ * will fill scatter-gather lists with pages of this size. If
+ * the Host Controller does not have specific page
+ * requirements itself, the registering Host Controller PSL
+ * must supply here the CPU MMU page size that can be obtained
+ * by the call Kern::RoundToPageSize(1).
+ */
+ TInt iControllerPageSize;
+ };
+
+
+ /**
+ * A static class implemented by the USB Host PIL layer to allow
+ * the host controller PSL to register to the PIL layer.
+ */
+ NONSHARABLE_CLASS( UsbHostPil )
+ {
+ public:
+ /**
+ * Registration function to be used by a stand-alone (non-OTG
+ * port) Host Controller PSL to register itself to the PIL
+ * layer. Host Controllers that are part of an OTG-port are
+ * registered by the OTG Controller PSL (see usb_otg_shai.h,
+ * function UsbOtgPil::RegisterOtgController).
+ *
+ * The intended usage is that each stand-alone Host Controller
+ * PSL is a kernel extension that registers itself to the USB
+ * Host PIL layer by making this call from their own kernel
+ * extension entry point function (or an equivalent code that
+ * runs during bootup).
+ *
+ * @param aHostControllerIf Reference to the Host Controller
+ * interface implemented by the registering PSL.
+ *
+ * @param aProperties Reference to an object describing the
+ * static properties of the Host Controller. The PIL layer
+ * requires that the supplied reference remains valid
+ * indefinitely, as a Host Controller cannot unregister.
+ *
+ * @lib usbotghostpil.lib
+ */
+ IMPORT_C static void RegisterHostController(
+ MHostControllerIf& aHostControllerIf,
+ const THostControllerProperties& aProperties );
+ };
+ };
+
+#endif // USB_HOST_SHAI_H
+
+/* End of File */