--- a/usb_plat/usb_shai_api/inc/usb_charger_detection_shai.h Thu Sep 02 22:23:37 2010 +0300
+++ b/usb_plat/usb_shai_api/inc/usb_charger_detection_shai.h Fri Sep 17 08:40:15 2010 +0300
@@ -17,7 +17,7 @@
/** @file
@brief USB Charger Detection SHAI header
- @version 0.2.0
+ @version 0.3.0
This header specifies the USB Charger Detection SHAI.
@@ -30,6 +30,8 @@
// System includes
#include <kern_priv.h>
+#include <usb/usb_charger_detection_shai_shared.h> // Common types shared with upper layers
+
/**
* This macro specifies the version of the USB Charger Detection SHAI
@@ -39,139 +41,12 @@
* older environment with old USB SHAI version that is missing some
* new definitions.
*/
-#define USB_CHARGER_DETECTION_SHAI_VERSION 0x020
+#define USB_CHARGER_DETECTION_SHAI_VERSION 0x030
// The namespace is documented in file usb_common_shai.h, so it is not
// repeated here
namespace UsbShai
{
- // Data types
-
- /**
- * An enumeration listing the different port types that can be
- * reported to the PIL layer by a registered Charger Detector
- * PSL. The available types mostly correspond to those mentioned
- * in the Battery Charging Specification Revision 1.1.
- */
- enum TPortType
- {
- /**
- * This type is reported to indicate that the Charger Detector
- * PSL has detected that we are no longer connected to a
- * powered port. This situation occurs when VBUS driven from
- * outside drops, or the Accessory Charger Adapter changes the
- * RID state from RID_A to RID_GND (which usually also means
- * that VBUS will drop very soon).
- */
- EPortTypeNone = 0,
-
- /**
- * This type is reported to indicate that the Charger
- * Detector PSL has detected that our device is connected to
- * an unsupported port. One common type of an unsupported port
- * is a PS/2 to USB adapter connected to a PS/2 port of a
- * computer.
- */
- EPortTypeUnsupported,
-
- /**
- * This type is reported when the Charger Detector PSL has
- * detected that our device is connected to a charging port,
- * but has not yet distinguished whether the port is a
- * Charging Downstream Port or a Dedicated Charging Port.
- *
- * When this port type is detected, the upper layers will
- * connect to the USB bus as the peripheral by requesting the
- * Peripheral Controller PSL to assert the D+ pull-up. The
- * Charger Detector PSL can then detect the exact port type by
- * observing what happens to the level of the D- line, as
- * specified in the Battery Charging Specification. Upon
- * detecting the exact port type, the Charger Detector PSL can
- * notify a new event with the correct type.
- *
- * If the Charger Detector PSL can directly distinguish the
- * exact port type, the PSL does not need to report this
- * generic charging port type, but can directly report the
- * more specific type EPortTypeDedicatedChargingPort or
- * EPortTypeChargingDownstreamPort.
- */
- EPortTypeChargingPort,
-
- /**
- * This type is reported when the Charger Detector PSL has
- * detected that our device is connected to a Dedicated
- * Charging Port.
- *
- * When this port type is detected, the upper layers will
- * connect to the USB bus as the peripheral by requesting the
- * Peripheral Controller PSL to assert the D+ pull-up, as
- * specified in the Battery Charging Specification.
- */
- EPortTypeDedicatedChargingPort,
-
- /**
- * This type is reported when the Charger Detector PSL has
- * detected that our device is connected to a Charging
- * Downstream Port.
- *
- * When this port type is detected, the upper layers will
- * connect to the USB bus as the peripheral by requesting the
- * Peripheral Controller PSL to assert the D+ pull-up, as
- * specified in the Battery Charging Specification.
- */
- EPortTypeChargingDownstreamPort,
-
- /**
- * This type is reported when the Charger Detector PSL has
- * detected that our device is connected to a Standard
- * Downstream Port.
- *
- * When this port type is detected, the upper layers will
- * connect to the USB bus as the peripheral by requesting the
- * Peripheral Controller PSL to assert the D+ pull-up, as
- * specified in the Battery Charging Specification.
- */
- EPortTypeStandardDownstreamPort,
-
- /**
- * This type is reported when the Charger Detector PSL has
- * detected that our device is connected to the OTG port of an
- * Accessory Charger Adapter and the ID pin is in the RID_A
- * range.
- *
- * When this port type is detected in an OTG-capable device,
- * the OTG State Machine will default to the host role.
- */
- EPortTypeAcaRidA,
-
- /**
- * This type is reported when the Charger Detector PSL has
- * detected that our device is connected to the OTG port of an
- * Accessory Charger Adapter and the ID pin is in the RID_B
- * range.
- *
- * When this port type is detected, the USB Peripheral PIL
- * layer will ensure that the Peripheral Controller PSL is not
- * allowed to connect to the bus, as required by the Battery
- * Charging Specification.
- */
- EPortTypeAcaRidB,
-
- /**
- * This type is reported when the Charger Detector PSL has
- * detected that our device is connected to the OTG port of an
- * Accessory Charger Adapter and the ID pin is in the RID_C
- * range.
- *
- * When this port type is detected, the upper layers will
- * connect to the USB bus as the peripheral by requesting the
- * Peripheral Controller PSL to assert the D+ pull-up, as
- * specified in the Battery Charging Specification.
- */
- EPortTypeAcaRidC,
- };
-
-
// Class declaration
/**
@@ -204,17 +79,24 @@
* MUsbPeripheralPilCallbackIf::DeviceEventNotification(). For
* an OTG-capable port, the requirement is documented in
* usb_otg_shai.h, function
- * MOtgObserverIf::NotifyVbusState().
+ * MOtgObserverIf::NotifyIdPinAndVbusState().
*
* 2. When VBUS is high, the Charger Detector PSL needs to
* observe changes in the ID pin state, if the Charger
- * Detector PSL support detecting the port types relevant
+ * Detector PSL supports detecting the port types relevant
* to Accessory Charger Adapter. This requirement is
* documented in more detail in usb_otg_shai.h, function
- * MOtgObserverIf::NotifyIdPinState().
+ * MOtgObserverIf::NotifyIdPinAndVbusState().
+ *
+ * 3. When our device has been detached from a reported port
+ * type (for example, the Charger Detector PSL reported
+ * port type for Standard Downstream Port and later VBUS
+ * drops indicating disconnect), the Charger Detector PSL
+ * must report the disconnection by notifying port type
+ * EPortTypeNone.
*
* @param aPortType The type of the port detected
- */
+ */
virtual void NotifyPortType( TPortType aPortType ) = 0;
};
@@ -241,20 +123,20 @@
* Controller PSL, or at least that the Peripheral Controller PSL
* is communicating with the Charger Detector PSL. This is
* necessary to ensure that the necessary parts of charger
- * detection are run before reporting VBUS high, and that the
- * Peripheral Controller and the charger detection can safely
- * share the bus without conflict (as both will need to touch the
- * line state). See usb_peripheral_shai.h,
+ * detection are run before reporting VBUS high (when Data Contact
+ * Detect is supported), and that the Peripheral Controller and
+ * the charger detection can safely share the bus without conflict
+ * (as both will need to touch the line state). See
+ * usb_peripheral_shai.h,
* MUsbPeripheralPilCallbackIf::DeviceEventNotification() for
- * description of the requirements.
+ * description of the requirements for peripheral-only PSLs.
*
* Similarly, it is expected that the Charger Detector interface
* for an OTG-capable port is implemented by the OTG Controller
* PSL, or at least that the OTG Controller PSL is communicating
* with the Charger Detector PSL. See usb_otg_shai.h,
- * MOtgObserverIf::NotifyIdPinState() and
- * MOtgObserverIf::NotifyVbusState() for description of the
- * requirements.
+ * MOtgObserverIf::NotifyIdPinAndVbusState() for description of
+ * the requirements for OTG-capable PSLs.
*
* When the PIL layer is ready to receive charger detection
* notifications from the PSL, it will use this interface to
@@ -283,85 +165,6 @@
/**
- * This class specifies the information provided by a Charger
- * Detector PSL when registering to the PIL layer.
- *
- * 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 UsbChargerDetectionPil::RegisterChargerDetector()
- */
- NONSHARABLE_CLASS( TChargerDetectorProperties )
- {
- public: // Types and constants
- /**
- * A bitmask type used to indicate the static capabilities of
- * the Charger Detector.
- */
- typedef TUint32 TChargerDetectorCaps;
-
- /**
- * Capability bit to indicate whether the USB system below the
- * SHAI (either in HW or in the low-level SW) supports
- * automatically reducing charging current for the duration of
- * the USB high-speed chirp signalling. See Battery Charging
- * Specification Revision 1.1, Chapter 3.6.2 for description
- * of the problem.
- *
- * If the system does not support this feature, the upper
- * layer USB components that calculate available charging
- * current will always limit the charging current taken from a
- * Charging Downstream Port so that the maximum current during
- * chirp is not violated.
- *
- * If the system supports this feature, the full available
- * charging current from a Charging Downstream Port is
- * utilized. It is then the responsibility of the HW or some
- * low-level SW below to SHAI to ensure that the charging
- * current is automatically reduced for the duration of chirp
- * signalling.
- *
- * If the system 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 TChargerDetectorCaps KChargerDetectorCapChirpCurrentLimiting = 0x00000001;
-
- public:
- /**
- * Inline constructor for the Charger Detector 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 TChargerDetectorProperties() :
- iCapabilities(0)
- {
- };
-
- public: // Data
- /**
- * A bitmask specifying the static capabilities of this
- * Charger Detector. The PSL fills this field by bitwise
- * OR'ing the TChargerDetectorCaps capability bits
- * corresponding to supported features.
- */
- TChargerDetectorCaps iCapabilities;
- };
-
- /**
* A static class implemented by the USB PIL layer to allow the
* PSL layer to register its charger detector component to the PIL
* layer.
@@ -383,13 +186,14 @@
* bootup).
*
* @param aChargerDetector Reference to the Charger Detector
- * 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 Charger Detector PSL cannot unregister.
*
* @param aProperties Reference to an object describing the
- * static properties of the Charger Detector. The PIL layer
- * requires that the supplied reference remains valid
- * indefinitely, as the registering Charger Detector cannot
- * unregister.
+ * static properties of the Charger Detector. The PIL takes
+ * a copy and the PSL is free to release the properties
+ * object upon return.
*
* @lib usbperipheralpil.lib
*/