[Tinyos-contrib-commits] CVS: tinyos-1.x/contrib/imote2/tools/src bootloader.doc, NONE, 1.1

[Lama Nachman]

Update of /cvsroot/tinyos/tinyos-1.x/contrib/imote2/tools/src
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv13661

Added Files:
	bootloader.doc 
Log Message:
Bootloader document


--- NEW FILE: bootloader.doc ---
ÐÏࡱá

ge to be loaded must have its text section placed in the right address know to the bootloader, so that the bootloader can jump to the application level code.
The methods to place the TOS Loader in Code Load Mode using USB should be automatic with minimal user interaction.
The TinyOS application can chose to perform SELF_TEST by setting the right attribute, if it does so then it is responsible for conveying the results to the boot loader.










Extra Features:
The BootLoader could maintain two different application images in the flash at known locations. One of the application images will be the current BOOT_IMAGE. The current application could receive a command over the radio to change the current boot location to the secondary image, which is the old working image.
Terminology:
Attribute (or Parameter): A Name value pair stored in the flash and is used by both the BootLoader and the Application.
BOOT_LOCATION: An attribute whose value is the start address of a valid application image.
SECONDARY_IMAGE: An attribute whose value is the start address of a previously used image.

Assumptions:
BootLoader is designed currently to load an OS which can initialize the hardware by itself (like TinyOS).
The image loaded from the PC must be in binary format.
The application (TinyOS) is responsible for setting the correct attribute parameters if a self test is required. The boot loader actions depend on its state which is set to NORMAL by default and its reset to NORMAL unless it is asked not to do so.
Application (TinyOS) performs the self test of the newly loaded image.  It has to convey the results to the boot loader for verification.




High Level Architecture:
BootLoader:
Functionality:
Load new application image to the flash over USB by synchronizing with the PC application.
Verify the CRC of the programmed image and assign it to be the “boot image”.
Jump to the “boot image” during normal operation, when there is no code to be loaded.
Prepare the application for SELF_TEST mode by setting the watch dog timer with sufficient interval for the application to perform the tests. This mechanism will enable an automatic reboot even if the application fails.
Overview: 	The boot loader is a self contained application that occupies the first few blocks in the flash memory and executes whenever the processor exits the reset state. It acts as a gateway for running the TinyOS application and also provides the code loading functionality through USB. The code loading functionality will eliminate JTAG and debug board to be used only for programming purposes (Source level debugging still requires both JTAG and debug board). The ability to allow the user to load new code is critical, but the most common case is to run a TinyOS (or like) application. The Boot Loader is optimized to reduce any unnecessary delays due to synchronizing with the PC. This is achieved by a series of checks, first of which is the presence of USB cable, if the USB is not connected then the BootLoader assumes that it has to jump to the TinyOS application and bypasses the PC synchronization part. 	The PC Application reboots the board (by sending a command to TinyOS application or by requesting the user to reboot manually) and waits for a sync command from the BootLoader. The BootLoader detects the USB cable and sends a sync command to the PC Application. The handshake between PC and the BootLoader will place them in a code loading mode where the image from the PC will be transferred to the BootLoader. Each packet is validated by the BootLoader using CRC check before it is placed in the secondary image location of the flash. The Image is considered to be “bootable” only after the complete image CRC (CRC of the whole image) is verified between the PC and the BootLoader. The BootLoader is responsible for checking the validity of the image and mark it as bootable. The BOOT_LOCATION is an attribute which is writable only by the BootLoader. 	Over the air code download through radio occurs in the TinyOS application. The packets are CRC verified and are placed in the secondary image location of the flash. If self test is disabled by the application then the boot loader verifies the validity of the image be
fore making it as the new bootable image. The application can optionally perform self test by setting the SELF_TEST attribute to TRUE. Self test is defined as a test to confirm the capability of the new image to download code and write it to the flash.  	If a self test is required then the boot loader sets the watch dog timer to a fixed time interval (TBD) and jumps to the application to let it perform the self test. As a part of the test the application downloads a known static image from the remote server and stores it in the flash. The copy of the test image should be already stored in the flash for the boot loader to verify. After watchdog reset the boot loader compares the downloaded test image with the preloaded test image to validate the self test. Upon successful verification the downloaded image is made bootable. .  The boot loader deletes the test image to prepare for next time.
Operation:
As a first step Boot Loader locks down the parts of flash that needs protection from software overwrite. This is because after each reboot the pxa flash memory moves from a “Locked-Down” state (Hardware Protection for writing) to a “Locked-State” which could be unlocked by the software by using the “Unlock” command sequence. Since we cannot trust the application not to interfere with the boot loader, the Boot Loader needs to reestablish the hardware lock after every reboot.
The Boot Loader operation is controlled by a state machine, in the NORMAL_STATE the Boot Loader tries to load an application from the BOOT_LOCATION (a known and fixed memory location). The state is also used as a communication mechanism between the application and the Boot Loader, in other words the application could place the Boot Loader in various states, like LOAD_CODE (internal state), VERIFY_NEW_IMAGE and SELF_TEST_DONE.
The boot loader always tries to sync with the PC after every reboot, unless the state is VERIFY_NEW_IMAGE. In this state the application has already loaded an image over the air in the secondary image location and requires the boot loader to verify the image and assign it to be the “boot image”.
The Boot Loader tries to synchronize with the PC software using USB. If there was a response from the PC side then it syncs with the PC software to load the appropriate code.
The binary image is divided in to pages, which is a fixed number of USB packets. The CRC check verification at the boot loader occurs after each page is downloaded. To efficiently use the resources the USB download continues while the previous page is being processed and transferred to the flash.

If the USB cable is not connected or if the sync fails with the PC application then the Boot Loader assumes that it has to jump to the application if there is a valid one.
If there is no valid application in the flash then the Boot Loader loops around trying to detect a USB connection and syncing with the PC application.
Any new image downloaded in to flash (whether it was downloaded through the application via radio or the Boot Loader) goes through the verification process automatically before it is marked valid. Code loading through the radio occurs at the application level. The application receives the new image through the radio and places it in SECONDARY_IMAGE location. The validation of this image occurs at the Boot Loader, so the application could place the Boot Loader in VERIFY_NEW_IMAGE state and reboot to get the Boot Loader to verify the image.
The application could notify the boot loader that a self test will be performed by setting the SELF_TEST attribute to TRUE.
Code Download process: 	 	The code loading through USB occurs as chunks of binary image. The HID USB class used by the drivers for communicating with the PC has a maximum limit of 64 bytes per packet, out of which three to four bytes are used at the higher level for protocol definitions, which leaves about 60 bytes per packet for th
e binary data. USB Packets are the basic blocks and the chunks are basically a group of packets. The size of the chunk is flexible for fine tuning the performance of data upload. 	The boot loader checks the CRC of the payload of the chunk and verifies it with the PC application before writing it to the flash.  If the CRC fails then the same chunk is downloaded again. This cycle is repeated till the complete image is downloaded. This process is described in fig 1.0. SHAPE  \* MERGEFORMAT 
                                      fig 1.0
Communication with PC application in CODE_LOAD Mode SHAPE  \* MERGEFORMAT 
                                      	fig 1.1
Communication with PC application in Command Line Mode



 SHAPE  \* MERGEFORMAT 

           
                          	fig 1.2
		Radio Load Mode with out SELF_TEST



 SHAPE  \* MERGEFORMAT 


                          	fig 1.3
			Radio Load Mode with SELF_TEST


PC Application:
Functionality:
The PC Application is a command line based tool to upload code to the IMote2 board by synchronizing with the BootLoader.
It also acts as a client for a command shell built in to the BootLoader (like BluSh).

Operation:
Allows the user to pass command line parameters to choose the operation mode (loading or command shell), specify the image to be loaded etc.
Allow the user to enter commands to be sent to the BootLoader and display the response from the BootLoader.
Respond to commands from the BootLoader which will include providing information like, image size, CRC of the image etc.


Modules:

This section explains the modules in the BootLoader and its functions.

Hardware Init:
Processor Initialization:
Enable the System Clocks.
Enable the 32 KHz timekeeping crystal.
Initialize MMU. 
Enable Instruction and Data cache.
Sync Flash.

Set the pin directions:
The pin settings will differ for the TinyOS because we will not be using most of the peripherals that are normally used in the application level. For example, the initial version of the boot loader will not include the radio in its image, so potentially configuring FIFOP, FIFO as input is not required.



Enable the USB communication:

The USB Communication with the PC is one of the first things that the BootLoader will require. So the init process will initialize the USB Client and load the driver for PC communication.
Code Loader and USB Driver:
Entering Code Load Mode:
The TOS Loader could be placed in code load mode in 2 ways.
When the user tries to load code in to IMote2, the PC application will try to communicate with the TinyOS application to reboot the board. If there is no response from the TinyOS application, then it requests the user to reboot the board. After reboot the BootLoader will sync with the PC application and download code through the USB.
The USB Driver in the TinyOS application will have ability to identify the Code_Load command from the PC App. This command will reboot the board to let the BootLoader synchronize with the PC. 
Code Loading:
Download binary image from the PC. The image is divided in to pages which will be a fixed number of USB packets. A CRC check will be performed on each page and the final packet which will be a LOAD_DONE packet will have the CRC of the whole image.
Data Flow Diagram for Code Load: EMBED Visio.Drawing.11  
                                         Fig 1.3                              USB Load data flow
PC Sync Mode:
Enable USB in a detect mode for code upload. The BootLoader sends a boot report to the PC and waits for a response. The PC application responds with a specific command to place the BootLoader in Code Load Mode. If there is no response from the PC for the “boot report” then BootLoader times out and jump to the application.
USB Driver:
The current USB driver will be in C, which will communicate with the hardware and move bytes to and from the PC application.
The ability to multiplex based on packet types will be built in to the driver, based on the PacketType the data will be routed to different higher level applications like BluSH, and CodeLoader.
Flash Partition:
Flash Sections: 
The 32MB of PXA271 flash is divided in to 16 sectors each of 2MB size. Each partition could be further divided in to either 128KB (Main Block) or 32KB (Parameter Block) Blocks. 
The first 15 sectors will be treated as Main Blocks and the last sector which will contain the partition table and the attributes will be a Parameter Block.
Each main partition will contain 16 blocks and the parameter partition will contain 64 blocks.
Code Partitions:
The BootLoader will occupy the first 8 blocks (of size 128k each) (TBD Need to know the size of the BootLoader image). The first eight blocks in the flash will be in “locked-down” mode in order to protect the BootLoader code.
The application code could be placed starting from the 9th block of the first partition. The exact starting address of the application should be in the partition table. 
The partition table will allow multiple application address entries to facilitate storing more than one image in the flash and be able to boot from any one of those. The Boot_Address parameter in the attribute table will provide one of the booting addresses.
Attribute Storage:
The attributes and the partition table will be placed in the last sector of the flash. Starting at 0x1e00000, the sector will contain 32KB blocks, each block will hold different attribute tables (see section 5 for attribute tables).

                         EMBED Visio.Drawing.11  
					Fig 1.4
Flash Partition in Imote2

Flash Driver and Code Verifier: 

Flash Driver:

Read, Write, Lock, Unlock, and allow all the required Flash operations.

Code Verifier:
Code verifier must be able to read a selected image from the flash and be able to verify the image with any user defined image file.

Parameter Partition and Attribute Table:
The last partition of the flash starting at 0x1E00000 is configured as a Parameter partition, which will hold the Attribute tables. Each Attribute table will be placed in one of the 32KB blocks for configuring the access control of the attribute table. 
Attribute Definition:
The Attributes keeps track of various system parameters and also functions as a communication between the TOS Loader and the application layer. Each entry in the attribute table will be a structure with the following fields (Table 1.0), 	
      Field       Data Length                   DescriptionTypeByteThe type or name of the attribute.ValidityByteDenotes if the attribute value is valid in that location. The possible values could be VALID – Latest valid value.UPDATING – Updating in new location.INVALID – Jump to NextAddress Location. LengthByteLength of the Attribute Value.Value<Length>Value of the Attribute.NextAddress4 BytesIf Validity = INVALID then this could be the next possible address to check for Validity. 				Table 1.0
Attribute Access:
Every attribute will have its own “access macro” which will provide the application with an interface to read and write attribute values. 
At a higher level the application will be provided with a generic Read and Write macro for accessing the attributes.
If a new attribute has to be added to the table, then it is required to create a new MACRO to access that attribute. The naming convention for the macro will be defined in the header (*.h) file.
Updating an attribute value will create a new entry for the attribute in the corresponding flash block. The NextAddress of the old entry will be updated to the current location of the attribute to form a linked list. The Validity of the old location will be flipped to Invalid.
If there is no space for writing new data in the current attribute block, then an Update_Attribute_Block function will fetch all the current value of the attributes in the block and will reset the attribute table with the latest values after a complete block erase.
The attribute tables are listed below:
Address Table:
Address map of all the attribute tables which enables an application to jump to the proper l
ocation to load the attribute table. 
This table is read only for both the BootLoader and the Application.
Partition Table:
This table will contain the starting address of each section of the flash memory. 
This table will be read only for the application and Read/Write for the BootLoader. 


Default Attribute Table:
A list of attributes either for the application or for interaction between the application and the TOS Loader. For example, this table could contain BOOT_ADDRESS (Address where the application should be booted from), BOOT_TIME_OUT etc. 
This table will be read only for both the TOS Loader and the application.

User Defined Attribute Table:
The list is same as above, but will have write permission for both the application and the TOS Loader. This table will override the default settings.
This table will have Read/Write permission for both the application and the BootLoader.

The diagram explains the attribute access data flow. EMBED Visio.Drawing.11  
                                                 Fig 1.5                                Attribute Access Data Flow
Message Integrity checker:
Check for CRC of the downloaded image before writing to the Flash. The TOS Loader could use any of the existing CRC code for image integrity check.
Blob also contains MD5 code that could be used for encryption purposes, if required.
Timers:
Simple Timer module for time out etc.
Diagnostic commands:
The concept of providing a command line tool for the user already exist in the form of BluSh in the IMote2 tinyos repository. The command line tool could provide the user with diagnostic commands like flash_memory_check, change_attribute, list_attribute etc. 

PC Application:
Command line application which syncs with the TOS Loader to load code in to the IMote2.
 Load the code using USB (or Radio).









PAGE  


PAGE  1



USB Load Mode

Boot Announce

<PC Application>

<Boot Loader>

Time out if no response

Request image details

Image Size, CRC, No of USB Packets

Request Packets 1-k

Binary Image Packet

Drop Chuncks on CRC failure and re-request

Load Completed

Reboot

Download Test Code

Set Watchdog and jump to App

<BootLoader>

<PC Application>

Set Self_Test


Response

Command

Time out if no response

Command line mode

Boot Announce

Check SELF_TEST

<Network>

Get State

Load Code

<Attribute>

<BootLoader>

<TinyOS App>

Request Packets k+1 - N

Drop packet on CRC failure and re-request

Binary Image Packet

No Self_Test


Check SELF_TEST

<Network>

Get State

Load Code

<Attribute>

<BootLoader>

<TinyOS App>

Verify New Image

Reboot

Change to
VERIFY_IMAGE

Compare the test images in flash

Reboot

Change to
VERIFY_IMAGE

Set LOADER_STATE = VERIFY_2





„














[...1283 lines suppressed...]

*q
>¹



.
J
f
„
—
9ò
ù
T