#include <twl/spi.h>u32 PM_GetBatteryLevel( u16* levelBuf );
| levelBuf | Buffer storing the remaining battery life for the battery pack. |
If PM_RESULT_SUCCESS, the command was run successfully.
If PM_RESULT_BUSY, the SPI was occupied by other processing and unable to process this function.
If PM_RESULT_ERROR, this function could not be used. This error means that this function was called during operation in NITRO mode. It will not be returned in any other situation.
If the command succeeded, a value indicating the remaining battery life of the battery pack will be stored at the address indicated by levelBuf. This value indicates one of six levels, from 0 (PM_BATTERY_LEVEL_MIN) to 5 (PM_BATTERY_LEVEL_MAX). Smaller values indicate that there is less battery life remaining.
Checks the remaining battery capacity of the battery pack.
This function uses PXI to send the command that performs the corresponding operation in the ARM7 processor. The ARM7 side that receives that command is executed by operating the PMIC.
A return value of PM_RESULT_SUCCESS indicates that the command was run successfully, and that the results are stored at the address given by the u16-type pointer levelBuf. This value indicates one of six levels, from 0 (PM_BATTERY_LEVEL_MIN) to 5 (PM_BATTERY_LEVEL_MAX). Smaller values indicate that there is less battery life remaining.
| Value Stored in levelBuf | Remaining Battery Life (Approximately) | LED Color on TWL |
|---|---|---|
5 (PM_BATTERY_LEVEL_MAX) |
100% | ■ Blue (steady light) |
| 4 | 60% | |
| 3 | 30% | |
| 2 | 10% | ■ Red (steady light) |
| 1 | 1% | ■■ Red (blinking light) |
0 (PM_BATTERY_LEVEL_MIN) |
0% |
The color and steady/blinking status of the LED cannot be controlled by applications.
The remaining battery charge level is only a guideline. There may be some error due to individual differences or degree of degradation between battery packs. For example, a value of 2 stored in levelBuf represents a 10% charge, but this does not mean that this value results when a 10% charge level is reached. Be sure to take this as an approximate guideline with a wide degree of variation. The actual remaining charge could be 5 or 20 percent. The remaining battery charge is split into 6 levels, and is one index used only by TWL units. As such, calculation of a standard value for remaining battery charge time based on the obtained charge level is impossible.
Internally, the remaining battery life will only change approximately once per second. If the backlight brightness is suddenly changed from the lowest to the highest setting and this causes the remaining battery life to drop by a sudden discrete amount in hardware terms, when the microprocessor checks remaining battery life, it will adjust its results to return continuous values.
However, this does not apply to applications that do not require exit processing, do not use SD Card or NAND memory, and which are likely to use up the battery completely (in other words, card applications). Even if you set a battery LOW callback for such applications, it is possible for remaining battery life to suddenly decrease past the point where the callback would have been called, until it reaches the forced shutdown level and the power is cut off.
When a value of 1 is detected for the remaining battery life, the callback function set by the PM_SetBatteryLowCallback function will be invoked to send a notification that the remaining battery life is low. However, as indicated by Getting Values Internally, in applications such as card applications that do not require exit processing, internal values change discretely and may skip directly to 0. In such a case, the callback will not be invoked.
In applications that require shutdown processing, such as NAND applications, the microprocessor adjusts the values, so there is no chance of values changing discretely and the callback being missed as a result. If it detects a remaining battery level of 0, the hardware will perform shutdown processing. Shutdown processing is not performed for applications that do not use SD Cards or NAND memory.
The PM_GetBattery function is similar to PM_GetBatteryLevel, but it can only get the remaining battery life as one of two levels. It is structured this way because the NITRO hardware was aware of only two levels of remaining battery life.
This function only operates on TWL hardware running in TWL mode. It cannot be used on NITRO hardware or TWL hardware running in NITRO mode. The function can be called, but it will return PM_RESULT_ERROR. The function will not return PM_RESULT_ERROR in TWL Mode.
The SPI is used for various other processes besides power management. If you call this function while another process is using it, this function sends a command to the ARM7. There, the SPI is determined to be BUSY, and PM_RESULT_BUSY is notified to the ARM9 without actually processing this function. Likewise, if you call this function while another PM process is running, that fact is determined on the ARM9 side, and this function returns PM_RESULT_BUSY. (In this case, the determination is made before notification is sent to the ARM7.)
Accordingly, if you want to ensure that this function succeeds, make it loop until it succeeds as shown below. (This example does not take into account mistakes such as wrong arguments.)
Example
while( PM_GetBatteryLevel( ... ) != PM_RESULT_SUCCESS )
{
}
PM_GetBattery
PM_SetBatteryLowCallback
2009/06/03 Removed a description of the PM_Init function (because OS_Init is now required).
2008/11/11 Adjusted the guidelines for the remaining battery life.
2008/08/23 Mentioned PM_RESULT_BUSY.
2008/04/09 Adjusted the guidelines for the remaining battery life.
2008/02/07 Added guidelines for the remaining battery life.
2008/01/24 Initial version.
CONFIDENTIAL