Digi Connect ME(TM) Dual-Boot Example Application
====================================================

Version 1.0.0

http://www.digi.com

This is a example NET+OS(R) application for the Digi Connect ME embedded 
module, which is provided on an "as is" basis without product support by Digi 
International. See software license section in this document for additional
information.

This example demonstrates a method by which one may store two application 
binary images (image.bin and backup.bin) in the flash of a Digi Connect ME or 
other NET+ARM device.

This example was written specifically using NET+OS 6.3, build
6.3.20.0 and is being provided as-is in hopes that it may prove
to be of some use to those looking for such support and/or wishing
to gain a deeper understanding of the build process and BSP.

This example provides a modified version of the boot loader, the
naftpapp example application, as well as several modified BSP files
through which the 'dual-boot' functionality is implemented.

Upon system power up the boot loader validates the application image, 
if the image is found to be valid it is copied to RAM and executed. If,
however, the image is invalid the backup image is copied to RAM and 
executed. With this implementation there it is assumed that the backup
image is never invalid. 

The flash of the Connect ME has been modified to use the following basic map:

Bootloader              First 64KB
Application Image       Next 'MaxFileSize' Bytes, as defined in bootldr.dat
BackUp Image            Next 512KB
Flash File System       Next 256KB
Unallocated Space       Possible unallocated space between FFS and NVRAM, this
                        size of this space can vary based on the amount of 
                        Flash on the device and the defined sizes for all
                        other defined components.
NVRAM                   Last sector (64KB) or flash

The contents of the netos63_gnu sub-directory should be copied
to the so name sub-directories of your individual NET+OS 
installation. It is highly recommended that backups of the 
original files are made prior to copying any files from this 
example over. 

This example should work on most development boards, but has specifically 
been tested on the Connect ME and EM, support for the Wi-ME and Wi-EM 
should also be possible, however modification to the customize.ldr file will
be necessary where one must increase the space allocated for the backup image,
BACKUP_IMAGE_SIZE, needs to be modified to 720KB (minimum) in order to 
accomodate the resultant image. For other custom platforms this value may need
to be modified in either direction.

The following files are provided with this application:


appconf.h                                               sets application configuration settings
root.c                                                  contains the applicationStart() function, 
                                                        that starts the FTP server thread
readme                                                  this file
naftpapp.c                                              contains the RAM based FTP application code
32b/makefile                                            Make file for the GNU toolset.
netos63_gnu/h/bsp_api.h                                 Modified version of original file
netos63_gnu/src/bsp/common/bsp_api.c                    Modified version of original file
netos63_gnu/src/bsp/init/arm7/blram.ldr                 Modified version of original file
netos63_gnu/src/bsp/init/arm7/blrom.ldr                 Modified version of original file
netos63_gnu/src/bsp/init/arm7/image.ldr                 Modified version of original file
netos63_gnu/src/bsp/init/arm7/rom.ldr                   Modified version of original file
netos63_gnu/src/bsp/platforms/connectme/blmain.c        Modified version of original file
netos63_gnu/src/bsp/platforms/connectme/customize.ldr   Modified version of original file

All changes made to the C source and header files, in respect to the implementation of the 
backup image support have been surrounded by comment statements, as such:

/* Start Backup Image Modifications */
The modifications will be here
/* End Backup Image Modifications */

In the case of some files there will be multiple areas where modifications had to be made; be
certain to search each file entirely, in order to identify all changes. In the arm/init/*.ldr 
files, where adding comments can be problematic the following two lines were added:

_NABackupMaxSizeInFlash = BACKUP_IMAGE_SIZE;
_NABackupImageFlashAddress = FLASH_START + APP_START_OFFSET_IN_FLASH + APP_MAX_SIZE_IN_FLASH;

In platforms/connectme/customize.ldr the following changes were made:

#ifdef OUTPUT_COMMENT_TO_LINKER_SCRIPT
/*
 * Amount of flash reserved for the backup application image.
 */
#endif
 
#define BACKUP_IMAGE_SIZE   512K

AND

#define APP_MAX_SIZE_IN_FLASH   (FLASH_SIZE - (APP_START_OFFSET_IN_FLASH + NVRAM_FLASH_SIZE + FILE_SYSTEM_SIZE + BACKUP_IMAGE_SIZE))
/* 
 * #define APP_MAX_SIZE_IN_FLASH   (FLASH_SIZE - (APP_START_OFFSET_IN_FLASH + NVRAM_FLASH_SIZE + FILE_SYSTEM_SIZE)) 
 */
 
Using this example:

1. Copy the file within the netos63_gnu sub-direcotry, of this example application, into
   your NET+Works environment. Make a backup of all affected files prior to performing this
   step. If you are using a platform other than connectme copy the contents of this example's
   connectme sub-directory into your platforms directory.
2. Rebuild your BSP. 
3. Build this example application.
4. Load and execute this application via your debugger.
5. From the c:\netos63_gnu\src\apps\nadual_boot\32b directory, us a FTP client and upload this
   example's image.bin file as backup.bin, i.e. 'put image.bin backup.bin'.
6. Exit the FTP client and allow the Connect ME to reboot. As the boot loader has not been replaced the 
   currently stored application will be executed, assuming there was a valid image in flash previous to 
   starting this procedure.   
7. Quit and restart the debugger, executing the ndual_boot example.
8. From the c:\netos63_gnu\src\bsp\platforms\connectme directory, use a FTP client and upload the
   platform's rom.bin (boot loader) image. Do not forget to put the client into binary mode first.
9. In order to test this application properly you will need to make the currently stored application 
   image invalid. Do this by creating a simple application that erases part or all of the flash sectors
   where the primary image is stored. On the Connect ME this is sectors 5-17 (832KB). 
10. Load and execute this example via the debugger. Once completed a power cycle of the Connect ME
    should show that the backup application has been executed.
    
It is strongly urged that one perform initial tests of this example application using a JTAGed Connect ME
before using it on a JTAGless module.
