GS2K Module Programming and Protocol Reference Guide · GS2K Module Programming and Protocol Reference Guide 1VV0301447 Rev 1.0 7 of 77 2015-05-05 About This Manual This manual provides

GS2K Module Programming and Protocol Reference Guide

G

S2K Module Programming and Protocol Reference Guide 1VV0301447 Rev. 1 – 2015-05-05

SPECIFICATIONS ARE SUBJECT TO CHANGE WITHOUT NOTICE

NOTICEWhile reasonable efforts have been made to assure the accuracy of this document, Telitassumes no liability resulting from any inaccuracies or omissions in this document, or fromuse of the information obtained herein. The information in this document has been carefullychecked and is believed to be reliable. However, no responsibility is assumed forinaccuracies or omissions. Telit reserves the right to make changes to any products describedherein and reserves the right to revise this document and to make changes from time to timein content hereof with no obligation to notify any person of revisions or changes. Telit does notassume any liability arising out of the application or use of any product, software, or circuitdescribed 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 Telitproducts (machines and programs), programming, or services that are not announced in yourcountry. Such references or information must not be construed to mean that Telit intends toannounce such Telit products, programming, or services in your country.

COPYRIGHTSThis instruction manual and the Telit products described in this instruction manual may be,include or describe copyrighted Telit material, such as computer programs stored insemiconductor memories or other media. Laws in the Italy and other countries preserve forTelit and its licensors certain exclusive rights for copyrighted material, including the exclusiveright to copy, reproduce in any form, distribute and make derivative works of the copyrightedmaterial. Accordingly, any copyrighted material of Telit and its licensors contained herein or inthe 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 byimplication, estoppel, or otherwise, any license under the copyrights, patents or patentapplications of Telit, as arises by operation of law in the sale of a product.

COMPUTER SOFTWARE COPYRIGHTSThe 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 pro-grams, including the exclusive right to copy or reproduce in any form the copyrighted com-puter 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 cop-ied (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.

USAGE AND DISCLOSURE RESTRICTIONS

I. License Agreements

The software described in this document is the property of Telit and its licensors. It isfurnished by express license agreement only and may be used only in accordance with theterms of such an agreement.

II. Copyrighted Materials

Software and documentation are copyrighted materials. Making unauthorized copies isprohibited 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 computerlanguage, 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 NOTfault-tolerant and are NOT designed, manufactured, or intended for use as on-line controlequipment in the following hazardous environments requiring fail-safe controls: the operationof Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air TrafficControl, 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 servicenames 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 allterms and conditions imposed on you in respect of such separate software. In addition toThird Party Terms, the disclaimer of warranty and limitation of liability provisions in thisLicense 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 ANYDIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIALDAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSEDAND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY,ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE ORTHE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSEAND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISEDOF THE POSSIBILITY OF SUCH DAMAGES.

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

APPLICABILITY TABLE


Table of Contents

Chapter 1 Programming the GS2000 Based Modules .................................................................... 191.1 Programming Mode ...............................................................................................................191.2 GS2000 Boot Procedure .......................................................................................................23

1.2.1 GS2000 Boot ROM Flow in Program Mode .................................................................241.3 Host Interface Overview ........................................................................................................25

1.3.1 HI Frame Format ..........................................................................................................25

Chapter 2 Download Class Messages ............................................................................................. 272.1 Download Request ................................................................................................................282.2 Copy Request ........................................................................................................................292.3 Error Indication ......................................................................................................................302.4 Ack (Acknowledgment) ..........................................................................................................312.5 Transferring Binary ................................................................................................................32

Chapter 3 ROM Debug Class Messages ......................................................................................... 353.1 RegPeek ................................................................................................................................363.2 RegPoke ................................................................................................................................373.3 MemRead ..............................................................................................................................383.4 MemWrite ..............................................................................................................................393.5 FlashRead .............................................................................................................................403.6 FlashErase ............................................................................................................................413.7 FlashEraseCheck ..................................................................................................................423.8 FlashCheckSum ....................................................................................................................433.9 Execute at Address ...............................................................................................................443.10 WLAN Start ..........................................................................................................................453.11 WLAN Stop ..........................................................................................................................46

Chapter 4 Memory Map and File System Structure ......................................................................... 474.1 Flash Structure ......................................................................................................................48

4.1.1 Super Block Structure ..................................................................................................494.1.2 Boot ROM Super Block ................................................................................................504.1.3 Boot APP Super Block .................................................................................................514.1.4 Boot Application ...........................................................................................................524.1.5 Backup of Control Block for Boot Application ...............................................................52

4.2 Firmware Block ......................................................................................................................534.2.1 Control Block ................................................................................................................544.2.2 Application Firmware ....................................................................................................564.2.3 WLAN Firmware ...........................................................................................................564.2.4 Static File System ........................................................................................................564.2.5 Backup of Control Block ...............................................................................................56

4.3 In-Module Flash File System .................................................................................................574.3.1 Static File System ........................................................................................................574.3.2 Dynamic File System ...................................................................................................58

Chapter 5 Programming Binaries .................................................................................................... 595.1 Programming the Binaries .....................................................................................................595.2 Programming At One Location ..............................................................................................645.3 Programming At Multiple Locations .......................................................................................64

1VV0301447 Rev 1.0 5 of 77 2015-05-05


Appendix A Opcodes .......................................................................................................... 65

Appendix B Firmware Model .............................................................................................. 67B.1 Memory Map for 5.1.x Releases ...........................................................................................67B.2 Memory Map for 5.2.x Releases ...........................................................................................72

1VV0301447 Rev 1.0 6 of 77 2015-05-05


About This Manual

This manual provides information required to program the GainSpan® GS2000 based modules using host interfaces like UART and SPI through individual commands, formats, and protocols. It describes memory map and file systems used to control how data is tracked, organized, stored and retrieved during different types of operations.

Refer to the following sections:

• Revision History, page 8

• Audience, page 8

• Standards, page 8

• Documentation Conventions, page 9

• Documentation, page 12

• References, page 14

• Contact Information, Support, page 16

• Returning Products to GainSpan, page 17

• Accessing the GainSpan Portal, page 18

1VV0301447 Rev 1.0 7 of 77 2015-05-05


Revision HistoryThis version of the GainSpan GS2000 Based Module Programming and Protocol Reference Guide contains the following new information listed in Table 1, page 8.

AudienceThis manual is designed for software engineers who want to know how to program the on-board Flash and describes the software and host interfaces, memory map file structure of the GS2000 based module commands, and steps for programming binaries and firmware. It is also intended for users of boot ROM commands who want to know the available commands and formats.

StandardsThe GainSpan GS module series supports the IEEE 802.11 b/g/n standards.

Table 1 Revision History

Version Date Remarks1.0 May 2015 Initial Release

1VV0301447 Rev 1.0 8 of 77 2015-05-05


Documentation ConventionsThis manual uses the following text and syntax conventions:

– Special text fonts represent particular commands, keywords, variables, or window sessions

– Color text indicates cross-reference hyper links to supplemental information

– Command notation indicates commands, subcommands, or command elements

Table 2, page 9, describes the text conventions used in this manual for software procedures that are explained using the AT command line interface.

Table 2 Document Text Conventions

Convention Type Description

command syntaxmonospaced font

This monospaced font represents command strings entered on a command line and sample source code.

AT XXXX

Proportional fontdescription

Gives specific details about a parameter.

<Data> DATA

UPPERCASEVariable parameter

Indicates user input. Enter a value according to the descriptions that follow. Each uppercased token expands into one or more other token.

lowercaseKeyword parameter

Indicates keywords. Enter values exactly as shown in the command description.

[ ]Square brackets

Enclose optional parameters. Choose none; or select one or more an unlimited number of times each. Do not enter brackets as part of any command.

[parm1|parm2|parm3]

?Question mark

Used with the square brackets to limit the immediately following token to one occurrence.

<ESC>Escape sequence

Each escape sequence <ESC> starts with the ASCII character 27 (0x1B). This is equivalent to the Escape key.

<ESC>C

<CR>Carriage return

Each command is terminated by a carriage return.

<LF>Line feed

Each command is terminated by a line feed.

1VV0301447 Rev 1.0 9 of 77 2015-05-05


<CR> <LF>Carriage returnLine feed

Each response is started with a carriage return and line feed with some exceptions.

< >Angle brackets

Enclose a numeric range, endpoints inclusive. Do not enter angle brackets as part of any command.

<SSID>

=Equal sign

Separates the variable from explanatory text. Is entered as part of the command.

PROCESSID = <CID>

.dot (period)

Allows the repetition of the element that immediately follows it multiple times. Do not enter as part of the command.

.AA:NN can be expanded to 1:01 1:02 1:03.

A.B.C.DIP address

IPv4-style address.

10.0.11.123

X:X::X:XIPv6 IP address

IPv6-style address.

3ffe:506::1Where the : : represents all 0x for those address components not explicitly given.

LINEEnd-to-line input token

Indicates user input of any string, including spaces. No other parameters may be entered after input for this token.

string of words

WORDSingle token

Indicates user input of any contiguous string (excluding spaces).

singlewordnospaces

Table 2 Document Text Conventions (Continued)

Convention Type Description

1VV0301447 Rev 1.0 10 of 77 2015-05-05


Table 3, page 11, describes the symbol conventions used in this manual for notification and important instructions.

Table 3 Symbol Conventions

Icon Type Description

NoteProvides helpful suggestions needed in understanding a feature or references to material not available in the manual.

Alert Alerts you of potential damage to a program, device, or system or the loss of data or service.

Caution Cautions you about a situation that could result in minor or moderate bodily injury if not avoided.

Warning Warns you of a potential situation that could result in death or serious bodily injury if not avoided.

Electro-Static Discharge (ESD)

Notifies you to take proper grounding precautions before handling a product.

1VV0301447 Rev 1.0 11 of 77 2015-05-05


1VV

T

or

ide

1VV

rial ,

DocumentationThe GainSpan documentation suite listed in Table 4, page 12 includes the part number, documentation name, and a description of the document. The documents are available on the GainSpan Portal. Refer to , page 17 for details.

Table 4 Documentation List

Part Number Document Title Description

0301435 GS2K Module Evaluation Board Hardware User Guide

Provides users steps to program theon-board Flash utilizing either UARor SPI interface for the GainSpan GS2000 based modules using DOSGraphical User Interface utility provided by GainSpan. The user guuses the evaluation boards as a reference example board.

0301463

GS2011M S2W Adapter Command Reference GuideGS2100M S2W Adapter Command Reference GuideGS2101M S2W Adapter Command Reference GuideGS2200M S2W Adapter Command Reference Guide

Provides a complete listing of AT secommands, including configurationexamples for initiating, maintainingand evaluating GainSpan WiFi GainSpan series modules.

1VV0301447 Rev 1.0 12 of 77 2015-05-05


Documentation FeedbackWe encourage you to provide feedback, comments, and suggestions so that we can improve the documentation. You can send your comments by logging into Telit Support Portal. If you are using e-mail, be sure to include the following information with your comments:

– Document name

– URL or page number

– Hardware release version (if applicable)

– Software release version (if applicable)

1VV0301447 Rev 1.0 13 of 77 2015-05-05

https://www.gainspan.com/secure/add_question


ReferencesThe GainSpan references listed in Table 5, page 14 are available on the GainSpan Portal. Refer to , page 17 for details.

Table 5 Other Documents and References

Title Description

Schematics

GS2000 Based Module Evaluation Board schematics supporting:• GS2011M• GS2100M• GS2101M• GS2200M• GS2200M SKB

Smart Phone Applications

• Smart Phone applications for iOS and Android to evaluate and demonstrate the Temperature and Light Sensor (TLS) firmware.

– For use with GS2011M EVK and GS2200 EVB and SKB only

• Android:

– GainSpan Provisioning

– GainSpan Firmware Update

– GainSpan Smartplug

– GainSpan TLS

– Concurrent Provisioning

• iOS:

– GainSpan TLS

– GainSpan Provisioning

– GainSpan-Renesas Wi-Fi Sensor

– GainSpan ConcurrentProvisioning

– GainSpan Freescale Wi- Fi Sensor

– GainSpan Audio

– GainSpan Smartplug

– GainSpan Firmware Update

Tools and UtilitiesSerial terminal program to evaluate and demonstrate Serial-to-Wi-Fi (S2W) applications such as

– gs2k_flashprogram.exe

1VV0301447 Rev 1.0 14 of 77 2015-05-05


1VV0301447 Rev 1.0 15 of 77 2015-05-05


Contact Information, SupportFor general contact, technical support services, technical questions and to report documentation errors contact Telit Technical Support at:

[email protected]

We recommend adding “Wi-Fi” in subject of the email. For example, the subject of email can be “Wi-Fi: Your actual issue or question in brief” like “Wi-Fi: SPI Driver Issue”.

Also, in description of your email, please provide details about the issue, product and module including software firmware version, module version and type, application being used, customizations done to application, use case, issue frequency, and ability to recreate it among other things wherever applicable.

Alternatively, for more Technical Support information or assistance, perform the following steps:

1. Visit http://www.telit.com, go to Products> Wi-Fi and Blue-tooth, then scroll down to the Telit Wi- Fi Portal.

2. Click Access the Portal Here icon which will direct you to the GainSpan portal http://www.gainspan/secure/login.com

1. Log in with your customer Email and Password.

2. Select the Location.

3. Select Q&A tab.

4. Select Ask a New Question.

5. Enter your technical support question, product information, and a brief description.

For detailed information about where you can buy the Telit modules or for recommendations on accessories and components visit:

http://www.telit.com

Our aim is to make this guide as helpful as possible. Keep us informed of your comments and suggestions for improvements. Telit appreciates feedback from the users of our information.

1VV0301447 Rev 1.0 16 of 77 2015-05-05

[email protected]


Returning Products to GainSpanIf a problem cannot be resolved by GainSpan technical support, a Return Material Authorization (RMA) is issued. This number is used to track the returned material at the factory and to return repaired or new components to the customer as needed.

To return a hardware component:

1. Determine the part number and serial number of the component.

2. Obtain an RMA number from Sales/Distributor Representative.

3. Provide the following information in an e-mail or during the telephone call:

– Part number and serial number of component

– Your name, organization name, telephone number, and fax number

– Description of the failure

4. The support representative validates your request and issues an RMA number for return of the components.

5. Pack the component for shipment.

Guidelines for Packing Components for ShipmentTo pack and ship individual components:

– When you return components, make sure they are adequately protected with packing materials and packed so that the pieces are prevented from moving around inside the carton.

– Use the original shipping materials if they are available.

– Place individual components in electrostatic bags.

– Write the RMA number on the exterior of the box to ensure proper tracking.

NOTE: Do not return any components to GainSpan Corporation unless you have first obtained an RMA number. GainSpan reserves the right to refuse shipments that do not have an RMA. Refused shipments will be returned to the customer by collect freight.

CAUTION! Do not stack any of the components.

1VV0301447 Rev 1.0 17 of 77 2015-05-05


Accessing the GainSpan PortalTo find the latest version of GainSpan documentation supporting the GainSpan product release you are interested in, you can search the GainSpan Portal website by performing the following steps:

1. Visit http://www.telit.com, go to Products> Wi-Fi and Blue-tooth, then scroll down the Telit Wi- Fi Portal.

2. Click Access the Portal Here icon which will direct you to the GainSpan portal http://www.gainspan/secure/login.com

3. Log in using your customer Email and Password.

4. Click the Getting Started tab to view a Quick Start tutorial on how to use various features within the GainSpan Portal.

5. Click the Agreements tab to download and upload the SLA for ADK and SDK respectively.

6. Click on the Documents tab to search, download, and print GainSpan product documentation.

7. Click the Software tab to search and download the latest software versions.

8. Click the Kits Purchased tab to view customer account history.

9. Click the Legal Documents tab to view GainSpan Non-Disclosure Agreement (NDA).

10. Click the Certifications tab to view GainSpan certifications.

NOTE: You must first contact GainSpan to set up an account, and obtain a customer user name and password before you can access the GainSpan Portal.

1VV0301447 Rev 1.0 18 of 77 2015-05-05

GS2K Module Programmiing and Protocol Reference Guide

Chapter 1 Programming the GS2000 Based Modules

This chapter provides information about programming the GS2000 based modules and describes the procedure to transfer binaries into the modules. It is assumed that the reader is generally familiar with GainSpan® SoC products, Internet Protocol (IP) networks and the operation and management of 802.11 wireless devices.

• Programming Mode, page 19

• GS2000 Boot ROM Flow in Program Mode, page 24

• Host Interface Overview, page 25

1.1 Programming ModeThe GS2000 based modules consist of the GS2000 SoC and a Flash. The firmware is programmed on the Flash through the GS2000 SoC. This Flash can be programmed through UART or SPI interface using the Host Interface (HI) protocols described in 1.3 Host Interface Overview, page 25.

For programming the Flash, the GS2000 SoC should be configured for Program mode. The following describe the key components of the GS2000 system.

• Two CPUs: WLAN CPU and APP CPU where APP CPU is the main CPU that runs first after power up and boots from its internal boot ROM.

• Code in the boot ROM: It first checks if a firmware download is requested. This is achieved by putting the module in program mode. To put the module in program mode, pull up the GPIO27 (GS2011M) or GPIO31 (GS2100M) high and then reset or power cycle the module. In Program Mode, GPIO33 will be driven high very briefly. At reset release, the following pins are sampled.

– GPIO27 (on GS2011M) or GPIO31 (on GS2100M) is the “Program Mode” pin. Value 1 sets Program Mode. Value 0 sets Run Mode.

– GPIO25 is the “Program Select/Previous Restore” pin. Function depends on Program Mode pin. Selects 921K baud in Program Mode. Selects Previous Restore in Run Mode.

– GPIO21 is the “Alternate Previous Restore” pin.

1VV0301447 Rev 1.0 19 of 77 2015-05-05


Table 6, page 20 describes the boot control pin functions for the GS2000 based module.

Table 6 Boot Control Pin Functions

Program Mode

GPIO27 or GPIO31

Program Select/Previous

Restore GPIO25

Alternate Previous Restore GPIO21

(GS2011M only)

Boot Control Function

0 0 0 Normal boot

0 0 1

Previous Code Restore. Restores prior code revision by invalidating the present code image. Will NOT invalidate the last remaining image. Note: below that GPIO21 and GPIO25 MUST NOT both be high at reset release in Run mode (GPIO27=0).

0 1 0

Previous Code Restore. Restores the prior code revision by invalidating the present code image. Will NOT invalidate the last remaining image.

0 1 1

Invalid. DO NOT USE THIS BOOT CONTROL STATE. This boot control state can invalidate the last remaining code image.

1 0 XProgram Mode with: UART0 @ 115.2K baud; nothing on GPIO15-18; SPI0 on SDIO pins.

1 1 X

Program Mode using: UART0 @ 921.6K baud; SPI0 on GPIO15-18. Note: that GPIO15-18 are only available on GS2000 SoC, and not on the modules.

NOTE: Both GPIO25 and GPIO21 MUST NOT be high in Run Mode at reset release.

NOTE: GPIO27 (or GPIO31), GPIO25, and GPIO21 should ONLY be used as outputs, and should not be used as inputs.

NOTE: In Run Mode, Boot ROM leaves all GPIO pins as input with pull resistor enabled until flash code sets them.

1VV0301447 Rev 1.0 20 of 77 2015-05-05


• UART0 Interface: It is used to program the module flash and it runs with the following settings:

Baud rate: 115200/921600 bps

Data: 8 bits

Parity: None

Stop: 1 bit

Flow control: None

Figure 1, page 21 shows the UART interface between the GS2000 based module and a Host.

Figure 1 UART Interface Between GS2000 Based Module and Host

NOTE: In Program Mode, only the pins required for the Program Mode specified interfaces are set to non-gpio mode.

NOTE: GPIO25 should be pulled up high for 921K.

1VV0301447 Rev 1.0 21 of 77 2015-05-05


• SPI0 Interface: It is used to program the module flash using a SPI master.

SPI Mode: Mode 1

SPI Clock: Up to 1.3MHz using Cheetah SPI adapter, 4MHz using Aardvark SPI adapter (www.totalphase.com for SPI adapters)

SPI Bit Order: MSB first

Slave Select: Active Low

Figure 2, page 22 shows the SPI interface between the GS2000 based module acting as an SPI Slave and a SPI Master.

Figure 2 SPI Interface Between GS2000 Based Module and SPI Master

1VV0301447 Rev 1.0 22 of 77 2015-05-05

www.totalphase.com


1.2 GS2000 Boot ProcedureFigure 3, page 23 shows the GS2000 Based Modules Boot Procedure Flow Diagram.

Figure 3 GS2000 Boot Procedure

1VV0301447 Rev 1.0 23 of 77 2015-05-05


1.2.1 GS2000 Boot ROM Flow in Program ModeThe following is the Boot ROM flow in Program mode.

1. Initialize the clocks.

2. Initialize the low level OTP driver.

3. Initialize the OTP memory management module.

4. Initialize the GPIOs.

5. Initialize the Flash interface.

6. Check if flash exist:

a. Read Flash ID (Issues a Flash Read ID command and reads the RX FIFO)

b. If Flash ID is 0, then it assumes flash device is not present and do not configure anything for flash.

c. If Flash is present, depending on the ID, configure the lanes (single lane / quad lane)

7. Initialize the flash cache.

8. Check the GPIO mode select pin (PROGRAM/RUN).

9. In Program mode, ideal loop waiting for Host interface commands over UART0 / SPI0.

1VV0301447 Rev 1.0 24 of 77 2015-05-05


1.3 Host Interface OverviewThe Host Interface (HI) allows external systems to access the on-chip APP CPU and WLAN CPU services. The HI allows the external system to perform programming on the on-module Flash of the GS2000 based modules through UART0 or SPI0 interface.

1.3.1 HI Frame FormatAll messages carried over the Host Interface have a common format. They are composed of a HI header, and parameters depending on the header. HI frames are composed, in addition to the HI header and parameters, of a start delimiter and a HI HEADER checksum. In programming mode, the boot ROM running on APP CPU always waits for incoming frames on the UART0 or SPI0 interface that it controls. This format is defined in Figure 4, page 25 below.

Figure 4 HI Frame Format (From Host Side)

An HI frame consists of:

1. Start-of-frame (SOF) delimiter: It is a single byte with a value of 0xA5 which is used to ensure synchronization at the frame level. The driver starts the reception process when it recognizes the delimiter. The length of the delimiter has been reduced to 1 byte to avoid alignment problems when waiting for the start element. However, no provisions are made to ensure that the subsequent data stream does not contain a byte with value 0xA5, so it is possible for the driver to mistake a data byte for a delimiter. Therefore, a header checksum has been added to ensure correct synchronization.

2. Host Interface header: It consists of the following fields:

a. Class: It is the service class that determines the format of the data in HI Parameters. The service class of a frame is signaled by the value of this field. The Download class used to program the on-module flash is represented as 0x02. ROM debug class is represented as 0x07.

b. Reserved: Reserved for future purposes (value = 0x00)

c. Additional Info: It is a general-purpose field which is of 2 bytes whose contents depend on the service class of the message. (This is not applicable for Download class and its value is 0x00.)

d. Length: It is 2 bytes long field which uses 11 bits to specify the length of HI parameters and it cannot exceed 1514 bytes. The length field does not include the 1 byte SOF and 7 bytes of HI header. Depending on the PHY used to carry the HI frame, it is possible that only the 11 significant bits will be transmitted.

1VV0301447 Rev 1.0 25 of 77 2015-05-05


e. Checksum: It is computed as the 1’s complement of the 8-bit long (modulo-256) sum of first 6 bytes of the HI Header.

3. HI Parameters: It is the section that consists of data specific for relevant messages. For more information, refer Chapter 2 Download Class Messages, page 27.

NOTE: Each byte is independently added to the sum, as an integer between 0 and 255, without regard for its significance within its own data field.

NOTE: The multi-byte fields in all of the commands are specified with lower byte first. That means 0x40080000 would be seen as 00 00 08 40.

1VV0301447 Rev 1.0 26 of 77 2015-05-05


Chapter 2 Download Class Messages

This chapter describes the format of different messages in download class. Figure 5, page 27 shows the HI frame for Download Class Messages. The class field of HI Header contains value 0x02 for Downloaded Class Messages.

• Download Request, page 28

• Copy Request, page 29

• Error Indication, page 30

• Ack (Acknowledgment), page 31

Figure 5 Download Class Messages

1VV0301447 Rev 1.0 27 of 77 2015-05-05


2.1 Download RequestThe Download request is composed of six fields (see Figure 6, page 28).

Figure 6 Download Request Format

Table 7, page 28 describes the Download Request Format.

Example - Download Request Command and Response

Table 8, page 28 shows the Download Request Command and Response that is sent/received to/from the GS2000 based module.

Table 7 Download Request Format

Identifier DescriptionOpcode It is 7 bits with a value of 0x01 (Bit 7 is reserved).

SeqNbr It is 1 byte and specifies the sequence number of the current request. It starts from 0x00 and increments by 1 with every request.

FileLength It is 4 bytes and specifies the total length of the downloaded File.BundleLength It is 2 bytes and specifies the length (in bytes) of the Data field.

RamAddr

It is 4 bytes and provides the address where the current code bundle must be stored in shared SRAM. In GainSpan gs2k_flashprogram tool the RamAddr starts at 0x00000000 location and is then incremented in steps based on the BundleLength.

Data <BundleLength> It provides the data to be written to SRAM.

NOTE: What is a File? The binary which needs to be downloaded is divided into multiple fragments and each fragment (maximum of 16KB) is termed as a File.

Table 8 Download Request Command and Response

Command Response AckA5 02 00 00 00 ED 03 0D 01 00 00 40 00 00 E1 03 00 00 00 00 66 77 6F 6B FF FF FF FF 50 00 00 00 04 30 00 00 00 ……

A5 02 00 00 00 02 00 FB 05 00

1VV0301447 Rev 1.0 28 of 77 2015-05-05


2.2 Copy RequestThe Copy request is composed of eight fields (see Figure 7, page 29).

Figure 7 Copy Request Format

Table 9, page 29 describes the Copy Request Format.

Example - Copy Request Command and Response

Table 10, page 29 shows the Copy Request Command and Response that is sent/received to/from the GS2000 based module.

Table 9 Copy Request Format

Identifier Description

Opcode

It is 7 bits (Bit 0 to Bit 6) with value 0x02 and Bit 7 is the field More which indicates if there is any pending File.• 0x02 - indicates that it is the last Copy Request and there is not further Files to be

downloaded.• 0x82 - indicates that there is another File for download.

SeqNbr It is 1 byte and specifies the sequence number of the current request. It is incremented by 1 with every next request.

FlashAddr It is 4 bytes and specifies the destination address (flash memory) of the File to be copied.Length It is 4 bytes and specifies the length (in bytes) of the File to be copied.

RamAddrIt is 4 bytes and specifies the source address (SRAM) of the File to be copied. In GainSpan gs2k_flashprogram tool the RamAddr is always 0x00000000 indicating where the 16K Download Request chunk starts in the SRAM.

Checksum It is 4 bytes and it is 1’s complement of sum of all the bytes in a File.

SwapFlashAddr It is 4 bytes and provides the address of the flash memory that is to be used as Swap Flash (reserved for future use).

Table 10 Copy Request Command and Response

Command Response AckA5 02 00 00 00 16 00 E7 82 11 00 00 01 00 00 40 00 00 00 00 00 00 3A D9 EC FF 00 00 00 08

A5 02 00 00 00 02 00 FB 05 11

NOTE: It is recommended for everyone to do an explicit erase because of the dynamic file system data. Although the Copy Request performs an erase before writing to the flash, it is a safe practice to do an explicit erase.

1VV0301447 Rev 1.0 29 of 77 2015-05-05


2.3 Error IndicationThe Error Indication is composed of three fields (see Figure 8, page 30).

Figure 8 Error Indication Format

Table 11, page 30 describes the Error Indication Format.

Table 11 Error Indication Format

Identifier DescriptionOpcode It is 7 bits with a value of 0x04 and Bit 7 (8th bit is reserved).

SeqNbr It is 1 byte and specifies the sequence number of the current error indication.

ErrorCode

It is 2 bytes and specifies a failure code. Different types of supported failure codes are:• 0x01 (ModuleBusy): It specifies that the module is busy and

the Firmware update module was not ready to receive a command. After receiving the error, the Host retries the command.

• 0x02 (ParamError): It specifies that the Copy Request contains inconsistent parameters.

• 0x12 (ChecksumError): It specifies that the computed checksum is different from the one passed in the Copy Request.

• 0x14 (SeqNumError): It specifies that a bad sequence number has been detected.

1VV0301447 Rev 1.0 30 of 77 2015-05-05


2.4 Ack (Acknowledgment)The Ack message is composed of two fields (see Figure 9, page 31).

Figure 9 Ack Message Format

Table 12, page 31 describes the Acknowledgment Indication.

Table 12 Acknowledgment Indication Format

Identifier Description

Opcode It is 7 bits with a value of 0x05 and the Bit 7 (8th bit is reserved).

SeqNbr It is 1 byte and specifies the sequence number of the request being acknowledged.

1VV0301447 Rev 1.0 31 of 77 2015-05-05


2.5 Transferring BinaryBinary is the data (Super Block, Control Block, Firmware, or any type of information) that is transferred from a host to the GS2000 based modules.

Consider a scenario where the host has to transfer a binary of 18KB to GS2000 based module. The host is connected to the GS2000 based module through the UART0 or SPI0 interface and transfers binary (see Figure 10, page 32).

Figure 10 Transferring Binary

1VV0301447 Rev 1.0 32 of 77 2015-05-05


The step-by-step procedure followed to transfer binary is as follows:

1. The host sends the first Download Request (Opcode=0x01, SeqNbr=0x00) which is a subset of the first File (16 KB of binary) to the GS2000 based module.

2. If the Download Request (Opcode=0x01, SeqNbr=0x00) is successfully downloaded on the RAM of GS2000 based module, then it sends an acknowledgment (Ack) with Opcode=0x05 and SeqNbr=0x00 (sequence number of the downloaded DR). Otherwise, it sends and error indication (Error) and the host resends the Download Request).

3. Host sends rest of the DRs similarly till the File is completely downloaded on GS2000 based module.

4. Once one complete File which is 16KB of the binary is successfully sent, the Host sends a Copy Request (Opcode=0x82, SeqNbr=0x0B) to the GS2000 based module.

5. GS2000 based module computes the checksum of the downloaded File in its SRAM and compares the computed File with checksum received in the Copy Request message.

6. After successful checksum verification, the GS2000 based module erases the flash, programs the flash, and sends an acknowledgment (Ack) with Opcode=0x05 and SeqNbr=0x0B (sequence number of the Copy Request) which indicates that the File is transferred successfully.

7. Host sends the next Download Request (Opcode=0x01, SeqNbr=0x0C) which is a subset of the next File (remaining 2KB of Binary) to the GS2000 based module.

8. Step 2 to Step 6 are repeated till the host sends the complete File to GS2000 based module.

1VV0301447 Rev 1.0 33 of 77 2015-05-05


- This page intentionally left blank -

1VV0301447 Rev 1.0 34 of 77 2015-05-05


Chapter 3 ROM Debug Class Messages

This chapter provides various boot ROM commands for the GS2000 based module for reading and writing registers, memory and external flash through flash interface. This chapter also describes the commands and their responses with examples. The HI Frame Format including Download Class, Download Request, Copy Request, Error Indication, and Ack are described in Chapter 1 Programming the GS2000 Based Modules, page 19.

• RegPeek, page 36

• RegPoke, page 37

• MemRead, page 38

• MemWrite, page 39

• FlashRead, page 40

• FlashErase, page 41

• FlashEraseCheck, page 42

• FlashCheckSum, page 43

• Execute at Address, page 44

• WLAN Start, page 45

• WLAN Stop, page 46

Figure 11, page 35 shows the ROM debug message format that forms the data portion of messages, i.e., HI Parameters portion.

Figure 11 ROM Debug Message Format

1VV0301447 Rev 1.0 35 of 77 2015-05-05


3.1 RegPeek

Command Table 13, page 36 describes the RegPeek Command Format.

Response Table 14, page 36 describes the RegPeek Response Format.

Notes:

1. Both request and response contain [addr, val, width] tuples even though request does not really need to contain val.

2. The maximum number of registers is limited by maximum HI frame size; i.e., 1500 bytes.

3. HI Header Additional Info field set to 1 to send the message to WLAN.

4. There shall be additional Addr, Val and Width fields (tuple) required in case there are more than one register.

5. Content of the response frame in this case shall be same as request frame except the response opcode = (request opcode + 0x40).

Table 13 RegPeek Command Format

Identifier DescriptionOpcode It is 8 bits - 0x41.NumRegs It is 4 bytes. Number of Registers.

Addr [Reg n] It is 4 bytes. Address of Register n. Unaligned accesses are allowed; i.e., the address need not be 4 byte aligned.

Val [Reg n]It is 4 bytes. Value of the Register n. For each operation, this should be set to zero. The value field is always 4 bytes wide irrespective of the width field; i.e., even 1 byte value takes 4 bytes space.

Width [Reg n] Number of bytes to read. Allowed values are 1 byte, 2 byte, and 4 byte; i.e., the width values are 1, 2, and 4 respectively.

Table 14 RegPeek Response Format



Val [Reg n]It is 4 bytes. Value of the Register n. For each operation, this should be set to zero. The value field is always 4 bytes wide irrespective of the width field; i.e., even 1 byte value takes 4 bytes space.

Width [Reg n] Number of bytes to read. Allowed values are 1 byte, 2 byte, and 4 bytes.

1VV0301447 Rev 1.0 36 of 77 2015-05-05


Example - RegPeek Command and Response

Table 15, page 37 shows the RegPeek Command and Response that is sent/received to/from the GS2000 based module.

3.2 RegPoke

Command Table 16, page 37 describes the RegPoke Command Format.

Notes:

1. Request contain [addr, val, width] tuples.



4. There shall be additional Addr, Val, and Width fields (tuple) required in case there are more than one register.

5. Content of the response frame in this case shall be same as request frame except the response opcode = (request opcode + 0x040).

Table 15 RegPeek Command and Response

Command ResponseA5 07 00 00 00 11 00 E7 41 01 00 00 00 00 00 08 40 00 00 00 00 04 00 00 00

A5 07 00 00 00 11 00 E7 81 01 00 00 00 00 00 08 40 50 50 41 00 04 00 00 00

Table 16 RegPoke Command Format



Val [Reg n] It is 4 bytes. Value of the Register n. The value field is always 4 bytes wide irrespective of the width field; i.e., even 1 byte value takes 4 bytes space.

Width [Reg n] Number of bytes to written. Allowed values are 1 byte, 2 byte, and 4 bytes.

1VV0301447 Rev 1.0 37 of 77 2015-05-05


Example - RegPoke Command

Table 17, page 38 shows the RegPoke Command that is sent to the GS2000 based module.

3.3 MemRead

Command Table 18, page 38 describes the MemRead Command Format.

Response Table 19, page 38 describes the MemRead Response Format.

Notes:



3. Content of the response frame in this case shall be same as request frame except the response code = (request code + 0x40).

Table 17 RegPoke Command

Command ResponseA5 07 00 00 00 11 00 E7 42 01 00 00 00 18 00 08 40 78 56 34 12 04 00 00 00

-

NOTE: There is no response to RegPoke.

Table 18 MemRead Command Format

Identifier DescriptionOpcode It is 8 bits - 0x43.

Addr It is 4 bytes. Address of Memory location. Unaligned accesses are allowed; i.e., the address need not be 4 byte aligned.

Len It is 4 bytes. Number of bytes to be written to the specified Memory location.

Table 19 MemRead Response Format



Len It is 4 bytes. Number of bytes to be read from the specified Memory location.Data Len bytes. This will contain the data present in the specified memory location.

1VV0301447 Rev 1.0 38 of 77 2015-05-05


Example - MemRead Command and Response

Table 20, page 39 shows the MemRead Command and Response that is sent/received to/from the GS2000 based module.

3.4 MemWrite

Command Table 21, page 39 describes the MemWrite Command Format.

Notes:




Example - MemWrite Command

Table 22, page 39 shows the MemWrite Command that is sent to the GS2000 based module.

Table 20 MemRead Command and Response

Command ResponseA5 07 00 00 00 09 00 EF 43 00 05 04 20 10 00 00 00

A5 07 00 00 00 19 00 DF 83 00 05 04 20 10 00 00 00 00 00 00 00 33 33 00 3E 45 49 4D 31 31 30 32 00

Table 21 MemWrite Command Format



Len It is 4 bytes. Number of bytes to be written to the specified Memory location.Data [Len bytes] Number of bytes to the specified memory location.

Table 22 MemWrite Command

Command ResponseA5 07 00 00 00 F7 03 FE 44 00 00 03 20 EE 03 00 00 80 B5 00 F0 ED FA 01 BD 2D E9 F2 4F 84 B0 07 00 15 00 1C 00 5F ……

-

NOTE: There is no response to MemWrite.

1VV0301447 Rev 1.0 39 of 77 2015-05-05


3.5 FlashRead

Command Table 23, page 40 describes the FlashRead Command Format.

Response Table 24, page 40 describes the FlashRead Response Format.

Notes:

1. The maximum read data is limited by maximum HI frame size; i.e., 1500 bytes.


Example - FlashRead Command and Response

Table 25, page 40 shows the FlashRead Command and Response that is sent/received to/from the GS2000 based module.

Table 23 FlashRead Command Format

Identifier DescriptionOpcode It is 8 bits - 0x46.Addr It is 4 bytes. Address of the Flash location.Len It is 4 bytes. Number of bytes to be read from the specified Flash location.

Table 24 FlashRead Response Format

Identifier DescriptionOpcode It is 8 bits - 0x86.Addr It is 4 bytes. Address of the Flash location.Len It is 4 bytes. Number of bytes to be read from the specified Flash location.Data Len bytes. This will contain the data from Flash.

Table 25 FlashRead Command and Response

Command ResponseA5 07 00 00 00 09 00 EF 46 00 00 01 00 0C 00 00 00

A5 07 00 00 00 15 00 E3 86 00 00 01 00 0C 00 00 00 66 77 6F 6B FF FF FF FF 50 00 00 00

1VV0301447 Rev 1.0 40 of 77 2015-05-05


3.6 FlashErase

Command Table 26, page 41 describes the FlashErase Command Format.

Note:

1. The minimum erase size for Flash erase is 4096 bytes. Less than that would yield success but no operation.

Response Table 27, page 41 describes the FlashErase Response Format.

Notes:

1. The maximum read data is limited by maximum HI frame size; i.e., 1500 bytes.


Example - FlashErase Command and Response

Table 28, page 41 shows the FlashErase Command and Response that is sent/received to/from the GS2000 based module.

Notes:

1. If the length is 4095 bytes, then nothing will get erased. However you will see boot ROM returning success.

2. If the length is 4096 bytes are erased, then 4K sector of the Flash gets erased.

3. If the length is 4097 bytes get erased, then it will erase 8K sector (assuming the start address is 0x00000000).

Table 26 FlashErase Command Format

Identifier DescriptionOpcode It is 8 bits - 0x49.Addr It is 4 bytes. Address of the Flash location.Len It is 4 bytes. Number of bytes to be read from the specified Flash location.

Table 27 FlashErase Response Format

Identifier DescriptionOpcode It is 8 bits - 0x89.Addr It is 4 bytes. Address of Flash location.Len It is 4 bytes. Number of bytes to be erased from the specified Flash location.

Table 28 FlashErase Command and Response

Command ResponseA5 07 00 00 00 09 00 EF 49 00 00 00 00 00 00 40 00

A5 07 00 00 00 09 00 EF 89 00 00 00 00 00 00 40 00

1VV0301447 Rev 1.0 41 of 77 2015-05-05


3.7 FlashEraseCheck

Command Table 29, page 42 describes the FlashEraseCheck Command Format.

Response Table 30, page 42 describes the FlashEraseCheck Response Format.

Example - Flash Erase Check Command and Response

Table 31, page 42 shows the Flash Erase Check Command and Response that is sent/received to/from the GS2000 based module.

The use of FlashEraseCheck is to reduce the erase time. Erasing an entire 2MB flash is a costly operation. The erase command takes the longest time to execute in the GS2000. In order to save time for erasing, perform an erase check which returns how much of the flash is erased. Based on this value, you can calculate how much flash needs to be erased and erase only that portion.

As mentioned previously in this document, you can do a binary search operation type Erase check in our FlashProgram tool; so for a 2MB:

1. Check from 0x100000 to 0x200000. If this check returns with a value indicating “not erased.” it is assumed there would be data between 0x000000 to 0x200000 and erase entire 2MB from 0x00 location.

2. Check from 0x80000 to 0x100000. If check returns with a value indicating “not erased,” then it is assumed there would be data between 0x000000 to 0x100000 and erase 1MB from 0x00 location.

Table 29 FlashEraseCheck Command Format

Identifier DescriptionOpcode It is 8 bits - 0x4d.

Addr It is 4 bytes. Address of Flash memory where to check. The address needs to be 4 byte aligned.

Len It is 4 bytes. Number of bytes to be checked in Flash.

Table 30 FlashEraseCheck Response Format

Identifier DescriptionOpcode It is 8 bits - 0x8d.

Addr It is 4 bytes. Address of the Flash memory where it got erased. The address needs to be 4 byte aligned.

Len It is 4 bytes. Number of contiguous words that has FF FF FF FF.

Table 31 Flash Erase Check Command and Response

Command ResponseA5 07 00 00 00 09 00 EF 4D 00 00 20 00 00 00 20 00

A5 07 00 00 00 09 00 EF 8D 00 00 20 00 00 00 06 00

1VV0301447 Rev 1.0 42 of 77 2015-05-05


3. Check from 0x80000 to 0x100000. If this check returns with a value indicating “not erased,” it is assumed there would be data between 0x000000 to 0x80000 and erase 512KB from 0x00 location.

4. Continue the check till you find some data and execute the erase command else indicate flash was erased already.

Erasing 4MB takes 22 seconds, but erasing 2MB takes around 12 seconds. So with the combination of erase check and erase, you might have to do an erase of only 1MB of the flash (since the single image firmware and Super Block is less than 1MB combined). This could save a few seconds.

3.8 FlashCheckSum

Command Table 32, page 43 describes the FlashCheckSum Command Format.

Response Table 33, page 43 describes the FlashCheckSum Response Format.

Example - Flash Checksum Command and Response

Table 34, page 43 shows the Flash Checksum Command and Response that is sent/received to/from the GS2000 based module.

Table 32 FlashCheckSum Command Format

Identifier DescriptionOpcode It is 8 bits - 0x4c.

Addr It is 4 bytes. Address of the Flash memory where to check. The address needs to be 4 byte aligned.

Len It is 4 bytes. Length of bytes to check the checksum.

Table 33 FlashCheckSum Response Format

Identifier DescriptionOpcode It is 8 bits - 0x8c.Checksum It is 4 bytes. Checksum.

Table 34 Flash Checksum Command and Response

Command ResponseA5 07 00 00 00 09 00 EF 4C 00 10 01 00 00 E0 0F 00

A5 07 00 00 00 05 00 F3 8C 52 1B 09 B7

1VV0301447 Rev 1.0 43 of 77 2015-05-05


3.9 Execute at Address

Command Table 35, page 44 describes the Execute at Address Command Format.

Note:

1. Thumb bit has to be set for execute command (0x20010000 is address to write data then in execute command give it as 01 00 01 20).

Response Table 36, page 44 describes the Execute at Address Response Format.

Note:

1. HI Header Additional Info field is set to 1 to send the message to WLAN.

Example - Execute at Address Command and Response

Table 37, page 44 shows the Execute at Address Command and Response that is sent/received to/from the GS2000 based module.

Table 35 Execute at Address Command Format

Identifier DescriptionOpcode It is 8 bits - 0x45.Addr It is 4 bytes. Address of the Memory location of the executable instruction.

Table 36 Execute at Address Response Format

Identifier DescriptionOpcode It is 8 bits - 0x85.Addr It is 4 bytes. Address of the Memory location of the executable instruction.

Table 37 Execute at Address Command and Response

Command ResponseA5 07 00 00 00 05 00 F3 45 01 00 03 20 A5 07 00 00 00 05 00 F3 85 00 01 00 03

1VV0301447 Rev 1.0 44 of 77 2015-05-05


3.10 WLAN Start

Command Table 38, page 45 describes the WLAN Start Command Format.

Response Table 39, page 45 describes the WLAN Start Response Format.

Example - WLAN Start Command and Response

Table 40, page 45 shows the WLAN Start Command and Response that is sent/received to/from the GS2000 based module.

Table 38 WLAN Start Command Format


Table 39 WLAN Start Response Format


Table 40 WLAN Start Command and Response

Command ResponseA5 07 00 01 00 01 00 F6 47 -

NOTE: There is no response to WLAN Start.

1VV0301447 Rev 1.0 45 of 77 2015-05-05


3.11 WLAN Stop

Command Table 41, page 46 describes the WLAN Stop Command Format.

Response Table 42, page 46 describes the WLAN Stop Response Format.

Example - WLAN Stop Command and Response

Table 43, page 46 shows the WLAN Stop Command and Response that is sent/received to/from the GS2000 based module.

Table 41 WLAN Stop Command Format


Table 42 WLAN Stop Response Format


Table 43 WLAN Stop Command and Response

Command ResponseA5 07 00 01 00 01 00 F6 48 -

NOTE: There is no response to WLAN Stop.

1VV0301447 Rev 1.0 46 of 77 2015-05-05


Chapter 4 Memory Map and File System Structure

This chapter provides an overview about the Memory Map and types of file system structure used in GainSpan® GS2000 based modules. This manual also reviews the Flash structure and provides necessary information required to understand. The GS2000 based 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. The chapter mainly focuses on the in-module flash.

• Flash Structure, page 48

• Firmware Block, page 53

• In-Module Flash File System, page 57

1VV0301447 Rev 1.0 47 of 77 2015-05-05


4.1 Flash StructureThe Memory Map in-module Flash contains Super Block, Firmware Blocks, and File Systems. The size of the memory map in the GS2011M is 4MB and for the GS2100M is 2MB. The memory map of an in-built module Flash in a GS2000 based module is shown in Figure 12, page 48.

Figure 12 GS2000 Based Module Flash

The Memory Map of in-module Flash contains:

• Flash Structure, page 48

• Firmware Block, page 53

• In-Module Flash File System, page 57

1VV0301447 Rev 1.0 48 of 77 2015-05-05


4.1.1 Super Block StructureThe Super Block consists of the following fields (see Figure 13, page 49).

Figure 13 Super Block Structure

1VV0301447 Rev 1.0 49 of 77 2015-05-05


4.1.2 Boot ROM Super BlockThe Boot ROM Super Block contains the address where the Control Block and Backup of Control Block for the Boot application should be. Table 44, page 50 describes the Boot APP Super Block fields.

Table 44 Boot ROM Super Block

Field Size (in bytes) Description

Signature 4 FLOK string to indicate that Super Block has been read.

FW0 Control Block Address 4 It contains the Control Block address for the Boot application’s FW0 firmware.

FW0 Backup of Control Block Address 4 It is the backup of the Control Block address for the Boot application’s firmware.

FW1 Control Block Address 4 It is filled with invalid address as there is only one boot application in Boot ROM Super Block.

FW1 Backup of Control Block Address 4 It is filled with invalid address as there is only one boot application in Boot ROM Super Block.

FW2 Control Block Address 4 It is filled with invalid address as there is only one boot application in Boot ROM Super Block.

FW2 Backup of Control Block Address 4 It is filled with invalid address as there is only one boot application in Boot ROM Super Block.

Factory Default Location 2 It contains the factory default elements such as OTP or Flash address. It is reserved for future use.

Factory Default Size 2 It is the total content size of the factory default elements. It is reserved for future use.

Factory Default Address 4It is the starting address of the factory default elements (OTP or Flash address). It is reserved for future use.

File System Address 4 It is the address of the Dynamic file system which will contain configuration files.

File System Size 4 it is the total size of the Dynamic file system.DMA Read Control Word 4 It is the Read control word for Flash interface.

DMA Controller Clock Divider 2 It is the clock divider of the DMA controller which is used to access the Flash interface.

DMA Read Command 2It is the read command OPCODE for reading the Flash. This is always set to QUAD I/O FAST READ (0xEB).

1VV0301447 Rev 1.0 50 of 77 2015-05-05


4.1.3 Boot APP Super BlockThe Boot Application Super Block contains the following:

• Addresses of all the Control Blocks in the module flash which specifies the number of firmwares supported.

• Address of the Configuration file system.

• Size of the Configuration file system.

Table 45, page 51 describes the APP Super Block fields.

Table 45 Boot APP Super Block


Signature 4 FLOK string to indicate that Super Block has been read.

FW0 Control Block Address 4 It is the Control Block address for the FW0 Firmware Block.

FW0 Backup of Control Block Address 4 it is the backup of Control Block address for the FW0 Firmware block.

FW1 Control Block Address 4 It is the Control Block address for the FW1 Firmware block.

FW1 Backup of Control Block Address 4 It is the backup of Control Block address for the FW1 Firmware block.

FW2 Control Block Address 4 It is the Control Block address for the FW2 Firmware block.

FW2 Backup of Control Block Address 4 It is the backup of Control Block address for the FW2 Firmware block.

Factory Default Location 2 It contains the factory default elements such as OTP or Flash address. It is reserved for future use.

Factory Default Size 2 It is the total content size of the factory default elements. It is reserved for future use.

Factory Default Address 4It is the starting address of the factory default elements (OTP or Flash address). It is reserved for future use.

File System Address 4 It is the address of the Dynamic file system which will contain configuration files.

File System Size 4 It is the total size of the Dynamic file system.DMA Read Control Word 4 It is the Read control word for Flash interface.

DMA Controller Clock Divider 2 It is the clock divider of the DMA controller which is used to access the Flash interface.

DMA Read Command 2It is the read command OPCODE for reading the Flash. This is always set to QUAD I/O FAST READ (0xEB).

1VV0301447 Rev 1.0 51 of 77 2015-05-05


4.1.4 Boot ApplicationIt is the application used to select the firmware to be loaded upon module boot up.

4.1.5 Backup of Control Block for Boot ApplicationIt is the backup of Control Block for Boot application.

1VV0301447 Rev 1.0 52 of 77 2015-05-05


4.2 Firmware BlockThe GS2000 based modules support 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 the following:

• Control Block, page 54

• Application Firmware, page 56

• WLAN Firmware, page 56

• Static File System, page 56

• Backup of Control Block, page 56

• Static File System, page 57

• Dynamic File System, page 58

1VV0301447 Rev 1.0 53 of 77 2015-05-05


4.2.1 Control BlockThe Control Block comes after the Super Block (see Figure 14, page 54).

Figure 14 Control Block in Module Flash

1VV0301447 Rev 1.0 54 of 77 2015-05-05


Table 46, page 55 describes the Control Block in Module Flash fields.

Table 46 Control Block in Module Flash


Signature 4 FWOK string similar to Super Block that validates the Control Block.

Revision Number 4It specifies the firmware version in Control Block. The latest firmware is identified with a highest Revision number.

Control Block Size 4 It specifies the size of block descriptors.

Block Descriptors - This is a four block descriptors and each block descriptor contains the following information about the static file system in module flash.

Offset 4 It is used to find the absolute address of the static file system in module flash.

Size 4 It is the size of the static file system.

Program Address 4 It is the address generated by the IAR tool while building firmware.

SRAM Address 4

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.

Owner of the Block - It specifies the owner of the block descriptor.

2

Defines who loads the static file system.

0x00 - App Boot ROM

0x01 - Application Firmware

0x02 - WLAN Boot ROM

0x03 - WLAN FirmwareFlags - It specifies a value which indicates one or more combinations of the following operations: (Loading, Mapping, Executing)

2

Special indicators.

Hex Value 0x01 - Load, remap, and run

Hex Value 0x02 - Load and remap

Hex Value 0x03 - Load

Hex Value 0x04 - Load and run

1VV0301447 Rev 1.0 55 of 77 2015-05-05


4.2.2 Application FirmwareThe 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. The Application software can be either Serial-to-WiFi, Temperature and Low Sensor (TLS), TLS Low Power, or any customer specific application.

4.2.3 WLAN FirmwareThe 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.

4.2.4 Static File SystemThe Static File System consists of Webpages, SSL certificates, etc. For more information on Static File System, refer to 4.3 In-Module Flash File System, page 57.

4.2.5 Backup of Control BlockBack Control Block is the same as Control Block (see 4.2.1 Control Block, page 54) and it is used for validating the firmware. If the content in the Control Block and Backup Control Block are not the same in a firmware, then it is considered an invalid firmware.

1VV0301447 Rev 1.0 56 of 77 2015-05-05


4.3 In-Module Flash File SystemThe In-Module Flash File System contains the following:

• Static file system: The Static file system in the module flash contains the web pages and security certificates

• Dynamic file system: The Dynamic file system in the module flash contains default configurations.

4.3.1 Static File SystemThe 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 Webpages 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.

For more information regarding available size and actual usage, refer to Appendix B Firmware Model, page 67.

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.

1VV0301447 Rev 1.0 57 of 77 2015-05-05


4.3.2 Dynamic File SystemApplication software uses the file system API (fopen, fread, fwrite, and so on) to create Dynamic File System during the first boot-up. For more information regarding available size and actual usage, refer to Appendix B Firmware Model, page 67.

The Dynamic File System consists of the following information:

• WLAN calibration information

• Certificates (AT command Adding and Web Page SSL Upload)

• Profile

• MAC Address

The Dynamic File System is represented with the following naming conventions:

• Drive 0

• Drive A

NOTE: It is recommended to use the Dynamic File System for storing custom information (e.g., sensor data, data logs, etc.). Custom applications that need 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 system.

1VV0301447 Rev 1.0 58 of 77 2015-05-05


Chapter 5 Programming Binaries

This chapter provides instructions on how to program binaries and how the information given in the previous chapters are implemented in the GainSpan® gs2k_flashprogram tool. This will allow you to build your own programming tool.

• Programming the Binaries, page 59

• Programming At One Location, page 64

• Programming At Multiple Locations, page 64

5.1 Programming the BinariesThere are two binaries that needs to be programmed:

• Super Block (in this chapter we are using superblock_4MB_3_Copy.bin as an example).

• Single Image Firmware (in this chapter we are using gs2011_s2w_5.1.1.bin as an example).

For more information on flash structure refer to Chapter 4 Memory Map and File System Structure, page 47.

Before programming the Super Block and the Single Image Application Firmware, it is recommended to explicitly erase the in-module flash. Although it is not necessary to erase explicitly it is recommended that you check the entire flash is erased before you do a fresh programming. The reason is that the module will have GainSpan® Factory Test Code. During the production process, there might be some dynamic file system data left on the flash. That’s why it is recommended to erase the entire flash. You can use the Flash Erase Check command and get the size of the flash that needs to be erased in order to have a completely erased flash. Then do an erase check again to verify if it is completely erased. This is implemented in the GainSpan gs2k_flashprogram tool.

The Memory Map Module Flash is described in 4.1 Flash Structure, page 48 and in Figure 12, page 48.

1VV0301447 Rev 1.0 59 of 77 2015-05-05


Super Block

The Super Block binary gets programmed at the 0x00000000 location (see Figure 15, page 60). “superblock_4MB_3_Copy.bin” is the name of the Super Block provided. Every Super Block includes a Boot ROM Super Block and an Application Super Block. The address where the Single Image Firmware would get programmed is taken from the Application Super Block. The Application Super Block starts at 0x1000 location of the main Super Block (see 4.1.1 Super Block Structure, page 49).

Figure 15 Super Block

1VV0301447 Rev 1.0 60 of 77 2015-05-05


Single Image Firmware

Single Image Firmware: The Single Image gets programmed at FW0 Control Block Address Field as shown in the illustrations below. This address would change based on the Super Block being used so it has to be read from the Super Block. In case of the superblock_4MB_3_Copy.bin, this address would be 0x00010000.

After the Single Image is programmed, you need to extract the first 4KB of the Single Image and Program it at the FW0 Backup Control Block address which is 0x001f0000 in case of the binaries sent. This 4KB is called as the Control Block. The Control Block is a part of the Single Image at the beginning but in order to complete the Firmware Block you need to put the same Control Block copied from the Single Image at the Backup Control Block location.

Update the REVISION Number field in both the Control Block areas. The default revision field of the Control Block (copied from the first 4KB of Single Image) contains 0xFFFFFFFF (see Figure 17, page 63). This should be modified to 0x01 (see 4.2.1 Control Block, page 54).

Programming

Every GainSpan module flash can have one or more than one firmware at a time. The firmware with the highest REVISION number is the copy that would be active and is called as the CURRENT VERSION.

The firmware with the lowest REVISION number is called the FACTORY VERSION and the firmware with a REVISION number between the highest and the lowest REVISION numbers is the PREVIOUS VERSION.

Select three options for firmwares other than for Super Block Image:

• Current Version

• Previous Version

• Factory Version

1VV0301447 Rev 1.0 61 of 77 2015-05-05


Figure 16, page 62 shows the flash memory structure for Two Firmware Model or Three Firmware Model.

Figure 16 Flash Memory Structure

The firmware image provided by GainSpan contains 0xFFFFFFFF in the REVISION number field. This field should be modified on the flash with the appropriate REVISION Number. You should have the capability to program one image, two images or three images based upon his selection and the Super Block you are using.

There can be four different types of Super Blocks:

• Superblock_4MB_3_Copy




Three cases for programming:

Case 1 - Programming Only One Firmware Image

Regardless of the Super Block file selected, program the firmware at FW0 Control Block address with REVISION Number 0x01. This firmware would be the CURRENT VERSION.

Case 2 - Programming Two Firmware Images

Use any of the above mentioned four Super Blocks and program the CURRENT VERSION firmware at FW1 Control Block address with REVISON Number 0x02 and the PREVIOUS VERSION firmware at the FW0 Control Block address with REVISION Number 0x01.

Case 3 - Programming Three Firmware Images

You could use only Superblock_4MB_3_Copy or Superblock_2MB_3_Copy images and program the CURRENT VERSION firmware at FW2 Control Block address with REVISON Number 0x03, and the PREVIOUS VERSION firmware at the FW1 Control Block address with REVISION Number 0x02 the FACTORY VERSION firmware at the FW0 Control Block address with REVISION Number 0x01.

1VV0301447 Rev 1.0 62 of 77 2015-05-05


The REVISION Number field in this image would be 0xFFFFFFFF and should be modified on the flash appropriately based upon which copy is it, and which Super Block type is selected. The same Control Block needs to be programmed at the Backup Control Block Address as explained in the document we sent.

Figure 17 Control Block Revision Number Field

NOTE: The Control Block is part of the Single Image Firmware that is provided. This is the first 4KB of the image.

1VV0301447 Rev 1.0 63 of 77 2015-05-05


5.2 Programming At One LocationTo program at one location, perform the following:

1. Select the Super Block Image and a Working Copy Image.

2. Program Super Block at 0x00000000

3. Verify that programmed Super Block has a valid “FLOK” signature.

4. Read the Application Super Block that starts from 0x1000 location and store the Control Block and Backup Control Block Addresses for FW0

5. Write the Single Image at the Control Block address for FW0 and modify the REVISION field in the Control Block from 0xFFFFFFFFFF to 0x01.

6. Copy the same modified Control Block and program it at the Backup Control Block address for FW0.

5.3 Programming At Multiple LocationsTo program at multiple locations, perform the following:

1. Select the Super Block Image and a Working Copy Image, Previous Copy Image and/or Factory Copy Image

2. Program Super Block at 0x00000000

3. Verify that programmed Super Block has a valid “FLOK” signature.

4. Read the Application Super Block that starts from 0x1000 location and store the Control Block and Backup Control Block Addresses for FW0, FW1, and FW2.

5. Write the Factory Copy Image at the Control Block address for FW0 and modify the REVISION field in the Control Block from 0xFFFFFFFFFF to 0x01.


7. Write the Previous Copy Image at the Control Block address for FW1 and modify the REVISION field in the Control Block from 0xFFFFFFFFFF to 0x02.


9. Write the Factory Copy Image at the Control Block address for FW2 and modify the REVISION field in the Control Block from 0xFFFFFFFFFF to 0x03.


NOTE: For detailed explanation at byte level, refer to Chapter 2 Download Class Messages, page 27, and Chapter 3 ROM Debug Class Messages, page 35.

1VV0301447 Rev 1.0 64 of 77 2015-05-05


Appendix A Opcodes

This chapter provides an overview of the Opcodes for the GS2000 based modules. Table 47, page 65 describes the Opcode message and command response examples.

Table 47 Opcode Message and Command Response

Message Command ResponseOpCode Example OpCode Example

Download 0x01A5 02 00 00 00 ED 03 0D 01 00 00 40 00 00 E1 03 00 00 00 00 66 77 6F 6B FF FF FF FF 50 00 00 00 04 30 00 00 00 ……

- A5 02 00 00 00 02 00 FB 05 00

Copy0x02,0x82

A5 02 00 00 00 16 00 E7 82 11 00 00 01 00 00 40 00 00 00 00 00 00 3A D9 EC FF 00 00 00 08

- A5 02 00 00 00 02 00 FB 05 11

Error Indication - - 0x04 -Ack - - 0x05 -

RegPeek 0x41 A5 07 00 00 00 11 00 E7 41 01 00 00 00 00 00 08 40 00 00 00 00 04 00 00 00

0x81 A5 07 00 00 00 11 00 E7 81 01 00 00 00 00 00 08 40 50 50 41 00 04 00 00 00

RegPoke 0x42 A5 07 00 00 00 11 00 E7 42 01 00 00 00 18 00 08 40 78 56 34 12 04 00 00 00

- -

MemRead 0x43 A5 07 00 00 00 09 00 EF 43 00 05 04 20 10 00 00 00

0x84A5 07 00 00 00 19 00 DF 83 00 05 04 20 10 00 00 00 00 00 00 00 33 33 00 3E 45 49 4D 31 31 30 32 00

MemWrite 0x44A5 07 00 00 00 F7 03 FE 44 00 00 03 20 EE 03 00 00 80 B5 00 F0 ED FA 01 BD 2D E9 F2 4F 84 B0 07 00 15 00 1C 00 5F ……

- -

FlashRead 0x46 A5 07 00 00 00 09 00 EF 46 00 00 01 00 0C 00 00 00

0x86 A5 07 00 00 00 15 00 E3 86 00 00 01 00 0C 00 00 00 66 77 6F 6B FF FF FF FF 50 00 00 00

FlashErase 0x49 A5 07 00 00 00 09 00 EF 49 00 00 00 00 00 00 40 00

0x89 A5 07 00 00 00 09 00 EF 89 00 00 00 00 00 00 40 00

FlashChecksum 0x4C A5 07 00 00 00 09 00 EF 4C 00 10 01 00 00 E0 0F 00

0x8C A5 07 00 00 00 05 00 F3 8C 52 1B 09 B7

FlashEraseCheck 0x4D A5 07 00 00 00 09 00 EF 4D 00 00 20 00 00 00 20 00

0x8D A5 07 00 00 00 09 00 EF 8D 00 00 20 00 00 00 06 00

Execute at Address 0x45 A5 07 00 00 00 05 00 F3 45 01 00 03 20 0x85 A5 07 00 00 00 05 00 F3 85 00 01 00 03

WLAN Start 0x47 A5 07 00 01 00 01 00 F6 47 - -WLAN Stop 0x48 A5 07 00 01 00 01 00 F6 48 - -

1VV0301447 Rev 1.0 65 of 77 2015-05-05



1VV0301447 Rev 1.0 66 of 77 2015-05-05


Appendix B Firmware Model

This chapter provides an overview of the Firmware Model Memory Map for software releases 5.1.x and 5.2.x.

B.1 Memory Map for 5.1.x ReleasesTable 48, page 67 lists the available size and currently used size for file systems 5.1.x releases.

Table 48 Firmware Model File System Sizes for 5.1.x Releases

5.1.x Releases Two Firmware Model (2MB)

Three Firmware Model (2MB)

Two Firmware Model (4MB)


Available Static File System (Webpage) 320KB 64KB 1088KB 576KB

Used Static File System (currently used)

64KB 64KB 64KB 64KB

Available Dynamic File System (Webpage)

448KB 448KB 512KB 512KB

Used Dynamic File System (currently used)

256KB 256KB 256KB 256KB

1VV0301447 Rev 1.0 67 of 77 2015-05-05


Figure 18, page 68 shows the memory map for a 2MB Two Firmware Model in 5.1.x releases.

Figure 18 Two Firmware Model for 5.1.x Releases (2MB)

1VV0301447 Rev 1.0 68 of 77 2015-05-05


Figure 19, page 69 shows the memory map for a 2MB Three Firmware Model in 5.1.x releases.

Figure 19 Three Firmware Model for 5.1.x Releases (2MB)

1VV0301447 Rev 1.0 69 of 77 2015-05-05


Figure 20, page 70 shows the memory map for a 4MB Two Firmware Model in 5.1.x releases.


1VV0301447 Rev 1.0 70 of 77 2015-05-05


Figure 21, page 71 shows the memory map for a 4MB Three Firmware Model in 5.1.x releases.


1VV0301447 Rev 1.0 71 of 77 2015-05-05


B.2 Memory Map for 5.2.x ReleasesTable 49, page 72 lists the available size and currently used size for file systems 5.2.x releases.

Table 49 Firmware Model File System Sizes for 5.2.x Releases

5.2.x Releases Two Firmware Model (2MB)

Two Firmware Model (4MB)


Available Static File System (Webpage) 124KB 892KB 380KB

Used Static File System (currently used) 64KB 64KB 64KB

Available Dynamic File System (Webpage) 448KB 512KB 512KB

Used Dynamic File System (currently used) 256KB 256KB 256KB

1VV0301447 Rev 1.0 72 of 77 2015-05-05


Figure 22, page 73 shows the memory map for a 2MB Two Firmware Model 5.2.x releases.


1VV0301447 Rev 1.0 73 of 77 2015-05-05


Figure 23, page 74 shows the memory map for a 4MB Two Firmware Model 5.2.x releases.


1VV0301447 Rev 1.0 74 of 77 2015-05-05


Figure 24, page 75 shows the memory map for a 4MB Three Firmware Model 5.2.x releases.


1VV0301447 Rev 1.0 75 of 77 2015-05-05



1VV0301447 Rev 1.0 76 of 77 2015-05-05