diff -r f92a4f87e424 -r 012cc2ee6408 usb_plat/usb_shai_api/inc/usb_otg_shai.h --- a/usb_plat/usb_shai_api/inc/usb_otg_shai.h Tue Aug 31 17:01:47 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,626 +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 OTG SHAI header - @version 0.2.0 - - This header specifies the USB OTG SHAI. - - @publishedDeviceAbstraction -*/ - - -#ifndef USB_OTG_SHAI_H -#define USB_OTG_SHAI_H - -// System includes -#include -#include // Common types shared between the USB SHAIs - -/** - * This macro specifies the version of the USB OTG 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_OTG_SHAI_VERSION 0x020 - -// The namespace is documented in file usb_common_shai.h, so it is not -// repeated here -namespace UsbShai - { - // Forward declarations - - class MOtgControllerIf; - class MOtgObserverIf; - class MPeripheralControllerIf; - class TPeripheralControllerProperties; - class MHostControllerIf; - class THostControllerProperties; - - // Data types - - /** - * Enumeration listing the possible states of the ID pin. Due to a - * dependency between OTG and USB Battery Charging, this - * enumeration lists also the special states introduced as part of - * the Battery Charging Specification version 1.1. - * - * An OTG Controller PSL for a system that does not support - * Accessory Charger Adapter (ACA) will always report only - * EIdStateRidFloat or EIdStateRidGnd. An OTG Controller PSL that - * supports ACA is required to report the ID pin state accurately - * in order for the OTG State Machine to understand why VBUS - * appears high even though we should default to the host role and - * should normally drive VBUS ourselves (in case of RID_A). - * - * Reporting an ACA state via the ID pin notification mechanism is - * not a substitute for reporting port type detection via the USB - * Charger Detection SHAI that is documented separately in - * usb_charger_detection_shai.h. When ACA is supported, it is - * required that the Charger Detector PSL guarantees that the OTG - * Observer gets notified of the ID pin state before reporting the - * port type to the Charger Detector Observer. - * - * @see usb_charger_detection_shai.h - */ - enum TIdPinState - { - /** ID pin is grounded */ - EIdStateRidGnd = 0, - - /** ID pin is floating */ - EIdStateRidFloat, - - /** - * ID pin is in the RID_A range, as specified in Battery - * Charging 1.1 specification - */ - EIdStateRidA, - - /** - * ID pin is in the RID_B range, as specified in Battery - * Charging 1.1 specification - */ - EIdStateRidB, - - /** - * ID pin is in the RID_C range, as specified in Battery - * Charging 1.1 specification - */ - EIdStateRidC - }; - - /** - * Enumeration listing the reported states of VBUS on the OTG - * port. - * - * The threshold for Session Valid comparison is VOTG_SESS_VLD as - * defined in the "On-The-Go and Embedded Host Supplement to the - * USB Revision 2.0 Specification", Table 4-1 Electrical - * Characteristics. The voltage level for a compliant - * implementation can be anywhere between 0.8 V and 4.0 V. - */ - enum TVbusState - { - /** VBUS is below the OTG Session Valid threshold */ - EVbusStateNoSession = 0, - - /** - * VBUS is above the OTG Session Valid threshold, but below - * the requirements of AVbusValid. - */ - EVbusStateSessionValid, - - /** - * When operating as the A-device and driving VBUS, indicates - * that the VBUS is in regulation, as defined in "On-The-Go - * and Embedded Host Supplement to the USB Revision 2.0 - * Specification" Section 4.2.1, "VBUS Output Voltage and - * Current". - * - * When a VBUS session has been started as the A-device, the - * OTG Controller PSL is required to report a VBUS level of - * EVbusStateAVbusValid when VBUS has successfully risen to - * allow the OTG State Machine to transition out of the - * a_wait_vrise state. - * - * After VBUS has been successfully raised when operating as - * the A-device, the PSL reporting a VBUS level less than - * EVbusStateAVbusValid is considered as a report of a VBUS - * error (over-current) situation and will result in ending - * the session immediately. - */ - EVbusStateAVbusValid - }; - - /** - * Enumeration listing the state of the OTG 2.0 state machine. - * - * The states match those defined in the "On-The-Go and Embedded - * Host Supplement to the USB Revision 2.0 Specification" for the - * OTG A-device and B-device states. - */ - enum TOtgState - { - /** The OTG state is b_idle */ - EOtgStateBIdle = 0, - - /** The OTG state is b_peripheral */ - EOtgStateBPeripheral, - - /** The OTG state is b_wait_acon */ - EOtgStateBWaitAcon, - - /** The OTG state is b_host */ - EOtgStateBHost, - - /** The OTG state is a_idle */ - EOtgStateAIdle, - - /** The OTG state is a_wait_vrise */ - EOtgStateAWaitVrise, - - /** The OTG state is a_wait_bcon */ - EOtgStateAWaitBcon, - - /** The OTG state is a_host */ - EOtgStateAHost, - - /** The OTG state is a_suspend */ - EOtgStateASuspend, - - /** The OTG state is a_peripheral */ - EOtgStateAPeripheral, - - /** The OTG state is a_wait_vfall */ - EOtgStateAWaitVfall, - - /** The OTG state is a_vbus_err */ - EOtgStateAVbusErr - }; - - /** - * Enumeration listing the roles that our device can be in. - */ - enum TOtgRole - { - /** - * Our device is idle, i.e. we are not operating in either the - * peripheral or the host role. This role indicates that - * neither the host controller nor the peripheral controller - * needs to be activated and the PSL is free to power down the - * controllers. - */ - EOtgRoleIdle = 0, - - /** Our device is operating in the peripheral role */ - EOtgRolePeripheral, - - /** Our device is operating in the host role */ - EOtgRoleHost - }; - - // Class declaration - - /** - * An interface class that needs to be implemented by each OTG - * Controller PSL that registers to the USB stack. - * - * The USB OTG Stack will call the functions of this interface - * from a DFC queued on the DFC queue supplied by the OTG - * Controller PSL in TOtgControllerProperties::iControllerDfcQueue - * when the OTG Controller PSL registered. - */ - NONSHARABLE_CLASS( MOtgControllerIf ) - { - public: - /** - * Called by the OTG stack to set the observer callback - * interface to be used by the OTG Controller PSL to report - * events. - * - * When the observer pointer is set to non-NULL value, the OTG - * Controller PSL is required to immediately report the - * current VBUS and ID states to the observer to get the - * status of the OTG stack up to date. - * - * @param aObserver Pointer to the observer interface to use, - * or NULL when the OTG stack is being unloaded. - */ - virtual void SetOtgObserver( MOtgObserverIf* aObserver ) = 0; - - /** - * When operating as the B-peripheral, the OTG stack calls - * this function to indicate that the upper layers are - * requesting our device to become the B-host. This means that - * our OTG device will need start the HNP signalling by - * disconnecting from the bus and allowing the A-device to - * connect as the peripheral. The signalling shall be started - * when the host has suspended the bus, which may already be - * the case or happen later. - * - * This function call is only relevant for OTG controllers - * that implement the HNP signalling in hardware and require - * an explicit request from SW to start the HNP role switch. - * If the OTG controller is under SW control by the Host and - * Peripheral Controller PSLs, the OTG Controller PSL should - * ignore this call. The HNP signalling in the SW-controlled - * case will be handled as normal calls to disconnect as - * peripheral and then start the host controller. - * - * For all controller types, the Host Controller PSL and the - * Peripheral Controller PSL associated with the OTG port are - * required to report events as they normally would when - * operating as the default role. For the Host Controller PSL, - * this includes notifying device connection, disconnection, - * and other relevant events via MRootHubCallbackIf. For the - * Peripheral Controller PSL, this includes notifying bus - * state events such as reset, suspend, and resume via - * MUsbPeripheralPilCallbackIf::DeviceEventNotification. - * - * The OTG Controller PSL is not required to perform any - * monitoring of HNP success or failure, or report that to the - * PIL layer. The PSL is only responsible for making the - * normal host and peripheral notifications mentioned above, - * and the PIL can see the HNP success or failure from those - * notifications. - */ - virtual void SetBHnpRequest() = 0; - - /** - * When operating as the B-device, the OTG stack calls this - * function to request the PSL to drive SRP signalling on the - * bus by pulsing the D+ dataline. The OTG Controller PSL may - * synchronously drive the 5..10 millisecond pulse before - * returning, but it may also do it asynchronously. - * - * The OTG PIL layer guarantees that the initial conditions - * for driving SRP are satisfied before the PIL calls this - * function. That is, the PIL guarantees that sufficient time - * has elapsed since the end of the previous VBUS session (if - * any) and the bus has been idle long enough. - * - * No special report from the OTG Controller PSL is required - * in either success or fail case. In a success case, the - * A-device will raise VBUS and the OTG state machine gets - * this as a normal VBUS notifications from the OTG Controller - * PSL. In a fail case, a timer in the upper layers will - * expire, indicating to upper layers that the SRP was not - * successful. - */ - virtual void SignalBSrp() = 0; - - /** - * Called by the OTG state machine to indicate a change in the - * required controller role. - * - * Whether the PSL needs to do any actions depends on the HW. - * For controllers that require special configuration in - * changing a role (other than just starting the peripheral - * controller or the host controller normally), the OTG - * Controller should do that special configuration when it - * gets this call. - * - * When changing a role, the OTG state machine will first - * disable the stack for the previous role, causing that stack - * to issue a stop request to the respective controller - * PSL. The OTG state machine will then call this function - * SetControllerRole() to set the controller role to the - * target role. Following this, the OTG state machine will - * enable the stack for the target role, causing that stack to - * issue a start request to the respective controller PSL. - * - * @param aControllerRole The OTG role to set our device to - * - * @return KErrNone if the OTG Controller successfully set the - * role or required no actions. Otherwise a system-wide - * error code. - */ - virtual TInt SetControllerRole( TOtgRole aControllerRole ) = 0; - }; - - - /** - * An interface class implemented by the USB stack to allow the - * OTG controller to report events to the USB stack. This includes - * events like VBUS rising and falling, ID pin becoming grounded - * or floating, and SRP being detected. - * - * It is required that the OTG Controller PSL calls these - * functions in the context of the DFC queue supplied by the OTG - * Controller PSL in TOtgControllerProperties::iControllerDfcQueue - * when the OTG Controller PSL registered. - */ - NONSHARABLE_CLASS( MOtgObserverIf ) - { - public: - /** - * Notify the current ID-pin state to the OTG stack. This - * needs to be called by the OTG Controller PSL everytime - * there is a change in the ID pin level. Redundant - * notifications that don't change the previously reported - * state are silently ignored, so the function is safe to call - * without worrying about extra calls. - * - * When USB Battery Charging is supported on the OTG-capable - * port, there is a dependency between normal USB - * functionality and USB Battery Charging (see - * usb_charger_detection_shai.h and specifically the - * description of class MChargerDetectorIf). In this case it - * is the responsibility of the OTG Controller PSL to - * communicate with the Charger Detector PSL (which it may - * implement itself) with respect to VBUS and ID pin events. - * - * For ID pin events that indicate connection to an Accessory - * Charger Adapter, it is required that the port type is first - * notified to the Charger Detector PSL Observer, followed by - * notifying the ID pin state to the OTG Observer (via this - * function). - * - * @param aIdPinState The current ID-pin state - */ - virtual void NotifyIdPinState( TIdPinState aIdPinState ) = 0; - - /** - * Notify the current VBUS state to the OTG stack. This needs - * to be called by the OTG Controller PSL everytime there is a - * change in the VBUS level. Redundant notifications that - * don't change the previously reported state are silently - * ignored, so the function is safe to call without worrying - * about extra calls. - * - * When USB Battery Charging is supported on the OTG-capable - * port, there is a dependency between normal USB - * functionality and USB Battery Charging (see - * usb_charger_detection_shai.h and specifically the - * description of class MChargerDetectorIf). In this case it - * is the responsibility of the OTG Controller PSL to - * communicate with the Charger Detector PSL (which it may - * implement itself) with respect to VBUS and ID pin events. - * - * When VBUS rises on the OTG-capable port that is currently - * the B-device and fully supports Battery Charging - * Specification Revision 1.1, the Charger Detector PSL and - * the OTG Controller PSL need to together guarantee that Data - * Contact Detect is completed and the port type detected - * before reporting VBUS rising. When the port type is known, - * the port type needs to be notified to the Charger Detector - * PSL Observer, followed by notifying the VBUS state to the - * OTG Observer (via this function). - * - * Where Data Contact Detect is not supported, the VBUS rise - * event needs to be notified to the OTG Observer (via this - * function) immediately and charger detection needs to - * proceed in parallel with the upper layers preparing the USB - * personality. This is necessary in order to ensure that we - * can fulfill the requirement to connect to the bus within a - * second, while still making as long as possible charger - * detection cycle to minimize the changes of false detections - * due to datalines not making contact yet. - * - * The OTG Controller PSL, the Peripheral Controller PSL and - * the Charger Detector PSL need to together guarantee that - * the peripheral controller does not attempt to connect to - * the bus while charger detection is still on-going. When - * detection has been completed and upper layers have - * indicated readiness to connect to the bus (see - * MPeripheralControllerIf::PeripheralConnect(), the - * Peripheral Controller PSL must connect to the bus. - * - * @param aVbusState The current VBUS state - */ - virtual void NotifyVbusState( TVbusState aVbusState ) = 0; - - /** - * When operating as the A-device with VBUS low, notify the - * OTG stack that SRP signalling has been detected on the - * bus. The OTG Controller must detect the SRP signalling from - * dataline pulsing, as specified in the "On-The-Go and - * Embedded Host Supplement to the USB Revision 2.0 - * Specification". - */ - virtual void NotifySrpDetected() = 0; - - /** - * This function is called by the OTG Controller PSL to report - * that it has detected the attachment of a device (A or B) - * that is malfunctioning in a low-level way that prevents - * attempting communication with the connected device. Such - * cases may include but are not necessarily limited to: - * - * 1. A B-device that drives its upstream VBUS. To prevent - * damage to the VBUS charge pump in our A-device, it may be - * necessary to prevent VBUS from being raised by our device. - * - * 2. A B-device that presents a single-ended one (both - * datalines high) on the bus. - * - * The detection of such malfunctioning devices is left to the - * OTG Controller PSL, as this type of malfunctions are - * low-level problems not necessarily detectable with the - * standard inputs available to the OTG state machine. - * - * To ensure that the OTG state machine stays in an idle - * state, the OTG Controller PSL should report ID floating and - * VBUS low prior to reporting the bad device attachment by - * calling this function. When the bad device is detached, the - * OTG Controller PSL can resume reporting ID and VBUS state - * truthfully, and must call NotifyBadDeviceDetached() to - * allow the upper layers to see the error condition has been - * cleared. - * - * @see NotifyBadDeviceDetached() - */ - virtual void NotifyBadDeviceAttached() = 0; - - /** - * This function is called by the OTG Controller PSL to report - * that a previously detected bad device has been detached. - * See NotifyBadDeviceAttached() for description of this - * functionality. - * - * @see NotifyBadDeviceAttached() - */ - virtual void NotifyBadDeviceDetached() = 0; - }; - - - /** - * This class specifies the information provided by an OTG - * Controller PSL when registering to the USB OTG 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 UsbOtgPil::RegisterOtgController() - */ - NONSHARABLE_CLASS( TOtgControllerProperties ) - { - public: // Types and constants - /** - * A bitmask type used to indicate the static capabilities of - * the OTG Controller. - */ - typedef TUint32 TOtgCaps; - - public: - /** - * Inline constructor for the OTG 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 TOtgControllerProperties() : - iCapabilities(0), - iControllerDfcQueue(NULL) - { - }; - - public: // Data - /** - * A bitmask specifying the static capabilities of this OTG - * 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 OTG 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. - */ - TOtgCaps iCapabilities; - - /** - * Pointer to a DFC queue that will be used for DFCs of this - * controller and the associated peripheral and host - * controllers. - * - * The OTG Controller must supply a pointer to a dedicated DFC - * queue that has been created for this OTG Controller PSL. - * Both the OTG Controller PSL itself and the OTG stack must - * queue their DFCs for this controller in this DFC queue to - * ensure the code is running in the same context. - * - * Furthermore, it is the responsibility of the OTG Controller - * PSL that registers to ensure that the Peripheral and Host - * Controller PSLs that are registered at the same time use - * the same DFC Queue in their respective properties object. - */ - TDfcQue* iControllerDfcQueue; - }; - - - /** - * A static class implemented by the USB OTG PIL layer to allow - * the OTG controller PSL to register to the PIL layer. - */ - NONSHARABLE_CLASS( UsbOtgPil ) - { - public: - /** - * Registration function to be used by the OTG Controller PSL - * to register itself and the associated peripheral and host - * controller PSLs to the PIL layer. - * - * The intended usage is that OTG Controller PSL (of which - * only one can exists in a given system) is a kernel - * extension that registers itself and the associated - * peripheral and host controller PSLs to the USB PIL layer by - * making this call from its kernel extension entry point - * function (or an equivalent code that runs during bootup). - * - * @param aOtgControllerIf Reference to the OTG Controller - * interface implemented by the registering PSL. - * - * @param aOtgProperties Reference to an object describing the - * static properties of the OTG Controller. The PIL layer - * requires that the supplied reference remains valid - * indefinitely, as an OTG Controller cannot unregister. - * - * @param aPeripheralControllerIf Reference to the Peripheral - * Controller interface implemented by the PSL controlling the - * Peripheral Controller associated with the registering OTG - * port. - * - * @param aPeripheralProperties Reference to an object - * describing the static properties of the Peripheral - * Controller. The PIL layer requires that the supplied - * reference remains valid indefinitely, as the registering - * OTG Controller cannot unregister. - * - * @param aHostControllerIf Reference to the Host Controller - * interface implemented by the PSL controlling the Host - * Controller associated with the registering OTG port. - * - * @param aHostProperties Reference to an object describing the - * static properties of the Host Controller. The PIL layer - * requires that the supplied reference remains valid - * indefinitely, as the registering OTG Controller cannot - * unregister. - * - * @lib usbotghostpil.lib - */ - IMPORT_C static void RegisterOtgController( - MOtgControllerIf& aOtgControllerIf, - const TOtgControllerProperties& aOtgProperties, - MPeripheralControllerIf& aPeripheralControllerIf, - const TPeripheralControllerProperties& aPeripheralProperties, - MHostControllerIf& aHostControllerIf, - const THostControllerProperties& aHostProperties ); - }; - }; - -#endif // USB_OTG_SHAI_H - -/* End of File */