WinCE: Updater Framework

Introduction

Updater framework is a set of drivers, libraries, applications and configuration files intended for Windows CE installation to systems based on CompuLab products. This document describes the Updater flow and operating environment.

Document Conventions

• Updater OS - the complete bootable operating system image that includes drivers, libraries applications and configuration files necessary to install Windows CE on the target system.
• Updater Application - an application that performs installation of operating system images and (optionally) user data onto the target system.
• Source storage - the storage media that contains images that will be installed on the target system. The source storage may also be used as the boot media for the device and contain the Updater OS.
• Target storage - the storage media that normally holds operating system image and (optionally) user data. In most cases the target storage is the on-board NAND flash.
• Target OS - one or more binary images that will be installed on the device.

Overview

The CompuLab Updater framework is designed to support the Windows CE installation on the evaluation kit. The following highlights describe Updater framework features:

• installs the CompuLab generated images to the target storage
• completely erases the flash
• sets bootloader parameters to OS-required defaults
• can use any storage device available in the evaluation kit for image sources
• easy and intuitive

Operating environment

The Updater Application is available on all Windows CE platforms supported by CompuLab. Each OS - hardware combination has platform specific customizations for general Updater framework.

Hardware setup

Current Updater framework functionality is designed for CompuLab base board supplied with the evaluation kit. Such policy has the following benefits:

• Well defined module hardware connectivity options
• Provides hardware access to display that allows to perform GUI feedback during update flow
• Allows to use verified Updater OS provided by CompuLab for all custom module configurations independently of custom base board support

Updater Invocation

The Updater Application supports two major invocation modes:

• The system boot is performed from non-default storage into dedicated Updater OS. In this case the Updater Application can have full control over the target storage.
• The system boot is performed from the default storage. In this case the Updater Application is not allowed to overwrite the live system. This in turn poses a requirement for availability of dedicated Updater OS partition on the default storage or external bootable media with Updater OS.

When the Updater Application is invoked on the live system, it will setup configuration files and boot parameters for the Updater OS and issue reboot to the Updater OS.

Source storage access

The source data for the installation/update may reside on

• USB flash
• MMC/SD card
• internal storage(NAND) partition

The Updater OS provides required drivers and configurations for the source storage mount in Updater Application.

Target storage access

Target storage is accessed via target media driver in the Updater OS. The target media (NAND) driver provides raw access (e.g. NAND FMD) to the media and file based access for data partitions (e.g. NAND FAL/FMD).

Update Flow

General update flow includes:

• prepare source storage content
  • source storage content includes configuration (e.g. XML) file that describes installation process
• setup source storage access
  • connect external media
• boot module
• boot Updater OS
• get access to source storage
  • mount source storage content
• invoke Updater Application
  • execute updater flow defined in .xml file

Updater framework functionality

Target storage layout

Target storage (default internal storage) is composed of one or more physical devices. Further it can be logically divided according to the following region types:

• Unique region
• Boot region
• Target OS region (can be more than one for multi-boot support)
• Reserved region

Each region can be further divided into logical entities, which are defined below according to region type.

Unique region

Unique region can reside in predefined location in NAND, or NOR flash, or in the different read only physical device, such as EEPROM. Content of unique region is updated once during production process.

Boot region

It is important to guarantee hardware write protection to boot region, otherwise in case of accidental content damage the module must be re-manufactured. Typically the boot region contains the following entities:

• bootstrap
• bootstrap parameters
• bootloader
• bootloader parameters
• splash screen
• bootloader reserved

The bootstrap and bootloader implementation is depended on hardware architecture and supported OS.

Each entity can appear multiple times for redundancy.

Target OS region

Typical OS region layout suitable for Windows CE from the target OS point of view contains the following entities:

• partition table
• optional Updater OS partition
• kernel partition
• optional OS partition
• user data partition
  • read/write access allowed
• optional user read-only data partition for critical user data

To guarantee reliable OS operation the OS region should be hardware write protected except the user data partition

Reserved region

This region is used for NAND flash bad block compensation, i.e. to unify the logical length of target medium on different NAND flash chips. It is always placed at the end of the medium. A typical example is relocation table that reserves 127 blocks at the end of NAND storage on CM-X300.

Updater Application

The Updater Application is launched automatically by the Updater OS and executes the update flow in the following manner:

• The update flow is unattended
• The actions specified by the XML configuration file are executed sequentially
• The GUI provides progress notification for each action
• Each action is reported to a log file and to the serial console

The Updater Application uses the XML syntax for its configuration file. There are three major sections in the Updater Application XML file (script.xml):

• Source storage section - provides the source storage access and logging information
• Target storage section - provides the target storage layout information and links it to the source storage content
• Update flow actions section - provides the list of the sequentially executed update flow actions with parameters

Source storage XML section

The <source_storage> element is used to define the source storage section. The following XML elements are used in this section:

• <access_information> - container element for source storage access information

child element	mandatory	values	description
<device_type>	yes	"usb" "sd" "network"	specifies the type of the source storage device
<mount_path>	yes	string value	specifies the file path for the source storage access. Updater Application will automatically mount this path if needed

• <logger_information> - container element for logging information
• <logger_information><updater_logger> - container element for Updater Application logging information

child element	mandatory	values	description
<file_name>	yes	string value	specifies the relative file path of the log file that will be stored on the source media
<append_log>	no	"true" "false"	specifies the log append policy
<verbosity>	no	"debug" "info" "error" "none"	specifies the verbosity of the log messages

• <logger_information><system_logger> - container element for Updater OS logging information

child element	mandatory	values	description
<file_name>	yes	string value	specifies the relative file path of the log file that will be stored on the source media
<append_log>	no	"true" "false"	specifies the log append policy
<verbosity>	no	"debug" "info" "error" "none"	specifies the verbosity of the log messages

Source storage XML syntax example

Source storage syntax example is taken from the CM-T3530 installation script:

<source_storage>
   <access_information>
     <device_type>USB</device_type>
     <mount_path>\Hard Disk</mount_path>
   </access_information>
   <logger_information>
     <updater_logger>
       <file_name>updater_log.txt</file_name>
       <append_log>false</append_log>
       <verbosity>debug</verbosity>       
     </updater_logger>
     <system_logger>
       <file_name>system_log.txt</file_name>
       <append_log>false</append_log>
     </system_logger>     
   </logger_information>
 </source_storage>

Target storage XML section

The <target_storage> element is used to define the target storage section. The following XML elements are used in this section:

• <device> - container element for target storage device information (e.g. NAND or NOR).

attribute	mandatory	values	description
id	yes	string value	unique name of the device

• <device><config> - specifies the device specific configuration parameters.

attribute	mandatory	values	description
type	yes	"nand" - use NAND flash as target storage "nor" - use NOR flash as target storage	specifies the type of the target storage device
chipid	yes	numeric value	specifies the chip id of the device
blocksize	no	numeric value	specifies the block size of the device
sectorsize	no	numeric value	specifies the sector size of the device
length	no	numeric value	specifies the device length accessible for Updater Application

• <region> - container element for target storage region information (e.g. Boot, Os, Reserved)

attribute	values	description
id	yes	string value	unique name of the region

• <region><config> - specifies the device specific configuration parameters.

attribute	mandatory	values	description
type	yes	"boot" "os" "reserved"	specifies the type of the region
start	no	numeric value	specifies the absolute start position of the region in bytes from the beginning of the device
length	no	numeric value "sectorsize" - use the device sector size "blocksize" - use the device block size "auto" - calculate the length according to the source file info	specifies the region length. The actual region length can be affected with other attributes.
alignment	no	numeric value "blocksize" - use the device block size "sectorsize" - use the device sector size	specifies the alignment of the region
reserve	no	percentage value (e.g. "10%")	specifies the size of the extra space to reserve in percents of the specified length
replication	no	numeric value	specifies the number of copies of the effective length for the actual region length calculation. calculation is as follows: reserved space = replication * length

• <entity> - container element for logging information

attribute	values	description
id	yes	string value	unique name of the entity

• <entity><config> - specifies the entity specific configuration parameters

attribute	mandatory	values	description
type	yes	"raw" - raw byte access "partition" - partiton level access "partition table" - partition table information	specifies the type of the entity
offset	no	numeric value	specifies the relative offset in bytes from the start of the region
length	no	numeric value "sectorsize" - use the device sector size "blocksize" - use the device block size "auto" - calculate the length according to the source file info	specifies the entity length. The actual region length can be affected with other attributes.
alignment	no	numeric value "blocksize" - use the device block size "sectorsize" - use the device sector size	specifies the alignment of the entity
reserve	no	percentage value(e.g. "10%")	specifies the size of the extra space to reserve in percents of the specified length
replication	no	numeric value	specifies the number of copies of the effective length for the actual region length calculation. calculation is as follows: reserved space = replication * length

Each of the above container elements can include the following elements:

• <source> - specifies the file on the storage media that provides content for the device/region/entity. Used for both store and upload commands.

attribute	values	description
file	string	name of the file on the source storage
format	"raw" - indicates raw binary format (e.g. nb0) "bin" - indicates .bin format (e.g. NK.bin)	file format used by Updater Application to parse the content of the source file

General Target storage clarifications

• The order of the device/region/entity in the XML file is important
• Each device/region/entity starts where the last device/region/entity has ended

Target storage XML syntax example

Target storage syntax example is taken from CM-T3530 NAND layout definition:

<target_storage>
  <device id="nand1">
    <config type="nand" chipid="1" sectorsize="0x800" blocksize="0x20000"></config>
    <region id="boot_region">
      <config type="boot" start="0x0" alignment="blocksize"></config>
      <entity id="boot_content">
        <config type ="raw" offset="0x0000" length="blocksize" replication="6" alignment="blocksize"></config>
        <source file="CMT35-nand.raw" format="raw"></source>
      </entity>     
      <entity id="splashscreen">
        <config type ="raw" length="auto" alignment="blocksize"></config>
        <source file="splashscreen.bmp" format="raw"></source>
      </entity>     
    </region>
    <region id="os_region">
      <config type="os" alignment="blocksize"></config>
      <source file="os_region.nb0" format="raw"></source>
      <entity  id="os_partition_table">
        <config type="partition_table"></config>
      </entity>
      <entity id="partition_nk">
        <config type="partition" name="nk"  length="auto" reserve="10%" alignment="sectorsize"></config>
        <source file="nk.bin" format="bin"></source>
      </entity>
      <entity id="partition_system">
        <config type="partition" name="system" alignment="sectorsize"></config>        
      </entity>
    </region>
    <region id="reserve_region">
      <config type="reserve" length="blocksize" replication="10" alignment="blocksize"></config>
    </region>
  </device>
</target_storage>

Update flow actions XML section

The <actions element is used to define the update flow actions section. The following XML elements are used in this section:

• <action> - container element for the update flow action information (e.g. store, upload, ..).

attribute	mandatory	values	description
type	yes	"erase" "store" "upload" "create_partition" "format_partition" "update_parameter" "reserve" "reset"	specifies the type of the action to execute by Updater Application. When "reserve" action is used, it must be the first action to be performed on the target.
subtype	no	for store/upload action type: "raw" - raw byte access "processed" - raw byte access and low level meta inforamtion "filesystem" - file based access for update_parameter action type: "offset" - binary structure parameters (e.g. Eboot parameters) "keyvalue" - key value parameters (e.g. U-boot parameters)	specifies more information about the action. This allows to preoperly parse the action parameters

• <action><target> - container element for the target storage information

attribute	mandatory	values	description
id	yes	string value	unique name of the target storage layout part. Must be the same as the id attribute in the corresponding target storage entity/region/device section.

• <action><params> - container element for the action parameters

attribute	mandatory	values	description
oem_attribute	no	"readonly" "reserved" "reserved_readonly"	specifies the additional OEM attributes for the target storage access (used in FAL/FMD model)
part_type	yes, for create_partition action	"binfs" "dos3_fat" "dos4_fat" "binary" "bootsection" "dos32_fat"	specifies the partition type for create_partition action
part_active	no	"true" "false"	specifies the active partition request for create_partition action
part_readonly	no	"true" "false"	specifies the readonly partition request for create_partition action
format_tfat	no	"true" "false"	specifies the TFAT format option for format_partition action
format_exfat	no	"true" "false"	specifies the EXFAT format option for format_partition action
param_name	yes, for update_parameter action with keyvalue subtype	string value	specifies the name of the parameter for update_parameter action with keyvalue subtype
param_type	yes, for update_parameter action with offset subtype	"string" - string value "number" - numeric value "reserved" - parameter value obtained from the source information	specifies the type of the parameter for update_parameter action
param_value	yes, for update_parameter action	string value numeric value "image_start" - image start parsed from NK.bin "image_length" - image length parsed from NK.bin "kernel_start" - kernel section start parsed from NK.bin "kernel_length" - kernel section length parsed from NK.bin	specifies the value of the parameter for update_parameter action
image_entity	no	string value	specifies the target storage entity with NK.bin for extraction of reserved parameters (e.g. kernel_start) for update_parameter action
param_offset	yes, for update_parameter action with offset subtype	numeric value	specifies the offset of the parameter in binary parameters structure for update_parameter action with offset subtype
param_length	yes, for update_parameter action with offset subtype	numeric value	specifies the length of the parameter in binary parameters structure for update_parameter action with offset subtype

Update flow acitons summary

• erase - erase disk/region/entity of the target media
• store - store disk/region/entity content from the source media in to the target disk/region/entity (performs automatic erase if needed)
  • store raw - store in .dio/.nb0 format
  • store processed - store in .dio.postproc format with FAL meta information (to be developed)
  • store filesystem - store files from archive/cab (To be developed)
• upload - upload disk/region/entity to the source storage
  • upload raw - upload in .dio/.nb0 format
  • upload processed - upload in .dio.postproc format with FAL information (to be developed)
  • upload filesystem - upload snapshot files into archive/cab (to be developed)
• create_partition - add new partition to the partition table. If partition table doesn't exist it will be created automatically
• format_partition - format specific partition with certain file system
• update_parameter - apply incremental update to bootloader/bootstrap environment or parameters block
• reserve - reserve some target media blocks from the scope of the block device driver
• reset - perform reset to the system

Update flow actions XML syntax example

<actions>
  <action type="reserve">
    <target id="reserve_region"></target>
    <params oem_attribute="reserved_readonly"></params>
  </action>  
  <action type="store" subtype="raw">
    <target id="boot_content"></target>
    <params block_status="reserved" oem_attribute="reserved_readonly"></params>
  </action>
  <action type="store" subtype="raw">
    <target id="splashscreen"></target>
    <params block_status="reserved" oem_attribute="reserved_readonly"></params>
  </action>
  <action type="erase">
    <target id="os_region"></target>
  </action>  
  <action type="partition_create">
    <target id="partition_nk"></target>
    <params part_type="bootsection" active="false"></params>
  </action>
  <action type="partition_create">
    <target id="partition_system"></target>
    <params part_type="dos32_fat" active="false"></params>
  </action>
  <action type="store" subtype="raw">
    <target id="partition_nk"></target>
  </action>
</actions>