FCL/sf/os/usb: comparison usb_plat/usb_shai_api/inc/usb_host

equal deleted inserted replaced

-:613028a7da24
+:eaaed528d5fd
 *
 */
 /** @file
 @brief USB Host SHAI header
-@version 0.2.0
+@version 0.3.0
 This header specifies the USB host SHAI.
 @publishedDeviceAbstraction
 */
 * 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
+#define USB_HOST_SHAI_VERSION 0x030
 // The namespace is documented in file usb_common_shai.h, so it is not
 // repeated here
 namespace UsbShai
 {
 class MRootHubIf;
 // Data types
 /**
-* An enumeration listing the host role electrical test modes
+* An enumeration listing the host role electrical test modes that
-* supported. These correspond to the test modes specified in
+* require special support from the host controller. These
-* Section "6.4.1.1 Test Modes" of the "On-The-Go and Embedded
+* correspond to the test modes specified in Section "6.4.1.1 Test
-* Host Supplement to the USB Revision 2.0 Specification" Revision
+* Modes" of the "On-The-Go and Embedded Host Supplement to the
-* 2.0 (a.k.a. USB OTG 2.0).
+* USB Revision 2.0 Specification" Revision 2.0 (a.k.a. USB OTG
+* 2.0).
+*
+* The single-step control transfer tests are performed as
+* transfers on the control pipe, but a special transfer flag
+* THostTransfer::KSingleStepControlDelayedDataPhase requests the
+* Host Controller PSL to delay the DATA phase when needed.
+*
+* Suspend and resume tests are performed using the normal suspend
+* and resume functionality in the USB Host SHAI, so they are not
+* a special case for the Host Controller PSL.
 *
 * @see MHostControllerIf::EnterHostTestMode()
 */
 enum THostTestMode
 {
 /**
-* Drive SE0 until host controller is reset. The call returns
+* Drive SE0 until the host controller is reset.
-* immediately after enabling the test mode.
 */
 ETestModeTestSE0NAK = 0,
 /**
-* Drive high-speed J until host controller is reset. The call
+* Drive high-speed J until the host controller is reset.
-* returns immediately after enabling the test mode.
 */
 ETestModeTestJ,
 /**
-* Drive high-speed K until host controller is reset. The call
+* Drive high-speed K until the host controller is reset.
-* returns immediately after enabling the test mode.
 */
 ETestModeTestK,
 /**
-* Send test packets until host controller is reset. The
+* Send test packets until the 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
+ETestModeTestPacket
-* 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
 *
 * @see MHostControllerIf::OpenPipe()
 */
 NONSHARABLE_CLASS( THostPipe )
 {
-public:
+public: // Types and constants
+/**
+* A bitmask type used to indicate some boolean properties of
+* the endpoint targeted by this pipe.
+*/
+typedef TUint32 TEndpointFlags;
 // 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
 /**
 * 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;
+static const TEndpointFlags 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;
+static const TEndpointFlags KHubHasMultipleTTs = 0x00000002;
 public: // Data
 /**
 * The type of the endpoint (control, bulk, interrupt,
 * isochronous)
 /** Maximum packet size to be used on this endpoint */
 TUint iMaxPacketSize;
 /** Flags specifying some boolean parameters of the endpoint */
-TUint32 iEndpointFlags;
+TEndpointFlags 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
 * reference to an object of this class when setting up a new transfer
 * with MHostPipeIf::StartTransfer().
 */
 NONSHARABLE_CLASS( THostTransfer )
 {
-public:
+public: // Types and constants
+/**
+* A bitmask type used to indicate some boolean properties of
+* a transfer.
+*/
+typedef TUint32 TTransferFlags;
 // 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,
+* This flag is set or cleared by the PIL layer and is only
-* i.e. the host is reading from the connected device. This is
+* relevant for bi-directional pipes, i.e. control pipes
-* needed for endpoint zero, which is bi-directional and
+* performing control transfers. The bit is not set for other
-* cannot implicitly know the direction of the transfer.
+* endpoint types.
+*
+* For a control transfer, this bit is set to specify that the
+* transfer direction is IN, i.e. the host is reading from the
+* connected device. For a control transfer with the bit
+* cleared, the transfer direction is OUT, i.e. the host is
+* writing to the connected device.
 *
 * This bit is set or cleared by the USB Host stack before
 * issuing a new transfer.
 */
-static const TUint32 KTransferDirIsIN = 0x00000001;
+static const TTransferFlags KTransferDirIsIN = 0x00000001;
 /**
-* For OUT endpoint transfers, indicates whether the Host
+* This flag is set or cleared by the PIL layer and is only
-* Controller PSL is required to force a short packet at the
+* relevant for bi-directional pipes, i.e. control pipes
-* end of the transfer.
+* performing control transfers. The bit is not set for other
+* endpoint types.
+*
+* For a control transfer, this bit is set to specify that the
+* transfer is a special single-step transfer with a delayed
+* data phase. This type of transfer is only used during the
+* high-speed host electrical tests.
+*
+* When this flag is set, the Host Controller PSL should
+* perform the transfer like it normally would, except that it
+* must have a 15 second delay between the completion of the
+* SETUP phase and the sending of the first IN token for the
+* DATA phase.
+*
+* For description and background of the usage of this special
+* transfer option, see the OTG 2.0 Supplement Section 6.4.1.1
+* Test Modes, and specifically the test
+* SINGLE_STEP_GET_DEVICE_DESCRIPTOR_DATA.
+*
+* This bit is set or cleared by the USB Host stack before
+* issuing a new transfer.
+*/
+static const TTransferFlags KSingleStepControlDelayedDataPhase = 0x00000002;
+/**
+* This flag is set or cleared by the PIL layer before issuing
+* a new transfer and is relevant for OUT transfers on bulk,
+* interrupt, and control pipes. It is never set for transfers
+* on isochronous pipes.
+*
+* For bulk, interrupt, or control 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
+static const TTransferFlags KOutForceShortPacket = 0x00000002;
-* issuing a new transfer.
-*/
+/**
-static const TUint32 KOutForceShortPacket = 0x00000002;
+* This flag is set or cleared by the Host Controller PSL
+* before completing the transfer and is only relevant for IN
-/**
+* pipes.
-* For IN endpoint transfers, indicates whether the transfer
+*
-* was terminated with a ZLP (Zero-Length Packet).
+* For IN endpoint transfers, this flag 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
+static const TTransferFlags KInZlpReceived = 0x00000004;
-* 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.
 */
 /**
 * Request flags specifying some boolean parameters for the
 * transfer.
 */
-TUint32 iRequestFlags;
+TTransferFlags 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.
 * 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.
+*
+* To maximize throughput, the PIL layer may call
+* StartTransfer() directly from a previous completion call
+* (see description in
+* MHostTransferCallbackIf::CompleteTransfer()). To prevent
+* recursion, the PSL should not call
+* MHostTransferCallbackIf::CompleteTransfer() directly from
+* within the MHostPipeIf::StartTransfer() call, but should
+* instead queue a DFC to complete the transfer, if
+* immediately completed.
 *
 * 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 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;
 * 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
+* This function is synchronous and should return when the
-* gated on the port without suspending the whole controller,
+* resume signalling on the port has completed.
-* the Host Controller PSL should ignore the port-specific
+*
-* suspend and resume calls and instead suspend/resume the
+* This function is also called when the Host Controller PSL
-* controller based on the controller-specific suspend and
+* has reported detection of a remote wakeup on a port of the
-* resume calls in MHostControllerIf.
+* root hub. This is to make sure the host port takes over
+* driving the resume on the bus. The Host Controller PSL or
+* the HW may have already started driving resume upon
+* detecting the remote wakeup, in which case the PSL only
+* needs to wait in this function until the resume signalling
+* has been 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 TInt StopHostController() = 0;
 /**
 * Place the host controller to the USB suspend state where it
-* does not send SOF packets.
+* does not send SOF packets. The Host Controller PSL may also
+* go into a power-saving mode where it for example shuts down
+* some clocks needed by the host controller when active. The
+* Host Controller PSL must still ensure that the host
+* controller or the root hub will be capable of detecting
+* device disconnection and remote wakeup when suspended.
 */
 virtual void SuspendController() = 0;
 /**
-* Resume the host controller from the USB suspend state by
+* Resume the host controller from the suspend state. If the
-* driving the resume signalling towards the root hub. The
+* Host Controller PSL put the host controller into a
-* signalling must last at least 20 milliseconds and follow
+* power-saving state by shutting down some clocks, the PSL
-* the requirements specified in USB 2.0 Specification Section
+* can re-enable them in this call. This call shall not result
-* 7.1.7.7 Resume Signaling. After the resume signalling has
+* in resume signalling to be driven on the bus, as that
-* completed, the controller must allow SOFs to be sent to the
+* should be done from MRootHubIf::ResumePort().
-* connected device again.
 */
 virtual void ResumeController() = 0;
 /**
 * Force the controller into a specific high-speed host test
 * 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
+* The function shall return immediately when the controller
-* run the selected test as specified for each tests in the
+* has been set to the requested test mode. The host
-* documentation of THostTestMode.
+* controller is expected to remain in the test mode until it
+* is shutdown by a call to StopHostController().
 *
 * @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,
+virtual TInt EnterHostTestMode( THostTestMode    aTestMode ) = 0;
-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
 public:
 /**
 * Complete a transfer request that had been set up with
 * MHostPipeIf::StartTransfer().
 *
+* To maximize throughput, the PIL layer may set up the next
+* transfer by calling MHostPipeIf::StartTransfer()
+* immediately from within this completion function. The PSL
+* has to be prepared for this and make sure it does not upon
+* return of the callback accidentally clean up some internal
+* state belonging to a new transfer started during the
+* callback.
+*
 * @param aTransferInfo The transfer information that
 *   identifies the transfer that has completed
 */
 virtual void CompleteTransfer( const THostTransfer& aTransferInfo ) = 0;
 };
 };
 /**
 * A static class implemented by the USB Host PIL layer to allow
-* the host controller PSL to register to the PIL layer.
+* the Host Controller PSL to register to the PIL layer.
 */
 NONSHARABLE_CLASS( UsbHostPil )
 {
 public:
 /**
 * 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.
+*   interface implemented by the registering PSL. The PIL layer
+*   requires that the supplied reference remains valid
+*   indefinitely, as the Host Controller cannot unregister.
 *
 * @param aProperties Reference to an object describing the
-*   static properties of the Host Controller. The PIL layer
+*   static properties of the Host Controller. The PIL takes a
-*   requires that the supplied reference remains valid
+*   copy and the PSL is free to release the properties object
-*   indefinitely, as a Host Controller cannot unregister.
+*   upon return.
 *
 * @lib usbotghostpil.lib
 */
 IMPORT_C static void RegisterHostController(
 MHostControllerIf&               aHostControllerIf,

changeset 51	eaaed528d5fd
parent 36	1a2a19ee918d
child 59	bbdce6bffaad