28 #ifndef USB_CHARGER_DETECTION_SHAI_H |
28 #ifndef USB_CHARGER_DETECTION_SHAI_H |
29 #define USB_CHARGER_DETECTION_SHAI_H |
29 #define USB_CHARGER_DETECTION_SHAI_H |
30 |
30 |
31 // System includes |
31 // System includes |
32 #include <kern_priv.h> |
32 #include <kern_priv.h> |
|
33 #include <usb/usb_charger_detection_shai_shared.h> // Common types shared with upper layers |
|
34 |
33 |
35 |
34 /** |
36 /** |
35 * This macro specifies the version of the USB Charger Detection SHAI |
37 * This macro specifies the version of the USB Charger Detection SHAI |
36 * header in binary coded decimal format. This allows the PSL layer to |
38 * header in binary coded decimal format. This allows the PSL layer to |
37 * confirm a certain definition is available, if needed. This can for |
39 * confirm a certain definition is available, if needed. This can for |
38 * example make it possible for a new PSL to support compilation in an |
40 * example make it possible for a new PSL to support compilation in an |
39 * older environment with old USB SHAI version that is missing some |
41 * older environment with old USB SHAI version that is missing some |
40 * new definitions. |
42 * new definitions. |
41 */ |
43 */ |
42 #define USB_CHARGER_DETECTION_SHAI_VERSION 0x020 |
44 #define USB_CHARGER_DETECTION_SHAI_VERSION 0x030 |
43 |
45 |
44 // The namespace is documented in file usb_common_shai.h, so it is not |
46 // The namespace is documented in file usb_common_shai.h, so it is not |
45 // repeated here |
47 // repeated here |
46 namespace UsbShai |
48 namespace UsbShai |
47 { |
49 { |
48 // Data types |
|
49 |
|
50 /** |
|
51 * An enumeration listing the different port types that can be |
|
52 * reported to the PIL layer by a registered Charger Detector |
|
53 * PSL. The available types mostly correspond to those mentioned |
|
54 * in the Battery Charging Specification Revision 1.1. |
|
55 */ |
|
56 enum TPortType |
|
57 { |
|
58 /** |
|
59 * This type is reported to indicate that the Charger Detector |
|
60 * PSL has detected that we are no longer connected to a |
|
61 * powered port. This situation occurs when VBUS driven from |
|
62 * outside drops, or the Accessory Charger Adapter changes the |
|
63 * RID state from RID_A to RID_GND (which usually also means |
|
64 * that VBUS will drop very soon). |
|
65 */ |
|
66 EPortTypeNone = 0, |
|
67 |
|
68 /** |
|
69 * This type is reported to indicate that the Charger |
|
70 * Detector PSL has detected that our device is connected to |
|
71 * an unsupported port. One common type of an unsupported port |
|
72 * is a PS/2 to USB adapter connected to a PS/2 port of a |
|
73 * computer. |
|
74 */ |
|
75 EPortTypeUnsupported, |
|
76 |
|
77 /** |
|
78 * This type is reported when the Charger Detector PSL has |
|
79 * detected that our device is connected to a charging port, |
|
80 * but has not yet distinguished whether the port is a |
|
81 * Charging Downstream Port or a Dedicated Charging Port. |
|
82 * |
|
83 * When this port type is detected, the upper layers will |
|
84 * connect to the USB bus as the peripheral by requesting the |
|
85 * Peripheral Controller PSL to assert the D+ pull-up. The |
|
86 * Charger Detector PSL can then detect the exact port type by |
|
87 * observing what happens to the level of the D- line, as |
|
88 * specified in the Battery Charging Specification. Upon |
|
89 * detecting the exact port type, the Charger Detector PSL can |
|
90 * notify a new event with the correct type. |
|
91 * |
|
92 * If the Charger Detector PSL can directly distinguish the |
|
93 * exact port type, the PSL does not need to report this |
|
94 * generic charging port type, but can directly report the |
|
95 * more specific type EPortTypeDedicatedChargingPort or |
|
96 * EPortTypeChargingDownstreamPort. |
|
97 */ |
|
98 EPortTypeChargingPort, |
|
99 |
|
100 /** |
|
101 * This type is reported when the Charger Detector PSL has |
|
102 * detected that our device is connected to a Dedicated |
|
103 * Charging Port. |
|
104 * |
|
105 * When this port type is detected, the upper layers will |
|
106 * connect to the USB bus as the peripheral by requesting the |
|
107 * Peripheral Controller PSL to assert the D+ pull-up, as |
|
108 * specified in the Battery Charging Specification. |
|
109 */ |
|
110 EPortTypeDedicatedChargingPort, |
|
111 |
|
112 /** |
|
113 * This type is reported when the Charger Detector PSL has |
|
114 * detected that our device is connected to a Charging |
|
115 * Downstream Port. |
|
116 * |
|
117 * When this port type is detected, the upper layers will |
|
118 * connect to the USB bus as the peripheral by requesting the |
|
119 * Peripheral Controller PSL to assert the D+ pull-up, as |
|
120 * specified in the Battery Charging Specification. |
|
121 */ |
|
122 EPortTypeChargingDownstreamPort, |
|
123 |
|
124 /** |
|
125 * This type is reported when the Charger Detector PSL has |
|
126 * detected that our device is connected to a Standard |
|
127 * Downstream Port. |
|
128 * |
|
129 * When this port type is detected, the upper layers will |
|
130 * connect to the USB bus as the peripheral by requesting the |
|
131 * Peripheral Controller PSL to assert the D+ pull-up, as |
|
132 * specified in the Battery Charging Specification. |
|
133 */ |
|
134 EPortTypeStandardDownstreamPort, |
|
135 |
|
136 /** |
|
137 * This type is reported when the Charger Detector PSL has |
|
138 * detected that our device is connected to the OTG port of an |
|
139 * Accessory Charger Adapter and the ID pin is in the RID_A |
|
140 * range. |
|
141 * |
|
142 * When this port type is detected in an OTG-capable device, |
|
143 * the OTG State Machine will default to the host role. |
|
144 */ |
|
145 EPortTypeAcaRidA, |
|
146 |
|
147 /** |
|
148 * This type is reported when the Charger Detector PSL has |
|
149 * detected that our device is connected to the OTG port of an |
|
150 * Accessory Charger Adapter and the ID pin is in the RID_B |
|
151 * range. |
|
152 * |
|
153 * When this port type is detected, the USB Peripheral PIL |
|
154 * layer will ensure that the Peripheral Controller PSL is not |
|
155 * allowed to connect to the bus, as required by the Battery |
|
156 * Charging Specification. |
|
157 */ |
|
158 EPortTypeAcaRidB, |
|
159 |
|
160 /** |
|
161 * This type is reported when the Charger Detector PSL has |
|
162 * detected that our device is connected to the OTG port of an |
|
163 * Accessory Charger Adapter and the ID pin is in the RID_C |
|
164 * range. |
|
165 * |
|
166 * When this port type is detected, the upper layers will |
|
167 * connect to the USB bus as the peripheral by requesting the |
|
168 * Peripheral Controller PSL to assert the D+ pull-up, as |
|
169 * specified in the Battery Charging Specification. |
|
170 */ |
|
171 EPortTypeAcaRidC, |
|
172 }; |
|
173 |
|
174 |
|
175 // Class declaration |
50 // Class declaration |
176 |
51 |
177 /** |
52 /** |
178 * An interface class implemented by the PIL layer to allow the |
53 * An interface class implemented by the PIL layer to allow the |
179 * Charger Detector PSL to report charger detection events to the |
54 * Charger Detector PSL to report charger detection events to the |
202 * documented in more detail in usb_peripheral_shai.h, |
77 * documented in more detail in usb_peripheral_shai.h, |
203 * function |
78 * function |
204 * MUsbPeripheralPilCallbackIf::DeviceEventNotification(). For |
79 * MUsbPeripheralPilCallbackIf::DeviceEventNotification(). For |
205 * an OTG-capable port, the requirement is documented in |
80 * an OTG-capable port, the requirement is documented in |
206 * usb_otg_shai.h, function |
81 * usb_otg_shai.h, function |
207 * MOtgObserverIf::NotifyVbusState(). |
82 * MOtgObserverIf::NotifyIdPinAndVbusState(). |
208 * |
83 * |
209 * 2. When VBUS is high, the Charger Detector PSL needs to |
84 * 2. When VBUS is high, the Charger Detector PSL needs to |
210 * observe changes in the ID pin state, if the Charger |
85 * observe changes in the ID pin state, if the Charger |
211 * Detector PSL support detecting the port types relevant |
86 * Detector PSL supports detecting the port types relevant |
212 * to Accessory Charger Adapter. This requirement is |
87 * to Accessory Charger Adapter. This requirement is |
213 * documented in more detail in usb_otg_shai.h, function |
88 * documented in more detail in usb_otg_shai.h, function |
214 * MOtgObserverIf::NotifyIdPinState(). |
89 * MOtgObserverIf::NotifyIdPinAndVbusState(). |
|
90 * |
|
91 * 3. When our device has been detached from a reported port |
|
92 * type (for example, the Charger Detector PSL reported |
|
93 * port type for Standard Downstream Port and later VBUS |
|
94 * drops indicating disconnect), the Charger Detector PSL |
|
95 * must report the disconnection by notifying port type |
|
96 * EPortTypeNone. |
215 * |
97 * |
216 * @param aPortType The type of the port detected |
98 * @param aPortType The type of the port detected |
217 */ |
99 */ |
218 virtual void NotifyPortType( TPortType aPortType ) = 0; |
100 virtual void NotifyPortType( TPortType aPortType ) = 0; |
219 }; |
101 }; |
220 |
102 |
221 |
103 |
222 /** |
104 /** |
239 * In practice, it is expected that the Charger Detector interface |
121 * In practice, it is expected that the Charger Detector interface |
240 * for a peripheral-only port is implemented by the Peripheral |
122 * for a peripheral-only port is implemented by the Peripheral |
241 * Controller PSL, or at least that the Peripheral Controller PSL |
123 * Controller PSL, or at least that the Peripheral Controller PSL |
242 * is communicating with the Charger Detector PSL. This is |
124 * is communicating with the Charger Detector PSL. This is |
243 * necessary to ensure that the necessary parts of charger |
125 * necessary to ensure that the necessary parts of charger |
244 * detection are run before reporting VBUS high, and that the |
126 * detection are run before reporting VBUS high (when Data Contact |
245 * Peripheral Controller and the charger detection can safely |
127 * Detect is supported), and that the Peripheral Controller and |
246 * share the bus without conflict (as both will need to touch the |
128 * the charger detection can safely share the bus without conflict |
247 * line state). See usb_peripheral_shai.h, |
129 * (as both will need to touch the line state). See |
|
130 * usb_peripheral_shai.h, |
248 * MUsbPeripheralPilCallbackIf::DeviceEventNotification() for |
131 * MUsbPeripheralPilCallbackIf::DeviceEventNotification() for |
249 * description of the requirements. |
132 * description of the requirements for peripheral-only PSLs. |
250 * |
133 * |
251 * Similarly, it is expected that the Charger Detector interface |
134 * Similarly, it is expected that the Charger Detector interface |
252 * for an OTG-capable port is implemented by the OTG Controller |
135 * for an OTG-capable port is implemented by the OTG Controller |
253 * PSL, or at least that the OTG Controller PSL is communicating |
136 * PSL, or at least that the OTG Controller PSL is communicating |
254 * with the Charger Detector PSL. See usb_otg_shai.h, |
137 * with the Charger Detector PSL. See usb_otg_shai.h, |
255 * MOtgObserverIf::NotifyIdPinState() and |
138 * MOtgObserverIf::NotifyIdPinAndVbusState() for description of |
256 * MOtgObserverIf::NotifyVbusState() for description of the |
139 * the requirements for OTG-capable PSLs. |
257 * requirements. |
|
258 * |
140 * |
259 * When the PIL layer is ready to receive charger detection |
141 * When the PIL layer is ready to receive charger detection |
260 * notifications from the PSL, it will use this interface to |
142 * notifications from the PSL, it will use this interface to |
261 * register itself as the Charger Detector PSL observer. This is |
143 * register itself as the Charger Detector PSL observer. This is |
262 * guaranteed to occur before any USB usage is attempted. |
144 * guaranteed to occur before any USB usage is attempted. |
279 * the charger detector is required to report events to |
161 * the charger detector is required to report events to |
280 */ |
162 */ |
281 virtual void SetChargerDetectorObserver( MChargerDetectorObserverIf& aObserver ) = 0; |
163 virtual void SetChargerDetectorObserver( MChargerDetectorObserverIf& aObserver ) = 0; |
282 }; |
164 }; |
283 |
165 |
284 |
|
285 /** |
|
286 * This class specifies the information provided by a Charger |
|
287 * Detector PSL when registering to the PIL layer. |
|
288 * |
|
289 * The PSL should prepare for the possibility that members may be |
|
290 * added to the end of this class in later SHAI versions if new |
|
291 * information is needed to support new features. The PSL should |
|
292 * not use this class as a direct member in an object that is not |
|
293 * allowed to grow in size due to binary compatibility reasons. |
|
294 * |
|
295 * @see UsbChargerDetectionPil::RegisterChargerDetector() |
|
296 */ |
|
297 NONSHARABLE_CLASS( TChargerDetectorProperties ) |
|
298 { |
|
299 public: // Types and constants |
|
300 /** |
|
301 * A bitmask type used to indicate the static capabilities of |
|
302 * the Charger Detector. |
|
303 */ |
|
304 typedef TUint32 TChargerDetectorCaps; |
|
305 |
|
306 /** |
|
307 * Capability bit to indicate whether the USB system below the |
|
308 * SHAI (either in HW or in the low-level SW) supports |
|
309 * automatically reducing charging current for the duration of |
|
310 * the USB high-speed chirp signalling. See Battery Charging |
|
311 * Specification Revision 1.1, Chapter 3.6.2 for description |
|
312 * of the problem. |
|
313 * |
|
314 * If the system does not support this feature, the upper |
|
315 * layer USB components that calculate available charging |
|
316 * current will always limit the charging current taken from a |
|
317 * Charging Downstream Port so that the maximum current during |
|
318 * chirp is not violated. |
|
319 * |
|
320 * If the system supports this feature, the full available |
|
321 * charging current from a Charging Downstream Port is |
|
322 * utilized. It is then the responsibility of the HW or some |
|
323 * low-level SW below to SHAI to ensure that the charging |
|
324 * current is automatically reduced for the duration of chirp |
|
325 * signalling. |
|
326 * |
|
327 * If the system supports this feature, the PSL shall set the |
|
328 * corresponding bit in iCapabilities (by bitwise OR'ing this |
|
329 * value). Otherwise the PSL shall clear the corresponding bit |
|
330 * in iCapabilities. |
|
331 */ |
|
332 static const TChargerDetectorCaps KChargerDetectorCapChirpCurrentLimiting = 0x00000001; |
|
333 |
|
334 public: |
|
335 /** |
|
336 * Inline constructor for the Charger Detector properties |
|
337 * object. This is inline rather than an exported function to |
|
338 * prevent a binary break in a case where an older PSL binary |
|
339 * might provide the constructor a smaller object due to the |
|
340 * PSL being compiled against an older version of the SHAI |
|
341 * header. When it's inline, the function is always in sync |
|
342 * with the object size. |
|
343 * |
|
344 * We slightly violate the coding conventions which say that |
|
345 * inline functions should be in their own file. We don't want |
|
346 * to double the number of USB SHAI headers just for sake of a |
|
347 * trivial constructor. |
|
348 */ |
|
349 inline TChargerDetectorProperties() : |
|
350 iCapabilities(0) |
|
351 { |
|
352 }; |
|
353 |
|
354 public: // Data |
|
355 /** |
|
356 * A bitmask specifying the static capabilities of this |
|
357 * Charger Detector. The PSL fills this field by bitwise |
|
358 * OR'ing the TChargerDetectorCaps capability bits |
|
359 * corresponding to supported features. |
|
360 */ |
|
361 TChargerDetectorCaps iCapabilities; |
|
362 }; |
|
363 |
166 |
364 /** |
167 /** |
365 * A static class implemented by the USB PIL layer to allow the |
168 * A static class implemented by the USB PIL layer to allow the |
366 * PSL layer to register its charger detector component to the PIL |
169 * PSL layer to register its charger detector component to the PIL |
367 * layer. |
170 * layer. |
381 * by making this call from their own kernel extension entry |
184 * by making this call from their own kernel extension entry |
382 * point function (or an equivalent code that runs during |
185 * point function (or an equivalent code that runs during |
383 * bootup). |
186 * bootup). |
384 * |
187 * |
385 * @param aChargerDetector Reference to the Charger Detector |
188 * @param aChargerDetector Reference to the Charger Detector |
386 * interface implemented by the registering PSL. |
189 * interface implemented by the registering PSL. The PIL |
|
190 * layer requires that the supplied reference remains valid |
|
191 * indefinitely, as the Charger Detector PSL cannot unregister. |
387 * |
192 * |
388 * @param aProperties Reference to an object describing the |
193 * @param aProperties Reference to an object describing the |
389 * static properties of the Charger Detector. The PIL layer |
194 * static properties of the Charger Detector. The PIL takes |
390 * requires that the supplied reference remains valid |
195 * a copy and the PSL is free to release the properties |
391 * indefinitely, as the registering Charger Detector cannot |
196 * object upon return. |
392 * unregister. |
|
393 * |
197 * |
394 * @lib usbperipheralpil.lib |
198 * @lib usbperipheralpil.lib |
395 */ |
199 */ |
396 IMPORT_C static void RegisterChargerDetector( MChargerDetectorIf& aChargerDetector, |
200 IMPORT_C static void RegisterChargerDetector( MChargerDetectorIf& aChargerDetector, |
397 TChargerDetectorProperties& aProperties ); |
201 TChargerDetectorProperties& aProperties ); |