diff --git a/drivers/power/bq27426_fg_mmi/README b/drivers/power/bq27426_fg_mmi/README index ed65a644bc7e..ef9435a7d0d9 100644 --- a/drivers/power/bq27426_fg_mmi/README +++ b/drivers/power/bq27426_fg_mmi/README @@ -1,13 +1,189 @@ -The following files were automatically generated by TI FG tool. -- bq27426_gmfs_coslight.h -- lenovo_atl_df1_gmfs.h +Motorola Mobility. BQ27426 Fuel Gauge Specific Bindings -In case new battery profile is used, make sure to include: -- reference in Android.mk -- reference in Kbuild -- generated Header file with respect to the battery profile given by Texas Instruments +This is a brief introduction on bq27426_fg_mmi, based on previous developments, +but edited and improved by Motorola. It is a DLKM, and messages on kernel logs +may be tagged as: +- "bq27426" +- "bq27426_bms" +- or no tag, if it's happening during probe + +This driver has the following components: +- README - this file :) +- build files (Makefile, Kbuild, Android.mk) +- command files (bqfs_cmd_type.h), which is the basic structure to interpret +the Battery Profile Header file. +- driver implementation (bq27426_fg_mmi.c) + +One of the main architectural differences in between Texas Instruments and +Qualcomm Fuel Gauge drivers is: +- battery profile format (QCOM provides as a .dtsi file, while TI shares it +as a .gm.fs) +- battery profile addition (as a DT file, QCOM requires it to be included on +OEM DT, while TI statically adds a battery profile to the driver itself). + +The following sections better detail the DT and how to add a battery profile to +a product. + +================================== + Mandatory Device Tree properties +================================== + +- design-capacity + Usage: mandatory + Value Type: + Definition: Defines maximum battery capacity, in mAh. + +- chem_id + Usage: mandatory + Value Type: + Definition: Each battery model has a unique identifier, called by Texas +Instruments as "Chemical ID" (or chem-id). This value is hard-stored to the +battery, and can be queried, similar to battery ID resistance in Qualcomm +architecture. This values comes from Texas Instruments Battery +Characterization Data. + +- serialnum + Usage: mandatory + Value Type: + Definition: Each battery model also has Serial Number, defining that battery +model. This is a reference value, not stored inside battery, but necessary to +control and differentiate battery models. This is a requirement per Texas +Instruments original Device Drive. + +================================= + Optional Device Tree properties +================================= + +- mmi,fg-batt-main + Usage: optional + Value Type: + Definition: Determines that component is measuring main battery. This is +helpful when using a dual battery architecture, to differentiate main and +flip batteries. + +- mmi,fg-batt-flip + Usage: optional + Value Type: + Definition: Determines that component is measuring flip battery. This is +helpful when using a dual battery architecture, to differentiate main and +flip batteries. + +======================================= + Performing a Battery Characterization +======================================= + +EE (Electronics Engineering), or Hardware Team starts this process. First, a +battery sample is requested from supplier. Then Texas Instruments is contacted +to verify how many samples they need to perform this characterization. + +At this point, it is important to emphasize to Texas Instruments that Fuel +Gauge data is stored on device runtime, and not on a test jig or factory, +because on the latter case, they will send a set of files to be used with a +specific software and hardware solution to hotplug the FG chip and store FG +characterization data. + +What Motorola needs is a file having .gm.fs extension containing command and +data sequence. This is also part of Texas Instruments process, so doesn't take +any extra effort/service on then to provide such data. + +Having that file, it is necessary to execute "battery_profil/convbqfs.pl" Perl +script. Parameters are: + +convbqfs.pl --input [--output {output file}] [--line] [--name {array name}] + if output file is not specified, default name is same with input file name with .h extension +Example: + convbqfs.pl --input bq27320.df.fs + convbqfs.pl --input bq27320.df.fs --output bq27320-bqfs-image.h + convbqfs.pl --input bq27320.df.fs --output bq27320-bqfs-image.h --line + convbqfs.pl --input bq27320.df.fs --output bq27320-bqfs-image.h --name bqfs_image + +===================================== + Adding a Battery Profile to Product +===================================== + +After file conversion is done by the Perl script, a .h file is generated. As a +recommended standard, files having this extension go to +"battery_profile/imported" folder, while .gm.fs files go to +"battery_profile/raw" folder. + +Once there, first step is to modify the Device Tree with the abovementioned DT +properties. Here's an example: + +bq27426_main: bq27426-battery-main@55 { + compatible = "ti,bq27426"; + reg = <0x55>; + status = "okay"; + pinctrl-names = "default"; + pinctrl-0 = <&bq27426_irq_main>; + interrupt-parent = <&tlmm>; + interrupts = <119 0>; + interrupt-names = "bq27426_irq"; + mmi,fg-batt-main; + design-capacity = <1400>; + battery_profile_0 { + chem_id = <2542>; + serialnum = "SB18C54570"; + }; + battery_profile_1 { + chem_id = <5>; + serialnum = "SB18C54580"; + }; +}; -"bqfs_cmd_type.h" is the basic structure to interpret the Battery Profile Header file. +It is also recommended to add multiple profiles as "battery_profile_X", being X +an incremental number starting from 0, based on which profile came first to +the product. -Battery profiles provided by TI are in "battery_profile" folder. +Once there, next step is to change /device/moto//device.mk file, +adding a makefile variable to the battery. Example: + +ATL_4000MAH_8A_BATTERY_PROFILE := true +ATL_LS30_1255MAH_BATTERY_PROFILE := true + + +Later, with this variable, a CFlag can be created on +"bq27426_fg_mmi/Android.mk". Example: + +ifneq ($(filter m y,$(CONFIG_ATL_LS40_1545MAH_BATTERY_PROFILE)),) + EXTRA_CFLAGS += -DATL_LS40_1545MAH_BATTERY_PROFILE +endif + + +Next step is to add a Kernel CFlag using previous flag on +"bq27426_fg_mmi/Kbuild". Example: + +ifeq ($(SCUD_4000MAH_8A_BATTERY_PROFILE),true) + KERNEL_CFLAGS += CONFIG_SCUD_4000MAH_8A_BATTERY_PROFILE=y +endif + + +Finally, to include battery profile to the driver implementation, on +"bq27426_fg_mmi/bq27426_fg_mmi.c". Example: + +#ifdef ATL_4000MAH_8A_BATTERY_PROFILE +#include "battery_profile/imported/lenovo_atl_df1_gmfs.h" +#endif + +=========================== + Dual Battery Architecture +=========================== + +Although each battery has its own Fuel Gauge chip, main system is unaware of +anything different than the FG chip from the original architecture. In other +words, great are the chances you are implementing this dual battery solution +based on Qualcomm architecture, which uses either QG or FG-Gen4 Fuel Gauge +algorithms. + +So, QCOM FG system will still wait for battery data, which should exist as a +single battery. That means original system needs to receive some "fake" data, +although reliable enough to not break anything else. + +For such, first step is to prepare a single package sample (for that, ask EE +Team to join both batteries in parallel, into a single package, having a small +internal resistance, separating each one. Few units (probably 03) of those +packages will be requested by Qualcomm to be characterized. + +From here on, this package is handled as a single battery, and as a result, a +Device Tree file (dtsi) will be shared via proper QCOM SR, which needs to be +properly integrated, as most MOT products.