--- a/usb_plat/usb_shai_api/inc/usb_host_shai.h Tue Aug 31 17:01:47 2010 +0300
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,1290 +0,0 @@
-/*
-* 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 */