手机modem开发（1）---MTK modem NVRAM

1、Modem NVRAM基础知识总结

 

1）Modem NVRAM 四个分区

  

 

nvdata：手机运行过程中，使用(读写)的NVRAM(除了存在protect_f和protect_s中的少数NVRAM)都是该分区的nvram文件。存储着普通NVRAM[1]数据、IMEI、barcode、Calibration数据等。对应的modem path是Z:\NVRAM，对应的AP  path是/data/nvram/md/NVRAM，这是在AP CCCI有做映射，对应的都是nvdata分区modem NVRAM。NVRAM目录下有CALIBRAT、NVD_DATA、NVD_CORE和NVD_IMEI四个目录](Smart Phone中IMPORTANT目录是空的，是Feature Phone遗留下来的)，后续第三点会对这四个目录进行介绍。

protect_1、protect_2 ：一般也称为protect_f和protect_s分区，protect_s是对protect_f中部分NVRAM的复制。主要存储着SIM Lock数据。具有NVRAM_CATEGORY_IMPORTANT_L4属性的NVRAM LID会存在protect_f分区，如果还具有NVRAM_ATTR_MULTIPLE属性，会存一个B文件到protect_s中。正常情况下protect_f中的A文件和protect_s中的B文件是相同的，因为写的时候都会去写两只nvram文件。

nvram：一般也称为binregion分区，是一个备份分区，备份具有NVRAM_CATEGORY_IMPORTANT和NVRAM_CATEGORY_CALIBRAT属性的NVRAM LID，备份的也就是CALIBRAT和NVD_IMEI两个目录，具体有IMEI、 barcode、Calibration数据和4G RF driver[5]参数这些NVRAM。备份可以由META Tool触发 ，ATE校准完会自动触发备份，SN Writer tool写完号后也会自动触发备份。

[1]普通NVRAM是指NVRAM_CATEGORY_USER属性的NVRAM

[2]从Android O1开始(包括Android O1)，AP这边的路径有变化，Modem这边没有变。如下：

Before Android O1(Not Included Android  O1)	After Android O1( Included Android  O1)
/data/nvram/md/NVRAM/	/vendor/nvdata/md/NVRAM/
/protect_f/md/	/vendor/protect_f/md/
/protect_s/md/	/vendor/protect_s/md/

[3]93Modem开始除了之前的四个目录，多了BACKUP目录。目前该目录下面没有nvram文件，手机运行时也不会使用该目录下的文件，详细可以参考FAQ09435 1.2中的NVRAM_ATTR_ RESERVE_BACKWARD属性。

[4]严格来说，IMPORTANT目录，只有在WR8.W1231.DC.WG.MP上还是存着SIM Lock，从WR8.W1244.DNR.WG.MP开始的Smart Phone版本都将SIM Lock存到protect_f和protect_s中了。

[5]不过从92Modem(92Modem的含义请参考最后[参考]中的第1点)开始有将部分4G RF Driver修改为NVRAM_CATEGORY_USER属性，并添加了NVRAM_ATTR_SW_VERNO_RESET属性 (93Modem修改NVRAM_ATTR_SW_VERNO_RESET为NVRAM_ATTR_OTA_RESET)

         MT67XX_Android_scatter.txt文件记录着各分区的信息，SP Flash Tool下载时，选择的scatter file就是这个文件。如搜索nvdata，protect1，protect2，nvram，可以查看各个分区的起始地址和大小。像分析问题时需要readback出备份binregion分区时，就要去该文件确认起始地址和大小。

 

 2. 升级方式对各个NVRAM分区的影响

Format All+Download

会擦除所有分区，所有NVRAM LID都会用code中的默认值重新生成。全擦后只有触发备份过，binregion中才会有备份内容，否则binregion是空的(Flash默认的全0 or 全f)。

Firmware Upgrade 、Factory Reset(恢复出厂设置)

只会擦除nvdata分区，开机时AP会将binregion中备份的CALIBRAT和NVD_IMEI两个目录还原到nvdata分区。具体NVRAM LID是IMEI、 barcode、Calibration数据和4G RF driver参数。

protect_f和protect_s分区不会被擦除，所以SIM Lock保持不变。

其他NVRAM LID恢复为code中的默认值。

如果binregion是空的，那么IMEI、 barcode、Calibration数据和4G RF driver参数也会用code中的默认值重新生成。

Download Only、OTA、SD upgrade 、Push modem

不会擦除任何分区。这种升级方式下，如果有修改code中的default值，那么需要将相应NVRAM LID的VERNO+1，才会生效，即将会利用code中的默认值重新生成新文件。

  注意：这里所说的所有分区和任何分区均指Modem NVRAM的四个分区：nvdata分区、 protect_f分区、protect_s分区和binregion分区。

 

3. NVRAM LID数据结构

 

NVRAM LID table就是由一个个具体NVRAM LID的结构构成。包括9项参数：LID，total_records，size， default_value，category，attr， fileprefix，fileverno，description。

这里以NVRAM_EF_EL1_BAND_INDICATOR_LID为例进行详细介绍，如上图所示。

NVRAM_EF_EL1_BAND_INDICATOR_LID， LID，NVRAM LID枚举名

NVRAM_EF_EL1_BAND_INDICATOR_TOTAL，total_records，当前NVRAM LID的record总个数

NVRAM_EF_EL1_BAND_INDICATOR_SIZE， size，每个record的size

NVRAM_DEFAULT_FUNC(nvram_get_eL1_default_value_to_write)，default_value，默认值来源

NVRAM_CATEGORY_CALIBRAT | NVRAM_CATEGORY_FUNC_DEFAULT，category，具有的category属性

NVRAM_ATTR_MULTIPLE，attr，attribute属性

“EL2T”，fileprefix[4+1]，文件名前缀，构成文件名前缀，必须四位，且是0000~ZZZZ，且必须整个工程唯一

VER(NVRAM_EF_EL1_BAND_INDICATOR_LID)，fileverno[3+1]，文件版本号，构成文件名后缀，必须三位，且是000~999，实际对应的是NVRAM_EF_EL1_BAND_INDICATOR_LID_VERNO

description，目前对于Smart Phone平台来说都是NULL，没有使用，是Feature Phone遗留下来的

 

4.NVRAM LID的category属性和attribute属性

         NVRAM LID的category属性和attribute属性的含义可以参考FAQ09435。

        下面对NVRAM目录下的CALIBRAT、NVD_DATA、NVD_CORE和NVD_IMEI四个目录进行介绍：

具有NVRAM_CATEGORY_USER属性的NVRAM，会存到/data/nvram/md/NVRAM/NVD_DATA/目录。里面存的是普通NVRAM，2G RF driver NVRAM，3G RF driver NVRAM。(从92Modem开始有将部分4G RF driver NVRAM从CALIBRAT属性修改为USER属性，也就是从CALIBRAT目录移到了NVD_DATA目录)

具有NVRAM_CATEGORY_INTERNAL属性的NVRAM，会存到/data/nvram/md/NVRAM/NVD_CORE/目录。里面只存了NVRAM_EF_SYS_LID这只NVRAM，由于具有NVRAM_ATTR_MULTIPLE属性，该目录下有A，B两只文件。

具有NVRAM_CATEGORY_CALIBRAT属性的NVRAM，会存到/data/nvram/md/NVRAM/CALIBRAT/目录。里面存了barcode，calibration NVRAM，部分4G RF driver NVRAM。

具有NVRAM_CATEGORY_IMPORTANT属性的NVRAM，会存到/data/nvram/md/NVRAM/NVD_IMEI/目录。80/90/91Modem里面只存了NVRAM_EF_IMEI_IMEISV_LID(IMEI)这只NVRAM。 92Modem添加了NVRAM_EF_NVRAM_LOCK_LID(IMEI Lock)这只NVRAM。93Modem新加入了5只NVRAM(C2K相关的3只NVRAM)。

具有NVRAM_CATEGORY_IMPORTANT_L4属性的NVRAM，会存到/protect_f/md/目录，如果该NVRAM具有NVRAM_ATTR_MULTIPLE属性，会有相应的B文件存在/protect_s/md/目录。里面存了NVRAM_EF_SML_LID(SIM Lock)， NVRAM_EF_SIM_LOCK_LID(也是SIM Lock，默认不会用到) ，NVRAM_EF_IMPT_COUNTER_LID(这只NVRAM可以不用care，没实用，从92Modem开始移到了NVD_DATA)。 93Modem新加入了3只NVRAM。

        Build modem生成的/build/.../nvram_auto_gen目录下的~nvram_lid_information.log和~nvram_lid_size.log文件，可以查看每支NVRAM LID真实的category和attribute。分析nvram问题经常需要提供这两只文件协助分析。

~nvram_lid_information.log包括如下7项信息：

LID:                 LID的枚举值

LID(String):   LID的名字

Filename:      文件名前缀

Verno:            NVRAM LID相应的VERNO号

Description:  目前对于Smart Phone平台来说都是NULL

Category:      具有的CATEGORY属性，参考FAQ09435可以计算得到相应的CATEGORY属性

Attribute:      具有的ATTR属性，参考FAQ09435可以计算得到相应的ATTR属性

~nvram_lid_size.log包括如下3项信息：

LID:                LID的枚举值

size:               整个nvram文件大小

LID(String):   LID的名字

  

5. 修改NVRAM的默认值，如何生效

  根据2. 升级方式对各个NVRAM分区的影响：

因为Format All+Download会擦除所有分区，所以修改任何NVRAM的默认值，然后 Format All+Download升级，均可生效。

因为Firmware Upgrade 只会擦除nvdata分区，所以修改普通NVRAM(NVRAM_CATEGORY_USER属性的NVRAM)的默认值，然后Firmware Upgrade升级，可以生效。但是修改具有备份的NVRAM(IMEI、 barcode、Calibration数据和4G RF driver)或者存在protect_f/protect_s分区的SIM Lock的默认值，是不会生效的。如修改备份的4G RF driver NVRAM LID的默认值，Firmware Upgrade升级不生效 ：

这是因为备份的4G RF driver NVRAM LID具有NVRAM_CATEGORY_CALIBRAT属性，在binregion中有备份，当Firmware Upgrade升级擦除nvdata分区后，开机后会从binregion中还原回来。

针对这种情况，想要修改默认值生效，Firmware Upgrade升级也是需要将相应的NVRAM LID VERNO+1。

因为Download Only、OTA、SD upgrade 、Push modem不会擦除任何分区，所以如果有修改code中的default值，想升级后生效，那么需要将相应NVRAM LID的VERNO+1，才会生效，这样将会利用code中的默认值重新生成新nvram文件。

原理：在flash上存储的NVRAM 对应的文件名是由文件名前缀，中间连接符和文件名后缀构成。文件名后缀就是NVRAM LID对应的VERNO。那么代码中将对应的NVRAM LID VERNO+1后，去flash上面读写这只文件的时候，就会发现不存在，那么就会用code中的默认值重新生成新文件[1]。

假设修改的是NVRAM_EF_IMS_PROFILE_LID这只NVRAM的默认值，它的文件名前缀MT79，升级前的NVRAM_EF_IMS_PROFILE_LID_VERNO号是000，修改默认值后将NVRAM_EF_IMS_PROFILE_LID_VERNO修改为001，那么Download Only升级前/data/nvram/md/NVRAM/NVD_DATA/目录中就有MT79_000这只文件。升级后，当读写到这只NVRAM的时候，是按MT79_001去NVD_DATA目录找这只文件，发现没有就会用代码中的默认值重新生成新文件MT79_001。

        [1]注意：并不是所有的NVRAM LID都可以通过VERNO+1的方式来升级:

        (1)具有NVRAM_CATEGORY_IMPORTANT或NVRAM_CATEGORY_IMPORTANT_L4属性的NVRAM LID不能通过VERNO+1方式升级，否则就会有modem assert，如NVRAM_EF_IMEI_IMEISV_LID(IMEI)和NVRAM_EF_SML_LID(SIM Lock)，这是我们的design，是对IMEI和SIM Lock的保护。

        (2)校准NVRAM LID和Barcode(NVRAM_EF_BARCODE_NUM_LID)也不能通过VENRO+1的方式升级，否则校准参数/Barcode就丢失了，不过一般也不会有这类需求。

        (3)部分RF NVRAM LID也不能通过VERNO+1的方式升级，目前明确的有CA组合和RF support band不行，如有修改必须全擦升级。其他的需要请RF同仁根据具体情况进行具体分析。(91Modem可以参考DCC上面的MT6176 LTE RF Customization NVRAM LID  OTA information (for Customer).pdf)

 

6. NVRAM默认值和对应VENRO的定义位置

  请参考FAQ19509

 

7. 如何客制化NVRAM LID

(1)80/90/91/92Modem请参考DCC上的Modem_NVRAM_to_Customer(Smart_Phone).docx文档的Page16~Page22页。

(2)93Modem请参考DCC上的CS0021-GAA5A-UMD-V1.1EN_Platform_System_Storage_and_Filesystem_Modem_NVRAM_User_Manual.docx文档的7.1.2章节

 

8. 如何在AP端读写Modem NVRAM

        AP端去读写Modem NVRAM，可以通过AP端向modem发送AT Command，而modem端需要客制化一条AT Command，同时在command handler中调用接口进行读写nvram。

        步骤如下：

        (1)AP端向Modem透传AT命令，AP端具体做法可以参考FAQ19648【如何发送AT命令】。

        (2)Modem端对AT命令进行客制化，具体可以参考FAQ17997【[AT Command]Smart Phone如何客制化AT command】。

        (3)command handler内部通过调用nvram_external_read_data/nvram_external_write_data来读写。

        kal_bool nvram_external_read_data(nvram_lid_enum LID, kal_uint16 rec_index, kal_uint8 *buffer, kal_uint32 buffer_size);

        kal_bool nvram_external_write_data(nvram_lid_enum LID, kal_uint16 rec_index, kal_uint8 *buffer, kal_uint32 buffer_size);

        注意：从91Modem开始读写IMEI和SIM Lock只能使用nvram_external_secure_read_data/nvram_external_secure_write_data接口，不能使用nvram_external_read_data/nvram_external_write_data。

        nvram_errno_enum nvram_external_secure_read_data(nvram_lid_enum LID, kal_uint16 rec_index, kal_uint8 *buffer, kal_uint32 buffer_size, void* reserved_ptr);

        nvram_errno_enum nvram_external_secure_write_data(nvram_lid_enum LID, kal_uint16 rec_index, kal_uint8 *buffer, kal_uint32 buffer_size, void* reserved_ptr);