GS2K Memory Map and File System Application Note
80560NT11600A Rev. 2.1 – 2017-09-27
GS2K Memory Map and File System Application Note
SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE
NOTICE
While reasonable efforts have been made to assure the accuracy of this document, Telit assumes no liability resulting from any inaccuracies or omissions in this document, or from use of the information obtained herein. The information in this document has been carefully checked and is believed to be reliable. However, no responsibility is assumed for inaccuracies or omissions. Telit reserves the right to make changes to any products described herein and reserves the right to revise this document and to make changes from time to time in content hereof with no obligation to notify any person of revisions or changes. Telit does not assume any liability arising out of the application or use of any product, software, or circuit described herein; neither does it convey license under its patent rights or the rights of others. It is possible that this publication may contain references to, or information about Telit products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that Telit intends to announce such Telit products, programming, or services in your country. COPYRIGHTS
This instruction manual and the Telit products described in this instruction manual may be, include or describe copyrighted Telit material, such as computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and its licensors certain exclusive rights for copyrighted material, including the exclusive right to copy, reproduce in any form, distribute and make derivative works of the copyrighted material. Accordingly, any copyrighted material of Telit and its licensors contained herein or in the Telit products described in this instruction manual may not be copied, reproduced, distributed, merged or modified in any manner without the express written permission of Telit. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit, as arises by operation of law in the sale of a product. COMPUTER SOFTWARE COPYRIGHTS
The Telit and 3rd Party supplied Software (SW) products described in this instruction manual may include copyrighted Telit and other 3rd Party supplied computer programs stored in semiconductor memories or other media. Laws in the Italy and other countries preserve for Telit and other 3rd Party supplied SW certain exclusive rights for copyrighted computer programs, including the exclusive right to copy or reproduce in any form the copyrighted computer program. Accordingly, any copyrighted Telit or other 3rd Party supplied SW computer programs contained in the Telit products described in this instruction manual may not be copied (reverse engineered) or reproduced in any manner without the express written permission of Telit or the 3rd Party SW supplier. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit or other 3rd Party supplied SW, except for the normal non-exclusive, royalty free license to use that arises by operation of law in the sale of a product.
80560NT11600A Rev. 2.1 Page 2 of 51 2017-09-27 GS2K Memory Map and File System Application Note
USAGE AND DISCLOSURE RESTRICTIONS
I. License Agreements
The software described in this document is the property of Telit and its licensors. It is furnished by express license agreement only and may be used only in accordance with the terms of such an agreement. II. Copyrighted Materials
Software and documentation are copyrighted materials. Making unauthorized copies is prohibited by law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, without prior written permission of Telit III. High Risk Materials
Components, units, or third-party products used in the product described herein are NOT fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control equipment in the following hazardous environments requiring fail-safe controls: the operation of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air Traffic Control, Life Support, or Weapons Systems (High Risk Activities"). Telit and its supplier(s) specifically disclaim any expressed or implied warranty of fitness for such High Risk Activities. IV. Trademarks
TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners. V. Third Party Rights
The software may include Third Party Right software. In this case, you agree to comply with all terms and conditions imposed on you in respect of such separate software. In addition to Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this License shall apply to the Third Party Right software. TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES EXPRESS OR IMPLIED FROM ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY MATERIALS FROM WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE USE OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH THE SOFTWARE, INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY QUALITY OR FITNESS FOR A PARTICULAR PURPOSE. NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY, ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE OR THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSE AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
80560NT11600A Rev. 2.1 Page 3 of 51 2017-09-27 GS2K Memory Map and File System Application Note
APPLICABILITY TABLE
PRODUCT
GS2K based Modules
SW Version
5.1.7/5.2.1 onwards
Note: The features described in the present document are provided by the products equipped with the software versions equal or higher than the versions shown in the table. See also the Revision History chapter.
80560NT11600A Rev. 2.1 Page 4 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Revision History
Version Date Remarks
1.0 July,2014 First issue
1.1 July,2014 Updated Module Memory Map
1.2 Oct,2014 Added in Module Flash File System
1.3 Feb,2015 Updated Super Block
1.4 Apr,2015 Added Memory Maps for GA Releases
Updated Super block, Control block, and Memory maps for GA 1.5 Apr,2015 Releases.
Apr,2015 Reworked on the review comments. 1.6 May,2015 Updated Application firmware and WLAN firmware models
Updated Super block, Control block, and Memory maps for GA 1.7 July,2015 Releases.
Added the reserved block in the memory maps and details of the 1.8 Aug,2015 difference between 5.1.X and 5.2.X control block.
Updated data in the Fig: Two Firmware Model for 5.2.0 Beta Release 1.9 Sept,2015 (4MB)
2.0 June,2016 Added Memory Map for 5.3.0 Release.
Added Appendix for Creating Maximum supported dynamic file 2.1 Sept-2017 system.
80560NT11600A Rev. 2.1 Page 5 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Table of Contents
NOTICE………...... 2
COPYRIGHTS …………………………………………………………………………………………..2
COMPUTER SOFTWARE COPYRIGHTS ...... 2
USAGE AND DISCLOSURE RESTRICTIONS ...... 3
APPLICABILITY TABLE ...... 4
CHAPTER 1. OVERVIEW ...... 10
1.1 PURPOSE ...... 10 1.2 SCOPE ...... 10 1.3 INTRODUCTION ...... 10 1.4 TERMINOLOGY ...... 10 CHAPTER 2. MODULE MEMORY MAP ...... 11
2.1 FLASH ...... 11 2.1.1 Super Block ...... 12 2.1.2 Firmware Block ...... 14 2.1.3 Dynamic File System ...... 18 2.2 SRAM ...... 20 2.3 RTC ...... 21 2.4 OTP ...... 21 2.5 ROM ...... 21 CHAPTER 3. MODULE FLASH FILE SYSTEM ...... 22
3.1 STATIC FILE SYSTEM ...... 22 3.1.1 Creating Static File System ...... 22 3.1.2 Modifying Static File System ...... 24 3.2 DYNAMIC FILE SYSTEM ...... 29 CHAPTER 4. EXTERNAL FLASH MEMORY MAP ...... 30
4.1 APPLICATION SUPER BLOCK ...... 31 4.2 FIRMWARE BLOCK ...... 31 4.2.1 Control Block ...... 31 4.2.2 Static File System ...... 32 4.2.3 Backup of Control Block ...... 32 4.3 DYNAMIC FILE SYSTEM ...... 32 CHAPTER 5. EXTERNAL FLASH FILE SYSTEM ...... 33
5.1 STATIC FILE SYSTEM ...... 33 5.1.1 Creating Static File System ...... 33 5.1.2 Modifying Static File System ...... 33 5.2 DYNAMIC FILE SYSTEM ...... 35 CHAPTER 6. MEMORY MAPS FOR GA RELEASES ...... 36
6.1 MEMORY MAP FOR 5.1.4, 5.1.5, 5.1.6, 5.1.7 GA RELEASES ...... 36 6.2 MEMORY MAP FOR 5.2.0, 5.2.1, AND 5.2.3 RELEASES ...... 41 6.3 MEMORY MAP FOR 5.3.0 RELEASE ...... 45 APPENDIX A CREATING MAXIMUM SUPPORTED DYNAMIC FILE SYSTEM ...... 49
80560NT11600A Rev. 2.1 Page 6 of 51 2017-09-27 GS2K Memory Map and File System Application Note
List of Figures
Figure 1: Memory Flash ...... 11
Figure 2: Super Block ...... 12
Figure 3: Boot ROM Super Block for Three Firmware Model ...... 12
Figure 4: Boot App Control Block ...... 14
Figure 5: Control Block in module flash ...... 15
Figure 6: SRAM Layout ...... 20
Figure 7: RTC Layout ...... 21
Figure 8: Web_page.FFS ...... 23
Figure 9: FILEDIR Folder ...... 23
Figure 10: Web Imager Folder ...... 24
Figure 11: Creating Web Image Binary ...... 24
Figure 12: Webpage file system location ...... 25
Figure 13: Super block ...... 26
Figure 14: Control block ...... 26
Figure 15: Modified Third Block descriptor ...... 27
Figure 16: Modified web_page.FFS ...... 27
Figure 17: New Webpage file system ...... 28
Figure 18: Modified Embedded File System Interface code ...... 29
Figure 19: External flash ...... 30
Figure 20: Control Block in external flash ...... 31
Figure 21: Super block ...... 34
Figure 22: Control block ...... 34
Figure 23: Two Firmware Model for 5.1.4,5.1.5, 5.1.6, and 5.1.7 GA Releases (2MB) ...... 37
Figure 24: Three Firmware Model for 5.1.4,5.1.5, 5.1.6, and 5.1.7 GA Releases (2MB) ...... 38
Figure 25: Two Firmware Model for 5.1.4,5.1.5, 5.1.6, and 5.1.7 GA Releases (4MB) ...... 39
Figure 26: Three Firmware Model for 5.1.4,5.1.5 and 5.1.6 GA Releases (4MB) ...... 40
Figure 27: Two Firmware Model for in 5.2.0, 5.2.1, and 5.2.3 releases (2MB) ...... 42
Figure 28: Two Firmware Model for 5.2.0, 5.2.1, and 5.2.3 releases (4MB) ...... 43
Figure 29: Three Firmware Model for 5.2.0, 5.2.1, and 5.2.3 releases (4MB) ...... 44
Figure 30: Two Firmware Model for in 5.3.0 release (2MB) ...... 46
80560NT11600A Rev. 2.1 Page 7 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Figure 31: Two Firmware Model for 5.3.0 release (4MB) ...... 47
Figure 32: Three Firmware Model for 5.3.0 release (4MB) ...... 48
80560NT11600A Rev. 2.1 Page 8 of 51 2017-09-27 GS2K Memory Map and File System Application Note
List of Tables
Table 1: Glossary of Terms ...... 10
Table 2: Macros for Webpage File System in Embedded File System Interface Code ...... 29
Table 3: Macros for Static file system in Embedded File System Interface Code ...... 35
80560NT11600A Rev. 2.1 Page 9 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Chapter 1. Overview
1.1 PURPOSE
This document provides an overview about the Memory map and the types of file systems used in GS2000 modules. 1.2 SCOPE
This document reviews the architecture of the Memory map and file systems used and provides with necessary information required to understand and modify file systems. This document assumes that the reader is generally familiar with GainSpan SoC products, Internet Protocol (IP) networks and the operation and management of 802.11 wireless devices. 1.3 INTRODUCTION
GS2000 modules use different types of memory maps and file systems to control how data is stored and retrieved. Applications use these memory maps and file system to track, organize, store, and retrieve files during various operations. 1.4 TERMINOLOGY
The following table lists the terminology used throughout this document.
Table 1: Glossary of Terms
Term Explanation
SB Super block
CB Control block
BCB Backup of control block
80560NT11600A Rev. 2.1 Page 10 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Chapter 2. Module Memory Map
The in-module memory map for GS2000 contains:
• Flash • SRAM • RTC • OTP • ROM 2.1 FLASH
Memory map in module flash contains Super block, Firmware blocks, and File systems. The size of the memory map in GS2011M is 4MB and GS2100M is 2MB. The memory map of an in- built module flash in a GS2000 based module is as shown below.
Figure 1: Memory Flash
The memory map of module flash contains:
• Super Block • Firmware Block • Dynamic File System
80560NT11600A Rev. 2.1 Page 11 of 51 2017-09-27 GS2K Memory Map and File System Application Note
2.1.1 Super Block The Super block consists of the following fields:
Figure 2: Super Block
2.1.1.1 Boot ROM Super Block
The Boot ROM Super block consists of the following fields:
Figure 3: Boot ROM Super Block for Three Firmware Model
• Signature: It is a four byte ‘FLOK’ string to indicate that Super block has been read. • FW0 Control Block Address: It contains Control block address for the Boot application’s FW0 firmware.
80560NT11600A Rev. 2.1 Page 12 of 51 2017-09-27 GS2K Memory Map and File System Application Note
• FW0 Backup of Control Block Address: It is the backup of control block address for the Boot application’s firmware. • FW1 Control Block Address: It is filled with invalid address as there is only one boot application in Boot ROM Super Block. • FW1 Backup of Control Block Address It is filled with invalid address as there is only one boot application in Boot ROM Super Block. • FW2 Control Block Address It is filled with invalid address as there is only one boot application in Boot ROM Super Block. • FW2 Backup of Control Block Address It is filled with invalid address as there is only one boot application in Boot ROM Super Block. • Factory Default Location: It contains the factory default elements such as OTP or Flash address. It is reserved for future use. • Factory Default Size: It is the total content size of the factory default elements. It is reserved for future use. • Factory Default Address: It is the starting address of the factory default elements (OTP or flash address). It is reserved for future use. • File system Address: It is the address of the Dynamic file system which will contain configuration files. • File system Size: It is the total size of the Dynamic file system. • DMA Read Control Word: It is the Read control word for flash interface. • DMA Controller Clock Divider: It is the clock divider of the DMA controller which is used to access the flash interface. • DMA Read Command: It is the read command OPCODE for reading the flash. This is always set to QUAD IO FAST READ (0xEB)
2.1.1.2 Boot App Super Block
It contains the similar structure of Boot ROM Super Block and consists of the following fields for a three-firmware model:
• Signature: It is a four byte ‘FLOK’ string to indicate that Super block has been read. • FW0 Control Block Address: It is the Control block address for the FW0 Firmware block. • FW0 Backup of Control Block Address: It is the backup of control block address for the FW0 Firmware block. • FW1 Control Block Address: It is the Control block address for the FW1 Firmware block. • FW1 Backup of Control Block Address: It is the backup of control block address for the FW1 Firmware block. • FW2 Control Block Address: It is the Control block address for the FW2 Firmware block. • FW2 Backup of Control Block Address: It is the backup of control block address for the FW2 Firmware block. • Factory Default Location: It contains the factory default elements such as OTP or Flash address. It is reserved for future use. • Factory Default Size: It is the total content size of the factory default elements. It is reserved for future use. • Factory Default Address: It is the starting address of the factory default elements (OTP or flash address). It is reserved for future use. • File system Address: It is the address of the Dynamic file system which will contain configuration files.
80560NT11600A Rev. 2.1 Page 13 of 51 2017-09-27 GS2K Memory Map and File System Application Note
• File system Size: It is the total size of the Dynamic file system. • DMA Read Control Word: It is the Read control word for flash interface. • DMA Controller Clock Divider: It is the clock divider of the DMA controller which is used to access the flash interface. • DMA Read Command: It is the read command OPCODE for reading the flash. This is always set to QUAD IO FAST READ (0xEB)
2.1.1.3 Boot App Control Block
It is the control block for the Boot application and contains the following fields:
Figure 4: Boot App Control Block 2.1.1.4 Boot Application
It is the application used to select the firmware to be loaded upon module boot up. 2.1.1.5 Backup of Control Block for Boot Application
It is the back up of control block for Boot application. 2.1.2 Firmware Block
The GS2000 based modules supports two-firmware model and three-firmware model. The two- firmware model contains two firmware blocks and the three-firmware model contains three firmware blocks.
Each firmware block contains:
• Control block • Application Firmware • WLAN Firmware • Static file system • Backup of control block
80560NT11600A Rev. 2.1 Page 14 of 51 2017-09-27 GS2K Memory Map and File System Application Note
2.1.2.1 Control Block
It comes after the super block and consists of the following fields:
Figure 5: Control Block in module flash
• Signature: It is a four byte ‘FWOK’ string similar to superblock that validates the control block. • Revision Number: It specifies the firmware version in control block. The latest firmware is identified with a highest Revision number. • Control Block Size: It specifies the size of block descriptors. • Block Descriptors: There are four block descriptors and each block descriptor contains following information about the static file system in module flash: o Offset: It is used to find the absolute address of the static file system in module flash. o Size: It is the size of the static file system. o Program Address: It is the address generated by the IAR tool while building firmware. o SRAM Address: It is the physical address of the firmware in SRAM. When APU executes an instruction, it always executes the Program address which is mapped to the SRAM address. o Owner of the Block: It specifies the owner of the block descriptor.
80560NT11600A Rev. 2.1 Page 15 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following table lists the binary values and description for Owner:
Owner of the Block Description of Owner
0 App Boot ROM
1 Application Firmware
2 WLAN Boot ROM
3 WLAN Firmware
o Flags: It specifies a value which indicates one or more combinations of the following operations: ▪ Loading ▪ Mapping ▪ Executing
The following table lists the flag values:
Binary Value Hex Value Description
0001 0x1 Load, remap, and run
0010 0x2 Load and remap
0100 0x3 Load
1000 0x4 Load and run
NOTE: In 5.1.X, number of descriptor are 4 and in 5.2.X number of descriptor are 5.
A new block descriptor is added that holds information about the firmware version in 5.2. X.
2.1.2.1.1 Control Block in 5.2.x In 5.2.0, the updated control block size is 100bytes, and it contains five block descriptors. Each block descriptor is of 20 bytes and the sequence of the block descriptors is changed as shown in the following table.
80560NT11600A Rev. 2.1 Page 16 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Block Descriptor Number 5.1.X 5.2.X
1. Application Start up Application Start up
2. WLAN Start up WLAN Start up
3. Web Image File system Temperature compensation
(Static File system)
4. Temperature compensation Web Image File system
(Static File system)
5. Not Valid Firmware Version information.
2.1.2.1.2 Fifth Block Descriptor in 5.2.X The fifth descriptor in 5.2.x Control block specifies firmware version. Following figure shows the information about each field.
APP Version GEPs Version WLAN Version Reserved Flag Owner of the Block
12000205 12000205 14000205 00000000 0020 0001
Following is the expansion of APP Version value:
12 – Extension
00 – Build
02 - Minor version
05 – Major version 80560NT11600A Rev. 2.1 Page 17 of 51 2017-09-27 GS2K Memory Map and File System Application Note
2.1.2.2 Application Firmware
GS2000 architecture includes the following components:
• Two ARM Cortex M3 CPUs • WLAN CPU subsystem for WLAN firmware • APP CPU subsystem for network services and application firmware The Application firmware implements networking protocol stacks and user application software and the Application software can be Serial-to-WiFi, Temperature and Low Sensor (TLS), TLS Low Power, or any customer specific application. 2.1.2.3 WLAN Firmware
The WLAN firmware is a GainSpan specific firmware provided to the customer as a binary file which implements 802.11 b/g/n WLAN and/or 802.15.4 protocol services. 2.1.2.4 Static File System
The Static file system is created in advance using File system creation software. For more information regarding Static file system, refer 3.1.1 Creating Static File System.
The Static file system is represented with the following naming conventions:
1. Drive: 1 2. Drive: B
For more information regarding available size and actual usage, refer Chapter 6. Memory Maps for GA Releases.
NOTE: It is not recommended to modify the static file system using Application software. For example, adding new file using API fopen, write operations, or modify operations are not recommended.
2.1.2.5 Backup of Control Block
Backup control block is same as Control Block (refer section 2.1.2.1 Control Block) and it is used for validating firmware. If the content in Control Block and Backup Control Block are not same in a firmware, then it is considered as an invalid firmware. 2.1.3 Dynamic File System
Application software uses the file system API (fopen, fread, fwrite, and so on) to create Dynamic file system during the first boot-up.
The Dynamic file system consists of following information:
• WLAN calibration information • Certificates (AT command Adding and WEB Page SSL Upload) • Profile • MAC Address
80560NT11600A Rev. 2.1 Page 18 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The Dynamic file system is represented with the following naming conventions:
• Drive 0 • Drive A
For more information regarding available size and actual usage, refer Chapter 6. Memory Maps for GA Releases
NOTE: It is recommended to use the dynamic file system for storing custom information (For example, sensor data, data logs, and so on). Custom application that needs data logging size of lesser than 128KB can use the On-module dynamic file system. If the requirement is more than 128KB, it is highly recommended to use the external flash file system. For more information, refer Chapter 4. External Flash Memory Map.
80560NT11600A Rev. 2.1 Page 19 of 51 2017-09-27 GS2K Memory Map and File System Application Note
2.2 SRAM The following figure shows the SRAM layout:
Figure 6: SRAM Layout
NOTE: In 5.1.X series, auto patch is a dummy block, where no information is stored. In 5.2.x series, the auto cache feature is enabled. The first 16k of the auto cache space is mapped to 128KB of GEPS patch libraries and the rest of the patch code will be place under the code section block.
80560NT11600A Rev. 2.1 Page 20 of 51 2017-09-27 GS2K Memory Map and File System Application Note
2.3 RTC The following figure shows the RTC layout:
Figure 7: RTC Layout 2.4 OTP
OTP is One Time Programmable Memory, divided in two parts, one for Application firmware and another for WLAN firmware. It contains important system related information for Application and WLAN firmware. For Application firmware, it contains information about MAC address, regularity Information and some module related information etc. For WLAN firmware, it contains information about Calibration data. 2.5 ROM
ROM is Read Only Memory, programmed with core modules of Application and WLAN firmware. Some of the modules of application firmware are RTOS, Network Stack, GEPS, Hardware Drivers (UART, SPI, and GPIO etc.), supplicant etc. In case of WLAN firmware, complete MAC is programmed in ROM.
80560NT11600A Rev. 2.1 Page 21 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Chapter 3. Module Flash File System
The module flash file system contains:
a. Static file system: The Static file system in the module flash contains the webpages and security certificates b. Dynamic file system: The Dynamic file system in the module flash contains default configurations. 3.1 STATIC FILE SYSTEM
The Static file system in module flash is used to store webpages (*.html, *.js, *.css) and security related certificates such as RootCA and Public Key in a predefined location of the module flash. The information about the predefined location of the Static file system is specified in the Control Block of each Firmware block.
One Firmware block contains one static file system and a three-firmware model contains three static file systems.
When a webpage access is requested from a web browser, the GS2000 module uses the Webpage binary to access web pages from the Static file system.
The file system partition of the Static file system in module flash is 1 and the Drive name is B. 3.1.1 Creating Static File System To create web image binary, perform the following steps:
Step 1: Extract the following tools and configuration files from the ..\Release package\ tools\fs_image_creater folder:
• safe-imager.exe: It is the file system creator tool which is used to create the Webpage file system. • web_pages.FFS: It is the configuration file which is used to configure the Webpage file system as shown in the following figure. It contains information such as: o Input file location o File system size o File system name o File system configurations
80560NT11600A Rev. 2.1 Page 22 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Figure 8: Web_page.FFS
Step 2: Extract the following webpage source files and folders from the release package and place them in the tools\fs_image_creater\FILEDIR folder as shown in the following figure:
css folder which contains styles.css.gz file
js folder which contains gs.min.js.gz file
logo.gif
html web pages in *. html.gz format
Figure 9: FILEDIR Folder
Step 3: Create a new folder (The folder can be named as per User’s preference. For example, Web Imager) and copy the safe-imager.exe, web_pages.FFS, and FILEDIR folder into it as shown in the following figure.
80560NT11600A Rev. 2.1 Page 23 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Figure 10: Web Imager Folder
Step 4: Open the DOS command prompt and go to the safe-image.exe file path. Step 5: Run the command safe-imager.exe web_pages.FFS in the DOS command prompt to create the web image binary as shown in the following figure.
Figure 11: Creating Web Image Binary 3.1.2 Modifying Static File System The Control block contains information related to Webpage file system. It contains four block descriptors. The third block descriptor provides following information about webpage file system.
• Offset address: It is used to find the absolute address of the webpage file system. Add the starting address of the Control block with Offset to get the absolute address of the webpage file system. • Size: It is the size of the webpage file system. Prerequisite
The Webpage file system is placed in a firmware block and modification of the Webpage file system requires,
• Understanding Super block and the firmware block’s Control block
80560NT11600A Rev. 2.1 Page 24 of 51 2017-09-27 GS2K Memory Map and File System Application Note
• Calculating the available space between the end of WLAN Firmware and the beginning of Backup of Control block
While increasing the size of the Webpage file system, ensure that the increased Webpage file system fits between the end of WLAN Firmware and the beginning of Backup of Control block as shown in the following figure.
Figure 12: Webpage file system location
NOTE: If the available space between the end of WLAN Firmware and the beginning of Backup of Control block is not enough for bigger Web pages, then increase the space by moving down the location of Backup of the Control block. This requires moving the position of Firmware blocks downwards by modifying the Super block.
80560NT11600A Rev. 2.1 Page 25 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Procedure
The steps involved to modify the webpage file system are as follows:
Step 1: Find the maximum available space for Webpage file system and modify the control block accordingly. Step 2: Create a new file system with modified configuration values.
Step 3: Update the Embedded File system Interface Source code according to the modified configuration values. The steps involved to modify are explained in detail in the following sections.
1. Find the Maximum Available Space and Modify Control Block
Compute the maximum available size for the webpage file system in the firmware block by checking the starting address of the Backup of control block from Super block and starting address of the webpage file system from the third block descriptor in Control block.
Consider a scenario where the starting address of the Control block (0x10000) and starting address of the Backup of control block (0xcf000) in the Super block as shown in Error! R eference source not found. and the Offset of the webpage file system in Control block is 0x6f000 as shown in Error! Reference source not found..
Figure 13: Super block
Figure 14: Control block
Step 1: In this example, the absolute address of the webpage is obtained by adding the Starting address of the Control block and the Offset of the Webpage file system which is: 0x10000 + 0x6f000 = 0x7f000.
Step 2: The maximum size of the Webpage file system that can fit is obtained by calculating the following.
Starting address of back up Control block – Starting address of Webpage file system which is 0xcf000 – 0x7f000 = 0x50000 (320KB).
80560NT11600A Rev. 2.1 Page 26 of 51 2017-09-27 GS2K Memory Map and File System Application Note
NOTE Continue to Step 3 if there is space available to increase the Webpage file system.
Step 3: Modify the size of the Webpage file system in the firmware block. In the above example, the default webpage file system is of 64 KB and the computed available memory is 320 KB. Increase the size of the webpage file system from 64 KB to 128 KB by modifying the value of third block descriptor in Control block.
Figure 15: Modified Third Block descriptor
2. Create Webpage File System
Execute the following steps to create a new Webpage file system with the modified configuration values:
Step 1: Change the configuration file web_page.FFS in the FILEDIR folder which is extracted from the tools folder in the release package ..\sdkpackage_location_folder\tools\fs_image_creater.
Figure 16: Modified web_page.FFS
Step 2: Create the new webpage file system by executing the following command. safe-imager.exe web_pages_mod.FFS
80560NT11600A Rev. 2.1 Page 27 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The Webpage file system is modified to 128 KB as shown below.
Figure 17: New Webpage file system
3. Update the Embedded File System Interface Code
Access the Embedded file system interface code and update the following macros as per the changes made in web_page.FFS file.
NOTE: The Embedded file system interface code for TLS application is App_fsif.c and for Serial to WiFi application is s2w_fs_if.c.
80560NT11600A Rev. 2.1 Page 28 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Table 2: Macros for Webpage File System in Embedded File System Interface Code
Macros Values
#define BLOCKSIZE_1 0x1000
#define BLOCKSTART_1 0x2
#define MAXBLOCKS_1 30
#define DESCSIZE_1 0x1000
#define DESCBLOCKSTART_1 0x30
#define DESCBLOCKS_1 2
#define DESCCACHE_1 0x400
#define SECTORSIZE_1 0x400
#define SECTORPERBLOCK_1 (BLOCKSIZE/SECTORSIZE)
The following figure shows the mapping between the modified Embedded file system interface code and the web_pages.FFS configuration file.
Figure 18: Modified Embedded File System Interface code 3.2 DYNAMIC FILE SYSTEM
The Configuration file system is a module file system which contains the initial default configurations for the GainSpan module to boot.
The file system partition of Configuration file system is 0 and the Drive name is A.
80560NT11600A Rev. 2.1 Page 29 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Chapter 4. External Flash Memory Map
Memory map in external flash contains Application super block, Firmware block, and File systems. The size of the memory map in External flash is extendable up to 16MB. The memory map of external flash in GS2000 based modules is as shown below.
Figure 19: External flash
NOTE: If Host firmware update is required, then it can be done for two file systems; one firmware update for static file system, and the other for dynamic File system which is used for Data logging. If there is no requirement for Host related firmware update, then the whole external flash can be used as Dynamic File system for Data Logging.
80560NT11600A Rev. 2.1 Page 30 of 51 2017-09-27 GS2K Memory Map and File System Application Note
4.1 APPLICATION SUPER BLOCK
It contains:
• Addresses of all the control blocks in the module flash which specifies the number of firmware’s supported • Address of the Configuration file system • Size of the Configuration file system
4.2 FIRMWARE BLOCK
The GS2000 based modules supports two-firmware model and three-firmware model. The two- firmware model contains two firmware blocks and the three-firmware model contains three firmware blocks.
Each firmware block contains:
• Control block • Static file system • Backup of control block
4.2.1 Control Block
It comes after the super block and consists of the following fields:
Figure 20: Control Block in external flash
• Signature: It is a four byte ‘FWOK’ string similar to superblock that validates and indicates that the control block is read. • Revision Number: It specifies the firmware version in control block. The latest firmware is identified with a highest Revision number. • Control Block Size: It specifies the size of block descriptors. • Block Descriptor: The block descriptor contains following information about the static file system in external flash: o Offset: It is used to find the absolute address of the static file system in external flash. o Size: It is the size of the static file system.
80560NT11600A Rev. 2.1 Page 31 of 51 2017-09-27 GS2K Memory Map and File System Application Note
4.2.2 Static File System
It is the 64 KB partition of the file system which contains:
• Host Code • Peripheral Code • Custom Web Pages
4.2.3 Backup of Control Block
It is the backup of a control block.
4.3 DYNAMIC FILE SYSTEM
It is the 1KB partition of the file system which is used for data logging.
80560NT11600A Rev. 2.1 Page 32 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Chapter 5. External Flash File System
The external flash file system contains:
• Static file system • Dynamic file system 5.1 STATIC FILE SYSTEM
Static file system is an external flash file system which is used to store the following:
• Host firmware: It is the firmware used by the Host MCU to access the GainSpan Module. • Custom web pages: These are custom webpages which are bigger in size and cannot be flashed on the module flash.
The file system partition of the Static file system is 3 and the Drive name is C. 5.1.1 Creating Static File System To create a Static file system, perform the following steps:
Step 1: Extract the following tools and configuration files from the \Release package\ tools\fs_image_creater folder:
• safe-imager.exe: It is the file system creator tool which is used to create the Static file system. • Static_file_system.FFS: It is the configuration file which is used to configure the Static file system. It contains information such as: o Input file location o File system size o File system name o File system configurations Step 2: Place the following files that require to be loaded on the external flash into ..\tools\fs_image_creater\FILEDIR folder such as:
• Host firmware • Custom Webpages Step 3: Open the DOS command prompt and go to the safe-image.exe file path.
Step 4: Run the command safe-imager.exe static_file_system.FFS in the DOS command prompt to create the file system. 5.1.2 Modifying Static File System To modify the Static file system, perform the following steps:
Step 1: Find the maximum available space for Static file system and modify the control block accordingly.
Step 2: Create a new file system with modified configuration values. Step 3: Update the Embedded File system Interface Source code according to the modified configuration values.
80560NT11600A Rev. 2.1 Page 33 of 51 2017-09-27 GS2K Memory Map and File System Application Note
1. Find the Maximum Available Space and Modify Control Block
Compute the maximum available size for the Static file system in the firmware block by checking the starting address of the Backup of control block from Super block and starting address of the Static file system from the Control block.
Consider a scenario where the starting address of the Control block (0x1000) and starting address of the Backup of control block (0xff000) is as shown in the following figure.
Figure 21: Super block
The Offset of the Static file system in Control block is 0x1000 as shown in the following figure.
Figure 22: Control block
Step 1: In this example, the absolute address of the Static file system (starting address of the static file system) is obtained by adding the Starting address of the Firmware 1’s Control block in Super block as shown in Error! Reference source not found. and the Offset of the Static file s ystem in Control block as shown in Error! Reference source not found..
0x1000 + 0x1000 = 0x2000.
Step 2: The maximum size of the Static file system that can fit is obtained by calculating the following. Starting address of back up Control block – Starting address of Static file system which is,
0xff000 – 0x2000 = 0xFD000
NOTE: Continue to Step 3 if there is space available to increase the Static file system.
1. Modify the size of the Static file system in the Control block.
2. Create Static File System
Execute the following steps to create a new Static file system with the modified configuration values:
80560NT11600A Rev. 2.1 Page 34 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Step 1: Change the configuration file static_file_system.FFS in the FILEDIR folder which is extracted from the tools folder in the release package ..\sdkpackage_location_folder\tools\fs_image_creater.
Step 2: Create the new static file system by executing the following command. safe-imager.exe static_file_system.FFS
3. Update the Embedded File System Interface Code
Access the Embedded File system Interface code and update the following macros as per the changes made in static_file_system.FFS file.
Table 3: Macros for Static file system in Embedded File System Interface Code
Macros Values
#define BLOCKSIZE_EF 0x1000
#define BLOCKSTART_EF 0x2
#define MAXBLOCKS_EF 30
#define DESCSIZE_EF 0x1000
#define DESCBLOCKSTART_EF 0x0
#define DESCBLOCKS_EF 2
#define DESCCACHE_EF 0x0
#define SECTORSIZE_EF 0x400
#define SECTORPERBLOCK_EF (BLOCKSIZE_EF/SECTORSIZE_EF)
5.2 DYNAMIC FILE SYSTEM
Dynamic file system is an external flash file system which is used for data logging. The file system partition of the Dynamic file system is 4 and the Drive name is D.
80560NT11600A Rev. 2.1 Page 35 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Chapter 6. Memory Maps for GA Releases
6.1 MEMORY MAP FOR 5.1.4, 5.1.5, 5.1.6, 5.1.7 GA RELEASES
The following table lists the available size and currently used size for file systems in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:
5.1.4,5.1.5, 5.1.6, Two Firmware Three Firmware Two Firmware Three Firmware and 5.1.7 GA Model (2MB) Model (2MB) Model (4MB) Model (4MB) Releases Available Static 320 KB 64 KB 1088 KB 576 KB file system (Webpage) Used Static file 64 KB 64 KB 64 KB 64 KB system (currently used) Available 448 KB 448 KB 512 KB 512 KB Dynamic file system (Webpage) Used Dynamic file 256 KB 256 KB 256 KB 256 KB system (currently used) Application and 440KB 440KB 440KB 440KB WLAN firmware size
80560NT11600A Rev. 2.1 Page 36 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 2MB Two firmware model in5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:
Figure 23: Two Firmware Model for 5.1.4,5.1.5, 5.1.6, and 5.1.7 GA Releases (2MB)
80560NT11600A Rev. 2.1 Page 37 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 2MB Three firmware model in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:
Figure 24: Three Firmware Model for 5.1.4,5.1.5, 5.1.6, and 5.1.7 GA Releases (2MB)
80560NT11600A Rev. 2.1 Page 38 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts the memory map for a 4MB Two firmware model in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:
Figure 25: Two Firmware Model for 5.1.4,5.1.5, 5.1.6, and 5.1.7 GA Releases (4MB)
80560NT11600A Rev. 2.1 Page 39 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 4MB Thee firmware model in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:
Figure 26: Three Firmware Model for 5.1.4,5.1.5 and 5.1.6 GA Releases (4MB)
80560NT11600A Rev. 2.1 Page 40 of 51 2017-09-27 GS2K Memory Map and File System Application Note
6.2 MEMORY MAP FOR 5.2.0, 5.2.1, AND 5.2.3 RELEASES The following table lists available size and currently used size for file systems in 5.2.0, 5.2.1, and 5.2.3 releases:
5.2.0, 5.2.1, and 5.2.3 Two Firmware Two Firmware Three Firmware Releases Model (2MB) Model (4MB) Model (4MB) Available Static file 124 KB 892 KB 380 KB system (Webpage) Used Static file system 64 KB 64 KB 64 KB (currently used) Available Dynamic file 448 KB 512 KB 512 KB system (Webpage) Used Dynamic file system 256 KB 256 KB 256 KB (currently used) Application and WLAN 636 KB 636 KB 636 KB firmware size
80560NT11600A Rev. 2.1 Page 41 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 2MB Two firmware model in in 5.2.0, 5.2.1, and 5.2.3 releases
Figure 27: Two Firmware Model for in 5.2.0, 5.2.1, and 5.2.3 releases (2MB)
80560NT11600A Rev. 2.1 Page 42 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 4 MB Two firmware model in 5.2.0, 5.2.1, and 5.2.3 releases:
Figure 28: Two Firmware Model for 5.2.0, 5.2.1, and 5.2.3 releases (4MB)
80560NT11600A Rev. 2.1 Page 43 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 4MB Three firmware model in 5.2.0, 5.2.1, and 5.2.3 releases:
Figure 29: Three Firmware Model for 5.2.0, 5.2.1, and 5.2.3 releases (4MB)
80560NT11600A Rev. 2.1 Page 44 of 51 2017-09-27 GS2K Memory Map and File System Application Note
6.3 MEMORY MAP FOR 5.3.0 RELEASE
The following table lists available size and currently used size for file systems in 5.3.0 release:
5.3.0 Release Two Firmware Two Firmware Three Firmware Model (2MB) Model (4MB) Model (4MB)
Available Static file system 124 KB 892 KB 380 KB (Webpage)
Used Static file system (currently 64 KB 64 KB 64 KB used)
Available Dynamic file system 448 KB 512 KB 512 KB (Webpage)
Used Dynamic file system 256 KB 256 KB 256 KB (currently used)
Application and WLAN firmware 636KB 636KB 632KB size
80560NT11600A Rev. 2.1 Page 45 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 2MB two firmware model in 5.3.0 release:
Figure 30: Two Firmware Model for in 5.3.0 release (2MB)
80560NT11600A Rev. 2.1 Page 46 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 4 MB two firmware model in 5.3.0 release:
Figure 31: Two Firmware Model for 5.3.0 release (4MB)
80560NT11600A Rev. 2.1 Page 47 of 51 2017-09-27 GS2K Memory Map and File System Application Note
The following figure depicts memory map for a 4MB three firmware model in 5.3.0 release:
Figure 32: Three Firmware Model for 5.3.0 release (4MB)
80560NT11600A Rev. 2.1 Page 48 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Appendix A Creating Maximum Supported Dynamic File System
To create a maximum supported dynamic file system:
• Update the superblock by changing the start address and the size of dynamic file system. • Update the source code. Steps to update the superblock:
Step 1: Open the superblock in Hex Editor.
Step 2: Press CTRL+8 to group the content as double word.
Step 3: Press CTRL+G and type the address as 0x1024. The value present in this address gives the start address of dynamic file system. Change this value from 0x380000 to 0x310000.
Step 4: Press CTRL+G and type the address as 0x1028. The value present in this address gives the size of dynamic file system. Change this value from 0x40000 to 0xF0000.
BEFORE:
AFTER:
80560NT11600A Rev. 2.1 Page 49 of 51 2017-09-27 GS2K Memory Map and File System Application Note
Steps to update the Source Code:
Step 1: Open app_fsif.c file.
Step 2: Update the maximum blocks according to the size of the file system.
Following macros are used while mounting the file system. These macros are defined in app_fsif.c file.
Update the maximum number of blocks from 14 to 238.
MACROS VALUES
BLOCKSIZE 0x1000
DESCSIZE 0x1000
SECTORSIZE 0x800
DESCCACHE 0x400
MAXBLOCKS 238
DESCBLOCKS 2
80560NT11600A Rev. 2.1 Page 50 of 51 2017-09-27