WinCE: Updater Framework

From Compulab Mediawiki
Revision as of 08:45, 19 July 2010 by Mike (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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.

Admolition note.png 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>

See Also

Retrieved from "https://mediawiki.compulab.com/w/index.php?title=WinCE:_Updater_Framework&oldid=1000"