2
* Copyright 2008-2009 Freescale Semiconductor, Inc. All Rights Reserved.
6
* The code contained herein is licensed under the GNU General Public
7
* License. You may obtain a copy of the GNU General Public License
8
* Version 2 or later at the following locations:
10
* http://www.opensource.org/licenses/gpl-license.html
11
* http://www.gnu.org/copyleft/gpl.html
14
////////////////////////////////////////////////////////////////////////////////
15
//! \addtogroup ddi_bc
18
// Copyright (c) 2004-2005 SigmaTel, Inc.
21
//! \brief Header file for the Battery Charger device driver.
24
//! This file contains externally visible declarations for the Battery Charger
27
//! \see ddi_bc.c and related files.
28
//! \todo [PUBS] Add definitions for TBDs in this file.
29
////////////////////////////////////////////////////////////////////////////////
34
#include <linux/types.h>
36
////////////////////////////////////////////////////////////////////////////////
38
////////////////////////////////////////////////////////////////////////////////
40
////////////////////////////////////////////////////////////////////////////////
42
////////////////////////////////////////////////////////////////////////////////
43
#define DDI_BC_MAX_RESTART_CYCLES 100
45
#define DDI_BC_LIION_CHARGING_VOLTAGE 4200
46
#define DDI_BC_ALKALINE_NIMH_CHARGING_VOLTAGE 1750
48
//! \brief Defines battery charger states.
49
typedef enum _ddi_bc_State {
51
DDI_BC_STATE_UNINITIALIZED = 0,
53
DDI_BC_STATE_BROKEN = 1,
55
DDI_BC_STATE_DISABLED = 2,
57
DDI_BC_STATE_WAITING_TO_CHARGE = 3,
59
DDI_BC_STATE_CONDITIONING = 4,
61
DDI_BC_STATE_CHARGING = 5,
63
DDI_BC_STATE_TOPPING_OFF = 6,
65
DDI_BC_STATE_DCDC_MODE_WAITING_TO_CHARGE = 7,
69
typedef enum _ddi_bc_BrokenReason {
71
DDI_BC_BROKEN_UNINITIALIZED = 0,
73
DDI_BC_BROKEN_CHARGING_TIMEOUT = 1,
75
DDI_BC_BROKEN_FORCED_BY_APPLICATION = 2,
77
DDI_BC_BROKEN_EXTERNAL_BATTERY_VOLTAGE_DETECTED = 3,
79
DDI_BC_BROKEN_NO_BATTERY_DETECTED = 4,
81
} ddi_bc_BrokenReason_t;
83
//! \brief Defines the battery charger configuration.
84
typedef struct _ddi_bc_Cfg {
85
//! \brief Units in milliseconds.
87
//! This field configures the expected period between calls to
88
//! ddi_bc_StateMachine. If die temperature monitoring is
89
//! enabled, then the data sheet recommends the period be around
92
//! Note that this period defines the minimum time resolution of
93
//! the battery charger.
95
uint32_t u32StateMachinePeriod;
97
//! \brief Units in mA/s.
99
//! This field configures the slope of the current ramp. Any
100
//! time the battery charger increases its current draw, it will
101
//! ramp up the current no faster than this rate.
103
//! Note that the minimum time resolution of the battery charger
104
//! is the configured period between calls to advance the state
105
//! machine. Also, the hardware has a minimum current resolution
106
//! of 10mA. If the given ramp slope cannot be expressed
107
//! exactly, then the largest expressible smaller slope will be
108
//! the result. If the actual period between calls to
109
//! ddi_bc_StateMachine is irregular, the current may ramp faster
112
uint16_t u16CurrentRampSlope;
114
//! \brief Units in millivolts.
116
//! This field configures the threshold conditioning voltage. If
117
//! the battery�s voltage is below this value, it will be
118
//! conditioned until its voltage rises above the maximum
119
//! conditioning voltage. After that, the battery will be
120
//! charged normally.
122
//! Note that the hardware has a minimum resolution of 8mV. If
123
//! the given voltage cannot be expressed exactly, then the
124
//! smallest expressible larger value will be used.
126
uint16_t u16ConditioningThresholdVoltage;
128
//! \brief Units in millivolts.
130
//! This field configures the maximum conditioning voltage. If
131
//! the battery charger is conditioning a battery, normal
132
//! charging begins when the voltage rises above this value.
134
//! This value should be slightly higher than the threshold
135
//! conditioning voltage because it is measured while a
136
//! conditioning current is actually flowing to the battery.
137
//! With a conditioning current of 0.1C, reasonable values for
138
//! the threshold and maximum conditioning voltages are 2.9V
139
//! and 3.0V respectively.
141
//! Note that the hardware has a minimum resolution of 8mV. If
142
//! the given voltage cannot be expressed exactly, then the
143
//! smallest expressible larger value will be used.
145
uint16_t u16ConditioningMaxVoltage;
147
//! \brief Units in milliamps.
149
//! This field configures the maximum conditioning current.
150
//! This is the maximum current that will be offered to a
151
//! battery while it is being conditioned. A typical value is
154
//! Note that the hardware has a minimum resolution of 10mA
155
//! (see the data sheet for details). If the given current
156
//! cannot be expressed exactly, then the largest expressible
157
//! smaller value will be used.
159
uint16_t u16ConditioningCurrent;
161
//! \brief Units in milliseconds.
163
//! This field configures the conditioning time-out. This is
164
//! the maximum amount of time that a battery will be
165
//! conditioned before the battery charger declares it to be
168
//! Note that the minimum time resolution of the battery
169
//! charger is the configured period between calls to advance
170
//! the state machine. If the given time-out cannot be
171
//! expressed exactly, then the shortest expressible longer
172
//! value will be used.
174
uint32_t u32ConditioningTimeout;
176
//! \brief Units in millivolts.
178
//! This field configures the final charging voltage. At this
179
//! writing, only two values are permitted: 4100 or 4200.
181
uint16_t u16ChargingVoltage;
183
//! \brief Units in milliamps.
185
//! This field configures the maximum current offered to a
186
//! charging battery.
188
//! Note that the hardware has a minimum resolution of 10mA
189
//! (see the data sheet for details). If the given current
190
//! cannot be expressed exactly, then the largest expressible
191
//! smaller value will be used.
193
uint16_t u16ChargingCurrent;
195
//! \brief Units in milliamps.
197
//! This field configures the current flow below which a
198
//! charging battery is regarded as fully charged (typical
199
//! 0.1C). At this point, the battery will be topped off.
201
//! Note that the hardware has a minimum resolution of 10mA
202
//! (see the data sheet for details). If the given current
203
//! cannot be expressed exactly, then the largest expressible
204
//! smaller value will be used.
206
uint16_t u16ChargingThresholdCurrent;
208
//! \brief Units in milliamps.
210
//! When charging while the DCDC converter's are enabled, the charger
211
//! is suppling current to both the battery and the Vbat input of the
212
//! DCDC converter. Once the total battery charger current falls
213
//! below this level, the charger will then stop charging until the
214
//! the battery voltage reaches the BC_LOW_DCDCMODE_BATTERY_VOLTAGE
215
//! threshold or until the DCDCs are no longer enabled.
217
//! Typically, this value should be left at 180 to avoid the risk
218
//! of topping off the battery too long in DCDC mode and avoid
219
//! exceeding the BC_CHARGING_TIMEOUT time which would put the charger
220
//! driver in the broken state and completely disable charging.
222
//! Note that the hardware has a minimum resolution of 10mA
223
//! (see the data sheet for details). If the given current
224
//! cannot be expressed exactly, then the largest expressible
225
//! smaller value will be used.
226
uint16_t u16DdcdModeChargingThresholdCurrent;
228
//! \brief Units in milliseconds.
230
//! This field configures the charging time-out. This is the
231
//! maximum amount of time that a battery will be charged
232
//! before the battery charger declares it to be broken.
234
//! Note that the minimum time resolution of the battery
235
//! charger is the configured period between calls to advance
236
//! the state machine. If the given time-out cannot be
237
//! expressed exactly, then the shortest expressible longer
238
//! value will be used.
240
uint32_t u32ChargingTimeout;
242
//! \brief Units in milliseconds.
244
//! This field configures the top-off period. This is the
245
//! amount of time a battery will be held in the Topping Off
246
//! state before it is declared fully charged.
248
//! Note that the minimum time resolution of the battery
249
//! charger is the configured period between calls to advance
250
//! the state machine. If the given time-out cannot be
251
//! expressed exactly, then the shortest expressible longer
252
//! value will be used.
254
uint32_t u32TopOffPeriod;
256
//! \brief Units in milliseconds.
258
//! This field configures the top-off period when the DCDC
259
//! converters are enabled. To avoid topping off the LiIon
260
//! battery too long and reducing it's long term capacity,
261
//! This time should be kept failry short.
263
//! Note that the minimum time resolution of the battery
264
//! charger is the configured period between calls to advance
265
//! the state machine. If the given time-out cannot be
266
//! expressed exactly, then the shortest expressible longer
267
//! value will be used.
268
uint32_t u32DcdcModeTopOffPeriod;
270
//! \brief Causes the battery charger to use an externally generated bias current
272
//! If cleared, this causes the battery charger to use an
273
//! externally generated bias current, which is expected to be
274
//! quite precise. Otherwise, the battery charger will
275
//! generate a lesser-quality bias current internally.
277
uint8_t useInternalBias:1;
279
//! \brief Indicates that the battery charger is to monitor the die temperature.
281
//! If set, this field indicates that the battery charger is to
282
//! monitor the die temperature. See below for fields that
283
//! configure the details.
285
uint8_t monitorDieTemp:1;
287
//! \brief Indicates that the battery charger is to monitor the battery temperature.
289
//! If set, this field indicates that the battery charger is to
290
//! monitor the battery temperature. See below for fields that
291
//! configure the details.
293
uint8_t monitorBatteryTemp:1;
295
//! \brief Units in degrees centigrade.
297
//! Note that the hardware reports die temperature in ranges of
298
//! 10 degree resolution minimum (see the data sheet for
299
//! details). If the battery charger is monitoring the die
300
//! temperature, and it rises to a range that includes a
301
//! temperature greater than or equal to this value, the
302
//! charging current will be clamped to the safe current.
304
int8_t u8DieTempHigh;
306
//! \brief Units in degrees centigrade.
308
//! Note that the hardware reports die temperature in ranges of
309
//! 10 degrees minimum (see the data sheet for details). If the
310
//! charging current is being clamped because of a high die
311
//! temperature, and it falls to a range that doesn�t include a
312
//! temperatures greater than or equal to this value, the
313
//! charging current clamp will be released.
317
//! \brief Units in milliamps.
319
//! If the battery charger detects a high die temperature, it
320
//! will clamp the charging current at or below this value.
322
uint16_t u16DieTempSafeCurrent;
324
//! \brief If the battery charger is monitoring the battery
325
//! temperature, this field indicates the LRADC channel to
328
uint8_t u8BatteryTempChannel;
330
//! \brief If the battery charger is monitoring the battery
331
//! temperature, and it rises to a measurement greater than or
332
//! equal to this value, the charging current will be clamped
333
//! to the corresponding safe current.
335
uint16_t u16BatteryTempHigh;
337
//! \brief If the charging current is being clamped because of a high
338
//! battery temperature, and it falls below this value, the
339
//! charging current clamp will be released.
341
uint16_t u16BatteryTempLow;
343
//! \brief Units in milliamps.
345
//! If the battery charger detects a high battery temperature,
346
//! it will clamp the charging current at or below this value.
348
uint16_t u16BatteryTempSafeCurrent;
350
//! \brief Units in millivolts.
352
//! In the WaitingToCharge state, if we are in DCDC
353
//! operating modes, if the battery voltage measurement
354
//! is below this value, we immediately proceed with charging.
355
//! the low criteria for this value is that it must be high
356
//! to not risk the battery voltage getting too low. The
357
//! upper criteria is that you do not want the IR voltage
358
//! drop under heavy loads to make you start charging too soon
359
//! because the goal in DCDC operating mode is to not be constantly
360
//! topping off the battery which can shorten its life
362
uint16_t u16LowDcdcBatteryVoltage_mv;
364
uint32_t u32StateMachineNonChargingPeriod;
367
//! Status returned by Battery Charger functions.
369
typedef enum _ddi_bc_Status {
371
DDI_BC_STATUS_SUCCESS = 0,
373
DDI_BC_STATUS_HARDWARE_DISABLED,
375
DDI_BC_STATUS_BAD_BATTERY_MODE,
377
DDI_BC_STATUS_CLOCK_GATE_CLOSED,
379
DDI_BC_STATUS_NOT_INITIALIZED,
381
DDI_BC_STATUS_ALREADY_INITIALIZED,
383
DDI_BC_STATUS_BROKEN,
385
DDI_BC_STATUS_NOT_BROKEN,
387
DDI_BC_STATUS_NOT_DISABLED,
389
DDI_BC_STATUS_BAD_ARGUMENT,
391
DDI_BC_STATUS_CFG_BAD_BATTERY_TEMP_CHANNEL,
393
DDI_BC_STATUS_CFG_BAD_CHARGING_VOLTAGE,
396
/////////////////////////////////////////////////////////////////////////////////
399
// These are the codes that might be published to PMI Subscribers.
400
/////////////////////////////////////////////////////////////////////////////////
402
#define DDI_BC_EVENT_GROUP (11<<10)
405
//! \todo [PUBS] Add definition(s)...
407
// Use the error code group value to make events unique for the EOI
409
ddi_bc_MinEventCode = DDI_BC_EVENT_GROUP,
411
ddi_bc_WaitingToChargeCode,
413
ddi_bc_State_ConditioningCode,
415
ddi_bc_State_Topping_OffCode,
417
ddi_bc_State_BrokenCode,
419
ddi_bc_SettingChargeCode,
421
ddi_bc_RaisingDieTempAlarmCode,
423
ddi_bc_DroppingDieTempAlarmCode,
428
ddi_bc_DcdcModeWaitingToChargeCode
431
////////////////////////////////////////////////////////////////////////////////
433
////////////////////////////////////////////////////////////////////////////////
435
////////////////////////////////////////////////////////////////////////////////
436
//! \brief Initialize the Battery Charger.
440
//! This function initializes the Battery Charger.
442
//! \param[in] pCfg A pointer to the new configuration.
444
//! \retval DDI_BC_STATUS_SUCCESS
445
//! If the operation succeeded.
446
//! \retval DDI_BC_STATUS_ALREADY_INITIALIZED
447
//! If the Battery Charger is already initialized.
448
//! \retval DDI_BC_STATUS_HARDWARE_DISABLED
449
//! If the Battery Charger hardware is disabled by a laser fuse.
450
//! \retval DDI_BC_STATUS_BAD_BATTERY_MODE
451
//! If the power supply is set up for a non-rechargeable battery.
452
//! \retval DDI_BC_STATUS_CLOCK_GATE_CLOSED
453
//! If the clock gate for the power supply registers is closed.
454
//! \retval DDI_BC_STATUS_CFG_BAD_CHARGING_VOLTAGE
455
//! If the charging voltage is not either 4100 or 4200.
456
//! \retval DDI_BC_STATUS_CFG_BAD_BATTERY_TEMP_CHANNEL
457
//! If the LRADC channel number for monitoring battery temperature
461
//! \see To view the function definition, see ddi_bc_init.c.
462
////////////////////////////////////////////////////////////////////////////////
463
extern ddi_bc_Status_t ddi_bc_Init(ddi_bc_Cfg_t * pCfg);
464
////////////////////////////////////////////////////////////////////////////////
466
//! \brief Report the Battery Charger configuration.
470
//! This function reports the Battery Charger configuration.
472
//! Note that, if the Battery Charger has not yet been initialized, the data
473
//! returned by this function is unknown.
475
//! \param[in,out] pCfg A pointer to a structure that will receive the data.
478
//! \see To view the function definition, see ddi_bc_api.c.
479
////////////////////////////////////////////////////////////////////////////////
480
extern void ddi_bc_QueryCfg(ddi_bc_Cfg_t * pCfg);
481
////////////////////////////////////////////////////////////////////////////////
483
//! \brief Shut down the Battery Charger.
487
//! This function immediately shuts down the Battery Charger hardware and
488
//! returns the state machine to the Uninitialized state. Use this function to
489
//! safely �mummify� the battery charger before retiring it from memory.
492
//! \see To view the function definition, see ddi_bc_api.c.
493
////////////////////////////////////////////////////////////////////////////////
494
extern void ddi_bc_ShutDown(void);
495
////////////////////////////////////////////////////////////////////////////////
497
//! \brief Advances the state machine.
501
//! This function advances the state machine.
503
//! \retval DDI_BC_STATUS_SUCCESS If all goes well
504
//! \retval DDI_BC_STATUS_NOT_INITIALIZED If the Battery Charger is not yet
506
//! \retval DDI_BC_STATUS_BROKEN If the battery violated a time-out
507
//! and has been declared broken.
510
//! \see To view the function definition, see ddi_bc_api.c.
511
////////////////////////////////////////////////////////////////////////////////
512
extern ddi_bc_Status_t ddi_bc_StateMachine(void);
513
////////////////////////////////////////////////////////////////////////////////
515
//! \brief Get the Battery Charger's current state.
519
//! This function returns the current state.
521
//! \retval The current state.
524
//! \see To view the function definition, see ddi_bc_api.c.
525
////////////////////////////////////////////////////////////////////////////////
526
extern ddi_bc_State_t ddi_bc_GetState(void);
527
////////////////////////////////////////////////////////////////////////////////
529
//! \brief Disable the Battery Charger.
533
//! This function forces the Battery Charger into the Disabled state.
535
//! \retval DDI_BC_STATUS_SUCCESS If all goes well
536
//! \retval DDI_BC_STATUS_NOT_INITIALIZED If the Battery Charger is not yet
540
//! \see To view the function definition, see ddi_bc_api.c.
541
////////////////////////////////////////////////////////////////////////////////
542
extern ddi_bc_Status_t ddi_bc_SetDisable(void);
543
////////////////////////////////////////////////////////////////////////////////
545
//! \brief Enable the Battery Charger.
549
//! If the Battery Charger is in the Disabled state, this function moves it to
550
//! the Waiting to Charge state.
552
//! \retval DDI_BC_STATUS_SUCCESS If all goes well
553
//! \retval DDI_BC_STATUS_NOT_INITIALIZED If the Battery Charger is not yet
555
//! \retval DDI_BC_STATUS_NOT_DISABLED If the Battery Charger is not
559
//! \see To view the function definition, see ddi_bc_api.c.
560
////////////////////////////////////////////////////////////////////////////////
561
extern ddi_bc_Status_t ddi_bc_SetEnable(void);
562
////////////////////////////////////////////////////////////////////////////////
564
//! \brief Declare the battery to be broken.
568
//! This function forces the Battery Charger into the Broken state.
570
//! \retval DDI_BC_STATUS_SUCCESS If all goes well
571
//! \retval DDI_BC_STATUS_NOT_INITIALIZED If the Battery Charger is not yet
575
//! \see To view the function definition, see ddi_bc_api.c.
576
////////////////////////////////////////////////////////////////////////////////
577
extern ddi_bc_Status_t ddi_bc_SetBroken(void);
578
////////////////////////////////////////////////////////////////////////////////
580
//! \brief Declare the battery to be fixed.
584
//! If the Battery Charger is in the Broken state, this function moves it to
585
//! the Disabled state.
587
//! \retval DDI_BC_STATUS_SUCCESS If all goes well
588
//! \retval DDI_BC_STATUS_NOT_INITIALIZED If the Battery Charger is not yet
590
//! \retval DDI_BC_STATUS_NOT_BROKEN If the Battery Charger is not broken.
593
//! \see To view the function definition, see ddi_bc_api.c.
594
////////////////////////////////////////////////////////////////////////////////
595
extern ddi_bc_Status_t ddi_bc_SetFixed(void);
596
////////////////////////////////////////////////////////////////////////////////
598
//! \brief Set the current limit.
602
//! This function applies a limit to the current that the Battery Charger can
605
//! \param[in] u16Limit The maximum current the Battery Charger can draw
608
//! \retval The expressible version of the limit.
611
//! \see To view the function definition, see ddi_bc_api.c.
612
////////////////////////////////////////////////////////////////////////////////
613
extern uint16_t ddi_bc_SetCurrentLimit(uint16_t u16Limit);
615
////////////////////////////////////////////////////////////////////////////////
617
//! \brief Report the current limit.
621
//! This function reports the limit to the current that the Battery Charger can
624
//! \retval The current limit.
627
//! \see To view the function definition, see ddi_bc_api.c.
628
////////////////////////////////////////////////////////////////////////////////
629
extern uint16_t ddi_bc_GetCurrentLimit(void);
631
////////////////////////////////////////////////////////////////////////////////
633
//! \brief Set the current threshold.
638
//! \param[in] u16Current Current threshold where charger deactivates (in mA).
641
////////////////////////////////////////////////////////////////////////////////
642
extern uint16_t ddi_bc_SetCurrentThreshold(uint16_t u16Current);
644
////////////////////////////////////////////////////////////////////////////////
646
//! \brief Set the battery charger state machine period.
650
//! This function sets a new state machine period. The Period and Slope should
651
//! be coordinated to achieve the minimal ramp step current which will minimize
652
//! transients on the system.
654
//! \param[in] u32StateMachinePeriod (in milliseconds)
655
//! \param[in] u16CurrentRampSlope (in mA/s)
657
//! \retval SUCCESS If all goes well
658
//! \retval ERROR_DDI_BCM_NOT_INITIALIZED If the Battery Charger is not yet
661
////////////////////////////////////////////////////////////////////////////////
662
extern ddi_bc_Status_t ddi_bc_SetNewPeriodAndSlope(uint32_t
663
u32StateMachinePeriod,
665
u16CurrentRampSlope);
667
////////////////////////////////////////////////////////////////////////////////
669
//! \brief Report the state machine period.
673
//! This function reports the battery charger period.
675
//! \retval The battery charger period (in milliseconds).
677
////////////////////////////////////////////////////////////////////////////////
678
extern uint32_t ddi_bc_GetStateMachinePeriod(void);
680
////////////////////////////////////////////////////////////////////////////////
682
//! \brief Report the current ramp slope.
686
//! This function reports the current ramp slope.
688
//! \retval The current ramp slope (in mA/s).
690
////////////////////////////////////////////////////////////////////////////////
691
extern uint32_t ddi_bc_GetCurrentRampSlope(void);
693
////////////////////////////////////////////////////////////////////////////////
695
//! \brief Report the time spent in the present state (milliseconds)
699
//! This function reports the time spent in the present charging state. Note that
700
//! for the states that actually charge the battery, this time does not include the
701
//! time spent under alarm conditions such as die termperature alarm or battery
702
//! temperature alarm.
704
//! \retval The time spent in the current state in milliseconds.
706
////////////////////////////////////////////////////////////////////////////////
707
uint32_t ddi_bc_GetStateTime(void);
709
////////////////////////////////////////////////////////////////////////////////
711
//! \brief Report the reason for being in the broken state
716
//! \retval ddi_bc_BrokenReason_t enumeration
718
////////////////////////////////////////////////////////////////////////////////
719
ddi_bc_BrokenReason_t ddi_bc_GetBrokenReason(void);
721
////////////////////////////////////////////////////////////////////////////////
723
//! \brief Restart the charge cycle
729
////////////////////////////////////////////////////////////////////////////////
730
ddi_bc_Status_t ddi_bc_ForceChargingToStart(void);
732
////////////////////////////////////////////////////////////////////////////////
734
////////////////////////////////////////////////////////////////////////////////
added
removed
arch/arm/mach-stmp378x/include/mach/ddi_bc.h
