gs2k memory map and file system application note€¦ · gs2k memory map and file system...

GS2K Memory Map and File System Application Note

80560NT11600A Rev. 2.4 – 2019-03-25


80560NT11600A Rev. 2.4 of 62 2019-03-14

NOTICE

COPYRIGHTS

COMPUTER SOFTWARE COPYRIGHTS

SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT 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.

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.

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.4 of 62 2019-03-14

USAGE AND DISCLOSURE RESTRICTIONS

I. License Agreements

II. Copyrighted Materials

III. High Risk Materials

IV. Trademarks

V. Third Party Rights

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.

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

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.

TELIT and the Stylized T Logo are registered in Trademark Office. All other product or service names are the property of their respective owners.

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.4 of 62 2019-03-14

APPLICABILITY TABLE

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.

PRODUCT

GS2K based Modules

SW Version

5.1.7/5.2.1 onwards


80560NT11600A Rev. 2.4 of 62 2019-03-14

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

1.5 Apr,2015 Updated Super block, Control block, and Memory maps for GA Releases.

1.6 Apr,2015 Reworked on the review comments.

May,2015 Updated Application firmware and WLAN firmware models

1.7 July,2015 Updated Super block, Control block, and Memory maps for GA Releases.

1.8 Aug,2015 Added the reserved block in the memory maps and details of the difference between 5.1.X and 5.2.X control block.

1.9 Sept,2015 Updated data in the Fig: Two Firmware Model for 5.2.0 Beta Release (4 MB)

2.0 June,2016 Added Memory Map for 5.3.0 release.

2.1 Sept,2017 Added Appendix for Creating Maximum supported dynamic file system.

2.2 May,2018

Added memory map details for 5.4.0 and 5.5.2 GA releases under section 6.3 Memory Map for 5.3.0, 5.4.0, and 5.5.2 GA Releases

Updated memory map details for 5.3.0 GA release under section 6.3 Memory Map for 5.3.0, 5.4.0, and 5.5.2 GA Releases

2.3 Sept,2018 Added the following sections regarding customization web images

• 3.1.1.1 Creating Custom Web Images and • 3.1.1.2 Uploading Custom Webpages into the SDK Builder

2.4 Mar,2019

Removed Application and WLAN data size from the table lists under Chapter 6 Memory Maps for GA Releases

Updated Static file system data size under section 6.3 Memory Map for 5.3.0, 5.4.0, 5.5.x, and 5.7.x GA Releases.


80560NT11600A Rev. 2.4 of 62 2019-03-14

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 ............................................................................ 34

3.2 DYNAMIC FILE SYSTEM ................................................................................................ 40 CHAPTER 4. EXTERNAL FLASH MEMORY MAP .............................................................. 41

4.1 APPLICATION SUPER BLOCK ......................................................................................... 42 4.2 FIRMWARE BLOCK ....................................................................................................... 42

4.2.1 Control Block ................................................................................................... 42 4.2.2 Static File System ............................................................................................ 43 4.2.3 Backup of Control Block .................................................................................. 43

4.3 DYNAMIC FILE SYSTEM ................................................................................................ 43 CHAPTER 5. EXTERNAL FLASH FILE SYSTEM ................................................................ 44

5.1 STATIC FILE SYSTEM ................................................................................................... 44 5.1.1 Creating Static File System ............................................................................. 44 5.1.2 Modifying Static File System ............................................................................ 44

5.2 DYNAMIC FILE SYSTEM ................................................................................................ 46 CHAPTER 6. MEMORY MAPS FOR GA RELEASES .......................................................... 47

6.1 MEMORY MAP FOR 5.1.4, 5.1.5, 5.1.6, AND 5.1.7 GA RELEASES ................................... 47 6.2 MEMORY MAP FOR 5.2.0, 5.2.1, AND 5.2.3 GA RELEASES ............................................. 52 6.3 MEMORY MAP FOR 5.3.0, 5.4.0, 5.5.X, AND 5.7.X GA RELEASES ................................... 56

APPENDIX A CREATING MAXIMUM SUPPORTED DYNAMIC FILE SYSTEM .................. 60


80560NT11600A Rev. 2.4 of 62 2019-03-14

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: Inserting HTML and GIF Files ................................................................................ 25

Figure 13: Creating webImage.bin File .................................................................................... 25

Figure 14: Generated webImage.bin Binary ............................................................................ 26

Figure 15: Replace the webImage.bin File .............................................................................. 26

Figure 16: Compiling S2W.eww Project .................................................................................. 26

Figure 17: Batch File ............................................................................................................... 27

Figure 18: Creating Single Image ............................................................................................ 28

Figure 19: Compressing the Files under FILEDIR Folder ........................................................ 29

Figure 20: Created a FILEDIR.zip Folder ................................................................................ 29

Figure 21: SDK Builder - Getting Started................................................................................. 30

Figure 22: SDK Builder - Welcome Page ................................................................................ 30

Figure 23: Building Custom Package ...................................................................................... 31

Figure 24: Firmware Update Interface ..................................................................................... 31

Figure 25: Uploading FILEDIR.zip Folder into the SDK Builder ............................................... 32

Figure 26: Summary Tab ......................................................................................................... 32

Figure 27: Submit Build Request ............................................................................................. 33

Figure 28: Programming the Flash .......................................................................................... 33

Figure 29: Webpage File System Location .............................................................................. 35

Figure 30: Super Block ............................................................................................................ 36


80560NT11600A Rev. 2.4 of 62 2019-03-14

Figure 31: Control Block .......................................................................................................... 36

Figure 32: Modified Third Block Descriptor .............................................................................. 37

Figure 33: Modified web_page.FFS ........................................................................................ 37

Figure 34: New Webpage File System .................................................................................... 38

Figure 35: Modified Embedded File System Interface Code ................................................... 39

Figure 36: External Flash ........................................................................................................ 41

Figure 37: Control Block in External Flash .............................................................................. 42

Figure 38: Super Block ............................................................................................................ 45

Figure 39: Control Block .......................................................................................................... 45

Figure 40: Two-Firmware Model for 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA Releases (2 MB) ......... 48

Figure 41: Three-Firmware Model for 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA Releases (2 MB) ...... 49

Figure 42: Two-Firmware Model for 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA Releases (4 MB) ......... 50

Figure 43: Three-Firmware Model for 5.1.4, 5.1.5, and 5.1.6 GA Releases (4 MB) ................ 51

Figure 44: Two-Firmware Model for in 5.2.0, 5.2.1, and 5.2.3 Releases (2 MB) ..................... 53

Figure 45: Two-Firmware Model for 5.2.0, 5.2.1, and 5.2.3 Releases (4 MB) ......................... 54

Figure 46: Three-Firmware Model for 5.2.0, 5.2.1, and 5.2.3 Releases (4 MB) ....................... 55

Figure 47: Two-Firmware Model for 5.4.0 and 5.5.2 Releases (2 MB) .................................... 57

Figure 48: Two-Firmware Model for 5.3.0, 5.4.0, 5.5.x, and 5.7.x Releases (4 MB) ................ 58

Figure 49: Three-Firmware Model for 5.3.0, 5.4.0, 5.5.x, and 5.7.x Releases (4 MB) ............. 59


80560NT11600A Rev. 2.4 of 62 2019-03-14

List of Tables Table 1: Glossary of Terms ..................................................................................................... 10

Table 2: Macros for Webpage File System in Embedded File System Interface Code ........... 39

Table 3: Macros for Static File System in Embedded File System Interface Code .................. 46


80560NT11600A Rev. 2.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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/GS2101M/GS2200M is 4 MB and in GS2100M is 2 MB. 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.4 of 62 2019-03-14

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.4 of 62 2019-03-14

• 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


the FW1 Firmware block. • FW2 Control Block Address: It is the Control block address for the FW2 Firmware


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.4 of 62 2019-03-14

• 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.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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.


80560NT11600A Rev. 2.4 of 62 2019-03-14

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.

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

(Static File system) Temperature compensation

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.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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 128 KB can use the On-module dynamic file system. If the requirement is more than 128 KB, it is highly recommended to use the external flash file system. For more information, refer Chapter 4. External Flash Memory Map.


80560NT11600A Rev. 2.4 of 62 2019-03-14

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 128 KB of GEPS patch libraries and the rest of the patch code will be place under the code section block.


80560NT11600A Rev. 2.4 of 62 2019-03-14

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. 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), supplicant, and so on. In case of WLAN firmware, complete MAC is programmed in ROM.


80560NT11600A Rev. 2.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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


80560NT11600A Rev. 2.4 of 62 2019-03-14

3.1.1.1 Creating Custom Web Images To create custom web images, perform the following steps:

1. Login to https://wifi.telit.com/secure/login and download the latest SDK Package. 2. In the downloaded package, locate and navigate to the folder <SDK

Package>/Embedded/tools/fs_image_creater/FILEDIR and insert the required HTML and GIF files into the folder.

Figure 12: Inserting HTML and GIF Files

NOTE: For .gif file the webImage.bin file should not exceed 64 KB size and the html pages should be in .gz format.

3. Open the DOS prompt and go to path <SDK Package>/Embedded/tools/fs_image_creater and run the following command to create a web image. Safe-imager.exe web_pages.FFS

Figure 13: Creating webImage.bin File

https://wifi.telit.com/secure/login


80560NT11600A Rev. 2.4 of 62 2019-03-14

4. A webImage.bin file will be created.

Figure 14: Generated webImage.bin Binary

5. Copy and replace this webimage.bin file into the path: <SDK Package>/Embedded/tools/Super_Control_block as shown below.

Figure 15: Replace the webImage.bin File

6. Next, navigate to the folder <SDK Package>/Embedded/userapps/s2w/build/s2w.eww and compile the S2W.eww project using any IAR version.

Figure 16: Compiling S2W.eww Project


80560NT11600A Rev. 2.4 of 62 2019-03-14

NOTE: It is recommended to use IAR Version 6.50.

7. After a successful compilation run, locate the batch file flash_program_FlashFetch_SingleImage.bat placed in the same path and follow the steps guided on terminal.

Figure 17: Batch File

NOTE:

Depending on the baud rate select the respective batch files.

For 921K Baud Rate, select flash_program_FlashFetch_SingleImage_921K.bat

and for 1152K Baud Rate, select flash_program_FlashFetch_SingleImage.bat

8. Open the DOS prompt and run the flash_program_FlashFetch_SingleImage.bat batch file.


80560NT11600A Rev. 2.4 of 62 2019-03-14

9. Enter the COM port assigned to the module when indicated.

Figure 18: Creating Single Image

10. A Single Image file is created under the bin folder.


80560NT11600A Rev. 2.4 of 62 2019-03-14

3.1.1.2 Uploading Custom Webpages into the SDK Builder Perform the following steps for uploading the custom webpages into the SDK Builder.

1. Navigate to FILEDIR folder located in <SDK Package>/Embedded/tools/fs_image_creater/FILEDIR.

2. Compress all the files located in the FILEDIR folder into a ZIP format.

Figure 19: Compressing the Files under FILEDIR Folder

3. A new FILEDIR.zip folder will be created in the same location.

Figure 20: Created a FILEDIR.zip Folder

4. Login to https://wifi.telit.com/secure/login. 5. Go to SDK Builder tab and select GS2000 from the drop-down menu.

https://wifi.telit.com/secure/login


80560NT11600A Rev. 2.4 of 62 2019-03-14

Figure 21: SDK Builder - Getting Started

6. GainSpan SDK Builder welcome page appears. Click Next to build a Custom SDK Package.

Figure 22: SDK Builder - Welcome Page

7. Select the build configuration as shown below and click Next.


80560NT11600A Rev. 2.4 of 62 2019-03-14

Figure 23: Building Custom Package

8. Navigate to the Firmware Update tab, under Firmware Update Interface select Custom Web pages option.

Figure 24: Firmware Update Interface

9. Select the Upload Custom Web Page option and click Browse to upload the FILEDIR.zip folder.


80560NT11600A Rev. 2.4 of 62 2019-03-14

Figure 25: Uploading FILEDIR.zip Folder into the SDK Builder

10. Click Next to proceed to the Summary Tab.

Figure 26: Summary Tab


80560NT11600A Rev. 2.4 of 62 2019-03-14

11. Scroll down the Summary Tab, click OK, and then, click Build to complete the Build process.

Figure 27: Submit Build Request

12. After a successful build, program the GS node using the gs_flashprogram tool available at location <Custom Package>\Tools\GS_programming_tool\gs2k_flashprogram.exe and program the module.

13. Ensure that the PROGRAM/RUN (SW7) switch is in PROGRAM mode and power cycle is performed. The board is now successfully erased and flashed with the single image.

Figure 28: Programming the Flash


80560NT11600A Rev. 2.4 of 62 2019-03-14

NOTE: By default, the baud rate is set to 921600.

14. Once the board is programmed, change the switch (SW7) to RUN mode. 15. Open the Tera Term VT Application and select the serial port assigned to the evaluation

board. Turn the ON/OFF switch on the EVB board to ON position and enter the following AT commands.

Make sure the PC is connected to the limited AP for accessing the webpage. Once the connection is established, you will be able to access the newly added GIF files and HTML pages.

To verify whether the added .GIF and .HTML files are accessible;

Open your web browser and type the URL for the web image using the IP address of the GS node. For example, https://<IP Address>/pic.gif.

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.4 of 62 2019-03-14

• 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 29: 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.4 of 62 2019-03-14

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! Reference 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 31: 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 (320 KB).


80560NT11600A Rev. 2.4 of 62 2019-03-14

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 32: 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 33: 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.4 of 62 2019-03-14

The Webpage file system is modified to 128 KB as shown below.

Figure 34: 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.4 of 62 2019-03-14

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 35: Modified Embedded File System Interface Code


80560NT11600A Rev. 2.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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 16 MB. The memory map of external flash in GS2000 based modules is as shown below.

Figure 36: 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.4 of 62 2019-03-14

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 37: 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.4 of 62 2019-03-14

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 1 KB partition of the file system which is used for data logging.


80560NT11600A Rev. 2.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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.


The Offset of the static file system in Control block is 0x1000 as shown in the following figure.

Figure 39: 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 Figure 38 and the Offset of the static file system in Control block as shown in Figure 39.

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:

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.


80560NT11600A Rev. 2.4 of 62 2019-03-14

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.4 of 62 2019-03-14

Chapter 6. Memory Maps for GA Releases

6.1 MEMORY MAP FOR 5.1.4, 5.1.5, 5.1.6, AND 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, and 5.1.7 GA Releases

Two-Firmware Model (2 MB)

Three-Firmware Model (2 MB)



Available static file system (Webpage)

320 KB 64 KB 1088 KB 576 KB

Used static file system (currently used)

64 KB 64 KB 64 KB 64 KB

Available dynamic file system (Webpage)

448 KB 448 KB 512 KB 512 KB

Used dynamic file system (currently used)

256 KB 256 KB 256 KB 256 KB


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 2 MB two-firmware model in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:

Figure 40: Two-Firmware Model for 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA Releases (2 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 2 MB three-firmware model in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:

Figure 41: Three-Firmware Model for 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA Releases (2 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 4 MB two-firmware model in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:

Figure 42: Two-Firmware Model for 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA Releases (4 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 4 MB three-firmware model in 5.1.4, 5.1.5, 5.1.6, and 5.1.7 GA releases:

Figure 43: Three-Firmware Model for 5.1.4, 5.1.5, and 5.1.6 GA Releases (4 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

6.2 MEMORY MAP FOR 5.2.0, 5.2.1, AND 5.2.3 GA 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 GA releases:

5.2.0, 5.2.1, and 5.2.3 GA Releases




Available static file system (Webpage)

124 KB 892 KB 380 KB

Used static file system (currently used)

64 KB 64 KB 64 KB

Available dynamic file system (Webpage)

448 KB 512 KB 512 KB

Used dynamic file system (currently used)

256 KB 256 KB 256 KB


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 2 MB two-firmware model in 5.2.0, 5.2.1, and 5.2.3 GA releases:

Figure 44: Two-Firmware Model for in 5.2.0, 5.2.1, and 5.2.3 Releases (2 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 4 MB two-firmware model in 5.2.0, 5.2.1, and 5.2.3 GA releases:

Figure 45: Two-Firmware Model for 5.2.0, 5.2.1, and 5.2.3 Releases (4 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 4 MB three-firmware model in 5.2.0, 5.2.1, and 5.2.3 GA releases:

Figure 46: Three-Firmware Model for 5.2.0, 5.2.1, and 5.2.3 Releases (4 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

6.3 MEMORY MAP FOR 5.3.0, 5.4.0, 5.5.X, AND 5.7.X GA RELEASES The following table lists available size and currently used size for file systems in 5.3.0, 5.4.0, 5.5.x, and 5.7.x GA releases:

5.3.0, 5.4.0, 5.5.2 GA Releases Two-Firmware Model (2 MB)



Available static file system (Webpage) 124 KB 512 KB 256 KB

Used static file system (currently used) 64 KB 64 KB 64 KB

Available dynamic file system (Webpage) 448 KB 512 KB 512 KB

Used dynamic file system (currently used) 256 KB 256 KB 256 KB


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 2 MB two-firmware model in 5.3.0, 5.4.0, 5.5.x, and 5.7.x GA releases:

Figure 47: Two-Firmware Model for 5.4.0 and 5.5.2 Releases (2 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 4 MB two-firmware model in 5.3.0, 5.4.0, 5.5.x, and 5.7.x GA releases:

Figure 48: Two-Firmware Model for 5.3.0, 5.4.0, 5.5.x, and 5.7.x Releases (4 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

The following figure depicts memory map for a 4 MB three-firmware model in 5.3.0, 5.4.0, 5.5.x, and 5.7.x GA releases:

Figure 49: Three-Firmware Model for 5.3.0, 5.4.0, 5.5.x, and 5.7.x Releases (4 MB)


80560NT11600A Rev. 2.4 of 62 2019-03-14

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.4 of 62 2019-03-14

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

gs2k memory map and file system application note€¦ · gs2k memory map and file system...

Documents